@voltro/cli 0.12.0 → 0.14.0

package/dist/startEntry.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.12.0",
+  "version": "0.14.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.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",
+    "@voltro/ai": "0.14.0",
+    "@voltro/cache": "0.14.0",
+    "@voltro/data-transfer": "0.14.0",
+    "@voltro/database": "0.14.0",
+    "@voltro/env": "0.14.0",
+    "@voltro/kv": "0.14.0",
+    "@voltro/logger": "0.14.0",
+    "@voltro/plugin-auth": "0.14.0",
+    "@voltro/plugin-broadcast": "0.14.0",
+    "@voltro/plugin-mail": "0.14.0",
+    "@voltro/plugin-storage": "0.14.0",
+    "@voltro/plugin-webhooks": "0.14.0",
+    "@voltro/protocol": "0.14.0",
+    "@voltro/runtime": "0.14.0",
+    "@voltro/serverless": "0.14.0",
+    "@voltro/workflow": "0.14.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -219,7 +219,7 @@ a `web/` (frontend).
 │   │   └── rpcGroup.generated.ts   # codegen — do NOT edit
 │   └── web/
 │       ├── app.config.ts       # { type:'web', apis, theme, locales, … }
-│       └── src/pages/**/*.tsx  # file-based routing
+│       └── src/pages/**/*.page.tsx  # file-based routing (only *.page.tsx)
 ├── packages/                   # shared libs
 └── AGENTS.md / CLAUDE.md       # this file
 ```
@@ -249,7 +249,77 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
-| `src/pages/**/*.tsx` | web page (file-based route) |
+| `*.page.tsx` (under `src/pages/`) | web page (file-based route) + `*.page.test.tsx` |
+| `*.component.tsx` | exactly ONE component (+ types) |
+| `*.component.ui.tsx` | presentational: one component, READS only — never writes |
+| `*.hook.ts` | exactly ONE `use*` hook (+ types) |
+| `*.types.ts` | types only — zero runtime exports |
+| `*.internal.ts` | only its own directory subtree may import it |
+| `*.fixture.ts` | test material — no production path may reach it |
+| `*.tracking.ts` | the ONLY place analytics may be called from |
+| `*.store.ts` | exactly ONE `defineStore` — client state, never server state |
+| `*.client.ts` | declares itself + its transitive imports browser-safe |
+
+**Only `*.page.tsx` is a route.** Everything else under `src/pages/` — components,
+hooks, tests — is ordinary code with no URL, so put it next to the page that uses
+it rather than in a distant `components/` directory. The suffix decides *whether*
+a file is a route; the path under `src/pages/` decides *which URL*. A `*.page.tsx`
+outside `src/pages/` never routes. A page MUST default-export its component —
+without it `voltro dev` refuses to boot and names the file.
+
+**Every suffix above is a CONTRACT, not a label.** Something else depends on each
+promise, and `voltro doctor` enforces all of them:
+
+- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
+  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
+  what lets a caller render it ten thousand times in a list, reuse it across
+  features, and prerender it without reading its source. Lift the write into the
+  owning `*.component.tsx` and pass a handler down.
+- `*.internal.ts` is the promise that refactoring inside that directory breaks
+  nobody. An import from another subtree revokes it.
+- `*.types.ts` having no runtime export is what makes importing it free and makes
+  it impossible for it to sit in a runtime import cycle.
+- `*.store.ts` holds ONE `defineStore`. Reads go through a selector
+  (`wizard.use((s) => s.step)`) — there is no whole-state read, because a
+  component holding all of it re-renders on every field. Scope a per-entity
+  instance with a KEY (`{ key: orderId }`), never a Provider. Seed it for SSR
+  from a loader with `seedStore(...)`; it rides the hydration payload the router
+  already writes. An action that writes SEVERAL fields wraps them in
+  `store.batch('label', () => …)` — one notification, one devtools entry, one
+  undo step, and a rollback if it throws; `await` first, then batch (an async
+  callback is an error). `{ persist: { key } }` survives a reload.
+  NEVER put server data in a store: a subscription is already
+  live, and a copy is not — the page then shows the stale one.
+- `*.tracking.ts` is where every `defineTracking(...)` spec lives — the event
+  catalogue, so "what do we send to third parties" is a file listing rather than
+  archaeology. A component wires one up with `useTracking(spec, props, sink)`; it
+  NAMES a spec, it never declares one. (`useTracking` is a hook, so it is not
+  confined — only the declaration is.)
+- Do NOT rename a file to `*.component.ui.tsx` just because it happens not to
+  write today. The suffix is a promise about what it MAY do.
+
+**These rules apply to code YOU write — never to vendored code.** A shadcn
+component (`npx shadcn add`) follows shadcn's conventions and is overwritten by
+the next `add`; renaming it breaks their convention and is undone next run. A
+directory is exempt when the app's `components.json` names it (`aliases.ui`) or
+it carries a `.voltro-vendored` file whose first line says where the code came
+from. Never add that marker to a directory of your own code — the point of the
+rules is that everything we author follows them.
+
+**Write the test in the same step as the code — always, for every primitive.**
+Not "afterwards", not in a cleanup pass: the filename is derivable
+(`users/[id].page.tsx` → `users/[id].page.test.tsx`,
+`Card.component.tsx` → `Card.component.test.tsx`,
+`order.mutation.server.ts` → `order.mutation.server.test.ts`), so there is
+nothing to decide. A change is not finished until its test exists and passes.
+
+Two traps worth naming, because a green run can hide both:
+
+- **`voltro test` transpiles without type-checking.** A type error in a TEST file
+  passes the suite and fails the package's `typecheck`. Run both.
+- **Never fake a service to make a test pass.** A test that only re-asserts its
+  own mock's return value is worse than no test — it reports coverage it does not
+  have. Assert the descriptor shape instead and cover the real path elsewhere.
 
 ## app.config.ts
 
@@ -344,9 +414,13 @@ declare it). Mixins compose via `.with(...)` and auto-stamp bookkeeping columns:
 ```ts
 export const todos = table('todos', { id: id(), title: text(), done: boolean().default(false) })
   .with(softDelete(), tenant())   // tenant() transitively requires audit()
-  .reactive()                     // opt into the matcher engine (subscriptions)
 ```
 
+- Every table is REACTIVE by default — nothing to opt into. `.nonReactive()`
+  turns reactivity OFF for a table entirely: no subscriber fires, locally or
+  across instances (the write still happens). Use it for a hot table nobody
+  subscribes to; never for one a query reads — that subscription never fires,
+  and `voltro dev` warns.
 - `id()` defaults to a branded **TypeID** (`todo_…`). Insert auto-injects it.
 - Indexes are **table-level** (`.index('name', [...])`) — there is NO
   column-level `.index()`. Declare `.index([...])` AFTER `.with(...)` to address

package/templates/AGENTS.md

@@ -219,7 +219,7 @@ a `web/` (frontend).
 │   │   └── rpcGroup.generated.ts   # codegen — do NOT edit
 │   └── web/
 │       ├── app.config.ts       # { type:'web', apis, theme, locales, … }
-│       └── src/pages/**/*.tsx  # file-based routing
+│       └── src/pages/**/*.page.tsx  # file-based routing (only *.page.tsx)
 ├── packages/                   # shared libs
 └── AGENTS.md / CLAUDE.md       # this file
 ```
@@ -249,7 +249,77 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
-| `src/pages/**/*.tsx` | web page (file-based route) |
+| `*.page.tsx` (under `src/pages/`) | web page (file-based route) + `*.page.test.tsx` |
+| `*.component.tsx` | exactly ONE component (+ types) |
+| `*.component.ui.tsx` | presentational: one component, READS only — never writes |
+| `*.hook.ts` | exactly ONE `use*` hook (+ types) |
+| `*.types.ts` | types only — zero runtime exports |
+| `*.internal.ts` | only its own directory subtree may import it |
+| `*.fixture.ts` | test material — no production path may reach it |
+| `*.tracking.ts` | the ONLY place analytics may be called from |
+| `*.store.ts` | exactly ONE `defineStore` — client state, never server state |
+| `*.client.ts` | declares itself + its transitive imports browser-safe |
+
+**Only `*.page.tsx` is a route.** Everything else under `src/pages/` — components,
+hooks, tests — is ordinary code with no URL, so put it next to the page that uses
+it rather than in a distant `components/` directory. The suffix decides *whether*
+a file is a route; the path under `src/pages/` decides *which URL*. A `*.page.tsx`
+outside `src/pages/` never routes. A page MUST default-export its component —
+without it `voltro dev` refuses to boot and names the file.
+
+**Every suffix above is a CONTRACT, not a label.** Something else depends on each
+promise, and `voltro doctor` enforces all of them:
+
+- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
+  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
+  what lets a caller render it ten thousand times in a list, reuse it across
+  features, and prerender it without reading its source. Lift the write into the
+  owning `*.component.tsx` and pass a handler down.
+- `*.internal.ts` is the promise that refactoring inside that directory breaks
+  nobody. An import from another subtree revokes it.
+- `*.types.ts` having no runtime export is what makes importing it free and makes
+  it impossible for it to sit in a runtime import cycle.
+- `*.store.ts` holds ONE `defineStore`. Reads go through a selector
+  (`wizard.use((s) => s.step)`) — there is no whole-state read, because a
+  component holding all of it re-renders on every field. Scope a per-entity
+  instance with a KEY (`{ key: orderId }`), never a Provider. Seed it for SSR
+  from a loader with `seedStore(...)`; it rides the hydration payload the router
+  already writes. An action that writes SEVERAL fields wraps them in
+  `store.batch('label', () => …)` — one notification, one devtools entry, one
+  undo step, and a rollback if it throws; `await` first, then batch (an async
+  callback is an error). `{ persist: { key } }` survives a reload.
+  NEVER put server data in a store: a subscription is already
+  live, and a copy is not — the page then shows the stale one.
+- `*.tracking.ts` is where every `defineTracking(...)` spec lives — the event
+  catalogue, so "what do we send to third parties" is a file listing rather than
+  archaeology. A component wires one up with `useTracking(spec, props, sink)`; it
+  NAMES a spec, it never declares one. (`useTracking` is a hook, so it is not
+  confined — only the declaration is.)
+- Do NOT rename a file to `*.component.ui.tsx` just because it happens not to
+  write today. The suffix is a promise about what it MAY do.
+
+**These rules apply to code YOU write — never to vendored code.** A shadcn
+component (`npx shadcn add`) follows shadcn's conventions and is overwritten by
+the next `add`; renaming it breaks their convention and is undone next run. A
+directory is exempt when the app's `components.json` names it (`aliases.ui`) or
+it carries a `.voltro-vendored` file whose first line says where the code came
+from. Never add that marker to a directory of your own code — the point of the
+rules is that everything we author follows them.
+
+**Write the test in the same step as the code — always, for every primitive.**
+Not "afterwards", not in a cleanup pass: the filename is derivable
+(`users/[id].page.tsx` → `users/[id].page.test.tsx`,
+`Card.component.tsx` → `Card.component.test.tsx`,
+`order.mutation.server.ts` → `order.mutation.server.test.ts`), so there is
+nothing to decide. A change is not finished until its test exists and passes.
+
+Two traps worth naming, because a green run can hide both:
+
+- **`voltro test` transpiles without type-checking.** A type error in a TEST file
+  passes the suite and fails the package's `typecheck`. Run both.
+- **Never fake a service to make a test pass.** A test that only re-asserts its
+  own mock's return value is worse than no test — it reports coverage it does not
+  have. Assert the descriptor shape instead and cover the real path elsewhere.
 
 ## app.config.ts
 
@@ -344,9 +414,13 @@ declare it). Mixins compose via `.with(...)` and auto-stamp bookkeeping columns:
 ```ts
 export const todos = table('todos', { id: id(), title: text(), done: boolean().default(false) })
   .with(softDelete(), tenant())   // tenant() transitively requires audit()
-  .reactive()                     // opt into the matcher engine (subscriptions)
 ```
 
+- Every table is REACTIVE by default — nothing to opt into. `.nonReactive()`
+  turns reactivity OFF for a table entirely: no subscriber fires, locally or
+  across instances (the write still happens). Use it for a hot table nobody
+  subscribes to; never for one a query reads — that subscription never fires,
+  and `voltro dev` warns.
 - `id()` defaults to a branded **TypeID** (`todo_…`). Insert auto-injects it.
 - Indexes are **table-level** (`.index('name', [...])`) — there is NO
   column-level `.index()`. Declare `.index([...])` AFTER `.with(...)` to address
@@ -452,7 +526,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. |
+| **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,7 +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. |
+| **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/_manifest.json

@@ -53,7 +53,7 @@
       "group": null,
       "description": "How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.",
       "path": "agent-docs/data.md",
-      "files": 16
+      "files": 17
     },
     {
       "id": "database/advancedqueries",
@@ -179,7 +179,7 @@
       "group": null,
       "description": "Scaffold a Voltro project and boot it locally in under a minute.",
       "path": "agent-docs/introduction.md",
-      "files": 5
+      "files": 6
     },
     {
       "id": "multi-tenancy",

package/templates/agent-docs/authentication.md

@@ -563,6 +563,45 @@ 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, { store }) => {
+      if (store === undefined) return []            // still booting — claim nothing
+      const role = await roleCache.get(subject.id, store)   // 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
+  …
+})
+```
+
+**You get the app's DataStore.** A role lives in the database, and without it the only way to reach one was a second connection path beside the framework's — to the same database the request store opens a moment later. It is the BOOT store, not a request-scoped one: strategies resolve before a request store exists, so it is `undefined` while the store is still being built. Return `[]` then rather than guessing.
+
+**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

@@ -154,6 +154,20 @@ 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.)
 
+`rbac/unenforced-scope` is the same registry read in the other direction: a
+scope a role GRANTS that no handler ever guards on. That direction has no
+artefact to inspect — you cannot grep for an authorization check that was never
+written, which is exactly why it survives review. One app modelled
+`api-keys:write` in its role catalogue, complete and reviewed, and no handler
+checked it: any member could mint a shared credential, and nothing failed.
+Tests pass when an authorization check is missing.
+
+It is a **warning**, because three innocent explanations exist: a plugin route
+enforces it internally (the graph cannot see inside a plugin), a REST route
+carries its own guards, or it is a UI-affordance scope that `useCan` reads to
+hide a button and no server check backs on purpose. All three are fine. Not
+knowing which is not.
+
 #### Declared vs OBSERVED — reconciled against reality
 
 A query's `source` and a mutation's `targets` are not documentation: the
@@ -163,7 +177,7 @@ nothing type-checks — the mutation succeeds, the write lands, and the wrong li
 fails to update.
 
 `voltro dev` records what each procedure ACTUALLY touched, into
-`app.graph.observed.json` (gitignored automatically). When that file is present,
+`app.graph.observed.generated.json` (gitignored automatically). When that file is present,
 `check` diffs it against the declarations:
 
 ```
@@ -447,6 +461,45 @@ _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.
+
+### What the boot tells you
+
+Three checks run at boot and print one line each when they have something to say
+— never fatal, and silent when the answer is fine:
+
+- **A reactive table with no change trigger** (postgres). The schema fingerprint
+  covers columns, not triggers, so a restored dump or a hand-run `DROP TRIGGER`
+  leaves the schema "up to date" and the subscription silently not reaching other
+  instances. The reverse is reported too: a `.nonReactive()` table still carrying
+  a trigger pays `REPLICA IDENTITY FULL` and a NOTIFY per write for nothing.
+- **A `.nonReactive()` table that a query reads.** That subscription will never
+  fire — first snapshot, then silence forever.
+- **`apiKeys: true` with no `apikeys:issue:*` scope declared.** The capability is
+  on and reachable by nobody; every issue request fails its guard.
+
+`voltro doctor` adds a fourth, over your source: an executor that writes
+`ctx.request.subject.id` while naming no guard, which is how an anonymous caller
+reaches a NOT NULL column and gets a raw statement failure instead of a typed
+refusal.
+
 ## `voltro dev <appDir>`
 
 ```bash
@@ -885,9 +938,31 @@ 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 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
 
@@ -1014,6 +1089,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
 ```
@@ -1064,8 +1172,8 @@ A page is listed when ALL of these hold:
 
 ```text
 •  renderMode:'spa' candidates (2 pages — loader-free, under a layout, currently ssr/default):
-   src/pages/dashboard/index.tsx  (/dashboard) — default renderMode
-   src/pages/admin/settings.tsx  (/admin/settings) — renderMode:'ssr'
+   src/pages/dashboard/index.page.tsx  (/dashboard) — default renderMode
+   src/pages/admin/settings.page.tsx  (/admin/settings) — renderMode:'ssr'
      → renderMode:'spa' skips this page's SSR compile while its layout shell still renders server-side — adopt it if the page BODY does not need SSR (internal/authenticated pages); keep 'ssr' if the page content needs SEO or server first-paint.
 ```
 

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).