@voltro/cli 0.50.1 → 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/internationalization.md

@@ -36,6 +36,13 @@ export default {
   // supported one. MUST be in `locales`. Pick your source-of-truth
   // language — typically English.
   defaultLocale: 'en' as const,
+  // The zone every date/time formatter renders in. Omit it and each
+  // runtime uses its own — the pod's on the server, the viewer's in the
+  // browser — which is a hydration mismatch on every SSR timestamp.
+  // An IANA name pins one zone for everyone; 'viewer' resolves it per
+  // request from the `voltro:tz` cookie.
+  timeZone: 'viewer' as const,
+  defaultTimeZone: 'UTC' as const,
 }
 ```
 
@@ -79,6 +86,18 @@ The client **adopts what the server resolved**, reading it from the `<html lang>
 
 `<html lang>` carries the same resolved locale — the value the `<I18nProvider>` renders with, on the same request. That matters on its own: it is what a screen reader pronounces in, what Chrome offers to translate *from*, and what hyphenation uses.
 
+### The same contract carries the render zone and the render clock
+
+`lang` is one of three answers the server decides and publishes so the client does not form its own:
+
+| attribute | what it carries |
+|---|---|
+| `lang` | the resolved locale |
+| `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.
+
 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.
 
 ## The cookie names are exported
@@ -675,7 +694,19 @@ formatDate(order.createdAt, { dateStyle: 'medium' })
 formatDate(order.createdAt, { dateStyle: 'medium', timeStyle: 'short', timeZone: 'Europe/Berlin' })
 ```
 
-`(value, options?) => string`, where `value` is a `Date`, a timestamp number, or a date string, and `options` is `Intl.DateTimeFormatOptions`. **Omit `timeZone` and the viewer's own zone is used** — which is what a multi-timezone app wants. Pass one only when the value genuinely belongs to a fixed zone (a store's opening hours, a scheduled broadcast). Pinning a global zone across the whole app is the anti-pattern this replaces.
+`(value, options?) => string`, where `value` is a `Date`, a timestamp number, or a date string, and `options` is `Intl.DateTimeFormatOptions`.
+
+**The zone comes from the provider, which you configure once** — `timeZone` in the web `app.config.ts` (see [Timezones under SSR](#timezones-under-ssr-the-setting-that-is-not-a-preference)). Pass `timeZone` in the options only when the value genuinely belongs to a fixed zone regardless of who is looking (a store's opening hours, a scheduled broadcast); that overrides the provider for one call.
+
+**With `timeZone` unset in `app.config.ts` there is no zone at all, and each runtime falls back to its own.** On a server-rendered page that is the pod's zone for the markup and the viewer's for the hydration render — a mismatch on every timestamp, and a different calendar day across midnight. `useTimeZone()` returns `undefined` in exactly that state, so you can assert on it.
+
+### `useTimeZone`
+
+```tsx
+const timeZone = useTimeZone()   // 'Europe/Berlin' — or undefined when none is pinned
+```
+
+`undefined` is a real answer and worth branching on: it means nobody decided, so the server and the browser are each using their own zone. It is not the same as `'UTC'`.
 
 ### `useRelativeTime`
 
@@ -688,7 +719,9 @@ relativeTime(comment.postedAt, { numeric: 'always' }) // "1 day ago" instead of
 relativeTime(comment.postedAt, { now: renderedAt })   // measure against a fixed base
 ```
 
-`(value, options?) => string`. Options are `Intl.RelativeTimeFormatOptions` plus a `now` override (a `Date`, number, or string) for deterministic rendering and tests; the default base is `Date.now()`.
+`(value, options?) => string`. Options are `Intl.RelativeTimeFormatOptions` plus a `now` override (a `Date`, number, or string) for deterministic rendering and tests.
+
+**Hydration-safe by default.** Without an explicit `now`, the base is the server's render instant for the server render *and* the hydration pass that has to match it — published as `<html data-voltro-now>` — then the live clock once hydration commits. So "3 minutes ago" cannot become "4 minutes ago" between the HTML and the first client render just because the network was slow, which is what a plain `Date.now()` base does whenever a unit boundary falls in the gap.
 
 It picks the **largest unit that fits**, so a 90-minute delta reads "1 hour ago", not "90 minutes ago". Anything under a second renders through the `second` unit at 0 — "now" — which avoids the "0 seconds ago" flicker hand-rolled versions produce. `numeric: 'auto'` is the default, so English gets "yesterday" rather than "1 day ago".
 
@@ -721,7 +754,7 @@ For a component that needs several at once, without stacking five hook calls:
 import { useFormatters } from '@voltro/i18n'
 
 function ActivityRow({ entry }: { readonly entry: Entry }) {
-  const { locale, formatDate, relativeTime, formatNumber, plural } = useFormatters()
+  const { locale, timeZone, formatDate, relativeTime, formatNumber, plural } = useFormatters()
 
   return (
     <li lang={locale}>
@@ -735,7 +768,77 @@ function ActivityRow({ entry }: { readonly entry: Entry }) {
 }
 ```
 
-It returns the active `locale` plus `formatDate`, `relativeTime`, `formatNumber` and `plural` — memoized together. Currency is not in the bundle because it needs its ISO code up front; call `useFormatCurrency(code)` alongside it when you need one.
+It returns the active `locale` and `timeZone` plus `formatDate`, `relativeTime`, `formatNumber` and `plural` — memoized together. Currency is not in the bundle because it needs its ISO code up front; call `useFormatCurrency(code)` alongside it when you need one.
+
+## Timezones under SSR — the setting that is not a preference
+
+A formatter is deterministic given the value, the locale, the zone and the clock. The provider supplies all four, and the two beyond locale are the ones that differ between the server and the browser:
+
+| | Where it came from before | What that means under SSR |
+|---|---|---|
+| **locale** | the provider, both sides | agreed already — the server publishes `<html lang>` and the client reads the attribute rather than `navigator.languages` |
+| **zone** | the runtime | the POD on the server (UTC on a container with no `TZ`), the VIEWER's machine in the browser |
+| **clock** | `Date.now()` | two numbers, differing by the network latency |
+
+So a server-rendered timestamp was a hydration mismatch (React error #418) waiting for a wide enough offset or a slow enough connection, and across midnight it was a different calendar **day**. The fix is the one the locale already used: **the server decides, publishes its answer, and the client reads the answer instead of forming its own.**
+
+### Configure it once
+
+```ts
+// apps/<project>/web/app.config.ts
+export default {
+  type: 'web' as const,
+  name: 'myApp',
+  port: 5191,
+  locales: ['de', 'en'] as const,
+  defaultLocale: 'de' as const,
+
+  timeZone: 'Europe/Berlin' as const,   // one zone for every viewer
+  // …or:
+  // timeZone: 'viewer' as const,       // resolve per request, per user
+  // defaultTimeZone: 'UTC' as const,   // before the viewer's zone is known
+}
+```
+
+Whatever it resolves to is stamped on the document as `<html data-voltro-tz>`, and the generated client entry reads that attribute. Both sides then format against one value — which is the property that removes the mismatch, whether or not the value is the viewer's true zone. Being *wrong together* is repairable after mount; being *different* is not.
+
+`timeZone` requires `locales`, because the zone rides the `<I18nProvider>` the framework generates from it.
+
+### `timeZone: 'viewer'` — how the server learns the zone
+
+Through the `voltro:tz` cookie, which has two writers and wants both:
+
+1. **The framework's script**, injected into `<head>`, seeds it from `Intl.DateTimeFormat().resolvedOptions().timeZone` when the cookie is absent. From the second request onward the server renders in the browser's zone with no login and no app code. It never overwrites an existing value and never reloads the page.
+2. **Your app, at login** — overwriting it with the zone you hold for the signed-in user. That is the authoritative one: a profile field or an identity provider's `timeZone` claim beats the machine a user happens to be sitting at.
+
+Write it from `middleware.ts`, which runs per request and can return cookies:
+
+```ts
+// apps/<project>/web/middleware.ts
+import { defineMiddleware } from '@voltro/web/middleware'
+import { TIMEZONE_COOKIE, isSupportedTimeZone } from '@voltro/i18n'
+
+export const userTimeZone = defineMiddleware({
+  run: async (req) => {
+    const zone = await zoneForSession(req.cookies)   // your session → the user's own zone
+    if (!isSupportedTimeZone(zone) || req.cookies[TIMEZONE_COOKIE] === zone) return undefined
+    return {
+      setCookies: [
+        { name: TIMEZONE_COOKIE, value: zone, path: '/', maxAge: 31_536_000, sameSite: 'lax' as const },
+      ],
+    }
+  },
+})
+```
+
+A cookie set here is applied to the jar the SAME render reads, so the zone takes
+effect on the response that sets it rather than the one after.
+
+Validate before you write. An unusable zone is dropped on the way in (a stale cookie, a typo in the config, a runtime with a trimmed ICU) rather than forwarded — `Intl.DateTimeFormat` throws on an unknown zone, and one bad value would otherwise degrade every timestamp in the app to a raw `Date` string.
+
+### Prerendered pages
+
+A `renderMode: 'static'` page is one artefact for every viewer, so `'viewer'` cannot mean the viewer there — it resolves to `defaultTimeZone`. The build publishes that value and its own build instant, so the markup and the first client render still agree; a relative time in a prerendered page corrects itself in one frame after mount rather than mismatching.
 
 ## Formatters vs. ICU in the catalog
 
@@ -750,7 +853,8 @@ For dates, numbers and relative time the hooks are the blessed path; reach for `
 
 - **Don't write `(s)`, `count === 1 ? 'x' : 'xs'`, or a `+ 's'` suffix.** It is wrong in most languages and cannot be fixed by a translator. Use `plural` / `usePlural` or ICU in the catalog.
 - **Don't hand-roll "X minutes ago".** `useRelativeTime` is one hook, is localized, and handles the sub-second and unit-selection cases that inline versions get wrong.
-- **Don't pin a global `timeZone` / locale for the whole app.** The formatters resolve the active locale from the provider; a pin makes every viewer read the app in one user's settings.
+- **Don't pass `timeZone` at every call site to work around a missing config.** Set `timeZone` in `app.config.ts` once. A per-call convention is a rule every new call has to remember, and the ones that forget are invisible until a viewer in another zone reads a wrong date.
+- **Don't call `Intl.DateTimeFormat().resolvedOptions().timeZone` in a component to "fix" SSR.** It is the viewer's true zone and therefore the wrong value: the server could not know it, so the server did not render with it, and using it on the client guarantees the mismatch. Let the server decide and publish — that is what `timeZone: 'viewer'` does.
 - **Don't pass a locale-formatted string to a machine consumer.** Formatted output is presentation — send ISO strings and raw numbers to APIs, `dateTime` attributes and sort keys.
 - **Don't format inside a `.map()` by constructing `Intl` objects yourself.** The hooks memoize per locale; a fresh `new Intl.NumberFormat(...)` per row is the slow path.
 
@@ -840,14 +944,28 @@ program.pipe(withTimezone('Europe/Berlin'))
 `currentTimezone` never fails — an absent context is the documented `UTC`
 default, so call sites don't handle a missing-service error.
 
-> **What ships today is the SEAM, not the wiring.** `@voltro/datetime/context`
-> exports `currentTimezone`, `withTimezone` and `resolvedTimezoneLayer`, and you
-> provide the layer yourself. The framework does **not** yet install it per
-> request, and there is **no `useTimezone()` hook** in the web layer — both are
-> planned to land in `@voltro/runtime` + `@voltro/web`. Until then: resolve the
-> zone yourself (`resolveTimezone`) and provide `resolvedTimezoneLayer` around
-> the work that needs it, or pass an explicit `timeZone` argument. Without a
-> provided layer every call reads the `UTC` default.
+> **Two zones, and only one of them is wired. Keep them apart.**
+>
+> The **render zone** — what a date LOOKS like in the UI — is wired end to end.
+> Set `timeZone` in the web `app.config.ts`, and the framework resolves it per
+> 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).
+>
+> The **server-side compute zone** — what `startOfDay` or a workflow's "same
+> time tomorrow" resolves against inside a handler — is still the SEAM only.
+> `@voltro/datetime/context` exports `currentTimezone`, `withTimezone` and
+> `resolvedTimezoneLayer`; the framework does **not** install the layer per
+> request, so resolve the zone yourself (`resolveTimezone`) and provide
+> `resolvedTimezoneLayer` around the work that needs it, or pass an explicit
+> `timeZone` argument. Without a provided layer every call reads the `UTC`
+> default.
+>
+> Rendering a date correctly does NOT give a route handler the user's zone, and
+> a handler that has it does NOT change what the browser renders. They are
+> separate values today and a `timeZone` in `app.config.ts` configures the
+> first one only.
 
 ## Arithmetic — the DST split is in the names