stitchkit 0.111.3 → 0.112.0

package/CHANGELOG.md

@@ -15,6 +15,15 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.112.0] - 2026-10-24
+
+### ⚠️ Breaking changes
+
+**Who must act:** scripts that combine named array options with bare positional arguments without an explicit `positionals` policy must name the scalar fields or declare their destinations. Flag-only calls and explicitly declared positional policies need no migration.
+
+- `stitchkit/cli` — **array options require named arguments or an explicit positional policy.** Without a declared `positionals` policy, a named array option together with any bare positional is now a usage error before dispatch. Schema-order inference could mistake the array's remaining elements for unrelated optional fields and execute a different call. Before: `app resolve --references alpha.md beta.md gamma.md` could assign `beta.md` and `gamma.md` to other fields. After: `app resolve --references alpha.md --references beta.md --references gamma.md`, or `app resolve --references:='["alpha.md","beta.md","gamma.md"]'`. Name scalar fields with flags too, or declare their exact positional policy. Command help describes one element per option; only a declared trailing positional array is variadic. See [ADR 0268](docs/decisions/0268-named-cli-arrays-require-explicit-positional-destinations.md) and the [migration](docs/guide/upgrading.md).
+  **Affects:** `stitchkit/cli` createCli, parseCliArgs
+
 ## [0.111.3] - 2026-10-20
 
 ### Fixed

package/dist/entrypoints/cli.js

@@ -16,7 +16,7 @@ import {
   renderCliView2,
   pollUntilDone2,
   createCli2
-} from "../index-jprxv2an.js";
+} from "../index-bd7spznx.js";
 import"../index-fynr93w4.js";
 import"../index-ct75c3at.js";
 import"../index-h7accrrv.js";

package/dist/entrypoints/tools.js

@@ -74,7 +74,7 @@ import {
   WaitTimeoutError,
   runWaitOperation,
   createCli2
-} from "../index-jprxv2an.js";
+} from "../index-bd7spznx.js";
 import {
   ManagedFilePathSchema2,
   ManagedFileRefSchema2

package/dist/{index-jprxv2an.js → index-bd7spznx.js}

@@ -1102,6 +1102,12 @@ function resolveCliView(flags, ascending) {
 // src/tools/cli/args.ts
 function buildToolArgs(tokens, fields, fieldFor, declaredPositionals, allowUnknown) {
   const { flags, jsonFields, literalBooleanFlags, positionals } = tokens;
+  if (declaredPositionals === undefined && positionals.length > 0) {
+    const arrayFlag = [...flags.keys()].find((key) => fieldFor(key)?.kind === "array");
+    if (arrayFlag !== undefined) {
+      throw new CliArgumentError2(`--${arrayFlag} cannot be combined with automatic positional arguments. Repeat --${arrayFlag} for each element or use --${arrayFlag}:=JSON; name other fields with flags, or declare a positional policy.`);
+    }
+  }
   const toolArgs = {};
   const fillable = declaredPositionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...declaredPositionals];
   const variadicTail = declaredPositionals !== undefined && fields.get(fillable[fillable.length - 1] ?? "")?.kind === "array" ? fillable[fillable.length - 1] : undefined;
@@ -1660,7 +1666,7 @@ function typeLabel(schema) {
   if (Array.isArray(schema.enum))
     return schema.enum.join("|");
   if (schema.type === "array")
-    return "value…";
+    return "value";
   if (typeof schema.type === "string")
     return schema.type;
   return "value";
@@ -1822,6 +1828,13 @@ function renderCommandHelp(name, command, descriptor, applicationOptions = []) {
     if (flag !== undefined) {
       lines.push("", `A boolean flag is on alone or takes true/false: --${flag}, --${flag} false, --no-${flag}`);
     }
+    const arrays = [...kinds].filter(([, info]) => info.kind === "array");
+    for (const [field] of arrays) {
+      lines.push("", `Repeat --${field} <value> for each element, or assign the whole array with --${field}:=JSON.`);
+    }
+    if (arrays.length > 0 && descriptor.positionals === undefined) {
+      lines.push("Array options cannot be combined with automatic positional arguments; name other fields with flags.");
+    }
     lines.push("", ...jsonValueHelp(fields), "");
   }
   const applicationLines = applicationOptionLines(applicationOptions);

package/dist/tools/cli/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAMjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AA6GD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAsBf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAyDvB"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAMjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAwHD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAsBf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAyDvB"}

package/dist/tools/cli/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAkIvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAsCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CA6DR"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAkIvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAsCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CAyER"}

package/llms/cli.2.txt

@@ -281,7 +281,7 @@ SDK nor the `ai` peer.
 |--------|------|---------|
 | `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
-| `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical (advanced) |
+| `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical; named array options together with bare positionals require an explicit `positionals` policy (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |
 | `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
 | `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, including discovered MCP object guards restored from JSON Schema, without the `stitchkit/tools` barrel |

package/llms/cli.txt

@@ -247,6 +247,15 @@ string, the schema says what it should be:
 | `z.record(z.string(), z.unknown())` | `--data '{"code":"007"}'` or `--data.code=007` → `"007"` |
 | `.optional()` / `.default()` | not required                           |
 
+An array option takes **one value per occurrence**, never a bare list after the flag.
+Repeat it (`--tag a --tag b`) or assign the whole array (`--tag:='["a","b"]'`).
+Without an explicit command `positionals` policy, combining any named array option
+with bare positionals is refused before dispatch: schema-order inference could otherwise
+assign the remaining array elements to unrelated fields. This includes short aliases,
+dotted array leaves, whole-array JSON and tokens after `--`, regardless of token order.
+Name the scalar fields too, or declare their exact positional destinations. An explicitly
+declared trailing positional array is the variadic form described below.
+
 Use the inline `:=` form to assign a whole JSON value without scalar coercion:
 
 ```bash
@@ -522,7 +531,7 @@ Declared aliases render beside their canonical options, for example
 
 The argument table and `Application options:` show bounds from their JSON Schema,
 for example `<integer> [>=1, <=50]`, `<string> [length >=1, length <=12]`, and
-`<value…> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
+`<value> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
 and `<=` include the endpoint; a zero limit is displayed too. Only limits the
 schema declares are shown: the safe-integer range every `z.int()` carries is the
 type, not a bound, so a bare integer prints `<integer>`, `.min(1)` prints `>=1` and

package/llms/stitchkit.txt

@@ -85,12 +85,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 56 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 57 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 56 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 57 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -102,7 +102,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 56 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 57 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/{upgrading-0.101.0-0.111.0.txt → upgrading-0.103.0-0.112.0.txt}

@@ -1,14 +1,45 @@
-# Upgrading 0.101.0 → 0.111.0 — stitchkit docs slice
+# Upgrading 0.103.0 → 0.112.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.101.0 → 0.111.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.103.0 → 0.112.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.101.0 → 0.111.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.103.0 → 0.112.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.112.0
+
+**Who must act:** scripts using an array option together with bare positional arguments without a declared `positionals` policy, including calls to `parseCliArgs`.
+
+An array flag consumes one value. Automatic schema-order positionals cannot distinguish additional array elements from values intended for unrelated fields, so the combination is refused before any handler or stdin read. The rule is independent of token order, includes aliases, dotted array leaves and whole-array JSON, and `--` does not bypass it. See [ADR 0268](../decisions/0268-named-cli-arrays-require-explicit-positional-destinations.md).
+
+```sh
+# before: the last two words could populate unrelated fields
+app resolve --references alpha.md beta.md gamma.md
+# after: repeat the option or assign the whole array
+app resolve --references alpha.md --references beta.md --references gamma.md
+app resolve --references:='["alpha.md","beta.md","gamma.md"]'
+
+# before: even an intended scalar positional has an implicit destination
+app resolve project-one --references alpha.md
+# after: name it
+app resolve --projectId project-one --references alpha.md
+```
+
+Applications that intend positional syntax declare its destinations on the available command:
+
+```ts
+createCli({ ...config, positionals: { resolve: ['projectId'] } })
+// app resolve project-one --references alpha.md
+
+createCli({ ...config, positionals: { resolve: ['references'] } })
+// app resolve alpha.md beta.md gamma.md
+```
+
+A declared trailing array accepts all remaining positional elements. Giving that same field both a flag and positional elements remains an error. An empty policy accepts flags only. Policies still target exact available command names: a partial dynamic catalogue needs no policy for an unavailable command to enforce this admission rule.
+
 ## Released migration: 0.111.0
 
 **Who must act:** applications whose raw routes call `parseBody` on JSON larger than 1 MiB, and applications whose OAuth clients send `/register` or `/token` bodies larger than 64 KiB.
@@ -874,63 +905,3 @@ For archive inspection, replace ad hoc line parsing with `readDiagnosticJournal`
 from the same filesystem leaf. Handle its `frame | anomaly` stream explicitly;
 missing files, permissions and unsafe paths still throw. See the
 [journal guide](application-kernel.md#bounded-local-diagnostic-journal).
-
-## Released migration: 0.102.0
-
-### `view_file` receives an array, not an array encoded as text
-
-**Who must act:** callers sending `paths` as a JSON-encoded array string, or
-matching the former media-extension refusal for that input. Managed MCP,
-Agent and CLI surfaces now reject it as `VALIDATION_ERROR` before IO; raw MCP
-reports an input-validation error. Correct single paths and arrays need no change.
-
-```ts
-// Before
-{ paths: '["image.png"]' }
-// After
-{ paths: ['image.png'] }
-// One file may also be a string
-{ paths: 'image.png' }
-```
-
-The same rule applies to an array element containing another encoded array.
-Do not change generic string-union coercion: path strings remain strings.
-A legitimate filename such as `[preview].PNG` is still accepted. Local
-unsupported-extension errors now include the caller's path and extension;
-match the error code rather than the former generic message.
-
-## Released migration: 0.101.0
-
-### `TelegramInitDataUser` is `TelegramUser`
-
-**Who must act:** code that names the type `TelegramInitDataUser` from
-`stitchkit/telegram`. The record is the same; its name now says it is any
-Telegram user, since `parseTelegramUser(ctx.from)` returns it for a Bot API user
-too.
-
-```ts
-// Before
-import type { TelegramInitDataUser } from 'stitchkit/telegram'
-function ensureAccount(user: TelegramInitDataUser) {}
-// After
-import type { TelegramUser } from 'stitchkit/telegram'
-function ensureAccount(user: TelegramUser) {}
-```
-
-### `TELEGRAM_BOT_TOKEN_PATTERN` matches the secret half only
-
-**Who must act:** code that uses `TELEGRAM_BOT_TOKEN_PATTERN` to find or cut a
-whole token. It now matches what follows `<bot id>:`, so a masking replace keeps
-the bot's id — `123456:[redacted]`. Masking needs nothing any more: `redact` and
-every logger on it mask bot tokens by shape; remove the pattern from
-`sensitiveUrlPatterns`, and use `redactTelegramBotToken(text)` for a string of
-your own.
-
-```ts
-// Before
-createJsonLogger({ sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN] })
-text.replace(new RegExp(TELEGRAM_BOT_TOKEN_PATTERN.source, 'g'), '[redacted]')
-// After
-createJsonLogger({})
-redactTelegramBotToken(text)
-```

package/llms/{upgrading-0.61.0-0.73.0.txt → upgrading-0.61.0-0.74.0.txt}

@@ -1,14 +1,75 @@
-# Upgrading 0.61.0 → 0.73.0 — stitchkit docs slice
+# Upgrading 0.61.0 → 0.74.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.61.0 → 0.73.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.61.0 → 0.74.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.61.0 → 0.73.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.61.0 → 0.74.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.74.0
+
+One change, and it only reaches you if you catch a refusal the **client** raised — one it made while
+planning the request, before anything was sent. A server refusal is unchanged.
+
+### If you match on the text of a client-side refusal
+
+A missing path param, a missing scoped prefix key, a non-flat field in a `GET` input, a missing or
+invalid multipart file: each used to arrive as a plain `Error` carrying only a sentence. They now
+arrive as an `ApiError` in the same shape a server validation failure uses.
+
+```ts
+// before
+catch (e) {
+  if (/Missing path param/.test(e.message)) …
+}
+
+// after
+catch (e) {
+  if (e.code === 'VALIDATION_ERROR' && e.status === 0) …   // refused here, nothing was sent
+}
+// e.details.issues[0].path === 'id'
+```
+
+`status` is what separates the two worlds, and it is not new — `0` has always meant *this never
+reached the server*, as `REQUEST_ABORTED` and `REQUEST_TIMEOUT` already used it:
+
+| | `code` | `status` |
+|---|---|---|
+| the client refused your arguments | `VALIDATION_ERROR` | `0` |
+| the server refused your arguments | `VALIDATION_ERROR` | `400` |
+
+`details.issues` is the same `{ path, code, message }` array on both, so one rendering serves both —
+and `zodIssues` / `ZodIssueSummary` are now importable from `stitchkit` itself, not only from
+`stitchkit/server`.
+
+### If you are on `createHttpClient` and your call site relied on a synchronous throw
+
+This is the sharp one, because it is invisible in a diff. Those refusals used to be thrown
+**synchronously** on the Ky-backed client — before the call returned a promise — so
+`api.upload({}).catch(handler)` never reached the handler, while the same mistake on the bare-fetch
+client rejected normally. They now reject on both.
+
+```ts
+// before, on createHttpClient only
+try {
+  api.upload({})            // threw here
+} catch (e) { … }
+
+// after, on both transports
+await api.upload({}).catch(handler)
+```
+
+A `try/catch` around an `await`ed call keeps working. A `try/catch` around an un-awaited call no
+longer catches anything — which was already true on the other transport.
+
+Not a migration, but worth knowing: a missing multipart file used to be reported as
+`UNKNOWN_ERROR`, the code that means *this client cannot tell you what happened*, on the one refusal
+where it is certain nothing was sent. → ADR 0148 carries the reasoning, including why argument
+validation stays on the server.
+
 ## Released migration: 0.73.0
 
 Two breaking changes. Nothing you send to a server changed, and only one of these

package/llms/{upgrading-0.74.0-0.100.0.txt → upgrading-0.75.0-0.102.0.txt}

@@ -1,14 +1,74 @@
-# Upgrading 0.74.0 → 0.100.0 — stitchkit docs slice
+# Upgrading 0.75.0 → 0.102.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.74.0 → 0.100.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.75.0 → 0.102.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.74.0 → 0.100.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.75.0 → 0.102.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.102.0
+
+### `view_file` receives an array, not an array encoded as text
+
+**Who must act:** callers sending `paths` as a JSON-encoded array string, or
+matching the former media-extension refusal for that input. Managed MCP,
+Agent and CLI surfaces now reject it as `VALIDATION_ERROR` before IO; raw MCP
+reports an input-validation error. Correct single paths and arrays need no change.
+
+```ts
+// Before
+{ paths: '["image.png"]' }
+// After
+{ paths: ['image.png'] }
+// One file may also be a string
+{ paths: 'image.png' }
+```
+
+The same rule applies to an array element containing another encoded array.
+Do not change generic string-union coercion: path strings remain strings.
+A legitimate filename such as `[preview].PNG` is still accepted. Local
+unsupported-extension errors now include the caller's path and extension;
+match the error code rather than the former generic message.
+
+## Released migration: 0.101.0
+
+### `TelegramInitDataUser` is `TelegramUser`
+
+**Who must act:** code that names the type `TelegramInitDataUser` from
+`stitchkit/telegram`. The record is the same; its name now says it is any
+Telegram user, since `parseTelegramUser(ctx.from)` returns it for a Bot API user
+too.
+
+```ts
+// Before
+import type { TelegramInitDataUser } from 'stitchkit/telegram'
+function ensureAccount(user: TelegramInitDataUser) {}
+// After
+import type { TelegramUser } from 'stitchkit/telegram'
+function ensureAccount(user: TelegramUser) {}
+```
+
+### `TELEGRAM_BOT_TOKEN_PATTERN` matches the secret half only
+
+**Who must act:** code that uses `TELEGRAM_BOT_TOKEN_PATTERN` to find or cut a
+whole token. It now matches what follows `<bot id>:`, so a masking replace keeps
+the bot's id — `123456:[redacted]`. Masking needs nothing any more: `redact` and
+every logger on it mask bot tokens by shape; remove the pattern from
+`sensitiveUrlPatterns`, and use `redactTelegramBotToken(text)` for a string of
+your own.
+
+```ts
+// Before
+createJsonLogger({ sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN] })
+text.replace(new RegExp(TELEGRAM_BOT_TOKEN_PATTERN.source, 'g'), '[redacted]')
+// After
+createJsonLogger({})
+redactTelegramBotToken(text)
+```
+
 ## Released migration: 0.100.0
 
 ### watch capacity and session/live/delivery adoption
@@ -1026,64 +1086,3 @@ schema.
 `stitchkit/live`, the watch hub, the keyspace and the trust fence are all
 additive. Adopt them when you want them; the guide is
 [Live data](./live.md).
-
-## Released migration: 0.74.0
-
-One change, and it only reaches you if you catch a refusal the **client** raised — one it made while
-planning the request, before anything was sent. A server refusal is unchanged.
-
-### If you match on the text of a client-side refusal
-
-A missing path param, a missing scoped prefix key, a non-flat field in a `GET` input, a missing or
-invalid multipart file: each used to arrive as a plain `Error` carrying only a sentence. They now
-arrive as an `ApiError` in the same shape a server validation failure uses.
-
-```ts
-// before
-catch (e) {
-  if (/Missing path param/.test(e.message)) …
-}
-
-// after
-catch (e) {
-  if (e.code === 'VALIDATION_ERROR' && e.status === 0) …   // refused here, nothing was sent
-}
-// e.details.issues[0].path === 'id'
-```
-
-`status` is what separates the two worlds, and it is not new — `0` has always meant *this never
-reached the server*, as `REQUEST_ABORTED` and `REQUEST_TIMEOUT` already used it:
-
-| | `code` | `status` |
-|---|---|---|
-| the client refused your arguments | `VALIDATION_ERROR` | `0` |
-| the server refused your arguments | `VALIDATION_ERROR` | `400` |
-
-`details.issues` is the same `{ path, code, message }` array on both, so one rendering serves both —
-and `zodIssues` / `ZodIssueSummary` are now importable from `stitchkit` itself, not only from
-`stitchkit/server`.
-
-### If you are on `createHttpClient` and your call site relied on a synchronous throw
-
-This is the sharp one, because it is invisible in a diff. Those refusals used to be thrown
-**synchronously** on the Ky-backed client — before the call returned a promise — so
-`api.upload({}).catch(handler)` never reached the handler, while the same mistake on the bare-fetch
-client rejected normally. They now reject on both.
-
-```ts
-// before, on createHttpClient only
-try {
-  api.upload({})            // threw here
-} catch (e) { … }
-
-// after, on both transports
-await api.upload({}).catch(handler)
-```
-
-A `try/catch` around an `await`ed call keeps working. A `try/catch` around an un-awaited call no
-longer catches anything — which was already true on the other transport.
-
-Not a migration, but worth knowing: a missing multipart file used to be reported as
-`UNKNOWN_ERROR`, the code that means *this client cannot tell you what happened*, on the one refusal
-where it is certain nothing was sent. → ADR 0148 carries the reasoning, including why argument
-validation stays on the server.

package/llms/upgrading.txt

@@ -11,9 +11,9 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.101.0 → 0.111.0: `llms/upgrading-0.101.0-0.111.0.txt`
-- 0.74.0 → 0.100.0: `llms/upgrading-0.74.0-0.100.0.txt`
-- 0.61.0 → 0.73.0: `llms/upgrading-0.61.0-0.73.0.txt`
+- 0.103.0 → 0.112.0: `llms/upgrading-0.103.0-0.112.0.txt`
+- 0.75.0 → 0.102.0: `llms/upgrading-0.75.0-0.102.0.txt`
+- 0.61.0 → 0.74.0: `llms/upgrading-0.61.0-0.74.0.txt`
 - 0.44.0 → 0.60.0: `llms/upgrading-0.44.0-0.60.0.txt`
 - 0.37.0 → 0.37.0: `llms/upgrading-0.37.0.txt`
 

package/llms-full.txt

@@ -77,12 +77,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 56 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 57 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 56 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 57 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -94,7 +94,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 56 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 57 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -9941,6 +9941,15 @@ string, the schema says what it should be:
 | `z.record(z.string(), z.unknown())` | `--data '{"code":"007"}'` or `--data.code=007` → `"007"` |
 | `.optional()` / `.default()` | not required                           |
 
+An array option takes **one value per occurrence**, never a bare list after the flag.
+Repeat it (`--tag a --tag b`) or assign the whole array (`--tag:='["a","b"]'`).
+Without an explicit command `positionals` policy, combining any named array option
+with bare positionals is refused before dispatch: schema-order inference could otherwise
+assign the remaining array elements to unrelated fields. This includes short aliases,
+dotted array leaves, whole-array JSON and tokens after `--`, regardless of token order.
+Name the scalar fields too, or declare their exact positional destinations. An explicitly
+declared trailing positional array is the variadic form described below.
+
 Use the inline `:=` form to assign a whole JSON value without scalar coercion:
 
 ```bash
@@ -10216,7 +10225,7 @@ Declared aliases render beside their canonical options, for example
 
 The argument table and `Application options:` show bounds from their JSON Schema,
 for example `<integer> [>=1, <=50]`, `<string> [length >=1, length <=12]`, and
-`<value…> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
+`<value> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
 and `<=` include the endpoint; a zero limit is displayed too. Only limits the
 schema declares are shown: the safe-integer range every `z.int()` carries is the
 type, not a bound, so a bare integer prints `<integer>`, `.min(1)` prints `>=1` and
@@ -16193,6 +16202,37 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.112.0
+
+**Who must act:** scripts using an array option together with bare positional arguments without a declared `positionals` policy, including calls to `parseCliArgs`.
+
+An array flag consumes one value. Automatic schema-order positionals cannot distinguish additional array elements from values intended for unrelated fields, so the combination is refused before any handler or stdin read. The rule is independent of token order, includes aliases, dotted array leaves and whole-array JSON, and `--` does not bypass it. See [ADR 0268](../decisions/0268-named-cli-arrays-require-explicit-positional-destinations.md).
+
+```sh
+# before: the last two words could populate unrelated fields
+app resolve --references alpha.md beta.md gamma.md
+# after: repeat the option or assign the whole array
+app resolve --references alpha.md --references beta.md --references gamma.md
+app resolve --references:='["alpha.md","beta.md","gamma.md"]'
+
+# before: even an intended scalar positional has an implicit destination
+app resolve project-one --references alpha.md
+# after: name it
+app resolve --projectId project-one --references alpha.md
+```
+
+Applications that intend positional syntax declare its destinations on the available command:
+
+```ts
+createCli({ ...config, positionals: { resolve: ['projectId'] } })
+// app resolve project-one --references alpha.md
+
+createCli({ ...config, positionals: { resolve: ['references'] } })
+// app resolve alpha.md beta.md gamma.md
+```
+
+A declared trailing array accepts all remaining positional elements. Giving that same field both a flag and positional elements remains an error. An empty policy accepts flags only. Policies still target exact available command names: a partial dynamic catalogue needs no policy for an unavailable command to enforce this admission rule.
+
 ## Released migration: 0.111.0
 
 **Who must act:** applications whose raw routes call `parseBody` on JSON larger than 1 MiB, and applications whose OAuth clients send `/register` or `/token` bodies larger than 64 KiB.
@@ -23410,7 +23450,7 @@ SDK nor the `ai` peer.
 |--------|------|---------|
 | `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
-| `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical (advanced) |
+| `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical; named array options together with bare positionals require an explicit `positionals` policy (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |
 | `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
 | `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, including discovered MCP object guards restored from JSON Schema, without the `stitchkit/tools` barrel |

package/llms.txt

@@ -18,7 +18,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.8 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 44.6 KB → [llms/cli.2.txt](llms/cli.2.txt) 21.3 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 45.3 KB → [llms/cli.2.txt](llms/cli.2.txt) 21.4 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
@@ -64,9 +64,9 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 12.7 KB
-- **Upgrading 0.101.0 → 0.111.0**: [llms/upgrading-0.101.0-0.111.0.txt](llms/upgrading-0.101.0-0.111.0.txt) 46.9 KB
-- **Upgrading 0.74.0 → 0.100.0**: [llms/upgrading-0.74.0-0.100.0.txt](llms/upgrading-0.74.0-0.100.0.txt) 45.1 KB
-- **Upgrading 0.61.0 → 0.73.0**: [llms/upgrading-0.61.0-0.73.0.txt](llms/upgrading-0.61.0-0.73.0.txt) 41.2 KB
+- **Upgrading 0.103.0 → 0.112.0**: [llms/upgrading-0.103.0-0.112.0.txt](llms/upgrading-0.103.0-0.112.0.txt) 46.6 KB
+- **Upgrading 0.75.0 → 0.102.0**: [llms/upgrading-0.75.0-0.102.0.txt](llms/upgrading-0.75.0-0.102.0.txt) 44.8 KB
+- **Upgrading 0.61.0 → 0.74.0**: [llms/upgrading-0.61.0-0.74.0.txt](llms/upgrading-0.61.0-0.74.0.txt) 43.5 KB
 - **Upgrading 0.44.0 → 0.60.0**: [llms/upgrading-0.44.0-0.60.0.txt](llms/upgrading-0.44.0-0.60.0.txt) 43.9 KB
 - **Upgrading 0.37.0 → 0.37.0**: [llms/upgrading-0.37.0.txt](llms/upgrading-0.37.0.txt) 6.2 KB
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.111.3",
+  "version": "0.112.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",