argsbarg 6.1.1 → 6.1.3

package/src/{types.ts → core/types.ts}

@@ -4,12 +4,13 @@ It is the shared declarative model that parsing, validation, help, and completio
 read from, so the package has one source of truth.
 */
 
+import type { AnyAppConfigSnapshot } from "~/config/context.ts";
 import type { CliContext } from "./context.ts";
 
 /**
  * How a leaf handler was dispatched.
  */
-export type CliInvocation = "cli" | "mcp" | "api";
+export type CliInvocation = "cli" | "mcp" | "http";
 
 /**
  * Option kinds: presence (boolean flag), string (free-form text), number (strict double), enum (fixed choices), or json (parsed JSON object/array).
@@ -61,14 +62,49 @@ export enum CliFallbackMode {
   UnknownOnly = "unknownOnly",
 }
 
+/**
+ * Per-surface CLI exposure (help, completions, cli-schema).
+ */
+export interface CliCliExposureConfig {
+  /** When `false`, not callable via CLI (cascades to descendants). Default: true. */
+  enabled?: boolean;
+  /** Callable; omit from help, completions, and schema export. */
+  hidden?: boolean;
+  completions?: { enabled?: boolean; hidden?: boolean };
+  schema?: { enabled?: boolean; hidden?: boolean };
+}
+
+/** HTTP method for REST leaves. */
+export type CliHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/**
+ * Per-node HTTP exposure and response defaults (routers: segment/enabled/hidden; leaves: full set).
+ */
+export interface CliHttpExposureConfig {
+  /** When `false`, omit from HTTP route table. Default: exposed. */
+  enabled?: boolean;
+  /** Callable; omit from OpenAPI / route discovery. */
+  hidden?: boolean;
+  /** Override inferred HTTP verb. */
+  method?: CliHttpMethod;
+  /** URL path segment override (≠ `key`). */
+  segment?: string;
+  /** Default success HTTP status when handler omits `ctx.respond({ status })`. */
+  successStatus?: number;
+  /** Default success Content-Type (OpenAPI + response headers). */
+  successContentType?: string;
+  /** Default Content-Disposition for binary/downloads. */
+  contentDisposition?: string;
+}
+
 /**
  * A named flag or value option (`--long`, `-short`), listed on command `options`.
  */
 export interface CliOption {
   /** Option name (e.g., "name", "verbose"). */
   name: string;
-  /** When `true`, omit from help, schema, completions, and MCP tool inputSchema (still parseable). */
-  hidden?: boolean;
+  /** Per-surface CLI exposure for this option. */
+  cli?: Pick<CliCliExposureConfig, "hidden">;
   /** Description shown in help. */
   description: string;
   /** Option kind: presence flag, string value, or number value. */
@@ -120,7 +156,7 @@ export interface CliPositional {
   argMax?: number;
 }
 
-/** Optional metadata for `mcp bundle` MCP Bundle output (program root `mcpServer.bundle` only). */
+/** @experimental MCP bundle output options (program root `mcpServer.bundle` only). */
 export interface CliMcpBundleConfig {
   author?: {
     name: string;
@@ -136,10 +172,15 @@ export interface CliMcpBundleConfig {
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
  * Must include `enabled: true`; omit `mcpServer` entirely to disable MCP.
+ * @experimental
  */
 export interface CliMcpServerConfig {
   /** When `true`, enables the `mcp` built-in and MCP stdio server. */
   enabled: boolean;
+  /** MCP error response defaults. */
+  errors?: CliMcpServerErrorsConfig;
+  /** Observe-only hooks for JSON-RPC messages. */
+  hooks?: CliMcpWireHooks;
   /** When `true`, `mcp bundle` writes `dist/<key>.mcpb` for Claude Desktop. Default false. */
   mcpd?: boolean;
   /** When `true`, `mcp bundle` also writes `dist/claude-plugin/<name>.zip`. Default false. */
@@ -161,23 +202,69 @@ export interface CliMcpServerConfig {
   bundle?: CliMcpBundleConfig;
 }
 
+/** JSON Schema for structured error responses (OpenAPI + HTTP/MCP error bodies). */
+export type CliJsonSchema = Record<string, unknown>;
+
+/** Wire-level HTTP hooks (observe-only; all requests including health and 404s). */
+export interface CliHttpWireHooks {
+  onRequest?: (ctx: CliHttpWireContext) => void | Promise<void>;
+  onResponse?: (ctx: CliHttpWireContext & { status: number; durationMs: number }) => void | Promise<void>;
+  onError?: (ctx: CliHttpWireContext & { failureKind: InvokeFailureKind; error: unknown }) => void | Promise<void>;
+}
+
+/** Per-request HTTP wire context for {@link CliHttpWireHooks}. */
+export interface CliHttpWireContext {
+  request: Request;
+  requestId: string;
+  clientIp: string;
+  path: string;
+  method: string;
+}
+
+/** Wire-level MCP hooks on JSON-RPC messages (observe-only). */
+export interface CliMcpWireHooks {
+  onRequest?: (ctx: CliMcpWireContext) => void | Promise<void>;
+  onResponse?: (ctx: CliMcpWireContext & { durationMs: number }) => void | Promise<void>;
+  onError?: (ctx: CliMcpWireContext & { failureKind: InvokeFailureKind; error: unknown }) => void | Promise<void>;
+}
+
+/** Per-message MCP wire context for {@link CliMcpWireHooks}. */
+export interface CliMcpWireContext {
+  rpcMethod: string;
+  requestId: string;
+  toolName?: string;
+}
+
 /**
- * Enables `myapp api` and the HTTP tool server (program root only).
- * Must include `enabled: true`; omit `apiServer` entirely to disable HTTP.
+ * Enables `myapp http` and the HTTP tool server (program root only).
+ * Must include `enabled: true`; omit `httpServer` entirely to disable HTTP.
  */
-export interface CliApiServerConfig {
-  /** When `true`, enables the `api` built-in and HTTP tool server. */
+export interface CliHttpServerConfig {
+  /** When `true`, enables the `http` built-in and HTTP tool server. */
   enabled: boolean;
   /** Listen host (default: `127.0.0.1`). */
   host?: string;
   /** Listen port (default: `3000`). */
   port?: number;
+  /** Honor `X-Forwarded-For` for client IP in hooks and logs. */
+  trustProxy?: boolean;
+  /** HTTP error response defaults. */
+  errors?: { errorSchema?: CliJsonSchema; obscureUnexpected?: boolean };
+  /** Observe-only hooks for all HTTP requests. */
+  hooks?: CliHttpWireHooks;
+}
+
+/** MCP server error defaults. */
+export interface CliMcpServerErrorsConfig {
+  errorSchema?: CliJsonSchema;
+  obscureUnexpected?: boolean;
 }
 
 /**
- * Declarative HTTP response hints for a leaf (used by OpenAPI and default headers).
+ * Declarative HTTP response hints passed to {@link apiSuccessResponse}.
+ * @internal Prefer `CliHttpExposureConfig` on the leaf.
  */
-export interface CliApiResponseConfig {
+export interface CliHttpResponseConfig {
   /** Default success Content-Type (default: `application/json`). */
   contentType?: string;
   /** Optional Content-Disposition (e.g. `attachment; filename="invoice.pdf"`). */
@@ -219,15 +306,13 @@ export interface CliMcpResource {
 export interface CliMcpToolConfig {
   /** When `false`, omit from `tools/list` (default: exposed). */
   enabled?: boolean;
+  /** Callable; omit from `tools/list` and MCP tool schemas. */
+  hidden?: boolean;
   /**
    * Override the generated MCP tool description.
    * Default: auto-generated from command path and description.
    */
   description?: string;
-  /**
-   * @deprecated Set `outputSchema` on the leaf command instead.
-   */
-  outputSchema?: Record<string, unknown>;
 }
 
 /**
@@ -310,6 +395,7 @@ export interface CliCompletionConfig {
   enabled?: boolean;
 }
 
+/** @experimental */
 export interface CliConfigureConfig {
   /** When `false`, hide/disable `configure` (default: enabled). */
   enabled?: boolean;
@@ -385,21 +471,16 @@ export interface CliDocsTopic {
 }
 
 /**
- * Enables `myapp docs` and bundled markdown topics (program root only).
- * Must include `enabled: true`; omit `docs` entirely to disable.
+ * Opt-out and optional topics for the `docs` built-in (program root only).
+ * Docs is enabled by default; set `enabled: false` to disable.
  */
 export interface CliDocsConfig {
-  /** When `true`, enables the `docs` built-in command group. */
-  enabled: boolean;
+  /** When `false`, hide/disable `docs` (default: enabled). */
+  enabled?: boolean;
   /** Router description for `myapp docs` (default: "Print bundled CLI documentation."). */
   description?: string;
-  /**
-   * Subcommand for bare `myapp docs` (maps to router `fallbackCommand`).
-   * When omitted, uses the first key in `topics` (insertion order).
-   */
-  defaultTopic?: string;
-  /** Topic key → bundled markdown. Reserved keys: `mcp`, `all` (supplied by the built-in). */
-  topics: Record<string, CliDocsTopic>;
+  /** Optional consumer markdown topics. Reserved keys: `mcp`, `all` (supplied by the built-in). */
+  topics?: Record<string, CliDocsTopic>;
 }
 
 /**
@@ -408,8 +489,10 @@ export interface CliDocsConfig {
 export interface CliNodeBase {
   /** Program or command key (e.g., "myapp", "stat", "owner"). */
   key: string;
-  /** When `true`, omit from help listings, schema, completions, and MCP tools (still invocable). */
-  hidden?: boolean;
+  /** Per-surface CLI exposure. */
+  cli?: CliCliExposureConfig;
+  /** Per-surface HTTP exposure and response defaults. */
+  http?: CliHttpExposureConfig;
   /** Short description shown in help. */
   description: string;
   /** Additional notes shown in help (`{argsbarg:program}` → program key). */
@@ -418,23 +501,29 @@ export interface CliNodeBase {
   options?: CliOption[];
 }
 
+/** Leaf input mode: `json` = pure JSON body (no CLI flags). */
+export type CliLeafKind = "json";
+
 /**
  * A leaf command node with a handler and optional positionals.
  */
 export type CliLeaf = CliNodeBase & {
+  /**
+   * When `"json"`, the leaf accepts a single JSON document (CLI positional or piped stdin;
+   * MCP/HTTP tool args = body). Requires `inputSchema`; forbids `options` and `positionals`.
+   */
+  kind?: CliLeafKind;
   /** Handler function for leaf commands. */
   handler: CliHandler;
   /** Positional argument definitions. */
   positionals?: CliPositional[];
   /**
    * JSON Schema for structured stdout (e.g. with `--json` or MCP when the handler emits JSON).
-   * Exported in `docs cli-schema`, `docs api`, and MCP `tools/list`; not validated at runtime yet.
+   * Exported in `docs cli-schema`, `docs cli`, and MCP `tools/list`; not validated at runtime yet.
    */
   outputSchema?: Record<string, unknown>;
   /** JSON Schema for MCP/HTTP tool arguments (flat object). */
   inputSchema?: Record<string, unknown>;
-  /** Declarative HTTP response metadata (Content-Type, Content-Disposition). */
-  apiResponse?: CliApiResponseConfig;
   /** Per-tool MCP exposure and metadata. */
   mcpTool?: CliMcpToolConfig;
 };
@@ -456,6 +545,109 @@ export type CliRouter = CliNodeBase & {
  */
 export type CliNode = CliLeaf | CliRouter;
 
+/** Classified failure kind for invoke error pipeline and HTTP/MCP status mapping. */
+export type InvokeFailureKind = "validation" | "help" | "unexpected" | "not_ready" | "missing_config" | "unknown_route";
+
+/**
+ * Per-invocation context attached in hooks (e.g. DB handles, auth principals).
+ * Augment in app code: `declare module "argsbarg" { interface CliLocals { db: AppDb } }`.
+ */
+export interface CliLocals {
+  /** Correlation id seeded before hooks run (HTTP/MCP wire id or generated UUID). */
+  requestId?: string;
+}
+
+/**
+ * Cross-request server state (HTTP/MCP runtime bag).
+ * Augment in app code: `declare module "argsbarg" { interface ServerState { db: AppDb } }`.
+ */
+export interface ServerState {
+  /** Set when app config soft-validation fails at server start. */
+  configFileError?: string;
+  /** Short-TTL cache for readiness probe results. */
+  readinessCache?: {
+    at: number;
+    result: { ok: boolean; checks: Record<string, { ok: boolean; error?: string; missing?: string[] }> };
+  };
+  /** Last readiness probe result. */
+  readiness?: { ok: boolean; checks: Record<string, { ok: boolean; error?: string; missing?: string[] }> };
+}
+
+/** Cross-request mutable state created at HTTP/MCP server start. */
+export interface ServerRuntime {
+  /** Mutable global bag (DB pool, degraded flags, readiness cache, etc.). */
+  state: ServerState;
+  program: CliProgram;
+  surface: "http" | "mcp";
+}
+
+/** Context for program-level invoke hooks (CLI, HTTP, MCP user commands). */
+export interface InvokeHookContext {
+  invocation: CliInvocation;
+  path: string[];
+  pathParams: Record<string, string>;
+  opts: Record<string, string>;
+  /** Per-invocation bag; `beforeInvoke` may write. Framework seeds `requestId` before hooks run. */
+  locals: CliLocals;
+  runtime?: ServerRuntime;
+  appConfig: AnyAppConfigSnapshot;
+  http?: { request: Request; clientIp: string; requestId: string };
+  mcp?: { rpcMethod: string; toolName?: string; requestId: string };
+}
+
+/** Error hook context after failure classification. */
+export interface ErrorHookContext extends InvokeHookContext {
+  failureKind: InvokeFailureKind;
+  error: unknown;
+  /** Default client-facing error before `formatError` override. */
+  clientError: ClientErrorOverride;
+}
+
+/** Client-facing error payload; `formatError` may return a partial override. */
+export interface ClientErrorOverride {
+  message: string;
+  exitCode?: number;
+}
+
+/** Minimal invoke result passed to `afterInvoke` (see {@link Cli.invoke}). */
+export interface CliInvokeHookResult {
+  kind: "ok" | "help" | "error";
+  exitCode: number;
+  failureKind?: InvokeFailureKind;
+  errorMsg?: string;
+}
+
+/** Program-level invoke and error hooks (skipped for builtins). */
+export interface CliProgramHooks {
+  /** May mutate `locals`, `opts`, `args`; may throw. Skipped for builtins. */
+  beforeInvoke?: (ctx: InvokeHookContext) => void | Promise<void>;
+  afterInvoke?: (ctx: InvokeHookContext & { result: CliInvokeHookResult }) => void | Promise<void>;
+  /** Mutate client-facing error payload only. Runs before `onError`. */
+  formatError?: (ctx: ErrorHookContext) => ClientErrorOverride | undefined | Promise<ClientErrorOverride | undefined>;
+  /** Observe only — runs after `formatError`; may enrich `locals`. Never mutates client response. */
+  onError?: (ctx: ErrorHookContext) => void | Promise<void>;
+}
+
+/** Context for optional `program.readiness` (HTTP/MCP health only). */
+export interface ReadinessContext {
+  program: CliProgram;
+  surface: "http" | "mcp";
+  appConfig: AnyAppConfigSnapshot;
+  runtime: ServerRuntime;
+}
+
+/** Framework logging defaults (ECS json or human text on stderr). */
+export interface CliLogConfig {
+  /** `json` = ECS lines; `text` = human stderr lines. Default: `json`. */
+  format?: "json" | "text";
+  /** Tee stderr + append; relative paths resolve under the app config dir. */
+  file?: string;
+  /** Emit HTTP/MCP access logs. Default: true. */
+  access?: boolean;
+  /** Emit error events after the hook pipeline. Default: true. */
+  errors?: boolean;
+}
+
 /**
  * Program root passed to {@link Cli}.
  * May be a leaf or router, plus optional program-level MCP and install config.
@@ -467,14 +659,20 @@ export type CliProgram = CliNode & {
   appConfig?: CliAppConfig;
   /** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
   mcpServer?: CliMcpServerConfig;
-  /** When set with `enabled: true`, enables the `api` built-in HTTP server. */
-  apiServer?: CliApiServerConfig;
+  /** When set with `enabled: true`, enables the `http` built-in HTTP server. */
+  httpServer?: CliHttpServerConfig;
   /** Opt-out and defaults for `configure`. */
   configure?: CliConfigureConfig;
   /** Opt-out for shell completion generation (`completion bash|zsh|fish`). */
   completion?: CliCompletionConfig;
-  /** When set with `enabled: true`, enables the `docs` built-in command group. */
+  /** Opt-out and optional topics for the `docs` built-in (default: enabled). */
   docs?: CliDocsConfig;
+  /** Invoke and error hooks for user commands on CLI, HTTP, and MCP. */
+  hooks?: CliProgramHooks;
+  /** Optional readiness probe for HTTP/MCP `GET /health/ready` only. */
+  readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
+  /** Framework logging (stderr + optional file). */
+  log?: CliLogConfig;
 };
 
 /** True when the node is a leaf (has a handler). */
@@ -482,14 +680,19 @@ export function isCliLeaf(node: CliNode): node is CliLeaf {
   return "handler" in node && typeof node.handler === "function";
 }
 
+/** True when the leaf accepts a pure JSON body (no CLI flags). */
+export function isJsonLeaf(leaf: CliLeaf): boolean {
+  return leaf.kind === "json";
+}
+
 /** True when the node is a router (has subcommands). */
 export function isCliRouter(node: CliNode): node is CliRouter {
   return "commands" in node && Array.isArray(node.commands);
 }
 
-/** Resolves structured stdout schema from the leaf (prefers leaf field over legacy `mcpTool.outputSchema`). */
+/** Resolves structured stdout schema from the leaf. */
 export function leafOutputSchema(leaf: CliLeaf): Record<string, unknown> | undefined {
-  return leaf.outputSchema ?? leaf.mcpTool?.outputSchema;
+  return leaf.outputSchema;
 }
 
 /**

package/src/{validate.ts → core/validate.ts}

@@ -2,12 +2,12 @@
 This module validates CLI schemas before execution.
 */
 
-import { reservedCommandNames, resolveCapabilities } from "./capabilities.ts";
-import { reservedDocsTopicResourceUris } from "./docs/mcp-resources.ts";
-import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
+import { AGENT_PAIRS, MCP_KEYS, mcpServerRequiredForArtifact } from "~/configure/artifacts/target-registry.ts";
+import { reservedDocsTopicResourceUris } from "~/docs/mcp-resources.ts";
+import { DOCS_BUILTIN_TOPIC_KEYS, docsEnabled } from "~/docs/resolve.ts";
+import { resolveMcpSchemaUri } from "~/mcp/tools.ts";
+import { reservedCommandNames, resolveCapabilities } from "~/runtime/capabilities.ts";
 import { validateFormatValue } from "./formats.ts";
-import { AGENT_PAIRS, MCP_KEYS, mcpServerRequiredForArtifact } from "./install/target-registry.ts";
-import { resolveMcpSchemaUri } from "./mcp/tools.ts";
 import {
   type CliLeaf,
   type CliNode,
@@ -19,24 +19,20 @@ import {
   type InstallTargetSpec,
   isCliLeaf,
   isCliRouter,
+  isJsonLeaf,
 } from "./types.ts";
 
 /** Validates `docs` configuration on the program root. */
 function validateDocsConfig(docs: import("./types.ts").CliDocsConfig): void {
-  const keys = Object.keys(docs.topics);
-  if (keys.length === 0) {
-    throw new CliSchemaValidationError("docs.topics must be non-empty");
-  }
+  const topics = docs.topics ?? {};
+  const keys = Object.keys(topics);
   for (const reserved of DOCS_BUILTIN_TOPIC_KEYS) {
-    if (reserved in docs.topics) {
+    if (reserved in topics) {
       throw new CliSchemaValidationError(`docs.topics key '${reserved}' is reserved for the docs built-in`);
     }
   }
-  if (docs.defaultTopic !== undefined && !(docs.defaultTopic in docs.topics)) {
-    throw new CliSchemaValidationError(`docs.defaultTopic '${docs.defaultTopic}' is not a key in docs.topics`);
-  }
   for (const key of keys) {
-    const text = docs.topics[key]?.text;
+    const text = topics[key]?.text;
     if (text === undefined || text.length === 0) {
       throw new CliSchemaValidationError(`docs.topics['${key}'].text must be non-empty`);
     }
@@ -180,15 +176,11 @@ export function cliValidateProgram(program: CliProgram): void {
     throw new CliSchemaValidationError("mcpServer requires enabled: true; omit mcpServer to disable MCP");
   }
 
-  if (program.apiServer !== undefined && program.apiServer.enabled !== true) {
-    throw new CliSchemaValidationError("apiServer requires enabled: true; omit apiServer to disable HTTP API");
+  if (program.httpServer !== undefined && program.httpServer.enabled !== true) {
+    throw new CliSchemaValidationError("httpServer requires enabled: true; omit httpServer to disable HTTP API");
   }
 
-  if (program.docs !== undefined && program.docs.enabled !== true) {
-    throw new CliSchemaValidationError("docs requires enabled: true; omit docs to disable bundled documentation");
-  }
-
-  if (program.docs?.enabled === true) {
+  if (docsEnabled(program) && program.docs?.topics !== undefined) {
     validateDocsConfig(program.docs);
   }
 
@@ -214,14 +206,20 @@ export function cliValidateProgram(program: CliProgram): void {
   walkNode(program, program, true);
 }
 
+const PARAM_ROUTER_KEY = /^:[a-zA-Z][a-zA-Z0-9_]*$/;
+
+function isParamRouterKey(key: string): boolean {
+  return key.startsWith(":");
+}
+
 function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
   if (!isRoot) {
     const rogue = node as CliProgram;
     if (rogue.mcpServer !== undefined) {
       throw new CliSchemaValidationError(`mcpServer is only supported on the program root (not on ${node.key})`);
     }
-    if (rogue.apiServer !== undefined) {
-      throw new CliSchemaValidationError(`apiServer is only supported on the program root (not on ${node.key})`);
+    if (rogue.httpServer !== undefined) {
+      throw new CliSchemaValidationError(`httpServer is only supported on the program root (not on ${node.key})`);
     }
     if (rogue.configure !== undefined) {
       throw new CliSchemaValidationError(`configure is only supported on the program root (not on ${node.key})`);
@@ -238,13 +236,22 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     if (isRoot && node.mcpTool !== undefined) {
       throw new CliSchemaValidationError("mcpTool is only supported on leaf commands");
     }
-    const outputSchema = node.outputSchema;
-    const legacyOutputSchema = node.mcpTool?.outputSchema;
-    if (outputSchema !== undefined && legacyOutputSchema !== undefined) {
-      throw new CliSchemaValidationError("Set outputSchema on the leaf only, not under mcpTool");
+    if (isJsonLeaf(node)) {
+      if (node.inputSchema === undefined) {
+        throw new CliSchemaValidationError(`kind: "json" requires inputSchema on ${node.key}`);
+      }
+      if ((node.options ?? []).length > 0) {
+        throw new CliSchemaValidationError(`kind: "json" forbids options on ${node.key}`);
+      }
+      if ((node.positionals ?? []).length > 0) {
+        throw new CliSchemaValidationError(`kind: "json" forbids positionals on ${node.key}`);
+      }
     }
-    const resolved = outputSchema ?? legacyOutputSchema;
-    if (resolved !== undefined && (typeof resolved !== "object" || resolved === null || Array.isArray(resolved))) {
+    const outputSchema = node.outputSchema;
+    if (
+      outputSchema !== undefined &&
+      (typeof outputSchema !== "object" || outputSchema === null || Array.isArray(outputSchema))
+    ) {
       throw new CliSchemaValidationError("outputSchema must be a JSON Schema object (not null or an array)");
     }
     const inputSchema = node.inputSchema;
@@ -296,11 +303,26 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
 
   if (isCliRouter(node)) {
     const seenNames = new Set<string>();
+    let paramRouterCount = 0;
     for (const child of node.commands) {
       if (seenNames.has(child.key)) {
         throw new CliSchemaValidationError(`Duplicate command name: ${child.key}`);
       }
       seenNames.add(child.key);
+      if (isParamRouterKey(child.key)) {
+        if (!PARAM_ROUTER_KEY.test(child.key)) {
+          throw new CliSchemaValidationError(
+            `Param router key '${child.key}' must match :[a-zA-Z][a-zA-Z0-9_]* on '${node.key}'`,
+          );
+        }
+        if (!isCliRouter(child)) {
+          throw new CliSchemaValidationError(`Param router '${child.key}' must be a router with subcommands`);
+        }
+        paramRouterCount++;
+      }
+    }
+    if (paramRouterCount > 1) {
+      throw new CliSchemaValidationError(`At most one param router per level on '${node.key}'`);
     }
 
     if (node.fallbackMode !== undefined && node.fallbackCommand === undefined) {

package/src/docs/builtin.ts

@@ -1,16 +1,8 @@
-import { docsSkillTopicDescription } from "../builtins/configure-copy.ts";
-import { resolveCapabilities } from "../capabilities.ts";
-import {
-  CliFallbackMode,
-  type CliLeaf,
-  type CliOption,
-  CliOptionKind,
-  type CliProgram,
-  type CliRouter,
-} from "../types.ts";
+import { docsSkillTopicDescription } from "~/builtins/configure-copy.ts";
+import { type CliLeaf, type CliOption, CliOptionKind, type CliProgram, type CliRouter } from "~/core/types.ts";
+import { resolveCapabilities } from "~/runtime/capabilities.ts";
 import {
   DOCS_ROUTER_DESCRIPTION,
-  docsEffectiveDefaultTopic,
   docsEnabled,
   docsIncludesHttpTopic,
   docsIncludesMcpTopic,
@@ -18,6 +10,7 @@ import {
   docsTopicDescription,
   docsUserTopicKeys,
   printDocsTopic,
+  resolveDocsConfig,
 } from "./resolve.ts";
 import { saveDocsTopic } from "./save.ts";
 
@@ -54,14 +47,12 @@ function docsRouterNotes(): string {
 
 /** Built-in `docs` router with bundled topic subcommands. */
 export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
-  const docs = program.docs;
-  if (!docs) {
-    throw new Error("docs not enabled");
-  }
+  const docs = resolveDocsConfig(program);
+  const topics = docs.topics ?? {};
   const leaves: CliLeaf[] = [];
 
   for (const key of docsUserTopicKeys(docs)) {
-    const topic = docs.topics[key];
+    const topic = topics[key];
     if (!topic) {
       throw new Error(`docs topic missing: ${key}`);
     }
@@ -82,7 +73,7 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
 
   leaves.push(
     docsLeaf(program, "cli-schema", "Print the full CLI command tree as JSON."),
-    docsLeaf(program, "api", "Print the full command reference as markdown."),
+    docsLeaf(program, "cli", "Print the full command reference as markdown."),
     docsLeaf(program, "skill", docsSkillTopicDescription(program, resolveCapabilities(program))),
   );
 
@@ -91,8 +82,6 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
     description: docs.description ?? DOCS_ROUTER_DESCRIPTION,
     notes: docsRouterNotes(),
     options: [DOCS_SAVE_OPTION],
-    fallbackCommand: docsEffectiveDefaultTopic(docs),
-    fallbackMode: CliFallbackMode.MissingOnly,
     commands: leaves,
   };
 }