@bitkyc08/opencodex 2.76.0 → 2.77.0

package/src/cli/gui.ts

@@ -1,5 +1,5 @@
 import type { OcxConfig } from "../types";
-import { canonicalGuiBrowserOrigin } from "../lib/gui-pair-capability";
+import { canonicalGuiBrowserOrigin, standaloneGuiPairingOrigin } from "../lib/gui-pair-capability";
 import { findLiveProxy, type LiveProxy } from "../server/proxy-liveness";
 import {
   requestBoundGuiPairingGrant,
@@ -23,7 +23,7 @@ export interface GuiCommandDeps extends RuntimeApiDeps {
 }
 
 function allowedPairingOrigin(origin: string, config: OcxConfig): boolean {
-  if (config.runtimeRole !== "hub") return false;
+  if (config.runtimeRole !== "hub") return standaloneGuiPairingOrigin(config) === origin;
   if (canonicalGuiBrowserOrigin(config.hub?.managementPublicOrigin) === origin) return true;
   return (config.corsAllowOrigins ?? []).some(value => canonicalGuiBrowserOrigin(value) === origin);
 }
@@ -62,7 +62,7 @@ export async function runGuiCommand(args: string[], deps: GuiCommandDeps): Promi
   }
   const config = deps.loadConfig();
   if (!allowedPairingOrigin(canonicalOrigin, config)) {
-    console.error("The pairing origin is not enabled by hub.managementPublicOrigin or corsAllowOrigins.");
+    console.error("Pairing requires the standalone configured literal loopback origin, or an allowed hub origin.");
     return 1;
   }
   const target = await (deps.findLiveProxy ?? findLiveProxy)();
@@ -70,6 +70,11 @@ export async function runGuiCommand(args: string[], deps: GuiCommandDeps): Promi
     console.error("No running attested OpenCodex proxy is available for GUI pairing.");
     return 1;
   }
+  if ((config.runtimeRole ?? "standalone") === "standalone"
+    && (target.port !== config.port || (target.hostname ?? "127.0.0.1") !== (config.hostname ?? "127.0.0.1"))) {
+    console.error("Standalone pairing requires the running proxy to use its configured loopback address and port.");
+    return 1;
+  }
   const result = await (deps.requestPairingGrant ?? requestBoundGuiPairingGrant)(target, canonicalOrigin, {
     ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
   });

package/src/cli/help-catalog.ts

@@ -0,0 +1,84 @@
+import { CAPABILITIES, type Capability } from "./capabilities";
+import { CLI_COMMANDS, findCommand, type CliCommandEntry } from "./registry";
+
+export type HelpResolution =
+  | { kind: "entry"; entry: CliCommandEntry; canonicalName: string; children: readonly Capability[] }
+  | { kind: "capability"; path: string[]; capability: Capability }
+  | { kind: "prefix"; path: string[]; children: readonly Capability[] }
+  | { kind: "models-context"; path: string[] }
+  | { kind: "unavailable"; path: string[]; parent?: string[] };
+
+function startsWithPath(command: readonly string[], prefix: readonly string[]): boolean {
+  return prefix.length <= command.length && prefix.every((token, index) => token === command[index]);
+}
+
+const DOCUMENTED_PATHS: readonly (readonly string[])[] = [
+  ...CAPABILITIES.filter(capability => !findCommand(capability.command[0])?.hidden).map(capability => capability.command),
+  ["models", "context"],
+];
+const MAX_DOCUMENTED_DEPTH = Math.max(...DOCUMENTED_PATHS.map(path => path.length));
+
+function canonicalEntry(entry: CliCommandEntry): CliCommandEntry {
+  return CLI_COMMANDS.find(candidate => candidate.aliases?.includes(entry.name)) ?? entry;
+}
+
+export interface HelpRecoveryCandidate {
+  names: string[];
+  path: string[];
+}
+
+/** Matching names may include aliases; destinations are always catalog-owned. */
+export function helpRecoveryCandidates(parent: readonly string[] = []): HelpRecoveryCandidate[] {
+  const candidates = new Map<string, HelpRecoveryCandidate>();
+  if (parent.length === 0) {
+    for (const entry of CLI_COMMANDS) {
+      if (entry.hidden) continue;
+      const canonical = canonicalEntry(entry);
+      if (canonical.hidden) continue;
+      const candidate = candidates.get(canonical.name) ?? { names: [], path: [canonical.name] };
+      candidate.names = [...new Set([...candidate.names, entry.name, ...(entry.aliases ?? [])])];
+      candidates.set(canonical.name, candidate);
+    }
+  } else {
+    if (parent.length >= MAX_DOCUMENTED_DEPTH) return [];
+    const entry = findCommand(parent[0]);
+    if (!entry || entry.hidden) return [];
+    const prefix = [canonicalEntry(entry).name, ...parent.slice(1)];
+    for (const documented of DOCUMENTED_PATHS) {
+      if (documented.length <= prefix.length || !startsWithPath(documented, prefix)) continue;
+      const path = documented.slice(0, prefix.length + 1);
+      candidates.set(path.join(" "), { names: [path[path.length - 1]], path });
+    }
+  }
+  return [...candidates.values()];
+}
+
+/** Static declarations describe help coverage, never the runtime's complete grammar. */
+export function resolveHelpPath(requested: readonly string[]): HelpResolution {
+  const entry = requested[0] ? findCommand(requested[0]) : undefined;
+  if (!entry) return { kind: "unavailable", path: [...requested] };
+  // Keep exact-name alias entries for root help; nested topics use the owner.
+  const canonical = canonicalEntry(entry);
+  const declared = CAPABILITIES.filter(capability => !findCommand(capability.command[0])?.hidden);
+  if (requested.length === 1) return {
+    kind: "entry", entry, canonicalName: canonical.name,
+    children: entry.hidden ? [] : declared.filter(candidate => candidate.command.length > 1 && candidate.command[0] === canonical.name),
+  };
+  const path = [canonical.name, ...requested.slice(1)];
+  if (path.length === 2 && path[0] === "models" && path[1] === "context") {
+    return { kind: "models-context", path };
+  }
+  const capability = declared.find(candidate => candidate.command.length === path.length && startsWithPath(candidate.command, path));
+  if (capability) return { kind: "capability", path, capability };
+  const children = declared.filter(candidate => startsWithPath(candidate.command, path));
+  if (children.length) return { kind: "prefix", path, children };
+
+  for (let length = Math.min(path.length - 1, MAX_DOCUMENTED_DEPTH); length > 1; length--) {
+    const parent = path.slice(0, length);
+    if ((length === 2 && parent[0] === "models" && parent[1] === "context")
+      || declared.some(candidate => startsWithPath(candidate.command, parent))) {
+      return { kind: "unavailable", path, parent };
+    }
+  }
+  return { kind: "unavailable", path, parent: [canonical.name] };
+}

package/src/cli/help-models-context.ts

@@ -0,0 +1,17 @@
+/** Exact runtime usage row, including its indentation. No runtime imports. */
+export const MODELS_CONTEXT_USAGE = "  ocx models context <status|value <tokens> [--set-all]|provider <name> on [--value <tokens>]|provider <name> off|all <on|off>> [--json]";
+
+export const MODELS_CONTEXT_DETAILS = [
+  "Manage context caps for routed providers.",
+  "status: read current settings without changing them (the default action).",
+  "value <tokens>: set a positive token cap for future toggles; --set-all also applies it to every routed provider.",
+  "provider <name> on|off: enable or disable a provider cap; on accepts --value <tokens> for that provider only.",
+  "all on|off: enable or disable caps for every routed provider.",
+  "--json: print the result as JSON.",
+  "",
+  "Examples:",
+  "  ocx models context status --json",
+  "  ocx models context value 128000",
+  "  ocx models context provider openai on --value 128000",
+  "  ocx models context all off",
+] as const;

package/src/cli/help-navigation.ts

@@ -0,0 +1,50 @@
+import { findCommand } from "./registry";
+
+// Presentation owns selection/order only; names and summaries belong to registry.
+const ACTION_GROUPS = [
+  { title: "Start here", commands: ["setup", "start", "status"] },
+  { title: "Common tasks", commands: ["doctor", "logs", "usage"] },
+] as const;
+
+const FAMILY_GROUPS = [
+  ["provider", "account", "models", "alias"],
+  ["combo", "route", "agent", "effort"],
+  ["observe", "inspect", "access", "api"],
+  ["config", "system", "integration"],
+] as const;
+
+function publicCommand(name: string) {
+  const entry = findCommand(name);
+  if (!entry || entry.hidden) throw new Error(`Invalid public help group command: ${name}`);
+  return entry;
+}
+
+function actionLines(name: string): string[] {
+  const entry = publicCommand(name);
+  const prefix = `  ocx ${entry.name}`.padEnd(16);
+  const lines: string[] = [];
+  let line = prefix;
+  for (const word of entry.summary.split(/\s+/)) {
+    if (line.trim() && line.length + word.length + 1 > 80 && line !== prefix) {
+      lines.push(line);
+      line = " ".repeat(prefix.length);
+    }
+    line += `${line.endsWith(" ") ? "" : " "}${word}`;
+  }
+  lines.push(line);
+  return lines;
+}
+
+export function renderRootHelp(): string {
+  const lines = ["opencodex (ocx) — Universal provider proxy for Codex", "Usage: ocx <command> [options]"];
+  for (const group of ACTION_GROUPS) {
+    lines.push("", `${group.title}:`, ...group.commands.flatMap(actionLines));
+  }
+  lines.push("", "Explore:");
+  for (const group of FAMILY_GROUPS) lines.push(`  ${group.map(name => publicCommand(name).name).join("  ")}`);
+  lines.push("", "More help:",
+    "  ocx help <command>       Command usage and declared topics",
+    "  ocx help --all           Complete command reference",
+    "  ocx capabilities --json  Declared capabilities for scripts");
+  return lines.join("\n");
+}

package/src/cli/help-recovery.ts

@@ -0,0 +1,66 @@
+import { helpRecoveryCandidates, resolveHelpPath } from "./help-catalog";
+import { redactSecretString } from "../lib/redact";
+
+const MAX_TOKEN_LENGTH = 64;
+const MAX_PATH_DEPTH = 8;
+const MAX_SUGGESTIONS = 3;
+
+function safeToken(value: string | undefined): value is string {
+  return value !== undefined && value.length >= 3 && value.length <= MAX_TOKEN_LENGTH
+    && /^[a-z][a-z0-9-]*$/i.test(value) && redactSecretString(value) === value;
+}
+
+/** Banded edit distance with adjacent transposition, over already bounded tokens. */
+function distance(left: string, right: string, limit: number): number {
+  if (Math.abs(left.length - right.length) > limit) return limit + 1;
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  let older = previous;
+  for (let i = 1; i <= left.length; i++) {
+    const current: number[] = Array(right.length + 1).fill(limit + 1);
+    current[0] = i;
+    for (let j = Math.max(1, i - limit); j <= Math.min(right.length, i + limit); j++) {
+      current[j] = Math.min(current[j - 1] + 1, previous[j] + 1,
+        previous[j - 1] + (left[i - 1] === right[j - 1] ? 0 : 1));
+      if (i > 1 && j > 1 && left[i - 1] === right[j - 2] && left[i - 2] === right[j - 1]) {
+        current[j] = Math.min(current[j], older[j - 2] + 1);
+      }
+    }
+    older = previous;
+    previous = current;
+  }
+  return previous[right.length];
+}
+
+/** Return complete help destinations, never user-supplied trailing operands. */
+export function suggestHelpPaths(path: readonly string[]): string[][] {
+  if (!path.length || path.length > MAX_PATH_DEPTH || !path.every(safeToken)) return [];
+  const result = resolveHelpPath(path);
+  if (result.kind !== "unavailable") return [];
+  const parent = result.parent ?? [];
+  const token = path[parent.length].toLowerCase();
+  const limit = token.length < 6 ? 1 : 2;
+  return helpRecoveryCandidates(parent).map(candidate => ({
+    path: candidate.path,
+    name: candidate.path.join(" "),
+    distance: Math.min(...candidate.names.filter(safeToken).map(name => distance(token, name.toLowerCase(), limit))),
+  })).filter(candidate => candidate.distance <= limit)
+    .sort((a, b) => a.distance - b.distance || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .slice(0, MAX_SUGGESTIONS).map(candidate => candidate.path);
+}
+
+export function formatHelpRecovery(path: readonly string[]): string {
+  const result = resolveHelpPath(path);
+  const parent = result.kind === "unavailable" ? result.parent : undefined;
+  const lines = [parent ? "Detailed help unavailable for the requested topic."
+    : safeToken(path[0]) ? `Unknown command: ${path[0]}` : "Unknown command."];
+  const suggestions = suggestHelpPaths(path);
+  if (suggestions.length) {
+    lines.push("Did you mean:", ...suggestions.map(suggestion => `  ocx help ${suggestion.join(" ")}`));
+  }
+  lines.push(parent ? `See: ocx help ${parent.join(" ")}` : "See: ocx help --all");
+  return lines.join("\n");
+}
+
+export function printUnknownCommand(command: string | undefined): void {
+  console.error(formatHelpRecovery(command === undefined ? [] : [command]));
+}

package/src/cli/help.ts

@@ -1,4 +1,7 @@
-import { findCommand } from "./registry";
+import { resolveHelpPath } from "./help-catalog";
+import { MODELS_CONTEXT_DETAILS, MODELS_CONTEXT_USAGE } from "./help-models-context";
+import { renderRootHelp } from "./help-navigation";
+import { formatHelpRecovery } from "./help-recovery";
 import { packageVersion as readPackageVersion } from "../lib/package-version";
 
 /**
@@ -17,6 +20,10 @@ export function printVersion(): void {
 }
 
 export function printUsage(): void {
+  console.log(renderRootHelp());
+}
+
+export function printFullUsage(): void {
   console.log(`opencodex (ocx) — Universal provider proxy for Codex
 
 Usage:
@@ -115,13 +122,50 @@ export function hasHelpFlag(values: string[]): boolean {
   return values.some(value => value === "--help" || value === "-h" || value === "help");
 }
 
-export function printSubcommandUsage(name: string | undefined): void {
-  const entry = name ? findCommand(name) : undefined;
-  if (!entry) {
-    console.error(`Unknown command: ${name ?? ""}`.trim());
-    printUsage();
+export function printSubcommandUsage(
+  name: string | undefined,
+  path?: readonly string[],
+  options: { fallbackToParent?: boolean; write?: (text: string) => void } = {},
+): void {
+  const write = options.write ?? console.log;
+  const result = resolveHelpPath(path ?? (name ? [name] : []));
+  if (result.kind === "unavailable") {
+    // Appended flags may follow runtime operands. An explicit `help <path>`
+    // requests that exact detail instead, so only the CLI head enables fallback.
+    if (options.fallbackToParent && result.parent) {
+      printSubcommandUsage(result.parent[0], result.parent, { write });
+      return;
+    }
+    console.error(formatHelpRecovery(result.path));
     process.exit(1);
   }
-  console.log(`Usage: ${entry.usage}\n\n${entry.summary}`);
-  if (entry.details?.length) console.log(`\n${entry.details.join("\n")}`);
+  if (result.kind === "entry") {
+    write(`Usage: ${result.entry.usage}\n\n${result.entry.summary}`);
+    if (result.entry.details?.length) write(`\n${result.entry.details.join("\n")}`);
+    if (result.children.length) {
+      write("\nDeclared commands (incomplete):");
+      for (const child of result.children) write(`  ocx help ${child.command.join(" ")}  ${child.summary}`);
+    }
+    if (result.canonicalName === "models") write("\nContext cap help: ocx help models context");
+    if (result.entry.name !== result.canonicalName) write(`\nCanonical help: ocx help ${result.canonicalName}`);
+    return;
+  }
+  if (result.kind === "models-context") {
+    write(`Usage:\n${MODELS_CONTEXT_USAGE}\n\n${MODELS_CONTEXT_DETAILS.join("\n")}`);
+  } else if (result.kind === "capability") {
+    const { capability } = result;
+    write(`Command: ocx ${result.path.join(" ")}\n\n${capability.summary}`);
+    if (capability.flags.length) {
+      write("\nDeclared flags:");
+      for (const flag of capability.flags) {
+        write(`  ${flag.name}${flag.value && flag.value !== "boolean" ? ` <${flag.value}>` : ""}${flag.required ? " (required)" : ""}  ${flag.summary}`);
+      }
+    }
+    if (capability.details?.length) write(`\n${capability.details.join("\n")}`);
+    write("\nCapability metadata is incomplete; this is not the full operand grammar.");
+  } else {
+    write(`Command group: ocx ${result.path.join(" ")}\n\nDeclared commands (incomplete):`);
+    for (const child of result.children) write(`  ocx ${child.command.join(" ")}  ${child.summary}`);
+  }
+  write(`\nParent help: ocx help ${result.path.slice(0, -1).join(" ")}`);
 }

package/src/cli/models-runtime.ts

@@ -14,6 +14,7 @@ import {
   type RuntimeApiDeps,
 } from "./runtime-api";
 import { isModelsRuntimeSubcommand } from "./models-runtime-subcommands";
+import { MODELS_CONTEXT_USAGE } from "./help-models-context";
 import { isValidProviderName } from "../config/provider-name";
 import { isValidModelDiscoveryModelId } from "../providers/model-discovery-limits";
 import { redactSecretString } from "../lib/redact";
@@ -42,7 +43,7 @@ const USAGE = `Usage:
   ocx models preset apply <provider> [--all] [--json]
   ocx models new-policy [on|off] [--provider <name>] [--json]
   ocx models new-arrivals [--json]
-  ocx models context <status|value <tokens> [--set-all]|provider <name> on [--value <tokens>]|provider <name> off|all <on|off>> [--json]
+${MODELS_CONTEXT_USAGE}
   ocx models shadow <status|set> [model|-] [--enabled <on|off>] [--json]
 
 Prices are USD per 1M tokens. Omitted cache rates default to 0.

package/src/cli/opencode.ts

@@ -39,6 +39,7 @@ import type {
   OpencodeProviderBlocks,
   OpencodeV2ProviderBlock,
 } from "../clients/config-export";
+import type { EffectiveModelExportMetadata } from "../clients/config-export/contracts";
 import { filterCatalogVisibleModels, visibleNativeSlugs } from "../codex/catalog";
 import { commandInvocation } from "../lib/win-exec";
 import { configuredAdminToken, opencodeCatalogToken } from "../lib/admin-secrets";
@@ -106,12 +107,30 @@ export interface OpencodeProxyModelRow {
   contextWindow?: number;
   /** Authoritative output limit (CatalogModel.maxOutputTokens); optional. */
   maxOutputTokens?: number;
+  /** Authoritative input ceiling (CatalogModel.maxInputTokens); optional. */
+  maxInputTokens?: number;
+  /**
+   * Derived on the hub from known evidence; absent means unknown, never a negative. An
+   * explicit `false` from the hub is evidence too and is carried through unchanged.
+   */
+  supportsTools?: boolean;
+  supportsReasoning?: boolean;
+  supportsReasoningSummaries?: boolean;
   /** Declared input modalities from `/api/models`; carried into opencode model capabilities. */
   inputModalities?: string[];
   /** Declared effort ladder from `/api/models`; carried into opencode model variants. */
   reasoningEfforts?: string[];
   /** Declared default effort from `/api/models`. */
   defaultReasoningEffort?: string;
+  /**
+   * Effective export metadata `/api/models` attaches to every row it produces. Custom row
+   * fields are the operator's stored overrides, so this object is the authoritative
+   * projection a client consumes; routed and native rows carry their declared default in it
+   * because the row-level default is the picker's preference order. When present, an absent
+   * field inside means "no declared value" — never "fall back to the row" — and every field
+   * below still works for rows without it (older hubs, hand-built rows).
+   */
+  exportMetadata?: EffectiveModelExportMetadata;
 }
 
 const PROJECT_CONFIG_FILENAMES = ["opencode.json", "opencode.jsonc"] as const;
@@ -324,6 +343,12 @@ export async function fetchOpencodeProxyModels(
 /**
  * Visible OpenCode catalog entries from proxy /api/models rows. Disabled rows are omitted;
  * native rows are omitted in Codex Direct mode.
+ *
+ * Custom rows carry their effective projection in `exportMetadata`; when it is present it
+ * wins over the row's own fields, which for a custom row are the operator's stored overrides
+ * rather than the resolved capabilities. Routed/native projections also distinguish declared
+ * defaults from picker preferences; older hubs without the field retain their row values. The empty-vs-undefined ladder distinction
+ * survives: a row declaring `reasoningEfforts: []` exports `[]`, not an absent key.
  */
 export function opencodeCatalogFromProxyRows(
   rows: readonly OpencodeProxyModelRow[],
@@ -343,24 +368,43 @@ export function opencodeCatalogFromProxyRows(
       && !visibleRouted.has(row)) continue;
     if (seen.has(namespaced)) continue;
     seen.add(namespaced);
+    const effective = row.exportMetadata;
+    const maxTokens = effective?.maxTokens ?? row.maxOutputTokens;
+    const maxInputTokens = effective?.maxInputTokens ?? row.maxInputTokens;
+    const inputModalities = effective?.inputModalities ?? row.inputModalities;
+    const reasoningEfforts = effective?.reasoningEfforts ?? row.reasoningEfforts;
+    // The projection is the authority on the default: when it exists, an absent default means
+    // NO declared default, and falling back to the row would reintroduce the picker's
+    // synthetic medium/low value. Rows without one (older hubs, hand-built rows) keep the
+    // row's own value.
+    const defaultReasoningEffort = effective !== undefined
+      ? effective.defaultReasoningEffort
+      : row.defaultReasoningEffort;
+    const supportsTools = effective?.supportsTools ?? row.supportsTools;
+    const supportsReasoning = effective?.supportsReasoning ?? row.supportsReasoning;
+    const supportsReasoningSummaries = effective?.supportsReasoningSummaries ?? row.supportsReasoningSummaries;
     catalog.push({
       namespaced,
       native: row.native === true,
       provider: row.provider,
       id: row.id,
-      contextWindow: row.contextWindow,
-      ...(typeof row.maxOutputTokens === "number" ? { maxTokens: row.maxOutputTokens } : {}),
+      contextWindow: effective?.contextWindow ?? row.contextWindow,
+      ...(typeof maxTokens === "number" ? { maxTokens } : {}),
+      ...(typeof maxInputTokens === "number" ? { maxInputTokens } : {}),
       displayName: row.displayNameSource === "fallback" ? undefined : row.displayName,
-      ...(Array.isArray(row.inputModalities) && row.inputModalities.length > 0
-        ? { inputModalities: [...row.inputModalities] }
+      ...(Array.isArray(inputModalities) && inputModalities.length > 0
+        ? { inputModalities: [...inputModalities] }
         : {}),
       ...(typeof row.fastRowAvailable === "boolean" ? { fastRowAvailable: row.fastRowAvailable } : {}),
-      ...(Array.isArray(row.reasoningEfforts) && row.reasoningEfforts.length > 0
-        ? { reasoningEfforts: [...row.reasoningEfforts] }
-        : {}),
-      ...(typeof row.defaultReasoningEffort === "string" && row.defaultReasoningEffort.length > 0
-        ? { defaultReasoningEffort: row.defaultReasoningEffort }
+      // `[]` is a declaration, not an absence: an explicit no-rungs ladder stays empty here.
+      ...(Array.isArray(reasoningEfforts) ? { reasoningEfforts: [...reasoningEfforts] } : {}),
+      ...(typeof defaultReasoningEffort === "string" && defaultReasoningEffort.length > 0
+        ? { defaultReasoningEffort }
         : {}),
+      // An explicit false survives the hop; only derivation is true-or-nothing.
+      ...(typeof supportsTools === "boolean" ? { supportsTools } : {}),
+      ...(typeof supportsReasoning === "boolean" ? { supportsReasoning } : {}),
+      ...(typeof supportsReasoningSummaries === "boolean" ? { supportsReasoningSummaries } : {}),
     });
   }
   return catalog;
@@ -377,7 +421,7 @@ export function isOpencodeRuntimeConfigError(
 
 /**
  * Merge inherited `OPENCODE_CONFIG_CONTENT` and override only our own blocks:
- * `provider.opencodex` (V1) and `providers.opencodex` (V2, the one carrying variants).
+ * `provider.opencodex` (V1 maps) and `providers.opencodex` (native V2 arrays).
  * When no inline layer is present, emit the minimal runtime object for this launcher.
  */
 export function mergeOpencodeRuntimeConfig(

package/src/cli/provider.ts

@@ -10,7 +10,7 @@
  */
 import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
 import { apiKeyTransportConfigError, modelCapabilitiesConfigError, mergeModelCapabilities } from "../config/provider-validation";
-import { hasHelpFlag } from "./help";
+import { hasHelpFlag, printSubcommandUsage } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";
 import { dropProviderCustomModels } from "../providers/provider-id-rewrite";
@@ -472,38 +472,12 @@ function handleSetDefault(args: string[]): void {
 // Router (F2 fix: handle help flags internally, like service/codex-shim)
 // ---------------------------------------------------------------------------
 
-const PROVIDER_USAGE = `Usage: ocx provider <subcommand>
-
-Subcommands:
-  list                  List configured and available providers
-  add <name>            Add a provider (registry or custom)
-  edit <name>           Edit live provider fields
-  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
-  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 add anthropic --api-key sk-ant-...
-  ocx provider add my-ollama --adapter openai-chat --base-url http://localhost:11434/v1
-  ocx provider show anthropic --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`;
 
 export async function handleProviderCommand(args: string[]): Promise<void> {
   const sub = args[0];
 
   if (!sub || sub === "help" || hasHelpFlag(args)) {
-    console.log(PROVIDER_USAGE);
+    printSubcommandUsage("provider");
     process.exit(0);
   }
 
@@ -533,7 +507,7 @@ export async function handleProviderCommand(args: string[]): Promise<void> {
         break;
       }
       console.error(`Unknown provider subcommand: ${sub}`);
-      console.error(PROVIDER_USAGE);
+      printSubcommandUsage("provider", undefined, { write: console.error });
       process.exit(1);
     }
   }

package/src/cli/registry.ts

@@ -275,12 +275,36 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "provider",
-    usage: "ocx provider <list|add|edit|test|remove|show|set-default|selected|quota|presets|account-mode>",
+    usage: "ocx provider <subcommand>",
     summary: "Non-interactive provider management.",
     details: [
-      "Subcommands: list, add/edit/test/remove/show, set-default, selected, quota, presets, account-mode",
+      "Subcommands:",
+      "  list                  List configured and available providers",
+      "  add <name>            Add a provider (registry or custom)",
+      "  edit <name>           Edit live provider fields",
+      "  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",
+      "  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 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.",
-      "Run `ocx provider --help` for full usage and examples.",
     ],
   },
   {
@@ -383,11 +407,11 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "`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]", summary: "Alias of ocx observe logs." },
+  { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Read or follow request logs (alias of ocx observe logs)." },
   {
     name: "usage",
     usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]",
-    summary: "Alias of ocx observe usage.",
+    summary: "Report token usage and estimated cost (alias of ocx observe usage).",
   },
   {
     name: "storage",