argsbarg 4.1.0 → 5.0.1

package/docs/config-schema.md

@@ -39,7 +39,7 @@ await cli.run();
 | Where argsbarg uses it | Purpose |
 | --- | --- |
 | Config file | Flat JSON keyed by schema names; strict load (unknown keys rejected) |
-| `install --configure` / `--status` | Interactive setup and status |
+| Interactive `configure` / `--status` | Auto-runs config wizard when `entries` is non-empty; `--status` for read-only inventory |
 | Built-in `config get` / `config set` | Read/write resolved values (opt-out via `commands: false`) |
 | MCP bundle / Claude plugin | `userConfig` for entries with `env` set |
 | `ctx.appConfig` in handlers | `get`, `require`, `set`, `read`, `path`, `dir` — prefer over `process.env` |
@@ -60,6 +60,7 @@ export interface CliAppConfigEntry {
   required?: boolean;   // default: true (can override jsonSchema required)
   sensitive?: boolean;  // default: name heuristic
   env?: string;         // env override + export to process.env after resolve
+  resolve?: CliAppConfigResolveFn;  // fallback after file; must be synchronous
 }
 
 export interface CliAppConfig {
@@ -92,13 +93,40 @@ No nested `env` bag. No extra keys — rejected on load.
 
 ## Resolution order (per schema key)
 
-| Key has `env`? | Resolved value |
-| --- | --- |
-| **Yes** | non-empty `process.env[env]` → else file[key] → else default |
-| **No** | file[key] → else default |
+| Step | Source | Notes |
+| --- | --- | --- |
+| 1 | **Env** (`entry.env`) | Non-empty host env wins over file and `resolve` |
+| 2 | **File** | `config.json` value for the key |
+| 3 | **`resolve()`** | Optional synchronous callback (e.g. `gh auth token`); return `undefined` to continue. Async/Promise return values are ignored. |
+| 4 | **Env** (`entry.env`) | Fallback when `resolve` returned `undefined` |
+| 5 | **Default** | `jsonSchema` / `entry.default` |
 
 Empty string in env or file counts as **missing** for required entries. After resolution, mapped values are exported to `process.env`.
 
+Example — GitHub token with `env: "GH_TOKEN"` and `resolve` calling `gh auth token`:
+
+```typescript
+githubToken: {
+  description: "GitHub API token.",
+  env: "GH_TOKEN",
+  sensitive: true,
+  resolve: () => {
+    try {
+      const r = Bun.spawnSync(["gh", "auth", "token"], { stdout: "pipe", stderr: "ignore" });
+      if (r.exitCode === 0) {
+        const token = new TextDecoder().decode(r.stdout).trim();
+        return token.length > 0 ? token : undefined;
+      }
+    } catch {
+      // `gh` not installed
+    }
+    return undefined;
+  },
+},
+```
+
+Interactive `configure` does not persist values supplied only by env or `resolve` when you press Enter to accept the current value.
+
 ## Hand-written vs generated
 
 | Approach | When |
@@ -180,10 +208,9 @@ Object/array/`$ref` properties require `--json` on `config set`.
 
 | Example | Role |
 | --- | --- |
-| [`examples/config-app/`](../examples/config-app/) | **Learn** — hand-written schema, minimal setup |
-| [`examples/consumer-app/`](../examples/consumer-app/) | **Copy** — schemagen discovery, `APP_CONFIG_JSON_SCHEMA` bridge |
+| [`examples/full-example/`](../examples/full-example/) | **Copy template** — schemagen discovery, `APP_CONFIG_JSON_SCHEMA` bridge, `program.appConfig`, built-in `config get`/`set` |
 
 ```bash
-cd examples/consumer-app && bun install && bun run schemagen
-CONSUMER_APP_API_TOKEN=dev bun run start config get apiToken --json
+cd examples/full-example && just setup && just schemagen
+FULL_EXAMPLE_API_TOKEN=dev just run config get apiToken --json
 ```

package/docs/configure.md

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

package/docs/developing.md

@@ -33,15 +33,15 @@ Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile
 | Recipe | When | Effect |
 | --- | --- | --- |
 | `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) |
+| `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 configure --sync --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,104 @@
+# Shipping via Homebrew (tap-from-repo)
+
+Argsbarg apps distribute the **binary and shell completions** through Homebrew, and **agent artifacts** (skills, MCP config) through `configure --sync`.
+
+## Distribution model
+
+| Layer | Mechanism |
+| --- | --- |
+| Binary + completions | Formula `install` block |
+| Skills + MCP | Formula `post_install` → `{key} configure --sync --yes` |
+| App config | User opt-in: `{key} configure` (interactive; not run from formula `post_install`) |
+
+**Only tap-from-repo** — in-repo `Formula/` or GitHub tap. Not Homebrew core.
+
+### End-user install
+
+```bash
+brew tap <org>/<repo>
+brew install <tap>/{key}
+{key} 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 (`configure --remove-config --yes`) |
+| `just uninstall-release` | Release formula from `{tap}` (keeps tap) |
+| `just uninstall-release-tap` | Release formula + `brew untap {tap}` |
+| `just test-release` | Install release formula and run formula test |
+
+End users: `<key> configure --remove-all --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}", "configure", "--sync", "--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`
+- Top-level `install` and `uninstall` commands (use `configure`)
+- `install --update` / `updateGetLatest`
+- Homebrew completion installer via CLI (Homebrew owns completions)
+- Bare-argv install bootstrap
+- Auto configure wizard after sync
+- 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/mcp.md

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

package/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 --release-repo org/my-cli --yes
+```
+
+Edit `scripts/create-identity.ts` to set `desc` (used by `program.description` and the Homebrew formula).
+
+`create` copies this template (including `.cursor/rules/cli-program.mdc`), substitutes identity placeholders, runs `bun install`, schemagen, `bun test`, and `git init` + Initial commit when appropriate.
+
+**Git bootstrap:** skipped when `{target}/.git` already exists, or when the target is inside an existing git work tree (monorepo subfolder). Standalone new directories get `Initial commit`.
+
+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
+```

package/examples/full-example/biome.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json",
+  "assist": { "actions": { "source": { "organizeImports": "on" } } },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "lineWidth": 120
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.json"],
+      "formatter": { "enabled": false },
+      "linter": { "enabled": false }
+    }
+  ]
+}

package/examples/{consumer-app → full-example}/bun.lock

@@ -8,6 +8,8 @@
         "argsbarg": "file:../..",
       },
       "devDependencies": {
+        "@biomejs/biome": "^2.5.0",
+        "@types/bun": "^1.3.12",
         "ts-json-schema-generator": "^2.3.0",
         "typescript": "^5.9.3",
       },