karajan-code 3.1.0 → 3.2.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.1.0 released** — first minor on v3. Bundles tool-correctness judge and TDD-discipline as new quality gates, `kj clean --all/--vector-stores/--repo` for housekeeping, `kj sync --apply` closing the SPDD loop, semantic test-diet auditor (498 test files, 0 loss-of-meaning findings), HU Board structural refactor (17 PRs), and a batch of security + flake fixes. No breaking changes; drop-in upgrade from v3.0.0. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.2.0 released** — Cost tracking end-to-end (epic KJC-PCS-0055 closed). Every `kj run` now records per-HU USD spend via the `BudgetTracker` cursor-snapshot pattern, persists it to `board.db.cost_usd`, and the HU Board surfaces both a per-card badge (`$0.02`) and a project-wide chip with per-plan breakdown. Null-safe: unmeasured HUs hide the badge instead of misleading "$0.00". Drop-in upgrade from v3.1.0. Full notes in [CHANGELOG.md](CHANGELOG.md).
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
@@ -121,7 +121,7 @@ pip install .
 
 Both options expect the `kj` binary to be on your `PATH` (via one of the methods above) — the Python wrapper does not vendor it.
 
-That's it. `kj init` auto-detects your installed agents and installs RTK for token optimization.
+That's it. `kj init` auto-detects your installed agents and installs the bundled integrations (RTK + Squeezr for token optimization; QMD for the per-project semantic wiki).
 
 ### Optional scanners for `kj audit` + `kj webperf`
 
@@ -366,14 +366,22 @@ Karajan auto-detects and auto-configures everything it can:
 
 No per-project configuration required. If you want to customize, config is layered: session > project > global.
 
+## Bundled integrations
+
+These ship with Karajan and `kj init` installs them as part of setup. They're token-efficiency layers the pipeline depends on — not nice-to-haves.
+
+| Tool | Invoked by | Why |
+|------|-----------|-----|
+| [**RTK**](https://github.com/rtk-ai/rtk) | Karajan (auto, on Bash outputs) | Reduces token consumption by 60-90% on Bash command outputs |
+| [**Squeezr**](https://www.npmjs.com/package/squeezr-ai) | Karajan (auto, on agent tool outputs) | Compresses verbose tool results before they reach the agent context |
+| [**QMD**](https://github.com/manufosela/qmd) | Karajan (`kj init` auto-registers `docs/`, `.reviews/`, `.karajan/plans/`); you (via `kj qmd query`) | Per-project semantic wiki for **humans**. Complements the **agent-facing** RAG index — `kj rag query` is what the pipeline reads; `kj qmd query` is what you read |
+
 ## Recommended companions
 
 None of these are required. Karajan runs fine on its own. They're tools that, when present, Karajan can take advantage of — or that help *you* work better around Karajan.
 
 | Tool | Invoked by | Why |
 |------|-----------|-----|
-| [**RTK**](https://github.com/rtk-ai/rtk) | Karajan (auto, on Bash outputs) | Reduces token consumption by 60-90% on Bash command outputs |
-| [**QMD**](https://github.com/manufosela/qmd) | You (CLI / MCP), complementary to RAG | Semantic search engine over Markdown corpora — works alongside `kj rag query` when you want a richer index over your own docs |
 | [**GitHub MCP**](https://github.com/github/github-mcp-server) | Your AI agent (via MCP) | Create PRs, manage issues directly from the agent |
 | [**Chrome DevTools MCP**](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Your AI agent (via MCP) | Verify UI changes visually after frontend modifications |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -26,6 +26,11 @@
   "engines": {
     "node": ">=22.22.1"
   },
+  "workspaces": [
+    "packages/ai-trash",
+    "packages/core",
+    "packages/hu-board"
+  ],
   "imports": {
     "#utils/*": "./src/utils/*",
     "#session/*": "./src/session/*",

package/packages/hu-board/package.json

@@ -13,11 +13,13 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@karajan/core": "*",
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
     "express": "^5.1.0",
     "express-rate-limit": "^8.5.0",
-    "helmet": "^8.1.0"
+    "helmet": "^8.1.0",
+    "js-yaml": "^4.2.0"
   },
   "devDependencies": {
     "supertest": "^7.1.0",

package/packages/hu-board/public/index.html

@@ -26,6 +26,7 @@
       <button class="nav-btn" data-view="sessions" title="Every kj run that has touched the board, newest first. Filter by project; click a session to inspect its iterations, commits and checkpoints.">Sessions</button>
       <a class="nav-btn" href="/pipeline.html" title="Live observability of pipeline runs (Karajan v2.7+): stage timings, agent calls, decision logs.">Pipeline</a>
       <a class="nav-btn" href="/rag.html" title="RAG retrieval-quality dashboard: chunk counts, embedder provider, db size.">RAG</a>
+      <a class="nav-btn" href="/wiki.html" title="Search the per-project QMD semantic wiki (docs, plans, reviews).">Wiki</a>
       <select class="project-select" id="project-select">
         <option value="">All Projects</option>
       </select>

package/packages/hu-board/public/styles.css

@@ -244,6 +244,17 @@ a:hover {
   font-family: var(--font-mono);
 }
 
+.section-header__cost {
+  font-size: 0.8rem;
+  color: var(--text-muted);
+  font-family: var(--font-mono);
+  padding: 2px 8px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-secondary, transparent);
+  cursor: help;
+}
+
 /* ---- Kanban Board ---- */
 .kanban {
   display: grid;
@@ -341,6 +352,12 @@ a:hover {
 .story-card__score--ok { color: var(--color-yellow); }
 .story-card__score--bad { color: var(--color-red); }
 
+.story-card__cost {
+  font-family: var(--font-mono);
+  font-size: 0.75rem;
+  color: var(--text-muted);
+}
+
 .quality-bar {
   display: inline-flex;
   gap: 1px;
@@ -939,3 +956,18 @@ body.scoped-mode .header__nav a[href="/pipeline.html"] {
 .rag-bar__label { color: var(--text-secondary, #cbd5e1); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .rag-bar__fill { display: block; height: 14px; background: linear-gradient(90deg, #7c3aed, #a78bfa); border-radius: 3px; }
 .rag-bar__value { text-align: right; color: var(--text-primary, #f8fafc); font-variant-numeric: tabular-nums; }
+
+/* KJC-TSK-0508 — Wiki panel (QMD semantic search) */
+.wiki-search { padding: 1rem; }
+.wiki-form { display: grid; grid-template-columns: 1fr 220px auto auto; gap: .5rem; align-items: center; }
+.wiki-form input[type="search"], .wiki-form input[type="text"] { padding: .5rem .75rem; border-radius: 6px; border: 1px solid var(--border, #334155); background: var(--bg-secondary, #1e1e2e); color: var(--text-primary, #f8fafc); font-size: .9rem; }
+.wiki-fast { display: flex; align-items: center; gap: .35rem; font-size: .85rem; color: var(--text-secondary, #94a3b8); }
+.wiki-hint { margin: .5rem 0 0; font-size: .8rem; color: var(--text-secondary, #94a3b8); font-style: italic; }
+.wiki-results { display: grid; gap: .75rem; padding: 0 1rem 1rem; }
+.wiki-hit { background: var(--bg-secondary, #1e1e2e); border-radius: 8px; padding: .9rem 1rem; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+.wiki-hit__head { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: .4rem; }
+.wiki-hit__src { font-family: ui-monospace, monospace; font-size: .85rem; color: #a78bfa; }
+.wiki-hit__score { font-size: .75rem; color: var(--text-secondary, #94a3b8); font-variant-numeric: tabular-nums; }
+.wiki-hit__snip { margin: 0; font-family: ui-monospace, monospace; font-size: .82rem; line-height: 1.45; color: var(--text-primary, #f8fafc); white-space: pre-wrap; word-break: break-word; }
+.wiki-code { background: #0f172a; color: #e2e8f0; padding: .5rem .75rem; border-radius: 6px; font-family: ui-monospace, monospace; font-size: .85rem; margin: .5rem 0; }
+@media (max-width: 720px) { .wiki-form { grid-template-columns: 1fr; } }

package/packages/hu-board/public/utils/board-view.js

@@ -35,7 +35,11 @@ async function renderBoard() {
       return;
     }
 
-    const stories = await api(`/api/projects/${encodeURIComponent(selectedProject)}/stories`);
+    const [stories, projectCost] = await Promise.all([
+      api(`/api/projects/${encodeURIComponent(selectedProject)}/stories`),
+      api(`/api/projects/${encodeURIComponent(selectedProject)}/cost`).catch(() => null),
+    ]);
+    const costSummary = projectCost ? formatProjectCostSummary(projectCost) : null;
 
     // Pre-resolve project initials + name for every distinct project_id in
     // the fetched stories so `renderStoryCard` is synchronous and the header
@@ -96,6 +100,7 @@ async function renderBoard() {
                   onclick="event.stopPropagation(); window.renameProjectModal('${esc(selectedProject)}', '${esc(projectDisplayName.replace(/'/g, '&#39;'))}');">✎</button>
         ` : ''}
         <span class="section-header__count">${stories.length} stories</span>
+        ${costSummary ? `<span class="section-header__cost" title="${esc(costSummary.tooltip)}">💵 ${esc(costSummary.label)}</span>` : ''}
         ${isRunning ? `
           <button id="running-badge-btn" class="section-header__badge"
                 style="margin-left:auto;padding:4px 10px;font-size:0.8rem;background:var(--color-yellow,#eab308);color:#000;border-radius:var(--radius-sm);font-weight:600;border:none;cursor:pointer;"
@@ -372,6 +377,10 @@ function renderStoryCard(story) {
             ${story.quality_total}/60 ${qualityBar(story.quality_total)}
           </span>
         ` : ''}
+        ${(() => {
+          const c = formatCost(story.cost_usd);
+          return c ? `<span class="story-card__cost" title="${esc(c.tooltip)}">💵 ${esc(c.label)}</span>` : '';
+        })()}
       </div>
       ${missingTestContract ? `
         <div class="story-card__meta" style="margin-top:4px;font-size:0.75rem;color:var(--color-yellow,#eab308);font-weight:600" title="This HU has no acceptance_tests declared — Run plan will reject it until you add at least one.">

package/packages/hu-board/public/utils/formatters.js

@@ -45,6 +45,47 @@ function formatSessionLabel(session) {
   };
 }
 
+function formatCost(costUsd) {
+  if (costUsd === null || costUsd === undefined) return null;
+  const n = Number(costUsd);
+  if (!Number.isFinite(n)) return null;
+  return {
+    label: `$${n.toFixed(2)}`,
+    tooltip: `Estimated cost: $${n.toFixed(4)}`,
+  };
+}
+
+function formatProjectCostSummary(cost) {
+  if (!cost || typeof cost !== "object") return null;
+  const total = Number(cost.totalUsd);
+  if (!Number.isFinite(total)) return null;
+  const byPlan = Array.isArray(cost.byPlan) ? cost.byPlan : [];
+  if (total === 0 && byPlan.length === 0) return null;
+
+  const lines = [`Total: $${total.toFixed(4)}`];
+  if (byPlan.length > 0) {
+    lines.push("By plan:");
+    for (const p of byPlan) {
+      const planTotal = Number(p?.totalUsd);
+      if (!Number.isFinite(planTotal)) continue;
+      const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
+      const planLabel = p?.planId || "unassigned";
+      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})`);
+    }
+  }
+  const unk = cost.unknownModelTokens;
+  if (unk && Number.isFinite(unk.tokensIn) && Number.isFinite(unk.tokensOut)) {
+    const unkTotal = unk.tokensIn + unk.tokensOut;
+    if (unkTotal > 0) {
+      lines.push(`(${unkTotal} tokens with unknown pricing not included)`);
+    }
+  }
+  return {
+    label: `Total: $${total.toFixed(2)}`,
+    tooltip: lines.join("\n"),
+  };
+}
+
 function humaniseProjectName(id) {
   if (!id || typeof id !== 'string') return id || '';
   const tail = id.split(/[/_]/).filter(Boolean).pop() || id;

package/packages/hu-board/public/wiki.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Karajan Wiki · QMD semantic search</title>
+  <link rel="stylesheet" href="/styles.css">
+</head>
+<body>
+  <header class="header">
+    <div class="header__logo"><div><div class="header__title">Karajan Wiki</div><div class="header__subtitle">QMD semantic search</div></div></div>
+    <nav class="header__nav">
+      <a class="nav-btn" href="/">← Board</a>
+      <a class="nav-btn" href="/rag.html">RAG</a>
+      <button class="nav-btn active">Wiki</button>
+    </nav>
+  </header>
+  <main class="main" id="wiki-app">
+    <section class="wiki-search">
+      <form id="wiki-form" class="wiki-form" autocomplete="off">
+        <input id="wiki-q" type="search" placeholder="Search the project wiki…" aria-label="Query" required>
+        <input id="wiki-collection" type="text" placeholder="collection (optional)" aria-label="Collection">
+        <label class="wiki-fast"><input id="wiki-fast" type="checkbox"> fast (no rerank)</label>
+        <button type="submit" class="control-btn" id="wiki-go">Search</button>
+      </form>
+      <p class="wiki-hint">QMD runs locally — 0 tokens, ~60s with rerank, ~5s in fast mode.</p>
+    </section>
+    <section id="wiki-results" class="wiki-results"></section>
+  </main>
+  <script src="/wiki.js"></script>
+</body>
+</html>

package/packages/hu-board/public/wiki.js

@@ -0,0 +1,53 @@
+// KJC-TSK-0508 — HU Board Wiki panel frontend. Calls POST /api/wiki/query
+// (server-side spawns `qmd query --format json`) and renders the hits.
+// A 503 with `installable:true` triggers an "Install QMD" CTA instead of
+// a generic error so the user can act on the missing binary.
+const TOKEN = new URLSearchParams(location.search).get("token") || localStorage.getItem("kj_board_token") || "";
+const HEADERS = { "Content-Type": "application/json", ...(TOKEN ? { Authorization: `Bearer ${TOKEN}` } : {}) };
+const ESC = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+
+function renderInstallCTA(root) {
+  root.innerHTML = `<div class="rag-card rag-card--error">
+    <h3>QMD not installed</h3>
+    <p>The semantic wiki engine is not available on this host. Install it once:</p>
+    <pre class="wiki-code">npm install -g @tobilu/qmd</pre>
+    <p class="rag-stat-sub">Then re-run <code>kj init</code> in this project to register the wiki collection.</p>
+  </div>`;
+}
+
+function renderHits(root, results) {
+  if (!Array.isArray(results) || results.length === 0) {
+    root.innerHTML = '<p class="rag-empty">no hits — try a broader query or run <code>qmd update</code>.</p>';
+    return;
+  }
+  root.innerHTML = results.map((r) => {
+    const src = r.source || r.path || r.file || "(unknown source)";
+    const snip = r.snippet || r.text || r.content || "";
+    const score = typeof r.score === "number" ? r.score.toFixed(3) : "";
+    return `<article class="wiki-hit">
+      <header class="wiki-hit__head"><span class="wiki-hit__src">${ESC(src)}</span>${score ? `<span class="wiki-hit__score">${ESC(score)}</span>` : ""}</header>
+      <pre class="wiki-hit__snip">${ESC(snip)}</pre>
+    </article>`;
+  }).join("");
+}
+
+async function runSearch(ev) {
+  ev?.preventDefault();
+  const root = document.getElementById("wiki-results");
+  const query = document.getElementById("wiki-q").value.trim();
+  if (!query) return;
+  const collection = document.getElementById("wiki-collection").value.trim() || undefined;
+  const fast = document.getElementById("wiki-fast").checked;
+  root.innerHTML = '<div class="loading"><div class="loading__spinner"></div><p>Searching the wiki…</p></div>';
+  try {
+    const res = await fetch("/api/wiki/query", { method: "POST", headers: HEADERS, body: JSON.stringify({ query, collection, fast }) });
+    const data = await res.json().catch(() => ({}));
+    if (res.status === 503 && data.installable) { renderInstallCTA(root); return; }
+    if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+    renderHits(root, data.results);
+  } catch (err) {
+    root.innerHTML = `<div class="rag-card rag-card--error"><strong>Error:</strong> ${ESC(err.message || String(err))}</div>`;
+  }
+}
+
+document.getElementById("wiki-form").addEventListener("submit", runSearch);

package/packages/hu-board/src/db.js

@@ -323,6 +323,11 @@ export function initDb() {
   // unconditionally so solo devs who later promote a plan don't lose
   // values they typed pre-share.
   try { db.exec('ALTER TABLE stories ADD COLUMN assignee TEXT'); } catch { /* already migrated */ }
+  // KJC-TSK-0514 (Cost C): persisted USD cost of running this HU. NULL
+  // until the orchestrator (Cost D) calls setStoryCost on HU close. UI
+  // renders "—" while NULL. Stored as REAL so the SQL aggregations in
+  // Cost E (/api/projects/:id/cost) can SUM directly without parsing.
+  try { db.exec('ALTER TABLE stories ADD COLUMN cost_usd REAL'); } catch { /* already migrated */ }
   try { db.exec('CREATE INDEX IF NOT EXISTS idx_stories_plan ON stories(plan_id)'); } catch { /* ignore */ }
 
   // is_test (KJC-TSK-0371 — board polish #3): per-project flag that
@@ -499,6 +504,32 @@ export function updateStoryStatus(storyId, status) {
   return res.changes > 0;
 }
 
+/**
+ * Persist the USD cost of a HU. Called by the orchestrator (Cost D) once
+ * the HU finishes — the value comes from `aggregateRunCost(events).totalUsd`
+ * (Cost B). `null` clears the cell so the UI renders "—" again. Other
+ * numeric inputs are coerced via `Number`; non-finite values reject with
+ * an explicit throw so callers don't silently NULL-out real cost rows.
+ *
+ * @param {string} storyId
+ * @param {number|null} costUsd
+ * @returns {boolean} true when the row existed and was updated
+ */
+export function setStoryCost(storyId, costUsd) {
+  let value = null;
+  if (costUsd !== null && costUsd !== undefined) {
+    const n = Number(costUsd);
+    if (!Number.isFinite(n)) {
+      throw new Error(`setStoryCost: costUsd must be a finite number or null (got ${costUsd})`);
+    }
+    value = n;
+  }
+  const res = getDb()
+    .prepare('UPDATE stories SET cost_usd = ?, updated_at = ? WHERE id = ?')
+    .run(value, new Date().toISOString(), storyId);
+  return res.changes > 0;
+}
+
 /**
  * List every distinct `plan_id` stamped on the stories of a given project.
  * Used by "mark plan ready" so the board can act on each plan of a project
@@ -598,6 +629,53 @@ export function getStoriesByProject(projectId) {
   `).all(projectId);
 }
 
+/**
+ * Aggregate $ cost for a project (KJC-TSK-0516, Cost E).
+ * Sums stories.cost_usd, groups by plan_id ('unassigned' for NULL).
+ * Returns null if project does not exist; otherwise an object with
+ * totalUsd=0 and byPlan=[] when no stories carry cost_usd yet.
+ * @param {string} projectId
+ * @returns {{ totalUsd:number, byPlan:Array<{planId:string,totalUsd:number,huCount:number}>, unknownModelTokens:object, currency:string } | null}
+ */
+export function getProjectCost(projectId) {
+  const project = getDb()
+    .prepare('SELECT id FROM projects WHERE id = ?')
+    .get(projectId);
+  if (!project) return null;
+
+  const rows = getDb()
+    .prepare(
+      `SELECT plan_id, cost_usd FROM stories
+       WHERE project_id = ? AND cost_usd IS NOT NULL`
+    )
+    .all(projectId);
+
+  const round4 = (n) => Math.round(n * 10000) / 10000;
+  const byPlanMap = new Map();
+  let totalUsd = 0;
+  for (const r of rows) {
+    const planId = r.plan_id || 'unassigned';
+    const cost = Number(r.cost_usd);
+    if (!Number.isFinite(cost)) continue;
+    totalUsd += cost;
+    const cur = byPlanMap.get(planId) || { planId, totalUsd: 0, huCount: 0 };
+    cur.totalUsd += cost;
+    cur.huCount += 1;
+    byPlanMap.set(planId, cur);
+  }
+
+  const byPlan = Array.from(byPlanMap.values())
+    .map((p) => ({ planId: p.planId, totalUsd: round4(p.totalUsd), huCount: p.huCount }))
+    .sort((a, b) => b.totalUsd - a.totalUsd);
+
+  return {
+    totalUsd: round4(totalUsd),
+    byPlan,
+    unknownModelTokens: { tokensIn: 0, tokensOut: 0, models: [] },
+    currency: 'USD',
+  };
+}
+
 /**
  * Returns full story detail including context requests.
  * @param {string} storyId

package/packages/hu-board/src/format.js

@@ -60,6 +60,85 @@ export function shortTask(text, max = MAX_TASK_CHARS) {
  *           created_at?: string|null }} session
  * @returns {{ title: string, subtitle: string, idChip: string }}
  */
+/**
+ * Format a per-HU cost (USD) for the card badge. Cost F (KJC-TSK-0517).
+ *
+ * Two outputs in one call so the UI can render both at once:
+ *   - `label`: 2-decimal "$X.XX" shown on the card (compact).
+ *   - `tooltip`: 4-decimal "Estimated cost: $X.XXXX" shown on hover
+ *     (matches the precision aggregated by Cost B/C/D, see
+ *     `packages/core/src/cost/index.js`).
+ *
+ * Returns `null` for null/undefined/non-finite inputs so the caller
+ * skips the badge entirely (rendering "$0.00" for an unknown cost
+ * would be misleading — there is a real difference between "we know it
+ * was free" and "we haven't measured it yet").
+ *
+ * @param {number|null|undefined} costUsd
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatCost(costUsd) {
+  if (costUsd === null || costUsd === undefined) return null;
+  const n = Number(costUsd);
+  if (!Number.isFinite(n)) return null;
+  return {
+    label: `$${n.toFixed(2)}`,
+    tooltip: `Estimated cost: $${n.toFixed(4)}`,
+  };
+}
+
+/**
+ * Format the aggregated project-level cost chip rendered in the board
+ * header. Cost G (KJC-TSK-0518). Consumes the shape returned by
+ * `GET /api/projects/:id/cost` (Cost E):
+ *   { totalUsd, byPlan: [{planId, totalUsd, huCount}, …],
+ *     unknownModelTokens: { tokensIn, tokensOut, models }, currency }
+ *
+ * Returns `{ label, tooltip }` where:
+ *   - `label` is the compact "Total: $X.XX" shown in the header.
+ *   - `tooltip` is a multi-line string with full precision, the
+ *     per-plan breakdown, and a note when some tokens used a model we
+ *     don't price (they aren't included in the total — surfacing the
+ *     skip is more honest than silently swallowing it).
+ *
+ * Returns `null` when there is nothing to show (no input, or no
+ * measured cost yet and no plans). The chip is then hidden — same
+ * reasoning as `formatCost`: "$0.00" with no data is misleading.
+ *
+ * @param {{totalUsd:number, byPlan?:Array, unknownModelTokens?:object}|null|undefined} cost
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatProjectCostSummary(cost) {
+  if (!cost || typeof cost !== "object") return null;
+  const total = Number(cost.totalUsd);
+  if (!Number.isFinite(total)) return null;
+  const byPlan = Array.isArray(cost.byPlan) ? cost.byPlan : [];
+  if (total === 0 && byPlan.length === 0) return null;
+
+  const lines = [`Total: $${total.toFixed(4)}`];
+  if (byPlan.length > 0) {
+    lines.push("By plan:");
+    for (const p of byPlan) {
+      const planTotal = Number(p?.totalUsd);
+      if (!Number.isFinite(planTotal)) continue;
+      const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
+      const planLabel = p?.planId || "unassigned";
+      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})`);
+    }
+  }
+  const unk = cost.unknownModelTokens;
+  if (unk && Number.isFinite(unk.tokensIn) && Number.isFinite(unk.tokensOut)) {
+    const unkTotal = unk.tokensIn + unk.tokensOut;
+    if (unkTotal > 0) {
+      lines.push(`(${unkTotal} tokens with unknown pricing not included)`);
+    }
+  }
+  return {
+    label: `Total: $${total.toFixed(2)}`,
+    tooltip: lines.join("\n"),
+  };
+}
+
 export function formatSessionLabel(session) {
   if (!session || !session.id) {
     return { title: "(no session)", subtitle: "", idChip: "" };

package/packages/hu-board/src/plan-mutations.js

@@ -17,13 +17,13 @@
 import { readFileSync, existsSync, readdirSync, mkdirSync, openSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { writeJsonAtomicSync } from '../../../src/utils/atomic-write.js';
+import { writeJsonAtomicSync } from '@karajan/core/atomic-write';
 import { spawn } from 'node:child_process';
 import { trackRun, untrack } from './run-tracker.js';
 import { getHuBoardRunsDir } from './db.js';
 import { fileURLToPath } from 'node:url';
-import { updateHuStatus, certifyAllHus, updateHu } from '../../../src/plan/plan-hu-ops.js';
-import { validateBlockedByChange } from '../../../src/plan/plan-validation.js';
+import { updateHuStatus, certifyAllHus, updateHu } from '@karajan/core/plan-hu-ops';
+import { validateBlockedByChange } from '@karajan/core/plan-validation';
 import { syncPlanFile } from './sync.js';
 import { getDb } from './db.js';
 
@@ -230,7 +230,7 @@ export async function revertHuFromSnapshot({ planId, huId, projectId }) {
   const projectDir = plan.projectDir;
   if (!projectDir) return { ok: false, error: 'plan sin projectDir' };
 
-  const { restoreHuSnapshot } = await import('../../../src/git/hu-snapshot.js');
+  const { restoreHuSnapshot } = await import('@karajan/core/hu-snapshot');
   const restore = await restoreHuSnapshot({ projectDir, huId });
   if (!restore.ok) return { ok: false, error: `restore falló: ${restore.error}` };
 

package/packages/hu-board/src/routes/api.js

@@ -22,6 +22,7 @@ import {
   listPlanIdsForProject,
   updateStoryStatus,
   setProjectIsTest,
+  getProjectCost,
 } from '../db.js';
 import { fullScan } from '../sync.js';
 import { setHuStatus, setHuFields, markPlanReady, runPlan, renameProject, revertHuFromSnapshot } from '../plan-mutations.js';
@@ -285,6 +286,20 @@ router.get('/stories/:id', (req, res) => {
   }
 });
 
+/**
+ * GET /api/projects/:id/cost - Aggregated $ cost for a project (KJC-TSK-0516).
+ * Sums stories.cost_usd, groups by plan_id, returns 404 if project missing.
+ */
+router.get('/projects/:id/cost', (req, res) => {
+  try {
+    const cost = getProjectCost(req.params.id);
+    if (!cost) return res.status(404).json({ error: 'Project not found' });
+    res.json(cost);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
 /**
  * GET /api/projects/:id/sessions - Sessions for a project.
  */
@@ -1325,7 +1340,7 @@ router.post('/rag/query', async (req, res) => {
     return res.status(400).json({ error: "'text' is required (non-empty string)" });
   }
   try {
-    const { openVecStore, countChunks } = await import('../../../../src/rag/vec-store.js');
+    const { openVecStore, countChunks } = await import('@karajan/core/vec-store');
     const { makeEmbedder } = await import('../../../../src/rag/embedders/factory.js');
     const { query } = await import('../../../../src/rag/retriever.js');
     const db = openVecStore({ dim: 768 });

package/packages/hu-board/src/routes/rag.js

@@ -5,7 +5,7 @@
 import { Router } from "express";
 import { existsSync, statSync } from "node:fs";
 import Database from "better-sqlite3";
-import { dbPath } from "../../../../src/rag/vec-store.js";
+import { dbPath } from "@karajan/core/vec-store";
 import { readConfig } from "../config-yaml.js";
 
 const router = Router();

package/packages/hu-board/src/routes/wiki.js

@@ -0,0 +1,43 @@
+// KJC-TSK-0508 — HU Board Wiki panel route.
+// POST /api/wiki/query → spawns `qmd query --format json` against the local
+// per-project QMD wiki (registered by `kj init` via KJC-TSK-0506). Returns
+// 503 with installable:true so the front renders an "Install QMD" CTA
+// instead of a generic error when the binary is missing.
+import { Router } from "express";
+import { runCommand } from "@karajan/core/process";
+
+const router = Router();
+const QMD_NOT_INSTALLED = /command not found|ENOENT|not recognized as/i;
+
+router.post("/query", async (req, res) => {
+  const raw = req.body?.query;
+  const query = typeof raw === "string" ? raw.trim() : "";
+  if (!query) return res.status(400).json({ ok: false, error: "query is required" });
+  const limit = Math.min(Math.max(parseInt(req.body?.limit, 10) || 10, 1), 50);
+  const collection = req.body?.collection ? String(req.body.collection).trim() : null;
+  const fast = req.body?.fast === true;
+
+  const args = ["query", query, "--format", "json", "-n", String(limit)];
+  if (collection) args.push("-c", collection);
+  if (fast) args.push("--no-rerank");
+
+  try {
+    const out = await runCommand("qmd", args, { timeout: 120_000 });
+    if (out.exitCode === 127 || QMD_NOT_INSTALLED.test(out.stderr || "")) {
+      return res.status(503).json({ ok: false, error: "qmd not installed", installable: true });
+    }
+    if (out.exitCode !== 0) {
+      const msg = (out.stderr || out.stdout || `qmd exit ${out.exitCode}`).trim();
+      return res.status(500).json({ ok: false, error: msg });
+    }
+    let results;
+    try { results = JSON.parse(out.stdout || "[]"); }
+    catch { return res.status(500).json({ ok: false, error: "qmd output is not valid JSON" }); }
+    res.json({ ok: true, results, count: Array.isArray(results) ? results.length : 0 });
+  } catch (err) {
+    if (err?.code === "ENOENT") return res.status(503).json({ ok: false, error: "qmd not installed", installable: true });
+    res.status(500).json({ ok: false, error: err?.message || String(err) });
+  }
+});
+
+export default router;

package/packages/hu-board/src/run-tracker.js

@@ -16,7 +16,7 @@
  * se borran como cleanup (responsabilidad de run-registry).
  */
 
-import { listActiveRuns as fsList } from "../../../src/utils/run-registry.js";
+import { listActiveRuns as fsList } from "@karajan/core/run-registry";
 
 const runs = new Map();
 let reaperTimer = null;