@voltro/cli 0.16.0 → 0.18.0

package/templates/agent-docs/routing.md

@@ -11,7 +11,7 @@
 
 _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 `*.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 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.
 
@@ -25,18 +25,18 @@ src/pages/
 ├── error.tsx               # error boundary
 ├── loading.tsx             # pending UI
 ├── not-found.tsx           # 404 fallback
-├── index.page.tsx               # /
-├── about.page.tsx               # /about
+├── page.tsx               # /
+├── about/page.tsx               # /about
 ├── (marketing)/            # route group — no URL segment
 │   ├── layout.tsx          # marketing-scoped layout
-│   └── pricing.page.tsx         # /pricing
+│   └── pricing/page.tsx         # /pricing
 ├── users/
 │   ├── layout.tsx          # users-scoped layout
 │   ├── error.tsx           # users-scoped error boundary
-│   ├── [id].page.tsx            # /users/:id
-│   └── index.page.tsx           # /users
+│   ├── [id]/page.tsx            # /users/:id
+│   └── page.tsx           # /users
 └── docs/
-    └── [...slug].page.tsx       # /docs/<anything>  (catch-all)
+    └── [...slug]/page.tsx       # /docs/<anything>  (catch-all)
 ```
 
 That's the whole router. No `<Route>`, no `<Switch>`, no `useRoutes`.
@@ -52,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 `*.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.
+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.
 
@@ -125,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.page.tsx → /about
+// src/pages/about/page.tsx → /about
 import type { ReactNode } from 'react'
 
 export default function About(): ReactNode {
@@ -145,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.page.tsx         → /
-src/pages/users/index.page.tsx   → /users
-src/pages/admin/index.page.tsx   → /admin
+src/pages/page.tsx         → /
+src/pages/users/page.tsx   → /users
+src/pages/admin/page.tsx   → /admin
 ```
 
 ## Dynamic segments
@@ -155,7 +155,7 @@ src/pages/admin/index.page.tsx   → /admin
 Brackets in the filename are dynamic. The captured value comes through `useParams<T>()`:
 
 ```tsx
-// src/pages/users/[id].page.tsx → /users/:id
+// src/pages/users/[id]/page.tsx → /users/:id
 import { useParams } from '@voltro/web'
 
 export default function User() {
@@ -167,7 +167,7 @@ export default function User() {
 Multiple dynamic segments in one path:
 
 ```text
-src/pages/orgs/[orgId]/projects/[projectId].page.tsx
+src/pages/orgs/[orgId]/projects/[projectId]/page.tsx
 // → /orgs/:orgId/projects/:projectId
 
 const { orgId, projectId } = useParams<{ orgId: string; projectId: string }>()
@@ -178,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].page.tsx → /docs/<anything>
+// src/pages/docs/[...slug]/page.tsx → /docs/<anything>
 const { slug } = useParams<{ slug: string }>()
 // /docs/intro/getting-started → slug = "intro/getting-started"
 ```
@@ -186,7 +186,7 @@ const { slug } = useParams<{ slug: string }>()
 **Optional** catch-all (matches the base URL too):
 
 ```tsx
-// src/pages/docs/[[...slug]].page.tsx
+// src/pages/docs/[[...slug]]/page.tsx
 // /docs       → slug = ""
 // /docs/foo   → slug = "foo"
 // /docs/foo/bar → slug = "foo/bar"
@@ -201,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.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
+src/pages/users/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
@@ -242,14 +242,14 @@ Parse the query string explicitly via `useServerRequest()` on the server and `wi
 
 ## Co-locating components, hooks and tests
 
-Only `*.page.tsx` is a route. Everything else under `src/pages/` is ordinary code and may sit next to the page that uses it:
+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/
 ├── users/
-│   ├── index.page.tsx        # → /users
-│   ├── index.page.test.tsx   # its test
-│   ├── [id].page.tsx         # → /users/:id
+│   ├── page.tsx        # → /users
+│   ├── page.test.tsx   # its test
+│   ├── [id]/page.tsx         # → /users/:id
 │   ├── UserCard.tsx          # a component — no URL
 │   └── useFilters.ts         # a hook — no URL
 ```
@@ -262,6 +262,8 @@ No naming trick is needed to keep something out of the router: the absence of th
 
 The canonical form is **no trailing slash** — always link with `<Link to="/about">`, not `<Link to="/about/">`.
 
+`Link` forwards every prop it does not consume itself to the underlying `<a>`, `ref` included — so it drops straight into a polymorphic slot (`<Button component={Link} to={url}>`) without a wrapper.
+
 The framework does NOT emit a trailing-slash redirect on its own. If you need `/about/` → `/about` normalisation (for SEO), configure a 301 redirect at your reverse proxy.
 
 ## What pages CAN'T do
@@ -319,11 +321,11 @@ Conventions:
 ```text
 src/pages/
 ├── layout.tsx                # outer (every page)
-├── about.page.tsx                 # /about → wrapped in outer layout
+├── about/page.tsx                 # /about → wrapped in outer layout
 └── dashboard/
     ├── layout.tsx            # nested (only /dashboard/*)
-    ├── index.page.tsx             # /dashboard
-    └── settings.page.tsx          # /dashboard/settings
+    ├── page.tsx             # /dashboard
+    └── settings/page.tsx          # /dashboard/settings
 ```
 
 For `/dashboard/settings`, the React tree is:
@@ -346,13 +348,13 @@ A directory in `(parentheses)` does NOT contribute a URL segment, but its layout
 src/pages/
 ├── (marketing)/
 │   ├── layout.tsx            # marketing-scoped chrome
-│   ├── index.page.tsx             # /
-│   ├── pricing.page.tsx           # /pricing
-│   └── about.page.tsx             # /about
+│   ├── page.tsx             # /
+│   ├── pricing/page.tsx           # /pricing
+│   └── about/page.tsx             # /about
 └── (app)/
     ├── layout.tsx            # authenticated app chrome
-    ├── dashboard.page.tsx         # /dashboard
-    └── settings.page.tsx          # /settings
+    ├── dashboard/page.tsx         # /dashboard
+    └── settings/page.tsx          # /settings
 ```
 
 Marketing pages get one layout; authenticated app pages get another; the URLs stay flat.
@@ -496,7 +498,7 @@ Those four are the **complete** set. An unrecognised value is a hard error namin
 ## static (SSG)
 
 ```tsx
-// src/pages/about.page.tsx
+// src/pages/about/page.tsx
 export const renderMode = 'static' as const
 ```
 
@@ -509,7 +511,7 @@ At `voltro build`:
 For dynamic patterns, export `getStaticPaths` to enumerate every URL to pre-render:
 
 ```tsx
-// src/pages/blog/[slug].page.tsx
+// src/pages/blog/[slug]/page.tsx
 export const renderMode = 'static' as const
 
 export const getStaticPaths = async () => [
@@ -734,7 +736,7 @@ Both are static module exports — the framework discovers them, the build pipel
 ## A loader
 
 ```tsx
-// src/pages/notes/[id].page.tsx
+// src/pages/notes/[id]/page.tsx
 import { useLoaderData } from '@voltro/web'
 
 interface Note {
@@ -844,7 +846,7 @@ splits the loader's result into data that blocks the shell and data that
 soon as the promise settles.
 
 ```tsx
-// src/pages/dashboard.page.tsx
+// src/pages/dashboard/page.tsx
 import { Await, defer, useLoaderData } from '@voltro/web'
 
 export const renderMode = 'ssr' as const   // required — see below
@@ -964,7 +966,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].page.tsx
+// src/pages/notes/[id]/page.tsx
 import { useSubscription } from '@voltro/client'
 import { useLoaderData, type PageMeta } from '@voltro/web'
 
@@ -1136,7 +1138,7 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
 ### Authenticated dashboard with cookie-driven loader
 
 ```tsx
-// src/pages/dashboard/index.page.tsx
+// src/pages/dashboard/page.tsx
 import { useLoaderData } from '@voltro/web'
 
 export const renderMode = 'ssr' as const
@@ -1162,7 +1164,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].page.tsx
+// src/pages/blog/[slug]/page.tsx
 import { listPostSlugs, type Post } from '../../content/posts'
 
 export const renderMode = 'static' as const
@@ -1563,7 +1565,7 @@ export default island(LikeButton, { name: 'LikeButton', hydrate: 'visible' })
 Use it in a page:
 
 ```tsx
-// src/pages/blog/[slug].page.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

@@ -903,9 +903,12 @@ that affordance read-only rather than binding to a tag that does not resolve. Th
 [`useCan`](/docs/ui/client-utilities/use-can); map them to your app's real RBAC
 scopes.
 
-The inspect surface is open in dev. When a deploy sets an inspect token the
-manifest GET is bearer-gated, so an admin UI pointed at a locked-down api has to
-supply that token — a deployment concern, not something this hook handles.
+The manifest GET is bearer-gated wherever it runs — `/_voltro/inspect/*` is
+fail-closed, so no configured `VOLTRO_INSPECT_TOKEN` means `401`, not "everyone".
+Under `voltro dev` that is handled for you (the dev server mints a token and its
+proxy attaches it server-side). An admin UI pointed at a deployed api has to
+supply the token itself — a deployment concern, not something this hook
+handles.
 
 
 

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.page.tsx` is plain JSX with the two static-render exports:
+`src/pages/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.page.tsx</code> to make it yours.</p>
+        <p>Edit <code>src/pages/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.page.tsx
+// src/pages/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].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`**.
+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].page.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.page.tsx — a pure client-side SPA (a bill splitter)
+// src/pages/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.page.tsx
+// src/pages/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.page.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.page.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].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.
+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].page.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.page.tsx
+// src/pages/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.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:
+`src/pages/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.page.tsx
+// src/pages/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.page.tsx                  # the reactive page — useSubscription + useMutation
+    └── 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.page.tsx
+// src/pages/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.page.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/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.page.tsx — the entire file
+// src/pages/[locale]/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.page.tsx
+// src/pages/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.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.
+- **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.page.tsx
+// src/pages/dashboard/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.page.tsx
+// src/pages/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].page.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].page.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