@voltro/cli 0.33.0 → 0.34.0

package/templates/agent-docs/cli.md

@@ -15,11 +15,11 @@ The Voltro CLI is the single entry point for scaffolding, dev, build, and run. I
 
 ## Command quick-reference
 
-The dispatcher routes `voltro <command> [args]` to the matching subcommand and passes the rest through. The full set:
+The dispatcher routes `voltro <command> [args]` to the matching subcommand and passes the rest through. **`voltro help` is the authority** — it prints the registry itself, so it cannot drift from what your installed CLI dispatches. The table below is every command that registry exposes, grouped by purpose:
 
 | Group | Commands |
 |---|---|
-| [Scaffolding](/docs/cli/scaffolding) | `create-project`, `add-app`, `list-templates`, `new` (scaffold one primitive — `query` / `mutation` / `action` / `workflow` / `page`) |
+| [Scaffolding](/docs/cli/scaffolding) | [`init`](/docs/cli/scaffolding#voltro-init) (initialise the current directory as a workspace root — no apps), `create-project`, `add-app`, `list-templates`, `new` (scaffold one primitive — `query` / `mutation` / `action` / `workflow` / `page`) |
 | Packages | `package` (`create` / `publishable` / `private` / `status`), `create-package` |
 | [Dev](/docs/cli/dev) | `dev`, `codegen`, `typecheck` (`tsc --noEmit` with the app's own TypeScript), `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` |
@@ -27,20 +27,61 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 | [Database](/docs/cli/migrate) | `migrate`, `db` (`plan` / `apply` / `plans` / `drift` / `squash` / `restore-snapshot` / `migrate` / `rollback` / `status` / `seed`), [`evolve`](/docs/database/migrations/rename-and-drop) (schema-evolution copilot — propose a codemod + branch-verified backfill for a rename / retype / split / drop of an existing column or table) |
 | [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 |
-| Ops / infra | `cache` (`status` / `flush` / `invalidate`), `add` (`redis`), `baseline` (`list` / `status` / `set`), `schedule-manifest`, [`storage`](/docs/plugins/storage) (`doctor` / `cors`) |
+| Ops / infra | `cache` (`status` / `flush` / `invalidate`), `add` (`redis`), `baseline` (`list` / `status` / `set`), `schedule` (`run <name>` — fire a registered schedule on demand; `--process` / `--trigger manual\|external` / `--url`), `schedule-manifest`, [`storage`](/docs/plugins/storage) (`doctor` / `cors`) |
 | AI / data | `embeddings backfill <table> --text <field> --vector <field>` — (re)embed rows the `vectorEmbedding()` mixin missed (pre-existing rows / a model change); `--dry-run` to preview; [`eval`](/docs/ai/agents#evaluating-recorded-runs-voltro-eval) — replay recorded agent runs against golden cases + judge, exit 1 on regression (a deploy gate; `--json` / `--branch` / `--threshold`) |
+| Integrate | [`webhooks`](/docs/plugins/webhooks#voltro-webhooks-consumer--the-package-your-subscribers-install) (`consumer` / `events`) — generate the ZERO-dependency Standard-Webhooks verification package your subscribers install, from your own declared events (`--out` / `--name`); list the events a subscriber can register for (`--json`) |
 | [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` |
 | [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled; `info` (`--json`) — CLI / node / package-manager / dialect + every installed `@voltro/*` version, flagging lockstep skew (exits 1 on skew) |
 | Harness | `test`, `e2e` |
 | Cloud | `cloud` (`login` / `whoami` / `projects` / `env` / `import`) |
 | Secrets | `secret` (`generate [purpose]` — the right var+format per secret; `generate` alone → a generic secret; `list`) |
-| Meta | `agents-md`, `version`, `help` |
+| Meta | `agents-md`, `telemetry` (reports that Voltro collects none — no phone-home, nothing to opt out of), `version`, `help` |
 
-Each command takes an optional path argument (the app directory) — defaults to `.` when run from inside an app. `voltro init` scaffolds a project (it delegates to the `create-project` scaffolder, forwarding `--api`/`--web`/`--baseline`/`--cache`). `voltro secret generate [purpose]` prints a cryptographically strong secret — with a purpose (`data-transfer`, `session`, `bundle-key`, `field-encryption`, `storage`, `inspect`) it emits the correct env var + length/format as a paste-ready `NAME=value` (`voltro secret list` shows them all); with no purpose, a generic base64url secret. `voltro telemetry` reports that Voltro collects none. `voltro deploy` shows the deploy paths — self-host via a [baseline](/docs/deployment/baselines) + CI, managed via the control-plane client `voltro cloud` (managed cloud deploy is coming soon — see [Voltro Cloud](/docs/deployment/voltro-cloud)), individual [serverless functions](/docs/deployment/serverless-functions) (`voltro serverless` → self-hosted Node, or Cloudflare / Scaleway), or a [static site](/docs/deployment/static-sites) (`voltro static` → Cloudflare Pages / S3 / Netlify).
+**Two commands are hidden from `voltro help` on purpose** and are not in the
+table: `prune-runtime <deploy-dir>` (trims a deployed web tree's `node_modules`
+to the reachable runtime set — the standalone Dockerfiles run it for you) and
+`_apply-codemods` (the re-exec target `voltro update` uses to run the target
+version's codemods). Both are dispatchable; neither is something you invoke
+directly.
+
+Each command takes an optional path argument (the app directory) — defaults to `.` when run from inside an app. `voltro init` initialises the current directory as a workspace root — `pnpm-workspace.yaml`, a root `package.json` with `dev`/`build`/`test`/`typecheck`, a `.gitignore` and `git init`, idempotently and without scaffolding any apps (`voltro create-project <name>` does that, and bootstraps the same root when there isn't one). `voltro secret generate [purpose]` prints a cryptographically strong secret — with a purpose (`data-transfer`, `session`, `bundle-key`, `field-encryption`, `storage`, `inspect`) it emits the correct env var + length/format as a paste-ready `NAME=value` (`voltro secret list` shows them all); with no purpose, a generic base64url secret. `voltro telemetry` reports that Voltro collects none. `voltro deploy` shows the deploy paths — self-host via a [baseline](/docs/deployment/baselines) + CI, managed via the control-plane client `voltro cloud` (managed cloud deploy is coming soon — see [Voltro Cloud](/docs/deployment/voltro-cloud)), individual [serverless functions](/docs/deployment/serverless-functions) (`voltro serverless` → self-hosted Node, or Cloudflare / Scaleway), or a [static site](/docs/deployment/static-sites) (`voltro static` → Cloudflare Pages / S3 / Netlify).
 
 ## Help + version
 
-`voltro help` prints the command list; `voltro version` prints the CLI version. These are subcommands, not global flags — there is no global `--version` / `--help` parsing in the dispatcher.
+`voltro help` prints the command list; `voltro version` prints the CLI version. Both are also reachable as bare flags — `voltro --help` / `-h` and `voltro --version` / `-v` — handled by the dispatcher before it looks for a subcommand.
+
+**Per-command help** is the useful one. `voltro <command> --help` (equivalently `voltro help <command>`) prints that command's usage line, its flags, the environment variables that change what it does, and worked examples:
+
+```bash
+voltro dev --help
+```
+
+```text
+voltro dev — Start the local development server (auto-discovers routes / mutations).
+
+Usage
+  voltro dev [app]
+
+Examples
+  voltro dev
+      boot the app in the current directory
+  voltro dev apps/acme/api
+      boot a specific app
+
+Environment
+  PORT                     override the port from app.config.ts
+  WATCH=0                  run the server directly, with no file-watching supervisor
+  WATCH_POLL=1             poll instead of using native FS events (bind-mounts: k8s hostPath / Docker)
+  …
+```
+
+`--help` never runs the command. A command with subcommands of its own (`db`, `cloud`, `workflows`, `inspect`, `update`, …) prints its own richer page instead.
+
+## Startup
+
+The CLI loads a command's implementation only when you dispatch it, so `voltro version`, `voltro info` and `voltro new` do not pay for the dev server, the build toolchain or the runtime. The same applies to the `voltro dev` supervisor's respawned child on every save.
+
+The CLI's first line is its own — no Node warnings ahead of it.
 
 ## Common per-command flags
 
@@ -57,7 +98,11 @@ Commands like `build` / `start` / `migrate` / `codegen` parse no flags at all
 
 ## Common env vars
 
-The CLI reads:
+The framework reads more than a hundred distinct `VOLTRO_*` / `DB_*` / `PG_*`
+variables across its packages, so this is **not** the full set and could not
+usefully be — it is the ones you reach for. Each subsystem's page carries its own; the complete transport-security
+and connection lists live in [Production hardening](/docs/deployment/production-hardening)
+and [Security](/docs/security/overview).
 
 | Var | Effect |
 |---|---|
@@ -72,6 +117,7 @@ The CLI reads:
 | `VOLTRO_INSPECT_TOKEN` | Bearer for the inspect surface. **Fail-closed:** unset → every request is `401`. `voltro dev` mints one per project; `voltro serve` / `voltro start` mint nothing, so a public deploy is closed by default (set it explicitly to open the surface). |
 | `VOLTRO_INSPECT_ALLOWED_HOSTS` | Extra `Host` names allowed to reach the **dev** inspect surface, past its DNS-rebinding guard (comma/space-separated). Loopback names + IP literals are always allowed; any other domain name is refused unless listed here — the api counterpart of vite's `allowedHosts`. |
 | `DB_URL` | Database connection string (falls back to `DB_PRIMARY_URL`; or the discrete `DB_*` / `PG_*` fields). |
+| `DB_ACQUIRE_TIMEOUT_MS` | How long a request may wait for a free pooled connection before failing (default `10000`; `0` restores the driver's own unbounded wait). Read on every command and every dialect that can bound it. `DB_ACQUIRE_QUEUE_LIMIT` is its mysql/mariadb counterpart and is deliberately **unset** by default. |
 | `VOLTRO_SESSION_SECRET` | Session-cookie signing secret (`@voltro/plugin-auth`). Rotate with zero downtime: move the old value to `VOLTRO_SESSION_SECRET_PREVIOUS` for one session lifetime — cookies signed with either secret keep verifying, and previous-key cookies are re-issued under the new one. |
 | `VOLTRO_DATA_TRANSFER_SECRET` | Gates the prod data-transfer endpoints (`POST /_voltro/admin/{export,import}`); ≥16 chars or the routes don't mount. |
 | `VOLTRO_BUNDLE_KEY` | Passphrase for `.vbundle` export encryption (`voltro data export --encrypt`). A DEDICATED key, not the transfer secret. |
@@ -79,6 +125,24 @@ The CLI reads:
 | `VOLTRO_STORAGE_SECRET` | Signs storage grant tokens (private files); falls back to the session secret if unset. |
 | `AI_PROVIDER` / `AI_MODEL` / `AI_API_KEY` | Per-provider AI config. |
 
+### Transport security — the overrides on by default since 0.34.0
+
+The api listener's cross-site check, proxy policy and security headers are **on
+by default** and configured in `app.config.ts`'s `security` block. Each has an
+env override, resolved identically under `dev` and `serve`, with the explicit
+config value always winning:
+
+| Var | Effect |
+|---|---|
+| `VOLTRO_ORIGIN_GUARD` | `off` disables the cross-site origin check. Anything else leaves the default `same-origin`. |
+| `VOLTRO_ALLOWED_ORIGINS` | Comma-separated origins allowed past that check — what a web app on a different origin than the api needs. |
+| `VOLTRO_TRUSTED_PROXIES` | Which hops may set `x-forwarded-for` / `x-forwarded-proto`: a comma-separated CIDR/IP list, `private`, `*` (trust the leftmost token), or a hop **count** (`2`). **Unset means the header is ignored entirely** and the socket address wins — set it if you run behind an ingress AND rate-limit or audit per IP. |
+| `VOLTRO_SECURITY_HEADERS` | `off` / `default` / `strict` — the whole header bundle's mode. |
+| `VOLTRO_CSP` | Content-Security-Policy for non-HTML api responses. `off` drops just this one. |
+| `VOLTRO_CSP_HTML` | CSP for HTML responses (under `strict` it defaults to the same policy as `VOLTRO_CSP`). `off` drops just this one. |
+| `VOLTRO_HSTS` | `Strict-Transport-Security` value. `off` drops just this one. |
+| `VOLTRO_MAX_RPC_BODY_BYTES` | Cap on the buffered `POST /rpc` JSON body (default 8 MiB) — an oversized body is refused `413` and never buffered past the cap. File uploads ride plugin routes with their own limits. |
+
 Generate any of the secret vars above with `voltro secret generate <purpose>` (see [`secret`](#command-quick-reference)) — it picks the right length and format. A lower environment's secrets must always differ from production's.
 
 ## Workflow patterns
@@ -86,10 +150,10 @@ Generate any of the secret vars above with `voltro secret generate <purpose>` (s
 ### "I'm starting a new project"
 
 ```bash
+mkdir acme && cd acme
 pnpx voltro create-project acme --api api-backend --web frontend-landing
-cd acme
 pnpm install
-pnpm dev   # turbo runs voltro dev across every app in the project
+pnpm dev   # pnpm -r --parallel dev — voltro dev in every app at once
 ```
 
 ### "I want to add a docs site to my existing project"
@@ -97,7 +161,7 @@ pnpm dev   # turbo runs voltro dev across every app in the project
 ```bash
 voltro add-app docs --template frontend-docs --to acme
 pnpm install   # picks up the new app's deps
-pnpm dev       # turbo adds the new app to its parallel boot
+pnpm dev       # the new app joins the parallel boot automatically
 ```
 
 ### "I changed my schema and want to apply it"
@@ -266,10 +330,52 @@ The HTTP surface is reachable directly too — e.g. `curl -s localhost:4000/_vol
 <!-- source: en/cli/scaffolding.md -->
 ## Scaffolding
 
-_create-project, add-app, list-templates — boot new code with the framework's conventions baked in._
+_init, create-project, add-app, list-templates — boot new code with the framework's conventions baked in._
 
 The scaffolder generates new projects + new apps from templates. Each template is a dogfooded reference; what you scaffold is the same shape the Voltro Cloud team uses.
 
+## `voltro init`
+
+```bash
+voltro init          # takes no arguments — it initialises the CURRENT directory
+```
+
+Turns the directory you are standing in into a **Voltro workspace root**, and
+scaffolds no apps at all. That is the whole distinction from `create-project`:
+`init` prepares the root, `create-project` fills it. They share one
+implementation (`ensureWorkspaceRoot`), so a greenfield `create-project` needs
+no separate `init` — it bootstraps the same root when there isn't one.
+
+What it writes, all of it **idempotent and additive**:
+
+| File | Behaviour |
+|---|---|
+| `pnpm-workspace.yaml` | Written only when the walk up finds no workspace at all. |
+| `package.json` (root) | Created when missing — `private`, `type: 'module'`, node/pnpm engines, the detected `packageManager`, the four scripts, `typescript` + `@types/node`. When it exists, only the **missing** keys are filled in; a script or a version range you already declared is never rewritten. |
+| `tsconfig.base.json` | Written when missing. Every app + package tsconfig the framework generates extends this exact path, so `tsc` fails before it reads your code without it. |
+| `.gitignore` | Created when missing; otherwise only the entries it does not already cover are appended. Includes `.env.local` — where `voltro dev` mints per-project secrets, and which must never be committed. |
+| `git init` | Only when nothing at or above the directory is already a git working tree. |
+
+The four root scripts are the workspace fan-outs:
+
+```json
+{ "dev": "pnpm -r --parallel dev", "build": "pnpm -r build",
+  "test": "pnpm -r test", "typecheck": "pnpm -r typecheck" }
+```
+
+Two refusals, both deliberate:
+
+- **A positional argument is an error** (`init takes no arguments — it
+  initialises the current directory`), with a hint pointing at
+  `voltro create-project <name>`. `voltro init acme` reads like "make me a
+  project called acme", and it is not that command.
+- **It will not nest a second root inside an existing pnpm workspace.** If an
+  ancestor already has a `pnpm-workspace.yaml`, it names that root and tells you
+  to run `create-project` from there instead.
+
+A second run on an already-initialised root prints `is already a Voltro
+workspace root — nothing to do.`
+
 ## `create-project`
 
 ```bash
@@ -286,6 +392,7 @@ Bootstraps a new project under `apps/<name>/` with selected templates.
 | `--baseline=<bare\|compose\|helm>` | prompts (or skip) | Deploy baseline to scaffold (`bare` / `compose` / `helm`). Without it, the interactive prompt lists the available ids. |
 | `--port-range <start>-<end>` | `5190-5199` | Port range for web apps in this project. Persisted in `project.json`. Also accepts `:` / `..` separators. |
 | `--no-input` | false | Skip prompts; suitable for CI / scripted scaffolding. |
+| `--no-register` | false | Do not contact the Voltro Cloud control plane. See [registration](#project-registration) below. |
 
 What it does:
 
@@ -304,6 +411,34 @@ pnpm install
 pnpm dev
 ```
 
+### Project registration
+
+`create-project` and `add-app` finish by registering the project with the Voltro Cloud control plane. This is how **self-hosted** use is counted, and the Terms of Service ask for projects and apps to be registered. It is worth knowing exactly when it happens and what it involves, because it is part of your first command.
+
+**If you are not logged in, nothing is sent.** No network call is attempted at all, and the scaffolder says so:
+
+```text
+→ cloud registration: skipped — not logged in, so nothing was sent from this machine.
+  Registration is how SELF-HOSTED use is counted; the Voltro Cloud Terms of Service ask
+  for projects and apps to be registered once you have an account.
+  Register later:   voltro cloud login   then   voltro cloud scan
+  Never ask again:  scaffold with --no-register
+```
+
+**If you are logged in**, it prints the destination and the contents before the call:
+
+```text
+→ registering project 'acme' with https://cloud.voltro.dev (self-hosted usage tracking, ToS-governed)
+  Sends: the project slug, and per app its name, kind, framework version and the NAMES of
+         declared primitives (queries, mutations, tables, plugins, …) plus a page count.
+  Never sends: source code, row data, environment values or secrets.
+  Skip with --no-register.
+```
+
+Pass `--no-register` to skip it entirely — appropriate for offline work, CI, or while evaluating. You can register later with `voltro cloud login` followed by `voltro cloud scan`.
+
+This is the only network call the CLI makes on its own behalf; `voltro telemetry` reports the rest of the picture (the framework collects nothing).
+
 ### The seeded agent guide
 
 `create-project` / `add-app` (and `voltro dev` on first boot) seed a guide that
@@ -543,6 +678,27 @@ lists the ones that reference none. It learns your own `require*` / `assert*`
 guard names, so it does not report the call sites of guards you already wrote.
 See [the authz scan](./build-and-start.md).
 
+### When the database is not reachable
+
+A refused, unresolvable or rejected database connection is reported as a condition with a fix, not as a framework crash:
+
+```text
+voltro: the database is not reachable at 127.0.0.1:5432 (ECONNREFUSED).
+
+  No database is configured — none of DB_URL / DB_HOST / PG_HOST is set in the
+  environment or in a loaded `.env`, so the framework used its local dev default.
+
+  Either start one:      pnpm db:up          (if your project ships a compose file)
+  or point at your own:  DB_URL=postgres://user:pass@host:5432/dbname
+                         — put it in `.env` next to app.config.ts, not just in one shell.
+
+  Re-run with --debug for the full stack.
+```
+
+When a variable **is** set, the message names it and says the address resolved and nothing answered there — which is a different problem from "is postgres running", and points you at the container, VPN or firewall instead. A server that answers and rejects you (wrong password, missing database) is reported as its own case, because the fix is different again.
+
+Pass `--debug` (or set `VOLTRO_DEBUG=1`) to get the full Effect stack instead.
+
 ## `voltro dev <appDir>`
 
 ```bash
@@ -741,20 +897,22 @@ A `<DevtoolsStringsProvider strings={…}>` mounted above the overlay works too;
 | `WATCH=0` | Disable filesystem watch. Useful under a parent watcher (Docker volume, devcontainer). |
 | `VOLTRO_DASHBOARD=off` | Don't auto-launch the dashboard. |
 | `VOLTRO_INSPECT=off` | Don't expose `/_voltro/inspect/*` endpoints. |
-| `PORT=4001` | Override the listen port (api or web). Both kinds read `PORT`, then `app.config.ts` `port:`, then the default. |
+| `PORT=4001` | Override the listen port (api or web). See [Which port an app binds](#which-port-an-app-binds) for the full order. |
 | `VOLTRO_DASHBOARD_PORT=5180` | Override the auto-launched dashboard port (default `5179`). |
 | `VOLTRO_LOG_LEVEL=debug` | Verbose framework logs. |
 | `VOLTRO_DEV_SSR_COMPILE_CONCURRENCY=4` | Max `ssr` pages compiled on demand at once (default `4`). Lower it (`1`/`2`) on a low-memory box if a burst of first-time `ssr` page loads spikes memory; raise it on a big machine. Warm (already-compiled) pages are never throttled. |
 
-## Multi-app dev (turbo)
+## Multi-app dev
 
-The `pnpm dev` at the project root delegates to `turbo run dev` which boots every app in parallel:
+The `dev` script the scaffolder writes at the workspace root is plain pnpm — no task runner to install:
 
 ```bash
-pnpm dev   # ↳ turbo runs `voltro dev` for every workspace app
+pnpm dev   # ↳ pnpm -r --parallel dev — `voltro dev` in every app at once
 ```
 
-Turbo's TUI mode shows one pane per app with live output. Set `"ui": "tui"` in `turbo.json` (the scaffolder does this for you).
+`pnpm -r` selects by "has a `dev` script", so an app that owns its own dev loop (an Expo `mobile-app`, an `edge-functions` bundle) opts out simply by not defining one. To run a single app: `pnpm --filter @acme/api dev`.
+
+If you prefer a task runner for its caching and per-app output panes, adding one is a normal workspace change — nothing in the framework depends on it.
 
 ## `voltro codegen <appDir>`
 
@@ -768,6 +926,24 @@ Regenerates `rpcGroup.generated.ts` (+ the web `.framework/*` entry) from the di
 - **CI environments** where you want the typed client baked into a tarball before tests run.
 - **Editor LSP confused** after a discovery pattern changed and the generated file went out of sync.
 
+### Staleness is detected, not assumed
+
+The generated file carries a `source-fingerprint` of the descriptor tree, so the other commands can tell whether it still matches your code:
+
+- **`voltro build`** regenerates it when it is stale. A CI build from a clean checkout never ran `voltro dev`, and it is a file the build can produce itself.
+- **`voltro test`** REFUSES and tells you to run `voltro codegen`:
+
+  ```text
+  voltro test: …/rpcGroup.generated.ts is stale — a descriptor changed since the group was generated.
+    The tests would run against the previously generated procedure group, pass, and prove nothing
+    about the descriptors you just edited.
+    Run `voltro codegen` (or boot `voltro dev` once) and try again.
+  ```
+
+  It refuses rather than regenerating because regenerating means importing your app's modules and config as a side effect of asking to run tests, and silently rewriting a checked-in source file is worse than stopping.
+
+The check reads bytes only — no app module is imported — so it costs milliseconds. A generated file written by an older framework version carries no stamp and reads as stale; run `voltro codegen` once.
+
 ## `voltro agents-md`
 
 ```bash
@@ -797,8 +973,22 @@ For api apps, Voltro applies its own discovery walker on every save. The pattern
 
 `*.tool.tsx` files are not discovered on their own — a tool is imported by the agent that uses it, so it's picked up through the agent file. Hidden dirs, `node_modules`, `dist`, and `.framework` are skipped.
 
+Those names are matched as whole **path segments**, so a directory called `distribution/` or a file called `distTools.ts` is watched normally.
+
 For web apps, Vite's built-in HMR handles the watch.
 
+### Workspace packages are watched too
+
+If your api depends on a workspace package (`"@acme/shared": "workspace:*"`), that package's `src/` is watched as well — editing `packages/shared/src/x.ts` restarts the api, exactly as editing a file inside the api would. The dependency set is resolved once at boot from the api's `package.json`, so adding a dependency needs a restart (it needs an install anyway).
+
+Only real workspace packages are watched. A published npm dependency resolves inside `node_modules` and is skipped, so an app outside a monorepo watches nothing extra.
+
+An edit in a dependency is logged with its package directory, not just the filename:
+
+```
+file changed — restarting   file=shared/src/x.ts
+```
+
 ## Restart triggers
 
 API apps restart (full process kill) on a change to **any source file**
@@ -819,6 +1009,19 @@ The restart is a full re-exec — there is no in-process hot-reload of a
 handler body; editing a query's executor respawns the child (debounced
 80ms, so a burst of saves collapses into one restart).
 
+### Reading the restart timing
+
+The completion line is printed when the api **can serve a request** — not when the replacement process was spawned:
+
+```text
+file changed — restarting        file=notes.list.query.ts
+restart complete — api ready     ms=1840
+```
+
+The first boot reports the same measurement as `dev server ready`. If a restart never prints its completion line, the child did not come up — look for the crash above it, which the supervisor logs before it goes back to waiting for the next save.
+
+That number is the whole wait: the process start, the module graph, discovery, codegen, the store connection, the boot schema diff and plugin boot. It is the number to quote if the inner loop feels slow.
+
 ### How the old process is stopped
 
 SIGTERM first. The child runs its teardown — plugin `onDeactivate`, the
@@ -892,6 +1095,32 @@ the env-file chain (app dir → ancestors) and hard-restarts, logging
 web closes Vite before the replacement spawns, so the restart can't hit a
 port-in-use race.
 
+## Which port an app binds
+
+Every command that starts an app listener — `voltro dev`, `voltro serve`,
+`voltro start`, `voltro dormancy` — resolves the port the same way, in this
+order:
+
+1. `VOLTRO_DASHBOARD_PORT`, and only in the auto-launched dashboard process.
+2. `PORT` from the environment.
+3. `--port <n>` (`voltro serve`, `voltro dormancy`).
+4. `port:` in the app's `app.config.ts`.
+5. `4000` for an api app, `5173` for a web app.
+
+`PORT` deliberately outranks `--port`: every host that assigns a port — a
+container platform, a PaaS, a Kubernetes Deployment — assigns it through `PORT`,
+and a `--port` baked into an image's start command must not override the port the
+host actually routed to.
+
+A value that is not a port in `1..65535` (`PORT=`, `PORT=8080x`) is **ignored**
+with a warning naming the variable, and the next source wins. It is not passed to
+`listen()`: `Number('8080x')` is `NaN`, node reads that as "any free port", and
+the app would come up healthy at an address nobody can guess.
+
+`voltro dev` does not take `--port`. Its file-watching supervisor respawns the
+app as `dev <app>` and drops flags, so a `--port` would silently stop applying at
+the first file change; set `PORT` for a one-off, or `port:` to keep it.
+
 ## Multiple instances on one machine
 
 Run two api apps + two web apps in parallel? Every app reads the same `PORT` env, so prefer setting each app's `port:` in its own `app.config.ts` and `--cwd`-ing into each — that avoids one shared `PORT` clobbering them all. The dashboard auto-launches once on `:5179`; later instances see it's already up and skip it.
@@ -904,7 +1133,7 @@ voltro dev apps/acme/docs &
 voltro dev apps/orbit/web &
 ```
 
-If you must override per-process from the shell, set `PORT` inline on each one (`PORT=4001 voltro dev apps/acme/api`) — but the config-file port is the cleaner path. `pnpm dev` at the repo root handles all of this for you via turbo.
+If you must override per-process from the shell, set `PORT` inline on each one (`PORT=4001 voltro dev apps/acme/api`) — but the config-file port is the cleaner path. `pnpm dev` at the workspace root handles all of this for you.
 
 ## Anti-patterns
 
@@ -999,7 +1228,7 @@ What it does:
 | Flag / env | Notes |
 |---|---|
 | `PORT=8080` | Override the listen port. |
-| `SSR_CACHE=postgres` | Use the Postgres-backed ISR cache. Requires the `PG_*` connection env (`PG_HOST` etc.) to also be set — without it, `voltro start` stays on the in-memory cache. Default is in-memory. |
+| `SSR_CACHE=postgres` | Use the Postgres-backed ISR cache. Requires the web process to also have a database in its environment — `DB_URL` (what the templates set), `DB_PRIMARY_URL`, `DB_HOST` or `PG_HOST`. Without one, `voltro start` **aborts** on `NODE_ENV=production`/`staging` and warns loudly elsewhere; it no longer falls back to the in-memory cache in silence. Default is in-memory. |
 | `VOLTRO_INSPECT=off` | Disable the inspect HTTP endpoints in production. |
 | `VOLTRO_INSPECT_TOKEN=…` | Bearer token guard on the inspect endpoints. |
 
@@ -1026,12 +1255,23 @@ The response includes a `x-voltro-rendered-by` header (`prerender` / `ssr` / `is
 
 ```bash
 SSR_CACHE=memory voltro start         # default — per-process, doesn't survive restart
-# Postgres-backed cache — needs the PG_* connection env too:
+# Postgres-backed cache — the web process needs a database in its env. Any of
+# the usual variables works; DB_URL is what the templates set.
+SSR_CACHE=postgres DB_URL=postgres://… voltro start
 SSR_CACHE=postgres PG_HOST=… PG_PORT=… PG_USER=… PG_PASSWORD=… PG_DATABASE=… voltro start
 ```
 
 For multi-instance + horizontal scale → Postgres. The cache table is auto-created on first boot.
 
+> **This used to recognise `PG_HOST` and nothing else.** An app configured the
+> documented way — `SSR_CACHE=postgres` plus `DB_URL` — silently got the
+> per-process memory cache, announced as `isr cache backend: memory
+> (per-process)`: an info line that reads like the default rather than like a
+> refusal. Both the cache and the CDC invalidator go through the same connection
+> resolver as everything else now, so `DB_URL` / `DB_PRIMARY_URL` / `DB_HOST` /
+> `PG_HOST` all work — and `PG_SSL` comes with them. Asking for the postgres
+> cache and getting memory is now a boot failure in production, not a log line.
+
 ## Tenant-aware ISR
 
 Pages with `tenantAware: true` get separate cache entries per tenant. The cache key becomes `<pathname>|tenant=<tenantId>`. See [Render modes](/docs/routing/render-modes).
@@ -1040,6 +1280,12 @@ Pages with `tenantAware: true` get separate cache entries per tenant. The cache
 
 For pages with `cacheInvalidatesOn: ['table', …]`, `voltro start` reads Postgres logical replication. Writes to listed tables invalidate every matching cache entry. Requires `SSR_CACHE=postgres` + `wal_level=logical`.
 
+If routes declare `cacheInvalidatesOn` and the web process has no database in
+its environment, boot now WARNS and names those routes — they fall back to plain
+`revalidate` staleness. That gap used to be reported at `debug`, which is
+invisible at the default level and indistinguishable from live invalidation
+working.
+
 ## Graceful shutdown
 
 `voltro start` handles SIGTERM:
@@ -1115,6 +1361,35 @@ Docker step) and prints the exact remedy: add a `voltro build .` step before
 `voltro serve .`. Drop it into your image build right after `voltro build` to
 guarantee the artefact is present before the image ships.
 
+### The access-decision gate
+
+Before the authz scan below — which is a heuristic over executor SOURCE — doctor
+runs the same **gate the boot runs**: every wire-exposed procedure must declare
+`guards:` or `openAccess:`. It is not advisory and not a ratchet, because a green
+answer here means the app starts:
+
+```
+access decisions · security.defaultDeny ON
+  ✗ no access decision                       3
+  ✓ openAccess, declared on purpose          2
+      pricing.current — public pricing page, reads no caller data
+      status.ping — health probe
+
+  ✗ invoices.list  (query)
+      src/api/invoices.query.ts
+```
+
+Every undecided procedure is listed — never a prefix — and the same set is in
+`voltro doctor --json` under `accessDecisions` for a CI gate:
+
+```bash
+voltro doctor --json | jq '.accessDecisions.undecided[] | {tag, kind, file}'
+```
+
+An app that sets `security: { defaultDeny: false }` still gets the list, marked
+advisory, and doctor does not fail on it. Detail:
+[Authorization](/docs/authentication/authorization).
+
 ### The authz scan
 
 `voltro doctor` answers one mechanical question over every executor: **does it
@@ -1612,6 +1887,13 @@ voltro migrate apps/api   # explicit app directory (defaults to cwd)
 
 `voltro migrate` forwards its arguments to `voltro db apply`, so the same flags apply; `--create-only` selects the bootstrap-only emitter instead. The diff / plan / apply / drift / squash workflow lives under `voltro db` (see below).
 
+`--create-only` creates the SAME set of tables every other command declares: your
+entities, the feature-mix framework tables, the agent-thread tables when the app
+has an `*.agent.tsx`, and every plugin's `extendSchema.tables` — plus each
+plugin's `extendSchema.migrations` afterwards. Before 0.34.0 it assembled that
+set itself and got the last two wrong, so bootstrapping a fresh database the
+documented way produced one with no plugin tables at all.
+
 For the deep dive on the schema DSL + day-to-day patterns, see [Database / Migrations](/docs/database/migrations).
 
 ## How discovery works
@@ -1654,14 +1936,28 @@ voltro db plan                            # diff declared schema vs live, color-
 voltro db plan --json                     # machine-readable for CI / PR comments
 voltro db plan --sql                      # raw DDL preview
 voltro db plan --against <url>            # diff vs a REMOTE env via /_voltro/inspect/migrations
-voltro db apply                           # execute the plan (dev only — refuses NODE_ENV=production)
+voltro db apply                           # execute the plan (refuses NODE_ENV=production — and an UNSET NODE_ENV resolves to production)
 voltro db apply --plan plan.json          # prod: apply a pre-reviewed plan from CI/CD
 voltro db plans [--limit 20]              # plan history from _voltro_migration_plans
+voltro db branch --pr <n>                 # REHEARSE the plan on a throwaway branch of the live schema
 voltro db drift                           # alert if live diverged from the latest applied fingerprint
 voltro db squash --before <iso-date>      # consolidate history into one snapshot
 voltro db restore-snapshot <plan-id>      # restore soft-dropped columns from a plan
 ```
 
+> **Every `voltro db …` / `voltro migrate` invocation declares its
+> environment.** An unset `NODE_ENV` resolves to `production` for these
+> commands — the same way it does for `voltro serve` and `voltro start` — so a
+> bare `voltro db apply` with no `NODE_ENV` refuses (exit 3) rather than
+> applying an un-reviewed diff. Locally: `NODE_ENV=development voltro db apply`,
+> or put `NODE_ENV=development` in your `.env` (a declared value always wins).
+> `voltro dev` declares `development` for itself and needs nothing.
+>
+> The second reason it matters is not the refusal: `_voltro_traces` and
+> `_voltro_undo_log` are created only outside production, so a migration command
+> that resolved the environment differently from the serving process **declared
+> a different schema** — and the declared set is what the fingerprint hashes.
+
 A separate file-based migration surface (the offline escape hatch) lives alongside it:
 
 ```bash
@@ -1692,9 +1988,26 @@ For zero-downtime deploys with breaking schema changes:
 
 The framework doesn't enforce these — that's an SRE responsibility. See [Migrations](/docs/database/migrations) for the playbook.
 
+## Rehearsing a migration before it reaches production — `voltro db branch`
+
+`voltro db plan` tells you what the diff IS. `voltro db branch` tells you what it
+DOES: it branches the live schema into a throwaway namespace, applies the plan
+there (destructive operations included — the branch is disposable, so the
+operation most likely to fail is the one that actually gets rehearsed), re-plans
+to prove the migration converges, and drops the branch.
+
+```bash
+voltro db branch --pr 128 --json > rehearsal.json   # exit 2 = the plan destroys data
+```
+
+Postgres only, and it says so on the other dialects rather than emitting Postgres
+syntax at them. Full behaviour, exit codes and the `--seed` trade-off:
+[Data branching](/docs/database/branching).
+
 ## See also
 
 - [Database / Migrations](/docs/database/migrations) — the schema DSL deep dive
+- [Data branching](/docs/database/branching) — `voltro db branch` + the branch primitive
 - [Self-hosting](/docs/deployment/self-hosting) — production migration patterns
 
 
@@ -1837,7 +2150,16 @@ curl -s localhost:$PORT/_voltro/inspect/rpc     | jq    # api: every query / mut
 curl -s localhost:$PORT/_voltro/inspect/metrics | jq    # rolling per-tag latency + invocation count
 ```
 
-There is no `/_voltro/inspect/queries` endpoint. The registered GET surface is `app`, `routes` (web-only), `cache` (web-only), `rpc` (api-only), `metrics`, and `subscriptions` (api-only) — `rpc` is the procedure list, `routes` is the web page tree.
+There is no `/_voltro/inspect/queries` endpoint. The registered GET surface is `app`, `routes` (web-only), `cache` (web-only), `rpc` (api-only), `metrics`, `subscriptions` (api-only), `checks` (api-only) and `agent/tools` (api-only) — `rpc` is the procedure list, `routes` is the web page tree.
+
+### Invariant checks + the agent-tool surface
+
+```bash
+curl -s localhost:$PORT/_voltro/inspect/checks      | jq   # browser-safety, procedure-access, convergence, serverOnly
+curl -s localhost:$PORT/_voltro/inspect/agent/tools | jq   # the exposeAsTool procedures an agent may run
+```
+
+`checks` runs the framework's own invariant checks and answers `pass | fail | unavailable` per check — `unavailable` means THIS process cannot answer it (a deployed `voltro serve` has no source tree to walk) and is never a pass. `agent/tools` lists the policy-admitted agent tools, and its sibling `POST /_voltro/inspect/agent/call` executes one; both are off until `agents: { mcp: true }`, and the call additionally needs the write credential plus an app credential on `x-voltro-agent-authorization`. See the [MCP server](/docs/cli/mcp) page for the full gate list.
 
 What the surface reads:
 
@@ -1988,6 +2310,19 @@ voltro test --coverage --reporter=junit --outputFile=reports/junit.xml
 That covers coverage numbers and a JUnit report for a merge-request widget, which
 is what most pipelines want beyond the exit code.
 
+**`--coverage` needs a provider package.** vitest ships coverage providers as
+*optional* peer dependencies, so nothing installs one for you. Every app
+scaffolded by `voltro create-project` / `voltro add-app` already declares
+`@vitest/coverage-v8` beside vitest; an older project adds it once:
+
+```bash
+pnpm add -D @vitest/coverage-v8      # or --coverage.provider=istanbul → @vitest/coverage-istanbul
+```
+
+`voltro test` checks for it *before* booting vitest and refuses with that
+install command, because vitest's own failure (`Cannot find dependency
+'@vitest/coverage-v8'`) names neither the flag nor the fix.
+
 The framework keeps three decisions for itself and they win over a forwarded
 flag: the **root** (a positional that is an existing directory, which vitest
 would otherwise read as a filter), `--watch`, and `passWithNoTests` — an explicit
@@ -2015,25 +2350,68 @@ voltro e2e apps/web   # explicit web app directory
 
 1. `voltro dev` for the api app.
 2. `voltro dev` for the web app.
-3. Playwright runs `*.e2e.ts` files.
+3. Runs every file matching `e2e/**/*.spec.ts`, one process each, as a **plain tsx script** (`node --import tsx <file>`).
 4. Tear down: stops the boot processes.
 
-The e2e files use Playwright's API directly:
+**There is no test runner and no browser driver here.** A spec is an ordinary TypeScript program: it runs top to bottom, and a non-zero exit code (an uncaught throw, `process.exit(1)`, a failed `node:assert`) is a failed file. The framework ships no `describe`/`it`, no `page` fixture, no reporter, no sharding, and no browser — because what `voltro e2e` actually contributes is the *lifecycle*, and the lifecycle is the same whichever driver you pick.
+
+Two environment variables are handed to every spec:
+
+| Variable | Value |
+|---|---|
+| `WEB_URL` | `http://localhost:<webPort>` — the booted web app |
+| `API_URL` | `http://localhost:<apiPort>` — the booted api app |
+
+A spec that only needs the API is just `fetch` plus `node:assert`:
 
 ```ts
-// apps/web/tests/signup.e2e.ts
-import { test, expect } from '@playwright/test'
-
-test('signup creates a user', async ({ page }) => {
-  await page.goto('/signup')
-  await page.fill('[name=email]', 'a@b.com')
-  await page.fill('[name=password]', 'correct horse battery staple')
-  await page.click('button[type=submit]')
-  await expect(page).toHaveURL(/\/dashboard/)
+// apps/web/e2e/signup.spec.ts
+import assert from 'node:assert/strict'
+
+const res = await fetch(`${process.env.API_URL}/v1/signup`, {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ email: 'a@b.com', password: 'correct horse battery staple' }),
 })
+
+assert.equal(res.status, 200)
+console.log('✓ signup accepted')
+```
+
+To drive a real browser, bring your own driver and launch it inside the spec — the framework does not choose one for you, and does not install one:
+
+```ts
+// apps/web/e2e/signup-browser.spec.ts
+import assert from 'node:assert/strict'
+import { chromium } from 'playwright-core'   // your dependency, not the framework's
+
+const browser = await chromium.launch()
+const page = await browser.newPage()
+await page.goto(`${process.env.WEB_URL}/signup`)
+await page.fill('[name=email]', 'a@b.com')
+await page.fill('[name=password]', 'correct horse battery staple')
+await page.click('button[type=submit]')
+await page.waitForURL(/\/dashboard/)
+assert.ok(page.url().includes('/dashboard'))
+await browser.close()
 ```
 
-The framework's `voltro e2e` handles the lifecycle for you: it boots the api + web siblings, runs Playwright against them, and tears the processes down on exit. Per-test isolation, fixtures, reporters, and sharding are configured in your Playwright config — `voltro e2e` itself forwards no flags to Playwright.
+Configure the boot in `app.config.ts`:
+
+```ts
+export default {
+  type: 'web' as const,
+  name: 'web',
+  e2e: {
+    apiDir: '../api',            // relative to the web app root
+    pattern: 'e2e/**/*.spec.ts',
+    apiPort: 4000,
+    webPort: 5173,
+  },
+}
+```
+
+Anything below the browser — a handler, a guard, a REST route, an `Idempotency-Key` replay, the `x-tenant` header — is faster and more precise from a [request-level test](/docs/testing/unit-testing#request-level-testing-maketestapp), which needs no booted process at all. Reach for `voltro e2e` when the thing under test *is* the two processes talking to each other.
 
 ## Securing the inspect surface
 
@@ -2606,20 +2984,22 @@ flag is the one-off override.
 <!-- source: en/cli/mcp.md -->
 ## MCP server (voltro-mcp)
 
-_Wire a running Voltro api into Claude Code / Cursor as an MCP server — read-only tools, resources and prompts over the app's procedures, tables, workflows and their JSON Schemas, over stdio or Streamable HTTP._
+_Wire a running Voltro api into Claude Code / Cursor as an MCP server — read the app's procedures, tables, workflows and JSON Schemas, EXECUTE the procedures you expose as agent tools under your app's own permissions, and run the framework's invariant checks. Over stdio or Streamable HTTP._
 
 `@voltro/mcp` ships two standalone bins — **`voltro-mcp`** (stdio) and **`voltro-mcp-http`** (Streamable HTTP) — that serve a running api's capability manifest to a coding agent over the Model Context Protocol. The agent can then discover what the backend exposes — every rpc procedure with its input/output JSON Schema, the user tables, the workflows, the schema-driven-UI widget kinds — before writing UI or agent code.
 
-It is **read-only metadata**: nothing here can execute a procedure or return row data. The bins talk to the same `GET /_voltro/inspect/manifest` endpoint the [inspect surface](/docs/cli/inspect) exposes, and honour its token gate. The server advertises three MCP capabilities — **tools**, **resources**, and **prompts**.
+Discovery is **read-only metadata** and is what you get with nothing configured beyond a URL: the bins talk to the same `GET /_voltro/inspect/manifest` endpoint the [inspect surface](/docs/cli/inspect) exposes, and honour its token gate. Two further surfaces are **off until you turn them on** — executing your app's agent tools, and the invariant checks. Both are covered below. The server advertises three MCP capabilities — **tools**, **resources**, and **prompts**.
 
 ## Setup
 
-Two environment variables, both optional:
+Four environment variables. The first two cover read-only discovery; the last two are what an executing tool call needs.
 
 | Var | Default | Notes |
 |---|---|---|
 | `VOLTRO_INSPECT_URL` | `http://localhost:4000` | Base URL of the running api. |
-| `VOLTRO_INSPECT_TOKEN` | _(unset)_ | Sent as `Authorization: Bearer <token>` when the inspect surface is gated. |
+| `VOLTRO_INSPECT_TOKEN` | _(unset)_ | Sent as `Authorization: Bearer <token>`. The inspect surface is fail-closed, so without it every call is a 401. |
+| `VOLTRO_INSPECT_WRITE_TOKEN` | _(unset)_ | Required to EXECUTE an app tool — a tool call is a non-GET inspect request, and those need a second credential. Read-only discovery does not use it. |
+| `VOLTRO_AGENT_TOKEN` | _(unset)_ | The **app** credential a tool call executes as. Never the inspect token — see below. |
 
 ### Claude Code
 
@@ -2654,6 +3034,9 @@ claude mcp add voltro --env VOLTRO_INSPECT_URL=http://localhost:4001 -- npx -y @
 | `voltro_get_table` | One table's full column list (types, nullability, FK targets, enums). |
 | `voltro_list_workflows` | The registered durable workflows. |
 | `voltro_list_widgets` | The schema-driven-UI widget kinds. |
+| `voltro_check_invariants` | The framework's invariant checks against the running app — see below. |
+
+Plus one `app_<procedure>` tool per procedure your app exposes as an agent tool AND its policy admits — see the next section. Those are the only tools that execute anything.
 
 ## The resources
 
@@ -2675,6 +3058,94 @@ Reusable MCP **prompt templates** that render against the _live_ manifest, so th
 | `explain_table` | `table` | The table's schema + the procedures that read/write it. |
 | `wire_ui_for_procedure` | `tag` | A brief to call one procedure and render its result, embedding its real input/output schema. |
 
+## Executing your app's procedures
+
+A procedure annotated `exposeAsTool` can be **called** by the agent — the tool body is the real rpc handler, run under a `Subject` your app's own auth chain resolved. So the agent's ceiling is that subject's permissions, by construction: there is no second authorization path, because there is no second path. A guard that refuses the subject refuses the agent.
+
+It is off until you say otherwise, at five independent gates:
+
+```ts
+// app.config.ts
+export default {
+  agents: {
+    tools: { allow: ['todos.*'], deny: ['*.purge'], includeWrites: true },
+    mcp: true,
+  },
+}
+```
+
+```ts
+// mutations/todos.create.mutation.ts
+export const descriptor = defineMutation({
+  name: 'todos.create',
+  input: Schema.Struct({ title: Schema.String }),
+  guards: [{ scope: 'todos:write' }],
+  exposeAsTool: { description: 'Create a todo for the signed-in user', confirm: false },
+})
+```
+
+1. **`agents.mcp: true`.** Not implied by anything else. Having an inspect token is not consent to let an agent execute procedures.
+2. **`VOLTRO_INSPECT_TOKEN`** — the transport is fail-closed; `voltro dev` mints one per project, `voltro serve` mints nothing.
+3. **`VOLTRO_INSPECT_WRITE_TOKEN`** + the `x-voltro-inspect-write` header. A tool call is a POST, and every non-GET inspect request already needed a second credential. An existing deployment with only the read token therefore executes nothing.
+4. **`VOLTRO_AGENT_TOKEN`** — the app credential the call executes AS, sent on its own `x-voltro-agent-authorization` header. **Required.** The inspect bearer is an operator credential; letting it double as an app identity would be exactly the second authorization path, and running as the anonymous subject instead would execute under a principal nobody chose. With [`apiKeys: true`](/docs/configuration/api-keys) your app already mints a scoped credential for this — scope it to what the agent may do, not to what you may do.
+5. **`agents.tools`** — the same `AppToolPolicy` the in-process [`appTools`](/docs/ai/tools) loop takes, so one policy covers both. `deny` beats `allow`; `includeWrites: true` is required before any mutation or action is callable at all.
+
+Then the app's own guards run. Nothing above replaces them.
+
+### `confirm` tools are not mounted here
+
+`confirm` means a human approves the concrete call before it executes. There is no human in the MCP server's process, and there is no way to produce one: a confirmation carried in the tool's arguments is written by the model, and an MCP client's approval prompt is a property of that client — several harnesses auto-approve. So a `confirm` tool is dropped, with that reason, rather than mounted in the hope that the far side asks.
+
+Writes confirm by default. An app that wants one callable unattended says so per descriptor (`exposeAsTool: { confirm: false }`) or app-wide (`agents.tools.requireConfirmForWrites: false`) — both are edits a reviewer sees in the diff.
+
+### Naming, and what an agent sees
+
+`todos.create` mounts as `app_todos_create` (MCP tool names are `[A-Za-z0-9_-]`). The tag is resolved back through the listing the server rendered, never by un-mangling the name the model produced, so no amount of argument shaping selects a different procedure. Writes are marked `[WRITE]` in the description — the model has no other signal that one of two tools destroys data.
+
+Everything that did NOT mount is reported with a reason (`GET /_voltro/inspect/agent/tools` returns `dropped[]`), because a tool silently missing from an agent's set is a support ticket that opens with "the agent says it can't do that".
+
+### In the audit trail
+
+An agent call runs the same plugin interceptor chain as a socket call, so `plugin-audit` records it as usual. It additionally stamps `via: 'agent'` on the write attribution, with the subject id of the **person** the agent acted as — an agent never escalates identity, which is precisely why an unmarked agent write would be indistinguishable from a human one. A change-event tap reads it as `event.via`.
+
+### What this does NOT defend against
+
+Stated rather than implied, because a bound you assume is worse than one you do not have:
+
+- **Prompt injection that steers the model into misusing a tool it IS permitted to run.** The allowlist bounds WHICH tools exist; it cannot bound intent. Tool results are your app's data, and app data can contain instructions.
+- **A client holding all three credentials.** It can call any admitted tool with any arguments. The bound is the subject's permissions — which is the design, and the reason to scope `VOLTRO_AGENT_TOKEN` narrowly.
+- **Call rate.** `maxPerRun` is reported for a client to honour; honouring it is the client's. Use [`plugin-ratelimit`](/docs/plugins/ratelimit) on the procedure for a bound that holds regardless of who is calling.
+
+## Verifying your own work
+
+`voltro_check_invariants` runs the framework's own invariant checks against the **running** app and returns a machine-readable verdict — the loop that turns "I generated some code" into "I checked it". `GET /_voltro/inspect/checks` is the same thing over HTTP.
+
+| Check | Answers |
+|---|---|
+| `browser-safety` | Does the generated rpcGroup transitively value-import a server-only module? The finding carries the full **import chain** — a bare specifier says a rule broke, the chain says which shared `lib/` file broke it. |
+| `procedure-access` | Does every wire-exposed procedure declare `guards:` or `openAccess:`? Runs the same verdict the boot gate runs, including `security.defaultDeny`. |
+| `schema-convergence` | Has the live schema drifted, and are operations pending? Read from the same snapshot `voltro db plan --against` reads. |
+| `server-only-exposure` | Does a wire-reachable query declare a `.serverOnly()` column in its output? |
+
+Each answers `pass`, `fail`, or **`unavailable`** — and `unavailable` is never a pass. Two of these read the source tree, and a deployed `voltro serve` has no generated rpcGroup to walk (frequently no `src/` at all after a `pnpm deploy`), so it reports them `unavailable` **with the reason** rather than omitting them. Three green checks that you cannot distinguish from "nobody looked" would be worse than no answer.
+
+```json
+{
+  "checks": [
+    { "id": "browser-safety", "status": "unavailable",
+      "reason": "this process has no generated rpcGroup to walk — the check reads the SOURCE import graph…" },
+    { "id": "procedure-access", "status": "fail",
+      "summary": "1 wire-exposed procedure(s) declare no access decision",
+      "findings": [{ "tag": "todos.secret", "kind": "query", "file": "queries/todos.secret.query.ts" }],
+      "fix": "give each one either `guards: [{ scope: '…' }]` or `openAccess: '<why it is public>'`…" }
+  ],
+  "summary": { "pass": 2, "fail": 1, "unavailable": 1 },
+  "mode": "serve"
+}
+```
+
+`voltro doctor`'s rule set is deliberately NOT here: it is a source-tree scan with its own allowlist file and exit-code contract, it would answer `unavailable` on the one deployment shape this surface exists to reach, and re-hosting it behind HTTP would be a second implementation of a large thing. Run the command, on the machine that has the source.
+
 ## Streamable HTTP transport
 
 For clients that speak MCP over HTTP, **`voltro-mcp-http`** serves the same surface over the current **Streamable HTTP** transport (the single-endpoint POST/GET model that replaced the old HTTP+SSE dual-endpoint). One endpoint handles:
@@ -2698,7 +3169,7 @@ The manifest is read through a TTL-cached source (~10 seconds): a procedure you
 
 ## Protocol scope
 
-MCP over JSON-RPC 2.0. `initialize` negotiates the protocol revision (`2025-06-18`, `2025-03-26`, `2024-11-05`) and advertises the `tools`, `resources`, and `prompts` capabilities; methods are `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`. The stdio bin frames this as newline-delimited JSON-RPC; the HTTP bin serves it over Streamable HTTP. Both transports route to the same pure protocol core (`handleMcpRequest`, `callTool`, `listResources`/`readResource`, `listPrompts`/`getPrompt`, `routeHttp`), all exported from `@voltro/mcp`.
+MCP over JSON-RPC 2.0. `initialize` negotiates the protocol revision (`2025-06-18`, `2025-03-26`, `2024-11-05`) and advertises the `tools`, `resources`, and `prompts` capabilities; methods are `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`. The stdio bin frames this as newline-delimited JSON-RPC; the HTTP bin serves it over Streamable HTTP. Both transports route to the same protocol core, all exported from `@voltro/mcp`: the pure `handleMcpRequest` (`callTool`, `listResources`/`readResource`, `listPrompts`/`getPrompt`) plus `handleMcpRequestAsync`, which handles the two methods that need a round trip to the app — `tools/list` folds in the admitted agent tools, and `tools/call` executes one or runs the invariant checks. With no live connection configured, `handleMcpRequestAsync` behaves exactly like the pure one.
 
 
 
@@ -2707,13 +3178,24 @@ MCP over JSON-RPC 2.0. `initialize` negotiates the protocol revision (`2025-06-1
 <!-- source: en/cli/update.md -->
 ## Update
 
-_voltro update — bump the framework to the latest version and run the codemods that adapt your source to any changed APIs._
+_voltro update — what the command does and does not do. It bumps and installs; it does not make your app boot. The boot refusals this release ships, and the order you meet them._
 
 `voltro update` upgrades an app to the latest framework release. It does three things in order:
 
 1. **Bump** every `@voltro/*` dependency in `package.json` to the target version.
 2. **Install** with your project's package manager — see [Which package manager](#which-package-manager) below.
-3. **Run the codemods** shipped with the target version — automatic source rewrites for any breaking API change, plus printed manual steps for anything that can't be automated.
+3. **Run the codemods** shipped with the target version. A codemod is either a **transform** (rewrites your source) or **`manual`** (prints written steps, only when your app is affected). **Every one of 0.34.0's 21 codemods is `manual`** — nothing is rewritten for you, and there is no diff to review afterwards.
+
+**`voltro update` does not make your app boot.** It moves versions and prints
+instructions; deciding what those instructions mean for your code is yours.
+0.34.0 ships **six boot refusals** — three of them fire on `voltro dev`, before
+you deploy anything — and `update`, `db apply` and `typecheck` all pass while an
+app is dead in every one of them. Start with [`voltro doctor`](#start-here-voltro-doctor),
+then read [the boot refusals](#the-boot-refusals-and-where-you-meet-them).
+
+For the per-change narrative — what each of the 21 notes is about and why —
+read [Upgrading to 0.34.0](/docs/releases/upgrading-to-0-34). This page is the
+command's own contract.
 
 ```bash
 voltro update                 # bump to the latest published version, install, run codemods
@@ -2729,7 +3211,219 @@ voltro update --codemods-only --from 0.3.0            # re-run codemods 0.3.0
 voltro update --codemods-only --from 0.3.0 --to 0.4.0 # explicit delta
 ```
 
-### Taking only part of the jump — `--only`
+## Start here: `voltro doctor`
+
+`voltro doctor` is the command that lists what will refuse to boot, and it
+reports the **exact set the boot refuses on, from the same function** — not a
+second implementation that can disagree with it.
+
+```bash
+voltro update
+voltro doctor          # every undecided procedure + every unverified webhook, by tag and file
+voltro doctor --json   # accessDecisions.undecided / webhookVerification.unverified — for CI
+```
+
+Run it before you try to start anything. Its two most important sections are the
+two source-shaped refusals below:
+
+```text
+access decisions · security.defaultDeny ON
+  ✗ no access decision                      18
+  ✓ openAccess, declared on purpose          0
+
+  ✗ notes.list  (query)
+      api/notes/list.query.ts
+  …
+
+  `voltro dev` and `voltro serve` REFUSE to boot on these. Give each a decision:
+  `guards: [{ scope: '…' }]`, or `openAccess: '<why anyone may call it>'`.
+```
+
+**What doctor cannot see.** It reads your source tree, so it covers the access
+decisions and the webhook declarations. The other four refusals are properties
+of your *environment* — a connection URL, `NODE_ENV`, a migration that has not
+run against a particular database — and no source scan can predict them. Read
+the list below for those.
+
+## The boot refusals, and where you meet them
+
+Six of them ship in 0.34.0. `voltro update` succeeds, `voltro db apply`
+succeeds and `voltro typecheck` succeeds in **all six** — the access decision is
+a runtime boot gate, not a type error, and the other five are environment facts
+no compiler is looking at. They are listed here in the order you actually meet
+them: the first three on your own machine, the last three in a container.
+
+### On your laptop — `voltro dev`
+
+**1. A wire-exposed procedure that decides nothing.** `guards:` used to default
+to *allowed*, so a `*.query.ts` with no guard was callable by any authenticated
+session. Every discovered procedure now declares `guards:` or `openAccess:`, or
+neither `voltro dev` nor `voltro serve` starts.
+
+```text
+[access] 18 wire-exposed procedures declare no access decision, and this app runs with `security.defaultDeny`:
+
+    notes.list  (query)
+      api/notes/list.query.ts
+    …
+
+  Each of these is callable by ANY authenticated session. Give each one a
+  decision — the two are equally acceptable and they are not the same claim:
+
+    guards: [{ scope: 'invoices:read' }]        the caller must hold a scope
+    openAccess: 'public pricing, no user data'  anyone may call it, and why
+```
+
+Three things worth knowing before you start editing:
+
+- **`openAccess` takes a reason, not a boolean.** It is what makes "we decided
+  this is open" distinguishable from "nobody looked".
+- **Do not rubber-stamp with a scope every caller already holds.** That
+  satisfies the gate, reads as protection, and enforces nothing.
+- **A procedure only other server code calls wants neither.** Mark it
+  `internal: true` and it leaves the wire entirely (and then it must not carry
+  `openAccess` — the definers refuse that combination).
+- **Your plugins' procedures are not your problem.** The gate reads your app's
+  own discovered files only.
+
+**The one-field escape hatch**, if you need to ship before you have decided
+everything:
+
+```ts
+// app.config.ts
+export default { security: { defaultDeny: false } }
+```
+
+That restores the old default-allow for the WHOLE app, in one place a reviewer
+can see. There is deliberately no env var for it — an env var is how a security
+default gets turned off in one CI job and stays off. `voltro doctor` keeps
+listing the undecided procedures while it is off, marked advisory.
+
+**2. An incoming webhook that does not say how it authenticates its caller.**
+An incoming webhook is a public, unauthenticated POST that runs your
+application code. The transport refuses to mount one that declared nothing:
+
+```text
+incoming webhook '/webhooks/stripe' is mounted without declaring how it authenticates its caller.
+An incoming webhook is a public POST that runs your application code, so the framework refuses
+to mount one that nothing verifies. Declare it on the descriptor:
+  · provider: stripeWebhookProvider()  — or any provider preset (HMAC + replay window)
+  · signature: { _tag: 'hmac', algorithm: 'hmacSha256', header: 'X-Signature', ... }
+  · verification: 'provider'           — the handler verifies with the provider's own SDK
+  · verification: 'none'               — deliberately public (gateway / IP allow-list owns it)
+A signature-verified webhook also needs its shared secret in VOLTRO_WEBHOOK_SECRET_<ID>;
+the framework mints no secret for you.
+```
+
+`verification: 'none'` is a legitimate answer when a gateway or IP allow-list
+owns the trust boundary. It has to be *said*, which is the whole change.
+
+**3. A mysql / mariadb / mssql URL asking for TLS the dialect cannot honour.**
+Both dialects used to DROP a TLS request rather than reject it, so
+`DB_URL=mysql://…?ssl=true` connected in plaintext with no warning. Only the two
+modes the cross-dialect `ssl` boolean can express are accepted; everything else
+throws where the connection is built — which is `voltro dev`, `voltro serve`,
+`voltro db apply` and `voltro migrate` alike.
+
+```text
+DB_URL '?sslmode=verify-full' is not supported by the mysql/mariadb dialect —
+use 'require' (TLS without certificate verification) or 'disable' (plaintext).
+```
+
+| URL says | Result |
+|---|---|
+| `?sslmode=require` / `?ssl=true` / `?ssl=1` | TLS, certificate NOT verified |
+| `?encrypt=1` | same (mssql only — tedious' spelling) |
+| `?sslmode=disable` / `?ssl=false` / `?ssl=0` | plaintext, explicitly |
+| `prefer`, `allow`, `verify-ca`, `verify-full`, `?ssl=yes`, a CA-profile name | **throws at boot** |
+
+If your URL said `?ssl=true` you were being lied to — that connection has been
+plaintext, and it is real now. **Confirm your server accepts TLS before rolling
+out.** Check it from the database rather than from the config:
+
+```sql
+-- mysql / mariadb: empty = plaintext, a cipher name = encrypted
+SHOW STATUS LIKE 'Ssl_cipher';
+-- mssql: FALSE / TRUE
+SELECT encrypt_option FROM sys.dm_exec_connections WHERE session_id = @@SPID;
+```
+
+postgres, sqlite and turso are unaffected.
+
+### In the container — `voltro serve` / `voltro start`
+
+These three fire only on a deploy environment (`NODE_ENV=production` or
+`staging`), which is exactly why they are the expensive ones: nothing on your
+machine reproduces them.
+
+**4. Pending `migrations/*.migration.ts` that have never run against this
+database.** It always had to run before serve; what changed is that skipping it
+is loud. Serve's other schema guard is a declarative fingerprint diff, and a
+file migration exists for the changes a state diff cannot infer — a data move, a
+backfill, a cross-table rewrite. Those move no fingerprint, so the guard passed
+and production ran un-migrated.
+
+```text
+serve: refusing to boot — 3 pending file-based migration(s) have never run against this
+database. They perform the changes a schema diff cannot infer (data moves, backfills, table
+splits), so the declarative fingerprint check below cannot see them and would have let this
+process serve un-migrated data.
+
+Run them from your pre-deploy job — `voltro db migrate .` (schema + files) or `voltro db files .`
+(files alone) — or set VOLTRO_AUTO_MIGRATE=0 to bypass every boot schema check. `voltro serve`
+never applies them itself: a rolling deploy would start N replicas and each would try.
+```
+
+Serve will not apply them for you, deliberately: a rolling deploy starts N
+replicas, each would try, and the migration lock turns that into N-1 processes
+blocked on boot. A refusal is recoverable in one command; a fleet wedged behind
+a lock is not.
+
+**5. `plugin-search` on the in-memory backend.** The heap-resident index is
+per-process AND non-durable — it starts empty after every deploy and nothing
+re-seeds it — so a single replica does not make it correct.
+
+```text
+plugin-search refuses to boot in production on the in-memory backend.
+
+The memory index lives in THIS process's heap. Two consequences, both silent:
+  • every replica holds a different index, so a result depends on which replica served you;
+  • the index starts EMPTY after every restart/deploy, and nothing re-seeds it automatically.
+
+Configure a durable engine in app.config.ts:
+  searchPlugin({ backend: { engine: 'typesense',    url: …, apiKey: … }, indexes })
+  …
+```
+
+If your deployment genuinely is one process that calls `backfillIndex` at
+startup, declare it: `searchPlugin({ singleProcessMemoryIndex: true, indexes })`
+— a claim the plugin holds you to, not a mute switch. Full reasoning:
+[the memory backend refuses to boot in production](/docs/plugins/search#the-memory-backend-refuses-to-boot-in-production).
+
+**6. `SSR_CACHE=postgres` with no database in the web process's environment.**
+`voltro start` used to select the postgres ISR cache only when `PG_HOST` was
+set, while every template and every deployment doc configures `DB_URL` — so an
+app that asked for the shared cache the documented way silently got the
+per-process memory one, reported at `info` as if it were the default. Both sides
+go through the connection resolver now, and the mismatch is fatal on a deploy
+environment:
+
+```text
+SSR_CACHE=postgres, but nothing in the environment names a database (looked for DB_URL,
+DB_PRIMARY_URL, DB_DIRECT_URL, DB_MIGRATE_URL, DB_HOST, PG_HOST). Refusing to fall back to
+the per-process memory cache: it is not shared between instances and does not survive a
+restart, so the pages this process serves would differ from its replicas' with nothing to
+indicate it.
+```
+
+Either give the web process a `DB_URL`, or drop `SSR_CACHE=postgres` and take
+the memory cache deliberately. Off a deploy environment it warns and falls back
+instead. Two knock-on effects with nothing to edit: pages declaring
+`cacheInvalidatesOn` that had *no* live invalidation now have it (a real change
+in origin load), and a web process with no database that declares
+`cacheInvalidatesOn` gets a boot warning naming those routes.
+
+## Taking only part of the jump — `--only`
 
 Ids are what `--dry-run` prints:
 
@@ -2803,7 +3497,16 @@ source version.
 
 ## The clean-tree guard
 
-Codemods **rewrite your source**, so you need a clean diff to review afterwards. `voltro update` refuses to run on a dirty git working tree — commit or stash first. Use `--dry-run` to preview without touching anything, or `--force` to override the guard (you accept a mixed diff).
+`voltro update` refuses to run on a dirty git working tree — commit or stash
+first. Use `--dry-run` to preview without touching anything, or `--force` to
+override the guard (you accept a mixed diff).
+
+The guard is about the writes `update` makes on your behalf: the version bump
+across every workspace `package.json`, the lockfile the install rewrites, and —
+in a release that ships one — a **transform** codemod rewriting your source.
+When the jump's codemods are all `manual`, as 0.34.0's 21 are, `update` writes
+nothing under `src/` at all, and the work the printed notes describe is a
+separate commit you author yourself.
 
 `--help` / `-h` is answered *before* the guard, so `voltro update --help` prints the flag list even on a dirty tree. The same holds for `voltro doctor --help`.
 
@@ -2882,27 +3585,68 @@ The same resolved manager is used for the **registry lookup** of the latest vers
 
 ## Codemods
 
-Each breaking public-API change in a release ships a **codemod**. When you update across that release, `voltro update` applies it:
+Each breaking public-API change in a release ships a **codemod**, and there are exactly two kinds:
+
+- A **transform codemod** rewrites your source automatically — renamed imports, moved modules, changed component props, restructured call signatures. The rewrite is scoped to files that actually import the affected symbol. Where the affected sites can be found but the fix needs your judgment, it inserts `// TODO(voltro-migration): …` markers so you can locate every spot.
+- A **manual codemod** prints written steps during the update, `appliesTo`-gated so you see it only when your app is actually affected. It writes nothing.
+
+**0.34.0's are all manual — 21 of them, zero transforms.** That is not an
+omission. The largest change in the release asks a question only you can answer
+("who may call this procedure?"), and a transform could have answered it
+mechanically for every procedure in your app — declaring your entire surface
+open on purpose, in one commit nobody reads, with a reason the tool invented.
+The framework does not sign that.
 
-- A **transform codemod** rewrites your source automatically — renamed imports, moved modules, changed component props, restructured call signatures. The rewrite is scoped to files that actually import the affected symbol.
-- A **manual codemod** prints written steps during the update, only when your app is affected — for changes that can't be mechanically transformed (a behavior change, a descriptor/executor restructure). Where the affected sites can be found but the fix needs your judgment, a codemod inserts `// TODO(voltro-migration): …` markers so you can locate every spot.
+So on this jump the output is a wall of text and no diff:
+
+```text
+Manual steps required (could not be automated):
+
+▸ 0.34.0/03_procedure-access-decision — Every wire-exposed procedure declares an access decision (`guards:` or `openAccess:`)
+  YOUR APP WILL NOT BOOT UNTIL EVERY WIRE-EXPOSED PROCEDURE DECIDES WHO MAY
+  CALL IT. …
+```
 
-Codemods that span multiple versions run in order (e.g. upgrading `0.2.0 → 0.4.0` runs the `0.3.0` and `0.4.0` codemods in sequence). Review the resulting diff before committing.
+Read the notes. They are the only artefact the upgrade produces, and each one
+prints only because your tree matched it.
+
+Codemods that span multiple versions run in order (e.g. upgrading `0.2.0 → 0.4.0` runs the `0.3.0` and `0.4.0` codemods in sequence).
 
 ## The database is separate
 
-`voltro update` does **not** touch your database. Framework-owned `_voltro_*` tables (workflow runs, schedules, …) are reconciled by the declarative differ, not by codemods: when a release changes one of those tables, your next `voltro db apply` (or `voltro dev` boot, which auto-applies) picks up the change. After an update:
+`voltro update` does **not** touch your database. Framework-owned `_voltro_*` tables (workflow runs, schedules, …) are reconciled by the declarative differ, not by codemods: when a release changes one of those tables, your next `voltro db apply` (or `voltro dev` boot, which auto-applies) picks up the change.
+
+Use `voltro db apply` (the declarative diff), not `voltro db migrate` (the imperative file-runner) — only the former reconciles framework tables. If your app also ships `migrations/*.migration.ts`, `voltro db migrate .` runs both halves and is what refusal 4 above asks your pre-deploy job for.
+
+## After the update — the checklist
 
 ```bash
 voltro update
-voltro db apply        # reconcile any changed framework tables — NOT voltro db migrate
-# then run your typecheck to confirm your code compiles against the new API
+voltro doctor          # ← the one that can fail. Every undecided procedure + unverified webhook.
+voltro db apply        # reconcile any changed framework tables
+voltro typecheck       # your code against the new API surface
+voltro dev             # the first boot that actually exercises the gates
 ```
 
-Use `voltro db apply` (the declarative diff), not `voltro db migrate` (the imperative file-runner) — only the former reconciles framework tables.
+**`update`, `db apply` and `typecheck` all pass on an app that will not start.**
+That is the shape to internalise: the access decision is a runtime boot gate, not
+a type error; the webhook declaration is a descriptor property, not a signature;
+and the environment-shaped refusals are facts about a container you have not
+started yet. The only two steps in that list that can tell you the truth are
+`voltro doctor` and an actual boot.
+
+For a deploy, add the container-side ones to your pre-deploy job before the
+image rolls:
+
+```bash
+voltro db migrate .    # schema diff AND file migrations — refusal 4
+# and check by hand: the mysql/mssql DB_URL's ?sslmode (3), a durable search
+# backend (5), and DB_URL on the WEB process if it sets SSR_CACHE=postgres (6)
+```
 
 ## Where to read next
 
+- [Upgrading to 0.34.0](/docs/releases/upgrading-to-0-34) — the per-change narrative behind the 21 notes
 - [Migrate](/docs/cli/migrate) — schema changes end-to-end
 - [Build & start](/docs/cli/build-and-start) — production paths