@voltro/cli 0.52.0 → 0.53.0

package/dist/{webhooksCommand-CoIO3jbj.js → webhooksCommand-4SVPDjKg.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-GjJWAYo2.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.52.0",
+  "version": "0.53.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.53.0",
+    "@voltro/cache": "0.53.0",
+    "@voltro/client": "0.53.0",
+    "@voltro/content": "0.53.0",
+    "@voltro/data-transfer": "0.53.0",
+    "@voltro/database": "0.53.0",
+    "@voltro/env": "0.53.0",
+    "@voltro/kv": "0.53.0",
+    "@voltro/logger": "0.53.0",
+    "@voltro/plugin-auth": "0.53.0",
+    "@voltro/plugin-broadcast": "0.53.0",
+    "@voltro/plugin-mail": "0.53.0",
+    "@voltro/plugin-storage": "0.53.0",
+    "@voltro/plugin-webhooks": "0.53.0",
+    "@voltro/protocol": "0.53.0",
+    "@voltro/runtime": "0.53.0",
+    "@voltro/serverless": "0.53.0",
+    "@voltro/workflow": "0.53.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.md

@@ -728,7 +728,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.53.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. |
@@ -788,6 +788,7 @@ each plugin's own README.
 | 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. |
 | 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 +799,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.53.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. |
@@ -69,6 +69,7 @@ each plugin's own README.
 | 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. |
 | 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",
@@ -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

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

package/templates/agent-docs/cli.md

@@ -29,7 +29,7 @@ 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) |
 | Harness | `test`, `e2e` |
@@ -147,7 +147,7 @@ config value always winning:
 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.
 

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