argsbarg 3.3.4 → 3.3.6

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.6] - 2026-06-21
+
+### Added
+
+- **`install --skill`** — installed `SKILL.md` and `reference.md` include a `Generated by … install --skill` HTML comment (after SKILL.md frontmatter).
+
+## [3.3.5] - 2026-06-21
+
+### Changed
+
+- **`notes` placeholders** — use `{argsbarg:program}` for the root program key in consumer `notes`. Built-in copy (e.g. `install` notes) interpolates the program key directly.
+
+### Removed
+
+- **`{app}` notes placeholder** — use `{argsbarg:program}` instead.
+
+### Fixed
+
+- **`docs schema` / `docs api` / MCP schema resource** — `{argsbarg:program}` in `notes` is resolved to the program key (same as help). Schema export uses the root program key for built-in subtrees on nested leaves.
+
 ## [3.3.4] - 2026-06-21
 
 
@@ -262,7 +282,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.4...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.6...HEAD
+[3.3.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.6
+[3.3.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.5
 [3.3.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.4
 [3.3.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.3
 [3.3.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.2

package/docs/ai-skills.md

@@ -34,6 +34,8 @@ For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true
 - **`SKILL.md`** — YAML frontmatter, when-to-use guidance, shell command catalog, 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`.
+
 Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tools/call` guidance. Use **`myapp docs mcp`** (when `docs` and `mcpServer` are enabled) or connect the MCP server for agent execution.
 
 ## MCP vs skills vs docs

package/docs/bundled-docs.md

@@ -102,4 +102,4 @@ Pass **`--save`** on `docs` or any docs subcommand to write files under **`./doc
 | `docs api --save` | `./docs/api.md` |
 | `docs skill --save` | `./docs/skill.md` |
 
-Argsbarg-generated markdown (`mcp`, `api`, `skill`) includes a `Generated by … docs … --save` HTML comment (`skill` places it after YAML frontmatter so parsers still work). Consumer topic files and `schema.json` are written as-is.
+Argsbarg-generated markdown (`mcp`, `api`, `skill`) includes a `Generated by … docs … --save` HTML comment (`skill` places it after YAML frontmatter so parsers still work). `schema.json` and argsbarg-generated markdown resolve `{argsbarg:program}` in `notes` to the program key. Consumer-authored topic files are written as-is.

package/examples/nested.ts

@@ -79,7 +79,7 @@ const cli = {
     {
       key: "read",
       description: "Print the first line of each file.",
-      notes: "Pass one or more file paths. {app} prints the first line of each.",
+      notes: "Pass one or more file paths. The program prints the first line of each.",
       positionals: [
         {
           name: "files",

package/index.d.ts

@@ -224,7 +224,7 @@ export interface CliNodeBase {
 	key: string;
 	/** Short description shown in help. */
 	description: string;
-	/** Additional notes shown in help (supports {app} placeholder). */
+	/** Additional notes shown in help (`{argsbarg:program}` → program key). */
 	notes?: string;
 	/** Global or command-level flags/options. */
 	options?: CliOption[];

package/package.json

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

package/src/builtins/install.ts

@@ -85,19 +85,20 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
 
 /** Builds the `install` built-in command. */
 export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
+  const app = root.key;
   return {
     key: "install",
     description: "Install the binary, shell completions, agent skills, and MCP config to your user environment.",
     notes:
       "First-time setup:\n" +
-      `  {app} install --all --yes\n\n` +
+      `  ${app} install --all --yes\n\n` +
       "Refresh after upgrading:\n" +
-      `  {app} install --reinstall\n` +
-      `  {app} update\n\n` +
+      `  ${app} install --reinstall\n` +
+      `  ${app} update\n\n` +
       "See what is installed:\n" +
-      `  {app} install --status\n\n` +
+      `  ${app} install --status\n\n` +
       "Remove everything installed with --all:\n" +
-      `  {app} install --uninstall --all --yes\n\n` +
+      `  ${app} install --uninstall --all --yes\n\n` +
       "Use --dry to preview changes, --json for machine-readable output.",
     options: installBuiltinOptions(root),
     handler: () => {},

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

@@ -53,3 +53,33 @@ test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
   expect(md).toContain("`<path>`");
   expect(schema.commands?.map((c) => c.key)).toEqual(["stat"]);
 });
+
+test("generateApiGuide resolves program key in install notes", () => {
+  const fixture: CliProgram = {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo app.",
+    commands: [{ key: "run", description: "Run.", handler: () => {} }],
+  };
+  const md = generateApiGuide(fixture);
+  expect(md).not.toContain("{argsbarg:program}");
+  expect(md).toContain("myapp install --all --yes");
+});
+
+test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
+  const fixture: CliProgram = {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo app.",
+    commands: [
+      {
+        key: "run",
+        description: "Run.",
+        notes: "Invoke `{argsbarg:program} run`.",
+        handler: () => {},
+      },
+    ],
+  };
+  const md = generateApiGuide(fixture);
+  expect(md).toContain("Invoke `myapp run`.");
+});

package/src/docs/api-guide.ts

@@ -1,5 +1,5 @@
 import type { CliSchemaExport } from "../builtins/export.ts";
-import { cliPositionalLabel } from "../help.ts";
+import { cliPositionalLabel, cliResolveNotes } from "../help.ts";
 import { cliSchemaExport } from "../schema.ts";
 import type { CliOption, CliPositional, CliProgram } from "../types.ts";
 import { CliFallbackMode, CliOptionKind } from "../types.ts";
@@ -43,6 +43,15 @@ function formatPositionalRow(p: CliPositional): string {
   return `| \`${label}\` | ${p.kind} | ${req} | ${p.description} |`;
 }
 
+/** Markdown blockquote for command notes (`{argsbarg:program}` resolved to root key). */
+function formatNotesBlockquote(notes: string, appKey: string): string {
+  const resolved = cliResolveNotes(notes, appKey);
+  return resolved
+    .split("\n")
+    .map((line) => `> ${line}`)
+    .join("\n");
+}
+
 /** Fallback routing note when present on a router node. */
 function fallbackLine(node: CliSchemaExport): string | null {
   if (node.fallbackCommand === undefined) {
@@ -66,7 +75,7 @@ function renderCommandNode(
   lines.push(`${heading} \`${cmd}\``, "", node.description, "");
 
   if (node.notes) {
-    lines.push(`> ${node.notes}`, "");
+    lines.push(formatNotesBlockquote(node.notes, rootKey), "");
   }
 
   const fb = fallbackLine(node);
@@ -121,7 +130,7 @@ export function generateApiGuide(program: CliProgram): string {
   ];
 
   if (schema.notes) {
-    lines.push(`> ${schema.notes}`, "");
+    lines.push(formatNotesBlockquote(schema.notes, program.key), "");
   }
 
   renderCommandNode(program.key, [], schema, lines);

package/src/docs/save.ts

@@ -2,6 +2,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { CliProgram } from "../types.ts";
 import { docsTopicContent } from "./resolve.ts";
+import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
 
 /** Relative output directory for `docs --save`. */
 export const DOCS_SAVE_DIR = "docs";
@@ -16,24 +17,16 @@ export function docsTopicIsGeneratedByArgsbarg(topic: string): boolean {
 
 /** HTML comment for generated markdown saved with `--save`. */
 export function docsSaveGeneratedHint(program: CliProgram, topic: string): string {
-  return `<!-- Generated by ${program.key} docs ${topic} --save; do not edit. -->\n\n`;
+  return generatedFileHtmlComment(`${program.key} docs ${topic} --save`);
 }
 
-const SKILL_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
-
 /** Inserts save hint without breaking YAML frontmatter (`docs skill`). */
 export function applySaveGeneratedHint(program: CliProgram, topic: string, content: string): string {
   if (!docsTopicIsGeneratedByArgsbarg(topic)) {
     return content;
   }
   const hint = docsSaveGeneratedHint(program, topic);
-  if (topic === "skill") {
-    const match = content.match(SKILL_FRONTMATTER_RE);
-    if (match) {
-      return `${match[0]}${hint}${content.slice(match[0].length)}`;
-    }
-  }
-  return `${hint}${content}`;
+  return insertGeneratedHint(content, hint, topic === "skill" ? { afterFrontmatter: true } : undefined);
 }
 
 /** File body for `--save` (hint on argsbarg-generated markdown only). */

package/src/help.ts

@@ -185,6 +185,14 @@ export function cliOptionLabel(o: CliOption, color: boolean): string {
   return style.aquaBold(left) + " " + style.greenBright(right);
 }
 
+/** Placeholder in `notes` for the root program key (resolved in help, schema, and docs api). */
+export const CLI_NOTES_PROGRAM = "{argsbarg:program}";
+
+/** Replaces `{argsbarg:program}` in notes/help text with the program key. */
+export function cliResolveNotes(notes: string, appKey: string): string {
+  return notes.replaceAll(CLI_NOTES_PROGRAM, appKey);
+}
+
 /** Formats a positional slot label (`<n>`, `[n]`, or varargs) for help. */
 export function cliPositionalLabel(p: CliPositional, color: boolean): string {
   const { argMin = 1, argMax = 1 } = p;
@@ -471,12 +479,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
   }
 
   if ((node.notes ?? "").length > 0) {
-    let resolved = node.notes!;
-    while (true) {
-      const r = resolved.indexOf("{app}");
-      if (r === -1) break;
-      resolved = resolved.slice(0, r) + schema.key + resolved.slice(r + 5);
-    }
+    const resolved = cliResolveNotes(node.notes!, schema.key);
     lines.push("");
     lines.push(
       renderTextBox("Notes", wrapText(resolved, hw - 4), hw, color).join("\n"),

package/src/index.test.ts

@@ -597,6 +597,44 @@ test("cliSchemaJson omits handlers and completion built-ins", () => {
   expect(schema).not.toHaveProperty("handler");
 });
 
+test("cliSchemaExport resolves program key in install notes", () => {
+  const root = testProgram({
+    key: "myapp",
+    version: "1.0.0",
+    description: "demo",
+    commands: [
+      {
+        key: "run",
+        description: "run",
+        handler: () => {},
+      },
+    ],
+  });
+
+  const json = cliSchemaJson(root);
+  expect(json).not.toContain("{argsbarg:program}");
+  expect(json).toContain("myapp install --all --yes");
+});
+
+test("cliSchemaExport resolves {argsbarg:program} in consumer notes", () => {
+  const root = testProgram({
+    key: "myapp",
+    version: "1.0.0",
+    description: "demo",
+    commands: [
+      {
+        key: "run",
+        description: "run",
+        notes: "Run `{argsbarg:program} run` to start.",
+        handler: () => {},
+      },
+    ],
+  });
+
+  const schema = JSON.parse(cliSchemaJson(root));
+  expect(schema.commands[0].notes).toBe("Run `myapp run` to start.");
+});
+
 test("docs help lists schema, api, and skill subcommands", () => {
   const root = testProgram({
     key: "app",
@@ -1735,7 +1773,9 @@ test("generateSkillBundle includes frontmatter and command catalog", () => {
   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).not.toContain("Generated by");
   expect(() => JSON.parse(bundle.referenceMd.match(/```json\n([\s\S]*?)\n```/)![1]!)).not.toThrow();
 });
 
@@ -1750,6 +1790,12 @@ test("cliSkillInstall writes project Cursor skill files", () => {
     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");
+    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. -->";
+    expect(skillText.indexOf(hint)).toBeGreaterThan(skillText.indexOf("---\n", 4));
+    const refText = readFileSync(join(skillDir, "reference.md"), "utf8");
+    expect(refText.startsWith(hint)).toBe(true);
   } finally {
     process.chdir(prev);
     rmSync(cwd, { recursive: true, force: true });

package/src/schema.ts

@@ -4,10 +4,11 @@ This module serializes the CLI schema tree to JSON for machine-readable introspe
 
 import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { exportPresentationBuiltins, type CliSchemaExport } from "./builtins/export.ts";
+import { cliResolveNotes } from "./help.ts";
 
 const RESERVED = new Set(["completion", "install", "docs", "mcp", "version", "update"]);
 
-function exportCommand(cmd: CliNode): CliSchemaExport {
+function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport {
   const out: CliSchemaExport = {
     key: cmd.key,
     description: cmd.description,
@@ -25,7 +26,7 @@ function exportCommand(cmd: CliNode): CliSchemaExport {
     if ((cmd.positionals ?? []).length > 0) {
       out.positionals = cmd.positionals;
     }
-    out.commands = exportPresentationBuiltins(cmd as CliProgram);
+    out.commands = exportPresentationBuiltins(root);
     return out;
   }
 
@@ -38,15 +39,27 @@ function exportCommand(cmd: CliNode): CliSchemaExport {
 
   const children = isCliRouter(cmd) ? cmd.commands.filter((ch) => !RESERVED.has(ch.key)) : [];
   if (children.length > 0) {
-    out.commands = children.map(exportCommand);
+    out.commands = children.map((ch) => exportCommand(ch, root));
   }
 
   return out;
 }
 
+/** Resolves `{argsbarg:program}` in exported notes using the root program key. */
+function resolveSchemaNotes(node: CliSchemaExport, appKey: string): CliSchemaExport {
+  const out: CliSchemaExport = { ...node };
+  if ((out.notes ?? "").length > 0) {
+    out.notes = cliResolveNotes(out.notes!, appKey);
+  }
+  if (out.commands) {
+    out.commands = out.commands.map((ch) => resolveSchemaNotes(ch, appKey));
+  }
+  return out;
+}
+
 /** Returns the JSON-safe command tree (handlers omitted). */
 export function cliSchemaExport(root: CliProgram): CliSchemaExport {
-  return exportCommand(root);
+  return resolveSchemaNotes(exportCommand(root, root), root.key);
 }
 
 export function cliSchemaJson(root: CliProgram): string {

package/src/skill/hint.ts

@@ -0,0 +1,42 @@
+import type { CliProgram } from "../types.ts";
+
+/** YAML frontmatter block at the start of SKILL.md. */
+export const MARKDOWN_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
+
+/** HTML comment marking argsbarg-generated markdown. */
+export function generatedFileHtmlComment(source: string): string {
+  return `<!-- Generated by ${source}; do not edit. -->\n\n`;
+}
+
+/** Prepends a hint, or inserts after frontmatter when requested. */
+export function insertGeneratedHint(
+  content: string,
+  hint: string,
+  options?: { afterFrontmatter?: boolean },
+): string {
+  if (options?.afterFrontmatter) {
+    const match = content.match(MARKDOWN_FRONTMATTER_RE);
+    if (match) {
+      return `${match[0]}${hint}${content.slice(match[0].length)}`;
+    }
+  }
+  return `${hint}${content}`;
+}
+
+/** Hint for `install --skill` output files. */
+export function skillInstallHint(program: CliProgram): string {
+  return generatedFileHtmlComment(`${program.key} install --skill`);
+}
+
+/** Applies install hints to SKILL.md (after frontmatter) and reference.md. */
+export function applySkillInstallHints(
+  program: CliProgram,
+  skillMd: string,
+  referenceMd: string,
+): { skillMd: string; referenceMd: string } {
+  const hint = skillInstallHint(program);
+  return {
+    skillMd: insertGeneratedHint(skillMd, hint, { afterFrontmatter: true }),
+    referenceMd: insertGeneratedHint(referenceMd, hint),
+  };
+}

package/src/skill/install.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { CliProgram } from "../types.ts";
 import { generateSkillBundle, type SkillTarget } from "./generate.ts";
+import { applySkillInstallHints } from "./hint.ts";
 
 export interface SkillInstallOpts {
   global?: boolean;
@@ -26,6 +27,7 @@ function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean):
 /** Writes SKILL.md and reference.md; returns changed file paths. */
 export function cliSkillInstall(root: CliProgram, target: SkillTarget, opts: SkillInstallOpts): string[] {
   const bundle = generateSkillBundle(root, target);
+  const { skillMd, referenceMd } = applySkillInstallHints(root, bundle.skillMd, bundle.referenceMd);
   const dir = resolveSkillDir(target, bundle.dirName, opts.global ?? false);
   const changed: string[] = [];
 
@@ -38,8 +40,8 @@ export function cliSkillInstall(root: CliProgram, target: SkillTarget, opts: Ski
 
   if (!opts.dry) {
     mkdirSync(dir, { recursive: true });
-    writeFileSync(skillPath, bundle.skillMd, "utf8");
-    writeFileSync(refPath, bundle.referenceMd, "utf8");
+    writeFileSync(skillPath, skillMd, "utf8");
+    writeFileSync(refPath, referenceMd, "utf8");
   }
 
   changed.push(skillPath, refPath);

package/src/types.ts

@@ -213,7 +213,7 @@ export interface CliNodeBase {
   key: string;
   /** Short description shown in help. */
   description: string;
-  /** Additional notes shown in help (supports {app} placeholder). */
+  /** Additional notes shown in help (`{argsbarg:program}` → program key). */
   notes?: string;
   /** Global or command-level flags/options. */
   options?: CliOption[];