@voltro/cli 0.52.0 → 0.54.0

package/dist/webDev-DlvZO30c.js

@@ -0,0 +1,2 @@
+import { p as e, x as t, y as n } from "./webDev-DSI9SOhs.js";
+export { e as loadConfig, n as tryRunWebServe, t as walkPagesTree };

package/dist/{webhooksCommand-CoIO3jbj.js → webhooksCommand-BvzXNHji.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev--A3nsxA3.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-cKUiZZsB.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
 	return r((await n(await t(e))).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor

package/dist/workspaceDeps-RKEkX92S.js

@@ -0,0 +1,45 @@
+import { dirname as e, join as t } from "node:path";
+import { promises as n } from "node:fs";
+//#region src/workspaceDeps.ts
+var r = async (r, i) => {
+	let a = r;
+	for (;;) {
+		let r = t(a, "node_modules", i);
+		try {
+			if ((await n.stat(r)).isDirectory()) {
+				let e = await n.realpath(r);
+				return e.includes("/node_modules/") ? null : e;
+			}
+		} catch {}
+		let o = e(a);
+		if (o === a) return null;
+		a = o;
+	}
+}, i = async (e) => {
+	let i;
+	try {
+		let r = await n.readFile(t(e, "package.json"), "utf8"), a = JSON.parse(r);
+		i = Object.keys({
+			...a.dependencies,
+			...a.devDependencies
+		});
+	} catch {
+		return [];
+	}
+	return (await Promise.all(i.map(async (i) => {
+		let a = await r(e, i);
+		if (a === null) return null;
+		let o = t(a, "src");
+		try {
+			if (!(await n.stat(o)).isDirectory()) return null;
+		} catch {
+			return null;
+		}
+		return {
+			pkg: i,
+			dir: o
+		};
+	}))).filter((e) => e !== null);
+};
+//#endregion
+export { i as n, r as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -730,6 +730,30 @@
         "title": "A throwing `onHttpRequest` interceptor now refuses the request (500) instead of being ignored",
         "kind": "manual"
       },
+      {
+        "version": "0.53.0",
+        "id": "0.53.0/01_conflict-columns-take-the-table",
+        "title": "`missingConflictColumns` takes the table and classifies absent vs NULL",
+        "kind": "manual"
+      },
+      {
+        "version": "0.53.0",
+        "id": "0.53.0/02_empty-struct-input-flipped",
+        "title": "`input: Schema.Struct({})` procedures flipped from accept-everything to reject-everything in 0.37.0",
+        "kind": "manual"
+      },
+      {
+        "version": "0.53.0",
+        "id": "0.53.0/03_validation-messages-are-ids",
+        "title": "Form validation messages are ids + catalog now, not effect developer text",
+        "kind": "manual"
+      },
+      {
+        "version": "0.53.0",
+        "id": "0.53.0/04_widget-kind-gained-array",
+        "title": "WidgetKind gained 'array' and 'reference' — total widget registries need two new entries",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -796,6 +820,13 @@
         "title": "A `renderMode:'spa'` page under a layout now server-renders that layout",
         "kind": "manual"
       }
+    ],
+    "renames": [
+      {
+        "at": "0.52.0",
+        "from": "@voltro/plugin-versioning",
+        "to": "@voltro/plugin-row-history"
+      }
     ]
   },
   "engines": {
@@ -805,35 +836,45 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.52.0",
-    "@voltro/cache": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/data-transfer": "0.52.0",
-    "@voltro/database": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/kv": "0.52.0",
-    "@voltro/logger": "0.52.0",
-    "@voltro/plugin-auth": "0.52.0",
-    "@voltro/plugin-broadcast": "0.52.0",
-    "@voltro/plugin-mail": "0.52.0",
-    "@voltro/plugin-storage": "0.52.0",
-    "@voltro/plugin-webhooks": "0.52.0",
-    "@voltro/protocol": "0.52.0",
-    "@voltro/runtime": "0.52.0",
-    "@voltro/serverless": "0.52.0",
-    "@voltro/workflow": "0.52.0",
+    "@voltro/ai": "0.54.0",
+    "@voltro/cache": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/content": "0.54.0",
+    "@voltro/data-transfer": "0.54.0",
+    "@voltro/database": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/kv": "0.54.0",
+    "@voltro/logger": "0.54.0",
+    "@voltro/plugin-auth": "0.54.0",
+    "@voltro/plugin-broadcast": "0.54.0",
+    "@voltro/plugin-mail": "0.54.0",
+    "@voltro/plugin-storage": "0.54.0",
+    "@voltro/plugin-webhooks": "0.54.0",
+    "@voltro/protocol": "0.54.0",
+    "@voltro/runtime": "0.54.0",
+    "@voltro/serverless": "0.54.0",
+    "@voltro/workflow": "0.54.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",
     "ts-morph": "^28.0.0"
   },
   "optionalDependencies": {
+    "@resvg/resvg-js": "^2.6.2",
     "@tailwindcss/vite": "^4.3.3",
     "@vercel/nft": "^1.10.2",
     "@vitejs/plugin-react": "^6.0.5",
     "esbuild": "^0.28.2",
+    "fontkit": "^2.0.4",
+    "satori": "0.29.0",
+    "sharp": "^0.35.3",
+    "subset-font": "^2.5.0",
     "tsx": "^4.23.12",
-    "vite": "^8.2.1"
+    "vite": "^8.2.1",
+    "@grpc/grpc-js": "^1.12.6",
+    "@grpc/reflection": "^1.0.4",
+    "grpc-health-check": "^2.0.2",
+    "@grpc/proto-loader": "^0.7.13"
   },
   "peerDependencies": {
     "@effect/platform": "^0.97.0",

package/templates/AGENTS.core.md

@@ -368,6 +368,8 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
+| `*.collection.ts` | content collection (`defineCollection`) — schema-typed markdown/JSON |
+| `content/<name>/**` | that collection's files (markdown + frontmatter, or `.json`) |
 | `page.tsx` (under `src/pages/`) | the route its DIRECTORY serves + `page.test.tsx` |
 | `*.component.tsx` | exactly ONE component (+ types) |
 | `*.component.ui.tsx` | presentational: one component, READS only — never writes |

package/templates/AGENTS.md

@@ -368,6 +368,8 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
+| `*.collection.ts` | content collection (`defineCollection`) — schema-typed markdown/JSON |
+| `content/<name>/**` | that collection's files (markdown + frontmatter, or `.json`) |
 | `page.tsx` (under `src/pages/`) | the route its DIRECTORY serves + `page.test.tsx` |
 | `*.component.tsx` | exactly ONE component (+ types) |
 | `*.component.ui.tsx` | presentational: one component, READS only — never writes |
@@ -728,7 +730,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.52.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.54.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |
@@ -786,8 +788,9 @@ each plugin's own README.
 | auth-workos | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-workos.md` (or `node_modules/@voltro/plugin-auth-workos/README.md`) | WorkOS AuthStrategy — verifies WorkOS AuthKit / SSO JWTs via JWKS (no API key) and maps org_id → tenantId. |
 | billing | `node_modules/@voltro/cli/templates/agent-docs/plugins/billing.md` (or `node_modules/@voltro/plugin-billing/README.md`) | Subscriptions, plans, entitlements, and usage metering over a pluggable provider (Stripe + mock). Money is integer minor units. |
 | broadcast | `node_modules/@voltro/cli/templates/agent-docs/plugins/broadcast.md` (or `node_modules/@voltro/plugin-broadcast/README.md`) | Cross-replica reactivity over a pub/sub bus (Redis / NATS) for non-postgres dialects — closes the single-instance gap so a write on one pod surfaces on another. |
-| cdc-out | `node_modules/@voltro/cli/templates/agent-docs/plugins/cdc-out.md` (or `node_modules/@voltro/plugin-cdc-out/README.md`) | Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. |
+| cdc-out | `node_modules/@voltro/cli/templates/agent-docs/plugins/cdc-out.md` (or `node_modules/@voltro/plugin-cdc-out/README.md`) | Declaratively mirror table changes outward to external sinks (webhook, Kafka, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. |
 | clickhouse | `node_modules/@voltro/cli/templates/agent-docs/plugins/clickhouse.md` (or `node_modules/@voltro/plugin-clickhouse/README.md`) | Production-grade OLAP AnalyticsSink over ClickHouse — self-hosted or ClickHouse Cloud — for billions of events with millisecond aggregates. |
+| comments | `node_modules/@voltro/cli/templates/agent-docs/plugins/comments.md` (or `node_modules/@voltro/plugin-comments/README.md`) | 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. |
 | datadog | `node_modules/@voltro/cli/templates/agent-docs/plugins/datadog.md` (or `node_modules/@voltro/plugin-datadog/README.md`) | Agentless Datadog metrics exporter — pushes the unified Metrics-API to Datadog's /api/v2/series HTTP intake. |
 | deactivation | `node_modules/@voltro/cli/templates/agent-docs/plugins/deactivation.md` (or `node_modules/@voltro/plugin-deactivation/README.md`) | A schema mixin that marks a subject as deactivated (can't log in) while keeping its data fully visible — the deliberate opposite of soft-delete. |
 | duckdb | `node_modules/@voltro/cli/templates/agent-docs/plugins/duckdb.md` (or `node_modules/@voltro/plugin-duckdb/README.md`) | Embedded DuckDB AnalyticsSink — real column-store OLAP in-process, no external service to run. |
@@ -798,12 +801,13 @@ each plugin's own README.
 | mail | `node_modules/@voltro/cli/templates/agent-docs/plugins/mail.md` (or `node_modules/@voltro/plugin-mail/README.md`) | Transactional email — Resend / Postmark / SendGrid / SMTP, React-Email templates with auto-discovery, per-tenant suppression, bounce/complaint handling, durable delivery via workflows. |
 | moderation | `node_modules/@voltro/cli/templates/agent-docs/plugins/moderation.md` (or `node_modules/@voltro/plugin-moderation/README.md`) | Moderate user content before it commits — keyword denylist or AI provider, block or flag via rpc interceptor, plus an in-handler redact helper. |
 | multitenancy | `node_modules/@voltro/cli/templates/agent-docs/plugins/multitenancy.md` (or `node_modules/@voltro/plugin-multitenancy/README.md`) | The tenant() schema mixin (auto-scoped reads, auto-filled inserts, tenant-resolved keyed writes), the assertOwnTenant write-guard, and the typed TenantMismatch error. |
-| notifications | `node_modules/@voltro/cli/templates/agent-docs/plugins/notifications.md` (or `node_modules/@voltro/plugin-notifications/README.md`) | Unified notifications — one send API across email / Slack / SMS / push / in-app, with per-user channel preferences, an in-app inbox, and delivery records. |
+| notifications | `node_modules/@voltro/cli/templates/agent-docs/plugins/notifications.md` (or `node_modules/@voltro/plugin-notifications/README.md`) | 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. |
 | openapi | `node_modules/@voltro/cli/templates/agent-docs/plugins/openapi.md` (or `node_modules/@voltro/plugin-openapi/README.md`) | Generate an OpenAPI 3.1 spec + Swagger-UI docs from your defineRestRoute descriptors and (opt-in) your rpc procedures. Your routes ARE the API docs — nothing hand-maintained. |
 | postgis | `node_modules/@voltro/cli/templates/agent-docs/plugins/postgis.md` (or `node_modules/@voltro/plugin-postgis/README.md`) | Postgres-native geography / geometry columns, geometry constructors (point/line/polygon/multi/GeoJSON), spatial predicates (ST_DWithin, ST_Within, ST_Contains, ST_Intersects, ST_Buffer, bbox &&), ST_Distance projection + <-> KNN ordering, and GiST indexes via expressionIndex. Postgres-only by design. |
 | posthog | `node_modules/@voltro/cli/templates/agent-docs/plugins/posthog.md` (or `node_modules/@voltro/plugin-posthog/README.md`) | Track-only AnalyticsSink that forwards events to PostHog's /capture endpoint — compose it with a second sink that owns reads. |
-| presence | `node_modules/@voltro/cli/templates/agent-docs/plugins/presence.md` (or `node_modules/@voltro/plugin-presence/README.md`) | Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor). Works cross-instance. |
+| presence | `node_modules/@voltro/cli/templates/agent-docs/plugins/presence.md` (or `node_modules/@voltro/plugin-presence/README.md`) | 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. |
 | prometheus | `node_modules/@voltro/cli/templates/agent-docs/plugins/prometheus.md` (or `node_modules/@voltro/plugin-prometheus/README.md`) | Prometheus exporter — scrapes the unified Metrics-API at GET /metrics in text exposition format. |
+| queue | `node_modules/@voltro/cli/templates/agent-docs/plugins/queue.md` (or `node_modules/@voltro/plugin-queue/README.md`) | 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. |
 | ratelimit | `node_modules/@voltro/cli/templates/agent-docs/plugins/ratelimit.md` (or `node_modules/@voltro/plugin-ratelimit/README.md`) | Per-endpoint, per-subject and per-tenant request limits via the rpc interceptors. Sliding-window / fixed-window / token-bucket, memory / postgres / redis stores. |
 | rbac | `node_modules/@voltro/cli/templates/agent-docs/plugins/rbac.md` (or `node_modules/@voltro/plugin-rbac/README.md`) | Roles + permissions + the permission() handler guard. Roles compile to scopes. |
 | row-history | `node_modules/@voltro/cli/templates/agent-docs/plugins/row-history.md` (or `node_modules/@voltro/plugin-row-history/README.md`) | 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. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.52.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.54.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |
@@ -67,8 +67,9 @@ each plugin's own README.
 | auth-workos | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-workos.md` (or `node_modules/@voltro/plugin-auth-workos/README.md`) | WorkOS AuthStrategy — verifies WorkOS AuthKit / SSO JWTs via JWKS (no API key) and maps org_id → tenantId. |
 | billing | `node_modules/@voltro/cli/templates/agent-docs/plugins/billing.md` (or `node_modules/@voltro/plugin-billing/README.md`) | Subscriptions, plans, entitlements, and usage metering over a pluggable provider (Stripe + mock). Money is integer minor units. |
 | broadcast | `node_modules/@voltro/cli/templates/agent-docs/plugins/broadcast.md` (or `node_modules/@voltro/plugin-broadcast/README.md`) | Cross-replica reactivity over a pub/sub bus (Redis / NATS) for non-postgres dialects — closes the single-instance gap so a write on one pod surfaces on another. |
-| cdc-out | `node_modules/@voltro/cli/templates/agent-docs/plugins/cdc-out.md` (or `node_modules/@voltro/plugin-cdc-out/README.md`) | Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. |
+| cdc-out | `node_modules/@voltro/cli/templates/agent-docs/plugins/cdc-out.md` (or `node_modules/@voltro/plugin-cdc-out/README.md`) | Declaratively mirror table changes outward to external sinks (webhook, Kafka, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. |
 | clickhouse | `node_modules/@voltro/cli/templates/agent-docs/plugins/clickhouse.md` (or `node_modules/@voltro/plugin-clickhouse/README.md`) | Production-grade OLAP AnalyticsSink over ClickHouse — self-hosted or ClickHouse Cloud — for billions of events with millisecond aggregates. |
+| comments | `node_modules/@voltro/cli/templates/agent-docs/plugins/comments.md` (or `node_modules/@voltro/plugin-comments/README.md`) | 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. |
 | datadog | `node_modules/@voltro/cli/templates/agent-docs/plugins/datadog.md` (or `node_modules/@voltro/plugin-datadog/README.md`) | Agentless Datadog metrics exporter — pushes the unified Metrics-API to Datadog's /api/v2/series HTTP intake. |
 | deactivation | `node_modules/@voltro/cli/templates/agent-docs/plugins/deactivation.md` (or `node_modules/@voltro/plugin-deactivation/README.md`) | A schema mixin that marks a subject as deactivated (can't log in) while keeping its data fully visible — the deliberate opposite of soft-delete. |
 | duckdb | `node_modules/@voltro/cli/templates/agent-docs/plugins/duckdb.md` (or `node_modules/@voltro/plugin-duckdb/README.md`) | Embedded DuckDB AnalyticsSink — real column-store OLAP in-process, no external service to run. |
@@ -79,12 +80,13 @@ each plugin's own README.
 | mail | `node_modules/@voltro/cli/templates/agent-docs/plugins/mail.md` (or `node_modules/@voltro/plugin-mail/README.md`) | Transactional email — Resend / Postmark / SendGrid / SMTP, React-Email templates with auto-discovery, per-tenant suppression, bounce/complaint handling, durable delivery via workflows. |
 | moderation | `node_modules/@voltro/cli/templates/agent-docs/plugins/moderation.md` (or `node_modules/@voltro/plugin-moderation/README.md`) | Moderate user content before it commits — keyword denylist or AI provider, block or flag via rpc interceptor, plus an in-handler redact helper. |
 | multitenancy | `node_modules/@voltro/cli/templates/agent-docs/plugins/multitenancy.md` (or `node_modules/@voltro/plugin-multitenancy/README.md`) | The tenant() schema mixin (auto-scoped reads, auto-filled inserts, tenant-resolved keyed writes), the assertOwnTenant write-guard, and the typed TenantMismatch error. |
-| notifications | `node_modules/@voltro/cli/templates/agent-docs/plugins/notifications.md` (or `node_modules/@voltro/plugin-notifications/README.md`) | Unified notifications — one send API across email / Slack / SMS / push / in-app, with per-user channel preferences, an in-app inbox, and delivery records. |
+| notifications | `node_modules/@voltro/cli/templates/agent-docs/plugins/notifications.md` (or `node_modules/@voltro/plugin-notifications/README.md`) | 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. |
 | openapi | `node_modules/@voltro/cli/templates/agent-docs/plugins/openapi.md` (or `node_modules/@voltro/plugin-openapi/README.md`) | Generate an OpenAPI 3.1 spec + Swagger-UI docs from your defineRestRoute descriptors and (opt-in) your rpc procedures. Your routes ARE the API docs — nothing hand-maintained. |
 | postgis | `node_modules/@voltro/cli/templates/agent-docs/plugins/postgis.md` (or `node_modules/@voltro/plugin-postgis/README.md`) | Postgres-native geography / geometry columns, geometry constructors (point/line/polygon/multi/GeoJSON), spatial predicates (ST_DWithin, ST_Within, ST_Contains, ST_Intersects, ST_Buffer, bbox &&), ST_Distance projection + <-> KNN ordering, and GiST indexes via expressionIndex. Postgres-only by design. |
 | posthog | `node_modules/@voltro/cli/templates/agent-docs/plugins/posthog.md` (or `node_modules/@voltro/plugin-posthog/README.md`) | Track-only AnalyticsSink that forwards events to PostHog's /capture endpoint — compose it with a second sink that owns reads. |
-| presence | `node_modules/@voltro/cli/templates/agent-docs/plugins/presence.md` (or `node_modules/@voltro/plugin-presence/README.md`) | Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor). Works cross-instance. |
+| presence | `node_modules/@voltro/cli/templates/agent-docs/plugins/presence.md` (or `node_modules/@voltro/plugin-presence/README.md`) | 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. |
 | prometheus | `node_modules/@voltro/cli/templates/agent-docs/plugins/prometheus.md` (or `node_modules/@voltro/plugin-prometheus/README.md`) | Prometheus exporter — scrapes the unified Metrics-API at GET /metrics in text exposition format. |
+| queue | `node_modules/@voltro/cli/templates/agent-docs/plugins/queue.md` (or `node_modules/@voltro/plugin-queue/README.md`) | 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. |
 | ratelimit | `node_modules/@voltro/cli/templates/agent-docs/plugins/ratelimit.md` (or `node_modules/@voltro/plugin-ratelimit/README.md`) | Per-endpoint, per-subject and per-tenant request limits via the rpc interceptors. Sliding-window / fixed-window / token-bucket, memory / postgres / redis stores. |
 | rbac | `node_modules/@voltro/cli/templates/agent-docs/plugins/rbac.md` (or `node_modules/@voltro/plugin-rbac/README.md`) | Roles + permissions + the permission() handler guard. Roles compile to scopes. |
 | row-history | `node_modules/@voltro/cli/templates/agent-docs/plugins/row-history.md` (or `node_modules/@voltro/plugin-row-history/README.md`) | 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. |

package/templates/agent-docs/_manifest.json

@@ -53,7 +53,7 @@
       "group": null,
       "description": "How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.",
       "path": "agent-docs/data.md",
-      "files": 19
+      "files": 21
     },
     {
       "id": "database/advancedqueries",
@@ -242,7 +242,7 @@
       "group": null,
       "description": "Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework.",
       "path": "agent-docs/routing.md",
-      "files": 9
+      "files": 13
     },
     {
       "id": "scheduling",
@@ -460,7 +460,7 @@
     {
       "slug": "cdc-out",
       "title": "CDC-out (reverse-ETL)",
-      "description": "Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.",
+      "description": "Declaratively mirror table changes outward to external sinks (webhook, Kafka, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.",
       "pkg": "@voltro/plugin-cdc-out",
       "doc": "plugins/cdc-out.md",
       "module": "agent-docs/plugins/cdc-out.md"
@@ -473,6 +473,14 @@
       "doc": "plugins/clickhouse.md",
       "module": "agent-docs/plugins/clickhouse.md"
     },
+    {
+      "slug": "comments",
+      "title": "Comments",
+      "description": "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.",
+      "pkg": "@voltro/plugin-comments",
+      "doc": "plugins/comments.md",
+      "module": "agent-docs/plugins/comments.md"
+    },
     {
       "slug": "datadog",
       "title": "Datadog",
@@ -556,7 +564,7 @@
     {
       "slug": "notifications",
       "title": "Notifications",
-      "description": "Unified notifications — one send API across email / Slack / SMS / push / in-app, with per-user channel preferences, an in-app inbox, and delivery records.",
+      "description": "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.",
       "pkg": "@voltro/plugin-notifications",
       "doc": "plugins/notifications.md",
       "module": "agent-docs/plugins/notifications.md"
@@ -588,7 +596,7 @@
     {
       "slug": "presence",
       "title": "Presence",
-      "description": "Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor). Works cross-instance.",
+      "description": "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.",
       "pkg": "@voltro/plugin-presence",
       "doc": "plugins/presence.md",
       "module": "agent-docs/plugins/presence.md"
@@ -601,6 +609,14 @@
       "doc": "plugins/prometheus.md",
       "module": "agent-docs/plugins/prometheus.md"
     },
+    {
+      "slug": "queue",
+      "title": "Queue (Kafka interop)",
+      "description": "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.",
+      "pkg": "@voltro/plugin-queue",
+      "doc": "plugins/queue.md",
+      "module": "agent-docs/plugins/queue.md"
+    },
     {
       "slug": "ratelimit",
       "title": "Rate limiting",

package/templates/agent-docs/ai.md

@@ -116,7 +116,7 @@ Env vars `providerFromEnv()` reads:
 | `AI_PROVIDER` | `mock` | `mock` \| `anthropic` \| `openai` \| `gateway`. |
 | `AI_MODEL` | per provider (see below) | Override the model. Defaults: `claude-opus-4-8` (anthropic), `gpt-5.5` (openai), `mock` (mock). **REQUIRED for `gateway`** — a `creator/model` id; boot throws if unset. |
 
-Provider API keys are read by the underlying `@ai-sdk/*` packages from their standard env vars — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AI_GATEWAY_API_KEY`. The framework doesn't read a separate `AI_API_KEY`. (To give a SINGLE agent its own key from code instead of env, see [Per-config key + base URL](#per-config-key--base-url) below.)
+Provider API keys are read by the underlying `@ai-sdk/*` packages from their standard env vars — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AI_GATEWAY_API_KEY`. The framework doesn't read a separate `AI_API_KEY`. (To give a SINGLE agent its own key from code instead of env, see [Per-config key + base URL](#per-config-key-base-url) below.)
 
 ## Anthropic
 
@@ -141,7 +141,7 @@ AI_MODEL=gpt-5.5
 OPENAI_API_KEY=sk-…
 ```
 
-Backed by `@ai-sdk/openai`. `AI_MODEL` is a plain OpenAI model id (`gpt-5.5`, `gpt-4o-mini`, …). For a self-hosted / Azure-style / proxy endpoint, set `baseURL` on a `ProviderConfig` (see [Per-config key + base URL](#per-config-key--base-url)) rather than an env var.
+Backed by `@ai-sdk/openai`. `AI_MODEL` is a plain OpenAI model id (`gpt-5.5`, `gpt-4o-mini`, …). For a self-hosted / Azure-style / proxy endpoint, set `baseURL` on a `ProviderConfig` (see [Per-config key + base URL](#per-config-key-base-url)) rather than an env var.
 
 ## Vercel AI Gateway
 
@@ -184,7 +184,7 @@ const r = yield* generateText({
 })
 ```
 
-This is the mechanism behind **per-agent keys** and **BYOK** (bring-your-own-key): a `defineAgentExecutor` can carry a static `model: { name, model, apiKey }`, OR a `model: (input) => ({ …, apiKey: input.apiKey })` function that derives the key from the request. The key stays server-side (the executor file never reaches the browser) and is NOT persisted — only the prompt is stored in `agent_messages`. The full pattern (dynamic model picker, cost/tier routing, BYOK, and the security footguns) lives in [Agents → Per-agent model + key](/docs/ai/agents#per-agent-model--key).
+This is the mechanism behind **per-agent keys** and **BYOK** (bring-your-own-key): a `defineAgentExecutor` can carry a static `model: { name, model, apiKey }`, OR a `model: (input) => ({ …, apiKey: input.apiKey })` function that derives the key from the request. The key stays server-side (the executor file never reaches the browser) and is NOT persisted — only the prompt is stored in `agent_messages`. The full pattern (dynamic model picker, cost/tier routing, BYOK, and the security footguns) lives in [Agents → Per-agent model + key](/docs/ai/agents#per-agent-model-key).
 
 ## Mock (for tests)
 
@@ -239,7 +239,7 @@ export default (input: { prompt: string }) =>
   })
 ```
 
-`GenerateTextOptions` is `{ prompt, system?, provider?, fallbacks?, maxTokens? }`. There is no `messages`/`effort` shape — the prompt is a single string the SDK wraps as the user turn; `system` steers it. `fallbacks` is a [provider fallback chain](#fallback-chain--survive-a-provider-outage).
+`GenerateTextOptions` is `{ prompt, system?, provider?, fallbacks?, maxTokens? }`. There is no `messages`/`effort` shape — the prompt is a single string the SDK wraps as the user turn; `system` steers it. `fallbacks` is a [provider fallback chain](#fallback-chain-survive-a-provider-outage).
 
 Structured output:
 
@@ -276,7 +276,7 @@ type ProviderConfig =
   | { name: 'gateway';   model: `${string}/${string}`; apiKey?: string; baseURL?: string }  // creator/model
 ```
 
-The mock-only `mockText` / `script` can't appear on a real provider (the type rejects it), the gateway's `model` is a `creator/model`-typed string (a bare `'gpt-5.5'` is a compile error, not a boot crash), and the per-provider model-id types (`AnthropicModel` / `OpenAIModel`) are **open unions** — known ids autocomplete, but any string the provider ships tomorrow still type-checks. Use `provider` for per-request model selection (e.g. a cheaper model on a fallback path), or to pin a specific key/endpoint (see [Per-config key + base URL](#per-config-key--base-url)).
+The mock-only `mockText` / `script` can't appear on a real provider (the type rejects it), the gateway's `model` is a `creator/model`-typed string (a bare `'gpt-5.5'` is a compile error, not a boot crash), and the per-provider model-id types (`AnthropicModel` / `OpenAIModel`) are **open unions** — known ids autocomplete, but any string the provider ships tomorrow still type-checks. Use `provider` for per-request model selection (e.g. a cheaper model on a fallback path), or to pin a specific key/endpoint (see [Per-config key + base URL](#per-config-key-base-url)).
 
 For runtime provider switching across a whole layer, bind an `AiServiceImpl` to the `AiService` Context tag at boot and read it with `yield* AiService` — `defaultAiService` (backed by `providerFromEnv`) is the default.
 
@@ -648,7 +648,7 @@ const { data: messages } = useSubscription('app', 'chat.messages', { threadId })
 const send = useAction('app', 'chat.send')
 ```
 
-The `agent_messages` row carries `streaming` (live typewriter flag), `order` (thread position), `stepOrder` (sub-position within a turn, for LLM↔tool steps), and `parts` (the structured `text` + `tool` payload the feed renders). Both `agent_threads` and `agent_messages` are tenant-scoped — the active org id is stamped on every row. Full worked example in [Streaming](/docs/ai/streaming#streaming-deltas-through-a-reactive-query-persisted-no-raw-socket).
+The `agent_messages` row carries `streaming` (live typewriter flag), `order` (thread position), `stepOrder` (sub-position within a turn, for LLM↔tool steps), and `parts` (the structured `text` + `tool` payload the feed renders). Both `agent_threads` and `agent_messages` are tenant-scoped — the active org id is stamped on every row. Full worked example in [Streaming](/docs/ai/streaming).
 
 ## Constraining responses (JSON, schema)
 

package/templates/agent-docs/authentication.md

@@ -2027,7 +2027,7 @@ Multi-key rotation ships. Set the new secret as `VOLTRO_SESSION_SECRET` and move
 ## What the framework does NOT defend against
 
 - **Server-side bugs that leak the cookie value** (e.g. logging `req.headers.cookie` to an aggregator). Audit your logging pipeline.
-- **Compromised user device.** A keylogger on a user's machine sees the password. TOTP/MFA enrolment ships today (see [HTTP handlers](/docs/authentication/handlers#mfa--totp-handlers-shipped)); passkeys ship too (phishing-resistant, no shared secret to keylog — see the [auth plugin overview](/docs/plugins/auth#passkeys--webauthn)). Ultimately devices have to be trusted.
+- **Compromised user device.** A keylogger on a user's machine sees the password. TOTP/MFA enrolment ships today (see [HTTP handlers](/docs/authentication/handlers#mfa-totp-handlers-shipped)); passkeys ship too (phishing-resistant, no shared secret to keylog — see the [auth plugin overview](/docs/plugins/auth#passkeys-webauthn)). Ultimately devices have to be trusted.
 - **Compromised provider.** If your secrets manager leaks `AUTH_SECRET`, every session is forgeable. Rotate immediately + invalidate every session.
 - **Phishing.** A user signing in on an attacker-controlled site → attacker has the cookie. Defence is browser-level (SSL pinning, password managers refusing to autofill on wrong domain). Passkeys help here directly: WebAuthn binds the credential to the origin, so an assertion produced on a phishing domain fails the origin/rpId check server-side.
 
@@ -2602,6 +2602,78 @@ A membership that ends mid-subscription therefore stops serving rows — the
 caller's open ticket list drops the rows they can no longer see, without a
 refresh and without the subscription having to be torn down.
 
+**On every transport, and that list is complete: the WebSocket, an [SSE
+stream](/docs/data/rest-routes#live-updates-over-http-stream-sse), and a
+[gRPC](/docs/data/grpc) server-streaming rpc.** All three open their
+subscription through the same code and resolve the filter per delivery, so
+"stays open for hours" never becomes a way to hold a stale predicate. The same
+delivery also re-checks the query's `guards:`; a filter resolution that FAILS
+revokes the subscription on all three rather than falling back to an unfiltered
+or empty read.
+
+## Declare which tables it narrows — `tables:`
+
+Optional, one line, and it buys back a feature the filter otherwise switches
+off for the whole app:
+
+```ts
+setRowFilter({
+  load,
+  predicate,
+  tables: ['bookmarks', 'recentSearches', 'todoSchedules', 'todoTags'],
+})
+```
+
+**What it buys.** [Delta-resume](/docs/data/wire-protocol#reconnect-delta-resume)
+is excluded for a subscription whose row set is re-resolved per delivery —
+replaying deltas could serve rows the subject has since lost. Without a
+declaration the framework cannot tell which tables your predicate may reach, so
+it excludes them all: one registration disables cheap reconnects for every
+subscription in the process. A deployment measured a filter over 4 tables
+costing it on all 173 of their query descriptors, 55 of whose source tables the
+filter never touches. With the declaration, only subscriptions on the listed
+tables are excluded.
+
+**Why a declaration and not a probe.** Resolving the scope at subscribe time
+and treating "returns `undefined` for this table" as safe is cheaper and
+unsound: your predicate is a function of freshly loaded context, so a table it
+does not narrow now may be narrowed on the next delivery — which is the entire
+reason the filter is re-resolved per delivery. A static list is a promise about
+every future resolution.
+
+**It is verified, not trusted.** Returning a predicate for a table outside the
+list raises `RowFilterDeclarationViolated` at the read that did it — the
+request fails and a subscription is revoked. A declaration nobody checks is a
+comment, and this one is load-bearing: the resume grant is issued on its
+strength. Omit `tables:` entirely and nothing is verified and nothing resumes —
+the conservative default.
+
+## Eager loads are refused, not silently unfiltered
+
+A relation pulled in with `.with(...)` is resolved **below** the seam that
+applies the filter: the stores expand the eager tree themselves (the memory
+store recurses through its own raw read; the SQL stores fold the relation into
+one join). So a filtered table reached through a relation would come back
+unfiltered.
+
+Rather than serve those rows, the read **refuses**, naming the table and both
+ways out:
+
+```
+row filter: 'readers' is reached through an eager load on 'notes', and an eager
+relation is resolved BELOW the row filter — its rows would come back
+unfiltered. Refusing the read rather than serving it.
+  → read 'readers' as its own query (it is filtered there), or
+  → drop 'readers' from this .with(...) if the relation does not need
+    row-level narrowing.
+```
+
+Only relations reaching a table your filter actually narrows are affected —
+every other eager load is untouched. Applying the filter inside eager
+compilation is the real fix and it is a per-dialect change; until then this is
+a refusal rather than a leak, for the same reason the module refuses to
+fail open.
+
 ## Row filters vs. guards
 
 They answer different questions, and a complete policy usually wants both:

package/templates/agent-docs/cli.md

@@ -29,9 +29,10 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 | [Data transfer](/docs/cli/data) | `data` (`export` / `import` / `unpack` / `inspect` / `backup` / `restore`) — directory + single-file `.vbundle` bundles, streaming assets, masking, at-rest encryption |
 | Ops / infra | `cache` (`status` / `flush` / `invalidate`), `add` (`redis`), `baseline` (`list` / `status` / `set`), `schedule` (`run <name>` — fire a registered schedule on demand; `--process` / `--trigger manual\|external` / `--url`), `schedule-manifest`, [`storage`](/docs/plugins/storage) (`doctor` / `cors`) |
 | AI / data | `embeddings backfill <table> --text <field> --vector <field>` — (re)embed rows the `vectorEmbedding()` mixin missed (pre-existing rows / a model change); `--dry-run` to preview; [`eval`](/docs/ai/agents#evaluating-recorded-runs-voltro-eval) — replay recorded agent runs against golden cases + judge, exit 1 on regression (a deploy gate; `--json` / `--branch` / `--threshold`) |
-| Integrate | [`webhooks`](/docs/plugins/webhooks#voltro-webhooks-consumer--the-package-your-subscribers-install) (`consumer` / `events`) — generate the ZERO-dependency Standard-Webhooks verification package your subscribers install, from your own declared events (`--out` / `--name`); list the events a subscriber can register for (`--json`) |
+| Integrate | [`webhooks`](/docs/plugins/webhooks#voltro-webhooks-consumer-the-package-your-subscribers-install) (`consumer` / `events`) — generate the ZERO-dependency Standard-Webhooks verification package your subscribers install, from your own declared events (`--out` / `--name`); list the events a subscriber can register for (`--json`) |
 | [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` |
 | [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled; `info` (`--json`) — CLI / node / package-manager / dialect + every installed `@voltro/*` version, flagging lockstep skew (exits 1 on skew) |
+| Mobile | `mobile` (`codegen` / `links`) — the Expo app's build-time steps: the typed rpc client + deep-link table, and the `apple-app-site-association` / `assetlinks.json` a universal link needs. `voltro codegen` inside a mobile app runs the same generators. |
 | Harness | `test`, `e2e` |
 | Cloud | `cloud` (`login` / `whoami` / `projects` / `env` / `import`); `login` is a top-level alias of `cloud login` |
 | Secrets | `secret` (`generate [purpose]` — the right var+format per secret; `generate` alone → a generic secret; `list`) |
@@ -143,11 +144,13 @@ config value always winning:
 | `VOLTRO_HSTS` | `Strict-Transport-Security` value. `off` drops just this one. |
 | `VOLTRO_MAX_RPC_BODY_BYTES` | Cap on the buffered `POST /rpc` JSON body (default 8 MiB) — an oversized body is refused `413` and never buffered past the cap. File uploads ride plugin routes with their own limits. |
 | `VOLTRO_MAX_BODY_BYTES` | Cap on every OTHER body read — plugin HTTP routes, REST routes, incoming webhooks (default 8 MiB, matching the rpc cap). The config-file spelling is `http.maxBodyBytes` in `app.config.ts`; per-route overrides (`defineRestRoute({ maxBodyBytes })`, a webhook handler's `maxBodyBytes`) win over both. Oversize is `413` for `Content-Length` and chunked alike. |
+| `VOLTRO_CRDT_COMPACT_MAX_BYTES` | Size above which a merged `crdtText()` / `crdtDoc()` blob is soft-compacted (default 512 KiB, `0` disables). The config-file spelling is `crdt.compactMaxBytes` in `app.config.ts`; this variable wins over it. See [local-first](/docs/local-first/overview#rich-text-crdtdoc-usecrdtdoc-usecrdteditor). |
+| `VOLTRO_GRPC_DRAIN_MS` | How long the [gRPC surface](/docs/data/grpc) lets open calls finish on shutdown before force-closing them (default 5000, `0` forces immediately). The config-file spelling is `grpc.drainMs`; this variable wins over it. Keep it below your orchestrator's termination grace. |
 
 Response compression for the buffered non-rpc surfaces (and `voltro start`'s
 HTML) is configured in the same `http:` block — `http.compression.{enabled,minBytes}`
 (default on, 1 KiB threshold; `POST /rpc` is never compressed). Details + the
-BREACH reasoning: [Security → compression](/docs/security/overview#response-compression--and-where-breach-sits).
+BREACH reasoning: [Security → compression](/docs/security/overview#response-compression-and-where-breach-sits).
 
 Generate any of the secret vars above with `voltro secret generate <purpose>` (see [`secret`](#command-quick-reference)) — it picks the right length and format. A lower environment's secrets must always differ from production's.
 
@@ -2031,7 +2034,7 @@ package's README.
 
 _voltro migrate — apply the declared schema through the declarative differ (an alias of voltro db apply)._
 
-`voltro migrate` applies your declared schema (`*.entity.ts` / `*.schema.ts` / `schema.ts`) to the configured database. It is an **alias of [`voltro db apply`](#the-declarative-workflow)**: it diffs the declared schema against the live database and emits the ALTERs, so a changed column or a new index actually lands.
+`voltro migrate` applies your declared schema (`*.entity.ts` / `*.schema.ts` / `schema.ts`) to the configured database. It is an **alias of [`voltro db apply`](#the-declarative-diff-workflow-voltro-db)**: it diffs the declared schema against the live database and emits the ALTERs, so a changed column or a new index actually lands.
 
 > Before 0.11.4 this command was a create-only apply (`CREATE TABLE IF NOT EXISTS`, no diffing), which meant a column or type change reported success having applied **nothing**. If you need that bootstrap-only behaviour for a brand-new database, it is now `voltro migrate --create-only`.
 

package/templates/agent-docs/configuration.md

@@ -126,6 +126,11 @@ just as secret and just as required, but inventing one produces a value that
 merely *looks* right and authenticates nobody — better that the boot gate fails
 and a human fetches the real one.
 
+Encodings: `base64url` and `hex` mint 32 random bytes; `p256` mints a valid
+P-256 private scalar (what web push's `VOLTRO_VAPID_PRIVATE_KEY` needs — a
+plugin can declare its own mintables the same way, which is how a configured
+`webPushChannel()` gets its key without you declaring anything).
+
 Minting is **development only**. `voltro serve`, `build` and `start` never mint:
 in production a missing secret is a boot failure, which is the whole point.
 Generate deployment values with `voltro secret generate <purpose>`.
@@ -302,6 +307,18 @@ This updates what code that reads a secret **per use** sees: outbound API keys r
 `setSecretsBackend(backend)` installs a backend for a test; `resetSecretsBackend()` restores the env default. `resolveSecretsBackend(config)` is the pure resolver the boot path uses to turn the `secrets` config value into a backend.
 
 
+## `VOLTRO_OG_SECRET` — conditional, multi-replica only
+
+The signed on-demand OG-image route (ssr pages exporting
+[`ogImage`](/docs/routing/loaders-and-meta#og-images-from-a-template-ogimage))
+signs its URLs with `VOLTRO_OG_SECRET`. The requirement is CONDITIONAL: a
+single process mints a per-boot secret and is self-consistent — only a
+multi-replica deploy needs the env var (the signing replica and the fetching
+replica differ), and a deploy boot with ssr `ogImage` pages and no secret
+refuses loudly rather than serving images that 403 on every other replica.
+Any long random value; same on every replica; never a default.
+
+
 
 ---