@voltro/cli 0.51.0 → 0.52.0

package/templates/agent-docs/data.md

@@ -2195,6 +2195,35 @@ mysql/mariadb (binlog), so a second node needs no extra wiring — the cost bein
 budgeted here is the matcher and re-query CPU each node spends on ITS OWN
 clients.
 
+## Raw WebSocket gateways — `defineWebSocket`
+
+Everything above rides the framework's subscription protocol, and that stays the answer for app realtime — live queries, optimistic patches, reconnect. A **gateway** exists for the other case: a FOREIGN protocol that needs a socket the framework does not speak — a Yjs provider, a legacy device fleet, an MQTT-over-WS bridge. It mounts its own upgrade path beside the rpc socket, in a `*.ws.ts` file discovered on **both** boot paths:
+
+```ts
+// gateways/yjs.ws.ts
+import { defineWebSocket } from '@voltro/protocol'
+
+export default defineWebSocket({
+  path: '/gateways/yjs',
+  auth: 'subject',   // REQUIRED, no default: 'subject' | 'public'
+  onConnection: ({ send, close, onMessage, subject, headers, path }) => {
+    const doc = attachDoc(subject!.id)
+    onMessage((data) => doc.applyUpdate(data))     // binary-safe frames
+    const stop = doc.onUpdate((update) => send(update))
+    return () => { stop(); doc.release() }          // teardown
+  },
+})
+```
+
+The contract, in the order it protects you:
+
+- **`auth` is mandatory and has no default.** `'subject'` runs the SAME auth chain as rpc/SSR *before* the upgrade — an unauthenticated caller gets `401` while the request is still plain http, and the connection is bound to the credential's expiry: when it lapses, the socket closes with application code `4001`, so a foreign client can re-auth and reconnect. `'public'` is a deliberate, written-down decision (a device fleet with protocol-level auth of its own).
+- **Every gateway path is origin-checked at upgrade** — cross-origin means `403`, which closes cross-site WebSocket hijacking for your protocol exactly as for the framework's socket.
+- **`onConnection({ send, close, onMessage, subject, headers, path })`** may return a teardown function — it runs on client disconnect, on credential expiry, and on server shutdown, so whatever the handler opened cannot outlive the socket.
+- A plain GET on a gateway path answers `426 Upgrade Required`; two gateways declaring one path refuse the boot.
+
+**The boundary to keep:** if your own UI needs live data, that is a query + `useSubscription`, never a gateway. A gateway hands you raw frames and none of the subscription protocol's guarantees — reach for it only when the CLIENT dictates the protocol.
+
 ## See also
 
 - [Subscribers (`*.subscribe.ts`)](/docs/data/subscribers) — server-side, best-effort post-commit reactivity to a table (NOT the client hook on this page).
@@ -2940,6 +2969,44 @@ const requireApiKey: RestGuard = (ctx) =>
   ctx.subject.type === 'apiKey' ? undefined : { status: 401, message: 'API key required' }
 ```
 
+## Methods — PATCH, HEAD and OPTIONS are first-class
+
+`method:` accepts `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` and `OPTIONS`, on REST routes and plugin HTTP routes alike. Two details:
+
+- **HEAD is admitted wherever GET is** (RFC 9110): a `HEAD` request runs the GET route's whole pipeline — method gate, guards, handler — and the transport drops the body. You never declare a second route for it.
+- **A wrong method is still a precise `405`**, with an `Allow:` header naming exactly the methods mounted on that path — including when several routes share one path.
+
+## Body limits — `maxBodyBytes`
+
+Every HTTP body read is capped at 8 MiB by default — `POST /rpc` (as it always was), plugin routes, REST routes and incoming webhooks. The app-wide cap is `http.maxBodyBytes` in `app.config.ts` (env override `VOLTRO_MAX_BODY_BYTES`); a route that legitimately takes more declares its own:
+
+```ts
+export default defineRestRoute({
+  method: 'POST',
+  path:   '/v1/import',
+  maxBodyBytes: 64 * 1024 * 1024,   // this route only — the app cap stays 8 MiB
+  // …
+})
+```
+
+The same per-route override exists on an incoming webhook's handler (`maxBodyBytes`) — fat provider payloads are the normal case there, not the exception. Two details:
+
+- **Routes that share one PATH share one body read.** The body is read once for the whole group, so the widest `maxBodyBytes` override in the group applies to the group.
+- An oversized body answers `413` whether it announces itself (`Content-Length`) or arrives chunked — the counter cuts it at the cap and never buffers past it.
+
+## Conditional GET — `etag: true`
+
+```ts
+export default defineRestRoute({
+  method: 'GET',
+  path:   '/v1/customers',
+  etag:   true,   // GET only — ignored elsewhere
+  // …
+})
+```
+
+The route stamps a **weak, content-derived** `ETag` (`W/"<sha-1 of the encoded output>"`) on every `200`, and answers a matching `If-None-Match` with `304 Not Modified` — the tag, no body. Weak on purpose: the transport may vary the BYTES per content-encoding, but the representation is the same. (`voltro start` does the equivalent for the web app's HTML on its own — `If-None-Match` answers `304` for buffered `200`s, with weak `W/"md5"` tags over the *uncompressed* body; `no-store` responses excepted.)
+
 ## Idempotency (`Idempotency-Key`)
 
 Set `idempotency: true` in `app.config.ts` and every mutating REST request (`POST`/`PUT`/`PATCH`/`DELETE`) that carries an `Idempotency-Key` header is deduplicated:
@@ -2970,6 +3037,56 @@ This is the Stripe-style contract — the **client** opts in by sending the head
 - **Inbound webhooks already dedup** via [`@voltro/plugin-webhooks`](/docs/plugins/webhooks) (provider key + `_voltro_webhook_*`) — don't double-cover them.
 - **Atomic claim, non-atomic completion.** Two concurrent same-key requests resolve to exactly one execution (the `UNIQUE(scope,key)` insert is the arbiter). But the cached response isn't committed in the handler's own transaction — a crash between the handler committing and the record flipping to `completed` leaves the key in-flight (a retry `409`s until the TTL lapses, then re-runs). REST handlers aren't auto-transactional, so this is the honest ceiling.
 
+## API versions — opt-in `version:` + the sunset flow
+
+A route that will evolve declares its version instead of baking it into the
+path; `version: 'v2'` mounts under `/v2/…`:
+
+```ts
+// v2 — the current shape
+export const listCustomers = defineRestRoute({
+  method: 'GET',
+  path: '/customers',
+  version: 'v2',
+  output: Schema.Struct({ data: Schema.Array(Customer), nextCursor: Schema.NullOr(Schema.String) }),
+  handler: async (_i, ctx) => ({ data: await ctx.store.query(customers), nextCursor: null }),
+})
+
+// v1 — still mounted, deprecated, and gone on a date
+export const listCustomersV1 = defineRestRoute({
+  method: 'GET',
+  path: '/customers',
+  version: 'v1',
+  deprecated: 'GET /v2/customers',   // Deprecation header + replacement pointer
+  sunset: '2027-03-01',              // Sunset header; 410 Gone from this date
+  output: Schema.Struct({ customers: Schema.Array(Customer) }),
+  handler: async (_i, ctx) => ({ customers: await ctx.store.query(customers) }),
+})
+```
+
+Two versions are **two descriptors** — the old one is ordinary code (visible,
+testable, deletable), not an entry in a transformation DSL. While it lives,
+responses carry `Deprecation: true` + `Sunset:`; past the date it answers
+`410 Gone` with `{ version: 'v1', replacement: 'GET /v2/customers' }`. Then
+you delete it. `version` is opt-in: a route without it keeps its literal path
+(no auto-prefix), and declaring `version:` on a path that already starts with
+`/vN/` is refused at definition — both spellings at once is never intended.
+`publicApi` projections version the same way (`spec.version`, default `v1`),
+and the OpenAPI doc groups each version's operations under a version tag with
+`x-voltro-api-version` — one document, the `/vN/` paths already separate them.
+
+**URI versioning only, on purpose.** Header- and media-type-versioning (the
+NestJS options) are not supported: the OpenAPI document, cache keys and plain
+`curl` are all path-shaped, and a version a URL cannot express is a version a
+cached response cannot vary on. If an edge must accept `Accept-Version:`
+headers, rewrite them to the path prefix at the proxy.
+
+**And the rpc socket is deliberately outside this.** The generated client is
+versioned with the server it was generated from — there is no `/v2` for
+`useMutation`. Honest edge: a browser tab that stayed open across your deploy
+runs the PREVIOUS client until reload; that skew window exists, it is small,
+and URL versioning would not remove it.
+
 ## Projecting an existing procedure — `publicApi`
 
 You often want to *offer* an API you don't consume from your own frontend. When the procedure already exists as a query / mutation / action, you don't need to rewrite it as a REST route — annotate it with `publicApi` and the framework mounts ONE HTTP route that runs the **same** handler, under the same guards:
@@ -3026,6 +3143,45 @@ Same guarantees as the WebSocket path, because it is the same code: the declarat
 
 For a hand-written `defineRestRoute`, the same machinery is available directly — return `sse((emit) => unsubscribe)` from the handler and frame events with `sseFrame(event, data)` (both from `@voltro/protocol/rest`).
 
+## Binary downloads — `bytes()`
+
+A handler that serves a file, an export or any non-JSON body returns `bytes(stream, options)` — imported beside `defineRestRoute` / `sse`:
+
+```ts
+import { defineRestRoute, bytes, requireScope } from '@voltro/protocol/rest'
+
+export default defineRestRoute({
+  method: 'GET',
+  path:   '/v1/exports/:id',
+  guards: [requireScope('exports:read')],
+  handler: async ({ params }, ctx) => {
+    const file = await locateExport(params.id)
+    // Lazy thunk form — the source is opened only when the response streams.
+    return bytes(() => openExportStream(file), {
+      contentType: 'application/zip',
+      contentLength: file.size,
+      contentDisposition: `attachment; filename="${file.name}"`,
+    })
+  },
+})
+```
+
+- The first argument is a web `ReadableStream<Uint8Array>` — or the **lazy thunk form** `() => ReadableStream`, which defers opening the source until the response actually streams.
+- The server **pipes without buffering** — a body larger than the heap is fine (the guarantee is exercised with a 256-MiB stream), and byte streams are **never compressed**.
+- Everything before the handler still runs — method gate, sunset, input decode, guards — so a streaming route is exactly as gated as a buffered one.
+- On a plugin HTTP route the same shape is `PluginHttpRouteResult.byteStream`.
+
+### Idempotency × streams — decided
+
+`streaming: true` on a method the idempotency binding claims (`POST`/`PUT`/`PATCH`/`DELETE`) is a **mount error**: a stream cannot cache a replayable body, so the idempotency claim could never complete — every retry would `409` until the TTL lapsed. The refusal names the two ways out: serve the stream on `GET`, or keep the idempotency binding away from the app's streaming routes. A handler that returns a stream *without* declaring `streaming: true` is caught at runtime instead — the claim is **released** so a retry re-processes.
+
+## No multipart parser — a declared boundary
+
+There is **no multipart parser** on REST or webhook routes — `multipart/form-data` against `/form/*` answers `415`, and a REST handler never sees parsed file parts. That boundary is deliberate, and this list of alternatives is complete:
+
+- **File uploads** ride [`@voltro/plugin-storage`](/docs/plugins/storage)'s upload routes — a binary PUT plus a resumable, chunked upload with signed tickets. That is the sanctioned file path, not a workaround.
+- **A provider that delivers webhooks as multipart** (the Mailgun-inbound class) needs, today, either a small parser proxy in front of the endpoint or the provider's JSON delivery mode where it offers one.
+
 ## REST route vs Action
 
 Both are unary request/response. Pick by transport + audience:
@@ -4464,7 +4620,7 @@ rather than letting whichever loaded last silently win.
 ## Retries, backoff, dead-letter
 
 | | |
-|---|---|
+| --- | --- |
 | Retry schedule | exponential — 1s, 2s, 4s … capped at 5 minutes |
 | Default attempts | 8 (`maxAttempts` on the handler, or per-enqueue) |
 | Exhausted | row moves to `dead`, logged at ERROR, stays in the table |
@@ -4530,7 +4686,7 @@ delivery-history screen renders. So every attempt appends a row to
 `_voltro_outbox_attempts`:
 
 | column | |
-|---|---|
+| --- | --- |
 | `outboxId` | the entry this attempt belongs to |
 | `effect` | denormalised — the history stays readable after the entry is purged |
 | `attempt` | 1-indexed, monotonic across the entry's whole life |
@@ -4626,6 +4782,20 @@ bound.
 - **Mirroring a table outward continuously** → `@voltro/plugin-cdc-out`, which
   is built for reverse-ETL with per-pipe ordering.
 
+## There is no generic job queue — take X for Y
+
+Voltro deliberately ships no `defineJob` primitive (priorities, worker pools, a
+BullMQ equivalent). The outbox, [workflows](/docs/workflows/overview) and
+[schedules](/docs/scheduling/overview) cover the cases between them, and a third
+durability primitive would drift from both. What to reach for instead:
+
+| you want… | take |
+| --- | --- |
+| a concurrency-limited worker pool | workflows + [declarative flow control](/docs/workflows/declarative-flow-control) — `concurrency` / `throttle` bound how many runs execute at once |
+| true priority scheduling (high-priority work overtakes queued low-priority work) | does not exist as a primitive — a workflow draining **your own queue table** in your priority order is the honest build |
+| a delayed / scheduled message | `delayMs` on `enqueue` (above) for a one-off delayed effect; a [schedule](/docs/scheduling/overview) for recurring time-based work; workflow [`sleep`](/docs/workflows/sleep) for a pause inside a durable process |
+| exactly-once delivery | does not exist — delivery is at-least-once everywhere, which is the strongest guarantee available without a distributed transaction into the target; **idempotent handlers are mandatory** (see above) |
+
 ## See also
 
 - [Mutations](/docs/data/mutations) — the transaction boundary this rides
@@ -5183,6 +5353,38 @@ const program = Effect.gen(function* () {
 )
 ```
 
+### ISR revalidation on publish
+
+A content type can declare which ISR routes fall when its content is
+published or unpublished — `publish()`/`unpublish()` fire
+[`revalidatePath` / `revalidateTag`](/docs/routing/render-modes#on-demand-revalidation)
+for each entry after the write commits, reaching every `voltro start`
+replica:
+
+```ts
+import { defineContentType, Schema } from '@voltro/cms'
+
+const blogPost = defineContentType({
+  name: 'blogPost',
+  displayName: 'Blog post',
+  pluralName: 'Blog posts',
+  fields: {
+    title: Schema.String.pipe(Schema.maxLength(200)),
+    body:  Schema.RichText({ allowImages: true, allowEmbeds: false }),
+  },
+  revalidate: {
+    paths: ['/blog/[slug]', '/blog'],
+    tags: ['blog'],
+  },
+})
+```
+
+You don't need this on postgres for the plain publish case: a route declaring
+`cacheInvalidatesOn: ['blogPost_published']` is already dropped by CDC when
+the published table changes. Declare `revalidate` for what CDC can't see —
+non-postgres dialects, routes whose loaders read the content indirectly, or
+tag fanout across several routes.
+
 ## The engine, standalone
 
 The validation/derivation engine is pure and exported on its own (also on
@@ -5269,15 +5471,16 @@ list; `mediaFields(type)` lists the top-level media field names.
 ## Versioning content
 
 `@voltro/cms` ships no parallel revision system — the derived tables are
-ordinary database tables, so `@voltro/plugin-versioning` gives full row history
-+ time-travel with no new machinery. List the derived table names in the
-plugin's `tables` option, then read a timeline or restore a snapshot:
+ordinary database tables, so `@voltro/plugin-row-history` gives full row history
+plus time-travel with no new machinery. The plugin records every table by default —
+narrow it with `include:` (pass the derived table handles) or `exclude:` if you
+only want content history — then read a timeline or restore a snapshot:
 
 ```ts no-check
-import { versioningPlugin, rowHistory, restoreAsOf } from '@voltro/plugin-versioning'
+import { rowHistoryPlugin, rowHistory, restoreAsOf } from '@voltro/plugin-row-history'
 
 // Register in your app's plugin list:
-versioningPlugin({})
+rowHistoryPlugin({})
 
 const timeline = await rowHistory(ctx.store, 'blogPost_published', postId, tenantId)
 await restoreAsOf(ctx.store, 'blogPost_published', postId, tenantId, someEarlierDate)

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

@@ -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

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
@@ -1401,7 +1406,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 +1764,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 +1773,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/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/`)
 
@@ -494,6 +530,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

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

@@ -26,10 +26,13 @@ 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** (a locally queryable
+> database, automatic mirroring of `localFirst()` tables, partial replication),
+> which is planned and not yet built. Today `localFirst()` is a declaration the
+> tooling discovers, not an auto-synced local database.
 
 ## CRDT text: `crdtText` + `mergeCrdtStates`
 
@@ -204,6 +207,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
@@ -348,9 +371,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/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/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