@voltro/cli 0.32.0 → 0.34.0

package/templates/agent-docs/deployment.md

@@ -300,9 +300,9 @@ cause.
 | `VOLTRO_STORAGE_SECRET` | optional (`@voltro/plugin-storage`) | Signs private-file grant tokens; falls back to the session secret if unset |
 | `AI_PROVIDER` | when using `@voltro/ai` | `anthropic` / `openai` / `mock` |
 | `AI_API_KEY` | with `AI_PROVIDER` | Provider's API key |
-| `SSR_CACHE` | optional | `memory` (default) or `postgres` (needs `PG_*` set too) for the ISR cache |
+| `SSR_CACHE` | optional | `memory` (default) or `postgres` for the ISR cache. `postgres` needs a database in the WEB process's env (`DB_URL` / `DB_HOST` / `PG_HOST`) — without one it aborts the boot in production rather than falling back to memory |
 | `VOLTRO_API_ORIGIN` / `VOLTRO_API_ORIGIN_<NAME>` | split web/api deploy with SSR pages | The api's internal origin the WEB pod uses for SSR `ctx.query` (`http://api.<ns>.svc.cluster.local`). Per-api `_<NAME>` (name upper-cased) wins over the shared one and over `serverUrl`. Never sent to the browser |
-| `PORT` | optional | App's listen port (overrides `app.config.ts.port`) |
+| `PORT` | optional | App's listen port. Outranks `--port` and `app.config.ts` `port:` — a platform that assigns a port sets this one, so it has to win. Unset, the app binds its declared `port:`, then 4000 (api) / 5173 (web). |
 | `VOLTRO_INSPECT` | optional | `off` to disable `_voltro/inspect/*` in prod |
 | `VOLTRO_INSPECT_TOKEN` | recommended | Bearer token guard on inspect endpoints |
 | `VOLTRO_DASHBOARD_APPS` | dashboard only | JSON `[{name?,url,token?}]` — target apps + inspect tokens the deployed DevTools dashboard shows (served at runtime from `/api/dashboard/config`) |
@@ -833,6 +833,8 @@ VOLTRO_SESSION_SECRET_PREVIOUS=<old>   # still verifies live cookies
 
 Keep `_PREVIOUS` in place for one session-TTL window, then drop it. Existing cookies verify against `previous` until they naturally expire — no live session is invalidated.
 
+> **If you embed the framework's middleware yourself** rather than booting through `voltro serve`, there is no boot gate to catch a missing secret. In that case a presented `voltro:session` cookie that cannot be verified now logs, once per process and at error level, that no credential-expiry bound is being imposed — so realtime subscriptions on that connection will not be cut off when the session expires. It is a diagnostic, not a refusal: a stale `voltro:session` cookie from another app on the same host is a normal thing for a browser to carry, and failing the request would turn that into a denial of service.
+
 ## 2. Kubernetes health probes
 
 `voltro serve` exposes two unauthenticated endpoints, both handled **before** any rate-limit interceptor:
@@ -1002,12 +1004,21 @@ indexed query instead of scanning every table). Force a full re-introspect with
 
 ## 4. Request limits & DoS
 
-`POST /rpc` (the buffered JSON endpoint the SSR loaders use) rejects an over-`Content-Length` body with **413** *before* buffering it into memory:
+`POST /rpc` (the buffered JSON endpoint the SSR loaders use) is capped, and the cap is enforced **as bytes arrive**:
 
 ```sh
 VOLTRO_MAX_RPC_BODY_BYTES=8388608   # default 8 MiB
 ```
 
+A declared `Content-Length` over the cap is refused up front, so an honest client
+gets its **413** without uploading anything — a courtesy, not the enforcement,
+since a `Transfer-Encoding: chunked` body declares no length at all. The byte
+counter is the enforcement: it stops accumulating the moment the running total
+crosses the limit, drains the rest of the upload rather than dropping the
+connection, and answers **413**. Both shapes therefore end in the same status
+code, and the refusal is logged under the `voltro:security` scope with the cap
+and the byte count at which the server stopped reading.
+
 Scope: this guards the `/rpc` JSON path only. File uploads ride separate storage routes with their own `limits.maxBytes`, and WebSocket frames are capped by the `ws` library default (100 MiB).
 
 **Put per-IP rate limiting and the primary body-size cap at the ingress** — that is the correct layer: it holds per-IP state and works across replicas, which an in-process limit can't.
@@ -1020,6 +1031,51 @@ nginx.ingress.kubernetes.io/limit-rps: "20"
 
 For **app-level** throttling (per-subject / per-tenant, e.g. an expensive action), use `@voltro/plugin-ratelimit` and the plugin `onHttpRequest` interceptor seam. It complements the ingress cap — it does not replace it.
 
+**There is no rate limit in the box.** The body cap above is the only request guard the runtime applies by default; `@voltro/plugin-ratelimit` is opt-in, so an app that has not installed and configured it has no per-IP, per-API-key or per-tenant cap on `/rpc` at all. The one on-by-default throttle anywhere in the framework is `plugin-auth`'s [brute-force lockout](/docs/authentication/passwords#brute-force-lockout), which covers sign-in credential attempts and nothing else. Treat the ingress limit as required, not as belt-and-braces.
+
+### Per-IP limits need a trusted proxy
+
+The address the runtime rate-limits, geo-blocks and audits by is
+`socket.remoteAddress` — **not** `x-forwarded-for`, which any client can write.
+Behind an ingress that means every request counts against the proxy's address —
+and every `sessions.ipAddress` row records the proxy — until you declare the hop:
+
+```ts
+// app.config.ts
+export default {
+  security: {
+    trustedProxies: ['private'],   // or: ['loopback'] · ['10.0.0.0/8'] · ['2'] · ['*']
+  },
+}
+```
+
+The same setting decides whether `x-forwarded-proto` is believed, which is what
+lets the runtime emit HSTS behind a TLS-terminating load balancer. Override it
+on a running deployment with `VOLTRO_TRUSTED_PROXIES=private` (comma-separated).
+
+### Cross-site protection and its allowlist
+
+Every state-changing request — `POST /rpc`, the `/ws` upgrade, every REST route
+projected from a `publicApi:` mutation, everything in `apiConfig.restRoutes`,
+and `POST /v1/api-keys` — refuses a browser request whose `Origin` is neither
+the `Host` it was sent to nor an allowlisted origin. **A split web/api
+deployment must declare its web origin** or the browser gets a 403 on every
+mutation, REST write and socket:
+
+```ts
+// app.config.ts
+export default {
+  security: {
+    allowedOrigins: ['https://app.example.com'],
+  },
+}
+```
+
+The environment override is `VOLTRO_ALLOWED_ORIGINS` (comma-separated).
+Server-to-server callers (SSR loaders, mobile SDKs, other services) send no
+`Origin` and are unaffected. Full detail in
+[Security](/docs/security/overview#cross-site-requests-are-refused).
+
 ## 5. Multi-tenant isolation
 
 Tables carrying the `tenant()` mixin are auto-scoped to the request's tenant — nothing more to do there. The gap is the **anonymous** request that matches no auth strategy: by default it resolves to a tenant-less anonymous Subject that can read any non-`tenant()` table across the DB.
@@ -1079,6 +1135,12 @@ sink, stops accepting new connections while **finishing already-accepted
 requests**, and closes the SQL connection pool **last** (waiting for in-flight
 transactions). Verified under concurrent load — accepted requests complete.
 
+The **transactional-outbox worker** is part of that sequence: its poll timer and
+its change subscription are released, and a delivery already in flight is
+awaited, before the pool closes. An outbox row that was still pending is not
+lost — it is durable, and the next process's first pass picks it up, which is
+one of the three reasons that poll exists.
+
 **But the app cannot drain a rolling update by itself.** The runtime
 (`NodeRuntime`) owns the `SIGTERM` signal and closes the HTTP listener promptly —
 so a request that *arrives* during shutdown is refused. Failing readiness from
@@ -1168,13 +1230,38 @@ scaled. An operator's second pod died on `Connection timed out` for exactly
 this. `voltro serve` now prints the number and the arithmetic at boot:
 
 ```
-db pool: max=10 per replica (DB_MAX_CONNECTIONS) × 4 replicas = up to 40 connections.
+db pool: max=10 per replica (DB_MAX_CONNECTIONS) + 1 = 11 × 4 replicas = up to 44 connections.
+Check that against your database's limit. PLUS 1 outside the pool (CDC LISTEN consumer) —
+those do not come out of the pool budget, they come out of the DATABASE's.
 ```
 
 Set `REPLICA_COUNT` from your deployment (Helm: `{{ .Values.replicaCount }}`) and
 the line does the multiplication for you; without it the line still names the
 formula. `voltro dev` deliberately does not print it — one process, no replicas.
 
+**Some connections are not in the pool, and the count is per process.** A
+connection running `LISTEN` cannot be returned to a pool, so the driver opens a
+standalone one. There are three such places and a full deployment can hold all
+three:
+
+| Process | Connection | When |
+|---|---|---|
+| api `voltro serve` | CDC `LISTEN` consumer | `changeStrategy: 'cdc'` (the default on postgres) |
+| web `voltro start` | ISR invalidator `LISTEN` | any page declares `cacheInvalidatesOn` |
+| web `voltro start` | postgres ISR cache client | `SSR_CACHE=postgres` |
+
+The third is not a `LISTEN` at all, which is why counting `LISTEN` rows in
+`pg_stat_activity` undercounts. Each process prints its own number in the boot
+line above — including `No connections outside the pool in this process` when
+there are none, so "counted, zero" is distinguishable from "not counted".
+
+**And a rolling update needs the surge pod's connections too.** A budget sized
+for `replicaCount` is exactly full at steady state and short during every
+deploy: `maxSurge` adds a pod that opens a full pool of its own. If that pod
+cannot connect it never becomes ready, so the rollout does not complete and the
+cluster stays at the higher pod count — the deploy cannot free itself. Size for
+`(replicaCount + maxSurge) × (DB_MAX_CONNECTIONS + out-of-pool)`.
+
 **`POD_IP` is each replica's identity, not only a workflow setting.**
 
 ```yaml
@@ -1203,6 +1290,67 @@ operator's own guidance, and better than ours was: a value taken from the
 release namespace cannot be left out of one environment's config file, because
 there is no file to forget.
 
+### The framework's own background pollers
+
+Two framework tasks ride the coordinated scheduler and write a row into
+`_voltro_schedule_claims` on every tick they win: the workflow **admission
+drainer** and the offloaded-**inference dispatcher**.
+
+**Where a peer replica's write is visible here, they do not poll at all.** Each
+runs one tick at startup — not optional; it is what finds work a previous
+process left behind — and then stops until something arrives. The wake comes
+from the change events their queue tables already emit, which is the same
+mechanism the rest of the framework's reactivity runs on. Measured against a
+real Postgres on a deployment that never uses either queue: **2 claim rows in
+five minutes**, one per task, both written at boot.
+
+That "where" is the whole condition, and it is satisfied by Postgres
+LISTEN/NOTIFY or by a broadcast broker (Redis/NATS — which a multi-replica
+deployment already runs for cross-replica reactivity). Without either, a
+*remote* replica's enqueue produces no local event, so stopping would mean
+sleeping through it. There the tasks back off to a ceiling instead:
+
+```sh
+VOLTRO_POLL_CEILING_MS=30000   # how long an arrival can wait when NOTHING woke the task
+```
+
+Nothing is lost in that case either — the replica that enqueued always sees its
+own write inline and drains it itself. What the ceiling covers is the narrower
+case of a *crashed* writer's lease being reclaimed by someone else.
+
+A number worth knowing before you tune anything: on a two-replica deployment
+that had never enqueued into either queue, these two tasks accounted for **99.3 %
+of the claim ledger** — 2 506 rows an hour against 18 from the app's own eight
+schedules. A fixed interval has no way to learn a queue is empty. That is what
+changed; the ceiling is the fallback, not the fix.
+
+### Tuning the cadence
+
+The intervals are declarable, with defaults most apps never change:
+
+```ts
+// app.config.ts
+export default {
+  scheduling: {
+    admissionDrainMs: 1000,   // workflow admission drainer
+    inferenceTickMs:  250,    // offloaded-inference dispatcher
+    cancelSweepMs:    2000,   // cancelOn sweep
+    pollCeilingMs:    30000,  // idle ceiling, where nothing can wake a task
+  },
+}
+```
+
+Each has a matching env var — `VOLTRO_ADMISSION_DRAIN_MS`,
+`VOLTRO_INFERENCE_TICK_MS`, `VOLTRO_CANCEL_SWEEP_MS`, `VOLTRO_POLL_CEILING_MS` —
+which **overrides** the config field, the same way `VOLTRO_TENANT_ISOLATION`
+overrides `tenancy.isolation`. The config is what a project declares; the env var
+is what an operator changes on a running deployment without a rebuild.
+
+Lowering an interval does **not** make anything more responsive: an arrival
+already wakes the task at once. It only bounds the case where nothing announced
+the work. A value of `0` or a non-number is ignored rather than honoured — a
+zero interval would turn an idle task into a spin.
+
 ### Workflow failover across replicas
 
 On a **SQL store** (postgres / mysql / mariadb / mssql), durable workflows survive a replica crash: completed `step({...})` activities are checkpointed in the cluster journal, so when a replica dies mid-run, a **surviving replica takes over the run and continues it from the last completed step** — it replays the completed steps rather than re-running them. (On sqlite the engine is single-process — durable within one replica, no cross-replica failover.) Two requirements:
@@ -1229,6 +1377,10 @@ Lower the lease for **faster failover**, at the cost of **false-positive reclaim
 - [ ] Serving pods run `voltro serve` (not `voltro dev`), with `VOLTRO_AUTO_MIGRATE=0`
 - [ ] Schema applied by a pre-deploy Job / initContainer (`voltro db apply`), not in the serving pod
 - [ ] `VOLTRO_MAX_RPC_BODY_BYTES` sane; ingress caps body size + per-IP rate
+- [ ] `VOLTRO_TRUSTED_PROXIES` set if you run behind an ingress AND rate-limit per IP
+- [ ] `VOLTRO_ALLOWED_ORIGINS` set if the web app is on a different origin than the api
+- [ ] Security headers reviewed (`VOLTRO_SECURITY_HEADERS`, `VOLTRO_CSP`); HSTS reaching the browser over https
+- [ ] Every `*.webhook.tsx` declares its verification, and each signature-verified one has its `VOLTRO_WEBHOOK_SECRET_<ID>`
 - [ ] `auth.anonymousTenantRequired: true` (unless the app serves anonymous public data)
 - [ ] `OTEL_EXPORTER_OTLP_ENDPOINT` + `OTEL_SERVICE_NAME` pointed at your collector
 - [ ] `VOLTRO_LOG_FORMAT=json`; `sentryPlugin()` + `SENTRY_DSN` for errors

package/templates/agent-docs/introduction.md

@@ -23,27 +23,52 @@ This guide gets you from zero to a running stack in under a minute.
 
 ## Scaffold a project
 
-`create-project` runs **inside an existing pnpm workspace** — it walks up from your current directory looking for `pnpm-workspace.yaml` and writes the project into that workspace's `apps/` directory. Run it from the root of your workspace:
+A Voltro monorepo is a pnpm workspace. `create-project` walks up from your current directory looking for `pnpm-workspace.yaml` — and **when there is none, it creates the workspace root right there** before scaffolding. So an empty directory is a perfectly good starting point:
 
 ```bash
+mkdir acme && cd acme
+
 pnpx voltro create-project acme \
   --api api-backend \
   --web frontend-landing \
   --port-range 5190-5199
 ```
 
-This creates `apps/acme/` inside the workspace with an `api/` (Voltro backend) and a `web/` (landing page) app. The project name is kebab-cased (so `Acme` becomes `acme`). The `--port-range` is recorded in `project.json` so every new app added later gets a unique port without you thinking about it.
+You get:
+
+```text
+acme/
+  pnpm-workspace.yaml     # the package globs + the install-script decisions
+  package.json            # dev / build / test / typecheck (plain `pnpm -r` scripts)
+  .gitignore              # incl. .env.local, where `voltro dev` mints your secrets
+  .git/                   # unless you were already inside a repo
+  AGENTS.md + CLAUDE.md   # the agent guide, seeded per project
+  apps/acme/
+    api/                  # Voltro backend
+    web/                  # landing page
+    project.json          # the project's port range + app map
+```
+
+The project name is kebab-cased (so `Acme` becomes `acme`). The `--port-range` is recorded in `project.json` so every new app added later gets a unique port without you thinking about it.
+
+Three things worth knowing about this first run:
+
+- **The install-script question is already answered.** pnpm refuses to finish an install that has an undecided `postinstall` (`ERR_PNPM_IGNORED_BUILDS`), and a Voltro workspace pulls three — all transitive, none of them anything you picked. `pnpm-workspace.yaml` ships the answers with a reason on each line: `esbuild: true` (vite's compiler binary), `@parcel/watcher` and `msgpackr-extract` `false` (optional native accelerators with pure-JS fallbacks, so your first install needs no C++ toolchain). Change your mind with `pnpm approve-builds`.
+- **Already have a workspace?** Nothing is overwritten. An existing `pnpm-workspace.yaml` is left alone, and only root scripts you *don't* already define are filled in. To prepare a directory without scaffolding anything yet, run `voltro init` — it creates the same workspace root and stops there.
+- **It registers the project with the cloud control plane** (self-hosted tracking) unless you pass `--no-register`. Offline, in CI, or just not interested: `--no-register` skips the network call entirely.
 
 ## Boot it
 
-Install and run from the **workspace root** — there is no top-level `acme/` directory to `cd` into; the project lives under `apps/acme/`:
+Install and run from the **workspace root** — there is no top-level `acme/api` to `cd` into; the project lives under `apps/acme/`:
 
 ```bash
 pnpm install
 pnpm dev
 ```
 
-The dev orchestrator boots every app in parallel with HMR. By default:
+The root `dev` script is `pnpm -r --parallel dev`: it runs every workspace package that has a `dev` script, at once. No task runner to install — and apps that own their own dev loop (an Expo mobile app, a serverless bundle) simply don't define `dev`, so they opt out by construction. To run one app on its own, `pnpm --filter @acme/api dev`.
+
+By default:
 
 - `api` listens on `:4000` (RPC over WebSocket on `/ws`)
 - `web` listens on the first port in your range (e.g. `5190`)
@@ -153,10 +178,10 @@ useMutation('billing', 'invoices.pay')
 Every procedure descriptor declares a globally unique `name`. That name is the **RPC tag**:
 
 ```ts
-defineQuery({ name: 'todos.list', /* ... */ })
-defineMutation({ name: 'todos.create', /* ... */ })
-defineAction({ name: 'support.ping', /* ... */ })
-defineStream({ name: 'agent.run', /* ... */ })
+defineQuery({    name: 'todos.list',   guards: [{ scope: 'todos:read' }],   /* ... */ })
+defineMutation({ name: 'todos.create', guards: [{ scope: 'todos:write' }],  /* ... */ })
+defineAction({   name: 'support.ping', guards: [{ scope: 'support:diagnostics' }], /* ... */ })
+defineStream({   name: 'agent.run',    guards: [{ scope: 'agents:run' }],   /* ... */ })
 ```
 
 Hooks use the API name plus RPC tag. There is no hand-written client SDK per endpoint.
@@ -172,6 +197,34 @@ Procedures are split into two files:
 
 This keeps the wire contract importable from the client while server code stays server-only.
 
+## Every Procedure Declares Who May Call It
+
+Dropping a descriptor into the tree **puts it on the wire**. So each one carries an access decision, and a descriptor that carries none is **refused at boot** — by `voltro dev`, by `voltro serve`, and by `voltro doctor` as a preflight. Exactly one of three:
+
+```ts
+export const invoiceList = defineQuery({
+  name: 'invoices.list',
+  guards: [{ scope: 'invoices:read' }],   // the caller must hold a scope
+  /* ... */
+})
+
+export const pricing = defineQuery({
+  name: 'pricing.current',
+  openAccess: 'public pricing page — reads no caller data',  // anyone may, and why
+  /* ... */
+})
+
+export const stampAudit = defineMutation({
+  name: 'auditLog.stamp',
+  internal: true,                          // not on the wire at all
+  /* ... */
+})
+```
+
+`openAccess` takes a **reason, not a boolean**, and that is the whole design: it is what makes *"we decided this is open"* distinguishable from *"nobody looked"*. Without it, the only way to satisfy the gate would be to invent a guard — and the guard people invent is one every caller already holds, which reads as protection and enforces nothing.
+
+The one to expect first: your **first self-written procedure file** will not boot until it has one of these three. Full rules in [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 ## The Main Primitives
 
 | Primitive | Use it for | Client hook | Durable? | Reactive? |
@@ -208,8 +261,11 @@ const { data: todos } = useSubscription('app', 'todos.list', {})
 When a mutation commits, the runtime emits change events. Queries whose `source` matches the changed table can update automatically.
 
 ```ts
-defineQuery({ name: 'todos.list', source: 'todos', /* ... */ })
-defineMutation({ name: 'todos.create', target: { table: 'todos', op: 'insert' }, /* ... */ })
+defineQuery({ name: 'todos.list', source: 'todos', guards: [{ scope: 'todos:read' }], /* ... */ })
+defineMutation({
+  name: 'todos.create', target: { table: 'todos', op: 'insert' },
+  guards: [{ scope: 'todos:write' }], /* ... */
+})
 ```
 
 There is no `refetch` as the normal path. The subscription lives for the lifetime of the component.
@@ -287,11 +343,14 @@ You don't need Docker for dev — Voltro ships an in-memory store. You'll want D
 The CLI runs from the registry without a global install:
 
 ```bash
+mkdir my-app && cd my-app
 pnpx voltro create-project my-app
 ```
 
 This is the smallest blast radius — `pnpx` fetches the latest CLI release into the local cache and discards it after.
 
+An empty directory is enough: `create-project` writes the pnpm workspace root (`pnpm-workspace.yaml`, a root `package.json` with `dev`/`build`/`test`/`typecheck`, a `.gitignore`, `git init`) when it can't find one above you. Inside an existing workspace it adds nothing but the project. `voltro init` does the workspace-root half on its own, for when you want the repo prepared before you pick templates.
+
 ### 2. Per-project dependency
 
 Once your project exists, the CLI is already a `dependency` of the `api` app's `package.json`, so:
@@ -300,7 +359,7 @@ Once your project exists, the CLI is already a `dependency` of the `api` app's `
 pnpm --filter @my-app/api exec voltro dev
 ```
 
-The api template's own `dev` script is `voltro dev .`, so `pnpm dev` in the app runs the CLI directly. If your workspace ships a turbo dev pipeline, `pnpm dev` at the repo root delegates to it. You rarely call the filtered form directly.
+The api template's own `dev` script is `voltro dev .`, so `pnpm dev` in the app runs the CLI directly. At the workspace root, `pnpm dev` is `pnpm -r --parallel dev` — every app at once. You rarely call the filtered form directly.
 
 ### 3. Global install
 
@@ -318,7 +377,7 @@ voltro version
 voltro list-templates
 ```
 
-The second command prints the app templates the CLI can scaffold. You'll see the `api-backend*` templates (`api-backend`, `api-backend-mail`, `api-backend-mariadb`, `api-backend-storage`) and the `frontend-*` templates (`frontend-blank`, `frontend-docs`, `frontend-landing`) — that's everything in place.
+The second command prints the app templates the CLI can scaffold — **dozens** of them, across four kinds: `api-*` backends, `frontend-*` web apps, an `edge-functions` serverless bundle, and `mobile-app` (Expo). The output is generated from the templates the installed CLI actually ships, so it is the authority on what your version can scaffold; do not go by a list in a doc. For what each one demonstrates and when to pick it, see the [app-template reference](/docs/reference/templates).
 
 ## Editor setup
 
@@ -363,13 +422,13 @@ Voltro replaces router and registry config with **filesystem conventions**. Drop
 
 | Suffix | What it is | Wired into |
 |---|---|---|
-| `*.query.ts` | Browser-safe reactive query descriptor: `defineQuery({ name, source, input, output })`. | Typed RPC group + client metadata. |
+| `*.query.ts` | Browser-safe reactive query descriptor: `defineQuery({ name, source, input, output, guards })`. | Typed RPC group + client metadata. |
 | `*.query.server.ts` | Server executor for the matching query descriptor. | Reactive subscription runtime. |
-| `*.mutation.ts` | Browser-safe mutation descriptor: `defineMutation({ name, target, input, output, error })`. | Typed RPC group + auto-optimistic metadata. |
+| `*.mutation.ts` | Browser-safe mutation descriptor: `defineMutation({ name, target, input, output, error, guards })`. | Typed RPC group + auto-optimistic metadata. |
 | `*.mutation.server.ts` | Server executor for the matching mutation descriptor. | Transactional mutation runner. |
-| `*.action.ts` | Browser-safe action descriptor: `defineAction({ name, input, output, error })`. | Typed RPC group. |
+| `*.action.ts` | Browser-safe action descriptor: `defineAction({ name, input, output, error, guards })`. | Typed RPC group. |
 | `*.action.server.ts` | Server executor for the matching action descriptor. | Non-transactional action runner. |
-| `*.stream.ts` | Browser-safe one-shot stream descriptor: `defineStream({ name, input, element, error })`. | Typed streaming RPC group. |
+| `*.stream.ts` | Browser-safe one-shot stream descriptor: `defineStream({ name, input, element, error, guards })`. | Typed streaming RPC group. |
 | `*.stream.server.ts` | Server executor returning an Effect `Stream`. | Plain server-to-client element streams. |
 | `*.workflow.tsx` | A durable Effect workflow. Survives restarts. | `@effect/workflow` runtime. |
 | `*.agent.tsx` | Browser-safe AI agent **descriptor**: `defineAgent({ name, input })`. Codegen-typed routes. | Agent runtime + client types. |
@@ -381,6 +440,18 @@ Voltro replaces router and registry config with **filesystem conventions**. Drop
 
 Procedure descriptors are intentionally separate from server executors. Descriptor files are safe for browser imports and codegen; `.server.ts` files can import the database, file system, SDK clients, secrets, and other server-only modules. Each descriptor has exactly one matching `.server.ts` file with the same primitive suffix. Workflows follow the same split: a browser-safe `*.workflow.tsx` descriptor (importing `workflow` from `@voltro/workflow/define`) paired with a `*.workflow.server.tsx` executor.
 
+### The access decision is not optional
+
+`guards` appears in all four procedure signatures above because dropping a file into the tree **puts it on the wire**, and a wire-exposed procedure has to say who may call it. Exactly one of three:
+
+```ts
+guards: [{ scope: 'notes:read' }]                    // the caller must hold a scope
+openAccess: 'public pricing page — reads no caller data'  // anyone may call it, and why
+internal: true                                        // not on the wire at all
+```
+
+A descriptor that declares none of them is **refused at boot** — by `voltro dev`, by `voltro serve`, and by `voltro doctor` as a preflight. This is the one field a newly-created procedure file is most likely to be missing, and the failure is a boot refusal naming the file rather than a subtle runtime surprise. Full rules, including `openAccess`'s required reason and the per-app `security.defaultDeny` switch: [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 The browser-safe rule is **transitive**, and that is where it usually breaks. The codegen pulls every descriptor (and every workflow descriptor) value-level into `rpcGroup.generated.ts`, which the web client loads — so a descriptor plus *everything it imports* must stay free of server-only code (`node:*`, the `database` handle, `@voltro/ai`, cluster, plugins, `@voltro/protocol/session`). The classic mistake is not a literal `import 'node:crypto'` but a descriptor importing a shared typed-error or helper from a `lib/` file that *also* imports the database — which drags the whole schema graph into the browser bundle. Keep typed errors, Schemas, and pure helpers in files with zero server imports; put DB-backed guards in `.server.ts`. A leak shows up as the web app fetching hundreds of modules / tens of MB on first load, or crashing with `Module "node:crypto" has been externalized for browser compatibility`.
 
 ### Declaring a shared file browser-safe: `*.client.ts`

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

@@ -23,11 +23,13 @@ imports it directly. The React wrappers live behind `@voltro/local-first/react`
 > [`crdtText()` database column](#the-crdttext-database-column) (with its
 > authoritative server-side merge on the write path), the
 > [`SyncClient`](#the-syncclient-bi-directional-wire) that drives the queue over a
-> transport, [presence/awareness](#presence--awareness) via `usePresence`,
-> [durable IndexedDB persistence](#durable-persistence), and the
+> transport, [`useCrdtText`](#a-collaborative-text-field-usecrdttext) — the React
+> binding for a collaborative text field — [presence/awareness](#presence--awareness)
+> via `usePresence`, [durable IndexedDB persistence](#durable-persistence), and the
 > [`localFirst` table mixin](#the-localfirst-table-mixin). What remains is a thin
 > [runtime binding](#whats-shipped-vs-a-runtime-seam) to provisioned infra
-> (a broker at scale, a running app's transport) — not un-built framework code.
+> (a broker at scale) plus the two app-specific tags `useCrdtText` is pointed at —
+> not un-built framework code.
 
 ## CRDT text: `crdtText` + `mergeCrdtStates`
 
@@ -139,6 +141,69 @@ Everything below the two transport functions — the drain loop, retry/attempt
 counting, optimistic local merge, durable persistence — is in the client and
 tested against an in-memory dispatcher that mirrors the server's merge.
 
+## A collaborative text field: `useCrdtText`
+
+`useCrdtText` is the React binding over that wire — one `crdtText()` cell, bound
+to the mutation that writes it and the reactive query that streams it:
+
+```tsx
+import { useMutation, useSubscription } from '@voltro/client'
+import { useCrdtText } from '@voltro/local-first/react'
+
+function BodyEditor({ id }: { id: string }) {
+  const row = useSubscription<{ body: Uint8Array | null }>('app', 'documents.byId', { id })
+  const save = useMutation<{ id: string; body: Uint8Array }>('app', 'documents.setBody')
+
+  const body = useCrdtText({
+    cell: { table: 'documents', id, column: 'body' },
+    remote: row.data?.body ?? null,             // what the server currently holds
+    push: (w) => save.mutate({ id: w.id, body: w.update }),  // deliver a local edit
+  })
+
+  return (
+    <>
+      <textarea value={body.text} onChange={(e) => body.setText(e.target.value)} />
+      {body.synced ? null : <em>saving… ({body.outstanding})</em>}
+    </>
+  )
+}
+```
+
+The hook owns one `SyncClient` per `(table, id, column)` cell — created and
+closed with the component — re-renders on a local edit, an ack or incoming
+merged state, and folds the streamed row back in. It returns `text`,
+`insert(index, text)`, `delete(index, length)`, `setText(next)`, the encoded
+`state`, `outstanding` / `synced`, and `setOnline`.
+
+<Callout type="warn">
+**`setText` is a span diff, and that is the whole point.** A `<textarea>` hands
+you the entire new string, so the obvious binding is "clear the document,
+insert the new text" — a delete-all/insert-all, which is exactly the
+last-write-wins behaviour a CRDT is chosen to prevent: two people typing in
+different paragraphs each erase the other's, and the text looks right on
+whichever peer typed last. `useCrdtText` diffs the common prefix and suffix and
+emits ONE delete plus ONE insert, so an edit outside the changed span survives.
+The diff is exported as `crdtTextEdit(before, after)` if you drive the document
+yourself.
+</Callout>
+
+Two things stay yours to name, because nothing can derive them: **which
+mutation** writes the column and **which query** streams the row. Voltro
+generates no per-table CRUD surface, so the hook takes those two as `push` and
+`remote` — the same shape as `usePresence`'s injected channel. Everything under
+them (client lifecycle, optimistic merge, offline queue, bounded retry, durable
+persistence, the edit encoding) is framework code.
+
+The descriptors on the other end declare the column as bytes-over-base64 —
+`Uint8Array` in the handler, a base64 string on the wire:
+
+```ts
+import { Schema } from 'effect'
+
+// documents.byId output (and documents.setBody input)
+body: Schema.NullOr(Schema.Uint8ArrayFromBase64)
+```
+
 ## Presence & awareness
 
 `usePresence(roomId, self, { channel })` publishes this peer's ephemeral state
@@ -168,6 +233,16 @@ Redis/NATS at scale (both already shipped). `createInMemoryPresenceChannel()` is
 the local/test transport. Join/leave, announce-back discovery, cursor
 propagation, and TTL expiry live in the pure `createPresenceRoom` the hook wraps.
 
+> **Two different hooks share the name `usePresence`, and they are not
+> interchangeable.** THIS one (`@voltro/local-first/react`) is peer-to-peer
+> awareness over a pub/sub channel — `usePresence(roomId, self, { channel })` →
+> `{ presence, others, setPresence }` — for high-frequency cursor/selection
+> state that must never touch the database.
+> [`@voltro/plugin-presence`](/docs/plugins/presence)'s is a server-backed
+> roster — `usePresence(channel, options)` → the list of members whose heartbeat
+> is fresh, plus a `useTyping` indicator, through the app's own rpc. Reach for
+> the plugin for "who is here"; reach for this one for "where is their cursor".
+
 ## The offline sync queue
 
 `useSyncQueue()` is a reactive view over a **pure, tested reducer**: writes made
@@ -252,7 +327,7 @@ code already speaks:
 
 | Runtime seam | What it binds | Why it's a binding, not code |
 | --- | --- | --- |
-| **Sync transport → a running app** | The `SyncClient`'s `push`/`onRemoteState` to one app's `useMutation` + `useSubscription`. | The two functions are app-specific glue; the drain loop, merge, retry, and persistence all ship and are tested. |
+| **Two app-specific tags** | Which mutation writes the `crdtText()` column, and which reactive query streams the row, in [`useCrdtText`](#a-collaborative-text-field-usecrdttext). | Voltro generates no per-table CRUD surface, so there is nothing to derive them from. The client lifecycle, optimistic merge, offline queue, retry, persistence and edit encoding all ship. |
 | **Presence channel → a broker at scale** | The `PresenceChannel` to a provisioned Redis/NATS broker. | It's a network hop over an already-shipped broker; the awareness logic ships and is tested over the in-memory channel. |
 | **wa-sqlite / Turso adapter** *(optional)* | A SQL durable adapter for cross-tab queries, behind `PersistenceAdapter`. | IndexedDB is the durable default today; a SQL backing is a sibling factory, nothing above it changes. |