qualia-framework 6.8.1 → 6.9.2

package/CHANGELOG.md

@@ -8,6 +8,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Note: git tags for historical versions were not retained; commit references are approximate
 > and dates reflect commit history rather than npm publish timestamps.
 
+## [6.9.2] - 2026-06-20 (docs — visual field manual)
+
+### Added — `docs/qualia-manual.html`
+- A self-contained, single-file introductory **Field Manual** in the Qualia house style (dark + teal `#00FFD1`), shipped in the npm package (`files`). It is the human-friendly visual companion to `docs/EMPLOYEE-QUICKSTART.md`: what the framework is, the plan→build→verify→ship→report loop, employee-mode install, the full command map grouped by purpose, a first-project walkthrough, the five hard rules, the credentials-and-who-issues-them table, and the `/qualia` "when you're lost" escape hatch. Content is grounded in the existing quickstart + skill set — nothing invented. Interactive but dependency-free: sticky scroll-spy nav, click-to-copy command chips, reveal-on-scroll, mobile-responsive, skip-link for a11y. `docs/EMPLOYEE-QUICKSTART.md` now links to it.
+
+## [6.9.1] - 2026-06-16 (fix — stale update banner)
+
+### Fixed — session-start showed a false "update available" banner after catching up
+- `hooks/session-start.js` rendered the cached `.qualia-update-available.json` notice on every session without checking it against the installed version. Because `auto-update.js` only clears that file on its next (throttled) run, the window between an install and that run showed a stale "Current 6.8.1 → Latest 6.9.0" banner even though 6.9.0 was already installed. `maybeRenderUpdateBanner` now validates the notice against `.qualia-config.json` and self-clears (skips render) when the installed version is at or past the advertised `latest`. Regression covered by two new cases in `tests/hooks.test.sh` (stale self-clears; genuine notice preserved).
+
+## [6.9.0] - 2026-06-13 (employee on-ramps — stack presets, employee-mode install, shared knowledge pull)
+
+Implements Part A of the 2026-06-13 restructure plan: turn the framework from an owner-only tool into something a new employee can take idea→deployed without tribal knowledge. **Additive only** — no skill, agent, hook, or rule was rewritten; these are on-ramps built *around* the existing loop.
+
+### Added — project-type stack presets (`templates/stacks/`)
+- **Four presets matching real Qualia work:** `landing-page` (Next.js SSG, no DB), `full-app` (Next.js + Supabase auth/RLS + Tailwind), `ai-agent` (adds OpenRouter + optional Retell/ElevenLabs/Telnyx voice), `internal-tool` (Supabase portal-style auth). Each preset ships `stack.json`, `env.required.json` (`{name, purpose, howToObtain, ownerIssued}`), `phases.md`, `verify-checklist.md`, and a minimal-but-runnable `scaffold/` (full-app/internal-tool include `lib/supabase` server+client adapters and an RLS-from-first-migration `0001_init.sql`; ai-agent adds a `lib/openrouter` adapter + `app/api/chat` route + `evals/`). `templates/stacks/README.md` documents the contract. This kills the "every project gets identical generic phases / no working skeleton" gaps.
+
+### Changed — `/qualia-new` instantiates a preset
+- Adds one project-type question, then lays down the chosen preset's scaffold, folds `phases.md` into the plan, and copies `env.required.json` to the new project's `.planning/env.required.json`. `--quick` skips it. Existing flow otherwise unchanged.
+
+### Changed — `/qualia-doctor` validates the preset's env + CLI auth
+- Reads `.planning/env.required.json` (fallback `./env.required.json`), checks each var (env or `.env.local`) and CLI logins (`vercel`, `supabase`, `gh`), and prints PASS/FAIL with the exact fix command. For `ownerIssued: true` vars it routes to "ask the OWNER (Fawzi)" instead of a self-serve command.
+
+### Added — two-mode install (OWNER / EMPLOYEE)
+- `npx qualia-framework install` accepts the explicit keyword `EMPLOYEE` at the install-code prompt: installs the full framework with **no team code**, `erp.enabled=false`. OWNER/team-code installs are byte-for-byte unchanged, and a genuinely bogus or empty code is still rejected (no silent self-elevation). `/qualia-report` degrades gracefully when no team code is set — it writes a **local** report file and says so, instead of failing. New `docs/EMPLOYEE-QUICKSTART.md` walks install→doctor→new→build/verify→ship→report with the credential each step needs.
+
+### Added — shared knowledge pull (Part C bridge)
+- On install/update the framework pulls a **read-only** copy of the `qualia-memory` vault's sanitized `wiki/_export/` (configurable via `QUALIA_KNOWLEDGE_SOURCE` / `QUALIA_KNOWLEDGE_SUBPATH`, git URL or local path) into the knowledge dir, skipping gracefully when unavailable. Freshness comes from the vault's nightly ERP-report ingest, not sync infra. The export is financial-data-sanitized at the source (see qualia-memory `scripts/export-team-wiki.py`).
+
+### Fixed — test drift
+- `tests/bin.test.sh` (Codex backup discipline #122/#123) now greps the `backups/` subdir, matching the v6.8.1 `bakPath()` relocation. The behavior was correct; the test path was stale.
+
 ## [6.8.1] - 2026-06-10 (installer hygiene — global hook sweep, bin purge, bak routing)
 
 Found via a live audit of an installed `~/.claude`: the retired brain experiment's `brain-inject.js` was still wired under `UserPromptSubmit`, firing a failing node process on every user prompt, and had survived four releases because the settings merge never looked at that event.

package/bin/install.js

@@ -171,6 +171,95 @@ function copyTreeTransform(src, dest, transform) {
   }
 }
 
+// ─── Shared knowledge pull (read-only mirror of qualia-memory) ───
+// Copy-on-install/update only — NOT a sync engine. Pulls a read-only snapshot
+// of the team's shared knowledge wiki into <home>/knowledge/shared/ so every
+// install ships the same accumulated patterns. Source is configurable:
+//   QUALIA_KNOWLEDGE_SOURCE — a local path OR a git URL (https/ssh/file)
+//   QUALIA_KNOWLEDGE_SUBPATH — subdir inside the source to copy (default wiki/_export)
+// Degrades GRACEFULLY: any failure (no git, no network, missing path, private-
+// repo auth fail) warns and continues. Never throws, never exits the installer.
+//
+// Returns { status, detail } for the caller to log. status is one of:
+//   "copied" | "skipped" | "error" (all non-fatal).
+const DEFAULT_KNOWLEDGE_SUBPATH = "wiki/_export";
+
+function copyTreeReadOnly(src, dest) {
+  // Copy a tree and lock every FILE 0o444 — this mirror is read-only; local
+  // edits belong in the user's own knowledge files, not here. Directories stay
+  // writable (0o755) so the next install/update can replace the mirror cleanly
+  // (deleting an entry needs write on its parent dir, not on the entry).
+  if (!fs.existsSync(src)) return 0;
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  let count = 0;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      count += copyTreeReadOnly(s, d);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+      try { fs.chmodSync(d, 0o444); } catch {}
+      count++;
+    }
+  }
+  return count;
+}
+
+function pullSharedKnowledge(knowledgeDest) {
+  const source = (process.env.QUALIA_KNOWLEDGE_SOURCE || "").trim();
+  if (!source) {
+    return { status: "skipped", detail: "QUALIA_KNOWLEDGE_SOURCE not set — shared knowledge pull disabled" };
+  }
+  const subpath = (process.env.QUALIA_KNOWLEDGE_SUBPATH || DEFAULT_KNOWLEDGE_SUBPATH).trim();
+  const sharedDest = path.join(knowledgeDest, "shared");
+  const os = require("os");
+  let tmpClone = null;
+  try {
+    let sourceRoot;
+    const looksGit = /^(https?:\/\/|git@|ssh:\/\/|git:\/\/)/.test(source) || source.endsWith(".git");
+    if (looksGit) {
+      // Shallow clone into a temp dir. spawnSync with argv (no shell) so the
+      // URL can't be misinterpreted. Short timeout — never hang an install.
+      const { spawnSync } = require("child_process");
+      tmpClone = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-knowledge-"));
+      const r = spawnSync("git", ["clone", "--depth", "1", "--quiet", source, tmpClone], {
+        stdio: ["ignore", "ignore", "pipe"],
+        timeout: 30000,
+        encoding: "utf8",
+      });
+      if (r.status !== 0) {
+        const why = (r.stderr || "").trim().split("\n").pop() || `git exited ${r.status}`;
+        return { status: "skipped", detail: `clone failed (${why}) — skipped, continuing` };
+      }
+      sourceRoot = tmpClone;
+    } else {
+      // Local path source.
+      if (!fs.existsSync(source)) {
+        return { status: "skipped", detail: `source path not found: ${source} — skipped, continuing` };
+      }
+      sourceRoot = source;
+    }
+
+    const exportDir = path.join(sourceRoot, subpath);
+    if (!fs.existsSync(exportDir)) {
+      return { status: "skipped", detail: `subpath '${subpath}' absent in source — skipped, continuing` };
+    }
+
+    // Replace the prior mirror wholesale (it's read-only and fully derived).
+    if (fs.existsSync(sharedDest)) {
+      try { fs.rmSync(sharedDest, { recursive: true, force: true }); } catch {}
+    }
+    const n = copyTreeReadOnly(exportDir, sharedDest);
+    return { status: "copied", detail: `${n} file(s) → knowledge/shared/ (read-only mirror)` };
+  } catch (e) {
+    return { status: "error", detail: `${e.message} — skipped, continuing` };
+  } finally {
+    if (tmpClone) { try { fs.rmSync(tmpClone, { recursive: true, force: true }); } catch {} }
+  }
+}
+
 function ensureCodexStatusLineConfig(existing) {
   const statusLine = `status_line = ${JSON.stringify(CODEX_STATUS_LINE)}`;
   const colors = "status_line_use_colors = true";
@@ -448,18 +537,42 @@ function askCode() {
       printHeader();
       const line = nextPipedLine();
       // Echo the prompt + answer for log readability.
-      process.stdout.write(`  ${WHITE}Enter install code:${RESET} ${line}\n`);
+      process.stdout.write(`  ${WHITE}Enter install code (or "EMPLOYEE" for no-code install):${RESET} ${line}\n`);
       resolve(String(line || "").trim());
       return;
     }
     const rl = getRl();
     printHeader();
-    rl.question(`  ${WHITE}Enter install code:${RESET} `, (answer) => {
+    console.log(`  ${DIM}OWNER / team member? Enter your install code (QS-NAME-##).${RESET}`);
+    console.log(`  ${DIM}New employee without a code? Type ${RESET}${TEAL}EMPLOYEE${RESET}${DIM} to install in employee mode.${RESET}`);
+    console.log("");
+    rl.question(`  ${WHITE}Install code or "EMPLOYEE":${RESET} `, (answer) => {
       resolve(String(answer || "").trim());
     });
   });
 }
 
+// ─── Employee mode (no team code) ────────────────────────
+// A new employee may not have a QS-NAME-## code yet. Typing "EMPLOYEE" at the
+// install-code prompt installs the full framework at the least-privilege role:
+// feature branches only, no main pushes (enforced by branch-guard, which trusts
+// the role bit in the 0o600 config). ERP reporting stays OFF until a real team
+// code is set, so /qualia-report degrades to a local-only report.
+//
+// Defaulting to EMPLOYEE (not OWNER) on a missing/keyword code is the secure
+// failure mode: a bogus code that is NOT the EMPLOYEE keyword is still rejected
+// (see main()), so this can't be used to silently self-elevate.
+const EMPLOYEE_KEYWORDS = new Set(["EMPLOYEE", "EMPLOYEE-MODE", "NO-CODE", "NOCODE"]);
+const EMPLOYEE_MEMBER = {
+  name: "Qualia Employee",
+  role: "EMPLOYEE",
+  description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+};
+
+function isEmployeeKeyword(raw) {
+  return EMPLOYEE_KEYWORDS.has(String(raw || "").trim().toUpperCase());
+}
+
 // ─── Prompt for install target (Claude / Codex / Both) ──
 // Backward-compat: a piped install with only the team code (single stdin
 // line) closes stdin before this prompt; we silently default to "1"
@@ -525,12 +638,24 @@ async function main() {
   }
   const rawCode = await askCode();
   const code = resolveTeamCode(rawCode);
-  const member = code ? TEAM[code] : null;
+  let member = code ? TEAM[code] : null;
+
+  // Employee mode: the user typed the EMPLOYEE keyword instead of a team code.
+  // Synthesize a least-privilege EMPLOYEE member. The team code stays empty,
+  // which keeps ERP reporting off (set later via a real code or set-erp-key).
+  const employeeMode = !member && isEmployeeKeyword(rawCode);
+  if (employeeMode) {
+    member = EMPLOYEE_MEMBER;
+  }
 
   if (!member) {
+    // A genuine bad code (not the EMPLOYEE keyword) is still rejected — typing
+    // garbage must never silently install. This preserves the install-code gate
+    // for team members while only the explicit EMPLOYEE keyword bypasses it.
     console.log("");
     log(`${RED}✗${RESET} Invalid code: "${rawCode}". Get your install code from Fawzi.`);
     log(`${DIM}  Tip: codes use digit zero, not letter O. Format: QS-NAME-##${RESET}`);
+    log(`${DIM}  No code yet? Type ${RESET}${TEAL}EMPLOYEE${RESET}${DIM} to install in employee mode.${RESET}`);
     console.log("");
     process.exit(1);
   }
@@ -539,6 +664,9 @@ async function main() {
   const roleColor = member.role === "OWNER" ? TEAL : GREEN;
   console.log(`  ${GREEN}✓${RESET} ${WHITE}${BOLD}Welcome, ${member.name}${RESET}`);
   console.log(`  ${DIM}  Role:${RESET} ${roleColor}${member.role}${RESET}`);
+  if (employeeMode) {
+    console.log(`  ${DIM}  Mode:${RESET} ${YELLOW}employee (no team code) — ERP reporting off until a code is set${RESET}`);
+  }
 
   // ─── Ask install target (Claude / Codex / Both) ────────
   const target = await askTarget();
@@ -552,7 +680,7 @@ async function main() {
   if (!installClaude) {
     // Codex-only path: skip the entire Claude install block. Jump straight
     // to the Codex installer + final summary.
-    await installCodex(member, target);
+    await installCodex(member, target, employeeMode);
     return;
   }
 
@@ -779,6 +907,15 @@ async function main() {
     }
   }
 
+  // ─── Shared knowledge pull (read-only mirror of qualia-memory wiki) ──
+  // Copy-on-install only. Configure with QUALIA_KNOWLEDGE_SOURCE (git URL or
+  // local path). Skips gracefully when unset/unreachable — never blocks install.
+  {
+    const pull = pullSharedKnowledge(knowledgeDest);
+    if (pull.status === "copied") ok(`shared knowledge — ${pull.detail}`);
+    else log(`${DIM}shared knowledge — ${pull.detail}${RESET}`);
+  }
+
   // ─── References (methodology docs loaded by skills at runtime) ────
   printSection("References");
   const refDir = path.join(FRAMEWORK_DIR, "references");
@@ -988,17 +1125,25 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   }
 
   // ─── Save config (for update command) ──────────────────
+  // Employee mode (no team code): code is the empty string, and ERP reporting
+  // is disabled by default — there's no team code to attribute reports to, so
+  // /qualia-report degrades to a local-only report. A real team code (or
+  // `qualia-framework set-erp-key`) flips ERP back on later.
   const configFile = path.join(CLAUDE_DIR, ".qualia-config.json");
   const config = {
-    code,
+    code: code || "",
     installed_by: member.name,
     role: member.role,
     version: require("../package.json").version,
     installed_at: new Date().toISOString().split("T")[0],
     erp: {
-      enabled: true,
+      enabled: !employeeMode,
       url: "https://portal.qualiasolutions.net",
       api_key_file: ".erp-api-key",
+      // Performance-audit telemetry. command_usage (counts) is always on.
+      // capturePrompts records real prompt text for the prompt-quality judge —
+      // written explicitly (not implied) so engineers can see and flip it.
+      capturePrompts: true,
     },
   };
   // mode 0o600: this file holds the role bit (OWNER vs EMPLOYEE) which the
@@ -1134,6 +1279,8 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     "fawzi-approval-guard.js",
     // v5.0 — insights-driven destructive-op + wrong-account guards
     "vercel-account-guard.js", "env-empty-guard.js", "supabase-destructive-guard.js",
+    // performance-audit telemetry capture (UserPromptSubmit)
+    "usage-capture.js",
   ]);
   const isQualiaHookCmd = (cmd) => {
     if (typeof cmd !== "string") return false;
@@ -1197,6 +1344,16 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
         ],
       },
     ],
+    // Performance-audit telemetry — record qualia-command usage + (opt-in)
+    // prompt samples per session for the ERP clock-out payload.
+    UserPromptSubmit: [
+      {
+        matcher: ".*",
+        hooks: [
+          { type: "command", command: nodeCmd("usage-capture.js"), timeout: 5 },
+        ],
+      },
+    ],
   };
 
   // Merge user hooks: strip Qualia-owned commands, preserve everything else.
@@ -1297,7 +1454,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
 
   // ─── Codex (optional second target) ──────────────────────
   if (installCodexTarget) {
-    await installCodex(member, target);
+    await installCodex(member, target, employeeMode);
   }
 
   // ─── Summary ───────────────────────────────────────────
@@ -1378,6 +1535,13 @@ function printSummary({ member, target, claudeInstalled }) {
   console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(shift submission)${RESET}`);
   console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
   console.log("");
+  console.log(
+    `  ${DIM}Telemetry${RESET}      ${DIM}your /qualia command usage + prompt samples feed the team${RESET}`
+  );
+  console.log(
+    `  ${DIM}              performance audit. Opt out:${RESET} ${TEAL}erp.capturePrompts=false${RESET} ${DIM}in ~/.claude/.qualia-config.json${RESET}`
+  );
+  console.log("");
   console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log(`  ${TEAL}${BOLD}Welcome to the future with Qualia.${RESET}`);
   console.log(`  ${DIM2}${RULE}${RESET}`);
@@ -1391,7 +1555,7 @@ function printSummary({ member, target, claudeInstalled }) {
 // Claude install. The only thing intentionally not claimed is a Claude-style
 // persistent statusLine setting; Codex exposes hook status messages today, not
 // an equivalent global status-line command.
-async function installCodex(member, target) {
+async function installCodex(member, target, employeeMode = false) {
   console.log("");
   console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}Codex${RESET}`);
   console.log(`  ${DIM2}${"─".repeat(40)}${RESET}`);
@@ -1480,9 +1644,13 @@ async function installCodex(member, target) {
       version: require("../package.json").version,
       installed_at: new Date().toISOString().split("T")[0],
       erp: {
-        enabled: true,
+        // Employee mode (no team code) leaves ERP off so /qualia-report
+        // degrades to a local-only report instead of failing.
+        enabled: !employeeMode,
         url: "https://portal.qualiasolutions.net",
         api_key_file: ".erp-api-key",
+        // See ~/.claude config above — explicit so engineers can see/flip it.
+        capturePrompts: true,
       },
     };
     atomicWrite(path.join(CODEX_DIR, ".qualia-config.json"), JSON.stringify(codexConfig, null, 2) + "\n", 0o600);
@@ -1604,6 +1772,13 @@ async function installCodex(member, target) {
         if (!fs.existsSync(out)) copyTextTransform(path.join(knowledgeSrc, file), out, codexText);
       }
     }
+    // Shared knowledge mirror (read-only) — same copy-on-install semantics as
+    // the Claude path. Skips gracefully when QUALIA_KNOWLEDGE_SOURCE is unset.
+    {
+      const pull = pullSharedKnowledge(knowledgeDest);
+      if (pull.status === "copied") ok(`shared knowledge — ${pull.detail}`);
+      else log(`${DIM}shared knowledge — ${pull.detail}${RESET}`);
+    }
     copyTextTransform(path.join(FRAMEWORK_DIR, "guide.md"), path.join(CODEX_DIR, "qualia-guide.md"), codexText);
     ok("templates/ + knowledge/ + references/ + guide");
   } catch (e) {

package/bin/report-payload.js

@@ -89,6 +89,16 @@ function buildPayload(options = {}) {
   const latestHarnessEval = harnessEval.latestEval(cwd);
   const workPacket = readLocalWorkPacket(cwd);
 
+  // Performance-audit telemetry captured during the session by the
+  // usage-capture UserPromptSubmit hook. Cleared by /qualia-report after upload.
+  const usagePath = options.usagePath || path.join(cwd, ".planning", ".session-usage.json");
+  const usage = readJson(usagePath, {});
+  const commandUsage =
+    usage && typeof usage.command_usage === "object" && usage.command_usage
+      ? usage.command_usage
+      : {};
+  const promptSamples = Array.isArray(usage.prompt_samples) ? usage.prompt_samples : [];
+
   return {
     project: tracking.project || path.basename(cwd),
     project_id: projectKey,
@@ -118,6 +128,8 @@ function buildPayload(options = {}) {
     gap_cycles: (tracking.gap_cycles || {})[String(phase)] || 0,
     build_count: tracking.build_count || 0,
     deploy_count: tracking.deploy_count || 0,
+    command_usage: commandUsage,
+    prompt_samples: promptSamples,
     deployed_url: tracking.deployed_url || "",
     ...(tracking.session_started_at ? { session_started_at: tracking.session_started_at } : {}),
     ...(tracking.last_pushed_at ? { last_pushed_at: tracking.last_pushed_at } : {}),

package/bin/state.js

@@ -729,6 +729,33 @@ function readNextMilestoneNameFromJourney(milestoneNum) {
   }
 }
 
+// A milestone name is a "placeholder" when it's blank or the literal
+// "Milestone N" fallback that close-milestone historically emitted when
+// tracking.json carried no real name. Placeholders must never beat a real
+// name from JOURNEY.md (observed in ERP reports as {"num":"9","name":"Milestone 9"}).
+function isPlaceholderMilestoneName(name, num) {
+  const trimmed = String(name == null ? "" : name).trim();
+  if (!trimmed) return true;
+  return new RegExp(`^Milestone\\s+${num}$`, "i").test(trimmed);
+}
+
+// Resolve the human name for milestone `num`. Preference order:
+//   1. `candidate` (e.g. tracking.json milestone_name) when it's a real name
+//   2. the `## Milestone N · Name` header in JOURNEY.md
+//   3. the "Milestone N" placeholder — last resort only
+function resolveMilestoneName(num, candidate) {
+  const trimmed = String(candidate == null ? "" : candidate).trim();
+  if (!isPlaceholderMilestoneName(trimmed, num)) return trimmed;
+  const fromJourney = readNextMilestoneNameFromJourney(num);
+  if (fromJourney) return fromJourney;
+  return `Milestone ${num}`;
+}
+
+// Normalize a milestone name for dedupe comparisons.
+function normalizeMilestoneName(name) {
+  return String(name == null ? "" : name).trim().toLowerCase();
+}
+
 function readState() {
   try {
     return fs.readFileSync(STATE_FILE, "utf8");
@@ -2166,7 +2193,9 @@ function cmdCloseMilestone(opts) {
   }
   ensureLifetime(t);
 
-  const closedMilestone = t.milestone || 1;
+  // parseInt — legacy tracking.json files carry milestone as a string ("9"),
+  // which would corrupt `closedMilestone + 1` ("91") and break num dedupe.
+  const closedMilestone = parseInt(t.milestone, 10) || 1;
   if (
     !opts.force &&
     typeof t.lifetime.last_closed_milestone === "number" &&
@@ -2227,9 +2256,13 @@ function cmdCloseMilestone(opts) {
     0,
     (parseInt(t.lifetime && t.lifetime.tasks_completed) || 0) - priorMilestoneTasks
   );
+  // Resolve the REAL milestone name: non-placeholder tracking.json
+  // milestone_name first, then the JOURNEY.md `## Milestone N · Name` header,
+  // and only as a last resort the "Milestone N" placeholder.
+  const milestoneName = resolveMilestoneName(closedMilestone, t.milestone_name);
   const summary = {
     num: closedMilestone,
-    name: t.milestone_name || `Milestone ${closedMilestone}`,
+    name: milestoneName,
     total_phases: parseInt(t.total_phases) || s.phases.length || 0,
     phases_completed: phasesCompleted,
     tasks_completed: tasksCompletedThisMilestone,
@@ -2237,8 +2270,18 @@ function cmdCloseMilestone(opts) {
     closed_at: new Date().toISOString(),
   };
   t.milestones = Array.isArray(t.milestones) ? t.milestones : [];
-  // Idempotency: don't duplicate if the same milestone number is already logged.
-  const existing = t.milestones.findIndex((m) => m && m.num === closedMilestone);
+  // Idempotency + dedupe: update in place when the same milestone number is
+  // already logged (num may be a string in legacy entries), OR when the same
+  // real name is already logged under a different num (renumbering drift —
+  // observed as duplicate names in ERP session_reports.milestones).
+  let existing = t.milestones.findIndex(
+    (m) => m && parseInt(m.num, 10) === closedMilestone
+  );
+  if (existing < 0 && !isPlaceholderMilestoneName(milestoneName, closedMilestone)) {
+    existing = t.milestones.findIndex(
+      (m) => m && normalizeMilestoneName(m.name) === normalizeMilestoneName(milestoneName)
+    );
+  }
   if (existing >= 0) {
     t.milestones[existing] = summary;
   } else {
@@ -2533,13 +2576,35 @@ function cmdBackfillMilestones(opts) {
     };
     closedSummaries.push({ num: row.num, name: row.name, phases: phaseCount });
 
-    const existing = t.milestones.findIndex((mm) => mm && mm.num === row.num);
+    // Match by num first (parseInt — legacy entries store num as a string),
+    // then by normalized real name under a different num (renumbering drift).
+    let existing = t.milestones.findIndex(
+      (mm) => mm && parseInt(mm.num, 10) === row.num
+    );
+    if (existing < 0 && !isPlaceholderMilestoneName(row.name, row.num)) {
+      existing = t.milestones.findIndex(
+        (mm) => mm && normalizeMilestoneName(mm.name) === normalizeMilestoneName(row.name)
+      );
+    }
     if (existing >= 0) {
       // Don't override entries that came from real /qualia-milestone close
       // (they have richer data). Only overwrite previously-backfilled entries.
       if (t.milestones[existing].backfilled) {
         t.milestones[existing] = summary;
         updated++;
+      } else if (
+        isPlaceholderMilestoneName(
+          t.milestones[existing].name,
+          parseInt(t.milestones[existing].num, 10)
+        ) ||
+        parseInt(t.milestones[existing].num, 10) !== row.num
+      ) {
+        // Real close entry but with a placeholder name ("Milestone 9") or a
+        // stale num — repair the identity fields in place, keep the richer
+        // close data (tasks_completed, shipped_url, closed_at).
+        t.milestones[existing].num = row.num;
+        t.milestones[existing].name = row.name;
+        updated++;
       }
     } else {
       t.milestones.push(summary);

package/docs/EMPLOYEE-QUICKSTART.md

@@ -0,0 +1,164 @@
+# 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.
+
+> Prefer a visual tour? Open **[`docs/qualia-manual.html`](./qualia-manual.html)** — the same path as an interactive Field Manual (command map, first-project walkthrough, copy-to-clipboard commands).
+
+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` | — |