@voltro/cli 0.50.1 → 0.51.0

package/dist/webDev-DposiF3j.js

@@ -0,0 +1,2 @@
+import { _ as e, y as t } from "./webDev-B-ubQEMX.js";
+export { e as tryRunWebServe, t as walkPagesTree };

package/dist/{webhooksCommand-DjE6u0r4.js → webhooksCommand-FLYY9IXh.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-Dz9GqA6P.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-CK522MV5.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
 	return r((await n(await t(e))).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.50.1",
+  "version": "0.51.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -700,6 +700,24 @@
         "title": "A COMPUTED `source:` can keep its typed names — do not widen the whole registry",
         "kind": "manual"
       },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/02_restore-refuses-without-marker",
+        "title": "`voltro data restore` refuses when it cannot write the in-progress marker",
+        "kind": "manual"
+      },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/03_restore-assets-returns-counts",
+        "title": "`restoreAssetsFromCas` returns `{ count, objects }`, not a number",
+        "kind": "manual"
+      },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/04_i18n-timezone-prop",
+        "title": "`<I18nProvider>`: `timeZone` is its own prop, not an `intlConfig` member",
+        "kind": "transform"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -775,22 +793,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.50.1",
-    "@voltro/cache": "0.50.1",
-    "@voltro/data-transfer": "0.50.1",
-    "@voltro/database": "0.50.1",
-    "@voltro/env": "0.50.1",
-    "@voltro/kv": "0.50.1",
-    "@voltro/logger": "0.50.1",
-    "@voltro/plugin-auth": "0.50.1",
-    "@voltro/plugin-broadcast": "0.50.1",
-    "@voltro/plugin-mail": "0.50.1",
-    "@voltro/plugin-storage": "0.50.1",
-    "@voltro/plugin-webhooks": "0.50.1",
-    "@voltro/protocol": "0.50.1",
-    "@voltro/runtime": "0.50.1",
-    "@voltro/serverless": "0.50.1",
-    "@voltro/workflow": "0.50.1",
+    "@voltro/ai": "0.51.0",
+    "@voltro/cache": "0.51.0",
+    "@voltro/data-transfer": "0.51.0",
+    "@voltro/database": "0.51.0",
+    "@voltro/env": "0.51.0",
+    "@voltro/kv": "0.51.0",
+    "@voltro/logger": "0.51.0",
+    "@voltro/plugin-auth": "0.51.0",
+    "@voltro/plugin-broadcast": "0.51.0",
+    "@voltro/plugin-mail": "0.51.0",
+    "@voltro/plugin-storage": "0.51.0",
+    "@voltro/plugin-webhooks": "0.51.0",
+    "@voltro/protocol": "0.51.0",
+    "@voltro/runtime": "0.51.0",
+    "@voltro/serverless": "0.51.0",
+    "@voltro/workflow": "0.51.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -404,11 +404,21 @@ Do NOT write `x.page.tsx`, `index.page.tsx` or `[id].page.tsx` — those were th
 **Every suffix above is a CONTRACT, not a label.** Something else depends on each
 promise, and `voltro doctor` enforces all of them:
 
-- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
-  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
-  what lets a caller render it ten thousand times in a list, reuse it across
-  features, and prerender it without reading its source. Lift the write into the
-  owning `*.component.tsx` and pass a handler down.
+- `*.component.ui.tsx` may read (`useT`, `useTFn`, `useCan`, `usePermissions`,
+  the `@voltro/i18n` formatters) but must never import a write hook
+  (`useMutation`, `useAction`, `useUpload`, …). That is what lets a caller render
+  it ten thousand times in a list, reuse it across features, and prerender it
+  without reading its source. Lift the write into the owning `*.component.tsx`
+  and pass a handler down.
+
+  **Reading is a recommendation, not a grudging allowance — call the hook, do
+  not take a prop.** Threading `t` / `formatDate` / `useCan` through props is
+  prop-drilling: it grows the prop surface with every formatter, has to be
+  restated in every intermediate signature and every test, and does NOT make the
+  component more reusable — it makes every call site worse. The one argument for
+  the prop, "it renders without a provider", is already paid for the moment any
+  test mounts one. Pick one way per component head: a `t` prop beside a
+  formatter hook is the worst of both.
 - `*.internal.ts` is the promise that refactoring inside that directory breaks
   nobody. An import from another subtree revokes it.
 - `*.types.ts` having no runtime export is what makes importing it free and makes

package/templates/AGENTS.md

@@ -404,11 +404,21 @@ Do NOT write `x.page.tsx`, `index.page.tsx` or `[id].page.tsx` — those were th
 **Every suffix above is a CONTRACT, not a label.** Something else depends on each
 promise, and `voltro doctor` enforces all of them:
 
-- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
-  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
-  what lets a caller render it ten thousand times in a list, reuse it across
-  features, and prerender it without reading its source. Lift the write into the
-  owning `*.component.tsx` and pass a handler down.
+- `*.component.ui.tsx` may read (`useT`, `useTFn`, `useCan`, `usePermissions`,
+  the `@voltro/i18n` formatters) but must never import a write hook
+  (`useMutation`, `useAction`, `useUpload`, …). That is what lets a caller render
+  it ten thousand times in a list, reuse it across features, and prerender it
+  without reading its source. Lift the write into the owning `*.component.tsx`
+  and pass a handler down.
+
+  **Reading is a recommendation, not a grudging allowance — call the hook, do
+  not take a prop.** Threading `t` / `formatDate` / `useCan` through props is
+  prop-drilling: it grows the prop surface with every formatter, has to be
+  restated in every intermediate signature and every test, and does NOT make the
+  component more reusable — it makes every call site worse. The one argument for
+  the prop, "it renders without a provider", is already paid for the moment any
+  test mounts one. Pick one way per component head: a `t` prop beside a
+  formatter hook is the worst of both.
 - `*.internal.ts` is the promise that refactoring inside that directory breaks
   nobody. An import from another subtree revokes it.
 - `*.types.ts` having no runtime export is what makes importing it free and makes
@@ -707,7 +717,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.50.1** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.51.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.50.1** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.51.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/cli.md

@@ -3412,8 +3412,22 @@ Aborting on the first one made `--assets` unusable for exactly the deployment th
 
 Only a genuine *not found* is treated this way. A 403 from a rotated credential or a 5xx from a backend outage still fails the capture — calling those "the object is gone" would turn a recoverable outage into a backup that quietly contains nothing.
 
+**Three numbers, because they answer three questions.** `_voltro_storage_refs` holds one row per *reference*, several of which legitimately name one *key*, and the content-addressed store keeps one body per distinct *object*:
+
+```
+57 reference(s) → 16 key(s) → 16 object(s), 65476 byte(s) under assets/
+```
+
+The stamp carries all three (`references`, `count`, `objects`, with `totalBytes` and `objectBytes` beside them). It used to carry only the reference count under the name `count`, so a stamp read `57` over a directory holding 16 files — and anyone answering *"are all the blobs there?"* after a restore compared the two and found a 3.5× gap that was not one. A key named by several references is also fetched once now, rather than downloaded and hashed once per row.
+
 Resume is per blob key, so re-running a `--assets` capture that was interrupted transfers only what is missing. The **dump itself has no resume** — a vendor artifact is one opaque file with no offset to restart from. If you need a resumable, chunkable, observable transfer, that is the logical path (`export` / `import`), and it is why the logical path exists.
 
+### The stamp's skew warning compares the backup against the TARGET
+
+`restore` reads `voltro-backup-stamp.json` before touching anything and warns when the backup's schema fingerprint differs from the target's. That warning used to say the difference was against "what this code declares", and it was not — the value it compares against is the target database's *live* schema, read by introspection at restore time. Bringing a target to the backup's shape makes the warning disappear while the declared fingerprint is a third value entirely, which is how the mislabel was caught. The comparison was always the useful one; only the sentence was wrong, and it sent readers looking for a code change where a database differed.
+
+The same distinction shows up in `voltro db plan`, which prints `live … · declared …` rather than `from → to` for the same reason: **a hash of a live database never equals the hash of the declaration it came from.** Introspection cannot recover everything a declaration carries — generated expressions, `maxLength`, sensitivity markers — so the two are not comparable and are not meant to match. The plan's operation list is what says whether they agree; `0 operations` under two different fingerprints means they do.
+
 ### A restore that is interrupted refuses the next boot
 
 `restore` writes one row into `_voltro_replace_in_progress` **before** the first destructive statement and removes it **after** the last write — the blobs included. Its presence at boot is a refusal naming the artifact that was going in.
@@ -3427,6 +3441,17 @@ Two changes, covering different dumps:
 - **A backup taken by `voltro data backup` excludes the marker table** (`--exclude-table` / `--ignore-table`). It can no longer carry the thing that erases the guard on the way back in.
 - **`restore` writes the marker back after the tool exits**, on the failing path as well as the succeeding one. That covers dumps taken before this version and dumps made by hand. If it was removed and rewritten you get a warning saying so; if it could not be rewritten you get an error, because the guard is then off for that run and nothing will stop the next boot.
 
+**A restore that cannot write the marker at all is refused.** Two things can prevent it — the bookkeeping store will not open (wrong credentials, an unreachable database, a missing env var, no `app.config.ts` from here), or the table is not there yet — and both mean the same thing to you: this restore would run with no guard. The refusal names which one it was:
+
+```
+✗ refusing to restore: the in-progress marker cannot be written.
+    reason: bookkeeping is unavailable: connect ECONNREFUSED 127.0.0.1:5432
+```
+
+This used to be a silent hole rather than a refusal, and worse than silent. The failure to open the store was caught and discarded, and the discarded value guarded *every* branch below it — including the refusal that would have reported the guard missing. So a restore ran on and, over a database with zero marker rows, printed *"the next boot will REFUSE, by design"*. The next boot did not refuse, and `voltro data clear-replace-marker` had nothing to clear. A restore is the operation you run against a target that is already unwell, so the precaution was falling away exactly when it was needed.
+
+**`--no-marker`** restores without the guard, deliberately. It warns every time and names the reason the marker was unavailable. It exists because the accidental way did: if going unguarded is ever right, it should be something you typed.
+
 | dialect | shape | effect |
 |---|---|---|
 | postgres, mysql, mariadb | the dump names the whole database, so the restore drops the marker table too | our backups exclude it; for any other dump the marker is written back after the tool exits |
@@ -3435,6 +3460,10 @@ Two changes, covering different dumps:
 
 Clear a marker deliberately with `voltro data clear-replace-marker --yes` once you have decided the current state is correct.
 
+**`_voltro_data_transfers` is excluded for the same reason, one table over.** The restore opens its own run row there *before* the tool starts; a dump that carried the table dropped it mid-flight, and the update recording the outcome then wrote into a table that no longer held the row. The visible result was that a failed native restore did not appear in `voltro data transfers` at all — only the `backup` row the dump had brought over from the *source* database. The command that answers "did the restore finish" could not see the run asking.
+
+Exactly those two tables are excluded, and the line is deliberate: a native restore into the same deployment *should* bring the migration ledger, the stored plans, the CDC offsets and the schedule claims — they describe the data being restored. These two describe the *restore*, and a record of an operation must not be overwritten by the operation it records.
+
 ### Both directions are in the history
 
 `backup` and `restore` write a row to the same `_voltro_data_transfers` record `import` and `export` use, so `voltro data transfers` answers "did last night's backup finish" from the instance that ran it:

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