argsbarg 4.1.1 → 5.0.1

package/CHANGELOG.md

@@ -7,6 +7,30 @@ 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
@@ -543,7 +567,9 @@ 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.1...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

package/README.md

@@ -98,9 +98,9 @@ Every app gets:
 - `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).
+- `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 `install` — they are reserved.
+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.
 
@@ -110,17 +110,17 @@ Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp
 
 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
 
 Ship via **Homebrew** (tap-from-repo). The formula installs the binary and shell completions; `post_install` runs agent artifact refresh:
 
 ```bash
 brew tap <org>/<repo>
 brew install <tap>/myapp
-myapp install --configure    # opt-in app config wizard
+myapp configure    # interactive per-target setup; opt-in app config wizard
 ```
 
-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`.
+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
 

package/docs/README.md

@@ -8,11 +8,11 @@ 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 / agent artifacts** | [install.md](install.md) — Homebrew + `myapp install --reinstall` |
+| **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** | `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 |

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

@@ -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,7 +413,7 @@ 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 |
@@ -427,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
 
@@ -467,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
 
@@ -475,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

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 (configure is opt-in, not in `--all`) and status |
+| Interactive `configure` / `--status` | Auto-runs config wizard when `entries` is non-empty; `--status` for read-only inventory |
 | 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` |
@@ -125,7 +125,7 @@ githubToken: {
 },
 ```
 
-`install --configure` does not persist values supplied only by env or `resolve` when you press Enter to accept the current value.
+Interactive `configure` does not persist values supplied only by env or `resolve` when you press Enter to accept the current value.
 
 ## Hand-written vs generated
 

package/docs/configure.md

@@ -0,0 +1,177 @@
+# Configure command
+
+The `configure` built-in manages **agent artifacts** (skills, MCP config, app config). The **binary and shell completions** ship via Homebrew — see [distribution-homebrew.md](distribution-homebrew.md).
+
+Opt out with `configure: { enabled: false }` on the program root.
+
+## End-user install (Homebrew)
+
+```bash
+brew tap <org>/<repo>
+brew install <tap>/<key>
+<key> configure    # interactive: per-target prompts; run when app config is required
+```
+
+Upgrade with `brew upgrade <key>`. Shell completions are installed by Homebrew during `brew install`. Users must configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
+
+**Uninstall the binary:** remove agent artifacts first (while the CLI is still on PATH), then `brew uninstall`:
+
+```bash
+<key> configure --remove-all --yes
+brew uninstall <tap>/<key>
+```
+
+## Developer install
+
+```bash
+just build
+just install-local    # same formula as production; gen-dev-formula uses file:// URL (`just install` is an alias)
+```
+
+Dev flow matches release: formula `install` copies the binary and generates completions; `post_install` runs `<key> configure --sync --yes` for skills/MCP. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles (skips completions and `post_install`). Use `just sync-artifacts` to refresh agent artifacts without touching the binary.
+
+## Quick reference
+
+```bash
+# Refresh skills/MCP after upgrade (Homebrew post_install runs this automatically)
+<key> configure --sync --yes
+
+# See what is installed
+<key> configure --status
+
+# Interactive per-target setup (default when run with a TTY)
+<key> configure
+
+# Remove all agent artifacts
+<key> configure --remove-all --yes
+
+# Remove app config only (not skills/MCP)
+<key> configure --remove-config --yes
+```
+
+Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remove-all`**, **`--remove-config`**) — see [Confirmation](#confirmation).
+
+## What gets configured
+
+| Target | Interactive | Mechanism |
+| --- | --- | --- |
+| Binary | skipped (read-only) | Homebrew formula `bin.install` |
+| Shell completions | skipped | Homebrew `generate_completions_from_executable` |
+| Cursor skill | Y/n prompt | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
+| Claude skill | Y/n prompt | `~/.claude/skills/<dir>/` when `~/.claude` exists |
+| Codex / OpenCode / OpenClaw skills | Y/n prompt | Agent-specific dirs when available |
+| MCP config | Y/n prompt | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
+| App config | auto-runs wizard | Interactive wizard writes `~/.local/lib/<key>/config.json` |
+
+### Externally managed binary (Homebrew)
+
+When **`PATH`** resolves the program key to the **running executable** (e.g. after `brew install`):
+
+- **`configure --status`** shows `app: system (PATH)`
+- **`--sync`** refreshes skills and MCP only — not the binary or completions
+
+MCP config uses the command name on **`PATH`**, not a Cellar path.
+
+### Interactive default
+
+Bare **`configure`** (TTY required) walks enabled install targets in order. For each target:
+
+- **Not installed:** `[Y/n]` — default install; `n` skips.
+- **Installed:** `[y/N]` — default keep; `n` uninstalls.
+- **App config** (`program.appConfig` with entries): runs the config wizard automatically (no Y/n gate). Remove the config file with **`configure --remove-config --yes`**.
+
+The **`app`** target (binary on PATH) is shown in `--status` only — never mutated by `configure`.
+
+### `configure.targets`
+
+Configure which artifacts participate in `--sync`:
+
+```typescript
+configure: {
+  agentIntegration: "mcp", // | "skill" | "both" — default from mcpServer.enabled
+  targets: {
+    chatgptMcp: false,
+    cursorSkill: { includedInAll: true },
+  },
+},
+```
+
+`ConfigureTargetSpec` is `boolean` or `{ enabled?: boolean; includedInAll?: boolean }`.
+
+Artifact keys: `chatgptMcp`, `claudeCodeMcp`, `claudeDesktopMcp`, `claudeSkill`, `codexMcp`, `codexSkill`, `configure`, `cursorMcp`, `cursorSkill`, `openclawMcp`, `openclawSkill`, `opencodeMcp`, `opencodeSkill`.
+
+## App config (`program.appConfig`)
+
+When `program.appConfig` is set, ArgsBarg manages a flat JSON config file at `~/.local/lib/<sanitized-key>/config.json`.
+
+| Mode | Description |
+| --- | --- |
+| Interactive `configure` | Config wizard when you accept the configure target |
+| `--status` | Shows config path and which required keys are set or missing |
+| `--remove-config --yes` | Removes the config directory |
+
+Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
+
+## Flags
+
+### Operation flags
+
+| Flag | Description |
+| --- | --- |
+| `--status` | Read-only inventory |
+| `--sync` | Refresh installed agent artifacts (Homebrew `post_install`; greenfield → full sync plan) |
+| `--remove-all` | Remove all detected agent artifacts |
+| `--remove-config` | Remove app config directory only |
+
+### Behavior flags
+
+| Flag | Description |
+| --- | --- |
+| `--yes`, `-y` | Skip confirmation (required for non-interactive modes) |
+| `--dry` | Preview changes |
+| `--json` | Machine-readable output (implies `--yes`) |
+
+## Confirmation
+
+Interactive `configure` prints a **`{app} Setup`** banner and per-target prompts. Non-interactive modes (`--sync`, `--remove-all`, `--remove-config`) require **`--yes`** unless `--dry`.
+
+## MCP merge behavior
+
+When MCP targets are installed, entries are merged into host config with:
+
+```json
+{ "command": "<root.key>", "args": ["mcp"] }
+```
+
+If an existing entry differs, the command exits with an error unless `--yes` is passed.
+
+## Formula `post_install`
+
+Release formulae should run:
+
+```ruby
+def post_install
+  system bin/"myapp", "configure", "--sync", "--yes"
+end
+```
+
+This refreshes skills/MCP without running the configure wizard (app config is opt-in via interactive `configure`).
+
+## Bootstrapping a new CLI
+
+```bash
+bunx argsbarg create my-cli --key my-cli --class-name MyCli --tap org/repo --yes
+bunx argsbarg create --check .
+```
+
+See [distribution-homebrew.md](distribution-homebrew.md) and [../examples/full-example/README.md](../examples/full-example/README.md).
+
+## Opt out
+
+```typescript
+configure: { enabled: false },
+```
+
+## Completion
+
+The `completion` built-in remains callable for Homebrew `generate_completions_from_executable` but is **hidden** from help and exported schema.

package/docs/developing.md

@@ -41,7 +41,7 @@ Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile
 
 **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-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.
+**Consumer app skill** — `just install-local` in each consumer (part of `consumers-sync`) runs Homebrew dev install then `myapp configure --sync --yes`, which updates `~/.cursor/skills/<app>/` from that app’s schema — not the argsbarg framework rule.
 
 ## npm package contents
 

package/docs/distribution-homebrew.md

@@ -1,14 +1,14 @@
 # Shipping via Homebrew (tap-from-repo)
 
-Argsbarg apps distribute the **binary and shell completions** through Homebrew, and **agent artifacts** (skills, MCP config) through `install --reinstall`.
+Argsbarg apps distribute the **binary and shell completions** through Homebrew, and **agent artifacts** (skills, MCP config) through `configure --sync`.
 
 ## Distribution model
 
 | Layer | Mechanism |
 | --- | --- |
 | Binary + completions | Formula `install` block |
-| Skills + MCP | Formula `post_install` → `{key} install --reinstall --yes` |
-| App config | User opt-in: `{key} install --configure` (interactive; not run from formula `post_install`) |
+| Skills + MCP | Formula `post_install` → `{key} configure --sync --yes` |
+| App config | User opt-in: `{key} configure` (interactive; not run from formula `post_install`) |
 
 **Only tap-from-repo** — in-repo `Formula/` or GitHub tap. Not Homebrew core.
 
@@ -17,7 +17,7 @@ Argsbarg apps distribute the **binary and shell completions** through Homebrew,
 ```bash
 brew tap <org>/<repo>
 brew install <tap>/{key}
-{key} install --configure   # when app config is required
+{key} configure   # when app config is required
 ```
 
 ### Developer install
@@ -36,12 +36,12 @@ Dev and release use the **same formula** (`Formula/{key}.rb`, class name, instal
 | Recipe | Removes |
 | --- | --- |
 | `just uninstall` | Formula `{key}` + tap symlink + skills/MCP |
-| `just uninstall-config` | App config file only (`uninstall --configure`) |
+| `just uninstall-config` | App config file only (`configure --remove-config --yes`) |
 | `just uninstall-release` | Release formula from `{tap}` (keeps tap) |
 | `just uninstall-release-tap` | Release formula + `brew untap {tap}` |
 | `just test-release` | Install release formula and run formula test |
 
-End users: `<key> uninstall --yes` then `brew uninstall <tap>/<key>`.
+End users: `<key> configure --remove-all --yes` then `brew uninstall <tap>/<key>`.
 
 ## Formula pattern
 
@@ -52,7 +52,7 @@ def install
 end
 
 def post_install
-  system bin/"{key}", "install", "--reinstall", "--yes"
+  system bin/"{key}", "configure", "--sync", "--yes"
 end
 ```
 
@@ -90,10 +90,11 @@ Template source: [`examples/full-example/`](../examples/full-example/) in the ar
 ## Removed (breaking)
 
 - Self-install to `~/.local/bin`
+- Top-level `install` and `uninstall` commands (use `configure`)
 - `install --update` / `updateGetLatest`
-- `install --completions` (Homebrew owns completions)
+- Homebrew completion installer via CLI (Homebrew owns completions)
 - Bare-argv install bootstrap
-- Auto configure wizard after `install --all`
+- Auto configure wizard after sync
 - Separate `{key}-local` formula and `{key}/dev` tap
 
 ## Config path

package/docs/mcp.md

@@ -61,11 +61,11 @@ Use your real binary or script path. For a compiled CLI, `command` can be the in
 
 ### Claude Code
 
-`install --mcp` merges into `~/.claude.json` under `mcpServers`.
+`configure` (MCP targets) merges into `~/.claude.json` under `mcpServers`.
 
 ### Claude Desktop
 
-`install --mcp` also merges into Claude Desktop config when app data is present:
+`configure` (MCP targets) also merges into Claude Desktop config when app data is present:
 
 | Platform | Path |
 | --- | --- |
@@ -77,7 +77,7 @@ Restart Claude Desktop after config changes. You can also install a **`.mcpb`**
 
 ### OpenCode
 
-When `~/.config/opencode` exists, **`install --mcp`** merges a local server under the top-level **`mcp`** key (not `mcpServers`):
+When `~/.config/opencode` exists, **`configure`** (MCP targets) merges a local server under the top-level **`mcp`** key (not `mcpServers`):
 
 ```json
 {
@@ -96,7 +96,7 @@ OpenCode reads `opencode.jsonc`, `opencode.json`, or `config.json` in that direc
 
 ### OpenAI Codex
 
-When **`codex`** is on PATH, **`install --mcp`** runs `codex mcp add <server> -- <binary> mcp`, which writes **`~/.codex/config.toml`**. Otherwise add manually:
+When **`codex`** is on PATH, **`configure`** (MCP targets) runs `codex mcp add <server> -- <binary> mcp`, which writes **`~/.codex/config.toml`**. Otherwise add manually:
 
 ```toml
 [mcp_servers.myapp]
@@ -110,7 +110,7 @@ Use **`codex mcp`** to list/add/remove servers, or **Settings → MCP → Open c
 
 **Web / Connectors (OpenAI’s documented path)** — **Settings → Connectors → Developer mode** with a **remote HTTPS MCP URL**. ChatGPT does not spawn local stdio binaries; bridge and tunnel local servers when needed.
 
-**Desktop JSON (gated auto-install)** — when ChatGPT app data exists, **`install --mcp`** also merges `mcpServers` into:
+**Desktop JSON (gated auto-install)** — when ChatGPT app data exists, **`configure`** (MCP targets) also merges `mcpServers` into:
 
 | Platform | Path |
 | --- | --- |
@@ -254,7 +254,7 @@ When both **`docs.enabled`** and **`mcpServer.enabled`** are true, each user key
 | MIME type | `text/markdown` |
 | Contents | Same body as `myapp docs <topicKey>` |
 
-Built-in docs subcommands (`schema`, `api`, `skill`, `mcp`) are **not** auto-exposed — use the schema resource, `install --skill`, or CLI `docs` instead. `docs` subcommands remain hidden from MCP `tools/list`.
+Built-in docs subcommands (`schema`, `api`, `skill`, `mcp`) are **not** auto-exposed — use the schema resource, `configure`, or CLI `docs` instead. `docs` subcommands remain hidden from MCP `tools/list`.
 
 Custom `mcpServer.resources` URIs must not collide with the schema URI or any auto docs topic URI (validated at program compile time).
 
@@ -326,7 +326,7 @@ At server start (`Cli.serveMcp()`), before the NDJSON loop:
 - JSON shape: flat object keyed by schema names — `{ "apiToken": "…" }`. Unknown keys rejected on load.
 - Loaded at MCP startup; host `process.env` wins for mapped env vars already set.
 - Missing required config does **not** exit the MCP server — enforced at `tools/call` with a helpful error.
-- Configure interactively: `myapp install --configure` (see [install.md](install.md)).
+- Configure interactively: `myapp configure` (see [configure.md](configure.md)).
 - Built-in `config get` / `config set` when `program.appConfig.commands` is enabled (default). Hosts inject `user_config` → env at spawn; they never write the argsbarg config file.
 
 Example:
@@ -411,11 +411,11 @@ skills/<dirName>/SKILL.md
 
 `plugin.json` references `.mcp.json` so Claude Desktop and Claude Code load the bundled MCP server when the plugin is enabled. The plugin zip preserves the executable bit on `bin/<key>`.
 
-The bundled `SKILL.md` is an **MCP routing stub** — it tells Claude to use the plugin’s MCP toolset (server id, `tools/list`, schema resource). It is not a shell CLI catalog and does not include `reference.md`. Use **`install --skill`** for a persisted shell-oriented skill bundle.
+The bundled `SKILL.md` is an **MCP routing stub** — it tells Claude to use the plugin’s MCP toolset (server id, `tools/list`, schema resource). It is not a shell CLI catalog and does not include `reference.md`. Use **`configure`** for a persisted shell-oriented skill bundle.
 
 Load locally with `claude --plugin-dir ./dist/claude-plugin/myapp.zip`.
 
-Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `install --mcp` and MCP hosts). Use **`install --mcp`** for Cursor, Claude Code, Claude Desktop, and OpenCode JSON config.
+Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `configure` MCP targets and MCP hosts). Use **`configure --sync --yes`** for Cursor, Claude Code, Claude Desktop, and OpenCode JSON config.
 
 ## Hidden commands and options
 

package/examples/full-example/README.md

@@ -29,11 +29,11 @@ Non-interactive:
 
 ```bash
 bunx argsbarg create my-cli \
-  --key my-cli --class-name MyCli --tap org/my-cli \
-  --homepage https://github.com/org/my-cli --release-repo org/my-cli \
-  --yes
+  --key my-cli --release-repo org/my-cli --yes
 ```
 
+Edit `scripts/create-identity.ts` to set `desc` (used by `program.description` and the Homebrew formula).
+
 `create` copies this template (including `.cursor/rules/cli-program.mdc`), substitutes identity placeholders, runs `bun install`, schemagen, `bun test`, and `git init` + Initial commit when appropriate.
 
 **Git bootstrap:** skipped when `{target}/.git` already exists, or when the target is inside an existing git work tree (monorepo subfolder). Standalone new directories get `Initial commit`.

package/examples/full-example/justfile

@@ -46,8 +46,8 @@ format:
 install: install-local
 
 # Refresh skills and MCP without reinstalling the formula
-install-artifacts:
-    {{cli_key}} install --reinstall --yes
+sync-artifacts:
+    just run configure --sync --yes
 
 # Dev install: build, write dev formula, symlink tap, brew install
 install-local: build
@@ -57,14 +57,14 @@ install-local: build
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
     brew install --formula {{tap}}/{{cli_key}}
     @echo ""
-    @echo "Next: {{cli_key}} install --configure"
+    @echo "Next: {{cli_key}} configure"
 
 # Remove local dev install, then install from GitHub tap
 install-production: uninstall
     brew tap {{tap}}
     brew install --formula {{tap}}/{{cli_key}}
     @echo ""
-    @echo "Next: {{cli_key}} install --configure"
+    @echo "Next: {{cli_key}} configure"
 
 # Alias for backward compatibility
 reinstall: reinstall-local
@@ -112,11 +112,11 @@ uninstall: uninstall-artifacts uninstall-formula
 
 # Remove agent artifacts only (skills, MCP)
 uninstall-artifacts:
-    {{cli_key}} uninstall --yes
+    just run configure --remove-all --yes
 
 # Remove app config file only
 uninstall-config:
-    {{cli_key}} uninstall --configure --yes
+    just run configure --remove-config --yes
 
 # Remove formula and untap
 uninstall-formula:

package/examples/full-example/scripts/formula-shared.ts

@@ -11,12 +11,12 @@ export const formulaInstallRuby = `def install
   end`;
 
 export const formulaPostInstallRuby = `def post_install
-    system bin/"${key}", "install", "--reinstall", "--yes"
+    system bin/"${key}", "configure", "--sync", "--yes"
   end`;
 
 export const formulaCaveatsRuby = `def caveats
     <<~EOS
-      Run \`${key} install --configure\` to set up app config (interactive).
+      Run \`${key} configure\` to set up agent artifacts and app config (interactive).
     EOS
   end`;