@percepta/create 3.1.5 → 3.2.0

package/templates/monorepo/auth/src/drizzle/schema/index.ts

@@ -0,0 +1,5 @@
+export { accounts } from "./auth/accounts";
+export { sessions } from "./auth/sessions";
+export { verifications } from "./auth/verifications";
+export { groupMembers, groups } from "./groups";
+export { users } from "./users";

package/templates/monorepo/auth/src/drizzle/schema/users.ts

@@ -0,0 +1,6 @@
+import { createUsersTable } from "@percepta/access-control/drizzle";
+
+export const users = createUsersTable();
+
+export type User = typeof users.$inferSelect;
+export type NewUser = typeof users.$inferInsert;

package/templates/monorepo/auth/src/index.ts

@@ -0,0 +1 @@
+export { auth, type BetterAuthSession } from "./auth";

package/templates/monorepo/auth/src/scim/README.md

@@ -0,0 +1,6 @@
+# SCIM Placeholder
+
+SCIM `/Users` and `/Groups` endpoints are intentionally a follow-up project.
+When implemented, they should update the local `users`, `groups`, and
+`group_members` projection through the access-control `groupSync` ingestion
+contract so SpiceDB and Postgres stay aligned.

package/templates/monorepo/auth/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "declaration": false,
+    "declarationMap": false,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["drizzle.config.ts", "src/**/*.ts"]
+}

package/templates/monorepo/package.json.template

@@ -5,18 +5,30 @@
   "description": "__APP_TITLE__",
   "scripts": {
     "preinstall": "npx only-allow pnpm",
-    "dev": "pnpm -r --parallel run dev",
-    "build": "pnpm -r run build",
-    "clean": "pnpm -r run clean",
-    "lint": "pnpm -r --parallel --no-bail run lint",
-    "lint:fix": "pnpm -r --no-bail run lint:fix",
-    "test": "pnpm -r run test"
+    "setup": "pnpm -r --filter './packages/*' --if-present run docker:up && pnpm run access:apply-local && pnpm run auth:db:setup-and-migrate && pnpm -r --filter './packages/*' --if-present run db:setup-and-migrate && pnpm -r --filter './packages/*' --if-present run db:seed",
+    "dev": "pnpm -r --parallel --if-present run dev",
+    "build": "pnpm -r --if-present run build",
+    "clean": "pnpm -r --if-present run clean",
+    "lint": "pnpm -r --parallel --no-bail --if-present run lint",
+    "lint:fix": "pnpm -r --no-bail --if-present run lint:fix",
+    "test": "pnpm -r --if-present run test",
+    "access:merge": "percepta-access-control merge --apps-dir \"$PWD/packages\" --out-dir access",
+    "access:validate": "percepta-access-control validate --apps-dir \"$PWD/packages\"",
+    "access:apply": "pnpm run access:merge && percepta-access-control apply --schema access/merged.zed --applications access/applications.generated.json",
+    "access:apply-local": "pnpm run access:merge && percepta-access-control apply --schema access/merged.zed --applications access/applications.generated.json --endpoint localhost:50051 --insecure --key dev-spicedb-token",
+    "access:seed-grants": "percepta-access-control seed-grants --fixture access/dev-grants.yaml",
+    "access:seed-groups": "percepta-access-control seed-groups",
+    "access:bootstrap-customer-admin": "percepta-access-control bootstrap-customer-admin",
+    "access:apply-bootstrap-grants": "percepta-access-control apply-bootstrap-grants --fixture access/bootstrap-grants.yaml",
+    "access:reconcile": "percepta-access-control reconcile --input access/reconcile.yaml",
+    "auth:db:setup-and-migrate": "pnpm --dir auth run db:setup-and-migrate"
   },
   "engines": {
     "node": ">=20",
     "pnpm": ">=9"
   },
   "devDependencies": {
+    "@percepta/access-control": "0.3.2",
     "@types/node": "^24.1.0",
     "eslint": "^9.18.0",
     "rimraf": "^5.0.5",

package/templates/monorepo/pnpm-workspace.yaml

@@ -1,2 +1,3 @@
 packages:
   - "packages/*"
+  - "auth"

package/templates/webapp/AGENTS.md

@@ -1,6 +1,6 @@
 # Webapp Template
 
-Next.js 15 full-stack application scaffolded from the Mosaic webapp template via `@percepta/create`. Uses React 19, TypeScript, Tailwind CSS v4, tRPC, Drizzle ORM, Better Auth, and Inngest.
+Next.js 15 full-stack application scaffolded from the Mosaic webapp template via `@percepta/create`. Uses React 19, TypeScript, Tailwind CSS v4, tRPC, Drizzle ORM, Better Auth, SpiceDB access control, and Inngest.
 
 ## Build & Dev Commands
 
@@ -8,17 +8,21 @@ Next.js 15 full-stack application scaffolded from the Mosaic webapp template via
 - `pnpm build` — production build
 - `pnpm lint` — run ESLint
 - `pnpm test` — run Vitest tests
-- `pnpm docker:up` / `pnpm docker:down` — start PostgreSQL and wait for health / stop PostgreSQL
+- `pnpm docker:up` / `pnpm docker:down` — start PostgreSQL and SpiceDB, waiting for health, or stop them
+- `pnpm access:validate` — validate access schema and manifest
+- `pnpm access:apply-local` — apply merged customer access schema to local SpiceDB
+- `pnpm auth:db:setup-and-migrate` — setup and migrate the shared customer auth database
 - `pnpm inngest:dev` — start local Inngest dev server when working on background jobs
 - `pnpm db:generate` — generate Drizzle migrations
 - `pnpm db:migrate` — apply migrations
 - `pnpm db:setup-and-migrate` — create DB + migrate
-- `pnpm db:studio` — open Drizzle Studio
-- `pnpm db:seed` — seed default dev user (admin@example.com / password)
+- `pnpm db:studio` — setup/migrate the database, then open Drizzle Studio
+- `pnpm db:seed` — seed default shared-auth dev users and local access grants (admin@example.com and user@example.com / password)
 
 **Package manager**: Always use `pnpm`, never `npm` or `yarn`.
 
-Local development only requires Postgres by default. Run Inngest locally when a workflow needs it. Do not run a local LGTM/Langfuse stack unless you are specifically debugging telemetry; those are wired by the Ryvn environment for deploys. If local LLM calls are needed, `pnpm dev` loads shared provider keys from `~/.config/percepta/create.env` when it exists.
+Local development requires PostgreSQL and SpiceDB. Run Inngest locally when a workflow needs it. Do not run a local LGTM/Langfuse stack unless you are specifically debugging telemetry; those are wired by the Ryvn environment for deploys.
+If local LLM calls are needed, `pnpm dev` loads shared provider keys from `~/.config/percepta/create.env` when it exists.
 
 ## Code Style
 
@@ -34,6 +38,7 @@ Local development only requires Postgres by default. Run Inngest locally when a
 
 ```
 src/                        # Application source
+├── access/                 # SpiceDB schema and manifest
 ├── app/                    # Next.js App Router pages, layouts, and API route handlers
 ├── components/             # React components
 ├── config/                 # Env config (clientEnvConfig, getEnvConfig)
@@ -45,6 +50,7 @@ src/                        # Application source
 │   ├── trpc.ts             # Context & procedure builders
 │   └── api/root.ts         # Root appRouter
 ├── services/
+│   ├── access/             # App access-control runtime binding
 │   ├── inngest/            # Background job definitions
 │   ├── langfuse/           # LLM observability
 │   ├── llm/                # LLM provider selection and call helpers
@@ -194,6 +200,7 @@ Detailed how-to guides for each major stack component. Read the relevant guide w
 | LLM Calls | [agent-skills/llm.md](agent-skills/llm.md) | Adding backend model calls, streaming, or structured generation |
 | LLM Observability (Langfuse) | [agent-skills/langfuse.md](agent-skills/langfuse.md) | App uses LLMs and needs trace/eval monitoring |
 | Database (Drizzle) | [agent-skills/database.md](agent-skills/database.md) | Adding tables, writing migrations, querying data |
+| Access Control (SpiceDB) | [agent-skills/access-control.md](agent-skills/access-control.md) | Adding Zed policy, app roles, permissioned resources, or group sync |
 | Deployment (Ryvn) | [agent-skills/ryvn.md](agent-skills/ryvn.md) | Ryvn overview and Percepta environment context |
 | Deploy to percepta-test | [agent-skills/deploy.md](agent-skills/deploy.md) | Step-by-step deploy using the pre-scaffolded `deploy/ryvn/` IaC files |
 | Build App (Oneshot) | [agent-skills/oneshot.md](agent-skills/oneshot.md) | Building a complete app from requirements end-to-end |
@@ -215,7 +222,7 @@ Client-side usage via `src/lib/trpc.ts`.
 
 ### Authentication
 
-Better Auth configured in `src/lib/auth/`. Email/password credentials enabled by default.
+Better Auth is configured in the customer monorepo's shared `@__REPO_NAME__/auth` package. The app imports it through `src/lib/auth/` for local session validation.
 
 - **Server-side**: `auth.api.getSession({ headers: await headers() })` — get session in server components or tRPC context
 - **Client-side**: `authClient.useSession()` — React hook from `src/lib/auth-client.ts`

package/templates/webapp/README.md

@@ -7,6 +7,7 @@ A production-ready Next.js application with authentication, database, logging, b
 - **Next.js 15** with App Router
 - **Authentication** via Better Auth with email/password credentials
 - **Database** with PostgreSQL, Drizzle ORM, and migrations
+- **Access Control** with SpiceDB schema authoring and manifest validation
 - **Logging** with Pino and structured safe/unsafe data separation
 - **Background Jobs** with Inngest
 - **LLM Calls** with a provider-backed `LLMService`
@@ -16,23 +17,21 @@ A production-ready Next.js application with authentication, database, logging, b
 
 ## Quick Start
 
-### 1. Start the Database
+### 1. Configure Environment
 
-```bash
-pnpm docker:up
-```
+Copy `.env.example` to `.env.local` and configure any app-specific environment variables.
 
-### 2. Initialize the Database
+### 2. Run Setup
 
 ```bash
-pnpm db:setup-and-migrate
+pnpm run setup
 ```
 
-### 3. Configure Environment
-
-Copy `.env.example` to `.env.local` and configure your environment variables.
+This starts local PostgreSQL and SpiceDB, applies the local access schema,
+sets up the shared customer auth database, runs app migrations, and seeds dev
+users.
 
-### 4. Start Inngest When Using Background Jobs
+### 3. Start Inngest When Using Background Jobs
 
 ```bash
 pnpm inngest:dev
@@ -40,7 +39,7 @@ pnpm inngest:dev
 
 Run this in a separate terminal when the app has Inngest functions or you want the local Inngest dashboard.
 
-### 5. Start Development Server
+### 4. Start Development Server
 
 ```bash
 pnpm dev
@@ -62,6 +61,7 @@ ANTHROPIC_API_KEY=sk-ant-...
 
 ```
 src/
+├── access/                 # SpiceDB schema and manifest
 ├── app/                    # Next.js App Router pages, layouts, and API route handlers
 ├── components/             # React components
 ├── config/                 # Environment configuration
@@ -72,6 +72,7 @@ src/
 ├── services/               # Business logic services
 │   ├── inngest/            # Background job definitions
 │   ├── langfuse/           # LLM observability
+│   ├── access/             # App access-control runtime binding
 │   ├── llm/                # LLM provider selection and call helpers
 │   └── logger/             # Structured logging
 └── utils/                  # Utility functions
@@ -85,16 +86,18 @@ src/
 | `pnpm build` | Build for production |
 | `pnpm start` | Start production server |
 | `pnpm lint` | Run ESLint |
-| `pnpm docker:up` | Start PostgreSQL container and wait until it is healthy |
-| `pnpm docker:down` | Stop PostgreSQL container |
+| `pnpm docker:up` | Start PostgreSQL and SpiceDB containers and wait until they are healthy |
+| `pnpm docker:down` | Stop PostgreSQL and SpiceDB containers |
+| `pnpm access:validate` | Validate the access manifest and schema |
+| `pnpm access:apply-local` | Apply the merged customer access schema to local SpiceDB |
+| `pnpm auth:db:setup-and-migrate` | Setup and migrate the shared customer auth database |
 | `pnpm inngest:dev` | Start the local Inngest dev server for this app |
 | `pnpm db:generate` | Generate Drizzle migrations |
 | `pnpm db:migrate` | Run database migrations |
 | `pnpm db:setup` | Create database and user |
 | `pnpm db:setup-and-migrate` | Setup and migrate database |
-| `pnpm db:studio` | Open Drizzle Studio |
-| `pnpm db:create-user` | Create a user account |
-| `pnpm db:seed` | Seed default dev user |
+| `pnpm db:studio` | Setup/migrate the database, then open Drizzle Studio |
+| `pnpm db:seed` | Seed default shared-auth dev users and local access grants |
 
 ## Logging
 
@@ -122,7 +125,7 @@ logger.error(
 
 ## Authentication
 
-This app uses [Better Auth](https://better-auth.com) for authentication with email/password credentials enabled by default.
+This app consumes the customer monorepo's shared [Better Auth](https://better-auth.com) package, `@__REPO_NAME__/auth`. The app still serves local development auth routes, but the users, sessions, accounts, groups, and group memberships live in the shared customer auth database.
 
 Required environment variables:
 
@@ -134,9 +137,14 @@ BETTER_AUTH_URL=http://localhost:3000
 To create a dev user:
 ```bash
 pnpm db:seed
-# Creates admin@example.com / password
+# Creates admin@example.com / password as an app admin
+# Creates user@example.com / password as a non-admin app member
 ```
 
+## Access Control
+
+App permissions are authored in `src/access/schema.zed`; `src/access/access.manifest.ts` describes the app integration surface for admin UI, seed scripts, and resource inventories. For the full workflow, read [agent-skills/access-control.md](agent-skills/access-control.md).
+
 ## Environment Variables
 
 ### Application
@@ -169,6 +177,14 @@ Generate a secret key:
 node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
 ```
 
+### Access Control
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SPICEDB_ENDPOINT` | SpiceDB gRPC endpoint | `localhost:50051` |
+| `SPICEDB_PRESHARED_KEY` | SpiceDB preshared key | `dev-spicedb-token` |
+| `SPICEDB_INSECURE` | Use insecure local gRPC transport | `true` |
+
 ### Inngest (Background Jobs)
 
 | Variable | Description |

package/templates/webapp/agent-skills/access-control.md

@@ -0,0 +1,301 @@
+# Access Control
+
+Use this guide when adding permissioned resources, changing Zed policy, assigning app roles, debugging denied checks, or wiring identity/group sync.
+
+## Mental Model
+
+The customer monorepo has one shared identity layer and one shared SpiceDB deployment:
+
+- `../../auth` owns Better Auth, `users`, `groups`, and `group_members`.
+- `../../access` merges every app's Zed schema with the shared `core/*` schema and applies customer-level topology.
+- This app owns only its app namespace, app-defined roles, and app resource relationships.
+
+There are three separate authorization layers:
+
+| Layer | Owner | Stored as |
+|-------|-------|-----------|
+| Customer admins | Customer bootstrap / Applications admin | `core/customer:main#admin@core/user:<users.id>` |
+| Application access | Customer Applications admin | `core/application:<app>#owner/member@core/user:<users.id>` or `core/group:<groups.id>#member` |
+| App roles/resources | This app's owner/admin UI and app code | `<app>/system:main#<role>@<subject>` and app resource relationships |
+
+Customer admins do not automatically get application access. To enter an app, a user or group must be an application `owner` or `member`.
+
+## Source Of Truth
+
+- `src/access/schema.zed` is the policy source of truth. SpiceDB evaluates this directly.
+- `src/access/access.manifest.ts` is integration metadata for TypeScript, admin UI, seed scripts, and resource inventories. It should describe what the app uses; it should not invent policy that is missing from Zed.
+
+After changing `schema.zed` or `access.manifest.ts`, run:
+
+```bash
+pnpm access:validate
+```
+
+PR CI runs the customer-level access validation, which merges every app schema
+and checks the schema/manifest contract.
+
+## Naming Rules
+
+Every app-authored SpiceDB definition must live under this app's namespace:
+
+```zed
+definition __APP_NAME_SNAKE__/system {
+  relation application: core/application
+  relation admin: core/user | core/group#member
+
+  permission access_app = application->access
+  permission manage_roles = access_app & (application->owner + admin)
+}
+```
+
+Use canonical shared identity refs:
+
+- Users: `core/user:<users.id>`
+- Groups: `core/group:<groups.id>#member`
+- Applications: `core/application:<appNamespace>`
+- System singleton: `<appNamespace>/system:main`
+
+Do not use email addresses, IdP external IDs, group slugs, or display names in SpiceDB refs. Resolve those values to shared `auth` table IDs first.
+
+## Application Access
+
+Application access means "can open this app at all." It comes from the customer-level `core/application` object.
+
+The starter system permission is:
+
+```zed
+permission access_app = application->access
+```
+
+The generated app gates the protected app layout with `canAccessApplication()`. Keep that gate in place for authenticated app pages. In tRPC, `protectedProcedure` means authenticated, `appProcedure` adds the default app-access gate, and `requirePermission` should be used for resource-specific checks.
+
+For resource permissions that should only be available inside the app, include `system->access_app` in the Zed expression or make the permission depend on another permission that does. If a permission is intentionally usable without app enrollment, list it in `externallyShareablePermissions` in the manifest.
+
+## App-Defined Roles
+
+App roles are static roles authored by the app builder in Zed and assigned by app owners/admins at runtime.
+
+To add a role:
+
+1. Add a relation to `<appNamespace>/system` in `schema.zed`.
+2. Include the role in `system.assignableRoles` in `access.manifest.ts` if app owners may assign it.
+3. Run `pnpm access:validate`.
+
+Example:
+
+```zed
+definition __APP_NAME_SNAKE__/system {
+  relation application: core/application
+  relation admin: core/user | core/group#member
+  relation hr_admin: core/user | core/group#member
+
+  permission access_app = application->access
+  permission manage_roles = access_app & (application->owner + admin)
+}
+```
+
+```ts
+import { defineAccessManifest } from "@percepta/access-control";
+
+export const accessManifest = defineAccessManifest({
+  // ...
+  system: {
+    // ...
+    assignableRoles: ["admin", "hr_admin"],
+  },
+} as const);
+```
+
+Role assignment is additive. Assigning `admin` and then `hr_admin` leaves both grants in place until each one is revoked.
+
+## Permissioned Resources
+
+Model app data as resource definitions when access varies by object or relationship.
+
+Example for a people app:
+
+```zed
+definition __APP_NAME_SNAKE__/employee {
+  relation system: __APP_NAME_SNAKE__/system
+  relation employee_user: core/user
+  relation manager: __APP_NAME_SNAKE__/employee
+
+  permission view_basic = system->access_app
+  permission view_private = system->access_app & (employee_user + manager->view_private + system->hr_admin)
+}
+```
+
+Then describe the resource in `access.manifest.ts`:
+
+```ts
+resources: {
+  employee: {
+    assignableRelations: ["employee_user", "manager"],
+    inventory: listEmployeesForAccessReconcile,
+    label: "Employee",
+    permissionsUsedByApp: ["view_basic", "view_private"],
+    ref: (id) => `__APP_NAME_SNAKE__/employee:${id}`,
+    systemLinked: true,
+    type: "__APP_NAME_SNAKE__/employee",
+  },
+},
+```
+
+Use `systemLinked: true` when the resource has a `relation system` and permissions depend on `system->...`. The access-control helpers call `touchResource()` when assigning resource relations, but resources created without relationships should call `touchResource()` after creation so app-level permissions can resolve.
+
+If `access:reconcile` should repair missing system links for a resource type, provide an `inventory` callback that yields the live resource IDs from Postgres. The library cannot discover app resources by itself.
+
+## Permissioned Postgres Tables
+
+When a Drizzle table backs a SpiceDB resource, bind the table to the resource manifest once. Keep Zed as the permission source of truth; the table binding only records object identity, relationship columns, and which field groups require which permissions.
+
+```ts
+import {
+  createColumnPermissionChecks,
+  definePermissionedResourceTable,
+} from "@percepta/access-control/drizzle";
+import { userSubjectRef } from "@percepta/access-control";
+import { accessManifest } from "@/access/access.manifest";
+import { employees } from "@/drizzle/schema";
+
+export const employeeAccess = definePermissionedResourceTable({
+  table: employees,
+  resource: accessManifest.resources.employee,
+  id: employees.id,
+  relations: {
+    employee_user: {
+      column: employees.userId,
+      subject: userSubjectRef,
+    },
+    manager: {
+      column: employees.managerEmployeeId,
+      subject: (employeeId: string) =>
+        accessManifest.resources.employee.ref(employeeId),
+    },
+  },
+  fieldGroups: {
+    basic: {
+      read: "view_basic",
+      columns: [employees.id, employees.name, employees.title],
+    },
+    compensation: {
+      read: "view_compensation",
+      write: "edit_compensation",
+      columns: [employees.salary, employees.bonus],
+    },
+  },
+} as const);
+```
+
+Use `createColumnPermissionChecks()` near serializers, mutation handlers, exports, and custom filters/sorts whenever the selected columns are dynamic:
+
+```ts
+const checks = createColumnPermissionChecks(employeeAccess, {
+  access: "read",
+  columns: [employees.salary],
+  id: employeeId,
+  subject: userSubjectRef(session.user.id),
+});
+const [canReadSalary] = await getAccessControl().permissions.canMany(checks);
+```
+
+Do not model ordinary Postgres columns as SpiceDB objects. Model business permissions in Zed, group columns under those permissions in the table binding, then enforce the binding at the API/data boundary.
+
+## App Code
+
+Use the app access service instead of constructing raw SpiceDB clients in feature code:
+
+```ts
+import { getAccessControl, toUserSubject } from "@/services/access/AppAccessControl";
+
+const allowed = await getAccessControl().permissions.can({
+  permission: "view_private",
+  resource: `__APP_NAME_SNAKE__/employee:${employeeId}`,
+  subject: toUserSubject(session.user.id),
+});
+```
+
+For tRPC procedures, use `protectedProcedure` for authentication-only calls, `appProcedure` for calls that should require app enrollment, and `requirePermission` for resource-specific authorization. Keep permission checks near the data load or mutation they protect.
+
+Use `canStrong` after writes that must observe a recent revocation immediately. Normal `can` checks use the request cache and standard SpiceDB read consistency.
+
+## Groups And Sync
+
+The local source of truth for groups is the shared `auth` package:
+
+- `groups` stores customer-global group IDs and upstream identifiers.
+- `group_members` stores the last observed membership projection.
+- SpiceDB group membership should be written through group sync/reconcile paths, not directly from app code.
+
+Development fixtures can seed groups into the shared auth projection. Future SCIM/JIT sync should write the same projection first, then mirror to SpiceDB. `access:reconcile` repairs SpiceDB to match the projection; it does not call the IdP itself.
+
+When assigning app roles or resource relations to a group, use the resolved shared group subject:
+
+```ts
+await getAccessControl().app.assignAppRole(
+  "admin",
+  `core/group:${groupId}#member`,
+);
+```
+
+## Shared Auth Boundary
+
+This app imports Better Auth from `@__REPO_NAME__/auth` via `src/lib/auth/index.ts`. The app does not own `users`, `groups`, `group_members`, sessions, accounts, or verification tables.
+
+When app code needs users for display, import from the shared auth package:
+
+```ts
+import { db as authDb } from "@__REPO_NAME__/auth/db";
+import { users } from "@__REPO_NAME__/auth/schema";
+```
+
+Use `users.id` in SpiceDB refs. `users.external_id`, email, and group external IDs are ingestion lookup keys only.
+
+The `users.role` column is not the app permission source of truth. If Better Auth admin features need it, update it deliberately for that UI. Do not rely on it for app access, app roles, or resource permissions.
+
+## Debugging A Denied Check
+
+1. Confirm the user can authenticate and has the expected shared `users.id` in the auth DB.
+2. Confirm application access first: the user or one of their groups needs `core/application:<app>#member` or `#owner`.
+3. Confirm local topology exists:
+
+```bash
+pnpm access:apply-local
+```
+
+4. Validate policy and manifest:
+
+```bash
+pnpm access:validate
+```
+
+5. Check whether the permission expression depends on a missing `system` link or resource relationship. For `systemLinked` resources, call `touchResource()` or assign a relationship through the app access helper.
+6. Check group membership in the shared `auth.group_members` projection before looking at SpiceDB. Reconcile only repairs what the projection says should exist.
+7. If a recently revoked grant still appears allowed inside the same request, use the strong read path for the follow-up check and avoid reusing stale cached results after writes.
+
+## Customer Merge Pipeline
+
+In production, the customer monorepo owns the combined SpiceDB schema:
+
+```bash
+pnpm --dir ../.. run access:merge
+pnpm --dir ../.. run access:validate
+pnpm --dir ../.. run access:apply
+```
+
+The merge step reads every app's `src/access/schema.zed` and `access.manifest.ts`, validates namespace boundaries, includes the library `core.zed`, and emits the customer-level app registry. App packages should not apply production schema fragments independently.
+
+Treat `pnpm --dir ../.. run access:apply` like a database migration step in the
+customer deploy pipeline, not like an ordinary PR check. PR CI should merge and
+validate; trusted deploy jobs should apply the already-validated merged schema to
+each environment's SpiceDB before deploying app code that depends on new
+relations or permissions.
+
+For additive changes, apply the schema first, then deploy the app. For
+destructive changes, use expand/contract:
+
+1. Add the new relation or permission while keeping the old one.
+2. Deploy app code that dual-writes or dual-reads as needed.
+3. Backfill relationships idempotently with `TOUCH` writes or `access:reconcile`.
+4. Switch permission expressions and app checks to the new shape.
+5. Stop old writes, delete old relationships, then remove the old relation in a later schema apply.

package/templates/webapp/agent-skills/database.md

@@ -10,7 +10,7 @@ Create a new schema file alongside the existing ones:
 
 ```typescript
 import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
-import { users } from "./auth/users";
+import { users } from "@__REPO_NAME__/auth/schema";
 
 export const documents = pgTable("documents", {
   id: uuid("id").defaultRandom().primaryKey(),

package/templates/webapp/docker-compose.yml

@@ -1,4 +1,20 @@
 services:
+  spicedb:
+    image: authzed/spicedb:v1.47.1
+    command:
+      - serve
+      - --datastore-engine
+      - memory
+      - --grpc-preshared-key
+      - dev-spicedb-token
+    ports:
+      - "50051:50051"
+    healthcheck:
+      test: ["CMD", "grpc_health_probe", "-addr=localhost:50051"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+
   postgres:
     image: postgres:16
     ports:

package/templates/webapp/env.example.template

@@ -14,10 +14,19 @@ DATABASE_USE_SSL=false
 # Authentication (Better Auth)
 BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32
 BETTER_AUTH_URL=http://localhost:3000
+# Optional override for the shared customer auth database. Defaults to the
+# customer monorepo database generated in ../../auth.
+# AUTH_DATABASE_NAME=
+# AUTH_DATABASE_URL=
 
 # Security
 ENCRYPTION_SECRET_KEY=generate-with-node-e-console-log-require-crypto-randomBytes-16-toString-hex
 
+# Access Control (SpiceDB)
+SPICEDB_ENDPOINT=localhost:50051
+SPICEDB_PRESHARED_KEY=dev-spicedb-token
+SPICEDB_INSECURE=true
+
 # Inngest (Background Jobs)
 INNGEST_BASE_URL=http://localhost:8288
 # INNGEST_SIGNING_KEY=

package/templates/webapp/next.config.ts

@@ -9,6 +9,7 @@ const nextConfig: NextConfig = {
   // Enable standalone output for Docker:
   output: "standalone",
   outputFileTracingRoot: monorepoRoot,
+  transpilePackages: ["@__REPO_NAME__/auth"],
   turbopack: {
     root: monorepoRoot,
   },