@voltro/cli 0.5.0 → 0.6.0

package/dist/serveEntry.js

@@ -1,4 +1,4 @@
-import { Nt as e, at as t } from "./dev-B71ICpXJ.js";
+import { Lt as e, lt as t } from "./dev-Bjq-nIvH.js";
 import { a as n } from "./startupRunner-DhlX9nqd.js";
-import { t as r } from "./serveCommand-C0WFA396.js";
+import { t as r } from "./serveCommand-C-XQ89NJ.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -31,6 +31,11 @@
       "import": "./dist/inspectState.js",
       "default": "./dist/inspectState.js"
     },
+    "./devActivity": {
+      "types": "./dist/devActivity.d.ts",
+      "import": "./dist/devActivity.js",
+      "default": "./dist/devActivity.js"
+    },
     "./startup": {
       "types": "./dist/startup.d.ts",
       "import": "./dist/startup.js",
@@ -52,22 +57,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.5.0",
-    "@voltro/cache": "0.5.0",
-    "@voltro/data-transfer": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/kv": "0.5.0",
-    "@voltro/logger": "0.5.0",
-    "@voltro/plugin-auth": "0.5.0",
-    "@voltro/plugin-broadcast": "0.5.0",
-    "@voltro/plugin-mail": "0.5.0",
-    "@voltro/plugin-storage": "0.5.0",
-    "@voltro/plugin-webhooks": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
-    "@voltro/serverless": "0.5.0",
-    "@voltro/workflow": "0.5.0",
+    "@voltro/ai": "0.6.0",
+    "@voltro/cache": "0.6.0",
+    "@voltro/data-transfer": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/kv": "0.6.0",
+    "@voltro/logger": "0.6.0",
+    "@voltro/plugin-auth": "0.6.0",
+    "@voltro/plugin-broadcast": "0.6.0",
+    "@voltro/plugin-mail": "0.6.0",
+    "@voltro/plugin-storage": "0.6.0",
+    "@voltro/plugin-webhooks": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
+    "@voltro/serverless": "0.6.0",
+    "@voltro/workflow": "0.6.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "ts-morph": "^28.0.0"

package/templates/AGENTS.core.md

@@ -126,6 +126,14 @@ line below replaces something real apps write by hand hundreds of times.
    delivery happens after commit, with backoff and a dead-letter. Do NOT call
    the remote from the mutation (not transactional), and do not hand-build a
    deliveries table + drain cron — that IS this primitive.
+11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+   grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
+   `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
+   the encrypted per-user token store, the OAuth authorize/callback pair,
+   refresh-before-use, and the `useConnection` + `<ConnectAccount>` connect UI.
+   The credential is bound to the REQUEST's subject — there is no parameter for
+   another subject. Do NOT hand-build a per-user token table, an OAuth action
+   pair, or a "credentials resolver" over your own schema.
 
 | You're about to write | Reach for instead |
 |---|---|
@@ -139,11 +147,13 @@ line below replaces something real apps write by hand hundreds of times.
 | hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
 | a loop issuing one `store.query` per node of a walk | `ctx.load` / `ctx.loadMany` |
 | a deliveries table + drain cron + retry worker | `ctx.outbox.enqueue` + `defineOutboxHandler` |
+| a per-user `integrationTokens` table + OAuth actions + a refresh check | `defineConnection` + `ctx.connections.get(id)` |
 | `row['name'] as string` on every field you read | nothing — `ctx.store.query(database.t….descriptor)` already returns the table's row type. A cast here means the descriptor was hand-built, or you are casting out of habit |
 
 Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
 **`database/querying.md`** (relations + `.with`), **`authentication.md`**
-(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`).
+(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`),
+**`data.md`** (`defineConnection`, the credentials vault).
 
 ### Pick the CLIENT primitive (decision rubric)
 
@@ -264,6 +274,31 @@ export default { type: 'web' as const, name: 'myWeb',
 Env, secrets, auth strategies, layers, plugins config → **`configuration.md`**.
 `store: 'memory'` loses data on restart — default to `postgres` for real work.
 
+**NEVER hardcode a secret, not even as a fallback.** Not
+`process.env.X ?? 'dev-only-change-me'`, not a value committed to `.env`. A
+hardcoded fallback means every environment that forgot to configure the
+variable shares one key that is readable by anyone with the repo — and it looks
+completely healthy until someone forges a session. Declare it instead:
+
+```ts
+env: defineEnv({
+  VOLTRO_SESSION_SECRET: envVar.secret({ generate: 'base64url' }),  // ours → minted
+  STRIPE_SECRET_KEY:     envVar.secret({ minLength: 20 }),          // theirs → must be set
+})
+```
+
+`generate` makes `voltro dev` mint a unique per-project value into a gitignored
+`.env.local` on first boot, so local development needs no placeholder at all.
+Omit it for third-party credentials — an invented API key authenticates nobody,
+and failing the boot gate is the useful outcome. Deployment values come from
+`voltro secret generate <purpose>`; `voltro serve` refuses to start without them.
+
+Also: don't read `process.env` for a secret at config time to pass it to a
+plugin. `app.config.ts` is evaluated BEFORE the env gate and before minting, so
+that read is what pushes you into writing a fallback. `authRoutesPlugin` and
+`voltroPasswordStrategy` resolve `VOLTRO_SESSION_SECRET` themselves — omit
+`secret:` entirely.
+
 ## The browser/server boundary (load-bearing — verify when you touch it)
 
 Codegen pulls every **descriptor** (`*.query.ts` / `*.mutation.ts` /

package/templates/AGENTS.md

@@ -126,6 +126,14 @@ line below replaces something real apps write by hand hundreds of times.
    delivery happens after commit, with backoff and a dead-letter. Do NOT call
    the remote from the mutation (not transactional), and do not hand-build a
    deliveries table + drain cron — that IS this primitive.
+11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+   grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
+   `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
+   the encrypted per-user token store, the OAuth authorize/callback pair,
+   refresh-before-use, and the `useConnection` + `<ConnectAccount>` connect UI.
+   The credential is bound to the REQUEST's subject — there is no parameter for
+   another subject. Do NOT hand-build a per-user token table, an OAuth action
+   pair, or a "credentials resolver" over your own schema.
 
 | You're about to write | Reach for instead |
 |---|---|
@@ -139,11 +147,13 @@ line below replaces something real apps write by hand hundreds of times.
 | hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
 | a loop issuing one `store.query` per node of a walk | `ctx.load` / `ctx.loadMany` |
 | a deliveries table + drain cron + retry worker | `ctx.outbox.enqueue` + `defineOutboxHandler` |
+| a per-user `integrationTokens` table + OAuth actions + a refresh check | `defineConnection` + `ctx.connections.get(id)` |
 | `row['name'] as string` on every field you read | nothing — `ctx.store.query(database.t….descriptor)` already returns the table's row type. A cast here means the descriptor was hand-built, or you are casting out of habit |
 
 Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
 **`database/querying.md`** (relations + `.with`), **`authentication.md`**
-(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`).
+(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`),
+**`data.md`** (`defineConnection`, the credentials vault).
 
 ### Pick the CLIENT primitive (decision rubric)
 
@@ -264,6 +274,31 @@ export default { type: 'web' as const, name: 'myWeb',
 Env, secrets, auth strategies, layers, plugins config → **`configuration.md`**.
 `store: 'memory'` loses data on restart — default to `postgres` for real work.
 
+**NEVER hardcode a secret, not even as a fallback.** Not
+`process.env.X ?? 'dev-only-change-me'`, not a value committed to `.env`. A
+hardcoded fallback means every environment that forgot to configure the
+variable shares one key that is readable by anyone with the repo — and it looks
+completely healthy until someone forges a session. Declare it instead:
+
+```ts
+env: defineEnv({
+  VOLTRO_SESSION_SECRET: envVar.secret({ generate: 'base64url' }),  // ours → minted
+  STRIPE_SECRET_KEY:     envVar.secret({ minLength: 20 }),          // theirs → must be set
+})
+```
+
+`generate` makes `voltro dev` mint a unique per-project value into a gitignored
+`.env.local` on first boot, so local development needs no placeholder at all.
+Omit it for third-party credentials — an invented API key authenticates nobody,
+and failing the boot gate is the useful outcome. Deployment values come from
+`voltro secret generate <purpose>`; `voltro serve` refuses to start without them.
+
+Also: don't read `process.env` for a secret at config time to pass it to a
+plugin. `app.config.ts` is evaluated BEFORE the env gate and before minting, so
+that read is what pushes you into writing a fallback. `authRoutesPlugin` and
+`voltroPasswordStrategy` resolve `VOLTRO_SESSION_SECRET` themselves — omit
+`secret:` entirely.
+
 ## The browser/server boundary (load-bearing — verify when you touch it)
 
 Codegen pulls every **descriptor** (`*.query.ts` / `*.mutation.ts` /

package/templates/agent-docs/_manifest.json

@@ -17,7 +17,7 @@
       "group": null,
       "description": "How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol.",
       "path": "agent-docs/authentication.md",
-      "files": 11
+      "files": 12
     },
     {
       "id": "caching",
@@ -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": 14
+      "files": 15
     },
     {
       "id": "database/advancedqueries",
@@ -161,7 +161,7 @@
       "group": null,
       "description": "Voltro Cloud (coming soon) — the managed runtime for your Voltro project. Today the Free control plane registers + observes your self-hosted apps.",
       "path": "agent-docs/deployment.md",
-      "files": 6
+      "files": 7
     },
     {
       "id": "internationalization",

package/templates/agent-docs/ai.md

@@ -438,7 +438,18 @@ So one agent can run GPT-5.5 on a dedicated key while another inherits the env d
 **Model picker / routing** — the input selects among server-owned configs (UI picker, cost/size routing, plan tiers):
 
 ```tsx
-// descriptor: input: Schema.Struct({ prompt: Schema.String, tier: Schema.Literal('fast', 'smart') })
+// support.agent.tsx — DESCRIPTOR: the picker is constrained to server-known tiers
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({ prompt: Schema.String, tier: Schema.Literal('fast', 'smart') }),
+})
+
+// support.agent.server.tsx — EXECUTOR: map the tier onto server-owned configs
+import { defineAgentExecutor } from '@voltro/ai'
+
 export default defineAgentExecutor(support, {
   model: (input) => input.tier === 'smart'
     ? { name: 'openai', model: 'gpt-5.5' }
@@ -449,7 +460,18 @@ export default defineAgentExecutor(support, {
 **BYOK (bring your own key)** — the caller supplies their OWN key; you fold it into the returned config:
 
 ```tsx
-// descriptor: input: Schema.Struct({ prompt: Schema.String, apiKey: Schema.String })
+// support.agent.tsx — DESCRIPTOR: the caller's own key is part of the input
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({ prompt: Schema.String, apiKey: Schema.String }),
+})
+
+// support.agent.server.tsx — EXECUTOR: fold the caller's key into the config
+import { defineAgentExecutor } from '@voltro/ai'
+
 export default defineAgentExecutor(support, {
   model: (input) => ({ name: 'openai', model: 'gpt-5.5', apiKey: input.apiKey }),
 })
@@ -505,10 +527,20 @@ System prompts go in the agent definition's `system` field, NOT in the messages
 The `system` field lives on the **executor**. Template it with per-call values (locale, persona, plan-specific instructions) — the function receives the input typed from the descriptor's schema:
 
 ```tsx
+// support.agent.tsx — DESCRIPTOR: every field `system` reads must be declared here
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({ prompt: Schema.String, plan: Schema.optional(Schema.String) }),
+})
+
 // support.agent.server.tsx — `plan` comes from the descriptor's input schema
+import { defineAgentExecutor } from '@voltro/ai'
+
 export default defineAgentExecutor(support, {
   system: (input) => `You are speaking with a user on the ${input.plan ?? 'free'} plan.`,
-  // …
 })
 ```
 

package/templates/agent-docs/authentication.md

@@ -1771,6 +1771,12 @@ guards: [
 ]
 ```
 
+A guard answers **may you call this**. It cannot answer **which rows may you
+see** — a list has no single resource to name. For visibility that follows from a
+relationship ("tickets on teams I hold a role on"), declare a
+[row filter](/docs/authentication/row-level-security) instead; it AND-merges a
+subject-derived predicate into every read, so it narrows and never grants.
+
 ### Activate it: register a tuple source
 
 A relationship guard needs to read the caller's relations. That comes from the
@@ -1858,3 +1864,166 @@ Full API — including the batch `useResourceCans` for per-row gating — in
 `rebacPolicyGraph()` returns every resource type, its actions, the relations each
 grants, and the implication edges — the policy graph a dashboard or an AI agent
 reads to reason about authority without grepping the code.
+
+
+
+---
+
+<!-- source: en/authentication/row-level-security.md -->
+## Row-level security
+
+_setRowFilter — a subject-derived predicate AND-merged into every read, so relational visibility ("rows on teams I hold a role on") is declared once instead of hand-written into every list handler and every subscription._
+
+Reads already scope themselves by tenant and by soft-delete, and a descriptor's
+[`guards:`](/docs/authentication/authorization#enforce-it-declaratively-guards)
+decide whether you may call a procedure **at all**. Neither of those says which
+**rows** you may see.
+
+That gap matters as soon as visibility is *relational* — "tickets on teams I hold
+a role on". Without a row filter, that predicate has to be hand-written into
+every list handler and every subscription, and a filter you have to remember is a
+filter you only have to forget once.
+
+`setRowFilter` declares it once. The framework AND-merges the resulting predicate
+into every read.
+
+## The two phases
+
+```ts no-check
+setRowFilter({
+  load:      (subject) => Effect<Ctx>,                    // ASYNC, once per request
+  predicate: (ctx, table) => Predicate | undefined,       // PURE + SYNC, per read
+})
+```
+
+- **`load`** resolves everything the predicates need — the memberships, the role
+  rows, the project ids — **once per request**. It may read the store. This is
+  the expensive half.
+- **`predicate`** derives the filter for one table from what `load` already
+  fetched. It runs on **every read**, so it must be pure and synchronous. Return
+  `undefined` for a table this filter does not constrain — which is most tables.
+
+### Why two halves rather than one function
+
+A single async `(subject, table) => Promise<Predicate>` would be simpler to
+declare and much worse to run. Every read on the hot path would await, and the
+obvious implementation would re-query the membership tables **once per query** —
+so a handler that reads five tables pays five membership lookups.
+
+Splitting the phases makes the per-read cost a map lookup and makes the
+per-request cost explicit and visible: one load, reused.
+
+## A worked example
+
+The motivating shape — rows on teams the caller holds a role on:
+
+```ts no-check
+// apps/api/rls.startup.ts
+import { Effect } from 'effect'
+import { eq, inSet } from '@voltro/database'
+import { setRowFilter } from '@voltro/runtime'
+import { database } from './database/index'
+
+setRowFilter({
+  // ASYNC — once per request. Read your own tables here.
+  load: (subject) =>
+    Effect.promise(async () => {
+      const rows = await database.teamMembers
+        .where(eq('userId', subject.id ?? ''))
+        .all()
+      return rows.map((row) => row.teamId)
+    }),
+
+  // PURE + SYNC — runs on every read.
+  predicate: (teamIds: ReadonlyArray<string>, table: string) =>
+    table === 'tickets' ? inSet('teamId', teamIds) : undefined,
+})
+```
+
+Register it at boot — `app.config.ts` or a `*.startup.ts`. It is process-global
+and last-write-wins. `Ctx` is whatever your `load` returns; the framework never
+inspects it.
+
+With that registered, an ordinary list query needs no filter of its own:
+
+```ts no-check
+// apps/api/queries/tickets.list.query.server.ts
+export default () => database.tickets.orderBy('createdAt', 'desc')
+```
+
+A caller with no memberships gets zero rows. Nothing in the handler says so.
+
+## It can only narrow, never grant
+
+The predicate is **AND-merged** onto whatever the handler already asked for — it
+never replaces it. A row filter cannot widen a query, so it can never become an
+accidental grant:
+
+```ts no-check
+// the handler asks for one ticket; the filter still applies
+database.tickets.where(eq('id', 'ticket-42'))
+// → id = 'ticket-42' AND teamId IN (…the caller's teams)
+```
+
+## Both read paths are filtered
+
+The filter applies to descriptor reads **and** to the fluent builder. A filter
+present on only one read path is not a filter, it is a detour:
+
+```ts no-check
+await ctx.store.query(tickets.descriptor)   // filtered
+await ctx.store.select('tickets').all()     // filtered
+```
+
+## A failing `load` denies
+
+If `load` fails, every constrained read is **refused** rather than silently
+running unfiltered. A row filter that degrades to "no filter" under load failure
+is worse than no filter at all, because the system keeps serving and nothing
+looks wrong.
+
+The refusal is expressed as a predicate that matches nothing, not as an error —
+so a failure surfaces as an **empty result** rather than a 500 on every page. The
+underlying cause is reported separately, so it cannot pass unnoticed.
+
+## What does *not* bypass it
+
+| | Bypasses the row filter? |
+|---|---|
+| `.unscoped()` / `crossTenant` | **No** |
+| a `system` subject | Yes |
+
+`.unscoped()` and `crossTenant` exist for legitimate cross-tenant admin reads.
+They opt out of **tenant isolation**, not out of **authorization** — letting them
+also drop row visibility would turn an isolation opt-out into an authorization
+one, which is exactly the silent widening this feature exists to prevent.
+
+Only a `system` subject bypasses, because a system subject is the framework
+acting as itself — janitor sweeps, migrations, the scheduler — rather than on
+behalf of a user. That bypass is deliberately the narrow, explicit one.
+
+Apps that register no filter pay nothing.
+
+## Subscriptions re-resolve it
+
+A subscription is the one read path that stays open for hours, so it is the one
+where a stale filter would matter most. Before every delivery the runtime
+re-derives the read from the **unfiltered base descriptor** and re-applies the
+freshly resolved filter.
+
+A membership that ends mid-subscription therefore stops serving rows — the
+caller's open ticket list drops the rows they can no longer see, without a
+refresh and without the subscription having to be torn down.
+
+## Row filters vs. guards
+
+They answer different questions, and a complete policy usually wants both:
+
+| | Question | Failure |
+|---|---|---|
+| [`guards:`](/docs/authentication/authorization#enforce-it-declaratively-guards) | May you call this procedure? | typed `ScopeError`, before the executor runs |
+| `setRowFilter` | Which rows may you see? | the rows are simply absent |
+
+A guard is the right tool for "may this caller edit *this* ticket". A row filter
+is the right tool for "which tickets appear in the list at all" — a question a
+guard cannot answer, because there is no single resource to name.

package/templates/agent-docs/cli.md

@@ -765,12 +765,13 @@ It covers both halves of the stack:
 | Scope | It notices | Reach for |
 |---|---|---|
 | server | `if (!rows[0]) throw …` | `.one()` / `.first()` |
-| server | 3+ sequential `store.query` in one handler | `relations()` + `.with()` |
+| server | 3+ sequential `store.query` in one handler | `relations()` + `.with()` — or `Effect.all` |
 | server | `Effect.promise(() => ctx.store.…)` | `yield* EffectStore` |
 | server | `requireScope(...)` at the top of an executor | `guards:` on the descriptor |
 | server | a `token` / `secret` / `password` column with no encryption | `.encrypted()` |
 | server | a notify / webhook helper called at a mutation's tail | `defineSubscriber` / `defineReaction` |
 | server | `hasMore` + `limit + 1` | `paginateById` |
+| server | `.getTime()` / `.toISOString()` mapping a row on the way out | `rowSchema(table)` as the descriptor's `output` |
 | client | per-field `useState` + a submit flag | `useFormBinding` |
 | client | a table with local sort/filter state | `useDataTable` |
 | client | `FileReader` / `readAsDataURL` | `useUpload` |
@@ -783,6 +784,71 @@ The rules are deliberately conservative — a detector that cries wolf trains yo
 to ignore it. A column that already carries `.encrypted()`, or a handler that
 already uses `.one()`, stays silent.
 
+Two of them are worth spelling out, because their advice is not one-line:
+
+**The credential-column rule skips names that aren't credentials.** A name ending
+in `Id` / `_id`, a name ending in `Hash` / `_hash`, and a name beginning with
+`vault` are all left alone:
+
+| Column | Why it's skipped |
+|---|---|
+| `jiraSecretId`, `token_id` | an IDENTIFIER of a secret held elsewhere, not the secret |
+| `apiKeyHash`, `password_hash` | the hash IS the protection — encrypting it is nonsense, and it breaks the column as a unique lookup key |
+| `vaultToken` | a HANDLE into a secret store, naming a secret held elsewhere |
+
+The suffix tests use a camelCase / underscore boundary on purpose: a blind
+`/id$/i` would also swallow `apiKeyValid`, while `tokenIdentifier` — which ends
+in neither — must still fire.
+
+**The sequential-reads rule names TWO levers, and the criterion for choosing.**
+Both shapes chain later reads off earlier results, so no text-level heuristic can
+split them — you make the call:
+
+- The reads are a **parent → child walk on ONE key** → declare `relations()` in a
+  `*.relations.ts` and collapse them into `.with({ … })`: one JSON-aggregate
+  query, on every dialect.
+- The reads **collect ids from SEVERAL sources** (JSON-array references, a
+  junction carrying extra columns, JS-side sorting) → keep the assembly and run
+  the independent LEADING reads under `Effect.all`. Same queries, same results,
+  only concurrent — zero parity risk.
+
+The second case is the common one. Measured on a real 74-hit codebase, about two
+handlers were clean full-parity `relations()` conversions and the other ~72 were
+multi-source assemblies where `.with()` covers only part of the work or subtly
+changes behaviour. Prescribing `relations()` for all of them would be wrong ~97%
+of the time — and advice that is usually wrong trains you to ignore the finding.
+
+The human view shows the first three file paths per finding and says how many it
+withheld. Those paths are the actionable part — a count you cannot turn back
+into a work list tells you the size of the problem, not how to fix it — and the
+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:
+
+```bash
+voltro doctor . --json          # the complete scan: every file path, machine-readable
+```
+
+```json
+{
+  "root": "/app/api",
+  "scannedFiles": 214,
+  "scannedDirs": ["queries", "mutations", "database"],
+  "findings": [
+    {
+      "id": "row-not-found",
+      "scope": "server",
+      "smell": "hand-written not-found branch on rows[0]",
+      "use": ".one() — fails with the typed NoRowFound on zero rows AND on more than one",
+      "files": ["queries/team.get.ts", "queries/user.get.ts", "…"]
+    }
+  ]
+}
+```
+
+That is the form to hand an agent, or to pipe into a script that works the list
+file by file.
+
 ## `voltro capabilities` — what the framework actually exports
 
 Asked "what does this framework export", a language model will produce a

package/templates/agent-docs/configuration.md

@@ -91,6 +91,44 @@ build-time constant, still works.)
 | `envVar.boolean(opts)` | `boolean` | `true/1/yes/on` ↔ `false/0/no/off/""` |
 | `envVar.url(opts)` | `string` | validated with `URL` |
 | `envVar.enum([…] as const, opts)` | literal union | must be one of the values |
+| `envVar.secret(opts)` | `string` | server-only, required, length floor |
+
+### `envVar.secret` — for values that must not be guessable
+
+```ts
+env: defineEnv({
+  // Ours to invent → `voltro dev` mints one per project.
+  VOLTRO_SESSION_SECRET: envVar.secret({ generate: 'base64url' }),
+  // Someone else's to issue → must be fetched, never invented.
+  STRIPE_SECRET_KEY:     envVar.secret({ minLength: 20 }),
+})
+```
+
+It differs from `envVar.string({ access: 'secret' })` in three ways, each
+closing a specific failure:
+
+- **`access` is forced to `'secret'`** — a value with a length floor is never
+  something you meant to bundle into a browser.
+- **There is no `default`.** A default secret is not a secret: every
+  deployment that forgot to set the variable would share it.
+- **A length floor** (default 32). Presence alone does not catch the real
+  failure mode — a variable that is *set* but reads `change-me` signs forgeable
+  cookies while looking completely healthy.
+
+**`generate` opts a variable into per-project minting.** On first `voltro dev`,
+any declared-but-unset mintable secret is written to a gitignored `.env.local`
+and the boot continues. That is why no Voltro template ships a secret value: a
+placeholder in a template is a signing key published to everyone who downloads
+it, and it passes every check you could write.
+
+Leave `generate` off for anything a third party issues. A WorkOS API key is
+just as secret and just as required, but inventing one produces a value that
+merely *looks* right and authenticates nobody — better that the boot gate fails
+and a human fetches the real one.
+
+Minting is **development only**. `voltro serve`, `build` and `start` never mint:
+in production a missing secret is a boot failure, which is the whole point.
+Generate deployment values with `voltro secret generate <purpose>`.
 
 Every builder takes `{ access, optional?, default?, description?, example? }`.
 Use `default` for a fallback (the value type stays present, `A`); use