qualia-framework 6.9.0 → 6.9.2

package/CHANGELOG.md

@@ -8,6 +8,16 @@ 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.

package/bin/install.js

@@ -1140,6 +1140,10 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       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
@@ -1275,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;
@@ -1338,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.
@@ -1519,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}`);
@@ -1626,6 +1649,8 @@ async function installCodex(member, target, employeeMode = false) {
         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);

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/docs/EMPLOYEE-QUICKSTART.md

@@ -2,6 +2,8 @@
 
 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.
 
 ---

package/docs/erp-contract.md

@@ -377,6 +377,8 @@ Snapshot shape:
 | last_pushed_at | string | optional (v3.6+) | ISO 8601 — distinct from `last_updated` (which fires on local writes too). |
 | build_count | number | optional (v3.6+) | Lifetime build counter. |
 | deploy_count | number | optional (v3.6+) | Lifetime deploy counter. |
+| command_usage | object | optional (v6.9+) | Per-session qualia slash-command histogram, e.g. `{ "qualia-build": 3, "qualia-fix": 1 }`. Captured by the `usage-capture` UserPromptSubmit hook into `.planning/.session-usage.json` and cleared at clock-out. Drives the ERP performance audit's command-usage signal. Defaults to `{}`. |
+| prompt_samples | string[] | optional (v6.9+) | Sampled real engineer prompts for the session (opt-in via `erp.capturePrompts`, default on; internal-only). Fed to the ERP prompt-quality judge. Capped at 60 entries / 8000 chars each. Defaults to `[]`. |
 | client_report_id | string | recommended (v4.0.4+) | Client-side sequential identifier: `QS-REPORT-01`, `QS-REPORT-02`, … per-project. Stable across retries. Preferred dedupe key over the ERP-generated `report_id`; safe to adopt as the ERP's primary report key. |
 | dry_run | boolean | optional (v4.0.4+) | `true` marks a synthetic ping (from `qualia-framework erp-ping`). Receivers should filter these out of production report views. |
 
@@ -393,4 +395,11 @@ All other fields are optional but recommended for complete reporting.
 - API keys are per-user, not per-project
 - Keys expire after 90 days (re-issue via Fawzi)
 - All traffic is HTTPS-only
-- No PII beyond team member names is transmitted
+- **Free-form content:** beyond team member names, the only free-form content
+  transmitted is `prompt_samples` — the engineer's real prompts — and only when
+  `erp.capturePrompts` is enabled (default on). This is disclosed to engineers
+  at install, in their own `.qualia-config.json`, and via a once-per-shift
+  runtime notice; they may opt out at any time. Treat `prompt_samples` as
+  data that **may contain PII**: store it access-controlled, keep it out of
+  third-party sub-processors that aren't covered by the team's data agreement,
+  and honor deletion requests. Every other field is non-PII project metadata.

package/docs/qualia-manual.html

@@ -0,0 +1,396 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Qualia Framework · Field Manual</title>
+<style>
+:root{
+  --bg:#0a0e12; --panel:#11161d; --panel2:#161d26; --border:#1f2937;
+  --text:#d7dee8; --dim:#8b98a8; --faint:#5b6675;
+  --teal:#00FFD1; --teal-dim:#0b8f7d; --amber:#f5b942; --red:#ff5c5c; --green:#4ade80;
+  --mono:'SF Mono',ui-monospace,Consolas,monospace;
+  --sans:-apple-system,'Segoe UI',Roboto,sans-serif;
+  --shadow:0 1px 2px rgba(0,0,0,.4),0 8px 30px rgba(0,0,0,.25);
+  --nav-w:240px;
+}
+*{box-sizing:border-box;margin:0;padding:0}
+html{scroll-behavior:smooth}
+body{
+  background:
+    radial-gradient(900px 500px at 85% -5%,rgba(0,255,209,.06),transparent 60%),
+    radial-gradient(700px 400px at 0% 0%,rgba(0,255,209,.04),transparent 55%),
+    var(--bg);
+  color:var(--text);font:15.5px/1.65 var(--sans);
+  -webkit-font-smoothing:antialiased;
+}
+a{color:var(--teal);text-decoration:none}
+a:hover{text-decoration:underline}
+
+/* skip link (a11y) */
+.skip{position:absolute;left:-999px;top:0;background:var(--teal);color:#04110e;padding:10px 16px;border-radius:0 0 8px 0;font-weight:700;z-index:100}
+.skip:focus{left:0}
+
+/* layout */
+.shell{display:grid;grid-template-columns:var(--nav-w) 1fr;max-width:1180px;margin:0 auto;gap:0}
+nav.side{
+  position:sticky;top:0;align-self:start;height:100vh;overflow-y:auto;
+  padding:30px 18px 40px;border-right:1px solid var(--border);
+}
+nav.side .brand{display:flex;align-items:center;gap:9px;margin-bottom:6px}
+nav.side .hex{color:var(--teal);font-size:20px;line-height:1}
+nav.side .brand b{font-size:15px;letter-spacing:.5px}
+nav.side .brand small{display:block;color:var(--faint);font-size:10.5px;letter-spacing:2px;text-transform:uppercase;margin-top:2px}
+nav.side ol{list-style:none;margin-top:24px;counter-reset:s}
+nav.side li{margin:1px 0}
+nav.side a{
+  display:flex;gap:10px;align-items:baseline;color:var(--dim);font-size:13.5px;
+  padding:7px 10px;border-radius:7px;border-left:2px solid transparent;transition:.15s;
+}
+nav.side a .n{counter-increment:s;color:var(--faint);font-family:var(--mono);font-size:11px;min-width:14px}
+nav.side a:hover{color:var(--text);background:var(--panel);text-decoration:none}
+nav.side a.active{color:var(--teal);background:var(--panel2);border-left-color:var(--teal)}
+nav.side a.active .n{color:var(--teal)}
+
+main{padding:54px 48px 120px;min-width:0}
+
+/* hero */
+.hero{margin-bottom:14px}
+.eyebrow{display:inline-flex;align-items:center;gap:8px;font-family:var(--mono);font-size:11.5px;color:var(--teal);letter-spacing:1.5px;text-transform:uppercase;border:1px solid var(--teal-dim);background:rgba(0,255,209,.05);padding:4px 12px;border-radius:30px;margin-bottom:20px}
+.eyebrow .dot{width:6px;height:6px;border-radius:50%;background:var(--teal);box-shadow:0 0 10px var(--teal)}
+h1{font-size:clamp(30px,5vw,46px);line-height:1.05;letter-spacing:-1.2px;font-weight:800}
+h1 .g{color:var(--teal)}
+.lede{color:var(--dim);font-size:clamp(15px,2vw,18px);max-width:62ch;margin-top:16px;line-height:1.55}
+
+/* sections */
+section{padding-top:64px;scroll-margin-top:24px}
+h2{font-size:24px;letter-spacing:-.4px;font-weight:700;display:flex;align-items:center;gap:12px;margin-bottom:6px}
+h2 .bar{width:26px;height:3px;border-radius:3px;background:var(--teal)}
+.sec-sub{color:var(--dim);margin-bottom:22px;max-width:64ch}
+h3{font-size:16px;font-weight:650;color:#fff;margin:26px 0 10px}
+p{margin:10px 0}
+.dim{color:var(--dim)}
+
+/* panels */
+.panel{background:var(--panel);border:1px solid var(--border);border-radius:14px;padding:22px 24px;margin:16px 0;box-shadow:var(--shadow)}
+.grid{display:grid;gap:16px}
+.g2{grid-template-columns:1fr 1fr}
+.g3{grid-template-columns:repeat(auto-fit,minmax(220px,1fr))}
+
+/* command chip w/ copy */
+code{font-family:var(--mono);font-size:.88em;background:var(--panel2);padding:2px 7px;border-radius:5px;color:var(--teal);border:1px solid var(--border)}
+.cmd{display:inline-flex;align-items:center;gap:8px;font-family:var(--mono);font-size:13px;background:var(--panel2);border:1px solid var(--border);border-radius:8px;padding:6px 8px 6px 12px;color:#cfe;cursor:pointer;transition:.15s;user-select:none}
+.cmd:hover{border-color:var(--teal-dim);background:#13202a}
+.cmd .ico{font-size:11px;color:var(--faint);border-left:1px solid var(--border);padding-left:8px}
+.cmd.copied{border-color:var(--teal);color:var(--teal)}
+.cmd.copied .ico{color:var(--teal)}
+
+pre{background:#0c1218;border:1px solid var(--border);border-left:3px solid var(--teal-dim);border-radius:0 10px 10px 0;padding:16px 18px;margin:14px 0;overflow-x:auto;font-family:var(--mono);font-size:13px;line-height:1.7;color:#b8c4d4}
+pre .c{color:var(--faint)}
+pre .t{color:var(--teal)}
+
+/* lifecycle flow */
+.flow{display:flex;flex-wrap:wrap;gap:10px;align-items:stretch;margin:20px 0}
+.step{flex:1 1 130px;background:var(--panel);border:1px solid var(--border);border-radius:12px;padding:14px 14px;position:relative;transition:.18s;min-width:120px}
+.step:hover{border-color:var(--teal-dim);transform:translateY(-3px)}
+.step .k{font-family:var(--mono);font-size:11px;color:var(--teal);letter-spacing:.5px}
+.step .cmdname{font-weight:700;font-size:14px;margin:6px 0 4px}
+.step .d{font-size:12px;color:var(--dim);line-height:1.45}
+.flow .arrow{display:flex;align-items:center;color:var(--faint);font-size:18px}
+
+/* command reference cards */
+.cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(260px,1fr));gap:14px;margin-top:14px}
+.card{background:var(--panel);border:1px solid var(--border);border-radius:12px;padding:16px 18px;transition:.18s}
+.card:hover{border-color:var(--teal-dim);box-shadow:var(--shadow)}
+.card h4{font-family:var(--mono);font-size:14px;color:var(--teal);margin-bottom:6px}
+.card p{font-size:13px;color:var(--dim);margin:0}
+.group-label{font-family:var(--mono);font-size:11px;letter-spacing:1.5px;text-transform:uppercase;color:var(--faint);margin:26px 0 4px}
+
+/* rules */
+.rule{display:flex;gap:14px;padding:14px 0;border-bottom:1px solid var(--border)}
+.rule:last-child{border-bottom:none}
+.rule .num{flex:0 0 30px;height:30px;border-radius:9px;background:rgba(0,255,209,.08);border:1px solid var(--teal-dim);color:var(--teal);display:flex;align-items:center;justify-content:center;font-weight:700;font-size:13px;font-family:var(--mono)}
+.rule b{color:#fff}
+.rule .why{color:var(--dim);font-size:13.5px;font-style:italic}
+
+/* table */
+table{width:100%;border-collapse:collapse;margin:14px 0;font-size:13.5px}
+th{text-align:left;color:var(--faint);font-weight:600;padding:9px 12px;border-bottom:1px solid var(--border);text-transform:uppercase;font-size:10.5px;letter-spacing:.8px}
+td{padding:10px 12px;border-bottom:1px solid #131a22;vertical-align:top}
+tr:hover td{background:rgba(255,255,255,.012)}
+
+/* callout */
+.note{border-left:3px solid var(--amber);background:rgba(245,185,66,.05);border-radius:0 10px 10px 0;padding:14px 18px;margin:16px 0;font-size:14px}
+.note.teal{border-left-color:var(--teal);background:rgba(0,255,209,.05)}
+.note b{color:#fff}
+
+/* walkthrough */
+.walk{counter-reset:w;margin-top:10px}
+.walk .w{display:flex;gap:16px;padding:16px 0;border-bottom:1px dashed var(--border)}
+.walk .w:last-child{border-bottom:none}
+.walk .wn{counter-increment:w;flex:0 0 36px;height:36px;border-radius:50%;background:var(--panel2);border:1px solid var(--teal-dim);color:var(--teal);display:flex;align-items:center;justify-content:center;font-weight:700;font-family:var(--mono)}
+.walk .wn::before{content:counter(w)}
+.walk .wbody{flex:1}
+.walk .wbody h4{font-size:15px;color:#fff;margin-bottom:3px}
+
+footer{margin-top:80px;padding-top:24px;border-top:1px solid var(--border);color:var(--faint);font-size:12.5px}
+
+/* reveal animation */
+.reveal{opacity:0;transform:translateY(14px);transition:opacity .5s ease,transform .5s ease}
+.reveal.in{opacity:1;transform:none}
+@media(prefers-reduced-motion:reduce){.reveal{opacity:1;transform:none;transition:none}html{scroll-behavior:auto}}
+
+/* mobile */
+.menu-btn{display:none}
+@media(max-width:860px){
+  .shell{grid-template-columns:1fr}
+  nav.side{position:fixed;inset:0 auto 0 0;width:260px;background:var(--bg);z-index:50;transform:translateX(-100%);transition:transform .25s;border-right:1px solid var(--border)}
+  nav.side.open{transform:none;box-shadow:0 0 60px rgba(0,0,0,.6)}
+  main{padding:70px 22px 90px}
+  .menu-btn{display:inline-flex;position:fixed;top:14px;left:14px;z-index:60;align-items:center;gap:8px;background:var(--panel);border:1px solid var(--border);color:var(--teal);font-family:var(--mono);font-size:13px;padding:8px 14px;border-radius:10px;cursor:pointer}
+  .g2,.g3{grid-template-columns:1fr}
+}
+</style>
+</head>
+<body>
+<a class="skip" href="#what">Skip to content</a>
+<button class="menu-btn" aria-label="Toggle navigation" onclick="document.querySelector('nav.side').classList.toggle('open')">☰ Menu</button>
+
+<div class="shell">
+<nav class="side" aria-label="Manual sections">
+  <div class="brand">
+    <span class="hex">⬢</span>
+    <div><b>QUALIA</b><small>Field Manual</small></div>
+  </div>
+  <ol>
+    <li><a href="#what" class="active"><span class="n"></span> What it is</a></li>
+    <li><a href="#loop"><span class="n"></span> The loop</a></li>
+    <li><a href="#install"><span class="n"></span> Install</a></li>
+    <li><a href="#commands"><span class="n"></span> Command map</a></li>
+    <li><a href="#first"><span class="n"></span> Your first project</a></li>
+    <li><a href="#rules"><span class="n"></span> The hard rules</a></li>
+    <li><a href="#keys"><span class="n"></span> Credentials</a></li>
+    <li><a href="#lost"><span class="n"></span> When you're lost</a></li>
+  </ol>
+</nav>
+
+<main id="top">
+  <header class="hero reveal">
+    <span class="eyebrow"><span class="dot"></span> Getting started · v6.9</span>
+    <h1>The Qualia <span class="g">Framework</span>,<br>in one sitting.</h1>
+    <p class="lede">A set of commands that takes you from an <b style="color:#fff">idea</b> to a <b style="color:#fff">shipped, reported</b> piece of work, without needing to memorise how Qualia builds software. You type one command, it tells you the next. This manual is the human-friendly tour of that path.</p>
+  </header>
+
+  <!-- WHAT -->
+  <section id="what" class="reveal">
+    <h2><span class="bar"></span> What it is</h2>
+    <p class="sec-sub">Qualia is an opinionated workflow that lives inside Claude Code (and Codex). It ships a lifecycle of <code>/qualia-*</code> slash commands, plus the guardrails (hooks, rules, and a shared brain) that keep every project consistent and safe.</p>
+    <div class="grid g3">
+      <div class="panel"><h3>🧭 It routes you</h3><p class="dim">Never wonder what's next. <code>/qualia</code> reads your project's state and hands you the exact next command. The framework keeps the map; you keep moving.</p></div>
+      <div class="panel"><h3>🛟 It guards you</h3><p class="dim">Deterministic hooks block the dangerous stuff (pushing to <code>main</code>, leaking secrets, destructive DB ops) before it happens. Rules aren't suggestions; they're enforced.</p></div>
+      <div class="panel"><h3>🧠 It remembers</h3><p class="dim">Lessons from every project flow into a shared knowledge base. A fix one person discovered shows up in everyone's install, so the team gets smarter over time.</p></div>
+    </div>
+    <div class="note teal"><b>The one-line mental model:</b> you describe <em>what</em> you want; the framework owns <em>how</em> Qualia builds it: the stack, the phases, the quality bar, the deploy steps.</div>
+  </section>
+
+  <!-- LOOP -->
+  <section id="loop" class="reveal">
+    <h2><span class="bar"></span> The loop</h2>
+    <p class="sec-sub">Every project walks the same path. You don't have to remember it (<code>/qualia</code> always points to the right step), but seeing it once makes everything click.</p>
+    <div class="flow">
+      <div class="step"><div class="k">START</div><div class="cmdname">/qualia-new</div><div class="d">Kickoff interview → pick a project preset → planning files written.</div></div>
+      <div class="arrow">→</div>
+      <div class="step"><div class="k">PLAN</div><div class="cmdname">/qualia-plan</div><div class="d">Break the current phase into small, wave-grouped tasks.</div></div>
+      <div class="arrow">→</div>
+      <div class="step"><div class="k">BUILD</div><div class="cmdname">/qualia-build</div><div class="d">Fresh builder agents execute the tasks, one atomic commit each.</div></div>
+      <div class="arrow">→</div>
+      <div class="step"><div class="k">VERIFY</div><div class="cmdname">/qualia-verify</div><div class="d">Goal-backward check that it actually works, not just that code ran.</div></div>
+      <div class="arrow">→</div>
+      <div class="step"><div class="k">SHIP</div><div class="cmdname">/qualia-ship</div><div class="d">Quality gates → commit → deploy to Vercel → verify live.</div></div>
+      <div class="arrow">→</div>
+      <div class="step"><div class="k">REPORT</div><div class="cmdname">/qualia-report</div><div class="d">Clock out, then generate your shift report and file it.</div></div>
+    </div>
+    <p class="dim">Plan → Build → Verify repeats per phase until the milestone is done. <code>/qualia-polish</code> slots in before shipping when the work is visual.</p>
+  </section>
+
+  <!-- INSTALL -->
+  <section id="install" class="reveal">
+    <h2><span class="bar"></span> Install in employee mode</h2>
+    <p class="sec-sub">You can install and do real work <b>today</b>, with no credentials. Employee mode gives you the full framework at the safest privilege level: feature branches only, no pushes to <code>main</code>.</p>
+    <pre><span class="c"># one command, works on a fresh machine</span>
+npx qualia-framework@latest install</pre>
+    <p>At the prompt <code>Install code or "EMPLOYEE":</code></p>
+    <table>
+      <tr><th>If you…</th><th>Type</th><th>You get</th></tr>
+      <tr><td>Have a team code</td><td><code>QS-NAME-##</code></td><td>Install as that team member (ERP reporting on, with the key)</td></tr>
+      <tr><td>Have no code yet</td><td><code>EMPLOYEE</code></td><td>Full framework, EMPLOYEE role, ERP reporting off until a code is set</td></tr>
+    </table>
+    <div class="note"><b>Nothing is missing in employee mode.</b> Skills, agents, hooks, and knowledge are installed identically. The only differences: you can't push to <code>main</code> (the <code>branch-guard</code> hook blocks it), and <code>/qualia-report</code> saves a <em>local</em> report instead of uploading to the ERP. Ask Fawzi for a <code>QS-NAME-##</code> code when you're ready to upgrade.</div>
+    <h3>Then confirm it's healthy</h3>
+    <p>Run the doctor before real work. It checks the install, hooks, project state, and the ERP queue, and prints PASS/FAIL with the exact fix for anything wrong.</p>
+    <p><span class="cmd" data-copy="/qualia-doctor">/qualia-doctor<span class="ico">copy</span></span> <span class="dim">in employee mode it reports ERP as disabled; that's expected, not an error.</span></p>
+  </section>
+
+  <!-- COMMANDS -->
+  <section id="commands" class="reveal">
+    <h2><span class="bar"></span> The command map</h2>
+    <p class="sec-sub">You won't use all of these on day one. The lifecycle six (the loop above) cover most work; the rest are there when you need them. Click any command to copy it.</p>
+
+    <div class="group-label">◆ Orient · where am I, what now</div>
+    <div class="cards">
+      <div class="card"><h4 data-copy="/qualia">/qualia</h4><p>The router. Reads your state, tells you the single next command. When in doubt, run this.</p></div>
+      <div class="card"><h4 data-copy="/qualia-idk">/qualia-idk</h4><p>Deep "I don't know what's going on" diagnostic. Plain-language guidance + a paste-ready command sequence.</p></div>
+      <div class="card"><h4 data-copy="/qualia-map">/qualia-map</h4><p>Inherited an existing codebase? Map it first (architecture, stack, conventions) before <code>/qualia-new</code>.</p></div>
+    </div>
+
+    <div class="group-label">◆ Build · idea to working code</div>
+    <div class="cards">
+      <div class="card"><h4 data-copy="/qualia-new">/qualia-new</h4><p>Start a project. Interview, research, planning substrate, pick a preset.</p></div>
+      <div class="card"><h4 data-copy="/qualia-scope">/qualia-scope</h4><p>Adversarial intake that grills the requirements before you plan, so v1 is the right v1.</p></div>
+      <div class="card"><h4 data-copy="/qualia-plan">/qualia-plan</h4><p>Break the current phase into wave-grouped, verifiable tasks.</p></div>
+      <div class="card"><h4 data-copy="/qualia-build">/qualia-build</h4><p>Execute the plan with fresh builder agents and atomic per-task commits.</p></div>
+      <div class="card"><h4 data-copy="/qualia-feature">/qualia-feature</h4><p>One small thing (1–5 files), auto-scoped. Skips the full phase machinery.</p></div>
+      <div class="card"><h4 data-copy="/qualia-fix">/qualia-fix</h4><p>Something's broken. Root-cause investigation, then a targeted repair.</p></div>
+    </div>
+
+    <div class="group-label">◆ Check & ship · make it real</div>
+    <div class="cards">
+      <div class="card"><h4 data-copy="/qualia-verify">/qualia-verify</h4><p>Goal-backward verification against acceptance criteria + design rubric.</p></div>
+      <div class="card"><h4 data-copy="/qualia-test">/qualia-test</h4><p>Write or run tests; <code>--tdd</code> drives a feature test-first.</p></div>
+      <div class="card"><h4 data-copy="/qualia-polish">/qualia-polish</h4><p>Visual quality pass: component, route, whole app, or a vibe pivot.</p></div>
+      <div class="card"><h4 data-copy="/qualia-review">/qualia-review</h4><p>Read-only production audit, severity-scored.</p></div>
+      <div class="card"><h4 data-copy="/qualia-ship">/qualia-ship</h4><p>Full deploy pipeline: gates → commit → deploy → verify live.</p></div>
+    </div>
+
+    <div class="group-label">◆ Maintain · close the loop</div>
+    <div class="cards">
+      <div class="card"><h4 data-copy="/qualia-report">/qualia-report</h4><p>Clock out. Generate and file your shift report (uploads to ERP when configured).</p></div>
+      <div class="card"><h4 data-copy="/qualia-learn">/qualia-learn</h4><p>Save a lesson, pattern, or client preference to the shared brain.</p></div>
+      <div class="card"><h4 data-copy="/qualia-milestone">/qualia-milestone</h4><p>Close the current milestone and open the next from the journey map.</p></div>
+      <div class="card"><h4 data-copy="/qualia-doctor">/qualia-doctor</h4><p>Health check the framework when something feels off.</p></div>
+    </div>
+  </section>
+
+  <!-- FIRST PROJECT -->
+  <section id="first" class="reveal">
+    <h2><span class="bar"></span> Your first project</h2>
+    <p class="sec-sub">A landing page, start to finish. The same shape works for anything bigger: just more Plan → Build → Verify loops.</p>
+    <div class="walk">
+      <div class="w"><span class="wn"></span><div class="wbody">
+        <h4>Install &amp; check</h4>
+        <p class="dim">Run <code>npx qualia-framework@latest install</code> (type <code>EMPLOYEE</code>), then <span class="cmd" data-copy="/qualia-doctor">/qualia-doctor<span class="ico">copy</span></span>. Green across the board? Go.</p>
+      </div></div>
+      <div class="w"><span class="wn"></span><div class="wbody">
+        <h4>Start the project</h4>
+        <p class="dim"><span class="cmd" data-copy="/qualia-new">/qualia-new<span class="ico">copy</span></span>: answer the short interview, and when asked, pick the <b>landing-page</b> preset. You now have a running skeleton and a phase plan, not a blank page.</p>
+      </div></div>
+      <div class="w"><span class="wn"></span><div class="wbody">
+        <h4>Plan → Build → Verify</h4>
+        <p class="dim">Walk the phase: <span class="cmd" data-copy="/qualia-plan">/qualia-plan<span class="ico">copy</span></span> <span class="cmd" data-copy="/qualia-build">/qualia-build<span class="ico">copy</span></span> <span class="cmd" data-copy="/qualia-verify">/qualia-verify<span class="ico">copy</span></span>. Repeat until verify passes. Stuck between steps? <code>/qualia</code>.</p>
+      </div></div>
+      <div class="w"><span class="wn"></span><div class="wbody">
+        <h4>Polish the look</h4>
+        <p class="dim">Landing pages live or die on design. <span class="cmd" data-copy="/qualia-polish">/qualia-polish<span class="ico">copy</span></span> runs a visual quality pass against the design rubric.</p>
+      </div></div>
+      <div class="w"><span class="wn"></span><div class="wbody">
+        <h4>Ship it</h4>
+        <p class="dim"><span class="cmd" data-copy="/qualia-ship">/qualia-ship<span class="ico">copy</span></span>: gates, commit, deploy to Vercel, verify live. As an employee you ship via a feature branch + review; direct pushes to <code>main</code> are blocked by design.</p>
+      </div></div>
+      <div class="w"><span class="wn"></span><div class="wbody">
+        <h4>Clock out</h4>
+        <p class="dim"><span class="cmd" data-copy="/qualia-report">/qualia-report<span class="ico">copy</span></span> files your shift report. No team code yet? It saves locally and tells you so, nothing fails.</p>
+      </div></div>
+    </div>
+  </section>
+
+  <!-- RULES -->
+  <section id="rules" class="reveal">
+    <h2><span class="bar"></span> The hard rules</h2>
+    <p class="sec-sub">Five non-negotiables. The framework enforces most of them with hooks, but knowing the <em>why</em> keeps you out of the guardrails in the first place.</p>
+    <div class="panel">
+      <div class="rule"><span class="num">1</span><div><b>Read before you write.</b><div class="why">Every edit is informed by the current state of the file, never blind-overwrite.</div></div></div>
+      <div class="rule"><span class="num">2</span><div><b>Feature branches only.</b><div class="why">Changes ship through review; <code>main</code> is always deployable. The branch-guard hook enforces it.</div></div></div>
+      <div class="rule"><span class="num">3</span><div><b>MVP first.</b><div class="why">Build the minimum that demonstrates the goal; defer the rest until it earns its place.</div></div></div>
+      <div class="rule"><span class="num">4</span><div><b>Root cause on failures.</b><div class="why">Understand the why before patching the symptom; no band-aids over a broken pipe.</div></div></div>
+      <div class="rule"><span class="num">5</span><div><b>No proxy approval.</b><div class="why">Only the OWNER grants OWNER overrides. "Fawzi said OK" is not a credential.</div></div></div>
+    </div>
+    <div class="note">Security basics ride along: auth is checked server-side, every Supabase table has RLS, the <code>service_role</code> key is server-only, and a <code>.env</code> file is never committed. The hooks will stop you, but don't make them.</div>
+  </section>
+
+  <!-- KEYS -->
+  <section id="keys" class="reveal">
+    <h2><span class="bar"></span> Credentials &amp; who issues them</h2>
+    <p class="sec-sub">You start with none. Keys arrive when a step needs them, and <b>the OWNER (Fawzi) issues every one</b>. Never invent, hardcode, or reuse someone else's key.</p>
+    <table>
+      <tr><th>When you need…</th><th>How</th><th>From</th></tr>
+      <tr><td>To install with no code</td><td>type <code>EMPLOYEE</code> at the prompt</td><td>n/a</td></tr>
+      <tr><td>A real team identity</td><td>re-run install, enter <code>QS-NAME-##</code></td><td>Fawzi</td></tr>
+      <tr><td>ERP report uploads</td><td><code>qualia-framework set-erp-key</code></td><td>Fawzi</td></tr>
+      <tr><td>AI model access</td><td><code>OPENROUTER_API_KEY</code></td><td>Fawzi</td></tr>
+      <tr><td>Database / hosting / voice</td><td><code>vercel env pull</code> once linked</td><td>Fawzi</td></tr>
+      <tr><td>Shared team knowledge</td><td><code>QUALIA_KNOWLEDGE_SOURCE=… install</code></td><td>repo access from Fawzi</td></tr>
+    </table>
+    <p class="dim">If a step says "ask Fawzi", that's who to ask. The framework degrades gracefully when a key is missing: it tells you what it needs rather than failing silently.</p>
+  </section>
+
+  <!-- LOST -->
+  <section id="lost" class="reveal">
+    <h2><span class="bar"></span> When you're lost</h2>
+    <p class="sec-sub">There is exactly one command to remember when nothing else makes sense.</p>
+    <div class="panel" style="text-align:center;padding:34px">
+      <span class="cmd" data-copy="/qualia" style="font-size:18px;padding:12px 16px 12px 22px">/qualia<span class="ico" style="font-size:13px">copy</span></span>
+      <p class="dim" style="margin-top:16px;max-width:52ch;margin-inline:auto">It reads where your project is and tells you the precise next move. If you only ever memorise one thing from this manual, memorise this. For a deeper "something feels off" read, use <code>/qualia-idk</code>.</p>
+    </div>
+  </section>
+
+  <footer>
+    <p>Qualia Framework · Field Manual · Qualia Solutions, Nicosia 🇨🇾 · a web/AI agency.<br>
+    The framework is the source of truth; if this manual and a command ever disagree, the command wins. Built to be read once and kept nearby.</p>
+  </footer>
+</main>
+</div>
+
+<script>
+(function(){
+  // ── copy-to-clipboard on any [data-copy] (command chips & cards) ──
+  function flash(el, label){
+    var prev = el.querySelector('.ico');
+    el.classList.add('copied');
+    if(prev){ var t=prev.textContent; prev.textContent='copied ✓'; setTimeout(function(){prev.textContent=t;el.classList.remove('copied');},1100); }
+    else { setTimeout(function(){el.classList.remove('copied');},1100); }
+  }
+  document.querySelectorAll('[data-copy]').forEach(function(el){
+    el.style.cursor='pointer';
+    el.setAttribute('title','Click to copy');
+    el.addEventListener('click',function(){
+      var txt = el.getAttribute('data-copy');
+      navigator.clipboard && navigator.clipboard.writeText(txt).then(function(){flash(el);}).catch(function(){flash(el);});
+    });
+  });
+
+  // ── scroll-spy: highlight the active nav link ──
+  var links = Array.prototype.slice.call(document.querySelectorAll('nav.side a'));
+  var map = {};
+  links.forEach(function(a){ map[a.getAttribute('href').slice(1)] = a; });
+  var spy = new IntersectionObserver(function(entries){
+    entries.forEach(function(e){
+      if(e.isIntersecting){
+        links.forEach(function(a){a.classList.remove('active');});
+        var a = map[e.target.id]; if(a) a.classList.add('active');
+      }
+    });
+  },{rootMargin:'-45% 0px -50% 0px',threshold:0});
+  document.querySelectorAll('section[id]').forEach(function(s){spy.observe(s);});
+
+  // close mobile nav on link tap
+  links.forEach(function(a){a.addEventListener('click',function(){document.querySelector('nav.side').classList.remove('open');});});
+
+  // ── reveal on scroll ──
+  var rev = new IntersectionObserver(function(entries){
+    entries.forEach(function(e){ if(e.isIntersecting){ e.target.classList.add('in'); rev.unobserve(e.target);} });
+  },{rootMargin:'0px 0px -10% 0px',threshold:.08});
+  document.querySelectorAll('.reveal').forEach(function(el){rev.observe(el);});
+})();
+</script>
+</body>
+</html>

package/hooks/session-start.js

@@ -167,17 +167,37 @@ function maybeDrainErpQueue() {
   } catch {}
 }
 
+function cmpVersions(a, b) {
+  // Returns >0 if a>b, <0 if a<b, 0 if equal. Tolerates missing/non-numeric
+  // segments by treating them as 0. Pure semver-major.minor.patch compare.
+  const pa = String(a || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
 function maybeRenderUpdateBanner() {
   // EMPLOYEE-only sticky banner. auto-update.js writes NOTIF_FILE when a new
   // version is detected; we render it every session until the user actually
-  // runs `npx qualia-framework@latest install`. The file is cleared by
-  // auto-update.js once the install completes or the version catches up.
+  // runs `npx qualia-framework@latest install`. auto-update.js clears the file
+  // when it next runs and finds the version caught up — but it is throttled, so
+  // between an install and that next run the notif can be stale. We therefore
+  // self-validate here against the installed version (.qualia-config.json) and
+  // clear+skip a stale notice rather than show a false "update available".
   if (!fs.existsSync(NOTIF_FILE) || !fs.existsSync(UI)) return;
   try {
     const notif = JSON.parse(fs.readFileSync(NOTIF_FILE, "utf8"));
-    if (notif && notif.current && notif.latest) {
-      runUi("update", notif.current, notif.latest);
+    if (!notif || !notif.current || !notif.latest) return;
+    const installed = readConfig().version;
+    if (installed && cmpVersions(installed, notif.latest) >= 0) {
+      // Already at or past the advertised latest — the notice is stale.
+      try { fs.unlinkSync(NOTIF_FILE); } catch {}
+      return;
     }
+    runUi("update", notif.current, notif.latest);
   } catch {}
 }
 

package/hooks/usage-capture.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — per-session framework-usage capture.
+ *
+ * Records, into `.planning/.session-usage.json` of the active project:
+ *   - command_usage : a histogram of qualia slash-commands the engineer fired
+ *   - prompt_samples: the engineer's real prompts (opt-in), for the ERP
+ *                     prompt-quality judge
+ *
+ * `report-payload.js` folds both into the /qualia-report clock-out payload, and
+ * `/qualia-report` clears the file after a successful upload. This is what feeds
+ * the ERP performance audit's "framework usage & prompting" pillar (command
+ * volume + diversity, and LLM-judged prompt quality).
+ *
+ * Privacy: prompt capture is opt-in via `erp.capturePrompts` in
+ * ~/.claude/.qualia-config.json (default ON for the internal team; set to false
+ * to record command counts only). The file is a .planning dotfile and is
+ * deleted at clock-out — it must never be committed.
+ *
+ * Never blocks: any error exits 0 with no stdout (adds no context to the prompt).
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MAX_SAMPLES = 60;
+const MAX_SAMPLE_LEN = 8000;
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function capturePromptsEnabled(home) {
+  const cfg =
+    readJson(path.join(home, '.claude', '.qualia-config.json'), null) ||
+    readJson(path.join(home, '.codex', '.qualia-config.json'), {});
+  return !cfg || !cfg.erp || cfg.erp.capturePrompts !== false;
+}
+
+function main() {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf8');
+  } catch {
+    process.exit(0);
+  }
+  let input = {};
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+  const cwd = input.cwd || input.cwd_path || process.cwd();
+  if (!prompt.trim()) process.exit(0);
+
+  // Only record inside a Qualia project (has .planning/).
+  const planningDir = path.join(cwd, '.planning');
+  if (!fs.existsSync(planningDir)) process.exit(0);
+
+  const usageFile = path.join(planningDir, '.session-usage.json');
+  const usage = readJson(usageFile, { command_usage: {}, prompt_samples: [] });
+  if (!usage.command_usage || typeof usage.command_usage !== 'object') usage.command_usage = {};
+  if (!Array.isArray(usage.prompt_samples)) usage.prompt_samples = [];
+
+  // Count a qualia slash-command if one appears as a token in the prompt.
+  const m = prompt.match(/(?:^|\s)\/(qualia[a-z0-9-]*)/i);
+  if (m) {
+    const cmd = m[1].toLowerCase();
+    usage.command_usage[cmd] = (usage.command_usage[cmd] || 0) + 1;
+  }
+
+  // Sample the real prompt for the prompt-quality judge (opt-in, disclosed).
+  if (capturePromptsEnabled(os.homedir())) {
+    // Transparency: tell the engineer once per shift that prompts are recorded
+    // and how to turn it off. stderr so it's seen but never enters model
+    // context. The flag rides in the usage file, which is cleared at clock-out,
+    // so the notice reappears each new shift. Best-effort — never blocks.
+    if (!usage.notice_shown) {
+      try {
+        process.stderr.write(
+          '\x1b[38;2;80;90;100m[qualia] This session records your /qualia command usage and ' +
+          'prompt samples for the team performance audit. Opt out anytime: set ' +
+          'erp.capturePrompts=false in ~/.claude/.qualia-config.json\x1b[0m\n'
+        );
+      } catch { /* never block the prompt */ }
+      usage.notice_shown = true;
+    }
+    usage.prompt_samples.push(prompt.trim().slice(0, MAX_SAMPLE_LEN));
+    if (usage.prompt_samples.length > MAX_SAMPLES) {
+      usage.prompt_samples = usage.prompt_samples.slice(-MAX_SAMPLES);
+    }
+  }
+
+  try {
+    fs.writeFileSync(usageFile, JSON.stringify(usage));
+  } catch {
+    /* best-effort; never block the prompt */
+  }
+  process.exit(0);
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.9.0",
+  "version": "6.9.2",
   "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/qualia-manual.html",
     "docs/EMPLOYEE-QUICKSTART.md",
     "CLAUDE.md",
     "AGENTS.md",

package/skills/qualia-report/SKILL.md

@@ -230,6 +230,9 @@ if [ "$ERP_ENABLED" = "true" ]; then
     if [ "$HTTP_CODE" = "200" ]; then
       ERP_REPORT_ID=$(echo "$BODY" | node -e "try{process.stdout.write(JSON.parse(require('fs').readFileSync(0,'utf8')).report_id||'')}catch{}")
       node ${QUALIA_BIN}/qualia-ui.js ok "Uploaded as $CLIENT_REPORT_ID (ERP: ${ERP_REPORT_ID:-none})"
+      # Reset per-session usage telemetry (command_usage + prompt_samples) now
+      # that it has been delivered, so the next shift starts from a clean slate.
+      rm -f .planning/.session-usage.json 2>/dev/null
       break
     fi
     if [ "$HTTP_CODE" = "401" ] || [ "$HTTP_CODE" = "422" ]; then

package/templates/planning.gitignore

@@ -8,3 +8,6 @@ tracking.json
 .state.journal
 .backup/
 migration-manifest.json
+# Performance-audit telemetry buffer. Holds the engineer's real prompt samples
+# until clock-out — must NEVER be committed (raw prompt text, may contain PII).
+.session-usage.json

package/tests/bin.test.sh

@@ -487,14 +487,15 @@ else
   fail_case "CLAUDE.md role substitution"
 fi
 
-# 31. All 13 hooks installed (block-env-edit removed in v3.2.0;
+# 31. All 14 hooks installed (block-env-edit removed in v3.2.0;
 # git-guardrails + stop-session-log added in v4.2.0;
 # vercel-account-guard + env-empty-guard + supabase-destructive-guard added in v5.0.0;
 # fawzi-approval-guard added in v6.2.11; pre-compact removed in v6.2.0 and
-# REINTRODUCED in v6.3.2 with sidecar-snapshot mechanism)
+# REINTRODUCED in v6.3.2 with sidecar-snapshot mechanism;
+# usage-capture added in v6.9.1 — UserPromptSubmit telemetry capture)
 HOOK_COUNT=$(ls "$TMP/.claude/hooks/"*.js 2>/dev/null | wc -l)
-if [ "$HOOK_COUNT" -eq 13 ]; then
-  pass "13 hooks installed in hooks/ (incl. pre-compact v6.3.2)"
+if [ "$HOOK_COUNT" -eq 14 ]; then
+  pass "14 hooks installed in hooks/ (incl. usage-capture v6.9.1)"
 else
   fail_case "hook count" "got $HOOK_COUNT"
 fi

package/tests/hooks.test.sh

@@ -420,6 +420,38 @@ else
 fi
 rm -rf "$TMP"
 
+# --- session-start.js — stale update banner self-clears (regression: v6.9.1) ---
+# A notif file whose advertised `latest` is already installed must NOT render a
+# false "update available" banner; it must be deleted. A genuinely-newer notif
+# must be preserved.
+QH=$(mktemp -d)
+mkdir -p "$QH/bin"
+echo 'process.exit(0)' > "$QH/bin/qualia-ui.js"   # dummy UI so render path is reachable
+echo '{"code":"QS-FAWZI-11","version":"6.9.0"}' > "$QH/.qualia-config.json"
+
+# Case 1: installed (6.9.0) >= notif.latest (6.9.0) → stale, must self-clear
+echo '{"current":"6.8.1","latest":"6.9.0","detected_at":"t"}' > "$QH/.qualia-update-available.json"
+(cd "$QH" && QUALIA_HOME="$QH" $NODE "$HOOKS_DIR/session-start.js" >/dev/null 2>&1)
+if [ ! -f "$QH/.qualia-update-available.json" ]; then
+  echo "  ✓ stale update notice self-clears when version caught up"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ stale update notice was NOT cleared"
+  FAIL=$((FAIL + 1))
+fi
+
+# Case 2: installed (6.9.0) < notif.latest (9.9.9) → genuine, must persist
+echo '{"current":"6.9.0","latest":"9.9.9","detected_at":"t"}' > "$QH/.qualia-update-available.json"
+(cd "$QH" && QUALIA_HOME="$QH" $NODE "$HOOKS_DIR/session-start.js" >/dev/null 2>&1)
+if [ -f "$QH/.qualia-update-available.json" ]; then
+  echo "  ✓ genuine update notice is preserved"
+  PASS=$((PASS + 1))
+else
+  echo "  ✗ genuine update notice was wrongly cleared"
+  FAIL=$((FAIL + 1))
+fi
+rm -rf "$QH"
+
 # pre-compact.js removed in v6.2.0 — state.js journal provides crash safety.
 
 # --- auto-update.js ---

package/tests/install-smoke.test.sh

@@ -124,10 +124,11 @@ else
 fi
 
 if [ -d "$HOME_DIR/.claude/hooks" ] \
-  && [ "$(find "$HOME_DIR/.claude/hooks" -maxdepth 1 -name '*.js' | wc -l | tr -d ' ')" = "13" ] \
+  && [ "$(find "$HOME_DIR/.claude/hooks" -maxdepth 1 -name '*.js' | wc -l | tr -d ' ')" = "14" ] \
   && [ -f "$HOME_DIR/.claude/hooks/fawzi-approval-guard.js" ] \
-  && [ -f "$HOME_DIR/.claude/hooks/pre-compact.js" ]; then
-  pass "packaged install has 13 hooks including pre-compact (v6.3.2 sidecar snapshot)"
+  && [ -f "$HOME_DIR/.claude/hooks/pre-compact.js" ] \
+  && [ -f "$HOME_DIR/.claude/hooks/usage-capture.js" ]; then
+  pass "packaged install has 14 hooks including usage-capture (v6.9.1 telemetry)"
 else
   fail_case "packaged hook set mismatch"
 fi