argsbarg 3.6.3 → 4.0.0

package/docs/mcp.md

@@ -125,14 +125,13 @@ Any host that spawns a subprocess and wires stdin/stdout works the same way: the
 
 ## Configuration
 
-Set `mcpServer` on the **program root only** (the `CliProgram` passed to `cliRun`). Validation rejects `mcpServer` on nested nodes.
+Set `mcpServer` on the **program root only** (the `CliProgram` passed to `new Cli(program)`). Validation rejects `mcpServer` on nested nodes.
 
 | Field | Default | Purpose |
 | --- | --- | --- |
 | `enabled` | *(required)* | Must be `true` when `mcpServer` is set |
 | `schemaResourceUri` | `<sanitized root key>://schema` | URI for the built-in schema resource |
 | `shellEnv` | off | Capture login-shell `env` at startup (`true` uses `$SHELL`, or pass a shell path) |
-| `envFile` | off | Load a `.env` file after `shellEnv` (`~` supported); warns on stderr if missing |
 | `resources` | `[]` | Custom `CliMcpResource` entries (additive; schema resource is always included) |
 
 MCP `serverInfo.name` and the default schema URI use the sanitized program `key` (non-alphanumeric characters become `_`). Program `version` comes from `CliProgram.version` (also used by the `version` built-in).
@@ -143,7 +142,6 @@ Example with optional fields:
 mcpServer: {
   enabled: true,
   shellEnv: true,
-  envFile: "~/.config/myapp/mcp.env",
 }
 ```
 
@@ -163,7 +161,7 @@ Tool names are derived from the command path, with each segment sanitized (non-a
 
 ### Tool descriptions
 
-Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash. Leaf **`notes`** are appended after a blank line (with `{argsbarg:program}` resolved). Tool arguments are defined in `inputSchema` (options and positionals with their descriptions). `mcpTool.requiresEnv` is appended as `[requires env: …]` on auto-generated descriptions.
+Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash. Leaf **`notes`** are appended after a blank line (with `{argsbarg:program}` resolved). Tool arguments are defined in `inputSchema` (options and positionals with their descriptions).
 
 | CLI path | MCP `description` (example) |
 | --- | --- |
@@ -194,14 +192,12 @@ Omitted or `enabled: true` exposes the command (default). `mcpTool` is only vali
 mcpTool: {
   enabled: true,
   description: "Custom tools/list text (overrides auto-generated path + help).",
-  requiresEnv: ["API_TOKEN", "DATABASE_URL"],
 }
 ```
 
 Set **`outputSchema` on the leaf** (not under `mcpTool`) — see [cli-program.md — Structured stdout](cli-program.md#structured-stdout).
 
-- **`description`** — when set, replaces the auto-generated `path — help` description entirely (no automatic `requiresEnv` suffix; mention vars in your text if needed).
-- **`requiresEnv`** — on auto-generated descriptions, appended as `[requires env: …]`. Enforced at `tools/call` time before the handler runs. Empty or unset env values count as missing.
+- **`description`** — when set, replaces the auto-generated `path — help` description entirely.
 
 ### Tool arguments
 
@@ -269,7 +265,7 @@ URIs must be unique and must not equal `schemaResourceUri`. `load()` runs synchr
 
 ## Invocation context
 
-Handlers receive `ctx.invocation`: `"cli"` for normal `cliRun` dispatch, `"mcp"` for MCP `tools/call`.
+Handlers receive `ctx.invocation`: `"cli"` for normal `Cli.run()` dispatch, `"mcp"` for MCP `tools/call`.
 
 MCP is always non-interactive. Commands that can mount Ink or prompts should implement a **headless fast path** (same path as non-TTY CLI with `--yes` / `--json`) — see [cli-program.md — Headless-capable handlers](cli-program.md#headless-capable-handlers).
 
@@ -287,9 +283,9 @@ handler: async (ctx) => {
 
 `Bun.spawn({ stdout: "inherit" })` under MCP corrupts the wire. Prefer `"pipe"` and let argsbarg return captured handler stdout in the tool result.
 
-### `cliInvoke` (public API)
+### `Cli.invoke` (public API)
 
-`cliInvoke(root, argv)` runs a leaf handler without exiting the process — useful for tests and headless integrations. Returns `{ kind, exitCode, stdout, stderr }`. MCP tool dispatch uses this internally.
+`new Cli(root).invoke(argv)` runs a leaf handler without exiting the process — useful for tests and headless integrations. Returns `{ kind, exitCode, stdout, stderr }`. MCP tool dispatch uses this internally.
 
 **Note:** Tool output is buffered until the handler completes. Live streaming (e.g. `tail -f`) is not supported yet; see [Design notes](#design-notes).
 
@@ -297,12 +293,12 @@ handler: async (ctx) => {
 
 MCP hosts (e.g. Cursor) often spawn your server with a minimal environment — missing `PATH` entries for Homebrew, nvm, rbenv, etc.
 
-At server start (`cliMcpServeStdio`), before the NDJSON loop:
+At server start (`Cli.serveMcp()`), before the NDJSON loop:
 
 | Order | Source | Behavior |
 | --- | --- | --- |
 | 1 | `shellEnv` | Spawns `$SHELL -l -c env`; merges into `process.env` |
-| 2 | `envFile` | Loads `.env`; **overwrites** keys from step 1 |
+| 2 | App config file | Loads `program.appConfig` keys from flat JSON when unset in host env |
 
 **`shellEnv` merge rules:**
 
@@ -310,18 +306,26 @@ At server start (`cliMcpServeStdio`), before the NDJSON loop:
 - **Other vars** — set only when absent from the host environment (host wins).
 - On failure — one-line warning on **stderr**; server continues.
 
-**`envFile`:**
+**App config (`program.appConfig`):**
 
-- Supports `~` expansion.
-- Missing file — warning on stderr, server continues.
-- Keys from the file **always overwrite** `process.env`.
+- Default path: `$XDG_CONFIG_HOME/<sanitized-key>/config` (Linux/macOS) or `%APPDATA%/<key>/config` (Windows). Override with `config.path`.
+- JSON shape: flat object keyed by schema names — `{ "apiToken": "…" }`. Unknown keys rejected on load.
+- Loaded at MCP startup; host `process.env` wins for mapped env vars already set.
+- Missing required config does **not** exit the MCP server — enforced at `tools/call` with a helpful error.
+- Configure interactively: `myapp install --configure` (see [install.md](install.md)).
+- Built-in `config get` / `config set` when `program.appConfig.commands` is enabled (default). Hosts inject `user_config` → env at spawn; they never write the argsbarg config file.
 
 Example:
 
 ```typescript
+appConfig: {
+  entries: {
+    apiToken: { description: "Create at https://example.com/settings/tokens", env: "API_TOKEN", sensitive: true },
+  },
+},
 mcpServer: {
+  enabled: true,
   shellEnv: true,
-  envFile: "~/.config/myapp/mcp.env",
 },
 ```
 
@@ -355,15 +359,35 @@ You should get one JSON line on stdout with `result.capabilities` and `result.se
 
 ## MCP Bundle (`mcp bundle`)
 
-When `mcpServer.enabled` is true, **`mcp bundle`** packs a Claude Desktop **`.mcpb`** bundle:
+When `mcpServer.enabled` is true, **`mcp bundle`** writes two distribution artifacts:
 
 ```bash
 just build
 ./dist/myapp mcp bundle
 # → dist/myapp.mcpb
+# → dist/claude-plugin/myapp.zip
+```
+
+Expects the compiled binary at **`dist/<program.key>`**.
+
+| Output | Purpose |
+| --- | --- |
+| **`dist/<key>.mcpb`** | Claude Desktop MCP Bundle (`.mcpb` zip) |
+| **`dist/claude-plugin/<name>.zip`** | Claude Code plugin zip (`<name>` is kebab-case from `program.key`) |
+
+Manifest metadata is generated from your schema (`mcpServerId`, tools, `program.appConfig` user config for env-mapped entries). Optional pack-time fields live under **`mcpServer.bundle`** (`author`, `icon`, `longDescription`).
+
+**Claude Code plugin zip layout** (paths at archive root):
+
+```
+.claude-plugin/plugin.json
+.mcp.json
+bin/myapp
+skills/<dirName>/SKILL.md
+skills/<dirName>/reference.md
 ```
 
-Expects the compiled binary at **`dist/<program.key>`** and writes **`dist/<program.key>.mcpb`**. Manifest metadata is generated from your schema (`mcpServerId`, tools, `requiresEnv`). Optional pack-time fields live under **`mcpServer.bundle`** (`author`, `icon`, `longDescription`).
+Load locally with `claude --plugin-dir ./dist/claude-plugin/myapp.zip`.
 
 Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `install --mcp` and MCP hosts). Use **`install --mcp`** for Cursor, Claude Code, Claude Desktop, and OpenCode JSON config.
 

package/docs/output-schema.md

@@ -0,0 +1,203 @@
+# 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_JSON_OUTPUT_SCHEMA } from "../schemas/outputSchemas.js";
+
+export const status = {
+  key: "status",
+  description: "Show environment status.",
+  outputSchema: STATUS_JSON_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 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"]
+  end
+  subgraph gen [just schemagen]
+    Discover["scripts/schemagen/discover-schema-roots.ts"]
+    Script["scripts/generate-output-schemas.ts"]
+    Gen["ts-json-schema-generator"]
+  end
+  subgraph artifacts [Committed]
+    Json["src/schemas/generated/*.json"]
+    Bridge["src/schemas/outputSchemas.ts"]
+  end
+  subgraph runtime [Runtime]
+    Leaves["leaf outputSchema"]
+    Docgen["just docgen"]
+  end
+  TypesTs --> Marker --> Discover
+  Narrow --> Discover
+  Discover --> Script --> Gen --> Json
+  Script --> Bridge --> 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` |
+| tsconfig | `"resolveJsonModule": true` |
+| CI | `just check`: `schemagen` → `git diff --exit-code src/schemas/generated/ src/schemas/outputSchemas.ts` → typecheck |
+| Docgen | `docgen` depends on `schemagen` so saved `./docs/api.md` and `./docs/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
+
+### 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:
+
+```typescript
+/** JSON payload for `myapp status --json`. */
+export interface StatusJsonOutput {
+  items: StatusJsonItem[];
+}
+
+/** JSON payload written to stdout after a headless mutating command. */
+export interface HeadlessOpResult {
+  command: string;
+  exitCode: number;
+  tasks: HeadlessTaskResult[];
+}
+```
+
+`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.
+
+### 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`):
+
+| 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` |
+
+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:
+
+```typescript
+// Auto-generated by scripts/generate-output-schemas.ts — do not edit by hand.
+
+import status from "./generated/status.json";
+
+/** JSON Schema for `myapp status --json`. */
+export const STATUS_JSON_OUTPUT_SCHEMA = status 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. **Schema roots** — `export interface` in a `types.ts` file, with **`JSON payload`** in the interface JSDoc naming 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/` or `src/schemas/outputSchemas.ts` — 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`):
+
+```typescript
+/** Runtime union across commands. */
+export type ResultSource = TranslationReadinessSource | { kind: "uids"; uids: string[] };
+
+/** JSON payload for `myapp pr` and `myapp file`. */
+export interface TranslationReadinessResult {
+  source: TranslationReadinessSource;
+  evaluatedAt: string;
+  // ...
+}
+```
+
+Patterns:
+
+- **Shallow dashboard types** — separate interfaces from fat API types so generated schema stays readable.
+- **Assignability tests** — ensure runtime rows satisfy schema-facing types so refactors cannot drift.
+
+Handlers keep using runtime types; only discovered roots (and their type graph) feed codegen.
+
+## Tests
+
+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`.
+
+## 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).
+
+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.
+
+**Reference implementation:** [`examples/consumer-app/`](../examples/consumer-app/) in this repo (shipped in npm as `node_modules/argsbarg/examples/consumer-app/`) — discovery script, bridges, 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
+
+- [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,17 +8,24 @@ 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. App config / `program.appConfig` guide and codegen → `node_modules/argsbarg/docs/config-schema.md`.
+5. `install`, completions, skills → `node_modules/argsbarg/docs/install.md`.
+6. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
+7. **Examples** (shipped under `node_modules/argsbarg/examples/`):
+   - Concepts / minimal config → `examples/config-app/`
+   - **Copy template** (all builtins, schemagen, `outputSchema`) → `examples/consumer-app/`
 
 **Hard rules** (details and examples are in the docs above — do not contradict them):
 
-- Reserved root commands: `completion`, `install`, `mcp`, `version`, `docs`, `update`.
+- Reserved root commands: `completion`, `install`, `mcp`, `version`, `docs`, `update`, `config`.
 - `satisfies CliProgram` / `CliLeaf`; action-oriented `description` on root, commands, options, and positionals.
-- Omit `mcpTool` unless genuinely CLI-only (`enabled: false`), `requiresEnv`, or an irreducible wire limit — fix schema and headless handlers first.
+- Omit `mcpTool` unless genuinely CLI-only (`enabled: false`) or an irreducible wire limit — fix schema and headless handlers first.
 - Interactive leaves: one headless path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json` (`shouldRunHeadless*`, `requireYesInNonTty`); not raw `isTTY`.
 - 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 in `outputSchemas.ts` — see `output-schema.md`; mark roots with **`JSON payload`** JSDoc in `src/**/types.ts`; do not hand-edit `src/schemas/generated/` or `outputSchemas.ts`.
+- App config: `program.appConfig.jsonSchema` from generated `configSchemas.ts` — see `config-schema.md`; mark roots with **`Config schema`** JSDoc; prefer the layout in `node_modules/argsbarg/examples/consumer-app/` when adding new schema roots.
 
-**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/config-app/main.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+/*
+Multi-file consumer example for program.appConfig.
+
+Files:
+  types.ts   — AppConfig interface (Config schema JSDoc marker for schemagen)
+  schema.ts  — APP_CONFIG_JSON_SCHEMA (inline; production apps generate this)
+  program.ts — CliProgram with appConfig block and commands using ctx.appConfig
+
+Try:
+  CONFIG_APP_API_TOKEN=dev bun ./examples/config-app/main.ts show --json
+  CONFIG_APP_API_TOKEN=dev bun ./examples/config-app/main.ts config get
+  CONFIG_APP_API_TOKEN=dev bun ./examples/config-app/main.ts ping
+*/
+
+import { Cli } from "../../src/index.ts";
+import { program } from "./program.ts";
+
+const cli = new Cli(program);
+await cli.run();

package/examples/config-app/program.ts

@@ -0,0 +1,81 @@
+/*
+CliProgram for the config-app example — program.appConfig with jsonSchema + metadata overlay.
+*/
+
+import pkg from "../../package.json" with { type: "json" };
+import {
+  type CliAppConfig,
+  type CliAppConfigEntry,
+  CliOptionKind,
+  type CliProgram,
+} from "../../src/index.ts";
+import { APP_CONFIG_JSON_SCHEMA } from "./schema.ts";
+
+const configPath = process.env.CONFIG_APP_CONFIG_FILE;
+
+const configSchema = {
+  apiToken: {
+    description: "Create at https://example.com/settings/tokens",
+    env: "CONFIG_APP_API_TOKEN",
+    sensitive: true,
+  },
+  defaultRegion: {
+    description: "AWS region for API calls.",
+    required: false,
+  },
+  maxRetries: {
+    description: "HTTP retry count (0–10).",
+  },
+  prefs: {
+    description: "Local cache preferences (not exported to env).",
+    required: false,
+  },
+} as const satisfies Record<string, CliAppConfigEntry>;
+
+export const program = {
+  key: "config-app",
+  version: pkg.version,
+  description: "Demonstrates program.appConfig, ctx.appConfig, and built-in config get/set.",
+  appConfig: {
+    ...(configPath ? { path: configPath } : {}),
+    jsonSchema: APP_CONFIG_JSON_SCHEMA,
+    entries: configSchema,
+  } satisfies CliAppConfig,
+  commands: [
+    {
+      key: "show",
+      description: "Print resolved config (secrets redacted).",
+      options: [
+        {
+          name: "json",
+          description: "Emit JSON.",
+          kind: CliOptionKind.Presence,
+        },
+      ],
+      handler: (ctx) => {
+        const out = {
+          defaultRegion: ctx.appConfig.get("defaultRegion"),
+          maxRetries: ctx.appConfig.get("maxRetries"),
+          prefs: ctx.appConfig.get("prefs"),
+          apiTokenSet: ctx.appConfig.get("apiToken") !== undefined,
+        };
+        if (ctx.hasFlag("json")) {
+          console.log(JSON.stringify(out, null, 2));
+        } else {
+          console.log(`region=${out.defaultRegion ?? "(not set)"}`);
+          console.log(`maxRetries=${out.maxRetries ?? "(not set)"}`);
+          console.log(`prefs=${out.prefs ? JSON.stringify(out.prefs) : "(not set)"}`);
+          console.log(`apiToken=${out.apiTokenSet ? "set" : "missing"}`);
+        }
+      },
+    },
+    {
+      key: "ping",
+      description: "Require apiToken and print a short confirmation.",
+      handler: (ctx) => {
+        const token = ctx.appConfig.require("apiToken");
+        console.log(`ok (token length ${String(token).length})`);
+      },
+    },
+  ],
+} satisfies CliProgram;

package/examples/config-app/schema.ts

@@ -0,0 +1,37 @@
+/*
+Inline draft-07 JSON Schema for AppConfig.
+Production apps commit generated JSON and import via configSchemas.ts — see docs/config-schema.md.
+*/
+
+import type { AppConfig } from "./types.ts";
+
+/** JSON Schema root for program.appConfig.jsonSchema (hand-written stand-in for schemagen). */
+export const APP_CONFIG_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  type: "object",
+  additionalProperties: false,
+  required: ["apiToken", "maxRetries"],
+  properties: {
+    apiToken: { type: "string", minLength: 1 },
+    defaultRegion: { type: "string", default: "us-east-1" },
+    maxRetries: { type: "integer", minimum: 0, maximum: 10, default: 3 },
+    prefs: {
+      type: "object",
+      additionalProperties: false,
+      required: ["ttl"],
+      properties: {
+        ttl: { type: "integer", minimum: 1 },
+      },
+    },
+  },
+} as const satisfies Record<string, unknown>;
+
+/** Compile-time check that schema keys align with AppConfig (documentation only). */
+type _SchemaKeys = keyof typeof APP_CONFIG_JSON_SCHEMA.properties;
+type _ConfigKeys = keyof AppConfig;
+const _assertKeysAlign: _SchemaKeys extends _ConfigKeys
+  ? _ConfigKeys extends _SchemaKeys
+    ? true
+    : never
+  : never = true;
+void _assertKeysAlign;

package/examples/config-app/types.ts

@@ -0,0 +1,19 @@
+/**
+ * Config schema
+ *
+ * Application settings persisted in a flat JSON file (`program.appConfig`).
+ * In a production app, generate `APP_CONFIG_JSON_SCHEMA` from this interface
+ * with ts-json-schema-generator — see docs/config-schema.md.
+ */
+export interface AppConfig {
+  /** API token from the provider dashboard. */
+  apiToken: string;
+  /** AWS region (default us-east-1). */
+  defaultRegion?: string;
+  /** HTTP retry count (default 3). */
+  maxRetries: number;
+  /** Local preferences (file-only; not mapped to process.env). */
+  prefs?: {
+    ttl: number;
+  };
+}

package/examples/consumer-app/README.md

@@ -0,0 +1,56 @@
+# consumer-app
+
+**Kitchen-sink argsbarg reference** — copy this layout when bootstrapping a production CLI. For a minimal `program.appConfig` intro, see [`../config-app/`](../config-app/).
+
+## What this demonstrates
+
+| Area | Files / wiring |
+| --- | --- |
+| All builtins | `completion`, `version`, `install` (+ `--update`), `docs`, `mcp`, `config get`/`set` |
+| `program.appConfig` | `src/types.ts` (`AppConfig`) → `schemas/configSchemas.ts` |
+| `outputSchema` | `src/commands/status/types.ts` (`StatusJsonOutput`) → `schemas/outputSchemas.ts` |
+| Schemagen | `scripts/schemagen.ts` + `scripts/schemagen/discover-schema-roots.ts` |
+| Handler access | `ctx.appConfig` in `src/program.ts` |
+| Package import | `from "argsbarg"` (not relative to argsbarg `src/`) |
+
+## Quick start (in this repo)
+
+```bash
+cd examples/consumer-app
+bun install
+bun run schemagen   # after changing src/**/types.ts
+CONSUMER_APP_API_TOKEN=dev bun run start status --json
+CONSUMER_APP_API_TOKEN=dev bun run start config get apiToken --json
+CONSUMER_APP_API_TOKEN=dev bun run start docs readme
+```
+
+## Copy into a new app
+
+1. Copy this directory into your repo (e.g. `apps/my-cli/`).
+2. Set `"argsbarg": "^<version>"` in `package.json` (replace `file:../..`).
+3. Run `bun run schemagen` and commit `schemas/generated/` + bridge `.ts` files.
+4. Copy [`node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc`](../../docs/templates/cursor/rules/cli-program.mdc) to `.cursor/rules/`.
+
+## Schemagen markers
+
+| Marker in interface JSDoc | Artifact |
+| --- | --- |
+| `Config schema` | `schemas/configSchemas.ts` + `schemas/generated/*-config.json` |
+| `JSON payload` | `schemas/outputSchemas.ts` + `schemas/generated/*.json` |
+
+Discovery walks `src/**/types.ts` only.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `CONSUMER_APP_API_TOKEN` | Overrides `apiToken` via `program.appConfig` env mapping |
+| `CONSUMER_APP_CONFIG_FILE` | Overrides config file path (`config.path`) |
+
+## Maintainers (argsbarg repo)
+
+When adding or changing builtins, update this example and run:
+
+```bash
+just consumer-app-schemagen
+```