@voltro/cli 0.33.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -376,6 +376,168 @@
         "title": "`CoordinatedScheduleHandle` gained `wake()`, `currentIntervalMs()` and `isArmed()` — update hand-written test doubles",
         "kind": "manual"
       },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/01_serve-does-mount-inspect",
+        "title": "Correction: `voltro serve` DOES mount an inspect surface (the 0.12.0 note said it mounts none)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/02_keyed-writes-are-tenant-scoped",
+        "title": "Keyed-by-pk writes are tenant-enforced, and `crud` refuses `.serverOnly()` input",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/03_procedure-access-decision",
+        "title": "Every wire-exposed procedure declares an access decision (`guards:` or `openAccess:`)",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/04_workos-oauth-state-pkce",
+        "title": "WorkOS hosted login: `workosAuthorizationUrl` → `workosBeginLogin`, with mandatory `state` + PKCE",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/05_analytics-mirror-versioned-writes",
+        "title": "Analytics CDC-mirror: version-ordered writes, tombstoned deletes, retry + repair",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/06_origin-guard-and-trusted-proxies",
+        "title": "Cross-site protection, trusted proxies and security headers are ON by default on the api listener",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/07_incoming-webhook-declares-verification",
+        "title": "An incoming webhook with no signature scheme now refuses to boot",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/08_init-initialises-the-workspace",
+        "title": "`voltro init` initialises the workspace root; scaffolding is `create-project` only",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/09_workflow-messages-queries-removed",
+        "title": "`workflow({ messages: { queries } })` is removed — it never had a send path",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/10_testing-mail-is-a-service",
+        "title": "`ctx.email` / `MockEmail` removed — assert mail through the mail plugin",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/11_ai-flows-per-step-human-signal",
+        "title": "`HUMAN_RESPONSE_SIGNAL` removed — a human step's signal name is now per-step",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/12_session-cookie-carries-identity",
+        "title": "The session cookie carries identity only — authority resolves per request",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/13_billing-provider-dunning",
+        "title": "Billing dunning — `BillingProvider.fetchSubscription` is required, and `plan()` now honours a grace period",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/14_search-memory-backend-refuses-production",
+        "title": "`plugin-search` on the in-memory backend now refuses to boot in production",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/15_mysql-mssql-tls-honoured",
+        "title": "mysql/mariadb and mssql connections honour ?ssl= / ?sslmode= — or refuse to boot",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/16_declare-node-env-for-migration-commands",
+        "title": "`voltro db apply` / `voltro migrate` now treat an unset NODE_ENV as production",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/17_isr-postgres-refuses-without-a-database",
+        "title": "The postgres ISR cache + CDC invalidator read DB_URL, and no longer fall back silently",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/18_serve-refuses-pending-file-migrations",
+        "title": "`voltro serve` refuses to boot with pending file-based migrations",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/19_connection-override-carries-a-credential",
+        "title": "Soft re-auth presents a credential — it no longer hands the server a Subject",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/20_user-store-auth-feature-methods",
+        "title": "UserStore gained the email-verification, invitation and impersonation methods",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/20_workflow-authority-resolves-at-resume",
+        "title": "A resumed workflow re-resolves its caller's authority instead of restoring it",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/21_admin-gates-on-declared-access",
+        "title": "The derived admin gates on the api's DECLARED access — the invented `<table>:create` scopes are gone",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/22_write-rejections-carry-the-typed-error",
+        "title": "A rejected mutate/run/signal/upload carries the typed error, not a FiberFailure",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/23_saml-signature-and-replay-defaults",
+        "title": "SAML: response-signature requirement relaxed + surfaced; replay protection ON by default",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/24_webhook-signing-renders-headers",
+        "title": "Webhook signing: `signPayload`/`verifySignature` → `signRequest`/`verifyRequest`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/25_presence-has-no-table",
+        "title": "Presence: `_voltro_presence` is gone, and so is `lastSeen` on the roster",
+        "kind": "manual"
+      },
+      {
+        "version": "0.34.0",
+        "id": "0.34.0/26_route-http-is-async",
+        "title": "`routeHttp` returns a Promise",
+        "kind": "manual"
+      },
       {
         "version": "0.4.0",
         "id": "0.4.0/01_rbac-forbidden-to-scopeerror",
@@ -475,22 +637,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.33.0",
-    "@voltro/cache": "0.33.0",
-    "@voltro/data-transfer": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/kv": "0.33.0",
-    "@voltro/logger": "0.33.0",
-    "@voltro/plugin-auth": "0.33.0",
-    "@voltro/plugin-broadcast": "0.33.0",
-    "@voltro/plugin-mail": "0.33.0",
-    "@voltro/plugin-storage": "0.33.0",
-    "@voltro/plugin-webhooks": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/serverless": "0.33.0",
-    "@voltro/workflow": "0.33.0",
+    "@voltro/ai": "0.34.0",
+    "@voltro/cache": "0.34.0",
+    "@voltro/data-transfer": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/kv": "0.34.0",
+    "@voltro/logger": "0.34.0",
+    "@voltro/plugin-auth": "0.34.0",
+    "@voltro/plugin-broadcast": "0.34.0",
+    "@voltro/plugin-mail": "0.34.0",
+    "@voltro/plugin-storage": "0.34.0",
+    "@voltro/plugin-webhooks": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
+    "@voltro/serverless": "0.34.0",
+    "@voltro/workflow": "0.34.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -148,7 +148,10 @@ line below replaces something real apps write by hand hundreds of times.
    parameterises it, so one aggregate serves per-team / per-period slices.
 5. **A permission check?** → declare **`guards:`** on the descriptor — it is
    enforced before the executor (and before a mutation's transaction opens) and
-   fails with a typed `ScopeError`. Two kinds, same array, all must pass:
+   fails with a typed `ScopeError`. **This is not optional: a wire-exposed
+   procedure that declares neither `guards:` nor `openAccess:` is REFUSED AT
+   BOOT** (`security.defaultDeny`, on by default). Two kinds, same array, all
+   must pass:
    - `{ scope: 'notes:write' }` — may the caller do this AT ALL.
    - `{ action, resourceType, resource: (input) => input.id }` — may they do it
      to THIS ROW (relationship/ReBAC, against a `defineResourcePolicy`). Needs a
@@ -159,6 +162,13 @@ line below replaces something real apps write by hand hundreds of times.
    in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
    at the top of every executor — or a hand-kept map from rpc tag to policy rule,
    which is fail-open by omission — is what `guards:` exists to delete.
+   **If the procedure really is open to everyone, say so — do not invent a
+   guard.** `openAccess: '<why anyone may call this>'` is the other accepted
+   answer, and the reason is required. Reaching for a scope every caller already
+   holds satisfies the gate, reads as protection, and enforces nothing. A
+   procedure only SERVER code calls wants neither: `internal: true` takes it off
+   the wire entirely (and then `openAccess` is refused — there is no wire to
+   decide about). `voltro doctor` lists every undecided procedure with its file.
 6. **Which ROWS may the caller see** (not: may they make the call)? →
    **`setRowFilter`** — a predicate derived from the Subject, AND-merged into
    EVERY read of that table, including every subscription delivery. `guards:`
@@ -210,6 +220,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
+| a scope every caller holds, added to make a boot gate pass | `openAccess: '<why it is open>'` — the honest spelling |
 | a token/secret column written as plain text | `.encrypted()` |
 | `Effect.promise(() => ctx.store.query(...))` in an Effect handler | `yield* EffectStore` |
 | hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
@@ -223,10 +234,49 @@ Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
 (`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`),
 **`data.md`** (`defineConnection`, the credentials vault).
 
+### Bind the api ONCE — typed hooks, not string tags
+
+Before any of the rubric below: app code calls the api through a **typed
+binding**, not through `@voltro/client`'s tag-taking hooks.
+
+```ts
+// src/lib/api.ts — one file, once per api
+import { createHooks } from '@voltro/client'
+import type { AppProcedures } from '@acme/api/rpcGroup'   // generated by codegen
+
+export const { useSubscription, useMutation, useAction } = createHooks<AppProcedures>('app')
+```
+
+`'app'` is the key the web app's `app.config.ts` gave the api in `apis:` — spelled
+once here, never at a call site again. Then:
+
+```tsx
+import { useSubscription, useMutation } from '../lib/api'
+
+const { data } = useSubscription('notes.list')   // rows inferred — NO `<T>`
+const create = useMutation('notes.create')       // input + output inferred
+```
+
+Do NOT write `useSubscription<ReadonlyArray<Note>>('app', 'notes.list')`. That
+form spells the api name at every call site, leaves the tag an unchecked string
+(a typo is a runtime error), and the `<T>` is an ASSERTION nothing compares
+against the server — a hand-kept mirror of a type the generator already knows.
+With the binding, a wrong tag, the wrong hook for the tag's kind, a missing
+required input, and a wrongly-shaped input are all compile errors, and the row
+type — including the client's `optimistic` marker — needs no annotation.
+
+Destructure the result; do not `export const api = createHooks(...)` and call
+`api.useSubscription(...)`. React's rules-of-hooks lint only sees a member call
+as a hook when the object is PascalCase, so the namespace form silently turns
+the hook lint off everywhere.
+
+The tag-taking hooks stay for code that only learns the tag at RUNTIME — plugin
+web bindings, libraries shipped against an unknown app. That is not app code.
+
 ### Pick the CLIENT primitive (decision rubric)
 
-`useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
-the whole client surface. The framework ships a **headless primitive for every
+`useSubscription` / `useMutation` / `useAction` (from your `src/lib/api.ts`
+binding above) are the transport — they are NOT the whole client surface. The framework ships a **headless primitive for every
 common UI job**, each derived from the descriptor Schema you already wrote. Reach
 for one BEFORE hand-rolling; ask in order:
 
@@ -597,6 +647,11 @@ primitive → just save; the supervised dev loop respawns and regenerates.
   But DO call `assertOwnTenant(input.tenantId, ctx.request.subject)` (from
   `@voltro/plugin-multitenancy/guard`) in custom mutations that write raw rows,
   and declare `error: TenantMismatch` — subscriptions are auto-scoped, writes are not.
+- **Every wire-exposed procedure declares an access decision, or it does not
+  boot.** `guards: [...]` (a check runs), `openAccess: '<why>'` (no check, on
+  purpose, with the reason in the source), or `internal: true` (off the wire).
+  `security: { defaultDeny: false }` in `app.config.ts` is the whole-app opt-out;
+  there is no env var for it.
 - **Gate authorization declaratively with `guards:`.** Add
   `guards: [{ scope: 'notes:write' }]` to `defineMutation`/`defineQuery`/`defineAction`
   — the framework enforces it BEFORE the executor (before the txn opens), fails

package/templates/AGENTS.md

@@ -148,7 +148,10 @@ line below replaces something real apps write by hand hundreds of times.
    parameterises it, so one aggregate serves per-team / per-period slices.
 5. **A permission check?** → declare **`guards:`** on the descriptor — it is
    enforced before the executor (and before a mutation's transaction opens) and
-   fails with a typed `ScopeError`. Two kinds, same array, all must pass:
+   fails with a typed `ScopeError`. **This is not optional: a wire-exposed
+   procedure that declares neither `guards:` nor `openAccess:` is REFUSED AT
+   BOOT** (`security.defaultDeny`, on by default). Two kinds, same array, all
+   must pass:
    - `{ scope: 'notes:write' }` — may the caller do this AT ALL.
    - `{ action, resourceType, resource: (input) => input.id }` — may they do it
      to THIS ROW (relationship/ReBAC, against a `defineResourcePolicy`). Needs a
@@ -159,6 +162,13 @@ line below replaces something real apps write by hand hundreds of times.
    in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
    at the top of every executor — or a hand-kept map from rpc tag to policy rule,
    which is fail-open by omission — is what `guards:` exists to delete.
+   **If the procedure really is open to everyone, say so — do not invent a
+   guard.** `openAccess: '<why anyone may call this>'` is the other accepted
+   answer, and the reason is required. Reaching for a scope every caller already
+   holds satisfies the gate, reads as protection, and enforces nothing. A
+   procedure only SERVER code calls wants neither: `internal: true` takes it off
+   the wire entirely (and then `openAccess` is refused — there is no wire to
+   decide about). `voltro doctor` lists every undecided procedure with its file.
 6. **Which ROWS may the caller see** (not: may they make the call)? →
    **`setRowFilter`** — a predicate derived from the Subject, AND-merged into
    EVERY read of that table, including every subscription delivery. `guards:`
@@ -210,6 +220,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
+| a scope every caller holds, added to make a boot gate pass | `openAccess: '<why it is open>'` — the honest spelling |
 | a token/secret column written as plain text | `.encrypted()` |
 | `Effect.promise(() => ctx.store.query(...))` in an Effect handler | `yield* EffectStore` |
 | hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
@@ -223,10 +234,49 @@ Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
 (`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`),
 **`data.md`** (`defineConnection`, the credentials vault).
 
+### Bind the api ONCE — typed hooks, not string tags
+
+Before any of the rubric below: app code calls the api through a **typed
+binding**, not through `@voltro/client`'s tag-taking hooks.
+
+```ts
+// src/lib/api.ts — one file, once per api
+import { createHooks } from '@voltro/client'
+import type { AppProcedures } from '@acme/api/rpcGroup'   // generated by codegen
+
+export const { useSubscription, useMutation, useAction } = createHooks<AppProcedures>('app')
+```
+
+`'app'` is the key the web app's `app.config.ts` gave the api in `apis:` — spelled
+once here, never at a call site again. Then:
+
+```tsx
+import { useSubscription, useMutation } from '../lib/api'
+
+const { data } = useSubscription('notes.list')   // rows inferred — NO `<T>`
+const create = useMutation('notes.create')       // input + output inferred
+```
+
+Do NOT write `useSubscription<ReadonlyArray<Note>>('app', 'notes.list')`. That
+form spells the api name at every call site, leaves the tag an unchecked string
+(a typo is a runtime error), and the `<T>` is an ASSERTION nothing compares
+against the server — a hand-kept mirror of a type the generator already knows.
+With the binding, a wrong tag, the wrong hook for the tag's kind, a missing
+required input, and a wrongly-shaped input are all compile errors, and the row
+type — including the client's `optimistic` marker — needs no annotation.
+
+Destructure the result; do not `export const api = createHooks(...)` and call
+`api.useSubscription(...)`. React's rules-of-hooks lint only sees a member call
+as a hook when the object is PascalCase, so the namespace form silently turns
+the hook lint off everywhere.
+
+The tag-taking hooks stay for code that only learns the tag at RUNTIME — plugin
+web bindings, libraries shipped against an unknown app. That is not app code.
+
 ### Pick the CLIENT primitive (decision rubric)
 
-`useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
-the whole client surface. The framework ships a **headless primitive for every
+`useSubscription` / `useMutation` / `useAction` (from your `src/lib/api.ts`
+binding above) are the transport — they are NOT the whole client surface. The framework ships a **headless primitive for every
 common UI job**, each derived from the descriptor Schema you already wrote. Reach
 for one BEFORE hand-rolling; ask in order:
 
@@ -597,6 +647,11 @@ primitive → just save; the supervised dev loop respawns and regenerates.
   But DO call `assertOwnTenant(input.tenantId, ctx.request.subject)` (from
   `@voltro/plugin-multitenancy/guard`) in custom mutations that write raw rows,
   and declare `error: TenantMismatch` — subscriptions are auto-scoped, writes are not.
+- **Every wire-exposed procedure declares an access decision, or it does not
+  boot.** `guards: [...]` (a check runs), `openAccess: '<why>'` (no check, on
+  purpose, with the reason in the source), or `internal: true` (off the wire).
+  `security: { defaultDeny: false }` in `app.config.ts` is the whole-app opt-out;
+  there is no env var for it.
 - **Gate authorization declaratively with `guards:`.** Add
   `guards: [{ scope: 'notes:write' }]` to `defineMutation`/`defineQuery`/`defineAction`
   — the framework enforces it BEFORE the executor (before the txn opens), fails
@@ -652,7 +707,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.33.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.34.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. |
@@ -663,7 +718,7 @@ each plugin's own README.
 | database.columnTypes | `node_modules/@voltro/cli/templates/agent-docs/database/columntypes.md` | Postgres-native ENUM types via dbEnum() — cheap ADD VALUE migrations, full type-narrowing. Falls back to CHECK constraints on other dialects. |
 | database.hosting | `node_modules/@voltro/cli/templates/agent-docs/database/hosting.md` | Run Voltro on any hosted Postgres, MySQL, MariaDB, or SQL Server — Supabase, Neon, Vercel Postgres, Railway, Render, Fly.io, AWS RDS, PlanetScale, Azure SQL, and more. Connection strings, pooling, gotchas. |
 | database.migrations | `node_modules/@voltro/cli/templates/agent-docs/database/migrations.md` | Voltro's planner-based migration system — diff your declared schema against the live DB, classify each change, refuse-to-apply anything risky without explicit intent. Dev auto-applies, prod refuses. |
-| Database | `node_modules/@voltro/cli/templates/agent-docs/database/misc.md` | Spin up an isolated branch of a tenant's data — a namespace snapshot/restore by default (dialect-agnostic, no vendor lock) or a Neon copy-on-write fast-path on Postgres — then bind to it and tear it down. The basis for per-PR preview environments. |
+| Database | `node_modules/@voltro/cli/templates/agent-docs/database/misc.md` | Branch the live schema and REHEARSE your migration on it — apply the plan to a throwaway copy, flag every lossy operation, prove it converges, drop the branch. Plus the branch primitive itself (namespace snapshot on Postgres, Neon copy-on-write fast-path). |
 | Database | `node_modules/@voltro/cli/templates/agent-docs/database/overview.md` | How Voltro talks to Postgres — the schema DSL, the query builder, mixins, migrations, and the reactive engine's relationship to all of it. |
 | database.querying | `node_modules/@voltro/cli/templates/agent-docs/database/querying.md` | Three cardinalities, one DSL. Declaration via relations(), eager loading via .with(), reactive invalidation via the two-stage dependency-graph + per-field pre-filter. |
 | database.scaling | `node_modules/@voltro/cli/templates/agent-docs/database/scaling.md` | Transparent read-replica routing with read-your-writes (RYW) consistency, multi-instance RYW via Redis, region-aware replica selection, and the per-dialect adapter surface. |
@@ -678,6 +733,7 @@ each plugin's own README.
 | Observability | `node_modules/@voltro/cli/templates/agent-docs/observability.md` | OpenTelemetry tracing in Voltro — the auto-emitted spans for every primitive, span attributes and nesting, the three enabling modes (console / OTLP / buffer), and adding your own spans with Effect.withSpan. |
 | Plugins | `node_modules/@voltro/cli/templates/agent-docs/plugins.md` | How Voltro plugins compose into the runtime, what they can intercept, the catalogue, and writing your own. |
 | Reference | `node_modules/@voltro/cli/templates/agent-docs/reference.md` | The client-side hook surface, grouped by purpose. |
+| Releases | `node_modules/@voltro/cli/templates/agent-docs/releases.md` | The largest release in the framework's history — what breaks your boot, what changes at runtime, and why none of it is rewritten for you. |
 | Routing | `node_modules/@voltro/cli/templates/agent-docs/routing.md` | Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework. |
 | Scheduling | `node_modules/@voltro/cli/templates/agent-docs/scheduling.md` | Deployment-agnostic scheduled jobs in Voltro — one *.cron.tsx definition that runs unchanged on a single box, a multi-instance fleet, or an external scheduler. |
 | Schema-driven UI | `node_modules/@voltro/cli/templates/agent-docs/schema-driven-ui.md` | Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue. |
@@ -686,7 +742,7 @@ each plugin's own README.
 | templates.appShells | `node_modules/@voltro/cli/templates/agent-docs/templates/appshells.md` | A marketing landing page — hero, features, CTA. Static-rendered with zero JS on the wire by default. |
 | templates.custom | `node_modules/@voltro/cli/templates/agent-docs/templates/custom.md` | Add a template the CLI can scaffold from — a directory under voltro-templates/apps/ with a manifest and the files to copy. |
 | templates.mobile | `node_modules/@voltro/cli/templates/agent-docs/templates/mobile.md` | An Expo (React Native) app that is the third consumer of your api — the same typed hooks (useSubscription / useMutation), offline-first by default, typed deep links, and device registration for push. Expo owns Metro; voltro dev runs the sibling api. |
-| Templates | `node_modules/@voltro/cli/templates/agent-docs/templates/overview.md` | Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call. |
+| Templates | `node_modules/@voltro/cli/templates/agent-docs/templates/overview.md` | Dozens of dogfooded starter templates ship with the framework — backend shapes, frontend shapes, a serverless function library, and an Expo mobile app. voltro list-templates is the authority; scaffold any of them with one CLI call. |
 | templates.serverless | `node_modules/@voltro/cli/templates/agent-docs/templates/serverless.md` | A library of standalone *.serverless.ts functions — pure compute, request-header/geo, outbound HTTP, Web Crypto HMAC, an LLM call, status-controlled errors. Run with voltro serverless; ship to node / Cloudflare / Scaleway. No server, no port. |
 | Testing | `node_modules/@voltro/cli/templates/agent-docs/testing.md` | Voltro's test story — the @voltro/testing package, the test pyramid (unit handlers/tools → workflow runner → e2e), and the voltro test / voltro e2e CLI commands. |
 | Workflows | `node_modules/@voltro/cli/templates/agent-docs/workflows.md` | Durable Effect workflows in Voltro — what they are, when to use them, and the current runtime boundaries. |
@@ -704,6 +760,7 @@ each plugin's own README.
 | auth-clerk | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-clerk.md` (or `node_modules/@voltro/plugin-auth-clerk/README.md`) | Clerk AuthStrategy — verifies Clerk-issued __session JWTs via the Frontend API JWKS (no secret key) and maps org_id → tenantId. |
 | auth-kinde | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-kinde.md` (or `node_modules/@voltro/plugin-auth-kinde/README.md`) | Kinde AuthStrategy — verifies Kinde-issued JWTs via JWKS at the configured issuer (no client secret) and maps org_code → tenantId. |
 | auth-oidc | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-oidc.md` (or `node_modules/@voltro/plugin-auth-oidc/README.md`) | Generic OIDC AuthStrategy — verifies any OpenID-Connect IdP's JWTs via JWKS (Okta, Keycloak, Cognito, Azure AD, Google Workspace). Discovery or explicit JWKS URL; maps a claim → tenantId. |
+| auth-social | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-social.md` (or `node_modules/@voltro/plugin-auth-social/README.md`) | First-party Sign in with Google / GitHub / Apple — mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, no identity vendor. |
 | auth-supabase | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-supabase.md` (or `node_modules/@voltro/plugin-auth-supabase/README.md`) | Supabase Auth (GoTrue) AuthStrategy — verifies Supabase-issued JWTs via the project's JWKS and maps app_metadata.tenant_id → tenantId. |
 | 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. |
@@ -719,7 +776,7 @@ each plugin's own README.
 | logship | `node_modules/@voltro/cli/templates/agent-docs/plugins/logship.md` (or `node_modules/@voltro/plugin-logship/README.md`) | Ship structured logs to Better Stack / Axiom / Loki / any HTTP sink — batched, redacted, fail-soft. Rides the framework log-sink hook. |
 | 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-scope reads + auto-fill writes), the assertOwnTenant write-guard, and the typed TenantMismatch error. |
+| 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. |
 | 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. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.33.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.34.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. |
@@ -20,7 +20,7 @@ each plugin's own README.
 | database.columnTypes | `node_modules/@voltro/cli/templates/agent-docs/database/columntypes.md` | Postgres-native ENUM types via dbEnum() — cheap ADD VALUE migrations, full type-narrowing. Falls back to CHECK constraints on other dialects. |
 | database.hosting | `node_modules/@voltro/cli/templates/agent-docs/database/hosting.md` | Run Voltro on any hosted Postgres, MySQL, MariaDB, or SQL Server — Supabase, Neon, Vercel Postgres, Railway, Render, Fly.io, AWS RDS, PlanetScale, Azure SQL, and more. Connection strings, pooling, gotchas. |
 | database.migrations | `node_modules/@voltro/cli/templates/agent-docs/database/migrations.md` | Voltro's planner-based migration system — diff your declared schema against the live DB, classify each change, refuse-to-apply anything risky without explicit intent. Dev auto-applies, prod refuses. |
-| Database | `node_modules/@voltro/cli/templates/agent-docs/database/misc.md` | Spin up an isolated branch of a tenant's data — a namespace snapshot/restore by default (dialect-agnostic, no vendor lock) or a Neon copy-on-write fast-path on Postgres — then bind to it and tear it down. The basis for per-PR preview environments. |
+| Database | `node_modules/@voltro/cli/templates/agent-docs/database/misc.md` | Branch the live schema and REHEARSE your migration on it — apply the plan to a throwaway copy, flag every lossy operation, prove it converges, drop the branch. Plus the branch primitive itself (namespace snapshot on Postgres, Neon copy-on-write fast-path). |
 | Database | `node_modules/@voltro/cli/templates/agent-docs/database/overview.md` | How Voltro talks to Postgres — the schema DSL, the query builder, mixins, migrations, and the reactive engine's relationship to all of it. |
 | database.querying | `node_modules/@voltro/cli/templates/agent-docs/database/querying.md` | Three cardinalities, one DSL. Declaration via relations(), eager loading via .with(), reactive invalidation via the two-stage dependency-graph + per-field pre-filter. |
 | database.scaling | `node_modules/@voltro/cli/templates/agent-docs/database/scaling.md` | Transparent read-replica routing with read-your-writes (RYW) consistency, multi-instance RYW via Redis, region-aware replica selection, and the per-dialect adapter surface. |
@@ -35,6 +35,7 @@ each plugin's own README.
 | Observability | `node_modules/@voltro/cli/templates/agent-docs/observability.md` | OpenTelemetry tracing in Voltro — the auto-emitted spans for every primitive, span attributes and nesting, the three enabling modes (console / OTLP / buffer), and adding your own spans with Effect.withSpan. |
 | Plugins | `node_modules/@voltro/cli/templates/agent-docs/plugins.md` | How Voltro plugins compose into the runtime, what they can intercept, the catalogue, and writing your own. |
 | Reference | `node_modules/@voltro/cli/templates/agent-docs/reference.md` | The client-side hook surface, grouped by purpose. |
+| Releases | `node_modules/@voltro/cli/templates/agent-docs/releases.md` | The largest release in the framework's history — what breaks your boot, what changes at runtime, and why none of it is rewritten for you. |
 | Routing | `node_modules/@voltro/cli/templates/agent-docs/routing.md` | Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework. |
 | Scheduling | `node_modules/@voltro/cli/templates/agent-docs/scheduling.md` | Deployment-agnostic scheduled jobs in Voltro — one *.cron.tsx definition that runs unchanged on a single box, a multi-instance fleet, or an external scheduler. |
 | Schema-driven UI | `node_modules/@voltro/cli/templates/agent-docs/schema-driven-ui.md` | Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue. |
@@ -43,7 +44,7 @@ each plugin's own README.
 | templates.appShells | `node_modules/@voltro/cli/templates/agent-docs/templates/appshells.md` | A marketing landing page — hero, features, CTA. Static-rendered with zero JS on the wire by default. |
 | templates.custom | `node_modules/@voltro/cli/templates/agent-docs/templates/custom.md` | Add a template the CLI can scaffold from — a directory under voltro-templates/apps/ with a manifest and the files to copy. |
 | templates.mobile | `node_modules/@voltro/cli/templates/agent-docs/templates/mobile.md` | An Expo (React Native) app that is the third consumer of your api — the same typed hooks (useSubscription / useMutation), offline-first by default, typed deep links, and device registration for push. Expo owns Metro; voltro dev runs the sibling api. |
-| Templates | `node_modules/@voltro/cli/templates/agent-docs/templates/overview.md` | Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call. |
+| Templates | `node_modules/@voltro/cli/templates/agent-docs/templates/overview.md` | Dozens of dogfooded starter templates ship with the framework — backend shapes, frontend shapes, a serverless function library, and an Expo mobile app. voltro list-templates is the authority; scaffold any of them with one CLI call. |
 | templates.serverless | `node_modules/@voltro/cli/templates/agent-docs/templates/serverless.md` | A library of standalone *.serverless.ts functions — pure compute, request-header/geo, outbound HTTP, Web Crypto HMAC, an LLM call, status-controlled errors. Run with voltro serverless; ship to node / Cloudflare / Scaleway. No server, no port. |
 | Testing | `node_modules/@voltro/cli/templates/agent-docs/testing.md` | Voltro's test story — the @voltro/testing package, the test pyramid (unit handlers/tools → workflow runner → e2e), and the voltro test / voltro e2e CLI commands. |
 | Workflows | `node_modules/@voltro/cli/templates/agent-docs/workflows.md` | Durable Effect workflows in Voltro — what they are, when to use them, and the current runtime boundaries. |
@@ -61,6 +62,7 @@ each plugin's own README.
 | auth-clerk | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-clerk.md` (or `node_modules/@voltro/plugin-auth-clerk/README.md`) | Clerk AuthStrategy — verifies Clerk-issued __session JWTs via the Frontend API JWKS (no secret key) and maps org_id → tenantId. |
 | auth-kinde | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-kinde.md` (or `node_modules/@voltro/plugin-auth-kinde/README.md`) | Kinde AuthStrategy — verifies Kinde-issued JWTs via JWKS at the configured issuer (no client secret) and maps org_code → tenantId. |
 | auth-oidc | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-oidc.md` (or `node_modules/@voltro/plugin-auth-oidc/README.md`) | Generic OIDC AuthStrategy — verifies any OpenID-Connect IdP's JWTs via JWKS (Okta, Keycloak, Cognito, Azure AD, Google Workspace). Discovery or explicit JWKS URL; maps a claim → tenantId. |
+| auth-social | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-social.md` (or `node_modules/@voltro/plugin-auth-social/README.md`) | First-party Sign in with Google / GitHub / Apple — mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, no identity vendor. |
 | auth-supabase | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-supabase.md` (or `node_modules/@voltro/plugin-auth-supabase/README.md`) | Supabase Auth (GoTrue) AuthStrategy — verifies Supabase-issued JWTs via the project's JWKS and maps app_metadata.tenant_id → tenantId. |
 | 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. |
@@ -76,7 +78,7 @@ each plugin's own README.
 | logship | `node_modules/@voltro/cli/templates/agent-docs/plugins/logship.md` (or `node_modules/@voltro/plugin-logship/README.md`) | Ship structured logs to Better Stack / Axiom / Loki / any HTTP sink — batched, redacted, fail-soft. Rides the framework log-sink hook. |
 | 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-scope reads + auto-fill writes), the assertOwnTenant write-guard, and the typed TenantMismatch error. |
+| 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. |
 | 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. |

package/templates/agent-docs/_manifest.json

@@ -8,7 +8,7 @@
       "group": null,
       "description": "How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework.",
       "path": "agent-docs/ai.md",
-      "files": 9
+      "files": 11
     },
     {
       "id": "authentication",
@@ -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": 18
+      "files": 19
     },
     {
       "id": "database/advancedqueries",
@@ -96,7 +96,7 @@
       "title": "Database",
       "section": "Database",
       "group": null,
-      "description": "Spin up an isolated branch of a tenant's data — a namespace snapshot/restore by default (dialect-agnostic, no vendor lock) or a Neon copy-on-write fast-path on Postgres — then bind to it and tear it down. The basis for per-PR preview environments.",
+      "description": "Branch the live schema and REHEARSE your migration on it — apply the plan to a throwaway copy, flag every lossy operation, prove it converges, drop the branch. Plus the branch primitive itself (namespace snapshot on Postgres, Neon copy-on-write fast-path).",
       "path": "agent-docs/database/misc.md",
       "files": 2
     },
@@ -226,6 +226,15 @@
       "path": "agent-docs/reference.md",
       "files": 7
     },
+    {
+      "id": "releases",
+      "title": "Releases",
+      "section": "Releases",
+      "group": null,
+      "description": "The largest release in the framework's history — what breaks your boot, what changes at runtime, and why none of it is rewritten for you.",
+      "path": "agent-docs/releases.md",
+      "files": 1
+    },
     {
       "id": "routing",
       "title": "Routing",
@@ -303,7 +312,7 @@
       "title": "Templates",
       "section": "Templates",
       "group": null,
-      "description": "Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call.",
+      "description": "Dozens of dogfooded starter templates ship with the framework — backend shapes, frontend shapes, a serverless function library, and an Expo mobile app. voltro list-templates is the authority; scaffold any of them with one CLI call.",
       "path": "agent-docs/templates/overview.md",
       "files": 1
     },
@@ -408,6 +417,14 @@
       "doc": "plugins/auth-oidc.md",
       "module": "agent-docs/plugins/auth-oidc.md"
     },
+    {
+      "slug": "auth-social",
+      "title": "Social login (Google / GitHub / Apple)",
+      "description": "First-party Sign in with Google / GitHub / Apple — mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, no identity vendor.",
+      "pkg": "@voltro/plugin-auth-social",
+      "doc": "plugins/auth-social.md",
+      "module": "agent-docs/plugins/auth-social.md"
+    },
     {
       "slug": "auth-supabase",
       "title": "Supabase Auth",
@@ -531,7 +548,7 @@
     {
       "slug": "multitenancy",
       "title": "Multi-tenancy",
-      "description": "The tenant() schema mixin (auto-scope reads + auto-fill writes), the assertOwnTenant write-guard, and the typed TenantMismatch error.",
+      "description": "The tenant() schema mixin (auto-scoped reads, auto-filled inserts, tenant-resolved keyed writes), the assertOwnTenant write-guard, and the typed TenantMismatch error.",
       "pkg": "@voltro/plugin-multitenancy",
       "doc": "plugins/multitenancy.md",
       "module": "agent-docs/plugins/multitenancy.md"