argsbarg 6.3.2 → 7.0.2

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.0.2] - 2026-08-13
+
+
+## [7.0.1] - 2026-08-13
+
+### Fixed
+
+- **`configure install` / `uninstall` / `status`** — skip the global required-`appConfig` gate so these subcommands reach their handlers (e.g. `configure uninstall` when config is incomplete).
+
+## [7.0.0] - 2026-08-13
+
+### Changed
+
+- **Breaking: `configure` subcommands** — replace flag modes with `configure install`, `configure uninstall`, and `configure status`. Bare `configure` shows help. Removed `--refresh`, `--remove-all`, `--remove-config`, and `--dry`. `--json` is only on `status` and `get`/`set`. `--yes` only on `uninstall` (skip TTY confirm).
+- **Breaking: configure hooks** — rename `afterRefresh` → `afterInstall`, `beforeRemoveAll` → `beforeUninstall` (no aliases).
+- **Breaking: Homebrew agent-artifact lifecycle** — drop formula `post_install` and `def uninstall` hooks (sandboxed / unsupported). Generated formulae use `caveats` with `configure install` and `configure uninstall`. `just install-local` runs install after brew; `just uninstall` runs uninstall first. New `just refresh` recipe in copy templates.
+- **MCP install idempotency** — `configure install` skips when an existing MCP entry matches; warns and skips on conflict (no overwrite).
+- **Configure output** — leaf install/uninstall functions print one line each; removed mutation summaries and progress noise.
+- **Capability-aware configure copy** — help text and caveats gate on `skill.enabled`, `mcpServer.enabled`, and non-empty `appConfig.entries`.
+- **Copy-template `argsbarg` bin shim** — `just setup` and `just consumers-dev` run `ln -sf` to fix Bun’s broken `node_modules/.bin/argsbarg` link for `file:` deps so `argsbarg schemagen` works.
+- **`argsbarg create` (json)** — post-create schemagen prepends the new project’s `node_modules/.bin` to `PATH` so it does not pick up a broken global `argsbarg`.
+
 ## [6.3.2] - 2026-08-07
 
 
@@ -22,12 +44,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- **`userHome()`** — resolves home from `TEST_USER_HOME` (tests) or platform defaults (`/Users/$USER`, `/home/$USER`, `USERPROFILE`). Never reads `$HOME`, fixing skills installing under Homebrew's `post_install` sandbox.
+- **`userHome()`** — resolve home from `TEST_USER_HOME` (tests) or platform defaults (`/Users/$USER`, `/home/$USER`, `USERPROFILE`). Never reads `$HOME`, fixing skills/MCP installing or failing to remove under Homebrew's `post_install` / `uninstall` sandbox.
 
 ### Changed
 
 - **Breaking: `configure --sync` → `configure --refresh`** — renames the non-interactive agent-artifact refresh flag (skills, MCP, config bootstrap). No `--sync` alias. Copy-template justfiles no longer ship a `refresh-artifacts` recipe; run `configure --refresh --yes` directly.
-- **Copy-template justfiles** — `install-local` depends on `uninstall` then `build` (`brew reinstall || brew install --force`). Dropped `uninstall-artifacts`, `uninstall-formula`, `uninstall-release`, and `uninstall-release-tap` (use `uninstall` + `uninstall-config`). Brew recipes prefix `HOMEBREW_NO_ASK=1`.
+- **Copy-template justfiles** — `install-local` depends on `uninstall` then `build`. Brew recipes prefix `HOMEBREW_NO_ASK=1`.
 
 ## [6.2.2] - 2026-08-07
 
@@ -925,7 +947,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/v6.3.2...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.2...HEAD
+[7.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.2
+[7.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.1
+[7.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.0
 [6.3.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.3.2
 [6.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.3.1
 [6.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.3.0

package/README.md

@@ -158,7 +158,7 @@ ArgsBarg automatically integrates several core features into your application. T
 ### Experimental Integrations (Opt-in)
 
 - `mcp` — Run as a Model Context Protocol stdio-based agent server (injected when `mcpServer.enabled` is `true`). See [docs/mcp.md](docs/mcp.md).
-- `configure` (`--refresh` / `--status` / `--remove-all`) — Interactive environment setup and developer agent credentials sync (enabled by default; opt out with `configure: { enabled: false }`). See [docs/configure.md](docs/configure.md).
+- `configure` (`install` / `uninstall` / `status`) — Agent artifact setup (enabled by default; opt out with `configure: { enabled: false }`). See [docs/configure.md](docs/configure.md).
 
 Do not declare top-level commands named `completion`, `version`, or `docs` as they are reserved by default. If their respective features are enabled, `http`, `mcp`, and `configure` are also reserved.
 
@@ -385,7 +385,7 @@ This refreshes the argsbarg-managed section in `AGENTS.md` while preserving your
 
 ### 3. Generated Skills & Workspace Configuration
 
-Running `myapp configure --refresh` installs a compact `SKILL.md` index and full-reference `reference.md` to `~/.agents/skills/<key>/` when `program.skill: { enabled: true }`.
+Running `myapp configure install` installs a compact `SKILL.md` index and full-reference `reference.md` to `~/.agents/skills/<key>/` when `program.skill: { enabled: true }`.
 
 See **[docs/configure.md](docs/configure.md)** and **[docs/ai-skills.md](docs/ai-skills.md)** for developer setup and automated Homebrew pipeline integration.
 

package/docs/README.md

@@ -9,10 +9,10 @@ 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 |
 | **JSON Schema validation** | [json-schema-subset.md](json-schema-subset.md) — Draft-07 / 2019-09 / 2020-12 (`$schema` on each schema; default Draft-07) |
-| **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `configure --refresh` |
+| **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `configure install` |
 | **HTTP tool server** | [http-server.md](http-server.md) — `myapp http`, endpoints, curl examples |
 | **Server logging** (`program.log`, `enrich`, `serialize`) | [logging.md](logging.md) — ECS JSON lines, trace headers, custom formats |
-| **Shipping configure / agent artifacts** | [configure.md](configure.md) — Homebrew + `myapp configure --refresh` |
+| **Shipping configure / agent artifacts** | [configure.md](configure.md) — Homebrew + `myapp configure install` |
 | **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) — `configure`, `docs skill` |

package/docs/ai-skills.md

@@ -14,17 +14,17 @@ export const program = {
 } satisfies CliProgram;
 ```
 
-When `skill.enabled` is `true`, Homebrew `post_install` (`configure --refresh --yes`) installs and refreshes the skill. When omitted or `enabled` is not `true`, no skill is installed.
+When `skill.enabled` is `true`, run `configure install` after `brew install` or `brew upgrade` to install and refresh the skill. When omitted or `enabled` is not `true`, no skill is installed.
 
 The skill directory name is the program `key` with `/`, `\`, and spaces replaced by `_` (e.g. `sqsp-qa`, `full-example`).
 
-## Install via `configure --refresh`
+## Install via `configure install`
 
 ```bash
-myapp configure --refresh --yes
+myapp configure install
 ```
 
-Skills are not prompted during interactive `configure` — install and uninstall are automatic when `skill.enabled` is set (brew install/uninstall and `--refresh` / `--remove-all`).
+Skills are installed via `configure install` and removed via `configure uninstall` (run `just install-local` / `just uninstall` in dev).
 
 ## Programmatic install
 
@@ -46,7 +46,7 @@ Installed files include an HTML comment hint (`Generated by myapp configure; do
 
 | Client | Skill path |
 | --- | --- |
-| Cursor, Codex, Copilot, most agents | `~/.agents/skills/<key>/` (auto via `configure --refresh`) |
+| Cursor, Codex, Copilot, most agents | `~/.agents/skills/<key>/` (auto via `configure install`) |
 | Claude Code | Manual symlink to `~/.claude/skills/<key>/` |
 
 ```bash
@@ -61,10 +61,10 @@ Skills describe **shell invocation only** — no MCP setup or `tools/call` guida
 | Mechanism | Role |
 | --- | --- |
 | **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`program.skill.enabled`** + **`configure --refresh`** | Persists optimized skill bundle at `~/.agents/skills/<key>/` |
+| **`program.skill.enabled`** + **`configure install`** | Persists optimized skill bundle at `~/.agents/skills/<key>/` |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
-`skill.md` is the routing index; `reference.md` matches `docs cli`. Prefer `configure --refresh` over `docs skill` for installed agents. See [cli-program.md](cli-program.md).
+`skill.md` is the routing index; `reference.md` matches `docs cli`. Prefer `configure install` over `docs skill` for installed 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 `configure`.
 

package/docs/bundled-docs.md

@@ -97,11 +97,11 @@ By default (unless `docs.enabled: false`):
 
 - **`docs cli-schema`** — same JSON as the former root `--schema` flag (handlers omitted; built-in subtrees included for leaf roots).
 - **`docs cli`** — markdown rendering of the same command tree (options, positionals, subcommands, fallback routing).
-- **`docs skill`** — prints the compact `SKILL.md` index. Prefer `configure --refresh --yes` for agents (persists index + full API in `reference.md`).
+- **`docs skill`** — prints the compact `SKILL.md` index. Prefer `configure install` for agents (persists index + full API in `reference.md`).
 
 ## MCP guide (`docs mcp`)
 
-When both docs (default) and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `program.appConfig`, schema resource URI, `configure --refresh`, and protocol notes.
+When both docs (default) and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `program.appConfig`, schema resource URI, `configure install`, and protocol notes.
 
 There is no override API in v1 — customize behavior via `mcpTool.description` on leaf commands.
 

package/docs/cli-program.md

@@ -541,9 +541,9 @@ 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 `configure get`/`set` skip this exit.
 - **MCP:** server stays up; missing config returns `isError: true` at `tools/call`.
-- **Configure:** interactive `configure` runs the app config wizard; **`configure --refresh`** refreshes agent artifacts to `~/.agents/` (see https://dotagentsprotocol.com). Optional `configure.afterRefresh` / `configure.beforeRemoveAll` for app-specific agent setup; see [configure.md](configure.md).
-- **Agent skill:** `program.skill: { enabled: true }` installs to `~/.agents/skills/<key>/` on `configure --refresh`; see [configure.md](configure.md) and [ai-skills.md](ai-skills.md).
-- **MCP install:** `mcpServer: { enabled: true }` merges into `~/.agents/mcp.json` on `configure --refresh`; manual Cursor/Claude setup in [mcp.md](mcp.md).
+- **Configure:** interactive `configure` runs the app config wizard; **`configure install`** refreshes agent artifacts to `~/.agents/` (see https://dotagentsprotocol.com). Optional `configure.afterInstall` / `configure.beforeUninstall` for app-specific agent setup; see [configure.md](configure.md).
+- **Agent skill:** `program.skill: { enabled: true }` installs to `~/.agents/skills/<key>/` on `configure install`; see [configure.md](configure.md) and [ai-skills.md](ai-skills.md).
+- **MCP install:** `mcpServer: { enabled: true }` merges into `~/.agents/mcp.json` on `configure install`; manual Cursor/Claude setup in [mcp.md](mcp.md).
 
 See [config-schema.md](config-schema.md) for codegen, [configure.md](configure.md) (`configure.targets`), and [mcp.md](mcp.md).
 
@@ -582,7 +582,7 @@ If you maintain argsbarg from a sibling checkout, `just consumers-dev` / `just c
 
 3. **Optional:** add consumer-specific sections above the `<!-- argsbarg:managed -->` marker in `AGENTS.md` (project context, Ink patterns, domain notes).
 
-- **Not this file:** `myapp configure --refresh` writes the **app** skill (`SKILL.md` under `~/.agents/skills/<key>/`) from your command schema — how to *invoke* the CLI. `AGENTS.md` is for *authoring* argsbarg schema.
+- **Not this file:** `myapp configure install` writes the **app** skill (`SKILL.md` under `~/.agents/skills/<key>/`) from your command schema — how to *invoke* the CLI. `AGENTS.md` is for *authoring* argsbarg schema.
 
 ## See also
 

package/docs/configure.md

@@ -13,92 +13,86 @@ Private GitHub release downloads require [GitHub CLI](https://cli.github.com/) a
 ```bash
 brew tap <org>/<repo> git@github.com:<org>/<repo>.git
 brew install <tap>/<key>
-<key> configure    # interactive: per-target prompts; run when app config is required
+<key> configure install   # skills, MCP, config bootstrap; required-config wizard on TTY
 ```
 
-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).
+Upgrade with `brew upgrade <key>`, then run `<key> configure install` again. 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:**
+**Uninstall:**
 
 ```bash
+<key> configure uninstall
 brew uninstall <tap>/<key>
 ```
 
-`brew uninstall` runs the formula `uninstall` hook (`configure --remove-all --yes`), which removes detected skills, MCP entries, and app config while the binary is still on PATH.
-
-To remove app config only (keep skills/MCP), run `configure --remove-config --yes` before uninstall.
+Run `configure uninstall` **before** `brew uninstall` while the binary is still on PATH. Homebrew does not run cleanup hooks for agent artifacts in `~/.agents`.
 
 ## Developer install
 
 ```bash
 just build
-just install-local    # uninstall, then build + brew install (`just install` is an alias)
+just install-local    # uninstall, build, brew install, configure install (`just install` is an alias)
 ```
 
-Dev flow matches release: `install-local` runs `uninstall` first (keg + untap; formula hook runs `configure --remove-all`), then stages the dev formula and installs. `post_install` runs `<key> configure --refresh --yes` for skills/MCP. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles (skips completions and `post_install`). Run `<key> configure --refresh --yes` (or `just run configure --refresh --yes`) to refresh agent artifacts without touching the binary.
+`just install-local` runs `configure uninstall` (via `just uninstall`), installs via Homebrew, then `configure install`. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles; run `just refresh` afterward for skills/MCP.
 
 ## Quick reference
 
 ```bash
-# Refresh skills/MCP after upgrade (Homebrew post_install runs this automatically)
-<key> configure --refresh --yes
+# Install skills/MCP after install or upgrade (required — not run by Homebrew)
+<key> configure install
 
 # See what is installed
-<key> configure --status
-
-# Interactive per-target setup (default when run with a TTY)
-<key> configure
+<key> configure status [--json]
 
-# Remove all agent artifacts
-<key> configure --remove-all --yes
+# Remove all agent artifacts and app config (run before brew uninstall)
+<key> configure uninstall [--yes]
 
-# Remove app config only (not skills/MCP)
-<key> configure --remove-config --yes
-
-# Read or write app config (non-interactive; when program.appConfig is set)
+# Read or write app config (when program.appConfig is set)
 <key> configure get [key] [--json] [--pretty]
 <key> configure set <key> <value> [--json] [--from-env]
 ```
 
-Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--refresh`**, **`--remove-all`**, **`--remove-config`**) — see [Confirmation](#confirmation).
+Bare `<key> configure` (no subcommand) shows help. Use subcommands above.
 
 ## What gets configured
 
-| Target | Interactive | Mechanism |
+| Target | `configure install` | Mechanism |
 | --- | --- | --- |
 | Binary | skipped (read-only) | Homebrew formula `bin.install` |
 | Shell completions | skipped | Homebrew `generate_completions_from_executable` |
-| Agent skill | skipped (automatic) | `~/.agents/skills/<key>/` when `program.skill.enabled` |
-| MCP config | skipped (automatic) | `~/.agents/mcp.json` when `mcpServer.enabled` (see https://dotagentsprotocol.com) |
-| App config | auto-runs wizard | Interactive wizard may update `~/.local/lib/<key>/config.json` when values change; `--refresh` bootstraps an empty file on install |
+| Agent skill | automatic | `~/.agents/skills/<key>/` when `program.skill.enabled` |
+| MCP config | automatic | `~/.agents/mcp.json` when `mcpServer.enabled` (see https://dotagentsprotocol.com) |
+| App config | bootstrap + wizard | Creates `~/.local/lib/<key>/config.json` as `{}` when missing; TTY wizard when required keys are missing |
 
 ### 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)`
-- **`configure --refresh`** refreshes the agent skill (when `program.skill.enabled`) and merges MCP into `~/.agents/mcp.json` (when `mcpServer.enabled`); also creates `~/.local/lib/<key>/config.json` as `{}` when missing (all apps)
+- **`configure status`** shows `app: system (PATH)`
+- **`configure install`** refreshes the agent skill (when `program.skill.enabled`) and registers MCP in `~/.agents/mcp.json` (when `mcpServer.enabled`); bootstraps `config.json` when missing
 
 MCP config uses the command name on **`PATH`**, not a Cellar path. For Cursor, Claude Code, and Claude Desktop, copy the `mcpServers` entry manually — see [mcp.md](mcp.md) and `docs mcp`.
 
-### Interactive default
+### Required-config wizard
 
-Bare **`configure`** (TTY required) runs the app config wizard when `program.appConfig` has entries. Agent skills and MCP are **not** prompted — they install automatically via brew `post_install` / `--refresh` when `program.skill.enabled` or `mcpServer.enabled` respectively.
+On **`configure install`**, when `program.appConfig` has entries and required keys are still missing after env resolution:
 
-Remove the config file with **`configure --remove-config --yes`**.
+- **TTY:** runs the config wizard (required keys only; Enter keeps current values)
+- **Non-TTY:** exits with an error listing missing keys
 
-The **`app`** and **`skill`** / **`agentsMcp`** targets are shown in `--status` only — never mutated by interactive `configure` (use `--refresh` / brew hooks).
+Optional keys are set via `configure set` or environment variables.
 
 ### `configure.targets`
 
-Optional gates for app binary status and app-config wizard participation in `--refresh`:
+Optional gates for app binary status:
 
 ```typescript
 skill: { enabled: true },
 mcpServer: { enabled: true },
 configure: {
   targets: {
-    configure: { includedInAll: true }, // optional: app config wizard on --refresh
+    configure: { includedInAll: true },
   },
 },
 ```
@@ -109,16 +103,14 @@ Artifact keys: `app`, `configure`. Legacy `configure.targets.*Mcp` keys are reje
 
 ### Lifecycle hooks
 
-Optional callbacks on `program.configure` for app-specific agent setup beyond the `.agents` protocol (e.g. Cursor or Claude Desktop config). Framework artifacts are installed/refreshed first; hooks extend or retract custom files.
+Optional callbacks on `program.configure` for app-specific agent setup beyond the `.agents` protocol (e.g. Cursor or Claude Desktop config).
 
 ```typescript
 configure: {
-  afterRefresh: async (ctx) => {
-    if (ctx.dry) return;
+  afterInstall: async (ctx) => {
     // e.g. symlink skill, merge Cursor mcp.json — ctx.paths has agentsSkillDir, agentsMcpPath, mcpName
   },
-  beforeRemoveAll: async (ctx) => {
-    if (ctx.dry) return;
+  beforeUninstall: async (ctx) => {
     // undo custom installs before framework removes ~/.agents/ artifacts
   },
 },
@@ -126,83 +118,63 @@ configure: {
 
 | Hook | When |
 | --- | --- |
-| `afterRefresh` | After `configure --refresh` installs framework artifacts |
-| `beforeRemoveAll` | Before `configure --remove-all` removes framework artifacts (not `--remove-config`) |
+| `afterInstall` | After `configure install` installs framework artifacts |
+| `beforeUninstall` | Before `configure uninstall` removes framework artifacts |
 
 ## App config (`program.appConfig`)
 
-Every app gets `~/.local/lib/<sanitized-key>/config.json` on first **`configure --refresh`** (Homebrew `post_install`), even without `program.appConfig`.
+Every app gets `~/.local/lib/<sanitized-key>/config.json` on first **`configure install`**, even without `program.appConfig`.
 
 When `program.appConfig` is set, ArgsBarg manages schema-driven values in that file.
 
 | Mode | Description |
 | --- | --- |
-| `configure --refresh` | Bootstraps `config.json` as `{}` when missing |
-| Interactive `configure` | Config wizard when `entries` is non-empty; re-prompts every entry (Enter keeps current); writes only when values or `_bindings` change |
-| `--status` | Shows config path, required keys (`set` / `missing`), and binding hints (`env`, `file`, `skip`) |
-| `--remove-config --yes` | Removes the config directory |
+| `configure install` | Bootstraps `config.json` as `{}` when missing; wizard for missing required keys on TTY |
+| `configure status` | Shows config path, required keys (`set` / `missing`), and binding hints (`env`, `file`, `skip`) |
+| `configure uninstall` | Removes the config directory |
 | `configure set --from-env` | Bind a key to its mapped env var (stores `_bindings`, no literal secret) |
 
-Per-key intent is stored under the reserved `_bindings` object (e.g. `"apiToken": "env"`). Env still wins at resolve time when set; bindings record user choice. CLI startup only prompts for missing required keys; interactive `configure` re-prompts all entries.
+Per-key intent is stored under the reserved `_bindings` object (e.g. `"apiToken": "env"`). Env still wins at resolve time when set; bindings record user choice.
 
 Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
 
-## Flags
-
-### Operation flags
+## Subcommands
 
-| Flag | Description |
+| Subcommand | Description |
 | --- | --- |
-| `--status` | Read-only inventory |
-| `--refresh` | Refresh installed agent artifacts; bootstrap `config.json` when missing (Homebrew `post_install`; greenfield → full install 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 (`--refresh`, `--remove-all`, `--remove-config`) require **`--yes`** unless `--dry`.
+| `install` | Install agent artifacts; bootstrap config; required-config wizard on TTY |
+| `uninstall` | Remove skill, MCP entry, and app config (`--yes` skips TTY confirm) |
+| `status` | Read-only inventory (`--json` for machine output) |
+| `get` / `set` | Read or write `program.appConfig` keys (when configured) |
 
 ## MCP merge behavior
 
-When MCP targets are installed, entries are merged into host config with:
+When MCP is enabled, `configure install` writes:
 
 ```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", "--refresh", "--yes"
-end
-```
-
-This refreshes skills/MCP without running the configure wizard (app config is opt-in via interactive `configure`).
+If an existing entry matches, install is a no-op. If an existing entry differs, install skips and prints a warning (existing entry is left unchanged).
 
-## Formula `uninstall`
+## Formula `caveats`
 
-Release formulae should run:
+Generated formulae document the two-step install when the app has skills, MCP, or `appConfig` entries. Homebrew prints `caveats` after `brew install` and in `brew info`:
 
 ```ruby
-def uninstall
-  system bin/"myapp", "configure", "--remove-all", "--yes"
+def caveats
+  <<~EOS
+    After install or upgrade:
+      myapp configure install
+
+    Before uninstall:
+      myapp configure uninstall
+      brew uninstall <tap>/myapp
+  EOS
 end
 ```
 
-Removes detected skills, MCP entries, and app config while the binary is still on PATH. Safe no-op when nothing was installed.
+Do **not** use `post_install` or `def uninstall` for agent artifacts — Homebrew sandboxes `post_install` and does not invoke formula `uninstall` hooks.
 
 ## Bootstrapping a new CLI
 

package/docs/developing.md

@@ -36,7 +36,7 @@ Sibling consumer repos (machine-specific paths in the root `justfile` `consumer_
 
 | Recipe | When | Effect |
 | --- | --- | --- |
-| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `AGENTS.md` from template (keeps app-specific prefix and conventions footer) |
+| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; fix `.bin/argsbarg` symlink; refresh `AGENTS.md` from template (keeps app-specific prefix and conventions footer) |
 | `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge `AGENTS.md`, `just build`, `just docgen`, `just install-local` (Homebrew dev formula + agent artifacts; `just install` is an alias) |
 | `just consumers-schemagen` | After `@sg` type changes in consumers | Runs `argsbarg schemagen` in each `consumer_apps` path (fails if missing) |
 
@@ -59,7 +59,7 @@ Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unr
 7. **Agent instructions:** `just consumers-dev` merges `AGENTS.md` + `CLAUDE.md` (includes **Abstractions** needless-extraction rule).
 8. **Verify:** `just test` and `just docgen` in each consumer repo.
 
-**Consumer app skill** — `just install-local` in each consumer (part of `consumers-sync`) runs Homebrew dev install then `myapp configure --refresh --yes`, which updates `~/.agents/skills/<app>/` when `program.skill.enabled` — 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 install`, which updates `~/.agents/skills/<app>/` when `program.skill.enabled` — not the argsbarg framework rule.
 
 ## npm package contents
 
@@ -71,7 +71,7 @@ Exclude `examples/full-example/node_modules/` and `examples/full-example-json/no
 
 ## Copy templates
 
-Both [`examples/full-example/`](../examples/full-example/) (CLI) and [`examples/full-example-json/`](../examples/full-example-json/) (schema-first) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
+Both [`examples/full-example/`](../examples/full-example/) (CLI) and [`examples/full-example-json/`](../examples/full-example-json/) (schema-first) use `argsbarg: file:../..` in-repo; `just setup` fixes the Bun `.bin/argsbarg` symlink so `argsbarg schemagen` works. They must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
 
 ```bash
 just example-full-check

package/docs/distribution-homebrew.md

@@ -6,16 +6,16 @@ ArgsBarg provides native, first-class support for packaging, releasing, and dist
 
 ## 1. Enterprise Distribution Model
 
-ArgsBarg maps the lifecycle of your application directly to standard Homebrew hooks, separating binary installation from user-interactive environment setup.
+Homebrew installs the **binary and shell completions** into the prefix. **Agent artifacts** (skills, MCP, app config) live under the user's home directory and are installed by the app's `configure` command — Homebrew's sandbox does not allow formula hooks to write there.
 
 | Layer | Mechanism | Role in Lifecycle |
 | --- | --- | --- |
 | **Binary & Autocompletions** | Formula `install` block | Installs compiled binary and registers native shell autocompletions. |
-| **Agent artifacts** | Formula `post_install` | Automatically runs `{key} configure --refresh --yes` to bootstrap configuration files and refresh agent artifacts. |
-| **Application Configuration** | User-facing `{key} configure` | Runs an interactive TTY setup wizard (only when `program.appConfig` defines required parameters). |
-| **Clean Uninstall** | Formula `uninstall` | Automatically runs `{key} configure --remove-all --yes` to clean up local configurations and symlinks. |
+| **Agent artifacts** | `{key} configure install` | User- or script-run after `brew install` / `brew upgrade`; installs skills/MCP and bootstraps `config.json`. |
+| **Application Configuration** | `{key} configure install` | Required-config wizard on TTY when `program.appConfig` defines required parameters. |
+| **Clean Uninstall** | `{key} configure uninstall` then `brew uninstall` | Removes `~/.agents` artifacts and app config; must run **before** uninstall while the binary is still on PATH. |
 
-*Note: This architecture explicitly separates non-interactive installation (safe for automation/CI) from interactive configuration (which requires a TTY).*
+*Note: `just install-local` runs both steps for developers. End users see the commands in formula `caveats` and `brew info`.*
 
 ---
 
@@ -33,6 +33,9 @@ brew tap <org>/<repo>
 
 # Install the application
 brew install <tap>/{key}
+
+# Install agent artifacts (skills, MCP, config bootstrap)
+{key} configure install
 ```
 
 The generated Homebrew formula points directly to your public GitHub release asset URL, allowing anyone to install and receive automatic updates securely.
@@ -53,8 +56,8 @@ gh auth login
 brew tap <org>/<repo> git@github.com:<org>/<repo>.git
 brew install <tap>/{key}
 
-# 3. Perform interactive configuration (such as API tokens) if required
-{key} configure
+# 3. Install agent artifacts (and required-config wizard on TTY when needed)
+{key} configure install
 ```
 
 #### 2. The Private Release Strategy:
@@ -85,20 +88,14 @@ class Myapp < Formula
     generate_completions_from_executable(bin/"myapp", "completion", base_name: "myapp")
   end
 
-  def post_install
-    # Non-interactive bootstrap of config files and developer links
-    system bin/"myapp", "configure", "--refresh", "--yes"
-  end
-
-  def uninstall
-    # Graceful clean up of local files on uninstall
-    system bin/"myapp", "configure", "--remove-all", "--yes"
-  end
-  
   def caveats
     <<~EOS
-      Interactive configuration is required. Please run:
-        myapp configure
+      After install or upgrade:
+        myapp configure install
+
+      Before uninstall:
+        myapp configure uninstall
+        brew uninstall <tap>/myapp
     EOS
   end
 end
@@ -116,13 +113,13 @@ ArgsBarg provides an optimized workflow for developers to build, package, and te
 # 1. Build the local release binary
 just build
 
-# 2. Uninstall any existing formula/tap, stage and install locally (bypasses GitHub, uses file://)
+# 2. Uninstall any existing formula/tap, stage and install locally, refresh agent artifacts
 just install-local
 
-# 3. Swap updated binaries quickly during tight edit cycles
+# 3. Swap updated binaries quickly during tight edit cycles (run `just refresh` for skills/MCP)
 just reinstall-local
 
-# 4. Uninstall the binary and gracefully clean up all configurations
+# 4. Remove agent artifacts, uninstall the binary, and untap
 just uninstall
 ```
 
@@ -130,10 +127,11 @@ just uninstall
 
 To ensure you test the exact formula that will be shipped to production, `just install-local` runs:
 
-1.  `just uninstall` — Remove any existing keg and untap (formula `uninstall` hook runs `configure --remove-all`).
+1.  `just uninstall` — `configure uninstall` (when possible), then remove keg and untap.
 2.  `bun scripts/dev-formula.ts install` — Safely backs up your production formula and writes a temporary local dev formula using a `file://` URL pointing to your build directory.
 3.  `brew reinstall || brew install --force` — Installs the package locally using Homebrew.
 4.  `bun scripts/dev-formula.ts reset` — Automatically restores your production formula on disk.
+5.  `{key} configure install` — Installs skills/MCP into `~/.agents` (outside Homebrew's sandbox).
 
 ---
 
@@ -170,4 +168,5 @@ just release --purge --dry-run    # Preview list of tag deletions
 
 Applications packaged via ArgsBarg adhere to standard system directories:
 *   **Resolved Configuration Path**: `~/.local/lib/<sanitized-key>/config.json`
+*   **Agent skill path**: `~/.agents/skills/<key>/`
 *   **Auto-Exports**: Developers can import `resolveAppConfigPath` or `displayAppConfigPath` directly from `argsbarg` to display helpful directories in help screens.

package/docs/mcp.md

@@ -46,10 +46,10 @@ bun run examples/nested.ts mcp
 
 ### `.agents` auto-install
 
-When `mcpServer.enabled` is set, `configure --refresh` merges a `mcpServers` entry into `~/.agents/mcp.json` per the https://dotagentsprotocol.com:
+When `mcpServer.enabled` is set, `configure install` merges a `mcpServers` entry into `~/.agents/mcp.json` per the https://dotagentsprotocol.com:
 
 ```bash
-myapp configure --refresh --yes
+myapp configure install
 ```
 
 ### Manual client setup
@@ -381,7 +381,7 @@ The bundled `SKILL.md` is an **MCP routing stub** — it tells Claude to use the
 
 Load locally with `claude --plugin-dir ./dist/claude-plugin/myapp.zip`.
 
-Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `configure` MCP targets and MCP hosts). Use **`configure --refresh --yes`** 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 install`** for Cursor, Claude Code, Claude Desktop, and OpenCode JSON config.
 
 ## Hidden commands and options
 

package/examples/full-example/Formula/full-example.rb

@@ -10,17 +10,15 @@ class FullExample < Formula
     generate_completions_from_executable(bin/"full-example", "completion", base_name: "full-example")
   end
 
-  def post_install
-    system bin/"full-example", "configure", "--refresh", "--yes"
-  end
-
-  def uninstall
-    system bin/"full-example", "configure", "--remove-all", "--yes"
-  end
-
   def caveats
     <<~EOS
-      Run `full-example configure` to set up agent artifacts and app config (interactive).
+      After install or upgrade:
+        full-example configure install
+
+      Before uninstall:
+        full-example configure uninstall
+        brew uninstall <tap>/full-example
+
       Restart MCP chat apps (Cursor, Claude Desktop, etc.) after install or upgrade so they load the updated server.
     EOS
   end