argsbarg 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.0] - 2026-06-20
+
+### Added
+
+- **`docs schema`** — print the full command tree as JSON (`myapp docs schema`). Replaces root `--schema` (requires `docs.enabled`).
+- **`docs api`** — print the command tree as markdown (`myapp docs api`). Human-readable companion to `docs schema`.
+- **`docs skill`** — print generated Cursor `SKILL.md` content to stdout (`myapp docs skill`).
+- **`update` built-in** — when `install.updateGetLatest` is set, `myapp update` downloads the latest binary and reinstalls installed artifacts.
+- **`install --reinstall`** — replaces `--update` (still accepted as a deprecated alias). Optional `--from <path>` for the binary source.
+
+### Changed
+
+- **Breaking:** root **`--schema`** removed — use **`docs schema`** when `docs.enabled` is `true`.
+- **Breaking:** **`install --update`** renamed to **`install --reinstall`**.
+
+## [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 +223,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.0.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.2.0...HEAD
+[3.2.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.2.0
+[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

@@ -95,20 +95,20 @@ Everything you need for a first-class CLI:
 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`).
 - **`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, schema JSON, API markdown, and generated skill content (`myapp docs`, `myapp docs readme`, `myapp docs schema`, `myapp docs api`, `myapp docs skill`, …). 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.
-Do not declare an option named **`schema`** — it is reserved for `--schema`.
+When **`docs.enabled`** is `true`, do not declare a top-level command named **`docs`** — it is reserved for the docs built-in.
 
 
 ### MCP (AI agents)
 
-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.
+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 docs 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.
 
@@ -122,7 +122,7 @@ myapp install --all --yes
 
 This copies the binary to `~/.local/bin`, installs shell completions (bash/zsh/fish when each shell is on PATH), writes Cursor/Claude skills when agent directories exist, and merges MCP server entries into Cursor and Claude config files.
 
-See **[docs/install.md](docs/install.md)** for `--update`, `--status`, `--uninstall`, and flags.
+See **[docs/install.md](docs/install.md)** for `--reinstall`, `update`, `--status`, `--uninstall`, and flags.
 
 
 ### Shell completions
@@ -187,7 +187,7 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 
 ### Capabilities (built-ins)
 
-`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`.
+`completion`, `version`, `install`, `update`, and `mcp` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, `install`, `docs`). Reserved command names: `completion` and `version` always; `install` unless `install.enabled: false`; `update` when `install.updateGetLatest` is set; `mcp` when `mcpServer.enabled` is `true`; `docs` when `docs.enabled` is `true`.
 
 
 
@@ -228,7 +228,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
-- **`reference.md`** — full `--schema` JSON export
+- **`SKILL.md`** — YAML frontmatter, when-to-use guidance, shell command catalog, pitfalls
+- **`reference.md`** — full `docs 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,91 @@
+# 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 schema       # full command tree as JSON
+myapp docs api          # command tree as markdown
+myapp docs skill        # generated Cursor SKILL.md
+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`**, **`schema`**, **`api`**, **`skill`** (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.
+
+## Schema, API, and skill (`docs schema`, `docs api`, `docs skill`)
+
+When `docs.enabled` is `true`:
+
+- **`docs schema`** — same JSON as the former root `--schema` flag (handlers omitted; built-in subtrees included for leaf roots).
+- **`docs api`** — markdown rendering of the same command tree (options, positionals, subcommands, fallback routing).
+- **`docs skill`** — prints generated Cursor `SKILL.md` content (same prose as `install --skill`, without writing files).
+
+## 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` | Writes shell command catalog + `reference.md` to disk |
+| `docs skill` | Print generated `SKILL.md` to stdout |
+| `docs api` | Print command tree markdown to stdout |
+| `docs schema` | Print command tree JSON to stdout |
+| `docs` | Bundled markdown topics 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

@@ -8,8 +8,11 @@ The `install` built-in installs the binary, shell completions, agent skills, and
 # First-time setup
 myapp install --all --yes
 
-# Refresh after upgrading
-myapp install --update
+# Refresh after upgrading (re-copy running binary + refresh installed artifacts)
+myapp install --reinstall
+
+# Download latest release (when install.updateGetLatest is configured)
+myapp update
 
 # See what is installed
 myapp install --status
@@ -42,9 +45,15 @@ On the program root:
 install: {
   enabled: false,       // opt out of the install built-in
   prefix: "~/.local/bin", // default bin directory
+  updateGetLatest: async ({ version }) => {
+    // download or locate latest binary; return { path, version, cleanup }
+    return { path: "/tmp/myapp", version: "2.0.0" };
+  },
 }
 ```
 
+When `updateGetLatest` is set, ArgsBarg also registers the **`update`** built-in (`myapp update`).
+
 Environment:
 
 - `INSTALL_PREFIX` — same as `install.prefix` / `--prefix`
@@ -53,15 +62,18 @@ Environment:
 
 | Flag | Description |
 | --- | --- |
-| `--yes` | Skip confirmation (required for non-TTY unless `--json` / `--update`) |
+| `--yes` | Skip confirmation (required for non-TTY unless `--json` / `--reinstall`) |
 | `--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`) |
 | `--prefix <dir>` | Override binary install directory |
-| `--update` | Update only artifacts already installed (implies `--bin` + `--yes`) |
+| `--reinstall` | Reinstall artifacts already on disk (implies `--bin` + `--yes`) |
+| `--from <path>` | Binary to copy with `--reinstall` (default: running executable) |
 | `--status` | Read-only inventory |
 | `--uninstall` | Remove detected artifacts (scope with `--bin`, `--completions`, `--skill`, `--mcp`) |
 
+`--update` is accepted as a deprecated alias for `--reinstall`.
+
 ## MCP merge behavior
 
 When `--mcp` runs, entries are merged into `mcpServers[<sanitized-key>]` with:

package/docs/mcp.md

@@ -113,7 +113,7 @@ Each tool’s `description` includes the human CLI path and the leaf’s help te
 
 ### Per-leaf visibility
 
-Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/list` while keeping it in the CLI and in `--schema` output:
+Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/list` while keeping it in the CLI and in `docs schema` output:
 
 ```typescript
 {
@@ -172,11 +172,11 @@ On success (`isError: false`):
 
 On failure (parse error, validation error, non-zero exit, thrown error), the message is returned as text content with `isError: true`. Handler stderr is included when present.
 
-Help and `--schema` are not available through tool calls; use the schema resource or run the CLI directly for those.
+Help and `docs schema` are not available through tool calls; use the schema resource or run the CLI directly for those.
 
 ## Schema and custom resources
 
-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.
+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 docs schema`. Override with `schemaResourceUri` if needed.
 
 | Property | Value |
 | --- | --- |
@@ -291,9 +291,7 @@ You should get one JSON line on stdout with `result.capabilities` and `result.se
 
 When MCP is enabled:
 
-- Do not declare a top-level command named **`ai`** — it is reserved for the built-in AI integration group.
 - Do not declare a top-level command named **`completion`** — reserved for shell completions.
-- Do not declare an option named **`schema`** — reserved for `--schema`.
 
 Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1).
 
@@ -304,4 +302,4 @@ Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1)
 - **User schema only** — tool dispatch uses your program root, not merged presentation builtins.
 - **Buffered output** — MCP tool results are sent after the handler finishes. Incremental stdout (log tail, progress) is not streamed; a future release may add MCP progress notifications.
 
-For the `--schema` export used by the resource, see the main README built-ins section.
+For the `docs schema` export used by the resource, see [docs/bundled-docs.md](bundled-docs.md).

package/examples/minimal.ts

@@ -14,6 +14,12 @@ const cli = {
   key: "minimal.ts",
   version: pkg.version,
   description: "Tiny demo.",
+  docs: {
+    enabled: true,
+    topics: {
+      readme: { text: "# minimal.ts\n\nTiny demo.\n" },
+    },
+  },
   positionals: [
     {
       name: "name",

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

@@ -167,11 +167,54 @@ export interface CliMcpToolConfig {
 /**
  * Opt-out and defaults for the `install` built-in (program root only).
  */
+export interface CliUpdateArtifact {
+	/** Path to an executable binary to copy into the install location. */
+	path: string;
+	/** Release version of `path` (used for already-current checks and success messages). */
+	version?: string;
+	/** Called after reinstall completes (e.g. remove a temp download directory). */
+	cleanup?: () => void | Promise<void>;
+}
+/** Fetches the latest release binary for the `update` built-in. */
+export type CliUpdateGetLatest = (ctx: {
+	version: string;
+}) => Promise<CliUpdateArtifact>;
 export interface CliInstallConfig {
 	/** When `false`, hide/disable `install` (default: enabled). */
 	enabled?: boolean;
 	/** Default bin directory (default: `~/.local/bin`). Overridden by `INSTALL_PREFIX` env and `--prefix`. */
 	prefix?: string;
+	/**
+	 * When set, enables the `update` built-in (`myapp update`).
+	 * Should download or locate the latest release binary and return its path.
+	 */
+	updateGetLatest?: CliUpdateGetLatest;
+}
+/**
+ * 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 +266,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.
@@ -237,7 +282,7 @@ export declare class CliSchemaValidationError extends Error {
 	constructor(message: string);
 }
 /** Outcome of a non-exiting CLI invocation. */
-export type CliInvokeKind = "ok" | "help" | "schema" | "error";
+export type CliInvokeKind = "ok" | "help" | "error";
 /** Result of cliInvoke: captured output and exit metadata without process.exit. */
 export interface CliInvokeResult {
 	/** Invocation outcome. */

package/package.json

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

package/src/builtins/completion-bash.ts

@@ -5,7 +5,6 @@ import {
   identToken,
   kHelpLong,
   kHelpShort,
-  kSchemaLong,
   mainName,
 } from "./shell-helpers.ts";
 
@@ -17,9 +16,6 @@ function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
     o += "    " + i + ")\n";
     o += "      case $w in\n";
     o += "        " + kHelpLong + "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n".replace(/\$\{kHelpLong\}/g, kHelpLong).replace(/\$\{kHelpShort\}/g, kHelpShort);
-    if (sc.path === "") {
-      o += "        " + kSchemaLong + ") echo 1 ;;\n";
-    }
     for (const op of sc.opts) {
       const base = "--" + op.name;
       if (op.kind === "presence") {
@@ -107,7 +103,7 @@ function emitSimulate(ident: string): string {
   o += "  local i=1 sid=0 w steps next\n";
   o += "  while (( i < COMP_CWORD )); do\n";
   o += "    w=\"${COMP_WORDS[i]}\"\n";
-  o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " || $w == " + kSchemaLong + " ]]; then\n";
+  o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " ]]; then\n";
   o += "      ((i++)); continue\n";
   o += "    fi\n";
   o += "    if [[ $w == --* ]]; then\n";
@@ -209,9 +205,6 @@ export function completionBashScript(schema: CliRouter): string {
   for (const [i, sc] of scopes.entries()) {
     out += "A_" + ident + "_" + i + "_opts=()\n";
     out += "A_" + ident + "_" + i + "_opts+=('" + kHelpLong + "' '" + kHelpShort + "')\n";
-    if (sc.path === "") {
-      out += "A_" + ident + "_" + i + "_opts+=('" + kSchemaLong + "')\n";
-    }
     for (const o of sc.opts) {
       out += "A_" + ident + "_" + i + "_opts+=('--" + o.name + "')\n";
       if (o.shortName) {

package/src/builtins/completion-fish.ts

@@ -5,8 +5,6 @@ import {
   identToken,
   kHelpLong,
   kHelpShort,
-  kSchemaDesc,
-  kSchemaLong,
 } from "./shell-helpers.ts";
 
 function scopeCondition(ident: string, scopeIndex: number, path: string): string {
@@ -43,9 +41,6 @@ export function completionFishScript(schema: CliRouter): string {
     }
 
     out += `complete -c ${app} -n '${cond}' -s h -l help -d '${escFishSingleQuoted("Show help for this command.")}'\n`;
-    if (sc.path === "") {
-      out += `complete -c ${app} -n '${cond}' -l schema -d '${escFishSingleQuoted(kSchemaDesc)}'\n`;
-    }
 
     for (const op of sc.opts) {
       if (op.kind === CliOptionKind.Presence) {

package/src/builtins/completion-zsh.ts

@@ -5,8 +5,6 @@ import {
   identToken,
   kHelpLong,
   kHelpShort,
-  kSchemaDesc,
-  kSchemaLong,
   mainName,
 } from "./shell-helpers.ts";
 
@@ -16,9 +14,6 @@ function emitScopeArraysZsh(ident: string, scopes: ScopeRec[]): string {
     out += "typeset -g A_" + ident + "_" + i + "_opts\n";
     out += "A_" + ident + "_" + i + "_opts=(";
     out += "'" + escShellSingleQuoted(kHelpLong) + ":" + escShellSingleQuoted("Show help for this command.") + "' '" + escShellSingleQuoted(kHelpShort) + ":" + escShellSingleQuoted("Show help for this command.") + "'";
-    if (sc.path === "") {
-      out += " '" + escShellSingleQuoted(kSchemaLong) + ":" + escShellSingleQuoted(kSchemaDesc) + "'";
-    }
     for (const o of sc.opts) {
       out += " '" + escShellSingleQuoted("--" + o.name) + ":" + escShellSingleQuoted(o.description) + "'";
       if (o.shortName) {
@@ -47,9 +42,6 @@ function emitConsumeLongZsh(ident: string, scopes: ScopeRec[]): string {
     o += "    " + i + ")\n";
     o += "      case $w in\n";
     o += "        " + kHelpLong + "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n".replace(/\$\{kHelpLong\}/g, kHelpLong).replace(/\$\{kHelpShort\}/g, kHelpShort);
-    if (sc.path === "") {
-      o += "        " + kSchemaLong + ") echo 1 ;;\n";
-    }
     for (const op of sc.opts) {
       const base = "--" + op.name;
       if (op.kind === "presence") {
@@ -137,7 +129,7 @@ function emitSimulateZsh(ident: string): string {
   o += "  local i=2 sid=0 w steps next\n";
   o += "  while (( i < CURRENT )); do\n";
   o += "    w=$words[i]\n";
-  o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " || $w == " + kSchemaLong + " ]]; then\n";
+  o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " ]]; then\n";
   o += "      ((i++)); continue\n";
   o += "    fi\n";
   o += "    if [[ $w == --* ]]; then\n";

package/src/builtins/dispatch.ts

@@ -6,11 +6,14 @@ import { completionFishScript } from "./completion-fish.ts";
 import { completionZshScript } from "./completion-zsh.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliBuiltinUpdateCommand } from "./update.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 { cliUpdate } from "../install/update.ts";
 import type { ParseResult } from "../parse.ts";
 import { ParseKind } from "../parse.ts";
 
@@ -79,6 +82,20 @@ export async function dispatchBuiltin(
     process.exit(0);
   }
 
+  if (pr.path[0] === "update") {
+    if (!caps.update) {
+      process.stderr.write(
+        "update is not enabled. Set install.updateGetLatest on the program root.\n",
+      );
+      process.exit(1);
+    }
+    if (pr.path.length !== 1) {
+      process.stderr.write("Unknown subcommand: update " + pr.path.slice(1).join(" ") + "\n");
+      process.exit(1);
+    }
+    await cliUpdate(program);
+  }
+
   if (pr.path[0] === "install") {
     if (!caps.install) {
       process.stderr.write("install is disabled. Remove install.enabled: false from the program root.\n");
@@ -126,6 +143,17 @@ export function builtinInterceptRoot(
     };
   }
 
+  if (first === "update" && caps.update) {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [cliBuiltinUpdateCommand(program)],
+      },
+      isLeafCompletionIntercept: false,
+    };
+  }
+
   if (first === "mcp" && caps.mcp) {
     return {
       parseRoot: {
@@ -148,5 +176,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

@@ -3,7 +3,9 @@ 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 { cliBuiltinUpdateCommand } from "./update.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
+import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 
 /** JSON-safe command node (no handlers). */
 export interface CliSchemaExport {
@@ -50,6 +52,13 @@ export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabi
   if (resolved.install) {
     builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program)));
   }
+  if (resolved.update) {
+    builtins.push(exportBuiltinNode(cliBuiltinUpdateCommand(program)));
+  }
+  const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
+  if (docsGroup) {
+    builtins.push(exportBuiltinNode(docsGroup));
+  }
   if (resolved.mcp) {
     builtins.push(exportBuiltinNode(cliBuiltinMcpCommand()));
   }

package/src/builtins/install.ts

@@ -26,10 +26,15 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
       kind: CliOptionKind.Presence,
     },
     {
-      name: "update",
-      description: "Update only artifacts already installed (always includes the binary).",
+      name: "reinstall",
+      description: "Reinstall artifacts already on disk (always includes the binary).",
       kind: CliOptionKind.Presence,
     },
+    {
+      name: "from",
+      description: "Binary to copy (default: running executable). Used with --reinstall.",
+      kind: CliOptionKind.String,
+    },
     {
       name: "status",
       description: "Print what is currently installed (read-only).",
@@ -87,7 +92,8 @@ export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
       "First-time setup:\n" +
       `  {app} install --all --yes\n\n` +
       "Refresh after upgrading:\n" +
-      `  {app} install --update\n\n` +
+      `  {app} install --reinstall\n` +
+      `  {app} update\n\n` +
       "See what is installed:\n" +
       `  {app} install --status\n\n` +
       "Remove everything:\n" +