argsbarg 6.0.0 → 6.0.1

package/CHANGELOG.md

@@ -7,6 +7,19 @@ 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
@@ -715,7 +728,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.0.0...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

package/README.md

@@ -167,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`).
 
 
 
@@ -267,8 +267,8 @@ To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-progr
 | Area                  | Files / wiring                                                                         |
 | --------------------- | -------------------------------------------------------------------------------------- |
 | All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `api`, `configure get`/`set`      |
-| `program.appConfig`   | `src/types.ts` (`AppConfig`) → `schemas/configSchemas.ts`                              |
-| `outputSchema`        | `src/commands/status/types.ts` → `schemas/outputSchemas.ts`                            |
+| `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/docs/api-server.md

@@ -134,7 +134,7 @@ All responses include wide-open CORS headers (`Access-Control-Allow-Origin: *`).
 
 ## 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`). Tools with custom `inputSchema` on the leaf are reflected in the document.
+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
 

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/output-schema.md

@@ -23,8 +23,9 @@ export const status = {
 | `myapp docs api` | Markdown per-command **Output** section |
 | `myapp docs skill` | `reference.md` for agent skills |
 | MCP `tools/list` | Optional `outputSchema` on each tool |
+| HTTP `GET /openapi.json` | Response schema per tool |
 
-**Not validated at runtime** — argsbarg does not parse or reject handler stdout against the schema today. The schema is documentation and MCP metadata.
+**Not validated at runtime** — argsbarg does not parse or reject handler stdout against the schema today. The schema is documentation and MCP/HTTP metadata.
 
 **Set on the leaf only** — not under `mcpTool` (legacy `mcpTool.outputSchema` still resolves but is deprecated).
 
@@ -43,31 +44,29 @@ Production CLIs with several JSON commands tend to use **codegen** so types, han
 
 ## Recommended pipeline (copy per repo)
 
-No shared npm package — each app copies the same **contract**. Reference implementations: **sqsp-qa-manager-poc**, **sqsp-workspaces**, **sqsp-i18n-tools-poc** (see each repo’s `docs/architecture.md` for which commands use which schema root).
+No shared npm package — each app copies the same **contract**. Reference implementations: **sqsp-qa-manager-poc**, **sqsp-workspaces**, **sqsp-i18n-tools-poc**, **pdf-gen** (see each repo’s `docs/architecture.md` for which commands use which schema root).
 
 ```mermaid
 flowchart LR
-  subgraph types [Schema-facing TS + JSDoc]
-    TypesTs["src/**/types.ts"]
-    Marker["JSDoc contains JSON payload"]
-    Narrow["Narrowed types where needed"]
+  subgraph types [schema-types.ts]
+    Config["export type configType = AppConfig"]
+    Output["export type outputType = StatusJsonOutput"]
+    Input["export type inputType = ToolInput (optional)"]
   end
   subgraph gen [just schemagen]
-    Discover["scripts/schemagen/discover-schema-roots.ts"]
-    Script["scripts/generate-output-schemas.ts"]
+    Discover["discover-schema-roots.ts"]
+    Script["schemagen.ts / generate-output-schemas.ts"]
     Gen["ts-json-schema-generator"]
   end
   subgraph artifacts [Committed]
-    Json["src/schemas/generated/*.json"]
-    Bridge["src/schemas/outputSchemas.ts"]
+    Json["schemas/generated/*.json"]
+    Bridge["outputSchemas.ts / inputSchemas.ts"]
   end
   subgraph runtime [Runtime]
-    Leaves["leaf outputSchema"]
+    Leaves["leaf outputSchema / inputSchema"]
     Docgen["just docgen"]
   end
-  TypesTs --> Marker --> Discover
-  Narrow --> Discover
-  Discover --> Script --> Gen --> Json
+  types --> Discover --> Script --> Gen --> Json
   Script --> Bridge --> Leaves --> Docgen
 ```
 
@@ -75,61 +74,95 @@ flowchart LR
 | --- | --- |
 | Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (`createGenerator` with `jsDoc: "extended"`) |
 | Config | `tsconfig: "tsconfig.json"`, `topRef: false`, `skipTypeCheck: false` |
-| Discovery | Walk `src/**/types.ts`; treat `export interface` as a schema root when its JSDoc contains **`JSON payload`** |
-| Artifacts | Commit `src/schemas/generated/*.json` **and** auto-generated `src/schemas/outputSchemas.ts` |
+| Discovery | Walk `src/**/schema-types.ts`; generate from `export type outputType = …` / `inputType` / `configType` when the target type is **defined in that file** |
+| Artifacts | Commit `schemas/generated/*.json` **and** auto-generated bridge modules |
 | tsconfig | `"resolveJsonModule": true` |
-| CI | `just check`: `schemagen` → `git diff --exit-code src/schemas/generated/ src/schemas/outputSchemas.ts` → typecheck |
+| CI | `just check`: `schemagen` → `git diff --exit-code schemas/` → typecheck |
 | Docgen | `docgen` depends on `schemagen` so saved `./docs/api.md` and `./docs/cli-schema.json` are fresh |
 
 Copy these scripts into each consumer repo (they are intentionally duplicated, not published):
 
-- `scripts/generate-output-schemas.ts` — generate JSON + rewrite the bridge
+- `scripts/schemagen.ts` or `scripts/generate-output-schemas.ts` — generate JSON + rewrite bridges
 - `scripts/schemagen/discover-schema-roots.ts` — find roots and map names → filenames / export constants
 - `scripts/schemagen/discover-schema-roots.test.ts` — lock discovery and naming per app
 
-### Marking a schema root
+### Declaring a schema root
 
-Put schema-facing interfaces in **`src/**/types.ts`** (e.g. `src/commands/status/types.ts`, `src/ui/runHeadless/types.ts`, `src/core/types.ts`). Add a JSDoc line containing **`JSON payload`** on the exported interface:
+Put schema-facing interfaces in **`schema-types.ts`** next to the command (or in a shared module when several commands reuse one shape). Export a role alias:
 
 ```typescript
-/** JSON payload for `myapp status --json`. */
+// src/commands/status/schema-types.ts
+import type { WorkspaceStatus } from "./types.ts";
+
+/** JSON stdout for `myapp status --json`. */
 export interface StatusJsonOutput {
-  items: StatusJsonItem[];
+  workspaces: WorkspaceStatus[];
 }
 
-/** JSON payload written to stdout after a headless mutating command. */
+/** Schemagen root for leaf outputSchema. */
+export type outputType = StatusJsonOutput;
+```
+
+```typescript
+// src/ui/runHeadless/schema-types.ts — shared by many mutating commands
+import type { HeadlessTaskResult } from "./types.ts";
+
 export interface HeadlessOpResult {
   command: string;
   exitCode: number;
   tasks: HeadlessTaskResult[];
 }
+
+export type outputType = HeadlessOpResult;
 ```
 
-`discoverSchemaRoots` scans only files named `types.ts` under `src/`. Nested helper interfaces in the same file are included in the generated schema when referenced by a root; they are **not** separate JSON files unless they are also marked roots.
+```typescript
+// src/commands/render-invoice/schema-types.ts — custom HTTP/MCP body (pdf-gen)
+export interface RenderInvoiceToolInput {
+  format: "pdf" | "html";
+  invoice: InvoiceData;
+}
+
+export type inputType = RenderInvoiceToolInput;
+export type outputType = RenderInvoiceWrittenOutput;
+```
+
+| Export | Role |
+| --- | --- |
+| `export type configType = AppConfig` | `program.appConfig.jsonSchema` (one per repo, typically `src/config/schema-types.ts`) |
+| `export type outputType = …` | `leaf.outputSchema` |
+| `export type inputType = …` | `leaf.inputSchema` (only when the tool body is not flat CLI flags) |
+
+**Domain helpers** stay in `types.ts` (or `core/types.ts`). Discovery scans only `schema-types.ts`. Re-export-only files (`export type outputType = HeadlessOpResult` pointing at another module) are **not** generation roots — generate once from the canonical definition file.
+
+Commands without structured JSON omit `schema-types.ts` and import a shared bridge constant (e.g. `HEADLESS_OP_RESULT_OUTPUT_SCHEMA`).
+
+When you do **not** set `inputSchema`, argsbarg builds tool input from CLI `options` + `positionals`.
 
 ### Stable naming (outfile + bridge export)
 
-Discovery maps each root type name to a generated filename and `outputSchemas.ts` constant. Suffix conventions (implemented in `outfileForType` / `schemaExportName`):
+Discovery maps each root type name to a generated filename and bridge constant. Suffix conventions (implemented in `outfileForOutputType` / `outputSchemaExportName`):
 
 | Type suffix | Example type | Generated file | Bridge export |
 | --- | --- | --- | --- |
 | `JsonOutput` | `StatusJsonOutput` | `status.json` | `STATUS_JSON_OUTPUT_SCHEMA` |
 | `OpResult` | `HeadlessOpResult` | `headless-op-result.json` | `HEADLESS_OP_RESULT_OUTPUT_SCHEMA` |
 | `Output` | `OpenUrlOutput` | `open-url.json` | `OPEN_URL_OUTPUT_SCHEMA` |
-| `Result` | `UidsResult` | `uids.json` | `UIDS_OUTPUT_SCHEMA` |
+| `Result` | `PrResult` | `pr.json` | `PR_RESULT_OUTPUT_SCHEMA` |
+| `ToolInput` | `RenderInvoiceToolInput` | `render-invoice-tool-input.json` | `RENDER_INVOICE_TOOL_INPUT_SCHEMA` |
 
 Prefer these suffixes for new roots so filenames and import constants stay predictable across repos.
 
 ### Generated bridge
 
-`scripts/generate-output-schemas.ts` rewrites `src/schemas/outputSchemas.ts` on every run:
+`scripts/schemagen.ts` rewrites `schemas/outputSchemas.ts` on every run:
 
 ```typescript
-// Auto-generated by scripts/generate-output-schemas.ts — do not edit by hand.
+// Auto-generated by scripts/schemagen.ts — do not edit by hand.
 
 import status from "./generated/status.json";
 
-/** JSON Schema for `myapp status --json`. */
+/** JSON Schema for leaf outputSchema from `StatusJsonOutput`. */
 export const STATUS_JSON_OUTPUT_SCHEMA = status as Record<string, unknown>;
 ```
 
@@ -139,26 +172,24 @@ Wire the constant on each leaf that emits that shape (several commands may share
 
 **Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs api`.
 
-1. **Schema roots** — `export interface` in a `types.ts` file, with **`JSON payload`** in the interface JSDoc naming which command(s) emit it.
+1. **Schema roots** — `export interface` in `schema-types.ts`, with `export type outputType = …` (or `inputType` / `configType`).
 2. **Per property** — `/** … */` on every field that should appear in JSON Schema `properties` (including nested named types).
 3. **Unions / enums** — document the alias; generator emits `enum` / `anyOf` with type-level description.
 4. **Formats** — property JSDoc can include `@format date-time` for ISO timestamps; add a smoke test that the generated property has `format: "date-time"`.
-5. **Do not hand-edit** `src/schemas/generated/` or `src/schemas/outputSchemas.ts` — change types/JSDoc, run `just schemagen`, commit both.
+5. **Do not hand-edit** `schemas/generated/` or bridge modules — change types/JSDoc, run `just schemagen`, commit both.
 
 ### Narrowing when runtime ≠ stdout
 
-When a shared runtime type is **wider** than one command’s JSON, add a **schema-facing** root in `types.ts` (still marked `JSON payload`):
+When a shared runtime type is **wider** than one command’s JSON, add a **schema-facing** root in `schema-types.ts`:
 
 ```typescript
-/** Runtime union across commands. */
-export type ResultSource = TranslationReadinessSource | { kind: "uids"; uids: string[] };
-
-/** JSON payload for `myapp pr` and `myapp file`. */
+/** JSON stdout for `myapp pr` and `myapp file`. */
 export interface TranslationReadinessResult {
   source: TranslationReadinessSource;
   evaluatedAt: string;
-  // ...
 }
+
+export type outputType = TranslationReadinessResult;
 ```
 
 Patterns:
@@ -173,18 +204,18 @@ Handlers keep using runtime types; only discovered roots (and their type graph)
 Per repo:
 
 - **`scripts/schemagen/discover-schema-roots.test.ts`** — asserts which roots are discovered and stable outfile / export-name mapping.
-- **`src/schemas/outputSchemas.test.ts`** (optional) — schema shape smoke tests: object root, key `description` fields, enums, `@format date-time`.
+- **`schemas/outputSchemas.test.ts`** (optional) — schema shape smoke tests: object root, key `description` fields, enums, `@format date-time`.
 
 ## Contributor workflow
 
-1. Add or edit schema-facing interfaces in `src/**/types.ts` with **`JSON payload`** JSDoc and per-field descriptions.
-2. `just schemagen` — refresh `src/schemas/generated/` and `src/schemas/outputSchemas.ts`.
-3. Import the bridge constant on the relevant leaf `outputSchema` fields.
-4. Commit generated JSON and the bridge with the type changes.
+1. Add or edit schema roots in `src/**/schema-types.ts` with `outputType` / `inputType` / `configType` and per-field JSDoc.
+2. `just schemagen` — refresh `schemas/generated/` and bridge modules.
+3. Import the bridge constant on the relevant leaf `outputSchema` / `inputSchema` fields.
+4. Commit generated JSON and bridges with the type changes.
 5. `just docgen` / `myapp docs api --save` — refresh consumer docs.
 6. Document which commands use which roots in **your** `docs/architecture.md` (argsbarg does not maintain per-app tables).
 
-Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` pointing at `node_modules/argsbarg/docs/output-schema.md` and your `src/schemas/` layout.
+Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` pointing at `node_modules/argsbarg/docs/output-schema.md` and your `schemas/` layout.
 
 **Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo (shipped in npm as `node_modules/argsbarg/examples/full-example/`) — discovery script, bridges, and `status` leaf with `outputSchema`.
 
@@ -193,10 +224,10 @@ Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/c
 - Shared codegen package or monorepo tooling
 - Runtime Zod / `.parse()` on stdout in argsbarg
 - `outputSchema` for plain-text, streaming, or Ink-only commands
-- Schema roots outside `src/**/types.ts` (use a dedicated `types.ts` next to handlers instead of `resolve.ts`)
 
 ## See also
 
+- [config-schema.md](config-schema.md) — `configType` / `program.appConfig`
 - [cli-program.md](cli-program.md) — structured stdout, headless JSON, `read*Flags`
 - [mcp.md](mcp.md) — `tools/list`, `structuredContent`
 - [bundled-docs.md](bundled-docs.md) — `docs api` / `docs cli-schema` docgen

package/examples/full-example/README.md

@@ -9,7 +9,7 @@ From a git checkout at this directory (requires [Homebrew](https://brew.sh), [ju
 ```bash
 brew install just bun
 just setup
-just schemagen   # after changing src/**/types.ts
+just schemagen   # after changing src/**/schema-types.ts
 just run status --json
 just run docs readme
 ```
@@ -60,14 +60,15 @@ just test-release
 
 Undo a local dev install: `just uninstall` (formula + agent artifacts; app config removed by formula `uninstall`), `just uninstall-config` (app config only, without uninstalling the formula).
 
-## Schemagen markers
+## Schemagen roots
 
-| Marker in interface JSDoc | Artifact |
+| Export in `schema-types.ts` | Artifact |
 | --- | --- |
-| `Config schema` | `schemas/configSchemas.ts` + `schemas/generated/*-config.json` |
-| `JSON payload` | `schemas/outputSchemas.ts` + `schemas/generated/*.json` |
+| `export type configType = …` | `schemas/configSchemas.ts` + `schemas/generated/*-config.json` |
+| `export type outputType = …` | `schemas/outputSchemas.ts` + `schemas/generated/*.json` |
+| `export type inputType = …` | `schemas/inputSchemas.ts` + `schemas/generated/*-tool-input.json` |
 
-Discovery walks `src/**/types.ts` only.
+Discovery walks `src/**/schema-types.ts` only. Domain helpers stay in sibling `types.ts`.
 
 ## Consumer docs
 

package/examples/full-example/schemas/generated/app-config.json

@@ -35,6 +35,6 @@
     "maxRetries"
   ],
   "additionalProperties": false,
-  "description": "Config schema\n\nApplication settings for `full-example` (`program.appConfig`).",
+  "description": "Application settings for `full-example` (`program.appConfig`).",
   "definitions": {}
 }

package/examples/full-example/schemas/generated/status.json

@@ -23,6 +23,6 @@
     "apiTokenSet",
     "version"
   ],
-  "description": "JSON payload for `full-example status --json`.",
+  "description": "JSON stdout for `full-example status --json`.",
   "definitions": {}
 }

package/examples/full-example/scripts/schemagen/discover-schema-roots.test.ts

@@ -5,19 +5,19 @@ import { discoverSchemaRoots } from "./discover-schema-roots.ts";
 const projectRoot = join(import.meta.dir, "../..");
 
 describe("discover-schema-roots", () => {
-  test("finds AppConfig and StatusJsonOutput in src types.ts files", () => {
+  test("finds AppConfig and StatusJsonOutput in schema-types.ts files", () => {
     const roots = discoverSchemaRoots(projectRoot);
     const config = roots.find((r) => r.kind === "config");
     const output = roots.find((r) => r.kind === "output");
     expect(config).toMatchObject({
       typeName: "AppConfig",
-      relFile: "src/types.ts",
+      path: "src/config/schema-types.ts",
       outfile: "app-config.json",
       exportName: "APP_CONFIG_JSON_SCHEMA",
     });
     expect(output).toMatchObject({
       typeName: "StatusJsonOutput",
-      relFile: "src/commands/status/types.ts",
+      path: "src/commands/status/schema-types.ts",
       outfile: "status.json",
       exportName: "STATUS_JSON_OUTPUT_SCHEMA",
     });

package/examples/full-example/scripts/schemagen/discover-schema-roots.ts

@@ -1,5 +1,5 @@
 /*
-Discovers schema roots in src (recursive) types.ts files by JSDoc markers.
+Discovers schema roots in schema-types.ts files via configType / inputType / outputType exports.
 Copy per consumer repo — see docs/output-schema.md and docs/config-schema.md.
 */
 
@@ -7,87 +7,142 @@ import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 import {
   configSchemaExportName,
+  inputSchemaExportName,
   outfileForConfigType,
+  outfileForInputType,
   outfileForOutputType,
   outputSchemaExportName,
 } from "./naming.ts";
 
-export type SchemaRootKind = "config" | "output";
+export type SchemaRootKind = "config" | "input" | "output";
+
+export type SchemaRole = "configType" | "inputType" | "outputType";
 
 export interface SchemaRoot {
   kind: SchemaRootKind;
   typeName: string;
-  /** Path relative to project root (e.g. src/types.ts). */
-  relFile: string;
+  /** Path relative to project root (e.g. src/config/schema-types.ts). */
+  path: string;
   outfile: string;
   exportName: string;
 }
 
-const CONFIG_MARKER = "Config schema";
-const OUTPUT_MARKER = "JSON payload";
+const SCHEMA_TYPES_FILE = "schema-types.ts";
+
+const ROLE_EXPORT_RE = /export\s+type\s+(configType|inputType|outputType)\s*=\s*(\w+)/g;
 
-const INTERFACE_RE = /\/\*\*([\s\S]*?)\*\/\s*export\s+interface\s+(\w+)/g;
+const ROLE_TO_KIND: Record<SchemaRole, SchemaRootKind> = {
+  configType: "config",
+  inputType: "input",
+  outputType: "output",
+};
 
-function listTypesTsFiles(srcDir: string, baseDir: string, out: string[]): void {
+function listSchemaTypesFiles(srcDir: string, baseDir: string, out: string[]): void {
   for (const ent of readdirSync(srcDir)) {
     const full = join(srcDir, ent);
     const st = statSync(full);
     if (st.isDirectory()) {
-      listTypesTsFiles(full, baseDir, out);
+      listSchemaTypesFiles(full, baseDir, out);
       continue;
     }
-    if (ent === "types.ts") {
+    if (ent === SCHEMA_TYPES_FILE) {
       out.push(relative(baseDir, full));
     }
   }
 }
 
-function classifyRoot(jsDoc: string, typeName: string, relFile: string): SchemaRoot | undefined {
-  const hasConfig = jsDoc.includes(CONFIG_MARKER);
-  const hasOutput = jsDoc.includes(OUTPUT_MARKER);
-  if (hasConfig && hasOutput) {
-    throw new Error(`${relFile}: ${typeName} has both Config schema and JSON payload markers`);
+/** True when `typeName` is declared in this file (not a re-export alias to another module). */
+function isTypeDefinedInFile(text: string, typeName: string): boolean {
+  if (new RegExp(`export\\s+interface\\s+${typeName}\\b`).test(text)) {
+    return true;
   }
-  if (!hasConfig && !hasOutput) {
-    return undefined;
+  if (new RegExp(`export\\s+type\\s+${typeName}\\s*=`).test(text)) {
+    return !["configType", "inputType", "outputType"].includes(typeName);
   }
-  if (hasConfig) {
+  return false;
+}
+
+function rootForRole(role: SchemaRole, typeName: string, path: string): SchemaRoot {
+  const kind = ROLE_TO_KIND[role];
+  if (kind === "config") {
     return {
-      kind: "config",
+      kind,
       typeName,
-      relFile,
+      path,
       outfile: outfileForConfigType(typeName),
       exportName: configSchemaExportName(typeName),
     };
   }
+  if (kind === "input") {
+    return {
+      kind,
+      typeName,
+      path,
+      outfile: outfileForInputType(typeName),
+      exportName: inputSchemaExportName(typeName),
+    };
+  }
   return {
-    kind: "output",
+    kind,
     typeName,
-    relFile,
+    path,
     outfile: outfileForOutputType(typeName),
     exportName: outputSchemaExportName(typeName),
   };
 }
 
-/** Find all schema roots under `src/` in files named types.ts. */
+function discoverFromFile(path: string, text: string): SchemaRoot[] {
+  const rolesSeen = new Set<SchemaRole>();
+  const roots: SchemaRoot[] = [];
+
+  for (const match of text.matchAll(ROLE_EXPORT_RE)) {
+    const role = match[1] as SchemaRole | undefined;
+    const typeName = match[2];
+    if (!role || !typeName) {
+      continue;
+    }
+    if (rolesSeen.has(role)) {
+      throw new Error(`${path}: duplicate export type ${role}`);
+    }
+    rolesSeen.add(role);
+    if (!isTypeDefinedInFile(text, typeName)) {
+      continue;
+    }
+    roots.push(rootForRole(role, typeName, path));
+  }
+
+  return roots;
+}
+
+/** Find all schema roots under `src/` in files named schema-types.ts. */
 export function discoverSchemaRoots(projectRoot: string): SchemaRoot[] {
   const srcDir = join(projectRoot, "src");
   const files: string[] = [];
-  listTypesTsFiles(srcDir, projectRoot, files);
+  listSchemaTypesFiles(srcDir, projectRoot, files);
+
   const roots: SchemaRoot[] = [];
-  for (const relFile of files.sort()) {
-    const text = readFileSync(join(projectRoot, relFile), "utf8");
-    for (const match of text.matchAll(INTERFACE_RE)) {
-      const jsDoc = match[1] ?? "";
-      const typeName = match[2];
-      if (!typeName) {
-        continue;
-      }
-      const root = classifyRoot(jsDoc, typeName, relFile);
-      if (root) {
-        roots.push(root);
+  const typeOwners = new Map<string, string>();
+
+  for (const relPath of files.sort()) {
+    const text = readFileSync(join(projectRoot, relPath), "utf8");
+    for (const root of discoverFromFile(relPath, text)) {
+      const prev = typeOwners.get(root.typeName);
+      if (prev) {
+        throw new Error(
+          `${relPath}: duplicate schema root type ${root.typeName} (already declared in ${prev})`,
+        );
       }
+      typeOwners.set(root.typeName, relPath);
+      roots.push(root);
     }
   }
+
+  const configRoots = roots.filter((r) => r.kind === "config");
+  if (configRoots.length > 1) {
+    throw new Error(
+      `multiple config schema roots: ${configRoots.map((r) => `${r.typeName} (${r.path})`).join(", ")}`,
+    );
+  }
+
   return roots;
 }

package/examples/full-example/scripts/schemagen/naming.ts

@@ -16,6 +16,23 @@ export function camelToScreamingSnake(name: string): string {
   return camelToKebab(name).replace(/-/g, "_").toUpperCase();
 }
 
+/** Generated JSON filename for a tool-input schema root. */
+export function outfileForInputType(typeName: string): string {
+  if (typeName.endsWith("ToolInput")) {
+    return `${camelToKebab(typeName.slice(0, -"ToolInput".length))}-tool-input.json`;
+  }
+  return `${camelToKebab(typeName)}-tool-input.json`;
+}
+
+/** Bridge export constant for a tool-input schema root. */
+export function inputSchemaExportName(typeName: string): string {
+  if (typeName.endsWith("ToolInput")) {
+    const base = typeName.slice(0, -"ToolInput".length);
+    return `${camelToScreamingSnake(base)}_TOOL_INPUT_SCHEMA`;
+  }
+  return `${camelToScreamingSnake(typeName)}_TOOL_INPUT_SCHEMA`;
+}
+
 /** Generated JSON filename for an output-schema root type. */
 export function outfileForOutputType(typeName: string): string {
   if (typeName.endsWith("JsonOutput")) {

package/examples/full-example/scripts/schemagen.ts

@@ -1,5 +1,5 @@
 /*
-Generate JSON Schema artifacts and bridge modules from discovered types.ts roots.
+Generate JSON Schema artifacts and bridge modules from discovered schema-types.ts roots.
 */
 
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -13,7 +13,7 @@ const generatedDir = join(projectRoot, "schemas", "generated");
 
 function generateJson(root: SchemaRoot): Record<string, unknown> {
   const generator = createGenerator({
-    path: join(projectRoot, root.relFile),
+    path: join(projectRoot, root.path),
     type: root.typeName,
     tsconfig: join(projectRoot, "tsconfig.json"),
     topRef: false,
@@ -52,6 +52,7 @@ function writeBridge(path: string, scriptName: string, roots: SchemaRoot[], bann
 
 const roots = discoverSchemaRoots(projectRoot);
 const configRoots = roots.filter((r) => r.kind === "config");
+const inputRoots = roots.filter((r) => r.kind === "input");
 const outputRoots = roots.filter((r) => r.kind === "output");
 
 mkdirSync(generatedDir, { recursive: true });
@@ -70,6 +71,14 @@ writeBridge(
   configRoots,
   "JSON Schema for program.appConfig.jsonSchema from",
 );
+if (inputRoots.length > 0) {
+  writeBridge(
+    join(projectRoot, "schemas", "inputSchemas.ts"),
+    "schemagen.ts",
+    inputRoots,
+    "JSON Schema for leaf inputSchema from",
+  );
+}
 writeBridge(
   join(projectRoot, "schemas", "outputSchemas.ts"),
   "schemagen.ts",
@@ -77,4 +86,6 @@ writeBridge(
   "JSON Schema for leaf outputSchema from",
 );
 
-console.log(`config roots: ${configRoots.length}, output roots: ${outputRoots.length}`);
+console.log(
+  `config roots: ${configRoots.length}, input roots: ${inputRoots.length}, output roots: ${outputRoots.length}`,
+);

package/examples/full-example/src/commands/status/schema-types.ts

@@ -0,0 +1,14 @@
+/** JSON stdout for `full-example status --json`. */
+export interface StatusJsonOutput {
+  /** Resolved AWS region. */
+  defaultRegion?: string;
+  /** Resolved retry count. */
+  maxRetries?: number;
+  /** Whether apiToken is set (value never included). */
+  apiTokenSet: boolean;
+  /** App version from program root. */
+  version: string;
+}
+
+/** Schemagen root for leaf outputSchema. */
+export type outputType = StatusJsonOutput;

package/examples/full-example/src/commands/status/types.ts

@@ -1,11 +1 @@
-/** JSON payload for `full-example status --json`. */
-export interface StatusJsonOutput {
-  /** Resolved AWS region. */
-  defaultRegion?: string;
-  /** Resolved retry count. */
-  maxRetries?: number;
-  /** Whether apiToken is set (value never included). */
-  apiTokenSet: boolean;
-  /** App version from program root. */
-  version: string;
-}
+export type { StatusJsonOutput } from "./schema-types.ts";

package/examples/full-example/src/{types.ts → config/schema-types.ts}

@@ -1,6 +1,4 @@
 /**
- * Config schema
- *
  * Application settings for `full-example` (`program.appConfig`).
  */
 export interface AppConfig {
@@ -21,3 +19,6 @@ export interface AppConfig {
     ttl: number;
   };
 }
+
+/** Schemagen root for program.appConfig.jsonSchema. */
+export type configType = AppConfig;

package/package.json

@@ -1,18 +1,13 @@
 {
   "name": "argsbarg",
-  "version": "6.0.0",
-  "type": "module",
-  "engines": {
-    "bun": ">=1.3"
-  },
-  "scripts": {
-    "//just": "echo this app uses justfile for development tasks"
-  },
+  "version": "6.0.1",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
-  "types": "./index.d.ts",
-  "bin": {
-    "argsbarg": "src/cli-tool/main.ts"
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@types/bun": "^1.3.12",
+    "dts-bundle-generator": "^9.5.1",
+    "typescript": "^5.9.3"
   },
   "exports": {
     ".": {
@@ -20,6 +15,12 @@
       "default": "./src/index.ts"
     }
   },
+  "bin": {
+    "argsbarg": "src/cli-tool/main.ts"
+  },
+  "engines": {
+    "bun": ">=1.3"
+  },
   "files": [
     "src",
     "index.d.ts",
@@ -29,10 +30,9 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.0",
-    "@types/bun": "^1.3.12",
-    "dts-bundle-generator": "^9.5.1",
-    "typescript": "^5.9.3"
-  }
+  "scripts": {
+    "//just": "echo this app uses justfile for development tasks"
+  },
+  "type": "module",
+  "types": "./index.d.ts"
 }

package/src/api/openapi.ts

@@ -4,6 +4,7 @@ Hand-built OpenAPI 3.1 document from exposed MCP tools.
 
 import { collectMcpTools } from "../mcp/tools.ts";
 import type { CliProgram } from "../types.ts";
+import { dereferenceJsonSchema } from "./schema-deref.ts";
 
 const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
 
@@ -18,8 +19,9 @@ function buildSuccessResponse(tool: ReturnType<typeof collectMcpTools>[number]):
   const media: Record<string, unknown> = {};
 
   if (contentType.includes("application/json")) {
+    const outputSchema = tool.outputSchema ?? { type: "object" };
     media[contentType] = {
-      schema: tool.outputSchema ?? { type: "object" },
+      schema: dereferenceJsonSchema(outputSchema),
     };
   } else if (contentType.includes("text/html")) {
     media[contentType] = { schema: { type: "string" } };
@@ -48,7 +50,7 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
           required: false,
           content: {
             [JSON_CONTENT_TYPE]: {
-              schema: tool.inputSchema,
+              schema: dereferenceJsonSchema(tool.inputSchema),
             },
           },
         },

package/src/api/result.ts

@@ -12,6 +12,21 @@ export interface ApiToolCallErrorBody {
   stderr?: string;
 }
 
+/** Strips ANSI escape sequences from CLI-formatted text. */
+export function stripAnsi(text: string): string {
+  const ansiEscape = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+  return text.replace(ansiEscape, "");
+}
+
+/** Returns the first non-empty line of text with ANSI escapes removed. */
+export function firstErrorLine(text: string): string {
+  const line = stripAnsi(text)
+    .split("\n")
+    .map((part) => part.trim())
+    .find((part) => part.length > 0);
+  return line ?? stripAnsi(text).trim();
+}
+
 /** Wide-open CORS headers applied to all API responses. */
 export const API_CORS_HEADERS: Readonly<Record<string, string>> = {
   "access-control-allow-origin": "*",
@@ -82,8 +97,15 @@ export function apiDocsHtml(): string {
   <title>API Reference</title>
 </head>
 <body>
-  <script id="api-reference" data-url="/openapi.json"></script>
+  <div id="api-reference"></div>
   <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  <script>
+    Scalar.createApiReference("#api-reference", {
+      url: "/openapi.json",
+      orderSchemaPropertiesBy: "preserve",
+      orderRequiredPropertiesFirst: false,
+    });
+  </script>
 </body>
 </html>`;
 }

package/src/api/schema-deref.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from "bun:test";
+import { dereferenceJsonSchema } from "./schema-deref.ts";
+
+test("dereferenceJsonSchema inlines nested definitions", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      invoice: { $ref: "#/definitions/InvoiceData" },
+    },
+    definitions: {
+      InvoiceData: {
+        type: "object",
+        properties: { id: { type: "string" } },
+        required: ["id"],
+      },
+    },
+  };
+  const out = dereferenceJsonSchema(schema);
+  expect(out.properties).toEqual({
+    invoice: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+    },
+  });
+  expect(out.definitions).toBeUndefined();
+});
+
+test("dereferenceJsonSchema supports $defs", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      item: { $ref: "#/$defs/Item" },
+    },
+    $defs: {
+      Item: { type: "string" },
+    },
+  };
+  const out = dereferenceJsonSchema(schema);
+  expect(out.properties).toEqual({ item: { type: "string" } });
+  expect(out.$defs).toBeUndefined();
+});
+
+test("dereferenceJsonSchema merges $ref siblings", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      invoice: {
+        $ref: "#/definitions/InvoiceData",
+        description: "Invoice payload",
+      },
+    },
+    definitions: {
+      InvoiceData: { type: "object" },
+    },
+  };
+  const out = dereferenceJsonSchema(schema) as {
+    properties: { invoice: { type: string; description: string } };
+  };
+  expect(out.properties.invoice).toEqual({
+    type: "object",
+    description: "Invoice payload",
+  });
+});
+
+test("dereferenceJsonSchema ignores circular refs", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      self: { $ref: "#/definitions/Node" },
+    },
+    definitions: {
+      Node: {
+        type: "object",
+        properties: {
+          again: { $ref: "#/definitions/Node" },
+        },
+      },
+    },
+  };
+  const out = dereferenceJsonSchema(schema) as {
+    properties: { self: { type: string; properties: { again: { $ref: string } } } };
+  };
+  expect(out.properties.self.type).toBe("object");
+  expect(out.properties.self.properties.again).toEqual({ $ref: "#/definitions/Node" });
+});
+
+test("dereferenceJsonSchema leaves external refs unchanged", () => {
+  const schema = {
+    type: "object",
+    properties: {
+      remote: { $ref: "https://example.com/schema.json" },
+    },
+  };
+  const out = dereferenceJsonSchema(schema);
+  expect(out.properties).toEqual({
+    remote: { $ref: "https://example.com/schema.json" },
+  });
+});

package/src/api/schema-deref.ts

@@ -0,0 +1,76 @@
+/*
+Inline JSON Schema $ref dereferencing for OpenAPI embedding.
+*/
+
+function decodeJsonPointerSegment(segment: string): string {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Resolves a same-document JSON Pointer (`#/definitions/Foo`). */
+function resolveJsonPointer(root: Record<string, unknown>, ref: string): unknown {
+  if (!ref.startsWith("#/")) {
+    return undefined;
+  }
+  const segments = ref
+    .slice(2)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (!isPlainObject(current)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+function derefValue(value: unknown, root: Record<string, unknown>, resolving: Set<string>): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => derefValue(item, root, resolving));
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+
+  if (typeof value.$ref === "string") {
+    const { $ref, ...siblings } = value;
+    if (resolving.has($ref)) {
+      return value;
+    }
+    const target = resolveJsonPointer(root, $ref);
+    if (target === undefined) {
+      return value;
+    }
+    resolving.add($ref);
+    const resolved = derefValue(structuredClone(target), root, resolving);
+    resolving.delete($ref);
+    if (!isPlainObject(resolved)) {
+      return resolved;
+    }
+    if (Object.keys(siblings).length === 0) {
+      return resolved;
+    }
+    return { ...resolved, ...siblings };
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "definitions" || key === "$defs") {
+      continue;
+    }
+    out[key] = derefValue(child, root, resolving);
+  }
+  return out;
+}
+
+/** Inlines internal `$ref` pointers and drops `definitions` / `$defs` from the output. */
+export function dereferenceJsonSchema(schema: Record<string, unknown>): Record<string, unknown> {
+  const root = structuredClone(schema);
+  return derefValue(root, root, new Set()) as Record<string, unknown>;
+}

package/src/api.integration.test.ts

@@ -8,7 +8,7 @@ import { $ } from "bun";
 import { generateOpenApi } from "./api/openapi.ts";
 import { API_CORS_HEADERS } from "./api/result.ts";
 import { handleApiRequest } from "./api/server.ts";
-import { Cli, CliContext, type CliContext as CliContextType, CliOptionKind } from "./index.ts";
+import { Cli, CliContext, type CliContext as CliContextType, CliOptionKind, cliErrWithHelp } from "./index.ts";
 import { nestedMcpFixture, testProgram } from "./test-fixtures.ts";
 import { cliValidateProgram } from "./validate.ts";
 
@@ -290,6 +290,37 @@ describe("HTTP API routes", () => {
     expect(res.status).toBe(400);
     const body = (await res.json()) as { error: string };
     expect(body.error).toContain("Missing argument: path");
+    expect(body).not.toHaveProperty("stderr");
+    expect(body.error).not.toContain("\u001B[");
+  });
+
+  test("POST /tools/:name returns plain JSON validation errors", async () => {
+    const failProgram = testProgram({
+      key: "app",
+      description: "Test app",
+      apiServer: { enabled: true },
+      commands: [
+        {
+          key: "fail",
+          description: "Fails with cliErrWithHelp.",
+          handler: (ctx: CliContextType) => {
+            cliErrWithHelp(ctx, "bad input");
+          },
+        },
+      ],
+    });
+    cliValidateProgram(failProgram);
+    const res = await apiRequest(
+      failProgram,
+      new Request("http://127.0.0.1/tools/fail", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toEqual({ error: "bad input" });
   });
 
   test("GET /openapi.json lists tool paths", async () => {
@@ -304,7 +335,10 @@ describe("HTTP API routes", () => {
     const res = await apiRequest(program, new Request("http://127.0.0.1/openapi-browser"));
     expect(res.status).toBe(200);
     expect(res.headers.get("content-type")).toContain("text/html");
-    expect(await res.text()).toContain("@scalar/api-reference");
+    const html = await res.text();
+    expect(html).toContain("@scalar/api-reference");
+    expect(html).toContain('orderSchemaPropertiesBy: "preserve"');
+    expect(html).toContain("orderRequiredPropertiesFirst: false");
   });
 });
 
@@ -319,6 +353,55 @@ test("generateOpenApi maps binary content types", () => {
   expect(pdf.schema.format).toBe("binary");
 });
 
+test("generateOpenApi dereferences nested inputSchema definitions", () => {
+  const program = testProgram({
+    key: "app",
+    description: "Test app",
+    apiServer: { enabled: true },
+    commands: [
+      {
+        key: "render",
+        description: "Render a document.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            invoice: { $ref: "#/definitions/InvoiceData" },
+          },
+          definitions: {
+            InvoiceData: {
+              type: "object",
+              properties: {
+                id: { type: "string" },
+              },
+              required: ["id"],
+            },
+          },
+        },
+        handler: () => ({ ok: true }),
+      },
+    ],
+  });
+  cliValidateProgram(program);
+  const doc = generateOpenApi(program) as {
+    paths: Record<
+      string,
+      {
+        post: {
+          requestBody: {
+            content: Record<string, { schema: { properties: { invoice: Record<string, unknown> } } }>;
+          };
+        };
+      }
+    >;
+  };
+  const schema = doc.paths["/tools/render"]?.post.requestBody.content["application/json; charset=utf-8"].schema;
+  expect(schema.properties.invoice).toEqual({
+    type: "object",
+    properties: { id: { type: "string" } },
+    required: ["id"],
+  });
+});
+
 test("ctx.respond throws when called twice", () => {
   const program = testProgram({
     key: "app",

package/src/cli-errors.ts

@@ -7,6 +7,9 @@ import type { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
 
 export function cliErrWithHelp(ctx: CliContext, msg: string): never {
+  if (ctx.invocation === "api" || ctx.invocation === "mcp") {
+    throw new Error(msg);
+  }
   const color = process.stderr.isTTY;
   const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
   process.stderr.write(`${line}\n`);

package/src/docs/mcp-resources.ts

@@ -3,7 +3,7 @@ Auto MCP resources for user docs.topics when docs and MCP are both enabled.
 */
 
 import type { CliProgram } from "../types.ts";
-import { docsEnabled, docsTopicContent, docsTopicDescription, docsUserTopicKeys } from "./resolve.ts";
+import { docsEnabled, docsTopicDescription, docsTopicText, docsUserTopicKeys } from "./resolve.ts";
 
 /** Default URI pattern for a docs topic MCP resource (`<mcpId>://docs/<topicKey>`). */
 export function defaultDocsTopicResourceUri(mcpId: string, topicKey: string): string {
@@ -45,7 +45,10 @@ export function docsMcpResources(program: CliProgram): {
       name: key,
       description: docsTopicDescription(key, topic.description),
       mimeType: "text/markdown",
-      load: () => docsTopicContent(program, key),
+      load: () => {
+        const text = docsTopicText(program, key);
+        return text.endsWith("\n") ? text : `${text}\n`;
+      },
     };
   });
 }

package/src/headless/tool-call.ts

@@ -2,7 +2,7 @@
 Shared headless tool dispatch for MCP and HTTP: config bootstrap, argv conversion, and invoke.
 */
 
-import { apiErrorResponse, apiSuccessResponse } from "../api/result.ts";
+import { apiErrorResponse, apiSuccessResponse, firstErrorLine } from "../api/result.ts";
 import type { Cli, CliInvokeResult } from "../cli.ts";
 import { bootstrapAppConfig } from "../config/bootstrap.ts";
 import { formatMcpMissingConfigMessage, missingRequiredConfig } from "../config/resolve.ts";
@@ -137,11 +137,21 @@ export function headlessSuccessToHttpResponse(
 
 /** Maps a headless failure result to a JSON HTTP error Response. */
 export function headlessFailureToHttpResponse(result: HeadlessToolCallFailure): Response {
-  const status = result.kind === "argv" || result.kind === "help" ? 400 : 500;
+  const status = resolveHttpErrorStatus(result);
   return apiErrorResponse(status, {
-    error: result.message,
-    exitCode: result.exitCode,
-    stdout: result.stdout,
-    stderr: result.stderr,
+    error: firstErrorLine(result.message),
   });
 }
+
+function resolveHttpErrorStatus(result: HeadlessToolCallFailure): number {
+  if (result.kind === "argv" || result.kind === "help") {
+    return 400;
+  }
+  if (result.kind === "invoke" && result.message.includes("ctx.respond()")) {
+    return 500;
+  }
+  if (result.exitCode === 1) {
+    return 400;
+  }
+  return 500;
+}