qualia-framework 6.8.0 → 6.9.0

package/docs/EMPLOYEE-QUICKSTART.md

@@ -0,0 +1,162 @@
+# Qualia Framework — Employee Quickstart
+
+A five-minute path from a fresh machine to a shipped, reported day of work. This is the route for a **new employee who does not have a team install code yet**. You can install and do real work in employee mode today; the OWNER (Fawzi) issues the keys that unlock ERP reporting and any direct provider integrations.
+
+Who issues credentials: **the OWNER (Fawzi) issues every key** — team install codes, the ERP API key, OpenRouter / Supabase / Vercel / Retell / ElevenLabs / Telnyx credentials. If a step says "ask Fawzi", that is who to ask. Never share or reuse another person's key.
+
+---
+
+## The path
+
+```
+install (employee mode) → /qualia-doctor → /qualia-new (pick preset) → build/verify loop → /qualia-ship → report
+```
+
+---
+
+## 1. Install — employee mode (no team code needed)
+
+```bash
+npx qualia-framework@latest install
+```
+
+At the prompt:
+
+```
+Install code or "EMPLOYEE":
+```
+
+- Have a team code (`QS-NAME-##`)? Enter it — you install as that team member.
+- **No code yet?** Type **`EMPLOYEE`**. You install at the least-privilege role: feature branches only, no pushes to `main` (enforced by the `branch-guard` hook). The full framework — skills, agents, hooks, knowledge — is installed exactly the same.
+
+What employee mode changes vs. a coded install:
+
+| | Coded install (team member) | Employee mode (no code) |
+|---|---|---|
+| Role | OWNER or EMPLOYEE per code | EMPLOYEE |
+| Skills / agents / hooks | full | full |
+| Push to `main` | OWNER only | blocked |
+| ERP reporting | on (with API key) | **off** until a code/key is set |
+| `/qualia-report` | uploads to ERP | saves a **local** report file |
+
+**Credentials this step needs:** none. That's the point — you can start immediately.
+
+To upgrade to a real team identity later: ask Fawzi for your `QS-NAME-##` code, then re-run `npx qualia-framework install` and enter it. That flips ERP reporting back on (you'll also need the ERP API key — see step 6).
+
+### Optional: shared team knowledge mirror
+
+The installer can pull a **read-only** copy of the team's shared knowledge wiki (`qualia-memory`) into `~/.claude/knowledge/shared/` so you start with the team's accumulated patterns and fixes. It is **opt-in and copy-on-install only** — not a live sync.
+
+```bash
+# Local checkout of the knowledge repo:
+QUALIA_KNOWLEDGE_SOURCE=/path/to/qualia-memory npx qualia-framework@latest install
+
+# Or a git URL (ask Fawzi for access if the repo is private):
+QUALIA_KNOWLEDGE_SOURCE=https://github.com/Qualiasolutions/qualia-memory.git \
+  npx qualia-framework@latest install
+```
+
+- `QUALIA_KNOWLEDGE_SOURCE` — a local path **or** a git URL. Unset → the pull is skipped silently.
+- `QUALIA_KNOWLEDGE_SUBPATH` — subdirectory inside the source to copy (default `wiki/_export`).
+- The mirror lands at `~/.claude/knowledge/shared/` with every file marked read-only. Your own learnings still go through `/qualia-learn` into your personal knowledge files — the shared mirror is reference material, refreshed on each install/update.
+- If the source is unreachable (no git, offline, missing path, private-repo auth fail) the installer **warns and continues** — it never blocks the install.
+
+**Credentials this step needs:** read access to the `qualia-memory` repo if you use a private git URL — ask Fawzi.
+
+---
+
+## 2. `/qualia-doctor` — confirm the install is healthy
+
+```
+/qualia-doctor
+```
+
+Checks install integrity, hooks, project state, contracts, memory, and the ERP queue. In employee mode it will report ERP as disabled — that is expected and not an error. Fix anything it flags before starting real work.
+
+**Credentials this step needs:** none.
+
+---
+
+## 3. `/qualia-new` — start a project (pick a preset)
+
+```
+/qualia-new
+```
+
+Runs the kickoff interview, researches the domain, and writes the planning substrate (`JOURNEY.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `CONTEXT.md`). When prompted, pick the project **preset / type** that matches what you're building (e.g. landing page, full app, AI agent, internal tool). The preset seeds the milestone arc so you're not planning from a blank page.
+
+**Credentials this step may need:**
+- `OPENROUTER_API_KEY` — for any AI-assisted research/generation. Ask Fawzi for one.
+- Provider keys (Supabase, Vercel, etc.) are not needed yet — they come in when you wire those services.
+
+---
+
+## 4. Build / verify loop
+
+Plan, build, and verify each phase:
+
+```
+/qualia-plan      # break the current phase into wave-grouped tasks
+/qualia-build     # execute the plan — builders + atomic commits
+/qualia-verify    # goal-backward check against acceptance criteria
+```
+
+Iterate until the phase passes verification. Use `/qualia` at any point to ask "what's my next step?".
+
+**Credentials this step needs:** whatever the feature touches —
+- `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_SERVICE_ROLE_KEY` for database work (service role key is **server-only**, never in client code).
+- `OPENROUTER_API_KEY` for AI calls.
+- Voice keys (`RETELL_API_KEY`, `ELEVENLABS_API_KEY`, `TELNYX_API_KEY`) for voice work.
+
+Pull these into a project with `vercel env pull` once the project is linked. **Ask Fawzi for any key you don't have** — do not invent or hardcode keys, and never commit a `.env` file.
+
+---
+
+## 5. `/qualia-ship` — deploy
+
+```
+/qualia-ship
+```
+
+Runs the quality gates, commits, deploys (Vercel via CLI), and verifies. As an employee you ship through a **feature branch and review** — `branch-guard` blocks direct pushes to `main`. Deploys happen only through the CLI; GitHub auto-deploy is intentionally disabled.
+
+**Credentials this step needs:**
+- A Vercel login on the correct team (`vercel whoami`; `vercel link` if the project isn't linked). Ask Fawzi which Vercel team the project belongs to.
+- Push access to the GitHub repo (org `QualiasolutionsCY` or `SakaniQualia`). Ask Fawzi to be added.
+
+---
+
+## 6. Report — clock out
+
+```
+/qualia-report
+```
+
+Generates your shift report, commits it to `.planning/reports/report-{date}.md`, and (when configured) uploads it to the ERP.
+
+**In employee mode (no team code), the report degrades gracefully:** it is generated and committed **locally**, and you'll see a clear message that it was saved locally because no team code is set. Nothing fails. To start uploading reports to the ERP:
+
+1. Get your team code (`QS-NAME-##`) from Fawzi and re-run `npx qualia-framework install` with it, **and**
+2. Set the ERP API key (ask Fawzi for it):
+   ```bash
+   printf '%s' "$QUALIA_ERP_KEY" | qualia-framework set-erp-key
+   ```
+   Verify with `qualia-framework erp-ping`.
+
+After that, `/qualia-report` uploads automatically and retries on transient ERP outages.
+
+**Credentials this step needs:** a team code + the ERP API key — both issued by Fawzi. Until then, local reports are the expected behavior.
+
+---
+
+## Quick reference
+
+| Need | Command | Issued by |
+|---|---|---|
+| Install with no code | type `EMPLOYEE` at the prompt | — |
+| Team code | re-run install, enter `QS-NAME-##` | Fawzi |
+| ERP API key | `qualia-framework set-erp-key` (piped) | Fawzi |
+| AI model access | `OPENROUTER_API_KEY` | Fawzi |
+| Supabase / Vercel / Voice keys | `vercel env pull` once linked | Fawzi |
+| Shared knowledge mirror | `QUALIA_KNOWLEDGE_SOURCE=... install` | repo access from Fawzi |
+| "What's my next step?" | `/qualia` | — |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.8.0",
+  "version": "6.9.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -52,6 +52,7 @@
     "docs/release.md",
     "docs/changelog-v6.html",
     "docs/onboarding.html",
+    "docs/EMPLOYEE-QUICKSTART.md",
     "CLAUDE.md",
     "AGENTS.md",
     "guide.md",

package/skills/qualia-doctor/SKILL.md

@@ -112,6 +112,61 @@ If the queue fails with `401`, the ERP API key is invalid. Use:
 printf '%s' "$QUALIA_ERP_KEY" | qualia-framework set-erp-key
 ```
 
+## 7. Project Env & Auth Health
+
+Verify the project has the env vars its stack preset requires, and that the CLIs the deploy pipeline needs are logged in. This is the gap that catches "it built fine locally but the deploy has no Supabase keys."
+
+**Read the env contract.** `/qualia-new` writes it per stack preset to `.planning/env.required.json` (fallback `./env.required.json`). It is a JSON array of `{ name, purpose, howToObtain, ownerIssued }`. If neither file exists, print `Env: N/A (no env contract — run /qualia-new to lay down a stack preset)` and skip to CLI auth.
+
+**Check each required var.** A var is PASS if it is present in the process env OR defined (non-empty value) in `.env.local`. Run this from the project root:
+
+```bash
+ENVFILE=".planning/env.required.json"; [ -f "$ENVFILE" ] || ENVFILE="env.required.json"
+if [ -f "$ENVFILE" ]; then
+  node -e '
+    const fs=require("fs");
+    const vars=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));
+    let local="";
+    try { local=fs.readFileSync(".env.local","utf8"); } catch {}
+    const inLocal=(n)=>new RegExp("^\\s*"+n+"\\s*=\\s*\\S","m").test(local);
+    for (const v of vars) {
+      const present = (process.env[v.name] && process.env[v.name].length>0) || inLocal(v.name);
+      if (present) { console.log("PASS  "+v.name); continue; }
+      if (v.ownerIssued) {
+        console.log("FAIL  "+v.name+" — MISSING. Owner-issued: ask the OWNER (Fawzi) for this key, then add it to .env.local");
+      } else {
+        console.log("FAIL  "+v.name+" — MISSING. "+(v.howToObtain||"")+" Then add "+v.name+"=... to .env.local");
+      }
+    }
+  ' "$ENVFILE"
+fi
+```
+
+Print one PASS/FAIL line per var with the **exact** next action:
+- Missing + `ownerIssued: true` → `ask the OWNER (Fawzi) for this key` (no self-serve command — only the OWNER issues it).
+- Missing + `ownerIssued: false` → the var's `howToObtain` string, then `add {NAME}=... to .env.local`.
+- Present → `PASS {NAME}`.
+
+**Check CLI logins.** The deploy pipeline needs these authenticated. Each prints PASS or FAIL with the exact fix:
+
+```bash
+# Vercel — needed for `vercel --prod`
+vercel whoami >/dev/null 2>&1 && echo "PASS  vercel (logged in)" \
+  || echo "FAIL  vercel — not logged in. Fix: vercel login"
+
+# Supabase — CLI present + authenticated (projects list needs auth; version proves install)
+supabase projects list >/dev/null 2>&1 && echo "PASS  supabase (authenticated)" \
+  || { supabase --version >/dev/null 2>&1 \
+       && echo "FAIL  supabase — installed but not authenticated. Fix: supabase login" \
+       || echo "FAIL  supabase — CLI missing. Fix: npm i -g supabase  (or use npx supabase)"; }
+
+# GitHub — needed for push / PRs
+gh auth status >/dev/null 2>&1 && echo "PASS  gh (authenticated)" \
+  || echo "FAIL  gh — not logged in. Fix: gh auth login"
+```
+
+Roll the worst result into the `Env` line of the Output block: all PASS → `PASS`; any owner-issued var missing → `BLOCKED (owner key needed)`; any other FAIL → `DEGRADED`.
+
 ## Output
 
 End with:
@@ -127,10 +182,14 @@ Planning hygiene: ...
 Memory: ...
 Design/UI: ...
 Employee experience: ...
+Env: ...
+CLI auth: ...
 ERP: ...
 Next: ...
 ```
 
+`Env` summarizes section 7's env-var check (PASS / DEGRADED / BLOCKED (owner key needed) / N/A). `CLI auth` summarizes the vercel/supabase/gh login checks (PASS if all three are authenticated, else DEGRADED with the first failing CLI named).
+
 ## Rules
 
 1. Read diagnostics before repair.
@@ -138,3 +197,6 @@ Next: ...
 3. Treat missing contracts as degraded trust, not a project failure.
 4. Prefer reinstall for missing framework files.
 5. Prefer `state.js fix` only for malformed generated state.
+6. **Never print secret values.** The env check reports presence (PASS/FAIL) only — never echo a key's contents.
+7. **Owner-issued vars get the OWNER, not a command.** For a missing `ownerIssued: true` var, the only correct fix is "ask the OWNER (Fawzi) for this key" — never suggest a self-serve way to obtain it (per the no-proxy-approval rule).
+8. Missing env contract is `N/A`, not a failure — it means no stack preset was laid down yet (`/qualia-new`).

package/skills/qualia-new/REFERENCE.md

@@ -84,6 +84,13 @@ User-scoped v1 features:
 Template type: {template_type from config.json}
 If set, use ${QUALIA_TEMPLATES}/projects/{type}.md as the milestone arc starting point.
 
+Stack preset: {stack_id from config.json}
+If .planning/phases.md exists (laid down by the Step 5a stack preset), read it as the
+seed phase plan for Milestone 1 — it is tuned to this stack's archetype. The runnable
+scaffold for this stack is already in the project root, so Milestone 1's foundation
+phase should build ON the scaffold (auth wiring, first migration, first feature),
+not re-scaffold from scratch.
+
 <full_detail>{true if --full-detail, else false}</full_detail>
   - false (default): Milestone 1 gets full phase detail; M2..M{N-1} stay as sketches. Detail fills in when each milestone opens via /qualia-milestone.
   - true: every milestone (M1..Handoff) gets full phase-level detail in ROADMAP.md upfront. Useful when the client wants a fully-committed plan at kickoff.

package/skills/qualia-new/SKILL.md

@@ -124,6 +124,44 @@ If "More questions": re-invoke `/qualia-scope` for additional rounds. Otherwise
 
 From questioning answers, infer type → `website` | `ai-agent` | `voice-agent` | `mobile-app` | `null`. If matched, `cat ${QUALIA_TEMPLATES}/projects/{type}.md` gives suggested milestone arc. Store `template_type` for Step 13.
 
+### Step 5a. Stack Preset Gate + Instantiate (ONE question, then lay down the scaffold)
+
+This is the **only** stack question. It selects one of four preset directories at `${QUALIA_TEMPLATES}/stacks/<id>/` and instantiates it. The preset carries the default tech, the env contract, the seed phase plan, and a runnable starter — so the project begins from a real skeleton, not an empty folder. Skip this step entirely on `--quick` (the quick wizard owns its own minimal layout).
+
+Use **AskUserQuestion** (never a plain-text prompt):
+
+- header: "Stack"
+- question: "What kind of build is this? Pick one — it lays down the starter scaffold and the env it needs."
+- options:
+  - "Landing page" — static marketing site, no database, no auth. (`landing-page`)
+  - "Full app" — authenticated product, Supabase + RLS + database. (`full-app`)
+  - "AI agent" — LLM/chat/voice agent, Supabase + OpenRouter. (`ai-agent`)
+  - "Internal tool" — staff portal, invite-only auth, role-gated. (`internal-tool`)
+
+Map the answer to `STACK_ID` ∈ `{landing-page, full-app, ai-agent, internal-tool}`. Pre-select the option that matches `template_type` from Step 5 if one was detected (`website`→`landing-page`/`full-app`, `ai-agent`/`voice-agent`→`ai-agent`), but the user's pick always wins.
+
+Then instantiate the preset (replace `<id>` with `STACK_ID`):
+
+```bash
+PRESET="${QUALIA_TEMPLATES}/stacks/${STACK_ID}"
+
+# 1. Lay down the starter scaffold into the project root (skeleton, not an app).
+#    -n: never clobber a file the user already created.
+mkdir -p .planning
+cp -Rn "${PRESET}/scaffold/." . 2>/dev/null || true
+
+# 2. Copy the env contract so /qualia-doctor can check it.
+cp "${PRESET}/env.required.json" .planning/env.required.json
+
+# 3. Seed the phase plan from the preset (roadmapper refines it in Step 13).
+cp "${PRESET}/phases.md" .planning/phases.md
+
+# 4. Keep the per-stack Definition-of-Done where verify can find it.
+cp "${PRESET}/verify-checklist.md" .planning/verify-checklist.md
+```
+
+Record the chosen stack in `config.json` (Step 9) as `"stack_id": "${STACK_ID}"`. The seed `phases.md` is the roadmapper's starting point at Step 13 — it reads `.planning/phases.md` (preset plan) alongside `${QUALIA_TEMPLATES}/projects/{template_type}.md` (milestone-arc hint) and the research synthesis, then writes the final ROADMAP.md. The scaffold gives Milestone 1 a real foundation to build on instead of an empty directory.
+
 ### Step 6. Design Direction (frontend only)
 
 - header: "Design"
@@ -212,6 +250,7 @@ git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
   "mode": "interactive",
   "depth": "standard",
   "template_type": "{detected or null}",
+  "stack_id": "{landing-page | full-app | ai-agent | internal-tool}",
   "workflow": {
     "research": true,
     "plan_check": true,
@@ -220,6 +259,8 @@ git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
 }
 ```
 
+`stack_id` is the preset chosen at Step 5a. It tells `/qualia-doctor` which env contract to expect and `/qualia-verify` which per-stack Definition-of-Done to load.
+
 **Note:** `workflow.research` is always `true`. It exists for telemetry but is no longer read as a gate.
 
 ### Step 10. Create DESIGN.md (frontend projects — OKLCH-first)
@@ -421,6 +462,7 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 ## Rules
 
 1. **Project type is the first question, period.** Step 1 (Demo / Full / Quick) is the literal first interaction with the user — even before "what are you building". Every downstream step branches on the answer. Don't skip it, don't infer it, don't ask anything before it.
+1a. **One stack question, then a real scaffold.** Step 5a asks exactly ONE stack-preset question (`landing-page` / `full-app` / `ai-agent` / `internal-tool`) and then instantiates it: copies `scaffold/` into the project (never clobbering existing files), copies `env.required.json` → `.planning/env.required.json`, and copies `phases.md` → `.planning/phases.md`. The project starts from a runnable skeleton, not an empty folder. Skip this step on `--quick`. Record the choice as `config.json.stack_id`.
 2. **AskUserQuestion for every discrete-choice question.** Project type, brownfield gate, design vibe, client type, approval gate, auto-chain — all use the interactive UI. The ONLY free-text question in the kickoff flow is the Step 3 one-line pitch. No plain-text prompts for anything that has a closed set of answers.
 3. **No ad-hoc clarification questioning.** After Step 3 (one-line pitch), the next tool call is `/qualia-scope`. No "let me ask a few quick things first", no "that's too broad, can you clarify". Depth is the scope skill's job — not yours.
 4. **Discovery interview is mandatory.** Step 4 always invokes `/qualia-scope` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 14 for full project.

package/skills/qualia-report/SKILL.md

@@ -126,12 +126,15 @@ fi
 ### Step 6 — Upload to ERP
 
 The full payload-builder + 3-attempt-retry logic lives unchanged from v4 — see the **ERP Upload** section below for the canonical implementation. Behavior summary:
+- **No team code in config (employee mode)** → skip upload, report stays LOCAL only; tell the employee explicitly it was saved locally because no team code is set
 - ERP disabled in config → skip upload with an info line, note local commit
 - API key missing → warn with self-service fix instructions, skip upload
 - 401/422 → permanent failure, no retry, tell employee to ask Fawzi
 - Transient (timeout/5xx) → 3 attempts with 1s/3s/9s backoff
 - Success → "Uploaded as $CLIENT_REPORT_ID (ERP: {uuid})"
 
+**No-team-code degrade (employee mode):** When the framework was installed in employee mode, `.qualia-config.json` has `code: ""` and `erp.enabled: false`. The report is still generated, written to `.planning/reports/report-{date}.md`, and committed locally (Steps 3 + 5). The ERP upload is skipped and the employee is told the report lives locally and how to enable ERP later (get a team code from Fawzi, or `qualia-framework set-erp-key`). This is a clean degrade, not an error.
+
 ### Step 7 — State + closing
 
 ```bash
@@ -148,6 +151,7 @@ node ${QUALIA_BIN}/qualia-ui.js info "Shift report submitted. You can clock out
 
 | Symptom | Likely cause | Self-service fix |
 |---|---|---|
+| "Report saved locally, not uploaded" | No team code (employee-mode install) | Expected — report is committed locally. To upload to ERP, get a team code from Fawzi and re-run `npx qualia-framework install`, or set a key with `qualia-framework set-erp-key` |
 | "Could not allocate report ID" | tracking.json missing/corrupt | `cat .planning/tracking.json` to inspect, or restore from `git checkout HEAD -- .planning/tracking.json` |
 | "ERP API key missing" | `${QUALIA_HOME}/.erp-api-key` empty | `printf '%s' "$QUALIA_ERP_KEY" \| qualia-framework set-erp-key` (ask Fawzi for the key) |
 | "ERP auth failed (401)" | Key revoked or wrong | Ask Fawzi for a fresh key |
@@ -168,6 +172,15 @@ REPORT_FILE=".planning/reports/report-{date}.md"
 SUBMITTED_BY=$(git config user.name || echo "unknown")
 SUBMITTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
+# Team code presence — empty in employee-mode installs. No code → the report
+# can't be attributed to a team member, so it degrades to a local-only report.
+TEAM_CODE=$(node -e "try{const c=JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude/.qualia-config.json','utf8'));process.stdout.write((c.code||'').trim())}catch{}")
+if [ -z "$TEAM_CODE" ] && [ "$DRY_RUN" != "true" ]; then
+  node ${QUALIA_BIN}/qualia-ui.js info "No team code configured (employee mode) — report saved LOCALLY at $REPORT_FILE, not uploaded to the ERP."
+  node ${QUALIA_BIN}/qualia-ui.js info "To enable ERP uploads: get a team code from Fawzi and re-run 'npx qualia-framework install', or 'printf '%s' \"\$QUALIA_ERP_KEY\" | qualia-framework set-erp-key'."
+  ERP_ENABLED="false"
+fi
+
 # Idempotency key — deterministic per (client_report_id, submitted_at). A retry
 # of the same shift report carries the same key, so the ERP can dedupe at the
 # header level in addition to the UPSERT on (project_id, client_report_id).

package/templates/stacks/README.md

@@ -0,0 +1,110 @@
+# Project-Type Stack Presets
+
+These presets turn the question *"what kind of project is this?"* into a runnable
+starting point. When `qualia-new` asks the user to pick a project type, the chosen
+preset supplies the env contract, the phase plan, the Definition-of-Done checklist,
+and a minimal-but-real code scaffold.
+
+This directory installs to `~/.claude/qualia-templates/stacks/` automatically — it
+ships inside the `templates/` tree, which the installer copies wholesale. No
+installer change is required to add or edit a preset.
+
+## The four stacks
+
+| `id`            | What it is                                                         | Database / auth          | AI       | Voice    |
+|-----------------|-------------------------------------------------------------------|--------------------------|----------|----------|
+| `landing-page`  | Static / SSG marketing site. No login, no DB.                     | none                     | none     | none     |
+| `full-app`      | Authenticated product: accounts, roles, dashboard, RLS-everywhere. | Supabase (auth + RLS)    | optional | none     |
+| `ai-agent`      | LLM / chat / tool-calling agent on top of the full-app base.       | Supabase (+ pgvector)    | OpenRouter | optional |
+| `internal-tool` | Staff-only portal / admin tool. Same Supabase base as full-app.    | Supabase (auth + RLS)    | optional | none     |
+
+All stacks default to the Qualia standard: **Next.js 16 (App Router) + React 19 +
+TypeScript + Tailwind + Vercel**, AI via **OpenRouter**, data via **Supabase**.
+
+## Preset contract (every `<id>/` directory has exactly this shape)
+
+```
+templates/stacks/<id>/
+  stack.json            metadata: id, title, description, archetype, defaultStack,
+                        scaffoldEntry, whenToUse
+  env.required.json     array of { name, purpose, howToObtain, ownerIssued }
+  phases.md             the increment / phase plan tuned for this stack
+  verify-checklist.md   the per-stack Definition-of-Done checklist
+  scaffold/             a minimal but REAL runnable starter (MVP, not a full app)
+```
+
+### `stack.json` fields
+
+| Field           | Meaning                                                                             |
+|-----------------|-------------------------------------------------------------------------------------|
+| `id`            | Stack id; must equal the directory name.                                            |
+| `title`         | Human label shown in the `qualia-new` project-type picker.                          |
+| `description`   | One line describing what this stack builds.                                         |
+| `archetype`     | The `references/archetypes/*.md` file whose DoD + Road this stack borrows.           |
+| `defaultStack`  | The default tech string (Next.js / Supabase / OpenRouter / …).                      |
+| `scaffoldEntry` | The file a developer opens first after the scaffold is laid down.                   |
+| `whenToUse`     | A short "pick this when…" sentence to disambiguate from neighbouring stacks.        |
+
+### Stack → archetype mapping (DoD source of truth)
+
+The stack ids are a delivery-facing rename of the archetype ids. The mapping keeps
+`qualia-scope`'s archetype DoD grill and `qualia-doctor`'s env check consistent:
+
+| Stack `id`      | `archetype` (DoD source)        |
+|-----------------|---------------------------------|
+| `landing-page`  | `website`                       |
+| `full-app`      | `web-app`                       |
+| `ai-agent`      | `ai-agent`                      |
+| `internal-tool` | `web-app`                       |
+
+`internal-tool` and `landing-page` reuse `web-app` / `website` DoD respectively;
+their `phases.md` and `verify-checklist.md` narrow that DoD to the stack's shape
+(no public SEO for an internal tool, no auth for a landing page).
+
+### `env.required.json` fields
+
+Each entry is an environment variable the stack needs to run:
+
+| Field         | Meaning                                                                              |
+|---------------|--------------------------------------------------------------------------------------|
+| `name`        | The env var name (e.g. `NEXT_PUBLIC_SUPABASE_URL`).                                  |
+| `purpose`     | Why the stack needs it.                                                              |
+| `howToObtain` | The exact step (or CLI command) to get the value.                                    |
+| `ownerIssued` | `true` if only the OWNER (Fawzi) can issue the key; `false` if self-serve.           |
+
+`ownerIssued: true` vars are ones a developer cannot mint themselves (paid third-party
+API keys: OpenRouter, Retell, ElevenLabs, Telnyx). When such a var is missing,
+`qualia-doctor` prints **"ask the OWNER (Fawzi) for this key"** instead of a self-serve
+fix command.
+
+## How `qualia-new` consumes a preset
+
+After the user picks a project type, `qualia-new`:
+
+1. Resolves the chosen `id` to `templates/stacks/<id>/`.
+2. Copies `env.required.json` → the new project's `.planning/env.required.json`
+   (creating `.planning/` if absent).
+3. Folds `phases.md` into the generated plan as the milestone-arc starting point.
+4. Lays down `scaffold/` into the project root (a runnable skeleton, then the
+   roadmapped phases build on it).
+
+## How `qualia-doctor` consumes a preset
+
+`qualia-doctor` reads `.planning/env.required.json` (falling back to `./env.required.json`)
+and, for each entry:
+
+1. Checks the var is present (in the shell env or in `.env.local`).
+2. Checks the relevant CLI logins: `vercel whoami`, `supabase projects list`
+   (or `supabase --version` for auth), `gh auth status`.
+3. Prints **PASS / FAIL** per item with the EXACT fix command.
+4. For `ownerIssued: true` vars whose value is missing, prints
+   **"ask the OWNER (Fawzi) for this key"** rather than a self-serve command.
+
+## Editing a preset
+
+- Keep the scaffold MVP. A runnable skeleton, not a finished app — the roadmapped
+  phases earn the rest.
+- Keep `env.required.json` accurate. A var that the scaffold does not actually read
+  should not be listed; a var the scaffold needs to boot must be.
+- After editing any JSON, validate it parses:
+  `node -e "require('./templates/stacks/<id>/stack.json')"`.

package/templates/stacks/ai-agent/env.required.json

@@ -0,0 +1,44 @@
+[
+  {
+    "name": "NEXT_PUBLIC_SUPABASE_URL",
+    "purpose": "Supabase project URL — used by both client and server SDKs.",
+    "howToObtain": "Supabase Dashboard → Project Settings → API → Project URL, or `npx supabase projects list`.",
+    "ownerIssued": false
+  },
+  {
+    "name": "NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY",
+    "purpose": "Public (anon/publishable) key for client-side Supabase calls. RLS protects data.",
+    "howToObtain": "Supabase Dashboard → Project Settings → API → Publishable/anon key.",
+    "ownerIssued": false
+  },
+  {
+    "name": "SUPABASE_SERVICE_ROLE_KEY",
+    "purpose": "Server-only service-role key. NEVER NEXT_PUBLIC_, never in a client component.",
+    "howToObtain": "Supabase Dashboard → Project Settings → API → service_role key.",
+    "ownerIssued": false
+  },
+  {
+    "name": "OPENROUTER_API_KEY",
+    "purpose": "Routes every LLM call through OpenRouter — never hardcode a single provider.",
+    "howToObtain": "Issued by Qualia. Ask the OWNER (Fawzi) for a key.",
+    "ownerIssued": true
+  },
+  {
+    "name": "RETELL_API_KEY",
+    "purpose": "Voice agent platform (only if the agent takes/makes phone calls).",
+    "howToObtain": "Issued by Qualia. Ask the OWNER (Fawzi) for a key.",
+    "ownerIssued": true
+  },
+  {
+    "name": "ELEVENLABS_API_KEY",
+    "purpose": "Voice synthesis / cloning / streaming (voice agents only).",
+    "howToObtain": "Issued by Qualia. Ask the OWNER (Fawzi) for a key.",
+    "ownerIssued": true
+  },
+  {
+    "name": "TELNYX_API_KEY",
+    "purpose": "Telephony / SIP for voice-agent phone numbers (voice agents only).",
+    "howToObtain": "Issued by Qualia. Ask the OWNER (Fawzi) for a key.",
+    "ownerIssued": true
+  }
+]

package/templates/stacks/ai-agent/phases.md

@@ -0,0 +1,53 @@
+# AI Agent — Phase Plan
+
+Stack: Next.js 16 (Vercel) · Supabase (Postgres + pgvector) · OpenRouter · Tailwind · Railway (workers, optional).
+Archetype: `ai-agent`. Seed plan copied into ROADMAP.md by `/qualia-new`.
+The differentiator is **Phase 3 — the eval gate**: no ship before evals are green.
+
+## Phase 1: Foundation & Data
+
+**Goal:** Stack deployed to a Vercel preview; Supabase wired with RLS on every table; OpenRouter wired with a model + fallback.
+
+**Success criteria:**
+1. Authenticated user can hit a stubbed endpoint; RLS verified as two users.
+2. Schema: conversations, messages, users (+ pgvector tables if RAG).
+3. OpenRouter wired with a model + fallback chain; secrets in env.
+4. Deploys to a Vercel preview URL.
+
+## Phase 2: Core Agent Loop
+
+**Goal:** A real end-to-end conversation works (input → model → response → persist), with cost/latency logged from the first call.
+
+**Success criteria:**
+1. Streaming chat works end-to-end and persists to Supabase.
+2. System prompt lives in source control — never hardcoded inline.
+3. Tool-calling scaffold present; RAG retrieval if applicable.
+4. Per-request token + latency + cost logged.
+
+## Phase 3: Evals & Guardrails (THE GATE)
+
+**Goal:** The agent passes a measurable eval suite mapped to the success metric. Guardrails handle refusal, fallback, and tool failure.
+
+**Success criteria:**
+1. Eval harness with pass/fail cases mapped to the success metric — green.
+2. Input validation; refusal/safety behavior; fallback on model failure; human-escalation path.
+3. Each tool: server-side validation, timeout + failure handling, idempotency on writes.
+4. Per-request + daily cost ceilings enforced. **No ship before this closes.**
+
+## Phase 4: App Surface & Polish
+
+**Goal:** Auth flows, rate limiting, and a non-AI-looking design pass.
+
+**Success criteria:**
+1. Auth flows + user management + rate limiting.
+2. DESIGN.md anti-slop pass; responsive; all async states incl. streaming.
+3. Product looks built, not generated.
+
+## Phase 5: Handoff
+
+**Goal:** Security review, prod deploy (Vercel + Railway if a worker), real-call smoke, handover.
+
+**Success criteria:**
+1. Secrets/env audit; GDPR posture (consent, retention, export/delete).
+2. Prod deploy; post-deploy smoke includes **real agent calls**, not just HTTP 200.
+3. Credentials, walkthrough, archive, `/qualia-report` to ERP.

package/templates/stacks/ai-agent/scaffold/.env.example

@@ -0,0 +1,12 @@
+# Supabase
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+SUPABASE_SERVICE_ROLE_KEY=
+
+# AI — route ALL LLM calls through OpenRouter. Ask the OWNER (Fawzi) for a key.
+OPENROUTER_API_KEY=
+
+# Voice (only for voice agents). Owner-issued — ask Fawzi.
+# RETELL_API_KEY=
+# ELEVENLABS_API_KEY=
+# TELNYX_API_KEY=

package/templates/stacks/ai-agent/scaffold/README.md

@@ -0,0 +1,31 @@
+# AI Agent
+
+LLM / chat / agent — Next.js 16 + Supabase + OpenRouter (+ optional Retell/ElevenLabs/Telnyx voice).
+
+## Run
+
+```bash
+npm install
+cp .env.example .env.local   # fill Supabase keys + OPENROUTER_API_KEY (ask Fawzi)
+npx supabase db push
+npm run dev                  # http://localhost:3000
+curl -X POST localhost:3000/api/chat -H 'content-type: application/json' \
+  -d '{"message":"hello"}'
+```
+
+## Where things live
+
+- `app/api/chat/route.ts` — the agent endpoint (input validation + routing).
+- `lib/openrouter/client.ts` — the ONLY seam that talks to the LLM. Model + fallback chain here.
+- `lib/prompts/system.ts` — system prompt in source control, never inline.
+- `lib/supabase/server.ts` — server adapter (mutations, RLS).
+- `supabase/migrations/` — conversations + messages, RLS from the first migration.
+- `evals/cases.json` — **the ship gate**. No ship before the suite is green (Phase 3).
+
+## Non-negotiables
+
+- All LLM calls through OpenRouter — never hardcode a provider.
+- Evals are the finish line, not "it replied".
+- `service_role` + `OPENROUTER_API_KEY` server-only, never logged.
+
+This is an MVP skeleton. Build the streaming loop, persistence, and evals per `.planning/ROADMAP.md`.