@voltro/cli 0.1.0

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

@@ -0,0 +1,3214 @@
+# templates.apiBackends
+
+> The minimal Voltro backend — app.config + schema + one streaming query + one tenant-guarded mutation. Tenant-aware out of the box.
+
+
+
+---
+
+<!-- source: en/templates/api-backend.md -->
+## API · Backend
+
+_The minimal Voltro backend — app.config + schema + one streaming query + one tenant-guarded mutation. Tenant-aware out of the box._
+
+The minimal but complete api template: an `app.config.ts`, a one-table schema, one streaming query, and one tenant-guarded mutation. It's the smallest reference that shows the framework's core file convention — the **descriptor / `.server.ts` executor split** — and the tenant-scoping guard. Start here when you're not sure which api template fits. Template id: **`api-backend`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-backend
+```
+
+## What ships
+
+```text
+apps/acme/api/                          # dir named by the app, not the template
+├── app.config.ts                       # type:api, name, store:'memory'
+├── package.json
+├── tsconfig.json
+├── README.md
+├── database/
+│   └── schema.ts                       # actors + tenants (core) + a notes table
+├── queries/
+│   ├── notes.query.ts                  # descriptor — browser-safe
+│   └── notes.query.server.ts           # server executor — default export
+└── mutations/
+    ├── notes.create.mutation.ts        # descriptor — browser-safe
+    └── notes.create.mutation.server.ts # server executor — default export
+```
+
+No actions, workflows, agents, or `AGENTS.md` ship — this template is deliberately the smallest working shape. The mail / storage / mariadb variants build on this same `notes` base.
+
+## The descriptor / `.server.ts` split
+
+Every query / mutation / action is **two files paired by basename**: a browser-safe descriptor (`*.query.ts` / `*.mutation.ts`) holding `defineQuery` / `defineMutation`, and a server-only executor (`*.query.server.ts` / `*.mutation.server.ts`) with a default export. The framework pairs them at boot. The descriptor file must never import `node:*` / database / runtime modules — it's what the web client pulls through codegen.
+
+### Query — `queries/notes.query.ts` + `.server.ts`
+
+```ts
+// notes.query.ts — descriptor (browser-safe)
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name: 'notes.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String, title: Schema.String, body: Schema.String,
+    done: Schema.Boolean, tenantId: Schema.String, createdAt: Schema.Date,
+  }),
+})
+```
+
+```ts
+// notes.query.server.ts — executor (default export)
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'notes' as const,
+    order: [{ column: 'createdAt' as const, direction: 'desc' as const }],
+    take: 100,
+    // tenant scope is AND-merged by the runtime — no manual eq('tenantId', …)
+  },
+})
+
+export default execute
+```
+
+### Mutation — `mutations/notes.create.mutation.ts` + `.server.ts`
+
+```ts
+// notes.create.mutation.ts — descriptor
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy'
+import { Schema } from 'effect'
+
+export const createNote = defineMutation({
+  name: 'notes.create',
+  target: { table: 'notes', op: 'insert',
+    shape: (input: { tenantId: string; title: string; body: string }) => ({
+      title: input.title, body: input.body, done: false,
+      tenantId: input.tenantId, createdAt: new Date(),
+    }) },
+  input:  Schema.Struct({ tenantId: Schema.String, title: Schema.NonEmptyString, body: Schema.String }),
+  output: Schema.Struct({ /* id, title, body, done, tenantId, createdAt */ }),
+  error:  TenantMismatch,
+})
+```
+
+```ts
+// notes.create.mutation.server.ts — executor
+import { assertOwnTenant } from '@voltro/plugin-multitenancy'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (input: { tenantId: string; title: string; body: string }, ctx: AppContext) => {
+  // Cross-tenant write guard — input.tenantId MUST match the subject's,
+  // else the rpc layer surfaces a typed TenantMismatch.
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+  // The framework auto-injects a `note_…` TypeID from the table's id() decl.
+  return ctx.store.insert('notes', {
+    title: input.title, body: input.body, done: false,
+    tenantId: input.tenantId, createdAt: new Date(),
+  })
+}
+
+export default execute
+```
+
+## Database
+
+The shipped schema declares the two framework core tables plus one example table:
+
+```ts
+// database/schema.ts
+import { boolean, databaseHandle, id, table, text, timestamp, type InferRow } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// Core tables — required by the audit / tenant mixins.
+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') })
+
+// Application table — rename / replace with your own.
+export const notes = table('notes', {
+  id: id({ prefix: 'note' }), title: text(), body: text(), done: boolean().default(false),
+})
+  .with(tenant())   // pulls audit() transitively → tenantId + createdAt/updatedAt/createdBy/updatedBy
+  .reactive()       // subscriptions get a fresh snapshot/delta on every write to notes
+
+export type Note = InferRow<typeof notes>
+export const database = databaseHandle({ actors, tenants, notes })
+```
+
+`tenant()` makes the table tenant-scoped: the runtime AND-merges `eq('tenantId', subject.tenantId)` into every subscription predicate, so cross-tenant reads can't leak.
+
+## Store — memory by default
+
+`app.config.ts` ships `store: 'memory'` — fast startup, no Docker, data resets on restart. Good for dev, tests, and a first impression. Switch to a real SQL backend by setting the dialect + connection env (or `store:` in `app.config.ts`):
+
+```bash
+DB_DIALECT=postgres DB_URL=postgres://app:app@localhost:5432/acme voltro dev .
+```
+
+`voltro dev` against a SQL store auto-migrates the discovered schema before any handler boots. See the SQL dialects guide for `mysql` / `mariadb` / `mssql` / `sqlite` / `turso`.
+
+## Discovery
+
+`voltro dev .` walks the app for the file conventions — `*.query.ts` + `*.query.server.ts`, `*.mutation.ts` + `*.mutation.server.ts`, `*.action.ts` + `*.action.server.ts`, `*.workflow.tsx`, `*.cron.tsx`, `schema.ts` / `*.entity.ts` — pairs each descriptor with its `.server.ts` executor, and rewrites `rpcGroup.generated.ts` (the typed client). Drop more files anywhere in the tree; nothing is registered manually.
+
+## When to use api-backend vs. the variants
+
+| You need… | Pick |
+|---|---|
+| The smallest reference to extend | `api-backend` |
+| Transactional email wired (React-Email) | [`api-backend-mail`](/docs/templates/api-backend-mail) |
+| File storage wired (public + private objects) | [`api-backend-storage`](/docs/templates/api-backend-storage) |
+| MariaDB binlog CDC + storage (K8s shape) | [`api-backend-mariadb`](/docs/templates/api-backend-mariadb) |
+
+All four share this `notes` base; the variants just wire a plugin / store on top.
+
+## Pairs well with
+
+- Any web template — `api-backend` is the most generic api.
+- [`@voltro/plugin-auth`](/docs/plugins/auth) — wire it in for real sign-in.
+
+## Anti-patterns
+
+- **Putting `node:*` / database imports in a descriptor (`*.query.ts`).** Those files reach the browser bundle through codegen. Keep server-only code in the `.server.ts` half.
+- **Dropping the cross-tenant write guard.** Tables with `tenant()` get automatic SUBSCRIPTION scoping, but a mutation that writes raw rows still needs `assertOwnTenant(input.tenantId, ctx.request.subject)` — without it a client authenticated as A can submit `tenantId: 'B'` and the row lands in B's data.
+- **Discovery walker as a security boundary.** It picks up everything matching the pattern. Every discovered descriptor is exposed via the rpc client — don't put secrets in one.
+
+
+
+---
+
+<!-- source: en/templates/api-backend-mail.md -->
+## API · Backend + Mail
+
+_The api-backend base plus transactional email wired — @voltro/plugin-mail and a React-Email welcome template you preview and send from the dashboard._
+
+The same minimal `notes` base as [`api-backend`](/docs/templates/api-backend), plus transactional email wired out of the box via [`@voltro/plugin-mail`](/docs/plugins/mail). It ships a React-Email welcome template and a `mail.sendWelcome` action. Template id: **`api-backend-mail`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-backend-mail
+```
+
+## What ships
+
+```text
+apps/acme/api/                          # dir named by the app, not the template
+├── app.config.ts                       # api + mailPlugin({ provider: 'console' })
+├── package.json
+├── tsconfig.json
+├── README.md
+├── database/
+│   └── schema.ts                       # actors + tenants + notes (same as api-backend)
+├── queries/
+│   ├── notes.query.ts + .query.server.ts
+├── mutations/
+│   └── notes.create.mutation.ts + .mutation.server.ts
+├── emails/
+│   └── welcome.email.tsx               # a React-Email welcome template
+└── actions/
+    └── sendWelcome.action.ts + .action.server.ts   # mail.sendWelcome
+```
+
+## The wiring
+
+`app.config.ts` adds the mail plugin with the zero-config `console` provider:
+
+```ts
+import { mailPlugin } from '@voltro/plugin-mail'
+
+export default {
+  type: 'api' as const,
+  name: '{{projectNamePascal}}{{appNamePascal}}',
+  store: 'memory' as const,
+  plugins: [
+    mailPlugin({ provider: 'console', from: '{{projectNamePascal}} <hello@example.com>' }),
+  ],
+}
+```
+
+The `console` provider **logs** what would be sent (no API key) and captures it in the dashboard outbox. For real delivery, switch `provider` to `'resend'` / `'postmark'` / `'sendgrid'` / `'smtp'` and set the matching env var (e.g. `RESEND_API_KEY`).
+
+## The email template — `emails/welcome.email.tsx`
+
+Authored with `defineEmail` + `@react-email/components`. Auto-discovered by `voltro dev` and registered with the plugin, so `mail.send({ template: 'welcome', props })` works and the dashboard Mail panel previews it:
+
+```tsx
+import { defineEmail } from '@voltro/plugin-mail'
+import { Body, Button, Container, Heading, Html, Text } from '@react-email/components'
+import { Schema } from 'effect'
+
+export const welcome = defineEmail({
+  name: 'welcome',
+  props: Schema.Struct({ name: Schema.String }),
+  preview: { name: 'Mario' },                 // pre-fills the dashboard preview box
+  subject: (p) => `Welcome, ${p.name}!`,
+  render: (p) => (
+    <Html><Body><Container>
+      <Heading>Welcome, {p.name} 👋</Heading>
+      <Text>Your workspace is ready.</Text>
+      <Button href="https://example.com/dashboard">Open your dashboard</Button>
+    </Container></Body></Html>
+  ),
+})
+```
+
+The shipped template carries `prefers-color-scheme` dark-mode handling and inline styles for email-client compatibility — replace the copy and brand for your product.
+
+## Sending — `actions/sendWelcome.action.ts` + `.server.ts`
+
+Email is external I/O, so it's an **action**, not a mutation. The descriptor declares the wire shape; the `.server.ts` executor calls `MailService`:
+
+```ts
+// sendWelcome.action.server.ts
+import { Effect } from 'effect'
+import { MailService } from '@voltro/plugin-mail'
+
+const execute = (input: { email: string; name: string }) =>
+  Effect.gen(function* () {
+    const mail = yield* MailService
+    const res = yield* mail.send({ to: input.email, template: 'welcome', props: { name: input.name } })
+    return { id: res.id, provider: res.provider }
+  })
+
+export default execute
+```
+
+Preview templates and inspect the dev outbox in the dashboard's **Mail** tab.
+
+## Pairs well with
+
+- Any web template — wire the `mail.sendWelcome` action behind a signup flow.
+
+## See also
+
+- [`@voltro/plugin-mail`](/docs/plugins/mail) — providers, templates, suppression, durable delivery.
+- [`api-backend`](/docs/templates/api-backend) — the base this builds on.
+
+
+
+---
+
+<!-- source: en/templates/api-backend-storage.md -->
+## API · Backend + Storage
+
+_The api-backend base plus file storage wired — @voltro/plugin-storage with public (CDN-direct) and private (policy + grants) objects, with upload examples._
+
+The same minimal `notes` base as [`api-backend`](/docs/templates/api-backend), plus file storage wired out of the box via [`@voltro/plugin-storage`](/docs/plugins/storage). It ships two upload actions demonstrating the public and private object classes. Template id: **`api-backend-storage`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-backend-storage
+```
+
+## What ships
+
+```text
+apps/acme/api/                          # dir named by the app, not the template
+├── app.config.ts                       # api + storagePlugin({ provider: 'memory' })
+├── package.json
+├── tsconfig.json
+├── README.md
+├── database/
+│   └── schema.ts                       # actors + tenants + notes (same as api-backend)
+├── queries/
+│   └── notes.query.ts + .query.server.ts
+├── mutations/
+│   └── notes.create.mutation.ts + .mutation.server.ts
+└── actions/
+    ├── uploadAvatar.action.ts + .action.server.ts      # storage.uploadAvatar — PUBLIC
+    └── uploadDocument.action.ts + .action.server.ts    # storage.uploadDocument — PRIVATE
+```
+
+## The wiring
+
+`app.config.ts` adds the storage plugin with the zero-config `memory` provider:
+
+```ts
+import { storagePlugin } from '@voltro/plugin-storage'
+
+export default {
+  type: 'api' as const,
+  name: '{{projectNamePascal}}{{appNamePascal}}',
+  store: 'memory' as const,
+  plugins: [
+    storagePlugin({ provider: 'memory' }),
+  ],
+}
+```
+
+The `memory` provider keeps blobs in-process (dev only). Swap to `'s3'` / `'minio'` (any S3-compatible bucket via `endpoint` — AWS, R2, GCS, B2, Wasabi), `'azure'`, `'filesystem'`, or `'database'` for real object storage. Set `cdnBaseUrl` on the plugin for production public delivery.
+
+## Two object classes
+
+- **PUBLIC** (`visibility: 'public'`) — served direct from the bucket/CDN; the returned `url` is what you put in an `<img src>`. The app's serve route is only a dev fallback.
+- **PRIVATE** (default) — gated by an **access policy** (any-of rules over `owner` / `roles` / `groups` / `scopes` / `tenant` / `apiKey` / `password` / a custom `guard`) PLUS **per-object grants** (share a file with a specific user / group / api-key, optionally expiring).
+
+### `actions/uploadAvatar.action.server.ts` — a PUBLIC object
+
+```ts
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { StorageService } from '@voltro/plugin-storage'
+
+const execute = (input: { bytesBase64: string; contentType: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const storage = yield* StorageService
+    const bytes = new Uint8Array(Buffer.from(input.bytesBase64, 'base64'))
+    const ref = yield* storage.put({
+      bytes, contentType: input.contentType,
+      visibility: 'public',
+      ownerId: ctx.request.subject.id, tenantId: ctx.request.subject.tenantId,
+      key: `avatars/${ctx.request.subject.id ?? 'anon'}/avatar`,
+    })
+    const url = yield* storage.getUrl(ref.id)
+    return { id: ref.id, url }
+  })
+
+export default execute
+```
+
+The shipped `uploadDocument` action mirrors this with `visibility: 'private'` so the file is access-checked on read. File upload is external I/O → an action, not a mutation. For large files prefer a presigned direct-to-bucket upload via the plugin's built-in `storage.mintUploadUrl` route.
+
+## Built-in routes + serve endpoint
+
+The plugin ships typed client routes — `storage.upload`, `storage.mintUrl`, `storage.mintUploadUrl`, `storage.share`, `storage.revoke`, `storage.listGrants` — plus the serve endpoint `GET /_voltro/storage/:id` (public → 302 to CDN; private → access-checked). Browse and share stored objects from the dashboard's **Storage** tab. `_voltro_storage_refs` + `_voltro_storage_grants` are auto-migrated on a SQL store.
+
+## Pairs well with
+
+- Any web template — wire the upload actions behind a file picker.
+
+## See also
+
+- [`@voltro/plugin-storage`](/docs/plugins/storage) — providers, access policies, grants, upload constraints, virus scanning, image transforms.
+- [`api-backend`](/docs/templates/api-backend) — the base this builds on.
+
+
+
+---
+
+<!-- source: en/templates/api-backend-mariadb.md -->
+## API · Backend (MariaDB)
+
+_MariaDB-backed Voltro backend — binlog CDC real-time across replicas plus file storage. The dogfooded shape for K8s multi-replica apps._
+
+The `notes` base wired for **MariaDB**: `store: 'mariadb'` turns on the binlog CDC reader so reactive subscriptions fan out across every replica via the database's binary log — no Redis/NATS, the binlog IS the message bus. File storage is on by default. This is the local-dev mirror of the `helm` MariaDB production shape. Template id: **`api-backend-mariadb`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-backend-mariadb --baseline=compose-mariadb
+```
+
+Pair it with the `compose-mariadb` baseline (or `helm`): MariaDB must run with `binlog_format=ROW` + `binlog_row_image=FULL` and a user holding `REPLICATION SLAVE, REPLICATION CLIENT`, plus MinIO/S3 for storage. The `compose-mariadb` baseline sets all of this up with one `pnpm db:up`.
+
+## What ships
+
+```text
+apps/acme/api/                          # dir named by the app, not the template
+├── app.config.ts                       # store:'mariadb' + storagePlugin()
+├── .env.example                        # DB / storage / AI / auth / cluster env
+├── package.json
+├── tsconfig.json
+├── README.md
+├── database/
+│   └── schema.ts                       # actors + tenants + notes (same as api-backend)
+├── queries/
+│   └── notes.query.ts + .query.server.ts
+└── mutations/
+    └── notes.create.mutation.ts + .mutation.server.ts
+```
+
+## The wiring
+
+```ts
+// app.config.ts
+import { storagePlugin } from '@voltro/plugin-storage'
+
+export default {
+  type: 'api' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  store: 'mariadb' as const,        // turns on binlog CDC
+  plugins: [
+    // Blobs in object storage (MinIO locally, S3 in prod); metadata in
+    // _voltro_storage_refs. Provider resolved from STORAGE_PROVIDER.
+    storagePlugin(),
+  ],
+}
+```
+
+The shipped `app.config.ts` also carries commented-out `jwtBearerStrategy` + `apiKeyStrategy` blocks under an `auth:` key — uncomment and configure them to wire your IdP / API keys.
+
+## Environment — `.env.example`
+
+Copy to `.env` and adjust. The key vars:
+
+```bash
+# Database (MariaDB + binlog CDC)
+DB_DIALECT=mariadb
+DB_URL=mysql://app:app@localhost:3307/{{projectNameSnake}}
+CDC=1                                   # push-based real-time across replicas (set 0 for inline-only)
+
+# File storage — MinIO locally, S3 in prod
+STORAGE_PROVIDER=minio
+S3_ENDPOINT=http://localhost:9000
+S3_BUCKET={{projectNameSnake}}
+S3_ACCESS_KEY_ID=minioadmin
+S3_SECRET_ACCESS_KEY=minioadmin
+S3_FORCE_PATH_STYLE=1
+
+# Auth — HMAC key for signed sessions (REQUIRED in production)
+VOLTRO_SESSION_SECRET=dev-only-change-me
+
+# Cluster (K8s, >1 replica) — advertise a routable host so a workflow
+# can resume on another pod. Inject POD_IP via the downward API in prod.
+# VOLTRO_WORKFLOW_RUNNER_HOST=
+```
+
+## Why MariaDB CDC
+
+Behind a load balancer each live client WebSocket lives on one replica. A mutation runs on one replica; without cross-instance fan-out, other replicas' clients go stale. MariaDB's ROW-format binlog is one of the two dialects (with postgres `LISTEN/NOTIFY`) that observe writes across instances natively — `CDC=1` reads the binlog and injects remote change events into every replica's store. With `CDC=0` it falls back to single-process inline emit.
+
+## Boot
+
+```bash
+pnpm install
+cp .env.example .env                    # then adjust DB_URL / secrets
+# Start MariaDB (binlog ROW) + MinIO — the compose-mariadb baseline does this:
+pnpm db:up
+pnpm --filter @acme/api dev
+```
+
+`voltro dev` against MariaDB auto-migrates the schema before any handler boots, and the boot log confirms `CDC: binlog CDC (ROW)`.
+
+## Pairs well with
+
+- The [`compose-mariadb` baseline](/docs/templates/overview#baselines-the-deploy-layer) — local MariaDB + MinIO.
+- The `helm` baseline — the K8s production target (per-pod `server_id` + workflow-runner host).
+
+## See also
+
+- [`api-backend`](/docs/templates/api-backend) — the base this builds on.
+- [`@voltro/plugin-storage`](/docs/plugins/storage) — the storage plugin wired here.
+
+
+
+---
+
+<!-- source: en/templates/api-durable.md -->
+## API · Durable
+
+_A cohesive order-fulfillment domain that exercises the whole durable surface — a workflow with a human-approval gate, an event trigger, a signal-injecting mutation, a cron, a subscriber, an aggregate, and a startup hook. Zero-infra boot._
+
+The template that exercises the framework's **durable-execution surface** end-to-end. Instead of a one-table CRUD reference, it ships a cohesive **order-fulfillment** domain: placing an order emits a domain event, a trigger starts a durable workflow, the workflow reserves stock → sleeps → **parks on a human-approval gate**, and a second mutation injects the approval signal that wakes it. Around that flow it wires a nightly cron, a table subscriber, a materialized aggregate, and a run-once startup hook — every durable / scheduled / reactive primitive in one app. It boots with **zero infrastructure** (`store: 'memory'`). Template id: **`api-durable`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-durable
+```
+
+No env or services required. `store: 'memory'` runs the in-process durable workflow engine (replay within one process). Switch `app.config.ts` to `store: 'postgres'` (and `docker compose up`) when you want durable state across restarts + multi-instance cluster workflow runners.
+
+## What ships
+
+```text
+apps/acme/api/                                   # dir named by the app, not the template
+├── app.config.ts                                # type:api, store:'memory', defineEnv
+├── package.json
+├── tsconfig.json
+├── README.md
+├── database/
+│   └── schema.ts                                # actors + tenants (core) + an orders table
+├── mutations/
+│   ├── orders.place.mutation.ts                 # descriptor — insert + emit order.placed
+│   ├── orders.place.mutation.server.ts          # executor — tenant guard + post-commit emit
+│   ├── orders.approve.mutation.ts               # descriptor — the human-approval surface
+│   └── orders.approve.mutation.server.ts        # executor — inject the approval signal
+├── triggers/
+│   └── order.placed.trigger.tsx                 # event order.placed → start orders.fulfill
+├── workflows/
+│   ├── order.fulfill.workflow.tsx               # descriptor — browser-safe contract
+│   └── order.fulfill.workflow.server.tsx        # executor — step → sleep → awaitSignal → step
+├── schedules/
+│   └── nightlyReport.cron.tsx                   # cron 0 2 * * * (UTC) — per-status tally
+├── subscribers/
+│   └── orderChanges.subscribe.ts                # post-commit reaction to every orders write
+├── aggregates/
+│   └── orderStats.aggregate.ts                  # materialized per-tenant/per-status roll-up
+└── startup/
+    └── warm.startup.tsx                         # run-once boot hook + onShutdown teardown
+```
+
+Every primitive is **auto-discovered by file convention** — nothing is registered in `app.config.ts`. Compared to [`api-backend`](/docs/templates/api-backend) (the smallest CRUD reference), this template adds the workflow / trigger / schedule / subscriber / aggregate / startup conventions on top of the same descriptor-split mutation shape.
+
+## The end-to-end flow
+
+1. **Place an order** → `orders.place` inserts the row, then emits `order.placed` *after the transaction commits* — so a rollback never starts a workflow for an order that doesn't exist.
+2. **The trigger fires** → `order.placed.trigger.tsx` starts the durable `orders.fulfill` workflow with `{ orderId, tenantId }`.
+3. **The workflow runs durably** → reserves stock (with saga-style compensation), waits a journaled delay, then **parks on `awaitSignal('approval')`**.
+4. **A human approves** → `orders.approve` re-derives the run's deterministic executionId and injects the `approval` signal; the parked run wakes (sub-second) and either ships or marks the order rejected.
+
+Meanwhile the **subscriber** logs every `orders` write, the **aggregate** keeps a live per-status tally, the **schedule** reports nightly, and the **startup hook** holds a process-lifetime resource.
+
+## Database
+
+The schema declares the two framework core tables plus an `orders` table carrying the order lifecycle:
+
+```ts
+// database/schema.ts
+import {
+  databaseHandle, id, integer, table, text, timestamp, type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// Core tables — required by the audit / tenant mixins.
+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') })
+
+// Application table — the order-fulfillment domain.
+export const orders = table('orders', {
+  id:     id({ prefix: 'order' }),
+  // The fulfillment lifecycle. `oneOf` narrows the row type to the literal
+  // union AND emits a cross-dialect CHECK constraint.
+  status: text().oneOf(['placed', 'reserved', 'approved', 'rejected', 'shipped']).default('placed'),
+  customerName: text(),
+  amountCents:  integer(),
+})
+  .with(tenant())   // pulls audit() transitively → tenantId + createdAt/updatedAt/createdBy/updatedBy
+  .reactive()       // subscriber + live subscriptions wake on every write to orders
+
+export type Order = InferRow<typeof orders>
+export const database = databaseHandle({ actors, tenants, orders })
+```
+
+`tenant()` makes the table tenant-scoped: the runtime AND-merges `eq('tenantId', subject.tenantId)` into every subscription so cross-tenant reads can't leak. `.reactive()` opts the table into the matcher engine so the `orderChanges` subscriber and any live query fire on every mutation write. See [multi-tenancy](/docs/multi-tenancy/overview).
+
+## Place — mutation that emits a domain event
+
+`orders.place` is the entry point. The descriptor declares the optimistic `target` + typed error; the executor writes the row, guards the tenant, and emits `order.placed` **after commit**.
+
+```ts
+// orders.place.mutation.ts — descriptor (browser-safe)
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { Schema } from 'effect'
+
+export const placeOrder = defineMutation({
+  name: 'orders.place',
+  // Auto-optimistic: every query whose `source: 'orders'` matches gets a
+  // placeholder row prepended; the server delta replaces it on commit.
+  target: {
+    table: 'orders', op: 'insert',
+    shape: (input: { tenantId: string; customerName: string; amountCents: number }) => ({
+      status: 'placed', customerName: input.customerName,
+      amountCents: input.amountCents, tenantId: input.tenantId,
+    }),
+  },
+  input: Schema.Struct({
+    tenantId:     Schema.String,
+    customerName: Schema.NonEmptyString,
+    amountCents:  Schema.Int.pipe(Schema.greaterThan(0)),
+  }),
+  output: Schema.Struct({
+    id: Schema.String, status: Schema.String, customerName: Schema.String,
+    amountCents: Schema.Number, tenantId: Schema.String,
+  }),
+  error: TenantMismatch,
+})
+```
+
+```ts
+// orders.place.mutation.server.ts — executor (default export)
+import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (
+  input: { tenantId: string; customerName: string; amountCents: number },
+  ctx: AppContext,
+) => {
+  // Cross-tenant write guard — reject a caller spoofing input.tenantId.
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+
+  // Framework auto-injects an `order_…` id + the tenant/audit columns.
+  const row = await ctx.store.insert('orders', {
+    status: 'placed', customerName: input.customerName,
+    amountCents: input.amountCents, tenantId: input.tenantId,
+  })
+
+  // Post-commit fan-out → the `order.placed` trigger starts the
+  // `orders.fulfill` workflow. Guard `ctx.events` so a unit-test ctx
+  // without it doesn't throw.
+  await ctx.events?.emit('order.placed', {
+    orderId: row['id'] as string, tenantId: input.tenantId,
+  })
+
+  return {
+    id: row['id'] as string, status: row['status'] as string,
+    customerName: row['customerName'] as string,
+    amountCents: row['amountCents'] as number, tenantId: row['tenantId'] as string,
+  }
+}
+
+export default execute
+```
+
+`TenantMismatch` is imported from the browser-safe `@voltro/plugin-multitenancy/guard` subpath, NOT the package root — the root re-exports the schema mixin, which would drag `@voltro/database` into the client rpcGroup bundle. `ctx.events.emit(...)` is post-commit safe: the event is recorded and fans out only once the row is durably written.
+
+## Event trigger — start a workflow from a domain event
+
+The trigger maps the `order.placed` event to a workflow start. It's auto-discovered (`*.trigger.tsx`); no `app.config.ts` wiring. See [event triggers](/docs/workflows/event-triggers).
+
+```tsx
+// triggers/order.placed.trigger.tsx
+import { defineEventTrigger } from '@voltro/runtime'
+
+export default defineEventTrigger<
+  { orderId: string; tenantId: string }
+>({
+  event:    'order.placed',
+  workflow: 'orders.fulfill',
+  // Dedup deliveries: a re-delivered event (crash + replay) with the same
+  // key short-circuits the second start.
+  idempotencyKey: (event) => `order.placed:${event.data.orderId}`,
+})
+```
+
+The event payload IS the workflow payload here (both `{ orderId, tenantId }`), so no `payload` mapper is needed — pass one when the shapes differ.
+
+## Durable workflow — step → sleep → awaitSignal → step
+
+Like the rpc primitives, a workflow is **two files paired by basename**: a browser-safe `*.workflow.tsx` descriptor (the `workflow({...})` contract — schema + idempotency only) and a server-only `*.workflow.server.tsx` executor. See [workflows](/docs/workflows/overview).
+
+```tsx
+// workflows/order.fulfill.workflow.tsx — descriptor (browser-safe)
+import { workflow } from '@voltro/workflow/define'
+import { Schema } from 'effect'
+
+export const FulfillOrder = workflow({
+  name: 'orders.fulfill',
+  payload: {
+    orderId:  Schema.String,
+    tenantId: Schema.String,
+  },
+  success: Schema.Struct({
+    orderId: Schema.String,
+    outcome: Schema.Literal('shipped', 'rejected'),
+  }),
+  // Dedup concurrent starts for the same order — after a crash + replay the
+  // trigger could fan out twice; the same key collapses them to one run.
+  idempotencyKey: ({ orderId }) => `fulfill:${orderId}`,
+})
+```
+
+The descriptor imports `workflow` from the browser-safe `@voltro/workflow/define` subpath so the codegen can value-import it for the client; the executor imports `step` / `sleep` / `awaitSignal` from the full `@voltro/workflow`.
+
+```tsx
+// workflows/order.fulfill.workflow.server.tsx — executor (server-only)
+import { step, sleep, awaitSignal, withCompensation } from '@voltro/workflow'
+import { Effect, Schema } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+
+const Decision = Schema.Struct({ approved: Schema.Boolean })
+
+const buildExecute = (ctx: AppContext) =>
+  (payload: { orderId: string; tenantId: string }, _executionId: string) =>
+    Effect.gen(function* () {
+      const { orderId } = payload
+
+      // 1. Reserve stock. `withCompensation` registers an undo that runs
+      //    only if the workflow as a whole fails after this point.
+      yield* withCompensation(
+        step({
+          name:    'reserve-stock',
+          input:   { orderId },
+          success: Schema.Struct({ orderId: Schema.String }),
+          execute: Effect.tryPromise({
+            try:   async () => {
+              await ctx.store.update('orders', orderId, { status: 'reserved' })
+              return { orderId }
+            },
+            catch: (error) => error as never,
+          }),
+        }),
+        // Saga rollback: release the reservation on whole-workflow failure.
+        () =>
+          Effect.promise(() =>
+            ctx.store.update('orders', orderId, { status: 'placed' }).then(() => undefined),
+          ),
+      )
+
+      // 2. Durable delay. The wake is journaled — survives a restart.
+      yield* sleep({ name: 'settle-window', duration: '5 seconds' })
+
+      // 3. Human-approval gate. The run parks here until an external caller
+      //    sends a matching `approval` signal; the parsed payload is
+      //    journaled, so a post-signal replay returns it instantly.
+      const decision = yield* awaitSignal(ctx, {
+        name:   'approval',
+        schema: Decision,
+        // pollIntervalMs defaults to 200 (backoff → 5s); timeoutMs 24h.
+      })
+
+      if (!decision.approved) {
+        yield* step({
+          name:    'mark-rejected',
+          input:   { orderId },
+          success: Schema.Struct({ orderId: Schema.String }),
+          execute: Effect.tryPromise({
+            try:   async () => {
+              await ctx.store.update('orders', orderId, { status: 'rejected' })
+              return { orderId }
+            },
+            catch: (error) => error as never,
+          }),
+        })
+        return { orderId, outcome: 'rejected' as const }
+      }
+
+      // 4. Approved → ship.
+      yield* step({
+        name:    'ship',
+        input:   { orderId },
+        success: Schema.Struct({ orderId: Schema.String }),
+        execute: Effect.tryPromise({
+          try:   async () => {
+            await ctx.store.update('orders', orderId, { status: 'shipped' })
+            return { orderId }
+          },
+          catch: (error) => error as never,
+        }),
+      })
+
+      return { orderId, outcome: 'shipped' as const }
+    })
+
+export default buildExecute
+```
+
+Three durable primitives in one body: each `step()` is journaled (replayed from its cached result on a crash, never re-run); [`sleep`](/docs/workflows/sleep) is a journaled delay that survives a restart; `awaitSignal` parks the run until an external decision arrives. `withCompensation` adds a saga-style finalizer that runs only if the whole workflow later fails — releasing the reservation so a downstream failure doesn't strand held stock. The default export is a **factory** `(ctx) => execute`; the CLI calls `workflow.toLayer(execute)` so the executor closes over the live `AppContext`.
+
+## Approve — inject the signal that wakes the parked run
+
+`orders.approve` is the human-approval surface. It pokes the workflow rather than writing a row, so it declares no optimistic `target`.
+
+```ts
+// orders.approve.mutation.ts — descriptor (browser-safe)
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const approveOrder = defineMutation({
+  name: 'orders.approve',
+  input: Schema.Struct({
+    orderId:  Schema.String,
+    tenantId: Schema.String,
+    approved: Schema.Boolean,
+  }),
+  output: Schema.Struct({
+    orderId: Schema.String,
+    eventId: Schema.String,
+  }),
+})
+```
+
+```ts
+// orders.approve.mutation.server.ts — executor
+import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (
+  input: { orderId: string; tenantId: string; approved: boolean },
+  ctx: AppContext,
+) => {
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+
+  if (!ctx.workflows) {
+    throw new Error('orders.approve: workflow runtime is not available in this context')
+  }
+
+  // Deterministic executionId for the running fulfillment workflow — same
+  // payload the `order.placed` trigger started it with.
+  const executionId = await ctx.workflows.executionId('orders.fulfill', {
+    orderId:  input.orderId,
+    tenantId: input.tenantId,
+  })
+
+  const { eventId } = await ctx.workflows.signal(
+    { executionId },
+    'approval',
+    { approved: input.approved },
+  )
+
+  return { orderId: input.orderId, eventId }
+}
+
+export default execute
+```
+
+Because the workflow's `idempotencyKey` (`fulfill:<id>`) makes its executionId a deterministic function of the payload, the approve mutation re-derives it from `{ orderId, tenantId }` and addresses the signal by executionId — no need to track the run handle from the place mutation. `ctx.workflows.signal(...)` writes a `signal-sent` row to the run's events log; the workflow's `awaitSignal('approval')` poll picks it up and parses it against its `{ approved: boolean }` schema.
+
+## Schedule — a nightly cron
+
+A single-file `*.cron.tsx` schedule runs periodic work. `timezone` is mandatory; the cron is validated at boot. See [scheduling](/docs/scheduling/overview).
+
+```tsx
+// schedules/nightlyReport.cron.tsx
+import { defineSchedule } from '@voltro/runtime'
+import { count, eq } from '@voltro/database'
+import { database } from '../database/schema'
+
+export default defineSchedule({
+  name:     'nightlyReport',
+  cron:     '0 2 * * *',     // 02:00 every day
+  timezone: 'UTC',
+  description: 'Logs a per-status order tally each night.',
+  handler: async (ctx) => {
+    // Tally placed-but-not-yet-shipped orders as a simple health signal.
+    const open = await ctx.app.store.query(
+      database.orders.where(eq('status', 'placed')).aggregate({ total: count() }).descriptor,
+    )
+    const total = (open[0] as { total?: number } | undefined)?.total ?? 0
+    console.info(`[nightlyReport] fired for ${ctx.scheduledAt.toISOString()} — ${total} order(s) still 'placed'`)
+  },
+  // optional, all default-safe:
+  onOverlap:    'skip',
+  maxRuntimeMs: 5 * 60_000,
+})
+```
+
+The handler is "a mutation the clock invokes" — `ctx.app` is the same `AppContext` shape a mutation gets. Zero-config coordination: on `store: 'memory'` it runs single-process; on a multi-instance SQL store the framework advisory-lock coordinates so exactly one replica fires each tick. For durable multi-step work, prefer the `workflow: { name, payload }` form over a handler.
+
+## Subscriber — react to every write post-commit
+
+A single-file `*.subscribe.ts` reacts to table writes after they commit. See [subscribers](/docs/data/subscribers).
+
+```ts
+// subscribers/orderChanges.subscribe.ts
+import { defineSubscriber } from '@voltro/runtime'
+
+export default defineSubscriber({
+  table: 'orders',
+  on:    'any',            // 'insert' | 'update' | 'delete' | 'any' | a list
+  handler: async (event, ctx) => {
+    const row = (event.new ?? event.old) as { id?: string; status?: string } | null
+    ctx.log.info('order changed', {
+      op:     event.op,
+      id:     row?.id,
+      status: row?.status,
+    })
+  },
+})
+```
+
+It fires AFTER commit (the row IS written), best-effort + fire-and-forget — a throw logs and the next event still arrives; it can't back-pressure the change stream. `event.new` is present on insert + update (null on delete); `event.old` on update + delete (null on insert). For crash-safe multi-step reactions, have the subscriber start a workflow instead.
+
+## Aggregate — a materialized roll-up
+
+A `*.aggregate.ts` is a pre-defined query the framework refreshes on a schedule, caches, and serves through `ctx.aggregates.<name>.read(...)`. See [aggregates](/docs/data/aggregates).
+
+```ts
+// aggregates/orderStats.aggregate.ts
+import { defineAggregate } from '@voltro/runtime'
+import { column, count } from '@voltro/database'
+import { Schema } from 'effect'
+import { database } from '../database/schema'
+
+export const OrderStat = Schema.Struct({
+  tenantId: Schema.String,
+  status:   Schema.String,
+  orders:   Schema.Number,
+})
+export type OrderStat = Schema.Schema.Type<typeof OrderStat>
+
+export default defineAggregate({
+  name:    'orderStats',
+  refresh: '1m',                 // re-run every minute (interval shorthand)
+  output:  OrderStat,
+  build: async (ctx) => {
+    const rows = await ctx.store.query(
+      database.orders
+        .groupBy(['tenantId', 'status'])
+        // Grouped columns must be EXPLICITLY projected via `column(...)` in
+        // the aggregate spec — they are NOT auto-included (SQL rule: a
+        // selected non-aggregate column must be in GROUP BY).
+        .aggregate({
+          tenantId: column('tenantId'),
+          status:   column('status'),
+          orders:   count(),
+        })
+        .descriptor,
+    )
+    return rows.map((r) => ({
+      tenantId: (r as { tenantId: string }).tenantId,
+      status:   (r as { status: string }).status,
+      orders:   (r as { orders: number }).orders,
+    }))
+  },
+})
+```
+
+`output` MUST match each returned row's shape. `build` runs as the system (no per-request subject), so it reads across every tenant; `tenantId` is part of the grouping so reads stay per-tenant. Reach for an aggregate when the source query is expensive but the result is small + bounded.
+
+## Startup — a run-once boot hook
+
+A `*.startup.tsx` default-exports a function (no `define*` wrapper). It runs once after migrations + seeds, when the rpc server is listening, and holds a resource for the process lifetime.
+
+```tsx
+// startup/warm.startup.tsx
+import type { StartupContext } from '@voltro/cli/startup'
+
+export default async ({ store, log, onShutdown, id }: StartupContext) => {
+  log.info(`startup '${id}': warming order-fulfillment caches`)
+
+  // Example long-lived resource: a heartbeat interval. Replace with a real
+  // warm-up (preload a dashboard cache, open a consumer, …).
+  const timer = setInterval(() => {
+    void store // `store` is the already-migrated DataStore, ready to use.
+  }, 60_000)
+
+  // Teardown runs on SIGTERM / SIGINT, LIFO across all startups, each
+  // awaited with a hard 5s timeout. Always release what you acquire.
+  onShutdown(() => {
+    clearInterval(timer)
+    log.info(`startup '${id}': torn down`)
+  })
+}
+```
+
+A throw here does NOT block boot — it's logged; the rpc surface stays up. Distinct from `*.seed.ts` (runs once and RETURNS) and `*.cron.tsx` (periodic): a startup HOLDS a resource until shutdown. `StartupContext` is imported from the `@voltro/cli/startup` subpath.
+
+## Try it
+
+Over the rpc surface (a `voltro dev` web client, `POST /rpc`, or the inspect `invoke` endpoint):
+
+```jsonc
+// 1. place — inserts the order and starts the fulfillment workflow via order.placed
+{ "tag": "orders.place",   "input": { "tenantId": "acme", "customerName": "Ada", "amountCents": 4200 } }
+// 2. approve — wakes the parked awaitSignal('approval') gate
+{ "tag": "orders.approve", "input": { "tenantId": "acme", "orderId": "order_…", "approved": true } }
+```
+
+Watch the run in the dashboard's **Workflows** tab (the `awaitSignal` gate also has a "Send signal…" button) and the order status walk `placed → reserved → shipped` live.
+
+## When to use api-durable vs. the variants
+
+| You need… | Pick |
+|---|---|
+| The smallest CRUD reference to extend | [`api-backend`](/docs/templates/api-backend) |
+| Workflows / triggers / schedules / aggregates exercised end-to-end | `api-durable` |
+| Transactional email wired (React-Email) | [`api-backend-mail`](/docs/templates/api-backend-mail) |
+| File storage wired (public + private objects) | [`api-backend-storage`](/docs/templates/api-backend-storage) |
+| MariaDB binlog CDC + storage (K8s shape) | [`api-backend-mariadb`](/docs/templates/api-backend-mariadb) |
+
+`api-durable` is the durable-execution showcase; the `notes`-based variants build CRUD + one plugin on top of [`api-backend`](/docs/templates/api-backend).
+
+## Pairs well with
+
+- Any web template — the durable api streams its order status over the same reactive subscriptions every web template consumes.
+- [`store: 'postgres'`](/docs/database/dialects) — switch the store for durable state across restarts + cluster workflow runners.
+
+## Anti-patterns
+
+- **Emitting the domain event before the write commits.** `orders.place` emits `order.placed` *after* `ctx.store.insert` returns — `ctx.events.emit` is post-commit safe so a rolled-back transaction never starts a workflow for an order that doesn't exist. Don't emit eagerly inside the same expression as the insert.
+- **Doing external I/O inside a mutation.** The place mutation only inserts + emits. HTTP calls, payments, and other side effects belong in a workflow `step()` (journaled + replayed) or an action — a mutation runs in a transaction and can't roll back an HTTP side effect.
+- **Tracking the workflow run handle to send a signal.** `orders.approve` re-derives the executionId from the payload via the deterministic `idempotencyKey` instead. Storing the handle from the place mutation is unnecessary and breaks across restarts.
+- **Dropping the cross-tenant write guard.** Tables with `tenant()` get automatic SUBSCRIPTION scoping, but a mutation that writes raw rows still needs `assertOwnTenant(input.tenantId, ctx.request.subject)` — and `TenantMismatch` must be imported from `@voltro/plugin-multitenancy/guard` in the descriptor, never the package root (the root leaks `@voltro/database` into the browser bundle).
+- **Putting server-only imports in a workflow descriptor.** `*.workflow.tsx` is value-imported into the client rpcGroup. Keep `step` / database / cluster imports in the `.server.tsx` executor; the descriptor imports only `@voltro/workflow/define`.
+
+
+
+---
+
+<!-- source: en/templates/api-ai.md -->
+## API · AI agent
+
+_A RAG support agent over a docs knowledge base — vectorEmbedding() auto-embedded docs, a retrieval tool, a real defineAgent/defineAgentExecutor model loop, and a generateObject action. Boots zero-infra; needs an AI key only to RUN the model._
+
+The AI template: a **RAG support agent** over a docs knowledge base. It exercises the framework's AI surface end-to-end — a `vectorEmbedding()` `docs` table that auto-embeds on every write, a `defineTool` the agent calls to retrieve docs, a real `defineAgent` / `defineAgentExecutor` model loop, and a `generateObject` action for structured output. It **boots and discovers every primitive with zero infra and no AI key** (`store: 'memory'`); you only need a provider key to actually RUN the agent or the summarize action. Template id: **`api-ai`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-ai
+```
+
+## What ships
+
+```text
+apps/acme/api/                          # dir named by the app, not the template
+├── app.config.ts                       # type:api, store:'memory', AI env declared
+├── package.json                        # adds @voltro/ai to the api deps
+├── tsconfig.json
+├── README.md
+├── database/
+│   └── schema.ts                       # actors + tenants (core) + a docs table with vectorEmbedding()
+├── agents/
+│   ├── support.agent.tsx               # descriptor — browser-safe (name + input)
+│   └── support.agent.server.tsx        # executor — system prompt + tools + maxSteps
+├── tools/
+│   └── searchDocs.tool.tsx             # retrieval tool — nearestNeighbours over docs
+├── actions/
+│   ├── summarize.action.ts             # descriptor — browser-safe
+│   └── summarize.action.server.tsx     # executor — generateObject structured output
+└── seeds/
+    └── docs.seed.ts                    # boot seed of sample docs (auto-embedded on insert)
+```
+
+No queries or mutations ship — the agent's two routes are SYNTHESIZED (see below). Builds on the same `actors` + `tenants` core as [`api-backend`](/docs/templates/api-backend), but the example table is `docs` (vector-embedded), not `notes`.
+
+## The agent — descriptor / `.server.ts` split
+
+Like every rpc primitive, an agent is **two files paired by basename**: a browser-safe descriptor (`*.agent.tsx`, `defineAgent` from `@voltro/ai/agent`) carrying just `name` + `input`, and a server-only executor (`*.agent.server.tsx`, `defineAgentExecutor` from `@voltro/ai`) carrying the system prompt, tools, model, and `maxSteps`. The descriptor is value-imported into `rpcGroup.generated.ts` so the web client is typed end-to-end; the executor holds the secrets and the server imports.
+
+### Descriptor — `agents/support.agent.tsx`
+
+```tsx
+// support.agent.tsx — DESCRIPTOR (browser-safe)
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({
+    prompt: Schema.String,
+    // Optional locale to steer the system prompt's reply language.
+    locale: Schema.optional(Schema.String),
+  }),
+})
+```
+
+### Executor — `agents/support.agent.server.tsx`
+
+```tsx no-check
+// support.agent.server.tsx — EXECUTOR (server-only)
+import { defineAgentExecutor } from '@voltro/ai'
+import { support } from './support.agent'
+import { searchDocs } from '../tools/searchDocs.tool'
+
+export default defineAgentExecutor(support, {
+  system: (input) =>
+    [
+      'You are a friendly, precise support agent for this product.',
+      'Answer ONLY from the knowledge base. ALWAYS call the `searchDocs`',
+      'tool first to retrieve relevant docs, then answer using their',
+      'content. If the docs do not cover the question, say so plainly',
+      'instead of guessing.',
+      `Reply in this locale: ${input.locale ?? 'en'}.`,
+    ].join(' '),
+  tools:    { searchDocs },
+  // No `model` → inherit AI_PROVIDER / AI_MODEL + the key var from env.
+  maxSteps: 6,
+})
+```
+
+Omitting `model` makes the agent inherit the provider from env (`AI_PROVIDER` / `AI_MODEL` + the provider's standard key var). That keeps the secret server-side and lets the same template run against any provider via `.env`.
+
+### Two synthesized routes — you write neither
+
+From the agent descriptor the framework SYNTHESIZES two procedures into `rpcGroup.generated.ts`:
+
+- **`support.send`** — an **action** that appends the user turn and drives a streaming assistant turn (delta-persisted to `agent_messages`). Wire input: the descriptor's `input` fields plus `threadId` + `order`.
+- **`support.messages`** — a **reactive query** (`source: 'agent_messages'`) that streams the persisted turns, including the live `streaming:true` row being patched, to the client.
+
+The thread tables (`agent_threads`, `agent_messages`) are auto-provided and auto-migrated because this app ships an `*.agent.tsx` — no schema file needed. Drive them from a web client:
+
+```tsx
+// mint a thread id, subscribe to the live feed, then send a turn
+const threadId = `thread_${crypto.randomUUID().replace(/-/g, '')}`
+const { data: messages } = useSubscription('app', ['support.messages', { threadId }], { threadId })
+const send = useAction('app', 'support.send')
+await send.run({ threadId, order: messages?.length ?? 0, prompt: 'How do I reset my password?' })
+```
+
+As `support.send` writes token deltas to the streaming row, the `support.messages` subscription re-fires and the client sees each chunk — the live typewriter bubble is just a row whose `streaming` flag is `true`. No streaming RPC, no manual ws handling.
+
+## The retrieval tool — `tools/searchDocs.tool.tsx`
+
+A `defineTool` (the `*.tool.tsx` convention) is a named DESCRIPTOR with Schema-typed `input` / `output` and NO body, plus a default-exported `(input, ctx) => …` handler. The framework wires the default export onto the descriptor at discovery, and the agent's `tools: { searchDocs }` imports the SAME module instance. This file is SERVER-ONLY — it's referenced from the agent executor, never a browser-loaded descriptor, so importing the `database` handle here is safe.
+
+```tsx
+import { defineTool } from '@voltro/ai'
+import type { AppContext } from '@voltro/runtime'
+import { Schema } from 'effect'
+import { database } from '../database/schema'
+
+const MAX_RESULTS = 5
+const SNIPPET_LEN = 280
+
+export const searchDocs = defineTool({
+  name:        'searchDocs',
+  description:
+    'Search the support knowledge base for documents relevant to a question. ' +
+    'Returns up to 5 results, each with a title and a short snippet of the body.',
+  input:  Schema.Struct({ query: Schema.String }),
+  output: Schema.Array(
+    Schema.Struct({ title: Schema.String, snippet: Schema.String }),
+  ),
+})
+
+export default async (
+  { query }: { query: string },
+  ctx: AppContext,
+): Promise<ReadonlyArray<{ title: string; snippet: string }>> => {
+  try {
+    const rows = await ctx.store.query(
+      database.docs.nearestNeighbours(query, MAX_RESULTS).descriptor,
+    )
+    return rows.map((row) => {
+      const body = String((row as { body?: unknown }).body ?? '')
+      return {
+        title:   String((row as { title?: unknown }).title ?? ''),
+        snippet: body.length > SNIPPET_LEN ? `${body.slice(0, SNIPPET_LEN)}…` : body,
+      }
+    })
+  } catch {
+    // No AI key / embed failure / cold table → degrade to "no results"
+    // rather than aborting the agent's tool loop.
+    return []
+  }
+}
+```
+
+Because `docs` carries `vectorEmbedding()`, the STRING overload of `nearestNeighbours(query, k)` is valid — the runtime embeds `query` before searching. Any failure (no AI key, embed error) is caught and returns `[]`, so a tool hiccup surfaces to the model as "no results" instead of aborting the whole agent turn.
+
+## The structured-output action — `actions/summarize.action.ts` + `.server.tsx`
+
+AI inference is external I/O, so it's an **action**, not a mutation. This one uses `generateObject` to take free-text and produce STRUCTURED output — a typed `{ title, summary, keyPoints, sentiment }` object instead of prose. The `output` Schema is exported from the descriptor so the executor can reuse the SAME schema to constrain the model: one source of truth for both the wire output and the shape the model must satisfy.
+
+```ts
+// summarize.action.ts — DESCRIPTOR (browser-safe)
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+// The structured shape the model must emit. Top-level `Schema.Struct`
+// (generateObject requires a JSON `object` at the root — an array/scalar
+// must be wrapped in a field, as `keyPoints` is here).
+export const SummaryResult = Schema.Struct({
+  title:     Schema.String,
+  summary:   Schema.String,
+  keyPoints: Schema.Array(Schema.String),
+  sentiment: Schema.Literal('positive', 'neutral', 'negative'),
+})
+export type SummaryResult = Schema.Schema.Type<typeof SummaryResult>
+
+export const summarize = defineAction({
+  name:  'support.summarize',
+  input: Schema.Struct({
+    // The raw text to summarise (a support thread, a doc, a transcript).
+    text: Schema.String,
+  }),
+  output: SummaryResult,
+})
+```
+
+```ts
+// summarize.action.server.tsx — EXECUTOR (server-only)
+import { Effect } from 'effect'
+import { generateObject } from '@voltro/ai'
+import { SummaryResult } from './summarize.action'
+
+const execute = (input: { text: string }) =>
+  Effect.gen(function* () {
+    const { object } = yield* generateObject({
+      schema: SummaryResult,
+      system:
+        'Summarise the given support text. Produce a short title, a 1-2 sentence ' +
+        'summary, the key points as a list, and the overall sentiment.',
+      prompt:    input.text,
+      maxTokens: 500,
+    })
+    return object
+  })
+
+export default execute
+```
+
+`generateObject` converts the `SummaryResult` Effect Schema to JSON Schema for the provider, then decodes the result back so brands/refinements hold. A provider failure or malformed output surfaces as a typed `AiError` (`reason: 'generation' | 'decode'`) on the Effect failure channel — declare it on the descriptor's `error:` to surface it typed to the client, or `Effect.catchTag('AiError', …)` to handle it in the executor.
+
+## Database — auto-embedded `docs`
+
+The schema declares the two framework core tables plus one vector-embedded knowledge-base table:
+
+```ts
+// database/schema.ts
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  vectorEmbedding,
+  type InferRow,
+} from '@voltro/database'
+
+// Core tables — required by the audit / tenant mixins.
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+})
+
+export const tenants = table('tenants', {
+  id:   id(),
+  name: text(),
+})
+
+// Knowledge base — vectorEmbedding({ from: 'body' }) adds the `embedding`
+// vector column + an HNSW index, and registers a re-embed hook that calls
+// @voltro/ai's `embed` on every insert/update of `body` — so a plain
+// ctx.store.insert('docs', { title, body }) auto-embeds, no app code.
+export const docs = table('docs', {
+  id:    id({ prefix: 'doc' }),
+  title: text(),
+  body:  text(),
+})
+  .with(
+    vectorEmbedding({
+      from:       'body',
+      model:      'text-embedding-3-small',
+      dimensions: 1536,
+    }),
+  )
+  // Opt into the matcher engine so subscriptions over `docs` re-fire on write.
+  .reactive()
+
+export type Doc = InferRow<typeof docs>
+
+export const database = databaseHandle({ actors, tenants, docs })
+```
+
+`dimensions` MUST match the embedding model's output width — `1536` is OpenAI's `text-embedding-3-small`. If you point at a different embedding model, change it to match (e.g. `768` / `3072`) or the vector column size won't line up. See [Vectors / RAG](/docs/database/vectors) for `nearestNeighbours`, `hybridSearch`, and the `vectorEmbedding()` mixin in depth.
+
+## The seed — `seeds/docs.seed.ts`
+
+`defineSeed` with `lifecycle: 'boot'` runs once per `voltro dev` boot, re-running only when the seed file's content fingerprint changes. `upsertByUnique` keys on `title`, so re-runs UPDATE rather than duplicate — idempotent. Because `docs` carries `vectorEmbedding({ from: 'body' })`, each insert/update AUTO-EMBEDS the body — no embedding code here.
+
+```ts
+import { defineSeed } from '@voltro/database'
+
+const SAMPLE_DOCS: ReadonlyArray<{ title: string; body: string }> = [
+  { title: 'Resetting your password', body: '…' },
+  { title: 'Inviting teammates',      body: '…' },
+  { title: 'Exporting your data',     body: '…' },
+  { title: 'API rate limits',         body: '…' },
+]
+
+export default defineSeed({
+  id:        'docs',
+  name:      'Sample knowledge-base docs',
+  lifecycle: 'boot',
+  steps: ({ step }) => [
+    step('seed-docs', async ({ upsertByUnique }) => {
+      let rowsTouched = 0
+      for (const doc of SAMPLE_DOCS) {
+        await upsertByUnique('docs', { title: doc.title }, { title: doc.title, body: doc.body })
+        rowsTouched += 1
+      }
+      return { rowsTouched }
+    }),
+  ],
+})
+```
+
+The auto-embed needs a provider key. Without one the rows still seed (title + body persist) but the `embedding` column stays empty. Set a key, then fill the gaps:
+
+```bash
+voltro embeddings backfill docs --text body --vector embedding
+# add --model <m> if you changed the embedding model from the default
+```
+
+This (re-)embeds existing rows the `vectorEmbedding()` mixin missed — the same command to run after a model change.
+
+## Store + AI provider — env
+
+`app.config.ts` ships `store: 'memory'` — fast startup, no Docker, data resets on restart. The vector column is still stored, but ANN falls back to a sequential scan (correct, just unindexed). Switch to `store: 'postgres'` for a real pgvector HNSW index.
+
+`@voltro/ai` reads the provider/model/key from env. All are OPTIONAL for booting; they're only needed to RUN the model. The template declares them with `defineEnv` so they show up in `voltro env` and `.env.example`:
+
+```ts
+// app.config.ts (excerpt)
+import { defineEnv, envVar } from '@voltro/env'
+
+export const env = defineEnv({
+  LOG_LEVEL:   envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  AI_PROVIDER: envVar.string({ access: 'public', optional: true }),   // e.g. 'openai' | 'anthropic'
+  AI_MODEL:    envVar.string({ access: 'public', optional: true }),   // e.g. 'gpt-4o-mini'
+  AI_API_KEY:  envVar.string({ access: 'secret', optional: true }),   // server-only
+})
+
+export default {
+  type:  'api' as const,
+  name:  'acmeApi',
+  store: 'memory' as const,
+  env,
+}
+```
+
+```bash
+# .env — @voltro/ai also accepts the provider-standard var (OPENAI_API_KEY / ANTHROPIC_API_KEY)
+AI_PROVIDER=openai
+AI_MODEL=gpt-4o-mini
+AI_API_KEY=sk-...
+```
+
+Editing `.env` hard-restarts `voltro dev` automatically. Run `voltro env` to see the resolved manifest.
+
+## When to use api-ai vs. the variants
+
+| You need… | Pick |
+|---|---|
+| RAG agent + tools + structured output (the AI showcase) | `api-ai` |
+| The smallest generic backend to extend | [`api-backend`](/docs/templates/api-backend) |
+| Transactional email wired (React-Email) | [`api-backend-mail`](/docs/templates/api-backend-mail) |
+| File storage wired (public + private objects) | [`api-backend-storage`](/docs/templates/api-backend-storage) |
+
+## Pairs well with
+
+- Any web template — pair `support.send` / `support.messages` with a chat UI for the live typewriter feed.
+- [AI agents](/docs/ai/agents) — the `defineAgent` / `defineAgentExecutor` model loop, synthesized routes, thread persistence.
+- [AI tools](/docs/ai/tools) — `defineTool` shape, how tool bodies reach app services.
+- [RAG](/docs/ai/rag) and [Vectors](/docs/database/vectors) — `vectorEmbedding()`, `nearestNeighbours`, `hybridSearch`.
+
+## Anti-patterns
+
+- **Hardcoding a model or API key in the descriptor.** The model + key live in the `.server.tsx` executor (or env), never the browser-safe `*.agent.tsx`. Omitting `model` to inherit from env keeps the secret server-side and lets one template run against any provider.
+- **Making the AI call a mutation.** AI inference is external I/O — use an **action**. A mutation runs in a transaction and can't roll back the model call's side effect; `summarize` is correctly an action.
+- **Letting a tool failure abort the agent turn.** `searchDocs` catches every error and returns `[]` so a missing key or embed failure degrades to "no results" instead of crashing the whole tool loop.
+- **Mismatching `dimensions` with the embedding model.** The `vector` column width is fixed at declaration. If `dimensions` doesn't match the model's output width, inserts/queries won't line up — change it together with the model.
+- **Hand-writing thread/send/list routes.** The agent path SYNTHESIZES `support.send` + `support.messages` and types them through codegen. Don't reinvent them just to get a typed client.
+
+
+
+---
+
+<!-- source: en/templates/api-data-advanced.md -->
+## API · Data (advanced)
+
+_A library/catalog api that tours the advanced schema DSL — the entity/relations split with eager loading, full-text search, dbEnum, array + generated + encrypted columns, and declarative query caching._
+
+A small **library/catalog** (authors + books) that closes the advanced schema-DSL gaps — the features that are documented but shown in no other api template: the `*.entity.ts` / `*.relations.ts` split with eager `.with()` loading, full-text search, `dbEnum`, array / generated / encrypted columns, and declarative query result caching. Reach for it as a worked reference when you're modelling something richer than a single flat table. Template id: **`api-data-advanced`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-data-advanced
+```
+
+## What ships
+
+```text
+apps/acme/api/                              # dir named by the app, not the template
+├── app.config.ts                           # type:api, store:'memory', governancePlugin({ fieldEncryption: true })
+├── .env                                     # DEV-ONLY VOLTRO_FIELD_ENCRYPTION_KEY (see below)
+├── package.json
+├── tsconfig.json
+├── README.md
+├── database/
+│   ├── actors.entity.ts                    # core audit-subject table
+│   ├── tenants.entity.ts                   # core tenant boundary
+│   ├── authors.entity.ts                   # name + .encrypted() bio
+│   ├── books.entity.ts                     # dbEnum genre, array tags, generated slug, FTS index
+│   ├── authors.relations.ts                # author → many books
+│   ├── books.relations.ts                  # book → one author
+│   └── index.ts                            # databaseHandle({...}) + relation registration
+├── queries/
+│   ├── books.search.query.ts(.server)      # FTS via .matching(...) + cache
+│   └── authors.withBooks.query.ts(.server) # eager-load via .with({ books: true })
+└── seeds/
+    └── catalog.seed.ts                      # demo authors + books
+```
+
+`store: 'memory'` keeps boot zero-infra (no Docker, data resets on restart). The schema DSL is identical across every SQL backend — switch `app.config.ts` to `store: 'postgres'` to see the native DDL the migrator emits (`CREATE TYPE … ENUM`, `text[]`, the STORED generated column, the tsvector + GIN FTS index). On `memory` the same features run through the in-process store: FTS degrades to a substring scan, arrays round-trip as JS arrays, encryption still applies. See the [SQL dialects guide](/docs/database/dialects).
+
+## The `*.entity.ts` / `*.relations.ts` split
+
+Tables are declared **one per file** with the `*.entity.ts` extension. Relations are declared OUTSIDE the table descriptor, in a sibling `*.relations.ts` file — the framework registers them at boot and the query builder's `.with()` chain uses them to eager-load.
+
+```ts
+// database/authors.entity.ts
+import { id, table, text } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy/mixin'
+
+export const authors = table('authors', {
+  id:   id({ prefix: 'author' }),
+  name: text(),
+  // Encrypted at rest. Requires governancePlugin({ fieldEncryption: true }).
+  bio:  text().encrypted().nullable(),
+})
+  // tenant() pulls audit() transitively → tenantId + createdAt/updatedAt/createdBy/updatedBy
+  .with(tenant())
+  .reactive()
+```
+
+```ts
+// database/authors.relations.ts — declared OUTSIDE the table descriptor
+import { relations } from '@voltro/database'
+import { authors } from './authors.entity'
+import { books } from './books.entity'
+
+// An author has MANY books. `foreignKey` auto-derives because exactly one
+// reference() column on `books` (`authorId`) points back at `authors`.
+export const authorsRelations = relations(authors, ({ many }) => ({
+  books: many(books),
+}))
+```
+
+```ts
+// database/books.relations.ts — the inverse, a book belongs to ONE author
+import { relations } from '@voltro/database'
+import { authors } from './authors.entity'
+import { books } from './books.entity'
+
+export const booksRelations = relations(books, ({ one }) => ({
+  author: one(authors),
+}))
+```
+
+The handle barrel imports the `*.relations.ts` files (side-effecting) so the eager-load walker can resolve them:
+
+```ts
+// database/index.ts
+import { databaseHandle, type InferRow } from '@voltro/database'
+import { actors } from './actors.entity'
+import { tenants } from './tenants.entity'
+import { authors } from './authors.entity'
+import { books } from './books.entity'
+
+// Register relations (side-effecting imports).
+import './authors.relations'
+import './books.relations'
+
+export { actors, tenants, authors, books }
+export type Author = InferRow<typeof authors>
+export type Book = InferRow<typeof books>
+
+export const database = databaseHandle({ actors, tenants, authors, books })
+```
+
+See [Relations](/docs/database/relations).
+
+## Eager loading — `.with({ books: true })`
+
+`authors.withBooks` returns each author with their books attached as an array, in ONE SQL roundtrip (the dialect's JSON-aggregation idiom — postgres `jsonb_agg`, sqlite `json_group_array`, mysql `JSON_ARRAYAGG`, mssql `FOR JSON PATH`). The per-branch `orderBy`/`limit` apply PER author.
+
+```ts
+// queries/authors.withBooks.query.server.ts — executor (server-only)
+import type { AppContext } from '@voltro/runtime'
+import { database } from '../database/index'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) =>
+  database.authors.with({
+    books: { orderBy: [{ column: 'title', direction: 'asc' }], limit: 50 },
+  })
+
+export default execute
+```
+
+The descriptor's `output` carries the nested `books` array, and `source: ['authors', 'books']` makes the reactive subscription re-run when EITHER table changes — a new book under an author pushes a fresh snapshot:
+
+```ts
+// queries/authors.withBooks.query.ts — descriptor (browser-safe)
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+const Book = Schema.Struct({
+  id: Schema.String, authorId: Schema.String, title: Schema.String,
+  summary: Schema.String, genre: Schema.String,
+  tags: Schema.Array(Schema.String), slug: Schema.String, tenantId: Schema.String,
+})
+
+export const authorsWithBooks = defineQuery({
+  name:   'authors.withBooks',
+  source: ['authors', 'books'],
+  input:  Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String, name: Schema.String,
+    // `bio` is the .encrypted() column — handlers + the wire see plaintext.
+    bio: Schema.NullOr(Schema.String), tenantId: Schema.String,
+    books: Schema.Array(Book),   // eager-loaded relation
+  }),
+})
+```
+
+See [Eager loading](/docs/database/relations/eager-loading).
+
+## Full-text search — `.fullTextIndex` + `.matching`
+
+`books` declares one FTS index over `title` + `summary`. That single declaration compiles to a different backend per dialect (postgres tsvector + GIN, mysql/mariadb `FULLTEXT`, sqlite FTS5, mssql ranked-LIKE fallback). The `books` table also carries the other specialized columns — `dbEnum`, `array(text())`, and a stored `.generatedAs(...)`:
+
+```ts
+// database/books.entity.ts
+import { array, dbEnum, id, reference, table, text } from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy/mixin'
+import { authors } from './authors.entity'
+
+// Native ENUM type — declared module-level as a reusable handle. `as const`
+// is required for the literal-union type. postgres → CREATE TYPE … ENUM
+// (ADD VALUE is O(1)); mysql/mariadb → native ENUM(...); mssql/sqlite → CHECK.
+export const bookGenre = dbEnum('book_genre', [
+  'fiction', 'nonfiction', 'fantasy', 'sciFi', 'mystery', 'biography',
+] as const)
+
+export const books = table('books', {
+  id:       id({ prefix: 'book' }),
+  authorId: reference(() => authors),                  // FK → authors, auto-indexed
+  title:    text(),
+  summary:  text(),
+  genre:    bookGenre.column().default('fiction'),     // native ENUM column
+  tags:     array(text()).default([]),                 // text[] on postgres; JSON codec elsewhere
+  // DB-computed STORED column derived from `title` on INSERT + UPDATE.
+  // `stored: true` persists it on disk so it's indexable. Same-row columns
+  // only. Raw SQL emitted verbatim — keep it portable (quoted identifier).
+  slug:     text().generatedAs(`lower("title")`, { stored: true }),
+})
+  .fullTextIndex('bookSearch', ['title', 'summary'], {
+    config:  'english',
+    weights: { title: 'A', summary: 'B' },
+  })
+  .with(tenant())
+  .reactive()
+```
+
+The query executor compiles the FTS predicate via `.matching('bookSearch', q)` — resolving the index's covered columns + config from the declaration on the table. No tenant filter is added by hand; `books` carries `tenant()`, so the runtime AND-merges `eq('tenantId', subject.tenantId)`:
+
+```ts
+// queries/books.search.query.server.ts — executor (server-only)
+import type { AppContext } from '@voltro/runtime'
+import { database } from '../database/index'
+
+const execute = (input: { q: string }, _ctx: AppContext) =>
+  database.books.matching('bookSearch', input.q).limit(50)
+
+export default execute
+```
+
+See [Full-text search](/docs/database/full-text-search), [Enums](/docs/database/enums), [Arrays & intervals](/docs/database/arrays-intervals), and [Generated columns](/docs/database/generated-columns).
+
+## Field encryption — `.encrypted()` + the DEV-ONLY `.env`
+
+`authors.bio` is flagged `.encrypted()`. The store middleware transparently encrypts it on write (AES-256-GCM) and decrypts on read — handlers always see plaintext while the column stores an opaque `enc:v1:…` string on disk on every dialect. An `.encrypted()` column is ciphertext in SQL, so you can't filter or sort by its plaintext — encrypt only what you read back whole (PII, tokens, notes). A book search never touches `bio`, so this is safe.
+
+The column ONLY works because `app.config.ts` wires `governancePlugin({ fieldEncryption: true })`, which registers the cipher. Boot fails loud if an `.encrypted()` column exists but no cipher is registered.
+
+```ts
+// app.config.ts
+import { defineEnv, envVar } from '@voltro/env'
+import { governancePlugin } from '@voltro/plugin-governance'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // NO `default` on purpose — see the note below.
+  VOLTRO_FIELD_ENCRYPTION_KEY: envVar.string({ access: 'secret' }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  env,
+  plugins: [
+    governancePlugin({ fieldEncryption: true }),   // reads secret VOLTRO_FIELD_ENCRYPTION_KEY
+  ],
+}
+```
+
+**Where the key actually comes from is the load-bearing detail.** `governancePlugin({ fieldEncryption: true })` resolves the AES-256-GCM key through the **Secrets-Resolver** — i.e. the process environment — NOT through a `defineEnv` `default`. A `defineEnv` default would satisfy the boot validation gate while the cipher still failed to resolve a key. That's why the env declaration above deliberately has no `default`, and the template instead ships a `.env` carrying a **DEV-ONLY** placeholder so `voltro dev` boots out of the box:
+
+```bash
+# .env — DEV-ONLY. `voltro dev` loads this into process.env at boot, BEFORE
+# the env-validation gate and BEFORE plugins activate, which is how the
+# governance plugin's cipher resolves its key from the Secrets-Resolver.
+VOLTRO_FIELD_ENCRYPTION_KEY=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff
+```
+
+> **Before production**, replace this placeholder with a real key (`openssl rand -hex 32`) and move it into your deployment's secret store — never ship the shipped value. **Lose the key → lose the data** (GCM fails closed, never silent corruption); **rotating it** makes every existing `.encrypted()` value unreadable.
+
+See [Field encryption](/docs/plugins/governance) and the [columns reference](/docs/database/columns).
+
+## Declarative query caching
+
+`books.search` adds `cache` to its `defineQuery`. The framework caches the server snapshot and auto-invalidates it whenever a mutation writes any table the query depends on (here, `books`) — zero manual busting. `scope` is REQUIRED and is a security decision: this query is tenant-filtered (the `tenant()` mixin AND-merges the caller's `tenantId`), so it depends on the caller → `scope: 'subject'` (the cache key includes the subject id, no cross-tenant leak). NEVER `global` on a subject-filtered query.
+
+```ts
+// queries/books.search.query.ts — descriptor (browser-safe)
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const searchBooks = defineQuery({
+  name:   'books.search',
+  source: 'books',
+  input:  Schema.Struct({ q: Schema.String }),
+  output: Schema.Struct({
+    id: Schema.String, authorId: Schema.String, title: Schema.String,
+    summary: Schema.String, genre: Schema.String,
+    tags: Schema.Array(Schema.String), slug: Schema.String, tenantId: Schema.String,
+  }),
+  cache: { ttl: '30s', swr: '5m', scope: 'subject' },
+})
+```
+
+The `authors.withBooks` query deliberately has NO `cache` — it's a join-shaped result, so the template lets the live dispatcher keep it fresh rather than cache a snapshot. See [Query result caching](/docs/caching/query-cache).
+
+## Boot seed
+
+`catalog.seed.ts` is a boot-lifecycle seed that idempotently `upsertByUnique`s a demo tenant, two authors, and three books, so the catalog has data the moment `voltro dev` boots. The seed store is the RAW store (no authenticated subject), so `tenant()` auto-fill doesn't fire — it passes `tenantId: 'acme'` explicitly (matching the dev AuthMiddleware default, which resolves `acme` from the `x-tenant` header). It passes `bio` as plaintext (the middleware encrypts it), `tags` as a JS array, and OMITS `slug` (the `.generatedAs(...)` STORED column is filled by the DB engine). See [Seeds](/docs/database/seeds).
+
+## Try it
+
+Subscribe from a web app via `useSubscription('app', 'books.search', { q: 'magic' })` and `useSubscription('app', 'authors.withBooks')`, or invoke them over HTTP through `POST /_voltro/inspect/invoke` for a one-shot snapshot.
+
+## When to use api-data-advanced vs. the variants
+
+| You need… | Pick |
+|---|---|
+| The smallest reference to extend | [`api-backend`](/docs/templates/api-backend) |
+| A worked tour of the advanced schema DSL (relations + eager loading, FTS, enum/array/generated/encrypted columns, query cache) | `api-data-advanced` |
+| Transactional email wired (React-Email) | [`api-backend-mail`](/docs/templates/api-backend-mail) |
+| File storage wired (public + private objects) | [`api-backend-storage`](/docs/templates/api-backend-storage) |
+| MariaDB binlog CDC + storage (K8s shape) | [`api-backend-mariadb`](/docs/templates/api-backend-mariadb) |
+
+## Pairs well with
+
+- Any web template — `api-data-advanced` exposes its queries over the standard rpc client.
+- [`@voltro/plugin-governance`](/docs/plugins/governance) — already wired here for field encryption; it also ships retention sweeps, GDPR export/erase, and a consent ledger.
+
+## Anti-patterns
+
+- **Shipping the placeholder `VOLTRO_FIELD_ENCRYPTION_KEY` to production.** The `.env` value is a public, DEV-ONLY constant. Generate a real key (`openssl rand -hex 32`), store it in your deployment's secret store, and never commit it. Lose the key and the ciphertext is gone for good.
+- **Expecting a `defineEnv` `default` to feed the cipher.** It won't — the cipher reads the Secrets-Resolver (process env), not the typed-env default. A default would pass the boot gate while the cipher still fails to resolve, so the key must reach `process.env` (here via `.env`).
+- **Filtering or sorting by an `.encrypted()` column's plaintext in SQL.** It's ciphertext on disk — those predicates can't run. Encrypt only fields you read back whole.
+- **Adding `tenantId` filters by hand in the query executors.** `authors` and `books` carry `tenant()`, so the runtime scopes reads automatically. Doing both works but signals you don't trust the framework.
+- **Passing `slug` in a write.** It's a `.generatedAs(...)` STORED column — the DB engine fills it from `title`. Passing a value fights the generator.
+
+
+
+---
+
+<!-- source: en/templates/api-auth.md -->
+## API · Auth
+
+_Real user authentication wired turnkey with @voltro/plugin-auth — password sign-up/in/out over HttpOnly session cookies, a strategy that resolves the session into a typed Subject, and a session.me action proving it. Zero-infra boot._
+
+Real user authentication, wired turnkey. Password **sign-up / sign-in / sign-out** over HttpOnly **session cookies**, a strategy that resolves the session into a typed `Subject` on every rpc call, and a `session.me` action that proves the loop end-to-end. Boots with **zero infra** (`memoryUserStore()`). Template id: **`api-auth`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-auth
+```
+
+The shipped `.env` supplies a DEV-ONLY `VOLTRO_SESSION_SECRET` so it boots out of the box — replace it for production (see Environment).
+
+## What ships
+
+```text
+apps/acme/api/
+├── app.config.ts               # authRoutesPlugin + voltroPasswordStrategy + memoryUserStore
+├── .env                        # DEV-ONLY VOLTRO_SESSION_SECRET
+├── package.json                # + @voltro/plugin-auth
+├── database/schema.ts          # core actors + tenants (users live in the memory store)
+└── actions/
+    ├── me.action.ts            # session.me descriptor — browser-safe
+    └── me.action.server.ts     # returns ctx.request.subject
+```
+
+## The two halves
+
+`app.config.ts` wires both, sharing ONE secret:
+
+```ts
+import { authRoutesPlugin, memoryUserStore, voltroPasswordStrategy } from '@voltro/plugin-auth'
+
+const SECRET = process.env.VOLTRO_SESSION_SECRET ?? 'dev-only-unsafe-session-secret-change-me'
+
+export default {
+  type: 'api' as const, name: 'AcmeApi', store: 'memory' as const,
+  plugins: [
+    authRoutesPlugin({
+      store: memoryUserStore(),
+      secret: SECRET,
+      defaultTenantId: 'acme',
+      cookieSecure: process.env.NODE_ENV === 'production',  // ← see the gotcha below
+    }),
+  ],
+  auth: { strategies: [voltroPasswordStrategy({ secret: SECRET })] },
+}
+```
+
+- **`authRoutesPlugin`** mounts the HTTP auth surface under `/auth/*` (`POST /auth/sign-up`, `/auth/sign-in`, `/auth/sign-out`, `GET /auth/csrf`, password-reset, magic-link, `/auth/sessions`, tenant memberships) and **signs** the `voltro:session` cookie on success.
+- **`voltroPasswordStrategy`** runs in the [AuthMiddleware](/docs/authentication/overview) chain on every rpc/ws call, **verifies** that cookie, and resolves it to a `Subject` — so handlers read the user via `ctx.request.subject`.
+
+They MUST share the same `secret` (one signs, the other verifies); the template reads `VOLTRO_SESSION_SECRET` once and passes it to both.
+
+### Reading the Subject — `session.me`
+
+```ts
+// actions/me.action.server.ts
+const execute = async (_input, ctx) => {
+  const subject = ctx.request.subject as { type: string; id: string | null; tenantId: string | null }
+  return { type: subject.type, id: subject.id ?? null, tenantId: subject.tenantId ?? null }
+}
+```
+
+Anonymous before sign-in (`type: 'anonymous'`, `id: null`); a `user` Subject once the session cookie resolves.
+
+## Gotcha — `cookieSecure` in dev
+
+`Secure` cookies are **HTTPS-only** — over `http://localhost` a browser (and `curl`) silently drops a `Secure` session cookie, so the sign-in → session → authenticated-call loop never authenticates. Setting `cookieSecure: process.env.NODE_ENV === 'production'` is what makes the loop work locally (off in dev, on over HTTPS in prod).
+
+## Try the loop (curl)
+
+State-changing routes are CSRF-protected; `session.me` is an rpc procedure (invoke it over HTTP via the dev inspect endpoint, which forwards your cookie):
+
+```bash
+# 1. CSRF token (+ csrf cookie into the jar)
+curl -s -c jar.txt http://localhost:4000/auth/csrf            # → { "csrfToken": "…" }
+
+# 2. Sign up (sets the HttpOnly session cookie)
+curl -s -b jar.txt -c jar.txt -X POST http://localhost:4000/auth/sign-up \
+  -H 'content-type: application/json' -H 'x-csrf-token: <csrf>' \
+  -d '{"email":"ada@example.com","password":"hunter2hunter2"}'
+# → { "ok": true, "subject": { "type": "user", "id": "u_…", "tenantId": "acme" } }
+
+# 3. session.me with the cookie → you're a user
+curl -s -b jar.txt -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' -d '{"tag":"session.me","input":{}}'
+# → { "ok": true, "result": { "type": "user", "id": "u_…", "tenantId": "acme" } }
+```
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| Durable accounts | `postgresUserStore({ sql })` + `store: 'postgres'` (manages its own auth tables) |
+| Magic-link / password-reset email | pass `sendEmail: mailSender(mailService)` (from [`@voltro/plugin-mail`](/docs/plugins/mail)) to `authRoutesPlugin` |
+| A login UI | pair with [`frontend-app`](/docs/templates/app) — a form POSTing to `/auth/sign-in`; authenticated rpc carries the cookie automatically |
+
+## Anti-patterns
+
+- **Forgetting `cookieSecure` in dev.** The `Secure` default drops the cookie over http — auth silently fails. See the gotcha above.
+- **Different secrets for the routes plugin vs. the strategy.** One signs, the other verifies — they must match. Read `VOLTRO_SESSION_SECRET` once and pass it to both.
+- **Shipping the DEV-ONLY `.env` secret.** Generate a real one (`openssl rand -hex 32`); rotating it invalidates every session.
+- **Trusting `x-tenant` in production.** The dev resolver reads it unauthenticated — this template's session strategy is the real path; don't leave the header as your auth.
+
+
+
+---
+
+<!-- source: en/templates/api-rest.md -->
+## API · REST + OpenAPI
+
+_A public REST API built on defineRestRoute — GET/POST/DELETE with query, path, and body parsing, scope guards, Idempotency-Key dedup, and an OpenAPI 3.1 spec + Swagger UI auto-generated from the route descriptors. Zero-infra boot._
+
+A turnkey **public REST API** — plain raw-HTTP endpoints a third party calls with a URL + JSON, the opposite end from the reactive rpc/WebSocket surface ([`api-backend`](/docs/templates/api-backend)). Four `defineRestRoute` endpoints over a `products` catalog, **scope-guarded** writes, **`Idempotency-Key`** dedup, and an **OpenAPI 3.1 spec + Swagger UI** generated from the descriptors. Boots with **zero infra** (`store: 'memory'`). Template id: **`api-rest`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-rest
+```
+
+Boots on `http://localhost:4000`; open `http://localhost:4000/docs` for the Swagger UI.
+
+## What ships
+
+```text
+apps/acme/api/
+├── app.config.ts               # restRoutes + openapiPlugin + apiKeyStrategy + idempotency
+├── package.json                # + @voltro/plugin-openapi
+├── database/schema.ts          # a plain `products` table (no mixins — the routes own auth)
+├── lib/product.ts              # shared wire Schema + row→wire mapper (one source of truth)
+└── routes/v1/
+    ├── products.list.route.tsx     # GET    /v1/products?limit=&cursor=   (public, paginated)
+    ├── products.get.route.tsx      # GET    /v1/products/:id              (public, 404)
+    ├── products.create.route.tsx   # POST   /v1/products                  (guarded + idempotent)
+    └── products.delete.route.tsx   # DELETE /v1/products/:id              (guarded)
+```
+
+REST routes are the **one** primitive that is NOT auto-discovered — they're registered explicitly via `restRoutes` in `app.config.ts`.
+
+## A route — query / path / body in, typed JSON out
+
+```tsx
+// routes/v1/products.create.route.tsx
+import { defineRestRoute, requireScope } from '@voltro/protocol/rest'
+import { Schema } from 'effect'
+import { Product, toProduct } from '../../lib/product'
+
+export default defineRestRoute({
+  method: 'POST',
+  path:   '/v1/products',
+  input:  Schema.Struct({                     // the desugar parses { query?, params?, body? }
+    body: Schema.Struct({
+      name:       Schema.NonEmptyString,
+      priceCents: Schema.Number.pipe(Schema.int(), Schema.greaterThanOrEqualTo(0)),
+    }),
+  }),
+  output:  Product,
+  summary: 'Create a product',                // OpenAPI metadata
+  guards:  [requireScope('products:write')],  // → 403 when the subject lacks the scope
+  handler: async ({ body }, ctx) => { /* ctx.subject + ctx.store injected by serve */ },
+})
+```
+
+The desugar, per request: method gate (`405`), input decode (`400` on a bad shape), guards (`403`), `await handler`, output encode (`200` JSON). A handler may `throw { status, message }` for a specific code (the `get`/`delete` routes `throw { status: 404 }`).
+
+## OpenAPI + Swagger UI — zero hand-written docs
+
+```ts
+// app.config.ts
+import { openapiPlugin } from '@voltro/plugin-openapi'
+
+const routes = [listProducts, getProduct, createProduct, deleteProduct]
+
+export default {
+  type: 'api' as const, name: 'AcmeApi', store: 'memory' as const,
+  plugins:    [openapiPlugin({ routes, info: { title: 'Acme API', version: '1.0.0' } })],
+  restRoutes: routes,            // the SAME array mounts the routes AND documents them
+  idempotency: true,             // Idempotency-Key dedup for the mutating routes
+}
+```
+
+`openapiPlugin` serves `GET /openapi.json` (the spec) + `GET /docs` (Swagger UI), built from the descriptors — `:id` paths render as OpenAPI `{id}`, and refined types (`NonEmptyString`, …) resolve under `components.schemas`. The route descriptors ARE the spec; there is nothing to hand-maintain.
+
+## Auth — the demo key is DEV-ONLY
+
+The guarded routes gate on a scope. `app.config.ts` wires an [`apiKeyStrategy`](/docs/authentication/overview) so `Authorization: Bearer <key>` resolves to a scoped `Subject`, and ships ONE hardcoded demo key (`restdemo_devkey` → `products:read` + `products:write`) so the write path works on first boot:
+
+```ts
+import { apiKeyStrategy } from '@voltro/protocol/apikey'
+// sha256('restdemo_devkey') → a fixed scoped Subject. DEV-ONLY.
+const DEMO_KEY_SHA256 = 'c891…41cd'
+auth: { strategies: [apiKeyStrategy({
+  prefix: 'restdemo_',
+  resolveKey: (hash) => hash === DEMO_KEY_SHA256
+    ? { id: 'svc_demo', tenantId: 'acme', scopes: ['products:read', 'products:write'] }
+    : null,
+})] }
+```
+
+Before deploying, **delete the demo constant** and look the token hash up against your own key store (store key **hashes**, never raw tokens) — or flip on the framework's first-class API keys (`apiKeys: true`) for admin-gated issue/list/revoke against `_voltro_api_keys`.
+
+## Try it (curl)
+
+```bash
+# The spec + interactive docs
+curl -s http://localhost:4000/openapi.json | jq '.info, (.paths | keys)'
+open http://localhost:4000/docs
+
+# Public reads — no auth
+curl -s http://localhost:4000/v1/products                    # → { "data": [], "nextCursor": null }
+
+# Guarded create — the demo key carries products:write
+curl -s -X POST http://localhost:4000/v1/products \
+  -H 'Authorization: Bearer restdemo_devkey' -H 'content-type: application/json' \
+  -d '{"name":"Widget","priceCents":1999}'                   # → 201 the created product
+
+# Without the key → 403 (the guard rejects)
+curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:4000/v1/products \
+  -H 'content-type: application/json' -d '{"name":"x","priceCents":1}'   # → 403
+
+# Idempotency — same key header twice → the first response replayed, not re-inserted
+curl -s -X POST http://localhost:4000/v1/products \
+  -H 'Authorization: Bearer restdemo_devkey' -H 'Idempotency-Key: order-42' \
+  -H 'content-type: application/json' -d '{"name":"Once","priceCents":500}'
+```
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| Durable data | `store: 'memory'` → `store: 'postgres'` (data survives restarts) |
+| Real API keys | delete the demo key; hash-lookup your own store, or set `apiKeys: true` |
+| Multi-tenant scoping | add `tenant()` to the table + scope each handler by the key's `tenantId` |
+| Versioning / sunset | a descriptor's `deprecated` sets a `Deprecation:` header; `sunset` sets `Sunset:` + `410`s past the date |
+
+## Anti-patterns
+
+- **Forgetting to register the route.** REST routes are NOT auto-discovered — add every `defineRestRoute` to the `restRoutes` array (and the `openapiPlugin` `routes` array) in `app.config.ts`, or it's neither mounted nor documented.
+- **Shipping the DEV-ONLY demo key.** It's a sample credential, like a README password — delete it and back the strategy with a real hash store before deploying.
+- **Reaching for REST when an action fits.** A REST route is for EXTERNAL HTTP callers. For your own reactive frontend, a [mutation](/docs/data/mutations) / [action](/docs/data/actions) over the rpc WebSocket is typed end-to-end and auto-optimistic.
+- **Expecting `Idempotency-Key` on the rpc transport.** It rides the HTTP surface only; double-submit from your own frontend is a UI concern (disable the button), not server idempotency.
+
+## See also
+
+- [App templates](/docs/reference/templates) — the full catalogue
+- [`@voltro/plugin-openapi`](/docs/plugins/overview) — the spec + Swagger generator
+- [`api-auth`](/docs/templates/api-auth) — real user sessions (the rpc-side auth counterpart)
+
+
+
+---
+
+<!-- source: en/templates/api-saas.md -->
+## API · SaaS bundle
+
+_The SaaS plugin bundle in one domain — billing entitlements (a quota gate), in-app + console notifications, analytics events, and live presence, wired turnkey. One projects.create mutation exercises billing + analytics + notifications together. Zero-infra boot._
+
+The four cross-cutting **SaaS plugins** wired turnkey in one cohesive domain — the billing / notifications / analytics / presence slice of the framework end to end, the way [`api-durable`](/docs/templates/api-durable) bundles the durable surface. A single `projects.create` mutation pulls three of them together. Boots **zero-infra** (`store: 'memory'`). Template id: **`api-saas`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-saas
+```
+
+## What ships
+
+```text
+apps/acme/api/
+├── app.config.ts                       # billingPlugin + notificationsPlugin + presencePlugin
+├── package.json                        # + the four SaaS plugins
+├── database/schema.ts                  # a tenant-scoped `projects` table
+├── queries/projects.list.query.ts      # reactive list (+ .server.ts)
+└── mutations/projects.create.mutation.ts  # the bundle in one handler (+ .server.ts)
+```
+
+Each plugin contributes its **own** routes + tables automatically — you wire them in `app.config.ts` and consume their services in handlers. The boot banner shows them all: `billing.subscription/startCheckout/…`, `notifications.inbox/markRead/…`, `presence.heartbeat/list/leave`.
+
+## The four plugins
+
+```ts
+// app.config.ts
+import { billingPlugin } from '@voltro/plugin-billing'
+import { presencePlugin } from '@voltro/plugin-presence'
+import { notificationsPlugin, consoleChannel } from '@voltro/plugin-notifications'
+
+plugins: [
+  billingPlugin({
+    provider: 'mock',                                   // in-memory; no Stripe key
+    plans: {                                            // tier → quota, in code
+      free: { entitlements: { projects: 3 } },
+      pro:  { priceId: 'price_demo_pro', entitlements: { projects: 'unlimited' } },
+    },
+  }),
+  notificationsPlugin({ channels: [consoleChannel()] }),  // + a durable in-app inbox
+  presencePlugin(),                                       // presence.heartbeat / list / leave
+]
+```
+
+- **Billing** — subscriptions + entitlements; `plans` is the single source of tier→quota truth. The `free` default caps `projects` at 3.
+- **Notifications** — one `NotificationService.send(...)` across channels + an in-app inbox (`useInbox()` / `useUnreadCount()` on the client).
+- **Presence** — ephemeral "who's online" per channel, plus the `usePresence(channel)` hook.
+
+## The bundle, in one handler
+
+`projects.create` is Effect-mode so it can `yield*` the plugin services the framework provides in the per-request stack:
+
+```ts
+// mutations/projects.create.mutation.server.ts
+import { EffectStore, useAnalytics } from '@voltro/runtime'
+import { requireEntitlement } from '@voltro/plugin-billing'
+import { NotificationService } from '@voltro/plugin-notifications'
+
+const execute = (input: { name: string }, ctx) =>
+  Effect.gen(function* () {
+    yield* requireEntitlement(ctx, 'projects', 1)                 // 1. BILLING — quota gate
+    const store = yield* EffectStore
+    const row = yield* store.insert('projects', { name: input.name })  // tenant() auto-stamps
+    yield* (yield* useAnalytics()).track({                        // 2. ANALYTICS — event
+      name: 'project_created', subjectId: ctx.request.subject.id, properties: { name: input.name },
+    })
+    yield* Effect.promise(() => (yield* NotificationService).send({  // 3. NOTIFICATIONS — inbox + console
+      to: ctx.request.subject.id ?? 'system', category: 'project',
+      title: 'Project created', body: `"${input.name}" is live.`,
+    }))
+    return { id: row['id'] as string, name: row['name'] as string, tenantId: row['tenantId'] as string }
+  })
+```
+
+The billing plugin auto-merges its typed `EntitlementExceeded` (+ `BillingError`) into this procedure's wire-error union — the client decodes the over-quota failure typed, **without** a manual `error:` declaration.
+
+## Try it (curl)
+
+`projects.create` and the plugin routes are rpc procedures — call them with `useMutation` / `useSubscription` from a web app, or over HTTP via the dev inspect endpoint:
+
+```bash
+# Create projects — the free plan allows 3
+for i in 1 2 3; do
+  curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+    -H 'content-type: application/json' \
+    -d "{\"tag\":\"projects.create\",\"input\":{\"name\":\"Project $i\"}}"
+done
+# → { "ok": true, "result": { "id": "proj_…", … } }
+
+# The 4th trips the billing entitlement
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' \
+  -d '{"tag":"projects.create","input":{"name":"Project 4"}}'
+# → { "ok": false, "error": { "_tag": "EntitlementExceeded", "entitlement": "projects", "limit": 3, "used": 3 } }
+```
+
+Each successful create also logs `[notify:project] → …: Project created` (console channel) and persists a `notification_inbox` row.
+
+## Enable durable analytics
+
+`useAnalytics().track(...)` is **noop-safe** with no sink configured (it never crashes), so the event API is reachable on the zero-infra memory store. To actually STORE + query events (`aggregate` / `timeseries` / `topN`), add a sink AND a SQL store — the postgres-lite sink needs a `SqlClient`:
+
+```ts
+// app.config.ts
+import { postgresAnalytics } from '@voltro/plugin-analytics-postgres'
+
+export default {
+  type: 'api' as const, name: 'AcmeApi',
+  store: 'postgres' as const,          // or 'sqlite' (file:./.voltro/db.sqlite)
+  analytics: postgresAnalytics(),       // events → _voltro_events
+  plugins: [ /* … */ ],
+}
+```
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| Real subscriptions / checkout | `billingPlugin({ provider: 'stripe', apiKey, webhookSecret, plans })` with real `priceId`s |
+| Email / Slack / SMS notifications | add `emailChannel()` / `webhookChannel()` / `smsChannel()` to `channels` |
+| Durable analytics at scale | `postgresAnalytics()` on postgres, or swap to `@voltro/plugin-clickhouse` / `@voltro/plugin-duckdb` |
+| Live presence roster in the UI | subscribe a reactive query over `_voltro_presence`, or use `usePresence(channel)` |
+
+## Anti-patterns
+
+- **Hand-rolling `notifications.*` / `billing.*` / `presence.*` procedures.** The plugins own those tag namespaces — boot fails on a collision. Use the plugin routes + services.
+- **Expecting analytics to persist on `memory`.** The postgres-lite sink needs a `SqlClient`. `track()` is reachable + safe on memory; events land in `_voltro_events` only once you wire a sink + a SQL store.
+- **Skipping the entitlement gate on a paid action.** A scope says "may you call this"; an entitlement says "do you have quota left" — orthogonal. A paid action needs both.
+
+## See also
+
+- [Plugins overview](/docs/plugins/overview) — the full plugin catalogue + status
+- [`api-durable`](/docs/templates/api-durable) — the durable + reactive bundle (the sibling showcase)
+- [App templates](/docs/reference/templates) — the full catalogue
+
+
+
+---
+
+<!-- source: en/templates/api-observability.md -->
+## API · Observability
+
+_Production-readiness in one backend — Prometheus metrics (GET /metrics + a custom counter), Sentry error tracking (inert without a DSN), distributed tracing, and a @voltro/testing unit test (makeTestContext + mockStore, run with voltro test). Zero-infra boot._
+
+The production-readiness slice in one backend: **Prometheus metrics**, **Sentry error tracking**, **distributed tracing**, and a **`@voltro/testing` unit test** — so a real service is observable AND covered from day one. Boots **zero-infra** (`store: 'memory'`). Template id: **`api-observability`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-observability
+```
+
+## What ships
+
+```text
+apps/acme/api/
+├── app.config.ts                       # prometheusPlugin() + sentryPlugin()
+├── package.json                        # + the plugins; devDeps: @voltro/testing, vitest
+├── database/schema.ts                  # a tenant-scoped `notes` table
+├── queries/notes.list.query.ts         # reactive list (+ .server.ts)
+├── mutations/notes.create.mutation.ts  # create + a custom metric (+ .server.ts)
+└── tests/notes.create.test.ts          # makeTestContext + mockStore
+```
+
+## Metrics — `GET /metrics` + your own counters
+
+```ts
+// app.config.ts
+import { prometheusPlugin } from '@voltro/plugin-prometheus'
+import { sentryPlugin } from '@voltro/plugin-sentry'
+
+plugins: [ prometheusPlugin(), sentryPlugin() ]
+```
+
+The framework already records `voltro_rpc_*` / `voltro_http_*` / subscription / cache metrics into Effect's global `MetricRegistry`; `prometheusPlugin()` exports them at `/metrics`. A **custom** counter shows up there automatically — declare it at module level, bump it in a handler:
+
+```ts
+// mutations/notes.create.mutation.server.ts
+import { Effect, Metric } from 'effect'
+import { counter } from '@voltro/runtime'
+
+const notesCreated = counter('app_notes_created_total', 'Notes created.')
+Effect.runSync(Metric.increment(notesCreated))   // → /metrics + the DevTools Metrics panel
+```
+
+```bash
+curl -s http://localhost:4000/metrics | grep -E 'app_notes_created_total|voltro_rpc_requests_total'
+# app_notes_created_total 1
+# voltro_rpc_requests_total{status="ok",tag="mutation.notes.create"} 1
+```
+
+Point Prometheus / Grafana at `/metrics`; gate a public deploy with `prometheusPlugin({ token })` / `PROMETHEUS_TOKEN`.
+
+## Errors — Sentry, inert until you set a DSN
+
+`sentryPlugin()` reports rpc / REST / workflow / schedule / subscriber / render errors, correlated to the active **`traceId`** — and is **inert without `SENTRY_DSN`**, so it ships wired. Set the env to turn it on; no code change. The plugin subscribes to the framework's server-error bus once, so every primitive is covered. For the full browser→backend waterfall, add the `sentry` field to a paired web app's `app.config.ts`.
+
+## Tracing — on by default
+
+`voltro dev` runs a buffer-only tracer that powers the DevTools **Traces** panel and stamps `fields.traceId` on every log line (`voltro logs --trace <id>`). Set `OTEL_EXPORTER_OTLP_ENDPOINT` to ship spans to Jaeger / Tempo / Honeycomb — no code change.
+
+## Testing — `makeTestContext`, no DB, no server
+
+```ts
+// tests/notes.create.test.ts
+import { makeTestContext, mockStore } from '@voltro/testing'
+import createNote from '../mutations/notes.create.mutation.server'
+
+const ctx = makeTestContext({
+  subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+  store:   mockStore({ notes: [] }),
+})
+const row = await createNote({ title: 'Hello', body: 'World' }, ctx)
+expect(row.tenantId).toBe('acme')   // tenant() stamped it — the REAL store, in-memory
+```
+
+`ctx.store` is the **same** mixin-wrapped store production uses, so tenant auto-scoping, soft-delete filtering, and audit auto-fill behave identically — in milliseconds, no docker. `ctx.withTenant('t2', (c) => c.store.query(…))` re-scopes the same data to prove cross-tenant isolation. Run it:
+
+```bash
+voltro test
+```
+
+The package also ships `MockClock` / `MockEmail` / `mockAi` / `makeWorkflowRunner` and `runDialectParity` (the `@voltro/testing/dialect` subpath).
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| Metrics on a public deploy | `prometheusPlugin({ token })` + scrape over TLS |
+| Errors in Sentry | set `SENTRY_DSN`; add `sentryPlugin({ traces: true })` for performance traces |
+| Spans in your tracer | `OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318` |
+| Vendor-native (Datadog) | add `@voltro/plugin-datadog` — agentless metrics + correlated logs/traces |
+| A CI gate | run `voltro test`; add `runDialectParity` for hand-written SQL |
+
+## Anti-patterns
+
+- **Re-creating the counter per call.** Declare `counter(...)` at MODULE level — a per-call `counter()` muddies the series.
+- **Wiring Sentry per primitive.** The plugin covers them all via the server-error bus — you just set the DSN.
+- **A real DB in unit tests.** `makeTestContext` + `mockStore` give real store behaviour in-memory; save a live database for `voltro e2e`.
+
+## See also
+
+- [Observability](/docs/observability/overview) · [Distributed tracing](/docs/observability/distributed-tracing) · [Unit testing](/docs/testing/unit-testing)
+- [App templates](/docs/reference/templates) — the full catalogue
+
+
+
+---
+
+<!-- source: en/templates/api-webhooks.md -->
+## API · Webhooks
+
+_First-class webhooks both ways — a signature-verified incoming *.webhook.tsx receiver (genericProvider HMAC) that rejects forged traffic before your handler runs, plus an outgoing defineOutgoingEvent a mutation emits to subscribed targets via a durable signed delivery workflow. Zero-infra boot._
+
+Webhooks **both ways**, wired turnkey: a **signature-verified incoming receiver** that rejects forged traffic before your code runs, and an **outgoing event** a mutation emits to subscribed targets through a durable, signed, retried delivery workflow. Webhooks are **file-convention** (drop a `*.webhook.tsx`, it's auto-discovered) — not a `plugins:[]` entry. Boots **zero-infra** (`store: 'memory'`). Template id: **`api-webhooks`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-webhooks
+```
+
+The shipped `.env` supplies a DEV-ONLY `VOLTRO_WEBHOOK_SECRET_ORDERS` so the incoming receiver boots with a key.
+
+## What ships
+
+```text
+apps/acme/api/
+├── .env                                  # VOLTRO_WEBHOOK_SECRET_ORDERS (dev signing secret)
+├── database/schema.ts                    # orders + webhookTables() bookkeeping
+├── webhooks/orders.webhook.tsx           # INCOMING — signature-verified receiver
+├── events/order.completed.webhook.tsx    # OUTGOING — defineOutgoingEvent
+├── mutations/orders.fulfill.mutation.ts  # create order + emit (+ .server.ts)
+└── queries/orders.list.query.ts          # reactive list (+ .server.ts)
+```
+
+## Incoming — verified before your handler runs
+
+```tsx
+// webhooks/orders.webhook.tsx → mounts at POST /webhooks/orders
+import { defineIncomingWebhook } from '@voltro/plugin-webhooks'
+import { genericProvider } from '@voltro/plugin-webhooks/providers'
+
+export default defineIncomingWebhook({
+  id: 'orders', provider: genericProvider(),
+  payload: Schema.Struct({ event: Schema.String, orderId: Schema.String, sku: Schema.String, totalCents: Schema.Number }),
+  handler: async (ctx) => { /* ctx.body is validated; ctx.idempotencyKey set */ },
+})
+```
+
+The framework's incoming middleware runs **before** `handler`:
+
+1. verify the HMAC over `<ts>.<rawBody>` with `VOLTRO_WEBHOOK_SECRET_ORDERS` → **`401`** on mismatch
+2. reject a `t` older than the replay window → **`401`**
+3. decode the body against `payload` → **`422`** on a bad shape
+4. claim the `Idempotency-Key` → a replay returns **`200 {duplicate:true}`** and the handler is **skipped**
+
+Only a request that passes all of that reaches `handler`. You never hand-roll a signature check, and forged traffic never runs your code. Built-in presets: `stripeProvider` / `githubProvider` / `slackProvider` / `genericProvider` (or `defineWebhookProvider` for a custom partner). The signing secret is `VOLTRO_WEBHOOK_SECRET_<UPPER_ID>` — here `_ORDERS`.
+
+### Try it (curl)
+
+```bash
+SECRET='devonly-webhook-secret-change-me'
+BODY='{"event":"order.created","orderId":"o_1","sku":"WIDGET","totalCents":1999}'
+TS=$(date +%s)
+SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.*= //')
+
+# valid signature → 200, handler runs
+curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:4000/webhooks/orders \
+  -H "X-Webhook-Signature: t=$TS,v1=$SIG" -H 'content-type: application/json' \
+  -H 'Idempotency-Key: evt_1' --data "$BODY"            # → 200
+
+# no signature → 401 · forged → 401 · valid sig + wrong shape → 422
+curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:4000/webhooks/orders \
+  -H 'content-type: application/json' --data "$BODY"     # → 401
+```
+
+## Outgoing — emit to subscribed targets
+
+```ts
+// events/order.completed.webhook.tsx
+export default defineOutgoingEvent({ id: 'order.completed', payload: Schema.Struct({ /* … */ }), version: 1 })
+
+// mutations/orders.fulfill.mutation.server.ts — after the row commits:
+const { eventId, deliveries } = await useWebhooks(ctx).emit('order.completed', { orderId, tenantId, /* … */ })
+```
+
+External systems subscribe at runtime — `ctx.webhooks.subscribe({ event: 'order.completed', url })` (a row in `_voltro_webhook_targets`). On `emit`, the framework fans out to every matching target through a **durable delivery workflow** — HMAC-signing the outbound request, retrying with backoff, honouring `Retry-After`; each attempt lands in `_voltro_webhook_deliveries`. `emit` returns immediately (the POSTs run in the background); `deliveries` is one entry per matched target (empty until someone subscribes).
+
+```bash
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"orders.fulfill","input":{"sku":"WIDGET","totalCents":4999}}'
+# → the order; the log shows: order.completed event=… → 0 target(s)
+```
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| A real partner (Stripe/GitHub/Slack) | swap `genericProvider()` → `stripeProvider()` etc.; set `VOLTRO_WEBHOOK_SECRET_<ID>` |
+| Durable targets + delivery history | `store: 'postgres'` (the `_voltro_webhook_*` tables survive restarts) |
+| A subscribe API | a mutation calling `ctx.webhooks.subscribe({ event, url, secret?, retry? })` |
+| A custom signature scheme | `defineWebhookProvider({ id, signature, idempotency })` |
+
+## Anti-patterns
+
+- **Trusting webhook input without verification.** The framework rejects unsigned incoming requests by default — don't set `signature: undefined` unless a network trust boundary gates the route.
+- **Mutating domain state synchronously in the outgoing emit path.** Mutate in the mutation, THEN emit — delivery is async (rollback drops the queued send).
+- **Re-using the idempotency TTL as the provider's retry window.** Pick TTL ≥ 2× the provider's max retry window so the dedup catches the slowest retry.
+
+## See also
+
+- [Plugins overview](/docs/plugins/overview) — `@voltro/plugin-webhooks` + the full catalogue
+- [App templates](/docs/reference/templates) — the full catalogue
+
+
+
+---
+
+<!-- source: en/templates/api-search.md -->
+## API · Search
+
+_Full-text search that stays in sync — @voltro/plugin-search mirrors every table write into an index via the post-commit change tap; the synthesized search.query rpc returns tenant-scoped hits. Memory backend (zero infra); swap one line for Typesense/Meilisearch/Algolia._
+
+Search that never drifts from your data. `@voltro/plugin-search` taps the post-commit ChangeEvent stream: every insert/update to a source table upserts its doc into a search index, every delete removes it — no app code, no cron, no manual reindex. The plugin synthesizes a `search.query` rpc that returns hits **auto-filtered to the caller's tenant**. The template runs on `memoryBackend()` (in-process, zero infra) so it boots and validates with nothing installed; going to production is one line in `lib/search.ts`. Template id: **`api-search`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-search
+voltro add-app search --template=api-search --to acme
+```
+
+## What ships
+
+```text
+apps/acme/api/
+├── app.config.ts                       # store:'memory', plugins: [searchPlugin({ backend, indexes })]
+├── lib/
+│   └── search.ts                       # the SHARED backend instance + the articles index spec
+├── database/schema.ts                  # actors, tenants, articles (tenant-scoped, reactive)
+├── mutations/articles.create.*         # writes that auto-index via the tap
+├── queries/articles.list.*             # a live list to sit next to the search box
+├── seeds/articles.seed.ts              # demo data
+├── startup/searchBackfill.startup.tsx  # backfillIndex() on boot
+├── package.json                        # + @voltro/plugin-search
+└── tsconfig.json
+```
+
+## The index — `searchPlugin` + a shared backend
+
+`lib/search.ts` holds the wiring, shared so `app.config.ts` (the plugin) and the boot startup (the backfill) use the **same** backend instance — `memoryBackend()` is a closure over a Map, so two calls would be two separate indexes:
+
+```ts
+// lib/search.ts
+import { memoryBackend, type IndexSpec, type SearchDoc } from '@voltro/plugin-search'
+
+export const searchBackend = memoryBackend()
+
+export const articlesIndex: IndexSpec = {
+  index: 'articles',
+  // Flatten a row → a search doc (must include `id`).
+  map: (row): SearchDoc => ({
+    id: row['id'] as string,
+    title: row['title'] as string,
+    body: row['body'] as string,
+    tag: row['tag'] as string,
+    tenantId: row['tenantId'] as string,
+  }),
+  // Makes search.query auto-filter to the caller's tenant — no leakage.
+  tenantField: 'tenantId',
+}
+```
+
+```ts
+// app.config.ts
+import { searchPlugin } from '@voltro/plugin-search'
+import { searchBackend, articlesIndex } from './lib/search'
+
+export default {
+  type: 'api' as const, name: 'AcmeSearch', store: 'memory' as const,
+  plugins: [searchPlugin({ backend: searchBackend, indexes: { articles: articlesIndex } })],
+}
+```
+
+## Live sync — the change tap
+
+There is **no indexing code** in your handlers. The plugin registers an `onChangeEvent` tap; when a mutation commits a write to `articles`, the plugin maps the row and upserts it (or removes it on delete). So a freshly-created article is searchable on the very next request:
+
+```bash
+# create an article — indexed on commit
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"articles.create","input":{"tenantId":"acme","title":"Reactive queries","body":"Subscriptions push deltas live.","tag":"guide"}}'
+# …then find it
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"search.query","input":{"index":"articles","q":"reactive"}}'
+# → { ok:true, result:[ { id, title:"Reactive queries", … } ] }
+```
+
+## `search.query` — tenant-scoped by construction
+
+The plugin synthesizes the `search.query` rpc — input `{ index, q, limit?, filters? }`, output the matching docs. Because the index spec set `tenantField: 'tenantId'`, the query auto-filters to the caller's tenant: a request resolved to tenant `acme` only ever sees `acme` docs, even though every tenant's docs share one index. Searching the same term as a different tenant returns nothing.
+
+## Backfill existing rows
+
+The change tap covers writes AFTER boot. `startup/searchBackfill.startup.tsx` seeds the index from rows already in the table — the demo seed's articles, or every row after a restart or a switch to a new engine. It uses the same `searchBackend` instance, so the docs it writes are exactly what `search.query` reads:
+
+```tsx
+import { backfillIndex } from '@voltro/plugin-search'
+import { database } from '../database/schema'
+import { searchBackend, articlesIndex } from '../lib/search'
+
+export default async ({ store, log }) => {
+  const rows = await store.query(database.articles.descriptor)
+  const count = await backfillIndex(searchBackend, articlesIndex, rows)
+  log.info(`search: backfilled ${count} article(s) into the index`)
+}
+```
+
+## On the web side
+
+```tsx
+import { useSearch } from '@voltro/plugin-search/web'
+const { results, run, pending } = useSearch('articles')
+// run('reactive') → results auto-scoped to the signed-in tenant
+```
+
+The `/web` subpath imports nothing server-only — it's just a query over the `search.query` rpc, browser-safe.
+
+## Going to production — one line
+
+`memoryBackend()` is in-process: great for dev, single-instance only. For real deployments swap it in `lib/search.ts` for a vendor engine — the indexing + query + backfill code is identical:
+
+```ts
+import { typesenseBackend } from '@voltro/plugin-search'         // or meilisearch / algolia
+export const searchBackend = typesenseBackend({ url: process.env.TYPESENSE_URL!, apiKey: process.env.TYPESENSE_KEY! })
+```
+
+## When to use api-search vs. the other backends
+
+| You want… | Pick |
+|---|---|
+| Full-text search kept in sync with a table | `api-search` |
+| Semantic / vector search + a RAG agent | [`api-ai`](/docs/templates/api-ai) (a `vectorEmbedding()` index + an agent) |
+| The minimal CRUD backend | [`api-backend`](/docs/templates/api-backend) |
+
+`api-search` is keyword/full-text (Typesense-style); `api-ai` is embeddings/semantic. They compose — `hybridSearch` fuses both.
+
+## Pairs well with
+
+- Any **web** template — drop a search box wired to `useSearch('articles')`.
+- [`api-backend`](/docs/templates/api-backend) patterns for the rest of the CRUD surface around the searchable table.
+
+## Anti-patterns
+
+- **Two `memoryBackend()` instances.** It's a closure over a Map — calling it twice gives two separate indexes, so a backfill into one is invisible to a `search.query` reading the other. Create ONE instance in `lib/search.ts` and share it (this template's whole reason for that file).
+- **Hand-indexing in your mutation.** Don't `searchBackend.upsert(...)` inside `articles.create` — the change tap already does it on commit. Doubling up risks drift and races. Let the tap own the index.
+- **Forgetting `tenantField`.** Without it, `search.query` returns every tenant's hits — a cross-tenant leak. Set `tenantField` on any index over a `tenant()`-scoped table.
+- **Relying on the seed's rows being indexed without the backfill.** The seed writes through the RAW store (no subject); whether that fires the tap is store-dependent. The boot `backfillIndex` is what guarantees pre-existing rows are in the index — keep it.
+
+
+
+---
+
+<!-- source: en/templates/api-feature-flags.md -->
+## API · Feature flags
+
+_Feature flags wired turnkey with @voltro/plugin-flags — flags as code (kill-switch / % rollout / targeting), a declarative gatedBy map that fails typed FlagDisabled before the handler, an in-handler requireFlag guard, and flags.evaluate for useFlag() on the web. Memory store, zero infra._
+
+Feature flags without a service. `@voltro/plugin-flags` declares flags **as code** and gates rpc calls two ways — declaratively (a `gatedBy` map fails `FlagDisabled` before the handler) and in-handler (`requireFlag(ctx, key)`). A flag is a bare boolean (kill-switch) or a rich definition with a deterministic `% rollout` and OR-of-rules `targeting`. The client gets the same evaluation via `useFlag()`. Memory store is zero-infra; `postgres` adds runtime toggles. Template id: **`api-feature-flags`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-feature-flags
+```
+
+## Flags as code
+
+```ts
+// app.config.ts
+import { flagsPlugin } from '@voltro/plugin-flags'
+
+flagsPlugin({
+  flags: {
+    newEditor: true,                                                   // kill-switch (on)
+    betaExport: false,                                                 // kill-switch (off)
+    proDashboard: { targeting: [{ metadata: { plan: 'pro' } }] },      // targeting
+    gradualRollout: { rollout: 25 },                                   // deterministic % rollout
+  },
+  gatedBy: { 'notes.export': 'betaExport' },     // tag → flag
+  store: 'memory',
+})
+```
+
+## Two ways to gate
+
+- **Declarative** — the `gatedBy` map points `notes.export` at `betaExport`. The framework fails typed `FlagDisabled` **before** the handler when the flag is off. No code in the handler.
+- **In-handler** — `notes.create` calls the Effect-native guard:
+
+```ts
+// notes.create.mutation.server.ts
+import { requireFlag } from '@voltro/plugin-flags'
+
+export default (input, ctx) => Effect.gen(function* () {
+  yield* requireFlag(ctx, 'newEditor')        // fails typed FlagDisabled when off
+  const store = yield* EffectStore
+  return yield* store.insert('notes', { title: input.title, body: input.body })
+})
+```
+
+Declare `error: FlagDisabled` (from the browser-safe `@voltro/plugin-flags/errors`) on the procedure so the client decodes it typed.
+
+## Try it
+
+```bash
+# newEditor ON → requireFlag passes → created:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"notes.create","input":{"tenantId":"acme","title":"hi","body":"x"}}'
+# betaExport OFF → gatedBy blocks → typed FlagDisabled:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"notes.export","input":{}}'
+# → { ok:false, error:{ _tag:"FlagDisabled", flag:"betaExport" } }
+```
+
+## On the web side
+
+```tsx
+import { useFlag } from '@voltro/plugin-flags/web'
+const showBeta = useFlag('betaExport')        // same targeting + rollout as the server
+{showBeta && <BetaExportButton />}
+```
+
+## Runtime toggles
+
+`store: 'postgres'` overlays runtime-toggleable flags (`_voltro_feature_flags`) on the code baseline — flip a kill-switch without a deploy. The dashboard ships a **Flags** panel for it.
+
+## Anti-patterns
+
+- **Trusting `useFlag` for enforcement.** It's a UI affordance; the server guard (`gatedBy` / `requireFlag`) is the real gate. Never gate a write on the client alone.
+- **A `% rollout` keyed on a non-stable id.** Rollout buckets deterministically per subject (or tenant via `rolloutBy: 'tenant'`) — an anonymous/idless caller buckets on `'anon'`, so don't expect per-call variation.
+
+
+
+---
+
+<!-- source: en/templates/api-ratelimit.md -->
+## API · Rate limiting
+
+_Per-endpoint / per-subject / per-tenant rpc rate limiting with @voltro/plugin-ratelimit — a default fallback + rules (exact tag or regex), sliding-window / token-bucket algorithms, composite keying, and a typed RateLimited error auto-merged into the wire error union. Memory store, zero infra._
+
+Throttle rpc calls without touching a handler. `@voltro/plugin-ratelimit` runs on the rpc interceptors — the one surface that sees every call AND the resolved subject. A `default` fallback applies everywhere; `rules` override per endpoint with a choice of algorithm and bucket key. Over-limit calls fail a typed `RateLimited` error the plugin merges into every procedure's wire error union. Memory store is single-node; postgres/redis for a cluster. Template id: **`api-ratelimit`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-ratelimit
+```
+
+## Limits as config
+
+```ts
+// app.config.ts
+import { rateLimitPlugin } from '@voltro/plugin-ratelimit'
+
+rateLimitPlugin({
+  default: { limit: 100, window: '1m' },                 // global fallback, per subject
+  rules: [
+    // 3/min per tenant, token-bucket (starts full → burst of 3, then refills)
+    { match: 'notes.create', limit: 3, window: '1m', algorithm: 'token-bucket', burst: 3, by: 'tenant' },
+  ],
+  store: 'memory',
+})
+```
+
+- **`match`** — an exact tag or a `/regex/`; **`kind`** narrows to mutation/query/action.
+- **`algorithm`** — `sliding-window` (default), `fixed-window`, or `token-bucket` (with `burst`).
+- **`by`** — the bucket key: `subject` (default), `tenant`, `apiKey`, `global`, or a composite array.
+
+## Typed `RateLimited`
+
+There's no rate-limit code in the handler — the interceptor enforces it. An over-limit call fails `RateLimited` (`{ tag, limit, retryAfterMs, resetAtMs }`), auto-merged into the procedure's wire error union, so the client decodes it typed and can show a "try again in N seconds".
+
+## Try it
+
+```bash
+# Fire notes.create four times for tenant 'acme' — the 4th trips the limit:
+for i in 1 2 3 4; do
+  curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+    -d "{\"tag\":\"notes.create\",\"input\":{\"tenantId\":\"acme\",\"title\":\"n$i\",\"body\":\"x\"}}"
+done
+# → calls 1-3: { ok:true } ; call 4: { ok:false, error:{ _tag:"RateLimited", … } }
+```
+
+## Multi-node
+
+`store: 'memory'` is single-process. Switch to `'postgres'` (state under a row lock, reuses `DB_*`/`PG_*`) or `'redis'` (fastest — one atomic Lua script; reads `CACHE_REDIS_URL` / `REDIS_URL`). All shared stores **fail open** on a backend error — a limiter outage degrades to "no limit", never to "deny everything".
+
+## Anti-patterns
+
+- **Rate-limiting reads you didn't mean to.** The `default` applies to queries too. Use `kind: 'mutation'` on a rule (or a tighter default) if you only want to throttle writes.
+- **Reusing the cache store as the limiter store.** A cache is get/set; a limiter needs an ATOMIC increment. They're separate backends — `store` here is independent of `@voltro/cache`.
+
+
+
+---
+
+<!-- source: en/templates/api-rbac.md -->
+## API · RBAC
+
+_Role-based access control with @voltro/plugin-rbac — a role→scope map, an interceptor that resolves the caller's roles to scopes, and an in-handler permission(ctx, 'notes:write') guard that fails typed Forbidden. admin:full bypasses. Config-only, zero infra; useCan() for web UI._
+
+Roles → scopes → guards. `@voltro/plugin-rbac` compiles a role map and an rpc interceptor resolves each caller's **roles** to **scopes**, stamped on the subject. Guard handlers with `permission(ctx, 'notes:write')`, the Effect-native guard that fails typed `Forbidden`. The `admin:full` scope is a blanket bypass. Config-only, zero infra. Template id: **`api-rbac`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-rbac
+```
+
+## Roles as config
+
+```ts
+// app.config.ts
+import { rbacPlugin } from '@voltro/plugin-rbac'
+
+const roles = {
+  viewer: ['notes:read'],
+  editor: ['notes:read', 'notes:write'],
+  admin:  ['admin:full'],                 // blanket bypass — passes every check
+}
+
+rbacPlugin({
+  roles,
+  // PRODUCTION: the default resolver reads subject.metadata.roles (set by your
+  // auth strategy), or do a DB lookup. The shipped DEMO maps tenant → role so
+  // you can try each via the x-tenant header with zero auth setup:
+  resolveRoles: (subject) =>
+    ({ acme: ['admin'], editors: ['editor'], readers: ['viewer'] })[subject.tenantId ?? ''] ?? ['viewer'],
+})
+```
+
+## Guard with `permission()`
+
+```ts
+// notes.create.mutation.server.ts
+import { permission } from '@voltro/plugin-rbac'
+
+export default (input, ctx) => Effect.gen(function* () {
+  yield* permission(ctx, 'notes:write')       // fails typed Forbidden for viewer
+  const store = yield* EffectStore
+  return yield* store.insert('notes', { title: input.title, body: input.body })
+})
+```
+
+Declare `error: Forbidden` (from the browser-safe `@voltro/plugin-rbac/errors`). Companions: `anyPermission(ctx, [...])` (OR), `assertPermission` (sync throw), `can(ctx, scope)` (boolean).
+
+## Try it
+
+```bash
+# admin tenant → admin:full → passes:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' -H 'x-tenant: acme' \
+  -d '{"tag":"notes.create","input":{"title":"hi","body":"x"}}'
+# → { ok:true, … }
+
+# readers tenant → viewer → notes:write missing → typed Forbidden:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' -H 'x-tenant: readers' \
+  -d '{"tag":"notes.create","input":{"title":"hi","body":"x"}}'
+# → { ok:false, error:{ _tag:"Forbidden", required:"notes:write" } }
+```
+
+## On the web side
+
+```tsx
+import { useCan } from '@voltro/plugin-rbac/web'
+const canWrite = useCan('notes:write')
+{canWrite && <NewNoteButton />}      // hide affordances the user can't use
+```
+
+`useCan` is a UI affordance only — the server `permission()` guard is the enforcement.
+
+## Persisted roles
+
+Set `tables: true` to store assignments in `roles` / `userRoles` tables and resolve them from the DB (multitenant-aware). The shipped template stays config-only.
+
+## Anti-patterns
+
+- **Returning scopes from `resolveRoles`.** It returns role SLUGS (`['editor']`); the `roles` map turns those into scopes. Returning scopes directly bypasses the map.
+- **Scopes ≠ entitlements.** RBAC answers "may you call this"; billing entitlements (see [`api-saas`](/docs/templates/api-saas)) answer "do you have quota left". A procedure can need both.
+
+
+
+---
+
+<!-- source: en/templates/api-moderation.md -->
+## API · Moderation
+
+_Pre-commit content moderation with @voltro/plugin-moderation — checks named input fields BEFORE the handler; a block rule rejects banned content with typed ContentRejected (write never commits), a flag rule writes it but queues it for review. keywordProvider or aiProvider. Memory store, zero infra._
+
+Stop bad content before it's written. `@voltro/plugin-moderation` checks named input fields on the rpc interceptors, **before** the handler: a `block` rule rejects the call with typed `ContentRejected` (the write never commits); a `flag` rule lets the write through but queues it for review. The provider is pluggable — `keywordProvider` is a zero-dep deny-list, `aiProvider()` an optional LLM classifier. Config-only, zero infra. Template id: **`api-moderation`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-moderation
+```
+
+## Rules as config
+
+```ts
+// app.config.ts
+import { moderationPlugin, keywordProvider } from '@voltro/plugin-moderation'
+
+moderationPlugin({
+  provider: keywordProvider(['spam', 'scam', 'phishing', 'malware']),
+  rules: [
+    { match: 'posts.create',    fields: ['title', 'body'], action: 'block' },   // reject
+    { match: 'comments.create', fields: ['body'],          action: 'flag'  },   // write + queue
+  ],
+})
+```
+
+There's no moderation code in the handlers — `posts.create` and `comments.create` are plain inserts; the interceptor enforces the rules.
+
+## Block vs flag
+
+- **block** — banned content fails typed `ContentRejected` (`{ tag, categories, reason }`) before the write. Declare `error: ContentRejected` (from `@voltro/plugin-moderation/errors`) on the procedure.
+- **flag** — the row IS written, but flagged; the dashboard's **Moderation** panel surfaces the review queue. For rewriting rather than rejecting, the in-handler `moderate(text)` helper returns a verdict you act on (the interceptor can't rewrite input).
+
+## Try it
+
+```bash
+# banned word in a post → blocked, nothing written:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"posts.create","input":{"title":"hi","body":"buy cheap spam now"}}'
+# → { ok:false, error:{ _tag:"ContentRejected", reason:"matched denied term(s): spam" } }
+
+# clean post → written; banned COMMENT → written but flagged (flag doesn't block):
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"comments.create","input":{"body":"this is spam"}}'
+# → { ok:true, … }   (queued for review)
+```
+
+## Swap in AI
+
+Replace `keywordProvider([...])` with `aiProvider()` — the rules don't change. `aiProvider` fails OPEN (a classifier outage lets content through rather than blocking everything).
+
+## Anti-patterns
+
+- **Putting the keyword list in the client.** Moderation runs server-side on the interceptor — a client check is bypassable. Keep the provider + rules on the api.
+- **Using `block` where you meant `flag`.** `block` is a hard reject (nothing written); `flag` keeps the content for human review. Pick per surface — comments often `flag`, public posts often `block`.
+
+
+
+---
+
+<!-- source: en/templates/api-versioning.md -->
+## API · Versioning
+
+_Full row history + time-travel with @voltro/plugin-versioning — snapshots every insert/update/delete on the listed tables via the post-commit change tap; read every version with rowHistory() and the value at a past instant with rowAsOf(). audit() is who/when; this is what-changed-to-what. Memory store, zero infra._
+
+Every version of a row, queryable. `@voltro/plugin-versioning` rides the post-commit ChangeEvent tap and records a FULL snapshot of every insert/update/delete on the listed tables. Read it back with `rowHistory(store, table, id)` (every version) and `rowAsOf(store, table, id, when)` (the value at a past instant — time-travel). `audit()` records WHO/WHEN; this records WHAT it changed to, so you can diff or restore. Memory store, zero infra. Template id: **`api-versioning`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-versioning
+```
+
+## Wire it + read it back
+
+```ts
+// app.config.ts
+import { versioningPlugin } from '@voltro/plugin-versioning'
+export default { type: 'api', name: 'AcmeVer', store: 'memory',
+  plugins: [versioningPlugin({ tables: ['documents'] })] }
+```
+
+The snapshotting is automatic. The point is to **read history through handlers** — the template ships two actions:
+
+```ts
+// documents.history.action.server.ts
+import { rowHistory } from '@voltro/plugin-versioning'
+export default async ({ id }, ctx) => {
+  const rows = await rowHistory(ctx.store, 'documents', id, ctx.request.subject.tenantId ?? null)
+  return rows.map((r) => ({ version: r.version, op: r.op, content: r.data?.content ?? null, changedAt: r.changedAt }))
+}
+
+// documents.asOf.action.server.ts
+import { rowAsOf } from '@voltro/plugin-versioning'
+export default async ({ id, at }, ctx) =>
+  rowAsOf(ctx.store, 'documents', id, ctx.request.subject.tenantId ?? null, at)  // the row as it was at `at` (epoch ms), or null
+```
+
+## Try it
+
+```bash
+ID=$(curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"documents.create","input":{"title":"Spec","content":"draft v1"}}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d "{\"tag\":\"documents.update\",\"input\":{\"id\":\"$ID\",\"content\":\"final v2\"}}" >/dev/null
+
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d "{\"tag\":\"documents.history\",\"input\":{\"id\":\"$ID\"}}"
+# → [ { version:1, op:"insert", content:"draft v1", … }, { version:2, op:"update", content:"final v2", … } ]
+# documents.asOf with v1's changedAt → { content:"draft v1" }  (time-travel)
+```
+
+## audit vs versioning
+
+| You want… | Use |
+|---|---|
+| WHO changed a row + WHEN | `audit()` mixin |
+| WHAT it changed to (every prior value) | `@voltro/plugin-versioning` (this) |
+
+They compose — `audit()` for accountability, versioning for diff/restore.
+
+## Production
+
+The memory history store is single-process. With a SQL store, history persists in `_voltro_row_history`. High-churn tables grow history fast — version what you need to diff/restore, not everything.
+
+## Anti-patterns
+
+- **Listing `versioningPlugin({ tables })` and stopping there.** That records history but never shows it. The value is in the READS — wire `rowHistory` / `rowAsOf` into a handler (or the dashboard) like this template does.
+- **Versioning every table.** Snapshots cost storage proportional to write volume. Pick the tables whose past values you actually need.
+
+
+
+---
+
+<!-- source: en/templates/api-backend-deactivation.md -->
+## API · Deactivation
+
+_The deactivation() schema mixin — adds deactivatedAt/deactivatedBy so a user can be locked out (your auth refuses a deactivated subject) while its row stays VISIBLE and queryable. The deliberate opposite of softDelete(), which hides + anonymises. Pure schema, zero infra._
+
+Lock a user out without erasing them. The `deactivation()` schema mixin adds `deactivatedAt` + `deactivatedBy` columns. A deactivated subject can't authenticate, but its row stays **visible and queryable** — no read-scoping, no delete interception. That's the deliberate opposite of `softDelete()`, which hides + anonymises. It's a pure schema mixin (no `plugins[]` entry). Template id: **`api-backend-deactivation`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-backend-deactivation
+```
+
+## The mixin
+
+```ts
+// database/schema.ts
+import { deactivation } from '@voltro/plugin-deactivation'
+
+export const users = table('users', {
+  id: id(), email: text().unique(), name: text(),
+})
+  // adds deactivatedAt + deactivatedBy (→ actors); pulls audit() transitively.
+  // NO defaultWhere — a deactivated user still shows up in queries.
+  .with(deactivation())
+  .reactive()
+```
+
+Deactivate with a normal update — `deactivatedAt` is just a column:
+
+```ts
+// users.deactivate.mutation.server.ts
+export default async ({ id }, ctx) =>
+  ctx.store.update('users', id, { deactivatedAt: new Date() })
+```
+
+## Visible-but-locked-out
+
+The point is what happens on a READ. After deactivation the row is STILL there and readable, just stamped:
+
+```bash
+ID=$(curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"users.create","input":{"email":"ada@acme.com","name":"Ada"}}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
+
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d "{\"tag\":\"users.deactivate\",\"input\":{\"id\":\"$ID\"}}" >/dev/null
+
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d "{\"tag\":\"users.get\",\"input\":{\"id\":\"$ID\"}}"
+# → { ok:true, result:{ …, deactivatedAt:"2026-…" } }   (NOT null → still visible)
+```
+
+With `softDelete()` instead, that `users.get` would return `null` — the row would be hidden.
+
+## deactivation vs softDelete
+
+| You want… | Use |
+|---|---|
+| Hide + anonymise a row (GDPR, "delete my account") | `softDelete()` |
+| Keep the row visible but mark the subject as locked out | `deactivation()` (this) |
+
+Compose the full lifecycle: `users.with(audit(), softDelete(), deactivation())`.
+
+## Anti-patterns
+
+- **Expecting deactivation to hide the row.** It doesn't — that's `softDelete()`. If a deactivated user must disappear from a list, filter on `deactivatedAt IS NULL` in that query yourself.
+- **Forgetting to enforce it in auth.** The mixin only stamps the column; YOUR auth resolver must refuse a subject whose `deactivatedAt` is set. The data layer keeps the row queryable on purpose.
+
+
+
+---
+
+<!-- source: en/templates/api-governance.md -->
+## API · Governance
+
+_Data governance in one plugin with @voltro/plugin-governance — AES-256-GCM field encryption for .encrypted() columns (handler sees plaintext, ciphertext at rest), admin-gated GDPR governance.export/erase over declared subjectScopes, a consent ledger, and retention TTL sweeps. Memory store, zero infra._
+
+Four compliance primitives, one plugin. `@voltro/plugin-governance` gives you **field encryption** (AES-256-GCM for `.encrypted()` columns — handlers see plaintext, the column holds `enc:v1:…` at rest), **GDPR** export/erase (admin-gated, walking declared subject scopes), a **consent ledger**, and **retention** sweeps (delete/anonymise rows past a TTL). The template boots zero-infra with a dev encryption key. Template id: **`api-governance`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-governance
+```
+
+The shipped `.env` carries a DEV `VOLTRO_FIELD_ENCRYPTION_KEY`. Generate your own (`openssl rand -hex 32`) and keep it in a secret store for production.
+
+## Field encryption
+
+```ts
+// database/schema.ts
+export const profiles = table('profiles', {
+  id: id(), name: text(), email: text(),
+  ssn: text().encrypted(),         // AES-256-GCM at rest
+}).with(audit())
+
+// app.config.ts
+governancePlugin({ fieldEncryption: true /* reads VOLTRO_FIELD_ENCRYPTION_KEY */ })
+```
+
+You pass plaintext; the store middleware encrypts on write and decrypts on read — handlers never touch the ciphertext. Boot **fails loud** if an `.encrypted()` column exists but no cipher is registered.
+
+```bash
+ID=$(curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d '{"tag":"profiles.create","input":{"name":"Ada","email":"ada@acme.com","ssn":"123-45-6789"}}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
+  -d "{\"tag\":\"profiles.get\",\"input\":{\"id\":\"$ID\"}}"
+# → { ok:true, result:{ …, ssn:"123-45-6789" } }   (plaintext — the column stored enc:v1:…)
+```
+
+## GDPR, consent, retention
+
+```ts
+governancePlugin({
+  fieldEncryption: true,
+  subjectScopes: [{ table: 'profiles', subjectField: 'id' }],     // GDPR walks these
+  retention: [{ table: 'profiles', ttlMs: 365 * 86_400_000, action: 'delete' }],
+})
+```
+
+- **GDPR** — `governance.export` / `governance.erase` are **admin-gated** (call as a subject with `admin:full` — see [`api-rbac`](/docs/templates/api-rbac)); they walk `subjectScopes` to bundle or erase everything belonging to a subject. `GovernanceService` exposes the same in-handler.
+- **Consent** — `governance.consent` (a mutation) records a grant; `governance.hasConsent` (a reactive query) checks it — subscribe to it on the web, or call `GovernanceService.hasConsent(...)` in a handler.
+- **Retention** — the sweep deletes (or `anonymize`s) rows whose age past `dateField` (default `createdAt`) exceeds `ttlMs`.
+
+## Rules
+
+- **Don't encrypt what you filter on.** An `.encrypted()` column is ciphertext on disk — no `WHERE` / `ORDER BY` in SQL. Encrypt fields you read back WHOLE (PII, tokens, notes).
+- **The key is everything.** GCM fails closed on a bad key — you get an error, never silent corruption. Back the key up; rotating it means re-encrypting.
+- **GDPR endpoints are admin-only by design.** Don't remove the `admin:full` gate — an unauthenticated export/erase is a data-exfiltration / griefing hole.
+
+
+
+---
+
+<!-- source: en/templates/api-kv.md -->
+## API · Key-value
+
+_Durable ctx.kv on an external-event-sync domain — a sync cursor you can't recompute plus TTL-bounded idempotency markers, contrasted with ctx.store (the rows) and ctx.cache. Zero-infra boot._
+
+The template that exercises **`ctx.kv`** — the framework's storage primitive for state you **can't recompute**. Instead of another CRUD reference, it ships a cohesive **external-event-sync** domain: a durable **cursor** (a watermark past everything already pulled) and TTL-bounded **idempotency markers** that dedupe redelivered events. Around them sit the synced rows in `ctx.store`, so the template makes the store-vs-kv-vs-cache distinction concrete. It boots with **zero infrastructure** (`store: 'memory'`). Template id: **`api-kv`**.
+
+## Scaffold
+
+```bash
+voltro create-project acme --api=api-kv
+```
+
+No env or services required. On `store: 'memory'`, `ctx.kv` runs on its `database` backend in-process — durable within the run, reset on restart. Switch `app.config.ts` to `store: 'postgres'` and the cursor + markers survive restarts and are shared across replicas.
+
+## The one idea
+
+Three storage primitives, three contracts — pick by what a loss costs you:
+
+| Primitive | Holds | If you lose it | Default backend |
+|---|---|---|---|
+| `ctx.cache` | recomputable derived views | free — recompute | memory (evicts for capacity) |
+| `ctx.kv` | the cursor + idempotency markers | re-process / double-process | database (durable, never evicted) |
+| `ctx.store` | the synced rows | re-fetchable from the source | your SQL store |
+
+A cursor is the textbook `ctx.kv` case: it isn't derived from anything you still hold, so a cache (which evicts) would silently reset your sync, and a hand-managed table row is overkill. See [durable key-value](/docs/caching/key-value).
+
+## What ships
+
+```text
+apps/acme/api/                                   # dir named by the app, not the template
+├── app.config.ts                                # type:api, store:'memory', defineEnv
+├── package.json
+├── tsconfig.json
+├── README.md
+├── database/
+│   └── schema.ts                                # actors + tenants (core) + a synced_events table
+├── actions/
+│   ├── sync.pull.action.ts                      # descriptor — pull a page of events
+│   ├── sync.pull.action.server.ts               # executor — getOrElse/has/set(ttl)/set
+│   ├── sync.status.action.ts                    # descriptor — read-only view
+│   ├── sync.status.action.server.ts             # executor (Effect) — yield* Kv
+│   ├── sync.reset.action.ts                     # descriptor — rewind the sync
+│   └── sync.reset.action.server.ts              # executor — delete + list/delete
+└── queries/
+    ├── events.list.query.ts                     # descriptor — reactive rows (store, for contrast)
+    └── events.list.query.server.ts              # executor — table descriptor
+```
+
+Every primitive is **auto-discovered by file convention** — nothing is registered in `app.config.ts`. The durable KV lives in the framework's `_voltro_kv` table (created automatically); no schema of yours models the cursor.
+
+## Database — the rows, deliberately NOT the cursor
+
+The schema declares the two framework core tables plus a `synced_events` table for the ingested rows. The cursor and markers are **not** modelled here — they're durable KV.
+
+```ts
+// database/schema.ts
+import {
+  databaseHandle, id, integer, table, text, timestamp, type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// Core tables — required by the tenant / audit mixins.
+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 events we ingest from the source — re-fetchable, so a table is their home.
+export const syncedEvents = table('synced_events', {
+  id:         id({ prefix: 'evt' }),
+  externalId: text(),
+  kind:       text(),
+  payload:    text(),
+  sequence:   integer(),
+})
+  .with(tenant())   // tenantId + audit columns, auto-stamped from the subject
+  .reactive()       // events.list subscription wakes on every insert
+
+export type SyncedEvent = InferRow<typeof syncedEvents>
+export const database = databaseHandle({ actors, tenants, syncedEvents })
+```
+
+## Pull — the durable cursor + idempotency markers
+
+`sync.pull` is the heart of the template. The descriptor declares the schema; the executor reads the durable cursor, pulls a page, dedupes each event against a TTL marker, inserts the new rows, and advances the cursor.
+
+```ts
+// actions/sync.pull.action.ts — descriptor (browser-safe)
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const syncPull = defineAction({
+  name: 'sync.pull',
+  input: Schema.Struct({
+    limit: Schema.optional(Schema.Int.pipe(Schema.greaterThan(0))),
+  }),
+  output: Schema.Struct({
+    pulled:  Schema.Int, // newly ingested (marker written)
+    skipped: Schema.Int, // already seen within the idempotency window
+    cursor:  Schema.Int, // the durable watermark after this call
+  }),
+})
+```
+
+```ts
+// actions/sync.pull.action.server.ts — executor (default export)
+import type { AppContext } from '@voltro/runtime'
+
+// Stand-in for a real upstream — deterministic + pure so it boots with no
+// network. A real handler would `fetch()` here.
+const fetchSince = (sequence: number, limit: number) =>
+  Array.from({ length: limit }, (_unused, i) => {
+    const seq = sequence + i + 1
+    return {
+      externalId: `ext-${seq}`,
+      kind:       seq % 3 === 0 ? 'updated' : 'created',
+      payload:    JSON.stringify({ seq }),
+      sequence:   seq,
+    }
+  })
+
+const MARKER_TTL_MS = 24 * 60 * 60_000 // 24h idempotency window
+
+const execute = async (input: { limit?: number }, ctx: AppContext) => {
+  // KV keys are app-global — fold the tenant in so two tenants never collide.
+  const tenantId = ctx.request.subject.tenantId ?? 'anon'
+  const cursorKey = `sync:${tenantId}:cursor`
+  const limit = Math.min(input.limit ?? 5, 50)
+
+  // Durable cursor — getOrElse writes the default (0) ONLY on a first-run miss.
+  const cursor = await ctx.kv.getOrElse<number>(cursorKey, () => 0)
+
+  let pulled = 0
+  let skipped = 0
+  let highest = cursor
+
+  for (const evt of fetchSince(cursor, limit)) {
+    const markerKey = `sync:${tenantId}:seen:${evt.externalId}`
+    if (await ctx.kv.has(markerKey)) {
+      skipped++ // the source redelivered it within the TTL window
+    } else {
+      await ctx.store.insert('synced_events', {
+        externalId: evt.externalId, kind: evt.kind,
+        payload:    evt.payload,   sequence: evt.sequence, tenantId,
+      })
+      await ctx.kv.set(markerKey, evt.sequence, { ttlMs: MARKER_TTL_MS })
+      pulled++
+    }
+    highest = Math.max(highest, evt.sequence)
+  }
+
+  await ctx.kv.set(cursorKey, highest) // advance the durable watermark
+  return { pulled, skipped, cursor: highest }
+}
+
+export default execute
+```
+
+Four KV operations carry the whole flow: **`getOrElse`** reads the cursor (writing the `0` default only on a genuine first-run miss), **`has`** checks a marker without deserializing, **`set(…, { ttlMs })`** writes a bounded idempotency marker, and **`set`** advances the cursor. The rows go to `ctx.store` because they're re-fetchable; the cursor + markers go to `ctx.kv` because they're not.
+
+## Status & reset — two handler surfaces
+
+Durable KV is reachable two ways, both wired in every runtime (`voltro dev` AND
+`voltro serve`): the async **`ctx.kv`** facade (`sync.pull` / `sync.reset`) and
+the Effect-native **`Kv`** service via `yield* Kv` (`sync.status`). They share
+one resolved store — pick by whether your handler is `async` or an `Effect`.
+
+```ts
+// actions/sync.status.action.server.ts — executor (Effect mode)
+import { Effect } from 'effect'
+import { Kv } from '@voltro/kv'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const kv = yield* Kv // the framework provides Kv to every handler runtime
+    const tenantId = ctx.request.subject.tenantId ?? 'anon'
+    const cursor = yield* kv.getOrElse(`sync:${tenantId}:cursor`, () => 0)
+    // list(prefix) → every live (non-expired) marker under it.
+    const markers = yield* kv.list(`sync:${tenantId}:seen:`)
+    return { cursor, activeMarkers: markers.length }
+  })
+
+export default execute
+```
+
+```ts
+// actions/sync.reset.action.server.ts — executor
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (input: { markers?: boolean }, ctx: AppContext) => {
+  const tenantId = ctx.request.subject.tenantId ?? 'anon'
+
+  // delete(key) → boolean (did it exist?).
+  const cursorCleared = await ctx.kv.delete(`sync:${tenantId}:cursor`)
+
+  let markersCleared = 0
+  if (input.markers) {
+    // list(prefix) + delete() to sweep a set. `ctx.kv.clear()` would drop the
+    // app's ENTIRE KV namespace — too broad for one tenant's sync keys.
+    for (const key of await ctx.kv.list(`sync:${tenantId}:seen:`)) {
+      if (await ctx.kv.delete(key)) markersCleared++
+    }
+  }
+
+  return { cursorCleared, markersCleared }
+}
+
+export default execute
+```
+
+Resetting **only the cursor** leaves the markers alive — so a following `sync.pull` re-reads from the start but **skips everything**, proving the two KV concerns are independent. That is the template's punchline.
+
+## Try it
+
+Over the rpc surface (a `voltro dev` web client, `POST /rpc`, or the inspect `invoke` endpoint):
+
+```jsonc
+{ "tag": "sync.pull",   "input": { "limit": 5 } }   // → { pulled: 5, skipped: 0, cursor: 5 }
+{ "tag": "sync.pull",   "input": { "limit": 5 } }   // → { pulled: 5, skipped: 0, cursor: 10 }
+{ "tag": "sync.status", "input": {} }               // → { cursor: 10, activeMarkers: 10 }
+{ "tag": "sync.reset",  "input": {} }               // → { cursorCleared: true, markersCleared: 0 }
+{ "tag": "sync.pull",   "input": { "limit": 5 } }   // → { pulled: 0, skipped: 5, cursor: 5 }  ← markers survived
+```
+
+The synced rows stream in live via the `events.list` subscription.
+
+## TTL & tenant namespacing
+
+- **TTL** — markers are written with `{ ttlMs }` (a 24h idempotency window). Expiry is lazy: an expired marker reads as a miss and is dropped on the next `has`/`get`. The cursor has **no** TTL — permanent until deleted.
+- **Tenant namespacing** — `ctx.kv` keys are app-global; the facade never namespaces for you. Every key folds in `ctx.request.subject.tenantId` (`sync:${tenantId}:…`) so two tenants' cursors/markers never collide.
+
+## When to use api-kv vs. the variants
+
+| You need… | Pick |
+|---|---|
+| The smallest CRUD reference to extend | [`api-backend`](/docs/templates/api-backend) |
+| Durable state you can't recompute (cursors, progress, idempotency) | `api-kv` |
+| Workflows / triggers / schedules exercised end-to-end | [`api-durable`](/docs/templates/api-durable) |
+| The advanced schema DSL + query caching | [`api-data-advanced`](/docs/templates/api-data-advanced) |
+
+## Anti-patterns
+
+- **Modelling a cursor as a table row.** A watermark you hand-`UPDATE` is exactly what `ctx.kv` replaces — one durable key, no schema, no migration. Reach for a table only when the data is relational and queried.
+- **Caching a cursor.** `ctx.cache` evicts for capacity; a cache miss on your sync watermark silently rewinds the sync (or double-processes). Durable state that a miss corrupts belongs in `ctx.kv`, never the cache.
+- **Forgetting the tenant in the key.** `ctx.kv` keys are app-global. A bare `sync:cursor` collides across tenants — always fold `subject.tenantId` (or the actor) into the key.
+- **Storing large or unbounded values in KV.** `ctx.kv` is for small control state — cursors, flags, markers — not blobs or ever-growing lists. It's durable with no eviction, so bulk data never gets reclaimed; model relational/bulk data as a table instead.
+
+## Pairs well with
+
+- [`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.