Fix graphs list enumeration via a served-registry scope path

[ragnorc]

What & why

omnigraph graphs list --server <name> was broken against any populated multi-graph server: the RFC-011 D7 require-graph guard ran inside the shared GraphClient::resolve() preamble and bailed with "pass --graph" before list_graphs() could run — the enumeration command only "enumerated" via its error text, which also broke --json consumers. Both remedies the error suggested made it worse: --graph/default_graph corrupted the URL to /graphs/<id>/graphs (404), and the command's own --uri option was dead (rejected at runtime despite its help text).

This fixes the class, not the instance: graphs list now resolves through a served-registry path (GraphClient::resolve_registry, synchronous by construction, so the async D7 probe structurally cannot run on it and no /graphs/<id> is ever appended); a declarative ScopeFlag × Capability matrix in guard_addressing rejects nonsense flags loudly (graphs list --graph/--store/--as, optimize --as, queries --store, …) instead of silently dropping them or failing late; and the verb's declared capability is threaded into GraphClient resolution, replacing the hardcoded Capability::Any. The dead --uri option is removed.

Backing issue / RFC

• Fixes an accepted issue: Closes #
• Implements / is an accepted RFC
• Trivial fast-lane — no issue/RFC required

None of the above: maintainer-internal process (bug reported and dispositioned in-session). The change preserves accepted RFC-011 behavior — Decision 7's candidate-listing error still fires on data verbs (pinned by system_remote.rs step 4), and Decision 2/9 addressing semantics are unchanged; graphs list is exempted because it is the enumeration D7 performs.

Checklist

• Change is focused (one logical change: served-registry scope resolution, in six single-purpose commits)
• Tests added/updated for behavior changes — two red→green pairs (each red commit lands immediately before its fix commit and was confirmed failing with the predicted symptom, including the /graphs/<id>/graphs URL corruption captured verbatim), a ScopeFlag × Capability matrix unit test, scope/client unit tests, and the previously-red #[ignore]d e2e graphs_list_against_multi_graph_server now passes
• Public docs updated — docs/user/cli/reference.md (new graphs list command-table row, served/direct capability bullets, loud-rejection classes, D7 exemption note) and the CLI after_help legend
• Reviewed against invariants — no Hard Invariant touched; closes the deny-list "silently dropped flag / failed later with an unrelated message" pattern the guard was built to prevent; every pre-existing pinned error text (guard clauses, remediation tails, alias message, D7 probe text, scope bails) is byte-identical

Notes for reviewers

• Reading order = commit order. Repo rule 12 pairs are visible in history: test(cli): pin scope-flag applicability matrix (red) → fix(cli): declarative ScopeFlag × Capability addressing guard, and test(cli): pin graphs-list served-registry resolution (red) → fix(cli): graphs list resolves through the served registry path. The bracketing refactors (registry_client extraction; capability threading) are behavior-neutral.
• Deliberate tightenings (previously silently ignored or failing late, now loud at the guard): --as on served/direct/local verbs, --store on served/control/local verbs. --as/--store remain consumed on data-plane (any) verbs — the parity harness and direct-write actor attribution depend on that. The served-write --as rejection keeps its own downstream message.
• default_graph is deliberately ignored on the registry path (an explicit --graph is rejected, a config default is skipped): rejecting the default would make graphs list unusable in any profile that sets one. Commented at resolve_registry.
• Verification: all nine CLI suites green (parity matrix 12/12, system_local 27/27, 65 bin unit tests), compiler (279) and api-types suites green, docs cross-link check green, plus a live smoke against a policy-enabled cluster server (enumeration, --json on stdout, fast guard rejections, D7 intact on query). The engine/cluster/server crates are byte-untouched by this diff; their suites hit the session's disk allowance locally, so CI is the canonical gate for them.
• The e2e that pins the fixed behavior remains #[ignore]d (loopback-dependent); the non-socket owners are the guard matrix unit test and the synchronous resolve_registry unit test, which run every PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_017fAXpLbhodrJMydMytJZEB

---

Generated by Claude Code

---

Note

Medium Risk
CLI addressing and scope resolution changed across many verbs; behavior is heavily tested but wrong flag acceptance could still confuse operators or break scripts.

Overview
Fixes graphs list so it hits the server’s bare GET /graphs registry URL instead of going through GraphClient::resolve(), where the RFC-011 D7 “pick a graph” probe blocked listing and --graph could turn the path into /graphs/<id>/graphs.

graphs list now uses synchronous resolve_registry (shared registry_client with the D7 probe). The dead --uri subcommand flag is removed; scope comes from global --server / --profile only, with default_graph ignored on this path.

guard_addressing is generalized to a ScopeFlag × Capability matrix (server, cluster, graph, store, --as, profile), with per-command refinements for init, cluster maintenance, and read-only control verbs. Misapplied flags fail up front instead of being dropped or failing later.

Each verb’s capability is threaded from main into GraphClient::resolve / resolve_with_policy. Capability::Served scope resolution rejects store- and cluster-bound profiles for registry commands.

Docs and OpenAPI comments are trimmed (internal RFC/MR refs); user CLI reference documents registry scope and the new rejection rules. Tests cover the matrix, registry URL shape, scope errors, and integration cases for graphs list, init, optimize, and queries list.

^{Reviewed by Cursor Bugbot for commit 7d3a095. Bugbot is set up for automated code reviews on this repo. Configure here.}

Greptile Summary

This PR fixes graph enumeration by resolving graphs list at the server registry scope. The main changes are:

• Adds a synchronous registry client that targets the bare server URL.
• Introduces a capability-based scope-flag guard for CLI commands.
• Threads command capabilities through graph-client resolution.
• Rejects unsupported addressing flags before command dispatch.
• Updates CLI tests, documentation, and generated API text.

Confidence Score: 5/5

This looks safe to merge.

• The previously reported explicit flag-loss paths are now rejected before dispatch.
• Registry resolution uses the bare server URL and skips graph-specific resolution.
• No additional distinct blocking issue qualifies for this review round.

Important Files Changed

Filename	Overview
crates/omnigraph-cli/src/client.rs	Adds registry-scoped resolution and threads command capabilities through normal client resolution.
crates/omnigraph-cli/src/planes.rs	Replaces ad hoc addressing checks with a capability and scope-flag matrix.
crates/omnigraph-cli/src/main.rs	Routes graph enumeration through the registry client and passes capabilities to graph resolvers.
crates/omnigraph-cli/src/scope.rs	Rejects store- and cluster-bound scopes for served registry commands.

_{Reviews (5): Last reviewed commit: "fix(cli): reject --profile on verbs that..." | Re-trigger Greptile}

Context used:

• Context used - AGENTS.md (source)
• Context used - CLAUDE.md (source)

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ef516c0. Configure here.}