@voltro/cli 0.29.0 → 0.30.0

package/templates/agent-docs/routing.md

@@ -1197,7 +1197,7 @@ 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'

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:

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

@@ -3291,3 +3291,212 @@ The synced rows stream in live via the `events.list` subscription.
 
 - [`store: 'postgres'`](/docs/database/dialects) — the cursor + markers survive restarts and are shared across replicas.
 - [Key-value backends](/docs/caching/kv-backends) — put just the KV on a persistent Redis with `KV_BACKEND=redis`, no handler change.
+
+
+
+---
+
+<!-- source: en/templates/api-collab.md -->
+## API · Collab (CRDT)
+
+_Real-time collaborative editing — a documents table whose body is a crdtText() column. Concurrent edits converge via an authoritative server-side CRDT merge on the write path, then broadcast over the reactive engine. Zero infra._
+
+The local-first / CRDT backend: a `documents` table whose `body` is a **`crdtText()`** column. When two clients edit the same body concurrently, the runtime folds each incoming update into the stored state with an **authoritative server-side merge on the write path** — so their edits **converge**, with no last-write-wins loser — and the reactive engine broadcasts the merged row to every subscriber. Zero-infra (`store: 'memory'`): the merge and the broadcast are both in-process, so two browser tabs pointed at one `voltro dev` collaborate with no database, no Redis, no external service. Template id: **`api-collab`**.
+
+## Scaffold the pair
+
+`api-collab` is the backend half — it exposes the `documents.list` subscription + `documents.create` / `documents.setBody` mutations that [`frontend-collab`](/docs/templates/collab) binds a collaborative editor to. Scaffold both together:
+
+```bash
+voltro create-project collab --api=api-collab --web=frontend-collab
+```
+
+## What ships
+
+```text
+apps/collab/api/
+├── app.config.ts                              # type:api, store:'memory'
+├── database/
+│   └── schema.ts                              # documents — a crdtText() body + tenant() + localFirst()
+├── queries/
+│   ├── documents.query.ts                     # documents.list — streaming subscription
+│   └── documents.query.server.ts
+├── mutations/
+│   ├── documents.create.mutation.ts           # create a document (title only)
+│   ├── documents.create.mutation.server.ts
+│   ├── documents.setBody.mutation.ts          # the CRDT write — a client's encoded update
+│   └── documents.setBody.mutation.server.ts
+└── tests/
+    └── documents.setBody.test.ts              # convergence proof — two edits merge, order-independently
+```
+
+## The headline: a `crdtText()` column + server merge
+
+`body: crdtText()` stores the encoded CRDT state as an opaque `bytes` blob. To the declarative differ it is an ordinary nullable `bytes` column — no special DDL — so it plans and round-trips on every dialect like any other column. `localFirst()` marks the table local-first (client mirror + CRDT convergence for its `crdtText()` fields); it adds no column, it is a property the framework reflects on.
+
+```ts
+// database/schema.ts
+import { crdtText, databaseHandle, id, localFirst, table, text, timestamp, type InferRow } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// Core tables the audit() / tenant() mixins reference.
+export const actors = table('actors', {
+  id: id(), kind: text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(), createdAt: timestamp().default('now'),
+})
+export const tenants = table('tenants', { id: id(), name: text(), createdAt: timestamp().default('now') })
+
+// The collaborative document. `body: crdtText()` is a CRDT-managed column —
+// stored as the encoded CRDT state (an opaque `bytes` blob; BYTEA / BLOB /
+// VARBINARY per dialect). Decode it with decodeCrdtText().
+export const documents = table('documents', {
+  id:    id({ prefix: 'doc' }),
+  title: text(),
+  body:  crdtText(), // Uint8Array | null
+})
+  // tenant() pulls audit() transitively (tenantId + timestamps + actor stamps)
+  // and auto-scopes every read/write. localFirst() marks the table local-first.
+  .with(tenant(), localFirst())
+
+export type Document = InferRow<typeof documents>
+export const database = databaseHandle({ actors, tenants, documents })
+```
+
+## The CRDT write — `documents.setBody`
+
+A client produces an encoded update from its local `crdtText()` handle (`handle.encode()`) and sends it here. The server does **not** overwrite `body` with it. Because `body` is a `crdtText()` column, the runtime's MutationStore intercepts the write, reads the **stored** state, and folds the incoming update in with `mergeCrdtStates` (from `@voltro/local-first`) **before** persisting. That authoritative server merge is the convergence guarantee; the reactive engine then broadcasts the merged row.
+
+```ts
+// mutations/documents.setBody.mutation.ts — descriptor (browser-safe)
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+// `op: 'update'` targets the row by primary key. `update` is the opaque encoded
+// CRDT state a client produced from its local handle (`handle.encode()`). No
+// tenant field: the tenant() mixin auto-scopes the update, so a foreign id
+// simply matches no row.
+export const setDocumentBody = defineMutation({
+  name: 'documents.setBody',
+  target: { table: 'documents', op: 'update' },
+  input: Schema.Struct({
+    id: Schema.NonEmptyString,
+    update: Schema.Uint8ArrayFromBase64,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    // The MERGED body — what every subscriber now converges to.
+    body: Schema.NullOr(Schema.Uint8ArrayFromBase64),
+    tenantId: Schema.String,
+  }),
+})
+```
+
+```ts
+// mutations/documents.setBody.mutation.server.ts — executor (default export)
+import type { AppContext } from '@voltro/runtime'
+
+// The handler looks like a plain overwrite — but `body` is a crdtText() column,
+// so the runtime's MutationStore intercepts the write: it reads the STORED state
+// and folds the incoming update in with mergeCrdtStates (@voltro/local-first)
+// BEFORE persisting. That authoritative server merge is what makes concurrent
+// edits converge; the reactive engine then broadcasts the merged row. This
+// handler stays a one-liner precisely because convergence lives in the write path.
+const execute = async (input: { id: string; update: Uint8Array }, ctx: AppContext) => {
+  const row = await ctx.store.update('documents', input.id, { body: input.update })
+  if (row === null) throw { status: 404, message: `document ${input.id} not found` }
+  return row
+}
+
+export default execute
+```
+
+The `body` field crosses the wire as base64 (`Schema.Uint8ArrayFromBase64` — JSON-safe, unlike raw bytes) and the rpc client decodes it back to a `Uint8Array`.
+
+## The streaming query — `documents.list`
+
+Every change to `documents` for the caller's tenant lands as a delta — including the merged `body` after any client's CRDT write. Oldest-first, so `documents[0]` is stable across clients (the collab page binds its editor to that first document, and every tab agrees on which one). The `tenant()` mixin AND-merges tenant scope into the predicate, so no manual `eq('tenantId', …)` is needed.
+
+```ts
+// queries/documents.query.ts — descriptor (browser-safe)
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listDocuments = defineQuery({
+  name: 'documents.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.NullOr(Schema.Uint8ArrayFromBase64),
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+})
+```
+
+```ts
+// queries/documents.query.server.ts — executor
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'documents' as const,
+    order: [{ column: 'createdAt' as const, direction: 'asc' as const }],
+    take: 100,
+    // tenant scope is AND-merged by the runtime — no manual eq('tenantId', …)
+  },
+})
+
+export default execute
+```
+
+## The convergence proof — with no database, no server
+
+The property that matters for a `crdtText()` column is **convergence**: two clients that edit the same body concurrently end at the same text, whichever write the server processes first, with **both** edits surviving. `ctx.store` from `@voltro/testing` is the same mixin-wrapped store the handler gets in production, so the authoritative server-side merge on the write path executes exactly as at runtime — the test needs no database.
+
+```ts
+// tests/documents.setBody.test.ts — run with `voltro test`
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { crdtText, decodeCrdtText } from '@voltro/local-first'
+import createDocument from '../mutations/documents.create.mutation.server'
+import setBody from '../mutations/documents.setBody.mutation.server'
+
+const freshCtx = () =>
+  makeTestContext({
+    subject: { type: 'user', id: 'u1', tenantId: 'acme' },
+    store: mockStore({ documents: [] }),
+  })
+
+describe('documents.setBody — authoritative server-side CRDT merge', () => {
+  it('folds two concurrent edits together so BOTH survive', async () => {
+    const ctx = freshCtx()
+    const doc = await createDocument({ tenantId: 'acme', title: 'Design doc' }, ctx)
+
+    await setBody({ id: String(doc['id']), update: crdtText().insert(0, 'Hello ').encode() }, ctx)
+    const merged = await setBody({ id: String(doc['id']), update: crdtText().insert(0, 'World').encode() }, ctx)
+
+    const text = decodeCrdtText(merged.body as Uint8Array)
+    expect(text).toContain('Hello')
+    expect(text).toContain('World')
+  })
+})
+```
+
+Note the second test in the shipped suite reuses the **same** two encoded updates in both orders and asserts the decoded text is identical — that is order-independent convergence, not chance. The suite also pins idempotency (re-applying a folded update is a no-op) and that a write to an unseen document 404s (tenant auto-scoped).
+
+## Store — memory by default
+
+`app.config.ts` ships `store: 'memory'` — the merge and the broadcast are in-process, so collaboration works across browser tabs on a single `voltro dev` with zero infra. Switch to `'postgres'` (the encoded state is a plain `bytes` column, so it persists like any other) when you go durable; run `voltro add redis` for a cross-instance broadcast when you scale past one process.
+
+## Pairs well with
+
+- [`frontend-collab`](/docs/templates/collab) — the editor UI that binds a textarea to this `crdtText()` body. Scaffold the pair with `--api=api-collab --web=frontend-collab`.
+
+## Anti-patterns
+
+- **Treating `documents.setBody` as an overwrite.** It is not last-write-wins — the runtime folds the incoming update into the stored state. Do not "read-modify-write" the body in the handler; send the client's encoded update and let the write path merge it.
+- **Putting `node:*` / database imports in a descriptor (`*.mutation.ts`).** Those files reach the browser bundle through codegen. Keep server-only code in the `.server.ts` half.
+- **Sending raw bytes over the wire.** `body` is declared `Schema.Uint8ArrayFromBase64` so it is JSON-safe; a raw `Uint8Array` in the schema would not round-trip through the rpc layer.
+- **Dropping the cross-tenant write guard on create.** `documents.create` calls `assertOwnTenant(input.tenantId, ctx.request.subject)`. Reads are auto-scoped by `tenant()`, but a mutation writing a raw `tenantId` still needs the guard.

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

@@ -1333,7 +1333,7 @@ Then point the form at the deployed function: set `CONTACT_ENDPOINT` in `src/con
 
 _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`**.
+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 one of the two fullstack templates that wire a web frontend to an api (the other is [`collab`](/docs/templates/collab), its local-first / CRDT sibling); every other `frontend-*` template is backend-less and every `api-*` template is frontend-less. Template id: **`frontend-app`**.
 
 ## Scaffold the pair
 
@@ -2060,3 +2060,146 @@ Everything under `src/pages/admin/` is yours. Swap the cookie gate (`lib/auth.ts
 - **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.
+
+
+
+---
+
+<!-- source: en/templates/collab.md -->
+## Collaborative editor
+
+_A collaborative document editor — a textarea bound to a crdtText() body over the reactive engine. Type in two browser tabs at once and the edits converge (server-authoritative CRDT merge), no last-write-wins loser._
+
+A live document editor whose textarea is bound to a **`crdtText()` body** over the framework's reactive loop. Type in **two browser tabs at once** and the edits **converge** — no last-write-wins loser — because the api merges every update into the shared document server-side, then broadcasts the merged result back live. Zero-infra: the merge and the broadcast are in-process on a single `voltro dev`. `frontend-collab` is a fullstack template — it consumes a sibling api. Template id: **`frontend-collab`**.
+
+## Scaffold the pair
+
+`frontend-collab` consumes a sibling api, so scaffold it **together with** [`api-collab`](/docs/templates/api-collab) — which exposes the `documents.list` subscription + `documents.create` / `documents.setBody` mutations this page binds to:
+
+```bash
+voltro create-project collab --api=api-collab --web=frontend-collab
+cd collab
+pnpm install
+pnpm dev            # boots BOTH apps — the api and the web
+```
+
+Open the web app, click **Create document**, then open a **second tab** on the same URL and type in both. Every keystroke merges — both tabs' edits survive.
+
+## What ships
+
+```text
+apps/collab/web/
+├── app.config.ts                  # type:web + the apis: { app } wiring + locales
+├── package.json                   # depends on @collab/api + @voltro/client + @voltro/local-first
+└── src/
+    ├── locales/{en,de}.ts         # bilingual UI strings
+    └── pages/
+        ├── layout.tsx             # root shell (header + <main> + <LocaleSwitcher>)
+        └── page.tsx               # the editor — subscription + CRDT handle + setBody
+```
+
+## The `apis` wiring
+
+A web app declares the apis it consumes in `app.config.ts`. The map KEY (`app`) is the lookup name every hook takes as its first argument:
+
+```ts
+// app.config.ts
+export default {
+  type: 'web' as const,
+  name: 'CollabWeb',
+  apis: {
+    app: { package: '@collab/api' },   // the sibling api-collab in this project
+  },
+}
+```
+
+The `package` resolves the sibling api workspace package; its port is auto-discovered, and codegen pulls its typed rpc surface so the hooks are end-to-end typed.
+
+## The collaborative loop
+
+The page keeps a **local `crdtText()` handle** (`@voltro/local-first`) seeded from the server state. Each keystroke applies a contiguous insert/delete to that handle and sends `handle.encode()` via `documents.setBody`; every incoming server body is **folded back** into the handle (idempotent), keeping every tab in sync. The convergence is authoritative and server-side — the api merges each update into the stored state before broadcasting.
+
+```tsx
+// src/pages/page.tsx
+import { useMutation, useSubscription } from '@voltro/client'
+import { useEffect, useRef, useState } from 'react'
+import { crdtText, emptyCrdtState, type CrdtState, type CrdtText } from '@voltro/local-first'
+
+interface DocRow {
+  readonly id: string
+  readonly title: string
+  readonly body: Uint8Array | null // encoded CRDT state (base64 on the wire)
+}
+
+const Editor = ({ doc, onUpdate }: {
+  readonly doc: DocRow
+  readonly onUpdate: (update: CrdtState) => void
+}) => {
+  // One LOCAL CRDT handle per mount, seeded from the current server state.
+  const handleRef = useRef<CrdtText | null>(null)
+  if (handleRef.current === null) handleRef.current = crdtText().merge(doc.body ?? emptyCrdtState())
+  const [text, setText] = useState(() => handleRef.current!.toString())
+
+  // Fold every incoming server body back into the local handle (idempotent) —
+  // remote edits appear and converge.
+  useEffect(() => {
+    const handle = handleRef.current!
+    handle.merge(doc.body ?? emptyCrdtState())
+    setText(handle.toString())
+  }, [doc.body])
+
+  const onChange = (next: string) => {
+    const handle = handleRef.current!
+    // (diff prev → next into a contiguous insert/delete — see the shipped page)
+    setText(next)
+    onUpdate(handle.encode()) // full encoded state; the server folds it in
+  }
+
+  return <textarea value={text} onChange={(event) => onChange(event.target.value)} rows={12} />
+}
+
+const IndexPage = () => {
+  // ONE live subscription; `data` re-renders on every write (this tab or another).
+  const { data } = useSubscription<ReadonlyArray<DocRow>>('app', 'documents.list')
+  const setBody = useMutation<{ id: string; update: CrdtState }>('app', 'documents.setBody')
+
+  const doc = (data ?? [])[0]
+  if (doc === undefined) return null
+
+  // Remount (key={doc.id}) when the bound document changes, so the handle's
+  // lifecycle is scoped to it.
+  return <Editor key={doc.id} doc={doc} onUpdate={(update) => setBody.mutate({ id: doc.id, update })} />
+}
+
+export default IndexPage
+```
+
+1. **`useSubscription('app', 'documents.list')`** streams the shared document, including its **merged** `body`, on every write.
+2. Each keystroke applies to the local handle and sends `handle.encode()` via **`useMutation('app', 'documents.setBody')`** — no `.withOptimistic`, no polling.
+3. The api's **authoritative server-side merge** folds the update into the stored state before broadcasting, so concurrent edits converge.
+4. Incoming server bodies are folded back into the handle (idempotent), keeping every tab in sync.
+
+This page is exactly the app-level binding the local-first docs describe as the `SyncClient` transport: `push` is the `setBody` mutation, `onRemoteState` is the `documents` subscription.
+
+## Not wired here: presence cursors
+
+Live "who else is editing" cursors (`usePresence` from `@voltro/local-first/react`) need a `PresenceChannel` bound to the app's broadcast broker — a runtime binding, not zero-infra in a single dev process across tabs — so this template omits them. The CRDT **text** convergence above needs none of that; it rides the reactive engine you already have. Wire presence when you add the broker binding.
+
+## Bilingual by default
+
+Like every frontend template, `frontend-collab` ships en/de with cookie i18n: nav labels and page copy come from `src/locales/{en,de}.ts` via `<T>` / `useT()`, and `<LocaleSwitcher>` writes the `voltro:locale` cookie. The `de.ts` catalog mirrors every key in `en.ts` — a missing translation fails typecheck.
+
+## When to use
+
+| You want… | Pick |
+|---|---|
+| A collaborative / local-first editor over the reactive loop | `frontend-collab` (+ `api-collab`) |
+| The plain reactive list+form loop (no CRDT) | [`frontend-app`](/docs/templates/app) (+ `api-backend`) |
+| Just the CRDT backend | [`api-collab`](/docs/templates/api-collab) |
+
+## Anti-patterns
+
+- **Scaffolding `frontend-collab` without `api-collab`.** It depends on the sibling `@<project>/api` workspace package — `pnpm install` fails without it. Always scaffold the pair.
+- **Binding the textarea to the raw server bytes.** Bind it to the **local handle's** string; fold incoming server bodies into that handle. Re-seeding the handle on every delta would drop in-flight local keystrokes.
+- **Sending the whole textarea value as text.** Send the handle's `encode()` — the encoded CRDT state is what the server merges. Overwriting with plain text throws away the convergence guarantee.
+- **Reaching for presence before the broker exists.** `usePresence` needs a bound `PresenceChannel`; it is a documented seam, not part of the zero-infra text-convergence path.

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

@@ -0,0 +1,60 @@
+# templates.mobile
+
+> An Expo (React Native) app that is the third consumer of your api — the same typed hooks (useSubscription / useMutation), offline-first by default, typed deep links, and device registration for push. Expo owns Metro; voltro dev runs the sibling api.
+
+
+
+---
+
+<!-- source: en/templates/mobile-app.md -->
+## Mobile app (Expo)
+
+_An Expo (React Native) app that is the third consumer of your api — the same typed hooks (useSubscription / useMutation), offline-first by default, typed deep links, and device registration for push. Expo owns Metro; voltro dev runs the sibling api._
+
+An [Expo](https://expo.dev) (React Native) app that consumes your Voltro api as a **third client** — alongside the web frontend — with the **same typed hooks** you already use. Template id: **`mobile-app`** (kind: `mobile`).
+
+> **Expo owns the dev loop, not `voltro dev`.** A mobile app is started with `expo start` / `expo run:ios`, not `voltro dev`. The sibling api still runs under `voltro dev`; the app connects to it over the network. That is why a `mobile` app gets no port and is not part of `voltro dev`'s orchestration.
+
+## Scaffold
+
+```bash
+# A project with a backend + a mobile app:
+voltro create-project acme --api=api-backend --mobile
+
+# …or add one to an existing project later:
+voltro add-app mobile --template=mobile-app --to acme
+```
+
+## What ships
+
+```text
+mobile-app/
+  app.config.ts            # EXPO config (scheme for deep links, plugins)
+  metro.config.js          # monorepo watchFolders so @voltro/* resolve
+  voltro.mobile.ts         # which api(s) this app consumes
+  src/
+    client.ts              # the Voltro client + the M0 seam (read its header)
+    persistence.ts         # RN key-value with a secure/plain split
+    lib/
+      deeplinks.ts         # the typed deep-link table + pure resolver  (tested)
+      sync.ts              # the background-sync decision layer          (tested)
+      notifications.ts     # build a _voltro_devices row from a token    (tested)
+    app/                   # Expo Router screens (list · detail · settings)
+  tests/                   # pure-logic tests (no simulator needed)
+```
+
+## The reactive loop, on a phone
+
+The screens use the **same hooks as the web frontend** — `useSubscription('app', 'notes.list')` streams the server query; `useMutation('app', 'notes.create')` writes it; a server delta re-renders the list. No refetch, no polling. Offline-first is the default: `offlineFirstDefaults` + an RN persistence adapter mean the app opens offline, queues mutations, and reconciles on reconnect, with a first-class connection banner.
+
+Deep links are typed and go through one table: a universal link, a custom-scheme URL, and a push payload's `data.deepLink` all resolve via the same `matchFirstDeepLink` path.
+
+## Honest status — read before you expect the loop on a device
+
+The **pure logic** (`src/lib/*`) is real and unit-tested (`pnpm test`, no simulator). The **client wiring** — building the runtime + subscription cache + rpc client the hooks read — is **not yet implemented for React Native**: on the web it lives in `@voltro/web`'s web-coupled boot. Wiring an RN-safe equivalent is Phase **M0** of the framework's mobile plan. Until it lands, `buildApiHandles()` in `src/client.ts` returns an empty map and the screens show their loading state — deliberately, not a crash. Its header spells out exactly what M0 must build.
+
+Booting the app on a device (`expo run:ios`) is your Expo/EAS CI step — there is no iOS/Android toolchain in the framework repo.
+
+## Prefer pure-native (SwiftUI / Compose)?
+
+You do not need React Native. `voltro build api --target swift` (or `--target kotlin`) emits a typed native SDK package from your api — see [React Native & mobile](/docs/react-native/overview).

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

@@ -1,6 +1,6 @@
 # Templates
 
-> Thirty-four dogfooded starter templates ship with the framework — twenty backend shapes, thirteen frontend shapes, and a serverless function library. Scaffold any of them with one CLI call.
+> Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call.
 
 
 
@@ -9,9 +9,9 @@
 <!-- source: en/templates/overview.md -->
 ## Overview
 
-_Thirty-four dogfooded starter templates ship with the framework — twenty backend shapes, thirteen frontend shapes, and a serverless function library. Scaffold any of them with one CLI call._
+_Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call._
 
-Voltro ships **thirty-four** starter templates across the **three kinds** you actually deploy: **twenty** backends (`api-*`), **thirteen** frontends (`frontend-*` plus `changelog`), and **one** serverless library (`edge-functions`). Each is a small, opinionated, dogfooded reference you scaffold once and then own — no update channel, no lock-in.
+Voltro ships **thirty-eight** starter templates across the **four kinds** you actually deploy: **twenty-two** backends (`api-*`), **fourteen** frontends (`frontend-*` plus `changelog`), **one** serverless library (`edge-functions`), and **one** Expo mobile app (`mobile-app`). Each is a small, opinionated, dogfooded reference you scaffold once and then own — no update channel, no lock-in.
 
 The CLI loads templates by walking `voltro-templates/apps/<id>/`; the directory name IS the template id you pass to `--api` / `--web` / `--template`. Run `voltro list-templates` to see them live.
 
@@ -52,19 +52,21 @@ The four `api-backend*` shapes share the same minimal `notes` domain and differ
 | [`api-versioning`](/docs/templates/api-versioning) | **Row history + time-travel** — `@voltro/plugin-versioning` snapshots every write via the change tap; `rowHistory()` (every version) + `rowAsOf()` (value at a past instant), read through handlers. Memory store. |
 | [`api-backend-deactivation`](/docs/templates/api-backend-deactivation) | **The `deactivation()` mixin** — lock a user out (`deactivatedAt`) while the row stays VISIBLE/queryable — the deliberate opposite of `softDelete()`'s hide+anonymise. Pure schema. |
 | [`api-governance`](/docs/templates/api-governance) | **Field encryption + GDPR + consent + retention** — `@voltro/plugin-governance`: AES-256-GCM `.encrypted()` columns (plaintext to handlers, ciphertext at rest), admin-gated `governance.export`/`erase`, a consent ledger, retention sweeps. |
+| [`api-collab`](/docs/templates/api-collab) | **Local-first / CRDT collaborative editing** — a `documents` table with a `crdtText()` `body`; concurrent edits from many clients CONVERGE via an authoritative server-side merge on the write path (no last-write-wins loser), then broadcast over the reactive engine. Zero-infra; pairs with `frontend-collab`. |
 
-All twenty are `kind: 'api'`.
+All twenty-two are `kind: 'api'`.
 
 ## Frontend templates (`--web=<id>`)
 
-Thirteen web shapes spanning every render mode — `static`, `spa`, `ssr`, `isr`, selective `islands` hydration — plus the reactive fullstack loop.
+Fourteen web shapes spanning every render mode — `static`, `spa`, `ssr`, `isr`, selective `islands` hydration — plus the reactive fullstack loop (and its local-first / CRDT variant).
 
 **Every frontend template is bilingual (en/de) out of the box**, with the i18n strategy matched to its render mode: the hydrated/SSR shells use cookie i18n (`<LocaleSwitcher>`), the static/islands sites use URL-prefix i18n (`/de/…`, one pre-rendered HTML file per locale). `frontend-i18n` remains the dedicated URL-prefix reference. See [URL strategies](/docs/i18n/url-strategies) for why render mode decides.
 
 | Template | Render mode | Best for |
 |---|---|---|
 | [`frontend-blank`](/docs/templates/blank) | — | Empty React + Vite shell with a layout and an index page. Start here for any custom UI. |
-| [`frontend-app`](/docs/templates/app) | `full` · reactive | **The reactive end-to-end loop** — a web frontend WIRED to an api (`useSubscription` + `useMutation` + auto-optimistic). The only fullstack template; pairs with `api-backend`. |
+| [`frontend-app`](/docs/templates/app) | `full` · reactive | **The reactive end-to-end loop** — a web frontend WIRED to an api (`useSubscription` + `useMutation` + auto-optimistic). Pairs with `api-backend`. |
+| [`collab`](/docs/templates/collab) | `full` · reactive · CRDT | **Local-first collaborative editor** — a textarea bound to a `crdtText()` body; type in two tabs at once and the edits CONVERGE (server-authoritative CRDT merge, no last-write-wins loser). Fullstack; pairs with `api-collab`. |
 | [`frontend-dashboard`](/docs/templates/dashboard) | `static` + `ssr` | **Auth-gated app shell** — a silent `(marketing)` route group + a `/dashboard` area gated by a nested layout loader that `RedirectError`s to `/login`. Scoped error/loading/not-found. No backend. |
 | [`frontend-admin`](/docs/templates/admin) | `ssr` · reactive | **Auto-admin back-office** — discovers your api's entities at runtime (capability map) and renders a live, permission-gated `<DataTable>` + `<AutoForm>` per entity, with provenance + undo. Editable template code; pairs with any api. |
 | [`frontend-landing`](/docs/templates/landing) | `static` · `islands` | Marketing landing — hero, features grid, CTA. Zero JS by default; flip `interactive: 'islands'` for interactive pieces. |
@@ -77,7 +79,7 @@ Thirteen web shapes spanning every render mode — `static`, `spa`, `ssr`, `isr`
 | [`frontend-ssr-api`](/docs/templates/ssr-api) | `ssr` · fed by api | **SSR from your backend** — an `ssr` loader calls `query('notes.list', {})` over the sibling api's POST /rpc, so real rows are in the first paint + `<title>`; `useSubscription` upgrades to live. Pairs with `api-backend`. |
 | [`frontend-contact`](/docs/templates/contact) | `static` + serverless | **Static page + a serverless email form** — the headline "static frontend, serverless backend" combo. The page ships to a CDN; the function scales to zero. |
 
-All thirteen are `kind: 'web'`. The CLI rejects an api template passed to `--web` (and vice-versa) on a kind mismatch.
+All fourteen are `kind: 'web'`. The CLI rejects an api template passed to `--web` (and vice-versa) on a kind mismatch.
 
 ## Serverless template (`--template=<id>` via `add-app`)
 
@@ -87,6 +89,14 @@ All thirteen are `kind: 'web'`. The CLI rejects an api template passed to `--web
 
 `kind: 'serverless'` — added to a project with `voltro add-app <name> --template=edge-functions`.
 
+## Mobile template (`--mobile`)
+
+| Template | Best for |
+|---|---|
+| [`mobile-app`](/docs/templates/mobile-app) | An **Expo (React Native) app** — the third consumer of your api, with the same typed hooks, offline-first defaults, typed deep links, and device registration for push. |
+
+`kind: 'mobile'` — scaffold with `voltro create-project <name> --mobile` or `voltro add-app <name> --template=mobile-app`. A mobile app gets **no port** and is **not** run by `voltro dev`: Expo owns Metro (`expo start` / `expo run:ios`), and the app connects to the sibling api over the network. Its pure logic is unit-tested; the on-device reactive loop depends on the mobile plan's M0 (see [React Native & mobile](/docs/react-native/overview)).
+
 ## Static + serverless combo
 
 The most common no-always-on-server shape: **a static page on a CDN + a serverless function for the one dynamic bit.** `frontend-contact` ships it whole — a static page whose island form POSTs to a bundled `*.serverless.ts` that sends mail. Or add `edge-functions` to any static web template and wire the page to whichever function it needs. The function's local dev server sends CORS headers (same as the edge hosts), so the cross-origin form works out of the box.