argsbarg 4.1.0 → 4.1.1

package/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.1.1] - 2026-07-03
+
+### Added
+
+- **`argsbarg create`** — interactive bootstrap from `examples/full-example`; copies template with substitutions; post-create runs `bun install`, schemagen, Cursor rule merge, `bun test`, and git init when appropriate.
+
+### Changed
+
+- **Breaking: `bunx argsbarg scaffold homebrew` → `bunx argsbarg create`** — single template in `examples/full-example/`; removed `docs/templates/homebrew/`.
+- **`examples/full-example/`** — `src/index.ts`, per-command modules, Biome, `.cursor/rules/` (`cli-program.mdc`, `code.mdc`).
+
+### Removed
+
+- **`argsbarg scaffold`** subcommands and **`docs/templates/homebrew/`**.
+
+### Added
+
+- **`CliAppConfigEntry.resolve`** — optional per-key fallback resolver after file (e.g. `gh auth token`); return `undefined` to fall back to `entry.env` and defaults. Resolution order: env → file → `resolve` → env → default.
+- **Install `--mcp` / `--skill` / `--configure` combined** — scoped flags compose (configure no longer blocks skill/MCP plan); configure wizard runs after install when combined.
+- **Top-level `uninstall` command** — sibling of `install` for removing agent artifacts; bare `uninstall` defaults to `--all`.
+- **Homebrew-first distribution** — tap-from-repo formula pattern; [docs/distribution-homebrew.md](docs/distribution-homebrew.md).
+- **Homebrew dev just recipes** — `install-local`, `reinstall-local`, `install-production` (+ `install` / `reinstall` aliases); `uninstall`, `uninstall-config`, `uninstall-release`, `uninstall-release-tap`, `test-release` in full-example template.
+- **CLI bin split** — `argsbarg` package bin points to `src/cli-tool/main.ts`; library API remains `import from "argsbarg"`.
+- **Config path exports** — `resolveAppConfigPath`, `displayAppConfigPath` exported from `argsbarg`.
+- **`--reinstall` greenfield fallback** — when no artifacts detected, `--reinstall` runs full `--all` plan (fresh `brew install` post_install).
+
+### Changed
+
+- **`mcpServer.shellEnv` default on** — login-shell env is captured at MCP startup unless `shellEnv: false`. PATH is merged; other vars fill gaps in host env.
+- **`CliAppConfigEntry.resolve` must be synchronous** — returning a Promise is ignored with a stderr warning; use `Bun.spawnSync` with piped stdout for subprocess resolvers (e.g. `gh auth token`).
+
+- **Breaking: `examples/consumer-app/` → `examples/full-example/`** — expanded justfile (dev/build/test/schemagen + Homebrew); CLI key `full-example`; removed redundant `examples/config-app/`.
+
+- **Breaking: `install --uninstall` removed** — use `<key> uninstall` instead (`install --uninstall` exits with a redirect message).
+- **Breaking: Homebrew-only install model** — drop self-install to `~/.local/bin`, `install --app`, `install --update` / `updateGetLatest`, home-dir completion installer (`install --completions`), bare-argv install bootstrap.
+- **Breaking: configure opt-in** — `configure` target excluded from `--all`; no post-install wizard; run `install --configure` explicitly.
+- **Install `--all` / `--reinstall`** — skills and MCP only (binary + completions via Homebrew formula).
+- **Completion built-in notes** — Homebrew installs completions; link to Shell-Completion docs.
+
+### Removed
+
+- **`examples/config-app/`** — superseded by `full-example` (`program.appConfig`, schemagen, and `config get`/`set` covered there).
+- **`install --update`**, **`updateGetLatest`**, **`ghReleaseUpdateGetLatest`** usage in install flow.
+- **Completion installer** — `install/targets/completions.ts`, home-dir completion paths.
+- **Install bootstrap** — bare argv no longer rewrites to `install`.
+
 ## [4.1.0] - 2026-07-01
 
 ### Added
@@ -497,7 +543,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/v4.1.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v4.1.1...HEAD
+[4.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.1.1
 [4.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.1.0
 [4.0.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.4
 [4.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.3

package/README.md

@@ -1,36 +1,36 @@
-![Logo](https://github.com/bdombro/bun-argsbarg/blob/main/logo.png)
-<!-- Big money NE - https://patorjk.com/software/taag/#p=testall&f=Bulbhead&t=shebangsy&x=none&v=4&h=4&w=80&we=false> -->
+Logo
 
-[![GitHub](https://img.shields.io/badge/GitHub-bdombro%2Fbun--argsbarg-181717?logo=github)](https://github.com/bdombro/bun-argsbarg)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![npm version](https://img.shields.io/npm/v/argsbarg.svg)](https://www.npmjs.com/package/argsbarg)
-[![Bun](https://img.shields.io/badge/Bun-%23000000.svg?logo=bun&logoColor=white)](https://bun.sh)
+
+
+[GitHub](https://github.com/bdombro/bun-argsbarg)
+[License: MIT](LICENSE)
+[npm version](https://www.npmjs.com/package/argsbarg)
+[Bun](https://bun.sh)
 
 Build beautiful, well-behaved CLI+MCP apps with Bun — **no third-party runtime dependencies**. 
 
 Why another CLI parser?
 
-*Schema-first* — define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface centralized, clear, and self-describing upfront.
+*Schema-first* — define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface auto-validated, centralized, clear, and self-describing upfront.
 
-*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.
+*AI Friendly* — Generate and install rich skills, mcp server, docs based on the schema.
 
-*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.
+*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.
 
-*Optional MCP server* — set `mcpServer: { enabled: true }` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp mcp` over stdio). See [docs/mcp.md](docs/mcp.md). Compiled apps can install the app, completions, skills, and MCP config with `myapp install` — see [docs/install.md](docs/install.md).
+*Shell completions* — `completion bash`, `completion zsh`, and `completion fish` built-ins generate scripts consumed by Homebrew during formula `install` (`generate_completions_from_executable`). See [docs/distribution-homebrew.md](docs/distribution-homebrew.md).
 
 *Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
 Also checkout ArgsBarg for [cpp](https://github.com/bdombro/cpp-argsbarg), [nim](https://github.com/bdombro/nim-argsbarg), and [swift](https://github.com/bdombro/swift-argsbarg)!
 
 Halps! -->
-![help-preview.png](https://github.com/bdombro/bun-argsbarg/blob/main/docs/help-preview.png)
+help-preview.png
 
 Sub-level Halps! -->
-![help-l2-preview.png](https://github.com/bdombro/bun-argsbarg/blob/main/docs/help-l2-preview.png)
+help-l2-preview.png
 
 Shell completions! -->
-![completions-preview.png](https://github.com/bdombro/bun-argsbarg/blob/main/docs/completions-preview.png)
-
+completions-preview.png
 
 ## Usage
 
@@ -73,8 +73,6 @@ await cli.run();
 
 `Cli.run()` parses `process.argv`, prints help or errors, dispatches the leaf handler, and **exits the process**.
 
-
-
 ## What is it?
 
 Everything you need for a first-class CLI:
@@ -96,50 +94,45 @@ Everything you need for a first-class CLI:
 Every app gets:
 
 - `-h` / `--help` at any routing depth (scoped help).
-- **`completion bash` / `completion zsh` / `completion fish`** — print shell completion scripts to stdout (injected by `Cli.run()`).
-- **`version`** — print `CliProgram.version` (`myapp version`).
-- **`mcp`** — when `mcpServer.enabled` is `true`, run as an MCP stdio server (`myapp mcp`).
-- **`docs`** — when `docs.enabled` is `true`, print bundled markdown topics, schema JSON, API markdown, and generated skill content (`myapp docs`, `myapp docs readme`, `myapp docs schema`, `myapp docs api`, `myapp docs skill`, …). See [docs/bundled-docs.md](docs/bundled-docs.md).
-- **`install`** — install the app, completions, skills, and MCP config to the user environment (`myapp install --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.
+- `completion bash` **/** `completion zsh` **/** `completion fish` — print shell completion scripts to stdout (injected by `Cli.run()`).
+- `version` — print `CliProgram.version` (`myapp version`).
+- `mcp` — when `mcpServer.enabled` is `true`, run as an MCP stdio server (`myapp mcp`).
+- `docs` — when `docs.enabled` is `true`, print bundled markdown topics, schema JSON, API markdown, and generated skill content (`myapp docs`, `myapp docs readme`, `myapp docs schema`, `myapp docs api`, `myapp docs skill`, …). See [docs/bundled-docs.md](docs/bundled-docs.md).
+- `install` — refresh agent skills and MCP config (`myapp install --reinstall --yes` after Homebrew install). 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.
 
 ### 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 docs schema`). Handlers can read `ctx.invocation`; use `cli.invoke(argv)` for headless testing.
 
-See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details. See **[docs/cli-program.md](docs/cli-program.md)** for schema authoring (consumer apps: copy **`docs/templates/cursor/rules/cli-program.mdc`** to **`.cursor/rules/cli-program.mdc`**).
+See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details. See **[docs/cli-program.md](docs/cli-program.md)** for schema authoring (consumer apps: run `bunx argsbarg create` or refresh with `bun scripts/merge-cli-program-rule.ts .` from the argsbarg package).
 
 ### Install CLI
 
-argsbarg includes CLI features to manage installation of your compiled bun app. After `bun build --compile` (or when running via `bun`), ship your CLI and let users run:
+Ship via **Homebrew** (tap-from-repo). The formula installs the binary and shell completions; `post_install` runs agent artifact refresh:
 
 ```bash
-myapp install --yes
+brew tap <org>/<repo>
+brew install <tap>/myapp
+myapp install --configure    # opt-in app config wizard
 ```
 
-This copies the app to `~/.local/bin`, installs shell completions (bash/zsh/fish when each shell is on PATH), and runs the configure wizard when `program.appConfig` is set. Agent skills or MCP config are included in `--all` per `install.agentIntegration` (skills when MCP is off; MCP when `mcpServer.enabled`).
-
-See **[docs/install.md](docs/install.md)** for `--reinstall`, `install --update`, `--status`, `--uninstall`, and flags.
-
+See **[docs/distribution-homebrew.md](docs/distribution-homebrew.md)** for formula patterns and `bunx argsbarg create`. See **[docs/install.md](docs/install.md)** for `install`, `uninstall`, `--reinstall`, and `--status`.
 
 ### Shell completions
 
-```bash
-myapp completion bash > ~/.bash_completion.d/myapp
-# or: source <(myapp completion bash)
+Homebrew installs completion scripts during `brew install` via `generate_completions_from_executable`. The CLI still exposes generation for formula authors:
 
-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
+```bash
+myapp completion bash
+myapp completion zsh
+myapp completion fish
 ```
 
-
+Users configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
 
 ## Quick Start
 
@@ -147,31 +140,38 @@ myapp completion fish > ~/.config/fish/completions/myapp.fish
 bun add argsbarg
 ```
 
+
+
 ### Cursor / AI agents
 
 Argsbarg ships authoring docs in `node_modules/argsbarg/docs/`. Agents do not load them unless your repo points there — copy the thin Cursor rule after install (it tells agents to **read** `cli-program.md`, not duplicate it):
 
 ```bash
 mkdir -p .cursor/rules
-cp node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc .cursor/rules/cli-program.mdc
+mkdir -p .cursor/rules
+bun scripts/merge-cli-program-rule.ts . \
+  node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc
 ```
 
 Add app-specific conventions in a second rule if needed. Copy the rule from the template, then add a `**<your-app> conventions:**` block at the bottom (see **Cursor rule** in [docs/cli-program.md](docs/cli-program.md)). Documentation map: **[docs/README.md](docs/README.md)**.
 
-
 ## How it works
 
 1. Build a **program root** with `satisfies CliProgram` (or `: CliProgram`): `key` is the app 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 new Cli(program).run()` — 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**.
 
+
+
 ### Fallback modes (`CliFallbackMode`)
 
-| Mode | Empty argv | Unknown first token |
-| --- | --- | --- |
-| `MissingOnly` | Default command | Error |
-| `MissingOrUnknown` | Default command | Default command (token becomes argv for the default) |
-| `UnknownOnly` | Root help (exit 1) | Default command |
+
+| Mode               | Empty argv         | Unknown first token                                  |
+| ------------------ | ------------------ | ---------------------------------------------------- |
+| `MissingOnly`      | Default command    | Error                                                |
+| `MissingOrUnknown` | Default command    | Default command (token becomes argv for the default) |
+| `UnknownOnly`      | Root help (exit 1) | Default command                                      |
+
 
 With `MissingOrUnknown` / `UnknownOnly`, unrecognized flags at the **current routing node** stop option consumption and the remainder is passed to the default command.
 
@@ -181,12 +181,16 @@ Set `fallbackCommand` / `fallbackMode` on nested routers too — e.g. `docs` wit
 
 Add `CliPositional` entries to the command’s `positionals` list (separate from `CliOption` flags). With `argMax: 0`, the tail accepts at least `argMin` tokens and has no upper bound unless you set `argMax` > 0.
 
-| Fields | Label |
-| --- | --- |
-| omit `argMin` / `argMax` (defaults `1` / `1`, one required word) | `<n>` |
-| `argMin: 0`, `argMax: 1` | `[n]` |
-| `argMin: 0`, `argMax: 0` | `[n...]` |
-| `argMin: 1`, `argMax: 0` | `<n...>` |
+
+| Fields                                                           | Label    |
+| ---------------------------------------------------------------- | -------- |
+| omit `argMin` / `argMax` (defaults `1` / `1`, one required word) | `<n>`    |
+| `argMin: 0`, `argMax: 1`                                         | `[n]`    |
+| `argMin: 0`, `argMax: 0`                                         | `[n...]` |
+| `argMin: 1`, `argMax: 0`                                         | `<n...>` |
+
+
+
 
 ### Reading values (`CliContext`)
 
@@ -201,25 +205,26 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.
 - `ctx.program` — program root (`CliProgram`) for contextual help.
 
-### 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`, `docs`). Reserved command names: `completion` and `version` always; `install` unless `install.enabled: false`; `mcp` when `mcpServer.enabled` is `true`; `docs` when `docs.enabled` is `true`. When `install.updateGetLatest` is set, `install --update` is available (not a separate command).
 
+### 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`, `docs`). Reserved command names: `completion` and `version` always; `install` unless `install.enabled: false`; `mcp` when `mcpServer.enabled` is `true`; `docs` when `docs.enabled` is `true`.
 
 ## Examples
 
 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 command tree, positional tails, async handlers. |
-| `ArgsBargFormats` | `examples/formats.ts` | `CliValueFormat`, `default`, `readLeafInputs()`. |
-| `ArgsBargConfigApp` | `examples/config-app/` | `program.appConfig`, `ctx.appConfig`, built-in `config get`/`set`, inline JSON Schema. |
-| `ArgsBargConsumerApp` | `examples/consumer-app/` | **Copy template:** all builtins, schemagen discovery, `outputSchema`, `from "argsbarg"`. |
 
-Examples ship in the npm package under `node_modules/argsbarg/examples/`. Agents should read **`config-app`** for concepts and **`consumer-app`** when scaffolding a full CLI.
+| Example               | File                     | Shows                                                                                    |
+| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
+| `ArgsBargMinimal`     | `examples/minimal.ts`    | String + presence flags, `MissingOrUnknown` fallback.                                    |
+| `ArgsBargNested`      | `examples/nested.ts`     | Nested command tree, positional tails, async handlers.                                   |
+| `ArgsBargFormats`     | `examples/formats.ts`    | `CliValueFormat`, `default`, `readLeafInputs()`.                                         |
+| `ArgsBargFullExample` | `examples/full-example/` | **Copy template:** all builtins, schemagen, Homebrew justfile, `outputSchema`, `from "argsbarg"`. |
+
+
+Examples ship in the npm package under `node_modules/argsbarg/examples/`. Bootstrap a production CLI with `bunx argsbarg create my-cli`.
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -234,11 +239,8 @@ nested.ts read ./README.md
 
 bun ./examples/formats.ts run --tags demo,docs --on 2026-06-22
 
-CONFIG_APP_API_TOKEN=dev bun ./examples/config-app/main.ts show --json
-CONFIG_APP_API_TOKEN=dev bun ./examples/config-app/main.ts config get
-
-cd examples/consumer-app && bun install && bun run schemagen
-CONSUMER_APP_API_TOKEN=dev bun run start status --json
+cd examples/full-example && just setup && just schemagen
+FULL_EXAMPLE_API_TOKEN=dev just run status --json
 ```
 
 
@@ -247,23 +249,27 @@ CONSUMER_APP_API_TOKEN=dev bun run start status --json
 
 The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you need to define a schema and run it. Parsing, completion script generation, help rendering, and schema pre-validation live in other modules under `src/` for tests and advanced integrations.
 
-| Symbol | Role |
-| --- | --- |
-| `CliProgram`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
-| `CliOptionKind`, `CliValueFormat`, `CliFallbackMode` | Option kinds, value formats (`duration`, `comma-list`, `date`, `date-time`), and root fallback behavior. |
-| `CliSchemaValidationError` | Thrown when the static command tree violates schema rules. |
-| `CliContext` | Handler context (`ctx.hasFlag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.readLeafInputs`, `ctx.invocation`, …). |
-| `CliLeafInputs` | Record type returned by `readLeafInputs()` — coerced option/positional values keyed by schema name. |
-| `Cli` | Runtime: validate + freeze program, `run()`, `invoke()`, `serveMcp()`, `appConfig` getter, `exportCommandSchema()`, `exportAppConfigSchema()`. |
-| `CliInvokeResult`, `CliInvokeKind` | Result types from `cli.invoke()`. |
-| `CliAppConfig`, `CliAppConfigEntry` | App config block on the program root (`entries` metadata overlay + optional `jsonSchema`). |
-| `cliErrWithHelp(ctx, msg)` | Print error + scoped help on stderr, exit 1. |
-| `parseDurationMs`, `parseCommaList`, `parseDate`, `parseDateTime` | Optional format parsers for use outside handlers. |
-
-Reserved identifiers (validated at startup): root commands **`completion`**, **`version`**, **`install`**, **`docs`** (when `docs.enabled` is `true`), and **`mcp`** (when `mcpServer.enabled` is `true`).
+
+| Symbol                                                            | Role                                                                                                                                           |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CliProgram`, `CliOption`, `CliPositional`, `CliHandler`          | Schema and handler types.                                                                                                                      |
+| `CliOptionKind`, `CliValueFormat`, `CliFallbackMode`              | Option kinds, value formats (`duration`, `comma-list`, `date`, `date-time`), and root fallback behavior.                                       |
+| `CliSchemaValidationError`                                        | Thrown when the static command tree violates schema rules.                                                                                     |
+| `CliContext`                                                      | Handler context (`ctx.hasFlag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.readLeafInputs`, `ctx.invocation`, …).                                |
+| `CliLeafInputs`                                                   | Record type returned by `readLeafInputs()` — coerced option/positional values keyed by schema name.                                            |
+| `Cli`                                                             | Runtime: validate + freeze program, `run()`, `invoke()`, `serveMcp()`, `appConfig` getter, `exportCommandSchema()`, `exportAppConfigSchema()`. |
+| `CliInvokeResult`, `CliInvokeKind`                                | Result types from `cli.invoke()`.                                                                                                              |
+| `CliAppConfig`, `CliAppConfigEntry`                               | App config block on the program root (`entries` metadata overlay + optional `jsonSchema`).                                                     |
+| `cliErrWithHelp(ctx, msg)`                                        | Print error + scoped help on stderr, exit 1.                                                                                                   |
+| `parseDurationMs`, `parseCommaList`, `parseDate`, `parseDateTime` | Optional format parsers for use outside handlers.                                                                                              |
+
+
+Reserved identifiers (validated at startup): root commands `completion`, `version`, `install`, `docs` (when `docs.enabled` is `true`), and `mcp` (when `mcpServer.enabled` is `true`).
 
 ---
 
+
+
 ## License
 
-MIT
+MIT

package/docs/README.md

@@ -9,11 +9,12 @@ Start here to pick the right guide.
 | **JSON stdout / `outputSchema`** | [output-schema.md](output-schema.md) — codegen pipeline, JSDoc, narrowing |
 | **App config / `program.appConfig`** | [config-schema.md](config-schema.md) — flat JSON file, `ctx.appConfig`, codegen |
 | **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `install --mcp` |
-| **Shipping install / completions / skills** | [install.md](install.md) — `myapp install`, shell completions |
+| **Shipping install / agent artifacts** | [install.md](install.md) — Homebrew + `myapp install --reinstall` |
+| **Homebrew tap-from-repo distribution** | [distribution-homebrew.md](distribution-homebrew.md) — formula pattern, `argsbarg create` |
 | **Bundling `myapp docs` topics** | [bundled-docs.md](bundled-docs.md) — consumer docgen vs framework docs |
 | **Agent skills** | [ai-skills.md](ai-skills.md) — `install --skill`, `docs skill` |
 | **Maintaining the argsbarg repo** | [developing.md](developing.md) — release, consumers, npm `files` |
-| **Cursor / IDE agents in a consumer app** | Copy [templates/cursor/rules/cli-program.mdc](templates/cursor/rules/cli-program.mdc) to `.cursor/rules/` |
+| **Cursor / IDE agents in a consumer app** | `bunx argsbarg create` (includes rule) or `bun scripts/merge-cli-program-rule.ts .` from argsbarg checkout |
 | **Runnable examples** (shipped in npm) | [examples/](examples/) — see table below |
 
 ## Examples (agents: read these)
@@ -22,9 +23,8 @@ Examples are included in the npm tarball (`package.json` `files`). After `bun ad
 
 | Tier | Path | Use when |
 | --- | --- | --- |
-| Learn | [examples/minimal.ts](../examples/minimal.ts), [config-app/](../examples/config-app/) | One feature at a time |
-| Reference | [examples/nested.ts](../examples/nested.ts), [formats.ts](../examples/formats.ts) | Routing, formats, MCP snippet |
-| **Copy** | [examples/consumer-app/](../examples/consumer-app/) | Bootstrapping a production CLI (all builtins + schemagen) |
+| Learn | [examples/minimal.ts](../examples/minimal.ts), [examples/nested.ts](../examples/nested.ts), [formats.ts](../examples/formats.ts) | One feature at a time |
+| **Copy** | [examples/full-example/](../examples/full-example/) | Bootstrapping a production CLI (all builtins + schemagen + Homebrew justfile) |
 
 ## Framework docs vs consumer docgen
 
@@ -32,6 +32,6 @@ Examples are included in the npm tarball (`package.json` `files`). After `bun ad
 | --- | --- | --- |
 | **Framework docs** | How argsbarg works; authoring conventions | This directory — shipped in `node_modules/argsbarg/docs/` after `bun add argsbarg` |
 | **Consumer docgen** | *Your* command tree, API, MCP guide for *your* app | `myapp docs api`, `docs schema`, `docs mcp` — written to `./docs/` with `--save` |
-| **Cursor rule** | Thin tripwire telling agents to read framework docs | `node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc` — copy into your repo and append app conventions |
+| **Cursor rule** | Thin tripwire telling agents to read framework docs | `node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc` — included by `create`; refresh with `merge-cli-program-rule.ts` |
 
 Agents do **not** load `node_modules/argsbarg/docs/` unless your repo references them (Cursor rule, `AGENTS.md`, or an `alwaysApply` project rule). Generated `./docs/api.md` in a consumer repo describes **your** CLI, not argsbarg itself.

package/docs/bundled-docs.md

@@ -8,7 +8,7 @@ Two documentation layers often coexist in a consumer repo:
 
 | Layer | Contents | How agents/humans get it |
 | --- | --- | --- |
-| **Argsbarg framework** | How to author `CliProgram`, MCP varargs policy, headless patterns | `node_modules/argsbarg/docs/` — wire via [Cursor rule](templates/cursor/rules/cli-program.mdc) or `AGENTS.md` |
+| **Argsbarg framework** | How to author `CliProgram`, MCP varargs policy, headless patterns | `node_modules/argsbarg/docs/` — wire via [full-example Cursor rule](../examples/full-example/.cursor/rules/cli-program.mdc) or `AGENTS.md` |
 | **Your CLI (docgen)** | Your command tree, options, MCP tool list, install notes | `myapp docs api`, `docs schema`, `docs mcp` — save with `--save` to `./docs/` |
 
 `docs api` and `docs schema` embed each leaf’s `outputSchema` when set — see [output-schema.md](output-schema.md) for how to generate and wire schemas.

package/docs/cli-program.md

@@ -417,7 +417,8 @@ await cli.run();
 | `default` | — | Used when `jsonSchema` omitted (all-string mode) |
 | `required` | `true` | When `false`, optional unless required by `jsonSchema` |
 | `sensitive` | name heuristic (`token`, `secret`, …) | Redact in prompts, `config get`, and status |
-| `env` | — | When set: non-empty host env overrides file; exported to `process.env` after resolve |
+| `env` | — | When set: non-empty host env overrides file; consulted again after `resolve` when `resolve` returns `undefined`; exported to `process.env` after resolve |
+| `resolve` | — | Optional fallback after file; return `undefined` to fall back to `env` (if set) and defaults |
 
 **Config file** (created on demand):
 
@@ -447,10 +448,11 @@ Agents do **not** discover package docs automatically. Wire them in after `bun a
 
 ```bash
 mkdir -p .cursor/rules
-cp node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc .cursor/rules/cli-program.mdc
+bun scripts/merge-cli-program-rule.ts . \
+  node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc
 ```
 
-The template is ~25 lines: when to read which doc, plus hard rules agents often get wrong. It does **not** duplicate this guide.
+The template is ~30 lines: when to read which doc, plus hard rules agents often get wrong. It does **not** duplicate this guide. `bunx argsbarg create` copies this file into new projects automatically.
 
 2. **Add an app-specific block at the bottom** (recommended). Replace the template placeholder with a heading like `**myapp conventions:**` and short bullets — shared flag modules, `read*Flags` / `resolve*` paths, Ink vs JSON-only, etc. Example:
 

package/docs/config-schema.md

@@ -39,7 +39,7 @@ await cli.run();
 | Where argsbarg uses it | Purpose |
 | --- | --- |
 | Config file | Flat JSON keyed by schema names; strict load (unknown keys rejected) |
-| `install --configure` / `--status` | Interactive setup and status |
+| `install --configure` / `--status` | Interactive setup (configure is opt-in, not in `--all`) and status |
 | Built-in `config get` / `config set` | Read/write resolved values (opt-out via `commands: false`) |
 | MCP bundle / Claude plugin | `userConfig` for entries with `env` set |
 | `ctx.appConfig` in handlers | `get`, `require`, `set`, `read`, `path`, `dir` — prefer over `process.env` |
@@ -60,6 +60,7 @@ export interface CliAppConfigEntry {
   required?: boolean;   // default: true (can override jsonSchema required)
   sensitive?: boolean;  // default: name heuristic
   env?: string;         // env override + export to process.env after resolve
+  resolve?: CliAppConfigResolveFn;  // fallback after file; must be synchronous
 }
 
 export interface CliAppConfig {
@@ -92,13 +93,40 @@ No nested `env` bag. No extra keys — rejected on load.
 
 ## Resolution order (per schema key)
 
-| Key has `env`? | Resolved value |
-| --- | --- |
-| **Yes** | non-empty `process.env[env]` → else file[key] → else default |
-| **No** | file[key] → else default |
+| Step | Source | Notes |
+| --- | --- | --- |
+| 1 | **Env** (`entry.env`) | Non-empty host env wins over file and `resolve` |
+| 2 | **File** | `config.json` value for the key |
+| 3 | **`resolve()`** | Optional synchronous callback (e.g. `gh auth token`); return `undefined` to continue. Async/Promise return values are ignored. |
+| 4 | **Env** (`entry.env`) | Fallback when `resolve` returned `undefined` |
+| 5 | **Default** | `jsonSchema` / `entry.default` |
 
 Empty string in env or file counts as **missing** for required entries. After resolution, mapped values are exported to `process.env`.
 
+Example — GitHub token with `env: "GH_TOKEN"` and `resolve` calling `gh auth token`:
+
+```typescript
+githubToken: {
+  description: "GitHub API token.",
+  env: "GH_TOKEN",
+  sensitive: true,
+  resolve: () => {
+    try {
+      const r = Bun.spawnSync(["gh", "auth", "token"], { stdout: "pipe", stderr: "ignore" });
+      if (r.exitCode === 0) {
+        const token = new TextDecoder().decode(r.stdout).trim();
+        return token.length > 0 ? token : undefined;
+      }
+    } catch {
+      // `gh` not installed
+    }
+    return undefined;
+  },
+},
+```
+
+`install --configure` does not persist values supplied only by env or `resolve` when you press Enter to accept the current value.
+
 ## Hand-written vs generated
 
 | Approach | When |
@@ -180,10 +208,9 @@ Object/array/`$ref` properties require `--json` on `config set`.
 
 | Example | Role |
 | --- | --- |
-| [`examples/config-app/`](../examples/config-app/) | **Learn** — hand-written schema, minimal setup |
-| [`examples/consumer-app/`](../examples/consumer-app/) | **Copy** — schemagen discovery, `APP_CONFIG_JSON_SCHEMA` bridge |
+| [`examples/full-example/`](../examples/full-example/) | **Copy template** — schemagen discovery, `APP_CONFIG_JSON_SCHEMA` bridge, `program.appConfig`, built-in `config get`/`set` |
 
 ```bash
-cd examples/consumer-app && bun install && bun run schemagen
-CONSUMER_APP_API_TOKEN=dev bun run start config get apiToken --json
+cd examples/full-example && just setup && just schemagen
+FULL_EXAMPLE_API_TOKEN=dev just run config get apiToken --json
 ```

package/docs/developing.md

@@ -33,15 +33,15 @@ Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile
 | Recipe | When | Effect |
 | --- | --- | --- |
 | `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` from template (keeps app-specific suffix) |
-| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **argsbarg Cursor rule**, `just build`, `just docgen`, `just install` (consumer app binary, completions, and **app** skill) |
+| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **argsbarg Cursor rule**, `just build`, `just docgen`, `just install-local` (Homebrew dev formula + agent artifacts; `just install` is an alias) |
 
 `consumers-sync` reads the version from **this repo’s** `package.json` — not npm. Run it **after** `just release` so consumers pin a version that exists on the registry.
 
-**Argsbarg authoring rule** — `scripts/merge-cli-program-rule.ts` copies `docs/templates/cursor/rules/cli-program.mdc` into each consumer’s `.cursor/rules/cli-program.mdc`, preserving any existing `**… conventions:**` footer block.
+**Argsbarg authoring rule** — `scripts/merge-cli-program-rule.ts` copies `examples/full-example/.cursor/rules/cli-program.mdc` into each consumer’s `.cursor/rules/cli-program.mdc`, preserving any existing `**… conventions:**` footer block.
 
 **Recommended in each consumer:** replace the template placeholder with `**<app> conventions:**` bullets (paths to `read*Flags`, shared flags, Ink vs JSON-only). Commit that file; merges refresh the shared top, not your footer.
 
-**Consumer app skill** — `just install` in each consumer (part of `consumers-sync`) runs `myapp install --skill`, which updates `~/.cursor/skills/<app>/` from that app’s schema — not the argsbarg framework rule.
+**Consumer app skill** — `just install-local` in each consumer (part of `consumers-sync`) runs Homebrew dev install then `myapp install --reinstall --yes`, which updates `~/.cursor/skills/<app>/` from that app’s schema — not the argsbarg framework rule.
 
 ## npm package contents
 
@@ -49,14 +49,14 @@ Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile
 
 When adding docs or examples intended for consumers, ensure they live under whitelisted paths (`docs/`, `examples/`, `src/`, etc.).
 
-Exclude `examples/consumer-app/node_modules/` from the npm tarball via [`.npmignore`](../.npmignore).
+Exclude `examples/full-example/node_modules/` from the npm tarball via [`.npmignore`](../.npmignore).
 
-## Kitchen-sink example
+## Full example
 
-[`examples/consumer-app/`](../examples/consumer-app/) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
+[`examples/full-example/`](../examples/full-example/) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
 
 ```bash
-just consumer-app-schemagen
+just full-example-schemagen
 just test
 ```