argsbarg 5.0.1 → 5.0.3

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.3] - 2026-07-04
+
+### Changed
+
+- **JSDoc style** — short `test()` callbacks no longer carry redundant one-liners; `describe` blocks still documented. `requireYesInNonTty` uses per-parameter JSDoc instead of `@param`. Pure re-export barrels stay comment-free.
+
+## [5.0.2] - 2026-07-04
+
+### Changed
+
+- **JSDoc style** — every `describe` block in `src/**/*.test.ts` now has a human-readable JSDoc; `configure` modules brought in line with file headers and symbol docs.
+
 ## [5.0.1] - 2026-07-04
 
 
@@ -567,7 +579,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/v5.0.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.0.3...HEAD
+[5.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.3
+[5.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.2
 [5.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.1
 [5.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.0
 [4.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.1.1

package/docs/distribution-homebrew.md

@@ -60,6 +60,8 @@ Completions require users to configure their shell per [Homebrew Shell Completio
 
 **Why configure is separate from `post_install`:** the wizard is interactive (TTY + prompts for secrets). Formula `post_install` runs non-interactively during `brew install` and in CI (`brew test`). Apps with `appConfig` print a one-line configure hint in formula `caveats` instead.
 
+**MCP hosts:** when `mcpServer.enabled` is true, add a caveats line that chat apps (Cursor, Claude Desktop, etc.) must be **restarted** after `brew install` / `brew upgrade` — `post_install` updates MCP config on disk, but hosts typically load it only at startup.
+
 ## Bootstrap CLI (`argsbarg create`)
 
 Copy the shipped `examples/full-example` template into a new directory with identity substitutions, then run install, schemagen, tests, and git init (when appropriate):

package/examples/full-example/scripts/formula-shared.ts

@@ -17,6 +17,7 @@ export const formulaPostInstallRuby = `def post_install
 export const formulaCaveatsRuby = `def caveats
     <<~EOS
       Run \`${key} configure\` to set up agent artifacts and app config (interactive).
+      Restart MCP chat apps (Cursor, Claude Desktop, etc.) after install or upgrade so they load the updated server.
     EOS
   end`;
 

package/index.d.ts

@@ -551,11 +551,16 @@ export declare function shouldRunHeadlessWithYes(ctx: HeadlessContext, opts: {
 	hasRequiredArgs: boolean;
 	dryRun?: boolean;
 }, interactive?: boolean): boolean;
-/**
- * Exits when non-interactive mode is used without `--yes`.
- * @param hint - Command-specific guidance appended to the error
- */
-export declare function requireYesInNonTty(yes: boolean, hint: string, dryRun?: boolean, interactive?: boolean): void;
+/** Exits when non-interactive mode is used without `--yes`. */
+export declare function requireYesInNonTty(
+/** True when `--yes` was passed on the command line. */
+yes: boolean, 
+/** Command-specific guidance appended to the error message. */
+hint: string, 
+/** When true, skip the check (dry-run preview). */
+dryRun?: boolean, 
+/** Injectable TTY probe for tests. */
+interactive?: boolean): void;
 /** Prefixes a success message when running in dry-run mode. */
 export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
 /** Resolved paths for `mcp bundle`. */

package/package.json

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

package/src/builtins/builtins.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for builtins/builtins module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { resolveCapabilities } from "../capabilities.ts";
 import { cliBuiltinDocsGroup } from "../docs/builtin.ts";
@@ -31,6 +35,7 @@ const noMcp: CliProgram = {
   commands: [{ key: "ping", description: "Ping.", handler: () => {} }],
 };
 
+/** Tests for builtins help copy. */
 describe("builtins help copy", () => {
   test("configure command includes Homebrew-oriented description", () => {
     const configure = cliBuiltinConfigureCommand(fixture);
@@ -56,6 +61,7 @@ describe("builtins help copy", () => {
     expect(configure.description).not.toContain("MCP");
   });
 
+  /** Configure notes mention brew upgrade and interactive configure. */
   test("configure notes mention brew upgrade and interactive configure", () => {
     const configure = cliBuiltinConfigureCommand(fixture);
     expect(configure.notes).toContain("brew upgrade");
@@ -93,6 +99,7 @@ describe("builtins help copy", () => {
   });
 });
 
+/** Tests for presentation root. */
 describe("presentation root", () => {
   test("includes mcp and configure when enabled", () => {
     const root = cliPresentationRoot(fixture);
@@ -115,6 +122,7 @@ describe("presentation root", () => {
   });
 });
 
+/** Tests for completion emitters. */
 describe("completion emitters", () => {
   test("fish script references app key and subcommands", () => {
     const schema = cliPresentationRoot(fixture);
@@ -144,7 +152,9 @@ describe("completion emitters", () => {
   });
 });
 
+/** Tests for schema export builtins. */
 describe("schema export builtins", () => {
+  /** ExportPresentationBuiltins includes config when appConfig set. */
   test("exportPresentationBuiltins includes config when appConfig set", () => {
     const withConfig: CliProgram = {
       ...fixture,
@@ -165,7 +175,9 @@ describe("schema export builtins", () => {
   });
 });
 
+/** Tests for docs skill topic copy. */
 describe("docs skill topic copy", () => {
+  /** Tests that mentions configure when configure is enabled. */
   test("mentions configure when configure is enabled", () => {
     const withDocs: CliProgram = {
       ...noMcp,

package/src/builtins/config.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for builtins/config module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -20,7 +24,9 @@ function configFixture(): CliProgram {
   };
 }
 
+/** Tests for builtins/config. */
 describe("builtins/config", () => {
+  /** Tests that config get redacts sensitive values. */
   test("config get redacts sensitive values", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
     const prevHome = process.env.HOME;
@@ -43,6 +49,7 @@ describe("builtins/config", () => {
     }
   });
 
+  /** Tests that config get --json redacts sensitive as { set: true }. */
   test("config get --json redacts sensitive as { set: true }", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
     const prevHome = process.env.HOME;
@@ -65,6 +72,7 @@ describe("builtins/config", () => {
     }
   });
 
+  /** Tests that config set writes and resolves without required exit. */
   test("config set writes and resolves without required exit", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
     const prevHome = process.env.HOME;

package/src/cli-tool/cli-smoke.test.ts

@@ -1,9 +1,14 @@
+/*
+Tests for cli-tool/cli-smoke module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 
 const main = join(import.meta.dir, "main.ts");
 
+/** Tests for argsbarg cli-tool. */
 describe("argsbarg cli-tool", () => {
   test("version subcommand prints version", () => {
     const proc = spawnSync("bun", [main, "version"], { encoding: "utf8" });

package/src/cli-tool/create.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for cli-tool/create module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -12,7 +16,9 @@ import {
   substituteTemplateContent,
 } from "./create.ts";
 
+/** Tests for argsbarg create. */
 describe("argsbarg create", () => {
+  /** Tests that substitutes {key} tokens. */
   test("substitutes {key} tokens", () => {
     const out = substituteTemplateContent(
       "key={key} class={className} env={envPrefix}_API_TOKEN tap={tap} org={tapOrg}",
@@ -44,6 +50,7 @@ describe("argsbarg create", () => {
     expect(classNameFromKey("1password")).toBe("App1password");
   });
 
+  /** ResolveCreateOptions derives identity defaults from key. */
   test("resolveCreateOptions derives identity defaults from key", () => {
     expect(resolveCreateOptions({ key: "1password", releaseRepo: "org/1password" }).className).toBe(
       "App1password",
@@ -63,6 +70,7 @@ describe("argsbarg create", () => {
     expect(() => resolveCreateOptions({ key: "at1" })).toThrow(/release repo/i);
   });
 
+  /** Tests that renderCreateTree includes justfile and create-identity. */
   test("renderCreateTree includes justfile and create-identity", () => {
     const tree = renderCreateTree({
       key: "testapp",
@@ -88,6 +96,7 @@ describe("argsbarg create", () => {
     expect(formula).toContain("create-identity.ts");
   });
 
+  /** Tests that --check detects drift. */
   test("--check detects drift", () => {
     const dir = mkdtempSync(join(tmpdir(), "argsbarg-create-"));
     try {
@@ -111,6 +120,7 @@ describe("argsbarg create", () => {
     }
   });
 
+  /** Tests that --check infers options from create-identity.ts. */
   test("--check infers options from create-identity.ts", () => {
     const dir = mkdtempSync(join(tmpdir(), "argsbarg-create-"));
     try {

package/src/cli-tool/full-example-capabilities.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for cli-tool/full-example-capabilities module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -45,7 +49,9 @@ const sinkProgram = {
   ],
 } satisfies CliProgram;
 
+/** Tests for full-example template. */
 describe("full-example template", () => {
+  /** Tests that program source enables every builtin flag. */
   test("program source enables every builtin flag", () => {
     expect(programSource).toContain("mcpServer: {");
     expect(programSource).toContain("enabled: true");

package/src/config/context.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for config/context module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -20,7 +24,9 @@ const program: CliProgram = {
   handler: () => {},
 };
 
+/** Tests for config/context. */
 describe("config/context", () => {
+  /** Tests that AppConfigSnapshot get, require, read, set. */
   test("AppConfigSnapshot get, require, read, set", () => {
     const dir = mkdtempSync(join(tmpdir(), "ctx-test-"));
     const prevHome = process.env.HOME;
@@ -50,6 +56,7 @@ describe("config/context", () => {
     }
   });
 
+  /** Tests that EmptyAppConfigSnapshot when program.appConfig unset. */
   test("EmptyAppConfigSnapshot when program.appConfig unset", () => {
     const programWithoutConfig: CliProgram = {
       key: "x",

package/src/config/file.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for config/file module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -40,6 +44,7 @@ function withHome<T>(fn: (home: string) => T): T {
   }
 }
 
+/** Tests for config/file. */
 describe("config/file", () => {
   test("buildProgramUserConfig from program.appConfig env entries", () => {
     const cfg = buildProgramUserConfig(program);
@@ -59,6 +64,7 @@ describe("config/file", () => {
     });
   });
 
+  /** ResolveAppConfig prefers host env over file. */
   test("resolveAppConfig prefers host env over file", () => {
     withHome((_home) => {
       const prevToken = process.env.API_TOKEN;
@@ -76,6 +82,7 @@ describe("config/file", () => {
     });
   });
 
+  /** MissingRequiredConfig and formatMissingConfigMessage. */
   test("missingRequiredConfig and formatMissingConfigMessage", () => {
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;

package/src/config/resolve.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for config/resolve module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
 import { captureMappedHostEnv, exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
@@ -25,6 +29,7 @@ const program: CliProgram = {
   handler: () => {},
 };
 
+/** Tests for config/resolve. */
 describe("config/resolve", () => {
   test("prefers env over file for mapped keys", () => {
     const prev = process.env.API_TOKEN;
@@ -110,6 +115,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Resolve callback supplies value when env and file are absent. */
   test("resolve callback supplies value when env and file are absent", () => {
     const resolveProgram: CliProgram = {
       ...program,
@@ -135,6 +141,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Env overrides resolve callback. */
   test("env overrides resolve callback", () => {
     const resolveProgram: CliProgram = {
       ...program,
@@ -161,6 +168,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** File overrides resolve callback. */
   test("file overrides resolve callback", () => {
     const resolveProgram: CliProgram = {
       ...program,
@@ -186,6 +194,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Tests that falls back to env when resolve returns undefined. */
   test("falls back to env when resolve returns undefined", () => {
     const resolveProgram: CliProgram = {
       ...program,
@@ -212,6 +221,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Resolve callback is skipped when env is set. */
   test("resolve callback is skipped when env is set", () => {
     let resolveCalled = false;
     const resolveProgram: CliProgram = {
@@ -243,6 +253,7 @@ describe("config/resolve", () => {
     }
   });
 
+  /** Tests that async resolve is ignored with stderr warning. */
   test("async resolve is ignored with stderr warning", () => {
     const resolveProgram: CliProgram = {
       ...program,

package/src/config/validate.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for config/validate module behavior.
+*/
+
 import { describe, expect, test } from "bun:test";
 import { parseConfigSetValue, validateConfigDocument } from "./validate.ts";
 
@@ -17,6 +21,7 @@ const rootSchema = {
   },
 };
 
+/** Tests for config/validate. */
 describe("config/validate", () => {
   test("accepts valid document", () => {
     const result = validateConfigDocument(

package/src/config.integration.test.ts

@@ -10,6 +10,7 @@ import { bootstrapAppConfig } from "./config/bootstrap.ts";
 import { resolveAppConfigPath } from "./config/file.ts";
 import { mcpRequest, testProgram } from "./test-fixtures.ts";
 
+/** Tests that bootstrapAppConfig prefers host env over config file. */
 test("bootstrapAppConfig prefers host env over config file", () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-env-"));
   const prevHome = process.env.HOME;
@@ -43,6 +44,7 @@ test("bootstrapAppConfig prefers host env over config file", () => {
   }
 });
 
+/** MCP program.appConfig fails when required config missing. */
 test("MCP program.appConfig fails when required config missing", async () => {
   const responses = await mcpRequest(
     [
@@ -60,6 +62,7 @@ test("MCP program.appConfig fails when required config missing", async () => {
   expect(res.result.content[0]?.text).toContain("argsTestSecret");
 });
 
+/** MCP program.appConfig succeeds when env present. */
 test("MCP program.appConfig succeeds when env present", async () => {
   const responses = await mcpRequest(
     [
@@ -77,6 +80,7 @@ test("MCP program.appConfig succeeds when env present", async () => {
   expect(res.result.content[0]?.text.trim()).toBe("sekrit");
 });
 
+/** MCP config file loads and exports vars for tool handlers. */
 test("MCP config file loads and exports vars for tool handlers", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-mcp-"));
   const configFile = join(dir, ".local", "lib", "mcp_test", "config");
@@ -106,6 +110,7 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
   rmSync(dir, { recursive: true, force: true });
 });
 
+/** Cli.run docs api skips required appConfig exit. */
 test("Cli.run docs api skips required appConfig exit", async () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-docs-skip-"));
   const configFile = join(dir, ".local", "lib", "docs_skip_test", "config");

package/src/configure/configure.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for configure/configure module behavior.
+*/
+
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -42,6 +46,7 @@ afterEach(() => {
   rmSync(home, { recursive: true, force: true });
 });
 
+/** Tests for configure opts. */
 describe("configure opts", () => {
   test("validate rejects multiple modes", () => {
     const opts = parseConfigureOpts({ sync: "1", status: "1" });
@@ -59,6 +64,7 @@ describe("configure opts", () => {
   });
 });
 
+/** Tests for install paths. */
 describe("install paths", () => {
   test("resolveInstallPaths includes skill and mcp paths", () => {
     const paths = resolveInstallPaths(fixture);
@@ -79,7 +85,9 @@ describe("install paths", () => {
   });
 });
 
+/** Tests for detect installed. */
 describe("detect installed", () => {
+  /** Detects cursor mcp when configured. */
   test("detects cursor mcp when configured", () => {
     const paths = resolveInstallPaths(fixture);
     mkdirSync(join(home, ".cursor"), { recursive: true });
@@ -95,6 +103,7 @@ describe("detect installed", () => {
   });
 });
 
+/** Tests for sync plan. */
 describe("sync plan", () => {
   test("buildUpdatePlan greenfield includes agent targets", () => {
     const paths = resolveInstallPaths(fixture);
@@ -123,6 +132,7 @@ describe("sync plan", () => {
   });
 });
 
+/** Tests for remove plan. */
 describe("remove plan", () => {
   test("buildUninstallPlan --all with nothing installed is empty", () => {
     const paths = resolveInstallPaths(fixture);
@@ -131,6 +141,7 @@ describe("remove plan", () => {
   });
 });
 
+/** Tests for app config wizard. */
 describe("app config wizard", () => {
   test("appConfigHasEntries when entries exist", () => {
     expect(

package/src/configure/index.ts

@@ -1,3 +1,7 @@
+/*
+Interactive and automated `configure` command orchestration (agent artifacts and app config).
+*/
+
 import { resolveCapabilities } from "../capabilities.ts";
 import { displayAppConfigPath, runConfigure } from "../config/bootstrap.ts";
 import { resolveInstallPaths } from "../install/paths.ts";
@@ -36,6 +40,7 @@ export function appConfigHasEntries(program: CliProgram): boolean {
   return !!entries && Object.keys(entries).length > 0;
 }
 
+/** Parsed flags for the top-level `configure` built-in. */
 export interface ConfigureOpts {
   sync?: boolean;
   removeAll?: boolean;
@@ -46,6 +51,7 @@ export interface ConfigureOpts {
   json?: boolean;
 }
 
+/** Maps raw argv flags into {@link ConfigureOpts}. */
 export function parseConfigureOpts(raw: Record<string, string>): ConfigureOpts {
   const flag = (name: string) => raw[name] === "1";
   return {
@@ -59,6 +65,7 @@ export function parseConfigureOpts(raw: Record<string, string>): ConfigureOpts {
   };
 }
 
+/** Returns an error message when configure flags are inconsistent; otherwise null. */
 export function validateConfigureOpts(opts: ConfigureOpts): string | null {
   const flags = [opts.sync, opts.removeAll, opts.removeConfig, opts.status].filter(Boolean);
   if (flags.length > 1) {
@@ -73,6 +80,7 @@ export function validateConfigureOpts(opts: ConfigureOpts): string | null {
   return null;
 }
 
+/** Adapts configure flags to internal install-plan option shape. */
 function configureToInstallOpts(opts: ConfigureOpts): InstallOpts {
   if (opts.status) {
     return { status: true, yes: opts.yes, dry: opts.dry, json: opts.json };
@@ -89,6 +97,7 @@ function configureToInstallOpts(opts: ConfigureOpts): InstallOpts {
   return { dry: opts.dry, json: opts.json };
 }
 
+/** Installs a skill target and returns changed paths. */
 function runSkillAction(root: CliProgram, kind: InstallActionKind, opts: InstallOpts): string[] {
   const target = skillTargetFromActionKind(kind);
   if (!target) return [];
@@ -99,6 +108,7 @@ function runSkillAction(root: CliProgram, kind: InstallActionKind, opts: Install
   });
 }
 
+/** Runs install or uninstall actions and collects changed paths. */
 function executePlan(
   root: CliProgram,
   actions: Array<InstallAction | UninstallAction>,
@@ -130,6 +140,7 @@ function executePlan(
   return changed;
 }
 
+/** Builds plan context limited to a single artifact key. */
 function buildSingleTargetContext(
   root: CliProgram,
   paths: ReturnType<typeof resolveInstallPaths>,
@@ -147,6 +158,7 @@ function buildSingleTargetContext(
   };
 }
 
+/** Resolves install or uninstall actions for one artifact target. */
 function actionsForTarget(
   root: CliProgram,
   paths: ReturnType<typeof resolveInstallPaths>,
@@ -164,6 +176,7 @@ function actionsForTarget(
   return target.planUninstall(ctx);
 }
 
+/** Walks enabled targets with per-target prompts (TTY required). */
 async function runInteractiveConfigure(root: CliProgram, opts: ConfigureOpts): Promise<string[]> {
   if (!process.stdin.isTTY) {
     throw new Error("Interactive configure requires a TTY. Use flags such as --sync --yes.");
@@ -218,6 +231,7 @@ async function runInteractiveConfigure(root: CliProgram, opts: ConfigureOpts): P
   return changed;
 }
 
+/** Runs sync, remove, or status modes without per-target prompts. */
 async function runAutomatedConfigure(root: CliProgram, opts: ConfigureOpts): Promise<string[]> {
   const installOpts = configureToInstallOpts(opts);
   const paths = resolveInstallPaths(root);

package/src/configure/prompt.ts

@@ -1,6 +1,11 @@
+/*
+TTY prompts for per-target install, skip, or uninstall during interactive `configure`.
+*/
+
 import { readSync } from "node:fs";
 import type { CliInstallArtifactKey } from "../install/target-types.ts";
 
+/** Human-readable labels for each install artifact key in interactive prompts. */
 const LABELS: Record<CliInstallArtifactKey, string> = {
   app: "App binary",
   cursorSkill: "Cursor skill",
@@ -18,10 +23,12 @@ const LABELS: Record<CliInstallArtifactKey, string> = {
   configure: "App config",
 };
 
+/** Returns the prompt label for an install artifact key. */
 export function artifactPromptLabel(key: CliInstallArtifactKey): string {
   return LABELS[key];
 }
 
+/** User choice from a per-target Y/n or y/N prompt. */
 export type TargetPromptAction = "install" | "skip" | "uninstall";
 
 /** Prompt per target: Y/n when not installed, y/N when installed. */

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

@@ -1,3 +1,7 @@
+/*
+Tests for docs/api-guide module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import { cliSchemaExport } from "../schema.ts";
 import type { CliProgram } from "../types.ts";
@@ -87,6 +91,7 @@ test("generateApiGuide mentions Homebrew upgrade", () => {
   expect(md).not.toContain("install --update");
 });
 
+/** Tests that generateApiGuide resolves {argsbarg:program} in consumer notes. */
 test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
   const fixture: CliProgram = {
     key: "myapp",
@@ -105,6 +110,7 @@ test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
   expect(md).toContain("Invoke `myapp run`.");
 });
 
+/** Tests that generateApiGuide and cliSchemaExport include leaf outputSchema. */
 test("generateApiGuide and cliSchemaExport include leaf outputSchema", () => {
   const fixture: CliProgram = {
     key: "myapp",

package/src/docs/docs.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for docs/docs module behavior.
+*/
+
 import { afterEach, beforeEach, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -49,6 +53,7 @@ function docsFixture(mcp = true): CliProgram {
   };
 }
 
+/** Docs reserved when enabled. */
 test("docs reserved when enabled", () => {
   const root: CliProgram = {
     ...docsFixture(),
@@ -63,6 +68,7 @@ test("docs reserved when enabled", () => {
   expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: docs/);
 });
 
+/** Docs rejects reserved topic keys. */
 test("docs rejects reserved topic keys", () => {
   const root = docsFixture();
   const docs = root.docs;
@@ -176,6 +182,7 @@ test("docs skill prints Cursor SKILL.md", async () => {
   expect(result.stdout).not.toContain("mcp.json");
 });
 
+/** Docs skill help recommends configure. */
 test("docs skill help recommends configure", async () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");

package/src/docs/mcp-resources.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for docs/mcp-resources module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import type { CliProgram } from "../types.ts";
 import {