@voltro/cli 0.52.0 → 0.54.0

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

@@ -1,6 +1,6 @@
 # Notifications
 
-> Unified notifications — one send API across email / Slack / SMS / push / in-app, with per-user channel preferences, an in-app inbox, and delivery records.
+> Unified notifications — one send API across email / Slack / SMS / mobile push / web push / in-app, with per-user channel preferences, an in-app inbox, and delivery records.
 
 
 
@@ -9,7 +9,7 @@
 <!-- source: en/plugins/notifications.md -->
 ## Notifications
 
-_Unified notifications — one send API across email / Slack / SMS / push / in-app, with per-user channel preferences, an in-app inbox, and delivery records._
+_Unified notifications — one send API across email / Slack / SMS / mobile push / web push / in-app, with per-user channel preferences, an in-app inbox, and delivery records._
 
 `@voltro/plugin-notifications` is the **one** messaging answer instead of twenty brand wrappers: a single `send` across channels, per-user preferences, and an in-app inbox with unread counts — not a per-vendor SDK in every handler.
 
@@ -34,7 +34,7 @@ export default {
 }
 ```
 
-The built-in **in-app** channel persists to the notification store and is appended automatically; `consoleChannel()`, `webhookChannel({ url, id?, format?, headers? })`, `emailChannel(send)`, `smsChannel(send)`, `pushChannel({ tokensFor, transport })` (see [Push](#push-apns-fcm)), and `customChannel(id, deliver)` cover the rest. A channel is just `{ id, deliver: (msg) => Promise<void> }` — bring your own.
+The built-in **in-app** channel persists to the notification store and is appended automatically; `consoleChannel()`, `webhookChannel({ url, id?, format?, headers? })`, `emailChannel(send)`, `smsChannel(send)`, `pushChannel({ tokensFor, transport, onTokenRejected? })` (see [Push](#push-apns-fcm)), `webPushChannel()` (see [Web Push](#web-push-vapid)), and `customChannel(id, deliver)` cover the rest. A channel is just `{ id, deliver: (msg) => Promise<void> }` — bring your own.
 
 `notificationsPlugin({ channels?, store?, digestWindowMs?, flushIntervalMs?, name? })` — the inbox, per-subject channel preferences, and delivery log **auto-persist to the framework DataStore by default**, durably, on every supported dialect. You only pass an explicit `store` for a **custom** backend (see [Store](#store)). `digestWindowMs` enables [digest/batching](#digest-batching); the scheduled flush (interval `flushIntervalMs`, default 30s) drains digest windows and quiet-hours deferrals.
 
@@ -75,7 +75,50 @@ pushChannel({
 })
 ```
 
-`deliver` formats one `PushPayload` per device token and sends each. A `PushTokenRejected` is captured into the fan-out (recorded `failed`, naming the rejected token — **never** the auth secret) so your app can prune the dead token. The push AUTH secret lives in your `transport` closure — it never enters the package and is never logged.
+Delivery is **per token and isolated**: each device token sends independently, and the delivery log records one row PER TOKEN (`endpoint` names it) — a stale token on one old phone no longer aborts the send to every current device, and the channel counts delivered when at least one token was reached. A `PushTokenRejected` thrown by your transport marks that token's record `failed` (naming the token — **never** the auth secret) and fires the optional `onTokenRejected(token, reason)` hook, which is where your app prunes the dead token from its own table. The push AUTH secret lives in your `transport` closure — it never enters the package and is never logged.
+
+## Web Push (VAPID)
+
+`webPushChannel()` delivers real browser push — a user subscribes once and receives notifications with the tab closed. Subscriptions are managed by the plugin itself (per subject AND per browser endpoint, in `_voltro_notification_push_subscriptions`), payloads are encrypted per RFC 8291, auth is VAPID (RFC 8292), and dead endpoints are pruned automatically.
+
+```ts
+// app.config.ts
+notificationsPlugin({
+  channels: [webPushChannel({ contact: 'mailto:ops@example.com' })],
+})
+```
+
+**The key is minted, never shipped.** The channel signs with `VOLTRO_VAPID_PRIVATE_KEY` (a base64url P-256 scalar); `voltro dev` mints a per-project value into the gitignored `.env.local` on first boot, and a production boot without one **refuses by name** — there is deliberately no default. The browser-facing public key is DERIVED from the private scalar, so a public/private pair can never desync.
+
+**Setup, three steps:**
+
+1. Configure the channel (above). Web push requires HTTPS in production (localhost is exempt).
+2. Copy the service worker into your web app: `cp node_modules/@voltro/plugin-notifications/sw.js public/sw.js`. Its URL decides its scope — served from the root it covers the whole app. It shows the notification, opens the declared `url` on click, reports the click, and posts the payload to open pages (`{ type: 'voltro:push' }` message) so an in-page inbox can refresh live.
+3. Offer the subscribe flow with the hook:
+
+```tsx
+import { useWebPush } from '@voltro/plugin-notifications/web'
+
+const PushSettings = () => {
+  const push = useWebPush()
+  if (push.status === 'unsupported') return <p>This browser cannot receive push.</p>
+  return push.status === 'subscribed'
+    ? <button onClick={() => void push.unsubscribe()}>Disable push</button>
+    : <button onClick={() => void push.subscribe()}>Enable push</button>
+}
+```
+
+The semantics, precisely:
+
+- **Multi-endpoint is the design, not an edge case.** Three browsers = three endpoint rows for one subject. Delivery is per endpoint and isolated; the delivery log records one row per endpoint. A re-subscribe on the same endpoint takes the row over — the endpoint belongs to the browser profile, and the latest signed-in subject owns it.
+- **Prune is automatic and exact.** A push service answering 404/410 for one endpoint deletes exactly that row; the subject's other browsers keep receiving. No app-side prune code.
+- **Payload cap ~4 KB.** Push services cap the encrypted body; an oversized payload SHRINKS (the `data` bag first, then the body is truncated) rather than being dropped.
+- **Click tracking is built in.** Each delivered notification carries a one-time click token; the service worker's `notificationclick` reports it and the delivery record gains `clickedAt` — open rates read straight off the delivery log.
+- **Preferences, quiet hours and digests apply unchanged** — the channel is a sender like any other (its preference key is `webPush`).
+- **iOS Safari, honestly:** web push works on iOS 16.4+ ONLY for installed home-screen web apps (PWA), never in the browser tab. Do not promise iOS coverage from a plain website.
+- **Scheduled send** is a recipe, not a switch: `defineSchedule` + `send` covers "notify at 9am" without a second delivery queue. Quiet hours and digests already defer within their own semantics.
+
+Subscribe/unsubscribe are RPC mutations (`notifications.webPushSubscribe` / `webPushUnsubscribe` — subject-bound, so one subject can never detach another's browser); `notifications.webPushPublicKey` hands the browser its `applicationServerKey`; `notifications.webPushStatus` counts the caller's registered endpoints.
 
 ## Digest / batching
 

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

@@ -1,6 +1,6 @@
 # Presence
 
-> Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor). Works cross-instance.
+> Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor — client-supplied and relayed verbatim; identity fields belong in the server-side resolveMember hook). Works cross-instance.
 
 
 
@@ -9,7 +9,7 @@
 <!-- source: en/plugins/presence.md -->
 ## Presence
 
-_Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor). Works cross-instance._
+_Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor — client-supplied and relayed verbatim; identity fields belong in the server-side resolveMember hook). Works cross-instance._
 
 `@voltro/plugin-presence` answers "who's here right now". A client heartbeats into a channel; the roster lists everyone whose heartbeat is fresh. Held **in memory**, owner-partitioned: every member belongs to exactly the replica holding its WebSocket, so concurrent writes to one key are impossible by construction and there is no table, no CRDT and no coordinator.
 
@@ -49,8 +49,50 @@ const Room = ({ channel }: { channel: string }) => {
 
 A member is `{ key, meta }`. **It pushes only when the roster actually moves** — a join, a leave, a change to someone's `meta`, a sweep, a peer's delta, a peer's death. A heartbeat that repeats what the server already knows pushes nothing, which is what keeps a large steady room free.
 
+**`meta` is client-supplied, unvalidated, and handed to every channel member verbatim — identity does not belong in it.** That contract is right for a cursor or a status flag, and wrong for `userName` / `avatarUrl`: any member of a channel could present any name and any `<img src>` to everyone else. For identity fields, give the plugin a server-side resolver — it runs on every heartbeat and its result is merged OVER the caller's `meta`, so a client cannot override what the server says about them:
+
+```ts
+presencePlugin({
+  // `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.**
-> [`@voltro/local-first/react`](/docs/local-first/overview#presence--awareness)
+> [`@voltro/local-first/react`](/docs/local-first/overview#presence-awareness)
 > exports one for peer-to-peer *awareness* — `usePresence(roomId, self, { channel })`
 > → `{ presence, others, setPresence }` — carrying high-frequency cursor and
 > selection state over a pub/sub channel. This one is the server-backed roster.

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

@@ -20,9 +20,11 @@ The framework records metrics into Effect's global `MetricRegistry`. One snapsho
 - **Core RPC** — `voltro_rpc_requests_total{tag,status}`, `voltro_rpc_errors_total{tag}`, `voltro_rpc_duration_seconds{tag}` (histogram). Emitted at the mutation / action handler boundary.
 - **HTTP routes** — `voltro_http_requests_total{route,status}`, `voltro_http_duration_seconds{route}`.
 - **Plugin interceptors** — `voltro_plugin_hook_duration_seconds{hook}`, `voltro_plugin_hook_errors_total{hook}`.
-- **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`).
+- **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

@@ -0,0 +1,172 @@
+# Queue (Kafka interop)
+
+> Consume and produce against an existing Kafka — Schema-decoded consumers (at-least-once, serial per partition, retry + dead-letter), batched producing via a handler service or transactionally through the outbox, and a kafkaSink for cdc-out.
+
+
+
+---
+
+<!-- source: en/plugins/queue.md -->
+## Queue (Kafka interop)
+
+_Consume and produce against an existing Kafka — Schema-decoded consumers (at-least-once, serial per partition, retry + dead-letter), batched producing via a handler service or transactionally through the outbox, and a kafkaSink for cdc-out._
+
+`@voltro/plugin-queue` is the door to queues **somebody else owns**: a Voltro
+backend consuming and producing against an adopter's existing Kafka. The
+boundary with the built-ins, in one line each: the [outbox](/docs/data/outbox)
+is *your own* durable side-effects, a [workflow](/docs/workflows/overview) is
+*your own* orchestration — this plugin is interop with foreign infrastructure.
+Kafka first; the provider contract is cut so SQS/RabbitMQ can be later
+implementations.
+
+```ts
+// app.config.ts
+import { queuePlugin } from '@voltro/plugin-queue'
+
+export default {
+  // …
+  plugins: [
+    queuePlugin({ brokers: ['kafka-1:9092', 'kafka-2:9092'] }),
+  ],
+}
+```
+
+## Consuming: `*.consumer.ts`
+
+```ts
+// src/consumers/orders.consumer.ts
+import { Schema } from 'effect'
+import { defineQueueConsumer } from '@voltro/plugin-queue'
+
+export const orders = defineQueueConsumer({
+  topic: 'orders',
+  schema: Schema.Struct({ orderId: Schema.String, total: Schema.Number }),
+  handler: async (order, ctx) => {
+    // MUST be idempotent — delivery is at-least-once. A unique-column
+    // upsert is the standard shape:
+    await ctx.store.upsert('orders_mirror',
+      { orderId: order.orderId, total: order.total },
+      { conflictColumns: ['orderId'] })
+  },
+})
+```
+
+Both boot paths discover `*.consumer.ts`; the plugin starts every registered
+consumer at activation and stops them at shutdown. The semantics, precisely:
+
+- **Ordering: serial per partition.** Parallelism exists only ACROSS
+  partitions — concurrency inside one would destroy ordering and commit
+  semantics both. Retry backoff deliberately BLOCKS the partition.
+- **Commit after the handler, per message.** A process killed mid-batch
+  redelivers exactly the unhandled tail — never the whole batch, never a
+  skipped message.
+- **Decode failures dead-letter IMMEDIATELY** (to `<topic>.dlq`, with
+  `x-voltro-dlq-*` reason headers) — a deterministic failure retried forever
+  is an infinite loop with extra steps, and a poison message must release
+  its partition.
+- **Handler failures retry with backoff, then dead-letter** after
+  `maxAttempts` (default 3).
+- **A rebalance is not a failure.** A partition revoked mid-batch or
+  mid-retry stops processing without a retry-counter increment or a DLQ
+  publish — the new owner redelivers.
+- **Handlers are NOT wrapped in a transaction** (the same documented
+  boundary as HTTP route handlers). A handler needing atomic multi-writes
+  opens `ctx.store.transactional` itself — and stays idempotent either way.
+- **Replica coordination is Kafka's own.** Every replica joins the same
+  consumer group and the broker assigns partitions — no advisory lock, unlike
+  [schedules](/docs/scheduling/coordination), which coordinate through the
+  claim table because no broker exists to do it for them.
+
+## Producing
+
+Two paths, one rule: transactional-with-a-write goes through the outbox.
+
+```ts
+// Inside a mutation — commits or rolls back WITH the domain write:
+await ctx.outbox.enqueue('queue.produce', {
+  topic: 'orders',
+  messages: [{ key: order.id, value: JSON.stringify(order) }],
+})
+```
+
+```ts
+// src/queue.outbox.ts — the bridge (once per app):
+import { queueOutboxHandler } from '@voltro/plugin-queue'
+export default queueOutboxHandler()
+```
+
+The outbox runner delivers after commit — batched (`messages` is an array →
+one transport round-trip), at-least-once, retried, dead-lettered. One
+durability path: the existing outbox, not a second one. For fire-and-forget
+producing without a surrounding write, `yield* QueueService` in a handler and
+call `produce(topic, messages)` directly.
+
+Topic creation is EXPLICIT (`provider.ensureTopics([...])`) — your Kafka is
+foreign infrastructure, and whether a client may create topics is your
+policy. A consumer started against a topic that does not exist yet warns and
+retries in the background (it connects once the topic appears), never
+aborting the boot.
+
+## cdc-out to Kafka
+
+`kafkaSink` plugs table-change mirroring ([plugin-cdc-out](/docs/plugins/cdc-out))
+into the SAME provider: 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 cdc-out's at-least-once dedupe handle.
+
+```ts
+import { cdcOutPlugin } from '@voltro/plugin-cdc-out'
+import { kafkaSink } from '@voltro/plugin-queue'
+
+cdcOutPlugin({ sinks: [{ table: 'orders', sink: kafkaSink({ topic: 'orders.cdc' }) }] })
+```
+
+## Observability
+
+**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

@@ -42,7 +42,9 @@ The framework ships some plugins; you write your own; the contract is small enou
 - [plugin-logship](/docs/plugins/logship) — ship structured logs to Better Stack / Axiom / Loki / any HTTP sink; batched, redacted, fail-soft
 - [plugin-moderation](/docs/plugins/moderation) — moderate user content before commit: keyword or AI provider, block / flag via interceptor + in-handler redact
 - [plugin-search](/docs/plugins/search) — keep an external index (Typesense / Meilisearch / Algolia) in sync via the ChangeEvent tap; tenant-scoped `search.query` + hook
-- [plugin-cdc-out](/docs/plugins/cdc-out) — declarative reverse-ETL: mirror table changes outward to a webhook sink (or any custom `CdcSink`) through a durable outbox; ordered per pipe, at-least-once from enqueue, dead-lettered
+- [plugin-cdc-out](/docs/plugins/cdc-out) — declarative reverse-ETL: mirror table changes outward to a webhook or Kafka sink (or any custom `CdcSink`) through a durable outbox; ordered per pipe, at-least-once from enqueue, dead-lettered
+- [plugin-queue](/docs/plugins/queue) — Kafka interop: Schema-decoded consumers (`*.consumer.ts`; at-least-once, serial per partition, retry + dead-letter), batched producing via a service or transactionally through the outbox, and a `kafkaSink` for cdc-out
+- [plugin-comments](/docs/plugins/comments) — comment threads on any app entity: replies, resolve/reopen, tenant-safe @-mentions with notifications, reactions, unread — live over the reactive engine, with the ejectable `<CommentsThread>` UI
 - [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-row-history](/docs/plugins/row-history) — full row history + time-travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions`); what-changed-to-what on every write
@@ -74,13 +76,15 @@ 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-comments` | ✓ | Comment threads anchored to any entity — fail-closed access delegation (`viaEntity`/`scope`), replies, resolve/reopen, tenant-safe mentions (validated twice, delivered via plugin-notifications incl. digests), reactions, per-subject unread, live `comments.list`, `<CommentsThread>` in `@voltro/ui`. [→ details](/docs/plugins/comments) |
+| `@voltro/plugin-queue` | ✓ | Kafka interop — `defineQueueConsumer` (`*.consumer.ts`, Schema-decoded, at-least-once, serial per partition, retry + DLQ with reason headers), batched producing via `QueueService` or transactionally through the outbox (`queueOutboxHandler`), `kafkaSink` for cdc-out, per-topic counters in the dashboards. [→ details](/docs/plugins/queue) |
 | `@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) |
-| `@voltro/plugin-clickhouse` | ✓ | Production OLAP via the official ClickHouse client. [→ details](/docs/plugins/analytics#voltroplugin-clickhouse) |
-| `@voltro/plugin-tinybird` | ✓ | Hosted ClickHouse via Events API + Pipes. [→ details](/docs/plugins/analytics#voltroplugin-tinybird) |
-| `@voltro/plugin-posthog` | ✓ | Product analytics — track-only; compose with another sink for reads. [→ details](/docs/plugins/analytics#voltroplugin-posthog) |
+| `@voltro/plugin-analytics-postgres` | ✓ | First-party lite — events on the main DataStore, cross-dialect (postgres / mysql / mariadb / mssql / sqlite / turso). [→ details](/docs/plugins/analytics) |
+| `@voltro/plugin-duckdb` | ✓ | Embedded DuckDB sidecar — real OLAP performance, no external service. [→ details](/docs/plugins/analytics) |
+| `@voltro/plugin-clickhouse` | ✓ | Production OLAP via the official ClickHouse client. [→ details](/docs/plugins/analytics) |
+| `@voltro/plugin-tinybird` | ✓ | Hosted ClickHouse via Events API + Pipes. [→ details](/docs/plugins/analytics) |
+| `@voltro/plugin-posthog` | ✓ | Product analytics — track-only; compose with another sink for reads. [→ details](/docs/plugins/analytics) |
 | `@voltro/plugin-atlassian` | ✓ | `JiraService` + `ConfluenceService` over the Atlassian REST / Greenhopper / Agile APIs — PAT **or** OAuth 2.0 (3LO) auth, transient retry, SSRF guard, comment-write, signature-verified inbound webhooks, avatar proxy, per-tenant cache. [→ details](/docs/plugins/atlassian) |
 | `@voltro/plugin-deactivation` | ✓ | `deactivation()` schema mixin — `deactivatedAt` + `deactivatedBy` (→ Actor); subject can't log in but data stays visible. [→ details](/docs/plugins/deactivation) |
 | `@voltro/plugin-prometheus` | ✓ | Prometheus exporter — `GET /metrics` in text exposition format over the unified Metrics-API (Effect `MetricRegistry`); counters / histograms / gauges + custom metrics, optional bearer gate + node process metrics. [→ details](/docs/plugins/prometheus) |
@@ -91,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) |
@@ -880,7 +884,7 @@ A plugin can mount plain HTTP routes beside the rpc surface (`@voltro/plugin-sto
 
 - **The full method union is first-class.** `method` is `'*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'`. **HEAD is admitted wherever GET is** (RFC 9110) — the GET handler runs and the transport drops the body; you never mount a second route for it. A wrong method stays a precise `405` with an `Allow:` header, including when several routes share one path.
 - **The body read is capped** — 8 MiB by default, the same cap as every other surface (`http.maxBodyBytes` in `app.config.ts`, env `VOLTRO_MAX_BODY_BYTES`), and the read is binary-clean. A route that takes more declares its own `maxBodyBytes`; routes **sharing a path share one body read**, so the widest override in the group applies to the group. Oversize answers `413` for both `Content-Length` and chunked requests.
-- **Binary streaming responses** return `byteStream` on the `PluginHttpRouteResult` — a `ReadableStream<Uint8Array>` (or lazy thunk) with optional `contentLength` / `contentDisposition`, piped without buffering and never compressed. It is the plugin-route spelling of the REST surface's [`bytes()`](/docs/data/rest-routes#binary-downloads--bytes).
+- **Binary streaming responses** return `byteStream` on the `PluginHttpRouteResult` — a `ReadableStream<Uint8Array>` (or lazy thunk) with optional `contentLength` / `contentDisposition`, piped without buffering and never compressed. It is the plugin-route spelling of the REST surface's [`bytes()`](/docs/data/rest-routes#binary-downloads-bytes).
 - **Buffered responses are compression-negotiated** (brotli/gzip, compressible types only) by the listener — nothing to declare; see [Security → compression](/docs/security/overview).
 
 A state-changing plugin route is origin-checked unless it declares `originGuard: 'exempt'`, and `req.remoteAddr` is the trusted-proxy-resolved client address — both covered with examples in [Security](/docs/security/overview#routes-that-a-third-party-legitimately-posts-to).
@@ -1335,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)
@@ -225,6 +244,18 @@ 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)),
+`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
+is unreachable; the first live event replaces it, and a reconnect inside the
+resume window continues with deltas from the mirrored revision. Offline
+WRITES ride [`useOutbox`](/docs/ui/client-utilities/use-outbox) — durable
+with `outboxPersistence()`, conflict resolution via `resolveConflict`.
+
 ## `useMutation(apiName, rpcTag)`
 
 Calls a `defineMutation` RPC.
@@ -592,7 +623,7 @@ window.history.forward()   // forward
 
 ## `useBlocker()`
 
-Hold a pending navigation so you can prompt before the user leaves — the unsaved-changes guard.
+Hold a pending navigation so you can prompt before the user leaves — the unsaved-changes guard. It guards SPA navigations, the browser's **Back/Forward gestures** (popstate: the router reverts the already-moved URL and offers `retry`/`reset` — this also covers ESC inside an [intercepting-route overlay](/docs/routing/intercepting-routes)), and full-page unloads via `beforeunload`.
 
 ```tsx
 import { useBlocker } from '@voltro/web'
@@ -637,7 +668,7 @@ setParams((p) => { p.set('page', '2'); return p })   // patch one param
 setParams({ page: '2' }, { push: true })             // distinct history entry
 ```
 
-Writes default to a history replace; pass `{ push: true }` for a Back entry or `{ scroll: false }` to keep scroll. See [Navigation](/docs/routing/navigation#reading--writing-search-params).
+Writes default to a history replace; pass `{ push: true }` for a Back entry or `{ scroll: false }` to keep scroll. See [Navigation](/docs/routing/navigation#reading-writing-search-params).
 
 `useSetSearchParams(searchParams)` — pass the schema to get the **typed** setter. Object form replaces the query (a left-out field decodes to its default on the next read); the updater form receives the current **decoded** params, so a merge is an explicit spread:
 
@@ -715,7 +746,7 @@ Precisely, it returns `LoaderData<T>`. For every ordinary loader that IS `T`. Fo
 a loader that returned `defer()`, `LoaderData<T>` flattens the two buckets into
 one object — eager fields as values, deferred fields as `Promise<T>` — so the
 compiler tells you which fields have to be rendered through
-[`<Await>`](/docs/routing/loaders-and-meta#deferring-slow-data-defer--await):
+[`<Await>`](/docs/routing/loaders-and-meta#deferring-slow-data-defer):
 
 ```tsx
 export const loader = async ({ query }) => defer(
@@ -856,7 +887,7 @@ that must react to router-pushed query changes without a reload re-render throug
 
 Prefer the typed form where the page declares a `searchParams` schema export —
 `useSearchParams(searchParams)` returns the decoded shape instead of a raw
-`URLSearchParams`. See [Routing hooks](/docs/reference/hooks-routing#usesearchparams--usesetsearchparams).
+`URLSearchParams`. See [Routing hooks](/docs/reference/hooks-routing#usesearchparams-usesetsearchparams).
 
 ## Reading cookies