argsbarg 4.0.4 → 4.1.1

package/docs/developing.md

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

package/docs/distribution-homebrew.md

@@ -0,0 +1,103 @@
+# 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`.
+
+## 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`) |
+
+**Only tap-from-repo** — in-repo `Formula/` or GitHub tap. Not Homebrew core.
+
+### End-user install
+
+```bash
+brew tap <org>/<repo>
+brew install <tap>/{key}
+{key} install --configure   # when app config is required
+```
+
+### Developer install
+
+```bash
+just build
+just install-local    # or `just install` (alias)
+just reinstall-local   # fast binary swap (`install -m 755` into Cellar; run install-local first)
+just uninstall        # undo formula + agent artifacts (not app config)
+```
+
+Dev and release use the **same formula** (`Formula/{key}.rb`, class name, install/post_install/test). `gen-dev-formula.ts` only changes `url`, `version`, and `sha256` to point at the local binary in `Formula/.staging/`. Release bumps restore the GitHub URL via `scripts/release.ts`.
+
+### Developer uninstall
+
+| Recipe | Removes |
+| --- | --- |
+| `just uninstall` | Formula `{key}` + tap symlink + skills/MCP |
+| `just uninstall-config` | App config file only (`uninstall --configure`) |
+| `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>`.
+
+## Formula pattern
+
+```ruby
+def install
+  bin.install "{key}"
+  generate_completions_from_executable(bin/"{key}", "completion", base_name: "{key}")
+end
+
+def post_install
+  system bin/"{key}", "install", "--reinstall", "--yes"
+end
+```
+
+Completions require users to configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
+
+**Why configure is separate from `post_install`:** the wizard is interactive (TTY + prompts for secrets). Formula `post_install` runs non-interactively during `brew install` and in CI (`brew test`). Apps with `appConfig` print a one-line configure hint in formula `caveats` instead.
+
+## Bootstrap CLI (`argsbarg create`)
+
+Copy the shipped `examples/full-example` template into a new directory with identity substitutions, then run install, schemagen, tests, and git init (when appropriate):
+
+```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
+```
+
+On a TTY, omit flags to use the interactive wizard. Verify an existing tree:
+
+```bash
+bunx argsbarg create --check .
+```
+
+Template source: [`examples/full-example/`](../examples/full-example/) in the argsbarg package (also under `node_modules/argsbarg/examples/full-example` after `bun add argsbarg`).
+
+**Git bootstrap skip rules:** post-create skips `git init` when the target already has a `.git` directory, or when the target sits inside an existing git work tree (e.g. a monorepo subfolder). Standalone new directories get an `Initial commit`.
+
+## Release workflow
+
+1. `just build` → `dist/{key}`
+2. `scripts/release.ts` → writes `Formula/{key}.rb` (GitHub URL + sha256), commits, tags, uploads `dist/{key}` to GitHub Releases
+3. Users `brew upgrade {key}` from the tap
+
+## Removed (breaking)
+
+- Self-install to `~/.local/bin`
+- `install --update` / `updateGetLatest`
+- `install --completions` (Homebrew owns completions)
+- Bare-argv install bootstrap
+- Auto configure wizard after `install --all`
+- Separate `{key}-local` formula and `{key}/dev` tap
+
+## Config path
+
+Default: `~/.local/lib/<sanitized-key>/config.json`
+
+Export helpers: `resolveAppConfigPath`, `displayAppConfigPath` from `argsbarg`.

package/docs/install.md

@@ -1,169 +1,206 @@
 # 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 manages **agent artifacts** (skills, MCP config, app config). The **binary and shell completions** ship via Homebrew — see [distribution-homebrew.md](distribution-homebrew.md).
 
-## Quick start
+Opt out with `install: { enabled: false }` on the program root.
+
+## End-user install (Homebrew)
+
+```bash
+brew tap <org>/<repo>
+brew install <tap>/<key>
+<key> install --configure    # when app config is required (interactive)
+```
+
+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:** `brew uninstall <key>`. Remove agent artifacts first (while the CLI is still on PATH):
+
+```bash
+<key> uninstall --yes
+brew uninstall <tap>/<key>
+```
+
+## Developer install
 
 ```bash
-# First-time setup
-myapp install --all --yes
+just build
+just install-local    # same formula as production; gen-dev-formula uses file:// URL (`just install` is an alias)
+```
 
-# Refresh after upgrading (re-copy running binary + refresh installed artifacts)
-myapp install --reinstall
+Dev flow matches release: formula `install` copies the binary and generates completions; `post_install` runs `<key> install --reinstall --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 install-artifacts` to refresh agent artifacts without touching the binary.
 
-# Upgrade to latest release (when install.updateGetLatest is configured)
-myapp install --update
+## Quick reference
+
+```bash
+# Refresh skills/MCP after upgrade (Homebrew post_install runs this automatically)
+<key> install --reinstall --yes
 
 # See what is installed
-myapp install --status
+<key> install --status
+
+# Configure app settings (interactive wizard — not part of --all or post_install)
+<key> install --configure
 
-# Remove everything installed with --all
-myapp install --uninstall --all --yes
+# Remove agent artifacts (default: --all)
+<key> uninstall --yes
 ```
 
+Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--reinstall`**) — see [Confirmation](#confirmation).
+
 ## What gets installed
 
-| Target | Flag | Destination |
+| Target | Flag | Mechanism |
 | --- | --- | --- |
-| Binary | `--bin` | `~/.local/bin/<key>` (or `--prefix`) |
-| 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`) |
+| Binary | Homebrew formula | `bin.install` in Formula |
+| Shell completions | Homebrew formula | `generate_completions_from_executable` |
+| Cursor skill | `--skill` / `--all` | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
+| Claude skill | `--skill` / `--all` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
+| Codex / OpenCode / OpenClaw skills | `--skill` / `--all` | Agent-specific dirs when available |
+| MCP config | `--mcp` / `--all` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
+| App config | `--configure` | Interactive wizard writes `~/.local/lib/<key>/config.json` |
 
-`--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).
+### Externally managed binary (Homebrew)
 
-`install --uninstall` requires the same target flags as install (`--all`, `--bin`, etc.) — bare `--uninstall` alone is an error.
+When **`PATH`** resolves the program key to the **running executable** (e.g. after `brew install`):
 
-Shells not on PATH are skipped silently (no warnings).
+- **`install --status`** shows `app: system (PATH)`
+- **`--all`** / **`--reinstall`** refresh skills and MCP only — not the binary or completions
 
-## Configuration
+MCP config uses the command name on **`PATH`**, not a Cellar path.
 
-On the program root:
+### Default `--all` behavior
 
-```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 }
-    return { path: "/tmp/myapp", version: "2.0.0" };
-  },
-}
-```
-
-When `updateGetLatest` is set, ArgsBarg adds **`install --update`** (download latest release and reinstall installed artifacts).
+Bare **`install`** and **`install --all`** install targets with **`includedInAll: true`**. Core defaults:
 
-### GitHub releases (`ghReleaseUpdateGetLatest`)
+- **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
+- **`configure`** is **opt-in** (`includedInAll: false`) — run **`install --configure`** separately
 
-For compiled binaries published via `gh release`, wire a hook without hand-rolling download logic:
+Desktop-only MCP hosts (`claudeDesktopMcp`, `chatgptMcp`) follow the MCP side only — no skill pair.
 
-```typescript
-import {
-  createGhFetchLatest,
-  createGhVersionCheck,
-  ghReleaseUpdateGetLatest,
-} from "argsbarg";
+Scoped flags (`--skill`, `--mcp`, `--configure`) run that artifact category. Honor `enabled: false` as a hard off.
 
-const cachePath = path.join(configDir, "version-check.json");
+Use **`install --status --json`** to preview effective targets before installing.
 
-install: {
-  updateGetLatest: ghReleaseUpdateGetLatest({
-    repo: "owner/repo",
-    asset: "myapp",
-    tempPrefix: "myapp-update.",
-    cachePath,
-  }),
-}
-
-// Optional: summary notice + background refresh
-const versionCheck = createGhVersionCheck({
-  currentVersion: "1.0.0",
-  commandName: "myapp",
-  cachePath,
-  fetchLatest: createGhFetchLatest({ repo: "owner/repo" }),
-});
-versionCheck.getUpdateNotice();
-versionCheck.refreshIfStale();
-```
+### Asymmetric uninstall
 
-Requires `gh` on PATH and `gh auth login`. Consumers keep app-specific config only (~15 lines).
+The top-level **`uninstall`** command removes agent artifacts. Bare **`uninstall`** is equivalent to **`uninstall --all`**.
 
-Environment:
+- **`uninstall --all`** removes **every detected artifact type**, ignoring `install.targets`.
+- Scoped uninstall (`--skill`, `--mcp`, `--configure`, …) removes only that category.
 
-- `INSTALL_PREFIX` — same as `install.prefix` / `--prefix`
+Missing targets are skipped silently.
 
-## App config (`program.appConfig`)
+## `install.targets`
 
-When `program.appConfig` is set on the program root, ArgsBarg manages a flat JSON config file:
+Configure which artifacts participate in `--all`, `--reinstall`:
 
 ```typescript
-appConfig: {
-  entries: {
-    apiToken: {
-      description: "Create at https://example.com/settings/tokens",
-      env: "API_TOKEN",
-      sensitive: true,
-    },
+install: {
+  agentIntegration: "mcp", // | "skill" | "both" — default from mcpServer.enabled
+  targets: {
+    chatgptMcp: false,
+    cursorSkill: { includedInAll: 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).
+`InstallTargetSpec` 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`.
 
 | 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; writes or updates the config file. **Not** included in `--all`. |
 | `--status` | Shows config path and which required keys are set or missing |
 
-**Configure UX** (TTY):
+Use **`uninstall --configure`** to remove the config directory.
 
+Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
+
+## `uninstall` command
+
+Sibling of `install` for removing agent artifacts:
+
+```bash
+<key> uninstall --yes              # all artifacts (default)
+<key> uninstall --configure --yes  # config only
+<key> uninstall --skill --yes      # skills only
 ```
-API token
-  Create at https://example.com/settings/tokens
-Current: REDACTED
-Value (Enter to keep):
-```
 
-Non-sensitive vars show the current value; first-time setup omits the `Current:` line.
+Same behavior flags as install: `--yes`, `--dry`, `--json`. Does not support `--status` or `--reinstall`.
+
+## Flags (`install`)
 
-## Flags
+### Target flags
+
+| Flag | Description |
+| --- | --- |
+| `--all` | Install the default agent artifact set for this app |
+| `--skill` | Install agent skills |
+| `--mcp` | Add MCP server configuration |
+| `--configure` | Run the interactive configuration wizard |
+
+### Operation flags (`install`)
 
 | Flag | Description |
 | --- | --- |
-| `--yes` | 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 |
+| `--reinstall` | Refresh installed agent artifacts (Homebrew `post_install`; greenfield → full `--all` plan) |
+| `--from <path>` | App executable reference for status detection (rare; default: running executable) |
+
+### Behavior flags
+
+| Flag | Description |
+| --- | --- |
+| `--yes`, `-y` | Skip confirmation |
+| `--dry` | Preview changes |
+| `--json` | Machine-readable output (implies `--yes`) |
+
+## Confirmation
+
+Install and uninstall (except `--yes`, `--json`, `--dry`, `--reinstall`) print a **`{app} Setup`** banner and numbered plan. Reply **`y`** for all, **`n`** or Enter to abort, or numbers for a subset.
 
 ## 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.
+
+## Formula `post_install`
+
+Release formulae should run:
+
+```ruby
+def post_install
+  system bin/"myapp", "install", "--reinstall", "--yes"
+end
+```
+
+This refreshes skills/MCP without running the configure wizard (configure is opt-in).
+
+## 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
-const cli = {
-  key: "myapp",
-  description: "...",
-  install: { enabled: false },
-  // ...
-} satisfies CliProgram;
+install: { enabled: false },
 ```

package/docs/mcp.md

@@ -131,7 +131,7 @@ Set `mcpServer` on the **program root only** (the `CliProgram` passed to `new Cl
 | --- | --- | --- |
 | `enabled` | *(required)* | Must be `true` when `mcpServer` is set |
 | `schemaResourceUri` | `<sanitized root key>://schema` | URI for the built-in schema resource |
-| `shellEnv` | off | Capture login-shell `env` at startup (`true` uses `$SHELL`, or pass a shell path) |
+| `shellEnv` | on (opt-out with `false`) | Capture login-shell `env` at startup (`true` uses `$SHELL`, or pass a shell path) |
 | `resources` | `[]` | Custom `CliMcpResource` entries (additive; schema resource is always included) |
 
 MCP `serverInfo.name` and the default schema URI use the sanitized program `key` (non-alphanumeric characters become `_`). Program `version` comes from `CliProgram.version` (also used by the `version` built-in).
@@ -141,7 +141,7 @@ Example with optional fields:
 ```typescript
 mcpServer: {
   enabled: true,
-  shellEnv: true,
+  shellEnv: false, // opt out of login-shell capture
 }
 ```
 
@@ -322,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.
@@ -339,7 +339,6 @@ appConfig: {
 },
 mcpServer: {
   enabled: true,
-  shellEnv: true,
 },
 ```
 
@@ -373,33 +372,45 @@ 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)
 ```
 
-Expects the compiled binary at **`dist/<program.key>`**.
+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>`**. 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
 ```
 
+`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`.

package/docs/output-schema.md

@@ -186,7 +186,7 @@ Per repo:
 
 Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` pointing at `node_modules/argsbarg/docs/output-schema.md` and your `src/schemas/` layout.
 
-**Reference implementation:** [`examples/consumer-app/`](../examples/consumer-app/) in this repo (shipped in npm as `node_modules/argsbarg/examples/consumer-app/`) — discovery script, bridges, and `status` leaf with `outputSchema`.
+**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo (shipped in npm as `node_modules/argsbarg/examples/full-example/`) — discovery script, bridges, and `status` leaf with `outputSchema`.
 
 ## Out of scope
 

package/examples/full-example/README.md

@@ -0,0 +1,98 @@
+# full-example
+
+**Full argsbarg reference app** — bootstrap new production CLIs with `bunx argsbarg create`.
+
+## What this demonstrates
+
+| Area | Files / wiring |
+| --- | --- |
+| All builtins | `completion`, `version`, `install`, `docs`, `mcp`, `config get`/`set` |
+| `program.appConfig` | `src/types.ts` (`AppConfig`) → `schemas/configSchemas.ts` |
+| `outputSchema` | `src/commands/status/types.ts` (`StatusJsonOutput`) → `schemas/outputSchemas.ts` |
+| Schemagen | `scripts/schemagen.ts` + `scripts/schemagen/discover-schema-roots.ts` |
+| Command layout | `src/commands/<name>/command.ts`; registration 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/`) |
+| Homebrew distribution | `scripts/formula-shared.ts`, `scripts/gen-dev-formula.ts`, `Formula/`, `justfile` |
+| Dev tooling | Biome (`just format` / `just lint`), TypeScript, colocated tests |
+| Cursor rules | `.cursor/rules/cli-program.mdc`, `.cursor/rules/code.mdc` |
+
+## Bootstrap a new CLI
+
+Interactive (TTY):
+
+```bash
+bunx argsbarg create my-cli
+```
+
+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
+```
+
+`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`.
+
+To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-program-rule.ts .` from an argsbarg checkout (or pass the npm package path to the template).
+
+## Quick start (in this repo)
+
+```bash
+cd examples/full-example
+just setup
+just schemagen   # after changing src/**/types.ts
+FULL_EXAMPLE_API_TOKEN=dev just run status --json
+FULL_EXAMPLE_API_TOKEN=dev just run config get apiToken --json
+FULL_EXAMPLE_API_TOKEN=dev just run docs readme
+```
+
+## Homebrew dev install
+
+Requires [Homebrew](https://brew.sh) and a compiled binary at `dist/full-example`:
+
+```bash
+just build
+just install-local              # first-time dev formula (`just install` is an alias)
+just reinstall-local            # fast binary swap during development
+just install-production         # uninstall local dev, install from GitHub tap
+just test-release
+```
+
+Undo a local dev install:
+
+```bash
+just uninstall          # dev formula + agent artifacts
+just uninstall-config   # app config only
+just uninstall-release  # release formula (keeps tap)
+```
+
+See [docs/distribution-homebrew.md](../../docs/distribution-homebrew.md).
+
+## Schemagen markers
+
+| Marker in interface JSDoc | Artifact |
+| --- | --- |
+| `Config schema` | `schemas/configSchemas.ts` + `schemas/generated/*-config.json` |
+| `JSON payload` | `schemas/outputSchemas.ts` + `schemas/generated/*.json` |
+
+Discovery walks `src/**/types.ts` only.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `FULL_EXAMPLE_API_TOKEN` | Overrides `apiToken` via `program.appConfig` env mapping |
+
+## Maintainers (argsbarg repo)
+
+When adding or changing builtins, update this example and run:
+
+```bash
+just check-full-example   # from argsbarg repo root
+just test                 # from examples/full-example
+```