diff --git a/devlog/_plan/261003_cli_gui_parity/000_plan.md b/devlog/_plan/261003_cli_gui_parity/000_plan.md
new file mode 100644
index 00000000000..4ca64462b75
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/000_plan.md
@@ -0,0 +1,58 @@
+# Make dashboard workflows usable from the terminal
+
+OpenCodex already implements many dashboard operations in its CLI, but discovery omits working commands and several workflows expose only some GUI fields. This unit completes the eligible task gaps, makes existing commands discoverable, and gives the shipped ocx skill verified task recipes. Operators keep the same management validation and consent boundaries, with explicit local/live target selection where those effects differ.
+
+Reader: maintainers reviewing the six-layer manual PR stack; they need the scope, exact command contracts and proof for each layer.
+
+## Loop contract
+
+- Archetype: satisfy a fixed, source-audited task inventory, followed by residual accounting.
+- Trigger: user requested near-GUI CLI parity, improved shipped skill, inherited-model subagents, repeated PABCD and a published stack.
+- Goal: every eligible GUI task has a named command/sequence, useful help, safe output, documented target and behavioral evidence; genuine exclusions and duplicate views remain explicit.
+- Non-goals: GUI redesign, provider routing redesign, new auth authority, raw API/config escape hatches, live-user operation, native GitHub stacks, merging, release or deployment.
+- Verifier: numbered phase acceptance tests plus the baseline/QA strategy in 003_verification_strategy.md; a docs checker observes these exact plan files and task ownership before B.
+- Stop: six open, reviewable PRs with successful current-head hosted CI; all task ledger rows closed as verified, alias or justified exclusion, with no unexplained UNKNOWN.
+- Durable artifacts: this unit, 008_task_ledger.json and ignored command/QA receipts under this session.
+- Outcomes: DONE requires implementation, synchronized skill/docs, independent reviews and CI. Real unsupported prerequisites/authority are reported under host blocked rules; workload or compaction is not completion.
+- Escalation: main resolves source/architecture conflicts; ask the user only for genuinely new authority. Failed delegates follow the bounded retry/retirement owner; do not swap models silently.
+- Resources: no user token/cost/time cap. Tool scope is repository editing, isolated local fixtures and GitHub PR/CI for this repository. No real accounts, credentials, running services, paid upstream calls or destructive user files are QA targets.
+
+## Baseline and source owners
+
+Baseline dev is 9f89b7265b754eb681215ad327fc9459af37b9e1. The initial inventories contain 176 task-entry rows, with two additional embedded dashboard setting groups subsequently found (memory models and compaction routing). Duplicate entry points are retained as aliases rather than silently dropped. Source-coverage labels in 004/005 are not passing runtime evidence. Executable 010..080 decisions supersede earlier source-join syntax proposals; the private audit record retains their history.
+
+The tree remains Bun TypeScript: src/cli owns domain handlers and pure help/capability data; existing server management modules own validation/live mutation; tests/cli plus domain server tests own proof; skills/ocx and docs-site own operating guidance; structure owns current contracts. Existing structure/manifest.json maps src/cli to runtime/config/integration/Desktop/release docs. Only affected owners are updated.
+
+## Dependency-ordered work phases and PR layers
+
+| Phase | Executable document | Dependency | Output / PR layer |
+| --- | --- | --- | --- |
+| wp0 | This roadmap, inventories and UX contract | none | Docs-only audit; locks the remaining designs before source edits |
+| wp1 | 010_discovery_foundation.md | wp0 | Pure metadata and generated-document capacity; layer 1 |
+| wp2 | 020_existing_workflow_discovery.md | wp1 | Accurate existing task discovery and skill routing; finish layer 1 |
+| wp3 | 030_provider_management.md | wp2 | Bounded input and exact provider live workflows; layer 2 |
+| wp4 | 040_models_routing.md | wp3 | Models, picker order, combos and routing profile edits; layer 3 |
+| wp5 | 050_accounts_runtime_settings.md | wp4 | Account policies, explicit auth options, agent/settings/v2 parity; layer 4 |
+| wp6 | 060_integrations_maintenance.md | wp5 | Live Desktop profile, integration recovery, storage and Hub reads; layer 5 |
+| wp7 | 070_observation_api_tools.md | wp6 | Timeline/log fidelity, scoped usage and chosen-key/audio tools; layer 6 |
+| wp8 | 080_acceptance_publication.md | wp7 | Residual task proof, final skill/docs and all exact-head PR receipts; finish layer 6 |
+
+Every work phase runs a full P→A→B→C→D cycle. wp0 is code-free. Later P revalidates its existing decade doc and quotes the previous D conclusion; changes to decisions return to the same architect before A. Branch names: codex/cli-parity-foundation → codex/cli-parity-providers → codex/cli-parity-models → codex/cli-parity-accounts → codex/cli-parity-integrations → codex/cli-parity-observation. The bottom targets dev; each child targets its open parent. No native stack registration or merge is authorized.
+
+## Coverage and decisions
+
+- 002_terminal_ux.md defines terminal behavior and progressive disclosure.
+- 003_verification_strategy.md records real baseline checks and verification scope.
+- 004_settings_coverage.md and 005_operations_coverage.md preserve field-level source joins.
+- 007_architecture_decisions.md records proposal dispositions, additive field chain and target boundaries.
+- 008_task_ledger.json assigns every row to a phase; historical labels are retained while current status/evidence advance.
+
+Source comparison established that local provider/custom-model/v2/logout effects differ from live management receipts. --live is therefore explicit and never inferred from proxy availability or --json. Existing local behavior remains available. Browser-session identity actions stay outside automated parity; data-plane API testing is included with the same data-plane admission authority.
+
+## Alternatives rejected
+
+A generic API request command would expose routes without usable task contracts. Generic config writes would bypass existing live validation and completion receipts. A new command framework would duplicate the existing Capability/domain-handler architecture. Declaring routes that local commands never fetch would make coverage appear complete while remaining false. None is used.
+
+## Phase records
+
+wp0 roadmap was locked after independent audits passed. Inventory corrections already folded: existing v2 verbs are real local implementations, not absent agent verbs; model preset custom is disabled in the GUI; Lab local commands must not acquire fictitious HTTP coverage; memory-model and compaction-routing controls need explicit rows. Whole-plan architect reflection is ALIGNED at a095a4e514d6d8e5a37dbf05a66b2c9156ebaeeb28a8e0fb878bc76f931c27b1; the serializer and data-plane contract amendments were audited independently and passed. See 009_roadmap_lock.md.
diff --git a/devlog/_plan/261003_cli_gui_parity/002_terminal_ux.md b/devlog/_plan/261003_cli_gui_parity/002_terminal_ux.md
new file mode 100644
index 00000000000..20ed64696fe
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/002_terminal_ux.md
@@ -0,0 +1,29 @@
+# Terminal UX contract
+
+This is a repeated-use management tool for people and automation. The design preserves the compact root help and contextual family navigation delivered by the CLI help stack; it extends task coverage without turning the terminal into an endpoint debugger.
+
+Design variance: 2/10. Motion: 1/10 (no decorative animation). Density: D8 for the full reference, progressive disclosure for first use. Monospace, plain text and predictable line ordering carry meaning; color or symbols never determine correctness. Raster concepts do not help this utility surface and are intentionally omitted.
+
+## Task language
+
+- Extend existing nouns before adding new roots. Prefer list/show/status, set/update, enable/disable, apply/reset and their established domain equivalents.
+- A family with no action offers a safe overview/help or an existing read-only default. It must never silently choose a write.
+- Help is available without a live proxy and never runs a management action. Examples use registered grammar and placeholders, with a next read/verify command after a mutation.
+- Short human output answers what changed, what remains unapplied and the next action. JSON preserves safe API DTO fidelity on stdout; diagnostics stay on stderr and failures keep documented exit codes.
+- Empty lists distinguish no configuration, no matching rows and unavailable evidence. Do not render unavailable as zero or an empty successful inventory.
+- Unknown/missing/duplicate arguments must fail before network writes. Boolean and numeric syntax reuse established parsers; structured inputs receive bounded, explicit JSON file/stdin forms only when the task's data shape needs them.
+- IDs and names are encoded at path/query boundaries. No arbitrary method/URL command is counted as GUI parity.
+
+## Writes and recovery
+
+Existing management routes remain the source of validation, persistence, ownership and live application. A saved configuration is not proof that the client/runtime applied it; preserve refusal, partial application and restart-needed fields in output.
+
+Destructive operations retain explicit confirmation or preview as appropriate to the existing command family and server contract. Read, preview, apply and verify are distinguishable operations. No hidden retry of non-idempotent writes. New commands do not expand account identity, browser consent or secret-returning authority.
+
+No-running-proxy output names the recovery command. Invalid input names the argument and expected syntax without leaking its value when secret-bearing. Server errors preserve meaningful reason/hint fields and failure exit codes. Tests activate server refusal, not-found/conflict, malformed arguments and non-confirmed mutation paths.
+
+## Discoverability and skills
+
+The capability registry, help resolver, generated management reference and human recipes describe the same supported commands. Existing undeclared commands must be mapped before declaring a gap. Skill recipes start with readiness/version checks when operating a real proxy, then task-specific commands and verification. Human-only exclusions stay explicit and do not gain an API workaround.
+
+Each inventory row records GUI task, existing API contract, existing CLI route, implementation/discovery gap, final command and verification, or a reasoned exclusion. Coverage is measured against user tasks, not endpoint count or lines added.
diff --git a/devlog/_plan/261003_cli_gui_parity/003_verification_strategy.md b/devlog/_plan/261003_cli_gui_parity/003_verification_strategy.md
new file mode 100644
index 00000000000..a863a13ebb7
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/003_verification_strategy.md
@@ -0,0 +1,30 @@
+# Verification strategy and observed baseline
+
+Baseline: `9f89b7265b754eb681215ad327fc9459af37b9e1`, the completed CLI-help stack on dev. This unit starts on `codex/cli-parity-foundation` in the existing managed worktree.
+
+Before implementation, the following ran successfully:
+
+| Command | Result | What it observes |
+| --- | --- | --- |
+| `bun run typecheck` | exit 0 | The repository TypeScript graph, including src/cli. |
+| `bun run structure:check` | exit 0 | Structure manifest, declared source ownership, existing paths and invariant bindings; not prose correctness. |
+| `bun run skill:surface:check` | exit 0 | Generated skill reference compared with src/cli/capabilities.ts. |
+| `bun test tests/cli/cli-capabilities.test.ts tests/cli/cli-capabilities-arguments.test.ts tests/server/management-route-registry.test.ts tests/ci-workflows/skill-ocx.test.ts` | 62 pass, 0 fail, 1180 assertions | Capability parsing, leaf-module import boundary, management declaration reconciliation and shipped-skill command/consent boundaries. |
+
+Raw evidence is in the ignored `.tmp/cli-parity/baseline-*.log` files. The source-map command is unavailable in the installed plugin (it requires a codexclaw development checkout); bounded file inventories and exact source anchors replace it.
+
+## Per-unit proof
+
+Each implementation phase owns focused regression files with exact expected HTTP method/path/body, safe structured output, error/exit mapping and no-request assertions for rejected inputs. Tests use isolated homes and injected RuntimeApiDeps or a disposable loopback fixture; they do not mutate the operator's running proxy, credentials, client applications or accounts.
+
+Acceptance includes real CLI subprocess invocations with separated stdout/stderr, recorded exit codes and plain/pipe output. Help/version paths must remain offline and write-free. For mutations, run an equivalent isolated management-route contract scenario where appropriate; mocking a request records transport shape but does not by itself prove server acceptance. Input files/stdin, cancellation and confirmation paths receive explicit reachable scenarios. Each QA-owned temporary server/process has a teardown receipt.
+
+Existing global gates remain intact. New test files enter both test-layout maps. Source changes update their owning structure docs; public behavior updates CLI docs and the operating skill. Generated output is regenerated from its actual registry owner and checked for drift. Prose/UX semantics receive independent human-style review, not a test that only looks for a phrase.
+
+## Broad verification and publication
+
+Focused tests and type/static/document gates run locally. Full-suite and platform coverage use the current-head hosted PR CI for every layer; the repository's full suite has tens of thousands of tests and concurrent worktrees make repeated local full/changed runs disproportionate. This is the resource-scoped verification plan, not permission to ignore failing focused tests. Record exact commands and the coverage left to CI in each PR.
+
+The preceding CLI-help task recorded four local full-suite failures, all reproduced on its untouched baseline (three restart-lease failures and a pre-request directory snapshot EISDIR). Those records are history, not current-unit passing evidence. If this unit encounters a failure, inspect it and attribute or repair it with fresh source/command evidence. No skip, threshold relaxation, retry-as-fix or unrelated suite substitution is allowed.
+
+Each PR must retain its own current-head CI run, event, attempt, expected executed jobs, checkouts actually tested and open-review dispositions. Canceled/skipped/missing jobs are not passing tests. The stack remains open for review at completion; merge/release is not part of this request.
diff --git a/devlog/_plan/261003_cli_gui_parity/004_settings_coverage.md b/devlog/_plan/261003_cli_gui_parity/004_settings_coverage.md
new file mode 100644
index 00000000000..9acce9af42b
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/004_settings_coverage.md
@@ -0,0 +1,144 @@
+# Settings GUI-to-CLI field/workflow gap join
+
+Source-only completed join, 2026-10-03. One row for every one of the 67 tasks in the settings GUI/API inventory; IDs are prefixed `set-`. Joined the CLI source inventory to targeted provider/models/account/agent/combo/route/protocol/Lab handlers. No whole-CLI rescan, runtime/test/proxy/credential access, or source edits. Only this second-pass artifact is written. Exact source anchors establish implementation shape, not runtime success.
+
+Status meanings:
+
+- **COMPLETE**: named implementation covers the GUI fields/actions; no new operation identified. Runtime validation remains unrun.
+- **DISCOVERY_ONLY**: GUI operation is implemented, but full leaf grammar is absent/incomplete in indexed capabilities/help; retain existing writer and improve discovery. This does not demand one capability entry per visual action.
+- **IMPLEMENTATION_GAP**: at least one reachable field/action or material workflow behavior differs; existing supported variants are retained explicitly in the row.
+- **EXCLUDED**: session-only consent or presentation boundary; no admin-token bypass should be proposed.
+- **UNKNOWN**: field coverage exists but local/live convergence equivalence needs isolated proof. A generic config writer or HTTP passthrough is not parity.
+
+Commands are shown without repeated `ocx` prefixes for readability. Recommended syntax is a remediation proposal for the parent, not a claim that those flags already exist. `--json` is preserved where implemented; secrets use existing stdin contracts. Source scopes include the directly referenced handler helpers only.
+
+## Corrections and important joins
+
+1. Model preset `custom` is a disabled GUI state, not a selectable action (`gui/src/pages/Models.tsx:1550`). Existing preset/all CLI is sufficient; do not implement a custom flag solely because the server accepts the field.
+2. Picker order and featured roster share `/api/subagent-models` but are distinct bodies. Existing `agent subagents set` does not implement picker ordering.
+3. `--effort-mode` on combo sets `defaultEffortMode` (fallback/force), not GUI `reasoningEffortMode` (strict/adaptive). A similar name is not field parity.
+4. Anthropic account threshold exists with `--account`; the same parser requires an account and does not expose the GUI pool-wide threshold/quota-window/enabled controls. Codex per-account threshold is also missing while pool-wide threshold exists.
+5. Registry deferred claims for Lab public actions are stale per the CLI inventory. CompatibilityMatrix is read-only and the local Lab reads already exist; do not plan an HTTP-only rewrite.
+6. GUI model-display-name mutation is absent from both dedicated CLI and current route declaration. Custom-model edit is not a substitute. Pricing reset, discovered metadata reset and context-cap variants are already implemented.
+7. **Parent correction applied:** multi-agent mode/thread/keep-native/hint operations exist under the independent `ocx v2` root (`src/cli/dispatch.ts:539`, `src/cli/v2.ts:109`). M13/S04 are not missing writers; they are UNKNOWN for local/live equivalence with confirmed JSON/discovery/advisory differences. No duplicate `agent mode` taxonomy is proposed.
+8. A11 reachability is now confirmed: picker and hard lock mount in `gui/src/pages/codex-set-multiauth.tsx:218` and `:221`. Client-settings ownership still needs sibling deduplication.
+
+## Complete task matrix
+
+| Task | Status | Existing command(s) | Exact missing variant / supported boundary | Recommended syntax / remediation | Source anchors (CLI and GUI/API) |
+|---|---|---|---|---|---|
+| set-P01 — Inspect configured providers, presets, authentication availability | DISCOVERY_ONLY | provider list/show/presets; inspect config; account list/current; status --json | Provider/catalog/authentication views exist across commands; static provider list is not the live config view. No separate raw OAuth-provider route command is needed if preset/auth inventory is preserved. | Index existing workflows and distinguish local provider list from inspect config; retain redaction. | src/cli/provider.ts:80; src/cli/provider-runtime.ts:235; src/cli/inspect.ts:209; src/cli/account.ts:44; gui/src/pages/use-providers-fetch.ts:34; src/server/management/provider-routes.ts:933 |
+| set-P02 — Add a preset/custom provider; enable canonical OpenAI account provider | IMPLEMENTATION_GAP | provider add P [--adapter A --base-url U --api-key ... --default-model M --allow-private-network --force --set-default --sync]; provider edit openai --enabled on | Add parser has no responsesPath/authMode fields; account-mode is a later command. Local add returns needsSync; --json returns before --sync executes. Live validated POST parity and canonical enable are separate concerns. | Extend add with --responses-path PATH and --auth-mode key\|forward\|oauth; use server POST on explicitly live path, preserving existing offline mode. Make --json --sync report actual convergence instead of silently bypassing it. | src/cli/provider.ts:142; src/cli/provider.ts:156; src/cli/provider.ts:212; src/cli/provider.ts:279; src/cli/provider-runtime.ts:73; gui/src/components/AddProviderModal.tsx:203; src/server/management/provider-routes.ts:1161 |
+| set-P03 — Edit provider transport, discovery, default model, note, network permission | IMPLEMENTATION_GAP | provider edit/update P --adapter A --base-url U --default-model M\|- --auth-mode MODE\|- --note TEXT\|- --api-key-transport MODE\|- --enabled on\|off --live-models on\|off --allow-private-network on\|off | GUI fields covered except Cursor upstreamHttpVersion. Empty note/default clearing exists; headers and context-tier CLI extras do not cover HTTP-version override. | Add --upstream-http-version http1.1\|- to provider edit; '-' sends null, omission leaves field unchanged; preserve server validation. | src/cli/provider-runtime.ts:59; src/cli/provider-runtime.ts:112; src/cli/provider-runtime.ts:312; gui/src/components/provider-workspace/ProviderSettings.tsx:233; src/server/management/provider-routes.ts:1412 |
+| set-P04 — Configure and inspect request pacing | IMPLEMENTATION_GAP | inspect pacing --name P --json | Read exists; provider edit has no requestPacing writer, no provider/model RPM, delay or concurrency fields, no enabled/reset controls. | Add provider pacing P [--enabled on\|off] [--rpm N] [--min-interval-ms N] [--max-concurrent N] [--model M] [--clear] --json; a domain-specific --file rules.json can carry atomic full rules, not arbitrary API paths. Preserve untouched provider/model fields. | src/cli/inspect.ts:214; src/cli/provider-runtime.ts:65; src/cli/provider-runtime.ts:140; gui/src/components/provider-workspace/ProviderSettings.tsx:178; src/server/management/provider-routes.ts:917 |
+| set-P05 — Enable/disable, choose default, remove provider | IMPLEMENTATION_GAP | provider edit P --enabled on\|off; provider set-default P; provider remove P | Enable is live PATCH. Set-default/remove are local paths; remove refuses current default while GUI reassigns an enabled replacement; local removal dependency check only examines targets. Thus CRUD names do not establish same live workflow. | Keep names, add/use live mutation path for set-default and remove with exact server receipt/dependency refusals. Explicit offline behavior must remain labeled. Do not emulate default deletion as two non-atomic requests. | src/cli/provider-runtime.ts:133; src/cli/provider.ts:345; src/cli/provider.ts:355; src/cli/provider.ts:459; gui/src/pages/use-providers-crud.ts:67; src/server/management/provider-routes.ts:1459 |
+| set-P06 — Change OpenAI account mode | DISCOVERY_ONLY | provider account-mode pool\|direct --json | Standalone PATCH is covered, including server-side rebind/cache effects. Leaf lacks dedicated capability metadata per CLI inventory. | Document/index existing command; no new writer. | src/cli/provider-runtime.ts:252; gui/src/components/provider-workspace/ProviderSettings.tsx:289; src/server/management/provider-routes.ts:1421 |
+| set-P07 — Atomically edit provider JSON | IMPLEMENTATION_GAP | config import exists but is not provider-editor CAS parity | No dedicated baseline/next provider DTO workflow; local full config import lacks server stale-baseline check, target scope and persisted receipt. | provider snapshot --json; provider apply --baseline FILE --file FILE --json. Snapshot emits {defaultProvider,providers}; apply sends exactly {baseline,next}, rejects stale 409 without auto-refresh/rebase; bounded files or stdin variant. No generic passthrough. | src/cli/provider-runtime.ts:312; src/server/management/provider-routes.ts:1055; gui/src/hooks/useJsonConfigEditor.ts:16; gui/src/hooks/useJsonConfigEditor.ts:55; src/server/management/provider-routes.ts:1055 |
+| set-P08 — Check provider connectivity | DISCOVERY_ONLY | provider test P --json | Existing named probe distinguishes applicable:false. No missing GUI action. | Index command and retain not-applicable/configuration-only versus live connectivity distinctions. | src/cli/provider-runtime.ts:148; gui/src/components/provider-workspace/ProviderOverview.tsx:109; src/server/management/provider-routes.ts:1619 |
+| set-P09 — Inspect provider quota/capacity/usage | COMPLETE | provider quota [--refresh] --json; account list P --quota [--refresh] --json; usage --range 30d --surface codex\|all --json | Operational quota and scoped usage reads exist. Generic telemetry ownership belongs to sibling; do not add a duplicate provider usage transport. | Reuse existing commands. Keep passive quota unavailable and partial usage signals. | src/cli/provider-runtime.ts:178; src/cli/account-api.ts:370; src/cli/observe.ts:164; gui/src/components/provider-workspace/ProviderWorkspaceShell.tsx:182; src/server/management/provider-routes.ts:904 |
+| set-P10 — OAuth login, add another account, reauthenticate, submit callback, cancel, logout | IMPLEMENTATION_GAP | account login P [--reauth --id I] [--no-wait]; account reauth/code/cancel; login P (local); logout P --json (local) | Core flow exists, but account login always sends addAccount:true for non-reauth; no explicit openBrowser override. Initial local-import login and runtime logout equivalence remain UNKNOWN. Meta Muse consent cannot be bypassed. | Add account login --open-browser on\|off and --add-account on\|off with omission preserving server preference; add account logout P --json for exact runtime logout if live-equivalence fixture fails. Keep local login behavior documented separately and preserve provider consent gate. | src/cli/account-auth.ts:139; src/cli/account-auth.ts:260; src/cli/dispatch.ts:374; src/cli/dispatch.ts:425; gui/src/pages/use-providers-oauth.ts:119; src/server/management/oauth-account-routes.ts:236 |
+| set-P11 — Kiro native device login | COMPLETE | account login kiro --method builder-id\|google\|github [--no-wait] --json; account cancel kiro --flow F --json | Native device method, flow polling and cancellation exist; add-only constraints match GUI. | Retain implementation; expose flags consistently in higher-level account help where omitted. | src/cli/account-auth.ts:150; src/cli/account-auth.ts:174; src/cli/account-auth.ts:327; gui/src/components/use-kiro-device-login.ts:46; src/server/management/oauth-account-routes.ts:250 |
+| set-P12 — Manage OAuth account roster | DISCOVERY_ONLY | account list/current/use P I; account alias P I TEXT\|-; account pause/resume P I; account remove P I --yes; all support --json | Roster lifecycle and clear alias are covered through provider-aware endpoints. Alias and several lifecycle leaves are under-indexed. | Index existing grammar; no new endpoint. Preserve provider capability refusals and exact id/alias resolution. | src/cli/account.ts:44; src/cli/account-extended.ts:438; src/cli/account-extended.ts:803; src/cli/account-extended.ts:1064; gui/src/hooks/useProviderAccountPools.ts:210; src/server/management/oauth-account-routes.ts:398 |
+| set-P13 — Import Antigravity accounts | DISCOVERY_ONLY | account import google-antigravity --format cockpit-tools --file F\|--stdin --json | Bounded import exists with redacted per-record receipt and nonzero for failed/unsupported records; no missing GUI action. | Index existing command and safe input forms. | src/cli/account-extended.ts:541; src/cli/account-extended.ts:595; src/cli/account-extended.ts:616; gui/src/components/provider-workspace/ProviderAuthPanel.tsx:358; src/server/management/oauth-account-routes.ts:835 |
+| set-P14 — Manage API-key pool | DISCOVERY_ONLY | account list/use P I; account add-key P [--label L] (stdin); account alias P I TEXT\|-; account remove P I --yes --json | Key pool lifecycle is implemented. Secret stdin and null/blank alias semantics already exist. | Index full family; do not add key text to argv examples or create duplicate key pool commands. | src/cli/account-api.ts:419; src/cli/account-extended.ts:507; src/cli/account-extended.ts:1064; gui/src/hooks/useProviderAccountPools.ts:279; src/server/management/oauth-account-routes.ts:929 |
+| set-P15 — Set account-pool strategy and thresholds | IMPLEMENTATION_GAP | account strategy P STRATEGY; account sticky P N; account auto-switch P on\|off\|threshold N\|status; account routes anthropic ... | Strategy/sticky cover common fields. No pool enabled writer or quotaWindow writer. Anthropic auto-switch delegates to account-only parser and requires --account, so GUI pool-level Anthropic threshold is missing. Generic/Codex thresholds exist. | Add account pool P [--enabled on\|off] [--threshold N] [--quota-window five-hour\|weekly\|max-utilization] --json, using unified pool/settings DTO supported fields. Can expose strategy/sticky in same command but retain existing aliases. Never map pool enable to threshold 0 or per-account override. | src/cli/account-extended.ts:355; src/cli/account-extended.ts:941; src/cli/account-extended.ts:974; src/cli/account-anthropic-threshold.ts:14; gui/src/pool-settings.ts:74; src/server/management/oauth-account-routes.ts:559 |
+| set-P16 — Set per-Anthropic-account auto-switch override | COMPLETE | account auto-switch anthropic status\|on\|off\|inherit\|threshold N --account I --json | Per-account nullable override and inherited/effective threshold are implemented; inherit sends null. | Keep command; do not confuse P15 pool policy with this scoped override. | src/cli/account-anthropic-threshold.ts:4; gui/src/hooks/useProviderAccountPools.ts:443; src/server/management/oauth-account-routes.ts:507 |
+| set-P17 — Control xAI Responses opt-in and model Fast variants | IMPLEMENTATION_GAP | provider edit xai --xai-chat on\|off --json | xaiResponsesOptIn is implemented via inverse --xai-chat (!value). No fastEnabled field/flag for provider Fast model variant rows. | Add provider edit P --fast on\|off mapping fastEnabled; document --xai-chat off means Responses opt-in true, without reversing existing flag meaning. | src/cli/provider-runtime.ts:76; src/cli/provider-runtime.ts:108; gui/src/components/provider-workspace/ProviderAuthPanel.tsx:75; src/server/management/provider-routes.ts:1412 |
+| set-P18 — Inspect/redeem Grok reset coupons | COMPLETE | account grok-reset-coupons [I] [--consume --yes --token-id T --operation-id UUID] --json | Read, token selection, consent flag and stable operation-id retry exist. | No new writer. Preserve explicit user spend intent and exact operation UUID on retry. | src/cli/account-auth.ts:374; gui/src/hooks/useGrokResetCoupons.ts:133; src/server/management/grok-coupon-routes.ts:63 |
+| set-P19 — Inspect/redeem Anthropic reset grants | IMPLEMENTATION_GAP | No Anthropic grant read command in account-auth dispatcher; Grok/Codex reset commands target different contracts | Read missing; consume is EXCLUDED because server requires gui-session. Do not extend reset-credit consume to Claude. | Add account anthropic-reset-grants [I] --json for GET only, with optional current-account semantics matching server. Explain session-only consume rather than attempting session minting. | src/cli/account-auth.ts:414; src/server/management/anthropic-reset-grant-routes.ts:109; src/server/management/anthropic-reset-grant-routes.ts:131; gui/src/hooks/useAnthropicResetGrants.ts:168; src/server/management/anthropic-reset-grant-routes.ts:131 |
+| set-P20 — Choose whether OAuth launches browser on proxy host | IMPLEMENTATION_GAP | account login currently omits openBrowser; GUI local preference feeds request field | No one-shot browser-launch override; device flag changes authentication protocol and is not equivalent. | Add account login P --open-browser on\|off; omit field when flag absent. No new persistent settings write required for GUI-local preference. | src/cli/account-auth.ts:139; src/cli/account-auth.ts:198; src/cli/account-auth.ts:260; gui/src/components/open-browser-pref-toggle.tsx:19 |
+| set-A01 — Inspect/refresh account readiness, quotas and active selection | COMPLETE | account list openai --quota [--refresh] --json; account current openai --json; account refresh openai --json | Read, quota refresh and POST validation refresh already exist. Login's old recovery prose pointing to GUI does not mean refresh command is absent. | Reuse command; update recovery guidance as discovery work only if in authorized scope. | src/cli/account-extended.ts:326; src/cli/account-extended.ts:347; src/cli/account-api.ts:281; gui/src/hooks/useCodexAccountPool.ts:317; src/codex/auth-api/routes.ts:35 |
+| set-A02 — Add/re-authenticate pool account with browser or device flow | IMPLEMENTATION_GAP | account login openai --id I --reauth --device --no-wait --json; account code/cancel openai --flow F | Start/poll/manual code/cancel complete; openBrowser one-shot preference absent as P20. No need for a second Codex login command. | Extend existing login flag as P20, keep id and flowId distinct, preserve device flag and user verification. | src/cli/account-auth.ts:139; src/cli/account-auth.ts:197; src/cli/account-auth.ts:294; src/cli/account-auth.ts:327; gui/src/components/use-add-codex-account-oauth.ts:95; src/codex/auth-api/routes.ts:493 |
+| set-A03 — Reauthenticate native main in place | COMPLETE | account main reauth --device [--no-wait] --json; account main reauth status\|cancel --flow F --json | Dedicated native-main no-body start, exact-flow polling/cancel implemented. | Keep native-main identity separate from account login openai. Sibling can own docs without duplicating operation. | src/cli/account-main.ts:192; gui/src/components/use-main-device-reauth.ts:99; src/codex/main-device-reauth-api.ts:49 |
+| set-A04 — Select active account, rename, remove | DISCOVERY_ONLY | account current/use/clear openai; account alias openai I TEXT\|-; account remove openai I --yes --json | Selection, explicit auto clear, rename/reset alias and removal exist. Main versus auto has documented identity precedence. | Index leaves. Use account clear to always clear pin when a real id is named auto. | src/cli/account.ts:44; src/cli/account.ts:364; src/cli/account-extended.ts:438; src/cli/account-extended.ts:1064; gui/src/hooks/useCodexAccountPool.ts:486; src/codex/auth-api/routes.ts:52 |
+| set-A05 — Pause/resume, pause exhausted accounts, set priority | COMPLETE | account pause/resume openai I; account pause-exhausted openai; account priority openai I N\|first\|earlier\|normal\|later\|last\|reset --json | Pause/resume/exhausted and priority null-reset are present. | No new commands; keep main restrictions and server-authoritative priority receipt. | src/cli/account-extended.ts:714; src/cli/account-extended.ts:803; src/cli/account-extended.ts:875; gui/src/hooks/useCodexAccountPool.ts:535; src/codex/auth-api/routes.ts:90 |
+| set-A06 — Set per-account auto-switch threshold | IMPLEMENTATION_GAP | account auto-switch openai on\|off\|threshold N\|status is pool-wide only | Codex per-account id plus threshold:null override has no parser path; --account is parsed only by Anthropic handler. | Extend account auto-switch openai ... --account I, add inherit => {id,threshold:null}; pool action with no --account remains {threshold}. Resolve main and aliases explicitly. | src/cli/account-extended.ts:355; src/cli/account-extended.ts:394; src/cli/account-anthropic-threshold.ts:4; gui/src/hooks/useCodexAccountPool.ts:623; src/codex/auth-api/routes.ts:310 |
+| set-A07 — Permit paid credits after quota exhaustion | IMPLEMENTATION_GAP | Only generic config fallback; no account-auth/extended credits policy handler | Both individual {id,creditsAfterLimit} and aggregate {all} variants are missing. | account credits openai I on\|off --json; account credits openai --all on\|off --json. Mutually exclusive selector/all; GET/read from account roster, PUT exact credits endpoint. Require explicit cost-spend opt-in intent; never infer from show-credits preference. | src/cli/account.ts:44; src/cli/account-auth.ts:414; src/codex/auth-api/routes.ts:122; gui/src/hooks/useCodexAccountPool.ts:662; src/codex/auth-api/routes.ts:122 |
+| set-A08 — Inspect/redeem Codex reset credits | DISCOVERY_ONLY | account reset-credits I\|main [--consume --yes --operation-id UUID] --json | Read and redeem exist, with stronger optional retry identity than current GUI. Root account usage omits operation-id though leaf handler supports it. | Index leaf grammar and stable retry id; no missing operation. | src/cli/account-auth.ts:345; src/cli/account.ts:69; gui/src/components/CodexAccountPool.tsx:441; src/codex/auth-api/routes.ts:454 |
+| set-A09 — Configure quota-window activation and credit display | IMPLEMENTATION_GAP | system settings --json reads settings; account refresh handles immediate refresh only | No codexQuotaAutoRefresh per-id/per-window writer and no showCodexCredits switch. Immediate refresh is not quota-window activation; show credits is not credits-after-limit. | account quota-activation openai I --window fiveHour\|weekly on\|off --json, exact {codexQuotaAutoRefresh:{id,window,enabled}}; system settings --show-codex-credits on\|off for presentation preference. Sibling/main decide ownership. | src/cli/system-command.ts:124; src/cli/account-extended.ts:326; gui/src/components/CodexAccountPool.tsx:374; src/server/management/config-routes.ts:564 |
+| set-A10 — Native-main profile inventory, register, switch/recover | DISCOVERY_ONLY | account main list\|doctor\|register LABEL\|switch I --yes\|recover [--rollback --yes] --json | Native-profile workflows implemented, including staging add beyond GUI. CLI recover without rollback intentionally uses {rollback:false}; GUI's confirmedStopped true does not imply missing safe recovery action. | Index existing family; shared lifecycle owner should verify no-op recovery versus rollback fixture, not add a second writer. | src/cli/account-main.ts:269; src/cli/account-main.ts:280; src/cli/account-main.ts:359; src/cli/account-main.ts:376; gui/src/components/CodexAccountPool.tsx:564; src/codex/native-profile-api.ts:137 |
+| set-A11 — Account-picker setting and main hard lock | IMPLEMENTATION_GAP | system settings --json reads values | No codexAccountPickerEnabled or codexMainAccountHardLock writer in dedicated settings handler. | Extend system settings --account-picker on\|off --main-account-hard-lock on\|off, exact settings fields and server receipt. Confirmed GUI mount at codex-set-multiauth:218/221; sibling-owned overlap, not unresolved reachability. | src/cli/system-command.ts:124; gui/src/pages/codex-set-multiauth.tsx:218; gui/src/components/CodexAccountPickerSetting.tsx:27; src/server/management/config-routes.ts:512 |
+| set-A12 — Read prompt layer stack and effective prompt text | COMPLETE | inspect codex-prompt --json; inspect codex-prompt --text (mutually exclusive) | Stack and bounded effective-text read are implemented. | No new command; unavailable text remains unavailable, not empty successful content. | src/cli/inspect.ts:32; src/cli/inspect.ts:216; gui/src/pages/codex-set-prompt.tsx:147; src/server/management/codex-prompt-routes.ts:308 |
+| set-A13 — Toggle/edit/order custom prompt layers and base variants | EXCLUDED | inspect codex-prompt is read-only | Prompt toggles, ordered custom layers, base select/edit/delete require GUI-session principal; no admin CLI write parity should be added. | Retain documented exclusion; user-directed GUI operation only unless parent separately redesigns product consent contract. | src/server/management/codex-prompt-routes.ts:299; src/server/management/route-registry.ts:198; gui/src/pages/codex-set-prompt.tsx:163; src/server/management/codex-prompt-routes.ts:332 |
+| set-A14 — Adopt existing prompt configuration or repair prompt drift | EXCLUDED | inspect codex-prompt can expose drift | Adopt/repair preview and commit share session-only gate; no auto-repair from read. | Retain exclusion; do not create token-based adoption/repair command. | src/server/management/codex-prompt-routes.ts:299; src/server/management/codex-prompt-routes.ts:413; src/server/management/route-registry.ts:196; gui/src/pages/codex-set-prompt.tsx:304; src/server/management/codex-prompt-routes.ts:413 |
+| set-A15 — Enable default-mode request-user-input | COMPLETE | agent request-user-input [on\|off] --json | Read and boolean write cover GUI; confirmed mounted in CodexSet. | No new command; sibling deduplicates advanced settings. | src/cli/inspect.ts:126; src/cli/agent.ts:432; gui/src/components/DefaultModeRequestUserInputSetting.tsx:7; src/server/management/agent-settings-routes.ts:509 |
+| set-A16 — Toggle Ultra Fast tier | IMPLEMENTATION_GAP | system settings --json reads ultraFastTier | No --ultra-fast-tier mutation flag; provider fastEnabled and catalog fastRows are different settings. | Add system settings --ultra-fast-tier on\|off --json => {ultraFastTier}; preserve server default deletion semantics. | src/cli/system-command.ts:124; src/server/management/config-routes.ts:654; gui/src/components/UltraFastTierSetting.tsx:36; src/server/management/config-routes.ts:516 |
+| set-M01 — Inspect catalog, exposed selection, context limits and provider metadata | DISCOVERY_ONLY | models live --provider P --json; models selected P; models context status; models preset show; models new-policy; alias list; inspect config/catalog | All catalog read families exist; plain models is explicitly static and cannot replace models live. | Index relevant leaves and communicate static versus live; no new catch-all catalog command required. | src/cli/models-runtime.ts:73; src/cli/models-runtime.ts:387; src/cli/models-runtime.ts:435; src/cli/models.ts:381; gui/src/pages/Models.tsx:395; src/server/management/model-routes.ts:213 |
+| set-M02 — Show/hide selected models or all models of one provider | DISCOVERY_ONLY | models enable\|disable P/M [--native] --json; models provider P on\|off --json | Single-model and provider-all identity-aware writes exist. GUI has no separately required arbitrary multi-selection batch command beyond these workflows. | Index existing verbs; preserve native bit and provider membership, not raw disabled-list overwrite. | src/cli/models-runtime.ts:354; src/cli/models-runtime.ts:369; gui/src/model-visibility.ts:87; src/server/management/model-routes.ts:621 |
+| set-M03 — Choose curated/provider model preset and default policy for newly discovered models | DISCOVERY_ONLY | models preset show [--provider P]; models preset apply P [--all]; models new-policy on\|off [--provider P]; models new-arrivals --json | GUI offers preset/all, both implemented. custom is a disabled state activated by model edits, not a missing GUI destination. Policy global/provider on/off covered. | No custom-preset flag required for GUI parity; index existing commands. Any server-only mode custom flag is optional API expansion. | src/cli/models-runtime.ts:435; src/cli/models-runtime.ts:474; gui/src/pages/Models.tsx:1529; gui/src/pages/Models.tsx:1550; gui/src/pages/Models.tsx:1170; src/server/management/model-routes.ts:233 |
+| set-M04 — Edit provider/model aliases and default alias policy | DISCOVERY_ONLY | alias list; alias set P\|P/M ALIAS; alias rm P\|P/M; alias defaults on\|off [--provider P] --json | Provider/model aliases, explicit remove and global/provider defaults covered. | Index full family; do not conflate model alias with display label. | src/cli/alias.ts:16; gui/src/pages/models-alias-editing.ts:30; src/server/management/model-routes.ts:295 |
+| set-M05 — Edit/reset model display label and cost override | IMPLEMENTATION_GAP | models price P/M; models set-price P/M --input N --output N [--cache-read N --cache-write N] or --auto; custom models edit --display-name only | Pricing including null reset complete. Discovered model display-name set/null clear absent; server route is also undeclared in registry. | Add models display-name P/M --set TEXT\|--clear --json; exact modelId/displayName body; preserve persistence receipt when HTTP reports catalog convergence failure. Do not repurpose custom model id endpoint. | src/cli/models-runtime.ts:106; src/cli/models-runtime.ts:202; src/cli/models-runtime.ts:566; src/server/management/model-routes.ts:447; gui/src/components/ModelPriceDialog.tsx:7; src/server/management/model-routes.ts:386 |
+| set-M06 — Create/edit/delete custom model definitions | UNKNOWN | models add P M --display-name --context-window --modalities --reasoning-efforts --default-reasoning-effort; models list-custom --json; models edit ID ...; models remove ID\|P/M --yes | All GUI custom CRUD fields exist. Add/remove are local and call syncCustomModelsIfLive; add/remove lack --json, while edit is live HTTP. Need isolated same-target convergence proof before declaring complete or runtime gap. | Do not invent missing CRUD. If machine parity required, add --json with saved/convergence receipt to local add/remove; optionally route live operations through custom-models API while retaining explicit offline mode. | src/cli/models.ts:185; src/cli/models.ts:197; src/cli/models.ts:280; src/cli/models.ts:359; src/cli/models-runtime.ts:195; gui/src/pages/Models.tsx:1310; src/server/management/model-routes.ts:743 |
+| set-M07 — Override/restore discovered-model capability metadata | COMPLETE | models set P/M --context-window N\|0\|- --modalities CSV\|- --reasoning-efforts CSV\|""\|- --default-reasoning-effort LEVEL\|-; --reset --json | All GUI metadata overrides and full null-reset exist; empty reasoning array versus inherited null is preserved. Catalog refresh failures have saved-state guidance. | Retain existing writer and schema; no generic JSON body option needed. | src/cli/models-runtime.ts:262; gui/src/components/ModelSettingsDialog.tsx:153; src/server/management/model-routes.ts:764 |
+| set-M08 — Override provider/per-model advertised context window | IMPLEMENTATION_GAP | models set P/M --context-window N\|0\|- covers per-model override | Provider-level contextWindow default and one patch containing touched modelContextWindows lack flags. Per-model individual override is already covered; do not duplicate it. | Extend provider edit P --context-window N\|- and repeatable --model-context-window MODEL=N\|-; null clears, untouched keys remain absent. Atomic multi-model patch is optional if parent accepts equivalent individual tasks; provider default is required. | src/cli/provider-runtime.ts:59; src/cli/models-runtime.ts:281; gui/src/pages/Models.tsx:854; gui/src/pages/Models.tsx:825; src/server/management/provider-routes.ts:1412 |
+| set-M09 — Configure context caps: per-provider, global default, apply/remove all | DISCOVERY_ONLY | models context status; models context value N [--set-all]; models context provider P on\|off [--value N]; models context all on\|off --json | All three cap shapes covered, including per-provider explicit value and apply/remove-all. No implementation gap. | Improve discovery only; preserve distinction between global default and applying to every provider. | src/cli/models-runtime.ts:500; gui/src/pages/Models.tsx:939; src/server/management/provider-routes.ts:1881 |
+| set-M10 — Configure picker order manually or by ranking policy | IMPLEMENTATION_GAP | agent subagents status shows picker fields; agent subagents set writes featured models only | No pickerOrder/pickerOrderMode writer. Manual order, default reset, alphabetical/provider/most-used modes all missing. | models order status; models order set --models CSV; models order set --mode default\|alphabetical\|provider\|most-used; models order reset --json. Manual/reset => mode null; ranking computes complete order from visible identities and usage where needed. Never write models for this task. | src/cli/agent.ts:163; src/cli/models-runtime.ts:566; gui/src/pages/Models.tsx:1904; gui/src/components/ModelPickerOrderEditor.tsx:83; src/server/management/subagent-model-routes.ts:19 |
+| set-M11 — Show generated Fast catalog rows | IMPLEMENTATION_GAP | system settings --json reads fastRows | No global fastRows flag; not covered by provider fastEnabled or ultraFastTier. | Add models fast-rows on\|off --json or system settings --fast-rows on\|off, choose one canonical verb and document alias if needed; PUT {fastRows}. | src/cli/system-command.ts:124; src/cli/models-runtime.ts:566; gui/src/components/ModelCatalogSettingsPanels.tsx:11; src/server/management/config-routes.ts:519 |
+| set-M12 — Configure shadow-call interception target | DISCOVERY_ONLY | models shadow status; models shadow set M\|- --enabled on\|off --json | Enable/disable target and empty-string clear covered. | Index existing command; retain validation on enable and target clear. | src/cli/models-runtime.ts:544; gui/src/pages/Models.tsx:480; src/server/management/config-routes.ts:1159 |
+| set-M13 — Configure multi-agent surface and per-session thread limit | UNKNOWN | v2 status; v2 mode v1\|default\|v2; v2 keep-native-v1 on\|off; v2 threads N (local, prose output) | All GUI effects have existing local commands. Mode/keep-native save config and resync; threads uses shared transition helper. No structured --json contract or GUI advisory-ack write in cmdV2. Same live-target and receipt equivalence remains unproven; these are NOT absent operations. | Keep ocx v2 taxonomy. Add strict --json parsing/receipts if machine parity is required; do not create agent mode. Parent decides whether advisory is GUI-only or needs an explicit v2 acknowledgment option. Verify local/shared helpers versus live management path before choosing transport changes. | src/cli/v2.ts:109; src/cli/v2.ts:177; src/cli/v2.ts:191; src/cli/v2.ts:220; src/cli/dispatch.ts:539; src/server/management/agent-settings-routes.ts:415; gui/src/pages/Models.tsx:1101 |
+| set-C01 — Inspect combos, target inventory, quota and catalog exposure | DISCOVERY_ONLY | combo list/show I; models live; inspect config; provider quota --json | All combo inventory/target/quota inputs present; GUI grouping doesn't require a separate command. | Index combo/route combo family; no new transport. | src/cli/combo.ts:54; src/cli/combo.ts:65; src/cli/dispatch.ts:849; gui/src/pages/Combos.tsx:138; src/server/management/combo-routes.ts:122 |
+| set-C02 — Create/edit/rename/remove combo and target policy | IMPLEMENTATION_GAP | combo set\|create\|update I --targets P/M[:W],... --strategy S --sticky N\|- --effort E\|- --alias A\|- --native-alias --display-name TEXT\|- --decision-provider P\|- --decision-model M\|- --decision-timeout N\|- --rename-from OLD; remove I --yes | Core CRUD/rename/JEV resets exist. Missing imageInput auto/disabled, reasoningEffortMode strict/adaptive, target reasoningEfforts/modelProfile; native-alias cannot explicitly switch off while keeping a native-shaped alias. --effort-mode is defaultEffortMode, NOT reasoningEffortMode. Replacing targets loses metadata without expressive parser. | Extend combo set with --image-input auto\|disabled --reasoning-effort-mode strict\|adaptive --native-alias on\|off (backward-compatible bare flag); --targets-file FILE for typed ordered targets incl optional reasoningEfforts/modelProfile, or repeatable structured --target flags. Preserve omitted fields and explicit clears. | src/cli/combo.ts:32; src/cli/combo.ts:80; src/cli/combo.ts:137; src/cli/combo.ts:163; gui/src/pages/Combos.tsx:301; src/server/management/combo-routes.ts:134 |
+| set-C03 — Probe selected JEV decision backend | COMPLETE | combo test [--combo I] [--decision-provider P\|--decision-model M] [--decision-timeout N] --json | Existing probe resolves saved selector client-side when --combo; explicit args probe chosen draft. Discovery command also exists. | No gap; keep potential model-call cost visible and do not treat successful configuration-only response as probe success. | src/cli/combo.ts:186; src/cli/combo.ts:215; gui/src/components/combo-workspace-jev-decision.tsx:107; src/server/management/decision-routes.ts:53 |
+| set-C04 — Explain a saved combo's protocol behavior | COMPLETE | api protocols --json; api explain --model combo/I --inbound responses\|chat\|messages --feature F[,F] ... --json | Saved combo plan and features covered by semantic protocol command. | No combo-specific duplicate required; document usage with public alias. | src/cli/api-protocols.ts:121; src/cli/api-protocols.ts:131; gui/src/components/combo-workspace-detail-panel.tsx:416; src/server/management/protocol-routes.ts:45 |
+| set-C05 — Inspect JEV combo decision outcomes and savings | IMPLEMENTATION_GAP | usage --range ... --model combo/I exists but returns ordinary usage | No jev=1/comboId report selector in usage parser; ordinary model-filtered usage is not JEV decisions/savings/backends report. | Add combo stats I --range 7d\|30d\|all --json, exact GET usage?jev=1&comboId=I&range=; sibling usage owner can share transport/formatting. Do not claim cost savings from missing/partial data. | src/cli/observe.ts:164; src/cli/combo.ts:251; gui/src/components/jev-stats-panel.tsx:90; gui/src/components/jev-stats-panel.tsx:90; src/server/management/logs-usage-routes.ts:188 |
+| set-R01 — Inspect routing profiles, candidates, scoring and compatibility suite choices | DISCOVERY_ONLY | route policy list/show I --json; inspect routing-analytics --json; models live; lab catalog --json | Existing commands expose profile/revision, scoring context, inventory and Lab suite choices. | Index leaves; local Lab query is valid transport for local target. | src/cli/route-policy.ts:27; src/cli/route-policy.ts:43; src/cli/inspect.ts:211; src/cli/lab.ts:87; gui/src/pages/RoutingProfiles.tsx:351; src/server/management/routing-profile-routes.ts:226 |
+| set-R02 — Create/update/remove routing profile | IMPLEMENTATION_GAP | route policy only list/show/dry-run/evaluate | No create/update/delete. Missing all profile-write fields and expectedRevision conflict workflow. | route policy create I --file PROFILE.json --json; route policy update I --file PROFILE.json --expected-revision REV --json; route policy remove I --yes --json. Domain profile schema is exact GUI profile object, not arbitrary endpoint JSON. Omitted profile branches are removed according to server full-profile semantics. | src/cli/route-policy.ts:85; src/server/management/routing-profile-routes.ts:233; gui/src/routing-profile-editor-data.ts:280; gui/src/pages/RoutingProfiles.tsx:458; src/server/management/routing-profile-routes.ts:233 |
+| set-R03 — Dry-run a saved route against requirements | DISCOVERY_ONLY | route policy dry-run\|evaluate I --model-context N --tools --image --structured-output --json | All four GUI evidence inputs supported. Advanced encrypted/reasoning/tier/candidate evidence are server-only and not GUI parity debt. | Index command; optional broader API support should be separate scope. | src/cli/route-policy.ts:55; gui/src/pages/RoutingProfiles.tsx:559; src/server/management/routing-profile-routes.ts:364 |
+| set-S01 — Choose/reorder featured subagent roster | DISCOVERY_ONLY | agent subagents\|roster status\|set CSV\|clear --json | Featured ordered roster, five-item max and empty-list clear covered; this does not cover M10 picker ordering. | Index leaf actions without creating a second roster writer. | src/cli/agent.ts:163; src/cli/agent.ts:426; gui/src/pages/Subagents.tsx:213; src/server/management/subagent-model-routes.ts:54 |
+| set-S02 — Force subagent model and configure fallback chain | COMPLETE | agent subagents force M\|-; agent fallback status\|set [CSV] [--poll-ms 5000..600000]\|clear --json | Force null and fallback empty-list clear/poll range match GUI. Server-only poll null reset not exposed in GUI, so not a GUI gap. | Retain implementation; document identity and clear semantics. | src/cli/agent.ts:173; src/cli/agent.ts:195; gui/src/components/subagents-workspace/SubagentForceControl.tsx:67; src/server/management/subagent-model-routes.ts:101 |
+| set-S03 — Configure delegation guidance/default model/effort and synchronize defaults | IMPLEMENTATION_GAP | agent injection\|guidance set --model M\|- --effort E\|- --guidance on\|off; status --json | Model, effort and guidance covered; syncCodexSubagentDefaults missing. Existing set outputs write result without GUI's normalized reread. | Add --sync-codex-defaults on\|off, exact field. Read authoritative injection DTO after successful save if write doesn't return normalized state; retain null clears. | src/cli/agent.ts:111; src/cli/agent.ts:137; src/server/management/agent-settings-routes.ts:608; gui/src/pages/use-subagent-delegation.ts:15; src/server/management/agent-settings-routes.ts:564 |
+| set-S04 — Set delegation mode and editable proactive hint | UNKNOWN | v2 mode v1\|default\|v2; v2 mode-hint TEXT; v2 mode-hint --clear; v2 status (local) | Mode and hint set/null-reset already exist. mode-hint uses same setMultiAgentModeHintText helper as management route; blank text rejected. Root registry omits mode-hint and cmdV2 lacks JSON/strict trailing-argument receipt handling. Shared mode live-equivalence/advisory issue is M13, not missing hint writer. | Document/index v2 mode-hint and --clear; extend existing v2 machine contract, not agent mode. A hint-file convenience is optional, not GUI parity debt. Test local scope/new-session behavior and shared writer failures before classifying local/live coverage complete. | src/cli/v2.ts:144; src/cli/v2.ts:167; src/cli/v2.ts:191; src/cli/registry.ts:575; src/server/management/agent-settings-routes.ts:394; gui/src/pages/Subagents.tsx:131 |
+| set-S05 — Ask for delegation model recommendation, then separately apply | COMPLETE | agent injection suggest WORK [--model SIZING_MODEL] [--apply] --json; agent injection set --model M --effort E | Suggestion, no-write default and explicit apply cover GUI propose/accept; includes optional sizing override beyond GUI. | No new command; preserve proposal failure/unsized and explicit apply semantics. | src/cli/agent.ts:73; gui/src/components/subagents-workspace/DelegationSuggest.tsx:49; src/server/management/agent-settings-routes.ts:578 |
+| set-K01 — Inspect/filter/paginate compatibility verdicts and subjects | DISCOVERY_ONLY | lab status; lab verdicts --subject --layer --suite --verdict --limit --cursor; lab subjects --limit --cursor --json | Filters/pagination and status read via local projection query already exist. Remote target equivalence is not proven and outside this local scope. | Index local read family; avoid new HTTP-only duplicates. | src/cli/lab.ts:76; src/cli/lab.ts:365; src/cli/lab.ts:385; gui/src/pages/compatibility-matrix-api.ts:35; src/server/management/lab-routes.ts:354 |
+| set-K02 — Inspect one verdict's evidence lineage and production context | DISCOVERY_ONLY | lab subject I; observations --subject I --layer L --suite T --limit --cursor; event I; artifact D; production-signals --subject I --limit --json | All lineage resources exposed; GUI aggregation is composition over named reads. No need to mimic bounded visual panel in CLI; preserve not_verification marker. | Document an evidence-lineage recipe and local target caveat; optional consolidated explain command is convenience, not confirmed missing data. | src/cli/lab.ts:76; src/cli/lab.ts:418; src/cli/lab.ts:428; src/cli/lab.ts:468; gui/src/pages/compatibility-matrix-api.ts:150; src/server/management/lab-routes.ts:358 |
+| set-K03 — Filter protocol pairs and view community trust context | DISCOVERY_ONLY | lab subject I --json; lab public community --json | Community trust DTO and subject protocol pairs exposed. Pair dropdown filters are client-side presentation over subject details; no new protocol-pair endpoint. | Index command/recipe; no mutation gap. If parent wants server-side pair filtering, treat it as separate enhancement. | src/cli/lab.ts:92; src/cli/lab.ts:297; src/cli/lab.ts:418; gui/src/pages/compatibility-protocol-pairs.ts:14; src/server/management/lab-routes.ts:287 |
+| set-K04 — Inspect provider upstream wire/protocol and conversion plan | COMPLETE | api protocols [--provider P] --json; api explain --model M --inbound PROTOCOL [--feature F] --json | Provider wire, global policy revision and plan features covered. | Retain semantic CLI commands; not generic passthrough. | src/cli/api-protocols.ts:121; src/cli/api-protocols.ts:131; gui/src/components/provider-workspace/ProviderProtocolPanel.tsx:1; src/server/management/protocol-routes.ts:67 |
+| set-K05 — Control protocol exposure/rollout | COMPLETE | api policy --messages on\|off --unrepresentable legacy\|reject --rollout SWITCH=on\|off ... --json | Messages toggle and all server rollout fields already supported. Actual GUI control is on API-surface cards, a sibling boundary. | No gap. Preserve strict feature/rollout validation; sibling can index overlapping entrypoint. | src/cli/api-protocols.ts:151; gui/src/pages/api-surface-cards.tsx:57; src/server/management/protocol-routes.ts:143 |
+
+## Priority remediation specifications and next proof
+
+These are bounded implementation candidates for the parent; several matrix rows share a single change. The 24 IMPLEMENTATION_GAP rows are **not** 24 independent command families. M13/S04 are now UNKNOWN for local/live equivalence, with existing effects confirmed.
+
+| Priority / rows | Exact implementation contract | Required isolated proof (not run here) |
+|---|---|---|
+| First: set-M05 display names | `models display-name P/M --set TEXT` or `--clear` sends PUT `/api/providers/P/model-display-names` `{modelId:M,displayName:TEXT\|null}`. Add regex route declaration. Keep custom model edit unchanged. Server can save and then return failed convergence; CLI must retain saved state/error receipt instead of saying no change happened. | Set, clear, missing model, encoded provider/model identifiers, saved-but-refresh-failed response; prove correct resource and that retry does not invent a custom definition. Source `src/server/management/model-routes.ts:447`; GUI receipt comment `gui/src/pages/Models.tsx:647`. |
+| First: set-R02 routing profile writes | Create `{mode:"create",id,profile}`; update `{mode:"update",id,expectedRevision,profile}`; remove query id with explicit destructive intent. Profile file is bounded/validated domain input. Exact fields: alias,candidates[{provider,model}],require{minContextWindow,minQuotaHeadroom,tools,imageInput,structuredOutput,reasoningEffort,serviceTier,localOnly,remoteAllowed,encryptedCodexTasks},optimize{latency,health,cost,quota},limits{maxEstimatedCostUsd,onUnknownCost},unknownEvidence,compatibility{requiredSuites,minStatus,maxEvidenceAgeMs,unknownEvidence,degradedEvidence}. | Create collision; update missing/stale revision leaves existing profile unchanged; delete dependent/in-use refusal; optional branch removal semantics and unknown field validation. Sources `src/cli/route-policy.ts:85`, `src/server/management/routing-profile-routes.ts:233`, `gui/src/routing-profile-editor-data.ts:280`. |
+| First: set-P07 provider snapshot/apply | Snapshot projected `{defaultProvider,providers}` only; apply exact `{baseline,next}` through PUT providers. No port/system/secret dump; strip derived GUI fields same as DTO projection. Never auto-retry stale baseline with fresh state because that would authorize overwriting intervening edits. | Stale-baseline 409; invalid endpoint/row; removal with dependencies; baseline read includes only permitted projection; no write after preview refusal; confirmed saved/catalog receipt. Sources `gui/src/hooks/useJsonConfigEditor.ts:16`, `src/server/management/provider-routes.ts:1055`. |
+| First: set-A07/set-A06/set-P15/set-P19 account gaps | Credit policy: `{id,creditsAfterLimit:boolean}` OR `{all:boolean}`; reject ambiguous selector/all. Codex override `{id,threshold:number\|null}` with inherit -> null; pool default remains `{threshold}`. Unified pool PATCH/PUT fields provider,enabled,strategy,stickyLimit,autoSwitchThreshold,quotaWindow; quotaWindow enum five-hour/weekly/max-utilization is Anthropic-only. Anthropic grants command is GET-only; consume session gate remains excluded. | One versus all, on/off, explicit main identity, unknown id, inheritance versus zero, invalid quota window, unsupported provider fields, no secret output, consume refusal without user GUI session. Sources `src/codex/auth-api/routes.ts:122`, `src/codex/auth-api/routes.ts:310`, `src/server/management/oauth-account-routes.ts:559`, `src/server/management/anthropic-reset-grant-routes.ts:131`. |
+| Next: set-M10 picker order | `models order` owns pickerOrder and pickerOrderMode only; never changes featured models or force. Manual ordered ids + null mode; default/reset -> empty/default order + null mode; alphabetical/provider/most-used computes order using current visible identities, preserves supported model namespaces, sends matching mode. Most-used refuses incomplete usage evidence rather than sorting a partial sample. | Capture exact body; roster/force unchanged; native/routed id collision; duplicate/invisible ids; null/default reset; most-used incomplete usage refusal. Sources `src/server/management/subagent-model-routes.ts:74`, `gui/src/pages/Models.tsx:1904`. |
+| Next: set-S03 injection field; set-S04/set-M13 existing v2 contract | Extend injection set only with syncCodexSubagentDefaults boolean and normalized reread. Existing `ocx v2 mode`, `keep-native-v1`, `threads`, `mode-hint TEXT` and `mode-hint --clear` already implement the other GUI effects locally. Add strict JSON parsing/receipt support in the existing family if required; advisory acknowledgment remains a parent product-contract decision. No duplicate agent-mode writer. | Injection effort normalization; local/live same-home/target and sync outcome; structured v2 output without swallowed trailing flags; hint blank rejection/null reset; advisory not auto-acknowledged. Sources `src/cli/agent.ts:125`, `src/cli/v2.ts:109`, `src/cli/v2.ts:144`, `src/cli/v2.ts:177`, `src/cli/v2.ts:191`, `src/cli/v2.ts:220`, `src/server/management/agent-settings-routes.ts:415`. |
+| Next: set-C02 combo fields | Typed targets input includes ordered provider/model, optional weight, reasoningEfforts, modelProfile. Add imageInput auto/disabled and reasoningEffortMode strict/adaptive. Do not confuse defaultEffortMode with reasoningEffortMode. Explicit nativeAlias false needed to disable while alias remains native-shaped. Existing renameFrom/JEV null selector/timeouts retained. | Metadata survives unrelated edit and target reorder; auto/strict explicitly revert disabled/adaptive; remove a target override intentionally; nativeAlias on/off; JEV provider/model mutual exclusion and null resets; rename retains dependencies. Sources `src/cli/combo.ts:32`, `src/cli/combo.ts:137`, `gui/src/combo-workspace-data.ts:507`. |
+| Next: set-P03/set-P04/set-P17/set-M08 provider fields | HTTP override null clears. Provider contextWindow null clears; modelContextWindows merges touched keys with per-key null deletes. requestPacing is whole-object replacement, not server merge: flags must either read/merge existing provider state or require a full typed pacing file; `--clear` sends requestPacing:null. fastEnabled boolean has separate meaning from global fastRows. | Exact PATCH body includes only intended fields; per-model pacing edit retains other rules; clear removes object; context null removes only selected key; Cursor protocol validation; provider fast toggle doesn't affect global fastRows. Sources `src/server/management/provider-routes.ts:479`, `src/server/management/provider-routes.ts:493`, `src/server/management/provider-routes.ts:513`, `src/server/management/provider-routes.ts:542`. |
+| Parent/sibling merge: set-A09/set-A11/set-A16/set-M11/set-C05 | Settings flags write showCodexCredits,codexAccountPickerEnabled,codexMainAccountHardLock,ultraFastTier,fastRows. Quota activation writes `{codexQuotaAutoRefresh:{id,window:"fiveHour"\|"weekly",enabled}}`; do not confuse this enum with pool quotaWindow. Combo stats reads `usage?jev=1&comboId=I&range=7d\|30d\|all`, not ordinary usage model filter. | Independent field bodies; true/false defaults; unavailable activation window returns 409; JEV-specific response/partial data; no duplicate ownership with operations sibling. Sources `src/server/management/config-routes.ts:564`, `src/cli/system-command.ts:124`, `src/cli/observe.ts:164`. |
+| Requires behavior proof: set-P02/set-P05/set-M06/P10 local-live portions | Preserve working offline/local commands; do not claim live management equivalence from local save alone. Add with --json currently returns before --sync; remove default differs from GUI and local dependency checks differ. Custom add/remove invoke live sync helper but need same-target fixture before deciding on a transport rewrite. | Isolated local config + fake live transport: same target selected, save/sync order and outcome, default deletion semantics, dependent combo refusal, JSON mode still applies requested sync, logout live cache convergence. Sources `src/cli/provider.ts:64`, `src/cli/provider.ts:279`, `src/cli/provider.ts:345`, `src/cli/models.ts:185`, `src/cli/dispatch.ts:425`. |
+
+## Explicit scope limits and exclusions
+
+- No changes to the settings GUI/API inventory in this pass. Corrections above are recorded here so parent can reconcile without concurrent edits.
+- Prompt mutation rows set-A13/set-A14 remain EXCLUDED; Anthropic grant consumption within set-P19 is EXCLUDED even though its read is an implementation gap. Human consent is not a flag to silently auto-answer.
+- Browser tabs/dialogs/search/collapse/clipboard/SSE invalidation are presentation mechanisms, not missing command operations. Protocol pair filtering over existing subject data belongs to this category; preserving unknown/trust evidence is still required.
+- Existing API protocol commands are complete, context-cap shapes are complete, model-settings full null reset is complete, and native-main reauth is complete. Do not duplicate these under new nouns.
+- Lab local projection readers are implementation, not missing HTTP calls. A future remote-target contract needs separate evidence; current source inventory doesn't authorize that expansion.
+- Main owns final command naming, roadmap/FSM, fixtures and implementation. This report recommends syntax but does not execute commands or claim runtime parity.
+
+## Final correction audit and bounded remaining unknowns
+
+Root-family cross-check followed `src/cli/registry.ts:277` provider, `:311` account, `:333` alias, `:337` models/model, `:369` combo/route, `:380` effort, `:393` agent, `:404` inspect, `:413` usage/observe, `:575` v2, plus already-inspected system/settings, API protocols and Lab handlers. Targeted checks of v2, effort, access and config-command found no dedicated writer for the remaining claimed pacing/fast/picker/credit/quota-activation fields. Generic config remains explicitly outside task-parity proof. No whole-CLI rescan was performed.
+
+Bounded unknowns:
+
+- **set-M13 / set-S04:** all operations exist under v2. Compare local config/CODEX_HOME, catalog sync result, existing shared transition/hint helpers, and GUI live receipt/advisory semantics with isolated fixtures. Missing JSON/strict argument contract and unindexed mode-hint are confirmed; whether GUI advisory acknowledgment should become a CLI field is a parent decision.
+- **set-M06:** custom model CRUD fields exist; local add/remove and live edit need isolated same-target save/convergence proof. Missing JSON on add/remove is confirmed; no claim of absent CRUD.
+- **Partial uncertainty within known-gap rows:** provider add/remove/set-default and OAuth local logout need live equivalence proof; their concrete missing fields or behavior differences are documented separately, so UNKNOWN transport does not erase those gaps.
+- **Sibling boundaries:** quota activation/settings and JEV stats recommendations need deduplication with operations/client-settings owner. Their GUI mounts and missing dedicated field parsers were inspected; ownership, not existence, is unresolved.
+
+Final matrix totals: 67 rows = 16 COMPLETE + 22 DISCOVERY_ONLY + 24 IMPLEMENTATION_GAP + 2 EXCLUDED + 3 UNKNOWN. Source-only evidence; no tests or live operations executed.
+
+## Dashboard-mounted panels added in roadmap reconciliation
+
+| ID | Task and source | Current CLI coverage | Work phase |
+|---|---|---|---|
+| set-S06 | Memory extraction/consolidation model settings; `gui/src/pages/dashboard-overview-panels.tsx`, `gui/src/components/MemoryModelsPanel.tsx` | No dedicated live block writer; the existing memory family does not prove these GUI fields | wp5 |
+| set-S07 | Compaction route model, effort, triggers and source scope; `gui/src/pages/dashboard-overview-panels.tsx`, `gui/src/components/CompactionRoutingPanel.tsx` | No dedicated live block writer | wp5 |
+
+These two source-backed implementation gaps supplement the historical 67-row settings inventory above. The task ledger is authoritative for current cross-domain aliases and completion evidence.
diff --git a/devlog/_plan/261003_cli_gui_parity/005_operations_coverage.md b/devlog/_plan/261003_cli_gui_parity/005_operations_coverage.md
new file mode 100644
index 00000000000..26480746bc1
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/005_operations_coverage.md
@@ -0,0 +1,158 @@
+# Operational task parity join
+
+Source-only bounded second pass, 2026-10-03. Root: `the task checkout`. Joined the operations GUI/API inventory with the CLI source inventory and targeted handlers only. No runtime requests, credentials, source edits, tests or Git writes. Source presence is not runtime proof. Main owns command conventions and the implementation roadmap.
+
+Status meanings: COMPLETE = existing domain command or documented sequence supports the task; DISCOVERY_ONLY = effect exists but task/leaf/route metadata is incomplete; IMPLEMENTATION_GAP = a necessary action/field/workflow cannot be expressed by the inspected handler; EXCLUDED = current deliberate session/consent or pure presentation boundary; UNKNOWN = target scope or sibling ownership prevents an honest equivalence claim. COMPLETE does not certify global JSON error/exit contracts; those are shared CLI audit work. New syntax below is a recommendation, never a claim of an existing command.
+
+## Highest-value confirmed gaps
+
+- `ops-K03`: key rename. Existing `access key set` only scopes providers/models (`src/cli/access.ts:168`); no name operand, despite sharing the GUI PATCH endpoint. Recommend `ocx access key rename <id-or-name> <name> [--json]`.
+- `ops-T07`: cleanup threshold and reduction target. Policy parser (`src/cli/storage.ts:162`) has enabled/percent/mode/schedule only; GUI submits trigger.archivedBytesOver and target.reduceToBytes (`gui/src/pages/Storage.tsx:709`). Recommend mutually exclusive `--remove-oldest-percent` / `--reduce-to-bytes`, plus `--archived-bytes-over`.
+- `ops-D15`, `ops-D16`: sidecar fields. Actual parser (`src/cli/agent.ts:256`) omits webSearch.streamRoutedModelOutput and vision.timeoutMs, both writable in GUI. Recommend `agent sidecar web --stream-routed-output on|off`, `agent sidecar vision --timeout-ms N`.
+- `ops-O13`, `ops-I15`, `ops-I16`: timeline and Cursor reads are advertised by capabilities but absent from real handlers. Recommend `companion timeline` and `integration native cursor status|local-installer` (read-only).
+- `ops-I10`/profile part of `ops-I13`, `ops-R01`/`ops-R07`: declared journal retirement and Hub read debt. Preserve registry owners; executor-local remote-workspace status is not Hub status.
+- `ops-I06`, `ops-L07`: Droid reasoning-default payload and link force-removal option absent from existing writer/parser.
+- `ops-K08`: `access test` exists, but does not accept the newly created data key and uses runtimeRequest management headers (`src/cli/access.ts:255`, `src/cli/runtime-api.ts:142`). It is not proof that the chosen key works. Recommend a separate `--api-key-stdin` path with explicit inference authorization and no secret echo; do not use the admin-header helper for data-plane key verification.
+
+Local/native counterexamples: startup repair invokes `ocx service repair`; shim repair invokes `ocx codex-shim install` (`src/server/startup-action-control.ts:109`); Windows tray writes invoke `ocx tray <action> --json` (`src/server/windows-tray-control.ts:9`). None is a missing effect merely because an HTTP route has no literal CLI caller.
+
+## Per-task join
+
+Commands below omit the common `ocx` prefix for readability. Each ID maps to the operations inventory. Proposed flags are recommendations, not existing features.
+
+| Task and GUI anchor | Status | Existing commands | Missing field/workflow or recommended syntax | Targeted proof |
+|---|---|---|---|---|
+| **ops-D01** — Read live health/version/uptime and provider overview; `gui/src/pages/dashboard-core-poll.ts:275` | UNKNOWN | status --json; health --json; system status --json | Liveness exists; system status bundles settings/startup/memory, not system/health. Exact remote version/uptime/spendLedger projection requires target comparison. Proposed system status extension only if needed. | src/cli/system-command.ts:35; src/cli/dispatch.ts:787; src/cli/index.ts:1677 |
+| **ops-D02** — Read model catalog and 30d usage; `gui/src/pages/dashboard-core-poll.ts:135`, `:142` | DISCOVERY_ONLY | models live --json; usage --range 30d --json | Catalog and usage reads exist; publish model live leaf. Provider/account projection details remain sibling-owned. | src/cli/models-runtime.ts:73; src/cli/observe.ts:209 |
+| **ops-D03** — Read runtime/client preferences; `gui/src/pages/dashboard-core-poll.ts:218` | DISCOVERY_ONLY | system settings --json | No field gap; complete settings leaf metadata. | src/cli/system-command.ts:123 |
+| **ops-D04** — Set Codex autostart; `gui/src/pages/use-dashboard-data.ts:753`, `:777` | DISCOVERY_ONLY | system settings --auto-start on/off --json | Boolean supported; no new setter needed. | src/cli/system-command.ts:127 |
+| **ops-D05** — Set Desktop authless / client compaction; `gui/src/pages/use-dashboard-data.ts:768`, `:778` | DISCOVERY_ONLY | system settings --desktop-authless on/off --client-compaction on/off --json; then system sync --json | Stored/effective/file-apply result exists. GUI auto-sync is expressible as sequence; document partial apply and explicit sync. | src/cli/system-command.ts:61; src/cli/system-command.ts:139; src/cli/system-command.ts:206 |
+| **ops-D06** — Sync client catalogs/configuration; `gui/src/pages/use-dashboard-data.ts:790`, `:796` | DISCOVERY_ONLY | system sync --json | Same POST/result; register leaf. Connected machine uses S05, not shared-hub target. | src/cli/system-command.ts:206 |
+| **ops-D07** — Read project-config warnings; `gui/src/pages/dashboard-core-poll.ts:126` | DISCOVERY_ONLY | system diagnostics --json | No missing query; register child metadata. | src/cli/system-command.ts:204 |
+| **ops-D08** — Read startup protection; `gui/src/pages/dashboard-core-poll.ts:104`; `gui/src/pages/Startup.tsx:140` | DISCOVERY_ONLY | system startup health/status --json | Startup protection readable. Existing hidden __startup-health is not a proposed public task. | src/cli/system-command.ts:150; src/cli/dispatch.ts:760 |
+| **ops-D09** — Read memory/storage pressure and active turns; `gui/src/components/MemoryObservabilityCard.tsx:243` | DISCOVERY_ONLY | observe memory --json; memory --json | Full metrics/active-turn payload readable; register diagnostic leaf. | src/cli/observe.ts:280 |
+| **ops-D10** — Drain and restart proxy; `gui/src/components/MemoryObservabilityCard.tsx:359` | COMPLETE | restart | Live drain/replacement exists; fallback ensure if stopped. Do not replace with ordinary stop/start. JSON/error-contract work is shared audit. | src/cli/dispatch.ts:777; src/cli/system-restart-client.ts:1 |
+| **ops-D11** — Check latest/preview package update; `gui/src/pages/use-dashboard-data.ts:824` | DISCOVERY_ONLY | system update check --channel latest/preview --json | Both GUI channels supported; register leaf. | src/cli/system-command.ts:166 |
+| **ops-D12** — Run package update, optionally restart; `gui/src/pages/use-dashboard-data.ts:909` | DISCOVERY_ONLY | system update run --channel latest/preview --restart on/off --yes --json | All payload fields exist. Accepted job is not completed update; use D13. | src/cli/system-command.ts:184 |
+| **ops-D13** — Observe update job; `gui/src/pages/use-dashboard-data.ts:493` | DISCOVERY_ONLY | system update status JOB-ID --json | Polling can be composed; --wait is optional convenience, not absent backend capability. | src/cli/system-command.ts:169 |
+| **ops-D14** — Desktop-shell update navigation; `gui/src/pages/use-dashboard-data.ts:6` (openDesktopUpdatePage dependency), `gui/src/pages/dashboard-overview-sections.tsx:220` | EXCLUDED | Desktop update UI panel | Shell navigation/native updater display differs from package job; preserve desktop-internal snapshot exemption. | src/server/management/route-registry.ts:376; gui/src/pages/use-dashboard-data.ts:6 |
+| **ops-D15** — Web search sidecar off/on/model/stream; `gui/src/pages/dashboard-overview-sections.tsx:585`, `:606`; save `gui/src/pages/use-dashboard-data.ts:563` | IMPLEMENTATION_GAP | agent sidecar web --model ID --backend BACKEND --enabled on/off --json | Missing webSearch.streamRoutedModelOutput. Recommend --stream-routed-output on/off. Selecting a model after Off needs --enabled on, already supported. | src/cli/agent.ts:256; gui/src/pages/dashboard-overview-sections.tsx:606 |
+| **ops-D16** — Vision sidecar off/on/model/reasoning/limits/timeout; `gui/src/pages/dashboard-overview-sections.tsx:467`, `:480`, `:628`, `:648` | IMPLEMENTATION_GAP | agent sidecar vision --model ID --backend BACKEND --reasoning LEVEL --max-descriptions N --enabled on/off --json | Missing vision.timeoutMs. Recommend --timeout-ms N; preserve backend/model coherence and sibling fields. | src/cli/agent.ts:256; gui/src/pages/dashboard-overview-sections.tsx:480 |
+| **ops-D17** — Shadow-call interception toggle/model; `gui/src/pages/dashboard-overview-sections.tsx:716`, `:728`; save `gui/src/pages/use-dashboard-data.ts:610` | DISCOVERY_ONLY | models shadow status --json; models shadow set MODEL --enabled on/off --json | Enabled/model supported, '-' clears model. Publish leaf, no new writer. | src/cli/models-runtime.ts:546 |
+| **ops-D18** — Multi-agent mode/advisory, injection/guidance/defaults, effort caps; `gui/src/pages/use-dashboard-data.ts:640`, `:679`, `:727`; `gui/src/pages/dashboard-overview-sections.tsx:78`, `:103` | UNKNOWN | v2; agent injection/effort/subagents/roles | Sibling owns multi-agent/advisory/injection/compaction/memory-model field join. No duplicate completeness claim here. | gui/src/pages/use-dashboard-data.ts:640; gui/src/pages/use-dashboard-data.ts:679; src/cli/agent.ts:48 |
+| **ops-S01** — Install service / repair service / install shim; `gui/src/pages/Startup.tsx:290`, `:294` | COMPLETE | service install; service repair; codex-shim install; system startup install-service/install-shim --json | GUI launcher directly maps to these commands. system startup has no --repair, but direct service repair is equivalent; shim repair is install. | src/server/startup-action-control.ts:109; src/service/cli.ts:233; src/cli/dispatch.ts:679 |
+| **ops-S02** — Windows tray status; `gui/src/pages/Startup.tsx:176` | COMPLETE | tray status --json; inspect windows-tray --json | Local command and management read both exist; platform support reported. | src/tray/windows.ts:784; src/cli/inspect.ts:213 |
+| **ops-S03** — Windows tray install/start/stop/uninstall; `gui/src/pages/Startup.tsx:268` | COMPLETE | tray install/start/stop/uninstall --json | GUI backend invokes this actual CLI; no missing route-effect gap. | src/server/windows-tray-control.ts:9; src/tray/windows.ts:784 |
+| **ops-S04** — Connected-machine shim status/install/repair/uninstall; `gui/src/pages/Startup.tsx:97`, `:104` | COMPLETE | codex-shim status/install/uninstall | Same diagnose/install/uninstall functions; repair maps to install in machine owner. Must run on client machine, not hub. Structured status is output enhancement only. | src/client/machine-api.ts:113; src/client/machine-api.ts:125; src/cli/dispatch.ts:695 |
+| **ops-S05** — Read connected-machine selected clients / sync them; `gui/src/pages/Integrations.tsx:62`, `:72` | UNKNOWN | sync on connected machine | Mutation exists; selectedClients+journalOwner display and machine-target receipt need client-state owner join. Keep domain sync syntax, not generic machine HTTP. | src/client/machine-api.ts:87; src/cli/dispatch.ts:508 |
+| **ops-C01** — Read Claude Code effective state/model choices; `gui/src/pages/ClaudeCode.tsx:88` | COMPLETE | claude config status --json | Same effective-state GET and fields. | src/cli/integrations.ts:64 |
+| **ops-C02** — Enable/disable Claude connection immediately; `gui/src/pages/ClaudeCode.tsx:166`; `gui/src/pages/use-claude-connection.ts:2` | COMPLETE | integration native claude on/off --json | Same immediate native mutation; local config edit alone would not count. | src/cli/inspect.ts:85; src/cli/inspect.ts:113 |
+| **ops-C03** — Enable/disable CLI first-party proxy environment; `gui/src/pages/ClaudeCode.tsx:178` | COMPLETE | claude config set --first-party on/off --json | cliFirstParty sent alone; shared-proxy-retained warning preserved. | src/cli/integrations.ts:78; src/cli/integrations.ts:121 |
+| **ops-C04** — Save Code behavior/auth/env/model mappings/helpers; `gui/src/pages/ClaudeCode.tsx:217` | COMPLETE | claude config set --enabled --auth-mode --system-env --fast-mode --auto-context --compact-window --inject-agents --small-fast-model --model-map --web-model --web-backend --vision-model --vision-backend | All GUI fields supported. Restore helper inheritance with both --web-model - --web-backend - (vision analog); backend removes empty override. Use typed values shown by handler usage. | src/cli/integrations.ts:16; src/cli/integrations.ts:78; src/server/management/agent-settings-routes.ts:1642 |
+| **ops-C05** — Start configured Claude intercept; `gui/src/components/ClaudeInterceptStart.tsx:18` | COMPLETE | claude intercept start --json | Exact configured-proxy start exists; no trust-install bypass. | src/cli/integrations.ts:372 |
+| **ops-C06** — Read Desktop editable profile/catalog and applied health; `gui/src/pages/ClaudeDesktop.tsx:270`, `:354` | UNKNOWN | claude desktop status --json; claude desktop show --json | status is live, show builds local desired profile; connected GUI editor reads hub. Consider explicit runtime-scope profile read after main target design. | src/cli/claude-desktop.ts:742; src/cli/claude-desktop.ts:751; src/cli/claude-desktop.ts:790 |
+| **ops-C07** — Edit Desktop assignment family/alias/default and save; `gui/src/pages/ClaudeDesktop.tsx:24`, `:418`, `:806`, `:826` | UNKNOWN | claude desktop move ROUTE FAMILY [--default]; default FAMILY ROUTE-or-none; import FILE | Local assignments/defaults/import exist; hub desired-profile target differs. Alias can be imported as profile JSON. Parent owns live-vs-local contract, no generic config workaround. | src/cli/claude-desktop.ts:806; src/cli/claude-desktop.ts:815; src/cli/claude-desktop.ts:833 |
+| **ops-C08** — Save then apply Desktop first-party/gateway; `gui/src/pages/ClaudeDesktop.tsx:433` | COMPLETE | claude desktop apply --first-party; apply --gateway | Mode-aware apply exists and preserves applied-marker warning. import --apply is gateway-only; separate apply selects first-party. Local/client paths guarded. | src/cli/claude-desktop.ts:676; src/cli/claude-desktop.ts:393; src/cli/claude-desktop.ts:479 |
+| **ops-C09** — Bind/unbind native picker ID to route; `gui/src/components/ClaudeFirstPartyBindings.tsx:59` | COMPLETE | claude desktop bind PICKER-ID ROUTE; unbind PICKER-ID | Exact set/remove live binding payloads exist. | src/cli/claude-desktop.ts:766 |
+| **ops-C10** — Enable/disable Desktop picker proxy; `gui/src/components/ClaudeDesktopPicker.tsx:97` | COMPLETE | claude desktop picker status/on/off | GET/PUT and trust workflow exist. Preserve trusted-local and interactive requirements; no raw persist/trust bypass. | src/cli/claude-desktop.ts:554; src/cli/claude-desktop.ts:623; src/cli/claude-desktop.ts:746 |
+| **ops-C11** — Export Desktop profile JSON; `gui/src/pages/ClaudeDesktop.tsx:468` | COMPLETE | claude desktop export PATH-or-dash | Artifact export exists. GUI can export unsaved draft; CLI has no GUI draft and exports persisted local profile. Draft-state visualization is not absent export capability. | src/cli/claude-desktop.ts:824; gui/src/pages/ClaudeDesktop.tsx:468 |
+| **ops-C12** — Import Desktop profile JSON; `gui/src/pages/ClaudeDesktop.tsx:480` | UNKNOWN | claude desktop import FILE [--apply] | CLI local import immediately persists; GUI imports draft then saves selected runtime. Connected/hub target ambiguity remains C07; reuse parser rather than inventing second one. | src/cli/claude-desktop.ts:833; gui/src/pages/ClaudeDesktop.tsx:480 |
+| **ops-G01** — Read Grok fence/catalog/status; `gui/src/pages/Grok.tsx:81` | DISCOVERY_ONLY | grok status/show --json | Same status implemented; incomplete route/leaf declaration in CLI inventory. | src/cli/integrations.ts:142 |
+| **ops-G02** — Save included/excluded Grok model selection; `gui/src/pages/Grok.tsx:151` | DISCOVERY_ONLY | grok set/include/exclude CSV --json; grok clear --json | Excluded-list replacement/add/remove/clear supported; publish precise grammar. | src/cli/integrations.ts:160 |
+| **ops-G03** — Save and apply Grok fence; `gui/src/pages/Grok.tsx:171` | DISCOVERY_ONLY | grok set CSV --json; then grok apply --json | Save then apply expressible; changed/skippedReason preserved in JSON. Register leaves; no duplicated writer. | src/cli/integrations.ts:153; src/cli/integrations.ts:174 |
+| **ops-I01** — List native integration desired/observed state; `gui/src/pages/integrations/native-api.ts:144`; overview `IntegrationsOverview.tsx:605` | COMPLETE | integration native list --json | Same desired/observed four-client collection. | src/cli/inspect.ts:90 |
+| **ops-I02** — Toggle native Grok / Codex / Claude Desktop; `gui/src/pages/integrations/native-api.ts:155`; overview `IntegrationsOverview.tsx:604` | COMPLETE | integration native grok/codex/claude-desktop on/off --json | All three mutations exist; backend disable refusal remains authoritative. | src/cli/inspect.ts:49; src/cli/inspect.ts:113 |
+| **ops-I03** — List file-client state / inspect one; `gui/src/pages/integrations/integration-api.ts:435`, `:441` | DISCOVERY_ONLY | integration client status/list/show [--client ID] --json | Collection and one-client reads exist. Capability focuses Aside; declare ordinary client routes too. | src/cli/integrations.ts:232; src/cli/integrations.ts:49 |
+| **ops-I04** — Preview apply / overwrite / disable; `gui/src/pages/integrations/FileIntegrationPage.tsx:219`; `integration-api.ts:475` | EXCLUDED | Existing apply/disable at I05 | Interactive-preview exemption intentional. Optional future integration client preview --client ID --operation apply/overwrite/disable requires parent policy change and bound follow-up mutation. | src/server/management/route-registry.ts:232; src/cli/integrations.ts:299 |
+| **ops-I05** — Apply / overwrite conflicting config / disable owned block; `gui/src/pages/integrations/FileIntegrationPage.tsx:251`; `integration-api.ts:512` | DISCOVERY_ONLY | integration client enable/disable --client ID [--overwrite-conflict] --json | Effects exist; no planFingerprint under current interactive-preview exemption. Preserve explicit overwrite waiver. Droid map is separate I06 gap. | src/cli/integrations.ts:299; src/cli/integrations.ts:319 |
+| **ops-I06** — Set/clear per-model Droid reasoning defaults; `gui/src/pages/integrations/DroidReasoningDefaultsPanel.tsx:27`, `:38` | IMPLEMENTATION_GAP | integration client enable --client droid | No droidReasoningDefaults input. Recommend repeatable --reasoning-default MODEL=EFFORT and explicit --clear-reasoning-defaults; if preview adopted, same map must bind apply. | src/cli/integrations.ts:299; gui/src/pages/integrations/integration-api.ts:483; gui/src/pages/integrations/integration-api.ts:520 |
+| **ops-I07** — Read rollback journal; `gui/src/pages/integrations/integration-api.ts:454` | DISCOVERY_ONLY | integration client history/journal [--client ID] --json | Journal read exists; publish non-Aside route/leaf and retain snapshot-expired status. | src/cli/integrations.ts:258 |
+| **ops-I08** — Preview rollback, including drift-confirmed retry; `gui/src/pages/integrations/RestoreDialog.tsx:143`; `integration-api.ts:496` | EXCLUDED | integration client restore --op ID [--confirm-drift] | Preview intentionally exempt. Optional restore --op ID --preview needs explicit bound confirmation policy, not new generic POST access. | src/server/management/route-registry.ts:233; src/cli/integrations.ts:278 |
+| **ops-I09** — Restore rollback snapshot; `gui/src/pages/integrations/RestoreDialog.tsx:191`; `integration-api.ts:543` | DISCOVERY_ONLY | integration client restore --op ID [--confirm-drift] --json | Restore and drift waiver implemented. Fingerprint not current scripted contract; don't label entire rollback missing. | src/cli/integrations.ts:278 |
+| **ops-I10** — Retire older rollback entry/snapshot; `gui/src/pages/integrations/FileIntegrationPage.tsx:446`; overview `IntegrationsOverview.tsx:851`; `integration-api.ts:571` | IMPLEMENTATION_GAP | history and restore only | No journal DELETE task. Recommend integration client history remove --op ID --yes --json; preserve newest-row refusal and snapshotRemoved:false receipt. | src/cli/integrations.ts:258; src/cli/integrations.ts:299; src/server/management/route-registry.ts:230 |
+| **ops-I11** — Disable all eligible file integrations; `gui/src/pages/integrations/IntegrationsOverview.tsx:443`, `:460`, `:512` | COMPLETE | Repeat integration client disable --client ID for explicit set | Existing sequential commands can disable the explicitly selected eligible set; this is a real write workflow, not presentation. GUI confirmation previews remain exempt. No atomic bulk endpoint; do not silently introduce wildcard/default-all scope. | gui/src/pages/integrations/IntegrationsOverview.tsx:443; gui/src/pages/integrations/IntegrationsOverview.tsx:512 |
+| **ops-I12** — List Aside profiles / read one / toggle selected profile; `gui/src/pages/integrations/AsideProfilesPage.tsx:54`, `:89`, `:116`; `integration-api.ts:424` | COMPLETE | integration client status/enable/disable --client aside --profile N --json | Canonical per-profile selection exists; omitted profile intentionally aggregate. Preview remains I04 exemption. | src/cli/integrations.ts:40; src/cli/integrations.ts:49; src/cli/integrations.ts:230 |
+| **ops-I13** — Aside profile rollback list/preview/restore/retire; `gui/src/pages/integrations/integration-api.ts:465`, `:503`, `:550`, `:585` | IMPLEMENTATION_GAP | history --client aside --profile N; restore --client aside --profile N --op ID [--confirm-drift] | Only retirement absent; preview exempt. Recommend history remove --client aside --profile N --op ID --yes --json with profile-response binding. | src/cli/integrations.ts:258; src/cli/integrations.ts:278; src/server/management/route-registry.ts:191 |
+| **ops-I14** — Refresh all server-selected Aside profiles; `gui/src/pages/integrations/aside-profile-api.ts:38` | UNKNOWN | sync reaches refreshAsideProfilesThroughServer | Refresh effect exists, but broad sync also synchronizes catalogs/other clients. Parent decide if broader scope is acceptable or add integration client sync --client aside reusing helper. | src/cli/aside-profiles.ts:9; src/cli/aside-profiles.ts:69; src/cli/dispatch.ts:526 |
+| **ops-I15** — Inspect Cursor installed builds/gateway/last-seen state; `gui/src/pages/integrations/CursorIntegrationPage.tsx:113`; `cursor-api.ts:34` | IMPLEMENTATION_GAP | integration native list/on/off; Cursor advertised only | Actual allowlist has no Cursor. Recommend integration native cursor status --json; read-only build/gateway/last-seen status. | src/cli/inspect.ts:49; src/cli/inspect.ts:99; src/cli/capabilities.ts:1015 |
+| **ops-I16** — Check advertised Cursor local installer; `gui/src/pages/integrations/CursorIntegrationPage.tsx:81`; `cursor-api.ts:59` | IMPLEMENTATION_GAP | No Cursor installer-read command | Recommend integration native cursor local-installer --json. Explicit update-channel query only; URL/version output never triggers install. | src/cli/inspect.ts:85; gui/src/pages/integrations/cursor-api.ts:59; src/server/management/cursor-integration-routes.ts:152 |
+| **ops-O01** — Read debug flags/env/runtime overrides; `gui/src/pages/Debug.tsx:48` | DISCOVERY_ONLY | observe debug --json; debug SCOPE status | Flags/env/overrides readable; publish scope grammar. | src/cli/observe.ts:281; src/cli/debug.ts:144 |
+| **ops-O02** — Toggle provider/usage/injection/Claude inbound capture; `gui/src/pages/Debug.tsx:180`, `:210` | DISCOVERY_ONLY | debug provider/usage/injection/claude on/off | All four toggles supported. Legacy JSON mutation output absence is shared machine-output work, not missing action. | src/cli/debug.ts:144; src/cli/debug.ts:150 |
+| **ops-O03** — Reset all capture overrides to env; `gui/src/pages/Debug.tsx:213` | COMPLETE | debug provider reset; debug usage reset; debug injection reset; debug claude reset | Four commands reach same final reset state; GUI atomic reset:true has no one-shot alias. Atomic reset-all optional unless parent contract requires it. | src/cli/debug.ts:163; gui/src/pages/Debug.tsx:213 |
+| **ops-O04** — Read/follow provider, usage, injection debug buffers; `gui/src/pages/Debug.tsx:97`, `:115` | IMPLEMENTATION_GAP | debug provider logs -f; debug usage logs -f; observe injection --json | Injection snapshot exists, continuous follow/after cursor does not. debug injection logs refuses. Recommend observe injection --follow --jsonl with bounded cursor polling. | src/cli/debug.ts:171; src/cli/observe.ts:283; gui/src/pages/Debug.tsx:115; gui/src/pages/Debug.tsx:168 |
+| **ops-O05** — Read Claude inbound metadata captures; `gui/src/pages/Debug.tsx:65` | DISCOVERY_ONLY | observe claude-inbound --json | Complete metadata snapshot read. Expose leaf with honest limit semantics. | src/cli/observe.ts:282 |
+| **ops-O06** — Read/retry/incrementally poll request log; `gui/src/pages/Logs.tsx:614` | COMPLETE | logs --limit 2000 --json; logs --follow --jsonl | Read/follow exists. GUI cursor amendments differ from CLI new-ID dedupe; an in-flight-to-terminal fixture is needed before claiming identical update visibility. No new API necessary. | src/cli/observe.ts:79; src/cli/observe.ts:100; gui/src/pages/Logs.tsx:614 |
+| **ops-O07** — Filter log snapshot by surface/model/provider/status/time/speed/interception/conversation/protocol; `gui/src/pages/Logs.tsx:728`; `gui/src/pages/logs-filter.ts:16`, `:103` | EXCLUDED | logs has provider/model/status/conversation/account filters | GUI local speed/intercept/protocol/time/view projections are presentation, not missing management mutations. More CLI read filters optional product choice. | gui/src/pages/Logs.tsx:728; gui/src/pages/logs-filter.ts:16; src/cli/observe.ts:85 |
+| **ops-O08** — Read usage by preset/custom window, surface and local-machine attribution; `gui/src/pages/Usage.tsx:1110` | UNKNOWN | usage --range --surface --since --until --provider --model --json | Custom bounds exist. Connected CLI uses own-key Hub report; GUI chooses machine vs whole-Hub via apiKeyId. Need target/principal join before proposing --scope machine/hub; don't infer missing from absent apiKeyId flag alone. | src/cli/observe.ts:164; src/cli/observe.ts:188; gui/src/pages/Usage.tsx:1110 |
+| **ops-O09** — Model text search, expand rows, tab and chart display; `gui/src/pages/Usage.tsx:1093`; chart components | EXCLUDED | No CLI task needed | Local search, expansion, tabs/graph styling. Server bounds remain O08. | gui/src/pages/Usage.tsx:1093 |
+| **ops-O10** — Read companion preferences/presence; `gui/src/pages/usage-companion-panel.tsx:215`; Tray `gui/src/pages/Tray.tsx:100` | COMPLETE | companion show --json | Settings/defaults/presence/corrupt payload available. | src/cli/companion.ts:13 |
+| **ops-O11** — Persist companion model/provider visibility and chart/menu appearance; `gui/src/pages/usage-companion-panel.tsx:302`, `:503` | COMPLETE | companion set KEY=VALUE ... --json | Domain settings map covers all GUI fields including JSON arrays, models=null and booleans. This is not generic API passthrough. | src/cli/companion.ts:20; gui/src/pages/usage-companion-utils.ts:9 |
+| **ops-O12** — Restore companion defaults (including corrupt-state recovery); `gui/src/pages/usage-companion-panel.tsx:350` | COMPLETE | companion reset --json | Same reset:true and corrupt-settings recovery. | src/cli/companion.ts:36 |
+| **ops-O13** — Read usage timeline for companion/chart/tray; `gui/src/pages/usage-companion-panel.tsx:257`; `gui/src/pages/Tray.tsx:118` | IMPLEMENTATION_GAP | companion show/set/reset only | Recommend companion timeline --hours N --bucket-minutes N --metric total/input/output/cached --aggregation sum/average/max --grouping model/modelAccount [--model ID repeated] [--hide-provider ID repeated] --json. Preserve truncated/missingMeasurements. | src/cli/companion.ts:46; gui/src/pages/usage-companion-utils.ts:52; src/server/management/usage-timeline-routes.ts:11 |
+| **ops-O14** — Open companion view in system browser; `gui/src/pages/usage-companion-panel.tsx:367` | EXCLUDED | No standalone operator equivalent required | Browser navigation is declared session-only. No forged dashboard principal/open-url passthrough. | src/server/management/route-registry.ts:268; src/server/management/companion-routes.ts:30 |
+| **ops-O15** — Tray refresh totals/accounts/quota; `gui/src/pages/Tray.tsx:79`, `:86`, `:104`; `gui/src/pages/tray-data.ts:27` | UNKNOWN | usage/companion show plus account read families | Sibling certifies account/quota fields; Tray display alone is excluded. | gui/src/pages/Tray.tsx:79; gui/src/pages/tray-data.ts:27 |
+| **ops-O16** — Tray switch current account/key; `gui/src/pages/Tray.tsx:39`; `gui/src/pages/tray-data.ts:36` | UNKNOWN | Account selection families in inventory-cli.md | Sibling owns exact Codex/OAuth/provider-key switch join. Prefer account command, not Tray-specific verb. | gui/src/pages/Tray.tsx:39; gui/src/pages/tray-data.ts:36 |
+| **ops-T01** — Inspect storage sizes/categories/Log Guard state; `gui/src/pages/Storage.tsx:1358` | COMPLETE | storage report --json | Same live storage/log-guard scan payload. | src/cli/storage.ts:233; src/server/management/storage-log-guard-routes.ts:216 |
+| **ops-T02** — Preview oldest archived-session cleanup percentage; `gui/src/pages/Storage.tsx:177` | COMPLETE | storage cleanup --percent N --json | Default preview emits digest/candidates; registry mutates declaration doesn't change handler's preview semantics. | src/cli/storage.ts:73; src/cli/storage.ts:88 |
+| **ops-T03** — Quarantine / permanently delete previewed archives; `gui/src/pages/Storage.tsx:201` | COMPLETE | storage cleanup --percent N --mode quarantine/permanent --yes --json | Fresh preview then exact returned digest. Standalone prior preview is recomputed, not reused; immutable preview receipt UX is optional, guard preserved. | src/cli/storage.ts:88; src/cli/storage.ts:105 |
+| **ops-T04** — List quarantine batches; `gui/src/pages/Storage.tsx:392` | COMPLETE | storage trash list --json | Full quarantine batch list. | src/cli/storage.ts:117 |
+| **ops-T05** — Restore a quarantine batch; `gui/src/pages/Storage.tsx:431` | COMPLETE | storage trash restore ENTRY-ID --yes --json | ID mutation with explicit confirmation exists; partial outcomes preserved in JSON/error. | src/cli/storage.ts:126; src/cli/storage.ts:141 |
+| **ops-T06** — Read policy/job; `gui/src/pages/Storage.tsx:672`, `:865` | COMPLETE | storage policy show --json | Policy/job state available. | src/cli/storage.ts:153 |
+| **ops-T07** — Enable/disable recurring cleanup / save threshold, target, schedule, mode; `gui/src/pages/Storage.tsx:709`, `:738` | IMPLEMENTATION_GAP | storage policy set --enabled --percent --mode --schedule --json | Missing trigger.archivedBytesOver and target.reduceToBytes. Recommend --archived-bytes-over BYTES plus exclusive --reduce-to-bytes BYTES / --remove-oldest-percent N, retaining --percent alias if chosen. Never implicitly enable. | src/cli/storage.ts:162; gui/src/pages/Storage.tsx:709 |
+| **ops-T08** — Run cleanup policy now; `gui/src/pages/Storage.tsx:790`, `:809` | COMPLETE | storage policy set EXISTING-FIELDS; policy run --yes --json; policy show --json | Run + poll expressible; disabled stays disabled. T07 separately limits draft fields. Optional --wait must preserve skipped/deferred/failed terminal outcomes. | src/cli/storage.ts:207; src/cli/storage.ts:214; src/cli/storage.ts:153 |
+| **ops-T09** — Inspect log protection fresh; `gui/src/components/storage-workspace/StorageWorkspace.tsx:515` | COMPLETE | storage codex-logs status --json; observe storage codex-logs status --json | Existing alias dispatch reaches actual read. | src/cli/storage.ts:223; src/cli/observe.ts:245 |
+| **ops-T10** — Protect logs compat / quiet; `gui/src/components/storage-workspace/StorageWorkspace.tsx:251`, `:261`, `:460` | COMPLETE | storage codex-logs protect --mode compat/quiet --json | Exact protection payload. | src/cli/observe.ts:248 |
+| **ops-T11** — Remove log protection / repair protection / compact logs; `gui/src/components/storage-workspace/StorageWorkspace.tsx:440`, `:463` | COMPLETE | storage codex-logs unprotect/repair/compact --json | Dynamic suffix dispatch reaches all three; no missing literal-route gap. | src/cli/observe.ts:258 |
+| **ops-K01** — List access keys/usage/pending rotations, endpoints, auth matrix, API/audio surfaces; `gui/src/pages/ApiKeys.tsx:155` | COMPLETE | access key list --json; access endpoints --json | Full list JSON includes auth/audio/usage/pending rotation; endpoint-only helper projects fewer fields. Discover existing complete payload, don't add duplicate read. | src/cli/access.ts:136; src/cli/access.ts:241 |
+| **ops-K02** — Create key with name; `gui/src/pages/ApiKeys.tsx:268` | COMPLETE | access key create NAME --json | Secret returned once. Preserve operating-skill restriction on agent receipt of raw keys; no credentials generated here. | src/cli/access.ts:143 |
+| **ops-K03** — Rename key; `gui/src/pages/ApiKeys.tsx:327` | IMPLEMENTATION_GAP | access key set edits scopes only | Recommend access key rename ID-or-NAME NEW-NAME --json; reuse unambiguous findKeyRow, PATCH only {id,name}, leave scope unchanged. | src/cli/access.ts:168; src/cli/access.ts:109; gui/src/pages/ApiKeys.tsx:327 |
+| **ops-K04** — Revoke key; `gui/src/pages/ApiKeys.tsx:302` | COMPLETE | access key remove ID --yes --json | Explicit ID revocation and confirmation exist. | src/cli/access.ts:224 |
+| **ops-K05** — Start rotation; `gui/src/pages/ApiKeys.tsx:349` | COMPLETE | access key rotate ID --json | Start returns key and rotationId. Actual grammar is rotate ID, not rotate start ID. | src/cli/access.ts:197 |
+| **ops-K06** — Commit rotation / abort rotation; `gui/src/pages/ApiKeys.tsx:371` | COMPLETE | access key rotate commit ID ROTATION-ID --json; rotate abort ID ROTATION-ID --json | Both methods and fields supported. | src/cli/access.ts:198; src/cli/access.ts:217 |
+| **ops-K07** — Read public external-model catalog; `gui/src/pages/ApiKeys.tsx:192` | DISCOVERY_ONLY | access models --json | Public /v1/models read exists, distinct from management models live; publish leaf. | src/cli/access.ts:246; src/cli/access.ts:279 |
+| **ops-K08** — Test newly created key on Responses / Chat / Messages for selected model; `gui/src/pages/ApiKeys.tsx:443`, `:456` | IMPLEMENTATION_GAP | access test MODEL --protocol responses/chat/messages --json | Existing inference test has no selected-key input and uses management headers; cannot prove newly created key works. Recommend --api-key-stdin with no secret echo/argv/env and explicit inference authorization. Ping text/token limit differences alone not the gap. | src/cli/access.ts:255; src/cli/runtime-api.ts:142; gui/src/pages/ApiKeys.tsx:456 |
+| **ops-K09** — Read generated client configuration / copy snippet; `gui/src/components/apikeys-workspace/ClientConfigRow.tsx:53` | COMPLETE | inspect client-config --client ID --json | Same generated config envelope. Export artifact and integration apply remain separate tasks. | src/cli/inspect.ts:157 |
+| **ops-K10** — Toggle public Messages API; `gui/src/pages/api-surface-cards.tsx:52` | COMPLETE | api policy --messages on/off --json | Exact messagesEnabled field; backend also updates legacy Claude inbound on closing. | src/cli/api-protocols.ts:152; src/server/management/protocol-settings-patch.ts:132 |
+| **ops-K11** — Preview model's protocol path/features; `gui/src/components/protocols/ProtocolPlanPanel.tsx` → `gui/src/protocol-api.ts:91` | COMPLETE | api explain --model ID --inbound responses/chat/messages --feature FEATURE [repeated] --json | Same preview/features/policy revision. Never call preview a successful live model probe. | src/cli/api-protocols.ts:130 |
+| **ops-K12** — Dictation file upload and cancel; `gui/src/components/apikeys-workspace/AudioApiPanel.tsx:2`; `gui/src/audio-api-client.ts:13` | UNKNOWN | No scoped audio CLI identified in supplied CLI inventory | Real data-plane upload, parent inclusion decision. If included: access audio transcribe FILE --model ID --api-key-stdin --json, bounded upload/cancel. Do not silently create new audio product. | gui/src/audio-api-client.ts:13; src/server/index/serve-options.ts:1594 |
+| **ops-K13** — Live voice connect/disconnect probe; `gui/src/audio-api-client.ts:88` | UNKNOWN | No scoped live-audio probe identified in supplied CLI inventory | Parent inclusion decision. If included: access audio live-check --model ID --api-key-stdin --json with timeout/session.close; connection-only, no microphone/delegation execution claim. | gui/src/audio-api-client.ts:88; src/server/live.ts:348 |
+| **ops-K14** — Download generated client configuration; `gui/src/components/apikeys-workspace/ClientConfigPanel.tsx:78` | COMPLETE | export --client ID --out PATH [--force] [--json] | Existing artifact task, explicit destination/non-clobber default. Native format default; --json requests JSON representation, not apply. | src/cli/export-command.ts:158; gui/src/components/apikeys-workspace/ClientConfigPanel.tsx:78 |
+| **ops-R01** — Hub devices/runtime availability/session status; `gui/src/pages/RemoteWorkspace.tsx:93` | IMPLEMENTATION_GAP | remote-workspace status is executor-local | Recommend remote-workspace hub status --json aggregating devices/runtimes/sessions via runtime management auth/target, not executor file store. | src/cli/remote-workspace.ts:80; src/server/management/route-registry.ts:397; src/server/management/remote-workspace-routes.ts:61 |
+| **ops-R02** — Create device enrollment code; `gui/src/pages/RemoteWorkspace.tsx:172` | EXCLUDED | remote-workspace pair consumes enrollment code | Grant creation is paired-dashboard consent; no --yes CLI minting/session impersonation. Preserve create-vs-consume roles. | src/server/management/route-registry.ts:400; src/server/management/remote-workspace-routes.ts:12 |
+| **ops-R03** — Start hub model session on selected remote root; `gui/src/pages/RemoteWorkspace.tsx:184` | EXCLUDED | No CLI proposed | Hub-authenticated model session start and access mode remain dashboard consent. | src/server/management/route-registry.ts:401 |
+| **ops-R04** — Submit prompt to bound session; `gui/src/pages/RemoteWorkspace.tsx:208` | EXCLUDED | No CLI proposed | Prompt may execute remote tools; do not use task parity to bypass session principal. | src/server/management/route-registry.ts:402 |
+| **ops-R05** — Stop session; `gui/src/pages/RemoteWorkspace.tsx:243` | EXCLUDED | No CLI proposed | Interactive remote session stop remains paired-session action. | src/server/management/route-registry.ts:404 |
+| **ops-R06** — Revoke device and stop its sessions; `gui/src/pages/RemoteWorkspace.tsx:256` | EXCLUDED | No CLI proposed | Device identity revocation and related session stops remain paired-session actions. | src/server/management/route-registry.ts:403 |
+| **ops-R07** — Read individual Hub runtimes/sessions endpoints | IMPLEMENTATION_GAP | No Hub runtime/session list command | Recommend remote-workspace hub runtimes --json and hub sessions --json. Declared debt; GUI currently reads both through aggregate R01 rather than distinct buttons. | src/server/management/route-registry.ts:398; src/server/management/route-registry.ts:399 |
+| **ops-L01** — Read link topology/status; `gui/src/pages/RemoteLink.tsx:186` | COMPLETE | link status --json | Admin topology DTO intentionally omits dashboard joinAvailable; do not forge consent field to match presentation. | src/cli/link.ts:256; src/server/management/link-routes.ts:580 |
+| **ops-L02** — Discover/rescan SSH aliases; `gui/src/pages/RemoteLink.tsx:262` | EXCLUDED | No CLI proposed | SSH candidates discovery remains dashboard-session-only contract. | src/server/management/route-registry.ts:389 |
+| **ops-L03** — Probe host key; `gui/src/pages/RemoteLink.tsx:282` | EXCLUDED | No CLI proposed | Host-key probe is interactive fingerprint-consent flow. | src/server/management/route-registry.ts:390 |
+| **ops-L04** — Accept shown fingerprint and validate remote OCX; `gui/src/pages/RemoteLink.tsx:298` | EXCLUDED | No CLI proposed | Persisting fingerprint requires observed pending key and consent; never auto-confirm from metadata. | src/server/management/route-registry.ts:391 |
+| **ops-L05** — Home adds child; `gui/src/pages/RemoteLink.tsx:313` | EXCLUDED | link issue is existing lower-level admin primitive | Not equivalent to Home-adds-Child transaction; retain session-only boundary rather than generic wrapper. | src/server/management/route-registry.ts:393; src/cli/link.ts:234 |
+| **ops-L06** — Standalone child joins Home and restarts; `gui/src/pages/RemoteLink.tsx:333` | EXCLUDED | No CLI proposed | Child join/restart consent contract unchanged; issue/port primitives alone not workflow parity. | src/server/management/route-registry.ts:392 |
+| **ops-L07** — Disconnect link / force-remove after remote cleanup failure; `gui/src/pages/RemoteLink.tsx:371`, `:422` | IMPLEMENTATION_GAP | link revoke --link-id ID --json | Normal revoke exists; parser rejects --force and sends no body. Recommend --force --yes for explicit forced local removal with residual remote-cleanup warning, normal defaults unchanged. | src/cli/link.ts:260; src/server/management/link-routes.ts:510; gui/src/pages/RemoteLink.tsx:371 |
+
+## Declared debt and intentional exclusions
+
+- Journal retirement: registry `src/server/management/route-registry.ts:230`, `:188`, `:191`; owner `260904_priority65_closeout WP7`, tracked source `devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md`. Global/profile mutations are GUI reachable; aggregate Aside DELETE is declared but current helper does not use that aggregate spelling.
+- Remote Workspace Hub reads: registry `src/server/management/route-registry.ts:397`, `:398`, `:399`; owner `remote-workspace-cli-followup`, tracked source `docs-site/src/content/docs/reference/management-api.md:214`. Existing executor-local status is not a replacement.
+- Interactive plans: registry `src/server/management/route-registry.ts:232`, `:233`, `:190`. Excluded under current declared contract, although useful plan-first CLI workflows are a product option. Do not omit planFingerprint if adopting bound confirmation; stale plans require renewed confirmation.
+- Link GUI admissions and Remote Workspace writes retain registry session-only classifications. GitHub star POST must never gain an agent action (`src/server/management/route-registry.ts:380`); current inspect star is read-only (`src/cli/inspect.ts:192`).
+- App session logout (`src/server/management/route-registry.ts:372`), desktop update snapshot (`:376`), companion browser navigation (`:268`), old Aside aliases (`:180`, `:181`), disabled config PUT (`:223`) and storage test streams (`:261`, `:263`) do not create new operational CLI debt.
+
+## Proof to request during implementation
+
+No code or tests were executed in this pass. Use isolated HTTP fixtures with RuntimeApiDeps (`src/cli/runtime-api.ts:136`) and controlled homes; shared auth helpers otherwise read normal user state. Assert parser → exact method/path/body/query → projection/exit status; no live proxy or real keys needed.
+
+1. Timeline/Cursor/Hub reads: route/flag encoding, read-only behavior, malformed response and meaningful empty state. Validate actual handler dispatch, not only capabilities route membership.
+2. Rename: PATCH exactly id/name, preserve provider/model scopes, reject ambiguous selector without write. Sidecar additions: partial patch retains siblings, booleans and timeout bounds preserved.
+3. Cleanup fields: mutually exclusive target forms and trigger threshold; absent enabled preserved. Droid defaults: same submitted map reaches chosen client/profile and any plan binding.
+4. Journal retire: global and Aside-profile route, newest-row 409, missing-row 404, snapshotRemoved:false visible. Link force: explicit confirmation, only requested force:true body, residual remote cleanup stays visible.
+5. Key test: fake sentinel secret from controlled stdin, dedicated data header only, no management token injection, no secret in stdout/stderr/errors. Prove selected-key rejection cannot pass via loopback bypass.
+6. Follow injection: after cursor advances, empty poll/no duplicates, interruption, malformed/error response. Log row amendment visibility is separately unresolved in O06.
+7. Target-dependent UNKNOWNs: verify Desktop local versus Hub profile, connected usage own-key versus Hub scope, machine sync selected-client projection, and narrow Aside-only refresh before promoting to COMPLETE or a gap.
+
+Parent boundary: command spelling/flags above are proposals. Main owns final convention, receipt/error/exit design, authorization policy and roadmap sequencing. Audio probe inclusion and sibling account/subagent joins remain explicitly UNKNOWN. No generic API passthrough or generic config editing is counted as parity.
+
+
+Static artifact receipt: 109 unique ops task rows; all 344 explicit source file/line anchors resolve; every operations-inventory ID has exactly one join row; Markdown column counts checked. Status totals: UNKNOWN=12, DISCOVERY_ONLY=23, COMPLETE=43, EXCLUDED=16, IMPLEMENTATION_GAP=15. No application execution or runtime success inferred.
diff --git a/devlog/_plan/261003_cli_gui_parity/006_target_contracts.md b/devlog/_plan/261003_cli_gui_parity/006_target_contracts.md
new file mode 100644
index 00000000000..d45b836874e
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/006_target_contracts.md
@@ -0,0 +1,219 @@
+# wp0 target crux: local versus live settings workflows
+
+2026-10-03, source-only bounded decision record. Resolves set-M06/M13/S04, provider P02/P05 and logout P10 for roadmap selection. No tracked files, prior artifacts, user config, credentials, proxy, upstream or tests were changed/run. Source establishes the transport/side-effect differences sufficiently to choose implementation; it does not establish runtime parity. Existing isolated tests were inspected, not executed.
+
+## Concrete roadmap choice
+
+**Retain existing roots and local behavior. Add an explicit `--live` option to the existing commands for exact management-target GUI behavior, with structured receipts. Do not auto-fallback between local and live; do not create `agent mode` or a generic API passthrough.** The only new API surface work needed by these cruxes is CLI transport/options, not new server routes. `--json` selects output, never target.
+
+| Tasks | Accepted implementation choice for roadmap | Smallest before → after |
+|---|---|---|
+| set-M06 | Existing `models add/remove` gain `--live --json`; keep existing local add/remove default and existing live `models edit`. Add proper local JSON save/sync disposition as output enhancement. | Before: add/remove modify local config and optionally perform broad Codex sync, emit prose; edit is live. After: explicit live add/remove use the same server custom-model handlers as GUI, return its identity and catalog receipt; local remains available and is labeled local. |
+| set-M13 | Reuse `v2 status`, `mode`, `keep-native-v1`, `threads`, plus existing on/off. Add `--live --json` and explicit advisory acknowledgment for live mode changes. Keep current local implementation and add strict JSON output/argument parsing. | Before: local files/Codex helpers, mode/keep sync, prose, no advisory-version write; trailing flags are not systematically rejected. After: live option operates on the selected management target and returns server post-write state/advisory/catalogRefresh; no-live remains existing local functionality. |
+| set-S04 | Reuse `v2 mode-hint TEXT` and `v2 mode-hint --clear`; route through the same narrow v2 live option when requested. Local set/null writer already exists and needs only machine output/discovery. | Before: shared local hint helper already implements set/null and rejects blanks. After: no duplicate hint implementation; optional live path receives the target runtime's capability/refusal and receipt. |
+| set-P02 | Existing `provider add` gains explicit live path; preserve offline default. Add missing typed fields (responses path/auth mode) to the same domain parser. | Before: local seed/save, `--json` bypasses `--sync`; target runtime not the mutation owner. After: live preset read/POST provider and receipt belong to one resolved server; local `--sync --json` actually executes the requested sync and reports disposition. |
+| set-P05 | Existing `provider remove` and `provider set-default` gain `--live`. Existing `provider edit --enabled` already uses management and does not need a second endpoint. | Before: local remove refuses current default and only deletes local provider/custom-model config; live GUI can reassign default and removes OAuth account set/caps. After: explicit live operations use exactly those server validations and effects, with destructive confirmation for removal. |
+| set-P10 logout | Existing top-level `logout P` gains `--live --json`; keep local logout default and its current removed/not-found semantics. | Before: shared auth-store removal occurs locally, but live caches/login state aren't cleared by this CLI branch. After: explicit live logout invokes `/api/oauth/logout?provider=P` and returns its actual success receipt; no unproved `removed:true` claim. |
+
+“Accepted” here is the explorer's concrete recommended lock for the parent's roadmap, not a claim that implementation or user-state mutation has occurred. Main retains naming/final phase authority. This choice is intentionally narrower than changing all existing command defaults.
+
+## Why machine-output enhancement alone is insufficient for live GUI parity
+
+### Shared persistence is not a shared target or completion receipt
+
+- `saveConfig` writes local config under a mutation lock and bumps a generation; its body is persistence, not a management request: `src/config.ts:370`.
+- Server handlers mutate their retained live `config`, use preserving/rebase-aware persistence (`src/config/live-reconcile.ts:443`), and perform explicit live-store/cache/convergence work. Their GET config returns that retained config: `src/server/management/config-routes.ts:306`.
+- `runtimeBaseUrl` selects the identity-checked live proxy or rejects absent/client-role management; it does not promise the dashboard's remote-relay target: `src/cli/runtime-api.ts:70`. Therefore `--live` means **the existing CLI management target**, not arbitrary GUI apiBase/remote equivalence. No new raw `--url` capability is proposed.
+- Resolve base URL **once per multi-request workflow**, then pass a pinned `RuntimeApiDeps.baseUrl` to every request. Otherwise list/resolve/delete can re-resolve the listener between calls (`src/cli/runtime-api.ts:136`). This is a per-command target fix, not a new transport framework.
+- Do not invoke the local handler before deciding `--live`; a refused or unreachable live request must never have already saved local config. Do not fall back after a transport error, timeout, 409 or partial receipt.
+
+### set-M06: custom model CRUD
+
+Local add writes `config.customModels`, calls `saveConfig`, then `syncCustomModelsIfLive`: `src/cli/models.ts:197`, `src/cli/models.ts:250`. Local remove follows the same save/sync family: `src/cli/models.ts:280`, `src/cli/models.ts:331`. The sync helper catches failures and emits warning text rather than returning a durable save/catalog receipt (`src/cli/models.ts:185`).
+
+`syncModelsToCodex(port, config=loadConfig())` checks local desired integration/service-home authority; depending on path it can refresh catalog/cache **and inject config** (`src/codex/sync.ts:99`, `src/codex/sync.ts:209`, `src/codex/sync.ts:293`). It is not equivalent to the GUI handler's catalog-only convergence.
+
+Live POST builds the same core `OcxCustomModel` fields, validates provider/collisions and mutates retained live config, then returns 201 `{...entry,catalogRefresh}` (`src/server/management/model-routes.ts:961`, `src/server/management/model-routes.ts:1001`). Live DELETE accepts UUID, updates live config, and returns `{ok:true,catalogRefresh}` (`src/server/management/model-routes.ts:1079`). Management convergence is bound to retained config and catalog-only scope (`src/server/management-api.ts:255`, `src/codex/management-convergence.ts:144`).
+
+**Resolved:** CRUD effects already exist, but a new live option is needed to claim the same target/management receipt. JSON-only changes cannot supply that. Existing local source remains a supported offline workflow.
+
+Exact live grammar:
+
+- `ocx models add P M [existing metadata flags] --live --json` → POST `/api/custom-models` with provider/modelId and provided displayName/contextWindow/inputModalities/reasoningEfforts/defaultReasoningEffort. No local `loadConfig()` preflight; target server validates provider.
+- `ocx models remove UUID --yes --live --json` → DELETE `/api/custom-models/UUID`.
+- Retain `P/M` removal convenience by GET `/api/custom-models` on the **same pinned target**, resolve exact-or-refuse using existing collision/slug rules, then DELETE UUID. Never resolve from local `customModels` before live deletion.
+- Preserve empty reasoning `[]` versus inherit omission/null. Existing live edit parser already handles clear variants (`src/cli/models-runtime.ts:195`).
+
+### set-M13 / set-S04: reuse v2
+
+Existing implementations are substantive, not aliases: `src/cli/v2.ts:109` status, `:144` hint set/clear, `:177` thread transition, `:191` mode save/sync, `:220` keep-native save/sync. Dispatch wires the root directly (`src/cli/dispatch.ts:539`).
+
+Server and local paths use the same `transitionMultiAgentV2` and `setMultiAgentModeHintText` helpers (`src/server/management/agent-settings-routes.ts:391`, `:415`, `:464`). Source establishes **local scalar/transition equivalence**, including blank hint rejection and null clear. It does not establish equivalence of surrounding target and convergence behavior: CLI sync is broad and local, while server returns post-write readings plus `catalogRefresh` (`src/server/management/agent-settings-routes.ts:484`). Local hint and threads paths do not issue management requests.
+
+Advisory semantics are now resolved: the GUI modal records explicit choice (`gui/src/pages/Models.tsx:2026`); the server validates acknowledgment is boolean and only true writes the advisory version **after** mode has landed (`src/server/management/agent-settings-routes.ts:372`, `:444`). There is no session-only principal gate or mandatory pre-write acknowledgment in `/api/v2`. Do not invent such a security guard. Do not auto-acknowledge just because a script requests a mode.
+
+Exact live grammar/mapping:
+
+| Existing root + proposed option | Exact live operation |
+|---|---|
+| `v2 status --live --json` | GET `/api/v2` |
+| `v2 mode v1\|default\|v2 --live [--acknowledge-surface-advisory] --json` | PUT `{multiAgentMode, multiAgentSurfaceAdvisoryAcknowledged?:true}`; omission preserves unacknowledged state; default remains string `default`, not null. |
+| `v2 keep-native-v1 on\|off --live --json` | PUT `{keepNativeChatGptOnV1:boolean}` |
+| `v2 threads N --live --json` | PUT `{maxConcurrentThreadsPerSession:N}`, integer >=1 |
+| `v2 mode-hint TEXT --live --json` | PUT `{multiAgentModeHintText:TEXT}`; nonblank raw text retained. |
+| `v2 mode-hint --clear --live --json` | PUT `{multiAgentModeHintText:null}` |
+| `v2 on\|off --live --json` | PUT `{enabled:boolean}`; retain server hybrid conflict refusal. |
+
+Use the same strict parser for local/live flags. `--json` must be consumed and unknown/trailing args rejected before local writers run; it must not be silently ignored. Local JSON must report `transport:local`, actual helper changed/no-op state and sync outcome without manufacturing server advisory or catalog receipts. Live JSON should preserve server returned state/warnings/catalogRefresh. If catalog refresh fails after persistence, do not claim rollback.
+
+### set-P02 / set-P05: provider lifecycle
+
+Local add parser seeds from registry/custom flags and writes local config (`src/cli/provider.ts:144`, `:192`, `:212`, `:274`). JSON mode returns before `--sync` handling (`:279`, `:292`). Existing test explicitly pins `needsSync:true` despite its misleading title (`tests/cli/cli-provider.test.ts:680`); fixing JSON-plus-sync is a deliberate behavior correction, not an untested assumption.
+
+Live POST validates the candidate, mutates retained live provider config, reconciles state stores, clears model cache and returns `{success:true,name,catalogRefresh}` (`src/server/management/provider-routes.ts:1372`, `:1400`). Live default selection rejects a disabled row and persists/reconciles a standalone `{setDefault:true}` (`:1459`). Local set-default only verifies existence before saving (`src/cli/provider.ts:439`, `:459`).
+
+Live remove is materially broader: default replacement and combo dependency checks (`src/server/management/provider-routes.ts:1824`), custom-model removal, cap cleanup, OAuth account-set removal, live-store reconciliation, model-cache invalidation and catalog receipt (`:1854`). Local remove refuses current default and deletes provider/custom-model config (`src/cli/provider.ts:345`, `:355`, `:364`). **Do not silently substitute the live delete in the existing unflagged command**: it would add credential deletion/default reassignment side effects.
+
+Exact live grammar:
+
+- `provider add P [existing fields plus --auth-mode MODE --responses-path PATH] --live --json` → POST `/api/providers` `{name,provider,setDefault?}`. Fetch target presets for canonical reserved provider seed; no local config mutation. Retain explicit `--force` overwrite intent. Existing POST is upsert: a read-before-post duplicate guard is not atomic create-only CAS; document that limit, do not claim a nonexistent server precondition.
+- `provider set-default P --live --json` → standalone PATCH `{setDefault:true}`.
+- `provider remove P --live --yes --json` → DELETE providers by name; server performs atomic default selection within its mutation path. Include removed credential scope in help/confirmation, and preserve dependentShadowIntercept/droppedCustomModels/catalogRefresh fields.
+- `provider edit P --enabled on|off --json` is already management-backed; no new implementation needed for enable/disable. Do not overload adding `--live` on this already-live branch into a new transport selector.
+- Reject `--live --sync`: live lifecycle endpoint already converges the catalog; broad local sync is a different action. Fix local `--sync --json` by running the requested local sync and reporting its actual returned/refused/skipped status; do not force it to `needsSync:false`.
+
+### set-P10: logout
+
+Both paths call `removeCredential`, which removes the active credential and chooses the next usable account under the store mutation lock (`src/oauth/store.ts:1093`). Local dispatch preserves useful removed/not-found semantics (`src/cli/dispatch.ts:425`). Store mutation persists and publishes account selection (`src/oauth/store.ts:828`), but publication uses in-process listeners (`src/lib/account-selection-events.ts:25`, `:36`); it is not a management cache-cleanup receipt.
+
+Server logout additionally clears login state, model/inflight catalog caches, provider/account quota caches and Devin direct caches (`src/server/management/oauth-account-routes.ts:373`). This is a concrete source difference; no timing probe against user state is needed to choose the live path.
+
+- `ocx logout P --live --json` → POST `/api/oauth/logout?provider=P`; no local credential read/remove first.
+- Keep local `logout P --json` existing exit 4/removed receipt semantics. The live route returns `{success:true}` and is effectively idempotent for a missing credential; do not synthesize `removed:true` or local exit 4 from it. No server response extension is necessary for minimum GUI parity.
+- Do not broaden login work in this crux. Browser preference/initial-login variants remain the separate P10/P20 parser gap already recorded.
+
+## Exact file plan
+
+New filenames below were checked absent at inspection time. Source files named existing must be extended narrowly; no shared transport framework is needed.
+
+| Work slice | Existing files to edit | New files proposed | Smallest responsibilities |
+|---|---|---|---|
+| Custom live add/remove + local receipts | `src/cli/models.ts`, `src/cli/models-runtime-subcommands.ts` only if dispatcher contract needs it | `src/cli/models-custom-runtime.ts`; `tests/cli/cli-models-custom-runtime.test.ts` | Route explicit live add/remove before local config access; typed bodies/same-target ID resolution; JSON local outcome separation. Reuse existing `src/cli/models-runtime.ts` edit implementation. |
+| v2 target/JSON contract | `src/cli/v2.ts`, `src/cli/dispatch.ts`, `src/cli/registry.ts` | `src/cli/v2-runtime.ts`; `tests/cli/cli-v2-runtime.test.ts` | Parse common flags once, reuse existing local functions, route live operations to `/api/v2`, project truthful receipts. Add mode-hint to root help. No agent.ts mode taxonomy. |
+| Provider live lifecycle | `src/cli/provider.ts`, `src/cli/provider-runtime.ts` only for shared parser/dispatch seam, `src/cli/registry.ts` | `src/cli/provider-lifecycle-runtime.ts`; `tests/cli/cli-provider-lifecycle-runtime.test.ts` | Explicit live add/default/remove; fetch target preset; reject local sync combination; preserve offline behavior. Existing local JSON-plus-sync test updated in `tests/cli/cli-provider.test.ts`. |
+| Live logout | `src/cli/dispatch.ts`, `src/cli/registry.ts` | `src/cli/logout-command.ts`; `tests/cli/cli-logout-runtime.test.ts` | Extract or wrap existing validated root grammar, add explicit live branch and injectable RuntimeApiDeps, keep local behavior. No new account logout alias required. |
+| Discovery/contracts/docs | `src/cli/capabilities.ts`; `skills/ocx/references/03_recipes.md`; `structure/runtime.md`, `structure/config.md`, `structure/clients/chatgpt-desktop.md`, `structure/ops/docs-and-release.md` as affected by each slice | none required for transport | Declare existing/new leaf options and distinguish local/live. Main owns canonical output/error envelope work. |
+| Test layout | `scripts/test-layout/layout.json`, `tests/fixtures/test-layout-expected.json` | none | Register every new test file in both maps. Avoid enlarging ratcheted `tests/codex-integration/codex-v2-gate.test.ts`; use focused new siblings. |
+
+Verified ownership mapping is `structure/INDEX.md:124`: CLI is jointly owned by runtime/config/client-integration/desktop/docs-and-release documents. The file plan names the applicable existing owners; main should update only the affected invariants, following their nested instructions. No server source change is necessary to expose these existing routes. A future atomic create-only provider contract or richer logout removed receipt would be separate scope, not hidden in this roadmap.
+
+## Source evidence versus required implementation proof
+
+Existing test source confirms that these are real existing features, not names inferred from declarations: `tests/codex-integration/codex-v2-gate.test.ts:1641` covers hint write/clear; `:1661` covers nonblank whitespace preservation and missing/blank rejection; `:1742` covers v1/v2 thread-slot transitions. `tests/cli/cli-provider.test.ts:473` deliberately expects local default-provider removal refusal; `:680` pins JSON skip-sync. None were run in this pass.
+
+The plan can be locked from source: a local sync and an HTTP catalog-only receipt have demonstrably different code paths; local versus live logout cleanup is explicit; provider removal side effects differ. Running those existing local tests would not establish cross-target live parity, so no scratch probe or test run was warranted merely to choose the roadmap.
+
+Implementation gate (for main, not claimed complete):
+
+1. Fake `RuntimeApiDeps.fetchImpl/baseUrl/findLiveProxy`, temporary home/auth context only, with every unexpected network call failing. Test target pinning across read/resolve/write and no local read/write on live refusal.
+2. Custom add/remove: exact metadata/null/empty variants; UUID versus slug collision; created entry and saved/catalog failure receipts; unflagged local path unchanged.
+3. V2: all seven live mappings above; strict unknown/trailing args before any mutation; hint null/blank cases; advisory omitted by default and true only by explicit flag; mixed live target local home remains untouched; server partial persistence/convergence outcome stays visible.
+4. Provider: live default delete reassigns through one DELETE, offline continues to refuse; dependent combos and credential cleanup are handler authority; missing provider and disabled default errors; live --sync rejected; local --sync --json calls sync and keeps truthful skipped/refused outcomes. Never assert read-before-create is CAS.
+5. Logout: live request never calls local removeCredential; server receipt preserved; local removed/not-found JSON/exit unchanged; mocked handler tests demonstrate cleanup functions invoked, not upstream calls.
+6. Use existing nonzero/error-body machinery; parent-owned machine-envelope work must retain RuntimeApiError.body on partial/failed-convergence responses. A tool exit or 2xx alone is not proof that persisted state and live/client state all converged.
+
+Remaining bounded limits: the existing CLI management target intentionally refuses a connected-client listener; dashboard remote relay equivalence is outside this change. Runtime receipts, target isolation and failure behavior remain to be tested during implementation. The transport choice and file plan no longer depend on an unexplained UNKNOWN.
+
+
+# Operational parity target decisions
+
+2026-10-03, bounded explorer follow-up. Repository root `the task checkout`; all source anchors are relative to that root. This artifact supersedes the target-dependent labels in `gaps-operations.md` for the rows below. Main owns roadmap and command conventions. No tracked files, live proxy, real credentials, upstream traffic, branch state or orchestration were touched. Two focused test files ran with pure/mock inputs; details below distinguish executed proof from inspected tests.
+
+## Decisions ready for the roadmap
+
+| Existing task IDs | Resolved classification | Decision and smallest command choice | Implementation boundary / source evidence |
+|---|---|---|---|
+| ops-C06 | IMPLEMENTATION_GAP for live desired-profile read; existing live status COMPLETE | Keep `ocx claude desktop show --json` explicitly local. Add **`ocx claude desktop profile show --json`**, a fixed GET `/api/claude-desktop` on the existing local management runtime. Invoke it on the hub host to inspect the Hub profile. Existing `desktop status --json` remains the applied-health read. | GUI receives sharedBase at `gui/src/App.tsx:584`, GET at `gui/src/pages/ClaudeDesktop.tsx:270`. CLI show builds disk state at `src/cli/claude-desktop.ts:790`; status uses live route at `:751`. `src/cli/runtime-api.ts:71` rejects a client-role listener and does not automatically authenticate to a Hub. Do not introduce `--url`, remote admin-token storage, or automatic relay login. |
+| ops-C07, ops-C12 | IMPLEMENTATION_GAP for live save/import; existing local editing retained | Add **`ocx claude desktop profile import FILE --json`**, validates one bounded DesktopProfile and sends `{profile}` to PUT `/api/claude-desktop`. It saves only; use existing `ocx claude desktop apply --gateway` or `--first-party` separately. Existing local `move`, `default`, `import`, `export` retain current meaning. A file-based profile operation is a domain operation, not generic config editing. | `src/cli/claude-desktop.ts:203` writes only persisted local profile under connection/CAS guards; it does not adopt live server config. GUI PUT `src/server/management/agent-settings-routes.ts:907` validates routes, protects applied markers, performs conflict check and explicitly adopts live config at `:959`. Existing connected import --apply is refused at `src/cli/claude-desktop.ts:736`. New handler: small `src/cli/claude-desktop-profile.ts`, dispatch through existing `src/cli/claude-desktop.ts:676`; do not grow a second parser or change auth. |
+| ops-S05 | COMPLETE for actual GUI task; discovery/output clarification only | **`ocx status --json`** already exposes `connection.selectedClients`; **`ocx sync`** on connected machine already runs the same domain sync. No `machine clients` command or journal inspection task is needed to match this GUI. | `gui/src/pages/Integrations.tsx:64` consumes only selectedClients; renders at `:137`. Although API also returns journalOwner/shim, that page does not display them. CLI projection `src/cli/status.ts:918` includes selectedClients. GUI machine API calls deps.sync (`src/client/machine-api.ts:94`), whose default is syncConnectedClient at `:30`; connected CLI uses syncConnectedClient at `src/cli/dispatch.ts:450`. No new remote transport. |
+| ops-O08 | Existing client-self + Hub-total COMPLETE in their authorized execution contexts; IMPLEMENTATION_GAP for administrator selecting one key on Hub | Keep **`ocx usage ... --json`** on a connected machine as own-key data-plane usage, and the same command on the Hub host as whole-Hub management usage. Add only **`--api-key-id ID`** to `ocx usage` for the existing non-client management branch. Reject this option on connected client before reading secret/transport; do not forward it to `/v1/usage`. | GUI machine button adds apiKeyId; Hub button omits it (`gui/src/pages/Usage.tsx:1113`, `:1275`). Management API accepts filter (`src/server/management/logs-usage-routes.ts:243`). CLI branch `src/cli/observe.ts:188` uses stored enrolled data key + `/v1/usage` for client; local Hub uses `/api/usage` at `:209`. `/v1/usage` authenticates exact configured key, projects `scope:'client'`, rejects caller-selected identity and strips accounts (`src/server/hub-usage.ts:15`, `:25`; `src/remote/hub-usage.ts:8`). This intentionally does NOT promise remote Hub-total access using a client data key. |
+| ops-I14 | IMPLEMENTATION_GAP for narrow invocation, not missing backend/helper | Add **`ocx integration client sync --client aside --json`**. No profile selector: GUI refreshes server-selected enabled profiles. Call existing **refreshAsideProfilesThroughServer**, preserving its direct-local attestation capability. Emit per-profile outcomes, and nonzero on any unsuccessful outcome; do not turn partial 207 into blanket success. | GUI uses exact POST `/api/client-integrations/aside/sync {}` at `gui/src/pages/integrations/aside-profile-api.ts:38`; owner `src/server/management/aside-profile-routes.ts:308`. Helper already exists in `src/cli/aside-profiles.ts:9`; capability transport at `:24`, `:50`; controlled baseUrl seam at `:69`. Current `ocx sync` first syncs Codex and other file clients, then calls helper at `src/cli/dispatch.ts:526`, so it is an effect superset with warning-only failure handling, not the narrow task. Add branch in `src/cli/integrations.ts:222` with lazy helper import; no new backend owner. |
+| ops-O06 | Snapshot read COMPLETE; follow amendment semantics IMPLEMENTATION_GAP | Keep command **`ocx logs --follow --jsonl`**. Make this existing follow workflow cursor/reset aware and surface changed already-seen rows; don't invent a history endpoint. Minimal compatible JSONL choice: re-emit a row when its canonical payload changes, with same id; document consumers should upsert. Preserve duplicate IDs when server explicitly returns them, resets and removals; see exact output decision below. | CLI `src/cli/observe.ts:100` never sends cursor and suppresses any seen ID at `:108`. Server content hash deliberately sends reset for same-ID content changes (`src/server/request-log-cursor.ts:50`, `:57`, `:77`); GUI replaces snapshot on reset (`gui/src/pages/Logs.tsx:621`) and merges only valid deltas. Probe below proves the mismatch with actual cursor/parser modules and the exact source-equivalent dedupe predicate. |
+| ops-D01 | IMPLEMENTATION_GAP for authenticated runtime-health projection | Add **`ocx system health --json`**, fixed GET `/api/system/health` via existing runtimeRequest, run on the serving runtime's host. Keep existing `ocx health` liveness contract and `system status` aggregate unchanged. | Endpoint returns status/service/version/uptime/pid/spendLedger at `src/server/management/system-routes.ts:66`. `ocx health --json` emits only ok/pid/port (`src/cli/dispatch.ts:787`); `status --json` emits health ok/url/message plus other machine state (`src/cli/status.ts:873`), not this projection; `system status` fetches only settings/startup/memory (`src/cli/system-command.ts:35`). New leaf in `src/cli/system-command.ts:193`; no new API or remote credential scheme. |
+
+The Desktop additions are deliberately scoped to the currently serving **local management runtime**, which may be a Hub. Running them on a connected client should preserve the existing client-role refusal and guidance to run on the Hub. The connected browser's independently authorized shared dashboard session is not a CLI credential. Existing connected Desktop **apply** intentionally downloads the Hub's resolved Desktop model snapshot and writes the connected machine's gateway config (`src/cli/claude-desktop.ts:238`, `:260`); that is a separate target from editing the Hub's desired profile.
+
+The GUI profile import stages a draft only (`gui/src/pages/ClaudeDesktop.tsx:480`) whereas a terminal import command naturally commits when explicitly invoked. This does not require implementing a persistent CLI draft editor: file inspection followed by explicit `profile import` and separate `apply` preserves the meaningful save/apply boundary. Reuse `parseDesktopProfile`; retain server's unavailable-model validation and trusted applied-marker handling. No automatic mode switch or apply is added to import.
+
+## Exact follow-output choice
+
+`ops-O06` is a workflow gap, not merely inefficient repeated polling. With a stable request id, CLI seen-ID dedupe loses later status/token/pricing updates even though `/api/logs` exposes them.
+
+Smallest bounded change is to extract cursor/snapshot state into **`src/cli/log-follow.ts`** and call it from **`src/cli/observe.ts`**. It should:
+
+1. Parse cursor/reset envelopes defensively. Legacy array/snapshot responses remain accepted and never manufacture a cursor.
+2. Replace the local bounded window on reset; append suffixes otherwise. The server explicitly permits repeated IDs, so do not use an id-only set to represent the window.
+3. Existing text/row-JSONL follow can re-emit changed rows; an explicit removed/reset event would be a different output contract. If deletion/reset visibility is required for exact machine reconstruction, add **`--events`** to follow and emit `{type:'snapshot',rows,cursor}`, `{type:'append',rows,cursor}` rather than silently breaking the existing row JSONL stream. This is the smallest additive exact-state option. No `--api-path` or new backend route.
+4. Keep `--json` one-shot; `--follow --jsonl` streaming. Bound window/cursor sizes, handle interruption, and never claim an accepted stale snapshot is new data.
+
+Recommended roadmap split: fix row amendments and cursor transport in existing follow; add `--events` only in the same reviewed output-contract unit if exact reset/removal projection is an acceptance requirement. GUI-to-CLI read parity must at least stop losing amendments. Full event schema is main's shared output-contract decision, not a new unresolved target/auth question.
+
+## Duplicate settings tasks: use existing IDs
+
+These are aliases for existing owner tasks, **not additional UNKNOWN roadmap rows**.
+
+| Operations row | Canonical settings IDs | Why |
+|---|---|---|
+| ops-D18 multi-agent mode/thread/native behavior and advisory | **set-M13**, **set-S04** | Existing v2 root and advisory/local-live join belong to these rows; do not introduce another agent-mode taxonomy. |
+| ops-D18 injection model/effort/guidance/default synchronization | **set-S03** | Same injection/default contract. Featured roster and fallback references, where rendered, map to **set-S01**, **set-S02**. Effort-cap metadata should be reconciled with this settings-owned unit, not counted again. |
+| ops-O15 account/quota/active-selection reads in Tray | **set-A01**, **set-P09**, **set-P12**, **set-P14** | Codex readiness/quota plus generic OAuth/API-key roster. Usage/companion reads stay ops-O08/O10/O13. |
+| ops-O16 Tray switches | **set-A04** (Codex), **set-P12** (OAuth), **set-P14** (provider API-key pool) | `gui/src/pages/tray-data.ts:36` selects these exact three route families. No tray-specific command. |
+
+Canonical titles/IDs verified from `.tmp/cli-parity/gaps-settings.md`. These references are stable task identities; that artifact may continue gaining source evidence while main assembles the roadmap.
+
+**Coverage expansion requiring main allocation, not a duplicate UNKNOWN:** the first inventory's D18 footnote also mentioned `MemoryModelsPanel` and `CompactionRoutingPanel`, but neither has a matching dedicated `set-*` row in the current 67-row settings join. They write `memoryModels` and `compactionRouting` through PUT `/api/settings` (`gui/src/components/MemoryModelsPanel.tsx:111`, `gui/src/components/CompactionRoutingPanel.tsx:180`); they are not injection or v2 fields and must not be falsely mapped to set-S03/M13. Parent should allocate these two field groups to its runtime/model settings unit before calling all dashboard fields closed. Exact values: memoryModels `{extract?:{...phase},consolidation?:{...phase}}|null`; compactionRouting `{model,reasoningEffort?,triggers?,sourceModels?}|null`. Existing system settings parser only handles autostart/stream-mode/desktop-authless/client-compaction (`src/cli/system-command.ts:123`), so generic `config set` would not establish live PUT parity. This pass does not create new set IDs or edit sibling artifacts.
+
+## Accepted C4 data-plane unit
+
+Parent explicitly accepted terminal model test, transcription and connection-only voice probe as tasks. **ops-K08/K12/K13 are included IMPLEMENTATION_GAPs**, not pending product scope. Browser microphone capture, playback widgets, copy buttons and waveform UI remain excluded. Authorization authority is unchanged.
+
+| ID | Smallest command | Code/contract and proof requirements |
+|---|---|---|
+| ops-K08 | **`ocx access test MODEL --protocol responses\|chat\|messages --api-key-stdin --json`** | Keep existing access test grammar, add explicit chosen-key input. Current `src/cli/access.ts:255` uses runtimeRequest, whose headers start with management auth (`src/cli/runtime-api.ts:142`); that is not GUI newly-created-key proof. Use bounded `readSecretBytes` (`src/cli/runtime-api.ts:398`) with a 4096-byte key limit, strict UTF-8/single-line decoding, explicit TTY refusal, input deadline and returned-buffer cleanup and a dedicated fixed data-plane transport that sets only the chosen `x-opencodex-api-key`, never management bearer/header defaults. Existing no-flag test must not newly claim selected-key validation. |
+| ops-K12 | **`ocx access audio transcribe FILE --model ID --api-key-stdin --json`** | Multipart file/model/response_format=json to fixed `/v1/audio/transcriptions`, bounded file size/deadline/body, abort on signal. GUI contract at `gui/src/audio-api-client.ts:13`; actual admitted route `src/server/index/serve-options.ts:1594`. Output transcript only by explicit task result, not incidental debug logging; no background retries that spend usage again. |
+| ops-K13 | **`ocx access audio live-check --model ID --api-key-stdin --json`** | Fixed WebSocket `/v1/live?model=...`, same data-key subprotocol scheme and session.update/client-delegation settings as GUI (`gui/src/audio-api-client.ts:71`, `:88`). Wait for server session id/status, then session.close; bounded readiness/session lifetime. No microphone, audio uploads, delegation execution or auto-reconnect. Return connection outcome, not a claim of usable voice roundtrip. |
+
+Recommended file boundaries: **`src/cli/access-data-plane.ts`** for fixed allowlisted HTTP test/transcription origin+headers+bounded response helpers, **`src/cli/access-audio.ts`** for the two audio verbs and WebSocket lifecycle; wire through **`src/cli/access.ts:274`**. These are domain-specific internal helpers, not an operator-visible arbitrary-URL request command. Reuse existing stdin/timeout/error primitives where safe; never call runtimeRequest for the chosen-key wire request.
+
+Target resolution reuses current topology, not a new credential store: standalone/Hub use the existing local serving origin; connected client uses its already-enrolled normalized serverUrl, analogous to `fetchHubUsage` (`src/client/hub-client.ts:484`). The explicit key is still provided for this task through stdin; never implicitly substitute the enrolled key or admin token. Revalidate connection identity around an async read on connected clients and retain HTTPS-or-loopback, redirect refusal, safe headers, and origin policy. Do not add `--base-url`, token argv/env flags, token file caches, or a management-relay credential exchange in this unit.
+
+For review, require fixture evidence for wrong chosen key, missing key, all three protocol shapes, explicit refusal when the target does not enforce the chosen key, no admin-header leakage, no redirects, no stderr/stdout secret echo, bounded file/body/session sizes, timeout/interruption and correct session.close. Existing auth/scope policy remains authoritative; adding a CLI cannot make a data key a management principal. All synthetic keys must stay fixture-only. The final 070 observational guard supersedes any unconditional chosen-key-enforcement assumption in this source proposal.
+
+## Focused proof and proposed test placement
+
+Executed, using only mocked/pure inputs:
+
+- From repository root: `bun test gui/tests/log-poll.test.ts tests/clients/client-hub-usage.test.ts` — Bun selected **only the client file**, 16 pass / 0 fail / 40 assertions. Do not claim this invocation ran GUI tests.
+- From `gui/`: `bun test tests/log-poll.test.ts` — 4 pass / 0 fail / 22 assertions. Covers legacy snapshots, reset metadata, malformed cursor rejection and repeated-ID preservation.
+- A fileless `bun -e` probe imported actual `src/server/request-log-cursor.ts` and `gui/src/pages/log-poll.ts`, fed two snapshots `{id:'fixture-same-id',status:200,totalTokens:1}` then tokens=9, and applied the exact source-equivalent CLI `seen.has(String(row.id))` predicate. Output: **`{"serverReset":true,"guiAmendedTokens":9,"cliDedupeEmitted":0}`**. This is proof of cursor/parser behavior plus a source-level CLI predicate reproduction, **not execution of the whole CLI follow loop**.
+
+Inspected only, not executed:
+
+- `tests/claude-integration/claude-desktop-cli.test.ts:402` asserts connected show/export/move/default remain local and warn; `:280` asserts connected import --apply refuses before writing; `:501` asserts apply delegates profile to live owner.
+- `tests/clients/aside-profile-sync-owner.test.ts:211` covers stale CLI refreshing only live-server-enabled Aside profiles; existing helper is the owner to reuse.
+- `tests/server/hub-usage.test.ts:66` rejects absent/environment/admin keys for data-plane usage; `:76` rejects caller-selected identity; `:85` retains authenticated scope with bounds/filters. Executed client-side mocks additionally verify dedicated data key/no Authorization and dropping management-only DTO fields.
+
+New focused files proposed (no edits made):
+
+| Change | Proposed focused test file | Essential assertions |
+|---|---|---|
+| Desktop live profile show/import | `tests/cli/cli-claude-desktop-profile.test.ts` | Fixed GET/PUT shape, bounded parse-before-write, missing/invalid file zero write, 409 does not rebase, live adoption result, client-role refusal, existing local verbs untouched. |
+| Runtime health read | `tests/cli/cli-system-health.test.ts` | Current runtime GET, version/uptime/pid/spendLedger preserved, remote/client refusal, no invented liveness success. |
+| Usage admin filter | `tests/cli/cli-usage-scope.test.ts` | Hub query includes apiKeyId only when explicit; connected rejection before secret/transport; default connected self read unchanged; invalid connection fails closed. |
+| Narrow Aside sync | `tests/cli/cli-aside-sync.test.ts` | Calls existing helper only, no Codex/other-client sync, no profile flag, partial outcomes nonzero, attestation refusal no fallback. Keep stale-owner test as server proof. |
+| Log amendments/events | `tests/cli/cli-log-follow.test.ts` | Changed same ID, repeated IDs, valid suffix, reset/removal, legacy snapshots, malformed cursor, bounded state, interruption. GUI parser tests are not CLI coverage. |
+| Data-plane chosen key/audio | `tests/cli/cli-access-data-plane.test.ts`, `tests/cli/cli-access-audio.test.ts` | Injected HTTP/WebSocket and fake stdin only; auth/secret/redirect/failure/cancel matrix above. No provider traffic. |
+
+Any new test files must be registered in both repository layout maps under the existing AGENTS rule. Prefer these siblings over extending already-large legacy parity/desktop files. Exact-head integration/test execution and final receipt design remain main-owned.
+
+Static receipt: 47 explicit source file/line anchors resolve; all 10 referenced set-* task IDs exist in the current settings join. Proposed new implementation/test paths are explicitly proposals and were not created.
diff --git a/devlog/_plan/261003_cli_gui_parity/007_architecture_decisions.md b/devlog/_plan/261003_cli_gui_parity/007_architecture_decisions.md
new file mode 100644
index 00000000000..978685d754b
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/007_architecture_decisions.md
@@ -0,0 +1,42 @@
+# Architecture decisions
+
+The reader is a maintainer reviewing named terminal workflows. Existing domain handlers and the existing management client remain the execution authority; the capability index becomes an accurate, scalable discovery layer.
+
+| Decision | Main disposition | Consequence |
+| --- | --- | --- |
+| CP-ARCH-01 | Accept fixed named metadata with handwritten domain handlers | No arbitrary method/URL API client, no generic config fallback counted as parity. |
+| CP-ARCH-02 | Amend: reuse Capability, without NamedCommandMeta/DomainCommand interfaces | Split type/data files only for size and pure-import boundaries. Handler signatures remain compatible. |
+| CP-ARCH-03 | Accept existing server validation/persistence/ownership | CLI parses grammar and bounded input; no second persistence engine or live-to-local fallback. |
+| CP-ARCH-04 | Accept additive optional Capability.usage | Exact operand grammar is available for verified leaves; old metadata output stays compatible when absent. |
+| CP-UX-01/02 | Accept fixed grammar, explicit JSON sources and scoped confirmation | Ordinary reversible changes do not gain gratuitous confirmation. Destructive actions preserve --yes and identity checks. |
+| CP-UX-03 | Amend: preserve legacy stderr prose and exit codes | No global JSON error-envelope migration. New diagnostics are safe and retain reason/hint/status. Partial receipts remain observable. |
+| CP-UX-04 | Scope observational claims | Help remains offline/write-free. Do not promise all legacy reads bypass shim preflight; new strict observational paths need their own proof. |
+| CP-AUDIT-01/02 | Accept task ledger plus separate API debt | Counts are not endpoint-prefix coverage. Local/native equivalence, duplicate GUI entry points and consent exclusions are explicit. |
+| CP-SIZE-01 | Accept capacity work before metadata expansion | Split generated reference into flat domain chapters; add a CLI structure owner by moving existing contracts, never raising line caps. |
+| CP-TEST-01 | Accept handler-wire, real route, CLI and negative evidence | No live user state/upstream traffic. Source declarations are not runtime proof. |
+| CP-DATA-01/02 | Accept bounded credentialless malformed-body observation before a chosen-key model probe | Fail unavailable on unproved enforcement, preserve existing server policy, and state the cross-request identity/policy limits; exact mechanism and real-route tests are in 070. |
+| CP-DELIVERY-01 | Accept dependency slices with sequential branch ownership | Main alone switches branches; implementation leaves have disjoint file scopes. Six manual PR layers, each with its own CI. |
+
+## Local and live are explicit targets
+
+Preserve offline/local commands. Add --live to provider add/remove/set-default, custom models add/remove, v2 and logout where the source comparison proves different retained runtime state or receipts. Decide the target before touching local config. A multi-request workflow resolves its management base once and reuses it. A refusal never falls back to local writes. --json is output selection, never target selection.
+
+For Desktop, use the existing namespace with profile show/import for the live desired profile; existing show/move/default/import remain local and apply remains separate. Management commands run on the serving runtime host, including a Hub; a connected-client management refusal remains a refusal. No remote admin credential scheme is introduced.
+
+## Capability usage field chain
+
+Creation: optional usage literals in pure capability domain files; type in src/cli/capability-types.ts. Serialization: capabilities-command.ts uses an explicit field projection; it must add usage conditionally while retaining the exact legacy shape for declarations without it. A real runCapabilities --json fixture verifies the field is not silently dropped. Deserialization: N/A, no persisted/external capability ingestion is introduced. Consumers: declared help renderer and generated reference use usage beneath canonical headings; command matching/recovery and capabilityInvocation remain based on command tokens. Tests cover absent-field compatibility, exact grammar, alias resolution and pure import closure.
+
+## Input and result boundaries
+
+New JSON file/stdin input is explicit, bounded to the management JSON contract (4 MiB), rejects interactive waiting, invalid UTF-8/JSON and wrong top-level shapes, and never echoes payloads. Domain files validate keys/shapes and reuse pure existing validators where appropriate. Composite requests are checked against the whole serialized body limit. Never read stdin twice in one invocation.
+
+Server errors retain their normal exit classification. A new safe nested-error projection in runtime-api preserves an existing nested code/message without dumping the raw body. Domain writers distinguish saved, applied, deferred, conflict and unknown completion; no blind write retry. Human text uses terminal escaping. JSON success remains the safe existing DTO, not a universal new envelope.
+
+## Explicit scope for data-plane tools
+
+The API Keys page's selected-key test, audio transcription and connection-only live probe are included as terminal tasks. They use a dedicated fixed data-plane transport with an explicit stdin key, never management auth or arbitrary URLs. Browser microphone capture/playback and waveform controls are presentation exclusions. No secret-returning creation/pairing operation is executed by the development agents.
+
+## Consultation provenance
+
+Architect: Epicurus, returned handle 01a1021d-2d94-7d20-95c1-a18da31958a8. Proposal and decision amendment are retained in task scratch. The architect accepted optional usage with exact legacy fallbacks and accepted retaining existing v2 roots after main corrected an inventory false-negative. Whole-plan reflection by the same architect is ALIGNED for SHA256 a095a4e514d6d8e5a37dbf05a66b2c9156ebaeeb28a8e0fb878bc76f931c27b1: all 178 IDs, unit assignments and acyclic aliases were checked, with no essential mismatch. This is separate from the earlier concept agreement. Reflection artifact is retained in task scratch; its decision mapping covers every accepted CP decision. Independent A remains a separate gate.
diff --git a/devlog/_plan/261003_cli_gui_parity/008_task_ledger.json b/devlog/_plan/261003_cli_gui_parity/008_task_ledger.json
new file mode 100644
index 00000000000..4a8531ffade
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/008_task_ledger.json
@@ -0,0 +1,185 @@
+{
+  "baseline": "9f89b7265b754eb681215ad327fc9459af37b9e1",
+  "candidateRows": 178,
+  "scopeNote": "176 initial rows plus two confirmed embedded settings groups; aliases are retained and excluded from unique eligible denominator, not silently dropped.",
+  "rows": [
+    {"id":"set-P01","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P01 — Inspect configured providers, presets, authentication availability","existingCli":"provider list/show/presets; inspect config; account list/current; status --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P02","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp3","evidence":[],"task":"set-P02 — Add a preset/custom provider; enable canonical OpenAI account provider","existingCli":"provider add P [--adapter A --base-url U --api-key ... --default-model M --allow-private-network --force --set-default --sync]; provider edit openai --enabled on","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P03","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp3","evidence":[],"task":"set-P03 — Edit provider transport, discovery, default model, note, network permission","existingCli":"provider edit/update P --adapter A --base-url U --default-model M\\|- --auth-mode MODE\\|- --note TEXT\\|- --api-key-transport MODE\\|- --enabled on\\|off --live-models on\\|off --allow-private-network on\\|off","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P04","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp3","evidence":[],"task":"set-P04 — Configure and inspect request pacing","existingCli":"inspect pacing --name P --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P05","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp3","evidence":[],"task":"set-P05 — Enable/disable, choose default, remove provider","existingCli":"provider edit P --enabled on\\|off; provider set-default P; provider remove P","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P06","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P06 — Change OpenAI account mode","existingCli":"provider account-mode pool\\|direct --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P07","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp3","evidence":[],"task":"set-P07 — Atomically edit provider JSON","existingCli":"config import exists but is not provider-editor CAS parity","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P08","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P08 — Check provider connectivity","existingCli":"provider test P --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P09","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P09 — Inspect provider quota/capacity/usage","existingCli":"provider quota [--refresh] --json; account list P --quota [--refresh] --json; usage --range 30d --surface codex\\|all --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P10","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-P10 — OAuth login, add another account, reauthenticate, submit callback, cancel, logout","existingCli":"account login P [--reauth --id I] [--no-wait]; account reauth/code/cancel; login P (local); logout P --json (local)","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P11","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P11 — Kiro native device login","existingCli":"account login kiro --method builder-id\\|google\\|github [--no-wait] --json; account cancel kiro --flow F --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P12","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P12 — Manage OAuth account roster","existingCli":"account list/current/use P I; account alias P I TEXT\\|-; account pause/resume P I; account remove P I --yes; all support --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P13","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P13 — Import Antigravity accounts","existingCli":"account import google-antigravity --format cockpit-tools --file F\\|--stdin --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P14","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P14 — Manage API-key pool","existingCli":"account list/use P I; account add-key P [--label L] (stdin); account alias P I TEXT\\|-; account remove P I --yes --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P15","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-P15 — Set account-pool strategy and thresholds","existingCli":"account strategy P STRATEGY; account sticky P N; account auto-switch P on\\|off\\|threshold N\\|status; account routes anthropic ...","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P16","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P16 — Set per-Anthropic-account auto-switch override","existingCli":"account auto-switch anthropic status\\|on\\|off\\|inherit\\|threshold N --account I --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P17","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp3","evidence":[],"task":"set-P17 — Control xAI Responses opt-in and model Fast variants","existingCli":"provider edit xai --xai-chat on\\|off --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P18","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-P18 — Inspect/redeem Grok reset coupons","existingCli":"account grok-reset-coupons [I] [--consume --yes --token-id T --operation-id UUID] --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P19","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-P19 — Inspect/redeem Anthropic reset grants","existingCli":"No Anthropic grant read command in account-auth dispatcher; Grok/Codex reset commands target different contracts","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-P20","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-P20 — Choose whether OAuth launches browser on proxy host","existingCli":"account login currently omits openBrowser; GUI local preference feeds request field","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A01","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-A01 — Inspect/refresh account readiness, quotas and active selection","existingCli":"account list openai --quota [--refresh] --json; account current openai --json; account refresh openai --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A02","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-A02 — Add/re-authenticate pool account with browser or device flow","existingCli":"account login openai --id I --reauth --device --no-wait --json; account code/cancel openai --flow F","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A03","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-A03 — Reauthenticate native main in place","existingCli":"account main reauth --device [--no-wait] --json; account main reauth status\\|cancel --flow F --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A04","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-A04 — Select active account, rename, remove","existingCli":"account current/use/clear openai; account alias openai I TEXT\\|-; account remove openai I --yes --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A05","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-A05 — Pause/resume, pause exhausted accounts, set priority","existingCli":"account pause/resume openai I; account pause-exhausted openai; account priority openai I N\\|first\\|earlier\\|normal\\|later\\|last\\|reset --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A06","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-A06 — Set per-account auto-switch threshold","existingCli":"account auto-switch openai on\\|off\\|threshold N\\|status is pool-wide only","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A07","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-A07 — Permit paid credits after quota exhaustion","existingCli":"Only generic config fallback; no account-auth/extended credits policy handler","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A08","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-A08 — Inspect/redeem Codex reset credits","existingCli":"account reset-credits I\\|main [--consume --yes --operation-id UUID] --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A09","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-A09 — Configure quota-window activation and credit display","existingCli":"system settings --json reads settings; account refresh handles immediate refresh only","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A10","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-A10 — Native-main profile inventory, register, switch/recover","existingCli":"account main list\\|doctor\\|register LABEL\\|switch I --yes\\|recover [--rollback --yes] --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A11","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-A11 — Account-picker setting and main hard lock","existingCli":"system settings --json reads values","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A12","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-A12 — Read prompt layer stack and effective prompt text","existingCli":"inspect codex-prompt --json; inspect codex-prompt --text (mutually exclusive)","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A13","domain":"settings","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"set-A13 — Toggle/edit/order custom prompt layers and base variants","existingCli":"inspect codex-prompt is read-only","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A14","domain":"settings","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"set-A14 — Adopt existing prompt configuration or repair prompt drift","existingCli":"inspect codex-prompt can expose drift","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A15","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-A15 — Enable default-mode request-user-input","existingCli":"agent request-user-input [on\\|off] --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-A16","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-A16 — Toggle Ultra Fast tier","existingCli":"system settings --json reads ultraFastTier","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M01","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-M01 — Inspect catalog, exposed selection, context limits and provider metadata","existingCli":"models live --provider P --json; models selected P; models context status; models preset show; models new-policy; alias list; inspect config/catalog","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M02","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-M02 — Show/hide selected models or all models of one provider","existingCli":"models enable\\|disable P/M [--native] --json; models provider P on\\|off --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M03","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-M03 — Choose curated/provider model preset and default policy for newly discovered models","existingCli":"models preset show [--provider P]; models preset apply P [--all]; models new-policy on\\|off [--provider P]; models new-arrivals --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M04","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-M04 — Edit provider/model aliases and default alias policy","existingCli":"alias list; alias set P\\|P/M ALIAS; alias rm P\\|P/M; alias defaults on\\|off [--provider P] --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M05","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp4","evidence":[],"task":"set-M05 — Edit/reset model display label and cost override","existingCli":"models price P/M; models set-price P/M --input N --output N [--cache-read N --cache-write N] or --auto; custom models edit --display-name only","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M06","domain":"settings","baseline":"UNKNOWN","status":"pending","unit":"wp4","evidence":[],"task":"set-M06 — Create/edit/delete custom model definitions","existingCli":"models add P M --display-name --context-window --modalities --reasoning-efforts --default-reasoning-effort; models list-custom --json; models edit ID ...; models remove ID\\|P/M --yes","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M07","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-M07 — Override/restore discovered-model capability metadata","existingCli":"models set P/M --context-window N\\|0\\|- --modalities CSV\\|- --reasoning-efforts CSV\\|\"\"\\|- --default-reasoning-effort LEVEL\\|-; --reset --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M08","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp3","evidence":[],"task":"set-M08 — Override provider/per-model advertised context window","existingCli":"models set P/M --context-window N\\|0\\|- covers per-model override","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M09","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-M09 — Configure context caps: per-provider, global default, apply/remove all","existingCli":"models context status; models context value N [--set-all]; models context provider P on\\|off [--value N]; models context all on\\|off --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M10","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp4","evidence":[],"task":"set-M10 — Configure picker order manually or by ranking policy","existingCli":"agent subagents status shows picker fields; agent subagents set writes featured models only","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M11","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-M11 — Show generated Fast catalog rows","existingCli":"system settings --json reads fastRows","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M12","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-M12 — Configure shadow-call interception target","existingCli":"models shadow status; models shadow set M\\|- --enabled on\\|off --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-M13","domain":"settings","baseline":"UNKNOWN","status":"pending","unit":"wp5","evidence":[],"task":"set-M13 — Configure multi-agent surface and per-session thread limit","existingCli":"v2 status; v2 mode v1\\|default\\|v2; v2 keep-native-v1 on\\|off; v2 threads N (local, prose output)","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-C01","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-C01 — Inspect combos, target inventory, quota and catalog exposure","existingCli":"combo list/show I; models live; inspect config; provider quota --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-C02","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp4","evidence":[],"task":"set-C02 — Create/edit/rename/remove combo and target policy","existingCli":"combo set\\|create\\|update I --targets P/M[:W],... --strategy S --sticky N\\|- --effort E\\|- --alias A\\|- --native-alias --display-name TEXT\\|- --decision-provider P\\|- --decision-model M\\|- --decision-timeout N\\|- --rename-from OLD; remove I --yes","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-C03","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-C03 — Probe selected JEV decision backend","existingCli":"combo test [--combo I] [--decision-provider P\\|--decision-model M] [--decision-timeout N] --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-C04","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-C04 — Explain a saved combo's protocol behavior","existingCli":"api protocols --json; api explain --model combo/I --inbound responses\\|chat\\|messages --feature F[,F] ... --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-C05","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp4","evidence":[],"task":"set-C05 — Inspect JEV combo decision outcomes and savings","existingCli":"usage --range ... --model combo/I exists but returns ordinary usage","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-R01","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-R01 — Inspect routing profiles, candidates, scoring and compatibility suite choices","existingCli":"route policy list/show I --json; inspect routing-analytics --json; models live; lab catalog --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-R02","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp4","evidence":[],"task":"set-R02 — Create/update/remove routing profile","existingCli":"route policy only list/show/dry-run/evaluate","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-R03","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-R03 — Dry-run a saved route against requirements","existingCli":"route policy dry-run\\|evaluate I --model-context N --tools --image --structured-output --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-S01","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-S01 — Choose/reorder featured subagent roster","existingCli":"agent subagents\\|roster status\\|set CSV\\|clear --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-S02","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-S02 — Force subagent model and configure fallback chain","existingCli":"agent subagents force M\\|-; agent fallback status\\|set [CSV] [--poll-ms 5000..600000]\\|clear --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-S03","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"set-S03 — Configure delegation guidance/default model/effort and synchronize defaults","existingCli":"agent injection\\|guidance set --model M\\|- --effort E\\|- --guidance on\\|off; status --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-S04","domain":"settings","baseline":"UNKNOWN","status":"pending","unit":"wp5","evidence":[],"task":"set-S04 — Set delegation mode and editable proactive hint","existingCli":"v2 mode v1\\|default\\|v2; v2 mode-hint TEXT; v2 mode-hint --clear; v2 status (local)","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-S05","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-S05 — Ask for delegation model recommendation, then separately apply","existingCli":"agent injection suggest WORK [--model SIZING_MODEL] [--apply] --json; agent injection set --model M --effort E","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-K01","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-K01 — Inspect/filter/paginate compatibility verdicts and subjects","existingCli":"lab status; lab verdicts --subject --layer --suite --verdict --limit --cursor; lab subjects --limit --cursor --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-K02","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-K02 — Inspect one verdict's evidence lineage and production context","existingCli":"lab subject I; observations --subject I --layer L --suite T --limit --cursor; event I; artifact D; production-signals --subject I --limit --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-K03","domain":"settings","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-K03 — Filter protocol pairs and view community trust context","existingCli":"lab subject I --json; lab public community --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-K04","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-K04 — Inspect provider upstream wire/protocol and conversion plan","existingCli":"api protocols [--provider P] --json; api explain --model M --inbound PROTOCOL [--feature F] --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"set-K05","domain":"settings","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"set-K05 — Control protocol exposure/rollout","existingCli":"api policy --messages on\\|off --unrepresentable legacy\\|reject --rollout SWITCH=on\\|off ... --json","sourceInventory":"004_settings_coverage.md"},
+    {"id":"ops-D01","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp7","evidence":[],"task":"ops-D01 — Read live health/version/uptime and provider overview; `gui/src/pages/dashboard-core-poll.ts:275`","existingCli":"status --json; health --json; system status --json","sourceInventory":"005_operations_coverage.md","disposition":"Included task; target/contract resolved in operational crux decision."},
+    {"id":"ops-D02","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D02 — Read model catalog and 30d usage; `gui/src/pages/dashboard-core-poll.ts:135`, `:142`","existingCli":"models live --json; usage --range 30d --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D03","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D03 — Read runtime/client preferences; `gui/src/pages/dashboard-core-poll.ts:218`","existingCli":"system settings --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D04","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D04 — Set Codex autostart; `gui/src/pages/use-dashboard-data.ts:753`, `:777`","existingCli":"system settings --auto-start on/off --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D05","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D05 — Set Desktop authless / client compaction; `gui/src/pages/use-dashboard-data.ts:768`, `:778`","existingCli":"system settings --desktop-authless on/off --client-compaction on/off --json; then system sync --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D06","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D06 — Sync client catalogs/configuration; `gui/src/pages/use-dashboard-data.ts:790`, `:796`","existingCli":"system sync --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D07","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D07 — Read project-config warnings; `gui/src/pages/dashboard-core-poll.ts:126`","existingCli":"system diagnostics --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D08","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D08 — Read startup protection; `gui/src/pages/dashboard-core-poll.ts:104`; `gui/src/pages/Startup.tsx:140`","existingCli":"system startup health/status --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D09","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D09 — Read memory/storage pressure and active turns; `gui/src/components/MemoryObservabilityCard.tsx:243`","existingCli":"observe memory --json; memory --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D10","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D10 — Drain and restart proxy; `gui/src/components/MemoryObservabilityCard.tsx:359`","existingCli":"restart","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D11","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D11 — Check latest/preview package update; `gui/src/pages/use-dashboard-data.ts:824`","existingCli":"system update check --channel latest/preview --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D12","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D12 — Run package update, optionally restart; `gui/src/pages/use-dashboard-data.ts:909`","existingCli":"system update run --channel latest/preview --restart on/off --yes --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D13","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D13 — Observe update job; `gui/src/pages/use-dashboard-data.ts:493`","existingCli":"system update status JOB-ID --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D14","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-D14 — Desktop-shell update navigation; `gui/src/pages/use-dashboard-data.ts:6` (openDesktopUpdatePage dependency), `gui/src/pages/dashboard-overview-sections.tsx:220`","existingCli":"Desktop update UI panel","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D15","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"ops-D15 — Web search sidecar off/on/model/stream; `gui/src/pages/dashboard-overview-sections.tsx:585`, `:606`; save `gui/src/pages/use-dashboard-data.ts:563`","existingCli":"agent sidecar web --model ID --backend BACKEND --enabled on/off --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D16","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp5","evidence":[],"task":"ops-D16 — Vision sidecar off/on/model/reasoning/limits/timeout; `gui/src/pages/dashboard-overview-sections.tsx:467`, `:480`, `:628`, `:648`","existingCli":"agent sidecar vision --model ID --backend BACKEND --reasoning LEVEL --max-descriptions N --enabled on/off --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D17","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-D17 — Shadow-call interception toggle/model; `gui/src/pages/dashboard-overview-sections.tsx:716`, `:728`; save `gui/src/pages/use-dashboard-data.ts:610`","existingCli":"models shadow status --json; models shadow set MODEL --enabled on/off --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-D18","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp8","evidence":[],"task":"ops-D18 — Multi-agent mode/advisory, injection/guidance/defaults, effort caps; `gui/src/pages/use-dashboard-data.ts:640`, `:679`, `:727`; `gui/src/pages/dashboard-overview-sections.tsx:78`, `:103`","existingCli":"v2; agent injection/effort/subagents/roles","sourceInventory":"005_operations_coverage.md","aliasOf":["set-M13","set-S03","set-S04","set-S01","set-S02","set-S06","set-S07"]},
+    {"id":"ops-S01","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-S01 — Install service / repair service / install shim; `gui/src/pages/Startup.tsx:290`, `:294`","existingCli":"service install; service repair; codex-shim install; system startup install-service/install-shim --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-S02","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-S02 — Windows tray status; `gui/src/pages/Startup.tsx:176`","existingCli":"tray status --json; inspect windows-tray --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-S03","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-S03 — Windows tray install/start/stop/uninstall; `gui/src/pages/Startup.tsx:268`","existingCli":"tray install/start/stop/uninstall --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-S04","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-S04 — Connected-machine shim status/install/repair/uninstall; `gui/src/pages/Startup.tsx:97`, `:104`","existingCli":"codex-shim status/install/uninstall","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-S05","domain":"operations","baseline":"UNKNOWN","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-S05 — Read connected-machine selected clients / sync them; `gui/src/pages/Integrations.tsx:62`, `:72`","existingCli":"sync on connected machine","sourceInventory":"005_operations_coverage.md","disposition":"Existing status selectedClients and syncConnectedClient are the same GUI task; discovery proof."},
+    {"id":"ops-C01","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-C01 — Read Claude Code effective state/model choices; `gui/src/pages/ClaudeCode.tsx:88`","existingCli":"claude config status --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C02","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-C02 — Enable/disable Claude connection immediately; `gui/src/pages/ClaudeCode.tsx:166`; `gui/src/pages/use-claude-connection.ts:2`","existingCli":"integration native claude on/off --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C03","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-C03 — Enable/disable CLI first-party proxy environment; `gui/src/pages/ClaudeCode.tsx:178`","existingCli":"claude config set --first-party on/off --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C04","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-C04 — Save Code behavior/auth/env/model mappings/helpers; `gui/src/pages/ClaudeCode.tsx:217`","existingCli":"claude config set --enabled --auth-mode --system-env --fast-mode --auto-context --compact-window --inject-agents --small-fast-model --model-map --web-model --web-backend --vision-model --vision-backend","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C05","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-C05 — Start configured Claude intercept; `gui/src/components/ClaudeInterceptStart.tsx:18`","existingCli":"claude intercept start --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C06","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp6","evidence":[],"task":"ops-C06 — Read Desktop editable profile/catalog and applied health; `gui/src/pages/ClaudeDesktop.tsx:270`, `:354`","existingCli":"claude desktop status --json; claude desktop show --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C07","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp6","evidence":[],"task":"ops-C07 — Edit Desktop assignment family/alias/default and save; `gui/src/pages/ClaudeDesktop.tsx:24`, `:418`, `:806`, `:826`","existingCli":"claude desktop move ROUTE FAMILY [--default]; default FAMILY ROUTE-or-none; import FILE","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C08","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-C08 — Save then apply Desktop first-party/gateway; `gui/src/pages/ClaudeDesktop.tsx:433`","existingCli":"claude desktop apply --first-party; apply --gateway","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C09","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-C09 — Bind/unbind native picker ID to route; `gui/src/components/ClaudeFirstPartyBindings.tsx:59`","existingCli":"claude desktop bind PICKER-ID ROUTE; unbind PICKER-ID","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C10","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-C10 — Enable/disable Desktop picker proxy; `gui/src/components/ClaudeDesktopPicker.tsx:97`","existingCli":"claude desktop picker status/on/off","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C11","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-C11 — Export Desktop profile JSON; `gui/src/pages/ClaudeDesktop.tsx:468`","existingCli":"claude desktop export PATH-or-dash","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-C12","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp6","evidence":[],"task":"ops-C12 — Import Desktop profile JSON; `gui/src/pages/ClaudeDesktop.tsx:480`","existingCli":"claude desktop import FILE [--apply]","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-G01","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-G01 — Read Grok fence/catalog/status; `gui/src/pages/Grok.tsx:81`","existingCli":"grok status/show --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-G02","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-G02 — Save included/excluded Grok model selection; `gui/src/pages/Grok.tsx:151`","existingCli":"grok set/include/exclude CSV --json; grok clear --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-G03","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-G03 — Save and apply Grok fence; `gui/src/pages/Grok.tsx:171`","existingCli":"grok set CSV --json; then grok apply --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I01","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-I01 — List native integration desired/observed state; `gui/src/pages/integrations/native-api.ts:144`; overview `IntegrationsOverview.tsx:605`","existingCli":"integration native list --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I02","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-I02 — Toggle native Grok / Codex / Claude Desktop; `gui/src/pages/integrations/native-api.ts:155`; overview `IntegrationsOverview.tsx:604`","existingCli":"integration native grok/codex/claude-desktop on/off --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I03","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-I03 — List file-client state / inspect one; `gui/src/pages/integrations/integration-api.ts:435`, `:441`","existingCli":"integration client status/list/show [--client ID] --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I04","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp6","evidence":[],"task":"ops-I04 — Preview apply / overwrite / disable; `gui/src/pages/integrations/FileIntegrationPage.tsx:219`; `integration-api.ts:475`","existingCli":"Existing apply/disable at I05","sourceInventory":"005_operations_coverage.md","disposition":"Included preview task; interactive-preview exemption is not a consent prohibition."},
+    {"id":"ops-I05","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-I05 — Apply / overwrite conflicting config / disable owned block; `gui/src/pages/integrations/FileIntegrationPage.tsx:251`; `integration-api.ts:512`","existingCli":"integration client enable/disable --client ID [--overwrite-conflict] --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I06","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp6","evidence":[],"task":"ops-I06 — Set/clear per-model Droid reasoning defaults; `gui/src/pages/integrations/DroidReasoningDefaultsPanel.tsx:27`, `:38`","existingCli":"integration client enable --client droid","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I07","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-I07 — Read rollback journal; `gui/src/pages/integrations/integration-api.ts:454`","existingCli":"integration client history/journal [--client ID] --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I08","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp6","evidence":[],"task":"ops-I08 — Preview rollback, including drift-confirmed retry; `gui/src/pages/integrations/RestoreDialog.tsx:143`; `integration-api.ts:496`","existingCli":"integration client restore --op ID [--confirm-drift]","sourceInventory":"005_operations_coverage.md","disposition":"Included preview task; interactive-preview exemption is not a consent prohibition."},
+    {"id":"ops-I09","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-I09 — Restore rollback snapshot; `gui/src/pages/integrations/RestoreDialog.tsx:191`; `integration-api.ts:543`","existingCli":"integration client restore --op ID [--confirm-drift] --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I10","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp6","evidence":[],"task":"ops-I10 — Retire older rollback entry/snapshot; `gui/src/pages/integrations/FileIntegrationPage.tsx:446`; overview `IntegrationsOverview.tsx:851`; `integration-api.ts:571`","existingCli":"history and restore only","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I11","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-I11 — Disable all eligible file integrations; `gui/src/pages/integrations/IntegrationsOverview.tsx:443`, `:460`, `:512`","existingCli":"Repeat integration client disable --client ID for explicit set","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I12","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-I12 — List Aside profiles / read one / toggle selected profile; `gui/src/pages/integrations/AsideProfilesPage.tsx:54`, `:89`, `:116`; `integration-api.ts:424`","existingCli":"integration client status/enable/disable --client aside --profile N --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I13","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp6","evidence":[],"task":"ops-I13 — Aside profile rollback list/preview/restore/retire; `gui/src/pages/integrations/integration-api.ts:465`, `:503`, `:550`, `:585`","existingCli":"history --client aside --profile N; restore --client aside --profile N --op ID [--confirm-drift]","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I14","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp6","evidence":[],"task":"ops-I14 — Refresh all server-selected Aside profiles; `gui/src/pages/integrations/aside-profile-api.ts:38`","existingCli":"sync reaches refreshAsideProfilesThroughServer","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I15","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp6","evidence":[],"task":"ops-I15 — Inspect Cursor installed builds/gateway/last-seen state; `gui/src/pages/integrations/CursorIntegrationPage.tsx:113`; `cursor-api.ts:34`","existingCli":"integration native list/on/off; Cursor advertised only","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-I16","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp6","evidence":[],"task":"ops-I16 — Check advertised Cursor local installer; `gui/src/pages/integrations/CursorIntegrationPage.tsx:81`; `cursor-api.ts:59`","existingCli":"No Cursor installer-read command","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O01","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-O01 — Read debug flags/env/runtime overrides; `gui/src/pages/Debug.tsx:48`","existingCli":"observe debug --json; debug SCOPE status","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O02","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-O02 — Toggle provider/usage/injection/Claude inbound capture; `gui/src/pages/Debug.tsx:180`, `:210`","existingCli":"debug provider/usage/injection/claude on/off","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O03","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-O03 — Reset all capture overrides to env; `gui/src/pages/Debug.tsx:213`","existingCli":"debug provider reset; debug usage reset; debug injection reset; debug claude reset","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O04","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp7","evidence":[],"task":"ops-O04 — Read/follow provider, usage, injection debug buffers; `gui/src/pages/Debug.tsx:97`, `:115`","existingCli":"debug provider logs -f; debug usage logs -f; observe injection --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O05","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-O05 — Read Claude inbound metadata captures; `gui/src/pages/Debug.tsx:65`","existingCli":"observe claude-inbound --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O06","domain":"operations","baseline":"COMPLETE","status":"pending","unit":"wp7","evidence":[],"task":"ops-O06 — Read/retry/incrementally poll request log; `gui/src/pages/Logs.tsx:614`","existingCli":"logs --limit 2000 --json; logs --follow --jsonl","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O07","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-O07 — Filter log snapshot by surface/model/provider/status/time/speed/interception/conversation/protocol; `gui/src/pages/Logs.tsx:728`; `gui/src/pages/logs-filter.ts:16`, `:103`","existingCli":"logs has provider/model/status/conversation/account filters","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O08","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp7","evidence":[],"task":"ops-O08 — Read usage by preset/custom window, surface and local-machine attribution; `gui/src/pages/Usage.tsx:1110`","existingCli":"usage --range --surface --since --until --provider --model --json","sourceInventory":"005_operations_coverage.md","disposition":"Included task; target/contract resolved in operational crux decision."},
+    {"id":"ops-O09","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-O09 — Model text search, expand rows, tab and chart display; `gui/src/pages/Usage.tsx:1093`; chart components","existingCli":"No CLI task needed","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O10","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-O10 — Read companion preferences/presence; `gui/src/pages/usage-companion-panel.tsx:215`; Tray `gui/src/pages/Tray.tsx:100`","existingCli":"companion show --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O11","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-O11 — Persist companion model/provider visibility and chart/menu appearance; `gui/src/pages/usage-companion-panel.tsx:302`, `:503`","existingCli":"companion set KEY=VALUE ... --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O12","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-O12 — Restore companion defaults (including corrupt-state recovery); `gui/src/pages/usage-companion-panel.tsx:350`","existingCli":"companion reset --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O13","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp7","evidence":[],"task":"ops-O13 — Read usage timeline for companion/chart/tray; `gui/src/pages/usage-companion-panel.tsx:257`; `gui/src/pages/Tray.tsx:118`","existingCli":"companion show/set/reset only","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O14","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-O14 — Open companion view in system browser; `gui/src/pages/usage-companion-panel.tsx:367`","existingCli":"No standalone operator equivalent required","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-O15","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp8","evidence":[],"task":"ops-O15 — Tray refresh totals/accounts/quota; `gui/src/pages/Tray.tsx:79`, `:86`, `:104`; `gui/src/pages/tray-data.ts:27`","existingCli":"usage/companion show plus account read families","sourceInventory":"005_operations_coverage.md","aliasOf":["set-A01","set-P09","set-P12","set-P14","ops-O08","ops-O10","ops-O13"]},
+    {"id":"ops-O16","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp8","evidence":[],"task":"ops-O16 — Tray switch current account/key; `gui/src/pages/Tray.tsx:39`; `gui/src/pages/tray-data.ts:36`","existingCli":"Account selection families in inventory-cli.md","sourceInventory":"005_operations_coverage.md","aliasOf":["set-A04","set-P12","set-P14"]},
+    {"id":"ops-T01","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T01 — Inspect storage sizes/categories/Log Guard state; `gui/src/pages/Storage.tsx:1358`","existingCli":"storage report --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T02","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T02 — Preview oldest archived-session cleanup percentage; `gui/src/pages/Storage.tsx:177`","existingCli":"storage cleanup --percent N --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T03","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T03 — Quarantine / permanently delete previewed archives; `gui/src/pages/Storage.tsx:201`","existingCli":"storage cleanup --percent N --mode quarantine/permanent --yes --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T04","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T04 — List quarantine batches; `gui/src/pages/Storage.tsx:392`","existingCli":"storage trash list --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T05","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T05 — Restore a quarantine batch; `gui/src/pages/Storage.tsx:431`","existingCli":"storage trash restore ENTRY-ID --yes --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T06","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T06 — Read policy/job; `gui/src/pages/Storage.tsx:672`, `:865`","existingCli":"storage policy show --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T07","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp6","evidence":[],"task":"ops-T07 — Enable/disable recurring cleanup / save threshold, target, schedule, mode; `gui/src/pages/Storage.tsx:709`, `:738`","existingCli":"storage policy set --enabled --percent --mode --schedule --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T08","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T08 — Run cleanup policy now; `gui/src/pages/Storage.tsx:790`, `:809`","existingCli":"storage policy set EXISTING-FIELDS; policy run --yes --json; policy show --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T09","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T09 — Inspect log protection fresh; `gui/src/components/storage-workspace/StorageWorkspace.tsx:515`","existingCli":"storage codex-logs status --json; observe storage codex-logs status --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T10","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T10 — Protect logs compat / quiet; `gui/src/components/storage-workspace/StorageWorkspace.tsx:251`, `:261`, `:460`","existingCli":"storage codex-logs protect --mode compat/quiet --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-T11","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-T11 — Remove log protection / repair protection / compact logs; `gui/src/components/storage-workspace/StorageWorkspace.tsx:440`, `:463`","existingCli":"storage codex-logs unprotect/repair/compact --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K01","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K01 — List access keys/usage/pending rotations, endpoints, auth matrix, API/audio surfaces; `gui/src/pages/ApiKeys.tsx:155`","existingCli":"access key list --json; access endpoints --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K02","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K02 — Create key with name; `gui/src/pages/ApiKeys.tsx:268`","existingCli":"access key create NAME --json","sourceInventory":"005_operations_coverage.md","disposition":"Existing human-only secret-returning operation; indexed as a family handoff with safe list/get/rotation follow-ups. No agent execution recipe or consent bypass."},
+    {"id":"ops-K03","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp7","evidence":[],"task":"ops-K03 — Rename key; `gui/src/pages/ApiKeys.tsx:327`","existingCli":"access key set edits scopes only","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K04","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K04 — Revoke key; `gui/src/pages/ApiKeys.tsx:302`","existingCli":"access key remove ID --yes --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K05","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K05 — Start rotation; `gui/src/pages/ApiKeys.tsx:349`","existingCli":"access key rotate ID --json","sourceInventory":"005_operations_coverage.md","disposition":"Existing human-only secret-returning operation; indexed as a family handoff with safe list/get/rotation follow-ups. No agent execution recipe or consent bypass."},
+    {"id":"ops-K06","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K06 — Commit rotation / abort rotation; `gui/src/pages/ApiKeys.tsx:371`","existingCli":"access key rotate commit ID ROTATION-ID --json; rotate abort ID ROTATION-ID --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K07","domain":"operations","baseline":"DISCOVERY_ONLY","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K07 — Read public external-model catalog; `gui/src/pages/ApiKeys.tsx:192`","existingCli":"access models --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K08","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp7","evidence":[],"task":"ops-K08 — Test newly created key on Responses / Chat / Messages for selected model; `gui/src/pages/ApiKeys.tsx:443`, `:456`","existingCli":"access test MODEL --protocol responses/chat/messages --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K09","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K09 — Read generated client configuration / copy snippet; `gui/src/components/apikeys-workspace/ClientConfigRow.tsx:53`","existingCli":"inspect client-config --client ID --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K10","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K10 — Toggle public Messages API; `gui/src/pages/api-surface-cards.tsx:52`","existingCli":"api policy --messages on/off --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K11","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K11 — Preview model's protocol path/features; `gui/src/components/protocols/ProtocolPlanPanel.tsx` → `gui/src/protocol-api.ts:91`","existingCli":"api explain --model ID --inbound responses/chat/messages --feature FEATURE [repeated] --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-K12","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp7","evidence":[],"task":"ops-K12 — Dictation file upload and cancel; `gui/src/components/apikeys-workspace/AudioApiPanel.tsx:2`; `gui/src/audio-api-client.ts:13`","existingCli":"No scoped audio CLI identified in supplied CLI inventory","sourceInventory":"005_operations_coverage.md","disposition":"Included task; target/contract resolved in operational crux decision."},
+    {"id":"ops-K13","domain":"operations","baseline":"UNKNOWN","status":"pending","unit":"wp7","evidence":[],"task":"ops-K13 — Live voice connect/disconnect probe; `gui/src/audio-api-client.ts:88`","existingCli":"No scoped live-audio probe identified in supplied CLI inventory","sourceInventory":"005_operations_coverage.md","disposition":"Included task; target/contract resolved in operational crux decision."},
+    {"id":"ops-K14","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-K14 — Download generated client configuration; `gui/src/components/apikeys-workspace/ClientConfigPanel.tsx:78`","existingCli":"export --client ID --out PATH [--force] [--json]","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-R01","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp6","evidence":[],"task":"ops-R01 — Hub devices/runtime availability/session status; `gui/src/pages/RemoteWorkspace.tsx:93`","existingCli":"remote-workspace status is executor-local","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-R02","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-R02 — Create device enrollment code; `gui/src/pages/RemoteWorkspace.tsx:172`","existingCli":"remote-workspace pair consumes enrollment code","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-R03","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-R03 — Start hub model session on selected remote root; `gui/src/pages/RemoteWorkspace.tsx:184`","existingCli":"No CLI proposed","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-R04","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-R04 — Submit prompt to bound session; `gui/src/pages/RemoteWorkspace.tsx:208`","existingCli":"No CLI proposed","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-R05","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-R05 — Stop session; `gui/src/pages/RemoteWorkspace.tsx:243`","existingCli":"No CLI proposed","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-R06","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-R06 — Revoke device and stop its sessions; `gui/src/pages/RemoteWorkspace.tsx:256`","existingCli":"No CLI proposed","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-R07","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp6","evidence":[],"task":"ops-R07 — Read individual Hub runtimes/sessions endpoints","existingCli":"No Hub runtime/session list command","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-L01","domain":"operations","baseline":"COMPLETE","status":"complete","unit":"wp2","evidence":["022_discovery_verification.md","src/cli/capabilities.ts","skills/ocx/references/01_management_surface.md"],"task":"ops-L01 — Read link topology/status; `gui/src/pages/RemoteLink.tsx:186`","existingCli":"link status --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-L02","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-L02 — Discover/rescan SSH aliases; `gui/src/pages/RemoteLink.tsx:262`","existingCli":"No CLI proposed","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-L03","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-L03 — Probe host key; `gui/src/pages/RemoteLink.tsx:282`","existingCli":"No CLI proposed","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-L04","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-L04 — Accept shown fingerprint and validate remote OCX; `gui/src/pages/RemoteLink.tsx:298`","existingCli":"No CLI proposed","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-L05","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-L05 — Home adds child; `gui/src/pages/RemoteLink.tsx:313`","existingCli":"link issue is existing lower-level admin primitive","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-L06","domain":"operations","baseline":"EXCLUDED","status":"pending","unit":"wp8","evidence":[],"task":"ops-L06 — Standalone child joins Home and restarts; `gui/src/pages/RemoteLink.tsx:333`","existingCli":"No CLI proposed","sourceInventory":"005_operations_coverage.md"},
+    {"id":"ops-L07","domain":"operations","baseline":"IMPLEMENTATION_GAP","status":"pending","unit":"wp6","evidence":[],"task":"ops-L07 — Disconnect link / force-remove after remote cleanup failure; `gui/src/pages/RemoteLink.tsx:371`, `:422`","existingCli":"link revoke --link-id ID --json","sourceInventory":"005_operations_coverage.md"},
+    {"id":"set-S06","task":"Memory extraction and consolidation model settings","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","existingCli":"No dedicated live block writer","sourceInventory":"gui/src/pages/dashboard-overview-panels.tsx:24; gui/src/components/MemoryModelsPanel.tsx:111","evidence":[],"unit":"wp5"},
+    {"id":"set-S07","task":"Compaction route model, effort, triggers and source scope","domain":"settings","baseline":"IMPLEMENTATION_GAP","status":"pending","existingCli":"No dedicated live block writer","sourceInventory":"gui/src/pages/dashboard-overview-panels.tsx:23; gui/src/components/CompactionRoutingPanel.tsx:180","evidence":[],"unit":"wp5"}
+  ]
+}
diff --git a/devlog/_plan/261003_cli_gui_parity/009_roadmap_lock.md b/devlog/_plan/261003_cli_gui_parity/009_roadmap_lock.md
new file mode 100644
index 00000000000..74a1fd03698
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/009_roadmap_lock.md
@@ -0,0 +1,22 @@
+# wp0 roadmap lock
+
+The source-audited CLI parity roadmap is locked for implementation. It assigns 178 GUI task-entry rows, including explicit aliases/exclusions, to eight executable work phases and six manual PR layers. No production source was changed in wp0.
+
+Whole-plan architecture reflection passed at a095a4e514d6d8e5a37dbf05a66b2c9156ebaeeb28a8e0fb878bc76f931c27b1. The later bounded key-test contract received the same architect's ALIGNED reflection at be1f17444ce9d83b230ee8ab33bf9e5357623a5fef77f27134eb39062448031f. Exact metadata JSON projection ownership was made explicit. Both independent plan reviews ended PASS after their recorded amendments; detailed analysis stays in ignored task scratch.
+
+Verification before implementation: docs checker validates all eight phase specs, 178 unique IDs, phase/alias ownership, source anchors and document bounds. Existing baseline contract tests/typecheck/structure/generated surface results are recorded in 003; they are not evidence that future commands work. Independent reviewers additionally verified selected existing resolver/parser/GUI fixture contracts with no live targets.
+
+Next: wp1 revalidates 010 against the latest integration base, then implements pure discovery and generated-document capacity. Every later phase keeps its assigned functionality and evidence obligations. No source implementation, PR publication or final product completion is claimed by this roadmap lock.
+
+## Locating the review and check evidence
+
+Task-local artifacts (intentionally ignored, not public security working notes):
+
+- `.tmp/cli-parity/architect-reflection.md`: whole-plan ALIGNED and final CP-DATA-01/02 ALIGNED, reviewer handle 01a1021d-2d94-7d20-95c1-a18da31958a8.
+- `.tmp/cli-parity/audit-roadmap.md`: independent roadmap re-audit PASS, no remaining blockers, reviewer 01a10243-08df-7542-b1ff-57b2b08918e9.
+- `.tmp/cli-parity/audit-security.md`: independent scoped planning re-audit PASS for be1f1744, no remaining planning blockers, reviewer 01a10243-09a5-76e2-91c6-097f65e474b5. This is not code-security certification.
+- `.tmp/cli-parity/fresh-reader.md` or the retained Euclid response (01a1025d-7ebb-7bc2-96f5-6c37cd0c6cf7): delivery/grounding/next-step read was clear; requested exact evidence locators, added here.
+- Check command: `python3 .tmp/cli-parity/check-plan.py` → exit 0, `PASS: 8 phase specs, 178 unique ledger IDs, valid phase/alias ownership, source anchors, no invented completion, bounded docs`.
+- Source-bound Check receipt: `.codexclaw/evidence/01a10024-8d6f-7500-b528-38212c4bc396/test-receipt.json`, produced by `cxc receipt test --session 01a10024-8d6f-7500-b528-38212c4bc396 -- python3 .tmp/cli-parity/check-plan.py`.
+
+These artifacts establish plan validation only. The later implementation phases must produce their own current-source tests, CLI QA and public PR/CI evidence.
diff --git a/devlog/_plan/261003_cli_gui_parity/010_discovery_foundation.md b/devlog/_plan/261003_cli_gui_parity/010_discovery_foundation.md
new file mode 100644
index 00000000000..1013985bee9
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/010_discovery_foundation.md
@@ -0,0 +1,59 @@
+# wp1 — Keep discovery pure and make room for complete task documentation
+
+Depends on wp0. Class C3. Layer 1. No management behavior or user-state changes. Outcome: the existing 74 declarations remain compatible while metadata, exact usage and generated chapters can grow without breaking import or file-size boundaries.
+
+## Exact change map
+
+| Kind | Path | Before → after |
+| --- | --- | --- |
+| NEW | src/cli/capability-types.ts | Move CapabilityRoute, CapabilityFlag, CapabilityJsonMode, Capability and HeadCapability declarations here; add only optional readonly usage?: string. No runtime imports. |
+| NEW | src/cli/capabilities-base.ts | Move existing HEAD_CAPABILITIES and CAPABILITIES literal data byte-faithfully; type-only imports from capability-types. No handler/config/Lab dependencies. |
+| MODIFY | src/cli/capabilities.ts | Preserve public type/function/array export names and existing order. Aggregate/re-export pure data only. capabilityInvocation remains canonical token joining; exact usage is a separate rendering concern. |
+| MODIFY | src/cli/capabilities-command.ts | Its explicit JSON projection currently drops unknown metadata fields. Add usage only when cap.usage is defined; preserve every existing field and no-usage shape. |
+| MODIFY | src/cli/help.ts | For a leaf with usage, render its exact Usage line and omit only that leaf's incomplete-operand warning. With no usage, preserve existing Command/partial-grammar output exactly. Matching and aliases stay in help-catalog. |
+| MODIFY | scripts/generate-ocx-skill-surface.ts | Export deterministic renderManagementSurfaces() returning a filename→text map; retain renderManagementSurface() as the index renderer for existing callers. Write/check compact 01_management_surface.md plus flat 01_surface_<domain>.md chapters. Canonical capability headings do not change; optional usage appears beneath. |
+| MODIFY | tests/cli/cli-capabilities.test.ts | Replace the no-relative-import syntax assertion with a stronger transitive pure-data allowlist boundary; no command/config/Lab import, dynamic import or unexpected dependency. Preserve all rendering/route/debt assertions. |
+| NEW | tests/cli/cli-capability-data.test.ts | Exercise graph refusal fixtures, type-only edges, optional usage JSON/rendering compatibility, aliases and default output. Exercise runCapabilities --json itself with an explicit usage fixture; a helper-only rendering check cannot certify serializer propagation. |
+| MODIFY | tests/ci-workflows/skill-ocx.test.ts | Compare every generated file to its owner map; index links resolve; every capability appears once across chapters. Scan all shipped references for command/consent rules, not only the old five-file list. |
+| NEW | structure/cli-management.md | Move existing CLI help/capability/management-client contracts from runtime into this owner; preserve factual content and links. Describe pure metadata and generated chapter contract after it exists. |
+| MODIFY | structure/runtime.md, structure/manifest.json, structure/INDEX.md | Replace moved prose with explicit owner links; add Tier 5 CLI doc with src/cli ownership and regenerate index. Do not raise 600-line cap or describe unbuilt phases as implemented. |
+| MODIFY/NEW | skills/ocx/references/01_management_surface.md, 01_surface_<domain>.md, skills/ocx/SKILL.md | Index/domain navigation replaces one growing generated blob. Remove 'safe at any time' blanket claims; distinguish non-config-mutating probes from cost-free observation. |
+
+Chapter domains are stable command-family groups: lifecycle, providers-models, accounts, agents-routing, integrations, observe-system, access-remote, lab. Resolve each root into exactly one group; unknown roots fail generation instead of disappearing. The index includes all canonical invocation links and derived counts. Generated filenames are a closed owner-produced set; check fails for missing/stale content. No arbitrary filesystem cleanup.
+
+## Field chain and safeguards
+
+usage literals → pure typed metadata → additive capabilities JSON → help and generated reference. No persisted deserializer is introduced. Existing omissions serialize as before. Help consumers do not import execution modules. Metadata purity is a test-time static import-graph assertion (E3), not a sandbox: dynamic evaluated code can evade a naive scanner, so disallow dynamic imports/require in these modules and keep literal-data review. Runtime enforcement layer: none; wording is 'checked dependency boundary'.
+
+## Acceptance
+
+- Original capability/HEAD JSON is identical except intentionally absent optional fields; count/order/root aliases unchanged.
+- A verified usage leaf renders operands; a legacy leaf retains exact prior help; alias resolution and recovery destinations stay canonical.
+- A synthetic data module importing a handler/config/Lab fails the graph guard; legal data/type edges pass.
+- Regeneration then --check succeeds; a changed/missing generated chapter fails; counts derive from arrays, never handwritten totals.
+- All generated chapters <2000 lines and structure docs ≤600; existing source caps are unchanged.
+- Focused commands: baseline four contract files plus new cli-capability-data and existing cli-help-paths/navigation/recovery files. No GUI render/build is needed; real CLI help and machine-output QA remains required.
+
+## Shared completion contract
+
+This phase follows 002_terminal_ux.md and 003_verification_strategy.md. Main owns registry/dispatch integration, layout-map registration, generated output and Git branch state; executor write scopes are disjoint and named before B. Existing method/path/body semantics come from the referenced source inventories, not endpoint-name guessing.
+
+Update the phase's capability domain, generated references, relevant public CLI pages and owning structure contracts in the same layer. Every new test file enters scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Existing tests are retained; no baseline cap increases or green-on-retry acceptance.
+
+Planned new test paths below become executable verification only after B creates them. The current baseline gates in 003 have actually run. C invokes the exact focused files, typecheck, structure and skill-surface checks, privacy where data is handled, a source-bound cxc receipt and real isolated CLI QA (stdout/stderr/exit/teardown). A successful function mock is transport proof only; relevant existing server tests or isolated real handlers verify accepted state. No live user proxy, credentials or upstream requests.
+
+Before P>A, revalidate this document against the parent layer and record the prior D conclusion. Consult an architect for actual decision changes; independent A review is separate. C must preserve saved-versus-applied/refused outcomes. D records exact checks and ledger evidence before the next cycle. Publishing is main-owned; this request stops at open PRs.
+
+## wp1 execution refinements (same-architect stale check)
+
+The exact pure-data graph initially contains only capability-types.ts, capabilities-base.ts and the capabilities.ts facade. Types has no imports/runtime initializer; base imports types only; facade imports/re-exports base values and types while retaining the three existing pure helpers. Use an explicit allowlist, not a wildcard that also admits capabilities-command.ts. The test-owned scanner handles imports, side-effect imports, re-exports and type edges, rejects unresolved/bare/outside/cyclic/computed loads, and ignores comment/string lookalikes. Reuse the existing narrow tokenization seam in tests/helpers/warmup-tokens.ts or a proven Bun scanner; do not assume a TypeScript 5 parser exists under this repository's native TS7 tooling. The same predicate must run against real files and bad/good fixtures. It checks dependencies, not arbitrary-code sandboxing.
+
+All shipped capability literals remain byte-faithful in wp1. Exercise a present usage value by adding a temporary property to a real existing leaf only inside an isolated Bun subprocess, then invoke actual runCapabilities JSON/help/generator consumers. A separate unmodified process checks absence compatibility. No production setter, synthetic command or shared-test global mutation.
+
+Closed chapter map for current roots: lifecycle={chatgpt,status,resolve,capabilities,sync}; providers-models={provider,models}; accounts={account}; agents-routing={agent,combo}; integrations={claude,integration}; observe-system={companion,usage,logs,storage,inspect,system}; access-remote={link,remote-workspace,hub,connect,api}; lab is an honestly empty reserved chapter until wp2. Unknown roots fail and wp2 extends the map deliberately. Preserve global invocation order in the index and original per-chapter order. Keep each old canonical index fragment as a short forwarding heading/link, so existing file-plus-fragment references continue to work. Test exact file+anchor reachability and collisions, not only substring presence.
+
+The generator checks the expected map and rejects extra owner-marked 01_surface_*.md files; it does not delete unrelated or stale files automatically. Scan every actually shipped reference Markdown for command/consent safety. SKILL may reach chapters through its index; test transitive navigation rather than require every chapter to be linked at the top level.
+
+Structure extraction is deliberately narrow: move substantive runtime CLI-readiness content and the two detailed head/help/catalog table contracts into cli-management.md. Keep old runtime headings and concise pointers to preserve anchors. Leave executable lifecycle ownership in runtime. Review the other mapped CLI docs; unchanged accurate contracts do not need copied prose. Register the new Tier 5 owner, stage paths before structure:check and regenerate INDEX through its owner script.
+
+Implementation leaves: (1) metadata/types/facade/serializer/help + CLI tests; (2) generator/skill/generated chapters + skill workflow tests. Main owns structure docs, both test-layout maps, integration/commits and all branch operations. Neither leaf edits the other's paths or runs a global typecheck while the other is writing.
diff --git a/devlog/_plan/261003_cli_gui_parity/011_foundation_revalidation.md b/devlog/_plan/261003_cli_gui_parity/011_foundation_revalidation.md
new file mode 100644
index 00000000000..6d0ad53fbab
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/011_foundation_revalidation.md
@@ -0,0 +1,15 @@
+# wp1 revalidation
+
+Previous D direction from 009: wp1 revalidates 010 against the latest integration base, then implements pure discovery and generated-document capacity. No change of direction is needed.
+
+Current source baseline for wp1 is aa720907314ed2c5ca68f5c22d851148d66b1d0d, merging dev a141b83623a3f1677f23477e91b9a42a74f495f7 after the docs-only cycle. Incoming changes concern native upload bytes, Ollama commentary replay and test-layout cleanup. Comparing the audited 9f89b7265b baseline to this tree found no changes in src/cli, the skill generator/skill files, structure/runtime.md or structure/manifest.json. The exact 010 source/consumer design remains applicable.
+
+The independent wp0 audit already corrected the explicit capabilities-command JSON projection owner. Current 010 includes that edit and a real serializer test; no helper-only proof is substituted. Optional usage leaves canonical invocation matching unchanged. The phase remains a pure metadata/documentation foundation with no management authority or runtime mutation change.
+
+Current test-layout baseline was checked because the incoming integration commits changed both layout maps. New tests will be registered against these current maps rather than copied from the earlier baseline. The original structure owner is at its 600-line cap, so the mapped CLI contract move stays necessary.
+
+The existing whole-unit architect proposal and concrete ALIGNED reflection cover CP-ARCH-02/04 and CP-SIZE-01 for 010. A bounded same-architect wp1 stale-check is requested; its resulting refinements and reflection will be recorded before A. Independent plan audit and actual B/C implementation proof are still required.
+
+Same-architect wp1 proposal confirmed all relevant committed seams unchanged and supplied exact export/edge roles, isolated usage fixtures, closed chapter ownership/link preservation and minimal structure extraction. Main accepted these under existing CP-ARCH-02/04 and CP-SIZE-01 and appended them to 010; no new framework or authority was introduced. Current layout baseline: 18 pass, 0 fail, 555 assertions. Concrete refinement is returned to that same architect before independent wp1 A.
+
+Same-architect reflection is ALIGNED for the concrete wp1 refinement (010 digest 11a4dd5ac83fe3578d580e9faea64f5882fb0f21092b12a7524cef1298511212). Artifact: `.tmp/cli-parity/wp1-reflection.md`. CP-ARCH-02, CP-ARCH-04 and CP-SIZE-01 have no essential mismatch; implementation and independent A/C proof remain separate.
diff --git a/devlog/_plan/261003_cli_gui_parity/012_foundation_verification.md b/devlog/_plan/261003_cli_gui_parity/012_foundation_verification.md
new file mode 100644
index 00000000000..e9952330bdc
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/012_foundation_verification.md
@@ -0,0 +1,27 @@
+# wp1 implementation and verification
+
+The discovery foundation is implemented: capability types and literal data have separate owners behind the stable facade; optional exact usage reaches the real JSON/help renderers; generated operating references have a compact index and eight bounded domain chapters. The 74 existing capability rows and two HEAD rows preserve their values and ordering. This phase adds capacity and correctness checks, not the later GUI task commands.
+
+## Observed checks
+
+| Check | Result / scope |
+| --- | --- |
+| Capability boundary and actual consumer tests | 71 pass, 0 fail, 597 assertions across cli-capability-data, cli-capabilities and cli-capabilities-arguments after review repairs. |
+| Existing CLI help regressions | 47 pass, 0 fail; actual alias/fallback/root behavior retained. |
+| Generated skill/reference tests | 21 pass, 0 fail, 617 assertions; missing/stale/extra owned files, fragment links, usage and limits exercised. |
+| Current test-layout maps | 18 pass, 0 fail, 555 assertions; both new test files registered. |
+| Integrated typecheck | exit 0 after the final helper repair. |
+| Actual metadata comparison | All original fields and ordering match the captured pre-source-change JSON. |
+| Generated source check | All nine generated files are current. |
+| Structure owner/index | Generated INDEX and structure checks passed after owned files were staged. Other mapped CLI contracts were inspected and remained accurate; only the affected runtime/release pointers changed. |
+| Staged whitespace | passed after removing two trailing blank EOF lines in new files. |
+
+The new dependency checker is deliberately limited to an admitted metadata grammar. Refusal fixtures cover computed/ambiguous expressions, loader aliases and reserved ambient host bindings. Independent implementation re-review is PASS with no remaining findings; exact probes and unchanged production hashes are recorded in the private review evidence. Harmless quoted data remains supported. This does not certify arbitrary JavaScript as sandboxed, and the existing metadata contains none of those loader forms.
+
+## Evidence and C gate
+
+Worker records: `.codexclaw/evidence/wp1-metadata-worker.md`, `wp1-f1-repair.md`, `wp1-f1-r2-repair.md`, and `wp1-surface-worker/verification.json`. Main integration logs use `.tmp/cli-parity/wp1-*`; the independent implementation review is `.tmp/cli-parity/wp1-code-review.md`. Actual CLI QA captures stdout/stderr/exit under this session's `qa/parity-wp1` evidence directory, with network denied and isolated configuration homes. Bun's private transpilation cache is accounted separately from application configuration and removed with the test sandbox.
+
+Final C receipt and review disposition remain separate from worker reports. Full/changed local suites were not run: focused scope is recorded above, and broad/platform verification belongs to each published PR's current-head hosted CI. No user proxy, credentials, paid upstream or client configuration was operated on.
+
+Next work phase consumes 020 to declare already-working tasks, add exact synopses and improve operating recipes; the base still has the original 74 declarations at this checkpoint.
diff --git a/devlog/_plan/261003_cli_gui_parity/020_existing_workflow_discovery.md b/devlog/_plan/261003_cli_gui_parity/020_existing_workflow_discovery.md
new file mode 100644
index 00000000000..ce0cfc9c806
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/020_existing_workflow_discovery.md
@@ -0,0 +1,47 @@
+# wp2 — Declare the operational CLI that already exists
+
+Depends on wp1. Class C3. Finish layer 1. Outcome: users/agents can discover existing task-specific verbs and exact operands without reverse-engineering source, while false route claims are removed rather than propagated.
+
+## Exact change map
+
+NEW pure data leaves: src/cli/capabilities-provider-models.ts, capabilities-accounts.ts, capabilities-agents-routing.ts, capabilities-integrations.ts, capabilities-observe-system.ts, capabilities-access-remote.ts, capabilities-lab.ts. Keep the original 74 entries in capabilities-base.ts; main adds exact usage and reviewed corrections there. MODIFY capabilities.ts to append seven new unique arrays after the baseline in the listed domain order. Leaves import only Capability types, never handlers. Preserve baseline row reference identity and relative order; full facade/base array identity intentionally ends with aggregation. Do not hide duplicates through last-wins merging.
+
+Use the command/route/flag matrix in the source inventory and 004/005: provider edit/test/quota/presets/account-mode/selected; models live/edit/visibility/selected/presets/new-policy/context/shadow; alias; combo CRUD; route-policy reads; account/current/switch/auth and policy leaves; agent and v2; client/Desktop/Grok operations; storage/debug/usage/system; access/remote and actual local Lab commands. Internal/hidden executables remain excluded. Only implemented leaves are declared in this phase; later missing actions are not advertised early.
+
+MODIFY src/cli/registry.ts and help.ts to remove the incorrect 'read-only Lab' description and reflect supported public groups. No new handler dispatch is introduced. Exact usage strings come from inspected handlers; flags which take values remain distinct from booleans. Add details for local versus management transport, user confirmation, caller-spend probes and safe read-back sequences.
+
+MODIFY src/server/management/route-registry.ts and tests/cli/cli-capabilities.test.ts only with evidence: shrink declaration debt when real HTTP calls are registered; do not invent HTTP calls for local provider/custom-model/Lab commands. Correct stale Lab 'no CLI' reasons to the actual local equivalent or narrower remaining runtime debt. Temporarily mark the falsely advertised timeline/Cursor routes as owned deferred work (wp6/wp7, these tracked phase docs), then remove that temporary debt in the implementing layer. No session-only reason is weakened.
+
+MODIFY skills/ocx/SKILL.md and references/02_json_shapes.md, 03_recipes.md, 04_failure_semantics.md, 05_remote_hub.md. Preserve consent/secret handoff rules. Correct incomplete discovery examples once indexed; distinguish legacy 64 usage errors, missing JSON support and local/live target semantics. Generated chapters are regenerated, not hand edited. Public docs reference/cli.md and reference/cli/{providers-accounts,agents,lifecycle}.md are the verified existing topic pages; extend the appropriate one rather than inventing a parallel root.
+
+NEW tests/cli/cli-capability-workflows.test.ts and tests/ci-workflows/skill-ocx-workflows.test.ts compare declared operand/flag examples with independently specified representative real handler invocations on isolated fixtures. Preserve the existing route ratchet, negative CLI argument tests and skill secret checks. Complete grammar is not proven by testing only the first word.
+
+## Acceptance
+
+Each baseline DISCOVERY_ONLY row has a canonical capability/help path and a task recipe or clear reference. Each declared management method/path is actually driven by that command; local equivalents use routes:[] plus honest transport detail. Capabilities --route works for newly indexed HTTP operations. No empty route lookup is misreported as proof of feature absence.
+
+Human-only and secret-returning tasks remain handoffs. No examples spend live quota, create keys, pair machines, star GitHub or copy plaintext credentials into agent transcripts. Unknown child help and --help remain offline and write-free. Metadata/skill tests, pure import boundary, route registry, structure, privacy and generated-surface check must pass before layer 1 publication.
+
+## Shared completion contract
+
+This phase follows 002_terminal_ux.md and 003_verification_strategy.md. Main owns registry/dispatch integration, layout-map registration, generated output and Git branch state; executor write scopes are disjoint and named before B. Existing method/path/body semantics come from the referenced source inventories, not endpoint-name guessing.
+
+Update the phase's capability domain, generated references, relevant public CLI pages and owning structure contracts in the same layer. Every new test file enters scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Existing tests are retained; no baseline cap increases or green-on-retry acceptance.
+
+Planned new test paths below become executable verification only after B creates them. The current baseline gates in 003 have actually run. C invokes the exact focused files, typecheck, structure and skill-surface checks, privacy where data is handled, a source-bound cxc receipt and real isolated CLI QA (stdout/stderr/exit/teardown). A successful function mock is transport proof only; relevant existing server tests or isolated real handlers verify accepted state. No live user proxy, credentials or upstream requests.
+
+Before P>A, revalidate this document against the parent layer and record the prior D conclusion. Consult an architect for actual decision changes; independent A review is separate. C must preserve saved-versus-applied/refused outcomes. D records exact checks and ledger evidence before the next cycle. Publishing is main-owned; this request stops at open PRs.
+
+## wp2 execution refinement
+
+Exact new exports, in aggregate append order: PROVIDER_MODEL_CAPABILITIES, ACCOUNT_CAPABILITIES, AGENT_ROUTING_CAPABILITIES, INTEGRATION_CAPABILITIES, OBSERVE_SYSTEM_CAPABILITIES, ACCESS_REMOTE_CAPABILITIES, LAB_CAPABILITIES. Import original base CAPABILITIES under a local alias; export one stable readonly aggregate. Existing public types, HEAD identity and three query helpers stay unchanged; helpers must inspect the aggregate. Leaf arrays are implementation details, not new facade exports.
+
+Extend tests/helpers/cli-capability-data.ts with seven exact owner filenames and role edges: each new leaf imports Capability types only; the facade imports those named values. Preserve restricted grammar, bad-edge/cycle/host/ambiguous-expression refusals and all prior negative fixtures. Update tests/cli/cli-capability-data.test.ts deliberately: baseline rows remain once, first and referentially identical; appended rows equal explicit leaf ownership; duplicate canonical keys fail. Remove only the no-longer-true full-array equality and universal no-usage assumption. Isolated fixtures still force both absent and present usage through real JSON/help, so legacy fallback coverage survives actual metadata growth.
+
+Main alone updates existing base entries from source-anchored worker proposals. Do not clone/rewrite all literals, reorder baseline rows or claim a local operation fetches HTTP. First-order field corrections and synopsis additions are static data, not a metadata registration framework.
+
+Progressive skill discovery starts with offline root/family/leaf help and the needed chapter. Full capabilities JSON is optional for an actual broad inventory; exact route lookup remains available and matches declared templates. Readiness/version checks apply before live management work, not offline help or explicitly local operations. Add --json only where the command's declaration/handler supports it. No new filtering flag or global output/error migration.
+
+Secret-returning human-only actions remain discoverable as family descriptions and handoffs, with safe follow-up leaves. Do not emit literal creation/rotation-start invocation or usage alternatives as executable-looking recipes in generated headings. Do not exempt generated pages from existing secret detectors or obscure spellings to evade them. Human-only task ledger rows remain accounted for rather than dropped.
+
+Worker scopes: A owns new provider-model/account leaf files and uniquely named tests; B owns new agent-routing/integration/Lab leaves and tests; C owns new observation-system/access-remote leaves and tests. Each returns scratch proposals for existing base rows and source anchors, without editing base/facade/guard/generator/registry/maps. A single docs leaf owns handwritten skill and existing public CLI pages. Main integrates all shared files and generated chapters after writers settle, checks exact method/route truth and records task coverage. All code/skill examples cover existing implementations only; future wp3..7 flags are not advertised yet.
diff --git a/devlog/_plan/261003_cli_gui_parity/021_discovery_revalidation.md b/devlog/_plan/261003_cli_gui_parity/021_discovery_revalidation.md
new file mode 100644
index 00000000000..66578c52ae9
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/021_discovery_revalidation.md
@@ -0,0 +1,9 @@
+# wp2 revalidation and consultation
+
+Previous D: wp1 foundation completed at 167881a850 with stable original metadata, generated-domain capacity, independent code review PASS and ten real offline CLI scenarios. Its final source-bound gate passed 67 structure/hygiene tests plus generated-surface/privacy checks. The source-bound receipt was archived before continuing.
+
+wp2 consumes 020. Current integration is 77ac2a93d2, merging dev e601cefcebcc20b2e04a04821ab45df6538d98f9. Only both test-layout maps conflicted; resolution retained the upstream maps and the two new foundation test registrations, without reviving retired entries. Incoming source changes concern provider/account/transport behavior and do not change the CLI/generator/skill seams this phase declares. Source anchors in the baseline inventories remain historical; workers verify actual handlers before declaring a verb.
+
+The same architect proposed keeping baseline data first and appending seven unique arrays, instead of rewriting/moving unchanged objects for grouping. Main accepts CP-ARCH-02's incremental composition, CP-ARCH-04's actual serializer/absent-present fixture coverage, CP-INTEGRATION-01's progressive task discovery and human handoffs, and CP-SIZE-01's closed generated map. Exact write ownership and export/guard changes are appended to 020. Concrete reflection and independent A precede implementation.
+
+Same-architect reflection is ALIGNED for concrete020 digest53ed87a26394cd0c5d5ae2fee9983d55042ad94385e68982bbbd950b8d3bfc49, covering incremental aggregation, actual JSON/fallback proof, human-only descriptions and disjoint ownership. Artifact: `.tmp/cli-parity/wp2-reflection.md`. The current layout baseline passed18 tests/555 assertions; no full local suite ran.
diff --git a/devlog/_plan/261003_cli_gui_parity/022_discovery_verification.md b/devlog/_plan/261003_cli_gui_parity/022_discovery_verification.md
new file mode 100644
index 00000000000..cad505c7709
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/022_discovery_verification.md
@@ -0,0 +1,29 @@
+# wp2 — Existing workflow discovery verified
+
+The existing CLI is now indexed by task: 289 capability entries replace the former 74-entry partial index. The original 74 rows retain their identity/order, seven pure domain leaves append existing workflows, and verified synopses distinguish local configuration from live management requests. This closes the ledger's 104 existing/discovery rows. It does not implement the missing GUI operations assigned to wp3–wp7.
+
+## Delivered behavior
+
+Offline leaf help includes actual operands, flags and output semantics. Eight generated chapters give the operating skill a progressive task entry point; the root index retains existing anchors. Handwritten examples use real parser-supported invocations, saved-versus-applied read-back and explicit authority for side effects. Public English CLI pages and contradictory claims in seven translations are synchronized.
+
+Timeline and Cursor routes previously appeared in metadata despite having no caller; they now have explicit roadmap debt. Lab descriptions acknowledge existing local controls without claiming those commands manage a selected running server. The PATCH pool-settings alias remains a server compatibility path; actual CLI writes use PUT. The bidirectional route debt guard still rejects unexplained new routes and stale exemptions.
+
+## Independent review and repairs
+
+Two inherited-model reviewers independently inspected the seven domain tables and main integration against handlers. Both finished with PASS after four material corrections: JSON reads require explicit key-list/companion-show actions; selected-model reads use CLI envelope metadata and document write receipts separately; secret-returning link/Hub/raw-export operations have prose handoffs instead of generated usage recipes; routing evaluation examples disclose Lab activation and already-enabled automation. Tests exercise the actual parser/output cases, omitted-action refusal, and accidental secret usage injection. No credential-bearing operation was executed.
+
+Private review receipts are `.tmp/cli-parity/wp2-review-discovery.md` and `wp2-review-integration.md`. Their prior FAIL sections remain historical; the final re-review verdict is PASS. Production authentication, credential storage, provider behavior and handlers are unchanged.
+
+## Verification and limits
+
+The integrated focused set passed 266 tests before the review repairs. The repaired provider read/write tests passed 31 cases; the final help/access repair set passed 35. The 97-case metadata/help/file-size set passed. New regressions retain the full negative dependency/host-import grammar fixtures and absent/present usage consumer coverage rather than replacing them with self-matching metadata assertions. Both layout maps register all eight new test files.
+
+Typecheck, structure ownership, privacy and whitespace checks passed during integration. Public docs built 561 pages and checked 77,947 internal links. The final source-bound receipt is archived under `.codexclaw/evidence/01a10024-8d6f-7500-b528-38212c4bc396/`; final command/output and commit identity accompany the PR.
+
+Seventeen actual CLI subprocess scenarios passed with closed stdin, network denial, isolated application homes and color disabled. They cover root/full/nested/alias help, provider/account/sidecar/Lab/storage/access tasks, repeated help, capability JSON, a known route lookup, empty/unmatched route errors and an unknown root. Main read the provider-edit and key-family output: required operands, clear sentinels, live/local distinction and human-only handoff are visible; no arbitrary model/credential values were introduced. Root help remains compact. The full JSON inventory is large, so the skill deliberately starts with the needed family/chapter. Teardown recorded zero network attempts, unchanged application configuration and removal of the temporary home; isolated Bun compilation cache writes are accounted for.
+
+Local full/changed suites were not run because their resource cost is disproportionate for this metadata/docs layer across concurrent worktrees. Relevant parser, transport, indirect source-oracle, layout, generated-file and help regressions were exercised. Broad suite and platform proof remains the published PR's exact-head hosted CI obligation; no pending CI is represented as a pass. The QA evidence matrix is `.codexclaw/evidence/01a10024-8d6f-7500-b528-38212c4bc396/qa/parity-wp2/`.
+
+## What did not improve
+
+No missing provider/model/account/settings/integration operation becomes implemented merely by appearing in the inventory. A declared command still needs its own target/version/authority checks; metadata is not execution permission or proof that an arbitrary server accepts every value. Mocked transport tests prove parser requests and output, not universal provider behavior. A remaining counterexample would be a declared synopsis rejected by its actual handler or a route claim without a caller; either must reopen this phase rather than be relabeled as coverage. wp3 starts from the provider-management plan and the verified existing metadata, with a fresh P/A cycle.
diff --git a/devlog/_plan/261003_cli_gui_parity/030_provider_management.md b/devlog/_plan/261003_cli_gui_parity/030_provider_management.md
new file mode 100644
index 00000000000..73834e820dd
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/030_provider_management.md
@@ -0,0 +1,44 @@
+# wp3 — Add exact live provider workflows and bounded structured input
+
+Depends on wp2. Class C3 with C4 review for credential/destination/deletion boundaries. Layer 2. Keep server authority and offline defaults; GUI-equivalent live mutations are explicit.
+
+## New shared input with its first consumer
+
+NEW src/cli/json-input.ts: explicit path or '-' reader with a 4 MiB ceiling matching src/server/management/body.ts:9, bounded stdin deadline, EOF/error cleanup and no TTY wait. Use existing readSecretBytes for injected stdin or existing bounded-body stream utilities; payload labels/errors never include raw JSON or credentials. Decode UTF-8 strictly, allow normal UTF-8 BOM behavior, parse once, expose unknown to the domain shape validator. Duplicate/conflicting sources are rejected before reading. Composite body byte size is checked before sending. No endpoint/method selection comes from input data.
+
+NEW tests/cli/cli-json-input.test.ts: empty/invalid/array/BOM/multiline input, exact cap and cap+1, stdin EOF/error/deadline/TTY refusal, cleanup and no value echo. This helper ships with provider snapshot/apply, not as an unused framework.
+
+## Provider command contracts
+
+| Command | Exact behavior |
+| --- | --- |
+| provider add P ... --live [--json] | Resolve runtime once; load target preset when needed; POST /api/providers {name,provider,setDefault?}. Add --responses-path and --auth-mode to domain parsing. Retain explicit --force overwrite intent and document existing upsert race; no invented atomic create-only guarantee. Reject --live --sync. |
+| provider set-default P --live --json | Standalone PATCH /api/providers?name=P with {setDefault:true}; server rejects disabled/unknown rows. |
+| provider remove P --live --yes --json | One DELETE /api/providers?name=P; disclose default reassignment and credential/custom-model cleanup. No local pre-write, emulated two-step deletion or fallback. |
+| provider edit P --upstream-http-version http1.1\|- --fast on\|off --context-window N\|- | Extend existing PATCH with upstreamHttpVersion (null clear), fastEnabled and provider contextWindow. Existing flags/omission semantics preserved. Per-model context already exists; optional repeated model-context-window only if atomic GUI update needs it. |
+| provider pacing P [--json] | GET provider-request-pacing?name=P, with meaningful no-rules state. |
+| provider pacing P --file FILE [--json] | PATCH only {requestPacing:<validated complete rules>}; domain rules contain enabled and optional provider/model RPM/minIntervalMs/maxConcurrentRequests. Provide common scalar flags for provider-level fields; preserve untouched rules for partial flags using one pinned read. Setting enabled:false disables pacing; per-model rules use the explicit complete rules file, not a speculative clear flag. |
+| provider snapshot --json | GET /api/config and project exactly GUI editor {defaultProvider,providers}, excluding hasApiKey/hasHeaders/xaiResponsesOptInState/initialModelSelection. No secret export. |
+| provider apply --baseline FILE --file FILE --json | PUT /api/providers exactly {baseline,next}; validate DTO shape, no credential/derived fields; preserve stale-baseline 409 and never auto-refresh/rebase. Removal within batch requires --yes with explicit affected scope in help. |
+
+MODIFY src/cli/provider.ts to route --live before local load/save, retain offline defaults and local removal refusal. Correct explicit local --sync --json: call existing syncModelsToCodex with quiet log parameter and report actual saved/synced/skipped/refused disposition; output mode must not cancel a requested effect. No false 'synced' message when stopped/failure. MODIFY provider-runtime.ts for extension dispatch only; NEW provider-lifecycle-runtime.ts, provider-settings.ts and provider-batch.ts own cohesive new behavior. RuntimeApiDeps is injectable; all multi-request workflows pin baseUrl once.
+
+MODIFY runtime-api.ts only for safe nested error code/message projection needed by routing/provider responses, retaining exit mapping/prose stderr. Never dump arbitrary RuntimeApiError.body. Domain failed-convergence output retains safe saved/catalog receipt rather than claiming rollback or unconditional success.
+
+Metadata: capabilities-provider-models.ts, registry usage and generated chapters. Structure: cli-management.md, config.md and existing provider destination contracts as affected; no provider adapter logic change. Public provider docs/skill recipes show snapshot/edit/apply/read-back and explicit live/offline distinction.
+
+NEW tests/cli/cli-provider-lifecycle-runtime.test.ts, cli-provider-settings.test.ts, cli-provider-batch.test.ts. MODIFY the original local provider sync JSON test to the deliberately corrected contract; retain its no-live case. Existing tests/providers/provider-config-batch-management.test.ts supplies server CAS/validation truth.
+
+## Acceptance
+
+Assert exact named requests, pinned target, zero local mutation on live refusal, wrong/missing/duplicate argument rejection before write, scalar omission/null/false/0, target preset handling and stale CAS refusal. Live deletion uses server dependency/default handling. Saved-but-unapplied receipts and missing proxy are honest. Body failures and credential-shaped data never leak. Baseline offline provider behavior stays tested. Explicit security review covers auth headers, input buffers, destination validation reuse and delete scope.
+
+## Shared completion contract
+
+This phase follows 002_terminal_ux.md and 003_verification_strategy.md. Main owns registry/dispatch integration, layout-map registration, generated output and Git branch state; executor write scopes are disjoint and named before B. Existing method/path/body semantics come from the referenced source inventories, not endpoint-name guessing.
+
+Update the phase's capability domain, generated references, relevant public CLI pages and owning structure contracts in the same layer. Every new test file enters scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Existing tests are retained; no baseline cap increases or green-on-retry acceptance.
+
+Planned new test paths below become executable verification only after B creates them. The current baseline gates in 003 have actually run. C invokes the exact focused files, typecheck, structure and skill-surface checks, privacy where data is handled, a source-bound cxc receipt and real isolated CLI QA (stdout/stderr/exit/teardown). A successful function mock is transport proof only; relevant existing server tests or isolated real handlers verify accepted state. No live user proxy, credentials or upstream requests.
+
+Before P>A, revalidate this document against the parent layer and record the prior D conclusion. Consult an architect for actual decision changes; independent A review is separate. C must preserve saved-versus-applied/refused outcomes. D records exact checks and ledger evidence before the next cycle. Publishing is main-owned; this request stops at open PRs.
diff --git a/devlog/_plan/261003_cli_gui_parity/040_models_routing.md b/devlog/_plan/261003_cli_gui_parity/040_models_routing.md
new file mode 100644
index 00000000000..b99b9681b6a
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/040_models_routing.md
@@ -0,0 +1,38 @@
+# wp4 — Complete model, picker, combo and policy editing
+
+Depends on wp3. Class C3; deletion and public routing identities receive focused C4 review. Layer 3.
+
+## Exact change map and contracts
+
+| Files | Before → after / command |
+| --- | --- |
+| NEW src/cli/models-custom-runtime.ts; MODIFY models.ts | `models add P M [existing metadata flags] --live --json` POSTs /api/custom-models. `models remove UUID-or-P/M --live --yes --json` resolves on the same pinned target then DELETEs UUID; no local lookup/fallback. Local add/remove gain truthful JSON save/sync receipts while retaining local behavior. |
+| NEW src/cli/models-order.ts; MODIFY models-runtime.ts, models-runtime-subcommands.ts | Add `models display-name P/M --set TEXT\|--clear --json` → PUT providers/P/model-display-names {modelId,displayName:string\|null}; pricing stays separate. Add `models order status`, `set --models CSV`, `set --mode default\|alphabetical\|provider\|most-used`, `reset`. Write pickerOrder/pickerOrderMode, never featured models. NEW src/cli/model-picker-ordering.ts implements the pure projection grounded in gui/src/model-picker-order.ts:43-92; do not import GUI runtime source into shipped CLI. Known independent sorting fixtures and a test-only GUI/CLI conformance comparison guard the deliberate duplicate projection. Default/reset sends pickerOrder:null and pickerOrderMode:null. Other modes derive a complete order from pickerAvailable plus exact observed identities; most-used fetches all/all usage and refuses usageIncomplete:true. Manual writes preserve featured-prefix constraints and reject ambiguous identities. Preserve native/routed public identities. |
+| MODIFY src/server/management/route-registry.ts | Declare implemented model-display-names PUT with correct regex mechanism/module. Do not change the endpoint. |
+| NEW src/cli/route-policy-write.ts; MODIFY route-policy.ts | `route policy create I --file PROFILE --json` PUTs {id,mode:create,profile}. update requires explicit --expected-revision copied from show; never silently reads a fresh revision or retries conflict. remove requires --yes and DELETE query id. Domain profile file covers alias/candidates/require/optimize/limits/unknownEvidence/compatibility, using existing validation. |
+| MODIFY src/cli/combo.ts (extract combo-input.ts if needed) | Extend set with --image-input auto\|disabled, --reasoning-effort-mode strict\|adaptive, --targets-file FILE and explicit native-alias off while retaining bare legacy flag. Targets preserve reasoningEfforts/modelProfile/lastResort and ordering. Omitted fields remain omitted; defaultEffortMode and reasoningEffortMode stay distinct. |
+| NEW src/cli/combo-stats.ts; wire combo.ts | `combo stats I --range 7d\|30d\|all --json` GET /api/usage with jev=1, comboId, range; show actual decisions/savings and incomplete evidence, not generic model usage. |
+
+Update pure provider-models/agents-routing capabilities, exact usages, generated chapters, CLI model/routing docs and recipes; source owners cli-management/config/catalog/subagents as affected. Do not change routing evaluator/provider algorithms.
+
+NEW tests/cli/cli-models-custom-runtime.test.ts, cli-models-order.test.ts, cli-models-display-name.test.ts, cli-route-policy-write.test.ts, cli-combo-parity.test.ts. Use existing tests/codex-integration/model-display-names-management-api.test.ts, tests/routing/routing-profile-management-editor.test.ts and model metadata regressions for real handler/persistence truth.
+
+## Activation matrix
+
+- Native and routed duplicate model labels remain separate identities; encoded provider/model delimiters survive requests.
+- Display reset sends null; invalid label causes zero accepted write; saved/convergence-failed response remains visible.
+- Ordering shows full current order; manual/policy/default/reset match GUI semantics; most-used consumes the correct usage scope and cannot drop unranked entries.
+- Revision changes between read and update produce 409/exit 5 with no automatic overwrite. Create-existing, update-missing, invalid profile and nonconfirmed delete retain distinct failures.
+- Targets-file and --targets are exclusive; unsupported nested fields/invalid effort/profile are refused. Existing omitted target metadata survives partial edits; scalar effort-mode names do not alias each other.
+- JEV report uses exact query and preserves missing/incomplete totals. No real decision probe/upstream request is part of tests.
+- Local and live custom model branches use different temporary homes/servers; prove no wrong-target writes and preserve catalog-only versus broader local-sync receipts.
+
+## Shared completion contract
+
+This phase follows 002_terminal_ux.md and 003_verification_strategy.md. Main owns registry/dispatch integration, layout-map registration, generated output and Git branch state; executor write scopes are disjoint and named before B. Existing method/path/body semantics come from the referenced source inventories, not endpoint-name guessing.
+
+Update the phase's capability domain, generated references, relevant public CLI pages and owning structure contracts in the same layer. Every new test file enters scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Existing tests are retained; no baseline cap increases or green-on-retry acceptance.
+
+Planned new test paths below become executable verification only after B creates them. The current baseline gates in 003 have actually run. C invokes the exact focused files, typecheck, structure and skill-surface checks, privacy where data is handled, a source-bound cxc receipt and real isolated CLI QA (stdout/stderr/exit/teardown). A successful function mock is transport proof only; relevant existing server tests or isolated real handlers verify accepted state. No live user proxy, credentials or upstream requests.
+
+Before P>A, revalidate this document against the parent layer and record the prior D conclusion. Consult an architect for actual decision changes; independent A review is separate. C must preserve saved-versus-applied/refused outcomes. D records exact checks and ledger evidence before the next cycle. Publishing is main-owned; this request stops at open PRs.
diff --git a/devlog/_plan/261003_cli_gui_parity/050_accounts_runtime_settings.md b/devlog/_plan/261003_cli_gui_parity/050_accounts_runtime_settings.md
new file mode 100644
index 00000000000..2e735ca1b7e
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/050_accounts_runtime_settings.md
@@ -0,0 +1,48 @@
+# wp5 — Complete account policy, login options and model-runtime settings
+
+Depends on wp4. Class C3 with scoped C4 credential/cost/ownership review. Layer 4. Existing v2/account/agent roots remain; no duplicate agent-mode family.
+
+## Account and auth contracts
+
+NEW src/cli/account-policy.ts, MODIFY account.ts/account-extended.ts/account-auth.ts only at owned dispatch/parsing seams:
+
+- `account pool P [--enabled on|off] [--threshold N] [--quota-window W] [--strategy S] [--sticky N] --json`: GET/PUT unified /api/pool/settings. Respect per-provider supported fields; absent fields preserved. Pool enabled is not threshold zero. Existing strategy/sticky/Anthropic per-account commands remain.
+- `account auto-switch openai ACTION --account I --json`: resolve ID/alias/main, PUT /api/codex-auth/auto-switch {id,threshold}; inherit sends null. Without --account preserve existing pool scope.
+- `account credits openai I on|off --json` or `account credits openai --all on|off --json`: exclusive selectors, exact /accounts/credits {id,creditsAfterLimit} or {all}. Clearly name paid-credit opt-in; display preference never implies permission. Read-back is the roster.
+- `account quota-activation openai I --window W on|off --json`: PUT settings {codexQuotaAutoRefresh:{id,window,enabled}} with existing window vocabulary and no other settings changes.
+- `account anthropic-reset-grants [I] --json`: GET-only existing endpoint. No consume command; session-only spend stays a GUI handoff.
+- Extend account login with explicit --open-browser on|off and --add-account on|off. Omitted flags preserve prior CLI defaults, not a guessed new default. Device, account id and flow id remain distinct. No automatic human verification.
+- NEW logout-command.ts, MODIFY dispatch.ts: `logout P --live --json` uses fixed runtime logout endpoint; no local credential removal before target selection or after failure. No-live retains removed/not-found behavior. No new stored credential system.
+
+## Runtime/model settings contracts
+
+NEW src/cli/agent-settings.ts and v2-runtime.ts; MODIFY agent.ts, system-command.ts, v2.ts and dispatch/registry where needed:
+
+- system settings adds --show-codex-credits, --account-picker, --main-account-hard-lock, --ultra-fast-tier, --fast-rows booleans mapped to existing keys only. Provider Fast is separate.
+- agent injection/guidance adds --sync-codex-defaults on|off, preserving model/effort/null semantics and normalized returned state.
+- agent sidecar web adds --stream-routed-output; vision adds --timeout-ms. Partial fields must retain siblings and inherited helper behavior.
+- agent memory-models show/set/clear: fixed settings memoryModels block with extract/consolidation model + optional reasoningEffort. set accepts --extract-model/--extract-effort and --consolidation-model/--consolidation-effort, or exclusive --file. Each invocation replaces the full memoryModels block; omitted phase means off, effort without a model is refused, clear sends null. No empty phase objects. Reuse existing memoryModelsSchema.
+- agent compaction-routing show/set/clear: set accepts required --model plus optional --effort, --triggers manual,auto and --sources selectors, or exclusive --file; clear sends null. Each set replaces the full block; omitted triggers/sources retain server default/all scope. Reuse compactionRoutingSchema; preserve exact selectors, no surprise upstream call.
+- Existing v2 status/on/off/mode/keep-native-v1/threads/mode-hint gain explicit --live and --json. Live maps exactly to GET/PUT /api/v2: enabled, multiAgentMode, keepNativeChatGptOnV1, maxConcurrentThreadsPerSession, multiAgentModeHintText. Only explicit --acknowledge-surface-advisory writes true; never auto-ack. Parse output/target flags and reject extra operands before local writers. Local transition/hint helpers remain; JSON reports local changed/sync outcome, not fabricated server receipts.
+
+All commands reuse established API and identity helpers. Runtime base is pinned across resolution/write. No credential writes or settings switches are performed against the operator's proxy in development QA.
+
+Metadata and docs: capabilities-accounts/agents-routing/observe-system, exact help, skill recipes and public account/agent docs. Update cli-management.md, config.md, subagents.md, account-control/provider ownership docs and Desktop integration contracts only where changed.
+
+NEW tests/cli/cli-account-policy.test.ts, cli-account-login-options.test.ts, cli-logout-runtime.test.ts, cli-agent-settings.test.ts, cli-system-settings-parity.test.ts, cli-v2-runtime.test.ts. Reuse existing account pool, threshold, native-main, schema and v2 tests. No additions to capped codex-v2-gate file.
+
+## Activation matrix
+
+Invalid/mixed selectors, unsupported pool fields, off/false/zero/null, threshold inheritance and account-not-found are distinct. Credits all/one cannot combine and never consume reset grants. Quota activation writes only its nested mutation. Login cancellation/expiry/refusal retains flow identity and no hidden fresh retry. Live refusal cannot fall back to local auth/config.
+
+Memory phases round-trip independently; disabling removes effort; compaction clear/null is distinct from omitted setting. v2 local and live targets use disjoint fixtures; hybrid conflicts and persisted-but-convergence-failed receipts remain visible. Machine output remains one safe JSON payload with no progress prose or secret values. Explicit security review covers spend intent, auth scope and native ownership.
+
+## Shared completion contract
+
+This phase follows 002_terminal_ux.md and 003_verification_strategy.md. Main owns registry/dispatch integration, layout-map registration, generated output and Git branch state; executor write scopes are disjoint and named before B. Existing method/path/body semantics come from the referenced source inventories, not endpoint-name guessing.
+
+Update the phase's capability domain, generated references, relevant public CLI pages and owning structure contracts in the same layer. Every new test file enters scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Existing tests are retained; no baseline cap increases or green-on-retry acceptance.
+
+Planned new test paths below become executable verification only after B creates them. The current baseline gates in 003 have actually run. C invokes the exact focused files, typecheck, structure and skill-surface checks, privacy where data is handled, a source-bound cxc receipt and real isolated CLI QA (stdout/stderr/exit/teardown). A successful function mock is transport proof only; relevant existing server tests or isolated real handlers verify accepted state. No live user proxy, credentials or upstream requests.
+
+Before P>A, revalidate this document against the parent layer and record the prior D conclusion. Consult an architect for actual decision changes; independent A review is separate. C must preserve saved-versus-applied/refused outcomes. D records exact checks and ledger evidence before the next cycle. Publishing is main-owned; this request stops at open PRs.
diff --git a/devlog/_plan/261003_cli_gui_parity/060_integrations_maintenance.md b/devlog/_plan/261003_cli_gui_parity/060_integrations_maintenance.md
new file mode 100644
index 00000000000..a2521e79ba8
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/060_integrations_maintenance.md
@@ -0,0 +1,47 @@
+# wp6 — Complete integration recovery, maintenance settings and Hub observation
+
+Depends on wp5. Class C3 with C4 destructive/ownership review. Layer 5.
+
+## Exact command and module changes
+
+| Command | Existing authority and payload | Files |
+| --- | --- | --- |
+| claude desktop profile show --json | GET /api/claude-desktop on current management runtime; existing desktop show stays local | NEW src/cli/claude-desktop-profile.ts; MODIFY claude-desktop.ts dispatch |
+| claude desktop profile import FILE --json | Bounded DesktopProfile parsed by existing validator; PUT {profile}, save only, separate existing apply. Preserve conflict/unavailable-model/applied-marker guards | same module; no server behavior change |
+| integration client enable --client droid --reasoning-default MODEL=EFFORT (repeatable) / --clear-reasoning-defaults | Existing integration payload gains droidReasoningDefaults; same map in any adopted preview/apply plan; no other client accepts it | MODIFY integrations.ts; NEW integration-input.ts if needed |
+| integration client history remove --op ID --yes --json [--client aside --profile N] | DELETE exact global/Aside/profile journal path with op identity; newest-row refusal, missing row and snapshotRemoved:false retained | NEW integration-journal.ts; wire integrations.ts |
+| integration client sync --client aside --json | Reuse refreshAsideProfilesThroughServer, not broad sync; report per-profile partial failures nonzero; no profile override | integrations.ts/aside-profiles.ts existing helper |
+| integration native cursor status/local-installer --json | Fixed existing Cursor GET routes; installer read never installs | MODIFY inspect.ts; small sibling if needed |
+| remote-workspace hub status/runtimes/sessions --json | Fixed Hub GET routes; keep existing remote-workspace status executor-local | NEW remote-workspace-hub.ts; MODIFY remote-workspace.ts |
+| storage policy set --archived-bytes-over N [--reduce-to-bytes N or --remove-oldest-percent N] | PUT nested trigger.archivedBytesOver and exclusive target shape; retain --percent alias; never implicitly enable | MODIFY storage.ts |
+| link revoke --link-id ID --force --yes --json | Only explicit force sends body {force:true}; CLI output explicitly derives remoteCleanup:skipped/unverified from force intent (the endpoint returns only linkId), with a remote disconnect recovery hint. Never claim a failed remote attempt. Ordinary revoke default unchanged | MODIFY link.ts |
+
+## Preview and optional checked commit
+
+Add integration client preview --client ID --operation apply|overwrite|disable [--profile N] [Droid defaults] --json and integration client restore --op ID --preview [--client aside --profile N] [--confirm-drift] --json. NEW src/cli/integration-preview.ts owns response/target validation; wire existing integrations.ts.
+
+Generic preview POSTs /api/client-integrations/preview {clientId,operation,droidReasoningDefaults?}; generic restore preview POSTs /api/client-integrations/restore/preview {opId,confirmDrift?}. Aside always uses /api/client-integrations/aside/profiles/N/preview with operation and optional restore intent. No aggregate Aside preview. All use existing admin management admission, not a GUI-session workaround.
+
+The returned version-1 plan has clientId, operation, optional profileId, state/foreignEdit, changes, fingerprint, canApply and willChange. It is an observation, not a stored authorization. Validate identity and render refused/no-op/applicable states distinctly. Fingerprint versions are p[0-9]+ with the supported hash shape; never accept an unbound marker.
+
+Existing enable/disable/restore gain optional --plan-fingerprint TOKEN. Derive operation from the actual command, enabled and overwrite intent, then send the flat pair operation + planFingerprint (not a nested plan object). Repeat exactly the preview's profile/opId/confirmDrift/Droid defaults. No required new preview step for direct legacy commands. Stale 409 returns a failure/re-preview instruction and never silently commits the returned replacement fingerprint. Reject --preview combined with --plan-fingerprint before any request. A stale-plan failure tells the operator to rerun the explicit preview; no unvalidated error-body dump is added to legacy stderr. Add tests/cli/cli-integration-preview.test.ts with real server plan/binding tests for unchanged, changed file/roster, wrong action/profile and passive-cache-unavailable scenarios.
+
+No new management authority or automatic GUI-session bootstrap. Remote Workspace enroll/start/prompt/revoke and SSH fingerprint/credential workflows remain current consent-session exclusions; Hub read commands do not unlock them. Client-role refusal is truthful. File-client apply/restore retain direct mode; the new optional preview/bound mode covers the GUI inspection workflow. No speculative snapshot or provider refresh occurs inside preview.
+
+Update capabilities-integrations/access-remote/observe-system, remove fulfilled route deferred entries, regenerate chapters and update skills/ocx remote/recovery recipes plus public integration/storage/remote docs. Structure owners: cli-management, clients/integrations, clients/claude-desktop, remote-workspace, remote-link and storage ownership. No GUI component changes or installation/service deployment.
+
+NEW tests/cli/cli-claude-desktop-profile.test.ts, cli-integration-journal.test.ts, cli-integration-droid.test.ts, cli-aside-sync.test.ts, cli-integration-cursor.test.ts, cli-remote-workspace-hub.test.ts, cli-storage-policy-fields.test.ts, cli-link-force.test.ts. Existing server integration/journal/Aside-owner/storage policy/link tests prove persistence/ownership contracts.
+
+## Activation matrix
+
+A wrong client/profile, missing op, nonconfirmed delete/force, newest journal row, concurrent profile save during the live handler and unreadable file must not silently mutate. A failed live profile save never writes local profile. Partial Aside results stay visible in both modes. Forced link results say remote cleanup was skipped/unverified, derived from the explicit invocation; do not invent a server residual field. Hub empty devices differs from unavailable Hub; executor status does not substitute. Cleanup targets cannot combine, omitted enable stays unchanged, integer boundaries reject incorrect shapes. Explicit security review checks irreversible backup retirement, credentials/trust boundaries and forced link semantics.
+
+## Shared completion contract
+
+This phase follows 002_terminal_ux.md and 003_verification_strategy.md. Main owns registry/dispatch integration, layout-map registration, generated output and Git branch state; executor write scopes are disjoint and named before B. Existing method/path/body semantics come from the referenced source inventories, not endpoint-name guessing.
+
+Update the phase's capability domain, generated references, relevant public CLI pages and owning structure contracts in the same layer. Every new test file enters scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Existing tests are retained; no baseline cap increases or green-on-retry acceptance.
+
+Planned new test paths below become executable verification only after B creates them. The current baseline gates in 003 have actually run. C invokes the exact focused files, typecheck, structure and skill-surface checks, privacy where data is handled, a source-bound cxc receipt and real isolated CLI QA (stdout/stderr/exit/teardown). A successful function mock is transport proof only; relevant existing server tests or isolated real handlers verify accepted state. No live user proxy, credentials or upstream requests.
+
+Before P>A, revalidate this document against the parent layer and record the prior D conclusion. Consult an architect for actual decision changes; independent A review is separate. C must preserve saved-versus-applied/refused outcomes. D records exact checks and ledger evidence before the next cycle. Publishing is main-owned; this request stops at open PRs.
diff --git a/devlog/_plan/261003_cli_gui_parity/070_observation_api_tools.md b/devlog/_plan/261003_cli_gui_parity/070_observation_api_tools.md
new file mode 100644
index 00000000000..2a3091f0a85
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/070_observation_api_tools.md
@@ -0,0 +1,60 @@
+# wp7 — Preserve diagnostic state and test selected data-plane credentials
+
+Depends on wp6. Layer 6. Observation is C3; chosen-key/model/audio consumers are a separate C4-reviewed part of this phase. No server admission changes or upstream production tests.
+
+## Observation contracts
+
+- Add system health --json, fixed GET /api/system/health. Existing health liveness and system status aggregate stay unchanged (src/cli/system-command.ts).
+- Add companion timeline with hours/bucket-minutes/metric/aggregation/grouping/model/provider filters matching usage-timeline route, preserving truncated/missingMeasurements. Keep companion show/set/reset (new src/cli/companion-timeline.ts, wire companion.ts).
+- Extend non-client usage with --api-key-id; reject it on connected clients before reading/transporting a key. Existing connected /v1/usage remains authenticated self-only; Hub host supports management total/key views. No admin privilege synthesized from a data key (observe.ts).
+- Extract src/cli/log-follow.ts: send/validate cursor, retain a bounded snapshot window, surface changed same-ID rows and repeated IDs. Existing row JSONL re-emits amendments for upsert consumers. Add --events only for --follow to emit versioned snapshot/append events containing rows/cursor for exact reset/removal reconstruction; do not silently replace legacy row output. --json stays one-shot. Legacy arrays stay accepted without manufactured cursor.
+- Add observe injection --follow --jsonl using its real after cursor and bounded polling; preserve snapshot command. SIGINT stops polls and leaves no running process. No write retry.
+
+## Fixed data-plane task contracts
+
+NEW src/cli/access-data-plane.ts and access-audio.ts; MODIFY access.ts:
+
+| Command | Wire behavior |
+| --- | --- |
+| access key rename ID-or-NAME NAME --json | Existing unambiguous key resolver; PATCH only {id,name}; preserve scopes and no plaintext output. |
+| access test MODEL --protocol responses\|chat\|messages --api-key-stdin --json | Reuse named protocol payloads, read explicit chosen key from bounded 4 KiB stdin; reject internal newline, empty/oversized/invalid UTF-8, TTY wait and input timeout without echo. Fixed /v1/responses, /v1/chat/completions or /v1/messages; dedicated x-opencodex-api-key only, never management-header helper. Existing unkeyed test cannot claim chosen-key verification. |
+| access audio transcribe FILE --model ID --api-key-stdin --json | Fixed /v1/audio/transcriptions multipart file/model/JSON response format; bounded file/body/time, cancellation, no retry. Output is the requested transcript/result only. |
+| access audio live-check --model ID --api-key-stdin --json | Fixed /v1/live WebSocket with the existing GUI key-subprotocol and session-update contract. Wait for actual session readiness, send session.close and close socket. No microphone, upload, delegation execution, reconnect or full voice-roundtrip claim. |
+
+Standalone/Hub origin is the existing identity-checked local serving origin. Connected clients may use their already-enrolled normalized serverUrl with connection identity rechecked around async key read; never substitute the enrolled key for the explicit key. Preserve HTTPS-or-loopback policy and refusal of redirects/cross-origin auth forwarding. No --base-url, secret argv/env, key cache or management-relay credential exchange.
+
+Shared input/output uses existing bounded readers and error/exit vocabulary. Chosen-key mode must first establish that the selected target enforces data credentials; it refuses unsupported/authless targets without a paid model probe. Wrong keys fail in stable key-enforcing fixtures; cross-request policy stability is not guaranteed. Fixtures must use actual admission/parser contracts, not a mocked 401 that assumes loopback key enforcement, and assert no administrative header/fallback is attached. Do not echo a raw error response that could contain credentials or arbitrary terminal controls. Key creation/rotation-start and pairing remain human-terminal handoffs in the skill.
+
+Update pure capability leaves, generated references, JSONL/event schema docs, skill observation/API recipes and public reference pages. Structure owners: cli-management, dashboard-and-usage, GUI/API authority, audio/live contract as affected. No change to router/data-plane server authentication.
+
+NEW tests/cli/cli-system-health.test.ts, cli-companion-timeline.test.ts, cli-usage-scope.test.ts, cli-log-follow.test.ts, cli-injection-follow.test.ts, cli-access-rename.test.ts, cli-access-data-plane.test.ts, cli-access-audio.test.ts. Reuse existing request-log cursor/GUI parser tests as independent expectations, not as substitutes for CLI behavior. Auth/server audio fixtures stay synthetic.
+
+## Selected-key model-test guard (CP-DATA-01)
+
+This is an observational two-request workflow, not an atomic key-admission certificate. Existing unkeyed testing stays unchanged. No server auth policy or endpoint is changed.
+
+1. Validate grammar, protocol/model and existing target trust/origin. Read a single explicit UTF-8 key through bounded readSecretBytes (4096 bytes, 30-second input deadline), reject TTY waiting/internal newlines/empty input, and clear returned mutable buffers after use. Recheck observable runtime/enrollment identity after asynchronous input; pin one origin and selected protocol path.
+2. Send one fresh credentialless POST to that exact model endpoint with literal body bytes `{`, Content-Type: application/json, optional Accept: application/json, credentials:omit and redirect:error. No auth/key/cookie/session/relay/caller headers, content encoding or user-defined body. Control limits: 5 seconds total through body consumption, 4096 response bytes. Cancel/release on every exit; no retry or cached observation.
+3. Continue only for HTTP 401 with the exact current native key-required envelope: OpenAI-shaped error has message 'opencodex API key required', type authentication_error and code invalid_api_key; Messages may also use its native top-level type:error with the same message/type, or the OpenAI shape from the existing Hub-link gate. Reject generic/nonmatching 401, unknown/malformed/oversized body, redirect, timeout/cancel/network failure and every other status before sending inference. Response shape never establishes a new trusted origin or cryptographic process identity.
+4. Recheck available identity/connection evidence and refuse detected drift. Only then issue one fixed 16-token model request with the supplied dedicated key, bounded to 60 seconds total and 2 MiB response. No management or enrolled-key fallback. A Messages control 401 followed by keyed 403 means failed/disabled test, not success. Audio uses its own explicit-key admission and does not run/reuse this control.
+5. Report observations exactly: 'Credentialless request was refused; the model request using the supplied key succeeded.' In selected-key JSON mode, use a versioned probe report with safe control/request observations plus response; unkeyed legacy JSON remains its existing payload. Never say unqualified key verified, key scope certified or billed-to-this-key. No key/fingerprint/raw request metadata is serialized.
+
+On current supported routes the fixed malformed body parses before routing and cannot dispatch model inference; local logging/rate/admission bookkeeping may occur, so this is not advertised as globally side-effect-free. The observation is invocation/protocol/target scoped. Listener restart/rebind, remote backend change or policy change between calls cannot be atomically excluded by a client. Identity checks detect some changes, not all; no reused connection or extra control is presented as a lease. An authless/unrecognized target returns explicit verification unavailable/nonzero without the inference payload.
+
+NEW tests/cli/cli-access-key-guard.test.ts and tests/server/cli-key-probe-admission.test.ts exercise actual resolver+handler route compositions with a provider-call trap for all three protocols: enforcing/no key -> native 401 before handler; authless/literal malformed body -> parse/disabled refusal and zero provider calls; accepted control/wrong key -> 401 and zero provider calls under stable enforcing policy; valid key -> one controlled mock inference; disabled Messages -> control 401 then keyed 403; Hub-link native envelope; nonmatching/spoof-shaped/malformed/oversized errors; redirect; interruption; identity drift. State-change fixtures explicitly demonstrate the cross-request claim limit instead of claiming an atomic guarantee. Record whether the fixture invokes the real serve dispatcher or composes real resolvers/handlers; a hand-written fetch 401 alone is only transport coverage.
+
+## Activation matrix
+
+Same request id with new tokens/status must emit an amendment; reset/deletion event reconstructs GUI state; duplicate/suffix/legacy/malformed cases are distinct and bounded. Empty polls don't flood output. Connected caller-specified key scope is refused before key read. Timeline incomplete evidence isn't zero.
+
+For API consumers verify all three protocol shapes, missing/wrong key on an enforcing target, authless-target refusal before a paid probe, no admin leakage, redirect refusal, non-JSON/malformed/oversized responses, file cap, timeout, interruption, origin changes and session.close. No fake key reaches a real provider. Security reviewer separately assesses data-key authority, secret lifecycle and bounded WebSocket cleanup before publication.
+
+## Shared completion contract
+
+This phase follows 002_terminal_ux.md and 003_verification_strategy.md. Main owns registry/dispatch integration, layout-map registration, generated output and Git branch state; executor write scopes are disjoint and named before B. Existing method/path/body semantics come from the referenced source inventories, not endpoint-name guessing.
+
+Update the phase's capability domain, generated references, relevant public CLI pages and owning structure contracts in the same layer. Every new test file enters scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Existing tests are retained; no baseline cap increases or green-on-retry acceptance.
+
+Planned new test paths below become executable verification only after B creates them. The current baseline gates in 003 have actually run. C invokes the exact focused files, typecheck, structure and skill-surface checks, privacy where data is handled, a source-bound cxc receipt and real isolated CLI QA (stdout/stderr/exit/teardown). A successful function mock is transport proof only; relevant existing server tests or isolated real handlers verify accepted state. No live user proxy, credentials or upstream requests.
+
+Before P>A, revalidate this document against the parent layer and record the prior D conclusion. Consult an architect for actual decision changes; independent A review is separate. C must preserve saved-versus-applied/refused outcomes. D records exact checks and ledger evidence before the next cycle. Publishing is main-owned; this request stops at open PRs.
diff --git a/devlog/_plan/261003_cli_gui_parity/080_acceptance_publication.md b/devlog/_plan/261003_cli_gui_parity/080_acceptance_publication.md
new file mode 100644
index 00000000000..93f1efe07b4
--- /dev/null
+++ b/devlog/_plan/261003_cli_gui_parity/080_acceptance_publication.md
@@ -0,0 +1,35 @@
+# wp8 — Close the task ledger and publish the reviewed manual stack
+
+Depends on wp7. Class C3 verification/docs; no speculative feature additions. Finish layer 6. Any genuinely new eligible gap discovered here is appended as an in-scope P-phase work unit, not hidden as an exclusion or ignored to finish.
+
+## Exact completion work
+
+MODIFY 008_task_ledger.json with per-row final commands/target, phase/PR, executed behavioral test or explicit source-equivalence plus relevant suite proof, help/skill evidence and terminal disposition. Reconcile overlapping GUI entry points through aliasOf arrays; keep baseline rows visible. Add memory-model and compaction-routing rows with confirmed dashboard-overview-panels mount anchors. Every excluded row names presentation/native/session/consent cause and evidence; implementation debt is never relabeled excluded.
+
+MODIFY skills/ocx/SKILL.md and references/02_json_shapes.md, 03_recipes.md, 04_failure_semantics.md, 05_remote_hub.md plus generated domain references to accurately describe delivered workflows. Add a compact task-to-command reference and examples for local/live choice, bounded body files, read-back and partial failure. Preserve all human-only/secret handoffs. Correct the opening coverage claim to the measured scope, not 'everything'.
+
+MODIFY affected public CLI docs and structure docs with final behavior; eliminate stale capability/debt counts by deriving them. Verify translated docs do not contradict changed English claims. Archive this unit to devlog/_fin only when every phase is complete; repair any tracked plan references in the same closure change. Record remaining pre-existing/API-only debt separately.
+
+## Publication contract
+
+Six manual layers, own topic/verification/template and current head. Publish after each layer is locally scoped-validated; create parent PR before child so legitimate bases pass enforce-target. Attach every created PR to this chat. Never register a native stack. No merge/release/deploy in this request.
+
+Inspect each actual current-head CI: event, attempt, jobs, tested checkout SHA, success of required Linux shards/gates and any triggered platform work. Canceled/skipped/missing/older-head checks are not passing tests. Independent review and required security review are recorded separately. Resolve correct findings and propagate lower-layer fixes upward with attribution and exact leases if rewriting becomes necessary; then refresh all affected proof. No workflow/queue/check bypass.
+
+## Acceptance
+
+- Task ledger has no unexplained pending/UNKNOWN/implementation gap; all eligible rows map to verified named workflows, or a specific acknowledged product limitation justified by actual platform/consent authority.
+- Existing supported effects retained; representative workflows exercise real handlers/CLI, target separation, machine output, invalid/missing inputs, server refusal, empty state, confirmation and cancellation.
+- Every new command appears in capability/help/skill/public docs with true flags and request effects; no generic endpoint or raw config fallback is counted.
+- Exact-head CI passes per PR. Worktree contains no uncommitted source; all authorized implementation is recoverable from the open PR stack.
+- Final report names PR URLs/heads/CI, measured coverage and specific genuine exclusions. No full local/platform pass is invented from baseline or skipped jobs.
+
+## Shared completion contract
+
+This phase follows 002_terminal_ux.md and 003_verification_strategy.md. Main owns registry/dispatch integration, layout-map registration, generated output and Git branch state; executor write scopes are disjoint and named before B. Existing method/path/body semantics come from the referenced source inventories, not endpoint-name guessing.
+
+Update the phase's capability domain, generated references, relevant public CLI pages and owning structure contracts in the same layer. Every new test file enters scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Existing tests are retained; no baseline cap increases or green-on-retry acceptance.
+
+Planned new test paths below become executable verification only after B creates them. The current baseline gates in 003 have actually run. C invokes the exact focused files, typecheck, structure and skill-surface checks, privacy where data is handled, a source-bound cxc receipt and real isolated CLI QA (stdout/stderr/exit/teardown). A successful function mock is transport proof only; relevant existing server tests or isolated real handlers verify accepted state. No live user proxy, credentials or upstream requests.
+
+Before P>A, revalidate this document against the parent layer and record the prior D conclusion. Consult an architect for actual decision changes; independent A review is separate. C must preserve saved-versus-applied/refused outcomes. D records exact checks and ledger evidence before the next cycle. Publishing is main-owned; this request stops at open PRs.
diff --git a/docs-site/src/content/docs/fr/reference/cli/agents.md b/docs-site/src/content/docs/fr/reference/cli/agents.md
index 290ebbea5e3..60a99fe7dfe 100644
--- a/docs-site/src/content/docs/fr/reference/cli/agents.md
+++ b/docs-site/src/content/docs/fr/reference/cli/agents.md
@@ -129,13 +129,16 @@ les valeurs par défaut du débogage sont `OPENCODEX_USAGE_DEBUG=1`.
 
 ### `ocx access <key|endpoints|models|test> ...`
 
-Gérez les clés d'admission OpenCodex et examinez les points de terminaison et les modèles externes. `ocx api-key
-<list|create|remove> ...` est un alias de `ocx access key`.
+Consultez la liste des clés API d’accès à OpenCodex, les points de terminaison externes et les modèles. `ocx api-key` est un alias de la famille de commandes `ocx access key`.
+
+La création d’une clé et le lancement d’une rotation renvoient un secret en clair, affiché une seule fois, aussi bien en texte qu’en JSON. Les agents doivent confier ces étapes à une personne utilisant directement un terminal en dehors de la session de l’agent. Ne demandez jamais la clé dans la conversation : demandez uniquement la confirmation de la configuration et du test de connexion, ainsi que les identifiants non secrets de la clé et de la rotation.
 
 ```bash
-ocx access key create deployment
+ocx access key list --json
 ```
 
+La confirmation du fonctionnement de la nouvelle clé n’autorise pas la révocation de l’ancienne. Pour finaliser la rotation ou supprimer l’ancienne clé, obtenez une autorisation explicite distincte pour révoquer cette clé. Consultez à nouveau la liste après l’opération autorisée. Ne contournez pas cette procédure par un appel direct à l’API.
+
 ## Intégrations client
 
 ### `ocx integration <claude|grok> ...`
diff --git a/docs-site/src/content/docs/fr/reference/cli/providers-accounts.md b/docs-site/src/content/docs/fr/reference/cli/providers-accounts.md
index 91b74330991..fef31abe62e 100644
--- a/docs-site/src/content/docs/fr/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/fr/reference/cli/providers-accounts.md
@@ -420,10 +420,7 @@ entrées de catalogue ; `enable`, `disable` et `provider` contrôlent la visibi
 liste d'autorisation des fournisseurs ; `context` contrôle les plafonds de contexte du fournisseur ; et `shadow` gère l'arrière-plan
 interception d'appel fantôme.
 
-Chaque opération par modèle proposée par le tableau de bord est disponible ici, donc une installation sans tête n'est jamais nécessaire
-appuyez sur GUI pour gérer un catalogue. `add`, `remove` et `list-custom` fonctionnent sur le fichier de configuration et appliquent
-à un proxy en cours d'exécution via une synchronisation de catalogue ; les autres parlent à la direction en direct API et exigent le
-proxy en cours d'exécution (`ocx start` ou un service installé).
+Le tableau ci-dessous décrit les opérations de catalogue prises en charge par la CLI, sans couvrir toutes les actions du tableau de bord. Modifier le nom affiché d’un modèle découvert automatiquement est différent de l’opération `edit` sur un modèle personnalisé. `add`, `remove` et `list-custom` utilisent la configuration locale ; une modification de modèle personnalisé peut tenter de synchroniser le catalogue si le proxy est en cours d’exécution. Un enregistrement local réussi ne prouve pas que la synchronisation est terminée. Les autres opérations de gestion des modèles utilisent l’API de gestion du proxy actif : vérifiez son état de préparation et sa version avant de les appeler. Il n’est pas nécessaire de démarrer le proxy pour consulter les modèles ou la configuration hors ligne.
 
 | Sous-commande | Drapeaux pris en charge | Actions |
 | --- | --- | --- |
diff --git a/docs-site/src/content/docs/ja/reference/cli/agents.md b/docs-site/src/content/docs/ja/reference/cli/agents.md
index d71c6a90336..9152d6d7f68 100644
--- a/docs-site/src/content/docs/ja/reference/cli/agents.md
+++ b/docs-site/src/content/docs/ja/reference/cli/agents.md
@@ -97,12 +97,16 @@ ocx debug usage logs [-f|--follow]
 
 ### `ocx access <key|endpoints|models|test> ...`
 
-OpenCodex アドミッション API キーを管理し、外部エンドポイントとモデルを検査します。 `ocx api-key <list|create|remove> ...` は `ocx access key` の別名です。
+OpenCodex へのアクセス用 API キーの一覧、外部エンドポイント、モデルを確認します。`ocx api-key` は `ocx access key` コマンド群の別名です。
+
+キーの作成とローテーションの開始では、通常のテキスト出力でも JSON 出力でも、一度だけ表示される平文の認証情報が返されます。エージェントはこれらの手順を実行せず、エージェントセッション外で人が直接操作するターミナルに委ねてください。キーそのものをチャットで求めず、設定と接続の確認結果、および秘密情報ではないキー ID とローテーション ID だけを受け取ってください。
 
 ```bash
-ocx access key create deployment
+ocx access key list --json
 ```
 
+新しいキーの設定と接続の確認は、古いキーの失効承認ではありません。ローテーションの確定や古いキーの削除には、そのキーを失効させるための明示的な承認が別途必要です。承認された操作の後は一覧を再確認してください。API の直接呼び出しでこの手順を回避しないでください。
+
 ## クライアントの統合
 
 ### `ocx integration <claude|grok> ...`
diff --git a/docs-site/src/content/docs/ja/reference/cli/providers-accounts.md b/docs-site/src/content/docs/ja/reference/cli/providers-accounts.md
index 5f46501bbb9..5b55efbff67 100644
--- a/docs-site/src/content/docs/ja/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/ja/reference/cli/providers-accounts.md
@@ -313,7 +313,7 @@ native-main トラフィックまたはジャーナル復旧を受け入れる
 
 `ocx model` は `ocx models` の別名です。サブコマンドを使用しない場合、構成されたプロバイダーに静的にシードされたモデルを一覧表示します。 `--provider` は 1 つの構成済みプロバイダーをフィルターし、`--json` はモデル メタデータを返します。 `live` は実行中のカタログを読み取ります。 `add`、`edit`、`remove`、および `list-custom` は手動カタログ エントリを管理します。 `enable`、`disable`、および `provider` は可視性を制御します。 `selected` はプロバイダー許可リストを制御します。 `context` はプロバイダーのコンテキストの上限を制御します。 `shadow` はバックグラウンドのシャドウ コール インターセプトを管理します。
 
-ダッシュボードが提供するモデルごとの操作はすべてここで利用できるため、ヘッドレスインストールではカタログを管理するために GUI が必要ありません。 `add`、`remove`、および `list-custom` は設定ファイルに対して機能し、カタログ同期を通じて実行中のプロキシに適用されます。残りはライブ管理 API と通信し、プロキシが実行されている必要があります (`ocx start`、またはインストールされたサービス)。
+以下の表は、CLI が対応するカタログ操作を示しています。ダッシュボードのすべての操作を網羅するものではありません。自動検出されたモデルの表示名変更は、カスタムモデルの `edit` 操作とは別です。`add`、`remove`、`list-custom` はローカル設定を使用し、カスタムモデルの変更時にプロキシが稼働していればカタログの同期を試みる場合があります。ローカルへの保存完了は、同期完了を意味しません。それ以外のモデル管理操作は稼働中のプロキシの管理 API を使用するため、呼び出す前に準備状態とバージョンを確認してください。オフラインでモデルや設定を確認するためにプロキシを起動する必要はありません。
 
 |サブコマンド |サポートされているフラグ |アクション |
 | --- | --- | --- |
diff --git a/docs-site/src/content/docs/ko/reference/cli/agents.md b/docs-site/src/content/docs/ko/reference/cli/agents.md
index 681e1ca9f7d..34d781cd8e4 100644
--- a/docs-site/src/content/docs/ko/reference/cli/agents.md
+++ b/docs-site/src/content/docs/ko/reference/cli/agents.md
@@ -122,13 +122,16 @@ scope를 지정하지 않으면 `ocx debug`는 사용량을 출력하고, 프록
 
 ### `ocx access <key|endpoints|models|test> ...`
 
-OpenCodex admission API key를 관리하고 외부 endpoint와 model을 검사합니다. `ocx api-key
-<list|create|remove> ...`는 `ocx access key`의 별칭입니다.
+OpenCodex 접속용 API 키 목록, 외부 엔드포인트와 모델을 조회합니다. `ocx api-key`는 `ocx access key` 명령 계열의 별칭입니다.
+
+키 생성과 교체 시작은 일반 텍스트와 JSON 출력 모두에서 일회성 평문 자격 증명을 반환합니다. 에이전트는 이 단계를 에이전트 세션 밖에서 사람이 직접 조작하는 터미널에 맡겨야 합니다. 키 자체를 채팅으로 요청하지 말고, 설정·연결 확인 결과와 비밀이 아닌 키·교체 ID만 전달받으세요.
 
 ```bash
-ocx access key create deployment
+ocx access key list --json
 ```
 
+새 키의 설정과 연결 확인은 기존 키 폐기 승인이 아닙니다. 교체를 확정하거나 기존 키를 삭제하려면 해당 키 폐기에 대한 별도의 명시적 승인이 필요합니다. 승인된 작업 후에는 목록을 다시 조회하세요. 직접 API를 호출해 이 절차를 우회하지 마세요.
+
 ## 클라이언트 통합
 
 ### `ocx integration <claude|grok> ...`
diff --git a/docs-site/src/content/docs/ko/reference/cli/providers-accounts.md b/docs-site/src/content/docs/ko/reference/cli/providers-accounts.md
index 9fd3cd1a649..fcb91a8a7e7 100644
--- a/docs-site/src/content/docs/ko/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/ko/reference/cli/providers-accounts.md
@@ -429,7 +429,7 @@ native-main 트래픽이나 저널 복구를 허용하기 전에 수명 주기 
 
 `ocx model`은 `ocx models`의 별칭입니다. 하위 명령이 없으면 설정된 제공자에 사전 등록된 모델을 나열합니다. `--provider`는 설정된 제공자 하나를 필터링하고 `--json`은 모델 메타데이터를 반환합니다. `live`는 실행 중인 카탈로그를 읽습니다. `add`, `edit`, `remove`, `list-custom`은 수동 카탈로그 항목을 관리합니다. `enable`, `disable`, `provider`는 가시성을 제어합니다. `selected`는 제공자 허용 목록을 제어합니다. `context`는 제공자 컨텍스트 한도를 제어합니다. `shadow`는 백그라운드 shadow-call 가로채기를 관리합니다.
 
-대시보드가 제공하는 모델별 작업은 모두 여기에서도 사용할 수 있으므로, 헤드리스 설치에서는 카탈로그를 관리할 때 GUI가 필요하지 않습니다. `add`, `remove`, `list-custom`은 구성 파일을 대상으로 하며 카탈로그 동기화를 통해 실행 중인 프록시에 적용됩니다. 나머지는 실시간 관리 API와 통신하며 프록시가 실행 중이어야 합니다(`ocx start` 또는 설치된 서비스).
+아래 표는 CLI가 지원하는 카탈로그 작업을 설명합니다. 대시보드의 모든 작업을 지원하는 것은 아닙니다. 자동으로 발견된 모델의 표시 이름 변경은 사용자 정의 모델의 `edit` 작업과 다릅니다. `add`, `remove`, `list-custom`은 로컬 구성을 사용하며, 사용자 정의 모델을 변경할 때 프록시가 실행 중이면 카탈로그 동기화를 시도할 수 있습니다. 로컬 저장이 완료되어도 동기화 완료를 뜻하지는 않습니다. 나머지 모델 관리 작업은 실행 중인 프록시의 관리 API를 사용하므로 호출 전에 준비 상태와 버전을 확인하세요. 오프라인 모델·구성 조회를 위해 프록시를 시작할 필요는 없습니다.
 
 | 하위 명령 | 지원 플래그 | 동작 |
 | --- | --- | --- |
diff --git a/docs-site/src/content/docs/reference/cli.md b/docs-site/src/content/docs/reference/cli.md
index 7bb9e2f1dc6..c1a58bb73e4 100644
--- a/docs-site/src/content/docs/reference/cli.md
+++ b/docs-site/src/content/docs/reference/cli.md
@@ -19,8 +19,8 @@ opencodex state.
 ## Nested help
 
 Family help such as `ocx help models` preserves the family's usage and details, then
-lists known declared child paths with summaries. These lists are marked as partial;
-they do not enumerate every runtime operation. Alias help retains the alias's own usage
+lists known declared child paths with summaries. These lists describe declared children;
+they do not guarantee exhaustive runtime coverage. Alias help retains the alias's own usage
 and details and points to its canonical family: `ocx help model` leads to `ocx help models`.
 Models help also links the curated `models context` topic separately from declared capabilities.
 
@@ -72,7 +72,7 @@ children. Suggestions are guidance only: the CLI never executes them or retries
 | `ocx modles` or `ocx help modles` | Suggests `ocx help models`. |
 | `ocx help account lisst` | Suggests `ocx help account list` within the account family. |
 | `ocx help qzxv` | Offers `ocx help --all` without guessing a command. |
-| `ocx help service install` | Reports unavailable detailed help and points to `ocx help service`; the runtime install operation remains valid. |
+| `ocx help models qzxv` | Reports unavailable detailed help and points to the known models family. |
 
 The Bun CLI rejects an unknown root before shim auto-restore or other command preflight.
 Recognized commands retain their existing preflight; hidden commands and the internal runner
@@ -139,7 +139,7 @@ Codex or npm, control a running process, or write configuration/cache state.
 
 For Windows x64 installation observation, see [the `attest` command](/reference/cli/agents/#explicit-installation-observation-on-windows-x64). Without explicit paths it observes the selected candidate identified from the proof-bound launcher snapshot; it does not grant update authority or attest runtime selection.
 
-List or status is the default where unambiguous. Use `--json` for structured snapshots and
+List or status is the default where unambiguous. Use `--json` only on leaves that support it, and
 `ocx observe logs --follow --jsonl` for a streaming request-log feed. Theme, language, navigation,
 and other purely visual browser state have no CLI equivalent; Cloudflare Tunnel setup is outside
 this command set.
@@ -173,17 +173,18 @@ and unavailable required services exit nonzero. `ocx health` specifically exits
 proxy is healthy and 1 otherwise, so it can be used as a service probe. Scripts should test the exit
 code instead of scraping human-readable output.
 
-The specific codes are set in one place, so every management command agrees:
+Many management commands share these mappings; other CLI families retain their own exit contracts:
 
 | Code | Cause |
 |---|---|
 | 0 | success |
-| 2 | usage error — bad, missing, or unknown arguments; nothing was sent |
+| 2 | local usage refusal in management handlers; also unsupported `doctor --json` |
+| 64 | invalid arguments to `capabilities`, `ready`, or `resolve`, before their discovery/request work |
 | 4 | HTTP 404 — the named account, provider, key, or route does not exist |
 | 5 | HTTP 409 — conflict; a lock is held or state changed underneath |
 | 1 | everything else, including transport failure and other HTTP errors |
 
-Exit 0 means no error was reported. Preview verbs (for example `ocx storage cleanup` without `--yes`) also exit 0 without mutating. A command never prints an error and exits 0.
+Exit 0 means no error was reported. Preview verbs (for example `ocx storage cleanup` without `--yes`) also exit 0 without mutating. A saved setting can still carry a skipped or incomplete apply result; read the receipt and stderr warnings.
 
 Destructive removal, import, credit-consumption, and update operations that advertise confirmation
 require `--yes` in non-interactive use. The flag is an explicit opt-in; omitting it must not silently
@@ -195,18 +196,45 @@ a prompt an automated caller can answer is not a safety boundary, so the flag is
 
 ## Driving the CLI from an agent
 
-`ocx capabilities --json` is the machine-readable index of declared capabilities, their management
-routes, known flags, and mutation metadata. It is not an exhaustive command grammar or a list of
-every runtime subcommand. Start there rather than parsing help text:
+Discover progressively, without starting a proxy:
+
+```bash
+ocx help
+ocx help models
+ocx help models preset show
+```
+
+Read the corresponding chapter in the repository's `skills/ocx/references/01_management_surface.md`
+or one of the public command-family pages above. Full `ocx help --all` is an
+escape to the top-level reference. A broad machine inventory is optional:
 
 ```bash
 ocx capabilities --json
 ocx capabilities --mutating-only --json
-ocx capabilities --route /api/logs
+ocx capabilities --route '/api/providers/{provider}/model-costs' --json
 ```
 
-An unmatched `--route` exits 4 rather than reporting empty success. The repository ships a fuller
-operating guide at `skills/ocx/`, whose surface map is generated from the same table.
+Route lookup matches the literal declared template, not concrete provider IDs or
+an HTTP method. A miss exits 4 and does not prove that a runtime command is absent.
+Declarations include local commands as well as management commands; only the
+latter need a live target. Before live operations, run `ocx ready --json` and
+`ocx status --json`, inspect the target and `versionSkew.relation`, and resolve
+version mismatch. `unknown` does not confirm matching builds. Offline help,
+local configuration and local Lab inspection do not require startup.
+
+Output flags are per command. `doctor` rejects `--json` with exit 2; `v2` has no
+JSON output contract. Even for JSON-capable management commands, API failures
+normally use stderr prose with optional `reason:` and `hint:` lines, not a JSON
+error envelope. Keep stdout, stderr and exit status separate.
+
+Coverage is measured by named workflows, not by shared route prefixes. Existing
+model presets, visibility, account controls and routing-profile reads do not imply
+support for discovered-model display-name edits or routing-profile writes.
+Session-only consent actions and browser presentation remain separate boundaries.
+Access-key creation and rotation-start return plaintext credentials: agents must
+hand those steps to a human-operated terminal outside the session and accept only
+non-secret IDs and confirmation. Never ask for credentials in chat or bypass a
+session-only action with another API client.
 
 ## Recent behavior changes
 
@@ -216,8 +244,8 @@ These are corrections to commands that previously misreported their own results:
   exited 0, so a script could not tell success from failure.
 - Client errors from `account` map HTTP 404 to exit 4 and HTTP 409 to exit 5, instead of collapsing
   everything into 1.
-- `--json` is honored in any argument position, including `ocx restore back --json`, which
-  previously accepted the flag and ignored it.
+- `ocx restore back --json` now honors its output flag, which it previously accepted and ignored.
+  This does not make `--json` a global option for every command.
 - `ocx logs --model` now actually filters. It was accepted and silently ignored, so the output
   looked filtered while showing every row.
 - `ocx storage` gained `cleanup`, `trash`, and `policy` subcommands. A bare `ocx storage` still
diff --git a/docs-site/src/content/docs/reference/cli/agents.md b/docs-site/src/content/docs/reference/cli/agents.md
index 178a57ab4cd..7ee064ef992 100644
--- a/docs-site/src/content/docs/reference/cli/agents.md
+++ b/docs-site/src/content/docs/reference/cli/agents.md
@@ -92,6 +92,8 @@ for the request surfaces where caps apply.
 ### `ocx v2 <status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|threads <n>|mode-hint <text|--clear>>`
 
 Manage the Codex `multi_agent_v2` feature flag and the three-state multi-agent surface mode.
+These are local controls with human output; do not append `--json`. Re-read
+`ocx v2 status` after a change and distinguish stored settings from new-session behavior.
 
 | Subcommand | Action |
 | --- | --- |
@@ -141,7 +143,7 @@ gate: it requires the native feature to be enabled with an explicit v2 surface
 ### `ocx combo <list|show|set|remove> ...` · `ocx route combo ...`
 
 Manage combo failover and round-robin virtual models. `ocx route combo` is the hierarchical alias;
-combo is currently the supported routing resource. Targets use
+combos and routing profiles are distinct resources. Combo targets use
 `provider/model[:weight],provider/model[:weight]`.
 
 ```bash
@@ -170,6 +172,50 @@ like decision models, with the derived endpoint.
 
 See [Combos](/guides/combos/) for routing behavior and configuration guidance.
 
+## Routing profiles
+
+Existing profiles support inspection and evaluation through the live API:
+
+```bash
+ocx route policy list --json
+ocx route policy show reliable --json
+ocx route policy dry-run reliable --model-context 128000 --tools --image --structured-output --json
+```
+
+Only run this evaluation with authority to activate Lab on the target. The management POST can activate Lab and start automation that is already enabled there, including upstream probes. Use list/show for observation without that activation effect.
+
+Replace `reliable` with a listed ID. `evaluate` is an alias for `dry-run`; both
+send requirements to the saved profile's evaluator without an inference request.
+Creation, update and deletion remain dashboard operations. Combo writes do not
+edit routing profiles. Re-read the profile and revision when an evaluation
+surprises you; missing IDs return exit 4 and missing operands return 2.
+
+## Compatibility Lab
+
+Lab is local inspection **and** explicit evidence/automation management. Reads
+use the local projection and do not require a running management API:
+
+```bash
+ocx lab status --json
+ocx lab catalog --json
+ocx lab subjects --limit 10 --json
+ocx lab automation status --json
+ocx lab automation runs --limit 10 --json
+ocx lab public community --json
+```
+
+`subject`, `observations`, `event`, `artifact`, and `production-signals` follow
+local evidence lineage. The public family offers preview/export by repeated
+`--event <id>`, verification/import through `--file <bundle.json>`, and community
+context. Export and import write local evidence. Verification can print its
+result and still exit nonzero when the bundle is not cryptographically valid.
+
+Automation enable/disable changes local policy; manual `lab run` selects a layer
+and scenario and may spend upstream quota. Read `ocx help lab` and the relevant
+leaf before these authorized operations. A saved local policy does not prove
+that a separately running proxy's scheduler adopted it. Full automation policy
+editing and run cancellation are not exposed by these CLI controls.
+
 ## Observability and debug
 
 ### `ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...`
@@ -233,13 +279,24 @@ debug defaults from `OPENCODEX_USAGE_DEBUG=1`.
 
 ### `ocx access <key|endpoints|models|test> ...`
 
-Manage OpenCodex admission API keys and inspect external endpoints and models. `ocx api-key
-<list|create|remove> ...` is an alias of `ocx access key`.
+Inspect admission keys, external endpoints and models with the access family.
+`ocx api-key` aliases the access-key family. Creation and rotation-start return a
+one-time plaintext credential in text and JSON output. Agents must leave those
+steps to a human-operated terminal outside the agent session; request only
+confirmation and non-secret key/rotation IDs, never the credential.
 
 ```bash
-ocx access key create deployment
+ocx access key list --json
 ```
 
+After the human configures and verifies the replacement, committing its rotation
+or removing the old key requires separate explicit revocation authority. Safe
+non-secret follow-ups are `ocx access key rotate commit <id> <rotation-id> --json`
+and `ocx access key rotate abort <id> <rotation-id> --json`, with authority for
+the chosen action. Re-list afterward. Missing pending state alone does not prove
+commit: expiry or abort can also clear it. Do not route around consent by issuing
+the secret-returning management request directly.
+
 ### `ocx api <protocols|explain|policy> ...`
 
 Inspect and set how requests travel between the client APIs and provider wires. See
diff --git a/docs-site/src/content/docs/reference/cli/lifecycle.md b/docs-site/src/content/docs/reference/cli/lifecycle.md
index ea1eb252960..fafb9e62304 100644
--- a/docs-site/src/content/docs/reference/cli/lifecycle.md
+++ b/docs-site/src/content/docs/reference/cli/lifecycle.md
@@ -5,6 +5,23 @@ description: Setup, start, stop, service, diagnostics, sync, and update commands
 
 These commands install, run, inspect, repair, and update the local opencodex proxy and its Codex integration.
 
+## Discover before starting services
+
+`ocx help`, `ocx help <family>` and `ocx help <family> <leaf>` are offline.
+Use `ocx help --all` when the compact root is insufficient. Help, local config
+validation and local Lab inspection do not require starting a proxy.
+
+Before a live management workflow, run `ocx ready --json` and `ocx status --json`.
+Readiness distinguishes `pending`, `failed` and `unreachable`; only `ready: true`
+confirms readiness. Check the target and `versionSkew.relation`: `unknown` is not
+proof of matching versions. A version mismatch calls for resolving the intended
+installation, not repeatedly trying a newer flag against an older server.
+
+Output and exit conventions are command-specific. `ready` and `resolve` reject
+invalid arguments with 64, while `doctor --json` is unsupported and exits 2.
+A successful local save or accepted restart request does not prove convergence;
+read the command receipt and re-check status after the requested operation.
+
 ## Setup
 
 ### `ocx init` · `ocx setup`
diff --git a/docs-site/src/content/docs/reference/cli/providers-accounts.md b/docs-site/src/content/docs/reference/cli/providers-accounts.md
index a5453b3f12c..5d799beb0ae 100644
--- a/docs-site/src/content/docs/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/reference/cli/providers-accounts.md
@@ -31,7 +31,7 @@ both `--adapter` and `--base-url`.
 ocx provider list --json
 ocx provider list --jsonl        # one configured provider object per line
 ocx provider test ark
-ocx provider add anthropic --api-key sk-ant-... --set-default --sync
+ocx provider add anthropic --set-default --sync
 ocx provider add local-dev --adapter openai-chat --base-url http://localhost:11434/v1
 ocx provider show anthropic --json
 ocx provider edit github-copilot --model-context-tier gpt-5.6-luna=long_context
@@ -60,9 +60,23 @@ boundary is yours to respect. Two reasons it matters:
 - Header values are persisted in `config.json` in cleartext, unlike API keys,
   which have their own storage and masking path.
 
-Use `--api-key` or an OAuth login for anything secret.
+Use the supported credential login or stdin flow for secret entry. Do not place
+keys in an agent transcript or copy them into command examples.
 :::
 
+### Local saves and live provider state
+
+`list`, `show`, `add`, `remove`, and `set-default` use local configuration;
+`edit`, `test`, `quota`, `selected`, `presets`, and `account-mode` use management
+calls. Check `ocx ready --json` and `ocx status --json` before live work. A local
+list does not establish that an already-running proxy adopted the configuration.
+
+`provider add <name> --json` reports `needsSync: true` and returns before the human
+`--sync` path, even when both flags are supplied. After authorized convergence,
+read `ocx inspect config --json` and `ocx models live --provider <name> --json`.
+`provider test` checks discovery connectivity; `applicable: false` is an expected
+static-catalog result, not successful inference or a failed connection.
+
 ## Authentication
 
 ### Diagnosing missing main-account quota
@@ -771,10 +785,12 @@ verified official-price fallbacks. Unknown models return `null`; no price is inv
 Automatic defaults are derived on read and do not populate `modelCosts` in your config,
 so catalog updates remain effective. Use `set-price` to save provider-specific rates.
 
-Every per-model operation the dashboard offers is available here, so a headless install never needs
-the GUI to manage a catalog. `add`, `remove`, and `list-custom` work against the config file and apply
-to a running proxy through a catalog sync; the rest talk to the live management API and require the
-proxy to be running (`ocx start`, or an installed service).
+The table below describes supported catalog workflows. It does not cover every dashboard
+operation: editing a discovered model's display name is not the custom-model `edit` operation.
+`add`, `remove`, and `list-custom` use local configuration; custom-model writes may attempt
+catalog convergence when a proxy is running. A local save does not prove that sync completed.
+The remaining model-management operations use the live API. Check readiness and version
+before those calls; offline model/config inspection does not require startup.
 
 | Subcommand | Supported flags | Action |
 | --- | --- | --- |
@@ -790,6 +806,10 @@ proxy to be running (`ocx start`, or an installed service).
 | `disable <provider/model\|native-model>` | `--native`, `--json` | Hide one model from Codex. |
 | `provider <name> <on\|off>` | `--json` | Enable or disable every model of one provider in a single write. |
 | `selected <provider>` | `--set <id,id...>`, `--clear`, `--json` | Read or replace the provider model allowlist. `--clear` removes the allowlist so every model is offered. |
+| `preset show` | `--provider <name>`, `--json` | Read shipped preset versions and the applied mode, optionally for one provider. |
+| `preset apply <provider>` | `--all`, `--json` | Apply the curated preset; `--all` clears the allowlist. A zero-match preset leaves selection unchanged and reports `fallback: "preset-empty"`. |
+| `new-policy [on\|off]` | `--provider <name>`, `--json` | Read or change exposure policy for newly discovered models; omission of provider selects global policy. A provider read can report `inherit`. |
+| `new-arrivals` | `--json` | Read recorded recent discoveries by provider; does not force a new upstream discovery. |
 | `context <status\|value <tokens> [--set-all]\|provider <name> on [--value <tokens>]\|provider <name> off\|all <on\|off>>` | `--json` | Read or set the context-window cap, globally or per provider. `value <tokens> --set-all` also re-points every routed provider (like the dashboard toggle); without it the value only becomes the default. `provider ... on --value <tokens>` sets an explicit cap for that provider only (`--value` is valid with `on` only). |
 | `shadow <status\|set> [model\|-]` | `--enabled <on\|off>`, `--json` | Read or set the replacement model for Codex's background helper calls. `-` clears the model. `status` also reports `sourceModels`, the helper slugs the proxy intercepts (default: `gpt-6-luna`, `gpt-5.6-luna`; clients through 0.144.x used `gpt-5.4-mini`, which an explicit `sourceModels` override can restore). |
 
@@ -814,6 +834,23 @@ and rejects an entire catalog containing any other value, so `add`, `edit`, and
 all refuse the bad value rather than storing something the catalog writer would have to strip later
 (#759).
 
+### Apply a preset and verify selection
+
+```bash
+ocx models preset show --provider anthropic --json
+ocx models preset apply anthropic --json
+ocx models selected anthropic --json
+ocx models new-policy --provider anthropic --json
+ocx models new-policy off --provider anthropic --json
+ocx models new-policy --provider anthropic --json
+ocx models new-arrivals --json
+```
+
+The writes require intent to change selection or discovery policy. Read back the
+selection and policy; a saved preset fallback can leave the previous selection
+intact. `preset apply <provider> --all` is the supported all-models mode; the
+dashboard's disabled custom preset does not add another selectable mode.
+
 ### Mark one model text-only
 
 Use `ocx provider add mine --adapter openai-chat --base-url https://example.com/v1 --default-model model-a --text-only` when registering a provider, or `ocx provider edit mine --model model-a --text-only` for an existing provider. Add can use `--model` or its default model; edit requires `--model`. The flag updates only that exact model's `modelCapabilities.inputModalities` to `["text"]`, preserving other models and axes.
diff --git a/docs-site/src/content/docs/ru/reference/cli/agents.md b/docs-site/src/content/docs/ru/reference/cli/agents.md
index 6221a4beed4..bb724a4f9d7 100644
--- a/docs-site/src/content/docs/ru/reference/cli/agents.md
+++ b/docs-site/src/content/docs/ru/reference/cli/agents.md
@@ -109,13 +109,16 @@ ocx debug usage logs [-f|--follow]
 
 ### `ocx access <key|endpoints|models|test> ...`
 
-Управляйте admission API-key'ами OpenCodex и проверяйте внешние endpoint'ы и модели.
-`ocx api-key <list|create|remove> ...` — alias `ocx access key`.
+Просматривайте список API-ключей доступа к OpenCodex, внешние конечные точки и модели. `ocx api-key` — псевдоним семейства команд `ocx access key`.
+
+Создание ключа и начало ротации возвращают секрет в открытом виде, показываемый только один раз, как в текстовом формате, так и в JSON. Агент должен передать эти действия человеку, который выполнит их вручную в терминале вне сеанса агента. Не запрашивайте сам ключ в чате: нужны только подтверждение настройки и проверки подключения, а также несекретные идентификаторы ключа и ротации.
 
 ```bash
-ocx access key create deployment
+ocx access key list --json
 ```
 
+Подтверждение работы нового ключа не является разрешением отозвать старый. Для завершения ротации или удаления старого ключа требуется отдельное явное разрешение на отзыв именно этого ключа. После разрешённой операции снова проверьте список. Не обходите этот порядок прямым вызовом API.
+
 ## Интеграции клиентов
 
 ### `ocx integration <claude|grok> ...`
diff --git a/docs-site/src/content/docs/ru/reference/cli/providers-accounts.md b/docs-site/src/content/docs/ru/reference/cli/providers-accounts.md
index 899594aa3ab..e7c68ee0d96 100644
--- a/docs-site/src/content/docs/ru/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/ru/reference/cli/providers-accounts.md
@@ -377,10 +377,7 @@ ocx account main recover [--rollback --yes] [--json]
 `selected` управляет allowlist'ом провайдера; `context` — provider context cap'ами; `shadow`
 управляет intercept'ом background shadow-call'ов.
 
-Любая per-model операция, которую умеет дашборд, доступна и здесь, так что headless-установке не
-нужен GUI для управления каталогом. `add`, `remove` и `list-custom` работают напрямую с файлом
-конфига и применяются к работающему прокси через sync каталога; остальные обращаются к live
-management API и требуют, чтобы прокси уже работал (`ocx start` или установленная служба).
+В таблице ниже перечислены поддерживаемые CLI операции с каталогом, а не все действия панели управления. Изменение отображаемого имени автоматически обнаруженной модели отличается от операции `edit` для пользовательской модели. Команды `add`, `remove` и `list-custom` работают с локальной конфигурацией; при изменении пользовательской модели может выполняться попытка синхронизации каталога, если прокси запущен. Успешное локальное сохранение не означает, что синхронизация завершена. Остальные операции управления моделями используют API работающего прокси: перед вызовом проверьте его готовность и версию. Для автономного просмотра моделей и конфигурации запускать прокси не нужно.
 
 | Подкоманда | Поддерживаемые флаги | Действие |
 | --- | --- | --- |
diff --git a/docs-site/src/content/docs/tr/reference/cli/agents.md b/docs-site/src/content/docs/tr/reference/cli/agents.md
index d8a3f847eeb..ad961696fb8 100644
--- a/docs-site/src/content/docs/tr/reference/cli/agents.md
+++ b/docs-site/src/content/docs/tr/reference/cli/agents.md
@@ -144,14 +144,16 @@ varsayılan olarak `OCX_DEBUG=1`'den gelir (eski `OCX_DEBUG_FRAMES=1` de
 
 ### `ocx access <key|endpoints|models|test> ...`
 
-OpenCodex kabul API anahtarlarını yönetin ve harici uç noktaları ile modelleri
-inceleyin. `ocx api-key <list|create|remove> ...`, `ocx access key`'in bir takma
-adıdır.
+OpenCodex erişim API anahtarlarının listesini, harici uç noktaları ve modelleri inceleyin. `ocx api-key`, `ocx access key` komut ailesinin takma adıdır.
+
+Anahtar oluşturma ve anahtar yenilemeyi başlatma işlemleri, hem metin hem de JSON çıktısında yalnızca bir kez gösterilen açık metin kimlik bilgisi döndürür. Ajanlar bu adımları, ajan oturumu dışında bir insanın doğrudan kullandığı terminale bırakmalıdır. Anahtarın kendisini sohbette istemeyin; yalnızca yapılandırmanın ve bağlantı testinin tamamlandığına dair onayı ve gizli olmayan anahtar ile yenileme kimliklerini alın.
 
 ```bash
-ocx access key create deployment
+ocx access key list --json
 ```
 
+Yeni anahtarın yapılandırılıp doğrulanması, eski anahtarı iptal etme izni değildir. Yenilemeyi kesinleştirmek veya eski anahtarı silmek için o anahtarın iptaline yönelik ayrıca açık izin gerekir. İzin verilen işlemden sonra listeyi yeniden kontrol edin. Doğrudan API çağrılarıyla bu süreci aşmaya çalışmayın.
+
 ## İstemci entegrasyonları
 
 ### `ocx integration <claude|grok> ...`
diff --git a/docs-site/src/content/docs/tr/reference/cli/providers-accounts.md b/docs-site/src/content/docs/tr/reference/cli/providers-accounts.md
index 8e8bef8b9e0..81fdff667b7 100644
--- a/docs-site/src/content/docs/tr/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/tr/reference/cli/providers-accounts.md
@@ -483,12 +483,7 @@ görünürlüğü kontrol eder; `selected` bir sağlayıcı izin listesini kontr
 `context` sağlayıcı bağlam sınırlarını kontrol eder; ve `shadow` arka plan gölge
 çağrı müdahalesini yönetir.
 
-Kontrol panelinin sunduğu model başına her işlem burada mevcuttur, bu nedenle
-başsız bir kurulum bir kataloğu yönetmek için asla GUI'ye ihtiyaç duymaz. `add`,
-`remove` ve `list-custom` yapılandırma dosyasına karşı çalışır ve bir katalog
-senkronizasyonu aracılığıyla çalışan bir proxy'ye uygulanır; geri kalanı canlı
-yönetim API'si ile konuşur ve proxy'nin çalışmasını gerektirir (`ocx start` veya
-kurulu bir servis).
+Aşağıdaki tablo, CLI tarafından desteklenen katalog işlemlerini açıklar; kontrol panelindeki tüm işlemleri kapsamaz. Otomatik keşfedilen bir modelin görünen adını değiştirmek, özel bir model üzerindeki `edit` işleminden farklıdır. `add`, `remove` ve `list-custom` yerel yapılandırmayı kullanır; özel model değişiklikleri, proxy çalışıyorsa katalog eşitlemesini deneyebilir. Yerel kaydın başarılı olması, eşitlemenin tamamlandığını göstermez. Diğer model yönetimi işlemleri çalışan proxy’nin yönetim API’sini kullanır; çağrıdan önce hazır olma durumunu ve sürümünü kontrol edin. Modelleri veya yapılandırmayı çevrimdışı incelemek için proxy’yi başlatmak gerekmez.
 
 | Alt komut | Desteklenen bayraklar | Eylem |
 | --- | --- | --- |
diff --git a/docs-site/src/content/docs/zh-cn/reference/cli/agents.md b/docs-site/src/content/docs/zh-cn/reference/cli/agents.md
index 5607ead7a94..239bf080052 100644
--- a/docs-site/src/content/docs/zh-cn/reference/cli/agents.md
+++ b/docs-site/src/content/docs/zh-cn/reference/cli/agents.md
@@ -101,13 +101,16 @@ ocx debug usage logs [-f|--follow]
 
 ### `ocx access <key|endpoints|models|test> ...`
 
-管理 OpenCodex 准入 API 密钥，并检查外部端点和模型。`ocx api-key
-<list|create|remove> ...` 是 `ocx access key` 的别名。
+查看 OpenCodex 接入 API 密钥列表、外部端点和模型。`ocx api-key` 是 `ocx access key` 命令组的别名。
+
+创建密钥和开始轮换时，无论选择文本还是 JSON 输出，都会返回仅显示一次的明文凭据。代理应将这些步骤交给人在代理会话之外直接操作的终端完成。不要索要密钥本身，也不要让用户将其粘贴到聊天中；只接收配置和连接验证的确认，以及非秘密的密钥 ID 和轮换 ID。
 
 ```bash
-ocx access key create deployment
+ocx access key list --json
 ```
 
+确认新密钥已配置并验证连接，不等于批准撤销旧密钥。提交轮换或删除旧密钥前，需要另行获得撤销该密钥的明确授权。执行获准的操作后，再次查看列表。不要通过直接调用 API 绕过这一流程。
+
 ## Client integrations
 
 ### `ocx integration <claude|grok> ...`
diff --git a/docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md b/docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md
index 6f77503e6b3..e8b01867515 100644
--- a/docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md
@@ -344,9 +344,7 @@ v1 恢复矩阵覆盖的是事务文件通过重命名发布后 OpenCodex 进程
 `disable` 和 `provider` 控制可见性；`selected` 控制提供方允许列表；`context` 控制提供方
 上下文上限；`shadow` 管理后台 shadow-call 拦截。
 
-这里提供仪表盘中所有逐模型操作，因此无头安装永远不需要 GUI 来管理目录。`add`、
-`remove` 和 `list-custom` 针对配置文件工作，并通过目录同步应用到正在运行的代理；
-其余命令会与在线管理 API 通信，并要求代理正在运行（`ocx start`，或已安装的服务）。
+下表说明 CLI 支持的模型目录操作，并不涵盖仪表盘中的所有操作。修改自动发现模型的显示名称与自定义模型的 `edit` 操作不同。`add`、`remove` 和 `list-custom` 使用本地配置；修改自定义模型时，如果代理正在运行，可能会尝试同步目录。本地保存成功并不代表同步已完成。其他模型管理操作使用运行中代理的管理 API，调用前应检查就绪状态和版本。离线查看模型或配置不需要启动代理。
 
 | 子命令 | 支持的标志 | 操作 |
 | --- | --- | --- |
diff --git a/docs-site/src/content/docs/zh-tw/reference/cli/agents.md b/docs-site/src/content/docs/zh-tw/reference/cli/agents.md
index 6b33b91c165..8e89e66d454 100644
--- a/docs-site/src/content/docs/zh-tw/reference/cli/agents.md
+++ b/docs-site/src/content/docs/zh-tw/reference/cli/agents.md
@@ -96,13 +96,16 @@ ocx debug usage logs [-f|--follow]
 
 ### `ocx access <key|endpoints|models|test> ...`
 
-管理 OpenCodex 許可 API 金鑰並檢查外部端點與模型。`ocx api-key
-<list|create|remove> ...` 是 `ocx access key` 的別名。
+檢視 OpenCodex 存取用 API 金鑰清單、外部端點與模型。`ocx api-key` 是 `ocx access key` 指令群組的別名。
+
+建立金鑰與開始輪替時，無論使用文字或 JSON 輸出，都會傳回僅顯示一次的明文憑證。代理應將這些步驟交由人在代理工作階段之外直接操作的終端機完成。不要索取金鑰本身，也不要請使用者貼到聊天中；只接收設定與連線驗證的確認，以及非機密的金鑰 ID 和輪替 ID。
 
 ```bash
-ocx access key create deployment
+ocx access key list --json
 ```
 
+確認新金鑰已設定並通過連線驗證，不等於核准撤銷舊金鑰。確認輪替或刪除舊金鑰前，必須另行取得撤銷該金鑰的明確授權。執行獲准的操作後，請再次檢視清單。不要透過直接呼叫 API 繞過此流程。
+
 ## 客戶端整合
 
 ### `ocx integration <claude|grok> ...`
diff --git a/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md b/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md
index e35f067cd8b..3be101615ff 100644
--- a/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md
+++ b/docs-site/src/content/docs/zh-tw/reference/cli/providers-accounts.md
@@ -325,7 +325,7 @@ Preview 建置使用 `<OPENCODEX_HOME>/native-main-profiles`。該配置絕不
 
 `ocx model` 是 `ocx models` 的別名。無子指令時，列出已設定供應商中靜態播種的模型。`--provider` 過濾一個已設定的供應商，而 `--json` 回傳模型中繼資料。`live` 讀取執行中的目錄；`add`、`edit`、`remove` 與 `list-custom` 管理手動目錄項目；`enable`、`disable` 與 `provider` 控制可見性；`selected` 控制供應商允許清單；`context` 控制供應商 context 上限；而 `shadow` 管理背景 shadow-call 攔截。
 
-儀表板提供的每個 per-model 操作在此皆可用，因此無頭安裝永不需要 GUI 來管理目錄。`add`、`remove` 與 `list-custom` 針對設定檔運作並透過目錄同步套用於執行中的代理；其餘與即時管理 API 通訊並需要代理正在執行（`ocx start` 或已安裝的服務）。
+下表說明 CLI 支援的模型目錄操作，並未涵蓋儀表板中的所有操作。修改自動探索模型的顯示名稱，與自訂模型的 `edit` 操作不同。`add`、`remove` 和 `list-custom` 使用本機設定；修改自訂模型時，如果代理伺服器正在執行，可能會嘗試同步目錄。本機儲存成功不代表同步已完成。其他模型管理操作使用執行中代理伺服器的管理 API，呼叫前應檢查就緒狀態與版本。離線檢視模型或設定不需要啟動代理伺服器。
 
 | 子指令 | 支援的旗標 | 動作 |
 | --- | --- | --- |
diff --git a/scripts/generate-ocx-skill-surface.ts b/scripts/generate-ocx-skill-surface.ts
index b0ede70217e..f54fcc1c92d 100644
--- a/scripts/generate-ocx-skill-surface.ts
+++ b/scripts/generate-ocx-skill-surface.ts
@@ -1,111 +1,182 @@
 /**
- * Generates `skills/ocx/references/01_management_surface.md` from the capability table.
+ * Generate the compact operating-skill index and its owned domain chapters.
+ * Pure renderers use the public capability facade; I/O stays in the CLI entry point.
  *
- * Generated rather than written, because a hand-maintained surface map is a SECOND description
- * of the CLI that is free to drift from the first -- the same defect class this unit removed from
- * the help text. `tests/ci-workflows/skill-ocx.test.ts` asserts the committed file matches this output, so a
- * capability added without regenerating fails CI instead of silently shipping a stale skill.
- *
- * Usage:
- *   bun scripts/generate-ocx-skill-surface.ts            # write
- *   bun scripts/generate-ocx-skill-surface.ts --check     # exit 1 if stale
+ * bun scripts/generate-ocx-skill-surface.ts          # write expected files only
+ * bun scripts/generate-ocx-skill-surface.ts --check  # reject missing/stale/extra owned files
  */
-import { writeFileSync, readFileSync, existsSync } from "node:fs";
+import { writeFileSync, readFileSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { CAPABILITIES, HEAD_CAPABILITIES, capabilityInvocation } from "../src/cli/capabilities";
+import { CAPABILITIES, HEAD_CAPABILITIES, capabilityInvocation, type Capability } from "../src/cli/capabilities";
 
-const TARGET = join(import.meta.dir, "..", "skills", "ocx", "references", "01_management_surface.md");
+const DIRECTORY = join(import.meta.dir, "..", "skills", "ocx", "references");
+const INDEX = "01_management_surface.md";
+const OWNER = "GENERATED by scripts/generate-ocx-skill-surface.ts";
+const PREAMBLE = `<!-- ${OWNER}. Do not edit by hand. -->\n<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->\n`;
 
-export function renderManagementSurface(): string {
-  const lines: string[] = [];
-  lines.push("<!-- GENERATED by scripts/generate-ocx-skill-surface.ts. Do not edit by hand. -->");
-  lines.push("<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->");
-  lines.push("");
-  lines.push("# The `ocx` management surface");
-  lines.push("");
-  lines.push("Every capability the CLI declares, with the management routes it drives and whether it");
-  lines.push("mutates state. This file is generated from the same table `ocx capabilities --json`");
-  lines.push("serves, so it cannot describe a command that does not exist.");
-  lines.push("");
-  lines.push("Ask the running binary instead of trusting this file when the two disagree:");
-  lines.push("");
-  lines.push("```bash");
-  lines.push("ocx capabilities --json                 # the whole table");
-  lines.push("ocx capabilities --mutating-only --json  # only state-changing verbs");
-  lines.push("ocx capabilities --route /api/logs      # which verbs drive one route");
-  lines.push("```");
-  lines.push("");
+// Navigation groups, not command dispatch. New roots require an explicit assignment.
+const DOMAINS = [
+  { name: "lifecycle", roots: ["chatgpt", "status", "resolve", "capabilities", "sync", "start", "stop", "restart", "service", "gui"] },
+  { name: "providers-models", roots: ["provider", "models", "alias"] },
+  { name: "accounts", roots: ["account", "auth", "login", "logout"] },
+  { name: "agents-routing", roots: ["agent", "combo", "route", "v2", "effort", "memory"] },
+  { name: "integrations", roots: ["claude", "integration", "grok", "codex-shim"] },
+  { name: "observe-system", roots: ["companion", "usage", "logs", "storage", "inspect", "system", "observe", "debug", "export", "import", "cost", "update", "config", "tray"] },
+  { name: "access-remote", roots: ["link", "remote-workspace", "hub", "connect", "api", "access"] },
+  { name: "lab", roots: ["lab"] },
+];
 
-  lines.push("## Resolved before dispatch");
-  lines.push("");
-  lines.push("These answer in the CLI head and never reach the proxy, so they work with nothing running.");
-  lines.push("");
-  lines.push("| Invocation | Purpose |");
-  lines.push("|---|---|");
+function chapterFilename(domain: string): string {
+  return `01_surface_${domain}.md`;
+}
+
+// GitHub Markdown anchors for canonical CLI headings (backticks are presentation only).
+function invocationAnchor(invocation: string): string {
+  return invocation.toLowerCase().replace(/[^\p{L}\p{N}_\-\s]/gu, "").replace(/ /g, "-");
+}
+
+function assignChapters(): Map<Capability, string> {
+  const roots = new Map<string, string>();
+  for (const domain of DOMAINS) {
+    for (const root of domain.roots) {
+      if (roots.has(root)) throw new Error(`Duplicate surface root: ${root}`);
+      roots.set(root, chapterFilename(domain.name));
+    }
+  }
+  const assignments = new Map<Capability, string>();
+  const anchors = new Set<string>();
+  for (const cap of CAPABILITIES) {
+    const file = roots.get(cap.command[0]!);
+    if (!file) throw new Error(`Unknown surface root: ${cap.command[0]}`);
+    const invocation = capabilityInvocation(cap);
+    const anchor = invocationAnchor(invocation);
+    if (anchors.has(anchor)) throw new Error(`Surface anchor collision: ${invocation} (#${anchor})`);
+    anchors.add(anchor);
+    assignments.set(cap, file);
+  }
+  return assignments;
+}
+
+// These existing discoverable names return plaintext credentials. Preserve their anchors
+// as prose handoffs, never turn them into executable-looking recipes.
+const SECRET_HANDOFFS = new Set(["ocx link issue", "ocx hub invite", "ocx config export"]);
+function capabilityHeading(invocation: string): string {
+  return SECRET_HANDOFFS.has(invocation) ? `### ${invocation}` : `### \`${invocation}\``;
+}
+
+function renderIndex(assignments: Map<Capability, string>): string {
+  const lines = [PREAMBLE, "# The `ocx` management surface", "",
+    "Declared capabilities, grouped by operating task. This index is not every CLI verb.",
+    "Read the chapter for routes, flags and mutation notes; use the running binary when versions differ.", "",
+    "```bash", "ocx capabilities --json                 # the declared table",
+    "ocx capabilities --mutating-only --json  # declared state-changing verbs",
+    "ocx capabilities --route /api/logs       # declarations for one route", "```", "",
+    "## Resolved before dispatch", "",
+    "These answer in the CLI head and never reach the proxy, so they work with nothing running.", "",
+    "| Invocation | Purpose |", "|---|---|"];
   for (const head of HEAD_CAPABILITIES) {
-    lines.push(`| \`${head.invocations.join("\` \`")}\` | ${head.summary} |`);
+    lines.push(`| \`${head.invocations.join("` `")}\` | ${tableCell(head.summary)} |`);
   }
-  lines.push("");
+  lines.push("", "## Task chapters", "", "| Chapter | Declared capabilities |", "|---|---|");
+  for (const domain of DOMAINS) {
+    const file = chapterFilename(domain.name);
+    const count = [...assignments.values()].filter(value => value === file).length;
+    lines.push(`| [${domain.name}](${file}) | ${count} |`);
+  }
+  lines.push("", "## Read-only capabilities", "",
+    "Read-oriented tasks are marked non-mutating in the registry. Probes may contact providers,",
+    "consume quota or refresh caches; this label does not promise cost-free or effect-free execution.", "",
+    "## State-changing capabilities", "",
+    "Check the chapter's flags, the requested authority and the operating skill's consent and secret rules.", "",
+    "## Canonical invocation index", "",
+    "Original invocation order. These headings preserve links to the previous single-file reference.", "");
+  for (const cap of CAPABILITIES) {
+    const invocation = capabilityInvocation(cap);
+    lines.push(capabilityHeading(invocation), "",
+      `[${cap.mutates ? "State-changing task" : "Read-oriented task"}](${assignments.get(cap)}#${invocationAnchor(invocation)})`, "");
+  }
+  lines.push("## Counts", "", `- declared capabilities: ${CAPABILITIES.length}`,
+    `- of those, state-changing: ${CAPABILITIES.filter(cap => cap.mutates).length}`,
+    `- head-resolved invocations: ${HEAD_CAPABILITIES.length}`, "");
+  return lines.join("\n");
+}
 
-  const mutating = CAPABILITIES.filter(c => c.mutates);
-  const reading = CAPABILITIES.filter(c => !c.mutates);
+/** Preserve literal prose inside a Markdown table cell, including enum separators. */
+function tableCell(value: string | undefined): string {
+  return (value ?? "").replaceAll("\\", "\\\\").replaceAll("|", "\\|").replace(/\r\n|[\r\n]/g, "<br>");
+}
 
-  for (const [title, group, note] of [
-    ["Read-only capabilities", reading, "Safe to run at any time; none of these change state."],
-    ["State-changing capabilities", mutating, "Each of these writes. Check the flags column before running one unattended."],
-  ] as const) {
-    lines.push(`## ${title}`);
-    lines.push("");
-    lines.push(note);
+function renderCapability(cap: Capability): string[] {
+  const invocation = capabilityInvocation(cap);
+  const handoff = SECRET_HANDOFFS.has(invocation);
+  const lines = [capabilityHeading(invocation), ""];
+  if (handoff) lines.push("Human-only handoff: ask the operator to perform this in their own terminal or dashboard; do not capture the secret-bearing result.", "");
+  if (!handoff && cap.usage !== undefined) lines.push(`Usage: \`${cap.usage}\``, "");
+  lines.push(cap.summary, "", `State-changing: ${cap.mutates ? "yes" : "no"}.`, "");
+  if (cap.routes.length > 0) {
+    lines.push("| Method | Route |", "|---|---|");
+    for (const route of cap.routes) lines.push(`| ${route.method} | \`${route.path}\` |`);
+  } else {
+    lines.push("Drives no management route.");
+  }
+  lines.push("");
+  if (cap.flags.length > 0) {
+    lines.push("| Flag | Value | Meaning |", "|---|---|---|");
+    for (const flag of cap.flags) lines.push(`| \`${flag.name}\` | ${tableCell(flag.value)} | ${tableCell(flag.summary)} |`);
     lines.push("");
-    for (const cap of group) {
-      lines.push(`### \`${capabilityInvocation(cap)}\``);
-      lines.push("");
-      lines.push(cap.summary);
-      lines.push("");
-      if (cap.routes.length > 0) {
-        lines.push("| Method | Route |");
-        lines.push("|---|---|");
-        for (const route of cap.routes) lines.push(`| ${route.method} | \`${route.path}\` |`);
-      } else {
-        lines.push("Drives no management route.");
-      }
-      lines.push("");
-      if (cap.flags.length > 0) {
-        lines.push("| Flag | Value | Meaning |");
-        lines.push("|---|---|---|");
-        for (const flag of cap.flags) lines.push(`| \`${flag.name}\` | ${flag.value} | ${flag.summary} |`);
-        lines.push("");
-      }
-      lines.push(`JSON mode: \`${cap.json}\`.`);
-      lines.push("");
-      for (const detail of cap.details ?? []) lines.push(`- ${detail}`);
-      if ((cap.details ?? []).length > 0) lines.push("");
-    }
   }
+  lines.push(`JSON mode: \`${cap.json}\`.`, "");
+  for (const detail of cap.details ?? []) lines.push(`- ${detail}`);
+  if ((cap.details ?? []).length > 0) lines.push("");
+  return lines;
+}
+
+/** Deterministic filename → Markdown map; no filesystem reads or metadata mutation. */
+export function renderManagementSurfaces(): Record<string, string> {
+  const assignments = assignChapters();
+  const files: Record<string, string> = { [INDEX]: renderIndex(assignments) };
+  for (const domain of DOMAINS) {
+    const file = chapterFilename(domain.name);
+    const caps = CAPABILITIES.filter(cap => assignments.get(cap) === file);
+    const lines = [PREAMBLE, `# ${domain.name}: declared management tasks`, "",
+      `[Management index](${INDEX}) · [Operating rules](../SKILL.md#secret-bearing-commands)`, "",
+      "Use these declarations to choose a task, then check its flags and authority before execution.",
+      "Non-mutating probes may still contact providers, consume quota or refresh caches.", "",
+      `Declared capabilities: ${caps.length}.`, ""];
+    if (caps.length === 0) lines.push("No declared capabilities yet. This chapter reserves navigation space; it does not promise a command.", "");
+    for (const cap of caps) lines.push(...renderCapability(cap));
+    files[file] = lines.join("\n");
+  }
+  for (const [file, content] of Object.entries(files)) {
+    if (content.split("\n").length - 1 >= 2000) throw new Error(`Surface file must stay below 2000 lines: ${file}`);
+  }
+  return files;
+}
 
-  lines.push("## Counts");
-  lines.push("");
-  lines.push(`- declared capabilities: ${CAPABILITIES.length}`);
-  lines.push(`- of those, state-changing: ${mutating.length}`);
-  lines.push(`- head-resolved invocations: ${HEAD_CAPABILITIES.length}`);
-  lines.push("");
-  return lines.join("\n");
+/** Compatibility entry point: the compact index, including old fragment forwarders. */
+export function renderManagementSurface(): string {
+  return renderManagementSurfaces()[INDEX]!;
 }
 
 if (import.meta.main) {
-  const rendered = renderManagementSurface();
+  const files = renderManagementSurfaces();
+  const extra = readdirSync(DIRECTORY).filter(file =>
+    /^01_surface_.*\.md$/.test(file) && !Object.hasOwn(files, file)
+    && readFileSync(join(DIRECTORY, file), "utf8").includes(OWNER)).sort();
+  for (const file of extra) console.error(`Unexpected generated chapter: ${file}. Review and remove it explicitly; generation never deletes files.`);
   if (process.argv.includes("--check")) {
-    const current = existsSync(TARGET) ? readFileSync(TARGET, "utf8") : "";
-    if (current === rendered) {
-      console.log("skills/ocx/references/01_management_surface.md is current.");
-      process.exit(0);
+    const stale = Object.entries(files).filter(([file, content]) =>
+      !existsSync(join(DIRECTORY, file)) || readFileSync(join(DIRECTORY, file), "utf8") !== content);
+    for (const [file] of stale) console.error(`${file} is missing or STALE.`);
+    if (stale.length || extra.length) {
+      console.error("Regenerate: bun scripts/generate-ocx-skill-surface.ts");
+      process.exit(1);
+    }
+    console.log(`All ${Object.keys(files).length} generated management surface files are current.`);
+  } else {
+    for (const [file, content] of Object.entries(files)) {
+      writeFileSync(join(DIRECTORY, file), content);
+      console.log(`wrote skills/ocx/references/${file}`);
     }
-    console.error("skills/ocx/references/01_management_surface.md is STALE.");
-    console.error("Regenerate: bun scripts/generate-ocx-skill-surface.ts");
-    process.exit(1);
   }
-  writeFileSync(TARGET, rendered);
-  console.log(`wrote ${TARGET}`);
 }
-
diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
index 6d4c2773830..5392c79fc37 100644
--- a/scripts/test-layout/layout.json
+++ b/scripts/test-layout/layout.json
@@ -2,6 +2,9 @@
   "version": 1,
   "root": "tests",
   "explicit": {
+    "cli-capability-integration-workflows.test.ts": "cli", "cli-capability-account-workflows.test.ts": "cli", "cli-capability-agent-workflows.test.ts": "cli", "cli-capability-operation-workflows.test.ts": "cli",
+    "cli-capability-provider-workflows.test.ts": "cli", "cli-capability-access-workflows.test.ts": "cli", "cli-capability-lab-workflows.test.ts": "cli", "skill-ocx-workflows.test.ts": "ci-workflows",
+    "cli-capability-data.test.ts": "cli", "skill-ocx-generated.test.ts": "ci-workflows",
     "cli-update-restart.test.ts": "cli",
     "cli-update-restart-child.test.ts": "cli",
     "cli-update-restart-transport.test.ts": "cli",
diff --git a/skills/ocx/SKILL.md b/skills/ocx/SKILL.md
index 700a0c974b1..075aa807454 100644
--- a/skills/ocx/SKILL.md
+++ b/skills/ocx/SKILL.md
@@ -1,90 +1,74 @@
 ---
 name: ocx
-description: "Drive a running opencodex (`ocx`) proxy from the CLI — account pools, provider routing, model catalog, usage and cost attribution, request logs, access keys, storage cleanup, and the management API. Use when a task involves controlling or inspecting an opencodex proxy rather than editing the opencodex codebase. Triggers: ocx, opencodex, proxy control, account pool, pause account, pool strategy, provider routing, usage report, cost attribution, access key, request log, conversation trace, storage cleanup, management API."
+description: "Operate opencodex (`ocx`): discover CLI tasks offline, inspect local configuration, and manage a running proxy’s account pool, providers, models, routing, usage report, and management API. Use for proxy operation rather than editing the opencodex codebase."
 ---
 
 # Operating `ocx`
 
-`ocx` controls a locally running opencodex proxy. The CLI covers the dashboard's operational
-surface, subject to Consent and Secret-bearing commands below. `ocx capabilities`
-lists the *declared* index, not every verb.
+`ocx` supports local configuration and named live management workflows. Coverage is
+per task: provider edits, account selection, model visibility, routing reads, client
+integration controls and diagnostics have different transports and limits. A shared
+API prefix does not prove that every dashboard action has a CLI equivalent.
 
-Be precise about the gap, because guessing costs you more than reading: the capability index below
-is complete and authoritative for what it lists, and it does not yet list every management route.
-A route with no declared capability may still have a working command — `ocx access key` and
-`ocx route policy` both work while `capabilities --route` returns nothing for them. So use the
-index first, and fall back to `ocx <group> help` before concluding a capability is missing.
+This skill is for **operating** a proxy. `AGENTS_INSTALL.md` covers installation
+and operating consent; the repository `AGENTS.md` covers code changes.
 
-This skill is for **operating** a proxy. Two neighbours cover different jobs: `AGENTS_INSTALL.md`
-is for installing one, and the repository `AGENTS.md` is for changing the codebase.
+## Find the task offline
 
-## Start here
+Start at the smallest useful level; no running proxy is needed for help:
 
 ```bash
-ocx capabilities --json
+ocx help                         # compact root
+ocx help models                  # family and declared children
+ocx help models preset show      # exact leaf, when declared
+ocx help --all                   # full top-level reference, when needed
 ```
 
-That is the machine-readable index of declared verbs, the routes they drive, their flags, and whether they
-mutate. Read it first rather than guessing a command name. It is not exhaustive — an unmatched
-`--route` exits 4 when the table has no row, even if a working verb exists. The converse of
-generation also holds: a verb can exist without appearing here (`ocx access key`, `ocx route policy`).
+Then read only the matching [task chapter](references/01_management_surface.md).
+For example, use [providers/models](references/01_surface_providers-models.md)
+for catalog work or [Lab](references/01_surface_lab.md) for local evidence.
+Use `ocx help <family> <leaf>` or appended `--help`, not a trailing bare `help`
+after nested operands. Missing detail can fall back to family help; it is not
+proof that a runtime operation is absent.
 
-Narrow it when you already know what you want:
+For a route you already know, an optional lookup is:
 
 ```bash
-ocx capabilities --mutating-only --json      # only state-changing verbs
-ocx capabilities --route /api/logs           # which verbs drive one route
+ocx capabilities --route '/api/providers/{provider}/model-costs' --json
 ```
 
-An unmatched `--route` exits 4 rather than printing an empty success.
+This matches the **declared path template**, not a concrete provider URL or HTTP
+method. Exit 4 means no declaration matched. Full `ocx capabilities --json` and
+`--mutating-only --json` are useful for broad inventories, not mandatory preflight.
+Declarations describe the installed CLI; actual handlers remain the grammar authority.
 
-## Three steps before any management call
+## Before live management work
 
-1. `ocx ready --json` — is the proxy up and admitting requests?
-2. `ocx status --json` — is this binary the same build as the running proxy? A version skew means
-   the help and flags you just read describe a *different* build than the one answering.
-3. Then the real command, with `--json`.
+1. `ocx ready --json` checks readiness (`ready`, `pending`, `failed`, `unreachable`).
+2. `ocx status --json` checks the target and `versionSkew.relation`. `unknown` is
+   not a confirmed match; a mismatch needs the intended installation resolved.
+3. Run the task with `--json` **only when that leaf supports it**. `ocx doctor`
+   rejects it; `ocx v2` has human output, not a JSON contract.
 
-Skipping step 2 is how an agent ends up reporting that a flag "does not work" when it simply does
-not exist in the running build yet.
+These checks do not require starting a proxy for offline help, local provider
+configuration, config validation or local Lab inspection. On a connected client,
+ordinary management commands do not automatically target the hub: perform them
+on the hub or use its dashboard. See [remote targeting](references/05_remote_hub.md).
 
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| 0 | success |
-| 2 | usage error — bad or missing arguments; nothing was sent |
-| 4 | not found — the named account, provider, key, or route does not exist |
-| 5 | conflict — a lock is held or the state changed under you; usually retryable |
-| 1 | everything else, including transport failure and any other HTTP error |
-
-**Never read a printed error with exit 0 as success.** Commands used to print a failure and exit 0;
-they no longer do, and a source scan keeps it that way. Exit 0 means no error was reported;
-inspect the result to see whether anything mutated (cleanup without `--yes` is a preview).
-
-## Reading a failure
-
-A management failure prints up to three lines: the message, then `reason:`, then `hint:`. The
-`reason` is the machine-actionable part — branch on it, not on the prose.
-
-Four named classes are worth handling specifically:
-
-| Reason | What it means | What to do |
-|---|---|---|
-| `oauth_mutation_busy` | another credential write is in flight (503, `Retry-After: 1`) | retry once after a second |
-| `catalog_busy` | a catalog gather is in flight (503, `Retry-After: 1`) | retry once after a second |
-| a config-mutation lock reason | a config write holds the lock | retry shortly |
-| a credential-conflict reason | the install is broken, not busy | run `ocx doctor`; retrying will not help |
-
-The first two are transient by construction and the server tells you how long to wait. The last is
-the one to stop on: repeating it just produces the same error more times.
+Inspect both the exit code and receipt. Saved config, runtime application, client
+file convergence, skipped work and partial completion are different outcomes;
+read back the relevant setting after a write. Exit 0 also covers previews and
+intentional no-ops. Management failures normally print stderr prose even with
+`--json`; usage codes include 2 and legacy 64 exceptions for `capabilities`,
+`ready`, and `resolve`. See [JSON shapes](references/02_json_shapes.md) and
+[failure semantics](references/04_failure_semantics.md) before scripting recovery.
 
 ## Consent: one thing you must not do
 
 **Do not star the repository on the user's behalf.** `ocx inspect star` reads the status, and that
-is the entire CLI surface for it. The starring POST requires a real dashboard session precisely so
-an agent cannot answer that question for its user — it spends *their* GitHub identity, which no
-flag can delegate. Do not route around it with `gh`, a direct HTTP call, or a minted session. If
+is the entire CLI surface for it. The starring POST requires a dashboard session, so an ordinary admin-token
+management call cannot perform it. That is not a barrier against a determined local
+agent; the consent rule still binds every mechanism because it spends *their* GitHub identity. Do not route around it with `gh`, a direct HTTP call, or a minted session. If
 starring would be useful, say so and let the user decide.
 
 The same boundary covers the session-gated `/api/codex-prompt` writes: read them with
@@ -132,58 +116,38 @@ Report the count and bytes from that output and get explicit approval before add
 `--mode quarantine` (the default) can be undone with `storage trash restore`; `--mode permanent`
 cannot.
 
-## Remote hub: three things agents get wrong
-
-**A hub is one port, and `ocx hub invite` writes the join command for you.** Remote machines dial
-`hostname:port` with their own per-client key; the hub's own processes dial `127.0.0.1:<the same
-port>` with no credential, through the loopback companion listener
-(`unauthenticatedLoopbackListener: {"enabled": true}`, no port). Have the operator run `ocx hub invite`
-on the hub outside the agent session rather than assembling an `ocx connect` line: it mints a single-use code and prints the exact
-command, with both origins already filled in. Its `--management-url` is a confirmation of
-`hub.managementPublicOrigin`, not an override. The operator transfers the command directly to the joining machine; keep it out of the transcript.
-
-Two consequences that look like bugs and are not. `ocx status` on a hub prints a `Hub:` block —
-read it before asking the operator anything about ports or tokens. And a hub does not rewrite its
-**own** Codex/Grok/Claude configs unless that listener is enabled; the skip says so in those words,
-and it is a gate, not the `clientIntegrations` toggle.
-
-**Pairing is not hub setup.** Configuring a hub — providers, accounts, routing, keys — never
-needs a pairing code. `GET /opencodex-session` mints a session by itself for a loopback
-request, and for a `hub` reached over the trusted Tailscale ingress when the login is in
-`remoteGui.allowedTailscaleUsers`. A pairing grant is the fallback for a remote browser that
-neither position nor identity vouches for. The management API is a separate ladder again: an
-agent driving a hub uses the admin token and never pairs. When a human asks "do I have to pair
-to set this up?", the answer is no.
-
-**`ocx disconnect` is only half of leaving a hub.** It restores local state and clears the
-connection, then tells you the hub key is still valid. Revoke it too: `ocx connect revoke
---admin-token-stdin` while still connected, or delete the key in the hub dashboard under
-Integrations → API Keys once the device is gone. Stopping after `disconnect` leaves a working
-credential behind.
-
-Credentials for these commands are stdin-only — `--pairing-code-stdin` and
-`--admin-token-stdin`. There is no argv or environment form, and that is deliberate.
-
-When `disconnect` refuses, do not route around it. Each refusal means the unwind cannot be
-proven safe: another process owns the token, no journal records the pre-connect state, a
-different client key owns the journal, or the restore was only partial.
-
-Details, including the one-port recipe, the invite flow and key rotation's two-step commit:
-`references/05_remote_hub.md`. Service and launchd semantics, including why
-`ocx service repair` can correctly do nothing while `ocx service restart` always restarts —
-so a restart is never a hand-written `launchctl kickstart`:
-`references/04_failure_semantics.md`.
+## Remote hub
+
+Read `ocx status` on the hub and `ocx connect status --json` on the client before
+changing their configuration. Pairing is not required to configure the hub.
+The optional loopback companion serves inference only, never management calls.
+A human transfers the invite directly to the joining machine outside this session.
+Remote credential inputs remain stdin-only (`--pairing-code-stdin`,
+`--admin-token-stdin`), never literal argv or environment values.
+
+Disconnect restores local state but leaves the hub key valid. With explicit
+revocation authority, revoke while still connected, or have the operator revoke
+on the hub after disconnection. Do not work around ownership or partial-restore
+refusals. [Remote hub](references/05_remote_hub.md) covers the one-port setup,
+credential handoff, managed rotation and disconnection order.
 
 ## References
 
 | File | Use it for |
 |---|---|
-| `references/01_management_surface.md` | the full capability → route map (generated) |
-| `references/02_json_shapes.md` | response envelopes and error shapes |
-| `references/03_recipes.md` | copy-paste sequences for real tasks |
-| `references/04_failure_semantics.md` | exit codes, 503 classes, what to retry |
-| `references/05_remote_hub.md` | hub/client roles, when pairing is and is not needed, key rotation, disconnection |
-
-`01_management_surface.md` is generated by `scripts/generate-ocx-skill-surface.ts` and a test fails
-if the committed copy drifts from the capability table. When it and the running binary disagree,
-believe `ocx capabilities --json`.
+| [Management index](references/01_management_surface.md) | declared capabilities in eight task chapters, with routes, flags and mutation notes (generated) |
+| [JSON shapes](references/02_json_shapes.md) | response envelopes and error shapes |
+| [Recipes](references/03_recipes.md) | copy-paste sequences for real tasks |
+| [Failure semantics](references/04_failure_semantics.md) | exit codes, 503 classes, what to retry |
+| [Remote hub](references/05_remote_hub.md) | hub/client roles, when pairing is and is not needed, key rotation, disconnection |
+
+The generated index routes to eight task chapters. Lab includes local reads,
+public evidence operations and explicit automation controls; it is not read-only.
+Read-oriented probes can contact providers, consume quota or refresh caches.
+Routing-profile writes and discovered-model display-name edits are current CLI
+gaps; custom-model editing is a different workflow. Browser presentation and
+session-only consent actions remain outside agent management authority.
+
+The index and chapters are generated by `scripts/generate-ocx-skill-surface.ts`.
+If metadata and execution disagree, check the installed CLI version and the live
+target before reporting unsupported behavior; do not infer a new flag.
diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md
index 817a98fbc03..c32773037ae 100644
--- a/skills/ocx/references/01_management_surface.md
+++ b/skills/ocx/references/01_management_surface.md
@@ -3,16 +3,13 @@
 
 # The `ocx` management surface
 
-Every capability the CLI declares, with the management routes it drives and whether it
-mutates state. This file is generated from the same table `ocx capabilities --json`
-serves, so it cannot describe a command that does not exist.
-
-Ask the running binary instead of trusting this file when the two disagree:
+Declared capabilities, grouped by operating task. This index is not every CLI verb.
+Read the chapter for routes, flags and mutation notes; use the running binary when versions differ.
 
 ```bash
-ocx capabilities --json                 # the whole table
-ocx capabilities --mutating-only --json  # only state-changing verbs
-ocx capabilities --route /api/logs      # which verbs drive one route
+ocx capabilities --json                 # the declared table
+ocx capabilities --mutating-only --json  # declared state-changing verbs
+ocx capabilities --route /api/logs       # declarations for one route
 ```
 
 ## Resolved before dispatch
@@ -24,1314 +21,1190 @@ These answer in the CLI head and never reach the proxy, so they work with nothin
 | `--version` `-v` `version` | Print the CLI version and exit. |
 | `help` `--help` `-h` | Print the command list, or one command's usage with `ocx help <command>`. |
 
+## Task chapters
+
+| Chapter | Declared capabilities |
+|---|---|
+| [lifecycle](01_surface_lifecycle.md) | 12 |
+| [providers-models](01_surface_providers-models.md) | 40 |
+| [accounts](01_surface_accounts.md) | 36 |
+| [agents-routing](01_surface_agents-routing.md) | 38 |
+| [integrations](01_surface_integrations.md) | 33 |
+| [observe-system](01_surface_observe-system.md) | 87 |
+| [access-remote](01_surface_access-remote.md) | 22 |
+| [lab](01_surface_lab.md) | 21 |
+
 ## Read-only capabilities
 
-Safe to run at any time; none of these change state.
+Read-oriented tasks are marked non-mutating in the registry. Probes may contact providers,
+consume quota or refresh caches; this label does not promise cost-free or effect-free execution.
 
-### `ocx link port`
+## State-changing capabilities
 
-Allocate a free loopback port for a remote home link.
+Check the chapter's flags, the requested authority and the operating skill's consent and secret rules.
 
-Drives no management route.
+## Canonical invocation index
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the selected port as JSON. |
+Original invocation order. These headings preserve links to the previous single-file reference.
 
-JSON mode: `payload`.
+### `ocx chatgpt`
 
-### `ocx link status`
+[State-changing task](01_surface_lifecycle.md#ocx-chatgpt)
 
-Read link listener and tunnel status.
+### `ocx link port`
 
-| Method | Route |
-|---|---|
-| GET | `/api/link/status` |
+[Read-oriented task](01_surface_access-remote.md#ocx-link-port)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the K16 status payload as JSON. |
+### ocx link issue
 
-JSON mode: `payload`.
+[State-changing task](01_surface_access-remote.md#ocx-link-issue)
 
-### `ocx remote-workspace status`
+### `ocx link status`
 
-Read local executor enrollment and available capabilities without printing credentials.
+[Read-oriented task](01_surface_access-remote.md#ocx-link-status)
 
-Drives no management route.
+### `ocx link revoke`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the public local executor status. |
+[State-changing task](01_surface_access-remote.md#ocx-link-revoke)
 
-JSON mode: `payload`.
+### `ocx remote-workspace pair`
 
-- Executor-local operation; Hub consent and session control stay in the dashboard.
+[State-changing task](01_surface_access-remote.md#ocx-remote-workspace-pair)
 
-### `ocx models price`
+### `ocx remote-workspace agent`
 
-Read the saved manual price for an exact provider/model selector.
+[State-changing task](01_surface_access-remote.md#ocx-remote-workspace-agent)
 
-| Method | Route |
-|---|---|
-| GET | `/api/providers/{provider}/model-costs` |
+### `ocx remote-workspace status`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit provider, modelId, and cost (null for automatic pricing). |
+[Read-oriented task](01_surface_access-remote.md#ocx-remote-workspace-status)
 
-JSON mode: `envelope`.
+### `ocx models price`
 
-- The provider must be configured; everything after the first slash is the exact upstream model ID.
+[Read-oriented task](01_surface_providers-models.md#ocx-models-price)
 
-### `ocx status`
+### `ocx models set-price`
 
-Proxy status, injection state, and version skew between this CLI and the running proxy.
+[State-changing task](01_surface_providers-models.md#ocx-models-set-price)
 
-Drives no management route.
+### `ocx models set`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the status envelope as JSON. |
+[State-changing task](01_surface_providers-models.md#ocx-models-set)
 
-JSON mode: `envelope`.
+### `ocx status`
 
-- Reads /healthz plus local config; drives no management API route.
+[Read-oriented task](01_surface_lifecycle.md#ocx-status)
 
 ### `ocx resolve`
 
-One JSON document naming the config home, the effective port, and the identity-checked proxy liveness verdict.
+[Read-oriented task](01_surface_lifecycle.md#ocx-resolve)
 
-Drives no management route.
+### ocx hub invite
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the resolve document as JSON (the shell contract). |
+[State-changing task](01_surface_access-remote.md#ocx-hub-invite)
 
-JSON mode: `envelope`.
+### `ocx connect rotate`
 
-- Exit 0 carries a trustworthy verdict (live or proven absent); exit 1 means the CLI could not resolve and a caller must refuse to guess — unknown liveness never reads as absent.
-- Built for embedding shells (desktop app): the liveness budgets stay owned by src/server/proxy-liveness.ts.
+[State-changing task](01_surface_access-remote.md#ocx-connect-rotate)
 
 ### `ocx capabilities`
 
-List the declared CLI capabilities and the management routes they drive.
+[Read-oriented task](01_surface_lifecycle.md#ocx-capabilities)
 
-Drives no management route.
+### `ocx provider list`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the full capability table as JSON. |
-| `--mutating-only` | boolean | Restrict output to capabilities that mutate state. |
-| `--route` | string | Show which capabilities drive a management route. |
+[Read-oriented task](01_surface_providers-models.md#ocx-provider-list)
 
-JSON mode: `envelope`.
+### `ocx provider resets`
 
-- Start here when driving ocx programmatically: it is the declared surface index, not a complete verb list.
+[Read-oriented task](01_surface_providers-models.md#ocx-provider-resets)
 
-### `ocx provider list`
+### `ocx provider keychain`
 
-Configured providers with connectivity and selected models.
+[State-changing task](01_surface_providers-models.md#ocx-provider-keychain)
 
-Drives no management route.
+### `ocx companion`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the provider list as JSON. |
-| `--jsonl` | boolean | Emit one configured provider per JSON line. |
+[State-changing task](01_surface_observe-system.md#ocx-companion)
 
-JSON mode: `envelope`.
+### `ocx account login`
 
-- Reads local config; drives no management API route.
+[State-changing task](01_surface_accounts.md#ocx-account-login)
 
-### `ocx provider resets`
+### `ocx account history`
 
-Recently detected quota resets and whether reset notifications are enabled.
+[Read-oriented task](01_surface_accounts.md#ocx-account-history)
 
-| Method | Route |
-|---|---|
-| GET | `/api/quota-resets` |
+### `ocx account main reauth`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit reset events as JSON. |
-| `--limit` | number | Limit returned events; defaults to 20, capped at 100. |
+[State-changing task](01_surface_accounts.md#ocx-account-main-reauth)
 
-JSON mode: `payload`.
+### `ocx account list`
 
-### `ocx account history`
+[Read-oriented task](01_surface_accounts.md#ocx-account-list)
 
-Cached quota observations for one stored Codex pool account.
+### `ocx account import-orca`
 
-| Method | Route |
-|---|---|
-| GET | `/api/codex-auth/quota/history` |
+[State-changing task](01_surface_accounts.md#ocx-account-import-orca)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the bounded observation history. |
-| `--limit` | number | Return the newest 1 to 200 observations. |
+### `ocx account refresh`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_accounts.md#ocx-account-refresh)
 
-- Use account history openai <pool-account-id>. Reads cached observations only; no refresh or warmup. Native main is not included.
+### `ocx account grok-reset-coupons`
 
-### `ocx account list`
+[State-changing task](01_surface_accounts.md#ocx-account-grok-reset-coupons)
 
-Codex OAuth accounts with pool priority and pause state.
+### `ocx usage`
 
-| Method | Route |
-|---|---|
-| GET | `/api/codex-auth/accounts` |
+[Read-oriented task](01_surface_observe-system.md#ocx-usage)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the account list as JSON. |
+### `ocx account pause`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_accounts.md#ocx-account-pause)
 
-- STATUS names `paused` alongside `selected`: a paused-but-selected account still receives requests.
-- `--quota` shows cached Codex windows (including 5h); `--refresh` bypasses the server TTL.
+### `ocx account resume`
 
-### `ocx usage`
+[State-changing task](01_surface_accounts.md#ocx-account-resume)
 
-Token and estimated-cost report over a time range.
+### `ocx account pause-exhausted`
 
-| Method | Route |
-|---|---|
-| GET | `/api/usage` |
+[State-changing task](01_surface_accounts.md#ocx-account-pause-exhausted)
+
+### `ocx account strategy`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--range` | string | today | 1d | 7d | 30d | all |
-| `--since` | string | Inclusive start: epoch milliseconds or full ISO datetime with timezone; requires --until and overrides --range. |
-| `--until` | string | Inclusive end: epoch milliseconds or full ISO datetime with timezone; requires --since. |
-| `--provider` | string | Restrict to one provider. |
-| `--model` | string | Restrict to one model id. |
-| `--json` | boolean | Emit the usage report as JSON. |
+[State-changing task](01_surface_accounts.md#ocx-account-strategy)
 
-JSON mode: `payload`.
+### `ocx account sticky`
 
-- Per-account totals are withheld under `--provider` or `--model`: account rows cannot be honestly re-partitioned by provider, so the report says so rather than printing an empty table.
-- An `(ambiguous)` account row aggregates several accounts; do not read it as one identity.
+[State-changing task](01_surface_accounts.md#ocx-account-sticky)
 
-### `ocx logs`
+### `ocx account routes`
 
-Recent request log rows, filterable by provider, model, conversation, account, and status.
+[State-changing task](01_surface_accounts.md#ocx-account-routes)
 
-| Method | Route |
-|---|---|
-| GET | `/api/logs` |
-
-| Flag | Value | Meaning |
-|---|---|---|
-| `--provider` | string | Restrict to one provider, matching failover attempts too. |
-| `--model` | string | Restrict to one model id, matching failover attempts too. |
-| `--conversation` | string | Restrict to one conversation id (`--conversationId` is accepted too). |
-| `--account` | string | Restrict to one account log label (`main`, `p<hex6>`, `o<hex6>`), matching failover attempts too. |
-| `--status` | string | An exact code (429) or a class (5xx). |
-| `--limit` | number | Row cap; defaults to 200. |
-| `--follow` | boolean | Poll for new rows; add --jsonl to emit JSONL. |
-| `--json` | boolean | Emit the server payload as JSON. |
-| `--jsonl` | boolean | Emit one row per line. |
-
-JSON mode: `payload`.
-
-- `--provider` and `--model` both match a failover attempt, so a request is findable by what actually served it, not only by what was asked for.
-- Rows print `conv=<id>` when the entry carries one, so a conversation filter can be told apart from an empty result.
-- Rows print `acct=<label>` when the account is known, so an `--account` filter can be told apart from an empty result.
-- `--follow` deduplicates by row id and cannot be combined with `--json`.
+### `ocx account auto-switch`
+
+[State-changing task](01_surface_accounts.md#ocx-account-auto-switch)
+
+### `ocx logs`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-logs)
 
 ### `ocx storage report`
 
-Disk usage under CODEX_HOME, with the log-guard protection report.
+[Read-oriented task](01_surface_observe-system.md#ocx-storage-report)
 
-| Method | Route |
-|---|---|
-| GET | `/api/storage` |
+### `ocx storage cleanup`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the storage report as JSON. |
+[State-changing task](01_surface_observe-system.md#ocx-storage-cleanup)
 
-JSON mode: `payload`.
+### `ocx storage trash`
 
-### `ocx inspect config`
+[State-changing task](01_surface_observe-system.md#ocx-storage-trash)
 
-The effective merged configuration the proxy is running.
+### `ocx storage policy`
 
-| Method | Route |
-|---|---|
-| GET | `/api/config` |
+[State-changing task](01_surface_observe-system.md#ocx-storage-policy)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the config as JSON. |
+### `ocx inspect config`
 
-JSON mode: `payload`.
+[Read-oriented task](01_surface_observe-system.md#ocx-inspect-config)
 
 ### `ocx inspect catalog`
 
-The generated model catalog served to clients.
+[Read-oriented task](01_surface_observe-system.md#ocx-inspect-catalog)
 
-| Method | Route |
-|---|---|
-| GET | `/api/catalog` |
+### `ocx inspect routing-analytics`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the catalog as JSON. |
+[Read-oriented task](01_surface_observe-system.md#ocx-inspect-routing-analytics)
 
-JSON mode: `payload`.
+### `ocx inspect pacing`
 
-### `ocx inspect routing-analytics`
+[Read-oriented task](01_surface_observe-system.md#ocx-inspect-pacing)
 
-Aggregate routing outcomes per provider and model.
+### `ocx inspect key-providers`
 
-| Method | Route |
-|---|---|
-| GET | `/api/routing-analytics` |
+[Read-oriented task](01_surface_observe-system.md#ocx-inspect-key-providers)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the analytics payload as JSON. |
+### `ocx inspect codex-prompt`
 
-JSON mode: `payload`.
+[Read-oriented task](01_surface_observe-system.md#ocx-inspect-codex-prompt)
 
-### `ocx inspect pacing`
+### `ocx inspect client-config`
 
-Request-pacing state for one provider or all of them.
+[Read-oriented task](01_surface_observe-system.md#ocx-inspect-client-config)
 
-| Method | Route |
-|---|---|
-| GET | `/api/provider-request-pacing` |
+### `ocx inspect star`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--name` | string | Restrict to one provider; omitted means every provider. |
-| `--json` | boolean | Emit the pacing state as JSON. |
+[Read-oriented task](01_surface_observe-system.md#ocx-inspect-star)
 
-JSON mode: `payload`.
+### `ocx inspect windows-tray`
 
-- An unknown provider name is a 404 rather than an empty result.
+[Read-oriented task](01_surface_observe-system.md#ocx-inspect-windows-tray)
 
-### `ocx inspect key-providers`
+### `ocx system codex-app-server`
 
-Providers that authenticate with an API key rather than OAuth.
+[Read-oriented task](01_surface_observe-system.md#ocx-system-codex-app-server)
 
-| Method | Route |
-|---|---|
-| GET | `/api/key-providers` |
+### `ocx system codex-cli-update check`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the provider list as JSON. |
+[Read-oriented task](01_surface_observe-system.md#ocx-system-codex-cli-update-check)
 
-JSON mode: `payload`.
+### `ocx system codex-cli-update attest`
 
-### `ocx inspect codex-prompt`
+[Read-oriented task](01_surface_observe-system.md#ocx-system-codex-cli-update-attest)
 
-The Codex system prompt state, or the prompt text itself.
+### `ocx system codex-restart`
 
-| Method | Route |
-|---|---|
-| GET | `/api/codex-prompt` |
-| GET | `/api/codex-prompt/text` |
+[State-changing task](01_surface_observe-system.md#ocx-system-codex-restart)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--text` | boolean | Print the prompt body verbatim instead of its metadata. |
-| `--json` | boolean | Emit the prompt metadata as JSON. |
+### `ocx claude config`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_integrations.md#ocx-claude-config)
 
-- Read-only by design: the six mutating prompt routes require a dashboard session.
+### `ocx claude intercept start`
 
-### `ocx inspect client-config`
+[State-changing task](01_surface_integrations.md#ocx-claude-intercept-start)
 
-The generated configuration snippet for a supported client.
+### `ocx claude desktop status`
 
-| Method | Route |
-|---|---|
-| GET | `/api/client-config` |
+[Read-oriented task](01_surface_integrations.md#ocx-claude-desktop-status)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--client` | string | Required client id; the route names every accepted value on error. |
-| `--json` | boolean | Emit the snippet payload as JSON. |
+### `ocx claude desktop bind`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-bind)
 
-### `ocx inspect star`
+### `ocx claude desktop unbind`
 
-Whether this repository is starred by the signed-in GitHub account.
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-unbind)
 
-| Method | Route |
-|---|---|
-| GET | `/api/github/star` |
+### `ocx claude desktop picker status`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the star status as JSON. |
+[Read-oriented task](01_surface_integrations.md#ocx-claude-desktop-picker-status)
 
-JSON mode: `payload`.
+### `ocx claude desktop picker on`
 
-- Starring is never available from the CLI; the verb says so rather than offering a flag that cannot work.
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-picker-on)
 
-### `ocx inspect windows-tray`
+### `ocx claude desktop picker off`
 
-Windows tray helper state.
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-picker-off)
 
-| Method | Route |
-|---|---|
-| GET | `/api/windows-tray` |
+### `ocx claude desktop picker trust`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the tray state as JSON. |
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-picker-trust)
 
-JSON mode: `payload`.
+### `ocx integration native`
 
-### `ocx system codex-app-server`
+[State-changing task](01_surface_integrations.md#ocx-integration-native)
 
-Codex app-server reachability and process state, as the dashboard sees it.
+### `ocx integration client`
 
-| Method | Route |
-|---|---|
-| GET | `/api/system/codex-app-server` |
+[State-changing task](01_surface_integrations.md#ocx-integration-client)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the app-server state as JSON. |
+### `ocx sync`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_lifecycle.md#ocx-sync)
 
-- The GUI reads this state directly; without a verb an agent could not tell whether the Codex app-server was reachable at all.
+### `ocx agent subagents force`
 
-### `ocx system codex-cli-update check`
+[State-changing task](01_surface_agents-routing.md#ocx-agent-subagents-force)
 
-Inspect a configured Codex CLI candidate and its ownership provenance.
+### `ocx agent request-user-input`
 
-Drives no management route.
+[State-changing task](01_surface_agents-routing.md#ocx-agent-request-user-input)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the redacted provenance report as JSON. |
+### `ocx agent roles`
 
-JSON mode: `envelope`.
+[State-changing task](01_surface_agents-routing.md#ocx-agent-roles)
 
-- Proof-bound published-launcher context authenticates the configured candidate snapshot, not successful Codex execution; this check does not attest or admit a selected runtime.
-- On Windows this first slice performs no candidate or configuration filesystem I/O: only a proof-captured absolute environment candidate can receive lexical app-bundle or version-manager labels; every other Windows candidate fails closed.
-- Makes no package-registry request.
-- Does not execute Codex or npm, install or repair software, control a process, or write configuration or cache state.
+### `ocx agent injection`
 
-### `ocx system codex-cli-update attest`
+[State-changing task](01_surface_agents-routing.md#ocx-agent-injection)
 
-Observe the selected or explicitly named Windows npm Codex installation files without enabling updates.
+### `ocx api protocols`
 
-Drives no management route.
+[Read-oriented task](01_surface_access-remote.md#ocx-api-protocols)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--candidate` | string | Absolute npm codex.cmd or package bin/codex.js path; all four paths are all-or-none. |
-| `--npm-prefix` | string | Absolute prefix containing node_modules/@openai/codex. |
-| `--npm-cli` | string | Absolute node_modules/npm/bin/npm-cli.js path. |
-| `--node` | string | Absolute node.exe path; observed, never executed. |
-| `--json` | boolean | Emit the path-free installation identity observation. |
+### `ocx combo test`
 
-JSON mode: `envelope`.
+[State-changing task](01_surface_agents-routing.md#ocx-combo-test)
 
-- Opt-in Windows x64 local-volume inspection using held native file handles; refuses reparse points, active writers and unsupported layouts.
-- Without explicit paths, the proof-bound launcher snapshot identifies the selected candidate: the configured CODEX_CLI_PATH or the first codex on the captured PATH, with an OpenCodex wrapper resolving to its codex.opencodex-real backing. Discovery only proposes paths; the held-handle observation remains the authority.
-- Success binds observed file identities and bytes, not selected-runtime admission or installer ownership.
-- selectionAttested, managed and applyAllowed remain false. The digest is an observation, not a durable update permit.
-- Does not run the named Codex/npm/Node files, query a registry, install software, control processes or persist state.
+### `ocx combo discover`
 
-### `ocx claude desktop status`
+[Read-oriented task](01_surface_agents-routing.md#ocx-combo-discover)
 
-Applied-vs-desired Claude Desktop state, including staleness, drift, and health.
+### `ocx api explain`
 
-| Method | Route |
-|---|---|
-| GET | `/api/claude-desktop/status` |
+[Read-oriented task](01_surface_access-remote.md#ocx-api-explain)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the live status as JSON. |
+### `ocx api policy`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_access-remote.md#ocx-api-policy)
 
-- Distinct from `claude desktop show`, which reports what this machine WOULD write; this reports what is actually in effect, which only the running proxy knows.
+### `ocx provider add`
 
-### `ocx claude desktop picker status`
+[State-changing task](01_surface_providers-models.md#ocx-provider-add)
 
-First-party picker mode: whether Claude Desktop's Code tab lists opencodex models, and what is missing if not.
+### `ocx provider show`
 
-| Method | Route |
-|---|---|
-| GET | `/api/claude-desktop/picker` |
+[Read-oriented task](01_surface_providers-models.md#ocx-provider-show)
 
-JSON mode: `none`.
+### `ocx provider remove`
 
-- Reports desired, effective, keychain trust, the Desktop egress profile, the model count and a reason with the next command to run.
+[State-changing task](01_surface_providers-models.md#ocx-provider-remove)
 
-### `ocx api protocols`
+### `ocx provider set-default`
 
-Read the protocol contract version, API surfaces, protocol settings and feature vocabulary.
+[State-changing task](01_surface_providers-models.md#ocx-provider-set-default)
 
-| Method | Route |
-|---|---|
-| GET | `/api/protocols` |
+### `ocx provider edit`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--provider` | string | Add one configured provider's upstream wire and who decided it. |
-| `--json` | boolean | Emit the GET /api/protocols body. |
+[State-changing task](01_surface_providers-models.md#ocx-provider-edit)
 
-JSON mode: `payload`.
+### `ocx provider test`
 
-### `ocx combo discover`
+[State-changing task](01_surface_providers-models.md#ocx-provider-test)
 
-List configured System One decision rows and catalog models that look like decision services.
+### `ocx provider quota`
 
-| Method | Route |
-|---|---|
-| GET | `/api/combos/decision-discovery` |
+[Read-oriented task](01_surface_providers-models.md#ocx-provider-quota)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--query` | string | Match catalog rows by this text instead of the built-in decision-model hint. |
-| `--json` | boolean | Emit the discovery payload. |
+### `ocx provider presets`
 
-JSON mode: `payload`.
+[Read-oriented task](01_surface_providers-models.md#ocx-provider-presets)
 
-- Read-only: nothing is probed and no provider row is created.
+### `ocx provider account-mode`
 
-### `ocx api explain`
+[State-changing task](01_surface_providers-models.md#ocx-provider-account-mode)
 
-Preview the request path a model would take from one inbound API, computed from config.
+### `ocx provider selected`
 
-| Method | Route |
-|---|---|
-| POST | `/api/protocols/plan` |
+[State-changing task](01_surface_providers-models.md#ocx-provider-selected)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--model` | string | Model selector as a client would send it. |
-| `--inbound` | string | Inbound API: responses, chat or messages. |
-| `--feature` | string | Request feature key to judge; repeatable or comma-separated. |
-| `--json` | boolean | Emit the ProtocolPlanV1 preview. |
+### `ocx models list`
 
-JSON mode: `payload`.
+[Read-oriented task](01_surface_providers-models.md#ocx-models-list)
 
-- A read-only POST: nothing is sent upstream, no combo state advances and the input is not logged.
+### `ocx models add`
 
-## State-changing capabilities
+[State-changing task](01_surface_providers-models.md#ocx-models-add)
 
-Each of these writes. Check the flags column before running one unattended.
+### `ocx models remove`
 
-### `ocx chatgpt`
+[State-changing task](01_surface_providers-models.md#ocx-models-remove)
 
-Experimental ChatGPT app-server shim: launch, restore or status (macOS only).
+### `ocx models list-custom`
 
-Drives no management route.
+[Read-oriented task](01_surface_providers-models.md#ocx-models-list-custom)
 
-JSON mode: `none`.
+### `ocx models live`
 
-- Default off; launch requires chatgptDesktop.appServerShim: true. Restore removes the generated launcher.
+[Read-oriented task](01_surface_providers-models.md#ocx-models-live)
 
-### `ocx link issue`
+### `ocx models edit`
 
-Issue one link credential and record its tunnel metadata.
+[State-changing task](01_surface_providers-models.md#ocx-models-edit)
 
-| Method | Route |
-|---|---|
-| POST | `/api/link/issue` |
+### `ocx models enable`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--alias` | string | SSH host alias for the linked machine. |
-| `--tunnel-port` | number | Remote loopback port for the reverse tunnel. |
-| `--json` | boolean | Emit the issue result as JSON. |
+[State-changing task](01_surface_providers-models.md#ocx-models-enable)
 
-JSON mode: `payload`.
+### `ocx models disable`
 
-- Requires the running proxy's admin token on loopback; the one-time data key is printed only on stdout.
+[State-changing task](01_surface_providers-models.md#ocx-models-disable)
 
-### `ocx link revoke`
+### `ocx models provider`
 
-Revoke a link credential and remove its link record.
+[State-changing task](01_surface_providers-models.md#ocx-models-provider)
 
-| Method | Route |
-|---|---|
-| DELETE | `/api/link/{id}` |
+### `ocx models selected`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--link-id` | string | Link id to revoke. |
-| `--json` | boolean | Emit the revoked link id as JSON. |
+[State-changing task](01_surface_providers-models.md#ocx-models-selected)
 
-JSON mode: `payload`.
+### `ocx models preset show`
 
-- Requires the running proxy's admin token on loopback.
+[Read-oriented task](01_surface_providers-models.md#ocx-models-preset-show)
 
-### `ocx remote-workspace pair`
+### `ocx models preset apply`
 
-Enroll this executor with one Hub using a one-time code from stdin and locally approved roots.
+[State-changing task](01_surface_providers-models.md#ocx-models-preset-apply)
 
-Drives no management route.
+### `ocx models new-policy`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the public local executor status. |
-| `--pairing-code-stdin` | boolean | Read the one-time pairing code from stdin. |
-| `--root` | string | Approve an absolute workspace directory; repeatable. |
-| `--toolchain-root` | string | Approve a read-only toolchain directory; repeatable. |
-| `--executor-helper` | string | Select a reviewed native helper file. |
-| `--name` | string | Name this executor. |
+[State-changing task](01_surface_providers-models.md#ocx-models-new-policy)
 
-JSON mode: `payload`.
+### `ocx models new-arrivals`
 
-- Executor-local operation; Hub consent and session control stay in the dashboard.
+[Read-oriented task](01_surface_providers-models.md#ocx-models-new-arrivals)
 
-### `ocx remote-workspace agent`
+### `ocx models context status`
 
-Keep the paired executor connected to its Hub.
+[Read-oriented task](01_surface_providers-models.md#ocx-models-context-status)
 
-Drives no management route.
+### `ocx models context value`
 
-JSON mode: `none`.
+[State-changing task](01_surface_providers-models.md#ocx-models-context-value)
 
-- Executor-local operation; Hub consent and session control stay in the dashboard.
+### `ocx models context provider`
 
-### `ocx models set-price`
+[State-changing task](01_surface_providers-models.md#ocx-models-context-provider)
 
-Save four manual USD-per-1M-token rates, or restore automatic pricing for one model.
+### `ocx models context all`
 
-| Method | Route |
-|---|---|
-| PUT | `/api/providers/{provider}/model-costs` |
+[State-changing task](01_surface_providers-models.md#ocx-models-context-all)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--input` | number | Input rate; required unless --auto is used. |
-| `--output` | number | Output rate; required unless --auto is used. |
-| `--cache-read` | number | Cache read rate; defaults to 0. |
-| `--cache-write` | number | Cache write rate; defaults to 0. |
-| `--auto` | boolean | Remove this model's override; cannot be combined with rates. |
-| `--json` | boolean | Emit the saved price or reset result as JSON. |
+### `ocx models shadow status`
 
-JSON mode: `payload`.
+[Read-oriented task](01_surface_providers-models.md#ocx-models-shadow-status)
 
-- Uses the exact upstream model ID after the first slash. Omitted cache rates default to zero; sibling model prices are preserved.
+### `ocx models shadow set`
 
-### `ocx models set`
+[State-changing task](01_surface_providers-models.md#ocx-models-shadow-set)
 
-Save per-model overrides for a routed model, or clear them back to the computed values.
+### `ocx alias list`
 
-| Method | Route |
-|---|---|
-| PUT | `/api/model-settings` |
+[Read-oriented task](01_surface_providers-models.md#ocx-alias-list)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--context-window` | string | Context window in tokens; 0 or - clears the override. |
-| `--modalities` | string | Comma-separated text,image,audio; - clears the override. |
-| `--reasoning-efforts` | string | Comma-separated ladder; "" for no reasoning, - to inherit. |
-| `--default-reasoning-effort` | string | Ladder member a request inherits when it omits one; - to inherit. |
-| `--reset` | boolean | Clear every override on this model; cannot be combined with the options above. |
-| `--json` | boolean | Emit the saved state as JSON. |
+### `ocx alias set`
 
-JSON mode: `envelope`.
+[State-changing task](01_surface_providers-models.md#ocx-alias-set)
 
-- Addresses a routed model as provider/model. The native openai lane and combos have no per-model overrides.
-- Unlike ocx models edit, which changes a custom model's own definition, this edits a row that already exists.
+### `ocx alias rm`
 
-### `ocx hub invite`
+[State-changing task](01_surface_providers-models.md#ocx-alias-rm)
 
-Mint a single-use pairing code on a hub and print the exact `ocx connect` line for one more machine.
+### `ocx alias defaults`
 
-Drives no management route.
+[State-changing task](01_surface_providers-models.md#ocx-alias-defaults)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit code, expiresAt, dataUrl, managementUrl, and command. |
-| `--data-url` | string | Advertise this data origin instead of hub.dataPublicOrigin or the bind address. |
-| `--management-url` | string | Confirm the management origin; it must equal hub.managementPublicOrigin. |
-| `--clients` | string | Pre-select codex and/or claude in the printed connect command. |
+### `ocx logout`
 
-JSON mode: `envelope`.
+[State-changing task](01_surface_accounts.md#ocx-logout)
 
-- Hub only: refuses when runtimeRole is not hub, and requires a running attested proxy.
-- The code is secret, single-use and short-lived; it is bound to hub.managementPublicOrigin and to the connecting machine's loopback browser origin.
-- The bound browser origin is always printed; when it is not http://localhost:10100 the warning names the port the connecting machine must use.
-- Refuses when the advertised data origin would be loopback (a loopback or wildcard bind with no hub.dataPublicOrigin and no --data-url) rather than printing a line that dials the other machine itself.
-- Prints no data-plane token. Remote machines receive their own revocable per-client key from the exchange.
-- Mints through the attested local pairing-grant route, the same one ocx gui pair uses; no admin token is read.
+### `ocx account current`
 
-### `ocx connect rotate`
+[Read-oriented task](01_surface_accounts.md#ocx-account-current)
 
-Rotate the connected client's data key against the hub, with commit and abort.
+### `ocx account use`
 
-| Method | Route |
-|---|---|
-| POST | `/api/keys/rotate` |
-| POST | `/api/keys/rotate/commit` |
-| DELETE | `/api/keys/rotate` |
+[State-changing task](01_surface_accounts.md#ocx-account-use)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--pairing-code-stdin` | boolean | Read a one-time pairing code from stdin as the rotation authority. |
-| `--admin-token-stdin` | boolean | Read the hub admin token from stdin as the rotation authority. |
-| `--json` | boolean | Emit the rotation result as JSON. |
+### `ocx account clear`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_accounts.md#ocx-account-clear)
 
-- Requires transient authority on stdin; the credential is never persisted or echoed.
-- A rotation left pending by a crash is resumed here — startup and status stop rather than guess which key generation is live.
+### `ocx account alias`
 
-### `ocx provider keychain`
+[State-changing task](01_surface_accounts.md#ocx-account-alias)
 
-Move a provider's API key into the OS keychain, restore it, or report where it lives.
+### `ocx account priority`
 
-| Method | Route |
-|---|---|
-| GET | `/api/providers/keychain` |
-| POST | `/api/providers/keychain` |
+[State-changing task](01_surface_accounts.md#ocx-account-priority)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the keychain status or result as JSON. |
+### `ocx account clear-cooldown`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_accounts.md#ocx-account-clear-cooldown)
 
-- `store` verifies every keychain write by read-back before config.json is rewritten with keychain: references; an unavailable keychain refuses with 503 and leaves the file untouched.
-- Headless services usually have no unlocked keychain session; prefer ${ENV_VAR} references there.
+### `ocx account remove`
 
-### `ocx companion`
+[State-changing task](01_surface_accounts.md#ocx-account-remove)
 
-Inspect and configure menu-bar and widget companion usage settings.
+### `ocx account add-key`
 
-| Method | Route |
-|---|---|
-| GET | `/api/companion/settings` |
-| GET | `/api/usage/timeline` |
-| PUT | `/api/companion/settings` |
+[State-changing task](01_surface_accounts.md#ocx-account-add-key)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit companion settings as JSON. |
+### `ocx account import`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_accounts.md#ocx-account-import)
 
-- `show` (the default) reads settings; `set key=value ...` updates selected settings; `reset` restores defaults.
-- Values accepted by `set` are parsed as JSON when valid, so booleans, numbers, arrays, objects, and null can be passed directly.
+### `ocx account reauth`
 
-### `ocx account login`
+[State-changing task](01_surface_accounts.md#ocx-account-reauth)
 
-Log in to an OAuth provider; Kiro can add a native device account.
+### `ocx account code`
 
-| Method | Route |
-|---|---|
-| POST | `/api/oauth/login` |
-| GET | `/api/oauth/status` |
+[State-changing task](01_surface_accounts.md#ocx-account-code)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--method` | string | For Kiro: builder-id, google, or github device login (add only). |
-| `--reauth` | boolean | Reauthenticate a selected existing account. |
-| `--id` | string | Account id for reauthentication. |
-| `--no-wait` | boolean | Return after the login flow starts. |
-| `--json` | boolean | Emit flow state as JSON. |
+### `ocx account cancel`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_accounts.md#ocx-account-cancel)
 
-### `ocx account main reauth`
+### `ocx account reset-credits`
 
-Reauthenticate the native main Codex login with a device code (#3898); headless hubs need no Codex App or keyring.
+[State-changing task](01_surface_accounts.md#ocx-account-reset-credits)
 
-| Method | Route |
-|---|---|
-| POST | `/api/codex-auth/main/reauth-device` |
-| GET | `/api/codex-auth/main/reauth-device` |
-| DELETE | `/api/codex-auth/main/reauth-device` |
+### `ocx account main doctor`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--device` | boolean | Run the device-code flow (the only reauth mode). |
-| `--no-wait` | boolean | Print the flow handle and code without waiting for completion. |
-| `--flow` | string | Flow id for status and cancel. |
-| `--json` | boolean | Emit the flow status as JSON. |
+[Read-oriented task](01_surface_accounts.md#ocx-account-main-doctor)
 
-JSON mode: `payload`.
+### `ocx account main list`
 
-- Same-identity reauth only: the device login must complete for the ChatGPT account that already holds the native main slot, and the commit is fenced by the exclusive claim plus a path/hash/inode snapshot.
-- /api/codex-auth/login stays pool-only and keeps rejecting __main__; this namespace is the only device-reauth surface for the native main slot.
-- Payloads carry only flowId, status, the verification URL, the device code, and a closed set of failure codes -- never tokens, emails, or raw account ids.
+[Read-oriented task](01_surface_accounts.md#ocx-account-main-list)
 
-### `ocx account import-orca`
+### `ocx account main register`
 
-Preview or register read-only links to Orca-managed Codex accounts without another login.
+[State-changing task](01_surface_accounts.md#ocx-account-main-register)
 
-Drives no management route.
+### `ocx account main add`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--source` | string | Orca data directory containing codex-accounts. |
-| `--registry` | string | The chosen Orca profile's orca-data.json account registry. |
-| `--apply` | boolean | Register new accounts; requires a stopped proxy. Default is preview. |
-| `--json` | boolean | Emit counts and fixed invalid-reason codes without credentials or source paths. |
+[State-changing task](01_surface_accounts.md#ocx-account-main-add)
 
-JSON mode: `envelope`.
+### `ocx account main reauth status`
 
-- Local files only; never copies refresh tokens or changes Orca authentication files.
-- Skips existing ChatGPT identities. New accounts remain pending until dashboard validation.
-- Orca must keep the source login available and refreshed; a missing or expired source fails closed.
-- Mixed eligible and invalid entries exit successfully; an all-invalid result exits nonzero.
+[Read-oriented task](01_surface_accounts.md#ocx-account-main-reauth-status)
 
-### `ocx account refresh`
+### `ocx account main reauth cancel`
 
-Refresh account quotas without model validation; pending Codex accounts require dashboard consent.
+[State-changing task](01_surface_accounts.md#ocx-account-main-reauth-cancel)
 
-| Method | Route |
-|---|---|
-| POST | `/api/codex-auth/accounts/refresh` |
-| GET | `/api/provider-quotas` |
+### `ocx account main switch`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the refresh result as JSON. |
+[State-changing task](01_surface_accounts.md#ocx-account-main-switch)
 
-JSON mode: `payload`.
+### `ocx account main recover`
 
-- CLI/admin-token refreshes only observe usage. After quota recovery, a human must click Refresh quotas in the dashboard to authorize model validation. Do not mint a GUI session to work around this consent boundary.
+[State-changing task](01_surface_accounts.md#ocx-account-main-recover)
 
-### `ocx account grok-reset-coupons`
+### `ocx agent status`
 
-Inspect or redeem Grok billing reset coupons; redemption is journaled and idempotent.
+[Read-oriented task](01_surface_agents-routing.md#ocx-agent-status)
 
-| Method | Route |
-|---|---|
-| GET | `/api/grok/reset-coupons` |
-| POST | `/api/grok/reset-coupons/consume` |
+### `ocx agent effort`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--consume` | boolean | Redeem one reset coupon; requires --yes. |
-| `--yes` | boolean | Explicit confirmation required by --consume. |
-| `--token-id` | string | Redeem a specific reset token instead of the default selection. |
-| `--operation-id` | string | UUIDv4 making a redemption idempotent: retries replay the journaled outcome. |
-| `--json` | boolean | Emit the coupon list or redemption result as JSON. |
+[Read-oriented task](01_surface_agents-routing.md#ocx-agent-effort)
 
-JSON mode: `payload`.
+### `ocx agent effort set`
 
-- Without --consume this is a read: remaining coupons and their validity windows.
-- The operation is journaled before the upstream call, so retrying the same --operation-id replays the recorded outcome instead of spending a second coupon.
+[State-changing task](01_surface_agents-routing.md#ocx-agent-effort-set)
 
-### `ocx account pause`
+### `ocx agent subagents`
 
-Exclude one account in a Codex, Anthropic or supported generic OAuth pool from automatic selection.
+[Read-oriented task](01_surface_agents-routing.md#ocx-agent-subagents)
 
-| Method | Route |
-|---|---|
-| PUT | `/api/codex-auth/accounts/pause` |
-| GET | `/api/oauth/accounts` |
-| PUT | `/api/oauth/accounts/pause` |
+### `ocx agent subagents set`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the pause result as JSON. |
+[State-changing task](01_surface_agents-routing.md#ocx-agent-subagents-set)
 
-JSON mode: `envelope`.
+### `ocx agent subagents clear`
 
-- Codex pause unbinds pinned threads and selects a fallback when possible; with no fallback, a paused-but-selected Codex account still receives requests. Anthropic and generic OAuth pause exclude the account from new requests, failover and refresh, and an all-paused pool answers 403. Credentials and health are preserved; already-sent turns are not cancelled.
+[State-changing task](01_surface_agents-routing.md#ocx-agent-subagents-clear)
 
-### `ocx account resume`
+### `ocx agent fallback`
 
-Return a paused account to a Codex, Anthropic or supported generic OAuth pool.
+[Read-oriented task](01_surface_agents-routing.md#ocx-agent-fallback)
 
-| Method | Route |
-|---|---|
-| PUT | `/api/codex-auth/accounts/pause` |
-| GET | `/api/oauth/accounts` |
-| PUT | `/api/oauth/accounts/pause` |
+### `ocx agent fallback set`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the resume result as JSON. |
+[State-changing task](01_surface_agents-routing.md#ocx-agent-fallback-set)
 
-JSON mode: `envelope`.
+### `ocx agent fallback clear`
 
-### `ocx account pause-exhausted`
+[State-changing task](01_surface_agents-routing.md#ocx-agent-fallback-clear)
 
-Pause every Codex account whose quota is spent.
+### `ocx agent sidecar`
 
-| Method | Route |
-|---|---|
-| PUT | `/api/codex-auth/accounts/pause-exhausted` |
+[Read-oriented task](01_surface_agents-routing.md#ocx-agent-sidecar)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit paused ids and the checked/failed counts as JSON. |
+### `ocx agent sidecar web`
 
-JSON mode: `envelope`.
+[State-changing task](01_surface_agents-routing.md#ocx-agent-sidecar-web)
 
-- The route refreshes quota per account and can partially fail; a non-zero failed count exits 1 and sets ok:false, because silence would read as `none were exhausted`.
+### `ocx agent sidecar vision`
 
-### `ocx account strategy`
+[State-changing task](01_surface_agents-routing.md#ocx-agent-sidecar-vision)
 
-Show or set how an account pool picks the next account.
+### `ocx effort`
 
-| Method | Route |
-|---|---|
-| GET | `/api/pool/settings` |
-| PUT | `/api/pool/settings` |
-| PATCH | `/api/pool/settings` |
+[State-changing task](01_surface_agents-routing.md#ocx-effort)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the applied strategy and sticky limit as JSON. |
+### `ocx effort set`
 
-JSON mode: `envelope`.
+[State-changing task](01_surface_agents-routing.md#ocx-effort-set)
 
-- A bare invocation reads and never writes.
-- The APPLIED value is echoed, not the requested one, so a server-side normalization stays visible.
-- Values are not re-validated in the CLI: the server owns the strategy names and the 1-100 sticky bound.
-- One route answers for every pool kind and declares which fields that kind honours in `supported`, so an unsupported field is a stated null rather than an absence. `anthropic` alone carries `quotaWindow`. Generic-provider settings steer selection only while `pool.kernel` is on. The legacy per-pool paths still work and are unchanged.
+### `ocx effort clear`
 
-### `ocx account sticky`
+[State-changing task](01_surface_agents-routing.md#ocx-effort-clear)
 
-Show or set how many consecutive requests stay on one account.
+### `ocx effort model`
 
-| Method | Route |
-|---|---|
-| GET | `/api/pool/settings` |
-| PUT | `/api/pool/settings` |
-| PATCH | `/api/pool/settings` |
+[Read-oriented task](01_surface_agents-routing.md#ocx-effort-model)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the applied strategy and sticky limit as JSON. |
+### `ocx v2 status`
 
-JSON mode: `envelope`.
+[Read-oriented task](01_surface_agents-routing.md#ocx-v2-status)
 
-- Only meaningful under the sticky-capable strategies; the pool strategy is the other half of this setting.
+### `ocx v2 on`
 
-### `ocx account routes`
+[State-changing task](01_surface_agents-routing.md#ocx-v2-on)
 
-Read, replace, or clear Anthropic OAuth model account routes.
+### `ocx v2 off`
 
-| Method | Route |
-|---|---|
-| GET | `/api/pool/settings` |
-| PUT | `/api/pool/settings` |
+[State-changing task](01_surface_agents-routing.md#ocx-v2-off)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--file` | string | Read a bounded JSON route array from a local file. |
-| `--clear` | boolean | Remove the stored routes. |
-| `--json` | boolean | Emit the unified settings response as JSON. |
+### `ocx v2 mode`
 
-JSON mode: `envelope`.
+[State-changing task](01_surface_agents-routing.md#ocx-v2-mode)
 
-- Only anthropic is supported. The server validates route names, patterns, and account IDs.
+### `ocx v2 keep-native-v1`
 
-### `ocx account auto-switch`
+[State-changing task](01_surface_agents-routing.md#ocx-v2-keep-native-v1)
 
-Show or set the usage percentage at which a pool moves to another account.
+### `ocx v2 threads`
 
-| Method | Route |
-|---|---|
-| GET | `/api/codex-auth/active` |
-| PUT | `/api/codex-auth/auto-switch` |
-| GET | `/api/oauth/accounts/pool` |
-| PUT | `/api/oauth/accounts/pool` |
-| GET | `/api/oauth/accounts` |
-| PUT | `/api/oauth/accounts/auto-switch` |
+[State-changing task](01_surface_agents-routing.md#ocx-v2-threads)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the stored threshold and whether it is applied. |
-| `--account` | string | Anthropic account ID; inherit restores the pool default, off stores zero. |
+### `ocx v2 mode-hint`
 
-JSON mode: `envelope`.
+[State-changing task](01_surface_agents-routing.md#ocx-v2-mode-hint)
 
-- A bare invocation reads and never writes.
-- `on` stores 80%, `off` stores 0%, and `threshold <n>` accepts 0-100.
-- Anthropic requires --account <id>; inherit sends null to restore its pool default. Manual/affinity precedence and pool-off recovery are unchanged.
-- For a generic OAuth pool, `inert: true` means the threshold is stored but not applied, `inert: false` means the pool is applying it, and an absent `inert` is an unknown capability.
+### `ocx combo list`
 
-### `ocx storage cleanup`
+[Read-oriented task](01_surface_agents-routing.md#ocx-combo-list)
 
-Preview or delete the oldest archived sessions by percentage.
+### `ocx combo show`
 
-| Method | Route |
-|---|---|
-| POST | `/api/storage/cleanup/preview` |
-| POST | `/api/storage/cleanup` |
+[Read-oriented task](01_surface_agents-routing.md#ocx-combo-show)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--percent` | number | Portion of the oldest archived sessions to target (0-100). |
-| `--mode` | string | quarantine (recoverable from trash) or permanent. |
-| `--yes` | boolean | Required to actually delete; without it this is a preview. |
-| `--json` | boolean | Emit the preview or result as JSON. |
+### `ocx combo set`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_agents-routing.md#ocx-combo-set)
 
-- Without `--yes` it prints what WOULD be freed and exits 0 having changed nothing.
-- There is no interactive confirmation: a prompt an agent can answer is not a safety boundary.
-- `--mode quarantine` moves files to trash, so `storage trash restore` can undo it; `permanent` cannot be undone.
+### `ocx combo remove`
 
-### `ocx storage trash`
+[State-changing task](01_surface_agents-routing.md#ocx-combo-remove)
 
-List quarantined cleanup batches, or restore one.
+### `ocx route policy list`
 
-| Method | Route |
-|---|---|
-| GET | `/api/storage/trash` |
-| POST | `/api/storage/trash/restore` |
+[Read-oriented task](01_surface_agents-routing.md#ocx-route-policy-list)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--yes` | boolean | Required for restore, which moves files and reconciles database rows. |
-| `--json` | boolean | Emit the trash list or restore result as JSON. |
+### `ocx route policy show`
 
-JSON mode: `payload`.
+[Read-oriented task](01_surface_agents-routing.md#ocx-route-policy-show)
 
-- Restore fails with a named 409 when the destination already exists, rather than overwriting it.
+### `ocx route policy dry-run`
 
-### `ocx storage policy`
+[State-changing task](01_surface_agents-routing.md#ocx-route-policy-dry-run)
 
-Show, change, or run the automatic archived-session cleanup policy.
+### `ocx route policy evaluate`
 
-| Method | Route |
-|---|---|
-| GET | `/api/storage/cleanup-policy` |
-| PUT | `/api/storage/cleanup-policy` |
-| POST | `/api/storage/cleanup-policy/run` |
+[State-changing task](01_surface_agents-routing.md#ocx-route-policy-evaluate)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--enabled` | string | true or false. |
-| `--percent` | number | Portion of oldest archived sessions each run targets. |
-| `--mode` | string | quarantine or permanent. |
-| `--schedule` | string | startup, daily, weekly, or manual. |
-| `--yes` | boolean | Required for `policy run`, which deletes immediately. |
-| `--json` | boolean | Emit the policy or run state as JSON. |
+### `ocx grok status`
 
-JSON mode: `payload`.
+[Read-oriented task](01_surface_integrations.md#ocx-grok-status)
 
-- `policy set` never enables implicitly: omitting `--enabled` keeps the stored value.
-- `policy run` forces a run regardless of schedule, so it needs `--yes`.
+### `ocx grok set`
 
-### `ocx system codex-restart`
+[State-changing task](01_surface_integrations.md#ocx-grok-set)
 
-Restart the Codex desktop app and app-servers.
+### `ocx grok exclude`
 
-| Method | Route |
-|---|---|
-| POST | `/api/system/codex-restart` |
+[State-changing task](01_surface_integrations.md#ocx-grok-exclude)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--yes` | boolean | Required: fully quits and relaunches the operator's Codex desktop app, which may discard unsaved composer drafts, model-picker selections, and pending approval prompts; also restarts its app-servers. |
-| `--json` | boolean | Emit the restart result as JSON. |
+### `ocx grok include`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_integrations.md#ocx-grok-include)
 
-- `sync --restart-codex` is not a substitute: it restarts only as a side effect after a catalog or cache write, so it cannot restart a healthy install on request.
-- Restarts the Codex desktop app as well as the app-servers, through the same module the CLI uses. When the proxy itself runs inside the Codex app it refuses instead, because restarting the app would kill the request.
-- --yes is mandatory because this interrupts a running editor session and may discard unsaved composer drafts, model-picker selections, and pending approval prompts; it must never happen because an agent guessed a subcommand.
+### `ocx grok clear`
 
-### `ocx claude config`
+[State-changing task](01_surface_integrations.md#ocx-grok-clear)
 
-Read or update Claude Code settings, including independent CLI first-party routing.
+### `ocx grok apply`
 
-| Method | Route |
-|---|---|
-| GET | `/api/claude-code` |
-| PUT | `/api/claude-code` |
+[State-changing task](01_surface_integrations.md#ocx-grok-apply)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--first-party` | string | For `set`, on or off; route standalone Claude CLI subscription requests through the intercept. |
-| `--json` | boolean | Emit the management response as JSON. |
+### `ocx integration client status`
 
-JSON mode: `payload`.
+[Read-oriented task](01_surface_integrations.md#ocx-integration-client-status)
 
-- `status` reads the route; `set` writes only submitted fields. Enabling first-party requires a running Claude intercept.
+### `ocx integration client history`
 
-### `ocx claude intercept start`
+[Read-oriented task](01_surface_integrations.md#ocx-integration-client-history)
 
-Start the local Claude interception pair on demand.
+### `ocx integration client enable`
 
-| Method | Route |
-|---|---|
-| POST | `/api/claude-intercept/start` |
+[State-changing task](01_surface_integrations.md#ocx-integration-client-enable)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the management response as JSON. |
+### `ocx integration client disable`
 
-JSON mode: `payload`.
+[State-changing task](01_surface_integrations.md#ocx-integration-client-disable)
 
-### `ocx claude desktop bind`
+### `ocx integration client restore`
 
-First-party: serve a Claude Desktop Code tab picker model with an opencodex route.
+[State-changing task](01_surface_integrations.md#ocx-integration-client-restore)
 
-| Method | Route |
-|---|---|
-| PUT | `/api/claude-desktop/first-party-bindings` |
+### `ocx claude config status`
 
-JSON mode: `none`.
+[Read-oriented task](01_surface_integrations.md#ocx-claude-config-status)
 
-- Takes a picker model id (claude-sonnet-4-6) and a route in the Desktop route vocabulary (provider/model or native/<slug>); the route must be one the Desktop profile can offer.
-- Only Claude Code traffic that reaches the proxy through the first-party intercept (Desktop's Code tab, the claude CLI) honours it; ocx claude and the public Messages endpoint are unaffected.
-- The Desktop picker keeps Anthropic's label; the binding changes which model answers, starting with the next request.
+### `ocx claude config set`
 
-### `ocx claude desktop unbind`
+[State-changing task](01_surface_integrations.md#ocx-claude-config-set)
 
-Remove a first-party Claude Desktop Code tab picker binding.
+### `ocx claude desktop show`
 
-| Method | Route |
-|---|---|
-| PUT | `/api/claude-desktop/first-party-bindings` |
+[Read-oriented task](01_surface_integrations.md#ocx-claude-desktop-show)
 
-JSON mode: `none`.
+### `ocx claude desktop move`
 
-- Removing an id that is not bound is a no-op; the remaining bindings are printed.
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-move)
 
-### `ocx claude desktop picker on`
+### `ocx claude desktop default`
 
-Turn first-party picker mode on and remember the choice.
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-default)
 
-| Method | Route |
-|---|---|
-| PUT | `/api/claude-desktop/picker` |
+### `ocx claude desktop export`
 
-JSON mode: `none`.
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-export)
 
-- Needs a running proxy, first-party mode and macOS. The first time, macOS asks to trust a local certificate authority limited to claude.ai; when the server cannot show that prompt the command runs the trust step in this terminal.
-- Claude Desktop then reaches the network through opencodex; fully quit and reopen Desktop afterwards.
+### `ocx claude desktop import`
 
-### `ocx claude desktop picker off`
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-import)
 
-Turn first-party picker mode off, remove its Desktop egress profile and certificate trust, and remember the choice.
+### `ocx claude desktop apply`
 
-| Method | Route |
-|---|---|
-| PUT | `/api/claude-desktop/picker` |
+[State-changing task](01_surface_integrations.md#ocx-claude-desktop-apply)
 
-JSON mode: `none`.
+### `ocx observe logs`
 
-- Works without a running proxy: the preference is saved and the picker profile and trust are removed locally.
+[Read-oriented task](01_surface_observe-system.md#ocx-observe-logs)
 
-### `ocx claude desktop picker trust`
+### `ocx logs explain`
 
-Run the macOS keychain step for picker mode in this terminal, then ask the server to finish enabling it.
+[Read-oriented task](01_surface_observe-system.md#ocx-logs-explain)
 
-| Method | Route |
-|---|---|
-| PUT | `/api/claude-desktop/picker` |
+### `ocx logs rebuild-index`
 
-JSON mode: `none`.
+[State-changing task](01_surface_observe-system.md#ocx-logs-rebuild-index)
 
-- The server removes trust this command added if the enable is refused; if the request is lost, trust is left alone and picker status tells what happened.
+### `ocx logs index-status`
 
-### `ocx integration native`
+[State-changing task](01_surface_observe-system.md#ocx-logs-index-status)
 
-Show or toggle the native Claude, Claude Desktop, Codex, and Grok integrations, and read the Cursor status (which builds are installed, gateway values, last request seen) and, on request, the Private Inference installer Cursor's update channel advertises.
+### `ocx observe usage`
 
-| Method | Route |
-|---|---|
-| GET | `/api/native-integrations` |
-| PUT | `/api/native-integrations/claude` |
-| PUT | `/api/native-integrations/claude-desktop` |
-| PUT | `/api/native-integrations/codex` |
-| PUT | `/api/native-integrations/grok` |
-| GET | `/api/native-integrations/cursor` |
-| GET | `/api/native-integrations/cursor/local-installer` |
+[Read-oriented task](01_surface_observe-system.md#ocx-observe-usage)
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the client rows or toggle result as JSON. |
+### `ocx observe storage`
 
-JSON mode: `payload`.
+[Read-oriented task](01_surface_observe-system.md#ocx-observe-storage)
 
-- The list renders per-client state, installed, and desired columns; a blocked disable is named rather than left silent.
-- Each client has its own route because a toggle rewrites that client's own config file.
+### `ocx observe memory`
 
-### `ocx integration client`
+[Read-oriented task](01_surface_observe-system.md#ocx-observe-memory)
 
-Inspect and toggle Aside profile catalogs, read their history, and restore a selected profile operation.
+### `ocx observe debug`
 
-| Method | Route |
-|---|---|
-| GET | `/api/client-integrations/aside/profiles` |
-| PUT | `/api/client-integrations/aside/profiles` |
-| GET | `/api/client-integrations/aside/profiles/{profileId}` |
-| PUT | `/api/client-integrations/aside/profiles/{profileId}` |
-| GET | `/api/client-integrations/aside/profiles/journal` |
-| GET | `/api/client-integrations/aside/profiles/{profileId}/journal` |
-| POST | `/api/client-integrations/aside/profiles/{profileId}/restore` |
-
-| Flag | Value | Meaning |
-|---|---|---|
-| `--client` | string | Select the file integration; use aside for profile controls. |
-| `--profile` | number | Select one registered Aside account; omitted toggles affect all profiles. |
-| `--op` | string | Operation ID for restore. |
-| `--confirm-drift` | boolean | Explicitly allow restore to replace subsequent edits. |
-| `--overwrite-conflict` | boolean | Explicitly allow enable to replace a conflicting provider block. |
-| `--json` | boolean | Emit the profile state, history, or mutation result as JSON. |
-
-JSON mode: `payload`.
-
-- Use status/show/list, history/journal, enable/disable, or restore after integration client.
-- These declarations cover the dedicated Aside profile paths; existing generic client routes retain their separate parity inventory.
+[Read-oriented task](01_surface_observe-system.md#ocx-observe-debug)
 
-### `ocx sync`
+### `ocx observe claude-inbound`
 
-Synchronize client catalogs, including Aside profiles through the running server's mutation owner.
+[Read-oriented task](01_surface_observe-system.md#ocx-observe-claude-inbound)
 
-| Method | Route |
-|---|---|
-| POST | `/api/client-integrations/aside/sync` |
+### `ocx observe injection`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--restart-codex` | boolean | Restart the Codex app-servers and fully quit and relaunch the Codex desktop app after a catalog or cache write, on macOS, Linux and Windows. |
-| `--restart-app-server-only` | boolean | Restart only the Codex app-servers and leave the desktop app running; wins over --restart-codex when both are given. |
-| `--restart-desktop-app` | boolean | Deprecated alias of --restart-codex. |
+[Read-oriented task](01_surface_observe-system.md#ocx-observe-injection)
 
-JSON mode: `none`.
+### `ocx memory`
 
-- The Aside refresh uses the live server; other catalog synchronization also performs local work.
+[Read-oriented task](01_surface_agents-routing.md#ocx-memory)
 
-### `ocx agent subagents force`
+### `ocx storage codex-logs status`
 
-Force Claude Code subagents onto one exposed model at the next routed launch; - clears.
+[Read-oriented task](01_surface_observe-system.md#ocx-storage-codex-logs-status)
 
-| Method | Route |
-|---|---|
-| GET | `/api/subagent-models` |
-| PUT | `/api/subagent-models` |
+### `ocx storage codex-logs protect`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the saved force setting. |
+[State-changing task](01_surface_observe-system.md#ocx-storage-codex-logs-protect)
 
-JSON mode: `payload`.
+### `ocx storage codex-logs unprotect`
 
-- Requires Claude Code 2.1.257+. Plain claude, forks, inherit skills, the main model and small-fast sidecars are unaffected.
+[State-changing task](01_surface_observe-system.md#ocx-storage-codex-logs-unprotect)
 
-### `ocx agent request-user-input`
+### `ocx storage codex-logs repair`
 
-Show or set whether default mode may ask the operator a question mid-task.
+[State-changing task](01_surface_observe-system.md#ocx-storage-codex-logs-repair)
 
-| Method | Route |
-|---|---|
-| GET | `/api/codex-auth/features/default-mode-request-user-input` |
-| PUT | `/api/codex-auth/features/default-mode-request-user-input` |
+### `ocx storage codex-logs compact`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the feature state as JSON. |
+[State-changing task](01_surface_observe-system.md#ocx-storage-codex-logs-compact)
 
-JSON mode: `payload`.
+### `ocx storage trash list`
 
-- A bare invocation reads and never writes.
+[Read-oriented task](01_surface_observe-system.md#ocx-storage-trash-list)
 
-### `ocx agent roles`
+### `ocx storage policy show`
 
-omo (Codex / LazyCodex): show each Codex agent role's model pin, set one role's model in its TOML and in omo.jsonc, or suggest a model for every role.
+[Read-oriented task](01_surface_observe-system.md#ocx-storage-policy-show)
 
-| Method | Route |
-|---|---|
-| GET | `/api/codex-agent-roles` |
-| PUT | `/api/codex-agent-roles/{role}` |
-| POST | `/api/codex-agent-roles/auto-assign` |
+### `ocx storage trash restore`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the role list, the write result or the proposals as JSON. |
-| `--model` | string | suggest: size the roles with this model instead of the Codex default model. |
-| `--apply` | boolean | suggest: write every proposal through the role model write. |
+[State-changing task](01_surface_observe-system.md#ocx-storage-trash-restore)
 
-JSON mode: `payload`.
+### `ocx storage policy set`
 
-- A bare invocation reads and never writes.
-- Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.
-- set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml; omo.jsonc is skipped when absent or when it contains comments.
-- suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort.
+[State-changing task](01_surface_observe-system.md#ocx-storage-policy-set)
 
-### `ocx agent injection`
+### `ocx storage policy run`
 
-Show or set the delegation model and effort, or suggest both for a described piece of delegated work.
+[State-changing task](01_surface_observe-system.md#ocx-storage-policy-run)
 
-| Method | Route |
-|---|---|
-| GET | `/api/injection-model` |
-| PUT | `/api/injection-model` |
-| POST | `/api/injection-model/suggest` |
+### `ocx debug provider`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--json` | boolean | Emit the delegation settings, the write result or the proposal as JSON. |
-| `--model` | string | set: the delegation model, - clears it. suggest: size the work with this model instead of the Codex default model. |
-| `--effort` | string | set: the delegation reasoning effort, - clears it. |
-| `--prompt` | string | set: a custom guidance prompt, - clears it. |
-| `--guidance` | string | set: on or off for OpenCodex delegation guidance. |
-| `--apply` | boolean | suggest: write the proposed model and effort through the delegation settings write. |
+[State-changing task](01_surface_observe-system.md#ocx-debug-provider)
 
-JSON mode: `payload`.
+### `ocx debug provider status`
 
-- A bare invocation reads and never writes.
-- suggest sizes the described work with one model call, picks the cheapest sufficient model the delegation picker offers, and writes nothing unless --apply is given.
+[Read-oriented task](01_surface_observe-system.md#ocx-debug-provider-status)
 
-### `ocx combo test`
+### `ocx debug provider on`
 
-Run one JEV decision probe through a decision method: TypeSafe, a System One row, or an opencodex model.
+[State-changing task](01_surface_observe-system.md#ocx-debug-provider-on)
 
-| Method | Route |
-|---|---|
-| POST | `/api/combos/decision-test` |
+### `ocx debug provider off`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--combo` | string | Combo id whose saved decision method is probed and whose recursion rules apply. |
-| `--decision-provider` | string | Probe a jev-decision provider row (or jev for TypeSafe) instead of the saved method. |
-| `--decision-model` | string | Probe an opencodex-routed model instead of the saved method. |
-| `--decision-timeout` | number | Decision deadline in milliseconds (1000-120000). |
-| `--json` | boolean | Emit the probe result. |
+[State-changing task](01_surface_observe-system.md#ocx-debug-provider-off)
 
-JSON mode: `payload`.
+### `ocx debug provider reset`
 
-- Sends one synthetic two-option decision; it may spend a decision call on the chosen backend.
+[State-changing task](01_surface_observe-system.md#ocx-debug-provider-reset)
 
-### `ocx api policy`
+### `ocx debug provider logs`
 
-Read the protocol policy, or change the Messages surface, unrepresentable policy and rollout switches.
+[Read-oriented task](01_surface_observe-system.md#ocx-debug-provider-logs)
 
-| Method | Route |
-|---|---|
-| GET | `/api/protocols` |
-| PATCH | `/api/protocols/settings` |
+### `ocx debug usage`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-usage)
+
+### `ocx debug usage status`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-debug-usage-status)
+
+### `ocx debug usage on`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-usage-on)
+
+### `ocx debug usage off`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-usage-off)
+
+### `ocx debug usage reset`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-usage-reset)
+
+### `ocx debug usage logs`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-debug-usage-logs)
+
+### `ocx debug injection`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-injection)
+
+### `ocx debug injection status`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-debug-injection-status)
+
+### `ocx debug injection on`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-injection-on)
+
+### `ocx debug injection off`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-injection-off)
+
+### `ocx debug injection reset`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-injection-reset)
+
+### `ocx debug claude`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-claude)
+
+### `ocx debug claude status`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-debug-claude-status)
+
+### `ocx debug claude on`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-claude-on)
+
+### `ocx debug claude off`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-claude-off)
+
+### `ocx debug claude reset`
+
+[State-changing task](01_surface_observe-system.md#ocx-debug-claude-reset)
+
+### `ocx system status`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-system-status)
+
+### `ocx system settings`
+
+[State-changing task](01_surface_observe-system.md#ocx-system-settings)
+
+### `ocx system startup health`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-system-startup-health)
+
+### `ocx system startup install-service`
+
+[State-changing task](01_surface_observe-system.md#ocx-system-startup-install-service)
+
+### `ocx system startup install-shim`
+
+[State-changing task](01_surface_observe-system.md#ocx-system-startup-install-shim)
+
+### `ocx system diagnostics`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-system-diagnostics)
+
+### `ocx system sync`
+
+[State-changing task](01_surface_observe-system.md#ocx-system-sync)
+
+### `ocx system update check`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-system-update-check)
+
+### `ocx system update run`
+
+[State-changing task](01_surface_observe-system.md#ocx-system-update-run)
+
+### `ocx system update status`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-system-update-status)
+
+### `ocx config show`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-config-show)
+
+### `ocx config get`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-config-get)
+
+### `ocx config set`
+
+[State-changing task](01_surface_observe-system.md#ocx-config-set)
+
+### `ocx config unset`
+
+[State-changing task](01_surface_observe-system.md#ocx-config-unset)
+
+### `ocx config validate`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-config-validate)
+
+### ocx config export
+
+[State-changing task](01_surface_observe-system.md#ocx-config-export)
+
+### `ocx config import`
+
+[State-changing task](01_surface_observe-system.md#ocx-config-import)
+
+### `ocx companion show`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-companion-show)
+
+### `ocx companion set`
+
+[State-changing task](01_surface_observe-system.md#ocx-companion-set)
+
+### `ocx companion reset`
+
+[State-changing task](01_surface_observe-system.md#ocx-companion-reset)
+
+### `ocx service install`
+
+[State-changing task](01_surface_lifecycle.md#ocx-service-install)
+
+### `ocx service repair`
+
+[State-changing task](01_surface_lifecycle.md#ocx-service-repair)
+
+### `ocx service restart`
+
+[State-changing task](01_surface_lifecycle.md#ocx-service-restart)
+
+### `ocx service start`
+
+[State-changing task](01_surface_lifecycle.md#ocx-service-start)
+
+### `ocx service stop`
+
+[State-changing task](01_surface_lifecycle.md#ocx-service-stop)
+
+### `ocx service status`
+
+[Read-oriented task](01_surface_lifecycle.md#ocx-service-status)
+
+### `ocx service uninstall`
+
+[State-changing task](01_surface_lifecycle.md#ocx-service-uninstall)
+
+### `ocx codex-shim install`
+
+[State-changing task](01_surface_integrations.md#ocx-codex-shim-install)
+
+### `ocx codex-shim status`
+
+[Read-oriented task](01_surface_integrations.md#ocx-codex-shim-status)
+
+### `ocx codex-shim uninstall`
+
+[State-changing task](01_surface_integrations.md#ocx-codex-shim-uninstall)
+
+### `ocx tray install`
+
+[State-changing task](01_surface_observe-system.md#ocx-tray-install)
+
+### `ocx tray start`
+
+[State-changing task](01_surface_observe-system.md#ocx-tray-start)
+
+### `ocx tray stop`
+
+[State-changing task](01_surface_observe-system.md#ocx-tray-stop)
+
+### `ocx tray status`
+
+[Read-oriented task](01_surface_observe-system.md#ocx-tray-status)
+
+### `ocx tray uninstall`
+
+[State-changing task](01_surface_observe-system.md#ocx-tray-uninstall)
+
+### `ocx access key`
+
+[State-changing task](01_surface_access-remote.md#ocx-access-key)
+
+### `ocx access key list`
+
+[Read-oriented task](01_surface_access-remote.md#ocx-access-key-list)
+
+### `ocx access key get`
+
+[Read-oriented task](01_surface_access-remote.md#ocx-access-key-get)
+
+### `ocx access key set`
+
+[State-changing task](01_surface_access-remote.md#ocx-access-key-set)
+
+### `ocx access key rotate commit`
+
+[State-changing task](01_surface_access-remote.md#ocx-access-key-rotate-commit)
+
+### `ocx access key rotate abort`
+
+[State-changing task](01_surface_access-remote.md#ocx-access-key-rotate-abort)
+
+### `ocx access key remove`
+
+[State-changing task](01_surface_access-remote.md#ocx-access-key-remove)
+
+### `ocx access endpoints`
+
+[Read-oriented task](01_surface_access-remote.md#ocx-access-endpoints)
+
+### `ocx access models`
+
+[Read-oriented task](01_surface_access-remote.md#ocx-access-models)
+
+### `ocx access test`
+
+[State-changing task](01_surface_access-remote.md#ocx-access-test)
+
+### `ocx lab status`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-status)
+
+### `ocx lab verdicts`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-verdicts)
+
+### `ocx lab subjects`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-subjects)
+
+### `ocx lab observations`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-observations)
+
+### `ocx lab events`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-events)
+
+### `ocx lab artifacts`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-artifacts)
+
+### `ocx lab catalog`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-catalog)
+
+### `ocx lab subject`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-subject)
+
+### `ocx lab event`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-event)
+
+### `ocx lab artifact`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-artifact)
+
+### `ocx lab production-signals`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-production-signals)
+
+### `ocx lab public preview`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-public-preview)
+
+### `ocx lab public export`
+
+[State-changing task](01_surface_lab.md#ocx-lab-public-export)
+
+### `ocx lab public verify`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-public-verify)
+
+### `ocx lab public import`
+
+[State-changing task](01_surface_lab.md#ocx-lab-public-import)
+
+### `ocx lab public community`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-public-community)
+
+### `ocx lab automation status`
+
+[Read-oriented task](01_surface_lab.md#ocx-lab-automation-status)
+
+### `ocx lab automation enable`
+
+[State-changing task](01_surface_lab.md#ocx-lab-automation-enable)
+
+### `ocx lab automation disable`
+
+[State-changing task](01_surface_lab.md#ocx-lab-automation-disable)
+
+### `ocx lab automation runs`
 
-| Flag | Value | Meaning |
-|---|---|---|
-| `--messages` | string | Open or close the Messages API: on or off. Off also turns the Claude integration off. |
-| `--unrepresentable` | string | legacy keeps today's behavior; reject refuses a request its path cannot carry. |
-| `--rollout` | string | One switch as name=on or name=off; repeatable. Every switch defaults off. |
-| `--json` | boolean | Emit the resulting GET /api/protocols body. |
+[Read-oriented task](01_surface_lab.md#ocx-lab-automation-runs)
 
-JSON mode: `payload`.
+### `ocx lab run`
 
-- A bare invocation reads and never writes.
-- A setting flag changes the operator's config; run it only when the operator asks for that change.
+[State-changing task](01_surface_lab.md#ocx-lab-run)
 
 ## Counts
 
-- declared capabilities: 74
-- of those, state-changing: 43
+- declared capabilities: 289
+- of those, state-changing: 177
 - head-resolved invocations: 2
diff --git a/skills/ocx/references/01_surface_access-remote.md b/skills/ocx/references/01_surface_access-remote.md
new file mode 100644
index 00000000000..0bf25ecf04a
--- /dev/null
+++ b/skills/ocx/references/01_surface_access-remote.md
@@ -0,0 +1,479 @@
+<!-- GENERATED by scripts/generate-ocx-skill-surface.ts. Do not edit by hand. -->
+<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->
+
+# access-remote: declared management tasks
+
+[Management index](01_management_surface.md) · [Operating rules](../SKILL.md#secret-bearing-commands)
+
+Use these declarations to choose a task, then check its flags and authority before execution.
+Non-mutating probes may still contact providers, consume quota or refresh caches.
+
+Declared capabilities: 22.
+
+### `ocx link port`
+
+Usage: `ocx link port [--json]`
+
+Allocate a free loopback port for a remote home link.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the selected port as JSON. |
+
+JSON mode: `envelope`.
+
+- Local temporary loopback socket allocation; no management API request.
+- Always emits a CLI-shaped {port} JSON object, even without --json.
+
+### ocx link issue
+
+Human-only handoff: ask the operator to perform this in their own terminal or dashboard; do not capture the secret-bearing result.
+
+Issue one link credential and record its tunnel metadata.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/link/issue` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--alias` | string | SSH host alias for the linked machine. |
+| `--tunnel-port` | number | Remote loopback port for the reverse tunnel. |
+| `--json` | boolean | Emit the issue result as JSON. |
+
+JSON mode: `payload`.
+
+- Human-only handoff: issues a credential and prints its plaintext once. Never capture it in an agent transcript. Requires loopback admin authority; tunnel port must be 1024-65535.
+
+### `ocx link status`
+
+Usage: `ocx link status [--json]`
+
+Read link listener and tunnel status.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/link/status` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the K16 status payload as JSON. |
+
+JSON mode: `payload`.
+
+- Reads live listener/tunnel metadata; when no proxy is found, falls back to the local link store. Always emits JSON.
+
+### `ocx link revoke`
+
+Usage: `ocx link revoke --link-id <id> [--json]`
+
+Revoke a link credential and remove its link record.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| DELETE | `/api/link/{id}` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--link-id` | string | Link id to revoke. |
+| `--json` | boolean | Emit the revoked link id as JSON. |
+
+JSON mode: `envelope`.
+
+- Requires a valid link ID and loopback admin authority. No force-removal option exists.
+- Always emits a CLI-shaped {linkId} JSON object. Already-revoked link_not_found is idempotent success.
+
+### `ocx remote-workspace pair`
+
+Usage: `ocx remote-workspace pair <hub-url> --pairing-code-stdin --root <absolute-path> [--root <absolute-path> ...] [--toolchain-root <absolute-directory> ...] [--executor-helper <absolute-file>] [--name <device-name>] [--json]`
+
+Enroll this executor with one Hub using a one-time code from stdin and locally approved roots.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the public local executor status. |
+| `--pairing-code-stdin` | boolean | Read the one-time pairing code from stdin. |
+| `--root` | string | Approve an absolute workspace directory; repeatable. |
+| `--toolchain-root` | string | Approve a read-only toolchain directory; repeatable. |
+| `--executor-helper` | string | Select a reviewed native helper file. |
+| `--name` | string | Name this executor. |
+
+JSON mode: `payload`.
+
+- Executor-local state/control; no Hub management API routes.
+- Pairing consumes a human-provided one-time code from stdin and persists enrollment; approved roots and platform confinement determine capabilities.
+
+### `ocx remote-workspace agent`
+
+Usage: `ocx remote-workspace agent`
+
+Keep the paired executor connected to its Hub.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Executor-local state/control; no Hub management API routes.
+- Maintains the enrolled executor connection to the Hub until interrupted.
+
+### `ocx remote-workspace status`
+
+Usage: `ocx remote-workspace status [--json]`
+
+Read local executor enrollment and available capabilities without printing credentials.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the public local executor status. |
+
+JSON mode: `payload`.
+
+- Executor-local state/control; no Hub management API routes.
+- Reports local enrollment and platform/helper capabilities without credentials; not Hub device/runtime/session inventory.
+
+### ocx hub invite
+
+Human-only handoff: ask the operator to perform this in their own terminal or dashboard; do not capture the secret-bearing result.
+
+Mint a single-use pairing code on a hub and print the exact `ocx connect` line for one more machine.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit code, expiresAt, dataUrl, managementUrl, and command. |
+| `--data-url` | string | Advertise this data origin instead of hub.dataPublicOrigin or the bind address. |
+| `--management-url` | string | Confirm the management origin; it must equal hub.managementPublicOrigin. |
+| `--clients` | string | Pre-select codex and/or claude in the printed connect command. |
+
+JSON mode: `envelope`.
+
+- Hub only: refuses when runtimeRole is not hub, and requires a running attested proxy.
+- The code is secret, single-use and short-lived; it is bound to hub.managementPublicOrigin and to the connecting machine's loopback browser origin.
+- The bound browser origin is always printed; when it is not http://localhost:10100 the warning names the port the connecting machine must use.
+- Refuses when the advertised data origin would be loopback (a loopback or wildcard bind with no hub.dataPublicOrigin and no --data-url) rather than printing a line that dials the other machine itself.
+- Prints no data-plane token. Remote machines receive their own revocable per-client key from the exchange.
+- Mints through the attested local pairing-grant route, the same one ocx gui pair uses; no admin token is read.
+
+### `ocx connect rotate`
+
+Rotate the connected client's data key against the hub, with commit and abort.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/keys/rotate` |
+| POST | `/api/keys/rotate/commit` |
+| DELETE | `/api/keys/rotate` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--pairing-code-stdin` | boolean | Read a one-time pairing code from stdin as the rotation authority. |
+| `--admin-token-stdin` | boolean | Read the hub admin token from stdin as the rotation authority. |
+| `--json` | boolean | Emit the rotation result as JSON. |
+
+JSON mode: `payload`.
+
+- Requires transient authority on stdin; the credential is never persisted or echoed.
+- A rotation left pending by a crash is resumed here — startup and status stop rather than guess which key generation is live.
+
+### `ocx api protocols`
+
+Usage: `ocx api protocols [--provider <name>] [--json]`
+
+Read the protocol contract version, API surfaces, protocol settings and feature vocabulary.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/protocols` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--provider` | string | Add one configured provider's upstream wire and who decided it. |
+| `--json` | boolean | Emit the GET /api/protocols body. |
+
+JSON mode: `payload`.
+
+### `ocx api explain`
+
+Usage: `ocx api explain --model <id> --inbound <responses|chat|messages> [--feature <key>[,<key>]]... [--json]`
+
+Preview the request path a model would take from one inbound API, computed from config.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| POST | `/api/protocols/plan` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--model` | string | Model selector as a client would send it. |
+| `--inbound` | string | Inbound API: responses, chat or messages. |
+| `--feature` | string | Request feature key to judge; repeatable or comma-separated. |
+| `--json` | boolean | Emit the ProtocolPlanV1 preview. |
+
+JSON mode: `payload`.
+
+- A read-only POST: nothing is sent upstream, no combo state advances and the input is not logged.
+
+### `ocx api policy`
+
+Usage: `ocx api policy [--messages <on|off>] [--unrepresentable <legacy|reject>] [--rollout <switch>=<on|off>]... [--json]`
+
+Read the protocol policy, or change the Messages surface, unrepresentable policy and rollout switches.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/protocols` |
+| PATCH | `/api/protocols/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--messages` | string | Open or close the Messages API: on or off. Off also turns the Claude integration off. |
+| `--unrepresentable` | string | legacy keeps today's behavior; reject refuses a request its path cannot carry. |
+| `--rollout` | string | One switch as name=on or name=off; repeatable. Every switch defaults off. |
+| `--json` | boolean | Emit the resulting GET /api/protocols body. |
+
+JSON mode: `payload`.
+
+- A bare invocation reads and never writes.
+- A setting flag changes the operator's config; run it only when the operator asks for that change.
+
+### `ocx access key`
+
+Usage: `ocx access key list [--json]`
+
+Manage API access keys and inspect masked metadata.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/keys` |
+| POST | `/api/keys` |
+| PATCH | `/api/keys` |
+| DELETE | `/api/keys` |
+| POST | `/api/keys/rotate` |
+| POST | `/api/keys/rotate/commit` |
+| DELETE | `/api/keys/rotate` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Mixed family: list/get read masked metadata; scope edits, revocation and rotation change authorization.
+- Creation and rotation initiation return plaintext secrets once and are human-only handoffs. Ask the operator to perform them in their terminal or dashboard; never capture the returned credential.
+- Use the separately documented safe follow-up leaves. keys and top-level api-key are aliases.
+
+### `ocx access key list`
+
+Usage: `ocx access key list [--json]`
+
+List masked access keys, usage, endpoints and pending rotations.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/keys` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- No plaintext secret is returned by the list route.
+
+### `ocx access key get`
+
+Usage: `ocx access key get <id-or-name> [--json]`
+
+Read one masked key and its access scope.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/keys` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Case-insensitive ID takes precedence over name; ambiguous names are refused.
+
+### `ocx access key set`
+
+Usage: `ocx access key set <id-or-name> [--allow-provider <name>]... [--allow-model <id>]... [--clear] [--json]`
+
+Replace selected provider/model scope dimensions.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/keys` |
+| PATCH | `/api/keys` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--allow-provider` | string | Provider scope; repeatable, replaces that dimension. |
+| `--allow-model` | string | Model scope; repeatable, replaces that dimension. |
+| `--clear` | boolean | Clear both dimensions; submitted allow options then override their dimension. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- At least one scope option is required. Unspecified dimensions are preserved; this command does not rename keys.
+
+### `ocx access key rotate commit`
+
+Usage: `ocx access key rotate commit <id> <rotation-id> [--json]`
+
+Commit a pending key rotation.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/keys/rotate/commit` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Use IDs from the human-authorized rotation. Commit only after the client accepts the replacement; the old credential is retired.
+
+### `ocx access key rotate abort`
+
+Usage: `ocx access key rotate abort <id> <rotation-id> [--json]`
+
+Abort a pending key rotation.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| DELETE | `/api/keys/rotate` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Use IDs from the human-authorized rotation. Abort discards the pending replacement credential.
+
+### `ocx access key remove`
+
+Usage: `ocx access key remove <id> --yes [--json]`
+
+Revoke one API access key.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| DELETE | `/api/keys` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Required confirmation before revoking the key. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Uses the exact ID, not name resolution; delete is an alias.
+
+### `ocx access endpoints`
+
+Usage: `ocx access endpoints [--json]`
+
+Read endpoint URLs from the access-key metadata.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/keys` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Projects only baseUrl, endpoint and fields ending in Endpoint; use key list for the full metadata payload.
+
+### `ocx access models`
+
+Usage: `ocx access models [--json]`
+
+Read the public external-model catalog.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Data-plane GET /v1/models via the runtime client; differs from management models live. The routes field indexes management API routes only.
+
+### `ocx access test`
+
+Usage: `ocx access test <model> [--protocol <chat|responses|messages>] [--json]`
+
+Send a small inference request through the selected protocol.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--protocol` | string | chat \| responses \| messages; default chat. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Data-plane POST /v1/chat/completions, /v1/responses or /v1/messages according to --protocol; these are not management API routes. May spend upstream quota; run only for an explicitly authorized inference probe.
+- Uses runtime management headers and has no chosen-key input; success is not validation of a newly created data key.
diff --git a/skills/ocx/references/01_surface_accounts.md b/skills/ocx/references/01_surface_accounts.md
new file mode 100644
index 00000000000..523acf11bad
--- /dev/null
+++ b/skills/ocx/references/01_surface_accounts.md
@@ -0,0 +1,832 @@
+<!-- GENERATED by scripts/generate-ocx-skill-surface.ts. Do not edit by hand. -->
+<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->
+
+# accounts: declared management tasks
+
+[Management index](01_management_surface.md) · [Operating rules](../SKILL.md#secret-bearing-commands)
+
+Use these declarations to choose a task, then check its flags and authority before execution.
+Non-mutating probes may still contact providers, consume quota or refresh caches.
+
+Declared capabilities: 36.
+
+### `ocx account login`
+
+Usage: `ocx account login <provider> [--id <account-id>] [--reauth] [--device] [--method <builder-id|google|github>] [--code -] [--no-wait] [--json]`
+
+Log in to an OAuth provider; Kiro can add a native device account.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/oauth/login` |
+| GET | `/api/oauth/status` |
+| POST | `/api/oauth/login/code` |
+| POST | `/api/codex-auth/login` |
+| GET | `/api/codex-auth/login-status` |
+| POST | `/api/codex-auth/login/code` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--id` | string | Account ID; provider OAuth requires --reauth when supplied. |
+| `--reauth` | boolean | Reauthenticate an existing account. |
+| `--device` | boolean | Codex device flow; accepted for already-device-native kimi, nous and github-copilot. |
+| `--method` | string | Kiro only: builder-id, google or github; add-only and incompatible with --reauth, --id, --device or --code. |
+| `--code` | string | Use - to read authorization material from stdin. |
+| `--no-wait` | boolean | Return after flow start. |
+| `--json` | boolean | Emit the command result as JSON. |
+
+JSON mode: `payload`.
+
+- openai, codex and chatgpt address the Codex pool. Native main uses the separate account main reauth flow.
+- Login is a human authorization handoff. Codes, verification material and credentials must not be copied into agent transcripts. Legacy argv code input warns about exposure; use stdin.
+- No --open-browser or --live flag is implemented. Provider OAuth --id requires --reauth; --method is Kiro add-only.
+
+### `ocx account history`
+
+Usage: `ocx account history openai <pool-account-id> [--limit <1-200>] [--json]`
+
+Cached quota observations for one stored Codex pool account.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/quota/history` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the bounded observation history. |
+| `--limit` | number | Return the newest 1 to 200 observations. |
+
+JSON mode: `payload`.
+
+- Use account history openai <pool-account-id>. Reads cached observations only; no refresh or warmup. Native main is not included.
+
+### `ocx account main reauth`
+
+Usage: `ocx account main reauth --device [--no-wait] [--json]`
+
+Reauthenticate the native main Codex login with a device code (#3898); headless hubs need no Codex App or keyring.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/codex-auth/main/reauth-device` |
+| GET | `/api/codex-auth/main/reauth-device` |
+| DELETE | `/api/codex-auth/main/reauth-device` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--device` | boolean | Run the device-code flow (the only reauth mode). |
+| `--no-wait` | boolean | Print the flow handle and code without waiting for completion. |
+| `--flow` | string | Flow id for status and cancel. |
+| `--json` | boolean | Emit the flow status as JSON. |
+
+JSON mode: `payload`.
+
+- Same-identity native main device reauthentication; pool login endpoints are separate. Human authorization is required and credentials are never printed.
+- Start requires --device; --no-wait returns a flow handle. Follow with account main reauth status --flow <id> or account main reauth cancel --flow <id>. Status/cancel require --flow and reject --device/--no-wait.
+- Returned verification URLs and device codes are human handoff material; keep them out of agent transcripts.
+
+### `ocx account list`
+
+Usage: `ocx account list [provider] [--all] [--quota [--refresh]] [--json]`
+
+List live Codex, OAuth and API-key accounts with optional quota observations.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/oauth/providers` |
+| GET | `/api/codex-auth/accounts` |
+| GET | `/api/codex-auth/active` |
+| GET | `/api/oauth/accounts` |
+| GET | `/api/providers/keys` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--all` | boolean | Include notes for providers with no stored accounts. |
+| `--quota` | boolean | Include quota observations; OAuth may probe upstream. |
+| `--refresh` | boolean | With --quota, bypass quota cache; otherwise has no effect. |
+| `--json` | boolean | Emit the command result as JSON. |
+
+JSON mode: `envelope`.
+
+- Omitting provider discovers OAuth providers and includes configured families. JSON is {accounts,notes}, not a raw server account array.
+- Default listing is observational. --quota can probe provider quotas; --refresh is only acted on together with --quota. A refresh observation is not pending-account validation consent.
+
+### `ocx account import-orca`
+
+Usage: `ocx account import-orca --source <orca-data-directory> --registry <orca-data.json> [--apply] [--json]`
+
+Preview or register read-only links to Orca-managed Codex accounts without another login.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--source` | string | Orca data directory containing codex-accounts. |
+| `--registry` | string | The chosen Orca profile's orca-data.json account registry. |
+| `--apply` | boolean | Register new accounts; requires a stopped proxy. Default is preview. |
+| `--json` | boolean | Emit counts and fixed invalid-reason codes without credentials or source paths. |
+
+JSON mode: `envelope`.
+
+- Local files only; never copies refresh tokens or changes Orca authentication files.
+- Skips existing ChatGPT identities. New accounts remain pending until dashboard validation.
+- Orca must keep the source login available and refreshed; a missing or expired source fails closed.
+- Mixed eligible and invalid entries exit successfully; an all-invalid result exits nonzero.
+
+### `ocx account refresh`
+
+Usage: `ocx account refresh <provider> [--json]`
+
+Refresh account quotas without model validation; pending Codex accounts require dashboard consent.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/codex-auth/accounts/refresh` |
+| GET | `/api/codex-auth/active` |
+| GET | `/api/provider-quotas` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the refresh result as JSON. |
+
+JSON mode: `envelope`.
+
+- CLI/admin-token refreshes only observe usage. After quota recovery, a human must click Refresh quotas in the dashboard to authorize model validation. Do not mint a GUI session to work around this consent boundary.
+
+### `ocx account grok-reset-coupons`
+
+Usage: `ocx account grok-reset-coupons [account-id] [--consume --yes [--token-id <token-id>] [--operation-id <uuid>]] [--json]`
+
+Inspect or redeem Grok billing reset coupons; redemption is journaled and idempotent.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/grok/reset-coupons` |
+| POST | `/api/grok/reset-coupons/consume` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--consume` | boolean | Redeem one reset coupon; requires --yes. |
+| `--yes` | boolean | Explicit confirmation required by --consume. |
+| `--token-id` | string | Redeem a specific reset token instead of the default selection. |
+| `--operation-id` | string | UUIDv4 making a redemption idempotent: retries replay the journaled outcome. |
+| `--json` | boolean | Emit the coupon list or redemption result as JSON. |
+
+JSON mode: `payload`.
+
+- Without --consume this is a read: remaining coupons and their validity windows.
+- The operation is journaled before the upstream call, so retrying the same --operation-id replays the recorded outcome instead of spending a second coupon.
+
+### `ocx account pause`
+
+Usage: `ocx account pause <provider> <account-id|alias|main> [--json]`
+
+Exclude one account in a Codex, Anthropic or supported generic OAuth pool from automatic selection.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/accounts` |
+| PUT | `/api/codex-auth/accounts/pause` |
+| GET | `/api/oauth/accounts` |
+| PUT | `/api/oauth/accounts/pause` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the pause result as JSON. |
+
+JSON mode: `envelope`.
+
+- Codex pause unbinds pinned threads and selects a fallback when possible; with no fallback, a paused-but-selected Codex account still receives requests. Anthropic and generic OAuth pause exclude the account from new requests, failover and refresh, and an all-paused pool answers 403. Credentials and health are preserved; already-sent turns are not cancelled.
+
+### `ocx account resume`
+
+Usage: `ocx account resume <provider> <account-id|alias|main> [--json]`
+
+Return a paused account to a Codex, Anthropic or supported generic OAuth pool.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/accounts` |
+| PUT | `/api/codex-auth/accounts/pause` |
+| GET | `/api/oauth/accounts` |
+| PUT | `/api/oauth/accounts/pause` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the resume result as JSON. |
+
+JSON mode: `envelope`.
+
+### `ocx account pause-exhausted`
+
+Usage: `ocx account pause-exhausted <provider> [--json]`
+
+Pause every Codex account whose quota is spent.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/codex-auth/accounts/pause-exhausted` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit paused ids and the checked/failed counts as JSON. |
+
+JSON mode: `envelope`.
+
+- Only Codex account pools are supported. Refreshes quota and may partially fail; nonzero failedAccountCount exits 1 and sets ok:false.
+
+### `ocx account strategy`
+
+Usage: `ocx account strategy <provider> [quota|round-robin|fill-first|least-loaded|reset-first] [--json]`
+
+Show or set how an account pool picks the next account.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/pool/settings` |
+| PUT | `/api/pool/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the applied strategy and sticky limit as JSON. |
+
+JSON mode: `envelope`.
+
+- A bare invocation reads and never writes.
+- The APPLIED value is echoed, not the requested one, so a server-side normalization stays visible.
+- Values are not re-validated in the CLI: the server owns the strategy names and the 1-100 sticky bound.
+- One route answers for every pool kind and declares which fields that kind honours in `supported`, so an unsupported field is a stated null rather than an absence. `anthropic` alone carries `quotaWindow`. Generic-provider settings steer selection only while `pool.kernel` is on. The legacy per-pool paths still work and are unchanged.
+
+### `ocx account sticky`
+
+Usage: `ocx account sticky <provider> [1-100] [--json]`
+
+Show or set how many consecutive requests stay on one account.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/pool/settings` |
+| PUT | `/api/pool/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the applied strategy and sticky limit as JSON. |
+
+JSON mode: `envelope`.
+
+- Only meaningful under the sticky-capable strategies; the pool strategy is the other half of this setting.
+
+### `ocx account routes`
+
+Usage: `ocx account routes anthropic [--file <json-file>|--clear] [--json]`
+
+Read, replace, or clear Anthropic OAuth model account routes.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/pool/settings` |
+| PUT | `/api/pool/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--file` | string | Read a bounded JSON route array from a local file. |
+| `--clear` | boolean | Remove the stored routes. |
+| `--json` | boolean | Emit the unified settings response as JSON. |
+
+JSON mode: `payload`.
+
+- Only anthropic is supported. Omitted --file/--clear reads. --clear sends routes:null; file and clear are mutually exclusive. The local JSON file must be a regular file of at most 64 KiB; the server validates its route array.
+
+### `ocx account auto-switch`
+
+Usage: `ocx account auto-switch <provider> <status|on|off|threshold <0-100>|inherit> [--account <id>] [--json]`
+
+Show or set the usage percentage at which a pool moves to another account.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/active` |
+| PUT | `/api/codex-auth/auto-switch` |
+| GET | `/api/oauth/accounts/pool` |
+| PUT | `/api/oauth/accounts/pool` |
+| GET | `/api/oauth/accounts` |
+| PUT | `/api/oauth/accounts/auto-switch` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the stored threshold and whether it is applied. |
+| `--account` | string | Anthropic account ID; inherit restores the pool default, off stores zero. |
+
+JSON mode: `envelope`.
+
+- An explicit action is required; status is the read-only action. A bare invocation is a usage error.
+- on stores 80, off stores 0 and threshold accepts 0-100. Anthropic requires --account <id> for every action and alone accepts inherit, which sends null. Codex and generic OAuth accept neither --account nor inherit.
+- Generic pool inert:true means stored but not applied; false means applied; absent means support is unknown. API-key providers are refused.
+
+### `ocx logout`
+
+Usage: `ocx logout <provider> [--json]`
+
+Remove the active stored OAuth credential for a provider locally.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit schemaVersion, ok, provider and removed; missing credentials include reason:not_found. |
+
+JSON mode: `envelope`.
+
+- Local credential-store operation, not POST /api/oauth/logout. Requires operator intent; rejects malformed arguments before store access. Missing credential exits 4, usage errors exit 2. Does not prove that a running proxy has reloaded its cached credentials.
+
+### `ocx account current`
+
+Usage: `ocx account current <provider> [--json]`
+
+Read the active account or API key for a provider.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/accounts` |
+| GET | `/api/codex-auth/active` |
+| GET | `/api/oauth/accounts` |
+| GET | `/api/providers/keys` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit provider, type, activeId and the projected account. |
+
+JSON mode: `envelope`.
+
+- Uses the live route for the configured account family; this does not report the physical native-main profile.
+
+### `ocx account use`
+
+Usage: `ocx account use <provider> <account-or-key-id|alias|main|auto> [--json]`
+
+Select a provider's pool account or API key.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/accounts` |
+| GET | `/api/codex-auth/active` |
+| PUT | `/api/codex-auth/active` |
+| PUT | `/api/oauth/accounts/active` |
+| PUT | `/api/providers/keys/active` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the selection receipt, including pin-drain information when present. |
+
+JSON mode: `envelope`.
+
+- Codex resolves IDs and aliases before reserved words; an account actually named auto wins. account clear openai always clears. OAuth and API-key selection pass the ID directly. This does not switch the physical Codex App login.
+
+### `ocx account clear`
+
+Usage: `ocx account clear <provider> [--json]`
+
+Clear a Codex pool's manual account selection pin.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/codex-auth/active` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the clear receipt. |
+
+JSON mode: `envelope`.
+
+- Only Codex account pools are supported; other families are refused. Sends accountId:null without interpreting auto as an account ID.
+
+### `ocx account alias`
+
+Usage: `ocx account alias <provider> <account-or-key-id|alias> <display-name|-> [--json]`
+
+Set or clear an account's display alias.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/accounts` |
+| PUT | `/api/codex-auth/accounts/alias` |
+| PUT | `/api/oauth/accounts/alias` |
+| PUT | `/api/providers/keys/alias` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the applied alias, or null after clearing. |
+
+JSON mode: `envelope`.
+
+- - clears with an empty string. Codex resolves existing aliases; other families take an ID. Native main cannot be renamed; aliases are at most 80 printable characters. rename is an existing command alias.
+
+### `ocx account priority`
+
+Usage: `ocx account priority <provider> <account-id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]`
+
+Read or change Codex account selection order.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/accounts` |
+| GET | `/api/codex-auth/active` |
+| PUT | `/api/codex-auth/accounts/priority` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the normalized priority and named preset. |
+
+JSON mode: `envelope`.
+
+- Only Codex pools support selection order. Omitting the value reads; reset sends null. Every write releases any manual pin, even if the value is unchanged; running threads retain their account until drained.
+
+### `ocx account clear-cooldown`
+
+Usage: `ocx account clear-cooldown <provider> <account-id|alias|main> [--json]`
+
+Lift an operator-clearable Codex or Anthropic account cooldown.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/accounts` |
+| GET | `/api/oauth/accounts` |
+| POST | `/api/codex-auth/accounts/clear-cooldown` |
+| POST | `/api/oauth/accounts/clear-cooldown` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit whether a cooldown was actually cleared. |
+
+JSON mode: `envelope`.
+
+- Other provider families are refused. Resolves Codex or Anthropic account aliases before writing.
+
+### `ocx account remove`
+
+Usage: `ocx account remove <provider> <account-or-key-id|alias> --yes [--json]`
+
+Remove a pool account or provider API key with explicit confirmation.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/accounts` |
+| GET | `/api/codex-auth/active` |
+| GET | `/api/oauth/accounts` |
+| GET | `/api/providers/keys` |
+| DELETE | `/api/codex-auth/accounts` |
+| DELETE | `/api/oauth/accounts` |
+| DELETE | `/api/providers/keys` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Confirm account/key deletion. |
+| `--json` | boolean | Emit removal and promoted-account information. |
+
+JSON mode: `envelope`.
+
+- Native main removal is refused. Reads the account family before and after deletion; a failed post-delete read means deletion may have succeeded. Only Codex resolves aliases here.
+
+### `ocx account add-key`
+
+Usage: `ocx account add-key <provider> [--label <label>] [--json]`
+
+Import an existing provider API key from a human-controlled stdin source.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/providers/keys` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--label` | string | Optional label for the imported key. |
+| `--json` | boolean | Emit a redacted receipt containing the key ID, never the key. |
+
+JSON mode: `envelope`.
+
+- API-key providers only. Requires non-TTY stdin and reads one secret line; never put plaintext keys in command arguments or agent transcripts. This imports an upstream credential, not an OpenCodex access-key creation workflow.
+
+### `ocx account import`
+
+Usage: `ocx account import google-antigravity --format cockpit-tools (--file <path>|--stdin) [--json]`
+
+Import Google Antigravity accounts from a bounded Cockpit Tools document.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/oauth/accounts/import` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--format` | string | Only cockpit-tools is supported. |
+| `--file` | string | Bounded source document; exclusive with --stdin. |
+| `--stdin` | boolean | Read the document from non-TTY stdin. |
+| `--json` | boolean | Emit sanitized per-record import outcomes. |
+
+JSON mode: `envelope`.
+
+- Human-controlled credential handoff: choose exactly one source. Unsupported providers/formats are refused before source I/O. Partial failures or unsupported records return nonzero; do not echo the document.
+
+### `ocx account reauth`
+
+Usage: `ocx account reauth <provider> [--id <account-id>] [--device] [--code -] [--no-wait] [--json]`
+
+Reauthenticate a provider account through the existing login flow.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/codex-auth/login` |
+| GET | `/api/codex-auth/login-status` |
+| POST | `/api/codex-auth/login/code` |
+| POST | `/api/oauth/login` |
+| GET | `/api/oauth/status` |
+| POST | `/api/oauth/login/code` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--id` | string | Account identity to reauthenticate. |
+| `--device` | boolean | Codex device login; accepted for already-device-native kimi, nous and github-copilot. |
+| `--code` | string | Use - to read the short-lived authorization code from stdin. |
+| `--no-wait` | boolean | Return after starting the flow. |
+| `--json` | boolean | Emit login instructions or completion state. |
+
+JSON mode: `payload`.
+
+- Alias of account login with --reauth. openai, codex and chatgpt address the pool; native main uses account main reauth. Human completes authorization; keep returned login material out of transcripts. Kiro --method cannot be combined with reauth.
+
+### `ocx account code`
+
+Usage: `ocx account code <provider> [--flow <flow-id>] [--code -] [--json]`
+
+Submit a login redirect or authorization code from stdin.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/codex-auth/login/code` |
+| POST | `/api/oauth/login/code` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--flow` | string | Required for openai, codex or chatgpt pool flows. |
+| `--code` | string | Use - for stdin; omission also reads stdin. |
+| `--json` | boolean | Emit submission receipt. |
+
+JSON mode: `payload`.
+
+- A short-lived credential is a human handoff. Legacy positional/argv code input exists but warns about exposure; use stdin and never echo it.
+
+### `ocx account cancel`
+
+Usage: `ocx account cancel <provider> [--flow <flow-id>] [--json]`
+
+Cancel a pending account login flow.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/codex-auth/login/cancel` |
+| POST | `/api/oauth/login/cancel` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--flow` | string | Required for Codex; selects a native Kiro flow when supplied. |
+| `--json` | boolean | Emit cancellation receipt. |
+
+JSON mode: `payload`.
+
+- Codex cancellation sends flowId. Other providers send provider; Kiro additionally forwards a supplied flowId.
+
+### `ocx account reset-credits`
+
+Usage: `ocx account reset-credits <account-id|main> [--consume --yes [--operation-id <uuid>]] [--json]`
+
+Read Codex reset-credit state, or explicitly consume one with operator authorization.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/reset-credits` |
+| POST | `/api/codex-auth/reset-credits/consume` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--consume` | boolean | Spend a reset credit; requires operator intent and --yes. |
+| `--yes` | boolean | Confirm consumption. |
+| `--operation-id` | string | UUIDv4 retry identity; only valid with --consume. |
+| `--json` | boolean | Emit reset-credit state or receipt. |
+
+JSON mode: `payload`.
+
+- A bare invocation reads only. main maps to __main__; reads never consume a credit. This does not control credits-after-limit settings.
+
+### `ocx account main doctor`
+
+Usage: `ocx account main doctor [--json]`
+
+Diagnose native Codex login profile storage and recovery state.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/native-main-profiles/doctor` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit diagnosis; this command also prints JSON by default. |
+
+JSON mode: `payload`.
+
+- Reports the physical login in the server's effective CODEX_HOME, independently of pool account selection.
+
+### `ocx account main list`
+
+Usage: `ocx account main list [--json]`
+
+List encrypted native Codex login profiles.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/native-main-profiles` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit public profile metadata, not stored credentials. |
+
+JSON mode: `payload`.
+
+### `ocx account main register`
+
+Usage: `ocx account main register <label> [--json]`
+
+Register the current physical Codex login as an encrypted profile.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/native-main-profiles/register` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the registration receipt. |
+
+JSON mode: `payload`.
+
+- Captures the current login in the effective CODEX_HOME; it does not start a new login or select a pool account.
+
+### `ocx account main add`
+
+Usage: `ocx account main add <label>`
+
+Add a native login profile through a human-operated official Codex login.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/native-main-profiles/stage` |
+| POST | `/api/native-main-profiles/stage/heartbeat` |
+| POST | `/api/native-main-profiles/stage/finish` |
+| POST | `/api/native-main-profiles/stage/cancel` |
+
+JSON mode: `none`.
+
+- Human handoff: runs official Codex login locally in the server-provided restricted staging home, maintains a writer lease and encrypts the result. No --json, --yes or --rollback mode. Cleanup failure requires account main doctor; never expose writer tokens or credential files.
+
+### `ocx account main reauth status`
+
+Usage: `ocx account main reauth status --flow <id> [--json]`
+
+Read an existing same-identity native-main reauthentication flow.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/main/reauth-device` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--flow` | string | Flow ID returned by the human-started reauthentication. |
+| `--json` | boolean | Emit flow state; pending state may include human login material. |
+
+JSON mode: `payload`.
+
+### `ocx account main reauth cancel`
+
+Usage: `ocx account main reauth cancel --flow <id> [--json]`
+
+Cancel a native-main reauthentication flow.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| DELETE | `/api/codex-auth/main/reauth-device` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--flow` | string | Flow ID to cancel. |
+| `--json` | boolean | Emit cancellation state. |
+
+JSON mode: `payload`.
+
+### `ocx account main switch`
+
+Usage: `ocx account main switch <profile-id-or-label> --yes [--json]`
+
+Switch the physical Codex App/CLI login to a registered profile.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/native-main-profiles/switch` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Confirm the operator has closed Codex App/CLI. |
+| `--json` | boolean | Emit the native-login switch receipt. |
+
+JSON mode: `payload`.
+
+- Changes the effective CODEX_HOME login, independently of account use openai. The operator must stop Codex first and restart it afterwards; no automatic restart is performed.
+
+### `ocx account main recover`
+
+Usage: `ocx account main recover [--rollback --yes] [--json]`
+
+Recover an interrupted native-login profile transaction.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/native-main-profiles/recover` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--rollback` | boolean | Restore the previous login; requires --yes. |
+| `--yes` | boolean | Confirm Codex App/CLI is stopped for rollback. |
+| `--json` | boolean | Emit recovery outcome. |
+
+JSON mode: `payload`.
+
+- Even without --rollback this calls recovery with rollback:false; it is not the doctor read. Rollback writes the native login only after explicit confirmation.
diff --git a/skills/ocx/references/01_surface_agents-routing.md b/skills/ocx/references/01_surface_agents-routing.md
new file mode 100644
index 00000000000..851ebfc12e3
--- /dev/null
+++ b/skills/ocx/references/01_surface_agents-routing.md
@@ -0,0 +1,807 @@
+<!-- GENERATED by scripts/generate-ocx-skill-surface.ts. Do not edit by hand. -->
+<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->
+
+# agents-routing: declared management tasks
+
+[Management index](01_management_surface.md) · [Operating rules](../SKILL.md#secret-bearing-commands)
+
+Use these declarations to choose a task, then check its flags and authority before execution.
+Non-mutating probes may still contact providers, consume quota or refresh caches.
+
+Declared capabilities: 38.
+
+### `ocx agent subagents force`
+
+Usage: `ocx agent subagents force <model|-> [--json]`
+
+Force Claude Code subagents onto one exposed model at the next routed launch; - clears.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/subagent-models` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the saved force setting. |
+
+JSON mode: `payload`.
+
+- Requires Claude Code 2.1.257+. Plain claude, forks, inherit skills, the main model and small-fast sidecars are unaffected.
+
+### `ocx agent request-user-input`
+
+Usage: `ocx agent request-user-input [on|off] [--json]`
+
+Show or set whether default mode may ask the operator a question mid-task.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-auth/features/default-mode-request-user-input` |
+| PUT | `/api/codex-auth/features/default-mode-request-user-input` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the feature state as JSON. |
+
+JSON mode: `payload`.
+
+- A bare invocation reads and never writes.
+
+### `ocx agent roles`
+
+Usage: `ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]`
+
+omo (Codex / LazyCodex): show each Codex agent role's model pin, set one role's model in its TOML and in omo.jsonc, or suggest a model for every role.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-agent-roles` |
+| PUT | `/api/codex-agent-roles/{role}` |
+| POST | `/api/codex-agent-roles/auto-assign` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the role list, the write result or the proposals as JSON. |
+| `--model` | string | suggest: size the roles with this model instead of the Codex default model. |
+| `--apply` | boolean | suggest: write every proposal through the role model write. |
+
+JSON mode: `payload`.
+
+- A bare invocation reads and never writes.
+- Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.
+- set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml; omo.jsonc is skipped when absent or when it contains comments.
+- suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort.
+
+### `ocx agent injection`
+
+Usage: `ocx agent injection status [--json]; ocx agent injection set [--model <id|->] [--effort <level|->] [--prompt <text|->] [--guidance <on|off>] [--json]; ocx agent injection suggest <work description> [--model <id>] [--apply] [--json]`
+
+Show or set the delegation model and effort, or suggest both for a described piece of delegated work.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/injection-model` |
+| PUT | `/api/injection-model` |
+| POST | `/api/injection-model/suggest` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the delegation settings, the write result or the proposal as JSON. |
+| `--model` | string | set: the delegation model, - clears it. suggest: size the work with this model instead of the Codex default model. |
+| `--effort` | string | set: the delegation reasoning effort, - clears it. |
+| `--prompt` | string | set: a custom guidance prompt, - clears it. |
+| `--guidance` | string | set: on or off for OpenCodex delegation guidance. |
+| `--apply` | boolean | suggest: write the proposed model and effort through the delegation settings write. |
+
+JSON mode: `payload`.
+
+- guidance aliases injection. Bare invocation reads; use explicit status before --json. set requires at least one setting and - clears model, effort or prompt.
+- suggest may spend a model call; it writes no settings unless --apply is explicitly supplied. Preserve unsized/unassigned/already-set outcomes.
+
+### `ocx combo test`
+
+Usage: `ocx combo test [--combo <id>] [--decision-provider <provider|jev> | --decision-model <route>] [--decision-timeout <ms>] [--json]`
+
+Run one JEV decision probe through a decision method: TypeSafe, a System One row, or an opencodex model.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/combos` |
+| POST | `/api/combos/decision-test` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--combo` | string | Combo id whose saved decision method is probed and whose recursion rules apply. |
+| `--decision-provider` | string | Probe a jev-decision provider row (or jev for TypeSafe) instead of the saved method. |
+| `--decision-model` | string | Probe an opencodex-routed model instead of the saved method. |
+| `--decision-timeout` | number | Decision deadline in milliseconds (1000-120000). |
+| `--json` | boolean | Emit the probe result. |
+
+JSON mode: `payload`.
+
+- --combo without an explicit decision override reads the saved combo first. The synthetic decision probe may spend a backend call; a failed-open receipt is not an applied decision.
+
+### `ocx combo discover`
+
+Usage: `ocx combo discover [--query <text>] [--json]`
+
+List configured System One decision rows and catalog models that look like decision services.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/combos/decision-discovery` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--query` | string | Match catalog rows by this text instead of the built-in decision-model hint. |
+| `--json` | boolean | Emit the discovery payload. |
+
+JSON mode: `payload`.
+
+- Read-only: nothing is probed and no provider row is created.
+
+### `ocx agent status`
+
+Usage: `ocx agent status [--json]`
+
+Read agent mode, delegation, effort caps, roster, fallback and sidecars.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/v2` |
+| GET | `/api/injection-model` |
+| GET | `/api/effort-caps` |
+| GET | `/api/subagent-models` |
+| GET | `/api/subagent-model-fallback` |
+| GET | `/api/sidecar-settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `envelope`.
+
+### `ocx agent effort`
+
+Usage: `ocx agent effort status [--json]`
+
+Read or set main and subagent effort caps.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/effort-caps` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- set requires at least one cap; a null clears it.
+
+### `ocx agent effort set`
+
+Usage: `ocx agent effort set [--main <level|->] [--subagent <level|->] [--json]`
+
+Read or set main and subagent effort caps.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/effort-caps` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--main` | string | Main effort cap; - clears. |
+| `--subagent` | string | Subagent effort cap; - clears. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- set requires at least one cap; a null clears it.
+
+### `ocx agent subagents`
+
+Usage: `ocx agent subagents status [--json]`
+
+Read, replace or clear the ordered featured subagent roster.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/subagent-models` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- At most five models; clear sends an empty roster. agent roster is an alias.
+
+### `ocx agent subagents set`
+
+Usage: `ocx agent subagents set <model,model...> [--json]`
+
+Read, replace or clear the ordered featured subagent roster.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/subagent-models` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- At most five models; clear sends an empty roster. agent roster is an alias.
+
+### `ocx agent subagents clear`
+
+Usage: `ocx agent subagents clear [--json]`
+
+Clear the saved subagents models.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/subagent-models` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- At most five models; clear sends an empty roster. agent roster is an alias.
+
+### `ocx agent fallback`
+
+Usage: `ocx agent fallback status [--json]`
+
+Read, replace or clear fallback models and polling interval.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/subagent-model-fallback` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- set requires models and/or --poll-ms; clear empties the models and may also set --poll-ms.
+
+### `ocx agent fallback set`
+
+Usage: `ocx agent fallback set [model,model...] [--poll-ms <5000-600000>] [--json]`
+
+Read, replace or clear fallback models and polling interval.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/subagent-model-fallback` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--poll-ms` | number | Polling interval, 5000-600000 milliseconds. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- set requires models and/or --poll-ms; clear empties the models and may also set --poll-ms.
+
+### `ocx agent fallback clear`
+
+Usage: `ocx agent fallback clear [--poll-ms <5000-600000>] [--json]`
+
+Clear the saved fallback models.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/subagent-model-fallback` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--poll-ms` | number | Polling interval, 5000-600000 milliseconds. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- set requires models and/or --poll-ms; clear empties the models and may also set --poll-ms.
+
+### `ocx agent sidecar`
+
+Usage: `ocx agent sidecar status [--json]`
+
+Read configured sidecars and candidate models.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/sidecar-settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+### `ocx agent sidecar web`
+
+Usage: `ocx agent sidecar web (--list | [--model <id|->] [--backend <openai|anthropic|xai|gemini|exa|->] [--reasoning <level>] [--max-descriptions <n>] [--enabled <on|off>]) [--json]`
+
+List web candidates or change the web sidecar.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/sidecar-settings` |
+| PUT | `/api/sidecar-settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--list` | boolean | Read candidates only; cannot combine with setting flags. |
+| `--model` | string | Model selector; - clears. |
+| `--backend` | string | Backend selector; - clears. |
+| `--reasoning` | string | Reasoning level. |
+| `--max-descriptions` | number | Positive description limit. |
+| `--enabled` | string | on or off. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- Without --list at least one setting is required. Stored settings and Codex application outcomes remain distinct.
+
+### `ocx agent sidecar vision`
+
+Usage: `ocx agent sidecar vision (--list | [--model <id|->] [--backend <openai|anthropic|routed|->] [--reasoning <level>] [--max-descriptions <n>] [--enabled <on|off>]) [--json]`
+
+List vision candidates or change the vision sidecar.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/sidecar-settings` |
+| PUT | `/api/sidecar-settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--list` | boolean | Read candidates only; cannot combine with setting flags. |
+| `--model` | string | Model selector; - clears. |
+| `--backend` | string | Backend selector; - clears. |
+| `--reasoning` | string | Reasoning level. |
+| `--max-descriptions` | number | Positive description limit. |
+| `--enabled` | string | on or off. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- Without --list at least one setting is required. Stored settings and Codex application outcomes remain distinct.
+
+### `ocx effort`
+
+Usage: `ocx effort [status|low|medium|high|xhigh|max|ultra|->] [--json]`
+
+Read effort settings or set the main cap with a shorthand level.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/effort-caps` |
+| GET | `/api/injection-model` |
+| PUT | `/api/effort-caps` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `envelope`.
+
+- Uses the live proxy when available, otherwise local config. Once live is selected, errors never fall back to local writes; set reads back live status and can report partial application.
+- The shorthand ocx effort <low|medium|high|xhigh|max|ultra|-> changes only the main cap; unset aliases clear.
+
+### `ocx effort set`
+
+Usage: `ocx effort set [--main <level|->] [--subagent <level|->] [--injection <level|->] [--json]`
+
+Set one or more effort fields.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/effort-caps` |
+| PUT | `/api/injection-model` |
+| GET | `/api/effort-caps` |
+| GET | `/api/injection-model` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--main` | string | Main cap; - clears. |
+| `--subagent` | string | Subagent cap; - clears. |
+| `--injection` | string | Delegation effort; - clears; also accepts none/minimal. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `envelope`.
+
+- Local configuration is used when no live proxy is found; runtime failures are not silent offline success.
+
+### `ocx effort clear`
+
+Usage: `ocx effort clear [--json]`
+
+Clear both caps while retaining delegation effort.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/effort-caps` |
+| GET | `/api/effort-caps` |
+| GET | `/api/injection-model` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `envelope`.
+
+- Local configuration is used when no live proxy is found; runtime failures are not silent offline success.
+
+### `ocx effort model`
+
+Usage: `ocx effort model <provider/model|model> [--json]`
+
+Inspect a model effort ladder and wire mappings from local configuration.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `envelope`.
+
+- Local configuration/catalog derivation; routes is empty because no management API is called.
+
+### `ocx v2 status`
+
+Usage: `ocx v2 [status]`
+
+Report local multi-agent mode and Codex feature settings.
+
+State-changing: no.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.
+- This command does not claim to update a remote proxy.
+
+### `ocx v2 on`
+
+Usage: `ocx v2 on`
+
+Enable the local Codex multi_agent_v2 feature.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.
+- Mode/feature changes may resync catalogs; a failed resync does not mean the setting was rolled back.
+
+### `ocx v2 off`
+
+Usage: `ocx v2 off`
+
+Disable the local Codex multi_agent_v2 feature.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.
+- Mode/feature changes may resync catalogs; a failed resync does not mean the setting was rolled back.
+
+### `ocx v2 mode`
+
+Usage: `ocx v2 mode <v1|default|v2>`
+
+Set local model-catalog multi-agent mode.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.
+- Mode/feature changes may resync catalogs; a failed resync does not mean the setting was rolled back.
+
+### `ocx v2 keep-native-v1`
+
+Usage: `ocx v2 keep-native-v1 <on|off>`
+
+Keep native ChatGPT on v1 while routed models use v2.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.
+- Mode/feature changes may resync catalogs; a failed resync does not mean the setting was rolled back.
+
+### `ocx v2 threads`
+
+Usage: `ocx v2 threads <n>`
+
+Set the local active-mode thread limit (integer at least 1).
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.
+- This command does not claim to update a remote proxy.
+
+### `ocx v2 mode-hint`
+
+Usage: `ocx v2 mode-hint <text|--clear>`
+
+Set nonblank local delegation hint text or restore effort-derived policy.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--clear` | boolean | Unset the hint. |
+
+JSON mode: `none`.
+
+- Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.
+- This command does not claim to update a remote proxy.
+
+### `ocx combo list`
+
+Usage: `ocx combo list [--json]`
+
+List saved combos.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/combos` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+### `ocx combo show`
+
+Usage: `ocx combo show <id> [--json]`
+
+Read one saved combo from the collection.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/combos` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+### `ocx combo set`
+
+Usage: `ocx combo set <id> [--targets <provider/model[:weight],...>] [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->] [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->] [--alias <name|->] [--native-alias] [--display-name <label|->] [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->] [--rename-from <id>] [--json]`
+
+Create, update or rename a combo.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/combos` |
+| PUT | `/api/combos` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--targets` | string | Ordered provider/model[:weight] list; required for creation. |
+| `--strategy` | string | Routing strategy. |
+| `--sticky` | string | Round-robin limit 1-100; - resets. |
+| `--effort` | string | Default effort; - clears. |
+| `--effort-mode` | string | fallback or force; - resets to fallback. |
+| `--alias` | string | Alias; - clears. |
+| `--native-alias` | boolean | Enable native-shaped alias. |
+| `--display-name` | string | Label; - clears. |
+| `--decision-provider` | string | JEV provider; - clears. |
+| `--decision-model` | string | JEV route; - clears; exclusive with provider. |
+| `--decision-timeout` | string | JEV deadline 1000-120000 ms; - clears. |
+| `--rename-from` | string | Existing combo ID to rename. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- create and update are aliases of set. Existing fields are read before writing; --targets replaces targets.
+- force overrides valid client effort and may increase cost and latency.
+- Only the implemented target grammar is supported; full GUI target metadata and routing-profile writes are separate tasks.
+
+### `ocx combo remove`
+
+Usage: `ocx combo remove <id> --yes [--json]`
+
+Remove a saved combo after explicit confirmation.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| DELETE | `/api/combos` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Confirm deletion. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- delete is an alias; the ID is encoded in the id query parameter.
+
+### `ocx route policy list`
+
+Usage: `ocx route policy list [--json]`
+
+List saved routing profiles and revisions.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/routing-profiles` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+### `ocx route policy show`
+
+Usage: `ocx route policy show <id> [--json]`
+
+Read one saved routing profile.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/routing-profiles` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+### `ocx route policy dry-run`
+
+Usage: `ocx route policy dry-run <id> [--model-context <tokens>] [--tools] [--image] [--structured-output] [--json]`
+
+Evaluate a saved profile against explicit requirements without changing it.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/routing-profiles/dry-run` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--model-context` | number | Positive context window requirement. |
+| `--tools` | boolean | Require tools. |
+| `--image` | boolean | Require image input. |
+| `--structured-output` | boolean | Require structured output. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- evaluate and dry-run do not save the profile, but their POST can activate Lab and start automation already enabled by local policy. No profile create, update or delete is exposed.
+
+### `ocx route policy evaluate`
+
+Usage: `ocx route policy evaluate <id> [--model-context <tokens>] [--tools] [--image] [--structured-output] [--json]`
+
+Evaluate a saved profile against explicit requirements without changing it.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/routing-profiles/dry-run` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--model-context` | number | Positive context window requirement. |
+| `--tools` | boolean | Require tools. |
+| `--image` | boolean | Require image input. |
+| `--structured-output` | boolean | Require structured output. |
+| `--json` | boolean | Emit structured JSON. |
+
+JSON mode: `payload`.
+
+- evaluate and dry-run do not save the profile, but their POST can activate Lab and start automation already enabled by local policy. No profile create, update or delete is exposed.
+
+### `ocx memory`
+
+Usage: `ocx memory [--limit <n>] [--json]`
+
+Read runtime memory and active-turn diagnostics.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/system/memory` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--limit` | number | Positive limit forwarded to the endpoint. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Alias of observe memory.
diff --git a/skills/ocx/references/01_surface_integrations.md b/skills/ocx/references/01_surface_integrations.md
new file mode 100644
index 00000000000..f0ca2ba4a94
--- /dev/null
+++ b/skills/ocx/references/01_surface_integrations.md
@@ -0,0 +1,717 @@
+<!-- GENERATED by scripts/generate-ocx-skill-surface.ts. Do not edit by hand. -->
+<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->
+
+# integrations: declared management tasks
+
+[Management index](01_management_surface.md) · [Operating rules](../SKILL.md#secret-bearing-commands)
+
+Use these declarations to choose a task, then check its flags and authority before execution.
+Non-mutating probes may still contact providers, consume quota or refresh caches.
+
+Declared capabilities: 33.
+
+### `ocx claude config`
+
+Usage: `ocx claude config status [--json]; ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]`
+
+Read or update Claude Code settings, including independent CLI first-party routing.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/claude-code` |
+| PUT | `/api/claude-code` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--enabled` | string | on or off. |
+| `--auth-mode` | string | auto, proxy or subscription. |
+| `--system-env` | string | on or off. |
+| `--fast-mode` | string | on or off. |
+| `--auto-context` | string | on or off. |
+| `--compact-window` | string | Positive token count or default to clear. |
+| `--inject-agents` | string | on or off. |
+| `--small-fast-model` | string | Model ID; - clears. |
+| `--model-map` | string | Comma-separated from=to mappings; - clears. |
+| `--blocked-skills` | string | Comma-separated names; - clears. |
+| `--web-model` | string | Model ID; - clears. |
+| `--web-backend` | string | openai, anthropic, xai, gemini, exa or -. |
+| `--vision-model` | string | Model ID; - clears. |
+| `--vision-backend` | string | openai, anthropic or -. |
+| `--first-party` | string | on or off; must be the only setting. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- At least one setting is required. --first-party must be set alone and writes Claude settings immediately.
+- Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings.
+
+### `ocx claude intercept start`
+
+Usage: `ocx claude intercept start [--json]`
+
+Start the local Claude interception pair on demand.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/claude-intercept/start` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the management response as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx claude desktop status`
+
+Usage: `ocx claude desktop status [--json]`
+
+Applied-vs-desired Claude Desktop state, including staleness, drift, and health.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/claude-desktop/status` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the live status as JSON. |
+
+JSON mode: `payload`.
+
+- Distinct from `claude desktop show`, which reports what this machine WOULD write; this reports what is actually in effect, which only the running proxy knows.
+
+### `ocx claude desktop bind`
+
+Usage: `ocx claude desktop bind <picker-model-id> <provider/model|native/slug>`
+
+First-party: serve a Claude Desktop Code tab picker model with an opencodex route.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/claude-desktop/first-party-bindings` |
+
+JSON mode: `none`.
+
+- Takes a picker model id (claude-sonnet-4-6) and a route in the Desktop route vocabulary (provider/model or native/<slug>); the route must be one the Desktop profile can offer.
+- Only Claude Code traffic that reaches the proxy through the first-party intercept (Desktop's Code tab, the claude CLI) honours it; ocx claude and the public Messages endpoint are unaffected.
+- The Desktop picker keeps Anthropic's label; the binding changes which model answers, starting with the next request.
+
+### `ocx claude desktop unbind`
+
+Usage: `ocx claude desktop unbind <picker-model-id>`
+
+Remove a first-party Claude Desktop Code tab picker binding.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/claude-desktop/first-party-bindings` |
+
+JSON mode: `none`.
+
+- Removing an id that is not bound is a no-op; the remaining bindings are printed.
+
+### `ocx claude desktop picker status`
+
+Usage: `ocx claude desktop picker status [--json]`
+
+First-party picker mode: whether Claude Desktop's Code tab lists opencodex models, and what is missing if not.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/claude-desktop/picker` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Reads the live picker when available; otherwise reports local offline picker state. JSON emits the picker DTO, not the enclosing API response. No trust mutation.
+
+### `ocx claude desktop picker on`
+
+Usage: `ocx claude desktop picker on`
+
+Turn first-party picker mode on and remember the choice.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/claude-desktop/picker` |
+
+JSON mode: `none`.
+
+- Needs a running proxy, first-party mode and macOS. The first time, macOS asks to trust a local certificate authority limited to claude.ai; when the server cannot show that prompt the command runs the trust step in this terminal.
+- Claude Desktop then reaches the network through opencodex; fully quit and reopen Desktop afterwards.
+
+### `ocx claude desktop picker off`
+
+Usage: `ocx claude desktop picker off`
+
+Turn first-party picker mode off, remove its Desktop egress profile and certificate trust, and remember the choice.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/claude-desktop/picker` |
+
+JSON mode: `none`.
+
+- Works without a running proxy: the preference is saved and the picker profile and trust are removed locally.
+
+### `ocx claude desktop picker trust`
+
+Usage: `ocx claude desktop picker trust`
+
+Run the macOS keychain step for picker mode in this terminal, then ask the server to finish enabling it.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/claude-desktop/picker` |
+| PUT | `/api/claude-desktop/picker` |
+
+JSON mode: `none`.
+
+- The server removes trust this command added if the enable is refused; if the request is lost, trust is left alone and picker status tells what happened.
+
+### `ocx integration native`
+
+Usage: `ocx integration native [list] [--json]; ocx integration native <claude|claude-desktop|codex|grok> <on|off> [--json]`
+
+Read native integration state or toggle Claude, Claude Desktop, Codex and Grok.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/native-integrations` |
+| PUT | `/api/native-integrations/claude` |
+| PUT | `/api/native-integrations/claude-desktop` |
+| PUT | `/api/native-integrations/codex` |
+| PUT | `/api/native-integrations/grok` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the client rows or toggle result as JSON. |
+
+JSON mode: `payload`.
+
+- Each toggle writes the selected client configuration through its runtime owner. Refused disables remain failures. Cursor status and installer have no branch in this handler and must remain deferred.
+
+### `ocx integration client`
+
+Usage: `ocx integration client status [--client <id>] [--profile <id>] [--json]; ocx integration client history [--client <id>] [--profile <id>] [--json]; ocx integration client enable --client <id> [--profile <id>] [--overwrite-conflict] [--json]; ocx integration client disable --client <id> [--profile <id>] [--json]; ocx integration client restore --op <opId> [--client aside --profile <id>] [--confirm-drift] [--json]`
+
+Inspect and toggle file integrations and Aside profiles, read journals, and restore selected operations.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/client-integrations` |
+| GET | `/api/client-integrations/{clientId}` |
+| GET | `/api/client-integrations/aside/profiles` |
+| GET | `/api/client-integrations/aside/profiles/{profileId}` |
+| GET | `/api/client-integrations/journal` |
+| GET | `/api/client-integrations/aside/profiles/journal` |
+| GET | `/api/client-integrations/aside/profiles/{profileId}/journal` |
+| PUT | `/api/client-integrations/{clientId}` |
+| PUT | `/api/client-integrations/aside/profiles` |
+| PUT | `/api/client-integrations/aside/profiles/{profileId}` |
+| POST | `/api/client-integrations/restore` |
+| POST | `/api/client-integrations/aside/profiles/{profileId}/restore` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--client` | string | File integration ID; aside selects profiles. |
+| `--profile` | number | Aside nonnegative integer account ID; requires --client aside. |
+| `--json` | boolean | Emit the result as JSON. |
+| `--overwrite-conflict` | boolean | Explicitly permit replacing a conflicting block. |
+| `--op` | string | Operation ID; --op-id is an alias. |
+| `--confirm-drift` | boolean | Explicitly allow replacing edits made after the snapshot. |
+
+JSON mode: `payload`.
+
+- status/show/list reads all clients, one client or Aside profiles. history/journal reads rollback records; expired snapshots stay visible.
+- enable/disable requires --client; an omitted Aside --profile toggles all profiles. --overwrite-conflict applies only to enable.
+- restore requires --op (alias --op-id); --client requires --profile and only Aside supports that profile selector. --confirm-drift is an explicit user waiver, never auto-retried. No preview or journal-retirement verb is claimed.
+
+### `ocx grok status`
+
+Usage: `ocx grok status [--json]`
+
+Read Grok model fence state and catalog.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/grok` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.
+- Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file.
+
+### `ocx grok set`
+
+Usage: `ocx grok set <model,model...> [--json]`
+
+Replace the excluded Grok model list.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/grok/selection` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.
+- Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file.
+
+### `ocx grok exclude`
+
+Usage: `ocx grok exclude <model,model...> [--json]`
+
+Add models to the Grok exclusion list.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/grok` |
+| PUT | `/api/grok/selection` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.
+- Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file.
+
+### `ocx grok include`
+
+Usage: `ocx grok include <model,model...> [--json]`
+
+Remove models from the Grok exclusion list.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/grok` |
+| PUT | `/api/grok/selection` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.
+- Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file.
+
+### `ocx grok clear`
+
+Usage: `ocx grok clear [--json]`
+
+Clear Grok exclusions.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/grok/selection` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.
+- Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file.
+
+### `ocx grok apply`
+
+Usage: `ocx grok apply [--json]`
+
+Apply the saved Grok model fence.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/grok/apply` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.
+- Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file.
+
+### `ocx integration client status`
+
+Usage: `ocx integration client status [--client <id>] [--profile <id>] [--json]`
+
+Read all file integrations, one client or an Aside profile.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/client-integrations` |
+| GET | `/api/client-integrations/{clientId}` |
+| GET | `/api/client-integrations/aside/profiles` |
+| GET | `/api/client-integrations/aside/profiles/{profileId}` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--client` | string | File integration ID; aside selects profiles. |
+| `--profile` | number | Aside nonnegative integer account ID; requires --client aside. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- show and list alias status; omitted Aside profile means the aggregate profile collection.
+
+### `ocx integration client history`
+
+Usage: `ocx integration client history [--client <id>] [--profile <id>] [--json]`
+
+Read integration rollback history and snapshot availability.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/client-integrations/journal` |
+| GET | `/api/client-integrations/aside/profiles/journal` |
+| GET | `/api/client-integrations/aside/profiles/{profileId}/journal` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--client` | string | File integration ID; aside selects profiles. |
+| `--profile` | number | Aside nonnegative integer account ID; requires --client aside. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- journal is an alias. Ordinary client filtering uses ?client=; expired snapshots remain visibly expired.
+
+### `ocx integration client enable`
+
+Usage: `ocx integration client enable --client <id> [--profile <id>] [--overwrite-conflict] [--json]`
+
+Apply the selected managed file integration.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/client-integrations/{clientId}` |
+| PUT | `/api/client-integrations/aside/profiles` |
+| PUT | `/api/client-integrations/aside/profiles/{profileId}` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--client` | string | Explicit file integration ID. |
+| `--profile` | number | Aside nonnegative integer account ID; requires --client aside. |
+| `--overwrite-conflict` | boolean | Explicitly permit replacing a conflicting block. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- An omitted Aside profile toggles all Aside profiles. Ownership, snapshots, journal and conflict refusals remain server-owned.
+- Partial Aside failures remain failures after emitting the per-profile result. Never infer permission to overwrite from a refusal.
+
+### `ocx integration client disable`
+
+Usage: `ocx integration client disable --client <id> [--profile <id>] [--json]`
+
+Disable the selected managed file integration.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/client-integrations/{clientId}` |
+| PUT | `/api/client-integrations/aside/profiles` |
+| PUT | `/api/client-integrations/aside/profiles/{profileId}` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--client` | string | Explicit file integration ID. |
+| `--profile` | number | Aside nonnegative integer account ID; requires --client aside. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- An omitted Aside profile toggles all Aside profiles. Ownership, snapshots, journal and conflict refusals remain server-owned.
+- Partial Aside failures remain failures after emitting the per-profile result. Never infer permission to overwrite from a refusal.
+
+### `ocx integration client restore`
+
+Usage: `ocx integration client restore --op <opId> [--client aside --profile <id>] [--confirm-drift] [--json]`
+
+Restore a selected rollback operation, retaining drift refusal.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/client-integrations/restore` |
+| POST | `/api/client-integrations/aside/profiles/{profileId}/restore` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--op` | string | Operation ID; --op-id is an alias. |
+| `--client` | string | File integration ID; aside selects profiles. |
+| `--profile` | number | Aside nonnegative integer account ID; requires --client aside. |
+| `--confirm-drift` | boolean | Explicitly allow replacing edits made after the snapshot. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- With --client, restore requires --profile; only Aside profiles accept that selector. No automatic drift confirmation or retry.
+
+### `ocx claude config status`
+
+Usage: `ocx claude config status [--json]`
+
+Read effective Claude Code configuration.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/claude-code` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- show is an alias; integration claude forwards to the same handler.
+
+### `ocx claude config set`
+
+Usage: `ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]`
+
+Change Claude Code settings through the runtime owner.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/claude-code` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--enabled` | string | on or off. |
+| `--auth-mode` | string | auto, proxy or subscription. |
+| `--system-env` | string | on or off. |
+| `--fast-mode` | string | on or off. |
+| `--auto-context` | string | on or off. |
+| `--compact-window` | string | Positive token count or default to clear. |
+| `--inject-agents` | string | on or off. |
+| `--small-fast-model` | string | Model ID; - clears. |
+| `--model-map` | string | Comma-separated from=to mappings; - clears. |
+| `--blocked-skills` | string | Comma-separated names; - clears. |
+| `--web-model` | string | Model ID; - clears. |
+| `--web-backend` | string | openai, anthropic, xai, gemini, exa or -. |
+| `--vision-model` | string | Model ID; - clears. |
+| `--vision-backend` | string | openai, anthropic or -. |
+| `--first-party` | string | on or off; must be the only setting. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- At least one setting is required. --first-party must be set alone and writes Claude settings immediately.
+- Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings.
+
+### `ocx claude desktop show`
+
+Usage: `ocx claude desktop show [--json]`
+
+Inspect the desired profile derived on this machine.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local config/catalog derivation, not GET of the remote desired profile. On a connected client scope is local; apply uses the hub profile. Catalog derivation may discover upstream models.
+
+### `ocx claude desktop move`
+
+Usage: `ocx claude desktop move <provider/model> <opus|fable|sonnet|haiku> [--default]`
+
+Move an available route to a local Desktop family.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--default` | boolean | Make this route the family default. |
+
+JSON mode: `none`.
+
+- Local profile persistence only; no management HTTP or --json. On connected clients this does not change the hub profile.
+
+### `ocx claude desktop default`
+
+Usage: `ocx claude desktop default <opus|fable|sonnet|haiku> <provider/model|none>`
+
+Set or clear a local Desktop family default.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local profile persistence only; none clears the default. Connected Desktop apply uses the hub profile.
+
+### `ocx claude desktop export`
+
+Usage: `ocx claude desktop export <path|->`
+
+Export the persisted local Desktop profile.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local file output; - writes JSON to stdout. There is no --json flag. A file destination is overwritten; this is not a GUI draft export.
+
+### `ocx claude desktop import`
+
+Usage: `ocx claude desktop import <path> [--apply]`
+
+Import a local Desktop profile, optionally applying it as a static gateway.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/claude-desktop/apply` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--apply` | boolean | After saving, apply as a static gateway. |
+
+JSON mode: `none`.
+
+- Without --apply this only persists locally. With a live local proxy, gateway apply is delegated by HTTP; otherwise local helpers apply it.
+- Connected clients refuse import --apply. A saved profile can remain saved after application fails; no --json mode.
+
+### `ocx claude desktop apply`
+
+Usage: `ocx claude desktop [apply] [--first-party | --gateway [--static|--hybrid|--discovery-only]]`
+
+Apply Claude Desktop first-party interception or gateway profile.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/claude-desktop/apply` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--first-party` | boolean | Keep Desktop on claude.ai and intercept its Code tab. |
+| `--gateway` | boolean | Apply a third-party gateway profile. |
+| `--static` | boolean | Static gateway model catalog. |
+| `--hybrid` | boolean | Hybrid gateway catalog. |
+| `--discovery-only` | boolean | Discovery-only gateway catalog. |
+
+JSON mode: `none`.
+
+- Uses local helpers or the live local apply route; connected gateway clients use the hub profile download path. No --json mode.
+- First-party requires a local hub with interception enabled. Preserve account-risk warnings, trust prompts and ownership refusals; metadata grants no consent.
+- Application and committed-marker persistence can diverge; inspect status after application and preserve warnings.
+
+### `ocx codex-shim install`
+
+Usage: `ocx codex-shim install`
+
+Local Codex launcher shim install.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local launcher/PATH wrapper operation on macOS, Linux and Windows; no management API or JSON mode.
+- Installation diagnoses wrapper health and reports readiness warnings.
+
+### `ocx codex-shim status`
+
+Usage: `ocx codex-shim status`
+
+Local Codex launcher shim status.
+
+State-changing: no.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local launcher/PATH wrapper operation on macOS, Linux and Windows; no management API or JSON mode.
+- Inspects local launcher wrapper state.
+
+### `ocx codex-shim uninstall`
+
+Usage: `ocx codex-shim uninstall`
+
+Local Codex launcher shim uninstall.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local launcher/PATH wrapper operation on macOS, Linux and Windows; no management API or JSON mode.
+- remove aliases uninstall.
diff --git a/skills/ocx/references/01_surface_lab.md b/skills/ocx/references/01_surface_lab.md
new file mode 100644
index 00000000000..51d0ff23da0
--- /dev/null
+++ b/skills/ocx/references/01_surface_lab.md
@@ -0,0 +1,455 @@
+<!-- GENERATED by scripts/generate-ocx-skill-surface.ts. Do not edit by hand. -->
+<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->
+
+# lab: declared management tasks
+
+[Management index](01_management_surface.md) · [Operating rules](../SKILL.md#secret-bearing-commands)
+
+Use these declarations to choose a task, then check its flags and authority before execution.
+Non-mutating probes may still contact providers, consume quota or refresh caches.
+
+Declared capabilities: 21.
+
+### `ocx lab status`
+
+Usage: `ocx lab status [--json]`
+
+Read local Lab projection status.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+
+### `ocx lab verdicts`
+
+Usage: `ocx lab verdicts [--subject <subject>] [--layer <layer>] [--suite <suite>] [--verdict <verdict>] [--from <ms>] [--to <ms>] [--limit <n>] [--cursor <cursor>] [--json]`
+
+Read local Lab verdicts.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--subject` | string | Exact subject ID. |
+| `--layer` | string | Evidence layer. |
+| `--suite` | string | Suite ID. |
+| `--verdict` | string | Compatibility verdict. |
+| `--from` | number | Inclusive timestamp in milliseconds. |
+| `--to` | number | Timestamp upper bound in milliseconds. |
+| `--limit` | number | Positive page size. |
+| `--cursor` | string | Opaque page cursor. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Read commands do not start probes or scheduler ticks.
+
+### `ocx lab subjects`
+
+Usage: `ocx lab subjects [--kind <kind>] [--limit <n>] [--cursor <cursor>] [--json]`
+
+Read local Lab subjects.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--kind` | string | Subject kind. |
+| `--limit` | number | Positive page size. |
+| `--cursor` | string | Opaque page cursor. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Read commands do not start probes or scheduler ticks.
+
+### `ocx lab observations`
+
+Usage: `ocx lab observations [--subject <subject>] [--layer <layer>] [--suite <suite>] [--scenario <scenario>] [--outcome <outcome>] [--execution-mode <execution-mode>] [--from <ms>] [--to <ms>] [--limit <n>] [--cursor <cursor>] [--json]`
+
+Read local Lab observations.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--subject` | string | Exact subject ID. |
+| `--layer` | string | Evidence layer. |
+| `--suite` | string | Suite ID. |
+| `--scenario` | string | Scenario ID. |
+| `--outcome` | string | Observation outcome. |
+| `--execution-mode` | string | Execution mode. |
+| `--from` | number | Inclusive timestamp in milliseconds. |
+| `--to` | number | Timestamp upper bound in milliseconds. |
+| `--limit` | number | Positive page size. |
+| `--cursor` | string | Opaque page cursor. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Read commands do not start probes or scheduler ticks.
+
+### `ocx lab events`
+
+Usage: `ocx lab events [--event-kind <event-kind>] [--subject <subject>] [--from <ms>] [--to <ms>] [--excluded <true|false>] [--limit <n>] [--cursor <cursor>] [--json]`
+
+Read local Lab events.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--event-kind` | string | Event kind. |
+| `--subject` | string | Exact subject ID. |
+| `--from` | number | Inclusive timestamp in milliseconds. |
+| `--to` | number | Timestamp upper bound in milliseconds. |
+| `--excluded` | string | true or false; takes a value. |
+| `--limit` | number | Positive page size. |
+| `--cursor` | string | Opaque page cursor. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Read commands do not start probes or scheduler ticks.
+
+### `ocx lab artifacts`
+
+Usage: `ocx lab artifacts [--status <status>] [--artifact-class <artifact-class>] [--limit <n>] [--cursor <cursor>] [--json]`
+
+Read local Lab artifacts.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--status` | string | present, corrupt or purged_unavailable. |
+| `--artifact-class` | string | Artifact class. |
+| `--limit` | number | Positive page size. |
+| `--cursor` | string | Opaque page cursor. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Read commands do not start probes or scheduler ticks.
+
+### `ocx lab catalog`
+
+Usage: `ocx lab catalog [--layer <layer>] [--suite <suite>] [--json]`
+
+Read local Lab catalog.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--layer` | string | Evidence layer. |
+| `--suite` | string | Suite ID. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Read commands do not start probes or scheduler ticks.
+
+### `ocx lab subject`
+
+Usage: `ocx lab subject <subjectId> [--json]`
+
+Inspect one local Lab subject.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+
+### `ocx lab event`
+
+Usage: `ocx lab event <eventId> [--json]`
+
+Inspect one local Lab event.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+
+### `ocx lab artifact`
+
+Usage: `ocx lab artifact <digest> [--json]`
+
+Inspect one local Lab artifact.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+
+### `ocx lab production-signals`
+
+Usage: `ocx lab production-signals --subject <id> [--limit <n>] [--json]`
+
+Read passive production context for one exact Lab route subject.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--subject` | string | Exact Lab route subject ID. |
+| `--limit` | number | Positive page size. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Passive production context is not verification evidence.
+
+### `ocx lab public preview`
+
+Usage: `ocx lab public preview --event <eventId> [--event <eventId> ...] [--json]`
+
+Preview unsigned local public evidence.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--event` | string | Event ID; repeat for multiple records. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- No remote publishing occurs. Preview creates no publisher key; export can create local signing identity and bundle files.
+
+### `ocx lab public export`
+
+Usage: `ocx lab public export --event <eventId> [--event <eventId> ...] [--json]`
+
+Export signed local public evidence.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--event` | string | Event ID; repeat for multiple records. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- No remote publishing occurs. Preview creates no publisher key; export can create local signing identity and bundle files.
+
+### `ocx lab public verify`
+
+Usage: `ocx lab public verify --file <bundle.json> [--json]`
+
+Verify a public evidence file.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--file` | string | Public evidence bundle path. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Signature validity proves integrity/continuity, not local verification.
+- A verification failure emits its structured summary and then returns nonzero.
+
+### `ocx lab public import`
+
+Usage: `ocx lab public import --file <bundle.json> [--json]`
+
+Import public evidence as untrusted community context.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--file` | string | Public evidence bundle path. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Signature validity proves integrity/continuity, not local verification.
+- Imported community evidence never becomes locally verified evidence.
+
+### `ocx lab public community`
+
+Usage: `ocx lab public community [--json]`
+
+List local untrusted community evidence context.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+
+### `ocx lab automation status`
+
+Usage: `ocx lab automation [status] [--json]`
+
+Read local automation policy, queue and run state.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+
+### `ocx lab automation enable`
+
+Usage: `ocx lab automation enable [--protocol] [--live] [--json]`
+
+Enable local Lab automation layers.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--protocol` | boolean | Select protocol conformance. |
+| `--live` | boolean | Select live route compatibility; may spend upstream quota. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- These flags already exist in the local handler. With neither flag, preserve current layer selection; with either flag, select only requested layers.
+- Persists local policy, reconciles the queue and starts a scheduler in this CLI process; this is not a remote scheduler control API. Task-effectiveness background remains disabled.
+
+### `ocx lab automation disable`
+
+Usage: `ocx lab automation disable [--json]`
+
+Disable local Lab automation.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- Persists disabled policy, reconciles the local queue and stops this process scheduler.
+
+### `ocx lab automation runs`
+
+Usage: `ocx lab automation runs [--limit <n>] [--cursor <c>] [--json]`
+
+List locally persisted automation runs.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--limit` | number | Positive page size. |
+| `--cursor` | string | Opaque page cursor. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+
+### `ocx lab run`
+
+Usage: `ocx lab run --layer <protocol_conformance|live_route_compatibility|task_effectiveness> --scenario <id> [--provider <name>] [--model <id>] [--json]`
+
+Plan and enqueue an explicit local Lab run.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--layer` | string | Evidence layer. |
+| `--scenario` | string | Scenario ID. |
+| `--provider` | string | Configured provider name. |
+| `--model` | string | Model ID. |
+| `--json` | boolean | Emit the local result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.
+- The live-route layer installs a production route executor and can spend upstream quota. Explicit operator authorization is required for probes.
+- An enqueued run receipt is not a completed verification. No run-cancel or full policy/routes editor is claimed.
diff --git a/skills/ocx/references/01_surface_lifecycle.md b/skills/ocx/references/01_surface_lifecycle.md
new file mode 100644
index 00000000000..e8aa0b21a9d
--- /dev/null
+++ b/skills/ocx/references/01_surface_lifecycle.md
@@ -0,0 +1,204 @@
+<!-- GENERATED by scripts/generate-ocx-skill-surface.ts. Do not edit by hand. -->
+<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->
+
+# lifecycle: declared management tasks
+
+[Management index](01_management_surface.md) · [Operating rules](../SKILL.md#secret-bearing-commands)
+
+Use these declarations to choose a task, then check its flags and authority before execution.
+Non-mutating probes may still contact providers, consume quota or refresh caches.
+
+Declared capabilities: 12.
+
+### `ocx chatgpt`
+
+Experimental ChatGPT app-server shim: launch, restore or status (macOS only).
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Default off; launch requires chatgptDesktop.appServerShim: true. Restore removes the generated launcher.
+
+### `ocx status`
+
+Proxy status, injection state, and version skew between this CLI and the running proxy.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the status envelope as JSON. |
+
+JSON mode: `envelope`.
+
+- Reads /healthz plus local config; drives no management API route.
+
+### `ocx resolve`
+
+One JSON document naming the config home, the effective port, and the identity-checked proxy liveness verdict.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the resolve document as JSON (the shell contract). |
+
+JSON mode: `envelope`.
+
+- Exit 0 carries a trustworthy verdict (live or proven absent); exit 1 means the CLI could not resolve and a caller must refuse to guess — unknown liveness never reads as absent.
+- Built for embedding shells (desktop app): the liveness budgets stay owned by src/server/proxy-liveness.ts.
+
+### `ocx capabilities`
+
+List the declared CLI capabilities and the management routes they drive.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the full capability table as JSON. |
+| `--mutating-only` | boolean | Restrict output to capabilities that mutate state. |
+| `--route` | string | Show which capabilities drive a management route. |
+
+JSON mode: `envelope`.
+
+- Start here when driving ocx programmatically: it is the declared surface index, not a complete verb list.
+
+### `ocx sync`
+
+Synchronize client catalogs, including Aside profiles through the running server's mutation owner.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/client-integrations/aside/sync` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--restart-codex` | boolean | Restart the Codex app-servers and fully quit and relaunch the Codex desktop app after a catalog or cache write, on macOS, Linux and Windows. |
+| `--restart-app-server-only` | boolean | Restart only the Codex app-servers and leave the desktop app running; wins over --restart-codex when both are given. |
+| `--restart-desktop-app` | boolean | Deprecated alias of --restart-codex. |
+
+JSON mode: `none`.
+
+- The Aside refresh uses the live server; other catalog synchronization also performs local work.
+
+### `ocx service install`
+
+Usage: `ocx service install [--native|--scheduler]`
+
+Install the local background service.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--native` | boolean | Windows WinSW backend; exclusive with --scheduler. |
+| `--scheduler` | boolean | Scheduled backend; exclusive with --native. |
+
+JSON mode: `none`.
+
+- Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.
+- Backend options apply only to install; other verbs use the installed backend.
+
+### `ocx service repair`
+
+Usage: `ocx service repair`
+
+Repair local service registration and verify serving health.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.
+- Backend options apply only to install; other verbs use the installed backend.
+
+### `ocx service restart`
+
+Usage: `ocx service restart`
+
+Restart the local background service.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.
+- Backend options apply only to install; other verbs use the installed backend.
+
+### `ocx service start`
+
+Usage: `ocx service start`
+
+Start the registered local service.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.
+- Backend options apply only to install; other verbs use the installed backend.
+
+### `ocx service stop`
+
+Usage: `ocx service stop`
+
+Stop the registered local service.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.
+- Backend options apply only to install; other verbs use the installed backend.
+
+### `ocx service status`
+
+Usage: `ocx service status`
+
+Inspect local service-manager status.
+
+State-changing: no.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.
+- Backend options apply only to install; other verbs use the installed backend.
+
+### `ocx service uninstall`
+
+Usage: `ocx service uninstall`
+
+Uninstall the local service.
+
+State-changing: yes.
+
+Drives no management route.
+
+JSON mode: `none`.
+
+- Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.
+- remove is an alias for uninstall.
diff --git a/skills/ocx/references/01_surface_observe-system.md b/skills/ocx/references/01_surface_observe-system.md
new file mode 100644
index 00000000000..5b4e5d62120
--- /dev/null
+++ b/skills/ocx/references/01_surface_observe-system.md
@@ -0,0 +1,1724 @@
+<!-- GENERATED by scripts/generate-ocx-skill-surface.ts. Do not edit by hand. -->
+<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->
+
+# observe-system: declared management tasks
+
+[Management index](01_management_surface.md) · [Operating rules](../SKILL.md#secret-bearing-commands)
+
+Use these declarations to choose a task, then check its flags and authority before execution.
+Non-mutating probes may still contact providers, consume quota or refresh caches.
+
+Declared capabilities: 87.
+
+### `ocx companion`
+
+Usage: `ocx companion show [--json] | ocx companion set <key>=<value> [...] [--json] | ocx companion reset [--json]`
+
+Inspect and configure menu-bar and widget companion usage settings.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/companion/settings` |
+| PUT | `/api/companion/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit companion settings as JSON. |
+
+JSON mode: `payload`.
+
+- Mixed family: show/default reads settings; set key=value assignments and reset write settings.
+- Values are parsed as JSON when valid; timeline is not implemented by this handler.
+
+### `ocx usage`
+
+Usage: `ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>] [--provider <name>] [--model <id>] [--json]`
+
+Token and estimated-cost report over a time range.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/usage` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--range` | string | today \| 1d \| 7d \| 30d \| all; default 30d. |
+| `--surface` | string | all \| codex \| claude \| grok; default all. |
+| `--since` | string | Inclusive epoch milliseconds or ISO datetime with timezone; requires --until. |
+| `--until` | string | Inclusive end; requires --since. Custom bounds override --range. |
+| `--provider` | string | Filter provider. |
+| `--model` | string | Filter model. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Alias of observe usage. Connected clients instead read their own enrolled-key Hub report through /v1/usage; this is not whole-Hub management usage.
+- Custom bounds require the server to confirm customWindow, since and until.
+
+### `ocx logs`
+
+Usage: `ocx logs [--provider <name>] [--model <id>] [--status <code>] [--conversation <id>] [--account <label>] [--limit <n>] [--follow] [--json|--jsonl]`
+
+Recent request log rows, filterable by provider, model, conversation, account, and status.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/logs` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--provider` | string | Filter provider, including failover attempts. |
+| `--model` | string | Filter model, including failover attempts. |
+| `--status` | string | Filter status code. |
+| `--conversation` | string | Filter conversation ID. |
+| `--conversationId` | string | Alias of --conversation. |
+| `--account` | string | Filter stable account log label. |
+| `--limit` | number | Positive row limit; default 200. |
+| `--follow` | boolean | Poll for new rows; add --jsonl to emit JSONL. |
+| `-f` | boolean | Alias of --follow. |
+| `--json` | boolean | Emit the result as JSON. |
+| `--jsonl` | boolean | Emit one row per JSON line; exclusive with --json. |
+
+JSON mode: `payload`.
+
+- Snapshot read or follow; --follow refuses --json and supports --jsonl. --conversationId and -f are accepted aliases.
+- Nested explain reads recorded decisions; rebuild-index and index-status touch the local derived index and have separate declarations.
+
+### `ocx storage report`
+
+Usage: `ocx storage report [--json]`
+
+Disk usage under CODEX_HOME, with the log-guard protection report.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/storage` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the storage report as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx storage cleanup`
+
+Usage: `ocx storage cleanup --percent <0-100> [--mode <quarantine|permanent>] [--yes] [--json]`
+
+Preview or delete the oldest archived sessions by percentage.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/storage/cleanup/preview` |
+| POST | `/api/storage/cleanup` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--percent` | number | Portion of the oldest archived sessions to target (0-100). |
+| `--mode` | string | quarantine (recoverable from trash) or permanent. |
+| `--yes` | boolean | Required to actually delete; without it this is a preview. |
+| `--json` | boolean | Emit the preview or result as JSON. |
+
+JSON mode: `payload`.
+
+- Without `--yes` it prints what WOULD be freed and exits 0 having changed nothing.
+- There is no interactive confirmation: a prompt an agent can answer is not a safety boundary.
+- `--mode quarantine` moves files to trash, so `storage trash restore` can undo it; `permanent` cannot be undone.
+
+### `ocx storage trash`
+
+Usage: `ocx storage trash [list] [--json] | ocx storage trash restore <entry-id> --yes [--json]`
+
+List quarantined cleanup batches, or restore one.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/storage/trash` |
+| POST | `/api/storage/trash/restore` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Required for restore, which moves files and reconciles database rows. |
+| `--json` | boolean | Emit the trash list or restore result as JSON. |
+
+JSON mode: `payload`.
+
+- Restore fails with a named 409 when the destination already exists, rather than overwriting it.
+- Mixed family: list/default reads quarantine batches; restore moves files and reconciles database rows only with --yes.
+
+### `ocx storage policy`
+
+Usage: `ocx storage policy [show] [--json] | ocx storage policy set [--enabled <true|false>] [--percent <1-100>] [--mode <quarantine|permanent>] [--schedule <startup|daily|weekly|manual>] [--json] | ocx storage policy run --yes [--json]`
+
+Show, change, or run the automatic archived-session cleanup policy.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/storage/cleanup-policy` |
+| PUT | `/api/storage/cleanup-policy` |
+| POST | `/api/storage/cleanup-policy/run` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--enabled` | string | true or false. |
+| `--percent` | number | Portion of oldest archived sessions each run targets. |
+| `--mode` | string | quarantine or permanent. |
+| `--schedule` | string | startup, daily, weekly, or manual. |
+| `--yes` | boolean | Required for `policy run`, which deletes immediately. |
+| `--json` | boolean | Emit the policy or run state as JSON. |
+
+JSON mode: `payload`.
+
+- `policy set` never enables implicitly: omitting `--enabled` keeps the stored value.
+- `policy run` forces a run regardless of schedule, so it needs `--yes`.
+- Mixed family: show/default reads; set persists submitted fields; run requires --yes and starts immediate cleanup. At least one setting is required by set.
+
+### `ocx inspect config`
+
+The effective merged configuration the proxy is running.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/config` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the config as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx inspect catalog`
+
+The generated model catalog served to clients.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/catalog` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the catalog as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx inspect routing-analytics`
+
+Aggregate routing outcomes per provider and model.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/routing-analytics` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the analytics payload as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx inspect pacing`
+
+Request-pacing state for one provider or all of them.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/provider-request-pacing` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--name` | string | Restrict to one provider; omitted means every provider. |
+| `--json` | boolean | Emit the pacing state as JSON. |
+
+JSON mode: `payload`.
+
+- An unknown provider name is a 404 rather than an empty result.
+
+### `ocx inspect key-providers`
+
+Providers that authenticate with an API key rather than OAuth.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/key-providers` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the provider list as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx inspect codex-prompt`
+
+The Codex system prompt state, or the prompt text itself.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/codex-prompt` |
+| GET | `/api/codex-prompt/text` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--text` | boolean | Print the prompt body verbatim instead of its metadata. |
+| `--json` | boolean | Emit the prompt metadata as JSON. |
+
+JSON mode: `payload`.
+
+- Read-only by design: the six mutating prompt routes require a dashboard session.
+
+### `ocx inspect client-config`
+
+The generated configuration snippet for a supported client.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/client-config` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--client` | string | Required client id; the route names every accepted value on error. |
+| `--json` | boolean | Emit the snippet payload as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx inspect star`
+
+Whether this repository is starred by the signed-in GitHub account.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/github/star` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the star status as JSON. |
+
+JSON mode: `payload`.
+
+- Starring is never available from the CLI; the verb says so rather than offering a flag that cannot work.
+
+### `ocx inspect windows-tray`
+
+Windows tray helper state.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/windows-tray` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the tray state as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx system codex-app-server`
+
+Usage: `ocx system codex-app-server [--json]`
+
+Codex app-server reachability and process state, as the dashboard sees it.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/system/codex-app-server` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the app-server state as JSON. |
+
+JSON mode: `payload`.
+
+- The GUI reads this state directly; without a verb an agent could not tell whether the Codex app-server was reachable at all.
+
+### `ocx system codex-cli-update check`
+
+Usage: `ocx system codex-cli-update check [--json]`
+
+Inspect a configured Codex CLI candidate and its ownership provenance.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the redacted provenance report as JSON. |
+
+JSON mode: `envelope`.
+
+- Proof-bound published-launcher context authenticates the configured candidate snapshot, not successful Codex execution; this check does not attest or admit a selected runtime.
+- On Windows this first slice performs no candidate or configuration filesystem I/O: only a proof-captured absolute environment candidate can receive lexical app-bundle or version-manager labels; every other Windows candidate fails closed.
+- Makes no package-registry request.
+- Does not execute Codex or npm, install or repair software, control a process, or write configuration or cache state.
+
+### `ocx system codex-cli-update attest`
+
+Usage: `ocx system codex-cli-update attest [--candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path>] [--json]`
+
+Observe the selected or explicitly named Windows npm Codex installation files without enabling updates.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--candidate` | string | Absolute npm codex.cmd or package bin/codex.js path; all four paths are all-or-none. |
+| `--npm-prefix` | string | Absolute prefix containing node_modules/@openai/codex. |
+| `--npm-cli` | string | Absolute node_modules/npm/bin/npm-cli.js path. |
+| `--node` | string | Absolute node.exe path; observed, never executed. |
+| `--json` | boolean | Emit the path-free installation identity observation. |
+
+JSON mode: `envelope`.
+
+- Opt-in Windows x64 local-volume inspection using held native file handles; refuses reparse points, active writers and unsupported layouts.
+- Without explicit paths, the proof-bound launcher snapshot identifies the selected candidate: the configured CODEX_CLI_PATH or the first codex on the captured PATH, with an OpenCodex wrapper resolving to its codex.opencodex-real backing. Discovery only proposes paths; the held-handle observation remains the authority.
+- Success binds observed file identities and bytes, not selected-runtime admission or installer ownership.
+- selectionAttested, managed and applyAllowed remain false. The digest is an observation, not a durable update permit.
+- Does not run the named Codex/npm/Node files, query a registry, install software, control processes or persist state.
+
+### `ocx system codex-restart`
+
+Usage: `ocx system codex-restart --yes [--json]`
+
+Restart the Codex desktop app and app-servers.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/system/codex-restart` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Required: fully quits and relaunches the operator's Codex desktop app, which may discard unsaved composer drafts, model-picker selections, and pending approval prompts; also restarts its app-servers. |
+| `--json` | boolean | Emit the restart result as JSON. |
+
+JSON mode: `payload`.
+
+- `sync --restart-codex` is not a substitute: it restarts only as a side effect after a catalog or cache write, so it cannot restart a healthy install on request.
+- Restarts the Codex desktop app as well as the app-servers, through the same module the CLI uses. When the proxy itself runs inside the Codex app it refuses instead, because restarting the app would kill the request.
+- --yes is mandatory because this interrupts a running editor session and may discard unsaved composer drafts, model-picker selections, and pending approval prompts; it must never happen because an agent guessed a subcommand.
+
+### `ocx observe logs`
+
+Usage: `ocx observe logs [--provider <name>] [--model <id>] [--status <code>] [--conversation <id>] [--account <label>] [--limit <n>] [--follow] [--json|--jsonl]`
+
+Read or follow request logs.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/logs` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--provider` | string | Filter provider, including failover attempts. |
+| `--model` | string | Filter model, including failover attempts. |
+| `--status` | string | Filter status code. |
+| `--conversation` | string | Filter conversation ID. |
+| `--conversationId` | string | Alias of --conversation. |
+| `--account` | string | Filter stable account log label. |
+| `--limit` | number | Positive row limit; default 200. |
+| `--follow` | boolean | Poll once per second; use --jsonl for streaming. |
+| `-f` | boolean | Alias of --follow. |
+| `--json` | boolean | Emit the result as JSON. |
+| `--jsonl` | boolean | Emit one row per JSON line; exclusive with --json. |
+
+JSON mode: `payload`.
+
+- Also available as logs. --follow refuses --json; streaming deduplicates by row ID, not row revisions.
+
+### `ocx logs explain`
+
+Usage: `ocx logs explain <request-id> [--json]`
+
+Explain the recorded routing decision for one request.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/request-history/{id}/route-decision` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- The request ID is URI-encoded; this reads an existing decision and sends no model request.
+- Also accepted after observe logs.
+
+### `ocx logs rebuild-index`
+
+Usage: `ocx logs rebuild-index [--json]`
+
+Rebuild the local request-history index.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Local derived SQLite index rebuild from the canonical ledger; no management API request.
+- Also accepted after observe logs.
+
+### `ocx logs index-status`
+
+Usage: `ocx logs index-status [--json]`
+
+Read and refresh local request-history index metadata.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Local index open may create, ingest or rebuild the derived SQLite index; this is not a write-free file inspection.
+- Also accepted after observe logs.
+
+### `ocx observe usage`
+
+Usage: `ocx observe usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>] [--provider <name>] [--model <id>] [--json]`
+
+Read token and estimated-cost usage.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/usage` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--range` | string | today \| 1d \| 7d \| 30d \| all; default 30d. |
+| `--surface` | string | all \| codex \| claude \| grok; default all. |
+| `--since` | string | Inclusive epoch milliseconds or ISO datetime with timezone; requires --until. |
+| `--until` | string | Inclusive end; requires --since. Custom bounds override --range. |
+| `--provider` | string | Filter provider. |
+| `--model` | string | Filter model. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Also available as ocx usage. Connected clients read their own enrolled-key Hub report through /v1/usage; this is not whole-Hub management usage.
+- Custom bounds require the server to confirm customWindow, since and until.
+
+### `ocx observe storage`
+
+Usage: `ocx observe storage [--limit <n>] [--json]`
+
+Read storage diagnostics.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/storage` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--limit` | number | Positive limit forwarded to the endpoint; endpoint semantics apply. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Reads the running proxy management API.
+
+### `ocx observe memory`
+
+Usage: `ocx observe memory [--limit <n>] [--json]`
+
+Read memory diagnostics.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/system/memory` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--limit` | number | Positive limit forwarded to the endpoint; endpoint semantics apply. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Reads the running proxy management API.
+
+### `ocx observe debug`
+
+Usage: `ocx observe debug [--limit <n>] [--json]`
+
+Read debug diagnostics.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--limit` | number | Positive limit forwarded to the endpoint; endpoint semantics apply. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Reads the running proxy management API.
+
+### `ocx observe claude-inbound`
+
+Usage: `ocx observe claude-inbound [--limit <n>] [--json]`
+
+Read claude-inbound diagnostics.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/claude/inbound-debug` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--limit` | number | Positive limit forwarded to the endpoint; endpoint semantics apply. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Snapshot read; no follow or cursor option.
+
+### `ocx observe injection`
+
+Usage: `ocx observe injection [--limit <n>] [--json]`
+
+Read injection diagnostics.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug/injection-logs` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--limit` | number | Positive limit forwarded to the endpoint; endpoint semantics apply. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Snapshot read; no follow or cursor option.
+
+### `ocx storage codex-logs status`
+
+Usage: `ocx storage codex-logs status [--json]`
+
+Inspect Codex Log Guard state.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/storage/codex-logs` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Also accepted after observe storage codex-logs. Omitted action defaults to status.
+
+### `ocx storage codex-logs protect`
+
+Usage: `ocx storage codex-logs protect [--mode <compat|quiet>] [--json]`
+
+Protect Codex logs in compat or quiet mode.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/storage/codex-logs/protect` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--mode` | string | compat \| quiet; default compat. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Also accepted after observe storage codex-logs. Mutates logs or their protection immediately; this handler has no --yes option.
+
+### `ocx storage codex-logs unprotect`
+
+Usage: `ocx storage codex-logs unprotect [--json]`
+
+Remove Codex log protection.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/storage/codex-logs/unprotect` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Also accepted after observe storage codex-logs. Mutates logs or their protection immediately; this handler has no --yes option.
+
+### `ocx storage codex-logs repair`
+
+Usage: `ocx storage codex-logs repair [--json]`
+
+Repair Codex log protection.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/storage/codex-logs/repair` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Also accepted after observe storage codex-logs. Mutates logs or their protection immediately; this handler has no --yes option.
+
+### `ocx storage codex-logs compact`
+
+Usage: `ocx storage codex-logs compact [--json]`
+
+Compact Codex logs.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/storage/codex-logs/compact` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Also accepted after observe storage codex-logs. Mutates logs or their protection immediately; this handler has no --yes option.
+
+### `ocx storage trash list`
+
+Usage: `ocx storage trash list [--json]`
+
+Read quarantine batches.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/storage/trash` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx storage policy show`
+
+Usage: `ocx storage policy show [--json]`
+
+Read cleanup policy and job state.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/storage/cleanup-policy` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx storage trash restore`
+
+Usage: `ocx storage trash restore <entry-id> --yes [--json]`
+
+Restore one quarantined session batch.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/storage/trash/restore` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Required confirmation before restoring stored sessions. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Moves files and reconciles database rows; partial outcomes remain in the response.
+
+### `ocx storage policy set`
+
+Usage: `ocx storage policy set [--enabled <true|false>] [--percent <1-100>] [--mode <quarantine|permanent>] [--schedule <startup|daily|weekly|manual>] [--json]`
+
+Save submitted cleanup policy fields.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/storage/cleanup-policy` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--enabled` | string | true \| false. |
+| `--percent` | number | Oldest archived-session percentage; server validates the 1-100 policy range. |
+| `--mode` | string | quarantine \| permanent. |
+| `--schedule` | string | startup \| daily \| weekly \| manual. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- At least one setting is required. Percent writes target.removeOldestPercent; mode, schedule and range validation belong to the server.
+
+### `ocx storage policy run`
+
+Usage: `ocx storage policy run --yes [--json]`
+
+Run the stored cleanup policy immediately.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/storage/cleanup-policy/run` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Required confirmation for immediate archived-session cleanup. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Run acceptance is not completion; inspect storage policy show for job state.
+
+### `ocx debug provider`
+
+Usage: `ocx debug provider [status|on|off|reset]`
+
+Read or change the provider debug override.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug` |
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Mixed family: omitted action/status reads; on/off/reset change runtime overrides. No JSON mode.
+- Reset follows the environment default. Logs have a separate child command.
+
+### `ocx debug provider status`
+
+Usage: `ocx debug provider status`
+
+Read provider debug state.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug provider on`
+
+Usage: `ocx debug provider on`
+
+Set provider debug override on.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug provider off`
+
+Usage: `ocx debug provider off`
+
+Set provider debug override off.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug provider reset`
+
+Usage: `ocx debug provider reset`
+
+Set provider debug override reset.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug provider logs`
+
+Usage: `ocx debug provider logs [-f|--follow]`
+
+Read or follow provider debug log lines.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug/logs` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `-f` | boolean | Follow new sequence numbers. |
+| `--follow` | boolean | Alias of -f. |
+
+JSON mode: `none`.
+
+- Text lines only; initial limit 500, then sequence-based polling.
+
+### `ocx debug usage`
+
+Usage: `ocx debug usage [status|on|off|reset]`
+
+Read or change the usage debug override.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug` |
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Mixed family: omitted action/status reads; on/off/reset change runtime overrides. No JSON mode.
+- Reset follows the environment default. Logs have a separate child command.
+
+### `ocx debug usage status`
+
+Usage: `ocx debug usage status`
+
+Read usage debug state.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug usage on`
+
+Usage: `ocx debug usage on`
+
+Set usage debug override on.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug usage off`
+
+Usage: `ocx debug usage off`
+
+Set usage debug override off.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug usage reset`
+
+Usage: `ocx debug usage reset`
+
+Set usage debug override reset.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug usage logs`
+
+Usage: `ocx debug usage logs [-f|--follow]`
+
+Read or follow usage debug log lines.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug/usage-logs` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `-f` | boolean | Follow new sequence numbers. |
+| `--follow` | boolean | Alias of -f. |
+
+JSON mode: `none`.
+
+- Text lines only; initial limit 500, then sequence-based polling.
+
+### `ocx debug injection`
+
+Usage: `ocx debug injection [status|on|off|reset]`
+
+Read or change the injection debug override.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug` |
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Mixed family: omitted action/status reads; on/off/reset change runtime overrides. No JSON mode.
+- Reset follows the environment default. Buffered reads use observe injection.
+
+### `ocx debug injection status`
+
+Usage: `ocx debug injection status`
+
+Read injection debug state.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug injection on`
+
+Usage: `ocx debug injection on`
+
+Set injection debug override on.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug injection off`
+
+Usage: `ocx debug injection off`
+
+Set injection debug override off.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug injection reset`
+
+Usage: `ocx debug injection reset`
+
+Set injection debug override reset.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug claude`
+
+Usage: `ocx debug claude [status|on|off|reset]`
+
+Read or change the claude debug override.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug` |
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Mixed family: omitted action/status reads; on/off/reset change runtime overrides. No JSON mode.
+- Reset follows the environment default. Buffered reads use observe claude-inbound.
+
+### `ocx debug claude status`
+
+Usage: `ocx debug claude status`
+
+Read claude debug state.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug claude on`
+
+Usage: `ocx debug claude on`
+
+Set claude debug override on.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug claude off`
+
+Usage: `ocx debug claude off`
+
+Set claude debug override off.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx debug claude reset`
+
+Usage: `ocx debug claude reset`
+
+Set claude debug override reset.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/debug` |
+
+JSON mode: `none`.
+
+- Requires a running proxy; legacy text output only.
+
+### `ocx system status`
+
+Usage: `ocx system status [--json]`
+
+Read settings, startup health and memory together.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/settings` |
+| GET | `/api/startup-health` |
+| GET | `/api/system/memory` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Default system action. The CLI bundles three payloads; this does not call /api/system/health.
+
+### `ocx system settings`
+
+Usage: `ocx system settings [--auto-start <on|off>] [--stream-mode <auto|legacy-tee|eager-relay>] [--desktop-authless <on|off>] [--client-compaction <on|off>] [--json]`
+
+Read or update supported runtime settings.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/settings` |
+| PUT | `/api/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--auto-start` | string | on \| off for Codex autostart. |
+| `--stream-mode` | string | auto \| legacy-tee \| eager-relay. |
+| `--desktop-authless` | string | on \| off for Codex Desktop authless. |
+| `--client-compaction` | string | on \| off for native replay portability; summaries may consume provider quota. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Mixed read/write: no setting flags reads; setting flags write only submitted fields. Stored, effective and config-apply states can differ.
+
+### `ocx system startup health`
+
+Usage: `ocx system startup health [--json]`
+
+Read startup protection.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/startup-health` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- health is the default; status is its alias.
+
+### `ocx system startup install-service`
+
+Usage: `ocx system startup install-service [--json]`
+
+Request startup install-service.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/startup-action` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- The server invokes the platform-local service repair or shim installation and reports its outcome.
+
+### `ocx system startup install-shim`
+
+Usage: `ocx system startup install-shim [--json]`
+
+Request startup install-shim.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/startup-action` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- The server invokes the platform-local service repair or shim installation and reports its outcome.
+
+### `ocx system diagnostics`
+
+Usage: `ocx system diagnostics [--json]`
+
+Read project-config diagnostics.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/diagnostics/project-config` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Runs against the serving proxy; inspect the returned saved/applied or failure result.
+
+### `ocx system sync`
+
+Usage: `ocx system sync [--json]`
+
+Synchronize client catalogs and configuration.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/sync` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Runs against the serving proxy; inspect the returned saved/applied or failure result.
+
+### `ocx system update check`
+
+Usage: `ocx system update check [--channel <latest|preview>] [--json]`
+
+Check the package update channel.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/update/check` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--channel` | string | latest \| preview; default latest. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Checks registry availability; does not install.
+
+### `ocx system update run`
+
+Usage: `ocx system update run [--channel <latest|preview>] [--restart <on|off>] --yes [--json]`
+
+Start a package update job.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/update/run` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--channel` | string | latest \| preview; default latest. |
+| `--restart` | string | on \| off; default on. |
+| `--yes` | boolean | Required confirmation for package update. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Installs software and may restart the proxy. Acceptance is not completion; inspect system update status with the returned job ID.
+
+### `ocx system update status`
+
+Usage: `ocx system update status <job-id> [--json]`
+
+Read one package update job.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/update/status` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+### `ocx config show`
+
+Usage: `ocx config show [--json] [--source]`
+
+Local configuration show.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--source` | boolean | Include source diagnostics. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local config/file operation; no management API request or automatic live convergence.
+- Displayed credential values are masked.
+- Always emits JSON; --source wraps config with source/error/warnings. Default action when omitted.
+
+### `ocx config get`
+
+Usage: `ocx config get <dot.path> [--json]`
+
+Local configuration get.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Local config/file operation; no management API request or automatic live convergence.
+- Displayed credential values are masked.
+
+### `ocx config set`
+
+Usage: `ocx config set <dot.path> <json-or-string> [--json]`
+
+Local configuration set.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local config/file operation; no management API request or automatic live convergence.
+- Displayed credential values are masked.
+
+### `ocx config unset`
+
+Usage: `ocx config unset <dot.path> [--json]`
+
+Local configuration unset.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local config/file operation; no management API request or automatic live convergence.
+
+### `ocx config validate`
+
+Usage: `ocx config validate [path|-] [--json]`
+
+Local configuration validate.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local config/file operation; no management API request or automatic live convergence.
+
+### ocx config export
+
+Human-only handoff: ask the operator to perform this in their own terminal or dashboard; do not capture the secret-bearing result.
+
+Human-only raw configuration export handoff.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Local config/file operation; no management API request or automatic live convergence.
+- Human-only secret-bearing export: raw credentials are included. Keep the file and stdout out of agent transcripts. --json is accepted but does not alter this raw export.
+
+### `ocx config import`
+
+Usage: `ocx config import <path|-> --yes [--json]`
+
+Local configuration import.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Required confirmation before replacing local config. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local config/file operation; no management API request or automatic live convergence.
+- Replaces local configuration after schema validation; requires --yes. Restart or explicitly sync if needed.
+
+### `ocx companion show`
+
+Usage: `ocx companion show [--json]`
+
+Read companion settings, defaults and presence.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/companion/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Settings only; no usage timeline request.
+
+### `ocx companion set`
+
+Usage: `ocx companion set <key>=<value> [...] [--json]`
+
+Save selected companion settings.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/companion/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Values are parsed as JSON when valid, otherwise as strings.
+
+### `ocx companion reset`
+
+Usage: `ocx companion reset [--json]`
+
+Restore companion defaults.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/companion/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `payload`.
+
+- Settings only; no usage timeline request.
+
+### `ocx tray install`
+
+Usage: `ocx tray install [--no-start] [--json]`
+
+Windows tray install.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--no-start` | boolean | Install without starting the tray. |
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.
+- Lifecycle writes require Windows.
+
+### `ocx tray start`
+
+Usage: `ocx tray start [--json]`
+
+Windows tray start.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.
+- Lifecycle writes require Windows.
+
+### `ocx tray stop`
+
+Usage: `ocx tray stop [--json]`
+
+Windows tray stop.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.
+- Lifecycle writes require Windows.
+
+### `ocx tray status`
+
+Usage: `ocx tray status [--json]`
+
+Windows tray status.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.
+- Lifecycle writes require Windows.
+
+### `ocx tray uninstall`
+
+Usage: `ocx tray uninstall [--json]`
+
+Windows tray uninstall.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the result as JSON. |
+
+JSON mode: `envelope`.
+
+- Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.
+- remove aliases uninstall.
diff --git a/skills/ocx/references/01_surface_providers-models.md b/skills/ocx/references/01_surface_providers-models.md
new file mode 100644
index 00000000000..09179ffd987
--- /dev/null
+++ b/skills/ocx/references/01_surface_providers-models.md
@@ -0,0 +1,846 @@
+<!-- GENERATED by scripts/generate-ocx-skill-surface.ts. Do not edit by hand. -->
+<!-- Regenerate: bun scripts/generate-ocx-skill-surface.ts -->
+
+# providers-models: declared management tasks
+
+[Management index](01_management_surface.md) · [Operating rules](../SKILL.md#secret-bearing-commands)
+
+Use these declarations to choose a task, then check its flags and authority before execution.
+Non-mutating probes may still contact providers, consume quota or refresh caches.
+
+Declared capabilities: 40.
+
+### `ocx models price`
+
+Usage: `ocx models price <provider/model> [--json]`
+
+Read the saved manual price for an exact provider/model selector.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/providers/{provider}/model-costs` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit provider, modelId, and cost (null for automatic pricing). |
+
+JSON mode: `envelope`.
+
+- The provider must be configured; everything after the first slash is the exact upstream model ID.
+
+### `ocx models set-price`
+
+Usage: `ocx models set-price <provider/model> (--input <N> --output <N> [--cache-read <N>] [--cache-write <N>]|--auto) [--json]`
+
+Save four manual USD-per-1M-token rates, or restore automatic pricing for one model.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/providers/{provider}/model-costs` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--input` | number | Input rate; required unless --auto is used. |
+| `--output` | number | Output rate; required unless --auto is used. |
+| `--cache-read` | number | Cache read rate; defaults to 0. |
+| `--cache-write` | number | Cache write rate; defaults to 0. |
+| `--auto` | boolean | Remove this model's override; cannot be combined with rates. |
+| `--json` | boolean | Emit the saved price or reset result as JSON. |
+
+JSON mode: `envelope`.
+
+- Uses the exact upstream model ID after the first slash. Omitted cache rates default to zero; sibling model prices are preserved.
+
+### `ocx models set`
+
+Usage: `ocx models set <provider/model> [--context-window <tokens|0|->] [--modalities <text,image,audio|->] [--reasoning-efforts <levels|->] [--default-reasoning-effort <level|->] [--reset] [--json]`
+
+Save per-model overrides for a routed model, or clear them back to the computed values.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/model-settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--context-window` | string | Context window in tokens; 0 or - clears the override. |
+| `--modalities` | string | Comma-separated text,image,audio; - clears the override. |
+| `--reasoning-efforts` | string | Comma-separated ladder; "" for no reasoning, - to inherit. |
+| `--default-reasoning-effort` | string | Ladder member a request inherits when it omits one; - to inherit. |
+| `--reset` | boolean | Clear every override on this model; cannot be combined with the options above. |
+| `--json` | boolean | Emit the saved state as JSON. |
+
+JSON mode: `envelope`.
+
+- Only routed provider/model selectors are supported. At least one option or --reset is required.
+- Context 0 or - and modalities/default effort - clear to null; reasoning efforts - restores inheritance while an empty string stores an empty ladder.
+- --reset clears all four overrides with null and cannot be combined with other settings. A saved-but-catalog-refresh-failed receipt must not be mistaken for an unsaved change.
+
+### `ocx provider list`
+
+Usage: `ocx provider list [--json|--jsonl]`
+
+Configured providers with connectivity and selected models.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the provider list as JSON. |
+| `--jsonl` | boolean | Emit one configured provider per JSON line. |
+
+JSON mode: `envelope`.
+
+- Local config and registry read, not GET /api/providers. --json and --jsonl are mutually exclusive.
+
+### `ocx provider resets`
+
+Usage: `ocx provider resets [--limit <n>] [--json]`
+
+Recently detected quota resets and whether reset notifications are enabled.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/quota-resets` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit reset events as JSON. |
+| `--limit` | number | Limit returned events; defaults to 20, capped at 100. |
+
+JSON mode: `payload`.
+
+### `ocx provider keychain`
+
+Usage: `ocx provider keychain <name> [status|store|restore] [--json]`
+
+Move a provider's API key into the OS keychain, restore it, or report where it lives.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/providers/keychain` |
+| POST | `/api/providers/keychain` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the keychain status or result as JSON. |
+
+JSON mode: `payload`.
+
+- status reads by provider name; store/restore POST {name,action}. These move an existing secret between config and OS keychain; keep credential material out of transcripts.
+
+### `ocx provider add`
+
+Usage: `ocx provider add <name> [--adapter <id>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <id>] [--model <id> --text-only] [--google-tool-schema-policy <compatible|reject-lossy>] [--allow-private-network] [--set-default] [--force] [--sync] [--json]`
+
+Add or replace a provider in local configuration.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--adapter` | string | Required for a provider absent from the registry. |
+| `--base-url` | string | Upstream URL; required for an unregistered provider. |
+| `--api-key` | string | Legacy argv credential input; prefer the human-operated stdin account add-key workflow. |
+| `--api-key-transport` | string | x-api-key or bearer. |
+| `--default-model` | string | Default upstream model ID. |
+| `--model` | string | Model for --text-only; requires that flag. |
+| `--text-only` | boolean | Declare text-only input for --model or the default model. |
+| `--google-tool-schema-policy` | string | Google adapter: compatible or reject-lossy. |
+| `--allow-private-network` | boolean | Permit a private upstream network. |
+| `--set-default` | boolean | Also select this provider as default. |
+| `--force` | boolean | Replace an existing provider. |
+| `--sync` | boolean | Attempt local Codex synchronization after saving in text mode. |
+| `--json` | boolean | Emit the local save receipt. |
+
+JSON mode: `envelope`.
+
+- Writes local config, not the provider management API. JSON returns after saving with needsSync:true, before --sync; inspect the receipt and synchronize separately. Keep real credentials out of argv and agent transcripts.
+
+### `ocx provider show`
+
+Usage: `ocx provider show <name> [--json]`
+
+Inspect one locally configured provider.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the local provider view. |
+
+JSON mode: `envelope`.
+
+- Reads local config; masks API-key and key-pool fields. This is not a live provider read or a general secret-export interface.
+
+### `ocx provider remove`
+
+Usage: `ocx provider remove <name> [--json]`
+
+Remove a provider from local configuration.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the removal receipt and needsSync. |
+
+JSON mode: `envelope`.
+
+- Local write, with no management HTTP call. Refuses the default, last provider, or combo dependencies; also removes that provider's custom models. Requires operator intent; the handler has no --yes flag.
+
+### `ocx provider set-default`
+
+Usage: `ocx provider set-default <name> [--json]`
+
+Select the default provider in local configuration.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the save/no-op receipt and needsSync. |
+
+JSON mode: `envelope`.
+
+- Local config operation; the provider must already exist. Does not claim live management convergence.
+
+### `ocx provider edit`
+
+Usage: `ocx provider edit <name> [--adapter <id>] [--base-url <url>] [--default-model <id|->] [--auth-mode <key|forward|oauth|local|->] [--note <text|->] [--api-key-transport <x-api-key|bearer|->] [--headers <json|->] [--enabled <on|off>] [--live-models <on|off>] [--retain-models <id,id|->] [--model <id> --text-only] [--xai-chat <on|off>] [--allow-private-network <on|off>] [--model-context-tier <model=default|long_context>] [--json]`
+
+Patch an existing provider through the running proxy.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PATCH | `/api/providers` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--adapter` | string | Adapter ID. |
+| `--base-url` | string | Upstream URL. |
+| `--default-model` | string | Model ID; - clears. |
+| `--auth-mode` | string | key, forward, oauth, local; - clears. |
+| `--note` | string | Note; - clears. |
+| `--api-key-transport` | string | x-api-key or bearer; - clears. |
+| `--headers` | string | JSON object; - or JSON null clears. |
+| `--enabled` | string | on or off. |
+| `--live-models` | string | on or off. |
+| `--retain-models` | string | Comma-separated IDs; - clears with null. |
+| `--model` | string | Requires --text-only. |
+| `--text-only` | boolean | Requires --model; declare text-only input. |
+| `--xai-chat` | string | xai only: on uses Chat, off opts into Responses. |
+| `--allow-private-network` | string | on or off. |
+| `--model-context-tier` | string | Repeatable github-copilot model=default or model=long_context. |
+| `--json` | boolean | Emit the management receipt. |
+
+JSON mode: `payload`.
+
+- At least one edit is required; only supplied fields are patched. update is an existing alias. Use provider show only for local state, not as proof of the live write.
+
+### `ocx provider test`
+
+Usage: `ocx provider test <name> [--json]`
+
+Probe a provider's live model discovery connectivity.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| POST | `/api/providers/test` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the probe result. |
+
+JSON mode: `payload`.
+
+- May contact the upstream provider; requires operator intent to probe. Static catalogs can return applicable:false; failed connectivity exits nonzero.
+
+### `ocx provider quota`
+
+Usage: `ocx provider quota [--refresh] [--json]`
+
+Read provider quota reports, optionally refreshing them.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/provider-quotas` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--refresh` | boolean | Request refresh=1; may contact providers and update cached observations. |
+| `--json` | boolean | Emit the quota report. |
+
+JSON mode: `payload`.
+
+- Reads quota observations without changing operator settings. Cache misses may probe upstream even without --refresh; --refresh bypasses the cache and updates observations. This GET is not the POST account-refresh operation.
+
+### `ocx provider presets`
+
+Usage: `ocx provider presets [--json]`
+
+Read provider presets from the running proxy.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/provider-presets` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the preset payload. |
+
+JSON mode: `payload`.
+
+### `ocx provider account-mode`
+
+Usage: `ocx provider account-mode <pool|direct> [--json]`
+
+Set OpenAI Codex account routing to pool or direct.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PATCH | `/api/providers` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the management receipt. |
+
+JSON mode: `payload`.
+
+- Patches codexAccountMode on provider openai; this does not switch the physical Codex login.
+
+### `ocx provider selected`
+
+Usage: `ocx provider selected <name> [--set <id,id...>|--clear] [--json]`
+
+Read or replace one provider's selected model allowlist.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/selected-models` |
+| PUT | `/api/selected-models` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--set` | string | Replace with comma-separated upstream IDs. |
+| `--clear` | boolean | Clear the allowlist to show all; exclusive with --set. |
+| `--json` | boolean | Emit the selected view or receipt. |
+
+JSON mode: `envelope`.
+
+- Without a mutation flag this reads only. --clear sends models:[], not a model named -.
+- Read JSON is the CLI projection {provider, selected: string[], available: string[]}, not the API's provider-keyed maps; missing entries become empty arrays. --set/--clear JSON returns the server's write receipt unchanged.
+
+### `ocx models list`
+
+Usage: `ocx models list [--provider <name>] [--json]`
+
+List static configured models locally.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--provider` | string | Limit to a configured provider. |
+| `--json` | boolean | Emit models and the static-catalog note. |
+
+JSON mode: `envelope`.
+
+- A bare models invocation is equivalent. Reads local config, never the live catalog; use models live for runtime discovery.
+
+### `ocx models add`
+
+Usage: `ocx models add <provider> <modelId> [--display-name <name>] [--context-window <tokens>] [--modalities <text,image,audio>] [--reasoning-efforts <levels|->] [--default-reasoning-effort <level|->]`
+
+Add a custom model definition to local configuration.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--display-name` | string | Custom display name without a slash. |
+| `--context-window` | number | Positive integer token count. |
+| `--modalities` | string | Comma-separated text, image, audio. |
+| `--reasoning-efforts` | string | Comma-separated supported levels; - inherits; an empty string declares no reasoning. |
+| `--default-reasoning-effort` | string | A declared level; - inherits. |
+
+JSON mode: `none`.
+
+- Writes local customModels and attempts local Codex catalog sync if a proxy is found. No custom-model management route or JSON mode is used.
+
+### `ocx models remove`
+
+Usage: `ocx models remove <customId|provider/modelId> [--yes]`
+
+Remove a custom definition from local configuration.
+
+State-changing: yes.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--yes` | boolean | Confirm deletion without an interactive prompt. |
+
+JSON mode: `none`.
+
+- Local config deletion followed by a local Codex sync attempt. Ambiguous selectors are refused; list-custom --json exposes full IDs. Does not call DELETE /api/custom-models/{id}.
+
+### `ocx models list-custom`
+
+Usage: `ocx models list-custom [--json]`
+
+List locally stored custom model definitions and their IDs.
+
+State-changing: no.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the local customModels array with full IDs. |
+
+JSON mode: `payload`.
+
+- Reads local configuration, not the management API.
+
+### `ocx models live`
+
+Usage: `ocx models live [--provider <name>] [--free-only] [--json]`
+
+Read the running proxy's model catalog.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/models` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--provider` | string | Filter returned rows by provider. |
+| `--free-only` | boolean | Include only rows explicitly classified free. |
+| `--json` | boolean | Emit the filtered catalog array. |
+
+JSON mode: `payload`.
+
+### `ocx models edit`
+
+Usage: `ocx models edit <custom-id> [--model-id <id>] [--display-name <name|->] [--context-window <tokens|0>] [--modalities <text,image,audio|->] [--reasoning-efforts <levels|->] [--default-reasoning-effort <level|->] [--json]`
+
+Edit a custom model by its definition ID through the proxy.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/custom-models/{id}` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--model-id` | string | Upstream model ID. |
+| `--display-name` | string | Custom definition name; - clears. |
+| `--context-window` | number | Safe token count; 0 clears. Unlike models set, - is invalid here. |
+| `--modalities` | string | Comma-separated modalities; - sends an empty list. |
+| `--reasoning-efforts` | string | Comma-separated levels; - inherits (null), empty string stores an empty ladder. |
+| `--default-reasoning-effort` | string | Default effort; - clears with null. |
+| `--json` | boolean | Emit the management receipt. |
+
+JSON mode: `payload`.
+
+- At least one edit is required. Operand is the custom definition ID from list-custom, not a provider/model selector. Discovered-model display-name overrides are a different resource.
+
+### `ocx models enable`
+
+Usage: `ocx models enable <provider/model|native-model> [--native] [--json]`
+
+Enable one routed or native catalog model.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/model-visibility` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--native` | boolean | Treat the whole selector as a native OpenAI model ID. |
+| `--json` | boolean | Emit the visibility receipt. |
+
+JSON mode: `payload`.
+
+### `ocx models disable`
+
+Usage: `ocx models disable <provider/model|native-model> [--native] [--json]`
+
+Disable one routed or native catalog model.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/model-visibility` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--native` | boolean | Treat the whole selector as a native OpenAI model ID. |
+| `--json` | boolean | Emit the visibility receipt. |
+
+JSON mode: `payload`.
+
+### `ocx models provider`
+
+Usage: `ocx models provider <name> <on|off> [--json]`
+
+Enable or disable all catalog rows for a provider.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/models` |
+| PUT | `/api/model-visibility` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the visibility receipt. |
+
+JSON mode: `payload`.
+
+- Reads targets from the live catalog first; refuses a provider without available models.
+
+### `ocx models selected`
+
+Usage: `ocx models selected <provider> [--set <id,id...>|--clear] [--json]`
+
+Read or replace a provider's selected model allowlist.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/selected-models` |
+| PUT | `/api/selected-models` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--set` | string | Replace the allowlist with comma-separated IDs. |
+| `--clear` | boolean | Send an empty list to show all; exclusive with --set. |
+| `--json` | boolean | Emit the selected view or receipt. |
+
+JSON mode: `envelope`.
+
+- Without --set or --clear this only reads. A literal - is not the clear spelling.
+- Read JSON is the CLI projection {provider, selected: string[], available: string[]}, not the API's provider-keyed maps; missing entries become empty arrays. --set/--clear JSON returns the server's write receipt unchanged.
+
+### `ocx models preset show`
+
+Usage: `ocx models preset show [--provider <name>] [--json]`
+
+Inspect shipped model presets and applied versions.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/model-presets` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--provider` | string | Project a single provider's preset. |
+| `--json` | boolean | Emit the preset view. |
+
+JSON mode: `payload`.
+
+### `ocx models preset apply`
+
+Usage: `ocx models preset apply <provider> [--all] [--json]`
+
+Apply a provider's curated model preset or show all models.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/model-presets` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--all` | boolean | Use mode all instead of preset. |
+| `--json` | boolean | Emit the application receipt. |
+
+JSON mode: `payload`.
+
+- An empty preset match preserves the previous selection and reports fallback; do not interpret it as successful narrowing.
+
+### `ocx models new-policy`
+
+Usage: `ocx models new-policy [on|off] [--provider <name>] [--json]`
+
+Read or set the policy for newly discovered models.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| GET | `/api/model-discovery` |
+| PUT | `/api/model-discovery` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--provider` | string | Scope the read/write to a provider; omitted means global. |
+| `--json` | boolean | Emit the policy view or receipt. |
+
+JSON mode: `payload`.
+
+- No state operand means read only. Only on/off writes exist; no inherit/clear operand is implemented.
+
+### `ocx models new-arrivals`
+
+Usage: `ocx models new-arrivals [--json]`
+
+Read recent model discoveries.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/model-discovery` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit recentArrivals grouped by provider. |
+
+JSON mode: `payload`.
+
+### `ocx models context status`
+
+Usage: `ocx models context status [--json]`
+
+Read routed-provider context caps.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/provider-context-caps` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit context settings. |
+
+JSON mode: `payload`.
+
+### `ocx models context value`
+
+Usage: `ocx models context value <tokens> [--set-all] [--json]`
+
+Set the default routed-provider context cap value.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/provider-context-caps` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--set-all` | boolean | Also apply the value to every routed provider. |
+| `--json` | boolean | Emit the context receipt. |
+
+JSON mode: `payload`.
+
+- Tokens must be a positive safe integer; separators _ and , are accepted. Without --set-all only the default for future toggles changes.
+
+### `ocx models context provider`
+
+Usage: `ocx models context provider <provider> <on|off> [--value <tokens>] [--json]`
+
+Toggle one provider's context cap, optionally choosing its value.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/provider-context-caps` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--value` | number | Positive integer; only valid with on. |
+| `--json` | boolean | Emit the context receipt. |
+
+JSON mode: `payload`.
+
+- off disables this provider's cap; --value is not a global value change.
+
+### `ocx models context all`
+
+Usage: `ocx models context all <on|off> [--json]`
+
+Enable or disable caps for all routed providers.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/provider-context-caps` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the context receipt. |
+
+JSON mode: `payload`.
+
+### `ocx models shadow status`
+
+Usage: `ocx models shadow status [--json]`
+
+Read shadow-call settings.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/shadow-call-settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit shadow-call settings. |
+
+JSON mode: `payload`.
+
+### `ocx models shadow set`
+
+Usage: `ocx models shadow set [model|-] [--enabled <on|off>] [--json]`
+
+Set the shadow-call model or enabled state.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/shadow-call-settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--enabled` | string | on or off; takes a value. |
+| `--json` | boolean | Emit the settings receipt. |
+
+JSON mode: `payload`.
+
+- At least a model or --enabled is required; - clears the model with an empty string. Enabling shadow calls can cause subsequent inference calls.
+
+### `ocx alias list`
+
+Usage: `ocx alias list [--json]`
+
+Read provider and model aliases.
+
+State-changing: no.
+
+| Method | Route |
+|---|---|
+| GET | `/api/aliases` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit alias maps and provenance. |
+
+JSON mode: `payload`.
+
+### `ocx alias set`
+
+Usage: `ocx alias set <provider|provider/native-model-id> <alias> [--json]`
+
+Assign a provider or upstream model alias.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/providers/{provider}/alias` |
+| PUT | `/api/providers/{provider}/model-aliases` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the alias receipt. |
+
+JSON mode: `payload`.
+
+- The first slash separates provider from the complete upstream model ID.
+
+### `ocx alias rm`
+
+Usage: `ocx alias rm <provider|provider/native-model-id> [--json]`
+
+Clear a provider or model alias.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/providers/{provider}/alias` |
+| PUT | `/api/providers/{provider}/model-aliases` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit the alias removal receipt. |
+
+JSON mode: `payload`.
+
+- Provider clear sends alias:null; model clear sends remove:[modelId].
+
+### `ocx alias defaults`
+
+Usage: `ocx alias defaults <on|off> [--provider <name>] [--json]`
+
+Toggle built-in model aliases globally or for a provider.
+
+State-changing: yes.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/default-aliases` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--provider` | string | Limit the toggle to one provider. |
+| `--json` | boolean | Emit the alias settings receipt. |
+
+JSON mode: `payload`.
diff --git a/skills/ocx/references/02_json_shapes.md b/skills/ocx/references/02_json_shapes.md
index e93be59748e..e157f9cf991 100644
--- a/skills/ocx/references/02_json_shapes.md
+++ b/skills/ocx/references/02_json_shapes.md
@@ -1,9 +1,9 @@
 # JSON shapes
 
-What the `--json` envelopes look like, and which field to read. Field names here were taken from
-live responses, not from the source.
+Selected response shapes and fields to inspect. These are command-specific examples,
+not a universal schema; check the installed leaf help and the actual receipt.
 
-## Two envelope styles
+## Output modes
 
 `ocx capabilities --json` reports which style each verb uses, as `json: "payload"` or
 `json: "envelope"`.
@@ -14,7 +14,9 @@ live responses, not from the source.
   fields the verb operated on.
 - **none** — the verb has no `--json` mode.
 
-`--json` is accepted in any argv position.
+Output flags are parsed by each command, not globally. Preserve the documented
+operand order; do not add `--json` to a leaf marked `none`. `doctor` rejects it
+with exit 2; `v2` remains human-output only.
 
 ## `ocx ready --json`
 
@@ -22,13 +24,15 @@ live responses, not from the source.
 {"ready":true,"status":"ready","pid":1443,"port":10100}
 ```
 
-The cheapest liveness check. `ready: false` with no error usually means still starting.
+A readiness probe, not a start command. `ready: false` can mean `pending`,
+`failed` or `unreachable`; only `pending` describes startup still in progress.
 
 ## `ocx status --json`
 
 Carries `schemaVersion`, then `proxy.running`, `proxy.pid`, `proxy.health.ok`, and a `dashboard`
 section. This is also where a version skew between your binary and the running proxy shows up —
-check it before trusting flags you just read about.
+check `versionSkew.relation` before trusting flags you just read about.
+`match` confirms version equality; `unknown` is not a match.
 
 ## `ocx logs --jsonl`
 
@@ -117,7 +121,8 @@ one with 409. The CLI handles that for you — it always previews first.
 
 ## Error shape
 
-A management error prints up to three lines and returns a non-zero code:
+A management error normally prints a message and optional reason/hint on stderr
+and returns a non-zero code; recovery details can add further lines:
 
 ```
 Error: <message>
@@ -125,6 +130,22 @@ reason: <machine-readable reason>
 hint: <what to do>
 ```
 
-Branch on `reason` in those stderr lines, never on the message prose. `--json` does **not** wrap
-API failures in `{error:{type,code,message}}`; `runCliAction` still prints the three-liner on
+Use `reason` when present, but it is optional; retain the exit code and stderr
+when absent. Nested server error objects do not have a universal CLI decoder. `--json` does **not** wrap
+API failures in `{error:{type,code,message}}`; `runCliAction` still prints prose on
 stderr and returns 4/5/1. Do not parse stdout for an error envelope that is not there.
+
+## Saved, applied, skipped and partial
+
+- Local `provider add <name> --json` returns `needsSync: true`. It returns before the
+  human-output `--sync` path; even both flags together do not prove live apply.
+- `models preset apply` can return `fallback: "preset-empty"`; selection is then
+  unchanged. Read `models selected <provider> --json` to check the effective list.
+- Client integration results can preserve saved intent while reporting individual
+  refused profiles. Inspect each profile and re-read status; partial is not full success.
+- `account pause-exhausted` includes `failedAccountCount`. Failed quota reads do
+  not establish that those accounts still have capacity.
+
+A local save or an accepted update is not proof that a client has reloaded its
+files. Do not automatically repeat a write whose apply or transport outcome is
+uncertain; read back first and preserve the reported limitations.
diff --git a/skills/ocx/references/03_recipes.md b/skills/ocx/references/03_recipes.md
index d89d829ed76..26beee621c9 100644
--- a/skills/ocx/references/03_recipes.md
+++ b/skills/ocx/references/03_recipes.md
@@ -1,21 +1,23 @@
 # Recipes
 
-The original sequences below were run against a live proxy; the Aside profile sequence was
-verified through an isolated live management handler and the production CLI. Every command named here exists; where the
-obvious-sounding command does *not* exist, that is called out rather than left as a trap.
-
-Preflight for all of them:
+Choose a task first with offline root, family and leaf help, then read its generated
+chapter. For live management sequences, check the target before the first call:
 
 ```bash
-ocx ready --json     # {"ready":true,"status":"ready","pid":…,"port":…}
-ocx status --json    # confirm proxy.running and no version skew
+ocx ready --json
+ocx status --json
 ```
 
+Inspect readiness and `versionSkew.relation`. Local configuration and local Lab
+inspection do not require starting the proxy. Each example uses only that leaf's
+supported output flags; mutation examples require authority for that task.
+
 ## 1. Audit the account pool and pause an exhausted account
 
 ```bash
 ocx account list openai --json --quota
 ocx account pause openai <account-id> --json
+ocx account list openai --json
 ```
 
 Read `accounts[]`; each row carries `id`, `paused`, `selected`, and — only under `--quota` — the
@@ -43,6 +45,8 @@ not the same as "not exhausted".
 ocx account strategy openai --json          # read
 ocx account strategy openai round-robin --json
 ocx account sticky openai 5 --json
+ocx account strategy openai --json
+ocx account sticky openai --json
 ```
 
 A bare invocation reads and never writes. The response echoes the **applied** value, not the one
@@ -165,21 +169,41 @@ return the plaintext once; list does not return the full plaintext.
 An `ambiguous` footer on the list means two configured keys share an id, so per-key totals do not
 exist for them — do not attribute usage to either.
 
-## 6. Add a provider, test it, make it default
+## 6. Save a provider, then verify live adoption
+
+Local config operations do not need a running proxy:
 
 ```bash
 ocx provider list --json
-ocx provider list --jsonl                   # one configured provider per line
-ocx provider add <name> --json                # registry providers auto-configure by name
+ocx provider add <name> --json
+ocx provider show <name> --json
+```
+
+Registry providers are seeded by name; custom providers also need `--adapter`
+and `--base-url`. Complete credential entry through the supported human login or
+stdin handoff, never by putting a key in an agent transcript.
+
+`needsSync: true` means saved, not live-applied. Adding `--sync` to this JSON
+invocation does not execute sync. After authorized synchronization and the live
+preflight, compare configured state with runtime state:
+
+```bash
+ocx inspect config --json
 ocx provider test <name> --json
-ocx provider set-default <name> --json
+ocx models live --provider <name> --json
 ```
 
-The promote verb is `set-default`, not `default`. A custom provider not in the registry also needs
-`--adapter` and `--base-url` on `add`.
+The test may contact the upstream model-discovery endpoint; it is not an inference
+success test. `applicable: false` means the provider has a static catalog, not a
+failed connection. Only promote the verified provider when requested:
+
+```bash
+ocx provider set-default <name> --json
+ocx provider list --json
+```
 
-Test before promoting: `provider test` reports reachability and the selected model, and a provider
-that answers `list` is not necessarily one that answers a request.
+`set-default` saves local config; its receipt and any convergence warning must be
+reported separately. Do not equate a local list with live management state.
 
 ## 7. Diagnose "management API is unreachable"
 
@@ -189,8 +213,9 @@ ocx status --json    # is it the build you think, on the port you think?
 ocx doctor           # what is structurally wrong (human; `--json` is refused with exit 2)
 ```
 
-In that order. `ready` false with `doctor` clean usually means it is still starting; `ready` true
-with a transport error on a specific verb means the route is failing, not the proxy.
+`ready` false distinguishes `pending`, `failed` and `unreachable`; only pending
+suggests waiting for startup. A ready process still may be the wrong role or
+version for a specific management operation. Diagnose that target before retrying.
 
 `doctor` has no `--json` mode. It rejects the flag with exit 2 rather than printing prose to a
 caller that asked for JSON, so parse `ready --json` and `status --json` for machine-readable
@@ -313,3 +338,81 @@ Read `profiles[]` to find numeric profile IDs. No profile selector means a bulk
 explicit selector affects only that registered profile. Sync intent and actual file state
 are distinct, so inspect each result after a partial bulk operation. The CLI returns nonzero
 for a partial refusal. Never use the overwrite or drift flags merely to suppress a refusal.
+
+## 11. Choose a model preset and inspect new arrivals
+
+These are live management operations. Start with the saved preset and selection:
+
+```bash
+ocx models preset show --provider anthropic --json
+ocx models selected anthropic --json
+```
+
+When asked to select the curated roster:
+
+```bash
+ocx models preset apply anthropic --json
+ocx models selected anthropic --json
+```
+
+`fallback: "preset-empty"` preserves the existing selection; do not report an
+empty preset as a successful narrowing. `preset apply <provider> --all` clears
+the allowlist. The dashboard's disabled custom preset is not another CLI mode.
+
+Read the discovery policy before changing it. This example disables automatic
+exposure of newly discovered models for one provider, then reads it back:
+
+```bash
+ocx models new-policy --provider anthropic --json
+ocx models new-policy off --provider anthropic --json
+ocx models new-policy --provider anthropic --json
+ocx models new-arrivals --json
+```
+
+The provider read may report `inherit`; omission of `--provider` selects global
+policy. Recent arrivals show recorded discovery state, not a fresh upstream probe.
+
+## 12. Inspect and dry-run an existing routing profile
+
+Use an ID returned by the list (here `reliable` is an example saved ID):
+
+```bash
+ocx route policy list --json
+ocx route policy show reliable --json
+ocx route policy dry-run reliable --model-context 128000 --tools --image --structured-output --json
+```
+
+Only run this evaluation with authority to activate Lab on the target. The management POST can activate Lab and start automation that is already enabled there, including upstream probes. Use list/show for observation without that activation effect.
+
+Dry-run evaluates saved routing evidence without an inference request; it does
+not create or edit a profile. `evaluate` is the same dry-run operation. Profile
+create/update/delete remain dashboard workflows; combo editing targets a different
+resource. A missing profile returns exit 4; a missing operand returns 2.
+
+## 13. Inspect local Lab evidence before exporting or running probes
+
+No live management preflight is needed for these local reads:
+
+```bash
+ocx lab status --json
+ocx lab catalog --json
+ocx lab automation status --json
+ocx lab automation runs --limit 10 --json
+ocx lab public community --json
+```
+
+Use `lab subjects`, `lab subject <id>`, `lab observations --subject <id>`,
+`lab event <id>` and `lab artifact <digest>` to follow evidence lineage. These
+read the local projection, not a connected hub's database.
+
+For a requested evidence transfer, preview selected events before export:
+
+```bash
+ocx lab public preview --event <event-id> --json
+```
+
+The public family also supports export, file verification and import; export and
+import write local evidence. Automation enable/disable and manual `lab run` are
+explicit mutations and can launch quota-consuming probes. Inspect their leaf help
+and obtain task authority rather than using them to repair a failed read. Local
+policy persistence does not prove another running proxy's scheduler adopted it.
diff --git a/skills/ocx/references/04_failure_semantics.md b/skills/ocx/references/04_failure_semantics.md
index b0755fd2718..0b63aefc8e8 100644
--- a/skills/ocx/references/04_failure_semantics.md
+++ b/skills/ocx/references/04_failure_semantics.md
@@ -4,12 +4,14 @@ What each exit code means, which failures are worth retrying, and which mean sto
 
 ## Exit codes
 
-Set in one place (`runCliAction`), so every verb agrees:
+`runCliAction` maps many management failures; the whole CLI does not share one
+exit contract. Its common mappings and the main exceptions are:
 
 | Code | Cause | Retry? |
 |---|---|---|
 | 0 | success | — |
-| 2 | usage error: bad, missing, or unknown arguments | no; nothing was sent |
+| 2 | locally rejected usage in management handlers; also unsupported `doctor --json` | fix arguments |
+| 64 | usage validation in `capabilities`, `ready`, `resolve` | fix arguments; no discovery/request for invalid input |
 | 4 | HTTP 404 — the named account, provider, key, or route does not exist | no |
 | 5 | HTTP 409 — conflict; a lock is held or state moved under you | usually yes |
 | 1 | everything else: transport failure, 5xx, unexpected errors | depends on `reason` |
@@ -18,10 +20,12 @@ Two consequences worth internalizing:
 
 **Exit 0 means no error was reported, not that a mutation happened.** Preview verbs
 (`storage cleanup` without `--yes`) exit 0 after a read-only preview. Parse `--json` (or the
-human summary) to see whether anything was written. A command that failed will not exit 0.
+human summary) to see whether anything was written. Read saved/applied/skipped
+fields and warnings as well; a successful save can leave live convergence pending.
 
-**Exit 2 means nothing was sent.** A usage error is rejected locally, before any request. Retrying
-the same arguments produces the same result; fix the arguments.
+**A local usage refusal is not a transport failure.** Fix the arguments rather than
+retrying unchanged. Unknown root commands and unavailable explicit help topics use
+exit 1; a capability route miss uses 4 even when an undeclared handler exists.
 
 ## Distinguishing "not running" from "failing"
 
@@ -29,9 +33,11 @@ the same arguments produces the same result; fix the arguments.
 ocx ready --json
 ```
 
-`ready` is the discriminator. If it fails or reports `ready: false`, nothing else will work and the
-answer is to start or wait for the proxy. If `ready` is true and one specific verb fails, the
-problem is that route or its arguments — not the proxy.
+Use readiness before live management. `pending` permits a bounded wait; `failed`
+and `unreachable` need diagnosis. Offline help, local config and local Lab reads
+still work without a proxy: do not start one just to perform those tasks. A ready
+proxy can still refuse a route, serve an older version, or be the wrong role.
+Check `status --json` and its `versionSkew` and target information.
 
 A transport failure exits 1 and names the underlying cause (connection refused, DNS, TLS). Those
 used to be indistinguishable; they are now reported separately, so read the message.
@@ -56,9 +62,10 @@ and repeating the call produces the same error indefinitely.
 
 ## A retry policy that does not spin
 
-1. Exit 2 → fix arguments. Never retry unchanged.
-2. Exit 4 → the target does not exist. List first (`account list`, `provider list`, `access key
-   list`) rather than retrying.
+1. Exit 2 or 64 → fix arguments. Never retry unchanged.
+2. Exit 4 → distinguish a missing resource from a missing declaration. For a
+   resource, list first (`account list`, `provider list`, `access key list`); for
+   a declaration, consult family help. Do not retry the same lookup.
 3. Exit 5 or a 503 with `Retry-After` → wait the stated interval, retry **once**. If it fails the
    same way twice, report it instead of looping.
 4. Exit 1 with a credential-conflict reason → run `ocx doctor` and report. Do not retry.
diff --git a/skills/ocx/references/05_remote_hub.md b/skills/ocx/references/05_remote_hub.md
index aaaf36a1e3d..ed1fa739664 100644
--- a/skills/ocx/references/05_remote_hub.md
+++ b/skills/ocx/references/05_remote_hub.md
@@ -4,6 +4,21 @@ The remote hub lets one machine hold the models and credentials while other mach
 and browsers use them. Four questions come up constantly, and three of them have
 answers that are easy to guess wrong.
 
+## Discover locally, manage the intended machine
+
+`ocx help connect`, `ocx help hub` and the
+[access/remote chapter](01_surface_access-remote.md) are offline discovery.
+`ocx connect status --json` reports the local connection. Before live management,
+run readiness and version checks on the machine serving the management API.
+A connected client's machine listener does not serve ordinary management routes;
+the CLI refuses that target rather than automatically forwarding the operation.
+Run management commands on the hub or use its dashboard (which supports relay).
+Local config and local Lab commands still refer to this machine's files.
+
+Read connection status again after an authorized connect, rotation or disconnect.
+A saved connection, completed catalog transfer, client-file rewrite and healthy
+remote service are separate observations; retain partial/refused outcomes.
+
 ## One port, and what runs on it
 
 A hub's data plane is one port. Remote machines dial `hostname:port` with their own
diff --git a/src/cli/capabilities-access-remote.ts b/src/cli/capabilities-access-remote.ts
new file mode 100644
index 00000000000..e322a3c94d1
--- /dev/null
+++ b/src/cli/capabilities-access-remote.ts
@@ -0,0 +1,85 @@
+import type { Capability } from "./capability-types";
+
+/** Verified existing handlers only; local operations never claim management routes. */
+export const ACCESS_REMOTE_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["access", "key"], summary: "Manage API access keys and inspect masked metadata.",
+    usage: "ocx access key list [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}, {"method": "POST", "path": "/api/keys"}, {"method": "PATCH", "path": "/api/keys"}, {"method": "DELETE", "path": "/api/keys"}, {"method": "POST", "path": "/api/keys/rotate"}, {"method": "POST", "path": "/api/keys/rotate/commit"}, {"method": "DELETE", "path": "/api/keys/rotate"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Mixed family: list/get read masked metadata; scope edits, revocation and rotation change authorization.", "Creation and rotation initiation return plaintext secrets once and are human-only handoffs. Ask the operator to perform them in their terminal or dashboard; never capture the returned credential.", "Use the separately documented safe follow-up leaves. keys and top-level api-key are aliases."],
+  },
+  {
+    command: ["access", "key", "list"], summary: "List masked access keys, usage, endpoints and pending rotations.",
+    usage: "ocx access key list [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["No plaintext secret is returned by the list route."],
+  },
+  {
+    command: ["access", "key", "get"], summary: "Read one masked key and its access scope.",
+    usage: "ocx access key get <id-or-name> [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Case-insensitive ID takes precedence over name; ambiguous names are refused."],
+  },
+  {
+    command: ["access", "key", "set"], summary: "Replace selected provider/model scope dimensions.",
+    usage: "ocx access key set <id-or-name> [--allow-provider <name>]... [--allow-model <id>]... [--clear] [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}, {"method": "PATCH", "path": "/api/keys"}],
+    flags: [{"name": "--allow-provider", "value": "string", "summary": "Provider scope; repeatable, replaces that dimension."}, {"name": "--allow-model", "value": "string", "summary": "Model scope; repeatable, replaces that dimension."}, {"name": "--clear", "value": "boolean", "summary": "Clear both dimensions; submitted allow options then override their dimension."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["At least one scope option is required. Unspecified dimensions are preserved; this command does not rename keys."],
+  },
+  {
+    command: ["access", "key", "rotate", "commit"], summary: "Commit a pending key rotation.",
+    usage: "ocx access key rotate commit <id> <rotation-id> [--json]",
+    routes: [{"method": "POST", "path": "/api/keys/rotate/commit"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Use IDs from the human-authorized rotation. Commit only after the client accepts the replacement; the old credential is retired."],
+  },
+  {
+    command: ["access", "key", "rotate", "abort"], summary: "Abort a pending key rotation.",
+    usage: "ocx access key rotate abort <id> <rotation-id> [--json]",
+    routes: [{"method": "DELETE", "path": "/api/keys/rotate"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Use IDs from the human-authorized rotation. Abort discards the pending replacement credential."],
+  },
+  {
+    command: ["access", "key", "remove"], summary: "Revoke one API access key.",
+    usage: "ocx access key remove <id> --yes [--json]",
+    routes: [{"method": "DELETE", "path": "/api/keys"}],
+    flags: [{"name": "--yes", "value": "boolean", "summary": "Required confirmation before revoking the key.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Uses the exact ID, not name resolution; delete is an alias."],
+  },
+  {
+    command: ["access", "endpoints"], summary: "Read endpoint URLs from the access-key metadata.",
+    usage: "ocx access endpoints [--json]",
+    routes: [{"method": "GET", "path": "/api/keys"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "envelope",
+    details: ["Projects only baseUrl, endpoint and fields ending in Endpoint; use key list for the full metadata payload."],
+  },
+  {
+    command: ["access", "models"], summary: "Read the public external-model catalog.",
+    usage: "ocx access models [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Data-plane GET /v1/models via the runtime client; differs from management models live. The routes field indexes management API routes only."],
+  },
+  {
+    command: ["access", "test"], summary: "Send a small inference request through the selected protocol.",
+    usage: "ocx access test <model> [--protocol <chat|responses|messages>] [--json]",
+    routes: [],
+    flags: [{"name": "--protocol", "value": "string", "summary": "chat | responses | messages; default chat."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Data-plane POST /v1/chat/completions, /v1/responses or /v1/messages according to --protocol; these are not management API routes. May spend upstream quota; run only for an explicitly authorized inference probe.", "Uses runtime management headers and has no chosen-key input; success is not validation of a newly created data key."],
+  },
+];
diff --git a/src/cli/capabilities-accounts.ts b/src/cli/capabilities-accounts.ts
new file mode 100644
index 00000000000..e675c5549db
--- /dev/null
+++ b/src/cli/capabilities-accounts.ts
@@ -0,0 +1,148 @@
+import type { Capability } from "./capability-types";
+
+/** Account pool operations and physical native-login profiles have separate owners. */
+export const ACCOUNT_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["logout"], summary: "Remove the active stored OAuth credential for a provider locally.",
+    usage: "ocx logout <provider> [--json]", routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit schemaVersion, ok, provider and removed; missing credentials include reason:not_found." }], mutates: true, json: "envelope",
+    details: ["Local credential-store operation, not POST /api/oauth/logout. Requires operator intent; rejects malformed arguments before store access. Missing credential exits 4, usage errors exit 2. Does not prove that a running proxy has reloaded its cached credentials."],
+  },
+  {
+    command: ["account", "current"], summary: "Read the active account or API key for a provider.",
+    usage: "ocx account current <provider> [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/codex-auth/active" }, { method: "GET", path: "/api/oauth/accounts" }, { method: "GET", path: "/api/providers/keys" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit provider, type, activeId and the projected account." }], mutates: false, json: "envelope",
+    details: ["Uses the live route for the configured account family; this does not report the physical native-main profile."],
+  },
+  {
+    command: ["account", "use"], summary: "Select a provider's pool account or API key.",
+    usage: "ocx account use <provider> <account-or-key-id|alias|main|auto> [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/codex-auth/active" }, { method: "PUT", path: "/api/codex-auth/active" }, { method: "PUT", path: "/api/oauth/accounts/active" }, { method: "PUT", path: "/api/providers/keys/active" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the selection receipt, including pin-drain information when present." }], mutates: true, json: "envelope",
+    details: ["Codex resolves IDs and aliases before reserved words; an account actually named auto wins. account clear openai always clears. OAuth and API-key selection pass the ID directly. This does not switch the physical Codex App login."],
+  },
+  {
+    command: ["account", "clear"], summary: "Clear a Codex pool's manual account selection pin.",
+    usage: "ocx account clear <provider> [--json]",
+    routes: [{ method: "PUT", path: "/api/codex-auth/active" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the clear receipt." }], mutates: true, json: "envelope",
+    details: ["Only Codex account pools are supported; other families are refused. Sends accountId:null without interpreting auto as an account ID."],
+  },
+  {
+    command: ["account", "alias"], summary: "Set or clear an account's display alias.",
+    usage: "ocx account alias <provider> <account-or-key-id|alias> <display-name|-> [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "PUT", path: "/api/codex-auth/accounts/alias" }, { method: "PUT", path: "/api/oauth/accounts/alias" }, { method: "PUT", path: "/api/providers/keys/alias" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the applied alias, or null after clearing." }], mutates: true, json: "envelope",
+    details: ["- clears with an empty string. Codex resolves existing aliases; other families take an ID. Native main cannot be renamed; aliases are at most 80 printable characters. rename is an existing command alias."],
+  },
+  {
+    command: ["account", "priority"], summary: "Read or change Codex account selection order.",
+    usage: "ocx account priority <provider> <account-id|alias|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/codex-auth/active" }, { method: "PUT", path: "/api/codex-auth/accounts/priority" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the normalized priority and named preset." }], mutates: true, json: "envelope",
+    details: ["Only Codex pools support selection order. Omitting the value reads; reset sends null. Every write releases any manual pin, even if the value is unchanged; running threads retain their account until drained."],
+  },
+  {
+    command: ["account", "clear-cooldown"], summary: "Lift an operator-clearable Codex or Anthropic account cooldown.",
+    usage: "ocx account clear-cooldown <provider> <account-id|alias|main> [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/oauth/accounts" }, { method: "POST", path: "/api/codex-auth/accounts/clear-cooldown" }, { method: "POST", path: "/api/oauth/accounts/clear-cooldown" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit whether a cooldown was actually cleared." }], mutates: true, json: "envelope",
+    details: ["Other provider families are refused. Resolves Codex or Anthropic account aliases before writing."],
+  },
+  {
+    command: ["account", "remove"], summary: "Remove a pool account or provider API key with explicit confirmation.",
+    usage: "ocx account remove <provider> <account-or-key-id|alias> --yes [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }, { method: "GET", path: "/api/codex-auth/active" }, { method: "GET", path: "/api/oauth/accounts" }, { method: "GET", path: "/api/providers/keys" }, { method: "DELETE", path: "/api/codex-auth/accounts" }, { method: "DELETE", path: "/api/oauth/accounts" }, { method: "DELETE", path: "/api/providers/keys" }],
+    flags: [{ name: "--yes", value: "boolean", required: true, summary: "Confirm account/key deletion." }, { name: "--json", value: "boolean", summary: "Emit removal and promoted-account information." }], mutates: true, json: "envelope",
+    details: ["Native main removal is refused. Reads the account family before and after deletion; a failed post-delete read means deletion may have succeeded. Only Codex resolves aliases here."],
+  },
+  {
+    command: ["account", "add-key"], summary: "Import an existing provider API key from a human-controlled stdin source.",
+    usage: "ocx account add-key <provider> [--label <label>] [--json]",
+    routes: [{ method: "POST", path: "/api/providers/keys" }],
+    flags: [{ name: "--label", value: "string", summary: "Optional label for the imported key." }, { name: "--json", value: "boolean", summary: "Emit a redacted receipt containing the key ID, never the key." }], mutates: true, json: "envelope",
+    details: ["API-key providers only. Requires non-TTY stdin and reads one secret line; never put plaintext keys in command arguments or agent transcripts. This imports an upstream credential, not an OpenCodex access-key creation workflow."],
+  },
+  {
+    command: ["account", "import"], summary: "Import Google Antigravity accounts from a bounded Cockpit Tools document.",
+    usage: "ocx account import google-antigravity --format cockpit-tools (--file <path>|--stdin) [--json]",
+    routes: [{ method: "POST", path: "/api/oauth/accounts/import" }],
+    flags: [{ name: "--format", value: "string", required: true, summary: "Only cockpit-tools is supported." }, { name: "--file", value: "string", summary: "Bounded source document; exclusive with --stdin." }, { name: "--stdin", value: "boolean", summary: "Read the document from non-TTY stdin." }, { name: "--json", value: "boolean", summary: "Emit sanitized per-record import outcomes." }], mutates: true, json: "envelope",
+    details: ["Human-controlled credential handoff: choose exactly one source. Unsupported providers/formats are refused before source I/O. Partial failures or unsupported records return nonzero; do not echo the document."],
+  },
+  {
+    command: ["account", "reauth"], summary: "Reauthenticate a provider account through the existing login flow.",
+    usage: "ocx account reauth <provider> [--id <account-id>] [--device] [--code -] [--no-wait] [--json]",
+    routes: [{ method: "POST", path: "/api/codex-auth/login" }, { method: "GET", path: "/api/codex-auth/login-status" }, { method: "POST", path: "/api/codex-auth/login/code" }, { method: "POST", path: "/api/oauth/login" }, { method: "GET", path: "/api/oauth/status" }, { method: "POST", path: "/api/oauth/login/code" }],
+    flags: [{ name: "--id", value: "string", summary: "Account identity to reauthenticate." }, { name: "--device", value: "boolean", summary: "Codex device login; accepted for already-device-native kimi, nous and github-copilot." }, { name: "--code", value: "string", summary: "Use - to read the short-lived authorization code from stdin." }, { name: "--no-wait", value: "boolean", summary: "Return after starting the flow." }, { name: "--json", value: "boolean", summary: "Emit login instructions or completion state." }], mutates: true, json: "payload",
+    details: ["Alias of account login with --reauth. openai, codex and chatgpt address the pool; native main uses account main reauth. Human completes authorization; keep returned login material out of transcripts. Kiro --method cannot be combined with reauth."],
+  },
+  {
+    command: ["account", "code"], summary: "Submit a login redirect or authorization code from stdin.",
+    usage: "ocx account code <provider> [--flow <flow-id>] [--code -] [--json]",
+    routes: [{ method: "POST", path: "/api/codex-auth/login/code" }, { method: "POST", path: "/api/oauth/login/code" }],
+    flags: [{ name: "--flow", value: "string", summary: "Required for openai, codex or chatgpt pool flows." }, { name: "--code", value: "string", summary: "Use - for stdin; omission also reads stdin." }, { name: "--json", value: "boolean", summary: "Emit submission receipt." }], mutates: true, json: "payload",
+    details: ["A short-lived credential is a human handoff. Legacy positional/argv code input exists but warns about exposure; use stdin and never echo it."],
+  },
+  {
+    command: ["account", "cancel"], summary: "Cancel a pending account login flow.",
+    usage: "ocx account cancel <provider> [--flow <flow-id>] [--json]",
+    routes: [{ method: "POST", path: "/api/codex-auth/login/cancel" }, { method: "POST", path: "/api/oauth/login/cancel" }],
+    flags: [{ name: "--flow", value: "string", summary: "Required for Codex; selects a native Kiro flow when supplied." }, { name: "--json", value: "boolean", summary: "Emit cancellation receipt." }], mutates: true, json: "payload",
+    details: ["Codex cancellation sends flowId. Other providers send provider; Kiro additionally forwards a supplied flowId."],
+  },
+  {
+    command: ["account", "reset-credits"], summary: "Read Codex reset-credit state, or explicitly consume one with operator authorization.",
+    usage: "ocx account reset-credits <account-id|main> [--consume --yes [--operation-id <uuid>]] [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/reset-credits" }, { method: "POST", path: "/api/codex-auth/reset-credits/consume" }],
+    flags: [{ name: "--consume", value: "boolean", summary: "Spend a reset credit; requires operator intent and --yes." }, { name: "--yes", value: "boolean", summary: "Confirm consumption." }, { name: "--operation-id", value: "string", summary: "UUIDv4 retry identity; only valid with --consume." }, { name: "--json", value: "boolean", summary: "Emit reset-credit state or receipt." }], mutates: true, json: "payload",
+    details: ["A bare invocation reads only. main maps to __main__; reads never consume a credit. This does not control credits-after-limit settings."],
+  },
+  {
+    command: ["account", "main", "doctor"], summary: "Diagnose native Codex login profile storage and recovery state.",
+    usage: "ocx account main doctor [--json]", routes: [{ method: "GET", path: "/api/native-main-profiles/doctor" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit diagnosis; this command also prints JSON by default." }], mutates: false, json: "payload",
+    details: ["Reports the physical login in the server's effective CODEX_HOME, independently of pool account selection."],
+  },
+  {
+    command: ["account", "main", "list"], summary: "List encrypted native Codex login profiles.",
+    usage: "ocx account main list [--json]", routes: [{ method: "GET", path: "/api/native-main-profiles" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit public profile metadata, not stored credentials." }], mutates: false, json: "payload",
+  },
+  {
+    command: ["account", "main", "register"], summary: "Register the current physical Codex login as an encrypted profile.",
+    usage: "ocx account main register <label> [--json]", routes: [{ method: "POST", path: "/api/native-main-profiles/register" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the registration receipt." }], mutates: true, json: "payload",
+    details: ["Captures the current login in the effective CODEX_HOME; it does not start a new login or select a pool account."],
+  },
+  {
+    command: ["account", "main", "add"], summary: "Add a native login profile through a human-operated official Codex login.",
+    usage: "ocx account main add <label>",
+    routes: [{ method: "POST", path: "/api/native-main-profiles/stage" }, { method: "POST", path: "/api/native-main-profiles/stage/heartbeat" }, { method: "POST", path: "/api/native-main-profiles/stage/finish" }, { method: "POST", path: "/api/native-main-profiles/stage/cancel" }],
+    flags: [], mutates: true, json: "none",
+    details: ["Human handoff: runs official Codex login locally in the server-provided restricted staging home, maintains a writer lease and encrypts the result. No --json, --yes or --rollback mode. Cleanup failure requires account main doctor; never expose writer tokens or credential files."],
+  },
+  {
+    command: ["account", "main", "reauth", "status"], summary: "Read an existing same-identity native-main reauthentication flow.",
+    usage: "ocx account main reauth status --flow <id> [--json]", routes: [{ method: "GET", path: "/api/codex-auth/main/reauth-device" }],
+    flags: [{ name: "--flow", value: "string", required: true, summary: "Flow ID returned by the human-started reauthentication." }, { name: "--json", value: "boolean", summary: "Emit flow state; pending state may include human login material." }], mutates: false, json: "payload",
+  },
+  {
+    command: ["account", "main", "reauth", "cancel"], summary: "Cancel a native-main reauthentication flow.",
+    usage: "ocx account main reauth cancel --flow <id> [--json]", routes: [{ method: "DELETE", path: "/api/codex-auth/main/reauth-device" }],
+    flags: [{ name: "--flow", value: "string", required: true, summary: "Flow ID to cancel." }, { name: "--json", value: "boolean", summary: "Emit cancellation state." }], mutates: true, json: "payload",
+  },
+  {
+    command: ["account", "main", "switch"], summary: "Switch the physical Codex App/CLI login to a registered profile.",
+    usage: "ocx account main switch <profile-id-or-label> --yes [--json]", routes: [{ method: "POST", path: "/api/native-main-profiles/switch" }],
+    flags: [{ name: "--yes", value: "boolean", required: true, summary: "Confirm the operator has closed Codex App/CLI." }, { name: "--json", value: "boolean", summary: "Emit the native-login switch receipt." }], mutates: true, json: "payload",
+    details: ["Changes the effective CODEX_HOME login, independently of account use openai. The operator must stop Codex first and restart it afterwards; no automatic restart is performed."],
+  },
+  {
+    command: ["account", "main", "recover"], summary: "Recover an interrupted native-login profile transaction.",
+    usage: "ocx account main recover [--rollback --yes] [--json]", routes: [{ method: "POST", path: "/api/native-main-profiles/recover" }],
+    flags: [{ name: "--rollback", value: "boolean", summary: "Restore the previous login; requires --yes." }, { name: "--yes", value: "boolean", summary: "Confirm Codex App/CLI is stopped for rollback." }, { name: "--json", value: "boolean", summary: "Emit recovery outcome." }], mutates: true, json: "payload",
+    details: ["Even without --rollback this calls recovery with rollback:false; it is not the doctor read. Rollback writes the native login only after explicit confirmation."],
+  },
+];
diff --git a/src/cli/capabilities-agents-routing.ts b/src/cli/capabilities-agents-routing.ts
new file mode 100644
index 00000000000..ff50690653d
--- /dev/null
+++ b/src/cli/capabilities-agents-routing.ts
@@ -0,0 +1,314 @@
+import type { Capability } from "./capability-types";
+
+export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["agent", "status"],
+    usage: "ocx agent status [--json]",
+    summary: "Read agent mode, delegation, effort caps, roster, fallback and sidecars.",
+    routes: [{"method": "GET", "path": "/api/v2"}, {"method": "GET", "path": "/api/injection-model"}, {"method": "GET", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/subagent-models"}, {"method": "GET", "path": "/api/subagent-model-fallback"}, {"method": "GET", "path": "/api/sidecar-settings"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: [],
+  },
+  {
+    command: ["agent", "effort"],
+    usage: "ocx agent effort status [--json]",
+    summary: "Read or set main and subagent effort caps.",
+    routes: [{"method": "GET", "path": "/api/effort-caps"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["set requires at least one cap; a null clears it."],
+  },
+  {
+    command: ["agent", "effort", "set"],
+    usage: "ocx agent effort set [--main <level|->] [--subagent <level|->] [--json]",
+    summary: "Read or set main and subagent effort caps.",
+    routes: [{"method": "PUT", "path": "/api/effort-caps"}],
+    flags: [{"name": "--main", "value": "string", "summary": "Main effort cap; - clears."}, {"name": "--subagent", "value": "string", "summary": "Subagent effort cap; - clears."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["set requires at least one cap; a null clears it."],
+  },
+  {
+    command: ["agent", "subagents"],
+    usage: "ocx agent subagents status [--json]",
+    summary: "Read, replace or clear the ordered featured subagent roster.",
+    routes: [{"method": "GET", "path": "/api/subagent-models"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["At most five models; clear sends an empty roster. agent roster is an alias."],
+  },
+  {
+    command: ["agent", "subagents", "set"],
+    usage: "ocx agent subagents set <model,model...> [--json]",
+    summary: "Read, replace or clear the ordered featured subagent roster.",
+    routes: [{"method": "PUT", "path": "/api/subagent-models"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["At most five models; clear sends an empty roster. agent roster is an alias."],
+  },
+  {
+    command: ["agent", "subagents", "clear"],
+    usage: "ocx agent subagents clear [--json]",
+    summary: "Clear the saved subagents models.",
+    routes: [{"method": "PUT", "path": "/api/subagent-models"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["At most five models; clear sends an empty roster. agent roster is an alias."],
+  },
+  {
+    command: ["agent", "fallback"],
+    usage: "ocx agent fallback status [--json]",
+    summary: "Read, replace or clear fallback models and polling interval.",
+    routes: [{"method": "GET", "path": "/api/subagent-model-fallback"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["set requires models and/or --poll-ms; clear empties the models and may also set --poll-ms."],
+  },
+  {
+    command: ["agent", "fallback", "set"],
+    usage: "ocx agent fallback set [model,model...] [--poll-ms <5000-600000>] [--json]",
+    summary: "Read, replace or clear fallback models and polling interval.",
+    routes: [{"method": "PUT", "path": "/api/subagent-model-fallback"}],
+    flags: [{"name": "--poll-ms", "value": "number", "summary": "Polling interval, 5000-600000 milliseconds."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["set requires models and/or --poll-ms; clear empties the models and may also set --poll-ms."],
+  },
+  {
+    command: ["agent", "fallback", "clear"],
+    usage: "ocx agent fallback clear [--poll-ms <5000-600000>] [--json]",
+    summary: "Clear the saved fallback models.",
+    routes: [{"method": "PUT", "path": "/api/subagent-model-fallback"}],
+    flags: [{"name": "--poll-ms", "value": "number", "summary": "Polling interval, 5000-600000 milliseconds."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["set requires models and/or --poll-ms; clear empties the models and may also set --poll-ms."],
+  },
+  {
+    command: ["agent", "sidecar"],
+    usage: "ocx agent sidecar status [--json]",
+    summary: "Read configured sidecars and candidate models.",
+    routes: [{"method": "GET", "path": "/api/sidecar-settings"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "payload",
+    details: [],
+  },
+  {
+    command: ["agent", "sidecar", "web"],
+    usage: "ocx agent sidecar web (--list | [--model <id|->] [--backend <openai|anthropic|xai|gemini|exa|->] [--reasoning <level>] [--max-descriptions <n>] [--enabled <on|off>]) [--json]",
+    summary: "List web candidates or change the web sidecar.",
+    routes: [{"method": "GET", "path": "/api/sidecar-settings"}, {"method": "PUT", "path": "/api/sidecar-settings"}],
+    flags: [{"name": "--list", "value": "boolean", "summary": "Read candidates only; cannot combine with setting flags."}, {"name": "--model", "value": "string", "summary": "Model selector; - clears."}, {"name": "--backend", "value": "string", "summary": "Backend selector; - clears."}, {"name": "--reasoning", "value": "string", "summary": "Reasoning level."}, {"name": "--max-descriptions", "value": "number", "summary": "Positive description limit."}, {"name": "--enabled", "value": "string", "summary": "on or off."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Without --list at least one setting is required. Stored settings and Codex application outcomes remain distinct."],
+  },
+  {
+    command: ["agent", "sidecar", "vision"],
+    usage: "ocx agent sidecar vision (--list | [--model <id|->] [--backend <openai|anthropic|routed|->] [--reasoning <level>] [--max-descriptions <n>] [--enabled <on|off>]) [--json]",
+    summary: "List vision candidates or change the vision sidecar.",
+    routes: [{"method": "GET", "path": "/api/sidecar-settings"}, {"method": "PUT", "path": "/api/sidecar-settings"}],
+    flags: [{"name": "--list", "value": "boolean", "summary": "Read candidates only; cannot combine with setting flags."}, {"name": "--model", "value": "string", "summary": "Model selector; - clears."}, {"name": "--backend", "value": "string", "summary": "Backend selector; - clears."}, {"name": "--reasoning", "value": "string", "summary": "Reasoning level."}, {"name": "--max-descriptions", "value": "number", "summary": "Positive description limit."}, {"name": "--enabled", "value": "string", "summary": "on or off."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Without --list at least one setting is required. Stored settings and Codex application outcomes remain distinct."],
+  },
+  {
+    command: ["effort"],
+    usage: "ocx effort [status|low|medium|high|xhigh|max|ultra|->] [--json]",
+    summary: "Read effort settings or set the main cap with a shorthand level.",
+    routes: [{"method": "GET", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/injection-model"}, {"method": "PUT", "path": "/api/effort-caps"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Uses the live proxy when available, otherwise local config. Once live is selected, errors never fall back to local writes; set reads back live status and can report partial application.", "The shorthand ocx effort <low|medium|high|xhigh|max|ultra|-> changes only the main cap; unset aliases clear."],
+  },
+  {
+    command: ["effort", "set"],
+    usage: "ocx effort set [--main <level|->] [--subagent <level|->] [--injection <level|->] [--json]",
+    summary: "Set one or more effort fields.",
+    routes: [{"method": "PUT", "path": "/api/effort-caps"}, {"method": "PUT", "path": "/api/injection-model"}, {"method": "GET", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/injection-model"}],
+    flags: [{"name": "--main", "value": "string", "summary": "Main cap; - clears."}, {"name": "--subagent", "value": "string", "summary": "Subagent cap; - clears."}, {"name": "--injection", "value": "string", "summary": "Delegation effort; - clears; also accepts none/minimal."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Local configuration is used when no live proxy is found; runtime failures are not silent offline success."],
+  },
+  {
+    command: ["effort", "clear"],
+    usage: "ocx effort clear [--json]",
+    summary: "Clear both caps while retaining delegation effort.",
+    routes: [{"method": "PUT", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/effort-caps"}, {"method": "GET", "path": "/api/injection-model"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Local configuration is used when no live proxy is found; runtime failures are not silent offline success."],
+  },
+  {
+    command: ["effort", "model"],
+    usage: "ocx effort model <provider/model|model> [--json]",
+    summary: "Inspect a model effort ladder and wire mappings from local configuration.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local configuration/catalog derivation; routes is empty because no management API is called."],
+  },
+  {
+    command: ["v2", "status"],
+    usage: "ocx v2 [status]",
+    summary: "Report local multi-agent mode and Codex feature settings.",
+    routes: [],
+    flags: [],
+    mutates: false,
+    json: "none",
+    details: ["Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.", "This command does not claim to update a remote proxy."],
+  },
+  {
+    command: ["v2", "on"],
+    usage: "ocx v2 on",
+    summary: "Enable the local Codex multi_agent_v2 feature.",
+    routes: [],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.", "Mode/feature changes may resync catalogs; a failed resync does not mean the setting was rolled back."],
+  },
+  {
+    command: ["v2", "off"],
+    usage: "ocx v2 off",
+    summary: "Disable the local Codex multi_agent_v2 feature.",
+    routes: [],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.", "Mode/feature changes may resync catalogs; a failed resync does not mean the setting was rolled back."],
+  },
+  {
+    command: ["v2", "mode"],
+    usage: "ocx v2 mode <v1|default|v2>",
+    summary: "Set local model-catalog multi-agent mode.",
+    routes: [],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.", "Mode/feature changes may resync catalogs; a failed resync does not mean the setting was rolled back."],
+  },
+  {
+    command: ["v2", "keep-native-v1"],
+    usage: "ocx v2 keep-native-v1 <on|off>",
+    summary: "Keep native ChatGPT on v1 while routed models use v2.",
+    routes: [],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.", "Mode/feature changes may resync catalogs; a failed resync does not mean the setting was rolled back."],
+  },
+  {
+    command: ["v2", "threads"],
+    usage: "ocx v2 threads <n>",
+    summary: "Set the local active-mode thread limit (integer at least 1).",
+    routes: [],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.", "This command does not claim to update a remote proxy."],
+  },
+  {
+    command: ["v2", "mode-hint"],
+    usage: "ocx v2 mode-hint <text|--clear>",
+    summary: "Set nonblank local delegation hint text or restore effort-derived policy.",
+    routes: [],
+    flags: [{"name": "--clear", "value": "boolean", "summary": "Unset the hint."}],
+    mutates: true,
+    json: "none",
+    details: ["Local config/CODEX_HOME and official Codex feature transition helpers; no management HTTP or --json mode. Changes affect new sessions.", "This command does not claim to update a remote proxy."],
+  },
+  {
+    command: ["combo", "list"],
+    usage: "ocx combo list [--json]",
+    summary: "List saved combos.",
+    routes: [{"method": "GET", "path": "/api/combos"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "payload",
+    details: [],
+  },
+  {
+    command: ["combo", "show"],
+    usage: "ocx combo show <id> [--json]",
+    summary: "Read one saved combo from the collection.",
+    routes: [{"method": "GET", "path": "/api/combos"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "payload",
+    details: [],
+  },
+  {
+    command: ["combo", "set"],
+    usage: "ocx combo set <id> [--targets <provider/model[:weight],...>] [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->] [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->] [--alias <name|->] [--native-alias] [--display-name <label|->] [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->] [--rename-from <id>] [--json]",
+    summary: "Create, update or rename a combo.",
+    routes: [{"method": "GET", "path": "/api/combos"}, {"method": "PUT", "path": "/api/combos"}],
+    flags: [{"name": "--targets", "value": "string", "summary": "Ordered provider/model[:weight] list; required for creation."}, {"name": "--strategy", "value": "string", "summary": "Routing strategy."}, {"name": "--sticky", "value": "string", "summary": "Round-robin limit 1-100; - resets."}, {"name": "--effort", "value": "string", "summary": "Default effort; - clears."}, {"name": "--effort-mode", "value": "string", "summary": "fallback or force; - resets to fallback."}, {"name": "--alias", "value": "string", "summary": "Alias; - clears."}, {"name": "--native-alias", "value": "boolean", "summary": "Enable native-shaped alias."}, {"name": "--display-name", "value": "string", "summary": "Label; - clears."}, {"name": "--decision-provider", "value": "string", "summary": "JEV provider; - clears."}, {"name": "--decision-model", "value": "string", "summary": "JEV route; - clears; exclusive with provider."}, {"name": "--decision-timeout", "value": "string", "summary": "JEV deadline 1000-120000 ms; - clears."}, {"name": "--rename-from", "value": "string", "summary": "Existing combo ID to rename."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["create and update are aliases of set. Existing fields are read before writing; --targets replaces targets.", "force overrides valid client effort and may increase cost and latency.", "Only the implemented target grammar is supported; full GUI target metadata and routing-profile writes are separate tasks."],
+  },
+  {
+    command: ["combo", "remove"],
+    usage: "ocx combo remove <id> --yes [--json]",
+    summary: "Remove a saved combo after explicit confirmation.",
+    routes: [{"method": "DELETE", "path": "/api/combos"}],
+    flags: [{"name": "--yes", "value": "boolean", "summary": "Confirm deletion.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["delete is an alias; the ID is encoded in the id query parameter."],
+  },
+  {
+    command: ["route", "policy", "list"],
+    usage: "ocx route policy list [--json]",
+    summary: "List saved routing profiles and revisions.",
+    routes: [{"method": "GET", "path": "/api/routing-profiles"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "payload",
+    details: [],
+  },
+  {
+    command: ["route", "policy", "show"],
+    usage: "ocx route policy show <id> [--json]",
+    summary: "Read one saved routing profile.",
+    routes: [{"method": "GET", "path": "/api/routing-profiles"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: false,
+    json: "payload",
+    details: [],
+  },
+  {
+    command: ["route", "policy", "dry-run"],
+    usage: "ocx route policy dry-run <id> [--model-context <tokens>] [--tools] [--image] [--structured-output] [--json]",
+    summary: "Evaluate a saved profile against explicit requirements without changing it.",
+    routes: [{"method": "POST", "path": "/api/routing-profiles/dry-run"}],
+    flags: [{"name": "--model-context", "value": "number", "summary": "Positive context window requirement."}, {"name": "--tools", "value": "boolean", "summary": "Require tools."}, {"name": "--image", "value": "boolean", "summary": "Require image input."}, {"name": "--structured-output", "value": "boolean", "summary": "Require structured output."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["evaluate and dry-run do not save the profile, but their POST can activate Lab and start automation already enabled by local policy. No profile create, update or delete is exposed."],
+  },
+  {
+    command: ["route", "policy", "evaluate"],
+    usage: "ocx route policy evaluate <id> [--model-context <tokens>] [--tools] [--image] [--structured-output] [--json]",
+    summary: "Evaluate a saved profile against explicit requirements without changing it.",
+    routes: [{"method": "POST", "path": "/api/routing-profiles/dry-run"}],
+    flags: [{"name": "--model-context", "value": "number", "summary": "Positive context window requirement."}, {"name": "--tools", "value": "boolean", "summary": "Require tools."}, {"name": "--image", "value": "boolean", "summary": "Require image input."}, {"name": "--structured-output", "value": "boolean", "summary": "Require structured output."}, {"name": "--json", "value": "boolean", "summary": "Emit structured JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["evaluate and dry-run do not save the profile, but their POST can activate Lab and start automation already enabled by local policy. No profile create, update or delete is exposed."],
+  },
+];
diff --git a/src/cli/capabilities-base.ts b/src/cli/capabilities-base.ts
new file mode 100644
index 00000000000..a0eb76c14d6
--- /dev/null
+++ b/src/cli/capabilities-base.ts
@@ -0,0 +1,783 @@
+import type { Capability, HeadCapability } from "./capability-types";
+
+export const HEAD_CAPABILITIES: readonly HeadCapability[] = [
+  {
+    invocations: ["--version", "-v", "version"],
+    summary: "Print the CLI version and exit.",
+    bannerLine: "ocx --version | -v          Print version",
+  },
+  {
+    invocations: ["help", "--help", "-h"],
+    summary: "Print the command list, or one command's usage with `ocx help <command>`.",
+    bannerLine: "ocx help [command]          Show help for a command",
+  },
+];
+
+/**
+ * Capabilities declared so far. Incomplete by design: later phases add verbs.
+ * `ocx capabilities` is the index of what is listed here, not of every CLI command.
+ * A capability must not name a route the command does not actually fetch.
+ */
+export const CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["chatgpt"],
+    summary: "Experimental ChatGPT app-server shim: launch, restore or status (macOS only).",
+    routes: [], flags: [], mutates: true, json: "none",
+    bannerLines: ["ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)"],
+    details: ["Default off; launch requires chatgptDesktop.appServerShim: true. Restore removes the generated launcher."],
+  },
+  {
+    command: ["link","port"],
+    summary: "Allocate a free loopback port for a remote home link.",
+    routes: [],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the selected port as JSON."}],
+    mutates: false,
+    json: "envelope",
+    usage: "ocx link port [--json]",
+    details: ["Local temporary loopback socket allocation; no management API request.","Always emits a CLI-shaped {port} JSON object, even without --json."],
+  },
+  {
+    command: ["link","issue"],
+    summary: "Issue one link credential and record its tunnel metadata.",
+    routes: [{"method":"POST","path":"/api/link/issue"}],
+    flags: [{"name":"--alias","value":"string","required":true,"summary":"SSH host alias for the linked machine."},{"name":"--tunnel-port","value":"number","required":true,"summary":"Remote loopback port for the reverse tunnel."},{"name":"--json","value":"boolean","summary":"Emit the issue result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Human-only handoff: issues a credential and prints its plaintext once. Never capture it in an agent transcript. Requires loopback admin authority; tunnel port must be 1024-65535."],
+  },
+  {
+    command: ["link","status"],
+    summary: "Read link listener and tunnel status.",
+    routes: [{"method":"GET","path":"/api/link/status"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the K16 status payload as JSON."}],
+    mutates: false,
+    json: "payload",
+    usage: "ocx link status [--json]",
+    details: ["Reads live listener/tunnel metadata; when no proxy is found, falls back to the local link store. Always emits JSON."],
+  },
+  {
+    command: ["link","revoke"],
+    summary: "Revoke a link credential and remove its link record.",
+    routes: [{"method":"DELETE","path":"/api/link/{id}"}],
+    flags: [{"name":"--link-id","value":"string","required":true,"summary":"Link id to revoke."},{"name":"--json","value":"boolean","summary":"Emit the revoked link id as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Requires a valid link ID and loopback admin authority. No force-removal option exists.","Always emits a CLI-shaped {linkId} JSON object. Already-revoked link_not_found is idempotent success."],
+    usage: "ocx link revoke --link-id <id> [--json]",
+  },
+  {
+    command: ["remote-workspace","pair"],
+    summary: "Enroll this executor with one Hub using a one-time code from stdin and locally approved roots.",
+    routes: [],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the public local executor status."},{"name":"--pairing-code-stdin","value":"boolean","summary":"Read the one-time pairing code from stdin."},{"name":"--root","value":"string","summary":"Approve an absolute workspace directory; repeatable."},{"name":"--toolchain-root","value":"string","summary":"Approve a read-only toolchain directory; repeatable."},{"name":"--executor-helper","value":"string","summary":"Select a reviewed native helper file."},{"name":"--name","value":"string","summary":"Name this executor."}],
+    mutates: true,
+    json: "payload",
+    details: ["Executor-local state/control; no Hub management API routes.","Pairing consumes a human-provided one-time code from stdin and persists enrollment; approved roots and platform confinement determine capabilities."],
+    usage: "ocx remote-workspace pair <hub-url> --pairing-code-stdin --root <absolute-path> [--root <absolute-path> ...] [--toolchain-root <absolute-directory> ...] [--executor-helper <absolute-file>] [--name <device-name>] [--json]",
+  },
+  {
+    command: ["remote-workspace","agent"],
+    summary: "Keep the paired executor connected to its Hub.",
+    routes: [],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Executor-local state/control; no Hub management API routes.","Maintains the enrolled executor connection to the Hub until interrupted."],
+    usage: "ocx remote-workspace agent",
+  },
+  {
+    command: ["remote-workspace","status"],
+    summary: "Read local executor enrollment and available capabilities without printing credentials.",
+    routes: [],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the public local executor status."}],
+    mutates: false,
+    json: "payload",
+    details: ["Executor-local state/control; no Hub management API routes.","Reports local enrollment and platform/helper capabilities without credentials; not Hub device/runtime/session inventory."],
+    usage: "ocx remote-workspace status [--json]",
+  },
+  {
+    command: ["models","price"],
+    summary: "Read the saved manual price for an exact provider/model selector.",
+    routes: [{"method":"GET","path":"/api/providers/{provider}/model-costs"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit provider, modelId, and cost (null for automatic pricing)."}],
+    mutates: false,
+    json: "envelope",
+    details: ["The provider must be configured; everything after the first slash is the exact upstream model ID."],
+    usage: "ocx models price <provider/model> [--json]",
+  },
+  {
+    command: ["models","set-price"],
+    summary: "Save four manual USD-per-1M-token rates, or restore automatic pricing for one model.",
+    routes: [{"method":"PUT","path":"/api/providers/{provider}/model-costs"}],
+    flags: [{"name":"--input","value":"number","summary":"Input rate; required unless --auto is used."},{"name":"--output","value":"number","summary":"Output rate; required unless --auto is used."},{"name":"--cache-read","value":"number","summary":"Cache read rate; defaults to 0."},{"name":"--cache-write","value":"number","summary":"Cache write rate; defaults to 0."},{"name":"--auto","value":"boolean","summary":"Remove this model's override; cannot be combined with rates."},{"name":"--json","value":"boolean","summary":"Emit the saved price or reset result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Uses the exact upstream model ID after the first slash. Omitted cache rates default to zero; sibling model prices are preserved."],
+    usage: "ocx models set-price <provider/model> (--input <N> --output <N> [--cache-read <N>] [--cache-write <N>]|--auto) [--json]",
+  },
+  {
+    command: ["models","set"],
+    summary: "Save per-model overrides for a routed model, or clear them back to the computed values.",
+    routes: [{"method":"PUT","path":"/api/model-settings"}],
+    flags: [{"name":"--context-window","value":"string","summary":"Context window in tokens; 0 or - clears the override."},{"name":"--modalities","value":"string","summary":"Comma-separated text,image,audio; - clears the override."},{"name":"--reasoning-efforts","value":"string","summary":"Comma-separated ladder; \"\" for no reasoning, - to inherit."},{"name":"--default-reasoning-effort","value":"string","summary":"Ladder member a request inherits when it omits one; - to inherit."},{"name":"--reset","value":"boolean","summary":"Clear every override on this model; cannot be combined with the options above."},{"name":"--json","value":"boolean","summary":"Emit the saved state as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Only routed provider/model selectors are supported. At least one option or --reset is required.","Context 0 or - and modalities/default effort - clear to null; reasoning efforts - restores inheritance while an empty string stores an empty ladder.","--reset clears all four overrides with null and cannot be combined with other settings. A saved-but-catalog-refresh-failed receipt must not be mistaken for an unsaved change."],
+    usage: "ocx models set <provider/model> [--context-window <tokens|0|->] [--modalities <text,image,audio|->] [--reasoning-efforts <levels|->] [--default-reasoning-effort <level|->] [--reset] [--json]",
+  },
+  {
+    command: ["status"],
+    summary: "Proxy status, injection state, and version skew between this CLI and the running proxy.",
+    // No management route: `collectStatus` identity-probes `/healthz` through
+    // `findLiveProxy` and reads local config. Declaring `GET /api/status` here was wrong
+    // -- that route does not exist, and the registry cross-check caught it.
+    routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the status envelope as JSON." }],
+    mutates: false,
+    json: "envelope",
+    details: ["Reads /healthz plus local config; drives no management API route."],
+  },
+  {
+    command: ["resolve"],
+    summary: "One JSON document naming the config home, the effective port, and the identity-checked proxy liveness verdict.",
+    // No management route, same split as status: discovery is the identity-checked
+    // /healthz probe inside findLiveProxy plus local config and the home from
+    // src/config/paths.ts.
+    routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the resolve document as JSON (the shell contract)." }],
+    mutates: false,
+    json: "envelope",
+    details: [
+      "Exit 0 carries a trustworthy verdict (live or proven absent); exit 1 means the CLI could not resolve and a caller must refuse to guess — unknown liveness never reads as absent.",
+      "Built for embedding shells (desktop app): the liveness budgets stay owned by src/server/proxy-liveness.ts.",
+    ],
+  },
+  {
+    command: ["hub","invite"],
+    summary: "Mint a single-use pairing code on a hub and print the exact `ocx connect` line for one more machine.",
+    routes: [],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit code, expiresAt, dataUrl, managementUrl, and command."},{"name":"--data-url","value":"string","summary":"Advertise this data origin instead of hub.dataPublicOrigin or the bind address."},{"name":"--management-url","value":"string","summary":"Confirm the management origin; it must equal hub.managementPublicOrigin."},{"name":"--clients","value":"string","summary":"Pre-select codex and/or claude in the printed connect command."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Hub only: refuses when runtimeRole is not hub, and requires a running attested proxy.","The code is secret, single-use and short-lived; it is bound to hub.managementPublicOrigin and to the connecting machine's loopback browser origin.","The bound browser origin is always printed; when it is not http://localhost:10100 the warning names the port the connecting machine must use.","Refuses when the advertised data origin would be loopback (a loopback or wildcard bind with no hub.dataPublicOrigin and no --data-url) rather than printing a line that dials the other machine itself.","Prints no data-plane token. Remote machines receive their own revocable per-client key from the exchange.","Mints through the attested local pairing-grant route, the same one ocx gui pair uses; no admin token is read."],
+  },
+  {
+    command: ["connect", "rotate"],
+    summary: "Rotate the connected client's data key against the hub, with commit and abort.",
+    // One command drives all three: start returns the new secret once, commit promotes it,
+    // and abort unwinds a rotation that could not be confirmed. They are not separate verbs
+    // because a half-rotation is not a state an operator should be able to leave behind.
+    routes: [
+      { method: "POST", path: "/api/keys/rotate" },
+      { method: "POST", path: "/api/keys/rotate/commit" },
+      { method: "DELETE", path: "/api/keys/rotate" },
+    ],
+    flags: [
+      { name: "--pairing-code-stdin", value: "boolean", summary: "Read a one-time pairing code from stdin as the rotation authority." },
+      { name: "--admin-token-stdin", value: "boolean", summary: "Read the hub admin token from stdin as the rotation authority." },
+      { name: "--json", value: "boolean", summary: "Emit the rotation result as JSON." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: [
+      "Requires transient authority on stdin; the credential is never persisted or echoed.",
+      "A rotation left pending by a crash is resumed here — startup and status stop rather than guess which key generation is live.",
+    ],
+  },
+  {
+    command: ["capabilities"],
+    summary: "List the declared CLI capabilities and the management routes they drive.",
+    routes: [],
+    flags: [
+      { name: "--json", value: "boolean", summary: "Emit the full capability table as JSON." },
+      { name: "--mutating-only", value: "boolean", summary: "Restrict output to capabilities that mutate state." },
+      { name: "--route", value: "string", summary: "Show which capabilities drive a management route." },
+    ],
+    mutates: false,
+    json: "envelope",
+    details: ["Start here when driving ocx programmatically: it is the declared surface index, not a complete verb list."],
+  },
+  {
+    command: ["provider","list"],
+    summary: "Configured providers with connectivity and selected models.",
+    routes: [],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the provider list as JSON."},{"name":"--jsonl","value":"boolean","summary":"Emit one configured provider per JSON line."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local config and registry read, not GET /api/providers. --json and --jsonl are mutually exclusive."],
+    usage: "ocx provider list [--json|--jsonl]",
+  },
+  {
+    command: ["provider","resets"],
+    summary: "Recently detected quota resets and whether reset notifications are enabled.",
+    routes: [{"method":"GET","path":"/api/quota-resets"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit reset events as JSON."},{"name":"--limit","value":"number","summary":"Limit returned events; defaults to 20, capped at 100."}],
+    mutates: false,
+    json: "payload",
+    usage: "ocx provider resets [--limit <n>] [--json]",
+    details: [],
+  },
+  {
+    command: ["provider","keychain"],
+    summary: "Move a provider's API key into the OS keychain, restore it, or report where it lives.",
+    routes: [{"method":"GET","path":"/api/providers/keychain"},{"method":"POST","path":"/api/providers/keychain"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the keychain status or result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["status reads by provider name; store/restore POST {name,action}. These move an existing secret between config and OS keychain; keep credential material out of transcripts."],
+    usage: "ocx provider keychain <name> [status|store|restore] [--json]",
+  },
+  {
+    command: ["companion"],
+    summary: "Inspect and configure menu-bar and widget companion usage settings.",
+    routes: [{"method":"GET","path":"/api/companion/settings"},{"method":"PUT","path":"/api/companion/settings"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit companion settings as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Mixed family: show/default reads settings; set key=value assignments and reset write settings.","Values are parsed as JSON when valid; timeline is not implemented by this handler."],
+    usage: "ocx companion show [--json] | ocx companion set <key>=<value> [...] [--json] | ocx companion reset [--json]",
+  },
+  {
+    command: ["account","login"],
+    summary: "Log in to an OAuth provider; Kiro can add a native device account.",
+    routes: [{"method":"POST","path":"/api/oauth/login"},{"method":"GET","path":"/api/oauth/status"},{"method":"POST","path":"/api/oauth/login/code"},{"method":"POST","path":"/api/codex-auth/login"},{"method":"GET","path":"/api/codex-auth/login-status"},{"method":"POST","path":"/api/codex-auth/login/code"}],
+    flags: [{"name":"--id","value":"string","summary":"Account ID; provider OAuth requires --reauth when supplied."},{"name":"--reauth","value":"boolean","summary":"Reauthenticate an existing account."},{"name":"--device","value":"boolean","summary":"Codex device flow; accepted for already-device-native kimi, nous and github-copilot."},{"name":"--method","value":"string","summary":"Kiro only: builder-id, google or github; add-only and incompatible with --reauth, --id, --device or --code."},{"name":"--code","value":"string","summary":"Use - to read authorization material from stdin."},{"name":"--no-wait","value":"boolean","summary":"Return after flow start."},{"name":"--json","value":"boolean","summary":"Emit the command result as JSON."}],
+    mutates: true,
+    json: "payload",
+    usage: "ocx account login <provider> [--id <account-id>] [--reauth] [--device] [--method <builder-id|google|github>] [--code -] [--no-wait] [--json]",
+    details: ["openai, codex and chatgpt address the Codex pool. Native main uses the separate account main reauth flow.","Login is a human authorization handoff. Codes, verification material and credentials must not be copied into agent transcripts. Legacy argv code input warns about exposure; use stdin.","No --open-browser or --live flag is implemented. Provider OAuth --id requires --reauth; --method is Kiro add-only."],
+  },
+  {
+    command: ["account","history"],
+    summary: "Cached quota observations for one stored Codex pool account.",
+    routes: [{"method":"GET","path":"/api/codex-auth/quota/history"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the bounded observation history."},{"name":"--limit","value":"number","summary":"Return the newest 1 to 200 observations."}],
+    mutates: false,
+    json: "payload",
+    details: ["Use account history openai <pool-account-id>. Reads cached observations only; no refresh or warmup. Native main is not included."],
+    usage: "ocx account history openai <pool-account-id> [--limit <1-200>] [--json]",
+  },
+  {
+    command: ["account","main","reauth"],
+    summary: "Reauthenticate the native main Codex login with a device code (#3898); headless hubs need no Codex App or keyring.",
+    routes: [{"method":"POST","path":"/api/codex-auth/main/reauth-device"},{"method":"GET","path":"/api/codex-auth/main/reauth-device"},{"method":"DELETE","path":"/api/codex-auth/main/reauth-device"}],
+    flags: [{"name":"--device","value":"boolean","summary":"Run the device-code flow (the only reauth mode)."},{"name":"--no-wait","value":"boolean","summary":"Print the flow handle and code without waiting for completion."},{"name":"--flow","value":"string","summary":"Flow id for status and cancel."},{"name":"--json","value":"boolean","summary":"Emit the flow status as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Same-identity native main device reauthentication; pool login endpoints are separate. Human authorization is required and credentials are never printed.","Start requires --device; --no-wait returns a flow handle. Follow with account main reauth status --flow <id> or account main reauth cancel --flow <id>. Status/cancel require --flow and reject --device/--no-wait.","Returned verification URLs and device codes are human handoff material; keep them out of agent transcripts."],
+    usage: "ocx account main reauth --device [--no-wait] [--json]",
+  },
+  {
+    command: ["account","list"],
+    summary: "List live Codex, OAuth and API-key accounts with optional quota observations.",
+    routes: [{"method":"GET","path":"/api/oauth/providers"},{"method":"GET","path":"/api/codex-auth/accounts"},{"method":"GET","path":"/api/codex-auth/active"},{"method":"GET","path":"/api/oauth/accounts"},{"method":"GET","path":"/api/providers/keys"}],
+    flags: [{"name":"--all","value":"boolean","summary":"Include notes for providers with no stored accounts."},{"name":"--quota","value":"boolean","summary":"Include quota observations; OAuth may probe upstream."},{"name":"--refresh","value":"boolean","summary":"With --quota, bypass quota cache; otherwise has no effect."},{"name":"--json","value":"boolean","summary":"Emit the command result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Omitting provider discovers OAuth providers and includes configured families. JSON is {accounts,notes}, not a raw server account array.","Default listing is observational. --quota can probe provider quotas; --refresh is only acted on together with --quota. A refresh observation is not pending-account validation consent."],
+    usage: "ocx account list [provider] [--all] [--quota [--refresh]] [--json]",
+  },
+  {
+    command: ["account","import-orca"],
+    summary: "Preview or register read-only links to Orca-managed Codex accounts without another login.",
+    routes: [],
+    flags: [{"name":"--source","value":"string","required":true,"summary":"Orca data directory containing codex-accounts."},{"name":"--registry","value":"string","required":true,"summary":"The chosen Orca profile's orca-data.json account registry."},{"name":"--apply","value":"boolean","summary":"Register new accounts; requires a stopped proxy. Default is preview."},{"name":"--json","value":"boolean","summary":"Emit counts and fixed invalid-reason codes without credentials or source paths."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Local files only; never copies refresh tokens or changes Orca authentication files.","Skips existing ChatGPT identities. New accounts remain pending until dashboard validation.","Orca must keep the source login available and refreshed; a missing or expired source fails closed.","Mixed eligible and invalid entries exit successfully; an all-invalid result exits nonzero."],
+    usage: "ocx account import-orca --source <orca-data-directory> --registry <orca-data.json> [--apply] [--json]",
+  },
+  {
+    command: ["account","refresh"],
+    summary: "Refresh account quotas without model validation; pending Codex accounts require dashboard consent.",
+    routes: [{"method":"POST","path":"/api/codex-auth/accounts/refresh"},{"method":"GET","path":"/api/codex-auth/active"},{"method":"GET","path":"/api/provider-quotas"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the refresh result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["CLI/admin-token refreshes only observe usage. After quota recovery, a human must click Refresh quotas in the dashboard to authorize model validation. Do not mint a GUI session to work around this consent boundary."],
+    usage: "ocx account refresh <provider> [--json]",
+  },
+  {
+    command: ["account","grok-reset-coupons"],
+    summary: "Inspect or redeem Grok billing reset coupons; redemption is journaled and idempotent.",
+    routes: [{"method":"GET","path":"/api/grok/reset-coupons"},{"method":"POST","path":"/api/grok/reset-coupons/consume"}],
+    flags: [{"name":"--consume","value":"boolean","summary":"Redeem one reset coupon; requires --yes."},{"name":"--yes","value":"boolean","summary":"Explicit confirmation required by --consume."},{"name":"--token-id","value":"string","summary":"Redeem a specific reset token instead of the default selection."},{"name":"--operation-id","value":"string","summary":"UUIDv4 making a redemption idempotent: retries replay the journaled outcome."},{"name":"--json","value":"boolean","summary":"Emit the coupon list or redemption result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Without --consume this is a read: remaining coupons and their validity windows.","The operation is journaled before the upstream call, so retrying the same --operation-id replays the recorded outcome instead of spending a second coupon."],
+    usage: "ocx account grok-reset-coupons [account-id] [--consume --yes [--token-id <token-id>] [--operation-id <uuid>]] [--json]",
+  },
+  {
+    command: ["usage"],
+    summary: "Token and estimated-cost report over a time range.",
+    routes: [{"method":"GET","path":"/api/usage"}],
+    flags: [{"name":"--range","value":"string","summary":"today | 1d | 7d | 30d | all; default 30d."},{"name":"--surface","value":"string","summary":"all | codex | claude | grok; default all."},{"name":"--since","value":"string","summary":"Inclusive epoch milliseconds or ISO datetime with timezone; requires --until."},{"name":"--until","value":"string","summary":"Inclusive end; requires --since. Custom bounds override --range."},{"name":"--provider","value":"string","summary":"Filter provider."},{"name":"--model","value":"string","summary":"Filter model."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["Alias of observe usage. Connected clients instead read their own enrolled-key Hub report through /v1/usage; this is not whole-Hub management usage.","Custom bounds require the server to confirm customWindow, since and until."],
+    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>] [--provider <name>] [--model <id>] [--json]",
+  },
+  {
+    command: ["account","pause"],
+    summary: "Exclude one account in a Codex, Anthropic or supported generic OAuth pool from automatic selection.",
+    routes: [{"method":"GET","path":"/api/codex-auth/accounts"},{"method":"PUT","path":"/api/codex-auth/accounts/pause"},{"method":"GET","path":"/api/oauth/accounts"},{"method":"PUT","path":"/api/oauth/accounts/pause"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the pause result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Codex pause unbinds pinned threads and selects a fallback when possible; with no fallback, a paused-but-selected Codex account still receives requests. Anthropic and generic OAuth pause exclude the account from new requests, failover and refresh, and an all-paused pool answers 403. Credentials and health are preserved; already-sent turns are not cancelled."],
+    usage: "ocx account pause <provider> <account-id|alias|main> [--json]",
+  },
+  {
+    command: ["account","resume"],
+    summary: "Return a paused account to a Codex, Anthropic or supported generic OAuth pool.",
+    routes: [{"method":"GET","path":"/api/codex-auth/accounts"},{"method":"PUT","path":"/api/codex-auth/accounts/pause"},{"method":"GET","path":"/api/oauth/accounts"},{"method":"PUT","path":"/api/oauth/accounts/pause"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the resume result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    usage: "ocx account resume <provider> <account-id|alias|main> [--json]",
+    details: [],
+  },
+  {
+    command: ["account","pause-exhausted"],
+    summary: "Pause every Codex account whose quota is spent.",
+    routes: [{"method":"PUT","path":"/api/codex-auth/accounts/pause-exhausted"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit paused ids and the checked/failed counts as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Only Codex account pools are supported. Refreshes quota and may partially fail; nonzero failedAccountCount exits 1 and sets ok:false."],
+    usage: "ocx account pause-exhausted <provider> [--json]",
+  },
+  {
+    command: ["account","strategy"],
+    summary: "Show or set how an account pool picks the next account.",
+    routes: [{"method":"GET","path":"/api/pool/settings"},{"method":"PUT","path":"/api/pool/settings"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the applied strategy and sticky limit as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["A bare invocation reads and never writes.","The APPLIED value is echoed, not the requested one, so a server-side normalization stays visible.","Values are not re-validated in the CLI: the server owns the strategy names and the 1-100 sticky bound.","One route answers for every pool kind and declares which fields that kind honours in `supported`, so an unsupported field is a stated null rather than an absence. `anthropic` alone carries `quotaWindow`. Generic-provider settings steer selection only while `pool.kernel` is on. The legacy per-pool paths still work and are unchanged."],
+    usage: "ocx account strategy <provider> [quota|round-robin|fill-first|least-loaded|reset-first] [--json]",
+  },
+  {
+    command: ["account","sticky"],
+    summary: "Show or set how many consecutive requests stay on one account.",
+    routes: [{"method":"GET","path":"/api/pool/settings"},{"method":"PUT","path":"/api/pool/settings"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the applied strategy and sticky limit as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Only meaningful under the sticky-capable strategies; the pool strategy is the other half of this setting."],
+    usage: "ocx account sticky <provider> [1-100] [--json]",
+  },
+  {
+    command: ["account","routes"],
+    summary: "Read, replace, or clear Anthropic OAuth model account routes.",
+    routes: [{"method":"GET","path":"/api/pool/settings"},{"method":"PUT","path":"/api/pool/settings"}],
+    flags: [{"name":"--file","value":"string","summary":"Read a bounded JSON route array from a local file."},{"name":"--clear","value":"boolean","summary":"Remove the stored routes."},{"name":"--json","value":"boolean","summary":"Emit the unified settings response as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Only anthropic is supported. Omitted --file/--clear reads. --clear sends routes:null; file and clear are mutually exclusive. The local JSON file must be a regular file of at most 64 KiB; the server validates its route array."],
+    usage: "ocx account routes anthropic [--file <json-file>|--clear] [--json]",
+  },
+  {
+    command: ["account","auto-switch"],
+    summary: "Show or set the usage percentage at which a pool moves to another account.",
+    routes: [{"method":"GET","path":"/api/codex-auth/active"},{"method":"PUT","path":"/api/codex-auth/auto-switch"},{"method":"GET","path":"/api/oauth/accounts/pool"},{"method":"PUT","path":"/api/oauth/accounts/pool"},{"method":"GET","path":"/api/oauth/accounts"},{"method":"PUT","path":"/api/oauth/accounts/auto-switch"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the stored threshold and whether it is applied."},{"name":"--account","value":"string","summary":"Anthropic account ID; inherit restores the pool default, off stores zero."}],
+    mutates: true,
+    json: "envelope",
+    details: ["An explicit action is required; status is the read-only action. A bare invocation is a usage error.","on stores 80, off stores 0 and threshold accepts 0-100. Anthropic requires --account <id> for every action and alone accepts inherit, which sends null. Codex and generic OAuth accept neither --account nor inherit.","Generic pool inert:true means stored but not applied; false means applied; absent means support is unknown. API-key providers are refused."],
+    usage: "ocx account auto-switch <provider> <status|on|off|threshold <0-100>|inherit> [--account <id>] [--json]",
+  },
+  {
+    command: ["logs"],
+    summary: "Recent request log rows, filterable by provider, model, conversation, account, and status.",
+    routes: [{"method":"GET","path":"/api/logs"}],
+    flags: [{"name":"--provider","value":"string","summary":"Filter provider, including failover attempts."},{"name":"--model","value":"string","summary":"Filter model, including failover attempts."},{"name":"--status","value":"string","summary":"Filter status code."},{"name":"--conversation","value":"string","summary":"Filter conversation ID."},{"name":"--conversationId","value":"string","summary":"Alias of --conversation."},{"name":"--account","value":"string","summary":"Filter stable account log label."},{"name":"--limit","value":"number","summary":"Positive row limit; default 200."},{"name":"--follow","value":"boolean","summary":"Poll for new rows; add --jsonl to emit JSONL."},{"name":"-f","value":"boolean","summary":"Alias of --follow."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--jsonl","value":"boolean","summary":"Emit one row per JSON line; exclusive with --json."}],
+    mutates: false,
+    json: "payload",
+    details: ["Snapshot read or follow; --follow refuses --json and supports --jsonl. --conversationId and -f are accepted aliases.","Nested explain reads recorded decisions; rebuild-index and index-status touch the local derived index and have separate declarations."],
+    usage: "ocx logs [--provider <name>] [--model <id>] [--status <code>] [--conversation <id>] [--account <label>] [--limit <n>] [--follow] [--json|--jsonl]",
+  },
+  {
+    command: ["storage","report"],
+    summary: "Disk usage under CODEX_HOME, with the log-guard protection report.",
+    routes: [{"method":"GET","path":"/api/storage"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the storage report as JSON."}],
+    mutates: false,
+    json: "payload",
+    bannerLines: ["ocx storage                 Storage report (default subcommand)"],
+    usage: "ocx storage report [--json]",
+    details: [],
+  },
+  {
+    command: ["storage","cleanup"],
+    summary: "Preview or delete the oldest archived sessions by percentage.",
+    routes: [{"method":"POST","path":"/api/storage/cleanup/preview"},{"method":"POST","path":"/api/storage/cleanup"}],
+    flags: [{"name":"--percent","value":"number","summary":"Portion of the oldest archived sessions to target (0-100)."},{"name":"--mode","value":"string","summary":"quarantine (recoverable from trash) or permanent."},{"name":"--yes","value":"boolean","summary":"Required to actually delete; without it this is a preview."},{"name":"--json","value":"boolean","summary":"Emit the preview or result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Without `--yes` it prints what WOULD be freed and exits 0 having changed nothing.","There is no interactive confirmation: a prompt an agent can answer is not a safety boundary.","`--mode quarantine` moves files to trash, so `storage trash restore` can undo it; `permanent` cannot be undone."],
+    usage: "ocx storage cleanup --percent <0-100> [--mode <quarantine|permanent>] [--yes] [--json]",
+  },
+  {
+    command: ["storage","trash"],
+    summary: "List quarantined cleanup batches, or restore one.",
+    routes: [{"method":"GET","path":"/api/storage/trash"},{"method":"POST","path":"/api/storage/trash/restore"}],
+    flags: [{"name":"--yes","value":"boolean","summary":"Required for restore, which moves files and reconciles database rows."},{"name":"--json","value":"boolean","summary":"Emit the trash list or restore result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Restore fails with a named 409 when the destination already exists, rather than overwriting it.","Mixed family: list/default reads quarantine batches; restore moves files and reconciles database rows only with --yes."],
+    usage: "ocx storage trash [list] [--json] | ocx storage trash restore <entry-id> --yes [--json]",
+  },
+  {
+    command: ["storage","policy"],
+    summary: "Show, change, or run the automatic archived-session cleanup policy.",
+    routes: [{"method":"GET","path":"/api/storage/cleanup-policy"},{"method":"PUT","path":"/api/storage/cleanup-policy"},{"method":"POST","path":"/api/storage/cleanup-policy/run"}],
+    flags: [{"name":"--enabled","value":"string","summary":"true or false."},{"name":"--percent","value":"number","summary":"Portion of oldest archived sessions each run targets."},{"name":"--mode","value":"string","summary":"quarantine or permanent."},{"name":"--schedule","value":"string","summary":"startup, daily, weekly, or manual."},{"name":"--yes","value":"boolean","summary":"Required for `policy run`, which deletes immediately."},{"name":"--json","value":"boolean","summary":"Emit the policy or run state as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["`policy set` never enables implicitly: omitting `--enabled` keeps the stored value.","`policy run` forces a run regardless of schedule, so it needs `--yes`.","Mixed family: show/default reads; set persists submitted fields; run requires --yes and starts immediate cleanup. At least one setting is required by set."],
+    usage: "ocx storage policy [show] [--json] | ocx storage policy set [--enabled <true|false>] [--percent <1-100>] [--mode <quarantine|permanent>] [--schedule <startup|daily|weekly|manual>] [--json] | ocx storage policy run --yes [--json]",
+  },
+  {
+    command: ["inspect", "config"],
+    summary: "The effective merged configuration the proxy is running.",
+    routes: [{ method: "GET", path: "/api/config" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the config as JSON." }],
+    mutates: false,
+    json: "payload",
+  },
+  {
+    command: ["inspect", "catalog"],
+    summary: "The generated model catalog served to clients.",
+    routes: [{ method: "GET", path: "/api/catalog" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the catalog as JSON." }],
+    mutates: false,
+    json: "payload",
+  },
+  {
+    command: ["inspect", "routing-analytics"],
+    summary: "Aggregate routing outcomes per provider and model.",
+    routes: [{ method: "GET", path: "/api/routing-analytics" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the analytics payload as JSON." }],
+    mutates: false,
+    json: "payload",
+  },
+  {
+    command: ["inspect", "pacing"],
+    summary: "Request-pacing state for one provider or all of them.",
+    routes: [{ method: "GET", path: "/api/provider-request-pacing" }],
+    flags: [
+      { name: "--name", value: "string", summary: "Restrict to one provider; omitted means every provider." },
+      { name: "--json", value: "boolean", summary: "Emit the pacing state as JSON." },
+    ],
+    mutates: false,
+    json: "payload",
+    details: ["An unknown provider name is a 404 rather than an empty result."],
+  },
+  {
+    command: ["inspect", "key-providers"],
+    summary: "Providers that authenticate with an API key rather than OAuth.",
+    routes: [{ method: "GET", path: "/api/key-providers" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the provider list as JSON." }],
+    mutates: false,
+    json: "payload",
+  },
+  {
+    command: ["inspect", "codex-prompt"],
+    summary: "The Codex system prompt state, or the prompt text itself.",
+    routes: [
+      { method: "GET", path: "/api/codex-prompt" },
+      { method: "GET", path: "/api/codex-prompt/text" },
+    ],
+    flags: [
+      { name: "--text", value: "boolean", summary: "Print the prompt body verbatim instead of its metadata." },
+      { name: "--json", value: "boolean", summary: "Emit the prompt metadata as JSON." },
+    ],
+    mutates: false,
+    json: "payload",
+    details: ["Read-only by design: the six mutating prompt routes require a dashboard session."],
+  },
+  {
+    command: ["inspect", "client-config"],
+    summary: "The generated configuration snippet for a supported client.",
+    routes: [{ method: "GET", path: "/api/client-config" }],
+    flags: [
+      { name: "--client", value: "string", summary: "Required client id; the route names every accepted value on error." },
+      { name: "--json", value: "boolean", summary: "Emit the snippet payload as JSON." },
+    ],
+    mutates: false,
+    json: "payload",
+  },
+  {
+    command: ["inspect", "star"],
+    summary: "Whether this repository is starred by the signed-in GitHub account.",
+    // GET only, permanently. The POST spends the operator identity and requires a dashboard
+    // session precisely so an agent cannot answer that question for them.
+    routes: [{ method: "GET", path: "/api/github/star" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the star status as JSON." }],
+    mutates: false,
+    json: "payload",
+    details: ["Starring is never available from the CLI; the verb says so rather than offering a flag that cannot work."],
+  },
+  {
+    command: ["inspect", "windows-tray"],
+    summary: "Windows tray helper state.",
+    routes: [{ method: "GET", path: "/api/windows-tray" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the tray state as JSON." }],
+    mutates: false,
+    json: "payload",
+  },
+  {
+    command: ["system","codex-app-server"],
+    summary: "Codex app-server reachability and process state, as the dashboard sees it.",
+    routes: [{"method":"GET","path":"/api/system/codex-app-server"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the app-server state as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["The GUI reads this state directly; without a verb an agent could not tell whether the Codex app-server was reachable at all."],
+    usage: "ocx system codex-app-server [--json]",
+  },
+  {
+    command: ["system","codex-cli-update","check"],
+    summary: "Inspect a configured Codex CLI candidate and its ownership provenance.",
+    routes: [],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the redacted provenance report as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Proof-bound published-launcher context authenticates the configured candidate snapshot, not successful Codex execution; this check does not attest or admit a selected runtime.","On Windows this first slice performs no candidate or configuration filesystem I/O: only a proof-captured absolute environment candidate can receive lexical app-bundle or version-manager labels; every other Windows candidate fails closed.","Makes no package-registry request.","Does not execute Codex or npm, install or repair software, control a process, or write configuration or cache state."],
+    usage: "ocx system codex-cli-update check [--json]",
+  },
+  {
+    command: ["system","codex-cli-update","attest"],
+    summary: "Observe the selected or explicitly named Windows npm Codex installation files without enabling updates.",
+    routes: [],
+    flags: [{"name":"--candidate","value":"string","summary":"Absolute npm codex.cmd or package bin/codex.js path; all four paths are all-or-none."},{"name":"--npm-prefix","value":"string","summary":"Absolute prefix containing node_modules/@openai/codex."},{"name":"--npm-cli","value":"string","summary":"Absolute node_modules/npm/bin/npm-cli.js path."},{"name":"--node","value":"string","summary":"Absolute node.exe path; observed, never executed."},{"name":"--json","value":"boolean","summary":"Emit the path-free installation identity observation."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Opt-in Windows x64 local-volume inspection using held native file handles; refuses reparse points, active writers and unsupported layouts.","Without explicit paths, the proof-bound launcher snapshot identifies the selected candidate: the configured CODEX_CLI_PATH or the first codex on the captured PATH, with an OpenCodex wrapper resolving to its codex.opencodex-real backing. Discovery only proposes paths; the held-handle observation remains the authority.","Success binds observed file identities and bytes, not selected-runtime admission or installer ownership.","selectionAttested, managed and applyAllowed remain false. The digest is an observation, not a durable update permit.","Does not run the named Codex/npm/Node files, query a registry, install software, control processes or persist state."],
+    usage: "ocx system codex-cli-update attest [--candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path>] [--json]",
+  },
+  {
+    command: ["system","codex-restart"],
+    summary: "Restart the Codex desktop app and app-servers.",
+    routes: [{"method":"POST","path":"/api/system/codex-restart"}],
+    flags: [{"name":"--yes","value":"boolean","summary":"Required: fully quits and relaunches the operator's Codex desktop app, which may discard unsaved composer drafts, model-picker selections, and pending approval prompts; also restarts its app-servers."},{"name":"--json","value":"boolean","summary":"Emit the restart result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["`sync --restart-codex` is not a substitute: it restarts only as a side effect after a catalog or cache write, so it cannot restart a healthy install on request.","Restarts the Codex desktop app as well as the app-servers, through the same module the CLI uses. When the proxy itself runs inside the Codex app it refuses instead, because restarting the app would kill the request.","--yes is mandatory because this interrupts a running editor session and may discard unsaved composer drafts, model-picker selections, and pending approval prompts; it must never happen because an agent guessed a subcommand."],
+    usage: "ocx system codex-restart --yes [--json]",
+  },
+  {
+    command: ["claude","config"],
+    summary: "Read or update Claude Code settings, including independent CLI first-party routing.",
+    routes: [{"method":"GET","path":"/api/claude-code"},{"method":"PUT","path":"/api/claude-code"}],
+    flags: [{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--auth-mode","value":"string","summary":"auto, proxy or subscription."},{"name":"--system-env","value":"string","summary":"on or off."},{"name":"--fast-mode","value":"string","summary":"on or off."},{"name":"--auto-context","value":"string","summary":"on or off."},{"name":"--compact-window","value":"string","summary":"Positive token count or default to clear."},{"name":"--inject-agents","value":"string","summary":"on or off."},{"name":"--small-fast-model","value":"string","summary":"Model ID; - clears."},{"name":"--model-map","value":"string","summary":"Comma-separated from=to mappings; - clears."},{"name":"--blocked-skills","value":"string","summary":"Comma-separated names; - clears."},{"name":"--web-model","value":"string","summary":"Model ID; - clears."},{"name":"--web-backend","value":"string","summary":"openai, anthropic, xai, gemini, exa or -."},{"name":"--vision-model","value":"string","summary":"Model ID; - clears."},{"name":"--vision-backend","value":"string","summary":"openai, anthropic or -."},{"name":"--first-party","value":"string","summary":"on or off; must be the only setting."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["At least one setting is required. --first-party must be set alone and writes Claude settings immediately.","Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings."],
+    usage: "ocx claude config status [--json]; ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
+  },
+  {
+    command: ["claude","intercept","start"],
+    summary: "Start the local Claude interception pair on demand.",
+    routes: [{"method":"POST","path":"/api/claude-intercept/start"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the management response as JSON."}],
+    mutates: true,
+    json: "payload",
+    usage: "ocx claude intercept start [--json]",
+    details: [],
+  },
+  {
+    command: ["claude","desktop","status"],
+    summary: "Applied-vs-desired Claude Desktop state, including staleness, drift, and health.",
+    routes: [{"method":"GET","path":"/api/claude-desktop/status"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the live status as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["Distinct from `claude desktop show`, which reports what this machine WOULD write; this reports what is actually in effect, which only the running proxy knows."],
+    usage: "ocx claude desktop status [--json]",
+  },
+  {
+    command: ["claude","desktop","bind"],
+    summary: "First-party: serve a Claude Desktop Code tab picker model with an opencodex route.",
+    routes: [{"method":"PUT","path":"/api/claude-desktop/first-party-bindings"}],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Takes a picker model id (claude-sonnet-4-6) and a route in the Desktop route vocabulary (provider/model or native/<slug>); the route must be one the Desktop profile can offer.","Only Claude Code traffic that reaches the proxy through the first-party intercept (Desktop's Code tab, the claude CLI) honours it; ocx claude and the public Messages endpoint are unaffected.","The Desktop picker keeps Anthropic's label; the binding changes which model answers, starting with the next request."],
+    usage: "ocx claude desktop bind <picker-model-id> <provider/model|native/slug>",
+  },
+  {
+    command: ["claude","desktop","unbind"],
+    summary: "Remove a first-party Claude Desktop Code tab picker binding.",
+    routes: [{"method":"PUT","path":"/api/claude-desktop/first-party-bindings"}],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Removing an id that is not bound is a no-op; the remaining bindings are printed."],
+    usage: "ocx claude desktop unbind <picker-model-id>",
+  },
+  {
+    command: ["claude","desktop","picker","status"],
+    summary: "First-party picker mode: whether Claude Desktop's Code tab lists opencodex models, and what is missing if not.",
+    routes: [{"method":"GET","path":"/api/claude-desktop/picker"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the result as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["Reads the live picker when available; otherwise reports local offline picker state. JSON emits the picker DTO, not the enclosing API response. No trust mutation."],
+    usage: "ocx claude desktop picker status [--json]",
+  },
+  {
+    command: ["claude","desktop","picker","on"],
+    summary: "Turn first-party picker mode on and remember the choice.",
+    routes: [{"method":"PUT","path":"/api/claude-desktop/picker"}],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Needs a running proxy, first-party mode and macOS. The first time, macOS asks to trust a local certificate authority limited to claude.ai; when the server cannot show that prompt the command runs the trust step in this terminal.","Claude Desktop then reaches the network through opencodex; fully quit and reopen Desktop afterwards."],
+    usage: "ocx claude desktop picker on",
+  },
+  {
+    command: ["claude","desktop","picker","off"],
+    summary: "Turn first-party picker mode off, remove its Desktop egress profile and certificate trust, and remember the choice.",
+    routes: [{"method":"PUT","path":"/api/claude-desktop/picker"}],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Works without a running proxy: the preference is saved and the picker profile and trust are removed locally."],
+    usage: "ocx claude desktop picker off",
+  },
+  {
+    command: ["claude","desktop","picker","trust"],
+    summary: "Run the macOS keychain step for picker mode in this terminal, then ask the server to finish enabling it.",
+    routes: [{"method":"GET","path":"/api/claude-desktop/picker"},{"method":"PUT","path":"/api/claude-desktop/picker"}],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["The server removes trust this command added if the enable is refused; if the request is lost, trust is left alone and picker status tells what happened."],
+    usage: "ocx claude desktop picker trust",
+  },
+  {
+    command: ["integration","native"],
+    summary: "Read native integration state or toggle Claude, Claude Desktop, Codex and Grok.",
+    routes: [{"method":"GET","path":"/api/native-integrations"},{"method":"PUT","path":"/api/native-integrations/claude"},{"method":"PUT","path":"/api/native-integrations/claude-desktop"},{"method":"PUT","path":"/api/native-integrations/codex"},{"method":"PUT","path":"/api/native-integrations/grok"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the client rows or toggle result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Each toggle writes the selected client configuration through its runtime owner. Refused disables remain failures. Cursor status and installer have no branch in this handler and must remain deferred."],
+    usage: "ocx integration native [list] [--json]; ocx integration native <claude|claude-desktop|codex|grok> <on|off> [--json]",
+  },
+  {
+    command: ["integration","client"],
+    summary: "Inspect and toggle file integrations and Aside profiles, read journals, and restore selected operations.",
+    routes: [{"method":"GET","path":"/api/client-integrations"},{"method":"GET","path":"/api/client-integrations/{clientId}"},{"method":"GET","path":"/api/client-integrations/aside/profiles"},{"method":"GET","path":"/api/client-integrations/aside/profiles/{profileId}"},{"method":"GET","path":"/api/client-integrations/journal"},{"method":"GET","path":"/api/client-integrations/aside/profiles/journal"},{"method":"GET","path":"/api/client-integrations/aside/profiles/{profileId}/journal"},{"method":"PUT","path":"/api/client-integrations/{clientId}"},{"method":"PUT","path":"/api/client-integrations/aside/profiles"},{"method":"PUT","path":"/api/client-integrations/aside/profiles/{profileId}"},{"method":"POST","path":"/api/client-integrations/restore"},{"method":"POST","path":"/api/client-integrations/aside/profiles/{profileId}/restore"}],
+    flags: [{"name":"--client","value":"string","summary":"File integration ID; aside selects profiles."},{"name":"--profile","value":"number","summary":"Aside nonnegative integer account ID; requires --client aside."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--overwrite-conflict","value":"boolean","summary":"Explicitly permit replacing a conflicting block."},{"name":"--op","value":"string","summary":"Operation ID; --op-id is an alias."},{"name":"--confirm-drift","value":"boolean","summary":"Explicitly allow replacing edits made after the snapshot."}],
+    mutates: true,
+    json: "payload",
+    details: ["status/show/list reads all clients, one client or Aside profiles. history/journal reads rollback records; expired snapshots stay visible.","enable/disable requires --client; an omitted Aside --profile toggles all profiles. --overwrite-conflict applies only to enable.","restore requires --op (alias --op-id); --client requires --profile and only Aside supports that profile selector. --confirm-drift is an explicit user waiver, never auto-retried. No preview or journal-retirement verb is claimed."],
+    usage: "ocx integration client status [--client <id>] [--profile <id>] [--json]; ocx integration client history [--client <id>] [--profile <id>] [--json]; ocx integration client enable --client <id> [--profile <id>] [--overwrite-conflict] [--json]; ocx integration client disable --client <id> [--profile <id>] [--json]; ocx integration client restore --op <opId> [--client aside --profile <id>] [--confirm-drift] [--json]",
+  },
+  {
+    command: ["sync"],
+    summary: "Synchronize client catalogs, including Aside profiles through the running server's mutation owner.",
+    routes: [{ method: "POST", path: "/api/client-integrations/aside/sync" }],
+    flags: [
+      { name: "--restart-codex", value: "boolean", summary: "Restart the Codex app-servers and fully quit and relaunch the Codex desktop app after a catalog or cache write, on macOS, Linux and Windows." },
+      { name: "--restart-app-server-only", value: "boolean", summary: "Restart only the Codex app-servers and leave the desktop app running; wins over --restart-codex when both are given." },
+      { name: "--restart-desktop-app", value: "boolean", summary: "Deprecated alias of --restart-codex." },
+    ],
+    mutates: true,
+    json: "none",
+    details: ["The Aside refresh uses the live server; other catalog synchronization also performs local work."],
+  },
+  {
+    command: ["agent","subagents","force"],
+    summary: "Force Claude Code subagents onto one exposed model at the next routed launch; - clears.",
+    routes: [{"method":"PUT","path":"/api/subagent-models"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the saved force setting."}],
+    mutates: true,
+    json: "payload",
+    details: ["Requires Claude Code 2.1.257+. Plain claude, forks, inherit skills, the main model and small-fast sidecars are unaffected."],
+    usage: "ocx agent subagents force <model|-> [--json]",
+  },
+  {
+    command: ["agent","request-user-input"],
+    summary: "Show or set whether default mode may ask the operator a question mid-task.",
+    routes: [{"method":"GET","path":"/api/codex-auth/features/default-mode-request-user-input"},{"method":"PUT","path":"/api/codex-auth/features/default-mode-request-user-input"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the feature state as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["A bare invocation reads and never writes."],
+    usage: "ocx agent request-user-input [on|off] [--json]",
+  },
+  {
+    command: ["agent","roles"],
+    summary: "omo (Codex / LazyCodex): show each Codex agent role's model pin, set one role's model in its TOML and in omo.jsonc, or suggest a model for every role.",
+    routes: [{"method":"GET","path":"/api/codex-agent-roles"},{"method":"PUT","path":"/api/codex-agent-roles/{role}"},{"method":"POST","path":"/api/codex-agent-roles/auto-assign"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the role list, the write result or the proposals as JSON."},{"name":"--model","value":"string","summary":"suggest: size the roles with this model instead of the Codex default model."},{"name":"--apply","value":"boolean","summary":"suggest: write every proposal through the role model write."}],
+    mutates: true,
+    json: "payload",
+    details: ["A bare invocation reads and never writes.","Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.","set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml; omo.jsonc is skipped when absent or when it contains comments.","suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort."],
+    usage: "ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]",
+  },
+  {
+    command: ["agent","injection"],
+    summary: "Show or set the delegation model and effort, or suggest both for a described piece of delegated work.",
+    routes: [{"method":"GET","path":"/api/injection-model"},{"method":"PUT","path":"/api/injection-model"},{"method":"POST","path":"/api/injection-model/suggest"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the delegation settings, the write result or the proposal as JSON."},{"name":"--model","value":"string","summary":"set: the delegation model, - clears it. suggest: size the work with this model instead of the Codex default model."},{"name":"--effort","value":"string","summary":"set: the delegation reasoning effort, - clears it."},{"name":"--prompt","value":"string","summary":"set: a custom guidance prompt, - clears it."},{"name":"--guidance","value":"string","summary":"set: on or off for OpenCodex delegation guidance."},{"name":"--apply","value":"boolean","summary":"suggest: write the proposed model and effort through the delegation settings write."}],
+    mutates: true,
+    json: "payload",
+    details: ["guidance aliases injection. Bare invocation reads; use explicit status before --json. set requires at least one setting and - clears model, effort or prompt.","suggest may spend a model call; it writes no settings unless --apply is explicitly supplied. Preserve unsized/unassigned/already-set outcomes."],
+    usage: "ocx agent injection status [--json]; ocx agent injection set [--model <id|->] [--effort <level|->] [--prompt <text|->] [--guidance <on|off>] [--json]; ocx agent injection suggest <work description> [--model <id>] [--apply] [--json]",
+  },
+  {
+    command: ["api","protocols"],
+    summary: "Read the protocol contract version, API surfaces, protocol settings and feature vocabulary.",
+    routes: [{"method":"GET","path":"/api/protocols"}],
+    flags: [{"name":"--provider","value":"string","summary":"Add one configured provider's upstream wire and who decided it."},{"name":"--json","value":"boolean","summary":"Emit the GET /api/protocols body."}],
+    mutates: false,
+    json: "payload",
+    usage: "ocx api protocols [--provider <name>] [--json]",
+    details: [],
+  },
+  {
+    command: ["combo","test"],
+    summary: "Run one JEV decision probe through a decision method: TypeSafe, a System One row, or an opencodex model.",
+    routes: [{"method":"GET","path":"/api/combos"},{"method":"POST","path":"/api/combos/decision-test"}],
+    flags: [{"name":"--combo","value":"string","summary":"Combo id whose saved decision method is probed and whose recursion rules apply."},{"name":"--decision-provider","value":"string","summary":"Probe a jev-decision provider row (or jev for TypeSafe) instead of the saved method."},{"name":"--decision-model","value":"string","summary":"Probe an opencodex-routed model instead of the saved method."},{"name":"--decision-timeout","value":"number","summary":"Decision deadline in milliseconds (1000-120000)."},{"name":"--json","value":"boolean","summary":"Emit the probe result."}],
+    mutates: true,
+    json: "payload",
+    details: ["--combo without an explicit decision override reads the saved combo first. The synthetic decision probe may spend a backend call; a failed-open receipt is not an applied decision."],
+    usage: "ocx combo test [--combo <id>] [--decision-provider <provider|jev> | --decision-model <route>] [--decision-timeout <ms>] [--json]",
+  },
+  {
+    command: ["combo","discover"],
+    summary: "List configured System One decision rows and catalog models that look like decision services.",
+    routes: [{"method":"GET","path":"/api/combos/decision-discovery"}],
+    flags: [{"name":"--query","value":"string","summary":"Match catalog rows by this text instead of the built-in decision-model hint."},{"name":"--json","value":"boolean","summary":"Emit the discovery payload."}],
+    mutates: false,
+    json: "payload",
+    details: ["Read-only: nothing is probed and no provider row is created."],
+    usage: "ocx combo discover [--query <text>] [--json]",
+  },
+  {
+    command: ["api","explain"],
+    summary: "Preview the request path a model would take from one inbound API, computed from config.",
+    routes: [{"method":"POST","path":"/api/protocols/plan"}],
+    flags: [{"name":"--model","value":"string","required":true,"summary":"Model selector as a client would send it."},{"name":"--inbound","value":"string","required":true,"summary":"Inbound API: responses, chat or messages."},{"name":"--feature","value":"string","summary":"Request feature key to judge; repeatable or comma-separated."},{"name":"--json","value":"boolean","summary":"Emit the ProtocolPlanV1 preview."}],
+    mutates: false,
+    json: "payload",
+    details: ["A read-only POST: nothing is sent upstream, no combo state advances and the input is not logged."],
+    usage: "ocx api explain --model <id> --inbound <responses|chat|messages> [--feature <key>[,<key>]]... [--json]",
+  },
+  {
+    command: ["api","policy"],
+    summary: "Read the protocol policy, or change the Messages surface, unrepresentable policy and rollout switches.",
+    routes: [{"method":"GET","path":"/api/protocols"},{"method":"PATCH","path":"/api/protocols/settings"}],
+    flags: [{"name":"--messages","value":"string","summary":"Open or close the Messages API: on or off. Off also turns the Claude integration off."},{"name":"--unrepresentable","value":"string","summary":"legacy keeps today's behavior; reject refuses a request its path cannot carry."},{"name":"--rollout","value":"string","summary":"One switch as name=on or name=off; repeatable. Every switch defaults off."},{"name":"--json","value":"boolean","summary":"Emit the resulting GET /api/protocols body."}],
+    mutates: true,
+    json: "payload",
+    details: ["A bare invocation reads and never writes.","A setting flag changes the operator's config; run it only when the operator asks for that change."],
+    usage: "ocx api policy [--messages <on|off>] [--unrepresentable <legacy|reject>] [--rollout <switch>=<on|off>]... [--json]",
+  },
+];
diff --git a/src/cli/capabilities-command.ts b/src/cli/capabilities-command.ts
index 56f148357bd..e2787549354 100644
--- a/src/cli/capabilities-command.ts
+++ b/src/cli/capabilities-command.ts
@@ -83,6 +83,7 @@ export async function runCapabilities(argv: string[]): Promise<number> {
         flags: cap.flags,
         mutates: cap.mutates,
         json: cap.json,
+        ...(cap.usage !== undefined ? { usage: cap.usage } : {}),
         ...(cap.details ? { details: cap.details } : {}),
       })),
       ...(route === undefined && !mutatingOnly ? { headCapabilities: HEAD_CAPABILITIES } : {}),
diff --git a/src/cli/capabilities-integrations.ts b/src/cli/capabilities-integrations.ts
new file mode 100644
index 00000000000..40be03b8fbc
--- /dev/null
+++ b/src/cli/capabilities-integrations.ts
@@ -0,0 +1,194 @@
+import type { Capability } from "./capability-types";
+
+export const INTEGRATION_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["grok", "status"],
+    usage: "ocx grok status [--json]",
+    summary: "Read Grok model fence state and catalog.",
+    routes: [{"method": "GET", "path": "/api/grok"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.", "Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file."],
+  },
+  {
+    command: ["grok", "set"],
+    usage: "ocx grok set <model,model...> [--json]",
+    summary: "Replace the excluded Grok model list.",
+    routes: [{"method": "PUT", "path": "/api/grok/selection"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.", "Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file."],
+  },
+  {
+    command: ["grok", "exclude"],
+    usage: "ocx grok exclude <model,model...> [--json]",
+    summary: "Add models to the Grok exclusion list.",
+    routes: [{"method": "GET", "path": "/api/grok"}, {"method": "PUT", "path": "/api/grok/selection"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.", "Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file."],
+  },
+  {
+    command: ["grok", "include"],
+    usage: "ocx grok include <model,model...> [--json]",
+    summary: "Remove models from the Grok exclusion list.",
+    routes: [{"method": "GET", "path": "/api/grok"}, {"method": "PUT", "path": "/api/grok/selection"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.", "Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file."],
+  },
+  {
+    command: ["grok", "clear"],
+    usage: "ocx grok clear [--json]",
+    summary: "Clear Grok exclusions.",
+    routes: [{"method": "PUT", "path": "/api/grok/selection"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.", "Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file."],
+  },
+  {
+    command: ["grok", "apply"],
+    usage: "ocx grok apply [--json]",
+    summary: "Apply the saved Grok model fence.",
+    routes: [{"method": "POST", "path": "/api/grok/apply"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["integration grok is an alias of grok; show aliases status. Saving selection and applying the saved fence are separate actions.", "Apply receipts can report changed or skippedReason; success is not a guarantee of a changed client file."],
+  },
+  {
+    command: ["integration", "client", "status"],
+    usage: "ocx integration client status [--client <id>] [--profile <id>] [--json]",
+    summary: "Read all file integrations, one client or an Aside profile.",
+    routes: [{"method": "GET", "path": "/api/client-integrations"}, {"method": "GET", "path": "/api/client-integrations/{clientId}"}, {"method": "GET", "path": "/api/client-integrations/aside/profiles"}, {"method": "GET", "path": "/api/client-integrations/aside/profiles/{profileId}"}],
+    flags: [{"name": "--client", "value": "string", "summary": "File integration ID; aside selects profiles."}, {"name": "--profile", "value": "number", "summary": "Aside nonnegative integer account ID; requires --client aside."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["show and list alias status; omitted Aside profile means the aggregate profile collection."],
+  },
+  {
+    command: ["integration", "client", "history"],
+    usage: "ocx integration client history [--client <id>] [--profile <id>] [--json]",
+    summary: "Read integration rollback history and snapshot availability.",
+    routes: [{"method": "GET", "path": "/api/client-integrations/journal"}, {"method": "GET", "path": "/api/client-integrations/aside/profiles/journal"}, {"method": "GET", "path": "/api/client-integrations/aside/profiles/{profileId}/journal"}],
+    flags: [{"name": "--client", "value": "string", "summary": "File integration ID; aside selects profiles."}, {"name": "--profile", "value": "number", "summary": "Aside nonnegative integer account ID; requires --client aside."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["journal is an alias. Ordinary client filtering uses ?client=; expired snapshots remain visibly expired."],
+  },
+  {
+    command: ["integration", "client", "enable"],
+    usage: "ocx integration client enable --client <id> [--profile <id>] [--overwrite-conflict] [--json]",
+    summary: "Apply the selected managed file integration.",
+    routes: [{"method": "PUT", "path": "/api/client-integrations/{clientId}"}, {"method": "PUT", "path": "/api/client-integrations/aside/profiles"}, {"method": "PUT", "path": "/api/client-integrations/aside/profiles/{profileId}"}],
+    flags: [{"name": "--client", "value": "string", "summary": "Explicit file integration ID.", "required": true}, {"name": "--profile", "value": "number", "summary": "Aside nonnegative integer account ID; requires --client aside."}, {"name": "--overwrite-conflict", "value": "boolean", "summary": "Explicitly permit replacing a conflicting block."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["An omitted Aside profile toggles all Aside profiles. Ownership, snapshots, journal and conflict refusals remain server-owned.", "Partial Aside failures remain failures after emitting the per-profile result. Never infer permission to overwrite from a refusal."],
+  },
+  {
+    command: ["integration", "client", "disable"],
+    usage: "ocx integration client disable --client <id> [--profile <id>] [--json]",
+    summary: "Disable the selected managed file integration.",
+    routes: [{"method": "PUT", "path": "/api/client-integrations/{clientId}"}, {"method": "PUT", "path": "/api/client-integrations/aside/profiles"}, {"method": "PUT", "path": "/api/client-integrations/aside/profiles/{profileId}"}],
+    flags: [{"name": "--client", "value": "string", "summary": "Explicit file integration ID.", "required": true}, {"name": "--profile", "value": "number", "summary": "Aside nonnegative integer account ID; requires --client aside."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["An omitted Aside profile toggles all Aside profiles. Ownership, snapshots, journal and conflict refusals remain server-owned.", "Partial Aside failures remain failures after emitting the per-profile result. Never infer permission to overwrite from a refusal."],
+  },
+  {
+    command: ["integration", "client", "restore"],
+    usage: "ocx integration client restore --op <opId> [--client aside --profile <id>] [--confirm-drift] [--json]",
+    summary: "Restore a selected rollback operation, retaining drift refusal.",
+    routes: [{"method": "POST", "path": "/api/client-integrations/restore"}, {"method": "POST", "path": "/api/client-integrations/aside/profiles/{profileId}/restore"}],
+    flags: [{"name": "--op", "value": "string", "summary": "Operation ID; --op-id is an alias.", "required": true}, {"name": "--client", "value": "string", "summary": "File integration ID; aside selects profiles."}, {"name": "--profile", "value": "number", "summary": "Aside nonnegative integer account ID; requires --client aside."}, {"name": "--confirm-drift", "value": "boolean", "summary": "Explicitly allow replacing edits made after the snapshot."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["With --client, restore requires --profile; only Aside profiles accept that selector. No automatic drift confirmation or retry."],
+  },
+  {
+    command: ["claude", "config", "status"],
+    usage: "ocx claude config status [--json]",
+    summary: "Read effective Claude Code configuration.",
+    routes: [{"method": "GET", "path": "/api/claude-code"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false,
+    json: "payload",
+    details: ["show is an alias; integration claude forwards to the same handler."],
+  },
+  {
+    command: ["claude", "config", "set"],
+    usage: "ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
+    summary: "Change Claude Code settings through the runtime owner.",
+    routes: [{"method": "PUT", "path": "/api/claude-code"}],
+    flags: [{"name": "--enabled", "value": "string", "summary": "on or off."}, {"name": "--auth-mode", "value": "string", "summary": "auto, proxy or subscription."}, {"name": "--system-env", "value": "string", "summary": "on or off."}, {"name": "--fast-mode", "value": "string", "summary": "on or off."}, {"name": "--auto-context", "value": "string", "summary": "on or off."}, {"name": "--compact-window", "value": "string", "summary": "Positive token count or default to clear."}, {"name": "--inject-agents", "value": "string", "summary": "on or off."}, {"name": "--small-fast-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--model-map", "value": "string", "summary": "Comma-separated from=to mappings; - clears."}, {"name": "--blocked-skills", "value": "string", "summary": "Comma-separated names; - clears."}, {"name": "--web-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--web-backend", "value": "string", "summary": "openai, anthropic, xai, gemini, exa or -."}, {"name": "--vision-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--vision-backend", "value": "string", "summary": "openai, anthropic or -."}, {"name": "--first-party", "value": "string", "summary": "on or off; must be the only setting."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["At least one setting is required. --first-party must be set alone and writes Claude settings immediately.", "Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings."],
+  },
+  {
+    command: ["claude", "desktop", "show"],
+    usage: "ocx claude desktop show [--json]",
+    summary: "Inspect the desired profile derived on this machine.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local config/catalog derivation, not GET of the remote desired profile. On a connected client scope is local; apply uses the hub profile. Catalog derivation may discover upstream models."],
+  },
+  {
+    command: ["claude", "desktop", "move"],
+    usage: "ocx claude desktop move <provider/model> <opus|fable|sonnet|haiku> [--default]",
+    summary: "Move an available route to a local Desktop family.",
+    routes: [],
+    flags: [{"name": "--default", "value": "boolean", "summary": "Make this route the family default."}],
+    mutates: true,
+    json: "none",
+    details: ["Local profile persistence only; no management HTTP or --json. On connected clients this does not change the hub profile."],
+  },
+  {
+    command: ["claude", "desktop", "default"],
+    usage: "ocx claude desktop default <opus|fable|sonnet|haiku> <provider/model|none>",
+    summary: "Set or clear a local Desktop family default.",
+    routes: [],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Local profile persistence only; none clears the default. Connected Desktop apply uses the hub profile."],
+  },
+  {
+    command: ["claude", "desktop", "export"],
+    usage: "ocx claude desktop export <path|->",
+    summary: "Export the persisted local Desktop profile.",
+    routes: [],
+    flags: [],
+    mutates: true,
+    json: "none",
+    details: ["Local file output; - writes JSON to stdout. There is no --json flag. A file destination is overwritten; this is not a GUI draft export."],
+  },
+  {
+    command: ["claude", "desktop", "import"],
+    usage: "ocx claude desktop import <path> [--apply]",
+    summary: "Import a local Desktop profile, optionally applying it as a static gateway.",
+    routes: [{"method": "POST", "path": "/api/claude-desktop/apply"}],
+    flags: [{"name": "--apply", "value": "boolean", "summary": "After saving, apply as a static gateway."}],
+    mutates: true,
+    json: "none",
+    details: ["Without --apply this only persists locally. With a live local proxy, gateway apply is delegated by HTTP; otherwise local helpers apply it.", "Connected clients refuse import --apply. A saved profile can remain saved after application fails; no --json mode."],
+  },
+  {
+    command: ["claude", "desktop", "apply"],
+    usage: "ocx claude desktop [apply] [--first-party | --gateway [--static|--hybrid|--discovery-only]]",
+    summary: "Apply Claude Desktop first-party interception or gateway profile.",
+    routes: [{"method": "POST", "path": "/api/claude-desktop/apply"}],
+    flags: [{"name": "--first-party", "value": "boolean", "summary": "Keep Desktop on claude.ai and intercept its Code tab."}, {"name": "--gateway", "value": "boolean", "summary": "Apply a third-party gateway profile."}, {"name": "--static", "value": "boolean", "summary": "Static gateway model catalog."}, {"name": "--hybrid", "value": "boolean", "summary": "Hybrid gateway catalog."}, {"name": "--discovery-only", "value": "boolean", "summary": "Discovery-only gateway catalog."}],
+    mutates: true,
+    json: "none",
+    details: ["Uses local helpers or the live local apply route; connected gateway clients use the hub profile download path. No --json mode.", "First-party requires a local hub with interception enabled. Preserve account-risk warnings, trust prompts and ownership refusals; metadata grants no consent.", "Application and committed-marker persistence can diverge; inspect status after application and preserve warnings."],
+  },
+];
diff --git a/src/cli/capabilities-lab.ts b/src/cli/capabilities-lab.ts
new file mode 100644
index 00000000000..6e8ef423f64
--- /dev/null
+++ b/src/cli/capabilities-lab.ts
@@ -0,0 +1,214 @@
+import type { Capability } from "./capability-types";
+
+export const LAB_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["lab", "status"],
+    usage: "ocx lab status [--json]",
+    summary: "Read local Lab projection status.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied."],
+  },
+  {
+    command: ["lab", "verdicts"],
+    usage: "ocx lab verdicts [--subject <subject>] [--layer <layer>] [--suite <suite>] [--verdict <verdict>] [--from <ms>] [--to <ms>] [--limit <n>] [--cursor <cursor>] [--json]",
+    summary: "Read local Lab verdicts.",
+    routes: [],
+    flags: [{"name": "--subject", "value": "string", "summary": "Exact subject ID."}, {"name": "--layer", "value": "string", "summary": "Evidence layer."}, {"name": "--suite", "value": "string", "summary": "Suite ID."}, {"name": "--verdict", "value": "string", "summary": "Compatibility verdict."}, {"name": "--from", "value": "number", "summary": "Inclusive timestamp in milliseconds."}, {"name": "--to", "value": "number", "summary": "Timestamp upper bound in milliseconds."}, {"name": "--limit", "value": "number", "summary": "Positive page size."}, {"name": "--cursor", "value": "string", "summary": "Opaque page cursor."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Read commands do not start probes or scheduler ticks."],
+  },
+  {
+    command: ["lab", "subjects"],
+    usage: "ocx lab subjects [--kind <kind>] [--limit <n>] [--cursor <cursor>] [--json]",
+    summary: "Read local Lab subjects.",
+    routes: [],
+    flags: [{"name": "--kind", "value": "string", "summary": "Subject kind."}, {"name": "--limit", "value": "number", "summary": "Positive page size."}, {"name": "--cursor", "value": "string", "summary": "Opaque page cursor."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Read commands do not start probes or scheduler ticks."],
+  },
+  {
+    command: ["lab", "observations"],
+    usage: "ocx lab observations [--subject <subject>] [--layer <layer>] [--suite <suite>] [--scenario <scenario>] [--outcome <outcome>] [--execution-mode <execution-mode>] [--from <ms>] [--to <ms>] [--limit <n>] [--cursor <cursor>] [--json]",
+    summary: "Read local Lab observations.",
+    routes: [],
+    flags: [{"name": "--subject", "value": "string", "summary": "Exact subject ID."}, {"name": "--layer", "value": "string", "summary": "Evidence layer."}, {"name": "--suite", "value": "string", "summary": "Suite ID."}, {"name": "--scenario", "value": "string", "summary": "Scenario ID."}, {"name": "--outcome", "value": "string", "summary": "Observation outcome."}, {"name": "--execution-mode", "value": "string", "summary": "Execution mode."}, {"name": "--from", "value": "number", "summary": "Inclusive timestamp in milliseconds."}, {"name": "--to", "value": "number", "summary": "Timestamp upper bound in milliseconds."}, {"name": "--limit", "value": "number", "summary": "Positive page size."}, {"name": "--cursor", "value": "string", "summary": "Opaque page cursor."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Read commands do not start probes or scheduler ticks."],
+  },
+  {
+    command: ["lab", "events"],
+    usage: "ocx lab events [--event-kind <event-kind>] [--subject <subject>] [--from <ms>] [--to <ms>] [--excluded <true|false>] [--limit <n>] [--cursor <cursor>] [--json]",
+    summary: "Read local Lab events.",
+    routes: [],
+    flags: [{"name": "--event-kind", "value": "string", "summary": "Event kind."}, {"name": "--subject", "value": "string", "summary": "Exact subject ID."}, {"name": "--from", "value": "number", "summary": "Inclusive timestamp in milliseconds."}, {"name": "--to", "value": "number", "summary": "Timestamp upper bound in milliseconds."}, {"name": "--excluded", "value": "string", "summary": "true or false; takes a value."}, {"name": "--limit", "value": "number", "summary": "Positive page size."}, {"name": "--cursor", "value": "string", "summary": "Opaque page cursor."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Read commands do not start probes or scheduler ticks."],
+  },
+  {
+    command: ["lab", "artifacts"],
+    usage: "ocx lab artifacts [--status <status>] [--artifact-class <artifact-class>] [--limit <n>] [--cursor <cursor>] [--json]",
+    summary: "Read local Lab artifacts.",
+    routes: [],
+    flags: [{"name": "--status", "value": "string", "summary": "present, corrupt or purged_unavailable."}, {"name": "--artifact-class", "value": "string", "summary": "Artifact class."}, {"name": "--limit", "value": "number", "summary": "Positive page size."}, {"name": "--cursor", "value": "string", "summary": "Opaque page cursor."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Read commands do not start probes or scheduler ticks."],
+  },
+  {
+    command: ["lab", "catalog"],
+    usage: "ocx lab catalog [--layer <layer>] [--suite <suite>] [--json]",
+    summary: "Read local Lab catalog.",
+    routes: [],
+    flags: [{"name": "--layer", "value": "string", "summary": "Evidence layer."}, {"name": "--suite", "value": "string", "summary": "Suite ID."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Read commands do not start probes or scheduler ticks."],
+  },
+  {
+    command: ["lab", "subject"],
+    usage: "ocx lab subject <subjectId> [--json]",
+    summary: "Inspect one local Lab subject.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied."],
+  },
+  {
+    command: ["lab", "event"],
+    usage: "ocx lab event <eventId> [--json]",
+    summary: "Inspect one local Lab event.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied."],
+  },
+  {
+    command: ["lab", "artifact"],
+    usage: "ocx lab artifact <digest> [--json]",
+    summary: "Inspect one local Lab artifact.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied."],
+  },
+  {
+    command: ["lab", "production-signals"],
+    usage: "ocx lab production-signals --subject <id> [--limit <n>] [--json]",
+    summary: "Read passive production context for one exact Lab route subject.",
+    routes: [],
+    flags: [{"name": "--subject", "value": "string", "summary": "Exact Lab route subject ID.", "required": true}, {"name": "--limit", "value": "number", "summary": "Positive page size."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Passive production context is not verification evidence."],
+  },
+  {
+    command: ["lab", "public", "preview"],
+    usage: "ocx lab public preview --event <eventId> [--event <eventId> ...] [--json]",
+    summary: "Preview unsigned local public evidence.",
+    routes: [],
+    flags: [{"name": "--event", "value": "string", "summary": "Event ID; repeat for multiple records.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "No remote publishing occurs. Preview creates no publisher key; export can create local signing identity and bundle files."],
+  },
+  {
+    command: ["lab", "public", "export"],
+    usage: "ocx lab public export --event <eventId> [--event <eventId> ...] [--json]",
+    summary: "Export signed local public evidence.",
+    routes: [],
+    flags: [{"name": "--event", "value": "string", "summary": "Event ID; repeat for multiple records.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "No remote publishing occurs. Preview creates no publisher key; export can create local signing identity and bundle files."],
+  },
+  {
+    command: ["lab", "public", "verify"],
+    usage: "ocx lab public verify --file <bundle.json> [--json]",
+    summary: "Verify a public evidence file.",
+    routes: [],
+    flags: [{"name": "--file", "value": "string", "summary": "Public evidence bundle path.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Signature validity proves integrity/continuity, not local verification.", "A verification failure emits its structured summary and then returns nonzero."],
+  },
+  {
+    command: ["lab", "public", "import"],
+    usage: "ocx lab public import --file <bundle.json> [--json]",
+    summary: "Import public evidence as untrusted community context.",
+    routes: [],
+    flags: [{"name": "--file", "value": "string", "summary": "Public evidence bundle path.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Signature validity proves integrity/continuity, not local verification.", "Imported community evidence never becomes locally verified evidence."],
+  },
+  {
+    command: ["lab", "public", "community"],
+    usage: "ocx lab public community [--json]",
+    summary: "List local untrusted community evidence context.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied."],
+  },
+  {
+    command: ["lab", "automation", "status"],
+    usage: "ocx lab automation [status] [--json]",
+    summary: "Read local automation policy, queue and run state.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied."],
+  },
+  {
+    command: ["lab", "automation", "enable"],
+    usage: "ocx lab automation enable [--protocol] [--live] [--json]",
+    summary: "Enable local Lab automation layers.",
+    routes: [],
+    flags: [{"name": "--protocol", "value": "boolean", "summary": "Select protocol conformance."}, {"name": "--live", "value": "boolean", "summary": "Select live route compatibility; may spend upstream quota."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "These flags already exist in the local handler. With neither flag, preserve current layer selection; with either flag, select only requested layers.", "Persists local policy, reconciles the queue and starts a scheduler in this CLI process; this is not a remote scheduler control API. Task-effectiveness background remains disabled."],
+  },
+  {
+    command: ["lab", "automation", "disable"],
+    usage: "ocx lab automation disable [--json]",
+    summary: "Disable local Lab automation.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "Persists disabled policy, reconciles the local queue and stops this process scheduler."],
+  },
+  {
+    command: ["lab", "automation", "runs"],
+    usage: "ocx lab automation runs [--limit <n>] [--cursor <c>] [--json]",
+    summary: "List locally persisted automation runs.",
+    routes: [],
+    flags: [{"name": "--limit", "value": "number", "summary": "Positive page size."}, {"name": "--cursor", "value": "string", "summary": "Opaque page cursor."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied."],
+  },
+  {
+    command: ["lab", "run"],
+    usage: "ocx lab run --layer <protocol_conformance|live_route_compatibility|task_effectiveness> --scenario <id> [--provider <name>] [--model <id>] [--json]",
+    summary: "Plan and enqueue an explicit local Lab run.",
+    routes: [],
+    flags: [{"name": "--layer", "value": "string", "summary": "Evidence layer.", "required": true}, {"name": "--scenario", "value": "string", "summary": "Scenario ID.", "required": true}, {"name": "--provider", "value": "string", "summary": "Configured provider name."}, {"name": "--model", "value": "string", "summary": "Model ID."}, {"name": "--json", "value": "boolean", "summary": "Emit the local result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Local Lab helpers and storage only; no management HTTP. Remote/live-proxy equivalence is not implied.", "The live-route layer installs a production route executor and can spend upstream quota. Explicit operator authorization is required for probes.", "An enqueued run receipt is not a completed verification. No run-cancel or full policy/routes editor is claimed."],
+  },
+];
diff --git a/src/cli/capabilities-observe-system.ts b/src/cli/capabilities-observe-system.ts
new file mode 100644
index 00000000000..6e32cfffa40
--- /dev/null
+++ b/src/cli/capabilities-observe-system.ts
@@ -0,0 +1,628 @@
+import type { Capability } from "./capability-types";
+
+/** Verified existing handlers only; local operations never claim management routes. */
+export const OBSERVE_SYSTEM_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["observe", "logs"], summary: "Read or follow request logs.",
+    usage: "ocx observe logs [--provider <name>] [--model <id>] [--status <code>] [--conversation <id>] [--account <label>] [--limit <n>] [--follow] [--json|--jsonl]",
+    routes: [{"method": "GET", "path": "/api/logs"}],
+    flags: [{"name": "--provider", "value": "string", "summary": "Filter provider, including failover attempts."}, {"name": "--model", "value": "string", "summary": "Filter model, including failover attempts."}, {"name": "--status", "value": "string", "summary": "Filter status code."}, {"name": "--conversation", "value": "string", "summary": "Filter conversation ID."}, {"name": "--conversationId", "value": "string", "summary": "Alias of --conversation."}, {"name": "--account", "value": "string", "summary": "Filter stable account log label."}, {"name": "--limit", "value": "number", "summary": "Positive row limit; default 200."}, {"name": "--follow", "value": "boolean", "summary": "Poll once per second; use --jsonl for streaming."}, {"name": "-f", "value": "boolean", "summary": "Alias of --follow."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}, {"name": "--jsonl", "value": "boolean", "summary": "Emit one row per JSON line; exclusive with --json."}],
+    mutates: false, json: "payload",
+    details: ["Also available as logs. --follow refuses --json; streaming deduplicates by row ID, not row revisions."],
+  },
+  {
+    command: ["logs", "explain"], summary: "Explain the recorded routing decision for one request.",
+    usage: "ocx logs explain <request-id> [--json]",
+    routes: [{"method": "GET", "path": "/api/request-history/{id}/route-decision"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["The request ID is URI-encoded; this reads an existing decision and sends no model request.", "Also accepted after observe logs."],
+  },
+  {
+    command: ["logs", "rebuild-index"], summary: "Rebuild the local request-history index.",
+    usage: "ocx logs rebuild-index [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Local derived SQLite index rebuild from the canonical ledger; no management API request.", "Also accepted after observe logs."],
+  },
+  {
+    command: ["logs", "index-status"], summary: "Read and refresh local request-history index metadata.",
+    usage: "ocx logs index-status [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Local index open may create, ingest or rebuild the derived SQLite index; this is not a write-free file inspection.", "Also accepted after observe logs."],
+  },
+  {
+    command: ["observe", "usage"], summary: "Read token and estimated-cost usage.",
+    usage: "ocx observe usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>] [--provider <name>] [--model <id>] [--json]",
+    routes: [{"method": "GET", "path": "/api/usage"}],
+    flags: [{"name": "--range", "value": "string", "summary": "today | 1d | 7d | 30d | all; default 30d."}, {"name": "--surface", "value": "string", "summary": "all | codex | claude | grok; default all."}, {"name": "--since", "value": "string", "summary": "Inclusive epoch milliseconds or ISO datetime with timezone; requires --until."}, {"name": "--until", "value": "string", "summary": "Inclusive end; requires --since. Custom bounds override --range."}, {"name": "--provider", "value": "string", "summary": "Filter provider."}, {"name": "--model", "value": "string", "summary": "Filter model."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Also available as ocx usage. Connected clients read their own enrolled-key Hub report through /v1/usage; this is not whole-Hub management usage.", "Custom bounds require the server to confirm customWindow, since and until."],
+  },
+  {
+    command: ["observe", "storage"], summary: "Read storage diagnostics.",
+    usage: "ocx observe storage [--limit <n>] [--json]",
+    routes: [{"method": "GET", "path": "/api/storage"}],
+    flags: [{"name": "--limit", "value": "number", "summary": "Positive limit forwarded to the endpoint; endpoint semantics apply."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Reads the running proxy management API."],
+  },
+  {
+    command: ["observe", "memory"], summary: "Read memory diagnostics.",
+    usage: "ocx observe memory [--limit <n>] [--json]",
+    routes: [{"method": "GET", "path": "/api/system/memory"}],
+    flags: [{"name": "--limit", "value": "number", "summary": "Positive limit forwarded to the endpoint; endpoint semantics apply."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Reads the running proxy management API."],
+  },
+  {
+    command: ["observe", "debug"], summary: "Read debug diagnostics.",
+    usage: "ocx observe debug [--limit <n>] [--json]",
+    routes: [{"method": "GET", "path": "/api/debug"}],
+    flags: [{"name": "--limit", "value": "number", "summary": "Positive limit forwarded to the endpoint; endpoint semantics apply."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Reads the running proxy management API."],
+  },
+  {
+    command: ["observe", "claude-inbound"], summary: "Read claude-inbound diagnostics.",
+    usage: "ocx observe claude-inbound [--limit <n>] [--json]",
+    routes: [{"method": "GET", "path": "/api/claude/inbound-debug"}],
+    flags: [{"name": "--limit", "value": "number", "summary": "Positive limit forwarded to the endpoint; endpoint semantics apply."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Snapshot read; no follow or cursor option."],
+  },
+  {
+    command: ["observe", "injection"], summary: "Read injection diagnostics.",
+    usage: "ocx observe injection [--limit <n>] [--json]",
+    routes: [{"method": "GET", "path": "/api/debug/injection-logs"}],
+    flags: [{"name": "--limit", "value": "number", "summary": "Positive limit forwarded to the endpoint; endpoint semantics apply."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Snapshot read; no follow or cursor option."],
+  },
+  {
+    command: ["memory"], summary: "Read runtime memory and active-turn diagnostics.",
+    usage: "ocx memory [--limit <n>] [--json]",
+    routes: [{"method": "GET", "path": "/api/system/memory"}],
+    flags: [{"name": "--limit", "value": "number", "summary": "Positive limit forwarded to the endpoint."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Alias of observe memory."],
+  },
+  {
+    command: ["storage", "codex-logs", "status"], summary: "Inspect Codex Log Guard state.",
+    usage: "ocx storage codex-logs status [--json]",
+    routes: [{"method": "GET", "path": "/api/storage/codex-logs"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Also accepted after observe storage codex-logs. Omitted action defaults to status."],
+  },
+  {
+    command: ["storage", "codex-logs", "protect"], summary: "Protect Codex logs in compat or quiet mode.",
+    usage: "ocx storage codex-logs protect [--mode <compat|quiet>] [--json]",
+    routes: [{"method": "POST", "path": "/api/storage/codex-logs/protect"}],
+    flags: [{"name": "--mode", "value": "string", "summary": "compat | quiet; default compat."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Also accepted after observe storage codex-logs. Mutates logs or their protection immediately; this handler has no --yes option."],
+  },
+  {
+    command: ["storage", "codex-logs", "unprotect"], summary: "Remove Codex log protection.",
+    usage: "ocx storage codex-logs unprotect [--json]",
+    routes: [{"method": "POST", "path": "/api/storage/codex-logs/unprotect"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Also accepted after observe storage codex-logs. Mutates logs or their protection immediately; this handler has no --yes option."],
+  },
+  {
+    command: ["storage", "codex-logs", "repair"], summary: "Repair Codex log protection.",
+    usage: "ocx storage codex-logs repair [--json]",
+    routes: [{"method": "POST", "path": "/api/storage/codex-logs/repair"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Also accepted after observe storage codex-logs. Mutates logs or their protection immediately; this handler has no --yes option."],
+  },
+  {
+    command: ["storage", "codex-logs", "compact"], summary: "Compact Codex logs.",
+    usage: "ocx storage codex-logs compact [--json]",
+    routes: [{"method": "POST", "path": "/api/storage/codex-logs/compact"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Also accepted after observe storage codex-logs. Mutates logs or their protection immediately; this handler has no --yes option."],
+  },
+  {
+    command: ["storage", "trash", "list"], summary: "Read quarantine batches.",
+    usage: "ocx storage trash list [--json]",
+    routes: [{"method": "GET", "path": "/api/storage/trash"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: [],
+  },
+  {
+    command: ["storage", "policy", "show"], summary: "Read cleanup policy and job state.",
+    usage: "ocx storage policy show [--json]",
+    routes: [{"method": "GET", "path": "/api/storage/cleanup-policy"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: [],
+  },
+  {
+    command: ["storage", "trash", "restore"], summary: "Restore one quarantined session batch.",
+    usage: "ocx storage trash restore <entry-id> --yes [--json]",
+    routes: [{"method": "POST", "path": "/api/storage/trash/restore"}],
+    flags: [{"name": "--yes", "value": "boolean", "summary": "Required confirmation before restoring stored sessions.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Moves files and reconciles database rows; partial outcomes remain in the response."],
+  },
+  {
+    command: ["storage", "policy", "set"], summary: "Save submitted cleanup policy fields.",
+    usage: "ocx storage policy set [--enabled <true|false>] [--percent <1-100>] [--mode <quarantine|permanent>] [--schedule <startup|daily|weekly|manual>] [--json]",
+    routes: [{"method": "PUT", "path": "/api/storage/cleanup-policy"}],
+    flags: [{"name": "--enabled", "value": "string", "summary": "true | false."}, {"name": "--percent", "value": "number", "summary": "Oldest archived-session percentage; server validates the 1-100 policy range."}, {"name": "--mode", "value": "string", "summary": "quarantine | permanent."}, {"name": "--schedule", "value": "string", "summary": "startup | daily | weekly | manual."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["At least one setting is required. Percent writes target.removeOldestPercent; mode, schedule and range validation belong to the server."],
+  },
+  {
+    command: ["storage", "policy", "run"], summary: "Run the stored cleanup policy immediately.",
+    usage: "ocx storage policy run --yes [--json]",
+    routes: [{"method": "POST", "path": "/api/storage/cleanup-policy/run"}],
+    flags: [{"name": "--yes", "value": "boolean", "summary": "Required confirmation for immediate archived-session cleanup.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Run acceptance is not completion; inspect storage policy show for job state."],
+  },
+  {
+    command: ["debug", "provider"], summary: "Read or change the provider debug override.",
+    usage: "ocx debug provider [status|on|off|reset]",
+    routes: [{"method": "GET", "path": "/api/debug"}, {"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Mixed family: omitted action/status reads; on/off/reset change runtime overrides. No JSON mode.", "Reset follows the environment default. Logs have a separate child command."],
+  },
+  {
+    command: ["debug", "provider", "status"], summary: "Read provider debug state.",
+    usage: "ocx debug provider status",
+    routes: [{"method": "GET", "path": "/api/debug"}],
+    flags: [],
+    mutates: false, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "provider", "on"], summary: "Set provider debug override on.",
+    usage: "ocx debug provider on",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "provider", "off"], summary: "Set provider debug override off.",
+    usage: "ocx debug provider off",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "provider", "reset"], summary: "Set provider debug override reset.",
+    usage: "ocx debug provider reset",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "provider", "logs"], summary: "Read or follow provider debug log lines.",
+    usage: "ocx debug provider logs [-f|--follow]",
+    routes: [{"method": "GET", "path": "/api/debug/logs"}],
+    flags: [{"name": "-f", "value": "boolean", "summary": "Follow new sequence numbers."}, {"name": "--follow", "value": "boolean", "summary": "Alias of -f."}],
+    mutates: false, json: "none",
+    details: ["Text lines only; initial limit 500, then sequence-based polling."],
+  },
+  {
+    command: ["debug", "usage"], summary: "Read or change the usage debug override.",
+    usage: "ocx debug usage [status|on|off|reset]",
+    routes: [{"method": "GET", "path": "/api/debug"}, {"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Mixed family: omitted action/status reads; on/off/reset change runtime overrides. No JSON mode.", "Reset follows the environment default. Logs have a separate child command."],
+  },
+  {
+    command: ["debug", "usage", "status"], summary: "Read usage debug state.",
+    usage: "ocx debug usage status",
+    routes: [{"method": "GET", "path": "/api/debug"}],
+    flags: [],
+    mutates: false, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "usage", "on"], summary: "Set usage debug override on.",
+    usage: "ocx debug usage on",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "usage", "off"], summary: "Set usage debug override off.",
+    usage: "ocx debug usage off",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "usage", "reset"], summary: "Set usage debug override reset.",
+    usage: "ocx debug usage reset",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "usage", "logs"], summary: "Read or follow usage debug log lines.",
+    usage: "ocx debug usage logs [-f|--follow]",
+    routes: [{"method": "GET", "path": "/api/debug/usage-logs"}],
+    flags: [{"name": "-f", "value": "boolean", "summary": "Follow new sequence numbers."}, {"name": "--follow", "value": "boolean", "summary": "Alias of -f."}],
+    mutates: false, json: "none",
+    details: ["Text lines only; initial limit 500, then sequence-based polling."],
+  },
+  {
+    command: ["debug", "injection"], summary: "Read or change the injection debug override.",
+    usage: "ocx debug injection [status|on|off|reset]",
+    routes: [{"method": "GET", "path": "/api/debug"}, {"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Mixed family: omitted action/status reads; on/off/reset change runtime overrides. No JSON mode.", "Reset follows the environment default. Buffered reads use observe injection."],
+  },
+  {
+    command: ["debug", "injection", "status"], summary: "Read injection debug state.",
+    usage: "ocx debug injection status",
+    routes: [{"method": "GET", "path": "/api/debug"}],
+    flags: [],
+    mutates: false, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "injection", "on"], summary: "Set injection debug override on.",
+    usage: "ocx debug injection on",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "injection", "off"], summary: "Set injection debug override off.",
+    usage: "ocx debug injection off",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "injection", "reset"], summary: "Set injection debug override reset.",
+    usage: "ocx debug injection reset",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "claude"], summary: "Read or change the claude debug override.",
+    usage: "ocx debug claude [status|on|off|reset]",
+    routes: [{"method": "GET", "path": "/api/debug"}, {"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Mixed family: omitted action/status reads; on/off/reset change runtime overrides. No JSON mode.", "Reset follows the environment default. Buffered reads use observe claude-inbound."],
+  },
+  {
+    command: ["debug", "claude", "status"], summary: "Read claude debug state.",
+    usage: "ocx debug claude status",
+    routes: [{"method": "GET", "path": "/api/debug"}],
+    flags: [],
+    mutates: false, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "claude", "on"], summary: "Set claude debug override on.",
+    usage: "ocx debug claude on",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "claude", "off"], summary: "Set claude debug override off.",
+    usage: "ocx debug claude off",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["debug", "claude", "reset"], summary: "Set claude debug override reset.",
+    usage: "ocx debug claude reset",
+    routes: [{"method": "PUT", "path": "/api/debug"}],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Requires a running proxy; legacy text output only."],
+  },
+  {
+    command: ["system", "status"], summary: "Read settings, startup health and memory together.",
+    usage: "ocx system status [--json]",
+    routes: [{"method": "GET", "path": "/api/settings"}, {"method": "GET", "path": "/api/startup-health"}, {"method": "GET", "path": "/api/system/memory"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "envelope",
+    details: ["Default system action. The CLI bundles three payloads; this does not call /api/system/health."],
+  },
+  {
+    command: ["system", "settings"], summary: "Read or update supported runtime settings.",
+    usage: "ocx system settings [--auto-start <on|off>] [--stream-mode <auto|legacy-tee|eager-relay>] [--desktop-authless <on|off>] [--client-compaction <on|off>] [--json]",
+    routes: [{"method": "GET", "path": "/api/settings"}, {"method": "PUT", "path": "/api/settings"}],
+    flags: [{"name": "--auto-start", "value": "string", "summary": "on | off for Codex autostart."}, {"name": "--stream-mode", "value": "string", "summary": "auto | legacy-tee | eager-relay."}, {"name": "--desktop-authless", "value": "string", "summary": "on | off for Codex Desktop authless."}, {"name": "--client-compaction", "value": "string", "summary": "on | off for native replay portability; summaries may consume provider quota."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Mixed read/write: no setting flags reads; setting flags write only submitted fields. Stored, effective and config-apply states can differ."],
+  },
+  {
+    command: ["system", "startup", "health"], summary: "Read startup protection.",
+    usage: "ocx system startup health [--json]",
+    routes: [{"method": "GET", "path": "/api/startup-health"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["health is the default; status is its alias."],
+  },
+  {
+    command: ["system", "startup", "install-service"], summary: "Request startup install-service.",
+    usage: "ocx system startup install-service [--json]",
+    routes: [{"method": "POST", "path": "/api/startup-action"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["The server invokes the platform-local service repair or shim installation and reports its outcome."],
+  },
+  {
+    command: ["system", "startup", "install-shim"], summary: "Request startup install-shim.",
+    usage: "ocx system startup install-shim [--json]",
+    routes: [{"method": "POST", "path": "/api/startup-action"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["The server invokes the platform-local service repair or shim installation and reports its outcome."],
+  },
+  {
+    command: ["system", "diagnostics"], summary: "Read project-config diagnostics.",
+    usage: "ocx system diagnostics [--json]",
+    routes: [{"method": "GET", "path": "/api/diagnostics/project-config"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Runs against the serving proxy; inspect the returned saved/applied or failure result."],
+  },
+  {
+    command: ["system", "sync"], summary: "Synchronize client catalogs and configuration.",
+    usage: "ocx system sync [--json]",
+    routes: [{"method": "POST", "path": "/api/sync"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Runs against the serving proxy; inspect the returned saved/applied or failure result."],
+  },
+  {
+    command: ["system", "update", "check"], summary: "Check the package update channel.",
+    usage: "ocx system update check [--channel <latest|preview>] [--json]",
+    routes: [{"method": "GET", "path": "/api/update/check"}],
+    flags: [{"name": "--channel", "value": "string", "summary": "latest | preview; default latest."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Checks registry availability; does not install."],
+  },
+  {
+    command: ["system", "update", "run"], summary: "Start a package update job.",
+    usage: "ocx system update run [--channel <latest|preview>] [--restart <on|off>] --yes [--json]",
+    routes: [{"method": "POST", "path": "/api/update/run"}],
+    flags: [{"name": "--channel", "value": "string", "summary": "latest | preview; default latest."}, {"name": "--restart", "value": "string", "summary": "on | off; default on."}, {"name": "--yes", "value": "boolean", "summary": "Required confirmation for package update.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Installs software and may restart the proxy. Acceptance is not completion; inspect system update status with the returned job ID."],
+  },
+  {
+    command: ["system", "update", "status"], summary: "Read one package update job.",
+    usage: "ocx system update status <job-id> [--json]",
+    routes: [{"method": "GET", "path": "/api/update/status"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: [],
+  },
+  {
+    command: ["config", "show"], summary: "Local configuration show.",
+    usage: "ocx config show [--json] [--source]",
+    routes: [],
+    flags: [{"name": "--source", "value": "boolean", "summary": "Include source diagnostics."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "envelope",
+    details: ["Local config/file operation; no management API request or automatic live convergence.", "Displayed credential values are masked.", "Always emits JSON; --source wraps config with source/error/warnings. Default action when omitted."],
+  },
+  {
+    command: ["config", "get"], summary: "Local configuration get.",
+    usage: "ocx config get <dot.path> [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Local config/file operation; no management API request or automatic live convergence.", "Displayed credential values are masked."],
+  },
+  {
+    command: ["config", "set"], summary: "Local configuration set.",
+    usage: "ocx config set <dot.path> <json-or-string> [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "envelope",
+    details: ["Local config/file operation; no management API request or automatic live convergence.", "Displayed credential values are masked."],
+  },
+  {
+    command: ["config", "unset"], summary: "Local configuration unset.",
+    usage: "ocx config unset <dot.path> [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "envelope",
+    details: ["Local config/file operation; no management API request or automatic live convergence."],
+  },
+  {
+    command: ["config", "validate"], summary: "Local configuration validate.",
+    usage: "ocx config validate [path|-] [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "envelope",
+    details: ["Local config/file operation; no management API request or automatic live convergence."],
+  },
+  {
+    command: ["config", "export"], summary: "Human-only raw configuration export handoff.",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Local config/file operation; no management API request or automatic live convergence.", "Human-only secret-bearing export: raw credentials are included. Keep the file and stdout out of agent transcripts. --json is accepted but does not alter this raw export."],
+  },
+  {
+    command: ["config", "import"], summary: "Local configuration import.",
+    usage: "ocx config import <path|-> --yes [--json]",
+    routes: [],
+    flags: [{"name": "--yes", "value": "boolean", "summary": "Required confirmation before replacing local config.", "required": true}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "envelope",
+    details: ["Local config/file operation; no management API request or automatic live convergence.", "Replaces local configuration after schema validation; requires --yes. Restart or explicitly sync if needed."],
+  },
+  {
+    command: ["companion", "show"], summary: "Read companion settings, defaults and presence.",
+    usage: "ocx companion show [--json]",
+    routes: [{"method": "GET", "path": "/api/companion/settings"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Settings only; no usage timeline request."],
+  },
+  {
+    command: ["companion", "set"], summary: "Save selected companion settings.",
+    usage: "ocx companion set <key>=<value> [...] [--json]",
+    routes: [{"method": "PUT", "path": "/api/companion/settings"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Values are parsed as JSON when valid, otherwise as strings."],
+  },
+  {
+    command: ["companion", "reset"], summary: "Restore companion defaults.",
+    usage: "ocx companion reset [--json]",
+    routes: [{"method": "PUT", "path": "/api/companion/settings"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "payload",
+    details: ["Settings only; no usage timeline request."],
+  },
+  {
+    command: ["service", "install"], summary: "Install the local background service.",
+    usage: "ocx service install [--native|--scheduler]",
+    routes: [],
+    flags: [{"name": "--native", "value": "boolean", "summary": "Windows WinSW backend; exclusive with --scheduler."}, {"name": "--scheduler", "value": "boolean", "summary": "Scheduled backend; exclusive with --native."}],
+    mutates: true, json: "none",
+    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.", "Backend options apply only to install; other verbs use the installed backend."],
+  },
+  {
+    command: ["service", "repair"], summary: "Repair local service registration and verify serving health.",
+    usage: "ocx service repair",
+    routes: [],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.", "Backend options apply only to install; other verbs use the installed backend."],
+  },
+  {
+    command: ["service", "restart"], summary: "Restart the local background service.",
+    usage: "ocx service restart",
+    routes: [],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.", "Backend options apply only to install; other verbs use the installed backend."],
+  },
+  {
+    command: ["service", "start"], summary: "Start the registered local service.",
+    usage: "ocx service start",
+    routes: [],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.", "Backend options apply only to install; other verbs use the installed backend."],
+  },
+  {
+    command: ["service", "stop"], summary: "Stop the registered local service.",
+    usage: "ocx service stop",
+    routes: [],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.", "Backend options apply only to install; other verbs use the installed backend."],
+  },
+  {
+    command: ["service", "status"], summary: "Inspect local service-manager status.",
+    usage: "ocx service status",
+    routes: [],
+    flags: [],
+    mutates: false, json: "none",
+    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.", "Backend options apply only to install; other verbs use the installed backend."],
+  },
+  {
+    command: ["service", "uninstall"], summary: "Uninstall the local service.",
+    usage: "ocx service uninstall",
+    routes: [],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.", "remove is an alias for uninstall."],
+  },
+  {
+    command: ["codex-shim", "install"], summary: "Local Codex launcher shim install.",
+    usage: "ocx codex-shim install",
+    routes: [],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Local launcher/PATH wrapper operation on macOS, Linux and Windows; no management API or JSON mode.", "Installation diagnoses wrapper health and reports readiness warnings."],
+  },
+  {
+    command: ["codex-shim", "status"], summary: "Local Codex launcher shim status.",
+    usage: "ocx codex-shim status",
+    routes: [],
+    flags: [],
+    mutates: false, json: "none",
+    details: ["Local launcher/PATH wrapper operation on macOS, Linux and Windows; no management API or JSON mode.", "Inspects local launcher wrapper state."],
+  },
+  {
+    command: ["codex-shim", "uninstall"], summary: "Local Codex launcher shim uninstall.",
+    usage: "ocx codex-shim uninstall",
+    routes: [],
+    flags: [],
+    mutates: true, json: "none",
+    details: ["Local launcher/PATH wrapper operation on macOS, Linux and Windows; no management API or JSON mode.", "remove aliases uninstall."],
+  },
+  {
+    command: ["tray", "install"], summary: "Windows tray install.",
+    usage: "ocx tray install [--no-start] [--json]",
+    routes: [],
+    flags: [{"name": "--no-start", "value": "boolean", "summary": "Install without starting the tray."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "envelope",
+    details: ["Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.", "Lifecycle writes require Windows."],
+  },
+  {
+    command: ["tray", "start"], summary: "Windows tray start.",
+    usage: "ocx tray start [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "envelope",
+    details: ["Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.", "Lifecycle writes require Windows."],
+  },
+  {
+    command: ["tray", "stop"], summary: "Windows tray stop.",
+    usage: "ocx tray stop [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "envelope",
+    details: ["Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.", "Lifecycle writes require Windows."],
+  },
+  {
+    command: ["tray", "status"], summary: "Windows tray status.",
+    usage: "ocx tray status [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: false, json: "envelope",
+    details: ["Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.", "Lifecycle writes require Windows."],
+  },
+  {
+    command: ["tray", "uninstall"], summary: "Windows tray uninstall.",
+    usage: "ocx tray uninstall [--json]",
+    routes: [],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    mutates: true, json: "envelope",
+    details: ["Local Windows-only tray lifecycle; no management API. Status on other platforms reports unsupported.", "remove aliases uninstall."],
+  },
+];
diff --git a/src/cli/capabilities-provider-models.ts b/src/cli/capabilities-provider-models.ts
new file mode 100644
index 00000000000..57194e64ad3
--- /dev/null
+++ b/src/cli/capabilities-provider-models.ts
@@ -0,0 +1,248 @@
+import type { Capability } from "./capability-types";
+
+/** Existing provider/model handlers; local configuration operations deliberately have no routes. */
+export const PROVIDER_MODEL_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["provider", "add"], summary: "Add or replace a provider in local configuration.",
+    usage: "ocx provider add <name> [--adapter <id>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <id>] [--model <id> --text-only] [--google-tool-schema-policy <compatible|reject-lossy>] [--allow-private-network] [--set-default] [--force] [--sync] [--json]",
+    routes: [], mutates: true, json: "envelope",
+    flags: [
+      { name: "--adapter", value: "string", summary: "Required for a provider absent from the registry." },
+      { name: "--base-url", value: "string", summary: "Upstream URL; required for an unregistered provider." },
+      { name: "--api-key", value: "string", summary: "Legacy argv credential input; prefer the human-operated stdin account add-key workflow." },
+      { name: "--api-key-transport", value: "string", summary: "x-api-key or bearer." },
+      { name: "--default-model", value: "string", summary: "Default upstream model ID." },
+      { name: "--model", value: "string", summary: "Model for --text-only; requires that flag." },
+      { name: "--text-only", value: "boolean", summary: "Declare text-only input for --model or the default model." },
+      { name: "--google-tool-schema-policy", value: "string", summary: "Google adapter: compatible or reject-lossy." },
+      { name: "--allow-private-network", value: "boolean", summary: "Permit a private upstream network." },
+      { name: "--set-default", value: "boolean", summary: "Also select this provider as default." },
+      { name: "--force", value: "boolean", summary: "Replace an existing provider." },
+      { name: "--sync", value: "boolean", summary: "Attempt local Codex synchronization after saving in text mode." },
+      { name: "--json", value: "boolean", summary: "Emit the local save receipt." },
+    ],
+    details: ["Writes local config, not the provider management API. JSON returns after saving with needsSync:true, before --sync; inspect the receipt and synchronize separately. Keep real credentials out of argv and agent transcripts."],
+  },
+  {
+    command: ["provider", "show"], summary: "Inspect one locally configured provider.",
+    usage: "ocx provider show <name> [--json]", routes: [], mutates: false, json: "envelope",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the local provider view." }],
+    details: ["Reads local config; masks API-key and key-pool fields. This is not a live provider read or a general secret-export interface."],
+  },
+  {
+    command: ["provider", "remove"], summary: "Remove a provider from local configuration.",
+    usage: "ocx provider remove <name> [--json]", routes: [], mutates: true, json: "envelope",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the removal receipt and needsSync." }],
+    details: ["Local write, with no management HTTP call. Refuses the default, last provider, or combo dependencies; also removes that provider's custom models. Requires operator intent; the handler has no --yes flag."],
+  },
+  {
+    command: ["provider", "set-default"], summary: "Select the default provider in local configuration.",
+    usage: "ocx provider set-default <name> [--json]", routes: [], mutates: true, json: "envelope",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the save/no-op receipt and needsSync." }],
+    details: ["Local config operation; the provider must already exist. Does not claim live management convergence."],
+  },
+  {
+    command: ["provider", "edit"], summary: "Patch an existing provider through the running proxy.",
+    usage: "ocx provider edit <name> [--adapter <id>] [--base-url <url>] [--default-model <id|->] [--auth-mode <key|forward|oauth|local|->] [--note <text|->] [--api-key-transport <x-api-key|bearer|->] [--headers <json|->] [--enabled <on|off>] [--live-models <on|off>] [--retain-models <id,id|->] [--model <id> --text-only] [--xai-chat <on|off>] [--allow-private-network <on|off>] [--model-context-tier <model=default|long_context>] [--json]",
+    routes: [{ method: "PATCH", path: "/api/providers" }], mutates: true, json: "payload",
+    flags: [
+      { name: "--adapter", value: "string", summary: "Adapter ID." },
+      { name: "--base-url", value: "string", summary: "Upstream URL." },
+      { name: "--default-model", value: "string", summary: "Model ID; - clears." },
+      { name: "--auth-mode", value: "string", summary: "key, forward, oauth, local; - clears." },
+      { name: "--note", value: "string", summary: "Note; - clears." },
+      { name: "--api-key-transport", value: "string", summary: "x-api-key or bearer; - clears." },
+      { name: "--headers", value: "string", summary: "JSON object; - or JSON null clears." },
+      { name: "--enabled", value: "string", summary: "on or off." },
+      { name: "--live-models", value: "string", summary: "on or off." },
+      { name: "--retain-models", value: "string", summary: "Comma-separated IDs; - clears with null." },
+      { name: "--model", value: "string", summary: "Requires --text-only." },
+      { name: "--text-only", value: "boolean", summary: "Requires --model; declare text-only input." },
+      { name: "--xai-chat", value: "string", summary: "xai only: on uses Chat, off opts into Responses." },
+      { name: "--allow-private-network", value: "string", summary: "on or off." },
+      { name: "--model-context-tier", value: "string", summary: "Repeatable github-copilot model=default or model=long_context." },
+      { name: "--json", value: "boolean", summary: "Emit the management receipt." },
+    ],
+    details: ["At least one edit is required; only supplied fields are patched. update is an existing alias. Use provider show only for local state, not as proof of the live write."],
+  },
+  {
+    command: ["provider", "test"], summary: "Probe a provider's live model discovery connectivity.",
+    usage: "ocx provider test <name> [--json]", routes: [{ method: "POST", path: "/api/providers/test" }], mutates: true, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the probe result." }],
+    details: ["May contact the upstream provider; requires operator intent to probe. Static catalogs can return applicable:false; failed connectivity exits nonzero."],
+  },
+  {
+    command: ["provider", "quota"], summary: "Read provider quota reports, optionally refreshing them.",
+    usage: "ocx provider quota [--refresh] [--json]", routes: [{ method: "GET", path: "/api/provider-quotas" }], mutates: false, json: "payload",
+    flags: [{ name: "--refresh", value: "boolean", summary: "Request refresh=1; may contact providers and update cached observations." }, { name: "--json", value: "boolean", summary: "Emit the quota report." }],
+    details: ["Reads quota observations without changing operator settings. Cache misses may probe upstream even without --refresh; --refresh bypasses the cache and updates observations. This GET is not the POST account-refresh operation."],
+  },
+  {
+    command: ["provider", "presets"], summary: "Read provider presets from the running proxy.",
+    usage: "ocx provider presets [--json]", routes: [{ method: "GET", path: "/api/provider-presets" }], mutates: false, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the preset payload." }],
+  },
+  {
+    command: ["provider", "account-mode"], summary: "Set OpenAI Codex account routing to pool or direct.",
+    usage: "ocx provider account-mode <pool|direct> [--json]", routes: [{ method: "PATCH", path: "/api/providers" }], mutates: true, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the management receipt." }],
+    details: ["Patches codexAccountMode on provider openai; this does not switch the physical Codex login."],
+  },
+  {
+    command: ["provider", "selected"], summary: "Read or replace one provider's selected model allowlist.",
+    usage: "ocx provider selected <name> [--set <id,id...>|--clear] [--json]",
+    routes: [{ method: "GET", path: "/api/selected-models" }, { method: "PUT", path: "/api/selected-models" }], mutates: true, json: "envelope",
+    flags: [{ name: "--set", value: "string", summary: "Replace with comma-separated upstream IDs." }, { name: "--clear", value: "boolean", summary: "Clear the allowlist to show all; exclusive with --set." }, { name: "--json", value: "boolean", summary: "Emit the selected view or receipt." }],
+    details: ["Without a mutation flag this reads only. --clear sends models:[], not a model named -.", "Read JSON is the CLI projection {provider, selected: string[], available: string[]}, not the API's provider-keyed maps; missing entries become empty arrays. --set/--clear JSON returns the server's write receipt unchanged."],
+  },
+  {
+    command: ["models", "list"], summary: "List static configured models locally.",
+    usage: "ocx models list [--provider <name>] [--json]", routes: [], mutates: false, json: "envelope",
+    flags: [{ name: "--provider", value: "string", summary: "Limit to a configured provider." }, { name: "--json", value: "boolean", summary: "Emit models and the static-catalog note." }],
+    details: ["A bare models invocation is equivalent. Reads local config, never the live catalog; use models live for runtime discovery."],
+  },
+  {
+    command: ["models", "add"], summary: "Add a custom model definition to local configuration.",
+    usage: "ocx models add <provider> <modelId> [--display-name <name>] [--context-window <tokens>] [--modalities <text,image,audio>] [--reasoning-efforts <levels|->] [--default-reasoning-effort <level|->]",
+    routes: [], mutates: true, json: "none",
+    flags: [
+      { name: "--display-name", value: "string", summary: "Custom display name without a slash." },
+      { name: "--context-window", value: "number", summary: "Positive integer token count." },
+      { name: "--modalities", value: "string", summary: "Comma-separated text, image, audio." },
+      { name: "--reasoning-efforts", value: "string", summary: "Comma-separated supported levels; - inherits; an empty string declares no reasoning." },
+      { name: "--default-reasoning-effort", value: "string", summary: "A declared level; - inherits." },
+    ],
+    details: ["Writes local customModels and attempts local Codex catalog sync if a proxy is found. No custom-model management route or JSON mode is used."],
+  },
+  {
+    command: ["models", "remove"], summary: "Remove a custom definition from local configuration.",
+    usage: "ocx models remove <customId|provider/modelId> [--yes]", routes: [], mutates: true, json: "none",
+    flags: [{ name: "--yes", value: "boolean", summary: "Confirm deletion without an interactive prompt." }],
+    details: ["Local config deletion followed by a local Codex sync attempt. Ambiguous selectors are refused; list-custom --json exposes full IDs. Does not call DELETE /api/custom-models/{id}."],
+  },
+  {
+    command: ["models", "list-custom"], summary: "List locally stored custom model definitions and their IDs.",
+    usage: "ocx models list-custom [--json]", routes: [], mutates: false, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the local customModels array with full IDs." }],
+    details: ["Reads local configuration, not the management API."],
+  },
+  {
+    command: ["models", "live"], summary: "Read the running proxy's model catalog.",
+    usage: "ocx models live [--provider <name>] [--free-only] [--json]", routes: [{ method: "GET", path: "/api/models" }], mutates: false, json: "payload",
+    flags: [{ name: "--provider", value: "string", summary: "Filter returned rows by provider." }, { name: "--free-only", value: "boolean", summary: "Include only rows explicitly classified free." }, { name: "--json", value: "boolean", summary: "Emit the filtered catalog array." }],
+  },
+  {
+    command: ["models", "edit"], summary: "Edit a custom model by its definition ID through the proxy.",
+    usage: "ocx models edit <custom-id> [--model-id <id>] [--display-name <name|->] [--context-window <tokens|0>] [--modalities <text,image,audio|->] [--reasoning-efforts <levels|->] [--default-reasoning-effort <level|->] [--json]",
+    routes: [{ method: "PUT", path: "/api/custom-models/{id}" }], mutates: true, json: "payload",
+    flags: [
+      { name: "--model-id", value: "string", summary: "Upstream model ID." },
+      { name: "--display-name", value: "string", summary: "Custom definition name; - clears." },
+      { name: "--context-window", value: "number", summary: "Safe token count; 0 clears. Unlike models set, - is invalid here." },
+      { name: "--modalities", value: "string", summary: "Comma-separated modalities; - sends an empty list." },
+      { name: "--reasoning-efforts", value: "string", summary: "Comma-separated levels; - inherits (null), empty string stores an empty ladder." },
+      { name: "--default-reasoning-effort", value: "string", summary: "Default effort; - clears with null." },
+      { name: "--json", value: "boolean", summary: "Emit the management receipt." },
+    ],
+    details: ["At least one edit is required. Operand is the custom definition ID from list-custom, not a provider/model selector. Discovered-model display-name overrides are a different resource."],
+  },
+  {
+    command: ["models", "enable"], summary: "Enable one routed or native catalog model.",
+    usage: "ocx models enable <provider/model|native-model> [--native] [--json]", routes: [{ method: "PUT", path: "/api/model-visibility" }], mutates: true, json: "payload",
+    flags: [{ name: "--native", value: "boolean", summary: "Treat the whole selector as a native OpenAI model ID." }, { name: "--json", value: "boolean", summary: "Emit the visibility receipt." }],
+  },
+  {
+    command: ["models", "disable"], summary: "Disable one routed or native catalog model.",
+    usage: "ocx models disable <provider/model|native-model> [--native] [--json]", routes: [{ method: "PUT", path: "/api/model-visibility" }], mutates: true, json: "payload",
+    flags: [{ name: "--native", value: "boolean", summary: "Treat the whole selector as a native OpenAI model ID." }, { name: "--json", value: "boolean", summary: "Emit the visibility receipt." }],
+  },
+  {
+    command: ["models", "provider"], summary: "Enable or disable all catalog rows for a provider.",
+    usage: "ocx models provider <name> <on|off> [--json]", routes: [{ method: "GET", path: "/api/models" }, { method: "PUT", path: "/api/model-visibility" }], mutates: true, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the visibility receipt." }],
+    details: ["Reads targets from the live catalog first; refuses a provider without available models."],
+  },
+  {
+    command: ["models", "selected"], summary: "Read or replace a provider's selected model allowlist.",
+    usage: "ocx models selected <provider> [--set <id,id...>|--clear] [--json]", routes: [{ method: "GET", path: "/api/selected-models" }, { method: "PUT", path: "/api/selected-models" }], mutates: true, json: "envelope",
+    flags: [{ name: "--set", value: "string", summary: "Replace the allowlist with comma-separated IDs." }, { name: "--clear", value: "boolean", summary: "Send an empty list to show all; exclusive with --set." }, { name: "--json", value: "boolean", summary: "Emit the selected view or receipt." }],
+    details: ["Without --set or --clear this only reads. A literal - is not the clear spelling.", "Read JSON is the CLI projection {provider, selected: string[], available: string[]}, not the API's provider-keyed maps; missing entries become empty arrays. --set/--clear JSON returns the server's write receipt unchanged."],
+  },
+  {
+    command: ["models", "preset", "show"], summary: "Inspect shipped model presets and applied versions.",
+    usage: "ocx models preset show [--provider <name>] [--json]", routes: [{ method: "GET", path: "/api/model-presets" }], mutates: false, json: "payload",
+    flags: [{ name: "--provider", value: "string", summary: "Project a single provider's preset." }, { name: "--json", value: "boolean", summary: "Emit the preset view." }],
+  },
+  {
+    command: ["models", "preset", "apply"], summary: "Apply a provider's curated model preset or show all models.",
+    usage: "ocx models preset apply <provider> [--all] [--json]", routes: [{ method: "PUT", path: "/api/model-presets" }], mutates: true, json: "payload",
+    flags: [{ name: "--all", value: "boolean", summary: "Use mode all instead of preset." }, { name: "--json", value: "boolean", summary: "Emit the application receipt." }],
+    details: ["An empty preset match preserves the previous selection and reports fallback; do not interpret it as successful narrowing."],
+  },
+  {
+    command: ["models", "new-policy"], summary: "Read or set the policy for newly discovered models.",
+    usage: "ocx models new-policy [on|off] [--provider <name>] [--json]", routes: [{ method: "GET", path: "/api/model-discovery" }, { method: "PUT", path: "/api/model-discovery" }], mutates: true, json: "payload",
+    flags: [{ name: "--provider", value: "string", summary: "Scope the read/write to a provider; omitted means global." }, { name: "--json", value: "boolean", summary: "Emit the policy view or receipt." }],
+    details: ["No state operand means read only. Only on/off writes exist; no inherit/clear operand is implemented."],
+  },
+  {
+    command: ["models", "new-arrivals"], summary: "Read recent model discoveries.",
+    usage: "ocx models new-arrivals [--json]", routes: [{ method: "GET", path: "/api/model-discovery" }], mutates: false, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit recentArrivals grouped by provider." }],
+  },
+  {
+    command: ["models", "context", "status"], summary: "Read routed-provider context caps.",
+    usage: "ocx models context status [--json]", routes: [{ method: "GET", path: "/api/provider-context-caps" }], mutates: false, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit context settings." }],
+  },
+  {
+    command: ["models", "context", "value"], summary: "Set the default routed-provider context cap value.",
+    usage: "ocx models context value <tokens> [--set-all] [--json]", routes: [{ method: "PUT", path: "/api/provider-context-caps" }], mutates: true, json: "payload",
+    flags: [{ name: "--set-all", value: "boolean", summary: "Also apply the value to every routed provider." }, { name: "--json", value: "boolean", summary: "Emit the context receipt." }],
+    details: ["Tokens must be a positive safe integer; separators _ and , are accepted. Without --set-all only the default for future toggles changes."],
+  },
+  {
+    command: ["models", "context", "provider"], summary: "Toggle one provider's context cap, optionally choosing its value.",
+    usage: "ocx models context provider <provider> <on|off> [--value <tokens>] [--json]", routes: [{ method: "PUT", path: "/api/provider-context-caps" }], mutates: true, json: "payload",
+    flags: [{ name: "--value", value: "number", summary: "Positive integer; only valid with on." }, { name: "--json", value: "boolean", summary: "Emit the context receipt." }],
+    details: ["off disables this provider's cap; --value is not a global value change."],
+  },
+  {
+    command: ["models", "context", "all"], summary: "Enable or disable caps for all routed providers.",
+    usage: "ocx models context all <on|off> [--json]", routes: [{ method: "PUT", path: "/api/provider-context-caps" }], mutates: true, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the context receipt." }],
+  },
+  {
+    command: ["models", "shadow", "status"], summary: "Read shadow-call settings.",
+    usage: "ocx models shadow status [--json]", routes: [{ method: "GET", path: "/api/shadow-call-settings" }], mutates: false, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit shadow-call settings." }],
+  },
+  {
+    command: ["models", "shadow", "set"], summary: "Set the shadow-call model or enabled state.",
+    usage: "ocx models shadow set [model|-] [--enabled <on|off>] [--json]", routes: [{ method: "PUT", path: "/api/shadow-call-settings" }], mutates: true, json: "payload",
+    flags: [{ name: "--enabled", value: "string", summary: "on or off; takes a value." }, { name: "--json", value: "boolean", summary: "Emit the settings receipt." }],
+    details: ["At least a model or --enabled is required; - clears the model with an empty string. Enabling shadow calls can cause subsequent inference calls."],
+  },
+  {
+    command: ["alias", "list"], summary: "Read provider and model aliases.",
+    usage: "ocx alias list [--json]", routes: [{ method: "GET", path: "/api/aliases" }], mutates: false, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit alias maps and provenance." }],
+  },
+  {
+    command: ["alias", "set"], summary: "Assign a provider or upstream model alias.",
+    usage: "ocx alias set <provider|provider/native-model-id> <alias> [--json]", routes: [{ method: "PUT", path: "/api/providers/{provider}/alias" }, { method: "PUT", path: "/api/providers/{provider}/model-aliases" }], mutates: true, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the alias receipt." }],
+    details: ["The first slash separates provider from the complete upstream model ID."],
+  },
+  {
+    command: ["alias", "rm"], summary: "Clear a provider or model alias.",
+    usage: "ocx alias rm <provider|provider/native-model-id> [--json]", routes: [{ method: "PUT", path: "/api/providers/{provider}/alias" }, { method: "PUT", path: "/api/providers/{provider}/model-aliases" }], mutates: true, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the alias removal receipt." }],
+    details: ["Provider clear sends alias:null; model clear sends remove:[modelId]."],
+  },
+  {
+    command: ["alias", "defaults"], summary: "Toggle built-in model aliases globally or for a provider.",
+    usage: "ocx alias defaults <on|off> [--provider <name>] [--json]", routes: [{ method: "PUT", path: "/api/default-aliases" }], mutates: true, json: "payload",
+    flags: [{ name: "--provider", value: "string", summary: "Limit the toggle to one provider." }, { name: "--json", value: "boolean", summary: "Emit the alias settings receipt." }],
+  },
+];
diff --git a/src/cli/capabilities.ts b/src/cli/capabilities.ts
index accda5db994..7a3c82376e7 100644
--- a/src/cli/capabilities.ts
+++ b/src/cli/capabilities.ts
@@ -1,1208 +1,39 @@
 /**
- * What `ocx` can do, as data an agent can read without parsing help text.
- *
- * This is the machine-readable index behind `ocx capabilities`. It relates each CLI
- * capability to the management route(s) it drives, which nothing in this repository did
- * before: help lived in twenty per-module `USAGE` constants and a hand-written banner
- * that a test explicitly licensed to drift from the command registry.
- *
- * LEAF MODULE. It imports nothing from `src/cli/`, and nothing here may import a command
- * module. That is not tidiness. Each command module declares its usage text as a
- * top-level `const USAGE`, evaluated at import time, so a cycle back into this table
- * would resolve to `undefined` under ESM rather than throwing -- silently emptying the
- * usage text that `rejectArgs` hands to `CliUsageError`, in the exact error-reporting
- * surface the CLI-operability issues are about. `tests/cli/cli-capabilities.test.ts` asserts
- * the absence of those imports and that every rendered usage string is non-empty, so the
- * failure mode is loud instead of degraded.
- *
- * Head-handled surfaces (`--version`, `help`) are declared separately in
- * `HEAD_CAPABILITIES`. They exit in the CLI head (`root.ts`) before dispatch and have no
- * runner key, so listing them as ordinary capabilities would break the registry parity
- * assertion that every canonical entry is a direct runner. `help` is excluded from
- * `CLI_COMMANDS` deliberately -- `tests/cli/cli-registry.test.ts` documents it as a
- * head-handled pseudo-case -- and that decision is preserved here rather than reversed.
+ * Stable discovery facade: literal metadata and types have separate pure owners.
+ * The transitive dependency boundary is checked by the CLI capability tests.
+ * Command modules must never enter this graph: their top-level usage constants
+ * can become undefined through an ESM cycle. This is not an execution sandbox.
  */
+import { CAPABILITIES as BASE_CAPABILITIES } from "./capabilities-base";
+import type { Capability } from "./capability-types";
+import { PROVIDER_MODEL_CAPABILITIES } from "./capabilities-provider-models";
+import { ACCOUNT_CAPABILITIES } from "./capabilities-accounts";
+import { AGENT_ROUTING_CAPABILITIES } from "./capabilities-agents-routing";
+import { INTEGRATION_CAPABILITIES } from "./capabilities-integrations";
+import { OBSERVE_SYSTEM_CAPABILITIES } from "./capabilities-observe-system";
+import { ACCESS_REMOTE_CAPABILITIES } from "./capabilities-access-remote";
+import { LAB_CAPABILITIES } from "./capabilities-lab";
 
-/** A management route a capability drives. Path text only; never a handler reference. */
-export interface CapabilityRoute {
-  readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-  readonly path: string;
-}
-
-export interface CapabilityFlag {
-  readonly name: string;
-  readonly value?: "string" | "number" | "boolean";
-  readonly required?: boolean;
-  readonly summary: string;
-}
-
-/**
- * How a capability emits JSON.
- *
- * - `payload`: the API payload, largely unwrapped.
- * - `envelope`: a CLI-shaped object with its own schema.
- * - `none`: no `--json` mode.
- */
-export type CapabilityJsonMode = "payload" | "envelope" | "none";
-
-export interface Capability {
-  /** Command path, e.g. `["account", "pause"]`. */
-  readonly command: readonly string[];
-  readonly summary: string;
-  readonly routes: readonly CapabilityRoute[];
-  readonly flags: readonly CapabilityFlag[];
-  readonly mutates: boolean;
-  readonly json: CapabilityJsonMode;
-  readonly details?: readonly string[];
-  /**
-   * Extra banner rows this capability owns, for surfaces the banner shows separately
-   * from the bare command (`ocx restore back`, `ocx doctor --reclaim-response-temps`).
-   * Without this the banner cannot equal the capability set: it legitimately carries more
-   * rows than there are commands.
-   */
-  readonly bannerLines?: readonly string[];
-}
-
-/**
- * Surfaces resolved in the CLI head, before dispatch.
- *
- * They belong in `ocx capabilities` output and in the banner, but not in `CLI_COMMANDS`:
- * `--version`, `-v`, and `version` are answered at `root.ts` and exit, so none of them is
- * a runner key to parity-check against.
- */
-export interface HeadCapability {
-  readonly invocations: readonly string[];
-  readonly summary: string;
-  readonly bannerLine: string;
-}
-
-export const HEAD_CAPABILITIES: readonly HeadCapability[] = [
-  {
-    invocations: ["--version", "-v", "version"],
-    summary: "Print the CLI version and exit.",
-    bannerLine: "ocx --version | -v          Print version",
-  },
-  {
-    invocations: ["help", "--help", "-h"],
-    summary: "Print the command list, or one command's usage with `ocx help <command>`.",
-    bannerLine: "ocx help [command]          Show help for a command",
-  },
-];
-
-/**
- * Capabilities declared so far. Incomplete by design: later phases add verbs.
- * `ocx capabilities` is the index of what is listed here, not of every CLI command.
- * A capability must not name a route the command does not actually fetch.
- */
 export const CAPABILITIES: readonly Capability[] = [
-  {
-    command: ["chatgpt"],
-    summary: "Experimental ChatGPT app-server shim: launch, restore or status (macOS only).",
-    routes: [], flags: [], mutates: true, json: "none",
-    bannerLines: ["ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)"],
-    details: ["Default off; launch requires chatgptDesktop.appServerShim: true. Restore removes the generated launcher."],
-  },
-  {
-    command: ["link", "port"],
-    summary: "Allocate a free loopback port for a remote home link.",
-    routes: [],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the selected port as JSON." }],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["link", "issue"],
-    summary: "Issue one link credential and record its tunnel metadata.",
-    routes: [{ method: "POST", path: "/api/link/issue" }],
-    flags: [
-      { name: "--alias", value: "string", required: true, summary: "SSH host alias for the linked machine." },
-      { name: "--tunnel-port", value: "number", required: true, summary: "Remote loopback port for the reverse tunnel." },
-      { name: "--json", value: "boolean", summary: "Emit the issue result as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: ["Requires the running proxy's admin token on loopback; the one-time data key is printed only on stdout."],
-  },
-  {
-    command: ["link", "status"],
-    summary: "Read link listener and tunnel status.",
-    routes: [{ method: "GET", path: "/api/link/status" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the K16 status payload as JSON." }],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["link", "revoke"],
-    summary: "Revoke a link credential and remove its link record.",
-    routes: [{ method: "DELETE", path: "/api/link/{id}" }],
-    flags: [
-      { name: "--link-id", value: "string", required: true, summary: "Link id to revoke." },
-      { name: "--json", value: "boolean", summary: "Emit the revoked link id as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: ["Requires the running proxy's admin token on loopback."],
-  },
-  {
-    "command": [
-      "remote-workspace",
-      "pair"
-    ],
-    "summary": "Enroll this executor with one Hub using a one-time code from stdin and locally approved roots.",
-    "routes": [],
-    "flags": [
-      {
-        "name": "--json",
-        "value": "boolean",
-        "summary": "Emit the public local executor status."
-      },
-      {
-        "name": "--pairing-code-stdin",
-        "value": "boolean",
-        "summary": "Read the one-time pairing code from stdin."
-      },
-      {
-        "name": "--root",
-        "value": "string",
-        "summary": "Approve an absolute workspace directory; repeatable."
-      },
-      {
-        "name": "--toolchain-root",
-        "value": "string",
-        "summary": "Approve a read-only toolchain directory; repeatable."
-      },
-      {
-        "name": "--executor-helper",
-        "value": "string",
-        "summary": "Select a reviewed native helper file."
-      },
-      {
-        "name": "--name",
-        "value": "string",
-        "summary": "Name this executor."
-      }
-    ],
-    "mutates": true,
-    "json": "payload",
-    "details": [
-      "Executor-local operation; Hub consent and session control stay in the dashboard."
-    ]
-  },
-  {
-    "command": [
-      "remote-workspace",
-      "agent"
-    ],
-    "summary": "Keep the paired executor connected to its Hub.",
-    "routes": [],
-    "flags": [],
-    "mutates": true,
-    "json": "none",
-    "details": [
-      "Executor-local operation; Hub consent and session control stay in the dashboard."
-    ]
-  },
-  {
-    "command": [
-      "remote-workspace",
-      "status"
-    ],
-    "summary": "Read local executor enrollment and available capabilities without printing credentials.",
-    "routes": [],
-    "flags": [
-      {
-        "name": "--json",
-        "value": "boolean",
-        "summary": "Emit the public local executor status."
-      }
-    ],
-    "mutates": false,
-    "json": "payload",
-    "details": [
-      "Executor-local operation; Hub consent and session control stay in the dashboard."
-    ]
-  },
-  {
-    command: ["models", "price"],
-    summary: "Read the saved manual price for an exact provider/model selector.",
-    routes: [{ method: "GET", path: "/api/providers/{provider}/model-costs" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit provider, modelId, and cost (null for automatic pricing)." }],
-    mutates: false,
-    json: "envelope",
-    details: ["The provider must be configured; everything after the first slash is the exact upstream model ID."],
-  },
-  {
-    command: ["models", "set-price"],
-    summary: "Save four manual USD-per-1M-token rates, or restore automatic pricing for one model.",
-    routes: [{ method: "PUT", path: "/api/providers/{provider}/model-costs" }],
-    flags: [
-      { name: "--input", value: "number", summary: "Input rate; required unless --auto is used." },
-      { name: "--output", value: "number", summary: "Output rate; required unless --auto is used." },
-      { name: "--cache-read", value: "number", summary: "Cache read rate; defaults to 0." },
-      { name: "--cache-write", value: "number", summary: "Cache write rate; defaults to 0." },
-      { name: "--auto", value: "boolean", summary: "Remove this model's override; cannot be combined with rates." },
-      { name: "--json", value: "boolean", summary: "Emit the saved price or reset result as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: ["Uses the exact upstream model ID after the first slash. Omitted cache rates default to zero; sibling model prices are preserved."],
-  },
-  {
-    command: ["models", "set"],
-    summary: "Save per-model overrides for a routed model, or clear them back to the computed values.",
-    routes: [{ method: "PUT", path: "/api/model-settings" }],
-    flags: [
-      { name: "--context-window", value: "string", summary: "Context window in tokens; 0 or - clears the override." },
-      { name: "--modalities", value: "string", summary: "Comma-separated text,image,audio; - clears the override." },
-      { name: "--reasoning-efforts", value: "string", summary: "Comma-separated ladder; \"\" for no reasoning, - to inherit." },
-      { name: "--default-reasoning-effort", value: "string", summary: "Ladder member a request inherits when it omits one; - to inherit." },
-      { name: "--reset", value: "boolean", summary: "Clear every override on this model; cannot be combined with the options above." },
-      { name: "--json", value: "boolean", summary: "Emit the saved state as JSON." },
-    ],
-    mutates: true,
-    json: "envelope",
-    details: [
-      "Addresses a routed model as provider/model. The native openai lane and combos have no per-model overrides.",
-      "Unlike ocx models edit, which changes a custom model's own definition, this edits a row that already exists.",
-    ],
-  },
-  {
-    command: ["status"],
-    summary: "Proxy status, injection state, and version skew between this CLI and the running proxy.",
-    // No management route: `collectStatus` identity-probes `/healthz` through
-    // `findLiveProxy` and reads local config. Declaring `GET /api/status` here was wrong
-    // -- that route does not exist, and the registry cross-check caught it.
-    routes: [],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the status envelope as JSON." }],
-    mutates: false,
-    json: "envelope",
-    details: ["Reads /healthz plus local config; drives no management API route."],
-  },
-  {
-    command: ["resolve"],
-    summary: "One JSON document naming the config home, the effective port, and the identity-checked proxy liveness verdict.",
-    // No management route, same split as status: discovery is the identity-checked
-    // /healthz probe inside findLiveProxy plus local config and the home from
-    // src/config/paths.ts.
-    routes: [],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the resolve document as JSON (the shell contract)." }],
-    mutates: false,
-    json: "envelope",
-    details: [
-      "Exit 0 carries a trustworthy verdict (live or proven absent); exit 1 means the CLI could not resolve and a caller must refuse to guess — unknown liveness never reads as absent.",
-      "Built for embedding shells (desktop app): the liveness budgets stay owned by src/server/proxy-liveness.ts.",
-    ],
-  },
-  {
-    command: ["hub", "invite"],
-    summary: "Mint a single-use pairing code on a hub and print the exact `ocx connect` line for one more machine.",
-    // Deliberately empty. The command DOES drive `POST /api/gui/pairing-grants` -- the attested
-    // local mint route `ocx gui pair` uses, authorized by a capability HMAC'd with the running
-    // proxy's own attestation secret rather than by the admin token, which is why it needs
-    // nothing exported in the shell. That route is answered in the composition root, ahead of
-    // `handleManagementAPI`, so it is not in MANAGEMENT_ROUTES; declaring it here would fail the
-    // capability/registry reconciliation rather than inform anyone. Widening the registry's scope
-    // to `src/server/index.ts` is its own change.
-    routes: [],
-    flags: [
-      { name: "--json", value: "boolean", summary: "Emit code, expiresAt, dataUrl, managementUrl, and command." },
-      { name: "--data-url", value: "string", summary: "Advertise this data origin instead of hub.dataPublicOrigin or the bind address." },
-      { name: "--management-url", value: "string", summary: "Confirm the management origin; it must equal hub.managementPublicOrigin." },
-      { name: "--clients", value: "string", summary: "Pre-select codex and/or claude in the printed connect command." },
-    ],
-    mutates: true,
-    json: "envelope",
-    details: [
-      "Hub only: refuses when runtimeRole is not hub, and requires a running attested proxy.",
-      "The code is secret, single-use and short-lived; it is bound to hub.managementPublicOrigin and to the connecting machine's loopback browser origin.",
-      "The bound browser origin is always printed; when it is not http://localhost:10100 the warning names the port the connecting machine must use.",
-      "Refuses when the advertised data origin would be loopback (a loopback or wildcard bind with no hub.dataPublicOrigin and no --data-url) rather than printing a line that dials the other machine itself.",
-      "Prints no data-plane token. Remote machines receive their own revocable per-client key from the exchange.",
-      "Mints through the attested local pairing-grant route, the same one ocx gui pair uses; no admin token is read.",
-    ],
-  },
-  {
-    command: ["connect", "rotate"],
-    summary: "Rotate the connected client's data key against the hub, with commit and abort.",
-    // One command drives all three: start returns the new secret once, commit promotes it,
-    // and abort unwinds a rotation that could not be confirmed. They are not separate verbs
-    // because a half-rotation is not a state an operator should be able to leave behind.
-    routes: [
-      { method: "POST", path: "/api/keys/rotate" },
-      { method: "POST", path: "/api/keys/rotate/commit" },
-      { method: "DELETE", path: "/api/keys/rotate" },
-    ],
-    flags: [
-      { name: "--pairing-code-stdin", value: "boolean", summary: "Read a one-time pairing code from stdin as the rotation authority." },
-      { name: "--admin-token-stdin", value: "boolean", summary: "Read the hub admin token from stdin as the rotation authority." },
-      { name: "--json", value: "boolean", summary: "Emit the rotation result as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "Requires transient authority on stdin; the credential is never persisted or echoed.",
-      "A rotation left pending by a crash is resumed here — startup and status stop rather than guess which key generation is live.",
-    ],
-  },
-  {
-    command: ["capabilities"],
-    summary: "List the declared CLI capabilities and the management routes they drive.",
-    routes: [],
-    flags: [
-      { name: "--json", value: "boolean", summary: "Emit the full capability table as JSON." },
-      { name: "--mutating-only", value: "boolean", summary: "Restrict output to capabilities that mutate state." },
-      { name: "--route", value: "string", summary: "Show which capabilities drive a management route." },
-    ],
-    mutates: false,
-    json: "envelope",
-    details: ["Start here when driving ocx programmatically: it is the declared surface index, not a complete verb list."],
-  },
-  {
-    command: ["provider", "list"],
-    summary: "Configured providers with connectivity and selected models.",
-    // Local config + PROVIDER_REGISTRY. Does not call GET /api/providers.
-    routes: [],
-    flags: [
-      { name: "--json", value: "boolean", summary: "Emit the provider list as JSON." },
-      { name: "--jsonl", value: "boolean", summary: "Emit one configured provider per JSON line." },
-    ],
-    mutates: false,
-    json: "envelope",
-    details: ["Reads local config; drives no management API route."],
-  },
-  {
-    command: ["provider", "resets"],
-    summary: "Recently detected quota resets and whether reset notifications are enabled.",
-    routes: [{ method: "GET", path: "/api/quota-resets" }],
-    flags: [
-      { name: "--json", value: "boolean", summary: "Emit reset events as JSON." },
-      { name: "--limit", value: "number", summary: "Limit returned events; defaults to 20, capped at 100." },
-    ],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["provider", "keychain"],
-    summary: "Move a provider's API key into the OS keychain, restore it, or report where it lives.",
-    routes: [
-      { method: "GET", path: "/api/providers/keychain" },
-      { method: "POST", path: "/api/providers/keychain" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the keychain status or result as JSON." }],
-    mutates: true,
-    json: "payload",
-    details: [
-      "`store` verifies every keychain write by read-back before config.json is rewritten with keychain: references; an unavailable keychain refuses with 503 and leaves the file untouched.",
-      "Headless services usually have no unlocked keychain session; prefer ${ENV_VAR} references there.",
-    ],
-  },
-  {
-    command: ["companion"],
-    summary: "Inspect and configure menu-bar and widget companion usage settings.",
-    routes: [
-      { method: "GET", path: "/api/companion/settings" },
-      { method: "GET", path: "/api/usage/timeline" },
-      { method: "PUT", path: "/api/companion/settings" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit companion settings as JSON." }],
-    mutates: true,
-    json: "payload",
-    details: [
-      "`show` (the default) reads settings; `set key=value ...` updates selected settings; `reset` restores defaults.",
-      "Values accepted by `set` are parsed as JSON when valid, so booleans, numbers, arrays, objects, and null can be passed directly.",
-    ],
-  },
-  {
-    command: ["account", "login"],
-    summary: "Log in to an OAuth provider; Kiro can add a native device account.",
-    routes: [
-      { method: "POST", path: "/api/oauth/login" },
-      { method: "GET", path: "/api/oauth/status" },
-    ],
-    flags: [
-      { name: "--method", value: "string", summary: "For Kiro: builder-id, google, or github device login (add only)." },
-      { name: "--reauth", value: "boolean", summary: "Reauthenticate a selected existing account." },
-      { name: "--id", value: "string", summary: "Account id for reauthentication." },
-      { name: "--no-wait", value: "boolean", summary: "Return after the login flow starts." },
-      { name: "--json", value: "boolean", summary: "Emit flow state as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-  },
-  {
-    command: ["account", "history"],
-    summary: "Cached quota observations for one stored Codex pool account.",
-    routes: [{ method: "GET", path: "/api/codex-auth/quota/history" }],
-    flags: [
-      { name: "--json", value: "boolean", summary: "Emit the bounded observation history." },
-      { name: "--limit", value: "number", summary: "Return the newest 1 to 200 observations." },
-    ],
-    mutates: false,
-    json: "payload",
-    details: ["Use account history openai <pool-account-id>. Reads cached observations only; no refresh or warmup. Native main is not included."],
-  },
-  {
-    command: ["account", "main", "reauth"],
-    summary: "Reauthenticate the native main Codex login with a device code (#3898); headless hubs need no Codex App or keyring.",
-    routes: [
-      { method: "POST", path: "/api/codex-auth/main/reauth-device" },
-      { method: "GET", path: "/api/codex-auth/main/reauth-device" },
-      { method: "DELETE", path: "/api/codex-auth/main/reauth-device" },
-    ],
-    flags: [
-      { name: "--device", value: "boolean", summary: "Run the device-code flow (the only reauth mode)." },
-      { name: "--no-wait", value: "boolean", summary: "Print the flow handle and code without waiting for completion." },
-      { name: "--flow", value: "string", summary: "Flow id for status and cancel." },
-      { name: "--json", value: "boolean", summary: "Emit the flow status as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "Same-identity reauth only: the device login must complete for the ChatGPT account that already holds the native main slot, and the commit is fenced by the exclusive claim plus a path/hash/inode snapshot.",
-      "/api/codex-auth/login stays pool-only and keeps rejecting __main__; this namespace is the only device-reauth surface for the native main slot.",
-      "Payloads carry only flowId, status, the verification URL, the device code, and a closed set of failure codes -- never tokens, emails, or raw account ids.",
-    ],
-  },
-  {
-    command: ["account", "list"],
-    summary: "Codex OAuth accounts with pool priority and pause state.",
-    routes: [{ method: "GET", path: "/api/codex-auth/accounts" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the account list as JSON." }],
-    mutates: false,
-    json: "payload",
-    details: [
-      "STATUS names `paused` alongside `selected`: a paused-but-selected account still receives requests.",
-      "`--quota` shows cached Codex windows (including 5h); `--refresh` bypasses the server TTL.",
-    ],
-  },
-  {
-    command: ["account", "import-orca"],
-    summary: "Preview or register read-only links to Orca-managed Codex accounts without another login.",
-    routes: [],
-    flags: [
-      { name: "--source", value: "string", required: true, summary: "Orca data directory containing codex-accounts." },
-      { name: "--registry", value: "string", required: true, summary: "The chosen Orca profile's orca-data.json account registry." },
-      { name: "--apply", value: "boolean", summary: "Register new accounts; requires a stopped proxy. Default is preview." },
-      { name: "--json", value: "boolean", summary: "Emit counts and fixed invalid-reason codes without credentials or source paths." },
-    ],
-    mutates: true,
-    json: "envelope",
-    details: [
-      "Local files only; never copies refresh tokens or changes Orca authentication files.",
-      "Skips existing ChatGPT identities. New accounts remain pending until dashboard validation.",
-      "Orca must keep the source login available and refreshed; a missing or expired source fails closed.",
-      "Mixed eligible and invalid entries exit successfully; an all-invalid result exits nonzero.",
-    ],
-  },
-  {
-    command: ["account", "refresh"],
-    summary: "Refresh account quotas without model validation; pending Codex accounts require dashboard consent.",
-    routes: [
-      { method: "POST", path: "/api/codex-auth/accounts/refresh" },
-      { method: "GET", path: "/api/provider-quotas" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the refresh result as JSON." }],
-    mutates: true,
-    json: "payload",
-    details: ["CLI/admin-token refreshes only observe usage. After quota recovery, a human must click Refresh quotas in the dashboard to authorize model validation. Do not mint a GUI session to work around this consent boundary."],
-  },
-  {
-    command: ["account", "grok-reset-coupons"],
-    summary: "Inspect or redeem Grok billing reset coupons; redemption is journaled and idempotent.",
-    routes: [
-      { method: "GET", path: "/api/grok/reset-coupons" },
-      { method: "POST", path: "/api/grok/reset-coupons/consume" },
-    ],
-    flags: [
-      { name: "--consume", value: "boolean", summary: "Redeem one reset coupon; requires --yes." },
-      { name: "--yes", value: "boolean", summary: "Explicit confirmation required by --consume." },
-      { name: "--token-id", value: "string", summary: "Redeem a specific reset token instead of the default selection." },
-      { name: "--operation-id", value: "string", summary: "UUIDv4 making a redemption idempotent: retries replay the journaled outcome." },
-      { name: "--json", value: "boolean", summary: "Emit the coupon list or redemption result as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "Without --consume this is a read: remaining coupons and their validity windows.",
-      "The operation is journaled before the upstream call, so retrying the same --operation-id replays the recorded outcome instead of spending a second coupon.",
-    ],
-  },
-  {
-    command: ["usage"],
-    summary: "Token and estimated-cost report over a time range.",
-    routes: [{ method: "GET", path: "/api/usage" }],
-    flags: [
-      { name: "--range", value: "string", summary: "today | 1d | 7d | 30d | all" },
-      { name: "--since", value: "string", summary: "Inclusive start: epoch milliseconds or full ISO datetime with timezone; requires --until and overrides --range." },
-      { name: "--until", value: "string", summary: "Inclusive end: epoch milliseconds or full ISO datetime with timezone; requires --since." },
-      { name: "--provider", value: "string", summary: "Restrict to one provider." },
-      { name: "--model", value: "string", summary: "Restrict to one model id." },
-      { name: "--json", value: "boolean", summary: "Emit the usage report as JSON." },
-    ],
-    mutates: false,
-    json: "payload",
-    details: [
-      "Per-account totals are withheld under `--provider` or `--model`: account rows cannot be honestly re-partitioned by provider, so the report says so rather than printing an empty table.",
-      "An `(ambiguous)` account row aggregates several accounts; do not read it as one identity.",
-    ],
-  },
-  {
-    command: ["account", "pause"],
-    summary: "Exclude one account in a Codex, Anthropic or supported generic OAuth pool from automatic selection.",
-    // Resume uses the same endpoints with `paused: false`.
-    routes: [
-      { method: "PUT", path: "/api/codex-auth/accounts/pause" },
-      { method: "GET", path: "/api/oauth/accounts" },
-      { method: "PUT", path: "/api/oauth/accounts/pause" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the pause result as JSON." }],
-    mutates: true,
-    json: "envelope",
-    details: [
-      "Codex pause unbinds pinned threads and selects a fallback when possible; with no fallback, a paused-but-selected Codex account still receives requests. Anthropic and generic OAuth pause exclude the account from new requests, failover and refresh, and an all-paused pool answers 403. Credentials and health are preserved; already-sent turns are not cancelled.",
-    ],
-  },
-  {
-    command: ["account", "resume"],
-    summary: "Return a paused account to a Codex, Anthropic or supported generic OAuth pool.",
-    routes: [
-      { method: "PUT", path: "/api/codex-auth/accounts/pause" },
-      { method: "GET", path: "/api/oauth/accounts" },
-      { method: "PUT", path: "/api/oauth/accounts/pause" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the resume result as JSON." }],
-    mutates: true,
-    json: "envelope",
-  },
-  {
-    command: ["account", "pause-exhausted"],
-    summary: "Pause every Codex account whose quota is spent.",
-    routes: [{ method: "PUT", path: "/api/codex-auth/accounts/pause-exhausted" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit paused ids and the checked/failed counts as JSON." }],
-    mutates: true,
-    json: "envelope",
-    details: [
-      "The route refreshes quota per account and can partially fail; a non-zero failed count exits 1 and sets ok:false, because silence would read as `none were exhausted`.",
-    ],
-  },
-  {
-    command: ["account", "strategy"],
-    summary: "Show or set how an account pool picks the next account.",
-    // Both pools, because both have the setting. The Codex pool reads its applied values
-    // from the active payload; the Anthropic pool has its own GET.
-    routes: [
-      { method: "GET", path: "/api/pool/settings" },
-      { method: "PUT", path: "/api/pool/settings" },
-      { method: "PATCH", path: "/api/pool/settings" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the applied strategy and sticky limit as JSON." }],
-    mutates: true,
-    json: "envelope",
-    details: [
-      "A bare invocation reads and never writes.",
-      "The APPLIED value is echoed, not the requested one, so a server-side normalization stays visible.",
-      "Values are not re-validated in the CLI: the server owns the strategy names and the 1-100 sticky bound.",
-      "One route answers for every pool kind and declares which fields that kind honours in `supported`, so an unsupported field is a stated null rather than an absence. `anthropic` alone carries `quotaWindow`. Generic-provider settings steer selection only while `pool.kernel` is on. The legacy per-pool paths still work and are unchanged.",
-    ],
-  },
-  {
-    command: ["account", "sticky"],
-    summary: "Show or set how many consecutive requests stay on one account.",
-    routes: [
-      { method: "GET", path: "/api/pool/settings" },
-      { method: "PUT", path: "/api/pool/settings" },
-      { method: "PATCH", path: "/api/pool/settings" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the applied strategy and sticky limit as JSON." }],
-    mutates: true,
-    json: "envelope",
-    details: ["Only meaningful under the sticky-capable strategies; the pool strategy is the other half of this setting."],
-  },
-  {
-    command: ["account", "routes"],
-    summary: "Read, replace, or clear Anthropic OAuth model account routes.",
-    routes: [{ method: "GET", path: "/api/pool/settings" }, { method: "PUT", path: "/api/pool/settings" }],
-    flags: [
-      { name: "--file", value: "string", summary: "Read a bounded JSON route array from a local file." },
-      { name: "--clear", value: "boolean", summary: "Remove the stored routes." },
-      { name: "--json", value: "boolean", summary: "Emit the unified settings response as JSON." },
-    ],
-    mutates: true,
-    json: "envelope",
-    details: ["Only anthropic is supported. The server validates route names, patterns, and account IDs."],
-  },
-  {
-    command: ["account", "auto-switch"],
-    summary: "Show or set the usage percentage at which a pool moves to another account.",
-    // Declared here rather than riding on `account strategy`, which is what it did before the
-    // unified route existed. `auto-switch` genuinely drives these three: the Codex pool reads
-    // its applied threshold from the active payload and writes through its own route, and a
-    // generic OAuth pool reads and writes the per-provider pool settings.
-    routes: [
-      { method: "GET", path: "/api/codex-auth/active" },
-      { method: "PUT", path: "/api/codex-auth/auto-switch" },
-      { method: "GET", path: "/api/oauth/accounts/pool" },
-      { method: "PUT", path: "/api/oauth/accounts/pool" },
-      { method: "GET", path: "/api/oauth/accounts" },
-      { method: "PUT", path: "/api/oauth/accounts/auto-switch" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the stored threshold and whether it is applied." },
-      { name: "--account", value: "string", summary: "Anthropic account ID; inherit restores the pool default, off stores zero." }],
-    mutates: true,
-    json: "envelope",
-    details: [
-      "A bare invocation reads and never writes.",
-      "`on` stores 80%, `off` stores 0%, and `threshold <n>` accepts 0-100.",
-      "Anthropic requires --account <id>; inherit sends null to restore its pool default. Manual/affinity precedence and pool-off recovery are unchanged.",
-      "For a generic OAuth pool, `inert: true` means the threshold is stored but not applied, `inert: false` means the pool is applying it, and an absent `inert` is an unknown capability.",
-    ],
-  },
-
-  {
-    command: ["logs"],
-    summary: "Recent request log rows, filterable by provider, model, conversation, account, and status.",
-    routes: [{ method: "GET", path: "/api/logs" }],
-    flags: [
-      { name: "--provider", value: "string", summary: "Restrict to one provider, matching failover attempts too." },
-      { name: "--model", value: "string", summary: "Restrict to one model id, matching failover attempts too." },
-      { name: "--conversation", value: "string", summary: "Restrict to one conversation id (`--conversationId` is accepted too)." },
-      { name: "--account", value: "string", summary: "Restrict to one account log label (`main`, `p<hex6>`, `o<hex6>`), matching failover attempts too." },
-      { name: "--status", value: "string", summary: "An exact code (429) or a class (5xx)." },
-      { name: "--limit", value: "number", summary: "Row cap; defaults to 200." },
-      { name: "--follow", value: "boolean", summary: "Poll for new rows; add --jsonl to emit JSONL." },
-      { name: "--json", value: "boolean", summary: "Emit the server payload as JSON." },
-      { name: "--jsonl", value: "boolean", summary: "Emit one row per line." },
-    ],
-    mutates: false,
-    json: "payload",
-    details: [
-      "`--provider` and `--model` both match a failover attempt, so a request is findable by what actually served it, not only by what was asked for.",
-      "Rows print `conv=<id>` when the entry carries one, so a conversation filter can be told apart from an empty result.",
-      "Rows print `acct=<label>` when the account is known, so an `--account` filter can be told apart from an empty result.",
-      "`--follow` deduplicates by row id and cannot be combined with `--json`.",
-    ],
-  },
-  {
-    command: ["storage", "report"],
-    summary: "Disk usage under CODEX_HOME, with the log-guard protection report.",
-    routes: [{ method: "GET", path: "/api/storage" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the storage report as JSON." }],
-    mutates: false,
-    json: "payload",
-    bannerLines: ["ocx storage                 Storage report (default subcommand)"],
-  },
-  {
-    command: ["storage", "cleanup"],
-    summary: "Preview or delete the oldest archived sessions by percentage.",
-    // Both routes, because the verb always previews: the mutating route requires the digest the
-    // preview returns and rejects a stale one, so the two are one operation.
-    routes: [
-      { method: "POST", path: "/api/storage/cleanup/preview" },
-      { method: "POST", path: "/api/storage/cleanup" },
-    ],
-    flags: [
-      { name: "--percent", value: "number", summary: "Portion of the oldest archived sessions to target (0-100)." },
-      { name: "--mode", value: "string", summary: "quarantine (recoverable from trash) or permanent." },
-      { name: "--yes", value: "boolean", summary: "Required to actually delete; without it this is a preview." },
-      { name: "--json", value: "boolean", summary: "Emit the preview or result as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "Without `--yes` it prints what WOULD be freed and exits 0 having changed nothing.",
-      "There is no interactive confirmation: a prompt an agent can answer is not a safety boundary.",
-      "`--mode quarantine` moves files to trash, so `storage trash restore` can undo it; `permanent` cannot be undone.",
-    ],
-  },
-  {
-    command: ["storage", "trash"],
-    summary: "List quarantined cleanup batches, or restore one.",
-    routes: [
-      { method: "GET", path: "/api/storage/trash" },
-      { method: "POST", path: "/api/storage/trash/restore" },
-    ],
-    flags: [
-      { name: "--yes", value: "boolean", summary: "Required for restore, which moves files and reconciles database rows." },
-      { name: "--json", value: "boolean", summary: "Emit the trash list or restore result as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: ["Restore fails with a named 409 when the destination already exists, rather than overwriting it."],
-  },
-  {
-    command: ["storage", "policy"],
-    summary: "Show, change, or run the automatic archived-session cleanup policy.",
-    routes: [
-      { method: "GET", path: "/api/storage/cleanup-policy" },
-      { method: "PUT", path: "/api/storage/cleanup-policy" },
-      { method: "POST", path: "/api/storage/cleanup-policy/run" },
-    ],
-    flags: [
-      { name: "--enabled", value: "string", summary: "true or false." },
-      { name: "--percent", value: "number", summary: "Portion of oldest archived sessions each run targets." },
-      { name: "--mode", value: "string", summary: "quarantine or permanent." },
-      { name: "--schedule", value: "string", summary: "startup, daily, weekly, or manual." },
-      { name: "--yes", value: "boolean", summary: "Required for `policy run`, which deletes immediately." },
-      { name: "--json", value: "boolean", summary: "Emit the policy or run state as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "`policy set` never enables implicitly: omitting `--enabled` keeps the stored value.",
-      "`policy run` forces a run regardless of schedule, so it needs `--yes`.",
-    ],
-  },
-  {
-    command: ["inspect", "config"],
-    summary: "The effective merged configuration the proxy is running.",
-    routes: [{ method: "GET", path: "/api/config" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the config as JSON." }],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["inspect", "catalog"],
-    summary: "The generated model catalog served to clients.",
-    routes: [{ method: "GET", path: "/api/catalog" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the catalog as JSON." }],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["inspect", "routing-analytics"],
-    summary: "Aggregate routing outcomes per provider and model.",
-    routes: [{ method: "GET", path: "/api/routing-analytics" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the analytics payload as JSON." }],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["inspect", "pacing"],
-    summary: "Request-pacing state for one provider or all of them.",
-    routes: [{ method: "GET", path: "/api/provider-request-pacing" }],
-    flags: [
-      { name: "--name", value: "string", summary: "Restrict to one provider; omitted means every provider." },
-      { name: "--json", value: "boolean", summary: "Emit the pacing state as JSON." },
-    ],
-    mutates: false,
-    json: "payload",
-    details: ["An unknown provider name is a 404 rather than an empty result."],
-  },
-  {
-    command: ["inspect", "key-providers"],
-    summary: "Providers that authenticate with an API key rather than OAuth.",
-    routes: [{ method: "GET", path: "/api/key-providers" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the provider list as JSON." }],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["inspect", "codex-prompt"],
-    summary: "The Codex system prompt state, or the prompt text itself.",
-    routes: [
-      { method: "GET", path: "/api/codex-prompt" },
-      { method: "GET", path: "/api/codex-prompt/text" },
-    ],
-    flags: [
-      { name: "--text", value: "boolean", summary: "Print the prompt body verbatim instead of its metadata." },
-      { name: "--json", value: "boolean", summary: "Emit the prompt metadata as JSON." },
-    ],
-    mutates: false,
-    json: "payload",
-    details: ["Read-only by design: the six mutating prompt routes require a dashboard session."],
-  },
-  {
-    command: ["inspect", "client-config"],
-    summary: "The generated configuration snippet for a supported client.",
-    routes: [{ method: "GET", path: "/api/client-config" }],
-    flags: [
-      { name: "--client", value: "string", summary: "Required client id; the route names every accepted value on error." },
-      { name: "--json", value: "boolean", summary: "Emit the snippet payload as JSON." },
-    ],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["inspect", "star"],
-    summary: "Whether this repository is starred by the signed-in GitHub account.",
-    // GET only, permanently. The POST spends the operator identity and requires a dashboard
-    // session precisely so an agent cannot answer that question for them.
-    routes: [{ method: "GET", path: "/api/github/star" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the star status as JSON." }],
-    mutates: false,
-    json: "payload",
-    details: ["Starring is never available from the CLI; the verb says so rather than offering a flag that cannot work."],
-  },
-  {
-    command: ["inspect", "windows-tray"],
-    summary: "Windows tray helper state.",
-    routes: [{ method: "GET", path: "/api/windows-tray" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the tray state as JSON." }],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["system", "codex-app-server"],
-    summary: "Codex app-server reachability and process state, as the dashboard sees it.",
-    routes: [{ method: "GET", path: "/api/system/codex-app-server" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the app-server state as JSON." }],
-    mutates: false,
-    json: "payload",
-    details: [
-      "The GUI reads this state directly; without a verb an agent could not tell whether the Codex app-server was reachable at all.",
-    ],
-  },
-  {
-    command: ["system", "codex-cli-update", "check"],
-    summary: "Inspect a configured Codex CLI candidate and its ownership provenance.",
-    routes: [],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the redacted provenance report as JSON." }],
-    mutates: false,
-    json: "envelope",
-    details: [
-      "Proof-bound published-launcher context authenticates the configured candidate snapshot, not successful Codex execution; this check does not attest or admit a selected runtime.",
-      "On Windows this first slice performs no candidate or configuration filesystem I/O: only a proof-captured absolute environment candidate can receive lexical app-bundle or version-manager labels; every other Windows candidate fails closed.",
-      "Makes no package-registry request.",
-      "Does not execute Codex or npm, install or repair software, control a process, or write configuration or cache state.",
-    ],
-  },
-  {
-    command: ["system", "codex-cli-update", "attest"],
-    summary: "Observe the selected or explicitly named Windows npm Codex installation files without enabling updates.",
-    routes: [],
-    flags: [
-      { name: "--candidate", value: "string", summary: "Absolute npm codex.cmd or package bin/codex.js path; all four paths are all-or-none." },
-      { name: "--npm-prefix", value: "string", summary: "Absolute prefix containing node_modules/@openai/codex." },
-      { name: "--npm-cli", value: "string", summary: "Absolute node_modules/npm/bin/npm-cli.js path." },
-      { name: "--node", value: "string", summary: "Absolute node.exe path; observed, never executed." },
-      { name: "--json", value: "boolean", summary: "Emit the path-free installation identity observation." },
-    ],
-    mutates: false,
-    json: "envelope",
-    details: [
-      "Opt-in Windows x64 local-volume inspection using held native file handles; refuses reparse points, active writers and unsupported layouts.",
-      "Without explicit paths, the proof-bound launcher snapshot identifies the selected candidate: the configured CODEX_CLI_PATH or the first codex on the captured PATH, with an OpenCodex wrapper resolving to its codex.opencodex-real backing. Discovery only proposes paths; the held-handle observation remains the authority.",
-      "Success binds observed file identities and bytes, not selected-runtime admission or installer ownership.",
-      "selectionAttested, managed and applyAllowed remain false. The digest is an observation, not a durable update permit.",
-      "Does not run the named Codex/npm/Node files, query a registry, install software, control processes or persist state.",
-    ],
-  },
-  {
-    command: ["system", "codex-restart"],
-    summary: "Restart the Codex desktop app and app-servers.",
-    routes: [{ method: "POST", path: "/api/system/codex-restart" }],
-    flags: [
-      { name: "--yes", value: "boolean", summary: "Required: fully quits and relaunches the operator's Codex desktop app, which may discard unsaved composer drafts, model-picker selections, and pending approval prompts; also restarts its app-servers." },
-      { name: "--json", value: "boolean", summary: "Emit the restart result as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "`sync --restart-codex` is not a substitute: it restarts only as a side effect after a catalog or cache write, so it cannot restart a healthy install on request.",
-      "Restarts the Codex desktop app as well as the app-servers, through the same module the CLI uses. When the proxy itself runs inside the Codex app it refuses instead, because restarting the app would kill the request.",
-      "--yes is mandatory because this interrupts a running editor session and may discard unsaved composer drafts, model-picker selections, and pending approval prompts; it must never happen because an agent guessed a subcommand.",
-    ],
-  },
-  {
-    command: ["claude", "config"],
-    summary: "Read or update Claude Code settings, including independent CLI first-party routing.",
-    routes: [{ method: "GET", path: "/api/claude-code" }, { method: "PUT", path: "/api/claude-code" }],
-    flags: [
-      { name: "--first-party", value: "string", summary: "For `set`, on or off; route standalone Claude CLI subscription requests through the intercept." },
-      { name: "--json", value: "boolean", summary: "Emit the management response as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: ["`status` reads the route; `set` writes only submitted fields. Enabling first-party requires a running Claude intercept."],
-  },
-  {
-    command: ["claude", "intercept", "start"],
-    summary: "Start the local Claude interception pair on demand.",
-    routes: [{ method: "POST", path: "/api/claude-intercept/start" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the management response as JSON." }],
-    mutates: true,
-    json: "payload",
-  },
-  {
-    command: ["claude", "desktop", "status"],
-    summary: "Applied-vs-desired Claude Desktop state, including staleness, drift, and health.",
-    routes: [{ method: "GET", path: "/api/claude-desktop/status" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the live status as JSON." }],
-    mutates: false,
-    json: "payload",
-    details: [
-      "Distinct from `claude desktop show`, which reports what this machine WOULD write; this reports what is actually in effect, which only the running proxy knows.",
-    ],
-  },
-  {
-    command: ["claude", "desktop", "bind"],
-    summary: "First-party: serve a Claude Desktop Code tab picker model with an opencodex route.",
-    routes: [{ method: "PUT", path: "/api/claude-desktop/first-party-bindings" }],
-    flags: [],
-    mutates: true,
-    json: "none",
-    details: [
-      "Takes a picker model id (claude-sonnet-4-6) and a route in the Desktop route vocabulary (provider/model or native/<slug>); the route must be one the Desktop profile can offer.",
-      "Only Claude Code traffic that reaches the proxy through the first-party intercept (Desktop's Code tab, the claude CLI) honours it; ocx claude and the public Messages endpoint are unaffected.",
-      "The Desktop picker keeps Anthropic's label; the binding changes which model answers, starting with the next request.",
-    ],
-  },
-  {
-    command: ["claude", "desktop", "unbind"],
-    summary: "Remove a first-party Claude Desktop Code tab picker binding.",
-    routes: [{ method: "PUT", path: "/api/claude-desktop/first-party-bindings" }],
-    flags: [],
-    mutates: true,
-    json: "none",
-    details: [
-      "Removing an id that is not bound is a no-op; the remaining bindings are printed.",
-    ],
-  },
-  {
-    command: ["claude", "desktop", "picker", "status"],
-    summary: "First-party picker mode: whether Claude Desktop's Code tab lists opencodex models, and what is missing if not.",
-    routes: [{ method: "GET", path: "/api/claude-desktop/picker" }],
-    flags: [],
-    mutates: false,
-    json: "none",
-    details: [
-      "Reports desired, effective, keychain trust, the Desktop egress profile, the model count and a reason with the next command to run.",
-    ],
-  },
-  {
-    command: ["claude", "desktop", "picker", "on"],
-    summary: "Turn first-party picker mode on and remember the choice.",
-    routes: [{ method: "PUT", path: "/api/claude-desktop/picker" }],
-    flags: [],
-    mutates: true,
-    json: "none",
-    details: [
-      "Needs a running proxy, first-party mode and macOS. The first time, macOS asks to trust a local certificate authority limited to claude.ai; when the server cannot show that prompt the command runs the trust step in this terminal.",
-      "Claude Desktop then reaches the network through opencodex; fully quit and reopen Desktop afterwards.",
-    ],
-  },
-  {
-    command: ["claude", "desktop", "picker", "off"],
-    summary: "Turn first-party picker mode off, remove its Desktop egress profile and certificate trust, and remember the choice.",
-    routes: [{ method: "PUT", path: "/api/claude-desktop/picker" }],
-    flags: [],
-    mutates: true,
-    json: "none",
-    details: [
-      "Works without a running proxy: the preference is saved and the picker profile and trust are removed locally.",
-    ],
-  },
-  {
-    command: ["claude", "desktop", "picker", "trust"],
-    summary: "Run the macOS keychain step for picker mode in this terminal, then ask the server to finish enabling it.",
-    routes: [{ method: "PUT", path: "/api/claude-desktop/picker" }],
-    flags: [],
-    mutates: true,
-    json: "none",
-    details: [
-      "The server removes trust this command added if the enable is refused; if the request is lost, trust is left alone and picker status tells what happened.",
-    ],
-  },
-  {
-    command: ["integration", "native"],
-    summary: "Show or toggle the native Claude, Claude Desktop, Codex, and Grok integrations, and read the Cursor status (which builds are installed, gateway values, last request seen) and, on request, the Private Inference installer Cursor's update channel advertises.",
-    routes: [
-      { method: "GET", path: "/api/native-integrations" },
-      { method: "PUT", path: "/api/native-integrations/claude" },
-      { method: "PUT", path: "/api/native-integrations/claude-desktop" },
-      { method: "PUT", path: "/api/native-integrations/codex" },
-      { method: "PUT", path: "/api/native-integrations/grok" },
-      { method: "GET", path: "/api/native-integrations/cursor" },
-      { method: "GET", path: "/api/native-integrations/cursor/local-installer" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the client rows or toggle result as JSON." }],
-    mutates: true,
-    json: "payload",
-    details: [
-      "The list renders per-client state, installed, and desired columns; a blocked disable is named rather than left silent.",
-      "Each client has its own route because a toggle rewrites that client's own config file.",
-    ],
-  },
-  {
-    command: ["integration", "client"],
-    summary: "Inspect and toggle Aside profile catalogs, read their history, and restore a selected profile operation.",
-    routes: [
-      { method: "GET", path: "/api/client-integrations/aside/profiles" },
-      { method: "PUT", path: "/api/client-integrations/aside/profiles" },
-      { method: "GET", path: "/api/client-integrations/aside/profiles/{profileId}" },
-      { method: "PUT", path: "/api/client-integrations/aside/profiles/{profileId}" },
-      { method: "GET", path: "/api/client-integrations/aside/profiles/journal" },
-      { method: "GET", path: "/api/client-integrations/aside/profiles/{profileId}/journal" },
-      { method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/restore" },
-    ],
-    flags: [
-      { name: "--client", value: "string", summary: "Select the file integration; use aside for profile controls." },
-      { name: "--profile", value: "number", summary: "Select one registered Aside account; omitted toggles affect all profiles." },
-      { name: "--op", value: "string", summary: "Operation ID for restore." },
-      { name: "--confirm-drift", value: "boolean", summary: "Explicitly allow restore to replace subsequent edits." },
-      { name: "--overwrite-conflict", value: "boolean", summary: "Explicitly allow enable to replace a conflicting provider block." },
-      { name: "--json", value: "boolean", summary: "Emit the profile state, history, or mutation result as JSON." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "Use status/show/list, history/journal, enable/disable, or restore after integration client.",
-      "These declarations cover the dedicated Aside profile paths; existing generic client routes retain their separate parity inventory.",
-    ],
-  },
-  {
-    command: ["sync"],
-    summary: "Synchronize client catalogs, including Aside profiles through the running server's mutation owner.",
-    routes: [{ method: "POST", path: "/api/client-integrations/aside/sync" }],
-    flags: [
-      { name: "--restart-codex", value: "boolean", summary: "Restart the Codex app-servers and fully quit and relaunch the Codex desktop app after a catalog or cache write, on macOS, Linux and Windows." },
-      { name: "--restart-app-server-only", value: "boolean", summary: "Restart only the Codex app-servers and leave the desktop app running; wins over --restart-codex when both are given." },
-      { name: "--restart-desktop-app", value: "boolean", summary: "Deprecated alias of --restart-codex." },
-    ],
-    mutates: true,
-    json: "none",
-    details: ["The Aside refresh uses the live server; other catalog synchronization also performs local work."],
-  },
-  {
-    command: ["agent", "subagents", "force"],
-    summary: "Force Claude Code subagents onto one exposed model at the next routed launch; - clears.",
-    routes: [{ method: "GET", path: "/api/subagent-models" }, { method: "PUT", path: "/api/subagent-models" }],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the saved force setting." }],
-    mutates: true,
-    json: "payload",
-    details: ["Requires Claude Code 2.1.257+. Plain claude, forks, inherit skills, the main model and small-fast sidecars are unaffected."],
-  },
-  {
-    command: ["agent", "request-user-input"],
-    summary: "Show or set whether default mode may ask the operator a question mid-task.",
-    routes: [
-      { method: "GET", path: "/api/codex-auth/features/default-mode-request-user-input" },
-      { method: "PUT", path: "/api/codex-auth/features/default-mode-request-user-input" },
-    ],
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the feature state as JSON." }],
-    mutates: true,
-    json: "payload",
-    details: ["A bare invocation reads and never writes."],
-  },
-  {
-    command: ["agent", "roles"],
-    summary: "omo (Codex / LazyCodex): show each Codex agent role's model pin, set one role's model in its TOML and in omo.jsonc, or suggest a model for every role.",
-    routes: [
-      { method: "GET", path: "/api/codex-agent-roles" },
-      { method: "PUT", path: "/api/codex-agent-roles/{role}" },
-      { method: "POST", path: "/api/codex-agent-roles/auto-assign" },
-    ],
-    flags: [
-      { name: "--json", value: "boolean", summary: "Emit the role list, the write result or the proposals as JSON." },
-      { name: "--model", value: "string", summary: "suggest: size the roles with this model instead of the Codex default model." },
-      { name: "--apply", value: "boolean", summary: "suggest: write every proposal through the role model write." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "A bare invocation reads and never writes.",
-      "Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.",
-      "set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml; omo.jsonc is skipped when absent or when it contains comments.",
-      "suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort.",
-    ],
-  },
-  {
-    command: ["agent", "injection"],
-    summary: "Show or set the delegation model and effort, or suggest both for a described piece of delegated work.",
-    routes: [
-      { method: "GET", path: "/api/injection-model" },
-      { method: "PUT", path: "/api/injection-model" },
-      { method: "POST", path: "/api/injection-model/suggest" },
-    ],
-    flags: [
-      { name: "--json", value: "boolean", summary: "Emit the delegation settings, the write result or the proposal as JSON." },
-      { name: "--model", value: "string", summary: "set: the delegation model, - clears it. suggest: size the work with this model instead of the Codex default model." },
-      { name: "--effort", value: "string", summary: "set: the delegation reasoning effort, - clears it." },
-      { name: "--prompt", value: "string", summary: "set: a custom guidance prompt, - clears it." },
-      { name: "--guidance", value: "string", summary: "set: on or off for OpenCodex delegation guidance." },
-      { name: "--apply", value: "boolean", summary: "suggest: write the proposed model and effort through the delegation settings write." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "A bare invocation reads and never writes.",
-      "suggest sizes the described work with one model call, picks the cheapest sufficient model the delegation picker offers, and writes nothing unless --apply is given.",
-    ],
-  },
-  {
-    command: ["api", "protocols"],
-    summary: "Read the protocol contract version, API surfaces, protocol settings and feature vocabulary.",
-    routes: [{ method: "GET", path: "/api/protocols" }],
-    flags: [
-      { name: "--provider", value: "string", summary: "Add one configured provider's upstream wire and who decided it." },
-      { name: "--json", value: "boolean", summary: "Emit the GET /api/protocols body." },
-    ],
-    mutates: false,
-    json: "payload",
-  },
-  {
-    command: ["combo", "test"],
-    summary: "Run one JEV decision probe through a decision method: TypeSafe, a System One row, or an opencodex model.",
-    routes: [{ method: "POST", path: "/api/combos/decision-test" }],
-    flags: [
-      { name: "--combo", value: "string", summary: "Combo id whose saved decision method is probed and whose recursion rules apply." },
-      { name: "--decision-provider", value: "string", summary: "Probe a jev-decision provider row (or jev for TypeSafe) instead of the saved method." },
-      { name: "--decision-model", value: "string", summary: "Probe an opencodex-routed model instead of the saved method." },
-      { name: "--decision-timeout", value: "number", summary: "Decision deadline in milliseconds (1000-120000)." },
-      { name: "--json", value: "boolean", summary: "Emit the probe result." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: ["Sends one synthetic two-option decision; it may spend a decision call on the chosen backend."],
-  },
-  {
-    command: ["combo", "discover"],
-    summary: "List configured System One decision rows and catalog models that look like decision services.",
-    routes: [{ method: "GET", path: "/api/combos/decision-discovery" }],
-    flags: [
-      { name: "--query", value: "string", summary: "Match catalog rows by this text instead of the built-in decision-model hint." },
-      { name: "--json", value: "boolean", summary: "Emit the discovery payload." },
-    ],
-    mutates: false,
-    json: "payload",
-    details: ["Read-only: nothing is probed and no provider row is created."],
-  },
-  {
-    command: ["api", "explain"],
-    summary: "Preview the request path a model would take from one inbound API, computed from config.",
-    routes: [{ method: "POST", path: "/api/protocols/plan" }],
-    flags: [
-      { name: "--model", value: "string", required: true, summary: "Model selector as a client would send it." },
-      { name: "--inbound", value: "string", required: true, summary: "Inbound API: responses, chat or messages." },
-      { name: "--feature", value: "string", summary: "Request feature key to judge; repeatable or comma-separated." },
-      { name: "--json", value: "boolean", summary: "Emit the ProtocolPlanV1 preview." },
-    ],
-    mutates: false,
-    json: "payload",
-    details: ["A read-only POST: nothing is sent upstream, no combo state advances and the input is not logged."],
-  },
-  {
-    command: ["api", "policy"],
-    summary: "Read the protocol policy, or change the Messages surface, unrepresentable policy and rollout switches.",
-    routes: [
-      { method: "GET", path: "/api/protocols" },
-      { method: "PATCH", path: "/api/protocols/settings" },
-    ],
-    flags: [
-      { name: "--messages", value: "string", summary: "Open or close the Messages API: on or off. Off also turns the Claude integration off." },
-      { name: "--unrepresentable", value: "string", summary: "legacy keeps today's behavior; reject refuses a request its path cannot carry." },
-      { name: "--rollout", value: "string", summary: "One switch as name=on or name=off; repeatable. Every switch defaults off." },
-      { name: "--json", value: "boolean", summary: "Emit the resulting GET /api/protocols body." },
-    ],
-    mutates: true,
-    json: "payload",
-    details: [
-      "A bare invocation reads and never writes.",
-      "A setting flag changes the operator's config; run it only when the operator asks for that change.",
-    ],
-  },
+  ...BASE_CAPABILITIES,
+  ...PROVIDER_MODEL_CAPABILITIES,
+  ...ACCOUNT_CAPABILITIES,
+  ...AGENT_ROUTING_CAPABILITIES,
+  ...INTEGRATION_CAPABILITIES,
+  ...OBSERVE_SYSTEM_CAPABILITIES,
+  ...ACCESS_REMOTE_CAPABILITIES,
+  ...LAB_CAPABILITIES,
 ];
 
+export { HEAD_CAPABILITIES } from "./capabilities-base";
+export type {
+  CapabilityRoute,
+  CapabilityFlag,
+  CapabilityJsonMode,
+  Capability,
+  HeadCapability,
+} from "./capability-types";
+
 /** Capabilities that drive `route`, for `ocx capabilities --route`. */
 export function capabilitiesForRoute(path: string): Capability[] {
   return CAPABILITIES.filter(cap => cap.routes.some(r => r.path === path));
diff --git a/src/cli/capability-types.ts b/src/cli/capability-types.ts
new file mode 100644
index 00000000000..e831e2c3030
--- /dev/null
+++ b/src/cli/capability-types.ts
@@ -0,0 +1,54 @@
+/** A management route a capability drives. Path text only; never a handler reference. */
+export interface CapabilityRoute {
+  readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  readonly path: string;
+}
+
+export interface CapabilityFlag {
+  readonly name: string;
+  readonly value?: "string" | "number" | "boolean";
+  readonly required?: boolean;
+  readonly summary: string;
+}
+
+/**
+ * How a capability emits JSON.
+ *
+ * - `payload`: the API payload, largely unwrapped.
+ * - `envelope`: a CLI-shaped object with its own schema.
+ * - `none`: no `--json` mode.
+ */
+export type CapabilityJsonMode = "payload" | "envelope" | "none";
+
+export interface Capability {
+  /** Command path, e.g. `["account", "pause"]`. */
+  readonly command: readonly string[];
+  readonly summary: string;
+  readonly routes: readonly CapabilityRoute[];
+  readonly flags: readonly CapabilityFlag[];
+  readonly mutates: boolean;
+  readonly json: CapabilityJsonMode;
+  /** Complete CLI usage, including operands, when verified for this leaf. */
+  readonly usage?: string;
+  readonly details?: readonly string[];
+  /**
+   * Extra banner rows this capability owns, for surfaces the banner shows separately
+   * from the bare command (`ocx restore back`, `ocx doctor --reclaim-response-temps`).
+   * Without this the banner cannot equal the capability set: it legitimately carries more
+   * rows than there are commands.
+   */
+  readonly bannerLines?: readonly string[];
+}
+
+/**
+ * Surfaces resolved in the CLI head, before dispatch.
+ *
+ * They belong in `ocx capabilities` output and in the banner, but not in `CLI_COMMANDS`:
+ * `--version`, `-v`, and `version` are answered at `root.ts` and exit, so none of them is
+ * a runner key to parity-check against.
+ */
+export interface HeadCapability {
+  readonly invocations: readonly string[];
+  readonly summary: string;
+  readonly bannerLine: string;
+}
diff --git a/src/cli/help-catalog.ts b/src/cli/help-catalog.ts
index 702c6c99d40..37264a08e22 100644
--- a/src/cli/help-catalog.ts
+++ b/src/cli/help-catalog.ts
@@ -3,7 +3,7 @@ import { CLI_COMMANDS, findCommand, type CliCommandEntry } from "./registry";
 
 export type HelpResolution =
   | { kind: "entry"; entry: CliCommandEntry; canonicalName: string; children: readonly Capability[] }
-  | { kind: "capability"; path: string[]; capability: Capability }
+  | { kind: "capability"; path: string[]; capability: Capability; children: readonly Capability[] }
   | { kind: "prefix"; path: string[]; children: readonly Capability[] }
   | { kind: "models-context"; path: string[] }
   | { kind: "unavailable"; path: string[]; parent?: string[] };
@@ -22,6 +22,18 @@ function canonicalEntry(entry: CliCommandEntry): CliCommandEntry {
   return CLI_COMMANDS.find(candidate => candidate.aliases?.includes(entry.name)) ?? entry;
 }
 
+/** Help-only aliases from access dispatch; never rewrite execution argv or operands. */
+function canonicalHelpPath(requested: readonly string[], entry: CliCommandEntry): string[] {
+  const path = entry.name === "api-key"
+    ? ["access", "key", ...requested.slice(1)]
+    : [canonicalEntry(entry).name, ...requested.slice(1)];
+  if (path[0] === "access") {
+    if (path[1] === "keys") path[1] = "key";
+    if (path[1] === "key" && path[2] === "delete") path[2] = "remove";
+  }
+  return path;
+}
+
 export interface HelpRecoveryCandidate {
   names: string[];
   path: string[];
@@ -35,19 +47,24 @@ export function helpRecoveryCandidates(parent: readonly string[] = []): HelpReco
       if (entry.hidden) continue;
       const canonical = canonicalEntry(entry);
       if (canonical.hidden) continue;
-      const candidate = candidates.get(canonical.name) ?? { names: [], path: [canonical.name] };
+      const path = canonicalHelpPath([entry.name], entry);
+      const identity = path.join(" ");
+      const candidate = candidates.get(identity) ?? { names: [], path };
       candidate.names = [...new Set([...candidate.names, entry.name, ...(entry.aliases ?? [])])];
-      candidates.set(canonical.name, candidate);
+      candidates.set(identity, candidate);
     }
   } else {
-    if (parent.length >= MAX_DOCUMENTED_DEPTH) return [];
     const entry = findCommand(parent[0]);
     if (!entry || entry.hidden) return [];
-    const prefix = [canonicalEntry(entry).name, ...parent.slice(1)];
+    const prefix = canonicalHelpPath(parent, entry);
+    if (prefix.length >= MAX_DOCUMENTED_DEPTH) return [];
     for (const documented of DOCUMENTED_PATHS) {
       if (documented.length <= prefix.length || !startsWithPath(documented, prefix)) continue;
       const path = documented.slice(0, prefix.length + 1);
-      candidates.set(path.join(" "), { names: [path[path.length - 1]], path });
+      const names = [path[path.length - 1]];
+      if (path.join(" ") === "access key") names.push("keys");
+      if (path.join(" ") === "access key remove") names.push("delete");
+      candidates.set(path.join(" "), { names, path });
     }
   }
   return [...candidates.values()];
@@ -58,19 +75,18 @@ export function resolveHelpPath(requested: readonly string[]): HelpResolution {
   const entry = requested[0] ? findCommand(requested[0]) : undefined;
   if (!entry) return { kind: "unavailable", path: [...requested] };
   // Keep exact-name alias entries for root help; nested topics use the owner.
-  const canonical = canonicalEntry(entry);
+  const path = canonicalHelpPath(requested, entry);
   const declared = CAPABILITIES.filter(capability => !findCommand(capability.command[0])?.hidden);
   if (requested.length === 1) return {
-    kind: "entry", entry, canonicalName: canonical.name,
-    children: entry.hidden ? [] : declared.filter(candidate => candidate.command.length > 1 && candidate.command[0] === canonical.name),
+    kind: "entry", entry, canonicalName: path.join(" "),
+    children: entry.hidden ? [] : declared.filter(candidate => candidate.command.length > path.length && startsWithPath(candidate.command, path)),
   };
-  const path = [canonical.name, ...requested.slice(1)];
   if (path.length === 2 && path[0] === "models" && path[1] === "context") {
     return { kind: "models-context", path };
   }
   const capability = declared.find(candidate => candidate.command.length === path.length && startsWithPath(candidate.command, path));
-  if (capability) return { kind: "capability", path, capability };
-  const children = declared.filter(candidate => startsWithPath(candidate.command, path));
+  const children = declared.filter(candidate => candidate.command.length > path.length && startsWithPath(candidate.command, path));
+  if (capability) return { kind: "capability", path, capability, children };
   if (children.length) return { kind: "prefix", path, children };
 
   for (let length = Math.min(path.length - 1, MAX_DOCUMENTED_DEPTH); length > 1; length--) {
@@ -80,5 +96,5 @@ export function resolveHelpPath(requested: readonly string[]): HelpResolution {
       return { kind: "unavailable", path, parent };
     }
   }
-  return { kind: "unavailable", path, parent: [canonical.name] };
+  return { kind: "unavailable", path, parent: [path[0]] };
 }
diff --git a/src/cli/help-recovery.ts b/src/cli/help-recovery.ts
index 37dca8719d0..41885b4409a 100644
--- a/src/cli/help-recovery.ts
+++ b/src/cli/help-recovery.ts
@@ -35,9 +35,9 @@ function distance(left: string, right: string, limit: number): number {
 export function suggestHelpPaths(path: readonly string[]): string[][] {
   if (!path.length || path.length > MAX_PATH_DEPTH || !path.every(safeToken)) return [];
   const result = resolveHelpPath(path);
-  if (result.kind !== "unavailable") return [];
+  if (result.kind !== "unavailable" || result.path.length > MAX_PATH_DEPTH) return [];
   const parent = result.parent ?? [];
-  const token = path[parent.length].toLowerCase();
+  const token = result.path[parent.length].toLowerCase();
   const limit = token.length < 6 ? 1 : 2;
   return helpRecoveryCandidates(parent).map(candidate => ({
     path: candidate.path,
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 63abff64822..dc78abfe43c 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -96,7 +96,7 @@ Usage:
   ocx system <sub>            Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
   ocx config [sub]            Validated configuration show/get/set/import/export
   ocx companion <show|set|reset>  Menu-bar and widget companion usage settings
-  ocx lab <sub>               Read-only Compatibility Lab projection inspection
+  ocx lab <sub>               Inspect Lab evidence and control local automation
   ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
@@ -154,7 +154,8 @@ export function printSubcommandUsage(
     write(`Usage:\n${MODELS_CONTEXT_USAGE}\n\n${MODELS_CONTEXT_DETAILS.join("\n")}`);
   } else if (result.kind === "capability") {
     const { capability } = result;
-    write(`Command: ocx ${result.path.join(" ")}\n\n${capability.summary}`);
+    const heading = capability.usage !== undefined ? `Usage: ${capability.usage}` : `Command: ocx ${result.path.join(" ")}`;
+    write(`${heading}\n\n${capability.summary}`);
     if (capability.flags.length) {
       write("\nDeclared flags:");
       for (const flag of capability.flags) {
@@ -162,7 +163,13 @@ export function printSubcommandUsage(
       }
     }
     if (capability.details?.length) write(`\n${capability.details.join("\n")}`);
-    write("\nCapability metadata is incomplete; this is not the full operand grammar.");
+    if (result.children.length) {
+      write("\nDeclared commands (incomplete):");
+      for (const child of result.children) write(`  ocx help ${child.command.join(" ")}  ${child.summary}`);
+    }
+    if (capability.usage === undefined) {
+      write("\nCapability metadata is incomplete; this is not the full operand grammar.");
+    }
   } else {
     write(`Command group: ocx ${result.path.join(" ")}\n\nDeclared commands (incomplete):`);
     for (const child of result.children) write(`  ocx ${child.command.join(" ")}  ${child.summary}`);
diff --git a/src/cli/registry.ts b/src/cli/registry.ts
index a0452cbcc55..0af4b01b428 100644
--- a/src/cli/registry.ts
+++ b/src/cli/registry.ts
@@ -633,8 +633,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "lab",
-    usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog> [options] [--json]",
-    summary: "Read-only Compatibility Lab projection inspection (local SQLite; no daemon).",
+    usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog|production-signals|public|automation|run> [options] [--json]",
+    summary: "Inspect local Compatibility Lab evidence and explicitly control automation.",
     details: [
       "status                Projection availability, schema versions, and row counts.",
       "verdicts              Paginated derived compatibility verdicts with filters.",
@@ -643,6 +643,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "events                Event history; event <id> returns one safe typed event.",
       "artifacts             Artifact metadata only (no content download).",
       "catalog               Packaged protocol/live scenario catalog metadata.",
+      "production-signals    Local passive routing evidence for a subject.",
+      "public                Preview/export local evidence; verify/import a bundle.",
+      "automation            Read status/runs or explicitly enable/disable local policy.",
+      "run                   Explicit manual scenario; live probes can consume quota.",
       "Reads never rebuild the projection, trigger probes, or require the proxy.",
     ],
   },
diff --git a/src/server/management/route-registry.ts b/src/server/management/route-registry.ts
index f2441b824da..3516e8917f6 100644
--- a/src/server/management/route-registry.ts
+++ b/src/server/management/route-registry.ts
@@ -234,8 +234,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   // server/management/lab-automation-routes
   { method: "GET", path: "/api/lab/automation", module: "server/management/lab-automation-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
   { method: "GET", path: "/api/lab/automation/runs", module: "server/management/lab-automation-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
-  { method: "POST", path: "/api/lab/automation/run", module: "server/management/lab-automation-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Lab automation run has no CLI verb yet. A local SQLite read cannot drive it, so local-transport does not apply.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
-  { method: "PUT", path: "/api/lab/automation", module: "server/management/lab-automation-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Lab automation config update has no CLI verb yet. A local SQLite read cannot drive it, so local-transport does not apply.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
+  { method: "POST", path: "/api/lab/automation/run", module: "server/management/lab-automation-routes", mutates: true, exempt: { reason: "deferred-verb", why: "ocx lab run explicitly executes a local scenario. The local invocation does not control the selected running proxy; this HTTP operation remains deferred.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
+  { method: "PUT", path: "/api/lab/automation", module: "server/management/lab-automation-routes", mutates: true, exempt: { reason: "deferred-verb", why: "ocx lab automation enable/disable updates local policy. The local invocation does not control the selected running proxy; this HTTP operation remains deferred.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
   // server/management/lab-routes
   { method: "GET", path: "/api/lab/artifacts", module: "server/management/lab-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
   { method: "GET", path: "/api/lab/catalog", module: "server/management/lab-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
@@ -246,10 +246,10 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/lab/status", module: "server/management/lab-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
   { method: "GET", path: "/api/lab/subjects", module: "server/management/lab-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
   { method: "GET", path: "/api/lab/verdicts", module: "server/management/lab-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
-  { method: "POST", path: "/api/lab/public/community/import", module: "server/management/lab-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Community evidence import has no CLI verb yet. A local SQLite read cannot drive it, so local-transport does not apply.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
-  { method: "POST", path: "/api/lab/public/export", module: "server/management/lab-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Public evidence export has no CLI verb yet. A local SQLite read cannot drive it, so local-transport does not apply.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
-  { method: "POST", path: "/api/lab/public/preview", module: "server/management/lab-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Public evidence preview has no CLI verb yet. A local SQLite read cannot drive it, so local-transport does not apply.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
-  { method: "POST", path: "/api/lab/public/verify", module: "server/management/lab-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Public evidence verification has no CLI verb yet. A local SQLite read cannot drive it, so local-transport does not apply.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
+  { method: "POST", path: "/api/lab/public/community/import", module: "server/management/lab-routes", mutates: true, exempt: { reason: "deferred-verb", why: "ocx lab public import reads a local bundle file. The local invocation does not control the selected running proxy; this HTTP operation remains deferred.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
+  { method: "POST", path: "/api/lab/public/export", module: "server/management/lab-routes", mutates: true, exempt: { reason: "deferred-verb", why: "ocx lab public export uses local evidence. The local invocation does not control the selected running proxy; this HTTP operation remains deferred.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
+  { method: "POST", path: "/api/lab/public/preview", module: "server/management/lab-routes", mutates: true, exempt: { reason: "deferred-verb", why: "ocx lab public preview uses local evidence. The local invocation does not control the selected running proxy; this HTTP operation remains deferred.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
+  { method: "POST", path: "/api/lab/public/verify", module: "server/management/lab-routes", mutates: true, exempt: { reason: "deferred-verb", why: "ocx lab public verify reads a local bundle file. The local invocation does not control the selected running proxy; this HTTP operation remains deferred.", owner: "wp7", ownerDoc: "devlog/_plan/260828_ocx_agentic_control/060_phase_gui_parity.md" } },
   // server/management/logs-usage-routes
   { method: "GET", path: "/api/claude/inbound-debug", module: "server/management/logs-usage-routes", mutates: false },
   { method: "GET", path: "/api/debug", module: "server/management/logs-usage-routes", mutates: false },
@@ -263,7 +263,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/storage/trash/restore/test-stream", module: "server/management/logs-usage-routes", mutates: false, exempt: { reason: "test-seam", why: "Opt-in streaming seam declared at src/storage/restore-job.ts:34." } },
   { method: "GET", path: "/api/usage", module: "server/management/logs-usage-routes", mutates: false },
   // server/management/usage-timeline-routes
-  { method: "GET", path: "/api/usage/timeline", module: "server/management/usage-timeline-routes", mutates: false },
+  { method: "GET", path: "/api/usage/timeline", module: "server/management/usage-timeline-routes", mutates: false, exempt: { reason: "deferred-verb", why: "The earlier capability advertised this route without invoking it; a dedicated CLI operation remains tracked in the parity roadmap.", owner: "261003_cli_gui_parity", ownerDoc: "devlog/_plan/261003_cli_gui_parity/070_observation_api_tools.md" } },
   // server/management/companion-routes
   { method: "POST", path: "/api/companion/open-in-browser", module: "server/management/companion-routes", mutates: true, exempt: { reason: "session-only", why: "Dashboard-only navigation helper; the GUI session opens its current view in the system browser, and there is no standalone CLI operation to drive." } },
   { method: "GET", path: "/api/companion/settings", module: "server/management/companion-routes", mutates: false },
@@ -301,8 +301,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "PUT", path: "/api/native-integrations/codex", module: "server/management/native-integration-routes", mutates: true },
   { method: "PUT", path: "/api/native-integrations/grok", module: "server/management/native-integration-routes", mutates: true },
   // server/management/cursor-integration-routes
-  { method: "GET", path: "/api/native-integrations/cursor", module: "server/management/cursor-integration-routes", mutates: false },
-  { method: "GET", path: "/api/native-integrations/cursor/local-installer", module: "server/management/cursor-integration-routes", mutates: false },
+  { method: "GET", path: "/api/native-integrations/cursor", module: "server/management/cursor-integration-routes", mutates: false, exempt: { reason: "deferred-verb", why: "The earlier capability advertised this route without invoking it; a dedicated CLI operation remains tracked in the parity roadmap.", owner: "261003_cli_gui_parity", ownerDoc: "devlog/_plan/261003_cli_gui_parity/060_integrations_maintenance.md" } },
+  { method: "GET", path: "/api/native-integrations/cursor/local-installer", module: "server/management/cursor-integration-routes", mutates: false, exempt: { reason: "deferred-verb", why: "The earlier capability advertised this route without invoking it; a dedicated CLI operation remains tracked in the parity roadmap.", owner: "261003_cli_gui_parity", ownerDoc: "devlog/_plan/261003_cli_gui_parity/060_integrations_maintenance.md" } },
   // server/management/oauth-account-routes
   { method: "DELETE", path: "/api/keys", module: "server/management/oauth-account-routes", mutates: true },
   { method: "DELETE", path: "/api/keys/rotate", module: "server/management/oauth-account-routes", mutates: true },
@@ -315,7 +315,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/oauth/accounts/pool", module: "server/management/oauth-account-routes", mutates: false },
   { method: "GET", path: "/api/pool/settings", module: "server/management/oauth-account-routes", mutates: false },
   { method: "PUT", path: "/api/pool/settings", module: "server/management/oauth-account-routes", mutates: true },
-  { method: "PATCH", path: "/api/pool/settings", module: "server/management/oauth-account-routes", mutates: true },
+  { method: "PATCH", path: "/api/pool/settings", module: "server/management/oauth-account-routes", mutates: true, exempt: { reason: "compatibility-alias", why: "Handled by the same partial settings branch as PUT /api/pool/settings; current CLI strategy, sticky and routes commands use PUT, not PATCH." } },
   { method: "GET", path: "/api/oauth/providers", module: "server/management/oauth-account-routes", mutates: false },
   { method: "GET", path: "/api/oauth/status", module: "server/management/oauth-account-routes", mutates: false },
   { method: "GET", path: "/api/providers/keys", module: "server/management/oauth-account-routes", mutates: false },
diff --git a/structure/INDEX.md b/structure/INDEX.md
index 2f7e3eea32c..0b1bcf534ab 100644
--- a/structure/INDEX.md
+++ b/structure/INDEX.md
@@ -78,6 +78,7 @@ The dashboard, the management API, and third-party client config ownership.
 
 | Doc | Scope |
 | --- | --- |
+| [`cli-management.md`](cli-management.md) | Terminal help and capability metadata, management-client output and the generated operating reference. |
 | [`gui-and-management-api.md`](gui-and-management-api.md) | Dashboard serving, authentication boundaries, /api/* ownership, and startup safety. |
 | [`dashboard-and-usage.md`](dashboard-and-usage.md) | Dashboard page contracts, usage accounting and request metrics, and per-surface management settings. |
 | [`clients/integrations.md`](clients/integrations.md) | Third-party client config ownership, snapshots, refresh, disable, and restore. |
@@ -114,6 +115,8 @@ A source area can be described by more than one doc, because these docs are orga
 | `docs-site/` | [`ops/docs-and-release.md`](ops/docs-and-release.md) |
 | `gui/` | [`overview.md`](overview.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`dashboard-and-usage.md`](dashboard-and-usage.md)<br>[`design-methodology.md`](design-methodology.md)<br>[`companion.md`](companion.md) |
 | `scripts/` | [`overview.md`](overview.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `scripts/generate-ocx-skill-surface.ts` | [`cli-management.md`](cli-management.md) |
+| `skills/ocx/` | [`cli-management.md`](cli-management.md) |
 | `src/adapters/` | [`runtime.md`](runtime.md)<br>[`transports/byte-accounting.md`](transports/byte-accounting.md)<br>[`transports/responses-wire-shapes.md`](transports/responses-wire-shapes.md)<br>[`transports/inventory.md`](transports/inventory.md)<br>[`data-planes/inbound-compat.md`](data-planes/inbound-compat.md)<br>[`providers-and-adapters.md`](providers-and-adapters.md)<br>[`providers/cursor.md`](providers/cursor.md)<br>[`providers/chat-compat.md`](providers/chat-compat.md)<br>[`adapters/registry.md`](adapters/registry.md) |
 | `src/bridge.ts` | [`transports/responses.md`](transports/responses.md) |
 | `src/bridge/` | [`transports/responses.md`](transports/responses.md)<br>[`transports/responses-wire-shapes.md`](transports/responses-wire-shapes.md) |
@@ -121,7 +124,7 @@ A source area can be described by more than one doc, because these docs are orga
 | `src/chatgpt/` | [`clients/chatgpt-desktop.md`](clients/chatgpt-desktop.md) |
 | `src/claude/` | [`runtime.md`](runtime.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md) |
 | `src/cli.ts` | [`runtime.md`](runtime.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
-| `src/cli/` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md)<br>[`clients/integrations.md`](clients/integrations.md)<br>[`clients/chatgpt-desktop.md`](clients/chatgpt-desktop.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `src/cli/` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md)<br>[`cli-management.md`](cli-management.md)<br>[`clients/integrations.md`](clients/integrations.md)<br>[`clients/chatgpt-desktop.md`](clients/chatgpt-desktop.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
 | `src/client/` | [`runtime.md`](runtime.md)<br>[`clients/claude-desktop.md`](clients/claude-desktop.md) |
 | `src/clients/` | [`clients/integrations.md`](clients/integrations.md) |
 | `src/codex/` | [`runtime.md`](runtime.md)<br>[`config.md`](config.md)<br>[`codex-home.md`](codex-home.md)<br>[`catalog.md`](catalog.md)<br>[`subagents.md`](subagents.md)<br>[`transports/responses-failover.md`](transports/responses-failover.md)<br>[`providers/openai-tiers.md`](providers/openai-tiers.md)<br>[`providers/openai-accounts.md`](providers/openai-accounts.md)<br>[`gui-and-management-api.md`](gui-and-management-api.md)<br>[`dashboard-and-usage.md`](dashboard-and-usage.md)<br>[`clients/chatgpt-desktop.md`](clients/chatgpt-desktop.md)<br>[`ops/docs-and-release.md`](ops/docs-and-release.md) |
diff --git a/structure/cli-management.md b/structure/cli-management.md
new file mode 100644
index 00000000000..552faced063
--- /dev/null
+++ b/structure/cli-management.md
@@ -0,0 +1,37 @@
+# CLI management and discovery
+
+`src/cli/` contains the terminal management interface. Process ownership, startup, stop and service contracts remain in [Runtime](runtime.md); this document owns command discovery, help, management-client presentation and the generated operating reference.
+
+## CLI readiness diagnostics
+
+Catalog-derived reasoning-level diagnostics are escaped only at the human-output boundary, which `src/cli/runtime-api.ts` owns alongside the human/JSON print split. Every CLI path that prints a hub-supplied catalog value renders it there: the first-time refusal in `src/cli/connect.ts` and the connected `ocx sync` refusal in `src/cli/dispatch.ts`. C0/C1 controls, DEL, and Unicode line/paragraph separators print as visible hexadecimal escapes; structured status retains the exact reason, and a rendered failure keeps the domain error as its `cause`. The ready/unverified/incompatible classification and exit policy are unchanged. `src/cli/capabilities-command.ts` rejects leftover positional arguments, unknown or repeated flags, and blank route filters with exit 64 before emitting a capability index; a valid unmatched route remains exit 4. `printData` in `src/cli/runtime-api.ts` escapes each human-output line at the shared renderer, including role and delegation-model suggestion rationale. JSON output retains the exact original values. `src/cli/export-command.ts` passes native serialized documents as individual lines so their multiline layout is preserved. `tests/cli/cli-headless-parity.test.ts` checks both suggestion paths independently from their parsed JSON output; `tests/cli/cli-export-command.test.ts` covers export framing.
+
+## Head and help navigation
+
+`src/cli/root.ts`, `src/cli/help.ts`, `src/cli/help-navigation.ts`
+
+The pure Bun-head parser retains command argv and derives transient help paths before shim preflight or command dispatch. Bare `help` is recognized only at root or immediately after the root command; nested paths use `--help`/`-h`, and exact `--` ends head help scanning. Later operand values such as `alias set demo help` stay commands. `runCli` exits help and rejects unknown roots before shim/stateful preflight, while preserving `parseCliHead` and its kinds. Registry names/aliases/hidden entries and the unregistered `internal` runner remain valid dispatch targets; hidden/internal names stay outside discovery and suggestions. `printUsage` renders the same compact index for bare `ocx`, `help`, `--help` and `-h`; static navigation groups reference registry names/summaries and add no configuration reads, width probes or color dependence. `printFullUsage` preserves the full reference behind `ocx help --all` and `ocx --help --all`. This contract concerns the Bun head; the Node launcher's updater interception has its own recognition rules.
+
+`src/cli/help-catalog.ts`, `src/cli/help-models-context.ts`, `src/cli/help-recovery.ts`
+
+Pure help resolution uses `src/cli/registry.ts` and `src/cli/capabilities.ts`, preserving exact alias usage/details before canonical family navigation. Entry results carry transient canonical identity and declared descendants; family help lists partial child coverage and links the curated models-context topic separately. Hidden entries remain explicitly callable but absent from discovery. Declared capabilities render summaries, known flags/details and parent pointers without inventing operand grammar; declared-prefix groups mark incomplete coverage. Unknown roots and unavailable explicit `ocx help <path>` detail use concise stderr-only diagnostics/navigation, empty stdout and exit 1, without a full banner. Missing detail never establishes unsupported runtime grammar. Successful appended flag-help parent fallback runs before recovery and preserves its write sink; unresolved explicit help uses stderr regardless of sink. The resolver does not validate runtime command execution. The curated models-context topic shares `MODELS_CONTEXT_USAGE` with `src/cli/models-runtime.ts`, preserving its status/value/provider/all grammar and read-only status example. The catalog projects pure transient recovery candidates from visible registry names/aliases, immediate declared children and curated topics, deduplicated by canonical destination. The pure recovery formatter bounds input/depth/work, matches conservative edit distances including adjacent transpositions and sorts by distance/name; at most three metadata-derived destinations are suggested, never executed or extended with trailing argv. Distant/control/oversized input gets no guess. Root diagnostics echo only a bounded command-shaped first token accepted by `src/lib/redact.ts`; nested diagnostics never echo arbitrary operands. `src/cli/dispatch.ts` reuses the formatter for direct unknown-root dispatch. Capability JSON preserves its existing schema and adds exact usage only for declarations that supply it; provider-specific error semantics remain unchanged. Provider syntax/examples live in registry details; `src/cli/provider.ts` uses the shared renderer for bare/help success (stdout, exit 0) and unknown-action diagnostics/help (stderr, exit 1, no stdout). The transient optional `write` sink defaults to `console.log`, accepts `console.error` for that error path and propagates through parent fallback. Bare provider retains ordinary preflight; only head-help forms bypass it.
+
+Runnable capability parents also expose their declared descendants. Nested help canonicalizes the supported access-key spellings (`api-key`, `access keys`, and key-action `delete`) while preserving exact root alias usage; recovery indexes the canonical path so prefix expansion cannot select an absent token. These are help-only mappings and never rewrite execution argv.
+
+## Pure capability data and additive usage
+
+`src/cli/capability-types.ts` owns the type-only contract. `src/cli/capabilities-base.ts` retains the original declarations. Seven domain leaves (`src/cli/capabilities-provider-models.ts`, `src/cli/capabilities-accounts.ts`, `src/cli/capabilities-agents-routing.ts`, `src/cli/capabilities-integrations.ts`, `src/cli/capabilities-observe-system.ts`, `src/cli/capabilities-access-remote.ts`, `src/cli/capabilities-lab.ts`) append verified existing workflows in a fixed order. Each leaf imports types only. The aggregate preserves baseline row identity and order; duplicate canonical paths fail validation. `src/cli/capabilities.ts` is the stable public facade for arrays, types and pure query helpers. Consumers continue to import the facade; metadata never imports command handlers, config, registry execution or Lab code. The explicit transitive boundary and cycle/forbidden-edge fixtures live in `tests/cli/cli-capability-data.test.ts`. Computed-member access, division/ambiguous-regex expressions and ambient host/loader identifiers are outside the admitted metadata grammar and fail closed, including benign shadowing or unquoted properties with reserved names. Quoted data remains supported. This is a checked dependency boundary, not an arbitrary-code sandbox.
+
+A declaration may carry `usage`, the exact synopsis for a verified leaf. `capabilityInvocation` and matching still use canonical command tokens. `src/cli/capabilities-command.ts` projects `usage` only when present, preserving the previous JSON object shape otherwise. The help renderer then uses the exact Usage line and omits that leaf's incomplete-grammar disclaimer. A declaration without usage keeps the prior Command/partial-grammar presentation. Root aliases, hidden entries, head-only invocations and the models-context special topic retain their existing semantics.
+
+## Generated operating reference
+
+`scripts/generate-ocx-skill-surface.ts` renders the compact `skills/ocx/references/01_management_surface.md` index and eight flat domain chapters from the same capability data. The index retains canonical fragment forwarders and links to complete chapter entries. Counts derive from declarations; grouping does not choose runtime dispatch or grant authority. Unknown roots and duplicate anchors are rejected rather than silently omitted.
+
+Generated flag-table cells escape literal pipes, backslashes and line breaks, and absent value types render as empty cells. Rendered Markdown regressions verify that enum choices stay in the meaning cell.
+
+The generator checks its closed expected file map and exact contents, including missing or stale owner-marked chapters. It writes expected outputs only and does not automatically delete unrelated/stale documents. `tests/ci-workflows/skill-ocx.test.ts` and the generator-focused tests check regeneration, reachable reference links, actual shipped Markdown and the preserved consent/secret-bearing command rules. Generated status grants no exemption from repository file-size limits.
+
+`skills/ocx/SKILL.md` is the operating guide, distinct from development instructions and installation consent. The index describes declared capabilities; it does not establish full runtime grammar, target-version compatibility, safe autonomous permission or free upstream execution. Handwritten task recipes provide target/readiness checks, command-level authority and read-back guidance.
+
+Management route declarations describe actual HTTP calls only; local Lab automation, config and data-plane probes retain empty management routes with explicit transport and side-effect notes. Task-family metadata preserves confirmation, human-only secret handoffs and per-handler JSON support. Leaf usage is derived from the existing parser; an indexed command does not gain new runtime behavior.
diff --git a/structure/manifest.json b/structure/manifest.json
index 48d655727f8..94e37167490 100644
--- a/structure/manifest.json
+++ b/structure/manifest.json
@@ -417,6 +417,17 @@
         "src/server/index.ts"
       ]
     },
+    {
+      "path": "cli-management.md",
+      "tier": 5,
+      "title": "CLI management and discovery",
+      "scope": "Terminal help and capability metadata, management-client output and the generated operating reference.",
+      "documents": [
+        "src/cli/",
+        "scripts/generate-ocx-skill-surface.ts",
+        "skills/ocx/"
+      ]
+    },
     {
       "path": "gui-and-management-api.md",
       "tier": 5,
diff --git a/structure/ops/docs-and-release.md b/structure/ops/docs-and-release.md
index eca9c2cedc9..578cfc77269 100644
--- a/structure/ops/docs-and-release.md
+++ b/structure/ops/docs-and-release.md
@@ -40,7 +40,7 @@ The Codex restart command follows the [CLI restart scope contract](../runtime.md
 
 The account reference documents the [Orca source-owned import](../codex-home.md#orca-source-owned-account-import).
 Its local-only command is declared in `src/cli/capabilities.ts`, and the generated skill surface
-lists its required source/registry paths and preview/apply flags.
+lists its required source/registry paths and preview/apply flags. The index and domain chapters follow the [CLI reference generation contract](../cli-management.md#generated-operating-reference).
 
 Local validation follows [the contributor test policy](../../AGENTS.md#commands): run the
 suite by default, with a documented resource exception requiring focused regression tests.
diff --git a/structure/runtime.md b/structure/runtime.md
index dec7f605844..8da04825876 100644
--- a/structure/runtime.md
+++ b/structure/runtime.md
@@ -53,7 +53,7 @@ this wire projection does not change the usage ledger.
 
 ## CLI readiness diagnostics
 
-Catalog-derived reasoning-level diagnostics are escaped only at the human-output boundary, which `src/cli/runtime-api.ts` owns alongside the human/JSON print split. Every CLI path that prints a hub-supplied catalog value renders it there: the first-time refusal in `src/cli/connect.ts` and the connected `ocx sync` refusal in `src/cli/dispatch.ts`. C0/C1 controls, DEL, and Unicode line/paragraph separators print as visible hexadecimal escapes; structured status retains the exact reason, and a rendered failure keeps the domain error as its `cause`. The ready/unverified/incompatible classification and exit policy are unchanged. `src/cli/capabilities-command.ts` rejects leftover positional arguments, unknown or repeated flags, and blank route filters with exit 64 before emitting a capability index; a valid unmatched route remains exit 4. `printData` in `src/cli/runtime-api.ts` escapes each human-output line at the shared renderer, including role and delegation-model suggestion rationale. JSON output retains the exact original values. `src/cli/export-command.ts` passes native serialized documents as individual lines so their multiline layout is preserved. `tests/cli/cli-headless-parity.test.ts` checks both suggestion paths independently from their parsed JSON output; `tests/cli/cli-export-command.test.ts` covers export framing.
+The [CLI management contract](cli-management.md#cli-readiness-diagnostics) owns terminal-safe human diagnostics, structured-output fidelity and capability argument failures.
 
 ## CLI resolve and stop contracts for embedding shells
 
@@ -124,8 +124,8 @@ does not perform OAuth, and runtime credential resolution rereads the owned sour
 | `src/lib/bun-runtime.ts` | Bundled-Bun resolution: `isRealBunBinary()` (size gate vs the ~450-byte placeholder stub), `bundledBunPath()`, and `durableBunPath()` (path baked into service/shim artifacts). Durable selection accepts only the source/path pair already stamped for the running executable; it never re-reads a project-dotenv `OPENCODEX_BUN_PATH`. |
 | `src/lib/plain-data.ts` | Detached copies for a consumer that must not observe later edits. Descriptor-based reads, including array elements, so an accessor is refused rather than invoked; refuses cycles, functions, class instances and anything else JSON could not have produced, and returns a copy-or-refusal union rather than degrading silently. Symbol-keyed process bookkeeping is skipped. |
 | `src/cli/index.ts` | `ocx` / `opencodex` CLI. Lifecycle: init, start, stop, restart, status, sync, restore/eject, gui, service, update. `restart` refuses an in-place restart requested by a CLI whose version differs from the attested `/healthz` version; a newer CLI may use the guarded standalone update path described below, because an in-place replacement respawns from the live installation; placeholder versions (unknown/0.0.0) stay incomparable and keep the restart path. Configuration: provider, account, models, combo/route, access, integrations, v2. Client launchers: Claude, OpenCode, MiniMax Code, and MiniMax CLI text. The MMX launcher owns a child-lifetime loopback path bridge from the client's hard-coded `/anthropic/v1/messages` path to the canonical `/v1/messages` data plane; the server does not expose an extra auth surface. Diagnostics: doctor, debug, observe, health. Windows adds tray. Hidden `__update-badge` prints the read-only package badge JSON without refresh or shim repair for the npm tray. The full top-level reference is rendered by `src/cli/help.ts`; this table names the groups, not every verb. After help/version and unknown-root early exits, recognized commands run the bounded best-effort Codex-shim auto-restore policy before dispatch. `status`, `doctor`, and `codex-shim status` skip shim auto-repair; `system codex-cli-update` suppresses it for its whole namespace, including malformed invocations. Keeps the `#!/usr/bin/env bun` shebang for from-source dev (`bun run src/cli/index.ts`). `src/cli/init.ts` validates an explicit setup port as a decimal integer from 1 through 65535 before publishing the initial configuration. Only an empty answer selects 10100; malformed input is reported and the port question is asked again, while EOF or SIGINT still cancels without saving. |
-| `src/cli/root.ts`, `src/cli/help.ts`, `src/cli/help-navigation.ts` | The pure Bun-head parser retains command argv and derives transient help paths before shim preflight or command dispatch. Bare `help` is recognized only at root or immediately after the root command; nested paths use `--help`/`-h`, and exact `--` ends head help scanning. Later operand values such as `alias set demo help` stay commands. `runCli` exits help and rejects unknown roots before shim/stateful preflight, while preserving `parseCliHead` and its kinds. Registry names/aliases/hidden entries and the unregistered `internal` runner remain valid dispatch targets; hidden/internal names stay outside discovery and suggestions. `printUsage` renders the same compact index for bare `ocx`, `help`, `--help` and `-h`; static navigation groups reference registry names/summaries and add no configuration reads, width probes or color dependence. `printFullUsage` preserves the full reference behind `ocx help --all` and `ocx --help --all`. This contract concerns the Bun head; the Node launcher's updater interception has its own recognition rules. |
-| `src/cli/help-catalog.ts`, `src/cli/help-models-context.ts`, `src/cli/help-recovery.ts` | Pure help resolution uses `src/cli/registry.ts` and `src/cli/capabilities.ts`, preserving exact alias usage/details before canonical family navigation. Entry results carry transient canonical identity and declared descendants; family help lists partial child coverage and links the curated models-context topic separately. Hidden entries remain explicitly callable but absent from discovery. Declared capabilities render summaries, known flags/details and parent pointers without inventing operand grammar; declared-prefix groups mark incomplete coverage. Unknown roots and unavailable explicit `ocx help <path>` detail use concise stderr-only diagnostics/navigation, empty stdout and exit 1, without a full banner. Missing detail never establishes unsupported runtime grammar. Successful appended flag-help parent fallback runs before recovery and preserves its write sink; unresolved explicit help uses stderr regardless of sink. The resolver does not validate runtime command execution. The curated models-context topic shares `MODELS_CONTEXT_USAGE` with `src/cli/models-runtime.ts`, preserving its status/value/provider/all grammar and read-only status example. The catalog projects pure transient recovery candidates from visible registry names/aliases, immediate declared children and curated topics, deduplicated by canonical destination. The pure recovery formatter bounds input/depth/work, matches conservative edit distances including adjacent transpositions and sorts by distance/name; at most three metadata-derived destinations are suggested, never executed or extended with trailing argv. Distant/control/oversized input gets no guess. Root diagnostics echo only a bounded command-shaped first token accepted by `src/lib/redact.ts`; nested diagnostics never echo arbitrary operands. `src/cli/dispatch.ts` reuses the formatter for direct unknown-root dispatch. Capability JSON and provider-specific error semantics remain unchanged. Provider syntax/examples live in registry details; `src/cli/provider.ts` uses the shared renderer for bare/help success (stdout, exit 0) and unknown-action diagnostics/help (stderr, exit 1, no stdout). The transient optional `write` sink defaults to `console.log`, accepts `console.error` for that error path and propagates through parent fallback. Bare provider retains ordinary preflight; only head-help forms bypass it. |
+| `src/cli/root.ts`, `src/cli/help.ts`, `src/cli/help-navigation.ts` | CLI head and compact/full help; see [head and help navigation](cli-management.md#head-and-help-navigation). |
+| `src/cli/help-catalog.ts`, `src/cli/help-models-context.ts`, `src/cli/help-recovery.ts` | Pure help resolution, contextual recovery and output sinks; see [head and help navigation](cli-management.md#head-and-help-navigation). |
 | `src/server/index.ts` | Bun server entrypoint: `startServer`, `/v1/responses` HTTP + WebSocket routing (compact handled before generic Responses), exact `POST /v1/images/generations` and `POST /v1/images/edits` routing, `/v1/models`, the Anthropic-shaped `/v1/messages` and OpenAI-shaped `/v1/chat/completions` compatibility surfaces, the Live/Realtime surface, the hosted-search relay, artifact serving, `/healthz`, the `/api/*` auth gate, the `/v1/*` JSON 404 guard, GUI fallback, the opt-in loopback-only hub-management listener, and facade re-exports for split server modules. The route table itself is built by `src/server/index/serve-options.ts`; this entry file owns the listener and the startup transaction. |
 | `src/server/images.ts` | Standalone Images data plane: default OpenAI or explicit custom-provider selection, Codex account affinity, bounded opaque request relay, single-attempt upstream fetch, pool health recording, and safe response/cancellation relay. |
 | `src/server/audio-transcriptions.ts` | Standalone multipart transcription; audio-specific key admission, bounded upload/response, stored OpenAI credential resolution and lease-bound cancellation. See [audio contracts](data-planes/inbound-compat.md#standalone-file-transcription). |
diff --git a/tests/ci-workflows/skill-ocx-generated.test.ts b/tests/ci-workflows/skill-ocx-generated.test.ts
new file mode 100644
index 00000000000..d727fef84d0
--- /dev/null
+++ b/tests/ci-workflows/skill-ocx-generated.test.ts
@@ -0,0 +1,282 @@
+import { describe, expect, test } from "bun:test";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { CAPABILITIES, HEAD_CAPABILITIES, capabilityInvocation } from "../../src/cli/capabilities";
+import { renderManagementSurfaces } from "../../scripts/generate-ocx-skill-surface";
+import { CAPABILITY_DATA_FILES } from "../helpers/cli-capability-data";
+import { repoPath } from "../helpers/repo-root";
+
+const INDEX = "01_management_surface.md";
+const OWNER = "GENERATED by scripts/generate-ocx-skill-surface.ts";
+// Audited navigation contract, independent of the generator's internal assignment helper.
+const GROUPS: Record<string, string[]> = {
+  lifecycle: ["chatgpt", "status", "resolve", "capabilities", "sync", "start", "stop", "restart", "service", "gui"],
+  "providers-models": ["provider", "models", "alias"], accounts: ["account", "auth", "login", "logout"],
+  "agents-routing": ["agent", "combo", "route", "v2", "effort", "memory"], integrations: ["claude", "integration", "grok", "codex-shim"],
+  "observe-system": ["companion", "usage", "logs", "storage", "inspect", "system", "observe", "debug", "export", "import", "cost", "update", "config", "tray"],
+  "access-remote": ["link", "remote-workspace", "hub", "connect", "api", "access"], lab: ["lab"],
+};
+const FILENAMES = [INDEX, ...Object.keys(GROUPS).map(domain => `01_surface_${domain}.md`)];
+const SKILL_DIR = repoPath("skills", "ocx");
+
+function headings(text: string): string[] {
+  return [...text.matchAll(/^#{1,6} (.+)$/gm)].map(match => match[1]!
+    .toLowerCase().replace(/[^\p{L}\p{N}_ -]/gu, "").replaceAll(" ", "-"));
+}
+
+function documents(directory: string): Record<string, string> {
+  const files: Record<string, string> = {};
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const file = join(directory, entry.name);
+    if (entry.isDirectory()) Object.assign(files, documents(file));
+    else if (entry.name.endsWith(".md")) files[file] = readFileSync(file, "utf8");
+  }
+  return files;
+}
+
+/** Check local Markdown links, then traverse from SKILL. Both file and fragment are required. */
+function navigationErrors(files: Record<string, string>, start: string): string[] {
+  const errors: string[] = [];
+  const edges = new Map<string, string[]>();
+  for (const [file, text] of Object.entries(files)) {
+    const targets: string[] = [];
+    for (const match of text.matchAll(/\[[^\]]+\]\(([^)\s]+)\)/g)) {
+      const href = match[1]!;
+      if (/^[a-z]+:/i.test(href)) continue;
+      const [path, fragment] = href.split("#");
+      const target = path ? resolve(dirname(file), path) : file;
+      if (files[target] === undefined) errors.push(`${file}: missing file ${href}`);
+      else if (fragment && !headings(files[target]!).includes(decodeURIComponent(fragment))) {
+        errors.push(`${file}: missing anchor ${href}`);
+      }
+      targets.push(target);
+    }
+    edges.set(file, targets);
+  }
+  const reached = new Set<string>();
+  const visit = (file: string) => {
+    if (reached.has(file)) return;
+    reached.add(file);
+    for (const next of edges.get(file) ?? []) visit(next);
+  };
+  visit(start);
+  for (const file of Object.keys(files)) if (!reached.has(file)) errors.push(`unreachable: ${file}`);
+  return errors;
+}
+
+// The generator runs unchanged in a temporary tree. No repository files or shared metadata
+// are mutated; present-usage/invalid declarations live only in a fresh subprocess instance.
+function withGenerator(run: (root: string, references: string) => void): void {
+  const root = mkdtempSync(join(tmpdir(), "ocx-skill-surface-"));
+  try {
+    const references = join(root, "skills", "ocx", "references");
+    mkdirSync(references, { recursive: true });
+    mkdirSync(join(root, "scripts"));
+    mkdirSync(join(root, "src", "cli"), { recursive: true });
+    cpSync(repoPath("scripts", "generate-ocx-skill-surface.ts"), join(root, "scripts", "generate-ocx-skill-surface.ts"));
+    for (const name of CAPABILITY_DATA_FILES) {
+      cpSync(repoPath("src", "cli", name), join(root, "src", "cli", name));
+    }
+    run(root, references);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function generate(root: string, ...args: string[]) {
+  const result = Bun.spawnSync([process.execPath, "scripts/generate-ocx-skill-surface.ts", ...args], {
+    cwd: root, stdout: "pipe", stderr: "pipe",
+  });
+  return { status: result.exitCode, stdout: result.stdout.toString(), stderr: result.stderr.toString() };
+}
+
+function renderFixture(root: string, mutation: string) {
+  const result = Bun.spawnSync([process.execPath, "-e", `
+    import { CAPABILITIES } from "./src/cli/capabilities";
+    import { renderManagementSurfaces } from "./scripts/generate-ocx-skill-surface";
+    ${mutation}
+    console.log(JSON.stringify(renderManagementSurfaces()));
+  `], { cwd: root, stdout: "pipe", stderr: "pipe" });
+  return { status: result.exitCode, stdout: result.stdout.toString(), stderr: result.stderr.toString() };
+}
+
+describe("generated operating-skill chapter contract", () => {
+  test("exactly eight chapters own all declarations once, in original order", () => {
+    const files = renderManagementSurfaces();
+    expect(Object.keys(files)).toEqual(FILENAMES);
+    expect(renderManagementSurfaces()).toEqual(files);
+    const owned: string[] = [];
+    for (const [domain, roots] of Object.entries(GROUPS)) {
+      const file = `01_surface_${domain}.md`;
+      const text = files[file]!;
+      const expected = CAPABILITIES.filter(cap => roots.includes(cap.command[0]!)).map(capabilityInvocation);
+      const actual = [...text.matchAll(/^### `?(ocx [^`\n]+)`?$/gm)].map(match => match[1]!);
+      expect(actual, file).toEqual(expected);
+      expect(text).toContain(`Declared capabilities: ${expected.length}.`);
+      expect(files[INDEX]).toContain(`| [${domain}](${file}) | ${expected.length} |`);
+      owned.push(...actual);
+    }
+    expect(owned.sort()).toEqual(CAPABILITIES.map(capabilityInvocation).sort());
+    expect(new Set(owned).size).toBe(CAPABILITIES.length);
+    const index = files[INDEX]!;
+    expect([...index.matchAll(/^### `?(ocx [^`\n]+)`?$/gm)].map(match => match[1]!))
+      .toEqual(CAPABILITIES.map(capabilityInvocation));
+    expect(index).toContain(`- declared capabilities: ${CAPABILITIES.length}`);
+    expect(index).toContain(`- of those, state-changing: ${CAPABILITIES.filter(cap => cap.mutates).length}`);
+    expect(index).toContain(`- head-resolved invocations: ${HEAD_CAPABILITIES.length}`);
+    for (const text of Object.values(files)) {
+      expect(text.split("\n").length - 1).toBeLessThan(2000);
+      expect(text.endsWith("\n")).toBe(true);
+      expect(new Set(headings(text)).size).toBe(headings(text).length);
+    }
+  });
+
+  test("shipped references are reachable and every local file+anchor link resolves", () => {
+    const files = documents(SKILL_DIR);
+    expect(navigationErrors(files, join(SKILL_DIR, "SKILL.md"))).toEqual([]);
+    for (const cap of CAPABILITIES) {
+      // Canonical CLI tokens are simple words/hyphens: old heading fragments must survive.
+      const fragment = capabilityInvocation(cap).replaceAll(" ", "-");
+      expect(headings(files[join(SKILL_DIR, "references", INDEX)]!)).toContain(fragment);
+      const domain = Object.entries(GROUPS).find(([, roots]) => roots.includes(cap.command[0]!))![0];
+      const target = `01_surface_${domain}.md#${fragment}`;
+      expect(files[join(SKILL_DIR, "references", INDEX)]).toContain(`](${target})`);
+      expect(headings(files[join(SKILL_DIR, "references", `01_surface_${domain}.md`)]!)).toContain(fragment);
+    }
+  });
+
+  test("secret-returning tasks remain prose handoffs even if usage is accidentally supplied", () => {
+    const tasks = ["ocx link issue", "ocx hub invite", "ocx config export"];
+    const files = renderManagementSurfaces();
+    for (const task of tasks) {
+      expect(CAPABILITIES.find(row => capabilityInvocation(row) === task)?.usage).toBeUndefined();
+      const owned = Object.values(files).filter(text => text.includes(`### ${task}\n`));
+      expect(owned).toHaveLength(2); // index and domain chapter; original anchor retained
+      expect(owned.some(text => text.includes("Human-only handoff:"))).toBe(true);
+      for (const text of Object.values(files)) {
+        expect(text).not.toContain("### `" + task + "`");
+        expect(text).not.toContain("Usage: `" + task);
+      }
+    }
+    withGenerator(root => {
+      const result = renderFixture(root, `
+        for (const row of CAPABILITIES) {
+          if (${JSON.stringify(tasks)}.includes("ocx " + row.command.join(" ")))
+            row.usage = "ocx " + row.command.join(" ") + " --unsafe-fixture";
+        }
+      `);
+      expect(result.status).toBe(0);
+      expect(result.stdout).not.toContain("--unsafe-fixture");
+    });
+  });
+
+  test("link proof rejects wrong files, wrong fragments and disconnected pages", () => {
+    const start = resolve("fixture", "SKILL.md");
+    const target = resolve("fixture", "chapter.md");
+    expect(navigationErrors({ [start]: "[chapter](chapter.md#ocx-account-pause)",
+      [target]: "### `ocx account pause`" }, start)).toEqual([]);
+    for (const [link, error] of [["missing.md#ocx-account-pause", "missing file"],
+      ["chapter.md#ocx-account-resume", "missing anchor"]]) {
+      expect(navigationErrors({ [start]: `[chapter](${link})`, [target]: "### `ocx account pause`" }, start).join("\n"))
+        .toContain(error!);
+    }
+    expect(navigationErrors({ [start]: "No link", [target]: "# Chapter" }, start)).toEqual([`unreachable: ${target}`]);
+  });
+
+  test("check detects missing, stale and extra owned chapters without deleting anything", () => {
+    withGenerator((root, refs) => {
+      const handwritten = join(refs, "01_surface_handwritten.md");
+      writeFileSync(handwritten, "# Unrelated handwritten reference\n");
+      let result = generate(root, "--check");
+      expect(result.status).toBe(1);
+      expect(result.stderr).toContain("01_management_surface.md is missing or STALE");
+      expect(generate(root).status).toBe(0);
+      expect(readdirSync(refs).sort()).toEqual([...FILENAMES, "01_surface_handwritten.md"].sort());
+      expect(generate(root, "--check").status).toBe(0);
+      const stale = join(refs, "01_surface_accounts.md");
+      writeFileSync(stale, "edited\n");
+      result = generate(root, "--check");
+      expect(result.status).toBe(1);
+      expect(result.stderr).toContain("01_surface_accounts.md is missing or STALE");
+      rmSync(stale);
+      expect(generate(root, "--check").status).toBe(1);
+      const extra = join(refs, "01_surface_obsolete.md");
+      const previous = `<!-- ${OWNER}. Do not edit by hand. -->\n# Obsolete\n`;
+      writeFileSync(extra, previous);
+      result = generate(root);
+      expect(result.status).toBe(0);
+      expect(result.stderr).toContain("Unexpected generated chapter: 01_surface_obsolete.md");
+      expect(readFileSync(extra, "utf8")).toBe(previous);
+      expect(readFileSync(handwritten, "utf8")).toBe("# Unrelated handwritten reference\n");
+      result = generate(root, "--check");
+      expect(result.status).toBe(1);
+      expect(result.stderr).toContain("Unexpected generated chapter: 01_surface_obsolete.md");
+      expect(result.stderr).not.toContain("missing or STALE");
+      rmSync(extra); // Fixture-owned cleanup; the generator never removes this file.
+      expect(generate(root, "--check").status).toBe(0);
+      for (const [file, text] of Object.entries(renderManagementSurfaces())) {
+        expect(readFileSync(join(refs, file), "utf8"), file).toBe(text);
+      }
+    });
+  });
+
+  test("optional usage appears beneath unchanged canonical headings only when present", () => {
+    withGenerator((root) => {
+      const baseline = renderFixture(root, "for (const row of CAPABILITIES) delete row.usage;");
+      expect(baseline.status).toBe(0);
+      const original = JSON.parse(baseline.stdout) as Record<string, string>;
+      expect(Object.values(original).join("\n")).not.toContain("Usage:");
+      const result = renderFixture(root, `
+        for (const row of CAPABILITIES) delete row.usage;
+        Object.assign(CAPABILITIES.find(cap => cap.command.join(" ") === "account pause"),
+          { usage: "ocx account pause <provider> <id> [--json]" });
+      `);
+      expect(result.status).toBe(0);
+      const rendered = JSON.parse(result.stdout) as Record<string, string>;
+      const usage = "Usage: `ocx account pause <provider> <id> [--json]`\n\n";
+      expect(rendered["01_surface_accounts.md"]).toContain("### `ocx account pause`\n\n" + usage);
+      rendered["01_surface_accounts.md"] = rendered["01_surface_accounts.md"]!.replace(usage, "");
+      expect(rendered).toEqual(original);
+    });
+  });
+
+  test("rendered flag tables retain enum choices, literal slashes and multiline meanings", () => {
+    withGenerator(root => {
+      const flags = [
+        { name: "--selection", value: "string", summary: "Choose alpha|beta|gamma." },
+        { name: "--path", value: "string", summary: "Use C:\\data\\* with left\\|right.\nNext line.\r\nFinal line." },
+        { name: "--optional", summary: "No explicit value kind." },
+      ];
+      const result = renderFixture(root, `Object.assign(CAPABILITIES.find(cap => cap.command.join(" ") === "access key list"), { flags: ${JSON.stringify(flags)} });`);
+      expect(result.status).toBe(0);
+      const files = JSON.parse(result.stdout) as Record<string, string>;
+      const markdown = files["01_surface_access-remote.md"]!.split("### `ocx access key list`\n")[1]!.split("\n### ")[0]!;
+      const html = Bun.markdown.html(markdown);
+      const rows = [...html.matchAll(/<tr>([\s\S]*?)<\/tr>/g)].map(row =>
+        [...row[1]!.matchAll(/<td>([\s\S]*?)<\/td>/g)].map(cell => cell[1]!));
+      const flagRows = rows.filter(row => row[0]?.startsWith("<code>--"));
+      expect(flagRows).toEqual([
+        ["<code>--selection</code>", "string", "Choose alpha|beta|gamma."],
+        ["<code>--path</code>", "string", "Use C:\\data\\* with left\\|right.<br>Next line.<br>Final line."],
+        ["<code>--optional</code>", "", "No explicit value kind."],
+      ]);
+    });
+  });
+
+  test("unknown roots, duplicate invocations, anchor collisions and oversize chapters fail closed", () => {
+    withGenerator((root) => {
+      for (const [mutation, message] of [
+        ['Object.assign(CAPABILITIES[0], { command: ["future-root"] });', "Unknown surface root: future-root"],
+        ['Object.assign(CAPABILITIES[1], { command: CAPABILITIES[0].command });', "Surface anchor collision"],
+        ['Object.assign(CAPABILITIES[0], { command: ["account", "a.b"] }); Object.assign(CAPABILITIES[1], { command: ["account", "ab"] });', "Surface anchor collision"],
+        ['Object.assign(CAPABILITIES[0], { details: Array(2000).fill("fixture detail") });', "Surface file must stay below 2000 lines: 01_surface_lifecycle.md"],
+        ['for (let i = 0; i < 500; i++) CAPABILITIES.push({ ...CAPABILITIES[0], command: ["account", `fixture-${i}`] });', "Surface file must stay below 2000 lines: 01_management_surface.md"],
+      ]) {
+        const result = renderFixture(root, mutation!);
+        expect(result.status).not.toBe(0);
+        expect(result.stderr).toContain(message!);
+      }
+    });
+  });
+});
diff --git a/tests/ci-workflows/skill-ocx-workflows.test.ts b/tests/ci-workflows/skill-ocx-workflows.test.ts
new file mode 100644
index 00000000000..d825290e09e
--- /dev/null
+++ b/tests/ci-workflows/skill-ocx-workflows.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { handleModelsRuntimeCommand } from "../../src/cli/models-runtime";
+import { handleRoutePolicyCommand } from "../../src/cli/route-policy";
+import type { RuntimeApiDeps } from "../../src/cli/runtime-api";
+import { repoPath } from "../helpers/repo-root";
+
+// Execute complete documented argv through real parsers, with transport replaced.
+// Fixtures are independent wire expectations, not capability metadata or prose assertions.
+// No live proxy, user credential, config write, subprocess or upstream request is used.
+const sources = [
+  "skills/ocx/references/03_recipes.md",
+  "docs-site/src/content/docs/reference/cli/providers-accounts.md",
+  "docs-site/src/content/docs/reference/cli/agents.md",
+];
+const preset = { mode: "preset", availableVersion: 3, appliedVersion: 2, presetCount: 2, totalCount: 4 };
+const profile = { id: "reliable", model: "policy/reliable", revision: "fixture-revision" };
+const arrivals = { anthropic: [{ id: "new-model", at: "2026-01-01T00:00:00Z", state: "off" }] };
+type Fixture = { prefix: string; path: string; method?: string; body?: unknown; response: unknown; output?: unknown };
+const fixtures: Fixture[] = [
+  { prefix: "ocx models preset show", path: "/api/model-presets", response: { providers: { anthropic: preset } }, output: preset },
+  { prefix: "ocx models preset apply", path: "/api/model-presets", method: "PUT", body: { provider: "anthropic", mode: "preset" }, response: { selected: ["existing"], fallback: "preset-empty" } },
+  { prefix: "ocx models selected", path: "/api/selected-models", response: { selected: { anthropic: ["existing"] }, available: { anthropic: ["existing", "new-model"] } }, output: { provider: "anthropic", selected: ["existing"], available: ["existing", "new-model"] } },
+  { prefix: "ocx models new-policy off", path: "/api/model-discovery", method: "PUT", body: { policy: "off", provider: "anthropic" }, response: { policy: "off", baselineBootstrapped: true } },
+  { prefix: "ocx models new-policy --provider", path: "/api/model-discovery", response: { policy: "on", providers: { anthropic: "off" } }, output: { provider: "anthropic", policy: "off" } },
+  { prefix: "ocx models new-arrivals", path: "/api/model-discovery", response: { recentArrivals: arrivals }, output: arrivals },
+  { prefix: "ocx route policy list", path: "/api/routing-profiles", response: { profiles: [profile] } },
+  { prefix: "ocx route policy show", path: "/api/routing-profiles", response: { profiles: [profile] }, output: profile },
+  { prefix: "ocx route policy dry-run", path: "/api/routing-profiles/dry-run", method: "POST", body: { profile: "reliable", evidence: { contextWindow: 128000, toolsRequired: true, imageInputRequired: true, structuredOutputRequired: true } }, response: { ok: true, selected: { provider: "anthropic", model: "existing" } } },
+];
+
+function documentedWorkflows(): Array<{ file: string; command: string }> {
+  return sources.flatMap(file => {
+    const markdown = readFileSync(repoPath(file), "utf8");
+    return [...markdown.matchAll(/```bash\n([\s\S]*?)```/g)].flatMap(block =>
+      block[1]!.split("\n").map(line => line.split(/\s+#/)[0]!.trim())
+        .filter(command => /^ocx (?:models (?:preset|new-policy|new-arrivals)\b|route policy\b)/.test(command)
+          || command === "ocx models selected anthropic --json")
+        .map(command => ({ file, command })),
+    );
+  });
+}
+
+async function invoke(command: string, response: unknown, status = 200) {
+  // These selected examples intentionally need no shell quoting. Never evaluate documentation.
+  const [binary, family, sub, ...args] = command.split(/\s+/);
+  expect(binary).toBe("ocx");
+  const calls: Array<{ path: string; method: string; body: unknown }> = [];
+  const output = spyOn(console, "log").mockImplementation(() => {});
+  const errors = spyOn(console, "error").mockImplementation(() => {});
+  const previousToken = process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  process.env.OPENCODEX_ADMIN_AUTH_TOKEN = "skill-workflow-fixture-no-live-authority";
+  const deps: RuntimeApiDeps = {
+    baseUrl: "http://cli-fixture.invalid",
+    fetchImpl: async (url, init) => {
+      calls.push({ path: new URL(String(url)).pathname, method: init?.method ?? "GET", body: init?.body ? JSON.parse(String(init.body)) : null });
+      return Response.json(response, { status });
+    },
+  };
+  try {
+    let code: number | null;
+    if (family === "models" && sub) code = await handleModelsRuntimeCommand(sub, args, deps);
+    else if (family === "route" && sub === "policy") code = await handleRoutePolicyCommand(args, deps);
+    else throw new Error(`Unsupported fixture family: ${family}`);
+    return { code, calls, stdout: output.mock.calls.flat().join("\n"), stderr: errors.mock.calls.flat().join("\n") };
+  } finally {
+    if (previousToken === undefined) delete process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+    else process.env.OPENCODEX_ADMIN_AUTH_TOKEN = previousToken;
+    output.mockRestore();
+    errors.mockRestore();
+  }
+}
+
+const examples = documentedWorkflows();
+describe("documented model and routing workflows", () => {
+  test("the extracted code values cover the independent handler fixtures", () => {
+    const exercised = new Set(examples.map(({ command }) => fixtures.find(f => command.startsWith(`${f.prefix} `))?.prefix));
+    expect([...exercised].sort()).toEqual(fixtures.map(f => f.prefix).sort());
+  });
+  for (const { file, command } of examples) {
+    test(`${file}: ${command}`, async () => {
+      const fixture = fixtures.find(f => command.startsWith(`${f.prefix} `));
+      if (!fixture) throw new Error(`No independent wire fixture for: ${command}`);
+      const result = await invoke(command, fixture.response);
+      expect(result.code).toBe(0);
+      expect(result.stderr).toBe("");
+      expect(result.calls).toEqual([{ path: fixture.path, method: fixture.method ?? "GET", body: fixture.body ?? null }]);
+      expect(JSON.parse(result.stdout)).toEqual(fixture.output ?? fixture.response);
+    });
+  }
+  test("bad nested operand/flag grammar is rejected before transport", async () => {
+    for (const command of [
+      "ocx models preset apply --json",
+      "ocx models new-policy off --provider --json",
+      "ocx route policy dry-run reliable --model-context-ms 128000 --json",
+    ]) {
+      const result = await invoke(command, {});
+      expect(result.code).toBe(2);
+      expect(result.calls).toEqual([]);
+      expect(result.stdout).toBe("");
+    }
+  });
+  test("JSON output requests preserve prose stderr and conflict exit semantics", async () => {
+    const result = await invoke("ocx models preset apply anthropic --json", { error: "changed", reason: "stale_revision", hint: "read back" }, 409);
+    expect(result.code).toBe(5);
+    expect(result.stdout).toBe("");
+    expect(result.stderr).toBe("Error: changed\nreason: stale_revision\nhint: read back");
+  });
+});
+
+test("routing evaluation recipes disclose enabled automation activation beside the example", () => {
+  for (const file of [sources[0]!, sources[2]!]) {
+    const text = readFileSync(repoPath(file), "utf8");
+    const example = text.indexOf("ocx route policy dry-run reliable");
+    expect(example).toBeGreaterThan(-1);
+    const adjacent = text.slice(example, example + 650);
+    expect(adjacent).toContain("authority to activate Lab");
+    expect(adjacent).toContain("upstream probes");
+  }
+});
diff --git a/tests/ci-workflows/skill-ocx.test.ts b/tests/ci-workflows/skill-ocx.test.ts
index dbd9693dcce..e04f1e6b0ed 100644
--- a/tests/ci-workflows/skill-ocx.test.ts
+++ b/tests/ci-workflows/skill-ocx.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { renderManagementSurface } from "../../scripts/generate-ocx-skill-surface";
+import { renderManagementSurface, renderManagementSurfaces } from "../../scripts/generate-ocx-skill-surface";
 import { CAPABILITIES, HEAD_CAPABILITIES, capabilityInvocation } from "../../src/cli/capabilities";
 import { CLI_COMMANDS } from "../../src/cli/registry";
 import { repoPath } from "../helpers/repo-root";
@@ -18,7 +18,7 @@ import { repoPath } from "../helpers/repo-root";
  */
 const SKILL_DIR = repoPath("skills", "ocx");
 const SKILL = join(SKILL_DIR, "SKILL.md");
-const REFERENCES = [
+const REQUIRED_REFERENCES = [
   "01_management_surface.md",
   "02_json_shapes.md",
   "03_recipes.md",
@@ -26,6 +26,16 @@ const REFERENCES = [
   "05_remote_hub.md",
 ];
 
+// Scan the shipped tree, including unlisted/stale and nested handwritten references.
+function referenceFiles(directory: string, prefix = ""): string[] {
+  return readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const relative = join(prefix, entry.name);
+    return entry.isDirectory() ? referenceFiles(join(directory, entry.name), relative)
+      : entry.name.endsWith(".md") ? [relative] : [];
+  }).sort();
+}
+const REFERENCES = referenceFiles(join(SKILL_DIR, "references"));
+
 function read(file: string): string {
   return readFileSync(join(SKILL_DIR, file), "utf8");
 }
@@ -33,7 +43,7 @@ function read(file: string): string {
 describe("skills/ocx structure", () => {
   test("SKILL.md and every reference exist", () => {
     expect(existsSync(SKILL)).toBe(true);
-    for (const ref of REFERENCES) {
+    for (const ref of REQUIRED_REFERENCES) {
       expect(existsSync(join(SKILL_DIR, "references", ref)), ref).toBe(true);
     }
   });
@@ -50,16 +60,17 @@ describe("skills/ocx structure", () => {
     }
   });
 
-  test("SKILL.md routes to every reference it ships", () => {
-    const text = readFileSync(SKILL, "utf8");
-    for (const ref of REFERENCES) expect(text, ref).toContain(ref);
-  });
+  // Transitive navigation and exact file+fragment checks live in skill-ocx-generated.test.ts.
 });
 
 describe("the generated surface reference cannot drift", () => {
   test("the committed file matches regeneration exactly", () => {
     // If this fails, run: bun scripts/generate-ocx-skill-surface.ts
-    expect(read("references/01_management_surface.md")).toBe(renderManagementSurface());
+    const files = renderManagementSurfaces();
+    expect(files["01_management_surface.md"]).toBe(renderManagementSurface());
+    for (const [file, content] of Object.entries(files)) {
+      expect(read(join("references", file)), file).toBe(content);
+    }
   });
 
   test("it names every declared capability", () => {
@@ -74,7 +85,9 @@ describe("the generated surface reference cannot drift", () => {
 
   test("it carries the do-not-edit marker", () => {
     // The marker is the only thing standing between a generated file and a hand-edited one.
-    expect(read("references/01_management_surface.md")).toContain("GENERATED by scripts/generate-ocx-skill-surface.ts");
+    for (const file of Object.keys(renderManagementSurfaces())) {
+      expect(read(join("references", file)), file).toContain("GENERATED by scripts/generate-ocx-skill-surface.ts");
+    }
   });
 });
 
diff --git a/tests/cli/cli-capabilities.test.ts b/tests/cli/cli-capabilities.test.ts
index 9c48cf65f53..6e4872f909f 100644
--- a/tests/cli/cli-capabilities.test.ts
+++ b/tests/cli/cli-capabilities.test.ts
@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { capabilityDataBoundary } from "../helpers/cli-capability-data";
 import {
   CAPABILITIES,
   HEAD_CAPABILITIES,
@@ -22,16 +21,9 @@ function captureStdout(): { lines: string[]; restore: () => void } {
   return { lines, restore: () => { console.log = original; } };
 }
 
-describe("capability table is a leaf data module", () => {
-  test("capabilities.ts imports nothing from src/cli", () => {
-    // Each command module declares `const USAGE` at top level, evaluated at import time.
-    // A cycle back into this table resolves to `undefined` under ESM instead of throwing,
-    // which would silently empty the usage text that rejectArgs hands CliUsageError --
-    // a degraded failure in the exact surface these issues are about.
-    const src = readFileSync(join(repoRoot, "src/cli/capabilities.ts"), "utf8");
-    const relative = src.match(/from\s+["']\.[^"']*["']/g) ?? [];
-    expect(relative).toEqual([]);
-    expect(/\bimport\s*\(/.test(src)).toBe(false);
+describe("capability table is a checked data graph", () => {
+  test("capability discovery has only the allowed transitive data/type edges", () => {
+    expect(capabilityDataBoundary(join(repoRoot, "src/cli"))).toEqual([]);
   });
 
   test("every capability renders a non-empty invocation and summary", () => {
@@ -150,7 +142,7 @@ describe("ocx capabilities output", () => {
     try { code = await runCapabilities(["--json", "--route", "/api/usage"]); } finally { cap.restore(); }
     expect(code).toBe(0);
     const parsed = JSON.parse(cap.lines.join("\n")) as { capabilities: { invocation: string }[] };
-    expect(parsed.capabilities.map(c => c.invocation)).toEqual(["ocx usage"]);
+    expect(parsed.capabilities.map(c => c.invocation)).toEqual(["ocx usage", "ocx observe usage"]);
   });
 
   test("an unmatched route exits non-zero instead of reporting empty success", async () => {
@@ -214,132 +206,32 @@ describe("ocx capabilities output", () => {
  * `route.exempt` needs, and the test prints the exact key to add or remove.
  */
 const UNDECLARED_ROUTES_2026_08_28: readonly string[] = [
-  "DELETE /api/codex-auth/accounts",
-  "DELETE /api/combos",
   "DELETE /api/custom-models/{id}",
-  "DELETE /api/keys",
-  "DELETE /api/oauth/accounts",
   "DELETE /api/providers",
-  "DELETE /api/providers/keys",
   "DELETE /api/routing-profiles",
-  "GET /api/aliases",
   "GET /api/claude-desktop",
-  "GET /api/claude/inbound-debug",
-  "GET /api/client-integrations",
-  "GET /api/client-integrations/journal",
-  "GET /api/client-integrations/{clientId}",
-  "GET /api/codex-auth/login-status",
   "GET /api/codex-auth/quota",
-  "GET /api/codex-auth/reset-credits",
-  "GET /api/combos",
   "GET /api/custom-models",
-  "GET /api/debug",
-  "GET /api/debug/injection-logs",
-  "GET /api/debug/logs",
-  "GET /api/debug/usage-logs",
-  "GET /api/diagnostics/project-config",
-  "GET /api/effort-caps",
-  "GET /api/grok",
-  "GET /api/keys",
-  "GET /api/model-discovery",
-  "GET /api/model-presets",
-  "GET /api/models",
-  "GET /api/native-main-profiles",
-  "GET /api/native-main-profiles/doctor",
-  "GET /api/oauth/providers",
-  "GET /api/provider-context-caps",
-  "GET /api/provider-presets",
   "GET /api/providers",
-  "GET /api/providers/keys",
   "GET /api/request-history",
   "GET /api/request-history/{id}",
-  "GET /api/request-history/{id}/route-decision",
-  "GET /api/routing-profiles",
-  "GET /api/selected-models",
-  "GET /api/settings",
-  "GET /api/shadow-call-settings",
-  "GET /api/sidecar-settings",
-  "GET /api/startup-health",
-  "GET /api/storage/codex-logs",
-  "GET /api/subagent-model-fallback",
   "GET /api/system/health",
-  "GET /api/system/memory",
   "GET /api/system/windows-replace-retries",
   "GET /api/update/badge",
-  "GET /api/update/check",
-  "GET /api/update/status",
-  "GET /api/v2",
   "PATCH /api/codex-auth/pool-strategy",
-  "PATCH /api/keys",
   "PATCH /api/oauth/accounts/pool",
-  "PATCH /api/providers",
-  "POST /api/claude-desktop/apply",
-  "POST /api/client-integrations/restore",
   "POST /api/codex-auth/accounts",
-  "POST /api/codex-auth/accounts/clear-cooldown",
-  "POST /api/codex-auth/login",
-  "POST /api/codex-auth/login/cancel",
-  "POST /api/codex-auth/login/code",
-  "POST /api/codex-auth/reset-credits/consume",
   "POST /api/custom-models",
-  "POST /api/grok/apply",
-  "POST /api/keys",
   "POST /api/model-discovery/acknowledge",
-  "POST /api/native-main-profiles/recover",
-  "POST /api/native-main-profiles/register",
-  "POST /api/native-main-profiles/stage",
-  "POST /api/native-main-profiles/stage/cancel",
-  "POST /api/native-main-profiles/stage/finish",
-  "POST /api/native-main-profiles/stage/heartbeat",
-  "POST /api/native-main-profiles/switch",
-  "POST /api/oauth/accounts/clear-cooldown",
-  "POST /api/oauth/accounts/import",
-  "POST /api/oauth/login/cancel",
-  "POST /api/oauth/login/code",
   "POST /api/oauth/logout",
   "POST /api/providers",
-  "POST /api/providers/keys",
-  "POST /api/providers/test",
-  "POST /api/routing-profiles/dry-run",
-  "POST /api/startup-action",
   "POST /api/stop",
-  "POST /api/storage/codex-logs/compact",
-  "POST /api/storage/codex-logs/protect",
-  "POST /api/storage/codex-logs/repair",
-  "POST /api/storage/codex-logs/unprotect",
-  "POST /api/sync",
   "POST /api/system/restart",
-  "POST /api/update/run",
   "POST /api/windows-tray",
   "PUT /api/claude-desktop",
-  "PUT /api/client-integrations/{clientId}",
-  "PUT /api/codex-auth/accounts/alias",
-  "PUT /api/codex-auth/accounts/priority",
-  "PUT /api/codex-auth/active",
   "PUT /api/codex-auth/failover",
-  "PUT /api/combos",
-  "PUT /api/custom-models/{id}",
-  "PUT /api/debug",
-  "PUT /api/default-aliases",
   "PUT /api/disabled-models",
-  "PUT /api/effort-caps",
-  "PUT /api/grok/selection",
-  "PUT /api/model-discovery",
-  "PUT /api/model-presets",
-  "PUT /api/model-visibility",
-  "PUT /api/oauth/accounts/active",
-  "PUT /api/oauth/accounts/alias",
-  "PUT /api/provider-context-caps",
-  "PUT /api/providers/keys/active",
-  "PUT /api/providers/keys/alias",
-  "PUT /api/providers/{provider}/alias",
-  "PUT /api/providers/{provider}/model-aliases",
   "PUT /api/routing-profiles",
-  "PUT /api/selected-models",
-  "PUT /api/settings",
-  "PUT /api/shadow-call-settings",
-  "PUT /api/sidecar-settings",
-  "PUT /api/subagent-model-fallback",
   "PUT /api/v2",
 ];
 
diff --git a/tests/cli/cli-capability-access-workflows.test.ts b/tests/cli/cli-capability-access-workflows.test.ts
new file mode 100644
index 00000000000..e166fcc462e
--- /dev/null
+++ b/tests/cli/cli-capability-access-workflows.test.ts
@@ -0,0 +1,169 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ACCESS_REMOTE_CAPABILITIES } from "../../src/cli/capabilities-access-remote";
+import { OBSERVE_SYSTEM_CAPABILITIES } from "../../src/cli/capabilities-observe-system";
+import { CAPABILITIES as BASE } from "../../src/cli/capabilities-base";
+import { handleAccessCommand } from "../../src/cli/access";
+import type { RuntimeApiDeps } from "../../src/cli/runtime-api";
+import { repoPath } from "../helpers/repo-root";
+
+const envKeys = ["HOME", "USERPROFILE", "OPENCODEX_HOME", "CODEX_HOME", "OPENCODEX_ADMIN_AUTH_TOKEN"] as const;
+let savedEnv: Array<string | undefined>;
+let home: string;
+let output: ReturnType<typeof spyOn>;
+let errors: ReturnType<typeof spyOn>;
+beforeEach(() => {
+  savedEnv = envKeys.map(key => process.env[key]);
+  home = mkdtempSync(join(tmpdir(), "ocx-capability-access-"));
+  for (const key of envKeys) process.env[key] = home;
+  delete process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  output = spyOn(console, "log").mockImplementation(() => {});
+  errors = spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  output.mockRestore(); errors.mockRestore();
+  envKeys.forEach((key, index) => {
+    const value = savedEnv[index];
+    if (value === undefined) delete process.env[key]; else process.env[key] = value;
+  });
+  rmSync(home, { recursive: true, force: true });
+});
+function capability(key: string) {
+  const value = ACCESS_REMOTE_CAPABILITIES.find(row => row.command.join(" ") === key);
+  if (!value) throw new Error(`Missing capability: ${key}`);
+  return value;
+}
+function transport(payload: unknown = {}) {
+  const requests: Array<{ path: string; method: string; body: unknown }> = [];
+  const deps: RuntimeApiDeps = {
+    baseUrl: "http://capability.invalid",
+    fetchImpl: async (input, init) => {
+      expect(new Headers(init?.headers).has("X-OpenCodex-API-Key")).toBe(false);
+      requests.push({ path: new URL(String(input)).pathname, method: init?.method ?? "GET", body: init?.body ? JSON.parse(String(init.body)) : null });
+      return Response.json(payload);
+    },
+  };
+  return { deps, requests };
+}
+
+describe("access capability workflows preserve consent and handler grammar", () => {
+  test("published key listing requires the explicit action before JSON", async () => {
+    expect(capability("access key").usage).toBe("ocx access key list [--json]");
+    const io = transport({ keys: [] });
+    expect(await handleAccessCommand(["key", "--json"], io.deps)).toBe(2);
+    expect(io.requests).toEqual([]);
+    expect(await handleAccessCommand(["key", "list", "--json"], io.deps)).toBe(0);
+    expect(io.requests).toHaveLength(1);
+  });
+  test("masked list and get use one real list endpoint, with ID/name resolution", async () => {
+    const row = { id: "fixture-id", name: "Fixture", prefix: "masked", allowedProviders: ["fixture"] };
+    const io = transport({ keys: [row] });
+    for (const key of ["access key list", "access key get"]) {
+      expect(capability(key).routes).toEqual([{ method: "GET", path: "/api/keys" }]);
+      expect(capability(key).mutates).toBe(false);
+    }
+    expect(await handleAccessCommand(["key", "list", "--json"], io.deps)).toBe(0);
+    expect(await handleAccessCommand(["key", "get", "FIXTURE", "--json"], io.deps)).toBe(0);
+    expect(JSON.parse(String(output.mock.calls[1]![0]))).toEqual(row);
+    expect(io.requests).toEqual([
+      { method: "GET", path: "/api/keys", body: null },
+      { method: "GET", path: "/api/keys", body: null },
+    ]);
+  });
+  test("scope set replaces named dimensions and preserves repeatable values", async () => {
+    const io = transport({ keys: [{ id: "fixture-id", name: "Fixture" }] });
+    const leaf = capability("access key set");
+    expect(leaf.routes).toEqual([{ method: "GET", path: "/api/keys" }, { method: "PATCH", path: "/api/keys" }]);
+    expect(leaf.flags.map(flag => flag.name)).toEqual(["--allow-provider", "--allow-model", "--clear", "--json"]);
+    expect(await handleAccessCommand(["key", "set", "Fixture", "--clear", "--allow-provider", "p1", "--allow-provider", "p2", "--json"], io.deps)).toBe(0);
+    expect(io.requests).toEqual([
+      { method: "GET", path: "/api/keys", body: null },
+      { method: "PATCH", path: "/api/keys", body: { id: "fixture-id", allowedProviders: ["p1", "p2"], allowedModels: null } },
+    ]);
+  });
+  test("ambiguous key name refuses without changing either key", async () => {
+    const io = transport({ keys: [{ id: "one", name: "same" }, { id: "two", name: "same" }] });
+    expect(capability("access key set").mutates).toBe(true);
+    expect(await handleAccessCommand(["key", "set", "same", "--allow-model", "p/model", "--json"], io.deps)).toBe(2);
+    expect(io.requests).toEqual([{ method: "GET", path: "/api/keys", body: null }]);
+  });
+  test("endpoints is a filtered envelope, models is the public data-plane catalog", async () => {
+    const io = transport({ baseUrl: "http://fixture.invalid", responsesEndpoint: "http://fixture.invalid/v1/responses", keys: [], audio: { enabled: false } });
+    expect(capability("access endpoints").json).toBe("envelope");
+    expect(await handleAccessCommand(["endpoints", "--json"], io.deps)).toBe(0);
+    expect(JSON.parse(String(output.mock.calls[0]![0]))).toEqual({ baseUrl: "http://fixture.invalid", responsesEndpoint: "http://fixture.invalid/v1/responses" });
+    expect(capability("access models").routes).toEqual([]);
+    expect(await handleAccessCommand(["models", "--json"], io.deps)).toBe(0);
+    expect(io.requests).toEqual([{ method: "GET", path: "/api/keys", body: null }, { method: "GET", path: "/v1/models", body: null }]);
+  });
+  test.each(["commit", "abort"])("rotation %s requires both IDs before transport", async operation => {
+    const leaf = capability("access key rotate " + operation);
+    expect(leaf.usage).toBe("ocx access key rotate " + operation + " <id> <rotation-id> [--json]");
+    expect(leaf.routes).toEqual([{ method: operation === "commit" ? "POST" : "DELETE", path: operation === "commit" ? "/api/keys/rotate/commit" : "/api/keys/rotate" }]);
+    const io = transport();
+    expect(await handleAccessCommand(["key", "rotate", operation, "fixture-id", "--json"], io.deps)).toBe(2);
+    expect(io.requests).toEqual([]);
+    // Source proof for destructive completion; never complete a real or fake rotation here.
+    const source = readFileSync(repoPath("src/cli/access.ts"), "utf8");
+    expect(source).toContain('body: JSON.stringify({ id, rotationId })');
+    expect(source).toContain('method: operation === "commit" ? "POST" : "DELETE"');
+  });
+  test("revocation requires explicit confirmation before transport", async () => {
+    expect(capability("access key remove").flags.find(flag => flag.name === "--yes")?.required).toBe(true);
+    const io = transport();
+    expect(await handleAccessCommand(["key", "remove", "fixture-id", "--json"], io.deps)).toBe(2);
+    expect(io.requests).toEqual([]);
+  });
+  test.each([
+    ["chat", "/v1/chat/completions", { model: "fixture/model", messages: [{ role: "user", content: "Reply with OK." }], max_tokens: 16, stream: false }],
+    ["responses", "/v1/responses", { model: "fixture/model", input: "Reply with OK.", max_output_tokens: 16 }],
+    ["messages", "/v1/messages", { model: "fixture/model", messages: [{ role: "user", content: "Reply with OK." }], max_tokens: 16 }],
+  ] as const)("inference %s uses only a fake transport and the existing body", async (protocol, path, body) => {
+    const leaf = capability("access test");
+    expect(leaf.mutates).toBe(true);
+    expect(leaf.routes).toEqual([]);
+    const io = transport({ ok: true });
+    expect(await handleAccessCommand(["test", "fixture/model", "--protocol", protocol, "--json"], io.deps)).toBe(0);
+    expect(io.requests).toEqual([{ method: "POST", path, body }]);
+  });
+  test("chosen-key, rename and future audio options are not falsely advertised", async () => {
+    const leaf = capability("access test");
+    expect(leaf.flags.map(flag => flag.name)).toEqual(["--protocol", "--json"]);
+    const io = transport();
+    expect(await handleAccessCommand(["test", "fixture/model", "--api-key-stdin"], io.deps)).toBe(2);
+    expect(io.requests).toEqual([]);
+    const keys = ACCESS_REMOTE_CAPABILITIES.map(row => row.command.join(" "));
+    expect(keys).not.toContain("access key rename");
+    expect(keys.some(key => key.startsWith("access audio"))).toBe(false);
+  });
+  test("secret-returning actions are family handoffs, never executable headings", () => {
+    const family = capability("access key");
+    expect(family.mutates).toBe(true);
+    expect(family.usage).toBe("ocx access key list [--json]");
+    for (const leaf of ACCESS_REMOTE_CAPABILITIES) {
+      const key = leaf.command.join(" ");
+      expect(key).not.toBe("access key create");
+      expect(key).not.toBe("access key rotate");
+      expect(leaf.usage).not.toMatch(/access key create|access key rotate (?:<|start)/);
+    }
+  });
+  test("new literals are unique, disjoint from baseline and import types only", () => {
+    const rows = [...OBSERVE_SYSTEM_CAPABILITIES, ...ACCESS_REMOTE_CAPABILITIES];
+    const keys = rows.map(row => row.command.join(" "));
+    expect(new Set(keys).size).toBe(keys.length);
+    const baselineKeys = new Set(BASE.map(row => row.command.join(" ")));
+    expect(keys.filter(key => baselineKeys.has(key))).toEqual([]);
+    for (const name of ["capabilities-observe-system.ts", "capabilities-access-remote.ts"]) {
+      const source = readFileSync(repoPath("src/cli", name), "utf8");
+      expect(source.match(/^import .*$/gm)).toEqual(['import type { Capability } from "./capability-types";']);
+      expect(source).not.toMatch(/import\(|require\(|process\.|Bun\./);
+    }
+    for (const leaf of rows) {
+      if (leaf.command.join(" ") === "config export") expect(leaf.usage).toBeUndefined();
+      else expect(leaf.usage?.startsWith("ocx " + leaf.command.join(" "))).toBe(true);
+      expect(leaf.flags.map(flag => flag.name)).not.toContain("--live");
+    }
+  });
+});
diff --git a/tests/cli/cli-capability-account-workflows.test.ts b/tests/cli/cli-capability-account-workflows.test.ts
new file mode 100644
index 00000000000..775d64cf7cd
--- /dev/null
+++ b/tests/cli/cli-capability-account-workflows.test.ts
@@ -0,0 +1,185 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { Readable } from "node:stream";
+import { readFileSync } from "node:fs";
+import { ACCOUNT_CAPABILITIES } from "../../src/cli/capabilities-accounts";
+import { CAPABILITIES as BASE } from "../../src/cli/capabilities-base";
+import { cmdAccount } from "../../src/cli/account";
+import { cmdNativeMainAccount } from "../../src/cli/account-main";
+import { handleAccountAuthCommand } from "../../src/cli/account-auth";
+import type { AccountDeps } from "../../src/cli/account-api";
+import type { OcxConfig } from "../../src/types";
+import { createTempHome, type TempHome } from "../helpers/temp-home";
+import { repoPath } from "../helpers/repo-root";
+
+type Captured = { method: string; path: string; body?: unknown };
+let home: TempHome;
+let previousToken: string | undefined;
+let output: ReturnType<typeof spyOn>;
+let errors: ReturnType<typeof spyOn>;
+beforeEach(() => {
+  home = createTempHome("ocx-capability-account-");
+  previousToken = process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  delete process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  output = spyOn(console, "log").mockImplementation(() => {});
+  errors = spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  output.mockRestore(); errors.mockRestore();
+  if (previousToken === undefined) delete process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  else process.env.OPENCODEX_ADMIN_AUTH_TOKEN = previousToken;
+  home.remove();
+});
+
+function fake(calls: Captured[], respond?: (call: Captured) => unknown): AccountDeps {
+  const config: OcxConfig = { port: 1, defaultProvider: "openai", providers: {
+    openai: { adapter: "openai-responses", baseUrl: "https://fixture.invalid", codexAccountMode: "pool" },
+    anthropic: { adapter: "anthropic", baseUrl: "https://fixture.invalid", authMode: "oauth" },
+    fixture: { adapter: "openai-chat", baseUrl: "https://fixture.invalid", authMode: "key" },
+  } };
+  return {
+    baseUrl: "http://127.0.0.1:1", loadConfigImpl: () => config,
+    fetchImpl: (async (input, init) => {
+      expect(new Headers(init?.headers).has("X-OpenCodex-API-Key")).toBe(false);
+      const url = new URL(String(input));
+      const call = { method: init?.method ?? "GET", path: url.pathname + url.search,
+        ...(init?.body === undefined ? {} : { body: JSON.parse(String(init.body)) }) };
+      calls.push(call);
+      if (respond) return Response.json(respond(call));
+      if (url.pathname === "/api/codex-auth/accounts") return Response.json({ accounts: [{ id: "acct-1", alias: "work" }, { id: "auto" }] });
+      if (url.pathname === "/api/codex-auth/active") return Response.json({ activeCodexAccountId: "acct-1" });
+      if (url.pathname === "/api/oauth/accounts") return Response.json({ accounts: [{ id: "oauth-1", alias: "work", active: true }], activeAccountId: "oauth-1" });
+      return Response.json({ ok: true });
+    }) as typeof fetch,
+    spawnCodexLoginImpl: () => { throw new Error("native login must never launch in discovery tests"); },
+  };
+}
+
+function capability(key: string) {
+  const row = ACCOUNT_CAPABILITIES.find(row => row.command.join(" ") === key);
+  expect(row).toBeDefined();
+  return row!;
+}
+
+describe("account discovery follows actual family-specific workflows", () => {
+  test("logout documents the existing local grammar without executing credential removal", () => {
+    const source = readFileSync(repoPath("src", "cli", "dispatch.ts"), "utf8");
+    const usage = /console\.error\(`Usage: (ocx logout <provider> \[--json\])  /.exec(source)?.[1];
+    expect(capability("logout").usage).toBe(usage);
+    expect(capability("logout").routes).toEqual([]);
+    expect(capability("logout").mutates).toBe(true);
+    expect(capability("logout").json).toBe("envelope");
+  });
+  test("new leaves do not shadow baseline and every leaf has explicit usage", () => {
+    const keys = ACCOUNT_CAPABILITIES.map(row => row.command.join(" "));
+    expect(new Set(keys).size).toBe(keys.length);
+    for (const row of ACCOUNT_CAPABILITIES) {
+      expect(BASE.some(base => base.command.join(" ") === row.command.join(" "))).toBe(false);
+      expect(row.usage?.startsWith(`ocx ${row.command.join(" ")}`)).toBe(true);
+    }
+  });
+
+  test("current reads OAuth accounts and projects an account envelope", async () => {
+    expect(capability("account current").routes).toContainEqual({ method: "GET", path: "/api/oauth/accounts" });
+    const calls: Captured[] = [];
+    expect(await cmdAccount(["current", "anthropic", "--json"], fake(calls))).toBe(0);
+    expect(calls).toEqual([{ method: "GET", path: "/api/oauth/accounts?provider=anthropic" }]);
+    expect(JSON.parse(String(output.mock.calls.at(-1)?.[0]))).toMatchObject({ provider: "anthropic", type: "oauth", activeId: "oauth-1", account: { id: "oauth-1" } });
+  });
+
+  test("a real auto ID remains selectable while clear sends null without a roster read", async () => {
+    expect(capability("account use").routes).toContainEqual({ method: "PUT", path: "/api/codex-auth/active" });
+    expect(capability("account clear").routes).toEqual([{ method: "PUT", path: "/api/codex-auth/active" }]);
+    const calls: Captured[] = [];
+    expect(await cmdAccount(["use", "openai", "auto", "--json"], fake(calls))).toBe(0);
+    expect(calls.filter(call => call.method === "PUT")).toEqual([{ method: "PUT", path: "/api/codex-auth/active", body: { accountId: "auto" } }]);
+    calls.length = 0;
+    expect(await cmdAccount(["clear", "openai", "--json"], fake(calls))).toBe(0);
+    expect(calls).toEqual([{ method: "PUT", path: "/api/codex-auth/active", body: { accountId: null } }]);
+  });
+
+  test.each([
+    { args: ["use", "anthropic", "oauth-1", "--json"], route: "/api/oauth/accounts/active", body: { provider: "anthropic", accountId: "oauth-1" } },
+    { args: ["use", "fixture", "key-1", "--json"], route: "/api/providers/keys/active", body: { name: "fixture", id: "key-1" } },
+    { args: ["alias", "fixture", "key-1", "-", "--json"], route: "/api/providers/keys/alias", body: { name: "fixture", id: "key-1", alias: "" } },
+    { args: ["alias", "anthropic", "oauth-1", "label", "--json"], route: "/api/oauth/accounts/alias", body: { provider: "anthropic", accountId: "oauth-1", alias: "label" } },
+    { args: ["alias", "openai", "work", "-", "--json"], route: "/api/codex-auth/accounts/alias", body: { id: "acct-1", alias: "" } },
+    { args: ["priority", "openai", "work", "reset", "--json"], route: "/api/codex-auth/accounts/priority", body: { id: "acct-1", priority: null } },
+  ])("$args uses the correct family body", async ({ args, route, body }) => {
+    expect(capability(`account ${args[0]}`).routes).toContainEqual({ method: "PUT", path: route });
+    const calls: Captured[] = [];
+    expect(await cmdAccount(args, fake(calls))).toBe(0);
+    expect(calls.filter(call => call.method === "PUT")).toEqual([{ method: "PUT", path: route, body }]);
+  });
+
+  test("cooldown resolves an Anthropic alias before its account-scoped write", async () => {
+    expect(capability("account clear-cooldown").routes).toContainEqual({ method: "POST", path: "/api/oauth/accounts/clear-cooldown" });
+    const calls: Captured[] = [];
+    expect(await cmdAccount(["clear-cooldown", "anthropic", "WORK", "--json"], fake(calls))).toBe(0);
+    expect(calls).toEqual([
+      { method: "GET", path: "/api/oauth/accounts?provider=anthropic" },
+      { method: "POST", path: "/api/oauth/accounts/clear-cooldown", body: { provider: "anthropic", accountId: "oauth-1" } },
+    ]);
+  });
+
+  test.each([
+    { key: "account main doctor", args: ["doctor", "--json"], route: "/api/native-main-profiles/doctor" },
+    { key: "account main list", args: ["list", "--json"], route: "/api/native-main-profiles" },
+    { key: "account main reauth status", args: ["reauth", "status", "--flow", "flow/id", "--json"], route: "/api/codex-auth/main/reauth-device?flowId=flow%2Fid" },
+  ])("$key reads its own namespace", async ({ key, args, route }) => {
+    expect(capability(key).routes).toEqual([{ method: "GET", path: route.split("?")[0] }]);
+    expect(capability(key).mutates).toBe(false);
+    const calls: Captured[] = [];
+    expect(await cmdNativeMainAccount(args, fake(calls))).toBe(0);
+    expect(calls).toEqual([{ method: "GET", path: route }]);
+  });
+
+  test("safe non-rollback recovery has its own explicit POST contract", async () => {
+    expect(capability("account main recover").mutates).toBe(true);
+    const calls: Captured[] = [];
+    expect(await cmdNativeMainAccount(["recover", "--json"], fake(calls, () => ({ recovered: false })))).toBe(0);
+    expect(calls).toEqual([{ method: "POST", path: "/api/native-main-profiles/recover", body: { rollback: false } }]);
+  });
+
+  test("reset-credit reads never consume and map main to the native ID", async () => {
+    expect(capability("account reset-credits").routes).toContainEqual({ method: "GET", path: "/api/codex-auth/reset-credits" });
+    const calls: Captured[] = [];
+    expect(await handleAccountAuthCommand("reset-credits", ["main", "--json"], fake(calls))).toBe(0);
+    expect(calls).toEqual([{ method: "GET", path: "/api/codex-auth/reset-credits?accountId=__main__" }]);
+  });
+
+  test("deletion and physical-login writes refuse unsafe grammar before any request", async () => {
+    const calls: Captured[] = [];
+    const deps = fake(calls);
+    expect(capability("account remove").flags.find(flag => flag.name === "--yes")?.required).toBe(true);
+    expect(capability("account main switch").flags.find(flag => flag.name === "--yes")?.required).toBe(true);
+    expect(capability("account main add").json).toBe("none");
+    expect(await cmdAccount(["remove", "openai", "work", "--json"], deps)).not.toBe(0);
+    expect(await cmdAccount(["remove", "openai", "main", "--yes", "--json"], deps)).not.toBe(0);
+    expect(await cmdNativeMainAccount(["switch", "profile", "--json"], deps)).not.toBe(0);
+    expect(await cmdNativeMainAccount(["recover", "--rollback", "--json"], deps)).not.toBe(0);
+    expect(await cmdNativeMainAccount(["add", "profile", "--json"], deps)).not.toBe(0);
+    expect(await cmdNativeMainAccount(["register"], deps)).not.toBe(0);
+    expect(capability("account main register").usage).toBe("ocx account main register <label> [--json]");
+    expect(calls).toEqual([]);
+  });
+
+  test("auth secrets, unsupported imports and spending stay behind safe refusal cases", async () => {
+    const calls: Captured[] = [];
+    const deps = fake(calls);
+    expect(capability("account reauth").routes).toContainEqual({ method: "POST", path: "/api/codex-auth/login" });
+    expect(await handleAccountAuthCommand("reauth", ["kiro", "--method", "builder-id", "--json"], deps)).not.toBe(0);
+    expect(await handleAccountAuthCommand("cancel", ["openai", "--json"], deps)).not.toBe(0);
+    expect(capability("account cancel").usage).toBe("ocx account cancel <provider> [--flow <flow-id>] [--json]");
+    expect(await cmdNativeMainAccount(["reauth", "cancel", "--json"], deps)).not.toBe(0);
+    expect(capability("account main reauth cancel").flags.find(flag => flag.name === "--flow")?.required).toBe(true);
+    expect(await handleAccountAuthCommand("reset-credits", ["main", "--consume", "--json"], deps)).not.toBe(0);
+    expect(capability("account import").usage).toContain("google-antigravity --format cockpit-tools");
+    expect(await cmdAccount(["import", "unsupported", "--format", "cockpit-tools", "--file", home.path("nonexistent")], deps)).not.toBe(0);
+    expect(capability("account add-key").routes).toEqual([{ method: "POST", path: "/api/providers/keys" }]);
+    const stdin = Object.assign(Readable.from([]), { isTTY: true });
+    expect(await cmdAccount(["add-key", "fixture", "--json"], { ...deps, stdinImpl: stdin })).not.toBe(0);
+    expect(capability("account code").flags.find(flag => flag.name === "--code")?.value).toBe("string");
+    expect(await handleAccountAuthCommand("code", ["openai", "--json"], { ...deps, stdinImpl: Readable.from([]) })).not.toBe(0);
+    expect(calls).toEqual([]);
+  });
+});
diff --git a/tests/cli/cli-capability-agent-workflows.test.ts b/tests/cli/cli-capability-agent-workflows.test.ts
new file mode 100644
index 00000000000..fb1b6ca9d7f
--- /dev/null
+++ b/tests/cli/cli-capability-agent-workflows.test.ts
@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AGENT_ROUTING_CAPABILITIES } from "../../src/cli/capabilities-agents-routing";
+import { handleAgentCommand } from "../../src/cli/agent";
+import { handleComboCommand } from "../../src/cli/combo";
+import { handleEffortCommand } from "../../src/cli/effort";
+import { handleRoutePolicyCommand } from "../../src/cli/route-policy";
+import { cmdV2 } from "../../src/cli/v2";
+import type { RuntimeApiDeps } from "../../src/cli/runtime-api";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+let home: string;
+let previous: Record<string, string | undefined>;
+let output: ReturnType<typeof spyOn<typeof console, "log">>;
+let errors: ReturnType<typeof spyOn<typeof console, "error">>;
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "ocx-cap-agent-"));
+  previous = { OPENCODEX_HOME: process.env.OPENCODEX_HOME, CODEX_HOME: process.env.CODEX_HOME };
+  process.env.OPENCODEX_HOME = home;
+  process.env.CODEX_HOME = join(home, "codex");
+  writeFileSync(join(home, "config.json"), JSON.stringify({ providers: {}, defaultProvider: "", port: 10100 }));
+  output = spyOn(console, "log").mockImplementation(() => {});
+  errors = spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  output.mockRestore(); errors.mockRestore();
+  for (const [key, value] of Object.entries(previous)) {
+    if (value === undefined) delete process.env[key]; else process.env[key] = value;
+  }
+  removeTreeWithRetry(home);
+});
+
+type RequestRow = { path: string; method: string; body: unknown };
+function runtime(reply: (request: RequestRow) => unknown = () => ({ ok: true })) {
+  const requests: RequestRow[] = [];
+  const deps: RuntimeApiDeps = {
+    baseUrl: "http://fixture.invalid", findLiveProxy: async () => null,
+    fetchImpl: (async (input, init) => {
+      const url = new URL(String(input));
+      const request = { path: url.pathname + url.search, method: init?.method ?? "GET", body: init?.body ? JSON.parse(String(init.body)) : null };
+      requests.push(request);
+      return Response.json(reply(request));
+    }) as typeof fetch,
+  };
+  return { requests, deps };
+}
+function leaf(key: string) {
+  const found = AGENT_ROUTING_CAPABILITIES.find(row => row.command.join(" ") === key);
+  expect(found).toBeDefined();
+  return found!;
+}
+
+describe("declared agent and routing workflows", () => {
+  test("agent status declares the six actual reads and preserves its envelope", async () => {
+    const { requests, deps } = runtime(request => ({ path: request.path }));
+    expect(leaf("agent status").json).toBe("envelope");
+    expect(await handleAgentCommand(["status", "--json"], deps)).toBe(0);
+    const paths = ["/api/v2", "/api/injection-model", "/api/effort-caps", "/api/subagent-models", "/api/subagent-model-fallback", "/api/sidecar-settings"];
+    expect(requests.map(r => r.path)).toEqual(paths);
+    expect(leaf("agent status").routes).toEqual(paths.map(path => ({ method: "GET", path })));
+    expect(JSON.parse(String(output.mock.calls[0][0])).caps).toEqual({ path: "/api/effort-caps" });
+  });
+
+  test.each([
+    { key: "agent effort set", args: ["effort", "set", "--main", "high", "--subagent", "-", "--json"], path: "/api/effort-caps", body: { effortCap: "high", subagentEffortCap: null } },
+    { key: "agent subagents set", args: ["subagents", "set", "demo/a,demo/b", "--json"], path: "/api/subagent-models", body: { models: ["demo/a", "demo/b"] } },
+    { key: "agent subagents clear", args: ["subagents", "clear", "--json"], path: "/api/subagent-models", body: { models: [] } },
+    { key: "agent fallback set", args: ["fallback", "set", "demo/b", "--poll-ms", "5000", "--json"], path: "/api/subagent-model-fallback", body: { models: ["demo/b"], pollMs: 5000 } },
+    { key: "agent fallback clear", args: ["fallback", "clear", "--json"], path: "/api/subagent-model-fallback", body: { models: [] } },
+  ])("$key drives the declared owner with explicit clear semantics", async ({ key, args, path, body }) => {
+    expect(leaf(key).routes).toEqual([{ method: "PUT", path }]);
+    expect(leaf(key).mutates).toBe(true);
+    const { requests, deps } = runtime();
+    expect(await handleAgentCommand(args, deps)).toBe(0);
+    expect(requests).toEqual([{ method: "PUT", path, body }]);
+  });
+
+  test("web sidecar candidates normalize the actual selected model before PUT", async () => {
+    const { requests, deps } = runtime(() => ({ webSearchModels: [{ value: "slot/demo", model: "demo", backend: "anthropic" }] }));
+    expect(leaf("agent sidecar web").flags.find(f => f.name === "--list")?.value).toBe("boolean");
+    expect(await handleAgentCommand(["sidecar", "web", "--model", "slot/demo", "--json"], deps)).toBe(0);
+    expect(requests).toEqual([
+      { path: "/api/sidecar-settings", method: "GET", body: null },
+      { path: "/api/sidecar-settings", method: "PUT", body: { webSearch: { model: "demo", backend: "anthropic" } } },
+    ]);
+    expect(leaf("agent sidecar web").routes).toEqual([{ method: "GET", path: "/api/sidecar-settings" }, { method: "PUT", path: "/api/sidecar-settings" }]);
+  });
+
+  test("vision list is a read and does not write settings", async () => {
+    const { requests, deps } = runtime(() => ({ visionModels: [{ value: "demo/vision", backend: "routed" }] }));
+    expect(leaf("agent sidecar vision").usage).toContain("--list");
+    expect(await handleAgentCommand(["sidecar", "vision", "--list", "--json"], deps)).toBe(0);
+    expect(requests).toEqual([{ path: "/api/sidecar-settings", method: "GET", body: null }]);
+    expect(JSON.parse(String(output.mock.calls[0][0]))).toEqual([{ value: "demo/vision", backend: "routed" }]);
+  });
+
+  test("effort set writes and reads back both live fields without changing local config", async () => {
+    const initial = readFileSync(join(home, "config.json"), "utf8");
+    const { requests, deps } = runtime(request => request.path === "/api/effort-caps"
+      ? { effortCap: "high", subagentEffortCap: "medium", efforts: ["medium", "high"] } : { effort: "minimal" });
+    expect(leaf("effort set").json).toBe("envelope");
+    expect(await handleEffortCommand(["set", "--main", "high", "--injection", "minimal", "--json"], deps)).toBe(0);
+    expect(requests).toEqual([
+      { path: "/api/effort-caps", method: "PUT", body: { effortCap: "high" } },
+      { path: "/api/injection-model", method: "PUT", body: { effort: "minimal" } },
+      { path: "/api/effort-caps", method: "GET", body: null },
+      { path: "/api/injection-model", method: "GET", body: null },
+    ]);
+    expect(readFileSync(join(home, "config.json"), "utf8")).toBe(initial);
+    expect(JSON.parse(String(output.mock.calls[0][0]))).toEqual({ ok: true, effortCap: "high", subagentEffortCap: "medium", injectionEffort: "minimal", source: "runtime" });
+  });
+
+  test("effort clear preserves injection effort in an isolated offline home", async () => {
+    writeFileSync(join(home, "config.json"), JSON.stringify({ providers: {}, effortCap: "high", subagentEffortCap: "medium", injectionEffort: "minimal" }));
+    expect(leaf("effort clear").mutates).toBe(true);
+    expect(await handleEffortCommand(["clear", "--json"], { findLiveProxy: async () => null })).toBe(0);
+    const saved = JSON.parse(readFileSync(join(home, "config.json"), "utf8"));
+    expect(saved.effortCap).toBeUndefined(); expect(saved.subagentEffortCap).toBeUndefined();
+    expect(saved.injectionEffort).toBe("minimal");
+    expect(JSON.parse(String(output.mock.calls[0][0])).source).toBe("config");
+  });
+
+  test("combo set reads the collection and sends independent target/rename fields", async () => {
+    const { requests, deps } = runtime(() => ({ combos: [] }));
+    expect(leaf("combo set").usage).toContain("--rename-from <id>");
+    expect(await handleComboCommand(["set", "new", "--targets", "demo/a:2,demo/b", "--strategy", "round-robin", "--sticky", "3", "--rename-from", "old", "--json"], deps)).toBe(0);
+    expect(requests).toEqual([
+      { path: "/api/combos", method: "GET", body: null },
+      { path: "/api/combos", method: "PUT", body: { id: "new", renameFrom: "old", combo: { strategy: "round-robin", stickyLimit: 3, targets: [{ provider: "demo", model: "a", weight: 2 }, { provider: "demo", model: "b" }] } } },
+    ]);
+    expect(leaf("combo set").routes).toEqual([{ method: "GET", path: "/api/combos" }, { method: "PUT", path: "/api/combos" }]);
+  });
+
+  test("combo remove refuses without confirmation before sending any DELETE", async () => {
+    const { requests, deps } = runtime();
+    expect(leaf("combo remove").flags.find(f => f.name === "--yes")?.required).toBe(true);
+    expect(await handleComboCommand(["remove", "fixture", "--json"], deps)).toBe(2);
+    expect(requests).toEqual([]);
+    expect(errors.mock.calls.flat().join(" ")).toContain("requires --yes");
+  });
+
+  test.each(["dry-run", "evaluate"])("route policy %s preserves exact evidence and marks possible Lab activation", async verb => {
+    const { requests, deps } = runtime(() => ({ profile: "fixture", selected: null }));
+    const capability = leaf("route policy " + verb);
+    expect(capability.mutates).toBe(true);
+    expect(capability.routes).toEqual([{ method: "POST", path: "/api/routing-profiles/dry-run" }]);
+    expect(await handleRoutePolicyCommand([verb, "fixture", "--model-context", "32000", "--tools", "--image", "--structured-output", "--json"], deps)).toBe(0);
+    expect(requests).toEqual([{ path: "/api/routing-profiles/dry-run", method: "POST", body: { profile: "fixture", evidence: { contextWindow: 32000, toolsRequired: true, imageInputRequired: true, structuredOutputRequired: true } } }]);
+  });
+
+  test("local v2 mode-hint clears through the real helper without claiming JSON or HTTP", async () => {
+    const { mkdirSync } = await import("node:fs");
+    mkdirSync(join(home, "codex"));
+    writeFileSync(join(home, "codex", "config.toml"), '[features.multi_agent_v2]\nmulti_agent_mode_hint_text = "old"\n');
+    const capability = leaf("v2 mode-hint");
+    expect(capability.routes).toEqual([]); expect(capability.json).toBe("none");
+    expect(capability.usage).toBe("ocx v2 mode-hint <text|--clear>");
+    expect(await cmdV2(["mode-hint", "--clear"])).toBe(0);
+    expect(readFileSync(join(home, "codex", "config.toml"), "utf8")).not.toContain("multi_agent_mode_hint_text");
+    expect(await cmdV2(["mode-hint", "   "])).toBe(1);
+  });
+
+  test("v2 invalid thread/mode operands refuse without invoking tools or synchronization", async () => {
+    let sideEffects = 0;
+    for (const [key, args] of [["v2 threads", ["threads", "0"]], ["v2 mode", ["mode", "invalid"]], ["v2 keep-native-v1", ["keep-native-v1", "invalid"]]] as const) {
+      expect(leaf(key).json).toBe("none"); expect(leaf(key).routes).toEqual([]);
+      expect(await cmdV2([...args], { execFile: () => { sideEffects++; }, sync: async () => { sideEffects++; } })).toBe(1);
+    }
+    expect(sideEffects).toBe(0);
+  });
+});
diff --git a/tests/cli/cli-capability-data.test.ts b/tests/cli/cli-capability-data.test.ts
new file mode 100644
index 00000000000..71f1a676f77
--- /dev/null
+++ b/tests/cli/cli-capability-data.test.ts
@@ -0,0 +1,373 @@
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import * as facade from "../../src/cli/capabilities";
+import * as base from "../../src/cli/capabilities-base";
+import { PROVIDER_MODEL_CAPABILITIES } from "../../src/cli/capabilities-provider-models";
+import { ACCOUNT_CAPABILITIES } from "../../src/cli/capabilities-accounts";
+import { AGENT_ROUTING_CAPABILITIES } from "../../src/cli/capabilities-agents-routing";
+import { INTEGRATION_CAPABILITIES } from "../../src/cli/capabilities-integrations";
+import { OBSERVE_SYSTEM_CAPABILITIES } from "../../src/cli/capabilities-observe-system";
+import { ACCESS_REMOTE_CAPABILITIES } from "../../src/cli/capabilities-access-remote";
+import { LAB_CAPABILITIES } from "../../src/cli/capabilities-lab";
+import { CAPABILITY_DATA_FILES, capabilityDataBoundary } from "../helpers/cli-capability-data";
+import { repoPath, repoRoot } from "../helpers/repo-root";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { SPAWN_BUDGET_MS } from "../helpers/test-budget";
+
+const validFiles: Record<string, string> = {
+  "capabilities.ts": `import { CAPABILITIES } from './capabilities-base';
+    import type { Capability } from './capability-types';
+    export { CAPABILITIES } from './capabilities-base';
+    export type { Capability } from './capability-types';`,
+  "capabilities-base.ts": `import type { Capability } from './capability-types';
+    export const CAPABILITIES: readonly Capability[] = [];`,
+  "capability-types.ts": `export interface Capability { readonly summary: string; }
+    export type Mode = 'payload' | 'none';`,
+};
+
+function checkFixture(changes: Record<string, string | undefined> = {}): string[] {
+  const leaves = Object.fromEntries(CAPABILITY_DATA_FILES.filter(name => !(name in validFiles))
+    .map(name => [name, `import type { Capability } from "./capability-types"; export const ROWS: readonly Capability[] = [];`]));
+  const files = { ...leaves, ...validFiles, ...changes };
+  const directory = resolve("capability-graph-fixture");
+  return capabilityDataBoundary(directory, path => {
+    const source = files[basename(path)];
+    if (source === undefined) throw new Error(`missing module ${path}`);
+    return source;
+  });
+}
+
+describe("checked capability dependency boundary", () => {
+  test("real graph and static type/value fixtures use the same predicate", () => {
+    expect(capabilityDataBoundary(repoPath("src", "cli"))).toEqual([]);
+    expect(checkFixture()).toEqual([]);
+    expect(checkFixture({
+      "capabilities-base.ts": `import { type Capability as Row } from './capability-types.ts';
+        export const CAPABILITIES: readonly Row[] = [];`,
+    })).toEqual([]);
+  });
+
+  test("comments, strings, templates and regex lookalikes are not dependencies", () => {
+    expect(checkFixture({ "capabilities-base.ts": validFiles["capabilities-base.ts"] + `
+      // import { handler } from './capabilities-command'; require('bad');
+      /* export * from '../config'; import('bad'); */
+      const text = "import('bad'); require('bad');";
+      const template = \`export * from '../lab'; import('bad')\`;
+      const pattern = /require\('bad'\)/;
+      const names = ["require", "import"];
+      const quoted = 'module[\`require\`]("node:path"); {} as any / import("node:path") / 1';
+      const templates = [\`require\`, \`module["require"]("node:path")\`];
+      const nested = { values: [["require"], ["import"]] };
+      const regexImport = /import\\("node:path"\\)/;
+      // module[\`require\`]("node:path"); {} as any / import("node:path") / 1
+
+    ` })).toEqual([]);
+  });
+
+  for (const [name, source] of Object.entries({
+    handler: `import { runCapabilities } from './capabilities-command';`,
+    config: `import { loadConfig } from '../config';`,
+    lab: `export { activate } from '../lab/index';`,
+    "type-only outside dependency": `import type { Settings } from '../config';`,
+    "side-effect import": `import '../config';`,
+    "side-effect allowed filename": `import './capability-types';`,
+    "bare import": `import { readFile } from 'node:fs';`,
+    "bare type import": `import type { Stats } from 'node:fs';`,
+    "default import": `import data from './capabilities-base';`,
+    "namespace import": `import * as data from './capabilities-base';`,
+    "type re-export outside": `export type { Settings } from '../config';`,
+    "bare re-export": `export { readFile } from 'node:fs';`,
+    "star re-export": `export * from './capability-types';`,
+    "type star re-export": `export type * from './capability-types';`,
+    "unresolved file": `import { data } from './missing';`,
+    "computed specifier": `import { data } from ('./capability-types');`,
+    "dynamic literal": `import('./capability-types');`,
+    "dynamic computed": `import('./capability-' + name);`,
+    "type import query": `type Row = import('./capability-types').Capability;`,
+    require: `require('./capability-types');`,
+    "F1 R2 quoted destructuring loader": 'const { "require": load } = module; load("node:path");',
+    "F1 template computed require": 'module[`require`]("node:path");',
+    "F1 division hidden import": 'const ratio = {} as any / Number(import("node:path")) / 1;',
+    "computed require": `module['require']('./capability-types');`,
+    "aliased require": `const load = require; load('./capability-types');`,
+    "import meta load": `import.meta.require('./capability-types');`,
+    "template expression load": 'const text = `ignored ${import("../config")}`;',
+    "value edge into types": `import { Capability } from './capability-types';`,
+    "base re-export": `export type { Capability } from './capability-types';`,
+    "malformed source": `export const data = [`,
+  })) {
+    test(`refuses ${name} reached transitively through base`, () => {
+      expect(checkFixture({ "capabilities-base.ts": validFiles["capabilities-base.ts"] + source }).length).toBeGreaterThan(0);
+    });
+  }
+
+  test("computed-member variants are outside the metadata grammar regardless of key spelling", () => {
+    for (const expression of [
+      'module[`requ\\u0069re`]("node:path")',
+      'module[`req${"uire"}`]("node:path")',
+      'module["req" + "uire"]("node:path")',
+      '(module)[`require`]("node:path")',
+      'module?.[`require`]("node:path")',
+      'module![`require`]("node:path")',
+      'const load = module[`require`]; load("node:path")',
+      'const key = "require"; module[key]("node:path")',
+      // A benign computed lookup is refused honestly as unsupported too.
+      'const first = rows[0]',
+    ]) {
+      expect(checkFixture({ "capabilities-base.ts": validFiles["capabilities-base.ts"] + expression + ";" })
+        .join("\n")).toContain("unsupported metadata expression: computed member or bracket position");
+    }
+  });
+
+  test("division and ambiguous regex tokens cannot hide literal or computed loads", () => {
+    for (const expression of [
+      'const ratio = {} as any / Number(import("node:path")) / 1;',
+      'const ratio = {} as unknown / Number(import(name)) / 1;',
+      'const ratio = {} as never / Number(module[`require`]("node:path")) / 1;',
+      'const ratio = 10 / Number(import("node:path")) / 1;',
+      'let ratio = 10; ratio /= Number(import(name));',
+      // These have no dependency; unsupported does not mean an actual load.
+      'const ratio = 10 / 2;',
+      'const pattern = true ? /harmless/ : /also-harmless/;',
+    ]) {
+      expect(checkFixture({ "capabilities-base.ts": validFiles["capabilities-base.ts"] + expression })
+        .join("\n")).toContain("unsupported metadata expression: division or ambiguous regex position");
+    }
+  });
+
+  test("host references are refused before nested, aliased or reassigned loaders escape", () => {
+    for (const [source, host] of [
+      ['const { "require": load } = module; load("node:path");', "module"],
+      ['const host = module; const { "require": load } = host; load("node:path");', "module"],
+      ['const { "host": { "require": load } } = { "host": module }; load("node:path");', "module"],
+      ['let load; ({ "require": load } = module); load("node:path");', "module"],
+      ['const { "require": load } = globalThis; load("node:path");', "globalThis"],
+      ['const { "module": { "require": load } } = global; load("node:path");', "global"],
+      ['const { "mainModule": { "require": load } } = process; load("node:path");', "process"],
+      ['const { "require": load } = this; load("node:path");', "this"],
+      ['(({ "require": load }) => load("node:path"))(module);', "module"],
+      [String.raw`const { "requ\u0069re": load } = modu\u006ce; load("node:path");`, "module"],
+      [String.raw`const { "require": load } = glo\u{62}alThis; load("node:path");`, "globalThis"],
+      [String.raw`const load = requ\u{69}re; load("node:path");`, "require"],
+    ]) {
+      expect(checkFixture({ "capabilities-base.ts": validFiles["capabilities-base.ts"] + source })
+        .join("\n")).toContain(`unsupported metadata host/loader identifier: ${host}`);
+    }
+  });
+
+  test("reserved host vocabulary rejects even benign references and local shadowing", () => {
+    for (const host of ["require", "module", "exports", "global", "globalThis", "Bun", "process", "Deno", "window", "self", "this"]) {
+      expect(checkFixture({ "capabilities-base.ts": validFiles["capabilities-base.ts"] + `const host = ${host};` })
+        .join("\n")).toContain(`unsupported metadata host/loader identifier: ${host}`);
+    }
+    for (const source of [
+      'const module = "harmless";',
+      'function copy(module: string) { return module; }',
+      'const data = { module: "harmless" };',
+      'type module = string;',
+    ]) {
+      expect(checkFixture({ "capabilities-base.ts": validFiles["capabilities-base.ts"] + source })
+        .join("\n")).toContain("unsupported metadata host/loader identifier: module");
+    }
+  });
+
+  test("quoted host/loader properties and inert spellings remain data", () => {
+    expect(checkFixture({ "capabilities-base.ts": validFiles["capabilities-base.ts"] + String.raw`
+      const data = {
+        "require": "display text", "module": { "require": "still data" },
+        "globalThis": "label", "global": "label", "Bun": "label", "process": "label",
+        "Deno": "label", "window": "label", "self": "label", "exports": "label", "this": "label",
+        "requ\u0069re": "escaped property", "modu\u006ce": "escaped property"
+      };
+      const { "require": text } = data;
+      const { "module": { "require": nestedText } } = data;
+      const quoted = "const host = modu\u006ce; globalThis; require";
+      const pattern = /module|globalThis|require|Bun|process/;
+      // module globalThis require; const { "require": load } = module;
+      /* modu\u006ce glo\u{62}alThis requ\u0069re */
+    ` })).toEqual([]);
+  });
+
+  test("does not confuse a mixed type/value clause with a type-only edge", () => {
+    expect(checkFixture({ "capabilities-base.ts": `import { type Capability, value } from './capability-types';` })
+      .join("\n")).toContain("forbidden edge import:value:capability-types.ts");
+  });
+
+  test("cycles, including type-only cycles, are reported", () => {
+    for (const prefix of ["", "type "]) {
+      expect(checkFixture({ "capabilities-base.ts": `import ${prefix}{ CAPABILITIES } from './capabilities';` })
+        .join("\n")).toContain("cycle: capabilities.ts");
+    }
+  });
+
+  test("missing allowlisted files fail closed", () => {
+    expect(checkFixture({ "capability-types.ts": undefined }).join("\n")).toContain("missing module");
+  });
+
+  test("types cannot gain dependencies or runtime initializers", () => {
+    for (const source of [
+      `import type { Capability } from './capabilities';`,
+      `export const state = 1;`,
+      `export enum State { Active }`,
+    ]) expect(checkFixture({ "capability-types.ts": source }).length).toBeGreaterThan(0);
+  });
+});
+
+const completeUsage = "ocx models set-price <provider/model> (--auto | --input <rate> --output <rate>) [--cache-read <rate>] [--cache-write <rate>] [--json]";
+const warning = "Capability metadata is incomplete; this is not the full operand grammar.";
+
+type Discovery = {
+  all: { schemaVersion: number; capabilities: Record<string, unknown>[]; headCapabilities: unknown[] };
+  filtered: { capabilities: Record<string, unknown>[]; headCapabilities?: unknown[] };
+  help: string;
+  alias: string;
+  legacy: string;
+  parent: string;
+  fallback: string;
+  invocation: string;
+  human: string;
+};
+
+function discovery(mode: "absent" | "present" | "undefined" | "empty"): Discovery {
+  const home = mkdtempSync(join(tmpdir(), "ocx-capability-data-"));
+  const codex = join(home, "codex");
+  const ocx = join(home, "ocx");
+  mkdirSync(codex);
+  mkdirSync(ocx);
+  // Only this child mutates a real row. No synthetic shipped command, shared global
+  // mutation, production injection seam, proxy, credentials or upstream are involved.
+  const script = `
+    globalThis.fetch = () => { throw new Error('discovery attempted HTTP'); };
+    const { CAPABILITIES, capabilityInvocation } = await import(${JSON.stringify(repoPath("src/cli/capabilities.ts"))});
+    for (const row of CAPABILITIES) delete row.usage;
+    const target = CAPABILITIES.find(cap => cap.command.join(' ') === 'models set-price');
+    if (!target) throw new Error('missing fixture leaf');
+    const mode = ${JSON.stringify(mode)};
+    if (mode !== 'absent') Object.defineProperty(target, 'usage', {
+      value: mode === 'undefined' ? undefined : mode === 'empty' ? '' : ${JSON.stringify(completeUsage)},
+      enumerable: true,
+    });
+    const { runCapabilities } = await import(${JSON.stringify(repoPath("src/cli/capabilities-command.ts"))});
+    const { printSubcommandUsage } = await import(${JSON.stringify(repoPath("src/cli/help.ts"))});
+    async function output(args) {
+      const lines = [];
+      const original = console.log;
+      console.log = text => lines.push(text);
+      try {
+        if (await runCapabilities(args) !== 0) throw new Error('capabilities failed');
+        return lines.join('\\n');
+      } finally { console.log = original; }
+    }
+    function help(path, fallbackToParent = false) {
+      const lines = [];
+      printSubcommandUsage(path[0], path, { write: line => lines.push(line), fallbackToParent });
+      return lines.join('\\n');
+    }
+    console.log(JSON.stringify({
+      all: JSON.parse(await output(['--json'])),
+      filtered: JSON.parse(await output(['--json', '--route', '/api/providers/{provider}/model-costs', '--mutating-only'])),
+      human: await output(['--route', '/api/providers/{provider}/model-costs', '--mutating-only']),
+      help: help(['models', 'set-price']), alias: help(['model', 'set-price']),
+      legacy: help(['models', 'price']), parent: help(['models']),
+      fallback: help(['model', 'set-price', 'example/model'], true),
+      invocation: capabilityInvocation(target),
+    }));`;
+  try {
+    const result = spawnSync(process.execPath, ["-e", script], {
+      cwd: repoRoot(), encoding: "utf8", timeout: SPAWN_BUDGET_MS - 5_000,
+      env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot,
+        HOME: home, USERPROFILE: home, CODEX_HOME: codex, OPENCODEX_HOME: ocx,
+        TMPDIR: home, TMP: home, TEMP: home },
+    });
+    expect(result.error).toBeUndefined();
+    expect(result.signal).toBeNull();
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(readdirSync(codex)).toEqual([]);
+    expect(readdirSync(ocx)).toEqual([]);
+    return JSON.parse(result.stdout) as Discovery;
+  } finally {
+    removeTreeWithRetry(home);
+    expect(existsSync(home)).toBe(false);
+  }
+}
+
+describe("capability facade and optional usage consumers", () => {
+  test("public runtime exports and base array/row identities remain stable", () => {
+    expect(Object.keys(facade).sort()).toEqual([
+      "CAPABILITIES", "HEAD_CAPABILITIES", "capabilitiesForRoute", "capabilityInvocation", "capabilityRouteKeys",
+    ].sort());
+    expect(facade.CAPABILITIES.slice(0, base.CAPABILITIES.length)).toEqual(base.CAPABILITIES);
+    base.CAPABILITIES.forEach((row, index) => expect(facade.CAPABILITIES[index]).toBe(row));
+    expect(new Set(facade.CAPABILITIES.map(row => row.command.join(" "))).size).toBe(facade.CAPABILITIES.length);
+    expect(facade.CAPABILITIES.slice(base.CAPABILITIES.length)).toEqual([
+      ...PROVIDER_MODEL_CAPABILITIES,
+      ...ACCOUNT_CAPABILITIES,
+      ...AGENT_ROUTING_CAPABILITIES,
+      ...INTEGRATION_CAPABILITIES,
+      ...OBSERVE_SYSTEM_CAPABILITIES,
+      ...ACCESS_REMOTE_CAPABILITIES,
+      ...LAB_CAPABILITIES,
+    ]);
+    expect(facade.HEAD_CAPABILITIES).toBe(base.HEAD_CAPABILITIES);
+    const matches = facade.capabilitiesForRoute("/api/providers/{provider}/model-costs");
+    expect(matches.map(facade.capabilityInvocation)).toEqual(["ocx models price", "ocx models set-price"]);
+    for (const row of matches) expect(base.CAPABILITIES.includes(row)).toBe(true);
+    expect(facade.capabilityRouteKeys().has("PUT /api/providers/{provider}/model-costs")).toBe(true);
+    expect(facade.CAPABILITIES.some(row => Object.hasOwn(row, "usage"))).toBe(true);
+  });
+
+  test("absent usage preserves exact legacy JSON shape, help and alias output", () => {
+    const result = discovery("absent");
+    expect(result.all.schemaVersion).toBe(1);
+    expect(result.all.headCapabilities).toEqual(base.HEAD_CAPABILITIES);
+    expect(result.all.capabilities).toEqual(facade.CAPABILITIES.map(cap => ({
+      command: cap.command, invocation: `ocx ${cap.command.join(" ")}`, summary: cap.summary,
+      routes: cap.routes, flags: cap.flags, mutates: cap.mutates, json: cap.json,
+      ...(cap.details ? { details: cap.details } : {}),
+    })));
+    expect(result.legacy).toBe([
+      "Command: ocx models price\n\nRead the saved manual price for an exact provider/model selector.",
+      "\nDeclared flags:",
+      "  --json  Emit provider, modelId, and cost (null for automatic pricing).",
+      "\nThe provider must be configured; everything after the first slash is the exact upstream model ID.",
+      `\n${warning}`, "\nParent help: ocx help models",
+    ].join("\n"));
+    expect(result.help).toStartWith("Command: ocx models set-price\n\n");
+    expect(result.help).toContain(warning);
+    expect(result.alias).toBe(result.help);
+  }, SPAWN_BUDGET_MS);
+
+  test("present usage reaches real full/filtered JSON and leaf/alias/fallback help only", () => {
+    const before = discovery("absent");
+    const after = discovery("present");
+    const target = after.all.capabilities.find(cap => cap.invocation === "ocx models set-price");
+    expect(target?.usage).toBe(completeUsage);
+    expect(after.filtered.capabilities).toEqual([target!]);
+    expect(after.filtered).not.toHaveProperty("headCapabilities");
+    expect(after.all.capabilities.filter(cap => Object.hasOwn(cap, "usage"))).toHaveLength(1);
+    expect(after.all.capabilities.map(({ usage: _usage, ...cap }) => cap)).toEqual(before.all.capabilities);
+    expect(after.help).toBe(before.help
+      .replace("Command: ocx models set-price", `Usage: ${completeUsage}`)
+      .replace(`\n\n${warning}`, ""));
+    expect(after.alias).toBe(after.help);
+    expect(after.fallback).toBe(after.help);
+    expect(after.legacy).toBe(before.legacy);
+    expect(after.parent).toBe(before.parent);
+    expect(after.human).toBe(before.human);
+    expect(after.invocation).toBe("ocx models set-price");
+  }, SPAWN_BUDGET_MS);
+
+  test("undefined remains absent while a defined empty string follows the defined-value contract", () => {
+    const absent = discovery("absent");
+    expect(discovery("undefined")).toEqual(absent);
+    const empty = discovery("empty");
+    expect(empty.filtered.capabilities[0].usage).toBe("");
+    expect(empty.help).toStartWith("Usage: \n\n");
+    expect(empty.help).not.toContain(warning);
+    expect(empty.alias).toBe(empty.help);
+  }, SPAWN_BUDGET_MS);
+});
diff --git a/tests/cli/cli-capability-integration-workflows.test.ts b/tests/cli/cli-capability-integration-workflows.test.ts
new file mode 100644
index 00000000000..ac8981fdf8e
--- /dev/null
+++ b/tests/cli/cli-capability-integration-workflows.test.ts
@@ -0,0 +1,148 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { INTEGRATION_CAPABILITIES } from "../../src/cli/capabilities-integrations";
+import { handleClientIntegrationCommand, handleClaudeConfigCommand, handleGrokCommand } from "../../src/cli/integrations";
+import { handleClaudeDesktopCommand } from "../../src/cli/claude-desktop";
+import type { RuntimeApiDeps } from "../../src/cli/runtime-api";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { repoPath } from "../helpers/repo-root";
+
+let home: string;
+let previous: Record<string, string | undefined>;
+let output: ReturnType<typeof spyOn<typeof console, "log">>;
+let errors: ReturnType<typeof spyOn<typeof console, "error">>;
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "ocx-cap-integration-"));
+  previous = { OPENCODEX_HOME: process.env.OPENCODEX_HOME, CODEX_HOME: process.env.CODEX_HOME };
+  process.env.OPENCODEX_HOME = home;
+  process.env.CODEX_HOME = join(home, "codex");
+  writeFileSync(join(home, "config.json"), JSON.stringify({ providers: {}, defaultProvider: "", port: 10100 }));
+  output = spyOn(console, "log").mockImplementation(() => {});
+  errors = spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  output.mockRestore(); errors.mockRestore();
+  for (const [key, value] of Object.entries(previous)) {
+    if (value === undefined) delete process.env[key]; else process.env[key] = value;
+  }
+  removeTreeWithRetry(home);
+});
+type Recorded = { path: string; method: string; body: unknown };
+function runtime(response: unknown = { ok: true }, status = 200) {
+  const requests: Recorded[] = [];
+  const deps: RuntimeApiDeps = { baseUrl: "http://fixture.invalid", findLiveProxy: async () => null,
+    fetchImpl: (async (input, init) => {
+      const url = new URL(String(input));
+      requests.push({ path: url.pathname + url.search, method: init?.method ?? "GET", body: init?.body ? JSON.parse(String(init.body)) : null });
+      return Response.json(response, { status });
+    }) as typeof fetch,
+  };
+  return { requests, deps };
+}
+function leaf(key: string) {
+  const capability = INTEGRATION_CAPABILITIES.find(row => row.command.join(" ") === key);
+  expect(capability).toBeDefined(); return capability!;
+}
+
+describe("declared integration workflows", () => {
+  test.each([
+    { args: ["status", "--json"], path: "/api/client-integrations" },
+    { args: ["status", "--client", "droid", "--json"], path: "/api/client-integrations/droid" },
+    { args: ["status", "--client", "aside", "--json"], path: "/api/client-integrations/aside/profiles" },
+    { args: ["status", "--client", "aside", "--profile", "2", "--json"], path: "/api/client-integrations/aside/profiles/2" },
+  ])("client read selects $path", async ({ args, path }) => {
+    expect(leaf("integration client status").mutates).toBe(false);
+    const { requests, deps } = runtime({ clients: [] });
+    expect(await handleClientIntegrationCommand(args, deps)).toBe(0);
+    expect(requests).toEqual([{ path, method: "GET", body: null }]);
+    expect(JSON.parse(String(output.mock.calls[0][0]))).toEqual({ clients: [] });
+  });
+
+  test("ordinary client metadata includes its real template, not only Aside", () => {
+    expect(leaf("integration client status").routes).toContainEqual({ method: "GET", path: "/api/client-integrations/{clientId}" });
+    expect(leaf("integration client enable").routes).toContainEqual({ method: "PUT", path: "/api/client-integrations/{clientId}" });
+  });
+
+  test("explicit enable conflict waiver reaches only the selected Aside profile", async () => {
+    const { requests, deps } = runtime({ ok: true, profileId: "2", state: "current" });
+    expect(leaf("integration client enable").flags.find(f => f.name === "--overwrite-conflict")?.value).toBe("boolean");
+    expect(await handleClientIntegrationCommand(["enable", "--client", "aside", "--profile", "2", "--overwrite-conflict", "--json"], deps)).toBe(0);
+    expect(requests).toEqual([{ path: "/api/client-integrations/aside/profiles/2", method: "PUT", body: { enabled: true, overwriteConflict: true } }]);
+  });
+
+  test("disable rejects an overwrite waiver without writing", async () => {
+    const { requests, deps } = runtime();
+    expect(leaf("integration client disable").flags.some(f => f.name === "--overwrite-conflict")).toBe(false);
+    expect(await handleClientIntegrationCommand(["disable", "--client", "droid", "--overwrite-conflict", "--json"], deps)).toBe(2);
+    expect(requests).toEqual([]);
+  });
+
+  test("history uses the ordinary journal filter and returns expired snapshots", async () => {
+    const payload = { operations: [{ opId: "fixture", snapshot: "expired" }] };
+    const { requests, deps } = runtime(payload);
+    expect(leaf("integration client history").routes).toContainEqual({ method: "GET", path: "/api/client-integrations/journal" });
+    expect(await handleClientIntegrationCommand(["history", "--client", "droid", "--json"], deps)).toBe(0);
+    expect(requests).toEqual([{ path: "/api/client-integrations/journal?client=droid", method: "GET", body: null }]);
+    expect(JSON.parse(String(output.mock.calls[0][0]))).toEqual(payload);
+  });
+
+  test("restore keeps a server drift refusal and never auto-confirms or retries", async () => {
+    const { requests, deps } = runtime({ error: "config_drift", hint: "Explicit drift confirmation required" }, 409);
+    expect(leaf("integration client restore").routes).toContainEqual({ method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/restore" });
+    expect(await handleClientIntegrationCommand(["restore", "--op", "fixture", "--client", "aside", "--profile", "2", "--json"], deps)).toBe(5);
+    expect(requests).toEqual([{ path: "/api/client-integrations/aside/profiles/2/restore", method: "POST", body: { opId: "fixture", confirmDrift: false } }]);
+    expect(output.mock.calls).toHaveLength(0);
+    expect(errors.mock.calls.flat().join(" ")).toContain("config_drift");
+  });
+
+  test("first-party Claude settings remain an isolated write with warnings intact", async () => {
+    const result = { ok: true, warnings: ["shared_proxy_retained"] };
+    const { requests, deps } = runtime(result);
+    expect(leaf("claude config set").flags.find(f => f.name === "--first-party")?.value).toBe("string");
+    expect(await handleClaudeConfigCommand(["set", "--first-party", "off", "--json"], deps)).toBe(0);
+    expect(requests).toEqual([{ path: "/api/claude-code", method: "PUT", body: { cliFirstParty: false } }]);
+    expect(JSON.parse(String(output.mock.calls[0][0]))).toEqual(result);
+    expect(await handleClaudeConfigCommand(["set", "--first-party", "on", "--enabled", "on", "--json"], deps)).toBe(2);
+    expect(requests).toHaveLength(1);
+  });
+
+  test("Grok include reads existing exclusions; apply returns its skipped receipt", async () => {
+    const { requests, deps } = runtime({ excluded: ["keep", "include-me"] });
+    expect(leaf("grok include").routes).toEqual([{ method: "GET", path: "/api/grok" }, { method: "PUT", path: "/api/grok/selection" }]);
+    expect(await handleGrokCommand(["include", "include-me", "--json"], deps)).toBe(0);
+    expect(requests).toEqual([{ path: "/api/grok", method: "GET", body: null }, { path: "/api/grok/selection", method: "PUT", body: { excluded: ["keep"] } }]);
+    const skipped = { ok: true, changed: false, skippedReason: "disabled" };
+    const apply = runtime(skipped);
+    expect(leaf("grok apply").routes).toEqual([{ method: "POST", path: "/api/grok/apply" }]);
+    expect(await handleGrokCommand(["apply", "--json"], apply.deps)).toBe(0);
+    expect(apply.requests).toEqual([{ path: "/api/grok/apply", method: "POST", body: null }]);
+    expect(JSON.parse(String(output.mock.calls.at(-1)![0]))).toEqual(skipped);
+  });
+
+  test("Desktop apply rejects incompatible mode flags before any apply dependency", async () => {
+    let calls = 0;
+    expect(leaf("claude desktop apply").json).toBe("none");
+    expect(await handleClaudeDesktopCommand(["apply", "--first-party", "--gateway"], {
+      findLiveProxyImpl: async () => { calls++; return null; },
+      postApplyImpl: async () => { calls++; return { ok: true }; },
+    })).toBe(2);
+    expect(calls).toBe(0);
+  });
+
+  test("Desktop local profile writers and export declare no fictitious HTTP or JSON flag", async () => {
+    // Source proof avoids invoking catalog discovery, file overwrites, or trust operations.
+    const source = await Bun.file(repoPath("src", "cli", "claude-desktop.ts")).text();
+    for (const verb of ["move", "default", "export"]) {
+      const declaration = leaf("claude desktop " + verb);
+      expect(declaration.routes).toEqual([]); expect(declaration.json).toBe("none");
+      const start = source.indexOf(`if (command === "${verb}")`);
+      const end = source.indexOf('\n    if (command === ', start + 1);
+      const block = source.slice(start, end);
+      expect(start).toBeGreaterThan(0);
+      expect(block).not.toContain("runtimeRequest(");
+      expect(block).toContain(verb === "export" ? "writeFileSync(resolve(target)" : "saveLocalDesktopProfile(");
+    }
+  });
+});
diff --git a/tests/cli/cli-capability-lab-workflows.test.ts b/tests/cli/cli-capability-lab-workflows.test.ts
new file mode 100644
index 00000000000..cd888cdf572
--- /dev/null
+++ b/tests/cli/cli-capability-lab-workflows.test.ts
@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LAB_CAPABILITIES } from "../../src/cli/capabilities-lab";
+import { handleLabCommand } from "../../src/cli/lab";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { repoPath } from "../helpers/repo-root";
+
+let home: string;
+let previous: Record<string, string | undefined>;
+let output: ReturnType<typeof spyOn<typeof console, "log">>;
+let errors: ReturnType<typeof spyOn<typeof console, "error">>;
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "ocx-cap-lab-"));
+  previous = { OPENCODEX_HOME: process.env.OPENCODEX_HOME, CODEX_HOME: process.env.CODEX_HOME };
+  process.env.OPENCODEX_HOME = home; process.env.CODEX_HOME = join(home, "codex");
+  output = spyOn(console, "log").mockImplementation(() => {});
+  errors = spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  output.mockRestore(); errors.mockRestore();
+  for (const [key, value] of Object.entries(previous)) {
+    if (value === undefined) delete process.env[key]; else process.env[key] = value;
+  }
+  removeTreeWithRetry(home);
+});
+function leaf(key: string) {
+  const result = LAB_CAPABILITIES.find(row => row.command.join(" ") === key);
+  expect(result).toBeDefined(); return result!;
+}
+
+describe("local Lab discovery contracts", () => {
+  test("catalog is a local JSON read with no projection or scheduler writes", async () => {
+    expect(leaf("lab catalog").routes).toEqual([]);
+    expect(leaf("lab catalog").mutates).toBe(false);
+    expect(await handleLabCommand(["catalog", "--json"], { configDir: home })).toBe(0);
+    const result = JSON.parse(String(output.mock.calls[0][0]));
+    expect(Array.isArray(result.scenarios)).toBe(true);
+    expect(result.scenarios.length).toBeGreaterThan(0);
+    expect(readdirSync(home)).toEqual([]);
+  });
+
+  test("invalid public evidence emits the failure summary and a nonzero exit", async () => {
+    const path = join(home, "invalid.json");
+    writeFileSync(path, "{}");
+    expect(leaf("lab public verify").usage).toBe("ocx lab public verify --file <bundle.json> [--json]");
+    expect(leaf("lab public verify").mutates).toBe(false);
+    expect(await handleLabCommand(["public", "verify", "--file", path, "--json"], { configDir: home })).toBe(1);
+    expect(JSON.parse(String(output.mock.calls[0][0]))).toEqual({ status: "schema_rejected", locallyVerified: false });
+    expect(readdirSync(home)).toEqual(["invalid.json"]);
+  });
+
+  test.each([
+    { key: "lab public import", args: ["public", "import", "--json"] },
+    { key: "lab automation enable", args: ["automation", "enable", "--protocol", "--unsupported", "--json"] },
+    { key: "lab automation disable", args: ["automation", "disable", "--unsupported", "--json"] },
+    { key: "lab run", args: ["run", "--layer", "live_route_compatibility", "--json"] },
+  ])("$key rejects incomplete input before local mutation or probes", async ({ key, args }) => {
+    expect(leaf(key).mutates).toBe(true); expect(leaf(key).routes).toEqual([]);
+    expect(await handleLabCommand(args, { configDir: home })).toBe(2);
+    expect(readdirSync(home)).toEqual([]);
+    expect(output.mock.calls).toHaveLength(0);
+  });
+
+  test("declarations distinguish actual local export/automation from HTTP", async () => {
+    const source = await Bun.file(repoPath("src", "cli", "lab.ts")).text();
+    for (const declaration of LAB_CAPABILITIES) expect(declaration.routes).toEqual([]);
+    expect(source).not.toMatch(/\bruntimeRequest\s*\(/);
+    expect(leaf("lab public preview").mutates).toBe(false);
+    expect(leaf("lab public export").mutates).toBe(true);
+    expect(source).toContain("exportLocalPublicEvidence({ eventIds }, configDir)");
+    expect(source).toContain('takeFlag(automationRest, "--live")');
+    expect(source).toContain("saveLabAutomationPolicyConfig(policy, configDir)");
+    expect(leaf("lab automation enable").flags.find(flag => flag.name === "--live")?.value).toBe("boolean");
+    expect(leaf("lab events").flags.find(flag => flag.name === "--excluded")?.value).toBe("string");
+    expect(leaf("lab run").flags.find(flag => flag.name === "--scenario")?.required).toBe(true);
+  });
+});
diff --git a/tests/cli/cli-capability-operation-workflows.test.ts b/tests/cli/cli-capability-operation-workflows.test.ts
new file mode 100644
index 00000000000..b8c1896bbe5
--- /dev/null
+++ b/tests/cli/cli-capability-operation-workflows.test.ts
@@ -0,0 +1,205 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CAPABILITIES as BASE } from "../../src/cli/capabilities-base";
+import { OBSERVE_SYSTEM_CAPABILITIES } from "../../src/cli/capabilities-observe-system";
+import { handleObserveCommand } from "../../src/cli/observe";
+import { handleStorageCommand } from "../../src/cli/storage";
+import { handleSystemCommand } from "../../src/cli/system-command";
+import { handleCompanionCommand } from "../../src/cli/companion";
+import { handleConfigCommand } from "../../src/cli/config-command";
+import { planServiceCommand } from "../../src/service/cli";
+import type { RuntimeApiDeps } from "../../src/cli/runtime-api";
+import { repoPath } from "../helpers/repo-root";
+
+const envKeys = ["HOME", "USERPROFILE", "OPENCODEX_HOME", "CODEX_HOME", "OPENCODEX_ADMIN_AUTH_TOKEN"] as const;
+let savedEnv: Array<string | undefined>;
+let home: string;
+let output: ReturnType<typeof spyOn>;
+let errors: ReturnType<typeof spyOn>;
+beforeEach(() => {
+  savedEnv = envKeys.map(key => process.env[key]);
+  home = mkdtempSync(join(tmpdir(), "ocx-capability-operations-"));
+  for (const key of envKeys) process.env[key] = home;
+  delete process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  output = spyOn(console, "log").mockImplementation(() => {});
+  errors = spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  output.mockRestore(); errors.mockRestore();
+  envKeys.forEach((key, index) => {
+    const value = savedEnv[index];
+    if (value === undefined) delete process.env[key]; else process.env[key] = value;
+  });
+  rmSync(home, { recursive: true, force: true });
+});
+function capability(key: string) {
+  const value = OBSERVE_SYSTEM_CAPABILITIES.find(row => row.command.join(" ") === key);
+  if (!value) throw new Error(`Missing capability: ${key}`);
+  return value;
+}
+function transport(payload: unknown = {}) {
+  const requests: Array<{ path: string; method: string; body: unknown }> = [];
+  const deps: RuntimeApiDeps = {
+    baseUrl: "http://capability.invalid",
+    fetchImpl: async (input, init) => {
+      expect(new Headers(init?.headers).has("X-OpenCodex-API-Key")).toBe(false);
+      const url = new URL(String(input));
+      requests.push({ path: url.pathname + url.search, method: init?.method ?? "GET", body: init?.body ? JSON.parse(String(init.body)) : null });
+      return Response.json(payload);
+    },
+  };
+  return { requests, deps };
+}
+
+describe("operation capability workflows use existing handlers", () => {
+  test.each([
+    ["observe memory", "memory", "/api/system/memory"],
+    ["observe debug", "debug", "/api/debug"],
+    ["observe claude-inbound", "claude-inbound", "/api/claude/inbound-debug"],
+    ["observe injection", "injection", "/api/debug/injection-logs"],
+    ["observe storage", "storage", "/api/storage"],
+  ])("%s snapshot forwards its limit", async (key, sub, path) => {
+    const leaf = capability(key);
+    expect(leaf.routes).toEqual([{ method: "GET", path }]);
+    expect(leaf.flags.map(flag => flag.name)).toContain("--limit");
+    expect(leaf.mutates).toBe(false);
+    const io = transport();
+    expect(await handleObserveCommand([sub, "--limit", "7", "--json"], io.deps)).toBe(0);
+    expect(io.requests).toEqual([{ method: "GET", path: path + "?limit=7", body: null }]);
+  });
+  test("logs retains exact filters and explain encodes one request ID", async () => {
+    const io = transport({ logs: [] });
+    expect(capability("observe logs").routes).toEqual([{ method: "GET", path: "/api/logs" }]);
+    expect(await handleObserveCommand(["logs", "--provider", "fixture", "--conversationId", "c/1", "--account", "main", "--limit", "3", "--json"], io.deps)).toBe(0);
+    expect(io.requests).toEqual([{ method: "GET", path: "/api/logs?provider=fixture&conversationId=c%2F1&account=main&limit=3", body: null }]);
+    const explain = transport();
+    expect(capability("logs explain").usage).toBe("ocx logs explain <request-id> [--json]");
+    expect(capability("logs explain").routes).toEqual([{ method: "GET", path: "/api/request-history/{id}/route-decision" }]);
+    expect(await handleObserveCommand(["logs", "explain", "req/1", "--json"], explain.deps)).toBe(0);
+    expect(explain.requests).toEqual([{ method: "GET", path: "/api/request-history/req%2F1/route-decision", body: null }]);
+  });
+  test("usage keeps surface and custom bounds in the actual request", async () => {
+    const io = transport({ customWindow: true, since: 1000, until: 2000 });
+    expect(capability("observe usage").flags.map(flag => flag.name)).toContain("--surface");
+    expect(await handleObserveCommand(["usage", "--range", "7d", "--surface", "claude", "--since", "1000", "--until", "2000", "--json"], io.deps)).toBe(0);
+    expect(io.requests).toEqual([{ method: "GET", path: "/api/usage?range=7d&surface=claude&since=1000&until=2000", body: null }]);
+  });
+  test("system settings distinguishes read from submitted field writes", async () => {
+    const leaf = capability("system settings");
+    expect(leaf.mutates).toBe(true);
+    expect(leaf.routes).toEqual([{ method: "GET", path: "/api/settings" }, { method: "PUT", path: "/api/settings" }]);
+    const io = transport();
+    expect(await handleSystemCommand(["settings", "--json"], io.deps)).toBe(0);
+    expect(await handleSystemCommand(["settings", "--auto-start", "off", "--desktop-authless", "on", "--client-compaction", "off", "--json"], io.deps)).toBe(0);
+    expect(io.requests).toEqual([
+      { method: "GET", path: "/api/settings", body: null },
+      { method: "PUT", path: "/api/settings", body: { codexAutoStart: false, codexDesktopAuthless: true, codexClientCompaction: false } },
+    ]);
+  });
+  test.each([
+    ["system startup health", ["startup", "health", "--json"], "/api/startup-health"],
+    ["system diagnostics", ["diagnostics", "--json"], "/api/diagnostics/project-config"],
+    ["system update check", ["update", "check", "--channel", "preview", "--json"], "/api/update/check?tag=preview"],
+    ["system update status", ["update", "status", "job/1", "--json"], "/api/update/status?jobId=job%2F1"],
+  ] as const)("%s follows the real read contract", async (key, args, path) => {
+    const io = transport();
+    expect(capability(key).routes).toEqual([{ method: "GET", path: path.split("?")[0]! }]);
+    expect(await handleSystemCommand([...args], io.deps)).toBe(0);
+    expect(io.requests).toEqual([{ method: "GET", path, body: null }]);
+  });
+  test("system status is a CLI envelope over exactly three reads", async () => {
+    const io = transport();
+    expect(capability("system status").json).toBe("envelope");
+    expect(await handleSystemCommand(["status", "--json"], io.deps)).toBe(0);
+    expect(io.requests.map(request => request.path).sort()).toEqual(["/api/settings", "/api/startup-health", "/api/system/memory"]);
+    expect(JSON.parse(String(output.mock.calls[0]![0]))).toEqual({ settings: {}, startup: {}, memory: {} });
+  });
+  test("companion family requires show when JSON is requested", async () => {
+    expect(BASE.find(row => row.command.join(" ") === "companion")?.usage).toStartWith("ocx companion show [--json]");
+    const io = transport({ settings: {} });
+    expect(await handleCompanionCommand(["--json"], io.deps)).toBe(2);
+    expect(io.requests).toEqual([]);
+    expect(await handleCompanionCommand(["show", "--json"], io.deps)).toBe(0);
+    expect(io.requests).toHaveLength(1);
+  });
+  test("companion leaves never claim or request timeline data", async () => {
+    const io = transport();
+    for (const sub of ["show", "set", "reset"]) {
+      expect(capability("companion " + sub).routes).toEqual([{ method: sub === "show" ? "GET" : "PUT", path: "/api/companion/settings" }]);
+      expect(await handleCompanionCommand([sub, ...(sub === "set" ? ["showChart=false", "models=null"] : []), "--json"], io.deps)).toBe(0);
+    }
+    expect(io.requests).toEqual([
+      { method: "GET", path: "/api/companion/settings", body: null },
+      { method: "PUT", path: "/api/companion/settings", body: { settings: { showChart: false, models: null } } },
+      { method: "PUT", path: "/api/companion/settings", body: { reset: true } },
+    ]);
+  });
+  test("storage policy set keeps nested target semantics", async () => {
+    const io = transport();
+    expect(capability("storage policy set").routes).toEqual([{ method: "PUT", path: "/api/storage/cleanup-policy" }]);
+    expect(await handleStorageCommand(["policy", "set", "--enabled", "false", "--percent", "12", "--json"], io.deps)).toBe(0);
+    expect(io.requests).toEqual([{ method: "PUT", path: "/api/storage/cleanup-policy", body: { enabled: false, target: { removeOldestPercent: 12 } } }]);
+  });
+  test.each([
+    ["storage trash restore", ["trash", "restore", "fixture-entry"]],
+    ["storage policy run", ["policy", "run"]],
+  ] as const)("%s refuses without confirmation before transport", async (key, args) => {
+    expect(capability(key).flags.find(flag => flag.name === "--yes")?.required).toBe(true);
+    const io = transport();
+    expect(await handleStorageCommand([...args], io.deps)).toBe(2);
+    expect(io.requests).toEqual([]);
+  });
+  test("update run refuses before any install request", async () => {
+    const io = transport();
+    expect(capability("system update run").mutates).toBe(true);
+    expect(await handleSystemCommand(["update", "run", "--json"], io.deps)).toBe(2);
+    expect(io.requests).toEqual([]);
+  });
+  test.each(["protect", "unprotect", "repair", "compact"])("Log Guard %s rejects an invalid mode before mutation", async action => {
+    const leaf = capability("storage codex-logs " + action);
+    expect(leaf.routes).toEqual([{ method: "POST", path: "/api/storage/codex-logs/" + action }]);
+    expect(leaf.mutates).toBe(true);
+    const io = transport();
+    expect(await handleStorageCommand(["codex-logs", action, "--mode", "invalid", "--json"], io.deps)).toBe(2);
+    expect(io.requests).toEqual([]);
+  });
+  test("index inspection is conservatively local and mutating", async () => {
+    const io = transport();
+    for (const action of ["index-status", "rebuild-index"]) {
+      expect(capability("logs " + action).routes).toEqual([]);
+      expect(capability("logs " + action).mutates).toBe(true);
+      expect(await handleObserveCommand(["logs", action, "--invalid"], io.deps)).toBe(2);
+    }
+    expect(io.requests).toEqual([]);
+    const source = readFileSync(repoPath("src/routing/history/indexer.ts"), "utf8");
+    expect(source).toMatch(/requestHistoryIndexStatus\(\)[\s\S]*?return openRequestHistoryIndex\(\)/);
+  });
+  test("local config metadata keeps secret export separate and missing operands refuse", async () => {
+    for (const action of ["get", "set", "unset", "export", "import"]) {
+      expect(capability("config " + action).routes).toEqual([]);
+      expect(await handleConfigCommand([action])).toBe(2);
+    }
+    expect(capability("config export").mutates).toBe(true);
+    expect(capability("config export").details?.join(" ")).toContain("raw credentials");
+  });
+  test("service backend flags have platform and subcommand limits without execution", () => {
+    expect(capability("service install").routes).toEqual([]);
+    expect(capability("service install").json).toBe("none");
+    expect(planServiceCommand(["install", "--native"], { platform: "linux" }).ok).toBe(false);
+    expect(planServiceCommand(["repair", "--native"], { platform: "win32" }).ok).toBe(false);
+    const plan = planServiceCommand(["install", "--native"], { platform: "win32" });
+    expect(plan.ok && plan.command).toBe("install");
+    for (const key of ["service repair", "service restart", "codex-shim install", "tray install"]) {
+      expect(capability(key).routes).toEqual([]);
+      expect(capability(key).mutates).toBe(true);
+    }
+    expect(capability("tray install").flags.map(flag => flag.name)).toEqual(["--no-start", "--json"]);
+    const tray = readFileSync(repoPath("src/tray/windows.ts"), "utf8");
+    expect(tray).toContain('args.includes("--no-start") && sub !== "install"');
+    expect(tray).toContain('process.platform !== "win32"');
+    const dispatch = readFileSync(repoPath("src/cli/dispatch.ts"), "utf8");
+    expect(dispatch).toContain('case "install": {\n        const r = installCodexShim();');
+  });
+});
diff --git a/tests/cli/cli-capability-provider-workflows.test.ts b/tests/cli/cli-capability-provider-workflows.test.ts
new file mode 100644
index 00000000000..c02b7d6d2a8
--- /dev/null
+++ b/tests/cli/cli-capability-provider-workflows.test.ts
@@ -0,0 +1,210 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { PROVIDER_MODEL_CAPABILITIES } from "../../src/cli/capabilities-provider-models";
+import { CAPABILITIES as BASE } from "../../src/cli/capabilities-base";
+import { handleProviderRuntimeCommand } from "../../src/cli/provider-runtime";
+import { handleModelsRuntimeCommand } from "../../src/cli/models-runtime";
+import { handleAliasCommand } from "../../src/cli/alias";
+import type { RuntimeApiDeps } from "../../src/cli/runtime-api";
+import { createTempHome, type TempHome } from "../helpers/temp-home";
+import { repoPath } from "../helpers/repo-root";
+
+type Request = { method: string; path: string; body?: unknown };
+let home: TempHome;
+let previousToken: string | undefined;
+let output: ReturnType<typeof spyOn>;
+let errors: ReturnType<typeof spyOn>;
+beforeEach(() => {
+  home = createTempHome("ocx-capability-provider-");
+  previousToken = process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  delete process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  output = spyOn(console, "log").mockImplementation(() => {});
+  errors = spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  output.mockRestore(); errors.mockRestore();
+  if (previousToken === undefined) delete process.env.OPENCODEX_ADMIN_AUTH_TOKEN;
+  else process.env.OPENCODEX_ADMIN_AUTH_TOKEN = previousToken;
+  home.remove();
+});
+
+function fake(calls: Request[], payload: unknown = { ok: true }): RuntimeApiDeps {
+  return {
+    baseUrl: "http://127.0.0.1:1",
+    fetchImpl: (async (input, init) => {
+      const url = new URL(String(input));
+      expect(new Headers(init?.headers).has("X-OpenCodex-API-Key")).toBe(false);
+      calls.push({ method: init?.method ?? "GET", path: url.pathname + url.search,
+        ...(init?.body === undefined ? {} : { body: JSON.parse(String(init.body)) }) });
+      return Response.json(payload);
+    }) as typeof fetch,
+  };
+}
+
+function capability(key: string) {
+  const row = PROVIDER_MODEL_CAPABILITIES.find(row => row.command.join(" ") === key);
+  expect(row).toBeDefined();
+  return row!;
+}
+
+describe("provider/model discovery follows existing handlers", () => {
+  test("new leaves are unique, separate from baseline, and have complete usage", () => {
+    const keys = PROVIDER_MODEL_CAPABILITIES.map(row => row.command.join(" "));
+    expect(new Set(keys).size).toBe(keys.length);
+    for (const row of PROVIDER_MODEL_CAPABILITIES) {
+      expect(BASE.some(base => base.command.join(" ") === row.command.join(" "))).toBe(false);
+      expect(row.usage?.startsWith(`ocx ${row.command.join(" ")}`)).toBe(true);
+      expect(row.flags.some(flag => flag.name === "--live")).toBe(false);
+    }
+  });
+
+  test("local provider and custom-model commands do not acquire fictitious management routes", () => {
+    for (const key of ["provider add", "provider show", "provider remove", "provider set-default", "models list", "models add", "models remove", "models list-custom"]) {
+      expect(capability(key).routes).toEqual([]);
+    }
+    expect(capability("models add").json).toBe("none");
+    expect(capability("models remove").flags.map(flag => flag.name)).toEqual(["--yes"]);
+    // Compare the source's actual public usage constants, without executing local mutation/sync.
+    const source = readFileSync(repoPath("src", "cli", "models.ts"), "utf8");
+    const removeUsage = /const REMOVE_USAGE = "Usage: ([^"]+)"/.exec(source)?.[1];
+    expect(capability("models remove").usage).toBe(removeUsage);
+    const listUsage = /const LIST_CUSTOM_USAGE = "Usage: ([^"]+)"/.exec(source)?.[1];
+    expect(capability("models list-custom").usage).toBe(listUsage);
+  });
+
+  test("provider edit keeps scalar clears, JSON nulls and inverse xAI routing distinct", async () => {
+    const row = capability("provider edit");
+    expect(row.routes).toEqual([{ method: "PATCH", path: "/api/providers" }]);
+    expect(row.flags.find(flag => flag.name === "--enabled")?.value).toBe("string");
+    const calls: Request[] = [];
+    expect(await handleProviderRuntimeCommand("edit", ["xai", "--default-model", "-", "--headers", "-", "--retain-models", "-", "--enabled", "off", "--xai-chat", "off", "--json"], fake(calls))).toBe(0);
+    expect(calls).toEqual([{ method: "PATCH", path: "/api/providers?name=xai", body: {
+      xaiResponsesOptIn: true, defaultModel: "", headers: null, disabled: true, retainModels: null,
+    } }]);
+  });
+
+  test.each([
+    { key: "provider account-mode", sub: "account-mode", args: ["direct", "--json"], expected: { method: "PATCH", path: "/api/providers?name=openai", body: { codexAccountMode: "direct" } } },
+    { key: "provider selected", sub: "selected", args: ["fixture", "--clear", "--json"], expected: { method: "PUT", path: "/api/selected-models", body: { provider: "fixture", models: [] } } },
+    { key: "provider presets", sub: "presets", args: ["--json"], expected: { method: "GET", path: "/api/provider-presets" } },
+    { key: "provider quota", sub: "quota", args: ["--refresh", "--json"], expected: { method: "GET", path: "/api/provider-quotas?refresh=1" } },
+  ])("$key declares the real request", async ({ key, sub, args, expected }) => {
+    expect(capability(key).routes).toContainEqual({ method: expected.method, path: expected.path.split("?")[0] });
+    const calls: Request[] = [];
+    expect(await handleProviderRuntimeCommand(sub, args, fake(calls))).toBe(0);
+    expect(calls).toEqual([expected]);
+  });
+
+  test.each([
+    { key: "provider selected", handler: handleProviderRuntimeCommand },
+    { key: "models selected", handler: handleModelsRuntimeCommand },
+  ])("$key declares an envelope and emits provider-specific read arrays", async ({ key, handler }) => {
+    expect(capability(key).json).toBe("envelope");
+    const calls: Request[] = [];
+    const deps = fake(calls, {
+      selected: { fixture: ["selected-model"], other: ["other-selection"] },
+      available: { fixture: ["selected-model", "available-model"], other: ["other-model"] },
+      serverOnly: "not part of the CLI read view",
+    });
+    expect(await handler("selected", ["fixture", "--json"], deps)).toBe(0);
+    expect(calls).toEqual([{ method: "GET", path: "/api/selected-models" }]);
+    expect(output.mock.calls).toHaveLength(1);
+    expect(JSON.parse(String(output.mock.calls[0]?.[0]))).toEqual({
+      provider: "fixture", selected: ["selected-model"], available: ["selected-model", "available-model"],
+    });
+    expect(await handler("selected", ["missing", "--json"], deps)).toBe(0);
+    expect(calls).toEqual([
+      { method: "GET", path: "/api/selected-models" },
+      { method: "GET", path: "/api/selected-models" },
+    ]);
+    expect(output.mock.calls).toHaveLength(2);
+    expect(JSON.parse(String(output.mock.calls[1]?.[0]))).toEqual({ provider: "missing", selected: [], available: [] });
+  });
+
+  test.each([
+    { key: "provider selected", handler: handleProviderRuntimeCommand },
+    { key: "models selected", handler: handleModelsRuntimeCommand },
+  ])("$key preserves the server receipt for writes", async ({ key, handler }) => {
+    expect(capability(key).json).toBe("envelope");
+    const calls: Request[] = [];
+    expect(await handler("selected", ["fixture", "--clear", "--json"], fake(calls, {
+      ok: true, selected: { fixture: [] }, saved: true,
+    }))).toBe(0);
+    expect(calls).toEqual([{ method: "PUT", path: "/api/selected-models", body: { provider: "fixture", models: [] } }]);
+    expect(output.mock.calls).toHaveLength(1);
+    expect(JSON.parse(String(output.mock.calls[0]?.[0]))).toEqual({ ok: true, selected: { fixture: [] }, saved: true });
+  });
+
+  test.each([
+    { key: "models context status", args: ["context", "status", "--json"], expected: { method: "GET", path: "/api/provider-context-caps" } },
+    { key: "models context value", args: ["context", "value", "128_000", "--set-all", "--json"], expected: { method: "PUT", path: "/api/provider-context-caps", body: { value: 128000, setAll: true } } },
+    { key: "models context provider", args: ["context", "provider", "fixture", "on", "--value", "64000", "--json"], expected: { method: "PUT", path: "/api/provider-context-caps", body: { provider: "fixture", enabled: true, value: 64000 } } },
+    { key: "models context all", args: ["context", "all", "off", "--json"], expected: { method: "PUT", path: "/api/provider-context-caps", body: { setAll: false } } },
+    { key: "models shadow status", args: ["shadow", "status", "--json"], expected: { method: "GET", path: "/api/shadow-call-settings" } },
+    { key: "models shadow set", args: ["shadow", "set", "-", "--enabled", "off", "--json"], expected: { method: "PUT", path: "/api/shadow-call-settings", body: { model: "", enabled: false } } },
+    { key: "models selected", args: ["selected", "fixture", "--clear", "--json"], expected: { method: "PUT", path: "/api/selected-models", body: { provider: "fixture", models: [] } } },
+    { key: "models preset show", args: ["preset", "show", "--json"], expected: { method: "GET", path: "/api/model-presets" } },
+    { key: "models preset apply", args: ["preset", "apply", "fixture", "--all", "--json"], expected: { method: "PUT", path: "/api/model-presets", body: { provider: "fixture", mode: "all" } } },
+    { key: "models new-policy", args: ["new-policy", "off", "--provider", "fixture", "--json"], expected: { method: "PUT", path: "/api/model-discovery", body: { policy: "off", provider: "fixture" } } },
+    { key: "models enable", args: ["enable", "fixture/upstream/model", "--json"], expected: { method: "PUT", path: "/api/model-visibility", body: { scope: "models", provider: "fixture", enabled: true, targets: [{ id: "upstream/model", native: false }] } } },
+    { key: "models disable", args: ["disable", "native-model", "--native", "--json"], expected: { method: "PUT", path: "/api/model-visibility", body: { scope: "models", provider: "openai", enabled: false, targets: [{ id: "native-model", native: true }] } } },
+  ])("$key keeps exact operands and body", async ({ key, args, expected }) => {
+    expect(capability(key).routes).toContainEqual({ method: expected.method, path: expected.path });
+    const calls: Request[] = [];
+    expect(await handleModelsRuntimeCommand(args[0]!, args.slice(1), fake(calls))).toBe(0);
+    expect(calls).toEqual([expected]);
+  });
+
+  test("custom edit clears a definition, not discovered-model settings or names", async () => {
+    expect(capability("models edit").routes).toEqual([{ method: "PUT", path: "/api/custom-models/{id}" }]);
+    const calls: Request[] = [];
+    expect(await handleModelsRuntimeCommand("edit", ["custom/id", "--display-name", "-", "--context-window", "0", "--modalities", "-", "--reasoning-efforts", "", "--default-reasoning-effort", "-", "--json"], fake(calls))).toBe(0);
+    expect(calls).toEqual([{ method: "PUT", path: "/api/custom-models/custom%2Fid", body: {
+      displayName: "", contextWindow: null, inputModalities: [], reasoningEfforts: [], defaultReasoningEffort: null,
+    } }]);
+  });
+
+  test("live filtering and provider-wide visibility use the actual catalog", async () => {
+    const calls: Request[] = [];
+    const rows = [{ provider: "fixture", id: "free", pricingStatus: "free" }, { provider: "fixture", id: "unknown" }, { provider: "other", id: "else", pricingStatus: "free" }];
+    expect(capability("models live").routes).toEqual([{ method: "GET", path: "/api/models" }]);
+    expect(await handleModelsRuntimeCommand("live", ["--provider", "fixture", "--free-only", "--json"], fake(calls, rows))).toBe(0);
+    expect(JSON.parse(String(output.mock.calls.at(-1)?.[0]))).toEqual([rows[0]]);
+    expect(capability("models provider").routes).toEqual([{ method: "GET", path: "/api/models" }, { method: "PUT", path: "/api/model-visibility" }]);
+    expect(await handleModelsRuntimeCommand("provider", ["fixture", "off", "--json"], fake(calls, rows))).toBe(0);
+    expect(calls.at(-1)).toEqual({ method: "PUT", path: "/api/model-visibility", body: { scope: "provider", provider: "fixture", enabled: false, targets: [{ id: "free", native: false }, { id: "unknown", native: false }] } });
+  });
+
+  test("new arrivals is a projection of discovery state", async () => {
+    const calls: Request[] = [];
+    expect(capability("models new-arrivals").routes).toEqual([{ method: "GET", path: "/api/model-discovery" }]);
+    expect(await handleModelsRuntimeCommand("new-arrivals", ["--json"], fake(calls, { recentArrivals: { fixture: [{ id: "new", at: "2026-10-04", state: "off" }] } }))).toBe(0);
+    expect(calls).toEqual([{ method: "GET", path: "/api/model-discovery" }]);
+    expect(JSON.parse(String(output.mock.calls.at(-1)?.[0]))).toEqual({ fixture: [{ id: "new", at: "2026-10-04", state: "off" }] });
+  });
+
+  test.each([
+    { key: "alias list", args: ["list", "--json"], expected: { method: "GET", path: "/api/aliases" } },
+    { key: "alias set", args: ["set", "fixture/upstream/model", "friendly", "--json"], expected: { method: "PUT", path: "/api/providers/fixture/model-aliases", body: { set: { "upstream/model": "friendly" } } } },
+    { key: "alias rm", args: ["rm", "fixture", "--json"], expected: { method: "PUT", path: "/api/providers/fixture/alias", body: { alias: null } } },
+    { key: "alias defaults", args: ["defaults", "off", "--provider", "fixture", "--json"], expected: { method: "PUT", path: "/api/default-aliases", body: { enabled: false, provider: "fixture" } } },
+  ])("$key exposes the existing alias request", async ({ key, args, expected }) => {
+    expect(capability(key).json).toBe("payload");
+    const calls: Request[] = [];
+    expect(await handleAliasCommand(args, fake(calls))).toBe(0);
+    expect(calls).toEqual([expected]);
+  });
+
+  test("invalid grammar is refused without contacting any provider", async () => {
+    const calls: Request[] = [];
+    const deps = fake(calls);
+    expect(capability("models context provider").usage).toBe("ocx models context provider <provider> <on|off> [--value <tokens>] [--json]");
+    expect(await handleModelsRuntimeCommand("context", ["provider", "fixture", "off", "--value", "64000"], deps)).not.toBe(0);
+    expect(await handleModelsRuntimeCommand("selected", ["fixture", "--set", "m", "--clear"], deps)).not.toBe(0);
+    expect(await handleModelsRuntimeCommand("edit", ["id", "--context-window", "-"], deps)).not.toBe(0);
+    expect(await handleProviderRuntimeCommand("test", [], deps)).not.toBe(0);
+    expect(capability("provider test").routes).toEqual([{ method: "POST", path: "/api/providers/test" }]);
+    expect(await handleProviderRuntimeCommand("edit", ["other", "--xai-chat", "on"], deps)).not.toBe(0);
+    expect(calls).toEqual([]);
+  });
+});
diff --git a/tests/cli/cli-help-navigation.test.ts b/tests/cli/cli-help-navigation.test.ts
index 0b04235613f..bed0e8f38b5 100644
--- a/tests/cli/cli-help-navigation.test.ts
+++ b/tests/cli/cli-help-navigation.test.ts
@@ -148,6 +148,6 @@ describe("CLI help navigation", () => {
       fallbackToParent: true, write: value => { lines.push(value); },
     }));
     expect(stdout).toBe("");
-    expect(lines.join("\n")).toContain("ocx models context <status|value");
+    expect(lines.join("\n")).toContain("ocx models context provider <provider> <on|off>");
   });
 });
diff --git a/tests/cli/cli-help-paths.test.ts b/tests/cli/cli-help-paths.test.ts
index 6be59a79c86..48d2aa9139e 100644
--- a/tests/cli/cli-help-paths.test.ts
+++ b/tests/cli/cli-help-paths.test.ts
@@ -79,22 +79,22 @@ describe("explicit CLI help paths", () => {
     expect(new Set(outputs).size).toBe(1);
   });
 
-  test("declared leaves show metadata without inventing operands", () => {
+  test("declared leaves show verified usage and exact operands", () => {
     const result = help(["help", "account", "list"]);
     expect(result.status).toBe(0);
     expect(result.stderr).toBe("");
-    expect(result.stdout).toContain("Command: ocx account list");
+    expect(result.stdout).toContain("Usage: ocx account list [provider]");
     expect(result.stdout).toContain("--json");
-    expect(result.stdout).toContain("paused-but-selected");
+    expect(result.stdout).toContain("--quota");
     expect(result.stdout).toContain("Parent help: ocx help account");
-    expect(result.stdout).not.toContain("Usage:");
+    expect(result.stdout).not.toContain("not the full operand grammar");
   });
 
   test("command-side help with operands falls back to known help without writes", () => {
     for (const [args, expected] of [
       [["service", "uninstall", "--help"], "Usage: ocx service"],
       [["codex-shim", "uninstall", "--help"], "Usage: ocx codex-shim"],
-      [["models", "context", "provider", "example", "on", "-h"], "ocx models context <status|value"],
+      [["models", "context", "provider", "example", "on", "-h"], "ocx models context provider <provider> <on|off>"],
     ] as const) {
       const result = help([...args]);
       expect(result.status).toBe(0);
@@ -111,14 +111,33 @@ describe("explicit CLI help paths", () => {
     expect(result.stdout).not.toContain("Usage:");
   });
 
+  test("runnable capability parents retain their usage and expose deeper help", () => {
+    const path = ["access", "key"];
+    const result = resolveHelpPath(path);
+    expect(result.kind).toBe("capability");
+    if (result.kind !== "capability") throw new Error("expected capability help");
+    expect(result.children.map(child => child.command.join(" "))).toContain("access key list");
+    expect(result.children.map(child => child.command.join(" "))).toContain("access key rotate commit");
+    expect(result.children.some(child => child.command.length <= path.length)).toBe(false);
+    const output = help(["help", ...path]);
+    expect(output.status).toBe(0);
+    expect(output.stderr).toBe("");
+    expect(output.stdout).toContain("Usage: ocx access key list [--json]");
+    expect(output.stdout).toContain("Declared commands (incomplete)");
+    expect(output.stdout).toContain("ocx help access key list");
+    expect(output.stdout).toContain("ocx help access key rotate commit");
+    expect(output.stdout).toContain("Parent help: ocx help access");
+    const leaf = resolveHelpPath(["access", "key", "list"]);
+    expect(leaf).toMatchObject({ kind: "capability", children: [] });
+  });
+
   test("undeclared detail does not claim runtime grammar is invalid", () => {
     for (const [path, parent] of [
-      [["service", "install"], "service"],
-      [["service", "uninstall"], "service"],
-      [["codex-shim", "uninstall"], "codex-shim"],
-      [["models", "list-custom"], "models"],
+      [["service", "not-declared"], "service"],
+      [["codex-shim", "not-declared"], "codex-shim"],
+      [["models", "not-declared"], "models"],
       [["account", "main", "not-declared"], "account main"],
-      [["models", "context", "status"], "models context"],
+      [["models", "context", "not-declared"], "models context"],
     ] as const) {
       const result = help(["help", ...path]);
       expect(result.status).toBe(1);
@@ -154,6 +173,40 @@ describe("explicit CLI help paths", () => {
     expect(resolveHelpPath(["account", "list"]).kind).toBe("capability");
   });
 
+  test("access aliases resolve nested help without changing exact root help", () => {
+    const root = resolveHelpPath(["api-key"]);
+    expect(root).toMatchObject({ kind: "entry", entry: { name: "api-key" }, canonicalName: "access key" });
+    const rootOutput = help(["help", "api-key"]);
+    expect(rootOutput.status).toBe(0);
+    expect(rootOutput.stdout).toContain("Usage: ocx api-key ");
+    expect(rootOutput.stdout).toContain("Canonical help: ocx help access key");
+    expect(rootOutput.stdout).toContain("ocx help access key list");
+    const canonical = help(["help", "access", "key", "remove"]);
+    expect(canonical.status).toBe(0);
+    for (const path of [["api-key", "delete"], ["api-key", "remove"], ["access", "keys", "delete"], ["access", "key", "delete"]]) {
+      const before = [...path];
+      expect(resolveHelpPath(path)).toMatchObject({ kind: "capability", path: ["access", "key", "remove"] });
+      expect(path).toEqual(before);
+      for (const args of [["help", ...path], [...path, "--help"]]) {
+        const output = help(args);
+        expect(output.status).toBe(0);
+        expect(output.stderr).toBe("");
+        expect(output.stdout).toBe(canonical.stdout);
+      }
+    }
+    const rotate = help(["help", "api-key", "rotate", "commit"]);
+    expect(rotate.status).toBe(0);
+    expect(rotate.stdout).toContain("Parent help: ocx help access key rotate");
+    const operand = ["access", "keys", "get", "delete"];
+    expect(resolveHelpPath(operand)).toMatchObject({
+      kind: "unavailable", path: ["access", "key", "get", "delete"], parent: ["access", "key", "get"],
+    });
+    expect(operand).toEqual(["access", "keys", "get", "delete"]);
+    for (const path of [["access", "delete"], ["provider", "delete"], ["access", "key", "rotate", "delete"]]) {
+      expect(resolveHelpPath(path)).toMatchObject({ kind: "unavailable", path });
+    }
+  });
+
   test("help lookup and rendering preserve machine capability JSON", async () => {
     const metadata = JSON.stringify({ CAPABILITIES, HEAD_CAPABILITIES });
     const lines: string[] = [];
diff --git a/tests/cli/cli-help-recovery.test.ts b/tests/cli/cli-help-recovery.test.ts
index 47abb55bfb7..60a553380d0 100644
--- a/tests/cli/cli-help-recovery.test.ts
+++ b/tests/cli/cli-help-recovery.test.ts
@@ -58,9 +58,9 @@ describe("CLI help recovery", () => {
     const account = helpRecoveryCandidates(["account"]);
     expect(account.every(candidate => candidate.path.length === 2)).toBe(true);
     expect(account.some(candidate => candidate.path.join(" ") === "account main")).toBe(true);
-    expect(helpRecoveryCandidates(["account", "main"]).map(candidate => candidate.path)).toEqual([["account", "main", "reauth"]]);
+    expect(helpRecoveryCandidates(["account", "main"]).map(candidate => candidate.path.at(-1))).toEqual(["reauth", "doctor", "list", "register", "add", "switch", "recover"]);
     expect(helpRecoveryCandidates(["model"]).some(candidate => candidate.path.join(" ") === "models context")).toBe(true);
-    expect(helpRecoveryCandidates(["models", "context"])).toEqual([]);
+    expect(helpRecoveryCandidates(["models", "context"]).map(candidate => candidate.path.at(-1))).toEqual(["status", "value", "provider", "all"]);
   });
 
   test("matching folds case, handles transposition, deduplicates aliases and respects distance limits", () => {
@@ -75,6 +75,28 @@ describe("CLI help recovery", () => {
     expect(suggestHelpPaths(["internla"])).toEqual([]);
   });
 
+  test("access alias recovery uses canonical depth and stays deterministic", () => {
+    expect(helpRecoveryCandidates(["api-key"])).toEqual(helpRecoveryCandidates(["access", "key"]));
+    expect(helpRecoveryCandidates(["access", "keys"])).toEqual(helpRecoveryCandidates(["access", "key"]));
+    for (const prefix of [["api-key"], ["access", "keys"], ["access", "key"]]) {
+      expect(suggestHelpPaths([...prefix, "lisst"])).toEqual([["access", "key", "list"]]);
+      expect(suggestHelpPaths([...prefix, "delet"])).toEqual([["access", "key", "remove"]]);
+      expect(suggestHelpPaths([...prefix, "rotate", "commti"])).toEqual([["access", "key", "rotate", "commit"]]);
+      expect(formatHelpRecovery([...prefix, "lisst"])).toBe(
+        "Detailed help unavailable for the requested topic.\nDid you mean:\n  ocx help access key list\nSee: ocx help access key");
+    }
+    expect(suggestHelpPaths(["api-ke"])).toEqual([["access", "key"]]);
+    expect(suggestHelpPaths(["access", "kyes"])).toEqual([["access", "key"]]);
+    expect(suggestHelpPaths(["api-key", "qzxv"])).toEqual([]);
+    expect(suggestHelpPaths(["api-key", "lisst", "private\u001b[2J"])).toEqual([]);
+    expect(suggestHelpPaths(["api-key", "lisst", ...Array(6).fill("operand")])).toEqual([]);
+    const result = cli(["help", "api-key", "lisst"]);
+    expect(result.status).toBe(1);
+    expect(result.stdout).toBe("");
+    expect(result.stderr).toBe(formatHelpRecovery(["api-key", "lisst"]) + "\n");
+    expect(result.stderr).not.toContain("TypeError");
+  });
+
   test("matching rejects unsafe tokens and excessive depth without truncating to candidates", () => {
     for (const token of ["mo", "modles\u001b", "modles\n", "modles\u0085", "modles\u2028", "mödles", "modles" + "x".repeat(59)]) {
       expect(suggestHelpPaths([token])).toEqual([]);
diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
index 8b397236936..ceb40036870 100644
--- a/tests/fixtures/test-layout-expected.json
+++ b/tests/fixtures/test-layout-expected.json
@@ -1,4 +1,14 @@
 {
+  "cli-capability-integration-workflows.test.ts": "cli",
+  "cli-capability-account-workflows.test.ts": "cli",
+  "cli-capability-agent-workflows.test.ts": "cli",
+  "cli-capability-operation-workflows.test.ts": "cli",
+  "cli-capability-provider-workflows.test.ts": "cli",
+  "cli-capability-access-workflows.test.ts": "cli",
+  "cli-capability-lab-workflows.test.ts": "cli",
+  "skill-ocx-workflows.test.ts": "ci-workflows",
+  "cli-capability-data.test.ts": "cli",
+  "skill-ocx-generated.test.ts": "ci-workflows",
   "cli-update-restart.test.ts": "cli",
   "cli-update-restart-child.test.ts": "cli",
   "cli-update-restart-transport.test.ts": "cli",
@@ -1088,36 +1098,20 @@
   "zz-ci-api-usage-isolation.test.ts": "ci-workflows",
   "zz-ci-storage-policy-isolation.test.ts": "ci-workflows",
   "zz-pr-coderabbit-readiness-revalidation.test.ts": "ci-workflows",
-  "deepseek-quota-currency.test.ts": "providers",
-  "mimo-token-plan-capacity.test.ts": "providers",
-  "command-code-tool-text-prose-split.test.ts": "providers",
-  "cli-effort-slug.test.ts": "cli",
-  "grok-47-build-fast-metadata.test.ts": "providers/xai",
-  "grok-47-fast-model.test.ts": "providers/xai",
-  "grok-47-fast-model-wire.test.ts": "providers/xai",
-  "client-link-connect.test.ts": "clients",
-  "client-link-relay.test.ts": "clients",
-  "client-link-runtime.test.ts": "clients",
-  "link-routes.test.ts": "clients",
-  "client-link-state.test.ts": "clients",
-  "client-link-status.test.ts": "clients",
-  "client-link-teardown.test.ts": "clients",
-  "client-link-tunnel.test.ts": "clients",
-  "link-ports.test.ts": "clients",
-  "injection-link-websocket.test.ts": "codex-integration",
-  "link-supervisor.test.ts": "clients",
-  "link-status-projection.test.ts": "clients",
-  "link-admission-wait.test.ts": "clients",
-  "link-fingerprint.test.ts": "clients",
-  "cli-link.test.ts": "cli",
-  "link-management-routes.test.ts": "server",
-  "link-compensation.test.ts": "clients",
-  "web-search-run-turn-loop.test.ts": "web-search",
-  "responses-run-turn-web-search.test.ts": "responses",
-  "server-combo-cooldown-recording.test.ts": "server",
-  "injection-routing-drift.test.ts": "codex-integration",
-  "injection-routing-healer.test.ts": "codex-integration",
-  "injection-routing-heal-apply.test.ts": "codex-integration",
-  "cli-start-routing-heal-wiring.test.ts": "cli",
-  "cli-status-codex-routing-drift.test.ts": "cli"
+  "deepseek-quota-currency.test.ts": "providers", "mimo-token-plan-capacity.test.ts": "providers",
+  "command-code-tool-text-prose-split.test.ts": "providers", "cli-effort-slug.test.ts": "cli",
+  "grok-47-build-fast-metadata.test.ts": "providers/xai", "grok-47-fast-model.test.ts": "providers/xai",
+  "grok-47-fast-model-wire.test.ts": "providers/xai", "client-link-connect.test.ts": "clients",
+  "client-link-relay.test.ts": "clients", "client-link-runtime.test.ts": "clients",
+  "link-routes.test.ts": "clients", "client-link-state.test.ts": "clients",
+  "client-link-status.test.ts": "clients", "client-link-teardown.test.ts": "clients",
+  "client-link-tunnel.test.ts": "clients", "link-ports.test.ts": "clients",
+  "injection-link-websocket.test.ts": "codex-integration", "link-supervisor.test.ts": "clients",
+  "link-status-projection.test.ts": "clients", "link-admission-wait.test.ts": "clients",
+  "link-fingerprint.test.ts": "clients", "cli-link.test.ts": "cli",
+  "link-management-routes.test.ts": "server", "link-compensation.test.ts": "clients",
+  "web-search-run-turn-loop.test.ts": "web-search", "responses-run-turn-web-search.test.ts": "responses",
+  "server-combo-cooldown-recording.test.ts": "server", "injection-routing-drift.test.ts": "codex-integration",
+  "injection-routing-healer.test.ts": "codex-integration", "injection-routing-heal-apply.test.ts": "codex-integration",
+  "cli-start-routing-heal-wiring.test.ts": "cli", "cli-status-codex-routing-drift.test.ts": "cli"
 }
diff --git a/tests/helpers/cli-capability-data.ts b/tests/helpers/cli-capability-data.ts
new file mode 100644
index 00000000000..5275556206b
--- /dev/null
+++ b/tests/helpers/cli-capability-data.ts
@@ -0,0 +1,221 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createScanner, LanguageVariant, SyntaxKind } from "typescript/unstable/ast";
+import { tokenize, type Token } from "./warmup-tokens";
+
+export const CAPABILITY_DATA_FILES = [
+  "capabilities.ts", "capabilities-base.ts", "capability-types.ts",
+  "capabilities-provider-models.ts",
+  "capabilities-accounts.ts",
+  "capabilities-agents-routing.ts",
+  "capabilities-integrations.ts",
+  "capabilities-observe-system.ts",
+  "capabilities-access-remote.ts",
+  "capabilities-lab.ts",
+
+] as const;
+
+type Edge = { target: string; kind: "import" | "export"; typeOnly: boolean };
+const ROLES: Readonly<Record<string, readonly string[]>> = {
+  "capabilities.ts": [
+    "import:value:capabilities-base.ts", "export:value:capabilities-base.ts",
+    "import:type:capability-types.ts", "export:type:capability-types.ts",
+    "import:value:capabilities-provider-models.ts",
+    "import:value:capabilities-accounts.ts",
+    "import:value:capabilities-agents-routing.ts",
+    "import:value:capabilities-integrations.ts",
+    "import:value:capabilities-observe-system.ts",
+    "import:value:capabilities-access-remote.ts",
+    "import:value:capabilities-lab.ts",
+
+  ],
+  "capabilities-base.ts": ["import:type:capability-types.ts"],
+  "capability-types.ts": [],
+  "capabilities-provider-models.ts": ["import:type:capability-types.ts"],
+  "capabilities-accounts.ts": ["import:type:capability-types.ts"],
+  "capabilities-agents-routing.ts": ["import:type:capability-types.ts"],
+  "capabilities-integrations.ts": ["import:type:capability-types.ts"],
+  "capabilities-observe-system.ts": ["import:type:capability-types.ts"],
+  "capabilities-access-remote.ts": ["import:type:capability-types.ts"],
+  "capabilities-lab.ts": ["import:type:capability-types.ts"],
+
+};
+
+function closingBrace(tokens: readonly Token[], start: number): number {
+  let depth = 0;
+  for (let i = start; i < tokens.length; i++) {
+    if (tokens[i].kind === SyntaxKind.OpenBraceToken) depth++;
+    if (tokens[i].kind === SyntaxKind.CloseBraceToken && --depth === 0) return i;
+  }
+  throw new Error("unclosed declaration");
+}
+
+/** Types owns only exported interface/type declarations, with no runtime initializer. */
+function checkTypes(tokens: readonly Token[]): void {
+  for (let i = 0; i < tokens.length;) {
+    if (tokens[i].kind === SyntaxKind.SemicolonToken) { i++; continue; }
+    if (tokens[i++].kind !== SyntaxKind.ExportKeyword) throw new Error("types role requires declarations only");
+    const kind = tokens[i++]?.kind;
+    if (kind === SyntaxKind.InterfaceKeyword) {
+      // This owner needs no extends clauses or computed members.
+      if (tokens[i++]?.kind !== SyntaxKind.Identifier || tokens[i]?.kind !== SyntaxKind.OpenBraceToken) {
+        throw new Error("unsupported types interface");
+      }
+      i = closingBrace(tokens, i) + 1;
+    } else if (kind === SyntaxKind.TypeKeyword) {
+      if (tokens[i++]?.kind !== SyntaxKind.Identifier || tokens[i++]?.kind !== SyntaxKind.EqualsToken) {
+        throw new Error("unsupported type alias");
+      }
+      while (i < tokens.length && tokens[i].kind !== SyntaxKind.SemicolonToken) i++;
+      if (i === tokens.length) throw new Error("unterminated type alias");
+    } else throw new Error("types role forbids runtime declarations");
+  }
+}
+
+/**
+ * Deliberately narrow expression grammar for metadata and the pure facade helpers.
+ * No computed member access or division is needed here. This closes whole syntax
+ * classes instead of decoding particular spellings of a require property. Brackets
+ * admit empty array/type suffixes and array literals only in these expression-start
+ * positions; other uses are unsupported, not evidence of a specific dependency.
+ *
+ * The shared lexer guesses regex versus division. Trust a regex token only after
+ * `=`, where a value must start: a division cannot legally occur there. Else refuse
+ * the ambiguous token without inspecting its swallowed body. Even benign division
+ * or a regex in another position is outside this boundary's admitted grammar.
+ */
+function checkMetadataExpressions(tokens: readonly Token[]): void {
+  const arrayStarts = new Set([
+    SyntaxKind.EqualsToken, SyntaxKind.ColonToken, SyntaxKind.CommaToken,
+    SyntaxKind.OpenBracketToken, SyntaxKind.OpenParenToken, SyntaxKind.ReturnKeyword,
+  ]);
+  for (let i = 0; i < tokens.length; i++) {
+    const kind = tokens[i].kind;
+    const previous = tokens[i - 1]?.kind;
+    if (kind === SyntaxKind.SlashToken || kind === SyntaxKind.SlashEqualsToken
+      || (kind === SyntaxKind.RegularExpressionLiteral && previous !== SyntaxKind.EqualsToken)) {
+      throw new Error("unsupported metadata expression: division or ambiguous regex position");
+    }
+    if (kind === SyntaxKind.OpenBracketToken
+      && tokens[i + 1]?.kind !== SyntaxKind.CloseBracketToken
+      && !arrayStarts.has(previous)) {
+      throw new Error("unsupported metadata expression: computed member or bracket position");
+    }
+  }
+}
+
+/**
+ * These data owners have no use for ambient host/loader bindings. Reserve their
+ * names in every identifier position, so aliases, destructuring and parameter
+ * bindings cannot hide where a loader came from. This intentionally also refuses
+ * benign shadowing, type names and unquoted property names using this vocabulary.
+ * Quoted keys, strings, template text and regex bodies remain ordinary data.
+ * It is a lexical contract, not scope analysis or an arbitrary-code sandbox.
+ */
+function checkHostIdentifiers(tokens: readonly Token[]): void {
+  const reserved = new Set([
+    "require", "module", "exports", "global", "globalThis", "Bun", "process",
+    "Deno", "window", "self", "this",
+  ]);
+  for (const token of tokens) {
+    if (token.kind !== SyntaxKind.Identifier
+      && !(token.kind >= SyntaxKind.FirstKeyword && token.kind <= SyntaxKind.LastKeyword)) continue;
+    let name = token.text;
+    if (name.includes("\\")) {
+      // Use the same native scanner's cooked value for escaped identifiers; the
+      // shared token helper intentionally only retains cooked string values.
+      const scanner = createScanner(true, LanguageVariant.Standard, name);
+      scanner.scan();
+      name = scanner.getTokenValue();
+    }
+    if (reserved.has(name)) throw new Error(`unsupported metadata host/loader identifier: ${name}`);
+  }
+}
+
+/**
+ * Read only the static named import/re-export shapes used by the enumerated data owners.
+ * Other load syntax fails closed, including type queries and require references.
+ * The shared TS7 lexer ignores comments, strings and regex bodies, while preserving
+ * code inside template substitutions. This checks dependencies, not arbitrary code.
+ */
+function edges(source: string, typesOnly: boolean): Edge[] {
+  const { tokens, unreadable } = tokenize(source);
+  if (unreadable.length) throw new Error(unreadable.join("; "));
+  checkMetadataExpressions(tokens);
+  checkHostIdentifiers(tokens);
+  const result: Edge[] = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.kind !== SyntaxKind.ImportKeyword && token.kind !== SyntaxKind.ExportKeyword) continue;
+    const kind = token.kind === SyntaxKind.ImportKeyword ? "import" : "export";
+    let cursor = i + 1;
+    const wholeType = tokens[cursor]?.kind === SyntaxKind.TypeKeyword;
+    if (wholeType) cursor++;
+    const next = tokens[cursor];
+    if (kind === "export" && next?.kind !== SyntaxKind.OpenBraceToken && next?.kind !== SyntaxKind.AsteriskToken) continue;
+    if (next?.kind !== SyntaxKind.OpenBraceToken) {
+      throw new Error("only static named imports/re-exports are allowed (no bare, side-effect or computed loads)");
+    }
+    const end = closingBrace(tokens, cursor);
+    let allType = end > cursor + 1;
+    for (let member = cursor + 1; member < end;) {
+      const inlineType = tokens[member]?.kind === SyntaxKind.TypeKeyword;
+      if (inlineType) member++;
+      allType &&= inlineType;
+      if (tokens[member++]?.kind !== SyntaxKind.Identifier) throw new Error("unsupported import/export member");
+      if (tokens[member]?.kind === SyntaxKind.AsKeyword) {
+        member++;
+        if (tokens[member++]?.kind !== SyntaxKind.Identifier) throw new Error("unsupported import/export alias");
+      }
+      if (member < end && tokens[member++]?.kind !== SyntaxKind.CommaToken) throw new Error("unsupported import/export clause");
+    }
+    cursor = end + 1;
+    // A local export does not load another module.
+    if (kind === "export" && tokens[cursor]?.kind !== SyntaxKind.FromKeyword) { i = end; continue; }
+    if (tokens[cursor++]?.kind !== SyntaxKind.FromKeyword || tokens[cursor]?.kind !== SyntaxKind.StringLiteral) {
+      throw new Error("unresolved import/export specifier");
+    }
+    result.push({ kind, target: tokens[cursor].value, typeOnly: wholeType || allType });
+    i = cursor;
+  }
+  if (typesOnly) checkTypes(tokens);
+  return result;
+}
+
+/** Same predicate for repository files and in-memory refusal fixtures. */
+export function capabilityDataBoundary(
+  directory: string,
+  read: (path: string) => string = path => readFileSync(path, "utf8"),
+): string[] {
+  const owners = new Map(CAPABILITY_DATA_FILES.map(name => [resolve(directory, name), name]));
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const errors: string[] = [];
+  function visit(path: string): void {
+    const name = owners.get(path);
+    if (!name) { errors.push(`outside data graph: ${path}`); return; }
+    if (visiting.has(path)) { errors.push(`cycle: ${name}`); return; }
+    if (visited.has(path)) return;
+    visiting.add(path);
+    try {
+      for (const edge of edges(read(path), name === "capability-types.ts")) {
+        if (!edge.target.startsWith("./") && !edge.target.startsWith("../")) {
+          errors.push(`${name}: bare dependency ${edge.target}`);
+          continue;
+        }
+        const target = resolve(dirname(path), edge.target.endsWith(".ts") ? edge.target : `${edge.target}.ts`);
+        const targetName = owners.get(target);
+        const role = `${edge.kind}:${edge.typeOnly ? "type" : "value"}:${targetName}`;
+        if (!ROLES[name].includes(role)) errors.push(`${name}: forbidden edge ${role} (${edge.target})`);
+        visit(target);
+      }
+    } catch (error) {
+      errors.push(`${name}: unreadable/unresolved: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    visiting.delete(path);
+    visited.add(path);
+  }
+  // Check every owner, even if a future facade accidentally stops referencing one.
+  for (const path of owners.keys()) visit(path);
+  return errors;
+}