argsbarg 1.4.3 → 2.0.0

package/.cursor/plans/cliprogram_capabilities_refactor_081e1737.plan.md

@@ -0,0 +1,224 @@
+---
+name: CliProgram capabilities refactor
+overview: Introduce `CliNode` / `CliProgram` types and an internal capabilities resolver, replacing `CliCommand` in the public API as a **2.0.0 breaking change**. Keep capability machinery private to avoid locking in unstable internals.
+todos:
+  - id: types-split
+    content: "Refactor src/types.ts: CliNodeBase, CliLeaf, CliRouter, CliNode, CliProgram; remove CliCommand"
+    status: completed
+  - id: capabilities-module
+    content: Add internal src/capabilities.ts (resolveCapabilities, reservedCommandNames)
+    status: completed
+  - id: wire-validate-presentation
+    content: Update validate.ts, presentation.ts, export.ts, dispatch.ts, runtime.ts, invoke.ts to use CliProgram + caps
+    status: completed
+  - id: internal-walkers
+    content: Update parse, context, mcp/tools, completion scopes, install paths to CliNode/CliProgram as appropriate
+    status: completed
+  - id: public-api-2
+    content: Update index.ts exports (CliProgram only), run typegen, bump 2.0.0 CHANGELOG; verify qa-cli + idp-trees compile against local checkout
+    status: completed
+  - id: examples-docs
+    content: Migrate examples + README to CliProgram / satisfies pattern
+    status: completed
+  - id: tests-migrate
+    content: Migrate tests; keep runtime negative tests with cast helpers
+    status: completed
+  - id: nice-to-haves
+    content: "Optional: ctx.program getter, cliValidateProgram rename, satisfies examples, @ts-expect-error type tests"
+    status: completed
+isProject: false
+---
+
+# CliProgram + internal capabilities (2.0)
+
+## Goals
+
+- **Types**: `CliNode` (user tree) + `CliProgram` (what `cliRun` accepts) with root-only `mcpServer` / `install` only on `CliProgram`.
+- **Capabilities**: One internal resolver drives reserved names, help/schema/completion visibility, and dispatch guards.
+- **Exports**: Minimal public surface — no `resolveCapabilities`, no presentation helpers, no builtin command builders.
+- **Breaking**: Drop `CliCommand` from the public API — ship **2.0.0 directly** (Option B; no deprecated alias release).
+
+## Type model
+
+Add to [`src/types.ts`](src/types.ts):
+
+```typescript
+interface CliNodeBase { key; description; notes?; options? }
+
+type CliLeaf = CliNodeBase & { handler; positionals?; mcpTool? }
+type CliRouter = CliNodeBase & { commands: CliNode[]; fallbackCommand?; fallbackMode? }
+type CliNode = CliLeaf | CliRouter
+
+type CliProgram = CliNode & { mcpServer?; install? }
+```
+
+Remove `mcpServer`, `install`, `mcpTool` from a shared `CliCommandBase`. Remove the old `CliCommand` union entirely **inside the repo**.
+
+**Leaf program roots** (`examples/minimal.ts`) remain valid: `CliProgram` = leaf + root config.
+
+```mermaid
+flowchart TB
+  subgraph public [Public API]
+    CliProgram
+    cliRun["cliRun(program)"]
+    cliInvoke["cliInvoke(program, argv)"]
+  end
+  subgraph internal [Internal only]
+    resolveCaps["resolveCapabilities(program)"]
+    presentation["presentationRoot(program)"]
+    dispatch["dispatchBuiltin(...)"]
+  end
+  CliProgram --> cliRun
+  CliProgram --> resolveCaps
+  resolveCaps --> presentation
+  resolveCaps --> dispatch
+  presentation --> help["help / schema / completions"]
+```
+
+## Export policy (intentionally narrow)
+
+### Export from [`src/index.ts`](src/index.ts) only
+
+| Symbol | Action |
+|--------|--------|
+| `CliProgram` | **Add** — primary schema type |
+| `CliCommand` | **Remove** — breaking |
+| `CliNode`, `CliLeaf`, `CliRouter` | **Do not export** — authors use `satisfies CliProgram` or `typeof program.commands[n]` |
+| `CliOption`, `CliPositional`, config types | unchanged |
+| `cliRun`, `cliInvoke`, `CliContext`, enums | unchanged signatures, `CliProgram` param |
+
+Run `just typegen` so [`index.d.ts`](index.d.ts) reflects only the barrel.
+
+### Keep internal (not in barrel, no deep `package.json` exports)
+
+- [`src/capabilities.ts`](src/capabilities.ts) (new): `resolveCapabilities`, `reservedCommandNames`
+- [`src/builtins/presentation.ts`](src/builtins/presentation.ts), [`export.ts`](src/builtins/export.ts), [`dispatch.ts`](src/builtins/dispatch.ts)
+- Completion emitters, install module, `setCompiledExecutableOverride`
+- [`src/completion.ts`](src/completion.ts) shim — trim re-exports if any leak toward public paths; tests import from `builtins/` or `completion.ts` directly in-repo only
+
+**Rule**: If it decides *when* a builtin appears, it stays internal. Consumers only see the resulting CLI behavior.
+
+## Internal capabilities module
+
+New [`src/capabilities.ts`](src/capabilities.ts):
+
+```typescript
+interface CliCapabilities {
+  completion: true;
+  mcp: boolean;      // !!program.mcpServer
+  install: boolean;  // isCompiledExecutable() && program.install?.enabled !== false
+}
+
+function resolveCapabilities(program: CliProgram): CliCapabilities
+function reservedCommandNames(caps: CliCapabilities): string[]
+```
+
+Wire callers to use this instead of re-deriving:
+
+| File | Change |
+|------|--------|
+| [`src/validate.ts`](src/validate.ts) | `cliValidateProgram(program)`; reserved names from `caps`; **keep** runtime root-only checks for untyped/JS abuse |
+| [`src/builtins/presentation.ts`](src/builtins/presentation.ts) | `presentationBuiltins(program, caps)` |
+| [`src/builtins/export.ts`](src/builtins/export.ts) | same |
+| [`src/builtins/dispatch.ts`](src/builtins/dispatch.ts) | derive `caps` once from `program` |
+| [`src/runtime.ts`](src/runtime.ts) | `cliRun(program: CliProgram)` |
+
+Walkers (`parse`, `mcp/tools`, completion scopes) take `CliNode` where they recurse; entrypoints take `CliProgram`.
+
+**Presentation vs user tree**: Help, `--schema`, and completion emitters consume `cliPresentationRoot(program)` (synthetic router with builtin stubs), not raw `CliProgram`. Capability logic decides what gets injected; emitters keep walking the same presentation shape.
+
+**Validate edge cases** (keep at runtime even when TS catches most mistakes):
+
+- `mcpServer` / `install` on inner nodes — reject (untyped/JS abuse)
+- `mcpTool` on program root (leaf-shaped `CliProgram`) — reject (same as today)
+- Reserved command names from `reservedCommandNames(caps)` — drop the old `cliPresentationRoot` escape hatch that skips injection when user already declared `completion`
+
+## Context typing
+
+[`src/context.ts`](src/context.ts):
+
+- Change `ctx.schema` type to `CliProgram` (field name unchanged — avoids extra public surface).
+- **Nice-to-have**: add `get program(): CliProgram` alias returning `this.schema` with JSDoc pointing to `schema` for familiarity. Do **not** export a new type for this.
+
+## Consumer migration (2.0)
+
+### Before/after (representative of qa-cli, idp-trees, and all `: CliCommand`-typed consumers)
+
+```typescript
+// Before (1.x)
+import { cliRun, type CliCommand, CliOptionKind, CliFallbackMode } from "argsbarg";
+const cli: CliCommand = { key: 'myapp', commands: [...], mcpServer: {...} };
+await cliRun(cli);
+
+// After (2.0)
+import { cliRun, type CliProgram, CliOptionKind, CliFallbackMode } from "argsbarg";
+const cli = { key: 'myapp', commands: [...], mcpServer: {...} } satisfies CliProgram;
+await cliRun(cli);
+```
+
+No structural change for well-formed apps — only import + type annotation. `: CliProgram` also works if the consumer prefers explicit annotation over `satisfies`. Both patterns are supported and type-check identically.
+
+### Consumer impact (verified)
+
+| Consumer | Files importing argsbarg | Uses `CliCommand`? | Uses `mcpServer`/`install`? | Migration cost |
+|---|---|---|---|---|
+| qa-cli | 3 (`index.tsx`, `mcpConfig.ts`, `mcp.ts`) | `const cli: CliCommand` | `mcpServer` on root | Replace `CliCommand` → `CliProgram` in 1 import, 1 annotation |
+| idp-trees | 3 (`index.tsx`, `mcp/config.ts`, `headless/mode.ts`) | `const cli: CliCommand` | `mcpServer` on root | Replace `CliCommand` → `CliProgram` in 1 import, 1 annotation |
+
+Both consumers only use `CliCommand` for the root schema annotation. Neither imports `CliNode`/`CliLeaf`/`CliRouter` (they can't — they don't exist yet). Neither has deeply nested command trees (max depth 2). All other imported types (`CliOptionKind`, `CliFallbackMode`, `CliMcpServerConfig`, `CliMcpToolConfig`, `CliInvocation`, `CliContext`, `isInteractiveTty`) remain unchanged — those files need zero changes.
+
+### `install` builtin default behavior
+
+Both qa-cli and idp-trees rely on the `install` builtin being **enabled by default** (they do not set `install` on the root). The capabilities resolver must preserve this: `install: isCompiledExecutable() && program.install?.enabled !== false` — which defaults to enabled when `install` is absent.
+
+## Tests and negative cases
+
+- Update fixtures in [`src/index.test.ts`](src/index.test.ts), [`src/builtins/builtins.test.ts`](src/builtins/builtins.test.ts), [`src/install/install.test.ts`](src/install/install.test.ts): `CliProgram` / `CliNode` internally.
+- Runtime rejection tests (`mcpServer` on nested node) use `as unknown as CliProgram` or a small `invalidProgram()` helper — proves validate still catches misuse without TS.
+
+## Docs and changelog
+
+- [`README.md`](README.md): `CliProgram`, capabilities mental model (1 short paragraph), reserved names derived from config.
+- [`CHANGELOG.md`](CHANGELOG.md): **2.0.0** — `CliCommand` removed; `CliProgram` added; show before/after migration snippet. Include a note that structural schema shape is unchanged — only the type name and annotation pattern differ.
+- Optional short **Architecture** note in README (not a new doc file unless you want one).
+
+### 2.0.0 migration snippet (for CHANGELOG)
+
+```typescript
+// 1.x
+import { type CliCommand } from "argsbarg";
+const cli: CliCommand = { ... };
+// 2.0
+import { type CliProgram } from "argsbarg";
+const cli = { ... } satisfies CliProgram;  // or : CliProgram
+```
+
+## Version and release
+
+**2.0.0** — rename-only breaking change for typed consumers; runtime behavior unchanged.
+
+**Release path (chosen): Option B** — jump straight to 2.0.0. No `CliCommand` deprecated alias in 1.6. Breaking changes are acceptable; known consumers (qa-cli, idp-trees) migrate in one import + one annotation each.
+
+### Pre-release checklist (required before tag)
+
+1. `just test` green in argsbarg
+2. `just typegen` — `index.d.ts` exports `CliProgram` only (no `CliCommand`)
+3. Point qa-cli and idp-trees `package.json` at local argsbarg checkout; confirm `tsc` / build passes with `CliProgram` migration applied in those repos
+4. CHANGELOG 2.0.0 entry with migration snippet
+
+---
+
+## Nice-to-haves (defer if time-boxed)
+
+1. **`satisfies CliProgram`** in all examples (better DX than `: CliProgram` annotation). Verify that `satisfies` still infers precise sub-command types (not widening to `object`), particularly in nested structures like `examples/nested.ts`.
+2. **`ctx.program` getter** — alias for `ctx.schema`; document `schema` as legacy name in JSDoc only (no removal in 2.0).
+3. **Internal rename** `cliValidateRoot` → `cliValidateProgram` (not exported today; safe).
+4. **Type tests** in `src/types.test.ts` — compile-only assertions that invalid shapes fail (e.g. `mcpServer` on `CliNode`) using `@ts-expect-error` snippets.
+5. **README diagram** — small mermaid of user tree vs injected capabilities (documentation only).
+
+## Explicitly out of scope (avoid future breaks)
+
+- Exporting `CliCapabilities`, `resolveCapabilities`, `presentationRoot`, builtin command builders
+- Exporting `CliNode` / `CliLeaf` / `CliRouter` (can add in 2.x if demand appears; not needed for `nested.ts`-style apps)
+- `package.json` subpath exports (`argsbarg/builtins`, etc.)
+- Renaming `ctx.schema` in 2.0 (would break handlers that read `.schema`)

package/.private/scratch.md

@@ -1,2 +1,2 @@
 - [x] --schema feature for ai agents
-- [ ] auto-generate/install a cursor skill  format for ~/.cursor/skills?
+- [x] opt-out install feature?

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-06-20
+
+### Changed (breaking)
+
+- **`CliCommand` removed** — use `CliProgram` as the schema type passed to `cliRun` / `cliInvoke`. The runtime object shape is unchanged; only the type name and how you annotate it differ.
+
+```typescript
+// 1.x
+import { type CliCommand } from "argsbarg";
+const cli: CliCommand = { ... };
+// 2.0
+import { type CliProgram } from "argsbarg";
+const cli = { ... } satisfies CliProgram;  // or : CliProgram
+```
+
+- **Internal type split** — `CliNode` / `CliLeaf` / `CliRouter` model the user command tree; `CliProgram` adds root-only `mcpServer` and `install`. These are not exported from the public API.
+- **Capabilities resolver** — reserved built-in names (`completion`, `install`, `mcp`) are derived from program config and runtime (compiled binary), not from user-declared commands.
+
+### Added
+
+- **`ctx.program`** — alias for `ctx.schema` on `CliContext` (same `CliProgram` value).
+
+## [1.5.0] - 2026-06-20
+
+### Added
+
+- **`install` built-in** (compiled binaries only) — install binary, bash/zsh/fish completions, Cursor/Claude skills, and MCP config (`install --all --yes`, `--update`, `--status`, `--uninstall`).
+- **`completion fish`** — fish tab-completion script generation.
+- Root **`install`** config (`{ enabled?: boolean, prefix?: string }`).
+
+### Changed (breaking)
+
+- **Removed `ai` command group** — no more `ai mcp` or `ai skill`.
+- **Restored top-level `mcp`** — `myapp mcp` (reserved only when `mcpServer` is set).
+- **Removed `aiSkill` config** — skill directory name defaults to sanitized root `key`; use `install --skill` instead of `ai skill`.
+
 ## [1.4.3] - 2026-06-19
 
 ### Added
@@ -135,7 +171,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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/v1.4.3...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v2.0.0
+[1.5.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.5.0
 [1.4.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.3
 [1.4.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.2
 [1.4.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.1

package/README.md

@@ -14,9 +14,9 @@ Why another CLI parser?
 
 *Beautiful `-h` screens* — scoped help at any routing depth, rendered in rounded UTF-8 boxes with tables, terminal-width wrapping, and color when stdout is a TTY. Errors print in red with contextual help on stderr.
 
-*Shell completions* — `completion bash` and `completion zsh` built-ins generate installable scripts from your schema so users get tab completion for commands, flags, and positionals without extra tooling.
+*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 ai mcp` over stdio). See [docs/mcp.md](docs/mcp.md). Install Cursor/Claude skills with `myapp ai skill cursor|claude` — see [docs/ai-skills.md](docs/ai-skills.md).
+*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).
 
 *Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
@@ -35,9 +35,9 @@ Shell completions! -->
 ## Usage
 
 ```typescript
-import { cliRun, CliCommand, CliOptionKind } from "argsbarg";
+import { cliRun, type CliProgram, CliOptionKind } from "argsbarg";
 
-const cli: CliCommand = {
+const cli = {
   key: "helloapp",
   description: "Tiny demo.",
   positionals: [
@@ -64,7 +64,7 @@ const cli: CliCommand = {
     }
     console.log(`hello ${name}`);
   },
-};
+} satisfies CliProgram;
 
 await cliRun(cli);
 ```
@@ -77,7 +77,7 @@ await cliRun(cli);
 
 Everything you need for a first-class CLI:
 
-- **Nested subcommands** (`CliCommand` with `commands` for groups, `handler` for leaves)
+- **Nested subcommands** (router nodes with `commands`, leaf nodes with `handler`)
 - **POSIX-style options** (`-x`, `--long`, `--long=value`) — kinds: presence, string, number, **enum** (`choices` array)
 - **Bundled presence flags** (`-abc`)
 - **Positional arguments and varargs tails** (`CliPositional` objects on `positionals`)
@@ -95,30 +95,32 @@ 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`** — print shell completion scripts to stdout (injected by `cliRun`).
-- **`ai`** — AI agent integration: `ai mcp` (when `mcpServer` is set), `ai skill cursor`, `ai skill claude` (install agent skills; opt out with `aiSkill: { enabled: false }`).
+- **`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`).
+- **`install`** — when running as a compiled binary (`bun build --compile`), 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`** — it is reserved for this built-in.
-Do not declare a top-level command named **`ai`** — it is reserved for this built-in.
+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 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 ai 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: {}` (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.
 
 See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details.
 
-### Agent skills
+### Install (compiled binaries)
 
-Install Cursor or Claude Code skills (command catalog + schema reference) with:
+After `bun build --compile`, ship a self-contained binary and let users run:
 
 ```bash
-myapp ai skill cursor          # .cursor/skills/<name>/
-myapp ai skill claude --global # ~/.claude/skills/<name>/
+myapp install --all --yes
 ```
 
-See **[docs/ai-skills.md](docs/ai-skills.md)** for opt-out, flags, and file layout.
+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.
 
 
 ### Shell completions
@@ -130,6 +132,8 @@ myapp completion bash > ~/.bash_completion.d/myapp
 myapp completion zsh > ~/.zsh/completions/_myapp   
 # then: fpath+=(~/.zsh/completions); autoload -Uz compinit && compinit
 # or, for a one-off test in the current shell: eval "$(myapp completion zsh)"
+
+myapp completion fish > ~/.config/fish/completions/myapp.fish
 ```
 
 
@@ -143,7 +147,7 @@ bun add bun-argsbarg
 
 ## How it works
 
-1. Build a **program root** `CliCommand` using pure TypeScript objects: `key` is the app/binary name, `commands` are top-level subcommands, `options` are global flags. The root must not set `handler` or declare `positionals` (validated at startup). Use `fallbackCommand` / `fallbackMode` on any **routing node** for default subcommand routing (not root-only).
+1. Build a **program root** with `satisfies CliProgram` (or `: CliProgram`): `key` is the app/binary name, `commands` are top-level subcommands, `options` are global flags. A router root must not set `handler` or declare `positionals` (validated at startup). A leaf root may set `handler` and `positionals` directly. Use `fallbackCommand` / `fallbackMode` on any **routing node** for default subcommand routing (not root-only).
 2. Call `await cliRun(root)` with that root — validates, parses argv, renders help or errors, invokes the leaf handler, and `process.exit`s with status **0** on success, **1** on implicit help or error (explicit `--help` → **0**).
 3. From a handler, `cliErrWithHelp(ctx, "message")` prints a red error line plus contextual help on stderr and exits **1**.
 
@@ -177,7 +181,11 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `ctx.typedOpt<T>("custom", parseFn)` — pass a custom parsing function for type-safe option resolution.
 - `ctx.args` — positional words in order as `string[]`.
 - `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.
-- `ctx.schema` — merged program root (`CliCommand`) for contextual help.
+- `ctx.schema` / `ctx.program` — program root (`CliProgram`) for contextual help.
+
+### Capabilities (built-ins)
+
+`completion`, `install`, and `mcp` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, compiled binary + `install`). Reserved command names follow from that config: `completion` and `install` are always reserved; `mcp` is reserved when `mcpServer` is set.
 
 
 
@@ -188,7 +196,7 @@ Check the `examples/` directory for full working scripts:
 | Example | File | Shows |
 | --- | --- | --- |
 | `ArgsBargMinimal` | `examples/minimal.ts` | String + presence flags, `MissingOrUnknown` fallback. |
-| `ArgsBargNested` | `examples/nested.ts` | Nested `CliCommand` tree, positional tails, async handlers. |
+| `ArgsBargNested` | `examples/nested.ts` | Nested command tree, positional tails, async handlers. |
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -210,7 +218,7 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 
 | Symbol | Role |
 | --- | --- |
-| `CliCommand`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
+| `CliProgram`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
 | `CliOptionKind`, `CliFallbackMode` | Option kinds (`Presence`, `String`, `Number`, `Enum`) and root fallback behavior. |
 | `CliSchemaValidationError` | Thrown when the static command tree violates schema rules. |
 | `CliContext` | Handler context (`ctx.flag`, `ctx.stringOpt`, `ctx.args`, `ctx.invocation`, …). |
@@ -218,7 +226,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 identifier (validated at startup): root command **`completion`**.
+Reserved identifiers (validated at startup): root commands **`completion`**, **`install`**, and **`mcp`** (only when `mcpServer` is set).
 
 ---
 

package/docs/ai-skills.md

@@ -1,75 +1,47 @@
-# Agent skills install
+# Agent skills
 
-ArgsBarg can install [Agent Skills](https://code.claude.com/docs/en/skills) content for **Cursor** and **Claude Code** from your CLI schema. Each install writes two files:
+ArgsBarg can generate Cursor and Claude Code skill directories (`SKILL.md` + `reference.md`) from your CLI schema.
 
-| File | Purpose |
-| --- | --- |
-| `SKILL.md` | Frontmatter + command catalog, execution notes, pitfalls |
-| `reference.md` | Full `--schema` JSON export |
-
-Skills are **install-only** — there is no print-to-stdout mode, because the artifact is always a two-file directory.
+## Install via `install` (recommended)
 
-## Quick start
+In a **compiled binary**, install skills to the user environment:
 
 ```bash
-# Project skill (commit .cursor/skills/ with your repo)
-myapp ai skill cursor
-
-# User-wide Claude Code skill
-myapp ai skill claude --global
+myapp install --skill --yes
+# or
+myapp install --all --yes
 ```
 
-On success, one line is printed to **stderr** with the install path (not the skill body).
+Skills are written when the agent home exists:
 
-## Opt-out
+- Cursor: `~/.cursor/skills/<dir>/` when `~/.cursor` exists
+- Claude Code: `~/.claude/skills/<dir>/` when `~/.claude` exists
 
-Skill install is **enabled by default**. Opt out on the program root:
+The skill directory name defaults to the sanitized program `key` (e.g. `minimal.ts` → `minimal_ts`).
 
-```typescript
-const cli: CliCommand = {
-  key: "myapp",
-  description: "My app.",
-  aiSkill: { enabled: false },
-  commands: [/* ... */],
-};
-```
+Existing skill directories are removed and rewritten on each install.
 
-Optional custom skill directory name:
+## Programmatic install
 
 ```typescript
-aiSkill: { name: "my-custom-skill" },
+import { cliSkillInstall } from "argsbarg/skill/install"; // internal module
 ```
 
-## Flags
+For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true, rimraf: true })` — it returns changed file paths.
 
-Available on `ai skill cursor` and `ai skill claude`:
+## Generated content
 
-| Flag | Effect |
-| --- | --- |
-| `--global` | Install under the user skills directory instead of the project |
-| `--force` | Overwrite an existing skill directory |
-
-## Install locations
-
-| Target | Project (default) | `--global` |
-| --- | --- | --- |
-| Cursor | `.cursor/skills/<name>/` | `~/.cursor/skills/<name>/` |
-| Claude Code | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` |
-
-`<name>` defaults to the sanitized program root `key` (same rules as MCP tool name segments).
-
-Do **not** install under `~/.cursor/skills-cursor/` — that path is reserved for Cursor built-ins.
+- **`SKILL.md`** — YAML frontmatter, when-to-use guidance, command catalog, MCP setup hints
+- **`reference.md`** — full `--schema` JSON export
 
 ## MCP vs skills
 
-| Mechanism | Purpose |
+| Mechanism | Role |
 | --- | --- |
-| **`myapp ai mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`myapp ai skill cursor\|claude`** | Static discovery and conventions for agents |
-
-Generated `SKILL.md` recommends MCP when `mcpServer` is configured, and documents shell invocation as a fallback.
+| **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
+| **`myapp install --skill`** | Static discovery files for agents |
 
-## Related
+See also:
 
-- [MCP server](mcp.md) — `mcpServer` config and `ai mcp` protocol
-- [README built-ins](../README.md#built-ins) — reserved command `ai`
+- [MCP server](mcp.md) — `mcpServer` config and `mcp` protocol
+- [Install](install.md) — binary, completions, skills, and MCP config

package/docs/install.md

@@ -0,0 +1,84 @@
+# Install command
+
+The `install` built-in is available only in **compiled binaries** (`bun build --compile`). It is hidden from help, `--schema`, and shell completions when running via `bun run`.
+
+## Quick start
+
+```bash
+# First-time setup
+myapp install --all --yes
+
+# Refresh after upgrading
+myapp install --update
+
+# See what is installed
+myapp install --status
+
+# Remove everything detected
+myapp install --uninstall --yes
+```
+
+## What gets installed
+
+| Target | Flag | Destination |
+| --- | --- | --- |
+| Binary | `--bin` | `~/.local/bin/<key>` (or `--prefix`) |
+| Bash completion | `--completions` | `~/.bash_completion.d/<key>` + `.bashrc` PATH snippet |
+| Zsh completion | `--completions` | `~/.zsh/completions/_<key>` + `.zshrc` fpath snippet |
+| Fish completion | `--completions` | `~/.config/fish/completions/<key>.fish` |
+| Cursor skill | `--skill` | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
+| 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).
+
+Shells not on PATH are skipped silently (no warnings).
+
+## Configuration
+
+On the program root:
+
+```typescript
+install: {
+  enabled: false,       // opt out of the install built-in
+  prefix: "~/.local/bin", // default bin directory
+}
+```
+
+Environment:
+
+- `INSTALL_PREFIX` — same as `install.prefix` / `--prefix`
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `--yes` | Skip confirmation (required for non-TTY unless `--json` / `--update`) |
+| `--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`) |
+| `--status` | Read-only inventory |
+| `--uninstall` | Remove detected artifacts (scope with `--bin`, `--completions`, `--skill`, `--mcp`) |
+
+## MCP merge behavior
+
+When `--mcp` runs, entries are merged into `mcpServers[<name>]` with:
+
+```json
+{ "command": "<root.key>", "args": ["mcp"] }
+```
+
+If an existing entry differs, the command exits with an error unless `--yes` is passed (then it overwrites).
+
+## Opt out
+
+```typescript
+const cli = {
+  key: "myapp",
+  description: "...",
+  install: { enabled: false },
+  // ...
+} satisfies CliProgram;
+```