@voltro/cli 0.53.0 → 0.55.0

package/templates/agent-docs/reference.md

@@ -61,6 +61,8 @@ these before hand-rolling a form, a table, or a picker** — full guide in
 | Hook | Purpose |
 |---|---|
 | [`useFormBinding`](/docs/ui/forms-and-tables) | Bind a form to a MUTATION — fields + validation from its input Schema; a server `ValidationError({ field })` routes to that field. |
+| [`useFormField`](/docs/ui/forms-and-tables) | One field of the enclosing binding — value, blur, the display-gated error, a11y props. Re-renders that field alone. |
+| [`useFormBindingContext`](/docs/ui/forms-and-tables) | The binding a `<FormBindingProvider>` (or `<AutoForm>`) mounted above — for a widget kit that needs the form itself, not one field. |
 | [`useDataTable`](/docs/ui/forms-and-tables) | Bind a table to a QUERY — live rows, columns derived from the output Schema, sort/filter/pagination. |
 | [`useQueryFilters`](/docs/ui/forms-and-tables) | Filter controls derived from a query's INPUT Schema (the read-side mirror of a form). |
 | [`useQueryField`](/docs/ui/forms-and-tables) | Query-bound picker — a debounced search term drives a live subscription. |
@@ -68,12 +70,14 @@ these before hand-rolling a form, a table, or a picker** — full guide in
 | [`useAsyncValidation`](/docs/ui/client-utilities/use-async-validation) | Live server-side validation (uniqueness, cross-row) over a query binding. |
 | [`useDebounced`](/docs/ui/client-utilities/use-debounced) | Debounce a value (search, filter, validation input). |
 | [`useRecord`](/docs/ui/client-utilities/use-record) | One live record from a "get" query, normalized (array → first row). |
+| [`useValidationMessages`](/docs/ui/forms-and-tables) | The app-wide validation-message resolver from `<ValidationMessagesProvider>`, or `undefined` when none is mounted — for a widget kit that resolves message ids itself. |
 
 ## Files, Permissions, and Client Utilities
 
 | Hook | Purpose |
 |---|---|
 | [`useUpload`](/docs/plugins/storage) | File upload with progress + cancel, on every storage provider. Not base64 → action. |
+| [`usePresenceChannel`](/docs/local-first/overview) | One presence wire for local-first: the peer roster plus a `publish`/`subscribe` pair for ephemeral payloads (cursors, typing), riding the existing presence lane rather than a second socket. Room-scoped — a mismatched room throws instead of delivering across rooms. |
 | [`useCan`](/docs/ui/client-utilities/use-can) | Scope/RBAC UI gate, over `<PermissionProvider>`. Lives in `@voltro/client` — scopes are a framework concept, so gating a button needs no rbac dependency. |
 | [`useCanAny`](/docs/ui/client-utilities/use-permissions) | OR variant of `useCan` — true when the subject holds AT LEAST ONE of the required scopes. |
 | [`usePermissions`](/docs/ui/client-utilities/use-permissions) / `<PermissionProvider>` | The current subject's scope set, fed once from your session query — the source `useCan` reads. Gates UI on the SAME scope strings the server checks. |
@@ -97,6 +101,23 @@ these before hand-rolling a form, a table, or a picker** — full guide in
 | [`useResumableAgentStream`](/docs/ai/streaming) | Agent stream that survives reload/reconnect. |
 | [`useDataCopilot`](/docs/ai/data-copilot) | Bind a data-copilot action by api name + tag. |
 
+## Plugin and Local-First Hooks
+
+Shipped by an installed plugin or by `@voltro/local-first`, not by
+`@voltro/client` — the import path is the package, and each takes the api name
+as its last argument (default `'app'`). The rest of the surface reads exactly
+like the hooks above.
+
+| Hook | Package | Purpose |
+|---|---|---|
+| [`useWebPush`](/docs/plugins/notifications) | `@voltro/plugin-notifications/web` | Web-push permission flow, service-worker registration and subscribe/unsubscribe — `{ status, error?, subscribe, unsubscribe }`, where `status` distinguishes `unsupported` / `denied` / `subscribed` for THIS browser. |
+| [`useComments`](/docs/plugins/comments) | `@voltro/plugin-comments/web` | The live threads on one anchor plus every action on them (`create`, `edit`, `resolve`, `remove`, `react`, `markRead`) and the unread badge count. |
+| [`useThread`](/docs/plugins/comments) | `@voltro/plugin-comments/web` | One thread by id — a projection over the same live list, so it opens no second subscription. |
+| [`useMentionSearch`](/docs/plugins/comments) | `@voltro/plugin-comments/web` | `@`-mention autocomplete over the app-declared, tenant-filtered directory. |
+| [`useCrdtText`](/docs/local-first/overview#a-collaborative-text-field-usecrdttext) | `@voltro/local-first/react` | A collaborative text field bound to one `crdtText()` cell — merged text, minimal-span edits, the offline queue and `synced`. |
+| [`useCrdtDoc`](/docs/local-first/overview#rich-text-crdtdoc-usecrdtdoc-usecrdteditor) | `@voltro/local-first/react` | The sync half of a `crdtDoc()` column — one `SyncClient` + one live CRDT document per cell, with the echo guard that keeps a folded remote update from being pushed back. Hands the document to `useCrdtEditor`. |
+| [`useCrdtEditor`](/docs/local-first/overview#rich-text-crdtdoc-usecrdtdoc-usecrdteditor) | `@voltro/local-first/editor` | A collaborative rich-text editor over a `crdtDoc()` column — one Tiptap instance bound to the shared document, carets bridged over an injected transport. |
+
 ## Where To Read Next
 
 - [Data hooks](/docs/reference/hooks-data)
@@ -210,9 +231,9 @@ type TeamsState = SubscriptionState<ReadonlyArray<Team>> & { readonly canEdit: b
 ```
 
 `loading` means **no data has arrived yet**, not "the subscription is still
-warming up". A cold-start failure leaves `loading` true and sets `error`, so a
-component branching on `loading` alone renders a skeleton forever — check
-`error`.
+warming up". A cold-start failure is its own state — `loading: false`,
+`failed: true`, `error` non-optional — so branching on `loading` alone is safe;
+render the failure off `failed`.
 
 Use `{ skip }` to defer until inputs are ready:
 
@@ -228,7 +249,7 @@ const { data } = useSubscription(
 ### Offline semantics with the local-first mirror
 
 With `@voltro/local-first`'s query mirror bound (see
-[the sync engine](/docs/local-first/overview#the-sync-engine-query-mirror--durable-outbox)),
+[the sync engine](/docs/local-first/overview#the-sync-engine-query-mirror-durable-outbox)),
 `useSubscription`'s behaviour extends offline WITHOUT a second API: a cold
 start seeds `data` (and `revision`) from the device's mirrored rows for the
 subject's partition, so `loading` resolves against local data when the server

package/templates/agent-docs/routing.md

@@ -207,6 +207,24 @@ src/pages/users/new/page.tsx        # /users/new → wins (static beats dynamic)
 src/pages/[...rest]/page.tsx        # everything else
 ```
 
+## Development mounts in React `StrictMode`
+
+The client entry wraps the tree in `StrictMode`, so **in development every
+effect runs twice, with a real unmount in between**. That is the point — it
+surfaces effects that are not safe to re-run — but it has one consequence
+worth stating outright, because it is expensive to rediscover:
+
+**An effect that keys off "have I mounted before?" fires on the second mount.**
+A deployment measured this as a picker that cleared its own just-loaded value:
+a "when the dependency changes, clear the selection" effect built on a
+mount-counting ref saw the second mount as a change, and an edit form opened
+with an empty required field and a red message while the record had the value.
+Visible only in development, which is exactly where it reads as a data bug.
+
+The rule that survives the double mount: **compare VALUES, not runs.** A reset
+that fires because "this is not the first run" is a reset waiting for the next
+remount; one that fires because the dependency actually differs is not.
+
 ## Query strings
 
 Query params are orthogonal to the URL pattern — they never appear in the file path. A page declares its query contract as a **`searchParams` schema export**, the same page-export convention as `meta`, `loader`, and `renderMode`:
@@ -245,6 +263,36 @@ export { searchParams } from '../../search/page'
 
 One schema, no drift — the mirror page decodes exactly what the original declares.
 
+**Two scanners read this line, and they do not agree.** The isr refusal above is a
+source scan, and so is the route-builder codegen that brands a route's URL with its
+searchParams type — but they recognise different spellings, which is worth knowing
+before you pick one:
+
+| spelling on the mirror page | typed `withQuery` on the mirror route | `isr` + schema refused |
+| --- | --- | --- |
+| `export const searchParams = …` | yes | yes |
+| `export { searchParams } from '../../search/page'` | **no** | yes |
+| `export * from '../../search/page'` | **no** | **no** |
+| `import { searchParams as base } …` + `export const searchParams = base` | yes | yes |
+
+The middle two are the ones to watch. A clause re-export still decodes correctly at
+runtime and is still refused on `isr` — but the route builder does not see it, so
+`withQuery` on the mirror's URL falls back to untyped and nothing reports it. A star
+re-export is seen by neither: the binding is on the module at runtime (`export *`
+forwards every named export), so the page behaves as if it declared a schema while
+the `isr` refusal never fires.
+
+So: prefer the last row when you want the mirror route's links type-checked, and
+never reach a schema through `export *` on an `isr` page.
+
+```tsx
+// src/pages/[locale]/search/page.tsx — one schema, and both scanners see it
+import { searchParams as base } from '../../search/page'
+
+export const searchParams = base
+export { default } from '../../search/page'
+```
+
 ### Routes without a schema
 
 `useSearchParams()` without an argument stays the raw `URLSearchParams` — nothing changes for a route that declares no schema:
@@ -521,7 +569,7 @@ export const renderMode = 'static' as const   // 'static' | 'spa' | 'ssr' | 'isr
 | `ssr` | Every request | Never | Authenticated dashboards, search results, anything cookie-driven |
 | `isr` | First request after build, then on revalidate | Per-key in-memory or Postgres | News feeds, listings, dashboards that change but not per-user |
 
-Those four are the **complete** set. An unrecognised value is a hard error naming the page — see [What doesn't work](#what-doesnt-work).
+Those four are the **complete** set. An unrecognised value is a hard error naming the page — see [What doesn't work](#what-doesn-t-work).
 
 ## static (SSG)
 
@@ -2062,7 +2110,7 @@ export const interactive = 'islands' as const
 
 With `interactive: 'islands'`, the page's HTML is server-rendered and its script tag points at the page's own entry. That entry registers the page's islands, scans for island markers, and hydrates each one on its own schedule — the page component itself never runs in the browser.
 
-Looking for Astro's **"Server Islands"** — per-request-rendered holes in otherwise static pages? In Voltro that is planned as **partial prerendering (PPR)**, not part of islands mode.
+Looking for Astro's **"Server Islands"** — per-request-rendered holes in otherwise static pages? In Voltro that is [**partial prerendering (PPR)**](/docs/routing/render-modes#partial-prerendering-ppr-cached-shell-per-request-holes): `ppr = true` on an `isr` page, a separate mechanism from islands mode. The two do not combine — ppr reveals its holes through hydration, so it requires `interactive: 'full'`.
 
 ## When to use islands
 
@@ -2449,9 +2497,14 @@ passthrough.
   this path; for `?image` assets quality is baked at build time from
   `images.quality`.
 - **Remote images** — same: loader seam, not the build pipeline.
-- **Markdown-content images** (a blog's relative references) — copied +
-  hashed by the content pipeline; build-time transformation for those is a
-  named non-goal for now.
+- **Markdown-content images** (a blog's relative references) — copied into
+  `dist/assets/content-media/<hash>.<ext>` by the content pipeline and the
+  `src` rewritten to that URL. A relative source resolves against the markdown
+  file that references it, and one that does not exist FAILS the build naming
+  the path — a page that renders while its image 404s is the outcome this
+  replaces. Absolute (`/…`) and remote sources are left untouched. Build-time
+  TRANSFORMATION (resize / format) stays a named non-goal here: a markdown
+  reference carries no width and no `sizes` to derive one from.
 
 ## `<Image>` without the pipeline
 
@@ -2730,7 +2783,7 @@ Two boundaries, stated rather than implied:
 
 ## A per-request CSP nonce — `cspNonce`
 
-Return `cspNonce` and the framework stamps `nonce="…"` onto every script tag of that render — the state script, the deferred registry, the shell's bundle tags, and React's own bootstrap/settle scripts (via React's nonce support). The POLICY header stays yours: set it via `responseHeaders`, with the same nonce.
+Return `cspNonce` and the framework stamps `nonce="…"` onto every script tag of that render — the state script, the deferred registry, the shell's bundle tags, the islands entry, and React's own bootstrap and Suspense scripts (via React's nonce support). The POLICY header stays yours: set it via `responseHeaders`, with the same nonce.
 
 ```ts
 import { randomBytes } from 'node:crypto'
@@ -2751,7 +2804,9 @@ export const csp = defineMiddleware({
 ```
 
 - **`isr` + `cspNonce` refuses the render, loudly.** A cached nonce is a lie the browser enforces — the second visitor gets HTML whose nonce the policy header no longer matches. The ways out: `ssr` for nonce'd pages, or a hash-based CSP for `isr`.
-- The PPR variant of that question is open until partial prerendering exists; a component for client-injected script tags (a `Script` component) is planned.
+- **`ppr` is refused for the same reason.** A [partial-prerendered](/docs/routing/render-modes#partial-prerendering-ppr-cached-shell-per-request-holes) page serves a cached shell whose inline registry scripts cannot carry a per-request nonce, so `cspNonce` on a `ppr` page is refused by name — same ways out as `isr`.
+- **Client-injected script tags carry the nonce too.** [`<Script>`](/docs/routing/third-party-scripts) propagates the DOCUMENT's own nonce onto the tag it injects, so a nonce'd `ssr` page needs no explicit `nonce` prop.
+- **`defer()` does not yet compose with `cspNonce`.** The settle `<script>` each [`<Await>`](/docs/routing/loaders-and-meta) boundary emits inside the streamed body is part of the RENDERED TREE — it is not one React injects, so React's nonce support does not reach it, and it is not in the `<head>` the framework stamps. Under `script-src 'nonce-…'` the browser blocks it, the deferred value is never published to the client registry, and the boundary stays on its fallback after hydration while the server HTML looks correct. Until that is closed, pick one per route: `defer()`, or a nonce'd CSP.
 
 ## `match` — where it runs
 
@@ -2931,5 +2986,22 @@ would any navigation.
 
 `from` matches route patterns literally, so a `[locale]` mirror declares its
 own: `/de/photos/[id]`'s page re-exports the base page and sets
-`intercept: { from: '/[locale]/photos' }` — same pattern as the documented
-searchParams schema re-export.
+`intercept: { from: '/[locale]/photos' }`.
+
+**Declares — not re-exports.** `intercept` is read off the page module at
+runtime, so any re-export forwards it, `export *` included. A mirror that
+forwards the base page's `intercept` therefore inherits `from: '/photos'`, and
+`from` is compared against the background's route PATTERN, which for a mirror is
+`/[locale]/photos`. The two never match, so the overlay silently never opens and
+the modal renders standalone — no error, no warning, just a page where a modal
+was expected. This is the opposite failure from the [searchParams
+re-export](/docs/routing/pages#mirror-routes-share-one-schema), which is silently
+*lost*; `intercept` is silently *inherited with the wrong pattern*.
+
+```tsx
+// src/pages/[locale]/photos/[id]/page.tsx
+export { default, meta } from '../../../photos/[id]/page'
+
+// NOT re-exported: the base's `from` names the un-prefixed pattern.
+export const intercept = { from: '/[locale]/photos' }
+```

package/templates/agent-docs/scheduling.md

@@ -214,7 +214,7 @@ The handler receives a `ScheduleContext` — the same `app` a mutation gets, plu
 > tenant-scoped** — a schedule runs as `system` with no tenant. Reads see every
 > tenant's rows, and a write to a `tenant()` table fails with
 > `TenantScopeViolation` unless you pass `tenantId` explicitly. See
-> [below](#a-schedule-runs-as-the-system-subject--no-tenant). This sentence is
+> [below](#a-schedule-runs-as-the-system-subject-no-tenant). This sentence is
 > here rather than only further down because "same shape as a mutation" is what
 > sets the expectation that gets violated.
 

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

@@ -257,6 +257,30 @@ const Input = Schema.Struct({
 )
 ```
 
+**The ids, and the shapes worth knowing.** `required`, `minLength {min}`,
+`maxLength {max}`, `betweenLength {min,max}`, `exactLength {amount}`,
+`pattern`, `invalidEmail` / `invalidUrl` / `invalidUuid`, `minValue {min}`,
+`maxValue {max}`, `minDate {min}` / `maxDate {max}`, `minItems` / `maxItems`,
+`integer`, `invalid`, `checking`, `invalidFileType` / `fileTooLarge`.
+
+Three of those exist because the generic answer is worse at the point of use:
+
+- **Two length bounds on one field are ONE statement.** `minLength(2)` +
+  `maxLength(50)` produce `betweenLength {min,max}` — not "at least 2" for a
+  field whose rule is "between 2 and 50" — and `length(4)` produces
+  `exactLength {amount}`.
+- **A declared `format` names the rule.** A regex never does: "Invalid format"
+  beside an email box tells nobody anything. Annotate the format and the id
+  gets specific — `Schema.String.pipe(Schema.pattern(EMAIL))
+  .annotations({ jsonSchema: { format: 'email' } })` → `validation.invalidEmail`.
+- **A date bound is not a number bound.** `minDate` / `maxDate` rather than
+  `minValue` reading "must be at least 2026-01-01".
+
+**Counting rules pass `count`.** `minItems` / `maxItems` carry `{ count }`
+(alongside `min`/`max`) because that is the parameter an i18n layer selects a
+plural form on — i18next keys pluralisation on a parameter named exactly
+`count`, so a message carrying only `{min}` cannot be pluralised at all.
+
 **Server-side rules route to their field too.** An executor raises a typed
 field error through the always-present `ctx.validation` — no declaration
 needed, `ValidationError` is auto-merged into every mutation's and action's
@@ -383,6 +407,61 @@ const form = useFormBinding('app', 'tasks.create', {
 holds SPA navigations (Back button included) and arms the native
 `beforeunload` prompt — see the routing docs.
 
+### Rich text — and who sanitizes it
+
+A rich-text field is `RichTextDocument`. Use it in the mutation input and the
+form renders an editor with no further annotation:
+
+```ts
+import { RichTextDocument } from '@voltro/web'
+
+const ArticleUpdateInput = Schema.Struct({
+  id: Schema.String,
+  body: RichTextDocument,
+})
+```
+
+Display it with `<RichTextView doc={article.body} />`.
+
+**The contract, because "who sanitizes" is the whole question.** The value is
+**not an HTML string** — it is a closed document tree with a fixed set of node
+types. There is no `html` node, no raw-markup escape hatch, no attribute bag,
+so there is nothing to sanitize: anything that is not one of the declared nodes
+simply fails to decode.
+
+That makes the **`Schema` decode the boundary** — the server's existing,
+non-bypassable input check, the same one every mutation input already passes
+through. The guarantee is therefore not "somebody remembered to sanitize this
+one"; it is that a document which reached your database is one of these shapes.
+
+The rest follows from that:
+
+- **A link's `href` is the one field pointing outward, and it is allowlisted**:
+  `http(s)`, `mailto:`, a `#fragment`, a `/path`. Nothing else — `javascript:`
+  and `data:` are refused by the decode, and control characters/whitespace are
+  stripped before the check, because `java\tscript:` navigates exactly like
+  `javascript:`.
+- **Client-side sanitizing is not a security boundary and is not treated as
+  one.** The widget's parser runs in the browser for the editing experience;
+  the browser is where an attacker sits, so every property it maintains is
+  re-established by the decode on the server.
+- **Rendering never uses `dangerouslySetInnerHTML`.** `<RichTextView>` maps
+  nodes to React elements and text to React children, so markup someone typed
+  into the box is markup the reader SEES. It also drops an href that would not
+  survive a decode — for the value that never went through one.
+
+**The built-in editor** is a `<textarea>` over a small, closed markdown subset:
+headings, `**bold**`, `*italic*`, `` `code` ``, `[text](href)`, `-` lists,
+`>` quotes and fenced code. Everything it does not recognise stays literal text.
+That is also what makes the field work with JavaScript off — the textarea posts
+source, `/form/*` parses it, the same decode validates it. Register your own
+`rich-text` widget (rung 2) for a WYSIWYG; the stored value shape is unchanged.
+
+**Not the collaborative case.** Concurrent, multi-writer editing is
+`crdtDoc()` + `useCrdtEditor` (`@voltro/local-first`) — a CRDT bytes column, a
+sync lane, Tiptap. This is the single-editor field: one column, one writer,
+ordinary JSON your server can validate, index and diff.
+
 **Testing.** `renderFormBinding` (from `@voltro/testing/client`) drives the
 REAL binding against a fake api — fill, blur, submit, read the visible
 errors; a mutation handler that throws `ValidationError({ field })`
@@ -399,6 +478,52 @@ expect(form.errors()['email']).toBe('validation.emailTaken')
 
 Runs under jsdom (`// @vitest-environment jsdom`).
 
+### What submit does with a failure, and what never reaches the wire
+
+**`submit()` does not reject.** A form calls it from an `onSubmit` handler that
+cannot await it, so a rejection has nowhere to go but the console — the form
+sits there looking saved while the failure is invisible. It resolves
+`undefined` instead, and the failure is state: field-routable errors land on
+their field, everything else in `state.submitError`, with an optional
+`onError` for a toast. That covers a composed `onSubmit` too — a follow-up
+write failing on its OWN mutation handle is a failure the binding never saw
+before, and it is the common shape (create the row, then its first child).
+
+**Only declared keys are sent.** A form almost always carries more than the
+mutation declares — a display toggle, a repeat control, a file held before
+upload — and the server has refused undeclared input fields since 0.37. The
+binding restricts the payload to the keys the input schema declares, which is
+the rule the no-JS path already followed (`unknown keys are dropped`), so the
+two submit paths agree. In development it warns once, naming what it dropped,
+because a genuinely misplaced field should still be visible. `toInput` remains
+the place to say what the write actually takes.
+
+**`setValue` with an unchanged value is a no-op.** Every React state source is
+expected to behave that way, and this one did not: each call produced a fresh
+`values` object, so an effect depending on `values` that re-set a field to the
+value it already held never settled.
+
+A widget kit that needs the whole form rather than one field reads it with
+`useFormBindingContext()` — the same provider, one level up.
+
+**Server and browser derive the same form.** A page rendered on the server
+resolves the mutation's input schema exactly as the browser will, so field
+lists, labels and required marks match and hydration holds. (`voltro dev` and
+`voltro start` both hand the descriptors over before rendering.)
+
+```tsx
+const form = useFormBinding('app', 'employees.update', {
+  toInput: (values) => ({ id, ...employeePatch(values) }),
+  onError: (error) => toast.error(String(error)),   // optional; state.submitError always carries it
+})
+
+// A field component anywhere below — no binding threaded through as a prop
+const City = () => {
+  const f = useFormField('address.city')
+  return <input value={String(f.value ?? '')} onChange={(e) => f.setValue(e.target.value)} onBlur={f.onBlur} />
+}
+```
+
 ### Forms without JavaScript
 
 On a server-rendered page, `<AutoForm>` works with JavaScript disabled — or not
@@ -419,7 +544,18 @@ the SAME input schema the RPC path decodes:
 - unknown keys are dropped
 
 Validation runs through the same `validateFields` as the client-side
-validation, so the error texts are identical. Then:
+validation, so the error texts are identical — in the request's language, not
+in English. The handler resolves the locale from THIS request through the same
+resolver that decided the surrounding page's language ([`voltro:locale` cookie
+› `Accept-Language` › the app's
+`defaultLocale`](/docs/i18n/overview#locale-resolution-order)); an app that
+configures no `locales` gets `en`. Then:
+
+Under URL-prefix i18n the referring URL wins over the cookie chain: a form on
+`/de/todos` renders its errors in German even if the `voltro:locale` cookie says
+otherwise, because there the prefix is which page you are on rather than a
+preference. A first segment that is not a declared locale falls through to the
+cookie chain.
 
 - **Success → `303 See Other`** (POST-redirect-GET): back to the submitting
   page, or to `redirectTo` (same-origin relative paths only; anything else is

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

@@ -13,7 +13,7 @@ _A marketing landing page — hero, features, CTA. Static-rendered with zero JS
 
 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.
+It ships plain JSX (a hero, a features list, a CTA) you replace with your own copy, bilingual out of the box (URL-prefix i18n: `/` + `/de`), plus the two asset pipelines a marketing page actually needs: a **local hero image** through `?image` + `<Image>` and a **self-hosted woff2** declared under `fonts:`. 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
 
@@ -27,14 +27,21 @@ voltro add-app marketing --template=frontend-landing --to acme
 
 ```text
 apps/acme/web/                          # dir named by the app, not the template
-├── app.config.ts                       # type:web, port:<allocated>
+├── app.config.ts                       # type:web, port:<allocated>, locales, fonts:
 ├── package.json
 ├── tsconfig.json
 └── src/
     ├── globals.css
+    ├── globals.d.ts                    # ambient '*.css' + '*?image'
+    ├── assets/hero.jpg                 # imported with ?image (build-time pipeline)
+    ├── fonts/Geist-Variable.woff2      # self-hosted, declared in app.config.ts
+    ├── fonts/LICENSE-Geist.txt         # the face's licence, shipped beside it
+    ├── lib/locale.ts                   # URL-prefix i18n helpers
+    ├── locales/{en,de}.ts              # the two catalogs
     └── pages/
         ├── layout.tsx                  # imports globals.css, renders {children}
-        └── index.tsx                   # the landing page (hero · features · CTA)
+        ├── page.tsx                    # the landing page (hero · features · CTA)
+        └── [locale]/page.tsx           # the /de mirror
 ```
 
 ## The page
@@ -88,9 +95,34 @@ import SignupForm from '../components/SignupForm.island'
 
 The surrounding HTML stays static; only the island hydrates.
 
+## The hero image — `?image` + `<Image>`
+
+`src/assets/hero.jpg` is imported with the **`?image` suffix**, the explicit opt-in to the [build-time image pipeline](/docs/routing/assets): the import resolves to an optimized-asset object instead of vite's plain hashed URL, and `<Image>` renders it as a `<picture>` with one `<source>` per modern format.
+
+```tsx
+import { Image } from '@voltro/web'
+import hero from '../assets/hero.jpg?image'
+
+<Image src={hero} alt="Abstract gradient artwork" priority sizes="(max-width: 900px) 100vw, 900px" />
+```
+
+`width`, `height` and the blur placeholder are **not props** — they come off the asset, which is what reserves the box (CLS ≈ 0) without hand-written numbers. `priority` marks it the LCP image (eager + high fetch priority). Nothing here needs JS, so it survives `interactive: 'none'`.
+
+The `*?image` ambient type is declared once in `src/globals.d.ts`. A **dynamic** `src` (a URL from a loader or CMS frontmatter) cannot be seen at build time — use the loader seam (`<Image src={url} loader={cdn} />`) instead.
+
+> **Under `voltro test`** the image plugin is not wired (it is a dev/build transform), so a `?image` specifier resolves to a plain URL string. The shipped `page.test.tsx` `vi.mock`s the import with the asset object the pipeline produces — copy that pattern rather than hand-writing `width`/`height` on the page.
+
+## The font — self-hosted, no CDN
+
+`app.config.ts` declares one family under [`fonts:`](/docs/routing/fonts), pointing at the woff2 committed in `src/fonts/`. The build content-hashes it and serves it from **your origin**, emits `@font-face`, computes a size-adjusted fallback face from the file's real metrics so the swap moves no text, and puts a `<link rel="preload">` in the shell.
+
+Reference it from CSS through the `--font-geist` variable the shell defines (`globals.css` points the kit's `--font-sans` at it), or from TSX with `localFont('Geist')`.
+
+**Swapping in your own face:** drop the `woff2` **and its licence file** into `src/fonts/`, then change `family` + `path`. The framework ships no font downloader on purpose — licence terms differ per family. The bundled Geist is SIL OFL 1.1 (`src/fonts/LICENSE-Geist.txt`).
+
 ## 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.
+`globals.css` imports `@voltro/ui-shadcn/tokens.css` (the design tokens) plus the mandatory `@source "./**/*.{tsx,ts,jsx,js}"` glob. Drop the kit import and use `@import "tailwindcss"` directly if you would rather start from nothing — but keep the `@source` line either way, and keep the `--font-sans` mapping if you keep the font declaration.
 
 ## What it doesn't ship