stitchkit 0.113.1 → 0.113.3

package/llms/cli.txt

@@ -213,9 +213,11 @@ const doctor = defineCliCommand({
 it the canonical JSON output is unchanged. `exitCode` classifies a successfully
 validated result and must return an integer in `0..255`; failed `ToolResult`
 envelopes and the application-wide `exitCodes` mapping remain authoritative for
-failures. A throwing callback, invalid status or non-string presenter becomes a
-normalized `INTERNAL_SERVER_ERROR`, never partial success output. Void native
-commands cannot declare either callback.
+failures. A throwing or invalid exit-status callback becomes a normalized
+`INTERNAL_SERVER_ERROR`. A throwing or non-string `present` preserves the validated
+result on stdout and reports `CLI_PRESENTATION_FAILED` separately, as described
+under [Aggregate views](#aggregate-views). Void native commands cannot declare
+either callback.
 
 `--version`, a selected native command and its command help run before
 `resolveAuth`, services, context or runtime-tool factories. Top-level help is
@@ -430,6 +432,7 @@ newline-terminated JSON record on its respective stream; progress and CLI usage
 diagnostics remain ordinary stderr text. This keeps stdout pipeable and
 `2>/dev/null` clean. The process exit code carries the error class (`0` ok,
 `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
+`CLI_PRESENTATION_FAILED → 8`,
 …) — override per app with `exitCodes`.
 
 ### A narrower question than "all of them"
@@ -490,13 +493,42 @@ command name — validated against the declared schema, and kept out of every
 operation's arguments: `handoff_read` above receives `{ handoffId: 'u' }` and
 nothing else. The values reach `resolveAuth(globals)`, `context(auth, globals)`
 and a native command's `globals`. An invalid value is an argument error naming
-the flag; a name that collides with a framework option, or with a field of any
-command, is refused at startup rather than shadowing it silently. Past a bare
+the flag. An application global that collides with a framework option is refused
+at startup. Field collisions in authored commands are configuration errors;
+runtime catalogue entries are isolated as described below. Past a bare
 `--` every token is a literal, so a positional value that reads like a global
 survives intact.
 
 Both help levels list them under `Application options:`.
 
+## When one runtime command cannot be represented in argv
+
+A `runtimeTools` catalogue can change independently of the CLI application. An
+entry whose input declares a framework option such as `json`, or a field shadowed
+by an application global such as `caller`, cannot receive that field through argv.
+Only that entry becomes unavailable. Other commands still run, and top-level,
+filtered and command-specific help retain the entry and its full reason:
+
+```text
+  inspect  Inspect an operation [unavailable]
+    Unavailable: [stitchkit] CLI command "inspect" declares field(s) shadowed by application global options: caller
+```
+
+Calling it returns `CLI_COMMAND_UNAVAILABLE`, `retryable: false`, and the same
+reason in `details.message` on stderr; the default exit code is 1. `--json`
+compacts the error as usual; `exitCodes` and `errorHint` apply. The refusal precedes
+command argument parsing, stdin, context, hooks and the handler; `--dry-run` cannot
+turn it into success. A known unavailable `--wait` target returns the same refusal;
+an unknown target keeps `NOT_FOUND`.
+
+This isolates only reserved/global **field** conflicts in `runtimeTools`.
+Native commands and contract-defined `services` still fail at startup for those
+conflicts. Duplicate or reserved command names and invalid local aliases,
+positionals or passthrough policies remain configuration errors for every entry.
+`createCliInvoker` receives globals and command input separately and has no argv
+projection, so its own `caller` or `json` input stays callable without renaming.
+See [ADR 0273](../decisions/0273-a-runtime-cli-field-conflict-is-one-commands-unavailability.md).
+
 ## When the managed surface cannot resolve
 
 A CLI whose commands come from a running server declares them with a factory,
@@ -622,7 +654,7 @@ would answer a question nobody asked.
 
 Three rules worth knowing before you rely on them:
 
-- **A field the result does not carry is an argument error.** A group of zero
+- **A field the result does not carry is a presentation error.** A group of zero
   over a misspelled field is indistinguishable from a true empty answer, and the
   caller reads it as data. The message names the fields that *are* there.
 - **An aggregate needs a collection** — the result itself when it is an array,
@@ -636,6 +668,17 @@ Three rules worth knowing before you rely on them:
 A failed call still reports its own error and exit code. An aggregate over an
 error is not an answer to the question that was asked.
 
+If the command succeeds but its requested view cannot be built, the CLI writes
+the complete original result to stdout, using the normal JSON format (`--json`
+still selects compact output). It writes a separate structured
+`CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`, configurable
+through `exitCodes`. Its `details.operationSucceeded: true` and `retryable: false`
+distinguish a presentation refusal from a failed operation; `details.cause`
+preserves the safe reason. Recover the answer from stdout instead of repeating
+the mutation. Domain retry hints are not appended to this diagnostic. CLI
+argument errors detected before execution still exit with `2`
+and have no successful result to preserve.
+
 ## Named profiles
 
 A CLI that talks to a deployed server needs an address and a credential per
@@ -681,284 +724,3 @@ await createCli({
 Files are written `0600` in a `0700` directory — and a profile file other users
 can read is refused with the `chmod` that fixes it, because it holds a
 credential.
-
-## Distribution and self-update
-
-`createCli` ships no executable, and that is right — but the step after the
-executable is not application logic either. It is the same problem for every
-consumer, with the same three traps:
-
-1. **The installer cannot parse the manifest.** A `curl … | sh` runs on a
-   machine where nothing is installed yet, including `jq`. So the installer is
-   generated *from* the manifest, server-side, with the URL and digest already
-   substituted — it parses no JSON at all.
-2. **Replacing a running binary is a rename, not a write.** Anything else can
-   leave a half-written executable on someone's PATH when the connection drops.
-3. **The digest covers the decompressed bytes** — the file that will actually be
-   executed, not the archive that was transferred.
-
-The framework owns the manifest shape, the installer generation and the update
-primitive. The application owns where the assets live, which platforms it
-publishes and who may download them.
-
-```ts
-import {
-  CliBuildManifestSchema, assertCliPublishable, renderCliInstaller,
-  selectCliBuildAsset, checkCliUpdate, applyCliUpdate,
-} from 'stitchkit/cli'
-
-// Publishing: refuse to republish one version from a different commit —
-// otherwise everyone who already installed it never receives the fix.
-assertCliPublishable(previous, next)
-
-// Serving: omit `asset` and one script covers every published target, selecting
-// by uname at run time — otherwise that dispatch is the last hand-written piece
-// of the install path, and every publisher writes the same x86_64 → x64 table.
-renderCliInstaller({ manifest, binaryName: 'myapp' })
-// Or pin one target explicitly:
-renderCliInstaller({ manifest, asset: selectCliBuildAsset(manifest, target), binaryName: 'myapp' })
-
-// Checking: bounded, at most once per interval, silent on any failure.
-const check = await checkCliUpdate({ manifestUrl, currentVersion, lastCheckedAt })
-if (check.status === 'outdated' && check.asset) {
-  // Replacing is always an explicit command, never a side effect of a check.
-  await applyCliUpdate({ asset: check.asset })
-}
-```
-
-`checkCliUpdate` has **four** answers, not three: `skipped`, `current`,
-`outdated` and `unknown`. "Could not ask" is not "up to date" — collapsing them
-is how a tool goes quiet about its own staleness for months. It never throws,
-and a command still exits with the code it earned.
-
-Carry the build stamp inside the binary (`CliBuildStampSchema`,
-`formatCliBuildStamp`) so the tool can say what it is rather than leaving the
-reader to infer it from behaviour.
-
-#### A manifest inside your own network
-
-The check goes through the same SSRF boundary every outbound fetch does, so a
-manifest served from `10.x`, `localhost` or a `.internal` name is refused and
-the answer is `unknown`. For a self-hosted deployment that is a wrong answer
-dressed as a careful one, and the refusal says so — it names the field that
-lifts it rather than reading like a timeout:
-
-```text
-refusing to fetch an internal host — the manifest endpoint is not public.
-Set `allowPrivateHosts` if it is your own deployment; the download keeps its
-own setting, because an asset URL comes from the document.
-```
-
-```ts
-const check = await checkCliUpdate({ manifestUrl, currentVersion, allowPrivateHosts: true })
-```
-
-Set it from whether **your** endpoint is private, not as a blanket switch, and
-leave `applyCliUpdate` at its default. The two are not the same decision: the
-manifest URL is configuration you wrote, while an asset URL arrives inside a
-document the endpoint served, and a document is exactly what an SSRF boundary
-exists to distrust.
-
-### Publishing a complete version
-
-`publishCli` is an opt-in publisher for a local application-owned distribution
-directory. It commits every target and its version manifest before atomically
-replacing the public `manifest.json`. It ships from its own evolving entrypoint,
-`stitchkit/cli/publish`: release infrastructure follows how distributions are
-published, so it is not held to the stable promise of `stitchkit/cli`
-([ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md)). The
-manifest, signatures, installer and updater it writes for stay in
-`stitchkit/cli`. Your application selects the CLI source identity and admits
-that snapshot at each phase:
-
-```ts
-import { publishCli } from 'stitchkit/cli/publish'
-
-const result = await publishCli({
-  storageRoot: '/srv/myapp/cli',
-  name: 'myapp', version: cliVersion, commit: selectedCliCommit,
-  baseUrl: 'https://downloads.example.com/cli/',
-  targets: [{ platform: 'linux', arch: 'x64' }],
-  signal,
-  admit: ({ phase, identity, signal }) => assertSelectedSource({ phase, identity, signal }),
-  build: ({ target, stamp, signal }) => compileSelectedSource({ target, stamp, signal }),
-})
-// result.outcome: 'published' | 'existing'; result.manifest is ready to serve.
-```
-
-The builder returns `Uint8Array` or `ReadableStream<Uint8Array>` containing the
-executable. Every target receives the same immutable `{ version, commit,
-builtAt }` stamp; carry it inside the binary. The publisher owns staging,
-gzip assets, paths and manifests. Callbacks receive the cancellation signal and
-run under the publication lock. Admission phases are `prepare`, each target's
-`build`, `commit`, and `promote`; validate the selected source through commit
-and promotion. A backend release can explicitly select an unchanged older CLI
-identity. The helper never substitutes a different commit or rebuilds an
-existing version under a new identity.
-
-Assets live at `<version>/<name>-<platform>-<arch>.gz`, with an immutable
-`<version>/manifest.json` and a public `manifest.json`. A verified repeat keeps
-the exact bytes and `builtAt`, requires the same target set and base URL, and
-returns `existing` without invoking the builder. A version committed before a
-failed promotion is recovered and promoted without rebuilding. Conflicting
-same-version commits, downgrades, unsafe components, corrupt manifests and
-assets are refused. Version/name/target components are validated before any
-build; `storageRoot` is absolute and its existing parent must be trusted.
-
-All limits are finite positive safe integers; `limits` overrides these defaults:
-
-| Field | Default | Enforced boundary |
-| --- | --- | --- |
-| `maxTargets` | 16 | Requested and verified target count |
-| `maxManifestBytes` | 256 KiB | Read and written manifest bytes |
-| `maxAssetBytes` | 256 MiB | Builder and decompressed executable bytes |
-| `maxCompressedBytes` | 256 MiB | Archived asset bytes |
-| `maxDirectoryEntries` | 128 | Version layout, root scan and commit space |
-| `maxStoredVersions` | 16 | Verified publisher-owned history |
-| `lockTimeoutMs` | 10,000 | Wait to acquire the lock |
-| `timeoutMs` | 600,000 | Whole publication deadline |
-
-`retention` defaults to 2 and keeps the current and previous published versions.
-It must be at least 2 and less than `maxStoredVersions` (at least 3), leaving a
-recovery slot. Older versions are pruned only after their own identity, exact
-layout, raw size and digest are verified. Runtime folders and foreign semver
-directories remain untouched. A full or unverifiable store refuses further
-publication; repeated completed candidates stay inside the owned history cap.
-Cancelled or failed incomplete staging is removed only while its root and
-directory generations still match. The shared asynchronous gzip decoder also
-bounds updater expansion by the declared raw size and configured byte cap.
-
-The publisher rejects symlink roots/versions/assets, non-regular files and
-multiply linked files, and checks held-lock, root and prior-pointer generations
-before commit and promotion. This is cooperative publication under a trusted
-parent directory. Portable path checks do not provide an atomic comparison with
-a hostile process replacing ancestors between syscalls. Durability uses file
-and directory sync on POSIX; Windows publication is refused. A deadline stops
-callback/stream waits and blocks late promotion; trusted callbacks remain
-responsible for cancelling their own subprocesses and external effects.
-
-A failure after an immutable commit reports that the publication outcome must
-be checked. A failure after public-pointer rename may already have published;
-`AtomicFilePublicationError.published` remains available when the atomic writer
-reports that boundary. Read the durable manifest and retry the admitted same
-identity to recover; an error does not promise rollback. Optional `signing` and
-`trust` reuse the Ed25519 contract below. The generated shell installer checks
-raw digest and size; the updater checks manifest authorship when given a trust
-root.
-
-### Proving who built it — signing the manifest
-
-The asset digest proves the bytes that arrived are the bytes the manifest named.
-It proves nothing about who named them: the manifest and the assets come from
-one origin, so whoever can replace one can replace the other. Authorship needs a
-key the build carries and the server never holds.
-
-```ts
-// Publishing — the only side that holds a private key.
-const signature = signCliManifest(manifest, { keyId: 'release-2026', privateKey })
-publish({ ...manifest, signature })
-
-// Installing — the trust root is compiled into the binary. One fetched at run
-// time from the same origin as the manifest would prove nothing.
-const trust = { keys: { 'release-2026': PUBLISHED_KEY } }
-const check = await checkCliUpdate({ manifestUrl, currentVersion, trust })
-if (check.status === 'outdated' && check.asset) {
-  await applyCliUpdate({ asset: check.asset, manifest: check.manifest, trust, backupPath })
-}
-```
-
-The signature covers `{name, version, commit, builtAt, assets[]}` with **every
-asset's digest**, so the chain closes on the file that will execute rather than
-on the document describing it; moving an asset to a new URL does not invalidate
-it, changing what an asset contains does.
-
-Five verdicts, and `unenforced` is the one that earns its keep: a build with no
-pinned key keeps updating, and the fact that nothing was checked is *visible*
-rather than assumed. `missing`, `unknown-key` and `invalid` are distinguished
-because they need different answers — a key you forgot to pin is not a forged
-signature.
-
-A bad verdict does not produce a fifth status. `outdated` is an instruction to
-install, and a manifest that failed its signature has not established that there
-is a newer build worth installing — only that a document claims one. The check
-answers `unknown` with the verdict in its reason, so it is never mistaken for a
-network failure. `applyCliUpdate` checks again and refuses **before** the
-download: a signature verified after the bytes are on the machine produces a
-cleanup problem rather than a refusal.
-
-### A way back — `backupPath` and `rollbackCliUpdate`
-
-Rolling back is a property of updating, not of the application:
-
-```ts
-const applied = await applyCliUpdate({ asset, targetPath, backupPath })
-// …the new build turns out to be wrong. `backupSha256` is absent when there was
-// nothing to keep — a first install — and that is the case with nothing to roll
-// back to:
-if (applied.backupSha256) {
-  rollbackCliUpdate({ targetPath, backupPath, expectedSha256: applied.backupSha256 })
-}
-```
-
-The copy is taken between "the new bytes verified" and the replacement — earlier
-would preserve a binary about to be replaced by a download that then failed its
-digest, later has nothing left to copy — and it carries the target's file mode,
-because a backup that cannot be executed is not a way back. A first install has
-nothing to keep, which is not a failure.
-
-`expectedSha256` is required, not optional. A rollback that installs whatever
-happens to be at the backup path is a second install of an unverified binary,
-and the day it is used is the day nobody is in a position to check.
-
-### Run it before it replaces anything — `verify`
-
-A digest proves the bytes are the ones published, not that they load. A tool
-that updates itself unattended — a daemon — and installs a build that does not
-start takes its own updater down with it, and every machine is then repaired by
-hand. `verify` is the step between "digest matched" and "target replaced":
-
-```ts
-await applyCliUpdate({
-  asset, targetPath, backupPath,
-  verify: async (candidate, signal) => {
-    const child = Bun.spawn(['bun', candidate, 'version'], { signal, stdout: 'pipe' })
-    const printed = (await new Response(child.stdout).text()).trim()
-    if ((await child.exited) !== 0 || printed !== check.version) {
-      throw new Error(`printed ${printed}, expected ${check.version}`)
-    }
-  },
-  verifyTimeoutMs: 15_000,   // default 30 000
-})
-```
-
-The verified bytes are written beside the target as an executable candidate
-with the target's extension, and `verify` gets its path — a path rather than a
-command, because a JavaScript bundle is started through its runtime. It runs
-before the backup and the replacement. If it throws or outlives
-`verifyTimeoutMs` (its `signal` aborts at the deadline), the candidate is
-removed, the target and any earlier backup are untouched, and the update is
-refused with the reason as its cause. The target is written from the checked
-bytes in memory, never from the candidate file, so nothing the candidate did
-while it ran can change what is installed.
-
-### Two release tracks
-
-`assertCliPublishable` takes one manifest **or every manifest already
-published**:
-
-```ts
-assertCliPublishable([stableManifest, betaManifest], next)
-```
-
-With a single argument and two tracks the check is silently useless: `1.2.3`
-goes to beta from one commit and to stable from another, the function is called
-with the track being published and sees no conflict, and the person who
-installed the beta is told they are current forever. Nothing on their machine
-looks wrong.
-
-**The channel itself is not an argument of the framework, and will not become
-one.** The framework has no model of how your URLs are built and should not: an
-asset's address comes from the manifest, and the manifest's address belongs to
-your server. A channel is two documents at two addresses — which of them a build
-consults is your decision, and `assertCliPublishable` is told about all of them
-rather than taught the shape of any.

package/llms/server.4.txt

@@ -553,7 +553,7 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
-`WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `CLI_PRESENTATION_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
 `CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,

package/llms-full.txt

@@ -10012,9 +10012,11 @@ const doctor = defineCliCommand({
 it the canonical JSON output is unchanged. `exitCode` classifies a successfully
 validated result and must return an integer in `0..255`; failed `ToolResult`
 envelopes and the application-wide `exitCodes` mapping remain authoritative for
-failures. A throwing callback, invalid status or non-string presenter becomes a
-normalized `INTERNAL_SERVER_ERROR`, never partial success output. Void native
-commands cannot declare either callback.
+failures. A throwing or invalid exit-status callback becomes a normalized
+`INTERNAL_SERVER_ERROR`. A throwing or non-string `present` preserves the validated
+result on stdout and reports `CLI_PRESENTATION_FAILED` separately, as described
+under [Aggregate views](#aggregate-views). Void native commands cannot declare
+either callback.
 
 `--version`, a selected native command and its command help run before
 `resolveAuth`, services, context or runtime-tool factories. Top-level help is
@@ -10229,6 +10231,7 @@ newline-terminated JSON record on its respective stream; progress and CLI usage
 diagnostics remain ordinary stderr text. This keeps stdout pipeable and
 `2>/dev/null` clean. The process exit code carries the error class (`0` ok,
 `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
+`CLI_PRESENTATION_FAILED → 8`,
 …) — override per app with `exitCodes`.
 
 ### A narrower question than "all of them"
@@ -10289,13 +10292,42 @@ command name — validated against the declared schema, and kept out of every
 operation's arguments: `handoff_read` above receives `{ handoffId: 'u' }` and
 nothing else. The values reach `resolveAuth(globals)`, `context(auth, globals)`
 and a native command's `globals`. An invalid value is an argument error naming
-the flag; a name that collides with a framework option, or with a field of any
-command, is refused at startup rather than shadowing it silently. Past a bare
+the flag. An application global that collides with a framework option is refused
+at startup. Field collisions in authored commands are configuration errors;
+runtime catalogue entries are isolated as described below. Past a bare
 `--` every token is a literal, so a positional value that reads like a global
 survives intact.
 
 Both help levels list them under `Application options:`.
 
+## When one runtime command cannot be represented in argv
+
+A `runtimeTools` catalogue can change independently of the CLI application. An
+entry whose input declares a framework option such as `json`, or a field shadowed
+by an application global such as `caller`, cannot receive that field through argv.
+Only that entry becomes unavailable. Other commands still run, and top-level,
+filtered and command-specific help retain the entry and its full reason:
+
+```text
+  inspect  Inspect an operation [unavailable]
+    Unavailable: [stitchkit] CLI command "inspect" declares field(s) shadowed by application global options: caller
+```
+
+Calling it returns `CLI_COMMAND_UNAVAILABLE`, `retryable: false`, and the same
+reason in `details.message` on stderr; the default exit code is 1. `--json`
+compacts the error as usual; `exitCodes` and `errorHint` apply. The refusal precedes
+command argument parsing, stdin, context, hooks and the handler; `--dry-run` cannot
+turn it into success. A known unavailable `--wait` target returns the same refusal;
+an unknown target keeps `NOT_FOUND`.
+
+This isolates only reserved/global **field** conflicts in `runtimeTools`.
+Native commands and contract-defined `services` still fail at startup for those
+conflicts. Duplicate or reserved command names and invalid local aliases,
+positionals or passthrough policies remain configuration errors for every entry.
+`createCliInvoker` receives globals and command input separately and has no argv
+projection, so its own `caller` or `json` input stays callable without renaming.
+See [ADR 0273](../decisions/0273-a-runtime-cli-field-conflict-is-one-commands-unavailability.md).
+
 ## When the managed surface cannot resolve
 
 A CLI whose commands come from a running server declares them with a factory,
@@ -10421,7 +10453,7 @@ would answer a question nobody asked.
 
 Three rules worth knowing before you rely on them:
 
-- **A field the result does not carry is an argument error.** A group of zero
+- **A field the result does not carry is a presentation error.** A group of zero
   over a misspelled field is indistinguishable from a true empty answer, and the
   caller reads it as data. The message names the fields that *are* there.
 - **An aggregate needs a collection** — the result itself when it is an array,
@@ -10435,6 +10467,17 @@ Three rules worth knowing before you rely on them:
 A failed call still reports its own error and exit code. An aggregate over an
 error is not an answer to the question that was asked.
 
+If the command succeeds but its requested view cannot be built, the CLI writes
+the complete original result to stdout, using the normal JSON format (`--json`
+still selects compact output). It writes a separate structured
+`CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`, configurable
+through `exitCodes`. Its `details.operationSucceeded: true` and `retryable: false`
+distinguish a presentation refusal from a failed operation; `details.cause`
+preserves the safe reason. Recover the answer from stdout instead of repeating
+the mutation. Domain retry hints are not appended to this diagnostic. CLI
+argument errors detected before execution still exit with `2`
+and have no successful result to preserve.
+
 ## Named profiles
 
 A CLI that talks to a deployed server needs an address and a credential per
@@ -13068,7 +13111,7 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
-`WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `CLI_PRESENTATION_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
 `CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
@@ -23593,7 +23636,7 @@ SDK nor the `ai` peer.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
+| `createCli` | function | build and run a CLI from contracts; a runtime catalogue field conflicting with reserved/global argv options disables only that entry, retained in help with its reason; invocation returns `CLI_COMMAND_UNAVAILABLE` before side effects — [guide](../guide/cli.md#when-one-runtime-command-cannot-be-represented-in-argv) |
 | `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; 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) |

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.9 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 45.3 KB → [llms/cli.2.txt](llms/cli.2.txt) 22.3 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 33.9 KB → [llms/cli.2.txt](llms/cli.2.txt) 36.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.113.1",
+  "version": "0.113.3",
   "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",