argsbarg 1.4.1 → 1.4.3

package/.cursor/plans/v1.3_parser_ergonomics_b3e91f02.plan.md

@@ -0,0 +1,455 @@
+---
+name: v1.3 — parser ergonomics
+overview: "Four targeted parser and DX improvements: nested fallbackCommand on any routing node, varargs + trailing options interleaved (fixes --flag after positionals), ctx.positional(name) named accessor, and MCP string→array coercion for varargs positionals."
+todos:
+  - id: types-jsdoc
+    content: "Step 1: Update JSDoc on fallbackCommand/fallbackMode to remove 'root-only' / 'top-level' language; no type changes needed"
+    status: completed
+  - id: validate-fallback
+    content: "Step 2: Remove root-only restriction on fallbackCommand/fallbackMode in validate.ts; add validation that fallbackCommand names a valid child key on any routing node"
+    status: completed
+  - id: parser-fallback
+    content: "Step 3: Extend routing loop to apply fallbackCommand/fallbackMode at non-root routing nodes (mirrors existing root logic)"
+    status: completed
+  - id: parser-varargs-trailing
+    content: "Step 4: Fix finishLeaf varargs loop to interleave known-option scanning instead of greedy-consuming all remaining tokens"
+    status: completed
+  - id: ctx-positional
+    content: "Step 5: Add ctx.positional(name) accessor to CliContext — named positional lookup computed from schema + commandPath + args"
+    status: completed
+  - id: mcp-coerce
+    content: "Step 6: Coerce string → string[] in mcpToolCallToArgv for varargs positionals (comma-split or single-item)"
+    status: completed
+  - id: tests
+    content: "Step 7: Unit + integration tests for all four features"
+    status: completed
+  - id: docs-changelog
+    content: "Step 8: Update README, CHANGELOG, docs/mcp.md; run just typegen and just test"
+    status: completed
+isProject: false
+---
+
+# v1.3 — parser ergonomics
+
+Four parser and DX improvements. No new runtime dependencies, no public API removals, no MCP protocol changes. All four were explicitly deferred from v1.2 and follow directly from consumer app feedback.
+
+---
+
+## Background
+
+From reading the current source before writing this plan:
+
+- **`fallbackCommand` types already support non-root** — `CliCommand` union allows `fallbackCommand` on any router node. The restriction is purely in `validate.ts` lines 39–52 (`!isRoot && cmd.fallbackCommand !== undefined → throw`). Parser fix is in the routing `while(true)` loop.
+- **Trailing options are already partially wired** — `finishLeaf` calls `consumeOptions` on the tail for bounded-arity positionals (see `allowsTrailingOptions`). The gap is varargs (`argMax === 0`): the greedy loop at line 289–304 consumes all remaining tokens before any trailing option scan can happen.
+- **`ctx.positional(name)`** — `CliContext` has `args: string[]` and `schema: CliCommand`. Named positional access can be computed from those; no parser change required.
+- **MCP string→array coercion** — `mcpToolCallToArgv` currently requires `args[pos.name]` to be `string[]` for varargs. Accepts only arrays; agents passing `"a,b"` or `"a"` silently fail.
+
+---
+
+## Implementation order
+
+1. JSDoc cleanup (no logic)
+2. Validation: remove root-only fallback restriction
+3. Parser: nested fallback routing
+4. Parser: varargs + trailing options interleaved
+5. `ctx.positional(name)`
+6. MCP string→array coercion
+7. Tests
+8. Docs + changelog
+
+Do steps 3 and 4 independently — they touch different parts of `parse.ts`. Step 3 is the routing loop; step 4 is `finishLeaf`. Both must pass existing tests before moving on.
+
+---
+
+## Step 1: JSDoc ([`src/types.ts`](src/types.ts))
+
+No type changes. Update JSDoc on the router branch of `CliCommand`:
+
+- `fallbackCommand`: change "Default **top-level** subcommand" → "Default subcommand"
+- `fallbackMode`: change "How fallbackCommand is applied" — add note that both fields work on any routing node, not just root
+
+---
+
+## Step 2: Validation ([`src/validate.ts`](src/validate.ts))
+
+### Remove root-only restriction
+
+Delete lines 39–52 entirely:
+```typescript
+// DELETE:
+if (!isRoot && cmd.fallbackCommand !== undefined) {
+  throw new CliSchemaValidationError(
+    "Fallback is only supported on the program root (not on " + cmd.key + ")",
+  );
+}
+if (!isRoot && cmd.fallbackMode !== undefined && ...) {
+  throw new CliSchemaValidationError(
+    "fallbackMode may only be set on the program root (not on " + cmd.key + ")",
+  );
+}
+```
+
+### Add fallbackCommand child validation (apply to ALL routing nodes, not just root)
+
+After the duplicate child name check (the `seenNames` loop), add:
+
+```typescript
+// fallbackMode without fallbackCommand is always invalid — check unconditionally
+if (cmd.fallbackMode !== undefined && cmd.fallbackCommand === undefined) {
+  throw new CliSchemaValidationError(
+    `fallbackMode requires fallbackCommand on '${cmd.key}'`,
+  );
+}
+
+if (cmd.fallbackCommand !== undefined) {
+  const children = cmd.commands ?? [];
+  const valid = children.find((c) => c.key === cmd.fallbackCommand);
+  if (!valid) {
+    throw new CliSchemaValidationError(
+      `fallbackCommand '${cmd.fallbackCommand}' is not a child of '${cmd.key}'`,
+    );
+  }
+}
+```
+
+**Note:** The existing root-level validation already does the child-lookup check implicitly via the runtime. Moving it into schema validation means it's caught at startup, not at dispatch time.
+
+---
+
+## Step 3: Parser — nested `fallbackCommand` ([`src/parse.ts`](src/parse.ts))
+
+The routing `while(true)` loop (line ~459) has two places where non-root routing nodes currently error. Both need fallback logic inserted before the error return.
+
+### Place 1: End of argv, current node has children (line ~485)
+
+Currently: `return helpResult(path, false)` when `current.commands.length > 0` and argv is exhausted.
+
+Add before that return:
+```typescript
+if ((current.commands ?? []).length > 0) {
+  const fb = current.fallbackCommand;
+  const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
+  if (
+    fb !== undefined &&
+    (fm === CliFallbackMode.MissingOnly || fm === CliFallbackMode.MissingOrUnknown)
+  ) {
+    const fbNode = findChild(current.commands ?? [], fb);
+    if (fbNode) {
+      path.push(fb);
+      current = fbNode;
+      continue;
+    }
+  }
+  return helpResult(path, false);
+}
+```
+
+### Place 2: Unknown subcommand token (line ~515–526)
+
+Currently: `return error "Unknown subcommand: tok"` when the token doesn't match any child.
+
+Add before that return:
+```typescript
+if ((current.commands ?? []).length > 0) {
+  const fb = current.fallbackCommand;
+  const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
+  const canRouteUnknown =
+    fb !== undefined &&
+    (fm === CliFallbackMode.MissingOrUnknown || fm === CliFallbackMode.UnknownOnly);
+
+  if (canRouteUnknown) {
+    const fbNode = findChild(current.commands ?? [], fb!);
+    if (fbNode) {
+      // Do NOT advance i — the unrecognized token stays as argv for the fallback
+      path.push(fb!);
+      current = fbNode;
+      continue;
+    }
+  }
+  return { kind: ParseKind.Error, ..., errorMsg: `Unknown subcommand: ${tok}` };
+}
+```
+
+This mirrors the root-level fallback logic at lines 406–452 exactly. The same `CliFallbackMode` semantics apply at every routing level.
+
+---
+
+## Step 4: Parser — varargs + trailing options ([`src/parse.ts`](src/parse.ts) — `finishLeaf`)
+
+### The problem
+
+`finishLeaf`'s varargs branch (line ~289–304):
+```typescript
+if (argMax === 0) {
+  while (idx < argv.length) {
+    args.push(argv[idx]);   // ← greedy: swallows --json and all flags
+    idx += 1;
+    count += 1;
+  }
+}
+```
+
+All remaining tokens (including `--flag` tokens) are consumed as positionals. The trailing option scan at lines 307–325 never runs because `idx === argv.length` after the greedy loop.
+
+### The fix
+
+Replace the greedy varargs loop with an interleaved loop that recognizes known options:
+
+```typescript
+if (argMax === 0) {
+  while (idx < argv.length) {
+    const tok = argv[idx];
+
+    // -- separator: force remaining tokens as positionals
+    if (!forcePositionals && tok === "--") {
+      forcePositionals = true;
+      idx++;
+      continue;
+    }
+
+    // Scoped help inside varargs tail — mirrors bounded path at lines 312–314
+    if (!forcePositionals && isHelpTok(tok)) {
+      return helpResult(path, true);
+    }
+
+    // Possible option token: attempt to consume as a known flag
+    if (!forcePositionals && tok.startsWith("-")) {
+      // MUST be false — lenient mode swallows unknown flags as positionals silently
+      const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
+      if (tailRep.report.err) {
+        return errorResult(tailRep.report.err);
+      }
+      if (tailRep.report.sawDoubleDash) {
+        forcePositionals = true;
+      }
+      if (tailRep.nextIndex > idx) {
+        // Consumed one or more options — loop without pushing a positional
+        idx = tailRep.nextIndex;
+        continue;
+      }
+      // consumeOptions stopped without advancing (unknown token in lenient mode
+      // would return stoppedOnUnknown, but we pass lenientUnknown=false, so
+      // any unknown -flag is already an error above). Fallthrough to error.
+      return errorResult(`Unexpected option token: ${tok}`);
+    }
+
+    // Plain positional token
+    args.push(tok);
+    idx++;
+    count++;
+  }
+}
+```
+
+**Key rules:**
+- `consumeOptions` is called with `lenientUnknown: false` — unknown flags in varargs tails are still errors, not silently treated as positionals
+- `--` terminates option scanning exactly as before; tokens after it go straight to `args`
+- Bounded positionals are unchanged — their existing trailing option scan at lines 307–325 still runs and is unaffected
+
+**Remove `allowsTrailingOptions`** — it becomes dead code once varargs interleaves. Delete the function and its call site.
+
+---
+
+## Step 5: `ctx.positional(name)` ([`src/context.ts`](src/context.ts))
+
+### Accessor
+
+```typescript
+/**
+ * Returns the value(s) for a named positional slot.
+ * Varargs slots (argMax === 0) return string[]; single slots return string | undefined.
+ */
+positional(name: string): string | string[] | undefined {
+  return this._positionalMap()[name];
+}
+```
+
+### Implementation (`_positionalMap`)
+
+Compute lazily and cache. Walk `this.schema` along `this.commandPath` to find the leaf, then map positional definitions to slices of `this.args`:
+
+```typescript
+private _posMap: Record<string, string | string[]> | undefined;
+
+private _positionalMap(): Record<string, string | string[]> {
+  if (this._posMap) return this._posMap;
+
+  let node: CliCommand = this.schema;
+  for (const seg of this.commandPath) {
+    const child = (node.commands ?? []).find((c) => c.key === seg);
+    if (!child) { this._posMap = {}; return {}; }
+    node = child;
+  }
+
+  const map: Record<string, string | string[]> = {};
+  let argIdx = 0;
+  for (const p of node.positionals ?? []) {
+    const { argMax = 1 } = p;
+    if (argMax === 0) {
+      map[p.name] = this.args.slice(argIdx);
+      argIdx = this.args.length;
+    } else {
+      const val = this.args[argIdx];
+      if (val !== undefined) map[p.name] = val;
+      argIdx++;
+    }
+  }
+
+  this._posMap = map;
+  return map;
+}
+```
+
+**Return type semantics:**
+- Varargs (`argMax === 0`) → always `string[]` (may be empty)
+- Single slot (`argMax === 1`) → `string` if present, `undefined` if optional and absent
+- Always consistent with `ctx.args` — `ctx.positional` is a named view over the same data
+
+**No changes to `ctx.args`** — existing handlers continue to work; this is purely additive.
+
+### Export
+
+Add `positional` to the public method list in JSDoc. No changes to `src/index.ts` needed — `CliContext` is already exported and consumers get the new method automatically.
+
+---
+
+## Step 6: MCP string→array coercion ([`src/mcp/tools.ts`](src/mcp/tools.ts) — `mcpToolCallToArgv`)
+
+### Current behavior (varargs positional)
+
+```typescript
+// Current:
+const val = args[pos.name];
+// assumes val is string[] — agents passing "a,b" or "a" get undefined behavior
+argv.push(...(val as string[]));
+```
+
+### Fix
+
+```typescript
+const raw = args[pos.name];
+let items: string[];
+if (Array.isArray(raw)) {
+  items = raw.map(String);
+} else if (typeof raw === "string") {
+  // Coerce: comma-split or single item
+  items = raw.includes(",")
+    ? raw.split(",").map((s) => s.trim()).filter(Boolean)
+    : raw.trim() ? [raw.trim()] : [];
+} else {
+  items = [];
+}
+argv.push(...items);
+```
+
+**`inputSchema` stays `{ type: "array", items: { type: "string" } }`** — array is the correct type for well-behaved agents. The coercion is a silent recovery from agents that pass strings anyway. Do not change the schema to `oneOf` — that complicates the JSON Schema unnecessarily.
+
+**Single string `"a"` → `["a"]`** (not comma-split). Comma is the delimiter only when present.
+
+---
+
+## Step 7: Tests ([`src/index.test.ts`](src/index.test.ts))
+
+### Nested `fallbackCommand` — unit tests
+
+1. Router node with `fallbackCommand` and empty argv → routes to fallback leaf.
+2. Router node with `fallbackCommand` + `MissingOrUnknown` + unknown token → routes to fallback (token stays in argv for fallback leaf).
+3. Router node with `fallbackCommand` + `MissingOnly` + unknown token → error "Unknown subcommand".
+4. `cliValidateRoot` rejects `fallbackCommand` naming a non-existent child on a non-root node.
+5. `cliValidateRoot` accepts `fallbackCommand` on a non-root router node when child exists.
+6. Scoped help: `myapp docs --help` on a router with fallback → shows docs subcommands, not fallback content.
+
+### Varargs + trailing options — unit tests
+
+7. `cliInvoke(root, ["read", "file.txt", "--json"])` where `read` has varargs positional and `--json` is a known option → `kind: "ok"`, `args: ["file.txt"]`, `opts: { json: "1" }`.
+8. `cliInvoke(root, ["read", "--json", "file.txt"])` → same result (option before varargs).
+9. `cliInvoke(root, ["read", "a.txt", "b.txt", "--json"])` → `args: ["a.txt", "b.txt"]`, `opts: { json: "1" }`.
+10. `cliInvoke(root, ["read", "file.txt", "--", "--json"])` → `args: ["file.txt", "--json"]`, `opts: {}` (`--` forces positional).
+11. `cliInvoke(root, ["read", "--unknown"])` → `kind: "error"`, errorMsg mentions `--unknown`.
+12. `parse(root, ["read", "file.txt", "--help"])` on a varargs leaf → `kind: Help`, `helpPath` contains `"read"` (scoped help, not an error). This guards the `isHelpTok` insertion.
+
+**Regression test inversion:** The existing test `"varargs tail does not parse trailing options"` (approximately line 337 in `index.test.ts`) currently *asserts the broken behavior* — `--json` ends up in `args`. Invert it: after Step 4, assert `--json` is in `opts` and absent from `args`. Do this as part of Step 7, not before.
+
+### `ctx.positional(name)` — unit tests
+
+13. Handler reads `ctx.positional("path")` on single-slot positional — returns the string value.
+14. Handler reads `ctx.positional("files")` on varargs positional — returns `string[]`.
+15. Handler reads `ctx.positional("opt")` on absent optional positional — returns `undefined`.
+16. `ctx.positional("files")` consistent with `ctx.args`: `ctx.positional("files")` deep-equals `ctx.args` when there is one varargs positional.
+
+### MCP string→array coercion — unit tests
+
+17. `mcpToolCallToArgv` with varargs positional: `args: { files: "a,b" }` → argv includes `"a"`, `"b"` as separate tokens.
+18. `mcpToolCallToArgv` with varargs positional: `args: { files: "a" }` (no comma) → argv includes `"a"` once.
+19. `mcpToolCallToArgv` with varargs positional: `args: { files: ["a","b"] }` (array) → unchanged behavior.
+20. `mcpToolCallToArgv` with varargs positional: `args: { files: "" }` (empty string) → no tokens appended.
+
+---
+
+## Step 8: Docs + changelog
+
+### [`README.md`](README.md)
+
+- Update `fallbackCommand` / `fallbackMode` table to note they work on any routing node.
+- Add `ctx.positional(name)` to the Reading values section.
+
+### [`docs/mcp.md`](docs/mcp.md)
+
+- Note MCP string→array coercion under tool arguments: agents may pass a comma-separated string for varargs positionals.
+
+### [`CHANGELOG.md`](CHANGELOG.md) — `[Unreleased]` → Added / Fixed
+
+**Added:**
+- `fallbackCommand` / `fallbackMode` now work on any routing node, not just the program root
+- `ctx.positional(name)` — named positional lookup; varargs return `string[]`, single slots return `string | undefined`
+- MCP varargs coercion: agents may pass `"a,b"` or `"a"` where `string[]` is expected
+
+**Fixed:**
+- Known options (`--flag`) after varargs positionals now parse correctly instead of being consumed as positional tokens
+
+### Typegen
+
+```
+just typegen
+```
+
+Verify `index.d.ts` reflects the new `positional` method on `CliContext`. No other new public types in this release.
+
+---
+
+## Pitfalls (do NOT)
+
+- Change `inputSchema` for varargs from `array` to `oneOf` — coercion is silent, schema stays canonical
+- Remove `ctx.args` — additive only; existing handlers must continue to work
+- Apply nested fallback logic before the existing root fallback — the root-level fallback code (lines 406–452 in `parse.ts`) stays as-is; the new code mirrors it in the routing loop body
+- Use `lenientUnknown: true` in the varargs interleaved option scan — unknown flags in varargs tails must still error
+- Break `allowsTrailingOptions` callers before deleting it — verify it has only one call site (line 308) before removing
+
+---
+
+## File change summary
+
+| File | Action |
+|------|--------|
+| [`src/types.ts`](src/types.ts) | JSDoc updates only |
+| [`src/validate.ts`](src/validate.ts) | Remove root-only fallback restriction; add child-key validation for all routing nodes |
+| [`src/parse.ts`](src/parse.ts) | Nested fallback in routing loop; varargs interleaved option scan; remove `allowsTrailingOptions` |
+| [`src/context.ts`](src/context.ts) | `positional(name)` accessor + `_positionalMap` private helper |
+| [`src/mcp/tools.ts`](src/mcp/tools.ts) | String→array coercion in `mcpToolCallToArgv` |
+| [`src/index.test.ts`](src/index.test.ts) | All new tests |
+| [`README.md`](README.md) | fallback + ctx.positional docs |
+| [`docs/mcp.md`](docs/mcp.md) | MCP coercion note |
+| [`CHANGELOG.md`](CHANGELOG.md) | Unreleased entries |
+| [`index.d.ts`](index.d.ts) | Regenerated via `just typegen` |
+
+---
+
+## Out of scope (explicitly deferred)
+
+- `ctx.positional` type overloads by argMax — return type is `string | string[] | undefined` for all slots; narrowing by schema type is possible but requires conditional types and adds complexity without clear benefit
+- `mcpTool.group` / `risk` / `requiresTty` annotations
+- `structuredError` for JSON on exit(1)
+- Streaming tool calls
+- Shared option groups / `extends`
+- Output truncation in MCP results
+- GNU-style option parsing before command routing (options mixed with subcommand tokens at root level)

package/.private/scratch.md

@@ -1 +1,2 @@
-- [x] --schema feature for ai agents
+- [x] --schema feature for ai agents
+- [ ] auto-generate/install a cursor skill  format for ~/.cursor/skills?

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.3] - 2026-06-19
+
+### Added
+
+- **`ai` built-in group** — `myapp ai skill cursor` and `myapp ai skill claude` install Agent Skills (`SKILL.md` + `reference.md`) to project or global skill directories.
+- **`aiSkill`** root config to opt out of skill install (`{ enabled: false }`).
+
+### Changed (breaking)
+
+- **`myapp mcp`** → **`myapp ai mcp`**
+- Reserved top-level command **`mcp`** → **`ai`** (user commands may now be named `mcp`)
+
+## [1.4.2] - 2026-06-19
+
+### Added
+
+- **`fallbackCommand` / `fallbackMode` on any routing node** — nested routers can define default subcommand routing, not just the program root.
+- **`ctx.positional(name)`** — named positional lookup; varargs return `string[]`, single slots return `string | undefined`.
+- **MCP varargs coercion** — agents may pass `"a,b"` or `"a"` where `string[]` is expected.
+
+### Fixed
+
+- **Known options after varargs positionals** — `--flag` tokens after a varargs tail parse as options instead of being consumed as positional arguments.
+
 ## [1.4.1] - 2026-06-19
 
 ### Added
@@ -111,7 +135,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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/v1.4.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.4.3...HEAD
+[1.4.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.3
+[1.4.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.2
 [1.4.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.1
 [1.4.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.0
 [1.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.3.1

package/README.md

@@ -16,7 +16,7 @@ Why another CLI parser?
 
 *Shell completions* — `completion bash` and `completion zsh` built-ins generate installable scripts from your schema so users get tab completion for commands, flags, and positionals without extra tooling.
 
-*Optional MCP server* — set `mcpServer: {}` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp mcp` over stdio). See [docs/mcp.md](docs/mcp.md).
+*Optional MCP server* — set `mcpServer: {}` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp ai mcp` over stdio). See [docs/mcp.md](docs/mcp.md). Install Cursor/Claude skills with `myapp ai skill cursor|claude` — see [docs/ai-skills.md](docs/ai-skills.md).
 
 *Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
@@ -96,19 +96,30 @@ Every app gets:
 - `-h` / `--help` at any routing depth (scoped help).
 - **`--schema`** at the program root — print the full command tree as JSON (for tooling and agents).
 - **`completion bash` / `completion zsh`** — print shell completion scripts to stdout (injected by `cliRun`).
-- **`mcp`** — when `mcpServer: {}` is set on the program root, run an MCP server over stdio (`myapp mcp`).
+- **`ai`** — AI agent integration: `ai mcp` (when `mcpServer` is set), `ai skill cursor`, `ai skill claude` (install agent skills; opt out with `aiSkill: { enabled: false }`).
 
 Do not declare a top-level command named **`completion`** — it is reserved for this built-in.
-Do not declare a top-level command named **`mcp`** — it is reserved when MCP is enabled.
+Do not declare a top-level command named **`ai`** — it is reserved for this built-in.
 Do not declare an option named **`schema`** — it is reserved for `--schema`.
 
 
 ### MCP (AI agents)
 
-Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `argsbarg://schema`. Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
+Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), then run `myapp ai mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `argsbarg://schema`. Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
 
 See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details.
 
+### Agent skills
+
+Install Cursor or Claude Code skills (command catalog + schema reference) with:
+
+```bash
+myapp ai skill cursor          # .cursor/skills/<name>/
+myapp ai skill claude --global # ~/.claude/skills/<name>/
+```
+
+See **[docs/ai-skills.md](docs/ai-skills.md)** for opt-out, flags, and file layout.
+
 
 ### Shell completions
 
@@ -132,7 +143,7 @@ bun add bun-argsbarg
 
 ## How it works
 
-1. Build a **program root** `CliCommand` using pure TypeScript objects: `key` is the app/binary name, `commands` are top-level subcommands, `options` are global flags. The root must not set `handler` or declare `positionals` (validated at startup). Use `fallbackCommand` / `fallbackMode` on the root only for default top-level routing.
+1. Build a **program root** `CliCommand` using pure TypeScript objects: `key` is the app/binary name, `commands` are top-level subcommands, `options` are global flags. The root must not set `handler` or declare `positionals` (validated at startup). 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**).
 3. From a handler, `cliErrWithHelp(ctx, "message")` prints a red error line plus contextual help on stderr and exits **1**.
 
@@ -144,7 +155,9 @@ bun add bun-argsbarg
 | `MissingOrUnknown` | Default command | Default command (token becomes argv for the default) |
 | `UnknownOnly` | Root help (exit 1) | Default command |
 
-With `MissingOrUnknown` / `UnknownOnly`, unrecognized **root** flags stop root-flag consumption and the remainder is passed to the default command.
+With `MissingOrUnknown` / `UnknownOnly`, unrecognized flags at the **current routing node** stop option consumption and the remainder is passed to the default command.
+
+Set `fallbackCommand` / `fallbackMode` on nested routers too — e.g. `docs` with `fallbackCommand: "guide"` routes `myapp docs` to the guide leaf without requiring a root-level default.
 
 ### Positionals (help labels)
 
@@ -163,6 +176,7 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `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.args` — positional words in order as `string[]`.
+- `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.
 - `ctx.schema` — merged program root (`CliCommand`) for contextual help.
 
 

package/docs/ai-skills.md

@@ -0,0 +1,75 @@
+# Agent skills install
+
+ArgsBarg can install [Agent Skills](https://code.claude.com/docs/en/skills) content for **Cursor** and **Claude Code** from your CLI schema. Each install writes two files:
+
+| File | Purpose |
+| --- | --- |
+| `SKILL.md` | Frontmatter + command catalog, execution notes, pitfalls |
+| `reference.md` | Full `--schema` JSON export |
+
+Skills are **install-only** — there is no print-to-stdout mode, because the artifact is always a two-file directory.
+
+## Quick start
+
+```bash
+# Project skill (commit .cursor/skills/ with your repo)
+myapp ai skill cursor
+
+# User-wide Claude Code skill
+myapp ai skill claude --global
+```
+
+On success, one line is printed to **stderr** with the install path (not the skill body).
+
+## Opt-out
+
+Skill install is **enabled by default**. Opt out on the program root:
+
+```typescript
+const cli: CliCommand = {
+  key: "myapp",
+  description: "My app.",
+  aiSkill: { enabled: false },
+  commands: [/* ... */],
+};
+```
+
+Optional custom skill directory name:
+
+```typescript
+aiSkill: { name: "my-custom-skill" },
+```
+
+## Flags
+
+Available on `ai skill cursor` and `ai skill claude`:
+
+| Flag | Effect |
+| --- | --- |
+| `--global` | Install under the user skills directory instead of the project |
+| `--force` | Overwrite an existing skill directory |
+
+## Install locations
+
+| Target | Project (default) | `--global` |
+| --- | --- | --- |
+| Cursor | `.cursor/skills/<name>/` | `~/.cursor/skills/<name>/` |
+| Claude Code | `.claude/skills/<name>/` | `~/.claude/skills/<name>/` |
+
+`<name>` defaults to the sanitized program root `key` (same rules as MCP tool name segments).
+
+Do **not** install under `~/.cursor/skills-cursor/` — that path is reserved for Cursor built-ins.
+
+## MCP vs skills
+
+| Mechanism | Purpose |
+| --- | --- |
+| **`myapp ai mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
+| **`myapp ai skill cursor\|claude`** | Static discovery and conventions for agents |
+
+Generated `SKILL.md` recommends MCP when `mcpServer` is configured, and documents shell invocation as a fallback.
+
+## Related
+
+- [MCP server](mcp.md) — `mcpServer` config and `ai mcp` protocol
+- [README built-ins](../README.md#built-ins) — reserved command `ai`