docs(cluster): the precise omnigraph.yaml contract

The 'Relationship to omnigraph.yaml' section becomes the exact rule set:
cluster commands read the per-operator config for exactly one thing (the
cli.actor default when --as is omitted), a --cluster server reads it for
nothing, and pointing data-plane targets at derived roots is ergonomics,
not coupling. Operator guide and CLI reference updated to match.

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

docs/user/cli-reference.md

@@ -19,7 +19,7 @@ Top-level command families and subcommands. Graph-targeting commands accept eith
 | `commit list \| show` | inspect commit graph |
 | `schema plan \| apply \| show (alias: get)` | migrations |
 | `lint` (alias: `check`) | offline / graph-backed query validation. Replaces `query lint` / `query check`, which are kept as deprecated argv-level shims that print a one-line warning and rewrite to `omnigraph lint` |
-| `cluster validate \| plan \| apply \| approve \| status \| refresh \| import \| force-unlock` | declarative cluster control plane. `validate` checks a local `cluster.yaml` folder and referenced schema/query/policy files; `plan` diffs it against local JSON state at `__cluster/state.json`, annotates dispositions, and embeds real schema-migration previews; `apply` converges the cluster — stored-query/policy catalog writes (content-addressed under `__cluster/resources/`), graph creates, schema updates (soft drops only; `--as` records the actor), and graph deletes behind a digest-bound approval from `cluster approve <resource> --as <actor>`; what apply converges is what an `omnigraph-server --cluster <dir>` deployment serves on its next restart (omnigraph.yaml deployments are unaffected); `status` reads the state ledger; `refresh`/`import` explicitly update local JSON state from read-only graph observations; `force-unlock <LOCK_ID>` manually removes a held local state lock by exact id |
+| `cluster validate \| plan \| apply \| approve \| status \| refresh \| import \| force-unlock` | declarative cluster control plane. `validate` checks a local `cluster.yaml` folder and referenced schema/query/policy files; `plan` diffs it against local JSON state at `__cluster/state.json`, annotates dispositions, and embeds real schema-migration previews; `apply` converges the cluster — stored-query/policy catalog writes (content-addressed under `__cluster/resources/`), graph creates, schema updates (soft drops only; `--as` records the actor), and graph deletes behind a digest-bound approval from `cluster approve <resource> --as <actor>` (`apply`/`approve` default the actor from the per-operator `omnigraph.yaml`'s `cli.actor` when `--as` is omitted; nothing else in that file affects cluster commands); what apply converges is what an `omnigraph-server --cluster <dir>` deployment serves on its next restart (omnigraph.yaml deployments are unaffected); `status` reads the state ledger; `refresh`/`import` explicitly update local JSON state from read-only graph observations; `force-unlock <LOCK_ID>` manually removes a held local state lock by exact id |
 | `optimize` | non-destructive Lance compaction (skips tables with `Blob` columns or uncovered drift; `--json` reports `skipped`) |
 | `repair [--confirm] [--force]` | preview or explicitly publish uncovered manifest/head drift. `--confirm` heals verified maintenance drift and exits non-zero if suspicious/unverifiable drift is refused; `--force --confirm` publishes suspicious/unverifiable drift after operator review |
 | `cleanup --keep N --older-than 7d --confirm` | destructive version GC |

docs/user/cluster-config.md

@@ -36,15 +36,26 @@ omnigraph cluster force-unlock <LOCK_ID> --config ./company-brain --json
 ## Relationship to `omnigraph.yaml`
 
 `cluster.yaml` does not replace `omnigraph.yaml`, and the two never describe
-the same fact. `omnigraph.yaml` remains how the CLI and server are configured
-today (graph targets, server bind, CLI defaults, credential env references) and
-is its long-term home for per-operator settings. `cluster.yaml` is the shared
-desired state of a whole deployment, read only by the `cluster` commands via
-`--config`. In the current stage, nothing recorded in the cluster state ledger
-affects what a server serves or what other CLI commands target — the cluster
-catalog is inspectable, not live. When server boot from cluster state ships in
-a later stage, it will be an explicit per-deployment mode switch, not a merge
-of the two files.
+the same fact. `omnigraph.yaml` is the permanent **per-operator** layer (CLI
+defaults, the operator's identity and credential references, graph targets
+for data-plane commands); `cluster.yaml` is the shared desired state of a
+whole deployment, read only by the `cluster` commands via `--config`.
+
+The exact contract:
+
+- **Cluster commands read `omnigraph.yaml` for exactly one thing**: the
+  `cli.actor` default used by `apply`/`approve` when `--as` is omitted —
+  operator identity is a per-operator fact. With `--as` present, no config
+  is read at all. Nothing else (its graph set, targets, bind, queries,
+  policies) ever influences a cluster command; a malformed `omnigraph.yaml`
+  breaks only the no-flag actor lookup, loudly.
+- **A `--cluster` server reads `omnigraph.yaml` for nothing** — not even the
+  implicit current-directory search runs (mode-inference rule 0). Boot from
+  cluster state XOR `omnigraph.yaml`, never a merge.
+- **The other direction is ergonomics, not coupling**: a per-operator
+  `omnigraph.yaml` may point `graphs.<name>.uri` at a cluster's derived root
+  (`./company-brain/graphs/knowledge.omni`) so data-plane commands can use
+  `--target <name>` — an ordinary local path, no special handling.
 
 ## Supported `cluster.yaml`
 

docs/user/cluster.md

@@ -109,8 +109,10 @@ omnigraph cluster apply --config ./company-brain --as andrew
 ```
 
 `--as <actor>` attributes the run: it is recorded in recovery sidecars and
-audit entries and threaded into the engine's commit history. Make it a habit
-on every apply (it is required for `approve`).
+audit entries and threaded into the engine's commit history. Set
+`cli: { actor: <you> }` in your per-operator `omnigraph.yaml` to make it the
+default when `--as` is omitted (the flag always wins; `approve` requires one
+of the two).
 
 What each change kind does:
 
@@ -234,9 +236,12 @@ with an in-flight apply.
 - **CI-driven convergence**: `validate` and `plan --json` are read-only and
   safe in pipelines; gate `apply --as ci` on plan review. Approvals are the
   human step by design — keep `cluster approve` out of automation.
-- **`omnigraph.yaml` still has a job**: per-operator settings (CLI defaults,
-  credentials, active context). It just no longer describes the deployment —
-  a server boots from one source or the other, never a merge of both.
+- **`omnigraph.yaml` still has a job**: per-operator settings — your
+  `cli.actor` default for `--as`, CLI defaults, credentials, and data-plane
+  ergonomics (point `graphs.<name>.uri` at a derived root like
+  `./company-brain/graphs/knowledge.omni` to use `--target <name>` for
+  loads). It just no longer describes the deployment — a server boots from
+  one source or the other, never a merge of both.
 
 ## What the control plane does not do (yet)