argsbarg 3.3.9 → 3.3.11

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`install` help copy** — `--update` and `--quiet` option descriptions match behavior; `install --update` error message clarified.
+- **`docs/install.md`** — quick-start and `--yes` flag docs aligned with install notes.
+
 ## [3.3.9] - 2026-06-21
 
 ### Changed
@@ -304,7 +317,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.9...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.11...HEAD
+[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
 [3.3.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.7

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 |

package/docs/install.md

@@ -11,7 +11,7 @@ myapp install --all --yes
 # Refresh after upgrading (re-copy running binary + refresh installed artifacts)
 myapp install --reinstall
 
-# Download latest release (when install.updateGetLatest is configured)
+# Upgrade to latest release (when install.updateGetLatest is configured)
 myapp install --update
 
 # See what is installed
@@ -99,7 +99,7 @@ Environment:
 
 | Flag | Description |
 | --- | --- |
-| `--yes` | Skip confirmation (required for non-TTY unless `--json` / `--reinstall`) |
+| `--yes` | Skip confirmation (required for non-TTY unless `--json`, `--reinstall`, or `--update`) |
 | `--dry` | Preview changes; per-step messages on stderr with `[dry run]` |
 | `--json` | Machine-readable output on stdout (implies `--yes`) |
 | `--quiet` | Suppress summaries and per-step messages (requires `--yes`) |

package/package.json

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

package/plan.md

@@ -2,13 +2,13 @@
 
 ## Current Status
 
-**Overall**: Core CLI, MCP, install, docs, and update built-ins are complete. Public API is stable at **3.x**.
+**Overall**: Core CLI, MCP, install, docs, and `install --update` are complete. Public API is stable at **3.x**.
 
 ### Shipped
 
 - Schema-driven parsing, help, completions, subcommand routing, fallback commands
 - MCP server (`mcpServer: { enabled: true }`), `ctx.invocation`, `cliInvoke`
-- `install` / `update` built-ins, agent skills, bundled `docs` (topics, schema, api, skill, mcp)
+- `install` built-in (`install --update` when `updateGetLatest` is set), agent skills, bundled `docs` (topics, schema, api, skill, mcp)
 - Headless helpers and `ghReleaseUpdateGetLatest` for GitHub release consumers
 
 ### Consumers

package/src/builtins/builtins.test.ts

@@ -37,6 +37,25 @@ describe("builtins help copy", () => {
     expect(names).not.toContain("mcp");
   });
 
+  test("install omits --update when updateGetLatest unset", () => {
+    const install = cliBuiltinInstallCommand(fixture);
+    expect(installBuiltinOptions(fixture).map((o) => o.name)).not.toContain("update");
+    expect(install.notes).not.toContain("Upgrade to latest release");
+    expect(install.notes).toContain("Refresh after upgrading");
+  });
+
+  test("install notes include upgrade section when updateGetLatest is set", () => {
+    const withUpdate: CliProgram = {
+      ...fixture,
+      install: { updateGetLatest: async () => ({ path: process.execPath }) },
+    };
+    const install = cliBuiltinInstallCommand(withUpdate);
+    const notes = install.notes ?? "";
+    expect(installBuiltinOptions(withUpdate).map((o) => o.name)).toContain("update");
+    expect(notes).toContain("Upgrade to latest release");
+    expect(notes.indexOf("install --reinstall")).toBeLessThan(notes.indexOf("install --update"));
+  });
+
   test("mcp builtin description is user-facing", () => {
     const mcp = cliBuiltinMcpCommand();
     expect(mcp.description).toContain("MCP server");
@@ -61,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/install.ts

@@ -67,7 +67,7 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     },
     {
       name: "quiet",
-      description: "Suppress informational output (requires --yes).",
+      description: "Suppress informational output (requires --yes, --json, --reinstall, or --update).",
       kind: CliOptionKind.Presence,
     },
   ];
@@ -84,7 +84,7 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     const statusIdx = opts.findIndex((o) => o.name === "status");
     opts.splice(statusIdx, 0, {
       name: "update",
-      description: "Download and install the latest release.",
+      description: "Download the latest release and reinstall installed artifacts.",
       kind: CliOptionKind.Presence,
     });
   }

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

@@ -64,6 +64,20 @@ test("generateApiGuide resolves program key in install notes", () => {
   const md = generateApiGuide(fixture);
   expect(md).not.toContain("{argsbarg:program}");
   expect(md).toContain("myapp install --all --yes");
+  expect(md).not.toContain("Upgrade to latest release");
+});
+
+test("generateApiGuide includes upgrade section when updateGetLatest is set", () => {
+  const fixture: CliProgram = {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo app.",
+    install: { updateGetLatest: async () => ({ path: process.execPath }) },
+    commands: [{ key: "run", description: "Run.", handler: () => {} }],
+  };
+  const md = generateApiGuide(fixture);
+  expect(md).toContain("Upgrade to latest release");
+  expect(md).toContain("myapp install --update");
 });
 
 test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {

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.",

package/src/install/update.ts

@@ -7,7 +7,7 @@ import { installErr } from "./status.ts";
 export async function cliUpdate(root: CliProgram): Promise<never> {
   const hook = root.install?.updateGetLatest;
   if (!hook) {
-    installErr("update is not configured. Set install.updateGetLatest on the program root.");
+    installErr("install --update is not configured. Set install.updateGetLatest on the program root.");
     process.exit(1);
   }