@voltro/cli 0.1.0

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

@@ -0,0 +1,42 @@
+// Rate-limited backend for the {{projectName}} project.
+//
+// `rateLimitPlugin` runs on the rpc interceptors — the one surface that sees
+// every call AND the resolved subject. A `default` fallback applies to every
+// procedure; `rules` override per endpoint (exact tag or `/regex/`), with a
+// choice of algorithm (sliding-window / fixed-window / token-bucket+burst) and
+// composite keying (`by: 'subject' | 'tenant' | 'apiKey' | 'global'` or an
+// array). Over-limit calls fail a typed `RateLimited` error — the plugin merges
+// it into every procedure's wire error union, so the client decodes it typed.
+// `store: 'memory'` is single-node; switch to 'postgres' / 'redis' for a cluster.
+import { defineEnv, envVar } from '@voltro/env'
+import { rateLimitPlugin } from '@voltro/plugin-ratelimit'
+
+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: [
+    rateLimitPlugin({
+      // Global fallback: 100 calls/min, per subject.
+      default: { limit: 100, window: '1m' },
+      rules: [
+        // Tight, per-endpoint: notes.create → 3/min per TENANT, token-bucket
+        // (the bucket starts full, so a burst of 3 is allowed, then refills).
+        {
+          match: 'notes.create',
+          limit: 3,
+          window: '1m',
+          algorithm: 'token-bucket',
+          burst: 3,
+          by: 'tenant',
+        },
+      ],
+      store: 'memory',
+    }),
+  ],
+  env,
+}

package/templates/apps/api-ratelimit/database/schema.ts

@@ -0,0 +1,37 @@
+// Schema for the {{projectName}} rate-limited backend — a tiny `notes` domain
+// to throttle. `actors` + `tenants` are the framework core tables.
+
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+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'),
+})
+
+export const notes = table('notes', {
+  id:    id({ prefix: 'note' }),
+  title: text(),
+  body:  text(),
+})
+  .with(tenant())
+  .reactive()
+
+export type Note = InferRow<typeof notes>
+
+export const database = databaseHandle({ actors, tenants, notes })

package/templates/apps/api-ratelimit/mutations/notes.create.mutation.server.ts

@@ -0,0 +1,16 @@
+import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (
+  input: { tenantId: string; title: string; body: string },
+  ctx: AppContext,
+) => {
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+  return ctx.store.insert('notes', {
+    title: input.title,
+    body: input.body,
+    tenantId: input.tenantId,
+  })
+}
+
+export default execute

package/templates/apps/api-ratelimit/mutations/notes.create.mutation.ts

@@ -0,0 +1,34 @@
+// Creates a note. There's NO rate-limit code here — the limit is enforced by
+// the plugin's rpc interceptor (see app.config.ts). When the caller is over
+// the limit, the call fails a typed `RateLimited` error that the plugin merges
+// into this procedure's wire error union automatically — you don't declare it.
+// (`TenantMismatch` is the explicit error this handler can throw.)
+
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { Schema } from 'effect'
+
+export const createNote = defineMutation({
+  name: 'notes.create',
+  target: {
+    table: 'notes',
+    op: 'insert',
+    shape: (input: { tenantId: string; title: string; body: string }) => ({
+      title: input.title,
+      body: input.body,
+      tenantId: input.tenantId,
+    }),
+  },
+  input: Schema.Struct({
+    tenantId: Schema.String,
+    title: Schema.NonEmptyString,
+    body: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    tenantId: Schema.String,
+  }),
+  error: TenantMismatch,
+})

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

@@ -0,0 +1,29 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/plugin-ratelimit": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/api-ratelimit/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-ratelimit",
+  "kind": "api",
+  "summary": "Per-endpoint / per-subject / per-tenant rate limiting — @voltro/plugin-ratelimit intercepts rpc calls: a default fallback + rules (exact tag or regex), sliding-window / token-bucket algorithms, composite keying (by subject/tenant/apiKey/global), and a typed RateLimited error auto-merged into the wire error union. Memory store, zero infra.",
+  "tags": ["api", "rate-limit", "throttle", "token-bucket", "plugin"]
+}

package/templates/apps/api-ratelimit/tests/notes.create.test.ts

@@ -0,0 +1,69 @@
+// Unit test for `notes.create` — driven through `@voltro/testing`.
+//
+// The rate limit itself is enforced by the plugin's rpc INTERCEPTOR (a
+// dispatch-time middleware wired in app.config.ts), NOT by this executor — and
+// `invoke` reproduces only the input-Schema decode, not middleware (see its
+// header). So we test the executor's OWN observable behavior: the tenant-guarded
+// insert. `makeTestContext` hands the handler the SAME mixin-wrapped `ctx.store`
+// it gets in production, so tenant auto-scoping behaves as at runtime.
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore, invoke } from '@voltro/testing'
+import { database } from '../database/schema' // registers actors / tenants / notes
+import { createNote } from '../mutations/notes.create.mutation'
+import createNoteHandler from '../mutations/notes.create.mutation.server'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+
+const subject = { type: 'user', id: 'u1', tenantId: 'acme' } as const
+
+describe('notes.create', () => {
+  it('inserts a note stamped with the caller tenant + a note_ TypeID', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ notes: [] }) })
+
+    const row = (await invoke(
+      createNote,
+      createNoteHandler,
+      { tenantId: 'acme', title: 'Ship it', body: 'World' },
+      ctx,
+    )) as { id: string; title: string; body: string; tenantId: string }
+
+    expect(row.title).toBe('Ship it')
+    expect(row.tenantId).toBe('acme')
+    expect(row.id).toMatch(/^note_/)
+
+    // The row is really in the store — the live tenant-scoped query sees it.
+    const rows = await ctx.store.query(database.notes.descriptor)
+    expect(rows).toHaveLength(1)
+  })
+
+  it('rejects a cross-tenant write with a typed TenantMismatch — nothing written', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ notes: [] }) })
+
+    await expect(
+      invoke(createNote, createNoteHandler, { tenantId: 'evil-corp', title: 'x', body: '' }, ctx),
+    ).rejects.toBeInstanceOf(TenantMismatch)
+
+    const rows = await ctx.store.select('notes').unscoped().all()
+    expect(rows).toHaveLength(0)
+  })
+
+  it('rejects an empty title at the input-schema decode (NonEmptyString)', async () => {
+    const ctx = makeTestContext({ subject, store: mockStore({ notes: [] }) })
+
+    await expect(
+      invoke(createNote, createNoteHandler, { tenantId: 'acme', title: '', body: '' }, ctx),
+    ).rejects.toThrow()
+  })
+
+  it('isolates tenants — a second tenant never sees the first tenant row', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store: mockStore({ notes: [] }),
+    })
+    await invoke(createNote, createNoteHandler, { tenantId: 't1', title: 'secret', body: '' }, ctx)
+
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.notes.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+})

package/templates/apps/api-ratelimit/tsconfig.json

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

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

@@ -0,0 +1,59 @@
+# {{projectName}} / {{appName}}
+
+Voltro API scaffold (template: **api-rbac**) — role-based access control with
+`@voltro/plugin-rbac`.
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000  (store: memory — zero infra)
+```
+
+## What this shows
+
+- **Roles → scopes, as config** — `app.config.ts` declares a role map
+  (`viewer → notes:read`, `editor → notes:read + notes:write`,
+  `admin → admin:full`). An rpc interceptor resolves each caller's roles to
+  scopes and stamps them on the subject.
+- **Guard with `permission()`** — `notes.create` calls
+  `permission(ctx, 'notes:write')`, the Effect-native guard. It fails typed
+  `Forbidden` when the caller lacks the scope; `admin:full` is a blanket bypass.
+  Companions: `anyPermission(ctx, [...])` (OR), `assertPermission` (sync throw),
+  `can(ctx, scope)` (boolean).
+- **Where roles come from** — the shipped `resolveRoles` is a DEMO that maps
+  the request's **tenant** to a role so you can try each with the `x-tenant`
+  header. Production reads the caller's real roles: the default resolver reads
+  `subject.metadata.roles` (set by your auth strategy), or do a DB lookup.
+
+## Try it
+
+```bash
+# admin tenant (acme) → admin:full → notes:write passes:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' -H 'x-tenant: acme' \
+  -d '{"tag":"notes.create","input":{"title":"hi","body":"x"}}'
+# → { ok:true, result:{ id, … } }
+
+# readers tenant → viewer → notes:write missing → typed Forbidden:
+curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json' -H 'x-tenant: readers' \
+  -d '{"tag":"notes.create","input":{"title":"hi","body":"x"}}'
+# → { ok:false, error:{ _tag:"Forbidden", required:"notes:write" } }
+```
+
+## On the web side
+
+```tsx
+import { useCan } from '@voltro/plugin-rbac/web'
+const canWrite = useCan('notes:write')
+{canWrite && <NewNoteButton />}     // hide affordances the user can't use
+```
+
+`useCan` is a UI affordance only — the server `permission()` guard is the real
+enforcement. Never trust the client.
+
+## Persisted roles
+
+Set `tables: true` to store role assignments in `roles` / `userRoles` tables
+and resolve them from the DB (multitenant-aware). The shipped template stays
+config-only.

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

@@ -0,0 +1,48 @@
+// RBAC backend for the {{projectName}} project.
+//
+// `rbacPlugin` compiles a role→scope map; an rpc interceptor resolves each
+// caller's ROLES to SCOPES and stamps them on the subject, so in-handler
+// guards like `permission(ctx, 'notes:write')` (Effect-native, fails typed
+// `Forbidden`) just work. The `admin:full` scope is a blanket bypass.
+//
+// Config-only — no tables, no infra.
+import { defineEnv, envVar } from '@voltro/env'
+import { rbacPlugin } from '@voltro/plugin-rbac'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+})
+
+// role → the scopes it grants. Scopes are `domain:action`; `admin:full` is the
+// framework's blanket bypass (passes every permission check).
+const roles = {
+  viewer: ['notes:read'],
+  editor: ['notes:read', 'notes:write'],
+  admin:  ['admin:full'],
+}
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  plugins: [
+    rbacPlugin({
+      roles,
+      // DEMO resolver — assigns a role by the request's tenant so you can try
+      // each role via the `x-tenant` header with zero auth setup. PRODUCTION
+      // reads the caller's REAL roles: the default resolver reads
+      // `subject.metadata.roles` (set by your auth strategy), or do a DB
+      // lookup here (`subject.id` / `subject.tenantId` → roles). Delete this
+      // whole `resolveRoles` to fall back to the metadata default.
+      resolveRoles: (subject) => {
+        const demo: Record<string, ReadonlyArray<string>> = {
+          acme:    ['admin'],
+          editors: ['editor'],
+          readers: ['viewer'],
+        }
+        return demo[subject.tenantId ?? ''] ?? ['viewer']
+      },
+    }),
+  ],
+  env,
+}

package/templates/apps/api-rbac/database/schema.ts

@@ -0,0 +1,37 @@
+// Schema for the {{projectName}} RBAC backend — a tiny `notes` domain to
+// guard. `actors` + `tenants` are the framework core tables.
+
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+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'),
+})
+
+export const notes = table('notes', {
+  id:    id({ prefix: 'note' }),
+  title: text(),
+  body:  text(),
+})
+  .with(tenant())
+  .reactive()
+
+export type Note = InferRow<typeof notes>
+
+export const database = databaseHandle({ actors, tenants, notes })

package/templates/apps/api-rbac/mutations/notes.create.mutation.server.ts

@@ -0,0 +1,22 @@
+import { EffectStore } from '@voltro/runtime'
+import type { AppContext } from '@voltro/runtime'
+import { permission } from '@voltro/plugin-rbac'
+import { Effect } from 'effect'
+
+const execute = (input: { title: string; body: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    // RBAC guard — passes for editor/admin, fails typed Forbidden for viewer.
+    yield* permission(ctx, 'notes:write')
+
+    const store = yield* EffectStore
+    // tenant() auto-fills tenantId from the subject — no need to pass it.
+    const row = yield* store.insert('notes', { title: input.title, body: input.body })
+    return {
+      id: row['id'] as string,
+      title: row['title'] as string,
+      body: row['body'] as string,
+      tenantId: row['tenantId'] as string,
+    }
+  })
+
+export default execute

package/templates/apps/api-rbac/mutations/notes.create.mutation.ts

@@ -0,0 +1,26 @@
+// Creates a note — requires the `notes:write` scope. The executor guards with
+// `permission(ctx, 'notes:write')`, the Effect-native RBAC guard that fails
+// typed `Forbidden` when the caller's resolved scopes don't include it.
+// Declaring `error: Forbidden` surfaces that to the client typed.
+//
+// `Forbidden` comes from the browser-safe `/errors` subpath.
+
+import { defineMutation } from '@voltro/protocol'
+import { Forbidden } from '@voltro/plugin-rbac/errors'
+import { Schema } from 'effect'
+
+export const createNote = defineMutation({
+  name: 'notes.create',
+  target: { table: 'notes', op: 'insert' },
+  input: Schema.Struct({
+    title: Schema.NonEmptyString,
+    body: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    tenantId: Schema.String,
+  }),
+  error: Forbidden,
+})

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

@@ -0,0 +1,29 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/plugin-rbac": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/api-rbac/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-rbac",
+  "kind": "api",
+  "summary": "Role-based access control — @voltro/plugin-rbac compiles a role→scope map and an interceptor resolves the caller's roles to scopes; guard handlers with permission(ctx, 'notes:write') (Effect-native, fails typed Forbidden). admin:full bypasses. Memory/config-only, zero infra; useCan() for web UI affordance.",
+  "tags": ["api", "rbac", "authz", "roles", "permissions", "plugin"]
+}

package/templates/apps/api-rbac/tests/notes.create.test.ts

@@ -0,0 +1,80 @@
+// Unit test for `notes.create` — driven through `@voltro/testing`.
+//
+// This executor is Effect-native: it `yield*`s the RBAC guard
+// `permission(ctx, 'notes:write')` (fails typed `Forbidden` for a caller
+// lacking the scope) and then `yield* EffectStore` to insert. `makeTestContext`
+// exposes the mixin-wrapped store as `ctx.store`; we provide it to the Effect as
+// the `EffectStore` layer via `makeEffectStoreLayer` — the SAME wiring the CLI
+// dev/serve dispatcher does — so the handler runs exactly as at runtime.
+//
+// In production the rbac INTERCEPTOR resolves the caller's roles → scopes and
+// stashes them on the subject before the handler runs. That interceptor is a
+// dispatch-time concern the unit harness doesn't run, so we drive the handler's
+// OWN guard directly by putting the resolved scope on `subject.scopes` — exactly
+// what the interceptor would have stashed. Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { Cause, Effect, Exit, Option, Schema } from 'effect'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { makeEffectStoreLayer } from '@voltro/runtime'
+import { database } from '../database/schema' // registers actors / tenants / notes
+import { createNote } from '../mutations/notes.create.mutation'
+import createNoteHandler from '../mutations/notes.create.mutation.server'
+import { Forbidden } from '@voltro/plugin-rbac/errors'
+
+// Run the Effect-native executor with the test store provided as EffectStore.
+const runExec = (input: { title: string; body: string }, ctx: ReturnType<typeof makeTestContext>) =>
+  Effect.runPromise(createNoteHandler(input, ctx).pipe(Effect.provide(makeEffectStoreLayer(ctx.store))))
+
+// Same, but returns the raw Exit so a typed failure can be inspected WITHOUT
+// the `FiberFailure` wrapper `runPromise` throws (which would defeat a plain
+// `instanceof Forbidden` assertion). Unwrap the Cause to get the real error.
+const runExit = (input: { title: string; body: string }, ctx: ReturnType<typeof makeTestContext>) =>
+  Effect.runPromiseExit(createNoteHandler(input, ctx).pipe(Effect.provide(makeEffectStoreLayer(ctx.store))))
+
+describe('notes.create', () => {
+  it('inserts for a caller holding notes:write — tenant-stamped, note_ TypeID', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'editor_1', tenantId: 'acme', scopes: ['notes:write'] },
+      store: mockStore({ notes: [] }),
+    })
+
+    const row = await runExec({ title: 'Ship it', body: 'World' }, ctx)
+
+    expect(row.title).toBe('Ship it')
+    expect(row.tenantId).toBe('acme') // tenant() auto-filled from the subject
+    expect(row.id).toMatch(/^note_/)
+
+    // The row is really in the store — the live tenant-scoped query sees it.
+    const rows = await ctx.store.query(database.notes.descriptor)
+    expect(rows).toHaveLength(1)
+  })
+
+  it('rejects a caller WITHOUT notes:write with typed Forbidden — nothing written', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'viewer_1', tenantId: 'acme', scopes: [] },
+      store: mockStore({ notes: [] }),
+    })
+
+    const exit = await runExit({ title: 'x', body: '' }, ctx)
+
+    expect(Exit.isFailure(exit)).toBe(true)
+    const failure = Exit.isFailure(exit) ? Cause.failureOption(exit.cause) : Option.none()
+    expect(Option.getOrThrow(failure)).toBeInstanceOf(Forbidden)
+
+    const rows = await ctx.store.query(database.notes.descriptor)
+    expect(rows).toHaveLength(0)
+  })
+
+  it('pins the descriptor: name, input decode + the declared Forbidden error', () => {
+    expect(createNote.name).toBe('notes.create')
+
+    const decoded = Schema.decodeUnknownSync(createNote.input)({ title: 'ok', body: 'b' })
+    expect(decoded).toEqual({ title: 'ok', body: 'b' })
+    // Empty title is rejected at the input Schema (NonEmptyString).
+    expect(() => Schema.decodeUnknownSync(createNote.input)({ title: '', body: '' })).toThrow()
+
+    const forbidden = new Forbidden({ required: 'notes:write' })
+    expect(Schema.is(Forbidden)(forbidden)).toBe(true)
+  })
+})

package/templates/apps/api-rbac/tsconfig.json

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

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

@@ -0,0 +1,85 @@
+# {{capProjectName}} {{capAppName}} — public REST API
+
+A turnkey **public REST API** built on `defineRestRoute`, with an
+auto-generated **OpenAPI 3.1 spec + Swagger UI**. Unlike the reactive
+rpc/WebSocket surface (`api-backend`), these are plain raw-HTTP endpoints a
+third party calls with a URL + JSON.
+
+## What it demonstrates
+
+- **`defineRestRoute`** — four endpoints over a `products` catalog:
+  - `GET    /v1/products?limit=&cursor=` — public, cursor-paginated list
+  - `GET    /v1/products/:id` — public, one product or `404`
+  - `POST   /v1/products` — **scope-guarded** + **idempotent** create
+  - `DELETE /v1/products/:id` — **scope-guarded** delete
+- **Query string + path params + JSON body** parsing → one decoded `input`.
+- **Scope guards** — `requireScope('products:write')` returns `403` unless the
+  caller's API key carries the scope.
+- **`Idempotency-Key`** — a retried `POST` replays the first response instead
+  of inserting twice (`app.config.ts` `idempotency: true`).
+- **`@voltro/plugin-openapi`** — `GET /openapi.json` (the spec) + `GET /docs`
+  (Swagger UI), generated from the route descriptors. No hand-written docs.
+
+REST routes are the ONE primitive that is **not auto-discovered** — they're
+registered explicitly via `restRoutes` in `app.config.ts`.
+
+## Run it
+
+```bash
+voltro dev .
+```
+
+Boots on `http://localhost:4000`. Then:
+
+```bash
+# The spec + interactive docs
+open http://localhost:4000/docs
+curl -s http://localhost:4000/openapi.json | jq '.info, (.paths | keys)'
+
+# Public reads — no auth
+curl -s http://localhost:4000/v1/products            # → { "data": [], "nextCursor": null }
+curl -s http://localhost:4000/v1/products/prod_xyz   # → 404
+
+# Guarded create — the demo API key carries products:write
+curl -s -X POST http://localhost:4000/v1/products \
+  -H 'Authorization: Bearer restdemo_devkey' \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Widget","priceCents":1999}'           # → 201 the created product
+
+# Same call WITHOUT the key → 403 (the guard rejects)
+curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:4000/v1/products \
+  -H 'Content-Type: application/json' -d '{"name":"x","priceCents":1}'   # → 403
+
+# Idempotency — repeat with the same key header → the SAME response replayed
+curl -s -X POST http://localhost:4000/v1/products \
+  -H 'Authorization: Bearer restdemo_devkey' \
+  -H 'Idempotency-Key: order-42' \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Once","priceCents":500}'
+```
+
+## Auth — the demo key is DEV-ONLY
+
+`app.config.ts` ships ONE hardcoded API key (`restdemo_devkey` → scopes
+`products:read` + `products:write`) so the guarded routes work on first boot.
+The `apiKeyStrategy` SHA-256-hashes the bearer token and matches the hash to a
+fixed Subject.
+
+**Before you deploy**, delete the demo constant and do one of:
+
+- look the token hash up against your own key store (store key **hashes**,
+  never raw tokens), or
+- flip on the framework's first-class API keys — set `apiKeys: true` in
+  `app.config.ts` for admin-gated issue/list/revoke against `_voltro_api_keys`,
+  with hash-only storage built in.
+
+## Make it real
+
+- `store: 'memory'` → `store: 'postgres'` (data survives restarts).
+- Replace `products` in `database/schema.ts` with your domain; add `tenant()`
+  if the API is multi-tenant (then scope each handler by the key's `tenantId`).
+- Add routes — drop another `*.route.tsx`, `export default defineRestRoute(…)`,
+  and add it to the `routes` array in `app.config.ts` (it joins both the mount
+  and the OpenAPI spec automatically).
+- Version/deprecate — a descriptor's `deprecated` sets a `Deprecation: true`
+  header; `sunset` sets `Sunset:` and `410`s past the date.