@voltro/cli 0.52.0 → 0.54.0

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

@@ -24,15 +24,17 @@ 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** (a locally queryable
-> database, automatic mirroring of `localFirst()` tables, partial replication),
-> which is planned and not yet built. Today `localFirst()` is a declaration the
-> tooling discovers, not an auto-synced local database.
+> [`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.
 
 ## CRDT text: `crdtText` + `mergeCrdtStates`
 
@@ -207,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
 
@@ -266,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
@@ -315,6 +341,161 @@ const adapter = await createIndexedDbPersistence({ databaseName: 'my-app' })
 const sync = createSyncClient({ transport, adapter }) // state now survives reload
 ```
 
+## 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 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. 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
+compaction); `.serverOnly()` on a CRDT column is a declaration error and
+`.encrypted()` makes it online-only.
+
+## The sync engine: query mirror + durable outbox
+
+The engine's two halves ride the primitives you already use — there is no
+second data API:
+
+- **Reads.** The subscription cache accepts a `mirror`; every base movement of
+  every subscribed query persists (rows + revision) into a **subject+tenant
+  partitioned** store over IndexedDB, and a cold start seeds from it — the UI
+  renders the last materialised rows offline through the SAME
+  `useSubscription` call, and the next connect presents the mirrored revision
+  as `voltro-resume-from`, so a reload inside the resume window continues with
+  deltas instead of a snapshot.
+- **Writes.** `useOutbox` with `persistence: outboxPersistence(adapter)` is
+  the durable offline queue: writes survive a reload, replay in order on
+  reconnect, stop at the first conflict, and a conflict resolves through
+  `resolveConflict(id, resolveWithPolicy(policy, local, remote, { crdtColumns }))`
+  — `crdtText()` columns merge, scalars follow the declared `conflictPolicy()`.
+  One drain per device even with many tabs (`withDrainLock`, a per-partition
+  Web Lock).
+
+```ts
+import {
+  createDurableKv, createQueryMirror, createSubscriptionMirrorBinding,
+} from '@voltro/local-first'
+import { localFirstTables } from './.framework/localFirst.generated'
+
+const { kv, durability } = await createDurableKv()          // 'memory' = visible degradation
+const mirror = createQueryMirror(kv, { subjectId, tenantId }) // ONE partition per subject
+const binding = createSubscriptionMirrorBinding(mirror, {
+  tags: { 'docs.list': 'docs' },                            // the app's sync set
+  metadata: localFirstTables,                               // codegen: encrypted columns stripped
+  schemaFingerprint: BUILD_ID,                              // local-DB migration gate
+})
+```
+
+The deliberate design decision, recorded here because the obvious alternative
+keeps being suggested: the engine is **not** a browser SQL database. The
+client's whole query surface is `(tag, input)` — predicates are built and
+evaluated on the server — so a wa-sqlite instance would evaluate a language
+the client never sees. What offline needs is the last materialised answer per
+query the user visited, kept current by deltas; that is what the mirror
+stores. (The `KvStore` seam still admits a SQLite backing without touching a
+consumer.)
+
+Soundness rules, all enforced structurally and tested:
+
+- **Partition by key.** Every stored key carries subject AND tenant; a
+  logout/login as somebody else can never read the predecessor's rows, and
+  `purge()` empties exactly one partition on revocation. Build ONE binding per
+  resolved subject and rebuild it on an auth change — the same blank-on-auth
+  doctrine the subscription cache itself follows.
+- **`.encrypted()` never lands.** The server decrypts on read, so a naive
+  mirror would persist plaintext on the device; the codegen-emitted
+  `localFirst.generated.ts` names those columns and the binding strips them
+  before every save. `.serverOnly()` columns never reach the wire at all.
+- **The snapshot is the visible state.** A save replaces the mirrored row
+  set, so a row the server stopped sending (revoked share, RLS change, soft
+  delete) is evicted by construction.
+- **Schema migration is a visible cold start.** Entries persist under the
+  build's `schemaFingerprint`; a new build's load misses them and the query
+  falls back to loading → fresh snapshot — never a mixed-shape render. The
+  offline queue deliberately does NOT gate on it: a queued old-shape write
+  replays against the new server, whose input schema is the authority, and a
+  rejection surfaces as a visible conflict instead of silently dropped work.
+- **Shapes are your queries.** There is no separate replication-shape
+  language: what is mirrored is exactly what the app subscribes to, so tenant
+  scoping, guards and `setRowFilter` apply server-side, fail-closed, exactly
+  as online — including parent-relative predicates ("tasks where projectId is
+  one of my projects"), which are just queries. Mirroring is per QUERY, so a
+  subgraph is N queries, not one nested shape. A storage budget is enforced
+  with `enforceBudget(maxBytes)` — oldest-saved entries evict first.
+
 ## Conflict policy for non-CRDT fields
 
 CRDT fields resolve themselves — the merge **is** the resolver. A plain scalar
@@ -343,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,7 +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 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/auth.md

@@ -333,7 +333,7 @@ authRoutesPlugin({
 })
 ```
 
-The canonical guard ships in `@voltro/plugin-deactivation`: `deactivationGuard()` refuses login when the user's `deactivatedAt` is set — making the `deactivation()` mixin's "a deactivated user can't log in" promise self-enforcing without a hand-rolled resolver check. See [deactivation](/docs/plugins/deactivation#enforcing-a-deactivated-user-cant-log-in). With no guards configured, every authenticated user proceeds exactly as before.
+The canonical guard ships in `@voltro/plugin-deactivation`: `deactivationGuard()` refuses login when the user's `deactivatedAt` is set — making the `deactivation()` mixin's "a deactivated user can't log in" promise self-enforcing without a hand-rolled resolver check. See [deactivation](/docs/plugins/deactivation). With no guards configured, every authenticated user proceeds exactly as before.
 
 ## Rehash-on-verify
 

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

@@ -0,0 +1,164 @@
+# Comments
+
+> Comment threads on any app entity — replies, resolve/reopen, @-mentions with notifications, reactions, unread counters — live over the reactive engine, with an ejectable thread UI.
+
+
+
+---
+
+<!-- source: en/plugins/comments.md -->
+## Comments
+
+_Comment threads on any app entity — replies, resolve/reopen, @-mentions with notifications, reactions, unread counters — live over the reactive engine, with an ejectable thread UI._
+
+`@voltro/plugin-comments` hangs discussion threads on anything your app can
+name — an order, a document, a row, a section anchor — and keeps every open
+view LIVE: a second client sees a new comment without a reload, because
+`comments.list` declares the plugin's reactivity channel as its `source:` and
+every write publishes it. No second push mechanism, no vendor websocket.
+
+```ts
+// app.config.ts
+import { commentsPlugin } from '@voltro/plugin-comments'
+
+export default {
+  // …
+  plugins: [
+    commentsPlugin({
+      access: {
+        viaEntity: async ({ anchor, subject, store }) => {
+          // Resolve the anchor to YOUR entity and answer with YOUR rules —
+          // the same guard your queries use. A row the guard cannot read
+          // (including a soft-deleted one) is a refusal.
+          const [table, rowId] = anchor.split(':')
+          if (table !== 'orders' || store === undefined) return false
+          const rows = await store.query({
+            table: 'orders', predicate: eq('id', rowId!),
+            order: [], take: 1, skip: undefined, projection: undefined,
+          })
+          return rows.length > 0
+        },
+      },
+      resolveMentions: async ({ query, subject }) =>
+        searchTeamMembers(query, subject.tenantId),
+    }),
+  ],
+}
+```
+
+## Access follows the anchor — fail-closed
+
+Only your app knows who may see the entity a thread hangs on. The plugin
+therefore takes a declared rule and REFUSES every read and write when none is
+declared — a comments surface with no access rule serves nobody rather than
+everybody:
+
+- **`access.viaEntity`** — guard delegation (above). Receives the anchor, the
+  calling subject and the bound store.
+- **`access.scope`** — one scope every comment reader/writer must hold, for
+  team-internal comment surfaces.
+
+A **soft-deleted anchor** is the same door: your guard cannot approve what it
+cannot read, so the whole thread answers `CommentAccessRefused` — an inbox
+notification that still points at it finds "no longer available", not a leak.
+
+## The live thread UI
+
+```tsx
+import { CommentsThread } from '@voltro/ui'
+
+const OrderPage = ({ order }) => <CommentsThread anchor={`orders:${order.id}`} />
+```
+
+Try it — this is the real plugin against this docs site's demo backend. Open
+this page in a **second tab**: a comment typed in one appears in the other
+without a reload (tabs share your per-browser visitor identity; other
+visitors' threads are isolated):
+
+```tsx
+import { CommentsThread } from '@voltro/ui'
+
+<CommentsThread anchor="demo:comments" />
+```
+
+`<CommentsThread>` is deliberately unstyled (semantic markup + `data-*`
+hooks) and ejectable; underneath it is `useComments(anchor)`:
+
+```tsx
+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
+forgetting impossible — and the plugin re-filters whatever your resolver
+returns to the caller's tenant (opt out with `crossTenant: true` for
+single-tenant apps). Mentions are ALSO re-validated at create time against the
+same resolver, so a hand-crafted mention on a foreign tenant is dropped, not
+delivered: the `@`-autocomplete cannot leak existence or names across the
+boundary, and no notification ever crosses it.
+
+A validated mention delivers through
+[`plugin-notifications`](/docs/plugins/notifications) when it is configured —
+recipient preferences, quiet hours and digests apply (ten mentions inside a
+digest window roll into ONE delivery). Without the notifications plugin the
+mention still renders in the thread; the push half is simply absent (a log
+note, never an error).
+
+## Moderation is opt-in, honestly
+
+Nothing is filtered automatically. To moderate comment bodies, add one rule to
+[`plugin-moderation`](/docs/plugins/moderation):
+
+```ts
+moderationPlugin({ rules: [{ match: /^comments\./, fields: ['body'] }] })
+```
+
+Deleting others' comments takes the `comments:moderate` scope; editing is
+always author-only.
+
+## What else ships
+
+- **Reactions** — per-emoji toggle, aggregated with `count` + `mine`, in the
+  live delta.
+- **Thread unread** — a per-subject read marker (`markRead`); `useComments`
+  returns `unreadCount` (your own comments are never unread for you).
+- **Resolve / reopen** — anyone who may read the anchor may resolve (the
+  Liveblocks semantic).
+- **Attachments** are a declared limit: grant an upload via
+  [`plugin-storage`](/docs/plugins/storage) and put the URL in the body —
+  first-class `attachments[]` is deliberately not built until the storage
+  grant flow is the proven shape.
+- **Known reactivity granularity:** the live feed is channel-wide — every
+  comment write re-runs every open `comments.list` subscription app-wide.
+  Fine for team-scale commenting; the read-set work on the realtime roadmap
+  is the named narrowing.
+
+## Observability
+
+`GET /_voltro/inspect/plugins/comments/threads` + a Comments panel in both
+dashboards (volume, open/resolved, recent threads).