diff --git a/src/cli/help.ts b/src/cli/help.ts
index 2a8f919bb..049c060ab 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -1,285 +1,10 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { findCommand } from "./registry";
 
 const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
 
-type HelpEntry = {
-  usage: string;
-  summary: string;
-  details?: string[];
-};
-
-const helpEntries: Record<string, HelpEntry> = {
-  init: { usage: "ocx init", summary: "Interactive setup for providers and Codex config injection." },
-  setup: { usage: "ocx setup", summary: "Interactive setup for providers and Codex config injection (alias of init)." },
-  start: { usage: "ocx start [--port <port>]", summary: "Start the proxy server and sync models to Codex." },
-  stop: { usage: "ocx stop", summary: "Stop the proxy and restore native Codex config." },
-  restore: {
-    usage: "ocx restore [back]",
-    summary: "Restore native Codex config without stopping the proxy; `restore back` re-points codex at the running proxy.",
-  },
-  eject: {
-    usage: "ocx eject [back]",
-    summary: "Restore native Codex config without stopping the proxy; `eject back` re-points codex at the running proxy.",
-  },
-  "recover-history": {
-    usage: "ocx recover-history --legacy-openai",
-    summary: "Explicitly recover pre-backup syncResumeHistory rows.",
-  },
-  uninstall: {
-    usage: "ocx uninstall",
-    summary: "Remove service/shim/config and restore native Codex.",
-    details: [
-      "Alias: ocx remove",
-      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
-    ],
-  },
-  remove: {
-    usage: "ocx remove",
-    summary: "Remove service/shim/config and restore native Codex.",
-    details: [
-      "Alias of: ocx uninstall",
-      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
-    ],
-  },
-  service: {
-    usage: "ocx service [install|start|stop|status|uninstall|remove]",
-    summary: "Run as a background service.",
-    details: [
-      "With no subcommand, installs/updates and starts the background service.",
-      "Use `ocx service status` to see diagnostics and log paths.",
-    ],
-  },
-  "codex-shim": {
-    usage: "ocx codex-shim <install|status|uninstall|remove>",
-    summary: "Auto-start the proxy when `codex` launches.",
-    details: ["Use `remove` as an alias for `uninstall`."],
-  },
-  tray: {
-    usage: "ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]",
-    summary: "Install and control the Windows status tray icon.",
-    details: [
-      "The tray starts at Windows login and provides one-click proxy controls.",
-      "Tray start/stop controls the icon only; use its menu to start or stop the proxy.",
-      "--no-start (install only) installs the tray without launching it immediately.",
-    ],
-  },
-  ensure: { usage: "ocx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
-  sync: {
-    usage: "ocx sync [--restart-codex]",
-    summary: "Fetch provider models and inject them into Codex config.",
-    details: [
-      "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
-      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
-    ],
-  },
-  "sync-cache": {
-    usage: "ocx sync-cache [--restart-codex]",
-    summary: "Refresh Codex's model cache from the active catalog.",
-    details: [
-      "Warns when Codex app-server processes still hold an in-memory model list.",
-      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
-    ],
-  },
-  status: { usage: "ocx status", summary: "Check proxy server status." },
-  doctor: { usage: "ocx doctor", summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability)." },
-  debug: {
-    usage: "ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>",
-    summary: "Show or toggle runtime provider, usage, injection, and Claude debug capture.",
-    details: [
-      "Provider: ocx debug provider on | off | status | reset | logs [-f]",
-      "Usage JSONL: ocx debug usage on | off | status | reset | logs [-f]",
-      "Env default: OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)",
-    ],
-  },
-  login: { usage: "ocx login <provider>", summary: "OAuth or API-key login for a provider." },
-  logout: { usage: "ocx logout <provider>", summary: "Remove a stored provider login." },
-  gui: { usage: "ocx gui", summary: "Open the opencodex dashboard." },
-  update: {
-    usage: "ocx update [--tag latest|preview]",
-    summary: "Update opencodex. Preview installs stay on the preview tag unless overridden.",
-  },
-  provider: {
-    usage: "ocx provider <list|add|edit|test|remove|show|set-default|selected|quota|presets|account-mode>",
-    summary: "Non-interactive provider management.",
-    details: [
-      "Subcommands: list, add/edit/test/remove/show, set-default, selected, quota, presets, account-mode",
-      "Registry providers are auto-configured by name. Custom providers need --adapter and --base-url.",
-      "Run `ocx provider --help` for full usage and examples.",
-    ],
-  },
-  account: {
-    usage: "ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|main> ...",
-    summary: "List and switch provider accounts and API-key pools (GUI parity).",
-    details: [
-      "list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).",
-      "current <provider>  Show the active account or key.",
-      "use <provider> <id> Switch the active credential; 'main' selects the Codex App login.",
-      "refresh <provider>  Force-refresh Codex or provider quota reports.",
-      "auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.",
-      "priority <provider> <id|main> [first|earlier|normal|later|last|-100..100|reset]  Selection order; omit the value to read it.",
-      "remove <provider> <id> --yes  Remove a stored account or key after an existence check.",
-      "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
-      "login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.",
-      "reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.",
-      "main <subcommand>     Manage the physical native Codex login separately from Pool routing.",
-      "Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.",
-      "A selection-order change applies from the next unbound request and never moves a bound thread.",
-    ],
-  },
-  models: {
-    usage: "ocx models <list|live|add|edit|remove|enable|disable|provider|selected|context|shadow> ...",
-    summary: "List models and manage custom (manually registered) models.",
-    details: [
-      "List available models from static config with no subcommand (liveModels may add more at runtime).",
-      "add: register a model the provider catalog does not advertise yet.",
-      "  --display-name <name>     Human label (no slashes).",
-      "  --context-window <tokens> e.g. 200000.",
-      "  --modalities text,image   Comma-separated (text|image|audio).",
-      "remove: delete a custom model by UUID or <provider>/<modelId>.",
-      "list-custom: show all custom models.",
-      "Changes apply immediately to a running proxy (catalog sync).",
-    ],
-  },
-  model: {
-    usage: "ocx model <subcommand>",
-    summary: "Alias of ocx models.",
-  },
-  combo: {
-    usage: "ocx combo <list|show|set|remove> ...",
-    summary: "Manage combo failover and round-robin virtual models.",
-    details: ["Alias hierarchy: ocx route combo ...", "Use --targets provider/model[:weight],provider/model[:weight]."],
-  },
-  route: {
-    usage: "ocx route combo <list|show|set|remove> ...",
-    summary: "Manage routing features; combo is currently the supported routing resource.",
-  },
-  agent: {
-    usage: "ocx agent <status|injection|effort|subagents|fallback|sidecar> ...",
-    summary: "Manage headless multi-agent, roster, effort, injection, and sidecar settings.",
-  },
-  observe: {
-    usage: "ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...",
-    summary: "Inspect proxy requests, usage, storage, memory, and debug data.",
-  },
-  logs: { usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Alias of ocx observe logs." },
-  usage: { usage: "ocx usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]", summary: "Alias of ocx observe usage." },
-  storage: { usage: "ocx storage [--json]", summary: "Alias of ocx observe storage." },
-  memory: { usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
-  access: {
-    usage: "ocx access <key|endpoints|models|test> ...",
-    summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
-  },
-  "api-key": { usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
-  export: {
-    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (opencode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code) wired to the running proxy.",
-    details: [
-      "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
-      "--out <path> writes the native config there and refuses to replace an existing file without --force.",
-      "The config never contains a real key; it carries a documented env reference or a non-secret loopback placeholder.",
-      "The destination path is printed for merging by hand — ocx never writes your real client config.",
-    ],
-  },
-  grok: { usage: "ocx grok <status|exclude|include|set|clear|apply> ...", summary: "Manage and apply the Grok Build model fence." },
-  integration: { usage: "ocx integration <claude|grok|client> ...", summary: "Manage supported client integrations." },
-  system: {
-    usage: "ocx system <status|settings|startup|diagnostics|sync|update> ...",
-    summary: "Manage headless runtime settings, startup, sync, diagnostics, and updates.",
-  },
-  config: {
-    usage: "ocx config <show|get|set|unset|validate|export|import> ...",
-    summary: "Inspect and safely modify validated OpenCodex configuration.",
-    details: ["Secrets are masked by show/get. Import requires --yes and validates before writing."],
-  },
-  claude: {
-    usage: "ocx claude [claude args...]",
-    summary: "Launch Claude Code wired to the proxy (env injection + gateway model discovery).",
-    details: [
-      "Ensures the proxy is running, then execs `claude` with ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN,",
-      "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 and model slots from config.claudeCode.",
-      "Routed models appear in the native /model picker with stable claude-opus-4-8-2026MMDD slot aliases (Claude Code >= 2.1.129).",
-      "Older versions: pick models via ANTHROPIC_MODEL or /model <id> directly (any string passes through).",
-      "User-exported ANTHROPIC_* variables always take precedence.",
-      "",
-      "Claude Desktop profile:",
-      "  ocx claude desktop [apply]                         Save and apply the four-family profile",
-      "  ocx claude desktop show [--json]                   Show routes, families, and defaults",
-      "  ocx claude desktop move <route> <family> [--default]",
-      "  ocx claude desktop default <family> <route|none>",
-      "  ocx claude desktop export <path|->                 Export versioned JSON (`-` = stdout)",
-      "  ocx claude desktop import <path> [--apply]         Validate and import JSON",
-      "Families: opus, fable, sonnet, haiku. New routes start in opus.",
-      "`none` is valid only when that family is empty.",
-      "Legacy apply flags remain supported: --static, --hybrid, --discovery-only.",
-      "",
-      "Claude Code settings: ocx claude config <status|set> ...",
-    ],
-  },
-  opencode: {
-    usage: "ocx opencode [opencode args...]",
-    summary: "Launch opencode wired to the proxy (runtime provider config).",
-    details: [
-      "Ensures the proxy is running, then execs `opencode` with the generated `provider.opencodex`",
-      "block injected through OpenCode's inline runtime layer (`OPENCODE_CONFIG_CONTENT`). Any",
-      "existing inline config in the environment is preserved and only `provider.opencodex` is",
-      "overwritten for this launch.",
-      "Global/project opencode.json may be read to warn about an existing provider.opencodex",
-      "override; on-disk files are never modified.",
-      "Routed models appear in the model picker as opencodex/<provider>/<model>.",
-      "Stop using `ocx opencode` and plain `opencode` behaves exactly as before.",
-    ],
-  },
-  restart: {
-    usage: "ocx restart",
-    summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
-  },
-  v2: {
-    usage: "ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>>",
-    summary: "Toggle the Codex multi_agent_v2 feature (multi-agent surface).",
-    details: [
-      "status                Show flag, multi-agent mode, and thread limit.",
-      "on | off              Enable/disable multi_agent_v2 (catalog resyncs).",
-      "mode <v1|default|v2>  Force all models to one surface, or respect upstream pins.",
-      "threads <n>           Set max_concurrent_threads_per_session (integer >= 1).",
-      "Flips preserve the active thread limit while moving between v1/v2 modes.",
-    ],
-  },
-  health: {
-    usage: "ocx health [--json]",
-    summary: "Check proxy health. Exits 0 if healthy, 1 otherwise.",
-    details: ["Use --json for structured output: {ok, pid, port}."],
-  },
-  ready: {
-    usage: "ocx ready [--json] [--wait [--timeout <seconds>]]",
-    summary: "Check post-sync readiness. Exits 0 only when ready.",
-    details: [
-      "Exact unauthenticated GET /readyz returns HTTP 200 when ready, or 503 with Retry-After: 1 for pending or failed.",
-      "Its sanitized HTTP identity is {service, version, uptime, pid, port, status}; /healthz is separate liveness, not readiness.",
-      "Default is a single identity-checked /readyz probe; old proxies without /readyz fail closed as unreachable.",
-      "--wait polls until ready or timeout, but exits immediately on terminal failed (default 45s, max 300s).",
-      "--timeout requires --wait and accepts a positive integer (1..300).",
-      "--json emits {ready, status, pid, port}; status is one of ready|pending|failed|unreachable.",
-      "Invalid or unknown arguments exit 64. Not-ready, pending, failed, timeout, and unreachable exit 1.",
-    ],
-  },
-  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).",
-    details: [
-      "status                Projection availability, schema versions, and row counts.",
-      "verdicts              Paginated derived compatibility verdicts with filters.",
-      "subjects              List subjects; subject <id> returns one typed subject.",
-      "observations          Paginated observation rows from the projection.",
-      "events                Event history; event <id> returns one safe typed event.",
-      "artifacts             Artifact metadata only (no content download).",
-      "catalog               Packaged protocol/live scenario catalog metadata.",
-      "Reads never rebuild the projection, trigger probes, or require the proxy.",
-    ],
-  },
-};
-
 function packageVersion(): string {
   const raw = readFileSync(join(repoRoot, "package.json"), "utf8");
   const parsed = JSON.parse(raw) as { version?: unknown };
@@ -352,7 +77,7 @@ export function hasHelpFlag(values: string[]): boolean {
 }
 
 export function printSubcommandUsage(name: string | undefined): void {
-  const entry = name ? helpEntries[name] : undefined;
+  const entry = name ? findCommand(name) : undefined;
   if (!entry) {
     console.error(`Unknown command: ${name ?? ""}`.trim());
     printUsage();
diff --git a/src/cli/registry.ts b/src/cli/registry.ts
new file mode 100644
index 000000000..1572cfddb
--- /dev/null
+++ b/src/cli/registry.ts
@@ -0,0 +1,384 @@
+export interface CliCommandEntry {
+  name: string;
+  aliases?: string[];
+  usage: string;
+  summary: string;
+  details?: string[];
+  hidden?: boolean;
+}
+
+export const CLI_COMMANDS: CliCommandEntry[] = [
+  {
+    name: "init",
+    aliases: ["setup"],
+    usage: "ocx init",
+    summary: "Interactive setup for providers and Codex config injection.",
+  },
+  {
+    name: "setup",
+    aliases: [],
+    usage: "ocx setup",
+    summary: "Interactive setup for providers and Codex config injection (alias of init).",
+  },
+  { name: "start", usage: "ocx start [--port <port>]", summary: "Start the proxy server and sync models to Codex." },
+  { name: "stop", usage: "ocx stop", summary: "Stop the proxy and restore native Codex config." },
+  {
+    name: "restore",
+    aliases: ["eject"],
+    usage: "ocx restore [back]",
+    summary: "Restore native Codex config without stopping the proxy; `restore back` re-points codex at the running proxy.",
+  },
+  {
+    name: "eject",
+    aliases: [],
+    usage: "ocx eject [back]",
+    summary: "Restore native Codex config without stopping the proxy; `eject back` re-points codex at the running proxy.",
+  },
+  {
+    name: "recover-history",
+    usage: "ocx recover-history --legacy-openai",
+    summary: "Explicitly recover pre-backup syncResumeHistory rows.",
+  },
+  {
+    name: "uninstall",
+    aliases: ["remove"],
+    usage: "ocx uninstall",
+    summary: "Remove service/shim/config and restore native Codex.",
+    details: [
+      "Alias: ocx remove",
+      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
+    ],
+  },
+  {
+    name: "remove",
+    aliases: [],
+    usage: "ocx remove",
+    summary: "Remove service/shim/config and restore native Codex.",
+    details: [
+      "Alias of: ocx uninstall",
+      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
+    ],
+  },
+  {
+    name: "service",
+    usage: "ocx service [install|start|stop|status|uninstall|remove]",
+    summary: "Run as a background service.",
+    details: [
+      "With no subcommand, installs/updates and starts the background service.",
+      "Use `ocx service status` to see diagnostics and log paths.",
+    ],
+  },
+  {
+    name: "codex-shim",
+    usage: "ocx codex-shim <install|status|uninstall|remove>",
+    summary: "Auto-start the proxy when `codex` launches.",
+    details: ["Use `remove` as an alias for `uninstall`."],
+  },
+  {
+    name: "tray",
+    usage: "ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]",
+    summary: "Install and control the Windows status tray icon.",
+    details: [
+      "The tray starts at Windows login and provides one-click proxy controls.",
+      "Tray start/stop controls the icon only; use its menu to start or stop the proxy.",
+      "--no-start (install only) installs the tray without launching it immediately.",
+    ],
+  },
+  { name: "ensure", usage: "ocx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
+  {
+    name: "sync",
+    usage: "ocx sync [--restart-codex]",
+    summary: "Fetch provider models and inject them into Codex config.",
+    details: [
+      "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
+      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+    ],
+  },
+  {
+    name: "sync-cache",
+    usage: "ocx sync-cache [--restart-codex]",
+    summary: "Refresh Codex's model cache from the active catalog.",
+    details: [
+      "Warns when Codex app-server processes still hold an in-memory model list.",
+      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+    ],
+  },
+  { name: "status", usage: "ocx status", summary: "Check proxy server status." },
+  {
+    name: "doctor",
+    usage: "ocx doctor",
+    summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability).",
+  },
+  {
+    name: "debug",
+    usage: "ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>",
+    summary: "Show or toggle runtime provider, usage, injection, and Claude debug capture.",
+    details: [
+      "Provider: ocx debug provider on | off | status | reset | logs [-f]",
+      "Usage JSONL: ocx debug usage on | off | status | reset | logs [-f]",
+      "Env default: OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)",
+    ],
+  },
+  { name: "login", usage: "ocx login <provider>", summary: "OAuth or API-key login for a provider." },
+  { name: "logout", usage: "ocx logout <provider>", summary: "Remove a stored provider login." },
+  { name: "gui", usage: "ocx gui", summary: "Open the opencodex dashboard." },
+  {
+    name: "update",
+    usage: "ocx update [--tag latest|preview]",
+    summary: "Update opencodex. Preview installs stay on the preview tag unless overridden.",
+  },
+  {
+    name: "provider",
+    usage: "ocx provider <list|add|edit|test|remove|show|set-default|selected|quota|presets|account-mode>",
+    summary: "Non-interactive provider management.",
+    details: [
+      "Subcommands: list, add/edit/test/remove/show, set-default, selected, quota, presets, account-mode",
+      "Registry providers are auto-configured by name. Custom providers need --adapter and --base-url.",
+      "Run `ocx provider --help` for full usage and examples.",
+    ],
+  },
+  {
+    name: "account",
+    usage: "ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|main> ...",
+    summary: "List and switch provider accounts and API-key pools (GUI parity).",
+    details: [
+      "list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).",
+      "current <provider>  Show the active account or key.",
+      "use <provider> <id> Switch the active credential; 'main' selects the Codex App login.",
+      "refresh <provider>  Force-refresh Codex or provider quota reports.",
+      "auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.",
+      "priority <provider> <id|main> [first|earlier|normal|later|last|-100..100|reset]  Selection order; omit the value to read it.",
+      "remove <provider> <id> --yes  Remove a stored account or key after an existence check.",
+      "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
+      "login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.",
+      "reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.",
+      "main <subcommand>     Manage the physical native Codex login separately from Pool routing.",
+      "Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.",
+      "A selection-order change applies from the next unbound request and never moves a bound thread.",
+    ],
+  },
+  {
+    name: "models",
+    aliases: ["model"],
+    usage: "ocx models <list|live|add|edit|remove|enable|disable|provider|selected|context|shadow> ...",
+    summary: "List models and manage custom (manually registered) models.",
+    details: [
+      "List available models from static config with no subcommand (liveModels may add more at runtime).",
+      "add: register a model the provider catalog does not advertise yet.",
+      "  --display-name <name>     Human label (no slashes).",
+      "  --context-window <tokens> e.g. 200000.",
+      "  --modalities text,image   Comma-separated (text|image|audio).",
+      "remove: delete a custom model by UUID or <provider>/<modelId>.",
+      "list-custom: show all custom models.",
+      "Changes apply immediately to a running proxy (catalog sync).",
+    ],
+  },
+  {
+    name: "model",
+    aliases: [],
+    usage: "ocx model <subcommand>",
+    summary: "Alias of ocx models.",
+  },
+  {
+    name: "combo",
+    usage: "ocx combo <list|show|set|remove> ...",
+    summary: "Manage combo failover and round-robin virtual models.",
+    details: ["Alias hierarchy: ocx route combo ...", "Use --targets provider/model[:weight],provider/model[:weight]."],
+  },
+  {
+    name: "route",
+    usage: "ocx route combo <list|show|set|remove> ...",
+    summary: "Manage routing features; combo is currently the supported routing resource.",
+  },
+  {
+    name: "agent",
+    usage: "ocx agent <status|injection|effort|subagents|fallback|sidecar> ...",
+    summary: "Manage headless multi-agent, roster, effort, injection, and sidecar settings.",
+  },
+  {
+    name: "observe",
+    usage: "ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...",
+    summary: "Inspect proxy requests, usage, storage, memory, and debug data.",
+  },
+  { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Alias of ocx observe logs." },
+  {
+    name: "usage",
+    usage: "ocx usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]",
+    summary: "Alias of ocx observe usage.",
+  },
+  { name: "storage", usage: "ocx storage [--json]", summary: "Alias of ocx observe storage." },
+  { name: "memory", usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
+  {
+    name: "access",
+    usage: "ocx access <key|endpoints|models|test> ...",
+    summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
+  },
+  { name: "api-key", usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
+  {
+    name: "export",
+    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (opencode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code) wired to the running proxy.",
+    details: [
+      "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
+      "--out <path> writes the native config there and refuses to replace an existing file without --force.",
+      "The config never contains a real key; it carries a documented env reference or a non-secret loopback placeholder.",
+      "The destination path is printed for merging by hand — ocx never writes your real client config.",
+    ],
+  },
+  {
+    name: "grok",
+    usage: "ocx grok <status|exclude|include|set|clear|apply> ...",
+    summary: "Manage and apply the Grok Build model fence.",
+  },
+  { name: "integration", usage: "ocx integration <claude|grok|client> ...", summary: "Manage supported client integrations." },
+  {
+    name: "system",
+    usage: "ocx system <status|settings|startup|diagnostics|sync|update> ...",
+    summary: "Manage headless runtime settings, startup, sync, diagnostics, and updates.",
+  },
+  {
+    name: "config",
+    usage: "ocx config <show|get|set|unset|validate|export|import> ...",
+    summary: "Inspect and safely modify validated OpenCodex configuration.",
+    details: ["Secrets are masked by show/get. Import requires --yes and validates before writing."],
+  },
+  {
+    name: "claude",
+    usage: "ocx claude [claude args...]",
+    summary: "Launch Claude Code wired to the proxy (env injection + gateway model discovery).",
+    details: [
+      "Ensures the proxy is running, then execs `claude` with ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN,",
+      "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 and model slots from config.claudeCode.",
+      "Routed models appear in the native /model picker with stable claude-opus-4-8-2026MMDD slot aliases (Claude Code >= 2.1.129).",
+      "Older versions: pick models via ANTHROPIC_MODEL or /model <id> directly (any string passes through).",
+      "User-exported ANTHROPIC_* variables always take precedence.",
+      "",
+      "Claude Desktop profile:",
+      "  ocx claude desktop [apply]                         Save and apply the four-family profile",
+      "  ocx claude desktop show [--json]                   Show routes, families, and defaults",
+      "  ocx claude desktop move <route> <family> [--default]",
+      "  ocx claude desktop default <family> <route|none>",
+      "  ocx claude desktop export <path|->                 Export versioned JSON (`-` = stdout)",
+      "  ocx claude desktop import <path> [--apply]         Validate and import JSON",
+      "Families: opus, fable, sonnet, haiku. New routes start in opus.",
+      "`none` is valid only when that family is empty.",
+      "Legacy apply flags remain supported: --static, --hybrid, --discovery-only.",
+      "",
+      "Claude Code settings: ocx claude config <status|set> ...",
+    ],
+  },
+  {
+    name: "opencode",
+    usage: "ocx opencode [opencode args...]",
+    summary: "Launch opencode wired to the proxy (runtime provider config).",
+    details: [
+      "Ensures the proxy is running, then execs `opencode` with the generated `provider.opencodex`",
+      "block injected through OpenCode's inline runtime layer (`OPENCODE_CONFIG_CONTENT`). Any",
+      "existing inline config in the environment is preserved and only `provider.opencodex` is",
+      "overwritten for this launch.",
+      "Global/project opencode.json may be read to warn about an existing provider.opencodex",
+      "override; on-disk files are never modified.",
+      "Routed models appear in the model picker as opencodex/<provider>/<model>.",
+      "Stop using `ocx opencode` and plain `opencode` behaves exactly as before.",
+    ],
+  },
+  {
+    name: "restart",
+    usage: "ocx restart",
+    summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
+  },
+  {
+    name: "v2",
+    usage: "ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>>",
+    summary: "Toggle the Codex multi_agent_v2 feature (multi-agent surface).",
+    details: [
+      "status                Show flag, multi-agent mode, and thread limit.",
+      "on | off              Enable/disable multi_agent_v2 (catalog resyncs).",
+      "mode <v1|default|v2>  Force all models to one surface, or respect upstream pins.",
+      "threads <n>           Set max_concurrent_threads_per_session (integer >= 1).",
+      "Flips preserve the active thread limit while moving between v1/v2 modes.",
+    ],
+  },
+  {
+    name: "health",
+    usage: "ocx health [--json]",
+    summary: "Check proxy health. Exits 0 if healthy, 1 otherwise.",
+    details: ["Use --json for structured output: {ok, pid, port}."],
+  },
+  {
+    name: "ready",
+    usage: "ocx ready [--json] [--wait [--timeout <seconds>]]",
+    summary: "Check post-sync readiness. Exits 0 only when ready.",
+    details: [
+      "Exact unauthenticated GET /readyz returns HTTP 200 when ready, or 503 with Retry-After: 1 for pending or failed.",
+      "Its sanitized HTTP identity is {service, version, uptime, pid, port, status}; /healthz is separate liveness, not readiness.",
+      "Default is a single identity-checked /readyz probe; old proxies without /readyz fail closed as unreachable.",
+      "--wait polls until ready or timeout, but exits immediately on terminal failed (default 45s, max 300s).",
+      "--timeout requires --wait and accepts a positive integer (1..300).",
+      "--json emits {ready, status, pid, port}; status is one of ready|pending|failed|unreachable.",
+      "Invalid or unknown arguments exit 64. Not-ready, pending, failed, timeout, and unreachable exit 1.",
+    ],
+  },
+  {
+    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).",
+    details: [
+      "status                Projection availability, schema versions, and row counts.",
+      "verdicts              Paginated derived compatibility verdicts with filters.",
+      "subjects              List subjects; subject <id> returns one typed subject.",
+      "observations          Paginated observation rows from the projection.",
+      "events                Event history; event <id> returns one safe typed event.",
+      "artifacts             Artifact metadata only (no content download).",
+      "catalog               Packaged protocol/live scenario catalog metadata.",
+      "Reads never rebuild the projection, trigger probes, or require the proxy.",
+    ],
+  },
+  {
+    name: "__refresh-version",
+    hidden: true,
+    usage: "ocx __refresh-version [preview|latest]",
+    summary: "Hidden detached helper: refresh the cached latest version.",
+  },
+  {
+    name: "__tray-start",
+    hidden: true,
+    usage: "ocx __tray-start",
+    summary: "Hidden internal: start the tray proxy.",
+  },
+  {
+    name: "__tray-restart",
+    hidden: true,
+    usage: "ocx __tray-restart",
+    summary: "Hidden internal: restart the tray proxy.",
+  },
+  {
+    name: "__startup-health",
+    hidden: true,
+    usage: "ocx __startup-health",
+    summary: "Hidden internal: print startup health JSON.",
+  },
+  {
+    name: "__tray-host",
+    hidden: true,
+    usage: "ocx __tray-host",
+    summary: "Hidden internal: run the Windows tray host.",
+  },
+  {
+    name: "__gui-update-worker",
+    hidden: true,
+    usage: "ocx __gui-update-worker <jobId> [channel] [restart]",
+    summary: "Hidden internal: run the GUI update worker.",
+  },
+];
+
+export function findCommand(name: string): CliCommandEntry | undefined {
+  // Exact-name wins so alias-name entries (setup/eject/remove/model) keep their
+  // own help text; the canonical entry is the fallback for alias lookups.
+  return CLI_COMMANDS.find(entry => entry.name === name)
+    ?? CLI_COMMANDS.find(entry => entry.aliases?.includes(name));
+}
+
+export function commandNames(): string[] {
+  return CLI_COMMANDS.map(entry => entry.name);
+}
diff --git a/tests/cli-registry.test.ts b/tests/cli-registry.test.ts
new file mode 100644
index 000000000..8de647331
--- /dev/null
+++ b/tests/cli-registry.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CLI_COMMANDS, findCommand } from "../src/cli/registry";
+
+const cliSource = readFileSync(join(import.meta.dir, "../src/cli/index.ts"), "utf8");
+
+/** Top-level switch case names in src/cli/index.ts.
+ * Top-level cases sit at 2-4 space indent; the nested codex-shim sub-switch
+ * cases (install/status/uninstall/remove) sit at 6+ and are not commands. */
+function topLevelSwitchCases(source: string): string[] {
+  const names: string[] = [];
+  for (const match of source.matchAll(/^ {2,4}case "([^"]+)"/gm)) names.push(match[1]!);
+  return names;
+}
+
+describe("CLI command registry parity", () => {
+  const cases = topLevelSwitchCases(cliSource);
+  const caseSet = new Set(cases);
+  const registryNames = new Set(CLI_COMMANDS.flatMap(entry => [entry.name, ...(entry.aliases ?? [])]));
+
+  test("every top-level switch case resolves in the registry", () => {
+    // `help`/`--help`/`-h` are head-handled pseudo-cases, not commands.
+    const headHandled = new Set(["help", "--help", "-h"]);
+    const unresolvable = cases.filter(name => !headHandled.has(name) && !registryNames.has(name));
+    expect(unresolvable).toEqual([]);
+  });
+
+  test("every registry entry has a top-level switch case", () => {
+    const missing = CLI_COMMANDS
+      .filter(entry => !caseSet.has(entry.name))
+      .map(entry => entry.name);
+    expect(missing).toEqual([]);
+  });
+
+  test("alias entries keep their own help entry (exact name wins over alias)", () => {
+    // `setup`, `eject`, `remove`, `model` each have their own help text; an
+    // alias lookup must not shadow them with the canonical entry.
+    expect(findCommand("setup")?.name).toBe("setup");
+    expect(findCommand("eject")?.name).toBe("eject");
+    expect(findCommand("remove")?.name).toBe("remove");
+    expect(findCommand("model")?.name).toBe("model");
+    expect(findCommand("init")?.name).toBe("init");
+    expect(findCommand("uninstall")?.name).toBe("uninstall");
+    expect(findCommand("models")?.name).toBe("models");
+  });
+
+  test("canonical entries declare the alias pairs", () => {
+    const aliasesOf = (name: string): string[] => CLI_COMMANDS.find(entry => entry.name === name)?.aliases ?? [];
+    expect(aliasesOf("init")).toContain("setup");
+    expect(aliasesOf("restore")).toContain("eject");
+    expect(aliasesOf("uninstall")).toContain("remove");
+    expect(aliasesOf("models")).toContain("model");
+  });
+
+  test("hidden entries are flagged and do not appear in help lookups by accident", () => {
+    const hidden = CLI_COMMANDS.filter(entry => entry.hidden);
+    expect(hidden.map(entry => entry.name).sort()).toEqual([
+      "__gui-update-worker",
+      "__refresh-version",
+      "__startup-health",
+      "__tray-host",
+      "__tray-restart",
+      "__tray-start",
+    ]);
+    for (const entry of hidden) {
+      expect(caseSet.has(entry.name)).toBe(true);
+      expect(findCommand(entry.name)?.name).toBe(entry.name);
+    }
+  });
+
+  test("entry names are unique", () => {
+    const names = CLI_COMMANDS.map(entry => entry.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});