karajan-code 3.1.0 → 3.2.0

package/src/rag/vec-store.js

@@ -1,253 +1,17 @@
-// KJC-PCS-0049 Step 1 — Vector store sobre better-sqlite3 + sqlite-vec.
-// El RAG indexer (Step 4) escribe; el retriever (Step 5) lee. Una sola
-// DB en `~/.karajan/rag.db` por instalación.
-import { mkdirSync, existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import Database from "better-sqlite3";
-import * as sqliteVec from "sqlite-vec";
-
-import { getKarajanHome } from "../utils/paths.js";
-
-const DEFAULT_DIM = 768;
-
-export function dbPath() {
-  return process.env.KJ_RAG_DB || join(getKarajanHome(), "rag.db");
-}
-
-/**
- * Open the rag.db, load the sqlite-vec extension, and ensure the
- * chunks + vec_chunks tables exist. Idempotent: a second call against
- * the same file is a no-op past the schema creation.
- *
- * Returns the open Database handle. Caller owns close().
- *
- * @param {Object} [opts]
- * @param {number} [opts.dim=768] — embedding dimension. Must match
- *   the embedder configured for the project (Step 2). Changing it
- *   later requires a fresh DB; the constant is captured in the
- *   virtual table DDL.
- */
-export function openVecStore({ dim = DEFAULT_DIM, path = dbPath() } = {}) {
-  if (!existsSync(dirname(path))) mkdirSync(dirname(path), { recursive: true });
-  const db = new Database(path);
-  sqliteVec.load(db);
-  db.pragma("journal_mode = WAL");
-  db.pragma("foreign_keys = ON");
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS chunks (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      source TEXT NOT NULL,
-      kind TEXT NOT NULL CHECK (kind IN ('plan', 'code', 'onboarding')),
-      text TEXT NOT NULL,
-      metadata TEXT,
-      created_at TEXT NOT NULL DEFAULT (datetime('now'))
-    );
-    CREATE INDEX IF NOT EXISTS chunks_by_source ON chunks(source);
-    CREATE INDEX IF NOT EXISTS chunks_by_kind ON chunks(kind);
-  `);
-  // KJC-TSK-0438 — Project isolation. project_slug = basename of projectDir
-  // normalized; chunks indexed before the migration carry NULL and remain
-  // queryable when `--project all` (or no slug detected at query time).
-  const cols = db.prepare("PRAGMA table_info(chunks)").all().map((c) => c.name);
-  if (!cols.includes("project_slug")) {
-    db.exec("ALTER TABLE chunks ADD COLUMN project_slug TEXT;");
-    db.exec("CREATE INDEX IF NOT EXISTS chunks_by_project ON chunks(project_slug);");
-  }
-  // KJC-TSK-0484 — Content-hash dedup. SHA-256 of the chunk text lets the
-  // indexer skip embedding bodies it has already seen for the same project.
-  // Older rows keep NULL; the lookup ignores NULLs so they neither dedup
-  // nor get deduped until they are re-indexed and stamped.
-  if (!cols.includes("content_hash")) {
-    db.exec("ALTER TABLE chunks ADD COLUMN content_hash TEXT;");
-    db.exec("CREATE INDEX IF NOT EXISTS chunks_by_hash ON chunks(content_hash, project_slug);");
-  }
-  // KJC-TSK-0455 — Auto-update by commit diff. Per-project metadata tracks
-  // the last commit whose changes were reflected in the index, so subsequent
-  // `kj rag index --since auto` invocations (and the post-merge hook / pre-run
-  // drift check landed in PR2) only re-embed the actual delta instead of the
-  // whole project.
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS vec_store_meta (
-      project_slug TEXT PRIMARY KEY,
-      last_indexed_commit TEXT,
-      last_indexed_at TEXT NOT NULL DEFAULT (datetime('now'))
-    );
-  `);
-  db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(embedding float[${dim}]);`);
-  // KJC-TSK-0443 — FTS5 keyword index for BM25 hybrid scoring. content='chunks'
-  // makes it a contentless mirror linked by id (no double storage); triggers
-  // sync the FTS5 rows on insert/update/delete. Rebuilds idempotently when
-  // the FTS5 table exists but is empty (e.g. created post-migration on a
-  // DB with pre-v2.28 chunks).
-  db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(text, content='chunks', content_rowid='id');
-    CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
-      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
-    END;
-    CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
-      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
-    END;
-    CREATE TRIGGER IF NOT EXISTS chunks_au AFTER UPDATE ON chunks BEGIN
-      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
-      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
-    END;
-  `);
-  const ftsCount = db.prepare("SELECT COUNT(*) AS n FROM chunks_fts").get().n;
-  const chunksCount = db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
-  if (ftsCount === 0 && chunksCount > 0) {
-    db.exec("INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild');");
-  }
-  return db;
-}
-
-/**
- * Persist one chunk. The chunks.id and vec_chunks.rowid stay in sync
- * because the virtual table rowid is set explicitly to the freshly
- * minted chunks.id. Returns that id.
- */
-export function insertChunk(db, { source, kind, text, metadata = null, embedding, project = null, contentHash = null }) {
-  if (!Array.isArray(embedding) && !ArrayBuffer.isView(embedding)) {
-    throw new Error("insertChunk: embedding must be an array or typed array of floats");
-  }
-  const meta = metadata == null ? null : (typeof metadata === "string" ? metadata : JSON.stringify(metadata));
-  const ins = db.prepare("INSERT INTO chunks (source, kind, text, metadata, project_slug, content_hash) VALUES (?, ?, ?, ?, ?, ?)");
-  const info = ins.run(source, kind, text, meta, project, contentHash);
-  // sqlite-vec's vec0 virtual table requires the rowid to arrive as a BigInt
-  // even for values that comfortably fit in a Number. Better-sqlite3 returns
-  // lastInsertRowid as BigInt only when safeIntegers mode is on; force it.
-  const id = typeof info.lastInsertRowid === "bigint" ? info.lastInsertRowid : BigInt(info.lastInsertRowid);
-  const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
-  db.prepare("INSERT INTO vec_chunks(rowid, embedding) VALUES (?, ?)").run(id, Buffer.from(buf.buffer));
-  return Number(id);
-}
-
-/**
- * Cosine-ordered nearest-neighbour search. Returns `[{ id, source, kind,
- * text, metadata, distance }]` for the topK best matches; lower
- * distance = closer. Returns `[]` when the store is empty.
- */
-export function searchSimilar(db, embedding, topK = 5, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
-  const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
-  const kindClause = kind ? "AND c.kind = ?" : "";
-  const projectClause = project ? "AND c.project_slug = ?" : "";
-  const sql = `
-    SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, v.distance
-    FROM vec_chunks v
-    JOIN chunks c ON c.id = v.rowid
-    WHERE v.embedding MATCH ? AND k = ? ${kindClause} ${projectClause}${whereSql}
-    ORDER BY v.distance
-  `;
-  const params = [Buffer.from(buf.buffer), topK];
-  if (kind) params.push(kind);
-  if (project) params.push(project);
-  if (whereParams.length) params.push(...whereParams);
-  const rows = db.prepare(sql).all(...params);
-  return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
-}
-
-/**
- * Normalize a projectDir into a stable slug used for project isolation.
- * Basename → lowercased → non-alphanumeric stripped to dashes.
- * KJC-TSK-0438.
- */
-export function projectSlug(projectDir) {
-  if (!projectDir) return null;
-  const base = String(projectDir).replace(/\/+$/, "").split("/").pop();
-  if (!base) return null;
-  return base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-}
-
-function safeParse(s) { try { return JSON.parse(s); } catch { return s; } }
-
-/**
- * Remove every chunk that came from a given source path. Both tables
- * are touched explicitly because vec0 virtual tables do not honour
- * SQLite foreign-key cascades.
- */
-export function deleteChunksBySource(db, source) {
-  const ids = db.prepare("SELECT id FROM chunks WHERE source = ?").all(source).map((r) => r.id);
-  if (ids.length === 0) return 0;
-  const placeholders = ids.map(() => "?").join(",");
-  db.prepare(`DELETE FROM vec_chunks WHERE rowid IN (${placeholders})`).run(...ids);
-  db.prepare(`DELETE FROM chunks WHERE id IN (${placeholders})`).run(...ids);
-  return ids.length;
-}
-
-// KJC-TSK-0455 — Per-project commit watermark for `kj rag index --since auto`
-// and the post-merge / pre-run drift hooks landing in PR2.
-export function getLastIndexedCommit(db, projectSlug) {
-  if (!projectSlug) return null;
-  const row = db.prepare("SELECT last_indexed_commit FROM vec_store_meta WHERE project_slug = ?").get(projectSlug);
-  return row?.last_indexed_commit ?? null;
-}
-
-export function setLastIndexedCommit(db, projectSlug, commit) {
-  if (!projectSlug || !commit) return;
-  db.prepare(`
-    INSERT INTO vec_store_meta (project_slug, last_indexed_commit, last_indexed_at)
-    VALUES (?, ?, datetime('now'))
-    ON CONFLICT(project_slug) DO UPDATE SET
-      last_indexed_commit = excluded.last_indexed_commit,
-      last_indexed_at = excluded.last_indexed_at
-  `).run(projectSlug, commit);
-}
-
-// KJC-TSK-0484 PR-B — Bulk fetch embeddings for an explicit set of chunk ids.
-// Returns Map<id, Float32Array>. Used by MMR diversification in retriever.js.
-export function getEmbeddingsByIds(db, ids) {
-  const out = new Map();
-  if (!ids?.length) return out;
-  const placeholders = ids.map(() => "?").join(",");
-  const rows = db.prepare(`SELECT rowid AS id, embedding FROM vec_chunks WHERE rowid IN (${placeholders})`).all(...ids);
-  for (const row of rows) {
-    if (!row.embedding) continue;
-    const buf = Buffer.isBuffer(row.embedding) ? row.embedding : Buffer.from(row.embedding);
-    out.set(Number(row.id), new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4));
-  }
-  return out;
-}
-
-// KJC-TSK-0484 — Lookup an already-indexed chunk by content_hash. Scoped to a
-// project so two repos with the same boilerplate file don't cross-pollute.
-// Returns `{ id, source }` or null. Pass `project=null` to match NULL slugs.
-export function findChunkByHash(db, hash, project = null) {
-  if (!hash) return null;
-  const sql = project
-    ? "SELECT id, source FROM chunks WHERE content_hash = ? AND project_slug = ? LIMIT 1"
-    : "SELECT id, source FROM chunks WHERE content_hash = ? AND project_slug IS NULL LIMIT 1";
-  const row = project ? db.prepare(sql).get(hash, project) : db.prepare(sql).get(hash);
-  return row || null;
-}
-
-export function countChunks(db, { kind = null } = {}) {
-  if (kind) return db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE kind = ?").get(kind).n;
-  return db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
-}
-
-/**
- * KJC-TSK-0443 — BM25 keyword search over chunks_fts. Returns
- * [{ id, source, kind, text, metadata, project_slug, bm25 }] ordered by
- * relevance (lower bm25 = better in SQLite FTS5). `query` is sanitized for
- * the FTS5 grammar: special chars are stripped, words split on whitespace.
- */
-export function searchBM25(db, queryText, topK = 10, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
-  const cleaned = String(queryText || "").replace(/["'()]/g, " ").split(/\s+/).filter(Boolean).join(" OR ");
-  if (!cleaned) return [];
-  const kindClause = kind ? "AND c.kind = ?" : "";
-  const projectClause = project ? "AND c.project_slug = ?" : "";
-  const sql = `
-    SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, bm25(chunks_fts) AS bm25
-    FROM chunks_fts JOIN chunks c ON c.id = chunks_fts.rowid
-    WHERE chunks_fts MATCH ? ${kindClause} ${projectClause}${whereSql}
-    ORDER BY bm25 LIMIT ?
-  `;
-  const params = [cleaned];
-  if (kind) params.push(kind);
-  if (project) params.push(project);
-  if (whereParams.length) params.push(...whereParams);
-  params.push(topK);
-  try {
-    const rows = db.prepare(sql).all(...params);
-    return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
-  } catch { return []; }
-}
+// Shim: vec-store primitives now live in @karajan/core/vec-store so
+// the hu-board workspace can consume them without a relative dep on the
+// CLI src tree. KJC-TSK-0511 PR4.
+export {
+  dbPath,
+  openVecStore,
+  insertChunk,
+  searchSimilar,
+  projectSlug,
+  deleteChunksBySource,
+  getLastIndexedCommit,
+  setLastIndexedCommit,
+  getEmbeddingsByIds,
+  findChunkByHash,
+  countChunks,
+  searchBM25,
+} from "@karajan/core/vec-store";

package/src/roles/audit-role.js

@@ -9,6 +9,7 @@ import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 import { collectCircularDeps } from "../audit/circular-deps.js";
 import { collectDeadExports } from "../audit/dead-exports.js";
 import { collectInjectionFindings } from "../audit/injection-findings.js";
+import { collectAiSlop } from "../audit/ai-slop-findings.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -53,6 +54,7 @@ export class AuditRole extends AgentRole {
     const noMadge = typeof input === "object" ? Boolean(input?.noMadge) : false;
     const noKnip = typeof input === "object" ? Boolean(input?.noKnip) : false;
     const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
+    const noAiSlop = typeof input === "object" ? Boolean(input?.noAiSlop) : false;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
@@ -64,6 +66,7 @@ export class AuditRole extends AgentRole {
     let circularDeps = null;
     let deadExports = null;
     let injectionFindings = null;
+    let aiSlop = null;
     try {
       basalCost = await measureBasalCost(projectDir);
       const previous = await loadPreviousAudit(projectDir);
@@ -116,7 +119,14 @@ export class AuditRole extends AgentRole {
         injectionFindings = await collectInjectionFindings(projectDir, this.logger);
       } catch { /* injection scan is best-effort (KJC-TSK-0498) */ }
     }
-    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings };
+    // AI-slop tells (KJC-TSK-0503). Deterministic, offline, regex-based.
+    // Local equivalent of Deslopify-style review. Best-effort.
+    if (!noAiSlop) {
+      try {
+        aiSlop = await collectAiSlop(projectDir);
+      } catch { /* ai-slop scan is best-effort */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, aiSlop };
   }
 
   /**

package/src/utils/ai-trash.js

@@ -0,0 +1,48 @@
+// ai-trash detection + Claude Code hook install (KJC-TSK-0391).
+// `kj-trash` is the binary shipped by the @karajan/ai-trash workspace.
+// detectAiTrash() probes the binary; installAiTrashHook() invokes
+// `kj-trash install --claude-code`, which idempotently patches
+// ~/.claude/settings.json to register the PreToolUse hook.
+
+import { runCommand } from "./process.js";
+
+/**
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectAiTrash() {
+  try {
+    const res = await runCommand("kj-trash", ["--help"]);
+    if (res.exitCode === 0 || res.exitCode === 2) {
+      return { available: true, version: "0.0.0" };
+    }
+    return { available: false, version: null };
+  } catch {
+    return { available: false, version: null };
+  }
+}
+
+/**
+ * Register the kj-trash PreToolUse hook in ~/.claude/settings.json.
+ * Idempotent: second run reports "already installed" without rewriting.
+ *
+ * @param {object} logger - logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, mutated: boolean, error: string|null }>}
+ */
+export async function installAiTrashHook(logger) {
+  logger.info("Registering ai-trash Claude Code hook...");
+  try {
+    const res = await runCommand("kj-trash", ["install", "--claude-code"], { timeout: 30_000 });
+    if (res.exitCode !== 0) {
+      const error = (res.stderr || "").trim() || `exit code ${res.exitCode}`;
+      logger.warn(`ai-trash hook install failed: ${error}`);
+      return { ok: false, mutated: false, error };
+    }
+    const mutated = !(res.stdout || "").includes("already installed");
+    logger.info(mutated ? "ai-trash hook installed." : "ai-trash hook already installed.");
+    return { ok: true, mutated, error: null };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`ai-trash hook install failed: ${error}`);
+    return { ok: false, mutated: false, error };
+  }
+}

package/src/utils/atomic-write.js

@@ -1,43 +1,6 @@
-// Atomic JSON writes for persistent state (resilience audit, Phase 2).
-//
-// A plain `writeFile(path, JSON.stringify(...))` truncates the live file
-// before the new content lands. If the process is killed mid-write
-// (SIGKILL, crash, power loss) the file is left truncated and the only
-// good copy is already gone — the plan / session / standby JSON
-// silently corrupts.
-//
-// write-temp + rename fixes it: `rename` is atomic on the same
-// filesystem, so a reader sees either the old file or the complete new
-// one, never a half-written one. The temp file sits next to the target
-// (same dir → same FS) and is uniquely named so concurrent writers do
-// not clobber each other's temp. A crash before the rename leaves an
-// orphan `.tmp` but never a corrupt target.
-
-import { writeFileSync, renameSync } from "node:fs";
-import { writeFile, rename } from "node:fs/promises";
-
-function tempPath(target) {
-  return `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
-}
-
-/**
- * Atomically write `obj` as pretty JSON to `target` (synchronous).
- * @param {string} target - destination path; its directory must exist
- * @param {unknown} obj
- */
-export function writeJsonAtomicSync(target, obj) {
-  const tmp = tempPath(target);
-  writeFileSync(tmp, JSON.stringify(obj, null, 2), "utf-8");
-  renameSync(tmp, target);
-}
-
-/**
- * Atomically write `obj` as pretty JSON to `target` (async).
- * @param {string} target - destination path; its directory must exist
- * @param {unknown} obj
- */
-export async function writeJsonAtomic(target, obj) {
-  const tmp = tempPath(target);
-  await writeFile(tmp, JSON.stringify(obj, null, 2), "utf-8");
-  await rename(tmp, target);
-}
+// Shim — the real implementation now lives in @karajan/core/atomic-write.
+// Kept here so CLI callers (src/**/*.js) keep importing
+// "#utils/atomic-write.js" without churn during KJC-TSK-0511 (decouple
+// @karajan/hu-board). Will be retired once every consumer migrates to
+// the @karajan/core import.
+export { writeJsonAtomic, writeJsonAtomicSync } from "@karajan/core/atomic-write";

package/src/utils/cli-ask-question.js

@@ -0,0 +1,76 @@
+import readline from "node:readline";
+
+/**
+ * Shared askQuestion factory used by `kj run` and `kj resume`.
+ *
+ * Pre-fix (KJC-BUG-0081 round 1), `src/commands/run.js` got the guard
+ * but `src/commands/resume.js` kept its own copy without the guard, so
+ * `kj resume --yes` in non-TTY mode still hung on the HU Board bridge.
+ * Centralising the three paths here means both commands honour the
+ * same contract and a future fix only needs to land in one place.
+ *
+ * Three paths:
+ *   1. Interactive TTY: prompt via readline (developer terminal).
+ *   2. No TTY + `flags.yes`: caller asked NOT to be prompted → write
+ *      question + context to stderr, return null so the run aborts
+ *      fast and loud (CI / scripted / `kj audit --yes` desatendido).
+ *   3. No TTY without `flags.yes` (HU Board ▶ Run plan with
+ *      `stdio=ignore`): publish through the file-based bridge so the
+ *      board can surface a modal; block until the user answers.
+ *
+ * @param {object} [opts]
+ * @param {string|null} [opts.sessionId]
+ * @param {object} [opts.flags]
+ * @returns {(question: string, context?: object) => Promise<string|null>}
+ */
+export function createCliAskQuestion(opts = {}) {
+  const { sessionId = null, flags = {} } = opts;
+  return async (question, context) => {
+    const stdinReadable = process.stdin && process.stdin.readable !== false;
+    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
+    if (!isInteractive) {
+      if (flags?.yes) {
+        process.stderr.write(
+          `\n[non-interactive --yes] Pipeline asked a question that cannot be auto-answered:\n`
+          + `  ❓ ${question}\n`
+          + (context?.detail ? `  Context: ${JSON.stringify(context.detail)}\n` : "")
+          + `  Stopping the session. Re-run without --yes (TTY or HU Board) to answer it,\n`
+          + `  or pass --skip-spec-review / a more complete spec so the question never appears.\n`
+        );
+        return null;
+      }
+      const { askThroughBoard } = await import("./board-prompt-bridge.js");
+      console.log(`\n❓ ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      console.log(
+        "\n[non-interactive] Routing the prompt to the HU Board.\n"
+        + "  Open http://localhost:4000 — a modal will appear asking for your answer.\n"
+        + "  This process is now waiting; closing the board does NOT cancel the run."
+      );
+      try {
+        return await askThroughBoard({ sessionId, question, context });
+      } catch (err) {
+        console.log(`\n[prompt-bridge] ${err.message} — stopping the session.`);
+        return null;
+      }
+    }
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      console.log(`\n❓ ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
+        rl.close();
+        if (answer.trim().toLowerCase() === "stop") {
+          resolve(null);
+        } else {
+          resolve(answer.trim());
+        }
+      });
+    });
+  };
+}

package/src/utils/doc-links.js

@@ -15,6 +15,8 @@ const ERROR_DOCS = {
   config_missing: `${BASE_URL}/getting-started/quick-start/`,
   branch_error: `${BASE_URL}/guides/pipeline/#git-workflow`,
   rtk_install: `${BASE_URL}/guides/configuration/#rtk`,
+  squeezr_install: `${BASE_URL}/guides/configuration/#squeezr`,
+  qmd_install: `${BASE_URL}/guides/configuration/#qmd`,
 };
 
 export function docLink(errorType) {

package/src/utils/os-detect.js

@@ -16,6 +16,16 @@ const INSTALL_COMMANDS = {
     linux: "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh && rtk init --global",
     windows: "Download from https://github.com/rtk-ai/rtk/releases and add to PATH"
   },
+  squeezr: {
+    macos: "npm install -g squeezr-ai",
+    linux: "npm install -g squeezr-ai",
+    windows: "npm install -g squeezr-ai"
+  },
+  qmd: {
+    macos: "npm install -g @tobilu/qmd",
+    linux: "npm install -g @tobilu/qmd",
+    windows: "npm install -g @tobilu/qmd"
+  },
   claude: {
     macos: "npm install -g @anthropic-ai/claude-code",
     linux: "npm install -g @anthropic-ai/claude-code",

package/src/utils/paths.js

@@ -1,123 +1,14 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-// Per-process vitest root. We memoise the *root* (not the suffixed
-// `.karajan` / `.kj` path) so callers with different legacy defaults
-// — plan-store wants `.kj`, db.js wants `.karajan` — can share one
-// random tmp prefix per test run without colliding.
-let _vitestRoot = null;
-function vitestRoot() {
-  if (_vitestRoot) return _vitestRoot;
-  _vitestRoot = path.join(
-    os.tmpdir(),
-    `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
-  );
-  // KJC-BUG-0075: clean up on clean exit so /tmp doesn't accumulate one
-  // dir per fork × run. `process.on('exit')` runs synchronously and only
-  // for graceful exits — SIGKILL leaks survive but are caught by the
-  // global-setup mtime purge at the start of the next run.
-  process.on("exit", () => {
-    try {
-      fs.rmSync(_vitestRoot, { recursive: true, force: true });
-    } catch {
-      // best-effort: never crash a test process on cleanup failure
-    }
-  });
-  return _vitestRoot;
-}
-
-function vitestTmpHome(defaultSegment) {
-  return path.join(vitestRoot(), defaultSegment);
-}
-
-// One-shot warning so users with KJ_HOME set in their shell rcfile do
-// not get spammed once per `kj` invocation. Reset across processes,
-// which is the granularity that matters for a humans-reading-stderr
-// audience.
-let _kjHomeWarned = false;
-function emitKjHomeDeprecationWarning() {
-  if (_kjHomeWarned) return;
-  _kjHomeWarned = true;
-  // eslint-disable-next-line no-console
-  console.warn(
-    "\x1b[33m[warn]\x1b[0m KJ_HOME is deprecated, rename to KARAJAN_HOME (KJ_HOME will be removed in a future release)"
-  );
-}
-
-/**
- * Unified resolver for Karajan's HOME-level storage root. Used by every
- * helper that previously rolled its own `getKjHome()` with subtly
- * different defaults and VITEST handling.
- *
- * Precedence (highest first):
- *   1. KARAJAN_HOME env var — explicit, no warning
- *   2. KJ_HOME env var      — explicit, prints deprecation warning once
- *   3. VITEST tmp dir       — auto-isolation under `os.tmpdir()/karajan-vitest-<pid>-<rand>/<defaultSegment>`
- *   4. `~/<defaultSegment>` — production default
- *
- * Callers pass `defaultSegment` so we can preserve `.kj` for legacy
- * paths (plan-store, standby-store) and `.karajan` for the canonical
- * root, until PR 3 unifies the defaults too.
- *
- * @param {object} [options]
- * @param {string} [options.defaultSegment=".karajan"]  HOME subdir name
- * @returns {string} absolute path
- */
-export function resolveHome({ defaultSegment = ".karajan" } = {}) {
-  if (process.env.KARAJAN_HOME) {
-    return path.resolve(process.env.KARAJAN_HOME);
-  }
-  if (process.env.KJ_HOME) {
-    emitKjHomeDeprecationWarning();
-    return path.resolve(process.env.KJ_HOME);
-  }
-  if (process.env.VITEST) {
-    return vitestTmpHome(defaultSegment);
-  }
-  return path.join(os.homedir(), defaultSegment);
-}
-
-/**
- * Canonical Karajan home (`~/.karajan` by default). Every helper that
- * used to roll its own `getKjHome()` now goes through this one — see
- * KJC-PCS-0047 PR 3 for the consolidation.
- */
-export function getKarajanHome() {
-  return resolveHome({ defaultSegment: ".karajan" });
-}
-
-// Test-only export. Tests that depend on observing the deprecation
-// warning being emitted exactly once need to reset the latch between
-// cases.
-export function __resetKjHomeWarningForTests() {
-  _kjHomeWarned = false;
-}
-
-export function getSessionRoot() {
-  return path.join(getKarajanHome(), "sessions");
-}
-
-export function getSonarComposePath() {
-  return path.join(getKarajanHome(), "docker-compose.sonar.yml");
-}
-
-/** Ollama RAG embedder compose: `<karajan-home>/docker-compose.ollama.yml` — KJC-TSK-0435. */
-export function getOllamaComposePath() {
-  return path.join(getKarajanHome(), "docker-compose.ollama.yml");
-}
-
-/** Webperf cache: `<karajan-home>/webperf/` — KJC-TSK-0420. */
-export function getWebperfDir() {
-  return path.join(getKarajanHome(), "webperf");
-}
-
-/** Run-registry: `<karajan-home>/runs/` — KJC-TSK-0420. */
-export function getRunsDir() {
-  return path.join(getKarajanHome(), "runs");
-}
-
-/** Board prompt bridge: `<karajan-home>/prompts/` — KJC-TSK-0420. */
-export function getPromptsDir() {
-  return path.join(getKarajanHome(), "prompts");
-}
+// Shim: paths primitives now live in @karajan/core/paths so the
+// hu-board workspace can consume them without a relative dep on the
+// CLI src tree. KJC-TSK-0511 PR3.
+export {
+  resolveHome,
+  getKarajanHome,
+  __resetKjHomeWarningForTests,
+  getSessionRoot,
+  getSonarComposePath,
+  getOllamaComposePath,
+  getWebperfDir,
+  getRunsDir,
+  getPromptsDir,
+} from "@karajan/core/paths";