argsbarg 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ 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
@@ -208,7 +223,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.1.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

package/README.md

@@ -95,22 +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 (`myapp docs`, `myapp docs readme`, …). See [docs/bundled-docs.md](docs/bundled-docs.md).
+- **`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.
 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: { 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.
 
@@ -124,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
@@ -189,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`.
 
 
 

package/docs/ai-skills.md

@@ -32,7 +32,7 @@ For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true
 ## Generated content
 
 - **`SKILL.md`** — YAML frontmatter, when-to-use guidance, shell command catalog, pitfalls
-- **`reference.md`** — full `--schema` JSON export
+- **`reference.md`** — full `docs schema` JSON export
 
 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.
 

package/docs/bundled-docs.md

@@ -27,6 +27,9 @@ const cli = {
 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
 ```
@@ -40,7 +43,7 @@ myapp docs mcp          # auto-generated when mcpServer.enabled
 | `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).
+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).").
 
@@ -56,6 +59,14 @@ Bun embeds the file when you `bun build --compile`. ArgsBarg does not read the f
 
 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.
@@ -70,8 +81,11 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 
 | Channel | Role |
 | --- | --- |
-| `install --skill` | Shell command catalog + `--schema` JSON (no MCP setup) |
-| `docs` | Bundled markdown on stdout |
+| `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/index.d.ts

@@ -167,11 +167,28 @@ 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).
@@ -265,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,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

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,12 +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";
 
@@ -80,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");
@@ -127,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: {

package/src/builtins/export.ts

@@ -3,6 +3,7 @@ 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";
 
@@ -51,6 +52,9 @@ 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));

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" +

package/src/builtins/presentation.ts

@@ -5,6 +5,7 @@ import { isCliLeaf, isCliRouter } from "../types.ts";
 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";
 
@@ -17,6 +18,9 @@ export function presentationBuiltins(program: CliProgram, caps: CliCapabilities)
   if (caps.install) {
     builtins.push(cliBuiltinInstallCommand(program));
   }
+  if (caps.update) {
+    builtins.push(cliBuiltinUpdateCommand(program));
+  }
   const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
   if (docsGroup) {
     builtins.push(docsGroup);

package/src/builtins/shell-helpers.ts

@@ -20,5 +20,3 @@ export function mainName(schemaName: string): string {
 
 export const kHelpLong = "--help";
 export const kHelpShort = "-h";
-export const kSchemaLong = "--schema";
-export const kSchemaDesc = "Print the full command tree as JSON.";

package/src/builtins/update.ts

@@ -0,0 +1,14 @@
+import type { CliLeaf, CliProgram } from "../types.ts";
+import { cliUpdate } from "../install/update.ts";
+
+/** Built-in `update` command (enabled when `install.updateGetLatest` is set). */
+export function cliBuiltinUpdateCommand(program: CliProgram): CliLeaf {
+  return {
+    key: "update",
+    description: "Download and install the latest release.",
+    mcpTool: { enabled: false },
+    handler: async () => {
+      await cliUpdate(program);
+    },
+  };
+}

package/src/capabilities.ts

@@ -11,15 +11,18 @@ export interface CliCapabilities {
   mcp: boolean;
   install: boolean;
   docs: boolean;
+  update: boolean;
 }
 
 /** Resolves which capabilities are enabled for a program. */
 export function resolveCapabilities(program: CliProgram): CliCapabilities {
+  const install = program.install?.enabled !== false;
   return {
     completion: true,
     mcp: program.mcpServer?.enabled === true,
-    install: program.install?.enabled !== false,
+    install,
     docs: program.docs?.enabled === true,
+    update: install && typeof program.install?.updateGetLatest === "function",
   };
 }
 
@@ -29,6 +32,9 @@ export function reservedCommandNames(caps: CliCapabilities): string[] {
   if (caps.install) {
     names.push("install");
   }
+  if (caps.update) {
+    names.push("update");
+  }
   if (caps.docs) {
     names.push("docs");
   }

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

@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test";
+import type { CliProgram } from "../types.ts";
+import { CliOptionKind } from "../types.ts";
+import { generateApiGuide } from "./api-guide.ts";
+import { cliSchemaExport } from "../schema.ts";
+
+const nestedFixture: CliProgram = {
+  key: "nested.ts",
+  version: "1.0.0",
+  description: "Nested groups demo.",
+  docs: { enabled: true, topics: { readme: { text: "# readme\n" } } },
+  commands: [
+    {
+      key: "stat",
+      description: "File metadata.",
+      commands: [
+        {
+          key: "owner",
+          description: "Ownership helpers.",
+          commands: [
+            {
+              key: "lookup",
+              description: "Resolve owner info.",
+              options: [
+                {
+                  name: "user-name",
+                  description: "User to look up.",
+                  kind: CliOptionKind.String,
+                  shortName: "u",
+                },
+              ],
+              positionals: [
+                {
+                  name: "path",
+                  description: "File or directory.",
+                  kind: CliOptionKind.String,
+                },
+              ],
+              handler: () => {},
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
+  const md = generateApiGuide(nestedFixture);
+  const schema = cliSchemaExport(nestedFixture);
+  expect(md).toContain("`nested.ts stat owner lookup`");
+  expect(md).toContain("`--user-name` (`-u`)");
+  expect(md).toContain("`<path>`");
+  expect(schema.commands?.map((c) => c.key)).toEqual(["stat"]);
+});