@withmata/blueprints 0.2.0

package/.claude/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.

package/.claude/commands/scaffold-foundation.md

@@ -0,0 +1,158 @@
+# Scaffold Foundation
+
+Set up the monorepo project skeleton using the foundation blueprint. **For single-repo applications** (standalone Next.js, Node, or Bun apps), skip this command and go directly to feature blueprints (`/scaffold-db`, `/scaffold-auth`) — they detect single-repo projects and adapt automatically.
+
+## Step 1: Read the Blueprint
+
+Read the full foundation blueprint and all template files:
+
+```
+~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
+~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/files/**/*
+```
+
+If not found at that path, ask the user for the path to their blueprints repo.
+
+The BLUEPRINT.md contains the full architecture documentation, naming conventions, folder conventions, and file manifest. Follow it precisely.
+
+## Step 2: Read Project Context
+
+Check if `.project-context.md` exists in the target project root:
+
+- **If it has a Discovery section**: use the product name to derive the npm scope (e.g., "Acme Dashboard" -> `@acme`). Use technical constraints to inform any decisions.
+
+- **If it has a Foundation section already**: warn the user. Ask: "Foundation was already set up. Do you want to re-scaffold (destructive — replaces existing structure) or skip?"
+
+- **If no context file exists**: that is fine. Ask the user directly for the product name and npm scope.
+
+## Step 3: Understand Current State
+
+Explore the target project directory:
+
+- Is it empty? Fresh start — scaffold everything.
+- Does it already have files? Ask before overwriting anything.
+- Is there an existing `package.json`? Read it for context.
+
+## Step 4: Ask Configuration Questions
+
+Only three questions — skip any already answered by project context:
+
+1. **npm scope** — "What npm scope should internal packages use? (e.g., @acme)" Default: derive from product name.
+2. **Project name** — "What is the human-readable project name?" (for metadata, page titles). Default: from discovery context.
+3. **Node.js version** — "Target Node.js version?" Default: `>=22`.
+
+## Step 5: Scaffold
+
+Create the monorepo skeleton by adapting all files from the blueprint. Replace placeholders:
+
+- `{{SCOPE}}` -> the npm scope (e.g., `@acme`)
+- `{{APP_NAME}}` -> the human-readable name (e.g., `Acme Dashboard`)
+
+### 5a. Root Configuration
+
+From `files/root/`, create at project root:
+- `package.json` — root monorepo config
+- `turbo.json` — task orchestration
+- `pnpm-workspace.yaml` — workspace patterns
+- `biome.json` — linting + formatting
+- `.gitignore` — from `files/root/gitignore`
+
+### 5b. Config Packages
+
+From `files/config/`, create:
+- `config/typescript-config/` — base.json, nextjs.json, react-library.json, package.json
+- `config/tailwind-config/` — shared-styles.css, postcss.config.js, package.json
+
+### 5c. Next.js App Shell
+
+From `files/apps/web/`, create:
+- `apps/web/package.json`
+- `apps/web/tsconfig.json`
+- `apps/web/next.config.ts`
+- `apps/web/env.ts`
+- `apps/web/postcss.config.mjs`
+- `apps/web/app/layout.tsx`
+- `apps/web/app/page.tsx`
+- `apps/web/app/globals.css`
+
+### 5d. Empty Workspace Directories
+
+Create empty directories for feature blueprints:
+- `apis/` — backend feature blueprint will add servers here
+- `packages/` — feature blueprints will add shared packages here
+
+### 5e. Initialize
+
+After creating all files:
+1. Initialize git if not already a repo: `git init`
+2. Run `pnpm install` to verify the workspace configuration is valid
+3. Verify the dev server starts: `pnpm dev` (briefly — just check it boots)
+
+## Step 6: Update Project Context
+
+Append the `## Foundation` section to `.project-context.md`:
+
+```yaml
+## Foundation
+monorepo_tool: turborepo
+package_manager: pnpm
+npm_scope: "<scope>"
+node_version: ">=22"
+workspaces:
+  apps: ["web"]
+  apis: []
+  packages: []
+  config: ["typescript-config", "tailwind-config"]
+framework: next.js (app router)
+typescript: strict
+linter: biome
+styling: tailwind-v4
+env_validation: t3-env + zod
+module_resolution: node subpath imports (#prefix)
+foundation_completed: <date>
+```
+
+If `.project-context.md` does not exist, create it with the standard header and the Foundation 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
+## Maintenance Rules
+
+### Monorepo maintenance
+- After every code change: format with Biome (`pnpm biome check --write .`) before considering work complete
+- After adding new workspace packages: verify `pnpm-workspace.yaml` patterns match, run `pnpm install`
+- After modifying shared configs (`config/typescript-config/`, `config/tailwind-config/`): verify all consumers still build
+- After changing `turbo.json`: verify task ordering with `pnpm turbo run <task> --dry`
+- After adding workspace dependencies: run `pnpm install` to create workspace links
+- Keep `turbo.json` tasks with `cache: false` for any task with side effects (migrations, code generation)
+```
+
+## Step 7: Summarize
+
+Tell the user:
+
+- Project structure overview (directory tree)
+- What was configured (scope, Node version, tooling)
+- How to start development: `pnpm dev`
+- Available feature blueprints to install next
+- Suggest: "Run `/scaffold-auth` to add authentication. Other feature blueprints: ui-shared-components, tailwind-v4, db-drizzle-postgres."
+
+## Important Notes
+
+- Never overwrite existing files without asking.
+- Preserve all `// CONFIGURE:` comments in generated files so the user can find customization points.
+- The Tailwind config is intentionally minimal — the UI feature blueprint extends it with shadcn, animations, and component-specific styles.
+- Feature blueprints will add scripts to root `package.json` and tasks to `turbo.json` — the foundation provides the base that they extend.

package/.cursor/commands/audit.md

@@ -0,0 +1,179 @@
+# Project Audit
+
+Run a health check against available blueprints. Analyze this project's current state and recommend improvements, missing best practices, or blueprints that could replace hand-rolled infrastructure. This command is read-only — it does not modify any files.
+
+## Step 1: Read Available Blueprints
+
+Load all available blueprint specs to understand what is possible:
+
+```
+~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
+~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
+~/Documents/WithMata/my-blueprints/blueprints/features/auth-better-auth/BLUEPRINT.md
+```
+
+Also scan for any additional feature blueprints:
+
+```
+~/Documents/WithMata/my-blueprints/blueprints/features/*/BLUEPRINT.md
+```
+
+Only consider a blueprint "available" if its BLUEPRINT.md has `Status: Complete`. If not found at these paths, ask the user for the path to their blueprints repo.
+
+## Step 2: Read Project Context
+
+Check if `.project-context.md` exists in this project root.
+
+- **If it exists**: read it fully. Note which stages are complete (Discovery, Foundation, Installed Blueprints) and what choices were made.
+- **If it does not exist**: note this — it means either no blueprints have been used, or the project predates the blueprint system.
+
+## Step 3: Explore the Project
+
+Regardless of whether project context exists, explore the actual project to understand its true state. If `.project-context.md` contradicts what you find in the actual files, trust the files and note the discrepancy.
+
+### 3a. Product & Planning
+
+- Does `docs/product/` exist? Are there product briefs, user stories, or discovery artifacts?
+- Is there any structured product documentation, or just a README?
+
+### 3b. Project Structure & Type
+
+- **Detect project type:**
+  - **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
+  - Record as `monorepo` or `single-repo` in the report
+- What package manager? Check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `bun.lock`
+- If monorepo: What workspaces exist? List `apps/`, `packages/`, `apis/`, `config/` or equivalent
+- Is there a `biome.json`? ESLint config? Prettier config?
+- Is TypeScript strict? Check `tsconfig.json` for `strict: true` and `noUncheckedIndexedAccess`
+- Are there shared config packages? Or is config duplicated?
+
+### 3c. Authentication
+
+- Is there an auth system? Search for:
+  - Better Auth config files (`better-auth`, `createAuthClient`)
+  - NextAuth/Auth.js files (`auth.ts`, `[...nextauth]`, `authOptions`)
+  - Hand-rolled auth (JWT imports, `bcrypt`, `jsonwebtoken`, session handling in middleware)
+  - Third-party services (Clerk, Auth0, Supabase auth, Firebase auth)
+- Are there login/signup pages? Route protection middleware?
+- Are there organization/team/workspace features?
+
+### 3d. Database
+
+- Is Drizzle set up? Check for `drizzle.config.ts`, `drizzle-kit`
+- Other ORMs? Check for Prisma (`schema.prisma`), TypeORM, Knex
+- Is there a shared DB package, or is database access scattered?
+
+### 3e. Styling & UI
+
+- Tailwind version? Check `tailwindcss` version in package.json — v3 (JS config) vs v4 (CSS config)
+- Is there a shared UI package, or are components duplicated?
+- Component library? shadcn/ui, Radix, MUI, Chakra?
+
+### 3f. Environment & Validation
+
+- How are env vars handled? t3-env, raw `process.env`, dotenv only?
+- Is there input validation? Zod, Valibot, Yup, Joi?
+
+### 3g. Code Quality
+
+- Are there patterns that diverge from best practices?
+  - Default exports where named exports are preferred
+  - Missing barrel exports (`index.ts`) in packages
+  - File-type organization instead of feature-based
+  - Missing or inconsistent error handling
+
+### 3h. Blueprint Dependency Check
+
+For each blueprint listed under `## Installed Blueprints` in `.project-context.md`:
+- Read its `## Blueprint Dependencies` section from the BLUEPRINT.md
+- Check if each `required` dependency is also listed in Installed Blueprints
+- If a required dependency is missing, include it in the report as a recommendation
+
+Example finding: "auth-better-auth is installed but its required dependency db-drizzle-postgres is not. Auth created a minimal db structure that lacks the full schema-group patterns. Run `/scaffold-db` to add the complete db patterns — it will merge without overwriting auth files."
+
+## Step 4: Generate the Audit Report
+
+Present findings as a structured report. Be concrete and specific — reference actual files and patterns found.
+
+### Report Format
+
+---
+
+**Project Audit: [project name or directory name]**
+
+### Current State
+
+| Area | Status | Details |
+|------|--------|---------|
+| Product Discovery | [done / not found / partial] | [Brief note] |
+| Foundation / Structure | [done / partial / needs work] | [Brief note] |
+| Authentication | [blueprint / hand-rolled / third-party / none] | [Brief note] |
+| Database | [Drizzle / Prisma / other / none] | [Brief note] |
+| Styling | [Tailwind v4 / v3 / other] | [Brief note] |
+| Code Quality | [good / needs attention] | [Brief note] |
+
+### Recommendations
+
+For each recommendation:
+
+1. **[Priority: High/Medium/Low] [Category] — [One-line summary]**
+   - **What we found:** [Specific observation referencing actual files]
+   - **Why it matters:** [Impact on the project — explain for non-technical users too]
+   - **Action:** [Exact command or step to fix it]
+
+---
+
+### Recommendation Priority Guidelines
+
+**High priority** — things that block progress or create real risk:
+- No auth system and the product needs user accounts
+- No monorepo structure in a multi-workspace project
+- Hand-rolled auth with security gaps (plain text passwords, no CSRF, no rate limiting)
+- Missing environment variable validation
+
+**Medium priority** — things that improve quality and maintainability:
+- A blueprint could replace hand-rolled infrastructure
+- Missing product documentation for a project still figuring out its direction
+- Inconsistent patterns across workspaces
+- Tailwind v3 when v4 is available
+- ESLint + Prettier when Biome could replace both
+
+**Low priority** — nice-to-haves:
+- Blueprints in development that are not yet available (mention them as "coming soon")
+- Style preferences that do not affect functionality
+- Optimizations for mature projects
+
+## Step 5: Provide Actionable Next Steps
+
+End the report with a clear list of what to do, in recommended order:
+
+### Next Steps
+
+```
+# Run these in order — each one is independent, stop whenever you want
+
+1. [command]    # [what it does and why]
+2. [command]    # [what it does and why]
+...
+```
+
+For blueprint commands, use the slash command format: `/discover`, `/scaffold-foundation`, `/scaffold-auth`
+
+For non-blueprint improvements, include the actual shell commands or instructions.
+
+## Tone Guidelines
+
+- **Be honest.** If the project is in great shape, say so. Do not manufacture recommendations.
+- **Be warm and accessible.** The user may be non-technical. Explain WHY something matters, not just what to do.
+- **Be specific.** "Your auth looks hand-rolled" is not helpful. "I found JWT signing in `lib/auth.ts` without CSRF protection — the auth blueprint handles this with Better Auth's built-in security" is helpful.
+- **Separate facts from opinions.** "You are using ESLint + Prettier" is a fact. "Biome could replace both with simpler config" is a recommendation — label it as such.
+- **Do not overwhelm.** Lead with the 3-5 most impactful recommendations. If there are many findings, prioritize.
+- **Celebrate what is done well.** If something follows best practices, acknowledge it briefly.
+
+## Important Notes
+
+- This command is **read-only**. It does not modify any files — it only reads and reports.
+- Only recommend blueprints with `Status: Complete`. Mention planned blueprints (tailwind-v4, ui-shared-components) as "coming soon" if relevant, but do not suggest running commands for them.
+- If the project is empty or brand new, keep the report short: "This is a fresh project. Here is where to start." and suggest `/discover` or `/scaffold-foundation`.
+- If everything looks good, say so: "This project is in great shape. No immediate recommendations."