@withmata/blueprints 0.5.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/design-system/SKILL.md

@@ -949,11 +949,17 @@ Tell the user:
   <link href="https://fonts.googleapis.com/css2?family=..." rel="stylesheet" />
   ```
 - **Tailwind sync status** — whether tokens were synced to the scaffolded `shared-styles.css`, or whether the user needs to run `/scaffold-tailwind` first
-- **Suggested next steps:**
-  - If tailwind is not yet scaffolded: "Run `/scaffold-tailwind` — it will auto-detect your design tokens from `docs/design/shared-styles.css`"
-  - If tailwind is scaffolded but UI is not: "Run `/scaffold-ui` — components will use your custom design tokens"
-  - If both are already scaffolded: "Your design tokens are live. Components will pick up the new palette on next build."
-- **Suggested UI improvements** — based on the design system decisions, note any component-specific suggestions (e.g., "Your round personality would look great with pill-shaped badges — consider updating badge radius if you've already scaffolded UI")
+- **Apply to existing project** — this is the most important post-generation step:
+  - If tailwind is scaffolded: "Want me to apply the new design tokens to your project now? I'll copy `docs/design/shared-styles.css` to `config/tailwind-config/shared-styles.css` (monorepo) or `src/styles/shared-styles.css` (single-repo). Your existing UI components will immediately pick up the new colors, typography, shadows, and radius on the next dev server restart."
+  - If the user confirms, copy the file and report what changed (new colors, new fonts, new shadows, etc.)
+  - If tailwind is NOT scaffolded: "Run `/scaffold-tailwind` — it will auto-detect your design tokens from `docs/design/shared-styles.css` and use them instead of the generic defaults."
+  - If tailwind is scaffolded but UI is not: "Run `/scaffold-ui` — it will auto-install Tailwind first (using your custom tokens) and then scaffold 31 components that inherit your design system."
+  - If both are already scaffolded and tokens were synced: "Your design tokens are live. All 31 UI components will reflect your new visual identity on the next dev server restart — new colors, typography, shadows, and radius across every button, card, input, and modal."
+- **Suggested UI improvements** — based on the design system decisions, note any component-specific suggestions. Be specific:
+  - "Your round personality suggests pill-shaped buttons — the current `rounded-4xl` in button.tsx already matches."
+  - "Consider adjusting card shadows to use the tinted shadow scale for a warmer feel."
+  - "The sidebar tokens now use your brand colors — the sidebar will match the rest of the app."
+  - "Your chosen font needs to be imported — add the Google Fonts link to `layout.tsx`."
 
 ## Important Rules
 

package/.claude/skills/reflect/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: reflect
+description: Run a structured thinking-partner session on any personal topic — life, relationships, career, decisions — and produce a reflection document capturing the journey
+---
+
+# Run a Reflection Session
+
+Run a deep, structured thinking session with the user on any personal topic they bring — relationships, career moves, life direction, family decisions, big purchases, identity questions, anything. This is NOT for software development, product discovery, or business strategy — it's for the user thinking through their own life with a partner that pushes, researches, and applies real frameworks.
+
+The session produces a reflection document that captures the *walkthrough*, not just the conclusion.
+
+## Step 1: Read the Blueprint
+
+Read the full thinking-partner blueprint and all templates:
+
+```
+~/.withmata/blueprints/blueprints/thinking/thinking-partner/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/thinking/thinking-partner/templates/*
+```
+
+If not found, run `npx @withmata/blueprints` to install.
+
+The BLUEPRINT.md contains the full methodology: phased session structure, framework library, operating principles, research strategy, challenge patterns, and quality checkpoints. Follow it precisely.
+
+## Step 2: Check for Prior Reflections
+
+Check whether a `reflections/` folder exists in the current working directory.
+
+- **If it doesn't exist:** This is the user's first session. Note that you'll create the folder when generating the document. Do NOT create `_patterns.md` after a first session.
+- **If it does exist and contains prior reflections:** Read each prior `reflection-*.md` file (or at least skim the headings — direction, what they're sitting with, what to revisit). Also read `_patterns.md` if it exists.
+  - Briefly acknowledge to the user what you noticed: e.g. "I see you've reflected on [topic] before, and a pattern that came up was [X]. Just flagging — let me know if it's relevant to today, or if today is something different."
+  - Do not assume continuity. The user might be here for something completely different.
+
+## Step 3: Open the Session
+
+Open with the Phase 1 questions from the blueprint, in order:
+
+1. "What's on your mind? What do you want to think through?"
+2. "What's the goal here? What would 'figured this out' look like?"
+3. "Why is this the goal? Why now?"
+
+Stay in Phase 1 until the *real* question — not the surface question — has been named. This often takes longer than feels comfortable. That's expected.
+
+## Step 4: Run the Session
+
+Follow the full 5-phase process documented in BLUEPRINT.md. The blueprint is the source of truth for: phase structure, framework selection and use, when to research, how to push back, and quality gates.
+
+Quick reference for the phases:
+1. **Goal & Why** — surface the real question
+2. **Reality & Context** — facts, evidence, surfaced assumptions; auto-research as needed
+3. **Framework Exploration** — apply 2–4 named frameworks chosen for this topic
+4. **Challenge & Steelman** — pre-mortem the chosen path; steelman the rejected path
+5. **Direction & Reflection Document** — only when the user signals readiness
+
+Critical reminders from the blueprint:
+- **Always name the framework you're using** ("I'm going to use Steelmanning here, which means...") — the user is learning these tools.
+- **Auto-research personal topics too** — base rates, what experts actually say, market data, what the research really shows. Don't ask permission.
+- **Recommend when the analysis points somewhere** — don't hide behind "only you can decide." The user takes recommendations as input.
+- **Sessions are not time-boxed** — the user signals when they're done.
+- **Maximum 4 frameworks per session** — two well-applied beats six glancing.
+
+## Step 5: Verify Quality Checkpoints
+
+Before generating the reflection document, verify ALL quality checkpoints listed in BLUEPRINT.md pass. If any fail, keep working — do not rush to generate the document. Specifically:
+
+- The *real* question is named (not just the surface frame)
+- Concrete events have replaced interpretations
+- Major factual claims have been checked, not assumed
+- At least 2 frameworks have been applied and named
+- Both the chosen path AND the rejected path have been pressure-tested
+- The user has articulated direction in their own words
+
+## Step 6: Generate the Reflection Document
+
+Once the user signals readiness AND the quality checkpoints pass:
+
+1. Ask the closing questions:
+   - "What's the direction you're taking from this?"
+   - "What's the *why* in one sentence?"
+   - "What are you going to revisit, and when?"
+
+2. Determine the output path:
+   - Default: `reflections/` in the current working directory
+   - Ask once if the user wants it elsewhere (e.g. `~/journal/reflections/`); remember for the rest of the session
+   - Create the folder if it doesn't exist
+
+3. Generate a topic slug (lowercase, hyphenated, descriptive — e.g. `leaving-current-job`, `whether-to-have-kids`, `how-to-respond-to-mom`).
+
+4. Write the document to:
+   ```
+   reflections/reflection-[topic-slug]-[YYYY-MM-DD].md
+   ```
+
+5. Use `templates/reflection-template.md` from the blueprint as the structural guide. Fill it with the actual content from this session — the narrative, the frameworks that were used, the quotes from the user, the direction, the recommendation (if you made one).
+
+   The reflection document is a NARRATIVE WALKTHROUGH, not a summary. It should read as the story of how the thinking moved. See "Document Quality Checklist" in BLUEPRINT.md.
+
+## Step 7: Update `_patterns.md` (2nd+ session only)
+
+If `reflections/` already contained at least one prior `reflection-*.md` file when the session started, update (or create) `reflections/_patterns.md` using `templates/_patterns.md` as the structural guide.
+
+- **First time creating it (2nd session):** populate from this session + the prior session(s) you read in Step 2.
+- **Updating an existing one:** add to it additively. Don't rewrite. New theme? Add it. New blind spot noticed? Add it. Update "sessions to date", "most recent", and the "Direction History" table.
+
+Be honest in `_patterns.md`. Don't fabricate patterns from a single data point. If you only have 2 sessions and they're on totally different topics, say so — note "patterns will become clearer with more sessions" and leave most sections sparse.
+
+## Step 8: Close
+
+Tell the user:
+
+- Where the reflection document was written (full path)
+- One sentence on what the document captures
+- If `_patterns.md` was created/updated, note that and what was added
+- Remind them: this is their artifact. They can edit it, share it, or revisit it whenever the situation looks different
+
+Do NOT:
+- Suggest a "next blueprint" or "next step" — this is not part of a lifecycle
+- Write to `.project-context.md` — this blueprint is intentionally outside the product-build system
+- Push the user toward another session — let them come back when they want to

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.