@voltro/cli 0.28.0 → 0.30.0

package/templates/apps/api-cms/content/blogPost.contentType.ts

@@ -0,0 +1,39 @@
+// A content type declared as CODE — typesafe, version-controlled, PR-reviewed.
+//
+// Each field uses the CMS `Schema` field DSL (distinct from the @voltro/database
+// column DSL). `defineContentType` resolves this to a descriptor the editor
+// introspects to generate its form, and `contentTypeToEntities` (in
+// database/schema.ts) compiles the fields DOWN to real `blogPost_drafts` +
+// `blogPost_published` columns.
+//
+// Imported from the MAIN `@voltro/cms` entry because it runs server-side at
+// discovery time (schema.ts imports it). The browser-safe field DSL is the same
+// object either way — the editor page never imports this file; it fetches the
+// resolved descriptor over rpc (content.types).
+import { Schema, defineContentType, derivedFrom, slugify } from '@voltro/cms'
+
+export const blogPost = defineContentType({
+  name:        'blogPost',
+  displayName: 'Blog post',
+  pluralName:  'Blog posts',
+  fields: {
+    // Single-line text, capped at 200 chars (validated at save time).
+    title: Schema.String.pipe(Schema.maxLength(200)),
+    // Computed-on-save from `title` (a caller value is overwritten), constrained
+    // to url-safe chars, and UNIQUE per tenant — the derived tables get a real
+    // composite (tenantId, slug) DB UNIQUE.
+    slug: Schema.String.pipe(
+      Schema.pattern(/^[a-z0-9-]+$/),
+      Schema.unique(),
+      derivedFrom('title', slugify),
+    ),
+    // Rich text stored as a JSON document (e.g. a TipTap doc). Images allowed.
+    body: Schema.RichText({ allowImages: true }),
+    // Optional short summary → nullable column + non-required editor input.
+    excerpt: Schema.String.pipe(Schema.maxLength(280)).optional(),
+    // Optional publish date the consumer app can order/filter by.
+    publishedAt: Schema.DateTime.optional(),
+  },
+  // Which columns the editor's list view shows + its default sort.
+  list: { columns: ['title', 'slug', 'status'], defaultSort: { field: 'updatedAt', dir: 'desc' } },
+})

package/templates/apps/api-cms/content/index.ts

@@ -0,0 +1,18 @@
+// The registry of content types this CMS serves. Adding a type = declaring it
+// in a `*.contentType.ts` file and adding it here (+ its entities in
+// database/schema.ts). The handlers look a type up by name through
+// `contentTypeByName`; the editor lists them via the content.types action.
+import type { ContentType } from '@voltro/cms'
+import { blogPost } from './blogPost.contentType'
+import { page } from './page.contentType'
+
+export { blogPost, page }
+
+export const contentTypes: ReadonlyArray<ContentType> = [blogPost, page]
+
+/** Look a content type up by name — the guard the dynamic handlers run before
+ *  touching a `<type>_drafts` / `<type>_published` table (an unknown name never
+ *  reaches a table string). */
+export const contentTypeByName: ReadonlyMap<string, ContentType> = new Map(
+  contentTypes.map((t) => [t.name, t]),
+)

package/templates/apps/api-cms/content/page.contentType.ts

@@ -0,0 +1,24 @@
+// A second content type — a generic marketing/site page. Shows that adding a
+// content type is a single file: declare it here, register its entities in
+// database/schema.ts, and the editor picks it up automatically (it fetches the
+// registered types over content.types).
+import { Schema, defineContentType, derivedFrom, slugify } from '@voltro/cms'
+
+export const page = defineContentType({
+  name:        'page',
+  displayName: 'Page',
+  pluralName:  'Pages',
+  fields: {
+    title: Schema.String.pipe(Schema.maxLength(200)),
+    slug: Schema.String.pipe(
+      Schema.pattern(/^[a-z0-9-]+$/),
+      Schema.unique(),
+      derivedFrom('title', slugify),
+    ),
+    body: Schema.RichText(),
+    // A closed value set → `<select>` in the editor + a CHECK constraint.
+    layout: Schema.Literal('default', 'wide', 'landing'),
+    seoTitle: Schema.String.pipe(Schema.maxLength(70)).optional(),
+  },
+  list: { columns: ['title', 'slug', 'layout', 'status'], defaultSort: { field: 'updatedAt', dir: 'desc' } },
+})

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

@@ -0,0 +1,64 @@
+// Schema for the {{projectName}} CMS backend.
+//
+// The content TABLES aren't hand-declared — they're COMPILED from the content
+// types. `contentTypeToEntities(blogPost)` returns a `{ draft, published }` pair
+// (`blogPost_drafts` + `blogPost_published`), each already tenant-scoped
+// (`tenant()`, which pulls `audit()` transitively) and carrying the lifecycle
+// `status` column. Registering them in `databaseHandle` is what makes the
+// framework's auto-migrate create them across every dialect. There is no
+// discovery of `*.contentType.ts`; THIS import is the wiring.
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type ColumnDefinition,
+  type InferRow,
+  type Table,
+  type TableLike,
+} from '@voltro/database'
+import { contentTypeToEntities } from '@voltro/cms'
+import { blogPost, page } from '../content'
+
+// ---------- 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'),
+})
+
+// ---------- Derived content tables ----------
+
+// Compile each content type to its draft/published table pair. Exported so the
+// tests can build a schema registry over the SAME tables the app registers.
+export const blogEntities = contentTypeToEntities(blogPost)
+export const pageEntities = contentTypeToEntities(page)
+
+export type BlogPostDraft = InferRow<typeof blogEntities.draft>
+export type PageDraft = InferRow<typeof pageEntities.draft>
+
+// `contentTypeToEntities` returns the structural `TableLike` type (it hides the
+// concrete generic), but each value IS a real `table(...).with(tenant())` at
+// runtime — exactly what `databaseHandle` registers. This boundary cast bridges
+// the two: no `any`, no behavioural change, just the concrete table type the
+// handle's inference expects.
+const asTable = (t: TableLike): Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string> =>
+  t as unknown as Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>
+
+export const database = databaseHandle({
+  actors,
+  tenants,
+  blogPostDrafts:    asTable(blogEntities.draft),
+  blogPostPublished: asTable(blogEntities.published),
+  pageDrafts:        asTable(pageEntities.draft),
+  pagePublished:     asTable(pageEntities.published),
+})

package/templates/apps/api-cms/mutations/content.publish.mutation.server.ts

@@ -0,0 +1,19 @@
+// Effect-mode executor. `publishEffect` runs `publish` inside `store.transactional`
+// (draft copy + status flip land atomically) and fails typed `ContentNotFound`
+// when the id has no draft in the caller's scope — caught into `{ ok: false }`.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { publishEffect } from '@voltro/cms'
+import { contentTypeByName } from '../content'
+
+const execute = (input: { type: string; id: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const ct = contentTypeByName.get(input.type)
+    if (ct === undefined) return { ok: false as const }
+    return yield* publishEffect(ctx.store, ct, input.id).pipe(
+      Effect.map((row) => ({ ok: true as const, id: row['id'] as string, status: row['status'] as string })),
+      Effect.catchTag('ContentNotFound', () => Effect.succeed({ ok: false as const })),
+    )
+  })
+
+export default execute

package/templates/apps/api-cms/mutations/content.publish.mutation.ts

@@ -0,0 +1,15 @@
+// `content.publish` — copy a draft into `<type>_published` (atomic per row) and
+// mark the draft published. Both tables are reactive, so a publish wakes live
+// consumer subscriptions. A missing draft (including another tenant's, which
+// reads as absent) comes back as `{ ok: false }` rather than an error.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const publishContent = defineMutation({
+  name: 'content.publish',
+  input: Schema.Struct({ type: Schema.NonEmptyString, id: Schema.NonEmptyString }),
+  output: Schema.Union(
+    Schema.Struct({ ok: Schema.Literal(true), id: Schema.String, status: Schema.String }),
+    Schema.Struct({ ok: Schema.Literal(false) }),
+  ),
+})

package/templates/apps/api-cms/mutations/content.saveDraft.mutation.server.ts

@@ -0,0 +1,36 @@
+// Effect-mode executor. `saveDraftEffect` runs the pipeline over the
+// request-scoped `ctx.store` (a DataStore): it derives the computed fields,
+// validates, and writes to `<type>_drafts` — the tenant/audit columns stamped
+// by the store spine. Its typed failures ride the Effect error channel, so we
+// `catchTag` them into the result union instead of letting them become a 500.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { saveDraftEffect } from '@voltro/cms'
+import { contentTypeByName } from '../content'
+
+const execute = (input: { type: string; values: Record<string, unknown> }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const ct = contentTypeByName.get(input.type)
+    if (ct === undefined) {
+      return {
+        ok: false as const,
+        violations: [{ field: 'type', rule: 'unknown', message: `unknown content type '${input.type}'` }],
+      }
+    }
+    return yield* saveDraftEffect(ctx.store, ct, input.values).pipe(
+      Effect.map((row) => ({ ok: true as const, id: row['id'] as string, status: row['status'] as string })),
+      // A rule violation → annotate the form; not an error.
+      Effect.catchTag('ContentValidationFailed', (e) =>
+        Effect.succeed({ ok: false as const, violations: [...e.violations] }),
+      ),
+      // A caller-pinned id owned by another tenant → refuse, surfaced the same way.
+      Effect.catchTag('ContentIdConflict', (e) =>
+        Effect.succeed({
+          ok: false as const,
+          violations: [{ field: 'id', rule: 'conflict', message: `id '${e.id}' belongs to another tenant` }],
+        }),
+      ),
+    )
+  })
+
+export default execute

package/templates/apps/api-cms/mutations/content.saveDraft.mutation.ts

@@ -0,0 +1,32 @@
+// `content.saveDraft` — upsert a draft. The executor runs the CMS pipeline
+// (derive `slug` from `title`, validate every field rule, write to
+// `<type>_drafts`). Validation failures don't crash: they come back as a typed
+// RESULT union (`{ ok: false, violations }`) the editor annotates the form from,
+// mirroring `contentViolations` on the client. Omit `values.id` to create; pass
+// it to update your own draft in place.
+//
+// The descriptor stays pure effect/Schema (no @voltro/cms import) so it is
+// browser-safe with nothing extra to pull into the bundle — the result union is
+// what carries the validation outcome across the wire.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+const Violation = Schema.Struct({
+  field:   Schema.String,
+  rule:    Schema.String,
+  message: Schema.String,
+})
+
+export const saveDraft = defineMutation({
+  name: 'content.saveDraft',
+  input: Schema.Struct({
+    type:   Schema.NonEmptyString,
+    // Arbitrary per-type field values (may carry `id` to update an existing
+    // draft). Validated on the server against the content type's rules.
+    values: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+  }),
+  output: Schema.Union(
+    Schema.Struct({ ok: Schema.Literal(true), id: Schema.String, status: Schema.String }),
+    Schema.Struct({ ok: Schema.Literal(false), violations: Schema.Array(Violation) }),
+  ),
+})

package/templates/apps/api-cms/mutations/content.unpublish.mutation.server.ts

@@ -0,0 +1,19 @@
+// Effect-mode executor. `unpublishEffect` deletes the published row + reverts
+// the draft inside a transaction; `ContentNotFound` (no published row in scope)
+// is caught into `{ ok: false }`.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { unpublishEffect } from '@voltro/cms'
+import { contentTypeByName } from '../content'
+
+const execute = (input: { type: string; id: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const ct = contentTypeByName.get(input.type)
+    if (ct === undefined) return { ok: false }
+    return yield* unpublishEffect(ctx.store, ct, input.id).pipe(
+      Effect.map(() => ({ ok: true })),
+      Effect.catchTag('ContentNotFound', () => Effect.succeed({ ok: false })),
+    )
+  })
+
+export default execute

package/templates/apps/api-cms/mutations/content.unpublish.mutation.ts

@@ -0,0 +1,11 @@
+// `content.unpublish` — take a published row down: delete it from
+// `<type>_published` and flip the draft back to `status: 'draft'` (atomic per
+// row). A row with no published copy in the caller's scope → `{ ok: false }`.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const unpublishContent = defineMutation({
+  name: 'content.unpublish',
+  input: Schema.Struct({ type: Schema.NonEmptyString, id: Schema.NonEmptyString }),
+  output: Schema.Struct({ ok: Schema.Boolean }),
+})

package/templates/apps/api-cms/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.30.0",
+    "@voltro/cms": "0.30.0",
+    "@voltro/database": "0.30.0",
+    "@voltro/env": "0.30.0",
+    "@voltro/plugin-auth": "0.30.0",
+    "@voltro/plugin-multitenancy": "0.30.0",
+    "@voltro/protocol": "0.30.0",
+    "@voltro/runtime": "0.30.0",
+    "@voltro/sql-postgres": "0.30.0",
+    "effect": "^3.22.0"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.30.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

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-collab/README.md

@@ -0,0 +1,70 @@
+# {{projectName}} / {{appName}}
+
+Voltro collaborative-editing backend (template: **api-collab**).
+
+Real-time **convergent** editing on a `crdtText()` column — concurrent edits
+from many clients merge without a last-write-wins loser, authoritatively on the
+server, then broadcast over the reactive engine. Zero infra (`store: 'memory'`):
+the merge and the broadcast are both in-process, so two browser tabs pointed at
+one `voltro dev` collaborate with no database and no external service.
+
+## Boot
+
+```bash
+pnpm install                # at the repo root
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000
+# → ws://localhost:4000/ws
+```
+
+## Pair it with a frontend
+
+`api-collab` exposes the `documents.list` subscription + `documents.create` /
+`documents.setBody` mutations that [`frontend-collab`](../frontend-collab)
+binds a collaborative editor to. Scaffold both together:
+
+```bash
+voltro create-project collab --api=api-collab --web=frontend-collab
+```
+
+## What's in here
+
+| File | Role |
+|---|---|
+| `app.config.ts`                              | App declaration (`store: 'memory'`). |
+| `database/schema.ts`                         | `documents` table — a `crdtText()` `body`, plus `tenant()` + `localFirst()`. |
+| `mutations/documents.create.mutation.ts`     | Create a document (title only; `body` starts empty). |
+| `mutations/documents.setBody.mutation.ts`    | The CRDT write — a client's encoded update; the runtime merges it. |
+| `queries/documents.query.ts`                 | `documents.list` streaming subscription. |
+| `tests/documents.setBody.test.ts`            | Convergence proof — two concurrent edits merge, order-independently. |
+
+## How the CRDT merge works
+
+`body: crdtText()` stores the encoded CRDT state as an opaque `bytes` blob. A
+client edits its LOCAL handle and sends the encoded update to
+`documents.setBody`. The handler writes it like any column — but because `body`
+is CRDT-managed, the runtime's MutationStore intercepts the write, reads the
+stored state, and folds the incoming update in with `mergeCrdtStates` (from
+`@voltro/local-first`) **before** persisting. That authoritative server merge is
+the convergence guarantee; the reactive engine then pushes the merged row to
+every subscriber.
+
+```
+ Client A ──update A──►┐
+                       ├─► documents.setBody ─► store.update('documents', id, { body })
+ Client B ──update B──►┘                          └─ runtime folds update into STORED
+                                                     state (mergeCrdtStates) → converges
+                                                        └─► reactive delta ─► all subscribers
+```
+
+`tests/documents.setBody.test.ts` proves it with no database: `ctx.store` from
+`@voltro/testing` is the same mixin-wrapped store as production, so the merge
+runs exactly as it does at runtime.
+
+## Multi-tenancy note
+
+The dev `AuthMiddleware` resolves the tenant from the `x-tenant` header,
+defaulting to `'acme'`. The `documents` table carries the `tenant()` mixin, so
+reads/writes are auto-scoped and `documents.create` guards that the submitted
+`tenantId` matches the caller's (a typed `TenantMismatch` otherwise). Wire real
+auth before production (see the authentication docs).

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

@@ -0,0 +1,28 @@
+// Collaborative-editing backend for the {{projectName}} project. Read by `voltro dev`.
+//
+// This is the LOCAL-FIRST / CRDT template — it exposes a `documents` table
+// whose `body` is a `crdtText()` column. When two clients edit the same body
+// concurrently, the runtime folds each incoming update into the stored state
+// with an authoritative SERVER-SIDE CRDT merge (on the write path, before the
+// row is written) so their edits CONVERGE — no last-write-wins loser — and the
+// reactive engine broadcasts the merged result to every subscriber.
+//
+// `store: 'memory'` keeps it ZERO-INFRA: the merge + the broadcast are both
+// in-process, so two browser tabs pointed at one `voltro dev` collaborate with
+// no database, no Redis, no external service. Switch to `'postgres'` (or run
+// `voltro add redis` for a cross-instance broadcast) when you go distributed.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Typed environment — declared once, validated at boot (fail-fast) and read on
+// the server via `serverEnv` / `getSecret` from '@voltro/env/server'. Run
+// `voltro env` for the manifest.
+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,
+  env,
+}