@voltro/cli 0.51.0 → 0.53.0

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

@@ -0,0 +1,142 @@
+# 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}`)
+```
+
+## 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).

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,21 @@ 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({
+  resolveMember: async ({ subject }) => {
+    const user = await users.byId((subject as { id: string }).id)
+    return user ? { userName: user.name, avatarUrl: user.avatarUrl } : undefined
+  },
+})
+```
+
+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,7 +20,7 @@ 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.
 - **`@voltro/cache`** counters, Effect's own `effect_fiber_*` runtime metrics, and **any custom metric** you or another plugin defines.

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

@@ -0,0 +1,129 @@
+# 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
+
+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.

package/templates/agent-docs/plugins/{versioning.md → row-history.md}

@@ -1,27 +1,27 @@
-# Row versioning
+# Row history
 
-> Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries.
+> Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries.
 
 
 
 ---
 
-<!-- source: en/plugins/versioning.md -->
-## Row versioning
+<!-- source: en/plugins/row-history.md -->
+## Row history
 
-_Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries._
+_Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries._
 
-`@voltro/plugin-versioning` keeps a complete value history of selected tables. Where [`audit()`](/docs/plugins/audit) records *who* changed a row and *when*, versioning records *what* — a full snapshot of the row on every insert / update / delete — and lets you read any row **as of** a past instant. It rides the framework's post-commit ChangeEvent tap, so it captures every write that goes through the store with no per-handler wiring.
+`@voltro/plugin-row-history` keeps a complete value history of selected tables. Where [`audit()`](/docs/plugins/audit) records *who* changed a row and *when*, row-history records *what* — a full snapshot of the row on every insert / update / delete — and lets you read any row **as of** a past instant. It rides the framework's post-commit ChangeEvent tap, so it captures every write that goes through the store with no per-handler wiring.
 
 ## Wiring
 
 ```ts
 // app.config.ts
-import { versioningPlugin } from '@voltro/plugin-versioning'
+import { rowHistoryPlugin } from '@voltro/plugin-row-history'
 
 export default {
   type: 'api' as const, name: 'api',
-  plugins: [versioningPlugin({})],
+  plugins: [rowHistoryPlugin({})],
 }
 ```
 
@@ -30,14 +30,14 @@ Every committed change to a listed table appends a row to `_voltro_row_history`
 The history row's own `id` is **derived** from `(tableName, rowId, version)` and has a fixed width — it is a surrogate, and every part of it is already a column beside it, so do not parse or construct it. That width is the point: an `id()` column is `VARCHAR(64)` on mysql/mariadb and `NVARCHAR(64)` on mssql, so a key built by concatenating those parts grew with your **table name** and stopped fitting past 22 characters — which failed every write to that table, not merely an import.
 
 
-### What gets versioned — opt OUT, not in
+### What gets recorded — opt OUT, not in
 
-`versioningPlugin({})` covers **every table your app declares**. There is no list to write and none to maintain.
+`rowHistoryPlugin({})` covers **every table your app declares**. There is no list to write and none to maintain.
 
 ```ts
-versioningPlugin({})                              // every app table
-versioningPlugin({ exclude: [domainEvents] })     // opt one out
-versioningPlugin({ include: [aiFlowsTable] })     // add a PLUGIN's table
+rowHistoryPlugin({})                              // every app table
+rowHistoryPlugin({ exclude: [domainEvents] })     // opt one out
+rowHistoryPlugin({ include: [aiFlowsTable] })     // add a PLUGIN's table
 ```
 
 Both take table **values**, not names — a misspelling is a compile error at the call site, exactly as with `reference(() => table)`.
@@ -51,18 +51,18 @@ A table named in both `include` and `exclude` throws at construction — only yo
 **Check the boot line once after upgrading.** It prints the RESOLVED count, not the configured one:
 
 ```txt
-versioning active · tables: 41 · historyTable: _voltro_row_history · retentionDays: 365
+row-history active · tables: 41 · historyTable: _voltro_row_history · retentionDays: 365
 ```
 
 If 41 surprises you, `exclude` is the knob. The retention sweep (`VOLTRO_ROW_HISTORY_TTL_HOURS`) still bounds age.
 
 ## What this is NOT — the grain
 
-Versioning records **row changes, not domain events**. One entry per row per write, named by *table*. If your product has a user-facing audit feature whose entries are named after an aggregate root — one `Team` event for a call that writes `teams` + `roles` + `userTeams` + `userTeamRoles` — this is the layer **underneath** that, not a replacement for it.
+Row history records **row changes, not domain events**. One entry per row per write, named by *table*. If your product has a user-facing audit feature whose entries are named after an aggregate root — one `Team` event for a call that writes `teams` + `roles` + `userTeams` + `userTeamRoles` — this is the layer **underneath** that, not a replacement for it.
 
 The distinction is worth reading before you plan a migration onto it. A migration off hundreds of hand-written audit calls onto this tap runs into the same wall a few hours in: the grain is different. A table-keyed tap does not produce an aggregate-keyed trail with better coverage, it produces a *different artifact*. The two compose:
 
-- **versioning** answers "what did row R look like before, and after" — for every write, whether or not anyone remembered to record it;
+- **row history** answers "what did row R look like before, and after" — for every write, whether or not anyone remembered to record it;
 - an **aggregate trail** (the [audit sink](/docs/plugins/audit), one row per mutation invocation) answers "what business operation happened, to which entity, and did it succeed";
 - `traceId` joins them, so one request reads as one story.
 
@@ -95,10 +95,10 @@ migration — with the same meaning as an absent `traceId`.
 
 ## The correlation bridge — joining *what changed* to *who called*
 
-`ChangeEvent` carries the calling `traceId` and `subjectId`, so a history row can be joined to the [audit sink](/docs/plugins/audit) row for the **same call**. Before this, both trails existed and shipped and nothing connected them: versioning knew what changed, the audit sink knew who called and whether they were refused, and no key spanned the two.
+`ChangeEvent` carries the calling `traceId` and `subjectId`, so a history row can be joined to the [audit sink](/docs/plugins/audit) row for the **same call**. Before this, both trails existed and shipped and nothing connected them: row-history knew what changed, the audit sink knew who called and whether they were refused, and no key spanned the two.
 
 ```ts
-import { historyByTrace, historyBySubject } from '@voltro/plugin-versioning'
+import { historyByTrace, historyBySubject } from '@voltro/plugin-row-history'
 
 // What did this call change? (`byTrace`)
 const touched = await historyByTrace(ctx.store, traceId, ctx.request.subject.tenantId)
@@ -118,7 +118,7 @@ Both questions were previously unanswerable at any speed — `byRow` is the only
 ## `timing` — when the history row is written
 
 ```ts
-versioningPlugin({ timing: 'in-transaction' })
+rowHistoryPlugin({ timing: 'in-transaction' })
 ```
 
 | | `'post-commit'` (default) | `'in-transaction'` |
@@ -175,7 +175,7 @@ That is the correct order, not a race to engineer around: the change is durable,
 { "id": "sess_1", "secret": "enc:v1:a56iziEV9THLhzmJ:Vk0ux+0bECleTLBJkCa0Rg==:3AtMwP" }
 ```
 
-So versioning a table with encrypted columns **does not widen exposure** — the history is exactly as readable as the row it came from. This is worth stating because "full row snapshot" reads alarming next to `.encrypted()`, and the cautious reader excludes the table. One did, and only found out by measuring.
+So keeping history for a table with encrypted columns **does not widen exposure** — the history is exactly as readable as the row it came from. This is worth stating because "full row snapshot" reads alarming next to `.encrypted()`, and the cautious reader excludes the table. One did, and only found out by measuring.
 
 **`.serverOnly()` columns ARE withheld**, and for a sharper reason than "a second copy": `crud.*` strips those columns from every row it returns, and a snapshot would smuggle the value back past that stripping inside a `json()` blob, where no column-level rule applies. A marker meaning *never serialize this to a client* cannot survive being re-exported through a different column's contents.
 
@@ -189,7 +189,7 @@ The withheld names are listed under `data._omitted`, so a reader can tell *"this
 ## Querying the timeline
 
 ```ts
-import { rowHistory, rowAsOf } from '@voltro/plugin-versioning'
+import { rowHistory, rowAsOf } from '@voltro/plugin-row-history'
 
 // Every version of a row, oldest → newest — TENANT-SCOPED to the caller:
 const history = await rowHistory(ctx.store, 'posts', postId, ctx.request.subject.tenantId)
@@ -204,7 +204,7 @@ Pass the caller's `tenantId` — reads are **tenant-scoped**: a row's value time
 ## Restore & diff
 
 ```ts
-import { restoreAsOf, diffVersions } from '@voltro/plugin-versioning'
+import { restoreAsOf, diffVersions } from '@voltro/plugin-row-history'
 
 // Roll the LIVE row back to its state at a past instant (tenant-scoped like
 // rowAsOf — no visible state then ⇒ null, nothing written). The restore goes

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

@@ -1,6 +1,6 @@
 # Storage
 
-> File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser.
+> File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser.
 
 
 
@@ -9,7 +9,7 @@
 <!-- source: en/plugins/storage.md -->
 ## Storage
 
-_File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser._
+_File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser._
 
 `@voltro/plugin-storage` is file storage behind one `StorageService`. Wire a
 provider in `app.config.ts`; consume it in handlers and actions via