@terreno/mcp 57.9.0 → 57.11.0

package/src/docs/versioned/next/reference/blocks.md

@@ -0,0 +1,178 @@
+# UI blocks
+
+`@terreno/blocks` checks the YAML (or JSON) document an agent uses when a chat reply is
+components instead of prose. Ask schemas are in [Agent UI Asks](agent-ui-asks.md). Validate a
+file locally with [the blocks how-to](../how-to/agent-ui-blocks.md).
+
+## Document
+
+A reply is one mapping. Keys, when present, are in this order: `v`, `datasets`, `blocks`.
+
+```yaml
+v: 1
+blocks:
+  - type: text
+    markdown: I could not find any signups for that range.
+```
+
+`parseBlocks` strips one surrounding ` ```yaml ` fence, parses YAML 1.2 core schema or JSON,
+and rejects anchors, aliases, and explicit tags (`YAML_FEATURE_DISALLOWED`). A value that is
+not a mapping with `v` is `NOT_A_DOCUMENT`. Callers display that reply with
+`wrapAsTextDocument`, which builds `{v: 1, blocks: [{type: text, markdown}]}`.
+
+## Datasets
+
+A dataset name matches `^[a-z][a-z0-9_]{0,63}$`. A document has at most 8 datasets.
+
+| Source | Fields | Rule |
+| --- | --- | --- |
+| inline | `columns`: `{name, type}` where `type` is `string`, `number`, or `date`; `rows`: arrays | At most 500 rows and 12 columns. Each row has one value per column. `source: inline` is optional. |
+| ref | `source: ref`, `id`, optional `grain` (`hour`, `day`, `week`, `month`), optional `limit` | `limit` above 1,000 is `TOO_MANY_POINTS`. Set `grain` to a coarser bucket. Column checks run when `knownDatasets` is passed. |
+
+## Charts and tables
+
+| Block | Required | Optional |
+| --- | --- | --- |
+| `chart` | `kind`: `line`, `bar`, `area`, `donut`, and either `data` + `x` + `y` or `points` (`{label, value}`) | `id`, `title`, `legend`, `emptyText`, `height`: `sm`, `md`, `lg` |
+| `table` | `data` (dataset name) | `id`, `columns` (names), `title` |
+
+`x` is a string or date column. `y` is a number column. A table lists at most 12 columns.
+
+## HTML
+
+| Block | Required | Optional |
+| --- | --- | --- |
+| `html` | `html` (at most 100,000 bytes) | `id`, `title`, `height`: `sm`, `md`, `lg` |
+
+`validateBlocks` returns `HTML_DISABLED` unless `options.allowHtml` is true. A host turns that on with `uiBlocks.html`. The server sanitizes the HTML before it is stored. The client renders it only when `allowHtml` is set.
+
+## Callout, image, and details
+
+| Block | Required | Optional |
+| --- | --- | --- |
+| `callout` | `text` | `id`, `status`: `info`, `warning`, `alert` |
+| `image` | `alt`, `src` | `id` |
+| `details` | `title`, `text` | `id` |
+
+`src` is a `data:image` URL, a `file:` ref (`file:` plus an id), or an `https` URL. `https` is allowed only when the hostname is in `validateBlocks` `imageHosts` (the server option is `uiBlocks.imageHosts`). Anything else is `IMAGE_HOST_NOT_ALLOWED`. An empty list rejects every `https` image. A ref dataset `id` uses 1–80 letters, digits, underscores, or hyphens. A block or action-element `id` stays lowercase and starts with a letter. `limit` of `0` is `INVALID_TYPE` (an integer of at least 1), not `TOO_SHORT`.
+
+Warnings do not block rendering:
+
+| Code | When |
+| --- | --- |
+| `BAR_TOO_MANY_CATEGORIES` | A bar chart would draw more than 60 categories. |
+| `DONUT_TOO_MANY_SLICES` | A donut chart would draw more than 8 slices. |
+| `LINE_SINGLE_POINT` | A line chart has one point. |
+
+## Blocks
+
+| Block | Required | Optional | Renders as |
+| --- | --- | --- | --- |
+| `heading` | `text` (1–200) | `size`: `sm`, `md`, `lg`, `xl`, `2xl`; `id` | `Heading` |
+| `text` | `markdown` (1–4,000) | `id` | `MarkdownView` |
+| `metric` | `label` (1–80), `value` (1–80) | `delta` (1–40), `trend`: `up`, `down`, `flat`, `helper` (1–120), `id` | `Card` |
+| `badge` | `text` (1–80) | `status`: `info`, `error`, `warning`, `success`, `neutral`, `active`; `id` | `Badge` |
+| `divider` | — | `id` | `SectionDivider` |
+| `context` | `text` (1–280) | `id` | `Text` |
+| `columns` | `children`: 2–4 blocks | `id` | `Box` row |
+| `card` | `children`: at least 1 block | `title` (1–120), `id` | `Card` |
+
+`columns` and `card` sit at the top level. Their children are leaf blocks. A layout block
+inside another layout block is `DEPTH_EXCEEDED`. Every block counts toward the 50-block
+cap, including the `card` or `columns` block itself, so a card cannot hold 50 children.
+
+`id` matches `^[a-z][a-z0-9_]{0,63}$`.
+
+## Actions
+
+An `actions` block requires `id` and `elements` (1–25). An element is a `button` or a
+`segmented` control.
+
+| Element | Required | Optional |
+| --- | --- | --- |
+| `button` | `id`, `text` (1–80), `action` | `variant`: `primary`, `secondary`, `outline`, `ghost`, `destructive`; `iconName` |
+| `segmented` | `id`, `target` (a chart or table `id`), `options` (2–8 of `{label, data}`) | — |
+
+`action.kind` is `reply` (`text`), `open` (`url` or `route`, exactly one), `select`
+(`target` plus `data`), or `callback` (`name` plus optional `payload`). A `select` target
+that is not a chart or table `id` is `SELECT_TARGET_INVALID`. When `validateBlocks` is
+called with `hostActions`, a callback `name` outside that list is `UNKNOWN_HOST_ACTION`.
+Omitting `hostActions` skips that check.
+
+## Partial parsing
+
+`parseBlocksPartial(text)` never throws. A document that `validateBlocks` accepts returns
+`{datasets, blocks, pending: false}`. A cut reply returns only the top-level blocks whose
+next `- ` already arrived, drops the unfinished tail, and sets `pending: true`. `datasets`
+is present only after the `blocks:` key has started and the prefix parses.
+
+## CLI
+
+`terreno-blocks validate <file | ->` prints each problem as `path  CODE  message — fix` and
+exits 1. A valid document exits 0. Warnings are printed and still exit 0.
+
+Unknown fields fail with `UNKNOWN_KEY`. `v` must be `1` (`UNSUPPORTED_VERSION`).
+
+## Limits
+
+| Limit | Value |
+| --- | --- |
+| Blocks in one document, including nested blocks | 50 |
+| Nesting | 2 (`blocks` → `columns` or `card` → leaf) |
+| `columns` children | 2–4 |
+| Elements in one `actions` block | 25 |
+| Text in one `text` block | 4,000 characters |
+| Document version | 1 |
+
+## Errors
+
+`validateBlocks` returns `{ok: true, doc, warnings}` or `{ok: false, errors, warnings}`.
+Each error is `{path, code, message, fix}`, sorted by path. `warnings` lists chart
+heuristics and does not fail `ok`.
+
+| Code | Meaning |
+| --- | --- |
+| `COLUMN_NOT_FOUND` | A chart or table names a column the dataset does not have. |
+| `COLUMN_TYPE_MISMATCH` | A column value, or a chart axis, does not match the column type. |
+| `DATASET_NOT_FOUND` | A chart or table names a dataset the document does not define. |
+| `DATASET_TOO_LARGE` | A dataset has more than 500 rows or 12 columns. |
+| `DEPTH_EXCEEDED` | A `columns` or `card` block is nested inside another layout block. |
+| `DUPLICATE_ID` | A block id, an action-element id, or a column name is used more than once. |
+| `HTML_DISABLED` | An html block is present and this host has not turned HTML on. |
+| `HTML_TOO_LARGE` | An html block is larger than 100,000 bytes. |
+| `IMAGE_HOST_NOT_ALLOWED` | An image URL is not a `data:image` URL, a `file:` ref, or an `https` URL on an allowed host. |
+| `INVALID_ENUM` | A value is not one of the allowed values. |
+| `INVALID_FORMAT` | A string does not match its required format. |
+| `INVALID_TYPE` | A value has the wrong type, including a numeric field below its minimum. |
+| `KEY_ORDER` | Top-level keys are not in the order `v`, `datasets`, `blocks`. |
+| `MISSING_REQUIRED` | A required field is missing. |
+| `NOT_A_DOCUMENT` | The reply is not one YAML or JSON mapping with a `v` field. |
+| `SELECT_TARGET_INVALID` | A select action names a block that is not a chart or table. |
+| `ROW_ARITY_MISMATCH` | A dataset row does not have one value per column. |
+| `TABLE_TOO_WIDE` | A table lists more than 12 columns. |
+| `TOO_FEW` | A list has fewer items than allowed. |
+| `TOO_LONG` | A string is longer than allowed. |
+| `TOO_MANY` | A list has more items than allowed. |
+| `TOO_MANY_BLOCKS` | The document has more than 50 blocks. |
+| `TOO_MANY_POINTS` | A ref dataset `limit` is above 1,000. |
+| `TOO_SHORT` | A string is empty or only whitespace. |
+| `UNKNOWN_HOST_ACTION` | A callback names a host action that is not registered. |
+| `UNKNOWN_KEY` | An object has a field that its schema does not define. |
+| `UNSUPPORTED_VERSION` | `v` is not 1. |
+| `YAML_FEATURE_DISALLOWED` | The document uses a YAML anchor, alias, or explicit tag. |
+
+## Exports
+
+| Export | Role |
+| --- | --- |
+| `parseBlocks(text)` | Fence strip, YAML or JSON parse |
+| `parseBlocksPartial(text)` | Completed top-level blocks while a reply is still streaming |
+| `validateBlocks(doc, options?)` | Structure, then dataset, chart, table, action, and html lint. `options.knownDatasets` checks `ref` columns. `options.hostActions` checks callback names. `options.allowHtml` allows `html` blocks. |
+| `wrapAsTextDocument(text)` | Display fallback for a non-document |
+| `blocksSchema` | Zod schema |
+| `blocksJsonSchema` | JSON Schema for the same structure |
+| `blocksPromptSection({hostActions, allowHtml})` | System-prompt section. Limits come from `BLOCK_LIMITS`. `allowHtml` adds the `html` block. |
+| `BLOCK_LIMITS` | The numbers in the table above |
+| `BLOCK_ERROR_CODES` | The codes in the table above |
+| `BLOCK_WARNING_CODES` | `BAR_TOO_MANY_CATEGORIES`, `DONUT_TOO_MANY_SLICES`, `LINE_SINGLE_POINT` |
+| `HTML_HEIGHTS`, `CALLOUT_STATUSES` | Allowed `html` heights and `callout` statuses. `HtmlBlock`, `CalloutBlock`, `ImageBlock`, and `DetailsBlock` are type exports. |

package/src/docs/versioned/next/reference/environment-variables.md

@@ -23,6 +23,7 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `TERRENO_TEST_MONGODB_URI` | `@terreno/test` | ❌ | auto | Yes | tooling |
 | `TERRENO_TEST_USE_MEMORY_MONGO` | `@terreno/test` | ❌ | — | No | tooling |
 | `TERRENO_TEST_USE_REPLSET` | `@terreno/test` | ❌ | — | No | tooling |
+| `TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` | `@terreno/test` | ❌ | `60000` | No | tooling |
 | `TERRENO_TEST_USE_FIXTURE_CACHE` | `@terreno/test` | ❌ | — | No | tooling |
 | `TERRENO_TEST_CACHE_DIR` | `@terreno/test` | ❌ | — | No | tooling |
 | `BUN_TEST_DISABLE_DB` | test harness | ❌ | — | No | tooling |
@@ -222,7 +223,7 @@ There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. Apps t
 |----------|---------|----------|---------|--------|-------|
 | `SLACK_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
 | `SLACK_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
-| `SLACK_BOT_TOKEN` | `@terreno/api` `lookupSlackUserIdByEmail` | ❌ | — | Yes | server |
+| `SLACK_BOT_TOKEN` | `@terreno/api` Slack Web API (`lookupSlackUserIdByEmail`, private channels, invites, `chat.postMessage`) | ❌ | — | Yes | server |
 | `GOOGLE_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
 | `GOOGLE_CHAT_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
 | `ZOOM_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |

package/src/docs/versioned/next/reference/lifecycle-plugin.md

@@ -16,6 +16,17 @@ loops that invoke those stages; they are not stages and must not appear as `stag
 | `terreno-4-brew` | Roast PASS for every in-scope task + branch/evidence | pushed head + PR + product-CI trigger check + review-bot wait + attached evidence | Taste |
 | `terreno-5-taste` | PR + current state | one current-head reaction; before push: fetch latest `master` (merge only when needed), re-verify last-run failed tests locally, run root `prepush` when present (otherwise affected-package checks) in a no-context subagent, then watch CI; invoked directly, repeats bounded reactions until terminal | null or fresh Taste |
 
+Pre-Grow skill (not a stage):
+
+| Skill | Input | Primary output | Next |
+| --- | --- | --- | --- |
+| `terreno-prd` | app owner + conversation, prototype, repository | interview, then a published full product PRD (problem, why now, solution, user stories, success metrics and guardrails, constraints, rollout, out of scope); every metric measurable or `TBD` with its decider | Grow, with the PRD as its spec; metrics become acceptance criteria, `TBD`s become grilling questions, settled product decisions are not re-asked |
+
+It is explicit-invoke only (`/terreno-prd`, `$terreno-prd`, `/terreno:prd`). It
+interviews with Grow's grilling procedure over a product tree, is sized for one app owner
+and one or two developers, and carries no implementation or testing decisions; those stay
+in Grow.
+
 Outer loops (not stages):
 
 | Skill | What it walks | Default |

package/src/docs/versioned/next/reference/mcp-server.md

@@ -391,6 +391,23 @@ Validate a Mongoose schema against Terreno conventions.
 - Recommendations for fixes
 - Severity levels (error, warning, info)
 
+### terreno_validate_ui_blocks
+
+Check one whole-reply YAML or JSON document. The text is the same report `terreno-blocks validate` prints: each problem is `path  CODE  message — fix`. A valid document with no warnings returns an empty string.
+
+**Parameters:**
+
+``````typescript
+{
+  document: string; // Required — the YAML or JSON document
+}
+``````
+
+**Returns:**
+
+- The CLI report, including a trailing newline when there is at least one line
+- An empty string when the document is valid and has no warnings
+
 ### terreno_bootstrap_ai_rules
 
 Scaffold AI coding assistant rules (AGENTS.md, Cursor/Windsurf rules, Copilot instructions, rulesync config).

package/src/docs/versioned/next/reference/syncdb.md

@@ -10,6 +10,7 @@ Local-first data layer for Terreno frontends. A TinyBase `MergeableStore` on dev
 - [createSyncDb configuration](#createsyncdb-configuration)
 - [SyncDb client methods](#syncdb-client-methods)
 - [React hooks](#react-hooks)
+- [Query windows](#query-windows)
 - [Codegen](#codegen)
 - [Conflict API](#conflict-api)
 - [Sync status API](#sync-status-api)
@@ -25,7 +26,8 @@ Local-first data layer for Terreno frontends. A TinyBase `MergeableStore` on dev
 - `createSyncDb`, `SyncDb`, `SyncDbConfig`, `MutateArgs`
 - `betterAuthAdapter`, `bridgeBetterAuthReactClient`, `AuthProvider`
 - `listConflicts`, `wipeLocalData`, `generateMutationId`
-- React (`@terreno/syncdb/react`): `SyncDbProvider`, `useEntity`, `useQuery`, `useEntityIds`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`, `createCollectionHooks`
+- Queries: `QueryFieldNotAllowedError`, `ListRequestError`, `WhereFilter`, `SortSpec`, `WindowQuery`, `QueryWindowState`, `QueryWindows`, `compileWhere`, `DEFAULT_WINDOW_PAGE_SIZE`
+- React (`@terreno/syncdb/react`): `SyncDbProvider`, `useEntity`, `useQuery`, `useEntityIds`, `useWindowQuery`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`, `createCollectionHooks`
 - CLI: `terreno-syncdb-codegen` (generates `SYNC_COLLECTIONS` + friendly hooks from OpenAPI)
 - Testing (`@terreno/syncdb/testing`): `createFakeTransport`
 
@@ -165,6 +167,7 @@ be passed to `betterAuthAdapter` directly.
 | `name` | `string` | — (required) | Persisted database name |
 | `collections` | `string[]` | — (required) | Collection names to sync (local tables + subscriptions) |
 | `windowCollections` | `string[]` | `[]` | Collections that join `{collection}\|admin`, skip snapshots/reconcile, and hydrate only known REST membership ids |
+| `queryCollections` | `Array<string \| {collection, path?, fullSync?}>` | `[]` | Collections too large to sync whole (or `fullSync: true` to keep snapshot sync and add windows). No snapshot/reconcile paging; rows arrive through [query windows](#query-windows) against the `modelRouter` list endpoint (`path`, default `/{collection}`) plus live deltas on the user's normal streams. Each entry must also be in `collections` and not in `windowCollections`. |
 | `organizationIdProvider` | `() => string \| undefined` | — | Read at send time: sets `X-Organization-Id` on HTTP sync calls and `organizationId` on socket mutate payloads |
 | `authProvider` | `AuthProvider` | — (required) | `{getToken, getUserId, onAuthChange, refresh?}` |
 | `baseUrl` | `string` | — | Server origin; required unless both `transport` and `httpChannel` are injected |
@@ -200,6 +203,7 @@ be passed to `betterAuthAdapter` directly.
 | `mutate({collection, operation, id?, data?})` | Optimistic local write + durable outbox enqueue + fire-and-forget replay. Returns `{mutationId, id}`. |
 | `reconcile()` | HTTP snapshot catch-up for every known stream; runs tombstone compaction on success. Also runs automatically on (re)connect, on a rate-limited seq-jump hint, and on the periodic timer; each `sync:subscribed` confirmation additionally pages just the streams it names. |
 | `hydrateWindow({collection, ids, restRows?})` | Admin window upsert: REST rows (optional) land immediately; every requested id is also fetched from `GET /sync/entities` before this resolves so seq/deleted metadata is canonical for immediate update/delete. A `{collection}|admin` delta that lands while the fetch is in flight wins, so hydration never rewinds a row to an older seq. Unknown ids are ignored. |
+| `queryWindows` | Server query windows for `queryCollections`: `fetchWindow({query, nextPage?})`, `getWindow(query)`, `retain(query)` → release, `refetchRetained()`, `pruneUnretained()`, `subscribe(cb)`, `keyFor(query)`. See [Query windows](#query-windows). |
 | `forceResync()` | Purge every known stream locally and re-bootstrap from cursor 0 (outbox/conflicts untouched). Returns `{ok, reason?, streams, purged, repaired}`. After discovery and each stream bootstrap it waits for in-flight `start`/`stop`/auth-change work, then abandons with `reason: "superseded"` when that work switched users or generations. |
 | `replayOutbox()` | Drain queued mutations for the current user now. |
 | `resolveConflict({mutationId, strategy})` | Apply `"useServer"` or `"keepMine"` to a recorded conflict. |
@@ -271,13 +275,26 @@ Subscribe to a single entity. Re-renders when that row changes. `isPending` is t
 
 ```typescript
 const todos = useQuery<Todo>("todos", {
-  filter: (t) => !t.completed,
-  sort: (a, b) => b.created.localeCompare(a.created),
-  includeDeleted: false,
+  where: {completed: false, created: {$gte: since}},
+  sort: "-created",
+  limit: 20,
 });
+
+// Callbacks still work and combine with `where`:
+const mine = useQuery<Todo>("todos", {filter: (t) => t.ownerId === userId, sort: byCreatedDesc});
 ```
 
-Returns decoded entity data arrays. Tombstones excluded unless `includeDeleted: true`. Filter and sort run in JS — memoize callbacks when collections are large.
+Returns decoded entity data arrays from the local store. Tombstones excluded unless `includeDeleted: true`.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `where` | `WhereFilter` | Mongo-style filter: equality, dot paths, `$eq` `$ne` `$gt` `$gte` `$lt` `$lte` `$in` `$nin` `$exists`, `$and` / `$or`. An array field matches when any element equals the value. Compared by value, so inline objects are fine. Throws for operators only the server can run (`$search`, `$regex`). |
+| `filter` | `(data) => boolean` | Arbitrary predicate, applied after `where`. |
+| `sort` | `SortSpec \| comparator` | `"-created name"`, `{created: "descending"}`, or `(a, b) => number`. |
+| `limit` | `number` | Keep the first N rows after filter and sort. |
+| `includeDeleted` | `boolean` | Include tombstones. |
+
+Filter and sort run in JS — memoize `filter`/comparator callbacks when collections are large.
 
 ### `useEntityIds(collection, options?)`
 
@@ -288,6 +305,38 @@ return ids.map((id) => <TodoRow key={id} id={id} />);
 
 Same options as `useQuery`, but returns only ordered ids with **referential stability** — the array identity changes only when membership or order changes, not on field updates. Pair with per-row `useEntity` for large lists.
 
+### `useWindowQuery(collection, options?)`
+
+```typescript
+const {data, isLoading, isFetching, hasMore, fetchNextPage, refetch, total, error} =
+  useWindowQuery<Message>("messages", {
+    where: {threadId, deleted: false},
+    sort: "-created",
+    pageSize: 30,
+  });
+```
+
+Server-filtered list over a `queryCollections` collection. See [Query windows](#query-windows).
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `where` | `WhereFilter` | — | Sent as qs list params (`status[$in][0]=open`). Fields must be in the route's `queryFields`. |
+| `sort` | `SortSpec` | route default | Server `sort`; also orders the local view. |
+| `pageSize` | `number` | `50` | Server `limit` per page (capped by the route's `maxLimit`). |
+| `skip` | `boolean` | `false` | Do not retain or fetch (e.g. a required param is missing). |
+| `liveMatch` | `boolean` | `true` | Show cached rows that newly match `where` inside the loaded range. |
+
+| Result | Description |
+|--------|-------------|
+| `data` / `ids` | This window's rows in view order. |
+| `isLoading` | No membership yet (first fetch in flight). Cached membership renders with `isLoading: false`. |
+| `isFetching` | Any request for this window is in flight. |
+| `isError` / `error` | Last request failed (cached rows still render). |
+| `errorCode` | Server error code of the last failure; `"query-param-not-allowed"` means a `where` field is missing from `queryFields`. |
+| `hasMore` / `total` | From the list response's `more` / `total`. |
+| `fetchNextPage()` | Append the next server page. |
+| `refetch()` | Reload every loaded page in one request, replacing membership. |
+
 ### `useMutate(collection)`
 
 ```typescript
@@ -331,7 +380,7 @@ Returns the `SyncDb` instance from context (escape hatch for imperative calls li
 
 ### `createCollectionHooks`
 
-Factory used by `terreno-syncdb-codegen` and by hand-written custom collections. Returns five operation hooks (`useListQuery`, `useReadQuery`, `useCreateMutation`, `useUpdateMutation`, `useDeleteMutation`). Generated SDKs rename them to friendly names (`useTodos`, `useTodo`, `useCreateTodo`, …). Mutation hooks return `[trigger]`; triggers apply locally and return `{mutationId, id}` synchronously. Optional `retries` maps to `maxAttempts` (`false` → 1, a number → that many, omitted → engine default).
+Factory used by `terreno-syncdb-codegen` and by hand-written custom collections. Returns six operation hooks (`useListQuery`, `useWindowQuery`, `useReadQuery`, `useCreateMutation`, `useUpdateMutation`, `useDeleteMutation`). Generated SDKs rename them to friendly names (`useTodos`, `useTodosWindow`, `useTodo`, `useCreateTodo`, …). `useWindowQuery` works only for collections listed in `queryCollections`. Mutation hooks return `[trigger]`; triggers apply locally and return `{mutationId, id}` synchronously. Optional `retries` maps to `maxAttempts` (`false` → 1, a number → that many, omitted → engine default).
 
 ```typescript
 export const {useListQuery: useNotes, useCreateMutation: useCreateNote} =
@@ -340,6 +389,107 @@ export const {useListQuery: useNotes, useCreateMutation: useCreateNote} =
   });
 ```
 
+## Query windows
+
+Use query windows when a collection is too large to sync whole (messages, events, audit
+rows). They match what an RTK list query did — `where`, `sort`, `limit`, `page`, `more`,
+`total` — but keep the data local-first and deduplicated.
+
+```typescript
+export const syncDb = createSyncDb({
+  collections: ["todos", "messages"],
+  queryCollections: [{collection: "messages", path: "/messages"}],
+  // ...
+});
+```
+
+**Membership, not copies.** A window is one list query against the collection's
+`modelRouter` list endpoint. Its result is an ordered id list stored in the reserved
+`_queryWindows` table. Each row lands once in the collection's entity table, keyed by id.
+Two windows that overlap share those rows:
+
+- A delta, mutation, or refetch for a shared row writes the store once; every window that
+  lists the row re-renders from it.
+- Each window lists only its own members. Window B never shows rows that only window A
+  fetched.
+
+**Live membership.** When `where` is locally evaluable (see `useQuery`'s `where`), a window
+also:
+
+- hides a member whose fields stop matching (an unpinned message leaves the "pinned" window);
+- shows cached rows that newly match (a live delta, or a local create) when they sort inside
+  the loaded range. With more pages unloaded, a row that sorts after the last loaded row
+  waits for `fetchNextPage()`. Without a `sort` and with more pages, only local creates are
+  admitted.
+
+A full fetch also records cached rows that matched `where` locally but that the server did
+not return (deleted, changed, or no longer visible while this device was offline). They stay
+out of the view until a newer delta or a local edit changes them, so stale cached data never
+resurrects a row.
+
+Set `liveMatch: false` to show server membership only. Operators only the server runs
+(`$search`) also fall back to server membership.
+
+**Fetching.** The first `retain` of a window in a session fetches it; persisted membership
+renders meanwhile, so windows work offline. Concurrent fetches of the same window share one
+request; a refetch and a `fetchNextPage()` on one window run one after the other. Retained
+windows refetch on reconnect and after `forceResync()` — query collections
+skip snapshot catch-up, so this is how deltas missed offline are recovered. Windows not on
+screen at that moment refetch the next time they are shown. Window fetches
+started before a `stop()` or user switch are discarded.
+
+**Seq.** List rows that carry `_syncSeq` (the `syncPlugin` field) are written with that seq.
+Rows without it (a `responseHandler` that strips it) are re-read from `GET /sync/entities` so
+a later mutation never sends a stale `baseVersion`. Rows with a pending outbox mutation, or
+with a newer seq from a delta, are never overwritten. A list `responseHandler` must return the
+same shape as the sync serializer; otherwise list rows and delta rows differ.
+
+**Missing `queryFields`.** Every `where` field must be in the route's `queryFields`. The
+server answers 400 `query-param-not-allowed` naming the field, the model, and the allowed
+list. syncdb turns it into `QueryFieldNotAllowedError` (`field`, `allowedQueryFields`,
+`model`), logs it with `console.error`, sets the window's `errorCode` to
+`"query-param-not-allowed"`, and rejects `fetchWindow` / `refetch` / `fetchNextPage` with it.
+Other list failures throw `ListRequestError` (`status`, `code`, `detail`).
+
+```typescript
+import {QueryFieldNotAllowedError} from "@terreno/syncdb";
+
+try {
+  await refetch();
+} catch (error) {
+  if (error instanceof QueryFieldNotAllowedError) {
+    // error.field === "title", error.allowedQueryFields === ["completed", "created", "ownerId"]
+  }
+}
+```
+
+**`maxLimit` and pipelining.** `modelRouter` clamps `limit` to the route's `maxLimit` and
+echoes the applied value. Window requests always send `page` (so the server never logs a
+truncated unpaginated list). When a fetch needs more rows than one request returns — a
+`refetch()` after several `fetchNextPage()` calls, or a `pageSize` above `maxLimit` — syncdb
+learns the cap from the echoed `limit` and splits the range into sequential page requests
+of `maxLimit` rows starting at the aligned page that contains the range, trimming the extra
+rows, so offsets stay exact. Each pipelined fetch logs a
+`console.warn` naming the row count, the cap, and the request count. Fix it by loading fewer
+pages, lowering `pageSize`, or raising `maxLimit` on the route.
+
+**Fully synced collections.** `queryCollections: [{collection: "todos", fullSync: true}]`
+keeps normal snapshot sync and also enables windows, for server-side filtering, paging, and
+totals over a collection that is already local. See `example-frontend/app/todo-windows.tsx`.
+
+**Limits.**
+
+- `refetch()` with several pages loaded reloads `pageSize × pages` rows (see below).
+- Page appends dedupe ids. A delete between page loads can shift offsets and skip one row
+  until the next refetch.
+- `null` in `where` is rejected (qs would send the string `"null"`); use `{$exists: false}`.
+  A top-level `{$in: []}` returns an empty window without a request; an empty array anywhere
+  else throws instead of silently widening the query.
+- Rows stay in the entity table after their windows unmount. `start()` prunes persisted
+  membership of unretained windows not fetched for 7 days (`pruneStale`);
+  `pruneUnretained()` drops all unretained membership. Rows are dropped by leave-purge,
+  tombstone compaction, or a wipe.
+
 ## Codegen
 
 `terreno-syncdb-codegen` is a bin of `@terreno/syncdb`. It reads OpenAPI, discovers list operations with `x-terreno-sync`, and writes typed hooks plus `SYNC_COLLECTIONS`.

package/src/docs/versioned/next/reference/test.md

@@ -79,10 +79,14 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 |----------|--------|
 | `TERRENO_TEST_USE_MEMORY_MONGO` | When `"true"`, `registerSimpleMongoPreload` starts `mongodb-memory-server` if `TERRENO_TEST_MONGODB_URI` is unset. |
 | `TERRENO_TEST_MONGODB_URI` | External MongoDB URI. Takes priority over in-memory server in `startMongoServer` and `registerSimpleMongoPreload`. |
+| `TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` | Per-mongod start timeout for in-memory servers started by `startMongoServer`. Default `60000` (mongodb-memory-server's own default is 10s). Startup is tried twice. |
 | `BUN_TEST_DISABLE_DB` | When `"true"`, `registerBackendPreload` skips all Mongo `beforeAll`/`afterAll` hooks (no DB startup). |
 
 `startMongoServer` also publishes the resolved URI to `TERRENO_TEST_MONGO_URI` and honors `TERRENO_TEST_USE_REPLSET=true` for replica-set memory servers.
 
+If `registerBackendPreload` cannot start Mongo, every later test fails at once with
+`MongoDB test server failed to start` instead of waiting on mongoose command buffering.
+
 ## Exported helpers
 
 | Export | Description |
@@ -92,6 +96,7 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 | `setTerrenoTestEnv` | Apply and validate auth test env vars. |
 | `startMongoServer` / `stopMongoServer` | Start or stop shared in-memory Mongo and connect mongoose. |
 | `getMongoServerUri` | Resolved URI after `startMongoServer`. |
+| `resolveMongoLaunchTimeoutMs` | In-memory mongod launch timeout from `TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` (integer ≥ 1000), default 60000. |
 | `getBaseServer` | Build an Express app for supertest from route registrars. |
 | `authAsUser` | Login helper returning auth headers for supertest. |
 | `createMongoTestCache` | Fixture-cache controller for fast `@terreno/api` tests. |
@@ -112,8 +117,12 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 Package CI uses `scripts/check-coverage.ts` (`bun run test:coverage`, default 95%
 functions and lines) as the live gate. Bun 1.4.2+ may exit 1 on bunfig
 `coverageThreshold` before isolated LCOV merges; the script continues when tests
-reported `0 fail` and then enforces 95% on the merged report. Dedicated CircleCI
-jobs (`api-ci`, `ai-ci`,
+reported `0 fail` and then enforces 95% on the merged report. The blocks
+coverage pass sets `--max-concurrency=1`, because Bun's default 20-way run
+exits 0 on a 2-vCPU worker before it prints the `All files` row. When that
+row is still missing after one retry, the script uses `coverage/lcov.info`
+only if it lists every non-test source file under `src/`. Dedicated CircleCI
+jobs (`api-ci`, `ai-ci`, `blocks-ci`,
 `rtk-ci`, `ui-ci`, `syncdb-ci`, `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run
 that script. Published packages without a dedicated workflow
 (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `@terreno/test`)