@voltro/cli 0.54.0 → 0.56.0

package/templates/agent-docs/data.md

@@ -431,6 +431,15 @@ between acting on it and learning to skim it:
   recorder resolves it through the relation registry instead, target and (for a
   many-to-many) junction alike. A write to the junction changes membership,
   which is exactly the change a user makes.
+- **A `crud.*` executor is watched exactly like a hand-written one** — and it is
+  the case that needs it most. `crud.list('tasks', { include: { subTasks: true } })`
+  reads a table your own file never names, so there is nothing in front of you to
+  check `source:` against. The descriptor stays yours either way: `crud.*` supplies
+  only the executor, you write the `source:` beside it. `crud.count` counts as a
+  read too — it returns a number rather than rows, but an insert changes that
+  number, so the counted table belongs in `source:` or "page 3 of 12" stops moving.
+  `crud.create` / `update` / `remove` issue no read at all and never produce a
+  finding.
 - **A table read only to NARROW a result is not counted** — a parent reached
   through `inSubquery(...)`, or a read the framework made to resolve your row
   filter. Those decide which rows come back rather than contributing rows, and
@@ -733,9 +742,12 @@ is always present (the fallback stands in until the first snapshot) and `loading
 is a plain boolean reporting the true state. There is nothing to narrow.
 
 **Errors.** `loading` means **no data has arrived yet** — it is not a claim that
-the subscription is healthy. A **cold-start** failure (nothing ever arrived)
-leaves `loading` true *and* sets `error`, so a component that branches on
-`loading` alone renders a skeleton forever; check `error` to break out of it. A
+the subscription is healthy. A **cold-start** failure (nothing ever arrived) is
+its own state: `loading` is `false`, `failed` is `true`, and `error` is
+non-optional there, so branching on `loading` alone can no longer render a
+skeleton forever. (It used to leave `loading` true, and the type's own comment
+predicted the consequence — the fix was to stop making `loading` mean two
+things rather than to keep warning about it.) A
 failure AFTER data arrived deliberately does NOT replace good data with an error
 banner (a transient websocket hiccup would blank a working screen); those reach
 the api's error bus instead — subscribe with `useOnRpcError` for
@@ -1119,7 +1131,13 @@ export const employeesUpdate = defineMutation({
   target: {
     table: 'employees',
     op: 'update',
-    relations: { assignedStores: 'employee_assigned_stores' },
+    relations: {
+      assignedStores: {
+        junction: 'employee_assigned_stores',
+        anchorColumn: 'employeeId',   // the junction reference() pointing at `employees`
+        targetColumn: 'storeId',      // the junction's other reference()
+      },
+    },
   },
 })
 ```
@@ -1127,9 +1145,7 @@ export const employeesUpdate = defineMutation({
 After the executor succeeds, `input.assignedStores` is reconciled against the
 junction via the diff-based link writer (`store.relationLinks`): missing rows
 inserted, surplus rows deleted, unchanged rows untouched — so reactive
-subscriptions on the junction see one change per changed row. The anchor
-column is derived from the junction's `reference()` targets; a self-junction
-(both columns referencing one table) is refused by name, never guessed.
+subscriptions on the junction see one change per changed row.
 
 The semantics worth knowing: an ABSENT input field leaves the links
 untouched — absent is not empty; an empty array is the explicit "clear them
@@ -1137,6 +1153,34 @@ all". The row id comes from the executor's `output.id`, falling back to
 `input.id`. The link writes go through `ctx.store`, so undo capture and
 cross-table rules see them like any other write.
 
+### The same declaration drives the optimistic update
+
+A junction change used to reach the browser only with the server delta — so on
+one submit the renamed title flipped immediately and the assigned stores sat on
+their old value until the roundtrip landed. It does not any more: `useMutation`
+reconciles the junction rows of every subscription sourced on `junction` the
+moment the mutation is sent, against the same `input[field]` the server will
+write.
+
+It is a diff, not a redraw: a surviving link keeps its own row (and its real
+id), a surplus link disappears, and only a genuinely new link is a staged
+optimistic row. The patches ride the ordinary optimistic lane — reverted if the
+mutation fails, kept after it succeeds until the server data actually moves.
+Nothing is on a timer.
+
+Client-side the anchor id is `input.id`; for an `insert` it is the same
+optimistic id the new row was stamped with, since the server's `output.id` is
+not knowable before the response arrives.
+
+**Why you state the two columns.** The optimistic patch runs in the BROWSER, and
+the browser cannot import your `db/` schema — `@voltro/database` is server-only
+by construction — so the junction's two `reference()` columns cannot be derived
+there. `anchorColumn` is the one pointing at the target's own table;
+`targetColumn` is the other. They are not taken on trust: before it writes, the
+server compares your declaration against the junction's real reference columns
+and refuses, naming the correct pair, if they disagree. A self-junction (both
+columns referencing one table) is still refused by name, never guessed.
+
 ## Typed Errors
 
 ```ts
@@ -2065,7 +2109,8 @@ the resume window (`reactive.resume.windowMs`, default 60 s) the server replays
 **only the deltas the client missed** — the re-subscribe presents the last
 materialised revision and the stream continues on the same revision line, so a
 short offline gap costs a handful of patches instead of every row. Outside the
-window, for computed queries, for row-filtered apps, or whenever anything is in
+window, for computed queries, for a subscription whose source table a
+registered row filter may narrow, or whenever anything is in
 doubt, the query answers with a fresh snapshot — the delta-resume wire contract
 lives in [the wire protocol](/docs/data/wire-protocol#reconnect-delta-resume).
 
@@ -2301,6 +2346,38 @@ The contract, in the order it protects you:
 
 **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.
 
+## When the api connects — `web.api.connect`
+
+Every declared api opens its WebSocket at mount by default. That is `'eager'`,
+and it is what the framework has always done.
+
+```ts
+// apps/web/app.config.ts
+web: { api: { connect: 'lazy' } }
+```
+
+`'lazy'` defers the connection to the FIRST hook that asks for that api —
+`useSubscription`, `useMutation`, `useAppClient`, any of them. A page that reads
+no data never opens a socket.
+
+Two measurements decide whether you want it. Both are from a real browser
+against a `voltro start`:
+
+- **`interactive: 'full'` is the default, and it connected regardless.** A
+  pre-rendered documentation page that subscribes to nothing opened a socket;
+  pages set to `interactive: 'none'` or `'islands'` opened none. So the pages
+  paying for a connection they never use are exactly the ordinary ones.
+- **An open socket keeps a dormancy-managed instance awake.** `isIdleNow`
+  returns false while `connectedClients() > 0` (see
+  [scale-to-zero](/docs/deployment/scale-to-zero)), so one browser tab left open
+  on a pricing page prevents scale-to-zero for as long as it stays open.
+
+`'eager'` remains the default because `'lazy'` moves WHEN a connection error
+surfaces — from page load to first data use — and an app that opens its socket
+for a side effect (a presence ping, an inspect stream) rather than through a data
+hook would notice the difference. If your app subscribes on every page, the two
+behave identically.
+
 ## 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).
@@ -3943,7 +4020,7 @@ These helpers give you the secure **handler**, not schema derivation. Deriving t
 
 _Per-table post-commit reactivity via file convention. Default-exported defineSubscriber({ table, on, handler }) — fires AFTER commit, best-effort, fire-and-forget for async handlers._
 
-Use a `*.subscribe.ts` file when you want code to **run after every commit** to a specific table — refresh a search index, emit an external notification, invalidate a cache, push to a worker queue. The file convention is parallel to `*.startup.ts` / `*.cron.tsx` / `*.webhook.tsx`: drop a file matching the suffix anywhere under `apps/<api>/`, default-export a `defineSubscriber({...})`, the framework discovers + binds it at boot.
+Use a `*.subscribe.ts` file when you want code to **run after every commit** to a specific table — refresh a search index, invalidate a cache, push to a worker queue, emit an external notification. The handler runs on **every replica**; when its effect must not repeat, add [`once:`](#how-often-does-it-run-once-per-replica-unless-you-say-otherwise). The file convention is parallel to `*.startup.ts` / `*.cron.tsx` / `*.webhook.tsx`: drop a file matching the suffix anywhere under `apps/<api>/`, default-export a `defineSubscriber({...})`, the framework discovers + binds it at boot.
 
 Subscribers are deliberately **best-effort** + **non-durable**. For crash-safe async work — "a row changed, now run a workflow" — reach for a [reaction](/docs/data/reactions) instead.
 
@@ -4014,6 +4091,90 @@ The `on` filter narrows by operation:
 
 Other-table events get filtered out before your handler sees them. The matcher does this at the dispatcher level so subscribers add zero hot-path overhead to writes that don't match their table.
 
+## How often does it run? Once per replica — unless you say otherwise
+
+A subscriber binds to the change stream on **every api instance**. One `INSERT`
+behind three replicas calls your handler three times.
+
+That is the right default and not a gap. A handler that refreshes a per-process
+cache, warms a local index, or updates in-memory state *has* to run everywhere —
+a fleet-wide gate would leave every other replica stale. The default assumes the
+handler is **idempotent**.
+
+It is the wrong default for an **effect** — a notification, a mail, a webhook, a
+payment — because there is nothing to make idempotent: the effect IS a write, so
+each run produces another one. Three replicas send three mails.
+
+`once: true` is the whole answer for most handlers — the framework derives the
+key:
+
+```ts
+export default defineSubscriber({
+  table: 'absence_requests',
+  on:    ['insert'],
+  once:  true,          // exactly one replica runs the handler per change
+  handler: notifyApprovers,
+})
+```
+
+It names the change by its CONTENT plus its position among content-identical
+repeats. That is not a detail: a fleet change carries no LSN, no commit id and no
+`traceId` (the last one deliberately, so a local trace is never mis-attributed to
+a remote write), so content is the only thing two replicas provably agree on —
+and `A→B`, then `B→A`, then `A→B` again has to count as three changes, not two.
+
+Pass a **function** when you want to be COARSER than one-per-change: two updates
+that differ only in a field you do not care about are two changes to `once: true`
+and can be one to a key you write yourself.
+
+```ts
+// apps/api/subscribers/notifyApprovers.subscribe.ts
+export default defineSubscriber({
+  table: 'absence_requests',
+  on:    ['insert'],
+  // Cluster-wide: exactly one replica runs the handler for each change.
+  once:  (event) => String((event.new as { id?: string } | null)?.id ?? ''),
+  handler: async (event, ctx) => {
+    for (const approver of await approversOf(ctx, event.new)) {
+      await sendNotification(ctx, { toEmployeeId: approver.id })
+    }
+  },
+})
+```
+
+**A key you write must tell two genuine changes apart.** A row id is enough for
+`insert` and `delete`, where a row changes state once. It is not enough for
+`update`: two edits to the same row produce the same id, and the second would be
+dropped as a duplicate of the first — an effect that silently stops happening for
+a row that keeps changing. Put something that moves in the key, or use
+`once: true`:
+
+```ts
+once: (event) => {
+  const row = event.new as { id?: string; updatedAt?: Date } | null
+  return `${row?.id ?? ''}:${row?.updatedAt?.toISOString() ?? ''}`
+},
+```
+
+**`once` is AT MOST once, not exactly once.** The claim is taken before the
+handler runs, so a replica that wins and then dies takes the event with it, and a
+claim that cannot be written at all (database unreachable) is taken by nobody.
+Both are loud in the log and neither is retried — a subscriber is best-effort by
+construction. When the effect must not be lost, the change stream is the wrong
+seam: run it inside the mutation, or start a workflow from a
+[reaction](/docs/data/reactions), where durability is the primitive's job.
+
+The boot log says which one each subscriber got:
+
+```
+subscriber: registered table=absence_requests on=["insert"] once=fleet
+subscriber: registered table=posts on=["insert","update"] once=per-replica
+```
+
+Claims live in `_voltro_change_claims` and are swept after an hour
+(`VOLTRO_CHANGE_CLAIMS_TTL_HOURS`). The key is namespaced per subscriber file, so
+two subscribers watching one table never lock each other out.
+
 ## Semantics — best-effort, fire-and-forget
 
 Subscribers are **non-durable** by design:
@@ -4087,6 +4248,8 @@ export default defineSubscriber({
 export default defineSubscriber({
   table: 'organizations',
   on:    'insert',
+  // The POST is an effect: without `once` every replica sends one.
+  once:  (event) => String((event.new as { id?: string } | null)?.id ?? ''),
   handler: async (event, ctx) => {
     if (!event.new) return
     const slug = event.new.slug as string
@@ -4203,9 +4366,17 @@ into the agent's prompt.
 
 ## Guards (the point)
 
-- **`dedupeKey` (required)** — the same logical change acts exactly once. This is
-  what stops a reaction whose act writes the watched table from self-triggering
+- **`dedupeKey` (required)** — the same logical change acts exactly once, across
+  the whole fleet. The key is claimed in `_voltro_change_claims` before the act
+  runs (INSERT-wins on a UNIQUE — the same arbiter the cron scheduler uses), so
+  two replicas seeing one change start one workflow, not two. This is also what
+  stops a reaction whose act writes the watched table from self-triggering
   forever. `defineReaction` throws at boot if it's missing.
+
+  The claim is taken BEFORE the act, which is what makes it a gate rather than a
+  report — and the cost is stated rather than hidden: an act that THROWS has
+  already consumed its key and is not re-run by a later duplicate. Durability
+  belongs to the workflow the act starts, not to the trigger.
 - **`rateLimit` (optional)** — at most `limit` firings per `windowMs`.
 - **`costBudgetUsd` (optional)** — a per-tenant AI spend ceiling; over budget,
   the reaction refuses (fails closed).
@@ -4226,8 +4397,9 @@ into the agent's prompt.
 - Best-effort + fire-and-forget (like subscribers) — a failing act logs +
   continues; it can't back-pressure the change stream. Durability comes from a
   workflow act (an agent act is best-effort).
-- `dedupeKey` is in-memory per process in v1 (it stops the self-trigger storm
-  within a run); a durable cross-restart dedupe table is a follow-up.
+- `dedupeKey` claims survive a restart but not forever: `_voltro_change_claims`
+  is swept after an hour (`VOLTRO_CHANGE_CLAIMS_TTL_HOURS`). A change whose key
+  reappears after that window acts again.
 
 ## When to use what
 
@@ -4672,6 +4844,19 @@ available without a distributed transaction into the target system, so:
 **Handlers must be idempotent.** A process that dies between "the remote
 accepted it" and "we recorded that" will retry.
 
+**On several replicas, that used to be the smaller reason.** Every replica runs
+the drain, and the drain read every pending row — so an effect was dispatched
+once *per replica*, on the happy path, every time. It is claimed now: a row moves
+`pending → delivering` in one atomic statement stamped with the claiming
+process, so a racing replica loses the row rather than duplicating it, and a
+claim whose holder stops responding is returned to the queue after its lease
+(`claimLeaseMs`, default 5 minutes — raise it above your slowest handler).
+
+That removes the routine duplicate. It does not make delivery exactly-once, and
+nothing can: the process can still die between the remote accepting and the row
+being marked. The idempotency requirement stands — it is now about the failure
+case it was always meant to describe, rather than about every single delivery.
+
 ## Declaring the handler
 
 One `*.outbox.ts` file per effect:
@@ -5022,11 +5207,17 @@ A resume is declined — always with a fresh snapshot — when:
   keeps delta-resume on every subscription whose source is not in that set —
   the common case, since most filters narrow a handful of tables. Without the
   declaration the framework cannot know which tables the predicate may reach
-  and excludes them all, which is what a deployment measured as one filter over
-  4 tables costing the feature on all 173 of their queries. Eager loads are
-  excluded wholesale because a relation resolves below the seam that narrows.
-  They reconnect with a fresh
-  snapshot, exactly as before.
+  and excludes them all. Eager loads are excluded wholesale because a relation
+  resolves below the seam that narrows. They reconnect with a fresh snapshot,
+  exactly as before.
+
+**Which of your queries actually got a ring** is recorded per label, since the
+excluded and the never-eligible look identical on the wire:
+`/_voltro/inspect/subscriptions` returns a `resume` array of
+`{ label, resumable, excluded }`, and `voltro dev` logs each verdict once under
+the `voltro:resume` scope. A `computed` verdict is the one worth reading first:
+it means the executor returns a value rather than a descriptor, so no row-filter
+declaration can ever change it.
 
 **Author a live-subscribed getter to return, not throw.** A subscription is a
 long-lived stream, so a getter that throws on every re-evaluation is a broken

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

@@ -148,6 +148,13 @@ deployments (k8s with `replicas: 3`, multi-pod ECS, etc.) need a
 shared store, otherwise a write on instance A doesn't pin reads on
 instance B.
 
+**The boot says so now.** When replicas are configured and the RYW store falls
+back to memory on a deployment whose environment says several replicas
+(`POD_NAME`, `FLY_ALLOC_ID`, `K_REVISION`, … — or `REPLICA_COUNT`, which is a
+declaration in both directions), the boot warns and names the two ways out. It
+used to log `ryw policy 'fallback'` as though the policy were in force, and the
+first symptom was a user reloading and seeing their own save gone.
+
 Wire Redis:
 
 ```sh
@@ -306,6 +313,31 @@ The bus is **additive** to the inline emit path. Local reactivity must survive a
 
 Because the inline path is never removed, a broker outage degrades **cross-replica** fan-out only — local reactivity keeps working, and the framework logs a warning. The bus reconnects when the broker returns.
 
+## When the connection drops
+
+Every cross-replica mechanism here rides a connection, and a connection that dies quietly is worse than one that fails loudly: the app keeps serving, the clients keep their sockets, and their live queries simply stop updating. So each path is required to notice, recover, and then **say that it lost something**.
+
+**A hole is never patched — it is re-derived.** None of these transports keeps a log. Postgres queues nothing for a listener that is not there; Redis and NATS pub/sub retain nothing at all. So there is nothing to replay, and the only complete recovery is to re-run every live query. That is safe precisely because a live query is idempotent, and it is what the framework does on every one of the events below:
+
+| What happened | How it is noticed | What you see |
+|---|---|---|
+| The postgres `LISTEN` connection died (failover, proxy, `pg_terminate_backend`) | A heartbeat sent through the pool goes unanswered on the LISTEN stream | `cdc: reconnecting` → `cdc: reconnected`, then every live query refreshes |
+| A peer's serial jumped — the broker dropped messages | Per-origin serial accounting; the count is exact | `broadcast: missed N change(s) from …` |
+| This replica could not subscribe at boot (the broker was restarting) | The subscribe is retried in the background | `broadcast: could not subscribe` → `broadcast: subscribed`, then a refresh |
+| The Redis or NATS transport re-dialled underneath us | The driver's connection lifecycle | `broadcast: transport disconnected` → a refresh on reconnect |
+
+Two consequences worth knowing:
+
+- **A broker that is down at boot does not stop the boot.** The replica starts, serves, keeps local reactivity, and joins the bus when the broker returns. A crash loop across the whole fleet is the wrong answer to a broker restart — which is exactly when every replica is dialling at once.
+- **A replica that restarts under a stable name is recognised as a new process.** A StatefulSet pod keeps its `POD_NAME`, and `VOLTRO_REPLICA_ID` is stable by definition, so the name alone cannot tell a restart from a continuation. Each publish carries a per-process epoch so peers reset their watermark instead of quietly ignoring the new process's serials.
+
+The postgres heartbeat is idle-only: any traffic on the channel — including another replica's heartbeat — counts as proof the connection works, so a busy channel never pays for one and a fleet pays roughly one probe per idle window however many replicas it has. Tune it with:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `VOLTRO_CDC_HEARTBEAT_MS` | `20000` | Silence on the channel before a probe is sent |
+| `VOLTRO_CDC_HEARTBEAT_TIMEOUT_MS` | `10000` | How long an unanswered probe may go before the consumer is declared dead |
+
 ## The honest caveat — app-mutation changes only
 
 The bus carries changes that flow through **`ctx.store`** (the framework's mutation path). It does **not** capture **out-of-band DB writes** — a `psql` session, a cron job, or a second service writing the same database directly. Those changes never hit `store.onChange`, so they never reach the bus.
@@ -340,7 +372,14 @@ A changelog table that every replica polls (`SELECT … WHERE seq > :last`) woul
 will NOT reach clients on other replicas. Add @voltro/plugin-broadcast (Redis / NATS) to close the gap…
 ```
 
-When BOTH a native path and the broadcast plugin are wired (e.g. postgres + broadcast), both stay active — the own-origin skip dedups, so there's no double-emit. The native path is the primary; the bus is harmless redundancy.
+When BOTH a native path and the broadcast plugin are wired (e.g. postgres + broadcast), both stay active — and they carry **different things**. The native path carries table changes to every replica. The bus carries reactivity *channels* (`publishReactivity`), which are not database writes and so have no native transport at all.
+
+```
+[voltro:dev] reactivity: native LISTEN/NOTIFY (postgres) carries table changes;
+@voltro/plugin-broadcast (redis) carries reactivity channels
+```
+
+This page used to say the two paths were harmless redundancy because "the own-origin skip dedups". They were not. The own-origin skip only ever covered a replica's own publish coming back to itself — so a change the native transport had already delivered to every replica was re-published by every replica under *its own* origin, and each peer injected it again. N replicas turned one change into N² deliveries: every subscriber, every live-query wake, every plugin tap. At two replicas a `*.subscribe.ts` handler ran **four** times for one `INSERT`, twice per instance.
 
 ## sqlite and the memory store behind replicas
 

package/templates/agent-docs/deployment.md

@@ -701,6 +701,50 @@ The api stays self-hosted (it must — WebSocket subscriptions + Postgres are
 always-on); only the static bytes move to the edge. `POST /rpc` forwards the
 session cookie exactly as the WS path, so SSR loaders + auth resolve identically.
 
+## Cache headers — `voltro start` sets them, and what they say
+
+Since 0.56.0 the production web server stamps `Cache-Control` on everything it
+serves out of `dist/`. Before that it stamped nothing, and a browser with neither
+`Cache-Control` nor `Last-Modified` has no freshness information at all: it
+revalidated every content-hashed chunk on every visit — for the reference fixture
+that is ten conditional round-trips before the page is interactive, on files whose
+name carries their content hash.
+
+| What | Header | Why |
+|---|---|---|
+| `/assets/index-7N08IhkU.js` (content-hashed) | `public, max-age=31536000, immutable` | The hash IS the version. A new build is a new URL, so there is nothing to invalidate. |
+| `/favicon.svg`, `/robots.txt`, anything from `public/` | `public, max-age=3600` | The URL is stable across deploys, so a long life would pin a stale file. |
+| A pre-rendered page | `public, max-age=0, must-revalidate` | The ETag turns the revalidation into a `304` with no body. |
+| An `isr` page | `public, max-age=0, must-revalidate` | Same, unless you opt into sharing it — below. |
+
+The defaults are deliberately safe for a SHARED cache: nothing is given an
+`s-maxage`, because a CDN holding an HTML page past a deploy serves the previous
+build's asset URLs and the framework has no purge hook to fix that. Two opt-ins,
+for apps that own their CDN and can purge it:
+
+```ts
+// apps/web/app.config.ts
+http: {
+  cache: {
+    // Let a shared cache hold pre-rendered HTML for 60s.
+    htmlSMaxAgeSeconds: 60,
+    // Let a shared cache hold an `isr` page for its OWN `revalidate` window
+    // (plus its stale-while-revalidate). Off by default: `revalidatePath`
+    // purges the framework's cache and a CDN cannot see that purge, so an
+    // on-demand invalidation would take up to `revalidate` seconds to reach a
+    // shared copy.
+    isrShared: true,
+    // Both lifetimes are tunable; `immutableMaxAgeSeconds: 0` turns the
+    // immutable header off entirely.
+    immutableMaxAgeSeconds: 31_536_000,
+    staticMaxAgeSeconds: 3_600,
+  },
+}
+```
+
+When you put the assets on a CDN with `voltro static`, the host's own rules apply
+to them instead — these headers are what the CONTAINER path says.
+
 ## What the framework decides for you
 
 - **Content-Type** per file, from its extension (including the ones generic tools
@@ -1623,7 +1667,7 @@ config format and have **not** been executed against a live account of that
 platform; if one drifts from what the platform ships today, the container is
 still right and the fix is in the wrapper.
 
-Three properties of the image every platform relies on:
+Four properties of the image every platform relies on:
 
 - **`PORT` wins.** The port precedence is `PORT` > `--port` > `app.config.ts` —
   deliberately, because platforms assign through `PORT`. You never configure a
@@ -1635,6 +1679,14 @@ Three properties of the image every platform relies on:
 - **`/internal/readiness` flips to 200 only after the whole boot.** Use it as
   the health check everywhere; routing traffic on process-up instead of
   readiness is how a deploy serves 502s for the first seconds.
+- **The build imports the serve bundle before the image is finished, and a
+  failed import fails the build.** The image-build stage has no database and no
+  secrets, so it cannot require a full boot — but it does not need one: a module
+  `prune-runtime` traced away, a truncated artefact, a wrong entry path or a
+  missing export all fail at *import*, long before anything connects. So the
+  import and a callable `runServe` are required; how far the subsequent start
+  gets is reported, not required. If your build turns red at `load gate:`, the
+  artefact is wrong and no amount of environment will fix it.
 
 ## Fly.io
 

package/templates/agent-docs/internationalization.md

@@ -102,6 +102,38 @@ Locale was already agreed; the zone and the clock were each read from the ambien
 
 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 language picker
+
+`<LocaleSwitcher>` writes the `voltro:locale` cookie and reloads, so the server
+re-renders in the chosen language. It ships from `@voltro/i18n` **unstyled** — a
+native `<select>` you style with your own CSS:
+
+```tsx
+import { useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+<LocaleSwitcher
+  locales={LOCALES}
+  current={useLocale()}          // server + first paint agree; without it the
+  ariaLabel={useT('lang.label')} // control hydrates from the cookie after mount
+  className="my-lang-select"
+/>
+```
+
+A native `<select>` on purpose: it works everywhere with no portal or
+positioning chrome, is keyboard-accessible by default, and is SSR-safe.
+`onChange` returning `false` suppresses the reload — for an app whose i18n
+runtime swaps catalogs in place.
+
+`@voltro/ui-shadcn` exports the same control pre-styled with the kit's classes.
+Use that one **only in a kit app**: its classes exist only when your CSS entry
+imports `@voltro/ui-shadcn/tokens.css`. Without it the control renders as a bare
+`<select>` with dead `class` attributes — `voltro doctor` reports exactly this.
+
 ## The cookie names are exported
 
 `LOCALE_COOKIE` and `THEME_COOKIE` come from **`@voltro/i18n`** (and from `@voltro/ui-shadcn` if you use the kit):

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

@@ -399,9 +399,16 @@ Two disciplines it enforces, because both fail silently when hand-rolled:
   when `local` is `true`. Without that every client re-broadcasts what it
   just received: one keystroke, one server write per open tab.
 
-A page mounting an editor needs `renderMode = 'client'`. The default is
+A page mounting an editor needs `renderMode = 'spa'`. The default is
 `'static'`, which pre-renders at build time, and the editor finds no
-`window` there.
+`window` there. `'spa'` is skipped by the prerender and mounts on the
+client; if the route has a layout, that layout still renders server-side
+as an SSR shell.
+
+This page said `'client'`, which is not one of the four render modes and
+fails the build — see [Render modes](/docs/routing/render-modes), which
+names that exact value as invalid. The `frontend-collab` template copied
+the sentence and was unbuildable for as long as it existed.
 
 Carets ride a `delivery: 'latest'` EVENT, deliberately not presence
 metadata: the roster's value-compare push would make every caret move a