@voltro/cli 0.13.0 → 0.14.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { X as e } from "./inspectMetrics-DOiiII34.js";
-import { t } from "./start-CjG_0xhR.js";
+import { $ as e } from "./inspectMetrics-CyVMeofr.js";
+import { t } from "./start-D8ATvTzo.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

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

package/templates/AGENTS.core.md

@@ -219,7 +219,7 @@ a `web/` (frontend).
 │   │   └── rpcGroup.generated.ts   # codegen — do NOT edit
 │   └── web/
 │       ├── app.config.ts       # { type:'web', apis, theme, locales, … }
-│       └── src/pages/**/*.tsx  # file-based routing
+│       └── src/pages/**/*.page.tsx  # file-based routing (only *.page.tsx)
 ├── packages/                   # shared libs
 └── AGENTS.md / CLAUDE.md       # this file
 ```
@@ -249,7 +249,77 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
-| `src/pages/**/*.tsx` | web page (file-based route) |
+| `*.page.tsx` (under `src/pages/`) | web page (file-based route) + `*.page.test.tsx` |
+| `*.component.tsx` | exactly ONE component (+ types) |
+| `*.component.ui.tsx` | presentational: one component, READS only — never writes |
+| `*.hook.ts` | exactly ONE `use*` hook (+ types) |
+| `*.types.ts` | types only — zero runtime exports |
+| `*.internal.ts` | only its own directory subtree may import it |
+| `*.fixture.ts` | test material — no production path may reach it |
+| `*.tracking.ts` | the ONLY place analytics may be called from |
+| `*.store.ts` | exactly ONE `defineStore` — client state, never server state |
+| `*.client.ts` | declares itself + its transitive imports browser-safe |
+
+**Only `*.page.tsx` is a route.** Everything else under `src/pages/` — components,
+hooks, tests — is ordinary code with no URL, so put it next to the page that uses
+it rather than in a distant `components/` directory. The suffix decides *whether*
+a file is a route; the path under `src/pages/` decides *which URL*. A `*.page.tsx`
+outside `src/pages/` never routes. A page MUST default-export its component —
+without it `voltro dev` refuses to boot and names the file.
+
+**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.
+- `*.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
+  it impossible for it to sit in a runtime import cycle.
+- `*.store.ts` holds ONE `defineStore`. Reads go through a selector
+  (`wizard.use((s) => s.step)`) — there is no whole-state read, because a
+  component holding all of it re-renders on every field. Scope a per-entity
+  instance with a KEY (`{ key: orderId }`), never a Provider. Seed it for SSR
+  from a loader with `seedStore(...)`; it rides the hydration payload the router
+  already writes. An action that writes SEVERAL fields wraps them in
+  `store.batch('label', () => …)` — one notification, one devtools entry, one
+  undo step, and a rollback if it throws; `await` first, then batch (an async
+  callback is an error). `{ persist: { key } }` survives a reload.
+  NEVER put server data in a store: a subscription is already
+  live, and a copy is not — the page then shows the stale one.
+- `*.tracking.ts` is where every `defineTracking(...)` spec lives — the event
+  catalogue, so "what do we send to third parties" is a file listing rather than
+  archaeology. A component wires one up with `useTracking(spec, props, sink)`; it
+  NAMES a spec, it never declares one. (`useTracking` is a hook, so it is not
+  confined — only the declaration is.)
+- Do NOT rename a file to `*.component.ui.tsx` just because it happens not to
+  write today. The suffix is a promise about what it MAY do.
+
+**These rules apply to code YOU write — never to vendored code.** A shadcn
+component (`npx shadcn add`) follows shadcn's conventions and is overwritten by
+the next `add`; renaming it breaks their convention and is undone next run. A
+directory is exempt when the app's `components.json` names it (`aliases.ui`) or
+it carries a `.voltro-vendored` file whose first line says where the code came
+from. Never add that marker to a directory of your own code — the point of the
+rules is that everything we author follows them.
+
+**Write the test in the same step as the code — always, for every primitive.**
+Not "afterwards", not in a cleanup pass: the filename is derivable
+(`users/[id].page.tsx` → `users/[id].page.test.tsx`,
+`Card.component.tsx` → `Card.component.test.tsx`,
+`order.mutation.server.ts` → `order.mutation.server.test.ts`), so there is
+nothing to decide. A change is not finished until its test exists and passes.
+
+Two traps worth naming, because a green run can hide both:
+
+- **`voltro test` transpiles without type-checking.** A type error in a TEST file
+  passes the suite and fails the package's `typecheck`. Run both.
+- **Never fake a service to make a test pass.** A test that only re-asserts its
+  own mock's return value is worse than no test — it reports coverage it does not
+  have. Assert the descriptor shape instead and cover the real path elsewhere.
 
 ## app.config.ts
 
@@ -344,9 +414,13 @@ declare it). Mixins compose via `.with(...)` and auto-stamp bookkeeping columns:
 ```ts
 export const todos = table('todos', { id: id(), title: text(), done: boolean().default(false) })
   .with(softDelete(), tenant())   // tenant() transitively requires audit()
-  .reactive()                     // opt into the matcher engine (subscriptions)
 ```
 
+- Every table is REACTIVE by default — nothing to opt into. `.nonReactive()`
+  turns reactivity OFF for a table entirely: no subscriber fires, locally or
+  across instances (the write still happens). Use it for a hot table nobody
+  subscribes to; never for one a query reads — that subscription never fires,
+  and `voltro dev` warns.
 - `id()` defaults to a branded **TypeID** (`todo_…`). Insert auto-injects it.
 - Indexes are **table-level** (`.index('name', [...])`) — there is NO
   column-level `.index()`. Declare `.index([...])` AFTER `.with(...)` to address

package/templates/AGENTS.md

@@ -219,7 +219,7 @@ a `web/` (frontend).
 │   │   └── rpcGroup.generated.ts   # codegen — do NOT edit
 │   └── web/
 │       ├── app.config.ts       # { type:'web', apis, theme, locales, … }
-│       └── src/pages/**/*.tsx  # file-based routing
+│       └── src/pages/**/*.page.tsx  # file-based routing (only *.page.tsx)
 ├── packages/                   # shared libs
 └── AGENTS.md / CLAUDE.md       # this file
 ```
@@ -249,7 +249,77 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
-| `src/pages/**/*.tsx` | web page (file-based route) |
+| `*.page.tsx` (under `src/pages/`) | web page (file-based route) + `*.page.test.tsx` |
+| `*.component.tsx` | exactly ONE component (+ types) |
+| `*.component.ui.tsx` | presentational: one component, READS only — never writes |
+| `*.hook.ts` | exactly ONE `use*` hook (+ types) |
+| `*.types.ts` | types only — zero runtime exports |
+| `*.internal.ts` | only its own directory subtree may import it |
+| `*.fixture.ts` | test material — no production path may reach it |
+| `*.tracking.ts` | the ONLY place analytics may be called from |
+| `*.store.ts` | exactly ONE `defineStore` — client state, never server state |
+| `*.client.ts` | declares itself + its transitive imports browser-safe |
+
+**Only `*.page.tsx` is a route.** Everything else under `src/pages/` — components,
+hooks, tests — is ordinary code with no URL, so put it next to the page that uses
+it rather than in a distant `components/` directory. The suffix decides *whether*
+a file is a route; the path under `src/pages/` decides *which URL*. A `*.page.tsx`
+outside `src/pages/` never routes. A page MUST default-export its component —
+without it `voltro dev` refuses to boot and names the file.
+
+**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.
+- `*.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
+  it impossible for it to sit in a runtime import cycle.
+- `*.store.ts` holds ONE `defineStore`. Reads go through a selector
+  (`wizard.use((s) => s.step)`) — there is no whole-state read, because a
+  component holding all of it re-renders on every field. Scope a per-entity
+  instance with a KEY (`{ key: orderId }`), never a Provider. Seed it for SSR
+  from a loader with `seedStore(...)`; it rides the hydration payload the router
+  already writes. An action that writes SEVERAL fields wraps them in
+  `store.batch('label', () => …)` — one notification, one devtools entry, one
+  undo step, and a rollback if it throws; `await` first, then batch (an async
+  callback is an error). `{ persist: { key } }` survives a reload.
+  NEVER put server data in a store: a subscription is already
+  live, and a copy is not — the page then shows the stale one.
+- `*.tracking.ts` is where every `defineTracking(...)` spec lives — the event
+  catalogue, so "what do we send to third parties" is a file listing rather than
+  archaeology. A component wires one up with `useTracking(spec, props, sink)`; it
+  NAMES a spec, it never declares one. (`useTracking` is a hook, so it is not
+  confined — only the declaration is.)
+- Do NOT rename a file to `*.component.ui.tsx` just because it happens not to
+  write today. The suffix is a promise about what it MAY do.
+
+**These rules apply to code YOU write — never to vendored code.** A shadcn
+component (`npx shadcn add`) follows shadcn's conventions and is overwritten by
+the next `add`; renaming it breaks their convention and is undone next run. A
+directory is exempt when the app's `components.json` names it (`aliases.ui`) or
+it carries a `.voltro-vendored` file whose first line says where the code came
+from. Never add that marker to a directory of your own code — the point of the
+rules is that everything we author follows them.
+
+**Write the test in the same step as the code — always, for every primitive.**
+Not "afterwards", not in a cleanup pass: the filename is derivable
+(`users/[id].page.tsx` → `users/[id].page.test.tsx`,
+`Card.component.tsx` → `Card.component.test.tsx`,
+`order.mutation.server.ts` → `order.mutation.server.test.ts`), so there is
+nothing to decide. A change is not finished until its test exists and passes.
+
+Two traps worth naming, because a green run can hide both:
+
+- **`voltro test` transpiles without type-checking.** A type error in a TEST file
+  passes the suite and fails the package's `typecheck`. Run both.
+- **Never fake a service to make a test pass.** A test that only re-asserts its
+  own mock's return value is worse than no test — it reports coverage it does not
+  have. Assert the descriptor shape instead and cover the real path elsewhere.
 
 ## app.config.ts
 
@@ -344,9 +414,13 @@ declare it). Mixins compose via `.with(...)` and auto-stamp bookkeeping columns:
 ```ts
 export const todos = table('todos', { id: id(), title: text(), done: boolean().default(false) })
   .with(softDelete(), tenant())   // tenant() transitively requires audit()
-  .reactive()                     // opt into the matcher engine (subscriptions)
 ```
 
+- Every table is REACTIVE by default — nothing to opt into. `.nonReactive()`
+  turns reactivity OFF for a table entirely: no subscriber fires, locally or
+  across instances (the write still happens). Use it for a hot table nobody
+  subscribes to; never for one a query reads — that subscription never fires,
+  and `voltro dev` warns.
 - `id()` defaults to a branded **TypeID** (`todo_…`). Insert auto-injects it.
 - Indexes are **table-level** (`.index('name', [...])`) — there is NO
   column-level `.index()`. Declare `.index([...])` AFTER `.with(...)` to address

package/templates/agent-docs/_manifest.json

@@ -53,7 +53,7 @@
       "group": null,
       "description": "How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.",
       "path": "agent-docs/data.md",
-      "files": 16
+      "files": 17
     },
     {
       "id": "database/advancedqueries",
@@ -179,7 +179,7 @@
       "group": null,
       "description": "Scaffold a Voltro project and boot it locally in under a minute.",
       "path": "agent-docs/introduction.md",
-      "files": 5
+      "files": 6
     },
     {
       "id": "multi-tenancy",

package/templates/agent-docs/authentication.md

@@ -573,8 +573,9 @@ If your authorization is a database ROLE rather than a scope on the token, the f
 // app.config.ts
 export default defineApiConfig({
   auth: {
-    resolveScopes: async (subject) => {
-      const role = await roleCache.get(subject.id)   // cache it — see below
+    resolveScopes: async (subject, { store }) => {
+      if (store === undefined) return []            // still booting — claim nothing
+      const role = await roleCache.get(subject.id, store)   // cache it — see below
       return role === 'admin' ? ['employee:admin', 'employee:read'] : ['employee:read']
     },
   },
@@ -591,6 +592,8 @@ export const payrollList = defineQuery({
 })
 ```
 
+**You get the app's DataStore.** A role lives in the database, and without it the only way to reach one was a second connection path beside the framework's — to the same database the request store opens a moment later. It is the BOOT store, not a request-scoped one: strategies resolve before a request store exists, so it is `undefined` while the store is still being built. Return `[]` then rather than guessing.
+
 **Scopes only — never a Subject.** The hook cannot change `id` or `tenantId`: identity belongs to the auth strategy, and a hook that could rewrite it would be a forgery surface. The returned scopes are UNIONED with whatever the strategy already set, so a resolver can grant authority but never revoke it.
 
 **It does not run for anonymous callers** — there is no identity to look a role up for.

package/templates/agent-docs/cli.md

@@ -154,6 +154,20 @@ requiring a scope no role grants, which makes that procedure permanently and
 silently uncallable. (With a custom `resolvePermissions` the vocabulary isn't
 exhaustive, so the rule stays quiet rather than flagging correct code.)
 
+`rbac/unenforced-scope` is the same registry read in the other direction: a
+scope a role GRANTS that no handler ever guards on. That direction has no
+artefact to inspect — you cannot grep for an authorization check that was never
+written, which is exactly why it survives review. One app modelled
+`api-keys:write` in its role catalogue, complete and reviewed, and no handler
+checked it: any member could mint a shared credential, and nothing failed.
+Tests pass when an authorization check is missing.
+
+It is a **warning**, because three innocent explanations exist: a plugin route
+enforces it internally (the graph cannot see inside a plugin), a REST route
+carries its own guards, or it is a UI-affordance scope that `useCan` reads to
+hide a button and no server check backs on purpose. All three are fine. Not
+knowing which is not.
+
 #### Declared vs OBSERVED — reconciled against reality
 
 A query's `source` and a mutation's `targets` are not documentation: the
@@ -466,6 +480,26 @@ The cleaner fix is on your side and worth doing anyway: start the container as
 the workspace owner, `docker run --user $(id -u):$(id -g)`. Then nothing needs
 handing over at all.
 
+### What the boot tells you
+
+Three checks run at boot and print one line each when they have something to say
+— never fatal, and silent when the answer is fine:
+
+- **A reactive table with no change trigger** (postgres). The schema fingerprint
+  covers columns, not triggers, so a restored dump or a hand-run `DROP TRIGGER`
+  leaves the schema "up to date" and the subscription silently not reaching other
+  instances. The reverse is reported too: a `.nonReactive()` table still carrying
+  a trigger pays `REPLICA IDENTITY FULL` and a NOTIFY per write for nothing.
+- **A `.nonReactive()` table that a query reads.** That subscription will never
+  fire — first snapshot, then silence forever.
+- **`apiKeys: true` with no `apikeys:issue:*` scope declared.** The capability is
+  on and reachable by nobody; every issue request fails its guard.
+
+`voltro doctor` adds a fourth, over your source: an executor that writes
+`ctx.request.subject.id` while naming no guard, which is how an anonymous caller
+reaches a NOT NULL column and gets a raw statement failure instead of a typed
+refusal.
+
 ## `voltro dev <appDir>`
 
 ```bash
@@ -1138,8 +1172,8 @@ A page is listed when ALL of these hold:
 
 ```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'
+   src/pages/dashboard/index.page.tsx  (/dashboard) — default renderMode
+   src/pages/admin/settings.page.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.
 ```
 

package/templates/agent-docs/data.md

@@ -971,6 +971,27 @@ const echo = useAction('app', 'demo.echo')
 await echo.run({ message })   // one call → one typed result
 ```
 
+### Actions declare what they touch
+
+An action is non-transactional external I/O, and it often touches a table on the
+way — a cache it fills, a job row it stamps. Declare it the same way a query and
+a mutation do:
+
+```ts
+export const syncIssue = defineAction({
+  name: 'jira.syncIssue',
+  input: Schema.Struct({ key: Schema.String }),
+  output: Schema.Struct({ ok: Schema.Boolean }),
+  source: 'jiraIssueCache',
+  target: { table: 'jiraIssueCache', op: 'upsert' },
+})
+```
+
+Without it the table is invisible to `voltro check`, which then reports it as an
+orphan. While any action declares neither, the orphan rule says so and asks for
+the declaration rather than proposing you delete the table — a wrong finding
+whose remedy is destructive is worse than a wrong finding.
+
 ## Action Pair
 
 Descriptor:
@@ -1207,6 +1228,12 @@ _How reactive query subscriptions stay live over WebSocket._
 
 A **subscription** is what the browser gets when it calls `useSubscription(...)` for a `defineQuery` RPC. The app code writes a query pair; the runtime keeps that query live over WebSocket and pushes new snapshots or deltas when matching data changes.
 
+Every table is reactive by default, so a query over any table is live with
+nothing to configure. A table explicitly marked
+[`.nonReactive()`](/docs/database/overview) emits no change events at all — a
+subscription over one returns its first snapshot and then stays silent forever,
+which is why `voltro dev` warns about that combination at boot.
+
 Subscriptions are not a separate file convention anymore. The file convention is [queries](/docs/data/queries): `*.query.ts` for the descriptor and `*.query.server.ts` for the executor.
 
 Live — add a todo (or open this page in a second tab) and the list updates with
@@ -2012,6 +2039,171 @@ When no analytics sink is configured the framework provides the no-op sink: the
 
 
 
+---
+
+<!-- source: en/data/client-state.md -->
+## Client state (defineStore)
+
+_defineStore — client state that is not server state. Selector-only reads, key scoping instead of providers, and SSR seeding that rides the payload the router already writes._
+
+Server state already has a home: a subscription **is** live server state, and it stays live. What has no home is the rest — which rows are selected, which wizard step you are on, the draft you have not submitted.
+
+Without a primitive for that you reach for zustand or jotai, which is a *parallel runtime* — the one thing the framework asks you not to bring. So it ships one.
+
+```ts
+// wizard.store.ts
+import { defineStore } from '@voltro/client'
+
+export const wizard = defineStore('wizard', () => ({ step: 0, draft: '' }))
+```
+
+```tsx
+const step = wizard.use((s) => s.step)                    // the global instance
+const step = wizard.use((s) => s.step, { key: orderId })  // one instance per order
+
+wizard.set({ step: 2 })
+wizard.set((s) => ({ ...s, step: s.step + 1 }))
+```
+
+## Reads go through a selector — there is no `useStore()`
+
+A component that holds the whole state re-renders on every change to any field, so an API that hands it over would be used and would be wrong. Reading a slice re-renders only when **that slice** changes:
+
+```tsx
+const coupon = wizard.use((s) => s.coupon)   // set({ note }) does not re-render this
+const count  = cart.use((s) => s.items.length) // ['a'] → ['b'] does not re-render this
+```
+
+### Computed values need `equals: shallow`
+
+A selector that *builds* something — an object literal, a mapped or filtered array — returns a fresh reference every call, so the default identity check reports "changed" forever and the component re-renders on **every** store change:
+
+```tsx
+import { shallow } from '@voltro/client'
+
+const visible = cart.use((s) => s.items.filter((i) => i.visible), { equals: shallow })
+const pair    = cart.use((s) => ({ a: s.a, b: s.b }), { equals: shallow })
+```
+
+You do not have to remember: in dev the framework detects the case and warns once, naming the fix. The selector is also memoised — it does not re-run while the state object is unchanged, so an expensive filter costs nothing on unrelated updates.
+
+## Scoping is by key, not by a Provider
+
+A Provider re-renders every consumer when its value identity changes, whether or not that consumer read the field that moved — that *is* what makes context painful at scale. So an instance is addressed by a key you already have:
+
+```tsx
+wizard.use((s) => s.step, { key: orderId })
+```
+
+which is the same model as everywhere else in the framework: `useSubscription('orders.list', { orgId })` is keyed by input, not by position in the tree. One read form, an optional key, no provider to forget.
+
+`wizard.release(orderId)` drops an instance; `wizard.keys()` lists the live ones.
+
+## SSR seeding adds no new channel
+
+Call `seedStore` anywhere on the server during a render and the value reaches the client's first render:
+
+```ts
+export const loader = async ({ params }) => {
+  seedStore(wizard, { step: 2 }, { key: params.orderId })
+  return { /* … */ }
+}
+```
+
+There is no `dehydrate()` to remember and no `hydrate()` to forget — the seed rides the hydration payload the router already writes, and `mount()` applies it before the tree exists. A step you can forget is a step somebody will.
+
+On the client `seedStore` **throws**. A silent no-op would leave the store empty in the browser and full on the server, and that surfaces as a hydration mismatch that reads like a React bug.
+
+**The key is part of the address.** Seed with `{ key: orderId }` and read with `{ key: orderId }`. A component reading the global instance while a loader seeded a key gets the initial value — correct, and easy to trip over once.
+
+## Surviving a reload
+
+`persist` writes the state to `localStorage` (or `sessionStorage`) on every change and reads it back when the store is defined:
+
+```tsx
+export const filters = defineStore(
+  'inbox:filters',
+  () => ({ status: 'open', sort: 'newest', draft: '' }),
+  {
+    persist: {
+      key: 'inbox:filters',
+      storage: 'local',              // 'session' lasts the tab
+      pick: (s) => ({ status: s.status, sort: s.sort }),
+      migrate: (stored) => (isFilters(stored) ? stored : undefined),
+    },
+  },
+)
+```
+
+Three details are the whole reason this is in the framework rather than in your codebase, because a hand-rolled version gets all three wrong:
+
+**The stored value is merged over `initial()`, not substituted for it.** Ship a new field and every returning user has state without it — `undefined` where the type promises a string. Merging means an old payload gains the new defaults.
+
+**`migrate` returning `undefined` discards the value.** A stale draft is an annoyance; a half-migrated one is a bug report nobody can reproduce. Discarding is the right answer far more often than guessing, so it is the easy one to write.
+
+**Every storage touch is guarded and wrapped.** The module is imported by the server render too, and Safari in private mode throws on *reading* `localStorage`, not just on writing. A store that throws at import time takes the page with it.
+
+**A persisted store on a server-rendered page hydrates against the *server* value.** The server has no `localStorage`, so it renders `initial()`; the stored value lands in the commit right after hydration. Without that, every returning user would get a hydration mismatch — a flash and a console error that reads like a React bug. `get()` is not deferred, only the render: an action reading the draft before the first paint reads the draft.
+
+`pick` narrows what gets written — persist the filters, not the open/closed state of every panel. And only the **global** instance persists: a keyed instance is per entity, and writing every key into one bucket grows without bound. Persist a map yourself if you mean to.
+
+## Actions that write more than once
+
+An action rarely touches one field. Applying a coupon writes the coupon *and* the recomputed total; that is one thing the user did, and `batch` says so:
+
+```ts
+checkout.batch('applyCoupon', () => {
+  checkout.set({ coupon })
+  checkout.set({ total: recompute(coupon) })
+})
+```
+
+One notification, one entry in the devtools feed named `applyCoupon`, and **one undo step**. Without it the same action is three of each — Ctrl-Z walks back through a third of a change at a time, and the feed shows three anonymous writes instead of the thing that happened. React batches the re-*renders* on its own; it cannot batch the meaning.
+
+**If the callback throws, every write it made is rolled back.** Nothing was announced yet, so an action that fails halfway cannot leave the half-applied state that is the usual reason people reach for a transaction. A nested `batch` joins its parent rather than opening a second one.
+
+### Async work goes around the batch, not inside it
+
+```ts
+const quote = await fetchQuote(coupon)          // await FIRST
+checkout.batch('applyCoupon', () => {           // then batch the writes
+  checkout.set({ coupon, total: quote.total })
+})
+```
+
+Passing an `async` function to `batch` is an **error**, not a warning. Everything after the first `await` would run outside the batch — writes escaping one at a time, a rollback covering only the synchronous head, and a devtools entry that lies about what the action did. Holding a batch open across time is not available: it would have to block every other write for the duration.
+
+## Undo and redo
+
+Every write passes through one seam, so the previous state is already recorded — undo is a lookup rather than a feature the store had to be designed around:
+
+```tsx
+draft.undo(orderId)      // back one write
+draft.redo(orderId)      // forward again
+draft.canUndo(orderId)   // for disabling the button
+draft.canRedo(orderId)
+```
+
+It is a cursor over an intact history, not a stack that consumes entries. So repeated calls walk back through the steps rather than toggling between the last two, and a **new write after an undo drops the redo tail** — the behaviour every editor has.
+
+An undo never becomes undoable itself, and each keyed instance has its own history.
+
+## Devtools: inspect, and travel
+
+The `voltro dev` overlay has a **Stores** tab. It lists every defined store with its live state — global and per key — and a feed of every write: which store, which key, the label if you passed one, and the fields that actually changed.
+
+`◀ Back` and `Forward ▶` step through that feed, restoring the state as it was before or after each write. The state a component reads moves with it, so you can walk back to the moment before a bug and watch it happen again.
+
+No extension, no connector, no version to match. Every write already passes through one seam, so the panel is just another subscriber — it sees writes made by code that never heard of devtools, on any machine, including a colleague's.
+
+## What a store must never hold
+
+Server data. Copying a subscription's rows into a store gives you a second copy that does not live; the page then renders the stale one, and the bug presents as *"reactivity is broken"*. `voltro doctor` reports a `*.store.ts` that reads a subscription.
+
+Read server state where you render it, and keep the store for what is genuinely client-side.
+
+
+
 ---
 
 <!-- source: en/data/crud.md -->
@@ -3098,7 +3290,7 @@ export const blogPost = defineContentType({
 register them in your `database/index.ts` so auto-migrate creates them. Both
 carry the lifecycle `status` column (`draft` / `published` / `archived`), the
 `tenant()` mixin (tenant-scoped reads/writes through the request store), and
-are `.reactive()` so a publish wakes live subscriptions.
+are reactive (the default) so a publish wakes live subscriptions.
 
 ## Reading — `ctx.cms`
 

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

@@ -657,11 +657,11 @@ DB_URL=postgresql://tsdbadmin:[PASSWORD]@[SERVICE].[PROJECT].tsdb.cloud.timescal
 
 Voltro's schema DSL emits ordinary Postgres tables. To turn one into a TimescaleDB hypertable (chunked by time for fast time-series queries), run `create_hypertable(...)` yourself after the table exists — via a custom migration or a `*.seed.ts` that issues the SQL. The framework's `voltro migrate` doesn't generate hypertable DDL; it's a deliberate, per-table decision.
 
-A table you convert to a hypertable still works with the reactive engine and `ctx.store` exactly as before — the conversion is transparent to Voltro's read/write path. Heavy time-series ingestion tables are usually NOT the ones you mark `.reactive()` (you don't want a subscription firing on every metric insert), so the two concerns rarely collide.
+A table you convert to a hypertable still works with the reactive engine and `ctx.store` exactly as before — the conversion is transparent to Voltro's read/write path. Heavy time-series ingestion tables are usually the ones you mark `.nonReactive()` (you don't want a notification firing on every metric insert), so the two concerns rarely collide.
 
 ## Enabling CDC
 
-Timescale is real Postgres, so Voltro's change-data-capture is `LISTEN/NOTIFY` and **on by default** (`CDC=1`) — no extension, no flag, and TimescaleDB's presence changes nothing here. Timescale Cloud puts **no transaction pooler in front by default**, so the `DB_URL` you connect with is session-mode and reactivity works immediately. (If you mark a hypertable `.reactive()`, every chunk insert fires a notification — usually you don't want that on high-ingest time-series tables; see the hypertable note above.)
+Timescale is real Postgres, so Voltro's change-data-capture is `LISTEN/NOTIFY` and **on by default** (`CDC=1`) — no extension, no flag, and TimescaleDB's presence changes nothing here. Timescale Cloud puts **no transaction pooler in front by default**, so the `DB_URL` you connect with is session-mode and reactivity works immediately. (Every table is reactive by default, so on a hypertable every chunk insert fires a notification — usually not what you want on high-ingest time-series tables. Mark it `.nonReactive()`; see the hypertable note above.)
 
 ## Pooling / SSL