@withmata/blueprints 0.3.2 → 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
 
@@ -138,7 +179,7 @@ Based on the project structure, project context, and user answers, adapt the blu
   - 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`
+- Merge auth env vars into `apis/server/src/env.ts` (if env-t3 is installed, this uses `@t3-oss/env-core` with Zod schemas — add vars to the `server` schema object)
 
 **If single-repo:**
 - Copy/adapt `files/server/auth.ts` -> `src/lib/auth/index.ts`
@@ -146,7 +187,7 @@ Based on the project structure, project context, and user answers, adapt the blu
   - 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)
+- Merge auth env vars into existing env files. If env-t3 is installed (check for `src/env/server.ts`), add server vars to `src/env/server.ts` and client vars to `src/env/client.ts`. Otherwise merge into `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
@@ -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: