argsbarg 3.6.3 → 4.0.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-06-24
+
+### Added
+
+- **`Cli` class** — single runtime entry: eager `cliValidateProgram` + `Object.freeze(program)` in constructor; `run()`, `invoke()`, `serveMcp()`; lazy `cli.appConfig` getter (refreshed on dispatch); `exportCommandSchema()` and `exportAppConfigSchema()`.
+- **`program.appConfig` + `CliAppConfig` / `CliAppConfigEntry`** — config-first model: flat JSON file, block `jsonSchema` (or all-string fallback), metadata overlay per key (`entries`), strict load (reject unknown keys), `ctx.appConfig` (`get`, `require`, `set`, `read`), built-in `config get`/`set`, zero-deps draft-07 subset validation.
+- **`docs/config-schema.md`** — recommended TypeScript → JSON Schema codegen for `program.appConfig.jsonSchema` (parallel to output-schema guide).
+- **`examples/consumer-app/`** — kitchen-sink copy template: all builtins, schemagen discovery, `outputSchema`, `from "argsbarg"`.
+- **`mcp bundle` Claude Code plugin** — writes `dist/<key>-plugin/` (`.claude-plugin/plugin.json`, `.mcp.json`, `bin/<key>`, skills) alongside `dist/<key>.mcpb`.
+
+### Changed
+
+- **Breaking:** **`cliRun`, `cliInvoke`, `cliMcpServeStdio` removed** — use `new Cli(program).run()`, `.invoke(argv)`, `.serveMcp()` instead.
+- **Breaking:** **`program.config` → `program.appConfig`**, **`schema` → `entries`**, **`CliConfig` → `CliAppConfig`**, **`ctx.config` → `ctx.appConfig`**.
+- **Breaking:** **`program.env` + `CliEnvVarConfig` removed** — use `program.appConfig.entries`; root `configFile` → `appConfig.path`; nested env bag → flat schema keys; no extra file keys / `raw()`.
+- **Breaking:** Handler config access — prefer `ctx.appConfig.get/require` over `process.env` for app config (env export remains for subprocesses).
+- **`mcp bundle`** — stdout prints both `.mcpb` and plugin directory paths (one line each).
+- **MCP config enforcement** — required keys from `program.appConfig` checked at `tools/call` (MCP) or before leaf dispatch (CLI).
+
+### Removed
+
+- **`mcpTool.requiresEnv`** — use `program.appConfig` schema entries with `env` instead.
+- **`mcpServer.envFile`** — use `program.appConfig` + JSON config file instead.
+- **`loadAppConfigEnv`, `ensureProgramEnv`** — replaced internally by `ensureAppConfig`, `exportConfigToEnv`.
+
+## [3.6.4] - 2026-06-23
+
+### Added
+
+- **`docs/output-schema.md`** — recommended TypeScript → JSON Schema codegen for leaf `outputSchema`: `JSON payload` JSDoc discovery in `src/**/types.ts`, auto-generated `outputSchemas.ts` bridge, naming suffixes, JSDoc quality bar, 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
@@ -20,6 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`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
 
@@ -413,7 +449,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.3...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v4.0.0...HEAD
+[4.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v4.0.0
+[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

package/README.md

@@ -35,9 +35,9 @@ Shell completions! -->
 ## Usage
 
 ```typescript
-import { cliRun, type CliProgram, CliOptionKind } from "argsbarg";
+import { Cli, type CliProgram, CliOptionKind } from "argsbarg";
 
-const cli = {
+const program = {
   key: "helloapp",
   version: "1.0.0",
   description: "Tiny demo.",
@@ -67,10 +67,11 @@ const cli = {
   },
 } satisfies CliProgram;
 
-await cliRun(cli);
+const cli = new Cli(program);
+await cli.run();
 ```
 
-`cliRun` parses `process.argv`, prints help or errors, dispatches the leaf handler, and **exits the process**.
+`Cli.run()` parses `process.argv`, prints help or errors, dispatches the leaf handler, and **exits the process**.
 
 
 
@@ -95,7 +96,7 @@ Everything you need for a first-class CLI:
 Every app gets:
 
 - `-h` / `--help` at any routing depth (scoped help).
-- **`completion bash` / `completion zsh` / `completion fish`** — print shell completion scripts to stdout (injected by `cliRun`).
+- **`completion bash` / `completion zsh` / `completion fish`** — print shell completion scripts to stdout (injected by `Cli.run()`).
 - **`version`** — print `CliProgram.version` (`myapp version`).
 - **`mcp`** — when `mcpServer.enabled` is `true`, run as an MCP stdio server (`myapp mcp`).
 - **`docs`** — when `docs.enabled` is `true`, print bundled markdown topics, schema JSON, API markdown, and generated skill content (`myapp docs`, `myapp docs readme`, `myapp docs schema`, `myapp docs api`, `myapp docs skill`, …). See [docs/bundled-docs.md](docs/bundled-docs.md).
@@ -108,7 +109,7 @@ When **`docs.enabled`** is `true`, do not declare a top-level command named **`d
 
 ### MCP (AI agents)
 
-Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `<sanitized-key>://schema` (same as `myapp docs schema`). Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
+Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `<sanitized-key>://schema` (same as `myapp docs schema`). Handlers can read `ctx.invocation`; use `cli.invoke(argv)` for headless testing.
 
 See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details. See **[docs/cli-program.md](docs/cli-program.md)** for schema authoring (consumer apps: copy **`docs/templates/cursor/rules/cli-program.mdc`** to **`.cursor/rules/cli-program.mdc`**).
 
@@ -155,13 +156,13 @@ 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. Documentation map: **[docs/README.md](docs/README.md)**. Authoring 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
 
 1. Build a **program root** with `satisfies CliProgram` (or `: CliProgram`): `key` is the app/binary 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 cliRun(root)` with that root — 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**).
+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**.
 
 ### Fallback modes (`CliFallbackMode`)
@@ -215,6 +216,10 @@ 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()`. |
+| `ArgsBargConfigApp` | `examples/config-app/` | `program.appConfig`, `ctx.appConfig`, built-in `config get`/`set`, inline JSON Schema. |
+| `ArgsBargConsumerApp` | `examples/consumer-app/` | **Copy template:** all builtins, schemagen discovery, `outputSchema`, `from "argsbarg"`. |
+
+Examples ship in the npm package under `node_modules/argsbarg/examples/`. Agents should read **`config-app`** for concepts and **`consumer-app`** when scaffolding a full CLI.
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -228,6 +233,12 @@ 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
+
+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
+
+cd examples/consumer-app && bun install && bun run schemagen
+CONSUMER_APP_API_TOKEN=dev bun run start status --json
 ```
 
 
@@ -243,8 +254,9 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | `CliSchemaValidationError` | Thrown when the static command tree violates schema rules. |
 | `CliContext` | Handler context (`ctx.hasFlag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.readLeafInputs`, `ctx.invocation`, …). |
 | `CliLeafInputs` | Record type returned by `readLeafInputs()` — coerced option/positional values keyed by schema name. |
-| `cliRun(root, [argv])` | Validate, parse argv, dispatch, exit. |
-| `cliInvoke(root, argv)` | Parse and dispatch without exiting; returns captured stdout/stderr. |
+| `Cli` | Runtime: validate + freeze program, `run()`, `invoke()`, `serveMcp()`, `appConfig` getter, `exportCommandSchema()`, `exportAppConfigSchema()`. |
+| `CliInvokeResult`, `CliInvokeKind` | Result types from `cli.invoke()`. |
+| `CliAppConfig`, `CliAppConfigEntry` | App config block on the program root (`entries` metadata overlay + optional `jsonSchema`). |
 | `cliErrWithHelp(ctx, msg)` | Print error + scoped help on stderr, exit 1. |
 | `parseDurationMs`, `parseCommaList`, `parseDate`, `parseDateTime` | Optional format parsers for use outside handlers. |
 

package/docs/README.md

@@ -6,12 +6,25 @@ Start here to pick the right guide.
 | --- | --- |
 | **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 |
+| **App config / `program.appConfig`** | [config-schema.md](config-schema.md) — flat JSON file, `ctx.appConfig`, codegen |
 | **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/` |
+| **Runnable examples** (shipped in npm) | [examples/](examples/) — see table below |
+
+## Examples (agents: read these)
+
+Examples are included in the npm tarball (`package.json` `files`). After `bun add argsbarg`, open `node_modules/argsbarg/examples/`.
+
+| Tier | Path | Use when |
+| --- | --- | --- |
+| Learn | [examples/minimal.ts](../examples/minimal.ts), [config-app/](../examples/config-app/) | One feature at a time |
+| Reference | [examples/nested.ts](../examples/nested.ts), [formats.ts](../examples/formats.ts) | Routing, formats, MCP snippet |
+| **Copy** | [examples/consumer-app/](../examples/consumer-app/) | Bootstrapping a production CLI (all builtins + schemagen) |
 
 ## Framework docs vs consumer docgen
 
@@ -22,11 +35,3 @@ Start here to pick the right guide.
 | **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

@@ -11,6 +11,8 @@ Two documentation layers often coexist in a consumer repo:
 | **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.
@@ -85,7 +87,7 @@ When `docs.enabled` is `true`:
 
 ## MCP guide (`docs mcp`)
 
-When both `docs.enabled` and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `requiresEnv`, schema resource URI, `install --mcp`, and protocol notes.
+When both `docs.enabled` and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `program.appConfig`, schema resource URI, `install --mcp`, and protocol notes.
 
 There is no override API in v1 — customize behavior via `mcpTool.description` on leaf commands.
 

package/docs/cli-program.md

@@ -112,7 +112,6 @@ Many "MCP problems" are schema or handler gaps. Prefer these over escape hatches
 | Field | Use when |
 | --- | --- |
 | `enabled: false` | Command is **genuinely** CLI-only (open browser, Ink-only flow with no scriptable equivalent) |
-| `requiresEnv: [...]` | Runtime secrets; appended to MCP description and enforced at `tools/call` |
 | `description: "..."` | **Irreducible** MCP limitation (e.g. live tail / `--watch` cannot be streamed on the MCP wire yet) |
 
 ### Structured stdout
@@ -134,6 +133,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**.
@@ -371,9 +372,70 @@ handler: async (ctx) => {
 
 Basic synchronous handlers do not need this structure — only commands with an interactive branch.
 
+## Configuration (`program.appConfig`)
+
+Declare app configuration on the **program root** (not on leaves). Values persist in a flat JSON file; handlers read resolved values via `ctx.appConfig`.
+
+```typescript
+import { Cli, type CliProgram } from "argsbarg";
+import { APP_CONFIG_JSON_SCHEMA } from "./schemas/configSchemas.js";
+
+const program = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "…",
+  appConfig: {
+    path: "~/.config/myapp/config", // optional override
+    jsonSchema: APP_CONFIG_JSON_SCHEMA, // optional; omit for all-string mode
+    entries: {
+      apiToken: {
+        description: "Create at https://example.com/settings/tokens",
+        env: "API_TOKEN",
+        sensitive: true,
+      },
+      defaultRegion: {
+        title: "Default region",
+        description: "AWS region (default us-east-1).",
+        required: false,
+      },
+      maxRetries: { description: "Retry count." },
+    },
+  },
+  handler: (ctx) => {
+    const token = ctx.appConfig.require("apiToken");
+    const region = ctx.appConfig.get("defaultRegion");
+  },
+} satisfies CliProgram;
+
+const cli = new Cli(program);
+await cli.run();
+```
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `description` | *(required)* | Shown in prompts, `config get`, and bundle manifests |
+| `title` | config key | Short label in `install --configure` |
+| `default` | — | Used when `jsonSchema` omitted (all-string mode) |
+| `required` | `true` | When `false`, optional unless required by `jsonSchema` |
+| `sensitive` | name heuristic (`token`, `secret`, …) | Redact in prompts, `config get`, and status |
+| `env` | — | When set: non-empty host env overrides file; exported to `process.env` after resolve |
+
+**Config file** (created on demand):
+
+- Default: `$XDG_CONFIG_HOME/<sanitized-key>/config` or `%APPDATA%/<key>/config`.
+- JSON: flat object keyed by schema names — `{ "apiToken": "…", "maxRetries": 5 }`.
+- **Strict:** unknown keys rejected on load.
+- **CLI:** missing required config exits 1 before the leaf handler (TTY prompt when interactive). Built-in `config get`/`set` skip this exit.
+- **MCP:** server stays up; missing config returns `isError: true` at `tools/call`.
+- **Configure:** `myapp install --configure` (not part of `--all`).
+
+See [config-schema.md](config-schema.md) for codegen, [install.md](install.md), and [mcp.md](mcp.md).
+
+**Handler access (`ctx.appConfig`):** `get`, `require`, `set`, `read` — prefer over `process.env` in handlers; env export remains for subprocess inheritance.
+
 ## Reserved names
 
-Do not declare user commands named `completion`, `install`, `mcp`, `version`, or `docs` at the root — ArgsBarg injects these when configured.
+Do not declare user commands named `completion`, `install`, `mcp`, `version`, `docs`, or `config` at the root — ArgsBarg injects these when configured.
 
 ## Cursor rule for consumer repos
 
@@ -388,15 +450,27 @@ 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`

package/docs/config-schema.md

@@ -0,0 +1,192 @@
+# Config schema (`program.appConfig`)
+
+How to declare app configuration — flat JSON file, env overrides, handler access via `ctx.appConfig`, and a **recommended codegen pipeline** for typed config.
+
+## Argsbarg contract
+
+On the **program root**, set `appConfig` with metadata `entries` and optional block `jsonSchema`:
+
+```typescript
+import { Cli, type CliProgram } from "argsbarg";
+import { APP_CONFIG_JSON_SCHEMA } from "./schemas/configSchemas.js";
+
+const program = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "…",
+  appConfig: {
+    jsonSchema: APP_CONFIG_JSON_SCHEMA,
+    entries: {
+      apiToken: {
+        description: "Create at https://example.com/settings/tokens",
+        env: "API_TOKEN",
+        sensitive: true,
+      },
+      defaultRegion: { description: "AWS region.", required: false },
+      maxRetries: { description: "Retry count." },
+    },
+  },
+  handler: (ctx) => {
+    const token = ctx.appConfig.require("apiToken");
+    const region = ctx.appConfig.get("defaultRegion"); // default already applied
+  },
+} satisfies CliProgram;
+
+const cli = new Cli(program);
+await cli.run();
+```
+
+| Where argsbarg uses it | Purpose |
+| --- | --- |
+| Config file | Flat JSON keyed by schema names; strict load (unknown keys rejected) |
+| `install --configure` / `--status` | Interactive setup and status |
+| Built-in `config get` / `config set` | Read/write resolved values (opt-out via `commands: false`) |
+| MCP bundle / Claude plugin | `userConfig` for entries with `env` set |
+| `ctx.appConfig` in handlers | `get`, `require`, `set`, `read` — prefer over `process.env` |
+
+**Validation at runtime** — argsbarg validates the config file and `config set` / `ctx.appConfig.set` against the effective JSON Schema (block `jsonSchema` or synthesized all-string schema).
+
+**No public config I/O exports** — consumers use `program.appConfig` for authoring and `ctx.appConfig` in handlers.
+
+See [cli-program.md — Configuration](cli-program.md#configuration-programappconfig) for resolution order, bootstrap timing, and reserved `config` command.
+
+## `CliAppConfig` and `CliAppConfigEntry`
+
+```typescript
+export interface CliAppConfigEntry {
+  description: string;
+  title?: string;       // default: config key
+  default?: string;     // all-string mode only
+  required?: boolean;   // default: true (can override jsonSchema required)
+  sensitive?: boolean;  // default: name heuristic
+  env?: string;         // env override + export to process.env after resolve
+}
+
+export interface CliAppConfig {
+  path?: string;        // default: ~/.config/<key>/config (OS rules)
+  commands?: boolean | { enabled?: boolean; mcpSet?: boolean };
+  jsonSchema?: Record<string, unknown>;  // draft-07 block schema
+  entries: Record<string, CliAppConfigEntry>;
+}
+```
+
+**Conventions:**
+
+- Secrets: `env: "API_TOKEN"` on entry; file key `apiToken`
+- Prefs without env: local-file only; excluded from MCP/plugin manifests
+- MCP manifests: only entries with `env` set (sanitized to snake_case keys)
+
+## Config file shape
+
+Flat JSON at `config.path` (default OS path unchanged):
+
+```json
+{
+  "apiToken": "xxx",
+  "defaultRegion": "eu-west-1",
+  "maxRetries": 5,
+  "prefs": { "ttl": 3600 }
+}
+```
+
+No nested `env` bag. No extra keys — rejected on load.
+
+## Resolution order (per schema key)
+
+| Key has `env`? | Resolved value |
+| --- | --- |
+| **Yes** | non-empty `process.env[env]` → else file[key] → else default |
+| **No** | file[key] → else default |
+
+Empty string in env or file counts as **missing** for required entries. After resolution, mapped values are exported to `process.env`.
+
+## Hand-written vs generated
+
+| Approach | When |
+| --- | --- |
+| **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)
+
+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"]
+  end
+  subgraph gen [just schemagen]
+    Script["scripts/generate-config-schemas.ts"]
+    Gen["ts-json-schema-generator"]
+  end
+  subgraph artifacts [Committed]
+    Json["src/schemas/generated/app-config.json"]
+    Bridge["src/schemas/configSchemas.ts"]
+  end
+  subgraph runtime [Runtime]
+    Program["program.appConfig.jsonSchema"]
+    Validate["argsbarg runtime subset validator"]
+  end
+  TypesTs --> Marker --> Script --> Gen --> Json
+  Script --> Bridge --> Program --> Validate
+```
+
+| Piece | Convention |
+| --- | --- |
+| Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) |
+| Discovery | JSDoc marker **`Config schema`** on the root config interface |
+| Artifacts | Commit `app-config.json` and `configSchemas.ts` bridge exporting `APP_CONFIG_JSON_SCHEMA` |
+| Consumer CI | Optional: `ajv` + `ajv-formats` against the same committed JSON (not an argsbarg runtime dep) |
+
+### Supported AppConfig shapes (argsbarg runtime validator)
+
+| Supported (v1) | Deferred |
+| --- | --- |
+| `type`, `properties`, `required`, `additionalProperties` | remote `$ref` |
+| `enum`, `const`, `default` | complex `if`/`then`/`else` |
+| local `#/definitions` + `$ref` | full draft-2020-12 |
+| `anyOf` / `oneOf` (basic) | |
+| `items`, `minItems`, `maxItems` | |
+| `minimum`, `maximum`, `minLength`, `maxLength`, `pattern` | |
+
+## Minimal example (no schemagen)
+
+```typescript
+appConfig: {
+  entries: {
+    apiToken: { description: "Token.", env: "API_TOKEN", sensitive: true },
+    greeting: { description: "Greeting.", default: "hello", required: false },
+  },
+},
+```
+
+All file values are strings. Defaults come from `entry.default`.
+
+## Built-in `config` command
+
+When `program.appConfig` is set and `commands !== false`:
+
+| Subcommand | Purpose |
+| --- | --- |
+| `config get [key]` | Resolved value(s); `--json`; `--json --pretty` |
+| `config set <key> <value>` | One key; full document re-validated after merge |
+
+`config get`/`set` skip required-config exit and TTY prompts. Sensitive values redact on `get` (`REDACTED` / `{ "set": true }` with `--json`).
+
+Object/array/`$ref` properties require `--json` on `config set`.
+
+## Example in this repo
+
+| Example | Role |
+| --- | --- |
+| [`examples/config-app/`](../examples/config-app/) | **Learn** — hand-written schema, minimal setup |
+| [`examples/consumer-app/`](../examples/consumer-app/) | **Copy** — schemagen discovery, `APP_CONFIG_JSON_SCHEMA` bridge |
+
+```bash
+cd examples/consumer-app && bun install && bun run schemagen
+CONSUMER_APP_API_TOKEN=dev bun run start config get apiToken --json
+```
+
+Set `CONSUMER_APP_CONFIG_FILE` to override the config file path.

package/docs/developing.md

@@ -32,12 +32,16 @@ Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile
 
 | Recipe | When | Effect |
 | --- | --- | --- |
-| `just consumer-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>` in each consumer |
-| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, `just build`, `just docgen`, `just install` |
+| `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.
 
-Re-copy `docs/templates/cursor/rules/cli-program.mdc` into consumer repos when the template changes (append app-specific conventions; do not fork the whole guide).
+**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
 
@@ -45,6 +49,19 @@ Re-copy `docs/templates/cursor/rules/cli-program.mdc` into consumer repos when t
 
 When adding docs or examples intended for consumers, ensure they live under whitelisted paths (`docs/`, `examples/`, `src/`, etc.).
 
+Exclude `examples/consumer-app/node_modules/` from the npm tarball via [`.npmignore`](../.npmignore).
+
+## Kitchen-sink example
+
+[`examples/consumer-app/`](../examples/consumer-app/) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
+
+```bash
+just consumer-app-schemagen
+just test
+```
+
+See [`.cursor/rules/examples.mdc`](../.cursor/rules/examples.mdc) for maintainer guidance.
+
 ## Docs
 
 See [README.md](README.md) for the documentation map. Framework authoring guide: [cli-program.md](cli-program.md).

package/docs/install.md

@@ -32,6 +32,7 @@ myapp install --uninstall --all --yes
 | Cursor skill | `--skill` | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
 | Claude skill | `--skill` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
 | MCP config | `--mcp` | Cursor, Claude Code/Desktop, OpenCode (`~/.config/opencode`), Codex (`codex` on PATH), ChatGPT desktop (when app data exists). ChatGPT web uses Connectors — see `docs mcp` |
+| App config | `--config` | JSON config file for `program.appConfig` (with `--uninstall`; included in `--uninstall --all`) |
 
 `--all` expands to `--bin`, `--completions`, `--skill`, and `--mcp` (when `mcpServer.enabled` is `true`) for both install and uninstall. Missing targets are skipped silently (no error if nothing is on disk or a shell/agent directory does not exist).
 
@@ -95,6 +96,42 @@ Environment:
 
 - `INSTALL_PREFIX` — same as `install.prefix` / `--prefix`
 
+## App config (`program.appConfig`)
+
+When `program.appConfig` is set on the program root, ArgsBarg manages a flat JSON config file:
+
+```typescript
+appConfig: {
+  entries: {
+    apiToken: {
+      description: "Create at https://example.com/settings/tokens",
+      env: "API_TOKEN",
+      sensitive: true,
+    },
+  },
+  path: "~/.config/myapp/config", // optional; default is OS-specific
+},
+```
+
+Default path: `$XDG_CONFIG_HOME/<sanitized-key>/config` (Linux/macOS) or `%APPDATA%/<key>/config` (Windows).
+
+| Flag | Description |
+| --- | --- |
+| `--configure` | Interactive prompt for each schema entry; writes or updates the config file (standalone — not part of `--all`) |
+| `--uninstall --config` | Remove the config file (included in `--uninstall --all`) |
+| `--status` | Shows config path and which required keys are set or missing |
+
+**Configure UX** (TTY):
+
+```
+API token
+  Create at https://example.com/settings/tokens
+Current: REDACTED
+Value (Enter to keep):
+```
+
+Non-sensitive vars show the current value; first-time setup omits the `Current:` line.
+
 ## Flags
 
 | Flag | Description |
@@ -108,7 +145,7 @@ Environment:
 | `--update` | Download latest release and reinstall installed artifacts (requires `install.updateGetLatest`; implies `--yes`) |
 | `--from <path>` | Binary to copy with `--reinstall` (default: running executable) |
 | `--status` | Read-only inventory |
-| `--uninstall` | Remove artifacts in scope (`--all`, `--bin`, `--completions`, `--skill`, `--mcp`); skips targets not installed |
+| `--uninstall` | Remove artifacts in scope (`--all`, `--bin`, `--completions`, `--skill`, `--mcp`, `--config`); skips targets not installed |
 
 ## MCP merge behavior