@voltro/cli 0.1.0

package/templates/agent-docs/cli.md

@@ -0,0 +1,1650 @@
+# CLI
+
+> The voltro CLI — every command, grouped by purpose, with the flags that actually matter.
+
+
+
+---
+
+<!-- source: en/cli/overview.md -->
+## Overview
+
+_The voltro CLI — every command, grouped by purpose, with the flags that actually matter._
+
+The Voltro CLI is the single entry point for scaffolding, dev, build, and run. It also seeds the framework agent guide into every project — written under BOTH `AGENTS.md` and `CLAUDE.md` — so AI coding agents have your framework conventions on tap.
+
+## Command quick-reference
+
+The dispatcher routes `voltro <command> [args]` to the matching subcommand and passes the rest through. The full set:
+
+| Group | Commands |
+|---|---|
+| [Scaffolding](/docs/cli/scaffolding) | `create-project`, `add-app`, `list-templates` |
+| Packages | `package` (`create` / `publishable` / `private` / `status`), `create-package` |
+| [Dev](/docs/cli/dev) | `dev`, `codegen`, `agents-md` |
+| [Build & run](/docs/cli/build-and-start) | `build`, `start`, `serve` |
+| Deploy | `deploy` (`plan` — auto-detect the target tier per app + function), [`serverless`](/docs/deployment/serverless-functions) (`list` / `dev` / `serve` / `build` / `deploy`), [`static`](/docs/deployment/static-sites) (`hosts` / `deploy`) |
+| [Database](/docs/cli/migrate) | `migrate`, `db` (`plan` / `apply` / `plans` / `drift` / `squash` / `restore-snapshot` / `migrate` / `rollback` / `status` / `seed`) |
+| [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`) |
+| 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 |
+| [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` |
+| 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` |
+
+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).
+
+## 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.
+
+## Common per-command flags
+
+There is no universal global-flag layer; flags are per-command. The ones that recur:
+
+| Flag | Where it applies |
+|---|---|
+| `--format pretty\|json` | `logs`, `traces`, `inspect`, `cluster`, `workflows` — machine-readable output. |
+| `--no-color` | `logs`, `traces` — strip ANSI codes when piping to a file. |
+| `--process <name>` | `logs`, `traces`, `inspect`, `cluster` — narrow to one running process. |
+| `--force` | `agents-md` — overwrite existing files. |
+
+Commands like `build` / `start` / `migrate` / `codegen` parse no flags at all — only an optional path. Check each command's page for its real surface.
+
+## Common env vars
+
+The CLI reads:
+
+| Var | Effect |
+|---|---|
+| `NODE_ENV` | `production` / `development` / `test`. Affects defaults across many commands. |
+| `DB_DIALECT` | `postgres` *(default)* / `mysql` / `mariadb` / `mssql` / `sqlite` / `turso` / `memory`. Picks the SQL backend. |
+| `STORE` | `memory` / `postgres` — alternate data-store selector (resolution order: `DB_DIALECT` → `STORE` → `app.config.ts`). |
+| `WATCH` | `0` / `1`. Toggle filesystem watch in `voltro dev`. |
+| `VOLTRO_DASHBOARD` | `off` to disable the auto-launched dashboard. |
+| `VOLTRO_LOG_FORMAT` | `pretty` / `json`. Force the logger's output format. |
+| `VOLTRO_LOG_LEVEL` | `trace` / `debug` / `info` / `warn` / `error` / `fatal`. |
+| `VOLTRO_INSPECT` | `off` to disable the `/_voltro/inspect/*` HTTP endpoints. |
+| `VOLTRO_INSPECT_TOKEN` | Bearer token for guarded inspect endpoints. |
+| `DB_URL` | Database connection string (falls back to `DB_PRIMARY_URL`; or the discrete `DB_*` / `PG_*` fields). |
+| `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. |
+| `VOLTRO_FIELD_ENCRYPTION_KEY` | Key for `.encrypted()` columns (`governancePlugin({ fieldEncryption: true })`) — a passphrase or a raw 64-hex AES-256 key. |
+| `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. |
+
+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
+
+### "I'm starting a new project"
+
+```bash
+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
+```
+
+### "I want to add a docs site to my existing 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
+```
+
+### "I changed my schema and want to apply it"
+
+```bash
+voltro db plan                 # diff declared schema vs live, color-coded
+# review the plan
+voltro db apply                # execute it (dev)
+# or, for the flagless idempotent apply (CI / ops):
+voltro migrate
+```
+
+### "I want a clean rebuild"
+
+```bash
+voltro codegen                 # rewrite the generated rpc group + .framework/*
+voltro build                   # vite build + SSG pre-render
+voltro start                   # production server
+```
+
+### "Something's wrong — inspect what's running"
+
+```bash
+voltro inspect rpc             # discovered procedures + workflows
+voltro inspect routes          # web page tree (web apps)
+voltro inspect metrics         # request rates, p95 latencies
+voltro logs --tail 100         # recent structured logs
+voltro traces --errors         # traces with an errored span
+voltro workflows list          # recent workflow runs
+```
+
+### "Did my edit break a binding?"
+
+`voltro check` runs blast-radius checks against the **running** api's live
+capability manifest — dangling `source` / `target` tables, unknown RBAC scopes,
+broken route bindings, orphan tables — at edit time instead of at runtime
+(needs `voltro dev` up). `--json` emits LLM-shaped diagnostics so a coding
+agent can fix-and-repeat; `--diff` previews the blast radius of a removal
+BEFORE you apply it.
+
+```bash
+voltro check                          # blast-radius checks vs the live manifest
+voltro check --json                   # { ok, diagnostics: [{ rule, node, breaks, fix }] }
+voltro check --diff removeTable:todos # what a proposed removal would break, before applying
+```
+
+The HTTP surface is reachable directly too — e.g. `curl -s localhost:4000/_voltro/inspect/rpc | jq` (there is no `/_voltro/inspect/queries` endpoint; it's `rpc` for procedures, `routes` for the web page tree, `subscriptions` for active subscribers).
+
+## Where to read next
+
+- [Scaffolding](/docs/cli/scaffolding) — start + grow a project
+- [Dev](/docs/cli/dev) — what happens during `voltro dev`
+- [Build & start](/docs/cli/build-and-start) — production paths
+- [Migrate](/docs/cli/migrate) — schema changes end-to-end
+- [Inspect & test](/docs/cli/inspect) — debugging + harness
+
+
+
+---
+
+<!-- source: en/cli/scaffolding.md -->
+## Scaffolding
+
+_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.
+
+## `create-project`
+
+```bash
+voltro create-project <name> [flags]
+```
+
+Bootstraps a new project under `apps/<name>/` with selected templates.
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--api <templateId>` | prompts, then `api-backend` | API template. Use `none` for web-only projects. Also accepts `--api=<id>`. |
+| `--web <templateId>` | prompts, then `frontend-blank` | Web template. Use `none` for api-only. Also accepts `--web=<id>`. |
+| `--cache=redis` | off | Wire the Redis cache backend at scaffold time — sets `cache: 'redis'` in `app.config.ts` and injects the `redis` service + `CACHE_*` env into the active baseline's infra. |
+| `--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. |
+
+What it does:
+
+1. Validates the name (camelCase or kebab-case, no `_`, no leading digits).
+2. Picks the next free port from `--port-range`.
+3. Renders templates into `apps/<name>/api/` + `apps/<name>/web/`, substituting `{{appName}}`, `{{projectName}}`, `{{port}}` placeholders.
+4. Writes `apps/<name>/project.json` recording the project's port range + app list.
+5. Updates `pnpm-workspace.yaml` to include the new project's apps.
+6. Seeds the **agent guide** for each app (see below).
+
+After scaffolding:
+
+```bash
+cd <repo-root>
+pnpm install
+pnpm dev
+```
+
+### The seeded agent guide
+
+`create-project` / `add-app` (and `voltro dev` on first boot) seed a guide that
+teaches AI coding agents the framework's conventions. It's generated, not a
+monolith:
+
+- **Root `AGENTS.md` + `CLAUDE.md`** — a slim always-loaded core (mental model,
+  the primitive rubric, file conventions, the browser/server boundary, naming,
+  anti-patterns) plus an **index** listing the workspace's installed plugins and
+  linking the deep, on-demand topic docs.
+- **Nested `AGENTS.md` + `CLAUDE.md` per app area** (`api/`, `api/database/`,
+  `web/`) — type-specific notes an agent loads only when working there; a
+  scaffolded app's file points at its template's doc.
+- **`.claude/skills/*`** — Claude Code skills for the common how-tos.
+
+Existing files are never overwritten; `voltro agents-md --force` refreshes them.
+Protect a hand-maintained file from `--force` with a `voltro:agents-md:keep`
+HTML comment at the top.
+
+## `add-app`
+
+```bash
+voltro add-app <appName> --template <templateId> [--to <projectName>]
+```
+
+Adds another app to an existing project. Works for any kind — `api`, `web`, or
+`serverless`. A `web` app gets the next free port from the project's range; a
+`serverless` app has no server, so it gets no port (run it with `voltro
+serverless`).
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--template <templateId>` | *(required)* | Template to scaffold. `voltro list-templates` for the catalogue. |
+| `--to <projectName>` | auto-detected | Target project. Required when >1 project exists. |
+
+What it does:
+
+1. Reads the target project's `project.json` for the port range.
+2. Picks the next free port from the range (rejects if the range is exhausted).
+3. Renders the template into `apps/<project>/<appName>/`.
+4. Updates `project.json` to record the new app.
+
+Example:
+
+```bash
+voltro add-app docs --template frontend-docs --to acme
+voltro add-app admin --template frontend-blank --to acme
+```
+
+## `list-templates`
+
+```bash
+voltro list-templates
+```
+
+Prints the catalogue. Templates come in three **kinds** — `api`, `web`, and
+`serverless` (a bundle of [`*.serverless.ts`](/docs/deployment/serverless-functions)
+functions deployed on their own):
+
+```
+id                    kind        summary
+--------------------  ----------  --------------------------------------------
+api-backend           api         Minimal Voltro backend (schema + query + mutation).
+api-backend-mail      api         + @voltro/plugin-mail + a React-Email template.
+api-backend-storage   api         + @voltro/plugin-storage (public + private objects).
+api-backend-mariadb   api         MariaDB binlog CDC + storage, tenant-aware.
+api-durable           api         Durable + reactive: workflow, trigger, cron, subscriber, aggregate.
+api-ai                api         RAG agent: vectorEmbedding + search tool + model loop.
+api-data-advanced     api         Advanced schema: relations, FTS, dbEnum, encrypted, caching.
+api-auth              api         Real user auth: plugin-auth sessions + cookie strategy.
+api-rest              api         Public REST API: defineRestRoute + plugin-openapi (Swagger).
+api-saas              api         SaaS bundle: billing + notifications + analytics + presence.
+api-observability     api         Metrics + errors + tracing + a @voltro/testing unit test.
+api-webhooks          api         First-class webhooks: signature-verified incoming + outgoing emit.
+frontend-blank        web         Empty React + layout shell.
+frontend-app          web         Fullstack reactive loop — wired to an api (useSubscription + useMutation).
+frontend-landing      web         Static marketing page — zero JS on the wire.
+frontend-static-blog  web         SSG blog: getStaticPaths + islands + per-post meta.
+frontend-spa          web         Pure client-rendered SPA (no backend, no SSR).
+frontend-ssr          web         Server-rendered pages: ssr + isr (revalidate, swr).
+frontend-contact      web         Static page + a serverless email form.
+frontend-docs         web         Catch-all docs site with i18n.
+changelog             web         Release-notes site (MDX + RSS).
+edge-functions        serverless  A library of *.serverless.ts functions (8 types).
+```
+
+See the [App templates catalogue](/docs/reference/templates) for what each
+demonstrates + a picks-for table. For programmatic use, add `--json`:
+
+```bash
+voltro list-templates --json
+```
+
+## `generate` (AI app-builder)
+
+`voltro generate "<prompt>"` turns a natural-language prompt into framework
+artifacts — queries, mutations, tables — **constrained to what your app can
+actually express**. It reads the committed capability manifest
+(`app.manifest.generated.json`, emitted by `voltro dev`) as the grammar, asks the
+model for an app graph + the files that realise it, and gates every candidate
+through the real `voltro check` before anything is written. A structurally-invalid
+proposal is re-prompted with its diagnostics (the errors-as-LLM-API loop), never
+written.
+
+```bash
+voltro generate "add a comments table with a list + create"          # dry-run: prints the proposal
+voltro generate "add a comments table with a list + create" --write  # applies the accepted artifacts
+```
+
+**Dry-run by default** — artifacts hit disk only with `--write`, and only ever a
+proposal that passed `voltro check`. Generation is also capped (file count + total
+bytes). Run `voltro dev` once first so the manifest exists.
+
+> Requires a model provider (`AI_PROVIDER` / `AI_MODEL` + the provider key, same
+> as [agents](/docs/ai/agents)). The cloud dashboard exposes the same builder for
+> proposal review (`apps.generateAppGraph`), behind the `aiBuilder` flag (off by
+> default → typed `FlagDisabled`).
+
+## Template tokens
+
+Templates contain `{{token}}` placeholders that the scaffolder substitutes:
+
+| Token | Example value |
+|---|---|
+| `{{appName}}` | `dashboard` |
+| `{{capAppName}}` | `Dashboard` |
+| `{{projectName}}` | `acme` |
+| `{{capProjectName}}` | `Acme` |
+| `{{port}}` | `5191` |
+
+Apply across both file content AND file/directory names — a template file named `{{appName}}.entity.ts` or a dir `pages/{{appNameSnake}}/` renders to your project's names. When writing your own template, use these freely; the substitution is global.
+
+## Writing a custom template
+
+Drop a directory into `voltro-templates/apps/<your-id>/`:
+
+```
+voltro-templates/apps/my-template/
+├── template.json
+├── package.json
+├── app.config.ts
+├── src/
+│   ├── pages/
+│   │   └── index.tsx
+│   └── …
+└── tsconfig.json
+```
+
+`template.json` declares the metadata:
+
+```json
+{
+  "id":      "my-template",
+  "kind":    "web",
+  "summary": "My custom template — does X.",
+  "tags":    ["marketing", "minimal"]
+}
+```
+
+`kind` is one of `api` / `web` / `serverless`. A `serverless` template ships a
+`functions/` dir of `*.serverless.ts` files (no `app.config.ts`, no pages) and
+is added with `voltro add-app`. Now `voltro list-templates` shows it; `voltro
+create-project --web my-template` (or `--api`) uses it, and any kind is added
+with `voltro add-app <name> --template my-template`.
+
+For private templates (in your own repo), set `VOLTRO_TEMPLATES_PATH=/path/to/my/templates` and the CLI walks there instead of the default location.
+
+## Idempotency
+
+The scaffolder refuses to overwrite an existing directory:
+
+```bash
+voltro create-project acme   # fails if apps/acme/ exists
+```
+
+To force, delete the directory first. The framework intentionally doesn't have a `--force` flag — accidental data loss is the kind of thing that happens once + ruins your day.
+
+## Anti-patterns
+
+- **Scaffolding into a non-Voltro repo.** The scaffolder writes to `apps/<project>/` + expects a `pnpm-workspace.yaml`. Without one, `pnpm install` doesn't link workspace packages.
+- **Renaming the scaffolded app directory afterwards.** `project.json` records the path; rename invalidates discovery. Either re-scaffold with the right name, or update `project.json` + every cross-package import by hand.
+- **Editing the templates dir directly to "fix" a scaffolded app.** Templates are starting points. After scaffolding, the app is yours — edit IT, not the template (unless the template itself has a bug).
+
+## See also
+
+- [App templates](/docs/reference/templates) — the catalogue with picks-for table
+- [Dev](/docs/cli/dev) — what `voltro dev` does with the scaffolded app
+
+
+
+---
+
+<!-- source: en/cli/dev.md -->
+## Dev
+
+_voltro dev, codegen, agents-md — what runs during local development and the env flags that shape it._
+
+`voltro dev` is the day-to-day command. It runs different machinery for api vs web apps but the contract is the same: edit a file, the right thing happens.
+
+## `voltro dev <appDir>`
+
+```bash
+voltro dev .                        # current dir
+voltro dev apps/acme/api            # explicit path
+```
+
+### What it does for an api app
+
+1. Reads `app.config.ts`. Bails if not `type: 'api'`.
+2. Walks `queries/`, `mutations/`, `workflows/`, etc. for the discovery patterns.
+3. Generates `.framework/rpcGroup.generated.ts` exporting a typed client.
+4. Starts the RPC over WebSocket server on `:4000` (override with `PORT`, or set `port:` in `app.config.ts`).
+5. Watches every discovery-matching file. On save:
+   - File added/removed → regen the discovery → restart the api process.
+   - File modified → reload the module → fire `hmr update` to connected clients.
+6. Resolves `STORE=memory` (in-memory store) or `STORE=postgres` (real DB).
+7. Auto-launches the inspect dashboard on `:5179` (unless `VOLTRO_DASHBOARD=off`).
+
+### What it does for a web app
+
+1. Reads `app.config.ts`. Bails if not `type: 'web'`.
+2. Walks `src/pages/` for queries + special files.
+3. Generates `.framework/main.tsx`, `.framework/app.tsx`, `index.html`.
+4. Starts Vite with the framework's plugin chain (React, Tailwind v4, page discovery, inspect, dashboard registry).
+5. Binds to the configured port from `app.config.ts.port` (strict — fails on conflict).
+6. Watches `src/`. On save, Vite HMR fires:
+   - TSX changes → React Refresh updates the live component.
+   - CSS changes → swap stylesheets in place.
+   - New page file → regen `.framework/app.tsx` → reload the query tree.
+
+### The in-page devtools overlay
+
+The generated web entry auto-mounts the `@voltro/devtools` overlay — a floating button that expands into live panels (subscriptions, mutations, indexes, webhooks, traces, routes, runtimes, logs; **Alt+V** toggles it). The component AND its stylesheet load dynamically under `import.meta.env.DEV` only; production builds strip the import entirely, so it needs zero code and ships zero bytes to prod. Opt out per app in `app.config.ts`:
+
+```ts
+// app.config.ts (web app)
+export default {
+  type: 'web' as const,
+  name: 'web',
+  disableDevtools: true,   // no overlay import, no mount, no stylesheet
+}
+```
+
+#### Inspect token (token-gated deploys)
+
+The overlay's webhooks / traces / indexes panels poll each api's `/_voltro/inspect/*` endpoints. Under `voltro dev` that surface is open, so no auth is needed. A token-gated deploy (`voltro start` with `VOLTRO_INSPECT_TOKEN` set) requires the same `Authorization: Bearer <token>` the CLI sends — otherwise the panels 401 to their empty state.
+
+The overlay reads that token from `VITE_VOLTRO_INSPECT_TOKEN` (only `VITE_`-prefixed vars reach the browser bundle). A foreign-host mount can also pass it explicitly:
+
+```tsx
+import { VoltroDevtools } from '@voltro/devtools'
+
+<VoltroDevtools inspectToken={import.meta.env.VITE_VOLTRO_INSPECT_TOKEN} />
+```
+
+When neither the prop nor the env var is set, no `Authorization` header is sent — local dev is unaffected. (The indexes panel's live SSE stream can't carry a header; a token-gated deploy falls back to token-carrying HTTP polling for that panel.)
+
+#### Overriding the overlay's labels
+
+Every user-facing label the overlay renders (tab labels, empty states, the FAB tooltip, …) routes through an overridable strings seam — the same pattern as `@voltro/ui`'s `UiStringsProvider`. Localize or rebrand by passing `strings` (deep-merged onto the English defaults — supply only what you change):
+
+```tsx
+import { VoltroDevtools } from '@voltro/devtools'
+
+<VoltroDevtools
+  strings={{
+    tabs: { subscriptions: 'Abos', logs: 'Protokolle' },
+    shell: { openLabel: 'Voltro Devtools öffnen' },
+  }}
+/>
+```
+
+A `<DevtoolsStringsProvider strings={…}>` mounted above the overlay works too; nested providers compose.
+
+### Common flags + env vars
+
+| Var / flag | Notes |
+|---|---|
+| `STORE=memory` | In-memory data store (default). Restart = state gone. |
+| `STORE=postgres` | Real Postgres via `DB_URL` (or the discrete `DB_*` / `PG_*` fields). Survives restarts. `DB_DIALECT` picks the SQL backend. |
+| `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. |
+| `VOLTRO_DASHBOARD_PORT=5180` | Override the auto-launched dashboard port (default `5179`). |
+| `VOLTRO_LOG_LEVEL=debug` | Verbose framework logs. |
+
+## Multi-app dev (turbo)
+
+The `pnpm dev` at the project root delegates to `turbo run dev` which boots every app in parallel:
+
+```bash
+pnpm dev   # ↳ turbo runs `voltro dev` for every workspace app
+```
+
+Turbo's TUI mode shows one pane per app with live output. Set `"ui": "tui"` in `turbo.json` (the scaffolder does this for you).
+
+## `voltro codegen <appDir>`
+
+```bash
+voltro codegen apps/acme/api   # regenerate the codegen for one app
+voltro codegen .               # current dir
+```
+
+Regenerates `rpcGroup.generated.ts` (+ the web `.framework/*` entry) from the discovered descriptors. It takes only an optional app-directory path — no flags. You rarely need this; `voltro dev` does it on every save. Useful for:
+
+- **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.
+
+## `voltro agents-md`
+
+```bash
+voltro agents-md          # seed AGENTS.md if it doesn't exist
+voltro agents-md --force  # overwrite existing file
+```
+
+Seeds the framework agent guide into the repo root under **both** filenames — `AGENTS.md` (the universal convention) and `CLAUDE.md` (project-pinned Claude Code setups) — written atomically from one template so they can't drift. The file teaches AI coding agents (Claude Code, Cursor, GitHub Copilot Chat) Voltro's conventions — file suffixes, schema DSL, query shape, layout contract, anti-patterns.
+
+When the framework's template gains new sections (new file convention, plugin shape change), run `voltro agents-md --force` to pull them in — `--force` overwrites BOTH files. The CLI doesn't auto-overwrite on boot, so apps that customised their guide keep their changes until they ask for a refresh.
+
+## File watch internals
+
+For api apps, Voltro applies its own discovery walker on every save. The patterns that trigger a re-discovery (and the matching `.server.ts` executors):
+
+- `**/*.query.ts`, `**/*.mutation.ts`, `**/*.action.ts`, `**/*.stream.ts` (+ their `.server.ts` siblings)
+- `**/*.workflow.tsx`, `**/*.trigger.tsx`
+- `**/*.cron.tsx`
+- `**/*.webhook.tsx`
+- `**/*.subscribe.ts`
+- `**/*.aggregate.ts`
+- `**/*.agent.tsx`
+- `**/*.email.tsx`
+- `**/*.seed.ts`, `**/*.startup.tsx`
+- `**/*.entity.ts`, `**/*.schema.ts`, `schema.ts`
+- `app.config.ts`
+
+`*.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.
+
+For web apps, Vite's built-in HMR handles the watch.
+
+## Restart triggers
+
+API apps restart (full process kill) on a change to **any source file**
+under the api project dir — every `.ts` / `.tsx` / `.mts` / `.cts` /
+`.js` / `.jsx` / `.mjs` / `.cjs` / `.json`, excluding `*.generated.*`
+(the codegen rewrites those every boot, so watching them would
+self-respawn forever). Concretely that includes:
+
+- `app.config.ts` / `package.json` change
+- A primitive descriptor / executor, or a new/removed primitive file
+- **A shared `lib/` / `services/` helper** that a descriptor or executor
+  imports — editing one respawns the api, because the whole module graph
+  is re-imported on restart (it is NOT enough to watch only the
+  convention files)
+- A change to any `.env` / `.env.local` file the process loaded at boot
+
+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).
+
+The `.env` trigger applies to **both api and web** apps — `process.env` is
+parsed once at boot, so editing a `.env` (or re-pulling secrets, e.g.
+`doppler secrets download > .env`) needs a full re-exec. `voltro dev` watches
+the env-file chain (app dir → ancestors) and hard-restarts, logging
+`.env changed (<file>) — hard-restarting…`. The api releases its port and the
+web closes Vite before the replacement spawns, so the restart can't hit a
+port-in-use race.
+
+## 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.
+
+```bash
+voltro dev apps/acme/api &     # port from apps/acme/api/app.config.ts
+voltro dev apps/orbit/api &    # port from apps/orbit/api/app.config.ts
+voltro dev apps/acme/web &
+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.
+
+## Anti-patterns
+
+- **Running `voltro dev` against a `voltro start` build directory.** The dev server expects source files; pointing it at `dist/` confuses it. Use `voltro start` for that.
+- **Ignoring `app.config.ts` changes.** They require a process restart (the discovery walker re-reads them at boot only). Save, watch the process die + come back up.
+- **Expecting a `.env` edit to hot-reload.** It can't — `process.env` is read once at boot. `voltro dev` hard-restarts the server on a `.env` change (you'll see `.env changed … — hard-restarting`); wait for the process to come back before testing, rather than assuming the new value is already live.
+- **Disabling the dashboard "to save resources".** It's a few MB of RAM + the inspect endpoints fail gracefully. Keep it on; it's the best debugging tool you have.
+
+
+
+---
+
+<!-- source: en/cli/build-and-start.md -->
+## Build & start
+
+_voltro build and voltro start — production builds, SSG pre-render, the SSR bundle, ISR cache._
+
+`voltro build` produces a production artefact; `voltro start` serves it. Two commands, clean separation.
+
+## `voltro build <appDir>`
+
+```bash
+voltro build apps/acme/web
+voltro build .                  # current dir
+```
+
+What it does for a web app:
+
+1. **vite build** against `.framework/` — produces `dist/` with chunked client bundle.
+2. **Pre-renders static pages** — every page with `renderMode: 'static'` is rendered to HTML once + lands at `dist/<path>/index.html`.
+3. **Pre-builds the SSR bundle** — every page module compiled to `dist/server/ssrEntry.js` so `voltro start` doesn't need a Vite middleware loader at runtime.
+4. **Copies `public/`** into `dist/`.
+
+For api apps, `voltro build` bundles the discovery-walked sources + dependencies into a single Node ESM entry at `dist/api.js`. Production servers run it via `node dist/api.js`.
+
+`voltro build` takes a single optional app directory and parses no flags — the SSR bundle is always attempted, and the SSG pre-render always runs for `static`-mode pages.
+
+### Output layout
+
+```
+apps/acme/web/.framework/dist/
+├── index.html                          # SPA shell fallback
+├── about/index.html                    # pre-rendered static page
+├── blog/first-post/index.html          # SSG via getStaticPaths
+├── assets/
+│   ├── index-abc.js                    # main client bundle
+│   ├── index-abc.css
+│   └── island-LikeButton-def.js        # per-island chunks (interactive: 'islands' pages)
+└── server/
+    └── ssrEntry.js                     # SSR bundle for voltro start
+```
+
+## `voltro start <appDir>`
+
+```bash
+voltro start apps/acme/web              # serves the build output
+PORT=8080 voltro start apps/acme/web
+```
+
+What it does:
+
+1. Reads `app.config.ts.port` (or `PORT` env var) for the listen port.
+2. Walks `dist/` to discover pre-rendered HTML files.
+3. Loads the SSR bundle from `dist/server/ssrEntry.js`. Falls back to Vite middleware mode if absent.
+4. Starts an `http.Server` that:
+   - Serves pre-rendered HTML for matched URLs.
+   - Serves static assets from `dist/assets/`, `dist/_voltro/`.
+   - Renders SSR pages per request via the SSR bundle.
+   - Reads / writes ISR cache for `renderMode: 'isr'` pages.
+
+### Flags + env vars
+
+| 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. |
+| `VOLTRO_INSPECT=off` | Disable the inspect HTTP endpoints in production. |
+| `VOLTRO_INSPECT_TOKEN=…` | Bearer token guard on the inspect endpoints. |
+
+### Per-request routing logic
+
+For a request to `/foo`:
+
+```text
+1. dist/foo/index.html exists? → serve it.
+2. URL matches a static asset? → serve from disk.
+3. URL matches a registered query?
+     - renderMode 'ssr' → render fresh via SSR bundle.
+     - renderMode 'isr' →
+         - cache HIT (fresh) → serve cached.
+         - cache HIT (stale) + staleWhileRevalidate → serve cached + bg refresh.
+         - cache MISS → render, store, serve.
+     - renderMode 'static' (no pre-render found) → serve SPA shell.
+4. None of the above → 404 via not-found.tsx.
+```
+
+The response includes a `x-voltro-rendered-by` header (`prerender` / `ssr` / `isr`) + cache state.
+
+## ISR cache backends
+
+```bash
+SSR_CACHE=memory voltro start         # default — per-process, doesn't survive restart
+# Postgres-backed cache — needs the PG_* connection env too:
+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.
+
+## 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).
+
+## CDC invalidation
+
+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`.
+
+## Graceful shutdown
+
+`voltro start` handles SIGTERM:
+
+1. Stop accepting new connections.
+2. Wait up to `SHUTDOWN_GRACE_MS` (default 30s) for in-flight requests to finish.
+3. Close active WebSocket connections (the client auto-reconnects).
+4. Exit.
+
+For container orchestrators, set `terminationGracePeriodSeconds: 60` to match.
+
+## Health checks
+
+`voltro start` exposes two unauthenticated probe routes:
+
+- `GET /internal/liveness` → `200 ok` — the process is up at all (restart the pod if it stops answering).
+- `GET /internal/readiness` → `200 ready` once boot completes, `503 not-ready` before (pulls the pod from Service endpoints until ready).
+
+Point the Kubernetes liveness probe at `/internal/liveness` and the readiness probe at `/internal/readiness`.
+
+## Multi-instance + sticky sessions
+
+For WebSocket connections to land on the same backend (required for in-process subscription state):
+
+- Reverse proxy: `lb_policy ip_hash` (Caddy) / `ip_hash` (nginx).
+- Or use `@voltro/plugin-cluster` to share subscription state across instances → any-load-balancer-works.
+
+## Anti-patterns
+
+- **Running `voltro start` against a directory without `dist/`.** It exits 1 with a clear `no built dist found — run voltro build first` (checked against `.framework/dist/index.html` before any heavy work). Run `voltro build` first.
+- **`voltro start` in dev to "test prod".** Use `voltro build && voltro start`. The dev server has different behaviour; serving dev artefacts via start is undefined.
+- **Skipping the SSR bundle build.** Middleware mode is slower (cold-start cost on every render). For production deploys with `renderMode: 'ssr'` pages, build the bundle.
+
+## See also
+
+- [Render modes](/docs/routing/render-modes) — which mode produces which output
+- [Voltro Cloud](/docs/deployment/voltro-cloud) — managed `voltro start` + autoscale (coming soon)
+- [Self-hosting](/docs/deployment/self-hosting) — Docker + reverse proxy patterns
+
+
+
+---
+
+<!-- source: en/cli/migrate.md -->
+## Migrate
+
+_voltro migrate — the idempotent schema apply; voltro db plan/apply for the declarative diff workflow._
+
+`voltro migrate` applies your declared schema (`*.entity.ts` / `*.schema.ts` / `schema.ts`) to the configured database. It's a **flagless, idempotent apply**: it walks the project for table descriptors, emits `CREATE TABLE IF NOT EXISTS` + `CREATE INDEX IF NOT EXISTS`, and runs the DDL in one transaction. Re-running is a no-op.
+
+```bash
+voltro migrate            # apply the discovered schema to the configured store
+voltro migrate apps/api   # explicit app directory (defaults to cwd)
+```
+
+There are no `--plan` / `--dry` / `--reset` / `--advisory-lock` flags on `voltro migrate` — the only argument it reads is an optional path. The diff / plan / apply / drift / squash workflow lives under `voltro db` (see below).
+
+For the deep dive on the schema DSL + day-to-day patterns, see [Database / Migrations](/docs/database/migrations).
+
+## How discovery works
+
+The migrator walks the project root (skipping `node_modules`, `dist`, `.framework`, etc.) for:
+
+- `*.entity.ts` / `*.schema.ts` / `schema.ts` — your table descriptors.
+- Feature files (`*.workflow.tsx`, `*.cron.tsx`, `*.webhook.tsx`) — their presence decides which framework-internal `_voltro_*` tables get created (workflow-run tables, schedule ledgers, etc.). **`_voltro_traces` is the exception — env-gated, not feature-gated:** it's created under `voltro dev` (durable trace history on by default) but NOT under `voltro serve` / `voltro start` (prod default off → set `VOLTRO_TRACING_PERSIST=interesting` to opt in). See [Distributed tracing](/docs/observability/distributed-tracing).
+
+The core `actors` table is injected automatically when you didn't declare your own, and `tenants` is registered when present, so the audit / soft-delete / tenant mixins resolve their FK targets.
+
+## `voltro dev` already auto-migrates
+
+On a SQL-backed store, `voltro dev` AUTO-APPLIES the discovered schema before any handler boots — so a standalone `voltro migrate` is rarely needed in the inner loop. It's the CI / ops-pipeline entry point.
+
+Opt out of the dev auto-migrate when you ship schema through a separate reviewed pipeline:
+
+```bash
+VOLTRO_AUTO_MIGRATE=0 voltro dev .
+```
+
+The boot log then says `auto-migrate: skipped (VOLTRO_AUTO_MIGRATE=0)`, and you run `voltro migrate` (or `voltro db apply`) explicitly.
+
+## Store + dialect selection
+
+The dialect is resolved from `DB_DIALECT` (default `postgres`); the connection comes from `DB_URL` / `DB_PRIMARY_URL`, falling back to the discrete `DB_*` / `PG_*` fields (`DB_HOST` / `PG_HOST`, `DB_PORT` / `PG_PORT`, etc.).
+
+```bash
+DB_DIALECT=postgres DB_URL=postgres://app:app@localhost:5432/app voltro migrate
+```
+
+Migrating against `DB_DIALECT=memory` is rejected — there's nothing to migrate. In dev with the memory store, the in-memory store learns its shape from the schema declaration directly; switch to a SQL dialect (`postgres`, `sqlite`, `mysql`, `mariadb`, `mssql`, `turso`) to test the real migration path.
+
+## The declarative diff workflow — `voltro db`
+
+The plan / apply / drift / squash machinery — diffing the declared schema against a live database, generating reviewable DDL, applying a pre-reviewed plan in production — lives under `voltro db`:
+
+```bash
+voltro db plan                            # diff declared schema vs live, color-coded
+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 --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 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
+```
+
+A separate file-based migration surface (the offline escape hatch) lives alongside it:
+
+```bash
+voltro db migrate                       # apply pending migration files
+voltro db rollback [--to <id>]          # undo migrations
+voltro db status                        # list applied / pending migrations
+voltro db seed                          # run boot-lifecycle seeds against the configured store
+voltro db seed --id <name>              # run one seed by id
+voltro db seed --store memory           # explicit override; default = the app's configured store
+```
+
+`voltro db seed` defaults to the same store the app runs on (`DB_DIALECT` → `STORE` → `app.config.ts` `store:` → `postgres`) — seeding to memory was a silent data-loss footgun, so you opt into it explicitly.
+
+## Production safety
+
+For production deploys:
+
+1. **Always apply schema BEFORE app version bumps.** App N+1 expects schema N+1; app N should still tolerate schema N+1.
+2. **Review the plan first.** `voltro db plan --json` in CI, apply the reviewed plan with `voltro db apply --plan plan.json`.
+3. **Check for drift.** `voltro db drift` flags a live database that diverged from the last applied fingerprint.
+4. **Verify backups before destructive changes.** Restoring is the actually-tested rollback path.
+
+For zero-downtime deploys with breaking schema changes:
+
+- Add new columns / tables → apply first, then deploy.
+- Remove columns → deploy code that doesn't read them, then apply the drop.
+- Rename → add new column + dual-write, deploy, drop old column later.
+
+The framework doesn't enforce these — that's an SRE responsibility. See [Migrations](/docs/database/migrations) for the playbook.
+
+## See also
+
+- [Database / Migrations](/docs/database/migrations) — the schema DSL deep dive
+- [Self-hosting](/docs/deployment/self-hosting) — production migration patterns
+
+
+
+---
+
+<!-- source: en/cli/inspect.md -->
+## Inspect & test
+
+_The HTTP inspect surface, the dashboard, voltro logs / voltro traces, voltro test, voltro e2e — the debugging + harness tools._
+
+When something's wrong, these are the tools. Live inspection of a running app happens over an HTTP surface (and the dashboard that consumes it), not a dedicated CLI verb. The shell-facing debugging commands are `voltro logs` and `voltro traces`; the harness commands are `voltro test` and `voltro e2e`.
+
+## `voltro inspect`
+
+`voltro inspect <subcommand>` is the ergonomic CLI wrapper over the HTTP surface below. It discovers every running api via `~/.voltro/runtime-registry.json`, fans the matching GET/POST out to each, and renders the merged result — no `curl` + `jq` needed.
+
+```bash
+voltro inspect app                              # manifest meta (kind, name, store, …)
+voltro inspect routes                           # web page tree (web apps only)
+voltro inspect rpc                              # procedures + workflow descriptors (api only)
+voltro inspect metrics                          # rolling rpc latency buckets
+voltro inspect cache                            # web data-cache stats (web apps only)
+voltro inspect schedules                        # cron registrations + coordination mode
+voltro inspect aggregates                       # materialised aggregate views
+voltro inspect invoke --tag users.list --input '{}'   # call a procedure over HTTP
+```
+
+Flags on every subcommand: `--process <name>` narrows to one api; `--format pretty|json` (default `pretty`). `invoke` additionally takes `--tag <procedureTag>` and `--input <json>`. With no subcommand it prints the endpoint map + the live processes it can reach.
+
+## The inspect HTTP surface
+
+Every `voltro dev` / `voltro start` instance exposes a read-only introspection surface under `/_voltro/inspect/*`. The [Voltro Dashboard](/docs/observability/dashboard) consumes it to render the route sitemap, RPC list, subscription panel, workflow runs, and metrics. You can also hit the endpoints directly with `curl` (the `voltro inspect` subcommands above are the thin wrapper over exactly these).
+
+```bash
+PORT=4000   # from the app's app.config.ts
+
+curl -s localhost:$PORT/_voltro/inspect/routes  | jq    # web: page tree + render-mode flags
+curl -s localhost:$PORT/_voltro/inspect/rpc     | jq    # api: every query / mutation / action / workflow
+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.
+
+What the surface reads:
+
+- The endpoints serve in-process state from the running instance — no separate daemon.
+- The default target is `http://localhost:<port>` based on the cwd's `app.config.ts`.
+- GET responses are JSON; pipe into `jq`.
+
+### Routes & RPC
+
+```bash
+curl -s localhost:$PORT/_voltro/inspect/routes | jq    # web: page tree + render-mode flags
+curl -s localhost:$PORT/_voltro/inspect/rpc    | jq    # api: query / mutation / action / workflow list
+```
+
+### Subscriptions panel
+
+```bash
+curl -s localhost:$PORT/_voltro/inspect/subscriptions | jq
+```
+
+Shows every active subscriber with:
+
+- Query name + input
+- Subject (who's subscribed)
+- Read set (which tables / rows are tracked)
+- Frame buffer depth (backpressure indicator)
+- Connection age
+
+For "why isn't this updating?" — check the read set. If your mutation writes to a table not in the read set, the subscription doesn't invalidate.
+
+### Workflow runs — `voltro workflows`
+
+`voltro workflows` is the primary surface for inspecting + operating runs:
+
+```bash
+voltro workflows list                          # recent runs
+voltro workflows show <runId>                  # one run's steps + events
+voltro workflows retry <runId>
+voltro workflows cancel <runId>
+voltro workflows suspend <runId>
+voltro workflows resume <runId>
+voltro workflows signal <runId> --name approval        # inject a named signal
+voltro workflows update <runId> --name …
+voltro workflows children <parentExecutionId>
+```
+
+Underneath, workflow state lives in the `_voltro_workflow_runs` + `_voltro_workflow_run_steps` tables and is surfaced live by the dashboard's Workflows panel. The same data is reachable over HTTP:
+
+```bash
+curl -s localhost:$PORT/_voltro/inspect/workflows/runs | jq            # recent runs
+curl -s "localhost:$PORT/_voltro/inspect/workflows/runs/<runId>/steps" | jq   # step-by-step
+curl -s "localhost:$PORT/_voltro/inspect/workflows/runs/<runId>/events" | jq  # the run's event log
+```
+
+Each run row carries ID, name, status (running / succeeded / failed / dead), step count, last completed step, and duration. The per-run action endpoint matches `…/workflows/runs/<runId>/<action>` for `cancel` / `retry` / `suspend` / `resume` / `signal` — the `voltro workflows` subcommands and the dashboard's run-detail buttons both POST to these:
+
+```bash
+curl -s -X POST localhost:$PORT/_voltro/inspect/workflows/runs/<runId>/retry
+curl -s -X POST localhost:$PORT/_voltro/inspect/workflows/runs/<runId>/cancel
+```
+
+For dead-letter triage, filter runs by `status`, or open the dashboard's Workflows tab. See [Workflows / Debugging](/docs/workflows/debugging).
+
+## `voltro logs`
+
+The fastest way to see what a running instance is doing. Buffers the last 2000 server-side log records plus every browser console line the dev console bridge forwarded.
+
+```bash
+voltro logs                                # last 100 from every running process
+voltro logs --tail 50 --level error        # only errors, last 50
+voltro logs --since 30s                    # last 30 seconds
+voltro logs --filter 'notes.summarise'     # message substring
+voltro logs --trace <traceId>              # the WHOLE causal chain for one request
+voltro logs --format json | jq '.records'  # machine-parseable
+```
+
+Run this BEFORE grepping source — the buffer carries the real error, stack, and rpc tag. The full flag set (`--scope`, `--source`, `--process`, `--no-color`, …) is documented in [Traces & logs from the shell](/docs/observability/cli) — the canonical reference for both commands.
+
+## `voltro traces`
+
+Mirror of `voltro logs` for the distributed-trace buffer.
+
+```bash
+voltro traces                              # 20 newest traces, pretty
+voltro traces --errors                     # only traces containing an errored span
+voltro traces --id <traceId>               # one trace, span waterfall
+voltro traces --errors --format json | jq '.traces[]'
+```
+
+Workflow: `voltro traces --errors --format json` to find a failure, then `voltro logs --trace <id> --format json` for the full chain (frontend → api → api, in order). The full flag set (`--min-duration`, `--status`, `--process`, …) lives in [Traces & logs from the shell](/docs/observability/cli).
+
+## `voltro test`
+
+```bash
+voltro test
+voltro test path/to/file.test.ts
+voltro test --filter notes
+```
+
+Runs Vitest with the framework's preset:
+
+- Auto-loaded global setup (test context, mock providers).
+- `STORE=memory` by default for fast isolation.
+- Plays well with `@voltro/testing` helpers (mock stores).
+
+The actual test runner is Vitest; this command is a thin wrapper that injects the framework's config. You can run vitest directly if you prefer:
+
+```bash
+pnpm vitest
+```
+
+## `voltro e2e`
+
+```bash
+voltro e2e            # current dir
+voltro e2e apps/web   # explicit web app directory
+```
+
+`voltro e2e` takes only an optional path to the web app; it parses no other flags. Boots:
+
+1. `voltro dev` for the api app.
+2. `voltro dev` for the web app.
+3. Playwright runs `*.e2e.ts` files.
+4. Tear down: stops the boot processes.
+
+The e2e files use Playwright's API directly:
+
+```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/)
+})
+```
+
+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.
+
+## Securing the inspect surface
+
+The inspect endpoints expose framework internals (queries, subscription state, workflow runs). In production, lock them down with a bearer token:
+
+```bash
+VOLTRO_INSPECT_TOKEN=$(openssl rand -hex 32)
+voltro start apps/api
+```
+
+Then every request must carry the token:
+
+```bash
+curl -s -H "Authorization: Bearer $VOLTRO_INSPECT_TOKEN" \
+  localhost:4000/_voltro/inspect/rpc | jq
+```
+
+Or disable the surface entirely: `VOLTRO_INSPECT=off`. The dashboard then can't introspect the production instance — that's intentional.
+
+## Anti-patterns
+
+- **Inspect surface open in production.** Either disable (`VOLTRO_INSPECT=off`) or lock behind `VOLTRO_INSPECT_TOKEN`. Anyone hitting `/_voltro/inspect/*` can read rpc shapes + live subscription data.
+- **`voltro test` against `STORE=postgres` by default.** Slower + flaky (test isolation harder). Use postgres only for integration tests that NEED it.
+- **Skipping `voltro e2e` because "it's slow".** It catches integration bugs that unit tests miss. Run it in CI on every PR; locally for changes that touch queries.
+
+## See also
+
+- [Workflows / Debugging](/docs/workflows/debugging) — the dashboard's workflow panel
+- [Self-hosting](/docs/deployment/self-hosting) — production observability setup
+
+
+
+---
+
+<!-- source: en/cli/data.md -->
+## Data (export / import / backup / restore)
+
+_voltro data — portable, resumable export/import of your app's data + assets (typed-NDJSON, content-addressed blobs), plus native backup/restore via the vendor tools._
+
+`voltro data` moves your app's data and assets in and out. It has **two families**, because backup and portability are different jobs with different right answers:
+
+- **Logical** — `export` / `import`: a portable, resumable, dialect-agnostic bundle. Use it for data takeout (GDPR), seeding staging from prod, or migrating across SQL dialects.
+- **Native** — `backup` / `restore`: orchestrates the vendor tools (`pg_dump`, `mysqldump`, …) for a lossless, point-in-time same-dialect backup. Use it for disaster recovery.
+
+Both stream — a table or a blob is never fully held in memory — and both survive interruptions.
+
+## Logical export
+
+```bash
+voltro data export ./backup-2026-07-01
+voltro data export ./out --tenant org_abc            # one tenant + its FK closure
+voltro data export ./out --tables users,posts         # an explicit set
+voltro data export ./out --assets                      # include stored blobs
+voltro data export ./out --compression gzip            # zstd (default) | gzip | none
+voltro data export ./out --consistency snapshot        # point-in-time (see below)
+voltro data export ./out --target api --api-url https://api.example.com --token $SECRET  # export FROM a live instance (in-process)
+voltro data export --target api --api-url https://api.example.com --token $SECRET --bundle-key backups/2026-07-01.vbundle  # instance exports straight to storage (scale)
+```
+
+The output is a **directory bundle**, not a zip — each table is an independent file, so an interrupted run resumes cleanly and per-table compression stays effective (a single zip would fight both). Over `--target api` this same bundle is streamed as one framed `.vbundle` archive (a zero-dependency concatenation, not a zip) and unpacked back into the directory on the other end.
+
+```
+backup-2026-07-01/
+  README.md                  # human summary: date, source host, dialect, scope,
+                             # table/row counts, and a LOUD real-vs-masked banner
+  manifest.json              # format version, source dialect + schema fingerprint,
+                             # per-table column types + row counts + checksums
+  data/
+    users.ndjson.zst         # one typed-encoded row per line, framed-compressed
+    posts.ndjson.zst
+  assets/
+    index.ndjson             # key → sha256 → size → content-type
+    9f86d081…                # blobs, content-addressed by sha256 (auto-deduped)
+  .ledger.json               # resume checkpoint (which tables/assets are done)
+```
+
+`README.md` is a human-readable sidecar written on every export — provenance (when, from which host, which dialect, scope) plus a prominent **data-sensitivity banner**: it says outright whether the bundle holds real (unmasked) data or was masked at the source (and which columns). It's ignored on import (the importer only reads files listed in `manifest.json`) and never contains a connection string or credentials. It rides inside the `.vbundle` archive too.
+
+### Single-file bundles (`.vbundle`) — one artifact, any size
+
+Give the export/import a path ending in **`.vbundle`** and you get (or read) **one self-contained file** instead of a directory — everything (tables + blobs + manifest + README) in a single artifact you can copy A→B:
+
+```bash
+voltro data export ./snapshot.vbundle --assets            # one file, blobs included
+voltro data import ./snapshot.vbundle --assets            # stream it back in
+voltro data inspect ./snapshot.vbundle                    # peek at the metadata WITHOUT extracting
+voltro data unpack ./snapshot.vbundle ./out               # explode a file to a dir to look inside
+```
+
+`voltro data inspect` prints the bundle's `README.md` (date, source host, dialect, scope, table/row counts, and the real-vs-masked banner) — read via an **early-stop peek** that stops after the metadata, so it stays fast even on a 200 GB bundle (add `--json` for the machine-readable `manifest.json`, `--passphrase` for an encrypted bundle). `voltro data unpack` fully extracts a file to a directory (blobs materialised under `assets/`), decrypting with `--passphrase` when needed.
+
+It's built to work at **any size (200 GB+) without needing that much scratch space**. The pipeline **streams end-to-end**: on export, blobs are pulled from object storage straight into the file (nothing staged locally — peak local disk is just the tables); on import, blobs stream straight from the file to the destination's object storage (never unpacked to a temp dir first). The file is a framed archive (`.vbundle`, a zero-dependency streamable format — not a zip, whose central-directory-at-the-end design would force downloading the whole thing before reading entry one). Blobs are named by storage key with a per-blob sha footer, so **integrity is per-entry** and a resumed transfer **skips blobs already present** at the destination.
+
+### Encryption at rest (`--encrypt`)
+
+A `.vbundle` is plaintext by default. For a copy that must be confidential at rest (a backup in a bucket, a file on a laptop/CI, an **unmasked** dump — which contains your `.encrypted()` columns as plaintext), encrypt it:
+
+```bash
+voltro data export ./backup.vbundle --assets --encrypt --passphrase "$BUNDLE_KEY"
+voltro data import ./backup.vbundle --assets --passphrase "$BUNDLE_KEY"
+voltro data unpack ./backup.vbundle ./inspect --passphrase "$BUNDLE_KEY"
+```
+
+- **A dedicated key, NOT the transfer secret.** The passphrase comes from `--passphrase` or `VOLTRO_BUNDLE_KEY` and is independent of `VOLTRO_DATA_TRANSFER_SECRET` (auth ≠ encryption; different instances have different transfer secrets; a local export has none). It's stretched with **scrypt** (salt + params in the file header).
+- **Streaming, authenticated AES-256-GCM.** The bundle is encrypted in chunks (the age/Tink STREAM construction), so it stays streaming + resumable at 200 GB, and it's **tamper- and truncation-evident**: a wrong passphrase, a flipped byte, or a dropped final chunk all fail decryption loudly — never a silent partial import.
+- **Complementary to masking.** Masking makes the *data* safe for a lower environment (strips PII); encryption makes the *artifact* confidential. A DR backup wants encryption (full real data); a prod→dev copy wants masking (and can add encryption too).
+
+### Why NDJSON, and why it's exact
+
+Rows are written as newline-delimited JSON — streamable, resumable by line, and human-inspectable. A naïve `JSON.stringify` would corrupt data, so a **typed codec** (driven by the column types in the manifest) handles the values JSON can't:
+
+- `bigint` → preserved exactly (never truncated to a float)
+- `NaN` / `Infinity` → preserved (JSON would turn them into `null`)
+- `bytes` → base64; `timestamp`/`date` → ISO-8601 → `Date` on import
+- `json` / `array` / `vector` → structured, verbatim
+
+### Scope
+
+| Flag | Selects |
+|---|---|
+| *(none)* | Every table (the default). |
+| `--tenant <id>` | Every `tenant()`-scoped table filtered to that tenant, **plus** the FK closure in BOTH directions: (1) the transitive **FK-parent** closure of those rows — closure-pulled shared tables (a global `users` / reference table) are **row-subset to the ids the tenant's rows actually reference**, never exported in full; and (2) the **child** closure — rows that *reference* the tenant's rows (the comments on the tenant's projects) come along too, each scoped to the ids that actually point into the tenant set. The child walk is anchored on the `tenant()` tables, so a row that references **only a shared parent** (a global `users` another tenant also references) is **not** pulled — that would be a cross-tenant leak. A `--tenant` bundle therefore carries the tenant's parents AND children and **no other tenant's rows** — that's what makes it safe as a GDPR / per-tenant takeout. |
+| `--tables a,b` | An explicit set (you own referential integrity; the importer's deferred-FK resolution covers load-order dangles, see below). |
+
+Tenant-scope details:
+
+- **A tenant scope without a tenant id refuses loudly** (`ScopeError`): pass `--tenant <id>` (CLI) or `scope.tenantId` (API/profile). It never falls back to an unfiltered export.
+- **Which tables count as tenant-scoped** comes from the `tenant()` mixin metadata when the CLI / admin endpoint can read the declared schema (authoritative — a table can carry a `tenantId` column *without* being tenant-scoped, e.g. a global `users` table's active-org pointer). Without that metadata the exporter falls back to a documented heuristic: any table with a `tenantId` column.
+- A **cross-tenant reference** (a tenant-A row pointing at a tenant-B row) is never followed — the bundle stays tenant-clean and the reference dangles; importing such a bundle reports it loudly (`DanglingReferenceError`) unless the target already has the row.
+
+### Consistency: `live` vs `snapshot`
+
+- **`live`** (default) — each table is read in short keyset-paginated chunks. Resilient and easy on the database, but the tables are read at slightly different instants (a concurrent write can leave a child whose parent you already passed; the importer's deferred-FK resolution handles the dangling reference — see below).
+- **`snapshot`** — every table is read inside **one transaction pinned to a single MVCC snapshot** (per-dialect isolation prelude), so the whole export is a consistent instant. The trade: that transaction is held open for the export's duration.
+
+## Logical import
+
+```bash
+voltro data import ./backup-2026-07-01
+voltro data import ./out --mode append --on-conflict skip   # insert-only
+voltro data import ./out --mode replace --atomic            # full refresh, all-or-nothing
+voltro data import ./out --target api --api-url https://api.example.com --token $SECRET  # upload to a live instance
+voltro data import --target api --api-url https://api.example.com --token $SECRET --bundle-key backups/2026-07-01.vbundle  # instance pulls from storage (scale)
+voltro data import ./out --assets            # also restore blobs
+voltro data import ./out --no-verify         # skip checksum/row-count verification
+voltro data import ./out --force             # import despite schema drift AND cross-dialect warnings
+```
+
+Import is **integrity-checked** (each table's checksum + row count verified as it decodes; each asset re-hashed against its content address), applies tables in **FK-parent-first order**, and a resumed run skips already-applied tables via the ledger.
+
+### Schema-drift pre-flight
+
+Every bundle records the **schema fingerprint** of the source it was exported from (a stable hash of the schema shape — the same fingerprint prod boot uses to detect drift). Before touching the target, `import` **recomputes the target app's fingerprint the same way** and compares it to the bundle's. On a mismatch it **refuses, fail-closed, before any row lands** — a drifted target (a missing column, a renamed table) would otherwise fail mid-load with a raw database error after some rows already committed:
+
+```text
+✗ schema drift: the target schema (fingerprint d6ba94b0…) differs from the bundle's
+  source (f67942f6…). Refusing before the table phase.
+    items.extra: in the target, not in the bundle
+  Re-export against the current schema, or pass --force to import anyway.
+```
+
+The error names the drift — the tables/columns that moved (down to per-column granularity for the tables the bundle carries) — so you can see exactly what changed. **`--force`** downgrades the refusal to a **loud warning** and proceeds (the operator has accepted that the shapes differ). Over the `--target api` path the same check runs **on the instance** against its declared schema and returns **`409` schema drift** with the fingerprints + diff; `--force` sends `x-import-force: 1` to override.
+
+The pre-flight only runs when the importer has a target schema (the CLI introspects it; the API endpoint uses the instance's declared schema). Importing into a fresh/empty database with no comparable schema simply skips the check.
+
+### Deferred-FK resolution
+
+A row whose write fails on a foreign-key constraint — a forward reference from a `live`-consistency export, a genuine FK **cycle** between tables (which the exporter orders by breaking the closing edge), or an intra-table self-reference to a later row — does **not** fail the import. It is held and resolved after every table has streamed:
+
+1. **Retry to a fixpoint** — forward references resolve once the later tables landed.
+2. **FK-shedding** — rows still stuck are written with their FK-bearing columns set to `NULL` (possible wherever those columns are nullable), which breaks row cycles on every dialect without session-level constraint toggles.
+3. **Patch pass** — shed rows are re-written with the full bundle row, restoring the FK values.
+
+Anything still unresolvable — the parent row exists in **neither the bundle nor the target**, or a `NOT NULL` FK cycle — fails with a typed `DanglingReferenceError` naming each offending table + primary key + the database's own reason. Held rows are the exception set, not the data set: memory is bounded by how many rows dangle at load time.
+
+### Write modes (`--mode`)
+
+| Mode | Behaviour | Use it for | Conflict |
+|---|---|---|---|
+| `upsert` (default) | INSERT-or-UPDATE by primary key | sync / idempotent re-import | overwrites per row |
+| `append` | INSERT only | additive data (event log, new seed) | `--on-conflict skip` (default) or `fail` |
+| `replace` | TRUNCATE the target tables (children-first) then INSERT | full refresh — target ends up **exactly** the bundle | — |
+
+`replace` **refuses a partial bundle** (a subset / tenant / table scope): truncating would delete rows the bundle never carried. Re-export with full scope, or use `upsert`. (`append --on-conflict fail` throws on a duplicate primary key only where the store enforces the constraint — every SQL dialect does; the in-memory dev store overwrites.)
+
+### Importing into a LIVE instance
+
+A plain import connects **straight to the database** (not through the running app), so it is an uncoordinated concurrent writer — readers can see partial state, the reactive layer either storms (CDC dialects) or goes stale (others), and rows race with live writes. So `import` / `restore` **refuse by default when a live instance is detected** (via the local runtime registry, or an explicit `--api-url` probe). Two ways forward:
+
+| Target | How | Guarantees | Use for |
+|---|---|---|---|
+| **direct** (default) | writes straight to the DB | none while live — **guarded**; pass `--allow-live` to override | a stopped target, a replica, a dev/staging DB not serving traffic |
+| **direct + `--atomic`** | wraps truncate+load in ONE transaction | MVCC readers see the import **all-or-nothing** (old until commit, new after) — the live-safe `replace` | replacing a live target's data with no partial-state window |
+| **in-process (`--target api`)** | `voltro data import <dir> --target api --api-url <url> --token <secret>` **uploads** the packed bundle (or, with `--bundle-key`, has the instance **pull it from storage**) to the instance's secret-gated admin endpoint, which imports it **in its own process** through its store | full app pipeline — validation, mixins, **field encryption**, hooks — AND automatic reactivity (in-process writes emit change events, so subscriptions update; no separate resync) | a live merge (incl. PROD) that must honour app invariants |
+
+`--atomic` is the recommended live `replace`: one transaction, so live reads never see a half-loaded table. (It holds a write transaction for the load duration — writes to those tables block, readers don't. A shadow-table rename would shorten that lock window, but for a full replace concurrent writes are discarded on swap anyway, so it isn't the default.)
+
+### The `--target api` data-transfer endpoints (prod-safe)
+
+`--target api` moves data in/out of a **running production** instance without direct DB access. It does NOT reuse the dev data-viewer surface — two dedicated endpoints, `POST /_voltro/admin/export` and `POST /_voltro/admin/import`, both built to be safe on prod and both gated by the **same** secret:
+
+- **Secure by default — no secret, no endpoints.** The instance mounts BOTH routes **only** when a data-transfer secret is configured: `VOLTRO_DATA_TRANSFER_SECRET=<≥16 chars>` (or `serveApi({ dataTransferSecret })`). Unset (or shorter than 16 chars) → the routes return `404`. There is no "on" switch that leaves them open.
+- **Secret gate, constant-time.** Every request must present that secret as a **Bearer token** (`Authorization: Bearer <secret>`), compared in constant time over SHA-256 digests (neither length nor content leaks via timing). The gate is a framework-owned secret **independent of app RBAC** — enabling data transfer can never accidentally ride on a user role. The CLI sends it via `--token` / `VOLTRO_DATA_TRANSFER_SECRET` (it must equal the server's secret). Wrong/absent token → `401`.
+- **One secret, both directions.** The same secret gates export (read) and import (write). If you need to grant export without import (e.g. a backup job that must never overwrite), split it into a per-operation credential deliberately — the default is one credential for the whole surface.
+
+**Import** (`POST /_voltro/admin/import`) applies a bundle **in the instance's own process** through its store — full app pipeline (validation, mixins, **field encryption**, hooks) AND automatic reactivity. Two transports, neither needs a server-readable path:
+  - **upload** (default) — the CLI **packs the bundle and uploads the bytes**; the server unpacks to its own temp dir, imports in-process, cleans up. Buffered → small/moderate bundles.
+  - **storage-pull** (`--bundle-key <key>`) — the CLI sends only `{ "bundleKey": "<key>" }`; the instance **streams that archive from its configured object storage** (S3 / Azure / MinIO / filesystem, resolved from the storage env — `STORAGE_PROVIDER`, `S3_*`, `AZURE_*`, …), no body buffering → arbitrarily large bundles.
+
+**Export** (`POST /_voltro/admin/export`) reads the instance's data **in-process** (so field-decryption + hooks apply) and packs a bundle. ⚠️ This is a **data-exfiltration surface** — it can read *all* prod data — which is exactly why it sits behind the same off-by-default secret. It is also the right place for **source-side masking on a live box**: name a **server-side** profile and its scope/subset/masking apply *before any byte leaves the instance* (fail-closed — see the prod→dev section below). Two transports:
+  - **download** (default) — the response body **is** the packed bundle; the CLI writes it to `<outDir>`. Buffered → small/moderate exports.
+  - **storage-push** (`--bundle-key <key>`) — the instance **exports straight to its object storage** under that key and returns `{ bundleKey, tables, rows }`, no response buffering → the scale path. Then pull it elsewhere (e.g. `import --bundle-key`).
+
+The masking policy for a `--target api` export is named by `--profile <name>` and loaded **on the server** (`data-profiles/<name>.ts`) — version-controlled on the instance, never supplied by the client. No profile → a raw export (the secret-holder is trusted to read prod).
+
+**Assets over the API — full parity with the file path.** With `--assets`, an API export **streams the instance's blobs from its own object storage into the bundle** (single-pass, nothing staged); an API import **streams the bundle's blobs straight to the destination instance's storage** as the archive arrives. So `voltro data export prod.vbundle --assets` (from a running instance via `--target api`) → `voltro data import prod.vbundle --target api --api-url <dev>` moves data *and* blobs at any size. (Uploading a *directory* bundle that has materialised assets over `--target api` transfers data only — pack a single-file `.vbundle` for assets; the CLI warns if you try.)
+
+- **Audited** — every export/import logs the transport, table + row counts, and (export) how many columns were masked.
+
+For a live **merge** (import) that must run app invariants + drive reactivity, this in-process path needs no quiesce/resync — in-process writes are reactive automatically.
+
+### Cross-dialect
+
+You can import a bundle into a **different** dialect than it came from — but only for the framework's portable DSL types. A cross-dialect import runs a **portability lint** first:
+
+- **Blocked** (refused unless `--force`): `raw()` columns (verbatim source-dialect SQL), and `vector` columns targeting a dialect with no vector type.
+- **Warned** (imported, represented differently): `array` / `interval` on a non-postgres target.
+- **Portable everywhere**: text, integer, real, boolean, timestamp, date, json, bytes, reference, enum, id.
+
+The lint **refuses loudly** rather than silently coercing — a blocked import tells you exactly which columns are the problem.
+
+## Reliability: chunking, retry, resume
+
+A production export can run for hours over millions of rows and gigabytes of blobs. It is built so a dropped connection, a pool blip, or an outright crash never means starting over — and so a huge table never blows up memory or knocks the source database over.
+
+### Chunking — flat memory, gentle on the DB
+
+Every table is read with a **keyset cursor**, not `OFFSET`: `WHERE pk > :last ORDER BY pk LIMIT n` (default **1000 rows/page**, tune with `chunkSize`). Consequences:
+
+- **Flat memory** — one bounded page is in memory at a time, regardless of table size (a 20 M-row table streams in 1000-row pages).
+- **O(1) per page** on the pk index — `OFFSET n` re-scans and skips `n` rows every page (O(n²) over a full walk); keyset reads each row exactly once.
+- **Backpressure** — a page is fetched only when the sink (encode → compress → disk) is ready to take it, so a slow disk throttles the DB reads instead of overrunning memory or hammering the server.
+
+`live` consistency keeps each read short (no long-held transaction → vacuum-friendly); `snapshot` trades that for one pinned transaction held for the export's duration (see above).
+
+### Retry — a blip doesn't kill the run
+
+Each page read is retried on a transient failure (dropped connection, pooled-backend hiccup) with **exponential backoff + jitter**, up to **5 attempts** by default (`retryTimes`). The retry is **per page**, and the keyset cursor is preserved — so a reconnected page resumes at exactly the row it stopped on, never re-emitting or skipping. A genuinely-broken read still surfaces after the attempts are exhausted rather than hanging.
+
+### Resume — re-run and it continues
+
+Both export and import checkpoint into a small **`.ledger.json`** and can be re-run to continue where they stopped:
+
+- **Export** writes each table with an atomic temp-file + rename, and records the table (and each asset) in the ledger only once it's fully written. A crash mid-table leaves **no half-written file** (the temp is discarded); re-running skips the completed tables/assets and redoes only the unfinished one. Assets are **content-addressed**, so resume is per-asset — a blob whose hash is already in the bundle is skipped.
+- **Import** keeps its own ledger (`.import.ledger.json`) and skips already-applied tables on a re-run. Correctness never depends on the ledger, though: every row is **upserted by primary key**, so redoing an in-flight table is always safe, and each table's checksum + row count and each asset's hash are **verified** as they load — a truncated or corrupted bundle fails loudly instead of importing garbage.
+
+Net: interrupt an export or import at any point — network drop, `Ctrl-C`, OOM-killed pod — and re-running the same command finishes the job without duplicating work or corrupting the target.
+
+### Progress & observability
+
+A multi-hour job is not a black box. Both pipelines signal per **table** — never per row, so the reporting never slows the hot path:
+
+- **`voltro data export|import` prints a line per finished table** — `export [7/23] users · 1.2k rows` — so you watch the run progress instead of staring at a silent terminal. A ledger-resumed table prints once with its recorded count.
+- **Programmatically**, `runExport` / `runImport` take an optional **`onProgress`** callback. It fires a `start` then a `done` event per table, in FK-parent-first order, carrying the table name, its 0-based `index`, the `tableCount`, `rowsDone`, and `total` (the table's row count when known ahead of time — import reads it from the manifest; a live export learns it only once the table drains). A throwing progress renderer never aborts the job.
+- **Traces + metrics are always on**, no wiring. Each table runs inside an `Effect.withSpan('data-transfer.export.table' | 'data-transfer.import.table')` (attributes `table` / `index` / `phase`), so if the app has tracing enabled the export/import shows per-table phase timing in the trace. Two metrics record throughput: `voltro_data_transfer_rows` (counter, tagged by `phase` + `table`) and `voltro_data_transfer_table_seconds` (histogram, tagged by `phase`).
+
+```ts
+import { runImport, type ProgressEvent } from '@voltro/data-transfer'
+
+yield* runImport({
+  store: target,
+  bundleDir: './backup',
+  onProgress: (e: ProgressEvent) => {
+    if (e.event === 'done') console.log(`[${e.index + 1}/${e.tableCount}] ${e.table}: ${e.rowsDone} rows`)
+  },
+})
+```
+
+### Typed errors — CLI-catchable AND rpc-declarable
+
+Every pipeline failure is a **tagged error**, caught by tag with `Effect.catchTag(...)`. The errors that appear on the `runExport` / `runImport` error channels — the **wire errors**, and therefore exactly what the `--target api` admin endpoints surface — are `Schema.TaggedError`, so a handler can declare them on an rpc procedure's `error:` schema and the rpc encoder marshals them across the wire round-trip-safely (no hand-rolled JSON per tag):
+
+`BundleError`, `CodecError`, `IntegrityError`, `CrossDialectError`, `ImportModeError`, `DanglingReferenceError`, `SchemaDriftError`, `MaskingError`, `ScopeError`.
+
+The two internal errors — `NativeToolError` (native `backup`/`restore`) and `CompressionError` (folded into `BundleError` by the pipelines) — never cross the wire, so they stay plain `Data.TaggedError`: still catchable by tag, just no Schema surface.
+
+```ts
+import { Effect } from 'effect'
+import { runImport, type SchemaDriftError } from '@voltro/data-transfer'
+
+yield* runImport({ store: target, bundleDir: './backup', targetSnapshot }).pipe(
+  Effect.catchTag('SchemaDriftError', (e: SchemaDriftError) => Effect.log(`refusing: schema drifted — ${e.diff.join('; ')}`)),
+)
+```
+
+## Native backup / restore
+
+```bash
+voltro data backup ./backups/2026-07-01     # pg_dump --format=custom / mysqldump --single-transaction / …
+voltro data restore ./backups/2026-07-01    # pg_restore / mysql / …
+```
+
+These shell out to the vendor tools resolved from your `DB_DIALECT` + connection env. They produce a dialect-native artifact (`db.dump`, `db.sql`, `db.sqlite`, `db.bacpac`) that is lossless and point-in-time consistent for **same-dialect** restore — the right tool for disaster recovery. Secrets are passed via the tools' environment variables (`PGPASSWORD`, `MYSQL_PWD`), never on the command line, where the tool supports it. The named tool must be installed and on `PATH`.
+
+## Masking (prod → dev/stage safely)
+
+Cloning prod into a lower environment must not carry real user data. `voltro data export`
+does this with **masking**: PII is replaced by realistic, referentially-consistent fakes
+**at the source** — before a row is ever written — so real values never reach the bundle,
+transit, or a developer's machine.
+
+```bash
+voltro data export ./out --profile dev
+```
+
+Masking is driven by **two layers**:
+
+1. **Classification in the schema** — [`.sensitive(class)` / `.safe()`](/docs/database/sensitivity)
+   on each column. This says *what kind* of data a column holds. It lives in the schema
+   because the data's meaning is a property of the schema, not of one export.
+2. **A per-environment masking POLICY** — how each class/column is transformed for *this*
+   target. It lives in a profile so a target environment's whole recipe is one reviewable,
+   version-controlled file.
+
+```ts
+// data-profiles/dev.profile.ts
+import { defineDataProfile } from '@voltro/data-transfer'
+export default defineDataProfile({
+  subset: { seeds: { users: undefined } },
+  masking: {
+    seed: process.env.MASK_SEED!,
+    // classes override the built-in defaults; columns override per-column
+    classes: { freeText: 'redact' },
+    columns: { '_voltro_mail_outbox.to': { fake: 'email' } },
+    onUnclassified: 'error', // fail-closed (default)
+  },
+  consistency: 'snapshot',
+  assets: true,
+})
+```
+
+### Deterministic + seed-keyed
+
+Every transform is deterministic and keyed on a secret **`seed`**:
+
+- **Same input → same fake, everywhere.** One email becomes the SAME fake in every table
+  it appears in, so joins survive; and it stays stable across re-runs, so dev data doesn't
+  churn. Keeping the seed stable is **pseudonymisation**.
+- **Rotate or discard the seed → the mapping is irrecoverable.** That makes the result
+  **anonymisation**.
+
+`seed` is REQUIRED — masking without one is a bug (pass it from the environment, never
+commit it). Transforms are also **format-preserving** (a fake email is a valid email) and
+**null-preserving** (a null stays null — nullability holds).
+
+### Actions
+
+An action is what a column's value becomes. Set them per class (`classes`) or per column
+(`columns`, which wins):
+
+| Action | Effect |
+|---|---|
+| `keep` | copy verbatim |
+| `null` | set to `null` |
+| `redact` | fixed placeholder (`[redacted]` for text, `null` otherwise) |
+| `hash` | deterministic opaque hex (stable, non-reversible without the seed) |
+| `dateShift` | shift a date by a seed-derived offset (relative intervals + ordering preserved) |
+| `{ fake: '<class>' }` | a format-preserving fake of that class |
+| `{ custom: (input) => … }` | your own transform (`input` = `{ value, table, column, columnType, seed }`) |
+
+### Class → action defaults
+
+A minimal policy is just a `seed` — every known class has a default action:
+
+| Class | Default action |
+|---|---|
+| `email` `fullName` `firstName` `lastName` `username` `phone` `address` `company` `url` `ip` `creditCard` | `{ fake: '<class>' }` |
+| `date` | `dateShift` |
+| `secret` | `null` |
+| `freeText` | `redact` |
+
+A custom class with no entry in `classes` falls back to `redact`. Resolution order for any
+column is: **`columns[table.column]` → the class's action (`classes` → built-in default) →
+`.safe()` keeps → PK/FK keeps → `onUnclassified`.**
+
+## Fail-closed
+
+Masking is **fail-closed**. A column that is neither `.sensitive()` nor `.safe()` (and isn't
+a PK/FK, and has no `columns` override) **refuses the export** and is named in the error —
+so a newly-added column can never silently leak PII to dev. Classify it, or override it in
+the policy.
+
+The opt-out is `onUnclassified: 'keep'` (or `'null'`), which makes masking **fail-open** for
+unclassified columns. Discouraged — it defeats the guarantee; prefer classifying the column.
+See [why fail-closed](/docs/database/sensitivity#why-fail-closed).
+
+## `--dry-run` — preview without writing
+
+Preview a masking export **without writing a bundle** — the trust surface before real data
+moves. It reads a small sample per table and reports, per masked column, the before→after;
+a **leak scan** that warns when a KEPT column still LOOKS like PII (catches a
+misclassification — a `.safe()` on something that isn't); and the fail-closed list.
+
+```bash
+voltro data export ./out --profile dev --dry-run
+```
+
+```text
+  users
+    email  [fake:email]  "ada@corp.com" → "grace.hopper1847@example.com"
+    name   [fake:fullName]  "Ada Byron" → "Linus Torvalds"
+    ssn    [null]  "078-05-1120" → null
+
+  ⚠ possible leaks in KEPT columns:
+    users.nickname looks like email: "ada@corp.com"
+
+  ✗ unclassified (would BLOCK a real export — add .sensitive()/.safe() or a policy override):
+    users.bio
+
+  ✓ every exported column is classified — safe to run.
+```
+
+Nothing is written. `--dry-run` exits non-zero when the unclassified list is non-empty, so
+it doubles as a CI gate for classification coverage. (It requires a profile with a masking
+policy — there is nothing to preview otherwise.)
+
+## Audit
+
+A masking export records what it changed in the bundle's `manifest.json`, under `masking`:
+
+```json
+"masking": {
+  "transformed": ["users.email", "users.name", "users.ssn"]
+}
+```
+
+`masking.transformed` lists every `table.column` that was pseudonymised/anonymised (i.e.
+every column whose action was not `keep`), so a reviewer can verify the copy was masked as
+intended — without diffing the data. A policy `id` is recorded alongside it when the policy
+sets one.
+
+## Subsetting
+
+`subset` exports a referentially-correct SLICE instead of whole tables. You give **seed
+rows** per table; the exporter adds their **transitive FK-parent closure** — every row the
+seeds (and their parents, recursively) point at — so the slice imports with **no dangling
+references**.
+
+```ts
+subset: {
+  seeds: {
+    users: undefined,                          // every user (no predicate)
+    orders: eq('status', 'open'),              // only open orders (a Predicate)
+  },
+}
+// exports those rows PLUS every parent row they reference (users an order points at, etc.)
+```
+
+A `subset` **replaces** `scope` when both are set — only the seeded tables and their parent
+closure are exported. Contrast the two:
+
+- **`scope`** (`--tenant` / `--tables` / all) selects **tables** (a tenant's rows plus the
+  row-subset FK parents they reference, or an explicit table set). Use it to move a tenant
+  or named tables.
+- **`subset`** selects **specific rows** and pulls in exactly the parents they need. Use it
+  to carve a small, self-consistent slice ("these 1000 users and everything they reference").
+
+**Child closure.** By default the closure follows **parents only** — a seeded user brings the
+org it belongs to, but not that user's posts. Set `children` to also pull in the rows that
+**reference** the seeded set, each scoped to the ids that actually point into it (never a whole
+child table). The child rows' own parents fold back through the parent closure, so the slice
+stays referentially complete:
+
+```ts
+subset: {
+  seeds:    { orgs: eq('id', 'org_abc') },
+  children: { roots: ['orgs'] },  // pull the org's users → their posts → those posts' comments
+}
+```
+
+`children.roots` **anchors** the walk: a child comes along only when it references a `roots`
+row (or a child already pulled in this walk), so the walk stays tight — a row that references
+only a *shared* parent outside the anchor is not dragged in. (This is exactly what keeps a
+`--tenant` export tenant-tight: its child walk is anchored on the `tenant()` tables.) Use
+`children: true` for an unanchored org-slice takeout where there is no tenant boundary to
+respect.
+
+Subsetting reads the selected rows into memory to collect id sets — it's built for small
+slices, not for halving a huge table (use `scope`/`--tenant` for that).
+
+## Profiles
+
+A **profile** bundles a target environment's whole recipe — scope/subset, masking,
+consistency, compression, assets — into one default-exported object, so
+`voltro data export --profile dev` is a single, reviewable, version-controlled description
+of *how prod becomes dev*.
+
+```ts
+import { defineDataProfile } from '@voltro/data-transfer'
+
+export default defineDataProfile({
+  scope:       { kind: 'all' },        // or omit and use --tenant/--tables
+  subset:      { seeds: { users: undefined } }, // replaces scope when set
+  masking:     { seed: process.env.MASK_SEED! },
+  consistency: 'snapshot',             // 'live' | 'snapshot'
+  compression: 'zstd',                 // 'zstd' | 'gzip' | 'none'
+  assets:      true,                   // include stored blobs
+})
+```
+
+`--profile <name>` resolves, in order: `./<name>`, `./<name>.profile.ts`,
+`./data-profiles/<name>.ts`, `./data-profiles/<name>.profile.ts`. So `--profile dev` finds
+`./dev.profile.ts` or `./data-profiles/dev.ts`. The module's **default export** must be the
+profile (use `defineDataProfile` for full type-checking).
+
+**CLI flags override profile values.** `--assets`, `--compression`, `--consistency`,
+`--tenant`, `--tables` all win over what the profile sets — so a profile is the default and a
+flag is the one-off override.
+
+## Which do I use?
+
+| Goal | Command |
+|---|---|
+| Disaster recovery / scheduled backups | `voltro data backup` (native) |
+| Clone prod → staging (masked, no real PII) | `voltro data export --profile <env>` (masking + subset) |
+| Preview a masked export before running it | `voltro data export --profile <env> --dry-run` |
+| Clone prod → staging (same dialect, unmasked) | `voltro data export` then `import` (or native backup/restore) |
+| GDPR / per-tenant takeout | `voltro data export --tenant <id> --assets` |
+| A small self-consistent slice of the data | `voltro data export --profile <env>` with a `subset` |
+| Move Postgres → MySQL | `voltro data export` then `import` (cross-dialect lint applies) |
+
+
+
+---
+
+<!-- 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._
+
+`@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**.
+
+## Setup
+
+Two environment variables, both optional:
+
+| 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. |
+
+### Claude Code
+
+```bash
+claude mcp add voltro -- npx -y @voltro/mcp
+# an api on a non-default port:
+claude mcp add voltro --env VOLTRO_INSPECT_URL=http://localhost:4001 -- npx -y @voltro/mcp
+```
+
+### Cursor / generic MCP config
+
+```json
+{
+  "mcpServers": {
+    "voltro": {
+      "command": "npx",
+      "args": ["-y", "@voltro/mcp"],
+      "env": { "VOLTRO_INSPECT_URL": "http://localhost:4000" }
+    }
+  }
+}
+```
+
+## The tools
+
+| Tool | Returns |
+|---|---|
+| `voltro_list_procedures` | Every rpc procedure with its kind; `[public-rest]` / `[agent-tool]` markers for projected descriptors. |
+| `voltro_get_procedure` | One procedure's kind, input/output JSON Schema, source file(s), table targets, and projections. |
+| `voltro_search_procedures` | Procedures whose tag contains a substring. |
+| `voltro_list_tables` | The app's USER tables (column count, reactivity). |
+| `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. |
+
+## The resources
+
+The server also exposes the manifest as MCP **resources** — stable, addressable `voltro://` URIs an agent reads. `resources/list` enumerates them (fresh from the manifest each call); `resources/read` returns the metadata as JSON.
+
+| URI | Contents |
+|---|---|
+| `voltro://manifest` | The whole capability manifest as JSON. |
+| `voltro://procedure/<tag>` | One procedure's kind, input/output JSON Schema, source, and table targets. |
+| `voltro://table/<name>` | One table's full column list. |
+
+## The prompts
+
+Reusable MCP **prompt templates** that render against the _live_ manifest, so the returned messages carry the app's real schema rather than a generic stub. `prompts/list` advertises them; `prompts/get` renders one.
+
+| Prompt | Arguments | Renders |
+|---|---|---|
+| `scaffold_procedure` | `kind`, `purpose` | A brief to draft a new query/mutation/action, listing the app's real tables + sibling procedures of that kind. |
+| `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. |
+
+## 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:
+
+- **POST** a JSON-RPC message → a JSON response, or an SSE stream (`text/event-stream`) carrying the response(s) when the client's `Accept` allows it. An `initialize` POST mints a session and returns it in the `Mcp-Session-Id` header; every later POST must echo that header.
+- **GET** (with `Accept: text/event-stream`) → opens the server→client SSE channel.
+- **DELETE** → ends the session.
+
+```bash
+VOLTRO_MCP_HTTP_PORT=4100 VOLTRO_INSPECT_URL=http://localhost:4000 npx -y @voltro/mcp voltro-mcp-http
+```
+
+| Var | Default | Notes |
+|---|---|---|
+| `VOLTRO_MCP_HTTP_PORT` | `4100` | Listen port. |
+| `VOLTRO_MCP_HTTP_PATH` | `/mcp` | The single MCP endpoint path. |
+
+## Freshness + failure behavior
+
+The manifest is read through a TTL-cached source (~10 seconds): a procedure you add during a `voltro dev` session shows up on the next tool call — no MCP-server restart. When the api is unreachable or the token is wrong, the tool output says so (`(no procedures — manifest unavailable: …)`) and the bin logs the reason to stderr at boot, instead of silently presenting an empty app.
+
+## 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`.