@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/capabilities-provider-models.ts

@@ -0,0 +1,302 @@
+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 a provider locally or explicitly to the running proxy.",
+    usage: "ocx provider add <name> [--adapter <id>] [--base-url <url>] [--responses-path <path>] [--auth-mode <key|forward|oauth|local>] [--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 | --live] [--json]",
+    routes: [{"method":"GET","path":"/api/providers"},{"method":"GET","path":"/api/provider-presets"},{"method":"POST","path":"/api/providers"}],
+    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":"Local only: perform requested Codex sync, including in JSON mode; saved-but-unsynced failures remain nonzero."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."},{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local configuration behavior."},{"name":"--responses-path","value":"string","summary":"Relative upstream Responses path; no scheme, query or fragment."},{"name":"--auth-mode","value":"string","summary":"Explicit key, forward, oauth or local auth mode."}],
+    details: ["Without --live, saves local configuration; --sync reports its actual disposition and needsSync, never fabricated client application. --live cannot be combined with --sync.","Live add reads the target roster and presets. An observed existing row requires --force; POST remains upsert, so the preflight is not atomic create-only protection.","Canonical OpenAI uses the target preset unchanged; transport/auth/model overrides are refused in live add. No local registry fallback when a needed target preset is missing.","Keep real credentials out of argv and agent transcripts; this does not authorize credential capture."],
+  },
+  {
+    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 local provider or explicitly delete it from the running proxy.",
+    usage: "ocx provider remove <name> [--json]; ocx provider remove <name> --live --yes [--json]",
+    routes: [{"method":"DELETE","path":"/api/providers"}],
+    mutates: true,
+    json: "envelope",
+    flags: [{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local configuration behavior."},{"name":"--yes","value":"boolean","summary":"Required with --live for provider and dependent custom-model/account cleanup."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
+    details: ["Local removal preserves its existing refusal for the current default and has no --yes option.","Live removal uses one server DELETE. The server can choose a replacement default and clean custom models, context caps and OAuth accounts; dependency/last-provider refusals stay authoritative.","No local fallback, multi-step deletion or automatic retry. A saved result with failed catalog convergence exits nonzero without claiming rollback."],
+  },
+  {
+    command: ["provider","set-default"],
+    summary: "Select the default provider locally or explicitly on the running proxy.",
+    usage: "ocx provider set-default <name> [--live] [--json]",
+    routes: [{"method":"PATCH","path":"/api/providers"}],
+    mutates: true,
+    json: "envelope",
+    flags: [{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local configuration behavior."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
+    details: ["Omission of --live retains local save/no-op semantics. Live sends only setDefault:true; disabled/unknown providers are refused by the server. This operation does not claim client synchronization."],
+  },
+  {
+    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>] [--upstream-http-version <http1.1|->] [--fast <on|off>] [--context-window <tokens|->] [--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."},{"name":"--upstream-http-version","value":"string","summary":"http1.1 pins HTTP/1.1; - clears the override."},{"name":"--fast","value":"string","summary":"on or off; false is an explicit edit."},{"name":"--context-window","value":"string","summary":"Positive safe integer provider context limit; - clears, zero is invalid."}],
+    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.","Management errors use safe fixed provider diagnostics; catalog failures retain the saved receipt and a nonzero exit."],
+  },
+  {
+    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 locally or explicitly on the running proxy.",
+    usage: "ocx models add <provider> <modelId> [--display-name <name>] [--context-window <tokens>] [--modalities <text,image,audio>] [--reasoning-efforts <levels|->] [--default-reasoning-effort <level|->] [--live] [--json]",
+    routes: [{"method":"POST","path":"/api/custom-models"}],
+    mutates: true,
+    json: "envelope",
+    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."},{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local custom-model behavior."},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
+    details: ["Without --live, saves locally and opportunistically syncs only if a proxy is available. No proxy keeps the save successful with needsSync:true; attempted failure/refusal is nonzero. JSON is one safe save/sync receipt.","Live add sends the same metadata to the server and returns its stored custom identity plus catalog outcome. Empty reasoning ladder differs from omitted/inherited metadata. No local fallback."],
+  },
+  {
+    command: ["models","remove"],
+    summary: "Remove an exact custom model locally or on the selected proxy.",
+    usage: "ocx models remove <customId|provider/modelId> [--yes] [--live] [--json]",
+    routes: [{"method":"GET","path":"/api/custom-models"},{"method":"DELETE","path":"/api/custom-models/{id}"}],
+    mutates: true,
+    json: "envelope",
+    flags: [{"name":"--yes","value":"boolean","summary":"Required for live or JSON deletion; local text mode retains its interactive confirmation."},{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local custom-model behavior."},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
+    details: ["Live selection uses the complete target custom roster and an exact stored ID or unambiguous provider/raw selector. Display labels, ID prefixes and encoded/raw collisions never choose a deletion target.","One encoded stored-ID DELETE; no alternative-ID retry, local fallback or revision protection. Local JSON saves/syncs retain the same opportunistic policy as add."],
+  },
+  {
+    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." }],
+  },
+  {
+    command: ["provider","pacing"],
+    usage: "ocx provider pacing <name> [--json]; ocx provider pacing <name> [--enabled <on|off>] [--rpm <number>] [--min-interval-ms <integer>] [--max-concurrent <integer>] [--json]; ocx provider pacing <name> --file <FILE|-> [--json]",
+    summary: "Read request pacing rules/status or explicitly replace the configured block.",
+    routes: [{"method":"GET","path":"/api/config"},{"method":"GET","path":"/api/provider-request-pacing"},{"method":"PATCH","path":"/api/providers"}],
+    flags: [{"name":"--enabled","value":"string","summary":"on or off; numeric changes never implicitly enable."},{"name":"--rpm","value":"number","summary":"Fractional requests per minute, from 1/60 to 60000."},{"name":"--min-interval-ms","value":"number","summary":"Positive integer delay, at most 3600000."},{"name":"--max-concurrent","value":"number","summary":"Positive integer concurrency cap."},{"name":"--file","value":"string","summary":"Complete rules JSON, or - for bounded non-TTY stdin; exclusive with scalar flags."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Read returns {provider,rules,status}; rules:null means no configured block, not an unavailable target.","Scalar edits preserve model rules observed from the pinned config; PATCH replaces the block and can overwrite an intervening edit. Use snapshot/apply for public-baseline CAS.","File mode validates a complete non-null rules block and writes without a prior rule read. Pacing limits reject zero."],
+  },
+  {
+    command: ["provider","snapshot"],
+    usage: "ocx provider snapshot [--json]",
+    summary: "Read the non-secret provider editor snapshot from the running proxy.",
+    routes: [{"method":"GET","path":"/api/config"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Emits exactly {defaultProvider,providers}, validating the canonical editor DTO after removing only GUI display markers. Unexpected secret/unknown fields fail closed.","Save this JSON as the baseline for apply; it is not raw config export and carries no cross-invocation target identity. Use the intended host/context."],
+  },
+  {
+    command: ["provider","apply"],
+    usage: "ocx provider apply --baseline <FILE|-> --file <FILE|-> [--yes] [--json]",
+    summary: "Apply a provider editor document with the server public-baseline conflict check.",
+    routes: [{"method":"PUT","path":"/api/providers"}],
+    flags: [{"name":"--baseline","value":"string","summary":"Original non-secret provider snapshot.","required":true},{"name":"--file","value":"string","summary":"Edited next snapshot.","required":true},{"name":"--yes","value":"boolean","summary":"Required for removals or renames within the submitted provider roster."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
+    mutates: true,
+    json: "payload",
+    details: ["Both documents must contain exactly defaultProvider and providers, with no credential/derived/unknown fields. At most one source may be stdin; each input and the complete serialized body are bounded to 4 MiB, with a 30-second read deadline.","Sends one {baseline,next} PUT. Stale baseline is exit 5; no automatic refresh, rebase, retry or local fallback.","Batch removal preserves the server batch contract and does not promise single-provider DELETE OAuth cleanup. Saved-but-unconverged catalog outcomes remain visible and nonzero."],
+  },
+  {
+    command: ["models","display-name"],
+    usage: "ocx models display-name <provider/raw-model> (--set <text> | --clear) [--json]",
+    summary: "Set or clear one raw upstream model display-name override.",
+    routes: [{"method":"PUT","path":"/api/providers/{provider}/model-display-names"}],
+    flags: [{"name":"--set","value":"string","summary":"Nonblank display label; exclusive with --clear."},{"name":"--clear","value":"boolean","summary":"Send null to clear the override."},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Split only the first provider slash; the remaining model ID is raw upstream identity, not a guessed public alias or encoded suffix.","A recognized saved-but-failed catalog HTTP503 retains its safe receipt and exits1; no retry or rollback claim."],
+  },
+  {
+    command: ["models","order","status"],
+    usage: "ocx models order status [--json]",
+    summary: "Read saved picker order, routed candidates and featured state.",
+    routes: [{"method":"GET","path":"/api/subagent-models"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
+    mutates: false,
+    json: "envelope",
+    details: ["Preserves native IDs in saved order. pickerAvailable is routed-only; unknown featured state is not an empty successful roster."],
+  },
+  {
+    command: ["models","order","set"],
+    usage: "ocx models order set (--models <csv> | --mode <default|alphabetical|provider|most-used>) [--json]",
+    summary: "Replace the routed picker order with an explicit list or sort mode.",
+    routes: [{"method":"GET","path":"/api/subagent-models"},{"method":"GET","path":"/api/models"},{"method":"GET","path":"/api/usage"},{"method":"PUT","path":"/api/subagent-models"}],
+    flags: [{"name":"--models","value":"string","summary":"Complete unique routed candidate permutation, preserving the exact featured prefix; exclusive with --mode."},{"name":"--mode","value":"string","summary":"default clears; alphabetical, provider and most-used compute complete routed orders."},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Manual/preset replacement refuses a native-inclusive saved order until explicit reset/default. It never edits the featured models/force fields.","Manual mode rechecks settings and identities before PUT and refuses observed drift; this is not server CAS. Raw/encoded ambiguities and missing identities refuse before writing.","Most-used reads all/all usage, uses requested model identities and refuses incomplete evidence. Presets retain unranked candidates. A saved receipt does not prove client convergence."],
+  },
+  {
+    command: ["models","order","reset"],
+    usage: "ocx models order reset [--json]",
+    summary: "Clear saved picker ordering and its mode.",
+    routes: [{"method":"PUT","path":"/api/subagent-models"}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
+    mutates: true,
+    json: "envelope",
+    details: ["Sends only pickerOrder:null and pickerOrderMode:null. Explicitly clears native-inclusive order as well; does not change featured models or force selection."],
+  },
+];