diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md index 6d864cc..ecb44b5 100644 --- a/docs/user/cli-reference.md +++ b/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 --as `; what apply converges is what an `omnigraph-server --cluster ` 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 ` 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 --as ` (`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 ` 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 ` 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 | diff --git a/docs/user/cluster-config.md b/docs/user/cluster-config.md index 5847d8e..081bfa2 100644 --- a/docs/user/cluster-config.md +++ b/docs/user/cluster-config.md @@ -36,15 +36,26 @@ omnigraph cluster force-unlock --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..uri` at a cluster's derived root + (`./company-brain/graphs/knowledge.omni`) so data-plane commands can use + `--target ` — an ordinary local path, no special handling. ## Supported `cluster.yaml` diff --git a/docs/user/cluster.md b/docs/user/cluster.md index 6241378..dcc4b2b 100644 --- a/docs/user/cluster.md +++ b/docs/user/cluster.md @@ -109,8 +109,10 @@ omnigraph cluster apply --config ./company-brain --as andrew ``` `--as ` 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: }` 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..uri` at a derived root like + `./company-brain/graphs/knowledge.omni` to use `--target ` 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)