import { EXPORT_CLIENT_IDS } from "../clients/client-ids";

export interface CliCommandEntry {
  name: string;
  aliases?: string[];
  usage: string;
  summary: string;
  details?: string[];
  hidden?: boolean;
}

export const CLI_COMMANDS: CliCommandEntry[] = [
  {
    name: "codex-provider",
    usage: "ocx codex-provider <status|allow <id> [--yes]|revoke <id>>",
    summary: "Explicitly allow or revoke local routing management for a custom Codex provider.",
    details: ["Consent is bound to the selected CODEX_HOME and provider ID. Only base_url is managed; transport settings and history are preserved."],
  },
  {
    name: "message",
    usage: "ocx message <sessions|send|enable|disable|status|hosts|serve> [options]",
    summary: "Discover loaded Codex sessions and queue messages locally or through explicit SSH peers.",
    details: ["Remote listeners/tunnels require explicit foreground serve; no daemon start. queued is submission, not processing; never replay an unknown send."],
  },
  {
    name: "chatgpt",
    usage: "ocx chatgpt <launch|restore|status>",
    summary: "Experimental ChatGPT app-server shim (macOS only, default off).",
    details: ["Experimental launch requires chatgptDesktop.appServerShim: true; restore removes its launcher."],
  },
  {
    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>] [--socks5 [host:port] | --socks5-off]",
    summary: "Start the proxy server and sync models to Codex.",
    details: [
      "--socks5 [host:port]  Route outbound provider traffic through SOCKS5 (default 127.0.0.1:10808). Saved as config.proxy.",
      "--socks5-off          Clear a saved SOCKS5 outbound proxy from config.proxy.",
    ],
  },
  {
    name: "stop",
    usage: "ocx stop [--json]",
    summary: "Stop the proxy; preserve connected-client integrations, restore native Codex config for standalone owners.",
    details: [
      "--json keeps the stop path unchanged and prints one structured summary document on stdout; human output moves to stderr.",
      "Exit codes are identical with and without --json: 0, 1, 79 (history cleanup incomplete), 80 (teardown deferred).",
    ],
  },
  {
    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.",
    details: [
      "--remove-codex-provider-table  Also remove [model_providers.opencodex] when a paginated home made restore keep it. Conversations tagged opencodex stop opening.",
    ],
  },
  {
    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.",
    details: [
      "--remove-codex-provider-table  Also remove [model_providers.opencodex] when a paginated home made restore keep it. Conversations tagged opencodex stop opening.",
    ],
  },
  {
    name: "recover-history",
    usage: "ocx recover-history (--legacy-openai | --ocx-compaction <thread-id>) --yes",
    summary: "Recover legacy provider metadata or one OpenCodeX-compacted thread for native replay.",
  },
  {
    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|repair|restart|start|stop|status|uninstall|remove|claim]",
    summary: "Run as a background service.",
    details: [
      "With no subcommand, installs when absent or repairs an existing service.",
      "`repair` refreshes the definition and reloads the manager only when something changed, so repairing a healthy service is not an outage.",
      "`restart` is the same refresh but always restarts: on macOS an unchanged, already-loaded job is kickstarted in place. Healthy Windows tasks are reused, while stale definitions may re-register and elevate.",
      "Use `ocx service status` to see diagnostics and log paths. On macOS it reports four states:",
      "loaded from the current plist, loaded from an OLDER plist (repair), not loaded (repair), or",
      "`launchd state could not be verified` -- which is an unanswerable probe, NOT a down service.",
      "Data-plane token: nothing has to be exported by hand. On a non-loopback hostname install/repair uses",
      "OPENCODEX_API_AUTH_TOKEN when set, otherwise reuses the existing owner-only ~/.opencodex/service-api-token,",
      "otherwise generates one; the launch wrapper reads that file at start and the value never enters a plist,",
      "a unit file, or argv. An ADMIN token in OPENCODEX_API_AUTH_TOKEN is refused -- unset it and rerun.",
      "Repair and restart never ask for the environment variable again once the token file exists.",
    ],
  },
  {
    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 (deprecated in favor of the desktop app).",
    details: [
      "The tray starts at Windows login and provides one-click proxy controls.",
      "Deprecated: the OpenCodex desktop app provides the tray on Windows, macOS, and Linux; `ocx tray` remains for installs without the desktop app.",
      "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: "connect",
    usage: "ocx connect <url> [--management-url <url>] (--pairing-code-stdin | --admin-token-stdin) [--clients codex,claude] [--management-transport direct|relay] [--catalog-timeout <seconds>] [--no-sync]",
    summary: "Connect this machine to a remote OpenCodex hub without persisting the one-time authority.",
    details: [
      "Status: ocx connect status [--json]",
      "Rotate or recover: ocx connect rotate (--pairing-code-stdin | --admin-token-stdin) [--json]",
      "Revoke while connected: ocx connect revoke --admin-token-stdin [--json]",
      "Machine resources: /api/machine/status, /api/machine/shim, /api/machine/clients, /api/machine/sync, /api/machine/disconnect, and the fixed /api/machine/hub-relay namespace.",
      "Remote browser self-logout uses /api/session/logout from the GUI; it is distinct from client disconnect and key revocation.",
      "Credentials are accepted only through stdin; argv and environment credential forms are not supported.",
    ],
  },
  {
    name: "link",
    usage: "ocx link <port|issue|status|revoke|reconnect|cleanup>",
    summary: "Allocate and manage a loopback remote home link.",
    details: [
      "Port: ocx link port [--json]",
      "Issue: ocx link issue --alias <alias> --tunnel-port <port> [--json]",
      "Status: ocx link status [--json]",
      "Revoke: ocx link revoke --link-id <id> [--force --yes] [--json]",
      "Reconnect: ocx link reconnect --link-id <id> [--json]",
      "Cleanup: ocx link cleanup [--link-id <id>] [--json]",
      "Issue, status, revoke, and reconnect use the running proxy's loopback management API and admin token.",
    ],
  },
  {
    name: "remote-workspace",
    usage: "ocx remote-workspace <pair|agent|status|hub>",
    summary: "Manage this workspace executor or inspect the selected Hub.",
    details: [
      "Pair: ocx remote-workspace pair <hub-url> --pairing-code-stdin --root <absolute-path> [--toolchain-root <absolute-directory>] [--executor-helper <absolute-file>] [--name <device-name>]",
      "Agent: ocx remote-workspace agent",
      "Status: ocx remote-workspace status [--json]",
      "Hub: ocx remote-workspace hub <status|runtimes|sessions> [--json]",
      "Codex, Claude Code, Pi, provider logins, and API keys remain on the hub; only workspace tools execute here.",
    ],
  },
  {
    name: "disconnect",
    usage: "ocx disconnect [--keep-catalog] [--json]",
    summary: "Restore local client state offline and clear the remote-hub connection.",
  },
  {
    name: "sync",
    usage: "ocx sync [--expect-link <linkId> | --expect-hub-key <apiKeyId>] [--restart-codex] [--restart-app-server-only]",
    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 restarts the app-servers AND fully quits and relaunches the Codex desktop app on macOS, Linux and Windows, after catalog/cache writes or a committed configuration change. It ends live conversations.",
      "--restart-app-server-only keeps the narrow behaviour: SIGTERM to matching app-server / code-mode-host processes, desktop app left running. It wins over --restart-codex when both are given.",
      "--restart-desktop-app is a deprecated alias of --restart-codex and prints a notice.",
      "--expect-link <linkId> syncs only when this machine is a connected Remote Link Child of that link (ocx connect status --json reports link.linkId); --expect-hub-key <apiKeyId> does the same for a hub client's key. The check runs under the lock that chooses the sync path.",
      "Any other state (disconnected, another link or key, the other client kind, a pending key rotation, connect or disconnect) changes nothing, never syncs local providers, exits 5, and prints {\"phase\":\"child_link_mismatch\"|\"hub_client_mismatch\",\"reason\":...} as the last stderr line. A malformed or repeated flag exits 2.",
    ],
  },
  {
    name: "sync-cache",
    usage: "ocx sync-cache [--restart-codex] [--restart-app-server-only]",
    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 restarts the app-servers AND fully quits and relaunches the Codex desktop app on macOS, Linux and Windows, so its model picker re-reads the catalog. It ends live conversations.",
      "--restart-app-server-only keeps the narrow behaviour: SIGTERM to matching app-server / code-mode-host processes, desktop app left running. It wins over --restart-codex when both are given.",
      "--restart-desktop-app is a deprecated alias of --restart-codex and prints a notice.",
    ],
  },
  {
    name: "catalog",
    usage: "ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex] [--restart-app-server-only]",
    summary: "Install a validated remote /v1/catalog snapshot into Codex.",
    details: [
      "Authentication is read only from the named environment variable and sent as a Bearer token.",
      "HTTPS is required except for loopback HTTP; redirects are refused.",
      "The catalog and models_cache.json are coordinated under the Codex catalog write lock.",
    ],
  },
  { 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).",
    details: [
      "Default mode is observe-only and reports the native-write coordinator state and exact path.",
      "After stopping the proxy/service, `--recover-zero-byte-coordinator --yes` moves only a proven zero-byte coordinator to a same-directory backup.",
    ],
  },
  {
    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> [--headless]",
    summary: "OAuth or API-key login for a provider.",
    details: [
      "--headless (anthropic, anthropic2): no browser and no local port; approve in any browser and paste the displayed code.",
      "Codex/ChatGPT: ocx login codex runs the Codex account-pool login (same flow as ocx account login codex).",
      "That one needs a running proxy; the OAuth and API-key providers log in locally.",
      "'chatgpt' and 'openai' are the same route; an OpenAI platform API key is 'ocx login openai-apikey'.",
    ],
  },
  { name: "logout", usage: "ocx logout <provider>", summary: "Remove a stored provider login." },
  {
    name: "gui",
    usage: "ocx gui [pair --origin <browser-origin> [--json]]",
    summary: "Open the opencodex dashboard or create a secret single-use remote pairing grant.",
    details: [
      "Pairing requires an explicit allowed --origin; there is no localhost or config-derived default.",
      "The printed grant is secret, single-use, short-lived, and must not be persisted.",
    ],
  },
  {
    name: "hub",
    usage: "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]\n  ocx hub disable [--revoke-clients --client-key <id> ...] [--json]",
    summary: "Invite another machine, or disable hub mode in one validated config write.",
    details: [
      "Topology: a hub serves ONE port. Remote machines dial `hostname:port` with their own per-client",
      "key; the hub's own local processes dial `127.0.0.1:<same port>` with no credential, through the",
      "loopback companion listener enabled by `unauthenticatedLoopbackListener: {\"enabled\": true}`.",
      "The browser-facing management plane is separate: a loopback-only ingress published by an",
      "operator-owned HTTPS frontend (Tailscale Serve) and advertised as hub.managementPublicOrigin.",
      "",
      "Nothing needs to be exported by hand. `ocx service install` provisions an owner-only data-plane",
      "token at ~/.opencodex/service-api-token and the launch wrapper reads it at start; the value never",
      "enters a plist, a unit file, argv, or the environment you typed in. Never copy that file to another",
      "machine -- every client gets its own revocable key from the pairing exchange.",
      "",
      "invite requires a running hub and mints a single-use, short-lived pairing code through the same",
      "attested local route `ocx gui pair` uses, then prints the exact command to run on the other",
      "machine. The code is bound to hub.managementPublicOrigin and to the connecting machine's local",
      "browser origin (`http://localhost:10100` unless corsAllowOrigins names another loopback origin);",
      "the bound origin is always printed, and a different one names the port the client needs.",
      "--data-url overrides the advertised data origin; hub.dataPublicOrigin is the persistent form, and",
      "the fallback is http://<bind address>:<port>. A loopback or wildcard bind has no such address, so",
      "invite refuses instead of advertising http://localhost:<port>, which would tell the other machine",
      "to dial itself and spend the code.",
      "--management-url is a CONFIRMATION, not an override: the grant is bound to",
      "hub.managementPublicOrigin, so a differing value is refused instead of printed.",
      "--clients chooses which client configs the printed ocx connect line will point at the hub.",
      "--json emits { code, expiresAt, dataUrl, managementUrl, command }. Do not persist the code.",
      "Hub state, including the data token and the companion listener, is reported by `ocx status`.",
    ],
  },
  {
    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 <subcommand>",
    summary: "Non-interactive provider management.",
    details: [
      "Subcommands:",
      "  list                  List configured and available providers",
      "  add <name>            Add a provider (registry or custom)",
      "  edit <name>           Edit live provider fields",
      "  pacing <name>         Read/edit live request pacing rules",
      "  snapshot              Read a non-secret provider editor baseline",
      "  apply                 Apply edited providers with baseline conflict checks",
      "  test <name>           Test the provider's upstream model endpoint",
      "  remove <name>         Remove a configured provider",
      "  show <name>           Show provider config details",
      "  set-default <name>    Change the default provider",
      "  add/remove/set-default support --live; live removal also requires --yes.",
      "  selected <name>       Show or set the provider model allowlist",
      "  quota                 Show provider quota reports",
      "  resets                Show recently detected quota resets",
      "  presets               List GUI provider presets",
      "  account-mode <mode>   Set OpenAI Codex pool/direct mode",
      "",
      "Examples:",
      "  ocx provider list",
      "  ocx provider list --jsonl",
      "  ocx provider presets --json",
      "  ocx provider add anthropic --api-key <key>",
      "  ocx provider add my-ollama --adapter openai-chat --base-url http://localhost:11434/v1",
      "  ocx provider show anthropic --json",
      "  ocx provider pacing anthropic --json",
      "  ocx provider snapshot --json",
      "  ocx provider set-default anthropic",
      "  ocx provider edit xai --xai-chat on   # opt Grok 4.5/4.6 into Chat Completions",
      "  ocx provider edit xai --xai-chat off  # use Responses again",
      "  ocx provider remove my-ollama",
      "",
      "Registry providers are auto-configured by name. Custom providers need --adapter and --base-url.",
    ],
  },
  {
    name: "account",
    usage: "ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|grok-reset-coupons|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.",
      "pool <provider>          Read/edit runtime-supported pool policy.",
      "credits openai ...       Explicit paid-credit-after-limit policy; separate from displaying balances.",
      "use-remaining openai <id|main> <on|off|status>  Use included quota up to its limit.",
      "quota-activation openai  Enable/disable one account reset-window refresh policy.",
      "anthropic-reset-grants   Read grant status only; consumption remains in the dashboard.",
      "login supports explicit browser/add-account options only for applicable flows; human verification remains required.",
      "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.",
      "grok-reset-coupons [<id>] [--consume --yes] Inspect or redeem Grok reset coupons.",
      "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: "alias",
    usage: "ocx alias <list|set|rm|defaults> ...",
    summary: "Manage short provider and model names.",
  },
  {
    name: "models",
    aliases: ["model"],
    usage: "ocx models <list|live|add|edit|remove|enable|disable|provider|selected|preset|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/remove support --live for the selected proxy; live or JSON removal requires --yes.",
      "Local add/remove JSON reports saved state and opportunistic sync; no proxy keeps the save successful/pending.",
      "display-name <provider/raw-model> --set <label> or --clear changes an exact upstream model label.",
      "order status/set/reset manages routed picker order; reset native-inclusive saved order before replacement.",
      "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: "advisor",
    usage: "ocx advisor <status|on|off|consent|set> ...",
    summary: "Inspect and configure the advisor sidecar (expert consultation for routed workers).",
    details: [
      "ocx advisor and ocx advisor status read the resolved settings; use --json for machine-readable output.",
      "ocx advisor on requires current context-sharing consent. Pass --ack-context-sharing to record consent v1 and enable. ocx advisor off disables the sidecar without granting consent.",
      "ocx advisor consent records consent v1 after printing the disclosure. ocx advisor consent --revoke removes it and stops task-context transfer.",
      "ocx advisor set updates --model, --effort, --policy and --timeout-ms; the model may be any routable model string (bare native, provider/model, or account-qualified). set does not grant consent.",
      "policy manual consults only when the worker calls the synthetic advisor tool; policy preflight also attempts one automatic consultation per task with a stable conversation identity, once the task shows orientation evidence. Without a stable identity, each eligible request may trigger another consultation. Both require current consent before any task context is sent.",
    ],
  },
  {
    name: "companion",
    usage: "ocx companion <show|set|reset|usage|timeline> ...",
    summary: "Inspect companion settings, filtered usage and timeline, or change preferences.",
    details: [
      "ocx companion and ocx companion show read settings; use --json for machine-readable output.",
      "ocx companion set accepts one or more key=value assignments; values are parsed as JSON when possible.",
      "ocx companion reset restores the default settings.",
      "ocx companion usage reads today and 30-day totals with saved model/provider filters; unavailable ranges return partial output and exit 1.",
      "ocx companion timeline reads buckets; --model selects models and --hide-provider excludes providers.",
    ],
  },
  {
    name: "combo",
    usage: "ocx combo <list|show|set|remove> ...",
    summary: "Manage combo virtual models and routing strategies.",
    details: ["Alias hierarchy: ocx route combo ...", "Use --targets provider/model[:weight],provider/model[:weight]."],
  },
  {
    name: "route",
    usage: "ocx route <combo|policy> <subcommand>",
    summary: "Manage combo routing and routing profiles.",
  },
  {
    name: "effort",
    usage: "ocx effort [status|<level>|set|clear|model] [--main <level|->] [--subagent <level|->] [--injection <level|->] [--json]",
    summary: "Inspect and configure reasoning effort caps and defaults.",
    details: [
      "With no arguments or `status`, displays effective effort caps, injection effort, and supported rungs.",
      "`ocx effort <level>` (or `set --main <level>`) sets the global/main-agent reasoning ceiling.",
      "`--subagent <level>` sets the hard ceiling for delegated sub-agent turns.",
      "`ocx effort clear` (or `set --main - --subagent -`) removes main and subagent caps but preserves injection effort; use `ocx effort set --injection -` to clear it.",
      "`ocx effort model <provider/model|model>` inspects a model's configured ladder, disabled status, and wire mappings.",
      "Works both online (via live proxy API) and offline (modifies persisted config safely with atomic writes).",
    ],
  },
  {
    name: "fallback",
    usage: "ocx fallback <status|off|on|clear|local> [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
    summary: "Turn model and provider fallback off or on per scope, and record per-device local fallback.",
    details: [
      "A refused fallback answers fallback_refused with the status of the failure that triggered it, and names the command that allows it.",
      "Precedence: a device set to off always refuses; otherwise route, then provider, then global; unset allows.",
      "Rotation among the accounts or keys of one provider pool is not a fallback and is not governed here.",
      "Live proxy only. On a Remote Link Child, status reads the Home; writes are refused. Run write commands on the Home.",
    ],
  },
  {
    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: "inspect",
    usage: "ocx inspect <config|catalog|routing-analytics|pacing|key-providers|codex-prompt|client-config|star|windows-tray> ...",
    summary: "Read effective config, catalog, analytics, pacing, and the generated client-config snippet.",
    details: [
      "`inspect star` reads the repository star status only. Starring uses your GitHub identity and is available from the dashboard alone.",
    ],
  },
  {
    name: "logs",
    usage: "ocx logs [filters] [--follow] [--json|--jsonl|--events]; ocx logs history [selectors] [--cursor <token>] [--json|--jsonl]; ocx logs get <request-id> [--json]",
    summary: "Read or follow request logs.",
    details: [
      "Default reads the recent ring. `history` pages the derived index with a resumable cursor; `get` reads one canonical row; `explain` is the route-decision view.",
    ],
  },
  {
    name: "usage",
    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--top <1-1000>] [--json]; ocx usage compare [--range <today|1d|7d|30d>] [--json]",
    summary: "Report token usage and estimated cost (alias of ocx observe usage).",
    details: [
      "`compare` reads the current named range and the previous equal window; `--range all` is refused.",
    ],
  },
  {
    name: "storage",
    usage: "ocx storage <report|cleanup|trash|policy> ...",
    summary: "Storage report, archived-session cleanup, trash restore, and the cleanup policy.",
    details: [
      "A bare `ocx storage` prints the report, as it did when this was an alias of `observe storage`.",
      "`cleanup` previews by default and only deletes under --yes; `trash restore` and `policy run` also require --yes.",
    ],
  },
  { name: "memory", usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
  {
    name: "access",
    usage: "ocx access <key|endpoints|models|test|audio> ...",
    summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
    details: [
      "Key rotation start uses POST /api/keys/rotate and returns the replacement secret once.",
      "Commit uses POST /api/keys/rotate/commit; abort uses DELETE /api/keys/rotate with the returned rotation id.",
      "key rename changes a masked key's name without clearing its scopes.",
      "test --api-key-stdin uses one supplied data key; it never substitutes management or enrolled credentials.",
      "audio transcribe/live-check use explicit piped key input and may use provider quota; authorize the operation first.",
    ],
  },
  { name: "api-key", usage: "ocx api-key <list|get|create|set|rename|rotate|remove> ...", summary: "Alias of ocx access key." },
  {
    name: "api",
    usage: "ocx api <protocols|explain|policy> ...",
    summary: "Inspect protocol paths, preview a request path, and read or change the protocol policy.",
    details: [
      "protocols [--provider <name>]   Contract version, API surfaces, protocol settings and feature vocabulary.",
      "explain --model <id> --inbound <responses|chat|messages> [--feature <key>]...   Preview the request path; sends nothing upstream.",
      "policy                          Read the protocol policy; with --messages, --unrepresentable or --rollout <switch>=<on|off> it changes config.",
      "Every rollout switch defaults off except antigravityDirect. `ocx api policy` writes only when a setting flag is given.",
    ],
  },
  {
    name: "export",
    usage: `ocx export --client <${EXPORT_CLIENT_IDS.join("|")}> [--model-names <alias|routed>] [--json] [--out <path>] [--force]`,
    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Command Code, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid, Qoder, Qoder CN, WorkBuddy, WorkBuddy AI, Gentle Shell, T3 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.",
      "Cline exports a two-document bundle: settings for providers.json and catalog for sibling models.json. Use integration client enable --client cline for a journaled write.",
      "Droid exports documented customModels for settings.json; use integration client enable --client droid for a journaled write.",
      "Gentle Shell uses its persistent selected home; use integration client enable --client gentle-shell for a journaled write, or Pi for link/shared homes.",
      "T3 Code exports providerInstances.opencodex for settings.json, a Claude provider instance routed through the proxy; use integration client enable --client t3code for a journaled write.",
      "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.",
      "Hermes and Command Code accept --model-names alias|routed; explicit naming uses a passive cached roster and can refuse while cold or stale. Omission keeps the existing routed export flow without changing managed policy.",
    ],
  },
  {
    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|native> ...",
    summary: "Manage supported client integrations, and the native client toggles.",
    details: [
      "`native` shows or flips the native Claude/Claude Desktop/Codex/Grok toggles; the other subcommands manage the reversible file integrations.",
      "client preview shows a proposed change; enable/disable/restore accept an optional --plan-fingerprint.",
      "client history remove requires --yes; client sync --client aside refreshes managed Aside profiles.",
      "native cursor status/local-installer are reads; installer lookup does not install anything.",
    ],
  },
  {
    name: "system",
    usage: "ocx system <status|health|settings|startup|diagnostics|sync|codex-app-server|codex-restart|update|codex-cli-update> ...",
    summary: "Manage headless runtime settings, health, startup, sync, diagnostics, OpenCodex updates, and Codex CLI update plans and jobs.",
    details: [
      "system update manages OpenCodex itself.",
      "system health reads authenticated service and spend-ledger diagnostics; root health remains liveness.",
      "ocx system codex-cli-update check [--json]",
      "ocx system codex-cli-update attest [--json]",
      "ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]",
      "ocx system codex-cli-update plan [--channel latest] [--json]",
      "ocx system codex-cli-update apply --plan-id <32-hex> --yes [--request-id <key>] [--json]",
      "ocx system codex-cli-update status <job-id> [--json]",
      "check and attest make no package-registry request, do not execute Codex or npm, and write nothing. plan adds a registry query and a process-table read and mutates no application state (temporary isolated npm files only, removed best-effort).",
    ],
  },
  {
    name: "config",
    usage: "ocx config [show|get|set|unset|validate|export|import] ...",
    summary: "Inspect and safely modify validated OpenCodex configuration.",
    details: [
      "show is the default: ocx config [show] [--json] [--source]. Flags alone also display the local configuration without a running proxy.",
      "--json may precede an explicit action without changing which action runs.",
      "--source is only supported for show and includes diagnostic source, error, and warning fields.",
      "Secrets are masked by show/get. Import requires --yes and validates before writing.",
    ],
  },
  {
    name: "claude",
    usage: "ocx claude [claude args...]",
    summary: "Launch Claude Code through the proxy, with native fallback when Claude routing is disabled.",
    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.",
      "When Claude routing is explicitly disabled, it launches natively after removing proven OpenCodex-owned proxy state.",
      "Routed models appear in the native /model picker with stable claude-opus-4-8-YYYYMMDD slot aliases,",
      "where the year runs 2026-2035 and 2026 slots are allocated first (Claude Code >= 2.1.129).",
      "Older versions: pick models via ANTHROPIC_MODEL or /model <id> directly (any string passes through).",
      "User-exported ANTHROPIC_* variables take precedence for routed launches; native fallback removes only proven OpenCodex-owned proxy values.",
      "",
      "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 status [--json]                 Show applied state, drift, and health",
      "  ocx claude desktop bind <picker-id> <route>        First-party: serve a Code tab picker model with a route",
      "  ocx claude desktop unbind <picker-id>              Remove a first-party binding",
      "  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",
      "  ocx claude desktop profile show [--json]           Read the running proxy's profile",
      "  ocx claude desktop profile import <file|-> [--json] Save the running profile without applying",
      "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: "codex",
    usage: "ocx codex [codex args...]",
    summary: "Launch Codex through the local proxy's routing, passing through when Codex routing is disabled.",
    details: [
      "Mirrors `ocx claude` on Codex's config-owned wiring channel: ensures the proxy is running,",
      "then execs `codex` unchanged. Routing itself stays config-owned (the injected `openai_base_url`",
      "in ~/.codex/config.toml); a launch never rewrites a config file.",
      "For verified local routing, a missing OPENCODEX_API_AUTH_TOKEN is filled from ~/.opencodex/service-api-token, the same",
      "injection the `codex` autostart shim performs.",
      "--help/-h, --version/-V, and Codex-internal subcommands (login, doctor, help, ...) skip the",
      "proxy ensure and pass the environment through unchanged, keeping the shim's argv grammar.",
      "No injected routing: informational notice, native exec, no ensure.",
      "Foreign gateway routing (custom-local/custom-remote): warning, native exec, that route untouched.",
      "Unverifiable routing: warning, and the proxy ensure is still attempted.",
      "Unknown routing never adds a service token; token-file overrides and management credentials are not used for client injection.",
      "A fresh token is loaded only for allowlisted argv, no HTTP(S)/ALL proxy or CODEX_*/OPENAI_*/AZURE_OPENAI_* env overrides",
      "(canonical CODEX_HOME is allowed), and verified home/config/system ownership and managed transport.",
      "Other inputs (including -c/--config, -p/--profile and resume/fork) withhold it with a value-free diagnostic.",
      "If the ensure fails, one stderr line is printed and launch continues subject to executable verification.",
      "Only a matched autostart wrapper launches its backing Codex directly; unknown state requires a verified bypass.",
      "Unverifiable or obsolete wrappers refuse with exit 1 and start no Codex; run `ocx codex-shim install`.",
      "Stop using `ocx codex` and plain `codex` behaves exactly as before.",
    ],
  },
  {
    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`",
      "and `providers.opencodex` blocks injected through OpenCode's inline runtime layer",
      "(`OPENCODE_CONFIG_CONTENT`). Any existing inline config in the environment is preserved",
      "and only `provider.opencodex` and `providers.opencodex` are overwritten for this launch.",
      "V1 receives reasoning-effort variant maps; V2 receives native variant arrays for the same declared choices and defaults.",
      "Global/project opencode.json may be read to warn about an existing provider.opencodex or",
      "providers.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: "mcode",
    usage: "ocx mcode [mcode args...]",
    summary: "Launch MiniMax Code through its managed OpenCodex provider.",
    details: [
      "First connect the reversible file integration: ocx integration client enable --client mcode",
      "The launcher verifies that custom_provider.opencodex targets the current loopback proxy before starting MCode.",
      "Select custom_provider:opencodex/<model> from MCode's model picker.",
    ],
  },
  {
    name: "mmx",
    usage: "ocx mmx text <chat|repl> [mmx args...]",
    summary: "Launch MiniMax CLI text commands through the proxy.",
    details: [
      "Only the official MMX Anthropic-compatible text surface is proxied.",
      "Use plain mmx for MiniMax-native image, video, speech, music, vision, search, quota, auth, config, file, and update commands.",
      "The wrapper isolates ~/.mmx credentials and refuses --api-key/--base-url overrides.",
    ],
  },
  {
    name: "zcode",
    usage: "ocx zcode [status|enable|disable|history|restore] [--json]",
    summary: "Connect ZCode (Z.ai desktop client) to the proxy via its managed provider.",
    details: [
      "Alias of ocx integration client <sub> --client zcode.",
      "enable manages ~/.zcode/v2/provider_config.json with schemaVersion 1; if the store is absent, it writes the legacy provider.opencodex block into ~/.zcode/v2/config.json.",
      "A surviving owned legacy block prevents switching stores. Run `ocx zcode disable` before enabling the current store. Unknown store schemas are refused.",
      "ZCode reads its config at startup — restart ZCode after enable/disable.",
      "Select OpenCodex Proxy/<provider>/<model> from ZCode's model picker.",
    ],
  },
  {
    name: "commandcode",
    usage: "ocx commandcode [status|show|list|enable|disable|history|journal|restore --op <opId>] [--json]",
    summary: "Connect Command Code CLI to the proxy via its managed provider.",
    details: [
      "Alias of ocx integration client <sub> --client commandcode.",
      "enable manages the opencodex block under the existing provider or providers root in ~/.commandcode/providers.json; disable removes only that block.",
      "Command Code reads providers on startup.",
      "`restore --op <opId>` replays the exact previous managed block; take the id from `ocx commandcode history`.",
    ],
  },
  {
    name: "cmd",
    usage: "ocx cmd [status|show|list|enable|disable|history|journal|restore --op <opId>] [--json]",
    summary: "Alias of ocx commandcode.",
  },
  {
    name: "restart",
    usage: "ocx restart",
    summary: "Request a graceful restart of the verified running proxy, preserving routing.",
    details: [
      "If no proxy is running, use the normal `ocx ensure` start policy, including the Codex autostart setting.",
      "Unverifiable running targets are refused without a stop/start fallback.",
      "Restarting an older proxy from this newer CLI requires standalone macOS/Linux proxies; supervised, shared, foreground, or unverifiable targets are refused.",
      "For a service-managed update, run `ocx service restart`; for a desktop-managed update, restart through the OpenCodex desktop app.",
    ],
  },
  {
    name: "v2",
    usage: "ocx v2 <status|on|off|mode <v1|default|v2>|keep-native-v1 <on|off>|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.",
      "keep-native-v1 <on|off>  Under mode v2, keep ChatGPT-native models on v1.",
      "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: "capabilities",
    usage: "ocx capabilities [--json] [--mutating-only] [--route <path>]",
    summary: "List the declared CLI capabilities and the management routes they drive.",
    details: [
      "The machine-readable surface index: start here when driving ocx programmatically instead of parsing help text.",
      "--route <path> answers the inverse question: which commands drive this management route.",
    ],
  },
  {
    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: "resolve",
    usage: "ocx resolve [--json]",
    summary: "Emit the resolved config home, effective port, and identity-checked proxy liveness as one JSON document.",
    details: [
      "Machine surface for embedding shells: it replaces a second home/port/liveness implementation beside the CLI.",
      "The port is the live listener's port when an opencodex proxy answers, otherwise the configured port (default 10100).",
      "Liveness is three-valued: live, absent-proven (every recorded and configured endpoint definitively dead), or unknown — unknown exits 1 and never reads as absent.",
      "--json emits one versioned document (schema ocx-resolve/1); the default prints two human lines.",
      "Exit 0 carries a trustworthy verdict; exit 1 means the CLI could not resolve (invalid config or undecidable liveness) and callers must refuse to guess.",
      "Any unknown argument exits 64 before preflight side effects.",
    ],
  },
  {
    name: "lab",
    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.",
      "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.",
      "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.",
    ],
  },
  {
    name: "__refresh-version",
    hidden: true,
    usage: "ocx __refresh-version [preview|latest]",
    summary: "Hidden detached helper: refresh the cached latest version.",
  },
  {
    name: "__update-badge",
    hidden: true,
    usage: "ocx __update-badge",
    summary: "Hidden internal: print cached package update badge JSON.",
  },
  {
    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);
}