@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/doctor.ts

@@ -33,6 +33,7 @@ import {
 } from "../codex/subagent-model-fallback";
 import { readCatalog, readCodexCatalogPath, readConfiguredDefaultModel } from "../codex/catalog/parsing";
 import { diagnoseCodexShim, findCodexOnPath, isWindowsInteropDir, type CodexShimDiagnostic } from "../codex/shim";
+import { overlayActivationHint } from "../codex/shim-overlay";
 import { providerTableString, rootTomlString } from "../codex/injected-marker";
 import { countPendingOpencodexHistory } from "../codex/history-provider";
 import {
@@ -481,28 +482,41 @@ export function collectProviderApiKeyDiagnostics(
 
 export type CodexEnvKeyReadinessDiagnostic = {
   envName: string;
-  shimState: "missing" | "unhealthy";
+  shimState: "missing" | "unhealthy" | "inactive";
   detail: string;
   action: string;
 };
 
+/** Shell activation and legacy migration are independent of admission-token readiness. */
+export function formatCodexShimDoctorLines(shim: CodexShimDiagnostic, platform = process.platform): string[] {
+  if (platform === "win32" || !shim.installed) return [];
+  const inactiveOverlay = shim.runnable === true && shim.active === false;
+  const healthyLegacy = shim.healthy && shim.runnable === undefined;
+  return inactiveOverlay || healthyLegacy ? shim.summary.split("\n").map(line => `       ${line}`) : [];
+}
+
 /** Warn when routed Codex cannot obtain its configured admission token at launch. */
 export function collectCodexEnvKeyReadiness(
   configText: string | null,
   env: EnvMap,
   shim: CodexShimDiagnostic,
   serviceTokenPresent: boolean,
+  shimActivationShown = false,
 ): CodexEnvKeyReadinessDiagnostic | null {
   if (!configText || rootTomlString(configText, "model_provider") !== "opencodex") return null;
   const envName = providerTableString(configText, "opencodex", "env_key")?.trim();
   const envValue = envName ? ownEnvValue(env, envName) : undefined;
   if (!envName || envValue?.trim() || shim.healthy || !serviceTokenPresent) return null;
-  const shimState = shim.installed ? "unhealthy" : "missing";
+  const shimState = shim.runnable && shim.active === false ? "inactive" : shim.installed ? "unhealthy" : "missing";
   return {
     envName,
     shimState,
     detail: `Codex uses env_key ${envName}, but that variable is unset and the OpenCodex shim is ${shimState}; the service token file exists but plain Codex does not load it`,
-    action: `Run 'ocx codex-shim install' to repair launch-time token injection, or export ${envName} in the process that starts Codex`,
+    action: shimState === "inactive"
+      ? shimActivationShown
+        ? `Activate the PATH shim as shown under Codex restart safety, or export ${envName} in the process that starts Codex`
+        : `${overlayActivationHint()} Or export ${envName} in the process that starts Codex`
+      : `Run 'ocx codex-shim install' to repair launch-time token injection, or export ${envName} in the process that starts Codex`,
   };
 }
 
@@ -1349,11 +1363,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     try { return readFileSync(codexConfigPath, "utf8"); } catch { return null; }
   })();
   const serviceTokenPresent = Boolean(readInstalledServiceToken()?.trim());
+  const codexShim = diagnoseCodexShim();
+  const codexShimLines = formatCodexShimDoctorLines(codexShim);
   const codexEnvKeyReadiness = collectCodexEnvKeyReadiness(
     codexConfigText,
     process.env,
-    diagnoseCodexShim(),
+    codexShim,
     serviceTokenPresent,
+    codexShimLines.length > 0,
   );
   // Use the same attested live startup verdict as `ocx status` when the proxy is already
   // identity-verified. A shell-local systemd probe can be a false negative for a system-wide
@@ -1366,6 +1383,7 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   console.log("\nCodex restart safety");
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
   console.log(`       ${formatStartupRoutingDetail(startup)}`);
+  for (const line of codexShimLines) console.log(line);
 
   console.log("\nCodex runtime selection");
   {

package/src/cli/export-command.ts

@@ -66,12 +66,13 @@ export interface ExportCommandDeps extends RuntimeApiDeps {
  * `opencodeCatalogFromProxyRows` owns the visibility rules (drop `disabled`, drop dupes,
  * drop native under Codex Direct) — the export core does none of that, so a row filtered
  * here is the only thing keeping a disabled model out of a client's picker. It also carries
- * the effort ladder, so the ladder a client receives comes from the same filtered, deduped
- * row as the model itself: a second lookup over the raw rows would let a hidden or disabled
- * duplicate donate its ladder to the visible entry.
+ * the effort ladder and the effective custom-row projection, so every per-model field a
+ * client receives comes from the same filtered, deduped row as the model itself: a second
+ * lookup over the raw rows would let a hidden or disabled duplicate donate its ladder to
+ * the visible entry.
  *
- * Modalities need no such lookup: `opencodeCatalogFromProxyRows` carries them on the catalog
- * entry, so the clients that filter them are handed the same filtered, deduped row.
+ * The empty-vs-undefined ladder distinction survives the hop: a row declaring `[]` exports
+ * `[]` (explicit "no rungs"), a row declaring nothing exports nothing (unknown).
  */
 export function exportModelsFromProxyRows(
   rows: readonly OpencodeProxyModelRow[],
@@ -87,13 +88,21 @@ export function exportModelsFromProxyRows(
     if (entry.fastRowAvailable !== undefined) model.fastRowAvailable = entry.fastRowAvailable;
     if (entry.displayName) model.displayName = entry.displayName;
     if (entry.contextWindow !== undefined) model.contextWindow = entry.contextWindow;
-    if (entry.reasoningEfforts && entry.reasoningEfforts.length > 0) {
-      model.reasoningEfforts = [...entry.reasoningEfforts];
-    }
+    // The catalog row's own output limit; dropping it here is what once made every CLI
+    // export fall back to the generated-metadata guess the management path never used.
+    if (entry.maxTokens !== undefined) model.maxTokens = entry.maxTokens;
+    if (entry.maxInputTokens !== undefined) model.maxInputTokens = entry.maxInputTokens;
+    if (entry.reasoningEfforts !== undefined) model.reasoningEfforts = [...entry.reasoningEfforts];
     if (entry.defaultReasoningEffort) model.defaultReasoningEffort = entry.defaultReasoningEffort;
     if (entry.inputModalities && entry.inputModalities.length > 0) {
       model.inputModalities = [...entry.inputModalities];
     }
+    // Explicit booleans survive, false included; nothing infers a negative from absence.
+    if (entry.supportsTools !== undefined) model.supportsTools = entry.supportsTools;
+    if (entry.supportsReasoning !== undefined) model.supportsReasoning = entry.supportsReasoning;
+    if (entry.supportsReasoningSummaries !== undefined) {
+      model.supportsReasoningSummaries = entry.supportsReasoningSummaries;
+    }
     return model;
   });
 }
@@ -194,7 +203,9 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
     // `--out` is the path that writes the selected client's native format.
     // Format metadata rides in the human lines below.
     printData(clientConfig, wantsJson, [
-      text.trimEnd(),
+      // `lines` entries print one console line each and are control-escaped, so
+      // the document goes in as individual lines rather than one multi-line blob.
+      ...text.trimEnd().split("\n"),
       "",
       ...(out !== undefined ? [`Wrote ${out}`] : []),
       `Destination: ${spec.destination(process.env)}`,

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,101 @@
+import { CAPABILITIES, type Capability } from "./capabilities";
+import { CLI_COMMANDS, findCommand, type CliCommandEntry } from "./registry";
+
+export type HelpResolution =
+  | { kind: "entry"; entry: CliCommandEntry; canonicalName: string; capability?: Capability; children: readonly Capability[] }
+  | { kind: "capability"; path: string[]; capability: Capability; children: readonly Capability[] }
+  | { kind: "prefix"; path: string[]; children: readonly Capability[] }
+  | { kind: "models-context"; path: string[] }
+  | { kind: "unavailable"; path: string[]; parent?: string[] };
+
+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;
+}
+
+/** Help-only aliases from access dispatch; never rewrite execution argv or operands. */
+function canonicalHelpPath(requested: readonly string[], entry: CliCommandEntry): string[] {
+  const path = entry.name === "api-key"
+    ? ["access", "key", ...requested.slice(1)]
+    : [canonicalEntry(entry).name, ...requested.slice(1)];
+  if (path[0] === "access") {
+    if (path[1] === "keys") path[1] = "key";
+    if (path[1] === "key" && path[2] === "delete") path[2] = "remove";
+  }
+  return path;
+}
+
+export interface HelpRecoveryCandidate {
+  names: string[];
+  path: string[];
+}
+
+/** 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 path = canonicalHelpPath([entry.name], entry);
+      const identity = path.join(" ");
+      const candidate = candidates.get(identity) ?? { names: [], path };
+      candidate.names = [...new Set([...candidate.names, entry.name, ...(entry.aliases ?? [])])];
+      candidates.set(identity, candidate);
+    }
+  } else {
+    const entry = findCommand(parent[0]);
+    if (!entry || entry.hidden) return [];
+    const prefix = canonicalHelpPath(parent, entry);
+    if (prefix.length >= MAX_DOCUMENTED_DEPTH) return [];
+    for (const documented of DOCUMENTED_PATHS) {
+      if (documented.length <= prefix.length || !startsWithPath(documented, prefix)) continue;
+      const path = documented.slice(0, prefix.length + 1);
+      const names = [path[path.length - 1]];
+      if (path.join(" ") === "access key") names.push("keys");
+      if (path.join(" ") === "access key remove") names.push("delete");
+      candidates.set(path.join(" "), { names, path });
+    }
+  }
+  return [...candidates.values()];
+}
+
+/** 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 path = canonicalHelpPath(requested, entry);
+  const declared = CAPABILITIES.filter(capability => !findCommand(capability.command[0])?.hidden);
+  if (requested.length === 1) return {
+    kind: "entry", entry, canonicalName: path.join(" "),
+    capability: entry.hidden ? undefined : declared.find(candidate => candidate.command.length === path.length && startsWithPath(candidate.command, path)),
+    children: entry.hidden ? [] : declared.filter(candidate => candidate.command.length > path.length && startsWithPath(candidate.command, path)),
+  };
+  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));
+  const children = declared.filter(candidate => candidate.command.length > path.length && startsWithPath(candidate.command, path));
+  if (capability) return { kind: "capability", path, capability, children };
+  if (children.length) return { kind: "prefix", path, children };
+
+  for (let length = Math.min(path.length - 1, MAX_DOCUMENTED_DEPTH); length > 1; length--) {
+    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: [path[0]] };
+}

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" || result.path.length > MAX_PATH_DEPTH) return [];
+  const parent = result.parent ?? [];
+  const token = result.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,8 @@
-import { findCommand } from "./registry";
+import { resolveHelpPath } from "./help-catalog";
+import type { Capability } from "./capabilities";
+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 +21,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:
@@ -33,7 +41,7 @@ Usage:
   ocx recover-history --ocx-compaction <thread-id> --yes
                                Back up and make one ocx1-compacted thread replayable by native Codex
   ocx uninstall               Remove service/shim/config and restore native Codex (alias: remove)
-  ocx service [sub]           Run as a background service (default: install/update/start)
+  ocx service [sub]           Run as a background service (default: install if absent, otherwise repair)
   ocx codex-shim <sub>        Auto-start proxy when \`codex\` launches (install|status|uninstall|remove)
   ocx tray <sub>              Windows status tray (install|start|stop|status|uninstall)
   ocx ensure                  Ensure the proxy is running and Codex config/cache are current
@@ -87,9 +95,9 @@ Usage:
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
-  ocx config <sub>            Validated configuration show/get/set/import/export
+  ocx config [sub]            Validated configuration show/get/set/import/export
   ocx companion <show|set|reset>  Menu-bar and widget companion usage settings
-  ocx lab <sub>               Read-only Compatibility Lab projection inspection
+  ocx lab <sub>               Inspect Lab evidence and control local automation
   ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
@@ -115,13 +123,63 @@ 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();
+function printCapabilityDetails(capability: Capability, write: (text: string) => void, shown: readonly string[] = []): void {
+  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}`);
+    }
+  }
+  const details = capability.details?.filter(detail => !shown.includes(detail));
+  if (details?.length) write(`\n${details.join("\n")}`);
+}
+
+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.capability) printCapabilityDetails(result.capability, write, result.entry.details);
+    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;
+    const heading = capability.usage !== undefined ? `Usage: ${capability.usage}` : `Command: ocx ${result.path.join(" ")}`;
+    write(`${heading}\n\n${capability.summary}`);
+    printCapabilityDetails(capability, write);
+    if (result.children.length) {
+      write("\nDeclared commands (incomplete):");
+      for (const child of result.children) write(`  ocx help ${child.command.join(" ")}  ${child.summary}`);
+    }
+    if (capability.usage === undefined) {
+      write("\nCapability metadata is incomplete; this is not the full operand grammar.");
+    }
+  } else {
+    write(`Command group: ocx ${result.path.join(" ")}\n\nDeclared commands (incomplete):`);
+    for (const child of result.children) write(`  ocx ${child.command.join(" ")}  ${child.summary}`);
+  }
+  write(`\nParent help: ocx help ${result.path.slice(0, -1).join(" ")}`);
 }