argsbarg 2.1.1 → 3.1.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ 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
+
+- **`version` built-in** — `myapp version` prints `CliProgram.version` (always available; reserved command name).
+
+### Changed
+
+- **`CliProgram.version`** (required) — single source of truth for the `version` built-in and MCP `serverInfo.version`. Removed `mcpServer.version` and automatic `package.json` lookup.
+- **MCP opt-in** — `mcpServer: { enabled: true }` enables MCP; omit `mcpServer` to disable. Empty `mcpServer: {}` is rejected at validation.
+- **MCP identity from `key`** — removed `mcpServer.name`. MCP `serverInfo.name`, schema URI, and `mcp.json` entry keys use `sanitizeToolSegment(root.key)` (e.g. `nested.ts` → `nested_ts://schema`). Shell `command` stays the raw `key`.
+
 ## [2.1.1] - 2026-06-20
 
 ### Changed
@@ -186,7 +208,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/v2.1.1...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
 [2.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v2.0.1

package/README.md

@@ -16,7 +16,7 @@ Why another CLI parser?
 
 *Shell completions* — `completion bash`, `completion zsh`, and `completion fish` built-ins generate installable scripts from your schema so users get tab completion for commands, flags, and positionals without extra tooling.
 
-*Optional MCP server* — set `mcpServer: {}` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp mcp` over stdio). See [docs/mcp.md](docs/mcp.md). Compiled binaries can install binary, completions, skills, and MCP config with `myapp install` — see [docs/install.md](docs/install.md).
+*Optional MCP server* — set `mcpServer: { enabled: true }` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp mcp` over stdio). See [docs/mcp.md](docs/mcp.md). Compiled binaries can install binary, completions, skills, and MCP config with `myapp install` — see [docs/install.md](docs/install.md).
 
 *Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
@@ -39,6 +39,7 @@ import { cliRun, type CliProgram, CliOptionKind } from "argsbarg";
 
 const cli = {
   key: "helloapp",
+  version: "1.0.0",
   description: "Tiny demo.",
   positionals: [
     {
@@ -96,17 +97,20 @@ Every app gets:
 - `-h` / `--help` at any routing depth (scoped help).
 - **`--schema`** at the program root — print the full command tree as JSON (for tooling and agents).
 - **`completion bash` / `completion zsh` / `completion fish`** — print shell completion scripts to stdout (injected by `cliRun`).
-- **`mcp`** — when `mcpServer` is set on the program root, run as an MCP stdio server (`myapp mcp`).
+- **`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`** or **`install`** — they are reserved.
-When **`mcpServer`** is set, do not declare a top-level command named **`mcp`** — it is reserved for the MCP built-in.
+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`.
 
 
 ### MCP (AI agents)
 
-Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `argsbarg://schema`. Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
+Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `<sanitized-key>://schema` (same as `myapp --schema`). Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
 
 See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details.
 
@@ -185,7 +189,7 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 
 ### Capabilities (built-ins)
 
-`completion`, `install`, and `mcp` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, `install`). Reserved command names follow from that config: `completion` and `install` are always reserved unless `install.enabled: false`; `mcp` is reserved when `mcpServer` is set.
+`completion`, `version`, `install`, and `mcp` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, `install`). Reserved command names: `completion` and `version` always; `install` unless `install.enabled: false`; `mcp` when `mcpServer.enabled` is `true`.
 
 
 
@@ -226,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`**, **`install`**, and **`mcp`** (only when `mcpServer` is set).
+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/docs/install.md

@@ -30,7 +30,7 @@ myapp install --uninstall --yes
 | Claude skill | `--skill` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
 | MCP config | `--mcp` | `~/.cursor/mcp.json` and `~/.claude.json` when MCP is enabled |
 
-`--all` expands to `--bin`, `--completions`, `--skill`, and `--mcp` (when `mcpServer` is set).
+`--all` expands to `--bin`, `--completions`, `--skill`, and `--mcp` (when `mcpServer.enabled` is `true`).
 
 Shells not on PATH are skipped silently (no warnings).
 
@@ -64,7 +64,7 @@ Environment:
 
 ## MCP merge behavior
 
-When `--mcp` runs, entries are merged into `mcpServers[<name>]` with:
+When `--mcp` runs, entries are merged into `mcpServers[<sanitized-key>]` with:
 
 ```json
 { "command": "<root.key>", "args": ["mcp"] }

package/docs/mcp.md

@@ -9,15 +9,18 @@ MCP is **opt-in**. Apps that do not set `mcpServer` on the program root behave e
 1. Add `mcpServer` to your program root:
 
 ```typescript
+import pkg from "../package.json" with { type: "json" };
+
 const cli = {
   key: "myapp",
+  version: pkg.version,
   description: "My app.",
-  mcpServer: { name: "myapp", version: "1.0.0" },
+  mcpServer: { enabled: true },
   commands: [/* ... */],
 } satisfies CliProgram;
 ```
 
-`mcpServer: {}` is enough to enable the server. Optional fields override defaults (see [Configuration](#configuration)).
+`mcpServer: { enabled: true }` opts in. Omit `mcpServer` entirely to disable MCP. Empty `mcpServer: {}` is rejected at validation.
 
 2. Run the MCP server:
 
@@ -66,26 +69,27 @@ Set `mcpServer` on the **program root only** (the `CliProgram` passed to `cliRun
 
 | Field | Default | Purpose |
 | --- | --- | --- |
-| `name` | root `key` | `serverInfo.name` in the `initialize` response |
-| `version` | `package.json` `version` in cwd, else `"0.0.0"` | `serverInfo.version` |
-| `schemaResourceUri` | `"argsbarg://schema"` | URI for the schema resource |
+| `enabled` | *(required)* | Must be `true` when `mcpServer` is set |
+| `schemaResourceUri` | `<sanitized root key>://schema` | URI for the built-in schema resource |
 | `shellEnv` | off | Capture login-shell `env` at startup (`true` uses `$SHELL`, or pass a shell path) |
 | `envFile` | off | Load a `.env` file after `shellEnv` (`~` supported); warns on stderr if missing |
-| `resources` | `[]` | Custom `CliMcpResource` entries for `resources/list` and `resources/read` |
+| `resources` | `[]` | Custom `CliMcpResource` entries (additive; schema resource is always included) |
+
+MCP `serverInfo.name` and the default schema URI use the sanitized program `key` (non-alphanumeric characters become `_`). Program `version` comes from `CliProgram.version` (also used by the `version` built-in).
 
-Example with all fields:
+Example with optional fields:
 
 ```typescript
 mcpServer: {
-  name: "nested-demo",
-  version: "1.0.0",
-  schemaResourceUri: "argsbarg://schema",
+  enabled: true,
+  shellEnv: true,
+  envFile: "~/.config/myapp/mcp.env",
 }
 ```
 
 ## Tools
 
-Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `ai`) are not exposed as tools.
+Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `version`, `install`, `mcp`) are not exposed as tools.
 
 ### Tool names
 
@@ -172,11 +176,11 @@ Help and `--schema` are not available through tool calls; use the schema resourc
 
 ## Schema and custom resources
 
-The built-in resource `argsbarg://schema` (or `schemaResourceUri`) exposes your full CLI tree as JSON — the same output as `myapp --schema`.
+The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nested.ts` → `nested_ts://schema`) exposes your full CLI tree as JSON — the same output as `myapp --schema`. Override with `schemaResourceUri` if needed.
 
 | Property | Value |
 | --- | --- |
-| Default URI | `argsbarg://schema` |
+| Default URI | `<sanitized root key>://schema` |
 | MIME type | `application/json` |
 | Contents | `cliSchemaJson(root)` — handlers omitted, built-ins excluded |
 
@@ -184,6 +188,7 @@ Add custom resources on the program root:
 
 ```typescript
 mcpServer: {
+  enabled: true,
   resources: [
     {
       uri: "myapp://config",

package/examples/mcp-test.ts

@@ -9,10 +9,10 @@ const envFilePath = process.env.ARGS_TEST_ENV_FILE;
 
 const cli = {
   key: "mcp-test",
+  version: "0.0.0-test",
   description: "MCP integration test fixture.",
   mcpServer: {
-    name: "mcp-test",
-    version: "0.0.0-test",
+    enabled: true,
     ...(envFilePath ? { envFile: envFilePath } : {}),
     resources: [
       {

package/examples/minimal.ts

@@ -7,10 +7,12 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
+import pkg from "../package.json" with { type: "json" };
 import { cliRun, CliProgram, CliOptionKind } from "../src/index.ts";
 
 const cli = {
   key: "minimal.ts",
+  version: pkg.version,
   description: "Tiny demo.",
   positionals: [
     {

package/examples/nested.ts

@@ -7,12 +7,20 @@ and fallback commands fit together in one schema.
 It demonstrates how the schema scales beyond one command.
 */
 
+import pkg from "../package.json" with { type: "json" };
 import { cliRun, CliProgram, CliOptionKind, CliFallbackMode } from "../src/index.ts";
 
 const cli = {
   key: "nested.ts",
+  version: pkg.version,
   description: "Nested groups demo.",
-  mcpServer: { name: "nested-demo", version: "1.0.0" },
+  mcpServer: { enabled: true },
+  docs: {
+    enabled: true,
+    topics: {
+      readme: { text: "# nested.ts\n\nNested groups demo.\n" },
+    },
+  },
   commands: [
     {
       key: "stat",

package/examples/option-required.ts

@@ -7,10 +7,12 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
+import pkg from "../package.json" with { type: "json" };
 import { cliRun, CliProgram, CliOptionKind, CliFallbackMode, isInteractiveTty } from "../src/index.ts";
 
 const cli = {
   key: "option-required.ts",
+  version: pkg.version,
   description: "Demo of a required option.",
   options: [
     {

package/index.d.ts

@@ -106,13 +106,12 @@ export interface CliPositional {
 }
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
+ * Must include `enabled: true`; omit `mcpServer` entirely to disable MCP.
  */
 export interface CliMcpServerConfig {
-	/** `initialize` serverInfo.name (default: root `key`). */
-	name?: string;
-	/** `initialize` serverInfo.version (default: see resolveMcpVersion). */
-	version?: string;
-	/** Resource URI for schema export (default: `"argsbarg://schema"`). */
+	/** When `true`, enables the `mcp` built-in and MCP stdio server. */
+	enabled: boolean;
+	/** Resource URI for schema export (default: `<sanitized root key>://schema`). */
 	schemaResourceUri?: string;
 	/**
 	 * Capture the user's login shell environment at MCP server start and merge it
@@ -127,7 +126,7 @@ export interface CliMcpServerConfig {
 	 */
 	envFile?: string;
 	/**
-	 * Custom MCP resources exposed alongside the built-in argsbarg://schema resource.
+	 * Custom MCP resources exposed alongside the built-in schema resource.
 	 * URIs must be unique and must not equal schemaResourceUri.
 	 */
 	resources?: CliMcpResource[];
@@ -174,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.
  */
@@ -218,10 +243,14 @@ export type CliNode = CliLeaf | CliRouter;
  * May be a leaf or router, plus optional program-level MCP and install config.
  */
 export type CliProgram = CliNode & {
-	/** When set, enables the `mcp` built-in subcommand. */
+	/** Program version (printed by the `version` built-in and MCP serverInfo). */
+	version: string;
+	/** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
 	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": "2.1.1",
+  "version": "3.1.0",
   "type": "module",
+  "engines": {
+    "bun": ">=1.3"
+  },
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"
   },

package/src/builtins/builtins.test.ts

@@ -8,8 +8,9 @@ import { CliProgram } from "../types.ts";
 
 const fixture: CliProgram = {
   key: "myapp",
+  version: "0.0.0",
   description: "Demo app.",
-  mcpServer: { name: "myapp" },
+  mcpServer: { enabled: true },
   commands: [
     {
       key: "hello",
@@ -31,7 +32,7 @@ describe("builtins help copy", () => {
   });
 
   test("install omits --mcp option when mcpServer unset", () => {
-    const noMcp: CliProgram = { key: "x", description: "x", handler: () => {} };
+    const noMcp: CliProgram = { key: "x", version: "0.0.0", description: "x", handler: () => {} };
     const names = installBuiltinOptions(noMcp).map((o) => o.name);
     expect(names).not.toContain("mcp");
   });
@@ -56,6 +57,10 @@ describe("presentation root", () => {
     const root = cliPresentationRoot(disabled);
     expect(root.commands?.map((c) => c.key)).not.toContain("install");
   });
+  test("includes version builtin", () => {
+    const root = cliPresentationRoot(fixture);
+    expect(root.commands?.map((c) => c.key)).toContain("version");
+  });
 });
 
 describe("completion emitters", () => {
@@ -75,7 +80,7 @@ describe("completion emitters", () => {
   });
 
   test("zsh script registers compdef", () => {
-    const schema = cliPresentationRoot({ key: "zapp", description: "z", handler: () => {} });
+    const schema = cliPresentationRoot({ key: "zapp", version: "0.0.0", description: "z", handler: () => {} });
     const zsh = completionZshScript(schema);
     expect(zsh).toContain("#compdef zapp");
     expect(zsh).toContain("compdef _zapp zapp");

package/src/builtins/dispatch.ts

@@ -6,8 +6,10 @@ import { completionFishScript } from "./completion-fish.ts";
 import { completionZshScript } from "./completion-zsh.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 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";
@@ -56,9 +58,18 @@ export async function dispatchBuiltin(
     return;
   }
 
+  if (pr.path[0] === "version") {
+    if (pr.path.length !== 1) {
+      process.stderr.write("Unknown subcommand: version " + pr.path.slice(1).join(" ") + "\n");
+      process.exit(1);
+    }
+    process.stdout.write(program.version + "\n");
+    process.exit(0);
+  }
+
   if (pr.path[0] === "mcp") {
     if (!caps.mcp) {
-      process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
+      process.stderr.write("MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n");
       process.exit(1);
     }
     if (pr.path.length !== 1) {
@@ -127,5 +138,28 @@ export function builtinInterceptRoot(
     };
   }
 
+  if (first === "version") {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [cliBuiltinVersionCommand()],
+      },
+      isLeafCompletionIntercept: false,
+    };
+  }
+
+  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

@@ -3,6 +3,8 @@ import type { CliFallbackMode, CliOption, CliPositional, CliProgram } from "../t
 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 {
@@ -42,10 +44,17 @@ function exportBuiltinNode(cmd: {
 /** Built-in subtrees matching help visibility for `--schema` export. */
 export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabilities): CliSchemaExport[] {
   const resolved = caps ?? resolveCapabilities(program);
-  const builtins: CliSchemaExport[] = [exportBuiltinNode(cliBuiltinCompletionGroup(program.key))];
+  const builtins: CliSchemaExport[] = [
+    exportBuiltinNode(cliBuiltinCompletionGroup(program.key)),
+    exportBuiltinNode(cliBuiltinVersionCommand()),
+  ];
   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/install.ts

@@ -1,3 +1,4 @@
+import { resolveCapabilities } from "../capabilities.ts";
 import { CliProgram, CliOption, CliOptionKind, type CliLeaf } from "../types.ts";
 
 /** Install command options (dynamic: `--mcp` only when MCP is enabled). */
@@ -66,7 +67,7 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     },
   ];
 
-  if (root.mcpServer !== undefined) {
+  if (resolveCapabilities(root).mcp) {
     opts.splice(4, 0, {
       name: "mcp",
       description: "Add or update MCP server entries in Cursor and Claude config files.",

package/src/builtins/presentation.ts

@@ -5,13 +5,22 @@ import { isCliLeaf, isCliRouter } from "../types.ts";
 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[] {
-  const builtins: CliNode[] = [cliBuiltinCompletionGroup(program.key)];
+  const builtins: CliNode[] = [
+    cliBuiltinCompletionGroup(program.key),
+    cliBuiltinVersionCommand(),
+  ];
   if (caps.install) {
     builtins.push(cliBuiltinInstallCommand(program));
   }
+  const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
+  if (docsGroup) {
+    builtins.push(docsGroup);
+  }
   if (caps.mcp) {
     builtins.push(cliBuiltinMcpCommand());
   }

package/src/builtins/version.ts

@@ -0,0 +1,10 @@
+import { type CliLeaf } from "../types.ts";
+
+/** Top-level `version` built-in (leaf). */
+export function cliBuiltinVersionCommand(): CliLeaf {
+  return {
+    key: "version",
+    description: "Print the program version.",
+    handler: () => {},
+  };
+}