feat(cli)!: unified load command; deprecate ingest as an alias

omnigraph load is now the single data-write command:
- works against remote graphs (POSTs the server's /ingest endpoint with the
  same bearer/actor resolution as other remote commands) — previously load
  was the only data command forced to open Lance storage directly
- --from <base> opts into fork-if-missing for --branch (the former ingest
  semantics); without --from a missing branch is an error, never a fork
- --mode is now required: overwrite is destructive, so there is no implicit
  default (the old silent default was overwrite)
- output gains base_branch/branch_created (and table sums on remote loads)

omnigraph ingest stays as a deprecated alias (defaults preserved: --from
main --mode merge) that prints a one-line warning to stderr, matching the
read/change deprecation convention; removal in a later release.

Docs updated in the same change: cli.md, cli-reference.md, policy.md,
audit.md, execution.md (unified load section), AGENTS.md quick-flow,
README.md.

BREAKING CHANGE: scripts running omnigraph load without --mode must now
pass it explicitly (previously defaulted to the destructive overwrite).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/dev/execution.md

@@ -168,12 +168,12 @@ Atomicity guarantee for multi-statement mutations: a mid-query failure leaves La
 
 For all three modes, a mid-load failure (RI / cardinality violation, validation error) leaves Lance HEAD untouched on the staged tables — the next load on the same tables proceeds normally with no `ExpectedVersionMismatch`.
 
-## `load` vs `ingest`
+## `load` and the deprecated `ingest` shims
 
-- `load(branch, data, mode)` — direct load to a branch (single publisher commit per call).
-- `ingest(branch, from, data, mode)` — branch-creating wrapper: if `branch` doesn't exist, fork it from `from` (default `main`) via `branch_create_from`, then call `load(branch, data, mode)`.
-- Returns `IngestResult { branch, base_branch, branch_created, mode, tables[] }`.
-- `ingest_as(actor_id)` records the actor on the resulting commit.
+- `load_as(branch, base, data, mode, actor)` — the unified entry (single publisher commit per call). `base: Some(b)` forks a missing `branch` from `b` first (via `branch_create_from_as`, which enforces `BranchCreate`); `base: None` requires the branch to exist — staging fails on an unknown branch, so a typo'd name can never create one.
+- `load(branch, data, mode)` — convenience wrapper with `base: None` and no actor.
+- Returns `LoadResult { branch, base_branch, branch_created, nodes_loaded, edges_loaded }`.
+- `ingest{,_as,_file,_file_as}` are `#[deprecated]` shims over `load_as` preserving the historical contract (`from: None` forks from `main`; returns `IngestResult`); they are slated for removal. The CLI `ingest` command is a deprecated alias of `load --from <base>`.
 
 ## Embeddings during load
 

docs/user/audit.md

@@ -1,7 +1,7 @@
 # Audit / Actor tracking
 
 - `Omnigraph::audit_actor_id: Option<String>` is the actor in effect.
-- `_as` variants of every write API let callers override the actor: `mutate_as`, `ingest_as`, `branch_merge_as`, `apply_schema_as`, etc.
+- `_as` variants of every write API let callers override the actor: `mutate_as`, `load_as`, `branch_merge_as`, `apply_schema_as`, etc.
 - Actor IDs are persisted on `GraphCommit.actor_id` with split storage in `_graph_commit_actors.lance` (the commit graph is split into `_graph_commits.lance` for the linkage and `_graph_commit_actors.lance` for the actor map).
 - HTTP server uses the bearer-token actor automatically; CLI uses the local user / explicit env (no implicit actor).
 - Pre-v0.4.0 graphs also stored actor IDs on `RunRecord.actor_id` in `_graph_runs.lance` / `_graph_run_actors.lance`. The Run state machine was removed in MR-771; those files are inert post-v0.4.0. The v2→v3 manifest migration sweeps any stale `__run__*` branches on first write-open (MR-770); the inert dataset bytes remain until a `delete_prefix` primitive lands.

docs/user/cli-reference.md

@@ -9,8 +9,8 @@ Top-level command families and subcommands. Graph-targeting commands accept eith
 | Command | Purpose |
 |---|---|
 | `init` | `--schema <pg>` → initialize a graph (also scaffolds `omnigraph.yaml` if missing) |
-| `load` | bulk load a branch (`--mode overwrite\|append\|merge`) |
-| `ingest` | branch-creating transactional load (`--from <base>`) |
+| `load` | bulk load a branch, local or remote (`--mode overwrite\|append\|merge` is **required** — overwrite is destructive, so there is no default). Without `--from` the target branch must exist; `--from <base>` forks a missing `--branch` from `<base>` first |
+| `ingest` | deprecated alias of `load --from <base>` (defaults: `--from main --mode merge`); prints a one-line warning to stderr |
 | `query` (alias: `read`) | run named read query; source via `--query <path>`, `-e`/`--query-string <GQ>`, or `--alias <name>` (exactly one). `read` is the deprecated previous name and prints a one-line warning to stderr |
 | `mutate` (alias: `change`) | run mutation query; same `--query` / `-e` / `--alias` mutual-exclusion as `query`. `change` is the deprecated previous name and prints a one-line warning to stderr |
 | `snapshot` | print current snapshot (per-table version + row count) |

docs/user/cli.md

@@ -42,7 +42,7 @@ omnigraph branch create --uri graph.omni --from main feature-x
 omnigraph branch list --uri graph.omni
 omnigraph branch merge --uri graph.omni feature-x --into main
 
-omnigraph ingest --data batch.jsonl --branch review/import-2026-04-09 graph.omni
+omnigraph load --data batch.jsonl --branch review/import-2026-04-09 --from main --mode merge graph.omni
 omnigraph export graph.omni --branch main --type Person > people.jsonl
 omnigraph commit list graph.omni --branch main --json
 omnigraph commit show --uri graph.omni <commit-id> --json

docs/user/policy.md

@@ -105,12 +105,13 @@ is validated/tested/explained as the anonymous policy.
 - `omnigraph policy validate` — parse + count actors, exit 1 on parse error.
 - `omnigraph policy test` — run cases in `policy.tests.yaml`, exit 1 on any expectation mismatch.
 - `omnigraph policy explain --actor … --action … [--branch …] [--target-branch …]` — show decision and matched rule.
-- `omnigraph --as <ACTOR> <subcommand>` — set the actor for the duration of one invocation. Effective for `change`, `load`, `ingest`, `branch create|delete|merge`, and `schema apply` against local URIs. No-op against remote HTTP URIs (actor is bearer-token-resolved server-side).
+- `omnigraph --as <ACTOR> <subcommand>` — set the actor for the duration of one invocation. Effective for `change`, `load` (and its deprecated `ingest` alias), `branch create|delete|merge`, and `schema apply` against local URIs. No-op against remote HTTP URIs (actor is bearer-token-resolved server-side).
 
 ## Enforcement
 
 Policy is a property of the **engine**, not the transport. Every mutating
-write — `mutate_as`, `load_as`, `ingest_as`, `apply_schema_as`,
+write — `mutate_as`, `load_as` (the deprecated `ingest_as` shims route
+through it), `apply_schema_as`,
 `branch_create_as`, `branch_create_from_as`, `branch_delete_as`,
 `branch_merge_as` — calls `Omnigraph::enforce(action, scope, actor)` at
 the head of the method. The gate fires identically whether the call