@withmata/blueprints 0.3.1 → 0.3.3

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

@@ -3,7 +3,8 @@ name: blueprint-catalog
 description: >
   Background knowledge about available project blueprints for scaffolding.
   Invoke when user discusses: databases, authentication, project setup,
-  monorepo, product ideas, scaffolding, or asks "what should I do next?"
+  monorepo, product ideas, scaffolding, environment variables, UI components,
+  design systems, Tailwind, or asks "what should I do next?"
 user-invocable: false
 ---
 
@@ -15,6 +16,9 @@ user-invocable: false
 | Monorepo Foundation | Foundation | Turborepo + pnpm monorepo with Next.js, Biome, TypeScript strict, Tailwind v4. | None | `/scaffold-foundation` |
 | Database | Feature | Drizzle ORM + PostgreSQL: schema groups, per-group migrations, seed scripts. | None | `/scaffold-db` |
 | Authentication | Feature | Better Auth + Drizzle + PostgreSQL: social login, email/password, organizations, role-based permissions. | Database | `/scaffold-auth` |
+| Environment Variables | Feature | T3 Env + Zod: validated, type-safe env vars for Next.js (client/server split) and backend apps. | None | `/scaffold-env` |
+| Tailwind v4 Design System | Feature | Full design system: shadcn tokens, animations, typography, sidebar/chart tokens, dark mode. | Foundation (recommended) | `/scaffold-tailwind` |
+| UI Shared Components | Feature | Shared UI package: shadcn/ui, path-based exports, cn utility, component generation. | Tailwind v4 | `/scaffold-ui` |
 
 ## Project Context
 
@@ -32,6 +36,12 @@ Suggest a blueprint when you observe these signals. Be helpful, not pushy — me
 
 **`/scaffold-auth`** — User mentions login, signup, users, accounts, teams, organizations, permissions, or authentication. Or is implementing auth from scratch. Recommend `/scaffold-db` first if not already installed.
 
+**`/scaffold-env`** — User mentions environment variables, `.env` files, env validation, type-safe config, T3 Env, or is accessing `process.env` directly. Or a Next.js app has no env validation. Standalone — works with any project.
+
+**`/scaffold-tailwind`** — User mentions design system, shadcn setup, animations, typography plugin, dark mode theming, or the Tailwind config is missing shadcn integration. Best after foundation.
+
+**`/scaffold-ui`** — User mentions shared components, UI package, component library, shadcn in monorepo, or needs to share components across apps. Recommend `/scaffold-tailwind` first if not installed.
+
 **`/audit`** — User asks "what should I do next?", wants to understand their project's state, or has hand-rolled infrastructure that a blueprint could improve.
 
 ## Lifecycle & Dependencies
@@ -42,7 +52,8 @@ Discovery → Foundation → Features is the recommended flow, but blueprints ca
 - **Single-repo project:** Skip foundation — go directly to feature blueprints (`/scaffold-db`, `/scaffold-auth`)
 - **Has monorepo, missing features:** Suggest specific feature blueprints
 - **Existing project:** Feature blueprints adapt to existing structures — no foundation required
-- **Dependencies:** `/scaffold-auth` works best after `/scaffold-db` (auth builds on db patterns). Install dependencies first.
+- **Dependencies:** `/scaffold-auth` works best after `/scaffold-db` (auth builds on db patterns). `/scaffold-ui` requires `/scaffold-tailwind`. Install dependencies first.
+- **Environment setup:** `/scaffold-env` is recommended for all projects — it's standalone and works with any combination of other blueprints
 
 ## Important
 

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

@@ -138,7 +138,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 +146,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

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

@@ -0,0 +1,222 @@
+---
+name: scaffold-env
+description: Scaffold T3 Env validated environment variables into the current project
+---
+
+# Scaffold Env Blueprint
+
+Scaffold the `env-t3` 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 env blueprint:
+
+```
+~/.withmata/blueprints/blueprints/features/env-t3/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/env-t3/files/**/*
+```
+
+If not found at these paths, run `npx @withmata/blueprints` to install.
+
+## 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 (from Foundation)
+  - What other blueprints are already installed (from Installed Blueprints)
+  - Use this information to pre-fill env variables and adapt file paths
+
+- **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 has `auth-better-auth` installed -> pre-populate auth env vars
+- Context has `env-t3` in Installed Blueprints -> warn about existing install
+
+## 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?"
+
+### 2b. Discover Apps
+
+Find all applications that need env setup:
+
+**Next.js apps** — look for:
+- `next.config.ts` or `next.config.js` or `next.config.mjs`
+- Typically in `apps/web/`, `apps/*/`, or project root (single-repo)
+
+**Backend apps** — look for:
+- `hono` or `express` or `@hono/node-server` in `package.json` dependencies
+- Typically in `apis/*/`, `apps/server/`, or project root (single-repo)
+
+### 2c. Check Existing Env Setup
+
+For each app found:
+- Does `env.ts` already exist? (Foundation blueprint creates a basic one)
+- Does `src/env/` directory exist? (Already has the split pattern)
+- Does `.env.example` exist?
+- Does `next.config.ts` already import env files?
+- Are `@t3-oss/env-nextjs` or `@t3-oss/env-core` already installed?
+
+### 2d. Check Installed Blueprints
+
+If other blueprints are installed, note their env vars so we can pre-populate:
+- **auth-better-auth**: `BETTER_AUTH_URL`, `BETTER_AUTH_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `AUTH_DATABASE_URL`
+- **db-drizzle-postgres**: `{{GROUP_UPPER}}_DATABASE_URL` (in db package, not app)
+
+## Step 3: Ask Clarifying Questions
+
+Before scaffolding, ask the user:
+
+1. **Which apps to configure** — "I found these apps: [list]. Set up env validation for all of them?" (Default: yes, all)
+
+2. **Existing env.ts** — If an `env.ts` already exists: "I found an existing `env.ts`. I'll migrate it to the client/server split pattern and merge existing variables. Sound good?"
+
+3. **Pre-populate from installed blueprints** — If other blueprints are installed: "I see auth-better-auth is installed. Should I add its env vars to the server env schema?"
+
+Skip questions where the answer is obvious from the project structure.
+
+## Step 4: Adapt and Scaffold
+
+### 4a. Next.js Apps
+
+For each Next.js app:
+
+**If `env.ts` exists (e.g., from foundation blueprint):**
+1. Read the existing `env.ts` to extract current variables
+2. Split variables: `NEXT_PUBLIC_*` -> `client.ts`, everything else -> `server.ts`
+3. Create `src/env/client.ts` with the client variables
+4. Create `src/env/server.ts` with the server variables
+5. Update `next.config.ts`:
+   - Replace `import "./env"` with `import "./src/env/server"` and `import "./src/env/client"`
+   - If no existing env import, add both imports at the top (before any other code)
+6. Delete the old `env.ts`
+
+**If no existing env setup:**
+1. Create `src/env/client.ts` from template — replace `{{APP_NAME}}`
+2. Create `src/env/server.ts` from template — replace `{{APP_NAME}}`
+3. Update `next.config.ts` — add imports at the top
+
+**For all Next.js apps:**
+4. Create `.env.example` from template — replace `{{APP_NAME}}`
+5. Create `.env.local` (empty file)
+6. If other blueprints are installed, merge their env vars into the appropriate schema
+
+### 4b. Backend Apps
+
+For each backend app:
+
+1. Create `src/env.ts` from template — replace `{{APP_NAME}}`
+2. Update the app's entry point to import env:
+   ```typescript
+   import { env } from "./env.js";
+   ```
+3. Create `.env.example` from template — replace `{{APP_NAME}}`
+4. Create `.env.local` (empty file)
+5. If the app has hardcoded `process.env.PORT` or similar, refactor to use `env.PORT`
+
+### 4c. Dependency Installation
+
+For each Next.js app:
+- Ensure `@t3-oss/env-nextjs` and `zod` are in `dependencies`
+
+For each backend app:
+- Ensure `@t3-oss/env-core`, `zod`, and `dotenv` are in `dependencies`
+
+## Step 5: Update Project Context
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### env-t3
+blueprint: env-t3
+choices:
+  nextjs_env_location: src/env/
+  backend_env_location: src/env.ts
+apps_configured:
+  - name: <app name>
+    type: <nextjs|backend>
+    files:
+      - <list of files created>
+packages_added:
+  - <list of packages added>
+```
+
+If `.project-context.md` does not exist, create it with the standard header and the Installed Blueprints section.
+
+### Create Maintenance Skill
+
+Create a project-level maintenance skill for the env blueprint:
+
+**File:** `<project>/.claude/skills/env-maintenance/SKILL.md`
+
+```yaml
+---
+name: env-maintenance
+description: Maintenance rules for T3 Env validated environment variables. Invoke when adding, removing, or modifying environment variables.
+user-invocable: false
+---
+
+### 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
+```
+
+## Step 6: Output Summary
+
+After scaffolding, provide the user with a clear summary:
+
+### Packages to Install
+
+**Next.js apps:**
+```bash
+pnpm add @t3-oss/env-nextjs zod
+```
+
+**Backend apps:**
+```bash
+pnpm add @t3-oss/env-core zod dotenv
+```
+
+### Files Created
+
+List every file that was created or modified, with a one-line description.
+
+### How to Use
+
+```typescript
+// In server components, API routes, server actions:
+import { serverEnv } from "~/env/server";
+
+// In client components:
+import { clientEnv } from "~/env/client";
+
+// In backend apps:
+import { env } from "./env.js";
+```
+
+### Next Steps
+
+- Fill in `.env.local` with your actual values (use `.env.example` as reference)
+- As you add features, add their env vars to the schema files and `.env.example`
+- Run `pnpm dev` to verify env validation passes
+
+## Important Notes
+
+- When adapting code, preserve the `// CONFIGURE:` comments so the user can find customization points later.
+- Never overwrite existing files without asking. If env files exist, merge new variables into them.
+- If `next.config.ts` already imports env files, don't add duplicate imports.
+- The env schema files are the source of truth for what variables an app needs — keep them accurate.

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

@@ -7,18 +7,34 @@ description: Set up a Turborepo + pnpm monorepo skeleton (skip for single-repo a
 
 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
+This skill operates in two modes:
 
-Read the full foundation blueprint and all template files:
+- **Install mode** (default) — fresh scaffold of the full monorepo skeleton
+- **Upgrade mode** — detects an existing foundation install and offers to apply updates (new features added to blueprints since the original install)
+
+## Step 1: Read the Blueprints
+
+Read the foundation blueprint and all template files:
 
 ```
 ~/.withmata/blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
 ~/.withmata/blueprints/blueprints/foundation/monorepo-turbo/files/**/*
 ```
 
+Also read the feature blueprints that foundation can optionally include:
+
+```
+~/.withmata/blueprints/blueprints/features/env-t3/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/env-t3/files/**/*
+~/.withmata/blueprints/blueprints/features/tailwind-v4/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/tailwind-v4/files/**/*
+~/.withmata/blueprints/blueprints/features/ui-shared-components/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/ui-shared-components/files/**/*
+```
+
 If not found, run `npx @withmata/blueprints` to install.
 
-The BLUEPRINT.md contains the full architecture documentation, naming conventions, folder conventions, and file manifest. Follow it precisely.
+The BLUEPRINT.md files contain the full architecture documentation, naming conventions, folder conventions, and file manifests. Follow them precisely.
 
 ## Step 2: Read Project Context
 
@@ -26,12 +42,48 @@ 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 it has a Foundation section already**: **switch to upgrade mode** (see Step 2b below).
+
+- **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
+
+When foundation is already installed, compare what's currently in the project against what the blueprints now offer. Check for:
+
+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`).
+
+2. **Missing features** — Check `.project-context.md` Installed Blueprints for:
+   - `env-t3` — Is it installed? If not, apply it automatically (env validation is not optional).
+   - `tailwind-v4` + `ui-shared-components` — Are they installed? If not, flag as available (frontend UI is optional).
+
+3. **Present findings to the user:**
+
+   ```
+   Foundation was installed on <date>. Here's what's available:
 
-- **If no context file exists**: that is fine. Ask the user directly for the product name and npm scope.
+   Updates to existing files:
+     ☐ turbo.json — new task caching strategy
+     ☐ apps/web/next.config.ts — updated config pattern
+
+   Auto-applying:
+     ✓ Validated environment variables (env-t3) — type-safe env with client/server split
+
+   New features (not yet installed):
+     ☐ Frontend UI setup (tailwind-v4 + ui-shared-components) — full design system and shared component library
+
+   Which would you like to apply?
+   ```
+
+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.
+
+After upgrade mode completes, skip to Step 7 (Summarize).
 
 ## Step 3: Understand Current State
 
+*(Install mode only — skipped in upgrade mode)*
+
 Explore the target project directory:
 
 - Is it empty? Fresh start — scaffold everything.
@@ -40,12 +92,20 @@ Explore the target project directory:
 
 ## Step 4: Ask Configuration Questions
 
-Only three questions — skip any already answered by project context:
+*(Install mode only — skipped in upgrade mode)*
+
+Core 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`.
 
+Optional feature question — ask after the core questions:
+
+4. **Frontend UI** — "Will this project have frontend work? If yes, I'll set up the full Tailwind design system and a shared UI component library (`packages/ui/`) with shadcn/ui. (Y/n)" Default: yes. If yes, applies both tailwind-v4 and ui-shared-components together.
+
+**Note:** Validated environment variables (env-t3) are always set up — not optional. Every app gets type-safe env validation.
+
 ## Step 5: Scaffold
 
 Create the monorepo skeleton by adapting all files from the blueprint. Replace placeholders:
@@ -66,7 +126,7 @@ From `files/root/`, create at project root:
 
 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
+- `config/tailwind-config/` — shared-styles.css, postcss.config.mjs, package.json
 
 ### 5c. Next.js App Shell
 
@@ -93,9 +153,73 @@ After creating all files:
 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 5.5: Optional Features
+
+Apply the optional features the user said yes to in Step 4. Each feature follows its own blueprint's integration steps but within the same session — no need to run separate scaffold commands.
+
+### 5.5a. Environment Variables (always applied)
+
+Follow the `env-t3` blueprint's integration steps:
+
+1. Create `apps/web/src/env/client.ts` and `apps/web/src/env/server.ts` from env-t3 templates
+2. Replace the foundation's `apps/web/env.ts` with the split pattern
+3. Update `apps/web/next.config.ts` — replace `import "./env"` with:
+   ```typescript
+   import "./src/env/server";
+   import "./src/env/client";
+   ```
+4. Create `apps/web/.env.example` from env-t3 template — replace `{{APP_NAME}}`
+5. Create `apps/web/.env.local` (empty)
+6. Ensure `@t3-oss/env-nextjs` and `zod` are in `apps/web/package.json` dependencies
+
+### 5.5b. Frontend UI Setup (if opted in)
+
+When the user opts in to frontend work, apply both tailwind-v4 and ui-shared-components together as a single step.
+
+**Tailwind design system** — follow the `tailwind-v4` blueprint's integration steps:
+
+1. Replace `config/tailwind-config/shared-styles.css` with the full version from the tailwind-v4 blueprint (includes `tw-animate-css`, `shadcn/tailwind.css`, `tailwind-scrollbar-hide`, sidebar tokens, chart tokens)
+2. Merge tailwind-v4 dependencies into `config/tailwind-config/package.json`:
+   - Add `@tailwindcss/typography`, `shadcn`, `tailwind-scrollbar-hide`, `tw-animate-css` to `dependencies`
+
+**Shared UI package** — follow the `ui-shared-components` blueprint's integration steps:
+
+1. Create `packages/ui/` with all files from the ui blueprint:
+   - `package.json` — replace `{{SCOPE}}`
+   - `tsconfig.json` — replace `{{SCOPE}}`
+   - `components.json`
+   - `styles/globals.css` — replace `{{SCOPE}}`
+   - `utils/cn.ts`
+   - `utils/cva.ts`
+2. Create empty directories: `packages/ui/components/ui/`, `packages/ui/icons/`, `packages/ui/icons/logos/`
+3. Update `apps/web/app/globals.css` to import UI styles:
+   ```css
+   @import "tailwindcss";
+   @import "{{SCOPE}}/tailwind-config";
+   @import "{{SCOPE}}/ui/styles";
+   @plugin "@tailwindcss/typography";
+
+   @source "../../packages/ui";
+   ```
+   Compute the `@source` relative path based on the actual directory structure.
+
+### 5.5d. Re-install
+
+If any optional features were applied:
+1. Run `pnpm install` again to wire new workspace dependencies
+2. Verify `pnpm dev` still boots cleanly
+
 ## Step 6: Update Project Context
 
-Append the `## Foundation` section to `.project-context.md`:
+**This step is mandatory.** The `.project-context.md` file is how other blueprints and future runs of `/scaffold-foundation` (upgrade mode) know what's been set up. Without it, every subsequent blueprint runs blind.
+
+If `.project-context.md` does not exist, create it now:
+
+```markdown
+# Project Context
+```
+
+Then append the `## Foundation` section:
 
 ```yaml
 ## Foundation
@@ -103,10 +227,11 @@ monorepo_tool: turborepo
 package_manager: pnpm
 npm_scope: "<scope>"
 node_version: ">=22"
+project_type: monorepo
 workspaces:
   apps: ["web"]
   apis: []
-  packages: []
+  packages: ["ui"]  # if frontend UI was applied, otherwise []
   config: ["typescript-config", "tailwind-config"]
 framework: next.js (app router)
 typescript: strict
@@ -117,11 +242,20 @@ 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.
+Then append `## Installed Blueprints` with entries for every feature that was applied:
+
+```markdown
+## Installed Blueprints
+```
+
+- Always add the `env-t3` project context block (see env-t3 BLUEPRINT.md)
+- If frontend UI was applied: add both the `tailwind-v4` and `ui-shared-components` project context blocks (see their BLUEPRINT.md files)
+
+**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 Skill
+### Create Maintenance Skills
 
-Create a project-level maintenance skill for the monorepo foundation:
+Create the foundation maintenance skill:
 
 **File:** `<project>/.claude/skills/monorepo-maintenance/SKILL.md`
 
@@ -141,19 +275,35 @@ user-invocable: false
 - Keep `turbo.json` tasks with `cache: false` for any task with side effects (migrations, code generation)
 ```
 
+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)
+
 ## Step 7: Summarize
 
 Tell the user:
 
-- Project structure overview (directory tree)
+### Install Mode Summary
+
+- Project structure overview (directory tree — include optional features that were applied)
 - What was configured (scope, Node version, tooling)
+- Which optional features were included
 - 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."
+- If frontend UI was set up: how to add shadcn components (`cd packages/ui && pnpm dlx shadcn@latest add button`)
+- Available feature blueprints to install next: `/scaffold-db`, `/scaffold-auth`
+
+### Upgrade Mode Summary
+
+- What was updated (list files that changed)
+- What new features were added (env, tailwind, UI)
+- Any manual steps remaining
+- Suggest next steps based on what's still not installed
 
 ## 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.
+- In upgrade mode, be conservative — only modify files that the blueprints own. Don't touch user-customized files (check for differences from the template before replacing).
+- If the user has customized colors in `shared-styles.css` or added variables to `env.ts`, ask before replacing. Offer to merge their customizations into the new version.
 - Feature blueprints will add scripts to root `package.json` and tasks to `turbo.json` — the foundation provides the base that they extend.
+- The individual `/scaffold-env`, `/scaffold-tailwind`, and `/scaffold-ui` skills still exist for projects that didn't use foundation or want to add features later. The foundation's optional feature steps follow the same blueprints — no duplication.