argsbarg 3.3.14 → 3.4.0

package/.private/scratch.md

@@ -1,2 +1,4 @@
 - [x] --schema feature for ai agents
-- [x] opt-out install feature?
+- [x] opt-out install feature?
+- [x] outputSchema
+- [x] mcpb bundle

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.4.0] - 2026-06-22
+
+### Added
+
+- **`hidden`** — boolean on commands and options; omitted from help listings, `docs schema` / `docs api`, shell completions, and MCP `tools/list`, but still parseable and invocable. Direct `-h` on a hidden command still works.
+- **`mcp bundle`** — built-in subcommand when `mcpServer.enabled` (macOS-only v1). Runs `myapp mcp bundle` to pack `dist/<key>.mcpb` from `dist/<key>`. Bare `myapp mcp` still starts the stdio server.
+- **`mcpServer.bundle`** — optional author, icon, and `longDescription` for MCP Bundle metadata.
+- **Leaf `outputSchema`** — optional JSON Schema for structured stdout; exported in `docs schema`, `docs api`, skill `reference.md`, and MCP `tools/list` (stdout not validated at runtime yet). Legacy `mcpTool.outputSchema` still works.
+- **MCP tool descriptions** — leaf `notes` are appended to `tools/list` descriptions (`{argsbarg:program}` resolved).
+
 ## [3.3.14] - 2026-06-21
 
 ### Changed
@@ -335,7 +345,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.14...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.4.0...HEAD
+[3.4.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.0
 [3.3.14]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.14
 [3.3.13]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.13
 [3.3.12]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.12

package/docs/cli-program.md

@@ -113,6 +113,25 @@ Many "MCP problems" are schema or handler gaps. Prefer these over escape hatches
 | `requiresEnv: [...]` | Runtime secrets; appended to MCP description and enforced at `tools/call` |
 | `description: "..."` | **Irreducible** MCP limitation (e.g. live tail / `--watch` cannot be streamed on the MCP wire yet) |
 
+### Structured stdout
+
+On **leaf commands**, set `outputSchema` to a JSON Schema describing stdout when the handler emits JSON (typically with `--json`, or via MCP on the headless path):
+
+```typescript
+{
+  key: "lookup",
+  description: "Resolve owner info.",
+  outputSchema: {
+    type: "object",
+    properties: { user: { type: "string" }, path: { type: "string" } },
+    required: ["user", "path"],
+  },
+  handler: (ctx) => { /* ... */ },
+}
+```
+
+Exported in `docs schema`, `docs api`, skill `reference.md`, and MCP `tools/list`. Not validated at runtime yet. Pair with `notes` for prose examples; do not duplicate the full schema in `notes`.
+
 Do **not** use `mcpTool.description` to paper over missing `--yes`, non-standard flag names, or handlers that only work interactively — fix those instead.
 
 If help text and MCP behavior match after your fixes, **omit `mcpTool` entirely**.

package/docs/mcp.md

@@ -103,7 +103,7 @@ Tool names are derived from the command path, with each segment sanitized (non-a
 
 ### Tool descriptions
 
-Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash. Tool arguments are defined in `inputSchema` (options and positionals with their descriptions). `mcpTool.requiresEnv` is appended as `[requires env: …]`.
+Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash. Leaf **`notes`** are appended after a blank line (with `{argsbarg:program}` resolved). Tool arguments are defined in `inputSchema` (options and positionals with their descriptions). `mcpTool.requiresEnv` is appended as `[requires env: …]` on auto-generated descriptions.
 
 | CLI path | MCP `description` (example) |
 | --- | --- |
@@ -138,6 +138,8 @@ mcpTool: {
 }
 ```
 
+Set **`outputSchema` on the leaf** (not under `mcpTool`) — see [cli-program.md — Structured stdout](cli-program.md#structured-stdout).
+
 - **`description`** — when set, replaces the auto-generated `path — help` description entirely (no automatic `requiresEnv` suffix; mention vars in your text if needed).
 - **`requiresEnv`** — on auto-generated descriptions, appended as `[requires env: …]`. Enforced at `tools/call` time before the handler runs. Empty or unset env values count as missing.
 
@@ -276,7 +278,7 @@ mcpServer: {
 | `initialize` | Returns capabilities (`tools`, `resources`) and `serverInfo`. |
 | `notifications/initialized` | Acknowledged; no response (notification). |
 | `ping` | Returns `{}`. |
-| `tools/list` | Lists all tools with `name`, `description`, `inputSchema`. |
+| `tools/list` | Lists all tools with `name`, `description`, `inputSchema`, and optional `outputSchema`. |
 | `tools/call` | Runs a leaf handler; params: `name`, `arguments` (object). |
 | `resources/list` | Lists schema + custom resources. |
 | `resources/read` | Returns resource body; params: `uri`. |
@@ -291,11 +293,29 @@ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun
 
 You should get one JSON line on stdout with `result.capabilities` and `result.serverInfo`.
 
+## MCP Bundle (`mcp bundle`)
+
+When `mcpServer.enabled` is true, **`mcp bundle`** packs a Claude Desktop **`.mcpb`** bundle (macOS-only v1):
+
+```bash
+just build
+./dist/myapp mcp bundle
+# → dist/myapp.mcpb
+```
+
+Expects the compiled binary at **`dist/<program.key>`** and writes **`dist/<program.key>.mcpb`**. Manifest metadata is generated from your schema (`mcpServerId`, tools, `requiresEnv`). Optional pack-time fields live under **`mcpServer.bundle`** (`author`, `icon`, `longDescription`).
+
+Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `install --mcp` and MCP hosts). Use **`install --mcp`** for Cursor / Claude Code JSON config.
+
+## Hidden commands and options
+
+Set **`hidden: true`** on a command or option to omit it from help listings, `docs schema` / `docs api`, shell completions, and MCP `tools/list` / tool `inputSchema`. Hidden commands remain invocable; **`myapp hidden-cmd -h`** still works.
+
 ## Reserved names
 
 When MCP is enabled:
 
-- Do not declare a top-level command named **`completion`** — reserved for shell completions.
+- Do not declare top-level commands named **`completion`** or **`mcp`** — reserved for platform builtins.
 
 Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1).
 

package/index.d.ts

@@ -69,6 +69,8 @@ export declare enum CliFallbackMode {
 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;
 	/** Description shown in help. */
 	description: string;
 	/** Option kind: presence flag, string value, or number value. */
@@ -104,6 +106,18 @@ export interface CliPositional {
 	 */
 	argMax?: number;
 }
+/** Optional metadata for `mcp bundle` MCP Bundle output (program root `mcpServer.bundle` only). */
+export interface CliMcpBundleConfig {
+	author?: {
+		name: string;
+		email?: string;
+		url?: string;
+	};
+	/** Repo-relative path to a PNG icon copied into the bundle. */
+	icon?: string;
+	/** Manifest `long_description` (defaults to program description). */
+	longDescription?: string;
+}
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
  * Must include `enabled: true`; omit `mcpServer` entirely to disable MCP.
@@ -130,6 +144,8 @@ export interface CliMcpServerConfig {
 	 * URIs must be unique and must not equal schemaResourceUri.
 	 */
 	resources?: CliMcpResource[];
+	/** Optional MCP Bundle (`.mcpb`) metadata for `mcp bundle`. */
+	bundle?: CliMcpBundleConfig;
 }
 /**
  * A custom MCP resource exposed under resources/list and resources/read.
@@ -163,6 +179,10 @@ export interface CliMcpToolConfig {
 	 * Empty string counts as absent.
 	 */
 	requiresEnv?: string[];
+	/**
+	 * @deprecated Set `outputSchema` on the leaf command instead.
+	 */
+	outputSchema?: Record<string, unknown>;
 }
 /**
  * Opt-out and defaults for the `install` built-in (program root only).
@@ -222,6 +242,8 @@ 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;
 	/** Short description shown in help. */
 	description: string;
 	/** Additional notes shown in help (`{argsbarg:program}` → program key). */
@@ -237,6 +259,11 @@ export type CliLeaf = CliNodeBase & {
 	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 schema`, `docs api`, and MCP `tools/list`; not validated at runtime yet.
+	 */
+	outputSchema?: Record<string, unknown>;
 	/** Per-tool MCP exposure and metadata. */
 	mcpTool?: CliMcpToolConfig;
 };
@@ -378,5 +405,25 @@ export declare function createGhVersionCheck(config: GhVersionCheckConfig): {
 };
 /** Shared `gh release view` fetcher for hooks and version-check refresh. */
 export declare function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string>;
+/** Resolved paths for `mcp bundle`. */
+export interface McpBundlePaths {
+	binaryPath: string;
+	outPath: string;
+	binaryName: string;
+}
+/** Default `dist/<key>` binary and `dist/<key>.mcpb` output under cwd. */
+export declare function defaultMcpBundlePaths(program: CliProgram, cwd?: string): McpBundlePaths;
+/** Generates MCPB `manifest.json` object from program schema and MCP tools. */
+export declare function generateMcpManifest(program: CliProgram, binaryName: string): Record<string, unknown>;
+export interface PackMcpBundleOpts {
+	cwd?: string;
+	binaryPath?: string;
+	outPath?: string;
+}
+/**
+ * Stages manifest + binary (+ optional icon) and writes a `.mcpb` ZIP.
+ * macOS-only v1; requires the compiled binary to exist.
+ */
+export declare function packMcpBundle(program: CliProgram, opts?: PackMcpBundleOpts): string;
 
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.3.14",
+  "version": "3.4.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/dispatch.ts

@@ -9,6 +9,7 @@ import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
 import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
 import { cliPresentationRoot } from "./presentation.ts";
+import { runMcpBundle } from "../mcp/bundle.ts";
 import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 import { cliMcpServeStdio } from "../mcp.ts";
 import { cliInstall } from "../install/index.ts";
@@ -72,12 +73,22 @@ export async function dispatchBuiltin(
       process.stderr.write("MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n");
       process.exit(1);
     }
-    if (pr.path.length !== 1) {
-      process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
-      process.exit(1);
+    const sub = pr.path[1];
+    if (pr.path.length === 1 || sub === "serve") {
+      await cliMcpServeStdio(program);
+      process.exit(0);
     }
-    await cliMcpServeStdio(program);
-    process.exit(0);
+    if (pr.path.length === 2 && sub === "bundle") {
+      try {
+        runMcpBundle(program);
+      } catch (err) {
+        process.stderr.write(err instanceof Error ? err.message + "\n" : "mcp bundle failed.\n");
+        process.exit(1);
+      }
+      process.exit(0);
+    }
+    process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
+    process.exit(1);
   }
 
   if (pr.path[0] === "install") {

package/src/builtins/export.ts

@@ -1,5 +1,7 @@
 import { type CliCapabilities, resolveCapabilities } from "../capabilities.ts";
-import type { CliFallbackMode, CliOption, CliPositional, CliProgram } from "../types.ts";
+import type { CliFallbackMode, CliNode, CliOption, CliPositional, CliProgram } from "../types.ts";
+import { isCliRouter } from "../types.ts";
+import { visibleOptions } from "../hidden.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
@@ -11,6 +13,8 @@ export interface CliSchemaExport {
   key: string;
   description: string;
   notes?: string;
+  /** JSON Schema for structured stdout when set on the leaf `mcpTool`. */
+  outputSchema?: Record<string, unknown>;
   options?: CliOption[];
   fallbackCommand?: string;
   fallbackMode?: CliFallbackMode;
@@ -18,13 +22,11 @@ export interface CliSchemaExport {
   positionals?: CliPositional[];
 }
 
-function exportBuiltinNode(cmd: {
-  key: string;
-  description: string;
-  notes?: string;
-  options?: CliOption[];
-  commands?: CliSchemaExport[];
-}): CliSchemaExport {
+function exportBuiltinNode(cmd: CliNode): CliSchemaExport | null {
+  if (cmd.hidden) {
+    return null;
+  }
+
   const out: CliSchemaExport = {
     key: cmd.key,
     description: cmd.description,
@@ -32,11 +34,23 @@ function exportBuiltinNode(cmd: {
   if ((cmd.notes ?? "").length > 0) {
     out.notes = cmd.notes;
   }
-  if ((cmd.options ?? []).length > 0) {
-    out.options = cmd.options;
+  const options = visibleOptions(cmd.options);
+  if (options.length > 0) {
+    out.options = options;
   }
-  if ((cmd.commands ?? []).length > 0) {
-    out.commands = (cmd.commands ?? []).map((ch) => exportBuiltinNode(ch));
+  if (isCliRouter(cmd)) {
+    if (cmd.fallbackCommand !== undefined) {
+      out.fallbackCommand = cmd.fallbackCommand;
+    }
+    if (cmd.fallbackMode !== undefined) {
+      out.fallbackMode = cmd.fallbackMode;
+    }
+    const children = cmd.commands
+      .map((ch) => exportBuiltinNode(ch))
+      .filter((ch): ch is CliSchemaExport => ch !== null);
+    if (children.length > 0) {
+      out.commands = children;
+    }
   }
   return out;
 }
@@ -45,18 +59,18 @@ function exportBuiltinNode(cmd: {
 export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabilities): CliSchemaExport[] {
   const resolved = caps ?? resolveCapabilities(program);
   const builtins: CliSchemaExport[] = [
-    exportBuiltinNode(cliBuiltinCompletionGroup(program)),
-    exportBuiltinNode(cliBuiltinVersionCommand()),
+    exportBuiltinNode(cliBuiltinCompletionGroup(program))!,
+    exportBuiltinNode(cliBuiltinVersionCommand())!,
   ];
   if (resolved.install) {
-    builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program)));
+    builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program))!);
   }
   const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
   if (docsGroup) {
-    builtins.push(exportBuiltinNode(docsGroup));
+    builtins.push(exportBuiltinNode(docsGroup)!);
   }
   if (resolved.mcp) {
-    builtins.push(exportBuiltinNode(cliBuiltinMcpCommand(program)));
+    builtins.push(exportBuiltinNode(cliBuiltinMcpCommand(program))!);
   }
   return builtins;
 }

package/src/builtins/index.ts

@@ -4,7 +4,7 @@ export { completionFishScript } from "./completion-fish.ts";
 export { cliBuiltinCompletionGroup } from "./completion-group.ts";
 export { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
 export { cliBuiltinMcpCommand } from "./mcp.ts";
-export { cliPresentationRoot, presentationBuiltins } from "./presentation.ts";
+export { cliParseRoot, cliPresentationRoot, parseBuiltins, presentationBuiltins } from "./presentation.ts";
 export { exportPresentationBuiltins, type CliSchemaExport } from "./export.ts";
 export { dispatchBuiltin, builtinInterceptRoot } from "./dispatch.ts";
 export { collectScopes, type ScopeRec } from "./scopes.ts";

package/src/builtins/mcp.ts

@@ -1,9 +1,9 @@
 import { resolveCapabilities } from "../capabilities.ts";
 import { docsEnabled } from "../docs/resolve.ts";
-import { type CliLeaf, type CliProgram } from "../types.ts";
+import { type CliLeaf, type CliProgram, type CliRouter, CliFallbackMode } from "../types.ts";
 
-/** Presence options for the top-level `mcp` built-in (leaf). */
-export function cliBuiltinMcpCommand(program: CliProgram): CliLeaf {
+/** Built-in `mcp` router: bare `myapp mcp` runs stdio (via hidden `serve` fallback); `mcp bundle` packs `.mcpb`. */
+export function cliBuiltinMcpCommand(program: CliProgram): CliRouter {
   const caps = resolveCapabilities(program);
   const lines = [
     "Stdio MCP server. Add to Cursor or Claude:",
@@ -18,10 +18,26 @@ export function cliBuiltinMcpCommand(program: CliProgram): CliLeaf {
   if (docsEnabled(program)) {
     lines.push("Full setup guide: {argsbarg:program} docs mcp");
   }
+
+  const serve: CliLeaf = {
+    key: "serve",
+    hidden: true,
+    description: "Run as an MCP server over stdio for AI agents.",
+    handler: () => {},
+  };
+
+  const bundle: CliLeaf = {
+    key: "bundle",
+    description: "Pack a Claude Desktop MCP Bundle (.mcpb) from dist/<key> (macOS-only v1).",
+    handler: () => {},
+  };
+
   return {
     key: "mcp",
-    description: "Run as an MCP server over stdio for AI agents.",
+    description: "MCP server and bundle tools.",
     notes: lines.join("\n"),
-    handler: () => {},
+    fallbackCommand: "serve",
+    fallbackMode: CliFallbackMode.MissingOnly,
+    commands: [serve, bundle],
   };
 }

package/src/builtins/presentation.ts

@@ -1,5 +1,6 @@
 import type { CliCapabilities } from "../capabilities.ts";
 import { resolveCapabilities } from "../capabilities.ts";
+import { presentationNode, visibleOptions } from "../hidden.ts";
 import type { CliLeaf, CliNode, CliProgram, CliRouter } from "../types.ts";
 import { isCliLeaf, isCliRouter } from "../types.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
@@ -8,8 +9,8 @@ import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
 import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 
-/** Built-in command nodes injected for help, schema, and completions. */
-export function presentationBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
+/** All built-in command nodes for argv parsing (includes hidden builtins). */
+export function parseBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
   const builtins: CliNode[] = [
     cliBuiltinCompletionGroup(program),
     cliBuiltinVersionCommand(),
@@ -27,9 +28,44 @@ export function presentationBuiltins(program: CliProgram, caps: CliCapabilities)
   return builtins;
 }
 
+/** Built-in subtrees visible in help, schema, and completions (hidden builtins omitted). */
+export function presentationBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
+  return parseBuiltins(program, caps).filter((b) => !b.hidden);
+}
+
+/**
+ * Full command tree for argv parsing, including hidden commands and builtins.
+ * Routing programs merge user commands with builtins; leaf programs wrap builtins only.
+ */
+export function cliParseRoot(program: CliProgram): CliRouter {
+  const caps = resolveCapabilities(program);
+  const builtins = parseBuiltins(program, caps);
+
+  if (isCliLeaf(program)) {
+    return {
+      key: program.key,
+      description: program.description,
+      notes: program.notes,
+      options: program.options,
+      commands: builtins,
+    };
+  }
+
+  return {
+    key: program.key,
+    description: program.description,
+    notes: program.notes,
+    options: program.options,
+    fallbackCommand: program.fallbackCommand,
+    fallbackMode: program.fallbackMode,
+    commands: [...program.commands, ...builtins],
+  };
+}
+
 /**
  * Returns a schema suitable for help display, including capability-built-in subtrees.
- * Routing programs get builtins merged; leaf programs are wrapped as a tiny router.
+ * Hidden commands and options are omitted. Routing programs get builtins merged;
+ * leaf programs are wrapped as a tiny router.
  */
 export function cliPresentationRoot(program: CliProgram): CliRouter {
   const caps = resolveCapabilities(program);
@@ -41,19 +77,23 @@ export function cliPresentationRoot(program: CliProgram): CliRouter {
       key: program.key,
       description: program.description,
       notes,
-      options: program.options,
+      options: visibleOptions(program.options),
       commands: builtins,
     };
   }
 
+  const userCommands = program.commands
+    .map((ch) => presentationNode(ch))
+    .filter((ch): ch is CliNode => ch !== null);
+
   return {
     key: program.key,
     description: program.description,
     notes,
-    options: program.options,
+    options: visibleOptions(program.options),
     fallbackCommand: program.fallbackCommand,
     fallbackMode: program.fallbackMode,
-    commands: [...program.commands, ...builtins],
+    commands: [...userCommands, ...builtins],
   };
 }
 
@@ -74,4 +114,3 @@ export function presentationRootNotes(program: CliProgram, caps: CliCapabilities
 
 /** Presentation tree may include builtin leaf stubs. */
 export type CliPresentationNode = CliNode | CliLeaf;
-

package/src/docs/api-guide.test.ts

@@ -105,3 +105,33 @@ test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
   const md = generateApiGuide(fixture);
   expect(md).toContain("Invoke `myapp run`.");
 });
+
+test("generateApiGuide and cliSchemaExport include leaf outputSchema", () => {
+  const fixture: CliProgram = {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo app.",
+    commands: [
+      {
+        key: "run",
+        description: "Run.",
+        outputSchema: {
+          type: "object",
+          properties: { id: { type: "string" } },
+          required: ["id"],
+        },
+        handler: () => {},
+      },
+    ],
+  };
+  const schema = cliSchemaExport(fixture);
+  expect(schema.commands![0]!.outputSchema).toEqual({
+    type: "object",
+    properties: { id: { type: "string" } },
+    required: ["id"],
+  });
+  const md = generateApiGuide(fixture);
+  expect(md).toContain("#### Output");
+  expect(md).toContain('"id"');
+  expect(md).toContain('"type": "string"');
+});

package/src/docs/api-guide.ts

@@ -52,6 +52,20 @@ function formatNotesBlockquote(notes: string, appKey: string): string {
     .join("\n");
 }
 
+/** Markdown section for leaf outputSchema (docs api / skill reference). */
+function formatOutputSchemaSection(schema: Record<string, unknown>): string[] {
+  return [
+    "#### Output",
+    "",
+    "JSON Schema for structured stdout (typically with `--json`, or via MCP when the handler emits JSON):",
+    "",
+    "```json",
+    JSON.stringify(schema, null, 2),
+    "```",
+    "",
+  ];
+}
+
 /** Fallback routing note when present on a router node. */
 function fallbackLine(node: CliSchemaExport): string | null {
   if (node.fallbackCommand === undefined) {
@@ -103,6 +117,10 @@ function renderCommandNode(
     lines.push("");
   }
 
+  if (node.outputSchema !== undefined) {
+    lines.push(...formatOutputSchemaSection(node.outputSchema));
+  }
+
   const children = node.commands ?? [];
   if (children.length > 0) {
     lines.push("#### Subcommands", "");

package/src/help.ts

@@ -8,6 +8,7 @@ style no matter how help is reached.
 */
 
 import { CliNode, CliOption, CliOptionKind, CliPositional, CliRouter, isCliLeaf, isCliRouter } from "./types.ts";
+import { visibleOptions, visibleSubcommands } from "./hidden.ts";
 
 // ── ANSI Style Helpers ────────────────────────────────────────────────────────
 
@@ -372,9 +373,9 @@ function rowsForPositionals(defs: CliPositional[], color: boolean): HelpRow[] {
   return defs.map((p) => ({ label: cliPositionalLabel(p, color), description: p.description }));
 }
 
-/** Table rows for subcommands, sorted by key. */
+/** Table rows for subcommands, sorted by key (hidden commands omitted). */
 function rowsForSubcommands(cmds: CliNode[]): HelpRow[] {
-  return cmds
+  return visibleSubcommands(cmds)
     .sort((a, b) => a.key.localeCompare(b.key))
     .map((c) => ({ label: c.key, description: c.description }));
 }
@@ -420,7 +421,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
       ).join("\n"),
     );
 
-    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color), hw, color);
+    const optBox = renderTableBox("Options", rowsForOptions(visibleOptions(schema.options), color), hw, color);
     if (optBox.length > 0) {
       lines.push("");
       lines.push(optBox.join("\n"));
@@ -470,7 +471,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
     ).join("\n"),
   );
 
-  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color), hw, color);
+  const optBox = renderTableBox("Options", rowsForOptions(visibleOptions(node.options), color), hw, color);
   if (optBox.length > 0) {
     lines.push("");
     lines.push(optBox.join("\n"));