@withmata/blueprints 0.2.0 → 0.3.2

package/{.opencode/commands/audit.md → .claude/skills/audit/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Run a project health check against available blueprints
+name: audit
+description: Run a project health check against available blueprints (read-only analysis)
+allowed-tools: Read, Glob, Grep, Bash(git *), Bash(ls *)
 ---
 
 # Project Audit
@@ -11,18 +13,18 @@ Run a health check against available blueprints. Analyze this project's current
 Load all available blueprint specs to understand what is possible:
 
 ```
-~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
-~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
-~/Documents/WithMata/my-blueprints/blueprints/features/auth-better-auth/BLUEPRINT.md
+~/.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:
 
 ```
-~/Documents/WithMata/my-blueprints/blueprints/features/*/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/*/BLUEPRINT.md
 ```
 
-Only consider a blueprint "available" if its BLUEPRINT.md has `Status: Complete`. If not found at these paths, ask the user for the path to their blueprints repo.
+Only consider a blueprint "available" if its BLUEPRINT.md has `Status: Complete`. If not found, run `npx @withmata/blueprints` to install.
 
 ## Step 2: Read Project Context
 

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

@@ -0,0 +1,63 @@
+---
+name: blueprint-catalog
+description: >
+  Background knowledge about available project blueprints for scaffolding.
+  Invoke when user discusses: databases, authentication, project setup,
+  monorepo, product ideas, scaffolding, environment variables, UI components,
+  design systems, Tailwind, or asks "what should I do next?"
+user-invocable: false
+---
+
+## Available Blueprints
+
+| Blueprint | Tier | What it does | Dependencies | Skill |
+|-----------|------|-------------|--------------|-------|
+| Product Discovery | Discovery | Structured session producing product thesis, user archetypes, and competitive analysis. No code. | None | `/discover` |
+| 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
+
+!`cat .project-context.md 2>/dev/null || echo "No .project-context.md found — no blueprints have been installed in this project yet."`
+
+## When to Recommend
+
+Suggest a blueprint when you observe these signals. Be helpful, not pushy — mention it once, then follow the user's lead.
+
+**`/discover`** — User describes a new product idea, asks "what should I build", is unsure about scope or target users, is non-technical or building their first product, or project has no product documentation.
+
+**`/scaffold-foundation`** — User wants to set up a monorepo, mentions Turborepo or project structure, or project has no `turbo.json` / `pnpm-workspace.yaml`. Best after discovery. Skip for single-repo apps.
+
+**`/scaffold-db`** — User mentions database, Drizzle, PostgreSQL, schemas, migrations, or needs a structured db layer. Or is writing raw SQL or using an ORM without organized schemas.
+
+**`/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
+
+Discovery → Foundation → Features is the recommended flow, but blueprints can be applied at any stage.
+
+- **New project, no code:** Start with `/discover` (especially for non-technical users) or `/scaffold-foundation` (for monorepos)
+- **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). `/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
+
+- Check `.project-context.md` first — do not recommend blueprints already recorded there.
+- Read the full BLUEPRINT.md before scaffolding. Follow ENGINEERING.md for coding conventions.
+- Only recommend blueprints listed above. Other blueprints are in development and not yet available.
+- Blueprints location: `~/.withmata/blueprints/`

package/.claude/{commands/discover.md → skills/discover/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: discover
+description: Run a structured product discovery session producing product documentation (no code)
+---
+
 # Run Product Discovery
 
 Run a rigorous product discovery session. This produces product documentation — no code is generated. The session is a structured 60-minute deep dive that transforms a raw idea into a defensible product strategy.
@@ -7,11 +12,11 @@ Run a rigorous product discovery session. This produces product documentation
 Read the full discovery blueprint and all templates:
 
 ```
-~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
-~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/templates/*
+~/.withmata/blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/discovery/product-discovery/templates/*
 ```
 
-If not found at that path, ask the user for the path to their blueprints repo.
+If not found, run `npx @withmata/blueprints` to install.
 
 The BLUEPRINT.md contains the full methodology: phased session structure, frameworks, operating principles, research strategy, challenge patterns, and quality checkpoints. Follow it precisely.
 

package/{.cursor/commands/new-blueprint.md → .claude/skills/new-blueprint/SKILL.md}

@@ -1,3 +1,8 @@
+---
+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.
@@ -214,11 +219,11 @@ Before considering the BLUEPRINT.md done, verify:
 - [ ] Code files use `{{SCOPE}}`, `{{APP_NAME}}`, and `// CONFIGURE:` markers
 - [ ] References link to official docs
 
-## Step 5: Create the Scaffold Command
+## Step 5: Create the Scaffold Skill
 
-Create the command in all three tool directories: `.claude/commands/scaffold-{name}.md`, `.opencode/commands/scaffold-{name}.md`, and `.cursor/commands/scaffold-{name}.md`. The OpenCode version should include YAML frontmatter with a `description` field. The Claude Code and Cursor versions use plain markdown (no frontmatter). The command body is the same across all three.
+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.
 
-Follow the pattern from existing commands (read `.claude/commands/scaffold-auth.md` as the model). Every scaffold command must:
+Every scaffold skill must:
 
 1. **Read the blueprint** — BLUEPRINT.md and all files
 2. **Read project context** — `.project-context.md` for existing state
@@ -226,14 +231,14 @@ Follow the pattern from existing commands (read `.claude/commands/scaffold-auth.
 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. **Inject maintenance rules** — detect and append to the target project's rules file(s): CLAUDE.md, AGENTS.md, or both (see the multi-tool injection pattern in existing scaffold commands)
+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 command should reference the BLUEPRINT.md as the source of truth for methodology and not duplicate its content.
+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 command are created:
+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.
 
@@ -243,14 +248,14 @@ After the blueprint and command are created:
 
 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 all three directories have the new scaffold command:** `.claude/commands/`, `.opencode/commands/`, and `.cursor/commands/`.
+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 command and verify it follows the pattern from Step 5
+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

package/{.cursor/commands/new-project.md → .claude/skills/new-project/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: new-project
+description: Take a product from idea to running code using the full blueprint lifecycle
+---
+
 # New Project
 
 Take a product from idea to running code. This command walks through the full lifecycle — defining the product, setting up the codebase to support it, and wiring in the capabilities it needs. You're a product partner with deep engineering expertise: the product strategy drives every technical decision.
@@ -7,19 +12,19 @@ Take a product from idea to running code. This command walks through the full li
 Load all available blueprints so you understand what's possible:
 
 ```
-~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
-~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/templates/*
-~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
-~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/files/**/*
+~/.withmata/blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/discovery/product-discovery/templates/*
+~/.withmata/blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/foundation/monorepo-turbo/files/**/*
 ```
 
 Also scan for available feature blueprints:
 
 ```
-~/Documents/WithMata/my-blueprints/blueprints/features/*/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/*/BLUEPRINT.md
 ```
 
-Only consider a feature blueprint "available" if its BLUEPRINT.md has `Status: Complete` (not a placeholder). If not found at the paths above, ask the user for the path to their blueprints repo.
+Only consider a feature blueprint "available" if its BLUEPRINT.md has `Status: Complete` (not a placeholder). If not found, run `npx @withmata/blueprints` to install.
 
 ## Step 2: Assess Current State
 

package/.claude/{commands/scaffold-auth.md → skills/scaffold-auth/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: scaffold-auth
+description: Scaffold Better Auth + Drizzle authentication into the current project
+---
+
 # Scaffold Auth Blueprint
 
 Scaffold the `auth-better-auth` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack.
@@ -7,11 +12,11 @@ Scaffold the `auth-better-auth` blueprint into the current project. Read the ful
 Read the full BLUEPRINT.md and all code files from the auth blueprint:
 
 ```
-blueprints/features/auth-better-auth/BLUEPRINT.md
-blueprints/features/auth-better-auth/files/**/*
+~/.withmata/blueprints/blueprints/features/auth-better-auth/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/auth-better-auth/files/**/*
 ```
 
-If these files are not in the current project, look for them at `~/Documents/WithMata/my-blueprints/blueprints/features/auth-better-auth/`. If still not found, ask the user for the path to their blueprints repo.
+If not found at these paths, run `npx @withmata/blueprints` to install.
 
 ## Step 1.5: Read Project Context
 
@@ -115,13 +120,13 @@ Based on the project structure, project context, and user answers, adapt the blu
 ### 4a. Database Layer
 
 **If monorepo:**
-- Copy/adapt `files/db/drizzle.config.ts` → `packages/db/drizzle/auth/drizzle.config.ts`
+- Copy/adapt `files/db/drizzle.config.ts` -> `packages/db/drizzle/auth/drizzle.config.ts`
 - Copy `files/db/auth-schema.ts` as a reference (the actual schema will be auto-generated)
 - Add the `"./auth"` export to `packages/db/package.json`
 - Add `auth:generate` and `auth:migrate` scripts to `packages/db/package.json`
 
 **If single-repo:**
-- Copy/adapt `files/db/drizzle.config.ts` → `drizzle/auth/drizzle.config.ts` (at project root)
+- Copy/adapt `files/db/drizzle.config.ts` -> `drizzle/auth/drizzle.config.ts` (at project root)
 - Adjust schema paths to `"./src/db/auth/schema.ts"` (relative to root)
 - Create `src/db/auth/` directory for auth schema
 - No separate package.json export needed — use direct imports
@@ -129,17 +134,17 @@ Based on the project structure, project context, and user answers, adapt the blu
 ### 4b. Server Layer
 
 **If monorepo:**
-- Copy/adapt `files/server/auth.ts` → `apis/server/src/auth/index.ts`
+- Copy/adapt `files/server/auth.ts` -> `apis/server/src/auth/index.ts`
   - Replace `{{APP_NAME}}`, `{{EMAIL_FROM}}`, `{{SCOPE}}`
-- Copy/adapt `files/server/auth-db.ts` → `apis/server/src/db/auth.ts`
-- Copy/adapt `files/server/middleware.ts` → `apis/server/src/middleware/auth.ts`
+- Copy/adapt `files/server/auth-db.ts` -> `apis/server/src/db/auth.ts`
+- Copy/adapt `files/server/middleware.ts` -> `apis/server/src/middleware/auth.ts`
 - Merge auth env vars into `apis/server/src/env.ts`
 
 **If single-repo:**
-- Copy/adapt `files/server/auth.ts` → `src/lib/auth/index.ts`
+- Copy/adapt `files/server/auth.ts` -> `src/lib/auth/index.ts`
   - Replace `{{APP_NAME}}`, `{{EMAIL_FROM}}`
   - Adjust DB import to use direct path: `import { db } from "@/db/auth/client"` or `#db/auth/client`
-- Copy/adapt `files/server/auth-db.ts` → `src/lib/db/auth.ts`
+- 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)
 
@@ -221,21 +226,19 @@ If `.project-context.md` does not exist, create it with the standard header and
 
 Also append any significant architectural decisions to the `## Architecture Decisions` section.
 
-### Inject Maintenance Rules
+### Create Maintenance Skill
 
-Append the condensed maintenance rules to the target project's rules file(s):
+Create a project-level maintenance skill for the auth blueprint:
 
-1. If `CLAUDE.md` exists in the target project → append rules there
-2. If `AGENTS.md` exists in the target project → append rules there
-3. If both exist → append to both (keep them in sync)
-4. If neither exists → ask the user which AI coding tool(s) they use:
-   - Claude Code → create CLAUDE.md with a `## Maintenance Rules` section
-   - OpenCode or Cursor → create AGENTS.md with a `## Maintenance Rules` section (both tools read AGENTS.md)
-   - Multiple tools → create all applicable files
+**File:** `<project>/.claude/skills/auth-maintenance/SKILL.md`
 
-The maintenance rules content is identical regardless of which file it goes into:
+```yaml
+---
+name: auth-maintenance
+description: Maintenance rules for Better Auth. Invoke when modifying auth config, providers, session settings, or auth schema.
+user-invocable: false
+---
 
-```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
@@ -245,8 +248,6 @@ The maintenance rules content is identical regardless of which file it goes into
 - Never edit the auto-generated auth schema directly — modify the Better Auth config and regenerate
 ```
 
-If the `## Maintenance Rules` heading already exists (from another blueprint), only add the `### auth-better-auth maintenance` subsection — do not duplicate the heading.
-
 ## Step 6: Output Summary
 
 After scaffolding, provide the user with a clear summary:

package/{.cursor/commands/scaffold-db.md → .claude/skills/scaffold-db/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: scaffold-db
+description: Scaffold Drizzle ORM + PostgreSQL database package into the current project
+---
+
 # Scaffold DB Blueprint
 
 Scaffold the `db-drizzle-postgres` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack.
@@ -7,11 +12,11 @@ Scaffold the `db-drizzle-postgres` blueprint into the current project. Read the
 Read the full BLUEPRINT.md and all template files from the db blueprint:
 
 ```
-blueprints/features/db-drizzle-postgres/BLUEPRINT.md
-blueprints/features/db-drizzle-postgres/files/**/*
+~/.withmata/blueprints/blueprints/features/db-drizzle-postgres/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/db-drizzle-postgres/files/**/*
 ```
 
-If these files are not in the current project, look for them at `~/Documents/WithMata/my-blueprints/blueprints/features/db-drizzle-postgres/`. If still not found, ask the user for the path to their blueprints repo.
+If not found at these paths, run `npx @withmata/blueprints` to install.
 
 ## Step 1.5: Read Project Context
 
@@ -188,21 +193,19 @@ scripts_added:
 
 If `.project-context.md` does not exist, create it with the standard header and the Installed Blueprints section. Log a note: "No discovery or foundation context found. Consider running `/discover` and `/scaffold-foundation` for a complete project context."
 
-### Inject Maintenance Rules
+### Create Maintenance Skill
 
-Append the condensed maintenance rules to the target project's rules file(s):
+Create a project-level maintenance skill for the database blueprint:
 
-1. If `CLAUDE.md` exists in the target project -> append rules there
-2. If `AGENTS.md` exists in the target project -> append rules there
-3. If both exist -> append to both (keep them in sync)
-4. If neither exists -> ask the user which AI coding tool(s) they use:
-   - Claude Code -> create CLAUDE.md with a `## Maintenance Rules` section
-   - OpenCode or Cursor -> create AGENTS.md with a `## Maintenance Rules` section (both tools read AGENTS.md)
-   - Multiple tools -> create all applicable files
+**File:** `<project>/.claude/skills/db-maintenance/SKILL.md`
 
-The maintenance rules content is identical regardless of which file it goes into:
+```yaml
+---
+name: db-maintenance
+description: Maintenance rules for Drizzle + PostgreSQL database. Invoke when modifying schemas, adding entities, or running migrations.
+user-invocable: false
+---
 
-```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`
@@ -211,8 +214,6 @@ The maintenance rules content is identical regardless of which file it goes into
 - Never use glob patterns in drizzle.config.ts schema — always list files explicitly, excluding index.ts
 ```
 
-If the `## Maintenance Rules` heading already exists (from another blueprint), only add the `### db-drizzle-postgres maintenance` subsection — do not duplicate the heading.
-
 ## Step 6: Output Summary
 
 After scaffolding, provide the user with a clear summary:

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.