@voltro/cli 0.1.0

package/templates/agent-docs/deployment.md

@@ -0,0 +1,999 @@
+# Deployment
+
+> Voltro Cloud (coming soon) — the managed runtime for your Voltro project. Today the Free control plane registers + observes your self-hosted apps.
+
+
+
+---
+
+<!-- source: en/deployment/voltro-cloud.md -->
+## Voltro Cloud
+
+_Voltro Cloud (coming soon) — the managed runtime for your Voltro project. Today the Free control plane registers + observes your self-hosted apps._
+
+Voltro Cloud is the managed tier of the same open-core runtime you run locally. It's not a fork — `voltro start` is what powers your production instances, just with custom domains, multi-region routing, provisioned Postgres / Redis / object storage, and a control plane that handles deploys.
+
+**Status:** managed cloud **deploy + provisioning is coming soon** and is not yet available. What's live today is the **Free control plane**: sign up and use it to **register and observe your self-hosted apps** (hosted observability, quotas, governance, teams). The managed-tier features described below are the planned shape of Voltro Cloud — see the per-section notes.
+
+## When to use Cloud vs self-host
+
+| | Cloud (coming soon) | Self-host (today) |
+|---|---|---|
+| Managed Postgres + Redis + pgvector | ✓ | You provision |
+| Multi-region + edge routing | ✓ | You set up Caddy / Cloudflare / your CDN |
+| Custom domains + automatic SSL | ✓ | You manage certs |
+| AI provider gateway (key rotation, fallback) | ✓ | You wire `AI_PROVIDER` directly |
+| Per-tenant vanity domains | ✓ (Enterprise) | Possible but you build the routing |
+| Observability (logs, traces, metrics) | ✓ | You wire OpenTelemetry to your sink |
+| Audit log retention | ≥ 90 days | Whatever you configure |
+| You own the data | ✓ — export anytime | ✓ |
+| You own the source code | ✓ | ✓ |
+
+Pre-release: the **Free tier is live** — sign up (passwordless, an email one-time code) and use the control plane to register + observe your **self-hosted** apps. Managed cloud **deploy + provisioning is coming soon** (`voltro cloud deploy` prints `control-plane deploy pipeline pending — not yet available` until it ships); paid tiers open with it at launch.
+
+## The `voltro cloud` client
+
+The control-plane client is `voltro cloud`, not a top-level `voltro deploy`. It authenticates against the control plane (base url via `VOLTRO_CLOUD_URL`) and manages projects + env vars:
+
+```bash
+voltro cloud login [--token <t>]          # store a session token in ~/.voltro/credentials.json
+voltro cloud whoami                       # the current account
+voltro cloud projects                     # list your projects
+voltro cloud env list [--project P]       # list a project's env vars
+voltro cloud env set <KEY> <VALUE> [--project P]
+voltro cloud env pull [--project P]       # write .env.cloud from the project's env
+voltro cloud import                       # scaffold voltro.cloud.toml from app.config.ts
+```
+
+### Scaffolding the deploy config — `voltro cloud import`
+
+`voltro cloud import` reads the app's `app.config.ts` (name + type) and writes a `voltro.cloud.toml` next to it. It refuses to overwrite an existing file. The generated shape:
+
+```toml
+# voltro.cloud.toml — generated by `voltro cloud import`.
+# Describes how this app deploys to the framework cloud control-plane.
+
+[project]
+name = "acme"
+type = "api"
+
+[deploy]
+# Target region + replica count. Tune before `voltro cloud deploy`.
+region = "auto"
+replicas = 1
+
+[env]
+# Project env-var names resolved from the control-plane at deploy time.
+# Use `voltro cloud env set <KEY> <VALUE>` to populate them.
+```
+
+### Deploy is pending
+
+`voltro cloud deploy` exists but the control-plane deploy pipeline is not yet available — running it prints `control-plane deploy pipeline pending — not yet available`. Build, upload, migrate, traffic-shifting, and one-click rollback are the planned shape of that pipeline; until it lands, use the `voltro cloud` env + project commands above to prepare a project.
+
+## Environments
+
+Per-project environments (`preview` / `staging` / `production`), each with its own env vars + DB + storage bucket, are part of the planned control-plane surface. Manage env vars today with `voltro cloud env list/set/pull`.
+
+## Custom domains
+
+*Coming soon with managed cloud hosting — not yet available.* When it ships, you'll add a domain in the Cloud UI and the platform handles:
+
+- DNS verification (TXT record)
+- ACME-issued SSL (Let's Encrypt or Google Trust Services)
+- Auto-renewal
+- Per-tenant vanity domains (Enterprise) — `tenant1.your-product.com` routes to the right tenant scope automatically
+
+## Observability
+
+*Available today for your registered self-hosted apps* (this is the live Free-tier control plane). OpenTelemetry-native:
+
+- **Logs** flow to the project's log stream (search + filter in-UI; export to Datadog / Loki / etc.)
+- **Traces** for every mutation, query, workflow, agent run
+- **Metrics** for request rates, error rates, p50/p95/p99 latencies, AI token spend per tenant
+
+## Provisioning
+
+*Coming soon with managed cloud hosting — not yet available.* When it ships, Cloud will provision managed Postgres, Redis, R2, Resend, etc. on your behalf. You'll also be able to BYO (point at your own Neon, Upstash, etc. via env vars) — billing for those goes through your account with the provider. Today you provision these yourself and self-host.
+
+See the [Cloud Premium Matrix](https://github.com/voltro-cloud/cloud-public/blob/main/PREMIUM.md) for the full feature breakdown.
+
+## Migration from self-hosted to Cloud
+
+*Deploying onto Cloud is coming soon — not yet available.* You can prepare a project today (scaffold the config, populate env), but there is no managed destination to deploy to yet.
+
+```bash
+voltro cloud import   # scaffold voltro.cloud.toml from the app's app.config.ts
+```
+
+`voltro cloud import` reads the app's `app.config.ts` and writes a `voltro.cloud.toml` (project name + type + a deploy/env skeleton). Populate the project env with `voltro cloud env set`. When managed hosting ships, your local Postgres data won't be migrated for you — you'll use `pg_dump` + `pg_restore` against the target database directly.
+
+
+
+---
+
+<!-- source: en/deployment/self-hosting.md -->
+## Self-hosting
+
+_Run Voltro on your own infra — Docker compose, env vars, reverse proxy, scaling._
+
+Voltro is open-core. The runtime that powers Voltro Cloud is the same runtime you run locally with `voltro start`. Self-hosting is fully supported — no separate "lite" runtime, no feature gates around the core API.
+
+## The shape of a self-hosted deploy
+
+You need:
+
+1. **Node.js 24+** to run the api + web processes.
+2. **Postgres 16+** with `pgvector` extension (for AI / search) and `wal_level=logical` (for subscriptions). Managed Postgres at Neon, Supabase, RDS, or your own server all work.
+3. **A reverse proxy** (Caddy / nginx / Cloudflare). Terminates TLS, routes paths, fronts the framework's processes.
+4. **(Optional) Redis** for cross-instance subscription fan-out when you scale beyond one api process.
+5. **(Optional) Object storage** (R2, S3, GCS) — required if you use `@voltro/plugin-storage`.
+
+Voltro doesn't require Kubernetes or any orchestrator. A single Docker host + Caddy is enough for ≥99% of deployments.
+
+## The supported path: `voltro baseline`
+
+You don't have to hand-write any of the deploy plumbing below — the CLI ships baselines that generate it. Pick one at project creation or switch later:
+
+```bash
+voltro create-project acme --api=api-backend --web=frontend-blank --baseline=compose
+# or, on an existing project:
+voltro baseline set compose       # generates docker/{api,web}.Dockerfile + docker-compose*.yml
+voltro baseline set helm          # generates charts/voltro-app/ for Kubernetes
+voltro baseline status            # which baseline is active
+```
+
+- `bare` — `.env.example` + a sample systemd unit. You bring your own Postgres + deploy.
+- `compose` — `docker/{api,web}.Dockerfile`, `docker-compose.yml` (postgres infra), `docker-compose.dev.yml` (HMR), `docker-compose.prod.yml` (built images).
+- `helm` — a `charts/voltro-app/` chart with per-env values + Deployment / Service / Ingress / Postgres StatefulSet.
+
+The hand-rolled compose + Caddyfile below are a reference for *what `voltro baseline set compose` generates* — read them to understand the shape, but prefer the generated files.
+
+## Docker compose
+
+```yaml
+# docker-compose.yml
+services:
+  postgres:
+    image: pgvector/pgvector:pg16
+    environment:
+      POSTGRES_PASSWORD: change-me
+      POSTGRES_DB: voltro
+    command: postgres -c wal_level=logical -c max_replication_slots=10
+    volumes:
+      - pg-data:/var/lib/postgresql/data
+
+  api:
+    build: ./apps/api
+    environment:
+      DB_DIALECT: postgres
+      DB_URL: postgres://postgres:change-me@postgres:5432/voltro
+      VOLTRO_SESSION_SECRET: ${VOLTRO_SESSION_SECRET}
+      AI_PROVIDER: anthropic
+      AI_API_KEY: ${ANTHROPIC_API_KEY}
+    depends_on: [postgres]
+
+  web:
+    build: ./apps/web
+    environment:
+      PORT: 5173
+    depends_on: [api]
+
+  caddy:
+    image: caddy:2
+    ports: ["80:80", "443:443"]
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile
+
+volumes:
+  pg-data:
+```
+
+## Caddyfile
+
+```caddyfile
+your-product.com {
+  # The api serves the rpc WebSocket upgrade at /ws, the one-shot HTTP rpc
+  # at /rpc, and introspection under /_voltro/*. Everything else is the web app.
+  reverse_proxy /ws         api:4000
+  reverse_proxy /rpc        api:4000
+  reverse_proxy /_voltro/*  api:4000
+  reverse_proxy *           web:5173
+}
+```
+
+Single-origin deployment — no CORS, `SameSite=strict` cookies, no `Domain` attribute needed. The cleanest production layout. (Adjust the paths if your app mounts the rpc transport on a custom path — see below.)
+
+### Custom WebSocket path — `transport.wsPath`
+
+By default the browser connects the realtime rpc WebSocket to a same-origin path derived per api (`/ws/<name>`), and the api serves it at `/ws`. When your edge only allows WebSocket **upgrades** on a *specific* path (a WAF / CDN rule), or you must match a path a **previous stack** used, set `transport.wsPath` on the **api** app. The api then serves the socket there AND the web client **auto-derives the same path** — declare it once, no web-side config, no drift:
+
+```ts
+// apps/api/app.config.ts
+export default {
+  type: 'api' as const,
+  name: 'api',
+  store: 'postgres' as const,
+  // Serve the rpc WebSocket on a fixed absolute path. The web app that
+  // consumes this api reads this value and connects here — nothing to set on
+  // the web side.
+  transport: { wsPath: '/api/sync' },
+}
+```
+
+Then route that path to the api in your proxy — everything else is unchanged:
+
+```caddyfile
+your-product.com {
+  reverse_proxy /api/sync   api:4000   # the custom WS path (served by the api)
+  reverse_proxy /rpc        api:4000
+  reverse_proxy /_voltro/*  api:4000
+  reverse_proxy *           web:5173
+}
+```
+
+The path is **relative** in the bundle, so the host resolves at runtime — **one built image works across every environment**; only the path is fixed. Keep the socket **same-origin** with the web app: the session cookie rides the WS upgrade, and a cross-origin socket wouldn't carry it (every subscription would run anonymous). For an api on a genuinely separate origin, use the api spec's absolute `url` on the web side plus a token-based `headers` resolver instead of a cookie. (One custom `wsPath` per origin — the framework fails the build if two same-origin apis would collide on it.)
+
+### `allowedHosts` — fronting the web app on a real domain
+
+Vite 8's DNS-rebind guard returns HTTP **403** for any request whose `Host`
+header isn't an IP or `localhost`. So a Voltro web app served through a
+reverse proxy / ingress on a real domain (e.g. `app.dev.example.com`) 403s
+in the browser until that host is allow-listed. Add the new optional field on
+the **web** app's `app.config.ts`:
+
+```ts
+// apps/web/app.config.ts
+export default {
+  type: 'web' as const,
+  name: 'web',
+  // string[] | true — default: unset = Vite default (only IPs + localhost).
+  allowedHosts: ['app.dev.example.com'],   // a leading-dot entry like
+                                           // '.example.com' matches all subdomains
+  // allowedHosts: true,                   // disable the check entirely —
+                                           // only behind a trusted proxy, since
+                                           // it removes the rebind protection
+}
+```
+
+This applies to the dev / Vite-served surface — a production `voltro start`
+SSR/SPA host fronted by the proxy. If you see a 403 in the browser but the
+proxy logs show the request reaching the app, this is almost always the
+cause.
+
+## Env vars
+
+| Var | Required | Notes |
+|---|---|---|
+| `DB_DIALECT` | for SQL stores | `postgres` (default) / `mysql` / `mariadb` / `mssql` / `sqlite` / `turso` |
+| `DB_URL` | for SQL stores | Database connection string (falls back to `DB_PRIMARY_URL`; or the discrete `DB_*` / `PG_*` fields) |
+| `VOLTRO_SESSION_SECRET` | when using `@voltro/plugin-auth` | 32+ random bytes from a real CSPRNG — the session-cookie signing key (`voltro secret generate session`) |
+| `VOLTRO_DATA_TRANSFER_SECRET` | to enable `--target api` export/import | Gates `POST /_voltro/admin/{export,import}`; ≥16 chars or the routes stay unmounted (`voltro secret generate data-transfer`) |
+| `VOLTRO_BUNDLE_KEY` | for encrypted `.vbundle` exports | Passphrase for at-rest bundle encryption — a DEDICATED key, not the transfer secret (`voltro secret generate bundle-key`) |
+| `VOLTRO_FIELD_ENCRYPTION_KEY` | with `governancePlugin({ fieldEncryption: true })` | Key for `.encrypted()` columns; boot fails loudly if missing while such columns exist (`voltro secret generate field-encryption`) |
+| `VOLTRO_STORAGE_SECRET` | optional (`@voltro/plugin-storage`) | Signs private-file grant tokens; falls back to the session secret if unset |
+| `AI_PROVIDER` | when using `@voltro/ai` | `anthropic` / `openai` / `mock` |
+| `AI_API_KEY` | with `AI_PROVIDER` | Provider's API key |
+| `SSR_CACHE` | optional | `memory` (default) or `postgres` (needs `PG_*` set too) for the ISR cache |
+| `PORT` | optional | App's listen port (overrides `app.config.ts.port`) |
+| `VOLTRO_INSPECT` | optional | `off` to disable `_voltro/inspect/*` in prod |
+| `VOLTRO_INSPECT_TOKEN` | recommended | Bearer token guard on inspect endpoints |
+| `VOLTRO_DASHBOARD_APPS` | dashboard only | JSON `[{name?,url,token?}]` — target apps + inspect tokens the deployed DevTools dashboard shows (served at runtime from `/api/dashboard/config`) |
+
+## Scaling beyond one instance
+
+When one api process isn't enough:
+
+1. Run multiple api containers behind the reverse proxy. The proxy's load-balancing default (round-robin) is fine for HTTP — for WebSocket, use sticky sessions (Caddy: `lb_policy ip_hash`).
+2. Install `@voltro/plugin-cluster` in `app.config.ts.plugins`. It sets up cross-instance subscription invalidation via Postgres NOTIFY (or Redis if you set `CLUSTER_TRANSPORT=redis`).
+3. Workflows: `@effect/cluster` shards work across instances by workflow ID. No further config — every instance pulls from the shared workflow queue.
+
+For multi-region: you need to run Postgres logical replication between regions yourself (or move to Voltro Cloud which handles it).
+
+## Backups
+
+Postgres is the source of truth. Use your provider's backup features (Neon PITR, RDS snapshots, `pg_dump` on a cron). Object-storage assets back up via the provider's lifecycle policies.
+
+## Deploying the DevTools dashboard
+
+The DevTools dashboard (route sitemap, rpc list, logs / traces, schedules, the per-plugin inspect panels) can run as its **own deployment on its own URL**. It reaches each observed app's `/_voltro/inspect/*` through its own same-origin proxy, so the target apps only need to be reachable from the dashboard pod — not the browser.
+
+- **Image:** the official `docker.io/voltro/dashboard` — a web-only Voltro app served by `voltro start`.
+- **Targets at runtime:** set `VOLTRO_DASHBOARD_APPS` to a JSON array of `{ name?, url, token? }`, where `url` is each app's origin and `token` is that app's `VOLTRO_INSPECT_TOKEN`. The dashboard serves it from `/api/dashboard/config` on boot, so **one image serves any environment** and the tokens stay server-side (never baked into the bundle):
+
+  ```
+  VOLTRO_DASHBOARD_APPS='[{"name":"prod","url":"https://app.example.com","token":"…"}]'
+  ```
+
+- **Gate it:** the dashboard is an ops surface — put it behind an IP allow-list and/or your SSO proxy. Each target app's inspect surface should itself be token-gated (`VOLTRO_INSPECT_TOKEN`); the dashboard forwards the configured token as `Authorization: Bearer`.
+
+## Production checklist
+
+- [ ] HTTPS terminates at the edge with HSTS preload
+- [ ] `VOLTRO_SESSION_SECRET` rotated from CSPRNG, stored in a secrets manager (not env file in git!)
+- [ ] `cookieSecure: true` in the `@voltro/plugin-auth` config
+- [ ] Postgres `wal_level=logical`, `max_replication_slots≥10`
+- [ ] `pgvector` extension if you use AI features
+- [ ] OpenTelemetry exporter pointed at your sink (Datadog / Honeycomb / Grafana / Loki)
+- [ ] `VOLTRO_INSPECT_TOKEN` set, or `VOLTRO_INSPECT=off` in production
+- [ ] CORS allow-list is exact origins (no `*` with credentials)
+- [ ] Database backups verified (a backup you've never restored isn't a backup)
+- [ ] At least one staging deploy that mirrors production exactly
+
+See `@voltro/plugin-auth/COOKIES.md` for the full cookie audit, and the [Why Voltro?](/docs/intro/why-voltro) page for what we won't build (and what we will).
+
+
+
+---
+
+<!-- source: en/deployment/scale-to-zero.md -->
+## Scale to zero
+
+_Dormancy — stop an idle app and bring it back on a request or a due cron/workflow, with no Kubernetes._
+
+Dormancy lets an idle app **scale to zero** — the app process stops while nothing is happening and comes back automatically on the next request, or when a scheduled job or a sleeping workflow is due. Idle apps cost almost nothing.
+
+It is the same runtime as always; an always-on **wake-orchestrator** sits in front and manages the app's lifecycle. Nothing about your queries, mutations, routes, schedules, or workflows changes.
+
+## Turn it on
+
+Two pieces: opt the app into sleep mode, then run the orchestrator in front of it.
+
+```typescript
+// apps/api/app.config.ts
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  store: 'postgres' as const,
+  dormancy: 'sleep',   // 'always-on' (default) | 'sleep'
+}
+```
+
+In `dormancy: 'sleep'`, self-scheduled crons and durable-workflow waits register a row in the `_voltro_wakeups` table instead of holding an in-process timer — so the orchestrator knows exactly when the app must be awake.
+
+```bash
+# Single-node, no Kubernetes — requires a SQL store (postgres/mysql/mariadb/mssql)
+voltro dormancy
+voltro dormancy --port 4000 --app-port 4001 --idle-grace-ms 60000
+```
+
+`voltro dormancy` owns the public port, spawns `voltro serve` on an internal port, and proxies to it. It **wakes** the app on the first request / WebSocket upgrade or when a `_voltro_wakeups` row falls due, and **stops** it once it has been idle — no clients, no in-flight requests, no actively-running workflow, no imminent wakeup — for the grace window.
+
+A reconnecting reactive client transparently wakes the app: the WebSocket upgrade brings it up, then the client re-subscribes from its cursor.
+
+> The orchestrator and the app share the app's database (the `_voltro_wakeups` table), so dormancy needs a **SQL store** — an in-process `memory` store can't be shared across the two processes.
+
+## What keeps an app awake
+
+The app is only stopped when, continuously for the grace window:
+
+- no WebSocket/reactive clients are connected,
+- no HTTP request is in flight,
+- no workflow is actively **executing** — a *suspended/sleeping* workflow is durable in the database and resumes on wake, so it does **not** keep the app awake,
+- no wakeup is due within the lookahead horizon.
+
+A long-sleeping workflow (`sleep('3 days')`) is exactly the case dormancy is built for: the app stops, and the orchestrator brings a fresh process up when the sleep is due — the workflow resumes from its journal.
+
+## Tiers (Voltro Cloud — coming soon)
+
+Managed cloud hosting is not yet available; the Pro / Enterprise rows below are the planned managed tiers. Today you self-host and run `voltro dormancy` yourself.
+
+| Tier | Behavior |
+| --- | --- |
+| Free / Self-Host (today) | aggressive sleep — `voltro dormancy`, honest cold-start on first hit per idle period; idle ≈ \$0 |
+| Pro (coming soon) | keep-warm — sub-second wake via the managed warm-pool/snapshot adapter |
+| Enterprise (coming soon) | always-on / dedicated — never scales down |
+
+On Voltro Cloud (when it ships) the wake adapter and grace values will be chosen for you per tier; on self-host you run `voltro dormancy` and tune the knobs yourself. The runtime is identical in every case.
+
+
+
+---
+
+<!-- source: en/deployment/serverless-functions.md -->
+## Serverless functions
+
+_Run isolated, independently-scaled work as *.serverless.ts functions — self-hosted (Node) or offloaded to Cloudflare Workers / Scaleway._
+
+A **`*.serverless.ts`** function is a self-contained unit run + deployed SEPARATELY
+from your api. It's written ONCE, Effect-first and schema-typed; the framework runs
+it on your own infra (`node`) or adapts it to an edge host's entrypoint
+(`fetch(request, env, ctx)` on Cloudflare Workers, `handle(event)` on Scaleway) —
+you never write platform boilerplate.
+
+## First: do you actually need one?
+
+For an always-on api, **reach for [`defineAction`](/docs/data/actions) first.** An
+action runs in-process and shares the rpc schema, session/tenant resolution, the
+DB handle, typed errors, CDC, tracing, and the WebSocket transport — all of which a
+serverless function THROWS AWAY (it gets only `HttpClient` + `ctx.env`: no DB, no
+session, no tracing). A serverless function is the right tool only when you
+specifically want one of:
+
+- **process isolation** — a heavy/risky dependency (native module, fat ML lib,
+  untrusted code) you don't want in the api's memory or crash domain;
+- **independent scaling** — a spiky endpoint scaled (or scaled-to-zero) separately
+  from the always-on api;
+- **independent release cadence** — deploy/restart that one unit without bouncing
+  the api and its live WebSocket connections.
+
+If none of those apply, write an action. The rest of this page assumes one does.
+
+## Writing a function
+
+```ts
+// api/functions/resizeImage.serverless.ts
+import { Effect, Schema } from 'effect'
+import { HttpClient } from '@effect/platform'
+import { defineServerless } from '@voltro/serverless'
+
+export default defineServerless({
+  name: 'resize-image',                        // kebab-case, DNS-safe — the deployed id
+  method: 'POST',                              // default POST; GET reads input from the query string
+  input:  Schema.Struct({ url: Schema.String, width: Schema.Number }),
+  output: Schema.Struct({ resized: Schema.String }),
+  runtime: { memoryMb: 512, timeoutSeconds: 30, region: 'fr-par' }, // best-effort host hints
+  handler: ({ url, width }, ctx) =>
+    Effect.gen(function* () {
+      const http = yield* HttpClient.HttpClient    // provided by the framework base layer
+      // ctx.env.SOME_SECRET  → the host's env / secret bindings
+      // ctx.waitUntil(p)     → background work that outlives the response (Cloudflare)
+      return { resized: `${url}?w=${width}` }
+    }),
+})
+```
+
+- **One default export per file** — a `defineServerless({ … })`.
+- `input` decodes the request (JSON body, or the query string for a `GET`).
+  `output` encodes the JSON response. A malformed input returns **400**.
+- The handler is Effect-first and may `yield* HttpClient.HttpClient` — the **only**
+  service the base layer provides. A serverless function is standalone: it has no
+  app database, plugins, or session. If your work needs those, it belongs in the
+  api as a mutation/action, not here.
+- To control the HTTP status, fail with `ServerlessHttpError({ status, message })`;
+  any other failure becomes a **500**.
+
+> **Start from a template.** The [`edge-functions`](/docs/reference/templates)
+> template ships eight runnable `*.serverless.ts` examples across the common
+> shapes (pure compute, geo from request headers, outbound HTTP, Web Crypto HMAC,
+> an LLM call, status-controlled errors). For the static-site-plus-form combo,
+> [`frontend-contact`](/docs/reference/templates) wires a static page's island
+> form to a serverless email function. `voltro add-app fns --template
+> edge-functions` drops the library into any project.
+
+## Develop locally
+
+Run one function on a real http port — same decode → run → encode the deployed
+function uses:
+
+```bash
+voltro serverless dev api/functions/resizeImage.serverless.ts --port 8910
+# POST http://localhost:8910/  with a JSON body matching `input`
+```
+
+Environment comes from `process.env` (load a `.env` with `node --env-file` if you
+like). `voltro serverless list` shows every discovered function.
+
+**CORS works locally.** `voltro serverless dev` / `serve` send
+`Access-Control-Allow-Origin` and answer the OPTIONS preflight — the same headers
+Cloudflare / Scaleway add at the edge. So a browser form on a static dev site
+(`localhost:5190`) can POST to the function (`localhost:8910`) cross-origin out of
+the box. The default is permissive (`*`); lock it down via the `cors` option on
+`serveServerless` when you self-host.
+
+## Self-hosted (default) — run it on your own infra
+
+The default target is **`node`** — no vendor, no cloud. Two shapes:
+
+```bash
+# Run ALL functions in ONE process — the cheap "one sidecar" case.
+# Drop it behind your baseline's reverse proxy (Caddy/nginx) next to the api.
+voltro serverless serve --port 8910 --host 0.0.0.0
+#   ▸ each function mounts at its `path` (or /<name> when several share /)
+#   ▸ GET /internal/liveness + /internal/readiness probes, like `voltro start`
+
+# OR build a standalone per-function kit (process isolation / independent scaling):
+voltro serverless build  --target node      # → index.mjs + Dockerfile + README (a complete kit)
+#   then: node index.mjs   (PORT from env)   — or `docker build` the emitted Dockerfile
+```
+
+`build --target node` produces a COMPLETE, self-hostable folder: the bundled
+`index.mjs` server **plus a `Dockerfile` and a `README`** with the exact run /
+docker / compose / reverse-proxy commands — drop it on any box with Node, or any
+container platform. (`deploy --target node` is the same, with the run plan
+printed.)
+
+`serve` is the everyday self-hosted runner; `build --target node` is the
+per-function kit you scale on its own. Either way the function runs the SAME
+`serverlessWebHandler` it would on the edge.
+
+## Edge offload (optional) — Cloudflare / Scaleway
+
+To save money on spiky or globally-distributed work, push a function to an edge
+host instead. The framework owns the bundle (esbuild) and the platform entry; the
+host's official CLI does only the upload, so those CLIs must be on PATH +
+authenticated.
+
+```bash
+# Cloudflare Workers — needs `wrangler` + CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID
+voltro serverless deploy --target cloudflare
+voltro serverless deploy --target cloudflare --node-compat   # add nodejs_compat for node:* builtins
+
+# Scaleway Functions — needs `scw` + SCW_ACCESS_KEY + SCW_SECRET_KEY + a namespace
+voltro serverless deploy --target scaleway --namespace-id <ns-id> --runtime node22
+
+# Inspect the plan without uploading:
+voltro serverless deploy --target cloudflare --dry-run
+```
+
+Build output lands in `.voltro/serverless/<target>/<name>/` — add `.voltro/` to
+your `.gitignore`.
+
+## How the three targets differ
+
+| Aspect | Node (self-hosted) | Cloudflare Workers | Scaleway Functions |
+|---|---|---|---|
+| Where it runs | your own infra | V8 isolate (web-standard, **not** Node) | Scaleway's Node.js (node20 / node22) |
+| `node:*` builtins | native | only with `--node-compat` | native |
+| Env / secrets | `process.env` | the `env` binding | `process.env` (`scw` args) |
+| `ctx.waitUntil` | best-effort | real (after the response) | best-effort |
+| Scaling | you (compose replicas / helm) | isolate, near-zero cold start | scale-to-zero, real cold starts (`min-scale ≥ 1` keeps warm) |
+| Runs the whole set | `serve` (one process) | one Worker per function | one function per namespace entry |
+
+Your handler code is identical across all three — only the target changes.
+
+## Notes
+
+- **Effect on the edge:** the framework pins `effect ≥ 3.20.0`, which carries the
+  fix for cross-request context isolation under concurrency. Don't pin an older
+  `effect` for a function you deploy to Workers.
+- **Browser/edge safety:** a Worker bundle must not pull `node:*` unless you pass
+  `--node-compat`. Keep function dependencies edge-safe, or deploy to Scaleway.
+- This is distinct from [scale-to-zero](/docs/deployment/scale-to-zero), which
+  idles your WHOLE api on a single node. Serverless functions split INDIVIDUAL
+  units off to a per-invocation host.
+
+
+
+---
+
+<!-- source: en/deployment/static-sites.md -->
+## Static-site deploy
+
+_Ship the static dist/ from `voltro build` to a cheap CDN (Cloudflare Pages, any S3-compatible bucket, Netlify) instead of serving it off the app server._
+
+`voltro build` emits a static `dist/` — pre-rendered HTML plus content-hashed
+assets. Serving that off your app server wastes the server on work a CDN does for
+pennies. `voltro static` ships `dist/` to a cheap external host, off the app
+server, so you save money at the edge.
+
+```bash
+voltro static hosts                                          # list supported hosts
+voltro static deploy --host cloudflare-pages --project-name my-site --spa
+voltro static deploy --host s3 --bucket my-bucket --endpoint https://s3.fr-par.scw.cloud
+voltro static deploy --host netlify --site-id <site-id>
+voltro static deploy --host cloudflare-pages --project-name my-site --dry-run
+```
+
+The framework owns the policy that's easy to get wrong; the host's official tool
+does the transfer (so it must be on PATH and authenticated).
+
+> **Static templates to start from:** [`frontend-static-blog`](/docs/reference/templates)
+> (SSG from a content source via `getStaticPaths` + islands),
+> [`frontend-landing`](/docs/reference/templates) (zero-JS marketing),
+> [`frontend-spa`](/docs/reference/templates) (client-rendered, `--spa`), and
+> [`frontend-contact`](/docs/reference/templates) (a static page + a serverless
+> form — the page deploys here, the function via `voltro serverless`).
+
+## Self-hosting already serves `dist/`
+
+You don't NEED `voltro static`. When you [self-host](/docs/deployment/self-hosting),
+`voltro start` serves `dist/` end-to-end (static HTML + SSR/ISR on demand), and
+your baseline's reverse proxy (Caddy/nginx) can serve the files directly too. So
+`voltro static` is a pure **cost-offload**: push the immutable assets to a cheap
+CDN while your api + Postgres stay on your own box.
+
+The split works because the browser reaches the self-hosted api over its own URL.
+Point the web app's api config at the api's public WebSocket endpoint:
+
+```ts
+// apps/web/app.config.ts
+apis: { app: { package: '@app/api', url: 'wss://api.yourdomain.com/ws' } }
+```
+
+The api stays self-hosted (it must — WebSocket subscriptions + Postgres are
+always-on); only the static bytes move to the edge. `POST /rpc` forwards the
+session cookie exactly as the WS path, so SSR loaders + auth resolve identically.
+
+## What the framework decides for you
+
+- **Content-Type** per file, from its extension (including the ones generic tools
+  get wrong: `.wasm`, `.woff2`, `.svg`, `.webmanifest`, `.avif`).
+- **Cache-Control:** content-hashed assets (`assets/index-a1b2c3d4.js`) →
+  `public, max-age=31536000, immutable`; HTML → revalidate on every request, so a
+  redeploy is visible immediately.
+- **SPA fallback** (`--spa`): serve `index.html` for unknown routes — for a
+  single-page app. Leave it off for per-route SSG output.
+
+For hosts that read them (Cloudflare Pages, Netlify) this is emitted as
+`_headers` / `_redirects`. **If you already ship your own `_headers` or
+`_redirects` in `dist/`, the framework leaves them untouched** — your intent wins.
+
+## The render-mode gate
+
+A pure static CDN can only serve pre-rendered HTML. So before it uploads,
+`voltro static deploy` checks the app's render-mode profile and **blocks** if the
+app isn't static-safe:
+
+- **`ssr` / `isr` pages** — these need a runtime to render per request; a CDN
+  can't run them.
+- **dynamic routes without `getStaticPaths`** — the build emits no artifact for
+  them, so they'd be 404 on a CDN.
+
+```bash
+voltro static deploy --host cloudflare-pages --project-name my-site
+# → voltro static deploy: "." is NOT pure-static —
+#     • 1 ssr page(s): need a runtime; a CDN can't render them
+#     → Serve those on a runtime (`voltro start` / a container), OR add
+#       getStaticPaths / set the pages to `static` / `spa`. To ship anyway
+#       (ssr/isr become client-rendered), pass --allow-dynamic.
+```
+
+Three ways forward:
+
+1. **Keep it static** — give dynamic routes a `getStaticPaths`, set pages to
+   `static` / `spa`. Then the deploy passes.
+2. **Ship anyway** — `--allow-dynamic`. The ssr/isr pages become client-rendered
+   (no server first-paint); fine if they degrade gracefully.
+3. **Use a runtime** — if the app genuinely needs SSR/ISR, it belongs on `voltro
+   start` / a container, not a pure CDN. See
+   [self-hosting](/docs/deployment/self-hosting). `voltro deploy plan` tells you,
+   per app, which tier it belongs to.
+
+`voltro build` records the profile to `dist/.voltro-build.json`, so the gate (and
+the cloud control-plane) classify without re-scanning. Point the scan at a
+non-default app root with `--app <dir>`.
+
+## Hosts
+
+| Host | `--host` | Mechanism | Auth |
+|---|---|---|---|
+| Cloudflare Pages | `cloudflare-pages` | `wrangler pages deploy` (built-in hash dedup) | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` |
+| S3-compatible | `s3` | `aws s3 sync` (two-pass cache) | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` |
+| Netlify | `netlify` | `netlify deploy` (SHA1 digest deploy) | `NETLIFY_AUTH_TOKEN` |
+
+### Cloudflare Pages
+
+```bash
+# one-time: wrangler pages project create my-site
+voltro static deploy --host cloudflare-pages --project-name my-site --spa
+```
+
+The project must exist first. Uploads are incremental (wrangler dedups by hash);
+new deploys auto-invalidate the edge.
+
+### S3-compatible (AWS, Scaleway, R2, B2, MinIO)
+
+One code path for every S3-compatible bucket — only the endpoint and keys change.
+Omit `--endpoint` for AWS; set it for the others.
+
+```bash
+# Scaleway Object Storage (has native static-website hosting)
+AWS_ACCESS_KEY_ID=<scw-access> AWS_SECRET_ACCESS_KEY=<scw-secret> \
+  voltro static deploy --host s3 --bucket my-bucket \
+    --endpoint https://s3.fr-par.scw.cloud \
+    --website-url https://my-bucket.s3-website.fr-par.scw.cloud
+```
+
+The sync runs two passes: immutable hashed assets first, then HTML with
+`no-cache`, and `--delete` prunes removed files. SPA fallback for a raw bucket is
+bucket-website / CDN configuration (and R2/B2/MinIO need a router in front
+entirely) — `--spa` warns rather than silently doing nothing here.
+
+### Netlify
+
+```bash
+voltro static deploy --host netlify --site-id <site-id> --spa
+```
+
+Netlify infers content types server-side and its digest-based deploy is
+incremental and atomic.
+
+## CI
+
+All three host CLIs run headless with a token in the environment — drop the
+deploy command into your pipeline after `voltro build`. Use `--dry-run` to print
+the exact plan in a PR check without uploading.
+
+
+
+---
+
+<!-- source: en/deployment/production-hardening.md -->
+## Production hardening
+
+_The production checklist — session secret, health probes, request limits, tenant isolation, observability, graceful shutdown, and multi-replica config._
+
+The defaults are tuned for `voltro dev`, where fast iteration wins. Before you point real traffic at `voltro serve`, walk this checklist — most items are a single env var or a one-line config, but skipping them is how a service leaks across tenants, forges sessions, or falls over under load.
+
+## 1. Session secret (REQUIRED)
+
+In production (`NODE_ENV=production`) `voltro serve` **refuses to boot** unless `VOLTRO_SESSION_SECRET` is set to a real value. It rejects three cases explicitly:
+
+- a **missing** value,
+- the built-in **public dev fallback** (it is committed in the framework source),
+- any value **shorter than 32 chars** — which catches placeholders like `changeme`.
+
+Generate a real one:
+
+```sh
+voltro secret generate session
+```
+
+Store it in your secrets manager and inject it as an env var — never commit it. Why the hard fail: a forgotten secret would otherwise sign session cookies with a key that is **public in the framework source**, letting anyone forge any session.
+
+**Rotation** is zero-downtime. Set the new value as `VOLTRO_SESSION_SECRET` and move the old one to `VOLTRO_SESSION_SECRET_PREVIOUS`:
+
+```sh
+VOLTRO_SESSION_SECRET=<new>            # signs new cookies
+VOLTRO_SESSION_SECRET_PREVIOUS=<old>   # still verifies live cookies
+```
+
+Keep `_PREVIOUS` in place for one session-TTL window, then drop it. Existing cookies verify against `previous` until they naturally expire — no live session is invalidated.
+
+## 2. Kubernetes health probes
+
+`voltro serve` exposes two unauthenticated endpoints, both handled **before** any rate-limit interceptor:
+
+- `GET /internal/liveness` — always `200 ok`. The process is up.
+- `GET /internal/readiness` — `200 ready` only after full boot, `503` before.
+
+Readiness **also** runs a DB ping (`SELECT 1`) on SQL stores. So a pod whose connection pool has died reports `503` and is pulled from the Service endpoints — instead of staying in rotation and erroring every request.
+
+```yaml
+# k8s Deployment — probes
+livenessProbe:
+  httpGet:
+    path: /internal/liveness
+    port: 4000
+  periodSeconds: 10
+readinessProbe:
+  httpGet:
+    path: /internal/readiness
+    port: 4000
+  periodSeconds: 5
+  failureThreshold: 3
+```
+
+> **Run `voltro serve` in serving pods — not `voltro dev`.** `voltro dev` is the
+> local-iteration supervisor: file-watch, respawn, codegen, and a boot-time
+> auto-migrate that introspects the whole schema. It does **not** expose the
+> probes above and binds its port only after that boot work finishes — so a TCP
+> probe can't tell "still booting" from "dead", and a large-schema migrate can
+> blow past a fixed startup window and get a healthy pod killed. Production pods
+> run `voltro serve`.
+
+## 3. Schema migration at deploy (don't migrate in the serving pod)
+
+`voltro serve` does **not** auto-migrate — schema changes go through an explicit
+deploy step, never on the serving pod's boot. The full contract (per-env
+fingerprint check, refuse-to-boot on mismatch, apply timing relative to the image
+swap) is [Prod pipeline](/docs/database/migrations/prod-pipeline); the k8s wiring
+is here.
+
+Run the apply as a **pre-deploy Job** (or `initContainer`) that holds the
+migration credentials and executes `voltro db apply`. It re-diffs the deployed
+code's declared schema against the live DB and applies the resulting plan — so
+it's a clean no-op on an already-current DB, which makes it safe to re-run and to
+run in every pod of a stateless deploy. A bare apply **refuses under
+`NODE_ENV=production`** by design (auto-apply on prod is not allowed), so the Job
+runs with `NODE_ENV` unset or `staging`; the serving pods keep
+`NODE_ENV=production`:
+
+```yaml
+# Helm pre-install/pre-upgrade Job — runs to completion BEFORE the new pods roll.
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: myapp-migrate
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade
+    "helm.sh/hook-weight": "-5"
+spec:
+  template:
+    spec:
+      restartPolicy: Never
+      containers:
+        - name: migrate
+          image: myapp:{{ .Values.image.tag }}
+          command: ["voltro", "db", "apply", "--note", "release {{ .Values.image.tag }}"]
+          env:
+            - { name: NODE_ENV, value: "staging" }   # bare apply is refused under "production"
+            # …plus the same DB_* connection env as the serving pods
+```
+
+```yaml
+# Serving Deployment — auto-migrate OFF; the Job already applied the schema.
+env:
+  - name: VOLTRO_AUTO_MIGRATE
+    value: "0"
+```
+
+For the reviewed-exact-diff flow — generate `voltro db plan --json > plan.json`
+in CI, apply it with `voltro db apply --plan plan.json` — see
+[Prod pipeline](/docs/database/migrations/prod-pipeline). That variant IS allowed
+under `NODE_ENV=production` (it refuses unless both fingerprints still match the
+reviewed plan). A Job runs **once per release** vs an `initContainer`'s once per
+replica, so it's the better fit for a multi-replica rollout.
+
+### If you DO run `voltro dev` in a cluster (dev / staging only)
+
+`voltro dev` binds a small **boot-health surface** on its own port so a probe can
+watch the slow boot (codegen + migrate) it otherwise couldn't see:
+
+- `GET /internal/liveness` → `200 ok` from the moment the process is up, through
+  the whole boot. Point `startupProbe` **and** `livenessProbe` here so migration
+  time counts as *alive*, not dead.
+- `GET /internal/readiness` → `503` until the app port is serving, then `200`.
+- `GET /internal/startup` → `200` JSON `{ phase, ready, tablesTotal, elapsedMs }`
+  (`phase` is `booting` → `migrating` → `ready`, or `error` with a message) — for
+  humans and dashboards watching progress.
+
+The port defaults to **app port + 1**; override with `VOLTRO_DEV_HEALTH_PORT`
+(set `0` to disable). A generous `startupProbe.failureThreshold` on
+`/internal/liveness` then gives a large-schema first migrate minutes instead of a
+fixed TCP window:
+
+```yaml
+# dev/staging pod running `voltro dev` — probe the boot-health port (4001)
+startupProbe:
+  httpGet: { path: /internal/liveness, port: 4001 }
+  periodSeconds: 10
+  failureThreshold: 60        # up to 10 minutes for a first cold migrate
+livenessProbe:
+  httpGet: { path: /internal/liveness, port: 4001 }
+readinessProbe:
+  httpGet: { path: /internal/readiness, port: 4001 }
+```
+
+Even a local `voltro dev` boots faster on reboots now: the auto-migrate skips the
+full introspect when the declared schema is unchanged (a fingerprint check — one
+indexed query instead of scanning every table). Force a full re-introspect with
+`VOLTRO_MIGRATE_FORCE=1`.
+
+## 4. Request limits & DoS
+
+`POST /rpc` (the buffered JSON endpoint the SSR loaders use) rejects an over-`Content-Length` body with **413** *before* buffering it into memory:
+
+```sh
+VOLTRO_MAX_RPC_BODY_BYTES=8388608   # default 8 MiB
+```
+
+Scope: this guards the `/rpc` JSON path only. File uploads ride separate storage routes with their own `limits.maxBytes`, and WebSocket frames are capped by the `ws` library default (100 MiB).
+
+**Put per-IP rate limiting and the primary body-size cap at the ingress** — that is the correct layer: it holds per-IP state and works across replicas, which an in-process limit can't.
+
+```yaml
+# nginx ingress — annotations on the Ingress resource
+nginx.ingress.kubernetes.io/proxy-body-size: "8m"
+nginx.ingress.kubernetes.io/limit-rps: "20"
+```
+
+For **app-level** throttling (per-subject / per-tenant, e.g. an expensive action), use `@voltro/plugin-ratelimit` and the plugin `onHttpRequest` interceptor seam. It complements the ingress cap — it does not replace it.
+
+## 5. Multi-tenant isolation
+
+Tables carrying the `tenant()` mixin are auto-scoped to the request's tenant — nothing more to do there. The gap is the **anonymous** request that matches no auth strategy: by default it resolves to a tenant-less anonymous Subject that can read any non-`tenant()` table across the DB.
+
+For an app where **every** request must be tenant-scoped (no anonymous public data), close that door:
+
+```ts
+// app.config.ts
+export default {
+  // ...
+  auth: {
+    anonymousTenantRequired: true,
+  },
+}
+```
+
+A request that matches no auth strategy **and** sends no `x-tenant` header is then rejected with `Unauthenticated` instead of resolving to a tenant-less Subject. It applies identically under `voltro dev` and `voltro serve`.
+
+> **Do NOT enable this if the app serves legitimate anonymous public data** — public read endpoints, reference tables — it would reject those callers. In that case, rely on putting `tenant()` on every private table instead.
+
+## 6. Observability (wire it or fly blind)
+
+By default nothing is exported. Wire it before you need it.
+
+**Traces + metrics** ship to any OTLP collector (Tempo / Jaeger / Honeycomb / Grafana Agent) from one env var:
+
+```sh
+OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318
+OTEL_SERVICE_NAME=my-api
+```
+
+**Structured logs** as JSON:
+
+```sh
+VOLTRO_LOG_FORMAT=json
+VOLTRO_LOG_LEVEL=info
+```
+
+**Error reporting** — add `sentryPlugin()` from `@voltro/plugin-sentry`. It stays inert until `SENTRY_DSN` is set, and reported errors correlate to the request `traceId`:
+
+```ts
+import { sentryPlugin } from '@voltro/plugin-sentry'
+
+export default {
+  // ...
+  plugins: [sentryPlugin()],
+}
+```
+
+Durable in-DB traces are **off in production by default** — traces belong in your OTLP backend, not your OLTP database.
+
+## 7. Graceful shutdown
+
+On `SIGTERM` / `SIGINT`, `voltro serve` shuts down cleanly (exit 0): it stops
+schedulers, detaches subscribers / reactions / aggregates, drains the analytics
+sink, stops accepting new connections while **finishing already-accepted
+requests**, and closes the SQL connection pool **last** (waiting for in-flight
+transactions). Verified under concurrent load — accepted requests complete.
+
+**But the app cannot drain a rolling update by itself.** The runtime
+(`NodeRuntime`) owns the `SIGTERM` signal and closes the HTTP listener promptly —
+so a request that *arrives* during shutdown is refused. Failing readiness from
+inside the process doesn't help: the listener is already closing. Draining is a
+**k8s-layer** job, done with a **preStop hook**:
+
+```yaml
+spec:
+  # Must exceed the preStop sleep + the app's own shutdown.
+  terminationGracePeriodSeconds: 30
+  containers:
+    - name: api
+      lifecycle:
+        preStop:
+          exec:
+            # k8s removes the pod from the Service endpoints AND runs this
+            # BEFORE sending SIGTERM. The sleep holds the pod up (listener open,
+            # finishing in-flight) while endpoint removal propagates — so no new
+            # request lands on a pod that's about to close.
+            command: ["sh", "-c", "sleep 5"]
+```
+
+Without the preStop hook, a rolling update drops the small window of requests
+that route to a terminating pod before k8s finishes removing it from the Service
+endpoints. With it, that window is drained. `terminationGracePeriodSeconds` must
+be larger than the sleep plus the app's own teardown, or k8s SIGKILLs mid-drain.
+
+## 8. Multiple replicas
+
+Cache and KV default to **in-process** (per-replica). For a shared backend across replicas:
+
+```sh
+CACHE_BACKEND=redis
+KV_BACKEND=redis
+```
+
+**Cross-replica reactivity** is the subtle one: a write on one pod never surfaces on another pod's open subscriptions unless the replicas share a change bus. Use:
+
+- **postgres** — LISTEN/NOTIFY (built in),
+- **mariadb** — binlog CDC (built in),
+- **other dialects** — `@voltro/plugin-broadcast` (Redis).
+
+Schedules and aggregates auto-coordinate via an advisory lock on SQL stores — no extra config to keep them from double-firing across replicas.
+
+## Checklist
+
+- [ ] `VOLTRO_SESSION_SECRET` set from `voltro secret generate session`, in a secrets manager
+- [ ] Rotation window uses `VOLTRO_SESSION_SECRET_PREVIOUS`
+- [ ] Liveness / readiness probes point at `/internal/liveness` + `/internal/readiness`
+- [ ] Serving pods run `voltro serve` (not `voltro dev`), with `VOLTRO_AUTO_MIGRATE=0`
+- [ ] Schema applied by a pre-deploy Job / initContainer (`voltro db apply`), not in the serving pod
+- [ ] `VOLTRO_MAX_RPC_BODY_BYTES` sane; ingress caps body size + per-IP rate
+- [ ] `auth.anonymousTenantRequired: true` (unless the app serves anonymous public data)
+- [ ] `OTEL_EXPORTER_OTLP_ENDPOINT` + `OTEL_SERVICE_NAME` pointed at your collector
+- [ ] `VOLTRO_LOG_FORMAT=json`; `sentryPlugin()` + `SENTRY_DSN` for errors
+- [ ] `terminationGracePeriodSeconds` generous for graceful drain
+- [ ] `CACHE_BACKEND` / `KV_BACKEND` + a cross-replica change bus when running >1 replica