argsbarg 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-06-20
+
+### Added
+
+- **`docs` built-in** — opt in with `docs: { enabled: true, topics: { ... } }` on the program root. Bundled markdown topics on stdout (`myapp docs`, `myapp docs readme`, `myapp docs all`). Auto **`docs mcp`** guide when `docs` and `mcpServer` are both enabled. See [docs/bundled-docs.md](docs/bundled-docs.md).
+
+### Changed
+
+- **Agent skills** — `SKILL.md` is shell-only (removed MCP setup, `mcp.json`, and `tools/call` content). Use `docs mcp` or MCP tools for agent execution guidance.
+
 ## [3.0.0] - 2026-06-20
 
 ### Added
@@ -198,7 +208,8 @@ 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.0.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.1.0...HEAD
+[3.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.1.0
 [3.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.0.0
 [2.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v2.1.1
 [2.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v2.1.0

package/README.md

@@ -99,10 +99,12 @@ Every app gets:
 - **`completion bash` / `completion zsh` / `completion fish`** — print shell completion scripts to stdout (injected by `cliRun`).
 - **`version`** — print `CliProgram.version` (`myapp version`).
 - **`mcp`** — when `mcpServer.enabled` is `true`, run as an MCP stdio server (`myapp mcp`).
+- **`docs`** — when `docs.enabled` is `true`, print bundled markdown topics (`myapp docs`, `myapp docs readme`, …). See [docs/bundled-docs.md](docs/bundled-docs.md).
 - **`install`** — install the binary, completions, skills, and MCP config to the user environment (`myapp install --all --yes`). See [docs/install.md](docs/install.md).
 
 Do not declare a top-level command named **`completion`**, **`version`**, or **`install`** — they are reserved.
 When **`mcpServer.enabled`** is `true`, do not declare a top-level command named **`mcp`** — it is reserved for the MCP built-in.
+When **`docs.enabled`** is `true`, do not declare a top-level command named **`docs`** — it is reserved for the docs built-in.
 Do not declare an option named **`schema`** — it is reserved for `--schema`.
 
 
@@ -228,7 +230,7 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | `cliInvoke(root, argv)` | Parse and dispatch without exiting; returns captured stdout/stderr. |
 | `cliErrWithHelp(ctx, msg)` | Print error + scoped help on stderr, exit 1. |
 
-Reserved identifiers (validated at startup): root commands **`completion`**, **`version`**, **`install`**, and **`mcp`** (only when `mcpServer.enabled` is `true`).
+Reserved identifiers (validated at startup): root commands **`completion`**, **`version`**, **`install`**, **`docs`** (when `docs.enabled` is `true`), and **`mcp`** (when `mcpServer.enabled` is `true`).
 
 ---
 

package/bun.lock

@@ -0,0 +1,21 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "argsbarg",
+      "devDependencies": {
+        "@types/bun": "^1.3.12",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+  }
+}

package/docs/ai-skills.md

@@ -31,17 +31,21 @@ For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true
 
 ## Generated content
 
-- **`SKILL.md`** — YAML frontmatter, when-to-use guidance, command catalog, MCP setup hints
+- **`SKILL.md`** — YAML frontmatter, when-to-use guidance, shell command catalog, pitfalls
 - **`reference.md`** — full `--schema` JSON export
 
-## MCP vs skills
+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
 
 | Mechanism | Role |
 | --- | --- |
 | **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`myapp install --skill`** | Static discovery files for agents |
+| **`myapp install --skill`** | Static shell command catalog for agents |
+| **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
 See also:
 
+- [Bundled docs](bundled-docs.md) — `docs` config and compile-time imports
 - [MCP server](mcp.md) — `mcpServer` config and `mcp` protocol
 - [Install](install.md) — binary, completions, skills, and MCP config

package/docs/bundled-docs.md

@@ -0,0 +1,77 @@
+# Bundled documentation (`docs`)
+
+ArgsBarg can expose bundled markdown topics as the built-in `docs` command group. Opt in on the program root with `docs: { enabled: true, topics: { ... } }`.
+
+## Quick start
+
+```typescript
+import readmeText from "../README.md" with { type: "text" };
+import archText from "../docs/architecture.md" with { type: "text" };
+
+const cli = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "My app.",
+  docs: {
+    enabled: true,
+    topics: {
+      readme: { text: readmeText },
+      architecture: { text: archText, description: "Contributor architecture notes." },
+    },
+  },
+  commands: [/* ... */],
+} satisfies CliProgram;
+```
+
+```bash
+myapp docs              # first topic (readme) via fallback
+myapp docs readme
+myapp docs architecture
+myapp docs all          # all user topics; includes auto mcp when MCP enabled
+myapp docs mcp          # auto-generated when mcpServer.enabled
+```
+
+## Configuration
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `enabled` | *(required)* | Must be `true` when `docs` is set |
+| `description` | `"Print bundled CLI documentation."` | Router help for `myapp docs` |
+| `defaultTopic` | first key in `topics` | `fallbackCommand` for bare `myapp docs` |
+| `topics` | *(required)* | Topic key → `{ text, description? }` |
+
+Reserved topic keys in `topics`: **`mcp`**, **`all`** (supplied by the built-in).
+
+When `description` is omitted on a topic, ArgsBarg generates leaf help (`readme` → "Print README (user guide).").
+
+## Compile-time bundling
+
+Topic `text` must be **bundled markdown strings**. Use Bun text imports in the consumer module graph:
+
+```typescript
+import readmeText from "../README.md" with { type: "text" };
+```
+
+Bun embeds the file when you `bun build --compile`. ArgsBarg does not read the filesystem at runtime.
+
+For several topics, use a barrel file (e.g. `src/docs/topics.ts`) so `index.tsx` stays small.
+
+## MCP guide (`docs mcp`)
+
+When both `docs.enabled` and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `requiresEnv`, schema resource URI, `install --mcp`, and protocol notes.
+
+There is no override API in v1 — customize behavior via `mcpTool.description` on leaf commands.
+
+## MCP tools
+
+All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: false }`).
+
+## Skills vs docs vs MCP
+
+| Channel | Role |
+| --- | --- |
+| `install --skill` | Shell command catalog + `--schema` JSON (no MCP setup) |
+| `docs` | Bundled markdown on stdout |
+| `mcp` | Callable tools + schema resource |
+
+Do not declare a top-level command named **`docs`** when `docs.enabled` is `true` — it is reserved.

package/examples/nested.ts

@@ -15,6 +15,12 @@ const cli = {
   version: pkg.version,
   description: "Nested groups demo.",
   mcpServer: { enabled: true },
+  docs: {
+    enabled: true,
+    topics: {
+      readme: { text: "# nested.ts\n\nNested groups demo.\n" },
+    },
+  },
   commands: [
     {
       key: "stat",

package/index.d.ts

@@ -173,6 +173,32 @@ export interface CliInstallConfig {
 	/** Default bin directory (default: `~/.local/bin`). Overridden by `INSTALL_PREFIX` env and `--prefix`. */
 	prefix?: string;
 }
+/**
+ * One bundled documentation topic for the `docs` built-in (program root only).
+ */
+export interface CliDocsTopic {
+	/** Bundled markdown (use compile-time text imports in the consumer). */
+	text: string;
+	/** Leaf help text for `myapp docs <key> -h`. Auto-generated from key when omitted. */
+	description?: string;
+}
+/**
+ * Enables `myapp docs` and bundled markdown topics (program root only).
+ * Must include `enabled: true`; omit `docs` entirely to disable.
+ */
+export interface CliDocsConfig {
+	/** When `true`, enables the `docs` built-in command group. */
+	enabled: boolean;
+	/** Router description for `myapp docs` (default: "Print bundled CLI documentation."). */
+	description?: string;
+	/**
+	 * Subcommand for bare `myapp docs` (maps to router `fallbackCommand`).
+	 * When omitted, uses the first key in `topics` (insertion order).
+	 */
+	defaultTopic?: string;
+	/** Topic key → bundled markdown. Reserved keys: `mcp`, `all` (supplied by the built-in). */
+	topics: Record<string, CliDocsTopic>;
+}
 /**
  * Base properties shared by all nodes in the user command tree.
  */
@@ -223,6 +249,8 @@ export type CliProgram = CliNode & {
 	mcpServer?: CliMcpServerConfig;
 	/** Opt-out and defaults for `install`. */
 	install?: CliInstallConfig;
+	/** When set with `enabled: true`, enables the `docs` built-in command group. */
+	docs?: CliDocsConfig;
 };
 /**
  * Handler closure type for leaf commands.

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "argsbarg",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "type": "module",
+  "engines": {
+    "bun": ">=1.3"
+  },
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"
   },

package/src/builtins/dispatch.ts

@@ -9,6 +9,7 @@ import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
 import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
 import { cliPresentationRoot } from "./presentation.ts";
+import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 import { cliMcpServeStdio } from "../mcp.ts";
 import { cliInstall } from "../install/index.ts";
 import type { ParseResult } from "../parse.ts";
@@ -148,5 +149,17 @@ export function builtinInterceptRoot(
     };
   }
 
+  const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
+  if (first === "docs" && docsGroup) {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [docsGroup],
+      },
+      isLeafCompletionIntercept: false,
+    };
+  }
+
   return { parseRoot: program, isLeafCompletionIntercept: false };
 }

package/src/builtins/export.ts

@@ -4,6 +4,7 @@ import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
+import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 
 /** JSON-safe command node (no handlers). */
 export interface CliSchemaExport {
@@ -50,6 +51,10 @@ export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabi
   if (resolved.install) {
     builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program)));
   }
+  const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
+  if (docsGroup) {
+    builtins.push(exportBuiltinNode(docsGroup));
+  }
   if (resolved.mcp) {
     builtins.push(exportBuiltinNode(cliBuiltinMcpCommand()));
   }

package/src/builtins/presentation.ts

@@ -6,6 +6,7 @@ import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
+import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 
 /** Built-in command nodes injected for help, schema, and completions. */
 export function presentationBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
@@ -16,6 +17,10 @@ export function presentationBuiltins(program: CliProgram, caps: CliCapabilities)
   if (caps.install) {
     builtins.push(cliBuiltinInstallCommand(program));
   }
+  const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
+  if (docsGroup) {
+    builtins.push(docsGroup);
+  }
   if (caps.mcp) {
     builtins.push(cliBuiltinMcpCommand());
   }

package/src/capabilities.ts

@@ -10,6 +10,7 @@ export interface CliCapabilities {
   completion: true;
   mcp: boolean;
   install: boolean;
+  docs: boolean;
 }
 
 /** Resolves which capabilities are enabled for a program. */
@@ -18,6 +19,7 @@ export function resolveCapabilities(program: CliProgram): CliCapabilities {
     completion: true,
     mcp: program.mcpServer?.enabled === true,
     install: program.install?.enabled !== false,
+    docs: program.docs?.enabled === true,
   };
 }
 
@@ -27,6 +29,9 @@ export function reservedCommandNames(caps: CliCapabilities): string[] {
   if (caps.install) {
     names.push("install");
   }
+  if (caps.docs) {
+    names.push("docs");
+  }
   if (caps.mcp) {
     names.push("mcp");
   }

package/src/docs/builtin.ts

@@ -0,0 +1,58 @@
+import { CliFallbackMode, type CliLeaf, type CliProgram, type CliRouter } from "../types.ts";
+import {
+  DOCS_ROUTER_DESCRIPTION,
+  docsEffectiveDefaultTopic,
+  docsEnabled,
+  docsIncludesMcpTopic,
+  docsTopicDescription,
+  docsUserTopicKeys,
+  printDocsTopic,
+} from "./resolve.ts";
+
+function docsLeaf(program: CliProgram, key: string, description: string): CliLeaf {
+  return {
+    key,
+    description,
+    mcpTool: { enabled: false },
+    handler: () => {
+      printDocsTopic(program, key);
+    },
+  };
+}
+
+/** Built-in `docs` router with bundled topic subcommands. */
+export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
+  const docs = program.docs!;
+  const leaves: CliLeaf[] = [];
+
+  for (const key of docsUserTopicKeys(docs)) {
+    const topic = docs.topics[key]!;
+    leaves.push(docsLeaf(program, key, docsTopicDescription(key, topic.description)));
+  }
+
+  if (docsIncludesMcpTopic(program)) {
+    leaves.push(
+      docsLeaf(program, "mcp", "Print MCP server setup and tool guidance."),
+    );
+  }
+
+  leaves.push(
+    docsLeaf(program, "all", "Print all bundled documentation combined."),
+  );
+
+  return {
+    key: "docs",
+    description: docs.description ?? DOCS_ROUTER_DESCRIPTION,
+    fallbackCommand: docsEffectiveDefaultTopic(docs),
+    fallbackMode: CliFallbackMode.MissingOnly,
+    commands: leaves,
+  };
+}
+
+/** Returns the docs built-in when enabled. */
+export function cliBuiltinDocsGroupIfEnabled(program: CliProgram): CliRouter | null {
+  if (!docsEnabled(program)) {
+    return null;
+  }
+  return cliBuiltinDocsGroup(program);
+}

package/src/docs/docs.test.ts

@@ -0,0 +1,121 @@
+import { expect, test } from "bun:test";
+import { cliPresentationRoot } from "../builtins/presentation.ts";
+import { completionBashScript } from "../completion.ts";
+import { cliInvoke } from "../index.ts";
+import type { CliProgram } from "../types.ts";
+import { cliValidateProgram } from "../validate.ts";
+import { combineAllDocs, docsEffectiveDefaultTopic } from "./resolve.ts";
+import { generateMcpGuide } from "./mcp-guide.ts";
+
+function docsFixture(mcp = true): CliProgram {
+  return {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo app.",
+    mcpServer: mcp ? { enabled: true } : undefined,
+    docs: {
+      enabled: true,
+      topics: {
+        readme: { text: "# Hello README\n" },
+        arch: { text: "# Architecture\n", description: "Contributor notes." },
+      },
+    },
+    commands: [
+      {
+        key: "run",
+        description: "Run something.",
+        handler: () => {},
+      },
+    ],
+  };
+}
+
+test("docs reserved when enabled", () => {
+  const root: CliProgram = {
+    ...docsFixture(),
+    commands: [
+      {
+        key: "docs",
+        description: "conflict",
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: docs/);
+});
+
+test("docs rejects reserved topic keys", () => {
+  const root = docsFixture();
+  root.docs!.topics.mcp = { text: "nope" };
+  expect(() => cliValidateProgram(root)).toThrow(/reserved/);
+});
+
+test("docsEffectiveDefaultTopic uses first topic key", () => {
+  expect(docsEffectiveDefaultTopic(docsFixture().docs!)).toBe("readme");
+});
+
+test("bare docs prints first topic via cliInvoke", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Hello README");
+});
+
+test("docs readme prints bundled text", async () => {
+  const result = await cliInvoke(docsFixture(), ["docs", "readme"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Hello README");
+});
+
+test("docs defaultTopic override", async () => {
+  const root = docsFixture();
+  root.docs!.defaultTopic = "arch";
+  const result = await cliInvoke(root, ["docs"]);
+  expect(result.stdout).toContain("Architecture");
+});
+
+test("docs mcp when MCP enabled", async () => {
+  const result = await cliInvoke(docsFixture(true), ["docs", "mcp"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("MCP server (myapp)");
+  expect(result.stdout).toContain("myapp mcp");
+});
+
+test("docs mcp absent from router when MCP disabled", async () => {
+  const root = docsFixture(false);
+  const presentation = cliPresentationRoot(root);
+  const docsNode = presentation.commands.find((c) => c.key === "docs");
+  expect(docsNode && "commands" in docsNode).toBe(true);
+  if (docsNode && "commands" in docsNode) {
+    expect(docsNode.commands.some((c) => c.key === "mcp")).toBe(false);
+  }
+  const result = await cliInvoke(root, ["docs", "mcp"]);
+  expect(result.exitCode).not.toBe(0);
+});
+
+test("docs all concatenates user topics and mcp", () => {
+  const program = docsFixture(true);
+  const combined = combineAllDocs(program);
+  expect(combined).toContain("Hello README");
+  expect(combined).toContain("Architecture");
+  expect(combined).toContain("MCP server (myapp)");
+});
+
+test("presentation includes docs subtree", () => {
+  const presentation = cliPresentationRoot(docsFixture());
+  const docsNode = presentation.commands.find((c) => c.key === "docs");
+  expect(docsNode).toBeDefined();
+  expect(docsNode && "commands" in docsNode && docsNode.commands.some((c) => c.key === "readme")).toBe(
+    true,
+  );
+});
+
+test("completions offer docs subcommands", () => {
+  const bash = completionBashScript(cliPresentationRoot(docsFixture()));
+  expect(bash).toContain("docs) echo");
+  expect(bash).toContain("readme) echo");
+});
+
+test("generateMcpGuide includes schema URI", () => {
+  const guide = generateMcpGuide(docsFixture(true));
+  expect(guide).toContain("myapp://schema");
+});

package/src/docs/mcp-guide.ts

@@ -0,0 +1,118 @@
+import { collectOptionDefs } from "../parse.ts";
+import {
+  collectMcpTools,
+  mcpServerId,
+  resolveMcpSchemaUri,
+  type McpToolDef,
+} from "../mcp/tools.ts";
+import { type CliProgram, CliOptionKind } from "../types.ts";
+
+/** Formats one exposed MCP tool for the auto-generated MCP guide. */
+function formatToolLine(root: CliProgram, tool: McpToolDef): 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(", ")})`;
+  }
+  return line;
+}
+
+/** Generates the auto `docs mcp` markdown guide from schema and MCP config. */
+export function generateMcpGuide(root: CliProgram): string {
+  const tools = collectMcpTools(root);
+  const schemaUri = resolveMcpSchemaUri(root);
+  const serverId = mcpServerId(root);
+  const mcp = root.mcpServer!;
+
+  const lines: string[] = [
+    `# MCP server (${root.key})`,
+    "",
+    `${root.key} exposes an MCP server via argsbarg. Each exposed leaf command becomes an MCP tool.`,
+    "",
+    "## Quick start",
+    "",
+    "```bash",
+    `${root.key} mcp`,
+    "```",
+    "",
+    "Cursor / Claude `mcp.json` entry:",
+    "",
+    "```json",
+    JSON.stringify(
+      {
+        mcpServers: {
+          [serverId]: {
+            command: root.key,
+            args: ["mcp"],
+          },
+        },
+      },
+      null,
+      2,
+    ),
+    "```",
+    "",
+    "Or run:",
+    "",
+    "```bash",
+    `${root.key} install --mcp --yes`,
+    "```",
+    "",
+  ];
+
+  if (mcp.shellEnv || mcp.envFile) {
+    lines.push("## Environment", "");
+    if (mcp.shellEnv) {
+      lines.push(
+        "- **`shellEnv`** — captures login-shell environment at MCP startup (PATH, toolchain shims, exports).",
+      );
+    }
+    if (mcp.envFile) {
+      lines.push(
+        "- **`envFile`** — loads `" + mcp.envFile + "` after shell env (overrides for its keys).",
+      );
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "## What agents get",
+    "",
+    "| Mechanism | Purpose |",
+    "|-----------|---------|",
+    "| `tools/list` | Callable tools for exposed leaf commands |",
+    "| `tools/call` | Runs handlers headlessly; JSON stdout becomes `structuredContent` when valid |",
+    `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} --schema\` |`,
+    "",
+    "## Exposed tools",
+    "",
+  );
+
+  if (tools.length === 0) {
+    lines.push("(No MCP tools exposed.)", "");
+  } else {
+    for (const tool of tools) {
+      lines.push(formatToolLine(root, tool));
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "## Tool arguments",
+    "",
+    "Arguments are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
+    `See \`${root.key} --schema\` or the schema resource for per-tool shapes.`,
+    "",
+    "Varargs positionals accept a JSON array or a comma-separated string.",
+    "",
+    "## Protocol",
+    "",
+    "Stdio NDJSON JSON-RPC. Help and `--schema` are not available through tool calls.",
+    `Run \`${root.key} docs\` for bundled user documentation.`,
+    "",
+  );
+
+  return lines.join("\n");
+}

package/src/docs/resolve.ts

@@ -0,0 +1,88 @@
+import type { CliDocsConfig, CliProgram } from "../types.ts";
+import { generateMcpGuide } from "./mcp-guide.ts";
+
+/** Built-in docs subcommand keys not allowed in `docs.topics`. */
+export const DOCS_BUILTIN_TOPIC_KEYS = ["mcp", "all"] as const;
+
+export type DocsBuiltinTopicKey = (typeof DOCS_BUILTIN_TOPIC_KEYS)[number];
+
+/** Default router description for the `docs` built-in. */
+export const DOCS_ROUTER_DESCRIPTION = "Print bundled CLI documentation.";
+
+/** Returns whether bundled docs are enabled on the program root. */
+export function docsEnabled(program: CliProgram): boolean {
+  return program.docs?.enabled === true;
+}
+
+/** User topic keys in declaration order. */
+export function docsUserTopicKeys(docs: CliDocsConfig): string[] {
+  return Object.keys(docs.topics);
+}
+
+/** Subcommand used when argv is bare `myapp docs`. */
+export function docsEffectiveDefaultTopic(docs: CliDocsConfig): string {
+  if (docs.defaultTopic !== undefined) {
+    return docs.defaultTopic;
+  }
+  const keys = docsUserTopicKeys(docs);
+  if (keys.length === 0) {
+    throw new Error("docs.topics must be non-empty");
+  }
+  return keys[0]!;
+}
+
+/** Whether MCP auto-guide topic is included. */
+export function docsIncludesMcpTopic(program: CliProgram): boolean {
+  return docsEnabled(program) && program.mcpServer?.enabled === true;
+}
+
+/** Leaf help description for a user topic. */
+export function docsTopicDescription(key: string, custom?: string): string {
+  if (custom) {
+    return custom;
+  }
+  if (key === "readme") {
+    return "Print README (user guide).";
+  }
+  const label = key.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return `Print ${label} documentation.`;
+}
+
+/** Ordered keys for `docs all` (user topics, then auto `mcp` when enabled). */
+export function docsPrintOrder(program: CliProgram): string[] {
+  const docs = program.docs!;
+  const order = docsUserTopicKeys(docs);
+  if (docsIncludesMcpTopic(program)) {
+    order.push("mcp");
+  }
+  return order;
+}
+
+/** Markdown body for one docs topic key. */
+export function docsTopicText(program: CliProgram, topic: string): string {
+  const docs = program.docs!;
+  if (topic === "mcp") {
+    if (!docsIncludesMcpTopic(program)) {
+      throw new Error("Unknown docs topic 'mcp'.");
+    }
+    return generateMcpGuide(program);
+  }
+  const entry = docs.topics[topic];
+  if (!entry) {
+    throw new Error(`Unknown docs topic '${topic}'.`);
+  }
+  return entry.text;
+}
+
+/** All bundled docs concatenated with horizontal rules. */
+export function combineAllDocs(program: CliProgram): string {
+  return docsPrintOrder(program)
+    .map((key) => docsTopicText(program, key).trim())
+    .join("\n\n---\n\n");
+}
+
+/** Writes one docs topic (or `all`) to stdout. */
+export function printDocsTopic(program: CliProgram, topic: string): void {
+  const content = topic === "all" ? combineAllDocs(program) : docsTopicText(program, topic);
+  process.stdout.write(`${content}\n`);
+}

package/src/index.test.ts

@@ -1760,7 +1760,10 @@ test("generateSkillBundle includes frontmatter and command catalog", () => {
   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 mcp");
+  expect(bundle.skillMd).toContain("Invoke via shell:");
+  expect(bundle.skillMd).not.toContain("mcp.json");
+  expect(bundle.skillMd).not.toContain("Prefer MCP");
+  expect(bundle.skillMd).not.toContain("tools/call");
   expect(bundle.referenceMd).toContain("```json");
   expect(() => JSON.parse(bundle.referenceMd.match(/```json\n([\s\S]*?)\n```/)![1]!)).not.toThrow();
 });

package/src/index.ts

@@ -20,6 +20,8 @@ export type {
   CliMcpServerConfig,
   CliMcpToolConfig,
   CliInstallConfig,
+  CliDocsConfig,
+  CliDocsTopic,
   CliOption,
   CliPositional,
 } from "./types.ts";

package/src/invoke.ts

@@ -5,8 +5,10 @@ process.exit so MCP tool calls can run handlers repeatedly.
 */
 
 import { CliContext } from "./context.ts";
+import { builtinInterceptRoot } from "./builtins/dispatch.ts";
+import { cliPresentationRoot } from "./builtins/presentation.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
-import { type CliNode, type CliProgram, isCliRouter } from "./types.ts";
+import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { format } from "node:util";
 
 /** Outcome of a non-exiting CLI invocation. */
@@ -49,8 +51,18 @@ function findChild(cmds: CliNode[], name: string): CliNode | undefined {
  * Never calls process.exit.
  */
 export async function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult> {
-  let pr = parse(root, argv);
-  pr = postParseValidate(root, pr);
+  let parseRoot: CliNode = root;
+  if (isCliLeaf(root)) {
+    const intercept = builtinInterceptRoot(root, argv);
+    if (intercept.parseRoot !== root) {
+      parseRoot = intercept.parseRoot;
+    }
+  } else {
+    parseRoot = cliPresentationRoot(root);
+  }
+
+  let pr = parse(parseRoot, argv);
+  pr = postParseValidate(parseRoot, pr);
 
   if (pr.kind === ParseKind.Help) {
     return {
@@ -82,7 +94,7 @@ export async function cliInvoke(root: CliProgram, argv: string[]): Promise<CliIn
     };
   }
 
-  let current: CliNode = root;
+  let current: CliNode = parseRoot;
   for (const seg of pr.path) {
     if (!isCliRouter(current)) {
       return {

package/src/runtime.ts

@@ -41,6 +41,11 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
     process.exit(1);
   }
 
+  if (argv.length >= 1 && argv[0] === "docs" && !caps.docs) {
+    process.stderr.write("docs is not enabled. Set docs: { enabled: true } on the program root.\n");
+    process.exit(1);
+  }
+
   let parseRoot: CliNode;
   let completionParseRoot: CliRouter = cliRootMergedWithBuiltins(program);
   let isLeafCompletionIntercept = false;

package/src/schema.ts

@@ -5,7 +5,7 @@ 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";
 
-const RESERVED = new Set(["completion", "install", "mcp"]);
+const RESERVED = new Set(["completion", "install", "docs", "mcp", "version"]);
 
 function exportCommand(cmd: CliNode): CliSchemaExport {
   const out: CliSchemaExport = {

package/src/skill/generate.ts

@@ -4,7 +4,7 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 
 import { collectOptionDefs } from "../parse.ts";
 import { cliSchemaJson } from "../schema.ts";
-import { collectMcpTools, mcpServerId, sanitizeToolSegment } from "../mcp/tools.ts";
+import { collectMcpTools, sanitizeToolSegment } from "../mcp/tools.ts";
 import { CliProgram, CliOptionKind } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
@@ -69,46 +69,14 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
     "## When to use",
     "",
-    `Use this skill when working with **${root.key}** — shell commands, automation, or agent tool calls for this application.`,
+    `Use this skill when working with **${root.key}** — shell commands and automation for this application.`,
     "",
     "## Execution",
     "",
+    "Invoke via shell:",
+    "",
   ];
 
-  if (root.mcpServer?.enabled === true) {
-    lines.push(
-      "**Prefer MCP** when a host has the server connected:",
-      "",
-      "```bash",
-      `${root.key} mcp`,
-      "```",
-      "",
-      "Example Cursor `mcp.json` entry:",
-      "",
-      "```json",
-      JSON.stringify(
-        {
-          mcpServers: {
-            [mcpServerId(root)]: {
-              command: root.key,
-              args: ["mcp"],
-            },
-          },
-        },
-        null,
-        2,
-      ),
-      "```",
-      "",
-      "When MCP tools are available, use `tools/call` with flat JSON arguments. Read the schema resource for full shapes.",
-      "",
-      "Otherwise invoke via shell:",
-      "",
-    );
-  } else {
-    lines.push("Invoke via shell:", "");
-  }
-
   lines.push("```bash", `${root.key} <subcommand> [options] [args]`, "```", "", "## Commands", "");
 
   if (tools.length === 0) {
@@ -124,7 +92,6 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "## Pitfalls",
     "",
     "- Use `--` before tokens that look like flags when they are positional arguments.",
-    "- Under MCP (`ctx.invocation === \"mcp\"`), child processes must not inherit stdout — use piped stdout.",
     "- Required environment variables are listed per command in descriptions (`requires env`).",
     "",
     "## Reference",

package/src/types.ts

@@ -160,6 +160,34 @@ export interface CliInstallConfig {
   prefix?: string;
 }
 
+/**
+ * One bundled documentation topic for the `docs` built-in (program root only).
+ */
+export interface CliDocsTopic {
+  /** Bundled markdown (use compile-time text imports in the consumer). */
+  text: string;
+  /** Leaf help text for `myapp docs <key> -h`. Auto-generated from key when omitted. */
+  description?: string;
+}
+
+/**
+ * Enables `myapp docs` and bundled markdown topics (program root only).
+ * Must include `enabled: true`; omit `docs` entirely to disable.
+ */
+export interface CliDocsConfig {
+  /** When `true`, enables the `docs` built-in command group. */
+  enabled: boolean;
+  /** Router description for `myapp docs` (default: "Print bundled CLI documentation."). */
+  description?: string;
+  /**
+   * Subcommand for bare `myapp docs` (maps to router `fallbackCommand`).
+   * When omitted, uses the first key in `topics` (insertion order).
+   */
+  defaultTopic?: string;
+  /** Topic key → bundled markdown. Reserved keys: `mcp`, `all` (supplied by the built-in). */
+  topics: Record<string, CliDocsTopic>;
+}
+
 /**
  * Base properties shared by all nodes in the user command tree.
  */
@@ -214,6 +242,8 @@ export type CliProgram = CliNode & {
   mcpServer?: CliMcpServerConfig;
   /** Opt-out and defaults for `install`. */
   install?: CliInstallConfig;
+  /** When set with `enabled: true`, enables the `docs` built-in command group. */
+  docs?: CliDocsConfig;
 };
 
 /** True when the node is a leaf (has a handler). */

package/src/validate.ts

@@ -13,6 +13,33 @@ import {
   isCliRouter,
 } from "./types.ts";
 import { resolveMcpSchemaUri } from "./mcp/tools.ts";
+import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
+
+/** Validates `docs` configuration on the program root. */
+function validateDocsConfig(docs: import("./types.ts").CliDocsConfig): void {
+  const keys = Object.keys(docs.topics);
+  if (keys.length === 0) {
+    throw new CliSchemaValidationError("docs.topics must be non-empty");
+  }
+  for (const reserved of DOCS_BUILTIN_TOPIC_KEYS) {
+    if (reserved in docs.topics) {
+      throw new CliSchemaValidationError(
+        `docs.topics key '${reserved}' is reserved for the docs built-in`,
+      );
+    }
+  }
+  if (docs.defaultTopic !== undefined && !(docs.defaultTopic in docs.topics)) {
+    throw new CliSchemaValidationError(
+      `docs.defaultTopic '${docs.defaultTopic}' is not a key in docs.topics`,
+    );
+  }
+  for (const key of keys) {
+    const text = docs.topics[key]?.text;
+    if (text === undefined || text.length === 0) {
+      throw new CliSchemaValidationError(`docs.topics['${key}'].text must be non-empty`);
+    }
+  }
+}
 
 /** Validates a program schema. */
 export function cliValidateProgram(program: CliProgram): void {
@@ -26,6 +53,16 @@ export function cliValidateProgram(program: CliProgram): void {
     );
   }
 
+  if (program.docs !== undefined && program.docs.enabled !== true) {
+    throw new CliSchemaValidationError(
+      "docs requires enabled: true; omit docs to disable bundled documentation",
+    );
+  }
+
+  if (program.docs?.enabled === true) {
+    validateDocsConfig(program.docs);
+  }
+
   const caps = resolveCapabilities(program);
   const reserved = reservedCommandNames(caps);
 
@@ -53,6 +90,11 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
         "install is only supported on the program root (not on " + node.key + ")",
       );
     }
+    if (rogue.docs !== undefined) {
+      throw new CliSchemaValidationError(
+        "docs is only supported on the program root (not on " + node.key + ")",
+      );
+    }
   }
 
   if (isCliLeaf(node)) {