argsbarg 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-06-21
+
+
+## [3.3.0] - 2026-06-20
+
+### Added
+
+- **Headless helpers** — `shouldRunHeadless`, `shouldRunHeadlessWithPositionals`, `shouldRunHeadlessWithYes`, `wantsDryRun`, `wantsExplicitJson`, `requireYesInNonTty`, `formatDryRunMessage` for Ink/MCP CLIs.
+- **`ghReleaseUpdateGetLatest`** — optional `install.updateGetLatest` factory for GitHub releases via `gh`.
+- **`createGhVersionCheck`** — version-check cache, update notices, and background refresh helpers.
+
+## [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 +234,10 @@ 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.3.0...HEAD
+[3.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.0
+[3.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.0
+[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).").
 
@@ -54,7 +57,15 @@ 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.
+Inline topics in your program root when the set is small; use a separate module only if the import map grows enough to clutter `index.tsx`.
+
+## 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`)
 
@@ -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,50 @@ 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`).
+
+### GitHub releases (`ghReleaseUpdateGetLatest`)
+
+For compiled binaries published via `gh release`, wire a hook without hand-rolling download logic:
+
+```typescript
+import {
+  createGhFetchLatest,
+  createGhVersionCheck,
+  ghReleaseUpdateGetLatest,
+} from "argsbarg";
+
+const cachePath = path.join(configDir, "version-check.json");
+
+install: {
+  updateGetLatest: ghReleaseUpdateGetLatest({
+    repo: "owner/repo",
+    asset: "myapp",
+    tempPrefix: "myapp-update.",
+    cachePath,
+  }),
 }
+
+// Optional: summary notice + background refresh
+const versionCheck = createGhVersionCheck({
+  currentVersion: "1.0.0",
+  commandName: "myapp",
+  cachePath,
+  fetchLatest: createGhFetchLatest({ repo: "owner/repo" }),
+});
+versionCheck.getUpdateNotice();
+versionCheck.refreshIfStale();
 ```
 
+Requires `gh` on PATH and `gh auth login`. Consumers keep app-specific config only (~15 lines).
+
 Environment:
 
 - `INSTALL_PREFIX` — same as `install.prefix` / `--prefix`
@@ -53,15 +97,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

@@ -21,6 +21,9 @@ const cli = {
       readme: { text: "# nested.ts\n\nNested groups demo.\n" },
     },
   },
+  install: {
+    updateGetLatest: async () => ({ path: process.execPath, version: pkg.version }),
+  },
   commands: [
     {
       key: "stat",

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. */
@@ -288,5 +305,80 @@ export declare function cliRun(program: CliProgram, argv?: string[]): Promise<ne
 export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 /** True when stdin is a TTY. */
 export declare const isInteractiveTty: boolean;
+/** Minimal context for headless routing helpers. */
+export type HeadlessContext = Pick<CliContext, "invocation">;
+/** True when `--dry-run` was passed. */
+export declare function wantsDryRun(hasDryRunFlag: boolean): boolean;
+/** True when `--json` was passed or the handler was invoked via MCP. */
+export declare function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean;
+/**
+ * Headless when MCP, `--json`, `--dry-run`, or stdin is not a TTY.
+ * Use for commands that should auto-emit JSON in pipelines.
+ */
+export declare function shouldRunHeadless(ctx: HeadlessContext, hasJsonFlag: boolean, hasDryRunFlag?: boolean, interactive?: boolean): boolean;
+/**
+ * Like {@link shouldRunHeadless}, but only auto-headless in non-TTY when positionals are present.
+ * Avoids turning empty invocations into JSON errors.
+ */
+export declare function shouldRunHeadlessWithPositionals(ctx: HeadlessContext, hasJsonFlag: boolean, positionals: string[], hasDryRunFlag?: boolean, interactive?: boolean): boolean;
+/**
+ * Headless when MCP, `--dry-run` with required args, or non-TTY with `--yes` and required args.
+ * Use for mutating commands that require explicit `--yes` in scripts.
+ */
+export declare function shouldRunHeadlessWithYes(ctx: HeadlessContext, opts: {
+	yes: boolean;
+	hasRequiredArgs: boolean;
+	dryRun?: boolean;
+}, interactive?: boolean): boolean;
+/**
+ * Exits when non-interactive mode is used without `--yes`.
+ * @param hint - Command-specific guidance appended to the error
+ */
+export declare function requireYesInNonTty(yes: boolean, hint: string, dryRun?: boolean, interactive?: boolean): void;
+/** Prefixes a success message when running in dry-run mode. */
+export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
+/** Config for {@link ghReleaseUpdateGetLatest}. */
+export interface GhReleaseUpdateConfig {
+	/** GitHub `owner/repo` slug. */
+	repo: string;
+	/** Release asset filename (e.g. `myapp`). */
+	asset: string;
+	/** Temp directory name prefix for downloads. */
+	tempPrefix: string;
+	/** Path to the on-disk version-check cache JSON file. */
+	cachePath: string;
+	/** Optional hint when `gh auth` fails or no releases exist. */
+	repoEnvHint?: string;
+}
+/** Config for {@link createGhVersionCheck}. */
+export interface GhVersionCheckConfig {
+	/** Installed semver string. */
+	currentVersion: string;
+	/** CLI command name for update notices (e.g. `qa`). */
+	commandName: string;
+	/** Path to the on-disk version-check cache JSON file. */
+	cachePath: string;
+	/** Cache TTL in milliseconds (default 24h). */
+	ttlMs?: number;
+	/** When true, skip background refresh (e.g. test subprocess). */
+	skipRefresh?: () => boolean;
+	/** When true, skip refresh because `gh` is unavailable. */
+	ghAvailable?: () => boolean;
+	/** Fetches latest release version via `gh`. */
+	fetchLatest: () => Promise<string>;
+}
+/** Returns whether the installed version matches the latest release. */
+export declare function isAlreadyCurrent(current: string, latest: string): boolean;
+/** Strips a leading `v` from a release tag. */
+export declare function parseReleaseTag(tag: string): string;
+/** Builds a `CliUpdateGetLatest` hook that downloads a release via `gh`. */
+export declare function ghReleaseUpdateGetLatest(config: GhReleaseUpdateConfig): CliUpdateGetLatest;
+/** Version-check cache helpers for summary notices and background refresh. */
+export declare function createGhVersionCheck(config: GhVersionCheckConfig): {
+	getUpdateNotice: () => string | null;
+	refreshIfStale: () => void;
+};
+/** Shared `gh release view` fetcher for hooks and version-check refresh. */
+export declare function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string>;
 
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/plan.md

@@ -1,194 +1,19 @@
 # bun-argsbarg Plan
 
-## Plan: bun-argsbarg — Bun CLI Argument Parser
-
-**TL;DR**: Convert the Swift `argsbarg` declarative CLI framework into a TypeScript/Bun library with the same CLI features (schema-driven parsing, help rendering, shell completion, subcommand routing, fallback commands) while leveraging TypeScript's type system for compile-time schema safety.
-
 ## Current Status
 
-**Overall**: Phases 1–5 (95%) complete; Phases 6–8 in progress.
-
-### ✅ Completed
-
-- **Phase 1**: Core Schema Types (`src/types.ts`)
-  - `CliOptionKind` enum (Presence, String, Number)
-  - `CliFallbackMode` enum (MissingOnly, MissingOrUnknown, UnknownOnly)
-  - `CliCommand`, `CliOption`, `CliPositional`, `CliHandler`, `CliContext` interfaces
-  - `CliSchemaValidationError` class
-  - `CliOption` on `options`, `CliPositional` on `positionals`, nested routes under `commands`
-
-- **Phase 2**: Argument Parser (`src/parse.ts`)
-  - `parse(root, argv)` with long/short options, bundling, equals syntax
-  - Option consumption logic with strict number validation
-  - Subcommand routing and positional argument collection
-  - Help token detection (`-h`, `--help`)
-  - `postParseValidate()` for strict option validation
-  - `cliValidateRoot()` for schema validation (root rules, child uniqueness, reserved names, positional ordering)
-  - Support for all fallback modes
-
-- **Phase 3**: Runtime Context (`src/context.ts`)
-  - `CliContext` class with typed accessors
-  - `flag(name)` — boolean presence check
-  - `stringOpt(name)` — string value or undefined
-  - `numberOpt(name)` — strict double parsing or null
-  - `typedOpt<T>(name, parse)` — generic typed accessor (TypeScript advantage)
-
-- **Phase 4**: Help Rendering (`src/help.ts`)
-  - `cliHelpRender()` for formatted help output
-  - TTY-aware ANSI colors (red, aqua, gray, bold)
-  - Unicode box drawing (╭╮├┤╰╯)
-  - Terminal width detection (`process.stdout.columns`)
-  - Text wrapping with visible width calculation (strips ANSI)
-  - Help sections: usage box, options table, positionals table, subcommands table, notes box
-  - `cliOptionLabel()` for formatted option display
-
-- **Phase 5**: Shell Completion (`src/completion.ts`)
-  - `completionBashScript(schema)` — bash tab-completion generator
-  - `completionZshScript(schema)` — zsh tab-completion generator
-  - Scope walking for command tree traversal
-  - Option/command/positional matching logic for both shells
-
-### 🚧 In Progress
-
-- **Phase 6**: Main Entry Point (`src/index.ts`)
-  - **Status**: Placeholder `hello()` function remains
-  - **Needs**: Implement `cliRun(root: CliCommand): Promise<void>`
-    - Validate schema via `cliValidateRoot()`
-    - Auto-merge built-in `completion` command with `bash`/`zsh` subcommands
-    - Call `parse()` on `process.argv.slice(2)`
-    - Call `postParseValidate()`
-    - Handle `ParseKind.Help` → render via `cliHelpRender()` → exit(0)
-    - Handle `ParseKind.Error` → render red error + contextual help → exit(1)
-    - Route to handler function with `CliContext`
-    - Support async handlers with `await`
-
-- **Phase 7**: Examples & Tests (`src/index.test.ts`, `examples/`)
-  - **Status**: Only placeholder tests exist
-  - **Needs**: 
-    - Replace `src/index.test.ts` with comprehensive test suite covering:
-      - Option parsing (long, short, bundled, equals syntax)
-      - Help detection and rendering
-      - Subcommand routing and fallback modes
-      - Positional argument collection and arity validation
-      - Unknown options/commands
-      - Schema validation errors
-      - Async handler support
-      - Typed option accessors
-    - Create `examples/minimal.ts` — hello with `--name` and `--verbose`
-    - Create `examples/nested.ts` — nested subcommands with positionals (mirroring Swift examples)
-
-### ❌ Not Started
-
-- **Phase 8**: Project Polish
-  - Add `biome.json` for linting/formatting
-  - Add CLI binary entry point (`bin/argsbarg`)
-  - Create `README.md` with API docs and usage examples
-  - Update `package.json` scripts and bin entry
-  - Verify all verification steps pass
-
-## Next Immediate Steps
-
-1. Implement `cliRun()` in `src/index.ts`
-2. Rewrite `src/index.test.ts` with actual test coverage
-3. Create working examples in `examples/`
-4. Run `bun test` and verify all tests pass
-5. Run examples and verify output matches expectations
-
-**Steps**
-
-### Phase 1: Core Schema Types (types.ts)
-- Define TypeScript equivalents of Swift's `CliOptionKind`, `CliOption`, `CliCommand`, `CliFallbackMode`
-- Leverage TypeScript generics/union types for compile-time safety (e.g., typed option values instead of string-only)
-- Add `CliHandler` type as `(ctx: CliContext) => void | Promise<void>` (support async handlers)
-- Add `CliSchemaValidationError` enum/class
-- **Parallel with Phase 2**
-
-### Phase 2: Argument Parser (parse.ts)
-- Implement `parse(root: CliCommand, argv: string[]): ParseResult` — same logic as Swift
-  - Long options (`--name`, `--name=value`)
-  - Short options (`-n`, bundled `-abc`)
-  - Subcommand routing through nested `CliCommand` tree
-  - Positional argument collection with arity validation (argMin/argMax)
-  - Help token detection (`-h`/`--help`)
-  - Root-level `fallbackCommand`/`fallbackMode` support
-- Implement `postParseValidate()` — strict number validation, option key verification
-- Implement `cliValidateRoot()` — schema validation (no handler on routing nodes, no positionals on root, unique short names, reserved `-h`, etc.)
-- **Depends on Phase 1**
-
-### Phase 3: Context & Runtime (context.ts)
-- Implement `CliContext` class with typed accessors:
-  - `flag(name)` — boolean presence check
-  - `stringOpt(name)` — string value
-  - `numberOpt(name)` — strict double parse
-  - **TypeScript enhancement**: `typedOpt<T>(name, parseFn)` — generic typed accessor
-- Implement `cliErrWithHelp(ctx, msg)` — red error + contextual help on stderr
-- **Depends on Phase 1**
-
-### Phase 4: Help Rendering (help.ts)
-- Terminal-aware help with rounded box drawing (same Unicode box chars as Swift)
-- TTY detection (Node's `process.stdout.isTTY` instead of Swift's `isatty`)
-- Terminal width detection (`TIOCGWINSZ` via `ioctl` or fallback to `process.stdout.columns`)
-- ANSI color support (TTY-aware, same palette: red/green/aqua/gray/bold)
-- Help sections: Usage box, Options table, Arguments table, Subcommands table, Notes box
-- `cliHelpRender(schema, helpPath, useStderr)` — full help for root or nested command
-- **Depends on Phase 1**
-
-### Phase 5: Shell Completion (completion.ts)
-- `completionBashScript(schema)` — generate bash tab-completion script
-- `completionZshScript(schema)` — generate zsh tab-completion script
-- Same scope-walking algorithm as Swift (depth-first, per-node arrays)
-- **Depends on Phase 1**
-
-### Phase 6: Main Entry Point (index.ts)
-- `cliRun(root: CliCommand)` — orchestrates: validate → merge builtins → parse → validate → dispatch
-- Auto-merge `completion`/`bash`/`zsh` reserved commands
-- Exit code handling (0 for help/success, 1 for errors)
-- **Depends on Phases 2-5**
-
-### Phase 7: Examples & Tests
-- `examples/minimal.ts` — hello world with options (like Swift's Minimal example)
-- `examples/nested.ts` — deeply nested subcommands with positionals (like Swift's Nested example)
-- `src/index.test.ts` — comprehensive tests mirroring Swift's ParseTests
-  - Bundled short flags, long option equals, fallback modes
-  - Unknown command, implicit help, invalid number validation
-  - Completion script generation verification
-  - Schema validation (root handler, root positionals, nested fallback, reserved names)
-  - **TypeScript-specific**: async handler support, typed option accessors
+**Overall**: Core CLI, MCP, install, docs, and update built-ins are complete. Public API is stable at **3.x**.
 
-### Phase 8: Project Polish
-- Add `biome.json` config (lint/format)
-- Add `bin/` entry in `package.json` for CLI executable
-- Add `README.md` with API docs and usage examples
-- Update `package.json` scripts
-- **Parallel with Phase 7**
+### Shipped
 
-**Relevant files**
-- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/src/index.ts` — replace placeholder `hello()` with `cliRun` + schema types
-- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/src/index.test.ts` — replace with comprehensive test suite
-- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/package.json` — add bin entry, biome config, README
-- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/tsconfig.json` — keep as-is (already correct for Bun)
-- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/examples/local-check.ts` — replace with minimal/nested examples
+- Schema-driven parsing, help, completions, subcommand routing, fallback commands
+- MCP server (`mcpServer: { enabled: true }`), `ctx.invocation`, `cliInvoke`
+- `install` / `update` built-ins, agent skills, bundled `docs` (topics, schema, api, skill, mcp)
+- Headless helpers and `ghReleaseUpdateGetLatest` for GitHub release consumers
 
-**Verification**
-1. `bun test` — all tests pass
-2. `bun ./examples/minimal.ts hello --name World --verbose` — outputs "hello World" with verbose mode
-3. `bun ./examples/minimal.ts hello --help` — shows formatted help with options table
-4. `bun ./examples/nested.ts stat owner lookup --user-name bob /etc/passwd` — outputs "lookup user=bob path=/etc/passwd"
-5. `bun ./examples/minimal.ts completion bash` — outputs valid bash completion script
-6. `bun ./examples/minimal.ts completion zsh` — outputs valid zsh completion script
-7. `bun lint` and `bun check-types` — no errors
-8. `bun ./examples/minimal.ts unknown-cmd` — shows fallback command help with red error
+### Consumers
 
-**Decisions**
-- **Single-file vs multi-file**: Multi-file (types/parse/context/help/completion) to match Swift's modular structure and keep files manageable
-- **Typed options**: Add `typedOpt<T>(name, parse: (s: string) => T)` to leverage TypeScript's type system — this is the key TypeScript advantage over Swift's string-only approach
-- **Async handlers**: Support `async (ctx) => Promise<void>` handlers — Bun/Node advantage over Swift's synchronous-only
-- **TTY detection**: Use `process.stdout.isTTY` and `process.stdout.columns` (Node built-in) instead of `ioctl`/`isatty` FFI
-- **No runtime dependencies**: Keep zero runtime deps, only `@types/bun` as dev dep
-- **CLI binary**: Add `bin/argsbarg` entry point so the library can also be used as a CLI tool
-- **Schema validation**: Same rules as Swift — root can't have handler/positionals, no duplicate shorts, `-h` reserved, etc.
+- **qa-cli** — argsbarg program with Ink UI; commands under `src/commands/`
+- **idp-trees** — argsbarg program with headless JSON ops; `cli/dispatch.ts` pattern
 
-**Further Considerations**
-1. Should we add a `@argsbarg()` decorator pattern for declarative schema definition (like Python's argparse decorators)? This would be a TypeScript-native enhancement.
-2. Should the CLI binary (`bin/argsbarg`) support loading schema from a config file (JSON/YAML) for dynamic CLIs?
-3. Error exit codes: Swift uses exit(1) for help (implicit) and exit(0) for explicit help. Should we match this or use more conventional exit codes?
+See [README.md](README.md) and [CHANGELOG.md](CHANGELOG.md) for release history.