docs(rfc): RFC-011 — CLI refactoring (one addressing & config model)

[aaltshuler]

What

Adds RFC-011 (docs/dev/rfc-011-cli-refactoring.md, Status: Proposed) — the
maintainer-internal design for the CLI once omnigraph.yaml is removed. Docs-only.

The model

• One ontology — store / server / cluster; cluster config vs operator config;
  catalog; context; capability — each term naming exactly one concept.
• Addressing = scope + --graph, access path derived. A command resolves a
  scope (operator defaults, a --context, or one explicit --store/--server/
  --cluster), --graph selects within it, and served-vs-direct falls out of the
  scope × the verb's capability (any/served/direct/control/local) —
  never a per-command toggle, never inferred from a URI scheme.
• Served is the front door; direct storage is privileged. Everyday scope is a
  server (bearer token, no bucket creds); direct remote access is an explicit,
  credentialed, admin/break-glass act.
• Stateless per command (no current_context); definitions named, payloads
  passed (query <name>, not --query file.gq).

Contents

Ontology · first principles · scope/capability model · resolution rule · config
shape · command shape · before/after · migration · invariants check · Decisions
(Q1–Q4, Q6, Q7, Q9–Q11 resolved; Q5, Q8 deferred) · full end-state taxonomy +
a current-state appendix.

Completes the config/CLI lineage: RFC-007 → RFC-008 → RFC-009 → RFC-010.

Scope

RFC only — no code. The standalone current-state map (cli-taxonomy.md) and the
implementation are separate follow-ups; the maintenance-as-server-jobs mechanism
(Decision 11) is its own future RFC.

Verification

scripts/check-agents-md.sh green; all RFC links resolve.

🤖 Generated with Claude Code

Greptile Summary

Adds RFC-011, the design document for the post-omnigraph.yaml CLI refactoring: a unified addressing model (scope + --graph + derived access path), a five-capability classifier (any/served/direct/control/local), stateless-per-command resolution, and a named-definitions-over-file-payloads convention. The docs/dev/index.md entry is the only other change.

• New RFC (754 lines): covers ontology, first principles, scope/capability model, resolution rule, config shape, command shape, before/after, migration, invariants check, resolved decisions (Q1–Q4, Q6, Q7, Q9–Q11), deferred decisions (Q5, Q8), and full end-state + current-state taxonomies.
• Two internal consistency issues found: the "four orthogonal questions" claim in §Design conflicts with the five-row table directly below it; and the migration section covers --target/--cluster-graph/--uri http://… but omits a staged-removal note for the positional <URI> / --uri s3://… form used by storage-native commands (init, optimize, repair, cleanup, schema plan) — these forms appear in the AGENTS.md quick-reference and will break without guidance.

Confidence Score: 5/5

Docs-only RFC addition with no code or config changes; safe to merge.

The change is two documentation files — a new RFC and a one-line index entry — with no executable code, no schema, and no API surface touched. The two findings are documentation inconsistencies within the RFC itself, not defects that would break anything today.

docs/dev/rfc-011-cli-refactoring.md — the "four orthogonal questions" vs five-row table and the missing positional storage URI migration note are both worth fixing before the implementation PR lands.

Important Files Changed

Filename	Overview
docs/dev/index.md	Single-row addition to the RFCs table registering RFC-011 with its description and link. Link target exists in the PR; no issues.
docs/dev/rfc-011-cli-refactoring.md	New 754-line RFC. Two internal consistency issues: "four orthogonal questions" in the prose but five axes in the adjacent table, and no staged-removal migration note for the positional storage URI form used by storage-native commands.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([Command invoked]) --> B{Verb capability = local?}
    B -- Yes --> Z[Reject scope/graph flags · run locally]
    B -- No --> C{Primitive flag supplied?\n--store / --server / --cluster}
    C -- Yes --> D[Use primitive as scope\nbypass operator-config defaults]
    C -- No --> E{--context or\nOMNIGRAPH_CONTEXT set?}
    E -- Yes --> F[Load named context as scope]
    E -- No --> G[Use operator-config flat defaults]
    D & F & G --> H{Verb is graph-scoped?}
    H -- Yes --> I{Scope is a store?}
    I -- Yes --> J[Store IS one graph\nreject --graph]
    I -- No --> K{default_graph or\n--graph provided?}
    K -- Yes --> L[Graph resolved]
    K -- No, 1 graph --> L
    K -- No, many graphs --> M[Error: list candidates\nnever auto-pick]
    H -- No, scope-scoped --> N[No graph selection]
    J & L & N --> O{Derive access path\nfrom scope x capability}
    O -- server scope + any/served --> P[Served path\nbearer token · Cedar policy]
    O -- cluster scope + direct/control --> Q[Direct privileged path\nbucket creds · Cedar policy]
    O -- store scope + any/direct --> R[Direct ad-hoc\nbucket creds if s3]
    O -- mismatch --> S[Error: name the required scope explicitly]

Loading

_{Reviews (2): Last reviewed commit: "docs(rfc): RFC-011 — address Greptile re..." | Re-trigger Greptile}