stitchkit 0.93.0 → 0.94.1

package/llms/primitives.txt

@@ -0,0 +1,158 @@
+# stitchkit/primitives — 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: Generic application primitives  (docs/guide/primitives.md) · API reference: `stitchkit/primitives`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Generic application primitives  (docs/guide/primitives.md)
+==============================================================================
+
+---
+title: Generic application primitives
+description: Declare lifecycle, access, exact values, audit, delivery and exports without moving application infrastructure into Stitchkit.
+type: guide
+status: active
+created: 2026-09-01
+updated: 2026-09-01
+---
+
+# Generic application primitives
+
+`stitchkit/primitives` is an optional browser-safe leaf. It declares values and policies; it does
+not own a database, transaction, scheduler, durable queue, transport or document generator.
+
+## Lifecycle and access
+
+```ts
+import { defineLifecycle, defineOwnerScope, definePermissionMatrix } from 'stitchkit/primitives';
+import { z } from 'zod';
+
+const lifecycle = defineLifecycle({
+  name: 'document',
+  states: ['draft', 'published'],
+  roles: ['author'],
+  transitions: {
+    publish: {
+      from: 'draft',
+      to: 'published',
+      by: ['author'],
+      payload: z.object({ note: z.string() }),
+    },
+  },
+});
+
+const permissions = definePermissionMatrix({
+  roles: ['reader', 'author'],
+  operations: ['read', 'publish'],
+  grants: {
+    reader: { read: true, publish: false },
+    author: { read: true, publish: true },
+  },
+});
+```
+
+Persist `transition(...).event` in the same application transaction as the next state. A state is
+an immutable branded value; `transition()` produces the next one. `availableTransitions()` and
+`transition()` read the same declaration.
+
+`defineOwnerScope` resolves one owner from authenticated identity. Reading across owners is a
+separate `acrossAllOwners(identity)` call and permission. Pass the resulting branded `OwnerScope`
+to the data adapter. This proves the scope was explicit; Stitchkit cannot prove what SQL an
+arbitrary adapter emits. `scanOwnerFilterRisks` maps existing caller-named manual filters before a
+migration.
+
+## Exact values and deadlines
+
+`defineMoney(currency)` stores integer minor units as a JSON string. Arithmetic keeps the currency
+literal in the type; division and rational shares return an explicit remainder. It does not own
+exchange rates.
+
+`defineUnitSystem` stores exact canonical decimal strings. Every conversion is an application
+rational with an id. A converted `QuantityProjection` is `derived` and carries both its source and
+conversion id; a form/database value can be marked `recorded`. Whether a derived projection is
+persisted or recomputed is an application decision.
+
+`defineDeadlinePolicy` requires an explicit `now`, IANA timezone and elapsed/calendar-day boundary.
+It returns the due instant, signed remaining days, overdue days and caller-owned category key.
+`queryBoundary(now)` returns instants suitable for a data-adapter predicate; reminders and
+escalations are not included.
+
+## Audit and delivery
+
+Put an audit decision beside each operation:
+
+```ts
+meta: { audit: audit.record(z.object({ changed: z.array(z.string()) })) }
+// or
+meta: { audit: audit.omit('read-only projection') }
+```
+
+`assertAuditDeclared(contract)` refuses silence. `createAuditRecord()` validates the change and
+returns a `DomainEvent`; the same id/value can feed both the journal and delivery.
+
+`defineDomainEventDelivery().plan(event)` is pure. Save that event and its destinations in the
+application's transaction. After commit, call `dispatch(event.id)`: the dispatcher accepts only an
+id and obtains actual work from `DomainEventOutbox.claim`. A transport returns `delivered`,
+`retryable`, `terminal` or `unknown`; the dispatcher calls the matching outbox transition. Only
+`retry` may schedule another claim, while `unknown` is held for inspection instead of guessed into
+a retry. The application owns retention and scheduling. There is deliberately no scheduler or
+distributed lease.
+
+## Exports
+
+`defineExportOperation` supplies one input and one result schema to an ordinary contract endpoint.
+A small result can be `ready` with a `ManagedFileRef`; a larger result can be `pending` with the id
+of the application's existing async operation. The input, scope, metadata and tool identity do not
+change. The application creates bytes and owns operation persistence; the managed-file boundary
+streams them.
+
+==============================================================================
+# API reference: `stitchkit/primitives`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/primitives`
+
+Browser-and-server-safe declarations for facts an application wants to define once. See the
+[primitives guide](../guide/primitives.md). Storage, transactions, data-adapter predicates,
+schedules, transports and file generation remain application-owned.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineLifecycle` | function | immutable finite-state transition declaration, role/payload validation, available-action projection and transition event |
+| `LifecycleState` / `LifecycleTransitionDefinition` / `LifecycleDefinition` | _types_ | branded state value and the declaration inferred from application strings |
+| `LifecycleTransitionInput` / `LifecycleTransitionResult` / `LifecycleTransitionSuccess` / `LifecycleTransitionFailure` | _types_ | typed execution input and distinct transition/state, role and payload outcomes |
+| `LifecycleTransitionEventSchema` / `LifecycleTransitionEvent` | schema / _type_ | canonical event returned for application-atomic persistence |
+| `defineOwnerScope` | function | resolve one owner from identity or require the explicit `acrossAllOwners` capability |
+| `OwnerScope` / `OwnerScopeDefinition` / `OwnerScopeResolution` | _types_ | branded adapter input and its resolved/refused outcomes |
+| `definePermissionMatrix` | function | exhaustive role × operation decisions with server check and client capability projection |
+| `PermissionGrantMatrix` / `PermissionCheckResult` | _types_ | compile-time complete matrix and unknown/allowed/denied runtime result |
+| `defineMoney` / `createMoneySchema` | functions | fixed-currency JSON-safe minor-unit value and Zod schema |
+| `addMoney` / `subtractMoney` / `multiplyMoney` / `shareMoney` / `splitMoney` | functions | exact same-currency arithmetic with explicit indivisible remainder |
+| `Money` / `MoneyShare` / `MoneySplit` | _types_ | currency-literal value and remainder-bearing operation results |
+| `defineUnitSystem` / `createQuantitySchema` / `addQuantity` | functions | exact decimal quantities and caller-declared finite conversions |
+| `Quantity` / `UnitConversion` / `QuantityProjection` | _types_ | unit-literal value, rational conversion and recorded/derived provenance |
+| `QuantityProjectionSchema` | schema | transport-safe recorded/derived quantity union |
+| `defineDeadlinePolicy` | function | elapsed- or calendar-day projection with explicit timezone, threshold, current time and caller category keys |
+| `DeadlineResultSchema` / `DeadlineResult` | schema / _type_ | due instant, remaining/overdue days and projected category |
+| `audit` | constant | constructors for explicit `record(changeSchema)` or `omit(reason)` endpoint metadata |
+| `assertAuditDeclared` | function | refuse a contract operation with no audit decision |
+| `createAuditRecord` | function | validate one declared change and return the canonical event value |
+| `AuditPolicy` / `AuditRecordPolicy` / `AuditOmitPolicy` / `CreateAuditRecordInput` | _types_ | audit declaration and record input contracts |
+| `AuditRecordSchema` / `AuditRecord` | schema / _type_ | domain-event-shaped audit record |
+| `createDomainEventSchema` | function | wrap a typed payload in the canonical event envelope |
+| `DomainEventSchema` / `DomainEvent` | schema / _type_ | generic event with stable id, time, subject and optional actor |
+| `DomainEventActorSchema` / `DomainEventActor` | schema / _type_ | structured actor identity and application role |
+| `DomainEventSubjectSchema` / `DomainEventSubject` | schema / _type_ | generic subject type/id pair |
+| `defineDomainEventDelivery` | function | plan routes and dispatch only application-outbox claims by committed event id |
+| `DomainEventDestinationSchema` / `DomainEventDestination` | schema / _type_ | transport-neutral destination identity |
+| `DomainEventDeliveryOutcomeSchema` / `DomainEventDeliveryOutcome` | schema / _type_ | delivered, retryable, terminal or unknown transport result |
+| `DomainEventDeliveryClaimSchema` / `DomainEventDeliveryClaim` | schema / _type_ | application-owned atomic outbox claim |
+| `DomainEventOutbox` / `DomainEventRoute` / `DomainEventTransport` | _types_ | host capabilities composed by process-local delivery |
+| `DomainEventDeliveryPlan` / `DomainEventDispatchResult` | _types_ | transaction input and bounded dispatch summary |
+| `defineExportOperation` / `createExportResultSchema` | functions | one typed contract operation returning a ready managed file or pending operation id |
+| `scanMoneyNumberRisks` / `scanOwnerFilterRisks` | functions | source-text migration diagnostics with caller-owned identifiers |
+| `SourceText` / `SourceRisk` | _types_ | migration scanner input and exact path/line evidence |
+
+---

package/llms/react.txt

@@ -0,0 +1,184 @@
+# stitchkit/react — 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: Frontend integrations  (docs/guide/frontend-integrations.md) · Guide: React Query policy  (docs/guide/react.md) · API reference: `stitchkit/react`  (docs/api/reference.md)
+
+Also read:
+- see `llms/server.txt` for the Realtime guide
+
+==============================================================================
+# Guide: Frontend integrations  (docs/guide/frontend-integrations.md)
+==============================================================================
+
+---
+title: Frontend integrations
+description: Compose Stitchkit with Next.js, React Router or a separate Vite development server
+type: architecture
+status: active
+created: 2026-08-08
+updated: 2026-08-08
+---
+
+# Frontend integrations
+
+The official `bun create stitchkit` application uses Next.js with a separate
+Bun API. Stitchkit remains a Fetch-native backend and does not own frontend
+routing, SSR or HMR.
+
+## Theme boundary in the official starter
+
+The generated Next.js application uses `@wrksz/themes`, not a Stitchkit-owned
+theme abstraction. Its root `ThemeProvider` comes from `@wrksz/themes/next` and
+lives directly in the server layout so Next 16 can inject the first-paint script
+through `useServerInsertedHTML`. The default `hybrid` storage reads a cookie
+during SSR and mirrors changes to localStorage for cross-tab synchronization.
+
+Client components import typed hooks from the fine-grained
+`@wrksz/themes/client/*` entrypoints. Nested visual examples use
+`ClientThemeProvider` with a scoped target and `storage="none"`; they never
+become a second global provider. Applications may add account-backed theme
+preferences, CSP nonces or consent-aware storage, but those policies remain
+application concerns.
+
+Theme state and theme animation are intentionally separate. `@wrksz/themes`
+owns selection, resolution, SSR prepaint and persistence. The generated app's
+`theme/transition.ts` wraps an interactive `setTheme` call with the native View
+Transition API and exposes typed style, duration, easing and origin settings.
+The default 250 ms crossfade matches the starter's visual language; the
+catalogue also demonstrates a radial reveal. The runner bypasses animation when
+the browser lacks the API or `prefers-reduced-motion: reduce` is active.
+
+## React Router
+
+Mount a `createHandler()` result in a catch-all resource route and pass the
+incoming `Request` through unchanged. Mount MCP as a second resource route. An
+SSR request creates its own typed client using that request's origin and auth;
+do not share request identity in a module singleton.
+
+```ts
+export async function loader({ request }: LoaderFunctionArgs) {
+  return apiHandler(request);
+}
+
+export async function action({ request }: ActionFunctionArgs) {
+  return apiHandler(request);
+}
+```
+
+## Vite
+
+Run Vite and the Stitchkit API as separate development processes. Declare one
+proxy for `/api`, `/mcp` and `/socket.io`; browser code still calls the typed
+client with same-origin paths. Production serves the static Vite output from a
+static host or reverse proxy and routes those backend paths to Stitchkit.
+
+Do not duplicate DTOs or handwritten API wrappers in either integration. The
+shared contract remains the only transport schema source.
+
+==============================================================================
+# Guide: React Query policy  (docs/guide/react.md)
+==============================================================================
+
+---
+title: React Query policy
+description: One request-local server client, one browser singleton and explicit retry rules for Stitchkit API errors
+type: guide
+status: active
+created: 2026-09-06
+updated: 2026-09-06
+---
+
+# React Query policy
+
+`stitchkit/react` contains policy adapters for TanStack Query. It does not own
+application queries, cache keys or authentication.
+
+## Query client per runtime
+
+Create the getter once. On the server, pass React's `cache` so identity is local
+to one render request. In the browser, the returned getter keeps one singleton
+inside this factory only:
+
+```ts
+import { cache } from 'react'
+import { createQueryClientFactory } from 'stitchkit/react'
+
+export const getQueryClient = createQueryClientFactory({
+  serverCache: cache,
+  queryClient: {
+    defaultOptions: { queries: { staleTime: 30_000 } },
+  },
+})
+```
+
+Pending queries are dehydrated so streaming SSR can resume them. Mutations do
+not retry by default. Every TanStack default may still be supplied through
+`queryClient`; a supplied query or mutation retry policy wins over the helper's
+defaults.
+
+## API error retries
+
+`apiErrorRetry()` returns a TanStack retry predicate. The default retries one
+network or `5xx` failure and refuses authorization, validation, abort and other
+`4xx` errors:
+
+```ts
+const retry = apiErrorRetry({
+  attempts: 2,
+  never: ['UNAUTHORIZED', 'FORBIDDEN'],
+  statusRanges: [[500, 599]],
+})
+```
+
+Ranges are inclusive. The predicate uses `ApiError.is`, so it remains valid when
+two bundles contain different copies of the class.
+
+Authentication remains application-owned. Memoize the application's own
+session query with `cache`; the generic starter does not invent a `getSession`
+endpoint or cookie vocabulary.
+
+==============================================================================
+# API reference: `stitchkit/react`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/react`
+
+Browser- and server-render-safe React data-layer helpers. Needs the
+`@tanstack/react-query` and `react-query-kit` peers.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createCursorQuery` | function | a cursor-paginated infinite query — [guide](../guide/client.md#cursor-pagination) |
+| `apiErrorRetry` | function | build a bounded network/HTTP-status retry predicate using cross-bundle `ApiError.is` — [guide](../guide/react.md#api-error-retries) |
+| `createQueryClientFactory` | function | request-local SSR QueryClient through a supplied cache adapter plus a factory-local browser singleton — [guide](../guide/react.md#query-client-per-runtime) |
+| `createCacheBridge` | function | sync socket events into the Query cache — [guide](../guide/realtime.md#cache-bridge) |
+| `createRealtimeCacheBridge` | function | the same bridge fed by a **validated realtime contract**; the payload comes from the contract's args tuple instead of inferring `never` |
+| `createEntityCacheHandlers` | function | created/updated/deleted cache handlers for one entity — [guide](../guide/realtime.md#entity-cache-handlers) |
+| `EntityCacheConfig` | _type_ | config for `createEntityCacheHandlers` |
+| `EntityCacheMembership` / `EntityCacheMembershipPolicy` | _type_ | per-exact-query `include | exclude | unknown` filter decision and unknown invalidation policy |
+| `EntityCacheTotalPolicy` / `EntityCacheTotalDeltaInput` | _type_ | evidence-aware reconciliation of numeric totals on paginated cache shapes |
+| `EntityCacheHandlers` | _type_ | the `{ created, updated, deleted }` handlers it returns |
+| `EntityCacheEvent` | _type_ | discriminated created/updated/deleted input for dynamic cache keys |
+| `EntityCacheKey` | _type_ | static `QueryKey` or event-aware key factory |
+| `EntityCacheListConfig` | _type_ | list shape, scoped key, insertion/missing-update policy and comparator |
+| `EntityCacheListShape` | _type_ | `array \| paginated \| infinite-array \| infinite-paginated` |
+| `DeletedPayload` | _type_ | a `deleted` event payload — the entity or a bare `{ id }` |
+| `CursorQueryConfig` | _type_ | config for `createCursorQuery` |
+| `ApiErrorRetryConfig` | _type_ | retry attempts, excluded application codes, inclusive status ranges and network policy |
+| `QueryClientFactoryConfig` / `QueryClientServerCache` | _type_ | TanStack config, mutation observer, retry policy and request-cache adapter |
+| `QueryRetryValue` | _type_ | TanStack's accepted query retry value retained by the factory pass-through |
+| `CacheBridge` | _type_ | the `createCacheBridge` handle |
+| `CacheBridgeConfig` | _type_ | config for `createCacheBridge` |
+| `RealtimeCacheBridgeConfig` | _type_ | config for `createRealtimeCacheBridge` — same fields, a `ValidatedRealtimeSocket` in place of the raw socket |
+| `CacheBridgeContext` | _type_ | the `ctx` a bridge handler receives |
+| `CacheBridgeHandler` | _type_ | one event-to-cache handler |
+| `CacheBridgeHandlers` | _type_ | the handler map |
+| `CacheBridgeSocket` | _type_ | the minimal emitter a bridge accepts |
+
+---
+
+For the rationale behind these APIs — why `Bun.serve` and not a framework, why
+two context types, why thin wrappers — see the
+[Architecture Decisions](../decisions/).

package/llms/release.txt

@@ -0,0 +1,176 @@
+# stitchkit/release — 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: Release  (docs/guide/release.md) · API reference: `stitchkit/release`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Release  (docs/guide/release.md)
+==============================================================================
+
+# Release
+
+A tab that outlives a release keeps running a bundle the server no longer
+serves. `stitchkit/release` makes the page follow the release it was built
+for: the server names its current frontend build, the browser compares that
+to its own, and reloads under a policy you declare. Both halves are
+**evolving**. → ADR 0167
+
+## The server: a marker and two channels
+
+```ts
+import { readFileSync } from 'node:fs'
+import { createReleaseMarker } from 'stitchkit/release'
+import { bindReleaseRefreshSignal, createServer } from 'stitchkit/server'
+
+// Where the *active* release wrote its build id. After a frontend-only
+// release the backend may still run from an older root — read the pointer to
+// the current one, not the process's own cwd. `null` means "no release": a
+// dev server under HMR stays silent.
+const release = createReleaseMarker({
+  read: () => (env.RELEASE_ROOT ? readFileSync(`${env.RELEASE_ROOT}/current/frontend/.next/BUILD_ID`, 'utf8') : null),
+  onError: (error) => logger.warn('release marker', error), // an unreadable file, a value that is not an id, a subscriber that threw
+})
+
+const server = createServer({ services, cors, release })
+
+// A deploy that replaced the frontend without restarting the backend sends
+// SIGUSR2; the marker re-reads and tells its subscribers.
+bindReleaseRefreshSignal(release, { onRefresh: (r) => logger.info('build', r) })
+```
+
+With `release` configured, **every** response — success, error, raw route —
+carries `X-Build-Id`, and `DEFAULT_CORS_EXPOSE_HEADERS` lets a cross-origin
+page read it. That is the universal channel: any application that makes HTTP
+requests has it, with no socket and no polling of its own.
+
+Where a Socket.IO server exists, add the fast path:
+
+```ts
+import { bindReleaseToSocketServer } from 'stitchkit/release'
+
+bindReleaseToSocketServer(io, release) // event `release` on connection and on change
+```
+
+A connection re-reads the file before it is answered, so a deploy signal the
+process missed while it was down is repaired by the next client that connects.
+
+Two things to keep straight: a custom `cors.exposeHeaders` **replaces** the
+default list, so add `X-Build-Id` to yours or a cross-origin page cannot read
+it; and do not list `SIGUSR2` in `bindProcessSignals` as well, or a deploy
+would shut the server down.
+
+## The deploy step
+
+The framework binds the signal; **your release sends it**, after the new
+frontend is active:
+
+```bash
+pm2 sendSignal SIGUSR2 my-backend      # or: kill -USR2 <pid>
+```
+
+Name it in the release steps of the project. A backend restart needs no
+signal — the marker reads on start, and every reconnecting browser asks.
+
+## The browser: a watcher and its feeds
+
+```ts
+import { createHttpClient } from 'stitchkit'
+import { createReleaseWatcher, observeReleaseFromSocket } from 'stitchkit/release'
+
+const release = createReleaseWatcher({
+  own: env.NEXT_PUBLIC_BUILD_ID ?? 'dev', // what THIS bundle was built with; `dev` never reloads
+  policy: 'when-hidden',           // or 'immediate' | 'on-navigation'
+  maxDeferMs: 15 * 60 * 1000,
+  onStale: () => toast('A new version is ready'),
+})
+
+const http = createHttpClient({ baseUrl, release })   // reads X-Build-Id from every response
+observeReleaseFromSocket(socket, release)             // and the socket event, where there is one
+```
+
+`observe` compares to `own`, never to the first id it happened to hear — a
+tab that loaded a cached bundle after the release is exactly the tab that must
+reload. An `own` of `dev` (configurable via `ignore`), or no `own` at all,
+never reloads, so a development bundle against a production API is not sent
+in a loop. And one reload per id: the id a reload was attempted for is kept
+in session storage, and if the page comes back and the server still names it,
+the server is wrong about what it serves (a marker reading the wrong root, a
+cached response) — the page stays, `stale()` is true, `onStale` has fired,
+and nothing loops.
+
+| Policy | Reloads |
+|--------|---------|
+| `immediate` | now — a chat, a dashboard |
+| `when-hidden` | when the tab is next hidden, or at `maxDeferMs` — a page with forms |
+| `on-navigation` | when you call `release.navigated()` on a route change, or at `maxDeferMs` — an SPA where a full load replaces a transition |
+
+`browserReleaseHost()` is what the watcher reads from a tab; a test passes its
+own `host` and drives visibility, the timer and `reload` by hand. Without a
+`document` (server-side rendering) the default host is inert: `observe`
+records the verdict and reloads nothing.
+
+## Adopting it
+
+1. Bake the build id into the bundle, from **one** source. Without it the
+   watcher has no `own` and never reloads — and it never says so, which is the
+   part worth spending a paragraph on.
+
+   `NEXT_PUBLIC_BUILD_ID=$(git rev-parse --short HEAD)` in the build command is
+   the short version and it has a failure mode: on an immutable-release layout
+   that variable usually lives in a static environment file, so it is easy for
+   two releases to ship the same id. Then `own` equals what the server reports
+   on every response, the watcher is correct to stay quiet, and nothing
+   anywhere is red. A reload that never happens looks exactly like a reload
+   that was not needed.
+
+   So mint it once and let one value reach all three readers. In Next, that is
+   `next.config`:
+
+   ```ts
+   const buildId = process.env.BUILD_ID ?? execSync('git rev-parse --short HEAD').toString().trim()
+
+   export default {
+     generateBuildId: () => buildId,          // → .next/BUILD_ID, which the server marker reads
+     env: { NEXT_PUBLIC_BUILD_ID: buildId },  // → the bundle, which becomes `own`
+   }
+   ```
+
+   The bundle's id and the file the server reports now come from the same
+   expression evaluated once, so they cannot drift apart per release. Any
+   arrangement with that property will do; the one to avoid is two places that
+   each decide the id and are expected to agree.
+2. Point `read` at the id of the **active** release, not the process's cwd.
+3. Add `release: (data: { buildId: string | null }) => void` to your
+   `ServerToClientEvents` map where you type your socket, so your own `on`
+   knows the event the binding emits. This is also what makes a **typed**
+   `Server<…>` fit `bindReleaseToSocketServer`: its `emit` is narrowed to the
+   names in your map, so until `release` is one of them the call fails to
+   typecheck — as a long structural mismatch, which reads like a bug in the
+   binding and is this line instead.
+4. Send `SIGUSR2` from the deploy step that activates a frontend without
+   restarting the backend, and name that step in the project's release steps.
+
+==============================================================================
+# API reference: `stitchkit/release`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/release`
+
+A page follows the release it was built for. The server keeps a marker of the
+current frontend build and names it on every response (`X-Build-Id`) and every
+socket connection; the browser compares that to its **own** build id and
+reloads under a declared policy. Reading the build id and sending the deploy
+signal stay with the application. → ADR 0167 — [guide](../guide/release.md)
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createReleaseMarker` / `ReleaseMarker` / `ReleaseMarkerConfig` / `ReleaseRefresh` | function / _type_ | `current()`, `refresh()` → `{ changed, buildId }`, `subscribe`; built on an application `read` that returns `null` where there is no release; a bad value or a throwing subscriber goes to `onError`, never out |
+| `RELEASE_HEADER` | const | `X-Build-Id` — set on every response of a handler configured with `release`, exposed through CORS by default |
+| `createReleaseWatcher` / `ReleaseWatcher` / `ReleaseWatcherConfig` / `ReleaseReloadPolicy` | function / _type_ | `observe(buildId)` against the bundle's own id; `immediate` / `when-hidden` / `on-navigation` with `maxDeferMs`; one reload per id, remembered across it; `navigated`, `stale`, `dispose`, `onStale` |
+| `browserReleaseHost` / `ReleaseWatcherHost` | function / _type_ | visibility, timer and reload behind one interface — a test supplies its own |
+| `bindReleaseToSocketServer` / `observeReleaseFromSocket` | function | the socket channel: each connection re-reads and hears the build, everyone hears a change; the client hands the event to the watcher |
+| `ReleaseSocketServer` / `ReleaseSocketEmitter` / `ReleaseSocketListener` / `ReleaseSocketOptions` | _type_ | the structural slices of a Socket.IO server and client the bindings use — no peer import |
+
+---

package/llms/remote.txt

@@ -0,0 +1,25 @@
+# stitchkit/remote — 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: API reference: `stitchkit/remote`  (docs/api/reference.md)
+
+Also read:
+- see `llms/tools.txt` for the MCP & agents guide
+
+==============================================================================
+# API reference: `stitchkit/remote`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/remote`
+
+Peer-free remote implementation boundary. Importing it does not load the MCP
+SDK, `ai`, or other optional tool peers, so it is safe in a thin CLI bundle.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `implementRemote` | function | bind a contract to a remote HTTP API — [guide](../guide/mcp-and-agents.md#proxying-a-remote-api--implementremote) |
+| `ImplementRemoteOptions` | _type_ | optional argument-rewrite hook for `implementRemote` |
+
+---