@voltro/cli 0.13.0 → 0.15.0

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 {

package/templates/agent-docs/routing.md

@@ -11,7 +11,9 @@
 
 _Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework._
 
-The web side of a Voltro app uses **file-based routing**: drop a TSX file under `src/pages/`, the CLI discovers it on every boot + save, and the file becomes a route. No router config, no manual `<Route>` declarations, no codegen step.
+The web side of a Voltro app uses **file-based routing**: drop a `*.page.tsx` file under `src/pages/`, the CLI discovers it on every boot + save, and the file becomes a route. No router config, no manual `<Route>` declarations, no codegen step.
+
+The suffix is what makes a file a route — the directory tree only decides *which URL*. Anything else under `src/pages/` (components, hooks, tests) is ordinary code and gets no URL, so it can live beside the page that uses it.
 
 This section covers everything about how URLs map to React + how Voltro decides when to render, what to ship to the browser, and how to navigate between pages.
 
@@ -23,18 +25,18 @@ src/pages/
 ├── error.tsx               # error boundary
 ├── loading.tsx             # pending UI
 ├── not-found.tsx           # 404 fallback
-├── index.tsx               # /
-├── about.tsx               # /about
+├── index.page.tsx               # /
+├── about.page.tsx               # /about
 ├── (marketing)/            # route group — no URL segment
 │   ├── layout.tsx          # marketing-scoped layout
-│   └── pricing.tsx         # /pricing
+│   └── pricing.page.tsx         # /pricing
 ├── users/
 │   ├── layout.tsx          # users-scoped layout
 │   ├── error.tsx           # users-scoped error boundary
-│   ├── [id].tsx            # /users/:id
-│   └── index.tsx           # /users
+│   ├── [id].page.tsx            # /users/:id
+│   └── index.page.tsx           # /users
 └── docs/
-    └── [...slug].tsx       # /docs/<anything>  (catch-all)
+    └── [...slug].page.tsx       # /docs/<anything>  (catch-all)
 ```
 
 That's the whole router. No `<Route>`, no `<Switch>`, no `useRoutes`.
@@ -50,7 +52,7 @@ That's the whole router. No `<Route>`, no `<Switch>`, no `useRoutes`.
 
 ## Architecture in one paragraph
 
-The framework generates a `.framework/app.tsx` on every boot that imports each `*.tsx` file under `src/pages/` (excluding `node_modules`), wraps them in their layout chains, and produces a `<Router routes={…} />` element. A `mount(App, { group })` call in `.framework/main.tsx` mounts it via `react-dom/client`'s `createRoot` (or `hydrateRoot` for SSR pages). The router watches `window.location` + intercepts `<Link>` clicks for client-side nav.
+The framework generates a `.framework/app.tsx` on every boot that imports each `*.page.tsx` file under `src/pages/` (excluding `node_modules`), wraps them in their layout chains, and produces a `<Router routes={…} />` element. A `mount(App, { group })` call in `.framework/main.tsx` mounts it via `react-dom/client`'s `createRoot` (or `hydrateRoot` for SSR pages). The router watches `window.location` + intercepts `<Link>` clicks for client-side nav.
 
 You don't write any of this. The CLI regenerates it on every save in dev; the build pipeline freezes it for production.
 
@@ -123,7 +125,7 @@ A **page** is any `*.tsx` file under `src/pages/` that's not a special file (`la
 ## A static page
 
 ```tsx
-// src/pages/about.tsx → /about
+// src/pages/about.page.tsx → /about
 import type { ReactNode } from 'react'
 
 export default function About(): ReactNode {
@@ -143,9 +145,9 @@ That's it. Save the file, the CLI's discovery sees it on next save, the page is
 `index.tsx` maps to the directory's URL:
 
 ```text
-src/pages/index.tsx         → /
-src/pages/users/index.tsx   → /users
-src/pages/admin/index.tsx   → /admin
+src/pages/index.page.tsx         → /
+src/pages/users/index.page.tsx   → /users
+src/pages/admin/index.page.tsx   → /admin
 ```
 
 ## Dynamic segments
@@ -153,7 +155,7 @@ src/pages/admin/index.tsx   → /admin
 Brackets in the filename are dynamic. The captured value comes through `useParams<T>()`:
 
 ```tsx
-// src/pages/users/[id].tsx → /users/:id
+// src/pages/users/[id].page.tsx → /users/:id
 import { useParams } from '@voltro/web'
 
 export default function User() {
@@ -165,7 +167,7 @@ export default function User() {
 Multiple dynamic segments in one path:
 
 ```text
-src/pages/orgs/[orgId]/projects/[projectId].tsx
+src/pages/orgs/[orgId]/projects/[projectId].page.tsx
 // → /orgs/:orgId/projects/:projectId
 
 const { orgId, projectId } = useParams<{ orgId: string; projectId: string }>()
@@ -176,7 +178,7 @@ const { orgId, projectId } = useParams<{ orgId: string; projectId: string }>()
 `[...name]` captures one OR more URL segments as a single param value (joined by `/`):
 
 ```tsx
-// src/pages/docs/[...slug].tsx → /docs/<anything>
+// src/pages/docs/[...slug].page.tsx → /docs/<anything>
 const { slug } = useParams<{ slug: string }>()
 // /docs/intro/getting-started → slug = "intro/getting-started"
 ```
@@ -184,7 +186,7 @@ const { slug } = useParams<{ slug: string }>()
 **Optional** catch-all (matches the base URL too):
 
 ```tsx
-// src/pages/docs/[[...slug]].tsx
+// src/pages/docs/[[...slug]].page.tsx
 // /docs       → slug = ""
 // /docs/foo   → slug = "foo"
 // /docs/foo/bar → slug = "foo/bar"
@@ -199,10 +201,10 @@ When multiple files could match (static, dynamic, catch-all), priority is:
 3. Optional catch-all (`[[...slug]]`) wins over required catch-all (`[...slug]`) — the optional form scores as more specific, so it matches first.
 
 ```text
-src/pages/users/index.tsx     # /users → wins for /users
-src/pages/users/[id].tsx       # /users/:id → wins for /users/42
-src/pages/users/new.tsx        # /users/new → wins (static beats dynamic)
-src/pages/[...rest].tsx        # everything else
+src/pages/users/index.page.tsx     # /users → wins for /users
+src/pages/users/[id].page.tsx       # /users/:id → wins for /users/42
+src/pages/users/new.page.tsx        # /users/new → wins (static beats dynamic)
+src/pages/[...rest].page.tsx        # everything else
 ```
 
 ## Query strings
@@ -238,20 +240,23 @@ export default function SearchPage() {
 
 Parse the query string explicitly via `useServerRequest()` on the server and `window.location.search` on the client, as shown above.
 
-## Private files
+## Co-locating components, hooks and tests
 
-Files starting with `_` are skipped by discovery — they're helpers next to pages:
+Only `*.page.tsx` is a route. Everything else under `src/pages/` is ordinary code and may sit next to the page that uses it:
 
 ```text
 src/pages/
-├── _components/
-│   └── UserCard.tsx          # NOT a route — import from siblings
 ├── users/
-│   ├── _helpers.ts           # NOT a route
-│   └── [id].tsx              # → /users/:id
+│   ├── index.page.tsx        # → /users
+│   ├── index.page.test.tsx   # its test
+│   ├── [id].page.tsx         # → /users/:id
+│   ├── UserCard.tsx          # a component — no URL
+│   └── useFilters.ts         # a hook — no URL
 ```
 
-You can also use the colocation pattern: keep page-specific components in a directory named with `_` prefix.
+No naming trick is needed to keep something out of the router: the absence of the suffix already does it. A `_`-prefixed directory has **no special meaning** — it is neither required nor recognised.
+
+> Before this convention, every `.tsx` under `src/pages/` became a route, so a co-located component silently got a URL. That route rendered nothing and nobody visited it in dev; the failure surfaced at the first production build. If you are upgrading, `voltro update` renames your pages for you.
 
 ## Trailing slashes
 
@@ -314,11 +319,11 @@ Conventions:
 ```text
 src/pages/
 ├── layout.tsx                # outer (every page)
-├── about.tsx                 # /about → wrapped in outer layout
+├── about.page.tsx                 # /about → wrapped in outer layout
 └── dashboard/
     ├── layout.tsx            # nested (only /dashboard/*)
-    ├── index.tsx             # /dashboard
-    └── settings.tsx          # /dashboard/settings
+    ├── index.page.tsx             # /dashboard
+    └── settings.page.tsx          # /dashboard/settings
 ```
 
 For `/dashboard/settings`, the React tree is:
@@ -341,13 +346,13 @@ A directory in `(parentheses)` does NOT contribute a URL segment, but its layout
 src/pages/
 ├── (marketing)/
 │   ├── layout.tsx            # marketing-scoped chrome
-│   ├── index.tsx             # /
-│   ├── pricing.tsx           # /pricing
-│   └── about.tsx             # /about
+│   ├── index.page.tsx             # /
+│   ├── pricing.page.tsx           # /pricing
+│   └── about.page.tsx             # /about
 └── (app)/
     ├── layout.tsx            # authenticated app chrome
-    ├── dashboard.tsx         # /dashboard
-    └── settings.tsx          # /settings
+    ├── dashboard.page.tsx         # /dashboard
+    └── settings.page.tsx          # /settings
 ```
 
 Marketing pages get one layout; authenticated app pages get another; the URLs stay flat.
@@ -491,7 +496,7 @@ Those four are the **complete** set. An unrecognised value is a hard error namin
 ## static (SSG)
 
 ```tsx
-// src/pages/about.tsx
+// src/pages/about.page.tsx
 export const renderMode = 'static' as const
 ```
 
@@ -504,7 +509,7 @@ At `voltro build`:
 For dynamic patterns, export `getStaticPaths` to enumerate every URL to pre-render:
 
 ```tsx
-// src/pages/blog/[slug].tsx
+// src/pages/blog/[slug].page.tsx
 export const renderMode = 'static' as const
 
 export const getStaticPaths = async () => [
@@ -729,7 +734,7 @@ Both are static module exports — the framework discovers them, the build pipel
 ## A loader
 
 ```tsx
-// src/pages/notes/[id].tsx
+// src/pages/notes/[id].page.tsx
 import { useLoaderData } from '@voltro/web'
 
 interface Note {
@@ -839,7 +844,7 @@ splits the loader's result into data that blocks the shell and data that
 soon as the promise settles.
 
 ```tsx
-// src/pages/dashboard.tsx
+// src/pages/dashboard.page.tsx
 import { Await, defer, useLoaderData } from '@voltro/web'
 
 export const renderMode = 'ssr' as const   // required — see below
@@ -959,7 +964,7 @@ Use `signal` for any fetch that could outlive the request — pass it to `fetch(
 Instead of hand-rolling a `fetch(INTERNAL_API/...)`, a server-side loader can call the backend rpc directly through `ctx.query` — the same query tags the client subscribes to, resolved to their initial snapshot:
 
 ```tsx
-// src/pages/notes/[id].tsx
+// src/pages/notes/[id].page.tsx
 import { useSubscription } from '@voltro/client'
 import { useLoaderData, type PageMeta } from '@voltro/web'
 
@@ -1131,7 +1136,7 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
 ### Authenticated dashboard with cookie-driven loader
 
 ```tsx
-// src/pages/dashboard/index.tsx
+// src/pages/dashboard/index.page.tsx
 import { useLoaderData } from '@voltro/web'
 
 export const renderMode = 'ssr' as const
@@ -1157,7 +1162,7 @@ export default function Dashboard() {
 `getStaticPaths` has no framework store — it reads its own content source (a CMS client, the filesystem, an API). The loader runs server-side and fetches via `query` (the backend rpc, resolved to its first snapshot):
 
 ```tsx
-// src/pages/blog/[slug].tsx
+// src/pages/blog/[slug].page.tsx
 import { listPostSlugs, type Post } from '../../content/posts'
 
 export const renderMode = 'static' as const
@@ -1558,7 +1563,7 @@ export default island(LikeButton, { name: 'LikeButton', hydrate: 'visible' })
 Use it in a page:
 
 ```tsx
-// src/pages/blog/[slug].tsx
+// src/pages/blog/[slug].page.tsx
 import LikeButton from '../../components/LikeButton.island'
 
 export const renderMode = 'static' as const

package/templates/agent-docs/schema-driven-ui.md

@@ -1017,7 +1017,8 @@ be on. Rather than repeat that check in every `useMutation` call site, each api'
 runtime carries an error bus; this hook subscribes to it with React lifecycle.
 
 ```tsx
-import { useOnRpcError, errorTag } from '@voltro/client'
+import { useOnRpcError } from '@voltro/client'
+import { errorTag } from '@voltro/protocol'
 
 useOnRpcError('app', useCallback((e) => {
   if (errorTag(e.error) === 'Unauthenticated') redirectToSignIn()
@@ -1093,16 +1094,26 @@ readable in a single place.
 ```tsx
 import { defineTracking, useTracking } from '@voltro/client'
 
-const spec = defineTracking('CheckoutButton', {
+interface CheckoutButtonProps {
+  readonly plan: 'free' | 'pro'
+  readonly onClick: () => void
+}
+
+const spec = defineTracking<CheckoutButtonProps>('CheckoutButton', {
   onMount: 'checkout.viewed',
   onClick: (props) => ({ event: 'checkout.started', plan: props.plan }),
 })
 
-const CheckoutButton = (props) => {
+const CheckoutButton = (props: CheckoutButtonProps) => {
   const tracked = useTracking(spec, props, sink)
   return <button {...tracked}>Checkout</button>
 }
 ```
+**Name the props.** The type parameter is what lets a payload builder read
+`props.plan` instead of indexing into `unknown` and casting — and a cast is the
+last thing that belongs in the one file that states what leaves the browser. It
+defaults to an untyped bag, so a loose catalogue still compiles; `useTracking`
+then returns the props type, which is what makes `{...tracked}` typecheck at all.
 
 `useTracking(spec, props, sink)` returns a **copy of your props** with every
 callback the map names wrapped, so invoking `onClick` fires its event and then

package/templates/agent-docs/templates/apibackends.md

@@ -137,7 +137,6 @@ export const notes = table('notes', {
   id: id({ prefix: 'note' }), title: text(), body: text(), done: boolean().default(false),
 })
   .with(tenant())   // pulls audit() transitively → tenantId + createdAt/updatedAt/createdBy/updatedBy
-  .reactive()       // subscriptions get a fresh snapshot/delta on every write to notes
 
 export type Note = InferRow<typeof notes>
 export const database = databaseHandle({ actors, tenants, notes })
@@ -588,13 +587,12 @@ export const orders = table('orders', {
   amountCents:  integer(),
 })
   .with(tenant())   // pulls audit() transitively → tenantId + createdAt/updatedAt/createdBy/updatedBy
-  .reactive()       // subscriber + live subscriptions wake on every write to orders
 
 export type Order = InferRow<typeof orders>
 export const database = databaseHandle({ actors, tenants, orders })
 ```
 
-`tenant()` makes the table tenant-scoped: the runtime AND-merges `eq('tenantId', subject.tenantId)` into every subscription so cross-tenant reads can't leak. `.reactive()` opts the table into the matcher engine so the `orderChanges` subscriber and any live query fire on every mutation write. See [multi-tenancy](/docs/multi-tenancy/overview).
+`tenant()` makes the table tenant-scoped: the runtime AND-merges `eq('tenantId', subject.tenantId)` into every subscription so cross-tenant reads can't leak. Every table is in the matcher engine by default, so the `orderChanges` subscriber and any live query fire on every mutation write. See [multi-tenancy](/docs/multi-tenancy/overview).
 
 ## Place — mutation that emits a domain event
 
@@ -1292,7 +1290,6 @@ export const docs = table('docs', {
     }),
   )
   // Opt into the matcher engine so subscriptions over `docs` re-fire on write.
-  .reactive()
 
 export type Doc = InferRow<typeof docs>
 
@@ -1459,7 +1456,6 @@ export const authors = table('authors', {
 })
   // tenant() pulls audit() transitively → tenantId + createdAt/updatedAt/createdBy/updatedBy
   .with(tenant())
-  .reactive()
 ```
 
 ```ts
@@ -1588,7 +1584,6 @@ export const books = table('books', {
     weights: { title: 'A', summary: 'B' },
   })
   .with(tenant())
-  .reactive()
 ```
 
 The query executor compiles the FTS predicate via `.matching('bookSearch', q)` — resolving the index's covered columns + config from the declaration on the table. No tenant filter is added by hand; `books` carries `tenant()`, so the runtime AND-merges `eq('tenantId', subject.tenantId)`:
@@ -2935,7 +2930,6 @@ export const users = table('users', {
   // adds deactivatedAt + deactivatedBy (→ actors); pulls audit() transitively.
   // NO defaultWhere — a deactivated user still shows up in queries.
   .with(deactivation())
-  .reactive()
 ```
 
 Deactivate with a normal update — `deactivatedAt` is just a column:
@@ -3122,7 +3116,6 @@ export const syncedEvents = table('synced_events', {
   sequence:   integer(),
 })
   .with(tenant())   // tenantId + audit columns, auto-stamped from the subject
-  .reactive()       // events.list subscription wakes on every insert
 
 export type SyncedEvent = InferRow<typeof syncedEvents>
 export const database = databaseHandle({ actors, tenants, syncedEvents })