argsbarg 3.4.2 → 3.6.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.0] - 2026-06-23
+
+### Added
+
+- **`CliValueFormat`** — optional `format` on string options: `duration`, `comma-list`, `date`, `date-time`; optional `default` and `pattern` (mutually exclusive with `format`).
+- **`CliContext`** — `durationOpt`, `commaListOpt`, `dateOpt`, `dateTimeOpt`, and `readLeafInputs()` for schema-driven handler reads.
+- **`formats` exports** — `parseDurationMs`, `parseCommaList`, `parseDate`, `parseDateTime` for reuse outside handlers.
+
+### Changed
+
+- **Post-parse validation** — applies option `default` values and validates `format` / `pattern` before handlers run.
+- **MCP varargs** — `tools/call` positional arrays must be JSON arrays (comma-separated strings no longer accepted).
+- **MCP comma-list options** — `format: comma-list` accepts string or array in `tools/call`.
+- **`docs mcp`**, **`docs api`**, and **`docs/cli-program.md`** — document value formats and varargs policy.
+- **Cursor rule template** (`docs/templates/cursor/rules/cli-program.mdc`) — thin tripwire that directs agents to read `node_modules/argsbarg/docs/cli-program.md` instead of duplicating authoring guidance.
+
+## [3.5.0] - 2026-06-22
+
+### Added
+
+- **`install --mcp`** — OpenCode: merges local MCP entry into `~/.config/opencode` config (`mcp` key, OpenCode `type: "local"` format).
+- **`install --mcp`** — Codex: runs `codex mcp add` when `codex` is on PATH.
+- **`install --mcp`** — ChatGPT desktop: merges into `chatgpt_mcp_config.json` when ChatGPT app data exists.
+
+### Changed
+
+- **`docs mcp`** — Codex/ChatGPT guidance: Connectors for web (remote MCP); gated desktop JSON auto-install.
+
 ## [3.4.2] - 2026-06-22
 
 ### Added
@@ -359,7 +387,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.4.2...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.0...HEAD
+[3.6.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.0
+[3.5.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.5.0
 [3.4.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.2
 [3.4.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.1
 [3.4.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.0

package/README.md

@@ -112,9 +112,9 @@ Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp
 
 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`**).
 
-### Install
+### Install CLI
 
-After `bun build --compile` (or when running via `bun`), ship your CLI and let users run:
+argsbarg includes CLI features to manage installation of your compiled bun app. After `bun build --compile` (or when running via `bun`), ship your CLI and let users run:
 
 ```bash
 myapp install --all --yes
@@ -140,12 +140,23 @@ myapp completion fish > ~/.config/fish/completions/myapp.fish
 
 
 
-## Install
+## Quick Start
 
 ```bash
-bun add bun-argsbarg
+bun add argsbarg
 ```
 
+### Cursor / AI agents
+
+Argsbarg ships authoring docs in `node_modules/argsbarg/docs/`. Agents do not load them unless your repo points there — copy the thin Cursor rule after install (it tells agents to **read** `cli-program.md`, not duplicate it):
+
+```bash
+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)**.
+
 
 ## How it works
 
@@ -178,9 +189,13 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 
 ### Reading values (`CliContext`)
 
-- `ctx.flag("verbose")` — presence options (`boolean`).
+- `ctx.flag("verbose")` / `ctx.hasFlag("verbose")` — presence options (`boolean`).
 - `ctx.stringOpt("name")` / `ctx.numberOpt("count")` — `string | undefined` / `number | null`.
-- `ctx.typedOpt<T>("custom", parseFn)` — pass a custom parsing function for type-safe option resolution.
+- `ctx.durationOpt("timeout")` — duration options (`format: CliValueFormat.Duration`) as milliseconds.
+- `ctx.commaListOpt("services")` — comma-list options as `string[] | undefined`.
+- `ctx.dateOpt("on")` / `ctx.dateTimeOpt("since")` — ISO date / date-time options.
+- `ctx.readLeafInputs()` — coerced option and positional values for the current leaf (schema-driven).
+- `ctx.typedOpt<T>("custom", parseFn)` — custom parsing for type-safe option resolution.
 - `ctx.args` — positional words in order as `string[]`.
 - `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.
 - `ctx.program` — program root (`CliProgram`) for contextual help.
@@ -221,12 +236,13 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | Symbol | Role |
 | --- | --- |
 | `CliProgram`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
-| `CliOptionKind`, `CliFallbackMode` | Option kinds (`Presence`, `String`, `Number`, `Enum`) and root fallback behavior. |
+| `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.args`, `ctx.invocation`, …). |
+| `CliContext` | Handler context (`ctx.flag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.readLeafInputs`, `ctx.invocation`, …). |
 | `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. |
+| `parseDurationMs`, `parseCommaList`, `parseDate`, `parseDateTime` | Optional format parsers for use outside handlers. |
 
 Reserved identifiers (validated at startup): root commands **`completion`**, **`version`**, **`install`**, **`docs`** (when `docs.enabled` is `true`), and **`mcp`** (when `mcpServer.enabled` is `true`).
 

package/biome.json

@@ -1,17 +1,40 @@
 {
-  "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json",
-  "organizeImports": {
-    "enabled": true
-  },
+  "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json",
+  "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true
+      "preset": "recommended"
     }
   },
   "formatter": {
     "enabled": true,
     "indentStyle": "space",
     "lineWidth": 100
-  }
+  },
+  "overrides": [
+    {
+      "includes": ["**/completion-bash.ts", "**/completion-zsh.ts"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noTemplateCurlyInString": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["**/*.test.ts"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noNonNullAssertion": "off"
+          },
+          "suspicious": {
+            "noTemplateCurlyInString": "off"
+          }
+        }
+      }
+    }
+  ]
 }

package/bun.lock

@@ -5,17 +5,39 @@
     "": {
       "name": "argsbarg",
       "devDependencies": {
+        "@biomejs/biome": "^2.5.0",
         "@types/bun": "^1.3.12",
+        "typescript": "^5.9.3",
       },
     },
   },
   "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.5.0", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.0", "@biomejs/cli-darwin-x64": "2.5.0", "@biomejs/cli-linux-arm64": "2.5.0", "@biomejs/cli-linux-arm64-musl": "2.5.0", "@biomejs/cli-linux-x64": "2.5.0", "@biomejs/cli-linux-x64-musl": "2.5.0", "@biomejs/cli-win32-arm64": "2.5.0", "@biomejs/cli-win32-x64": "2.5.0" }, "bin": { "biome": "bin/biome" } }, "sha512-4kURkd9hAPrdDM3C9n82ycYgx8hvQcW6MjKTEejruj8rK0N8P3OPpdy8BvI8kt3KWY4ycF5XtDOrktetEfhfuw=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-Mn3Fwi3SA5fgmfCPqmzpWF2DLZnms3BVAhM088nTnGrTZmHS3wwIjcoZPqpXeNgd3DrrLH6xp8vTLIBuJoZiXw=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-rg3VPL5P8mYro6pqlXYXuJWph21slVp3SZtAqWSrkZs40d2gTzYmHF8E/X1iTID25btmNKltNDJ926sqVBp7DQ=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-tl+LW8fdD96/xdeWtWwc82LIOc5CoY7N2AsogLTp5R4ECErYt+8Jl/N68ezN9vzSiqPTxw6vjcihoLPYKZHrlw=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-vQdM4oSGaf7ZNeGO9w5+Y8SBtyser9M6znxYbm7Ec8wInxJu1WiKxFYZW5Auj2d80bcVvefuGGRxoFOE0eee8g=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.0", "", { "os": "linux", "cpu": "x64" }, "sha512-zpEGf4RQbFEh8Vt7OmavLyyOzRbtcE9osCqrS1kfvt8jDvxwhKXLSf7n0ebr/ov0RJ9ssP+lhs6C8a9WwFvrQA=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.0", "", { "os": "linux", "cpu": "x64" }, "sha512-+9hIcMngJ+yGUahXqZuZ8CoWKJE9SAZsFsM3QDvXpNsLbXZ9lqVzgBhOk/jTSYkOA0GLP9eu3teukqpLUojHMg=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-jB0wAvTLI4itx5VidqVUejPQFhRUxiZ9l9FvZ26D5fl6t3qme+ZB4PD3bTSeL1vZ8NI2Rx/zj6H9zcESuGHKGw=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.0", "", { "os": "win32", "cpu": "x64" }, "sha512-VT/lF+GId+67j8aDfLkxdxNoVApsPSTbyAtB3jJq0IWTrY77WXfbPfpngxq0bA6JCEv/7k8C9qWjDRKRznDlyw=="],
+
     "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
 
     "@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
 
     "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
 
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
     "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
   }
 }

package/docs/cli-program.md

@@ -136,6 +136,65 @@ Do **not** use `mcpTool.description` to paper over missing `--yes`, non-standard
 
 If help text and MCP behavior match after your fixes, **omit `mcpTool` entirely**.
 
+## Value formats
+
+On **string options**, optional metadata improves validation, MCP `inputSchema`, and handler reads:
+
+| Field | Purpose |
+| --- | --- |
+| `format: CliValueFormat.Duration` | Values like `30s`, `20m`, `1h`; read with `ctx.durationOpt(name)` (milliseconds) |
+| `format: CliValueFormat.CommaList` | Single-flag lists (`--services a,b`); MCP may pass string or array; read with `ctx.commaListOpt(name)` |
+| `format: CliValueFormat.Date` | `YYYY-MM-DD`; read with `ctx.dateOpt(name)` |
+| `format: CliValueFormat.DateTime` | RFC 3339 instant; read with `ctx.dateTimeOpt(name)` |
+| `default: "..."` | Applied in post-parse when the option is omitted (not valid with `required: true`) |
+| `pattern: "..."` | Regex validation (mutually exclusive with `format`) |
+
+`format` applies to **string options only** — not positionals. Post-parse keeps raw strings in `ctx.opts`; typed readers return coerced values.
+
+**Example** (duration with default, comma-list flag):
+
+```typescript
+import { CliOptionKind, CliValueFormat } from "argsbarg";
+
+options: [
+  {
+    name: "timeout",
+    description: "Maximum wait time.",
+    kind: CliOptionKind.String,
+    format: CliValueFormat.Duration,
+    default: "20m",
+  },
+  {
+    name: "services",
+    description: "Service names to reset (single env only).",
+    kind: CliOptionKind.String,
+    format: CliValueFormat.CommaList,
+  },
+],
+handler: async (ctx) => {
+  const timeoutMs = ctx.durationOpt("timeout")!; // always set via default
+  const services = ctx.commaListOpt("services"); // string[] | undefined
+},
+```
+
+**Varargs positionals** (`argMax: 0`):
+
+| Surface | Multiple values |
+| --- | --- |
+| CLI | Space-separated words: `myapp uids uid-a uid-b` |
+| MCP | JSON array on the positional key: `{ "uids": ["uid-a", "uid-b"] }` |
+
+Read varargs with `ctx.positional("uids")` (returns `string[]`) or `ctx.args`. Do not comma-split argv tokens or use `format` on positionals.
+
+**`readLeafInputs()`** — for leaves with several flags, one schema-driven read instead of hand-rolled `hasFlag` / `stringOpt` lines:
+
+```typescript
+const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs();
+// duration → number (ms); comma-list → string[]; presence → boolean; number → number
+```
+
+Cross-field rules (e.g. `--match-remote` requires `--branch`) stay in consumer `resolve*` layers — argsbarg does not validate those.
+
 ## 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:
@@ -219,7 +278,22 @@ Do not declare user commands named `completion`, `install`, `mcp`, `version`, or
 
 ## Cursor rule for consumer repos
 
-Copy `node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc` to `.cursor/rules/cli-program.mdc` so agents editing your CLI schema follow these conventions.
+Argsbarg ships framework docs under `node_modules/argsbarg/docs/` (same files as this repo’s `docs/`). **This file is the authoritative guide** — the Cursor rule is a thin tripwire that tells agents to read it.
+
+Agents do **not** discover package docs automatically. Wire them in after `bun add argsbarg`:
+
+1. **Copy the Cursor rule** (recommended):
+
+```bash
+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.
+
+2. **Optional:** a second rule for app-only conventions (e.g. `src/cli/shared.ts` flag names, JSON-only handlers, Ink patterns).
+
+3. **Optional:** `.cursor/argsbarg.mdc` or `AGENTS.md` pointing at `node_modules/argsbarg/docs/cli-program.md` for broader context.
 
 ## See also
 

package/docs/install.md

@@ -31,7 +31,7 @@ myapp install --uninstall --all --yes
 | Fish completion | `--completions` | `~/.config/fish/completions/<key>.fish` |
 | Cursor skill | `--skill` | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
 | Claude skill | `--skill` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
-| MCP config | `--mcp` | `~/.cursor/mcp.json` (when `~/.cursor` exists), `~/.claude.json` (Claude Code), and Claude Desktop `claude_desktop_config.json` when Claude Desktop app data 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` |
 
 `--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).
 

package/docs/mcp.md

@@ -75,6 +75,50 @@ Use your real binary or script path. For a compiled CLI, `command` can be the in
 
 Restart Claude Desktop after config changes. You can also install a **`.mcpb`** bundle via **`mcp bundle`** (see [MCP Bundle](#mcp-bundle-mcp-bundle)).
 
+### OpenCode
+
+When `~/.config/opencode` exists, **`install --mcp`** merges a local server under the top-level **`mcp`** key (not `mcpServers`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "myapp": {
+      "type": "local",
+      "command": ["myapp", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+OpenCode reads `opencode.jsonc`, `opencode.json`, or `config.json` in that directory. Argsbarg updates the first existing file, or creates `config.json`. JSON-with-comments (`.jsonc`) is not auto-edited — add the block manually or use a `.json` config file.
+
+### OpenAI Codex
+
+When **`codex`** is on PATH, **`install --mcp`** runs `codex mcp add <server> -- <binary> mcp`, which writes **`~/.codex/config.toml`**. Otherwise add manually:
+
+```toml
+[mcp_servers.myapp]
+command = "myapp"
+args = ["mcp"]
+```
+
+Use **`codex mcp`** to list/add/remove servers, or **Settings → MCP → Open config.toml** in the Codex app. CLI and IDE extension share the same file.
+
+### ChatGPT
+
+**Web / Connectors (OpenAI’s documented path)** — **Settings → Connectors → Developer mode** with a **remote HTTPS MCP URL**. ChatGPT does not spawn local stdio binaries; bridge and tunnel local servers when needed.
+
+**Desktop JSON (gated auto-install)** — when ChatGPT app data exists, **`install --mcp`** also merges `mcpServers` into:
+
+| Platform | Path |
+| --- | --- |
+| macOS | `~/Library/Application Support/ChatGPT/chatgpt_mcp_config.json` |
+| Windows | `%APPDATA%\OpenAI\ChatGPT\chatgpt_mcp_config.json` |
+
+Local JSON support varies by desktop build. Prefer **Connectors** for ChatGPT web or when tools do not appear after install.
+
 ### Other MCP hosts
 
 Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`mcp`** starts the server.
@@ -321,7 +365,7 @@ just build
 
 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`).
 
-Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `install --mcp` and MCP hosts). Use **`install --mcp`** for Cursor, Claude Code, and Claude Desktop JSON config.
+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.
 
 ## Hidden commands and options
 

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

@@ -1,29 +1,23 @@
 ---
-description: Argsbarg CliProgram authoring; copy to .cursor/rules/cli-program.mdc
-globs: "**/*.{ts,tsx}"
+description: Argsbarg schema — read framework docs before editing CLI commands
+globs: "src/**/commands/**/*.{ts,tsx},src/index.{ts,tsx}"
 alwaysApply: false
 ---
 
-**argsbarg** — `CliProgram` drives help, MCP, and skills. Full guide: `node_modules/argsbarg/docs/cli-program.md`.
+When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
 
-## Defaults
-- `mcpServer: { enabled: true }` for MCP; **omit `mcpTool`** unless an escape hatch is required
-- `description` on root, commands, options, and positionals (→ `-h`, MCP `inputSchema`, skills)
-- `satisfies CliProgram`; root: `key`, `version`, `description`
-- Reserved root commands (do not declare): `completion`, `install`, `mcp`, `version`, `docs`, `update`
+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`.
 
-## Schema
-- **Inline** options, positionals, and handler schema; extract to `export const …Command = { … } satisfies CliLeaf` (or router type) when shared flags, `mcpTool` spreads, or large handlers justify a module — not zero-arg wrapper functions
-- Leaf descriptions: action-oriented, not UI jargon
-- Prefer option names `yes`, `dry-run`, `json` when semantics match; describe non-interactive use on the option
+**Hard rules** (details and examples are in the docs above — do not contradict them):
 
-## `mcpTool` (rare)
-Fix schema/handler first — not for missing `--yes`, wrong flag names, or unfinished headless paths.
-Only: `enabled: false` (CLI-only), `requiresEnv`, or irreducible limits (e.g. streaming `--watch`). Comment why if used.
+- Reserved root commands: `completion`, `install`, `mcp`, `version`, `docs`, `update`.
+- `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.
+- 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.
 
-## Headless
-Interactive commands need one fast path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json`.
-- Mutators: `requireYesInNonTty`, `shouldRunHeadlessWithYes`
-- Queries: `shouldRunHeadless`, `wantsExplicitJson`
-- Varargs/positionals: `shouldRunHeadlessWithPositionals`
-- `ctx.invocation === "mcp"` only for subprocess/TTY wire behavior; use argsbarg headless helpers, not raw `isTTY`
+**App-specific conventions:** add below or in a separate `.cursor/rules/` file (shared flags path, Ink vs JSON-only, etc.).

package/index.d.ts

@@ -1,33 +1,5 @@
 // Generated by dts-bundle-generator v9.5.1
 
-/**
- * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
- */
-export declare class CliContext {
-	readonly appName: string;
-	readonly commandPath: string[];
-	readonly args: string[];
-	readonly program: CliProgram;
-	readonly opts: Record<string, string>;
-	readonly invocation: CliInvocation;
-	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation);
-	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
-	hasFlag(name: string): boolean;
-	/** Returns the string value for a string-valued option, if present. */
-	stringOpt(name: string): string | undefined;
-	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
-	numberOpt(name: string): number | null;
-	/**
-	 * Generic typed accessor: parses a stored string using the provided parse function.
-	 * This is the TypeScript-native advantage over the Swift version.
-	 */
-	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
-	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
-	positional(name: string): string | string[] | undefined;
-	private _posMap;
-	private _positionalMap;
-}
 /**
  * How a leaf handler was dispatched.
  */
@@ -45,6 +17,20 @@ export declare enum CliOptionKind {
 	/** Fixed set of allowed string values. Requires non-empty `choices` on the option. */
 	Enum = "enum"
 }
+/**
+ * Named validation/coercion for string options (`format` on `CliOption`).
+ * Positionals do not use `format`; varargs use space-separated CLI tokens and JSON arrays over MCP.
+ */
+export declare enum CliValueFormat {
+	/** Duration text such as `30s`, `20m`, `1h`, `2d` (default unit minutes when omitted). */
+	Duration = "duration",
+	/** Comma-separated list on a single option value (`--services a,b`). */
+	CommaList = "comma-list",
+	/** Calendar date `YYYY-MM-DD`. */
+	Date = "date",
+	/** RFC 3339 instant with `Z` or numeric offset. */
+	DateTime = "date-time"
+}
 /**
  * When `fallbackCommand` is used for missing or unknown subcommand tokens at a routing node.
  */
@@ -84,6 +70,15 @@ export interface CliOption {
 	 * Must be a non-empty array of distinct non-empty strings.
 	 */
 	choices?: string[];
+	/**
+	 * Named string validation for `kind: String` options. Mutually exclusive with `pattern`.
+	 * Not supported on positionals.
+	 */
+	format?: CliValueFormat;
+	/** Default value applied in post-parse when the option is omitted. */
+	default?: string;
+	/** Regex pattern for string options. Mutually exclusive with `format`. */
+	pattern?: string;
 }
 /**
  * An ordered positional argument slot, listed on leaf `positionals`.
@@ -308,30 +303,56 @@ export declare class CliSchemaValidationError extends Error {
 	/** Creates a schema validation error with a human-readable rule violation. */
 	constructor(message: string);
 }
-/** Outcome of a non-exiting CLI invocation. */
-export type CliInvokeKind = "ok" | "help" | "error";
-/** Result of cliInvoke: captured output and exit metadata without process.exit. */
-export interface CliInvokeResult {
-	/** Invocation outcome. */
-	kind: CliInvokeKind;
-	/** Simulated exit code. */
-	exitCode: number;
-	/** Captured stdout during handler execution. */
-	stdout: string;
-	/** Captured stderr during handler execution. */
-	stderr: string;
-	/** Set when kind === "error" (parse/validation message). */
-	errorMsg?: string;
-}
+/** Coerced leaf inputs keyed by option and positional names. */
+export type CliLeafInputs = Record<string, boolean | number | string | string[] | undefined>;
 /**
- * Parses argv against the user root, runs the leaf handler, and returns captured output.
- * Never calls process.exit.
+ * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
  */
-export declare function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult>;
-export declare function cliRun(program: CliProgram, argv?: string[]): Promise<never>;
-export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
-/** True when stdin is a TTY. */
-export declare const isInteractiveTty: boolean;
+export declare class CliContext {
+	readonly appName: string;
+	readonly commandPath: string[];
+	readonly args: string[];
+	readonly program: CliProgram;
+	readonly opts: Record<string, string>;
+	readonly invocation: CliInvocation;
+	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation);
+	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
+	hasFlag(name: string): boolean;
+	/** Returns the string value for a string-valued option, if present. */
+	stringOpt(name: string): string | undefined;
+	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
+	numberOpt(name: string): number | null;
+	/**
+	 * Generic typed accessor: parses a stored string using the provided parse function.
+	 * This is the TypeScript-native advantage over the Swift version.
+	 */
+	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
+	/** Duration option in milliseconds (post-parse validated). */
+	durationOpt(name: string): number | undefined;
+	/** Comma-list option as a string array (post-parse validated). */
+	commaListOpt(name: string): string[] | undefined;
+	/** Date option as canonical YYYY-MM-DD (post-parse validated). */
+	dateOpt(name: string): string | undefined;
+	/** Date-time option as normalized ISO 8601 UTC (post-parse validated). */
+	dateTimeOpt(name: string): string | undefined;
+	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
+	positional(name: string): string | string[] | undefined;
+	/** Reads coerced option and positional values for the current leaf from schema metadata. */
+	readLeafInputs(): CliLeafInputs;
+	private _readOptionValue;
+	private _leafNode;
+	private _posMap;
+	private _positionalMap;
+}
+/** Parses a duration string (e.g. 20m, 1h, 30s) into milliseconds. */
+export declare function parseDurationMs(durationStr: string): number;
+/** Splits a comma-separated string into trimmed non-empty tokens. */
+export declare function parseCommaList(s: string): string[];
+/** Returns canonical YYYY-MM-DD after validation. */
+export declare function parseDate(s: string): string;
+/** Returns normalized ISO 8601 UTC after validation. */
+export declare function parseDateTime(s: string): string;
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
 /** True when `--json` was passed or the handler was invoked via MCP. */
@@ -405,6 +426,26 @@ export declare function createGhVersionCheck(config: GhVersionCheckConfig): {
 };
 /** Shared `gh release view` fetcher for hooks and version-check refresh. */
 export declare function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string>;
+/** Outcome of a non-exiting CLI invocation. */
+export type CliInvokeKind = "ok" | "help" | "error";
+/** Result of cliInvoke: captured output and exit metadata without process.exit. */
+export interface CliInvokeResult {
+	/** Invocation outcome. */
+	kind: CliInvokeKind;
+	/** Simulated exit code. */
+	exitCode: number;
+	/** Captured stdout during handler execution. */
+	stdout: string;
+	/** Captured stderr during handler execution. */
+	stderr: string;
+	/** Set when kind === "error" (parse/validation message). */
+	errorMsg?: string;
+}
+/**
+ * Parses argv against the user root, runs the leaf handler, and returns captured output.
+ * Never calls process.exit.
+ */
+export declare function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult>;
 /** Resolved paths for `mcp bundle`. */
 export interface McpBundlePaths {
 	binaryPath: string;
@@ -425,5 +466,9 @@ export interface PackMcpBundleOpts {
  * Requires the compiled binary to exist.
  */
 export declare function packMcpBundle(program: CliProgram, opts?: PackMcpBundleOpts): string;
+export declare function cliRun(program: CliProgram, argv?: string[]): Promise<never>;
+export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
+/** True when stdin is a TTY. */
+export declare const isInteractiveTty: boolean;
 
 export {};