argsbarg 6.1.1 → 6.1.3

package/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.3] - 2026-07-24
+
+### Added
+
+- **HTTP REST API** — nested `/api/...` routes from the command tree; `:param` routers; query/body binding; verb inference (`get`/`post`/…); default success statuses (POST **201**, DELETE **204**).
+- **Per-surface exposure** — `cli`, `http`, and `mcpTool` blocks replace global `hidden` (`enabled` / `hidden` per surface; `cli.enabled` cascades).
+- **Invoke hooks and error pipeline** — `program.hooks` (`beforeInvoke`, `afterInvoke`, `formatError`, `onError`), `failureKind` on `CliInvokeResult`, and HTTP/MCP status mapping (`validation`/`help` → 400, `unexpected` → 500, `missing_config`/`not_ready` → 503).
+- **Server runtime and observability** — `ServerRuntime`, ECS logging (`program.log`), `serveHttp(overrides?)` / `serveMcp(overrides?)`, `GET /health/live` and `GET /health/ready`, soft config validation at server start, HTTP/MCP wire hooks, CLI flags on `http` / `mcp serve`.
+- **`pathParams`** on parse results and `ctx.inputs`; `:param` shell completion fallback.
+- **Schema export** — `outputContentType` on leaves without `outputSchema`; program `errorSchema` from server error config.
+- **Export subpaths** — `argsbarg/cli`, `argsbarg/http`, `argsbarg/mcp`, `argsbarg/headless` (root barrel unchanged). See [docs/developing.md](docs/developing.md#advanced-imports).
+- **`docs/json-schema-subset.md`** — documents the custom JSON Schema validator used for `appConfig` and `inputSchema`.
+- **`src/help.test.ts`** — label unit tests and help render regressions (migrated from `parse.test.ts`).
+- **Compact skill `reference.md`** — `generateCliGuideBody({ compact: true })` omits inline `outputSchema` JSON; pointers to `docs cli-schema` / OpenAPI.
+- **`examples/full-example` `render-json` command** — `kind: "json"` leaf with schemagen `inputSchema`, `ctx.inputsAs`, and HTTP invoke test.
+- **`examples/full-example` `workspaces` command** — REST CRUD demo with `:id` router, hooks, readiness, layered in-memory SQLite (`db/`, `store/workspaces`), and versioned migrations.
+- **`scripts/merge-code-rule.ts`** — merge full-example `code.mdc` into consumer repos (preserves app convention footer).
+- **`just consumers-schemagen`** — run schemagen across local `consumer_apps` paths.
+
+### Changed
+
+- **Breaking: `@sg` schemagen** — role exports (`configType` / `inputType` / `outputType`) removed. Mark types with `/** @sg */` immediately above `export interface` / `export type`; import `{TypeName}Schema` from colocated `__generated__/`.
+- **Breaking: `McpToolDef.apiName` / `apiToolName()` removed** — HTTP uses REST `/api/...` routes only.
+- **Breaking: `loadLeafInputs` and `CliHttpResponseConfig` unexported** from the root barrel (use `ctx.inputs` / `ctx.inputsAs`; leaf `http.successContentType`).
+- **Framework-owned `ctx.locals.requestId`** — seeded before `beforeInvoke` on every invocation (wire HTTP/MCP id when present, else `randomUUID()`).
+- **`examples/full-example` simplified** — no default `appConfig`; commands use `@sg` named schemas; minimal `program.ts`.
+- **Internal refactor** — needless single-use extractions inlined across `src/` per `.cursor/rules/code.mdc`.
+- **Internal: `src/` layout** — `src/core/`, `src/runtime/`, `src/headless/routing.ts`, shared/integration tests → `src/test/`; cross-module imports use `~/` (`tsconfig` `paths`). Public exports unchanged.
+- **Internal: import paths** — directory barrels omit `/index.ts` (`~/configure`, `./__generated__`, `~/index` for the package root).
+- **Breaking: removed `POST /tools/*`** — use `/api/*` REST routes; OpenAPI paths updated.
+- **Breaking: `leaf.apiResponse` removed** — use `http.successContentType` / `http.contentDisposition`.
+- **Breaking: global `hidden` removed** — use per-surface `cli.hidden`, `http.hidden`, `mcpTool.hidden`.
+- **Breaking: HTTP rename (`api` → `http`)** — `apiServer` → `httpServer`, `Cli.serveApi()` → `serveHttp()`, builtin `myapp api` → `myapp http`, `ctx.invocation: "http"`, `capabilities.http`, `src/api/` → `src/http/`, reserved command `http`. OpenAPI generator names unchanged (`generateOpenApi`).
+- **Breaking: docs topic `api` → `cli`** — `docs api` → `docs cli`, saved `docs/cli.md`, `src/docs/cli-guide.ts`. Reserved docs topic key `cli`.
+- **Breaking: removed deprecated input reads** — `readLeafInputs`, `readLeafInputsAsync`, `ctx.readLeafInputs()`, `ctx.readLeafInputsAsync()`. Use `ctx.inputs` / `ctx.inputsAs<T>()`.
+- **Breaking: removed `mcpTool.outputSchema`** — use leaf `outputSchema` only.
+- **Breaking: `src/install/` → `src/configure/artifacts/`** — configure artifact modules colocated under configure; deprecated install stubs removed.
+- **`docs` built-in default-on** — built-in subcommands (`cli-schema`, `cli`, `skill`, conditional `mcp`/`http`/`openapi`) work with no `docs` config block.
+- **`docs.topics` optional** — add `topics` only when bundling consumer markdown.
+- **Experimental callouts** — blockquotes in `docs/mcp.md`, `docs/ai-skills.md`, `docs/configure.md`; `@experimental` JSDoc on MCP/configure bundle types.
+
+### Removed
+
+- **Breaking: bare `myapp docs` auto-print** — shows router help; `defaultTopic` removed.
+- **Breaking: user `docs` command** — reserved by default; opt out with `docs: { enabled: false }`.
+
+### Migration (6.1.2)
+
+| Before | After |
+| --- | --- |
+| `POST /tools/:name` | `/api/...` REST (see `openapi.json`) |
+| `hidden: true` on node | `cli.hidden`, `http.hidden`, or `mcpTool.hidden` |
+| `apiResponse.contentType` | `http.successContentType` |
+| `apiServer` | `httpServer` |
+| `myapp api` | `myapp http` |
+| `invocation: "api"` | `invocation: "http"` |
+| `docs api` / `docs/api.md` | `docs cli` / `docs/cli.md` |
+| `ctx.readLeafInputs()` | `ctx.inputs` or `ctx.inputsAs<T>()` |
+| `mcpTool.outputSchema` | `outputSchema` on the leaf |
+| `from "argsbarg/install/..."` | `from "argsbarg/configure/artifacts/..."` (internal) |
+
+Regenerate saved docs (`just docgen`) and run `argsbarg schemagen` after upgrading.
+
+## [6.1.2] - 2026-07-23
+
+### Added
+
+- **`kind: "json"` on `CliLeaf`** — pure JSON body leaves with no CLI flags. Requires `inputSchema`; forbids `options` and `positionals`. CLI accepts one JSON positional or piped stdin; MCP/HTTP use the tool args object directly. **`isJsonLeaf()`** helper exported.
+
 ## [6.1.1] - 2026-07-23
 
 ### Added
@@ -764,7 +833,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/v6.1.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.3...HEAD
+[6.1.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.3
+[6.1.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.2
 [6.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.1
 [6.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.0
 [6.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.2

package/README.md

@@ -95,14 +95,14 @@ 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`).
-- `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).
+- `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).
 
 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.
+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.
 
 ### MCP (AI agents)
 
@@ -110,11 +110,11 @@ Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp
 
 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
+### HTTP tool server
 
-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`.
+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 `/api/...` with inferred HTTP verbs. Discover routes via `GET /openapi.json`.
 
-See **[docs/api-server.md](docs/api-server.md)** for endpoints, curl examples, and response shapes.
+See **[docs/http-server.md](docs/http-server.md)** for endpoints, curl examples, and response shapes.
 
 ### Configure CLI
 
@@ -209,9 +209,7 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `ctx.dateOpt("on")` / `ctx.dateTimeOpt("since")` — ISO date / date-time options.
 - `ctx.inputs` — coerced option and positional values for the current leaf; when `inputSchema` is set, validated before the handler runs and cached on `ctx`.
 - `ctx.inputsAs<T>()` — `ctx.inputs` cast to a schemagen or app input type.
-- `ctx.readLeafInputs()` — deprecated; use `ctx.inputs` or `ctx.inputsAs()`.
-- `ctx.jsonOpt(name)` — parsed Json option (flag, preloaded stdin, or MCP/API `toolArgs`).
-- `ctx.readLeafInputsAsync()` — deprecated alias for `readLeafInputs()`.
+- `ctx.jsonOpt(name)` — parsed Json option (flag, preloaded stdin, or MCP/HTTP `toolArgs`).
 - `ctx.typedOpt<T>("custom", parseFn)` — custom parsing for type-safe option resolution.
 - `ctx.args` — positional words in order as `string[]`.
 - `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.
@@ -221,7 +219,7 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 
 ### Capabilities (built-ins)
 
-`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`.
+`completion`, `version`, `configure`, `mcp`, and `http` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, `httpServer`, `configure`, `docs`). Reserved command names: `completion` and `version` always; `configure` unless `configure.enabled: false`; `docs` unless `docs.enabled: false` (default on); `mcp` when `mcpServer.enabled` is `true`; `http` when `httpServer.enabled` is `true`.
 
 ## Examples
 
@@ -232,7 +230,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`, `readLeafInputs()`.                                                  |
+| `ArgsBargFormats`     | `examples/formats.ts`    | `CliValueFormat`, `default`, `ctx.inputs`.                                                  |
 | `ArgsBargFullExample` | `examples/full-example/` | **Copy template:** all builtins, schemagen, Homebrew justfile, `outputSchema`, `from "argsbarg"`. |
 
 
@@ -263,16 +261,16 @@ Edit `scripts/create-identity.ts` in the new repo to set `desc` (used by `progra
 
 Verify an existing tree: `bunx argsbarg create --check .`
 
-To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-program-rule.ts .` from an argsbarg checkout (or pass the npm package path to the template).
+To refresh Cursor rules in an existing consumer: `bun scripts/merge-cli-program-rule.ts .` and `bun scripts/merge-code-rule.ts .` from an argsbarg checkout (or pass the npm package path to the template).
 
 ### What the full-example template includes
 
 
 | Area                  | Files / wiring                                                                         |
 | --------------------- | -------------------------------------------------------------------------------------- |
-| All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `api`, `configure get`/`set`      |
-| `program.appConfig`   | `src/config/types.ts` → `configSchema` from `__generated__/`                         |
-| `outputSchema`        | `src/commands/status/types.ts` → `outputSchema` from `__generated__/`                  |
+| 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 |
@@ -313,8 +311,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.readLeafInputs`, `ctx.invocation`, …).                                |
-| `CliLeafInputs`                                                   | Record type returned by `readLeafInputs()` — 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`).                                                     |
@@ -322,7 +320,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`), `mcp` (when `mcpServer.enabled` is `true`), and `api` (when `apiServer.enabled` is `true`).
+Reserved identifiers (validated at startup): root commands `completion`, `version`, `configure`, `docs` (unless `docs.enabled: false`), `mcp` (when `mcpServer.enabled` is `true`), and `http` (when `httpServer.enabled` is `true`).
 
 ---
 

package/bin/argsbarg

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+ROOT="$(cd "$(dirname "$SOURCE")/.." && pwd)"
+exec bun "$ROOT/src/cli-tool/main.ts" "$@"

package/docs/README.md

@@ -8,8 +8,9 @@ Start here to pick the right guide.
 | **Authoring a `CliProgram`** (humans or agents) | [cli-program.md](cli-program.md) — schema, formats, headless, `read*Flags` |
 | **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 |
+| **JSON Schema subset (validation)** | [json-schema-subset.md](json-schema-subset.md) — supported keywords for config and `inputSchema` |
 | **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 |
+| **HTTP tool server** | [http-server.md](http-server.md) — `myapp http`, 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 |
@@ -32,7 +33,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 cli-schema`, `docs mcp` — written to `./docs/` with `--save` |
+| **Consumer docgen** | *Your* command tree, API, MCP guide for *your* app | `myapp docs cli`, `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.
+Agents do **not** load `node_modules/argsbarg/docs/` unless your repo references them (Cursor rule, `AGENTS.md`, or an `alwaysApply` project rule). Generated `./docs/cli.md` in a consumer repo describes **your** CLI, not argsbarg itself.

package/docs/ai-skills.md

@@ -1,5 +1,7 @@
 # Agent skills
 
+> This feature is experimental.
+
 ArgsBarg can generate Cursor and Claude Code skill directories (`SKILL.md` + `reference.md`) from your CLI schema.
 
 ## Install via `configure` (recommended)
@@ -35,7 +37,7 @@ For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true
 ## Generated content
 
 - **`SKILL.md`** — YAML frontmatter, compact command index, pitfalls, and a pointer to `reference.md`
-- **`reference.md`** — full `docs api` markdown reference
+- **`reference.md`** — full `docs cli` markdown reference
 
 Installed files include an HTML comment hint (`Generated by myapp configure; do not edit.`) after SKILL.md frontmatter and at the top of `reference.md`.
 
@@ -49,7 +51,7 @@ Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tool
 | **`myapp configure`** (skill targets) | Persists optimized skill bundle (`SKILL.md` index + `reference.md` full API) |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
-`SKILL.md` is the routing index; `reference.md` matches `docs api`. Prefer `configure` over `docs skill` for agents. See [cli-program.md](cli-program.md).
+`SKILL.md` is the routing index; `reference.md` matches `docs cli`. Prefer `configure` over `docs skill` for agents. See [cli-program.md](cli-program.md).
 
 **Claude Code plugin** (`mcpServer.claudePlugin: true` → `mcp bundle` writes `dist/claude-plugin/<name>.zip`) ships a separate MCP pointer skill (`SKILL.md` only) that routes agents to the bundled MCP server. This is a **dist artifact**, not installed via `configure`. Use **`configure`** for persisted shell-oriented skills.
 

package/docs/bundled-docs.md

@@ -1,6 +1,6 @@
 # Bundled documentation (`docs`)
 
-ArgsBarg can expose bundled markdown topics as the built-in `docs` command group. Opt in on the program root with `docs: { enabled: true, topics: { ... } }`.
+ArgsBarg exposes the built-in `docs` command group on every CLI by default. Built-in subcommands (`cli-schema`, `cli`, `skill`, and conditional `mcp` / `http` / `openapi`) work with zero config. Add optional `docs.topics` for consumer-authored markdown, or opt out with `docs: { enabled: false }`.
 
 ## Framework docs vs your app's docgen
 
@@ -9,16 +9,29 @@ 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 cli-schema`, `docs mcp` — save with `--save` to `./docs/` |
+| **Your CLI (docgen)** | Your command tree, options, MCP tool list, install notes | `myapp docs cli`, `docs cli-schema`, `docs mcp` — save with `--save` to `./docs/` |
 
-`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.
+`docs cli` 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.
+Do not confuse them: editing `./docs/cli.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.
 
 See [docs/README.md](README.md) for the full documentation map.
 
 ## Quick start
 
+Zero config — built-in docgen only:
+
+```typescript
+const cli = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "My app.",
+  commands: [/* ... */],
+} satisfies CliProgram;
+```
+
+Optional consumer markdown topics:
+
 ```typescript
 import readmeText from "../README.md" with { type: "text" };
 import archText from "../docs/architecture.md" with { type: "text" };
@@ -28,7 +41,6 @@ const cli = {
   version: "1.0.0",
   description: "My app.",
   docs: {
-    enabled: true,
     topics: {
       readme: { text: readmeText },
       architecture: { text: archText, description: "Contributor architecture notes." },
@@ -39,32 +51,31 @@ const cli = {
 ```
 
 ```bash
-myapp docs              # first topic (readme) via fallback
+myapp docs              # router help (subcommand list)
 myapp docs readme
 myapp docs architecture
 myapp docs cli-schema       # full command tree as JSON
-myapp docs api          # command tree as markdown
+myapp docs cli          # 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 http         # auto-generated when httpServer.enabled
+myapp docs openapi      # OpenAPI 3.1 JSON when httpServer.enabled
 myapp docs readme --save   # write ./docs/readme.md
 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.
+Top-level `myapp --help` points agents at `myapp docs skill`. The `docs skill` subcommand description recommends `configure` for a persisted bundle.
 
 ## Configuration
 
 | Field | Default | Purpose |
 | --- | --- | --- |
-| `enabled` | *(required)* | Must be `true` when `docs` is set |
+| `enabled` | `true` | Set `false` to disable the `docs` built-in |
 | `description` | `"Print bundled CLI documentation."` | Router help for `myapp docs` |
-| `defaultTopic` | first key in `topics` | `fallbackCommand` for bare `myapp docs` |
-| `topics` | *(required)* | Topic key → `{ text, description? }` |
+| `topics` | *(none)* | Optional topic key → `{ text, description? }` |
 
-Reserved topic keys in `topics`: **`http`**, **`mcp`**, **`all`**, **`schema`**, **`api`**, **`skill`**, **`openapi`** (reserved — use the matching `docs <name>` subcommand instead).
+Reserved topic keys in `topics`: **`http`**, **`mcp`**, **`all`**, **`schema`**, **`cli`**, **`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).").
 
@@ -80,29 +91,29 @@ 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`.
 
-## CLI schema, API, and skill (`docs cli-schema`, `docs api`, `docs skill`)
+## CLI schema, API, and skill (`docs cli-schema`, `docs cli`, `docs skill`)
 
-When `docs.enabled` is `true`:
+By default (unless `docs.enabled: false`):
 
 - **`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 cli`** — 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`).
 
 ## MCP guide (`docs mcp`)
 
-When both `docs.enabled` and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `program.appConfig`, schema resource URI, `configure --sync`, and protocol notes.
+When both docs (default) and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `program.appConfig`, schema resource URI, `configure --sync`, and protocol notes.
 
 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.
+When both docs (default) and `httpServer.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).
+Shell invocation tables remain under **`docs cli`** (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`.
+When both docs (default) and `httpServer.enabled` are `true`, ArgsBarg injects a **`docs openapi`** topic with the same OpenAPI 3.1 document served at `GET /openapi.json`.
 
 ## MCP tools
 
@@ -114,13 +125,27 @@ 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 cli` | Print command tree markdown 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 |
 
-Do not declare a top-level command named **`docs`** when `docs.enabled` is `true` — it is reserved.
+Do not declare a top-level command named **`docs`** unless `docs.enabled: false` — it is reserved by default.
+
+## Agent artifact contract
+
+Load one primary artifact per task — avoid pulling `reference.md`, `cli-schema.json`, and `openapi.json` together unless you need all three.
+
+| Goal | Load |
+| --- | --- |
+| Route to the right command | `SKILL.md` (via `configure` or `docs skill`) |
+| Full command tree + option prose | `reference.md` or `docs cli` |
+| Machine-readable CLI tree + schemas | `docs cli-schema` |
+| HTTP request/response shapes | `docs openapi` or `GET /openapi.json` |
+| MCP tool list + env config | `docs mcp` |
+
+Skill `reference.md` is **compact** (no embedded `outputSchema` JSON blocks). Fetch `cli-schema` or OpenAPI when you need exact shapes.
 
 ## Save to disk (`--save`)
 
@@ -131,7 +156,7 @@ Pass **`--save`** on `docs` or any docs subcommand to write files under **`./doc
 | `docs readme --save` | `./docs/readme.md` |
 | `docs cli-schema --save` | `./docs/cli-schema.json` |
 | `docs openapi --save` | `./docs/openapi.json` |
-| `docs api --save` | `./docs/api.md` |
+| `docs cli --save` | `./docs/cli.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). `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.
+Argsbarg-generated markdown (`mcp`, `http`, `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

@@ -34,12 +34,12 @@ 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
+  httpServer: { 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).
+`httpServer` and `mcpServer` are independent. Tool exposure uses the same rules (`mcpTool.enabled: false` hides from MCP and HTTP). See [http-server.md](http-server.md).
 
 ## Inline schema by default
 
@@ -101,6 +101,18 @@ Option and positional `description` strings appear in `-h`, MCP `inputSchema`, a
 
 Use root **`notes`** for cross-cutting hints shown in help (install commands, docs topics, VPN requirements).
 
+## Agent-friendly schema
+
+Descriptions and schemas are copied into MCP tools, HTTP OpenAPI, and generated skills — optimize for smaller, clearer agent payloads:
+
+- Prefer **`kind: "json"`** leaves with schemagen `inputSchema` for complex tool bodies (one nested object beats many flat flags).
+- Keep **`description`** strings short and action-oriented; put examples in **`notes`**, not duplicated in every option.
+- Use **`hidden: true`** or **`mcpTool.enabled: false`** for debug/internal commands.
+- For shape discovery: HTTP agents load **`docs openapi`** or `GET /openapi.json`; MCP agents use **`docs cli-schema`**; load full **`docs cli`** only when prose is needed.
+- Skill **`reference.md`** uses a compact CLI guide (no inline `outputSchema` JSON) — see [bundled-docs.md](bundled-docs.md#agent-artifact-contract).
+
+Validation keywords: [json-schema-subset.md](json-schema-subset.md).
+
 ## Well-known option names
 
 Prefer **`yes`**, **`dry-run`**, and **`json`** when semantics match. They appear in `-h`, MCP `inputSchema`, and generated skills — write clear option `description` strings (e.g. "Skip confirmation; use for non-interactive runs.").
@@ -145,7 +157,7 @@ On **leaf commands**, set `outputSchema` to a JSON Schema describing stdout when
 }
 ```
 
-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`.
+Exported in `docs cli-schema`, `docs cli`, 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).
 
@@ -211,8 +223,6 @@ const { limit, "skip-readiness": skipReadiness, timeout } = ctx.inputs;
 const { format, invoice } = ctx.inputsAs<RenderInvoiceInput>();
 ```
 
-**`readLeafInputs()`** — deprecated alias for `ctx.inputs`.
-
 **`CliLeafInputs`** — return type of `ctx.inputs` (exported from `"argsbarg"`). A flat record keyed by **schema option and positional names** (hyphens preserved, e.g. `"skip-readiness"`). Values are coerced per kind/format:
 
 | Schema | Value in `CliLeafInputs` |
@@ -230,6 +240,38 @@ const { format, invoice } = ctx.inputsAs<RenderInvoiceInput>();
 
 Omitted options appear as `undefined` (not absent keys). Options with `default` are filled in post-parse before handlers run, so `ctx.inputs` and `durationOpt` see defaults. **`ctx.opts` always holds raw strings** — use typed accessors or `ctx.inputs` for coerced values.
 
+### Typed `locals` and server `state`
+
+**`ctx.locals`** — per-invocation bag populated in `program.hooks.beforeInvoke` (framework seeds `requestId` before hooks run). **`ctx.runtime.state`** — shared HTTP/MCP server bag (DB pools, readiness cache, etc.).
+
+Argsbarg exports empty **`CliLocals`** and **`ServerState`** interfaces. Augment them once in your app so handlers see typed fields.
+
+Create a `src/types/argsbarg.d.ts` file (or any name under your `tsconfig.json`'s `include` path) and ensure it contains at least one top-level `import` or `export` statement so TypeScript treats it as a module (module augmentation). Because it is matched by the `include` paths in `tsconfig.json`, TypeScript automatically loads it globally—no runtime or build-time imports are needed in your entry points!
+
+```typescript
+// src/types/argsbarg.d.ts
+import type { AppDb } from "../db";
+
+declare module "argsbarg" {
+  interface CliLocals {
+    db: AppDb;
+  }
+  interface ServerState {
+    db?: AppDb;
+  }
+}
+```
+
+```typescript
+// program.ts
+hooks: { beforeInvoke: AppDb.attach },
+
+// handler
+handler: (ctx) => ctx.locals.db.workspaces.list(),
+```
+
+Use **`CliLocals`** for handler-facing per-request state (`ctx.locals.db`). Use **`ServerState`** for cross-request server resources (`ctx.runtime.state.db`). Populate both in `beforeInvoke` when needed.
+
 ### Json options and piped stdin
 
 For nested tool bodies (e.g. invoice template data), declare a matching property in schemagen `inputType`, wire `inputSchema` on the leaf, and add a **`kind: Json`** option with the same name:
@@ -255,7 +297,31 @@ Use **`ctx.jsonOpt("invoice")`**, **`ctx.inputs`**, or **`ctx.inputsAs<MyInput>(
 
 At most one `pipable` Json option per leaf. Json option names must appear in `inputSchema.properties` when a custom `inputSchema` is set.
 
-See [output-schema.md](output-schema.md) for schemagen `inputType` and [api-server.md](api-server.md) for HTTP tool bodies.
+### Pure JSON leaves (`kind: "json"`)
+
+When the entire tool body is JSON (no CLI flags), set **`kind: "json"`** on the leaf with **`inputSchema`** and **no `options` or `positionals`**:
+
+```typescript
+{
+  key: "render-invoice",
+  description: "Render an invoice from template data",
+  kind: "json",
+  inputSchema,
+  handler: (ctx) => {
+    const { format, invoice } = ctx.inputsAs<RenderInvoiceInput>();
+    // ...
+  },
+}
+```
+
+| Surface | How input is supplied |
+| --- | --- |
+| CLI | One JSON positional **or** pipe a JSON document to stdin |
+| MCP / HTTP | Full tool args object (`ctx.toolArgs` / POST body) |
+
+Example CLI: `jq '{format:"pdf", invoice:.}' data.json | myapp render-invoice`
+
+See [output-schema.md](output-schema.md) for schemagen `inputType`, [http-server.md](http-server.md) for HTTP tool bodies, and [json-schema-subset.md](json-schema-subset.md) for supported schema keywords.
 
 `CliLeafInputs` is intentionally untyped at the framework level. Narrow in your app (`read*Flags(ctx)` returning a typed struct) rather than expecting inference from `satisfies CliLeaf`.
 
@@ -269,7 +335,7 @@ For apps with **Ink + headless + MCP** (multiple surfaces per leaf), avoid scatt
 
 | Layer | Responsibility |
 | --- | --- |
-| **`read*Flags(ctx)`** | Read coerced values from `ctx` (`readLeafInputs()`, `durationOpt`, `commaListOpt`, shared mutator flags) into one typed struct |
+| **`read*Flags(ctx)`** | Read coerced values from `ctx` (`ctx.inputs`, `durationOpt`, `commaListOpt`, shared mutator flags) into one typed struct |
 | **`resolve*Input(flags)`** | Cross-field validation and defaults; returns `{ ok, input }` or `{ ok: false, error }` |
 
 The handler calls **`read*Flags` once**, passes the struct to **`resolve*Input`**, then branches to Ink, headless, or MCP with the same resolved input.
@@ -314,7 +380,7 @@ handler: async (ctx) => {
 };
 ```
 
-**JSON-only CLIs** — a single `readCommandOptions(ctx)` wrapping `readLeafInputs()` per shared option set is usually enough; full `resolve*` layering is optional.
+**JSON-only CLIs** — a single `readCommandOptions(ctx)` wrapping `ctx.inputs` per shared option set is usually enough; full `resolve*` layering is optional.
 
 ## Upgrading to 3.6+
 
@@ -334,7 +400,7 @@ CLI argv is unchanged: space-separated words. Use `format: comma-list` on an **o
 
 ### Value formats (optional)
 
-Add `format`, `default`, or `pattern` on string **options**; read with `ctx.durationOpt`, `ctx.commaListOpt`, `ctx.readLeafInputs()`, etc. Replace hand-rolled `split(",")` / `parseDurationMs` try/catch where the schema can declare the shape.
+Add `format`, `default`, or `pattern` on string **options**; read with `ctx.durationOpt`, `ctx.commaListOpt`, `ctx.inputs`, etc. Replace hand-rolled `split(",")` / `parseDurationMs` try/catch where the schema can declare the shape.
 
 ### Handler layering (optional)
 
@@ -345,7 +411,7 @@ 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)
+- **HTTP API** (`ctx.invocation === "http"` — same headless rules as MCP)
 - **Non-TTY CLI** (pipes, CI, `myapp cmd --yes` in a script)
 - **Explicit flags** (`--json`, `--dry-run`)