@percepta/create 3.6.2 → 3.6.3

package/templates/monorepo/README.md

@@ -11,7 +11,7 @@ pnpm install
 # Run development mode for all packages
 pnpm dev
 
-# Set up local services, access-control topology, databases, and seed users
+# Set up root local services, databases, access-control topology, and seed users
 pnpm run setup
 
 # Add another Mosaic package using this workspace's pinned generator
@@ -35,10 +35,23 @@ pnpm lint
 ```
 access/              # Customer-level SpiceDB fixtures and generated merge artifacts
 auth/                # Shared Better Auth users/groups package for this customer
+docker-compose.yml   # Root-owned local PostgreSQL and SpiceDB services
+scripts/             # Root-owned local infrastructure helpers
 packages/
   └── your-package/  # Application and library packages
 ```
 
+## Local Infrastructure
+
+Local development infrastructure is owned by the monorepo root. `pnpm run setup`
+starts the root Docker Compose services, creates the shared `auth` database,
+discovers app `DATABASE_URL`s from `packages/*/.env.local`, creates those app
+databases, runs auth and app migrations, and seeds local users/grants.
+
+When you add another webapp with `pnpm mosaic add webapp my-app`, the generated
+app gets its own local `DATABASE_URL`. Re-running `pnpm run setup` creates that
+database before running migrations.
+
 ## Access Control
 
 Application builders define app-local Zed schemas in each package's
@@ -56,7 +69,7 @@ PR CI merges the customer schema and runs static schema/manifest validation.
 `access:apply` is reserved for trusted deploy jobs and should run once per
 target environment with that environment's SpiceDB credentials.
 
-For local development, `pnpm run setup` seeds the generated app's default dev
+For local development, `pnpm run setup` seeds each generated app's default dev
 users and access grants. For additional local grants, copy the example fixture
 files in `access/`, fill in customer-global user/group IDs from `auth/`, then
 run:
@@ -83,4 +96,29 @@ pnpm mosaic add webapp my-app
 pnpm mosaic add library my-lib
 ```
 
-The compatibility metadata lives in `.mosaic-workspace.json`.
+The customer slug and compatibility metadata live in `.mosaic-workspace.json`.
+
+## Registering the customer OS blueprint
+
+To register this customer monorepo's OS blueprint in `Percepta-Core/infra`,
+run:
+
+```bash
+pnpm mosaic infra register-os-blueprint
+```
+
+The command reads the customer slug from `.mosaic-workspace.json`, opens or
+updates an infra PR that writes
+`ryvn/definitions/<customer>/blueprints/<customer>-os.blueprint.yaml`, and does
+not create environment installations. It authenticates with `GITHUB_TOKEN`,
+`GH_TOKEN`, or the GitHub CLI's `gh auth token`.
+
+After adding a webapp, register its app database in the customer OS blueprint:
+
+```bash
+pnpm mosaic infra register-app my-app
+```
+
+This opens or updates an infra PR that adds `my-app: {}` to the customer OS
+blueprint's `app_databases` default. Merge the OS blueprint PR before
+registering apps.

package/templates/monorepo/auth/README.md

@@ -22,6 +22,9 @@ lands.
 
 ## Database
 
-By default this package uses the customer monorepo database name generated at
-scaffold time. Override with `AUTH_DATABASE_NAME` or `AUTH_DATABASE_URL` when
-the shared auth database lives somewhere else.
+By default this package uses a shared `auth` database with local PostgreSQL
+defaults. Remote deployments should inject `AUTH_DATABASE_URL` from the
+monorepo auth database Secret.
+
+Do not use app `DATABASE_URL` for this package. That belongs to each webapp's
+own database.

package/templates/monorepo/auth/package.json

@@ -13,12 +13,10 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "db:setup": "tsx ./scripts/setup-database.ts",
-    "db:setup-and-migrate": "pnpm db:setup && pnpm db:migrate"
+    "db:migrate": "drizzle-kit migrate"
   },
   "dependencies": {
-    "@percepta/auth": "0.1.3",
+    "@percepta/auth": "0.1.4",
     "drizzle-orm": "^0.45.2"
   },
   "devDependencies": {

package/templates/monorepo/auth/src/config/database.ts

@@ -7,7 +7,7 @@ import {
 export type { AuthDatabaseConfig } from "@percepta/auth";
 
 export function getAuthDatabaseConfig(): AuthDatabaseConfig {
-  return readAuthDatabaseConfig({ defaultDatabaseName: "__DB_NAME__" });
+  return readAuthDatabaseConfig({ defaultDatabaseName: "auth" });
 }
 
 export function getAuthDatabaseConnectionString(): string {

package/templates/{webapp → monorepo}/docker-compose.yml

@@ -22,11 +22,11 @@ services:
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: __DB_NAME__
+      POSTGRES_DB: postgres
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U postgres -d __DB_NAME__"]
+      test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
       interval: 5s
       timeout: 5s
       retries: 5

package/templates/monorepo/package.json.template

@@ -6,7 +6,10 @@
   "scripts": {
     "preinstall": "npx only-allow pnpm",
     "mosaic": "pnpm dlx __CREATE_PACKAGE__@__CREATE_VERSION__",
-    "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",
+    "setup": "pnpm run docker:up && pnpm run db:setup-local && pnpm run auth:db:migrate && pnpm run access:apply-local && pnpm -r --filter './packages/*' --if-present run db:migrate && pnpm -r --filter './packages/*' --if-present run db:seed",
+    "docker:up": "docker compose up -d --wait",
+    "docker:down": "docker compose down",
+    "db:setup-local": "node scripts/setup-local-databases.mjs",
     "dev": "pnpm -r --parallel --if-present run dev",
     "build": "pnpm -r --if-present run build",
     "clean": "pnpm -r --if-present run clean",
@@ -22,7 +25,7 @@
     "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"
+    "auth:db:migrate": "pnpm --dir auth run db:migrate"
   },
   "engines": {
     "node": ">=20",

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/webapp/AGENTS.md

@@ -8,20 +8,18 @@ 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 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 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
@@ -58,13 +56,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
@@ -200,8 +194,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 +214,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 +241,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,6 +1,6 @@
 # __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__`
 
@@ -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`:
 
@@ -88,17 +88,13 @@ src/
 | `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 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