@voltro/cli 0.33.0 → 0.35.0

package/templates/agent-docs/templates/apibackends.md

@@ -43,6 +43,8 @@ No actions, workflows, agents, or `AGENTS.md` ship — this template is delibera
 
 Every query / mutation / action is **two files paired by basename**: a browser-safe descriptor (`*.query.ts` / `*.mutation.ts`) holding `defineQuery` / `defineMutation`, and a server-only executor (`*.query.server.ts` / `*.mutation.server.ts`) with a default export. The framework pairs them at boot. The descriptor file must never import `node:*` / database / runtime modules — it's what the web client pulls through codegen.
 
+**Every descriptor also declares an access decision** — `guards: [{ scope }]` or `openAccess: '<why>'`, or the app refuses to boot (`security.defaultDeny`). Both procedures here are `openAccess` with the reason in the file, and the reason is a real claim rather than the word "demo": `tenant()` confines every delivery to the request's tenant, but this template configures no auth strategy, so that tenant comes from the caller's own `x-tenant` header — it shapes the result, it does not authorize the caller. A `guards: [{ scope }]` would be *unsatisfiable* here: with no auth strategy and no rbac, every caller resolves to an anonymous Subject holding no scopes, so the guard would deny 100% of traffic — an outage, not security. Add an identity (see [`api-auth`](/docs/templates/api-auth) / [`api-rbac`](/docs/templates/api-rbac)), then swap the line for a `guards:` in the same change. **Your own new procedure files need one of these three from the first save.**
+
 ### Query — `queries/notes.query.ts` + `.server.ts`
 
 ```ts
@@ -52,6 +54,10 @@ import { Schema } from 'effect'
 
 export const listNotes = defineQuery({
   name: 'notes.list',
+  openAccess:
+    'lists notes for the request\'s tenant only (`tenant()` scopes every delivery). No auth '
+    + 'strategy ships in this template, so that tenant comes from the caller\'s own `x-tenant` '
+    + 'header — result shaping, not access control. Add a strategy, then a `guards:`.',
   input: Schema.Struct({}),
   output: Schema.Struct({
     id: Schema.String, title: Schema.String, body: Schema.String,
@@ -86,6 +92,10 @@ import { Schema } from 'effect'
 
 export const createNote = defineMutation({
   name: 'notes.create',
+  openAccess:
+    'inserts a note carrying only what the caller sent, into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch). No auth strategy ships in this template, so '
+    + 'there is no identity a scope guard could name.',
   target: { table: 'notes', op: 'insert',
     shape: (input: { tenantId: string; title: string; body: string }) => ({
       title: input.title, body: input.body, done: false,
@@ -465,8 +475,10 @@ S3_ACCESS_KEY_ID=minioadmin
 S3_SECRET_ACCESS_KEY=minioadmin
 S3_FORCE_PATH_STYLE=1
 
-# Auth — HMAC key for signed sessions (REQUIRED in production)
-VOLTRO_SESSION_SECRET=dev-only-change-me
+# Auth — the HMAC key for signed sessions is NOT set here. `voltro dev` mints
+# a unique per-project value into a gitignored `.env.local` on first boot
+# (`envVar.secret({ generate: 'base64url' })`). In production the variable
+# must come from your secret store; a missing one is a boot failure on purpose.
 
 # Cluster (K8s, >1 replica) — advertise a routable host so a workflow
 # can resume on another pod. Inject POD_IP via the downward API in prod.
@@ -606,6 +618,10 @@ import { Schema } from 'effect'
 
 export const placeOrder = defineMutation({
   name: 'orders.place',
+  openAccess:
+    'inserts an order built only from caller-supplied fields into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch); reads nothing and modifies no existing row. '
+    + 'No auth strategy ships here, so there is no identity a scope guard could name.',
   // Auto-optimistic: every query whose `source: 'orders'` matches gets a
   // placeholder row prepended; the server delta replaces it on commit.
   target: {
@@ -809,6 +825,11 @@ import { Schema } from 'effect'
 
 export const approveOrder = defineMutation({
   name: 'orders.approve',
+  openAccess:
+    'injects the approval signal into the caller\'s own tenant\'s parked fulfilment run — the '
+    + 'executionId is derived from `{ orderId, tenantId }` and `assertOwnTenant` rejects a '
+    + 'mismatch, so no other tenant\'s run is addressable. It still decides whether an order '
+    + 'ships: the first procedure here to grow an `orders:approve` guard once an identity exists.',
   input: Schema.Struct({
     orderId:  Schema.String,
     tenantId: Schema.String,
@@ -1059,7 +1080,7 @@ apps/acme/api/                          # dir named by the app, not the template
 │   └── searchDocs.tool.tsx             # retrieval tool — nearestNeighbours over docs
 ├── actions/
 │   ├── summarize.action.ts             # descriptor — browser-safe
-│   └── summarize.action.server.tsx     # executor — generateObject structured output
+│   └── summarize.action.server.ts      # executor — generateObject structured output
 └── seeds/
     └── docs.seed.ts                    # boot seed of sample docs (auto-embedded on insert)
 ```
@@ -1192,7 +1213,7 @@ export default async (
 
 Because `docs` carries `vectorEmbedding()`, the STRING overload of `nearestNeighbours(query, k)` is valid — the runtime embeds `query` before searching. Any failure (no AI key, embed error) is caught and returns `[]`, so a tool hiccup surfaces to the model as "no results" instead of aborting the whole agent turn.
 
-## The structured-output action — `actions/summarize.action.ts` + `.server.tsx`
+## The structured-output action — `actions/summarize.action.ts` + `.server.ts`
 
 AI inference is external I/O, so it's an **action**, not a mutation. This one uses `generateObject` to take free-text and produce STRUCTURED output — a typed `{ title, summary, keyPoints, sentiment }` object instead of prose. The `output` Schema is exported from the descriptor so the executor can reuse the SAME schema to constrain the model: one source of truth for both the wire output and the shape the model must satisfy.
 
@@ -1214,6 +1235,9 @@ export type SummaryResult = Schema.Schema.Type<typeof SummaryResult>
 
 export const summarize = defineAction({
   name:  'support.summarize',
+  openAccess:
+    'summarises caller-supplied text; reads no table and no other caller\'s data. '
+    + 'Metered by the AI provider, so rate-limit and guard it before it is public.',
   input: Schema.Struct({
     // The raw text to summarise (a support thread, a doc, a transcript).
     text: Schema.String,
@@ -1223,7 +1247,7 @@ export const summarize = defineAction({
 ```
 
 ```ts
-// summarize.action.server.tsx — EXECUTOR (server-only)
+// summarize.action.server.ts — EXECUTOR (server-only)
 import { Effect } from 'effect'
 import { generateObject } from '@voltro/ai'
 import { SummaryResult } from './summarize.action'
@@ -1538,6 +1562,10 @@ const Book = Schema.Struct({
 export const authorsWithBooks = defineQuery({
   name:   'authors.withBooks',
   source: ['authors', 'books'],
+  openAccess:
+    'streams the seeded demo catalogue (authors + their books) for the request\'s tenant; the '
+    + 'seed holds no personal data. `bio` is `.encrypted()` and still crosses the wire on '
+    + 'purpose — encryption at rest is not an exposure marker; `.serverOnly()` is.',
   input:  Schema.Struct({}),
   output: Schema.Struct({
     id: Schema.String, name: Schema.String,
@@ -1631,14 +1659,17 @@ export default {
 
 **Where the key actually comes from is the load-bearing detail.** `governancePlugin({ fieldEncryption: true })` resolves the AES-256-GCM key through the **Secrets-Resolver** — i.e. the process environment — NOT through a `defineEnv` `default`. A `defineEnv` default would satisfy the boot validation gate while the cipher still failed to resolve a key. That's why the env declaration above deliberately has no `default`, and the template instead ships a `.env` carrying a **DEV-ONLY** placeholder so `voltro dev` boots out of the box:
 
-```bash
-# .env — DEV-ONLY. `voltro dev` loads this into process.env at boot, BEFORE
-# the env-validation gate and BEFORE plugins activate, which is how the
-# governance plugin's cipher resolves its key from the Secrets-Resolver.
-VOLTRO_FIELD_ENCRYPTION_KEY=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff
+```ts
+// The key is OURS to invent, so declare it as minted. `voltro dev` writes a
+// unique per-project value into a gitignored `.env.local` before the env gate
+// runs — so the cipher resolves a key that exists nowhere else, and no key
+// value is ever committed or shipped.
+VOLTRO_FIELD_ENCRYPTION_KEY: envVar.secret({ generate: 'hex' }),
 ```
 
-> **Before production**, replace this placeholder with a real key (`openssl rand -hex 32`) and move it into your deployment's secret store — never ship the shipped value. **Lose the key → lose the data** (GCM fails closed, never silent corruption); **rotating it** makes every existing `.encrypted()` value unreadable.
+> **Minting is dev-only.** `serve` / `build` / `start` have no such step: in production a missing key must remain a boot failure, and the value belongs in your deployment's secret store. **Lose the key → lose the data** (GCM fails closed, never silent corruption); **rotating it** makes every existing `.encrypted()` value unreadable.
+>
+> Never write a key value into a shipped file — not even an obviously-fake one. A placeholder in a template is a signing key published to everyone who downloads it, and a 64-hex placeholder passes every length check and appears on no blocklist.
 
 See [Field encryption](/docs/plugins/governance) and the [columns reference](/docs/database/columns).
 
@@ -1654,6 +1685,10 @@ import { Schema } from 'effect'
 export const searchBooks = defineQuery({
   name:   'books.search',
   source: 'books',
+  openAccess:
+    'full-text search over the seeded demo book catalogue, tenant-scoped; the seed holds no '
+    + 'personal data. The result cache is `scope: \'subject\'`, so an open read still cannot '
+    + 'serve one caller a snapshot built for another.',
   input:  Schema.Struct({ q: Schema.String }),
   output: Schema.Struct({
     id: Schema.String, authorId: Schema.String, title: Schema.String,
@@ -2182,7 +2217,7 @@ expect(row.tenantId).toBe('acme')   // tenant() stamped it — the REAL store, i
 voltro test
 ```
 
-The package also ships `MockClock` / `MockEmail` / `mockAi` / `makeWorkflowRunner` and `runDialectParity` (the `@voltro/testing/dialect` subpath).
+The package also ships `MockClock` / `mockAi` / `makeTestApp` / `defineFactory` / `makeWorkflowRunner` and `runDialectParity` (the `@voltro/testing/dialect` subpath). Mail is asserted through the mail plugin's own memory provider, not a mock — see [Unit testing → plugin services](/docs/testing/unit-testing#plugin-services-mail-storage-your-own).
 
 ## Going to production
 
@@ -2403,6 +2438,8 @@ curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json
 
 The plugin synthesizes the `search.query` rpc — input `{ index, q, limit?, filters? }`, output the matching docs. Because the index spec set `tenantField: 'tenantId'`, the query auto-filters to the caller's tenant: a request resolved to tenant `acme` only ever sees `acme` docs, even though every tenant's docs share one index. Searching the same term as a different tenant returns nothing.
 
+**`search.query` is a SEPARATE surface with its own access decision, made by the plugin.** The boot gate that requires `guards:` / `openAccess:` / `internal: true` reads only the procedures *you* wrote — a plugin's are the plugin author's call and you cannot edit them. So the two files this template ships, `queries/articles.list.query.ts` and `mutations/articles.create.mutation.ts`, each carry their own `openAccess:` with the reason in the file (the rows are the template's own seeded demo articles; no auth strategy ships here, so a scope guard would deny every caller). Anything you add beside them needs one of the three from the first save, or the app will not boot. See [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 ## Backfill existing rows
 
 The change tap covers writes AFTER boot. `startup/searchBackfill.startup.tsx` seeds the index from rows already in the table — the demo seed's articles, or every row after a restart or a switch to a new engine. It uses the same `searchBackend` instance, so the docs it writes are exactly what `search.query` reads:
@@ -2429,15 +2466,28 @@ const { results, run, pending } = useSearch('articles')
 
 The `/web` subpath imports nothing server-only — it's just a query over the `search.query` rpc, browser-safe.
 
-## Going to production — one line
+## Going to production — one line, and it is not optional
 
-`memoryBackend()` is in-process: great for dev, single-instance only. For real deployments swap it in `lib/search.ts` for a vendor engine — the indexing + query + backfill code is identical:
+`memoryBackend()` is in-process: great for dev, and **under
+`NODE_ENV=production` it refuses to boot** (`SearchBackendNotDurable`). This
+template ships it because it needs zero infrastructure to run locally — it is
+not a deployable default, and a deploy that keeps it does not start. Swap it in
+`lib/search.ts` for a vendor engine; the indexing + query + backfill code is
+identical:
 
 ```ts
 import { typesenseBackend } from '@voltro/plugin-search'         // or meilisearch / algolia
 export const searchBackend = typesenseBackend({ url: process.env.TYPESENSE_URL!, apiKey: process.env.TYPESENSE_KEY! })
 ```
 
+**Single-instance is not the exception it sounds like.** The heap-resident index
+is empty after every restart and deploy, so a genuinely one-process app searches
+nothing until something re-seeds it. If that is your deployment and a
+`*.startup.tsx` really does call `backfillIndex` for every index, declare it —
+`searchPlugin({ singleProcessMemoryIndex: true, indexes })` — and the plugin
+will hold you to both halves, warning if a peer replica ever announces itself.
+Full reasoning: [the memory backend refuses to boot in production](/docs/plugins/search#the-memory-backend-refuses-to-boot-in-production).
+
 ## When to use api-search vs. the other backends
 
 | You want… | Pick |
@@ -2981,7 +3031,7 @@ Compose the full lifecycle: `users.with(audit(), softDelete(), deactivation())`.
 
 _Data governance in one plugin with @voltro/plugin-governance — AES-256-GCM field encryption for .encrypted() columns (handler sees plaintext, ciphertext at rest), admin-gated GDPR governance.export/erase over declared subjectScopes, a consent ledger, and retention TTL sweeps. Memory store, zero infra._
 
-Four compliance primitives, one plugin. `@voltro/plugin-governance` gives you **field encryption** (AES-256-GCM for `.encrypted()` columns — handlers see plaintext, the column holds `enc:v1:…` at rest), **GDPR** export/erase (admin-gated, walking declared subject scopes), a **consent ledger**, and **retention** sweeps (delete/anonymise rows past a TTL). The template boots zero-infra with a dev encryption key. Template id: **`api-governance`**.
+Four compliance primitives, one plugin. `@voltro/plugin-governance` gives you **field encryption** (AES-256-GCM for `.encrypted()` columns — handlers see plaintext, the column holds `enc:v1:…` at rest), **GDPR** export/erase (admin-gated, walking declared subject scopes), a **consent ledger**, and **retention** sweeps (delete/anonymise rows past a TTL). The template boots zero-infra on a key `voltro dev` mints for your project — no key ships with it. Template id: **`api-governance`**.
 
 ## Scaffold
 
@@ -2989,7 +3039,7 @@ Four compliance primitives, one plugin. `@voltro/plugin-governance` gives you **
 voltro create-project acme --api=api-governance
 ```
 
-The shipped `.env` carries a DEV `VOLTRO_FIELD_ENCRYPTION_KEY`. Generate your own (`openssl rand -hex 32`) and keep it in a secret store for production.
+**No encryption key ships with this template** — a key committed to a template is a key published to everyone who downloads it. `VOLTRO_FIELD_ENCRYPTION_KEY` is declared with `generate: 'hex'`, so `voltro dev` mints a unique one into a gitignored `.env.local` on first boot. Your deployment mints its own: `voltro secret generate field-encryption`.
 
 ## Field encryption
 
@@ -2997,7 +3047,8 @@ The shipped `.env` carries a DEV `VOLTRO_FIELD_ENCRYPTION_KEY`. Generate your ow
 // database/schema.ts
 export const profiles = table('profiles', {
   id: id(), name: text(), email: text(),
-  ssn: text().encrypted(),         // AES-256-GCM at rest
+  // TWO markers, two different questions — say both when you mean both.
+  ssn: text().encrypted().serverOnly(),   // encrypted AT REST · and may never leave the server
 }).with(audit())
 
 // app.config.ts
@@ -3006,12 +3057,16 @@ governancePlugin({ fieldEncryption: true /* reads VOLTRO_FIELD_ENCRYPTION_KEY */
 
 You pass plaintext; the store middleware encrypts on write and decrypts on read — handlers never touch the ciphertext. Boot **fails loud** if an `.encrypted()` column exists but no cipher is registered.
 
+**`.encrypted()` is not an exposure marker**, and reading it as one is a tempting category error: the runtime decrypts for the handler, so an encrypted column reaches a client exactly like any other unless it is *also* `.serverOnly()`. That is why the column above carries both, and why `profiles.get` returns the last four digits it derived server-side — proof the cipher ran, without publishing the value.
+
 ```bash
 ID=$(curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
   -d '{"tag":"profiles.create","input":{"name":"Ada","email":"ada@acme.com","ssn":"123-45-6789"}}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["result"]["id"])')
 curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' \
   -d "{\"tag\":\"profiles.get\",\"input\":{\"id\":\"$ID\"}}"
-# → { ok:true, result:{ …, ssn:"123-45-6789" } }   (plaintext — the column stored enc:v1:…)
+# → { ok:true, result:{ …, ssnLast4:"6789" } }
+#   The handler read "123-45-6789" as plaintext (the cipher decrypted it) and
+#   published four digits, because the column is also `.serverOnly()`.
 ```
 
 ## GDPR, consent, retention
@@ -3032,6 +3087,8 @@ governancePlugin({
 
 - **Don't encrypt what you filter on.** An `.encrypted()` column is ciphertext on disk — no `WHERE` / `ORDER BY` in SQL. Encrypt fields you read back WHOLE (PII, tokens, notes).
 - **The key is everything.** GCM fails closed on a bad key — you get an error, never silent corruption. Back the key up; rotating it means re-encrypting.
+- **Three orthogonal markers, three questions.** `.encrypted()` = encrypted at rest · `.serverOnly()` = may it leave the server at all · `.sensitive()`/`.safe()` = may it appear in a `voltro data export`. Using one to answer another's question is the mistake.
+- **Every procedure declares an access decision.** `guards: [{ scope }]` or `openAccess: '<why>'`, or the app refuses to boot (`security.defaultDeny`). Both procedures here are `openAccess` with the reason in the file: the template configures no auth strategy and no rbac, so every caller resolves to an anonymous Subject holding no scopes and a scope guard would deny 100% of traffic — an outage, not security. Add an identity (see [`api-auth`](/docs/templates/api-auth) / [`api-rbac`](/docs/templates/api-rbac)), then the guard.
 - **GDPR endpoints are admin-only by design.** Don't remove the `admin:full` gate — an unauthenticated export/erase is a data-exfiltration / griefing hole.
 
 
@@ -3132,6 +3189,10 @@ import { Schema } from 'effect'
 
 export const syncPull = defineAction({
   name: 'sync.pull',
+  openAccess:
+    'advances the request tenant\'s own sync watermark; every KV key is namespaced by that '
+    + 'tenant and the rows land in a `tenant()` table. The upstream is a local pure generator '
+    + '— no network call, no credential.',
   input: Schema.Struct({
     limit: Schema.optional(Schema.Int.pipe(Schema.greaterThan(0))),
   }),
@@ -3378,6 +3439,10 @@ import { Schema } from 'effect'
 export const setDocumentBody = defineMutation({
   name: 'documents.setBody',
   target: { table: 'documents', op: 'update' },
+  openAccess:
+    'merges a caller-supplied CRDT update into a document of the request\'s tenant — a merge, '
+    + 'not an overwrite, so no concurrent editor\'s text is lost, and an id outside the tenant '
+    + 'matches no row. Guard who may edit once the app has an identity.',
   input: Schema.Struct({
     id: Schema.NonEmptyString,
     update: Schema.Uint8ArrayFromBase64,
@@ -3424,6 +3489,10 @@ import { Schema } from 'effect'
 
 export const listDocuments = defineQuery({
   name: 'documents.list',
+  openAccess:
+    'streams the documents of the request\'s tenant, CRDT body included (`tenant()` scopes '
+    + 'every delivery). No auth strategy ships here, so the tenant comes from the caller\'s own '
+    + '`x-tenant` header — add a strategy, then a `guards:`.',
   input: Schema.Struct({}),
   output: Schema.Struct({
     id: Schema.String,

package/templates/agent-docs/templates/appshells.md

@@ -1986,37 +1986,53 @@ import { useCapabilityManifest, deriveEntityAdmins } from '@voltro/client'
 
 const { manifest } = useCapabilityManifest('app')   // one-shot fetch of the capability map
 const entities = manifest ? deriveEntityAdmins(manifest) : []
-// each entity: { table, columns, listTag?, createTag?, updateTag?, deleteTag?, createScope, writeScope, deleteScope }
+// each entity: { table, columns, serverOnlyColumns, sensitiveColumns, reactive,
+//                pkColumn?, editable, list, create, update, delete }
+// each of list/create/update/delete: { tag?, guards? }
 ```
 
-`deriveEntityAdmins` joins each user table to the procedures that actually serve it — the query whose `source` is the table (→ the list `<DataTable>`), the mutations whose `target` is `{table, op}` (→ create/edit/delete). So the admin binds only to procedures that **exist**; it never guesses tags by naming convention.
+`deriveEntityAdmins` joins each user table to the procedures that actually serve it — the query whose `source` is the table (→ the list `<DataTable>`), the mutations whose `target` is `{table, op}` (→ create/edit/delete) — and carries each one's **declared access**. So the admin binds only to procedures that **exist**, and gates only on permissions the api really declares; it never guesses either by naming convention.
 
 ## Per-entity CRUD
 
 ```tsx
 // src/pages/admin/[entity]/page.tsx (abridged)
-const canCreate = useCan(spec.createScope)         // <table>:create
-{spec.createTag && canCreate ? (
-  <AutoForm api="app" mutation={spec.createTag} submitLabel={`Add ${spec.table}`} />
+const create = useAccessDecision(spec.create.guards)   // the procedure's OWN guards
+{spec.create.tag && create !== 'denied' ? (
+  <AutoForm api="app" mutation={spec.create.tag} submitLabel={`Add ${spec.table}`} />
 ) : null}
 
-{spec.listTag ? (
-  <DataTable api="app" query={spec.listTag} rowActions={rowActions} />
+{spec.list.tag ? (
+  <DataTable api="app" query={spec.list.tag} rowActions={rowActions} />
 ) : null}
 ```
 
-The list is a **live subscription** — a create from the form (or anyone, in another tab) appears without a refetch. Each row's actions include a delete (gated by `useCan(spec.deleteScope)`, run via `useMutation(spec.deleteTag)`) and a **provenance** drawer (`useProvenance`) answering "why is this row here?".
+The list is a **live subscription** — a create from the form (or anyone, in another tab) appears without a refetch. Each row's actions include a delete (keyed on `spec.pkColumn`, gated by `useAccessDecision(spec.delete.guards)`, run via `useMutation(spec.delete.tag)`) and a **provenance** drawer (`useProvenance`) answering "why is this row here?".
 
-## Permission gating
+## Permission gating — from the api's own declaration
 
-Write affordances are hidden via `useCan` on conventional per-entity scopes (`<table>:create`, `<table>:delete`). `<PermissionProvider>` in the admin layout feeds the current subject's scopes; the demo seeds `admin:full` (bypass) — **swap it for your session's real scopes**:
+Each action carries `guards`: the procedure's `guards:` / `openAccess:` declaration, straight off the capability map. `useAccessDecision` judges it against the scopes `<PermissionProvider>` supplies, so the UI gate and the server check read the **same data** and cannot drift. The demo seeds `admin:full` (bypass) — **swap it for your session's real scopes**:
 
 ```tsx
 const { data } = useSubscription<{ scopes: string[] }>('app', 'auth.session')
 <PermissionProvider scopes={data?.scopes ?? []}>…</PermissionProvider>
 ```
 
-This is UX gating, not enforcement — the api's own `permission()` guards remain the real authorization boundary. Row-level field visibility (vs. action-level) is a future step.
+**The decision is three-valued.** `allowed` and `denied` are what they sound like; `unknown` means only the server can answer — a guard carrying a `resource` extractor is checked per **row**, and a browser holding global scopes cannot pre-compute it. The admin **shows** those controls and lets the api reply with a typed `ScopeError`. Hiding them would empty the back-office for exactly the multi-tenant apps whose subjects are minted with no global scopes at all.
+
+This is still UX gating, not enforcement — the api's own guards remain the real authorization boundary.
+
+## The three exposure axes
+
+The columns come from your schema, and the admin honours each marker differently — they are orthogonal, and substituting one for another leaks or hides data:
+
+| Marker | Admin behaviour |
+|---|---|
+| `.serverOnly()` | **Never rendered and never submitted.** It is absent from `spec.columns`; the page names it from `serverOnlyColumns` so the omission is visible rather than silent. The runtime refuses it as mutation input anyway (`assertNoServerOnlyInput`) — this is the same rule one layer earlier. |
+| `.encrypted()` | **Shown and editable.** At-rest encryption is not wire exposure; your procedures read it decrypted. |
+| `.sensitive(class)` | **Shown**, and listed in `sensitiveColumns` so a bulk export masks it. |
+
+Rows are keyed on `spec.pkColumn`, not a hard-coded `id`. A table with no single primary key reports `editable: false` and renders list-only.
 
 ## Undo / redo
 
@@ -2057,9 +2073,11 @@ Everything under `src/pages/admin/` is yours. Swap the cookie gate (`lib/auth.ts
 
 ## Anti-patterns
 
-- **Shipping the demo `admin:full` scopes to production.** That bypasses every `useCan` gate. Feed the subject's real scopes to `<PermissionProvider>`.
-- **Treating `useCan` as authorization.** It hides buttons; the server's `permission()` guard is the real gate. A hidden action is still callable over rpc by a crafted client.
-- **Assuming a naming convention.** The admin binds to discovered tags, not `<table>.create`-style guesses — so it works even when your procedures are named differently.
+- **Shipping the demo `admin:full` scopes to production.** That bypasses every gate. Feed the subject's real scopes to `<PermissionProvider>`.
+- **Treating the UI decision as authorization.** It hides buttons; the server's guards are the real gate. A hidden action is still callable over rpc by a crafted client.
+- **Assuming a naming convention — for tags *or* for scopes.** The admin binds to discovered tags and gates on discovered guards. A UI that invents `<table>:create` hides every write from every app that named its scope anything else: a total outage of the affordance that looks like a working permission check, and that a demo seeding `admin:full` can never surface.
+- **Collapsing `unknown` into `denied`.** That is the same outage by another route — it is the answer for every per-resource guard, which is the whole multi-tenant case.
+- **Hiding a column because it is `.encrypted()`.** Encryption-at-rest is not wire exposure. `.serverOnly()` is the only one of the three axes that means "do not render this".
 
 
 

package/templates/agent-docs/templates/overview.md

@@ -1,6 +1,6 @@
 # Templates
 
-> Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call.
+> Dozens of dogfooded starter templates ship with the framework — backend shapes, frontend shapes, a serverless function library, and an Expo mobile app. voltro list-templates is the authority; scaffold any of them with one CLI call.
 
 
 
@@ -9,11 +9,16 @@
 <!-- source: en/templates/overview.md -->
 ## Overview
 
-_Thirty-eight dogfooded starter templates ship with the framework — twenty-two backend shapes, fourteen frontend shapes, a serverless function library, and an Expo mobile app. Scaffold any of them with one CLI call._
+_Dozens of dogfooded starter templates ship with the framework — backend shapes, frontend shapes, a serverless function library, and an Expo mobile app. voltro list-templates is the authority; scaffold any of them with one CLI call._
 
-Voltro ships **thirty-eight** starter templates across the **four kinds** you actually deploy: **twenty-two** backends (`api-*`), **fourteen** frontends (`frontend-*` plus `changelog`), **one** serverless library (`edge-functions`), and **one** Expo mobile app (`mobile-app`). Each is a small, opinionated, dogfooded reference you scaffold once and then own — no update channel, no lock-in.
+Voltro ships **dozens** of starter templates across the **four kinds** you actually deploy: backends (`api-*`), frontends (`frontend-*` plus `changelog`), a serverless library (`edge-functions`), and an Expo mobile app (`mobile-app`). Each is a small, opinionated, dogfooded reference you scaffold once and then own — no update channel, no lock-in.
 
-The CLI loads templates by walking `voltro-templates/apps/<id>/`; the directory name IS the template id you pass to `--api` / `--web` / `--template`. Run `voltro list-templates` to see them live.
+**`voltro list-templates` is the authority, not this page.** It prints the
+templates your installed CLI actually ships; the tables below cover the ones
+worth a paragraph of explanation, and several ids exist that have no entry here.
+If an id appears in the command's output and not below, it exists and works.
+
+The CLI loads templates by walking `voltro-templates/apps/<id>/`; the directory name IS the template id you pass to `--api` / `--web` / `--template`.
 
 ```bash
 # A project with a backend + a blank frontend:
@@ -27,7 +32,7 @@ Each app gets its own port from the project's `portRange`, wired through `pnpm d
 
 ## Backend templates (`--api=<id>`)
 
-The four `api-backend*` shapes share the same minimal `notes` domain and differ only in the plugin/store wired on top. The other three are **feature showcases** — a cohesive domain that exercises one whole slice of the framework end to end.
+The `api-backend*` shapes share the same minimal `notes` domain and differ only in the plugin/store wired on top. The rest are **feature showcases** — each a cohesive domain that exercises one whole slice of the framework end to end.
 
 | Template | Best for |
 |---|---|
@@ -54,11 +59,11 @@ The four `api-backend*` shapes share the same minimal `notes` domain and differ
 | [`api-governance`](/docs/templates/api-governance) | **Field encryption + GDPR + consent + retention** — `@voltro/plugin-governance`: AES-256-GCM `.encrypted()` columns (plaintext to handlers, ciphertext at rest), admin-gated `governance.export`/`erase`, a consent ledger, retention sweeps. |
 | [`api-collab`](/docs/templates/api-collab) | **Local-first / CRDT collaborative editing** — a `documents` table with a `crdtText()` `body`; concurrent edits from many clients CONVERGE via an authoritative server-side merge on the write path (no last-write-wins loser), then broadcast over the reactive engine. Zero-infra; pairs with `frontend-collab`. |
 
-All twenty-two are `kind: 'api'`.
+Every one of these is `kind: 'api'` — and `voltro list-templates` lists more `api-*` ids than the table above covers.
 
 ## Frontend templates (`--web=<id>`)
 
-Fourteen web shapes spanning every render mode — `static`, `spa`, `ssr`, `isr`, selective `islands` hydration — plus the reactive fullstack loop (and its local-first / CRDT variant).
+Web shapes spanning every render mode — `static`, `spa`, `ssr`, `isr`, selective `islands` hydration — plus the reactive fullstack loop (and its local-first / CRDT variant).
 
 **Every frontend template is bilingual (en/de) out of the box**, with the i18n strategy matched to its render mode: the hydrated/SSR shells use cookie i18n (`<LocaleSwitcher>`), the static/islands sites use URL-prefix i18n (`/de/…`, one pre-rendered HTML file per locale). `frontend-i18n` remains the dedicated URL-prefix reference. See [URL strategies](/docs/i18n/url-strategies) for why render mode decides.
 
@@ -79,7 +84,7 @@ Fourteen web shapes spanning every render mode — `static`, `spa`, `ssr`, `isr`
 | [`frontend-ssr-api`](/docs/templates/ssr-api) | `ssr` · fed by api | **SSR from your backend** — an `ssr` loader calls `query('notes.list', {})` over the sibling api's POST /rpc, so real rows are in the first paint + `<title>`; `useSubscription` upgrades to live. Pairs with `api-backend`. |
 | [`frontend-contact`](/docs/templates/contact) | `static` + serverless | **Static page + a serverless email form** — the headline "static frontend, serverless backend" combo. The page ships to a CDN; the function scales to zero. |
 
-All fourteen are `kind: 'web'`. The CLI rejects an api template passed to `--web` (and vice-versa) on a kind mismatch.
+Every one of these is `kind: 'web'`, and again there are more `web` ids than rows here. The CLI rejects an api template passed to `--web` (and vice-versa) on a kind mismatch.
 
 ## Serverless template (`--template=<id>` via `add-app`)