argsbarg 4.0.3 → 4.1.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.1.0] - 2026-07-01
+
+### Added
+
+- **Install bootstrap** — bare `myapp` (empty argv, TTY, binary not on PATH) rewrites to `myapp install`.
+- **Interactive install banner** — TTY install/uninstall prints `{app} Setup` before the numbered plan; config wizard uses `Configuration Setup`.
+- **Config file** — path is `~/.local/lib/<sanitized-key>/config.json`. Configure wizard writes accepted values (including Enter to copy from env) to the file.
+- **`install.targets`** — `InstallTargetSpec` per artifact; `install.agentIntegration` for MCP vs skill defaults.
+- **Agent install targets** — `codexSkill`, `opencodeSkill`, `openclawSkill`, `openclawMcp`.
+- **Install status JSON** — `install --status --json` includes `agentIntegration` and `effective` target preview.
+- **`mcpServer.mcpd`** — opt-in Claude Desktop `.mcpb` from `mcp bundle` (default off).
+- **`mcpServer.claudePlugin`** — opt-in Claude Code plugin zip from `mcp bundle` (default off).
+
+### Changed
+
+- **Sensitive config prompts** — `sensitive: true` entries disable terminal echo (raw-mode read with `*` feedback); Ctrl+C exits as usual.
+- **Breaking: `install --all`** — includes agent targets per `agentIntegration` (skills when MCP off, MCP when `mcpServer.enabled`); not both for the same host unless `both`.
+- **Scoped `--skill` / `--mcp`** — install only targets enabled by `agentIntegration` + `install.targets`, not every host in the category.
+- **Breaking: `--config` removed** — use **`--configure`** (install = wizard; uninstall = remove config directory).
+- **Breaking: `program.appConfig.path` removed** — config file is always `~/.local/lib/<sanitized-key>/config.json`.
+- **Breaking: `--quiet` removed** from `install`.
+- **Breaking: `--prefix` removed** — app always installs to `~/.local/bin/<key>`.
+- **Breaking: `install.prefix` and `INSTALL_PREFIX` removed** — custom install locations are not supported.
+- **Breaking: `--reinstall` / `--update`** — refresh detected artifacts in effective target scope (not bin-only).
+- **Breaking: `mcp bundle`** — writes artifacts only when `mcpServer.mcpd` and/or `mcpServer.claudePlugin` is true (both default off).
+- **Breaking: bare `install --uninstall`** — equivalent to `--uninstall --all` (removes all detected artifacts; ignores `install.targets`).
+- **Claude plugin zip** — `plugin.json` includes `"mcpServers": ".mcp.json"` so Claude Desktop/Code load the bundled MCP server; `bin/<key>` retains executable permissions in the zip.
+
+## [4.0.4] - 2026-06-25
+
+### Added
+
+- **MCP docs topic resources** — when `docs.enabled` and `mcpServer.enabled`, each user `docs.topics` key is auto-exposed as `<mcpId>://docs/<topicKey>` (`text/markdown`, same body as `myapp docs <topic>`). Built-in `docs schema` / `api` / `skill` / `mcp` are not auto-exposed.
+
+### Changed
+
+- **Claude Code plugin skill** — `mcp bundle` plugin zip includes an MCP routing `SKILL.md` only (no shell catalog, no `reference.md`). `install --skill` unchanged.
+- **Validation** — `mcpServer.resources` URIs that collide with auto docs topic resources are rejected at schema validation time.
+
 ## [4.0.3] - 2026-06-24
 
 
@@ -458,7 +497,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.0.3...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v4.1.0...HEAD
+[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
 [4.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.2
 [4.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.1

package/README.md

@@ -6,7 +6,7 @@
 [![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)
 
-Build beautiful, well-behaved CLI apps with Bun — **no third-party runtime dependencies**. 
+Build beautiful, well-behaved CLI+MCP apps with Bun — **no third-party runtime dependencies**. 
 
 Why another CLI parser?
 
@@ -16,7 +16,7 @@ Why another CLI parser?
 
 *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.
 
-*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 binaries can install binary, completions, skills, and MCP config with `myapp install` — see [docs/install.md](docs/install.md).
+*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).
 
 *Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
@@ -100,7 +100,7 @@ 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`** — install the binary, completions, skills, and MCP config to the user environment (`myapp install --all --yes`). See [docs/install.md](docs/install.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.
@@ -118,10 +118,10 @@ See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom
 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:
 
 ```bash
-myapp install --all --yes
+myapp install --yes
 ```
 
-This copies the binary to `~/.local/bin`, installs shell completions (bash/zsh/fish when each shell is on PATH), writes Cursor/Claude skills when agent directories exist, and merges MCP server entries into Cursor and Claude config files.
+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.
 
@@ -161,7 +161,7 @@ Add app-specific conventions in a second rule if needed. Copy the rule from the
 
 ## How it works
 
-1. Build a **program root** with `satisfies CliProgram` (or `: CliProgram`): `key` is the app/binary 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).
+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**.
 

package/docs/ai-skills.md

@@ -8,14 +8,17 @@ Install skills to the user environment:
 
 ```bash
 myapp install --skill --yes
-# or
-myapp install --all --yes
+# or bare install when agentIntegration defaults to skill:
+myapp install --yes
 ```
 
-Skills are written when the agent home exists:
+Skills are written when the agent home or CLI exists:
 
 - Cursor: `~/.cursor/skills/<dir>/` when `~/.cursor` exists
 - Claude Code: `~/.claude/skills/<dir>/` when `~/.claude` exists
+- Codex: `~/.codex/skills/<dir>/` when `codex` is on PATH
+- OpenCode: `~/.config/opencode/skills/<dir>/`
+- OpenClaw: `~/.openclaw/skills/<dir>/` when `openclaw` is on PATH
 
 The skill directory name defaults to the sanitized program `key` (e.g. `minimal.ts` → `minimal_ts`).
 
@@ -48,8 +51,10 @@ Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tool
 
 `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).
 
+**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.
+
 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) — binary, completions, skills, and MCP config
+- [Install](install.md) — app, completions, skills, and MCP config

package/docs/bundled-docs.md

@@ -104,6 +104,7 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 | `docs api` | Print command tree markdown to stdout |
 | `docs schema` | Print command tree JSON to stdout |
 | `docs` | Bundled markdown topics on stdout |
+| MCP docs topic resources | User `docs.topics` on the MCP wire (`<mcpId>://docs/<topic>`) when docs + MCP enabled |
 | `mcp` | Callable tools + schema resource |
 
 Do not declare a top-level command named **`docs`** when `docs.enabled` is `true` — it is reserved.

package/docs/cli-program.md

@@ -385,7 +385,6 @@ const program = {
   version: "1.0.0",
   description: "…",
   appConfig: {
-    path: "~/.config/myapp/config", // optional override
     jsonSchema: APP_CONFIG_JSON_SCHEMA, // optional; omit for all-string mode
     entries: {
       apiToken: {
@@ -427,11 +426,12 @@ 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:** `myapp install --configure` (not part of `--all`).
+- **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).
 
-See [config-schema.md](config-schema.md) for codegen, [install.md](install.md), and [mcp.md](mcp.md).
+See [config-schema.md](config-schema.md) for codegen, [install.md](install.md) (`install.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; `dir` is its parent directory (both honor `program.appConfig.path` when set, otherwise the OS default from `program.key`).
+**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
 

package/docs/config-schema.md

@@ -63,7 +63,6 @@ export interface CliAppConfigEntry {
 }
 
 export interface CliAppConfig {
-  path?: string;        // default: ~/.config/<key>/config (OS rules)
   commands?: boolean | { enabled?: boolean; mcpSet?: boolean };
   jsonSchema?: Record<string, unknown>;  // draft-07 block schema
   entries: Record<string, CliAppConfigEntry>;
@@ -78,7 +77,7 @@ export interface CliAppConfig {
 
 ## Config file shape
 
-Flat JSON at `config.path` (default OS path unchanged):
+Flat JSON at `~/.local/lib/<sanitized-key>/config`:
 
 ```json
 {
@@ -188,5 +187,3 @@ Object/array/`$ref` properties require `--json` on `config set`.
 cd examples/consumer-app && bun install && bun run schemagen
 CONSUMER_APP_API_TOKEN=dev bun run start config get apiToken --json
 ```
-
-Set `CONSUMER_APP_CONFIG_FILE` to override the config file path.

package/docs/developing.md

@@ -32,7 +32,7 @@ Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile
 
 | Recipe | When | Effect |
 | --- | --- | --- |
-| `just consumer-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` from template (keeps app-specific suffix) |
+| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` from template (keeps app-specific suffix) |
 | `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **argsbarg Cursor rule**, `just build`, `just docgen`, `just install` (consumer app binary, completions, and **app** skill) |
 
 `consumers-sync` reads the version from **this repo’s** `package.json` — not npm. Run it **after** `just release` so consumers pin a version that exists on the registry.

package/docs/install.md

@@ -1,44 +1,149 @@
 # Install command
 
-The `install` built-in installs the binary, shell completions, agent skills, and MCP config. Opt out with `install: { enabled: false }` on the program root.
+The `install` built-in installs the app, shell completions, agent skills, and MCP config. Opt out with `install: { enabled: false }` on the program root.
 
-## Quick start
+## End-user install
+
+Ship a compiled binary (or app bundle). Users install interactively — no `--yes` required when stdin is a TTY:
+
+- **Terminal:** run `./myapp`, `myapp`, or `myapp install` (bare `install` is equivalent to `--all`).
+- **macOS app:** double-click the `.app`; when the binary is not yet on PATH and stdin is a TTY, launching with no arguments bootstraps to **`myapp install`**.
+
+Interactive flow prints a **`{app} Setup`** banner, a numbered plan, and a confirm prompt. When the app needs API keys or other settings, a **`Configuration Setup`** section runs after install (or immediately for **`install --configure`**).
+
+**Uninstall is CLI-only** — there is no GUI uninstaller. Users run:
+
+```bash
+myapp install --uninstall          # remove all detected artifacts
+myapp install --uninstall --app    # scoped removal
+```
+
+Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--reinstall`**, **`--update`**) — see [Confirmation](#confirmation).
+
+## Quick start (automation)
 
 ```bash
-# First-time setup
+# First-time setup (bare `install` is equivalent to `--all`)
+myapp install --yes
+
+# Or explicitly
 myapp install --all --yes
 
-# Refresh after upgrading (re-copy running binary + refresh installed artifacts)
+# Refresh after upgrading (re-copy running app + refresh detected artifacts in scope)
 myapp install --reinstall
 
-# Upgrade to latest release (when install.updateGetLatest is configured)
+# Upgrade to latest release (when this app supports remote updates)
 myapp install --update
 
 # See what is installed
 myapp install --status
 
-# Remove everything installed with --all
-myapp install --uninstall --all --yes
+# Remove everything detected on disk (bare `install --uninstall` is equivalent to `--uninstall --all`)
+myapp install --uninstall --yes
 ```
 
 ## What gets installed
 
 | Target | Flag | Destination |
 | --- | --- | --- |
-| Binary | `--bin` | `~/.local/bin/<key>` (or `--prefix`) |
+| App | `--app` | `~/.local/bin/<key>` |
 | Bash completion | `--completions` | `~/.bash_completion.d/<key>` + `.bashrc` PATH snippet |
 | Zsh completion | `--completions` | `~/.zsh/completions/_<key>` + `.zshrc` fpath snippet |
 | Fish completion | `--completions` | `~/.config/fish/completions/<key>.fish` |
 | Cursor skill | `--skill` | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
 | Claude skill | `--skill` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
-| MCP config | `--mcp` | Cursor, Claude Code/Desktop, OpenCode (`~/.config/opencode`), Codex (`codex` on PATH), ChatGPT desktop (when app data exists). ChatGPT web uses Connectors — see `docs mcp` |
-| App config | `--config` | JSON config file for `program.appConfig` (with `--uninstall`; included in `--uninstall --all`) |
+| Codex / OpenCode / OpenClaw skills | `--skill` | Agent-specific dirs when the agent home or CLI is available |
+| MCP config | `--mcp` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop (when app data exists). ChatGPT web uses Connectors — see `docs mcp` |
+| App config | `--configure` | Interactive wizard writes app settings; `--uninstall --configure` removes the file |
+
+### Default `--all` behavior
+
+Bare **`install`** and **`install --all`** install targets with **`includedInAll: true`**. Core defaults:
+
+- **Always included:** `app`, `completions`, `configure` (wizard when `program.appConfig` is set)
+- **Agent integration** (`install.agentIntegration`, default from `mcpServer.enabled`):
+  - **`skill`** (default when MCP off): all `*Skill` keys in `--all`; paired `*Mcp` keys excluded
+  - **`mcp`** (default when `mcpServer.enabled`): all `*Mcp` keys in `--all`; paired skills excluded
+  - **`both`**: MCP and skill for the same host when available
+
+Desktop-only MCP hosts (`claudeDesktopMcp`, `chatgptMcp`) follow the MCP side only — no skill pair.
+
+Scoped flags (`--app`, `--completions`, `--configure`) run that artifact category. **`--skill`** and **`--mcp`** install only targets enabled by `agentIntegration` and per-key `install.targets`. Honor `enabled: false` as a hard off.
+
+Use **`install --status --json`** to preview effective targets (`effective.all`, `effective.mcp`, `effective.skill`) before installing.
+
+### Asymmetric uninstall
+
+- **`install --uninstall --all`** (including bare **`install --uninstall`**) removes **every detected artifact type**, ignoring `install.targets`.
+- Scoped uninstall (`--app`, `--skill`, …) removes only that category.
+
+Missing targets are skipped silently (no error if nothing is on disk or a shell/agent directory does not exist). Shells not on PATH are skipped silently (no warnings).
+
+## `install.targets`
+
+Configure which artifacts participate in `--all`, `--reinstall`, and `--update`:
+
+```typescript
+install: {
+  agentIntegration: "mcp", // | "skill" | "both" — default from mcpServer.enabled
+  targets: {
+    app: { includedInAll: false },
+    chatgptMcp: false,
+    cursorSkill: { includedInAll: true },
+  },
+},
+```
+
+`InstallTargetSpec` is `boolean` or `{ enabled?: boolean; includedInAll?: boolean }`. Shorthand `true` enables the target with default `includedInAll`; `false` disables it.
+
+Artifact keys: `app`, `chatgptMcp`, `claudeCodeMcp`, `claudeDesktopMcp`, `claudeSkill`, `codexMcp`, `codexSkill`, `completions`, `configure`, `cursorMcp`, `cursorSkill`, `openclawMcp`, `openclawSkill`, `opencodeMcp`, `opencodeSkill`.
+
+Conflicting targets (e.g. both `cursorMcp` and `cursorSkill` without `agentIntegration: 'both'`) fail at program validation time.
+
+## Examples
+
+### MCP CLI (default)
+
+```typescript
+const program = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "…",
+  mcpServer: { enabled: true },
+  install: {}, // agentIntegration defaults to "mcp"
+  // …
+} satisfies CliProgram;
+```
+
+Bare **`myapp install --yes`** installs the app, completions, configure wizard (when `appConfig` is set), and MCP hosts — not shell skills for paired agents.
 
-`--all` expands to `--bin`, `--completions`, `--skill`, and `--mcp` (when `mcpServer.enabled` is `true`) for both install and uninstall. Missing targets are skipped silently (no error if nothing is on disk or a shell/agent directory does not exist).
+### Shell-only CLI (default)
 
-`install --uninstall` requires the same target flags as install (`--all`, `--bin`, etc.) — bare `--uninstall` alone is an error.
+```typescript
+const program = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "…",
+  install: {}, // agentIntegration defaults to "skill"
+  // …
+} satisfies CliProgram;
+```
+
+Bare install includes agent skills (when each host is available), not MCP config.
+
+### Overrides
+
+```typescript
+install: {
+  agentIntegration: "both", // MCP + skill on the same host
+  targets: {
+    chatgptMcp: false, // opt out of one MCP host
+    app: { includedInAll: false }, // skip app on --all
+  },
+},
+```
 
-Shells not on PATH are skipped silently (no warnings).
+Preview resolved targets: **`myapp install --status --json`**.
 
 ## Configuration
 
@@ -47,19 +152,18 @@ On the program root:
 ```typescript
 install: {
   enabled: false,       // opt out of the install built-in
-  prefix: "~/.local/bin", // default bin directory
   updateGetLatest: async ({ version }) => {
-    // download or locate latest binary; return { path, version, cleanup }
+    // download or locate latest release; return { path, version, cleanup }
     return { path: "/tmp/myapp", version: "2.0.0" };
   },
 }
 ```
 
-When `updateGetLatest` is set, ArgsBarg adds **`install --update`** (download latest release and reinstall installed artifacts).
+When `updateGetLatest` is set, ArgsBarg adds **`install --update`** (download latest release and reinstall installed artifacts in scope).
 
 ### GitHub releases (`ghReleaseUpdateGetLatest`)
 
-For compiled binaries published via `gh release`, wire a hook without hand-rolling download logic:
+For compiled apps published via `gh release`, wire a hook without hand-rolling download logic:
 
 ```typescript
 import {
@@ -92,10 +196,6 @@ versionCheck.refreshIfStale();
 
 Requires `gh` on PATH and `gh auth login`. Consumers keep app-specific config only (~15 lines).
 
-Environment:
-
-- `INSTALL_PREFIX` — same as `install.prefix` / `--prefix`
-
 ## App config (`program.appConfig`)
 
 When `program.appConfig` is set on the program root, ArgsBarg manages a flat JSON config file:
@@ -109,53 +209,74 @@ appConfig: {
       sensitive: true,
     },
   },
-  path: "~/.config/myapp/config", // optional; default is OS-specific
 },
 ```
 
-Default path: `$XDG_CONFIG_HOME/<sanitized-key>/config` (Linux/macOS) or `%APPDATA%/<key>/config` (Windows).
+Config file path: `~/.local/lib/<sanitized-key>/config.json`.
 
 | Flag | Description |
 | --- | --- |
-| `--configure` | Interactive prompt for each schema entry; writes or updates the config file (standalone — not part of `--all`) |
-| `--uninstall --config` | Remove the config file (included in `--uninstall --all`) |
+| `--configure` | Interactive prompt for each setting; writes or updates the config file. On full install, the wizard runs automatically when configuration is in scope. Standalone **`install --configure`** runs the wizard only (no other install steps). |
+| `--uninstall --configure` | Remove the config directory (`~/.local/lib/<key>/`) |
 | `--status` | Shows config path and which required keys are set or missing |
 
 **Configure UX** (TTY):
 
 ```
-API token
+Configuration Setup
+
+API token (API_TOKEN)
   Create at https://example.com/settings/tokens
-Current: REDACTED
-Value (Enter to keep):
+  Current: REDACTED
+  Value (Enter to copy from env):
 ```
 
-Non-sensitive vars show the current value; first-time setup omits the `Current:` line.
+Non-sensitive vars show the current value; first-time setup omits the `Current:` line. When the current value comes from a mapped environment variable, Enter copies it into `config.json`; otherwise Enter keeps the existing file value. At runtime, a non-empty mapped environment variable always wins over `config.json` (the file is the fallback when env is unset).
 
 ## Flags
 
+### Target flags
+
+| Flag | Description |
+| --- | --- |
+| `--all` | Install the default set (app, shell completions, and configuration when supported) |
+| `--app` | Copy this app to the install directory |
+| `--completions` | Install bash, zsh, and fish tab-completion scripts |
+| `--skill` | Install agent skills for Cursor, Claude, and other supported AI tools |
+| `--mcp` | Add MCP server configuration for Cursor, Claude Code, and other supported agents |
+| `--configure` | Run the configuration wizard (install) or remove the config file (`--uninstall`) |
+
+### Operation flags
+
 | Flag | Description |
 | --- | --- |
-| `--yes` | Skip confirmation (required for non-TTY unless `--json`, `--reinstall`, or `--update`) |
+| `--status` | Read-only inventory |
+| `--reinstall` | Refresh everything already installed (implies `--yes`; no numbered confirm) |
+| `--update` | Download the latest release and refresh installed files (implies `--yes`) |
+| `--uninstall` | Remove installed files (`--all` removes everything; use individual flags for one category) |
+| `--from <path>` | App executable to copy with `--reinstall` / `--update` (default: running executable) |
+
+### Behavior flags
+
+| Flag | Description |
+| --- | --- |
+| `--yes`, `-y` | Skip confirmation (required for non-TTY unless `--json`, `--reinstall`, or `--update`) |
 | `--dry` | Preview changes; per-step messages on stderr with `[dry run]` |
 | `--json` | Machine-readable output on stdout (implies `--yes`) |
-| `--quiet` | Suppress summaries and per-step messages (requires `--yes`) |
-| `--prefix <dir>` | Override binary install directory |
-| `--reinstall` | Reinstall artifacts already on disk (implies `--bin` + `--yes`) |
-| `--update` | Download latest release and reinstall installed artifacts (requires `install.updateGetLatest`; implies `--yes`) |
-| `--from <path>` | Binary to copy with `--reinstall` (default: running executable) |
-| `--status` | Read-only inventory |
-| `--uninstall` | Remove artifacts in scope (`--all`, `--bin`, `--completions`, `--skill`, `--mcp`, `--config`); skips targets not installed |
+
+## Confirmation
+
+Install and uninstall (except `--yes`, `--json`, `--dry`, `--reinstall`, `--update`) print a **`{app} Setup`** banner on stderr, then a numbered list of planned actions on stdout. Reply **`y`** for all, **`n`** or Enter to abort, or numbers for a subset. On **install**, when the plan includes the app as item **1**, it is always installed (prompt example: **`2,3`**); MCP and other targets need the binary on PATH. On **uninstall**, use any subset (e.g. **`1,3`**). After you confirm, **`Done.`** prints on stderr. Per-step progress is suppressed until you confirm; the final **`Installed N file(s).`** summary still prints.
 
 ## MCP merge behavior
 
-When `--mcp` runs, entries are merged into `mcpServers[<sanitized-key>]` with:
+When `--mcp` runs, 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 (then it overwrites).
+If an existing entry differs, the command exits with an error unless `--yes` is passed (then it overwrites). MCP conflict checks run only for hosts present in the current plan.
 
 ## Opt out
 

package/docs/mcp.md

@@ -244,6 +244,20 @@ The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nest
 | MIME type | `application/json` |
 | Contents | `cliSchemaJson(root)` — handlers omitted, built-ins excluded |
 
+### Auto docs topic resources
+
+When both **`docs.enabled`** and **`mcpServer.enabled`** are true, each user key in **`docs.topics`** is also exposed as an MCP resource:
+
+| Property | Value |
+| --- | --- |
+| URI | `<sanitized root key>://docs/<topicKey>` (e.g. `myapp://docs/readme`) |
+| 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`.
+
+Custom `mcpServer.resources` URIs must not collide with the schema URI or any auto docs topic URI (validated at program compile time).
+
 Add custom resources on the program root:
 
 ```typescript
@@ -261,7 +275,7 @@ mcpServer: {
 },
 ```
 
-URIs must be unique and must not equal `schemaResourceUri`. `load()` runs synchronously at `resources/read` time.
+URIs must be unique and must not equal `schemaResourceUri` or any auto docs topic URI (`<mcpId>://docs/<topicKey>`). `load()` runs synchronously at `resources/read` time.
 
 ## Invocation context
 
@@ -308,7 +322,7 @@ At server start (`Cli.serveMcp()`), before the NDJSON loop:
 
 **App config (`program.appConfig`):**
 
-- Default path: `$XDG_CONFIG_HOME/<sanitized-key>/config` (Linux/macOS) or `%APPDATA%/<key>/config` (Windows). Override with `config.path`.
+- Default path: `~/.local/lib/<sanitized-key>/config`.
 - 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.
@@ -359,34 +373,47 @@ You should get one JSON line on stdout with `result.capabilities` and `result.se
 
 ## MCP Bundle (`mcp bundle`)
 
-When `mcpServer.enabled` is true, **`mcp bundle`** writes two distribution artifacts:
+When `mcpServer.enabled` is true, **`mcp bundle`** writes dist artifacts you opt into on the program root:
 
 ```bash
 just build
 ./dist/myapp mcp bundle
-# → dist/myapp.mcpb
-# → dist/claude-plugin/myapp.zip
+# → dist/myapp.mcpb          (when mcpServer.mcpd: true)
+# → dist/claude-plugin/myapp.zip  (when mcpServer.claudePlugin: true)
+```
+
+Enable one or both flags:
+
+```typescript
+mcpServer: {
+  enabled: true,
+  mcpd: true,           // Claude Desktop `.mcpb`
+  claudePlugin: true,   // Claude Code plugin zip
+},
 ```
 
-Expects the compiled binary at **`dist/<program.key>`**.
+Expects the compiled binary at **`dist/<program.key>`**. Stdout prints one path per artifact produced.
 
 | Output | Purpose |
 | --- | --- |
-| **`dist/<key>.mcpb`** | Claude Desktop MCP Bundle (`.mcpb` zip) |
-| **`dist/claude-plugin/<name>.zip`** | Claude Code plugin zip (`<name>` is kebab-case from `program.key`) |
+| **`dist/<key>.mcpb`** | Claude Desktop MCP Bundle — when `mcpd: true` (default **false**) |
+| **`dist/claude-plugin/<name>.zip`** | Claude Code plugin zip — when `claudePlugin: true` (default **false**) |
 
 Manifest metadata is generated from your schema (`mcpServerId`, tools, `program.appConfig` user config for env-mapped entries). Optional pack-time fields live under **`mcpServer.bundle`** (`author`, `icon`, `longDescription`).
 
 **Claude Code plugin zip layout** (paths at archive root):
 
 ```
-.claude-plugin/plugin.json
+.claude-plugin/plugin.json   # includes "mcpServers": ".mcp.json"
 .mcp.json
-bin/myapp
+bin/myapp                    # executable (0755 preserved in the zip)
 skills/<dirName>/SKILL.md
-skills/<dirName>/reference.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.
+
 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.

package/docs/templates/cursor/rules/cli-program.mdc

@@ -10,7 +10,7 @@ When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
 2. MCP tools, varargs, `inputSchema` → also `node_modules/argsbarg/docs/mcp.md`.
 3. JSON stdout / `outputSchema` guide and codegen → `node_modules/argsbarg/docs/output-schema.md`.
 4. App config / `program.appConfig` guide and codegen → `node_modules/argsbarg/docs/config-schema.md`.
-5. `install`, completions, skills → `node_modules/argsbarg/docs/install.md`.
+5. `install`, `install.targets`, completions, skills → `node_modules/argsbarg/docs/install.md`.
 6. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
 7. **Examples** (shipped under `node_modules/argsbarg/examples/`):
    - Concepts / minimal config → `examples/config-app/`

package/examples/config-app/program.ts

@@ -11,8 +11,6 @@ import {
 } from "../../src/index.ts";
 import { APP_CONFIG_JSON_SCHEMA } from "./schema.ts";
 
-const configPath = process.env.CONFIG_APP_CONFIG_FILE;
-
 const configSchema = {
   apiToken: {
     description: "Create at https://example.com/settings/tokens",
@@ -37,7 +35,6 @@ export const program = {
   version: pkg.version,
   description: "Demonstrates program.appConfig, ctx.appConfig, and built-in config get/set.",
   appConfig: {
-    ...(configPath ? { path: configPath } : {}),
     jsonSchema: APP_CONFIG_JSON_SCHEMA,
     entries: configSchema,
   } satisfies CliAppConfig,

package/examples/consumer-app/README.md

@@ -11,6 +11,7 @@
 | `outputSchema` | `src/commands/status/types.ts` (`StatusJsonOutput`) → `schemas/outputSchemas.ts` |
 | Schemagen | `scripts/schemagen.ts` + `scripts/schemagen/discover-schema-roots.ts` |
 | Handler access | `ctx.appConfig` in `src/program.ts` |
+| MCP doc topics | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled |
 | Package import | `from "argsbarg"` (not relative to argsbarg `src/`) |
 
 ## Quick start (in this repo)
@@ -45,7 +46,6 @@ Discovery walks `src/**/types.ts` only.
 | Variable | Purpose |
 | --- | --- |
 | `CONSUMER_APP_API_TOKEN` | Overrides `apiToken` via `program.appConfig` env mapping |
-| `CONSUMER_APP_CONFIG_FILE` | Overrides config file path (`config.path`) |
 
 ## Maintainers (argsbarg repo)