@withmata/blueprints 0.7.0 → 3.0.0

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

@@ -76,7 +76,7 @@ Regardless of whether project context exists, explore the actual project to unde
 ### 3f. Environment & Validation
 
 - 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?
+- Are the Zod schema files well-commented as the variable registry? (No `.env.example` — values come from Infisical or the platform.)
 - Is there build-time validation (env imported in `next.config.ts`)?
 
 ### 3g. Code Quality
@@ -172,10 +172,10 @@ For each installed blueprint with updates, show detailed information. Use plain
 │     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
+│     The env schema files now document each variable
+│     (purpose, local/production hints) — the schema is
+│     the registry; values come from Infisical.
+│     File: src/env/server.ts
 │
 │ To apply: /scaffold-env
 └─────────────────────────────────────────────────────
@@ -316,7 +316,7 @@ What was done
 Blueprint upgrades:
   ✓ foundation — consolidated maintenance rules,
     cleaned up legacy patterns
-  ✓ env-t3 — updated server.ts, .env.example
+  ✓ env-t3 — updated server.ts schema (the registry)
   ✓ tailwind-v4 — updated shared-styles.css, added
     tailwind-scrollbar-hide
 

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

@@ -21,6 +21,7 @@ user-invocable: false
 | 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 Tailwind v4 upgrade: shadcn tokens, shadows, easing, animations, sidebar/chart tokens, dark mode. Auto-detects `/design-system` output. | Foundation (recommended) | `/scaffold-tailwind` |
 | UI Shared Components | Feature | 31 base components (Base UI + Phosphor): compound patterns, form system, app shell, data display. Auto-installs Tailwind. | Tailwind v4 (auto-installed) | `/scaffold-ui` |
+| Secrets (Infisical) | Feature | Centralized secret management: /shared domain folders with environment-aware references, placeholder injection, and `infisical run` wiring. | Environment Variables (env-t3) | `/scaffold-infisical` |
 
 ## Project Context
 
@@ -50,6 +51,8 @@ Suggest a blueprint when you observe these signals. Be helpful, not pushy — me
 
 **`/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.
 
+**`/scaffold-infisical`** — User mentions Infisical, secret management, shared secrets across apps, secret references, rotating keys in one place, or has the same secret duplicated across multiple `.env`/Infisical folders. Requires `/scaffold-env` first (reads the T3 schemas).
+
 **`/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
@@ -64,6 +67,7 @@ Discovery → Foundation → Features is the recommended flow, but blueprints ca
 - **Need marketing pages:** Run `/copywrite-landing` for landing pages, `/copywrite` for other pages (pricing, about, features)
 - **Dependencies:** `/scaffold-auth` works best after `/scaffold-db` (auth builds on db patterns). `/scaffold-ui` auto-installs `/scaffold-tailwind`. `/scaffold-tailwind` auto-detects design system tokens.
 - **Environment setup:** `/scaffold-env` is recommended for all projects — it's standalone
+- **Secret management:** after `/scaffold-env`, run `/scaffold-infisical` to move secret delivery into Infisical with a shared single-source-of-truth structure (env-aware references). Best for multi-app/multi-environment projects
 
 ## Important
 

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

@@ -54,7 +54,6 @@ If `env-t3` is found in `.project-context.md` under `## Installed Blueprints`, s
 
    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)
@@ -100,7 +99,6 @@ Find all applications that need 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?
 
@@ -144,9 +142,8 @@ For each Next.js app:
 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
+4. Create `.env.local` (empty file)
+5. If other blueprints are installed, merge their env vars into the appropriate schema
 
 ### 4b. Backend Apps
 
@@ -157,9 +154,8 @@ For each backend app:
    ```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`
+3. Create `.env.local` (empty file)
+4. If the app has hardcoded `process.env.PORT` or similar, refactor to use `env.PORT`
 
 ### 4c. Dependency Installation
 
@@ -209,11 +205,11 @@ 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`
+- The Zod schema files (client.ts/server.ts/env.ts) are the registry of env vars — keep them well-commented. There is no .env.example; values come from Infisical or the platform.
+- After adding a new env var: add it to the env schema file (client.ts or server.ts) and, if used locally, .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
+- After removing an env var: remove from the schema 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
 ```
 
 If a `### env-t3 maintenance` section already exists in the file, skip — do not duplicate.
@@ -253,9 +249,10 @@ 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`
+- Fill in `.env.local` with your actual values (the env schema files document what's needed), or run via `infisical run` once `/scaffold-infisical` is set up
+- As you add features, add their env vars to the schema files (the registry)
 - Run `bun dev` to verify env validation passes
+- For multi-app/multi-environment projects, run `/scaffold-infisical` next to centralize secret delivery (a /shared single source of truth with environment-aware references) instead of per-app `.env` files
 
 ## Important Notes
 

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

@@ -205,9 +205,8 @@ Follow the `env-t3` blueprint's integration steps:
    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
+4. Create `apps/web/.env.local` (empty)
+5. Ensure `@t3-oss/env-nextjs` and `zod` are in `apps/web/package.json` dependencies
 
 ### 5.5b. Frontend UI Setup (if opted in)
 
@@ -318,11 +317,11 @@ Then append sections for each blueprint applied in this run. Foundation always a
 - 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`
+- The Zod schema files (client.ts/server.ts/env.ts) are the registry of env vars — keep them well-commented. There is no .env.example; values come from Infisical or the platform.
+- After adding a new env var: add it to the env schema file (client.ts or server.ts) and, if used locally, .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
+- After removing an env var: remove from the schema 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
 ```
 
 If frontend UI was applied, also append:

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

@@ -0,0 +1,173 @@
+---
+name: scaffold-infisical
+description: Scaffold Infisical secret management — a /shared domain structure with environment-aware references, placeholder injection, and infisical run wiring — driven by the project's T3 env schemas
+---
+
+# Scaffold Infisical Secrets Blueprint
+
+Scaffold the `secrets-infisical` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack. This blueprint **depends on `env-t3`** — it reads the T3 Zod schemas to learn which variables exist, then builds the Infisical structure around them.
+
+## Step 1: Read the Blueprint
+
+Read the full BLUEPRINT.md and all template files:
+
+```
+~/.withmata/blueprints/blueprints/features/secrets-infisical/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/secrets-infisical/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:
+  - Confirm `env-t3` is installed. If NOT, **stop** and tell the user to run `/scaffold-env` first (hard dependency — the T3 schemas are the source of truth for the variable list).
+  - Note `db-drizzle-postgres` / `auth-better-auth` — they define the natural domains (databases, auth).
+  - npm scope, workspace layout, project type.
+  - If `secrets-infisical` is already listed → switch to upgrade mode (Step 1.6).
+
+- **If it does not exist**: env-t3 cannot be confirmed installed. Ask the user whether the project has T3 env schemas; if not, point them to `/scaffold-env` first.
+
+## Step 1.6: Upgrade Mode
+
+If `secrets-infisical` is found in `.project-context.md` under `## Installed Blueprints`:
+
+1. Read the recorded domain map, environments, and apps wired.
+2. Re-read the T3 schemas; diff against the recorded shared keys.
+3. For each NEW var: classify (shared vs app-native), pick its domain, plan a placeholder in `/shared/<domain>` for every env + an env-aware reference in each consuming app folder.
+4. Present additions; never delete user secrets without confirmation.
+5. Update `scripts/infisical-map.sh`, re-run the sync script in dry-run, then apply.
+6. Update `installed_at`; skip to Step 9 (Output Summary).
+
+## Step 0: Preconditions (verify before any changes)
+
+- `infisical --version` works (else: `brew install infisical/get-cli/infisical`).
+- `infisical login` done.
+- An Infisical project exists and `infisical init` has produced a committed `.infisical.json` in each app/package dir (workspaceId only — no secrets).
+- The project's environments are known (default `dev`, `staging`, `prod`). Confirm with the user; capture the exact environment **slugs** — these go into the reference prefix and MUST match Infisical's env slugs.
+
+## Step 2: Understand the Target Project
+
+- Detect project type (monorepo vs single-repo) — reuse the same detection as scaffold-env (`turbo.json`, `"workspaces"`, `pnpm-workspace.yaml`, etc.).
+- Discover apps/packages that need secrets (`apps/web`, `apps/server`, `packages/db`, …).
+- **Read the T3 env schemas** in each (`env/client.ts`, `env/server.ts`, backend `env.ts`, plus how `packages/db` reads `process.env`) → the full variable list per app.
+
+## Step 3: Derive and Confirm the Plan (do not apply yet)
+
+- Classify each var:
+  - **app-native** (`NEXT_PUBLIC_*`, `PORT`, single-app config) → real value in the app folder, never referenced.
+  - **shared** (DB URLs, API keys, anything >1 app uses, or a domain's canonical key) → goes in `/shared/<domain>` + an env-aware reference in each consuming app.
+  - When ambiguous, ask.
+- Group shared vars into domains (derive from installed blueprints + schema groups; see the BLUEPRINT domain table).
+- Build a dry-run plan: folders, shared placeholders, app references, app-native vars left in place.
+- **Present the domain map + plan and ask the user to confirm/edit.** Encourage verbose, self-describing names (`IMAGE_BUCKET_ENDPOINT`, not `STORAGE_ENDPOINT`). Offer an optional rename/cleanup sub-step if the project has vague names or dead vars.
+
+## Step 4: Generate the Sync Script + Data Map
+
+- Write `scripts/infisical-sync.sh` (idempotent, dry-run by default, `APPLY=1` to apply, loops the environments list) and `scripts/infisical-map.sh` (the confirmed `ENVIRONMENTS`, `DOMAINS`, `APP_PATHS`, `SHARED_MAP`, `REF_MAP`).
+- The reference helper MUST emit the env-prefixed form, substituting the current loop environment's slug:
+
+  ```bash
+  REF() { printf '${%s.shared.%s.%s}' "$ENV" "$1" "$2"; }   # $ENV is the slug
+  ```
+
+- Shared placeholders use the `REPLACE_ME` sentinel (or sensible non-secret defaults). Never overwrite an existing value.
+- `chmod +x scripts/infisical-sync.sh`.
+
+## Step 5: Apply
+
+- Run dry-run (`APPLY=0`), show the plan, get the OK, then run with `APPLY=1`. The script loops every environment.
+
+## Step 6: Wire package.json
+
+- Add/adjust `infisical run --path=/apps/<app> --env=<env>` wrappers in dev/run scripts; add `:dev` variants for `packages/db` scripts. Leave production scripts clean (the host injects Infisical).
+
+## Step 7: Verify (do not skip)
+
+For at least the dev environment, resolve a reference end to end:
+
+```bash
+infisical run --path=/apps/server --env=dev -- printenv CORE_DATABASE_URL
+```
+
+- Prints a value → good.
+- Prints the literal `${dev.shared...}` → the reference is malformed or the shared key/folder is missing. Fix before continuing. (Most common past failure: the bare `${shared...}` form without the env slug.)
+
+## Step 8: Record + Maintenance Skill
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### secrets-infisical
+blueprint: secrets-infisical
+installed_at: <date>
+choices:
+  placeholder_sentinel: REPLACE_ME
+  script_language: bash
+environments:
+  - <env slugs>
+domain_map:
+  <domain>: [<keys>]
+apps_wired:
+  - path: <appPath>
+    references: [<domains>]
+script_path: scripts/infisical-sync.sh
+```
+
+If `.project-context.md` does not exist, create it with the standard header and the Installed Blueprints section.
+
+### Create Maintenance Skill
+
+Append to the shared project-level maintenance skill at `<project>/.claude/skills/project-maintenance/SKILL.md`. If the file does not exist, create it with frontmatter:
+
+```yaml
+---
+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 (skip if `### secrets-infisical maintenance` already exists — do not duplicate):
+
+```markdown
+### secrets-infisical maintenance
+- Adding a SHARED env var (used by >1 app, or a domain's canonical value):
+  1. Add the key to its `/shared/<domain>` folder in EVERY environment, set to
+     `REPLACE_ME` (or a non-secret default).
+  2. Add an environment-aware reference `${<env>.shared.<domain>.<KEY>}` in each
+     consuming app/package folder, for every environment.
+  3. Add the key to scripts/infisical-map.sh (SHARED_MAP + REF_MAP) and re-run
+     `APPLY=1 ./scripts/infisical-sync.sh`.
+  4. Tell the human which `/shared/<domain>/<KEY>` placeholders to fill.
+- Adding an APP-NATIVE var (PORT, NEXT_PUBLIC_*, single-app config): set it
+  directly in that app's Infisical folder as a real value — do NOT create a
+  shared key or reference.
+- Reference syntax is ALWAYS `${<env-slug>.shared.<domain>.<KEY>}` where the slug
+  matches the environment the reference lives in. The bare `${shared...}` form
+  DOES NOT resolve. Verify with:
+  `infisical run --path=/apps/<app> --env=dev -- printenv <KEY>`.
+- Rotating a secret: edit the single `/shared/<domain>/<KEY>` value; all
+  referencing apps inherit it. Never edit the value in an app folder.
+- Removing a var: delete the shared key AND every app reference to it; remove from
+  infisical-map.sh.
+- Never commit real secret values. `.infisical.json` is safe to commit; `.env*`
+  stays gitignored.
+```
+
+## Step 9: Output Summary
+
+- List files created/modified, with a one-line description each.
+- Print the full domain map and the per-app reference list.
+- Print the app-native vars as "set directly — not referenced."
+- Print the **`REPLACE_ME` checklist**: every `/shared/<domain>/<KEY>` still set to the placeholder, per environment, so the user knows exactly what to paste into the Infisical dashboard.
+- Remind: real values are pasted in Infisical; the agent never sets them.
+
+## Important Notes
+
+- The reference slug MUST match the environment it lives in. The script iterates per env and substitutes `$ENV` into both `--env` and the reference string.
+- Never write real secret values — only placeholders and plumbing.
+- `.infisical.json` is safe to commit; `.env*` stays gitignored.
+- Idempotent: re-running the sync script must be safe — `stub` only sets when empty, `link` just rewrites the same reference.

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`, `/copywrite`, `/copywrite-landing`, `/design-system`, `/scaffold-foundation`, `/scaffold-env`, `/scaffold-tailwind`, `/scaffold-ui`, `/scaffold-auth`, `/scaffold-db`, `/audit`, plus `blueprint-catalog` (background, auto-invoked)
+- **Available skills:** `/new-project`, `/discover`, `/copywrite`, `/copywrite-landing`, `/design-system`, `/scaffold-foundation`, `/scaffold-env`, `/scaffold-tailwind`, `/scaffold-ui`, `/scaffold-auth`, `/scaffold-db`, `/scaffold-infisical`, `/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/env-t3/BLUEPRINT.md

@@ -10,7 +10,9 @@ Complete.
 
 ## Problem
 
-Environment variable management is tedious and error-prone across projects. Developers forget to add new variables to `.env.example`, miss the split between client and server vars in Next.js, deploy with missing variables that only crash at runtime, and have no type safety when accessing `process.env`. This blueprint creates a validated, type-safe environment variable system using `@t3-oss/env` + Zod that catches missing or malformed variables at build time.
+Environment variable management is tedious and error-prone across projects. Developers miss the split between client and server vars in Next.js, deploy with missing variables that only crash at runtime, and have no type safety when accessing `process.env`. This blueprint creates a validated, type-safe environment variable system using `@t3-oss/env` + Zod that catches missing or malformed variables at build time.
+
+The Zod schema files are the **registry** of what environment variables an app needs — there is no separate `.env.example`. Values are delivered by Infisical (see the `secrets-infisical` blueprint) or the deployment platform; for local work, a developer uses `.env.local` or `infisical run`.
 
 This blueprint covers both Next.js apps (client/server split with `@t3-oss/env-nextjs`) and backend apps (server-only with `@t3-oss/env-core`).
 
@@ -56,9 +58,9 @@ Both files are imported in `next.config.ts` to trigger build-time validation.
 
 - **`z.preprocess` for PORT** (recommended) — Environment variables are always strings. PORT needs to be a number. `z.preprocess` handles the string-to-number conversion cleanly.
 
-- **`.env.example` with documentation** (required) — Every app gets a documented `.env.example` with section headers, comments explaining each variable, and local/production value hints. This is the single source of truth for what environment variables an app needs.
+- **Schema files are the registry** (required) — The Zod schema files (`client.ts`, `server.ts`, `env.ts`) are the single source of truth for what environment variables an app needs. Keep them well-commented (purpose, local/production hints) — they replace the old `.env.example`. Values come from Infisical or the platform.
 
-- **Empty `.env.local` created** (required) — An empty `.env.local` file is created during scaffolding so developers have the file ready to fill in. This file is gitignored.
+- **Empty `.env.local` created** (required) — An empty `.env.local` file is created during scaffolding so developers have the file ready to fill in for local work. This file is gitignored.
 
 ---
 
@@ -70,7 +72,7 @@ Both files are imported in `next.config.ts` to trigger build-time validation.
 - Zod for schema validation
 - Client/server split in Next.js (two files)
 - Build-time validation via `next.config.ts` import
-- `.env.example` for every app
+- Well-commented schema files as the variable registry (no `.env.example`)
 
 **Recommended defaults — ask during scaffolding:**
 
@@ -123,7 +125,6 @@ apps/web/
 │   ├── client.ts              # Client env schema + validation
 │   └── server.ts              # Server env schema + validation
 ├── next.config.ts             # Imports both env files for build-time validation
-├── .env.example               # Documented env template
 └── .env.local                 # Local values (gitignored)
 ```
 
@@ -152,7 +153,6 @@ apis/server/
 ├── src/
 │   ├── env.ts                 # Server env schema + validation
 │   └── index.ts               # Imports env.ts at top
-├── .env.example               # Documented env template
 └── .env.local                 # Local values (gitignored)
 ```
 
@@ -175,7 +175,6 @@ For standalone applications (Next.js or backend) without a monorepo, the pattern
 |--------|----------|-------------|
 | Next.js env location | `apps/web/src/env/` | `src/env/` |
 | Backend env location | `apis/server/src/env.ts` | `src/env.ts` |
-| `.env.example` location | Per-app (e.g., `apps/web/.env.example`) | Project root `.env.example` |
 | `.env.local` location | Per-app (e.g., `apps/web/.env.local`) | Project root `.env.local` |
 | Import path | `~/env/server` or `~/env/client` | `~/env/server` or `@/env/server` |
 
@@ -186,7 +185,7 @@ All core patterns are project-type-agnostic:
 - Zod schemas for validation
 - Client/server split (two files) for Next.js
 - Build-time validation via `next.config.ts` import
-- `.env.example` documentation pattern
+- Well-commented schema files as the variable registry
 - `emptyStringAsUndefined: true`
 
 ---
@@ -197,10 +196,8 @@ All core patterns are project-type-agnostic:
 |---|---|---|---|
 | `files/nextjs/env/client.ts` | Next.js client env schema | `apps/web/src/env/client.ts` | `src/env/client.ts` |
 | `files/nextjs/env/server.ts` | Next.js server env schema | `apps/web/src/env/server.ts` | `src/env/server.ts` |
-| `files/nextjs/.env.example` | Documented env template (Next.js) | `apps/web/.env.example` | `.env.example` |
 | `files/nextjs/.env.local` | Empty local env file (Next.js) | `apps/web/.env.local` | `.env.local` |
 | `files/server/env.ts` | Backend env schema (`@t3-oss/env-core`) | `apis/server/src/env.ts` | `src/env.ts` |
-| `files/server/.env.example` | Documented env template (backend) | `apis/server/.env.example` | `.env.example` |
 | `files/server/.env.local` | Empty local env file (backend) | `apis/server/.env.local` | `.env.local` |
 
 ---
@@ -222,29 +219,27 @@ All core patterns are project-type-agnostic:
    import "./src/env/client";
    ```
    If existing `import "./env"` is present, replace it with the two new imports.
-6. Copy `.env.example` — replace `{{APP_NAME}}`
-7. Create `.env.local` (empty)
-8. If other blueprints are already installed, pre-populate their env vars into the appropriate schema files
+6. Create `.env.local` (empty)
+7. If other blueprints are already installed, pre-populate their env vars into the appropriate schema files
 
 ### Phase 2: Backend App Setup (if present)
 
-9. Copy `env.ts` to `src/env.ts` in the backend app — replace `{{APP_NAME}}`
-10. Update the app's entry point (e.g., `src/index.ts`) to import `env.ts`:
-    ```typescript
-    import { env } from "./env.js";
-    ```
-11. Copy `.env.example` — replace `{{APP_NAME}}`
-12. Create `.env.local` (empty)
+8. Copy `env.ts` to `src/env.ts` in the backend app — replace `{{APP_NAME}}`
+9. Update the app's entry point (e.g., `src/index.ts`) to import `env.ts`:
+   ```typescript
+   import { env } from "./env.js";
+   ```
+10. Create `.env.local` (empty)
 
 ### Phase 3: Dependency Installation
 
-13. For each Next.js app: ensure `@t3-oss/env-nextjs` and `zod` are in `dependencies`
-14. For each backend app: ensure `@t3-oss/env-core`, `zod`, and `dotenv` are in `dependencies`
+11. For each Next.js app: ensure `@t3-oss/env-nextjs` and `zod` are in `dependencies`
+12. For each backend app: ensure `@t3-oss/env-core`, `zod`, and `dotenv` are in `dependencies`
 
 ### Phase 4: Verification
 
-15. Run `bun dev` (or equivalent) — env validation should run without errors
-16. Try removing a required variable from `.env.local` — build should fail with a clear error message
+13. Run `bun dev` (or equivalent) — env validation should run without errors
+14. Try removing a required variable from `.env.local` — build should fail with a clear error message
 
 ---
 
@@ -254,22 +249,22 @@ All core patterns are project-type-agnostic:
 
 | When you... | Then do... | Why |
 |---|---|---|
-| Add a new env var in code | Add to `env/client.ts` or `env/server.ts` schema AND `.env.example` AND `.env.local` | Missing from schema = build-time crash; missing from example = teammates can't set up |
+| Add a new env var in code | Add to the `env/client.ts` or `env/server.ts` schema (the registry) and, if used locally, `.env.local` | Missing from schema = build-time crash; the schema documents what's needed |
 | Add a `NEXT_PUBLIC_*` var | Put it in `env/client.ts` with both `client` schema and `runtimeEnv` entries | Client vars must be explicitly mapped in Next.js |
 | Add a server-only var to Next.js | Put it in `env/server.ts` (uses `experimental__runtimeEnv: process.env`) | Avoids listing every server var twice |
-| Remove an env var | Remove from schema file, `.env.example`, and `.env.local` | Stale vars cause confusion |
+| Remove an env var | Remove from the schema file and `.env.local` | Stale vars cause confusion |
 | Add a new app to the monorepo | Create its own `env/` files — don't share env schemas between apps | Each app has different variable requirements |
-| Change a var from optional to required | Update the Zod schema (remove `.optional()`) and ensure `.env.example` has a value | Will break builds for teammates with empty values |
+| Change a var from optional to required | Update the Zod schema (remove `.optional()`) and ensure the value is provided (Infisical/platform/`.env.local`) | Will break builds where the value is empty |
 
 ### Condensed Rules for project rules file
 
 ```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`
+- The Zod schema files (client.ts/server.ts/env.ts) are the registry of env vars — keep them well-commented. There is no .env.example; values come from Infisical or the platform.
+- After adding a new env var: add it to the env schema file (client.ts or server.ts) and, if used locally, .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
+- After removing an env var: remove from the schema 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
 ```
 
 ---
@@ -288,7 +283,7 @@ All core patterns are project-type-agnostic:
 - **Client/server split** — Next.js apps always get two files, not one combined file
 - **Build-time validation** — env files are always imported in `next.config.ts`
 - **`emptyStringAsUndefined`** — always enabled (prevents empty string foot-guns)
-- **`.env.example` documentation** — always includes section headers and comments
+- **Schema as registry** — the Zod schema files are the documented source of truth for env vars; no `.env.example` (values come from Infisical or the platform)
 
 ## Project Context Output
 
@@ -307,13 +302,11 @@ apps_configured:
     files:
       - src/env/client.ts
       - src/env/server.ts
-      - .env.example
       - .env.local
   - name: server
     type: backend
     files:
       - src/env.ts
-      - .env.example
       - .env.local
 packages_added:
   - "@t3-oss/env-nextjs"

package/blueprints/features/secrets-infisical/BLUEPRINT.md

@@ -0,0 +1,295 @@
+# Secrets Management Blueprint — Infisical /shared + Env-Aware References
+
+## Tier
+
+Feature
+
+## Status
+
+Complete.
+
+## Problem
+
+Multi-app monorepos duplicate the same secret (DB URLs, API keys) across every app's env, so a rotation means editing N places and inevitably drifting. Local `.env` files also have to be copied into every fresh clone / workspace, and there's no single place that says "this is the canonical value." This blueprint centralizes every shared secret **once** in Infisical under a domain-grouped `/shared` folder, and has each app reference those values, so a single change propagates everywhere and a fresh checkout needs only `infisical login` + the committed `.infisical.json`.
+
+The agent does all the plumbing (folders, placeholders, references, `infisical run` wiring); the human's only remaining job is to paste real secret values over the placeholders in the Infisical dashboard. The agent never invents or guesses secret values.
+
+## Blueprint Dependencies
+
+- **Required:** `env-t3` — the T3 Zod schemas (`env/client.ts`, `env/server.ts`, backend `env.ts`) are the source of truth for which variables exist; this blueprint reads them to build the Infisical structure. If `env-t3` is not installed, run `/scaffold-env` first.
+- **Recommended:** `db-drizzle-postgres`, `auth-better-auth` — they define the natural domains (databases, auth) and their variables.
+
+### Interaction with Other Blueprints
+
+- `env-t3` defines *what* vars exist + validation. This blueprint defines *where the values live and how they're delivered*. They are complementary layers — `env-t3` stays usable without Infisical (some projects deliver secrets via Vercel/Railway directly), and Infisical cleanly **consumes** the T3 schemas instead of bloating them.
+- When a feature blueprint adds an env var to a T3 schema, the maintenance rules here sync it into Infisical as a placeholder. The T3 schema change and the Infisical change are two halves of the same edit.
+
+---
+
+## Architecture
+
+### Core Pattern
+
+- Canonical **values** live exactly once in `/shared/<domain>/<KEY>` (placeholders until a human fills them).
+- Apps/packages hold **environment-aware references**: `${<ENV_SLUG>.shared.<domain>.<KEY>}` — never raw values for shared vars.
+- **App-native** vars (`PORT`, `NEXT_PUBLIC_*`, langfuse keys, etc.) stay as real values in the app folder, never referenced.
+- The CLI delivers secrets at launch via `infisical run --path=<app> --env=<env>`.
+
+Change a shared value once → every app that references it sees the new value. No copy-paste drift across `apps/server`, `apps/web`, `packages/db`.
+
+### Reference Syntax (CRITICAL)
+
+References MUST be environment-prefixed, and the slug MUST match the environment the reference lives in:
+
+```
+${dev.shared.pipeline.PIPELINE_VERSION}      # in the dev environment
+${staging.shared.pipeline.PIPELINE_VERSION}  # in the staging environment
+${prod.shared.pipeline.PIPELINE_VERSION}     # in the prod environment
+```
+
+The **same key** therefore has a **different literal value in each environment** — each points at its own environment's shared subtree.
+
+The bare form `${shared.<domain>.<KEY>}` **DOES NOT RESOLVE** (this is the #1 past failure). Other wrong forms:
+
+```
+${shared.pipeline.PIPELINE_VERSION}          ← MISSING env slug — does not resolve
+${env.shared.pipeline.PIPELINE_VERSION}      ← literal "env" — wrong
+${/shared/pipeline/PIPELINE_VERSION}         ← slash path form — wrong for this case
+```
+
+Verify with the §Verification check below — the reference must print its value, not the literal `${...}`.
+
+### Domains
+
+`/shared` is subdivided by **concern** (not by app), derived from installed blueprints + the T3 schemas: e.g. `core`, `auth`, `pipeline`, `knowledge-base`, `image-storage`, `ai`, `search`, `infra`. Domains are a soft taxonomy; the user confirms the map before anything is applied.
+
+| Source signal | Domain(s) created |
+|---|---|
+| `db-drizzle-postgres` installed, schema groups | one domain per DB group (`core`, `auth`, `pipeline`, …), each with a `*_DATABASE_URL` |
+| `auth-better-auth` installed | `auth` (`BETTER_AUTH_*`, `GOOGLE_*`, `RESEND_EMAIL_API_KEY`) |
+| Object storage / S3-style vars present | `image-storage`, `knowledge-base` (bucket keys) |
+| LLM / model API keys present | `ai` |
+| Web search / scraping / media API keys present | `search` |
+| Redis / queue / cache | `infra` |
+| Anything not classifiable | `core` (catch-all) or ask |
+
+### Placeholders
+
+Every shared secret is created with the `REPLACE_ME` sentinel (caps-with-underscore, trivially greppable in the UI). Sensible **non-secret** defaults are allowed for clearly non-sensitive config (`KB_QUEUE_NAMESPACE=pgboss_<env>`, `KB_ENABLE_RERANK=false`, `*_PUBLIC_BASE_URL=https://replace-me.example.com`). Anything that is an actual secret (keys, passwords, connection strings) → `REPLACE_ME`. The sync script only stubs a value if it is currently empty — it never overwrites a filled value.
+
+### Verbose, Meaningful Names
+
+The blueprint encourages self-describing variable names with the domain/purpose embedded: `STORAGE_ENDPOINT` → `IMAGE_BUCKET_ENDPOINT`, `RESEND_API_KEY` → `RESEND_EMAIL_API_KEY`, `SYNTHETIC_API_KEY` → `SYNTHETIC_AI_API_KEY`, `PARALLEL_API_KEY` → `PARALLEL_RESEARCH_API_KEY`. The skill offers an optional rename/cleanup step.
+
+---
+
+## Hard Requirements vs Recommended Defaults
+
+**Hard requirements:**
+- Infisical CLI + a linked project (`.infisical.json` committed per app/package — holds no secrets).
+- `/shared/<domain>` canonical values; app folders hold env-aware references.
+- Environment-prefixed reference syntax (the slug matches the environment the reference lives in).
+- An idempotent, dry-run-by-default sync script committed to the repo.
+- `infisical run --path --env` wrappers in dev/run scripts.
+
+**Recommended defaults — ask during scaffolding:**
+
+| Choice | Recommended | Alternatives |
+|---|---|---|
+| Environments | `dev`, `staging`, `prod` | project-specific set (use the real Infisical slugs) |
+| Placeholder sentinel | `REPLACE_ME` | per-key sentinel `REPLACE_ME_<KEY>`; key-name-as-value |
+| Sync script language | bash (uses Infisical CLI, zero deps) | TypeScript |
+| Domain map | derived from blueprints/schemas, user confirms | fully manual |
+
+---
+
+## Dependencies
+
+### Tooling
+
+| Tool | Install | Purpose |
+|---|---|---|
+| Infisical CLI | `brew install infisical/get-cli/infisical` | Create folders/secrets, deliver them via `infisical run` |
+
+### npm packages
+
+None required at runtime — delivery is via the CLI wrapper. `env-t3` already provides the validation layer.
+
+### Environment Variables
+
+This blueprint creates no new variables of its own. It mirrors the variables already declared in the project's T3 env schemas into Infisical.
+
+---
+
+## Monorepo Wiring
+
+- `.infisical.json` committed in each of `apps/*`, `packages/*` that need secrets (workspaceId only — no secrets).
+- `package.json` dev scripts wrapped in `infisical run --path=/apps/<app> --env=dev`:
+  ```jsonc
+  // apps/server
+  "dev": "infisical run --path=/apps/server --env=dev -- bun --watch src/index.ts"
+  // apps/web
+  "dev": "infisical run --path=/apps/web --env=dev -- bun run --bun next dev"
+  // packages/db — a :dev variant per script that needs DB envs
+  "core:migrate:dev": "infisical run --env=dev --path=/packages/db -- bun run core:migrate"
+  ```
+- Production scripts stay clean — Railway/the host injects Infisical at the platform level.
+
+## Single-Repo Adaptation
+
+One app folder (e.g. `/app`) plus `/shared`. Same env-aware references; same placeholder + sync-script approach. `infisical run --path=/app --env=dev`. The `APP_PATHS` and `REF_MAP` in the data map collapse to the single app.
+
+---
+
+## File Manifest
+
+| File | Purpose | Target |
+|---|---|---|
+| `files/scripts/infisical-sync.sh` | Idempotent, dry-run-by-default structure sync; loops all environments | `scripts/infisical-sync.sh` |
+| `files/scripts/infisical-map.sh` | Data map: `ENVIRONMENTS`, `DOMAINS`, `APP_PATHS`, `SHARED_MAP`, `REF_MAP` (generated per project) | `scripts/infisical-map.sh` |
+| `files/docs/INFISICAL.md` | Runbook: setup, reference syntax, verification, maintenance | `docs/INFISICAL.md` |
+
+---
+
+## Integration Steps
+
+### Phase 0: Preconditions
+
+1. Confirm Infisical CLI installed (`infisical --version`); else `brew install infisical/get-cli/infisical`.
+2. Confirm `infisical login` done.
+3. Confirm an Infisical project exists and `infisical init` produced a committed `.infisical.json` in each app/package dir.
+4. Confirm `env-t3` is installed (read `.project-context.md`). If not, run `/scaffold-env` first.
+5. Capture the real environment **slugs** (default `dev`, `staging`, `prod`) — these go into the reference prefix and MUST match Infisical exactly.
+
+### Phase 1: Read Sources of Truth
+
+6. Read the T3 env schemas in every app/package → full variable list per app.
+7. Read `.project-context.md` → installed blueprints, app layout, npm scope.
+
+### Phase 2: Derive and Confirm the Plan (do not apply yet)
+
+8. Classify each var: shared-reference vs app-native.
+9. Group shared vars into domains (table above).
+10. Produce a dry-run plan: folders, shared placeholders, app references, app-native vars left in place.
+11. **Present the domain map + plan and ask the user to confirm/edit.**
+
+### Phase 3: Generate the Sync Script + Data Map
+
+12. Write `scripts/infisical-sync.sh` and `scripts/infisical-map.sh` from the templates, filling the data map from the confirmed plan.
+
+### Phase 4: Apply
+
+13. Run dry-run, show output, then (on user OK) re-run with `APPLY=1`. The script loops every environment.
+
+### Phase 5: Wire package.json
+
+14. Add/adjust `infisical run --path=... --env=...` wrappers in dev/run scripts; add `:dev` variants for `packages/db` scripts. Leave production scripts clean.
+
+### Phase 6: Verify (do not skip)
+
+15. Resolve a reference end to end for at least `dev`:
+    ```bash
+    infisical run --path=/apps/server --env=dev -- printenv CORE_DATABASE_URL
+    ```
+    Prints a value → good. Prints the literal `${dev.shared...}` → the reference is malformed or the shared key/folder is missing. Fix before continuing.
+
+### Phase 7: Record + Summarize
+
+16. Update `.project-context.md` and the project-maintenance skill.
+17. Print files created, the full domain map, and the **`REPLACE_ME` checklist** the user must fill in Infisical.
+
+---
+
+## Maintenance Hooks
+
+### Secrets Hooks
+
+| When you... | Then do... | Why |
+|---|---|---|
+| Add a **shared** env var to a T3 schema | Add the key to `/shared/<domain>` (placeholder) in every env, add an env-aware reference in each consuming app folder, update `infisical-map.sh`, re-run the sync script | Keeps the single source of truth and every consumer in sync |
+| Add an **app-native** var | Set it directly in that app's Infisical folder as a real value — no shared key, no reference | App-native vars don't belong in `/shared` |
+| Add a new environment | Add its slug to `ENVIRONMENTS` and re-run the sync script | Folders + references are per-environment |
+| Rotate a secret | Edit the single `/shared/<domain>/<KEY>` value; all apps inherit it | Never edit a value in an app folder — it should be a reference |
+| Remove a var | Delete the shared key AND every app reference; remove from `infisical-map.sh` | Stale references print the literal `${...}` |
+
+### Condensed Rules for project rules file
+
+```markdown
+### secrets-infisical maintenance
+- Adding a SHARED env var (used by >1 app, or a domain's canonical value):
+  1. Add the key to its `/shared/<domain>` folder in EVERY environment, set to
+     `REPLACE_ME` (or a non-secret default).
+  2. Add an environment-aware reference `${<env>.shared.<domain>.<KEY>}` in each
+     consuming app/package folder, for every environment.
+  3. Add the key to scripts/infisical-map.sh (SHARED_MAP + REF_MAP) and re-run
+     `APPLY=1 ./scripts/infisical-sync.sh`.
+  4. Tell the human which `/shared/<domain>/<KEY>` placeholders to fill.
+- Adding an APP-NATIVE var (PORT, NEXT_PUBLIC_*, single-app config): set it
+  directly in that app's Infisical folder as a real value — do NOT create a
+  shared key or reference.
+- Reference syntax is ALWAYS `${<env-slug>.shared.<domain>.<KEY>}` where the slug
+  matches the environment the reference lives in. The bare `${shared...}` form
+  DOES NOT resolve. Verify with:
+  `infisical run --path=/apps/<app> --env=dev -- printenv <KEY>`.
+- Rotating a secret: edit the single `/shared/<domain>/<KEY>` value; all
+  referencing apps inherit it. Never edit the value in an app folder.
+- Removing a var: delete the shared key AND every app reference to it; remove from
+  infisical-map.sh.
+- Never commit real secret values. `.infisical.json` is safe to commit; `.env*`
+  stays gitignored.
+```
+
+---
+
+## What's Configurable
+
+- Environments list (slugs)
+- Domain map (the soft taxonomy)
+- Placeholder sentinel
+- Which apps/packages are wired
+- Sync script language (bash vs TS)
+
+## What's Opinionated
+
+- **Infisical** as the secret store.
+- **`/shared` + env-aware references** as the single-source-of-truth mechanism.
+- **Environment-prefixed reference syntax** — non-negotiable; it's the only form that resolves.
+- **Placeholder-first, human-fills-values** workflow — the agent never writes real secret values.
+
+## Project Context Output
+
+Appends to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### secrets-infisical
+blueprint: secrets-infisical
+installed_at: <date>
+choices:
+  placeholder_sentinel: REPLACE_ME
+  script_language: bash
+environments:
+  - dev
+  - staging
+  - prod
+domain_map:
+  core: [CORE_DATABASE_URL]
+  auth: [AUTH_DATABASE_URL, BETTER_AUTH_URL, BETTER_AUTH_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, RESEND_EMAIL_API_KEY]
+  # ... one entry per domain
+apps_wired:
+  - path: /apps/server
+    references: [core, auth, ...]
+  - path: /apps/web
+    references: [ai]
+  - path: /packages/db
+    references: [core, auth, pipeline, knowledge-base]
+script_path: scripts/infisical-sync.sh
+```
+
+---
+
+## References
+
+- **Infisical secret references:** https://infisical.com/docs/documentation/platform/secret-reference
+- **Infisical CLI:** https://infisical.com/docs/cli/overview
+- **`infisical run`:** https://infisical.com/docs/cli/commands/run
+- **`infisical secrets`:** https://infisical.com/docs/cli/commands/secrets

package/blueprints/features/secrets-infisical/files/docs/INFISICAL.md

@@ -0,0 +1,119 @@
+# Infisical Secrets Runbook
+
+How secrets work in this project, and how to keep them in sync.
+
+## The model
+
+- **Canonical values live once** in Infisical under `/shared/<domain>/<KEY>`.
+- **Apps and packages hold references**, never raw values, for anything shared.
+- **App-native values** (`PORT`, `NEXT_PUBLIC_*`, etc.) live directly in the app's
+  Infisical folder.
+- Secrets are delivered at launch by the Infisical CLI:
+  `infisical run --path=<app> --env=<env> -- <command>`.
+
+Change a shared value once and every referencing app inherits it — no drift.
+
+## Reference syntax (read this before editing anything)
+
+References are **environment-prefixed**. The slug MUST match the environment the
+reference lives in:
+
+```
+${dev.shared.pipeline.PIPELINE_VERSION}      # stored in the dev environment
+${staging.shared.pipeline.PIPELINE_VERSION}  # stored in the staging environment
+${prod.shared.pipeline.PIPELINE_VERSION}     # stored in the prod environment
+```
+
+The same key has a different literal value per environment — each points at its
+own environment's `/shared` subtree.
+
+**Wrong forms (do not use — they silently fail to resolve):**
+
+```
+${shared.pipeline.PIPELINE_VERSION}      ← missing env slug (the classic bug)
+${env.shared.pipeline.PIPELINE_VERSION}  ← literal "env"
+${/shared/pipeline/PIPELINE_VERSION}     ← slash path form
+```
+
+## First-time setup
+
+1. Install the CLI: `brew install infisical/get-cli/infisical`
+2. `infisical login`
+3. Ensure each app/package has a committed `.infisical.json` (from `infisical init`).
+   It holds the workspace id only — no secrets — and is safe to commit.
+4. Run the sync script to create the structure (see below).
+5. Open the Infisical dashboard and paste real values over every `REPLACE_ME`
+   placeholder in `/shared/<domain>`.
+
+## The sync script
+
+`scripts/infisical-sync.sh` creates and maintains the `/shared` structure and all
+app references. It is **dry-run by default** and **idempotent** (never overwrites a
+filled value):
+
+```bash
+# from a dir with .infisical.json (e.g. apps/server)
+APPLY=0 ./scripts/infisical-sync.sh    # dry run — prints the plan, changes nothing
+APPLY=1 ./scripts/infisical-sync.sh    # apply to every environment in ENVIRONMENTS
+```
+
+The plan lives in `scripts/infisical-map.sh` (`ENVIRONMENTS`, `DOMAINS`,
+`APP_PATHS`, `SHARED_MAP`, `REF_MAP`). Edit that file to add/remove vars.
+
+## Verification
+
+After applying, resolve a reference end to end:
+
+```bash
+infisical run --path=/apps/server --env=dev -- printenv CORE_DATABASE_URL
+```
+
+- ✅ prints the value (or `REPLACE_ME`) → the reference resolved correctly.
+- ❌ prints the literal `${dev.shared.core.CORE_DATABASE_URL}` → the reference is
+  malformed or the shared key/folder is missing. Fix before proceeding (almost
+  always a missing shared key or a bare `${shared...}` reference).
+
+## Running apps with secrets
+
+```jsonc
+// apps/server
+"dev": "infisical run --path=/apps/server --env=dev -- bun --watch src/index.ts"
+// apps/web
+"dev": "infisical run --path=/apps/web --env=dev -- bun run --bun next dev"
+// packages/db — a :dev variant per script that needs DB envs
+"core:migrate:dev": "infisical run --env=dev --path=/packages/db -- bun run core:migrate"
+```
+
+Production scripts stay clean — the host (e.g. Railway) injects Infisical at the
+platform level.
+
+## Maintenance
+
+**Add a shared var** (used by >1 app, or a domain's canonical value):
+1. Add `"domain KEY"` to `SHARED_MAP` and `"appPath domain KEY"` to `REF_MAP` in
+   `scripts/infisical-map.sh`.
+2. Run `APPLY=1 ./scripts/infisical-sync.sh`.
+3. Paste the real value over the new `/shared/<domain>/<KEY>` placeholder.
+
+**Add an app-native var:** set it directly in that app's Infisical folder as a
+real value. Do not add it to the map.
+
+**Add an environment:** add its slug to `ENVIRONMENTS` and re-run the sync.
+
+**Rotate a secret:** edit the single `/shared/<domain>/<KEY>` value. Every
+referencing app inherits it. Never edit the value in an app folder.
+
+**Remove a var:** delete the shared key and every app reference, and remove it
+from `infisical-map.sh`.
+
+## Gotchas
+
+- **Env slugs must match Infisical exactly.** If your envs are
+  Development/Staging/Production with slugs `dev`/`staging`/`prod`, the references
+  use `dev`/`staging`/`prod`.
+- **Folders are per-environment.** The tree exists in every environment; the sync
+  loops them all.
+- **Local override foot-gun:** a local `.env.local` applied with `override: true`
+  beats Infisical. Watch for stale local values masking the real ones.
+- **Never commit real secret values.** `.infisical.json` is safe to commit;
+  `.env*` stays gitignored.

package/blueprints/features/secrets-infisical/files/scripts/infisical-map.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# Data map for infisical-sync.sh — generated by /scaffold-infisical, edit freely.
+#
+# This file is the per-project plan. The example below is the worked reference
+# shape (a multi-app monorepo); /scaffold-infisical regenerates it from YOUR
+# project's T3 env schemas + installed blueprints. Treat it as a template, not a
+# hardcode.
+#
+# Four arrays drive the sync:
+#   ENVIRONMENTS  — the env slugs (MUST match Infisical exactly)
+#   DOMAINS       — the /shared subfolders
+#   APP_PATHS     — app/package folders that hold references
+#   SHARED_MAP    — "domain KEY [non-secret default]"  (omit default -> REPLACE_ME)
+#   REF_MAP       — "appPath domain KEY"  (the env-aware reference is generated)
+
+ENVIRONMENTS=(dev staging prod)
+
+DOMAINS=(core auth pipeline knowledge-base image-storage ai search infra)
+
+APP_PATHS=(/apps/server /apps/web /packages/db)
+
+# "domain KEY [non-secret default]"  — omit default for real secrets (-> REPLACE_ME)
+SHARED_MAP=(
+  "core CORE_DATABASE_URL"
+  "auth AUTH_DATABASE_URL"
+  "auth BETTER_AUTH_URL"
+  "auth BETTER_AUTH_SECRET"
+  "auth GOOGLE_CLIENT_ID"
+  "auth GOOGLE_CLIENT_SECRET"
+  "auth RESEND_EMAIL_API_KEY"
+  "pipeline PIPELINE_DATABASE_URL"
+  "pipeline PIPELINE_VERSION"
+  "knowledge-base KB_DATABASE_URL"
+  "knowledge-base KB_BUCKET_ENDPOINT"
+  "knowledge-base KB_BUCKET_NAME"
+  "knowledge-base KB_BUCKET_ACCESS_KEY_ID"
+  "knowledge-base KB_BUCKET_SECRET_ACCESS_KEY"
+  "knowledge-base KB_BUCKET_REGION"
+  "knowledge-base KB_QUEUE_NAMESPACE pgboss_dev"
+  "knowledge-base KB_ENABLE_RERANK false"
+  "image-storage IMAGE_BUCKET_ENDPOINT"
+  "image-storage IMAGE_BUCKET_NAME"
+  "image-storage IMAGE_BUCKET_ACCESS_KEY_ID"
+  "image-storage IMAGE_BUCKET_SECRET_ACCESS_KEY"
+  "image-storage IMAGE_BUCKET_PUBLIC_BASE_URL https://replace-me.example.com"
+  "ai OPENROUTER_API_KEY"
+  "ai OPENROUTER_DEFAULT_MODEL"
+  "ai SYNTHETIC_AI_API_KEY"
+  "ai MISTRAL_OCR_API_KEY"
+  "ai FIREWORKS_AI_API_KEY"
+  "ai JINA_PAGE_EXTRACTOR_API_KEY"
+  "search PARALLEL_RESEARCH_API_KEY"
+  "search TAVILY_API_KEY"
+  "search EXA_API_KEY"
+  "search PEXELS_API_KEY"
+  "search UNSPLASH_API_KEY"
+  "search BRAVE_SEARCH_API_KEY"
+  "search SERPER_API_KEY"
+  "infra REDIS_URL"
+)
+
+# "appPath domain KEY"  — the env-aware reference is generated automatically
+REF_MAP=(
+  "/apps/server core CORE_DATABASE_URL"
+  "/apps/server auth AUTH_DATABASE_URL"
+  "/apps/server auth BETTER_AUTH_URL"
+  "/apps/server auth BETTER_AUTH_SECRET"
+  "/apps/server auth GOOGLE_CLIENT_ID"
+  "/apps/server auth GOOGLE_CLIENT_SECRET"
+  "/apps/server auth RESEND_EMAIL_API_KEY"
+  "/apps/server pipeline PIPELINE_DATABASE_URL"
+  "/apps/server pipeline PIPELINE_VERSION"
+  "/apps/server knowledge-base KB_DATABASE_URL"
+  "/apps/server knowledge-base KB_BUCKET_ENDPOINT"
+  "/apps/server knowledge-base KB_BUCKET_NAME"
+  "/apps/server knowledge-base KB_BUCKET_ACCESS_KEY_ID"
+  "/apps/server knowledge-base KB_BUCKET_SECRET_ACCESS_KEY"
+  "/apps/server knowledge-base KB_BUCKET_REGION"
+  "/apps/server knowledge-base KB_QUEUE_NAMESPACE"
+  "/apps/server knowledge-base KB_ENABLE_RERANK"
+  "/apps/server image-storage IMAGE_BUCKET_ENDPOINT"
+  "/apps/server image-storage IMAGE_BUCKET_NAME"
+  "/apps/server image-storage IMAGE_BUCKET_ACCESS_KEY_ID"
+  "/apps/server image-storage IMAGE_BUCKET_SECRET_ACCESS_KEY"
+  "/apps/server image-storage IMAGE_BUCKET_PUBLIC_BASE_URL"
+  "/apps/server ai OPENROUTER_API_KEY"
+  "/apps/server ai OPENROUTER_DEFAULT_MODEL"
+  "/apps/server ai SYNTHETIC_AI_API_KEY"
+  "/apps/server ai MISTRAL_OCR_API_KEY"
+  "/apps/server ai FIREWORKS_AI_API_KEY"
+  "/apps/server ai JINA_PAGE_EXTRACTOR_API_KEY"
+  "/apps/server search PARALLEL_RESEARCH_API_KEY"
+  "/apps/server search TAVILY_API_KEY"
+  "/apps/server search EXA_API_KEY"
+  "/apps/server search PEXELS_API_KEY"
+  "/apps/server search UNSPLASH_API_KEY"
+  "/apps/server search BRAVE_SEARCH_API_KEY"
+  "/apps/server search SERPER_API_KEY"
+  "/apps/server infra REDIS_URL"
+  "/apps/web ai SYNTHETIC_AI_API_KEY"
+  "/packages/db core CORE_DATABASE_URL"
+  "/packages/db auth AUTH_DATABASE_URL"
+  "/packages/db pipeline PIPELINE_DATABASE_URL"
+  "/packages/db knowledge-base KB_DATABASE_URL"
+  "/packages/db knowledge-base KB_BUCKET_ENDPOINT"
+  "/packages/db knowledge-base KB_BUCKET_NAME"
+  "/packages/db knowledge-base KB_BUCKET_ACCESS_KEY_ID"
+  "/packages/db knowledge-base KB_BUCKET_SECRET_ACCESS_KEY"
+  "/packages/db knowledge-base KB_BUCKET_REGION"
+)
+
+# NOTE on app-native vars: deliberately NOT listed here. PORT, FRONTEND_DOMAIN,
+# NEXT_PUBLIC_*, langfuse keys, etc. are set directly as real values in their app
+# folder (by the user), never referenced. The skill prints them as
+# "app-native — set directly."

package/blueprints/features/secrets-infisical/files/scripts/infisical-sync.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+#
+# infisical-sync.sh — create/maintain a domain-grouped /shared secret structure
+# in Infisical, with each app/package folder holding ENVIRONMENT-AWARE references.
+#
+# SAFE BY DEFAULT: prints the plan, changes nothing unless APPLY=1.
+# Idempotent. Never prints secret values. Never overwrites existing values.
+# Runs across every environment in ENVIRONMENTS.
+#
+#   APPLY=0 ./scripts/infisical-sync.sh    # dry run (default)
+#   APPLY=1 ./scripts/infisical-sync.sh    # apply to all environments
+#
+# Requires: `infisical login`, a committed .infisical.json in the cwd (run from a
+# dir that has one, e.g. apps/server), and scripts/infisical-map.sh alongside.
+#
+# REFERENCE SYNTAX (the only form that resolves):
+#   ${<env-slug>.shared.<domain>.<KEY>}   e.g. ${dev.shared.core.CORE_DATABASE_URL}
+# The slug MUST match the environment the reference lives in.
+
+set -uo pipefail
+APPLY="${APPLY:-0}"
+PLACEHOLDER="${PLACEHOLDER:-REPLACE_ME}"
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$HERE/infisical-map.sh"   # defines: ENVIRONMENTS, DOMAINS, APP_PATHS,
+                                  # SHARED_MAP, REF_MAP. See infisical-map.sh.
+
+plan() { printf '  %s\n' "$*"; }
+banner() { printf '\n=== %s ===\n' "$*"; }
+
+# REF <domain> <KEY>  -> ${<ENV>.shared.<domain>.<KEY>}   (ENV is the current env slug)
+REF() { printf '${%s.shared.%s.%s}' "$ENV" "$1" "$2"; }
+
+mkfolder() { # parentPath name
+  plan "folder  $1/$2"
+  [ "$APPLY" = 1 ] && infisical secrets folders create \
+    --env "$ENV" --path "$1" --name "$2" --silent >/dev/null 2>&1 || true
+}
+
+# stub <domain> <KEY> [defaultValue]
+# Sets /shared/<domain>/<KEY> to a placeholder ONLY if it has no value yet.
+stub() {
+  local d="$1" k="$2" v="${3:-$PLACEHOLDER}" cur
+  cur="$(infisical secrets get "$k" --env "$ENV" --path "/shared/$d" --plain --silent 2>/dev/null)" || cur=""
+  if [ -n "$cur" ]; then plan "keep    /shared/$d/$k (already set)"; return; fi
+  plan "stub    /shared/$d/$k = $v"
+  [ "$APPLY" = 1 ] && infisical secrets set "$k=$v" --env "$ENV" --path "/shared/$d" --silent >/dev/null 2>&1 || true
+}
+
+# link <appPath> <domain> <KEY>  -> sets KEY=${ENV.shared.domain.KEY} in the app folder
+link() {
+  local app="$1" d="$2" k="$3"
+  plan "ref     ${app}/${k} = $(REF "$d" "$k")"
+  [ "$APPLY" = 1 ] && infisical secrets set "${k}=$(REF "$d" "$k")" \
+    --env "$ENV" --path "$app" --silent >/dev/null 2>&1 || true
+}
+
+printf 'Infisical sync — APPLY=%s%s\n' "$APPLY" \
+  "$([ "$APPLY" = 1 ] && echo '  (LIVE)' || echo '  (dry run — no changes)')"
+
+for ENV in "${ENVIRONMENTS[@]}"; do
+  banner "ENVIRONMENT: $ENV"
+
+  banner "1. Folders ($ENV)"
+  mkfolder /        shared
+  for d in "${DOMAINS[@]}"; do mkfolder /shared "$d"; done
+  for app in "${APP_PATHS[@]}"; do
+    # ensure app/package folders exist (apps/server, apps/web, packages/db, ...)
+    parent="$(dirname "$app")"; name="$(basename "$app")"
+    [ "$parent" = "/" ] || mkfolder "$parent" "$name"
+  done
+
+  banner "2. Shared placeholders ($ENV)"
+  # SHARED_MAP entries look like "domain KEY [optionalDefault]"
+  for entry in "${SHARED_MAP[@]}"; do
+    # shellcheck disable=SC2086
+    stub $entry
+  done
+
+  banner "3. App references ($ENV)"
+  # REF_MAP entries look like "appPath domain KEY"
+  for entry in "${REF_MAP[@]}"; do
+    # shellcheck disable=SC2086
+    link $entry
+  done
+done
+
+printf '\nDone (%s).\n' "$([ "$APPLY" = 1 ] && echo applied || echo 'dry run — re-run with APPLY=1')"

package/dist/index.js

@@ -6,7 +6,7 @@ import pc4 from "picocolors";
 
 // src/constants.ts
 var API_URL = process.env["WITHMATA_API_URL"] || "https://blueprints.withmata.dev";
-var VERSION = "0.7.0";
+var VERSION = "3.0.0";
 
 // src/lib/install-state.ts
 import { existsSync, readdirSync, lstatSync, readlinkSync } from "fs";
@@ -269,7 +269,7 @@ function isBlueprintsRepo(dir) {
 function discoverBlueprints(blueprintsDir) {
   const ids = [];
   if (!existsSync3(blueprintsDir)) return ids;
-  const tiers = ["discovery", "foundation", "features"];
+  const tiers = ["discovery", "foundation", "features", "thinking"];
   for (const tier of tiers) {
     const tierDir = join3(blueprintsDir, tier);
     if (!existsSync3(tierDir)) continue;
@@ -483,6 +483,15 @@ var SKILL_GROUPS = [
         description: "Check project health and find available upgrades"
       }
     ]
+  },
+  {
+    title: "Think",
+    skills: [
+      {
+        command: "/reflect",
+        description: "Run a structured thinking-partner session on any personal topic"
+      }
+    ]
   }
 ];
 function showSummary({

package/package.json

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

package/blueprints/features/env-t3/files/nextjs/.env.example

@@ -1,17 +0,0 @@
-# =============================================================================
-# {{APP_NAME}} — Environment Variables
-# =============================================================================
-# Copy this file to .env.local and fill in the values.
-# Feature blueprints will add their own variables — check their BLUEPRINT.md.
-
-# -----------------------------------------------------------------------------
-# App
-# -----------------------------------------------------------------------------
-
-# Frontend URL (used for redirects, CORS, and metadata)
-# Local: http://localhost:3000 | Production: https://yourdomain.com
-NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
-
-# CONFIGURE: Feature blueprints add variables here:
-# - /scaffold-auth adds: BETTER_AUTH_URL, BETTER_AUTH_SECRET, GOOGLE_CLIENT_ID, etc.
-# - /scaffold-db adds: DATABASE_URL (in packages/db/.env for monorepos)

package/blueprints/features/env-t3/files/server/.env.example

@@ -1,14 +0,0 @@
-# =============================================================================
-# {{APP_NAME}} Server — Environment Variables
-# =============================================================================
-# Copy this file to .env.local and fill in the values.
-
-# -----------------------------------------------------------------------------
-# Server Configuration
-# -----------------------------------------------------------------------------
-
-# Port the server listens on
-# Local: 4000 | Production: Set by hosting platform
-PORT=4000
-
-# CONFIGURE: Add server-specific variables below