@voltro/cli 0.13.0 → 0.14.0

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

@@ -1132,6 +1132,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 +2295,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 +2483,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'

package/templates/agent-docs/introduction.md

@@ -383,11 +383,28 @@ Procedure descriptors are intentionally separate from server executors. Descript
 
 The browser-safe rule is **transitive**, and that is where it usually breaks. The codegen pulls every descriptor (and every workflow descriptor) value-level into `rpcGroup.generated.ts`, which the web client loads — so a descriptor plus *everything it imports* must stay free of server-only code (`node:*`, the `database` handle, `@voltro/ai`, cluster, plugins, `@voltro/protocol/session`). The classic mistake is not a literal `import 'node:crypto'` but a descriptor importing a shared typed-error or helper from a `lib/` file that *also* imports the database — which drags the whole schema graph into the browser bundle. Keep typed errors, Schemas, and pure helpers in files with zero server imports; put DB-backed guards in `.server.ts`. A leak shows up as the web app fetching hundreds of modules / tens of MB on first load, or crashing with `Module "node:crypto" has been externalized for browser compatibility`.
 
+### Declaring a shared file browser-safe: `*.client.ts`
+
+A shared `lib/` helper can state the rule about itself. Name it `*.client.ts` (or `*.client.tsx`) and it declares: *I, and everything I transitively import, are browser-safe.* `voltro dev` walks its import graph at boot and refuses to start if the claim is false, printing the chain.
+
+```text
+lib/orderErrors.client.ts   # I and my imports are browser-safe — checked at boot
+lib/orderGuards.server.ts   # I may touch the database handle
+lib/orderTypes.ts           # unmarked: no claim, the graph decides
+```
+
+This is the mirror of `*.server.ts`, and it works for the same reason: both declare a **permission**, which is something an import graph cannot derive. The graph can tell you what a file imports; it can never tell you what a file is *allowed* to import.
+
+Without the marker the leak is still caught — by the rpcGroup guard — but only once some descriptor happens to reach the file, and the error is a forty-module chain you read backwards to find the one shared file that should never have touched the database. The marker moves the failure to that file, at the moment it is written.
+
+An unmarked file makes no claim, and that is fine: `*.client.ts` is for the shared files where the mistake is expensive, not a label to sprinkle on everything.
+
+
 ## The web side (`apps/*/web/`)
 
 | Path | What it is |
 |---|---|
-| `src/pages/*.tsx` | A page. URL is the file path; `[id].tsx` -> `/:id`, `[...slug].tsx` -> catch-all. |
+| `src/pages/*.tsx` | A page. URL is the file path; `[id].page.tsx` -> `/:id`, `[...slug].page.tsx` -> catch-all. |
 | `src/pages/layout.tsx` | Outer layout — wraps every page. |
 | `src/pages/error.tsx` | Error boundary for the whole subtree. |
 | `src/pages/not-found.tsx` | Fallback rendered when no page matches. |
@@ -398,7 +415,7 @@ The browser-safe rule is **transitive**, and that is where it usually breaks. Th
 Each page can opt into a render strategy via two exports:
 
 ```tsx
-// src/pages/blog/[slug].tsx
+// src/pages/blog/[slug].page.tsx
 export const renderMode = 'isr' as const           // 'static' | 'spa' | 'ssr' | 'isr'
 export const interactive = 'islands' as const      // 'none' | 'islands' | 'full'
 ```
@@ -436,3 +453,117 @@ apps/acme/api/
 - **Don't put two procedure descriptors with the same `name`.** The CLI fails the boot — fix the name collision.
 - **Don't import `.server.ts` files from your web app.** Use the generated client. Importing the server module straight into the browser bundle leaks server-only deps (Postgres driver, secret keys).
 - **Don't move generated files in `.framework/` into the user source tree.** They're disposable; the CLI rewrites them on every boot.
+
+
+
+---
+
+<!-- source: en/intro/file-taxonomy.md -->
+## The web file taxonomy
+
+_The contract suffixes for web code — component, component.ui, hook, types, internal, fixture, tracking — what each one promises and which rule enforces it._
+
+Every suffix on this page is a **contract**, not a label. Something else in the codebase depends on the promise, and `voltro doctor` enforces it. That is the whole admission test, and it is why the list is short:
+
+> Does another file's correctness depend on this file keeping its promise?
+
+If yes, the promise belongs in the name — you cannot see a contract before you break it otherwise. If no, it is a category, and categories are read out of the file.
+
+## The catalogue
+
+| Suffix | Promise | Enforced by |
+|---|---|---|
+| `*.component.tsx` | exactly one component (+ types) | `component/one-per-file`, `component/no-hook-export` |
+| `*.component.ui.tsx` | one component, **reads only** | `ui/no-write`, `ui/orphaned`, `ui/unlinked` |
+| `*.hook.ts` | exactly one `use*` hook (+ types) | `hook/one-per-file`, `hook/no-component-export` |
+| `*.types.ts` | zero runtime exports | `types/runtime-export` |
+| `*.internal.ts` | only its own subtree imports it | `internal/foreign-import` |
+| `*.fixture.ts` | no production path reaches it | `fixture/production-import` |
+| `*.tracking.ts` | analytics happens nowhere else | `tracking/outside-tracking-file` |
+| `*.client.ts` | it and its imports are browser-safe | boot-time import walk, `client/not-browser-safe` |
+| `*.store.ts` | exactly one `defineStore`, no server state | `store/one-per-file`, `store/mirrors-server-state` |
+
+## `*.component.ui.tsx` — reads, never writes
+
+```tsx
+// OrderRow.component.ui.tsx
+import { useCan } from '@voltro/client'
+import { useT } from '@voltro/i18n'
+
+export const OrderRow = (props: { order: Order; onCancel: () => void }) => {
+  const cancelLabel = useT('orders.cancel')
+  const mayCancel = useCan('orders:write')
+  return <tr>{/* … */}</tr>
+}
+```
+
+Reading is allowed on purpose. Threading translations and permissions through props is prop-drilling — it makes every call site worse without making the component more portable.
+
+**Writing** is what breaks the contract. A component that can mutate cannot be rendered ten thousand times in a list, reused across features, or prerendered without first reading what it does — and that property is exactly what its callers rely on. Lift the mutation into the `*.component.tsx` that owns it and pass a handler down.
+
+The same file must also be *reached* from a `*.component.tsx`, another `*.component.ui.tsx`, or a page. An unrendered presentational component is carried, reviewed and refactored forever without ever reaching a user; that is how a design system quietly doubles in size.
+
+## `*.internal.ts` — the feature boundary
+
+```text
+src/features/orders/
+├── index.ts                 # the public surface
+├── orderState.internal.ts   # only this directory may import it
+└── OrderList.component.tsx
+```
+
+`.internal` is the promise that refactoring inside that directory breaks nobody. An import from another feature revokes it — silently, and without a single review comment, which is how a boundary rots.
+
+## `*.types.ts` — provably free to import
+
+No runtime export at all. That is not tidiness: it is what makes importing the module cost nothing in the bundle **and** makes it impossible for it to participate in a runtime import cycle. In a large codebase the second guarantee is the valuable one — an import cycle is only visible when it finally throws.
+
+## `*.tracking.ts` — analytics is confined
+
+```ts
+// checkout.tracking.ts
+import { defineTracking } from '@voltro/client'
+
+export const checkoutTracking = defineTracking('CheckoutButton', {
+  onMount: (props) => ({ event: 'checkout_started', orderId: props.orderId }),
+  onClick: 'checkout.confirmed',
+})
+```
+
+A component then wires it up with `useTracking(checkoutTracking, props, sink)` — it names a spec, it does not author one. Event names, property bags and the decisions about which fields leave the building all live in one place.
+
+`useTracking` itself is a hook, so it is *not* confined — a rule nobody could satisfy is a rule everybody disables. What is confined is `defineTracking`, the declaration.
+
+The payoff is not tidiness. "What do we send to third parties" becomes a file listing instead of an archaeology project — which is the only form in which that question can be answered on demand when someone asks about personal data.
+
+## What deliberately has NO suffix
+
+A generic "one component per file" rule would be worth enforcing everywhere, so tying it to a rename would make it opt-in — less coverage for more cost. The shape rules above fire only on files that *declared* the contract, because declaring it is what makes the promise mean something.
+
+`*.store.ts` was in this section until `defineStore` shipped, and the reason it moved out is the rule itself: **suffixes follow primitives, never the reverse.** While client state was something you brought yourself, a suffix for it would have promised nobody anything. Now `voltro check` reads those files — one store per file, and no store mirroring server state — so the name carries a contract.
+
+There is no `*.form.tsx`, and it is the most-requested one. A form is a component; what makes it a form is the schema it validates against, which is already declared and already typed. A suffix would add a rename without adding a checkable promise — "contains a `<form>`" is not something another file's correctness depends on. If forms ever gain a framework primitive that other code binds to, the rule above will produce the suffix on its own.
+
+## Code you did not write
+
+Our rules are **ours**. A shadcn component arrives via `npx shadcn add`, follows shadcn's conventions (many exports per file, a hook beside the component), and is overwritten by the next `add`. Renaming it would break their convention, be undone on the next generator run, and leave the directory half-migrated the moment one file fails to classify.
+
+So the taxonomy applies to what you write, always — and to nothing else. Two signals mark a directory as not-yours:
+
+1. **`components.json`** at the app root. Its `aliases.ui` names the directory shadcn owns, so a shadcn project needs no configuration at all. Only `aliases.ui` is honoured — `aliases.components` is where your own components live too, and exempting it would silence the taxonomy across most of a codebase.
+2. **A `.voltro-vendored` file** in any directory, whose first line names the source:
+
+```text
+src/vendor/.voltro-vendored     # "copied from acme-design-system v3"
+```
+
+The marker is a file with a reason in it rather than a config list on purpose. A config list is invisible from the directory it exempts and quietly becomes where people put their own code to silence a rule. `voltro doctor` prints every exemption it honoured, so the escape hatch is never silent.
+
+## Migrating
+
+`voltro update` renames what it can decide from the exports alone: one component → `*.component.tsx`, one hook → `*.hook.ts`, no runtime exports → `*.types.ts`. Imports travel with the file.
+
+Two things it will NOT do:
+
+- A file exporting a component **and** a hook is left alone and reported. That is the file the taxonomy most wants split, and no codemod can decide which half keeps the name.
+- `*.component.ui.tsx` is never inferred. "Presentational" is a promise about what a component *may* do; one that merely happens not to write today has not made it.

package/templates/agent-docs/plugins.md

@@ -471,7 +471,8 @@ definePluginRoute({
 })
 ```
 
-`source` must name a table declared `.reactive()`. Omit `source` for a plain
+`source` must name a table that is reactive — every table is, unless it opted
+out with `.nonReactive()`. Omit `source` for a plain
 poll-only plugin query, a mutation, or an action. This is exactly how
 `@voltro/plugin-presence` makes `presence.list` push-driven — the
 `usePresence` roster updates live with no client polling.

package/templates/agent-docs/reference.md

@@ -482,7 +482,7 @@ className={pathname.startsWith('/dashboard') ? 'active' : ''}
 URL params from `[name]` segments. Typed via the generic.
 
 ```tsx
-// src/pages/users/[id].tsx
+// src/pages/users/[id].page.tsx
 import { useParams } from '@voltro/web'
 
 const { id } = useParams<{ id: string }>()
@@ -491,7 +491,7 @@ const { id } = useParams<{ id: string }>()
 For catch-all queries:
 
 ```tsx
-// src/pages/docs/[...slug].tsx
+// src/pages/docs/[...slug].page.tsx
 const { slug } = useParams<{ slug: string }>()
 // /docs/intro/getting-started → slug = "intro/getting-started"
 ```
@@ -499,7 +499,7 @@ const { slug } = useParams<{ slug: string }>()
 For multi-segment dynamic paths:
 
 ```tsx
-// src/pages/orgs/[orgId]/projects/[projectId].tsx
+// src/pages/orgs/[orgId]/projects/[projectId].page.tsx
 const { orgId, projectId } = useParams<{ orgId: string; projectId: string }>()
 ```
 
@@ -604,7 +604,7 @@ Idempotent — multiple calls for the same path fire one loader. The prefetched
 Page's loader output, typed.
 
 ```tsx
-// src/pages/notes/[id].tsx
+// src/pages/notes/[id].page.tsx
 import { useLoaderData } from '@voltro/web'
 
 interface Note {