@withmata/blueprints 0.2.0

package/.cursor/commands/scaffold-auth.md

@@ -0,0 +1,310 @@
+# Scaffold Auth Blueprint
+
+Scaffold the `auth-better-auth` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack.
+
+## Step 1: Read the Blueprint
+
+Read the full BLUEPRINT.md and all code files from the auth blueprint:
+
+```
+blueprints/features/auth-better-auth/BLUEPRINT.md
+blueprints/features/auth-better-auth/files/**/*
+```
+
+If these files are not in the current project, look for them at `~/Documents/WithMata/my-blueprints/blueprints/features/auth-better-auth/`. If still not found, ask the user for the path to their blueprints repo.
+
+## Step 1.5: Read Project Context
+
+Check if `.project-context.md` exists in the target project root:
+
+- **If it exists**: read it to understand:
+  - Product name and scope (from Discovery)
+  - npm scope, workspace layout, server framework (from Foundation)
+  - What other blueprints are already installed (from Installed Blueprints)
+  - Use this information to pre-fill configuration questions in Step 3 and adapt file paths in Step 4
+
+- **If it does not exist**: proceed normally — explore the project manually (Step 2) and ask all configuration questions (Step 3)
+
+When project context provides clear answers, skip the corresponding questions in Step 3. For example:
+- Context says `server_framework: hono` -> do not ask about server framework
+- Context says `npm_scope: "@acme"` -> use `@acme` for package references
+- Context has `auth-better-auth` in Installed Blueprints -> warn about existing install
+
+## Step 1.7: Check Blueprint Dependencies
+
+Read the Blueprint Dependencies section from `auth-better-auth/BLUEPRINT.md`.
+
+For `features/db-drizzle-postgres` (required):
+- Check `.project-context.md` for `db-drizzle-postgres` under `## Installed Blueprints`
+- If installed: proceed normally
+- If NOT installed, check filesystem:
+  - Monorepo: does `packages/db/` exist?
+  - Single-repo: does `src/db/` exist?
+- If db directory exists (but not in project context): note it, proceed normally — the scaffold command already handles merging
+- If neither installed nor directory exists:
+  - Ask: "Auth requires a database package. The db-drizzle-postgres blueprint establishes the schema-group pattern that auth builds on. Install it first? (Y/n)"
+  - If yes: run `/scaffold-db` first, then continue with auth
+  - If no: warn about missing patterns, proceed with creating a minimal db structure for auth only
+
+For `foundation/monorepo-turbo` (recommended):
+- If not present: mention once: "Tip: The monorepo-turbo foundation blueprint provides workspace structure that auth integrates with. Consider running `/scaffold-foundation` first."
+- Continue without blocking.
+
+## Step 2: Understand the Target Project
+
+Before making any changes, explore the target project to understand:
+
+### 2a. Detect Project Type
+
+Check `.project-context.md` for `project_type`. If not present, detect:
+
+- **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `"workspaces"` in root `package.json`
+- **Single-repo indicators**: Single `package.json` at root, `src/` directory, no workspace config
+
+Confirm with user: "This looks like a [monorepo|single-repo] project. Is that right?"
+
+Record the project type in `.project-context.md` if not already there.
+
+### 2b. Explore Structure
+
+**If monorepo:**
+1. What workspaces exist? Where do apps, APIs, and packages live?
+2. Is there a Hono server, Express server, or is it Next.js-only? Where are API routes?
+3. Is Drizzle already set up? Is there a shared DB package?
+4. Is this Next.js? What version? Is there an existing middleware.ts?
+
+**If single-repo:**
+1. What framework is this? (Next.js, Node/Express, Hono, Bun?)
+2. Does `src/db/` or `lib/db/` exist?
+3. What import convention is used? (`@/` paths, `#` subpath imports, relative?)
+4. Is there an existing `middleware.ts`?
+
+**Both:**
+5. Existing auth to replace or integrate with?
+6. UI library? Styling approach?
+7. Package manager?
+8. Validation — Zod, t3-env?
+9. Data fetching — SWR, TanStack Query?
+
+Skip exploration for anything already documented in `.project-context.md`.
+
+## Step 3: Ask Clarifying Questions
+
+Before scaffolding, ask the user about their preferences. Use the blueprint's "Hard Requirements vs Recommended Defaults" table. Specifically ask:
+
+1. **Organization plugin** — "Do you need multi-tenant organizations (teams/workspaces with member management and invitations), or is this a single-tenant app?"
+
+2. **Database setup** — "Should auth use a separate database, or share the existing app database?" (Recommend separate if no strong preference.)
+
+3. **Social providers** — "Which social login providers do you want? Google is included by default. Any others (GitHub, Discord, etc.)?"
+
+4. **Email provider** — "The blueprint uses Resend for transactional emails (verification, password reset, invitations). Do you want to use Resend, or a different provider?"
+
+5. **Defaults check** — "The blueprint recommends these tools (which may already match your project). Want to go with the defaults, or change any?"
+   - Zod for validation
+   - t3-env for environment variable validation
+   - SWR (`useSWRMutation`) for auth mutation hooks
+   - react-hook-form for auth forms
+
+Skip questions where the answer is obvious from the project structure or from `.project-context.md`.
+
+## Step 4: Adapt and Scaffold
+
+Based on the project structure, project context, and user answers, adapt the blueprint files:
+
+### 4a. Database Layer
+
+**If monorepo:**
+- Copy/adapt `files/db/drizzle.config.ts` → `packages/db/drizzle/auth/drizzle.config.ts`
+- Copy `files/db/auth-schema.ts` as a reference (the actual schema will be auto-generated)
+- Add the `"./auth"` export to `packages/db/package.json`
+- Add `auth:generate` and `auth:migrate` scripts to `packages/db/package.json`
+
+**If single-repo:**
+- Copy/adapt `files/db/drizzle.config.ts` → `drizzle/auth/drizzle.config.ts` (at project root)
+- Adjust schema paths to `"./src/db/auth/schema.ts"` (relative to root)
+- Create `src/db/auth/` directory for auth schema
+- No separate package.json export needed — use direct imports
+
+### 4b. Server Layer
+
+**If monorepo:**
+- Copy/adapt `files/server/auth.ts` → `apis/server/src/auth/index.ts`
+  - Replace `{{APP_NAME}}`, `{{EMAIL_FROM}}`, `{{SCOPE}}`
+- Copy/adapt `files/server/auth-db.ts` → `apis/server/src/db/auth.ts`
+- Copy/adapt `files/server/middleware.ts` → `apis/server/src/middleware/auth.ts`
+- Merge auth env vars into `apis/server/src/env.ts`
+
+**If single-repo:**
+- Copy/adapt `files/server/auth.ts` → `src/lib/auth/index.ts`
+  - Replace `{{APP_NAME}}`, `{{EMAIL_FROM}}`
+  - Adjust DB import to use direct path: `import { db } from "@/db/auth/client"` or `#db/auth/client`
+- Copy/adapt `files/server/auth-db.ts` → `src/lib/db/auth.ts`
+- Default to Next.js API routes (no separate Hono server)
+- Merge auth env vars into existing `env.ts` (or create one)
+
+**Both:**
+- If the project uses a different server framework than Hono, adapt the middleware while keeping the core `auth.api.getSession({ headers })` pattern
+
+### 4c. Mount Auth Handler
+
+**If monorepo with Hono server:**
+- Add CORS config + `app.on(["POST", "GET"], "/api/auth/*", ...)` handler in `apis/server/`
+
+**If single-repo or Next.js API routes:**
+- Create `app/api/auth/[...all]/route.ts` with `toNextJsHandler(auth)`
+- No CORS config needed (same origin)
+
+**Other frameworks:** Follow the platform integration section in BLUEPRINT.md
+
+### 4d. Client Layer
+
+**If monorepo:**
+- Copy client files to `apps/web/auth/`
+- Add `"#auth/*": "./auth/*"` import alias to `apps/web/package.json`
+
+**If single-repo:**
+- Copy client files to `src/auth/`
+- Add `"#auth/*": "./src/auth/*"` import alias to root `package.json` (or use `@/auth/*` if that's the convention)
+
+**Both:**
+- Adapt `files/client/auth-client.ts` — adjust baseURL for deployment setup
+- If using org plugin: copy all `files/client/context/`, `hooks/`, `schema/`, `types/` files
+- If NOT using org plugin: only copy `files/client/schema/auth.ts`
+
+### 4e. Route Protection
+
+- Copy/adapt `files/middleware/route-protection.ts` into the project's Next.js middleware
+- If middleware.ts already exists, MERGE the auth logic into it — don't overwrite
+- If using Hono standalone mode: add API proxy rewrites to `next.config.ts`
+
+### 4f. Project Scripts
+
+**If monorepo:**
+- Add `auth:generate` script to the server package (runs `@better-auth/cli generate`)
+- Add `auth:generate`, `auth:migrate`, `auth:setup` to root `package.json` (Turbo wrappers)
+- Add `auth:generate` and `auth:migrate` tasks to `turbo.json` (both `cache: false`)
+
+**If single-repo:**
+- Add scripts directly to root `package.json`:
+  - `auth:generate` -> `npx @better-auth/cli@latest generate --config ./src/lib/auth/index.ts --output ./src/db/auth/schema.ts --yes`
+  - `auth:migrate` -> `drizzle-kit generate --config ./drizzle/auth/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/auth/drizzle.config.ts`
+  - `auth:setup` -> `pnpm auth:generate && pnpm auth:migrate`
+- No Turbo tasks needed
+
+## Step 5: Update Project Context
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### auth-better-auth
+blueprint: auth-better-auth
+choices:
+  database: <user's choice>
+  auth_db_isolation: <separate|shared>
+  server_framework: <hono|next.js>
+  organization_plugin: <true|false>
+  social_providers: [<list>]
+  email_provider: <resend|other>
+  env_validation: <t3-env|other>
+  form_validation: <zod|other>
+  data_fetching: <swr|other>
+files_created:
+  - <list of all files created or modified>
+env_vars_added:
+  - <list of env vars>
+scripts_added:
+  - <list of scripts>
+```
+
+If `.project-context.md` does not exist, create it with the standard header and the Installed Blueprints section. Log a note: "No discovery or foundation context found. Consider running `/discover` and `/scaffold-foundation` for a complete project context."
+
+Also append any significant architectural decisions to the `## Architecture Decisions` section.
+
+### Inject Maintenance Rules
+
+Append the condensed maintenance rules to the target project's rules file(s):
+
+1. If `CLAUDE.md` exists in the target project → append rules there
+2. If `AGENTS.md` exists in the target project → append rules there
+3. If both exist → append to both (keep them in sync)
+4. If neither exists → ask the user which AI coding tool(s) they use:
+   - Claude Code → create CLAUDE.md with a `## Maintenance Rules` section
+   - OpenCode or Cursor → create AGENTS.md with a `## Maintenance Rules` section (both tools read AGENTS.md)
+   - Multiple tools → create all applicable files
+
+The maintenance rules content is identical regardless of which file it goes into:
+
+```markdown
+### auth-better-auth maintenance
+- After modifying Better Auth server config, plugins, or providers: run `pnpm auth:generate && pnpm auth:migrate`
+- After updating `better-auth` package: run `pnpm auth:generate`, check for schema changes, migrate if needed
+- After adding/changing env vars: update all `.env` files and verify `pnpm dev` starts clean
+- After changing `BETTER_AUTH_URL` or `FRONTEND_DOMAIN`: verify CORS config and OAuth callback URLs
+- After any auth changes: verify `{BETTER_AUTH_URL}/api/auth/ok` responds
+- Never edit the auto-generated auth schema directly — modify the Better Auth config and regenerate
+```
+
+If the `## Maintenance Rules` heading already exists (from another blueprint), only add the `### auth-better-auth maintenance` subsection — do not duplicate the heading.
+
+## Step 6: Output Summary
+
+After scaffolding, provide the user with a clear summary:
+
+### Packages to Install
+
+List every package that needs to be installed, grouped by workspace:
+
+```
+# Server (apis/server or wherever auth lives)
+pnpm add better-auth drizzle-orm pg resend @t3-oss/env-core zod dotenv
+
+# Client (apps/web)
+pnpm add better-auth swr react-hook-form @hookform/resolvers zod @t3-oss/env-nextjs
+
+# DB package (packages/db) — dev deps
+pnpm add -D drizzle-kit pg
+```
+
+Adjust based on what's already installed in the project.
+
+### Environment Variables
+
+List every env var that needs to be set, with example values:
+
+```env
+# Server
+BETTER_AUTH_URL=http://localhost:4000
+BETTER_AUTH_SECRET=          # Generate: openssl rand -base64 32
+AUTH_DATABASE_URL=           # PostgreSQL connection URL
+FRONTEND_DOMAIN=http://localhost:3000
+GOOGLE_CLIENT_ID=            # From Google Cloud Console
+GOOGLE_CLIENT_SECRET=        # Redirect URI: {BETTER_AUTH_URL}/api/auth/callback/google
+RESEND_API_KEY=              # From resend.com
+
+# Client (.env.local in web app)
+NEXT_PUBLIC_API_URL=http://localhost:4000
+NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
+```
+
+### Manual Steps Remaining
+
+List anything that can't be automated:
+
+1. **Create a PostgreSQL database** for auth (if using separate auth DB)
+2. **Set up Google OAuth** — create OAuth 2.0 credentials in Google Cloud Console, add redirect URI
+3. **Set up Resend** — create an account, verify your domain, get API key
+4. **Run auth setup** — `pnpm auth:setup` (generates schema + runs migrations)
+5. **Build auth UI pages** — follow the Auth Flows section in BLUEPRINT.md to create the pages matching your design system
+6. **Test the auth flow** — sign up, verify email, sign in, create org (if applicable)
+
+### Files Created
+
+List every file that was created or modified, with a one-line description.
+
+## Important Notes
+
+- If the Better Auth skills are installed (`npx skillsadd better-auth/skills`), invoke `/best-practices` for quick-reference on configuration. If not available, refer to the Better Auth docs and References section in BLUEPRINT.md.
+- When adapting code, preserve the `// CONFIGURE:` comments so the user can find customization points later.
+- If the project structure differs significantly from the blueprint's assumptions, explain the differences and suggest how to adapt rather than forcing the blueprint's structure.
+- Never overwrite existing files without asking. If a file exists (like `middleware.ts` or `env.ts`), merge the auth additions into it.

package/.cursor/commands/scaffold-db.md

@@ -0,0 +1,270 @@
+# Scaffold DB Blueprint
+
+Scaffold the `db-drizzle-postgres` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack.
+
+## Step 1: Read the Blueprint
+
+Read the full BLUEPRINT.md and all template files from the db blueprint:
+
+```
+blueprints/features/db-drizzle-postgres/BLUEPRINT.md
+blueprints/features/db-drizzle-postgres/files/**/*
+```
+
+If these files are not in the current project, look for them at `~/Documents/WithMata/my-blueprints/blueprints/features/db-drizzle-postgres/`. If still not found, ask the user for the path to their blueprints repo.
+
+## Step 1.5: Read Project Context
+
+Check if `.project-context.md` exists in the target project root:
+
+- **If it exists**: read it to understand:
+  - Product name and scope (from Discovery)
+  - npm scope, workspace layout, TypeScript config package name (from Foundation)
+  - What other blueprints are already installed (from Installed Blueprints)
+  - Use this information to pre-fill configuration questions in Step 3 and adapt file paths in Step 4
+
+- **If it does not exist**: proceed normally — explore the project manually (Step 2) and ask all configuration questions (Step 3)
+
+When project context provides clear answers, skip the corresponding questions in Step 3. For example:
+- Context says `npm_scope: "@acme"` -> use `@acme` for package references
+- Context has `db-drizzle-postgres` in Installed Blueprints -> warn about existing install
+- Context has `auth-better-auth` installed -> `packages/db/` likely exists already
+
+## Step 2: Understand the Target Project
+
+Before making any changes, explore the target project to understand:
+
+### 2a. Detect Project Type
+
+Check `.project-context.md` for `project_type`. If not present, detect:
+
+- **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `"workspaces"` in root `package.json`
+- **Single-repo indicators**: Single `package.json` at root, `src/` directory, no workspace config
+
+Confirm with user: "This looks like a [monorepo|single-repo] project. Is that right?"
+
+Record the project type in `.project-context.md` if not already there (add `project_type: monorepo` or `project_type: single-repo` under `## Foundation`).
+
+### 2b. Explore Structure
+
+**If monorepo:**
+1. What workspaces exist? Where do apps, APIs, and packages live?
+2. Does `packages/db/` already exist? (The auth blueprint may have created it.) If so, what exports, scripts, and schema groups are already present?
+3. What npm scope is used? Check root or any workspace `package.json`.
+4. What is the shared TypeScript config package name? Check `config/typescript-config/` or similar.
+5. Does `turbo.json` exist? Are there any existing db-related tasks?
+6. Does `pnpm-workspace.yaml` include `packages/*`?
+
+**If single-repo:**
+1. Does `src/db/` already exist? If so, what's in it?
+2. What framework is this? (Next.js, Node/Express, Hono, Bun?)
+3. What import convention is used? (`@/` paths, `#` subpath imports, relative?)
+4. Is there an existing `.env` or `.env.local`?
+
+**Both:**
+- Package manager — pnpm, npm, yarn, or bun?
+
+Skip exploration for anything already documented in `.project-context.md`.
+
+## Step 3: Ask Clarifying Questions
+
+Before scaffolding, ask the user about their preferences:
+
+1. **Schema group name** — "What should your main schema group be called? This groups related database tables together (e.g., 'core' for your main application data, 'app' for a simpler name). Default: `core`"
+
+2. **Include example entity?** — "Include an example entity file demonstrating the full Drizzle pattern (pgTable, pgEnum, indexes, type exports)? Recommended if this is your first time using Drizzle." (Default: yes)
+
+3. **Include seed script?** — "Include a seed script template for populating development data?" (Default: yes)
+
+4. **Connection helper** — "Should the database connection helper live in the db package (simpler — import and use directly), or will each consuming app create its own connection (more flexible — each app controls its own pool settings)?" (Default: in db package)
+
+5. **Existing `packages/db/`** — If it already exists (e.g., from the auth blueprint): "I found an existing `packages/db/` package. I'll add the new schema group to it without overwriting existing files. Does that sound right?"
+
+Skip questions where the answer is obvious from the project structure or from `.project-context.md`.
+
+## Step 4: Adapt and Scaffold
+
+Based on the project structure, project context, and user answers, adapt the blueprint files.
+
+### 4a. Project Setup
+
+**If monorepo — Package Setup (or merge if exists):**
+
+If `packages/db/` does NOT exist:
+- Create the full package: `package.json`, `tsconfig.json`, `.env.example`
+- Replace all placeholders:
+  - `{{SCOPE}}` -> the project's npm scope (e.g., `@acme`)
+  - `{{GROUP}}` -> the schema group name (e.g., `core`)
+  - `{{GROUP_UPPER}}` -> uppercase for env vars (e.g., `CORE`)
+
+If `packages/db/` already exists:
+- Merge the new schema group's export into existing `package.json` exports
+- Merge new scripts into existing scripts (don't overwrite existing ones like `build`, `typecheck`, `clean`)
+- Skip `tsconfig.json` if it already exists and looks correct
+- Add `{{GROUP_UPPER}}_DATABASE_URL` to existing `.env.example`
+
+**If single-repo — Directory Setup:**
+
+- Create `src/db/` directory (no separate `package.json` — use root)
+- Add `{{GROUP_UPPER}}_DATABASE_URL` to root `.env.example` (or `.env` if that's the convention)
+- No separate `tsconfig.json` needed — inherits from root
+- Replace placeholders in files: `{{GROUP}}`, `{{GROUP_UPPER}}`
+- Skip `{{SCOPE}}` — use direct imports instead (`@/db/{{GROUP}}` or `#db/{{GROUP}}`)
+
+### 4b. Schema Group Files
+
+- Create `src/{{GROUP}}/` directory
+- Copy example entity file (if user said yes) — replace all placeholders
+- Create barrel `index.ts` with re-exports
+- Copy `client.ts` helper (if user chose "in db package") — replace placeholders
+
+### 4c. Drizzle Config
+
+- **Monorepo:** Create `packages/db/drizzle/{{GROUP}}/` directory
+- **Single-repo:** Create `drizzle/{{GROUP}}/` at project root
+- Copy `drizzle.config.ts` — replace `{{GROUP}}`, `{{GROUP_UPPER}}`
+- Adjust schema file paths based on project type:
+  - Monorepo: `"./src/{{GROUP}}/example.ts"` (relative to `packages/db/`)
+  - Single-repo: `"./src/db/{{GROUP}}/example.ts"` (relative to project root)
+- Verify schema file paths match actual files created in 4b
+
+### 4d. Seed Script (optional)
+
+- Create `src/scripts/` directory (if it doesn't exist)
+- Copy `seed.ts` — replace placeholders, adjust entity imports
+- If a seed script already exists, ask before overwriting
+
+### 4e. Project Integration
+
+**If monorepo:**
+- Add `{{GROUP}}:generate`, `{{GROUP}}:migrate` tasks to `turbo.json` (both `cache: false`) — merge into existing tasks
+- Add convenience scripts to root `package.json`:
+  - `db:generate` -> `turbo run {{GROUP}}:generate --filter={{SCOPE}}/db --no-cache`
+  - `db:migrate` -> `turbo run {{GROUP}}:migrate --filter={{SCOPE}}/db --no-cache`
+  - `db:studio` -> `turbo run drizzle:studio:{{GROUP}} --filter={{SCOPE}}/db --no-cache`
+  - `db:seed` -> `turbo run seed --filter={{SCOPE}}/db --no-cache`
+- Verify `pnpm-workspace.yaml` includes `packages/*`
+
+**If single-repo:**
+- Add scripts directly to root `package.json` (direct drizzle-kit calls, no Turbo):
+  - `db:generate` -> `drizzle-kit generate --config ./drizzle/{{GROUP}}/drizzle.config.ts`
+  - `db:migrate` -> `drizzle-kit generate --config ./drizzle/{{GROUP}}/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/{{GROUP}}/drizzle.config.ts`
+  - `db:studio` -> `drizzle-kit studio --config ./drizzle/{{GROUP}}/drizzle.config.ts`
+  - `db:seed` -> `tsx src/db/scripts/seed.ts`
+- Add drizzle-orm, dotenv as dependencies and drizzle-kit, pg, @types/pg, tsx as devDependencies
+- No `turbo.json` changes needed
+
+## Step 5: Update Project Context
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### db-drizzle-postgres
+blueprint: db-drizzle-postgres
+choices:
+  schema_group: <group name>
+  include_example: <true|false>
+  include_seed: <true|false>
+  connection_helper: <in-db-package|per-app>
+files_created:
+  - <list of all files created or modified>
+env_vars_added:
+  - <GROUP_UPPER>_DATABASE_URL
+scripts_added:
+  db_package:
+    - <group>:generate
+    - <group>:migrate
+    - drizzle:studio:<group>
+    - seed
+  root:
+    - db:generate
+    - db:migrate
+    - db:studio
+    - db:seed
+  turbo_tasks:
+    - <group>:generate
+    - <group>:migrate
+```
+
+If `.project-context.md` does not exist, create it with the standard header and the Installed Blueprints section. Log a note: "No discovery or foundation context found. Consider running `/discover` and `/scaffold-foundation` for a complete project context."
+
+### Inject Maintenance Rules
+
+Append the condensed maintenance rules to the target project's rules file(s):
+
+1. If `CLAUDE.md` exists in the target project -> append rules there
+2. If `AGENTS.md` exists in the target project -> append rules there
+3. If both exist -> append to both (keep them in sync)
+4. If neither exists -> ask the user which AI coding tool(s) they use:
+   - Claude Code -> create CLAUDE.md with a `## Maintenance Rules` section
+   - OpenCode or Cursor -> create AGENTS.md with a `## Maintenance Rules` section (both tools read AGENTS.md)
+   - Multiple tools -> create all applicable files
+
+The maintenance rules content is identical regardless of which file it goes into:
+
+```markdown
+### db-drizzle-postgres maintenance
+- After creating a new schema file: add it to `drizzle/<group>/drizzle.config.ts` schema array AND the group's `index.ts` barrel export
+- After any schema change: run `pnpm <group>:generate && pnpm <group>:migrate`
+- After adding a new schema group: create drizzle config, add package.json export, add scripts (see BLUEPRINT.md "Adding a New Schema Group")
+- After updating drizzle-orm/drizzle-kit: run generate and check migration diff for unexpected changes
+- Never use glob patterns in drizzle.config.ts schema — always list files explicitly, excluding index.ts
+```
+
+If the `## Maintenance Rules` heading already exists (from another blueprint), only add the `### db-drizzle-postgres maintenance` subsection — do not duplicate the heading.
+
+## Step 6: Output Summary
+
+After scaffolding, provide the user with a clear summary:
+
+### Packages to Install
+
+List every package that needs to be installed. Adjust based on project type and what's already installed:
+
+**If monorepo:**
+```bash
+# In packages/db/
+pnpm add drizzle-orm dotenv
+pnpm add -D drizzle-kit pg @types/pg tsx typescript
+```
+
+**If single-repo:**
+```bash
+# At project root
+pnpm add drizzle-orm dotenv
+pnpm add -D drizzle-kit pg @types/pg tsx
+```
+
+### Environment Variables
+
+```env
+# Monorepo: packages/db/.env | Single-repo: .env at root
+{{GROUP_UPPER}}_DATABASE_URL=postgresql://user:password@localhost:5432/{{GROUP}}_db
+```
+
+### Manual Steps Remaining
+
+1. **Create a PostgreSQL database** — `createdb {{GROUP}}_db` (or use your database hosting provider)
+2. **Set DATABASE_URL** — update the `.env` file with your actual connection string
+3. **Install dependencies** — `pnpm install` from the project root
+4. **Generate initial migration** — `pnpm db:generate`
+5. **Apply migration** — `pnpm db:migrate`
+6. **Verify** — `pnpm db:studio` (should open Drizzle Studio showing your tables)
+7. **(Optional) Run seed** — `pnpm db:seed` (inserts sample data)
+
+### Files Created
+
+List every file that was created or modified, with a one-line description.
+
+### Next Steps
+
+- Replace the example entity with your actual domain entities
+- For each new entity: copy the example file pattern, then follow the "Adding New Entities" checklist in BLUEPRINT.md
+- If you need authentication: run `/scaffold-auth` — it will add auth schemas to the existing `packages/db/`
+
+## Important Notes
+
+- When adapting code, preserve the `// CONFIGURE:` comments so the user can find customization points later.
+- If the project structure differs significantly from the blueprint's assumptions, explain the differences and suggest how to adapt rather than forcing the blueprint's structure.
+- Never overwrite existing files without asking. If a file exists (like `package.json` or `turbo.json`), merge the new additions into it.
+- If `packages/db/` already exists from the auth blueprint, be especially careful to merge — not overwrite — the `package.json` exports, scripts, and dependencies.