argsbarg 3.3.12 → 3.3.14

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.14] - 2026-06-21
+
+### Changed
+
+- **Generated notes** — deduplicated agent, docs, MCP, and completion help; each topic owns its guidance in one place.
+
+## [3.3.13] - 2026-06-21
+
+### Changed
+
+- **Agent skills** — `SKILL.md` is a compact command index; `reference.md` holds the full `docs api` guide. `docs skill` notes recommend `install --skill` for the optimized persisted bundle.
+
 ## [3.3.12] - 2026-06-21
 
 ### Changed
@@ -323,7 +335,9 @@ 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.12...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.14...HEAD
+[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
 [3.3.11]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.11
 [3.3.10]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.10

package/docs/ai-skills.md

@@ -31,8 +31,8 @@ For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true
 
 ## Generated content
 
-- **`SKILL.md`** — YAML frontmatter, when-to-use guidance, the same command reference as `docs api` (without the API doc header), pitfalls
-- **`reference.md`** — full `docs schema` JSON export
+- **`SKILL.md`** — YAML frontmatter, compact command index, pitfalls, and a pointer to `reference.md`
+- **`reference.md`** — full `docs api` markdown reference
 
 Installed files include an HTML comment hint (`Generated by myapp install --skill; do not edit.`) after SKILL.md frontmatter and at the top of `reference.md`.
 
@@ -43,10 +43,10 @@ Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tool
 | Mechanism | Role |
 | --- | --- |
 | **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`myapp install --skill`** | Static shell command reference for agents (same body as `docs api`) |
+| **`myapp install --skill`** | Persists optimized skill bundle (`SKILL.md` index + `reference.md` full API) |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
-Command reference in skills reuses the `docs api` command tree. See [cli-program.md](cli-program.md).
+`SKILL.md` is the routing index; `reference.md` matches `docs api`. Prefer `install --skill` over `docs skill` for agents. See [cli-program.md](cli-program.md).
 
 See also:
 

package/docs/bundled-docs.md

@@ -35,7 +35,7 @@ myapp docs readme --save   # write ./docs/readme.md
 myapp docs schema --save   # write ./docs/schema.json
 ```
 
-When `docs` is enabled, top-level `myapp --help` includes a Notes line: `Agents: run \`myapp docs skill\` to learn how to use this app`.
+When `docs` is enabled, top-level `myapp --help` points agents at `myapp docs skill`. The `docs skill` subcommand description recommends `install --skill` for a persisted bundle.
 
 ## Configuration
 
@@ -68,7 +68,7 @@ When `docs.enabled` is `true`:
 
 - **`docs schema`** — same JSON as the former root `--schema` flag (handlers omitted; built-in subtrees included for leaf roots).
 - **`docs api`** — markdown rendering of the same command tree (options, positionals, subcommands, fallback routing).
-- **`docs skill`** — prints generated Cursor `SKILL.md` content (same prose as `install --skill`, without writing files).
+- **`docs skill`** — prints the compact `SKILL.md` index. Prefer `install --skill --yes` for agents (persists index + full API in `reference.md`).
 
 ## MCP guide (`docs mcp`)
 
@@ -84,7 +84,7 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 
 | Channel | Role |
 | --- | --- |
-| `install --skill` | Writes `SKILL.md` (API command reference) + `reference.md` to disk |
+| `install --skill` | Writes compact `SKILL.md` + full-API `reference.md` to disk |
 | `docs skill` | Print generated `SKILL.md` to stdout |
 | `docs api` | Print command tree markdown to stdout |
 | `docs schema` | Print command tree JSON to stdout |

package/package.json

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

package/src/builtins/builtins.test.ts

@@ -57,9 +57,14 @@ describe("builtins help copy", () => {
   });
 
   test("mcp builtin description is user-facing", () => {
-    const mcp = cliBuiltinMcpCommand();
+    const withDocs: CliProgram = {
+      ...fixture,
+      docs: { enabled: true, topics: { readme: { text: "# r\n" } } },
+    };
+    const mcp = cliBuiltinMcpCommand(withDocs);
     expect(mcp.description).toContain("MCP server");
-    expect(mcp.notes).toContain('["mcp"]');
+    expect(mcp.notes).toContain("install --mcp --yes");
+    expect(mcp.notes).toContain("docs mcp");
   });
 });
 
@@ -87,7 +92,8 @@ describe("presentation root", () => {
       docs: { enabled: true, topics: { readme: { text: "# r\n" } } },
     };
     const root = cliPresentationRoot(withDocs);
-    expect(root.notes).toContain("Agents: run `myapp docs skill` to learn how to use this app");
+    expect(root.notes).toContain("For AI agents: `myapp docs skill`.");
+    expect(root.notes).not.toContain("install --skill");
   });
 });
 

package/src/builtins/completion-group.ts

@@ -1,10 +1,13 @@
-import { type CliLeaf, type CliNode, type CliRouter } from "../types.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import { type CliLeaf, type CliProgram, type CliRouter } from "../types.ts";
 
 /**
  * Builds the static `completion` / `bash` / `zsh` / `fish` command subtree (merged into the program root at runtime).
  */
-export function cliBuiltinCompletionGroup(appName: string): CliRouter {
-  return {
+export function cliBuiltinCompletionGroup(program: CliProgram): CliRouter {
+  const appName = program.key;
+  const caps = resolveCapabilities(program);
+  const router: CliRouter = {
     key: "completion",
     description: "Generate the autocompletion script for shells.",
     commands: [
@@ -12,15 +15,10 @@ export function cliBuiltinCompletionGroup(appName: string): CliRouter {
         key: "bash",
         description: "Print a bash tab-completion script.",
         notes:
-          "Output is the whole script.\n" +
-          "Pipe it to a file, or feed it straight into your shell.\n\n" +
-          "To keep it across restarts, save it and source that file from ~/.bashrc.\n\n" +
-          "For example:\n\n" +
-          `echo 'eval \"$(${appName} completion bash)\"' >> ~/.bashrc\n` +
-          `\nor\n` +
+          "Manual install:\n\n" +
           `  ${appName} completion bash > ~/.bash_completion.d/${appName}\n` +
           `  echo 'source ~/.bash_completion.d/${appName}' >> ~/.bashrc\n\n` +
-          "To try it only in this session (nothing written to disk):\n" +
+          "Try this session only:\n\n" +
           `  source <(${appName} completion bash)`,
         handler: () => {},
       },
@@ -28,23 +26,26 @@ export function cliBuiltinCompletionGroup(appName: string): CliRouter {
         key: "zsh",
         description: "Print a zsh tab-completion script.",
         notes:
-          "Output is the whole script.\n\n" +
-          `fpath setup: ${appName} completion zsh > ~/.zsh/completions/_${appName}\n\n` +
-          `source setup: echo 'eval \"$(${appName} completion zsh)\"' >> ~/.zshrc\n\n` +
-          "To try it only in this session (nothing written to disk):\n" +
-          `  eval \"$(${appName} completion zsh)\"`,
+          "Manual install:\n\n" +
+          `  ${appName} completion zsh > ~/.zsh/completions/_${appName}\n\n` +
+          "Ensure ~/.zsh/completions is on your fpath, then restart zsh.\n\n" +
+          "Try this session only:\n\n" +
+          `  eval "$(${appName} completion zsh)"`,
         handler: () => {},
       },
       {
         key: "fish",
         description: "Print a fish tab-completion script.",
         notes:
-          "Output is the whole script.\n\n" +
-          "Install:\n" +
+          "Manual install:\n\n" +
           `  ${appName} completion fish > ~/.config/fish/completions/${appName}.fish\n\n` +
           "Fish loads completions from that directory automatically.",
         handler: () => {},
       },
     ],
   };
+  if (caps.install) {
+    router.notes = `Install for all shells:\n\n  ${appName} install --completions --yes`;
+  }
+  return router;
 }

package/src/builtins/dispatch.ts

@@ -110,7 +110,7 @@ export function builtinInterceptRoot(
       parseRoot: {
         key: program.key,
         description: program.description,
-        commands: [completionGroup(program.key)],
+        commands: [completionGroup(program)],
       },
       isLeafCompletionIntercept: true,
     };
@@ -132,7 +132,7 @@ export function builtinInterceptRoot(
       parseRoot: {
         key: program.key,
         description: program.description,
-        commands: [cliBuiltinMcpCommand()],
+        commands: [cliBuiltinMcpCommand(program)],
       },
       isLeafCompletionIntercept: false,
     };

package/src/builtins/export.ts

@@ -45,7 +45,7 @@ function exportBuiltinNode(cmd: {
 export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabilities): CliSchemaExport[] {
   const resolved = caps ?? resolveCapabilities(program);
   const builtins: CliSchemaExport[] = [
-    exportBuiltinNode(cliBuiltinCompletionGroup(program.key)),
+    exportBuiltinNode(cliBuiltinCompletionGroup(program)),
     exportBuiltinNode(cliBuiltinVersionCommand()),
   ];
   if (resolved.install) {
@@ -56,7 +56,7 @@ export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabi
     builtins.push(exportBuiltinNode(docsGroup));
   }
   if (resolved.mcp) {
-    builtins.push(exportBuiltinNode(cliBuiltinMcpCommand()));
+    builtins.push(exportBuiltinNode(cliBuiltinMcpCommand(program)));
   }
   return builtins;
 }

package/src/builtins/install.ts

@@ -117,7 +117,8 @@ export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
     "Remove everything installed with --all:",
     `  ${app} install --uninstall --all --yes`,
     "",
-    "Use --dry to preview changes, --json for machine-readable output.",
+    "Use --dry to preview changes without writing files.",
+    "Use --json for machine-readable output.",
   );
   return {
     key: "install",

package/src/builtins/mcp.ts

@@ -1,13 +1,27 @@
-import { type CliLeaf } from "../types.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import { docsEnabled } from "../docs/resolve.ts";
+import { type CliLeaf, type CliProgram } from "../types.ts";
 
 /** Presence options for the top-level `mcp` built-in (leaf). */
-export function cliBuiltinMcpCommand(): CliLeaf {
+export function cliBuiltinMcpCommand(program: CliProgram): CliLeaf {
+  const caps = resolveCapabilities(program);
+  const lines = [
+    "Stdio MCP server. Add to Cursor or Claude:",
+    "",
+    "  command: {argsbarg:program}",
+    "  args: mcp",
+    "",
+  ];
+  if (caps.install) {
+    lines.push("Or:", "", "  {argsbarg:program} install --mcp --yes", "");
+  }
+  if (docsEnabled(program)) {
+    lines.push("Full setup guide: {argsbarg:program} docs mcp");
+  }
   return {
     key: "mcp",
     description: "Run as an MCP server over stdio for AI agents.",
-    notes:
-      "Configure MCP clients with `command` set to this program name and `args` set to `[\"mcp\"]`.\n\n" +
-      "See docs/mcp.md for setup details.",
+    notes: lines.join("\n"),
     handler: () => {},
   };
 }

package/src/builtins/presentation.ts

@@ -11,7 +11,7 @@ import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 /** Built-in command nodes injected for help, schema, and completions. */
 export function presentationBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
   const builtins: CliNode[] = [
-    cliBuiltinCompletionGroup(program.key),
+    cliBuiltinCompletionGroup(program),
     cliBuiltinVersionCommand(),
   ];
   if (caps.install) {
@@ -22,7 +22,7 @@ export function presentationBuiltins(program: CliProgram, caps: CliCapabilities)
     builtins.push(docsGroup);
   }
   if (caps.mcp) {
-    builtins.push(cliBuiltinMcpCommand());
+    builtins.push(cliBuiltinMcpCommand(program));
   }
   return builtins;
 }
@@ -64,8 +64,7 @@ export function presentationRootNotes(program: CliProgram, caps: CliCapabilities
     parts.push(program.notes!.trim());
   }
   if (caps.docs) {
-    const cmd = `${program.key} docs skill`;
-    parts.push(`Agents: run \`${cmd}\` to learn how to use this app`);
+    parts.push(`For AI agents: \`${program.key} docs skill\`.`);
   }
   if (parts.length === 0) {
     return undefined;

package/src/docs/builtin.ts

@@ -36,6 +36,11 @@ function docsLeaf(program: CliProgram, key: string, description: string): CliLea
   };
 }
 
+/** Help notes for the `docs` router. */
+function docsRouterNotes(): string {
+  return "Topics print to stdout. Add --save to write files under ./docs/.";
+}
+
 /** Built-in `docs` router with bundled topic subcommands. */
 export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
   const docs = program.docs!;
@@ -54,13 +59,14 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
 
   leaves.push(
     docsLeaf(program, "schema", "Print the full command tree as JSON."),
-    docsLeaf(program, "api", "Print the command tree as markdown."),
-    docsLeaf(program, "skill", "Print generated Cursor SKILL.md content."),
+    docsLeaf(program, "api", "Print the full command reference as markdown."),
+    docsLeaf(program, "skill", "Print a reference agent SKILL, use `install --skill` for optimized."),
   );
 
   return {
     key: "docs",
     description: docs.description ?? DOCS_ROUTER_DESCRIPTION,
+    notes: docsRouterNotes(),
     options: [DOCS_SAVE_OPTION],
     fallbackCommand: docsEffectiveDefaultTopic(docs),
     fallbackMode: CliFallbackMode.MissingOnly,

package/src/docs/docs.test.ts

@@ -152,11 +152,26 @@ test("docs skill prints Cursor SKILL.md", async () => {
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("---");
   expect(result.stdout).toContain("name: myapp");
-  expect(result.stdout).toContain("#### Options");
-  expect(result.stdout).not.toContain("## Commands");
+  expect(result.stdout).toContain("## Commands");
+  expect(result.stdout).toContain("For full detail, open `reference.md`");
+  expect(result.stdout).not.toContain("#### Options");
   expect(result.stdout).not.toContain("mcp.json");
 });
 
+test("docs skill help recommends install --skill", async () => {
+  const presentation = cliPresentationRoot(docsFixture());
+  const docsNode = presentation.commands.find((c) => c.key === "docs");
+  expect(docsNode && "commands" in docsNode).toBe(true);
+  if (docsNode && "commands" in docsNode) {
+    const skill = docsNode.commands.find((c) => c.key === "skill");
+    expect(skill?.description).toContain("reference agent SKILL");
+    expect(skill?.description).toContain("install --skill");
+    expect(skill?.notes).toBeUndefined();
+    expect(docsNode.notes).toContain("--save");
+    expect(docsNode.notes).not.toContain("install --skill");
+  }
+});
+
 test("presentation includes docs schema and skill", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");

package/src/index.test.ts

@@ -496,7 +496,7 @@ test("leaf completion help prints correctly", async () => {
   const out = stdout.toString();
   expect(exitCode).toBe(0);
   expect(out).toContain("Show help for this command.");
-  expect(out).toContain("Output is the whole script.");
+  expect(out).toContain("Manual install:");
   expect(stderr.toString()).toBe("");
 });
 
@@ -658,7 +658,7 @@ test("docs help lists schema, api, and skill subcommands", () => {
   expect(help).toContain("api");
   expect(help).toContain("markdown");
   expect(help).toContain("skill");
-  expect(help).toContain("SKILL.md");
+  expect(help).toContain("reference agent SKILL");
 });
 
 test("root help omits legacy --schema flag", () => {
@@ -690,7 +690,8 @@ test("root help shows agent docs hint when docs enabled", () => {
     commands: [{ key: "run", description: "Run.", handler: () => {} }],
   });
   const help = cliHelpRender(cliPresentationRoot(root), [], false);
-  expect(help).toContain("Agents: run `myapp docs skill` to learn how to use this app");
+  expect(help).toContain("For AI agents: `myapp docs skill`.");
+  expect(help).not.toContain("install --skill");
 });
 
 test("root help omits agent hint when docs disabled", () => {
@@ -1808,22 +1809,24 @@ test("install config on non-root node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/install is only supported on the program root/);
 });
 
-test("generateSkillBundle includes frontmatter and API command reference", () => {
+test("generateSkillBundle includes frontmatter and compact command index", () => {
   const bundle = generateSkillBundle(nestedMcpFixture, "cursor");
   expect(bundle.dirName).toBe("nested_ts");
   expect(bundle.skillMd).toMatch(/^---\nname: nested_ts\n/);
-  expect(bundle.skillMd).toContain("`nested.ts stat owner lookup`");
-  expect(bundle.skillMd).toContain("#### Options");
+  expect(bundle.skillMd).toContain("## Commands");
+  expect(bundle.skillMd).toContain("`nested.ts stat owner lookup <path>`");
   expect(bundle.skillMd).toContain("Invoke via shell:");
-  expect(bundle.skillMd).not.toContain("## Commands");
+  expect(bundle.skillMd).toContain("For full detail, open `reference.md`");
+  expect(bundle.skillMd).not.toContain("#### Options");
   expect(bundle.skillMd).not.toContain("CLI API reference");
   expect(bundle.skillMd).not.toContain("mcp.json");
   expect(bundle.skillMd).not.toContain("Prefer MCP");
   expect(bundle.skillMd).not.toContain("tools/call");
   expect(bundle.skillMd).not.toContain("Generated by");
-  expect(bundle.referenceMd).toContain("```json");
+  expect(bundle.referenceMd).toContain("CLI API reference");
+  expect(bundle.referenceMd).toContain("#### Options");
   expect(bundle.referenceMd).not.toContain("Generated by");
-  expect(() => JSON.parse(bundle.referenceMd.match(/```json\n([\s\S]*?)\n```/)![1]!)).not.toThrow();
+  expect(bundle.referenceMd).not.toContain("```json");
 });
 
 test("cliSkillInstall writes project Cursor skill files", () => {
@@ -1836,7 +1839,8 @@ test("cliSkillInstall writes project Cursor skill files", () => {
     const skillDir = join(cwd, ".cursor", "skills", "nested_ts");
     expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true);
     expect(existsSync(join(skillDir, "reference.md"))).toBe(true);
-    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("`nested.ts stat owner lookup`");
+    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("## Commands");
+    expect(readFileSync(join(skillDir, "reference.md"), "utf8")).toContain("CLI API reference");
     const skillText = readFileSync(join(skillDir, "SKILL.md"), "utf8");
     expect(skillText.startsWith("---\n")).toBe(true);
     const hint = "<!-- Generated by nested.ts install --skill; do not edit. -->";

package/src/skill/generate.ts

@@ -2,10 +2,10 @@
 This module generates Agent Skills content (SKILL.md + reference.md) from a CLI schema.
 */
 
-import { generateApiGuideBody } from "../docs/api-guide.ts";
-import { cliSchemaJson } from "../schema.ts";
-import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
-import { CliProgram } from "../types.ts";
+import { generateApiGuide } from "../docs/api-guide.ts";
+import { collectOptionDefs } from "../parse.ts";
+import { collectMcpTools, sanitizeToolSegment, type McpToolDef } from "../mcp/tools.ts";
+import { CliProgram, CliOptionKind } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
 
@@ -31,10 +31,47 @@ function skillDescription(root: CliProgram): string {
   return truncate(desc, 1024);
 }
 
+/** CLI path with required single-slot positionals for the compact catalog. */
+function commandCatalogPath(root: CliProgram, tool: McpToolDef): string {
+  const base = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
+  const slots = (tool.leaf.positionals ?? [])
+    .filter((p) => (p.argMin ?? 1) > 0 && (p.argMax ?? 1) === 1)
+    .map((p) => `<${p.name}>`);
+  if (slots.length === 0) {
+    return base;
+  }
+  return `${base} ${slots.join(" ")}`;
+}
+
+/** Formats one command line for the SKILL.md index (details live in reference.md). */
+function formatCommandEntry(root: CliProgram, tool: McpToolDef): string {
+  const cliPath = commandCatalogPath(root, tool);
+  let line = `- **\`${cliPath}\`** — ${tool.leaf.description}`;
+  const opts = collectOptionDefs(root, tool.path);
+  const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
+  if (flags.length > 0) {
+    line += ` (flags: ${flags.join(", ")})`;
+  }
+  const enums = opts.filter((o) => o.kind === CliOptionKind.Enum && o.choices?.length);
+  for (const e of enums) {
+    line += ` (\`--${e.name}\`: ${e.choices!.join(" | ")})`;
+  }
+  const varargs = (tool.leaf.positionals ?? []).filter((p) => (p.argMax ?? 1) === 0);
+  if (varargs.length > 0) {
+    line += ` (varargs: ${varargs.map((p) => p.name).join(", ")})`;
+  }
+  const env = tool.leaf.mcpTool?.requiresEnv;
+  if (env && env.length > 0) {
+    line += ` [requires env: ${env.join(", ")}]`;
+  }
+  return line;
+}
+
 /** Builds SKILL.md body for the given target. */
 function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): string {
   const name = sanitizeToolSegment(root.key);
   const description = skillDescription(root);
+  const tools = collectMcpTools(root);
 
   const lines: string[] = [
     "---",
@@ -46,10 +83,6 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
     root.description,
     "",
-    "## When to use",
-    "",
-    `Use this skill when working with **${root.key}** — shell commands and automation for this application.`,
-    "",
     "## Execution",
     "",
     "Invoke via shell:",
@@ -58,18 +91,30 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     `${root.key} <subcommand> [options] [args]`,
     "```",
     "",
-    generateApiGuideBody(root).trimEnd(),
+    "## Commands",
     "",
+  ];
+
+  if (tools.length === 0) {
+    lines.push("(No leaf commands in schema.)", "");
+  } else {
+    for (const tool of tools) {
+      lines.push(formatCommandEntry(root, tool));
+    }
+    lines.push("");
+  }
+
+  lines.push(
     "## Pitfalls",
     "",
-    "- Use `--` before tokens that look like flags when they are positional arguments.",
-    "- Required environment variables are listed per command in descriptions (`requires env`).",
+    "- Pass `--` before arguments that look like flags.",
+    "- Commands marked `[requires env: ...]` need those variables set in the shell.",
     "",
     "## Reference",
     "",
-    "See `reference.md` in this skill directory for the full `docs schema` JSON export.",
+    `For full detail, open \`reference.md\` in this skill directory (same as \`${root.key} docs api\`).`,
     "",
-  ];
+  );
 
   if (target === "cursor") {
     lines.push(
@@ -96,18 +141,9 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
   return lines.join("\n");
 }
 
-/** Builds reference.md with pretty-printed schema JSON. */
+/** Builds reference.md with the full `docs api` markdown guide. */
 function buildReferenceMd(root: CliProgram): string {
-  return [
-    `# ${root.key} — CLI reference`,
-    "",
-    "Generated from the program `docs schema` export. Handlers and runtime-only nodes are omitted.",
-    "",
-    "```json",
-    cliSchemaJson(root).trimEnd(),
-    "```",
-    "",
-  ].join("\n");
+  return generateApiGuide(root);
 }
 
 /** Generates SKILL.md and reference.md for Cursor or Claude Code. */