npm - qualia-framework - Versions diffs - 6.8.1 → 6.9.2 - Mend

qualia-framework 6.8.1 → 6.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (85) hide show

package/docs/erp-contract.md CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.8.1",
+  "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,8 @@
     "docs/release.md",
     "docs/changelog-v6.html",
     "docs/onboarding.html",
+    "docs/qualia-manual.html",
+    "docs/EMPLOYEE-QUICKSTART.md",
     "CLAUDE.md",
     "AGENTS.md",
     "guide.md",