fix(cli): align lint plane label + document the plane model (RFC-010 follow-up) (#218)

Addresses the Greptile review on #217:

P1 — `lint` reported two different names. `command_label` returns `lint`, but
`execute_query_lint` passed `"query lint"` as the resolver operation string, so
`lint --server` said `lint` while `lint <https>` said `query lint`. Both were
pinned by tests. `query lint` is the *deprecated* alias (argv-rewritten to
`lint`), so the canonical name is `lint`: switch both user-facing strings in
`execute_query_lint` (the storage-plane bail label and the
requires-schema-or-target usage message) to `lint`, and update the two pinned
assertions in `cli_data.rs`.

P2 — user-doc debt (AGENTS.md rule 1: error text is observable behavior).
Document the plane model in `cli-reference.md` (new *Command planes* section:
data vs storage/maintenance vs control, which addressing flags apply, and the
declared wrong-plane / remote-target errors), and add an addressing note to
`maintenance.md` cross-referencing it.

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

crates/omnigraph-cli/src/helpers.rs

@@ -754,10 +754,10 @@ pub(crate) async fn execute_query_lint(
     let has_graph_target =
         cli_uri.is_some() || cli_target.is_some() || config.cli_graph_name().is_some();
     if !has_graph_target {
-        bail!("query lint requires --schema <schema.pg> or a resolvable graph target");
+        bail!("lint requires --schema <schema.pg> or a resolvable graph target");
     }
 
-    let uri = resolve_local_uri(config, cli_uri, cli_target, "query lint")?;
+    let uri = resolve_local_uri(config, cli_uri, cli_target, "lint")?;
     let db = Omnigraph::open(&uri).await?;
     Ok(lint_query_file(
         &db.catalog(),

crates/omnigraph-cli/tests/cli_data.rs

@@ -586,7 +586,7 @@ query list_people() {
     // RFC-010 Slice 1: the storage-plane verbs now share one declared message
     // (was: "query lint is only supported against local graph URIs …").
     assert!(
-        stderr.contains("`query lint` is a storage-plane command and needs direct storage access")
+        stderr.contains("`lint` is a storage-plane command and needs direct storage access")
             && stderr.contains("remote server"),
         "storage-plane remote-target message not found; got: {stderr}"
     );
@@ -615,7 +615,7 @@ query list_people() {
     );
     let stderr = String::from_utf8_lossy(&output.stderr);
     assert!(
-        stderr.contains("query lint requires --schema <schema.pg> or a resolvable graph target")
+        stderr.contains("lint requires --schema <schema.pg> or a resolvable graph target")
     );
 }
 

docs/user/cli-reference.md

@@ -28,6 +28,21 @@ Top-level command families and subcommands. Graph-targeting commands accept a po
 | `policy validate \| test \| explain` | Cedar tooling. Selects `cli.graph`, else `server.graph`, else top-level `policy.file` |
 | `version` / `-v` | print `omnigraph 0.3.x` |
 
+## Command planes
+
+Every command lives on one **plane**, which determines how it reaches a graph and which addressing flags apply (RFC-010):
+
+- **Data plane** — `query`, `mutate`, `load`, `ingest`, `branch *`, `snapshot`, `export`, `commit *`, `schema show`, `schema apply` (and `graphs list`, remote-only today). Run against a graph **embedded or via a server**: accept a positional `URI` / `--target` / `--server` (+ `--graph` for multi-graph servers).
+- **Storage / maintenance plane** — `init`, `optimize`, `repair`, `cleanup`, `schema plan`, `queries validate`, `lint`. Run with **direct storage access** (`file://` / `s3://`), never through a server. They accept a positional `URI` or `--target`, but **not** `--server` / `--graph`, and a `--target` that resolves to a remote (`http(s)://`) server is rejected. (`init` takes only a positional `URI` today — no `--target`.)
+- **Control plane** — `cluster *`. Operates on a cluster directory via `--config <dir>`.
+
+These restrictions are enforced and reported, not silent:
+
+- A data-plane addressing flag on a non-data verb fails loudly, e.g.: ``optimize is a storage-plane command; --server/--graph address the data plane and do not apply. Use --target <name> or a storage URI.``
+- A storage-plane verb pointed at a remote target fails loudly, e.g.: ``optimize is a storage-plane command and needs direct storage access; the resolved target is a remote server (https://…). Pass the graph's file:// or s3:// URI.``
+
+To maintain a server-backed graph, run the maintenance verbs from a host with storage access against the graph's storage URI (or `--target`), out-of-band from the serving process — there are no server routes for `optimize` / `repair` / `cleanup` by design.
+
 ## Config surfaces
 
 Two config surfaces with single owners (RFC-007/RFC-008), plus a zero-config

docs/user/maintenance.md

@@ -2,6 +2,8 @@
 
 `db/omnigraph/optimize.rs` and `db/omnigraph/repair.rs`.
 
+**Addressing (RFC-010).** `optimize`, `repair`, and `cleanup` are **storage-plane** CLI commands: they run with direct storage access against a positional `URI` or `--target`, never through a server, and reject `--server` / `--graph` or a `--target` that resolves to a remote (`http(s)://`) URL with a declared error. There are no server routes for them by design — to maintain a server-backed graph, run them out-of-band against the graph's storage URI. See the *Command planes* section of [cli-reference.md](cli-reference.md).
+
 ## `optimize_all_tables(db)` — non-destructive
 
 - Lance `compact_files()` on every node + edge table on `main`, then **publishes the compacted version to the `__manifest`** so the manifest's `table_version` tracks the compacted Lance HEAD. Reads pin the manifest version, so without this publish compaction would be invisible to readers *and* would break the HEAD-vs-manifest precondition of the next schema apply / strict update/delete ("stale view … refresh and retry"). The publish advances the graph version (a system-attributed commit) only for tables that actually compacted.