feat(cluster): add read-only validate and plan

docs/dev/testing.md

@@ -8,6 +8,7 @@ This file is the always-on map of the test surface. **Consult it before every ta
 |---|---|---|
 | `omnigraph` (engine) | `crates/omnigraph/tests/` | Integration tests (21 files), fixture-driven, share `tests/helpers/mod.rs` |
 | `omnigraph-cli` | `crates/omnigraph-cli/tests/` | `cli.rs` (unit-ish), `system_local.rs`, `system_remote.rs`, share `tests/support/mod.rs` |
+| `omnigraph-cluster` | mostly in-source `#[cfg(test)] mod tests` | Cluster config parser, local JSON state diff, read-only validate/plan |
 | `omnigraph-server` | `crates/omnigraph-server/tests/` | `server.rs` (HTTP-level), `openapi.rs` (OpenAPI drift / regeneration) |
 | `omnigraph-compiler` | mostly in-source `#[cfg(test)] mod tests` | Parser, type-checker, IR lowering, lint |
 

docs/user/cli-reference.md

@@ -2,7 +2,7 @@
 
 A reference for the `omnigraph` binary's command surface and `omnigraph.yaml` schema. For a quick-start guide, see [cli.md](cli.md).
 
-17 top-level command families, 40+ subcommands. All commands accept either a positional `URI`, `--uri`, or a `--target <name>` resolved against `omnigraph.yaml`.
+18 top-level command families, 40+ subcommands. Graph commands accept either a positional `URI`, `--uri`, or a `--target <name>` resolved against `omnigraph.yaml`; `cluster` commands instead use `--config <dir>`.
 
 ## Top-level commands
 
@@ -21,6 +21,7 @@ A reference for the `omnigraph` binary's command surface and `omnigraph.yaml` sc
 | `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` |
 | `queries validate \| list` | operate on the server-side stored-query registry (the `queries:` block). `validate` type-checks every stored query against the live schema offline (opens the selected graph; exits non-zero on any breakage), catching schema drift without restarting the server; `list` prints the selected registry's query names, MCP exposure, and typed params. For per-graph registries, pass `--target <graph>` or set `cli.graph`; with no graph selection, `list` shows only top-level `queries:`. Distinct from `lint`, which validates a single `.gq` file |
+| `cluster validate \| plan` | read-only cluster-control preview. `validate` checks a local `cluster.yaml` folder and referenced schema/query/policy files; `plan` diffs it against local JSON state at `__cluster/state.json`. No apply, lock, graph open, server change, or state write occurs in Stage 1 |
 | `optimize` | non-destructive Lance compaction (skips tables with `Blob` columns; `--json` reports a `skipped` field) |
 | `cleanup --keep N --older-than 7d --confirm` | destructive version GC |
 | `embed` | offline JSONL embedding pipeline |
@@ -73,6 +74,20 @@ policy:
   file: ./policy.yaml
 ```
 
+## Cluster config preview
+
+```bash
+omnigraph cluster validate --config ./company-brain
+omnigraph cluster plan     --config ./company-brain --json
+```
+
+`--config` is a directory containing `cluster.yaml`; it defaults to `.`.
+Stage 1 accepts graphs, schemas, stored queries, and policy bundle file
+references. `cluster plan` reads local JSON state from
+`<config-dir>/__cluster/state.json`; a missing file means empty state. External
+state backends, apply, locks, pipelines, UI specs, embeddings, aliases, and
+bindings are reserved for later stages. See [cluster-config.md](cluster-config.md).
+
 ## Output formats (`query` command, alias: `read`)
 
 - `json` — pretty-printed object with metadata + rows

docs/user/cluster-config.md

@@ -0,0 +1,95 @@
+# Cluster Config
+
+**Status:** Stage 1 read-only preview.
+
+Cluster config is the future control-plane configuration surface for a whole
+OmniGraph deployment. In this stage, OmniGraph can validate a local
+`cluster.yaml` folder and produce a deterministic read-only plan. It does not
+apply changes, acquire locks, open graph roots, start servers, or write state.
+
+## Commands
+
+```bash
+omnigraph cluster validate --config ./company-brain
+omnigraph cluster plan     --config ./company-brain --json
+```
+
+`--config` points at a directory, not a file. The directory must contain
+`cluster.yaml`. When omitted, it defaults to the current directory.
+
+## Supported `cluster.yaml`
+
+Stage 1 accepts only the read-only resource subset:
+
+```yaml
+version: 1
+metadata:
+  name: company-brain
+
+state:
+  backend: cluster
+  lock: true
+
+graphs:
+  knowledge:
+    schema: ./knowledge.pg
+    queries:
+      find_experts:
+        file: ./knowledge.gq
+
+policies:
+  base:
+    file: ./base.policy.yaml
+    applies_to: [knowledge]
+```
+
+`metadata.name` is a display label. `state.lock` is parsed for forward
+compatibility, but no lock is acquired in this read-only stage. `state.backend`
+may be omitted or set to `cluster`; external state backends are reserved for a
+later stage.
+
+## Validation
+
+`cluster validate` checks:
+
+- `cluster.yaml` syntax and supported fields
+- duplicate YAML keys
+- schema, query, and policy file existence
+- schema parsing and catalog construction
+- stored-query parsing and query-name matching
+- stored-query type-checking against the desired schema
+- policy `applies_to` graph references
+
+Fields reserved for later phases, such as `pipelines`, `embeddings`, `ui`,
+`aliases`, and `bindings`, fail with a typed diagnostic instead of being
+silently ignored.
+
+## Planning
+
+`cluster plan` first performs validation, then reads local JSON state from:
+
+```text
+<config-dir>/__cluster/state.json
+```
+
+If the file is missing, the state is treated as empty and every desired
+resource is planned as a create. If present, the file must use this shape:
+
+```json
+{
+  "version": 1,
+  "applied_revision": {
+    "config_digest": "...",
+    "resources": {
+      "graph.knowledge": { "digest": "..." },
+      "schema.knowledge": { "digest": "..." },
+      "query.knowledge.find_experts": { "digest": "..." },
+      "policy.base": { "digest": "..." }
+    }
+  }
+}
+```
+
+Plan output compares desired resource digests against state resource digests
+and reports `create`, `update`, and `delete` changes. The command never writes
+`state.json`; apply and locking are later-stage work.

docs/user/index.md

@@ -13,6 +13,7 @@ of MRs, internal recovery mechanics, or contributor-only invariants.
 | Install OmniGraph | [install.md](install.md) |
 | Run the CLI locally | [cli.md](cli.md) |
 | Look up every CLI flag and config field | [cli-reference.md](cli-reference.md) |
+| Validate and plan cluster config | [cluster-config.md](cluster-config.md) |
 | Write schemas | [schema-language.md](schema-language.md) |
 | Read schema-lint diagnostic codes | [schema-lint.md](schema-lint.md) |
 | Write queries and mutations | [query-language.md](query-language.md) |