@withmata/blueprints 0.3.3 → 0.3.4

package/.claude/skills/audit/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: audit
-description: Run a project health check against available blueprints (read-only analysis)
-allowed-tools: Read, Glob, Grep, Bash(git *), Bash(ls *)
+description: Run a project health check against available blueprints (read-only analysis, with optional upgrade execution)
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
 
 # 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.
+Run a health check against available blueprints. Analyze this project's current state, check installed blueprints for available upgrades, and recommend improvements. The analysis phase is read-only — modifications only happen if the user explicitly approves upgrades in Step 6.
 
 ## Step 1: Read Available Blueprints
 
@@ -15,22 +15,18 @@ Load all available blueprint specs to understand what is possible:
 ```
 ~/.withmata/blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
 ~/.withmata/blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
-~/.withmata/blueprints/blueprints/features/auth-better-auth/BLUEPRINT.md
-```
-
-Also scan for any additional feature blueprints:
-
-```
 ~/.withmata/blueprints/blueprints/features/*/BLUEPRINT.md
 ```
 
 Only consider a blueprint "available" if its BLUEPRINT.md has `Status: Complete`. If not found, run `npx @withmata/blueprints` to install.
 
+For each available blueprint, also read its template files (`files/**/*`) — you'll need these for upgrade comparison in Step 4.
+
 ## 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 exists**: read it fully. Note which stages are complete (Discovery, Foundation, Installed Blueprints) and what choices were made. Pay attention to `installed_at` dates for each blueprint.
 - **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
@@ -75,11 +71,13 @@ Regardless of whether project context exists, explore the actual project to unde
 - 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?
+- Does `shared-styles.css` have the full design system (animations, sidebar tokens, chart tokens) or just the minimal foundation version?
 
 ### 3f. Environment & Validation
 
-- How are env vars handled? t3-env, raw `process.env`, dotenv only?
-- Is there input validation? Zod, Valibot, Yup, Joi?
+- How are env vars handled? t3-env with client/server split, single env.ts, raw `process.env`, dotenv only?
+- Is there `.env.example` with documentation?
+- Is there build-time validation (env imported in `next.config.ts`)?
 
 ### 3g. Code Quality
 
@@ -96,9 +94,44 @@ For each blueprint listed under `## Installed Blueprints` in `.project-context.m
 - 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: Check Installed Blueprints for Upgrades
+
+**Note on system migrations:** System-level migrations (consolidating maintenance folders, renaming legacy fields, upgrading env patterns) are handled by `/scaffold-foundation`'s upgrade mode (Step 1.6a). The audit doesn't define its own migrations — it detects that foundation has upgrades available, which includes any pending migrations. When the user approves, the audit delegates to scaffold-foundation which runs the migrations as part of its upgrade flow.
+
+For each blueprint listed in `.project-context.md` under `## Installed Blueprints`, compare the current blueprint templates against what's installed in the project.
+
+### 4a. For each installed blueprint:
+
+1. Read the `files_created` or `files_modified` list from project context
+2. Read the `installed_at` date
+3. For each file in the blueprint's File Manifest:
+   - Read the current template file from `~/.withmata/blueprints/`
+   - Resolve placeholders (`{{SCOPE}}`, `{{APP_NAME}}`, etc.) using project context values
+   - Read the corresponding file in the project
+   - Compare them and categorize:
+     - **Template updated** — the blueprint template has changed, the project file matches the OLD template (upgrade available)
+     - **New file** — file exists in the current blueprint but not in the project (added since install)
+     - **Unchanged** — template matches project file (no action needed)
+     - **User-modified** — project file differs from both old and new templates (user customized it — flag for careful merge)
+
+4. Check for new dependencies in the blueprint's `package.json` templates that aren't in the project's `package.json`
+
+### 4b. Compile upgrade details
 
-## Step 4: Generate the Audit Report
+For each blueprint with available upgrades, prepare a detailed summary:
+
+- Blueprint name and install date
+- Each file with changes: what specifically changed and why it matters
+- New dependencies that would be added
+- Whether files are blueprint-owned (safe to replace) or user-modified (needs merge)
+
+### 4c. Check for foundation-level upgrades
+
+If foundation is installed, also check:
+- Are there new feature blueprints available that weren't installed? (e.g., env-t3, tailwind-v4, ui-shared-components)
+- Are there structural improvements in the foundation templates?
+
+## Step 5: Generate the Audit Report
 
 Present findings as a structured report. Be concrete and specific — reference actual files and patterns found.
 
@@ -116,57 +149,183 @@ Present findings as a structured report. Be concrete and specific — reference
 | 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] |
+| Styling | [Tailwind v4 full / v4 minimal / v3 / other] | [Brief note] |
+| UI Package | [blueprint / hand-rolled / none] | [Brief note] |
+| Environment Variables | [t3-env split / t3-env single / raw process.env / none] | [Brief note] |
 | Code Quality | [good / needs attention] | [Brief note] |
 
-### Recommendations
+### Blueprint Upgrades Available
+
+For each installed blueprint with updates, show detailed information. Use plain language — explain what the change means for the project, not just what files changed:
+
+```
+┌─────────────────────────────────────────────────────
+│ env-t3  (installed 2026-03-15)
+│
+│ What's improved:
+│
+│   • Better empty value handling
+│     Your environment validation now catches a common
+│     mistake: setting a variable to an empty string
+│     (like DATABASE_URL=) which previously passed
+│     validation but caused crashes at runtime.
+│     File: src/env/server.ts
+│
+│   • Clearer documentation for teammates
+│     The .env.example file now has section headers and
+│     explains what each variable is for, with example
+│     values for local development and production.
+│     File: .env.example
+│
+│ To apply: /scaffold-env
+└─────────────────────────────────────────────────────
+
+┌─────────────────────────────────────────────────────
+│ tailwind-v4  (installed 2026-03-15)
+│
+│ What's improved:
+│
+│   • Ready for dashboards and data pages
+│     New color tokens for charts and sidebar navigation
+│     that work in both light and dark mode. If you build
+│     any analytics pages or admin dashboards, the styling
+│     is ready to go.
+│     File: config/tailwind-config/shared-styles.css
+│
+│   • Cleaner scrollable areas
+│     Added a utility to hide scrollbars while keeping
+│     scroll functionality — useful for custom menus,
+│     sidebars, and overflow containers.
+│     New dependency: tailwind-scrollbar-hide
+│
+│ To apply: /scaffold-tailwind
+└─────────────────────────────────────────────────────
+```
+
+If no upgrades are available for any installed blueprint, say: "All installed blueprints are up to date — you're running the latest patterns."
+
+### Recommended Blueprints (Not Yet Installed)
+
+For each available blueprint that's NOT installed and would benefit this project. Explain the value in terms a non-developer can understand — focus on what it enables for the product, not just the technical implementation:
 
-For each recommendation:
+```
+┌─────────────────────────────────────────────────────
+│ Shared UI Component Library
+│ Blueprint: ui-shared-components
+│
+│ What this gives you:
+│   A central place for all your buttons, forms, cards,
+│   and other interface elements. When you update a
+│   component here, every app in your project gets the
+│   update automatically. No more copy-pasting UI code
+│   between apps and watching them drift apart.
+│
+│   Includes a tool (shadcn) for quickly adding
+│   professionally designed, accessible components —
+│   just run one command to add a button, dialog,
+│   dropdown, or any of 40+ ready-made components.
+│
+│ Ready to install: Yes
+│   Requires: Tailwind design system (installed ✓)
+│
+│ To install: /scaffold-ui
+└─────────────────────────────────────────────────────
+```
+
+### Other Recommendations
+
+For non-blueprint recommendations (code quality, structural improvements):
 
 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]
+   - **Why it matters:** [Impact — 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
+- Hand-rolled auth with security gaps
+- Missing environment variable validation (raw `process.env` usage)
 
 **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
+- Missing product documentation
 - Inconsistent patterns across workspaces
 - Tailwind v3 when v4 is available
-- ESLint + Prettier when Biome could replace both
+- Single `env.ts` instead of client/server split
 
 **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
+---
+
+## Step 6: Offer Actionable Upgrades
+
+After presenting the report, offer to apply changes. This is the transition from read-only analysis to execution.
+
+### Present the action plan:
+
+```
+──────────────────────────────────────────────
+Action Plan
 
-End the report with a clear list of what to do, in recommended order:
+Blueprint upgrades (improvements to what you have):
+  1. foundation — system cleanup + template updates
+  2. env-t3 — better empty value handling, clearer docs
+  3. tailwind-v4 — dashboard tokens, scrollbar utility
 
-### Next Steps
+New capabilities (not yet installed):
+  4. ui-shared-components — shared component library with shadcn
 
+Which would you like to apply? (numbers, "all", or "skip")
+──────────────────────────────────────────────
 ```
-# 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]
-...
+Foundation upgrades always run first when selected — they include system migrations (like consolidating maintenance folders) that other upgrades may depend on.
+
+### On user response:
+
+- **"all"** — run everything in dependency order: foundation first, then other upgrades, then new installs last
+- **Specific numbers** — run only the selected ones, still in the correct order
+- **"skip"** — end the audit without making changes
+
+### Execution order:
+
+1. **Foundation upgrades first** — includes system migrations that clean up legacy patterns
+2. **Other blueprint upgrades** — in dependency order (env, tailwind, db, auth)
+3. **New blueprint installs** — in dependency order (tailwind before UI, db before auth)
+
+For each approved action:
+1. Announce what's happening in plain language: "Upgrading your environment variable setup..."
+2. For system migrations: execute the migration directly (consolidate files, rename fields)
+3. For blueprint upgrades/installs: follow that scaffold skill's upgrade mode (Step 1.6)
+4. Report result: "Done — updated 2 files, your env setup now catches empty values"
+5. Move to next
+
+### After all upgrades:
+
+Present a final summary:
+
 ```
+──────────────────────────────────────────────
+What was done
 
-For blueprint commands, use the slash command format: `/discover`, `/scaffold-foundation`, `/scaffold-auth`
+Blueprint upgrades:
+  ✓ foundation — consolidated maintenance rules,
+    cleaned up legacy patterns
+  ✓ env-t3 — updated server.ts, .env.example
+  ✓ tailwind-v4 — updated shared-styles.css, added
+    tailwind-scrollbar-hide
 
-For non-blueprint improvements, include the actual shell commands or instructions.
+Skipped:
+  ○ ui-shared-components — not selected
+
+Next: run pnpm install to pick up new dependencies.
+──────────────────────────────────────────────
+```
 
 ## Tone Guidelines
 
@@ -174,12 +333,13 @@ For non-blueprint improvements, include the actual shell commands or instruction
 - **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.
+- **Do not overwhelm.** Lead with the most impactful findings. If everything is up to date and nothing is missing, keep the report short.
 - **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.
+- Steps 1–5 are read-only analysis. Step 6 is the only step that modifies files, and only with user approval.
+- Only recommend blueprints with `Status: Complete`.
 - 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."
+- If everything is up to date and no recommendations apply: "This project is in great shape. All blueprints are current, no upgrades available."
+- When executing upgrades in Step 6, defer to each scaffold skill's own upgrade mode logic. The audit skill orchestrates but doesn't duplicate the upgrade implementation.

package/.claude/skills/new-project/SKILL.md

@@ -220,7 +220,7 @@ List anything that can't be automated (aggregated from all stages).
 Suggest next steps in terms of product progress, not just technical tasks. Reference specific commands:
 
 - "The product thesis identified [pillar] as a core pillar — `/scaffold-auth` wires in the user accounts and access control to support that."
-- "Other feature blueprints coming soon: UI components, database, Tailwind theming."
+- "Run `/audit` to see all available blueprints and what would benefit your project."
 - "Start building the core product experience — the [archetype]'s primary workflow."
 
 ---

package/.claude/skills/scaffold-auth/SKILL.md

@@ -33,7 +33,48 @@ Check if `.project-context.md` exists in the target project root:
 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
+- Context has `auth-better-auth` in Installed Blueprints -> switch to upgrade mode (Step 1.6)
+
+## Step 1.6: Upgrade Mode
+
+If `auth-better-auth` is found in `.project-context.md` under `## Installed Blueprints`, switch to upgrade mode.
+
+1. **Read installed state** — from project context, get `files_created`, `choices` (plugins, providers, framework), and `installed_at`
+2. **Compare templates against installed files** — auth files are heavily customized, so be extra conservative:
+   - **Blueprint-owned (safe to update):**
+     - Auth client setup (`auth-client.ts`) — compare client plugin configuration pattern
+     - Client schemas (`schema/auth.ts`, `schema/organization.ts`) — compare Zod validation patterns
+     - Client types (`types/organization.ts`) — compare type definitions
+   - **Partially user-owned (merge carefully):**
+     - Server auth config (`auth.ts`) — compare plugin setup, but users add custom plugins. Merge new patterns, don't replace.
+     - Middleware (`middleware.ts`, `route-protection.ts`) — users customize routes. Only update structural patterns.
+     - Env vars — merge into env schema files if env-t3 is installed (add new auth vars, keep existing ones).
+   - **User-owned (never touch):**
+     - Auth database schema (`auth-schema.ts`) — auto-generated by Better Auth
+     - Drizzle config for auth — user-maintained schema file list
+     - Custom hooks, context providers with user business logic
+3. **Present findings:**
+   ```
+   auth-better-auth was installed on <date>. Checking for updates...
+
+   Updated templates:
+     ☐ auth-client.ts — updated client plugin configuration
+     ☐ schema/auth.ts — updated Zod validation
+
+   Merge candidates (will preserve your customizations):
+     ☐ server auth.ts — new plugin option available
+     ☐ middleware.ts — updated middleware pattern
+
+   User-owned (never touched):
+     ✓ auth-schema.ts, drizzle config, custom hooks
+
+   Apply updates?
+   ```
+4. **Apply selectively** — for merge candidates, show the user what's new and let them decide. For auth config, highlight new plugin options or security improvements.
+5. **Update project context** — update `installed_at` date
+6. **Skip to Output Summary**
+
+**Important:** Auth is the most user-customized blueprint. Most files will have been modified. Upgrade mode should focus on: new plugin options, security improvements, updated patterns. Never replace files wholesale — always merge or show diffs.
 
 ## Step 1.7: Check Blueprint Dependencies
 
@@ -204,6 +245,7 @@ Append an entry to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### auth-better-auth
 blueprint: auth-better-auth
+installed_at: <date>
 choices:
   database: <user's choice>
   auth_db_isolation: <separate|shared>
@@ -228,17 +270,21 @@ Also append any significant architectural decisions to the `## Architecture Deci
 
 ### Create Maintenance Skill
 
-Create a project-level maintenance skill for the auth blueprint:
+Append to the shared project-level maintenance skill at `<project>/.claude/skills/project-maintenance/SKILL.md`.
 
-**File:** `<project>/.claude/skills/auth-maintenance/SKILL.md`
+If the file does not exist, create it with frontmatter:
 
 ```yaml
 ---
-name: auth-maintenance
-description: Maintenance rules for Better Auth. Invoke when modifying auth config, providers, session settings, or auth schema.
+name: project-maintenance
+description: Maintenance rules for all installed blueprints. Invoke when modifying schemas, env vars, auth config, workspace configs, UI components, or Tailwind tokens.
 user-invocable: false
 ---
+```
+
+Then append:
 
+```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
@@ -248,6 +294,8 @@ user-invocable: false
 - Never edit the auto-generated auth schema directly — modify the Better Auth config and regenerate
 ```
 
+If a `### auth-better-auth maintenance` section already exists in the file, skip — do not duplicate.
+
 ## Step 6: Output Summary
 
 After scaffolding, provide the user with a clear summary:

package/.claude/skills/scaffold-db/SKILL.md

@@ -32,9 +32,44 @@ Check if `.project-context.md` exists in the target project root:
 
 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 `db-drizzle-postgres` in Installed Blueprints -> switch to upgrade mode (Step 1.6)
 - Context has `auth-better-auth` installed -> `packages/db/` likely exists already
 
+## Step 1.6: Upgrade Mode
+
+If `db-drizzle-postgres` is found in `.project-context.md` under `## Installed Blueprints`, switch to upgrade mode.
+
+1. **Read installed state** — from project context, get `files_created`, `choices` (schema group, connection helper), and `installed_at`
+2. **Compare templates against installed files** — only compare blueprint-owned files, NOT user schema files:
+   - `packages/db/package.json` — compare exports pattern, scripts, dependencies. Look for new scripts, updated dep versions.
+   - `packages/db/tsconfig.json` — compare TypeScript config.
+   - `packages/db/.env.example` — compare env documentation.
+   - `drizzle/<group>/drizzle.config.ts` — compare config pattern (but NOT the schema file list — that's user-maintained).
+   - `src/<group>/client.ts` — compare connection helper pattern (if included).
+   - `src/scripts/seed.ts` — compare seed script pattern.
+3. **Present findings:**
+   ```
+   db-drizzle-postgres was installed on <date>. Checking for updates...
+
+   Updated templates:
+     ☐ packages/db/package.json — new scripts or updated dependencies
+     ☐ drizzle/<group>/drizzle.config.ts — updated config pattern
+
+   Unchanged:
+     ✓ packages/db/tsconfig.json — no changes
+
+   User-owned (never touched):
+     ✓ src/<group>/*.ts — your schema files
+     ✓ drizzle/<group>/*.sql — your migrations
+
+   Apply updates?
+   ```
+4. **Apply selectively** — merge new scripts/deps into `package.json` without overwriting existing ones. For `drizzle.config.ts`, only update structural patterns — never modify the user's schema file list.
+5. **Update project context** — update `installed_at` date
+6. **Skip to Step 6 (Output Summary)**
+
+**Important:** Schema files (`src/<group>/*.ts`), migration files (`drizzle/<group>/*.sql`), barrel exports (`index.ts`), and the `.env` file are all user-owned. Upgrade mode must never touch these.
+
 ## Step 2: Understand the Target Project
 
 Before making any changes, explore the target project to understand:
@@ -166,6 +201,7 @@ Append an entry to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### db-drizzle-postgres
 blueprint: db-drizzle-postgres
+installed_at: <date>
 choices:
   schema_group: <group name>
   include_example: <true|false>
@@ -195,17 +231,21 @@ If `.project-context.md` does not exist, create it with the standard header and
 
 ### Create Maintenance Skill
 
-Create a project-level maintenance skill for the database blueprint:
+Append to the shared project-level maintenance skill at `<project>/.claude/skills/project-maintenance/SKILL.md`.
 
-**File:** `<project>/.claude/skills/db-maintenance/SKILL.md`
+If the file does not exist, create it with frontmatter:
 
 ```yaml
 ---
-name: db-maintenance
-description: Maintenance rules for Drizzle + PostgreSQL database. Invoke when modifying schemas, adding entities, or running migrations.
+name: project-maintenance
+description: Maintenance rules for all installed blueprints. Invoke when modifying schemas, env vars, auth config, workspace configs, UI components, or Tailwind tokens.
 user-invocable: false
 ---
+```
 
+Then append:
+
+```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`
@@ -214,6 +254,8 @@ user-invocable: false
 - Never use glob patterns in drizzle.config.ts schema — always list files explicitly, excluding index.ts
 ```
 
+If a `### db-drizzle-postgres maintenance` section already exists in the file, skip — do not duplicate.
+
 ## Step 6: Output Summary
 
 After scaffolding, provide the user with a clear summary:

package/.claude/skills/scaffold-env/SKILL.md

@@ -32,7 +32,43 @@ Check if `.project-context.md` exists in the target project root:
 
 When project context provides clear answers, skip the corresponding questions in Step 3. For example:
 - Context has `auth-better-auth` installed -> pre-populate auth env vars
-- Context has `env-t3` in Installed Blueprints -> warn about existing install
+- Context has `env-t3` in Installed Blueprints -> switch to upgrade mode (Step 1.6)
+
+## Step 1.6: Upgrade Mode
+
+If `env-t3` is found in `.project-context.md` under `## Installed Blueprints`, switch to upgrade mode instead of a fresh install.
+
+1. **Read installed state** — from project context, get the `files_created` list and `choices` (env locations, apps configured)
+2. **Compare templates against installed files** — for each file in the blueprint's File Manifest:
+   - Read the current template from `~/.withmata/blueprints/blueprints/features/env-t3/files/`
+   - Resolve `{{APP_NAME}}` using project context
+   - Read the corresponding file in the project
+   - Categorize:
+     - **Updated** — template has changed (new Zod patterns, new structure)
+     - **New** — file exists in current blueprint but not in the project (e.g., new backend env template)
+     - **Unchanged** — template matches installed file (skip)
+     - **User-modified** — file differs from both the old and new templates (user added their own env vars — this is expected and normal for env files)
+3. **Present findings:**
+   ```
+   env-t3 was installed on <date>. Checking for updates...
+
+   Updated templates:
+     ☐ src/env/server.ts — updated Zod patterns
+     ☐ .env.example — new documentation sections
+
+   New files available:
+     ☐ apis/server/src/env.ts — backend env validation (not set up previously)
+
+   User-customized (will merge, not replace):
+     ✓ src/env/client.ts — you've added custom vars (keeping yours)
+
+   Apply updates?
+   ```
+4. **Apply selectively** — for user-modified env files (which is most of them), merge new structural patterns while preserving user-added variables. Never delete user env vars.
+5. **Update project context** — update `installed_at` date
+6. **Skip to Step 6 (Output Summary)**
+
+**Important:** Env files are almost always user-modified (users add their own variables). Upgrade mode for env should focus on structural changes (new `// CONFIGURE:` sections, updated Zod patterns, new `emptyStringAsUndefined` options) rather than replacing the whole file.
 
 ## Step 2: Understand the Target Project
 
@@ -140,6 +176,7 @@ Append an entry to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### env-t3
 blueprint: env-t3
+installed_at: <date>
 choices:
   nextjs_env_location: src/env/
   backend_env_location: src/env.ts
@@ -156,17 +193,21 @@ If `.project-context.md` does not exist, create it with the standard header and
 
 ### Create Maintenance Skill
 
-Create a project-level maintenance skill for the env blueprint:
+Append to the shared project-level maintenance skill at `<project>/.claude/skills/project-maintenance/SKILL.md`.
 
-**File:** `<project>/.claude/skills/env-maintenance/SKILL.md`
+If the file does not exist, create it with frontmatter:
 
 ```yaml
 ---
-name: env-maintenance
-description: Maintenance rules for T3 Env validated environment variables. Invoke when adding, removing, or modifying environment variables.
+name: project-maintenance
+description: Maintenance rules for all installed blueprints. Invoke when modifying schemas, env vars, auth config, workspace configs, UI components, or Tailwind tokens.
 user-invocable: false
 ---
+```
 
+Then append:
+
+```markdown
 ### env-t3 maintenance
 - After adding a new env var: add it to the env schema file (client.ts or server.ts), `.env.example`, and `.env.local`
 - NEXT_PUBLIC_* vars go in env/client.ts with explicit runtimeEnv mapping; server vars go in env/server.ts
@@ -175,6 +216,8 @@ user-invocable: false
 - Keep .env.example documented with section headers and local/production hints
 ```
 
+If a `### env-t3 maintenance` section already exists in the file, skip — do not duplicate.
+
 ## Step 6: Output Summary
 
 After scaffolding, provide the user with a clear summary:

package/.claude/skills/scaffold-foundation/SKILL.md

@@ -36,19 +36,53 @@ If not found, run `npx @withmata/blueprints` to install.
 
 The BLUEPRINT.md files contain the full architecture documentation, naming conventions, folder conventions, and file manifests. Follow them precisely.
 
-## Step 2: Read Project Context
+## Step 1.5: 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**: **switch to upgrade mode** (see Step 2b below).
+- **If it has a Foundation section already**: switch to upgrade mode (Step 1.6).
 
 - **If no context file exists**: that is fine. Ask the user directly for the product name and npm scope. Proceed with install mode.
 
-### Step 2b: Upgrade Mode Detection
+## Step 1.6: Upgrade Mode
 
-When foundation is already installed, compare what's currently in the project against what the blueprints now offer. Check for:
+When foundation is already installed, run migrations first, then check for template updates and missing features.
+
+### 1.6a: System Migrations
+
+Check for legacy patterns from older blueprint versions and offer to migrate them. Run these checks in order:
+
+**Migration: Separate maintenance skills → consolidated `project-maintenance/`**
+
+Scan `.claude/skills/` in the project for individual maintenance skill directories:
+- `auth-maintenance/`
+- `db-maintenance/`
+- `env-maintenance/`
+- `tailwind-maintenance/`
+- `ui-maintenance/`
+- `monorepo-maintenance/`
+
+If any are found:
+1. Read each `SKILL.md` to extract the maintenance rules (the `### {name} maintenance` sections)
+2. Create (or update) `.claude/skills/project-maintenance/SKILL.md` with the consolidated frontmatter and all extracted sections
+3. Remove the old individual directories
+4. Report: "Migrated {n} separate maintenance skills into one `project-maintenance/SKILL.md`"
+
+**Migration: `foundation_completed` → `installed_at`**
+
+Check `.project-context.md` for `foundation_completed:` under `## Foundation`. If found, rename the field to `installed_at:`.
+
+**Future migrations go here.** Each migration should:
+- Check for the legacy pattern
+- Only run if the legacy pattern is detected (idempotent)
+- Report what was changed
+- Be safe to run multiple times (no-op if already migrated)
+
+### 1.6b: Template Updates and Missing Features
+
+After migrations, compare what's currently in the project against what the blueprints now offer:
 
 1. **Foundation file updates** — Compare each foundation template file against the installed version. Flag files where the blueprint template has changed (e.g., updated `turbo.json` task structure, new fields in `package.json`).
 
@@ -61,6 +95,10 @@ When foundation is already installed, compare what's currently in the project ag
    ```
    Foundation was installed on <date>. Here's what's available:
 
+   Migrations applied:
+     ✓ Consolidated 4 maintenance skills into project-maintenance/SKILL.md
+     ✓ Renamed foundation_completed → installed_at in project context
+
    Updates to existing files:
      ☐ turbo.json — new task caching strategy
      ☐ apps/web/next.config.ts — updated config pattern
@@ -76,11 +114,11 @@ When foundation is already installed, compare what's currently in the project ag
 
 4. Apply only what the user selects. For each selected feature, follow its blueprint's integration steps (adapted to the existing project). Skip configuration questions where the answer is already in `.project-context.md`.
 
-5. Update `.project-context.md` with the newly installed features and update `foundation_completed` date.
+5. Update `.project-context.md` with the newly installed features and update `installed_at` date.
 
 After upgrade mode completes, skip to Step 7 (Summarize).
 
-## Step 3: Understand Current State
+## Step 2: Understand Current State
 
 *(Install mode only — skipped in upgrade mode)*
 
@@ -239,7 +277,7 @@ linter: biome
 styling: tailwind-v4
 env_validation: t3-env + zod
 module_resolution: node subpath imports (#prefix)
-foundation_completed: <date>
+installed_at: <date>
 ```
 
 Then append `## Installed Blueprints` with entries for every feature that was applied:
@@ -253,19 +291,25 @@ Then append `## Installed Blueprints` with entries for every feature that was ap
 
 **Verify the file exists and is well-formed before proceeding to Step 7.** If it's missing or empty, that is a bug — fix it before summarizing.
 
-### Create Maintenance Skills
+### Create Maintenance Skill
+
+All blueprints share a single project-level maintenance skill. Create or append to:
 
-Create the foundation maintenance skill:
+**File:** `<project>/.claude/skills/project-maintenance/SKILL.md`
 
-**File:** `<project>/.claude/skills/monorepo-maintenance/SKILL.md`
+If the file does not exist, create it with the frontmatter header:
 
 ```yaml
 ---
-name: monorepo-maintenance
-description: Maintenance rules for the Turborepo monorepo foundation. Invoke when modifying workspace configs, shared packages, or Turbo tasks.
+name: project-maintenance
+description: Maintenance rules for all installed blueprints. Invoke when modifying schemas, env vars, auth config, workspace configs, UI components, or Tailwind tokens.
 user-invocable: false
 ---
+```
 
+Then append sections for each blueprint applied in this run. Foundation always adds:
+
+```markdown
 ### 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`
@@ -273,11 +317,32 @@ user-invocable: false
 - 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)
+
+### env-t3 maintenance
+- After adding a new env var: add it to the env schema file (client.ts or server.ts), `.env.example`, and `.env.local`
+- NEXT_PUBLIC_* vars go in env/client.ts with explicit runtimeEnv mapping; server vars go in env/server.ts
+- After removing an env var: remove from schema, .env.example, and .env.local
+- Never access process.env directly — always use the typed env objects (clientEnv, serverEnv, or env)
+- Keep .env.example documented with section headers and local/production hints
 ```
 
-Also create maintenance skills:
-- Always create `env-maintenance/SKILL.md` (see scaffold-env skill for template)
-- If frontend UI: create both `tailwind-maintenance/SKILL.md` and `ui-maintenance/SKILL.md` (see scaffold-tailwind and scaffold-ui skills for templates)
+If frontend UI was applied, also append:
+
+```markdown
+### tailwind-v4 maintenance
+- After adding a new color: add CSS variable to both :root and .dark selectors in shared-styles.css, then map in @theme inline
+- After adding a new app: import the tailwind-config package in the app's globals.css
+- After upgrading Tailwind: check for @import, @theme, or @custom-variant breaking changes
+- Never use tailwind.config.js — all configuration is CSS-based in shared-styles.css
+- Colors use OKLCH color space — do not use hex or RGB
+
+### ui-shared-components maintenance
+- Add shadcn components via `pnpm dlx shadcn@latest add <name>` from packages/ui/
+- Use cn() for all className composition — never concatenate class strings manually
+- Internal imports use #prefix (#components/ui/button); cross-package imports use @scope/ui/components/ui/button
+- After adding a new export directory: add to both exports and imports in packages/ui/package.json
+- After adding a new consuming app: add @import and @source directive to the app's globals.css
+```
 
 ## Step 7: Summarize
 

package/.claude/skills/scaffold-tailwind/SKILL.md

@@ -29,6 +29,29 @@ Check if `.project-context.md` exists in the target project root:
   - Use this to determine if `config/tailwind-config/` exists
 
 - **If it does not exist**: proceed normally — explore the project manually
+- **If `tailwind-v4` is in Installed Blueprints**: switch to upgrade mode (Step 1.6)
+
+## Step 1.6: Upgrade Mode
+
+If `tailwind-v4` is found in `.project-context.md` under `## Installed Blueprints`, switch to upgrade mode.
+
+1. **Read installed state** — from project context, get `files_modified`, `choices`, and `installed_at`
+2. **Compare templates against installed files:**
+   - `config/tailwind-config/shared-styles.css` — compare against current blueprint template. Look for new imports (`@import`), new tokens in `@theme inline`, new CSS variables in `:root` and `.dark`, new base layer rules.
+   - `config/tailwind-config/package.json` — compare dependencies. Look for new or updated packages.
+3. **Present findings:**
+   ```
+   tailwind-v4 was installed on <date>. Checking for updates...
+
+   Updated files:
+     ☐ shared-styles.css — new tokens added (e.g., new sidebar variants, chart colors)
+     ☐ package.json — new dependency: <package>
+
+   Apply updates?
+   ```
+4. **Apply selectively** — `shared-styles.css` is a blueprint-owned file (users customize colors but the structure is ours). For color value changes, ask before overwriting. For new token additions (new `--color-*` vars), safe to append.
+5. **Update project context** — update `installed_at` date
+6. **Skip to Step 6 (Output Summary)**
 
 ## Step 2: Understand the Target Project
 
@@ -111,6 +134,7 @@ Append an entry to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### tailwind-v4
 blueprint: tailwind-v4
+installed_at: <date>
 choices:
   include_sidebar_tokens: <true|false>
   include_chart_tokens: <true|false>
@@ -127,17 +151,21 @@ packages_added:
 
 ### Create Maintenance Skill
 
-Create a project-level maintenance skill:
+Append to the shared project-level maintenance skill at `<project>/.claude/skills/project-maintenance/SKILL.md`.
 
-**File:** `<project>/.claude/skills/tailwind-maintenance/SKILL.md`
+If the file does not exist, create it with frontmatter:
 
 ```yaml
 ---
-name: tailwind-maintenance
-description: Maintenance rules for Tailwind v4 design system. Invoke when modifying theme tokens, colors, or adding new apps.
+name: project-maintenance
+description: Maintenance rules for all installed blueprints. Invoke when modifying schemas, env vars, auth config, workspace configs, UI components, or Tailwind tokens.
 user-invocable: false
 ---
+```
 
+Then append:
+
+```markdown
 ### tailwind-v4 maintenance
 - After adding a new color: add CSS variable to both :root and .dark selectors in shared-styles.css, then map in @theme inline
 - After adding a new app: import the tailwind-config package in the app's globals.css
@@ -146,6 +174,8 @@ user-invocable: false
 - Colors use OKLCH color space — do not use hex or RGB
 ```
 
+If a `### tailwind-v4 maintenance` section already exists in the file, skip — do not duplicate.
+
 ## Step 6: Output Summary
 
 ### Packages Added

package/.claude/skills/scaffold-ui/SKILL.md

@@ -32,6 +32,41 @@ Check if `.project-context.md` exists in the target project root:
 
 When project context provides clear answers, skip the corresponding questions in Step 3.
 
+If `ui-shared-components` is in Installed Blueprints, switch to upgrade mode (Step 1.6).
+
+## Step 1.6: Upgrade Mode
+
+If `ui-shared-components` is found in `.project-context.md` under `## Installed Blueprints`, switch to upgrade mode.
+
+1. **Read installed state** — from project context, get `files_created`, `choices`, and `installed_at`
+2. **Compare templates against installed files:**
+   - `packages/ui/package.json` — compare exports, imports, dependencies. Look for new export patterns, updated deps.
+   - `packages/ui/components.json` — compare shadcn config. Look for updated aliases or style changes.
+   - `packages/ui/utils/cn.ts` — compare utility implementation.
+   - `packages/ui/utils/cva.ts` — compare CVA re-export.
+   - `packages/ui/styles/globals.css` — compare style imports.
+   - `packages/ui/tsconfig.json` — compare TypeScript config.
+   - Check consuming app `globals.css` — verify `@import` and `@source` directives are present and correct.
+3. **Present findings:**
+   ```
+   ui-shared-components was installed on <date>. Checking for updates...
+
+   Updated files:
+     ☐ packages/ui/package.json — new export patterns or dependencies
+     ☐ packages/ui/components.json — updated shadcn configuration
+
+   New files:
+     ☐ packages/ui/utils/cva.ts — new utility (didn't exist in previous version)
+
+   Unchanged:
+     ✓ packages/ui/utils/cn.ts — no changes
+
+   Apply updates?
+   ```
+4. **Apply selectively** — `package.json` exports and `components.json` are blueprint-owned. `components/ui/` files are user-owned (shadcn-generated) — never touch those.
+5. **Update project context** — update `installed_at` date
+6. **Skip to Step 6 (Output Summary)**
+
 ## Step 2: Understand the Target Project
 
 ### 2a. Detect Project Type
@@ -128,6 +163,7 @@ Append an entry to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### ui-shared-components
 blueprint: ui-shared-components
+installed_at: <date>
 choices:
   shadcn_style: <style>
   icon_library: <library>
@@ -142,17 +178,21 @@ packages_added:
 
 ### Create Maintenance Skill
 
-Create a project-level maintenance skill:
+Append to the shared project-level maintenance skill at `<project>/.claude/skills/project-maintenance/SKILL.md`.
 
-**File:** `<project>/.claude/skills/ui-maintenance/SKILL.md`
+If the file does not exist, create it with frontmatter:
 
 ```yaml
 ---
-name: ui-maintenance
-description: Maintenance rules for shared UI component library. Invoke when adding components, icons, or modifying the UI package.
+name: project-maintenance
+description: Maintenance rules for all installed blueprints. Invoke when modifying schemas, env vars, auth config, workspace configs, UI components, or Tailwind tokens.
 user-invocable: false
 ---
+```
 
+Then append:
+
+```markdown
 ### ui-shared-components maintenance
 - Add shadcn components via `pnpm dlx shadcn@latest add <name>` from packages/ui/
 - Use cn() for all className composition — never concatenate class strings manually
@@ -161,6 +201,8 @@ user-invocable: false
 - After adding a new consuming app: add @import and @source directive to the app's globals.css
 ```
 
+If a `### ui-shared-components maintenance` section already exists in the file, skip — do not duplicate.
+
 ## Step 6: Output Summary
 
 ### Packages to Install

package/ENGINEERING.md

@@ -43,5 +43,5 @@ These preferences apply to ALL blueprints in this repo and to any project scaffo
 - **Project context:** Every blueprint appends to `.project-context.md` in the target project root — tool-agnostic location readable by any AI coding tool
 - **Skills live in `.claude/skills/<name>/SKILL.md`** — single source of truth. Installed globally to `~/.claude/skills/`, `~/.config/opencode/skills/`, `~/.cursor/skills/` via the CLI. OpenCode and Cursor also read `~/.claude/skills/` as a cross-tool fallback.
 - **Rules/preferences are in `ENGINEERING.md`** — tool-specific files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/engineering.mdc`) point to it
-- **Available skills:** `/new-project`, `/discover`, `/scaffold-foundation`, `/scaffold-auth`, `/scaffold-db`, `/audit`, plus `blueprint-catalog` (background, auto-invoked)
+- **Available skills:** `/new-project`, `/discover`, `/scaffold-foundation`, `/scaffold-env`, `/scaffold-tailwind`, `/scaffold-ui`, `/scaffold-auth`, `/scaffold-db`, `/audit`, plus `blueprint-catalog` (background, auto-invoked)
 - **BLUEPRINT.md required** in every blueprint directory. Placeholder blueprints must still have a BLUEPRINT.md documenting intended scope.

package/blueprints/features/auth-better-auth/BLUEPRINT.md

@@ -1,5 +1,9 @@
 # Auth Blueprint — Better Auth + Drizzle
 
+## Tier
+
+Feature
+
 ## Problem
 
 Full authentication and authorization for a TypeScript monorepo: multi-provider social login, email/password with verification, password reset, organization-based multi-tenancy with role-based permissions (owner/admin/member), invitation system, and session management with cookie-based route protection.

package/blueprints/features/db-drizzle-postgres/BLUEPRINT.md

@@ -551,6 +551,7 @@ Appends to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### db-drizzle-postgres
 blueprint: db-drizzle-postgres
+installed_at: <date>
 choices:
   schema_group: {{GROUP}}
   include_example: true|false

package/blueprints/features/env-t3/BLUEPRINT.md

@@ -297,6 +297,7 @@ Appends to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### env-t3
 blueprint: env-t3
+installed_at: <date>
 choices:
   nextjs_env_location: src/env/
   backend_env_location: src/env.ts

package/blueprints/features/tailwind-v4/BLUEPRINT.md

@@ -252,6 +252,7 @@ Appends to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### tailwind-v4
 blueprint: tailwind-v4
+installed_at: <date>
 choices:
   include_sidebar_tokens: true
   include_chart_tokens: true

package/blueprints/features/ui-shared-components/BLUEPRINT.md

@@ -338,6 +338,7 @@ Appends to `.project-context.md` under `## Installed Blueprints`:
 ```yaml
 ### ui-shared-components
 blueprint: ui-shared-components
+installed_at: <date>
 choices:
   shadcn_style: new-york
   icon_library: lucide

package/blueprints/foundation/monorepo-turbo/BLUEPRINT.md

@@ -372,7 +372,7 @@ linter: biome
 styling: tailwind-v4
 env_validation: t3-env + zod
 module_resolution: node subpath imports (#prefix)
-foundation_completed: <date>
+installed_at: <date>
 ```
 
 

package/dist/index.js

@@ -6,7 +6,7 @@ import pc3 from "picocolors";
 
 // src/constants.ts
 var API_URL = process.env["WITHMATA_API_URL"] || "https://blueprints.withmata.dev";
-var VERSION = "0.3.3";
+var VERSION = "0.3.4";
 
 // src/steps/auth.ts
 import { log } from "@clack/prompts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withmata/blueprints",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Set up AI-powered project blueprints for Claude Code, OpenCode, and Cursor",
   "type": "module",
   "bin": {

package/.claude/skills/new-blueprint/SKILL.md

@@ -1,270 +0,0 @@
----
-name: new-blueprint
-description: Add a new blueprint to the withmata blueprints repository
----
-
-# Add a New Blueprint
-
-Guide the user through adding a new blueprint to this repo. This command ensures every blueprint follows the established conventions and is fully wired up.
-
-## Step 1: Understand the Conventions
-
-Read these files to understand the system you're adding to:
-
-```
-ENGINEERING.md                # Engineering preferences
-README.md                    # System overview and blueprint anatomy
-CHANGELOG.md                 # To update when done
-```
-
-Also scan existing complete blueprints to understand the quality bar:
-
-```
-blueprints/features/auth-better-auth/BLUEPRINT.md    # Best example of a feature blueprint
-blueprints/foundation/monorepo-turbo/BLUEPRINT.md    # Best example of a foundation blueprint
-blueprints/discovery/product-discovery/BLUEPRINT.md  # Best example of a discovery blueprint
-```
-
-## Step 2: Gather Information
-
-Ask the user:
-
-1. **"What pattern are you extracting?"** — What does it do? (e.g., "shared database layer with Drizzle", "Stripe billing integration", "email service with Resend")
-
-2. **"Which tier?"** — Discovery (produces docs), Foundation (project skeleton), or Feature (plugs into existing project)? Most new blueprints are Features.
-
-3. **"Is there an existing project to extract from?"** — If yes, get the path. If no, we're building from scratch — which is fine but harder.
-
-4. **"What should it be called?"** — Suggest a name following the convention: `{domain}-{tool}` for features (e.g., `auth-better-auth`, `db-drizzle-postgres`, `billing-stripe`, `email-resend`). Foundation and discovery blueprints use `{purpose}-{tool}` (e.g., `monorepo-turbo`, `product-discovery`).
-
-## Step 3: Extract or Build
-
-### If extracting from an existing project:
-
-Read the relevant code in the source project. Understand:
-- What files are involved
-- How they connect to each other
-- What's project-specific vs what's the reusable pattern
-- What dependencies are needed
-- What environment variables are required
-- How it integrates with the monorepo (workspace deps, turbo tasks, root scripts)
-
-Then create the blueprint:
-
-1. Create the directory: `blueprints/{tier}/{name}/`
-2. Create `files/` with the extracted code — generalize project-specific values:
-   - Replace npm scopes with `{{SCOPE}}`
-   - Replace app names with `{{APP_NAME}}`
-   - Replace project-specific emails, URLs, etc. with `{{PLACEHOLDER}}` and `// CONFIGURE:` comments
-   - Remove any business logic that's not part of the pattern
-3. Create `BLUEPRINT.md` following the structure below
-
-### If building from scratch:
-
-1. Create the directory: `blueprints/{tier}/{name}/`
-2. Build the code files in `files/`, following the conventions in ENGINEERING.md
-3. Create `BLUEPRINT.md` following the structure below
-
-## Step 4: Write the BLUEPRINT.md
-
-This is the most important file. It's what makes AI-assisted scaffolding intelligent rather than mechanical. Follow this structure:
-
-### Required sections (all tiers):
-
-```markdown
-# [Name] Blueprint — [Short Description]
-
-## Tier
-[Discovery | Foundation | Feature]
-
-## Status
-[Complete | In Progress | Planned]
-
-## Problem
-[What problem does this blueprint solve? Be specific about the pain point.]
-```
-
-### Additional sections for Feature blueprints:
-
-```markdown
-## Blueprint Dependencies
-
-[Does this blueprint require or recommend other blueprints be installed first?
-List them in a table with columns: Blueprint, Type (required/recommended), Why.
-If required, include a subsection explaining fallback behavior if the dependency is absent.
-If no dependencies, write "None."]
-
-## Single-Repo Adaptation
-
-[How does file placement, imports, and scripts differ for standalone (non-monorepo) apps?
-Include a path mapping table (monorepo vs single-repo) and a single-repo scripts example.
-Document what core patterns stay the same regardless of project type.]
-
-## Architecture
-
-### Core Pattern
-[How does this work at a high level?]
-
-### Key Decisions
-[For each major decision, document WHAT you chose and WHY. This is what lets the AI coding tool adapt intelligently.]
-
-- **[Decision 1]** (recommended/required) — [Explanation of what and why. Include alternatives if relevant.]
-- **[Decision 2]** (optional) — [Explanation]
-
-## Hard Requirements vs Recommended Defaults
-
-**Hard requirements:**
-- [Things that can't change]
-
-**Recommended defaults — ask during scaffolding:**
-
-| Choice | Recommended | Alternatives |
-|---|---|---|
-| [Choice 1] | [Default] | [Options] |
-
-## Dependencies
-
-### npm packages
-
-**Server:**
-| Package | Version | Purpose |
-|---|---|---|
-| [pkg] | [version] | [why] |
-
-**Client:**
-| Package | Version | Purpose |
-|---|---|---|
-
-### Environment Variables
-
-| Variable | Where | Description |
-|---|---|---|
-| [VAR] | [Server/Client] | [What it's for] |
-
-## Monorepo Wiring
-
-[How does this integrate across workspaces? Package exports, workspace deps, turbo tasks, root scripts. This section is critical — it's the hardest part to figure out from scratch.]
-
-## File Manifest
-
-| File | Purpose | Target Location |
-|---|---|---|
-| [file path in files/] | [what it does] | [where it goes in target project] |
-
-## Integration Steps
-
-[Ordered phases for scaffolding. Group related steps.]
-
-### Phase 1: [Name]
-1. [Step]
-2. [Step]
-
-### Phase 2: [Name]
-...
-
-## Maintenance Hooks
-
-[What needs to happen after changes to keep this working?]
-
-### Condensed Rules for project rules file
-
-```markdown
-### [name] maintenance
-- [rule 1]
-- [rule 2]
-```
-
-## References
-
-- [Links to docs, repos, etc.]
-```
-
-### Additional sections for Discovery blueprints:
-
-```markdown
-## Output
-[What documents are generated and where]
-
-## Process
-[The conversational flow — phases, frameworks, quality gates]
-```
-
-### Additional sections for Foundation blueprints:
-
-```markdown
-## Output
-[What project structure is generated — show the directory tree]
-
-## Architecture
-[Key structural decisions: why this tool, why this config, why this convention]
-
-## Expects from Discovery
-[What info it reads from the discovery context, if anything]
-```
-
-### Quality checklist for BLUEPRINT.md:
-
-Before considering the BLUEPRINT.md done, verify:
-
-- [ ] Every architectural decision explains WHY, not just WHAT
-- [ ] Configurable vs opinionated choices are clearly separated
-- [ ] Blueprint Dependencies section is present (even if "None")
-- [ ] Single-Repo Adaptation section documents path mapping and script differences
-- [ ] File manifest covers every file in files/ with both monorepo and single-repo target locations
-- [ ] Integration steps are ordered and phased, with conditional monorepo/single-repo phases
-- [ ] Dependencies list specific versions
-- [ ] Environment variables are documented with descriptions
-- [ ] Monorepo wiring is documented (this is always the hardest part)
-- [ ] Maintenance hooks define trigger-action pairs
-- [ ] Code files use `{{SCOPE}}`, `{{APP_NAME}}`, and `// CONFIGURE:` markers
-- [ ] References link to official docs
-
-## Step 5: Create the Scaffold Skill
-
-Create the skill as `.claude/skills/scaffold-{name}/SKILL.md`. Follow the pattern from existing skills (read `.claude/skills/scaffold-auth/SKILL.md` as the model). Add YAML frontmatter with `name` and `description` fields.
-
-Every scaffold skill must:
-
-1. **Read the blueprint** — BLUEPRINT.md and all files
-2. **Read project context** — `.project-context.md` for existing state
-3. **Explore the target project** — understand current structure
-4. **Ask clarifying questions** — based on the blueprint's configurable options
-5. **Adapt and scaffold** — replace placeholders, adapt to project structure
-6. **Update project context** — append to `.project-context.md`
-7. **Create maintenance skill** — as the final step, create a project-level maintenance skill at `<project>/.claude/skills/{name}-maintenance/SKILL.md` with `user-invocable: false` containing the blueprint's maintenance hooks
-8. **Summarize** — packages to install, env vars to set, manual steps remaining
-
-The skill should reference the BLUEPRINT.md as the source of truth for methodology and not duplicate its content.
-
-## Step 6: Update the Repo
-
-After the blueprint and skill are created:
-
-1. **Update README.md** — Add the new blueprint to the appropriate table (Complete or Planned) in the "Available blueprints" section. Add a scaffold command entry to the "Available commands" table.
-
-2. **Update CHANGELOG.md** — Add an entry under [Unreleased] → Added describing the new blueprint.
-
-3. **Update the directory structure** in README.md if it's shown there.
-
-4. **Check for a planned blueprint placeholder** — If `blueprints/features/{name}/BLUEPRINT.md` already existed as a planned placeholder, replace it entirely with the full BLUEPRINT.md. Don't try to preserve the placeholder content.
-
-5. **Ensure the new scaffold skill exists at `.claude/skills/scaffold-{name}/SKILL.md`.**
-
-## Step 7: Verify
-
-Before considering the blueprint done:
-
-1. Read back the BLUEPRINT.md and verify it meets the quality checklist from Step 4
-2. Read the scaffold skill and verify it follows the pattern from Step 5
-3. Verify all files in files/ use proper placeholders (no hardcoded scopes or app names)
-4. Verify README.md and CHANGELOG.md are updated
-5. Show the user a summary of everything that was created
-
-## Tips for Good Blueprints
-
-- **Extract from real projects** — Blueprints that come from battle-tested code are always better than theoretical ones.
-- **Document the WHY** — The code is the easy part. The decisions and reasoning are what make AI-assisted scaffolding intelligent.
-- **Keep it focused** — One blueprint, one problem. If you're tempted to add "and also X", that's probably a separate blueprint.
-- **Include the monorepo wiring** — Package exports, workspace dependencies, turbo tasks, root scripts. This is always the part people get wrong, and it's where the blueprint adds the most value.
-- **Think about maintenance** — What breaks silently if you forget to run something? Those are your maintenance hooks.
-- **Use existing blueprints as your quality bar** — Read auth-better-auth before writing yours. Match that level of detail.