docs(readme): align with cluster-first paradigm + RFC-011 CLI ergonomics (#262)

* docs(readme): align with the cluster-first paradigm + RFC-011 CLI ergonomics

The README's command examples and crate list predated 0.7.0. Update them:

- Common Commands: capability/addressing model — positional/`--store` for direct
  storage, `--server` for served graphs (no positional `http(s)://`), `query`/
  `mutate` invoke a stored query by name (positional is the query name), `load`
  requires `--mode`. Drop the false "same URI works for local/s3/http" claim and
  the deprecated `read`/`change` + `--name` forms; mention `~/.omnigraph/config.yaml`.
- New "Serving (cluster-first)" section: a deployment is a cluster.yaml converged
  with `cluster apply` and served by `omnigraph-server --cluster <dir|s3://…>`
  (no single-graph mode; config-free boot from a bucket).
- Fix the stale docs link (`docs/user/cli.md` → `cli/index.md` + the CLI reference)
  after the docs were restructured into topic sections.
- Workspace Crates: list all seven (add omnigraph-policy, omnigraph-api-types,
  omnigraph-cluster) with cluster-first framing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(agents): fix the stale `read --name` quick-reference example

AGENTS.md (always-loaded; symlinked to CLAUDE.md) still showed the deprecated
`omnigraph read --query … --name … <s3-uri>` form. Update it to the RFC-011
shape: `omnigraph query --query … <name> … --store <uri>` (read→query, --name→
positional query name, positional URI→--store). Addresses the bot-review finding
on #262.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

AGENTS.md

@@ -210,9 +210,9 @@ omnigraph load --data ./seed.jsonl --mode overwrite s3://my-bucket/graph.omni
 # Load a review batch onto its own branch (--from forks it if missing)
 omnigraph load --branch review/2026-04-25 --from main --mode merge --data ./batch.jsonl s3://my-bucket/graph.omni
 
-# Run a hybrid (vector + BM25) query
-omnigraph read --query ./queries.gq --name find_similar \
-  --params '{"q":"trends in AI safety"}' --format table s3://my-bucket/graph.omni
+# Run a hybrid (vector + BM25) query — ad-hoc .gq against a store (positional = query name)
+omnigraph query --query ./queries.gq find_similar \
+  --params '{"q":"trends in AI safety"}' --format table --store s3://my-bucket/graph.omni
 
 # Plan + apply schema migration
 omnigraph schema plan  --schema ./next.pg s3://my-bucket/graph.omni

README.md

@@ -78,18 +78,51 @@ value.
 
 ## Common Commands
 
-The same URI works for local paths, `s3://…`, or `http://host:port`.
+Every command declares the **capability** it needs and how it's addressed.
+Direct storage (`init`, `load`, `branch`, …) takes a positional `file://`/`s3://`
+URI or `--store <uri>`; a served graph is addressed with `--server <name|url>`
+(never a positional `http(s)://` URI). `query`/`mutate` invoke a stored query
+**by name** (the positional is the query name, not a graph URI).
 
 ```bash
-omnigraph init   --schema ./schema.pg ./graph.omni
-omnigraph load   --data   ./data.jsonl ./graph.omni
-omnigraph read   --query  ./queries.gq --name get_person --params '{"name":"Alice"}' ./graph.omni
-omnigraph change --query  ./queries.gq --name insert_person --params '{"name":"Mina"}' ./graph.omni
-omnigraph branch create --from main feature-x ./graph.omni
-omnigraph branch merge  feature-x --into main ./graph.omni
+# Create a graph and load data (--mode is required; overwrite is destructive)
+omnigraph init --schema ./schema.pg ./graph.omni
+omnigraph load --data ./data.jsonl --mode merge --store ./graph.omni
+
+# Read / write — ad-hoc .gq against a local store (positional selects the query)
+omnigraph query  --query ./queries.gq get_person    --params '{"name":"Alice"}' --store ./graph.omni
+omnigraph mutate --query ./queries.gq insert_person  --params '{"name":"Mina"}'  --store ./graph.omni
+
+# Branch and merge (Git-style, across the whole graph)
+omnigraph branch create --from main feature-x --store ./graph.omni
+omnigraph branch merge  feature-x --into main --store ./graph.omni
+
+# Against a running server: invoke a stored query by name from the catalog
+omnigraph query find_people --server prod --graph knowledge --params '{"q":"AI safety"}'
 ```
 
-See [docs/user/cli.md](docs/user/cli.md) for schema apply, snapshots, data loading, commits, and policy commands.
+Operator settings (identity, named servers/clusters, credentials, defaults) live
+in `~/.omnigraph/config.yaml`; with a default scope set, the addressing flags can
+be omitted. See [docs/user/cli/index.md](docs/user/cli/index.md) and the
+[CLI reference](docs/user/cli/reference.md) for schema apply, snapshots, commits,
+profiles, and policy/queries tooling.
+
+## Serving (cluster-first)
+
+A deployment is a **cluster**: a `cluster.yaml` (graphs, schemas, stored queries,
+policies, storage) that you converge with `cluster apply`, then serve. The server
+boots from the cluster only — it has no single-graph mode — and serves every
+graph under `/graphs/{id}/…`.
+
+```bash
+omnigraph cluster apply  --config ./company-brain          # converge the declared state
+omnigraph-server --cluster ./company-brain --bind 0.0.0.0:8080
+# or config-free from object storage — the bucket IS the deployment:
+omnigraph-server --cluster s3://my-bucket/company-brain --bind 0.0.0.0:8080
+```
+
+See the [cluster guide](docs/user/clusters/index.md) and
+[deployment guide](docs/user/deployment.md).
 
 ## Clients
 
@@ -131,10 +164,13 @@ Notes:
 
 ## Workspace Crates
 
-- `crates/omnigraph-compiler`: shared schema/query parser, typechecker, catalog, and IR lowering
-- `crates/omnigraph`: storage/runtime, branching, merge, change detection, and query execution
-- `crates/omnigraph-cli`: CLI for graph lifecycle (init/load), query/mutate, branch/commit/merge, schema/lint, snapshot/export, policy, and maintenance (optimize/cleanup)
-- `crates/omnigraph-server`: Axum HTTP server for remote reads, changes, ingest, export, branches, and commits
+- `crates/omnigraph-compiler`: shared schema/query parser, typechecker, catalog, and IR lowering (zero Lance dependency)
+- `crates/omnigraph` (package `omnigraph-engine`): storage/runtime, branching, merge, change detection, query execution, and embeddings
+- `crates/omnigraph-policy`: Cedar policy compilation and enforcement
+- `crates/omnigraph-api-types`: shared HTTP wire DTOs used by both the server and the CLI
+- `crates/omnigraph-cluster`: cluster config validation, planning, and apply (the control plane)
+- `crates/omnigraph-server`: Axum HTTP server — cluster-first, serving N graphs under `/graphs/{id}/…`
+- `crates/omnigraph-cli`: CLI for graph lifecycle (init/load), query/mutate, branch/commit/merge, schema/lint, snapshot/export, cluster control, policy/queries, profiles, and maintenance (optimize/repair/cleanup)
 
 ## Contributing