@voltro/cli 0.11.4 → 0.13.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { xt as e } from "./inspectMetrics-D4EJ8LTi.js";
-import { t } from "./start-DyJE6w1R.js";
+import { X as e } from "./inspectMetrics-DOiiII34.js";
+import { t } from "./start-CjG_0xhR.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.4",
+  "version": "0.13.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.4",
-    "@voltro/cache": "0.11.4",
-    "@voltro/data-transfer": "0.11.4",
-    "@voltro/database": "0.11.4",
-    "@voltro/env": "0.11.4",
-    "@voltro/kv": "0.11.4",
-    "@voltro/logger": "0.11.4",
-    "@voltro/plugin-auth": "0.11.4",
-    "@voltro/plugin-broadcast": "0.11.4",
-    "@voltro/plugin-mail": "0.11.4",
-    "@voltro/plugin-storage": "0.11.4",
-    "@voltro/plugin-webhooks": "0.11.4",
-    "@voltro/protocol": "0.11.4",
-    "@voltro/runtime": "0.11.4",
-    "@voltro/serverless": "0.11.4",
-    "@voltro/workflow": "0.11.4",
+    "@voltro/ai": "0.13.0",
+    "@voltro/cache": "0.13.0",
+    "@voltro/data-transfer": "0.13.0",
+    "@voltro/database": "0.13.0",
+    "@voltro/env": "0.13.0",
+    "@voltro/kv": "0.13.0",
+    "@voltro/logger": "0.13.0",
+    "@voltro/plugin-auth": "0.13.0",
+    "@voltro/plugin-broadcast": "0.13.0",
+    "@voltro/plugin-mail": "0.13.0",
+    "@voltro/plugin-storage": "0.13.0",
+    "@voltro/plugin-webhooks": "0.13.0",
+    "@voltro/protocol": "0.13.0",
+    "@voltro/runtime": "0.13.0",
+    "@voltro/serverless": "0.13.0",
+    "@voltro/workflow": "0.13.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.13.0** | `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.13.0** | `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/authentication.md

@@ -563,6 +563,42 @@ const resolve = composeAuthStrategies(
 
 Order matters: put the cheapest / most-common strategy first. When no strategy matches, the resolver returns an [anonymous Subject](/docs/authentication/subject) scoped to the `x-tenant` header (or a custom `fallback` you supply).
 
+## Roles from your database — `auth.resolveScopes`
+
+If your authorization is a database ROLE rather than a scope on the token, the framework cannot see it. `voltro check`'s `rbac/unguarded-mutation` reports every such write as unguarded — correctly, because nothing about the decision is declared — and the declarative alternative is unusable for you: subjects that come from an external IdP carry no scopes, so `requireScope('employee:admin')` would lock out every real user. One app measured 1566 findings it had no way to act on.
+
+`resolveScopes` closes that. It runs after a strategy matches and adds scopes to the resolved Subject from whatever source you like:
+
+```ts
+// app.config.ts
+export default defineApiConfig({
+  auth: {
+    resolveScopes: async (subject) => {
+      const role = await roleCache.get(subject.id)   // cache it — see below
+      return role === 'admin' ? ['employee:admin', 'employee:read'] : ['employee:read']
+    },
+  },
+})
+```
+
+The same authorization is now declarable on the descriptor:
+
+```ts
+export const payrollList = defineQuery({
+  name: 'payroll.list',
+  guards: [requireScope('employee:admin')],   // visible in the manifest, checkable in CI
+  …
+})
+```
+
+**Scopes only — never a Subject.** The hook cannot change `id` or `tenantId`: identity belongs to the auth strategy, and a hook that could rewrite it would be a forgery surface. The returned scopes are UNIONED with whatever the strategy already set, so a resolver can grant authority but never revoke it.
+
+**It does not run for anonymous callers** — there is no identity to look a role up for.
+
+**Cache it yourself.** It is on the request path. A `Map` keyed by subject id with a short TTL is usually enough. The framework deliberately does not cache for you, because only you know how quickly a role change has to take effect.
+
+Wired identically under `voltro dev` and `voltro serve`.
+
 ## Wiring it into the app
 
 The composed resolver becomes the runtime's `AuthMiddleware` — the per-request middleware that populates `SubjectService` so every handler can `yield* SubjectService` (or read `ctx.subject`). On a single-strategy password app you never touch this; the plugin wires `voltroPasswordStrategy` for you. You only assemble the chain explicitly when you add a second strategy:

package/templates/agent-docs/cli.md

@@ -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.generated.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
@@ -398,6 +447,25 @@ _voltro dev, codegen, agents-md — what runs during local development and the e
 
 `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.
 
+### Running `voltro dev` in a container
+
+If your dev pod runs as root with the host workspace bind-mounted, everything
+the framework generates would otherwise land `root:root` inside your own tree —
+and on the host `voltro build` then fails on its own output:
+
+```
+EACCES: permission denied, open '…/apps/display/.framework/index.html'
+```
+
+`voltro dev` and `voltro build` hand their generated output (`.framework`,
+`.env.local`, every `*.generated.*`) to whoever owns the app root, and warn
+loudly when they cannot. Only generated state — the framework never takes
+ownership of a file you wrote.
+
+The cleaner fix is on your side and worth doing anyway: start the container as
+the workspace owner, `docker run --user $(id -u):$(id -g)`. Then nothing needs
+handing over at all.
+
 ## `voltro dev <appDir>`
 
 ```bash
@@ -798,6 +866,100 @@ 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.
+
+The rule follows the IMPORT GRAPH, not the filename. Server-convention files
+(`*.server.ts`, `*.cron.ts`, `*.subscribe.ts`, …) are the starting points, and
+any file reachable from them and from **nothing else** counts as server code
+too. That matters: keyed on filenames alone the rule caught 9 of 39 outbound
+calls on the app that reported it — the other 30 sat in `lib/*.ts` helpers
+(payments, an AI provider, TTS) imported only from server executors. A
+`lib/payments-mollie.ts` is not client code, and no file extension can say so.
+
+A helper a page ALSO imports stays unflagged, and that is the property keeping
+this rule useful: `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. Relative imports and your tsconfig `paths` aliases are both
+followed.
+
+The detector also flags an **executor that never names its own descriptor**.
+Pairing is by FILENAME, which is right — and it means a `*.server.ts` can be a
+complete, correct executor with no reference at all to the contract it
+implements. Those are exactly the files where a hand-written input drifts from
+the wire: in one reported codebase, six executors declared `boardPurpose: string`
+where their own descriptor said `Schema.Literal(...)`, discarding the contract at
+the executor boundary. Fix by importing the descriptor and typing the input as
+`ExecutorInput<typeof descriptor>`. Only a SIBLING import clears the finding —
+an executor importing nothing but `@voltro/*` and `node:*` has still not named
+its contract.
+
+
+### 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
@@ -893,6 +1055,39 @@ matching rule lives inside the CLI, so you cannot re-derive the list with your
 own grep. `--json` prints the complete scan, nothing elided, with no preflight
 output mixed in:
 
+### Duplicate package instances
+
+`voltro doctor` also reports any identity-sensitive package resolved at more than
+one version — `effect`, `@effect/*`, `@voltro/*`, react/react-dom:
+
+```
+•  1 package(s) resolved at more than one version:
+     effect — 3.18.4, 3.21.0
+       node_modules/effect
+       ../../node_modules/effect
+```
+
+This is worth its own check because of how it PRESENTS. Effect's types are
+nominal, so a `Schema` built by one copy is not the type the other expects, and
+the errors land in the GENERATED `rpcGroup.generated.ts` — a file you cannot edit
+and did not write:
+
+```
+Property '[TypeId]' is missing in type … Schema<any, any, unknown>
+Type 'typeof Never' is not assignable to type 'All'
+Argument of type 'Rpc<…, Stream<…>, …>' is not assignable to 'Any'
+```
+
+Read cold, that says "the framework emits bad types". It says nothing about the
+dependency tree, which is where the problem is. And the RUNTIME usually stays
+green — two instances only diverge where identity matters — so the app boots,
+serves and passes its tests while `tsc` is red.
+
+Fix it in the install, not the code: align the version across the workspace (a
+root `pnpm.overrides` / `resolutions` entry for `effect` is the blunt
+instrument), then reinstall. Do NOT add `@ts-nocheck` to the generated file — it
+is exactly where a genuine mistake in your own descriptors surfaces.
+
 ```bash
 voltro doctor . --json          # the complete scan: every file path, machine-readable
 ```
@@ -1007,16 +1202,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).
 
@@ -1163,6 +1360,23 @@ 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).
@@ -1293,6 +1507,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
@@ -1332,7 +1570,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)
@@ -1350,7 +1590,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.
 

package/templates/agent-docs/configuration.md

@@ -326,6 +326,54 @@ const issued = await svc.issue({ tenantId, name: 'mobile app', scopes: ['read']
 // show issued.token ONCE; later: svc.rotate(id), svc.revoke(id), svc.list(tenantId)
 ```
 
+## The second ownership axis — `metadata`
+
+`tenantId` and `onBehalfOf` are the two relationships the framework models. If
+your keys also belong to something else — a team, a project, an environment —
+and that binding is what authorizes them, store it in `metadata`:
+
+```ts
+const key = await keys.issue({
+  tenantId: ctx.request.subject.tenantId,
+  name: 'CI deploy',
+  createdBy: ctx.request.subject.id,   // who minted it
+  onBehalfOf: null,                    // an ORG key: acts as no person
+  metadata: { teamId: 'team_7' },      // your axis
+})
+```
+
+It comes straight back on resolve, so a guard needs no second query:
+
+```ts
+const resolved = await keys.verify(token)
+resolved?.metadata   // { teamId: 'team_7' }
+```
+
+It survives `rotate` — a rotated key is the same credential with a new secret,
+so dropping it would silently de-authorize every rotated key. And it reaches the
+Subject as `metadata`, alongside the framework's own claims.
+
+**It is app data, never identity.** The strategy merges your bag UNDER its own
+claims: `provider`, and the acting `userId`, are written afterwards from
+`onBehalfOf` and always win — including when the answer is "none". A bag that
+could set `userId` would let whoever minted a key choose who the request is.
+
+Before this slot existed, an app with a team axis could authenticate through the
+built-in strategy and still not authorize, so `apiKeys: true` was unusable for
+it. The alternatives people reached for were a second table joined on every auth
+check, or `team:<id>` smuggled into `scopes` — where `hasScope` then sees a scope
+that is not a scope.
+
+## Two strategies, one prefix
+
+If your app already runs its own key strategy on a prefix and you then enable
+`apiKeys: true`, both claim the same shape. The chain is first-match-wins, so the
+first one decides the Subject — and if they resolve to different authority,
+*which strategy answered* decides whether authorization works.
+
+`voltro dev` / `voltro serve` warn at boot when this happens. Give them distinct
+prefixes (`apiKeys: { prefix: 'vk_' }`) or drop one.
+
 ## Security model
 
 - **Hash-only storage.** A DB dump never exposes a usable key — only `sha256(token)`. Lose a token → rotate it (`rotate` revokes the old + issues a fresh one with the same scopes).

package/templates/agent-docs/data.md

@@ -691,6 +691,14 @@ column — and required otherwise. `upsertRow`'s `conflictColumns` are constrain
 to the table's own columns, so a typo is a compile error too. The string-keyed
 `ctx.store.insert` / `upsert` still work unchanged; the typed seam is opt-in.
 
+> **If you adopt it, check your tooling for the old spelling.** `insertRow`
+> replaces `store.insert('<tableName>', …)`, so anything that matches on that
+> string stops matching — a lint rule, a codemod, an architecture test. One team
+> had a test asserting every mutation writes an audit log; it matched
+> `store.insert('auditLogs'`, and migrating to `insertRow` silently blinded it.
+> Green suite, gap reintroduced. Grep for the old spelling before you migrate,
+> not after.
+
 ## Partial updates: `ctx.store.applyDefined`
 
 A partial-update mutation should set only the fields the caller actually sent — not overwrite an omitted field with `undefined`. Instead of hand-writing `if (input.x !== undefined) patch.x = input.x` per field, use `ctx.store.applyDefined(input, keys)`:
@@ -2099,6 +2107,37 @@ export default crud.list('articles', { columns: ['id', 'title', 'createdAt'] })
 
 **Trap:** an eager `include` branch joins on a foreign key, so a projection that omits that FK breaks the relation. Keep the FK in `columns` when you also pass `include`.
 
+### `scope` — keep per-subject narrowing when you adopt the helper
+
+`filter` builds the WHERE from the request; `scope` builds it from the **caller**:
+
+```ts
+crud.list('timeEntries', {
+  filter: (input) => ({ status: input.status }),      // what the caller ASKED for
+  scope:  (ctx)   => ({ ownerId: ctx.request.subject.id }),  // what it MAY SEE
+})
+```
+
+A WHERE built only from `input` can express *the rows the caller asked for*, never
+*the rows the caller may see*.
+
+`scope` is merged **last**, so a request field of the same name can never widen it —
+`?ownerId=someone-else` is simply overridden. That ordering is why the two are
+separate options rather than one: only one of them is a security boundary, and kept
+apart, *"does this list declare a `scope`?"* is a question a reviewer — or a future
+boot audit — can actually ask. Folded into `filter`, it becomes *"does this filter
+happen to read ctx somewhere in its body?"*, which nothing can check. Tenant scope still applies automatically; anything
+narrower — owner, team, role — does not. So replacing a hand-written handler that
+carried such a narrowing with `crud.list` **widens the result set, silently and
+without an error**. One app lost exactly that across eight list views.
+
+Use the same filter for `crud.count`, or the total contradicts the pages —
+"showing 10 of 4000" on a page holding ten rows.
+
+The reason this is an option rather than a reason to leave: hand-writing the query
+to get the narrowing also forfeits `serverOnly` stripping and the page-size clamp.
+A narrowing requirement should not cost you the safety rails.
+
 ## What they deliberately don't do — authorization
 
 A guard runs *before* the executor, so gating lives on the **descriptor**, not the handler — an executor cannot gate itself. Keep every write descriptor guarded: