@voltro/cli 0.33.0 → 0.34.0

package/templates/agent-docs/plugins.md

@@ -19,7 +19,7 @@ The framework ships some plugins; you write your own; the contract is small enou
 
 - [The plugin contract](/docs/plugins/contract) — `definePlugin`, lifecycle hooks, rpc interceptors, framework-version compatibility
 - [plugin-audit](/docs/plugins/audit) — mutation audit log + `audit()` mixin
-- [plugin-auth](/docs/plugins/auth) — full auth suite: password (rehash-on-verify) + sessions (multi-key rotation + sliding-window) + magic-link/reset + passkeys (atomic clone detection, BYO multi-replica challenge store) + CSRF + session revocation + memberships/switch-tenant + TOTP/MFA (sign-in enforcement + recovery codes), mounted by `authRoutesPlugin()` (see also the [Authentication section](/docs/authentication/overview))
+- [plugin-auth](/docs/plugins/auth) — full auth suite: password (rehash-on-verify) + sessions (multi-key rotation + sliding-window) + magic-link/reset + email verification + tenant invitations + user impersonation + passkeys (atomic clone detection, BYO multi-replica challenge store) + CSRF + session revocation + memberships/switch-tenant + TOTP/MFA (sign-in enforcement + recovery codes), mounted by `authRoutesPlugin()` (see also the [Authentication section](/docs/authentication/overview))
 - [plugin-multitenancy](/docs/plugins/multitenancy) — `tenant()` schema mixin + `assertOwnTenant` write-guard + `TenantMismatch`
 - [plugin-soft-delete](/docs/plugins/soft-delete) — `softDelete()` schema mixin (hide on delete, `hardDelete()` bypass)
 - [plugin-rbac](/docs/plugins/rbac) — roles + permissions + the `permission()` guard
@@ -46,7 +46,8 @@ The framework ships some plugins; you write your own; the contract is small enou
 - [plugin-governance](/docs/plugins/governance) — data governance: retention TTL sweep, GDPR export + erasure, consent ledger, field encryption
 - [plugin-openapi](/docs/plugins/openapi) — OpenAPI 3.1 spec + Swagger-UI docs generated from your `defineRestRoute` descriptors and (opt-in) rpc procedures
 - [plugin-versioning](/docs/plugins/versioning) — full row history + time-travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions`); what-changed-to-what on every write
-- [plugin-presence](/docs/plugins/presence) — ephemeral realtime presence: heartbeat roster per channel + `usePresence` / `useTyping` hooks, cross-instance
+- [plugin-presence](/docs/plugins/presence) — ephemeral realtime presence: heartbeat roster per channel + `usePresence` / `useTyping` hooks, held in memory; cross-instance with [plugin-broadcast](/docs/plugins/broadcast)
+- [plugin-auth-social](/docs/plugins/auth-social) — first-party Sign in with Google / GitHub / Apple: mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, sessions issued through plugin-auth
 - [plugin-scim](/docs/plugins/scim) — SCIM 2.0 provisioning (Users + Groups at `/scim/v2`) so an enterprise IdP can create/deactivate users
 - [plugin-sso-saml](/docs/plugins/sso-saml) — enterprise SAML 2.0 SSO: SP-initiated login + Single Logout, ACS, metadata (+ IdP-metadata-URL auto cert rotation, encrypted assertions, SP request signing); mints a framework session
 - [API keys](/docs/configuration/api-keys) — **first-class** (not a plugin): `apiKeys: true` enables Bearer-key auth + admin-gated issue/list/revoke
@@ -60,7 +61,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | Plugin | Status | What it does |
 |---|---|---|
 | `@voltro/plugin-audit` | ✓ | Mutation audit log + `audit()` mixin |
-| `@voltro/plugin-auth` | ✓ | Full auth suite via `authRoutesPlugin()`: password (rehash-on-verify), sessions (multi-key rotation + sliding-window), magic-link + password-reset, passkeys/WebAuthn (atomic clone detection, BYO multi-replica challenge store), CSRF, session enumeration + revocation, memberships + switch-tenant, TOTP/MFA (sign-in enforcement + recovery codes); `authTables` schemas |
+| `@voltro/plugin-auth` | ✓ | Full auth suite via `authRoutesPlugin()`: password (rehash-on-verify), sessions (multi-key rotation + sliding-window), magic-link + password-reset, email verification (off/soft/strict policy), tenant invitations (addressed, single-use, role chosen by the inviter), user impersonation (marked, time-bounded, escalation-proof), passkeys/WebAuthn (atomic clone detection, BYO multi-replica challenge store), CSRF, session enumeration + revocation, memberships + switch-tenant, TOTP/MFA (sign-in enforcement + recovery codes); `authTables` schemas |
 | `@voltro/plugin-multitenancy` | ✓ | `tenant()` schema mixin (read-scope + write-fill) + `assertOwnTenant` guard + typed `TenantMismatch` |
 | `@voltro/plugin-soft-delete` | ✓ | `softDelete()` schema mixin — `deletedAt` / `deletedBy`; `delete` → UPDATE, `hardDelete()` bypass |
 | `@voltro/plugin-rbac` | ✓ | Roles compile to scopes + the `permission()` handler guard + typed `ScopeError` |
@@ -71,6 +72,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-postgis` | ✓ | Postgres-native `geography` / `geometry` columns + spatial predicates (`ST_DWithin`, `ST_Contains`, `ST_Intersects`); GiST indexes via `.expressionIndex(..., { kind: 'gist' })`. No `ST_Distance` projection yet. Postgres-only by design (fails loud elsewhere). [→ details](/docs/plugins/postgis) |
 | `@voltro/plugin-broadcast` | ✓ | Cross-replica reactivity — fans out app-mutation change events to every replica over a pub/sub bus (Redis / NATS). Closes the single-instance gap for every non-postgres dialect. [→ details](/docs/plugins/broadcast) |
 | `@voltro/plugin-webhooks` | ✓ | Incoming + outgoing webhooks — `defineIncomingWebhook` (signature verify + idempotency, Stripe/GitHub/Slack presets) and `defineEvent` (durable delivery workflow, HMAC signing, retries, filters). [→ details](/docs/plugins/webhooks) |
+| `@voltro/plugin-auth-social` | ✓ | First-party social login — Sign in with Google / GitHub / Apple with no identity vendor: authorize URL + code exchange + JWKS-verified ID tokens, mandatory PKCE (S256) and `state`, an explicit account-linking policy (`never` by default), Apple's signed-JWT client secret / one-time name / private-relay email all handled; sessions via `issueUserSession`. [→ details](/docs/plugins/auth-social) |
 | `@voltro/plugin-auth-{workos,kinde,clerk,auth0,supabase,oidc}` | ✓ | Six IdP adapters over the shared `jwtBearerStrategy` — JWKS verify + claims→tenant mapping; WorkOS additionally ships hosted-login OAuth primitives (`workosAuthorizationUrl` / `workosAuthenticateWithCode`) for a redirect-based SSO login flow. [→ details](/docs/authentication/external-idp) |
 | `@voltro/plugin-analytics-postgres` | ✓ | First-party lite — events on the main DataStore, cross-dialect (postgres / mysql / mariadb / mssql / sqlite / turso). [→ details](/docs/plugins/analytics#voltroplugin-analytics-postgres) |
 | `@voltro/plugin-duckdb` | ✓ | Embedded DuckDB sidecar — real OLAP performance, no external service. [→ details](/docs/plugins/analytics#voltroplugin-duckdb) |
@@ -91,7 +93,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-governance` | ✓ | Data governance — retention TTL sweep (delete / anonymise), GDPR subject export + erasure (admin-gated routes + `GovernanceService`), consent ledger, field encryption. [→ details](/docs/plugins/governance) |
 | `@voltro/plugin-openapi` | ✓ | OpenAPI 3.1 spec (`GET /openapi.json`) + Swagger-UI (`GET /docs`) generated from `defineRestRoute` descriptors AND (opt-in) rpc procedures (queries/mutations/actions/streams → `POST /rpc/<name>`) — input/output/error Schemas via `JSONSchema.make`. [→ details](/docs/plugins/openapi) |
 | `@voltro/plugin-versioning` | ✓ | Full row history + time-travel — value snapshot of every insert/update/delete on listed tables into `_voltro_row_history` (rides the ChangeEvent tap); `rowHistory` / `rowAsOf` queries + `restoreAsOf` / `diffVersions`; TTL + per-row cap retention. [→ details](/docs/plugins/versioning) |
-| `@voltro/plugin-presence` | ✓ | Ephemeral realtime presence — heartbeat roster per channel (`presence.heartbeat`/`list`/`leave` + `usePresence`), a `useTyping` typing indicator, swept `_voltro_presence` table, cross-instance. [→ details](/docs/plugins/presence) |
+| `@voltro/plugin-presence` | ✓ | Ephemeral realtime presence — heartbeat roster per channel (`presence.heartbeat`/`list`/`leave` + `usePresence`), a `useTyping` typing indicator. Held **in memory**, owner-partitioned — no table is written; cross-instance requires [`@voltro/plugin-broadcast`](/docs/plugins/broadcast), and without a broker each replica sees only its own clients. [→ details](/docs/plugins/presence) |
 | `@voltro/plugin-scim` | ✓ | SCIM 2.0 provisioning — Users + Groups REST at `/scim/v2` (bearer-gated) incl. group-membership PATCH/PUT + the RFC 7644 discovery trio (ServiceProviderConfig/Schemas/ResourceTypes), `userName`/`externalId`/`displayName eq` filters, pagination, unique `userName`, `active:false` deactivation; `_voltro_scim_users`/`_voltro_scim_groups`. [→ details](/docs/plugins/scim) |
 | `@voltro/plugin-sso-saml` | ✓ | Enterprise SAML 2.0 SSO — SP-initiated login + Single Logout (both directions) + ACS + SP metadata under `/saml`; IdP-metadata-URL auto cert rotation, encrypted assertions, clock-skew, SP request signing. Signature verify via `@node-saml/node-saml` (optional+lazy), mints a framework session. [→ details](/docs/plugins/sso-saml) |
 
@@ -126,7 +128,7 @@ Order matters: the framework composes outer→inner, so the rate-limit intercept
 | `extendSchema` | Contribute tables + custom SQL migrations (tracked in `_voltro_plugin_migrations`). |
 | `services` | Provide an Effect `Layer` whose Tags every handler can `yield*` (e.g. `MailService`, `StorageService`). |
 | `routes` | Register plugin-owned rpc queries / mutations / actions (alias-prefixed tags). |
-| `httpRoutes` | Serve public raw-HTTP endpoints on the framework listener (e.g. `GET /_voltro/storage/:id`). The request carries `store` — the app's DataStore — for a route that must read or write (a login endpoint minting a session row cannot be an rpc mutation). Not tenant-scoped: raw HTTP has no resolved Subject, so scope it yourself. |
+| `httpRoutes` | Serve public raw-HTTP endpoints on the framework listener (e.g. `GET /_voltro/storage/:id`). The request carries `store` — the app's DataStore — for a route that must read or write (a login endpoint minting a session row cannot be an rpc mutation), and `remoteAddr`, the client address already resolved through `security.trustedProxies` (use it instead of `x-forwarded-for`). Not tenant-scoped: raw HTTP has no resolved Subject, so scope it yourself. A state-changing route is [origin-checked](/docs/security/overview#cross-site-requests-are-refused) unless it declares `originGuard: 'exempt'`. |
 | `inspectEndpoints` | Mount tooling under `/_voltro/inspect/plugins/<alias>/…`. |
 | `onScheduleFire` / `onWorkflowStep` / `onHttpRequest` | Wrap every cron firing, every workflow `step()`, every pre-auth HTTP request. |
 | `onInstall` / `onActivate` / `onDeactivate` / `onUninstall` | Lifecycle hooks at first-install, boot, shutdown, and removal. |
@@ -207,10 +209,15 @@ To REPLACE one deliberately, declare it:
 
 ```ts
 // Adopt the plugin's namespace, add your own leaves beside it…
-defineQuery({ name: 'notifications.archive', … })
-
-// …and REPLACE just the one you need to behave differently.
-defineMutation({ name: 'notifications.markRead', overridesPlugin: true, … })
+defineQuery({ name: 'notifications.archive', guards: [{ scope: 'notifications:read' }], … })
+
+// …and REPLACE just the one you need to behave differently. Your replacement is
+// YOUR procedure, so it needs its own access decision — the plugin's does not
+// carry over with the tag.
+defineMutation({
+  name: 'notifications.markRead', overridesPlugin: true,
+  guards: [{ scope: 'notifications:write' }], …
+})
 ```
 
 The plugin's route is dropped, not merely permitted alongside yours — permitting
@@ -345,6 +352,8 @@ onChangeEvent: (event: PluginChangeEvent) => Effect.Effect<void, unknown>
 // PluginChangeEvent = {
 //   table, op: 'insert'|'update'|'delete', new: Row | null, old: Row | null,
 //   origin?: 'inline' | 'injected', changeScope: 'local' | 'fleet',
+//   traceId?, subjectId?, procedure?,
+//   oversized?: 'rehydrated' | 'tombstone' | 'unrecovered',
 // }
 ```
 
@@ -359,6 +368,8 @@ onChangeEvent: (event) =>
       )
 ```
 
+**Check `event.oversized` before you treat an image as a snapshot.** It is absent on an ordinary event, and set when the transport could not carry the row and the images were reconstructed — a row over postgres' 8000-byte NOTIFY cap. `'rehydrated'` means `new` is the row re-read from the database (correct to index or forward, but the row as it is NOW rather than the image at commit); `'tombstone'` means a delete whose `old` is the primary key and nothing else (enough to REMOVE the row, never a record of what it held); `'unrecovered'` means both images are null and the content is gone. A tap that stores history must not write a tombstone as a snapshot. Full guarantee: [postgres — oversized rows](/docs/database/dialects/postgres).
+
 Runs under BOTH `voltro dev` and `voltro serve` (the prod serve path fans out the same way). Requires the `'store:changes:read'` permission. It is NOT durable at the framework layer — a crash between commit and the fork loses the event; build durability INSIDE the Effect (insert into an outbox and retry against the typed error channel, the way `@voltro/plugin-cdc-out` does). Exactly-once / change-scope semantics are unchanged: read `event.origin` + `event.changeScope` inside the Effect to act once per change fleet-wide (skip `origin: 'injected'` on `'local'` scope; elect one worker on `'fleet'`). Used by `@voltro/plugin-search` to mirror rows into an external index. For in-transaction reactions use a mutation; for best-effort per-table reactions in app code prefer a `*.subscribe.ts` — `onChangeEvent` is the plugin-level equivalent.
 
 ### `onInstall` / `onUninstall` / `onActivate` / `onDeactivate` lifecycle
@@ -523,9 +534,8 @@ export const auditPlugin = (): VoltroPlugin =>
   })
 ```
 
-Tag derivation: `<plugin-alias>.<query.name>` unless `query.name` contains
-a dot (escape hatch). Plugin alias strips `@scope/` + the `plugin-` prefix
-and kebab→camelCase:
+Tag derivation: `<plugin-alias>.<query.name>`. The plugin alias strips
+`@scope/` + the `plugin-` prefix and kebab→camelCase:
 
 | Plugin name | Alias |
 |---|---|
@@ -535,6 +545,71 @@ and kebab→camelCase:
 | `plain-name` | `plainName` |
 | `@voltro/audit` | `audit` (no `plugin-` to strip) |
 
+A `query.name` that already contains a dot is handled by whether it names the
+plugin's OWN namespace:
+
+- `'notifications.inbox'` on a plugin whose canonical name is
+  `@voltro/plugin-notifications` is re-namespaced — under
+  `alias: 'inbox'` it becomes `inbox.inbox`, not `notifications.inbox`.
+  A deeper path keeps its depth: `'audit.admin.events'` under `alias: 'trail'`
+  becomes `trail.admin.events`.
+- `'acme.legacyBridge'` — a namespace that is not the plugin's own — passes
+  through untouched. That is the escape hatch, and it is the only case that
+  still bypasses the alias.
+
+The re-namespacing needs the plugin to declare `baseName` (its canonical name,
+before any app-supplied `alias`); a plugin that omits it keeps the older
+behaviour where any dotted name passes through.
+
+### Naming a plugin: `alias` vs `name`
+
+Two different app-side problems land on a plugin's name, so first-party plugins
+that carry tables or routes accept two separate options:
+
+| Option | Question it answers | Effect |
+|---|---|---|
+| `alias` | "your namespace collides with mine" | replaces the namespace — tags become `<alias>.<route>`, the inspect mount becomes `/_voltro/inspect/plugins/<alias>/…` |
+| `name` | "I want two of these" | appends a `#suffix` discriminator so two installs never register the same tag |
+
+```ts
+notificationsPlugin({ alias: 'alerts' })                    // alerts.inbox
+notificationsPlugin({ name: 'ops' })                        // notifications#ops.inbox
+notificationsPlugin({ alias: 'alerts', name: 'ops' })       // alerts#ops.inbox
+```
+
+`alias` exists to escape a tag collision, which is fatal at codegen. Two costs
+are worth knowing before you reach for it:
+
+- the local and cloud dashboards fetch a plugin's inspect panel at its DEFAULT
+  slug, so an aliased plugin keeps serving its inspect endpoints while its
+  dashboard panel stops resolving;
+- the plugin-migration ledger key is `<plugin-alias>__<migration.id>`, so
+  aliasing a plugin that ships `extendSchema.migrations` makes its already-applied
+  migrations look unapplied. Choose the alias before first boot, not after.
+
+### `tables: false` — keeping your own tables
+
+Plugins whose tables carry no authorization or safety decision accept
+`tables: false`, which stops them contributing DDL through `extendSchema` so an
+app can keep equivalent tables it already has. Everything else — routes,
+inspect, interceptors — is unchanged.
+
+```ts
+notificationsPlugin({ tables: false })   // you declare the six notification tables
+```
+
+It is offered on `@voltro/plugin-rbac`, `@voltro/plugin-audit`,
+`@voltro/plugin-notifications` and `@voltro/plugin-ai-flows`. The plugin still
+writes to those tables BY NAME, so you take over declaring each one with the
+shape the package exports, and a missing or mis-shaped table fails at the first
+write rather than at boot.
+
+It is deliberately NOT offered on plugins whose tables carry a guarantee — the
+SAML assertion replay cache, SCIM provisioning state, billing's usage counters,
+cdc-out's delivery outbox, the governance consent ledger, search's tenant-scoped
+index rows. A `tables: false` there would disable a security or correctness
+decision with no signal to the app that it now owns it.
+
 Boot fails with a clear error on tag collisions (between two plugins, or
 with a user-authored tag).
 
@@ -770,7 +845,7 @@ markers. The plugin sees the api name + the list of discovered user-query
 rpc tags so it can emit per-rpc bindings. Returning `null` contributes
 nothing.
 
-### `templates: PluginTemplate[]` — ship `voltro init` templates
+### `templates: PluginTemplate[]` — ship scaffolding templates
 
 ```ts
 definePlugin({
@@ -819,8 +894,14 @@ export const rateLimitPlugin = (opts: { perMinute: number }) =>
     name: '@vendor/plugin-rate-limit',
     permissions: ['http:intercept'],
     onHttpRequest: async (next, ctx) => {
-      const remoteAddr = ctx.headers['x-forwarded-for'] ?? ctx.remoteAddr ?? 'unknown'
-      if (buckets.consume(remoteAddr, opts.perMinute) === 'exhausted') {
+      // `ctx.remoteAddr` is ALREADY resolved through the app's
+      // `security.trustedProxies` policy — the same value the framework's own
+      // rate limiter, geo-block and audit rows use. Never read
+      // `ctx.headers['x-forwarded-for']`: it is a request header, so any
+      // caller can write it, and a limiter keyed on it is bypassed by one
+      // extra header. `undefined` only when the socket address is unavailable.
+      const clientAddr = ctx.remoteAddr ?? 'unknown'
+      if (buckets.consume(clientAddr, opts.perMinute) === 'exhausted') {
         return {
           status: 429,
           headers: { 'retry-after': '60', 'content-type': 'application/json' },
@@ -832,10 +913,28 @@ export const rateLimitPlugin = (opts: { perMinute: number }) =>
   })
 ```
 
+**`ctx.remoteAddr` is the client address — `x-forwarded-for` is not.**
+The framework resolves `remoteAddr` through the app's
+`security.trustedProxies` policy (`VOLTRO_TRUSTED_PROXIES`) before it hands you
+the context: with no trusted proxy declared the header is ignored entirely and
+the socket address wins, and with one declared only the hops that are actually
+a configured proxy are believed. Reading `ctx.headers['x-forwarded-for']`
+yourself throws that away and keys your limiter on a string the caller typed —
+one extra header and every request looks like a new client. The same rule
+applies to a plugin's raw HTTP routes, where the resolved value arrives as
+`req.remoteAddr`; see [Trusted proxies](/docs/security/overview#the-same-address-reaches-your-plugin-routes).
+
 A per-plugin `plugin.<name>.http-intercept` metric is auto-emitted so
 the dashboard's Plugins panel surfaces HTTP-intercept latency next to
 RPC-intercept latency.
 
+**Runs on both boot paths.** The chain is composed and installed identically by
+`voltro dev` and `voltro serve` — this is a production capability, and for a
+pre-auth shield production is the point. There is exactly ONE exemption, and it
+is deliberate: `GET /internal/liveness` and `GET /internal/readiness` are
+answered before the interceptor, so a rate-limit or geo-block plugin cannot 503
+a Kubernetes probe and take the replica out of rotation.
+
 ### `extendSchema: { tables, migrations }` — contribute schema + migrations
 
 A plugin contributes BOTH declarative table descriptors AND custom SQL
@@ -848,6 +947,14 @@ The ledger key is `<plugin-alias>__<migration.id>` so two plugins can
 each ship `'001-init'` without collision. Failure aborts boot;
 re-runs are no-ops.
 
+**Which commands run them:** `voltro dev`'s boot auto-migrate, `voltro db apply`
+(bare and `--plan`) and `voltro migrate --create-only`. NOT `voltro serve` —
+serve never applies a schema, so a plugin's steps land in the pre-deploy job
+alongside the schema, which is where they belong. Until 0.34.0 only the `voltro
+dev` boot ran them, so a plugin's SQL steps executed on every developer machine
+and on no deployed database; if you ship migrations, verify against a deployed
+database rather than a dev boot.
+
 ```ts
 import { Effect, Schema } from 'effect'
 import { definePlugin } from '@voltro/protocol'
@@ -1387,17 +1494,42 @@ analytics: duckdbAnalytics({
 }),
 ```
 
-The postgres-lite (`postgresAnalytics({ mirrorTables: [...] })`) and ClickHouse (`clickhouseAnalytics({ url, mirrorTables: [...] })`) sinks take the same options. Each mirrored table lands as `_voltro_mirror_<table>` (`voltro_mirror_<table>` on DuckDB / ClickHouse) holding `{ id, data }` — `id` is the source row's primary key, `data` is the full row as JSON. Analytical queries JOIN events against the mirror:
+The postgres-lite (`postgresAnalytics({ mirrorTables: [...] })`) and ClickHouse (`clickhouseAnalytics({ url, mirrorTables: [...] })`) sinks take the same options. Each mirrored table lands as `_voltro_mirror_<table>` (`voltro_mirror_<table>` on DuckDB / ClickHouse) holding `{ id, data, version, is_deleted }` — `id` is the source row's primary key, `data` is the full row as JSON, `version` orders the writes (see below) and `is_deleted` marks a tombstone. Analytical queries JOIN events against the mirror and filter tombstones out:
 
 ```sql
 -- DuckDB: events per user tier
 SELECT json_extract_string(m.data, '$.tier'), COUNT(*)
 FROM voltro_events e
-JOIN voltro_mirror_users m ON m.id = e.subject_id
+JOIN voltro_mirror_users m ON m.id = e.subject_id AND m.is_deleted = false
 GROUP BY 1
 ```
 
-The mirror is **opt-in** (omit `mirrorTables` → events-only) and **idempotent** — inserts/updates upsert by primary key, deletes remove by key, so a re-delivered change (e.g. after a reconnect) is a no-op-equivalent overwrite. Per-change failures are isolated into the log channel: the OLTP write that produced the change already committed, so a warehouse hiccup never surfaces to the request. On DuckDB the mirror table is a plain `(id, data)` table; on ClickHouse it's a `ReplacingMergeTree(version)` so re-inserts collapse to the latest version on merge (deletes write a `is_deleted = 1` tombstone — filter `is_deleted = 0` or use `FINAL`).
+The mirror is **opt-in** (omit `mirrorTables` → events-only) and **idempotent** — inserts/updates upsert by primary key, deletes write a tombstone by key, so a re-delivered change (e.g. after a reconnect) is a no-op-equivalent overwrite.
+
+### Delivery guarantee
+
+**At-least-once for the lifetime of the process, ordered per row.** Read that sentence literally — every clause is a promise the framework keeps, and the sentence stops where the implementation does:
+
+- **Retried, not dropped.** A failing mirror write is retried with exponential backoff (`retryAttempts`, default 5). A write that outlives its retries is queued for **repair**: a timer re-reads the row's *current* state from your database and re-applies it, so the mirror converges on the truth rather than on a stale change that happened to be in flight.
+- **Ordered per row.** Writes for the same primary key are applied one at a time, in commit order, and every write carries a **version** stamped when the change left the store — never a clock read inside the warehouse client. A change that arrives late therefore *loses*: ClickHouse's `ReplacingMergeTree(version)` keeps the highest version, and the DuckDB / postgres mirrors apply the update only when the incoming version is newer. Different rows are still mirrored concurrently.
+- **A delete is a tombstone, not a row removal.** Filter `is_deleted = false` (`is_deleted = 0` / `FINAL` on ClickHouse). A physical delete would leave nothing for a late, stale insert of the same key to lose against — the row would silently come back.
+- **Never surfaces to the request.** The OLTP write that produced the change has already committed; a warehouse outage is isolated into the log channel and the metrics below.
+- **A graceful shutdown is not a crash.** On SIGINT / SIGTERM the mirror stops taking new changes and then **settles** what is already queued and in flight, before the sink itself is disposed. That drain is bounded (3 s of the teardown budget you set with `VOLTRO_SHUTDOWN_GRACE_MS`, default 10 s): a warehouse that has stopped answering cannot hold the process open until the orchestrator's SIGKILL, which would lose strictly more. The two outcomes log differently — `analytics mirror drained` at info, or a `warn` naming what was still pending when the deadline cut it, because that is the moment those counters can still be read.
+- **Not durable across a crash.** The repair queue lives in memory. A change still awaiting repair when the process dies — SIGKILL, an OOM, a host failure — is lost, as is one evicted after `repairQueueLimit`. Both are logged at error level and counted by `voltro_analytics_mirror_dropped_total` — if that counter is non-zero, the affected tables need a re-seed.
+
+Metrics: `voltro_analytics_mirror_forwarded_total`, `..._retries_total`, `..._repair_queued_total`, `..._dropped_total`.
+
+### Tuning
+
+Every number the mirror picks on your behalf has a default and an environment override:
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `VOLTRO_ANALYTICS_MIRROR_RETRY_ATTEMPTS` | `5` | Total attempts per mirror write (`1` = no retry). |
+| `VOLTRO_ANALYTICS_MIRROR_RETRY_BASE_MS` | `100` | First backoff delay; doubles per attempt. |
+| `VOLTRO_ANALYTICS_MIRROR_RETRY_MAX_MS` | `30000` | Ceiling for the doubling backoff. |
+| `VOLTRO_ANALYTICS_MIRROR_REPAIR_INTERVAL_MS` | `60000` | How often the repair loop re-drives exhausted changes (`0` disables it). |
+| `VOLTRO_ANALYTICS_MIRROR_REPAIR_QUEUE_LIMIT` | `10000` | Maximum keys held for repair before the oldest is dropped and counted. |
 
 ## Default — no sink configured
 

package/templates/agent-docs/reference.md

@@ -13,10 +13,13 @@ _The client-side hook surface, grouped by purpose._
 
 The web side of a Voltro app talks to API apps through React hooks. Data hooks are keyed by API name and RPC tag; routing hooks are provided by `@voltro/web`.
 
+App code should reach for the **typed binding** rather than the tag-taking hooks directly: [`createHooks(apiName)`](/docs/reference/hooks-data) takes the api's generated `AppProcedures` map and returns `useSubscription` / `useMutation` / `useAction` whose tag is a literal union and whose input and output types are inferred — so a typo'd tag is a compile error and the result needs no annotation. Bind it once per api in `src/lib/api.ts`. The tag-taking forms documented below are the primitive underneath, for code that only learns the tag at runtime.
+
 ## Data Hooks
 
 | Hook | Purpose |
 |---|---|
+| [`createHooks`](/docs/reference/hooks-data) | Bind the typed hook surface for one api — the recommended app-facing entry point. |
 | [`useSubscription`](/docs/reference/hooks-data) | Subscribe to a reactive query (`*.query.ts`). |
 | [`useMutation`](/docs/reference/hooks-data) | Run an atomic write (`*.mutation.ts`). |
 | [`useAction`](/docs/reference/hooks-data) | Run a unary non-transactional action (`*.action.ts`). |
@@ -112,6 +115,51 @@ _useSubscription, useMutation, useAction, useWorkflow, workflow status hooks, us
 
 Data hooks from `@voltro/client` are keyed by **api name** plus **RPC tag**. The tags come from descriptors discovered in the API app.
 
+## `createHooks(apiName)` — the typed hook binding
+
+`createHooks` turns the api's generated procedure map into hooks whose **RPC tag is a literal union** and whose **input and output types are inferred**. It is the recommended way to call an api from app code.
+
+Codegen emits `AppProcedures` into the api's `rpcGroup.generated.ts` — a type-level map of every tag (yours and every plugin's) to the descriptor behind it. Bind it once, at module scope, next to the rest of your api glue:
+
+```ts
+// src/lib/api.ts — one file, one line, once per app
+import { createHooks } from '@voltro/client'
+import type { AppProcedures } from '@app/api/rpcGroup'
+
+export const { useSubscription, useMutation, useAction } = createHooks<AppProcedures>('app')
+```
+
+`'app'` is the key this web app gave the api in `app.config.ts` → `apis`. It is now spelled exactly once per app instead of once per call site:
+
+```tsx
+import { useSubscription, useMutation } from '../lib/api'
+
+const { data } = useSubscription('notes.list')   // ReadonlyArray<Note>, inferred
+const create = useMutation('notes.create')       // input + output inferred
+```
+
+What the compiler catches that it could not before:
+
+| Mistake | Before | Now |
+|---|---|---|
+| Typo in the tag (`'notes.lst'`) | Runtime dev-console error | Compile error |
+| Wrong hook for the kind (a mutation passed to `useSubscription`) | Runtime `console.error` | Compile error |
+| Missing a required input field | Request sent with `undefined` | Compile error |
+| Wrongly-shaped input | Server-side decode failure | Compile error |
+| Result type annotation disagreeing with the server | Never detected | Impossible — there is no annotation |
+
+The result keeps every narrowing rule of the untyped hook: `loading` still discriminates `data`, `fallback` / `initialSnapshot` still remove the branch, and only a **dynamic** `skip` adds the `idle` state.
+
+Row types include the auto-optimistic marker the client adds, so `row.optimistic` type-checks on a live list without a hand-written row mirror.
+
+**Destructure the result** — do not export the object and call `api.useSubscription(...)`. `react-hooks/rules-of-hooks` only recognises a member call as a hook when the object is PascalCase, so a lowercase namespace silently switches off rules-of-hooks and exhaustive-deps at every call site.
+
+`import type` is erased at build time, so the binding adds nothing to the browser bundle.
+
+**`rpcGroup.generated.ts` is written by codegen**, so a tree that has never booted does not have it yet and `tsc` reports `Cannot find module '@app/api/rpcGroup'`. `voltro dev` generates it on boot; run `voltro codegen` once for a fresh clone or a CI job that only typechecks. The scaffolded api templates do this in their own `typecheck` script, and `pnpm -r` runs the api before anything that depends on it.
+
+The tag-taking hooks below are the primitive underneath. Reach for them when the tag is only known at runtime — plugin web bindings and libraries shipped against an unknown app — not in app code.
+
 ## `useSubscription(apiName, rpcTag, input?, options?)`
 
 Subscribes to a reactive `defineQuery` RPC.
@@ -1101,13 +1149,18 @@ If the work is "do X once and finish", it's a seed. If it's "keep X running unti
 <!-- source: en/reference/templates.md -->
 ## App templates
 
-_The scaffolding catalogue — every api / web / serverless template, what it demonstrates, and when to pick it._
+_The scaffolding catalogue — the api / web / serverless / mobile templates, what each demonstrates, and when to pick it._
 
 Every template is a dogfooded, runnable reference. Scaffold one with
 `voltro create-project --api <id> --web <id>` (or `voltro add-app <name>
---template <id>`), and run `voltro list-templates` for the live list.
+--template <id>`).
+
+**`voltro list-templates` is the authority, not this page.** It prints the
+templates your installed CLI actually ships — there are dozens — while the
+tables below cover the ones worth a paragraph of explanation. If an id appears
+in the command's output and not here, it exists and works.
 
-Templates come in **three kinds**, matching the three things you deploy:
+Templates come in **four kinds**, matching the four things you deploy:
 
 - **`api`** — a long-running backend (`app.config` `type: 'api'`).
 - **`web`** — a frontend (`type: 'web'`); gets a dev-server port.
@@ -1115,6 +1168,10 @@ Templates come in **three kinds**, matching the three things you deploy:
   functions](/docs/deployment/serverless-functions) shipped on their own with
   `voltro serverless`. No long-running server, no port — add it to a project
   with `voltro add-app`.
+- **`mobile`** — an Expo (React Native) app (`mobile-app`), scaffolded with
+  `--mobile`. Expo owns its own dev loop, so it is not part of `voltro dev`; the
+  sibling api still is, and the app consumes it over the network with the same
+  typed hooks the web app uses.
 
 ## API backends (`kind: api`)