@voltro/cli 0.11.3 → 0.12.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { bt as e } from "./inspectMetrics-SRtv8KDy.js";
-import { t } from "./start-Crl39M38.js";
+import { X as e } from "./inspectMetrics-uEfIS1vp.js";
+import { t } from "./start-DKcQd52a.js";
 export { e as loadDotEnv, t as runStartCommand };

package/dist/startup.js

@@ -1,2 +1,2 @@
-import { n as e, t } from "./startupRunner-DhlX9nqd.js";
+import { n as e, t } from "./startupRunner-DPGFchOa.js";
 export { t as loadStartupFiles, e as runStartups };

package/dist/{startupRunner-DhlX9nqd.js → startupRunner-DPGFchOa.js}

@@ -1,44 +1,30 @@
-import { basename as e } from "node:path";
-import { pathToFileURL as t } from "node:url";
+import { n as e } from "./appModuleLoader-C9r9mxZt.js";
+import { basename as t } from "node:path";
 import { publishServerError as n } from "@voltro/protocol";
-//#region src/appModuleLoader.ts
-var r = /* @__PURE__ */ new Map(), i = /* @__PURE__ */ new Map(), a = (e) => {
-	for (let [t, n] of Object.entries(e)) r.set(t, n);
-}, o = () => r.size > 0, s = async (e) => {
-	let n = i.get(e);
-	if (n) return n;
-	let a = r.get(e);
-	if (a !== void 0) {
-		if (typeof a == "function") {
-			let t = await a();
-			return i.set(e, t), t;
-		}
-		return a;
-	}
-	return await import(t(e).href);
-}, c = (e) => e.replace(/\.startup\.tsx?$/, ""), l = async (t, n) => {
-	let r = [];
-	for (let i of t) {
-		let t;
+//#region src/startupRunner.ts
+var r = (e) => e.replace(/\.startup\.tsx?$/, ""), i = async (n, i) => {
+	let a = [];
+	for (let o of n) {
+		let n;
 		try {
-			t = await s(i);
+			n = await e(o);
 		} catch (e) {
-			n.warn("startup: failed to import", { file: i }, e);
+			i.warn("startup: failed to import", { file: o }, e);
 			continue;
 		}
-		let a = t.default;
-		if (typeof a != "function") {
-			n.warn("startup: no default-export function", { file: i });
+		let s = n.default;
+		if (typeof s != "function") {
+			i.warn("startup: no default-export function", { file: o });
 			continue;
 		}
-		r.push({
-			file: i,
-			id: c(e(i)),
-			fn: a
+		a.push({
+			file: o,
+			id: r(t(o)),
+			fn: s
 		});
 	}
-	return r;
-}, u = async (e, t, r) => {
+	return a;
+}, a = async (e, t, r) => {
 	let i = [];
 	for (let a of e) {
 		let e = r.child(`startup:${a.id}`), o = {
@@ -82,4 +68,4 @@ var r = /* @__PURE__ */ new Map(), i = /* @__PURE__ */ new Map(), a = (e) => {
 	} };
 };
 //#endregion
-export { a, s as i, u as n, o as r, l as t };
+export { a as n, i as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.11.3",
-    "@voltro/cache": "0.11.3",
-    "@voltro/data-transfer": "0.11.3",
-    "@voltro/database": "0.11.3",
-    "@voltro/env": "0.11.3",
-    "@voltro/kv": "0.11.3",
-    "@voltro/logger": "0.11.3",
-    "@voltro/plugin-auth": "0.11.3",
-    "@voltro/plugin-broadcast": "0.11.3",
-    "@voltro/plugin-mail": "0.11.3",
-    "@voltro/plugin-storage": "0.11.3",
-    "@voltro/plugin-webhooks": "0.11.3",
-    "@voltro/protocol": "0.11.3",
-    "@voltro/runtime": "0.11.3",
-    "@voltro/serverless": "0.11.3",
-    "@voltro/workflow": "0.11.3",
+    "@voltro/ai": "0.12.0",
+    "@voltro/cache": "0.12.0",
+    "@voltro/data-transfer": "0.12.0",
+    "@voltro/database": "0.12.0",
+    "@voltro/env": "0.12.0",
+    "@voltro/kv": "0.12.0",
+    "@voltro/logger": "0.12.0",
+    "@voltro/plugin-auth": "0.12.0",
+    "@voltro/plugin-broadcast": "0.12.0",
+    "@voltro/plugin-mail": "0.12.0",
+    "@voltro/plugin-storage": "0.12.0",
+    "@voltro/plugin-webhooks": "0.12.0",
+    "@voltro/protocol": "0.12.0",
+    "@voltro/runtime": "0.12.0",
+    "@voltro/serverless": "0.12.0",
+    "@voltro/workflow": "0.12.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -452,6 +452,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
+| **What's new in 0.11.4** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,6 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
+| **What's new in 0.11.4** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_manifest.json

@@ -35,7 +35,7 @@
       "group": null,
       "description": "The voltro CLI — every command, grouped by purpose, with the flags that actually matter.",
       "path": "agent-docs/cli.md",
-      "files": 9
+      "files": 10
     },
     {
       "id": "configuration",

package/templates/agent-docs/cli.md

@@ -21,9 +21,9 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 |---|---|
 | [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` |
+| [Dev](/docs/cli/dev) | `dev`, `codegen`, `agents-md`, [`env`](/docs/cli/env) (`check` / `sync` / `types` / `turbo`), [`generate`](/docs/cli/scaffolding) (AI app-builder), `dashboard` (serve the DevTools dashboard standalone; `--port`, `VOLTRO_DASHBOARD_APPS`) |
 | [Build & run](/docs/cli/build-and-start) | `build`, `start`, `serve` |
-| 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`) |
+| 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`), `dormancy` (single-node scale-to-zero: fronts the app, stops it when idle, wakes on the next request; `--idle-grace-ms` / `--tick-ms`) |
 | [Database](/docs/cli/migrate) | `migrate`, `db` (`plan` / `apply` / `plans` / `drift` / `squash` / `restore-snapshot` / `migrate` / `rollback` / `status` / `seed`) |
 | [Update](/docs/cli/update) | `update` (`--to` / `--dry-run` / `--force` / `--exact`) — bump every `@voltro/*`, install, run the codemods that adapt your source to the new version |
 | [Data transfer](/docs/cli/data) | `data` (`export` / `import` / `unpack` / `inspect` / `backup` / `restore`) — directory + single-file `.vbundle` bundles, streaming assets, masking, at-rest encryption |
@@ -105,8 +105,7 @@ pnpm dev       # turbo adds the new app to its parallel boot
 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
+# `voltro migrate` is an alias of `db apply` — same differ, shorter name (CI / ops)
 ```
 
 ### "I want a clean rebuild"
@@ -130,19 +129,69 @@ 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.
+`voltro check` runs blast-radius checks over your app's typed graph — dangling
+`source` / `target` tables, scopes no role grants, unguarded mutations, broken
+route bindings, orphan tables — at edit time instead of at runtime. `--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.
+
+It prefers a running api (its manifest is ground truth, including live table
+introspection). **With none reachable it assembles the same graph from source**,
+so it works as a pre-commit hook or a CI gate without a second terminal —
+`--offline` forces that path.
 
 ```bash
-voltro check                          # blast-radius checks vs the live manifest
+voltro check                          # running api if there is one, else from source
+voltro check --offline                # never contact a server — the CI form
+voltro check --url https://api.example.com   # a DEPLOYED app
 voltro check --json                   # { ok, diagnostics: [{ rule, node, breaks, fix }] }
 voltro check --diff removeTable:todos # what a proposed removal would break, before applying
 ```
 
+`rbac/unknown-scope` needs a declared scope vocabulary to compare against —
+`rbacPlugin({ roles })` publishes one automatically. It catches a guard
+requiring a scope no role grants, which makes that procedure permanently and
+silently uncallable. (With a custom `resolvePermissions` the vocabulary isn't
+exhaustive, so the rule stays quiet rather than flagging correct code.)
+
+#### Declared vs OBSERVED — reconciled against reality
+
+A query's `source` and a mutation's `targets` are not documentation: the
+framework routes optimistic patches and decides which subscriptions a write
+invalidates from them. A wrong declaration is a live, user-visible bug that
+nothing type-checks — the mutation succeeds, the write lands, and the wrong list
+fails to update.
+
+`voltro dev` records what each procedure ACTUALLY touched, into
+`app.graph.observed.json` (gitignored automatically). When that file is present,
+`check` diffs it against the declarations:
+
+```
+observed: 12/34 procedures exercised (35%)
+  mutation(orders.place) (api/orders/place.mutation.ts)
+    writes 'inventory' (update) but declares no target for it
+    subscriptions on that table are not invalidated by this mutation
+    fix: add { table: 'inventory', op: 'update' } to this procedure's targets
+  22 unexercised — no recording, so nothing is claimed about them
+```
+
+Three things about that output are deliberate:
+
+- **Coverage comes first.** Three findings at 8% coverage and three at 95% are
+  different claims. Hiding the denominator is how a check starts overstating
+  what it knows.
+- **`unexercised` is a third state, not a finding.** A procedure no test and no
+  dev session ever ran has *no observation* — which is not the same as "touches
+  nothing". It is counted and never reported as a problem.
+- **Observed diagnostics never fail the build.** An observation is evidence
+  about the runs that happened, not a proof about the ones that didn't, and
+  `check`'s exit code gates CI. They are always warnings.
+
+No file → the section is skipped silently. This is not derived by parsing your
+handlers: a static pass over code that reaches the store through shared helpers,
+behind conditionals, has a long tail of both false positives and false negatives
+— and a check that is *sometimes* wrong is one people stop reading.
+
 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
@@ -798,6 +847,78 @@ Docker step) and prints the exact remedy: add a `voltro build .` step before
 `voltro serve .`. Drop it into your image build right after `voltro build` to
 guarantee the artefact is present before the image ships.
 
+### The predicate-column check
+
+`eq` / `isNull` / `inSet` are free functions, so the column name arrives as a bare
+`string` and the builder cannot relate it to the table the predicate is attached
+to:
+
+```ts
+database.teamAppointments.where(isNull('deletedAt'))
+//                               ^ teamAppointments has no softDelete() mixin,
+//                                 so no `deletedAt` column exists. tsc: OK.
+```
+
+That type-checks — review and CI pass — and then fails at runtime as a bare SQL
+error. `voltro doctor` checks every literal predicate column against the table's
+declared columns and names both:
+
+```
+✗  predicate columns: 1 filter on a column that does not exist (214 checked)
+  api/appointments/rollforward.query.server.ts:31  'teamAppointments' has no column 'deletedAt'
+    columns: id, teamId, startsAt, createdAt, updatedAt
+  This type-checks today and fails at runtime as a bare SQL error.
+```
+
+Matching is on the AST, never on text, so a column name in a comment or an
+unrelated string cannot trip it. A call site whose table cannot be resolved is
+skipped silently — an unresolvable receiver is usually not a table at all.
+
+The type-level fix (binding the predicate to the row, `where(c => isNull(c.x))`)
+is the right end state and is planned separately. This check is the half that
+works **retroactively**: it finds the bug in code that already exists, which a
+type change never will.
+
+The detector also flags **raw `fetch()` in server files**. The SSRF guard the
+framework ships lives in the `HttpClient` handlers `yield*` — so it protects
+exactly the apps that already adopted it, and misses the ones that never did.
+Those are usually the same apps that secured least elsewhere, which is why the
+absence is worth naming out loud rather than assuming the default did its job.
+
+Server files only (`*.server.ts`, `*.cron.ts`, `*.subscribe.ts`, …): `fetch` is
+unremarkable in a browser component, and flagging it there would make the rule
+noise that gets scrolled past — taking the real findings with it.
+
+### The `workflows.start` audit
+
+`voltro doctor` also diffs every `workflows.start(name, payload)` call site
+against the workflows the app actually registers:
+
+```
+✗  workflow starts: 13/14 call sites checked
+  api/crons/weekly.cron.ts:22  'sprint.report' payload is missing: teamId
+  api/crons/weekly.cron.ts:22  'sprint.report' payload has unknown field(s): scheduledAt
+    accepted: sinceIso, teamId
+  1 UNCHECKED (not verified — not a pass):
+    api/crons/digest.cron.ts:8 — payload spreads a value
+```
+
+**Why this exists even though `workflows.start` validates at runtime.** Runtime
+validation fires on the next firing — which for a daily cron is hours, for a
+weekly one is a week, and for a quarterly one is a quarter. And
+`voltro inspect schedules --failing` cannot see a job that has *never fired*,
+because its roll-up is built from recorded runs. A weekly workflow broken by a
+refactor is invisible to both until it next runs.
+
+**`UNCHECKED` is never folded into a pass.** A payload built with a spread or a
+computed key can contribute any name, so its key set is unknowable here. Those
+call sites are counted and listed rather than passed silently — `0 issues` must
+not be readable as "all verified". The workflow **name** is checked regardless,
+since a rename or a deletion is decidable whatever the payload looks like.
+
+The required keys come from the live `payloadSchema`, the same source the runtime
+validation reads, so the two cannot disagree about what a payload needs.
+
 ### The hand-roll detector
 
 `voltro doctor` also scans your source for shapes the framework already has a
@@ -1007,16 +1128,18 @@ package's README.
 <!-- source: en/cli/migrate.md -->
 ## Migrate
 
-_voltro migrate — the idempotent schema apply; voltro db plan/apply for the declarative diff workflow._
+_voltro migrate — apply the declared schema through the declarative differ (an alias of voltro db apply)._
+
+`voltro migrate` applies your declared schema (`*.entity.ts` / `*.schema.ts` / `schema.ts`) to the configured database. It is an **alias of [`voltro db apply`](#the-declarative-workflow)**: it diffs the declared schema against the live database and emits the ALTERs, so a changed column or a new index actually lands.
 
-`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.
+> Before 0.11.4 this command was a create-only apply (`CREATE TABLE IF NOT EXISTS`, no diffing), which meant a column or type change reported success having applied **nothing**. If you need that bootstrap-only behaviour for a brand-new database, it is now `voltro migrate --create-only`.
 
 ```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).
+`voltro migrate` forwards its arguments to `voltro db apply`, so the same flags apply; `--create-only` selects the bootstrap-only emitter instead. The diff / plan / apply / drift / squash workflow lives under `voltro db` (see below).
 
 For the deep dive on the schema DSL + day-to-day patterns, see [Database / Migrations](/docs/database/migrations).
 
@@ -1125,12 +1248,61 @@ voltro inspect rpc                              # procedures + workflow descript
 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 schedules --failing              # only broken crons — exits 1 if any (see below)
 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.
 
+### `schedules --failing` — is any cron actually broken?
+
+A schedule fires unattended: there is no user watching it fail. The plain
+`schedules` listing answers *which crons exist and when they fire next* — never
+whether they **work**. `--failing` rolls each schedule's recent runs
+(`/_voltro/inspect/schedules/runs`) into a verdict and prints only the broken
+ones:
+
+```bash
+$ voltro inspect schedules --failing
+# schedules @api
+  sprint.report  0 2 * * *  FAILING x87
+    every recorded run failed (last 20)
+    Workflow "sprint.report" was started with an invalid payload. missing required field(s): teamId
+```
+
+It **exits 1 when anything is failing**, so it works as a post-deploy gate and
+not only as something someone remembers to run:
+
+```bash
+voltro inspect schedules --failing || echo "broken cron — do not promote"
+```
+
+A trailing success ends a streak (a recovered job is not reported), and
+`skipped` / `missed` runs are ignored — those are coordination outcomes (another
+pod took the tick, the process was down), not handler verdicts. A schedule that
+has never run is not "failing".
+
+Pair it with `voltro logs --level error`: a failing handler now logs at **error**
+level, so the two surfaces agree.
+
+## Targeting a deployed app
+
+Every command in this family resolves its target from the local runtime registry — the apps running on *this* machine. Pass `--url` to point one at a **deployed** app instead:
+
+```bash
+voltro inspect app     --url https://api.example.com --token "$TOKEN"
+voltro logs   --tail 100 --url https://api.example.com
+voltro traces --errors   --url https://api.example.com
+voltro check             --url https://api.example.com
+```
+
+`--token` (or `VOLTRO_INSPECT_TOKEN`) supplies the bearer; `VOLTRO_INSPECT_URL` sets a default target so you can drop the flag. Works for `inspect`, `logs`, `traces`, `workflows`, `cluster` and `check`.
+
+## Securing the local surface
+
+`voltro dev` mints a per-project `VOLTRO_INSPECT_TOKEN` into `.env.local`, so the inspect surface is authenticated from the first boot — the dev server listens on every interface, and without a token anyone on the same network could read your rows, schema and logs. You don't have to wire it anywhere: the CLI picks the token up from the runtime registry (so the commands work from any directory), and the dashboard's server-side proxy supplies it for same-machine targets. Setting `VOLTRO_INSPECT_TOKEN` yourself always wins.
+
 ## 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).
@@ -1235,6 +1407,18 @@ 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 cluster`
+
+`voltro cluster status` gives a clustering snapshot of every running api — one row per instance with its `replicaId`, runner address, dialect, CDC flavour, coordination mode, and `server_id`, plus a flag for any SQL runner stuck on `localhost` (a common misconfiguration that silently breaks cross-instance work). Use it to confirm a multi-instance deployment actually formed a cluster rather than N isolated nodes.
+
+```bash
+voltro cluster status                 # pretty table across every running api
+voltro cluster status --json          # machine-readable (also --format json)
+voltro cluster status --process api   # narrow to one named process
+```
+
+Like the rest of the inspect family it reads the live `/_voltro/inspect/*` surface, so an api has to be running.
+
 ## `voltro test`
 
 ```bash
@@ -1249,6 +1433,30 @@ Runs Vitest with the framework's preset:
 - `STORE=memory` by default for fast isolation.
 - Plays well with `@voltro/testing` helpers (mock stores).
 
+### Every vitest flag is forwarded
+
+Anything the command does not interpret itself goes straight to vitest — parsed
+by **vitest's own CLI parser**, not a list this wrapper maintains:
+
+```bash
+voltro test --coverage
+voltro test --reporter=junit --outputFile=reports/junit.xml
+voltro test --coverage --reporter=junit --outputFile=reports/junit.xml
+```
+
+That covers coverage numbers and a JUnit report for a merge-request widget, which
+is what most pipelines want beyond the exit code.
+
+The framework keeps three decisions for itself and they win over a forwarded
+flag: the **root** (a positional that is an existing directory, which vitest
+would otherwise read as a filter), `--watch`, and `passWithNoTests` — an explicit
+filter that matches no file is an *error*, which vitest cannot decide because it
+does not know which positional was treated as a root.
+
+An unrecognised flag is ignored rather than fatal, and a flag vitest cannot parse
+at all degrades to "run without the extra flags" with a warning instead of taking
+the run down.
+
 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
@@ -1288,7 +1496,9 @@ The framework's `voltro e2e` handles the lifecycle for you: it boots the api + w
 
 ## Securing the inspect surface
 
-The inspect endpoints expose framework internals (queries, subscription state, workflow runs). In production, lock them down with a bearer token:
+The surface is **fail-closed**: with no `VOLTRO_INSPECT_TOKEN` configured, every endpoint answers `401`. The absence of a secret is not consent — a check you were configured not to perform is a refusal, not a pass.
+
+That is why `voltro dev` mints one for you (above) and why nothing mints outside dev: in production a missing secret must stay a boot-time decision rather than an invented value. So a production `voltro start` serves nothing here until you set the token yourself:
 
 ```bash
 VOLTRO_INSPECT_TOKEN=$(openssl rand -hex 32)
@@ -1306,7 +1516,7 @@ Or disable the surface entirely: `VOLTRO_INSPECT=off`. The dashboard then can't
 
 ## 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.
+- **Assuming the surface is open because you didn't configure it.** It is the reverse: no token means `401`, not "everyone". If a production dashboard suddenly stops introspecting, the missing `VOLTRO_INSPECT_TOKEN` is the first thing to check — not a network problem.
 - **`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.
 
@@ -2052,3 +2262,43 @@ Use `voltro db apply` (the declarative diff), not `voltro db migrate` (the imper
 
 - [Migrate](/docs/cli/migrate) — schema changes end-to-end
 - [Build & start](/docs/cli/build-and-start) — production paths
+
+
+
+---
+
+<!-- source: en/cli/env.md -->
+## Env
+
+_voltro env — inspect and sync the typed-env manifest; emit env.generated.d.ts so CI tsc knows your env vars._
+
+`voltro env` works with the **typed-env manifest** — the set of environment variables your app declares (via `envVar(...)`) and the framework requires. It's how a missing or malformed env var becomes a boot-time error with a clear message instead of a mysterious runtime failure.
+
+```bash
+voltro env            # check (default) — validate the current env against the manifest
+voltro env check      # explicit
+voltro env sync       # write/update .env.example from the manifest
+voltro env types      # emit env.generated.d.ts (typed process.env for CI tsc)
+voltro env turbo      # emit the turbo globalEnv/globalPassThroughEnv list
+```
+
+## `check` (default)
+
+Validates the current environment against the declared manifest and fails (non-zero) on a missing required var or a value that doesn't parse. Run it in a pre-deploy step to catch a misconfigured environment before the app boots. Run with no subcommand and it defaults to `check`.
+
+## `sync` — keep `.env.example` honest
+
+Writes `.env.example` from the manifest so the committed template always matches what the app actually reads — new `envVar(...)` declarations show up without hand-editing.
+
+## `types` — typed `process.env` for CI
+
+Emits `env.generated.d.ts`, which types `process.env` to your declared vars. Commit it (or generate it in CI before `tsc`) so a typo in a `process.env.MY_VAR` reference is a type error, not a runtime `undefined`.
+
+## `turbo` — monorepo cache correctness
+
+Emits the `globalEnv` / `globalPassThroughEnv` entries for `turbo.json`, so Turbo's cache invalidates when a relevant env var changes and passes the right vars through to tasks.
+
+## Related
+
+- [Secrets](/docs/cli/overview#common-env-vars) — generating secret values with `voltro secret`.
+- [Configuration](/docs/configuration) — declaring env vars with `envVar(...)`.