@voltro/cli 0.28.0 → 0.30.0

package/templates/agent-docs/local-first-mobile.md

@@ -0,0 +1,426 @@
+# Local-first & Mobile
+
+> "@voltro/local-first — CRDT text merge (crdtText/mergeCrdtStates), the offline sync-queue + SyncClient wire, presence/awareness, durable persistence, and the localFirst table mixin. Pure and browser-safe; the React hooks live behind a subpath."
+
+
+
+---
+
+<!-- source: en/local-first/overview.md -->
+## Local-first & CRDTs
+
+_"@voltro/local-first — CRDT text merge (crdtText/mergeCrdtStates), the offline sync-queue + SyncClient wire, presence/awareness, durable persistence, and the localFirst table mixin. Pure and browser-safe; the React hooks live behind a subpath."_
+
+`@voltro/local-first` is the framework's foundation for **offline-capable,
+multiplayer, convergent** apps: edit while disconnected, see other peers' cursors,
+and reconcile without losing work when the network returns. The `.` entry is
+**pure and browser-safe** — no `effect`, no `node:*` — so a route or component
+imports it directly. The React wrappers live behind `@voltro/local-first/react`
+(React is an optional peer, so the pure path never pulls it in).
+
+> **What ships today**: the pure CRDT text merge, the offline sync-queue reducer,
+> the connection-lifecycle state machine, the conflict policy, the
+> [`crdtText()` database column](#the-crdttext-database-column) (with its
+> authoritative server-side merge on the write path), the
+> [`SyncClient`](#the-syncclient-bi-directional-wire) that drives the queue over a
+> transport, [presence/awareness](#presence--awareness) via `usePresence`,
+> [durable IndexedDB persistence](#durable-persistence), and the
+> [`localFirst` table mixin](#the-localfirst-table-mixin). What remains is a thin
+> [runtime binding](#whats-shipped-vs-a-runtime-seam) to provisioned infra
+> (a broker at scale, a running app's transport) — not un-built framework code.
+
+## CRDT text: `crdtText` + `mergeCrdtStates`
+
+A CRDT (Conflict-free Replicated Data Type) text field can be edited by many
+peers offline and always converges to the same result. `crdtText()` builds one
+(Yjs-backed behind the `CrdtBackend` abstraction), and `mergeCrdtStates()` is
+the heart of the package — it converges two encoded states into one,
+deterministically and order-independently.
+
+```ts
+import { crdtText, mergeCrdtStates, decodeCrdtText } from '@voltro/local-first'
+
+// A field, edited offline. `insert`/`delete` mutate and return the same handle.
+const doc = crdtText('Hello').insert(5, ', world')
+const state = doc.encode() // the wire/storage form: a CrdtState
+
+// Converge two peers' encoded states — order-independent, no lost edits.
+const remote = crdtText('Hello').insert(5, ' there').encode()
+const merged = mergeCrdtStates(state, remote)
+decodeCrdtText(merged) // the plain-string view; both edits survive
+```
+
+`mergeCrdtStates` is deterministic (`decodeCrdtText(mergeCrdtStates(a, b))`
+equals the same for `(b, a)`), idempotent (re-merging a contained state is a
+no-op), and treats `emptyCrdtState()` as identity. The backend is a parameter on
+every function (defaulting to Yjs), so a later swap to Loro touches no call site.
+
+## The `crdtText()` database column
+
+`@voltro/database` ships a `crdtText()` **column type** for CRDT-managed fields.
+It needs no special DDL — to the declarative differ it is an ordinary nullable
+`bytes` column (BYTEA / BLOB / LONGBLOB / VARBINARY), so it plans and round-trips
+on every dialect like any other:
+
+```ts
+import { table, id, text, crdtText } from '@voltro/database'
+
+export const documents = table('documents', {
+  id: id(),
+  title: text(),
+  body: crdtText(), // CRDT-managed field — stored as the encoded state (bytes)
+})
+```
+
+The row type is `Uint8Array | null` (the encoded CRDT state); decode it to a
+string with `decodeCrdtText()`, and produce writes with a `crdtText()` handle's
+`.encode()`. The merge is **authoritative and server-side**: the runtime folds an
+incoming update into the stored state with `mergeCrdtStates` on the write path
+before writing, then the reactive engine broadcasts the merged result — which is
+what makes concurrent edits converge without a last-write-wins loser.
+
+## The `localFirst` table mixin
+
+`localFirst()` **marks a table as local-first** — mirrored to the client, synced
+bi-directionally, and (for its `crdtText()` fields) converged via CRDT merge. It
+adds no column; it is a property the framework reflects on.
+
+```ts
+import { table, id, text, crdtText, localFirst } from '@voltro/database'
+
+export const documents = table('documents', {
+  id: id(),
+  title: text(),
+  body: crdtText(),
+}).with(localFirst()) // opt this table into local-first sync + persistence
+```
+
+Discovery needs no codegen change — a marker mixin rides `.with()` like any
+column type. `isLocalFirst(table)` and `localFirstTables(schema)` are pure
+helpers, and the runtime's schema registry reflects it as `hasLocalFirst(table)`
+(beside `crdtColumns(table)`), which is the signal a client-sync-set builder
+reads. A local-first table may also carry plain columns — those sync
+last-write-wins via the [conflict policy](#conflict-policy-for-non-crdt-fields).
+
+## The `SyncClient`: bi-directional wire
+
+`createSyncClient({ transport })` maps the offline sync queue onto a transport:
+a local edit merges optimistically and queues; reconnect drains it to the server
+with retry; incoming merged state folds back via the CRDT — and concurrent edits
+converge. It invents **no** transport of its own — the `SyncTransport` is two
+functions an app binds to its **existing** wire:
+
+- `push` — deliver a queued CRDT write. Bound to a [`useMutation`](/docs/data/mutations)
+  that writes the `crdtText()` column (the server folds it authoritatively).
+- `onRemoteState` — receive merged state. Bound to the reactive
+  [`useSubscription`](/docs/data/queries) that already streams the row.
+
+```ts
+import { createSyncClient } from '@voltro/local-first'
+
+const sync = createSyncClient({
+  transport: {
+    kind: 'sync-transport',
+    push: (write) => runMutation('documents.setBody', write.payload),
+    onRemoteState: (handler) =>
+      subscribeRow('documents', (row) =>
+        handler({ table: 'documents', id: row.id, column: 'body', state: row.body }),
+      ),
+  },
+  adapter: durablePersistence, // optional — survives a reload
+})
+
+// A local edit: merges locally at once, queues, drains when online.
+sync.enqueue({ table: 'documents', id: 'd1', column: 'body', update: doc.encode() })
+sync.getText({ table: 'documents', id: 'd1', column: 'body' }) // the merged view
+```
+
+Everything below the two transport functions — the drain loop, retry/attempt
+counting, optimistic local merge, durable persistence — is in the client and
+tested against an in-memory dispatcher that mirrors the server's merge.
+
+## Presence & awareness
+
+`usePresence(roomId, self, { channel })` publishes this peer's ephemeral state
+(cursor, name, selection) and returns everyone else's — the multiplayer cursors
+of a collaborative editor. Presence is **ephemeral and high-frequency**, so it
+rides a pub/sub channel, never Postgres CDC or a table.
+
+```tsx
+import { usePresence } from '@voltro/local-first/react'
+
+function Editor({ documentId, channel }) {
+  const { presence, others, setPresence } = usePresence(
+    documentId,
+    { cursor: 0, name: 'Ada' },
+    { channel },
+  )
+  // render `others` as remote cursors; update on selection change:
+  const onSelect = (cursor: number) => setPresence({ cursor, name: 'Ada' })
+  return <Cursors others={others} />
+}
+```
+
+The `PresenceChannel` is the **same dumb string-payload pub/sub shape** as the
+framework broker (`@voltro/plugin-broadcast`), so a runtime binding forwards
+straight onto the app's provisioned broker — in-memory locally,
+Redis/NATS at scale (both already shipped). `createInMemoryPresenceChannel()` is
+the local/test transport. Join/leave, announce-back discovery, cursor
+propagation, and TTL expiry live in the pure `createPresenceRoom` the hook wraps.
+
+## The offline sync queue
+
+`useSyncQueue()` is a reactive view over a **pure, tested reducer**: writes made
+offline are queued, and a transport drains them when connectivity returns. Use it
+directly for fine-grained UI, or let the [`SyncClient`](#the-syncclient-bi-directional-wire)
+drive it for you.
+
+```tsx
+import { useSyncQueue, useConnectionStatus } from '@voltro/local-first/react'
+
+function SaveIndicator() {
+  const queue = useSyncQueue()
+  const { status } = useConnectionStatus(queue.outstanding)
+  // `outstanding` counts pending + in-flight (0 means synced).
+  return status === 'synced' ? null : <span>Saving… ({status})</span>
+}
+```
+
+## Connection status
+
+`useConnectionStatus(outstanding)` observes the connection lifecycle for the
+local-first layer — network up/down plus reconnect confirmation — and folds the
+number of unsynced writes into a display `status` of `offline | syncing |
+synced`, so `synced` means online **and** drained. It feeds the machine the two
+signals a browser can observe (`navigator.onLine` + the `online`/`offline`
+events); confirmed round-trips (`confirm()`/`confirmFailed()`) are left to the
+caller, so the hook never invents a server ping.
+
+> This is the local-first connection machine, distinct from `@voltro/client`'s
+> RPC-error-derived [`useConnectionStatus`](/docs/ui/client-utilities/use-connection-status) —
+> a different package with a different signal source.
+
+## Durable persistence
+
+Local CRDT state and the offline queue should survive a reload. Everything above
+storage speaks the `PersistenceAdapter` contract, so the backing swaps freely:
+
+- `createInMemoryPersistence()` — ephemeral (lost on reload); the test/default.
+- `createIndexedDbPersistence()` — **durable**, over the browser's own
+  IndexedDB. No WASM, no added dependency; the IDB implementation is injectable,
+  so it is tested against a fake backend that survives a reopen.
+
+```ts
+import { createIndexedDbPersistence } from '@voltro/local-first'
+
+const adapter = await createIndexedDbPersistence({ databaseName: 'my-app' })
+const sync = createSyncClient({ transport, adapter }) // state now survives reload
+```
+
+## Conflict policy for non-CRDT fields
+
+CRDT fields resolve themselves — the merge **is** the resolver. A plain scalar
+like `title` needs a policy. `conflictPolicy()` declares one per field; the
+default everywhere is last-write-wins, and any field you do not name falls back
+to it, so a policy never has to enumerate every column.
+
+```ts
+import { conflictPolicy } from '@voltro/local-first'
+
+const policy = conflictPolicy({
+  title: 'lastWriteWins',
+  // A custom resolver MUST converge: both peers pick the same winner.
+  tags: (local, remote) => (remote.updatedAt >= local.updatedAt ? remote.value : local.value),
+})
+
+policy.resolveRecord(
+  { title: { value: 'Draft', updatedAt: 1 } },
+  { title: { value: 'Final', updatedAt: 2 } },
+) // → { title: 'Final' }
+```
+
+The one property that matters is **convergence**: `lastWriteWins` breaks an
+exact `updatedAt` tie on a stable, symmetric key (writer id, then the value's
+string form), so two peers agree regardless of which side each calls "local".
+
+## What's shipped vs. a runtime seam
+
+The framework code for local-first is built and tested end to end against
+in-memory transports. What remains is not un-built framework — it is the thin
+binding to **provisioned infrastructure**, sitting behind interfaces the tested
+code already speaks:
+
+| Runtime seam | What it binds | Why it's a binding, not code |
+| --- | --- | --- |
+| **Sync transport → a running app** | The `SyncClient`'s `push`/`onRemoteState` to one app's `useMutation` + `useSubscription`. | The two functions are app-specific glue; the drain loop, merge, retry, and persistence all ship and are tested. |
+| **Presence channel → a broker at scale** | The `PresenceChannel` to a provisioned Redis/NATS broker. | It's a network hop over an already-shipped broker; the awareness logic ships and is tested over the in-memory channel. |
+| **wa-sqlite / Turso adapter** *(optional)* | A SQL durable adapter for cross-tab queries, behind `PersistenceAdapter`. | IndexedDB is the durable default today; a SQL backing is a sibling factory, nothing above it changes. |
+
+
+
+---
+
+<!-- source: en/react-native/overview.md -->
+## React Native
+
+_"@voltro/react-native — the credential-free mobile plumbing: registerDevice + the _voltro_devices table, defineDeepLink + its matcher, useBackgroundSync, and offline-first client defaults + connection status."_
+
+The React-client bindings are **import-safe** in React Native — every DOM touch
+in `@voltro/client` is `typeof window`-guarded, so nothing crashes at import.
+What is **not done yet** is wiring the client's runtime for RN: building the
+`ApiHandle`s (runtime + subscription cache + rpc client) over a native
+WebSocket, plus an RN persistence adapter and a NetInfo connection signal. That
+is Phase **M0** of the mobile plan — until it lands, the reactive loop is
+unproven on a device. `@voltro/react-native` ships the mobile-specific plumbing
+that works **today**, limited to the parts that need **no per-tenant credentials
+and no native runtime**: device registration, background-sync scheduling,
+offline-first defaults, a connection-status surface, and the deep-link
+declaration shape.
+
+> **Scaffold a mobile app.** `voltro create-project acme --api=api-backend
+> --mobile` (or `voltro add-app mobile --template mobile-app`) scaffolds an Expo
+> app that consumes your api with the same typed hooks. Expo owns Metro
+> (`expo start` / `expo run:ios`), not `voltro dev`. See
+> [the `mobile-app` template](/docs/templates/mobile-app).
+
+The package **root is RN-safe** — no `node:*`, no `@voltro/database`, and React
+is reached only through the hooks (an optional peer). The `_voltro_devices` table
+declaration is server-side and lives at `@voltro/react-native/schema`.
+
+## Device registration
+
+A device is registered **after** the OS issues its push token (APNs on iOS, FCM
+on Android, Web Push on web). `registerDevice()` normalises a raw input into a
+row and upserts it through whatever transport the app already has — a generated
+mutation caller or a plain `fetch` — so the package stays free of transport
+coupling.
+
+```ts
+import { registerDevice } from '@voltro/react-native'
+
+// `userId`/`tenantId` are stamped SERVER-side from the authenticated request —
+// never trusted from the client. `locale`/`timezone` default from the device.
+await registerDevice(
+  (row) => api.mutate('registerDevice', row),
+  { deviceToken, platform: 'ios' },
+)
+```
+
+Registration is idempotent: the row is stored in `_voltro_devices` with a unique
+key of `(platform, token)`, so re-registering the same token updates the row in
+place instead of inserting a duplicate. A **rotated** token is a new
+registration; reaping the stale one is the sender adapter's job (a seam), not the
+client's.
+
+### The `_voltro_devices` table
+
+The table declaration is a server-side entry — it imports the `@voltro/database`
+column DSL, so it is deliberately off the RN-safe root. Contribute it to your
+schema and it migrates like any framework table (the `_voltro_*` prefix rides the
+declarative differ on `voltro dev` / `voltro db apply`, on every dialect):
+
+```ts
+// schema/devices.ts — add the framework device table to your app's schema.
+export { devicesTable } from '@voltro/react-native/schema'
+```
+
+It carries tenant + user scope, `platform`, `token`, `locale`, `timezone`,
+optional `appVersion`/`metadata`, and a `lastSeenAt` rotation clock. It is unique
+on `(platform, token)` and indexed on `userId` — the hot read path for fanning a
+push out to every device of a user.
+
+## Deep links: `defineDeepLink` + the matcher
+
+`defineDeepLink({ pattern, handler })` is the descriptor a deep-link file
+declares; its pure matcher turns `/orders/:id` + `/orders/42` into `{ id: '42' }`.
+The params are inferred from the `:name` segments, so `handler` type-checks
+against exactly the params the pattern declares.
+
+```ts
+import { defineDeepLink } from '@voltro/react-native'
+
+export default defineDeepLink({
+  pattern: '/orders/:id',
+  handler: ({ id }) => navigateTo(`/orders/${id}`),
+})
+```
+
+The matcher is pure — no navigation, no side effects — and normalises scheme +
+host away, so a universal link, an App Link, and a custom-scheme URL all match
+the same path-only pattern:
+
+```ts
+import { matchDeepLink, matchFirstDeepLink } from '@voltro/react-native'
+import orderLink from './orders.deepLink'
+
+matchDeepLink('/orders/:id', '/orders/42') // → { id: '42' }
+matchDeepLink('/orders/:id', '/orders/42/edit') // → null
+
+// Until `*.deepLink.ts` file discovery lands, register links by hand —
+// declaration order wins, so list more-specific patterns first.
+const hit = matchFirstDeepLink([orderLink], 'myapp://orders/42')
+hit?.params.id // '42'
+```
+
+> **Seam — file discovery.** Wiring `*.deepLink.ts` into codegen (so the router
+> auto-collects every declared link) is one additive file, landing after the
+> current release settles. The descriptor shape above is **final**, so register
+> links via `matchFirstDeepLink()` until then.
+
+## Background sync
+
+`useBackgroundSync(onSync, options)` owns three triggers — an interval timer, a
+"returned to foreground" subscription, and a manual `sync()` — over a pure
+`shouldSync` policy (single-flight, foreground-gated, interval-gated). The OS
+background-fetch **registration** itself stays the app's; this hook is only the
+interval/foreground state machine.
+
+```tsx
+import { useBackgroundSync } from '@voltro/react-native'
+
+function SyncIndicator() {
+  const { status, lastSyncAt, sync } = useBackgroundSync(
+    () => api.refetchAll(),
+    { intervalMs: 60_000, syncOnForeground: true },
+  )
+
+  return <button onClick={sync}>Sync ({status})</button>
+}
+```
+
+`onSync` may be async — a rejection is captured into `status: 'error'` +
+`lastError`, a resolution into `status: 'success'` + `lastSyncAt`.
+
+## Offline-first defaults + connection status
+
+`offlineFirstDefaults` is the mobile posture as a value you spread into your
+client config: local-first ON, optimistic mutations, sync-on-foreground, a
+5-minute cadence, and a retry backoff schedule. `useMobileConnectionStatus()`
+surfaces a `connected | degraded | offline` status — `offline` from
+`navigator.onLine`, `degraded` from failures the app reports.
+
+```tsx
+import { offlineFirstDefaults, useMobileConnectionStatus } from '@voltro/react-native'
+
+// Spread the mobile posture into your client config.
+const config = { ...offlineFirstDefaults, url }
+
+function ConnectionPill() {
+  const { status, reportFailure, reportSuccess } = useMobileConnectionStatus()
+  return <span data-status={status}>{status}</span>
+}
+```
+
+## What's shipped vs. a seam
+
+This package ships the credential-free plumbing above. The parts that need
+external credentials or a native runtime are flagged as **deliberate seams** —
+not built here:
+
+| Seam | Why it is not in this package |
+|---|---|
+| **APNs / FCM sender adapters** | Need per-tenant Apple Developer / Firebase credentials — genuinely external, managed via provider provisioning. Registration stores the token; sending to it is the seam. |
+| **Native module bindings** (camera, biometrics, secure token storage) | Need a native runtime this TS package cannot provide. |
+| **Swift / Kotlin SDK generators** | **Built + golden-tested** — `voltro build api --target swift\|kotlin` emits a native SDK package. What is deferred is *compiling* the emitted package (`swiftc` / Gradle): that is a mobile-CI step, no cross-language toolchain lives in the framework repo. |
+| **Universal-links / App-Links file automation** (`apple-app-site-association`, `assetlinks.json`) | A deployment-layer concern, not a client primitive. |
+| **`*.deepLink.ts` codegen discovery** | One additive file after the release settles; the descriptor shape is final, so register links via `matchFirstDeepLink()` today. |

package/templates/agent-docs/routing.md

@@ -785,6 +785,38 @@ export default function NotePage(): ReactNode {
 
 `useLoaderData<T>()` returns the loader's resolved value, typed via the generic.
 
+**On a page that declares a `loader`, the value is always there.** The router
+never renders such a page without its data: a settled loader commits its data
+and the displayed route together, a pending one shows the `Pending` skeleton
+(or keeps the previous page), and one that threw renders the error subtree. You
+do not need a guard, and adding one only hides a real mistake behind a `?.`.
+
+**Calling it where no `loader` exists is an error, and it says so.** A level with
+no `loader` export throws:
+
+```text
+useLoaderData() was called at a level that declares no `loader`. Export `loader`
+from this page/layout, or — if this component is shared between routes that have
+one and routes that do not — read it with `useOptionalLoaderData()` …
+```
+
+Note what is NOT an absence: an empty **result**. A loader returning
+`{ items: [] }` returns exactly that. `undefined` never means "the query found
+nothing" — it means "there is no loader at this level".
+
+### `useOptionalLoaderData()` — for a component on both kinds of route
+
+One case needs it: a component genuinely mounted both under routes that declare
+a loader and routes that do not. It returns `undefined` instead of throwing.
+
+```tsx
+const data = useOptionalLoaderData<Data>()
+const project = data?.project
+```
+
+A loader that legitimately resolves to `undefined` is not an error — both hooks
+hand that `undefined` back. Only the missing `loader` throws.
+
 ## When loaders run
 
 | renderMode | When loader runs |
@@ -830,6 +862,23 @@ export default function Profile() {
 
 Because the SSR markup and the hydration render read the same loader value, they match — no hydration flicker — and you don't hand-build a seed store to bridge the two. This is distinct from `fallback`, whose value never came from the server and so keeps `loading: true`; use exactly one of the two.
 
+> **Seed whatever the screen checks FIRST, not whatever is most interesting.**
+> A component's server render stops at its OUTERMOST unsatisfied gate, so an
+> unseeded subscription in an early branch hides every seeded one below it:
+>
+> ```tsx
+> // Seeding `roadmap` changes nothing while this branch is the first one.
+> if (availableYearsIdle || availableYearsLoading) return <Spinner />
+> return <Roadmap data={roadmap} />
+> ```
+>
+> The symptom is a page that still server-renders a spinner after you seeded
+> the data you care about. Walk the component's early returns from the top and
+> seed each subscription they read, or move the gate below the render you want.
+> The same applies to an auth gate: a `useSubscription`-backed
+> `AuthenticationProvider` has no data during a server render, so every page
+> under it renders its loading state until that subscription is seeded too.
+
 Client-side navigation is unchanged: moving to another route runs that route's
 loaders in the browser as usual. A `spa` page has no server render, so its
 loader runs on the client on first mount.
@@ -1148,18 +1197,26 @@ export const meta = ({ loaderData }: { loaderData: { note?: { title: string; bod
 })
 ```
 
-The third context field — `locale: string` — is the active i18n locale for this render. For `[locale]/…` routes it carries the URL-prefix locale (`'de'` on `/de/notes/42`). For bare-path routes it carries the active locale from the framework's `voltro:lang` cookie when set — so **cookie-based i18n works too** (an authed dashboard with no `[locale]` URL still gets a translated `<title>` that tracks the language switch) — otherwise the app's `defaultLocale`. Use it to localise title / description / canonical / OG per locale at SSG time so search engines see translated head tags on every variant, and to give cookie-i18n pages a translated tab title:
+The third context field — `locale: string` — is the active i18n locale for this render. For `[locale]/…` routes it carries the URL-prefix locale (`'de'` on `/de/notes/42`). For bare-path routes it carries the active locale from the framework's `voltro:locale` cookie when set — so **cookie-based i18n works too** (an authed dashboard with no `[locale]` URL still gets a translated `<title>` that tracks the language switch) — otherwise the app's `defaultLocale`. Use it to localise title / description / canonical / OG per locale at SSG time so search engines see translated head tags on every variant, and to give cookie-i18n pages a translated tab title:
 
 ```tsx
 import { getCatalog } from '../lib/locale'
-import { localeCanonicalUrl } from '../lib/seo'
+import { seoAlternates } from '@voltro/web'
 
 export const meta = ({ locale }: { locale: string }): PageMeta => {
   const c = getCatalog(locale)
   return {
     title:       c['seo.notes.title']       as string,
     description: c['seo.notes.description'] as string,
-    canonical:   localeCanonicalUrl('/notes', locale),
+    // Canonical URL for THIS locale + a reciprocal `hreflang` alternate for
+    // every locale (incl. `x-default`), spread straight into the meta.
+    ...seoAlternates({
+      siteUrl:       'https://notes.example.com',
+      path:          '/notes',
+      locale,
+      locales:       ['en', 'de'],
+      defaultLocale: 'en',
+    }),
   }
 }
 ```
@@ -1168,6 +1225,40 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
 
 `loaderData` is the PAGE loader's result. Because `meta` runs server-side after the loader, the SSR'd `<head>` is already correct on first paint — no client-side title patching, no flash.
 
+## Technical SEO: canonical, hreflang, sitemap & robots
+
+The framework ships the cheap technical-SEO primitives so an indexable app gets them without app-level plumbing.
+
+**Canonical + hreflang helpers** (`@voltro/web`) are pure functions you call from `meta`. They are browser-safe, so importing them into a `*.page.tsx` never drags a server module into the client bundle:
+
+- `canonicalUrl(siteUrl, path)` — one absolute canonical URL.
+- `seoAlternates({ siteUrl, path, locale, locales, defaultLocale })` — returns `{ canonical, links }` where `canonical` is this locale's URL and `links` is one `rel="alternate"` per locale (each an **absolute** URL, as Google requires) plus `hreflang="x-default"`. The alternate set is reciprocal across every locale — exactly what Google's [hreflang rules](https://developers.google.com/search/docs/specialty/international/localized-versions) want. The locale model is URL-PREFIX routing: the default locale on the bare path (`/notes`), other locales prefixed (`/de/notes`).
+
+**Keeping a page out of the index** — set `noIndex` on its meta. It emits `<meta name="robots" content="noindex, nofollow">` AND excludes the route from the generated `sitemap.xml`:
+
+```tsx
+export const meta: PageMeta = { title: 'Checkout', noIndex: true }
+```
+
+**`sitemap.xml` + `robots.txt`** are generated at `voltro build` from the prerendered routes. Turn them on with a `seo.siteUrl` in `app.config.ts`:
+
+```ts
+export default {
+  type: 'web' as const,
+  name:  'Notes',
+  locales: ['en', 'de'],
+  defaultLocale: 'en',
+  seo: {
+    siteUrl:  'https://notes.example.com',
+    disallow: ['/admin'],           // extra robots Disallow prefixes (optional)
+  },
+}
+```
+
+- **`sitemap.xml`** lists every prerendered route (minus `noIndex` ones). With 2+ `locales`, each URL carries the full `xhtml:link` alternate set. Written only when `seo.siteUrl` is set — absolute URLs are required.
+- **`robots.txt`** is generated even without `siteUrl`. Production allows all and advertises the sitemap; `voltro dev` — and any build with `VOLTRO_SEO_NOINDEX=1` (staging / preview deploys) — disallows everything, so a non-production surface never gets indexed by default.
+- A user-authored `public/sitemap.xml` / `public/robots.txt` always wins — the generator never overwrites one.
+
 ## Examples
 
 ### Authenticated dashboard with cookie-driven loader

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

@@ -202,6 +202,18 @@ A combined create-or-edit screen is a three-line wrapper:
   `{ fields, values, errors, isValid, pending, setValue, submit, reset }` for
   100% custom JSX — the binding stays.
 
+### Accessible by default
+
+The built-in widgets render accessible HTML without any extra work: a `<label htmlFor>` tied to the control, `aria-required` on required fields (the visual `*` is `aria-hidden` — assistive tech learns "required" from the control, not from a spoken "star"), and, on error, `aria-invalid` + a `role="alert"` message associated via `aria-describedby`. A radio group ties its error to the whole `<fieldset>`.
+
+Add **help text** by putting a `description` on the field's Schema — it renders as a hint and is associated to the control via `aria-describedby`, so a screen reader announces it with the label:
+
+```ts
+Schema.Struct({
+  handle: Schema.String.annotations({ description: 'Shown on your public profile' }),
+})
+```
+
 ## `<DataTable>` — bind to a QUERY
 
 Columns come from the query's output `Schema`; rows are a LIVE subscription

package/templates/agent-docs/security.md

@@ -88,6 +88,23 @@ DNS is not resolved. A public hostname that *resolves* to a private address (DNS
 rebinding) still passes. That vector needs network-layer egress control; it is
 stated here rather than silently implied.
 
+## Auditing what your log tables actually hold
+
+```bash
+voltro db scan-credentials
+voltro db scan-credentials --table my_events:actor
+```
+
+Counts rows whose Subject carries a credential-shaped key — `token`, `secret`, `password`, `apikey`, `credential`, `privatekey` — in `_voltro_audit_log` and `_voltro_row_history`, plus any table you name with `--table <name>[:<column>]` (the column defaults to `subject`). Exit code `1` on a hit, so CI can gate on it.
+
+**It is a command and not a documented query on purpose.** The same check once shipped as SQL you were asked to run yourself, in its postgres spelling (`subject::text ILIKE '%token%'`). On MySQL/MariaDB the natural translation is a bare `LIKE` — and against the `utf8mb4_bin` collation the migrator emits for a `json()` column, `LIKE` is case-**sensitive**. So `'%token%'` does not match `jiraToken`, and almost every JSON key that carries a credential is camelCase. A team ran the translated query over 141 rows, got `0`, and nearly reported themselves clean; 117 of those rows held a working credential. Every dialect now casts to its own text type before lowering, in code you do not have to translate.
+
+**A `0` here never means two things.** Each line prints the number of rows *scanned* beside the number of hits. An empty table says so in words rather than reading as clean, a missing table reports as missing rather than as zero, and a run that examined nothing exits `2`.
+
+Run it on every environment. A development database is not a sample of production.
+
+If it finds something: purge the rows **and** rotate the credentials — assume anything written to a log table has been read — then move the credential off the Subject entirely with `connectionCredentials(...)`, which keeps it in the framework vault.
+
 ## Supply-chain assurance
 
 Every release passes automated supply-chain gates in CI before a single package is published: