@voltro/cli 0.13.0 → 0.15.0

package/templates/agent-docs/data.md

@@ -911,10 +911,10 @@ Throw a matching error from the server file; the client can narrow on `_tag`.
 
 Tagged errors **round-trip structurally** over the wire — the caught value carries `_tag` plus every declared field as real properties (and `instanceof` works, same Schema class both ends). You do **not** need to parse the error message string.
 
-Inside Effect, use `Effect.catchTag('NoteQuotaExceeded', …)`. In a React `try/catch` (outside Effect, where `catchTag` isn't available and the decoded value may be a plain object, not a class instance), match with **`errorTag(err)`** — the dependency-free tag reader `@voltro/client` ships:
+Inside Effect, use `Effect.catchTag('NoteQuotaExceeded', …)`. In a React `try/catch` (outside Effect, where `catchTag` isn't available and the decoded value may be a plain object, not a class instance), match with **`errorTag(err)`** — the dependency-free tag reader `@voltro/protocol` ships (it reads what `toRpc` writes):
 
 ```ts
-import { errorTag } from '@voltro/client'
+import { errorTag } from '@voltro/protocol'
 
 try {
   await createNote(input)
@@ -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
 

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

@@ -435,6 +435,27 @@ VOLTRO_DESTRUCTIVE_OK=1 voltro db apply --note 'retiring users table after migra
 
 For complex multi-table retirements (move data out, then drop), use a [file-based migration](./file-based.md) — explicit ordering + a transaction wrapped around the data move.
 
+### Name the tables, not the whole run
+
+`VOLTRO_DESTRUCTIVE_OK=1` acknowledges **every** lossy op in the plan. That is
+rarely what you mean — a plan with one intended drop and three other lossy ops
+would have all four approved by a single `1`. Give it a comma-separated list
+instead:
+
+```sh
+# Only these tables — every other lossy op in the plan stays refused.
+VOLTRO_DESTRUCTIVE_OK=users,legacy_notes voltro db apply --note 'retiring the pre-migration tables'
+```
+
+An op the list does not name stays blocked, and a plan with anything still
+blocked is refused as a whole. Half a plan applied is how a schema ends up in a
+state neither the declaration nor the database describes.
+
+There is deliberately **no `.dropped()` marker for a table**, unlike for a
+column. A dropped column leaves a slot worth documenting in the declaration; a
+dropped table leaves nothing, so the marker would be a dead entry you have to
+remember to delete.
+
 ## `.narrowedFrom()` for type changes
 
 A bare column type change is **refuse-to-plan** — the planner blocks it
@@ -1132,6 +1153,59 @@ If `down` throws, the rollback is treated as failed — the schema stays
 in the half-rolled-back state + the operator handles it manually. The
 framework can't auto-recover from a broken inverse.
 
+## Remote databases: boot will not apply them unattended
+
+`voltro dev` applies pending migration files at boot. Against a local
+database that is the whole point of the escape hatch. Against a remote
+one it means that saving a file is enough to change production — before
+review, before CI, without typing a command.
+
+So when the configured database is **not local** and there are pending
+migration files, dev boot refuses instead:
+
+```text
+file-based migrations: refusing to auto-apply 1 file-based migration(s)
+to a REMOTE database (ep-cool-dawn.eu-central-1.aws.neon.tech).
+
+  Pending:
+    • 20260725_150000_drop_legacy_subscriptions
+```
+
+A database counts as **local** when its host is loopback
+(`localhost`, `127.0.0.1`, `::1`), a private LAN address
+(`10.x`, `192.168.x`, `172.16–31.x`), `host.docker.internal`, a `.local`
+/ `.localhost` name, a `file:` / `sqlite:` URL, or a **bare hostname**
+like `postgres` or `db` — only a container network resolves those, so
+`docker compose up` keeps working untouched. Everything else — a managed
+provider, any dotted public hostname, an unparseable `DB_URL` — counts as
+remote.
+
+Three ways forward:
+
+```sh
+# 1. Point the app at a local database (what dev boot assumes)
+DB_URL=postgres://app:app@localhost:5432/app voltro dev
+
+# 2. Apply them deliberately, once
+voltro db files .
+
+# 3. Accept unattended applies for this environment
+VOLTRO_REMOTE_MIGRATIONS_OK=1 voltro dev
+```
+
+The gate is **silent when nothing is pending**, which is the normal
+case — running dev against a remote database is unaffected until the
+moment a file would actually execute against it. It refuses rather than
+skipping quietly: a skipped migration leaves the database in a shape the
+app does not expect (a half-done table split, a column the handlers
+already read), and the failures that follow point everywhere except at
+the cause.
+
+It does **not** try to detect destructive SQL. In arbitrary SQL that is
+not decidable, so such a check would be either leaky or noisy. What the
+gate separates is the two things boot used to conflate: *saving a file*
+and *applying it to production*.
+
 ## Applying file-based migrations from the CLI
 
 `voltro db files` applies pending file-based migrations under
@@ -2242,7 +2316,7 @@ If multiple apps target the same database, they're showing the same `_voltro_mig
 
 ## Source code
 
-The shared component lives in `voltro/packages/devtools-ui/src/pages/MigrationsPage.tsx`. The local devtools wiring is in `voltro-devtools/apps/dashboard/src/pages/apps/[appId]/migrations.tsx`. Both repos are open to extension.
+The shared component lives in `voltro/packages/devtools-ui/src/pages/MigrationsPage.page.tsx`. The local devtools wiring is in `voltro-devtools/apps/dashboard/src/pages/apps/[appId]/migrations.page.tsx`. Both repos are open to extension.
 
 
 
@@ -2430,8 +2504,8 @@ server enforces this regardless of which buttons the UI renders.
 
 ## Source code
 
-- Component: `voltro/packages/devtools-ui/src/pages/MigrationsPage.tsx` — shared
-- Cloud wiring: `voltro-cloud/apps/voltro-cloud/dashboard/src/pages/_/p/[orgSlug]/[projectSlug]/apps/[appSlug]/migrations.tsx`
+- Component: `voltro/packages/devtools-ui/src/pages/MigrationsPage.page.tsx` — shared
+- Cloud wiring: `voltro-cloud/apps/voltro-cloud/dashboard/src/pages/_/p/[orgSlug]/[projectSlug]/apps/[appSlug]/migrations.page.tsx`
 - Cloud-api proxy: `voltro-cloud/apps/voltro-cloud/api/queries/apps.inspectMigrationsStatus.query.ts` + `.query.server.ts`
 - Approval schema: `voltro-cloud/apps/voltro-cloud/api/database/migrationPlans.entity.ts` + `migrationApprovals.entity.ts`
 - Approval rpc: `migrations.submitPlan` + `migrations.approve` (mutations), `migrations.pendingApprovals` (query), `migrations.reviewByToken` (action)

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

@@ -39,6 +39,17 @@ This section covers everything about how the framework reads + writes data.
 
 You declare tables once. The migrator produces SQL; the runtime gives you a typed `ctx.store`; the reactive engine watches the same rows.
 
+**Every table is reactive by default.** There is nothing to opt into — this is a
+reactive framework, so a capability you had to remember to switch on is one half
+your tables would not have. Writes emit change events, subscriptions stay live,
+and on a multi-instance deployment the change reaches the other instances too.
+
+`.nonReactive()` turns it off for one table, on every dialect: no subscriber
+fires, locally or across instances. The write still happens — this is about
+notification, never persistence. Use it for a genuinely hot table nobody
+subscribes to (an append-only event log, a metrics sink); never for one a query
+reads, because that subscription would never fire. `voltro dev` warns if you do.
+
 ## A first table
 
 ```ts

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

@@ -150,6 +150,13 @@ See [migrations](/docs/database/migrations) for schema changes — seeds populat
 
 _Six SQL backends, one schema DSL. Decision matrix, configuration, boot-log shape, and the cross-dialect feature parity table the framework hides for you._
 
+**Reactivity is dialect-independent.** Every table is reactive by default on all
+six backends — you write nothing to get it, and `.nonReactive()` turns it off
+for one table everywhere. What differs is only the TRANSPORT that carries a
+change between instances: Postgres uses LISTEN/NOTIFY, MySQL and MariaDB read
+the binlog, MSSQL uses Change Tracking, and SQLite / Turso have no native one —
+[`@voltro/plugin-broadcast`](../multi-replica) closes that gap.
+
 Voltro runs on six SQL backends. The application code — schema, queries, workflows, subscriptions, the reactive engine — is written ONCE and compiles down to the dialect-native idiom at runtime. Selecting a dialect is a single environment variable.
 
 ```
@@ -361,7 +368,27 @@ The framework wraps `pg` (`node-postgres`) via Effect's typed connection layer.
 
 ## CDC — LISTEN/NOTIFY
 
-Every `*.reactive()` table gets an AFTER trigger that emits a `framework_changes` notification on each insert / update / delete. The dispatcher LISTENs on that channel once per process and fans out to subscribers in-memory.
+Every table gets an AFTER trigger that emits a `framework_changes` notification on each insert / update / delete. The dispatcher LISTENs on that channel once per process and fans out to subscribers in-memory.
+
+**Every table gets this by default.** Reactivity is what the framework is for,
+so you write nothing to opt in — the trigger above is installed for every table
+unless you opt it out.
+
+`.nonReactive()` turns reactivity **off** for a table — not "off across
+instances". It emits no change events at all: no local subscriber fires and no
+cross-instance transport carries it. That holds on every dialect, including
+sqlite and turso, because the guard sits at each store's emit. On postgres it
+additionally drops the trigger and `REPLICA IDENTITY FULL`; on mysql/mariadb and
+mssql it drops the table from the reader's filter.
+
+The write itself is unaffected — this is about notification, never persistence.
+
+Worth using for a genuinely hot table nobody subscribes to: an append-only event
+log, a metrics sink. `REPLICA IDENTITY FULL` widens every UPDATE/DELETE in the
+WAL and the trigger fires on every write, so that is a real saving.
+
+Do **not** use it on a table a query reads — that subscription will never fire.
+`voltro dev` and `voltro serve` warn at boot when that combination exists.
 
 Latency: very low on a local-network postgres (it varies with network and load). The framework instruments this — `voltro traces` shows the notification → dispatcher → subscriber waterfall.
 
@@ -514,6 +541,11 @@ rows.map((r) => r.id)   // ← the full generated range, in input order
 
 MySQL has no `LISTEN/NOTIFY`, but MySQL 8's ROW-format binary log is a real out-of-band CDC source — the SAME binlog the framework already tails for mariadb. The framework tails the primary's binlog via the `@vlasky/zongji` replication client, so **every replica tails the binlog itself and a write on any instance surfaces on every instance's `onChange`** (true cross-instance reactivity in a multi-replica deploy). This is at parity with mariadb: binlog CDC is **one path** with per-variant detection, not two implementations.
 
+**Every table is reactive by default** — nothing to opt into. `.nonReactive()`
+turns it off for one table on *every* dialect: no subscriber fires, locally or
+across instances. The write still happens; only the notification is suppressed.
+See [the schema overview](/docs/database/overview).
+
 ### How it works
 
 1. With `CDC=1` (the default for any SQL dialect) on `mysql`, the store starts a binlog reader on a **separate replication connection** — distinct from the SQL pool.
@@ -739,6 +771,11 @@ The framework uses it for the no-pagination case of `many()` / `manyToMany()` on
 
 MariaDB has no `LISTEN/NOTIFY`, but it gets a real out-of-band CDC source: the framework tails the primary's **ROW-format binary log** via the `@vlasky/zongji` replication client. This is the MariaDB equivalent of postgres's `LISTEN/NOTIFY` — **every replica tails the binlog itself, so a write on any instance surfaces on every instance's `onChange`** (true cross-instance reactivity in a multi-replica deploy).
 
+**Every table is reactive by default** — nothing to opt into. `.nonReactive()`
+turns it off for one table on *every* dialect: no subscriber fires, locally or
+across instances. The write still happens; only the notification is suppressed.
+See [the schema overview](/docs/database/overview).
+
 This is **one binlog-CDC path shared with `mysql`** — mysql-8 and mariadb speak the same ROW binlog to the reader, so both get cross-instance CDC. The only engine difference is the binlog-end query (mariadb `SHOW MASTER STATUS`; mysql 8.4 `SHOW BINARY LOG STATUS`), which the store picks per variant.
 
 ### How it works
@@ -979,6 +1016,11 @@ Requires the deployment to use Always-On AGs (the modern HA story since SQL Serv
 
 SQL Server ships **Change Tracking** (CT) — a lightweight, built-in change source available on every edition (unlike the heavier Change Data Capture feature). The framework's mssql store uses it as an out-of-band CDC reader so a write on ANY instance surfaces on EVERY instance's `onChange` — the mssql equivalent of postgres `LISTEN/NOTIFY` or mariadb binlog CDC.
 
+**Every table is reactive by default** — nothing to opt into. `.nonReactive()`
+turns it off for one table on *every* dialect: no subscriber fires, locally or
+across instances. The write still happens; only the notification is suppressed.
+See [the schema overview](/docs/database/overview).
+
 Enable it and set `changeStrategy: 'cdc'` (the default when `CDC` is not `0`):
 
 ```sh
@@ -1098,6 +1140,11 @@ SQLite is single-writer by definition. Setting `DB_REPLICA_URLS=…` is a no-op
 
 Sqlite has no LISTEN/NOTIFY equivalent and no trigger-based fan-out is needed (everything runs in one process). The framework's `SqliteStore` uses an in-process Node `EventEmitter` (composed as a private field, not subclassed):
 
+**Every table is reactive by default** — nothing to opt into. `.nonReactive()`
+turns it off for one table on *every* dialect: no subscriber fires, locally or
+across instances. The write still happens; only the notification is suppressed.
+See [the schema overview](/docs/database/overview).
+
 - Insert/update/delete emit `'change'` events synchronously to the dispatcher.
 - The dispatcher's `onChange` callback is registered against the emitter — no polling, no triggers, no log table.
 
@@ -1237,6 +1284,11 @@ Like `sqlite`, Turso is single-node here. The workflow engine boots with `runner
 
 Same as `sqlite`: an in-process Node `EventEmitter` fans insert/update/delete events to the dispatcher. Sub-millisecond, single-process. No `LISTEN/NOTIFY`, no triggers.
 
+**Every table is reactive by default** — nothing to opt into. `.nonReactive()`
+turns it off for one table on *every* dialect: no subscriber fires, locally or
+across instances. The write still happens; only the notification is suppressed.
+See [the schema overview](/docs/database/overview).
+
 ## Not supported on Turso (beta gaps)
 
 These are SQLite features the `sqlite` dialect has but Turso's MVCC mode does not. The framework fails LOUD at migrate rather than emit DDL the engine rejects:

package/templates/agent-docs/internationalization.md

@@ -423,7 +423,7 @@ export default function Layout({ children }) {
 }
 ```
 
-Pair this with locale-prefixed page files: `src/pages/[locale]/index.tsx`, `src/pages/[locale]/docs/[...slug].tsx`, etc. Each re-exports the default-locale query's component, which reads `useUrlLocale()` to decide which catalog data to query.
+Pair this with locale-prefixed page files: `src/pages/[locale]/index.page.tsx`, `src/pages/[locale]/docs/[...slug].page.tsx`, etc. Each re-exports the default-locale query's component, which reads `useUrlLocale()` to decide which catalog data to query.
 
 Reference implementations: `voltro-dev/apps/voltro-dev/docs/` (URL-prefix on dynamic + static content) and `voltro-dev/apps/voltro-dev/landing/` (URL-prefix on a pure static marketing site — 10 default-locale pages, 10 locale-prefixed mirrors, one combined `voltro build` run).
 
@@ -441,7 +441,7 @@ dist/de/features/foo/index.html        ← de mirror
 Each variant ships with the right `<I18nProvider>`-wrapped body **and** the right per-locale `<title>` / `<meta description>` / `<link rel="canonical">` / OG tags — **if** the page's `meta` is exported as a function of `({ locale })`. With a plain static `meta: PageMeta` object, the body is correctly localised but the head tags stay default-locale on every variant.
 
 ```tsx
-// src/pages/features/foo.tsx — meta as a function of locale
+// src/pages/features/foo.page.tsx — meta as a function of locale
 import { getCatalog } from '../lib/locale'
 import { localeCanonicalUrl, ogTags, standardLinks } from '../lib/seo'
 
@@ -472,7 +472,7 @@ The `[locale]/…` mirror is the trigger for SSG **output** — without mirror f
 12 lines per page. Re-export the canonical page's `default`, `renderMode`, `interactive`, `meta`, plus a `getStaticPaths` that enumerates non-default locales:
 
 ```tsx
-// src/pages/[locale]/features/foo.tsx
+// src/pages/[locale]/features/foo.page.tsx
 import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../../lib/locale'
 export { default } from '../../features/foo'
 export { renderMode, interactive, meta } from '../../features/foo'