@voltro/cli 0.53.0 → 0.54.0

package/templates/agent-docs/introduction.md

@@ -544,6 +544,16 @@ export const searchParams = Schema.Struct({
 
 - `searchParams` (an `effect/Schema` struct — every field optional or with a default) types the page's query string: `useSearchParams(searchParams)` returns the decoded shape, and links built with `withQuery` type-check against it. Details: [Pages → Query strings](/docs/routing/pages#query-strings).
 
+Two more page exports change what the framework produces for a route:
+
+```tsx
+export const ogImage = ({ params, loaderData, locale }) => ({ type: 'div', props: { /* satori JSX */ } })
+export const intercept = { from: '/photos' }
+```
+
+- `ogImage` declares the page's `og:image` as a satori JSX template. `static` pages render the PNG at BUILD time into `dist/assets/og/`; `ssr` pages render it on demand over a signed route. The `og:image` / `twitter:image` / `twitter:card` tags are injected automatically unless your own `meta` already sets them. A declared font is REQUIRED (there is no bundled default), and an `ssr` route exporting it needs `VOLTRO_OG_SECRET` — `voltro start` refuses the boot otherwise. Details: [Loaders and meta → OG images](/docs/routing/loaders-and-meta#og-images-from-a-template-ogimage).
+- `intercept` makes the page an **intercepting route**: `from` names one or more ROUTE PATTERNS (`'/photos'`, `['/photos', '/albums/[id]']`), and a soft navigation arriving from one of them renders this page as an overlay above the still-mounted origin. Every hard load — and a soft navigation from anywhere else — renders it standalone. Details: [Intercepting routes](/docs/routing/intercepting-routes).
+
 ## Discovery in practice
 
 ```text
@@ -605,11 +615,26 @@ If yes, the promise belongs in the name — you cannot see a contract before you
 | `*.store.ts` | exactly one `defineStore`, no server state | `store/one-per-file`, `store/mirrors-server-state` |
 | `*.collection.ts` | declares content collections (`defineCollection`); frontmatter schema violations fail the build naming the file | the build's collection decode + reference validation |
 | `*.consumer.ts` | declares queue consumers (`defineQueueConsumer`, @voltro/plugin-queue); loading registers, the plugin's activation starts them | the queue runner (decode→DLQ, retry→DLQ, commit-per-message) |
+| `*.ws.ts` | default-exports one raw WebSocket gateway (`defineWebSocket`), mounting its own upgrade path beside the rpc socket | boot discovery on BOTH paths (`voltro dev` and `voltro serve`); two gateways on one path refuse the boot |
 
 A `*.component.tsx` promises exactly ONE component. It does not promise to export nothing else: types, and plain module-local values a `const COLUMNS = […]` beside the table that renders them, are fine and always were. What the rule counts is components — a declaration that renders — so an object, an array, a string or a `new` beside your component is not a second one, and neither is `export default Card` next to `export const Card`.
 
 The BOUNDARY rules (`internal/foreign-import`, `fixture/production-import`, `ui/unlinked`) are assertions about your import graph, so it is worth knowing which edges they follow: relative specifiers, your tsconfig `paths` aliases (read from the nearest `tsconfig.json`, so a per-app `@/*` works when you run `voltro doctor` at the repo root), `export … from` re-exports, and dynamic `import()`. A package import is a leaf — the walk stops at the edge of your app.
 
+## Contracts that are not suffixes
+
+The admission test above is about the PROMISE, not about the spelling — and three of the framework's conventions carry one without being a suffix on a filename. They are listed here because a reader looking for "what does the framework read out of my tree" would otherwise stop at the table:
+
+| Convention | Promise | Read by |
+|---|---|---|
+| `searchParams` page export | the page's query string decodes through this `effect/Schema` struct — every field optional or with a default | `useSearchParams(searchParams)`, `withQuery` link typing, and the render-mode scan (a page declaring BOTH `renderMode: 'isr'` and `searchParams` is refused) |
+| `ogImage` page export | this route's `og:image` is a satori JSX template, not a file you ship | the build (`static` → a hashed PNG in `dist/assets/og/`) and `voltro start` (`ssr` → a signed on-demand route, which needs `VOLTRO_OG_SECRET`) |
+| `intercept` page export | `from` names the routes a soft navigation may arrive from for this page to render as an overlay above them | the client router; a hard load renders the page standalone regardless |
+| `grpc.manifest.json` (app root) | field numbers are checked in and append-only — a deleted field goes `reserved`, never re-used | `voltro grpc proto` and the gRPC surface wiring, which derive wire identity from it rather than from declaration order |
+| `content/<name>/**` | the files a `*.collection.ts` declares — markdown with frontmatter, or `.json` for a data collection | `getCollection` / `getEntry`, the build's collection artifacts, and the dev server's watcher |
+
+The page exports are per-ROUTE and the last two are per-APP, which is the only reason they cannot be spellings: there is nothing to rename.
+
 ## `*.component.ui.tsx` — reads, never writes
 
 ```tsx

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

@@ -24,13 +24,14 @@ imports it directly. The React wrappers live behind `@voltro/local-first/react`
 > authoritative server-side merge on the write path), the
 > [`SyncClient`](#the-syncclient-bi-directional-wire) that drives the queue over a
 > transport, [`useCrdtText`](#a-collaborative-text-field-usecrdttext) — the React
-> binding for a collaborative text field — [presence/awareness](#presence--awareness)
+> binding for a collaborative text field — [presence/awareness](#presence-awareness)
 > via `usePresence`, [durable IndexedDB persistence](#durable-persistence), and the
-> [`localFirst` table mixin](#the-localfirst-table-mixin). What remains falls in
-> two tiers: a thin [runtime binding](#whats-shipped-vs-a-runtime-seam) to
-> provisioned infra (a broker at scale) plus the two app-specific tags
-> `useCrdtText` is pointed at — and the sync **engine**, which is now BUILT:
-> the [query mirror](#the-sync-engine-query-mirror--durable-outbox) persists
+> [`localFirst` table mixin](#the-localfirst-table-mixin). What remains is
+> ONE thing — the two app-specific tags `useCrdtText` is pointed at
+> ([runtime seam](#what-s-shipped-vs-a-runtime-seam)); the presence broker
+> binding ships and a browser SQL engine was deliberately rejected. And the
+> sync **engine** is now BUILT:
+> the [query mirror](#the-sync-engine-query-mirror-durable-outbox) persists
 > every subscribed query's rows per subject+tenant partition, `useOutbox`
 > queues offline writes durably, and a reload renders mirrored rows offline
 > and delta-resumes online.
@@ -208,25 +209,25 @@ import { Schema } from 'effect'
 body: Schema.NullOr(Schema.Uint8ArrayFromBase64)
 ```
 
-### Known cost limits of `crdtText()` today
+### What a `crdtText()` keystroke costs
 
-Two amplification effects are worth knowing before you put a `crdtText()` column
-on a hot editing path — both are per-keystroke costs, and both are real today:
+A CRDT column on a hot editing path has two amplification effects to reason
+about, and the framework handles both — neither is left to your query shape:
 
-- **Wire amplification downstream.** A subscription delta carries the row's
-  columns, and for a CRDT column that is the merged **full state** (base64) —
-  every keystroke ships the whole document to every subscriber of the query,
-  not the one-edit update. Keep the streamed query's projection narrow (don't
-  project `body` into a list view), or subscribe to the document row alone.
-- **Undo/row-history capture.** Server-side capture (the undo log — default-on
-  outside production — and `plugin-row-history`'s row history, where enabled)
-  snapshots the row per mutation, so per-keystroke mutations write a
-  full-state blob per keystroke into those tables. Point them away from
-  CRDT-heavy tables, or batch edits before pushing.
+- **Downstream the wire carries the EDIT, not the document.** A changed CRDT
+  cell diffs into an incremental `mergeCells` subscription op rather than a
+  full-blob replace, so a one-character edit ships bytes proportional to the
+  edit regardless of document size — a query that projects `body` into a list
+  view does not stream the whole state per keystroke.
+- **Server-side capture skips CRDT columns.** The undo log (default-on outside
+  production) and `plugin-row-history` strip CRDT columns from the captured
+  row, and an update touching ONLY CRDT columns is not captured at all, so
+  per-keystroke mutations write no full-state blob into those tables.
 
-Both limits are on the framework's roadmap (incremental delivery and
-CRDT-aware capture); until then they are costs to design around, not bugs to
-report.
+What stays a real cost is the stored value itself: the blob in the row grows
+with the document's edit history and soft-compacts past
+`crdt.compactMaxBytes` — see the [operational
+rules](#rich-text-crdtdoc-usecrdtdoc-usecrdteditor) below.
 
 ## Presence & awareness
 
@@ -267,6 +268,30 @@ propagation, and TTL expiry live in the pure `createPresenceRoom` the hook wraps
 > is fresh, plus a `useTyping` indicator, through the app's own rpc. Reach for
 > the plugin for "who is here"; reach for this one for "where is their cursor".
 
+### Binding it to the app's own presence lane — `usePresenceChannel`
+
+`createInMemoryPresenceChannel()` is the local transport; in a running app the
+binding is [`@voltro/plugin-presence`](/docs/plugins/presence)'s
+`usePresenceChannel(roomId, { selfKey })`, which returns a `PresenceChannel`
+backed by the plugin's existing heartbeat roster and rpc. Pass it straight in as
+the `channel` above:
+
+```tsx
+import { usePresence } from '@voltro/local-first/react'
+import { usePresenceChannel } from '@voltro/plugin-presence/web'
+
+function Editor({ documentId, userId }) {
+  const channel = usePresenceChannel(documentId, { selfKey: userId })
+  const { others, setPresence } = usePresence(documentId, { cursor: 0 }, { channel })
+  return <Cursors others={others} />
+}
+```
+
+That is deliberately ONE wire: awareness payloads ride the presence lane the app
+already runs rather than a second socket with its own lifecycle. The channel is
+room-scoped, and publishing into a room it was not created for THROWS — a silent
+cross-room delivery is the failure worth being loud about.
+
 ## The offline sync queue
 
 `useSyncQueue()` is a reactive view over a **pure, tested reducer**: writes made
@@ -316,25 +341,83 @@ const adapter = await createIndexedDbPersistence({ databaseName: 'my-app' })
 const sync = createSyncClient({ transport, adapter }) // state now survives reload
 ```
 
-## Rich text: `crdtDoc()` + `useCrdtEditor`
+## Rich text: `crdtDoc()` + `useCrdtDoc` + `useCrdtEditor`
 
 `crdtDoc()` stores a WHOLE collaborative document (rich text, maps, arrays)
 as a column — same storage and authoritative server merge as `crdtText()`,
-which stays as the plain-text specialisation. The editor binding is Tiptap
-(`@voltro/local-first/editor`, optional peers): `useCrdtEditor({ doc })`
-binds one editor to the document handle; content edits ride the app's
-mutation (folded server-side under a per-row mutex) and remote edits arrive
-as incremental `mergeCells` subscription deltas — a one-character edit ships
-under 1 KB in BOTH directions regardless of document size.
+which stays as the plain-text specialisation. The column definitions are
+identical; what differs is which client binding you reach for.
+
+Two hooks, and they are a pair. **`useCrdtDoc`**
+(`@voltro/local-first/react`) owns the SYNC half — one `SyncClient` and one
+live CRDT document per cell, the same wire `useCrdtText` rides.
+**`useCrdtEditor`** (`@voltro/local-first/editor`, Tiptap, optional peers)
+owns the EDITOR half and takes that document:
+
+```tsx
+import { useCrdtDoc } from '@voltro/local-first/react'
+import { useCrdtEditor } from '@voltro/local-first/editor'
+import { EditorContent } from '@tiptap/react'
+
+const Page = ({ id }: { id: string }) => {
+  const row  = useSubscription<{ body: Uint8Array | null }>('app', 'documents.byId', { id })
+  const save = useMutation<{ id: string; update: Uint8Array }>('app', 'documents.setBody')
+  const shared = useCrdtDoc({
+    cell: { table: 'documents', id, column: 'body' },
+    remote: row.data?.body ?? null,                      // null = NOT LOADED
+    push: (w) => save.mutate({ id: w.id, update: w.update }),
+  })
+  // `doc` is null until the mount effect has run — render the editor in a
+  // CHILD so `useCrdtEditor` is never a conditional hook call.
+  return shared.doc === null ? null : <Surface doc={shared.doc} />
+}
+
+const Surface = ({ doc }: { doc: CrdtDocHandle }) => (
+  <EditorContent editor={useCrdtEditor({ doc })} />
+)
+```
+
+`useCrdtDoc` returns `{ doc, loaded, outstanding, synced, setOnline }`. The
+two names it asks for are the same two `useCrdtText` asks for and the same
+two nothing can derive: the mutation that writes the column, and the
+reactive query that streams the row.
+
+Everything else is the hook's: local edits ride the app's mutation as
+INCREMENTAL updates (folded server-side under a per-row mutex), remote edits
+arrive as `mergeCells` subscription deltas — a one-character edit ships
+under 1 KB in BOTH directions regardless of document size — plus the offline
+queue, bounded retry, per-cell coalescence and durable persistence.
+
+Two disciplines it enforces, because both fail silently when hand-rolled:
+
+- **`remote: null` means NOT LOADED, not empty.** Folding an empty document
+  over a loading row lets the first keystroke push a state that erases what
+  was stored. `loaded` tells a UI which it is.
+- **The echo guard.** A `crdtDoc()` document is mutated by the EDITOR, so
+  local edits surface as `doc.onUpdate` callbacks — and folding a peer's
+  state through `applyState` fires the same callback. The hook pushes only
+  when `local` is `true`. Without that every client re-broadcasts what it
+  just received: one keystroke, one server write per open tab.
+
+A page mounting an editor needs `renderMode = 'client'`. The default is
+`'static'`, which pre-renders at build time, and the editor finds no
+`window` there.
 
 Carets ride a `delivery: 'latest'` EVENT, deliberately not presence
 metadata: the roster's value-compare push would make every caret move a
-"real" change. `attachAwarenessBridge` publishes one member's state per
-envelope (never the aggregated room). Stable positions for inline comments
-come from `encodeAnchor`/`resolveAnchor` on the doc handle.
-
-Operational rules: the stored blob soft-compacts past
-`VOLTRO_CRDT_COMPACT_MAX_BYTES` (default 512 KiB) without breaking the merge
+"real" change. Pass an `awareness` transport plus `user` to
+`useCrdtEditor` to mount them; `attachAwarenessBridge` publishes one
+member's state per envelope (never the aggregated room). Stable positions
+for inline comments come from `encodeAnchor`/`resolveAnchor` on the doc
+handle.
+
+The `frontend-collab` + `api-collab` template pair is this whole loop,
+scaffoldable: `voltro create-project collab --api=api-collab
+--web=frontend-collab`.
+
+Operational rules: the stored blob soft-compacts past `crdt.compactMaxBytes`
+in `app.config.ts` (default 512 KiB, `0` disables; env override
+`VOLTRO_CRDT_COMPACT_MAX_BYTES`) without breaking the merge
 lineage; `rebaseText` is the explicit hard reset (a NEW EPOCH — subscribers
 receive it as a fresh snapshot). CRDT columns are excluded from undo capture
 and row history (document history = named snapshots taken BEFORE
@@ -441,16 +524,31 @@ string form), so two peers agree regardless of which side each calls "local".
 
 ## What's shipped vs. a runtime seam
 
-The framework code for local-first is built and tested end to end against
-in-memory transports. What remains is not un-built framework — it is the thin
-binding to **provisioned infrastructure**, sitting behind interfaces the tested
-code already speaks:
+The framework code for local-first is built and tested end to end. **One** thing
+remains, and it is not un-built framework — it is a pair of names only your app
+knows:
 
 | Runtime seam | What it binds | Why it's a binding, not code |
 | --- | --- | --- |
 | **Two app-specific tags** | Which mutation writes the `crdtText()` column, and which reactive query streams the row, in [`useCrdtText`](#a-collaborative-text-field-usecrdttext). | Voltro generates no per-table CRUD surface, so there is nothing to derive them from. The client lifecycle, optimistic merge, offline queue, retry, persistence and edit encoding all ship. |
-| **Presence channel → a broker at scale** | The `PresenceChannel` to a provisioned Redis/NATS broker. | It's a network hop over an already-shipped broker; the awareness logic ships and is tested over the in-memory channel. |
-| **wa-sqlite / Turso adapter** *(optional)* | A SQL durable adapter for cross-tab queries, behind `PersistenceAdapter`. | IndexedDB is the durable default today; a SQL backing is a sibling factory, nothing above it changes. |
+
+Two entries that used to sit in that table are gone, in opposite directions —
+worth stating, because "we have not built it" and "we decided against it" are
+different answers:
+
+- **The presence broker binding ships.** `usePresenceChannel`
+  (`@voltro/plugin-presence/web`) is a `PresenceChannel` over the framework's
+  own presence lane, so cross-replica fan-out is the broadcast plugin's and
+  there is ONE presence wire rather than two. Nothing to bind by hand; see
+  [Presence & awareness](#presence-awareness).
+- **A wa-sqlite / Turso adapter was rejected, not deferred.** The client's whole
+  query surface is `(tag, input)` — predicates are built and evaluated on the
+  server — so a browser SQL engine would evaluate a language the client never
+  sees. What offline needs is the last materialised answer per query, which is
+  exactly what the [query mirror](#the-sync-engine-query-mirror-durable-outbox)
+  stores. A SQLite *backing* beneath `KvStore` remains possible without any
+  consumer changing (React Native's adapter is exactly that) — that is a
+  storage choice, not a missing engine.
 
 
 

package/templates/agent-docs/observability.md

@@ -71,9 +71,11 @@ Even with no exporter, `voltro dev` installs a **buffer-only** tracer — that's
 
 ## Metrics export
 
-Separate from tracing, the framework records **metrics** into Effect's global `MetricRegistry` — one source of truth (`voltro_rpc_*`, `voltro_http_*`, `voltro_plugin_hook_*`, `voltro_subscription_*` + `voltro_subscriptions_active`, `voltro_db_*`, plus `effect_fiber_*` and any custom metric). Three ways to get them out:
+Separate from tracing, the framework records **metrics** into Effect's global `MetricRegistry` — one source of truth (`voltro_rpc_*`, `voltro_http_*`, `voltro_plugin_hook_*`, `voltro_subscription_*` + `voltro_subscriptions_active`, `voltro_db_*`, `voltro_ppr_*`, `voltro_queue_*`, plus `effect_fiber_*` and any custom metric). Three ways to get them out:
 
-The **web server** additionally counts [partial prerendering](/docs/routing/render-modes#partial-prerendering-ppr--cached-shell--per-request-holes): shell serves, hole passes/settles/errors, and last/max hole latency. Shell hit-rate is the isr cache's own `x-voltro-cache` HIT/STALE/MISS accounting — a ppr shell is a normal isr entry.
+The **web server** additionally exports [partial prerendering](/docs/routing/render-modes#partial-prerendering-ppr-cached-shell-per-request-holes), labelled by `page` (the declared route pattern, never a resolved URL): `voltro_ppr_shell_serves_total{page}`, `voltro_ppr_hole_passes_total{page}`, `voltro_ppr_hole_settles_total{page}`, `voltro_ppr_hole_errors_total{page}` and the `voltro_ppr_hole_pass_seconds{page}` histogram. `voltro dev` and `voltro start` emit the same set. Shell hit-rate is the isr cache's own `x-voltro-cache` HIT/STALE/MISS accounting — a ppr shell is a normal isr entry.
+
+`voltro_ppr_hole_errors_total` is the one to alert on: a failed hole pass is invisible from outside. The shell is already on the wire with a `200`, so the page renders and every `<Await>` boundary simply stays on its fallback — a page that looks like it is loading and never will. A single hole *rejecting* is not counted there; that settles the deferred-error envelope and renders the boundary's `errorFallback`.
 
 ```bash
 # OTLP metrics — the SAME OTEL endpoint that enables trace export also enables

package/templates/agent-docs/plugins/atlassian.md

@@ -18,7 +18,7 @@ _JiraService + ConfluenceService over the Atlassian REST / Greenhopper / Agile A
 Two auth modes, both first-class (choose per deployment):
 
 - **PAT / basic** — a Personal Access Token per subject. The default for Jira/Confluence **Data Center / Server**. Wire it via `credentialsResolver` (below).
-- **OAuth 2.0 (3LO)** — the authorization-code flow for Atlassian **Cloud**, where the app acts on behalf of a consenting user. Use the toolkit ([OAuth 2.0 (3LO)](#oauth-20-3lo)) to obtain an access token, then feed it into the same `credentialsResolver`.
+- **OAuth 2.0 (3LO)** — the authorization-code flow for Atlassian **Cloud**, where the app acts on behalf of a consenting user. Use the toolkit ([OAuth 2.0 (3LO)](#oauth-2-0-3lo)) to obtain an access token, then feed it into the same `credentialsResolver`.
 
 It also supports [inbound Jira/Confluence webhooks](#inbound-webhooks) (signature-verified) and writing comments to issues and pages.
 
@@ -55,7 +55,7 @@ export default {
 > there it travels with the identity into everything that persists a Subject. A
 > reporter found a working Jira PAT in plaintext in 12 of 23 rows of their
 > `_voltro_audit_log` exactly that way. The `store` handle above exists so it
-> never has to enter the Subject; [`connectionCredentials`](#connections) is
+> never has to enter the Subject; [`connectionCredentials`](/docs/data/connections) is
 > better still, because then you do not hold the token at all.
 
 The resolver returns `AtlassianCredentials`:

package/templates/agent-docs/plugins/audit.md

@@ -73,7 +73,7 @@ auditPlugin({
 // custom function: (event: AuditEvent) => void | Promise<void> | Effect.Effect<void>
 ```
 
-`'datastore'` is the production sink: it survives restarts, is shared across replicas, and is queryable via `ctx.store.select('_voltro_audit_log')`. Each row carries the flattened `tag` / `at` / `subjectId` / `tenantId` / `traceId` / `status` / `durationMs` (indexed by `tag` + `traceId`) plus the full `subject` / `input` / `outcome` as portable `json()` columns, plus the `chainId` / `seq` / `prevHash` / `hash` tamper-evidence columns (see [the hash chain](#tamper-evidence--the-hash-chain)).
+`'datastore'` is the production sink: it survives restarts, is shared across replicas, and is queryable via `ctx.store.select('_voltro_audit_log')`. Each row carries the flattened `tag` / `at` / `subjectId` / `tenantId` / `traceId` / `status` / `durationMs` (indexed by `tag` + `traceId`) plus the full `subject` / `input` / `outcome` as portable `json()` columns, plus the `chainId` / `seq` / `prevHash` / `hash` tamper-evidence columns (see [the hash chain](#tamper-evidence-the-hash-chain)).
 
 The custom function is the escape hatch for persisting events anywhere the built-in table's schema doesn't fit — e.g. an `Effect.Effect<void>` sink that writes rows into your own audit table on top of `@effect/sql`. All return shapes are normalised by the interceptor. A sink that throws / rejects / dies is caught and swallowed, so a broken sink can never mask the mutation's real outcome.
 
@@ -406,7 +406,7 @@ subjects *do* carry a `teamId`, which made subject-only worse than nothing for
 them: it would have populated for key-authenticated calls and been null for every
 human one, so a filtered view would have looked like it worked.
 
-The input here is **raw** — not what [`redactInput`](#redactinput--what-of-the-payload-is-kept)
+The input here is **raw** — not what [`redactInput`](#redactinput-what-of-the-payload-is-kept)
 will store. That is required (a scope derived from a redacted payload is not
 derivable at all) and it is a hazard worth naming: whatever you return lands in
 `scope`, which is *not* redacted. Return the dimension, never the payload.

package/templates/agent-docs/plugins/billing.md

@@ -69,7 +69,7 @@ export default (input: { tenantId: string }, _ctx) =>
   })
 ```
 
-The subscription row lives in your DB; the provider is the source of truth and webhooks keep the row in sync. `plan()` returns the plan whose **limits apply right now**: `'free'` with no subscription, the paid plan while active or trialing, and — because a bounced card should not downgrade a customer on the same second — the paid plan for the whole [grace period](#failed-payments--stripe-retries-dunning-composes-on-the-outcome) after a failed payment, falling back only once the lockout is real.
+The subscription row lives in your DB; the provider is the source of truth and webhooks keep the row in sync. `plan()` returns the plan whose **limits apply right now**: `'free'` with no subscription, the paid plan while active or trialing, and — because a bounced card should not downgrade a customer on the same second — the paid plan for the whole [grace period](#failed-payments-stripe-retries-dunning-composes-on-the-outcome) after a failed payment, falling back only once the lockout is real.
 
 ## Entitlement checks
 

package/templates/agent-docs/plugins/cdc-out.md

@@ -1,6 +1,6 @@
 # CDC-out (reverse-ETL)
 
-> Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.
+> Declaratively mirror table changes outward to external sinks (webhook, Kafka, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.
 
 
 
@@ -9,7 +9,7 @@
 <!-- source: en/plugins/cdc-out.md -->
 ## CDC-out (reverse-ETL)
 
-_Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered._
+_Declaratively mirror table changes outward to external sinks (webhook, Kafka, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered._
 
 # CDC-out — declarative reverse-ETL
 
@@ -66,7 +66,12 @@ plugin name (`@voltro/plugin-cdc-out#analytics`) and the inspect mount
 - **`webhookSink(url, { headers? })`** — POSTs each batch as
   `{ records: [...] }` JSON, honoring the engine's per-attempt abort signal.
   Its host is declared as a `network:outbound:<host>` permission automatically.
-- **Warehouse / Kafka** — implement the `CdcSink` interface
+- **`kafkaSink({ topic })`** — from
+  [`@voltro/plugin-queue`](/docs/plugins/queue#cdc-out-to-kafka), producing
+  through the same provider your consumers use: message key = the row id (one
+  row's changes stay ordered in one partition), value = the change record, and
+  the `x-voltro-delivery-key` header carries the dedupe handle below.
+- **Warehouse (Snowflake / BigQuery / …)** — implement the `CdcSink` interface
   (`{ name, deliver(batch, ctx), outboundHost? }`). `deliver` may return a
   **Promise or an Effect** — both compose without wrapping. The engine is
   connector-agnostic; the sink is the only thing that changes.

package/templates/agent-docs/plugins/comments.md

@@ -90,6 +90,28 @@ import { useComments } from '@voltro/plugin-comments/web'
 const { threads, unreadCount, create, resolve, react, markRead } = useComments(`orders:${id}`)
 ```
 
+`useComments(anchor, apiName?)` subscribes to `comments.list`, whose `source:`
+is the plugin's own reactivity channel — so a second client sees a new comment
+without a reload, and every action on the handle (`create`, `edit`, `resolve`,
+`remove`, `react`, `markRead`) re-runs the list for all subscribers.
+`unreadCount` is the sum of the threads' own counters, i.e. the badge number.
+
+Two focused hooks sit beside it, both from the same entry point:
+
+```tsx
+import { useThread, useMentionSearch } from '@voltro/plugin-comments/web'
+
+const thread = useThread(`orders:${id}`, threadId)   // ThreadView | undefined
+const people = useMentionSearch(term)                // [{ subjectId, label }]
+```
+
+`useThread(anchor, threadId, apiName?)` is a projection over the SAME live
+list — it opens no second subscription, so a detail pane beside the thread
+list costs nothing. `useMentionSearch(query, apiName?)` drives the
+`@`-autocomplete over `comments.mentionSearch`; the directory it searches is
+the app's own `resolveMentions` seam, already tenant-filtered by the rule
+below.
+
 ## Mentions are tenant-safe by construction
 
 The `resolveMentions` seam RECEIVES the calling subject — the signature makes

package/templates/agent-docs/plugins/presence.md

@@ -53,13 +53,42 @@ A member is `{ key, meta }`. **It pushes only when the roster actually moves**
 
 ```ts
 presencePlugin({
-  resolveMember: async ({ subject }) => {
-    const user = await users.byId((subject as { id: string }).id)
-    return user ? { userName: user.name, avatarUrl: user.avatarUrl } : undefined
+  // `store` is the app's DataStore, handed over at boot — app.config.ts is
+  // evaluated long before one exists, so the hook receives it rather than
+  // making you smuggle one in through a module cell.
+  resolveMember: async ({ subject, store }) => {
+    const rows = await store.query({
+      table: 'users', predicate: { column: 'id', op: 'eq', value: (subject as { id: string }).id },
+      order: [], projection: undefined, skip: undefined, take: 1,
+    } as never) as ReadonlyArray<{ name?: string; avatarUrl?: string }>
+    const user = rows[0]
+    return { userName: user?.name ?? null, avatarUrl: user?.avatarUrl ?? null }
   },
+  // The keys the SERVER owns — stripped from the caller's meta before the merge.
+  identityFields: ['userName', 'avatarUrl'],
 })
 ```
 
+**Read the merge precisely — the obvious resolver has a hole in it.** Resolved
+fields are merged OVER the caller's `meta`, so a key the resolver **does not
+return** is not overwritten: it keeps whatever the client sent. A resolver that
+returns only what it found (`{ userName }` for a user with no avatar) therefore
+leaves a caller-supplied `avatarUrl` — or a `userName` the resolver has never
+heard of — standing in the roster every other member reads. That is the exact
+substitution the hook exists to prevent, and a deployment hit it while adopting
+the hook.
+
+Two ways to close it, and declaring is the better one:
+
+- **`identityFields: ['userName', 'avatarUrl']`** — the keys the server owns.
+  They are removed from the caller's `meta` BEFORE the merge, so a key the
+  resolver happens not to return on this call is *absent* rather than
+  caller-controlled. Ignored without a `resolveMember`: with no server identity
+  to protect, stripping a client field would only delete data the app put there
+  deliberately.
+- **Return every identity key on every call**, `null` for the ones you have no
+  value for.
+
 The roster key is already the subject id, so a by-id lookup is the whole job — keep it cheap or cached. Alternatively resolve identity on the READ side from the roster keys (a `users.getByIds` query over `member.key`) and keep `meta` for ephemeral state only.
 
 > **There is a second `usePresence`, and it is a different hook.**

package/templates/agent-docs/plugins/prometheus.md

@@ -23,6 +23,8 @@ The framework records metrics into Effect's global `MetricRegistry`. One snapsho
 - **Subscriptions** — `voltro_subscriptions_active{tag}` (gauge of currently-open subscriptions), `voltro_subscription_deliveries_total{tag,kind}` + `voltro_subscription_delivery_seconds{tag,kind}` (per-delivery produce→push latency; `kind` = `snapshot` | `delta`). Backpressure & resume: `voltro_subscription_buffered_bytes{tag}` (gauge of pending bytes per blocked subscription), `voltro_subscription_coalesced_total{tag}` (updates collapsed onto the newest state while a consumer was blocked), `voltro_subscription_overrun_total{tag}` (streams closed with `SubscriptionOverrun`), `voltro_subscription_oversized_total{tag}` (events over `reactive.socket.oversizedEventBytes` — telemetry, not a cap).
 - **Schedules (crons)** — `voltro_schedule_runs_total{schedule,status}` (firings by name + outcome — `status` = `succeeded` | `failed`), `voltro_schedule_duration_seconds{schedule}` (histogram), and `voltro_schedule_last_success_timestamp_seconds{schedule}` (a **gauge holding the UNIX time of the last SUCCESS**). Emitted by the framework scheduler, so every cron gets them with no per-handler wiring. A cron fires unattended — the failure mode is silent — so this is the series to alert on: `time() - voltro_schedule_last_success_timestamp_seconds{schedule="…"} > <interval × N>` fires when a job stops succeeding (a failure counter alone can't catch a job that stopped firing at all, but the last-success gauge going stale does). A failure moves the counter but deliberately NOT the gauge.
 - **Workflows (durable execution)** — `voltro_workflow_runs_total{workflow,status}` (terminal outcomes — `status` = `succeeded` | `failed`), `voltro_workflow_duration_seconds{workflow}` (histogram), and `voltro_workflow_last_success_timestamp_seconds{workflow}` (last-success gauge). Emitted by the workflow run-recording seam. Because the framework applies no retry of its own, a `failed` run is **terminal** — it is the dead-letter state — so `voltro_workflow_runs_total{status="failed"}` **is** the dead-letter rate, and the last-success gauge going stale is the "this workflow stopped completing" alert (same shape as the schedule alert). A failure moves the counter but not the gauge.
+- **Partial prerendering (web)** — `voltro_ppr_shell_serves_total{page}`, `voltro_ppr_hole_passes_total{page}`, `voltro_ppr_hole_settles_total{page}`, `voltro_ppr_hole_errors_total{page}` and `voltro_ppr_hole_pass_seconds{page}` (histogram). `page` is the DECLARED route pattern (`/blog/[slug]`), never a resolved URL — a label that grows with visitors is how a scrape target falls over. `voltro dev` and `voltro start` emit the same set. `voltro_ppr_hole_errors_total` is the alert: the shell already went out with a `200`, so a failed hole pass leaves every `<Await>` boundary on its fallback and nothing else says so.
+- **[Queues](/docs/plugins/queue)** — `voltro_queue_consumed_total{topic,outcome}` (`outcome` = `ok` | `dead-lettered`; the two together are every message the runner finished with, so the dead-letter RATE is a division with no join), `voltro_queue_retries_total{topic}`, `voltro_queue_produced_total{topic}`, and `voltro_queue_lag_messages{topic,partition}` — a gauge of the backlog behind the message just picked up, read out of the fetch response rather than an admin round trip. A message abandoned by a rebalance is deliberately in no outcome: its new owner redelivers and counts it there.
 - **`@voltro/cache`** counters, Effect's own `effect_fiber_*` runtime metrics, and **any custom metric** you or another plugin defines.
 
 Two consumers read the SAME snapshot, so they never disagree:

package/templates/agent-docs/plugins/queue.md

@@ -123,7 +123,50 @@ cdcOutPlugin({ sinks: [{ table: 'orders', sink: kafkaSink({ topic: 'orders.cdc'
 
 ## Observability
 
-Per-topic counters (consumed / retried / dead-lettered / produced + the last
-error) on `GET /_voltro/inspect/plugins/queue/consumers` and in the
-dashboards' Queue panel. Message headers carry `traceparent` through to
-`ctx.traceparent` for cross-system trace continuity.
+**Metrics.** Every counter is exported to the [metrics
+registry](/docs/observability/overview#metrics-export), so it is scrapeable via
+[`@voltro/plugin-prometheus`](/docs/plugins/prometheus) and readable at
+`GET /_voltro/inspect/metrics`:
+
+| Series | Type | What it answers |
+| --- | --- | --- |
+| `voltro_queue_consumed_total{topic,outcome}` | counter | Throughput, and — with `outcome` = `ok` \| `dead-lettered` — the dead-letter rate as a plain division. |
+| `voltro_queue_retries_total{topic}` | counter | In-process handler retries. A retry BLOCKS its partition, so a rising rate is head-of-line latency, not just noise. |
+| `voltro_queue_produced_total{topic}` | counter | Messages produced through the outbox bridge. |
+| `voltro_queue_lag_messages{topic,partition}` | gauge | Backlog behind the message just picked up — "are the consumers keeping up", which no counter can answer. |
+
+`outcome` has two values on purpose: `ok` + `dead-lettered` is *every* message
+the runner finished with. A message abandoned by a **rebalance** is in neither —
+it was not consumed here, its new owner redelivers it and counts it there, and
+counting it twice would make the dead-letter ratio wrong in the direction of
+looking healthy.
+
+Lag is a **sample at pickup** and costs nothing to collect (`highWatermark`
+rides along in the fetch response — no admin round trip per message). Read it
+together with the consume rate: nothing arrives to move the gauge on an idle or
+revoked partition, so it holds its last value, and a frozen high lag and a
+frozen low lag look identical on their own.
+
+The per-topic counters plus the last error also stay on
+`GET /_voltro/inspect/plugins/queue/consumers` and in the dashboards' Queue
+panel — that view is this replica, right now, and carries an error *string*,
+which is not a time series. Both are moved by one recorder each, so they cannot
+drift.
+
+**Tracing.** Each consumed message is processed inside a `queue.consume` span
+that ADOPTS the producer's `traceparent` header as its parent, so a Kafka hop no
+longer ends the trace. The span covers the whole message — decode, every retry,
+and the dead-letter publish — and carries `messaging.system`,
+`messaging.destination.name`, `messaging.consumer.group.name`,
+`messaging.destination.partition.id`, `messaging.message.offset` and
+`voltro.queue.outcome` (`ok` | `dead-lettered` | `stale`). A missing or
+malformed `traceparent` starts a fresh root span rather than failing the
+message. `ctx.traceparent` is still handed to your handler for hops the
+framework does not make for you.
+
+Consumer spans are emitted from detached work — a broker callback, outside the
+server's Effect scope — and reach the server's tracer because the server
+publishes its tracer instance for exactly that case. There is still only ONE
+tracer: a second provider would mean a second exporter nothing flushes at
+shutdown. The same applies to `cdcOut.deliver` and
+`plugin.<name>.schedule-fire`, which run detached for the same reason.

package/templates/agent-docs/plugins.md

@@ -95,7 +95,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-logship` | ✓ | Ship structured logs to Better Stack / Axiom / Loki / any HTTP sink — rides the log-sink hook, batched + redacted + fail-soft, trace-correlated. [→ details](/docs/plugins/logship) |
 | `@voltro/plugin-moderation` | ✓ | Content moderation — keyword denylist or AI provider (fails open), block (typed `ContentRejected`) / flag via rpc interceptor + in-handler `moderate()` redact helper. [→ details](/docs/plugins/moderation) |
 | `@voltro/plugin-search` | ✓ | External search index sync — rides the ChangeEvent tap to mirror tables into Typesense / Meilisearch / Algolia (memory default), tenant-scoped `search.query` action (facets · highlighting · fuzziness · range/negation filters · engine-param passthrough) + `useSearch` hook + `backfillIndex` + durable cross-replica sync stats. [→ details](/docs/plugins/search) |
-| `@voltro/plugin-cdc-out` | ◐ | Declarative reverse-ETL — mirror table changes outward to external sinks (webhook, plus a `CdcSink` interface for custom sinks) through a durable outbox; ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. Engine + memory/webhook sinks shipped; anything else implements the `CdcSink` interface. |
+| `@voltro/plugin-cdc-out` | ◐ | Declarative reverse-ETL — mirror table changes outward to external sinks (webhook, Kafka via [`kafkaSink`](/docs/plugins/queue#cdc-out-to-kafka), plus a `CdcSink` interface for custom sinks) through a durable outbox; ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. Engine + memory/webhook/Kafka sinks shipped; a warehouse connector implements the `CdcSink` interface. |
 | `@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-row-history` | ✓ | Full row history + time-travel — value snapshot of every insert/update/delete (every table by default; narrow with include/exclude) into `_voltro_row_history` (rides the ChangeEvent tap); `rowHistory` / `rowAsOf` queries + `restoreAsOf` / `diffVersions`; TTL + per-row cap retention. [→ details](/docs/plugins/row-history) |
@@ -1339,11 +1339,11 @@ The contract is deliberately narrow. **No raw SQL, no funnels, no cohorts, no cu
 
 | Plugin | Type | Best for | Ceiling |
 |---|---|---|---|
-| [`@voltro/plugin-analytics-postgres`](#voltroplugin-analytics-postgres) | Lite | Day-1 zero-setup, dev + early production | ~10M events/day |
-| [`@voltro/plugin-duckdb`](#voltroplugin-duckdb) | Embedded OLAP | Real column-store performance, no external service | Vertical scale: ~hundreds of GB in one process |
-| [`@voltro/plugin-clickhouse`](#voltroplugin-clickhouse) | External OLAP | Production-scale analytics, self-hosted or ClickHouse Cloud | Billions of events comfortably |
-| [`@voltro/plugin-tinybird`](#voltroplugin-tinybird) | Hosted ClickHouse | Pay-as-you-go without operating ClickHouse | Tinybird's own limits |
-| [`@voltro/plugin-posthog`](#voltroplugin-posthog) | Product analytics | Sessions, feature flags, funnels in PostHog's UI | `track()` only — compose with another sink for reads |
+| [`@voltro/plugin-analytics-postgres`](#voltro-plugin-analytics-postgres) | Lite | Day-1 zero-setup, dev + early production | ~10M events/day |
+| [`@voltro/plugin-duckdb`](#voltro-plugin-duckdb) | Embedded OLAP | Real column-store performance, no external service | Vertical scale: ~hundreds of GB in one process |
+| [`@voltro/plugin-clickhouse`](#voltro-plugin-clickhouse) | External OLAP | Production-scale analytics, self-hosted or ClickHouse Cloud | Billions of events comfortably |
+| [`@voltro/plugin-tinybird`](#voltro-plugin-tinybird) | Hosted ClickHouse | Pay-as-you-go without operating ClickHouse | Tinybird's own limits |
+| [`@voltro/plugin-posthog`](#voltro-plugin-posthog) | Product analytics | Sessions, feature flags, funnels in PostHog's UI | `track()` only — compose with another sink for reads |
 
 ## Picking one
 

package/templates/agent-docs/reference.md

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