@percepta/create 3.6.2 → 4.0.0

package/templates/monorepo/scripts/setup-local-databases.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LOCAL_POSTGRES_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+const LOCAL_POSTGRES_PORT = "5434";
+const POSTGRES_SERVICE = "postgres";
+const POSTGRES_USER = "postgres";
+const ROOT_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+const PACKAGES_DIR = path.join(ROOT_DIR, "packages");
+
+const databases = new Set(["auth"]);
+
+for (const packageDir of listPackageDirs()) {
+  const database = readPackageDatabaseName(packageDir);
+  if (database != null) {
+    databases.add(database);
+  }
+}
+
+for (const database of [...databases].sort()) {
+  ensureDatabase(database);
+}
+
+function listPackageDirs() {
+  if (!existsSync(PACKAGES_DIR)) return [];
+
+  return readdirSync(PACKAGES_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => packageDirFor(entry.name));
+}
+
+function packageDirFor(packageName) {
+  if (
+    packageName === "." ||
+    packageName === ".." ||
+    packageName.includes("/") ||
+    packageName.includes("\\")
+  ) {
+    throw new Error(`Unexpected package directory name: ${packageName}`);
+  }
+
+  return path.join(PACKAGES_DIR, packageName);
+}
+
+function readPackageDatabaseName(packageDir) {
+  const env = readPackageEnvFile(packageDir);
+  const databaseUrl = env.DATABASE_URL;
+  if (databaseUrl == null || databaseUrl.length === 0) return null;
+
+  let url;
+  try {
+    url = new URL(databaseUrl);
+  } catch {
+    throw new Error(
+      `Invalid DATABASE_URL in ${path.relative(ROOT_DIR, packageDir)}/.env.local`,
+    );
+  }
+
+  if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") {
+    throw new Error(
+      `DATABASE_URL in ${path.relative(ROOT_DIR, packageDir)}/.env.local must use postgres or postgresql.`,
+    );
+  }
+
+  const port = url.port || "5432";
+  if (!LOCAL_POSTGRES_HOSTS.has(url.hostname) || port !== LOCAL_POSTGRES_PORT) {
+    console.log(
+      `Skipping non-local app database for ${path.relative(ROOT_DIR, packageDir)}.`,
+    );
+    return null;
+  }
+
+  const database = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
+  if (database.length === 0) {
+    throw new Error(
+      `DATABASE_URL in ${path.relative(ROOT_DIR, packageDir)}/.env.local must include a database name.`,
+    );
+  }
+
+  return database;
+}
+
+function readPackageEnvFile(packageDir) {
+  const safePackageDir = assertPackageDir(packageDir);
+  const envPath = path.join(safePackageDir, ".env.local");
+  if (!existsSync(envPath)) return {};
+
+  const env = {};
+  const content = readFileSync(envPath, "utf8");
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const normalized = line.startsWith("export ") ? line.slice(7).trim() : line;
+    const separatorIndex = normalized.indexOf("=");
+    if (separatorIndex === -1) continue;
+
+    const key = normalized.slice(0, separatorIndex).trim();
+    const rawValue = normalized.slice(separatorIndex + 1).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+
+    env[key] = unquote(rawValue);
+  }
+
+  return env;
+}
+
+function assertPackageDir(packageDir) {
+  const resolvedPackageDir = path.resolve(packageDir);
+  const relative = path.relative(PACKAGES_DIR, resolvedPackageDir);
+
+  if (
+    relative.length === 0 ||
+    relative.startsWith("..") ||
+    path.isAbsolute(relative) ||
+    relative.includes(path.sep)
+  ) {
+    throw new Error(`Unexpected package directory: ${packageDir}`);
+  }
+
+  return resolvedPackageDir;
+}
+
+function unquote(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}
+
+function ensureDatabase(database) {
+  const exists = execDockerCompose([
+    "exec",
+    "-T",
+    POSTGRES_SERVICE,
+    "psql",
+    "-U",
+    POSTGRES_USER,
+    "-d",
+    "postgres",
+    "-tAc",
+    `SELECT 1 FROM pg_database WHERE datname = ${quotePgLiteral(database)}`,
+  ]).trim();
+
+  if (exists === "1") {
+    console.log(`Database ${database} already exists.`);
+    return;
+  }
+
+  execDockerCompose([
+    "exec",
+    "-T",
+    POSTGRES_SERVICE,
+    "createdb",
+    "-U",
+    POSTGRES_USER,
+    database,
+  ]);
+  console.log(`Database ${database} created.`);
+}
+
+function execDockerCompose(args) {
+  return execFileSync("docker", ["compose", ...args], {
+    cwd: ROOT_DIR,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "inherit"],
+  });
+}
+
+function quotePgLiteral(value) {
+  return `'${value.replaceAll("'", "''")}'`;
+}

package/templates/monorepo/turbo.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://turborepo.com/schema.json",
+  "ui": "tui",
+  "globalDependencies": ["pnpm-workspace.yaml"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", "**/.next/**", "!**/.next/cache/**"]
+    },
+    "typecheck": {
+      "dependsOn": ["^build"]
+    },
+    "test": {
+      "dependsOn": ["^build"]
+    },
+    "clean": {
+      "cache": false
+    }
+  }
+}

package/templates/webapp/.node-version

@@ -1,2 +1 @@
 24.4.1
-

package/templates/webapp/AGENTS.md

@@ -1,35 +1,34 @@
 # 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, SpiceDB access control, and Inngest.
+Next.js 16 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
 
 - `pnpm dev` — start dev server with Turbopack
 - `pnpm build` — production build
-- `pnpm lint` — run ESLint
+- `pnpm typecheck` — type-check with `tsc`
 - `pnpm test` — run Vitest tests
-- `pnpm docker:up` / `pnpm docker:down` — start PostgreSQL and SpiceDB, waiting for health, or stop them
+- Linting and formatting run from the monorepo root: `pnpm lint` (oxlint) and `pnpm format` (oxfmt)
 - `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 auth:db:migrate` — run shared customer auth database migrations
 - `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` — setup/migrate the database, then open Drizzle Studio
+- `pnpm db:studio` — run migrations, then open Drizzle Studio
 - `pnpm db:seed` — seed shared-auth dev users and local grants for customer admin, app admin, app user, and app non-user personas (all use password)
 
 **Package manager**: Always use `pnpm`, never `npm` or `yarn`.
 
-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.
+Local PostgreSQL and SpiceDB are owned by the monorepo root. Use `pnpm run setup` from this package or the root to start services, create local databases, run migrations, and seed users/grants. 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
 
 - Double quotes for strings
-- `no-console` is enforced — use `@percepta/logger` instead (see below)
-- Logger messages must be plain string literals, not variables or templates
-- `no-process-env` is enforced — use `getEnvConfig()` from `src/config/`
+- Prefer `@percepta/logger` over `console` (oxlint flags `console` as a warning, see below)
+- Logger messages should be plain string literals, not variables or templates
+- Read env via `getEnvConfig()` from `src/config/` rather than `process.env` directly (a project convention)
 - Use `@percepta/design` components before writing custom UI
 - For loading/error states, use local UI or add `@percepta/components` if you want `AsyncContent`
 - Tailwind CSS for all styling; icons from `lucide-react`
@@ -58,13 +57,9 @@ src/                        # Application source
 │   └── observability/      # OpenTelemetry setup
 └── utils/                  # Helpers (cn, pathEncryption, etc.)
 
-deploy/                     # Infrastructure-as-code for Ryvn deployments
+deploy/                     # Optional release metadata
 └── ryvn/
-    ├── __APP_NAME__.service.yaml                                       # Ryvn web service
-    ├── __APP_NAME__-terraform.service.yaml                             # Ryvn schema service
-    └── environments/<env>/installations/
-        ├── __APP_NAME__.env.<env>.serviceinstallation.yaml
-        └── __APP_NAME__-terraform.env.<env>.serviceinstallation.yaml
+    └── __APP_NAME__.service.yaml                                       # Ryvn web service
 ```
 
 ## @percepta Packages
@@ -109,22 +104,26 @@ Also includes composite components: `ButtonWithDropdown`, `Combobox`, `IconButto
 
 ### @percepta/build — Shared Build Configs
 
-Provides centralized formatter, TypeScript, bundler, and Vitest configuration.
-
-```js
-// eslint.config.mjs
-import eslint from "@eslint/js";
-import tseslint from "typescript-eslint";
-
-export default tseslint.config(eslint.configs.recommended, ...tseslint.configs.recommended);
-```
+Provides centralized linter (oxlint), formatter (oxfmt), TypeScript, bundler (tsdown), and Vitest configuration.
 
 ```json
 // tsconfig.json
 { "extends": "@percepta/build/tsconfig/web" }
 ```
 
-Vitest config is also available via `@percepta/build/vitest`.
+```ts
+// oxfmt.config.ts
+import { defineOxfmtReactConfig } from "@percepta/build/oxfmt";
+export default defineOxfmtReactConfig({ stylesheet: "./src/styles/globals.css" });
+```
+
+```ts
+// vitest.config.ts
+import { createVitestConfig } from "@percepta/build/vitest";
+export default createVitestConfig({ additionalSetupFiles: ["./vitest.setup.ts"] });
+```
+
+Linting is configured once at the monorepo root via `@percepta/build/oxlint`.
 
 ### @percepta/components — Optional React Utilities
 
@@ -200,8 +199,7 @@ Detailed how-to guides for each major stack component. Read the relevant guide w
 | 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 |
+| Deployment (Ryvn) | [agent-skills/ryvn.md](agent-skills/ryvn.md) | Ryvn service release notes; environment installs live in infra |
 | Build App (Oneshot) | [agent-skills/oneshot.md](agent-skills/oneshot.md) | Building a complete app from requirements end-to-end |
 
 ## Key Patterns
@@ -221,14 +219,14 @@ Client-side usage via `src/lib/trpc.ts`.
 
 ### Authentication
 
-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.
+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. `DATABASE_URL` is this app's database only; deployed auth should use `AUTH_DATABASE_URL` from the monorepo auth Secret.
 
 - **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`
 - **Sign in**: `authClient.signIn.email({ email, password })` — client-side
 - **Sign out**: `authClient.signOut()` — client-side
 - **API route**: `src/app/api/auth/[...all]/route.ts` — Better Auth handler
-- **Env vars**: `BETTER_AUTH_SECRET` (required), `BETTER_AUTH_URL` (defaults to `http://localhost:3000`)
+- **Env vars**: `BETTER_AUTH_SECRET` (required), `BETTER_AUTH_URL` (defaults to `http://localhost:3000`), `AUTH_DATABASE_URL` for deployed shared auth DB wiring
 
 ### Background Jobs
 
@@ -248,11 +246,11 @@ OpenTelemetry initialized in `src/instrumentation.ts`. Server traces and metrics
 
 ## Deployment
 
-To deploy this app to percepta-test, follow [agent-skills/deploy.md](agent-skills/deploy.md). The direct deploy helper treats percepta-test as an existing platform environment: it preflights the shared Postgres, Inngest, OTEL collector, and LGTM installations, then creates/updates this app's Ryvn services and installations.
-
-The release CI/CD workflows are already included under `.github/workflows/`.
-
-For Ryvn CLI operations, use the `/use-ryvn` skill.
+Blueberry does not generate environment-specific deployments. Customer and
+stack-specific infrastructure, app database registration, runtime services,
+ingress, secrets, and service installations belong in the infra repo. The
+release CI/CD workflow is included under `.github/workflows/` for stacks that
+use Ryvn releases.
 
 ## Template Sync
 

package/templates/webapp/README.md

@@ -1,12 +1,12 @@
 # __APP_TITLE__
 
-A production-ready Next.js application with authentication, database, logging, background jobs, and infrastructure as code.
+A production-ready Next.js application with authentication, database, logging, and background jobs.
 
 Design theme: `__MOSAIC_DESIGN_THEME__`
 
 ## Features
 
-- **Next.js 15** with App Router
+- **Next.js 16** 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
@@ -14,7 +14,7 @@ Design theme: `__MOSAIC_DESIGN_THEME__`
 - **Background Jobs** with Inngest
 - **LLM Calls** with a provider-backed `LLMService`
 - **Observability** with OpenTelemetry, LGTM-compatible traces/metrics/logs, and Langfuse integration
-- **Infrastructure** with Terraform modules for AWS (RDS, S3, IAM)
+- **Deployment-ready** Dockerfile and environment-neutral service metadata
 - **Type Safety** with TypeScript and Zod schemas
 
 ## Quick Start
@@ -29,9 +29,9 @@ Copy `.env.example` to `.env.local` and configure any app-specific environment v
 pnpm run setup
 ```
 
-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.
+This delegates to the monorepo root. The root setup starts local PostgreSQL and
+SpiceDB, creates the shared auth database and this app's database, applies the
+local access schema, runs migrations, and seeds dev users.
 
 ### 3. Start Inngest When Using Background Jobs
 
@@ -49,7 +49,7 @@ pnpm dev
 
 Open [http://localhost:3000](http://localhost:3000) to see your app.
 
-OpenTelemetry, Faro, and Langfuse are optional in local development. Leave their env vars empty unless you are actively debugging telemetry; production deploys wire server traces, metrics, logs, and shared Langfuse demo credentials into the target Ryvn environment. General HTTP and database spans go to the OTEL/LGTM pipeline; Langfuse receives only AI SDK spans by default.
+OpenTelemetry, Faro, and Langfuse are optional in local development. Leave their env vars empty unless you are actively debugging telemetry. Remote deployments should provide telemetry and Langfuse values through the target platform. General HTTP and database spans go to the OTEL/LGTM pipeline; Langfuse receives only AI SDK spans by default.
 
 If you need local LLM calls, set provider keys once in your shell profile or in `~/.config/percepta/create.env`:
 
@@ -87,18 +87,14 @@ src/
 | `pnpm dev` | Start development server with Turbopack |
 | `pnpm build` | Build for production |
 | `pnpm start` | Start production server |
-| `pnpm lint` | Run ESLint |
-| `pnpm docker:up` | Start PostgreSQL and SpiceDB containers and wait until they are healthy |
-| `pnpm docker:down` | Stop PostgreSQL and SpiceDB containers |
+| `pnpm typecheck` | Type-check with `tsc` |
 | `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 auth:db:migrate` | Run migrations for 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` | Setup/migrate the database, then open Drizzle Studio |
+| `pnpm db:studio` | Run migrations, then open Drizzle Studio |
 | `pnpm db:seed` | Seed default shared-auth dev users and local access grants |
 | `pnpm test:e2e:install` | Install the Chromium browser used by Playwright |
 | `pnpm test:e2e` | Run Playwright e2e tests after local setup |
@@ -153,15 +149,19 @@ logger.error(
 
 ## Authentication
 
-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.
+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. Deployed apps should receive that shared database through `AUTH_DATABASE_URL` from the monorepo auth Secret; `DATABASE_URL` is reserved for this app's own database.
 
-Required environment variables:
+Required auth environment variables:
 
 ```bash
 BETTER_AUTH_SECRET=generate-with-openssl-rand-base64-32
 BETTER_AUTH_URL=http://localhost:3000
 ```
 
+Remote deployments should also set `AUTH_DATABASE_URL` from the shared auth
+database Secret. Local development can omit it and use the root-created local
+`auth` database.
+
 To create dev users:
 ```bash
 pnpm db:seed
@@ -184,17 +184,17 @@ App permissions are authored in `src/access/schema.zed`; `src/access/access.mani
 | `NODE_ENV` | Environment mode | `development` |
 | `APP_BASE_URL` | Base URL for the app | - |
 
-### Database
+### App Database
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `DATABASE_HOST` | PostgreSQL host | `localhost` |
-| `DATABASE_PORT` | PostgreSQL port | `5434` |
-| `DATABASE_USERNAME` | Database user | `postgres` |
-| `DATABASE_PASSWORD` | Database password | `postgres` |
-| `DATABASE_NAME` | Database name | `__DB_NAME__` |
-| `DATABASE_SCHEMA` | Optional Postgres schema/search path | - |
-| `DATABASE_USE_SSL` | Enable SSL | `false` |
+| `DATABASE_URL` | App PostgreSQL connection URL | `postgresql://postgres:postgres@localhost:5434/__DB_NAME__` |
+
+### Shared Auth Database
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AUTH_DATABASE_URL` | Shared auth database URL from the monorepo auth Secret | - |
 
 ### Security
 
@@ -231,13 +231,13 @@ node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
 | `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
 | `LANGFUSE_SECRET_KEY` | Langfuse secret key |
 
-`deploy:percepta-test` sets the shared Langfuse URL and inherits the demo project keys from the `demos-commons` Ryvn variable group.
+Set these values through the target deployment platform when Langfuse is enabled.
 
 ### LLM Providers
 
 | Variable | Description |
 |----------|-------------|
-| `ANTHROPIC_API_KEY` | Anthropic API key. Inherited from `demos-commons` for `percepta-test` deploys |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
 | `OPENAI_API_KEY` | OpenAI API key for local or non-demo deployments |
 | `LLM_PROVIDER` | Optional provider override: `anthropic` or `openai` |
 | `LLM_MODEL` | Optional model override |
@@ -254,7 +254,7 @@ const result = await LLMService.create().generateText({
 });
 ```
 
-For local development, `pnpm dev` also loads `~/.config/percepta/create.env` when that file exists. Production deploys do not use that local file; they inherit provider keys from the target Ryvn environment.
+For local development, `pnpm dev` also loads `~/.config/percepta/create.env` when that file exists. Remote deployments do not use that local file; they should receive provider keys from the target platform.
 
 ### OpenTelemetry / LGTM
 
@@ -270,7 +270,7 @@ For local development, `pnpm dev` also loads `~/.config/percepta/create.env` whe
 | `OTEL_METRICS_EXPORTER` | Set to `otlp` to export server metrics |
 | `OTEL_METRIC_EXPORT_INTERVAL` | Metrics export interval in milliseconds |
 
-`deploy:percepta-test` configures these for the existing percepta-test OTEL collector and LGTM stack. Application logs are written to stdout and collected by the platform collector.
+Configure these values through the target deployment platform. Application logs are written to stdout so the platform collector can collect them.
 
 ## Local AWS Development
 
@@ -284,17 +284,13 @@ This application uses the default AWS SDK credential provider chain:
 
 2. **AWS Credentials File**: Run `aws configure` or `aws sso login`
 
-## Infrastructure (Terraform)
-
-The `terraform/` directory contains modules for AWS infrastructure:
-
-- **RDS**: PostgreSQL database
-- **S3**: File storage with logging
-- **Networking**: VPC endpoints
-- **Secrets**: AWS Secrets Manager
-- **IAM**: Roles and policies
+## Infrastructure
 
-See `terraform/README.md` for deployment instructions.
+The app template does not own cloud infrastructure. The infra repo owns base
+environment infrastructure, customer monorepo infrastructure, app database
+registration, observability, and shared services. App deployments expect the
+customer monorepo infrastructure blueprint to create an app-scoped Kubernetes
+Secret named `__APP_NAME__-postgresql`.
 
 ## Learn More
 

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

@@ -38,11 +38,9 @@ export * from "./documents";
 pnpm db:generate
 ```
 
-This creates a new SQL migration file and normalizes generated foreign key
-references so they stay schema-relative when `DATABASE_SCHEMA` is set in
-`percepta-test`. **Review the generated SQL** — Drizzle generates it
-automatically but you should verify it's correct, especially for new foreign
-keys and destructive changes.
+This creates a new SQL migration file and normalizes generated SQL. **Review
+the generated SQL** — Drizzle generates it automatically but you should verify
+it's correct, especially for new foreign keys and destructive changes.
 
 ### 4. Apply the migration
 
@@ -95,21 +93,25 @@ If `createTransaction` is called while already inside a transaction, it reuses t
 
 ## Running PostgreSQL Locally
 
-### Start with Docker Compose
+### Start with root setup
 
 ```bash
-pnpm docker:up
+pnpm run setup
 ```
 
-This starts PostgreSQL 16 on port **5434** (not the default 5432, to avoid conflicts).
+This delegates to the monorepo root. Root setup starts PostgreSQL 16 on port
+**5434** and SpiceDB on **50051**, creates the shared auth database plus each
+app database discovered from `packages/*/.env.local`, then runs migrations and
+seeds.
 
-### Create the database and run migrations
+### Run migrations
 
 ```bash
-pnpm db:setup-and-migrate
+pnpm db:migrate
 ```
 
-This creates the database if it doesn't exist and applies all pending migrations.
+This applies all pending migrations. Database creation is owned by the local
+infrastructure setup, not by the app migration command.
 
 ### Inspect the database
 
@@ -119,27 +121,25 @@ pnpm db:studio
 
 Opens Drizzle Studio in the browser — a visual database explorer.
 
-### Stop PostgreSQL
+### Stop local services
 
 ```bash
-pnpm docker:down
+pnpm --dir ../.. run docker:down
 ```
 
 ## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `DATABASE_HOST` | `localhost` | PostgreSQL host |
-| `DATABASE_PORT` | `5434` | PostgreSQL port |
-| `DATABASE_USERNAME` | `postgres` | Database user |
-| `DATABASE_PASSWORD` | `postgres` | Database password |
-| `DATABASE_NAME` | `__DB_NAME__` | Database name |
-| `DATABASE_SCHEMA` | - | Optional Postgres schema/search path |
-| `DATABASE_USE_SSL` | `false` | Enable SSL connections |
+| `DATABASE_URL` | `postgresql://postgres:postgres@localhost:5434/__DB_NAME__` | App PostgreSQL connection URL |
+
+Shared auth data belongs to the customer monorepo auth package. Deployed apps
+should receive `AUTH_DATABASE_URL` from the monorepo auth Secret; do not reuse
+`DATABASE_URL` for auth.
 
 ## Key Concepts
 
 - **Schemas are TypeScript, migrations are SQL.** You define tables in TS, then `pnpm db:generate` creates the SQL diff. Never hand-write migration SQL.
 - **DatabaseService is a singleton.** Call `DatabaseService.create()` anywhere — it always returns the same instance with the same connection pool.
 - **Transaction propagation is automatic.** Code inside `createTransaction` gets a transaction; code outside gets the raw connection. `getDatabase()` returns whichever is active.
-- **Port 5434.** The local Docker Compose uses port 5434 to avoid conflicting with any system PostgreSQL on 5432.
+- **Root-owned local infra.** The monorepo root Docker Compose uses port 5434 to avoid conflicting with any system PostgreSQL on 5432.

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

@@ -60,11 +60,11 @@ This is a singleton — `create()` returns the same instance every time. It grac
 
 ## Getting Langfuse Keys
 
-### Percepta's Internal Instance
+### Shared Instances
 
-Percepta runs a shared Langfuse instance. For `percepta-test` deploys, the generated Ryvn installation uses the shared demo project by inheriting `LANGFUSE_PUBLIC_KEY` and sensitive `LANGFUSE_SECRET_KEY` from the `demos-commons` variable group.
-
-For non-demo environments, verify the target Ryvn environment has a Langfuse installation or shared Langfuse project, then store the project keys in an environment-scoped variable group or installation secrets.
+If the target stack provides a shared Langfuse instance, store
+`LANGFUSE_PUBLIC_KEY` and sensitive `LANGFUSE_SECRET_KEY` through that
+platform's environment-scoped variable or secret mechanism.
 
 ### Self-Hosted / Langfuse Cloud
 
@@ -74,17 +74,17 @@ For external projects, you can:
 
 ## Running Locally
 
-### Option 1: Use Percepta's Langfuse (recommended)
+### Option 1: Use a Shared Langfuse Instance
 
 Set the keys in `.env.local` if you want local traces to go to the shared instance:
 
 ```bash
-LANGFUSE_BASE_URL=https://langfuse.percepta-test.aitco.dev
+LANGFUSE_BASE_URL=https://langfuse.example.com
 LANGFUSE_PUBLIC_KEY=pk-lf-...
 LANGFUSE_SECRET_KEY=sk-lf-...
 ```
 
-Traces from local dev appear in the shared dashboard under your project.
+Traces from local dev appear in the configured shared dashboard under your project.
 
 ### Option 2: Run Langfuse locally
 

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

@@ -40,7 +40,9 @@ The shared `@percepta/ai` provider helper chooses a provider at call time:
 
 ## Deployment
 
-For `percepta-test`, `deploy:percepta-test` attaches the `demos-commons` Ryvn variable group. That group provides the shared `ANTHROPIC_API_KEY` and Langfuse project keys, so generated demo apps do not need per-app LLM secrets.
+Provider keys and Langfuse credentials should come from the target deployment
+platform. Do not commit shared provider keys or generated environment-specific
+secret files to the app repo.
 
 ## Local Development
 
@@ -54,6 +56,6 @@ ANTHROPIC_API_KEY=sk-ant-...
 
 ## Observability
 
-`LLMService` enables AI SDK telemetry by default and attaches provider/model metadata to each call. When `LANGFUSE_*` values are configured, the template's OpenTelemetry bootstrap sends LLM spans to Langfuse. In `percepta-test`, those values are inherited from the environment.
+`LLMService` enables AI SDK telemetry by default and attaches provider/model metadata to each call. When `LANGFUSE_*` values are configured, the template's OpenTelemetry bootstrap sends LLM spans to Langfuse.
 
 Use a stable `telemetryFunctionId` for every meaningful LLM operation, such as `extract-invoice-fields` or `draft-member-message`.