@voltro/cli 0.51.0 → 0.53.0

package/templates/agent-docs/database/advancedqueries.md

@@ -379,7 +379,7 @@ Emits `CONSTRAINT <name> UNIQUE (col1, col2, ...)` inline in CREATE
 TABLE on every dialect. Standard SQL.
 
 This is what backs `ctx.store.upsert(..., { conflictColumns: ['a', 'b'] })`
-— see [Bulk operations](/docs/database/bulk-operations#upsert).
+— see [Bulk operations](/docs/database/bulk-operations#upsert-insert-or-update-on-conflict).
 
 ## GiST indexes (PostGIS spatial)
 
@@ -689,7 +689,7 @@ mssql, sqlite 3.8+).
   depend on?"
 
 When you don't have a recursive structure, plain
-[`withCte()`](/docs/database/query-builder#ctes) is enough.
+[`withCte()`](/docs/database/query-builder#ctes-common-table-expressions) is enough.
 
 ## Shape
 
@@ -820,7 +820,7 @@ eager-load with `.with({...})` to get the per-field pre-filter.
 
 ## See also
 
-- [Plain CTEs](/docs/database/query-builder#ctes) — `withCte()` for
+- [Plain CTEs](/docs/database/query-builder#ctes-common-table-expressions) — `withCte()` for
   non-recursive named sub-queries
 - [Self-joins](/docs/database/self-joins) — for single-level
   parent/child queries
@@ -830,7 +830,7 @@ eager-load with `.with({...})` to get the per-field pre-filter.
   `unionAll`, the mechanism a recursive CTE is built on
 - [Joins](/docs/database/joins) — relation-based traversal when the
   graph depth is fixed (e.g. parent + immediate children)
-- [Aggregations](/docs/database/query-builder#aggregations) —
+- [Aggregations](/docs/database/query-builder#aggregates) —
   COUNT/SUM/AVG over a recursive CTE's result set
 
 
@@ -940,7 +940,7 @@ keep the branches' result sets bounded.
   the column-level "in A but not in B" case
 - [Aggregations](/docs/database/aggregations) — `count()` etc. on
   a set-op result is a common pattern
-- [CTEs](/docs/database/query-builder#ctes) — name a complex set-op
+- [CTEs](/docs/database/query-builder#ctes-common-table-expressions) — name a complex set-op
   result so you can reference it in a larger query
 
 
@@ -1044,7 +1044,7 @@ Non-correlated only. The inner query can NOT reference outer-row
 columns like `WHERE inner.userId = users.id`. For correlated
 sub-queries (a common shape: "user who has at least one post created
 in the last hour") use a [Self-join](/docs/database/self-joins) or
-an [Eager-load](/docs/database/joins#eager-loading) — both can
+an [Eager-load](/docs/database/joins#eager-loading-via-with-spec) — both can
 express the same query without the correlation reference.
 
 ## Reactivity
@@ -1069,7 +1069,7 @@ every dialect we ship. No per-dialect dispatch.
   with `count()` etc. for "count of X where Y belongs to Z"
 - [Self-joins](/docs/database/self-joins) — when the relationship
   can be expressed as a join instead
-- [CTEs](/docs/database/query-builder#ctes) — for naming a
+- [CTEs](/docs/database/query-builder#ctes-common-table-expressions) — for naming a
   sub-query you reuse multiple times in the same outer query
 
 

package/templates/agent-docs/database/columntypes.md

@@ -350,7 +350,7 @@ on it explicitly via `.expressionIndex(name, [...], { ... })`.
 
 - [Columns](/docs/database/columns) — `.computed(row => ...)` and
   `.default(() => ...)` for the app-side variants
-- [Indexes](/docs/database/indexes#expression) — `.expressionIndex()`
+- [Indexes](/docs/database/indexes#expression-indexes) — `.expressionIndex()`
   for indexing a generated column
 - [Full-text search](/docs/database/full-text-search) — the FTS
   pattern uses STORED tsvector generated columns
@@ -989,7 +989,7 @@ behavioural gaps are too large to paper over.
 ## See also
 
 - [Columns](/docs/database/columns) — the regular schema-DSL types
-- [Expression indexes](/docs/database/indexes#expression) — the
+- [Expression indexes](/docs/database/indexes#expression-indexes) — the
   framework's index API (`kind: 'gist' | 'gin'` on postgres)
 - [PostGIS docs](https://postgis.net/docs/) — the official manual,
   authoritative for every spatial function the framework re-exports

package/templates/agent-docs/database/querying.md

@@ -309,7 +309,7 @@ The query builder has dedicated pages for the deeper topics:
 - **[Self-joins](/docs/database/self-joins)** — `.as(alias)` +
   `.innerJoin(table, alias, on)` + `.selectJoined({...})` for parent/
   child trees and CTE references.
-- **[CTEs](/docs/database/query-builder#ctes)** — `.withCte(name, sub)`
+- **[CTEs](/docs/database/query-builder#ctes-common-table-expressions)** — `.withCte(name, sub)`
   for named sub-queries reusable inside the outer SELECT.
 - **[Recursive CTEs](/docs/database/recursive-cte)** — `.recursiveCte`
   for tree walks (org hierarchy, comment threads, file folders).

package/templates/agent-docs/database/schema.md

@@ -445,7 +445,7 @@ framework runs on the post-commit change channel.
 **Reach for `reference()` first.** A real foreign key across a plugin boundary
 works and survives the plugin renaming its table, because `reference()` takes
 the table as a VALUE — see
-[plugins/overview](/docs/plugins/overview#pointing-your-table-at-a-plugins-row).
+[plugins/overview](/docs/plugins/overview).
 `pluginRef` is for the case where you have deliberately chosen NOT to have a
 key: it enforces nothing at the database level.
 
@@ -712,7 +712,7 @@ yield* ctx.store.update('documents', input.id, { title: input.title, version: in
 
 **Why not `updatedAt`.** A timestamp cannot do this job. Two writes in the same millisecond are indistinguishable, and across replicas the clocks disagree — a comparison that looks correct in a test loses rows under load. An integer the database owns is totally ordered and needs no clock. (`.version()` therefore rejects a `text()` or `timestamp()` column at declaration.)
 
-**What it does not do.** It is not a history — it records *that* a row changed, not what to; use [`plugin-versioning`](/docs/plugins/versioning) for that. It is not a lock: a conflict is **reported**, never queued or merged, because merging two intents is a decision only your application can make. And it is not a retry — "re-apply my change on top of theirs" is correct for some changes and wrong for others, so you write it.
+**What it does not do.** It is not a history — it records *that* a row changed, not what to; use [`plugin-row-history`](/docs/plugins/row-history) for that. It is not a lock: a conflict is **reported**, never queued or merged, because merging two intents is a decision only your application can make. And it is not a retry — "re-apply my change on top of theirs" is correct for some changes and wrong for others, so you write it.
 
 **Three details worth knowing:**
 

package/templates/agent-docs/database/seedsdialects.md

@@ -543,7 +543,7 @@ and cannot be engineered away:
 - **`old` is null on an oversized update, and pk-only on an oversized delete.**
   There is nowhere to read a pre-image from. A tombstone is enough to REMOVE the
   row from a search index, an analytics mirror or a CDC stream; it is not a
-  record of what the row contained, and `@voltro/plugin-versioning` writes
+  record of what the row contained, and `@voltro/plugin-row-history` writes
   `data: null` for one rather than a fabricated empty snapshot.
 - **`'unrecovered'` means the content is gone.** No retry can bring it back —
   it was never delivered. Subscriptions are unaffected (they re-query); taps
@@ -1055,7 +1055,7 @@ MariaDB's GTID format differs from MySQL's: `0-1-100` (domain-server-sequence) v
 - **`mariadb` schema package is wire-compatible with `mysql`**. If you migrate from MySQL → MariaDB, the framework re-emits DDL cleanly via `applySchema(..., 'mariadb')`. Production data round-trips through `mysqldump` without translation.
 - **`sql_mode=NO_BACKSLASH_ESCAPES`** is sometimes set on MariaDB deploys. The framework's identifier escaping handles it, but user-written `unsafe()` strings that hand-escape backslashes may produce wrong output. Leave that mode off if you can.
 - **Sequence-based ID columns**. MariaDB has true CREATE SEQUENCE; the framework doesn't use it (TypeID / ULID / Snowflake are client-side). If you reach for sequences for legacy reasons, they're outside the framework's auto-injection path.
-- **Hand-rolled `AUTO_INCREMENT` primary keys** work the same as on mysql: an `insert` / `insertMany` with no client-side `id` recovers the DB-generated id via `LAST_INSERT_ID()` (connection-pinned; `insertMany` recovers the whole consecutive range). See the [mysql page](/docs/database/dialects/mysql#auto_increment-ids--last_insert_id-recovery) for the worked example — the recovery path is identical on both engines.
+- **Hand-rolled `AUTO_INCREMENT` primary keys** work the same as on mysql: an `insert` / `insertMany` with no client-side `id` recovers the DB-generated id via `LAST_INSERT_ID()` (connection-pinned; `insertMany` recovers the whole consecutive range). See the [mysql page](/docs/database/dialects/mysql) for the worked example — the recovery path is identical on both engines.
 
 ## Where it lives
 

package/templates/agent-docs/database/transactions.md

@@ -261,7 +261,7 @@ await ctx.store.upsert('orgSlugs', {
 ```
 
 Requires a composite UNIQUE constraint on the table — declare it via
-`.unique([cols])` in the schema (see [Indexes](/docs/database/indexes#composite-unique)).
+`.unique([cols])` in the schema (see [Indexes](/docs/database/indexes#composite-unique-constraints)).
 
 ## `insertIgnore` — keep existing on conflict
 
@@ -314,7 +314,7 @@ const count = await ctx.store.updateMany('posts', { hidden: true }, {
 // count: number of rows actually updated
 ```
 
-The `where` predicate is a regular [Predicate](/docs/database/query-builder#predicates)
+The `where` predicate is a regular [Predicate](/docs/database/query-builder)
 AST — same shape `.where()` uses. Sub-queries via `inSubquery` /
 `exists` are supported.
 
@@ -395,5 +395,5 @@ matters.
   `aggregate()` for read-side bulk reads
 - [Sub-queries](/docs/database/sub-queries) — `inSubquery` /
   `exists` in `updateMany` `where:` clauses
-- [Composite UNIQUE](/docs/database/indexes#composite-unique) — for
+- [Composite UNIQUE](/docs/database/indexes#composite-unique-constraints) — for
   the constraint that backs `upsert`'s `conflictColumns: ['a', 'b']`

package/templates/agent-docs/deployment.md

@@ -312,11 +312,15 @@ cause.
 When one api process isn't enough:
 
 1. Run multiple api containers behind the reverse proxy. The proxy's load-balancing default (round-robin) is fine for HTTP — for WebSocket, use sticky sessions (Caddy: `lb_policy ip_hash`).
-2. Install `@voltro/plugin-cluster` in `app.config.ts.plugins`. It sets up cross-instance subscription invalidation via Postgres NOTIFY (or Redis if you set `CLUSTER_TRANSPORT=redis`).
+2. Cross-instance subscription invalidation: on Postgres (LISTEN/NOTIFY) and MySQL/MariaDB (binlog CDC) this is built in — nothing to install. On any other dialect, or when you prefer a broker, add [`@voltro/plugin-broadcast`](/docs/plugins/broadcast) with a Redis or NATS provider to `app.config.ts.plugins` so every replica sees every change.
 3. Workflows: `@effect/cluster` shards work across instances by workflow ID. No further config — every instance pulls from the shared workflow queue.
 
 For multi-region: you need to run Postgres logical replication between regions yourself (or move to Voltro Cloud which handles it).
 
+### Scaling is replicas, not a service split
+
+Voltro deliberately ships no microservice transports — no `@MessagePattern`-style service-to-service RPC, no broker-backed internal messaging layer. Splitting one app into services would contradict the architecture thesis this whole page rests on: **one monolith process, scaled by running more replicas of it**, with `@effect/cluster` sharding durable work across instances by workflow ID. Every capability that a service split usually buys already has a first-class path: an external system boundary is [REST routes](/docs/data/rest-routes) + [OpenAPI](/docs/plugins/openapi) (`@voltro/plugin-openapi`), and a reliable outbound side effect is the [transactional outbox](/docs/data/outbox). If you find yourself wanting an internal message bus between "services", the answer is more replicas of the same image — not a second process shape.
+
 ## Backups
 
 Postgres is the source of truth. Use your provider's backup features (Neon PITR, RDS snapshots, `pg_dump` on a cron). Object-storage assets back up via the provider's lifecycle policies.
@@ -1008,6 +1012,7 @@ indexed query instead of scanning every table). Force a full re-introspect with
 
 ```sh
 VOLTRO_MAX_RPC_BODY_BYTES=8388608   # default 8 MiB
+VOLTRO_MAX_BODY_BYTES=8388608       # default 8 MiB
 ```
 
 A declared `Content-Length` over the cap is refused up front, so an honest client
@@ -1114,6 +1119,14 @@ VOLTRO_LOG_FORMAT=json
 VOLTRO_LOG_LEVEL=info
 ```
 
+In `json` mode (the default off a TTY, so a pod gets it without configuration)
+EVERY line the framework emits is a parseable record — the boot banner, the app
+surface, `voltro db apply`'s plan summary, refusal detail, and every subsystem
+logger (schedule, broadcast, workflow, flow-control). A hand-formatted table or
+a `[tag]`-prefixed adapter line between JSON records is a bug, not a style: log
+collectors show it as unparsed noise. On a TTY the same surfaces render as the
+human-readable banners and tables.
+
 **Error reporting** — add `sentryPlugin()` from `@voltro/plugin-sentry`. It stays inert until `SENTRY_DSN` is set, and reported errors correlate to the request `traceId`:
 
 ```ts
@@ -1401,7 +1414,7 @@ Lower the lease for **faster failover**, at the cost of **false-positive reclaim
 - [ ] Liveness / readiness probes point at `/internal/liveness` + `/internal/readiness`
 - [ ] Serving pods run `voltro serve` (not `voltro dev`), with `VOLTRO_AUTO_MIGRATE=0`
 - [ ] Schema applied by a pre-deploy Job / initContainer (`voltro db apply`), not in the serving pod
-- [ ] `VOLTRO_MAX_RPC_BODY_BYTES` sane; ingress caps body size + per-IP rate
+- [ ] `VOLTRO_MAX_RPC_BODY_BYTES` + `VOLTRO_MAX_BODY_BYTES` (plugin routes/webhooks) sane; ingress caps body size + per-IP rate
 - [ ] `VOLTRO_TRUSTED_PROXIES` set if you run behind an ingress AND rate-limit per IP
 - [ ] `VOLTRO_ALLOWED_ORIGINS` set if the web app is on a different origin than the api
 - [ ] Security headers reviewed (`VOLTRO_SECURITY_HEADERS`, `VOLTRO_CSP`); HSTS reaching the browser over https
@@ -1759,7 +1772,7 @@ and the drill is the part people skip.
 ## Which one
 
 | | scale-to-zero | managed DB | rolling deploys | cost floor |
-|---|---|---|---|---|
+| --- | --- | --- | --- | --- |
 | Fly.io | yes (`auto_stop`) | Fly Postgres | yes | ~0 idle |
 | Railway | usage-based sleep | built-in | yes | ~0 idle |
 | Render | paid plans only | built-in | yes | fixed/instance |
@@ -1768,3 +1781,17 @@ and the drill is the part people skip.
 An api that owns cron schedules should not scale to zero. An api with bursty
 traffic and no schedules is exactly what scale-to-zero is for. When in doubt,
 the boring answer — one always-on instance — is also the cheapest to operate.
+
+## Why there is no edge-SSR adapter
+
+Every recipe above deploys a container, and that is deliberate: Voltro's SSR is
+Node-first (`renderToPipeableStream` into a Node stream, `voltro start` as a
+long-running Node HTTP server), not a Workers/edge runtime — so there is no
+Vercel-/Netlify-edge SSR adapter, and none is planned as a posture. The edge
+still gets first-class use where it fits the model: isolated
+[`*.serverless.ts` functions](/docs/deployment/serverless-functions)
+(`@voltro/serverless`, with Cloudflare / Scaleway / Node adapters) for
+request-shaped work at the edge, and
+[static / ISR pages](/docs/deployment/static-sites) served from a CDN for
+everything that does not need a per-request render. If a page must render per
+request, it renders in the container.

package/templates/agent-docs/internationalization.md

@@ -96,7 +96,7 @@ The client **adopts what the server resolved**, reading it from the `<html lang>
 | `data-voltro-tz` | the IANA zone every date/time formatter renders in — set `timeZone` in `app.config.ts` |
 | `data-voltro-now` | the server's render instant, so `useRelativeTime` produces the same string in the hydration pass |
 
-Locale was already agreed; the zone and the clock were each read from the ambient runtime, which meant a server-rendered timestamp was a hydration mismatch waiting for a wide enough offset or a slow enough connection. See [Plurals & formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr--the-setting-that-is-not-a-preference) — that is the page to read before you migrate hand-rolled `toLocaleString()` calls onto the hooks.
+Locale was already agreed; the zone and the clock were each read from the ambient runtime, which meant a server-rendered timestamp was a hydration mismatch waiting for a wide enough offset or a slow enough connection. See [Plurals & formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr-the-setting-that-is-not-a-preference) — that is the page to read before you migrate hand-rolled `toLocaleString()` calls onto the hooks.
 
 See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, [Plurals & formatting](/docs/i18n/formatting) for CLDR plural selection and the `Intl`-backed date / number / relative-time hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
 
@@ -951,7 +951,7 @@ default, so call sites don't handle a missing-service error.
 > request, publishes it on the document, and every `@voltro/i18n` formatter on
 > both sides of the hydration boundary uses it. Read it with `useTimeZone()`
 > from `@voltro/i18n`. See
-> [Formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr--the-setting-that-is-not-a-preference).
+> [Formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr-the-setting-that-is-not-a-preference).
 >
 > The **server-side compute zone** — what `startOfDay` or a workflow's "same
 > time tomorrow" resolves against inside a handler — is still the SEAM only.

package/templates/agent-docs/introduction.md

@@ -132,6 +132,22 @@ Voltro is deliberately opinionated about boring things (HTTP, state, transport,
 - **Magic.** Every file convention is documented; every generated file lives in `.framework/` and you can read it.
 - **Codegen you have to remember to run.** Schema flows from your tables to your React components automatically via Vite's module graph.
 
+## Deliberate noes
+
+Two questions come up in every framework comparison. Both are decided — deliberately no — and here is why, so nobody has to re-litigate them.
+
+### Why is there no GraphQL API?
+
+1. **GraphQL's three core promises are solved differently here.** Type-safe selective reads ⇒ typed queries + schema inference. One endpoint for every client ⇒ the RPC socket with a generated client. Third-party consumers ⇒ [REST routes](/docs/data/rest-routes) + [OpenAPI 3.1](/docs/plugins/openapi) (`@voltro/plugin-openapi`).
+2. **A GraphQL gateway would have no access to the reactivity path** — source-based invalidation, per-delivery guards. It would be a second, dead read path whose results are never live: exactly the kind of duplicate path this framework refuses to keep.
+3. **Resolver N+1, persisted-query complexity, and a second permission model** (field-level vs. our guards/RLS) buy nothing the existing surface cannot do.
+
+Don't build a GraphQL layer over the stores. External consumers get REST + OpenAPI; internal clients get RPC + live subscriptions.
+
+### Why not React Server Components?
+
+RSC is a second rendering **and** data model — Flight serialization, `'use client'` boundaries, deep bundler integration — that would compete with the reactive subscription model instead of composing with it. The problems it solves are covered by what exists today: [islands](/docs/routing/islands) for shipping less JS, loaders for server data at render time, and streaming SSR with `defer()` for progressive delivery. Don't write `'use server'` / `'use client'` directives in a Voltro app; they mark a boundary this framework does not have.
+
 ## Where to read next
 
 - [Getting started](/docs/intro/getting-started) — scaffold + boot in under a minute
@@ -435,6 +451,7 @@ Voltro replaces router and registry config with **filesystem conventions**. Drop
 | `*.agent.server.tsx` | Server agent **executor**: `defineAgentExecutor(descriptor, { system, tools, model, maxSteps })`. | Agent runtime. |
 | `*.tool.tsx` | A tool an agent can call. Schema + handler. | Agent runtime. |
 | `*.webhook.tsx` | Outgoing webhook spec (target, retry, schema). | Webhook delivery worker. |
+| `*.ws.ts` | Raw WebSocket gateway — `defineWebSocket({ path, auth, onConnection })` as the default export, for FOREIGN protocols beside the rpc socket. | Upgrade listener on the api server, both boot paths. |
 | `*.entity.ts` | Database table — one table per file: `table()` + columns + mixins. Re-exported from a `database/index.ts` barrel. | Migrations + the runtime data store. |
 | `*.config.ts` | App-level config (`app.config.ts`, `tsconfig.json`, etc.). | The CLI. |
 
@@ -470,6 +487,25 @@ Without the marker the leak is still caught — by the rpcGroup guard — but on
 
 An unmarked file makes no claim, and that is fine: `*.client.ts` is for the shared files where the mistake is expensive, not a label to sprinkle on everything.
 
+### Raw WebSocket gateways: `*.ws.ts`
+
+A `*.ws.ts` file's default export mounts a raw WebSocket upgrade path beside the rpc socket — for a protocol the framework does not speak (a Yjs provider, a legacy device fleet). Discovered on **both** boot paths, `voltro dev` and `voltro serve`:
+
+```ts
+// gateways/collab.ws.ts
+import { defineWebSocket } from '@voltro/protocol'
+
+export default defineWebSocket({
+  path: '/gateways/collab',
+  auth: 'subject',   // REQUIRED, no default — or 'public', a decision you write down
+  onConnection: ({ send, onMessage, subject }) => {
+    onMessage((data) => send(data))   // your protocol, your frames
+    return () => { /* teardown — runs on disconnect, credential expiry, shutdown */ }
+  },
+})
+```
+
+`auth: 'subject'` authenticates through the same chain as rpc/SSR **before** the upgrade (401 while it is still http) and binds the connection to the credential's expiry (close code `4001`); every gateway path is origin-checked at upgrade. Two gateways on one path refuse the boot; a plain GET on a gateway path answers `426`. App realtime stays [subscriptions](/docs/data/subscriptions) — full detail under [Raw WebSocket gateways](/docs/data/subscriptions#raw-websocket-gateways-definewebsocket).
 
 ## The web side (`apps/*/web/`)
 
@@ -482,6 +518,10 @@ An unmarked file makes no claim, and that is fine: `*.client.ts` is for the shar
 | `src/pages/loading.tsx` | Pending UI shown while loaders resolve. |
 | `src/pages/(group)/` | Route group — does not contribute a URL segment, but layout/error files inside still apply. |
 | `src/*.island.tsx` | A client-side hydration island (split chunk). Used in `interactive: 'islands'` pages. |
+| `src/**/*.collection.ts` | A content collection declaration (`defineCollection`) — schema-typed markdown/JSON under `content/<name>/**`. See [Content collections](/docs/data/content-collections). |
+| `src/**/*.consumer.ts` | A queue consumer (`defineQueueConsumer`, @voltro/plugin-queue) — Schema-decoded, at-least-once, serial per partition. See [Queue](/docs/plugins/queue). |
+| `grpc.manifest.json` | The gRPC field-number manifest (checked in — append-only wire identity; deletes go `reserved`). See [gRPC surface](/docs/data/grpc). |
+| `content/<name>/**` | A collection's content files (markdown with frontmatter, or `.json` for data collections). Read by `getCollection`/`getEntry`. |
 
 Each page can opt into a render strategy via two exports:
 
@@ -494,6 +534,16 @@ export const interactive = 'islands' as const      // 'none' | 'islands' | 'full
 - `renderMode` controls when the HTML is produced (build vs. request).
 - `interactive` controls how much JS ships (`'none'` strips it all, `'full'` hydrates the page, `'islands'` hydrates only `.island.tsx` files).
 
+A page can also declare its query-string contract as a page export:
+
+```tsx
+export const searchParams = Schema.Struct({
+  page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+})
+```
+
+- `searchParams` (an `effect/Schema` struct — every field optional or with a default) types the page's query string: `useSearchParams(searchParams)` returns the decoded shape, and links built with `withQuery` type-check against it. Details: [Pages → Query strings](/docs/routing/pages#query-strings).
+
 ## Discovery in practice
 
 ```text
@@ -553,6 +603,8 @@ If yes, the promise belongs in the name — you cannot see a contract before you
 | `*.tracking.ts` | analytics happens nowhere else | `tracking/outside-tracking-file` |
 | `*.client.ts` | it and its imports are browser-safe | boot-time import walk, `client/not-browser-safe` |
 | `*.store.ts` | exactly one `defineStore`, no server state | `store/one-per-file`, `store/mirrors-server-state` |
+| `*.collection.ts` | declares content collections (`defineCollection`); frontmatter schema violations fail the build naming the file | the build's collection decode + reference validation |
+| `*.consumer.ts` | declares queue consumers (`defineQueueConsumer`, @voltro/plugin-queue); loading registers, the plugin's activation starts them | the queue runner (decode→DLQ, retry→DLQ, commit-per-message) |
 
 A `*.component.tsx` promises exactly ONE component. It does not promise to export nothing else: types, and plain module-local values a `const COLUMNS = […]` beside the table that renders them, are fine and always were. What the rule counts is components — a declaration that renders — so an object, an array, a string or a `new` beside your component is not a second one, and neither is `export default Card` next to `export const Card`.
 

package/templates/agent-docs/local-first-mobile.md

@@ -26,10 +26,14 @@ imports it directly. The React wrappers live behind `@voltro/local-first/react`
 > transport, [`useCrdtText`](#a-collaborative-text-field-usecrdttext) — the React
 > binding for a collaborative text field — [presence/awareness](#presence--awareness)
 > via `usePresence`, [durable IndexedDB persistence](#durable-persistence), and the
-> [`localFirst` table mixin](#the-localfirst-table-mixin). What remains is a thin
-> [runtime binding](#whats-shipped-vs-a-runtime-seam) to provisioned infra
-> (a broker at scale) plus the two app-specific tags `useCrdtText` is pointed at —
-> not un-built framework code.
+> [`localFirst` table mixin](#the-localfirst-table-mixin). What remains falls in
+> two tiers: a thin [runtime binding](#whats-shipped-vs-a-runtime-seam) to
+> provisioned infra (a broker at scale) plus the two app-specific tags
+> `useCrdtText` is pointed at — and the sync **engine**, which is now BUILT:
+> the [query mirror](#the-sync-engine-query-mirror--durable-outbox) persists
+> every subscribed query's rows per subject+tenant partition, `useOutbox`
+> queues offline writes durably, and a reload renders mirrored rows offline
+> and delta-resumes online.
 
 ## CRDT text: `crdtText` + `mergeCrdtStates`
 
@@ -204,6 +208,26 @@ import { Schema } from 'effect'
 body: Schema.NullOr(Schema.Uint8ArrayFromBase64)
 ```
 
+### Known cost limits of `crdtText()` today
+
+Two amplification effects are worth knowing before you put a `crdtText()` column
+on a hot editing path — both are per-keystroke costs, and both are real today:
+
+- **Wire amplification downstream.** A subscription delta carries the row's
+  columns, and for a CRDT column that is the merged **full state** (base64) —
+  every keystroke ships the whole document to every subscriber of the query,
+  not the one-edit update. Keep the streamed query's projection narrow (don't
+  project `body` into a list view), or subscribe to the document row alone.
+- **Undo/row-history capture.** Server-side capture (the undo log — default-on
+  outside production — and `plugin-row-history`'s row history, where enabled)
+  snapshots the row per mutation, so per-keystroke mutations write a
+  full-state blob per keystroke into those tables. Point them away from
+  CRDT-heavy tables, or batch edits before pushing.
+
+Both limits are on the framework's roadmap (incremental delivery and
+CRDT-aware capture); until then they are costs to design around, not bugs to
+report.
+
 ## Presence & awareness
 
 `usePresence(roomId, self, { channel })` publishes this peer's ephemeral state
@@ -292,6 +316,103 @@ const adapter = await createIndexedDbPersistence({ databaseName: 'my-app' })
 const sync = createSyncClient({ transport, adapter }) // state now survives reload
 ```
 
+## Rich text: `crdtDoc()` + `useCrdtEditor`
+
+`crdtDoc()` stores a WHOLE collaborative document (rich text, maps, arrays)
+as a column — same storage and authoritative server merge as `crdtText()`,
+which stays as the plain-text specialisation. The editor binding is Tiptap
+(`@voltro/local-first/editor`, optional peers): `useCrdtEditor({ doc })`
+binds one editor to the document handle; content edits ride the app's
+mutation (folded server-side under a per-row mutex) and remote edits arrive
+as incremental `mergeCells` subscription deltas — a one-character edit ships
+under 1 KB in BOTH directions regardless of document size.
+
+Carets ride a `delivery: 'latest'` EVENT, deliberately not presence
+metadata: the roster's value-compare push would make every caret move a
+"real" change. `attachAwarenessBridge` publishes one member's state per
+envelope (never the aggregated room). Stable positions for inline comments
+come from `encodeAnchor`/`resolveAnchor` on the doc handle.
+
+Operational rules: the stored blob soft-compacts past
+`VOLTRO_CRDT_COMPACT_MAX_BYTES` (default 512 KiB) without breaking the merge
+lineage; `rebaseText` is the explicit hard reset (a NEW EPOCH — subscribers
+receive it as a fresh snapshot). CRDT columns are excluded from undo capture
+and row history (document history = named snapshots taken BEFORE
+compaction); `.serverOnly()` on a CRDT column is a declaration error and
+`.encrypted()` makes it online-only.
+
+## The sync engine: query mirror + durable outbox
+
+The engine's two halves ride the primitives you already use — there is no
+second data API:
+
+- **Reads.** The subscription cache accepts a `mirror`; every base movement of
+  every subscribed query persists (rows + revision) into a **subject+tenant
+  partitioned** store over IndexedDB, and a cold start seeds from it — the UI
+  renders the last materialised rows offline through the SAME
+  `useSubscription` call, and the next connect presents the mirrored revision
+  as `voltro-resume-from`, so a reload inside the resume window continues with
+  deltas instead of a snapshot.
+- **Writes.** `useOutbox` with `persistence: outboxPersistence(adapter)` is
+  the durable offline queue: writes survive a reload, replay in order on
+  reconnect, stop at the first conflict, and a conflict resolves through
+  `resolveConflict(id, resolveWithPolicy(policy, local, remote, { crdtColumns }))`
+  — `crdtText()` columns merge, scalars follow the declared `conflictPolicy()`.
+  One drain per device even with many tabs (`withDrainLock`, a per-partition
+  Web Lock).
+
+```ts
+import {
+  createDurableKv, createQueryMirror, createSubscriptionMirrorBinding,
+} from '@voltro/local-first'
+import { localFirstTables } from './.framework/localFirst.generated'
+
+const { kv, durability } = await createDurableKv()          // 'memory' = visible degradation
+const mirror = createQueryMirror(kv, { subjectId, tenantId }) // ONE partition per subject
+const binding = createSubscriptionMirrorBinding(mirror, {
+  tags: { 'docs.list': 'docs' },                            // the app's sync set
+  metadata: localFirstTables,                               // codegen: encrypted columns stripped
+  schemaFingerprint: BUILD_ID,                              // local-DB migration gate
+})
+```
+
+The deliberate design decision, recorded here because the obvious alternative
+keeps being suggested: the engine is **not** a browser SQL database. The
+client's whole query surface is `(tag, input)` — predicates are built and
+evaluated on the server — so a wa-sqlite instance would evaluate a language
+the client never sees. What offline needs is the last materialised answer per
+query the user visited, kept current by deltas; that is what the mirror
+stores. (The `KvStore` seam still admits a SQLite backing without touching a
+consumer.)
+
+Soundness rules, all enforced structurally and tested:
+
+- **Partition by key.** Every stored key carries subject AND tenant; a
+  logout/login as somebody else can never read the predecessor's rows, and
+  `purge()` empties exactly one partition on revocation. Build ONE binding per
+  resolved subject and rebuild it on an auth change — the same blank-on-auth
+  doctrine the subscription cache itself follows.
+- **`.encrypted()` never lands.** The server decrypts on read, so a naive
+  mirror would persist plaintext on the device; the codegen-emitted
+  `localFirst.generated.ts` names those columns and the binding strips them
+  before every save. `.serverOnly()` columns never reach the wire at all.
+- **The snapshot is the visible state.** A save replaces the mirrored row
+  set, so a row the server stopped sending (revoked share, RLS change, soft
+  delete) is evicted by construction.
+- **Schema migration is a visible cold start.** Entries persist under the
+  build's `schemaFingerprint`; a new build's load misses them and the query
+  falls back to loading → fresh snapshot — never a mixed-shape render. The
+  offline queue deliberately does NOT gate on it: a queued old-shape write
+  replays against the new server, whose input schema is the authority, and a
+  rejection surfaces as a visible conflict instead of silently dropped work.
+- **Shapes are your queries.** There is no separate replication-shape
+  language: what is mirrored is exactly what the app subscribes to, so tenant
+  scoping, guards and `setRowFilter` apply server-side, fail-closed, exactly
+  as online — including parent-relative predicates ("tasks where projectId is
+  one of my projects"), which are just queries. Mirroring is per QUERY, so a
+  subgraph is N queries, not one nested shape. A storage budget is enforced
+  with `enforceBudget(maxBytes)` — oldest-saved entries evict first.
+
 ## Conflict policy for non-CRDT fields
 
 CRDT fields resolve themselves — the merge **is** the resolver. A plain scalar
@@ -348,9 +469,13 @@ constructs the `ApiHandle` (runtime + subscription cache + rpc client) over a
 WebSocket **you** inject, so RN passes its own `globalThis.WebSocket` and gets
 the same client stack the web app uses, without pulling in `@voltro/web`.
 
-Still open before the loop is proven end-to-end on a device: codegen emitting the
-api's rpc group for a mobile app, an RN persistence adapter, a NetInfo connection
-signal, and a reconnect supervisor. `@voltro/react-native` ships the
+Still open before the loop is proven end-to-end on a device: the device boot
+itself — everything here is unit-tested without a simulator, so booting a real
+Metro runtime is the remaining verification — plus `*.deepLink.ts` codegen
+discovery (until it lands, register links via `matchFirstDeepLink(links, url)`),
+push **sender** adapters (APNs / FCM need per-tenant credentials), and
+native-module bindings (camera, biometrics, secure token storage need a native
+runtime). `@voltro/react-native` ships the
 mobile-specific plumbing around that, limited to the parts that need **no
 per-tenant credentials and no native runtime**: device registration,
 background-sync scheduling, offline-first defaults, a connection-status surface,

package/templates/agent-docs/observability.md

@@ -73,6 +73,8 @@ Even with no exporter, `voltro dev` installs a **buffer-only** tracer — that's
 
 Separate from tracing, the framework records **metrics** into Effect's global `MetricRegistry` — one source of truth (`voltro_rpc_*`, `voltro_http_*`, `voltro_plugin_hook_*`, `voltro_subscription_*` + `voltro_subscriptions_active`, `voltro_db_*`, plus `effect_fiber_*` and any custom metric). Three ways to get them out:
 
+The **web server** additionally counts [partial prerendering](/docs/routing/render-modes#partial-prerendering-ppr--cached-shell--per-request-holes): shell serves, hole passes/settles/errors, and last/max hole latency. Shell hit-rate is the isr cache's own `x-voltro-cache` HIT/STALE/MISS accounting — a ppr shell is a normal isr entry.
+
 ```bash
 # OTLP metrics — the SAME OTEL endpoint that enables trace export also enables
 # metrics. Ships to any OTLP/HTTP collector (Prometheus OTLP, Grafana Agent,

package/templates/agent-docs/plugins/ai-flows.md

@@ -356,7 +356,7 @@ import { Effect } from 'effect'
 export default defineSchedule({ cron: '*/15 * * * *', timezone: 'Europe/Berlin', handler: (s) => Effect.promise(() => runCadenceTick(s.app)) })
 ```
 
-Adopt `@voltro/plugin-versioning` on `_voltro_ai_flows` for automatic edit history.
+Adopt `@voltro/plugin-row-history` on `_voltro_ai_flows` for automatic edit history.
 
 ## Deployment notes
 

package/templates/agent-docs/plugins/audit.md

@@ -86,7 +86,7 @@ auditPlugin({ sink: 'datastore', record: 'errors' })
 ```
 
 - `'all'` (default) — every invocation.
-- `'errors'` — refusals only: a denied guard, a revoked key, a rejected validation. This is the forensic core, and it pairs with [`@voltro/plugin-versioning`](/docs/plugins/versioning), which records the successful *writes* — so the two together still cover everything while this table stays small enough that retention is a footnote.
+- `'errors'` — refusals only: a denied guard, a revoked key, a rejected validation. This is the forensic core, and it pairs with [`@voltro/plugin-row-history`](/docs/plugins/row-history), which records the successful *writes* — so the two together still cover everything while this table stays small enough that retention is a footnote.
 - a predicate — `(event) => boolean`, for anything else.
 
 `'all'` is the default even though `'errors'` is often the right choice, because defaulting to errors would silently stop recording successes for every app that upgrades — and "what did this compromised account touch" is answered by successes. Shrinking the trail is a decision you make with your eyes open.
@@ -166,7 +166,7 @@ The trail is only useful if you can enter it by the questions an incident asks.
 
 ```ts
 import { auditByTrace, auditBySubject } from '@voltro/plugin-audit'
-import { historyByTrace } from '@voltro/plugin-versioning'
+import { historyByTrace } from '@voltro/plugin-row-history'
 
 // What happened during ONE call — and what it changed.
 const calls   = await auditByTrace(ctx.store, traceId)
@@ -176,7 +176,7 @@ const changed = await historyByTrace(ctx.store, traceId, ctx.request.subject.ten
 const denied = await auditBySubject(ctx.store, actorId, { status: 'error', limit: 50 })
 ```
 
-`traceId` is the join key. [`plugin-versioning`](/docs/plugins/versioning) records *what changed*; this records *who called and whether they were refused*. Neither is complete alone, and before the join key existed they could not be read together at all.
+`traceId` is the join key. [`plugin-row-history`](/docs/plugins/row-history) records *what changed*; this records *who called and whether they were refused*. Neither is complete alone, and before the join key existed they could not be read together at all.
 
 `auditBySubject` takes `status` as a real argument rather than leaving you to filter in JS: the index is `(subjectId, status, at)`, so a filter applied after fetching would not use it.
 
@@ -300,7 +300,7 @@ philosophies.
 
 That matters because the right to be forgotten is one this framework grants:
 `@voltro/plugin-governance`'s `governance.erase` (`delete | anonymize`) exists
-for it. Without a snapshot, installing audit + versioning + governance together
+for it. Without a snapshot, installing audit + row-history + governance together
 makes the first two unreadable for exactly the subjects an investigation is
 about. **Anonymisation is the worse half**: the join succeeds and returns
 "Anonymised" for every entry that actor ever produced, retroactively rewriting
@@ -392,7 +392,7 @@ auditPlugin({
     typeof ctx.input?.teamId === 'string' ? { teamId: ctx.input.teamId } : undefined,
 })
 
-versioningPlugin({
+rowHistoryPlugin({
   // From the ROW here — that is what this plugin has.
   resolveScope: (row) => ({ teamId: row.teamId }),
 })

package/templates/agent-docs/plugins/auth.md

@@ -333,7 +333,7 @@ authRoutesPlugin({
 })
 ```
 
-The canonical guard ships in `@voltro/plugin-deactivation`: `deactivationGuard()` refuses login when the user's `deactivatedAt` is set — making the `deactivation()` mixin's "a deactivated user can't log in" promise self-enforcing without a hand-rolled resolver check. See [deactivation](/docs/plugins/deactivation#enforcing-a-deactivated-user-cant-log-in). With no guards configured, every authenticated user proceeds exactly as before.
+The canonical guard ships in `@voltro/plugin-deactivation`: `deactivationGuard()` refuses login when the user's `deactivatedAt` is set — making the `deactivation()` mixin's "a deactivated user can't log in" promise self-enforcing without a hand-rolled resolver check. See [deactivation](/docs/plugins/deactivation). With no guards configured, every authenticated user proceeds exactly as before.
 
 ## Rehash-on-verify
 

package/templates/agent-docs/plugins/cdc-out.md

@@ -1,6 +1,6 @@
 # CDC-out (reverse-ETL)
 
-> Declaratively mirror table changes outward to external sinks (webhook / Kafka / Snowflake / BigQuery) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.
+> Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.
 
 
 
@@ -9,7 +9,7 @@
 <!-- source: en/plugins/cdc-out.md -->
 ## CDC-out (reverse-ETL)
 
-_Declaratively mirror table changes outward to external sinks (webhook / Kafka / Snowflake / BigQuery) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered._
+_Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered._
 
 # CDC-out — declarative reverse-ETL