argsbarg 6.1.9 → 6.1.10

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.10] - 2026-07-29
+
+### Changed
+
+- Update docs
+
 ## [6.1.9] - 2026-07-27
 
 ### Added
@@ -879,7 +885,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.9...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.10...HEAD
+[6.1.10]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.10
 [6.1.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.9
 [6.1.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.8
 [6.1.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.7

package/README.md

@@ -5,32 +5,48 @@ Logo
 [npm version](https://www.npmjs.com/package/argsbarg)
 [Bun](https://bun.sh)
 
-Build beautiful, well-behaved CLI+MCP+HTTP apps with Bun — **no third-party runtime dependencies**. 
+Build beautiful, well-behaved, production-grade CLIs, HTTP REST services, MCP Servers for Bun from a single, unified schema. All with only 2 modest dependencies.
 
-Why another CLI parser?
+Why ArgsBarg?
 
-*Schema-first* — define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface auto-validated, centralized, clear, and self-describing upfront.
+*Schema-first & Auto-validated* — Define your entire command structure, options, description, and inputs once. ArgsBarg compiles this into type-safe option accessors, command-line routing, and validation schemas, keeping your code and interfaces perfectly aligned.
 
-*AI Friendly* — Generate and install rich skills, mcp server, docs based on the schema.
+*Automated Schemagen & Docgen* — Maintain single-source truth by decorating standard TypeScript types (`/** @sg */ interface...`) to automatically compile them into runtime validation schemas (`argsbarg schemagen`). Easily export standard-compliant API documentation, full CLI reference markdown, OpenAPI 3.1 definitions, and agent skill sheets directly from your code (`docs --save` command) using introspection.
 
-*Beautiful* `-h` *screens* — scoped help at any routing depth, rendered in rounded UTF-8 boxes with tables, terminal-width wrapping, and color when stdout is a TTY. Errors print in red with contextual help on stderr.
+*Production REST Server* — Instantly expose your commands as HTTP REST endpoints (`POST /v1/some-command`) with built-in Kubernetes-compliant `/health/liveness` and `/health/readiness` probes, ECS structured JSON logging to `stderr`, and auto-generated OpenAPI 3.1 specs with an interactive Swagger UI.
 
-*Shell completions* — `completion bash`, `completion zsh`, and `completion fish` built-ins generate scripts consumed by Homebrew during formula `install` (`generate_completions_from_executable`). See [docs/distribution-homebrew.md](docs/distribution-homebrew.md).
+*First-Class Homebrew Distribution* — Exposes robust native support for packaging and distributing compiled binaries and shell completions cleanly via a standard tap-from-repo Homebrew model. Includes built-in completion script generators (`completion bash`/`zsh`/`fish`) consumed by Homebrew's standard `generate_completions_from_executable` command out of the box, ensuring friction-free installations and updates for your developers.
+
+*High-Performance & Light Footprint* — Optimized specifically for Bun. Executes TypeScript and TSX source files directly with no transpile or bundling steps required, leveraging `Bun.serve` for rapid startup and low memory usage. Ships with only two production dependencies (`@cfworker/json-schema` and `ts-json-schema-generator`).
 
-*Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
+*Beautiful* `-h` *screens* — Scoped help at any routing depth, rendered in rounded UTF-8 boxes with tables, terminal-width wrapping, and color when stdout is a TTY. Errors print in red with contextual help on stderr.
+
+*Shell completions* — `completion bash`, `completion zsh`, and `completion fish` built-ins generate scripts consumed by Homebrew during formula `install` (`generate_completions_from_executable`). See [docs/distribution-homebrew.md](docs/distribution-homebrew.md).
 
 Also checkout ArgsBarg for [cpp](https://github.com/bdombro/cpp-argsbarg), [nim](https://github.com/bdombro/nim-argsbarg), and [swift](https://github.com/bdombro/swift-argsbarg)!
 
 Halps! -->
 help-preview.png
+[help-preview.png](docs/help-preview.png)
+
 
 Sub-level Halps! -->
 help-l2-preview.png
+[help-l2-preview.png](docs/help-l2-preview.png)
 
 Shell completions! -->
 completions-preview.png
+[completions-preview.png](docs/completions-preview.png)
+
+Production-grade HTTP Server! -->
+```sh
+$ myapp http
+{"@timestamp":"2026-07-29T10:23:59.094Z","message":"HTTP API listening on http://127.0.0.1:13000",...}
+{"@timestamp":"2026-07-29T10:23:59.194Z","message":"GET /health/liveness","ecs.version":"8.11.0",...}
+{"@timestamp":"2026-07-29T10:23:59.195Z","message":"server stopping","ecs.version":"8.11.0",...}
+```
 
-## Usage
+## Basic Usage
 
 ```typescript
 import { Cli, type CliProgram, CliOptionKind } from "argsbarg";
@@ -85,83 +101,123 @@ Everything you need for a first-class CLI:
 - **Rich help**: rounded UTF-8 boxes, tables, terminal width detection (`process.stdout.columns`), colors when stdout/stderr is a TTY
 - **TypeScript-native**: Typed option accessors (`ctx.typedOpt<T>`) and `async/await` handler support.
 
+## Getting Started
 
+You can either quickly bootstrap a complete, feature-rich project skeleton using our CLI creator or manually integrate ArgsBarg into an existing codebase.
 
-## Built-ins
+### Option A: Bootstrap a New Project (Recommended)
 
-Every app gets:
+ArgsBarg provides an interactive project generator to scaffold a new repository fully equipped with TypeScript, Biome, automated schemagen/docgen, standard testing, and Homebrew integration rules:
 
-- `-h` / `--help` at any routing depth (scoped help).
-- `completion bash` **/** `completion zsh` **/** `completion fish` — print shell completion scripts to stdout (injected by `Cli.run()`).
-- `version` — print `CliProgram.version` (`myapp version`).
-- `mcp` — when `mcpServer.enabled` is `true`, run as an MCP stdio server (`myapp mcp`).
-- `http` — when `httpServer.enabled` is `true`, run as an HTTP tool server (`myapp http`).
-- `docs` — print bundled markdown topics, schema JSON, CLI markdown, and generated skill content (`myapp docs cli`, `myapp docs cli-schema`, `myapp docs skill`, …). Enabled by default; opt out with `docs: { enabled: false }`. See [docs/bundled-docs.md](docs/bundled-docs.md).
-- `configure` — manage agent skills, MCP config, and app config (`myapp configure --sync --yes` after Homebrew install). See [docs/configure.md](docs/configure.md).
+```bash
+# Interactive setup (prompts for naming and git configurations)
+bunx argsbarg create my-app
 
-Do not declare a top-level command named `completion`, `version`, or `configure` — they are reserved.
-When `mcpServer.enabled` is `true`, do not declare a top-level command named `mcp` — it is reserved for the MCP built-in.
-When `httpServer.enabled` is `true`, do not declare a top-level command named `http` — it is reserved for the HTTP built-in.
-When docs is enabled (default), do not declare a top-level command named `docs` — it is reserved for the docs built-in. Opt out with `docs: { enabled: false }` if needed.
+# Non-interactive / Headless setup
+bunx argsbarg create my-app \
+  --key my-cli --release-repo org/my-cli --yes
+```
 
-### MCP (AI agents)
+Edit `scripts/create-identity.ts` in the new repository to set your description. The `create` command copies the full-featured template, runs `bun install`, bootstraps a git repository (if standalone), and runs initial validation tests.
 
-Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `<sanitized-key>://schema` (same as `myapp docs cli-schema`). Handlers can read `ctx.invocation`; use `cli.invoke(argv)` for headless testing.
+#### What the bootstrapped template includes:
 
-See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details. See **[docs/cli-program.md](docs/cli-program.md)** for schema authoring (consumer apps: run `bunx argsbarg create` or refresh with `bun scripts/merge-cli-program-rule.ts .` from the argsbarg package).
+| Area                  | Files / wiring                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| All built-ins          | `completion`, `version`, `configure`, `docs`, `mcp`, `http`, `configure get`/`set`       |
+| `@sg` schemagen       | `/** @sg */` on types in `src/**/*.ts` → `{TypeName}Schema` in `__generated__/`          |
+| `outputSchema`        | `src/commands/status/types.ts` → `StatusJsonOutputSchema` from `__generated__/`          |
+| Schemagen             | `just schemagen` → `argsbarg schemagen` (justfile exports `node_modules/.bin` on `PATH`) |
+| 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/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`                                |
 
-### HTTP tool server
+*Tip: Verify an existing tree or template setup with `bunx argsbarg create --check .`*
 
-Opt in on the program root with `httpServer: { enabled: true }`, then run `myapp http` for an HTTP REST server (default `http://127.0.0.1:3000`). Nested CLI paths map to REST routes at the server root by default (e.g. `/workspaces`); set `httpServer.pathPrefix: "/api"` to prefix all user routes. Discover routes via `GET /openapi.json`.
+### Option B: Manual Installation (For Existing Projects)
 
-See **[docs/http-server.md](docs/http-server.md)** for endpoints, curl examples, and response shapes.
+To manually integrate ArgsBarg into your existing Bun application: `bun add argsbarg`.
 
-### Configure CLI
 
-Ship via **Homebrew** (tap-from-repo). The formula installs the binary and shell completions; `post_install` runs agent artifact refresh. Private taps require `gh auth login` — see [docs/distribution-homebrew.md](docs/distribution-homebrew.md#end-user-install).
+## Built-in Commands
 
-```bash
-brew install gh
-gh auth login
-brew tap <org>/<repo> git@github.com:<org>/<repo>.git
-brew install <tap>/myapp
-myapp configure    # interactive per-target setup; opt-in app config wizard
-```
+ArgsBarg automatically integrates several core features into your application. These are divided into stable core capabilities and optional experimental integrations:
+
+### Core Capabilities (Stable)
+
+- `-h` / `--help` — Highly-formatted, terminal-width scoped help at any routing depth.
+- `version` — Print the program's version (e.g., `myapp version`).
+- `http` — Launch the high-performance HTTP REST server (injected when `httpServer.enabled` is `true`).
+- `completion bash` / `zsh` / `fish` — Generate shell completion scripts to stdout for deployment and packaging.
+- `docs` — Print bundled markdown topics, schema JSON, or CLI reference markdown (`myapp docs cli`, `myapp docs cli-schema`, etc.). Enabled by default; see [docs/bundled-docs.md](docs/bundled-docs.md).
+- `configure get` / `set` — Query and update application-level configurations non-interactively (active when `program.appConfig` contains configuration schema entries).
+
+### Experimental Integrations (Opt-in)
 
-See **[docs/distribution-homebrew.md](docs/distribution-homebrew.md)** for formula patterns and `bunx argsbarg create`. See **[docs/configure.md](docs/configure.md)** for `configure`, `--sync`, `--remove-all`, and `--status`.
+- `mcp` — Run as a Model Context Protocol stdio-based agent server (injected when `mcpServer.enabled` is `true`). See [docs/mcp.md](docs/mcp.md).
+- `configure` (`--sync` / `--status` / `--remove-all`) — Interactive environment setup and developer agent credentials sync (enabled by default; opt out with `configure: { enabled: false }`). See [docs/configure.md](docs/configure.md).
 
-### Shell completions
+Do not declare top-level commands named `completion`, `version`, or `docs` as they are reserved by default. If their respective features are enabled, `http`, `mcp`, and `configure` are also reserved.
 
-Homebrew installs completion scripts during `brew install` via `generate_completions_from_executable`. The CLI still exposes generation for formula authors:
+## HTTP REST Server
+
+By opting in with `httpServer: { enabled: true }` on your program root, running your app with the `http` subcommand launches a high-performance HTTP REST server powered natively by `Bun.serve`. This is ideal for sidecars, microservices, and micro-container deployments (such as in Kubernetes).
+
+Nested command paths map directly to standard REST paths (e.g., `v1 invoices render` maps to `POST /v1/invoices/render`).
+
+```typescript
+const cli = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "My service.",
+  httpServer: { enabled: true, port: 3000 },
+  commands: [/* ... */],
+} satisfies CliProgram;
+```
 
 ```bash
-myapp completion bash
-myapp completion zsh
-myapp completion fish
+myapp http --port 3000
 ```
 
-Users configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
 
-## Quick Start
+
+### Key HTTP Features:
+
+- **Built-in Health Checks** — Automatic `/health/liveness` (responds 200 when online) and `/health/readiness` (responds 200 when online and config validation passes) probes out of the box, compliant with container orchestrators.
+- **OpenAPI 3.1 Spec & Swagger UI** — Serves standard `/openapi.json` and a `/swagger` interactive API browser generated directly from your command schema and JSDoc metadata.
+- **Pre-Handler Schema Validation** — Incoming request payloads are validated against the compile-time JSON Schema (`inputSchema`) on leaf commands before your handler ever runs.
+- **ECS Structured Logging** — Access and error logs are automatically structured as Elastic Common Schema (ECS) JSON objects and written to `stderr` (e.g., for Datadog or ELK collection).
+- **W3C Distributed Tracing** — Automatically parses, propagates, and echoes `traceparent` headers for distributed tracing pipelines.
+
+See **[docs/http-server.md](docs/http-server.md)** for details on endpoints and response shapes, and **[docs/logging.md](docs/logging.md)** for log configurations.
+
+## Distribution & Packaging (Homebrew)
+
+ArgsBarg is built to distribute the compiled binary and shell completions cleanly through Homebrew via a standard **tap-from-repo** model.
+
+### Installation & Post-Install Setup:
 
 ```bash
-bun add argsbarg
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+brew install <tap>/myapp
 ```
 
+During installation, Homebrew registers the built-in generated shell completions automatically via `generate_completions_from_executable` (see [docs/distribution-homebrew.md](docs/distribution-homebrew.md)).
 
+### Shell Completions:
 
-### Cursor / AI agents
-
-Argsbarg ships authoring docs in `node_modules/argsbarg/docs/`. Agents do not load them unless your repo points there — copy the thin Cursor rule after install (it tells agents to **read** `cli-program.md`, not duplicate it):
+Completion scripts can also be output directly at any time for manual setups or formula auditing:
 
 ```bash
-mkdir -p .cursor/rules
-mkdir -p .cursor/rules
-bun scripts/merge-cli-program-rule.ts . \
-  node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc
+myapp completion bash
+myapp completion zsh
+myapp completion fish
 ```
 
-Add app-specific conventions in a second rule if needed. Copy the rule from the template, then add a `**<your-app> conventions:**` block at the bottom (see **Cursor rule** in [docs/cli-program.md](docs/cli-program.md)). Documentation map: **[docs/README.md](docs/README.md)**.
+
 
 ## How it works
 
@@ -230,7 +286,7 @@ Check the `examples/` directory for full working scripts:
 | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
 | `ArgsBargMinimal`     | `examples/minimal.ts`    | String + presence flags, `MissingOrUnknown` fallback.                                             |
 | `ArgsBargNested`      | `examples/nested.ts`     | Nested command tree, positional tails, async handlers.                                            |
-| `ArgsBargFormats`     | `examples/formats.ts`    | `CliValueFormat`, `default`, `ctx.inputs`.                                                  |
+| `ArgsBargFormats`     | `examples/formats.ts`    | `CliValueFormat`, `default`, `ctx.inputs`.                                                        |
 | `ArgsBargFullExample` | `examples/full-example/` | **Copy template:** all builtins, schemagen, Homebrew justfile, `outputSchema`, `from "argsbarg"`. |
 
 
@@ -266,21 +322,21 @@ To refresh Cursor rules in an existing consumer: `bun scripts/merge-cli-program-
 ### What the full-example template includes
 
 
-| Area                  | Files / wiring                                                                         |
-| --------------------- | -------------------------------------------------------------------------------------- |
-| All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `http`, `configure get`/`set`      |
-| `@sg` schemagen       | `/** @sg */` on types in `src/**/*.ts` → `{TypeName}Schema` in `__generated__/`         |
-| `outputSchema`        | `src/commands/status/types.ts` → `StatusJsonOutputSchema` from `__generated__/`         |
+| Area                  | Files / wiring                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `http`, `configure get`/`set`       |
+| `@sg` schemagen       | `/** @sg */` on types in `src/**/*.ts` → `{TypeName}Schema` in `__generated__/`          |
+| `outputSchema`        | `src/commands/status/types.ts` → `StatusJsonOutputSchema` from `__generated__/`          |
 | Schemagen             | `just schemagen` → `argsbarg schemagen` (justfile exports `node_modules/.bin` on `PATH`) |
-| 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/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`                              |
+| 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/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`                                |
 
 
-When changing builtins or the template, run `just check-full-example` from the argsbarg repo root.
+When changing builtins or the template, run `just example-full-check` from the argsbarg repo root.
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -301,6 +357,42 @@ just run status --json
 
 
 
+## [Experimental] AI Agent & Copilot Integrations
+
+ArgsBarg includes optional experimental features designed to make your CLI and services easily discoverable and executable by modern developer AI agents (such as Cursor, Claude Code, and standard MCP clients). These are entirely opt-in and do not affect the footprint, performance, or stability of the core CLI and HTTP layers.
+
+### 1. Model Context Protocol (MCP) Server
+
+Opt in by setting `mcpServer: { enabled: true }` on your program root. Running `myapp mcp` starts a JSON-RPC 2.0 stdio server.
+
+- **Automatic Tool Exposure** — Every leaf command in your CLI tree becomes an executable MCP tool with inputs automatically generated from your CLI options.
+- **Documentation Resources** — Your CLI structure, JSON schemas, and bundled `docs.topics` are automatically exposed to agents as resources (e.g., `<key>://schema`).
+- **Context-Aware Invocations** — Handlers can read `ctx.invocation` to distinguish between direct CLI, HTTP requests, or headless MCP calls.
+
+See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor/Claude setup, and protocol details.
+
+### 2. IDE Copilot Rules (Cursor / Claude Code)
+
+ArgsBarg ships authoring docs under `node_modules/argsbarg/docs/`. Because AI agents do not automatically read inside `node_modules/`, you can copy a thin custom rule into your project:
+
+```bash
+mkdir -p .cursor/rules
+bun scripts/merge-cli-program-rule.ts . \
+  node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc
+```
+
+This acts as a "tripwire" that instructs AI agents in your workspace to read ArgsBarg's framework documentation before modifying your command definitions or schemas. See the **Cursor rule** section in [docs/cli-program.md](docs/cli-program.md).
+
+### 3. Generated Skills & Workspace Configuration
+
+Running `myapp configure` launches an interactive setup wizard that can automatically write compact `SKILL.md` index files and full-reference markdown files (`reference.md`) directly into your global IDE directories (e.g., `~/.cursor/skills/` or `~/.claude/skills/`).
+
+See **[docs/configure.md](docs/configure.md)** and **[docs/ai-skills.md](docs/ai-skills.md)** for developer setup and automated Homebrew pipeline integration.
+
+---
+
+
+
 ## Public API overview
 
 The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you need to define a schema and run it. Parsing, completion script generation, help rendering, and schema pre-validation live in other modules under `src/` for tests and advanced integrations.
@@ -311,8 +403,8 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | `CliProgram`, `CliOption`, `CliPositional`, `CliHandler`          | Schema and handler types.                                                                                                                      |
 | `CliOptionKind`, `CliValueFormat`, `CliFallbackMode`              | Option kinds, value formats (`duration`, `comma-list`, `date`, `date-time`), and root fallback behavior.                                       |
 | `CliSchemaValidationError`                                        | Thrown when the static command tree violates schema rules.                                                                                     |
-| `CliContext`                                                      | Handler context (`ctx.hasFlag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.inputs`, `ctx.invocation`, …).                                |
-| `CliLeafInputs`                                                   | Record type returned by `ctx.inputs` — coerced option/positional values keyed by schema name.                                            |
+| `CliContext`                                                      | Handler context (`ctx.hasFlag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.inputs`, `ctx.invocation`, …).                                        |
+| `CliLeafInputs`                                                   | Record type returned by `ctx.inputs` — coerced option/positional values keyed by schema name.                                                  |
 | `Cli`                                                             | Runtime: validate + freeze program, `run()`, `invoke()`, `serveMcp()`, `appConfig` getter, `exportCommandSchema()`, `exportAppConfigSchema()`. |
 | `CliInvokeResult`, `CliInvokeKind`                                | Result types from `cli.invoke()`.                                                                                                              |
 | `CliAppConfig`, `CliAppConfigEntry`                               | App config block on the program root (`entries` metadata overlay + optional `jsonSchema`).                                                     |

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

@@ -70,7 +70,7 @@ Exclude `examples/full-example/node_modules/` from the npm tarball via [`.npmign
 [`examples/full-example/`](../examples/full-example/) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
 
 ```bash
-just full-example-schemagen
+just example-full-schemagen
 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.

package/examples/full-example/docs/http.md

@@ -1,3 +1,5 @@
+<!-- Generated by full-example docs http --save; do not edit. -->
+
 # HTTP API (full-example)
 
 full-example exposes user commands over HTTP REST routes derived from the CLI tree.
@@ -10,7 +12,7 @@ full-example http
 
 Listens on **http://127.0.0.1:3000** by default (`httpServer.host` / `httpServer.port`).
 
-Bind is localhost-only in v0 — use a reverse proxy for remote access.
+Bind is localhost-only by default — use a reverse proxy for remote access.
 
 ## Endpoints
 

package/examples/full-example/justfile

@@ -34,6 +34,22 @@ migrate DB="./workspaces.db":
 # Run schemagen, typecheck, and format
 check: schemagen format typecheck
 
+# demo the HTTP API
+demo-http:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    bun ./src/index.ts http --port 13000 &
+    trap 'kill $! 2>/dev/null || true' EXIT
+    until curl -sf http://127.0.0.1:13000/health/liveness >/dev/null; do sleep 0.1; done
+
+# demo a CLI command
+demo-cli:
+    @just run {{cli_key}} status
+
+# demo a CLI command
+demo-help:
+    @just run {{cli_key}} --help
+
 # Run the CLI from source with optional args; restarts on file changes
 dev *ARGS:
     bun --watch ./src/index.ts {{ARGS}}
@@ -53,6 +69,10 @@ alias fmt := format
 format:
     bun run biome check ./src ./scripts --write --unsafe
 
+# Run the HTTP server
+http:
+    @just run http
+
 # Alias for backward compatibility
 install: install-local
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.1.9",
+  "version": "6.1.10",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/docs/http-guide.ts

@@ -45,7 +45,7 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     `Listens on **${baseUrl}** by default (\`httpServer.host\` / \`httpServer.port\`).`,
     "",
-    "Bind is localhost-only in v0 — use a reverse proxy for remote access.",
+    "Bind is localhost-only by default — use a reverse proxy for remote access.",
     "",
     "## Endpoints",
     "",

package/src/docs/save.ts

@@ -8,7 +8,7 @@ import { docsTopicContent } from "./resolve.ts";
 export const DOCS_SAVE_DIR = "docs";
 
 /** Builtin docs topics generated by argsbarg (not consumer `docs.topics`). */
-export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "cli", "skill"] as const;
+export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "cli", "skill", "http"] as const;
 
 /** Whether `--save` should prepend a generated-file hint (argsbarg writers only). */
 export function docsTopicIsGeneratedByArgsbarg(topic: string): boolean {