qualia-framework 7.2.1 → 7.3.0

package/bin/cli.js

@@ -156,6 +156,82 @@ function cmdVersion() {
   console.log("");
 }
 
+// ─── Snapshot / Rollback (update safety net) ─────────────────────
+// `update` re-runs the installer in place; a crash or bad version mid-update
+// used to leave a half-migrated tree with no restore path. We snapshot the
+// framework-owned subtrees into <home>/.qualia-prev/ BEFORE updating, so
+// `rollback` can restore the previous version. User/security files (CLAUDE.md,
+// settings.json, .qualia-config.json, .erp-api-key) are NOT snapshotted — they
+// stay on their existing in-place merge/backup path. Single-deep (last update).
+const SNAPSHOT_DIRS = ["bin", "skills", "agents", "hooks", "rules", "qualia-design", "references", "qualia-references"];
+const SNAPSHOT_FILES = ["package.json", "qualia-guide.md"];
+const PREV_DIR = ".qualia-prev";
+
+function homeVersion(home) {
+  try { return JSON.parse(fs.readFileSync(configFileForHome(home), "utf8")).version || null; } catch {}
+  try { return JSON.parse(fs.readFileSync(path.join(home, "package.json"), "utf8")).version || null; } catch {}
+  return null;
+}
+
+function snapshotHome(home) {
+  const prev = path.join(home, PREV_DIR);
+  try { fs.rmSync(prev, { recursive: true, force: true }); } catch {} // single-deep
+  fs.mkdirSync(prev, { recursive: true });
+  const swapped = [];
+  for (const d of SNAPSHOT_DIRS) {
+    const src = path.join(home, d);
+    if (fs.existsSync(src)) { fs.cpSync(src, path.join(prev, d), { recursive: true }); swapped.push(d); }
+  }
+  for (const f of SNAPSHOT_FILES) {
+    const src = path.join(home, f);
+    if (fs.existsSync(src)) { fs.cpSync(src, path.join(prev, f)); swapped.push(f); }
+  }
+  const manifest = { from_version: homeVersion(home), to_version: null, swapped, ts: new Date().toISOString() };
+  fs.writeFileSync(path.join(prev, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+  return manifest;
+}
+
+function finalizeSnapshot(home) {
+  const mf = path.join(home, PREV_DIR, "manifest.json");
+  try {
+    const m = JSON.parse(fs.readFileSync(mf, "utf8"));
+    m.to_version = homeVersion(home);
+    fs.writeFileSync(mf, JSON.stringify(m, null, 2) + "\n");
+  } catch {}
+}
+
+function restoreHome(home) {
+  const prev = path.join(home, PREV_DIR);
+  const mf = path.join(prev, "manifest.json");
+  if (!fs.existsSync(mf)) return { ok: false, reason: "no snapshot" };
+  let m;
+  try { m = JSON.parse(fs.readFileSync(mf, "utf8")); } catch (e) { return { ok: false, reason: `unreadable manifest: ${e.message}` }; }
+  for (const name of m.swapped || []) {
+    const snap = path.join(prev, name);
+    const live = path.join(home, name);
+    if (!fs.existsSync(snap)) continue;
+    try {
+      if (fs.statSync(snap).isDirectory()) {
+        fs.rmSync(live, { recursive: true, force: true });
+        fs.cpSync(snap, live, { recursive: true });
+      } else {
+        fs.cpSync(snap, live);
+      }
+    } catch { /* continue; partial restore is re-runnable since the snapshot is kept */ }
+  }
+  // Reconcile the config version store back to the snapshot's version so doctor's
+  // reconciliation check goes green (the marker package.json was restored above).
+  if (m.from_version) {
+    try {
+      const cf = configFileForHome(home);
+      const cfg = JSON.parse(fs.readFileSync(cf, "utf8"));
+      cfg.version = m.from_version;
+      fs.writeFileSync(cf, JSON.stringify(cfg, null, 2) + "\n");
+    } catch {}
+  }
+  return { ok: true, manifest: m };
+}
+
 function cmdUpdate() {
   banner();
   const cfg = readConfig();
@@ -166,8 +242,23 @@ function cmdUpdate() {
     process.exit(1);
   }
 
+  // Snapshot every installed home BEFORE updating so `rollback` can restore.
+  const snapHomes = installedHomes().filter((h) => fs.existsSync(configFileForHome(h)));
+  for (const h of snapHomes) { try { snapshotHome(h); } catch { /* non-fatal — update still proceeds */ } }
+
+  // --snapshot-only: take the safety snapshot without running the update (also
+  // the testable seam for the snapshot+rollback path, which otherwise needs npx).
+  if (process.argv.includes("--snapshot-only")) {
+    for (const h of snapHomes) {
+      const label = path.basename(h) === ".codex" ? "Codex" : "Claude";
+      console.log(`  ${GREEN}✓${RESET} ${label}: snapshot v${homeVersion(h) || "?"} → ${PREV_DIR}/  (restore: ${TEAL}qualia-framework rollback${RESET})`);
+    }
+    console.log("");
+    return;
+  }
+
   console.log(`  ${DIM}Current:${RESET}  ${WHITE}${PKG.version}${RESET}`);
-  console.log(`  ${DIM}Updating...${RESET}`);
+  console.log(`  ${DIM}Updating...${RESET} ${DIM}(snapshot taken — ${RESET}${TEAL}rollback${RESET}${DIM} available)${RESET}`);
   console.log("");
 
   try {
@@ -180,16 +271,49 @@ function cmdUpdate() {
       encoding: "utf8",
     });
     if (r.status !== 0) {
-      console.log(`  ${RED}✗${RESET} Update failed. Run manually: npx qualia-framework@latest install`);
+      console.log(`  ${RED}✗${RESET} Update failed. Restore the previous version: ${TEAL}qualia-framework rollback${RESET}`);
+      console.log(`  ${DIM}Or retry:${RESET} npx qualia-framework@latest install`);
       process.exit(1);
     }
+    for (const h of snapHomes) finalizeSnapshot(h);
   } catch (e) {
     console.log(`  ${RED}✗${RESET} Update failed: ${e.message}`);
-    console.log(`  ${DIM}Run manually:${RESET} npx qualia-framework@latest install`);
+    console.log(`  ${DIM}Restore:${RESET} ${TEAL}qualia-framework rollback${RESET}  ${DIM}·  Retry:${RESET} npx qualia-framework@latest install`);
     process.exit(1);
   }
 }
 
+// ─── Rollback ────────────────────────────────────────────────────
+// Restores the framework-owned subtrees from the last <home>/.qualia-prev/
+// snapshot (taken automatically before each `update`), and resets the config
+// version store to the snapshot's version so `doctor` reconciles. Covers all
+// installed homes that carry a snapshot.
+function cmdRollback() {
+  banner();
+  console.log("");
+  const homes = installedHomes().filter((h) => fs.existsSync(path.join(h, PREV_DIR, "manifest.json")));
+  if (homes.length === 0) {
+    console.log(`  ${YELLOW}!${RESET} No snapshot to roll back to.`);
+    console.log(`  ${DIM}A snapshot is taken automatically before each ${RESET}${TEAL}update${RESET}${DIM}, or take one now:${RESET} ${TEAL}qualia-framework update --snapshot-only${RESET}`);
+    console.log("");
+    process.exit(1);
+  }
+  let failed = 0;
+  for (const home of homes) {
+    const label = path.basename(home) === ".codex" ? "Codex" : "Claude";
+    const r = restoreHome(home);
+    if (r.ok) {
+      console.log(`  ${GREEN}✓${RESET} ${label}: rolled back ${r.manifest.to_version || "?"} → ${WHITE}${r.manifest.from_version || "?"}${RESET} (${(r.manifest.swapped || []).length} subtrees)`);
+    } else {
+      console.log(`  ${RED}✗${RESET} ${label}: ${r.reason}`);
+      failed++;
+    }
+  }
+  console.log(`\n  ${DIM}Verify:${RESET} ${TEAL}qualia-framework doctor${RESET}`);
+  console.log("");
+  if (failed > 0) process.exit(1);
+}
+
 // ─── Uninstall ───────────────────────────────────────────
 // Surgical removal of the Qualia Framework from installed homes.
 // Preserves CLAUDE.md / AGENTS.md (user may have customized them), Codex
@@ -466,14 +590,30 @@ async function cmdUninstall() {
     safeUnlink(path.join(home, "qualia-guide.md"), counters);
 
     safeRmDir(path.join(home, ".qualia-traces"), counters);
+    safeRmDir(path.join(home, ".qualia-prev"), counters); // pre-update rollback snapshot
 
     // Memory-loop runner (installed alongside bin/, not a .js so not in QUALIA_BIN_FILES).
     safeUnlink(path.join(home, "bin", "qualia-loop.sh"), counters);
+    // cli.js is copied next to the runtime scripts to power the bare-command
+    // shim, but it's not in QUALIA_BIN_FILES (binFiles excludes it), so remove
+    // it explicitly here.
+    safeUnlink(path.join(home, "bin", "cli.js"), counters);
 
     if (isCodexHome(home)) cleanCodexHooksJson(home, counters);
     else cleanSettingsJson(home, counters);
   }
 
+  // ── Bare-command PATH shim teardown ───────────────────────
+  // linkBareCommand (install.js) drops a `qualia-framework` shim into the
+  // first writable user-bin dir on PATH. Remove it from every candidate so
+  // uninstall leaves no dangling command.
+  try {
+    const home = require("os").homedir();
+    for (const d of [".local/bin", ".npm-global/bin", "bin"]) {
+      safeUnlink(path.join(home, d, "qualia-framework"), counters);
+    }
+  } catch {}
+
   // ── Memory loop systemd --user timer teardown ─────────────
   // installMemoryTimer() (bin/install.js) enables a nightly timer + writes unit
   // files. Disable + remove them so uninstall leaves no scheduled job behind.
@@ -1468,6 +1608,31 @@ function cmdDoctor() {
     }
   }
 
+  // ── Version reconciliation (single source of truth) ─────────────
+  // install.js writes the SAME PKG_VERSION to the home-root package.json marker
+  // and each home's .qualia-config.json `version`. They agree right after a clean
+  // install — but a partial/crashed update can leave them disagreeing while every
+  // file-presence check above still passes, so doctor would otherwise report
+  // "healthy" on a half-migrated tree. Catch that drift explicitly.
+  const seenVersions = [];
+  for (const home of homes) {
+    const hlabel = path.basename(home) === ".codex" ? "Codex" : "Claude";
+    let markerV = null, cfgV = null;
+    try { markerV = JSON.parse(fs.readFileSync(path.join(home, "package.json"), "utf8")).version || null; } catch {}
+    try { cfgV = JSON.parse(fs.readFileSync(configFileForHome(home), "utf8")).version || null; } catch {}
+    if (markerV && cfgV) {
+      check(`${hlabel} version reconciled (${cfgV})`, markerV === cfgV,
+        `version drift: package.json marker=${markerV} vs .qualia-config.json=${cfgV} — reinstall: npx qualia-framework@latest install`);
+    }
+    if (markerV) seenVersions.push(markerV);
+    if (cfgV) seenVersions.push(cfgV);
+  }
+  const distinctVersions = [...new Set(seenVersions)];
+  if (distinctVersions.length > 1) {
+    check("installed version consistent across stores", false,
+      `multiple versions present (${distinctVersions.join(", ")}) — reinstall to reconcile: npx qualia-framework@latest install`);
+  }
+
   // ── Version vs. installed ──────────────────────────────
   const cfg = readConfig();
   if (cfg.installed_at) {
@@ -1636,7 +1801,8 @@ function cmdHelp() {
   console.log("");
   console.log(`  ${WHITE}Commands:${RESET}`);
   console.log(`    qualia-framework ${TEAL}install${RESET}      Install or reinstall the framework`);
-  console.log(`    qualia-framework ${TEAL}update${RESET}       Update to the latest version`);
+  console.log(`    qualia-framework ${TEAL}update${RESET}       Update to the latest version (${DIM}snapshots first${RESET})`);
+  console.log(`    qualia-framework ${TEAL}rollback${RESET}     Restore the previous version from the pre-update snapshot`);
   console.log(`    qualia-framework ${TEAL}version${RESET}      Show installed version + check for updates`);
   console.log(`    qualia-framework ${TEAL}uninstall${RESET}    Clean removal from installed Claude/Codex homes (${DIM}-y to skip prompts${RESET})`);
   console.log(`    qualia-framework ${TEAL}migrate${RESET}      Wire current hook + env layout into ~/.claude/settings.json`);
@@ -1690,6 +1856,9 @@ switch (cmd) {
   case "upgrade":
     cmdUpdate();
     break;
+  case "rollback":
+    cmdRollback();
+    break;
   case "uninstall":
   case "remove":
     cmdUninstall().catch((e) => {

package/bin/erp-retry.js

@@ -18,6 +18,11 @@
 //
 // Hard rules:
 // - Never throw out the queue file on parse error — back it up and start fresh.
+// - Bound the queue: items older than QUEUE_TTL_DAYS are pruned, and the queue
+//   is length-capped at QUEUE_MAX_ITEMS (oldest dropped first). Anything pruned
+//   is backed up to a .pruned.<ts>.json sidecar — never silently destroyed.
+// - give_up items are kept but never count against the --max drain cap, so a
+//   backlog of stuck items can't starve freshly-enqueued reports.
 // - Max 10 attempts per item before marking give_up=true (stops the cycle).
 // - 401/422 are permanent failures: keep the item but mark give_up=true so
 //   the user can see it and resolve manually (typically: fix the API key).
@@ -55,6 +60,13 @@ const CONFIG_FILE = path.join(QUALIA_HOME, ".qualia-config.json");
 const MAX_GIVE_UP_ATTEMPTS = 10;
 const DEFAULT_TIMEOUT_MS = 5000;
 const DEFAULT_MAX_ITEMS = 100;
+// Bound the queue so a backlog of stuck/given-up items can't grow without limit.
+// Oldest items past the TTL are pruned; if the queue still exceeds the length
+// cap, the oldest (by enqueued_at) are dropped. Anything pruned is backed up to
+// a .pruned.<ts>.json sidecar first — same never-silently-destroy discipline as
+// the corrupt-queue backup in readQueue(). Override via env for tests.
+const QUEUE_MAX_ITEMS = Number(process.env.ERP_QUEUE_MAX_ITEMS) || 200;
+const QUEUE_TTL_DAYS = Number(process.env.ERP_QUEUE_TTL_DAYS) || 30;
 
 // ─── Args ───────────────────────────────────────────────
 const args = process.argv.slice(2);
@@ -101,6 +113,63 @@ function writeQueue(data) {
   fs.renameSync(tmp, QUEUE_FILE);
 }
 
+// Bound the queue: drop items older than the TTL, then drop the oldest beyond
+// the length cap. Returns { queue, pruned } — pruned items are NOT discarded by
+// this function; the caller must back them up before persisting the trimmed
+// queue. Pure (no I/O) so it's testable in isolation.
+function pruneQueue(queue, { now = Date.now(), ttlDays = QUEUE_TTL_DAYS, maxItems = QUEUE_MAX_ITEMS } = {}) {
+  const ttlMs = ttlDays * 24 * 60 * 60 * 1000;
+  const ageOf = (it) => {
+    const t = Date.parse(it && it.enqueued_at);
+    return Number.isFinite(t) ? now - t : 0; // unparseable timestamp → treat as fresh, never auto-drop
+  };
+  const pruned = [];
+  let kept = queue.filter((it) => {
+    if (ageOf(it) > ttlMs) { pruned.push(it); return false; }
+    return true;
+  });
+  if (kept.length > maxItems) {
+    // Drop the oldest (largest age) first so fresh reports survive.
+    const ranked = kept.map((it, i) => ({ it, i, age: ageOf(it) }))
+      .sort((a, b) => b.age - a.age || a.i - b.i);
+    const dropCount = kept.length - maxItems;
+    const dropSet = new Set(ranked.slice(0, dropCount).map((r) => r.i));
+    const next = [];
+    kept.forEach((it, i) => { if (dropSet.has(i)) pruned.push(it); else next.push(it); });
+    kept = next;
+  }
+  return { queue: kept, pruned };
+}
+
+// Back pruned items up to a sidecar, mirroring the corrupt-queue backup path.
+// Best-effort: never throws (a failed backup must not block the drain).
+function backupPruned(pruned) {
+  if (!pruned || pruned.length === 0) return "";
+  const bak = `${QUEUE_FILE}.pruned.${new Date().toISOString().replace(/[:.]/g, "-")}.json`;
+  try {
+    fs.writeFileSync(bak, JSON.stringify({ pruned_at: new Date().toISOString(), queue: pruned }, null, 2) + "\n", { mode: 0o600 });
+    return bak;
+  } catch { return ""; }
+}
+
+// One-line health stats for callers (session-start surface, `show`). Reports
+// the total count and the age in whole hours of the oldest item.
+function queueStats(data) {
+  const q = (data && Array.isArray(data.queue)) ? data.queue : [];
+  if (q.length === 0) return { count: 0, give_up: 0, oldest_hours: 0 };
+  const now = Date.now();
+  let oldest = 0;
+  for (const it of q) {
+    const t = Date.parse(it && it.enqueued_at);
+    if (Number.isFinite(t)) oldest = Math.max(oldest, now - t);
+  }
+  return {
+    count: q.length,
+    give_up: q.filter((it) => it && it.give_up).length,
+    oldest_hours: Math.floor(oldest / (60 * 60 * 1000)),
+  };
+}
+
 function enqueue({ client_report_id, idempotency_key, url, payload, last_error, headers }) {
   if (!client_report_id || !url || !payload) {
     throw new Error("enqueue: client_report_id, url, payload are required");
@@ -188,22 +257,34 @@ function readConfig() {
 // ─── Actions ────────────────────────────────────────────
 async function actionDrain() {
   const data = readQueue();
+
+  // Bound the queue before draining: TTL-prune + length-cap, backing up anything
+  // dropped. This runs even when the drain itself is skipped below (no key / ERP
+  // off) so a stranded backlog can't accumulate forever.
+  const { queue: bounded, pruned } = pruneQueue(data.queue);
+  if (pruned.length > 0) {
+    data.queue = bounded;
+    const bak = backupPruned(pruned);
+    writeQueue({ queue: bounded });
+    log(`erp-retry: pruned ${pruned.length} stale item(s)${bak ? ` (backup at ${bak})` : ""}`);
+  }
+
   if (data.queue.length === 0) {
     log("erp-retry: queue empty");
-    return { drained: 0, kept: 0, give_up: 0 };
+    return { drained: 0, kept: 0, give_up: 0, pruned: pruned.length };
   }
 
   const cfg = readConfig();
   const erpEnabled = !cfg.erp || cfg.erp.enabled !== false;
   if (!erpEnabled) {
     log("erp-retry: ERP disabled in config; skipping drain (queue preserved)");
-    return { drained: 0, kept: data.queue.length, give_up: 0 };
+    return { drained: 0, kept: data.queue.length, give_up: 0, pruned: pruned.length };
   }
 
   const apiKey = readApiKey();
   if (!apiKey) {
     log("erp-retry: API key missing; skipping drain (queue preserved)");
-    return { drained: 0, kept: data.queue.length, give_up: 0 };
+    return { drained: 0, kept: data.queue.length, give_up: 0, pruned: pruned.length };
   }
 
   let drained = 0;
@@ -212,12 +293,14 @@ async function actionDrain() {
   let processed = 0;
 
   for (const item of data.queue) {
-    // Already given up — keep but don't try.
+    // Already given up — keep but don't try, and DON'T count against the --max
+    // cap (processed is not incremented here). A backlog of stuck items must
+    // never starve freshly-enqueued reports out of the drain budget.
     if (item.give_up) {
       remaining.push(item);
       continue;
     }
-    // Respect the per-run cap.
+    // Respect the per-run cap (counts only live, retryable items).
     if (processed >= MAX_ITEMS) {
       remaining.push(item);
       continue;
@@ -257,7 +340,7 @@ async function actionDrain() {
   if (drained > 0 || give_up > 0 || !QUIET) {
     log(`erp-retry: drained=${drained} kept=${remaining.length} give_up=${give_up}`);
   }
-  return { drained, kept: remaining.length, give_up };
+  return { drained, kept: remaining.length, give_up, pruned: pruned.length };
 }
 
 function actionShow() {
@@ -266,7 +349,8 @@ function actionShow() {
     log("queue empty");
     return;
   }
-  log(`${data.queue.length} item(s) in queue:`);
+  const stats = queueStats(data);
+  log(`${stats.count} item(s) in queue (oldest ${stats.oldest_hours}h, give_up ${stats.give_up}):`);
   for (const item of data.queue) {
     log(`  ${item.client_report_id}  enqueued=${item.enqueued_at}  attempts=${item.attempts || 0}${item.give_up ? "  GIVE_UP" : ""}`);
     if (item.last_error) log(`    last_error: ${item.last_error}`);
@@ -288,7 +372,7 @@ function actionClear() {
 // ─── Export for in-process use (qualia-report skill enqueues directly;
 //     auto-report.js reuses the POST + config/key readers so there is ONE
 //     ERP-upload seam, not two). ──
-module.exports = { enqueue, readQueue, writeQueue, postOnce, readApiKey, readConfig };
+module.exports = { enqueue, readQueue, writeQueue, postOnce, readApiKey, readConfig, pruneQueue, backupPruned, queueStats };
 
 // ─── CLI entrypoint ─────────────────────────────────────
 if (require.main === module) {

package/bin/install.js

@@ -507,6 +507,29 @@ function closeRl() {
   if (SHARED_RL) { try { SHARED_RL.close(); } catch {} SHARED_RL = null; }
 }
 
+// Ask a question while masking the typed answer with '*' (for install codes).
+// The prompt itself is written before muting, so only keystrokes are hidden.
+function questionMasked(rl, prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.stdoutMuted = false;
+      rl.output.write("\n");
+      resolve(answer);
+    });
+    rl.stdoutMuted = true;
+    if (!rl.__maskPatched) {
+      rl.__maskPatched = true;
+      const origWrite = rl._writeToOutput.bind(rl);
+      rl._writeToOutput = function (str) {
+        if (!rl.stdoutMuted) return origWrite(str);
+        // Pass control sequences (newlines) through; mask printable input.
+        if (str === "\n" || str === "\r\n" || str === "\r") return rl.output.write(str);
+        return rl.output.write("*");
+      };
+    }
+  });
+}
+
 // Read every available stdin line into an array. Resolves immediately on
 // 'end'. Used only when stdin is piped (legacy `echo ... | install`).
 function bufferStdin() {
@@ -536,8 +559,9 @@ function askCode() {
     if (!IS_INTERACTIVE) {
       printHeader();
       const line = nextPipedLine();
-      // Echo the prompt + answer for log readability.
-      process.stdout.write(`  ${WHITE}Enter install code (or "EMPLOYEE" for no-code install):${RESET} ${line}\n`);
+      // Echo the prompt for log readability, but never reveal the code itself.
+      const shown = isEmployeeKeyword(line) ? String(line).trim().toUpperCase() : (line ? "*".repeat(String(line).trim().length || 1) : "");
+      process.stdout.write(`  ${WHITE}Enter install code (or "EMPLOYEE" for no-code install):${RESET} ${shown}\n`);
       resolve(String(line || "").trim());
       return;
     }
@@ -546,7 +570,7 @@ function askCode() {
     console.log(`  ${DIM}OWNER / team member? Enter your install code (QS-NAME-##).${RESET}`);
     console.log(`  ${DIM}New employee without a code? Type ${RESET}${TEAL}EMPLOYEE${RESET}${DIM} to install in employee mode.${RESET}`);
     console.log("");
-    rl.question(`  ${WHITE}Install code or "EMPLOYEE":${RESET} `, (answer) => {
+    questionMasked(rl, `  ${WHITE}Install code or "EMPLOYEE":${RESET} `).then((answer) => {
       resolve(String(answer || "").trim());
     });
   });
@@ -734,6 +758,76 @@ function installMemoryTimer() {
   }
 }
 
+// ─── Bare `qualia-framework` command (PATH shim) ─────────────
+// `npx qualia-framework install` runs the CLI via npx but leaves no bare
+// command behind — the runtime scripts land in <home>/bin, but the meta-CLI
+// (doctor/version/update/team/traces/uninstall) was never copied, so
+// `qualia-framework doctor` is "command not found". `npm i -g` is the usual
+// workaround but it's fragile for a team: npm's global prefix varies per
+// machine (nvm/pnpm/bun), is frequently not on PATH, and forks a SECOND copy
+// of the package that drifts from whatever `update` last fetched. Instead we
+// self-link: cli.js is copied next to the runtime scripts (above) and we drop
+// a tiny shim into a PATH dir that execs it. One install → a working, offline
+// bare command with a single source of truth; `update` re-points it for free
+// because update re-runs this installer.
+function linkBareCommand(primaryHome) {
+  printSection("Bare command");
+  const os = require("os");
+  const HOME = os.homedir();
+
+  if (process.platform === "win32") {
+    log(`${DIM}Windows — PATH shim skipped. Use:${RESET} ${TEAL}npx qualia-framework <cmd>${RESET}`);
+    return;
+  }
+
+  // cli.js must already be sitting next to the runtime scripts (scripts step).
+  const cliPath = path.join(primaryHome, "bin", "cli.js");
+  if (!fs.existsSync(cliPath)) {
+    warn(`bare command — cli.js missing at ${cliPath}; skipped`);
+    return;
+  }
+
+  // Prefer a user-bin dir that is already on $PATH and writable; otherwise
+  // default to ~/.local/bin (the XDG standard) and tell the user to add it.
+  const pathDirs = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  const writable = (d) => { try { fs.accessSync(d, fs.constants.W_OK); return true; } catch { return false; } };
+  const localBin = path.join(HOME, ".local", "bin");
+  const candidates = [localBin, path.join(HOME, ".npm-global", "bin"), path.join(HOME, "bin")];
+
+  let target = candidates.find((d) => fs.existsSync(d) && writable(d) && pathDirs.includes(d));
+  let onPath = Boolean(target);
+  if (!target) {
+    target = localBin;
+    try { fs.mkdirSync(target, { recursive: true }); } catch {}
+    onPath = pathDirs.includes(target);
+  }
+
+  const shimPath = path.join(target, "qualia-framework");
+  const shimBody = [
+    "#!/usr/bin/env bash",
+    "# qualia-framework — self-linked by the installer; execs the local CLI.",
+    "# Re-pointed on every install/update so it tracks the latest fetched cli.js.",
+    `exec node "${cliPath}" "$@"`,
+    "",
+  ].join("\n");
+
+  try {
+    fs.writeFileSync(shimPath, shimBody);
+    fs.chmodSync(shimPath, 0o755);
+    ok(`qualia-framework → ${shimPath.replace(HOME, "~")}`);
+  } catch (e) {
+    warn(`bare command — ${e.message}`);
+    return;
+  }
+
+  if (onPath) {
+    log(`${DIM}Try it:${RESET} ${TEAL}qualia-framework doctor${RESET}`);
+  } else {
+    log(`${YELLOW}!${RESET} ${DIM}${target.replace(HOME, "~")} is not on your PATH yet. Add it:${RESET}`);
+    log(`  ${TEAL}echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc${RESET}`);
+  }
+}
+
 // ─── Main ────────────────────────────────────────────────
 async function main() {
   // Piped install: drain stdin once up front. Avoids EOF/'close' racing
@@ -787,6 +881,7 @@ async function main() {
     // Codex-only path: skip the entire Claude install block. Jump straight
     // to the Codex installer + final summary.
     await installCodex(member, target, employeeMode);
+    try { linkBareCommand(CODEX_DIR); } catch (e) { warn(`bare command — ${e.message}`); }
     return;
   }
 
@@ -1028,7 +1123,11 @@ async function main() {
   const refDest = path.join(CLAUDE_DIR, "qualia-references");
   if (fs.existsSync(refDir)) {
     if (!fs.existsSync(refDest)) fs.mkdirSync(refDest, { recursive: true });
-    for (const file of fs.readdirSync(refDir)) {
+    for (const entry of fs.readdirSync(refDir, { withFileTypes: true })) {
+      // Skip nested dirs (e.g. archetypes/) — they are handled by the canonical
+      // tree copy below. Reading a directory as a text file throws EISDIR.
+      if (entry.isDirectory()) continue;
+      const file = entry.name;
       try {
         copyTextTransform(path.join(refDir, file), path.join(refDest, file), claudeText);
         ok(file);
@@ -1098,6 +1197,17 @@ async function main() {
       try { fs.chmodSync(out, 0o755); } catch {}
       ok(script.label);
     }
+    // Ship cli.js alongside the runtime scripts so the bare `qualia-framework`
+    // command can exec it locally (see linkBareCommand). It is intentionally
+    // NOT in RUNTIME_BIN_SCRIPTS — the skills never call it; only the PATH
+    // shim does, and keeping it out of the manifest keeps trust-score's
+    // REQUIRED_BIN probe (and uninstall) scoped to true runtime scripts.
+    try {
+      const cliOut = path.join(binDest, "cli.js");
+      copy(path.join(FRAMEWORK_DIR, "bin", "cli.js"), cliOut);
+      try { fs.chmodSync(cliOut, 0o755); } catch {}
+      ok("cli.js (meta-command — powers the bare `qualia-framework`)");
+    } catch (e) { warn(`cli.js — ${e.message}`); }
     // v6.8.1: purge retired bin scripts (same belt-and-suspenders as
     // DEPRECATED_HOOKS — bin/ never had an orphan pass, so the brain
     // experiment's indexer survived reinstalls).
@@ -1243,7 +1353,10 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     code: code || "",
     installed_by: member.name,
     role: member.role,
-    version: require("../package.json").version,
+    // Single source: the same PKG_VERSION written to the home root package.json
+    // marker — config and marker can never disagree out of a clean install
+    // (doctor's version-reconciliation check enforces this).
+    version: PKG_VERSION,
     installed_at: new Date().toISOString().split("T")[0],
     erp: {
       enabled: !employeeMode,
@@ -1423,6 +1536,9 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
           { type: "command", if: "Bash(vercel --prod*)|Bash(vercel deploy*)", command: nodeCmd("vercel-account-guard.js"), timeout: 8, statusMessage: "⬢ Verifying Vercel account..." },
           { type: "command", if: "Bash(vercel env*)", command: nodeCmd("env-empty-guard.js"), timeout: 5, statusMessage: "⬢ Checking env value..." },
           { type: "command", if: "Bash(supabase*)|Bash(npx supabase*)", command: nodeCmd("supabase-destructive-guard.js"), timeout: 5, statusMessage: "⬢ Checking Supabase safety..." },
+          // Close the Bash bypass: SQL written/executed through the shell (heredoc→.sql,
+          // psql -c/-f, supabase db execute/push) never reaches the Edit|Write migration-guard.
+          { type: "command", if: "Bash(*psql*)|Bash(*.sql*)|Bash(supabase db execute*)|Bash(supabase db push*)|Bash(npx supabase db execute*)|Bash(npx supabase db push*)", command: nodeCmd("migration-guard.js"), timeout: 10, statusMessage: "⬢ Checking migration safety..." },
           { type: "command", if: "Bash(git commit*)", command: nodeCmd("secret-guard.js"), timeout: 10, statusMessage: "⬢ Scanning staged content for secrets..." },
         ],
       },
@@ -1602,6 +1718,9 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     await installCodex(member, target, employeeMode);
   }
 
+  // ─── Bare command (PATH shim) ────────────────────────────
+  try { linkBareCommand(CLAUDE_DIR); } catch (e) { warn(`bare command — ${e.message}`); }
+
   // ─── Summary ───────────────────────────────────────────
   closeSection();
   printSummary({ member, target, claudeInstalled: true });
@@ -1797,7 +1916,7 @@ async function installCodex(member, target, employeeMode = false) {
       code: Object.entries(TEAM).find(([, m]) => m.name === member.name)?.[0] || "",
       installed_by: member.name,
       role: member.role,
-      version: require("../package.json").version,
+      version: PKG_VERSION, // single source — same constant as the marker + Claude config
       installed_at: new Date().toISOString().split("T")[0],
       erp: {
         // Employee mode (no team code) leaves ERP off so /qualia-report
@@ -1844,6 +1963,12 @@ async function installCodex(member, target, employeeMode = false) {
       copy(src, out);
       try { fs.chmodSync(out, 0o755); } catch {}
     }
+    // cli.js powers the bare `qualia-framework` shim (not a runtime script).
+    try {
+      const cliOut = path.join(binDest, "cli.js");
+      copy(path.join(FRAMEWORK_DIR, "bin", "cli.js"), cliOut);
+      try { fs.chmodSync(cliOut, 0o755); } catch {}
+    } catch {}
     ok(`bin/ (${scripts.length} scripts)`);
   } catch (e) {
     warn(`Codex scripts — ${e.message}`);
@@ -1988,6 +2113,9 @@ async function installCodex(member, target, employeeMode = false) {
               { type: "command", command: nodeCmd("vercel-account-guard.js"), timeout: 8 },
               { type: "command", command: nodeCmd("env-empty-guard.js"), timeout: 5 },
               { type: "command", command: nodeCmd("supabase-destructive-guard.js"), timeout: 5 },
+              // Bash-bypass parity with Claude: migration-guard self-gates on the Bash
+              // path (only blocks when it detects inline SQL bypassing supabase/migrations/).
+              { type: "command", command: nodeCmd("migration-guard.js"), timeout: 10 },
               { type: "command", command: nodeCmd("secret-guard.js"), timeout: 10, statusMessage: "⬢ Scanning staged content for secrets..." },
             ],
           },