argsbarg 1.4.0 → 1.4.2

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/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`ctx.invocation`** (`"cli"` or `"mcp"`) on `CliContext` for handler branching.
+- **`cliInvoke`** and `CliInvokeResult` exported from the public API.
+- **`CliOptionKind.Enum`** with `choices` — JSON Schema `enum`, shell completions, parse validation, help labels.
+- **`mcpTool.description`** — per-leaf MCP tool description override.
+- **`mcpTool.requiresEnv`** — env requirements in auto-generated descriptions; enforced at `tools/call` (empty string counts as absent).
+- **`mcpServer.resources`** — pluggable `CliMcpResource` items in `resources/list` and `resources/read`.
+- **`mcpServer.shellEnv`** — login-shell env captured at MCP server start; `PATH` always merged, other vars fill gaps in host env.
+- **`mcpServer.envFile`** — `.env` file loaded into `process.env` after `shellEnv` (warns on stderr if missing).
+
 ## [1.4.0] - 2026-06-19
 
 ### Added
@@ -98,7 +123,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.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.4.2...HEAD
+[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
 [1.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.3.0

package/README.md

@@ -78,7 +78,7 @@ await cliRun(cli);
 Everything you need for a first-class CLI:
 
 - **Nested subcommands** (`CliCommand` with `commands` for groups, `handler` for leaves)
-- **POSIX-style options** (`-x`, `--long`, `--long=value`)
+- **POSIX-style options** (`-x`, `--long`, `--long=value`) — kinds: presence, string, number, **enum** (`choices` array)
 - **Bundled presence flags** (`-abc`)
 - **Positional arguments and varargs tails** (`CliPositional` objects on `positionals`)
 - **Scoped help** at any routing depth (`-h` / `--help`)
@@ -105,9 +105,9 @@ 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`.
+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.
 
-See **[docs/mcp.md](docs/mcp.md)** for configuration, Cursor setup, tool naming, argument mapping, and protocol details.
+See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details.
 
 
 ### Shell completions
@@ -132,7 +132,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 +144,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 +165,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.
 
 
@@ -197,10 +200,11 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | Symbol | Role |
 | --- | --- |
 | `CliCommand`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
-| `CliOptionKind`, `CliFallbackMode` | Option kinds and root fallback behavior. |
+| `CliOptionKind`, `CliFallbackMode` | Option kinds (`Presence`, `String`, `Number`, `Enum`) and root fallback behavior. |
 | `CliSchemaValidationError` | Thrown when the static command tree violates schema rules. |
-| `CliContext` | Handler context (`ctx.flag`, `ctx.stringOpt`, `ctx.args`, …). |
+| `CliContext` | Handler context (`ctx.flag`, `ctx.stringOpt`, `ctx.args`, `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. |
 
 Reserved identifier (validated at startup): root command **`completion`**.