npm - qualia-framework - Versions diffs - 6.9.0 → 6.14.0 - Mend

qualia-framework 6.9.0 → 6.14.0

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 (35) hide show

package/CHANGELOG.md +88 -0
package/agents/verifier.md +1 -1
package/bin/agent-status.js +251 -0
package/bin/analyze-gate.js +318 -0
package/bin/command-surface.js +1 -0
package/bin/install.js +31 -4
package/bin/report-payload.js +19 -0
package/bin/runtime-manifest.js +2 -0
package/bin/state.js +145 -11
package/docs/EMPLOYEE-QUICKSTART.md +5 -3
package/docs/erp-contract.md +33 -1
package/docs/qualia-manual.html +396 -0
package/hooks/branch-guard.js +133 -63
package/hooks/pre-deploy-gate.js +38 -0
package/hooks/session-start.js +24 -4
package/hooks/task-write-guard.js +165 -0
package/hooks/usage-capture.js +108 -0
package/package.json +2 -1
package/skills/qualia-build/SKILL.md +30 -1
package/skills/qualia-report/SKILL.md +3 -0
package/skills/qualia-ship/SKILL.md +3 -0
package/skills/qualia-update/SKILL.md +96 -0
package/skills/qualia-verify/SKILL.md +7 -1
package/templates/journey.md +1 -1
package/templates/planning.gitignore +3 -0
package/tests/agent-status.test.sh +138 -0
package/tests/analyze-gate.test.sh +170 -0
package/tests/bin.test.sh +6 -4
package/tests/hooks.test.sh +250 -17
package/tests/install-smoke.test.sh +5 -3
package/tests/lib.test.sh +2 -2
package/tests/run-all.sh +2 -0
package/tests/runner.js +3 -2
package/tests/state.test.sh +95 -0
package/skills/qualia-discuss/SKILL.md +0 -222

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 (leaking secrets, destructive DB ops, force-pushing) before it happens, and record the risky-but-allowed stuff (pushing to <code>main</code>) for the owner. 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 are the norm; pushing to <code>main</code> is allowed but recorded for the owner.</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: pushing to <code>main</code> is recorded for the owner (the <code>branch-guard</code> hook counts each one to the ERP) rather than free, 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, prefer a feature branch + review; direct pushes to <code>main</code> are allowed but recorded for the owner, so save them for trivially safe changes.</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 by default.</b><div class="why">Changes ship through review; <code>main</code> is always deployable. Pushing to <code>main</code> is allowed but the branch-guard hook records it for the owner.</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>