@voltro/cli 0.27.0 → 0.29.0

package/templates/apps/api-saas-starter/app.config.ts

@@ -0,0 +1,87 @@
+// The SaaS backend for the {{projectName}} project — the WHOLE loop in one api.
+// Read by `voltro dev`.
+//
+// It composes two shipped plugins that are normally wired separately, plus a
+// small tenant-scoped domain (projects + invites), so that signup → paywall →
+// app works out of the box:
+//
+//   • @voltro/plugin-auth   — password sign-up/in/out over an HttpOnly session
+//     cookie, and a strategy that resolves that cookie into a typed `Subject`
+//     on every rpc/ws call (so handlers read `ctx.request.subject`).
+//   • @voltro/plugin-billing — subscriptions + ENTITLEMENTS over a pluggable
+//     provider. `plans` is the single source of tier→quota truth. The handlers
+//     call `requireEntitlement(...)`, which consumes the tenant's metered
+//     quota and fails typed `EntitlementExceeded` when it's exhausted — that
+//     typed failure IS the paywall signal the frontend upgrades on.
+//
+// The domain then ties them together: `projects.create` spends a `projects`
+// quota (free = 3), and `invites.create` spends a `seats` quota (free = 1) — so
+// the free plan runs out and upgrading to `pro` (via `billing.startCheckout`)
+// lifts the caps. Boots ZERO-infra (`store: 'memory'`, `mock` billing provider,
+// `memoryUserStore`); the README shows the production swaps.
+import { defineEnv, envVar } from '@voltro/env'
+import { authRoutesPlugin, memoryUserStore, voltroPasswordStrategy } from '@voltro/plugin-auth'
+import { billingPlugin } from '@voltro/plugin-billing'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // HMAC key that signs + verifies the session cookie.
+  //
+  // `generate` means this project mints its OWN key: `voltro dev` writes a
+  // unique value into a gitignored `.env.local` on first boot. No value ships
+  // with the template — a shipped placeholder would be a signing key published
+  // to everyone who downloads it, and every session in every deployment built
+  // from it would be forgeable. Your DEPLOYMENT mints its own the same way (a
+  // missing secret is a hard boot failure in `serve`/`build`/`start`).
+  VOLTRO_SESSION_SECRET: envVar.secret({
+    generate: 'base64url',
+    description: 'HMAC key that signs and verifies session cookies.',
+  }),
+})
+
+// In-process user store — zero infra. `postgresUserStore({ sql })` for durable
+// accounts (it manages its own `_voltro_auth_*` tables, auto-migrated).
+const userStore = memoryUserStore()
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  env,
+  plugins: [
+    // ── Auth ─────────────────────────────────────────────────────────────
+    authRoutesPlugin({
+      store: userStore,
+      // New sign-ups land in this tenant. Every table below carries `tenant()`,
+      // so the runtime AND-merges `tenantId = subject.tenantId` into reads —
+      // one tenant never sees another's projects or invites.
+      defaultTenantId: 'acme',
+      successRedirect: '/',
+      // `Secure` cookies are HTTPS-only, so OFF in dev (a localhost http page
+      // would silently drop the cookie) and ON in production — this is what
+      // makes the sign-in → session → authenticated-call loop work locally.
+      cookieSecure: process.env.NODE_ENV === 'production',
+    }),
+    // ── Billing ──────────────────────────────────────────────────────────
+    // `mock` is the in-memory provider (no Stripe key needed) — great for dev.
+    // `plans` is the single source of tier→quota truth: `free` caps projects at
+    // 3 and seats at 1; `pro` lifts both. Swap `provider: 'stripe'` (+
+    // STRIPE_SECRET_KEY) and real `priceId`s for production checkout.
+    billingPlugin({
+      provider: 'mock',
+      plans: {
+        free: { entitlements: { projects: 3, seats: 1 } },
+        pro:  {
+          priceId: 'price_demo_pro',
+          entitlements: { projects: 'unlimited', seats: 10 },
+        },
+      },
+    }),
+  ],
+  auth: {
+    // Resolves the session cookie the /auth routes mint into the request's
+    // Subject. Reads the SAME VOLTRO_SESSION_SECRET the routes sign with, so
+    // the signing and verifying sides cannot drift.
+    strategies: [voltroPasswordStrategy()],
+  },
+}

package/templates/apps/api-saas-starter/database/schema.ts

@@ -0,0 +1,57 @@
+// Schema for the {{projectName}} SaaS backend.
+//
+// Two tenant-scoped domain tables — `projects` and `invites`. The plugins
+// contribute their OWN tables automatically (auth uses the in-process
+// `memoryUserStore`; billing adds `_voltro_billing_*`), so you don't declare
+// those here. `actors` + `tenants` are the framework's core tables the audit /
+// tenant mixins reference.
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// ---------- Core tables (required by the audit / tenant mixins) ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})
+
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})
+
+// ---------- Application tables ----------
+
+// Creating a project spends the billing `projects` entitlement (free = 3) —
+// see mutations/projects.create.
+export const projects = table('projects', {
+  id:   id({ prefix: 'proj' }),
+  name: text(),
+})
+  // tenant() pulls audit() transitively → tenantId + createdAt / updatedAt /
+  // createdBy / updatedBy (auto-stamped by the runtime).
+  .with(tenant())
+
+// Inviting a teammate spends the billing `seats` entitlement (free = 1) — see
+// mutations/invites.create.
+export const invites = table('invites', {
+  id:     id({ prefix: 'inv' }),
+  email:  text(),
+  status: text().oneOf(['pending', 'accepted', 'revoked']),
+})
+  .with(tenant())
+
+export type Project = InferRow<typeof projects>
+export type Invite = InferRow<typeof invites>
+
+export const database = databaseHandle({ actors, tenants, projects, invites })

package/templates/apps/api-saas-starter/mutations/invites.create.mutation.server.ts

@@ -0,0 +1,26 @@
+// Effect-mode: gate on the `seats` entitlement (free = 1), then write the
+// pending invite. Because the free plan grants a single seat, the FIRST invite
+// after sign-up already trips `EntitlementExceeded` unless the tenant has
+// upgraded / bought seats — which is exactly the seat-management moment the
+// frontend's team page surfaces.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { EffectStore } from '@voltro/runtime'
+import { requireEntitlement } from '@voltro/plugin-billing'
+
+const execute = (input: { email: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    yield* requireEntitlement(ctx, 'seats', 1)
+
+    const store = yield* EffectStore
+    const row = yield* store.insert('invites', { email: input.email, status: 'pending' })
+
+    return {
+      id:       row['id'] as string,
+      email:    row['email'] as string,
+      status:   row['status'] as string,
+      tenantId: row['tenantId'] as string,
+    }
+  })
+
+export default execute

package/templates/apps/api-saas-starter/mutations/invites.create.mutation.ts

@@ -0,0 +1,18 @@
+// Invite a teammate — spends a `seats` entitlement. Same shape as
+// projects.create: the billing plugin merges `EntitlementExceeded` into the
+// wire-error union, so running out of seats surfaces typed and the frontend
+// shows "buy more seats" (billing.changeSeats) instead of a generic error.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createInvite = defineMutation({
+  name:   'invites.create',
+  target: { table: 'invites', op: 'insert' },
+  input:  Schema.Struct({ email: Schema.NonEmptyString }),
+  output: Schema.Struct({
+    id:       Schema.String,
+    email:    Schema.String,
+    status:   Schema.String,
+    tenantId: Schema.String,
+  }),
+})

package/templates/apps/api-saas-starter/mutations/projects.create.mutation.server.ts

@@ -0,0 +1,29 @@
+// Effect-mode so it can `yield*` the billing service the framework provides in
+// the per-request stack. `requireEntitlement` consumes the tenant's metered
+// `projects` quota (free = 3) and fails typed `EntitlementExceeded` when it's
+// exhausted — BEFORE the row is written, so an over-quota create never leaves a
+// partial write. Upgrading to `pro` (via `billing.startCheckout`) lifts the cap
+// to `unlimited` and the same handler starts succeeding again.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { EffectStore } from '@voltro/runtime'
+import { requireEntitlement } from '@voltro/plugin-billing'
+
+const execute = (input: { name: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    // 1. Billing gate — fails closed (typed EntitlementExceeded) when the
+    //    tenant has no `projects` quota left. Runs BEFORE the write.
+    yield* requireEntitlement(ctx, 'projects', 1)
+
+    // 2. Write the row. `tenant()` auto-stamps tenantId + audit columns.
+    const store = yield* EffectStore
+    const row = yield* store.insert('projects', { name: input.name })
+
+    return {
+      id:       row['id'] as string,
+      name:     row['name'] as string,
+      tenantId: row['tenantId'] as string,
+    }
+  })
+
+export default execute

package/templates/apps/api-saas-starter/mutations/projects.create.mutation.ts

@@ -0,0 +1,18 @@
+// Create a project — the paywall in ONE handler. The billing plugin auto-merges
+// its typed `EntitlementExceeded` (+ `BillingError`) into this procedure's
+// wire-error union, so the client decodes the over-quota failure typed WITHOUT
+// a manual `error:` declaration here. That typed failure is the paywall signal:
+// the frontend catches `_tag === 'EntitlementExceeded'` and shows the upgrade CTA.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createProject = defineMutation({
+  name:   'projects.create',
+  target: { table: 'projects', op: 'insert' },
+  input:  Schema.Struct({ name: Schema.NonEmptyString }),
+  output: Schema.Struct({
+    id:       Schema.String,
+    name:     Schema.String,
+    tenantId: Schema.String,
+  }),
+})

package/templates/apps/api-saas-starter/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "lint": "voltro doctor .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.97.0",
+    "@effect/rpc": "^0.76.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-auth": "0.29.0",
+    "@voltro/plugin-billing": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
+    "@voltro/sql-postgres": "0.29.0",
+    "effect": "^3.22.0"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.29.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/api-saas-starter/queries/invites.list.query.server.ts

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'invites' as const,
+    predicate: undefined,
+    order: [{ column: 'createdAt' as const, direction: 'desc' as const }],
+    take: 100,
+    skip: undefined,
+    projection: undefined,
+  },
+})
+
+export default execute

package/templates/apps/api-saas-starter/queries/invites.list.query.ts

@@ -0,0 +1,17 @@
+// Streaming subscription of the tenant's teammate invites. Tenant-scoped like
+// projects.list — read live from the frontend's team page with
+// `useSubscription('app', 'invites.list')`.
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listInvites = defineQuery({
+  name: 'invites.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id:        Schema.String,
+    email:     Schema.String,
+    status:    Schema.String,
+    tenantId:  Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

package/templates/apps/api-saas-starter/queries/projects.list.query.server.ts

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'projects' as const,
+    predicate: undefined,
+    order: [{ column: 'createdAt' as const, direction: 'desc' as const }],
+    take: 100,
+    skip: undefined,
+    projection: undefined,
+  },
+})
+
+export default execute

package/templates/apps/api-saas-starter/queries/projects.list.query.ts

@@ -0,0 +1,18 @@
+// Streaming subscription of the tenant's projects. Every change to `projects`
+// for the caller's tenant lands as a delta — the frontend upgrades its first
+// paint to live with `useSubscription('app', 'projects.list')`. The runtime
+// AND-merges the tenant predicate (the table carries `tenant()`), so this never
+// leaks across tenants — no manual `eq('tenantId', ...)` needed.
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listProjects = defineQuery({
+  name: 'projects.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id:        Schema.String,
+    name:      Schema.String,
+    tenantId:  Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

package/templates/apps/api-saas-starter/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-saas-starter",
+  "kind": "api",
+  "summary": "The whole SaaS loop wired end to end: @voltro/plugin-auth (sign-up/in → session cookie → typed Subject) + @voltro/plugin-billing (free/pro plans, entitlement paywall, seats, checkout) + a tenant-scoped projects + invites backend. projects.create is gated by the billing `projects` quota (4th trips EntitlementExceeded); invites.create consumes a `seats` entitlement. Pair with the frontend-saas web template for signup → paywall → app. Boots zero-infra.",
+  "tags": ["api", "saas", "auth", "billing", "entitlements", "paywall", "seats", "invites", "starter"]
+}

package/templates/apps/api-saas-starter/tests/projects.create.test.ts

@@ -0,0 +1,62 @@
+// Unit tests with `@voltro/testing` — no database, no running server, no
+// billing backend. The create executors run in Effect mode and `yield*` the
+// billing service (`requireEntitlement`), which lives in the per-request plugin
+// layer the unit harness does NOT wire — so we do not fake it. Instead we PIN
+// each descriptor's wire contract (the shape the client codegen + the paywall
+// branch depend on) and prove the `tenant()` scoping that keeps one SaaS
+// tenant's rows invisible to another — the headline isolation guarantee.
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { Schema } from 'effect'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema'   // registers projects / invites / actors / tenants
+import { createProject } from '../mutations/projects.create.mutation'
+import { createInvite } from '../mutations/invites.create.mutation'
+
+describe('projects.create descriptor', () => {
+  it('decodes a valid input and rejects a blank name', () => {
+    const decode = Schema.decodeUnknownSync(createProject.input)
+    expect(decode({ name: 'Acme App' })).toEqual({ name: 'Acme App' })
+    // `name: Schema.NonEmptyString` — an empty string fails the wire decode.
+    expect(() => decode({ name: '' })).toThrow()
+  })
+
+  it('encodes the output shape the client expects', () => {
+    const encode = Schema.encodeUnknownSync(createProject.output)
+    const wire = encode({ id: 'proj_1', name: 'Acme App', tenantId: 'acme' })
+    expect(wire).toEqual({ id: 'proj_1', name: 'Acme App', tenantId: 'acme' })
+  })
+})
+
+describe('invites.create descriptor', () => {
+  it('decodes an email and rejects a blank one', () => {
+    const decode = Schema.decodeUnknownSync(createInvite.input)
+    expect(decode({ email: 'ada@example.com' })).toEqual({ email: 'ada@example.com' })
+    expect(() => decode({ email: '' })).toThrow()
+  })
+
+  it('encodes the invite output shape', () => {
+    const encode = Schema.encodeUnknownSync(createInvite.output)
+    const wire = encode({ id: 'inv_1', email: 'ada@example.com', status: 'pending', tenantId: 'acme' })
+    expect(wire).toEqual({ id: 'inv_1', email: 'ada@example.com', status: 'pending', tenantId: 'acme' })
+  })
+})
+
+describe('tenant isolation (REAL tenant scoping)', () => {
+  it('t2 never sees t1 projects', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ projects: [], invites: [] }),
+    })
+    // Raw insert through the mixin store — tenant() auto-stamps tenantId=t1.
+    const row = await ctx.store.insert('projects', { name: 'secret' })
+    expect(row['tenantId']).toBe('t1')
+
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.projects.descriptor))
+    expect(seenByT2).toHaveLength(0)
+    // …and t1 still sees its own row.
+    const seenByT1 = await ctx.store.query(database.projects.descriptor)
+    expect(seenByT1).toHaveLength(1)
+  })
+})

package/templates/apps/api-saas-starter/tests/session.test.ts

@@ -0,0 +1,33 @@
+// `session.me` returns the caller's resolved identity — the proof the auth loop
+// threads the Subject through to handlers, and the value the frontend's SSR gate
+// reads to decide redirect-to-login vs render. `makeTestContext({ subject })`
+// sets `ctx.request.subject` to exactly what the AuthMiddleware would resolve at
+// runtime, so the executor is fully runnable with no cookie, no session store,
+// no running server. Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext } from '@voltro/testing'
+import '../database/schema'   // registers actors / tenants
+import me from '../actions/me.action.server'
+
+describe('session.me', () => {
+  it('reflects a signed-in user Subject', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+    })
+    const identity = await me({}, ctx)
+
+    expect(identity.type).toBe('user')
+    expect(identity.id).toBe('user_1')
+    expect(identity.tenantId).toBe('acme')
+  })
+
+  it('returns an anonymous identity with null id/tenant when no session is present', async () => {
+    const ctx = makeTestContext()
+    const identity = await me({}, ctx)
+
+    expect(identity.type).toBe('anonymous')
+    expect(identity.id).toBeNull()
+    expect(identity.tenantId).toBeNull()
+  })
+})

package/templates/apps/api-saas-starter/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -13,17 +13,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.27.0",
-    "@voltro/database": "0.27.0",
-    "@voltro/env": "0.27.0",
-    "@voltro/plugin-multitenancy": "0.27.0",
-    "@voltro/plugin-search": "0.27.0",
-    "@voltro/protocol": "0.27.0",
-    "@voltro/runtime": "0.27.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/plugin-search": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.27.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-status/README.md

@@ -0,0 +1,88 @@
+# {{capProjectName}} {{capAppName}} — status-page backend
+
+The backend for a public **status page**: live queries anyone can subscribe to,
+plus operator-only mutations to declare and resolve incidents. Boots
+**zero-infra** (`store: 'memory'`). Pair it with the **frontend-status** web
+template:
+
+```bash
+voltro init my-status --api=api-status --web=frontend-status
+voltro dev
+```
+
+## The asymmetry it encodes
+
+A status page is read by everyone and written by a few — so:
+
+- **Reads are PUBLIC.** `incidents.live`, `updates.list`, `components.list`
+  carry **no guard**, so an anonymous browser can `useSubscription('app',
+  'incidents.live')` and the timeline updates live.
+- **Writes are OPERATOR-ONLY.** Every mutation declares
+  `guards: [{ scope: 'status:write' }]`, enforced by `@voltro/plugin-rbac` in the
+  dispatch spine before the executor. The demo resolver (`authz.ts`) grants the
+  `operator` role to the `ops` tenant; everyone else — anonymous included — is
+  denied.
+
+## Surface
+
+| Tag | Kind | Guard |
+|---|---|---|
+| `incidents.live` | query (stream) | — public |
+| `updates.list` | query (stream) | — public |
+| `components.list` | query (stream) | — public |
+| `incidents.create` | mutation | `status:write` |
+| `incidents.update` | mutation | `status:write` |
+| `incidents.resolve` | mutation | `status:write` |
+| `components.create` | mutation | `status:write` |
+
+## Try it (curl)
+
+```bash
+voltro dev .
+
+# A public read — no auth (anyone can watch)
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' \
+  -d '{"tag":"incidents.live","input":{}}'
+
+# An operator write — needs the `ops` tenant (demo resolver → operator role)
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' -H 'x-tenant: ops' \
+  -d '{"tag":"incidents.create","input":{"title":"API degraded","impact":"major"}}'
+
+# The SAME write without the operator tenant → typed ScopeError
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' \
+  -d '{"tag":"incidents.create","input":{"title":"nope","impact":"minor"}}'
+# → { "ok": false, "error": { "_tag": "ScopeError", "required": "status:write" } }
+```
+
+## Files
+
+```
+app.config.ts             rbacPlugin (roles + demo resolver)
+authz.ts                  the role→scope map (status:write) — one source of truth
+database/schema.ts        components / incidents / incident_updates (PUBLIC, not tenant-scoped)
+queries/                  incidents.live / updates.list / components.list — ungated streams
+mutations/                incidents.create|update|resolve, components.create — status:write
+tests/                    the public-read / operator-write asymmetry + descriptor pins
+```
+
+## Going to production
+
+- **Real operator auth.** Replace the demo `resolveRoles` with subject metadata
+  or a DB lookup, and pair this api with `api-auth` / `api-saas-starter` so
+  operators actually sign in. The rbac gate is already in place — you only swap
+  where the roles come from.
+- **Durable store.** `store: 'postgres'` (or `sqlite`) so incident history
+  survives a restart.
+- **Notify subscribers** on open/resolve with `@voltro/plugin-mail` (opt-in).
+
+## Anti-patterns
+
+- **Tenant-scoping the public tables.** Adding `tenant()` to `incidents` would
+  make an anonymous visitor (no tenant) see nothing. Public reads stay
+  unscoped; the rbac guard on the writes is the boundary.
+- **A write-only authz model.** These reads are intentionally ungated because
+  they're public — but if you ever gate a read, gate it with `guards:` on the
+  query (enforced on open AND every delivery), not a check inside the handler.

package/templates/apps/api-status/app.config.ts

@@ -0,0 +1,36 @@
+// Backend for the {{projectName}} public status page. Read by `voltro dev`.
+//
+// The shape of a status page is asymmetric, and this config encodes it:
+//   • READS are PUBLIC — `incidents.live` / `updates.list` / `components.list`
+//     carry NO guard, so an anonymous visitor's browser can subscribe and see
+//     the live timeline. (A status page that requires a login is useless during
+//     an outage.)
+//   • WRITES are OPERATOR-ONLY — every mutation declares a `status:write` guard.
+//     `rbacPlugin` resolves each caller's ROLES to SCOPES and the framework
+//     enforces the guard in the dispatch spine, before the executor. `voltro
+//     check` can see the guard statically.
+//
+// The role map lives in `authz.ts`. Config-only — no external infra.
+import { defineEnv, envVar } from '@voltro/env'
+import { rbacPlugin } from '@voltro/plugin-rbac'
+import { demoRolesForTenant, roles } from './authz'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  plugins: [
+    rbacPlugin({
+      roles,
+      // Demo: `ops` tenant → operator. Swap for a real resolver (subject
+      // metadata / a DB lookup) when you wire operator auth — pair this api
+      // with the api-auth / api-saas-starter auth backend.
+      resolveRoles: (subject) => demoRolesForTenant(subject.tenantId),
+    }),
+  ],
+  env,
+}

package/templates/apps/api-status/authz.ts

@@ -0,0 +1,33 @@
+// The status page's authorization vocabulary, in ONE place — split out of
+// app.config.ts so the tests build the real plugin from the real role map (a
+// test that redeclares the roles only proves its own copy is self-consistent).
+//
+// A status page has exactly two kinds of caller: the PUBLIC (anonymous
+// visitors, who only READ — the live queries carry no guard) and OPERATORS
+// (who post incidents). So there is one write scope, `status:write`, held by
+// the `operator` role; `admin` gets the wildcard bypass.
+//
+// This map is ALSO the app's declared scope vocabulary: `rbacPlugin` publishes
+// its union, and `voltro check` errors on any descriptor guard requiring a
+// scope that appears nowhere here — so a guard and its grant can't silently
+// drift out of sync.
+export const roles = {
+  operator: ['status:write'],
+  admin:    ['*'],
+}
+
+/**
+ * DEMO role resolver — grants `operator` to callers in the `ops` tenant so
+ * every operator flow is reachable with an `x-tenant: ops` header and zero auth
+ * setup. Everyone else (including anonymous visitors) gets NO role, so the
+ * ungated read queries still work but every `status:write` mutation is denied.
+ *
+ * PRODUCTION reads the caller's REAL roles: the default resolver reads
+ * `subject.metadata.roles` (set by your auth strategy — pair this with the
+ * api-auth / api-saas-starter auth wiring), or do a DB lookup here. If this
+ * throws, rbac degrades to the subject's own scopes — it never grants on
+ * failure.
+ */
+export const demoRolesForTenant = (
+  tenantId: string | null | undefined,
+): ReadonlyArray<string> => (tenantId === 'ops' ? ['operator'] : [])