@voltro/cli 0.8.0 → 0.10.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { P as e } from "./inspectMetrics-EK0CcHyu.js";
-import { t } from "./start-DuyBQxW3.js";
+import { N as e } from "./inspectMetrics-BeMjgt8x.js";
+import { t } from "./start-C_M4fGS2.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -57,24 +57,25 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.8.0",
-    "@voltro/cache": "0.8.0",
-    "@voltro/data-transfer": "0.8.0",
-    "@voltro/database": "0.8.0",
-    "@voltro/env": "0.8.0",
-    "@voltro/kv": "0.8.0",
-    "@voltro/logger": "0.8.0",
-    "@voltro/plugin-auth": "0.8.0",
-    "@voltro/plugin-broadcast": "0.8.0",
-    "@voltro/plugin-mail": "0.8.0",
-    "@voltro/plugin-storage": "0.8.0",
-    "@voltro/plugin-webhooks": "0.8.0",
-    "@voltro/protocol": "0.8.0",
-    "@voltro/runtime": "0.8.0",
-    "@voltro/serverless": "0.8.0",
-    "@voltro/workflow": "0.8.0",
+    "@voltro/ai": "0.10.0",
+    "@voltro/cache": "0.10.0",
+    "@voltro/data-transfer": "0.10.0",
+    "@voltro/database": "0.10.0",
+    "@voltro/env": "0.10.0",
+    "@voltro/kv": "0.10.0",
+    "@voltro/logger": "0.10.0",
+    "@voltro/plugin-auth": "0.10.0",
+    "@voltro/plugin-broadcast": "0.10.0",
+    "@voltro/plugin-mail": "0.10.0",
+    "@voltro/plugin-storage": "0.10.0",
+    "@voltro/plugin-webhooks": "0.10.0",
+    "@voltro/protocol": "0.10.0",
+    "@voltro/runtime": "0.10.0",
+    "@voltro/serverless": "0.10.0",
+    "@voltro/workflow": "0.10.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
+    "tinyglobby": "^0.2.17",
     "ts-morph": "^28.0.0"
   },
   "optionalDependencies": {

package/templates/agent-docs/cli.md

@@ -427,37 +427,63 @@ voltro dev apps/acme/api            # explicit path
 6. Watches `src/`. On save, Vite HMR fires:
    - A page / layout **component** change → React Fast Refresh patches the live
      component in place; client state survives (see below).
-   - A page / layout **`loader`** (or other non-component export) change → a
+   - A page-local **value export** (`const COLUMNS = [...]`) change → also a hot
+     update, even in the same save as the JSX (see below).
+   - A **server-read export** — `loader`, `renderMode`, `meta`, … — change → a
      full page reload, on purpose (see below).
    - CSS changes → swap stylesheets in place.
    - New page file → regen the entry files → reload the route tree.
 
+`renderMode: 'ssr'` pages compile on demand the first time each route is hit. To
+keep a burst of cold pages — several browser tabs, or a health-check sweep across
+many routes — from spiking memory, `voltro dev` compiles at most **4** of them at
+once and collapses duplicate concurrent requests for the same route into a single
+compile. Already-compiled (warm) pages are never throttled, so a hot app stays
+fully concurrent. Tune the cap with `VOLTRO_DEV_SSR_COMPILE_CONCURRENCY` (below) —
+drop it on a low-memory box, raise it on a big machine.
+
 
 ### Fast Refresh: what hot-updates and what reloads
 
 Editing a **page or layout component** applies as a hot update — the React tree
 stays mounted, so form input, scroll position, open dialogs and every `useState`
-survive. Editing a **`loader`** (or `meta` / `renderMode` / any other
-non-component export of a route module) triggers a full page reload instead.
-
-That split is deliberate, not a gap. A `loader` also runs on the server: the page
-in front of you was rendered from the OLD one, and the router caches loader
-results per route + params, so hot-swapping the function would leave stale data
-on screen with nothing to signal it. A reload re-runs SSR with the new loader.
+survive. So does editing a **page-local value** the page happens to export — a
+`const COLUMNS = [...]` you change together with the table that renders it. The
+module re-evaluates, the component renders the new value, and your client state
+is untouched.
+
+A full page reload happens for exactly one class of edit: an export the
+**server** already read to produce the page in front of you.
+
+| Export | What the server does with it |
+| --- | --- |
+| `loader` | runs it (SSR / prerender), and the router caches the result per route + params |
+| `renderMode`, `dynamic` | picks the render strategy for the route |
+| `meta` | renders it into `<head>` |
+| `getStaticPaths` | enumerates which paths get prerendered |
+| `revalidate`, `staleWhileRevalidate` | sets the ISR cache window |
+| `cacheInvalidatesOn` | wires the page into the ISR cache invalidator |
+| `interactive` | decides how much client JS is shipped |
+| `tenantAware` | forms part of the server-side cache key |
+
+That reload is deliberate, not a gap. The HTML you are looking at was produced
+from the OLD value, so hot-swapping the export would leave stale output on
+screen with nothing to signal it. A reload re-runs SSR with the new value, and
+the console line names the export and the server step that consumed it.
 
 The mechanism, in case you hit an edge: React Fast Refresh only accepts a module
 whose exports are all components, and a page exporting `loader` beside its
 component fails that test. `voltro dev` registers each route module's
-non-component exports with the React plugin's ignore hook, and decides the
-reload itself by comparing those exports' VALUES across the update — a function
-by its source text, anything else by its JSON form — so a JSX-only edit (which
-recreates the `loader` object) is correctly read as "unchanged".
+non-component exports with the React plugin's ignore hook (so Fast Refresh
+judges only the components), then makes the reload call itself by comparing the
+server-read exports' VALUES across the update — a function by its source text,
+anything else by its JSON form — so a JSX-only edit, which recreates the
+`loader` function object, is correctly read as "unchanged".
 
-One consequence worth knowing: a page that exports a non-component value which
-changes on the same save as its JSX — a `const COLUMNS = [...]` you edit
-together with the table that renders it — reloads rather than hot-updates. Move
-that value into a sibling module (`./columns.ts`) and the page hot-updates
-again; the sibling's own edits still propagate through the page's boundary.
+One residual caveat: **adding or removing** a non-component export still
+reloads once, whatever it is. Fast Refresh sees an export that was not on the
+ignore list yet and refuses the boundary; the next edit to that page hot-updates
+normally.
 
 ### The in-page devtools overlay
 
@@ -515,6 +541,7 @@ A `<DevtoolsStringsProvider strings={…}>` mounted above the overlay works too;
 | `PORT=4001` | Override the listen port (api or web). Both kinds read `PORT`, then `app.config.ts` `port:`, then the default. |
 | `VOLTRO_DASHBOARD_PORT=5180` | Override the auto-launched dashboard port (default `5179`). |
 | `VOLTRO_LOG_LEVEL=debug` | Verbose framework logs. |
+| `VOLTRO_DEV_SSR_COMPILE_CONCURRENCY=4` | Max `ssr` pages compiled on demand at once (default `4`). Lower it (`1`/`2`) on a low-memory box if a burst of first-time `ssr` page loads spikes memory; raise it on a big machine. Warm (already-compiled) pages are never throttled. |
 
 ## Multi-app dev (turbo)
 
@@ -810,6 +837,16 @@ It covers both halves of the stack:
 | client | `useMemo` fanning in several subscriptions | `useDerived` |
 | client | a local Next.js compat shim | the native `@voltro/web` exports |
 | client | a hand-rolled presence heartbeat | `@voltro/plugin-presence` |
+| client | `data === undefined` / `!data` on a subscription result | branch on `loading` (and `idle`, if you pass `skip`) |
+
+The subscription rule **resolves the binding** rather than matching text, and
+that distinction is the reason this scanner parses at all. A consumer migrating
+these call sites wrote a regex codemod for the same job, and it rewrote a
+`summary === undefined` check inside a child component where `summary` was a
+PROP. Their compiler happened to catch it, because that name was out of scope
+there; had the names matched, a silent behaviour change would have shipped. Text
+cannot tell you which declaration an identifier refers to — so a rule about
+identifiers has no business being written in text.
 
 The rules are deliberately conservative — a detector that cries wolf trains you
 to ignore it. A column that already carries `.encrypted()`, or a handler that
@@ -873,13 +910,52 @@ voltro doctor . --json          # the complete scan: every file path, machine-re
       "use": ".one() — fails with the typed NoRowFound on zero rows AND on more than one",
       "files": ["queries/team.get.ts", "queries/user.get.ts", "…"]
     }
-  ]
+  ],
+  "spaCandidates": []
 }
 ```
 
 That is the form to hand an agent, or to pipe into a script that works the list
 file by file.
 
+### `renderMode:'spa'` candidates
+
+`voltro doctor` also flags web pages that could adopt `renderMode: 'spa'` without
+losing their server-rendered shell. A page under a layout renders that LAYOUT
+chain on the server — nav, sidebar, auth gate, via the layout's own loader — even
+when the page itself is `'spa'`. So a page whose BODY needs no SSR can skip its
+per-page SSR compile while the shell still server-renders. Like the hand-roll
+detector, this is **advisory and never blocking**.
+
+A page is listed when ALL of these hold:
+
+- it is a **page file** — not `layout.tsx` / `loading.tsx` / `error.tsx` /
+  `not-found.tsx`;
+- it exports **no `loader`** (so `'spa'` loses nothing the page contributed
+  server-side);
+- its `renderMode` is **`'ssr'` or unset/default** — not a page that already
+  opted into a non-SSR render (`'spa'` / `'static'` / `'isr'`, or any other
+  explicit mode);
+- a **`layout.tsx` sits somewhere in its directory chain** — root, an ancestor, or
+  the page's own dir. This is the load-bearing condition: only then does a layout
+  still SSR the shell. A page with no layout would, as `'spa'`, ship no server
+  HTML at all — so it is never flagged.
+
+```text
+•  renderMode:'spa' candidates (2 pages — loader-free, under a layout, currently ssr/default):
+   src/pages/dashboard/index.tsx  (/dashboard) — default renderMode
+   src/pages/admin/settings.tsx  (/admin/settings) — renderMode:'ssr'
+     → renderMode:'spa' skips this page's SSR compile while its layout shell still renders server-side — adopt it if the page BODY does not need SSR (internal/authenticated pages); keep 'ssr' if the page content needs SEO or server first-paint.
+```
+
+Adopt `'spa'` for internal or authenticated pages whose content needs no SEO or
+server first-paint; keep `'ssr'` (or the `'static'` default) when it does. There
+is deliberately **no codemod** to flip pages automatically — dropping a page
+body's server render is a per-page product decision, not a mechanically-safe
+transform. Every candidate (with its `file`, `pattern`, and `currentMode`) is
+also in `voltro doctor --json` under a `spaCandidates` array; the human view
+above caps at ten pages and points to `--json` for the rest.
+
 ## `voltro capabilities` — what the framework actually exports
 
 Asked "what does this framework export", a language model will produce a

package/templates/agent-docs/data.md

@@ -994,6 +994,51 @@ try {
 }
 ```
 
+### Multi-step sequences — `useSequence`
+
+The rule above says a loop keeps its `try/catch`, and that left multi-step
+writes as the only verbose thing on the write path — while being the hardest
+case, not the easiest. `useSequence` runs the steps in order, gives the whole
+sequence **one** `onError`, and lets each step say how to undo itself:
+
+```tsx
+const seq = useSequence({ onError: (e) => toast.error(readError(e)) })
+
+const result = await seq.run(
+  sequence()
+    .step('upload', () => upload.run({ file }), {
+      undo: (created) => removeObject.run({ id: created.id }),
+    })
+    .step('attach', (c) => createAttachment.run({ refId: c.upload.id })),
+)
+
+if (result.ok) setAttachmentId(result.data.attach.id)
+```
+
+Each step's context is typed and accumulates, so a fourth step can read the
+first step's result by name. `run` resolves with a discriminated result rather
+than rejecting — same "handled" semantics as `useMutation`/`useAction`.
+
+**`undo` receives its own step's result**, which is the point: the id you just
+created is what you need to delete it again. Undos run in reverse for the steps
+that already succeeded.
+
+**This is not a transaction, and the difference matters.** After `createTicket`
+returns, the ticket exists in Jira; nothing the browser does un-creates it, it
+can only issue a delete and hope. And the compensation runs *in the tab* — close
+it, lose the network, or navigate away mid-rollback and the remaining undos
+never happen. Two rules follow, and the primitive enforces both:
+
+- the step that **failed** is never compensated (it may or may not have had an
+  effect — undoing it is a guess, and a wrong guess deletes something else);
+- a failing `undo` never replaces the original error, and never stops the
+  remaining undos. Cleanup failures come back in `compensationFailures`, so an
+  orphan is something you can see rather than something you find later.
+
+**When the rollback has to survive a closed tab, this is the wrong tool.** Put
+the sequence in a [workflow](/docs/workflows/overview): the engine owns retries
+and compensation there, and a crash resumes instead of leaking.
+
 ## Action vs Mutation vs Stream
 
 | Need | Use |
@@ -1118,6 +1163,40 @@ const { data } = useSubscription(
 
 While skipped, no WebSocket subscription opens and `data` stays `undefined`.
 
+### Skipped is `idle`, not `loading`
+
+A skipped subscription reports **`idle: true`, `loading: false`**. The two are
+different questions — "waiting for the first snapshot" and "not asking at all" —
+and conflating them breaks the pattern this hook otherwise blesses:
+
+```tsx
+// WRONG on a skipping call site — renders a skeleton for a query you switched off
+if (loading) return <Skeleton/>
+```
+
+Passing a dynamic `skip` therefore changes the return type: you get a third
+state, and TypeScript will not let you ignore it.
+
+```tsx
+const s = useSubscription<Team[]>('app', 'teams.list', {}, { skip: !open })
+
+if (s.idle)    return null          // deliberately not asking
+if (s.loading) return <Skeleton/>   // asking, no answer yet
+return <TeamsTable teams={s.data}/> // `data` is Team[] — narrowed
+```
+
+Call sites that never skip are untouched — `if (loading)` still proves `data` is
+present there, and a literal `{ skip: false }` counts as never skipping. The
+third state exists only where "not asking" is a real outcome.
+
+With a `fallback` there is nothing to narrow either way: `data` is always
+present, and `idle` tells you whether what is on screen is the fallback because
+you chose not to ask.
+
+A subscription that was live and is then skipped goes idle — it does **not**
+keep serving the snapshot it still holds. Otherwise `skip: !open` would show
+last time's data the moment a dialog reopens.
+
 ## Streams Are Different
 
 For non-database or transient element feeds, use [streams](/docs/data/streams), not subscriptions:
@@ -1794,6 +1873,35 @@ export default defineSubscriber({
 
 The default export must be a `defineSubscriber({...})` result. The file is identified by suffix (`*.subscribe.ts` / `*.subscribe.tsx`).
 
+## `ctx.store` — reading and writing back
+
+`ctx` carries `log`, `id`, and **`store`** — the same store surface a handler
+uses, so a subscriber can act on the change it just saw:
+
+```ts
+export default defineSubscriber({
+  table: 'orders',
+  on:    'insert',
+  handler: async (event, ctx) => {
+    await ctx.store.insert('order_audit', {
+      orderId:  String(event.new?.['id']),
+      tenantId: String(event.new?.['tenantId']),   // explicit — see below
+    })
+  },
+})
+```
+
+**`ctx.store` is NOT tenant-scoped.** A subscriber fires from the change stream,
+not from a request, so there is no subject to scope to and no tenant to infer.
+Reads see every tenant's rows; a write to a `tenant()` table without an explicit
+`tenantId` fails with `TenantScopeViolation` rather than landing in an arbitrary
+tenant. When your reaction is per-tenant, take the tenant from the row that
+changed, as above. This is the same posture a schedule's `ctx.app.store` has —
+both are post-request system work.
+
+Writes are mixin-stamped exactly as a request-path write is: id scheme,
+timestamps, audit columns. Only the subject differs.
+
 ## What fires when
 
 The framework binds to the store's `onChange` channel. Subscribers fire **after the transaction commits** — the row IS persisted when your handler runs. This means:
@@ -1818,7 +1926,7 @@ Subscribers are **non-durable** by design:
 - **Async handlers are NOT awaited by the dispatcher.** Fire-and-forget — a slow handler can't back-pressure the change stream. Errors propagate to the structured log via `.catch()`, but the change-emission path returns immediately.
 - **No retry, no resume.** If the process crashes mid-handler, the work is gone. Same if the network call inside the handler fails — there's no built-in retry policy.
 
-If you need any of those properties (transactional, durable, retried), don't hand-roll the kickoff in the handler — a subscriber's `ctx` carries exactly two members (`ctx.log` and `ctx.id`), so there is no framework handle to start a workflow with. "A row changed → start a workflow" has its own primitive: a [reaction](/docs/data/reactions). A `*.reaction.tsx` watches the same post-commit change stream and its `act` starts the workflow for you, behind mandatory guards:
+If you need any of those properties (transactional, durable, retried), don't hand-roll the kickoff in the handler — a subscriber's `ctx` carries no workflow handle, deliberately. "A row changed → start a workflow" has its own primitive: a [reaction](/docs/data/reactions). A `*.reaction.tsx` watches the same post-commit change stream and its `act` starts the workflow for you, behind mandatory guards:
 
 ```tsx
 // reactions/fulfillOrder.reaction.tsx

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

@@ -38,7 +38,11 @@ export default defineSeed({
 
 Seeds are meant to be safe to re-run. The `upsertByUnique(table, matchFields, fullRow)` helper does "row matching `matchFields` exists? update it : insert it", returning `{ row, created }`. Use stable string ids (not random tokens) so subsequent runs match the same rows instead of duplicating.
 
-The runner also fingerprints each seed by hashing its source. On a `boot`-lifecycle seed it only re-runs when the fingerprint changes — so an unchanged seed doesn't re-execute on every `voltro dev` restart. Override the fingerprint when the seed depends on external state (env vars) that should force a re-run:
+The runner also fingerprints each seed by hashing its source. On a `boot`-lifecycle seed it only re-runs when the fingerprint changes — so an unchanged seed doesn't re-execute on every `voltro dev` restart. The record lives in `_voltro_seeds`, one row per seed.
+
+Two things the skip deliberately does **not** do. A **failed** run is recorded as failed and never satisfies the skip, so a broken seed retries on the next boot instead of disabling itself permanently. And if the ledger cannot be read at all — unmigrated database, memory store, missing table — every boot seed **runs**: re-doing idempotent work costs time, whereas skipping data restoration on a database we could not inspect costs data.
+
+Override the fingerprint when the seed depends on external state (env vars) that should force a re-run:
 
 ```ts
 fingerprint: ({ src }) => `${src}:${process.env.SEED_VERSION ?? ''}`,
@@ -50,9 +54,21 @@ fingerprint: ({ src }) => `${src}:${process.env.SEED_VERSION ?? ''}`,
 |---|---|---|
 | `boot` | On every `voltro dev` boot, **only if the fingerprint changed** | — |
 | `manual` | Only via `voltro db seed --id <name>` or the dashboard | — |
-| `onTenantCreate` | After a successful `tenant()` insert | — |
-| `onSchemaChange` | After a [migration](/docs/database/migrations) touches a watched table | `watchedTables` |
-| `cron` | On a cron cadence (via the [scheduling](/docs/scheduling/overview) runtime) | `cron` |
+| `onTenantCreate` | **Not wired yet** — declared and validated, never triggered | — |
+| `onSchemaChange` | **Not wired yet** — declared and validated, never triggered | `watchedTables` |
+| `cron` | **Not wired yet** — declared and validated, never triggered | `cron` |
+
+Only `boot` and `manual` actually execute today. The other three lifecycles
+validate at definition time (a `cron` seed without a `cron` field throws, an
+`onSchemaChange` seed without `watchedTables` throws) and are registered so the
+dashboard can list them — but nothing fires them. A seed declared with one of
+them will never run, silently.
+
+Until they are wired, express the same intent with a primitive that does run: a
+`*.cron.tsx` schedule whose handler does the seeding, or an explicit `voltro db
+seed --id <name>` from your migration/provisioning step. This table said
+otherwise until 0.10.0, which is exactly the kind of promise that costs someone
+a debugging afternoon — it is corrected here rather than quietly dropped.
 
 ```ts
 defineSeed({

package/templates/agent-docs/routing.md

@@ -469,22 +469,25 @@ The generated `.framework/app.tsx` records this chain explicitly per route — y
 <!-- source: en/routing/render-modes.md -->
 ## Render modes
 
-_static (SSG) vs ssr vs isr — when each runs, what it caches, and how to pick._
+_static (SSG) vs spa vs ssr vs isr — when each runs, what it caches, and how to pick._
 
-Every page declares a `renderMode`. The mode controls **when** the HTML is produced — at build time, on every request, or build-once-revalidate-occasionally.
+Every page declares a `renderMode`. The mode controls **when** the HTML is produced — at build time, on every request, build-once-revalidate-occasionally, or not on the server at all.
 
 ```tsx
-export const renderMode = 'static' as const   // 'static' | 'ssr' | 'isr'
+export const renderMode = 'static' as const   // 'static' | 'spa' | 'ssr' | 'isr'
 ```
 
-## The three modes
+## The four modes
 
 | Mode | When HTML is produced | Cached? | Best for |
 |---|---|---|---|
 | `static` *(default)* | `voltro build` time | Forever | Marketing pages, docs, anything that doesn't change per-request |
+| `spa` | Never for the page itself (its layout chain may still be server-rendered) | — | Reactive dashboards whose state lives in the browser |
 | `ssr` | Every request | Never | Authenticated dashboards, search results, anything cookie-driven |
 | `isr` | First request after build, then on revalidate | Per-key in-memory or Postgres | News feeds, listings, dashboards that change but not per-user |
 
+Those four are the **complete** set. An unrecognised value is a hard error naming the page — see [What doesn't work](#what-doesnt-work).
+
 ## static (SSG)
 
 ```tsx
@@ -625,6 +628,35 @@ The framework reads Postgres logical replication; writes to `posts` or `comments
 
 Requires `SSR_CACHE=postgres` and a `wal_level=logical` Postgres.
 
+## spa (client-only, with an optional SSR layout shell)
+
+```tsx
+export const renderMode = 'spa' as const
+```
+
+A `spa` page renders entirely in the browser — the page itself is never server-rendered. Reach for it when a page genuinely needs a fresh client render every load (most reactive dashboards) and doesn't need its own first-paint HTML or SEO.
+
+**If the page's route has a layout, that layout is still server-rendered.** The server renders the layout chain — running its layout loaders — around an empty page slot (`<div data-voltro-page-slot>`), inlines the layout data, and marks the page client-only. The browser hydrates that shell and mounts the page into the slot after hydration. So the shell (nav, sidebar, auth gate) gets an instant first paint while the page stays client-only. The page's own `loader` still runs in the browser.
+
+Because a layout now runs on the server for spa routes too, a layout used **only** by spa pages must be SSR-safe — no unguarded `window` / `document` in its render or its `loader`. Layouts shared with any `static` / `ssr` / `isr` page already render server-side (and `static` is the default), so they are unaffected. A spa page with **no** layout is a pure client mount, unchanged.
+
+**`voltro build` prerenders that shell to a file — but only when no layout in the page's chain exports a `loader`.** A layout loader may resolve per-visitor data (the signed-in user, a tenant), and freezing one render of it into a static file would serve the first visitor's data to everyone. So a chain with any layout loader is left to `voltro start`, which runs the loader per request; the build logs which route it skipped and why. A loader-less chain is request-independent by construction and is written to `dist/<route>/index.html`, so a static host paints the layout immediately instead of an empty `#root`.
+
+**On a static host, that file is also the SPA fallback.** A static host answers every URL it has no file for with `index.html` — so once your ROOT route is prerendered, a deep link to `/reports` is served the root's document. The framework handles this: the inlined hydration payload records the pathname it was rendered for, and the client refuses to adopt markup that belongs to another route, falling back to a normal client render instead. Without that check React would hydrate the root's layout while rendering `/reports`, report a hydration mismatch, and silently re-render the whole tree.
+
+Nothing to configure. Two things follow from it, though:
+
+- Deep links into a static deployment are **client-rendered**, not hydrated. The visitor sees the app; they don't get the prerendered paint. If that matters for a route, give it `static` (or `isr`/`ssr` behind `voltro start`) so it has a file of its own.
+- The pathname is compared *after* normalising a trailing slash, a trailing `/index.html`, and percent-encoding — the shapes a static host varies on. Your own routes are unaffected.
+
+**A layout in that chain may use `defer()`.** The shell then STREAMS: the layout chain and the empty page slot flush immediately, and the deferred layout value arrives afterwards behind its `<Await>` boundary — the same mechanism an `ssr` page gets, applied to the shell. So a sidebar whose nav counts take 300ms no longer holds back the first paint of the rest of the shell. Nothing about the hydration seam changes: the first flush still carries the empty page slot, and the page still mounts into it after hydration.
+
+What still cannot defer on this path:
+
+- **A prerendered shell.** `voltro build` only prerenders a shell whose chain has no layout loader (see above), and `defer()` can only come from a loader — so the two never meet. If they did, the build would refuse by name rather than freeze the `<Await>` fallback into the file.
+- **The page's own loader.** A `spa` page's loader runs in the *browser*, so there is no server render to stream into. Use `<Await>` on a client promise instead, or move the data into a layout loader.
+- **`interactive: 'none'` / `'islands'`**, for the same reason as on an `ssr` page: revealing a streamed boundary needs React's inline reveal scripts, and neither mode ever hydrates the root.
+
 ## Picking between them
 
 | You have… | Use |
@@ -663,12 +695,15 @@ A request to `/foo`:
 1. **Pre-rendered HTML exists at `dist/foo/index.html`?** Serve it. (static + isr-already-cached.)
 2. **No pre-render, page is `ssr`?** Render fresh, serve.
 3. **No pre-render, page is `isr`?** Cache lookup → MISS → render → store → serve.
-4. **No pre-render, page is `static`?** Serve the SPA shell — the client router takes over.
+4. **No pre-render, page is `spa` with a layout?** Render the SSR layout shell (layouts + an empty page slot) on demand; the client mounts the page into the slot.
+5. **No pre-render, page is `spa` with no layout, or `static`?** Serve the SPA shell — the client router takes over.
 
 That last case is how dynamic `static` routes work in dev / when `getStaticPaths` didn't include the URL.
 
 ## What doesn't work
 
+- **Any value outside the four modes.** `renderMode` is a closed set — `'static' | 'spa' | 'ssr' | 'isr'`. Anything else (`'client'`, `'csr'`, a typo) fails the build and `voltro dev` at codegen, naming the page, the value and the valid set. There are no aliases: a page that renders only in the browser is `'spa'`.
+- **Declaring `renderMode` on a `layout.tsx` / `error.tsx` / `loading.tsx`.** The mode is a property of the PAGE; the framework never reads one off a special file. Whether a layout renders on the server follows from the page's mode.
 - **Switching `renderMode` per request.** It's a static module export — one value per build.
 - **Assuming `ssr` is client-only in dev.** It is not: `voltro dev` runs the same SSR path `voltro start` does, streaming included, so cookie-driven gates and `useServerRequest()` behave the same in both. What dev does NOT do is pre-render `static` pages — those fall through to the SPA shell.
 - **`isr` with `cacheInvalidatesOn` against memory cache.** Memory cache is per-process; CDC events fire across processes. Use `SSR_CACHE=postgres`.
@@ -763,12 +798,19 @@ loaders in the browser as usual. A `spa` page has no server render, so its
 loader runs on the client on first mount.
 
 Layout loaders are inlined the same way, keyed per layout, so each layout reads
-its OWN data on the first render. The one exception is `voltro build`'s static
-prerender, which runs page loaders but not layout loaders — a `static` page's
-layouts resolve their data on the client after mount. The PAGE keeps its own
-inlined data for the whole of that window, however slow those layout loaders
-are, so the no-guard promise above holds on a prerendered page too: only the
-layout shows its no-data fallback until its loader settles.
+its OWN data on the first render. This includes `voltro build`'s static
+prerender: it runs the page loader **and** every layout loader in the chain at
+build time, so a CMS-backed nav or footer is baked into the prerendered file and
+the layout loader does not re-run after hydration. Layout loaders see the same
+build-time context the page loader does — `params`, `pathname`, `signal` — and
+nothing request-shaped: there is no `headers` and no `query` at build time. A
+layout loader that needs either belongs on an `ssr` page.
+
+If a layout loader throws during the build, the page is still prerendered — with
+no layout data, and a warning in the build log. The layout then resolves its
+data on the client after mount, and the PAGE keeps its own inlined data for the
+whole of that window, so the no-guard promise above still holds: only the layout
+shows its no-data fallback until its loader settles.
 
 
 ## Deferring slow data: `defer()` + `<Await>`
@@ -789,7 +831,7 @@ export const loader = async ({ query }: { query?: <T>(tag: string, input?: Recor
   // EAGER — awaited before the shell renders. Keep this fast.
   { user: await query?.<User>('users.me') },
   // DEFERRED — NOT awaited. Each becomes a promise on useLoaderData().
-  { report: query!<Report>('reports.quarterly') },
+  { report: query!<QuarterlyReport>('reports.quarterly') },
 )
 
 export default function Dashboard() {
@@ -835,8 +877,12 @@ otherwise guarantees by construction.
 A rejected deferred value never takes the page down: it renders
 `errorFallback` in place, on the server and on the client alike.
 
-### `defer()` requires `renderMode: 'ssr'` and full interactivity
+### `defer()` requires a streamed response and full interactivity
 
+That means `renderMode: 'ssr'`, or — for a **layout** loader — the SSR layout
+shell of a `renderMode: 'spa'` page under it, which `voltro dev` and
+`voltro serve` also stream (see
+[render modes](/docs/routing/render-modes#spa-client-only-with-an-optional-ssr-layout-shell)).
 Every other combination is a **hard error at boot or build**, naming the page —
 because each one fails silently otherwise:
 
@@ -846,8 +892,9 @@ because each one fails silently otherwise:
 | `renderMode: 'isr'` | ISR caches a completed HTML string. Filling it in would make `defer()` a silent no-op that still reads like it streams. |
 | `interactive: 'none'` | Revealing a streamed boundary needs React's inline reveal scripts, and this mode ships no JS. The fallback would be permanent. |
 | `interactive: 'islands'` | The page's React root never hydrates, so nothing consumes the streamed value. |
+| A **prerendered** spa layout shell | `voltro build` writes it to a file, which has no "after". Unreachable in practice — the build only prerenders a shell whose chain has no layout loader — but refused by name if it ever is reached. |
 
-In all four cases the fix is the same: put the value in the eager bucket (or
+In all of these the fix is the same: put the value in the eager bucket (or
 return it directly) and let the page render as it did before.
 
 ### Layout loaders can defer too
@@ -856,6 +903,13 @@ A `layout.tsx` loader may return `defer()` under the same rules. Its deferred
 fields are keyed per layout, so a layout reads its own promises via
 `useLoaderData()` exactly as a page does.
 
+This includes a layout that wraps a **client-only (`renderMode: 'spa'`) page**.
+The server renders that route as a layout shell — the layout chain around an
+empty page slot — and a deferring layout makes that shell stream: chain and slot
+first, the deferred layout value afterwards. The page still mounts on the client
+after hydration, unchanged. What a spa page's **own** loader cannot do is defer:
+it runs in the browser, so there is no server render to stream into.
+
 ### Client-side navigation
 
 On a client-side navigation there is no server render, so the loader runs in the
@@ -931,6 +985,15 @@ Two rules that fall out of this:
 
 Under the hood, `ctx.query` is a one-shot `POST /rpc` call (see [Wire protocol](/docs/data/wire-protocol#http-one-shot-rpc-post-rpc)).
 
+### Authentication in loaders
+
+Auth is resolved by the **api**, never the web app. Two rules follow:
+
+- **Strategies live on the `type:'api'` app.** A `type:'web'` app has no auth middleware, so `auth.strategies` in a web `app.config.ts` does nothing. Configure your IdP (`supabaseStrategy`, `workosStrategy`, the built-in password strategy, …) on the api's `app.config.ts`.
+- **`ctx.query` forwards the request's cookie automatically.** A server-side loader's `ctx.query` sends the browser's `Cookie` header on the one-shot `POST /rpc`, so the api resolves the SAME Subject + tenant it would over the WebSocket. You never thread a token through by hand — a logged-in user's cookie-mode session (e.g. `@supabase/ssr`'s `sb-<ref>-auth-token`) is verified by the api's strategies, and tenant-scoped queries return that user's rows during SSR.
+
+So a cookie-mode Supabase app configures `supabaseStrategy({ cookieName: 'sb-<ref>-auth-token' })` on the **api**; the web loader's `ctx.query` then authenticates for free. See [Supabase Auth](/docs/plugins/auth-supabase).
+
 ## Errors from loaders
 
 If the loader throws, the framework:

package/templates/agent-docs/scheduling.md

@@ -224,6 +224,38 @@ Use `scheduledAt`, not `Date.now()`, for any time-bucketed query (the "prune ses
 
 `ctx.trigger === 'manual'` distinguishes a dashboard **Run now** click from a clock firing — handy when a manual run should skip a guard (e.g. "only on weekdays") that the scheduled path enforces.
 
+## A schedule runs as the SYSTEM subject — no tenant
+
+`ctx.app.store` is **not tenant-scoped**. A schedule has no request, so it has
+no signed-in user and no tenant to infer, and the framework refuses to pick one
+for you. Reads see every tenant's rows.
+
+That is the right default for what crons usually are — a backfill, a reconcile,
+a GC sweep — but it means a **per-tenant** cron has to say which tenant it means:
+
+```tsx
+handler: async (ctx) => {
+  const tenants = await ctx.app.store.select('tenants').all()
+  for (const t of tenants) {
+    const stale = await ctx.app.store.select('sessions')
+      .where('tenantId', t.id)                    // explicit, not inferred
+      .where('expiresAt', '<', ctx.scheduledAt)
+      .all()
+    // …
+  }
+}
+```
+
+Writes to a `tenant()` table need the same treatment: pass `tenantId`
+explicitly, or the write fails with `TenantScopeViolation` rather than landing
+somewhere arbitrary.
+
+This behaves identically under `voltro dev` and `voltro serve`. It did not
+always — before 0.10.0, dev scoped schedules to `$TENANT` (default `acme`)
+while production ran them unscoped, so the same cron read one tenant in
+development and all of them in production. If you added `.unscoped()` to a cron
+to work around that, it is now a no-op and can go.
+
 ## Discovery
 
 `voltro dev` and `voltro build` glob `**/*.cron.{ts,tsx}` under your api app. Each discovered schedule is logged at boot:

package/templates/apps/api-ai/package.json

@@ -11,16 +11,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/ai": "0.8.0",
-    "@voltro/cli": "0.8.0",
-    "@voltro/database": "0.8.0",
-    "@voltro/env": "0.8.0",
-    "@voltro/protocol": "0.8.0",
-    "@voltro/runtime": "0.8.0",
+    "@voltro/ai": "0.10.0",
+    "@voltro/cli": "0.10.0",
+    "@voltro/database": "0.10.0",
+    "@voltro/env": "0.10.0",
+    "@voltro/protocol": "0.10.0",
+    "@voltro/runtime": "0.10.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.8.0",
+    "@voltro/testing": "0.10.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }