docs(rfc): RFC-010 — restructure the CLI around explicit planes

[aaltshuler]

Proposes making the CLI's three planes — data, storage/maintenance, control — explicit and coherent. Docs-only; separate from the Phase 3c code PR (#213).

Problem

The CLI forces you to name a graph differently per plane (query it as --server prod --graph knowledge, maintain it as s3://bucket/knowledge.omni), and plane restrictions (graphs list server-only, optimize storage-only) are accidental — you find them by hitting a cryptic error.

Proposal (CLI-internal only — no engine/server/wire change)

1. One graph-addressing model across every verb — --target works for query and optimize.
2. Declared, per-subcommand capability surface (expands RFC-009 Phase 4) — honest "this is storage-plane, --server doesn't apply" errors from one table.
3. Plane-grouped --help.
4. Maintenance stays off the wire — deliberately, stated as a decision (no HTTP routes for optimize/cleanup/repair).

Includes a Target CLI ergonomics section with concrete before/after examples.

Review thread folded in

Keeps the Codex review verbatim with per-point Resolution notes:

• Sharpened resolver authority rule (operator/legacy --target must be direct storage; cluster-managed graphs via explicit --cluster --graph — no silent precedence between operator config and cluster.yaml).
• Per-subcommand capability table (schema plan vs show/apply; queries validate vs list; session/tooling commands classified).
• graphs list aligned to RFC-009's both-later target (not superseded).
• init promoted to an explicit cluster apply signpost for cluster-managed roots.
• Test plan extending existing CLI suites + pinning new wrong-plane error strings (Hyrum).

Linked from docs/dev/index.md.

🤖 Generated with Claude Code

Greptile Summary

This docs-only PR adds RFC-010 (docs/dev/rfc-010-cli-planes-restructure.md), a proposal to make OmniGraph's three CLI planes (data, storage/maintenance, control) explicit through a unified --target addressing model, a per-subcommand capability table, and plane-grouped --help. A one-line update to docs/dev/index.md registers the new RFC in the working-documents table.

• The RFC resolves all four points from its embedded review pass (resolver authority rule, graphs list RFC-009 alignment, per-subcommand capability table, init signpost to cluster apply) and adds a concrete test plan pinning new wrong-plane error strings.
• The RFC uses omnigraph query throughout (current-state table, examples, help block), but AGENTS.md (v0.7.0 baseline) consistently uses omnigraph read; if read is the actual verb, this mismatch propagates into the companion implementation PR (refactor(cli): collapse export + graphs-list onto GraphClient (RFC-009 Phase 3c) #213).
• The grouped --help example places graphs list in "INSPECT / SESSION" while the capability table classifies it as data-plane (remote today), creating an internal inconsistency within the RFC.

Confidence Score: 4/5

Safe to merge as a docs-only RFC — no code, no wire changes, no migration. The verb naming question should be resolved before the companion implementation PR (#213) begins.

The RFC is well-reasoned and internally consistent on its main design decisions, but it systematically uses query as the top-level query verb while the live codebase reference (AGENTS.md) shows read. If the verb is actually read, every example and the plane classification table in this RFC will mislead the implementation PR.

docs/dev/rfc-010-cli-planes-restructure.md — verb name consistency and graphs list help-group placement.

Important Files Changed

Filename	Overview
docs/dev/rfc-010-cli-planes-restructure.md	New 381-line RFC proposing three-plane CLI restructure. Well-structured with good internal cross-references to RFC-009, but contains a systematic query/read verb name mismatch with AGENTS.md, a within-document inconsistency in where graphs list is grouped, and an unusual embedded AI review transcript that duplicates already-incorporated resolutions.
docs/dev/index.md	One-line addition registering RFC-010 in the working documents table with a correct relative link and accurate summary description.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["graph-addressing input\n(positional URI | --target | --graph | --server)"] --> B{Resolver}
    B --> C{Command plane?}
    C -->|Data plane\nquery/mutate/load/branch…| D{Target type}
    D -->|file:// or s3://| E[EmbeddedClient\n→ engine directly]
    D -->|http/https or named server| F[RemoteClient\n→ HTTP GraphClient]
    D -->|--target alias| G{Config lookup}
    G -->|resolves to storage URI| E
    G -->|resolves to server URL| F
    C -->|Storage / maintenance plane\noptimize/repair/cleanup/init…| H{Target type}
    H -->|file:// or s3://| I[Embedded engine\non storage directly]
    H -->|http/https → FAIL| J["error: storage-plane command\nneeds direct storage access"]
    H -->|--target alias| K{Config lookup}
    K -->|resolves to storage URI| I
    K -->|resolves to remote URL| J
    H -->|--cluster dir --graph id| L[Resolve URI\nfrom cluster state]
    L --> I
    C -->|Control plane\ncluster validate/plan/apply…| M["--config dir\n→ cluster directory"]
    style J fill:#f88,stroke:#c00
    style E fill:#8f8,stroke:#080
    style F fill:#8f8,stroke:#080
    style I fill:#8f8,stroke:#080
    style M fill:#88f,stroke:#008

Loading

_{Reviews (1): Last reviewed commit: "docs(rfc): RFC-010 — restructure the CLI..." | Re-trigger Greptile}

Greptile also left 3 inline comments on this PR.

[greptile-apps]

aaltshuler has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[greptile-apps]

query vs read — command name inconsistency with live codebase

AGENTS.md (Version surveyed: 0.7.0, the canonical current state) shows the query verb as omnigraph read (omnigraph read --query ./queries.gq), but this RFC uses query throughout — in the current-state plane table, all Target CLI ergonomics examples (omnigraph query --target knowledge --query q.gq), and the grouped --help block. If the actual top-level verb is read, this inconsistency will silently misdirect the implementation PR (#213) when authors pick the verb name to refactor around. Either confirm that query is already the correct verb name (perhaps introduced alongside RFC-009 Phase 3c), or align the RFC examples with read. If a rename is part of this proposal, it should be stated explicitly as a change rather than assumed.

[greptile-apps]

graphs list plane classification conflicts between help block and capability table

The --help grouping example places graphs list under "INSPECT / SESSION" alongside queries list, login, logout, and other config/session commands. The capability table directly below classifies it as data-plane (Data (remote) ✅, with embedded-cluster coming later per RFC-009). These two representations within the same RFC contradict each other: the help block implies it's session-scoped tooling, while the table correctly reflects it as a data-plane command that requires a multi-graph server today. The help block should move graphs list into the DATA PLANE group (perhaps with a parenthetical noting the embedded-cluster future state), or the RFC needs prose explaining why it's grouped differently from its capability classification.

[greptile-apps]

Review transcript embedded in the RFC body is non-standard for this project

RFC-009 (the document this RFC builds on) has no embedded review section — proposals end after "Open questions." Keeping the Codex review verbatim as a permanent ## Review comments (Codex, 2026-06-13) section means future readers navigating docs/dev/ will encounter what reads as a design review transcript as part of the canonical proposal. Since all four resolutions have already been incorporated into the body ("Proposed shape", "Compatibility", "Test plan", "Relationship to RFC-009"), the review section is now entirely redundant with the proposal text. Consider either removing the section (the incorporated resolutions stand on their own) or collapsing it to a single-sentence acknowledgment that the Codex review pass was incorporated.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!