@yemi33/squad 0.1.12 → 0.1.13

package/dashboard.html

@@ -47,6 +47,34 @@
   .status-badge.working { background: rgba(210,153,34,0.15); color: var(--yellow); border: 1px solid var(--yellow); animation: pulse 1.5s infinite; }
   .status-badge.done { background: rgba(63,185,80,0.15); color: var(--green); border: 1px solid var(--green); }
   .agent-action { font-size: 11px; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 100%; }
+  .token-tiles { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 8px; margin-bottom: 12px; }
+  .token-tile { background: var(--surface2); border: 1px solid var(--border); border-radius: 6px; padding: 10px 12px; }
+  .token-tile-label { font-size: 10px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.5px; }
+  .token-tile-value { font-size: 20px; font-weight: 700; color: var(--text); margin-top: 2px; }
+  .token-tile-sub { font-size: 10px; color: var(--muted); margin-top: 2px; }
+  .token-chart { display: flex; align-items: flex-end; gap: 3px; height: 80px; margin: 8px 0; }
+  .token-bar { flex: 1; min-width: 8px; max-width: 24px; background: var(--blue); border-radius: 2px 2px 0 0; position: relative; cursor: default; transition: background 0.15s; }
+  .token-bar:hover { background: var(--green); }
+  .token-bar-tip { display: none; position: absolute; bottom: 100%; left: 50%; transform: translateX(-50%); background: var(--surface); border: 1px solid var(--border); border-radius: 4px; padding: 3px 6px; font-size: 9px; white-space: nowrap; z-index: 10; color: var(--text); }
+  .token-bar:hover .token-bar-tip { display: block; }
+  .token-chart-labels { display: flex; gap: 3px; }
+  .token-chart-labels span { flex: 1; min-width: 8px; max-width: 24px; font-size: 8px; color: var(--muted); text-align: center; overflow: hidden; }
+  .token-agent-table { width: 100%; margin-top: 10px; }
+  .token-agent-table th { text-align: left; font-size: 10px; color: var(--muted); font-weight: 500; padding: 4px 8px; border-bottom: 1px solid var(--border); }
+  .token-agent-table td { font-size: 11px; padding: 4px 8px; }
+  .kb-tabs { display: flex; gap: 4px; flex-wrap: wrap; margin-bottom: 8px; }
+  .kb-tab { background: var(--surface2); border: 1px solid var(--border); color: var(--muted); font-size: 11px; cursor: pointer; padding: 3px 10px; border-radius: 4px; transition: all 0.2s; }
+  .kb-tab:hover { color: var(--text); border-color: var(--text); }
+  .kb-tab.active { color: var(--blue); border-color: var(--blue); background: rgba(88,166,255,0.08); }
+  .kb-tab .badge { background: var(--border); color: var(--text); font-size: 9px; padding: 0 5px; border-radius: 8px; margin-left: 4px; }
+  .kb-list { max-height: 400px; overflow-y: auto; }
+  .kb-item { display: flex; align-items: flex-start; gap: 10px; padding: 8px 0; border-bottom: 1px solid var(--border); cursor: pointer; transition: background 0.1s; }
+  .kb-item:hover { background: var(--surface2); }
+  .kb-item:last-child { border-bottom: none; }
+  .kb-item-body { flex: 1; min-width: 0; }
+  .kb-item-title { font-size: 12px; color: var(--text); font-weight: 500; }
+  .kb-item-meta { font-size: 10px; color: var(--muted); margin-top: 2px; display: flex; gap: 8px; }
+  .kb-item-preview { font-size: 10px; color: var(--muted); margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 100%; }
   .agent-result { font-size: 10px; color: var(--text); background: var(--surface2); padding: 6px 8px; border-radius: 4px; margin-top: 6px; white-space: pre-wrap; word-break: break-word; max-height: 80px; overflow-y: auto; line-height: 1.4; border-left: 2px solid var(--blue); }
   .agent-card { min-width: 0; }
   .agent-emoji { font-size: 20px; margin-right: 4px; }
@@ -463,6 +491,12 @@
     <div id="notes-list">Loading...</div>
   </section>
 
+  <section>
+    <h2>Knowledge Base <span class="count" id="kb-count">0</span></h2>
+    <div class="kb-tabs" id="kb-tabs"></div>
+    <div class="kb-list" id="kb-list"><p class="empty">No knowledge entries yet. Notes are classified here after consolidation.</p></div>
+  </section>
+
   <section>
     <h2>Squad Skills <span class="count" id="skills-count">0</span></h2>
     <div id="skills-list"><p class="empty">No skills yet. Agents create these when they discover repeatable workflows.</p></div>
@@ -485,6 +519,11 @@
     <div id="metrics-content"><p class="empty">No metrics yet. Metrics appear after agents complete tasks.</p></div>
   </section>
 
+  <section>
+    <h2>Token Usage</h2>
+    <div id="token-usage-content"><p class="empty">No usage data yet.</p></div>
+  </section>
+
   <section class="pr-panel" id="completed-section">
     <h2>Recent Completions <span class="count" id="completed-count">0</span></h2>
     <div id="completed-content"><p class="empty">No completed dispatches yet.</p></div>
@@ -1134,6 +1173,9 @@ async function refresh() {
     renderMetrics(data.metrics || {});
     renderWorkItems(data.workItems || []);
     renderSkills(data.skills || []);
+    // Refresh KB less frequently (every 3rd cycle = ~12s)
+    if (!window._kbRefreshCount) window._kbRefreshCount = 0;
+    if (window._kbRefreshCount++ % 3 === 0) refreshKnowledgeBase();
   } catch(e) { console.error('refresh error', e); }
 }
 
@@ -1357,9 +1399,10 @@ function openAllWorkItems() {
 // -- Metrics --
 function renderMetrics(metrics) {
   const el = document.getElementById('metrics-content');
-  const agents = Object.entries(metrics);
+  const agents = Object.entries(metrics).filter(([k]) => !k.startsWith('_'));
   if (agents.length === 0) {
     el.innerHTML = '<p class="empty">No metrics yet. Metrics appear after agents complete tasks.</p>';
+    renderTokenUsage(metrics);
     return;
   }
   let html = '<table class="pr-table"><thead><tr><th>Agent</th><th>Done</th><th>Errors</th><th>PRs</th><th>Approved</th><th>Rejected</th><th>Rate</th><th>Reviews</th></tr></thead><tbody>';
@@ -1379,6 +1422,85 @@ function renderMetrics(metrics) {
   }
   html += '</tbody></table>';
   el.innerHTML = html;
+  renderTokenUsage(metrics);
+}
+
+function renderTokenUsage(metrics) {
+  const el = document.getElementById('token-usage-content');
+  const agents = Object.entries(metrics).filter(([k]) => !k.startsWith('_'));
+  const daily = metrics._daily || {};
+
+  // Aggregate totals
+  let totalCost = 0, totalInput = 0, totalOutput = 0, totalCache = 0;
+  for (const [, m] of agents) {
+    totalCost += m.totalCostUsd || 0;
+    totalInput += m.totalInputTokens || 0;
+    totalOutput += m.totalOutputTokens || 0;
+    totalCache += m.totalCacheRead || 0;
+  }
+
+  if (totalCost === 0 && Object.keys(daily).length === 0) {
+    el.innerHTML = '<p class="empty">No usage data yet. Token tracking starts on next agent completion.</p>';
+    return;
+  }
+
+  const fmtTokens = (n) => n >= 1000000 ? (n / 1000000).toFixed(1) + 'M' : n >= 1000 ? (n / 1000).toFixed(0) + 'K' : String(n);
+  const fmtCost = (n) => '$' + n.toFixed(2);
+
+  // Summary tiles
+  let html = '<div class="token-tiles">';
+  html += '<div class="token-tile"><div class="token-tile-label">Total Cost</div><div class="token-tile-value">' + fmtCost(totalCost) + '</div></div>';
+  html += '<div class="token-tile"><div class="token-tile-label">Input Tokens</div><div class="token-tile-value">' + fmtTokens(totalInput) + '</div></div>';
+  html += '<div class="token-tile"><div class="token-tile-label">Output Tokens</div><div class="token-tile-value">' + fmtTokens(totalOutput) + '</div></div>';
+  html += '<div class="token-tile"><div class="token-tile-label">Cache Reads</div><div class="token-tile-value">' + fmtTokens(totalCache) + '</div></div>';
+
+  // Today's cost
+  const today = new Date().toISOString().slice(0, 10);
+  const todayData = daily[today];
+  if (todayData) {
+    html += '<div class="token-tile"><div class="token-tile-label">Today</div><div class="token-tile-value">' + fmtCost(todayData.costUsd) + '</div><div class="token-tile-sub">' + todayData.tasks + ' tasks</div></div>';
+  }
+  html += '</div>';
+
+  // Daily bar chart (last 14 days)
+  const days = Object.keys(daily).sort().slice(-14);
+  if (days.length > 1) {
+    const maxCost = Math.max(...days.map(d => daily[d].costUsd || 0), 0.01);
+    html += '<div style="font-size:10px;color:var(--muted);margin:8px 0 4px">Daily Cost (last ' + days.length + ' days)</div>';
+    html += '<div class="token-chart">';
+    for (const day of days) {
+      const d = daily[day];
+      const pct = Math.max(((d.costUsd || 0) / maxCost) * 100, 2);
+      html += '<div class="token-bar" style="height:' + pct + '%"><div class="token-bar-tip">' + day.slice(5) + ': ' + fmtCost(d.costUsd) + ' / ' + d.tasks + ' tasks</div></div>';
+    }
+    html += '</div>';
+    html += '<div class="token-chart-labels">';
+    for (const day of days) {
+      html += '<span>' + day.slice(8) + '</span>';
+    }
+    html += '</div>';
+  }
+
+  // Per-agent token table
+  const agentsWithUsage = agents.filter(([, m]) => (m.totalCostUsd || 0) > 0);
+  if (agentsWithUsage.length > 0) {
+    html += '<table class="token-agent-table"><thead><tr><th>Agent</th><th>Cost</th><th>Input</th><th>Output</th><th>Cache</th><th>$/task</th></tr></thead><tbody>';
+    for (const [id, m] of agentsWithUsage.sort((a, b) => (b[1].totalCostUsd || 0) - (a[1].totalCostUsd || 0))) {
+      const tasks = (m.tasksCompleted || 0) + (m.tasksErrored || 0);
+      const perTask = tasks > 0 ? fmtCost((m.totalCostUsd || 0) / tasks) : '-';
+      html += '<tr>' +
+        '<td style="font-weight:600">' + escHtml(id) + '</td>' +
+        '<td>' + fmtCost(m.totalCostUsd || 0) + '</td>' +
+        '<td>' + fmtTokens(m.totalInputTokens || 0) + '</td>' +
+        '<td>' + fmtTokens(m.totalOutputTokens || 0) + '</td>' +
+        '<td>' + fmtTokens(m.totalCacheRead || 0) + '</td>' +
+        '<td style="color:var(--muted)">' + perTask + '</td>' +
+      '</tr>';
+    }
+    html += '</tbody></table>';
+  }
+
+  el.innerHTML = html;
 }
 
 // -- Command Center (Unified Input) --
@@ -1846,6 +1968,109 @@ async function cmdSubmitPrd(parsed) {
   const projLabel = (parsed.projects || []).length > 0 ? ' (' + parsed.projects.join(', ') + ')' : '';
   showToast('cmd-toast', 'PRD item ' + (data.id || id) + ' added' + projLabel, true);
 }
+// ─── Knowledge Base ──────────────────────────────────────────────────────────
+let _kbData = {};
+let _kbActiveTab = 'all';
+
+const KB_CAT_LABELS = {
+  architecture: 'Architecture',
+  conventions: 'Conventions',
+  'project-notes': 'Project Notes',
+  'build-reports': 'Build Reports',
+  reviews: 'Reviews',
+};
+const KB_CAT_ICONS = {
+  architecture: '\u{1F3D7}',
+  conventions: '\u{1F4CB}',
+  'project-notes': '\u{1F4DD}',
+  'build-reports': '\u{2699}',
+  reviews: '\u{1F50D}',
+};
+
+async function refreshKnowledgeBase() {
+  try {
+    _kbData = await fetch('/api/knowledge').then(r => r.json());
+    renderKnowledgeBase();
+  } catch {}
+}
+
+function renderKnowledgeBase() {
+  const tabsEl = document.getElementById('kb-tabs');
+  const listEl = document.getElementById('kb-list');
+  const countEl = document.getElementById('kb-count');
+
+  // Count total
+  let total = 0;
+  for (const items of Object.values(_kbData)) total += items.length;
+  countEl.textContent = total;
+
+  if (total === 0) {
+    tabsEl.innerHTML = '';
+    listEl.innerHTML = '<p class="empty">No knowledge entries yet. Notes are classified here after consolidation.</p>';
+    return;
+  }
+
+  // Render tabs
+  let tabsHtml = '<button class="kb-tab ' + (_kbActiveTab === 'all' ? 'active' : '') + '" onclick="kbSetTab(\'all\')">All <span class="badge">' + total + '</span></button>';
+  for (const [cat, items] of Object.entries(_kbData)) {
+    if (items.length === 0) continue;
+    const label = KB_CAT_LABELS[cat] || cat;
+    tabsHtml += '<button class="kb-tab ' + (_kbActiveTab === cat ? 'active' : '') + '" onclick="kbSetTab(\'' + cat + '\')">' + label + ' <span class="badge">' + items.length + '</span></button>';
+  }
+  tabsEl.innerHTML = tabsHtml;
+
+  // Collect items for active tab
+  let items = [];
+  if (_kbActiveTab === 'all') {
+    for (const [cat, catItems] of Object.entries(_kbData)) {
+      for (const item of catItems) items.push({ ...item, category: cat });
+    }
+    items.sort((a, b) => b.date.localeCompare(a.date));
+  } else {
+    items = (_kbData[_kbActiveTab] || []).map(i => ({ ...i, category: _kbActiveTab }));
+  }
+
+  if (items.length === 0) {
+    listEl.innerHTML = '<p class="empty">No entries in this category.</p>';
+    return;
+  }
+
+  listEl.innerHTML = items.slice(0, 50).map(item => {
+    const icon = KB_CAT_ICONS[item.category] || '\u{1F4C4}';
+    const label = KB_CAT_LABELS[item.category] || item.category;
+    return '<div class="kb-item" onclick="kbOpenItem(\'' + escHtml(item.category) + '\', \'' + escHtml(item.file) + '\')">' +
+      '<div class="kb-item-body">' +
+        '<div class="kb-item-title">' + icon + ' ' + escHtml(item.title) + '</div>' +
+        '<div class="kb-item-meta">' +
+          '<span>' + label + '</span>' +
+          (item.agent ? '<span>' + item.agent + '</span>' : '') +
+          '<span>' + (item.date || '') + '</span>' +
+          '<span>' + Math.round(item.size / 1024) + 'KB</span>' +
+        '</div>' +
+        (item.preview ? '<div class="kb-item-preview">' + escHtml(item.preview) + '</div>' : '') +
+      '</div>' +
+    '</div>';
+  }).join('');
+}
+
+function kbSetTab(tab) {
+  _kbActiveTab = tab;
+  renderKnowledgeBase();
+}
+
+async function kbOpenItem(category, file) {
+  try {
+    const content = await fetch('/api/knowledge/' + category + '/' + encodeURIComponent(file)).then(r => r.text());
+    // Strip frontmatter for display
+    const display = content.replace(/^---[\s\S]*?---\n*/m, '');
+    document.getElementById('modal-title').textContent = file;
+    document.getElementById('modal-body').textContent = display;
+    document.getElementById('modal').classList.add('open');
+  } catch (e) {
+    console.error('Failed to load KB item:', e);
+  }
+}
+
 // ─── Command History ──────────────────────────────────────────────────────────
 const CMD_HISTORY_KEY = 'squad-cmd-history';
 const CMD_HISTORY_MAX = 50;

package/dashboard.js

@@ -811,6 +811,53 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  // GET /api/knowledge — list all knowledge base entries grouped by category
+  if (req.method === 'GET' && req.url === '/api/knowledge') {
+    const kbDir = path.join(SQUAD_DIR, 'knowledge');
+    const categories = ['architecture', 'conventions', 'project-notes', 'build-reports', 'reviews'];
+    const result = {};
+    for (const cat of categories) {
+      const catDir = path.join(kbDir, cat);
+      const files = safeReadDir(catDir).filter(f => f.endsWith('.md')).sort().reverse();
+      result[cat] = files.map(f => {
+        const content = safeRead(path.join(catDir, f)) || '';
+        // Extract title from first heading
+        const titleMatch = content.match(/^#\s+(.+)/m);
+        const title = titleMatch ? titleMatch[1] : f.replace(/\.md$/, '');
+        // Extract agent and date from frontmatter
+        const agentMatch = content.match(/^agent:\s*(.+)/m);
+        const dateMatch = content.match(/^date:\s*(.+)/m);
+        return {
+          file: f,
+          category: cat,
+          title,
+          agent: agentMatch ? agentMatch[1].trim() : '',
+          date: dateMatch ? dateMatch[1].trim() : '',
+          size: content.length,
+          preview: content.replace(/^---[\s\S]*?---\n*/m, '').split('\n').filter(l => l.trim() && !l.startsWith('#')).slice(0, 3).join(' ').slice(0, 200),
+        };
+      });
+    }
+    return jsonReply(res, 200, result);
+  }
+
+  // GET /api/knowledge/:category/:file — read a specific knowledge base entry
+  const kbMatch = req.url.match(/^\/api\/knowledge\/([^/]+)\/([^?]+)/);
+  if (kbMatch && req.method === 'GET') {
+    const cat = kbMatch[1];
+    const file = decodeURIComponent(kbMatch[2]);
+    // Prevent path traversal
+    if (file.includes('..') || file.includes('/') || file.includes('\\')) {
+      return jsonReply(res, 400, { error: 'invalid file name' });
+    }
+    const content = safeRead(path.join(SQUAD_DIR, 'knowledge', cat, file));
+    if (content === null) return jsonReply(res, 404, { error: 'not found' });
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.end(content);
+    return;
+  }
+
   // POST /api/inbox/persist — promote an inbox item to team notes
   if (req.method === 'POST' && req.url === '/api/inbox/persist') {
     try {

package/engine.js

@@ -38,6 +38,7 @@ const CONTROL_PATH = path.join(ENGINE_DIR, 'control.json');
 const DISPATCH_PATH = path.join(ENGINE_DIR, 'dispatch.json');
 const LOG_PATH = path.join(ENGINE_DIR, 'log.json');
 const INBOX_DIR = path.join(SQUAD_DIR, 'notes', 'inbox');
+const KNOWLEDGE_DIR = path.join(SQUAD_DIR, 'knowledge');
 const ARCHIVE_DIR = path.join(SQUAD_DIR, 'notes', 'archive');
 const PLANS_DIR = path.join(SQUAD_DIR, 'plans');
 const IDENTITY_DIR = path.join(SQUAD_DIR, 'identity');
@@ -738,8 +739,9 @@ function spawnAgent(dispatchItem, config) {
     safeWrite(archivePath, outputContent);
     safeWrite(latestPath, outputContent); // overwrite latest for dashboard compat
 
-    // Extract agent's final result text from stream-json output
+    // Extract agent's final result text + token usage from stream-json output
     let resultSummary = '';
+    let taskUsage = null;
     try {
       const lines = stdout.split('\n');
       for (let i = lines.length - 1; i >= 0; i--) {
@@ -747,8 +749,19 @@ function spawnAgent(dispatchItem, config) {
         if (!line || !line.startsWith('{')) continue;
         try {
           const obj = JSON.parse(line);
-          if (obj.type === 'result' && obj.result) {
-            resultSummary = obj.result.slice(0, 500);
+          if (obj.type === 'result') {
+            if (obj.result) resultSummary = obj.result.slice(0, 500);
+            if (obj.total_cost_usd || obj.usage) {
+              taskUsage = {
+                costUsd: obj.total_cost_usd || 0,
+                inputTokens: obj.usage?.input_tokens || 0,
+                outputTokens: obj.usage?.output_tokens || 0,
+                cacheRead: obj.usage?.cache_read_input_tokens || obj.usage?.cacheReadInputTokens || 0,
+                cacheCreation: obj.usage?.cache_creation_input_tokens || obj.usage?.cacheCreationInputTokens || 0,
+                durationMs: obj.duration_ms || 0,
+                numTurns: obj.num_turns || 0,
+              };
+            }
             break;
           }
         } catch {}
@@ -807,7 +820,7 @@ function spawnAgent(dispatchItem, config) {
     updateAgentHistory(agentId, dispatchItem, code === 0 ? 'success' : 'error');
 
     // Update quality metrics
-    updateMetrics(agentId, dispatchItem, code === 0 ? 'success' : 'error');
+    updateMetrics(agentId, dispatchItem, code === 0 ? 'success' : 'error', taskUsage);
 
     // Cleanup temp files
     try { fs.unlinkSync(sysPromptPath); } catch {}
@@ -1992,7 +2005,7 @@ function createReviewFeedbackForAuthor(reviewerAgentId, pr, config) {
   log('info', `Created review feedback for ${authorAgentId} from ${reviewerAgentId} on ${pr.id}`);
 }
 
-function updateMetrics(agentId, dispatchItem, result) {
+function updateMetrics(agentId, dispatchItem, result, taskUsage) {
   const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
   const metrics = safeJson(metricsPath) || {};
 
@@ -2005,7 +2018,11 @@ function updateMetrics(agentId, dispatchItem, result) {
       prsRejected: 0,
       reviewsDone: 0,
       lastTask: null,
-      lastCompleted: null
+      lastCompleted: null,
+      totalCostUsd: 0,
+      totalInputTokens: 0,
+      totalOutputTokens: 0,
+      totalCacheRead: 0,
     };
   }
 
@@ -2021,6 +2038,35 @@ function updateMetrics(agentId, dispatchItem, result) {
     m.tasksErrored++;
   }
 
+  // Track token usage per agent
+  if (taskUsage) {
+    m.totalCostUsd = (m.totalCostUsd || 0) + (taskUsage.costUsd || 0);
+    m.totalInputTokens = (m.totalInputTokens || 0) + (taskUsage.inputTokens || 0);
+    m.totalOutputTokens = (m.totalOutputTokens || 0) + (taskUsage.outputTokens || 0);
+    m.totalCacheRead = (m.totalCacheRead || 0) + (taskUsage.cacheRead || 0);
+  }
+
+  // Track daily usage (all agents combined)
+  const today = dateStamp();
+  if (!metrics._daily) metrics._daily = {};
+  if (!metrics._daily[today]) metrics._daily[today] = { costUsd: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0, tasks: 0 };
+  const daily = metrics._daily[today];
+  daily.tasks++;
+  if (taskUsage) {
+    daily.costUsd += taskUsage.costUsd || 0;
+    daily.inputTokens += taskUsage.inputTokens || 0;
+    daily.outputTokens += taskUsage.outputTokens || 0;
+    daily.cacheRead += taskUsage.cacheRead || 0;
+  }
+
+  // Prune daily entries older than 30 days
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - 30);
+  const cutoffStr = cutoff.toISOString().slice(0, 10);
+  for (const day of Object.keys(metrics._daily)) {
+    if (day < cutoffStr) delete metrics._daily[day];
+  }
+
   safeWrite(metricsPath, metrics);
 }
 
@@ -2053,6 +2099,25 @@ function consolidateInbox(config) {
 function consolidateWithLLM(items, existingNotes, files, config) {
   _consolidationInFlight = true;
 
+  // Pre-classify items to generate KB paths for Haiku to reference
+  const kbPaths = items.map(item => {
+    const content = item.content || '';
+    const name = (item.name || '').toLowerCase();
+    const contentLower = content.toLowerCase();
+    let cat = 'project-notes';
+    if (name.includes('review') || name.includes('pr-') || name.includes('pr4') || name.includes('feedback')) cat = 'reviews';
+    else if (name.includes('build') || name.includes('bt-') || contentLower.includes('build pass') || contentLower.includes('build fail') || contentLower.includes('lint')) cat = 'build-reports';
+    else if (contentLower.includes('architecture') || contentLower.includes('design doc') || contentLower.includes('system design')) cat = 'architecture';
+    else if (contentLower.includes('convention') || contentLower.includes('pattern') || contentLower.includes('always use') || contentLower.includes('best practice')) cat = 'conventions';
+    const agentMatch = item.name.match(/^(\w+)-/);
+    const agent = agentMatch ? agentMatch[1] : 'unknown';
+    const titleMatch = content.match(/^#\s+(.+)/m);
+    const titleSlug = titleMatch ? titleMatch[1].toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50) : item.name.replace(/\.md$/, '');
+    return { file: item.name, category: cat, kbPath: `knowledge/${cat}/${dateStamp()}-${agent}-${titleSlug}.md` };
+  });
+
+  const kbRefBlock = kbPaths.map(p => `- \`${p.file}\` → \`${p.kbPath}\``).join('\n');
+
   // Build the prompt with all inbox notes
   const notesBlock = items.map(item =>
     `<note file="${item.name}">\n${(item.content || '').slice(0, 8000)}\n</note>`
@@ -2097,6 +2162,10 @@ Read every inbox note carefully. Produce a consolidated digest following these r
 
 6. **Write a descriptive title**: First line must be a single-line title summarizing what was learned. Do NOT use generic text like "Consolidated from N items".
 
+7. **Reference the knowledge base**: Each note is being filed into the knowledge base at these paths. After each insight bullet, add a reference link so readers know where to find the full detail:
+${kbRefBlock}
+   Format: \`→ see knowledge/category/filename.md\` on a new line after the insight, indented.
+
 ## Output Format
 
 Respond with ONLY the markdown below — no preamble, no explanation, no code fences:
@@ -2106,6 +2175,7 @@ Respond with ONLY the markdown below — no preamble, no explanation, no code fe
 
 #### Category Name
 - **Bold key**: insight text _(agent)_
+  → see \`knowledge/category/filename.md\`
 
 _Processed N notes, M insights extracted, K duplicates removed._
 
@@ -2194,6 +2264,7 @@ Use today's date: ${dateStamp()}`;
       }
 
       safeWrite(NOTES_PATH, newContent);
+      classifyToKnowledgeBase(items);
       archiveInboxFiles(files);
       log('info', `LLM consolidation complete: ${files.length} notes processed by Haiku`);
     } else {
@@ -2313,10 +2384,78 @@ function consolidateWithRegex(items, files) {
     if (sections.length > 10) { newContent = sections[0] + '\n---\n\n### ' + sections.slice(-8).join('\n---\n\n### '); }
   }
   safeWrite(NOTES_PATH, newContent);
+  classifyToKnowledgeBase(items);
   archiveInboxFiles(files);
   log('info', `Regex fallback: consolidated ${files.length} notes → ${deduped.length} insights into notes.md`);
 }
 
+// ─── Knowledge Base Classification ───────────────────────────────────────────
+// Classifies each inbox note into a knowledge/ subdirectory based on content.
+// Full original content is preserved (not summarized) for deep reference.
+function classifyToKnowledgeBase(items) {
+  if (!fs.existsSync(KNOWLEDGE_DIR)) fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
+
+  const categoryDirs = {
+    architecture: path.join(KNOWLEDGE_DIR, 'architecture'),
+    conventions: path.join(KNOWLEDGE_DIR, 'conventions'),
+    'project-notes': path.join(KNOWLEDGE_DIR, 'project-notes'),
+    'build-reports': path.join(KNOWLEDGE_DIR, 'build-reports'),
+    reviews: path.join(KNOWLEDGE_DIR, 'reviews'),
+  };
+  for (const dir of Object.values(categoryDirs)) {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+
+  let classified = 0;
+  for (const item of items) {
+    const content = item.content || '';
+    const name = (item.name || '').toLowerCase();
+    const contentLower = content.toLowerCase();
+
+    // Classify by filename patterns + content keywords
+    let category = 'project-notes'; // default
+    if (name.includes('review') || name.includes('pr-') || name.includes('pr4') || name.includes('feedback')) {
+      category = 'reviews';
+    } else if (name.includes('build') || name.includes('bt-') || contentLower.includes('build pass') || contentLower.includes('build fail') || contentLower.includes('lint')) {
+      category = 'build-reports';
+    } else if (contentLower.includes('architecture') || contentLower.includes('design doc') || contentLower.includes('system design') || contentLower.includes('data flow') || contentLower.includes('how it works')) {
+      category = 'architecture';
+    } else if (contentLower.includes('convention') || contentLower.includes('pattern') || contentLower.includes('always use') || contentLower.includes('never use') || contentLower.includes('rule:') || contentLower.includes('best practice')) {
+      category = 'conventions';
+    }
+
+    // Write to knowledge base with clean filename
+    const agentMatch = item.name.match(/^(\w+)-/);
+    const agent = agentMatch ? agentMatch[1] : 'unknown';
+    const titleMatch = content.match(/^#\s+(.+)/m);
+    const titleSlug = titleMatch
+      ? titleMatch[1].toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50)
+      : item.name.replace(/\.md$/, '');
+    const kbFilename = `${dateStamp()}-${agent}-${titleSlug}.md`;
+    const kbPath = path.join(categoryDirs[category], kbFilename);
+
+    // Add frontmatter with metadata
+    const frontmatter = `---
+source: ${item.name}
+agent: ${agent}
+category: ${category}
+date: ${dateStamp()}
+---
+
+`;
+    try {
+      safeWrite(kbPath, frontmatter + content);
+      classified++;
+    } catch (e) {
+      log('warn', `Failed to classify ${item.name} to knowledge base: ${e.message}`);
+    }
+  }
+
+  if (classified > 0) {
+    log('info', `Knowledge base: classified ${classified} note(s) into knowledge/`);
+  }
+}
+
 function archiveInboxFiles(files) {
   if (!fs.existsSync(ARCHIVE_DIR)) fs.mkdirSync(ARCHIVE_DIR, { recursive: true });
   for (const f of files) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/squad",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Multi-agent AI dev team that runs from ~/.squad/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "squad": "bin/squad.js"