npm - @voltro/cli - Versions diffs - 0.52.0 → 0.53.0 - Mend

@voltro/cli 0.52.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (195) hide show

package/templates/agent-docs/database/seedsdialects.md CHANGED Viewed

@@ -1055,7 +1055,7 @@ MariaDB's GTID format differs from MySQL's: `0-1-100` (domain-server-sequence) v
 - **`mariadb` schema package is wire-compatible with `mysql`**. If you migrate from MySQL → MariaDB, the framework re-emits DDL cleanly via `applySchema(..., 'mariadb')`. Production data round-trips through `mysqldump` without translation.
 - **`sql_mode=NO_BACKSLASH_ESCAPES`** is sometimes set on MariaDB deploys. The framework's identifier escaping handles it, but user-written `unsafe()` strings that hand-escape backslashes may produce wrong output. Leave that mode off if you can.
 - **Sequence-based ID columns**. MariaDB has true CREATE SEQUENCE; the framework doesn't use it (TypeID / ULID / Snowflake are client-side). If you reach for sequences for legacy reasons, they're outside the framework's auto-injection path.
-- **Hand-rolled `AUTO_INCREMENT` primary keys** work the same as on mysql: an `insert` / `insertMany` with no client-side `id` recovers the DB-generated id via `LAST_INSERT_ID()` (connection-pinned; `insertMany` recovers the whole consecutive range). See the [mysql page](/docs/database/dialects/mysql#auto_increment-ids--last_insert_id-recovery) for the worked example — the recovery path is identical on both engines.
+- **Hand-rolled `AUTO_INCREMENT` primary keys** work the same as on mysql: an `insert` / `insertMany` with no client-side `id` recovers the DB-generated id via `LAST_INSERT_ID()` (connection-pinned; `insertMany` recovers the whole consecutive range). See the [mysql page](/docs/database/dialects/mysql) for the worked example — the recovery path is identical on both engines.
 ## Where it lives

package/templates/agent-docs/database/transactions.md CHANGED Viewed

@@ -261,7 +261,7 @@ await ctx.store.upsert('orgSlugs', {
 ```
 Requires a composite UNIQUE constraint on the table — declare it via
-`.unique([cols])` in the schema (see [Indexes](/docs/database/indexes#composite-unique)).
+`.unique([cols])` in the schema (see [Indexes](/docs/database/indexes#composite-unique-constraints)).
 ## `insertIgnore` — keep existing on conflict
@@ -314,7 +314,7 @@ const count = await ctx.store.updateMany('posts', { hidden: true }, {
 // count: number of rows actually updated
 ```
-The `where` predicate is a regular [Predicate](/docs/database/query-builder#predicates)
+The `where` predicate is a regular [Predicate](/docs/database/query-builder)
 AST — same shape `.where()` uses. Sub-queries via `inSubquery` /
 `exists` are supported.
@@ -395,5 +395,5 @@ matters.
   `aggregate()` for read-side bulk reads
 - [Sub-queries](/docs/database/sub-queries) — `inSubquery` /
   `exists` in `updateMany` `where:` clauses
-- [Composite UNIQUE](/docs/database/indexes#composite-unique) — for
+- [Composite UNIQUE](/docs/database/indexes#composite-unique-constraints) — for
   the constraint that backs `upsert`'s `conflictColumns: ['a', 'b']`

package/templates/agent-docs/deployment.md CHANGED Viewed

@@ -1119,6 +1119,14 @@ VOLTRO_LOG_FORMAT=json
 VOLTRO_LOG_LEVEL=info
 ```
+In `json` mode (the default off a TTY, so a pod gets it without configuration)
+EVERY line the framework emits is a parseable record — the boot banner, the app
+surface, `voltro db apply`'s plan summary, refusal detail, and every subsystem
+logger (schedule, broadcast, workflow, flow-control). A hand-formatted table or
+a `[tag]`-prefixed adapter line between JSON records is a bug, not a style: log
+collectors show it as unparsed noise. On a TTY the same surfaces render as the
+human-readable banners and tables.
 **Error reporting** — add `sentryPlugin()` from `@voltro/plugin-sentry`. It stays inert until `SENTRY_DSN` is set, and reported errors correlate to the request `traceId`:
 ```ts

package/templates/agent-docs/internationalization.md CHANGED Viewed

@@ -96,7 +96,7 @@ The client **adopts what the server resolved**, reading it from the `<html lang>
 | `data-voltro-tz` | the IANA zone every date/time formatter renders in — set `timeZone` in `app.config.ts` |
 | `data-voltro-now` | the server's render instant, so `useRelativeTime` produces the same string in the hydration pass |
-Locale was already agreed; the zone and the clock were each read from the ambient runtime, which meant a server-rendered timestamp was a hydration mismatch waiting for a wide enough offset or a slow enough connection. See [Plurals & formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr--the-setting-that-is-not-a-preference) — that is the page to read before you migrate hand-rolled `toLocaleString()` calls onto the hooks.
+Locale was already agreed; the zone and the clock were each read from the ambient runtime, which meant a server-rendered timestamp was a hydration mismatch waiting for a wide enough offset or a slow enough connection. See [Plurals & formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr-the-setting-that-is-not-a-preference) — that is the page to read before you migrate hand-rolled `toLocaleString()` calls onto the hooks.
 See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, [Plurals & formatting](/docs/i18n/formatting) for CLDR plural selection and the `Intl`-backed date / number / relative-time hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
@@ -951,7 +951,7 @@ default, so call sites don't handle a missing-service error.
 > request, publishes it on the document, and every `@voltro/i18n` formatter on
 > both sides of the hydration boundary uses it. Read it with `useTimeZone()`
 > from `@voltro/i18n`. See
-> [Formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr--the-setting-that-is-not-a-preference).
+> [Formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr-the-setting-that-is-not-a-preference).
 >
 > The **server-side compute zone** — what `startOfDay` or a workflow's "same
 > time tomorrow" resolves against inside a handler — is still the SEAM only.

package/templates/agent-docs/introduction.md CHANGED Viewed

@@ -505,7 +505,7 @@ export default defineWebSocket({
 })
 ```
-`auth: 'subject'` authenticates through the same chain as rpc/SSR **before** the upgrade (401 while it is still http) and binds the connection to the credential's expiry (close code `4001`); every gateway path is origin-checked at upgrade. Two gateways on one path refuse the boot; a plain GET on a gateway path answers `426`. App realtime stays [subscriptions](/docs/data/subscriptions) — full detail under [Raw WebSocket gateways](/docs/data/subscriptions#raw-websocket-gateways--definewebsocket).
+`auth: 'subject'` authenticates through the same chain as rpc/SSR **before** the upgrade (401 while it is still http) and binds the connection to the credential's expiry (close code `4001`); every gateway path is origin-checked at upgrade. Two gateways on one path refuse the boot; a plain GET on a gateway path answers `426`. App realtime stays [subscriptions](/docs/data/subscriptions) — full detail under [Raw WebSocket gateways](/docs/data/subscriptions#raw-websocket-gateways-definewebsocket).
 ## The web side (`apps/*/web/`)
@@ -518,6 +518,10 @@ export default defineWebSocket({
 | `src/pages/loading.tsx` | Pending UI shown while loaders resolve. |
 | `src/pages/(group)/` | Route group — does not contribute a URL segment, but layout/error files inside still apply. |
 | `src/*.island.tsx` | A client-side hydration island (split chunk). Used in `interactive: 'islands'` pages. |
+| `src/**/*.collection.ts` | A content collection declaration (`defineCollection`) — schema-typed markdown/JSON under `content/<name>/**`. See [Content collections](/docs/data/content-collections). |
+| `src/**/*.consumer.ts` | A queue consumer (`defineQueueConsumer`, @voltro/plugin-queue) — Schema-decoded, at-least-once, serial per partition. See [Queue](/docs/plugins/queue). |
+| `grpc.manifest.json` | The gRPC field-number manifest (checked in — append-only wire identity; deletes go `reserved`). See [gRPC surface](/docs/data/grpc). |
+| `content/<name>/**` | A collection's content files (markdown with frontmatter, or `.json` for data collections). Read by `getCollection`/`getEntry`. |
 Each page can opt into a render strategy via two exports:
@@ -599,6 +603,8 @@ If yes, the promise belongs in the name — you cannot see a contract before you
 | `*.tracking.ts` | analytics happens nowhere else | `tracking/outside-tracking-file` |
 | `*.client.ts` | it and its imports are browser-safe | boot-time import walk, `client/not-browser-safe` |
 | `*.store.ts` | exactly one `defineStore`, no server state | `store/one-per-file`, `store/mirrors-server-state` |
+| `*.collection.ts` | declares content collections (`defineCollection`); frontmatter schema violations fail the build naming the file | the build's collection decode + reference validation |
+| `*.consumer.ts` | declares queue consumers (`defineQueueConsumer`, @voltro/plugin-queue); loading registers, the plugin's activation starts them | the queue runner (decode→DLQ, retry→DLQ, commit-per-message) |
 A `*.component.tsx` promises exactly ONE component. It does not promise to export nothing else: types, and plain module-local values a `const COLUMNS = […]` beside the table that renders them, are fine and always were. What the rule counts is components — a declaration that renders — so an object, an array, a string or a `new` beside your component is not a second one, and neither is `export default Card` next to `export const Card`.

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

@@ -29,10 +29,11 @@ imports it directly. The React wrappers live behind `@voltro/local-first/react`
 > [`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.
+> `useCrdtText` is pointed at — and the sync **engine**, which 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`
@@ -315,6 +316,103 @@ const adapter = await createIndexedDbPersistence({ databaseName: 'my-app' })
 const sync = createSyncClient({ transport, adapter }) // state now survives reload
 ```
+## Rich text: `crdtDoc()` + `useCrdtEditor`
+`crdtDoc()` stores a WHOLE collaborative document (rich text, maps, arrays)
+as a column — same storage and authoritative server merge as `crdtText()`,
+which stays as the plain-text specialisation. The editor binding is Tiptap
+(`@voltro/local-first/editor`, optional peers): `useCrdtEditor({ doc })`
+binds one editor to the document handle; content edits ride the app's
+mutation (folded server-side under a per-row mutex) and remote edits arrive
+as incremental `mergeCells` subscription deltas — a one-character edit ships
+under 1 KB in BOTH directions regardless of document size.
+Carets ride a `delivery: 'latest'` EVENT, deliberately not presence
+metadata: the roster's value-compare push would make every caret move a
+"real" change. `attachAwarenessBridge` publishes one member's state per
+envelope (never the aggregated room). Stable positions for inline comments
+come from `encodeAnchor`/`resolveAnchor` on the doc handle.
+Operational rules: the stored blob soft-compacts past
+`VOLTRO_CRDT_COMPACT_MAX_BYTES` (default 512 KiB) without breaking the merge
+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

package/templates/agent-docs/observability.md CHANGED Viewed

@@ -73,6 +73,8 @@ Even with no exporter, `voltro dev` installs a **buffer-only** tracer — that's
 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:
+The **web server** additionally counts [partial prerendering](/docs/routing/render-modes#partial-prerendering-ppr--cached-shell--per-request-holes): shell serves, hole passes/settles/errors, and last/max hole latency. Shell hit-rate is the isr cache's own `x-voltro-cache` HIT/STALE/MISS accounting — a ppr shell is a normal isr entry.
 ```bash
 # OTLP metrics — the SAME OTEL endpoint that enables trace export also enables
 # metrics. Ships to any OTLP/HTTP collector (Prometheus OTLP, Grafana Agent,

package/templates/agent-docs/plugins/auth.md CHANGED Viewed

@@ -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/comments.md ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.