@voltro/cli 0.11.2 → 0.11.4

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { bt as e } from "./inspectMetrics-BuBwg1yW.js";
-import { t } from "./start-ChN6PO-c.js";
+import { xt as e } from "./inspectMetrics-D4EJ8LTi.js";
+import { t } from "./start-DyJE6w1R.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.11.2",
-    "@voltro/cache": "0.11.2",
-    "@voltro/data-transfer": "0.11.2",
-    "@voltro/database": "0.11.2",
-    "@voltro/env": "0.11.2",
-    "@voltro/kv": "0.11.2",
-    "@voltro/logger": "0.11.2",
-    "@voltro/plugin-auth": "0.11.2",
-    "@voltro/plugin-broadcast": "0.11.2",
-    "@voltro/plugin-mail": "0.11.2",
-    "@voltro/plugin-storage": "0.11.2",
-    "@voltro/plugin-webhooks": "0.11.2",
-    "@voltro/protocol": "0.11.2",
-    "@voltro/runtime": "0.11.2",
-    "@voltro/serverless": "0.11.2",
-    "@voltro/workflow": "0.11.2",
+    "@voltro/ai": "0.11.4",
+    "@voltro/cache": "0.11.4",
+    "@voltro/data-transfer": "0.11.4",
+    "@voltro/database": "0.11.4",
+    "@voltro/env": "0.11.4",
+    "@voltro/kv": "0.11.4",
+    "@voltro/logger": "0.11.4",
+    "@voltro/plugin-auth": "0.11.4",
+    "@voltro/plugin-broadcast": "0.11.4",
+    "@voltro/plugin-mail": "0.11.4",
+    "@voltro/plugin-storage": "0.11.4",
+    "@voltro/plugin-webhooks": "0.11.4",
+    "@voltro/protocol": "0.11.4",
+    "@voltro/runtime": "0.11.4",
+    "@voltro/serverless": "0.11.4",
+    "@voltro/workflow": "0.11.4",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/agent-docs/_manifest.json

@@ -35,7 +35,7 @@
       "group": null,
       "description": "The voltro CLI — every command, grouped by purpose, with the flags that actually matter.",
       "path": "agent-docs/cli.md",
-      "files": 9
+      "files": 10
     },
     {
       "id": "configuration",
@@ -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": 15
+      "files": 16
     },
     {
       "id": "database/advancedqueries",

package/templates/agent-docs/authentication.md

@@ -723,6 +723,28 @@ The strategy above only *verifies* — your browser still has to *send* the toke
 
   This is **required when the api is a separate origin** (the common case — `api.example.com` vs your web origin): there is no shared cookie and no upgrade header, so without `headers` every subscription connects **anonymous** (the shell renders, but user-/tenant-scoped data stays empty). A static object works for non-rotating tokens; never hardcode a secret literal — it ships to the browser.
 
+### Declaratively — `apis.<name>.authHeaders` in `app.config.ts`
+
+Rather than hand-writing a `mount()` entry just to inject the thunk, declare it on the api in `app.config.ts`. The framework owns the client mount, the SSR-null case (the resolver runs browser-only — it never fires on the server), and the re-resolve on every reconnect; you supply only the token function:
+
+```ts
+// app.config.ts
+export default {
+  type: 'web' as const,
+  apis: {
+    api: {
+      package: '@app/api',
+      // Resolved fresh on every (re)connect — a rotating token is pulled anew:
+      authHeaders: async () => ({
+        authorization: `Bearer ${(await supabase.auth.getSession()).data.session?.access_token ?? ''}`,
+      }),
+    },
+  },
+}
+```
+
+`authHeaders` is a **function**, so it is imported from `app.config.ts` into the client bundle rather than serialized — the file must stay browser-safe (no `node:*` / server-only value imports; the env schema and other pure config are fine). It supersedes a static `headers` on the same api. This is the preferred form; reach for a hand-written `mount()` only when you need to wrap the tree in your own provider as well.
+
 ## WorkOS
 
 ```ts

package/templates/agent-docs/cli.md

@@ -21,9 +21,9 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 |---|---|
 | [Scaffolding](/docs/cli/scaffolding) | `create-project`, `add-app`, `list-templates` |
 | Packages | `package` (`create` / `publishable` / `private` / `status`), `create-package` |
-| [Dev](/docs/cli/dev) | `dev`, `codegen`, `agents-md` |
+| [Dev](/docs/cli/dev) | `dev`, `codegen`, `agents-md`, [`env`](/docs/cli/env) (`check` / `sync` / `types` / `turbo`), [`generate`](/docs/cli/scaffolding) (AI app-builder), `dashboard` (serve the DevTools dashboard standalone; `--port`, `VOLTRO_DASHBOARD_APPS`) |
 | [Build & run](/docs/cli/build-and-start) | `build`, `start`, `serve` |
-| Deploy | `deploy` (`plan` — auto-detect the target tier per app + function), [`serverless`](/docs/deployment/serverless-functions) (`list` / `dev` / `serve` / `build` / `deploy`), [`static`](/docs/deployment/static-sites) (`hosts` / `deploy`) |
+| Deploy | `deploy` (`plan` — auto-detect the target tier per app + function), [`serverless`](/docs/deployment/serverless-functions) (`list` / `dev` / `serve` / `build` / `deploy`), [`static`](/docs/deployment/static-sites) (`hosts` / `deploy`), `dormancy` (single-node scale-to-zero: fronts the app, stops it when idle, wakes on the next request; `--idle-grace-ms` / `--tick-ms`) |
 | [Database](/docs/cli/migrate) | `migrate`, `db` (`plan` / `apply` / `plans` / `drift` / `squash` / `restore-snapshot` / `migrate` / `rollback` / `status` / `seed`) |
 | [Update](/docs/cli/update) | `update` (`--to` / `--dry-run` / `--force` / `--exact`) — bump every `@voltro/*`, install, run the codemods that adapt your source to the new version |
 | [Data transfer](/docs/cli/data) | `data` (`export` / `import` / `unpack` / `inspect` / `backup` / `restore`) — directory + single-file `.vbundle` bundles, streaming assets, masking, at-rest encryption |
@@ -1125,12 +1125,44 @@ voltro inspect rpc                              # procedures + workflow descript
 voltro inspect metrics                          # rolling rpc latency buckets
 voltro inspect cache                            # web data-cache stats (web apps only)
 voltro inspect schedules                        # cron registrations + coordination mode
+voltro inspect schedules --failing              # only broken crons — exits 1 if any (see below)
 voltro inspect aggregates                       # materialised aggregate views
 voltro inspect invoke --tag users.list --input '{}'   # call a procedure over HTTP
 ```
 
 Flags on every subcommand: `--process <name>` narrows to one api; `--format pretty|json` (default `pretty`). `invoke` additionally takes `--tag <procedureTag>` and `--input <json>`. With no subcommand it prints the endpoint map + the live processes it can reach.
 
+### `schedules --failing` — is any cron actually broken?
+
+A schedule fires unattended: there is no user watching it fail. The plain
+`schedules` listing answers *which crons exist and when they fire next* — never
+whether they **work**. `--failing` rolls each schedule's recent runs
+(`/_voltro/inspect/schedules/runs`) into a verdict and prints only the broken
+ones:
+
+```bash
+$ voltro inspect schedules --failing
+# schedules @api
+  sprint.report  0 2 * * *  FAILING x87
+    every recorded run failed (last 20)
+    Workflow "sprint.report" was started with an invalid payload. missing required field(s): teamId
+```
+
+It **exits 1 when anything is failing**, so it works as a post-deploy gate and
+not only as something someone remembers to run:
+
+```bash
+voltro inspect schedules --failing || echo "broken cron — do not promote"
+```
+
+A trailing success ends a streak (a recovered job is not reported), and
+`skipped` / `missed` runs are ignored — those are coordination outcomes (another
+pod took the tick, the process was down), not handler verdicts. A schedule that
+has never run is not "failing".
+
+Pair it with `voltro logs --level error`: a failing handler now logs at **error**
+level, so the two surfaces agree.
+
 ## The inspect HTTP surface
 
 Every `voltro dev` / `voltro start` instance exposes a read-only introspection surface under `/_voltro/inspect/*`. The [Voltro Dashboard](/docs/observability/dashboard) consumes it to render the route sitemap, RPC list, subscription panel, workflow runs, and metrics. You can also hit the endpoints directly with `curl` (the `voltro inspect` subcommands above are the thin wrapper over exactly these).
@@ -1235,6 +1267,18 @@ voltro traces --errors --format json | jq '.traces[]'
 
 Workflow: `voltro traces --errors --format json` to find a failure, then `voltro logs --trace <id> --format json` for the full chain (frontend → api → api, in order). The full flag set (`--min-duration`, `--status`, `--process`, …) lives in [Traces & logs from the shell](/docs/observability/cli).
 
+## `voltro cluster`
+
+`voltro cluster status` gives a clustering snapshot of every running api — one row per instance with its `replicaId`, runner address, dialect, CDC flavour, coordination mode, and `server_id`, plus a flag for any SQL runner stuck on `localhost` (a common misconfiguration that silently breaks cross-instance work). Use it to confirm a multi-instance deployment actually formed a cluster rather than N isolated nodes.
+
+```bash
+voltro cluster status                 # pretty table across every running api
+voltro cluster status --json          # machine-readable (also --format json)
+voltro cluster status --process api   # narrow to one named process
+```
+
+Like the rest of the inspect family it reads the live `/_voltro/inspect/*` surface, so an api has to be running.
+
 ## `voltro test`
 
 ```bash
@@ -2052,3 +2096,43 @@ Use `voltro db apply` (the declarative diff), not `voltro db migrate` (the imper
 
 - [Migrate](/docs/cli/migrate) — schema changes end-to-end
 - [Build & start](/docs/cli/build-and-start) — production paths
+
+
+
+---
+
+<!-- source: en/cli/env.md -->
+## Env
+
+_voltro env — inspect and sync the typed-env manifest; emit env.generated.d.ts so CI tsc knows your env vars._
+
+`voltro env` works with the **typed-env manifest** — the set of environment variables your app declares (via `envVar(...)`) and the framework requires. It's how a missing or malformed env var becomes a boot-time error with a clear message instead of a mysterious runtime failure.
+
+```bash
+voltro env            # check (default) — validate the current env against the manifest
+voltro env check      # explicit
+voltro env sync       # write/update .env.example from the manifest
+voltro env types      # emit env.generated.d.ts (typed process.env for CI tsc)
+voltro env turbo      # emit the turbo globalEnv/globalPassThroughEnv list
+```
+
+## `check` (default)
+
+Validates the current environment against the declared manifest and fails (non-zero) on a missing required var or a value that doesn't parse. Run it in a pre-deploy step to catch a misconfigured environment before the app boots. Run with no subcommand and it defaults to `check`.
+
+## `sync` — keep `.env.example` honest
+
+Writes `.env.example` from the manifest so the committed template always matches what the app actually reads — new `envVar(...)` declarations show up without hand-editing.
+
+## `types` — typed `process.env` for CI
+
+Emits `env.generated.d.ts`, which types `process.env` to your declared vars. Commit it (or generate it in CI before `tsc`) so a typo in a `process.env.MY_VAR` reference is a type error, not a runtime `undefined`.
+
+## `turbo` — monorepo cache correctness
+
+Emits the `globalEnv` / `globalPassThroughEnv` entries for `turbo.json`, so Turbo's cache invalidates when a relevant env var changes and passes the right vars through to tasks.
+
+## Related
+
+- [Secrets](/docs/cli/overview#common-env-vars) — generating secret values with `voltro secret`.
+- [Configuration](/docs/configuration) — declaring env vars with `envVar(...)`.

package/templates/agent-docs/data.md

@@ -315,6 +315,8 @@ export default defineExecutor(notesSummary, async (_input, ctx) => {
 
 It's a runtime identity (returns the handler unchanged) — the whole value is the compile check. The Effect error and requirement channels stay inferred; only the success value is constrained. A **descriptor-return** (reactive) executor is allowed through unchecked: the store produces the rows, so a value-level return type can't express the row-vs-`output` check. `defineExecutor` works the same for `defineMutation` / `defineAction` handlers.
 
+> **Composing one executor inside another (e.g. a workflow `step`).** The value `defineExecutor` returns is typed as the `ExecutorReturn` UNION (`Output | Promise | Effect | descriptor-return`), so it has no `.pipe` — you can't feed the wrapped default export straight into another Effect. Export the handler's raw `Effect` separately (a named `export const execute = …`, or import the un-wrapped function) and compose THAT; keep the `defineExecutor`-wrapped default only as the procedure's entry point. The union return is deliberate — it's what lets one helper type every executor shape — so this is a "import the raw effect for composition" convention, not a gap to route around.
+
 ## Auto-optimistic source
 
 `source` also connects query caches to mutation `target` metadata:
@@ -1577,6 +1579,61 @@ This is the Stripe-style contract — the **client** opts in by sending the head
 - **Inbound webhooks already dedup** via [`@voltro/plugin-webhooks`](/docs/plugins/webhooks) (provider key + `_voltro_webhook_*`) — don't double-cover them.
 - **Atomic claim, non-atomic completion.** Two concurrent same-key requests resolve to exactly one execution (the `UNIQUE(scope,key)` insert is the arbiter). But the cached response isn't committed in the handler's own transaction — a crash between the handler committing and the record flipping to `completed` leaves the key in-flight (a retry `409`s until the TTL lapses, then re-runs). REST handlers aren't auto-transactional, so this is the honest ceiling.
 
+## Projecting an existing procedure — `publicApi`
+
+You often want to *offer* an API you don't consume from your own frontend. When the procedure already exists as a query / mutation / action, you don't need to rewrite it as a REST route — annotate it with `publicApi` and the framework mounts ONE HTTP route that runs the **same** handler, under the same guards:
+
+```ts
+// queries/absenceRequests.list.query.ts
+export default defineQuery({
+  name:   'absenceRequests.list',
+  input:  Schema.Struct({ status: Schema.optional(Schema.String), limit: Schema.optional(Schema.Number) }),
+  output: Schema.Array(AbsenceRequest),
+  guards: [requireScope('absences:read')],
+  publicApi: {},   // → GET /v1/absenceRequests/list?status=open&limit=20
+})
+```
+
+- **Method** derives from the kind: query → `GET`, mutation / action → `POST` (override with `method`).
+- **Path** derives from the tag: `/<version>/<tag-as-path>` (override with `path`; set `version`).
+- **Input binding** follows the method: for `GET` the descriptor's `input` schema is bound to the **query string**, otherwise to the JSON **body**. So filter and pagination fields are plain URL params — no separate input shape.
+- **Relations** need nothing extra: eager loading is resolved server-side by the executor, so `include` works identically over HTTP.
+- **Authorization is the same code** as the WebSocket path — the declarative `guards:`, the row filter, and tenant scoping all run before the handler. A procedure that denies on the socket denies here.
+- Also available per endpoint: `scopes` (extra API-key scopes), `rateLimit`, `idempotent`.
+
+This pairs with [`crud.list`](/docs/data/crud): `filter` / `paginate` / `sort` / `include` on the executor plus `publicApi: {}` on the descriptor is a complete, filtered, paginated REST list endpoint in one declaration.
+
+Use `publicApi` when the procedure already exists and the derived URL is fine; use `defineRestRoute` when you need a hand-shaped URL, path params, or a response that isn't the procedure's output.
+
+### Live updates over HTTP — `stream: 'sse'`
+
+A third party that can't open your WebSocket can still follow changes: `stream: 'sse'` on a QUERY projects it as Server-Sent Events — the initial `snapshot`, then a `delta` per change, until the client disconnects.
+
+```ts
+export default defineQuery({
+  name:   'orders.live',
+  input:  Schema.Struct({ status: Schema.optional(Schema.String) }),
+  output: Schema.Array(Order),
+  guards: [requireScope('orders:read')],
+  publicApi: { stream: 'sse' },   // → GET /v1/orders/live?status=open  (text/event-stream)
+})
+```
+
+```js
+// any EventSource client — no Voltro SDK needed
+const es = new EventSource('/v1/orders/live?status=open')
+es.addEventListener('snapshot', (e) => setRows(JSON.parse(e.data).data))
+es.addEventListener('delta',    (e) => applyDelta(JSON.parse(e.data)))
+```
+
+Each event's `_tag` becomes the SSE `event:` name, so a client listens per kind instead of switching on a payload field. The framing handles the details that bite otherwise: embedded newlines are split across `data:` lines (a raw `\n` would truncate the event), a `retry:` hint is sent, and a keep-alive comment goes out every 15s so proxies don't drop an idle stream.
+
+Same guarantees as the WebSocket path, because it is the same code: the declarative `guards:`, the row filter and tenant scoping all run before anything is emitted, and the client's disconnect tears the subscription down (including a disconnect *during* setup). A guard denial arrives as one `error` event rather than an HTTP status — by then the response headers are already sent.
+
+`stream: 'sse'` on a mutation or action is ignored: there is nothing to subscribe to.
+
+For a hand-written `defineRestRoute`, the same machinery is available directly — return `sse((emit) => unsubscribe)` from the handler and frame events with `sseFrame(event, data)` (both from `@voltro/protocol/rest`).
+
 ## REST route vs Action
 
 Both are unary request/response. Pick by transport + audience:
@@ -1947,6 +2004,120 @@ When no analytics sink is configured the framework provides the no-op sink: the
 
 
 
+---
+
+<!-- source: en/data/crud.md -->
+## CRUD helpers
+
+_crud.* secure-default handler helpers — tenant-scoped reads, column redaction, and null-not-throw getById, so the CRUD tail of a handler is one honest line._
+
+Most of a plain list / get / create / update / delete handler is the same five lines every time — and getting those lines subtly wrong is how data leaks. The `crud.*` helpers from `@voltro/runtime` give you the **executor** with the secure defaults baked in; you still write the descriptor (schemas + `guards`), which is where the browser-safe wire contract and the authorization live.
+
+```ts
+// accounts.list.query.server.ts
+import { crud } from '@voltro/runtime'
+
+export default crud.list('accounts', { redact: ['apiSecret'] })
+```
+
+```ts
+// accounts.list.query.ts — the descriptor stays hand-written + browser-safe
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export default defineQuery({
+  name: 'accounts.list',
+  input: Schema.Struct({}),
+  // note: the wire output OMITS apiSecret, so it never reaches the client
+  output: Schema.Array(Schema.Struct({ id: Schema.String, name: Schema.String })),
+})
+```
+
+## What the defaults bake in
+
+- **Tenant scope.** `crud.list` and `crud.getById` read through `ctx.store`, which auto-scopes a `tenant()` table. They never call `.unscoped()`, so a cross-tenant read is impossible through them — `payslips.list` cannot return another tenant's rows.
+- **Redaction.** A column a generated read must never ship — a credential, a token hash, a salary — is stripped from every returned row (reads and the row a `create` / `update` echoes). Two sources: a column marked [`.serverOnly()`](/docs/database/sensitivity) is stripped **automatically** (declare the exposure policy once at the schema and every crud read respects it — the single-source form), plus the per-call `redact: [...]` option for anything not worth a schema marker. Declare the same omission in the descriptor's `output` schema so the column never reaches the client at all; the helper is the runtime guarantee that it doesn't, whatever the schema says.
+- **`getById` returns `null`, never throws.** A reactive getter that throws takes its shared-WebSocket siblings down with it. `crud.getById` resolves `null` for an absent row.
+
+## The helpers
+
+| Helper | Executor it returns |
+|---|---|
+| `crud.list(table, { redact? })` | tenant-scoped list of every row, redacted |
+| `crud.getById(table, { redact? })` | one row by `input.id`, or `null` — redacted |
+| `crud.create(table, { redact? })` | insert `input`; id/tenant/audit auto-stamped; echoes the redacted row |
+| `crud.update(table, { redact? })` | patch `{ id, ...patch }`; returns the updated row or `null` |
+| `crud.remove(table)` | delete `input.id`; returns `{ deleted }` |
+| `crud.count(table, { filter? })` | `COUNT(*)` of the filtered, tenant-scoped set — the total for page-based UIs |
+
+`redactColumns(rows, cols)` is exported standalone for a hand-written handler that isn't plain CRUD but still needs to redact declaratively.
+
+## `crud.list` read ergonomics — filter, sort, paginate, include
+
+A generated list isn't limited to "all rows". `crud.list` takes the ergonomics every real list view needs — all optional and additive on top of `redact`:
+
+```ts
+export default crud.list('absenceRequests', {
+  filter:   (input) => ({ employeeId: input.employeeId, status: input.status }), // → WHERE
+  paginate: true,                                        // ?page=3&pageSize=20  (or ?limit=20&offset=40)
+  sort:     [{ column: 'createdAt', direction: 'desc' }], // multi-column
+  include:  { employee: { with: { team: true } } },      // eager relations, nested filter/sort
+  redact:   ['internalNote'],
+})
+```
+
+- **`filter`** maps the request input to a `WHERE` — return a column→value map; an `undefined` field is ignored (an absent filter param is a no-op). Applied through the tenant-scoped `.where`.
+- **`paginate: true`** accepts BOTH paging styles, so a caller uses whichever its UI thinks in: **`page`** (1-based) + **`pageSize`** (default 100), or **`limit`** / **`offset`** (defaults 100 / 0). `page` wins when both are sent, and a `page` below 1 clamps to the first page rather than producing a negative offset. For the total a page-based UI needs ("page 3 of 12"), pair it with `crud.count` — see below.
+- **`maxPageSize`** caps how many rows ONE request may ask for (default **1000**). The page size is caller-controlled, so without a cap `?limit=1000000` is a one-request read of the whole table — and with `publicApi` that caller is anyone who can reach the URL. Values above the cap are clamped, not rejected; raise it deliberately for an export-style endpoint.
+- **`sort`** is a multi-column `orderBy`, applied in order.
+- **`include`** is the SAME spec [`.with(...)`](/docs/database/relations) takes, so nested relations and per-branch `where` / `orderBy` / `limit` (nested filtering and sort) all work. `getById` takes `include` too.
+
+
+Pass `crud.count` the **same** `filter` as the list (share the option object) so the total and the pages can't disagree about which rows they mean. It ignores paging fields on the input — it counts the whole filtered set, not the current page:
+
+```ts
+// the total, for rendering "page 3 of 12" — SAME filter as the list
+export default crud.count('absenceRequests', {
+  filter: (input) => ({ employeeId: input.employeeId, status: input.status }),
+})
+```
+
+Declare the filter / pagination fields in the descriptor's `input` schema so the client can pass them; the executor reads them off `input`.
+
+**You don't need a `toView` projection layer** — the `output` schema already shapes the wire result. `crud.list` returns full rows, and on encode Effect **strips every column the output schema doesn't declare** (a tight `Schema.Struct({ id, name })` ships only `id` + `name`, whatever else the row holds), and a `timestampMs` field normalizes a `Date` to epoch ms. So select fields by naming them in `output`, and normalize dates with the wire field schemas — no per-table view function. (Renames are expressible via a Schema transform if you need them.)
+
+### `columns` — don't even READ what you drop
+
+The output schema stops a column reaching the client; `columns` stops it being read at all. Use it when a table carries something wide that a list view never shows — a long text body, a big `json()` blob:
+
+```ts
+export default crud.list('articles', { columns: ['id', 'title', 'createdAt'] })
+// the large `body` is never SELECTed, transferred from the DB, or decoded
+```
+
+`.serverOnly()` columns are removed from the projection automatically — they're stripped from the response anyway, so reading them is pure waste.
+
+**Trap:** an eager `include` branch joins on a foreign key, so a projection that omits that FK breaks the relation. Keep the FK in `columns` when you also pass `include`.
+
+## What they deliberately don't do — authorization
+
+A guard runs *before* the executor, so gating lives on the **descriptor**, not the handler — an executor cannot gate itself. Keep every write descriptor guarded:
+
+```ts
+export default defineMutation({
+  name: 'accounts.create',
+  input: AccountInput,
+  output: Account,
+  guards: [requireScope('accounts:write')],   // ← the gate; crud.create does not add one
+})
+```
+
+## Scope — why the schema is still hand-written
+
+These helpers give you the secure **handler**, not schema derivation. Deriving the descriptor's `input`/`output` from the table automatically would need the table VALUE inside the descriptor file — and a descriptor is loaded value-level by the browser client, so importing a table there drags the store and driver into the browser bundle (the boundary guard aborts the boot; `rowSchema` is server-only for exactly this reason). Full schema-derivation, and a boot audit that fails when a `tenant()` table's list reads unscoped or a write goes ungated, are a separate planned pass — the handler defaults above are the part that ships browser-safe today and closes the leak class.
+
+
+
 ---
 
 <!-- source: en/data/subscribers.md -->

package/templates/agent-docs/database/misc.md

@@ -225,6 +225,38 @@ Precedence, exactly:
 3. **`.safe()`** on an encrypted column suppresses the implied secret and copies
    it verbatim — say this only when you have genuinely reviewed the plaintext.
 
+## `.serverOnly()` — never to a client
+
+A THIRD, independent axis. `.sensitive()` / `.safe()` are about **data export
+masking**; `.encrypted()` is about **storage at rest**; `.serverOnly()` is about
+**wire exposure** — a column marked `.serverOnly()` is read normally by server
+code but must NEVER be serialized to a client:
+
+```ts
+keyHash: text().serverOnly(),   // an auth middleware verifies it; a client never sees it
+```
+
+The three are orthogonal — a column can carry any combination:
+
+```ts
+keyHash:      text().serverOnly(),               // a hash you never ship (not secret at rest — it IS the digest)
+recoveryNote: text().encrypted(),                // encrypted at rest, but the owner may read it → not serverOnly
+apiToken:     text().encrypted().serverOnly(),    // secret at rest AND never to a client
+```
+
+Enforcement: the [`crud.*` read helpers](/docs/data/crud) strip `.serverOnly()`
+columns from every returned row **automatically** — you declare the exposure
+policy once at the schema and can't forget it on a handler. For a hand-written
+query, omit the column from the `output` schema (and don't put it in the returned
+object) — and `voltro dev` **warns at boot**, naming the query and column, if a
+wire-reachable query's output declares a `.serverOnly()` column of its `source`
+table, so a secret can't ship on the wire by omission-mistake.
+
+Distinct from `.encrypted()` on purpose: encryption at rest says nothing about
+who may receive the plaintext — a private note you decrypt *for its owner* is a
+valid case, so treating "encrypted" as "never to a client" would be wrong. State
+the exposure policy explicitly.
+
 ## Worked example
 
 ```ts

package/templates/agent-docs/database/querying.md

@@ -1044,6 +1044,35 @@ The framework deliberately avoids the Prisma / TypeORM "auto-generated junction"
 
 3. **Schema is explicit**. Looking at your `database/` directory tells you exactly which tables exist. No hidden auto-generated tables to chase down at migration time.
 
+## Writing links — `store.links`
+
+Reconciling the set of links from one row (a post's tags, a user's orgs) by hand — read the current rows, work out which to insert and which to delete — is fiddly and easy to get wrong. A drop-all-then-reinsert shortcut loses data when two requests overlap and makes a reactive subscription on the junction churn *every* row even when nothing changed. `ctx.store.links(junctionTable, anchor)` does the diff for you:
+
+```ts
+// anchor names the source column + id; the target column is auto-detected
+await ctx.store.links('org_memberships', { userId: user.id }).set(orgIds)  // reconcile to exactly orgIds
+await ctx.store.links('org_memberships', { userId: user.id }).add([orgId]) // idempotent — no-op if already linked
+await ctx.store.links('org_memberships', { userId: user.id }).remove([orgId])
+const orgIds = await ctx.store.links('org_memberships', { userId: user.id }).list()
+```
+
+`set(targetIds)` writes only the **difference**: the missing links are inserted, the surplus deleted, and links that are already correct are left untouched — so a reactive consumer sees a change only for what actually changed, and it returns `{ added, removed }`. `add` and `remove` read first and act only on the genuine delta, so both are idempotent.
+
+The **target column** is the junction's *other* `reference()` column — the one the anchor doesn't name. A junction with anything but exactly two reference columns is refused (write it by hand with `insertMany` / `deleteMany`). The writes go through the normal store path, so a junction that carries `tenant()` / `audit()` gets those columns stamped as usual.
+
+`set` / `add` / `remove` manage only the two FK columns. For a junction that carries **per-row payload** — a membership `role`, a `capacity` value — use `setRows`, which diffs on the (source, target) pair AND updates the payload:
+
+```ts
+await ctx.store.links('team_capacities', { teamId: team.id }).setRows([
+  { projectId: 'p1', capacity: 40 },
+  { projectId: 'p2', capacity: 20 },
+])
+// added rows inserted with payload, removed deleted, a surviving row whose payload
+// CHANGED is updated, an unchanged one is left untouched → { added, removed, updated }
+```
+
+Only rows whose payload actually differs are written, so a reactive consumer sees a change exactly where the data changed — the diff-based replacement for a drop-and-reinsert on a data-carrying junction. Payload is compared by strict per-column equality (scalars like `capacity` / `role`).
+
 ## SQL shape
 
 The framework emits an INNER JOIN through the junction:

package/templates/agent-docs/internationalization.md

@@ -178,13 +178,20 @@ useT('does.not.exist')             // ✗ compile error — not a catalog key
 
 It's almost pure type refinement — the runtime is the same `useT` / `useTFn` / `<T>` (plus a `.dynamic` escape, below), only the signatures narrow to your catalog. Requires the base catalog to be `as const` (so its message strings survive as literal types).
 
-**Scope.** Simple `{name}` and single-argument `{count, number}` placeholders are extracted and required. For a *nested* inline ICU message (`{count, plural, one {…} other {…}}` / `select`), the **top-level arg** (`count`) is required and a branch's inner text is NOT mistaken for a var — so `t('duration', { count })` typechecks and renders. A REAL var nested inside a branch (`other {# — {discipline}}`) is not collected, so it reads as *not required* rather than wrongly required; pass it via the loose values bag. Pluralising in JS over simple `{count}` messages (`items.map((i) => t('cart.one', { count: i.n }))`) stays fully typed. `<T>` gets a typed key with loose values, because its rich-text `<tag>` renderers can't be modelled by placeholder extraction.
+**Scope.** Simple `{name}` and single-argument `{count, number}` placeholders are extracted and required. A *nested* inline ICU message (`{count, plural, one {…} other {…}}` / `select`) is fully parsed: the **top-level arg** (`count`) AND a real var nested inside a branch are both required, while a branch's literal text is never mistaken for a var. So for `'{count, plural, one {# blocker in {discipline}} other {# blockers in {discipline}}}'`, `t('blockers', { count, discipline })` is required — omit `discipline` and it's a compile error, not a render-time throw:
+
+```tsx
+t('blockers', { count: n, discipline })   // ✓ both required — discipline lives inside the branches
+```
+
+`<T>` gets a typed key with loose values, because its rich-text `<tag>` renderers can't be modelled by placeholder extraction.
 
 ### Runtime-computed keys — `t.dynamic`
 
 For a key you build at runtime, do NOT cast it to the catalog key union — that union spans placeholder-bearing keys, so the call then demands a spurious 2nd ICU arg. Use `t.dynamic`, a plain-string escape with no forced args, on both `useT` and the `useTFn()` result:
 
 ```tsx
+import { useTFn } from '@app/messages' // your createTypedMessages() barrel — `.dynamic` lives on these
 const t = useTFn()
 t.dynamic(`status.${row.state}`)                 // ✓ plain string, no forced arg
 t.dynamic(`greeting.${kind}`, { name })          // values still allowed, but loose

package/templates/agent-docs/reference.md

@@ -985,6 +985,41 @@ export default (input: { prompt: string }) =>
   })
 ```
 
+### Writing a wrapper that PROVIDES a service
+
+A helper that provides a service must be generic over `R` and **subtract** the tag
+it provides, or it silently narrows what callers may pass it. The failure mode is
+confusing because it shows up at the CALL site, not in the wrapper:
+
+```ts
+import { Context, Effect } from 'effect'
+
+class Tenant extends Context.Tag('Tenant')<Tenant, { readonly id: string }>() {}
+
+// WRONG — `R` defaults to `never`, so this only accepts effects that need
+// nothing else. Pass it an effect that also needs `Db` and it stops compiling.
+const withTenantBad = <A, E>(id: string, effect: Effect.Effect<A, E>) =>
+  Effect.provideService(effect, Tenant, { id })
+
+// RIGHT — generic over `R`, and the return type SUBTRACTS the tag it provided.
+const withTenant = <A, E, R>(
+  id: string,
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, Exclude<R, Tenant>> =>
+  Effect.provideService(effect, Tenant, { id })
+```
+
+`Exclude<R, Tenant>` is what makes the wrapper composable: the caller's remaining
+requirements pass through untouched, and only the tag you actually supplied
+disappears. Without it, the wrapper's own signature dictates the caller's entire
+requirement set.
+
+The same rule applies to any callback the framework takes from you (an AI tool
+body, a media generator, a workflow step): declare its `R` as `unknown` rather
+than letting it default to `never`, then let the framework's own bridge discharge
+it. A callback typed `Effect<A, E, never>` cannot use ANY service, which is
+rarely what you meant.
+
 ## Context By Primitive
 
 | Server file | Transaction | Typical store usage | External I/O | Returns |

package/templates/agent-docs/routing.md

@@ -793,6 +793,23 @@ Two consequences worth designing around:
   a side effect), put it in an effect or use `useSubscription` — do not rely on
   the loader firing a second time.
 
+#### SSR first paint, then live — `initialSnapshot`
+
+When a page wants the SSR-rendered data AND a live subscription, hand the loader's value to `useSubscription` as its `initialSnapshot`. The loader fetches the data on the server with `ctx.query`; the subscription shows that value at the first paint with `loading: false` — it is real server data, not a placeholder — then swaps to the live stream the instant its first snapshot arrives:
+
+```tsx
+export const loader = async ({ query }) => query('employees.me', {})
+
+export default function Profile() {
+  const seed = useLoaderData<Employee>()
+  // First paint shows the SSR value; the WS stream takes over seamlessly.
+  const { data } = useSubscription<Employee>('app', 'employees.me', {}, { initialSnapshot: seed })
+  return <ProfileCard employee={data} />
+}
+```
+
+Because the SSR markup and the hydration render read the same loader value, they match — no hydration flicker — and you don't hand-build a seed store to bridge the two. This is distinct from `fallback`, whose value never came from the server and so keeps `loading: true`; use exactly one of the two.
+
 Client-side navigation is unchanged: moving to another route runs that route's
 loaders in the browser as usual. A `spa` page has no server render, so its
 loader runs on the client on first mount.

package/templates/agent-docs/workflows.md

@@ -1308,6 +1308,37 @@ test('notes.summarise retries the LLM step', async () => {
 
 The result includes `{ status, output, error, steps, runId }`. `runner.inspect(runId)` returns the assembled run later without re-running it.
 
+## A start with the wrong payload
+
+`ctx.workflows.start(name, payload)` validates the payload against the workflow's
+`payload` schema **before** the engine sees it. A mismatch throws a
+`WorkflowPayloadError` naming three things:
+
+```
+Workflow "sprint.report" was started with an invalid payload. missing required
+field(s): teamId. { readonly teamId: string } └─ ["teamId"] is missing
+```
+
+The error also carries them structurally — `workflowName`, `missingFields`,
+`_tag: 'WorkflowPayloadError'` — so a handler can branch on it.
+
+This matters most where nobody is watching. A **cron** whose payload drifted from
+the workflow's schema fails on every single firing; the schedule run is recorded
+`failed` in `_voltro_schedule_runs` and the log line is an **error**, not a warn,
+so `voltro logs --level error` and any alert wired to it see it. A nightly job
+that has been dead since a refactor is the exact failure this pair of behaviours
+exists to surface.
+
+An unknown workflow name lists the registered ones, so a rename reads differently
+from a deletion:
+
+```
+Unknown workflow: sprint.reports. Registered workflows: billing.run, sprint.report.
+```
+
+Validation runs on the **decoded** value, so a `Schema.Date` payload accepts a
+`Date` — passing the already-domain-shaped value is correct and is not rejected.
+
 ## Anti-patterns
 
 - **Querying old table names.** Use `_voltro_workflow_runs`, `_voltro_workflow_run_steps`, and `_voltro_workflow_run_events`.