argsbarg 3.3.10 → 3.3.12

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.12] - 2026-06-21
+
+### Changed
+
+- **Agent skills** — `SKILL.md` embeds the `docs api` command reference (body only) instead of a separate `## Commands` bullet catalog.
+
+## [3.3.11] - 2026-06-21
+
+### Added
+
+- **Root help agent hint** — when `docs` is enabled, top-level `-h` includes a Notes line: `Agents: run \`myapp docs skill\` to learn how to use this app`. Root help also renders `program.notes`.
+
 ## [3.3.10] - 2026-06-21
 
 ### Changed
@@ -311,7 +323,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.10...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.12...HEAD
+[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
 [3.3.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.9
 [3.3.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.8

package/docs/ai-skills.md

@@ -31,7 +31,7 @@ For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true
 
 ## Generated content
 
-- **`SKILL.md`** — YAML frontmatter, when-to-use guidance, shell command catalog, pitfalls
+- **`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
 
 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 catalog for agents |
+| **`myapp install --skill`** | Static shell command reference for agents (same body as `docs api`) |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
-Command catalog lines reuse MCP tool descriptions. See [cli-program.md](cli-program.md).
+Command reference in skills reuses the `docs api` command tree. See [cli-program.md](cli-program.md).
 
 See also:
 

package/docs/bundled-docs.md

@@ -35,6 +35,8 @@ 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`.
+
 ## Configuration
 
 | Field | Default | Purpose |
@@ -82,7 +84,7 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 
 | Channel | Role |
 | --- | --- |
-| `install --skill` | Writes shell command catalog + `reference.md` to disk |
+| `install --skill` | Writes `SKILL.md` (API command reference) + `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.10",
+  "version": "3.3.12",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/builtins.test.ts

@@ -80,6 +80,15 @@ describe("presentation root", () => {
     const root = cliPresentationRoot(fixture);
     expect(root.commands?.map((c) => c.key)).toContain("version");
   });
+
+  test("root notes include agent hint when docs enabled", () => {
+    const withDocs: CliProgram = {
+      ...fixture,
+      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");
+  });
 });
 
 describe("completion emitters", () => {

package/src/builtins/presentation.ts

@@ -34,11 +34,13 @@ export function presentationBuiltins(program: CliProgram, caps: CliCapabilities)
 export function cliPresentationRoot(program: CliProgram): CliRouter {
   const caps = resolveCapabilities(program);
   const builtins = presentationBuiltins(program, caps);
+  const notes = presentationRootNotes(program, caps);
 
   if (isCliLeaf(program)) {
     return {
       key: program.key,
       description: program.description,
+      notes,
       options: program.options,
       commands: builtins,
     };
@@ -47,7 +49,7 @@ export function cliPresentationRoot(program: CliProgram): CliRouter {
   return {
     key: program.key,
     description: program.description,
-    notes: program.notes,
+    notes,
     options: program.options,
     fallbackCommand: program.fallbackCommand,
     fallbackMode: program.fallbackMode,
@@ -55,5 +57,22 @@ export function cliPresentationRoot(program: CliProgram): CliRouter {
   };
 }
 
+/** Root help notes: consumer `program.notes` plus agent discovery when `docs` is enabled. */
+export function presentationRootNotes(program: CliProgram, caps: CliCapabilities): string | undefined {
+  const parts: string[] = [];
+  if ((program.notes ?? "").trim().length > 0) {
+    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`);
+  }
+  if (parts.length === 0) {
+    return undefined;
+  }
+  return parts.join("\n\n");
+}
+
 /** Presentation tree may include builtin leaf stubs. */
 export type CliPresentationNode = CliNode | CliLeaf;
+

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

@@ -1,7 +1,7 @@
 import { expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
 import { CliOptionKind } from "../types.ts";
-import { generateApiGuide } from "./api-guide.ts";
+import { generateApiGuide, generateApiGuideBody } from "./api-guide.ts";
 import { cliSchemaExport } from "../schema.ts";
 
 const nestedFixture: CliProgram = {
@@ -45,6 +45,14 @@ const nestedFixture: CliProgram = {
   ],
 };
 
+test("generateApiGuideBody matches command section of full API guide", () => {
+  const body = generateApiGuideBody(nestedFixture);
+  const full = generateApiGuide(nestedFixture);
+  expect(full).toContain(body.trimEnd());
+  expect(body).toContain("## `nested.ts stat`");
+  expect(body).not.toContain("CLI API reference");
+});
+
 test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
   const md = generateApiGuide(nestedFixture);
   const schema = cliSchemaExport(nestedFixture);

package/src/docs/api-guide.ts

@@ -117,6 +117,14 @@ function renderCommandNode(
   }
 }
 
+/** Command-tree markdown shared by `docs api` and generated agent skills (no API doc header). */
+export function generateApiGuideBody(program: CliProgram): string {
+  const schema = cliSchemaExport(program);
+  const lines: string[] = [];
+  renderCommandNode(program.key, [], schema, lines);
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
 /** Generates markdown API reference from the same export as `docs schema`. */
 export function generateApiGuide(program: CliProgram): string {
   const schema = cliSchemaExport(program);
@@ -133,6 +141,6 @@ export function generateApiGuide(program: CliProgram): string {
     lines.push(formatNotesBlockquote(schema.notes, program.key), "");
   }
 
-  renderCommandNode(program.key, [], schema, lines);
+  lines.push(generateApiGuideBody(program).trimEnd(), "");
   return `${lines.join("\n").trimEnd()}\n`;
 }

package/src/docs/docs.test.ts

@@ -152,7 +152,8 @@ 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("## Commands");
+  expect(result.stdout).toContain("#### Options");
+  expect(result.stdout).not.toContain("## Commands");
   expect(result.stdout).not.toContain("mcp.json");
 });
 

package/src/help.ts

@@ -381,6 +381,21 @@ function rowsForSubcommands(cmds: CliNode[]): HelpRow[] {
 
 // ── Main Help Render ──────────────────────────────────────────────────────────
 
+function appendNotesBox(
+  lines: string[],
+  notes: string | undefined,
+  appKey: string,
+  hw: number,
+  color: boolean,
+): void {
+  if ((notes ?? "").length === 0) {
+    return;
+  }
+  const resolved = cliResolveNotes(notes!, appKey);
+  lines.push("");
+  lines.push(renderTextBox("Notes", wrapText(resolved, hw - 4), hw, color).join("\n"));
+}
+
 /**
  * Renders full help for the app root or a nested command, following `helpPath` from the root key.
  * `useStderr` is reserved for call-site consistency; width and color use stdout TTY.
@@ -416,6 +431,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
         renderTableBox("Commands", rowsForSubcommands(schema.commands ?? []), hw, color).join("\n"),
       );
     }
+    appendNotesBox(lines, schema.notes, schema.key, hw, color);
     return lines.join("\n") + "\n\n";
   }
 
@@ -479,11 +495,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
   }
 
   if ((node.notes ?? "").length > 0) {
-    const resolved = cliResolveNotes(node.notes!, schema.key);
-    lines.push("");
-    lines.push(
-      renderTextBox("Notes", wrapText(resolved, hw - 4), hw, color).join("\n"),
-    );
+    appendNotesBox(lines, node.notes, schema.key, hw, color);
   }
 
   return lines.join("\n") + "\n\n";

package/src/index.test.ts

@@ -678,6 +678,50 @@ test("root help omits legacy --schema flag", () => {
   expect(help).not.toContain("--schema");
 });
 
+test("root help shows agent docs hint when docs enabled", () => {
+  const root = testProgram({
+    key: "myapp",
+    version: "1.0.0",
+    description: "demo",
+    docs: {
+      enabled: true,
+      topics: { readme: { text: "# readme\n" } },
+    },
+    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");
+});
+
+test("root help omits agent hint when docs disabled", () => {
+  const root = testProgram({
+    key: "myapp",
+    version: "1.0.0",
+    description: "demo",
+    commands: [{ key: "run", description: "Run.", handler: () => {} }],
+  });
+  const help = cliHelpRender(cliPresentationRoot(root), [], false);
+  expect(help).not.toContain("Agents:");
+  expect(help).not.toContain("docs skill");
+});
+
+test("root help includes program notes and agent hint", () => {
+  const root = testProgram({
+    key: "myapp",
+    version: "1.0.0",
+    description: "demo",
+    notes: "See `{argsbarg:program} docs readme` for the user guide.",
+    docs: {
+      enabled: true,
+      topics: { readme: { text: "# readme\n" } },
+    },
+    commands: [{ key: "run", description: "Run.", handler: () => {} }],
+  });
+  const help = cliHelpRender(cliPresentationRoot(root), [], false);
+  expect(help).toContain("See `myapp docs readme` for the user guide.");
+  expect(help).toContain("myapp docs skill");
+});
+
 const nestedMcpFixture = testProgram({
   key: "nested.ts",
   description: "Nested groups demo.",
@@ -1764,12 +1808,15 @@ 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 command catalog", () => {
+test("generateSkillBundle includes frontmatter and API command reference", () => {
   const bundle = generateSkillBundle(nestedMcpFixture, "cursor");
   expect(bundle.dirName).toBe("nested_ts");
   expect(bundle.skillMd).toMatch(/^---\nname: nested_ts\n/);
-  expect(bundle.skillMd).toContain("stat owner lookup");
+  expect(bundle.skillMd).toContain("`nested.ts stat owner lookup`");
+  expect(bundle.skillMd).toContain("#### Options");
   expect(bundle.skillMd).toContain("Invoke via shell:");
+  expect(bundle.skillMd).not.toContain("## Commands");
+  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");
@@ -1789,7 +1836,7 @@ 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("stat owner lookup");
+    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("`nested.ts stat owner lookup`");
     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 { collectOptionDefs } from "../parse.ts";
+import { generateApiGuideBody } from "../docs/api-guide.ts";
 import { cliSchemaJson } from "../schema.ts";
 import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
-import { CliProgram, CliOptionKind } from "../types.ts";
+import { CliProgram } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
 
@@ -31,31 +31,10 @@ function skillDescription(root: CliProgram): string {
   return truncate(desc, 1024);
 }
 
-/** Formats one command line for the catalog section. */
-function formatCommandEntry(root: CliProgram, tool: ReturnType<typeof collectMcpTools>[number]): string {
-  const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
-  let line = `- **\`${cliPath}\`** — ${tool.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(", ")})`;
-  }
-  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[] = [
     "---",
@@ -75,20 +54,12 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
     "Invoke via shell:",
     "",
-  ];
-
-  lines.push("```bash", `${root.key} <subcommand> [options] [args]`, "```", "", "## 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(
+    "```bash",
+    `${root.key} <subcommand> [options] [args]`,
+    "```",
+    "",
+    generateApiGuideBody(root).trimEnd(),
+    "",
     "## Pitfalls",
     "",
     "- Use `--` before tokens that look like flags when they are positional arguments.",
@@ -98,7 +69,7 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
     "See `reference.md` in this skill directory for the full `docs schema` JSON export.",
     "",
-  );
+  ];
 
   if (target === "cursor") {
     lines.push(