argsbarg 4.1.0 → 4.1.1

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,272 +1,172 @@
 # Install command
 
-The `install` built-in installs the app, 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).
 
-## End-user install
+Opt out with `install: { enabled: false }` on the program root.
 
-Ship a compiled binary (or app bundle). Users install interactively — no `--yes` required when stdin is a TTY:
+## End-user install (Homebrew)
 
-- **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`**.
+```bash
+brew tap <org>/<repo>
+brew install <tap>/<key>
+<key> install --configure    # when app config is required (interactive)
+```
 
-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`**).
+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 is CLI-only** — there is no GUI uninstaller. Users run:
+**Uninstall the binary:** `brew uninstall <key>`. Remove agent artifacts first (while the CLI is still on PATH):
 
 ```bash
-myapp install --uninstall          # remove all detected artifacts
-myapp install --uninstall --app    # scoped removal
+<key> uninstall --yes
+brew uninstall <tap>/<key>
 ```
 
-Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--reinstall`**, **`--update`**) — see [Confirmation](#confirmation).
-
-## Quick start (automation)
+## Developer install
 
 ```bash
-# First-time setup (bare `install` is equivalent to `--all`)
-myapp install --yes
+just build
+just install-local    # same formula as production; gen-dev-formula uses file:// URL (`just install` is an alias)
+```
 
-# Or explicitly
-myapp install --all --yes
+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.
 
-# Refresh after upgrading (re-copy running app + refresh detected artifacts in scope)
-myapp install --reinstall
+## Quick reference
 
-# Upgrade to latest release (when this app supports remote updates)
-myapp install --update
+```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
 
-# Remove everything detected on disk (bare `install --uninstall` is equivalent to `--uninstall --all`)
-myapp install --uninstall --yes
+# Configure app settings (interactive wizard — not part of --all or post_install)
+<key> install --configure
+
+# 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 |
 | --- | --- | --- |
-| 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 |
-| 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 |
+| 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` |
+
+### Externally managed binary (Homebrew)
+
+When **`PATH`** resolves the program key to the **running executable** (e.g. after `brew install`):
+
+- **`install --status`** shows `app: system (PATH)`
+- **`--all`** / **`--reinstall`** refresh skills and MCP only — not the binary or completions
+
+MCP config uses the command name on **`PATH`**, not a Cellar path.
 
 ### 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
+- **`configure`** is **opt-in** (`includedInAll: false`) — run **`install --configure`** separately
 
 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.
+Scoped flags (`--skill`, `--mcp`, `--configure`) run that artifact category. Honor `enabled: false` as a hard off.
 
-Use **`install --status --json`** to preview effective targets (`effective.all`, `effective.mcp`, `effective.skill`) before installing.
+Use **`install --status --json`** to preview effective targets 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.
+The top-level **`uninstall`** command removes agent artifacts. Bare **`uninstall`** is equivalent to **`uninstall --all`**.
+
+- **`uninstall --all`** removes **every detected artifact type**, ignoring `install.targets`.
+- Scoped uninstall (`--skill`, `--mcp`, `--configure`, …) 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).
+Missing targets are skipped silently.
 
 ## `install.targets`
 
-Configure which artifacts participate in `--all`, `--reinstall`, and `--update`:
+Configure which artifacts participate in `--all`, `--reinstall`:
 
 ```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.
-
-### Shell-only CLI (default)
-
-```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
-  },
-},
-```
-
-Preview resolved targets: **`myapp install --status --json`**.
-
-## Configuration
-
-On the program root:
-
-```typescript
-install: {
-  enabled: false,       // opt out of the install built-in
-  updateGetLatest: async ({ version }) => {
-    // 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 in scope).
-
-### GitHub releases (`ghReleaseUpdateGetLatest`)
-
-For compiled apps published via `gh release`, wire a hook without hand-rolling download logic:
+`InstallTargetSpec` is `boolean` or `{ enabled?: boolean; includedInAll?: boolean }`.
 
-```typescript
-import {
-  createGhFetchLatest,
-  createGhVersionCheck,
-  ghReleaseUpdateGetLatest,
-} from "argsbarg";
-
-const cachePath = path.join(configDir, "version-check.json");
-
-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();
-```
-
-Requires `gh` on PATH and `gh auth login`. Consumers keep app-specific config only (~15 lines).
+Artifact keys: `chatgptMcp`, `claudeCodeMcp`, `claudeDesktopMcp`, `claudeSkill`, `codexMcp`, `codexSkill`, `configure`, `cursorMcp`, `cursorSkill`, `openclawMcp`, `openclawSkill`, `opencodeMcp`, `opencodeSkill`.
 
 ## App config (`program.appConfig`)
 
-When `program.appConfig` is set on the program root, ArgsBarg manages a flat JSON config file:
-
-```typescript
-appConfig: {
-  entries: {
-    apiToken: {
-      description: "Create at https://example.com/settings/tokens",
-      env: "API_TOKEN",
-      sensitive: true,
-    },
-  },
-},
-```
-
-Config file path: `~/.local/lib/<sanitized-key>/config.json`.
+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 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>/`) |
+| `--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.
 
-```
-Configuration Setup
+Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
+
+## `uninstall` command
 
-API token (API_TOKEN)
-  Create at https://example.com/settings/tokens
-  Current: REDACTED
-  Value (Enter to copy from env):
+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
 ```
 
-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).
+Same behavior flags as install: `--yes`, `--dry`, `--json`. Does not support `--status` or `--reinstall`.
 
-## Flags
+## Flags (`install`)
 
 ### 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`) |
+| `--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
+### Operation flags (`install`)
 
 | Flag | Description |
 | --- | --- |
 | `--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) |
+| `--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 (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`) |
+| `--yes`, `-y` | Skip confirmation |
+| `--dry` | Preview changes |
+| `--json` | Machine-readable output (implies `--yes`) |
 
 ## 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.
+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
 
@@ -276,15 +176,31 @@ When `--mcp` runs, entries are merged into host config with:
 { "command": "<root.key>", "args": ["mcp"] }
 ```
 
-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.
+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
 }
 ```
 
@@ -339,7 +339,6 @@ appConfig: {
 },
 mcpServer: {
   enabled: true,
-  shellEnv: true,
 },
 ```
 

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
+```

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 }
+    }
+  ]
+}