@voltro/cli 0.1.0

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

@@ -0,0 +1,2062 @@
+# templates.appShells
+
+> A marketing landing page — hero, features, CTA. Static-rendered with zero JS on the wire by default.
+
+
+
+---
+
+<!-- source: en/templates/landing.md -->
+## Landing
+
+_A marketing landing page — hero, features, CTA. Static-rendered with zero JS on the wire by default._
+
+A marketing landing page. The page exports `renderMode = 'static'` + `interactive = 'none'`, so `voltro build` pre-renders it to HTML and `voltro start` serves the file directly — zero framework JS on the wire. Template id: **`frontend-landing`**.
+
+It ships plain JSX (a hero, a features list, a CTA) you replace with your own copy — no design-system dependency to fight. When you need a contact form or sign-up flow, switch `interactive: 'islands'` on the page and mark the interactive component with a `*.island.tsx` suffix so only that bundle ships.
+
+## Scaffold
+
+```bash
+voltro create-project acme --web=frontend-landing
+# or onto an existing project
+voltro add-app marketing --template=frontend-landing --to acme
+```
+
+## What ships
+
+```text
+apps/acme/web/                          # dir named by the app, not the template
+├── app.config.ts                       # type:web, port:<allocated>
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── globals.css
+    └── pages/
+        ├── layout.tsx                  # imports globals.css, renders {children}
+        └── index.tsx                   # the landing page (hero · features · CTA)
+```
+
+## The page
+
+`src/pages/index.tsx` is plain JSX with the two static-render exports:
+
+```tsx
+export const renderMode  = 'static' as const   // pre-render at build time
+export const interactive = 'none'   as const   // strip ALL framework JS — plain HTML + CSS
+
+export default function Index() {
+  return (
+    <main>
+      <section>
+        <h1>{/* your brand */}</h1>
+        <p>Replace this hero copy with your value prop.</p>
+        <a href="#features">Learn more →</a>
+      </section>
+      <section id="features">
+        <h2>Features</h2>
+        <ul>{/* feature bullets */}</ul>
+      </section>
+      <section>
+        <h2>Ready to start?</h2>
+        <p>Edit <code>src/pages/index.tsx</code> to make it yours.</p>
+      </section>
+    </main>
+  )
+}
+```
+
+`interactive: 'none'` means the framework strips every `<script type="module">` from the rendered HTML — the page ships as content + CSS only. Best perf for a pure-content marketing page.
+
+## Adding an interactive piece
+
+A contact form, a newsletter signup, a theme toggle — anything that needs JS — goes in an island so only that bundle hydrates:
+
+```tsx
+// src/components/SignupForm.island.tsx
+import { island } from '@voltro/web'
+const SignupForm = () => { /* … */ }
+export default island(SignupForm, { name: 'SignupForm', hydrate: 'visible' })
+```
+
+```tsx
+// src/pages/index.tsx
+export const interactive = 'islands' as const   // was 'none'
+import SignupForm from '../components/SignupForm.island'
+// … render <SignupForm /> somewhere in the page …
+```
+
+The surrounding HTML stays static; only the island hydrates.
+
+## Styling
+
+`globals.css` is yours. Add `@import "tailwindcss"` plus the mandatory `@source "./**/*.{tsx,ts,jsx,js}"` glob if you want Tailwind, or `@import "@voltro/ui-shadcn/tokens.css"` (plus the kit `@source`) to pull in the design tokens and compose shadcn-style components on top.
+
+## What it doesn't ship
+
+- **A sign-in form / auth.** Wire it yourself, or pair the page with an `api` and the framework's session helpers.
+- **Live data / subscriptions.** Marketing pages are static. Pair with an api template if you need a live stat.
+
+## Pairs well with
+
+- [`frontend-docs`](/docs/templates/docs) — link "Docs" from the landing's nav.
+- Any api template — pair the marketing site with a backend in the same project.
+
+## Anti-patterns
+
+- **Hydrating the whole page when only one widget is interactive.** Keep `interactive: 'none'` and wrap the one interactive bit in an `island()` (then set `'islands'`) — don't flip the whole page to `'full'`.
+- **Leaving `renderMode` unset.** The default is `'static'` already, but the explicit pair (`'static'` + `'none'`) is what makes this page ship zero JS — keep it.
+
+
+
+---
+
+<!-- source: en/templates/blank.md -->
+## Blank
+
+_Empty React + Vite + Tailwind shell. Start here when you want custom UI without an opinion getting in the way._
+
+The minimal web app — React + Vite + the framework's wiring + nothing else. Use it when you want full design control without inheriting the design tokens, layouts, or compositions other templates ship. Template id: **`frontend-blank`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --web=frontend-blank
+voltro add-app marketing --template=frontend-blank --to acme
+```
+
+## What ships
+
+```text
+apps/acme/web/                          # dir named by the app, not the template
+├── app.config.ts                       # type:web, port:<allocated>
+├── package.json
+├── tsconfig.json
+└── src/
+    └── pages/
+        ├── layout.tsx                  # just renders {children}
+        └── index.tsx                   # an index page
+```
+
+That's it. No `@voltro/ui-shadcn` dependency, no design tokens, no `globals.css`. Add `@import "tailwindcss"` in a `src/globals.css` (and the mandatory `@source` glob) yourself when you want Tailwind.
+
+## When to use blank vs. landing
+
+| You want… | Pick |
+|---|---|
+| A marketing landing surface | `frontend-landing` |
+| A documentation site | `frontend-docs` |
+| To bring your own brand / UI from scratch | `frontend-blank` |
+
+If you're going to override every default + replace every composition, scaffold `frontend-blank` instead of fighting `frontend-landing`'s defaults.
+
+## When to NOT use blank
+
+If your final product is going to be a:
+
+- Marketing landing → scaffold [`frontend-landing`](/docs/templates/landing).
+- Docs site → scaffold [`frontend-docs`](/docs/templates/docs).
+
+`frontend-blank` is the right pick when neither opinionated frontend template matches your shape, AND you want to keep the dependency footprint minimal.
+
+## What you have to do yourself
+
+- **Layout shell** — `layout.tsx` just renders `{children}`. Add a header, footer, etc.
+- **Styling** — no `globals.css` ships. Add `@import "tailwindcss"` + the `@source` glob yourself, or bring any other CSS approach.
+- **Component library** — bring your own or `pnpm add @voltro/ui-shadcn` later for the kit's components.
+- **Theme toggle** — none included. Add via `@voltro/ui-shadcn`'s `ThemeToggle` or roll your own.
+
+## Pairs well with
+
+- Any api template — `frontend-blank` doesn't presuppose one. The wiring is the same as the other web templates.
+- [`@voltro/ui-shadcn`](/docs/routing/styling) — the kit can be added incrementally. Import primitives one at a time (the styling page covers the mandatory Tailwind wiring).
+
+## Anti-patterns
+
+- **Starting with `frontend-blank` to "save bundle size" then importing every kit primitive.** If you end up wanting most of the kit, scaffold `frontend-landing` — the styling is already set up.
+- **Treating `frontend-blank` as the "canonical" template.** It's the LEAST opinionated. The other frontend templates are built on the same primitives plus a layer of curated design.
+
+
+
+---
+
+<!-- source: en/templates/docs.md -->
+## Docs
+
+_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`**.
+
+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.
+
+## Scaffold
+
+```bash
+voltro create-project mydocs --web=frontend-docs
+# or
+voltro add-app docs --template=frontend-docs --to acme
+```
+
+## What ships
+
+```text
+apps/acme/docs/                         # dir named by the app, not the template
+├── app.config.ts                       # type:web, port:<allocated>
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── globals.css
+    └── pages/
+        ├── layout.tsx                  # the shell wrapping every page
+        ├── index.tsx                   # / landing page
+        └── docs/
+            └── [...slug].tsx           # /docs/* catch-all renderer
+```
+
+## The catch-all renderer
+
+`src/pages/docs/[...slug].tsx` is the whole engine. It declares:
+
+```tsx
+export const renderMode  = 'static' as const   // pre-render at build
+export const interactive = 'none'   as const   // ship zero JS — pure content
+
+// Replace this stub with your own loader (markdown folder, CMS, DB).
+const DOCS = [
+  { slug: 'intro/getting-started', title: 'Getting started', body: '…' },
+  { slug: 'guides/first-page',     title: 'Your first page',  body: '…' },
+]
+
+// getStaticPaths enumerates the URLs to pre-render. The captured slug
+// is the raw `/`-joined path (NOT a string array), so 'intro/getting-started'
+// renders one HTML file at /docs/intro/getting-started.
+export const getStaticPaths = async () =>
+  DOCS.map((d) => ({ params: { slug: d.slug } }))
+
+export default function DocPage() {
+  const { slug } = useParams<{ slug: string }>()
+  const doc = DOCS.find((d) => d.slug === slug)
+  // … render doc.title + doc.body, or a not-found fallback …
+}
+```
+
+Every `getStaticPaths` entry becomes one pre-rendered HTML file at build time. Because `interactive: 'none'`, the framework strips the JS bundle from each page — the output is plain content HTML.
+
+## Wiring real content
+
+The stub `DOCS` array is the swap point. Point the loader at whatever holds your docs:
+
+- **Markdown folder** — read `*.md` at build time with a Vite `import.meta.glob` and parse frontmatter; map each file to a `{ slug, title, body }`.
+- **CMS / database** — fetch the doc index in `getStaticPaths`, fetch each page's body in the loader.
+
+The component contract (`{ slug }` param → render a doc) doesn't change — only where `DOCS` comes from.
+
+## Adding a page
+
+With the stub source, a page is a new entry in the `DOCS` array. With a real markdown loader, a page is a new `.md` file the glob picks up. Either way `getStaticPaths` re-enumerates and `voltro build` emits one more HTML file.
+
+## Pairs well with
+
+- [`frontend-landing`](/docs/templates/landing) — the docs share the marketing site's brand.
+
+## Anti-patterns
+
+- **Client-side markdown rendering.** Render content during the build / loader pass so it reaches React as pre-rendered HTML. Re-rendering every page client-side is wasteful and hurts search-engine indexing.
+- **Leaving `interactive` unset on content pages.** The starter sets `'none'` deliberately — a docs page that ships no JS loads fastest. Only switch to `'islands'` if you add a search box or theme toggle.
+
+
+
+---
+
+<!-- source: en/templates/changelog.md -->
+## Changelog
+
+_A changelog / release-notes site — MDX releases rendered to a list and per-release pages with highlighted code, plus an RSS feed, powered by @voltro/changelog._
+
+A changelog / release-notes site. Write each release as an `.mdx` file; the template renders a reverse-chronological list, one page per release with syntax-highlighted code, and an RSS feed. Powered by `@voltro/changelog`. Template id: **`changelog`**.
+
+## Scaffold
+
+```bash
+voltro create-project myapp --web=changelog
+# or
+voltro add-app changelog --template=changelog --to acme
+```
+
+## What ships
+
+```text
+apps/acme/changelog/                    # dir named by the app, not the template
+├── app.config.ts                       # type:web, port:<allocated>
+├── package.json                        # build = generate RSS, then voltro build
+├── tsconfig.json
+├── content/
+│   └── releases/
+│       ├── 0.1.0.mdx                   # one file per release (frontmatter + markdown)
+│       └── 0.2.0.mdx
+├── scripts/
+│   └── generate-rss.mjs                # writes public/rss.xml at build time
+└── src/
+    ├── globals.css
+    ├── globals.d.ts
+    ├── lib/
+    │   └── releases.ts                 # loadReleases over the MDX glob
+    └── pages/
+        ├── layout.tsx                  # BlogLayout shell
+        ├── index.tsx                   # the release list
+        └── [slug].tsx                  # one page per release
+```
+
+## How it works
+
+A release is an `.mdx` file with frontmatter. `version` and `releasedAt` are required; everything else is optional:
+
+```mdx
+---
+version: 0.2.0
+releasedAt: 2026-06-21
+slug: v0-2-0          # URL segment; defaults to a slugified version
+title: Typed env + faster boot
+summary: Declare your environment once; it's validated at startup.
+tags: [feature, performance]   # feature | fix | breaking | security | performance
+---
+
+## What changed
+
+Markdown body — code fences are highlighted at build time.
+```
+
+`src/lib/releases.ts` reads every file via Vite's raw glob and turns them into typed, sorted records:
+
+```ts
+import { loadReleases } from '@voltro/changelog'
+
+const sources = import.meta.glob('../../content/releases/*.mdx', {
+  query: '?raw', import: 'default', eager: true,
+}) as Record<string, string>
+
+export const releases = loadReleases(sources)   // newest first, invalid files skipped
+```
+
+`index.tsx` maps `releases` to the list. `[slug].tsx` enumerates the release slugs with `getStaticPaths` so `voltro build` pre-renders one HTML page per release, and its loader calls `highlightRelease` — at build time (Node) that runs shiki over the code fences; in the browser it's a no-op and the plain markdown HTML is used.
+
+Both pages are `renderMode: 'static'` + `interactive: 'none'`, so the output is pure content HTML with no JS bundle.
+
+## RSS feed
+
+`pnpm build` runs `scripts/generate-rss.mjs` (which calls `renderReleaseRss`) before the static build, emitting `public/rss.xml` → served at `/rss.xml`. Set `SITE_URL` so the feed's links are absolute:
+
+```bash
+SITE_URL=https://changelog.example.com pnpm build && pnpm start
+```
+
+The feed is generated as a static file rather than a route because the build pre-renders HTML pages — a feed is a non-HTML artifact.
+
+## "What's new" badge in another app
+
+The browser-only `@voltro/changelog/web` subpath ships `useChangelogBadge`, which polls this site's `rss.xml` and tells a **product** app's nav when there's an unread release. Add it to that app (not this one):
+
+```tsx
+import { useChangelogBadge } from '@voltro/changelog/web'
+
+const { hasUnread, latest, markRead } = useChangelogBadge({
+  url: 'https://changelog.example.com/rss.xml',
+})
+// render a dot when `hasUnread`; call `markRead()` when the user opens it.
+```
+
+## Add a release
+
+Drop a new `.mdx` file in `content/releases/`. Files missing `version` / `releasedAt` are skipped; the list re-sorts newest-first automatically and `voltro build` emits one more page.
+
+## Pairs well with
+
+- [`frontend-landing`](/docs/templates/landing) — the changelog shares the marketing site's brand.
+
+## Anti-patterns
+
+- **Rendering markdown client-side.** The template renders at build / loader time so content reaches React as pre-rendered HTML — faster, and indexable.
+- **Putting the badge on the changelog site.** `useChangelogBadge` belongs in the product app whose users you want to notify, pointed at this site's feed — not on the changelog itself.
+
+
+
+---
+
+<!-- source: en/templates/spa.md -->
+## SPA
+
+_Pure client-rendered single-page app (renderMode: 'spa') — a fully interactive standalone tool, no backend, no SSR. State lives in the browser._
+
+A pure client-rendered web app — a fully interactive standalone tool with NO backend and NO SSR. Every page sets `renderMode = 'spa'`, so `voltro build` skips pre-rendering and the client renders on load. That is the right call when the page's state lives entirely in the browser (here: `localStorage`), so a server-rendered first paint would just be discarded on hydration. The shipped example is a bill splitter — plain React, plain CSS, no rpc client, no loader. Template id: **`frontend-spa`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --web=frontend-spa
+voltro add-app splitter --template=frontend-spa --to acme
+```
+
+## What ships
+
+```text
+apps/acme/web/                          # dir named by the app, not the template
+├── app.config.ts                       # type:web, theme:'system', defineEnv
+├── package.json
+├── tsconfig.json
+├── README.md
+└── src/
+    ├── globals.css                     # self-contained plain CSS (no Tailwind / kit)
+    └── pages/
+        ├── layout.tsx                  # imports globals.css, renders {children}
+        └── index.tsx                   # the bill splitter — renderMode: 'spa'
+```
+
+No rpc client, no loader, no `apis:` entry, no `@voltro/ui-shadcn` dependency. The app depends only on `@voltro/web` / `@voltro/client` / `@voltro/env` / `@voltro/cli` + React 19 — it's React plus the framework's web wiring and nothing else.
+
+## `renderMode = 'spa'` — client-render, no pre-render
+
+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)
+import type { ReactNode } from 'react'
+import { useEffect, useState } from 'react'
+
+export const renderMode = 'spa' as const
+// `interactive` defaults to 'full' — every component hydrates. That is
+// correct for an SPA where the whole tree is interactive (don't reach for
+// islands here; islands only help when most of the page is static).
+
+const TIP_PRESETS = [10, 15, 18, 20] as const
+const STORAGE_KEY = '{{appName}}:last-tip'
+
+export default function BillSplitter(): ReactNode {
+  const [bill, setBill] = useState('')
+  const [tipPct, setTipPct] = useState(18)
+  const [people, setPeople] = useState(2)
+  // ...
+}
+```
+
+`interactive` is left at its default `'full'` — the whole tree hydrates, which is right for an SPA. Islands only help when most of the page is static; here the JS *is* the page.
+
+## Browser-only state via `localStorage`
+
+The last tip % is remembered locally. Because `localStorage` is client-only, it's read in an effect (the effect body never runs on the server) — restore on mount, persist on change:
+
+```tsx
+// Restore the last tip % from localStorage — client-only, so read it in
+// an effect (it never runs on the server).
+useEffect(() => {
+  const saved = Number(window.localStorage.getItem(STORAGE_KEY))
+  if (Number.isFinite(saved) && saved > 0) setTipPct(saved)
+}, [])
+
+useEffect(() => {
+  window.localStorage.setItem(STORAGE_KEY, String(tipPct))
+}, [tipPct])
+```
+
+This is the canonical "spa is the right call" signal: state that only exists in the browser. With `renderMode: 'static'` the server would render a default tip % and the client would overwrite it on mount — a visible flash for zero benefit.
+
+## Layout + styling — self-contained, no Tailwind
+
+The root `layout.tsx` imports `globals.css` and renders its children. The SPA renders entirely client-side, so there's no SSR document to worry about:
+
+```tsx
+// src/pages/layout.tsx
+import type { ReactNode } from 'react'
+import '../globals.css'
+
+export default function Layout({ children }: { readonly children: ReactNode }): ReactNode {
+  return <>{children}</>
+}
+```
+
+`globals.css` is hand-written plain CSS with light/dark custom properties — no `@import "tailwindcss"`, no `@source` glob, no `@voltro/ui-shadcn`. The dark variant keys off `:root.dark`, which the framework's pre-paint theme script toggles (see below):
+
+```css
+/* src/globals.css — self-contained, plain CSS */
+:root {
+  --bg: #f4f4f5;
+  --card: #ffffff;
+  --fg: #18181b;
+  --muted: #71717a;
+  --accent: #0d9488;
+  --border: #e4e4e7;
+}
+
+:root.dark {
+  --bg: #09090b;
+  --card: #18181b;
+  --fg: #fafafa;
+  --muted: #a1a1aa;
+  --accent: #2dd4bf;
+  --border: #27272a;
+}
+```
+
+## Config — `theme: 'system'` + a public env var
+
+`app.config.ts` is the minimal web shape: `type: 'web'`, `theme: 'system'`, and a single public env var declared with `defineEnv`. `theme: 'system'` lets the framework's inline head script set the `:root.dark` class from the OS preference (or the `voltro:theme` cookie) BEFORE first paint — no light→dark flash, and no `useEffect` toggling the class:
+
+```ts
+// app.config.ts
+import { defineEnv, envVar } from '@voltro/env'
+
+export const env = defineEnv({
+  VOLTRO_PUBLIC_APP_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  theme: 'system' as const,
+  env,
+}
+```
+
+The public var is browser-bundled, so it carries the mandatory `VOLTRO_PUBLIC_*` prefix and is read on the client via `publicEnv.VOLTRO_PUBLIC_APP_NAME` from `@voltro/env/public`.
+
+## Build + serve
+
+```bash
+voltro build .     # production build (no pre-render for spa pages)
+voltro start .     # serve the built dist/
+```
+
+## When to use frontend-spa vs. the other web templates
+
+| You want… | Pick |
+|---|---|
+| A heavily interactive standalone tool whose state lives in the browser | `frontend-spa` |
+| A blank React shell to bring your own brand | [`frontend-blank`](/docs/templates/blank) |
+| A marketing landing surface | [`frontend-landing`](/docs/templates/landing) |
+| A documentation site | [`frontend-docs`](/docs/templates/docs) |
+
+Reach for `frontend-spa` only when the JS *is* the page. For content pages (marketing, blog, docs) prefer `renderMode: 'static'` and `island()` for the few interactive widgets — see the [render modes guide](/docs/routing/render-modes).
+
+## Pairs well with
+
+- **Nothing on the backend** — the point of this template is a self-contained client app. Add an api later (and an `apis:` entry in `app.config.ts`) only when you genuinely need server-side data.
+- Any api template if you DO grow a backend — the web wiring is identical to the other web templates.
+
+## Anti-patterns
+
+- **Reaching for `interactive: 'islands'` because it "sounds faster".** Islands only help when most of the page is static. An SPA is interactive everywhere — every island becomes its own React root, which is *slower* than one full-tree hydration. Leave `interactive` at its default `'full'`.
+- **Using `renderMode: 'spa'` for a content page.** If the page is mostly static text with a couple of interactive widgets, that's `renderMode: 'static'` + `island()`, not `spa` — you'd be throwing away SEO and first-paint for nothing.
+- **Reading `localStorage` at module top-level or during render.** It doesn't exist on the server and isn't synchronous-safe across hydration. Read it in a `useEffect` (as the template does) so the body only runs client-side.
+- **Toggling the `dark` class from a `useEffect`.** That paints a white flash on every navigation. The template sets `theme: 'system'` in `app.config.ts` and lets the framework's pre-paint script handle it — `globals.css` just reacts to `:root.dark`.
+
+
+
+---
+
+<!-- source: en/templates/ssr.md -->
+## SSR + ISR
+
+_Server-rendered pages (renderMode: 'ssr') and incrementally-cached pages (renderMode: 'isr' + revalidate / staleWhileRevalidate / tenantAware) — the render modes that need a runtime, not a static CDN._
+
+The server-rendered render modes in one app — a per-request `renderMode: 'ssr'` page (fresh on every visit, reads cookies/headers via `useServerRequest()`) plus two `renderMode: 'isr'` pages that cache the rendered HTML and revalidate it on a window (one tenant-aware, one with stale-while-revalidate). Unlike a static site these render on a runtime, so you serve them with `voltro start`, NOT a bare CDN. It's self-contained — the loaders compute their own data, so it boots with zero infra; swap a loader for `ctx.query(...)` to pull from your api. Template id: **`frontend-ssr`**.
+
+## Scaffold
+
+```bash
+voltro add-app web --template=frontend-ssr --to acme
+voltro create-project acme --web=frontend-ssr
+```
+
+## What ships
+
+```text
+apps/acme/web/                          # dir named by the app, not the template
+├── app.config.ts                       # type:web, theme:'system', defineEnv
+├── package.json
+├── tsconfig.json
+├── README.md
+└── src/
+    ├── globals.css                     # self-contained plain CSS (no Tailwind / kit)
+    └── pages/
+        ├── layout.tsx                  # nav + globals; <Link> client-nav
+        ├── index.tsx                   # `/`         — renderMode: 'ssr'
+        ├── feed.tsx                    # `/feed`     — renderMode: 'isr' + revalidate + tenantAware
+        └── feed-swr.tsx                # `/feed-swr` — renderMode: 'isr' + staleWhileRevalidate
+```
+
+No rpc client, no `apis:` entry, no `@voltro/ui-shadcn` dependency. The app depends only on `@voltro/web` / `@voltro/client` / `@voltro/env` / `@voltro/cli` + React 19 — the three pages exist to demonstrate the SSR and ISR render modes, nothing else.
+
+## SSR vs ISR — both need a runtime
+
+These render modes do NOT pre-render at build time the way `static` does — they produce HTML on a server, per request. `voltro build` won't bake them into flat files, and `voltro start` is what serves them. A pure CDN can't run a loader per request, so don't ship these there.
+
+| Page | Mode | What it demonstrates |
+|---|---|---|
+| `/` | `ssr` | Fresh per request; `useServerRequest()` reads cookies + headers server-side |
+| `/feed` | `isr` + `revalidate` + `tenantAware` | Cached HTML, revalidated on a window, per-tenant cache key |
+| `/feed-swr` | `isr` + `staleWhileRevalidate` | Serve stale instantly, refresh in the background |
+
+The full reference for these modes lives in the [render modes guide](/docs/routing/render-modes).
+
+## `renderMode = 'ssr'` — fresh on every request
+
+`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
+import type { ReactNode } from 'react'
+import { useLoaderData, useServerRequest, type LoaderFn, type PageMeta } from '@voltro/web'
+
+export const renderMode = 'ssr' as const
+
+export const meta: PageMeta = {
+  title: '{{capProjectName}} — SSR (fresh per request)',
+  description: 'Server-rendered on every request.',
+}
+
+interface HomeData {
+  readonly renderedAt: string
+  readonly nonce: number
+}
+
+export const loader: LoaderFn<HomeData> = async () => ({
+  renderedAt: new Date().toISOString(),
+  nonce: Math.floor(Math.random() * 1_000_000),
+})
+```
+
+### Reading the request with `useServerRequest()`
+
+`useServerRequest()` reads the request's cookies + headers — on the server during SSR, and the same shape on the client. This is the primitive for cookie-backed preferences (locale, theme) WITHOUT a hydration flash — the server reads the cookie before render starts, so the SSR'd HTML is already correct:
+
+```tsx
+export default function Home(): ReactNode {
+  const data = useLoaderData<HomeData>()
+  const req = useServerRequest()
+  const acceptLanguage = req?.headers['accept-language'] ?? 'unset'
+  const themeCookie = req?.cookies['voltro:theme'] ?? 'unset'
+  // … renders renderedAt, nonce, acceptLanguage, themeCookie …
+}
+```
+
+Use SSR for anything that varies per request: a logged-in dashboard, a page that reads the visitor's cookie/locale, or any data that must NOT be cached across requests.
+
+## `renderMode = 'isr'` — cache + revalidate + tenant-aware key
+
+`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
+import type { ReactNode } from 'react'
+import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
+
+export const renderMode = 'isr' as const
+
+// Cache window — a number (seconds) OR a string like '1 hour' / '30 seconds'.
+export const revalidate = '10 seconds'
+
+// Tenant-aware caching: the cache key includes the `x-tenant` request header,
+// so tenant A's render is never served to tenant B. Leave it off for pages
+// that don't vary by tenant (they then share ONE cache entry).
+export const tenantAware = true
+
+export const meta: PageMeta = {
+  title: '{{capProjectName}} — ISR (cached + revalidated)',
+  description: 'Cached HTML, revalidated on a window.',
+}
+
+interface FeedData {
+  readonly renderedAt: string
+  readonly nonce: number
+  readonly tenant: string
+}
+
+export const loader: LoaderFn<FeedData> = async ({ headers }) => ({
+  renderedAt: new Date().toISOString(),
+  nonce: Math.floor(Math.random() * 1_000_000),
+  tenant: headers?.['x-tenant'] ?? 'anonymous',
+})
+```
+
+The loader's `headers` is populated server-side (lowercased keys) — that's how `/feed` reads `x-tenant` to label the row. Watch the response headers to see the cache work: `x-voltro-cache: MISS` on the first request (it rendered), then `HIT` within the window, then `MISS` again after it expires.
+
+## `staleWhileRevalidate` — serve stale, refresh in the background
+
+`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
+import type { ReactNode } from 'react'
+import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
+
+export const renderMode = 'isr' as const
+export const revalidate = '5 seconds'
+// Within this window AFTER `revalidate` expires, requests get the STALE HTML
+// instantly + a background refresh runs. Beyond (revalidate + swr) the next
+// request blocks on a fresh render, like plain ISR.
+export const staleWhileRevalidate = '30 seconds'
+
+export const meta: PageMeta = {
+  title: '{{capProjectName}} — stale-while-revalidate',
+  description: 'Serve stale instantly, refresh in the background.',
+}
+```
+
+The response header tells you which path served the page: `x-voltro-cache: MISS` → `HIT` → `STALE` (background refresh) → `MISS` again after the SWR window.
+
+## Layout — nav + globals, full hydration
+
+The root `layout.tsx` imports `globals.css` and renders a nav. SSR/ISR pages hydrate fully by default, so `<Link>` does client-side navigation after the first load:
+
+```tsx
+// src/pages/layout.tsx
+import type { ReactNode } from 'react'
+import { Link } from '@voltro/web'
+import '../globals.css'
+
+export default function Layout({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <>
+      <nav className="top">
+        <Link to="/">/ (ssr)</Link>
+        <Link to="/feed">/feed (isr)</Link>
+        <Link to="/feed-swr">/feed-swr (isr + swr)</Link>
+      </nav>
+      <main>{children}</main>
+    </>
+  )
+}
+```
+
+`globals.css` is hand-written plain CSS with light/dark custom properties — no `@import "tailwindcss"`, no `@source` glob, no `@voltro/ui-shadcn`. The dark variant keys off `:root.dark`, which the framework's pre-paint theme script toggles (driven by `theme: 'system'` in `app.config.ts`).
+
+## Config — self-contained, zero infra
+
+`app.config.ts` is the minimal web shape: `type: 'web'`, `theme: 'system'`, and a single public env var. There's NO `apis:` entry — the loaders compute their own data, so the app boots with zero backend:
+
+```ts
+// app.config.ts
+import { defineEnv, envVar } from '@voltro/env'
+
+export const env = defineEnv({
+  VOLTRO_PUBLIC_APP_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  theme: 'system' as const,
+  env,
+}
+```
+
+### Pulling fresh data from your api
+
+To render from YOUR reactive backend instead of computing the data in the loader, declare an `apis` entry in `app.config.ts` and call `ctx.query` in an ssr/isr loader. `query` is present ONLY server-side (ssr/isr); it invokes the api's rpc directly over `POST /rpc`, forwarding the session cookie so the SAME Subject + tenant resolve as the WS path:
+
+```ts
+// app.config.ts:  apis: { app: { package: '@{{projectName}}/api' } }
+export const loader: LoaderFn<Data> = async ({ query }) => ({
+  post: await query!('posts.get', { id: '…' }),   // `query` is server-only
+})
+```
+
+In the browser, fetch live data with `useSubscription` in the component — the loader feeds the SSR first paint + the document `<title>`, the subscription keeps it live.
+
+## Build + serve
+
+```bash
+voltro build .     # production build + pre-built SSR bundle
+voltro start .     # production runtime — serves SSR/ISR on demand, runs the cache
+```
+
+The ISR cache only runs under `voltro start`. Watch the response headers there:
+
+```bash
+curl -i http://localhost:5190/        | grep x-voltro    # x-voltro-rendered-by: ssr
+curl -i http://localhost:5190/feed    | grep x-voltro    # x-voltro-cache: MISS, then HIT
+```
+
+## When to use frontend-ssr vs. the other web templates
+
+| You want… | Pick |
+|---|---|
+| Per-request HTML (cookies, auth) and/or cached-but-fresh content | `frontend-ssr` |
+| A heavily interactive standalone tool whose state lives in the browser | [`frontend-spa`](/docs/templates/spa) |
+| A blank React shell to bring your own brand | [`frontend-blank`](/docs/templates/blank) |
+| A marketing landing surface | [`frontend-landing`](/docs/templates/landing) |
+| A documentation site | [`frontend-docs`](/docs/templates/docs) |
+
+Reach for `frontend-ssr` only when a page's HTML must differ per visitor (`ssr`) or must be cached-but-fresh (`isr`). For pages that are identical for everyone and stable for a whole deploy, prefer `renderMode: 'static'` — see the [render modes guide](/docs/routing/render-modes).
+
+## Pairs well with
+
+- **Any api template** when you grow a backend — add an `apis:` entry in `app.config.ts` and call `ctx.query(...)` in the ssr/isr loaders to render from your reactive data.
+- [Self-hosting](/docs/deployment/self-hosting) on `voltro start` / a container — SSR/ISR need a runtime; only the `static` pages go to a [CDN](/docs/deployment/static-sites).
+
+## Anti-patterns
+
+- **Shipping SSR/ISR pages to a pure CDN.** They need a runtime to render per request — `voltro static deploy` will (correctly) refuse them. Serve them on `voltro start` / a container, and push only your `static` pages to a CDN.
+- **Reaching for `useServerRequest()` AFTER a user interaction.** It's for reading the request DURING the server render. To react to a button click that writes a cookie, use a regular event handler + `document.cookie` — SSR doesn't matter there.
+- **Using `renderMode: 'ssr'` for a page that's the same for everyone.** SSR re-renders on every request with no caching. If the HTML doesn't vary per visitor, that's `renderMode: 'static'` (identical for a whole deploy) or `renderMode: 'isr'` (cached + revalidated) — SSR there is wasted work on every hit.
+- **Setting `scope`-less / `tenantAware: false` on a per-tenant ISR page.** Without `tenantAware: true` an ISR page shares ONE cache entry across tenants — tenant A's render would be served to tenant B. Turn it on for anything that varies by `x-tenant`; leave it off only for pages that are genuinely the same for every tenant.
+- **Calling `query!(...)` without guarding for the client.** `ctx.query` is `undefined` for client-side loader invocations — only rely on it under `renderMode: 'ssr' | 'isr'`, and use `useSubscription` in the component for live browser data.
+
+
+
+---
+
+<!-- source: en/templates/static-blog.md -->
+## Static blog
+
+_A static SSG blog (renderMode: 'static') — dynamic [slug] routes pre-rendered at build via getStaticPaths from a content source, per-post meta from loaderData, and ONE island for selective hydration. No backend._
+
+A static, pre-rendered blog — every page is built to flat HTML by `voltro build`, so the browser downloads HTML and (almost) nothing else. It's the canonical **CMS→static** shape: a dynamic `[slug]` route is enumerated at build time by `getStaticPaths` reading a content source, each post's `<title>`/`<description>` comes from its `loader` data, and the one bit that moves — a reading-progress bar — is a single `island()` hydrated inside otherwise-inert HTML. No api, no rpc client, no SSR. Template id: **`frontend-static-blog`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --web=frontend-static-blog
+voltro add-app blog --template=frontend-static-blog --to acme
+```
+
+## What ships
+
+```text
+apps/acme/web/                          # dir named by the app, not the template
+├── app.config.ts                       # type:web, theme:'system', defineEnv (public-only)
+├── package.json
+├── tsconfig.json
+├── README.md
+└── src/
+    ├── globals.css
+    ├── content/
+    │   └── posts.ts                     # the content source (the "CMS") — single source of truth
+    ├── components/
+    │   └── ReadingProgress.island.tsx   # the ONE island — island() + hydrate: 'load'
+    └── pages/
+        ├── layout.tsx                   # imports globals.css, site header
+        ├── index.tsx                    # the post LIST — interactive: 'none' (zero JS)
+        └── blog/
+            └── [slug].tsx               # per-post page — getStaticPaths + loader + meta + the island
+```
+
+No rpc client, no loader fetching a backend, no `apis:` entry. The app depends only on `@voltro/web` / `@voltro/client` / `@voltro/env` / `@voltro/cli` + React 19 — the same minimal web wiring as `frontend-spa`, but every page is `renderMode: 'static'` instead of `'spa'`.
+
+## The content source — one swappable array (the "CMS")
+
+`src/content/posts.ts` is a plain in-repo array: the simplest stand-in for a CMS. It is imported by the index page (the list), the `[slug]` page (the detail), AND `getStaticPaths` — so it is the single source of truth for "which posts exist". In a real app you replace the body of `getStaticPaths` + the page loader to read from a CMS API, a database query, or a folder of markdown; nothing else changes.
+
+```ts
+// src/content/posts.ts
+export interface Post {
+  /** URL segment — `/blog/<slug>`. Must be unique + DNS-safe. */
+  readonly slug: string
+  readonly title: string
+  /** ISO date, shown + used for ordering. */
+  readonly date: string
+  /** One-line summary — feeds the list + the `<meta name="description">`. */
+  readonly excerpt: string
+  readonly readingMinutes: number
+  /** Body paragraphs, separated by a blank line. */
+  readonly body: string
+}
+
+export const posts: ReadonlyArray<Post> = [
+  {
+    slug: 'hello-static',
+    title: 'Why this blog ships zero JavaScript',
+    date: '2025-01-15',
+    excerpt: 'Every page is pre-rendered at build time, so the browser downloads HTML and nothing else.',
+    readingMinutes: 3,
+    body: `…`,
+  },
+  // …more posts…
+]
+```
+
+## 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.
+
+```tsx
+// src/pages/blog/[slug].tsx
+import type { ReactNode } from 'react'
+import { useLoaderData, notFound, type LoaderFn, type PageMeta } from '@voltro/web'
+import { posts, type Post } from '../../content/posts'
+import ReadingProgress from '../../components/ReadingProgress.island'
+
+export const renderMode = 'static' as const
+export const interactive = 'islands' as const
+
+// Which concrete paths to pre-render. Every returned `params` becomes one
+// built HTML file; un-enumerated slugs are simply not built (→ 404).
+export const getStaticPaths = async (): Promise<Array<{ params: { slug: string } }>> =>
+  posts.map((post) => ({ params: { slug: post.slug } }))
+
+// Runs at build time for each enumerated slug. Returning `notFound()` skips
+// the artifact at build / 404s at runtime — defensive, though getStaticPaths
+// only ever feeds us slugs that exist.
+export const loader: LoaderFn<Post> = async ({ params }) => {
+  const post = posts.find((p) => p.slug === params.slug)
+  if (!post) return notFound(`post ${params.slug}`)
+  return post
+}
+
+// `meta` as a function of the loader data → correct per-post <title> in the
+// pre-rendered HTML (great for SEO + social cards).
+export const meta = ({ loaderData }: { loaderData: Post }): PageMeta => ({
+  title: `${loaderData.title} — Acme`,
+  description: loaderData.excerpt,
+})
+
+export default function BlogPost(): ReactNode {
+  const post = useLoaderData<Post>()
+  return (
+    <main>
+      <ReadingProgress />
+      <p><a href="/">← All posts</a></p>
+      <article>
+        <h1>{post.title}</h1>
+        <p className="muted">{post.date} · {post.readingMinutes} min read</p>
+        {post.body.split('\n\n').map((para, i) => (
+          <p key={i}>{para}</p>
+        ))}
+      </article>
+    </main>
+  )
+}
+```
+
+Point `getStaticPaths` + `loader` at a CMS/DB/filesystem and the build will pre-render exactly those pages — the "static generation from a content source" pattern, with no extra config. A pure `'static'` page 404s for slugs you didn't enumerate, which is exactly right for a fixed content set; if you ALSO set `renderMode: 'ssr' | 'isr'`, `voltro start` renders the un-enumerated ones on demand.
+
+## The ONE island — selective hydration
+
+The post list ships zero JavaScript, but the post page wants a thin reading-progress bar that tracks scrolling. Hydrating the whole article to get that one widget would be wasteful. Instead the page declares `interactive: 'islands'` and the bar is wrapped in `island()`: the framework renders the article once as inert HTML and attaches React ONLY to the island marker — the surrounding HTML never runs a React lifecycle.
+
+```tsx
+// src/components/ReadingProgress.island.tsx
+import type { ReactNode } from 'react'
+import { useEffect, useState } from 'react'
+import { island } from '@voltro/web'
+
+function ReadingProgress(): ReactNode {
+  const [pct, setPct] = useState(0)
+
+  useEffect(() => {
+    const onScroll = (): void => {
+      const el = document.documentElement
+      const max = el.scrollHeight - el.clientHeight
+      setPct(max > 0 ? Math.min(100, (el.scrollTop / max) * 100) : 0)
+    }
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    window.addEventListener('resize', onScroll)
+    return () => {
+      window.removeEventListener('scroll', onScroll)
+      window.removeEventListener('resize', onScroll)
+    }
+  }, [])
+
+  return <div className="reading-progress" style={{ width: `${pct}%` }} aria-hidden="true" />
+}
+
+export default island(ReadingProgress, { name: 'ReadingProgress', hydrate: 'load' })
+```
+
+`hydrate: 'load'` wakes the island immediately — it must track scrolling from the very first frame. Other strategies defer the cost: `'idle'`, `'visible'` (on scroll-into-view, the best default below the fold), `'interaction'` (on first pointer/key), `'never'` (inert HTML forever).
+
+## The list page — `interactive: 'none'` (zero JS)
+
+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
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { posts } from '../content/posts'
+
+export const renderMode = 'static' as const
+export const interactive = 'none' as const
+
+export const meta: PageMeta = {
+  title: 'Acme — Blog',
+  description: 'A static, pre-rendered blog built with Voltro.',
+}
+
+// Newest first — sort a copy so the source array stays stable.
+const byDateDesc = [...posts].sort((a, b) => b.date.localeCompare(a.date))
+
+export default function Index(): ReactNode {
+  return (
+    <main>
+      <h1>Blog</h1>
+      <p className="muted">{posts.length} posts · pre-rendered at build time</p>
+      <ul className="post-list">
+        {byDateDesc.map((post) => (
+          <li key={post.slug}>
+            <a href={`/blog/${post.slug}`}>{post.title}</a>
+            <p>
+              <span className="muted">{post.date} · {post.readingMinutes} min</span>
+              {' — '}
+              {post.excerpt}
+            </p>
+          </li>
+        ))}
+      </ul>
+    </main>
+  )
+}
+```
+
+The layout uses a plain `<a>` (not `<Link>`) deliberately: the list is `interactive: 'none'` and the posts are `'islands'`, so there is no router runtime to intercept clicks — a real browser navigation is the correct, robust behaviour for a static content site.
+
+## Config — `theme: 'system'` + a public env var
+
+`app.config.ts` is the minimal web shape: a single public env var declared with `defineEnv`, and `theme: 'system'` so the framework's inline head script sets the `:root.dark` class from the OS preference (or the `voltro:theme` cookie) BEFORE first paint — no light→dark flash. A static site has no server, so a `secret` here makes no sense; everything is `public` (browser-bundled, `VOLTRO_PUBLIC_*`-prefixed):
+
+```ts
+// app.config.ts
+import { defineEnv, envVar } from '@voltro/env'
+
+export const env = defineEnv({
+  VOLTRO_PUBLIC_SITE_NAME: envVar.string({ access: 'public', default: 'Acme' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: 'AcmeBlog',
+  port: 5173,
+  theme: 'system' as const,
+  env,
+}
+```
+
+## Build + serve
+
+```bash
+voltro build .     # pre-render → dist/ (one HTML file per post)
+voltro start .     # serve the built dist/ locally
+```
+
+Because the output is pure static files, you can push `dist/` to any CDN instead of running a server. Add a post by appending to `src/content/posts.ts`; `getStaticPaths` reads the same array, so a new entry is pre-rendered on the next build — no route config.
+
+## When to use frontend-static-blog vs. the other web templates
+
+| You want… | Pick |
+|---|---|
+| A content site (blog/docs/marketing) pre-rendered to flat HTML with a few interactive widgets | `frontend-static-blog` |
+| A heavily interactive standalone tool whose state lives in the browser | [`frontend-spa`](/docs/templates/spa) |
+| A blank React shell to bring your own brand | [`frontend-blank`](/docs/templates/blank) |
+| A marketing landing surface | [`frontend-landing`](/docs/templates/landing) |
+| A documentation site | [`frontend-docs`](/docs/templates/docs) |
+
+## Pairs well with
+
+- **Nothing on the backend** — the point of this template is a self-contained static site. Add an api later (and an `apis:` entry in `app.config.ts`) only when a page genuinely needs live, request-time data — at which point flip that page to `renderMode: 'ssr' | 'isr'`.
+- Any api template if the blog grows a comments section or admin surface — the web wiring is identical to the other web templates.
+
+## Anti-patterns
+
+- **Reaching for `interactive: 'islands'` on a page that's interactive everywhere.** Islands only help when most of the page is static and a few widgets move (this template: a static article + one progress bar). A dashboard where everything is interactive wants `interactive: 'full'` — every island would be its own React root, which is *slower* than one full-tree hydration. See the [render modes guide](/docs/routing/render-modes).
+- **Forgetting `getStaticPaths` on a dynamic `[slug]` route.** Without it the build can't know which concrete URLs to emit, so NO post page is pre-rendered. Every dynamic segment that's `renderMode: 'static'` needs `getStaticPaths` to enumerate its paths from the content source.
+- **Returning the wrong shape from `meta`.** `meta` here is a function of `{ loaderData }` — read the post's fields off `loaderData`, don't hardcode a single title for every post, or every page gets the same `<title>` and you lose the per-post SEO win.
+- **Shipping JS on the `interactive: 'none'` list page.** The framework strips the bundle on purpose — don't paper over it with a Suspense boundary or a `requestIdleCallback` re-import. If a page genuinely needs interactivity, mark it `'islands'` (wrap the moving part in `island()`) or `'full'`.
+- **Using `<a>` to a CMS/DB query at request time on a `'static'` page.** A `'static'` page's loader runs at BUILD time only — there is no per-request render. If the data must be fresh per visit, the page is `renderMode: 'ssr'` (or `'isr'` for cached-with-revalidation), not `'static'`.
+
+
+
+---
+
+<!-- source: en/templates/contact.md -->
+## Contact form
+
+_Static page + a serverless email contact form — an island form POSTs to a bundled *.serverless.ts that sends mail via Resend. Page → CDN, function → scales to zero._
+
+The headline "static frontend, serverless backend" combo: a pre-rendered page (`renderMode: 'static'`) whose only hydrated part is an `island()` contact form, which POSTs JSON to a **standalone** `functions/sendMessage.serverless.ts`. That function is NOT part of a long-running api — the CLI bundles + ships it on its own, it sends mail via Resend over `HttpClient`, and it scales to zero. The page can go to any CDN; the function deploys SEPARATELY with `voltro serverless`. That split — page on the edge, backend on demand — is the whole point of the template. Template id: **`frontend-contact`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --web=frontend-contact
+```
+
+## What ships
+
+```text
+apps/acme/web/                          # dir named by the app, not the template
+├── app.config.ts                       # type:web, theme:'system', defineEnv
+├── package.json                        # scripts: dev, build, fn:dev, fn:deploy
+├── tsconfig.json
+├── README.md
+├── functions/
+│   └── sendMessage.serverless.ts       # the serverless backend — defineServerless, sends mail
+└── src/
+    ├── globals.css
+    ├── config.ts                        # CONTACT_ENDPOINT — where the form POSTs
+    ├── components/
+    │   └── ContactForm.island.tsx       # the only hydrated part (an island)
+    └── pages/
+        ├── layout.tsx                   # imports globals.css, renders {children}
+        └── index.tsx                    # static page — renderMode:'static', interactive:'islands'
+```
+
+The serverless function lives next to the web app but is a separate deploy artifact — it depends on `@voltro/serverless` (+ `@effect/platform` for `HttpClient`). The page itself depends only on `@voltro/web` / `@voltro/client` / `@voltro/env` / `@voltro/cli` + React 19.
+
+## 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:
+
+```tsx
+// src/pages/index.tsx
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import ContactForm from '../components/ContactForm.island'
+
+export const renderMode = 'static' as const
+export const interactive = 'islands' as const
+
+export const meta: PageMeta = {
+  title: '{{capProjectName}} — Get in touch',
+  description: 'Static page, serverless contact form.',
+}
+
+export default function Index(): ReactNode {
+  return (
+    <main>
+      <section className="hero">
+        <h1>{{capProjectName}}</h1>
+        <p className="lead">
+          This page is pre-rendered and ships from a CDN. The form below talks to
+          a serverless function that scales to zero — no always-on server in sight.
+        </p>
+      </section>
+
+      <section className="contact">
+        <h2>Send us a message</h2>
+        <ContactForm />
+      </section>
+    </main>
+  )
+}
+```
+
+The form is an island with `hydrate: 'visible'` — it's below the fold, so hydration defers until it scrolls into view. On submit it POSTs JSON to `CONTACT_ENDPOINT` (the serverless function), which lives on a **different origin**; the call works because the function's dev runner AND the edge hosts send CORS headers:
+
+```tsx
+// src/components/ContactForm.island.tsx
+import type { FormEvent, ReactNode } from 'react'
+import { useState } from 'react'
+import { island } from '@voltro/web'
+import { CONTACT_ENDPOINT } from '../config'
+
+type Status =
+  | { readonly kind: 'idle' }
+  | { readonly kind: 'sending' }
+  | { readonly kind: 'sent' }
+  | { readonly kind: 'error'; readonly message: string }
+
+function ContactForm(): ReactNode {
+  const [name, setName] = useState('')
+  const [email, setEmail] = useState('')
+  const [message, setMessage] = useState('')
+  const [status, setStatus] = useState<Status>({ kind: 'idle' })
+
+  const onSubmit = async (e: FormEvent): Promise<void> => {
+    e.preventDefault()
+    setStatus({ kind: 'sending' })
+    try {
+      const res = await fetch(CONTACT_ENDPOINT, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name, email, message }),
+      })
+      const body = (await res.json().catch(() => ({}))) as { error?: string; detail?: string }
+      if (!res.ok) {
+        setStatus({ kind: 'error', message: body.detail ?? body.error ?? `HTTP ${res.status}` })
+        return
+      }
+      setStatus({ kind: 'sent' })
+      setName(''); setEmail(''); setMessage('')
+    } catch (err) {
+      setStatus({ kind: 'error', message: err instanceof Error ? err.message : 'network error' })
+    }
+  }
+  // ...form JSX (name / email / message inputs + a submit button)...
+}
+
+export default island(ContactForm, { name: 'ContactForm', hydrate: 'visible' })
+```
+
+`CONTACT_ENDPOINT` is a plain constant in `src/config.ts` (not `publicEnv`) so the template typechecks BEFORE `voltro dev` generates the env types. Its default is the local serverless dev port, so the form works the moment you run `fn:dev` in another terminal:
+
+```ts
+// src/config.ts
+export const CONTACT_ENDPOINT = 'http://localhost:8910'
+```
+
+## The serverless function — `defineServerless`
+
+`functions/sendMessage.serverless.ts` is a standalone `*.serverless.ts`. It declares a Schema-validated `input` (a bad payload → a typed `400` before your handler runs), reads its secret from `ctx.env`, and sends the email by POSTing to Resend's HTTP API with the framework-provided `HttpClient`. No `node:*` import — so the SAME file runs on a Cloudflare Worker:
+
+```ts
+// functions/sendMessage.serverless.ts
+import { Effect, Schema } from 'effect'
+import { HttpClient, HttpClientRequest } from '@effect/platform'
+import { defineServerless, ServerlessHttpError } from '@voltro/serverless'
+
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/
+
+export default defineServerless({
+  name: 'send-message',
+  method: 'POST',
+  input: Schema.Struct({
+    name: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(120)),
+    email: Schema.String.pipe(Schema.pattern(EMAIL_RE)),
+    message: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(5000)),
+  }),
+  output: Schema.Struct({ ok: Schema.Boolean }),
+  runtime: { memoryMb: 128, timeoutSeconds: 10 },
+  handler: ({ name, email, message }, ctx) =>
+    Effect.gen(function* () {
+      const apiKey = ctx.env.RESEND_API_KEY
+      const to = ctx.env.CONTACT_TO ?? 'you@example.com'
+      const from = ctx.env.CONTACT_FROM ?? 'Contact form <onboarding@resend.dev>'
+
+      // No key wired yet → fail with a clear 503 the form can render. The
+      // function never pretends to send: honest in dev, honest in prod.
+      if (!apiKey) {
+        return yield* Effect.fail(
+          new ServerlessHttpError({
+            status: 503,
+            message: 'email-not-configured',
+            detail: 'Set RESEND_API_KEY (+ optionally CONTACT_TO / CONTACT_FROM) in the function env.',
+          }),
+        )
+      }
+
+      const http = yield* HttpClient.HttpClient
+      const request = HttpClientRequest.post('https://api.resend.com/emails').pipe(
+        HttpClientRequest.setHeader('authorization', `Bearer ${apiKey}`),
+        HttpClientRequest.bodyUnsafeJson({
+          from,
+          to: [to],
+          reply_to: email,
+          subject: `New message from ${name}`,
+          text: `${message}\n\n— ${name} <${email}>`,
+        }),
+      )
+
+      const response = yield* http.execute(request)
+      if (response.status >= 400) {
+        const detail = yield* response.text
+        return yield* Effect.fail(new ServerlessHttpError({ status: 502, message: 'email-send-failed', detail }))
+      }
+      return { ok: true }
+    }),
+})
+```
+
+`ServerlessHttpError({ status, message, detail })` is how you control the HTTP status the form sees — `503` when no key is configured, `502` when Resend rejects the send. The handler `Effect` declares `HttpClient` as its only dependency; the runner provides it.
+
+## Run both halves locally (two terminals)
+
+The page and the function run as two separate dev servers:
+
+```bash
+pnpm install
+
+# Terminal 1 — the static site (HMR dev server)
+pnpm --filter @acme/web dev          # voltro dev .
+
+# Terminal 2 — the serverless function on http://localhost:8910
+pnpm --filter @acme/web fn:dev       # voltro serverless dev functions/sendMessage.serverless.ts
+```
+
+The form POSTs to `http://localhost:8910` (the `CONTACT_ENDPOINT` default). The cross-origin POST works because **`voltro serverless dev` sends CORS headers** — the same headers Cloudflare / Scaleway add at the edge, so dev matches prod.
+
+Without `RESEND_API_KEY` the function returns a clean `503 email-not-configured` and the form renders it — it never pretends to send. To send for real, pass the secret to the function's env:
+
+```bash
+RESEND_API_KEY=re_... CONTACT_TO=you@example.com \
+  pnpm --filter @acme/web fn:dev
+```
+
+## Deploy — the split
+
+The page and the function ship to **different** places — that's the headline:
+
+```bash
+# 1. The static page → a CDN
+pnpm --filter @acme/web build
+voltro static deploy --host cloudflare-pages --project-name web
+
+# 2. The function → a function host (scales to zero), deployed SEPARATELY
+voltro serverless deploy --target node          # the package's fn:deploy script
+#   ...or --target cloudflare, or --target scaleway
+```
+
+Then point the form at the deployed function: set `CONTACT_ENDPOINT` in `src/config.ts` to the URL `voltro serverless deploy` printed, and rebuild the page. The function host bills per invocation and idles to zero between requests — no always-on server for an inbox form that fires a few times a day.
+
+## When to use frontend-contact vs. the other web templates
+
+| You want… | Pick |
+|---|---|
+| A static page + ONE serverless backend endpoint (a form, a small action) | `frontend-contact` |
+| A pure static surface with no backend at all | [`frontend-blank`](/docs/templates/blank) |
+| A heavily-interactive standalone tool whose state lives in the browser | [`frontend-spa`](/docs/templates/spa) |
+| A marketing landing surface | [`frontend-landing`](/docs/templates/landing) |
+| A documentation site | [`frontend-docs`](/docs/templates/docs) |
+
+## Pairs well with
+
+- [Serverless functions](/docs/deployment/serverless-functions) — the deploy + runtime model for the `*.serverless.ts` half (node / Cloudflare / Scaleway, scales to zero).
+- [Static sites](/docs/deployment/static-sites) — where the pre-rendered page goes (any CDN).
+- [Edge functions](/docs/templates/edge-functions) — when you need MORE than one function, or richer routing than a single contact endpoint.
+- [Render modes](/docs/routing/render-modes) — the `static` + `islands` combination the page leans on.
+
+## Anti-patterns
+
+- **Turning the function into a long-running api.** A `*.serverless.ts` is a standalone, scale-to-zero artifact — bundled + deployed on its own with `voltro serverless`, not discovered by `voltro dev` as part of an api. If you find yourself wanting queries, subscriptions, or a database next to it, you want an api template, not this.
+- **Reaching for `node:*` in the function.** The handler is edge-safe by design (it runs on a Cloudflare Worker). Use the framework-provided `HttpClient` for outbound HTTP; a `node:`-prefixed import breaks the Cloudflare/Scaleway targets.
+- **Making the function pretend to send when no key is wired.** The template fails LOUD with a `503 email-not-configured` that the form renders. Don't swap that for a silent `{ ok: true }` — a contact form that silently drops messages is worse than one that says it's not configured.
+- **Letting the form go `interactive: 'full'` or `'none'`.** The page is mostly static copy with one interactive widget — that's exactly `interactive: 'islands'` + an `island()` form. `'full'` hydrates the whole tree for no reason; `'none'` would strip the JS the form needs.
+- **Skipping the input Schema on the function.** The `defineServerless` `input` is what turns a malformed POST into a typed `400` before your handler runs. Don't hand-parse `JSON.parse(body)` and trust it.
+
+
+
+---
+
+<!-- source: en/templates/app.md -->
+## Fullstack app
+
+_The reactive end-to-end loop in one page — a web frontend wired to an api. A live list (useSubscription) + a create form (useMutation) with zero-boilerplate auto-optimistic updates._
+
+The framework's headline feature — a web client subscribing to a server query and getting WebSocket deltas on every write — in one page. `frontend-app` is the **only** template that wires a web frontend to an api; every other `frontend-*` template is backend-less and every `api-*` template is frontend-less. Template id: **`frontend-app`**.
+
+## Scaffold the pair
+
+`frontend-app` consumes a sibling api, so scaffold it **together with** [`api-backend`](/docs/templates/api-backend) — which exposes the `notes.list` query + `notes.create` mutation this page uses:
+
+```bash
+voltro create-project demo --api=api-backend --web=frontend-app
+cd demo
+pnpm install
+pnpm dev            # boots BOTH apps — the api and the web
+```
+
+Add a note and it appears in the list instantly — no refetch, no polling. Open a second tab: a note added in one shows up live in the other.
+
+## What ships
+
+```text
+apps/demo/web/
+├── app.config.ts                  # type:web + the apis: { app } wiring
+├── package.json                   # depends on @demo/api (the sibling) + @voltro/client
+├── tsconfig.json
+├── README.md
+└── src/pages/
+    ├── layout.tsx                 # root shell (header + <main>)
+    └── index.tsx                  # the reactive page — useSubscription + useMutation
+```
+
+## The `apis` wiring
+
+A web app declares the apis it consumes in `app.config.ts`. The map KEY is the lookup name every hook takes as its first argument:
+
+```ts
+// app.config.ts
+export default {
+  type: 'web' as const,
+  name: 'DemoWeb',
+  apis: {
+    app: { package: '@demo/api' },   // the sibling api in this project
+  },
+}
+```
+
+The `package` resolves the api workspace package; its port is auto-discovered from its own `app.config.ts`, and codegen pulls its typed rpc surface so the hooks are end-to-end typed. Add more entries to consume more apis — each gets its own WebSocket + reconnect cycle, independent of the others.
+
+```ts
+// package.json — the web depends on the sibling api as a workspace package
+"dependencies": {
+  "@demo/api": "workspace:*",
+  "@voltro/client": "workspace:*",
+  "@voltro/web": "workspace:*"
+}
+```
+
+## The reactive loop
+
+```tsx
+// src/pages/index.tsx
+import { useMutation, useSubscription } from '@voltro/client'
+
+const TENANT = 'acme'
+
+const IndexPage = () => {
+  // ONE live WebSocket subscription. `data` re-renders whenever the `notes`
+  // table changes — from this tab, another tab, a workflow, or a raw DB write.
+  const { data, revision, error, pendingPatches } =
+    useSubscription<ReadonlyArray<Note>>('app', 'notes.list')
+
+  // Invokes the mutation. Its descriptor declares `target: { table:'notes',
+  // op:'insert' }`, so the framework AUTO-PREPENDS an optimistic row the
+  // instant you submit — replaced by the real row (or reverted) on resolve.
+  const create = useMutation<{ tenantId: string; title: string; body: string }>('app', 'notes.create')
+
+  const notes = data ?? []
+  // … a form that calls create.mutate({ tenantId: TENANT, title, body }) …
+}
+```
+
+1. **`useSubscription('app', 'notes.list')`** opens the live feed. The first argument (`'app'`) is the api NAME from `app.config.ts`; the second is the rpc tag. Two components subscribing with the same triple share ONE upstream subscription.
+2. **`useMutation('app', 'notes.create').mutate({...})`** writes. There is no `.withOptimistic`, no `useOptimistic`, no `startTransition` — the auto-optimistic patch comes from the mutation's server-side `target`. Optimistic rows carry `optimistic: true`; render them faintly until the server delta supersedes them.
+
+The subscription builder also exposes `revision`, `emittedAt`, `error`, and `pendingPatches` for status UI; the mutation builder exposes `pending`, `error`, and `data`.
+
+## 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.
+
+## When to use
+
+| You want… | Pick |
+|---|---|
+| To see the reactive loop / start a real fullstack app | `frontend-app` (+ `api-backend`) |
+| A frontend with no backend | [`frontend-blank`](/docs/templates/blank) / [`frontend-landing`](/docs/templates/landing) |
+| Just the backend | [`api-backend`](/docs/templates/api-backend) |
+
+## Anti-patterns
+
+- **Scaffolding `frontend-app` without an api.** It depends on the sibling `@<project>/api` workspace package — `pnpm install` fails without it. Always scaffold the pair (`--api=api-backend --web=frontend-app`).
+- **Polling / `refetch`.** This framework is push-based; the subscription stays live for the component's lifetime. If you reach for `setInterval(() => refetch())`, something is wrong with the subscription.
+- **Hand-rolling optimistic updates.** The `target` on the mutation descriptor drives the patch automatically. Only reach for `.withOptimistic` when the default insert/update/delete shape isn't what you want.
+- **Trusting `x-tenant` in production.** The dev `AuthMiddleware` reads it unauthenticated. Wire a real resolver before shipping (see the [authentication docs](/docs/authentication/overview)).
+
+
+
+---
+
+<!-- source: en/templates/i18n.md -->
+## i18n
+
+_A bilingual (en/de) static site using the URL-prefix i18n strategy — type-checked translation catalogs, [locale] mirror pages, and per-locale SSG so each language is its own crawlable URL with a translated title. No backend._
+
+A bilingual static site built the **URL-prefix** way: the default locale (English) lives at the bare path (`/`, `/about`), and every other locale is prefixed (`/de`, `/de/about`). Each translated page is its own crawlable URL with its own pre-rendered `<title>` — the SEO-friendly shape for docs, marketing, and any content where the URL *is* the product. Translations are type-checked against a base catalog so they can never silently drift, and `voltro build` emits one HTML file per (page × locale). No api, no rpc client, no SSR. Template id: **`frontend-i18n`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --web=frontend-i18n
+voltro add-app site --template=frontend-i18n --to acme
+```
+
+## What ships
+
+```text
+apps/acme/web/                          # dir named by the app, not the template
+├── app.config.ts                       # type:web, theme:'system', locales:['en','de']
+├── package.json                        # + @voltro/i18n
+├── tsconfig.json
+├── README.md
+└── src/
+    ├── globals.css
+    ├── globals.d.ts                     # `declare module '*.css'`
+    ├── lib/
+    │   └── locale.ts                    # SUPPORTED_LOCALES + URL-prefix helpers (single source of truth)
+    ├── locales/
+    │   ├── en.ts                        # base catalog (source of truth)
+    │   └── de.ts                        # defineLocale<typeof en>() → parity-enforced
+    └── pages/
+        ├── layout.tsx                   # inner URL-driven <I18nProvider> + language switch
+        ├── index.tsx                    # home — renderMode 'static', meta as fn of {locale}
+        ├── about.tsx                    # second page
+        └── [locale]/
+            ├── index.tsx                # mirror → emits /de
+            └── about.tsx                # mirror → emits /de/about
+```
+
+The app depends on `@voltro/web` / `@voltro/client` / `@voltro/env` / `@voltro/cli` + React 19 + **`@voltro/i18n`** — the only addition over the other web templates. No `apis:` entry; every page is `renderMode: 'static'`.
+
+## The catalogs — type-checked parity
+
+`src/locales/en.ts` is the base catalog and the source of truth. `src/locales/de.ts` runs through `defineLocale<typeof en>()`, a curried helper that **enforces exact key parity at the type level** — drop or add a key and `tsc --noEmit` fails. That's the whole point of the base-catalog pattern: translations can't silently fall out of sync.
+
+```ts
+// src/locales/en.ts — base catalog
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  'nav.home':      'Home',
+  'home.title':    'Hello, {name}',
+  'home.tagline':  'A bilingual static site built with Voltro.',
+  // …
+} as const)
+```
+
+```ts
+// src/locales/de.ts — MUST mirror en key-for-key, or tsc fails
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'nav.home':      'Start',
+  'home.title':    'Hallo, {name}',
+  'home.tagline':  'Eine zweisprachige statische Website, gebaut mit Voltro.',
+  // …
+})
+```
+
+Keep ICU MessageFormat placeholders (`{name}`, `{count, plural, …}`) identical across locales — react-intl validates them at render time. Read them in components with `<T id="…" />` (JSX) or `useT('…')` (imperative).
+
+## URL-prefix routing — `lib/locale.ts` + `[locale]` mirrors
+
+The framework's auto-wired `<I18nProvider>` is *cookie*-driven (Strategy A — product dashboards). URL-prefix routing (Strategy B) needs the active locale to come from the URL instead, so `src/lib/locale.ts` is the single source of truth: it lists the supported locales (kept in sync with `app.config.ts`) and the prefix helpers.
+
+```ts
+// src/lib/locale.ts (excerpt)
+import { useLocation } from '@voltro/web'
+
+export const SUPPORTED_LOCALES = ['en', 'de'] as const
+export const DEFAULT_LOCALE = 'en'
+
+// '/de/about' → 'de'; '/about' → 'en' (default lives at the bare path)
+export const useUrlLocale = (): Locale => localeFromPathname(useLocation())
+
+// '/about' + 'de' → '/de/about'; the default locale stays bare ('/about')
+export const withLocalePrefix = (path: string, locale: string): string =>
+  locale === DEFAULT_LOCALE ? path : path === '/' ? `/${locale}` : `/${locale}${path}`
+```
+
+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
+import { SUPPORTED_LOCALES, DEFAULT_LOCALE } from '../../lib/locale'
+
+export { default } from '../index'
+export { renderMode, meta } from '../index'
+
+export const getStaticPaths = async (): Promise<Array<{ params: { locale: string } }>> =>
+  SUPPORTED_LOCALES
+    .filter((l) => l !== DEFAULT_LOCALE)
+    .map((locale) => ({ params: { locale } }))
+```
+
+## Per-locale `<title>` — `meta` as a function of `{ locale }`
+
+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
+import { T, useT, useLocale } from '@voltro/i18n'
+import { getCatalog } from '../lib/locale'
+
+export const renderMode = 'static' as const
+
+export const meta = ({ locale }: { locale: string }) => {
+  const c = getCatalog(locale)               // the catalog for this locale, at build time
+  return { title: c['meta.home.title'], description: c['meta.home.description'] }
+}
+
+export default function Index() {
+  const greeting = useT('home.title', { name: 'Voltro' })   // imperative form
+  return (
+    <article>
+      <h1>{greeting}</h1>
+      <p><T id="home.tagline" /></p>                          {/* JSX form */}
+      <p><T id="home.activeLocale" values={{ locale: useLocale().toUpperCase() }} /></p>
+    </article>
+  )
+}
+```
+
+## The layout — inner URL-driven provider + language switch
+
+`src/pages/layout.tsx` wraps every page in an **inner** `<I18nProvider>` whose locale comes from `useUrlLocale()`. Because `useLocation` re-renders on client-side navigation, moving between `/about` and `/de/about` swaps the catalog without a full reload; at build time it resolves to the same locale the SSG pipeline pre-rendered. The language switch is a set of plain `<a>` links — one per locale, pointing at the current path under each prefix.
+
+```tsx
+// src/pages/layout.tsx (excerpt)
+import { I18nProvider, T } from '@voltro/i18n'
+import { useLocation } from '@voltro/web'
+import { CATALOGS, DEFAULT_LOCALE, SUPPORTED_LOCALES, stripLocalePrefix, useUrlLocale, withLocalePrefix } from '../lib/locale'
+
+export default function Layout({ children }) {
+  const locale = useUrlLocale()
+  const barePath = stripLocalePrefix(useLocation())   // keep the page when switching language
+  return (
+    <I18nProvider locale={locale} messages={CATALOGS[locale]} defaultLocale={DEFAULT_LOCALE}>
+      <nav>
+        {SUPPORTED_LOCALES.map((code) => (
+          <a key={code} href={withLocalePrefix(barePath, code)} aria-current={code === locale ? 'true' : undefined}>
+            {code.toUpperCase()}
+          </a>
+        ))}
+      </nav>
+      <main>{children}</main>
+    </I18nProvider>
+  )
+}
+```
+
+The nav uses plain `<a>` (not `<Link>`) on purpose: the hrefs are *computed* per locale, and `<Link to>` wants a statically-known route URL. The Router's global click interceptor SPA-navigates internal `<a>` anyway, so the inner provider still swaps catalogs without a reload.
+
+## Config — `locales` + `defaultLocale`
+
+`locales` in `app.config.ts` is load-bearing: it tells `voltro build` to pre-render a per-locale variant for every `[locale]/...` mirror, each wrapped in the right catalog's provider. Every code listed MUST have a matching `src/locales/<code>.ts`, and `defaultLocale` MUST be one of `locales`. Keep these two fields in sync with `SUPPORTED_LOCALES` / `DEFAULT_LOCALE` in `src/lib/locale.ts`.
+
+```ts
+// app.config.ts
+export default {
+  type: 'web' as const,
+  name: 'AcmeSite',
+  port: 5173,
+  theme: 'system' as const,
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  env,
+}
+```
+
+## Build + serve
+
+```bash
+voltro build .     # pre-render → one HTML file per (page × locale)
+voltro start .     # serve the built output locally
+```
+
+The build emits the URL-prefixed tree:
+
+```text
+dist/index.html            ← en (default, bare path)
+dist/about/index.html      ← en
+dist/de/index.html         ← de mirror
+dist/de/about/index.html   ← de mirror
+```
+
+Each variant ships its localised body AND the right per-locale `<title>` / `<meta description>`. The output is pure static files — push it to any CDN.
+
+## Add a locale
+
+1. Add the code to `SUPPORTED_LOCALES` in `src/lib/locale.ts` AND to `locales` in `app.config.ts`.
+2. Add `src/locales/<code>.ts` (mirror `en.ts`; the type-check enforces parity), and add it to `CATALOGS` in `src/lib/locale.ts`.
+
+The `[locale]` mirrors pick it up automatically — `getStaticPaths` reads `SUPPORTED_LOCALES`.
+
+## When to use frontend-i18n vs. the other web templates
+
+| You want… | Pick |
+|---|---|
+| A multilingual content/marketing site where each language is its own crawlable URL | `frontend-i18n` |
+| A single-language content site pre-rendered to flat HTML | [`frontend-static-blog`](/docs/templates/static-blog) |
+| A documentation site | [`frontend-docs`](/docs/templates/docs) |
+| A blank React shell to bring your own brand | [`frontend-blank`](/docs/templates/blank) |
+| A product app where all locales share one URL (cookie-driven) | any web template + `locales` in `app.config.ts` (Strategy A) |
+
+## Pairs well with
+
+- **Nothing on the backend** — this is a self-contained static site. Add an api later (and an `apis:` entry) only when a page needs live, request-time data, then flip that page to `renderMode: 'ssr' | 'isr'`.
+- The **cookie-only** i18n strategy (Strategy A) for sibling *product* apps where the URL shouldn't encode the language — same catalogs, no `[locale]` mirrors. See [URL strategies](/docs/i18n/url-strategies) for both.
+
+## 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.
+- **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.
+- **Reading the cookie directly in a component.** Use `useT` / `useLocale` — the active locale is React state inside the provider, not browser state. Reaching for `document.cookie` re-introduces the hydration flash the framework is designed to avoid.
+
+
+
+---
+
+<!-- source: en/templates/dashboard.md -->
+## Dashboard
+
+_An authenticated dashboard shell — a silent (marketing) route group for public pages, a /dashboard area gated by a nested layout loader that RedirectErrors to /login when there's no session, and scoped error/loading/not-found special files. SSR auth gate, no backend._
+
+The app shell every SaaS frontend needs: a public marketing area and an authenticated dashboard, with the auth gate done right. Public pages live in a **silent route group** (`(marketing)/` — organises files + scopes a layout without adding a URL segment). The `/dashboard` area is gated by a **nested layout loader** that runs once for every page beneath it, server-side, and `throw`s `RedirectError('/login')` when there's no session — so an unauthenticated visitor is bounced before any dashboard HTML renders. The authed pages are `renderMode: 'ssr'` precisely so the gate runs per request. The gate is a cookie-only stand-in, so the template boots with **no backend**. Template id: **`frontend-dashboard`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --web=frontend-dashboard
+voltro add-app app --template=frontend-dashboard --to acme
+```
+
+## What ships
+
+```text
+apps/acme/web/                          # dir named by the app, not the template
+├── app.config.ts                       # type:web, theme:'system', defineEnv (public-only)
+├── package.json
+├── tsconfig.json
+├── README.md
+└── src/
+    ├── globals.css
+    ├── globals.d.ts                     # `declare module '*.css'`
+    ├── config.ts                        # APP_NAME brand constant
+    ├── lib/
+    │   └── auth.ts                      # the cookie-only demo gate (readCookie + isSignedIn)
+    └── pages/
+        ├── layout.tsx                   # thin root layout (loads the stylesheet)
+        ├── (marketing)/                 # SILENT route group → URLs have NO group segment
+        │   ├── layout.tsx               # marketing header/footer chrome
+        │   ├── index.tsx                # /        — public landing (static)
+        │   └── login.tsx                # /login   — sets the demo session cookie
+        └── dashboard/                   # real /dashboard prefix
+            ├── layout.tsx               # THE AUTH GATE — loader + RedirectError + shared data
+            ├── error.tsx                # scoped error boundary
+            ├── loading.tsx              # scoped opt-in skeleton
+            ├── not-found.tsx            # scoped 404
+            ├── index.tsx                # /dashboard          — overview (ssr)
+            └── settings.tsx             # /dashboard/settings — settings (ssr)
+```
+
+The app depends only on `@voltro/web` / `@voltro/client` / `@voltro/env` / `@voltro/cli` + React 19 — no api, no rpc client.
+
+## Two route shapes — silent group vs real prefix
+
+`src/pages/(marketing)/` is a **route group**: the parentheses organise files and scope a layout, but the directory name **never appears in a URL**. So the pages inside are `/` and `/login` — not `/(marketing)/...`. Use a group when you want a shared layout (here: the marketing header) for a set of pages without inventing a URL segment for it.
+
+`src/pages/dashboard/` is an ordinary directory, so it DOES contribute a URL segment — `/dashboard`, `/dashboard/settings`. The contrast is the point: a group for cross-cutting layout scoping, a real dir when you want the prefix.
+
+## The auth gate — a nested layout loader
+
+A `layout.tsx` can export a `loader`, just like a page. The framework runs it once for every page beneath that directory, **in parallel with the page loader, server-side, before render**. That makes the dashboard layout's loader the one right place to validate the session and preload shared data:
+
+```tsx
+// src/pages/dashboard/layout.tsx
+import { RedirectError, useLoaderData, type LoaderFn } from '@voltro/web'
+import { isSignedIn } from '../../lib/auth'
+
+interface DashboardData {
+  readonly user: { readonly name: string; readonly plan: string }
+}
+
+export const loader: LoaderFn<DashboardData> = async ({ headers }) => {
+  if (!isSignedIn(headers)) {
+    // No session → bounce to login, remembering where they were headed.
+    throw new RedirectError('/login?from=/dashboard')
+  }
+  // Shared data, loaded ONCE for every page beneath this layout, read via
+  // useLoaderData<DashboardData>() right here in the layout.
+  return { user: { name: 'Demo User', plan: 'Pro' } }
+}
+
+export default function DashboardLayout({ children }) {
+  const { user } = useLoaderData<DashboardData>()
+  // … sidebar + topbar showing `user`, then {children} …
+}
+```
+
+`RedirectError` is loader control-flow, NOT an error-boundary error: on SSR it emits a `303` + `Location`; on a client navigation it does `navigate(location, { replace: true })` so Back doesn't bounce onto the redirecting page. (Its sibling `NotFoundError` renders the scoped `not-found.tsx` instead.)
+
+## Why the dashboard pages are `renderMode: 'ssr'`
+
+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
+export const renderMode = 'ssr' as const
+export const meta = { title: 'Overview' }
+export default function Overview() { /* … */ }
+```
+
+The public marketing pages stay `static` (pre-rendered, CDN-friendly) — only the gated area pays for SSR.
+
+## The demo gate — cookie-only, zero backend
+
+`src/lib/auth.ts` is a deliberate stand-in so the template boots with nothing wired. It reads a cookie from **both** places the gate runs — the request `Cookie` header on SSR, and `document.cookie` on a client navigation (where the loader's `headers` is undefined):
+
+```ts
+// src/lib/auth.ts
+export const SESSION_COOKIE = 'demo_session'
+
+export const isSignedIn = (headers: Record<string, string | undefined> | undefined): boolean => {
+  const cookieHeader = headers?.['cookie'] ?? (typeof document === 'undefined' ? '' : document.cookie)
+  return readCookie(cookieHeader, SESSION_COOKIE) !== undefined
+}
+```
+
+`/login` writes that cookie (a real app POSTs credentials to an api that returns a signed, HttpOnly cookie). Swap `isSignedIn` for your real check — verify a signed session, or call your api — and the rest of the shell is unchanged.
+
+## Scoped special files
+
+Three files under `dashboard/` apply to every page in that subtree:
+
+- **`error.tsx`** — an error boundary. A render error (or a loader rejection that ISN'T a `RedirectError` / `NotFoundError`) bubbles to the nearest `error.tsx` instead of the router default. `reset` re-runs the failed segment.
+- **`loading.tsx`** — an OPT-IN skeleton. By default navigation is deferred (the previous page stays until the loader settles); adding `loading.tsx` opts this subtree into swapping in immediately and showing a skeleton — which suits a data-backed dashboard.
+- **`not-found.tsx`** — a scoped 404. On a client navigation to an unmatched `/dashboard/...` URL the router renders this; a direct request to such a URL returns a `404`.
+
+## Build + serve
+
+```bash
+voltro build .     # static marketing pages + an SSR bundle for /dashboard
+voltro start .     # serve: / + /login are static; /dashboard renders per request
+```
+
+`voltro start` returns `303 → /login?from=/dashboard` for `/dashboard` without a session cookie, and `200` once the cookie is set — the gate in action.
+
+## Wire a real backend
+
+Add an api and an `apis:` entry in `app.config.ts`, then read live data in the dashboard pages with `useSubscription`. The gate stays the same — only its session check moves from the demo cookie to your real session. For the gate's own session verification, see the [Sessions guide](/docs/authentication/sessions).
+
+## When to use frontend-dashboard vs. the other web templates
+
+| You want… | Pick |
+|---|---|
+| An authenticated app shell — public pages + a gated dashboard | `frontend-dashboard` |
+| The reactive end-to-end loop (frontend wired to an api) | [`frontend-app`](/docs/templates/app) |
+| Server-rendered / cached pages without an auth gate | [`frontend-ssr`](/docs/templates/ssr) |
+| A blank React shell to bring your own brand | [`frontend-blank`](/docs/templates/blank) |
+
+## Pairs well with
+
+- **Any api template** — drop one in, add an `apis:` entry, and the dashboard pages become live. [`api-auth`](/docs/templates/api-auth) is the natural partner: replace the demo cookie with its real session, and `isSignedIn` becomes a real verification.
+
+## Anti-patterns
+
+- **Making the gated pages `static`.** A `static` page renders once at build time — the loader can't redirect per visitor, and the build rejects a `RedirectError`. Gated pages are `renderMode: 'ssr'` (or `'isr'` if the content is cacheable and not per-subject).
+- **Putting the gate in each page's loader.** The whole point of the layout loader is that it runs once for every page beneath it. Duplicating the session check in each page is the bug the nested layout loader exists to avoid.
+- **Reading only `headers` in the gate.** `headers` is populated server-side; on a client navigation it's undefined. Fall back to `document.cookie` (or your client-side session source) so the gate works on SPA navigation too — otherwise a client nav into the dashboard always bounces to `/login`.
+- **Trusting an unsigned cookie in production.** The demo cookie is a stand-in. A real gate verifies a *signed* session (or calls the api) — a bare `present/absent` cookie check is forgeable. See the [Sessions guide](/docs/authentication/sessions).
+- **Throwing a plain `Error` for redirects.** A plain `throw new Error()` hits the `error.tsx` boundary. Control-flow redirects use `RedirectError` / `redirect()`; 404s use `NotFoundError` / `notFound()`.
+
+
+
+---
+
+<!-- source: en/templates/ssr-api.md -->
+## SSR + api
+
+_Server-rendered pages fed by a sibling api — an `ssr` loader calls `query('notes.list', {})` over the api's POST /rpc so real rows are in the first paint and the <title>, then useSubscription upgrades the same data to live. Pairs with api-backend._
+
+The SSR-from-your-backend shape: a page that server-renders **real api data** into the first paint. The index page is `renderMode: 'ssr'`, and its loader runs on the server on every request, calling `query('notes.list', {})` over the api's `POST /rpc` surface — so the rows AND the document `<title>` are correct in the HTML before it's sent (crawlable, no client round-trip). The component then upgrades the same data to live with `useSubscription`. This is the piece [`frontend-ssr`](/docs/templates/ssr) leaves out — that template shows the `ssr` / `isr` mechanics but computes its data locally; this one wires the loader to a real sibling api. Template id: **`frontend-ssr-api`**.
+
+## Scaffold — pairs with an api
+
+This template consumes an api exposing `notes.list`. Scaffold both:
+
+```bash
+voltro create-project acme --api=api-backend --web=frontend-ssr-api
+voltro add-app web --template=frontend-ssr-api --to acme
+```
+
+## What ships
+
+```text
+apps/acme/web/                          # dir named by the app, not the template
+├── app.config.ts                       # type:web, theme:'system', apis: { app }
+├── package.json                        # + @acme/api (workspace:*)
+├── tsconfig.json
+├── README.md
+└── src/
+    ├── globals.css
+    ├── globals.d.ts                     # `declare module '*.css'`
+    └── pages/
+        ├── layout.tsx
+        └── index.tsx                    # renderMode:'ssr' — loader query() + useSubscription
+```
+
+The only addition over a standalone web template is the api dependency: `package.json` declares `@acme/api` and `app.config.ts` names it under `apis`.
+
+## Wiring the api — `apis` in `app.config.ts`
+
+```ts
+// app.config.ts
+export default {
+  type: 'web' as const,
+  name: 'AcmeWeb',
+  port: 5173,
+  // The NAME ('app') is the lookup key the loader's `query` + the hooks use.
+  // The `package` resolves the sibling api in this project; its port is
+  // auto-discovered from its own app.config.ts, and codegen pulls its typed
+  // rpc surface so `query` + `useSubscription` are end-to-end typed.
+  apis: { app: { package: '@acme/api' } },
+}
+```
+
+## The SSR loader — `query()` over POST /rpc
+
+`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
+import { useLoaderData, type LoaderFn, type PageMeta } from '@voltro/web'
+import { useSubscription } from '@voltro/client'
+
+interface Note { readonly id: string; readonly title: string; readonly body: string; readonly done: boolean }
+interface HomeData { readonly notes: ReadonlyArray<Note> }
+
+export const renderMode = 'ssr' as const
+
+export const loader: LoaderFn<HomeData> = async ({ query }) => ({
+  // Pass the row type so the result is typed without importing the api.
+  notes: query ? await query<ReadonlyArray<Note>>('notes.list', {}) : [],
+})
+
+export const meta = ({ loaderData }: { loaderData: HomeData }): PageMeta => ({
+  title: `${loaderData.notes.length} notes — Acme`,
+  description: 'Server-rendered from the api on every request.',
+})
+```
+
+`query?.(...)` is guarded because `query` is `undefined` for client-side loader invocations — only rely on it under `renderMode: 'ssr' | 'isr'`.
+
+## SSR → live, one data source
+
+The component renders the SSR'd snapshot, then `useSubscription` upgrades it to live once the WebSocket connects. During SSR `useSubscription` returns `undefined`, so the first paint is the loader's data; it swaps to live on the client — no flash, one data source:
+
+```tsx
+export default function Home() {
+  const { notes: initial } = useLoaderData<HomeData>()
+  const { data: live } = useSubscription<ReadonlyArray<Note>>('app', 'notes.list')
+  const notes = live ?? initial
+  return <ul>{notes.map((n) => <li key={n.id}>{n.title}{n.done ? ' ✓' : ''}</li>)}</ul>
+}
+```
+
+## Build + serve
+
+```bash
+voltro build .     # codegen pulls the api's rpc types + builds an SSR bundle
+voltro start .     # the loader hits the api per request; the api must be running
+```
+
+`voltro start` renders the page server-side on each request, so the api has to be up (start it alongside the web). Unlike a `static` page, there's no pre-rendered HTML — the point is fresh, per-request data.
+
+## SSR vs the other render modes
+
+| The page's data… | Use | Template |
+|---|---|---|
+| Must hit the api per request (per-subject, always fresh) | `renderMode: 'ssr'` | `frontend-ssr-api` (this) |
+| Changes occasionally + can be cached | `renderMode: 'isr'` + `revalidate` | same loader, cached HTML |
+| Is fully client-reactive (no SSR needed) | `useSubscription` in a default page | [`frontend-app`](/docs/templates/app) |
+| Is computed locally / needs no backend | `ssr` with a local loader | [`frontend-ssr`](/docs/templates/ssr) |
+
+## When to use frontend-ssr-api vs. the other web templates
+
+| You want… | Pick |
+|---|---|
+| Server-rendered pages whose first paint + `<title>` come from real api data | `frontend-ssr-api` |
+| The reactive end-to-end loop with client-side rendering | [`frontend-app`](/docs/templates/app) |
+| SSR / ISR mechanics without a backend | [`frontend-ssr`](/docs/templates/ssr) |
+| An auth-gated app shell | [`frontend-dashboard`](/docs/templates/dashboard) |
+
+## Pairs well with
+
+- [`api-backend`](/docs/templates/api-backend) — the documented partner; it exposes the `notes.list` query this loader calls. Any api with a streaming query works — point the loader's tag at it.
+
+## Anti-patterns
+
+- **Relying on `query` outside `ssr` / `isr`.** It's `undefined` for client-side loader runs. Guard with `query?.(...)`, and fetch live data in the component with `useSubscription` — not in a client-side loader.
+- **Using the loader result as the live source.** The loader runs once per request; for updates after first paint, subscribe in the component. The pattern is SSR'd snapshot → `useSubscription` upgrade, with `live ?? initial`.
+- **Making the page `static`.** A `static` page's loader runs at build time with no per-request render and no `query` — it can't read per-request api data. If the HTML must reflect current rows, it's `ssr` (or `isr` for cached-with-revalidation).
+- **Importing the api's VALUE exports into the page.** A type-only `import type { Note } from '@acme/api/database'` is browser-safe; importing values pulls server-only modules into the browser bundle. This template keeps a local `Note` interface to stay self-contained.
+
+
+
+---
+
+<!-- source: en/templates/admin.md -->
+## Admin
+
+_An auto-admin back-office that discovers your api's entities at runtime (capability map) and renders a live, reactive, permission-gated CRUD view per entity — DataTable + AutoForm + provenance + undo, assembled from shipped primitives as editable template code._
+
+The back-office, done for you — without a sealed generated cage. The admin reads your api's **capability map** (`/_voltro/inspect/manifest`) at runtime and renders a live, reactive view for every entity it exposes: a `<DataTable>` over the list query and an `<AutoForm>` over the create mutation, columns and fields straight from the descriptors' schemas. Point it at **any** Voltro api and the sidebar + pages adapt — there's no per-entity code. And it's **editable template code you own**, not a runtime feature (the lesson of the schema-driven-UI graveyard). Template id: **`frontend-admin`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-backend --web=frontend-admin
+voltro dev   # the admin discovers api-backend's entities
+```
+
+Sign in at `/login` (a demo cookie gate) → `/admin`.
+
+## How discovery works
+
+The sidebar and every entity page are driven by two `@voltro/client` exports:
+
+```tsx
+import { useCapabilityManifest, deriveEntityAdmins } from '@voltro/client'
+
+const { manifest } = useCapabilityManifest('app')   // one-shot fetch of the capability map
+const entities = manifest ? deriveEntityAdmins(manifest) : []
+// each entity: { table, columns, listTag?, createTag?, updateTag?, deleteTag?, createScope, writeScope, deleteScope }
+```
+
+`deriveEntityAdmins` joins each user table to the procedures that actually serve it — the query whose `source` is the table (→ the list `<DataTable>`), the mutations whose `target` is `{table, op}` (→ create/edit/delete). So the admin binds only to procedures that **exist**; it never guesses tags by naming convention.
+
+## Per-entity CRUD
+
+```tsx
+// src/pages/admin/[entity].tsx (abridged)
+const canCreate = useCan(spec.createScope)         // <table>:create
+{spec.createTag && canCreate ? (
+  <AutoForm api="app" mutation={spec.createTag} submitLabel={`Add ${spec.table}`} />
+) : null}
+
+{spec.listTag ? (
+  <DataTable api="app" query={spec.listTag} rowActions={rowActions} />
+) : null}
+```
+
+The list is a **live subscription** — a create from the form (or anyone, in another tab) appears without a refetch. Each row's actions include a delete (gated by `useCan(spec.deleteScope)`, run via `useMutation(spec.deleteTag)`) and a **provenance** drawer (`useProvenance`) answering "why is this row here?".
+
+## Permission gating
+
+Write affordances are hidden via `useCan` on conventional per-entity scopes (`<table>:create`, `<table>:delete`). `<PermissionProvider>` in the admin layout feeds the current subject's scopes; the demo seeds `admin:full` (bypass) — **swap it for your session's real scopes**:
+
+```tsx
+const { data } = useSubscription<{ scopes: string[] }>('app', 'auth.session')
+<PermissionProvider scopes={data?.scopes ?? []}>…</PermissionProvider>
+```
+
+This is UX gating, not enforcement — the api's own `permission()` guards remain the real authorization boundary. Row-level field visibility (vs. action-level) is a future step.
+
+## Undo / redo
+
+The topbar's undo bar wraps the framework's built-in undo (`useUndoLog('app')` → the `__voltro.undo.*` built-ins): revert the last change across the whole admin, server-persisted so it survives reload. It requires undo capture on (`VOLTRO_UNDO`, on by default in dev); if you run with it off, delete the `UndoBar` lines.
+
+## What ships
+
+```text
+apps/acme/web/
+├── app.config.ts            # type:web, apis:{ app } — the api the admin introspects
+└── src/
+    ├── config.ts            # APP_NAME
+    ├── lib/{auth,admin}.ts  # demo cookie gate + demo scopes (both swap for real)
+    └── pages/
+        ├── (marketing)/     # silent group — public landing + /login
+        └── admin/           # /admin SSR gate (layout loader → RedirectError)
+            ├── layout.tsx    # auth gate + capability-map nav + PermissionProvider + undo bar
+            ├── index.tsx     # entity overview cards
+            ├── [entity].tsx  # the per-entity CRUD binding
+            └── error|loading|not-found.tsx
+```
+
+## 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.
+
+## When to use frontend-admin vs. the other web templates
+
+| You want… | Pick |
+|---|---|
+| A back-office over your api's entities, done for you | `frontend-admin` |
+| An authenticated app shell (public + gated dashboard), no backend | [`frontend-dashboard`](/docs/templates/dashboard) |
+| The reactive end-to-end loop (one entity, hand-wired) | [`frontend-app`](/docs/templates/app) |
+
+## Pairs well with
+
+- **Any api template** — the admin adapts to whatever entities + procedures it exposes. [`api-data-advanced`](/docs/templates/api-data-advanced) (authors + books) shows it rendering related entities; [`api-rbac`](/docs/templates/api-rbac) supplies real scopes for the gating.
+
+## Anti-patterns
+
+- **Shipping the demo `admin:full` scopes to production.** That bypasses every `useCan` gate. Feed the subject's real scopes to `<PermissionProvider>`.
+- **Treating `useCan` as authorization.** It hides buttons; the server's `permission()` guard is the real gate. A hidden action is still callable over rpc by a crafted client.
+- **Assuming a naming convention.** The admin binds to discovered tags, not `<table>.create`-style guesses — so it works even when your procedures are named differently.