argsbarg 6.1.9 → 6.2.0

package/docs/cli-program.md

@@ -8,10 +8,6 @@ ArgsBarg turns your schema into help, shell completions, MCP tools, and agent sk
 
 ```typescript
 const cli = {
-  key: "myapp",
-  version: "1.0.0",
-  description: "One-line summary of what the CLI does.",
-  mcpServer: { enabled: true },
   commands: [
     {
       key: "greet",
@@ -22,6 +18,10 @@ const cli = {
       handler: async (ctx) => { /* ... */ },
     },
   ],
+  description: "One-line summary of what the CLI does.",
+  key: "myapp",
+  mcpServer: { enabled: true },
+  version: "1.0.0",
 } satisfies CliProgram;
 ```
 
@@ -31,11 +31,11 @@ No `mcpTool` blocks required. Every leaf becomes an MCP tool; `inputSchema` come
 
 ```typescript
 const cli = {
-  key: "myapp",
-  version: "1.0.0",
+  commands: [/* ... */],
   description: "One-line summary of what the CLI does.",
   httpServer: { enabled: true }, // myapp api → http://127.0.0.1:3000
-  commands: [/* ... */],
+  key: "myapp",
+  version: "1.0.0",
 } satisfies CliProgram;
 ```
 
@@ -90,7 +90,7 @@ export const reserveCommand = {
 
 Use a **parameterized factory** only when the schema truly depends on inputs (e.g. `createUpsertCommand(deps)` for tests or injected config). A `reserveCommand()` that returns a static literal adds indirection without benefit.
 
-**`satisfies CliProgram`** on the root (or **`satisfies CliLeaf`** / router type on extracted modules) preserves type-checking whether inline or not.
+**`satisfies CliProgram`** on the root (or **`satisfies CliLeaf`** / router type on extracted modules) preserves type-checking whether inline or not. Keep **program-root fields in alphabetical order** (`appConfig`, `commands`, `description`, `docs`, `hooks`, `httpServer`, `key`, `mcpServer`, `readiness`, `skill`, `version`, …).
 
 ## Descriptions
 
@@ -541,8 +541,9 @@ await cli.run();
 - **Strict:** unknown keys rejected on load.
 - **CLI:** missing required config exits 1 before the leaf handler (TTY prompt when interactive). Built-in `docs` and `configure get`/`set` skip this exit.
 - **MCP:** server stays up; missing config returns `isError: true` at `tools/call`.
-- **Configure:** interactive `configure` runs the app config wizard; **`configure --sync`** refreshes agent artifacts.
-- **Agent integration:** `configure.agentIntegration` (`mcp` | `skill` | `both`) sets default sync targets; see [configure.md](configure.md#configuretargets).
+- **Configure:** interactive `configure` runs the app config wizard; **`configure --sync`** refreshes agent artifacts to `~/.agents/` ([.agents protocol](https://dotagentsprotocol.com/)).
+- **Agent skill:** `program.skill: { enabled: true }` installs to `~/.agents/skills/<key>/` on `configure --sync`; see [configure.md](configure.md) and [ai-skills.md](ai-skills.md).
+- **MCP install:** `mcpServer: { enabled: true }` merges into `~/.agents/mcp.json` on `configure --sync`; manual Cursor/Claude setup in [mcp.md](mcp.md).
 
 See [config-schema.md](config-schema.md) for codegen, [configure.md](configure.md) (`configure.targets`), and [mcp.md](mcp.md).
 
@@ -583,7 +584,7 @@ If you maintain argsbarg from a sibling checkout, `just consumer-dev` / `just co
 
 3. **Optional:** a separate rule (e.g. `.cursor/argsbarg.mdc` or `AGENTS.md`) for broader package API notes.
 
-**Not this file:** `myapp configure` writes the **app** skill (`SKILL.md` under `~/.cursor/skills/`) from your command schema — how to *invoke* the CLI. The rule above is for *authoring* argsbarg schema.
+- **Not this file:** `myapp configure --sync` writes the **app** skill (`SKILL.md` under `~/.agents/skills/<key>/`) from your command schema — how to *invoke* the CLI. The rule above is for *authoring* argsbarg schema.
 
 ## See also
 

package/docs/config-schema.md

@@ -224,9 +224,9 @@ Object/array/`$ref` properties require `--json` on `configure set` when comma-se
 
 | Example | Role |
 | --- | --- |
-| [`examples/full-example/`](../examples/full-example/) | **Copy template** — `@sg` schemagen, builtins; optional `program.appConfig` |
+| [`examples/full-example-json/`](../examples/full-example-json/) | **Schema-first copy template** — `@sg` schemagen, builtins; optional `program.appConfig` |
 
 ```bash
-cd examples/full-example && just setup && just schemagen
-FULL_EXAMPLE_API_TOKEN=dev just run configure get apiToken --json
+cd examples/full-example-json && just setup && just schemagen
+FULL_EXAMPLE_JSON_API_TOKEN=dev just run configure get apiToken --json
 ```

package/docs/configure.md

@@ -68,10 +68,8 @@ Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remo
 | --- | --- | --- |
 | 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 when `mcpServer.enabled` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
+| Agent skill | skipped (automatic) | `~/.agents/skills/<key>/` when `program.skill.enabled` |
+| MCP config | skipped (automatic) | `~/.agents/mcp.json` when `mcpServer.enabled` ([.agents protocol](https://dotagentsprotocol.com/)) |
 | App config | auto-runs wizard | Interactive wizard may update `~/.local/lib/<key>/config.json` when values change; `--sync` bootstraps an empty file on install |
 
 ### Externally managed binary (Homebrew)
@@ -79,37 +77,35 @@ Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remo
 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; also creates `~/.local/lib/<key>/config.json` as `{}` when missing (all apps)
+- **`configure --sync`** refreshes the agent skill (when `program.skill.enabled`) and merges MCP into `~/.agents/mcp.json` (when `mcpServer.enabled`); also creates `~/.local/lib/<key>/config.json` as `{}` when missing (all apps)
 
-MCP config uses the command name on **`PATH`**, not a Cellar path.
+MCP config uses the command name on **`PATH`**, not a Cellar path. For Cursor, Claude Code, and Claude Desktop, copy the `mcpServers` entry manually — see [mcp.md](mcp.md) and `docs mcp`.
 
 ### Interactive default
 
-Bare **`configure`** (TTY required) walks enabled install targets in order. For each target:
+Bare **`configure`** (TTY required) runs the app config wizard when `program.appConfig` has entries. Agent skills and MCP are **not** prompted — they install automatically via brew `post_install` / `--sync` when `program.skill.enabled` or `mcpServer.enabled` respectively.
 
-- **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`**.
+Remove the config file with **`configure --remove-config --yes`**.
 
-The **`app`** target (binary on PATH) is shown in `--status` only — never mutated by `configure`.
+The **`app`** and **`skill`** / **`agentsMcp`** targets are shown in `--status` only — never mutated by interactive `configure` (use `--sync` / brew hooks).
 
 ### `configure.targets`
 
-Configure which artifacts participate in `--sync`:
+Optional gates for app binary status and app-config wizard participation in `--sync`:
 
 ```typescript
+skill: { enabled: true },
+mcpServer: { enabled: true },
 configure: {
-  agentIntegration: "mcp", // | "skill" | "both" — default from mcpServer.enabled
   targets: {
-    chatgptMcp: false,
-    cursorSkill: { includedInAll: true },
+    configure: { includedInAll: true }, // optional: app config wizard on --sync
   },
 },
 ```
 
 `ConfigureTargetSpec` is `boolean` or `{ enabled?: boolean; includedInAll?: boolean }`.
 
-Artifact keys: `chatgptMcp`, `claudeCodeMcp`, `claudeDesktopMcp`, `claudeSkill`, `codexMcp`, `codexSkill`, `configure`, `cursorMcp`, `cursorSkill`, `openclawMcp`, `openclawSkill`, `opencodeMcp`, `opencodeSkill`.
+Artifact keys: `app`, `configure`. Legacy `configure.targets.*Mcp` keys are rejected — MCP installs to `~/.agents/mcp.json` when `mcpServer.enabled`.
 
 ## App config (`program.appConfig`)
 

package/docs/decisions.md

@@ -1,59 +1,96 @@
-# Decisions
+# Architecture Decision Records (ADRs)
 
-This doc tracks big architectural decisions so that we can avoid re-hashing the same decisions over and over.
+This document records the key architectural decisions made during the design and implementation of ArgsBarg.
 
-## HTTP REST vs flat `/tools/:name`
+---
 
-Decision: **nested `/api/...` REST** (7.0)
+## ADR 1: Exclusively Support Bun as the JavaScript/TypeScript Runtime
+
+### Status
+
+Accepted
 
 ### Context
 
-- v6 exposed tools as `POST /tools/:flat-name` with hyphen-joined paths
-- Nested resources (e.g. `workspaces/{id}`) and verb-specific methods need a route model aligned with the CLI tree
+We evaluated whether to build ArgsBarg as a dual-runtime library supporting both Node.js and Bun, or to target Bun exclusively. 
+
+Supporting Node.js requires maintaining complex build steps (transpilation, bundlers, CommonJS vs ESM dual-packaging, polyfills for HTTP serving) and limits the features we can offer to both the library and its consumers.
+
+### Decision
+
+Exclusively support Bun as the sole runtime for ArgsBarg and its consumer applications.
+
+### Consequences
+
+- **Pros:**
+  - **Zero-Build, Source-First Architecture:** Because Bun executes TypeScript and TSX directly from source, consumers can run their source code directly in production without any transpile or bundling steps (no Babel, Webpack, `ts-node`, or `tsx` required).
+  - **High-Performance Native HTTP (**`Bun.serve`**):** ArgsBarg's HTTP REST server is built directly on top of Bun's native, ultra-fast HTTP stack, offering millisecond-range startup times and massive throughput out of the box with zero boilerplate.
+  - **Native File and Text Imports:** ArgsBarg leverages Bun's native import attributes (e.g., `import readmeText from "./README.md" with { type: "text" }`) to bundle documentation and schemas at compile-time without reading the filesystem at runtime or requiring custom bundler plugins.
+  - **Unified, Lightweight Toolchain:** Both the framework and consumers benefit from Bun's native, ultra-fast package manager, built-in test runner (`bun test`), and zero-config TypeScript support, keeping the project's footprint and developer friction incredibly low.
+- **Cons (What We Lose):**
+  - **Loss of Node-Only Enterprise Tooling:** We lose out-of-the-box integration with legacy enterprise APMs (Application Performance Monitoring like Datadog, New Relic) and security/compliance scanners that are strictly compiled for Node.js runtimes or depend on Node's internal V8 debugging APIs.
+  - **Serverless Platform Friction:** Standard serverless platforms (e.g., AWS Lambda, Google Cloud Functions) have optimized native runtimes for Node.js, whereas running Bun on these platforms requires deploying custom layers or heavier Docker containers.
+  - **Reduced Addressable Library Adoption:** By locking out standard Node.js environments, we lose a significant portion of the mainstream Node.js developer base who cannot adopt Bun due to rigid corporate policies, legacy infrastructure, or strict compliance guidelines.
+  - **100% Node API Compatibility Guarantee:** While Bun's Node compatibility layer is exceptionally high, we lose the 100% absolute guarantee that legacy CommonJS packages or complex native C++ addons (N-API) will run flawlessly without minor polyfill adjustments.
+  - **No Node.js Execution Path:** Applications cannot run on standard Node.js without a separate bundling/transpilation layer, making ArgsBarg a Bun-exclusive framework.
+
+---
+
+
+
+## ADR 2: Schema-Driven Contracts via JSON Schema (vs Zod)
 
-### Rationale
 
-1. Command tree already encodes hierarchy — REST paths mirror `http.segment ?? key` plus `:param` routers
-2. Verb leaves (`get`, `post`, …) map to HTTP methods without duplicating path segments
-3. OpenAPI paths match real URLs clients call; query/body binding matches MCP flat args
-4. Hard break on `/tools/*` is acceptable pre-7.0-ship
 
-## Validation: JSON-SCHEMA vs Zod, etc
+### Status
 
-Decision: JSON-SCHEMA
+Accepted
 
 ### Context
-- JSON-SCHEMA is an open standard to capture a schema in json
-- Zod is the leading Typescript schema management library
-- Others are similar or less good than Zod
 
-### Rational
-Zod may actually cause more complexity and little/no gain for consumers. 
+We evaluated schema management and runtime validation libraries—specifically comparing the TypeScript-first library **Zod** against the industry-standard **JSON Schema** specification—for input and configuration contracts.
 
-Yes Zod implements some features we do custom for JSON-SCHEMA, but is opinionated, less flexible, and would actually explode complexity in some situations. Zod could be a win for consumers if they require substantial, complex validation -- but then that may not convert well to json-schema anyways and json-schema generation is a big win.
+### Decision
 
-1. Argsbarg does a lot of schema patching/manipulation to create different schemas per target (cli-schema.json, MCP contract, openapi.json). This would be harder with Zod
-2. Consumers can use Zod by converting to JSON Schema (`zod-to-json-schema`, `z.toJSONSchema()`) and passing the result to `inputSchema` / `appConfig.jsonSchema`. Argsbarg resolves the validator draft from each schema’s `$schema` (Draft-07 default; 2019-09 / 2020-12 when set).
-3. For uses like API pass-through, proxy, dynamic schemas, Zod may actually explode complexity for consumers.
-4. Our TS->json-schema approach is actually easier and better in many cases
-  - Just write plain typescript, done.
-  - Better intellisense -- substantially less abstraction/inference, much better control
+Adopt JSON Schema (using `@cfworker/json-schema` and `ts-json-schema-generator`) as the core validation format.
 
-## Structured logging (ECS Logging)
+### Consequences
 
-Decision: **ECS Logging–compatible NDJSON to stderr** (default), with optional `enrich` / `serialize` hooks
+- **Pros:**
+  - **Dynamic Manipulation:** Allows ArgsBarg to dynamically slice, patch, and transform schemas at runtime for different targets (CLI parser, MCP tools, OpenAPI JSON, and app configuration). This is far more complex to do with Zod.
+  - **Tooling Parity:** Integrates cleanly with a "write TypeScript, compile to schema" developer workflow.
+  - **Better IntelliSense:** Users write plain TypeScript interface definitions rather than chained Zod schemas, resulting in cleaner code and zero-abstraction IntelliSense.
+  - **Interop:** Consumers who prefer Zod can still use it and convert their schemas via `zod-to-json-schema` before passing them to ArgsBarg.
+- **Cons:**
+  - Fewer expressive, runtime-only custom validation features (like refinements and transformations) built into the framework core.
+
+---
+
+
+
+## ADR 3: Structured Logging (ECS-Compatible JSON)
+
+
+
+### Status
+
+Accepted (v6.1.9)
 
 ### Context
 
-- HTTP/MCP servers need access logs, error logs, and trace correlation in production log pipelines
-- Consumers may need custom fields (team labels, vendor-specific shapes) without baking proprietary formats into argsbarg core
-- OpenTelemetry log export is out of scope for the framework runtime (no third-party observability SDK dependency)
+HTTP and MCP servers require standard, trace-correlated, and easily digestible access and error logging for production pipelines (such as Datadog, Elasticsearch, and GCP logs). We wanted to deliver first-class, standard-compliant logs out of the box without introducing heavy third-party observability libraries or proprietary schemas.
+
+### Decision
+
+Emit server access and error logs to `stderr` formatted as Elastic Common Schema (ECS)-compatible NDJSON by default, with optional `program.log.enrich` and `program.log.serialize` hooks.
+
+### Consequences
 
-### Rationale
+- **Pros:**
+  - **Industry Standard:** ECS-compatible fields (`ecs.version`, `log.level`, etc.) play perfectly with all standard log collectors (ELK, Fluent Bit, Datadog).
+  - **Twelve-Factor Native:** Writing structured JSON to `stderr` keeps `stdout` clean for CLI command payloads and output redirects.
+  - **Distributed Tracing:** Standard W3C `traceparent` headers are automatically parsed and propagated without proprietary metadata layouts.
+  - **Zero Heavy Dependencies:** Avoids bundling heavy OpenTelemetry SDKs or other binary telemetry clients in the core open-source library.
+- **Cons:**
+  - Requires minor log collector or format mapper adjustments if the deployment environment is strictly standardized on a non-ECS log layout.
 
-1. **ECS Logging** is an open standard (NDJSON, `ecs.version`, canonical field names) — works with Elasticsearch, Datadog, GCP log agents, etc.
-2. **stderr + JSONL** keeps stdout free for CLI output and matches twelve-factor log collection
-3. **W3C Trace Context** (`traceparent`) enables cross-service correlation without vendor-specific field layouts
-4. **`program.log.enrich`** — additive hook for consumer-specific fields; cannot override the ECS baseline
-5. **`program.log.serialize`** — escape hatch for full custom lines in consumer repos (argsbarg does not endorse that output as ECS)
-6. **No Tyson / OTel SDK in core** — proprietary or heavy observability stacks belong in consumer config or infra (Fluent Bit remapping), not in the open-source framework

package/docs/developing.md

@@ -38,7 +38,7 @@ Sibling consumer repos (machine-specific paths in the root `justfile` `consumer_
 
 `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 rules** — `scripts/merge-cli-program-rule.ts` and `scripts/merge-code-rule.ts` copy templates from `examples/full-example/.cursor/rules/` into each consumer, preserving any existing `**… conventions:**` footer block.
+**Argsbarg authoring rules** — `scripts/merge-cli-program-rule.ts` and `scripts/merge-code-rule.ts` copy templates from `examples/full-example-json/.cursor/rules/` into each consumer, preserving any existing `**… conventions:**` footer block.
 
 **Recommended in each consumer:** replace template placeholders with `**<app> conventions:**` bullets. Commit those files; merges refresh the shared top, not your footer.
 
@@ -55,7 +55,7 @@ Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unr
 7. **Cursor rules:** `just consumers-dev` merges `cli-program.mdc` + `code.mdc` (includes **Abstractions** needless-extraction rule).
 8. **Verify:** `just test` and `just docgen` in each consumer repo.
 
-**Consumer app skill** — `just install-local` in each consumer (part of `consumers-sync`) runs Homebrew dev install then `myapp configure --sync --yes`, 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 `~/.agents/skills/<app>/` when `program.skill.enabled` — not the argsbarg framework rule.
 
 ## npm package contents
 
@@ -63,14 +63,14 @@ Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unr
 
 When adding docs or examples intended for consumers, ensure they live under whitelisted paths (`docs/`, `examples/`, `src/`, etc.).
 
-Exclude `examples/full-example/node_modules/` from the npm tarball via [`.npmignore`](../.npmignore).
+Exclude `examples/full-example/node_modules/` and `examples/full-example-json/node_modules/` from the npm tarball via [`.npmignore`](../.npmignore).
 
-## Full example
+## Copy templates
 
-[`examples/full-example/`](../examples/full-example/) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
+Both [`examples/full-example/`](../examples/full-example/) (CLI) and [`examples/full-example-json/`](../examples/full-example-json/) (schema-first) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
 
 ```bash
-just full-example-schemagen
+just example-full-check
 just test
 ```
 

package/docs/distribution-homebrew.md

@@ -1,159 +1,172 @@
-# Shipping via Homebrew (tap-from-repo)
+# Homebrew Distribution & Release Guide (Tap-from-Repo)
 
-Argsbarg apps distribute the **binary and shell completions** through Homebrew, and **agent artifacts** (skills, MCP config) through `configure --sync`.
+ArgsBarg provides native, first-class support for packaging, releasing, and distributing command-line binaries and shell autocomplete configurations through Homebrew via a standard **tap-from-repo** model. This is designed to serve as a secure, standard-compliant mechanism for internal enterprise distribution.
 
-## Distribution model
+---
 
-| Layer | Mechanism |
-| --- | --- |
-| Binary + completions | Formula `install` block |
-| Skills + MCP | Formula `post_install` → `{key} configure --sync --yes` |
-| App config file | Bootstrapped as `{}` on `post_install` via `--sync` (`~/.local/lib/<key>/config.json`) |
-| App config values | User opt-in: `{key} configure` (interactive wizard when `program.appConfig` has entries) |
-| App config cleanup | Formula `uninstall` → `{key} configure --remove-all --yes` |
+## 1. Enterprise Distribution Model
 
-**Only tap-from-repo** — in-repo `Formula/` or GitHub tap. Not Homebrew core.
+ArgsBarg maps the lifecycle of your application directly to standard Homebrew hooks, separating binary installation from user-interactive environment setup.
 
-### End-user install
+| Layer | Mechanism | Role in Lifecycle |
+| --- | --- | --- |
+| **Binary & Autocompletions** | Formula `install` block | Installs compiled binary and registers native shell autocompletions. |
+| **Telemetry & Agent Synclinks** | Formula `post_install` | Automatically runs `{key} configure --sync --yes` to bootstrap configuration files and sync developer tools. |
+| **Application Configuration** | User-facing `{key} configure` | Runs an interactive TTY setup wizard (only when `program.appConfig` defines required parameters). |
+| **Clean Uninstall** | Formula `uninstall` | Automatically runs `{key} configure --remove-all --yes` to clean up local configurations and symlinks. |
 
-For **private or internal GitHub taps**, authenticate with GitHub CLI before `brew install` or `brew upgrade` (release formulae download via the GitHub API; Homebrew discovers credentials from `gh auth login`).
+*Note: This architecture explicitly separates non-interactive installation (safe for automation/CI) from interactive configuration (which requires a TTY).*
 
-```bash
-brew install gh   # skip if already installed
-gh auth login     # skip if already authenticated
-```
+---
 
-Then:
+## 2. Distribution Strategies: Public vs. Private Taps
 
-```bash
-brew tap <org>/<repo> git@github.com:<org>/<repo>.git
-brew install <tap>/{key}
-{key} configure   # when app config is required
-```
-
-Upgrade:
-
-```bash
-brew upgrade {key}
-```
+ArgsBarg supports both open-source public formulas and secure private enterprise distribution. You can configure your repository structure depending on your project type.
 
-Local dev installs (`just install-local`) use a `file://` staging URL and do not need GitHub authentication.
+### Strategy A: Public Open-Source Taps (Default)
 
-### Developer install
+For open-source projects, Homebrew requires zero authentication. Users can tap your public repository and install your application with standard commands out of the box:
 
 ```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 (app config removed by formula uninstall)
-```
+# Tap the public repository
+brew tap <org>/<repo>
 
-Dev and release use the **same formula file** (`Formula/{key}.rb`). `just install-local` runs:
-
-```bash
-bun scripts/dev-formula.ts install    # back up release formula, write file:// dev formula
-brew install --formula <tap>/{key}  # install from the dev formula
-bun scripts/dev-formula.ts reset      # restore release formula
+# Install the application
+brew install <tap>/{key}
 ```
 
-If `brew install` fails, run `bun scripts/dev-formula.ts reset` manually to restore the release formula.
-
-### Developer uninstall
+The generated Homebrew formula points directly to your public GitHub release asset URL, allowing anyone to install and receive automatic updates securely.
 
-| Recipe | Removes |
-| --- | --- |
-| `just uninstall` | Formula `{key}` + tap symlink + skills/MCP + app config via formula `uninstall` |
-| `just uninstall-config` | App config file only (`configure --remove-config --yes`) |
-| `just uninstall-release` | Release formula from `{tap}` (keeps tap; agent artifacts via formula `uninstall`) |
-| `just uninstall-release-tap` | Release formula + `brew untap {tap}` (agent artifacts via formula `uninstall`) |
-| `just test-release` | Install release formula and run formula test |
+### Strategy B: Private & Proprietary Corporate Taps
 
-End users: `brew uninstall <tap>/<key>`. The formula `uninstall` hook runs `configure --remove-all --yes` (skills, MCP, and app config).
+For proprietary, inner-source, or internal company tools, security is paramount. ArgsBarg provides a built-in strategy to distribute packages securely from private GitHub repositories without exposing sensitive personal tokens or raw download links in your formula code.
 
-## Formula pattern
+#### 1. End-User Authentication:
+Users authenticate locally using the standard GitHub CLI (`gh`), which Homebrew natively integrates with to retrieve download credentials:
 
-```ruby
-def install
-  bin.install "{key}"
-  generate_completions_from_executable(bin/"{key}", "completion", base_name: "{key}")
-end
+```bash
+# 1. Install and authenticate with GitHub CLI (if not already done)
+brew install gh
+gh auth login
 
-def post_install
-  system bin/"{key}", "configure", "--sync", "--yes"
-end
+# 2. Tap and install your private corporate repository
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+brew install <tap>/{key}
 
-def uninstall
-  system bin/"{key}", "configure", "--remove-all", "--yes"
-end
+# 3. Perform interactive configuration (such as API tokens) if required
+{key} configure
 ```
 
-Release formulae generated by `scripts/formula-shared.ts` embed a `GitHubPrivateReleaseDownloadStrategy` that resolves the release asset through the GitHub API at download time and authenticates with `GitHub::API.credentials` (Homebrew discovers `gh auth login` automatically):
+#### 2. The Private Release Strategy:
+Release formulae generated by ArgsBarg's scripts utilize a custom **`GitHubPrivateReleaseDownloadStrategy`**. This strategy executes the secure asset download through standard GitHub API requests, leveraging the user's local `gh` login credentials securely under the hood:
 
 ```ruby
 url "https://github.com/<org>/<repo>/releases/download/vX.Y.Z/{key}",
     using: GitHubPrivateReleaseDownloadStrategy
 ```
 
-Local dev formulae (`just install-local`) use a plain `file://` URL and do not need the token.
+---
 
-Completions require users to configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
+## 3. Standardized Formula Pattern
 
-**Why the wizard is separate from `post_install`:** prompting for secrets requires a TTY. `post_install` only bootstraps an empty `config.json` and refreshes skills/MCP. Apps with `appConfig` print a one-line configure hint in formula `caveats` for the interactive wizard.
+ArgsBarg standardizes your Homebrew formulas. A typical generated formula (`Formula/{key}.rb`) is incredibly clean:
 
-**MCP hosts:** when `mcpServer.enabled` is true, add a caveats line that chat apps (Cursor, Claude Desktop, etc.) must be **restarted** after `brew install` / `brew upgrade` — `post_install` updates MCP config on disk, but hosts typically load it only at startup.
+```ruby
+class Myapp < Formula
+  desc "My application description"
+  homepage "https://github.com/org/myapp"
+  url "https://github.com/org/myapp/releases/download/v1.0.0/myapp.zip"
+  sha256 "a1b2c3d4e5f6g7h8..."
+  version "1.0.0"
+
+  def install
+    bin.install "myapp"
+    # Auto-generates shell completions for bash, zsh, and fish directly from the executable
+    generate_completions_from_executable(bin/"myapp", "completion", base_name: "myapp")
+  end
+
+  def post_install
+    # Non-interactive bootstrap of config files and developer links
+    system bin/"myapp", "configure", "--sync", "--yes"
+  end
+
+  def uninstall
+    # Graceful clean up of local files on uninstall
+    system bin/"myapp", "configure", "--remove-all", "--yes"
+  end
+  
+  def caveats
+    <<~EOS
+      Interactive configuration is required. Please run:
+        myapp configure
+    EOS
+  end
+end
+```
 
-## 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):
+## 4. Developer Iteration Workflow
 
-```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
-```
+ArgsBarg provides an optimized workflow for developers to build, package, and test their Homebrew installer locally before pushing releases.
 
-On a TTY, omit flags to use the interactive wizard. Verify an existing tree:
+### Local Staging Commands:
 
 ```bash
-bunx argsbarg create --check .
+# 1. Build the local release binary
+just build
+
+# 2. Stage and install the formula locally (bypasses GitHub, uses file://)
+just install-local
+
+# 3. Swap updated binaries quickly during tight edit cycles
+just reinstall-local
+
+# 4. Uninstall the binary and gracefully clean up all configurations
+just uninstall
 ```
 
-Template source: [`examples/full-example/`](../examples/full-example/) in the argsbarg package (also under `node_modules/argsbarg/examples/full-example` after `bun add argsbarg`).
+### Under the Hood:
 
-**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`.
+To ensure you test the exact formula that will be shipped to production, `just install-local` runs:
 
-## Release workflow
+1.  `bun scripts/dev-formula.ts install` — Safely backs up your production formula and writes a temporary local dev formula using a `file://` URL pointing to your build directory.
+2.  `brew install --formula <tap>/{key}` — Installs the package locally using Homebrew.
+3.  `bun scripts/dev-formula.ts reset` — Automatically restores your production formula on disk.
 
-1. `just build` → `dist/{key}`
-2. `scripts/release.ts` → zips `dist/{key}` to `dist/{key}.zip`, writes `Formula/{key}.rb` (GitHub zip URL + archive sha256), commits, tags, uploads `dist/{key}.zip` to GitHub Releases
-3. Users `brew upgrade {key}` from the tap
+---
 
-Requires the `zip` CLI on the release machine. `just install-local` still stages the bare binary via `file://` (no zip).
+## 5. Automated Release Pipeline
 
-### Stale release cleanup
+ArgsBarg automates the release cycle. A production-ready release is performed using a single command:
 
 ```bash
-just release --purge              # delete all GitHub releases except the newest (confirm on TTY)
-just release --purge --yes        # skip confirmation
-just release --purge --dry-run    # list tags that would be deleted
-just release patch --purge        # release, then purge older releases
+# Performs build, zips binary, updates Formula with new SHA-256, tags git, pushes, and uploads release asset
+just release patch   # or minor | major
 ```
 
-`--purge` removes GitHub Release records and attached assets only — git tags remain on the remote. Old formula pins that reference deleted release URLs will fail until users upgrade.
+### Release Pipeline Steps:
 
-## Removed (breaking)
+1.  **Build**: Compiles the binary to `dist/{key}`.
+2.  **Archive**: Packages the binary into a compressed `dist/{key}.zip`.
+3.  **Integrity Check**: Calculates the cryptographically secure SHA-256 hash of the zip file.
+4.  **Formula Sync**: Updates the version number and `sha256` parameter in `Formula/{key}.rb`.
+5.  **Tag & Push**: Commits changes, tags the repository with the new version, pushes to GitHub, and publishes the compiled zip to GitHub Releases.
 
-- 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
+### Older Release Retention & Cleanup:
+
+To keep your storage footprint clean, the pipeline supports purging stale historical release assets while preserving the git tags:
+
+```bash
+just release --purge              # Interactive tag purge of older release records
+just release --purge --yes        # Silent automated purge (useful in CI/CD)
+just release --purge --dry-run    # Preview list of tag deletions
+```
 
-## Config path
+---
 
-Default: `~/.local/lib/<sanitized-key>/config.json`
+## 6. Directory Defaults
 
-Export helpers: `resolveAppConfigPath`, `displayAppConfigPath` from `argsbarg`.
+Applications packaged via ArgsBarg adhere to standard system directories:
+*   **Resolved Configuration Path**: `~/.local/lib/<sanitized-key>/config.json`
+*   **Auto-Exports**: Developers can import `resolveAppConfigPath` or `displayAppConfigPath` directly from `argsbarg` to display helpful directories in help screens.