@voltro/cli 0.13.0 → 0.14.0

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

@@ -1093,16 +1093,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 })

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

@@ -39,7 +39,7 @@ apps/acme/web/                          # dir named by the app, not the template
 
 ## The page
 
-`src/pages/index.tsx` is plain JSX with the two static-render exports:
+`src/pages/index.page.tsx` is plain JSX with the two static-render exports:
 
 ```tsx
 export const renderMode  = 'static' as const   // pre-render at build time
@@ -59,7 +59,7 @@ export default function Index() {
       </section>
       <section>
         <h2>Ready to start?</h2>
-        <p>Edit <code>src/pages/index.tsx</code> to make it yours.</p>
+        <p>Edit <code>src/pages/index.page.tsx</code> to make it yours.</p>
       </section>
     </main>
   )
@@ -80,7 +80,7 @@ export default island(SignupForm, { name: 'SignupForm', hydrate: 'visible' })
 ```
 
 ```tsx
-// src/pages/index.tsx
+// src/pages/index.page.tsx
 export const interactive = 'islands' as const   // was 'none'
 import SignupForm from '../components/SignupForm.island'
 // … render <SignupForm /> somewhere in the page …
@@ -185,7 +185,7 @@ If your final product is going to be a:
 
 _A documentation site with a catch-all docs router and build-time static pre-rendering of every page via getStaticPaths._
 
-A documentation-site starter. `src/pages/docs/[...slug].tsx` is a catch-all router; `getStaticPaths` enumerates every doc URL at build time so `voltro build` pre-renders them all into a static site you can deploy anywhere. Template id: **`frontend-docs`**.
+A documentation-site starter. `src/pages/docs/[...slug].page.tsx` is a catch-all router; `getStaticPaths` enumerates every doc URL at build time so `voltro build` pre-renders them all into a static site you can deploy anywhere. Template id: **`frontend-docs`**.
 
 The starter ships a tiny in-file `DOCS` array as stub content. Replace it with a real loader (a markdown reader, a CMS query, a database fetch) — the page component's contract stays the same.
 
@@ -215,7 +215,7 @@ apps/acme/docs/                         # dir named by the app, not the template
 
 ## The catch-all renderer
 
-`src/pages/docs/[...slug].tsx` is the whole engine. It declares:
+`src/pages/docs/[...slug].page.tsx` is the whole engine. It declares:
 
 ```tsx
 export const renderMode  = 'static' as const   // pre-render at build
@@ -418,7 +418,7 @@ No rpc client, no loader, no `apis:` entry, no `@voltro/ui-shadcn` dependency. T
 The page exports `renderMode = 'spa'`, which tells `voltro build` not to pre-render it: the client renders it on load. Use this when the whole page is interactive AND its state lives in the browser — an SSR'd first paint would just be discarded on hydration, so rendering it on the server buys nothing.
 
 ```tsx
-// src/pages/index.tsx — a pure client-side SPA (a bill splitter)
+// src/pages/index.page.tsx — a pure client-side SPA (a bill splitter)
 import type { ReactNode } from 'react'
 import { useEffect, useState } from 'react'
 
@@ -603,7 +603,7 @@ The full reference for these modes lives in the [render modes guide](/docs/routi
 `index.tsx` exports `renderMode = 'ssr'`. Its loader runs SERVER-SIDE on EVERY request under `voltro start` — the timestamp and nonce change on each refresh, and the loader can read the incoming request to personalise the HTML before it's sent. There is no caching: the response carries `x-voltro-rendered-by: ssr`.
 
 ```tsx
-// src/pages/index.tsx
+// src/pages/index.page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, useServerRequest, type LoaderFn, type PageMeta } from '@voltro/web'
 
@@ -646,7 +646,7 @@ Use SSR for anything that varies per request: a logged-in dashboard, a page that
 `feed.tsx` takes the SAME render path as SSR, but `voltro start` CACHES the HTML and serves the cached copy to every request within the `revalidate` window. After the window expires the next request re-renders and replaces the cache — cache hits return in well under a millisecond. `tenantAware: true` folds the `x-tenant` request header into the cache key, so tenant A's render is never served to tenant B:
 
 ```tsx
-// src/pages/feed.tsx
+// src/pages/feed.page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
 
@@ -685,7 +685,7 @@ The loader's `headers` is populated server-side (lowercased keys) — that's how
 `feed-swr.tsx` is the same ISR page plus a `staleWhileRevalidate` window. When `revalidate` expires, instead of blocking the next visitor on a fresh render, the cache serves the STALE HTML immediately AND kicks off a background re-render. The visitor never waits; the cache catches up out-of-band. Beyond `revalidate + staleWhileRevalidate` the next request blocks on a fresh render, like a cold MISS:
 
 ```tsx
-// src/pages/feed-swr.tsx
+// src/pages/feed-swr.page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
 
@@ -878,10 +878,10 @@ export const posts: ReadonlyArray<Post> = [
 
 ## SSG dynamic routes — `getStaticPaths` + `loader` + per-post `meta`
 
-A dynamic route like `src/pages/blog/[slug].tsx` matches infinitely many URLs. To pre-render it statically the build needs to know WHICH slugs exist — that is what `getStaticPaths` answers, by mapping over the content source. For each enumerated `params` the build runs the `loader` (server-side, at build time) and renders one HTML file. The `meta` export is a FUNCTION of the loader data, so each post gets its own correct `<title>` / `<description>` baked into the HTML — exactly what you want for SEO and social cards.
+A dynamic route like `src/pages/blog/[slug].page.tsx` matches infinitely many URLs. To pre-render it statically the build needs to know WHICH slugs exist — that is what `getStaticPaths` answers, by mapping over the content source. For each enumerated `params` the build runs the `loader` (server-side, at build time) and renders one HTML file. The `meta` export is a FUNCTION of the loader data, so each post gets its own correct `<title>` / `<description>` baked into the HTML — exactly what you want for SEO and social cards.
 
 ```tsx
-// src/pages/blog/[slug].tsx
+// src/pages/blog/[slug].page.tsx
 import type { ReactNode } from 'react'
 import { useLoaderData, notFound, type LoaderFn, type PageMeta } from '@voltro/web'
 import { posts, type Post } from '../../content/posts'
@@ -972,7 +972,7 @@ export default island(ReadingProgress, { name: 'ReadingProgress', hydrate: 'load
 The index at `/` is pure content: a list of posts with no interactivity. It declares `interactive: 'none'`, which makes the framework strip EVERY `<script>` it would otherwise emit — the HTML ships with no JS bundle at all. It reads the same content source the `[slug]` page + `getStaticPaths` use:
 
 ```tsx
-// src/pages/index.tsx
+// src/pages/index.page.tsx
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
 import { posts } from '../content/posts'
@@ -1106,10 +1106,10 @@ The serverless function lives next to the web app but is a separate deploy artif
 
 ## The static page + the island form
 
-`src/pages/index.tsx` is `renderMode: 'static'` (pre-rendered, servable from a CDN) and `interactive: 'islands'` — so only the `<ContactForm>` island hydrates; the headline + copy ship as inert HTML with no React lifecycle:
+`src/pages/index.page.tsx` is `renderMode: 'static'` (pre-rendered, servable from a CDN) and `interactive: 'islands'` — so only the `<ContactForm>` island hydrates; the headline + copy ship as inert HTML with no React lifecycle:
 
 ```tsx
-// src/pages/index.tsx
+// src/pages/index.page.tsx
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
 import ContactForm from '../components/ContactForm.island'
@@ -1358,7 +1358,7 @@ apps/demo/web/
 ├── README.md
 └── src/pages/
     ├── layout.tsx                 # root shell (header + <main>)
-    └── index.tsx                  # the reactive page — useSubscription + useMutation
+    └── index.page.tsx                  # the reactive page — useSubscription + useMutation
 ```
 
 ## The `apis` wiring
@@ -1390,7 +1390,7 @@ The `package` resolves the api workspace package; its port is auto-discovered fr
 ## The reactive loop
 
 ```tsx
-// src/pages/index.tsx
+// src/pages/index.page.tsx
 import { useMutation, useSubscription } from '@voltro/client'
 
 const TENANT = 'acme'
@@ -1418,7 +1418,7 @@ The subscription builder also exposes `revision`, `emittedAt`, `error`, and `pen
 
 ## Pairing with a different api
 
-This page is wired to api-backend's `notes` domain. To point it at your own api, change `apis.app.package` in `app.config.ts`, then swap the rpc tags + the row type in `src/pages/index.tsx` to match your descriptors. The hook shapes are identical for any api.
+This page is wired to api-backend's `notes` domain. To point it at your own api, change `apis.app.package` in `app.config.ts`, then swap the rpc tags + the row type in `src/pages/index.page.tsx` to match your descriptors. The hook shapes are identical for any api.
 
 ## When to use
 
@@ -1533,7 +1533,7 @@ export const withLocalePrefix = (path: string, locale: string): string =>
 Each page has a one-line **mirror** under `src/pages/[locale]/`. The mirror re-exports the bare page verbatim (the component reads its locale from the URL via the layout's provider) and uses `getStaticPaths` to enumerate the *non-default* locales — which is what tells `voltro build` to emit the `/de/...` HTML. Without the mirror, only the default-locale URL is built.
 
 ```tsx
-// src/pages/[locale]/index.tsx — the entire file
+// src/pages/[locale]/index.page.tsx — the entire file
 import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../lib/locale'
 
 export { default } from '../index'
@@ -1550,7 +1550,7 @@ export const getStaticPaths = async (): Promise<Array<{ params: { locale: string
 The body of each page is localised automatically (the SSG pipeline wraps every variant in the right catalog's provider). The document head is NOT — unless you export `meta` as a **function of `{ locale }`**. The framework drives `locale` from `params.locale` on the `[locale]` route (and `defaultLocale` on the bare path), so each variant bakes the right `<title>` / `<meta description>` into its HTML — exactly what you want for SEO and social cards. A plain `meta` object would leave the head English on `/de`.
 
 ```tsx
-// src/pages/index.tsx
+// src/pages/index.page.tsx
 import { T, useT, useLocale } from '@voltro/i18n'
 import { getCatalog } from '../lib/locale'
 
@@ -1662,7 +1662,7 @@ The `[locale]` mirrors pick it up automatically — `getStaticPaths` reads `SUPP
 
 ## Anti-patterns
 
-- **Forgetting the `[locale]` mirror for a new page.** Create `src/pages/foo.tsx` AND a one-line mirror `src/pages/[locale]/foo.tsx`. Without the mirror, only the default-locale URL is emitted — `/de/foo` 404s.
+- **Forgetting the `[locale]` mirror for a new page.** Create `src/pages/foo.page.tsx` AND a one-line mirror `src/pages/[locale]/foo.page.tsx`. Without the mirror, only the default-locale URL is emitted — `/de/foo` 404s.
 - **Exporting `meta` as a plain object.** The body localises, but the `<title>` / `<meta description>` stay English on `/de`. Export `meta` as a function of `{ locale }` and read the catalog via `getCatalog(locale)`.
 - **Skipping `defineLocale<typeof en>()` for a non-base catalog.** Plain `defineCatalog(...)` compiles but loses the parity check — the one feature that stops translations drifting. Always run non-base locales through `defineLocale<typeof en>()`.
 - **Angle brackets in catalog strings.** react-intl's ICU parser treats `<tag>` as a rich-text element and fails (`FORMAT_ERROR`) if there's no matching close tag. Write "page titles", not "`<title>` tags", in a message.
@@ -1759,7 +1759,7 @@ export default function DashboardLayout({ children }) {
 The gate must run **per request** — it reads the request's cookie and may redirect. A `static` page is pre-rendered once at build time with no per-visitor render, so it can't redirect per-visitor; in fact `voltro build` **rejects** a `RedirectError` thrown during static pre-render. So the authed pages declare `renderMode: 'ssr'`:
 
 ```tsx
-// src/pages/dashboard/index.tsx
+// src/pages/dashboard/index.page.tsx
 export const renderMode = 'ssr' as const
 export const meta = { title: 'Overview' }
 export default function Overview() { /* … */ }
@@ -1884,7 +1884,7 @@ export default {
 `query` is present ONLY server-side (`ssr` / `isr`). It invokes the api's rpc directly over `POST /rpc`, **forwarding the request's session cookie** so the same Subject + tenant resolve as the WebSocket path. A streaming query is drained to its FIRST snapshot — here, the current notes for this tenant. `meta` reads the result, so the `<title>` reflects real data in the server-rendered HTML:
 
 ```tsx
-// src/pages/index.tsx
+// src/pages/index.page.tsx
 import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
 import { useSubscription } from '@voltro/client'
 
@@ -1994,7 +1994,7 @@ const entities = manifest ? deriveEntityAdmins(manifest) : []
 ## Per-entity CRUD
 
 ```tsx
-// src/pages/admin/[entity].tsx (abridged)
+// src/pages/admin/[entity].page.tsx (abridged)
 const canCreate = useCan(spec.createScope)         // <table>:create
 {spec.createTag && canCreate ? (
   <AutoForm api="app" mutation={spec.createTag} submitLabel={`Add ${spec.table}`} />
@@ -2041,7 +2041,7 @@ apps/acme/web/
 
 ## Make it yours
 
-Everything under `src/pages/admin/` is yours. Swap the cookie gate (`lib/auth.ts`) + demo scopes (`lib/admin.ts`) for real auth; replace the generic `[entity].tsx` with a hand-built page for any entity that needs more than CRUD.
+Everything under `src/pages/admin/` is yours. Swap the cookie gate (`lib/auth.ts`) + demo scopes (`lib/admin.ts`) for real auth; replace the generic `[entity].page.tsx` with a hand-built page for any entity that needs more than CRUD.
 
 ## When to use frontend-admin vs. the other web templates
 

package/templates/agent-docs/testing.md

@@ -23,7 +23,7 @@ Everything in it is in-memory and synchronous-friendly — no docker, no running
 
 | Export | Use |
 |---|---|
-| `makeTestContext(options?)` | The request `ctx` a handler/tool sees at runtime — subject-scoped `ctx.store`, `clock`, `email`, optional `ai`. → [Unit testing](/docs/testing/unit-testing) |
+| `makeTestContext(options?)` | The request `ctx` a handler/tool sees at runtime — subject-scoped `ctx.store`, `clock`, `email`, `webhooks`, optional `ai`. → [Unit testing](/docs/testing/unit-testing) |
 | `mockStore(seed)` | Seed rows: `makeTestContext({ store: mockStore({ todos: [...] }) })`. |
 | `MockClock` / `MockEmail` / `MockLLM` | Deterministic clock, captured email, queued LLM responses. |
 | `makeVoltroTestClient(config)` | The frontend harness — render a component against mocked `useSubscription` / `useMutation`, from the `@voltro/testing/client` subpath. → [Component testing](/docs/testing/component-testing) |
@@ -51,6 +51,8 @@ voltro e2e     # boot api + web siblings, run tests, tear down
 
 `voltro test` is a thin wrapper over vitest — it runs the app's test files with the framework's config. Everything `@voltro/testing` exports is plain TypeScript you import inside those files; there's no special test runner.
 
+`e2e/` is left alone: those specs belong to `voltro e2e`, which drives them through tsx against a booted api + web. They define no vitest suite, so collecting them would report "No test suite found" — a red run for an app laid out exactly as the framework asks. Pass your own `--exclude` and it wins outright.
+
 ## What NOT to do
 
 - **Don't spin up Postgres for a handler test.** `makeTestContext`'s in-memory store enforces the same mixin behaviour — tenant scoping, soft-delete, audit — so a unit test catches the same class of bug far faster. Save a real database for [dialect parity](/docs/testing/dialect-parity) and e2e.
@@ -480,6 +482,19 @@ ctx.email.lastTo('a@b.com')    // the most recent email to that address, or unde
 ctx.email.clear()              // reset between cases
 ```
 
+### `ctx.webhooks` — `MockWebhooks`
+
+Records outgoing webhook emissions. Every context derived from this one — the transaction context `invoke` builds for a mutation, a `withSubject` / `withTenant` block — shares the same recorder, so what you assert on IS what the handler emitted.
+
+```ts
+ctx.webhooks.emitted                     // EmittedWebhook[] — every emit, in order
+ctx.webhooks.last('todo.created')        // the most recent emission of that event
+ctx.webhooks.payloadsFor('todo.created') // just the payloads, oldest first
+ctx.webhooks.clear()                     // reset between cases
+```
+
+It records; it does not deliver, sign, or consult subscriptions. `emit` reports `{ delivered: 0 }` because no targets are subscribed, and saying so is more honest than a number a test might assert against.
+
 ### `ctx.llm` — `MockLLM`
 
 A queue of canned model responses plus a record of every call. Each `MockResponse` is one of `{ text }`, `{ toolCall: { name, input } }`, or `{ error: { code, message? } }`.

package/templates/agent-docs/whats-new.md

@@ -76,6 +76,22 @@ BREAKING entries name a codemod; run `voltro update` to apply it.
   A dev container running as root with the host workspace bind-mounted wrote `apps/api/.env.local` as `root:root 0600` INTO THE SHARED WORKSPACE. On the host, everything that loads env then died with EACCES — vitest, `voltro doctor`, the editor — and the developer could not even read the file, while the next container boot recreated it. Container-with-bind-mount is the ordinary dev shape, not an edge case.
 
   `0600` stays (the file holds a real signing key), because loosening it to `0644` would make that key readable by every account on the machine for the far more common single-user case. Ownership was the wrong variable, so that is the one corrected: the mint chowns the file to whoever owns the directory, which root can do — exactly the case that needs it — and reports loudly when it cannot. A plain EACCES while loading an env file now names the owning uid, the mode and the current uid, because that pair IS the diagnosis and none of it appears in node's message.
+- **@voltro/cli** — Framework-generated output is handed to the workspace's owner, not left owned by whoever the process happens to be.
+
+  The previous release fixed this for the minted `.env.local`. The report that followed showed the scope was wrong: it is EVERY directory the framework generates. A dev pod running as root with the host monorepo bind-mounted leaves `.framework/` and `app.graph.observed.*` as `root:root` inside the developer's own tree, and on the host:
+
+  ```
+  voltro build . → EACCES: permission denied, open '…/apps/display/.framework/index.html'
+  ```
+
+  That is the harder failure. `.env.local` broke env loading; this breaks the production build of every web app outright, with no workaround short of chown-ing by hand after each pod boot. One team could only verify their frontends through test suites and live requests against the running pods.
+
+  `voltro dev` and `voltro build` now hand their generated output — `.framework`, `.env.local`, every `*.generated.*` — to the uid that owns the app root, and say so loudly when they cannot. A no-op on every ordinary run and in any container started with `--user <uid>:<gid>`: when the process already owns the root it returns without touching the tree. Only generated state is claimed; the framework never chowns a file a human wrote.
+- **@voltro/cli** — The observed app-graph no longer restarts the dev server.
+
+  `app.graph.observed.json` was written into the watched app root every 10 seconds, and the supervisor's watcher fired on each write. A downstream pod measured two restarts before every boot over 2000 log lines — the rule, not an outlier — and paid a ~46 s boot three times per save.
+
+  The watcher excludes `<name>.generated.<ext>`, a substring rule chosen precisely because a per-extension whitelist had already let a generated file slip twice. This file slipped it a third time by not carrying the segment at all. It is now `app.graph.observed.generated.json`, which matches the convention instead of adding a fourth special case to a list that has drifted three times; a stale un-suffixed file from an older dev server is removed on boot so it cannot keep triggering restarts.
 - **@voltro/cli** — Four tooling fixes, all from downstream reports:
 
   - **`voltro check --offline` crashed on any app that declares a workflow.** It built workflow entries as `{ name }` behind an `as never` while `InspectWorkflowEntry` is keyed by `tag`, so the manifest's sort read `undefined` and threw — surfacing as "could not assemble the graph from source" rather than the type error underneath. The cast is what let the two shapes disagree. - **`voltro check --offline` reported plugin tables as `dangling-source`.** It collected only the app's own `*.entity.ts` tables, so a query reading `_voltro_storage_refs` was an `error` — which sets the exit code, failing the CI gate the offline mode exists for. It now uses the same `assembleFrameworkTables` the migrator does. - **`voltro test` now derives `resolve.alias` from the app's tsconfig `paths`.** An app mapping `@/* → ./src/*` could not test any module importing through it (`Cannot find package '@/locales/en'`), and the workaround was a local `vitest.config.ts` restating what tsconfig already said. - **The `raw-fetch` doctor rule follows the import graph.** Keyed on filename conventions it caught 9 of 39 outbound calls on the reporting app; the other 30 were in `lib/*.ts` helpers only server code imports. A file reachable from a server-convention file and from nothing else is server code; one a page also imports is not, and stays unflagged.

package/templates/apps/api-ai/database/schema.ts

@@ -59,8 +59,6 @@ export const docs = table('docs', {
       dimensions: 1536,
     }),
   )
-  // Opt into the matcher engine so subscriptions over `docs` re-fire on write.
-  .reactive()
 
 export type Doc = InferRow<typeof docs>