argsbarg 5.1.16 → 6.0.1

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.0.1] - 2026-07-22
+
+### Added
+
+- **OpenAPI schema dereferencing** — inline internal `$ref` pointers when building OpenAPI documents so API reference UIs show nested request shapes.
+
+### Changed
+
+- **Schemagen discovery contract** — `examples/full-example` and docs now use `src/**/schema-types.ts` with `export type configType` / `outputType` / `inputType` instead of JSDoc markers (`Config schema`, `JSON payload`, `Tool input`) on `types.ts`.
+- **HTTP tool errors** — return a plain `{ "error": "..." }` JSON body without ANSI color codes or appended CLI help text.
+- **`cliErrWithHelp`** — on `api` / `mcp` invocations, throws a plain error instead of printing contextual help.
+- **`GET /openapi-browser`** — Scalar config preserves schema property order from the OpenAPI document (`orderSchemaPropertiesBy: "preserve"`).
+
+## [6.0.0] - 2026-07-22
+
+### Added
+
+- **`apiServer`** — opt-in HTTP tool server (`myapp api`). Exposes leaf commands over `GET /health`, `GET /openapi.json`, `GET /openapi-browser`, and `POST /tools/:name`. Defaults to `127.0.0.1:3000`. Independent of `mcpServer`.
+- **`ctx.respond()`** — set machine-readable responses for API/MCP; polymorphic CLI stdout printing.
+- **Implicit handler return values** — non-undefined return values become JSON responses for headless invocations.
+- **`apiResponse`** leaf metadata — default HTTP `Content-Type` and `Content-Disposition`.
+- **`generateOpenApi(program)`** — hand-built OpenAPI 3.1 document; served at `GET /openapi.json`.
+- **`GET /openapi-browser`** — Scalar API reference UI (CDN). Replaces `GET /docs`.
+- **`ctx.toolArgs`** — original flat tool JSON for API/MCP handlers with custom `inputSchema`.
+- **Wide-open CORS** — `Access-Control-Allow-Origin: *` on all API responses.
+- **`docs http`** — auto-generated HTTP API guide when `docs` and `apiServer` are both enabled.
+- **`docs openapi`** — print OpenAPI 3.1 JSON (`myapp docs openapi`); save with `--save` to `./docs/openapi.json` when `apiServer` is enabled.
+- **`Cli.invoke(argv, { invocation, toolArgs })`** — optional invocation source (`"mcp"` default, `"api"` for HTTP).
+- **`ctx.invocation === "api"`** — headless helpers treat API like MCP.
+
+### Changed
+
+- **HTTP success responses** — raw body (JSON/HTML/PDF bytes); no `{ ok, stdout, stderr }` envelope.
+- **MCP/API tool handlers** — must `ctx.respond()` or return a value; stdout is not part of success payloads.
+- **MCP binary** — `Uint8Array` responses encoded as base64 in `structuredContent`.
+- **Removed `POST /tools`** — MCP-shaped invoke endpoint; use `POST /tools/:name` only.
+- **HTTP API tool names** — hyphen-joined command paths (e.g. `render-invoice`, `stat-owner-lookup`); MCP keeps underscore-sanitized names (`render_invoice`, `stat_owner_lookup`).
+- **Removed `GET /docs`** — use **`GET /openapi-browser`** for the Scalar API reference UI.
+- **Removed `GET /schema`** from the HTTP API — use `myapp docs cli-schema`, MCP `://schema`, or `GET /openapi.json` / `docs openapi` instead.
+- **Removed `GET /tools`** from the HTTP API — use `GET /openapi.json` for tool discovery.
+- **Renamed `docs schema` → `docs cli-schema`** — saved file is `./docs/cli-schema.json` (disambiguates CLI tree JSON from OpenAPI and JSON Schema artifacts).
+- **Custom `inputSchema`** on leaves is used for MCP/HTTP tool metadata when set.
+
 ## [5.1.16] - 2026-07-07
 
 
@@ -685,7 +728,9 @@ 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/v5.1.16...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.0.1...HEAD
+[6.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.1
+[6.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.0
 [5.1.16]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.16
 [5.1.15]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.15
 [5.1.14]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.14

package/README.md

@@ -1,13 +1,11 @@
 Logo
 
-
-
 [GitHub](https://github.com/bdombro/bun-argsbarg)
 [License: MIT](LICENSE)
 [npm version](https://www.npmjs.com/package/argsbarg)
 [Bun](https://bun.sh)
 
-Build beautiful, well-behaved CLI+MCP apps with Bun — **no third-party runtime dependencies**. 
+Build beautiful, well-behaved CLI+MCP+HTTP apps with Bun — **no third-party runtime dependencies**. 
 
 Why another CLI parser?
 
@@ -97,19 +95,27 @@ Every app gets:
 - `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`).
-- `docs` — when `docs.enabled` is `true`, print bundled markdown topics, schema JSON, API markdown, and generated skill content (`myapp docs`, `myapp docs readme`, `myapp docs schema`, `myapp docs api`, `myapp docs skill`, …). See [docs/bundled-docs.md](docs/bundled-docs.md).
+- `api` — when `apiServer.enabled` is `true`, run as an HTTP tool server (`myapp api`).
+- `docs` — when `docs.enabled` is `true`, print bundled markdown topics, schema JSON, API markdown, and generated skill content (`myapp docs`, `myapp docs readme`, `myapp docs cli-schema`, `myapp docs api`, `myapp docs skill`, …). 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).
 
 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 `apiServer.enabled` is `true`, do not declare a top-level command named `api` — it is reserved for the HTTP API built-in.
 When `docs.enabled` is `true`, do not declare a top-level command named `docs` — it is reserved for the docs built-in.
 
 ### MCP (AI agents)
 
-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 schema`). Handlers can read `ctx.invocation`; use `cli.invoke(argv)` for headless testing.
+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.
 
 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).
 
+### HTTP API
+
+Opt in on the program root with `apiServer: { enabled: true }`, then run `myapp api` for an HTTP tool server (default `http://127.0.0.1:3000`). Same tool exposure as MCP: `POST /tools/:name` (hyphen-joined command paths). Discover tools via `GET /openapi.json`.
+
+See **[docs/api-server.md](docs/api-server.md)** for endpoints, curl examples, and response shapes.
+
 ### 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).
@@ -161,7 +167,7 @@ Add app-specific conventions in a second rule if needed. Copy the rule from the
 
 1. Build a **program root** with `satisfies CliProgram` (or `: CliProgram`): `key` is the app name, `commands` are top-level subcommands, `options` are global flags. A router root must not set `handler` or declare `positionals` (validated at startup). A leaf root may set `handler` and `positionals` directly. Use `fallbackCommand` / `fallbackMode` on any **routing node** for default subcommand routing (not root-only).
 2. Call `await new Cli(program).run()` — validates, parses argv, renders help or errors, invokes the leaf handler, and `process.exit`s with status **0** on success, **1** on implicit help or error (explicit `--help` → **0**).
-3. From a handler, `cliErrWithHelp(ctx, "message")` prints a red error line plus contextual help on stderr and exits **1**.
+3. From a handler, `cliErrWithHelp(ctx, "message")` prints a red error line plus contextual help on stderr and exits **1** (CLI only; API/MCP invocations throw a plain `Error`).
 
 
 
@@ -211,18 +217,18 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 
 ### Capabilities (built-ins)
 
-`completion`, `version`, `install`, and `mcp` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, `install`, `docs`). Reserved command names: `completion` and `version` always; `install` unless `install.enabled: false`; `mcp` when `mcpServer.enabled` is `true`; `docs` when `docs.enabled` is `true`.
+`completion`, `version`, `install`, `mcp`, and `api` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, `apiServer`, `install`, `docs`). Reserved command names: `completion` and `version` always; `install` unless `install.enabled: false`; `mcp` when `mcpServer.enabled` is `true`; `api` when `apiServer.enabled` is `true`; `docs` when `docs.enabled` is `true`.
 
 ## Examples
 
 Check the `examples/` directory for full working scripts:
 
 
-| Example               | File                     | Shows                                                                                    |
-| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
-| `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`, `readLeafInputs()`.                                         |
+| Example               | File                     | Shows                                                                                             |
+| --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
+| `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`, `readLeafInputs()`.                                                  |
 | `ArgsBargFullExample` | `examples/full-example/` | **Copy template:** all builtins, schemagen, Homebrew justfile, `outputSchema`, `from "argsbarg"`. |
 
 
@@ -257,18 +263,20 @@ To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-progr
 
 ### What the full-example template includes
 
-| Area | Files / wiring |
-| --- | --- |
-| All builtins | `completion`, `version`, `configure`, `docs`, `mcp`, `configure get`/`set` |
-| `program.appConfig` | `src/types.ts` (`AppConfig`) → `schemas/configSchemas.ts` |
-| `outputSchema` | `src/commands/status/types.ts` → `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/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` |
+
+| Area                  | Files / wiring                                                                         |
+| --------------------- | -------------------------------------------------------------------------------------- |
+| All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `api`, `configure get`/`set`      |
+| `program.appConfig`   | `src/config/schema-types.ts` (`AppConfig`) → `schemas/configSchemas.ts`              |
+| `outputSchema`        | `src/commands/status/schema-types.ts` → `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/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.
 
@@ -310,7 +318,7 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | `parseDurationMs`, `parseCommaList`, `parseDate`, `parseDateTime` | Optional format parsers for use outside handlers.                                                                                              |
 
 
-Reserved identifiers (validated at startup): root commands `completion`, `version`, `install`, `docs` (when `docs.enabled` is `true`), and `mcp` (when `mcpServer.enabled` is `true`).
+Reserved identifiers (validated at startup): root commands `completion`, `version`, `install`, `docs` (when `docs.enabled` is `true`), `mcp` (when `mcpServer.enabled` is `true`), and `api` (when `apiServer.enabled` is `true`).
 
 ---
 

package/docs/README.md

@@ -9,6 +9,7 @@ Start here to pick the right guide.
 | **JSON stdout / `outputSchema`** | [output-schema.md](output-schema.md) — codegen pipeline, JSDoc, narrowing |
 | **App config / `program.appConfig`** | [config-schema.md](config-schema.md) — flat JSON file, `ctx.appConfig`, codegen |
 | **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `configure --sync` |
+| **HTTP tool server** | [api-server.md](api-server.md) — `myapp api`, endpoints, curl examples |
 | **Shipping configure / agent artifacts** | [configure.md](configure.md) — Homebrew + `myapp configure --sync` |
 | **Homebrew tap-from-repo distribution** | [distribution-homebrew.md](distribution-homebrew.md) — formula pattern, `argsbarg create` |
 | **Bundling `myapp docs` topics** | [bundled-docs.md](bundled-docs.md) — consumer docgen vs framework docs |
@@ -31,7 +32,7 @@ Examples are included in the npm tarball (`package.json` `files`). After `bun ad
 | Source | What it is | Where it lives |
 | --- | --- | --- |
 | **Framework docs** | How argsbarg works; authoring conventions | This directory — shipped in `node_modules/argsbarg/docs/` after `bun add argsbarg` |
-| **Consumer docgen** | *Your* command tree, API, MCP guide for *your* app | `myapp docs api`, `docs schema`, `docs mcp` — written to `./docs/` with `--save` |
+| **Consumer docgen** | *Your* command tree, API, MCP guide for *your* app | `myapp docs api`, `docs cli-schema`, `docs mcp` — written to `./docs/` with `--save` |
 | **Cursor rule** | Thin tripwire telling agents to read framework docs | `node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc` — included by `create`; refresh with `merge-cli-program-rule.ts` |
 
 Agents do **not** load `node_modules/argsbarg/docs/` unless your repo references them (Cursor rule, `AGENTS.md`, or an `alwaysApply` project rule). Generated `./docs/api.md` in a consumer repo describes **your** CLI, not argsbarg itself.

package/docs/api-server.md

@@ -0,0 +1,141 @@
+# HTTP API server
+
+ArgsBarg can expose your CLI as an HTTP tool server. Each **leaf command** becomes a callable tool — the same exposure model as MCP. The server uses Bun's built-in HTTP stack and binds to **localhost by default**.
+
+The HTTP API is **opt-in**. Apps that do not set `apiServer` on the program root behave exactly as before.
+
+## Quick start
+
+1. Add `apiServer` to your program root:
+
+```typescript
+import pkg from "../package.json" with { type: "json" };
+
+const cli = {
+  key: "myapp",
+  version: pkg.version,
+  description: "My app.",
+  apiServer: { enabled: true },
+  commands: [/* ... */],
+} satisfies CliProgram;
+```
+
+`apiServer: { enabled: true }` opts in. Omit `apiServer` entirely to disable HTTP. Empty `apiServer: {}` is rejected at validation.
+
+2. Run the HTTP server:
+
+```bash
+myapp api
+```
+
+The process listens until interrupted. Startup prints the listen URL to stderr.
+
+## Configuration
+
+Set `apiServer` on the **program root only**. Validation rejects `apiServer` on nested nodes.
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `enabled` | *(required)* | Must be `true` when `apiServer` is set |
+| `host` | `127.0.0.1` | Listen address |
+| `port` | `3000` | Listen port |
+
+`apiServer` and `mcpServer` are independent — enable either or both.
+
+## Tool names
+
+HTTP and MCP use different tool identifiers for the same leaf command:
+
+| CLI path | HTTP API (`POST /tools/:name`) | MCP (`tools/call`) |
+| --- | --- | --- |
+| `stat owner lookup` | `stat-owner-lookup` | `stat_owner_lookup` |
+| `render-invoice` | `render-invoice` | `render_invoice` |
+
+OpenAPI `paths` use the API id (`/tools/render-invoice`, etc.).
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/health` | Liveness check |
+| `GET` | `/openapi.json` | OpenAPI 3.1 document (per-tool `POST /tools/{name}` paths) |
+| `GET` | `/openapi-browser` | Interactive Scalar API reference (CDN) |
+| `POST` | `/tools/:name` | Invoke tool; body is a flat JSON args object |
+| `OPTIONS` | `*` | CORS preflight (wide-open `Access-Control-Allow-Origin: *`) |
+
+## Examples
+
+```bash
+curl -s http://127.0.0.1:3000/health
+curl -s http://127.0.0.1:3000/openapi.json
+open http://127.0.0.1:3000/openapi-browser
+curl -s -X POST http://127.0.0.1:3000/tools/{tool-key} \
+  -H 'content-type: application/json' \
+  -d '{...}'
+```
+
+Replace `{tool-key}` with a path segment from `openapi.json` (`paths` keys are `/tools/{tool-key}`); body keys match that tool's flat JSON args (see `docs cli-schema` or `openapi.json`).
+
+## Handler responses (`ctx.respond()`)
+
+API and MCP tool handlers must return machine-readable output via **`ctx.respond()`** or by **returning a value** (implicit JSON). `console.log` is not included in HTTP/MCP success payloads.
+
+```typescript
+handler: (ctx) => {
+  if (ctx.hasFlag("json")) {
+    return { user: "alice", path: "/tmp" };
+  }
+  ctx.respond({
+    body: pdfBytes,
+    contentType: "application/pdf",
+    headers: { "Content-Disposition": 'inline; filename="invoice.pdf"' },
+  });
+},
+```
+
+**CLI mode:** `ctx.respond()` prints to stdout (JSON pretty-printed, strings as-is, `Uint8Array` as raw bytes). Handlers may still use `console.log` for human-only CLI output.
+
+### Leaf metadata
+
+```typescript
+apiResponse?: {
+  contentType?: string;           // default application/json
+  contentDisposition?: string;    // e.g. attachment; filename="invoice.pdf"
+};
+```
+
+Used by OpenAPI and as a default `Content-Type` when the handler does not set one.
+
+## Responses
+
+**Success (`200`):** raw body — no `{ ok, stdout }` envelope.
+
+| Body type | HTTP `Content-Type` |
+| --- | --- |
+| object / array | `application/json` |
+| string | handler `contentType` or `text/plain` |
+| `Uint8Array` | e.g. `application/pdf` (required on `respond()`) |
+
+**Errors:** JSON `{ "error": "...", "exitCode?": number }` with `400` (bad args), `404` (unknown tool), `503` (missing config), or `500` (handler failure).
+
+## MCP binary payloads
+
+Binary `ctx.respond()` bodies are encoded in MCP `structuredContent` as:
+
+```json
+{ "data": "<base64>", "contentType": "application/pdf", "encoding": "base64" }
+```
+
+String bodies use `{ "content": "...", "contentType": "..." }`. JSON objects are returned as-is in `structuredContent`.
+
+## CORS
+
+All responses include wide-open CORS headers (`Access-Control-Allow-Origin: *`). Not configurable in v1.
+
+## OpenAPI
+
+Call `generateOpenApi(program)` or `openApiJson(program)` from the package, fetch `GET /openapi.json` from a running server, or run `myapp docs openapi` / `myapp docs openapi --save` (writes `./docs/openapi.json` when `docs.enabled` and `apiServer.enabled`). Nested `inputSchema` / `outputSchema` `$ref` pointers are dereferenced when the OpenAPI document is built so API reference UIs can show nested request shapes.
+
+## Complex tool inputs
+
+For nested request bodies (e.g. invoice template data), set `inputSchema` on the leaf and read `ctx.toolArgs` in the handler — it contains the original flat JSON body from `POST /tools/:name`.

package/docs/bundled-docs.md

@@ -9,9 +9,9 @@ Two documentation layers often coexist in a consumer repo:
 | Layer | Contents | How agents/humans get it |
 | --- | --- | --- |
 | **Argsbarg framework** | How to author `CliProgram`, MCP varargs policy, headless patterns | `node_modules/argsbarg/docs/` — wire via [full-example Cursor rule](../examples/full-example/.cursor/rules/cli-program.mdc) or `AGENTS.md` |
-| **Your CLI (docgen)** | Your command tree, options, MCP tool list, install notes | `myapp docs api`, `docs schema`, `docs mcp` — save with `--save` to `./docs/` |
+| **Your CLI (docgen)** | Your command tree, options, MCP tool list, install notes | `myapp docs api`, `docs cli-schema`, `docs mcp` — save with `--save` to `./docs/` |
 
-`docs api` and `docs schema` embed each leaf’s `outputSchema` when set — see [output-schema.md](output-schema.md) for how to generate and wire schemas.
+`docs api` and `docs cli-schema` embed each leaf’s `outputSchema` when set — see [output-schema.md](output-schema.md) for how to generate and wire schemas.
 
 Do not confuse them: editing `./docs/api.md` after docgen updates **your** app reference; it does not change argsbarg's framework guides. When MCP behavior changes (e.g. varargs arrays in 3.6+), update consumer `docs/mcp.md` via **`myapp docs mcp --save`** and bump the `argsbarg` dependency.
 
@@ -42,12 +42,15 @@ const cli = {
 myapp docs              # first topic (readme) via fallback
 myapp docs readme
 myapp docs architecture
-myapp docs schema       # full command tree as JSON
+myapp docs cli-schema       # full command tree as JSON
 myapp docs api          # command tree as markdown
 myapp docs skill        # generated Cursor SKILL.md
 myapp docs mcp          # auto-generated when mcpServer.enabled
+myapp docs http         # auto-generated when apiServer.enabled
+myapp docs openapi      # OpenAPI 3.1 JSON when apiServer.enabled
 myapp docs readme --save   # write ./docs/readme.md
-myapp docs schema --save   # write ./docs/schema.json
+myapp docs cli-schema --save   # write ./docs/cli-schema.json
+myapp docs openapi --save  # write ./docs/openapi.json
 ```
 
 When `docs` is enabled, top-level `myapp --help` points agents at `myapp docs skill`. The `docs skill` subcommand description recommends `configure` for a persisted bundle.
@@ -61,7 +64,7 @@ When `docs` is enabled, top-level `myapp --help` points agents at `myapp docs sk
 | `defaultTopic` | first key in `topics` | `fallbackCommand` for bare `myapp docs` |
 | `topics` | *(required)* | Topic key → `{ text, description? }` |
 
-Reserved topic keys in `topics`: **`mcp`**, **`all`**, **`schema`**, **`api`**, **`skill`** (reserved — use the matching `docs <name>` subcommand instead).
+Reserved topic keys in `topics`: **`http`**, **`mcp`**, **`all`**, **`schema`**, **`api`**, **`skill`**, **`openapi`** (reserved — use the matching `docs <name>` subcommand instead).
 
 When `description` is omitted on a topic, ArgsBarg generates leaf help (`readme` → "Print README (user guide).").
 
@@ -77,11 +80,11 @@ Bun embeds the file when you `bun build --compile`. ArgsBarg does not read the f
 
 Inline topics in your program root when the set is small; use a separate module only if the import map grows enough to clutter `index.tsx`.
 
-## Schema, API, and skill (`docs schema`, `docs api`, `docs skill`)
+## CLI schema, API, and skill (`docs cli-schema`, `docs api`, `docs skill`)
 
 When `docs.enabled` is `true`:
 
-- **`docs schema`** — same JSON as the former root `--schema` flag (handlers omitted; built-in subtrees included for leaf roots).
+- **`docs cli-schema`** — same JSON as the former root `--schema` flag (handlers omitted; built-in subtrees included for leaf roots).
 - **`docs api`** — markdown rendering of the same command tree (options, positionals, subcommands, fallback routing).
 - **`docs skill`** — prints the compact `SKILL.md` index. Prefer `configure --sync --yes` for agents (persists index + full API in `reference.md`).
 
@@ -91,6 +94,16 @@ When both `docs.enabled` and `mcpServer.enabled` are `true`, ArgsBarg injects a
 
 There is no override API in v1 — customize behavior via `mcpTool.description` on leaf commands.
 
+## HTTP guide (`docs http`)
+
+When both `docs.enabled` and `apiServer.enabled` are `true`, ArgsBarg injects a **`docs http`** topic with curl examples, endpoints, and tool list.
+
+Shell invocation tables remain under **`docs api`** (not HTTP).
+
+## OpenAPI (`docs openapi`)
+
+When both `docs.enabled` and `apiServer.enabled` are `true`, ArgsBarg injects a **`docs openapi`** topic with the same OpenAPI 3.1 document served at `GET /openapi.json`.
+
 ## MCP tools
 
 All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: false }`).
@@ -102,7 +115,7 @@ All `docs` subcommands are hidden from MCP `tools/list` (`mcpTool: { enabled: fa
 | `configure` (skill targets) | Writes compact `SKILL.md` + full-API `reference.md` to disk |
 | `docs skill` | Print generated `SKILL.md` to stdout |
 | `docs api` | Print command tree markdown to stdout |
-| `docs schema` | Print command tree JSON to stdout |
+| `docs cli-schema` | Print command tree JSON to stdout |
 | `docs` | Bundled markdown topics on stdout |
 | MCP docs topic resources | User `docs.topics` on the MCP wire (`<mcpId>://docs/<topic>`) when docs + MCP enabled |
 | `mcp` | Callable tools + schema resource |
@@ -116,8 +129,9 @@ Pass **`--save`** on `docs` or any docs subcommand to write files under **`./doc
 | Command | Output |
 | --- | --- |
 | `docs readme --save` | `./docs/readme.md` |
-| `docs schema --save` | `./docs/schema.json` |
+| `docs cli-schema --save` | `./docs/cli-schema.json` |
+| `docs openapi --save` | `./docs/openapi.json` |
 | `docs api --save` | `./docs/api.md` |
 | `docs skill --save` | `./docs/skill.md` |
 
-Argsbarg-generated markdown (`mcp`, `api`, `skill`) includes a `Generated by … docs … --save` HTML comment (`skill` places it after YAML frontmatter so parsers still work). `schema.json` and argsbarg-generated markdown resolve `{argsbarg:program}` in `notes` to the program key. Consumer-authored topic files are written as-is.
+Argsbarg-generated markdown (`mcp`, `api`, `skill`) includes a `Generated by … docs … --save` HTML comment (`skill` places it after YAML frontmatter so parsers still work). `cli-schema.json`, `openapi.json`, and argsbarg-generated markdown resolve `{argsbarg:program}` in `notes` to the program key. Consumer-authored topic files are written as-is.

package/docs/cli-program.md

@@ -27,6 +27,20 @@ const cli = {
 
 No `mcpTool` blocks required. Every leaf becomes an MCP tool; `inputSchema` comes from options and positionals.
 
+## HTTP API (optional)
+
+```typescript
+const cli = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "One-line summary of what the CLI does.",
+  apiServer: { enabled: true }, // myapp api → http://127.0.0.1:3000
+  commands: [/* ... */],
+} satisfies CliProgram;
+```
+
+`apiServer` and `mcpServer` are independent. Tool exposure uses the same rules (`mcpTool.enabled: false` hides from MCP and HTTP). See [api-server.md](api-server.md).
+
 ## Inline schema by default
 
 ArgsBarg is **schema-first** — the program tree is the product. **Keep `CliProgram` and leaf fields inline** (`key`, `description`, `options`, `positionals`, `handler`) so a reader sees the full command contract in one place.
@@ -131,7 +145,7 @@ On **leaf commands**, set `outputSchema` to a JSON Schema describing stdout when
 }
 ```
 
-Exported in `docs schema`, `docs api`, skill `reference.md`, and MCP `tools/list`. Not validated at runtime yet. Pair with `notes` for prose examples; do not duplicate the full schema in `notes`.
+Exported in `docs cli-schema`, `docs api`, skill `reference.md`, and MCP `tools/list`. Not validated at runtime yet. Pair with `notes` for prose examples; do not duplicate the full schema in `notes`.
 
 For a **outputSchema codegen guidelines** (TypeScript types → JSON Schema → `outputSchema` constants), see [output-schema.md](output-schema.md).
 
@@ -300,10 +314,11 @@ Ink + headless + MCP apps benefit from `read*Flags(ctx)` + `resolve*Input(flags)
 Simple leaves (read args, print stdout) are already headless — no extra work. **Any handler that might mount Ink, prompt, or open a browser should also implement a scriptable fast path** for:
 
 - **MCP** (`ctx.invocation === "mcp"` — always non-interactive)
+- **HTTP API** (`ctx.invocation === "api"` — same headless rules as MCP)
 - **Non-TTY CLI** (pipes, CI, `myapp cmd --yes` in a script)
 - **Explicit flags** (`--json`, `--dry-run`)
 
-Use **one headless implementation** for all three; do not fork separate "MCP handlers."
+Use **one headless implementation** for MCP, HTTP API, and scripted CLI; do not fork separate transport handlers.
 
 ### When to branch
 

package/docs/config-schema.md

@@ -142,33 +142,43 @@ Mirror the [output-schema.md](output-schema.md) pattern for config:
 
 ```mermaid
 flowchart LR
-  subgraph types [Schema-facing TS + JSDoc]
-    TypesTs["src/**/types.ts"]
-    Marker["JSDoc contains Config schema"]
+  subgraph types [schema-types.ts]
+    Marker["export type configType = AppConfig"]
   end
   subgraph gen [just schemagen]
-    Script["scripts/generate-config-schemas.ts"]
+    Script["scripts/schemagen.ts"]
     Gen["ts-json-schema-generator"]
   end
   subgraph artifacts [Committed]
-    Json["src/schemas/generated/app-config.json"]
-    Bridge["src/schemas/configSchemas.ts"]
+    Json["schemas/generated/app-config.json"]
+    Bridge["schemas/configSchemas.ts"]
   end
   subgraph runtime [Runtime]
     Program["program.appConfig.jsonSchema"]
     Validate["argsbarg runtime subset validator"]
   end
-  TypesTs --> Marker --> Script --> Gen --> Json
+  types --> Script --> Gen --> Json
   Script --> Bridge --> Program --> Validate
 ```
 
 | Piece | Convention |
 | --- | --- |
 | Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) |
-| Discovery | JSDoc marker **`Config schema`** on the root config interface |
+| Discovery | `export type configType = …` in `src/config/schema-types.ts` (type defined in same file) |
 | Artifacts | Commit `app-config.json` and `configSchemas.ts` bridge exporting `APP_CONFIG_JSON_SCHEMA` |
 | Consumer CI | Optional: `ajv` + `ajv-formats` against the same committed JSON (not an argsbarg runtime dep) |
 
+Example:
+
+```typescript
+// src/config/schema-types.ts
+export interface AppConfig {
+  apiToken: string;
+}
+
+export type configType = AppConfig;
+```
+
 ### Supported AppConfig shapes (argsbarg runtime validator)
 
 | Supported (v1) | Deferred |

package/docs/developing.md

@@ -28,7 +28,7 @@ Update `CHANGELOG.md` under `[Unreleased]` before releasing.
 
 ## Local consumer apps
 
-Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile` if needed):
+Sibling consumer repos (machine-specific paths in the root `justfile` `consumer_apps` variable, e.g. `~/dev/ss/sqsp-workspaces`):
 
 | Recipe | When | Effect |
 | --- | --- | --- |

package/docs/mcp.md

@@ -171,7 +171,7 @@ Each tool’s `description` includes the human CLI path and the leaf’s help te
 
 ### Per-leaf visibility
 
-Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/list` while keeping it in the CLI and in `docs schema` output:
+Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/list` while keeping it in the CLI and in `docs cli-schema` output:
 
 ```typescript
 {
@@ -232,11 +232,11 @@ On success (`isError: false`):
 
 On failure (parse error, validation error, non-zero exit, thrown error), the message is returned as text content with `isError: true`. Handler stderr is included when present.
 
-Help and `docs schema` are not available through tool calls; use the schema resource or run the CLI directly for those.
+Help and `docs cli-schema` are not available through tool calls; use the schema resource or run the CLI directly for those.
 
 ## Schema and custom resources
 
-The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nested.ts` → `nested_ts://schema`) exposes your full CLI tree as JSON — the same output as `myapp docs schema`. Override with `schemaResourceUri` if needed.
+The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nested.ts` → `nested_ts://schema`) exposes your full CLI tree as JSON — the same output as `myapp docs cli-schema`. Override with `schemaResourceUri` if needed.
 
 | Property | Value |
 | --- | --- |
@@ -419,7 +419,7 @@ Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `configure`
 
 ## Hidden commands and options
 
-Set **`hidden: true`** on a command or option to omit it from help listings, `docs schema` / `docs api`, shell completions, and MCP `tools/list` / tool `inputSchema`. Hidden commands remain invocable; **`myapp hidden-cmd -h`** still works.
+Set **`hidden: true`** on a command or option to omit it from help listings, `docs cli-schema` / `docs api`, shell completions, and MCP `tools/list` / tool `inputSchema`. Hidden commands remain invocable; **`myapp hidden-cmd -h`** still works.
 
 ## Reserved names
 
@@ -436,4 +436,4 @@ Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1)
 - **User schema only** — tool dispatch uses your program root, not merged presentation builtins.
 - **Buffered output** — MCP tool results are sent after the handler finishes. Incremental stdout (log tail, progress) is not streamed; a future release may add MCP progress notifications.
 
-For the `docs schema` export used by the resource, see [docs/bundled-docs.md](bundled-docs.md).
+For the `docs cli-schema` export used by the resource, see [docs/bundled-docs.md](bundled-docs.md).