@voltro/cli 0.33.0 → 0.35.0

package/templates/agent-docs/deployment.md

@@ -11,7 +11,7 @@
 
 _Voltro Cloud (coming soon) — the managed runtime for your Voltro project. Today the Free control plane registers + observes your self-hosted apps._
 
-Voltro Cloud is the managed tier of the same open-core runtime you run locally. It's not a fork — `voltro start` is what powers your production instances, just with custom domains, multi-region routing, provisioned Postgres / Redis / object storage, and a control plane that handles deploys.
+Voltro Cloud is the managed tier of the same runtime you run yourself. It's not a fork — `voltro start` is what powers your production instances, just with custom domains, multi-region routing, provisioned Postgres / Redis / object storage, and a control plane that handles deploys.
 
 **Status:** managed cloud **deploy + provisioning is coming soon** and is not yet available. What's live today is the **Free control plane**: sign up and use it to **register and observe your self-hosted apps** (hosted observability, quotas, governance, teams). The managed-tier features described below are the planned shape of Voltro Cloud — see the per-section notes.
 
@@ -117,7 +117,7 @@ voltro cloud import   # scaffold voltro.cloud.toml from the app's app.config.ts
 
 _Run Voltro on your own infra — Docker compose, env vars, reverse proxy, scaling._
 
-Voltro is open-core. The runtime that powers Voltro Cloud is the same runtime you run locally with `voltro start`. Self-hosting is fully supported — no separate "lite" runtime, no feature gates around the core API.
+The runtime that powers Voltro Cloud is the same runtime you run yourself with `voltro start` — one codebase, one license. Self-hosting is fully supported — no separate "lite" runtime, no feature gates around the core API.
 
 ## The shape of a self-hosted deploy
 
@@ -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.
@@ -1073,17 +1129,29 @@ Durable in-DB traces are **off in production by default** — traces belong in y
 
 ## 7. Graceful shutdown
 
-On `SIGTERM` / `SIGINT`, `voltro serve` shuts down cleanly (exit 0): it stops
-schedulers, detaches subscribers / reactions / aggregates, drains the analytics
-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.
-
-**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
-inside the process doesn't help: the listener is already closing. Draining is a
-**k8s-layer** job, done with a **preStop hook**:
+On `SIGTERM` / `SIGINT`, `voltro serve` shuts down cleanly (exit 0), in this
+order: it stops accepting new connections and lets **in-flight requests finish
+against a fully-alive app** (bounded — the request drain gets 60% of the
+shutdown grace, so the teardown behind it always fits inside the deadline),
+then stops schedulers, detaches subscribers / reactions / aggregates, drains
+the analytics sink and mirror, ends any remaining WebSocket, and closes the
+SQL connection pool **last** (waiting for in-flight transactions). Verified
+against a real serve under signal: a request in flight when `SIGTERM` lands
+completes with a full response before the process exits — no preStop hook, no
+orchestrator. A bare `voltro serve` under docker compose drains itself.
+
+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.
+
+**What an orchestrator still adds: routing.** The app finishes every request
+it has *accepted* — but a request that *arrives* after `SIGTERM` is refused
+(the listener closes immediately, on purpose), and only the layer that routes
+traffic can stop sending it. Failing readiness from inside the process doesn't
+help: the listener is already closed. Under k8s, close that window with a
+**preStop hook**:
 
 ```yaml
 spec:
@@ -1101,10 +1169,15 @@ spec:
             command: ["sh", "-c", "sleep 5"]
 ```
 
-Without the preStop hook, a rolling update drops the small window of requests
-that route to a terminating pod before k8s finishes removing it from the Service
-endpoints. With it, that window is drained. `terminationGracePeriodSeconds` must
-be larger than the sleep plus the app's own teardown, or k8s SIGKILLs mid-drain.
+Without the preStop hook, a rolling update refuses the small window of requests
+that still route to a terminating pod before k8s finishes removing it from the
+Service endpoints — refused with a connection error, not truncated mid-response
+(everything already accepted completes either way). With it, that window is
+served too. `terminationGracePeriodSeconds` must be larger than the sleep plus
+the app's own teardown, or k8s SIGKILLs mid-drain. Environments with no
+endpoint removal at all — docker compose above all — need nothing: there is no
+routing layer to lag behind the shutdown, so the built-in drain is the whole
+story.
 
 **Bound the app's own teardown with `VOLTRO_SHUTDOWN_GRACE_MS`.** After
 `SIGTERM`, the runtime runs its finalizers (pool close, plugin `onDeactivate`,
@@ -1128,10 +1201,10 @@ spec:
           value: "22000"
 ```
 
-The close is clean on the client side too: on shutdown each live WebSocket is
-closed with a proper close frame (not an abrupt socket drop), and the web
-client's supervisor reconnects on any close — so an open dashboard re-attaches
-to a healthy replica across a rolling deploy without a page reload.
+Live WebSockets are ENDED promptly at shutdown — the drain never lets an open
+socket hold the process to the deadline — and the web client's supervisor
+treats any close as a reconnect signal, so an open dashboard re-attaches to a
+healthy replica across a rolling deploy without a page reload.
 
 ## 8. Multiple replicas
 
@@ -1305,7 +1378,7 @@ VOLTRO_WORKFLOW_FAILOVER_HEARTBEAT=5    # lease-refresh cadence (default 10; kee
 
 Lower the lease for **faster failover**, at the cost of **false-positive reclaims**: if a *healthy* replica is paused longer than the lease by a GC pause or a DB-latency spike, another replica may briefly also claim its shards. Keep the heartbeat around a third of the lease so one slow refresh doesn't trip a reclaim. For crash detection that doesn't depend on the timeout at all, pair it with a K8s **liveness probe** so a dead pod is removed promptly.
 
-(A separate concern is *new*-message pickup: a workflow triggered on the replica that owns its shard starts immediately, but one owned by ANOTHER replica is otherwise picked up on that replica's next storage poll — up to 10s. **If you run a broadcast broker (Redis/NATS — which a multi-replica deployment already does for cross-replica reactivity), this is automatic and near-instant**: a trigger pushes a "wake" over the bus and the shard owner re-polls at once, on any SQL dialect. Without a broker, tune `VOLTRO_WORKFLOW_POLL_INTERVAL=2` instead. Unrelated to the failover path above.)
+(A separate concern is *new*-message pickup: a workflow triggered on the replica that owns its shard starts immediately, but one owned by ANOTHER replica is otherwise picked up on that replica's next storage poll — up to 10s. **If you run a broadcast broker (Redis/NATS — which a multi-replica deployment already does for cross-replica reactivity), this is automatic and near-instant**: a trigger pushes a "wake" over the bus and the shard owner re-polls at once, on any SQL dialect. **Without a broker, the change stream does the same job wherever remote changes reach the spine** — a Postgres-only multi-replica fleet (LISTEN/NOTIFY CDC) is the common case: a remote replica's signal, start context, or run transition arrives as a change event and triggers an immediate, coalesced re-poll, so signal/step latency stops being poll-bounded there too. Only with *neither* a broker *nor* CDC does the poll interval remain the bound — tune `VOLTRO_WORKFLOW_POLL_INTERVAL=2` then. Unrelated to the failover path above.)
 
 ## Checklist
 
@@ -1315,6 +1388,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
@@ -1495,3 +1572,185 @@ Air-gapped and enterprise deployments attest seats contractually instead; no tel
 
 - [Voltro Cloud](./voltro-cloud.md) — the control plane these features live in
 - [Self-hosting](./self-hosting.md) — running Voltro yourself
+
+
+
+---
+
+<!-- source: en/deployment/platforms.md -->
+## Platform recipes
+
+_Deploy the same container to Fly.io, Railway, Render, or a Hetzner VM — one image, four wrappers._
+
+Every recipe on this page deploys the **same artifact**: the production image
+from the compose baseline's `docker/api.Dockerfile` (`voltro baseline set
+compose` writes it into your project). The platforms differ only in the wrapper
+— how they build it, which env vars they inject, and how they health-check it.
+
+**What is verified, stated exactly.** The container itself is the tested part:
+it builds from a clean context, boots `voltro serve` from the precompiled serve
+bundle, survives the `pnpm deploy` relocation, and answers
+`/internal/readiness` with 200 — that loop runs in this repo's own validation.
+The platform wrapper files below are written against each platform's current
+config format and have **not** been executed against a live account of that
+platform; if one drifts from what the platform ships today, the container is
+still right and the fix is in the wrapper.
+
+Three properties of the image every platform relies on:
+
+- **`PORT` wins.** The port precedence is `PORT` > `--port` > `app.config.ts` —
+  deliberately, because platforms assign through `PORT`. You never configure a
+  port in the wrapper beyond telling the platform which one the app answers on.
+- **A missing secret refuses to boot.** `VOLTRO_SESSION_SECRET` unset is a
+  clean, named boot refusal — not a server that signs with a default. Set
+  secrets in the platform's secret store before the first deploy, or read the
+  refusal message; both are correct outcomes.
+- **`/internal/readiness` flips to 200 only after the whole boot.** Use it as
+  the health check everywhere; routing traffic on process-up instead of
+  readiness is how a deploy serves 502s for the first seconds.
+
+## Fly.io
+
+```toml
+# fly.toml
+app = "my-voltro-api"
+primary_region = "fra"
+
+[build]
+  dockerfile = "docker/api.Dockerfile"
+  build-args = { APP_PATH = "apps/my-app/api" }
+
+[env]
+  DB_DIALECT = "postgres"
+
+[http_service]
+  internal_port = 4000
+  force_https = true
+  auto_stop_machines = "stop"
+  auto_start_machines = true
+  min_machines_running = 0
+
+  [[http_service.checks]]
+    path = "/internal/readiness"
+    interval = "10s"
+    timeout = "2s"
+```
+
+```sh
+fly secrets set VOLTRO_SESSION_SECRET=$(openssl rand -base64 32) DB_URL=<from fly postgres attach>
+fly deploy
+```
+
+The one Fly-specific decision: `auto_stop_machines` gives you scale-to-zero,
+and a cold start pays the container boot. The serve bundle exists for exactly
+this — the framework-boot slice of a cold start is ~180–210 ms instead of ~1 s.
+Read [Scale to zero](/docs/deployment/scale-to-zero) before choosing
+`min_machines_running = 0` for an api that owns schedules: a machine that is
+never awake fires no cron.
+
+## Railway
+
+Railway detects the Dockerfile; point it at the right one and set the build
+context to the repo root (the Dockerfile copies the whole workspace for
+`pnpm install`).
+
+```json
+// railway.json
+{
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "docker/api.Dockerfile"
+  },
+  "deploy": {
+    "healthcheckPath": "/internal/readiness",
+    "restartPolicyType": "ON_FAILURE"
+  }
+}
+```
+
+Set `VOLTRO_SESSION_SECRET` and `DB_URL` as service variables; Railway injects
+`PORT` and the image binds to it — no port config anywhere. The
+`APP_PATH` build arg goes into the service's build settings.
+
+## Render
+
+```yaml
+# render.yaml
+services:
+  - type: web
+    name: my-voltro-api
+    runtime: docker
+    dockerfilePath: ./docker/api.Dockerfile
+    dockerContext: .
+    healthCheckPath: /internal/readiness
+    envVars:
+      - key: DB_DIALECT
+        value: postgres
+      - key: VOLTRO_SESSION_SECRET
+        sync: false
+      - key: DB_URL
+        fromDatabase:
+          name: my-voltro-db
+          property: connectionString
+
+databases:
+  - name: my-voltro-db
+    plan: basic-1gb
+```
+
+`sync: false` makes the secret a dashboard-entered value that never lands in
+the blueprint file — the same "we ship no secret values" rule the framework
+enforces on its own templates applies to yours.
+
+## Hetzner (or any bare VM)
+
+A VM is the compose baseline with a process manager on top — this is the one
+recipe whose whole stack is the already-validated path from
+[Self-hosting](/docs/deployment/self-hosting).
+
+```sh
+# once, on the VM
+apt-get install -y docker.io docker-compose-plugin
+git clone <your-repo> /srv/app && cd /srv/app
+cp .env.example .env   # then fill in real values — nothing boots without them
+docker compose up -d --build
+```
+
+```ini
+# /etc/systemd/system/voltro.service — survive reboots
+[Unit]
+Description=voltro stack
+Requires=docker.service
+After=docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=true
+WorkingDirectory=/srv/app
+ExecStart=/usr/bin/docker compose up -d
+ExecStop=/usr/bin/docker compose down
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Caddy (in the baseline compose) terminates TLS with an automatic Let's Encrypt
+certificate — point the domain's A record at the VM and the certificate is
+provisioned on first request. What a VM does NOT give you: rolling deploys
+(compose restarts in place — expect seconds of downtime per deploy, or put two
+VMs behind a load balancer), and managed Postgres backups —
+[`voltro data backup`](/docs/cli/data) plus the restore drill is your baseline,
+and the drill is the part people skip.
+
+## Which one
+
+| | scale-to-zero | managed DB | rolling deploys | cost floor |
+|---|---|---|---|---|
+| Fly.io | yes (`auto_stop`) | Fly Postgres | yes | ~0 idle |
+| Railway | usage-based sleep | built-in | yes | ~0 idle |
+| Render | paid plans only | built-in | yes | fixed/instance |
+| Hetzner VM | no | bring your own | no (single VM) | fixed, cheapest at steady load |
+
+An api that owns cron schedules should not scale to zero. An api with bursty
+traffic and no schedules is exactly what scale-to-zero is for. When in doubt,
+the boring answer — one always-on instance — is also the cheapest to operate.

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`)
@@ -102,7 +127,7 @@ Voltro is deliberately opinionated about boring things (HTTP, state, transport,
 
 ## What we won't do
 
-- **Lock you in.** Self-hosting is fully supported. Cloud is the premium tier of the same open-core runtime, not a fork.
+- **Lock you in.** Self-hosting is fully supported. Cloud is the premium tier of the same runtime, not a fork.
 - **Multi-runtime grab-bag.** Effect-TS end-to-end — no Restate, no Temporal, no Inngest, not even opt-in.
 - **Magic.** Every file convention is documented; every generated file lives in `.framework/` and you can read it.
 - **Codegen you have to remember to run.** Schema flows from your tables to your React components automatically via Vite's module graph.
@@ -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`