argsbarg 6.0.0 → 6.0.2

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.0.2] - 2026-07-22
+
+### Added
+
+- **`argsbarg schemagen`** — centralized JSON Schema generation from `src/**/schema.ts` into colocated `__generated__/` directories (`configSchema.json`, `inputSchema.json`, `outputSchema.json`, plus `index.ts` re-exports). Removes orphan `__generated__/` trees and stale JSON when schema roots or kinds are removed.
+- **`argsbarg/schemagen`** export — `runSchemagen`, `discoverSchemaRoots`, and naming helpers (`src/cli-tool/schemagen/`).
+
+### Changed
+
+- **Schemagen convention** — replace per-repo `scripts/schemagen*` copies and `schema-types.ts` bindings with `schema.ts` + gitignored `__generated__/`. Run via `just schemagen` (`argsbarg schemagen` with `node_modules/.bin` on `PATH`).
+
+## [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
+
+- **Colocated schemagen** — `*.schema.json` beside each `schema-types.ts`; exports `configSchema` / `inputSchema` / `outputSchema` (replaces central `*Schemas.ts` bridges).
+- **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 +739,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.0.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.0.2...HEAD
+[6.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.2
+[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,9 +267,9 @@ 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`                            |
-| Schemagen             | `scripts/schemagen.ts` + `scripts/schemagen/discover-schema-roots.ts`                  |
+| `program.appConfig`   | `src/config/schema.ts` → `configSchema` from `__generated__/`                         |
+| `outputSchema`        | `src/commands/status/schema.ts` → `outputSchema` from `__generated__/`                  |
+| Schemagen             | `just schemagen` → `argsbarg schemagen` (justfile exports `node_modules/.bin` on `PATH`) |
 | Command layout        | `src/commands/<name>/command.ts`; registration in `src/program.ts`                     |
 | MCP doc topics        | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled |
 | Package import        | `from "argsbarg"` (not relative to argsbarg `src/`)                                    |

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

@@ -136,39 +136,51 @@ Interactive `configure` does not persist values supplied only by env or `resolve
 | **Omit `jsonSchema`** | Simple apps; all values stored as strings; use `entry.default` |
 | **Codegen from TypeScript** | Typed config, nested objects, shared with JSON Schema CI |
 
-## Recommended pipeline (copy per repo)
+## Recommended pipeline (argsbarg schemagen)
 
 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.ts]
+    Marker["export type configType = AppConfig"]
   end
-  subgraph gen [just schemagen]
-    Script["scripts/generate-config-schemas.ts"]
+  subgraph gen [argsbarg schemagen]
+    Script["argsbarg schemagen"]
     Gen["ts-json-schema-generator"]
   end
-  subgraph artifacts [Committed]
-    Json["src/schemas/generated/app-config.json"]
-    Bridge["src/schemas/configSchemas.ts"]
+  subgraph artifacts [Gitignored __generated__]
+    Json["configSchema.json"]
+    Index["index.ts"]
   end
   subgraph runtime [Runtime]
     Program["program.appConfig.jsonSchema"]
     Validate["argsbarg runtime subset validator"]
   end
-  TypesTs --> Marker --> Script --> Gen --> Json
-  Script --> Bridge --> Program --> Validate
+  types --> Script --> Gen --> Json
+  Gen --> Index --> 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 |
-| Artifacts | Commit `app-config.json` and `configSchemas.ts` bridge exporting `APP_CONFIG_JSON_SCHEMA` |
+| Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled with argsbarg) |
+| Discovery | `export type configType = …` in `src/config/schema.ts` (type defined in same file) |
+| Artifacts | `src/config/__generated__/` — gitignored; run `just schemagen` after clone |
 | Consumer CI | Optional: `ajv` + `ajv-formats` against the same committed JSON (not an argsbarg runtime dep) |
 
+Example:
+
+```typescript
+// src/config/schema.ts
+export interface AppConfig {
+  apiToken: string;
+}
+
+export type configType = AppConfig;
+```
+
+Wire on the program root: `import { configSchema } from "./config/__generated__/index.ts"`.
+
 ### Supported AppConfig shapes (argsbarg runtime validator)
 
 | Supported (v1) | Deferred |
@@ -210,7 +222,7 @@ Object/array/`$ref` properties require `--json` on `configure set` when comma-se
 
 | Example | Role |
 | --- | --- |
-| [`examples/full-example/`](../examples/full-example/) | **Copy template** — schemagen discovery, `APP_CONFIG_JSON_SCHEMA` bridge, `program.appConfig`, built-in `configure get`/`set` |
+| [`examples/full-example/`](../examples/full-example/) | **Copy template** — `argsbarg schemagen`, `program.appConfig`, built-in `configure get`/`set` |
 
 ```bash
 cd examples/full-example && just setup && just schemagen

package/docs/output-schema.md

@@ -1,18 +1,18 @@
 # Output schemas (`outputSchema`)
 
-How to describe JSON stdout on leaf commands — and a **recommended codegen pipeline** used in production argsbarg apps.
+How to describe JSON stdout on leaf commands — and the **argsbarg schemagen** pipeline used in production apps.
 
 ## Argsbarg contract
 
 On **leaf commands**, set `outputSchema` to a JSON Schema object when the handler emits JSON (typically with `--json`, always for JSON-only commands, or on the MCP headless path).
 
 ```typescript
-import { STATUS_JSON_OUTPUT_SCHEMA } from "../schemas/outputSchemas.js";
+import { outputSchema } from "./__generated__/index.ts";
 
 export const status = {
   key: "status",
   description: "Show environment status.",
-  outputSchema: STATUS_JSON_OUTPUT_SCHEMA,
+  outputSchema,
   handler: async (ctx) => { /* writes JSON to stdout */ },
 } satisfies CliLeaf;
 ```
@@ -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).
 
@@ -41,124 +42,156 @@ See [cli-program.md — Structured stdout](cli-program.md#structured-stdout) for
 
 Production CLIs with several JSON commands tend to use **codegen** so types, handlers, and schemas stay aligned.
 
-## Recommended pipeline (copy per repo)
+## Schemagen pipeline (built into argsbarg)
 
-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 per-repo scripts to copy — run **`argsbarg schemagen`** (or `import { runSchemagen } from "argsbarg/schemagen"`).
+
+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.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"]
+  subgraph gen [argsbarg schemagen]
+    Discover["discover schema.ts roots"]
     Gen["ts-json-schema-generator"]
   end
-  subgraph artifacts [Committed]
-    Json["src/schemas/generated/*.json"]
-    Bridge["src/schemas/outputSchemas.ts"]
+  subgraph artifacts [Gitignored __generated__]
+    Json["configSchema.json / inputSchema.json / outputSchema.json"]
+    Index["index.ts re-exports"]
   end
   subgraph runtime [Runtime]
-    Leaves["leaf outputSchema"]
+    Leaves["import { outputSchema } from ./__generated__/index.ts"]
     Docgen["just docgen"]
   end
-  TypesTs --> Marker --> Discover
-  Narrow --> Discover
-  Discover --> Script --> Gen --> Json
-  Script --> Bridge --> Leaves --> Docgen
+  types --> Discover --> Gen --> Json
+  Gen --> Index --> Leaves --> Docgen
 ```
 
 | Piece | Convention |
 | --- | --- |
-| 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` |
+| Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled as an argsbarg dependency) |
+| Discovery | Walk `src/**/schema.ts`; generate from `export type outputType = …` / `inputType` / `configType` when the target type is **defined in that file** |
+| Artifacts | `src/**/__generated__/` — gitignored; run schemagen after clone or when `schema.ts` changes |
+| Invocation | `just schemagen` — justfile exports `node_modules/.bin` on `PATH` for local `argsbarg` |
 | tsconfig | `"resolveJsonModule": true` |
-| CI | `just check`: `schemagen` → `git diff --exit-code src/schemas/generated/ src/schemas/outputSchemas.ts` → typecheck |
+| CI | `just check`: `schemagen` → typecheck (no git diff on generated files) |
+| Cleanup | Schemagen removes orphan `__generated__/` dirs and stale JSON when roots or kinds are removed |
 | 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/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
+### Declaring a schema root
 
-### Marking 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.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.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.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.ts — custom HTTP/MCP body (pdf-gen)
+export interface RenderInvoiceToolInput {
+  format: "pdf" | "html";
+  invoice: InvoiceData;
+}
 
-### Stable naming (outfile + bridge export)
+export type inputType = RenderInvoiceToolInput;
+export type outputType = RenderInvoiceWrittenOutput;
+```
+
+| Export | Role |
+| --- | --- |
+| `export type configType = AppConfig` | `program.appConfig.jsonSchema` (one per repo, typically `src/config/schema.ts`) |
+| `export type outputType = …` | `leaf.outputSchema` |
+| `export type inputType = …` | `leaf.inputSchema` (only when the tool body is not flat CLI flags) |
 
-Discovery maps each root type name to a generated filename and `outputSchemas.ts` constant. Suffix conventions (implemented in `outfileForType` / `schemaExportName`):
+**Domain helpers** stay in `types.ts` (or `core/types.ts`). Discovery scans only `schema.ts`. Re-export-only files (`export type outputType = HeadlessOpResult` pointing at another module) are **not** generation roots — generate once from the canonical definition file.
 
-| 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` |
+Commands without structured JSON omit `schema.ts`. Shared shapes (e.g. `HeadlessOpResult`) live in one canonical `schema.ts`; other commands import `{ outputSchema }` from that module’s `__generated__/index.ts`.
 
-Prefer these suffixes for new roots so filenames and import constants stay predictable across repos.
+When you do **not** set `inputSchema`, argsbarg builds tool input from CLI `options` + `positionals`.
 
-### Generated bridge
+### Generated artifacts
 
-`scripts/generate-output-schemas.ts` rewrites `src/schemas/outputSchemas.ts` on every run:
+Schemagen writes under `__generated__/` beside each `schema.ts`:
+
+| Kind | Generated file | Exported const (from `__generated__/index.ts`) |
+| --- | --- | --- |
+| config | `configSchema.json` | `configSchema` |
+| output | `outputSchema.json` | `outputSchema` |
+| input | `inputSchema.json` | `inputSchema` |
+
+Wire on the leaf:
 
 ```typescript
-// Auto-generated by scripts/generate-output-schemas.ts — do not edit by hand.
+import { outputSchema } from "./__generated__/index.ts";
 
-import status from "./generated/status.json";
+export const statusCommand = {
+  outputSchema,
+  // …
+} satisfies CliLeaf;
+```
 
-/** JSON Schema for `myapp status --json`. */
-export const STATUS_JSON_OUTPUT_SCHEMA = status as Record<string, unknown>;
+Shared mutators:
+
+```typescript
+import { outputSchema } from "../../../ui/runHeadless/__generated__/index.ts";
 ```
 
-Wire the constant on each leaf that emits that shape (several commands may share one schema, e.g. mutating ops sharing `HeadlessOpResult`).
+App config:
+
+```typescript
+import { configSchema } from "./config/__generated__/index.ts";
+
+appConfig: { jsonSchema: configSchema, entries: { … } },
+```
 
 ## Schema-facing types
 
 **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.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** `__generated__/` — change types/JSDoc in `schema.ts`, run `just schemagen`.
 
 ### 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.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:
@@ -170,33 +203,32 @@ Handlers keep using runtime types; only discovered roots (and their type graph)
 
 ## Tests
 
-Per repo:
+In argsbarg: `src/cli-tool/schemagen/schemagen.test.ts` locks discovery and generation against `examples/full-example/`.
+
+Per consumer repo (optional):
 
-- **`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`.
+- **`src/generated-schemas.test.ts`** — smoke-test that key `outputSchema` objects have expected shape.
 
 ## 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.
-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).
+1. Add or edit schema roots in `src/**/schema.ts` with `outputType` / `inputType` / `configType` and per-field JSDoc.
+2. `just schemagen` — refresh `src/**/__generated__/`.
+3. Import `{ outputSchema }` / `{ inputSchema }` / `{ configSchema }` from the relevant `__generated__/index.ts`.
+4. `just docgen` / `myapp docs api --save` — refresh consumer docs.
+5. 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`.
 
-**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`.
+**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo — `schema.ts` roots, `__generated__/`, and `status` leaf with `outputSchema`.
 
 ## Out of scope
 
-- 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.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 |
-| --- | --- |
-| `Config schema` | `schemas/configSchemas.ts` + `schemas/generated/*-config.json` |
-| `JSON payload` | `schemas/outputSchemas.ts` + `schemas/generated/*.json` |
+| Export in `schema.ts` | Generated artifact | Import on leaf / program |
+| --- | --- | --- |
+| `export type configType = …` | `__generated__/configSchema.json` | `{ configSchema }` from `config/__generated__/index.ts` → `program.appConfig.jsonSchema` |
+| `export type outputType = …` | `__generated__/outputSchema.json` | `{ outputSchema }` from `__generated__/index.ts` → `leaf.outputSchema` |
+| `export type inputType = …` | `__generated__/inputSchema.json` | `{ inputSchema }` from `__generated__/index.ts` → `leaf.inputSchema` |
 
-Discovery walks `src/**/types.ts` only.
+Discovery walks `src/**/schema.ts` only. Domain helpers stay in sibling `types.ts`. `__generated__/` is gitignored — run `argsbarg schemagen` (via `just schemagen` or `just setup`).
 
 ## Consumer docs
 

package/examples/full-example/bun.lock

@@ -10,7 +10,6 @@
       "devDependencies": {
         "@biomejs/biome": "^2.5.0",
         "@types/bun": "^1.3.12",
-        "ts-json-schema-generator": "^2.3.0",
         "typescript": "^5.9.3",
       },
     },
@@ -36,40 +35,12 @@
 
     "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
 
-    "@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
-
     "@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
 
     "argsbarg": ["argsbarg@file:../..", { "devDependencies": { "@biomejs/biome": "^2.5.0", "@types/bun": "^1.3.12", "typescript": "^5.9.3" }, "bin": { "argsbarg": "src/index.ts" } }],
 
-    "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
-
-    "brace-expansion": ["brace-expansion@5.0.6", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g=="],
-
     "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
 
-    "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
-
-    "glob": ["glob@13.0.6", "", { "dependencies": { "minimatch": "^10.2.2", "minipass": "^7.1.3", "path-scurry": "^2.0.2" } }, "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw=="],
-
-    "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
-
-    "lru-cache": ["lru-cache@11.5.1", "", {}, "sha512-RPimw/7aMdv2oqRrxKwvZXcPfwBrn/JZ2xYcY9Hus/6LaS3VOAKVWKWgNLCFSiOm1ESXinjsDlidVU7JlnCN2A=="],
-
-    "minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg=="],
-
-    "minipass": ["minipass@7.1.3", "", {}, "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A=="],
-
-    "normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
-
-    "path-scurry": ["path-scurry@2.0.2", "", { "dependencies": { "lru-cache": "^11.0.0", "minipass": "^7.1.2" } }, "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg=="],
-
-    "safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
-
-    "ts-json-schema-generator": ["ts-json-schema-generator@2.9.0", "", { "dependencies": { "@types/json-schema": "^7.0.15", "commander": "^14.0.3", "glob": "^13.0.6", "json5": "^2.2.3", "normalize-path": "^3.0.0", "safe-stable-stringify": "^2.5.0", "tslib": "^2.8.1", "typescript": "^5.9.3" }, "bin": { "ts-json-schema-generator": "bin/ts-json-schema-generator.js" } }, "sha512-NR5ZE108uiPtBHBJNGnhwoUaUx5vWTDJzDFG9YlRoqxPU76n+5FClRh92dcGgysbe1smRmYalM9Saj97GW1J4Q=="],
-
-    "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
-
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],

package/examples/full-example/justfile

@@ -1,5 +1,7 @@
 set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
 
+export PATH := justfile_directory() + "/node_modules/.bin:" + env_var("PATH")
+
 cli_key := `bun scripts/print-identity.ts key`
 tap_org := `bun scripts/print-identity.ts tapOrg`
 tap_repo := `bun scripts/print-identity.ts tapRepo`
@@ -19,9 +21,8 @@ build:
     bun build ./src/index.ts --compile --outfile=dist/{{cli_key}}
     @rm -f .*.bun-build
 
-# Run schemagen, git diff check, typecheck, and format
+# Run schemagen, typecheck, and format
 check: schemagen format typecheck
-    git diff --exit-code schemas/
 
 # Run the CLI from source with optional args; restarts on file changes
 dev *ARGS:
@@ -84,11 +85,13 @@ run *ARGS:
 
 # Generate JSON Schema artifacts from TypeScript types
 schemagen:
-    bun run schemagen
+    argsbarg schemagen
 
 # Install bun/npm dependencies
+# Install bun/npm dependencies and generate schemas
 setup:
     bun install
+    just schemagen
 
 # Run unit tests (after check)
 test: check

package/examples/full-example/package.json

@@ -9,7 +9,6 @@
   },
   "scripts": {
     "biome": "biome",
-    "schemagen": "bun run scripts/schemagen.ts",
     "start": "bun run src/index.ts"
   },
   "dependencies": {
@@ -18,7 +17,6 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
     "@types/bun": "^1.3.12",
-    "ts-json-schema-generator": "^2.3.0",
     "typescript": "^5.9.3"
   }
 }

package/examples/full-example/src/commands/status/__generated__/index.ts

@@ -0,0 +1,5 @@
+// Auto-generated by argsbarg schemagen — do not edit by hand.
+
+import outputSchemaJson from "./outputSchema.json";
+
+export const outputSchema = outputSchemaJson as Record<string, unknown>;

package/examples/full-example/{schemas/generated/status.json → src/commands/status/__generated__/outputSchema.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/src/commands/status/command.ts

@@ -3,7 +3,7 @@ Status leaf — demonstrates outputSchema and ctx.appConfig.
 */
 
 import { type CliLeaf, CliOptionKind } from "argsbarg";
-import { STATUS_JSON_OUTPUT_SCHEMA } from "../../../schemas/outputSchemas.ts";
+import { outputSchema } from "./__generated__/index.ts";
 import type { StatusJsonOutput } from "./types.ts";
 
 export const statusCommand = {
@@ -16,7 +16,7 @@ export const statusCommand = {
       kind: CliOptionKind.Presence,
     },
   ],
-  outputSchema: STATUS_JSON_OUTPUT_SCHEMA,
+  outputSchema,
   handler: (ctx) => {
     const out: StatusJsonOutput = {
       defaultRegion: ctx.appConfig.get("defaultRegion") as string | undefined,