argsbarg 3.6.2 → 3.6.4

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.4] - 2026-06-23
+
+### Added
+
+- **`docs/output-schema.md`** — recommended TypeScript → JSON Schema codegen pipeline for leaf `outputSchema` (manifest, bridge, JSDoc, narrowing, CI).
+
+### Changed
+
+- **`docs/README.md`**, **`cli-program.md`**, **`bundled-docs.md`**, Cursor rule template — cross-links to output-schema guide.
+
+## [3.6.3] - 2026-06-23
+
+### Added
+
+- **`docs/README.md`** — documentation map (framework vs consumer docgen).
+- **`docs/developing.md`** — maintainer workflow (`consumer-dev`, `consumers-sync`, npm `files`).
+- **`examples/formats.ts`** — `CliValueFormat`, `default`, and `readLeafInputs()` demo.
+
+### Changed
+
+- **`cli-program.md`** — `CliLeafInputs` / `readLeafInputs()` semantics, upgrading to 3.6+, read-once-resolve-once cross-links.
+- **`bundled-docs.md`** — framework docs vs consumer docgen.
+- **`docs/mcp.md`** — varargs JSON array only (fixes stale comma-string guidance).
+- **`consumers-dev` / `consumers-sync`** — refresh consumer `.cursor/rules/cli-program.mdc` from template via `scripts/merge-cli-program-rule.ts`.
+
 ## [3.6.2] - 2026-06-23
 
 ### Added
@@ -399,7 +424,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/v3.6.2...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.4...HEAD
+[3.6.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.4
+[3.6.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.3
 [3.6.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.2
 [3.6.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.1
 [3.6.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.0

package/README.md

@@ -155,7 +155,7 @@ mkdir -p .cursor/rules
 cp node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc .cursor/rules/cli-program.mdc
 ```
 
-Add app-specific conventions in a second rule if needed. Full guide: **[docs/cli-program.md](docs/cli-program.md)**.
+Add app-specific conventions in a second rule if needed. Copy the rule from the template, then add a `**<your-app> conventions:**` block at the bottom (see **Cursor rule** in [docs/cli-program.md](docs/cli-program.md)). Documentation map: **[docs/README.md](docs/README.md)**.
 
 
 ## How it works
@@ -214,6 +214,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()`. |
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -225,6 +226,8 @@ minimal.ts hello --name world
 eval "$(nested.ts completion zsh)"
 nested.ts stat owner lookup -u alice ./README.md
 nested.ts read ./README.md
+
+bun ./examples/formats.ts run --tags demo,docs --on 2026-06-22
 ```
 
 
@@ -238,7 +241,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.flag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.readLeafInputs`, `ctx.invocation`, …). |
+| `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. |
 | `cliRun(root, [argv])` | Validate, parse argv, dispatch, exit. |
 | `cliInvoke(root, argv)` | Parse and dispatch without exiting; returns captured stdout/stderr. |
 | `cliErrWithHelp(ctx, msg)` | Print error + scoped help on stderr, exit 1. |

package/docs/README.md

@@ -0,0 +1,33 @@
+# Argsbarg documentation
+
+Start here to pick the right guide.
+
+| If you are… | Read |
+| --- | --- |
+| **New to argsbarg** | [../README.md](../README.md) — install, minimal usage, public API |
+| **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 |
+| **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `install --mcp` |
+| **Shipping install / completions / skills** | [install.md](install.md) — `myapp install`, shell completions |
+| **Bundling `myapp docs` topics** | [bundled-docs.md](bundled-docs.md) — consumer docgen vs framework docs |
+| **Agent skills** | [ai-skills.md](ai-skills.md) — `install --skill`, `docs skill` |
+| **Maintaining the argsbarg repo** | [developing.md](developing.md) — release, consumers, npm `files` |
+| **Cursor / IDE agents in a consumer app** | Copy [templates/cursor/rules/cli-program.mdc](templates/cursor/rules/cli-program.mdc) to `.cursor/rules/` |
+
+## Framework docs vs consumer docgen
+
+| Source | What it is | Where it lives |
+| --- | --- | --- |
+| **Framework docs** | How argsbarg works; authoring conventions | This directory — shipped in `node_modules/argsbarg/docs/` after `bun add argsbarg` |
+| **Consumer docgen** | *Your* command tree, API, MCP guide for *your* app | `myapp docs api`, `docs schema`, `docs mcp` — written to `./docs/` with `--save` |
+| **Cursor rule** | Thin tripwire telling agents to read framework docs | `node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc` — copy into your repo and append app conventions |
+
+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.
+
+## Examples
+
+| Example | Shows |
+| --- | --- |
+| [../examples/minimal.ts](../examples/minimal.ts) | Presence + string flags, fallback routing |
+| [../examples/nested.ts](../examples/nested.ts) | Nested commands, varargs, MCP + `docs` |
+| [../examples/formats.ts](../examples/formats.ts) | `CliValueFormat`, `default`, `readLeafInputs()` |

package/docs/bundled-docs.md

@@ -2,6 +2,21 @@
 
 ArgsBarg can expose bundled markdown topics as the built-in `docs` command group. Opt in on the program root with `docs: { enabled: true, topics: { ... } }`.
 
+## Framework docs vs your app's docgen
+
+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 [Cursor rule](templates/cursor/rules/cli-program.mdc) or `AGENTS.md` |
+| **Your CLI (docgen)** | Your command tree, options, MCP tool list, install notes | `myapp docs api`, `docs schema`, `docs mcp` — save with `--save` to `./docs/` |
+
+`docs api` and `docs schema` embed each leaf’s `outputSchema` when set — see [output-schema.md](output-schema.md) for how to generate and wire schemas.
+
+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.
+
+See [docs/README.md](README.md) for the full documentation map.
+
 ## Quick start
 
 ```typescript

package/docs/cli-program.md

@@ -2,6 +2,8 @@
 
 ArgsBarg turns your schema into help, shell completions, MCP tools, and agent skills. **The same `description` fields you write for humans are the agent contract** for basic apps.
 
+**Documentation map:** [docs/README.md](README.md) — which guide to read for MCP, install, consumer docgen, and Cursor setup.
+
 ## Minimal app (MCP is free)
 
 ```typescript
@@ -132,6 +134,8 @@ On **leaf commands**, set `outputSchema` to a JSON Schema describing stdout when
 
 Exported in `docs schema`, `docs api`, skill `reference.md`, and MCP `tools/list`. Not validated at runtime yet. Pair with `notes` for prose examples; do not duplicate the full schema in `notes`.
 
+For a **outputSchema codegen guidelines** (TypeScript types → JSON Schema → `outputSchema` constants), see [output-schema.md](output-schema.md).
+
 Do **not** use `mcpTool.description` to paper over missing `--yes`, non-standard flag names, or handlers that only work interactively — fix those instead.
 
 If help text and MCP behavior match after your fixes, **omit `mcpTool` entirely**.
@@ -193,6 +197,26 @@ const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs()
 // duration → number (ms); comma-list → string[]; presence → boolean; number → number
 ```
 
+**`CliLeafInputs`** — return type of `readLeafInputs()` (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` |
+| --- | --- |
+| Presence | `boolean` |
+| Number | `number` or `undefined` if omitted |
+| String (plain) | `string` or `undefined` |
+| `format: duration` | `number` (milliseconds) |
+| `format: comma-list` | `string[]` |
+| `format: date` | `string` (`YYYY-MM-DD`) |
+| `format: date-time` | `string` (normalized UTC ISO) |
+| Single positional | `string` or `undefined` |
+| Varargs positional | `string[]` or `undefined` |
+
+Omitted options appear as `undefined` (not absent keys). Options with `default` are filled in post-parse before handlers run, so `readLeafInputs()` and `durationOpt` see defaults. **`ctx.opts` always holds raw strings** — use typed accessors or `readLeafInputs()` for coerced values.
+
+`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`.
+
+See [examples/formats.ts](../examples/formats.ts) for a runnable demo.
+
 Cross-field rules (e.g. `--match-remote` requires `--branch`) stay in consumer `resolve*` layers — argsbarg does not validate those.
 
 ## Read flags once, resolve once
@@ -248,6 +272,30 @@ handler: async (ctx) => {
 
 **JSON-only CLIs** — a single `readCommandOptions(ctx)` wrapping `readLeafInputs()` per shared option set is usually enough; full `resolve*` layering is optional.
 
+## Upgrading to 3.6+
+
+### MCP varargs (breaking)
+
+Varargs positionals (`argMax: 0`) must be a **JSON array** in `tools/call` — comma-separated strings are no longer accepted.
+
+```json
+// before (removed)
+{ "uids": "a,b,c" }
+
+// after
+{ "uids": ["a", "b", "c"] }
+```
+
+CLI argv is unchanged: space-separated words. Use `format: comma-list` on an **option** when a single flag should accept `a,b` or `["a","b"]` over MCP.
+
+### 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.
+
+### Handler layering (optional)
+
+Ink + headless + MCP apps benefit from `read*Flags(ctx)` + `resolve*Input(flags)` — see above.
+
 ## Headless-capable handlers
 
 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:
@@ -342,14 +390,28 @@ mkdir -p .cursor/rules
 cp node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc .cursor/rules/cli-program.mdc
 ```
 
-The template is ~25 lines: when to read which doc, plus hard rules agents often get wrong. It does **not** duplicate this guide — re-copy after upgrading argsbarg when the template changes.
+The template is ~25 lines: when to read which doc, plus hard rules agents often get wrong. It does **not** duplicate this guide.
+
+2. **Add an app-specific block at the bottom** (recommended). Replace the template placeholder with a heading like `**myapp conventions:**` and short bullets — shared flag modules, `read*Flags` / `resolve*` paths, Ink vs JSON-only, etc. Example:
+
+```markdown
+**sqsp-qa conventions:**
+
+- Shared mutator flags: `readQaMutatingFlags(ctx)` in `src/cli/shared.ts`.
+- Per command: `read*Flags` + `resolve*Input` in `commands/<name>/resolve.ts`.
+```
+
+If you maintain argsbarg from a sibling checkout, `just consumer-dev` / `just consumers-sync` refresh the shared template and **keep** this footer (matched by the `**… conventions:**` heading). Commit `.cursor/rules/cli-program.mdc` in your repo.
 
-2. **Optional:** a second rule for app-only conventions (e.g. `src/cli/shared.ts` flag names, JSON-only handlers, Ink patterns).
+3. **Optional:** a separate rule (e.g. `.cursor/argsbarg.mdc` or `AGENTS.md`) for broader package API notes.
 
-3. **Optional:** `.cursor/argsbarg.mdc` or `AGENTS.md` pointing at `node_modules/argsbarg/docs/cli-program.md` for broader context.
+**Not this file:** `myapp install --skill` writes the **app** skill (`SKILL.md` under `~/.cursor/skills/`) from your command schema — how to *invoke* the CLI. The rule above is for *authoring* argsbarg schema.
 
 ## See also
 
+- [Documentation map](README.md) — which doc to read when
+- [Output schemas](output-schema.md) — codegen pipeline for leaf `outputSchema`
+- [Developing argsbarg](developing.md) — release, consumer sync, npm `files`
 - [MCP server](mcp.md) — tools, schema resource, env bootstrapping
 - [Agent skills](ai-skills.md) — `install --skill`
-- [Bundled docs](bundled-docs.md) — `docs` topics and `docs mcp`
+- [Bundled docs](bundled-docs.md) — `docs` topics, consumer docgen vs framework docs

package/docs/developing.md

@@ -0,0 +1,54 @@
+# Developing argsbarg
+
+Notes for maintainers of this repository. Also shipped under `node_modules/argsbarg/docs/` for fork maintainers.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) ≥ 1.3
+- [just](https://github.com/casey/just) — `just` lists recipes
+- `gh` and `npm` logged in for release
+
+## Day-to-day
+
+```bash
+just check    # typecheck + format
+just test     # check + unit tests
+just typegen  # regenerate index.d.ts
+```
+
+## Release
+
+```bash
+just release patch   # or minor | major
+```
+
+The release script bumps `package.json`, promotes `[Unreleased]` in `CHANGELOG.md`, commits, tags, pushes, creates a GitHub release, and publishes to npm. Run `just test` first (the `just release` recipe does).
+
+Update `CHANGELOG.md` under `[Unreleased]` before releasing.
+
+## Local consumer apps
+
+Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile` if needed):
+
+| Recipe | When | Effect |
+| --- | --- | --- |
+| `just consumer-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` from template (keeps app-specific suffix) |
+| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **argsbarg Cursor rule**, `just build`, `just docgen`, `just install` (consumer app binary, completions, and **app** skill) |
+
+`consumers-sync` reads the version from **this repo’s** `package.json` — not npm. Run it **after** `just release` so consumers pin a version that exists on the registry.
+
+**Argsbarg authoring rule** — `scripts/merge-cli-program-rule.ts` copies `docs/templates/cursor/rules/cli-program.mdc` into each consumer’s `.cursor/rules/cli-program.mdc`, preserving any existing `**… conventions:**` footer block.
+
+**Recommended in each consumer:** replace the template placeholder with `**<app> conventions:**` bullets (paths to `read*Flags`, shared flags, Ink vs JSON-only). Commit that file; merges refresh the shared top, not your footer.
+
+**Consumer app skill** — `just install` in each consumer (part of `consumers-sync`) runs `myapp install --skill`, which updates `~/.cursor/skills/<app>/` from that app’s schema — not the argsbarg framework rule.
+
+## npm package contents
+
+`npm publish` does **not** honor `.gitignore`. Only paths listed in `package.json` `files` are included in the tarball (plus always-excluded defaults like `node_modules`).
+
+When adding docs or examples intended for consumers, ensure they live under whitelisted paths (`docs/`, `examples/`, `src/`, etc.).
+
+## Docs
+
+See [README.md](README.md) for the documentation map. Framework authoring guide: [cli-program.md](cli-program.md).

package/docs/mcp.md

@@ -208,7 +208,7 @@ Set **`outputSchema` on the leaf** (not under `mcpTool`) — see [cli-program.md
 Each tool’s `inputSchema` is a JSON Schema object built from your CLI definition:
 
 - **Options** — parent-scoped flags are included (e.g. `stat`’s `--json` appears on `stat_owner_lookup`). Presence options are `boolean`; string, number, and **enum** options match their `CliOptionKind` (`Enum` uses JSON Schema `enum`). Required options are listed in `required`.
-- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`. For varargs, agents may also pass a comma-separated string (`"a,b"`) or a single string (`"a"`) — both are coerced to separate argv tokens at dispatch time.
+- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`. **Varargs must be a JSON array** — comma-separated strings are not accepted (use `format: comma-list` on an option when a single flag should accept `"a,b"` or `["a","b"]`).
 
 Arguments are a **flat JSON object** keyed by option and positional names (same names as in your schema, including hyphenated option names like `"user-name"`).
 

package/docs/output-schema.md

@@ -0,0 +1,181 @@
+# Output schemas (`outputSchema`)
+
+How to describe JSON stdout on leaf commands — and a **recommended codegen pipeline** used in production argsbarg 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_OUTPUT_SCHEMA } from "../schemas/outputSchemas.js";
+
+export const status = {
+  key: "status",
+  description: "Show environment status.",
+  outputSchema: STATUS_OUTPUT_SCHEMA,
+  handler: async (ctx) => { /* writes JSON to stdout */ },
+} satisfies CliLeaf;
+```
+
+| Where argsbarg uses it | Purpose |
+| --- | --- |
+| `myapp docs schema` | Full command tree JSON export |
+| `myapp docs api` | Markdown per-command **Output** section |
+| `myapp docs skill` | `reference.md` for agent skills |
+| MCP `tools/list` | Optional `outputSchema` on each tool |
+
+**Not validated at runtime** — argsbarg does not parse or reject handler stdout against the schema today. The schema is documentation and MCP metadata.
+
+**Set on the leaf only** — not under `mcpTool` (legacy `mcpTool.outputSchema` still resolves but is deprecated).
+
+**Draft version** — argsbarg accepts any JSON Schema object (`type`, `properties`, `definitions`, etc.). Generators may emit draft-07 or draft 2020-12; docgen embeds the object as-is.
+
+See [cli-program.md — Structured stdout](cli-program.md#structured-stdout) for when to use `outputSchema` vs `notes`, and [mcp.md](mcp.md) for how MCP returns parsed JSON as `structuredContent`.
+
+## Hand-written vs generated
+
+| Approach | When |
+| --- | --- |
+| **Inline object** on the leaf | One-off commands, spikes, very small shapes |
+| **Codegen from TypeScript** | Multiple commands share a shape, nested objects, or you want rich `description` fields in `docs api` / skills |
+
+Production CLIs with several JSON commands tend to use **codegen** so types, handlers, and schemas stay aligned.
+
+## Recommended pipeline (copy per repo)
+
+No shared npm package — each app copies the same **contract**. Reference implementations: **sqsp-qa-tools**, **idp-trees**, **sqsp-i18n-tools** (see each repo’s `docs/architecture.md` for manifest tables).
+
+```mermaid
+flowchart LR
+  subgraph types [Schema-facing TS + JSDoc]
+    Roots["Manifest root interfaces"]
+    Narrow["Narrowed types where needed"]
+  end
+  subgraph gen [just schemagen]
+    Script["scripts/generate-output-schemas.ts"]
+    Gen["ts-json-schema-generator"]
+  end
+  subgraph artifacts [Committed]
+    Json["src/schemas/generated/*.json"]
+  end
+  subgraph runtime [Runtime]
+    Bridge["src/schemas/outputSchemas.ts"]
+    Leaves["leaf outputSchema"]
+    Docgen["just docgen"]
+  end
+  Roots --> Script
+  Narrow --> Script
+  Script --> Gen --> Json --> Bridge --> Leaves --> Docgen
+```
+
+| Piece | Convention |
+| --- | --- |
+| Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (e.g. `createGenerator` with `jsDoc: "extended"`) |
+| Config | `tsconfig: "tsconfig.json"`, `topRef: false`, `skipTypeCheck: false` |
+| Manifest | Explicit `{ typeName, path, outfile }[]` — only **roots** become schema files |
+| Artifacts | Commit `src/schemas/generated/*.json` |
+| Bridge | `src/schemas/outputSchemas.ts` imports JSON → `*_OUTPUT_SCHEMA` constants |
+| tsconfig | `"resolveJsonModule": true` |
+| CI | `just check`: run `schemagen` → `git diff --exit-code src/schemas/generated/` → typecheck |
+| Docgen | `docgen` depends on `schemagen` so saved `./docs/api.md` and `./docs/schema.json` are fresh |
+
+Type files can live anywhere the manifest points (`commands/<cmd>/types.ts`, `resolve.ts`, `core/types.ts`, `ui/runHeadless.ts`).
+
+### Example manifest + generator
+
+```typescript
+const MANIFEST = [
+  { typeName: "StatusJsonOutput", path: "src/commands/status/resolve.ts", outfile: "status.json" },
+  { typeName: "HeadlessOpResult", path: "src/ui/runHeadless.ts", outfile: "headless-op-result.json" },
+];
+
+for (const entry of MANIFEST) {
+  const generator = createGenerator({
+    path: path.join(ROOT, entry.path),
+    type: entry.typeName,
+    tsconfig: path.join(ROOT, "tsconfig.json"),
+    topRef: false,
+    skipTypeCheck: false,
+    jsDoc: "extended",
+  });
+  fs.writeFileSync(
+    path.join(OUT_DIR, entry.outfile),
+    `${JSON.stringify(generator.createSchema(entry.typeName), null, 2)}\n`,
+  );
+}
+```
+
+### Example bridge
+
+```typescript
+import statusJson from "./generated/status.json";
+
+export const STATUS_JSON_OUTPUT_SCHEMA = statusJson as Record<string, unknown>;
+```
+
+Wire the constant on each leaf that emits that shape (several commands may share one schema, e.g. mutating ops sharing `HeadlessOpResult`).
+
+## Schema-facing types
+
+**Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs api`.
+
+1. **Manifest roots** — `export interface` (preferred) or documented type alias; top-level JSDoc names which command(s) emit it.
+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/` — change types/JSDoc, run `just schemagen`, commit JSON.
+
+### Narrowing when runtime ≠ stdout
+
+When a shared runtime type is **wider** than one command’s JSON, add a **schema-facing** type:
+
+```typescript
+/** Runtime union across commands. */
+export type ResultSource = TranslationReadinessSource | { kind: "uids"; uids: string[] };
+
+/** JSON for `pr` and `file` only — no `uids` variant. */
+export interface TranslationReadinessResult {
+  source: TranslationReadinessSource;
+  evaluatedAt: string;
+  // ...
+}
+```
+
+Patterns:
+
+- **Shallow dashboard types** — separate interfaces from fat API types so generated schema stays readable.
+- **Assignability tests** — `expectTypeOf<RuntimeRow>().toMatchTypeOf<SchemaFacingRow>()` or equivalent so refactors cannot drift.
+
+Handlers keep using runtime types; only the manifest root (and its graph) feed codegen.
+
+## Tests
+
+After wiring, add `src/schemas/outputSchemas.test.ts` (or similar):
+
+- Each exported schema has `type: "object"` (or expected root).
+- Key `properties` / `definitions` have non-empty `description` from JSDoc.
+- Spot-check enums, required fields, and `@format date-time` where it matters.
+
+## Contributor workflow
+
+1. Edit schema-facing interfaces and JSDoc.
+2. `just schemagen` — refresh `src/schemas/generated/`.
+3. Commit generated JSON with the type changes.
+4. `just docgen` / `myapp docs api --save` — refresh consumer docs.
+5. Document app-specific manifest roots in **your** `docs/architecture.md` (not in argsbarg).
+
+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.
+
+## 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
+- Forcing identical file layout across repos — the **manifest** is authoritative
+
+## See also
+
+- [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 schema` docgen
+- [docs/README.md](README.md) — documentation map

package/docs/templates/cursor/rules/cli-program.mdc

@@ -8,8 +8,9 @@ When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
 
 1. **Read** `node_modules/argsbarg/docs/cli-program.md` (required — authoritative guide).
 2. MCP tools, varargs, `inputSchema` → also `node_modules/argsbarg/docs/mcp.md`.
-3. `install`, completions, skills → `node_modules/argsbarg/docs/install.md`.
-4. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
+3. JSON stdout / `outputSchema` guide and codegen → `node_modules/argsbarg/docs/output-schema.md`.
+4. `install`, completions, skills → `node_modules/argsbarg/docs/install.md`.
+5. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
 
 **Hard rules** (details and examples are in the docs above — do not contradict them):
 
@@ -20,5 +21,6 @@ When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
 - String options: `format` / `default` / `pattern` per `cli-program.md`; `readLeafInputs()` for multi-flag leaves.
 - Varargs (`argMax: 0`): CLI space-separated; MCP JSON array only — no comma-splitting positionals.
 - Multi-surface leaves (Ink + headless + MCP): one **`read*Flags(ctx)`** per command (or shared family helper + extensions); one **`resolve*Input(flags)`** for cross-field rules — handler reads ctx once, all paths share the struct.
+- JSON stdout: `outputSchema` on the leaf from generated constants — see `output-schema.md`; do not hand-edit `src/schemas/generated/`.
 
-**App-specific conventions:** add below or in a separate `.cursor/rules/` file (shared flags path, Ink vs JSON-only, etc.).
+**App-specific conventions:** replace this line with a `**<your-app> conventions:**` section (bullets only). Keep it at the bottom of this file — `just consumer-dev` / `just consumers-sync` in the argsbarg repo refresh the template above and preserve this block. Do not duplicate `cli-program.md` here; link paths and patterns only. For a second rule file (e.g. `.cursor/argsbarg.mdc`), that is fine too.

package/examples/formats.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env bun
+/*
+ * Value formats demo: duration, comma-list, date, default, and readLeafInputs().
+ * Run: bun ./examples/formats.ts run --tags alpha,beta --on 2026-06-22
+ * MCP: pass comma-list as string or array; varargs N/A on this leaf.
+ */
+
+import pkg from "../package.json" with { type: "json" };
+import { cliRun, CliFallbackMode, CliOptionKind, CliValueFormat, type CliProgram } from "../src/index.ts";
+
+const cli = {
+  key: "formats.ts",
+  version: pkg.version,
+  description: "Value formats and readLeafInputs demo.",
+  fallbackCommand: "run",
+  fallbackMode: CliFallbackMode.MissingOnly,
+  mcpServer: { enabled: true },
+  commands: [
+    {
+      key: "run",
+      description: "Print coerced option values from readLeafInputs().",
+      options: [
+        {
+          name: "timeout",
+          description: "Wait budget (default 30s).",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.Duration,
+          default: "30s",
+        },
+        {
+          name: "tags",
+          description: "Comma-separated labels.",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.CommaList,
+        },
+        {
+          name: "on",
+          description: "Calendar day (YYYY-MM-DD).",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.Date,
+        },
+        {
+          name: "verbose",
+          description: "Also print raw ctx.opts strings.",
+          kind: CliOptionKind.Presence,
+          shortName: "v",
+        },
+      ],
+      handler: (ctx) => {
+        const inputs = ctx.readLeafInputs();
+        const out = {
+          readLeafInputs: inputs,
+          durationMs: ctx.durationOpt("timeout"),
+          tags: ctx.commaListOpt("tags"),
+          on: ctx.dateOpt("on"),
+        };
+        if (ctx.hasFlag("verbose")) {
+          Object.assign(out, { rawOpts: ctx.opts });
+        }
+        process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+      },
+    },
+  ],
+} satisfies CliProgram;
+
+await cliRun(cli);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.6.2",
+  "version": "3.6.4",
   "type": "module",
   "engines": {
     "bun": ">=1.3"