@voltro/cli 0.28.0 → 0.29.0

package/templates/apps/api-cms/queries/content.list.query.ts

@@ -0,0 +1,27 @@
+// `content.list` — a LIVE, tenant-scoped list of one content type's rows. The
+// editor subscribes with `useSubscription('cms', 'content.list', { type })`; a
+// publish/save wakes the subscription so the list updates without a refetch.
+// `status` picks the table: 'draft' (the editor's working set, the default) or
+// 'published' (what consumers read).
+//
+// The output pins only the columns a list view needs — the runtime drops the
+// rest (`Schema.Struct` ignores excess), so ONE query shape serves every content
+// type even though their full rows differ. `title`/`slug` are optional so a type
+// without them still decodes.
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listContent = defineQuery({
+  name: 'content.list',
+  input: Schema.Struct({
+    type:   Schema.NonEmptyString,
+    status: Schema.optional(Schema.Literal('draft', 'published')),
+  }),
+  output: Schema.Struct({
+    id:        Schema.String,
+    status:    Schema.String,
+    title:     Schema.optional(Schema.String),
+    slug:      Schema.optional(Schema.String),
+    updatedAt: Schema.Date,
+  }),
+})

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

@@ -0,0 +1,6 @@
+{
+  "id": "api-cms",
+  "kind": "api",
+  "summary": "A headless CMS backend composed from @voltro/cms: content types declared as code (defineContentType + the Schema field DSL) compile to draft/published tables, the write pipeline (saveDraft → derive+validate, publish/unpublish) drives the lifecycle, and a typed rpc surface (content.list/get/types/saveDraft/publish/unpublish) feeds an editor. Auth via @voltro/plugin-auth; tenant-scoped content. Pair with the frontend-cms editor web template. Boots zero-infra.",
+  "tags": ["api", "cms", "content", "headless", "drafts", "publishing", "editor", "auth"]
+}

package/templates/apps/api-cms/tests/content.descriptors.test.ts

@@ -0,0 +1,64 @@
+// Descriptor + executor contract pins — the shapes the client codegen and the
+// editor depend on. No database, no running server. Run with `voltro test`.
+
+import { describe, it, expect } from 'vitest'
+import { Schema } from 'effect'
+import { makeTestContext } from '@voltro/testing'
+import '../database/schema' // registers the core + derived content tables
+import { saveDraft } from '../mutations/content.saveDraft.mutation'
+import { listContent } from '../queries/content.list.query'
+import contentTypesExecute from '../actions/content.types.action.server'
+
+describe('content.saveDraft descriptor', () => {
+  it('decodes an input carrying arbitrary per-type values', () => {
+    const decode = Schema.decodeUnknownSync(saveDraft.input)
+    const input = { type: 'blogPost', values: { title: 'Hi', body: 'x' } }
+    expect(decode(input)).toEqual(input)
+  })
+
+  it('encodes both arms of the result union', () => {
+    const encode = Schema.encodeUnknownSync(saveDraft.output)
+    expect(encode({ ok: true, id: 'blogPost_1', status: 'draft' })).toEqual({ ok: true, id: 'blogPost_1', status: 'draft' })
+    const fail = { ok: false, violations: [{ field: 'title', rule: 'required', message: 'missing' }] }
+    expect(encode(fail)).toEqual(fail)
+  })
+})
+
+describe('content.list descriptor', () => {
+  it('accepts a type + optional status and pins the list projection shape', () => {
+    const decodeIn = Schema.decodeUnknownSync(listContent.input)
+    expect(decodeIn({ type: 'blogPost', status: 'draft' })).toEqual({ type: 'blogPost', status: 'draft' })
+    // The output carries only what a list view needs — id/status/title?/slug?/
+    // updatedAt; the runtime drops a row's other columns against this shape.
+    const encode = Schema.encodeUnknownSync(listContent.output)
+    const wire = encode({ id: 'p1', status: 'published', title: 'T', slug: 't', updatedAt: new Date(0) })
+    expect(wire.id).toBe('p1')
+    expect(wire.status).toBe('published')
+    expect(wire.title).toBe('T')
+  })
+})
+
+describe('content.types executor', () => {
+  it('projects the registered types to a wire-safe, order-preserving descriptor', async () => {
+    const ctx = makeTestContext({ subject: { type: 'user', id: 'u1', tenantId: 'acme' } })
+    const out = await contentTypesExecute({}, ctx)
+
+    const names = out.types.map((t) => t.name)
+    expect(names).toContain('blogPost')
+    expect(names).toContain('page')
+
+    const blog = out.types.find((t) => t.name === 'blogPost')!
+    const fieldNames = blog.fields.map((f) => f.name)
+    expect(fieldNames).toEqual(['title', 'slug', 'body', 'excerpt', 'publishedAt'])
+    // The slug field is a string with a richer widget than plain text is fine —
+    // and its derived transform (a function) is NOT on the wire shape.
+    const slug = blog.fields.find((f) => f.name === 'slug')!
+    expect(slug.kind).toBe('string')
+    expect('transform' in slug).toBe(false)
+    // The Literal `layout` on `page` carries its value set for the <select>.
+    const page = out.types.find((t) => t.name === 'page')!
+    const layout = page.fields.find((f) => f.name === 'layout')!
+    expect(layout.editorHint).toBe('select')
+    expect(layout.literals).toEqual(['default', 'wide', 'landing'])
+  })
+})

package/templates/apps/api-cms/tests/content.write.test.ts

@@ -0,0 +1,85 @@
+// The CMS write pipeline against the REAL runtime store spine — an
+// InMemoryDataStore wrapped by `wrapStoreWithMixinBehaviour` with a registry
+// built from the SAME derived tables the app registers. That's what makes these
+// assertions honest: derivation + validation come from @voltro/cms, and
+// tenant-scoping/stamping come from the spine, not a mock. Run with `voltro test`.
+
+import { describe, it, expect } from 'vitest'
+import {
+  InMemoryDataStore,
+  makeSchemaRegistry,
+  wrapStoreWithMixinBehaviour,
+  type RegistryTableLike,
+} from '@voltro/runtime'
+import { ContentValidationFailed, publish, saveDraft } from '@voltro/cms'
+import { blogPost } from '../content'
+import { blogEntities, pageEntities } from '../database/schema'
+
+// Registry over the real derived tables → hasTenant/hasAudit/idScheme reflect a
+// booted app exactly.
+const registry = makeSchemaRegistry([
+  blogEntities.draft, blogEntities.published,
+  pageEntities.draft, pageEntities.published,
+] as ReadonlyArray<RegistryTableLike>)
+
+// A request-scoped store for one tenant over a shared underlying store.
+const storeFor = (underlying: InMemoryDataStore, tenantId: string) =>
+  wrapStoreWithMixinBehaviour(underlying, {
+    subject: { type: 'user', id: 'usr_editor', tenantId },
+    schemaRegistry: registry,
+  })
+
+const validInput = {
+  title: 'Hello World',
+  body: { type: 'doc', content: [{ type: 'paragraph' }] },
+}
+
+describe('saveDraft → derive + validate + write', () => {
+  it('derives the slug from the title, stamps status/tenant, generates an id', async () => {
+    const store = storeFor(new InMemoryDataStore(), 'tnt_A')
+    const draft = await saveDraft(store, blogPost, validInput)
+
+    expect(draft['slug']).toBe('hello-world')     // derivedFrom('title', slugify)
+    expect(draft['status']).toBe('draft')
+    expect(draft['tenantId']).toBe('tnt_A')        // stamped by the spine
+    expect(typeof draft['id']).toBe('string')
+  })
+
+  it('rejects an invalid row with ContentValidationFailed carrying per-field violations', async () => {
+    const store = storeFor(new InMemoryDataStore(), 'tnt_A')
+    // Missing required `title` (so the derived slug is empty → pattern fails too).
+    await expect(saveDraft(store, blogPost, { body: 'x' })).rejects.toBeInstanceOf(ContentValidationFailed)
+  })
+})
+
+describe('publish → copy draft to published', () => {
+  it('publishes a draft and the published row keeps the same id + slug', async () => {
+    const store = storeFor(new InMemoryDataStore(), 'tnt_A')
+    const draft = await saveDraft(store, blogPost, validInput)
+
+    const published = await publish(store, blogPost, draft['id'] as string)
+    expect(published['id']).toBe(draft['id'])
+    expect(published['slug']).toBe('hello-world')
+    expect(published['status']).toBe('published')
+  })
+})
+
+describe('tenant isolation (REAL scoping)', () => {
+  it("tenant B never sees tenant A's published content", async () => {
+    const underlying = new InMemoryDataStore()
+    const a = storeFor(underlying, 'tnt_A')
+    const b = storeFor(underlying, 'tnt_B')
+
+    const draft = await saveDraft(a, blogPost, validInput)
+    await publish(a, blogPost, draft['id'] as string)
+
+    const seenByA = await a.query({
+      table: 'blogPost_published', predicate: undefined, order: [], take: 10, skip: undefined, projection: undefined,
+    })
+    const seenByB = await b.query({
+      table: 'blogPost_published', predicate: undefined, order: [], take: 10, skip: undefined, projection: undefined,
+    })
+    expect(seenByA).toHaveLength(1)
+    expect(seenByB).toHaveLength(0)
+  })
+})

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

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

package/templates/apps/api-data-advanced/package.json

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

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

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

package/templates/apps/api-feature-flags/package.json

@@ -13,18 +13,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/plugin-flags": "0.28.0",
-    "@voltro/plugin-multitenancy": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
-    "@voltro/sql-postgres": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-flags": "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.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -13,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/plugin-openapi": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
-    "@voltro/sql-postgres": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/plugin-openapi": "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.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -13,20 +13,20 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/plugin-analytics-postgres": "0.28.0",
-    "@voltro/plugin-billing": "0.28.0",
-    "@voltro/plugin-multitenancy": "0.28.0",
-    "@voltro/plugin-notifications": "0.28.0",
-    "@voltro/plugin-presence": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
-    "@voltro/sql-postgres": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/plugin-analytics-postgres": "0.29.0",
+    "@voltro/plugin-billing": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/plugin-notifications": "0.29.0",
+    "@voltro/plugin-presence": "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.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-saas-starter/README.md

@@ -0,0 +1,103 @@
+# {{capProjectName}} {{capAppName}} — the full SaaS backend
+
+The whole SaaS loop wired end to end in ONE api — **sign up → hit a paywall →
+upgrade → invite a teammate** — composing two shipped plugins that are normally
+wired separately, plus a small tenant-scoped domain. Boots **zero-infra**
+(`store: 'memory'`, `mock` billing provider, in-process users).
+
+Pair it with the **frontend-saas** web template for the dashboard UI:
+
+```bash
+voltro init my-saas --api=api-saas-starter --web=frontend-saas
+```
+
+## What it composes
+
+- **Auth** ([`@voltro/plugin-auth`](https://voltro.cloud/docs/plugins/auth)) —
+  password **sign-up / sign-in / sign-out** over an HttpOnly **session cookie**,
+  and `voltroPasswordStrategy` resolving that cookie into a typed `Subject` on
+  every rpc/ws call. `session.me` returns it (the frontend's SSR gate reads it).
+- **Billing** ([`@voltro/plugin-billing`](https://voltro.cloud/docs/plugins/overview)) —
+  subscriptions + **entitlements** over the in-memory `mock` provider. `plans`
+  is the single source of tier→quota truth: `free` caps `projects` at 3 and
+  `seats` at 1; `pro` lifts both.
+- **Domain** — tenant-scoped `projects` + `invites`. `projects.create` spends
+  the `projects` quota; `invites.create` spends the `seats` quota. Over quota →
+  typed **`EntitlementExceeded`** (the paywall signal), the row never written.
+
+## The loop
+
+| Step | Call | Result |
+|---|---|---|
+| Sign up | `POST /auth/sign-up` | session cookie; lands in tenant `acme` on the `free` plan |
+| Work | `projects.create` ×3 | ok |
+| **Paywall** | `projects.create` (4th) | typed `EntitlementExceeded { entitlement: 'projects', limit: 3 }` |
+| Upgrade | `billing.startCheckout` → `pro` | `projects` becomes `unlimited`, `seats` → 10 |
+| Invite | `invites.create` | spends a `seats` entitlement |
+| Buy seats | `billing.changeSeats` | raises the seat quantity |
+
+`billing.*` (`subscription`, `startCheckout`, `changePlan`, `changeSeats`,
+`invoices`) and `/auth/*` are contributed by the plugins — you don't author them.
+
+## Run it
+
+```bash
+voltro dev .
+# → http://localhost:4000   (rpc + /auth/* HTTP routes)
+```
+
+`voltro dev` mints a unique `VOLTRO_SESSION_SECRET` into a gitignored
+`.env.local` on first boot — no secret ships with the template.
+
+### Try the loop (curl)
+
+```bash
+# Sign up (CSRF-protected — grab a token first, keep the cookie jar)
+curl -s -c jar.txt http://localhost:4000/auth/csrf                     # → { "csrfToken": "<csrf>" }
+curl -s -b jar.txt -c jar.txt -X POST http://localhost:4000/auth/sign-up \
+  -H 'content-type: application/json' -H 'x-csrf-token: <csrf>' \
+  -d '{"email":"ada@example.com","password":"hunter2hunter2"}'
+
+# Create projects — the free plan allows 3, the 4th trips the paywall
+for i in 1 2 3 4; do
+  curl -s -b jar.txt -X POST http://localhost:4000/_voltro/inspect/invoke \
+    -H 'content-type: application/json' \
+    -d "{\"tag\":\"projects.create\",\"input\":{\"name\":\"Project $i\"}}"
+done
+# → the 4th: { "ok": false, "error": { "_tag": "EntitlementExceeded", "entitlement": "projects", "limit": 3, … } }
+```
+
+## Files
+
+```
+app.config.ts                 authRoutesPlugin + voltroPasswordStrategy + billingPlugin (free/pro plans)
+database/schema.ts            core actors/tenants + tenant-scoped projects + invites
+actions/me.action.ts(.server) session.me — the resolved Subject (SSR gate reads it)
+queries/
+  projects.list.query.*       live, tenant-scoped subscription
+  invites.list.query.*        live, tenant-scoped subscription
+mutations/
+  projects.create.*           entitlement-gated (projects quota → paywall)
+  invites.create.*            entitlement-gated (seats quota)
+tests/                        descriptor pins + tenant isolation + session.me
+```
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| Durable accounts | swap `memoryUserStore()` for `postgresUserStore({ sql })` + `store: 'postgres'` |
+| Real Stripe checkout | `billingPlugin({ provider: 'stripe', apiKey, webhookSecret, plans })` with real `priceId`s |
+| Email flows (magic-link, reset) | pass `sendEmail: mailSender(mailService)` from `@voltro/plugin-mail` |
+| Cookie hardening | `cookieSecure: true` (+ `cookieDomain`) — already ON in production here |
+
+## Anti-patterns
+
+- **Authoring your own `billing.*` / `/auth/*` procedures.** The plugins own
+  those namespaces — boot fails on a collision. Use the plugin routes + services.
+- **Skipping the entitlement gate on a paid action.** A scope says "may you call
+  this"; an entitlement says "do you have quota left". `requireEntitlement` is
+  one line and fails closed — that's what makes the paywall real.
+- **Reading `VOLTRO_SESSION_SECRET` at config time for a fallback.** The plugin
+  reads it per request, after the env gate mints it. A hardcoded fallback is a
+  published signing key.

package/templates/apps/api-saas-starter/actions/me.action.server.ts

@@ -0,0 +1,18 @@
+// Executor for `session.me`. Reads the Subject the AuthMiddleware resolved (via
+// voltroPasswordStrategy reading the session cookie) and returns it.
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (_input: Record<string, never>, ctx: AppContext) => {
+  const subject = ctx.request.subject as {
+    readonly type: string
+    readonly id: string | null
+    readonly tenantId: string | null
+  }
+  return {
+    type:     subject.type,
+    id:       subject.id ?? null,
+    tenantId: subject.tenantId ?? null,
+  }
+}
+
+export default execute

package/templates/apps/api-saas-starter/actions/me.action.ts

@@ -0,0 +1,20 @@
+// `session.me` — returns the caller's resolved identity. This is the proof the
+// auth loop works end-to-end, and the frontend's SSR auth gate reads it: call
+// it with no session cookie and you get an anonymous Subject; sign in via POST
+// /auth/sign-in (which sets the cookie), call it again, and
+// `voltroPasswordStrategy` has resolved that cookie into a `user` Subject.
+// Browser-safe descriptor — no server imports here.
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const me = defineAction({
+  name:  'session.me',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    // 'anonymous' | 'user' | 'apiKey' | 'serviceAccount'
+    type:     Schema.String,
+    // null while anonymous; the user id once signed in.
+    id:       Schema.NullOr(Schema.String),
+    tenantId: Schema.NullOr(Schema.String),
+  }),
+})