argsbarg 4.1.0 → 5.0.1

package/CHANGELOG.md

@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.1] - 2026-07-04
+
+
+## [5.0.0] - 2026-07-03
+
+### Added
+
+- **Top-level `configure` built-in** — interactive per-target wizard (TTY required); non-interactive `--sync --yes` (replaces `install --reinstall`), `--remove-all --yes`, `--remove-config --yes`, and `--status`.
+- **`configure --remove-config --yes`** — config-only removal without touching skills/MCP.
+
+### Changed
+
+- **Breaking: `install` and `uninstall` removed** — use `configure` and its flags; no redirects or deprecated aliases.
+- **Breaking: `program.install` → `program.configure`** — `CliConfigureConfig`, `CliConfigureTargets`, `caps.configure`.
+- **Breaking: `completion` hidden** from help and exported schema; still callable for Homebrew `generate_completions_from_executable`.
+- **Breaking: skill install hint** — `Generated by … configure` (was `install --skill`).
+- **Formula `post_install`** — `configure --sync --yes` (was `install --reinstall --yes`).
+- **Just recipes** — `sync-artifacts`, `configure --remove-all --yes`, `configure --remove-config --yes`.
+- **Docs** — `docs/install.md` replaced by [docs/configure.md](docs/configure.md).
+
+### Removed
+
+- Top-level **`install`** and **`uninstall`** commands and all scoped install/uninstall flags (`--all`, `--skill`, `--mcp`, `--reinstall`, …).
+
+## [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 +567,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/v4.1.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.0.1...HEAD
+[5.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.1
+[5.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.0
+[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).
+- `configure` — manage agent skills, MCP config, and app config (`myapp configure --sync --yes` after Homebrew install). See [docs/configure.md](docs/configure.md).
 
+Do not declare a top-level command named `completion`, `version`, or `configure` — 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
+### Configure 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 configure    # interactive per-target setup; 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/configure.md](docs/configure.md)** for `configure`, `--sync`, `--remove-all`, 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

@@ -8,12 +8,13 @@ Start here to pick the right guide.
 | **Authoring a `CliProgram`** (humans or agents) | [cli-program.md](cli-program.md) — schema, formats, headless, `read*Flags` |
 | **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 |
+| **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `configure --sync` |
+| **Shipping configure / agent artifacts** | [configure.md](configure.md) — Homebrew + `myapp configure --sync` |
+| **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` |
+| **Agent skills** | [ai-skills.md](ai-skills.md) — `configure`, `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/ai-skills.md

@@ -2,14 +2,14 @@
 
 ArgsBarg can generate Cursor and Claude Code skill directories (`SKILL.md` + `reference.md`) from your CLI schema.
 
-## Install via `install` (recommended)
+## Install via `configure` (recommended)
 
 Install skills to the user environment:
 
 ```bash
-myapp install --skill --yes
-# or bare install when agentIntegration defaults to skill:
-myapp install --yes
+myapp configure --sync --yes
+# or interactive (accept skill targets when prompted):
+myapp configure
 ```
 
 Skills are written when the agent home or CLI exists:
@@ -37,7 +37,7 @@ For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true
 - **`SKILL.md`** — YAML frontmatter, compact command index, pitfalls, and a pointer to `reference.md`
 - **`reference.md`** — full `docs api` markdown reference
 
-Installed files include an HTML comment hint (`Generated by myapp install --skill; do not edit.`) after SKILL.md frontmatter and at the top of `reference.md`.
+Installed files include an HTML comment hint (`Generated by myapp configure; do not edit.`) after SKILL.md frontmatter and at the top of `reference.md`.
 
 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.
 
@@ -46,15 +46,15 @@ Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tool
 | Mechanism | Role |
 | --- | --- |
 | **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`myapp install --skill`** | Persists optimized skill bundle (`SKILL.md` index + `reference.md` full API) |
+| **`myapp configure`** (skill targets) | Persists optimized skill bundle (`SKILL.md` index + `reference.md` full API) |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
-`SKILL.md` is the routing index; `reference.md` matches `docs api`. Prefer `install --skill` over `docs skill` for agents. See [cli-program.md](cli-program.md).
+`SKILL.md` is the routing index; `reference.md` matches `docs api`. Prefer `configure` over `docs skill` for agents. See [cli-program.md](cli-program.md).
 
-**Claude Code plugin** (`mcpServer.claudePlugin: true` → `mcp bundle` writes `dist/claude-plugin/<name>.zip`) ships a separate MCP pointer skill (`SKILL.md` only) that routes agents to the bundled MCP server. This is a **dist artifact**, not installed via `install`. Use **`install --skill`** for persisted shell-oriented skills.
+**Claude Code plugin** (`mcpServer.claudePlugin: true` → `mcp bundle` writes `dist/claude-plugin/<name>.zip`) ships a separate MCP pointer skill (`SKILL.md` only) that routes agents to the bundled MCP server. This is a **dist artifact**, not installed via `configure`. Use **`configure`** for persisted shell-oriented skills.
 
 See also:
 
 - [Bundled docs](bundled-docs.md) — `docs` config and compile-time imports
 - [MCP server](mcp.md) — `mcpServer` config and `mcp` protocol
-- [Install](install.md) — app, completions, skills, and MCP config
+- [Configure](configure.md) — app, completions, skills, and MCP config

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.
@@ -50,7 +50,7 @@ myapp docs readme --save   # write ./docs/readme.md
 myapp docs schema --save   # write ./docs/schema.json
 ```
 
-When `docs` is enabled, top-level `myapp --help` points agents at `myapp docs skill`. The `docs skill` subcommand description recommends `install --skill` for a persisted bundle.
+When `docs` is enabled, top-level `myapp --help` points agents at `myapp docs skill`. The `docs skill` subcommand description recommends `configure` for a persisted bundle.
 
 ## Configuration
 
@@ -83,11 +83,11 @@ 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 the compact `SKILL.md` index. Prefer `install --skill --yes` for agents (persists index + full API in `reference.md`).
+- **`docs skill`** — prints the compact `SKILL.md` index. Prefer `configure --sync --yes` for agents (persists index + full API in `reference.md`).
 
 ## MCP guide (`docs mcp`)
 
-When both `docs.enabled` and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `program.appConfig`, schema resource URI, `install --mcp`, and protocol notes.
+When both `docs.enabled` and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `program.appConfig`, schema resource URI, `configure --sync`, and protocol notes.
 
 There is no override API in v1 — customize behavior via `mcpTool.description` on leaf commands.
 
@@ -99,7 +99,7 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 
 | Channel | Role |
 | --- | --- |
-| `install --skill` | Writes compact `SKILL.md` + full-API `reference.md` to disk |
+| `configure` (skill targets) | Writes compact `SKILL.md` + full-API `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 |

package/docs/cli-program.md

@@ -2,7 +2,7 @@
 
 ArgsBarg turns your schema into help, shell completions, MCP tools, and agent skills. **The same `description` fields you write for humans are the agent contract** for basic apps.
 
-**Documentation map:** [docs/README.md](README.md) — which guide to read for MCP, install, consumer docgen, and Cursor setup.
+**Documentation map:** [docs/README.md](README.md) — which guide to read for MCP, configure, consumer docgen, and Cursor setup.
 
 ## Minimal app (MCP is free)
 
@@ -413,11 +413,12 @@ await cli.run();
 | Field | Default | Purpose |
 | --- | --- | --- |
 | `description` | *(required)* | Shown in prompts, `config get`, and bundle manifests |
-| `title` | config key | Short label in `install --configure` |
+| `title` | config key | Short label in interactive `configure` |
 | `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):
 
@@ -426,16 +427,16 @@ await cli.run();
 - **Strict:** unknown keys rejected on load.
 - **CLI:** missing required config exits 1 before the leaf handler (TTY prompt when interactive). Built-in `docs` and `config get`/`set` skip this exit.
 - **MCP:** server stays up; missing config returns `isError: true` at `tools/call`.
-- **Configure:** included in default `--all` via `install.targets.configure`; also **`myapp install --configure`** (wizard only).
-- **Agent integration:** `install.agentIntegration` (`mcp` | `skill` | `both`) sets default `--all` targets; see [install.md](install.md#examples).
+- **Configure:** interactive `configure` runs the app config wizard; **`configure --sync`** refreshes agent artifacts.
+- **Agent integration:** `configure.agentIntegration` (`mcp` | `skill` | `both`) sets default sync targets; see [configure.md](configure.md#configuretargets).
 
-See [config-schema.md](config-schema.md) for codegen, [install.md](install.md) (`install.targets`), and [mcp.md](mcp.md).
+See [config-schema.md](config-schema.md) for codegen, [configure.md](configure.md) (`configure.targets`), and [mcp.md](mcp.md).
 
 **Handler access (`ctx.appConfig`):** `get`, `require`, `set`, `read`, `path`, `dir` — prefer over `process.env` in handlers; env export remains for subprocess inheritance. `path` is the resolved absolute config file path (`~/.local/lib/<key>/config`); `dir` is its parent directory.
 
 ## Reserved names
 
-Do not declare user commands named `completion`, `install`, `mcp`, `version`, `docs`, or `config` at the root — ArgsBarg injects these when configured.
+Do not declare user commands named `completion`, `configure`, `mcp`, `version`, `docs`, or `config` at the root — ArgsBarg injects these when configured.
 
 ## Cursor rule for consumer repos
 
@@ -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:
 
@@ -465,7 +467,7 @@ If you maintain argsbarg from a sibling checkout, `just consumer-dev` / `just co
 
 3. **Optional:** a separate rule (e.g. `.cursor/argsbarg.mdc` or `AGENTS.md`) for broader package API notes.
 
-**Not this file:** `myapp install --skill` writes the **app** skill (`SKILL.md` under `~/.cursor/skills/`) from your command schema — how to *invoke* the CLI. The rule above is for *authoring* argsbarg schema.
+**Not this file:** `myapp configure` writes the **app** skill (`SKILL.md` under `~/.cursor/skills/`) from your command schema — how to *invoke* the CLI. The rule above is for *authoring* argsbarg schema.
 
 ## See also
 
@@ -473,5 +475,5 @@ If you maintain argsbarg from a sibling checkout, `just consumer-dev` / `just co
 - [Output schemas](output-schema.md) — codegen pipeline for leaf `outputSchema`
 - [Developing argsbarg](developing.md) — release, consumer sync, npm `files`
 - [MCP server](mcp.md) — tools, schema resource, env bootstrapping
-- [Agent skills](ai-skills.md) — `install --skill`
+- [Agent skills](ai-skills.md) — `configure`
 - [Bundled docs](bundled-docs.md) — `docs` topics, consumer docgen vs framework docs