@withmata/blueprints 0.5.0 → 3.0.0

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.