@voltro/cli 0.23.0 → 0.24.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
 import { Z as e } from "./inspectMetrics-dcC7gnxu.js";
 import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-Cl8sicD5.js";
+import { t as r } from "./serveCommand-C4gzDZzc.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.23.0",
+  "version": "0.24.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.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.23.0",
-    "@voltro/cache": "0.23.0",
-    "@voltro/data-transfer": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/kv": "0.23.0",
-    "@voltro/logger": "0.23.0",
-    "@voltro/plugin-auth": "0.23.0",
-    "@voltro/plugin-broadcast": "0.23.0",
-    "@voltro/plugin-mail": "0.23.0",
-    "@voltro/plugin-storage": "0.23.0",
-    "@voltro/plugin-webhooks": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
-    "@voltro/serverless": "0.23.0",
-    "@voltro/workflow": "0.23.0",
+    "@voltro/ai": "0.24.0",
+    "@voltro/cache": "0.24.0",
+    "@voltro/data-transfer": "0.24.0",
+    "@voltro/database": "0.24.0",
+    "@voltro/env": "0.24.0",
+    "@voltro/kv": "0.24.0",
+    "@voltro/logger": "0.24.0",
+    "@voltro/plugin-auth": "0.24.0",
+    "@voltro/plugin-broadcast": "0.24.0",
+    "@voltro/plugin-mail": "0.24.0",
+    "@voltro/plugin-storage": "0.24.0",
+    "@voltro/plugin-webhooks": "0.24.0",
+    "@voltro/protocol": "0.24.0",
+    "@voltro/runtime": "0.24.0",
+    "@voltro/serverless": "0.24.0",
+    "@voltro/workflow": "0.24.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/agent-docs/authentication.md

@@ -166,6 +166,27 @@ import { handleSignIn } from '@voltro/plugin-auth'
 
 Use `handleSignIn` instead of rolling your own — the timing-oracle gap is the kind of subtle bug that hides for years. Note it returns a `401 HandlerResult`, it does not throw a domain error.
 
+## Brute-force lockout
+
+`plugin-auth` locks an account after repeated failed credential attempts, so password-spraying and credential-stuffing don't get unlimited guesses. After **5 failed attempts** (a wrong password — or, for MFA users, a wrong second-factor code) within **15 minutes**, sign-in for that email is refused with a `429 account_locked` (carrying a `retryAfterSeconds`) for **15 minutes**. A completed login clears the counter.
+
+The counter is keyed by **email**, not user id, and it tracks unknown addresses too: a locked account and an unknown-but-hammered address respond identically, so the lock can't be turned into an existence oracle — the same reasoning as the timing-oracle defence above.
+
+It is **on by default** — a security default you get for free. Tune or disable it per app:
+
+```ts
+authRoutesPlugin({
+  store,
+  lockout: {
+    maxAttempts: 5,      // failed attempts before locking (default 5)
+    windowSeconds: 900,  // counting window (default 15 min)
+    lockSeconds: 900,    // lock duration (default 15 min)
+  },
+})
+```
+
+The counter lives in the `loginAttempts` table (contributed via `authTables`), so it appears automatically on your next `voltro db apply` / `voltro dev` boot. For lockout that holds across multiple nodes, back the store with Postgres (`postgresUserStore`) — the in-memory store is single-node.
+
 ## Rehashing on parameter bump
 
 When the framework updates the default cost parameters, existing hashes stay valid — `verifyPassword` reads `N`/`r`/`p` from the stored hash string itself (they're encoded inline as `scrypt$<N>$<r>$<p>$…`). Rehash-on-verify ships: `needsRehash(stored)` reports whether a hash is below the current cost, and `verifyPasswordWithRehash(plaintext, stored)` returns `{ valid, rehash? }` — when the password matches an under-cost hash, `rehash` is a freshly-minted replacement. `handleSignIn` wires this through `UserStore.updatePassword`, so a user's stored hash silently strengthens on their next login, no forced reset and no backfill.

package/templates/agent-docs/cli.md

@@ -2174,6 +2174,23 @@ voltro data restore ./backups/2026-07-01    # pg_restore / mysql / …
 
 These shell out to the vendor tools resolved from your `DB_DIALECT` + connection env. They produce a dialect-native artifact (`db.dump`, `db.sql`, `db.sqlite`, `db.bacpac`) that is lossless and point-in-time consistent for **same-dialect** restore — the right tool for disaster recovery. Secrets are passed via the tools' environment variables (`PGPASSWORD`, `MYSQL_PWD`), never on the command line, where the tool supports it. The named tool must be installed and on `PATH`.
 
+### The provenance stamp — a restore that refuses the wrong DB
+
+A native dump is opaque: it doesn't say which dialect made it, which schema shape it carries, or when. `backup` writes a sidecar `voltro-backup-stamp.json` next to the artifact recording exactly that — `dialect`, the live schema `fingerprint`, the `@voltro/cli` version, and the timestamp.
+
+`restore` reads the stamp **before touching the DB** and acts on two failures that are otherwise silent until they corrupt:
+
+- **Cross-dialect restore → refused.** Restoring a postgres dump while `DB_DIALECT=mysql` is never valid; it stops with an error instead of half-loading. Override with `--force` only if you genuinely know better.
+- **Schema/code skew → warned.** If the backup's schema fingerprint differs from what the running code declares, restore prints a warning to run `voltro db apply` afterwards — the dump's shape predates (or postdates) this deploy's code. (Production boot already refuses on a fingerprint mismatch; the stamp surfaces it at restore time, before the boot.)
+
+A backup with no stamp (older, or hand-made) restores with a caution rather than a hard stop.
+
+### Point-in-time recovery (PITR) is your database's job, not the framework's
+
+`backup` is a point-in-time **snapshot**. "Restore to 14:32, just before the bad deploy" (PITR) needs continuous WAL/binlog archiving, which lives at the database/provider layer — pg's `archive_command` + a base backup (pgBackRest / WAL-G), a managed provider's continuous backup (RDS, Cloud SQL, Neon, PlanetScale). The framework deliberately does **not** reimplement it: layer PITR under these native snapshots at the infra layer. A weekly `voltro data backup` + provider PITR together give you both a portable artifact and a fine-grained restore point.
+
+> **Test your backups.** A backup you've never restored is a hypothesis. Restore your latest artifact into a throwaway database and boot the app against it on a schedule — the stamp's dialect/fingerprint checks turn a silently-broken backup into a loud one, but only an actual restore proves the bytes are good.
+
 ## Masking (prod → dev/stage safely)
 
 Cloning prod into a lower environment must not carry real user data. `voltro data export`

package/templates/agent-docs/data.md

@@ -816,6 +816,26 @@ try {
 
 The same applies to `run` on [actions](/docs/data/actions).
 
+## Idempotency — a retried mutation runs exactly once
+
+The reactive client resends an in-flight mutation after a network blip. Without a guard, "create order" or "charge card" would run twice. `useMutation` (and `useAction`) mint a fresh **idempotency key** per call and attach it to the rpc frame; when idempotency is enabled the server dedupes a repeat of that key — the handler runs once and the retry replays the first result.
+
+Enable it once (this also covers the REST `Idempotency-Key` header — one switch, both surfaces):
+
+```ts
+// app.config.ts
+export default {
+  idempotency: true, // or { ttlMs: 600_000 } — the dedup window (default 24h)
+}
+```
+
+For a HIGHER-level guarantee — dedupe a double-click or an offline resend of the *same logical action* — pass a STABLE key derived from the action's identity, instead of the per-call one:
+
+```ts
+await placeOrder.mutate(cart, { idempotencyKey: `order:${cart.id}` })
+```
+
+The key is scoped to `(tenant, subject, mutation)`, so one user's key can never replay another's. The replayed result is byte-for-byte the first one — a `Date` in the output comes back a `Date`, not a string — because it round-trips through the mutation's output schema. Off by default: with no `idempotency` config, every call runs.
 
 ## Auto-Optimistic
 
@@ -2123,171 +2143,6 @@ 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 -->
@@ -2735,6 +2590,171 @@ into the agent's prompt.
 
 
 
+---
+
+<!-- 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/outbox.md -->

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

@@ -4,69 +4,6 @@
 
 
 
----
-
-<!-- source: en/database/migrations/adopt.md -->
-## Adopting a table into a plugin's
-
-_voltro db adopt — move an app's grown table into a plugin-owned one, with a snapshot, a count verify and the drop last._
-
-An app that did not start on a green field already has a table for half the plugins it installs. `voltro db adopt` is the way **into** the plugin's table, so using the plugin does not mean running a second source of truth beside it.
-
-```bash
-voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts
-voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts --apply
-```
-
-**Dry run unless you pass `--apply`.** The interesting failure here is irreversible and the interesting output is the refusal, so nothing is written until you say so. A refused plan prints no steps at all, rather than a preview of something that will not happen.
-
-## The map file is yours
-
-```ts
-// ai-flows.map.ts
-export default {
-  map: {
-    name:         'name',
-    mode:         { expr: `CASE WHEN "allowDeviation" THEN 'agentic' ELSE 'deterministic' END` },
-    costMicroUsd: { expr: '"totalCostCents" * 10000' },
-  },
-  leaveUnset: ['id'],
-}
-```
-
-Read `target: source` — fill the plugin's column FROM this expression of mine, which is the direction the SQL runs. A string is a source column; `{ expr }` is raw SQL against the source row, for the unit conversions and merged fields no tool can infer. Those are domain knowledge, and a tool inventing them silently corrupts data.
-
-`leaveUnset` is how "the target's own default fills this" stops looking like "I forgot it".
-
-## What it refuses
-
-- **a NOT NULL target column nobody maps to** — the alternative is a silent zero that reads as real data forever after;
-- **a target table that already holds rows** — adopt MOVES rows into a table, it does not merge into one somebody else already wrote;
-- **a typo on either side of the map.**
-
-A source column nobody carries across is reported but not fatal: dropping a dead column is deliberate often enough, and "I forgot this" and "I decided" look identical in a map file.
-
-## The order, and why the drop is last
-
-1. **snapshot** — `<table>__adopt_snapshot`, a real table in the same database, so restoring is a statement rather than an operational procedure at 2am. It keeps the columns the adopt left behind.
-2. **copy**
-3. **verify by count** — this catches the one failure that is otherwise invisible: a `WHERE` inside a raw expression silently dropping rows.
-4. **drop the source** — last, and only if the counts match.
-
-On a mismatch **both tables stay** and the command says so. The snapshot is never removed after a failed verify — it exists for exactly the run that goes wrong. `--keep-source` copies and verifies without dropping at all.
-
-## Ids, if the typeid prefixes differ
-
-The dry run says so before anything runs, because discovering it after the copy is discovering it too late: every row gets a new id, so every reference to the old table has to be rewritten — **including ids embedded in JSON columns**.
-
-Rewriting them is **not** automatic. Those ids live in your columns and inside your JSON, and only you know where. The translation table is what the command owes you; the rewrite is what you owe yourself. Doing it automatically is the one place here where being wrong would be silent.
-
-## After the move
-
-Your rows are now in a table whose shape the framework evolves — and nothing special happens to them. They migrate exactly like every other row, through the same declarative differ. A narrowing can fail on your data, loudly, the same way it would on anybody's.
-
-
-
 ---
 
 <!-- source: en/database/migrations/index.md -->
@@ -3295,6 +3232,35 @@ Fix:
   resolves the root from the first non-flag argument, defaulting to
   the current working directory
 
+## "N reactive table(s) have NO change trigger in the database" (postgres)
+
+```text
+auto-migrate: 500 reactive table(s) have NO change trigger in the database —
+ab_test_results, ab_test_variants, ab_tests, … (+492). Writes to them will not
+reach another instance's subscribers; a single instance is unaffected, which is
+why this stays invisible until you scale out. Run `voltro db apply` to install them.
+```
+
+On postgres, reactivity is carried by DDL: a per-table `framework_changes_<table>` trigger that `NOTIFY`s the CDC channel. The declared schema and the database can disagree about which tables have one.
+
+**Run `voltro db apply`.** It converges the triggers as its own step, and it does so **even when the schema diff is empty** — the usual case here, because a missing trigger is not a shape difference and `db plan` will correctly report `0 operations`:
+
+```text
+$ voltro db apply
+schema diff: 0 operations, 0 blocked
+  (schema is up to date)
+db apply: installing change triggers on 500 table(s)
+db apply: change triggers converged (1501 statement(s))
+```
+
+`db apply --plan` converges them too, so the pre-deploy Job pattern needs no extra step.
+
+**Why a table ends up without one.** The trigger DDL is emitted by the full-schema path — a fresh database — so any table that arrived while your app was already running, or during a release that installed none, has no trigger. A restored dump can do it too (triggers travel with a full dump, but not with a schema-only or `--no-triggers` one), as can a hand-run `DROP TRIGGER` during an incident.
+
+**Why it stays invisible.** A single instance's own writes reach its own subscribers through the in-process path. The trigger is what carries a write to the *other* instances, so the symptom only appears when you scale out — subscriptions that quietly stop updating, with nothing in the logs.
+
+The mirror case is reported the same way: a `.nonReactive()` table that still carries a trigger keeps paying `REPLICA IDENTITY FULL` and a `NOTIFY` on every write for a subscription nobody receives. `db apply` removes both.
+
 ## When the fix hint doesn't match reality
 
 The fix hints come from the planner's classification logic — they should always be actionable. If you see one that doesn't make sense given your code:
@@ -3313,3 +3279,66 @@ Hint mismatches are bugs in the planner's classification — they're rare but al
 - [Drift](./drift.md) — when the live DB diverged
 - [Multi-dialect strategy](./multi-dialect.md) — why MySQL + forward-roll
 - [Prod pipeline](./prod-pipeline.md) — the deploy-step apply pattern
+
+
+
+---
+
+<!-- source: en/database/migrations/adopt.md -->
+## Adopting a table into a plugin's
+
+_voltro db adopt — move an app's grown table into a plugin-owned one, with a snapshot, a count verify and the drop last._
+
+An app that did not start on a green field already has a table for half the plugins it installs. `voltro db adopt` is the way **into** the plugin's table, so using the plugin does not mean running a second source of truth beside it.
+
+```bash
+voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts
+voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts --apply
+```
+
+**Dry run unless you pass `--apply`.** The interesting failure here is irreversible and the interesting output is the refusal, so nothing is written until you say so. A refused plan prints no steps at all, rather than a preview of something that will not happen.
+
+## The map file is yours
+
+```ts
+// ai-flows.map.ts
+export default {
+  map: {
+    name:         'name',
+    mode:         { expr: `CASE WHEN "allowDeviation" THEN 'agentic' ELSE 'deterministic' END` },
+    costMicroUsd: { expr: '"totalCostCents" * 10000' },
+  },
+  leaveUnset: ['id'],
+}
+```
+
+Read `target: source` — fill the plugin's column FROM this expression of mine, which is the direction the SQL runs. A string is a source column; `{ expr }` is raw SQL against the source row, for the unit conversions and merged fields no tool can infer. Those are domain knowledge, and a tool inventing them silently corrupts data.
+
+`leaveUnset` is how "the target's own default fills this" stops looking like "I forgot it".
+
+## What it refuses
+
+- **a NOT NULL target column nobody maps to** — the alternative is a silent zero that reads as real data forever after;
+- **a target table that already holds rows** — adopt MOVES rows into a table, it does not merge into one somebody else already wrote;
+- **a typo on either side of the map.**
+
+A source column nobody carries across is reported but not fatal: dropping a dead column is deliberate often enough, and "I forgot this" and "I decided" look identical in a map file.
+
+## The order, and why the drop is last
+
+1. **snapshot** — `<table>__adopt_snapshot`, a real table in the same database, so restoring is a statement rather than an operational procedure at 2am. It keeps the columns the adopt left behind.
+2. **copy**
+3. **verify by count** — this catches the one failure that is otherwise invisible: a `WHERE` inside a raw expression silently dropping rows.
+4. **drop the source** — last, and only if the counts match.
+
+On a mismatch **both tables stay** and the command says so. The snapshot is never removed after a failed verify — it exists for exactly the run that goes wrong. `--keep-source` copies and verifies without dropping at all.
+
+## Ids, if the typeid prefixes differ
+
+The dry run says so before anything runs, because discovering it after the copy is discovering it too late: every row gets a new id, so every reference to the old table has to be rewritten — **including ids embedded in JSON columns**.
+
+Rewriting them is **not** automatic. Those ids live in your columns and inside your JSON, and only you know where. The translation table is what the command owes you; the rewrite is what you owe yourself. Doing it automatically is the one place here where being wrong would be silent.
+
+## After the move
+
+Your rows are now in a table whose shape the framework evolves — and nothing special happens to them. They migrate exactly like every other row, through the same declarative differ. A narrowing can fail on your data, loudly, the same way it would on anybody's.