@voltro/cli 0.33.0 → 0.35.0

package/templates/apps/api-status/queries/incidents.live.query.ts

@@ -1,20 +1,33 @@
-// The live incident feed — the heart of the status page. NO `guards:`, so an
-// anonymous visitor's browser can subscribe: `useSubscription('app',
+// The live incident feed — the heart of the status page. Deliberately OPEN, so
+// an anonymous visitor's browser can subscribe: `useSubscription('app',
 // 'incidents.live')`. Every insert/update to `incidents` lands as a delta, so a
 // newly-declared incident (or a resolve) shows up on every open status page
 // within seconds — no polling.
+//
+// This template is the clearest place in the library to see that `openAccess:`
+// and `guards:` are two spellings of the SAME obligation, not a strict option
+// and a lax one. The reads here are open on purpose; the four mutations beside
+// them carry `guards: [{ scope: 'status:write' }]` and are satisfiable through
+// the real role map in `authz.ts`. Both are decisions. What the framework
+// refuses to boot on is neither.
 import { defineQuery } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 export const incidentsLive = defineQuery({
   name: 'incidents.live',
+  openAccess:
+    'the public incident feed a status page exists to publish — title, impact, status and '
+    + 'timestamps of THIS operator\'s own incidents, nothing caller-derived and no personal '
+    + 'data. A status page that requires a login is useless during the outage it reports.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:         Schema.String,
-    title:      Schema.String,
-    impact:     Schema.String,
-    status:     Schema.String,
-    startedAt:  Schema.Date,
-    resolvedAt: Schema.NullOr(Schema.Date),
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:         Schema.String,
+      title:      Schema.String,
+      impact:     Schema.String,
+      status:     Schema.String,
+      startedAt:  Schema.Date,
+      resolvedAt: Schema.NullOr(Schema.Date),
+    }),
+  ),
 })

package/templates/apps/api-status/queries/updates.list.query.ts

@@ -1,17 +1,24 @@
-// Live feed of incident timeline entries. Public (no guard). The page joins
+// Live feed of incident timeline entries — public by design. The page joins
 // these to incidents by `incidentId` client-side to render each incident's
-// update history.
+// update history. `incidents.update`, which writes them, is
+// `status:write`-guarded.
 import { defineQuery } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 export const updatesList = defineQuery({
   name: 'updates.list',
+  openAccess:
+    'the public incident timeline a status page exists to publish — the operator\'s own '
+    + 'update posts, nothing caller-derived and no personal data. Posting one is '
+    + '`status:write`-guarded.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:         Schema.String,
-    incidentId: Schema.String,
-    body:       Schema.String,
-    status:     Schema.String,
-    createdAt:  Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:         Schema.String,
+      incidentId: Schema.String,
+      body:       Schema.String,
+      status:     Schema.String,
+      createdAt:  Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-status/tests/status.test.ts

@@ -54,10 +54,18 @@ describe('incidents.create — operator-gated', () => {
 })
 
 describe('incidents.live — reads are PUBLIC', () => {
-  it('an anonymous visitor may subscribe (no guard on the query)', async () => {
+  it('an anonymous visitor may subscribe — the query declares `openAccess`', async () => {
     const ctx = ctxFor(subjectFor(null, null, 'anonymous'))
     await expect(invoke(incidentsLive, incidentsLiveHandler, {}, ctx)).resolves.toBeDefined()
   })
+
+  it('…which is a DECISION, not an omission', () => {
+    // Before `openAccess` existed, "nobody decided" and "we decided it is open"
+    // were the same descriptor and a reviewer could not tell them apart. Assert
+    // the marker is present, or this suite would keep passing on a query whose
+    // guard someone deleted by accident.
+    expect(incidentsLive.openAccess).toBeTruthy()
+  })
 })
 
 describe('incidents.create — descriptor', () => {

package/templates/apps/api-versioning/actions/documents.asOf.action.ts

@@ -6,6 +6,18 @@ import { Schema } from 'effect'
 
 export const documentAsOf = defineAction({
   name: 'documents.asOf',
+  // Open, with the same load-bearing detail as `documents.history`: the
+  // executor passes `ctx.request.subject.tenantId` into `rowAsOf` explicitly,
+  // because a version table is not auto-scoped by the `tenant()` mixin. That
+  // argument is what keeps a caller-supplied id from reading another tenant's
+  // past values; do not drop it.
+  //
+  // No auth strategy and no rbac ship in this template, so a scope guard would
+  // deny every caller rather than the wrong ones.
+  openAccess:
+    'returns one past value of a document in the CALLER\'S OWN tenant — `rowAsOf` is passed '
+    + '`subject.tenantId` explicitly, so an id from another tenant returns null. Time travel '
+    + 'reaches only where the live read already could.',
   input: Schema.Struct({ id: Schema.String, at: Schema.Number }),
   output: Schema.NullOr(Schema.Struct({
     title: Schema.String,

package/templates/apps/api-versioning/actions/documents.history.action.ts

@@ -6,6 +6,19 @@ import { Schema } from 'effect'
 
 export const documentHistory = defineAction({
   name: 'documents.history',
+  // Open — and this one needs its bound named, because a version table is a
+  // second copy of your data that the `tenant()` mixin does NOT scope for you.
+  // The executor passes `ctx.request.subject.tenantId` to `rowHistory`
+  // explicitly, so a caller-supplied id from another tenant yields nothing.
+  // Read that as the load-bearing line it is: drop the argument and this
+  // becomes a cross-tenant read of every past value.
+  //
+  // No auth strategy and no rbac ship in this template, so a
+  // `guards: [{ scope: 'documents:history' }]` would deny every caller.
+  openAccess:
+    'lists past versions of a document in the CALLER\'S OWN tenant — `rowHistory` is passed '
+    + '`subject.tenantId` explicitly, so an id from another tenant returns nothing (a version '
+    + 'table is not auto-scoped by `tenant()`). No auth strategy ships here to guard against.',
   input: Schema.Struct({ id: Schema.String }),
   output: Schema.Array(Schema.Struct({
     version: Schema.Number,

package/templates/apps/api-versioning/mutations/documents.create.mutation.ts

@@ -8,6 +8,15 @@ import { Schema } from 'effect'
 export const createDocument = defineMutation({
   name: 'documents.create',
   target: { table: 'documents', op: 'insert' },
+  // Open: writes only the title + content the caller sent, into the request's
+  // tenant (`tenant()` auto-stamps `tenantId`), and touches no existing row.
+  // No auth strategy and no rbac ship in this template, so every caller is an
+  // anonymous Subject holding no scopes and a `guards: [{ scope }]` would deny
+  // all of them rather than the wrong ones.
+  openAccess:
+    'inserts a document built only from caller-supplied fields into the request\'s tenant; '
+    + 'reads nothing and modifies no existing row. No auth strategy ships here, so there is no '
+    + 'identity a scope guard could name.',
   input: Schema.Struct({
     title: Schema.NonEmptyString,
     content: Schema.String,

package/templates/apps/api-versioning/mutations/documents.update.mutation.ts

@@ -8,6 +8,18 @@ import { Schema } from 'effect'
 export const updateDocument = defineMutation({
   name: 'documents.update',
   target: { table: 'documents', op: 'update' },
+  // Open: `tenant()` scopes the update, so a caller-supplied `id` from another
+  // tenant matches no row. Nothing is destroyed either — the versioning plugin
+  // snapshots the previous value, so every edit is recoverable through
+  // `documents.history` / `documents.asOf`.
+  //
+  // History is an audit trail, not an access control: it tells you WHAT
+  // changed, never whether the change was allowed. No auth strategy or rbac
+  // ships here, so a `guards: [{ scope }]` would deny every caller.
+  openAccess:
+    'edits a document of the request\'s tenant (an id outside it matches no row); the previous '
+    + 'value is snapshotted, so nothing is destroyed. Version history records changes — it '
+    + 'does not authorize them.',
   input: Schema.Struct({
     id: Schema.String,
     content: Schema.String,

package/templates/apps/api-versioning/package.json

@@ -13,18 +13,19 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/plugin-versioning": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/plugin-versioning": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-webhooks/mutations/orders.fulfill.mutation.ts

@@ -4,6 +4,22 @@ import { Schema } from 'effect'
 export const fulfillOrder = defineMutation({
   name:   'orders.fulfill',
   target: { table: 'orders', op: 'insert' },
+  // Open — and unlike a plain insert, this one FANS OUT: on commit it emits
+  // `order.completed` to every subscribed target, so an unguarded call makes
+  // this server POST to third parties. Two things bound that today and both are
+  // checkable: the emit is post-commit (a rollback ships nothing), and the
+  // target list is empty until someone calls `ctx.webhooks.subscribe`, which is
+  // not reachable from this procedure.
+  //
+  // No auth strategy and no rbac ship in this template, so a
+  // `guards: [{ scope: 'orders:write' }]` would deny every caller instead of
+  // the wrong ones. Add an identity, then that guard — before real subscribers
+  // exist. (The INCOMING `orders` webhook is a different door with its own
+  // control: an HMAC signature over `<unix>.<rawBody>`, not this decision.)
+  openAccess:
+    'inserts an order from caller-supplied fields into the request\'s tenant, then emits '
+    + '`order.completed` post-commit. The emit reaches only targets someone registered via '
+    + '`ctx.webhooks.subscribe` — none by default — so guard this before subscribers exist.',
   input:  Schema.Struct({ sku: Schema.NonEmptyString, totalCents: Schema.Number }),
   output: Schema.Struct({
     id:         Schema.String,

package/templates/apps/api-webhooks/package.json

@@ -13,19 +13,20 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/plugin-webhooks": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-postgres": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/plugin-webhooks": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
+    "@voltro/sql-postgres": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-webhooks/queries/orders.list.query.ts

@@ -4,6 +4,16 @@ import { Schema } from 'effect'
 export const listOrders = defineQuery({
   name:   'orders.list',
   source: 'orders',
+  // Open: `tenant()` confines every delivery to the tenantId on the request, so
+  // one tenant's orders never reach another's subscription, and the rows carry
+  // only sku / amount / status — no customer identity. With no auth strategy
+  // configured that tenantId is the caller's own `x-tenant` header, and a
+  // `guards: [{ scope }]` would be unsatisfiable: an anonymous Subject holds no
+  // scopes, so the guard would deny 100% of traffic.
+  openAccess:
+    'lists the request tenant\'s own orders (sku, amount, status — no customer identity); '
+    + '`tenant()` scopes every delivery. No auth strategy ships here, so the tenant comes from '
+    + 'the caller\'s `x-tenant` header — add a strategy, then a `guards:`.',
   input:  Schema.Struct({}),
   output: Schema.Array(Schema.Struct({
     id:         Schema.String,

package/templates/apps/changelog/package.json

@@ -12,12 +12,12 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/changelog": "0.33.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@voltro/changelog": "0.35.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/i18n": "0.35.0",
+    "@voltro/web": "0.35.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -25,7 +25,9 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "tsx": "^4.22.4",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/edge-functions/package.json

@@ -12,8 +12,8 @@
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/serverless": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/serverless": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {

package/templates/apps/frontend-admin/package.json

@@ -12,21 +12,23 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.33.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/ui-shadcn": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@{{projectName}}/api": "0.35.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/i18n": "0.35.0",
+    "@voltro/ui-shadcn": "0.35.0",
+    "@voltro/web": "0.35.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.33.0",
+    "@voltro/devtools": "0.35.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/frontend-admin/src/lib/admin.ts

@@ -1,16 +1,27 @@
-// The scopes the admin gates its write actions on (via useCan). The admin
-// derives a CONVENTIONAL scope per entity action — `<table>:create`,
-// `<table>:write`, `<table>:delete` (see deriveEntityAdmins) — and hides any
-// action the current subject's scopes don't satisfy.
+// The scopes the admin judges its write affordances against.
 //
-// DEMO: we feed `admin:full` (the blanket-bypass scope) so the demo shows every
-// action. In a real app, REPLACE this with the current subject's scopes from
-// your session — e.g. a reactive query:
+// READ THIS BEFORE SWAPPING IT OUT — the shape changed, and the old shape had a
+// trap. The admin no longer invents a scope per entity (`<table>:create` and
+// friends). It reads each procedure's OWN declared access off the capability
+// map (`spec.create.guards` — the descriptor's `guards:` / `openAccess:`) and
+// decides with `useAccessDecision`. So these scopes are matched against what
+// your api really declares; a name that appears in neither place gates nothing.
+//
+// That is the whole fix. A UI gating on an invented convention hides every write
+// from every caller of every app that named its scopes differently — a total
+// outage of the affordance that reads like a working permission check, and that
+// a demo seeding `admin:full` can never surface.
+//
+// DEMO: we feed `admin:full` (the blanket-bypass scope) so the scaffold shows
+// every action on first boot. In a real app, REPLACE this with the current
+// subject's scopes from your session — e.g. a reactive query:
 //
 //   const { data } = useSubscription<{ scopes: string[] }>('app', 'auth.session')
 //   <PermissionProvider scopes={data?.scopes ?? []}>…</PermissionProvider>
 //
-// useCan reads these reactively, so the admin's affordances update the instant
+// useAccessDecision reads these reactively, so affordances update the instant
 // the subject's roles change. (This is UX gating, not enforcement — the api's
-// own permission() guards remain the real authorization boundary.)
+// own guards remain the real authorization boundary. A control shown while the
+// decision is `unknown` is deliberate: a per-row guard is the server's to
+// answer, and it answers with a typed ScopeError.)
 export const DEMO_SCOPES: ReadonlyArray<string> = ['admin:full']

package/templates/apps/frontend-admin/src/locales/de.ts

@@ -18,7 +18,7 @@ export default defineLocale<typeof en>()({
   'lang.label': 'Sprache',
 
   'landing.heading': 'Das Backoffice, für dich erledigt.',
-  'landing.body':    'Dieser Admin liest zur Laufzeit die <strong>Capability-Map</strong> deiner API und rendert eine live, reaktive <code>DataTable</code> + <code>AutoForm</code> für jede Entität, die sie freigibt — rechtegeprüft mit <code>useCan</code>, mit einer Herkunfts-Lade pro Zeile und universellem Undo/Redo. Richte ihn auf eine beliebige Voltro-API und er passt sich an; der Seiten-Code unter <code>src/pages/admin/</code> gehört dir zum Bearbeiten.',
+  'landing.body':    'Dieser Admin liest zur Laufzeit die <strong>Capability-Map</strong> deiner API und rendert eine live, reaktive <code>DataTable</code> + <code>AutoForm</code> für jede Entität, die sie freigibt — gegated auf den Zugriff, den jede Prozedur selbst deklariert, mit einer Herkunfts-Lade pro Zeile und universellem Undo/Redo. Richte ihn auf eine beliebige Voltro-API und er passt sich an; der Seiten-Code unter <code>src/pages/admin/</code> gehört dir zum Bearbeiten.',
   'landing.cta':     'Beim Admin anmelden →',
 
   'login.heading': 'Anmelden',
@@ -38,6 +38,7 @@ export default defineLocale<typeof en>()({
   'overview.reactiveSuffix': ' · reaktiv',
   'overview.readonly':       'schreibgeschützt',
   'overview.empty':          'Diese API stellt keine Benutzer-Entitäten bereit.',
+  'overview.serverOnly':     '{count, plural, one {# reine Server-Spalte, ausgeblendet} other {# reine Server-Spalten, ausgeblendet}}',
 
   'entity.create':  'Erstellen',
   'entity.addLabel': '{table} hinzufügen',
@@ -48,6 +49,15 @@ export default defineLocale<typeof en>()({
   'entity.delete':  'Löschen',
   'entity.unknown': 'Keine Entität <code>{entity}</code> in der Capability-Map dieser API.',
 
+  'entity.requires':          'erfordert {scopes}',
+  'entity.openAccess':        'offener Zugriff — {reason}',
+  'entity.accessUndeclared':  'keine Zugriffsentscheidung deklariert',
+  'entity.accessUnknown':     'Diese API prüft die Berechtigung pro Zeile, das kann nur sie beantworten. Das Bedienelement wird angezeigt; die API entscheidet beim Absenden.',
+
+  'entity.serverOnly':   '{count, plural, one {# reine Server-Spalte verlässt} other {# reine Server-Spalten verlassen}} die API nie und {count, plural, one {kann} other {können}} nicht übermittelt werden: {names}',
+  'entity.sensitive':    'Personenbezogene Daten — in Exporten maskiert: {names}',
+  'entity.notEditable':  'Kein einzelner Primärschlüssel, daher lassen sich Zeilen nicht zum Bearbeiten oder Löschen adressieren. Nur Liste.',
+
   'prov.title':       'Herkunft · <code>{table}</code> #{id}',
   'prov.close':       'schließen',
   'prov.loading':     'lädt…',

package/templates/apps/frontend-admin/src/locales/en.ts

@@ -24,7 +24,7 @@ export default defineCatalog({
 
   // ---- Public landing ((marketing)/index.tsx) ----
   'landing.heading': 'The back-office, done for you.',
-  'landing.body':    'This admin reads your api’s <strong>capability map</strong> at runtime and renders a live, reactive <code>DataTable</code> + <code>AutoForm</code> for every entity it exposes — permission-gated with <code>useCan</code>, with a per-row provenance drawer and universal undo/redo. Point it at any Voltro api and it adapts; the page code under <code>src/pages/admin/</code> is yours to edit.',
+  'landing.body':    'This admin reads your api’s <strong>capability map</strong> at runtime and renders a live, reactive <code>DataTable</code> + <code>AutoForm</code> for every entity it exposes — gated on the access each procedure itself declares, with a per-row provenance drawer and universal undo/redo. Point it at any Voltro api and it adapts; the page code under <code>src/pages/admin/</code> is yours to edit.',
   'landing.cta':     'Sign in to the admin →',
 
   // ---- Public sign-in ((marketing)/login.tsx) ----
@@ -47,6 +47,7 @@ export default defineCatalog({
   'overview.reactiveSuffix': ' · reactive',
   'overview.readonly':       'read-only',
   'overview.empty':          'No user entities exposed by this api.',
+  'overview.serverOnly':     '{count, plural, one {# server-only column, hidden} other {# server-only columns, hidden}}',
 
   // ---- Per-entity CRUD (admin/[entity].tsx) ----
   'entity.create':  'Create',
@@ -58,6 +59,17 @@ export default defineCatalog({
   'entity.delete':  'Delete',
   'entity.unknown': 'No entity <code>{entity}</code> in this api’s capability map.',
 
+  // ---- Declared access, shown rather than guessed (admin/[entity].tsx) ----
+  'entity.requires':          'requires {scopes}',
+  'entity.openAccess':        'open access — {reason}',
+  'entity.accessUndeclared':  'no access decision declared',
+  'entity.accessUnknown':     'This api checks permission per row, so only it can answer. The control is shown; the api decides when you submit.',
+
+  // ---- Exposure axes, straight from the schema (admin/[entity].tsx) ----
+  'entity.serverOnly':   '{count, plural, one {# server-only column} other {# server-only columns}} never leave the api and cannot be submitted: {names}',
+  'entity.sensitive':    'Personal data — masked in exports: {names}',
+  'entity.notEditable':  'No single primary key, so rows can’t be addressed for edit or delete. List only.',
+
   // ---- Provenance drawer (admin/[entity].tsx) ----
   'prov.title':       'Provenance · <code>{table}</code> #{id}',
   'prov.close':       'close',

package/templates/apps/frontend-admin/src/pages/admin/[entity]/page.tsx

@@ -1,22 +1,36 @@
 // Per-entity CRUD — URL `/admin/<entity>`. Everything here is DISCOVERED:
 // useCapabilityManifest → deriveEntityAdmins gives this entity's list query +
-// create/update/delete mutation tags + the columns. We bind the shipped
-// schema-driven components to those tags:
-//   - <DataTable api="app" query={listTag}/>  — live, reactive rows
-//   - <AutoForm  api="app" mutation={createTag}/> — fields from the input schema
-// Writes are gated by useCan on the conventional `<table>:create|delete` scopes;
-// each row has a provenance ("why is this here?") drawer (08) + delete; the
-// layout's undo bar reverts the last change (00/09). Edit this file freely — it's
-// your template code, not a sealed runtime feature.
+// create/update/delete actions + the columns. We bind the shipped schema-driven
+// components to those tags:
+//   - <DataTable api="app" query={spec.list.tag}/>      — live, reactive rows
+//   - <AutoForm  api="app" mutation={spec.create.tag}/> — fields from the input schema
+//
+// WRITES ARE GATED ON THE ACCESS THE API DECLARES, not on a scope string this
+// page invented. `spec.create.guards` is the procedure's own `guards:` /
+// `openAccess:`, straight off the capability map, so this gate and the server's
+// check read the same data and cannot drift.
+//
+// The decision is THREE-valued, and `unknown` is SHOWN, not hidden: a guard with
+// a `resource` extractor is answered per ROW by the server, and a browser
+// holding only global scopes cannot pre-compute it. Hiding those would empty the
+// admin for exactly the multi-tenant apps whose subjects carry no global scopes.
+// The server stays the authorization boundary and answers a typed ScopeError.
+//
+// Each row has a provenance ("why is this here?") drawer (08) + delete; the
+// layout's undo bar reverts the last change (00/09). Edit this file freely —
+// it's your template code, not a sealed runtime feature.
 import { useState, type ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
 import { useParams, AutoForm, DataTable } from '@voltro/web'
 import {
   useCapabilityManifest,
   deriveEntityAdmins,
-  useCan,
+  useAccessDecision,
+  requiredScopes,
+  openAccessReason,
   useMutation,
   useProvenance,
+  type EntityAction,
   type EntityAdminSpec,
 } from '@voltro/client'
 import { T, useTFn } from '@voltro/i18n'
@@ -55,23 +69,36 @@ const ProvenanceDrawer = ({ table, id, onClose }: { readonly table: string; read
   )
 }
 
+// What the api requires for this action, in words — so an operator who hits a
+// ScopeError can read the scope they are missing instead of guessing at it.
+const AccessNote = ({ action }: { readonly action: EntityAction }): ReactNode => {
+  const reason = openAccessReason(action.guards)
+  const scopes = requiredScopes(action.guards)
+  if (reason !== undefined) return <span className="meta"><T id="entity.openAccess" values={{ reason }} /></span>
+  if (scopes.length > 0) return <span className="meta"><T id="entity.requires" values={{ scopes: scopes.join(', ') }} /></span>
+  return <span className="meta"><T id="entity.accessUndeclared" /></span>
+}
+
 // The bound CRUD surface for one entity. A child component so its hooks
-// (useCan/useMutation) get the real spec, never undefined.
+// (useAccessDecision/useMutation) get the real spec, never undefined.
 const EntityAdmin = ({ spec }: { readonly spec: EntityAdminSpec }): ReactNode => {
   const [sel, setSel] = useState<string | null>(null)
   const t = useTFn()
-  const canCreate = useCan(spec.createScope)
-  const canDelete = useCan(spec.deleteScope)
-  // Always-called; the tag is only used when deleteTag exists (gated below).
-  const del = useMutation<{ id: string }>('app', spec.deleteTag ?? '__voltro.noop')
+  const create = useAccessDecision(spec.create.guards)
+  const remove = useAccessDecision(spec.delete.guards)
+  // Always-called; the tag is only used when spec.delete.tag exists (gated below).
+  const del = useMutation<Record<string, string>>('app', spec.delete.tag ?? '__voltro.noop')
+  // The column the api keys rows on — NOT a hard-coded `id`. A table keyed on
+  // anything else would otherwise get an empty id sent on every delete.
+  const pk = spec.pkColumn ?? 'id'
 
   const rowActions = (row: Row): ReactNode => {
-    const id = String(row['id'] ?? '')
+    const id = String(row[pk] ?? '')
     return (
       <span className="row-actions">
         <button type="button" className="btn ghost" onClick={() => setSel(id)}><T id="entity.why" /></button>
-        {spec.deleteTag && canDelete && id ? (
-          <button type="button" className="btn danger" onClick={() => void del.mutate({ id })}><T id="entity.delete" /></button>
+        {spec.delete.tag && spec.editable && remove !== 'denied' && id ? (
+          <button type="button" className="btn danger" onClick={() => void del.mutate({ [pk]: id })}><T id="entity.delete" /></button>
         ) : null}
       </span>
     )
@@ -81,17 +108,33 @@ const EntityAdmin = ({ spec }: { readonly spec: EntityAdminSpec }): ReactNode =>
     <section>
       <h1>{spec.table}</h1>
 
-      {spec.createTag && canCreate ? (
+      {/* `.serverOnly()` columns are absent from `spec.columns` by construction —
+          they never cross the wire, and the runtime REFUSES a mutation input that
+          sets one. Saying so beats a silently shorter column list. */}
+      {spec.serverOnlyColumns.length > 0 ? (
+        <p className="meta">
+          <T id="entity.serverOnly" values={{ count: spec.serverOnlyColumns.length, names: spec.serverOnlyColumns.join(', ') }} />
+        </p>
+      ) : null}
+      {spec.sensitiveColumns.length > 0 ? (
+        <p className="meta">
+          <T id="entity.sensitive" values={{ names: spec.sensitiveColumns.join(', ') }} />
+        </p>
+      ) : null}
+      {!spec.editable ? <p className="meta"><T id="entity.notEditable" /></p> : null}
+
+      {spec.create.tag && create !== 'denied' ? (
         <div className="section">
-          <h2><T id="entity.create" /></h2>
-          <AutoForm api="app" mutation={spec.createTag} submitLabel={t('entity.addLabel', { table: spec.table })} />
+          <h2><T id="entity.create" /> <AccessNote action={spec.create} /></h2>
+          {create === 'unknown' ? <p className="muted"><T id="entity.accessUnknown" /></p> : null}
+          <AutoForm api="app" mutation={spec.create.tag} submitLabel={t('entity.addLabel', { table: spec.table })} />
         </div>
       ) : null}
 
       <div className="section">
         <h2><T id="entity.rows" /></h2>
-        {spec.listTag ? (
-          <DataTable api="app" query={spec.listTag} rowActions={rowActions} emptyText={t('entity.empty', { table: spec.table })} />
+        {spec.list.tag ? (
+          <DataTable api="app" query={spec.list.tag} rowActions={rowActions} emptyText={t('entity.empty', { table: spec.table })} />
         ) : (
           <p className="muted"><T id="entity.noList" /></p>
         )}