llm-kb 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-kb",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "LLM-powered knowledge base. Drop documents, build a wiki, ask questions. Inspired by Karpathy.",
   "bin": {
     "llm-kb": "./bin/cli.js"
@@ -8,7 +8,9 @@
   "type": "module",
   "scripts": {
     "build": "tsup src/cli.ts --format esm --out-dir bin --clean",
-    "dev": "tsup src/cli.ts --format esm --out-dir bin --watch"
+    "dev": "tsup src/cli.ts --format esm --out-dir bin --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "llm",
@@ -28,16 +30,19 @@
   "dependencies": {
     "@llamaindex/liteparse": "^1.4.4",
     "@mariozechner/pi-coding-agent": "^0.65.0",
+    "adm-zip": "^0.5.17",
     "chalk": "^5.6.2",
     "chokidar": "^5.0.0",
     "commander": "^13.1.0",
     "exceljs": "^4.4.0",
-    "mammoth": "^1.12.0",
-    "officeparser": "^6.0.7",
-    "ora": "^9.3.0"
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "officeparser": "^6.0.7"
   },
   "devDependencies": {
+    "@types/marked-terminal": "^6.1.1",
     "tsup": "^8.4.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.2"
   }
 }

package/plan.md

@@ -50,6 +50,251 @@ Config file has no readers yet. Deferred to Phase 2/3. README updated instead.
 - `--save` flag — research mode, saves to `outputs/`, re-indexes
 - Query mode is read-only (read tool only). Research mode adds bash + write.
 
-**Deferred to Phase 4:**
-- Trace logging (JSON per query: question, filesRead, citations, tokens, duration)
-- Needed for eval, but no eval system yet to consume traces
+---
+
+## Phase 3: Auth Fix + Eval Loop + LLM Config
+
+> Full spec: `PHASE3_SPEC.md`
+> **Trigger:** 182 LinkedIn saves — people coming back to try `npx llm-kb run` this week.
+
+### Why now
+- **Auth fix is urgent.** Users hit a wall if Pi SDK isn't installed. `ANTHROPIC_API_KEY` must work as fallback.
+- **Eval loop is the differentiator.** Nobody else building llm-wiki scripts has traces + citation checking.
+- **Model config cuts cost.** Haiku for indexing (10x cheaper than Sonnet). Users shouldn't pay Sonnet prices for one-line summaries.
+
+### Build order
+
+## Slice 1: Auth fix 🔴 DO FIRST
+
+Check auth before creating any session. Support two paths:
+
+```
+npx llm-kb run ./docs
+  ├─ ~/.pi/agent/auth.json exists? → Pi SDK auth. Done.
+  ├─ ANTHROPIC_API_KEY set? → Configure Pi SDK programmatically. Done.
+  └─ Neither? → Clear error:
+       No LLM authentication found.
+       Option 1: npm install -g @mariozechner/pi-coding-agent && pi
+       Option 2: export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Definition of done:
+- [ ] `ANTHROPIC_API_KEY=sk-... npx llm-kb run ./docs` works without Pi installed
+- [ ] Pi SDK auth works as before (no regression)
+- [ ] Clear error when neither is available
+- [ ] README updated with both auth options
+
+## Slice 2: LLM config
+
+Auto-generate `.llm-kb/config.json` on first run:
+
+```json
+{
+  "indexModel": "claude-haiku-3-5",
+  "queryModel": "claude-sonnet-4-20250514",
+  "provider": "anthropic"
+}
+```
+
+Env var overrides: `LLM_KB_INDEX_MODEL`, `LLM_KB_QUERY_MODEL`
+Priority: env var → config file → defaults
+
+Definition of done:
+- [ ] Config auto-generated on first run
+- [ ] Haiku for indexing, Sonnet for query by default
+- [ ] Env vars override config
+- [ ] `llm-kb status` shows current model config
+
+## Slice 3: Trace logging
+
+Every query logs JSON to `.llm-kb/traces/`:
+
+```json
+{
+  "id": "2026-04-06T14-30-00-query",
+  "timestamp": "2026-04-06T14:30:00Z",
+  "question": "what are the reserve requirements?",
+  "mode": "query",
+  "filesRead": ["index.md", "reserve-policy.md"],
+  "filesSkipped": ["board-deck.md", "pipeline.md"],
+  "answer": "Reserve requirements are defined in...",
+  "citations": [
+    { "file": "reserve-policy.md", "location": "p.3", "claim": "Minimum reserve ratio of 12%" }
+  ],
+  "durationMs": 4200
+}
+```
+
+Capture via `session.subscribe()` — intercept tool calls to track `filesRead`.
+
+Definition of done:
+- [ ] Every query writes a trace JSON to `.llm-kb/traces/`
+- [ ] Trace includes: question, mode, filesRead, filesSkipped, answer, citations, durationMs
+
+## Slice 4: `llm-kb status`
+
+```
+Knowledge Base: ./research/.llm-kb/
+  Sources: 12 files (8 PDF, 2 XLSX, 1 DOCX, 1 TXT)
+  Index: 12 entries, last updated 2 min ago
+  Outputs: 3 saved research answers
+  Traces: 47 queries logged
+  Model: claude-sonnet-4 (query), claude-haiku-3-5 (index)
+  Auth: Pi SDK
+```
+
+Definition of done:
+- [ ] `llm-kb status` prints KB stats, auth method, model config, trace count
+
+## Slice 5: `llm-kb eval`
+
+Pi SDK session (read-only) that:
+1. Reads trace files from `.llm-kb/traces/`
+2. For each trace checks: citation validity, missing sources, answer consistency
+3. Writes report to `.llm-kb/wiki/outputs/eval-report.md`
+4. Watcher detects report, re-indexes
+
+```bash
+llm-kb eval --folder ./research
+llm-kb eval --folder ./research --last 20
+```
+
+Definition of done:
+- [ ] `llm-kb eval` reads traces and writes eval-report.md
+- [ ] Flags: invalid citations, skipped-but-relevant files, answer contradictions
+- [ ] Report gets re-indexed by watcher
+
+## Slice 6: Blog Part 4
+
+- Write AFTER `llm-kb eval` runs on real data
+- Show actual eval-report.md output
+- Title: "How llm-kb Knows When It Got It Wrong"
+
+---
+
+## Phase 3 Definition of Done
+
+- [ ] `ANTHROPIC_API_KEY` works without Pi SDK installed
+- [ ] Clear error when no auth found
+- [ ] Config file with model selection (index vs query model)
+- [ ] Every query logs a trace JSON to `.llm-kb/traces/`
+- [ ] `llm-kb eval` checks citations and writes report
+- [ ] `llm-kb status` shows KB stats + config + auth
+- [ ] README updated with auth options + eval command
+- [ ] Blog Part 4 written with real eval output
+
+---
+
+## Phase 4: Wiki Compilation (The Farzapedia Pattern)
+
+> **Insight:** Farza's implementation is what Karpathy called the best version. The key isn't just indexing sources — it's compiling them into a **concept-organized wiki** with backlinked articles. The agent navigates concepts, not raw files.
+>
+> Current llm-kb: agent reads source summaries → picks source files → answers from raw docs.
+> Wiki pattern: agent reads concept articles → drills into specific articles → answers from synthesized knowledge.
+
+### The Structural Shift
+
+**Current (source-organized):**
+```
+sources/lease-castlelake.md    ─┐
+sources/lease-genesis.md       ─┤→ index.md (flat table, one row per source)
+sources/maintenance-manual.md  ─┘
+```
+
+**Wiki (concept-organized):**
+```
+sources/lease-castlelake.md    ─┐
+sources/lease-genesis.md       ─┤→ articles/reserve-requirements.md
+sources/maintenance-manual.md  ─┘   articles/key-parties.md
+                                      articles/engine-types.md
+                                      articles/maintenance-obligations.md
+                                      index.md (catalog of ARTICLES with backlinks)
+```
+
+Farza's quote: *"The structure of the wiki files and how it's all backlinked is very easily crawlable by any agent. Starting at index.md, the agent does a really good job at drilling into the specific pages it needs."*
+
+Karpathy's quote: *"I thought I had to reach for fancy RAG, but the LLM has been pretty good about auto-maintaining index files and brief summaries of all the documents and it reads all the important related data fairly easily at this ~small scale."*
+
+### New Command
+
+```bash
+llm-kb compile ./folder
+```
+
+Or auto-triggered after indexing when `--wiki` flag is passed:
+
+```bash
+llm-kb run ./folder --wiki   # parse + index + compile wiki
+```
+
+### Wiki Directory Structure
+
+```
+.llm-kb/
+  wiki/
+    sources/          # raw parsed files (unchanged)
+    articles/         # NEW: concept-organized articles
+      concepts/       # thematic articles (reserve-requirements.md, etc)
+      entities/       # people, companies, assets
+      timeline.md     # chronological view of events
+    index.md          # NOW points to articles, not sources
+    source-index.md   # OLD flat source table (kept for reference)
+```
+
+### How Compile Works
+
+1. LLM reads ALL source files (via existing sources/ dir)
+2. LLM identifies key concepts, entities, and themes
+3. LLM writes one markdown article per concept — like a Wikipedia entry
+4. Each article has:
+   - Description (synthesized from multiple sources)
+   - Backlinks to related articles: `[[reserve-requirements]]`, `[[key-parties]]`
+   - Source citations: `(Source: lease-castlelake.md, p.3)`
+5. Writes `articles/index.md` — catalog of all articles with one-line descriptions
+
+### Incremental Updates (The Compounding Part)
+
+When a new source is added (watcher detects it):
+1. Parse it → sources/
+2. LLM reads new source + `articles/index.md`
+3. LLM updates 2-3 most relevant existing articles where new content fits
+4. OR creates a new article if the topic is genuinely new
+5. Updates `articles/index.md` catalog
+
+Farza: *"The most magical thing now is as I add new things, the system updates 2-3 different articles where it feels the context belongs, or just creates a new article. Like a super genius librarian."*
+
+### Query Change
+
+With wiki mode active, query agent reads `articles/index.md` (concept catalog) instead of `source-index.md` (source table). Agent drills into concept articles, gets synthesized cross-referenced answers.
+
+Fallback: if no articles compiled yet, falls back to source-index behavior.
+
+### Blog Post
+
+Part 5 or 6: *"Why Your Knowledge Base Needs a Librarian, Not a Search Engine"*
+- Show the before/after: flat source index vs concept wiki
+- Show Farza's insight: built for agents, not humans
+- Show the compounding: add one doc, 3 articles updated automatically
+- Live demo: `llm-kb compile` on a real document set
+
+### Why This Matters for llm-kb
+
+- Karpathy publicly called this the best implementation of his pattern
+- Farza has **no public code** — llm-kb ships it as `npx llm-kb compile`
+- Farzapedia got **920K views** on Farza's tweet, **Karpathy quote-tweeted** it at **920K views**
+- First open-source implementation of the exact pattern Karpathy validated
+- Blog post can reference both tweets legitimately ("inspired by Farza's Farzapedia")
+
+### Definition of Done (Phase 4)
+
+- [ ] `llm-kb compile ./folder` reads sources and writes articles/ directory
+- [ ] Each article is a proper markdown file with backlinks and source citations
+- [ ] `articles/index.md` is a concept catalog (not a source table)
+- [ ] Watcher triggers incremental article updates when new source added
+- [ ] Query uses article index when available, falls back to source index
+- [ ] `llm-kb status` shows: X sources, Y articles, last compiled
+- [ ] Blog Part 5 written: concept wiki vs flat index, Farzapedia reference
+
+---
+
+*Phase 4 added April 6, 2026 — inspired by Farzapedia (@FarzaTV), highlighted by Karpathy as best implementation of the LLM wiki pattern. 920K views on Farza's tweet, Karpathy quote-tweet at 920K views.*

package/src/auth.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { AuthStorage } from "@mariozechner/pi-coding-agent";
+import chalk from "chalk";
+
+export type AuthMethod = "pi-sdk" | "api-key" | "none";
+
+export interface AuthResult {
+  ok: true;
+  method: AuthMethod;
+  authStorage?: AuthStorage; // undefined = use Pi SDK default (file-based)
+}
+
+export interface AuthFailure {
+  ok: false;
+}
+
+/**
+ * Detect available auth and return an AuthStorage if needed.
+ *
+ * Priority:
+ * 1. Pi SDK auth.json  → use default file-based storage (no override needed)
+ * 2. ANTHROPIC_API_KEY → create in-memory storage with the key
+ * 3. Neither           → return failure
+ */
+export function checkAuth(): AuthResult | AuthFailure {
+  const piAuthPath = join(homedir(), ".pi", "agent", "auth.json");
+
+  if (existsSync(piAuthPath)) {
+    return { ok: true, method: "pi-sdk" };
+  }
+
+  if (process.env.ANTHROPIC_API_KEY) {
+    const authStorage = AuthStorage.inMemory({
+      anthropic: { type: "api_key", key: process.env.ANTHROPIC_API_KEY },
+    });
+    return { ok: true, method: "api-key", authStorage };
+  }
+
+  return { ok: false };
+}
+
+/**
+ * Print a friendly error when no auth is configured and exit.
+ */
+export function exitWithAuthError(): never {
+  console.error(chalk.red("\n  No LLM authentication found.\n"));
+  console.error(`  ${chalk.bold("Option 1:")} Install Pi SDK ${chalk.dim("(recommended)")}`);
+  console.error(chalk.dim("    npm install -g @mariozechner/pi-coding-agent"));
+  console.error(chalk.dim("    pi\n"));
+  console.error(`  ${chalk.bold("Option 2:")} Set your Anthropic API key`);
+  console.error(chalk.dim("    export ANTHROPIC_API_KEY=sk-ant-...\n"));
+  process.exit(1);
+}

package/src/cli.ts

@@ -5,10 +5,15 @@ import { scan, summarize } from "./scan.js";
 import { parsePDF } from "./pdf.js";
 import { buildIndex } from "./indexer.js";
 import { startWatcher } from "./watcher.js";
-import { query } from "./query.js";
+import { startSessionWatcher } from "./session-watcher.js";
+import { query, createChat } from "./query.js";
+import { runEval } from "./eval.js";
+import { ChatDisplay } from "./tui-display.js";
 import { resolveKnowledgeBase } from "./resolve-kb.js";
+import { checkAuth, exitWithAuthError } from "./auth.js";
+import { ensureConfig, loadConfig } from "./config.js";
 import { existsSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
+import { mkdir, readdir, stat } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import chalk from "chalk";
 
@@ -17,20 +22,26 @@ const program = new Command();
 program
   .name("llm-kb")
   .description("Drop files into a folder. Get a knowledge base you can query.")
-  .version("0.2.0");
+  .version("0.4.0");
 
 program
   .command("run")
   .description("Scan, parse, index, and watch a folder")
   .argument("<folder>", "Path to your documents folder")
   .action(async (folder: string) => {
-    console.log(`\n${chalk.bold("llm-kb")} v0.2.0\n`);
+    console.log(`\n${chalk.bold("llm-kb")} v0.4.0\n`);
+
+    const auth = checkAuth();
+    if (!auth.ok) exitWithAuthError();
 
     if (!existsSync(folder)) {
       console.error(chalk.red(`Error: Folder not found: ${folder}`));
       process.exit(1);
     }
 
+    const root = resolve(folder);
+    const config = await ensureConfig(root);
+
     console.log(`Scanning ${folder}...`);
 
     const files = await scan(folder);
@@ -44,12 +55,10 @@ program
     console.log(`  Found ${chalk.bold(files.length.toString())} files (${summarize(files)})`);
     if (pdfs.length === 0) return;
 
-    // Set up .llm-kb folder structure
-    const root = resolve(folder);
     const sourcesDir = join(root, ".llm-kb", "wiki", "sources");
     await mkdir(sourcesDir, { recursive: true });
 
-    // Parse PDFs with inline progress
+    // Parse PDFs
     let parsed = 0;
     let skipped = 0;
     let failed = 0;
@@ -57,76 +66,192 @@ program
 
     for (let i = 0; i < pdfs.length; i++) {
       const pdf = pdfs[i];
-      const fullPath = join(root, pdf.path);
-
-      // Inline progress — overwrite same line
-      const progress = `  Parsing... ${i + 1}/${pdfs.length} — ${pdf.name}`;
-      process.stdout.write(`\r${progress.padEnd(80)}`);
-
+      const progress = `  Parsing... ${i + 1}/${pdfs.length} \u2014 ${pdf.name}`;
+      process.stdout.write(`\r${progress.padEnd(process.stdout.columns || 80)}`);
       try {
-        const result = await parsePDF(fullPath, sourcesDir);
-        if (result.skipped) {
-          skipped++;
-        } else {
-          parsed++;
-        }
+        const result = await parsePDF(join(root, pdf.path), sourcesDir);
+        if (result.skipped) skipped++; else parsed++;
       } catch (err: any) {
         failed++;
         errors.push({ name: pdf.name, message: err.message });
       }
     }
 
-    // Clear progress line
-    process.stdout.write(`\r${"".padEnd(80)}\r`);
+    process.stdout.write(`\r${"".padEnd(process.stdout.columns || 80)}\r`);
 
-    // Summary
     const parts: string[] = [];
     if (parsed > 0) parts.push(chalk.green(`${parsed} parsed`));
     if (skipped > 0) parts.push(chalk.dim(`${skipped} skipped (up to date)`));
     if (failed > 0) parts.push(chalk.red(`${failed} failed`));
     console.log(`  ${parts.join(", ")}`);
+    for (const err of errors) console.log(chalk.red(`    \u2717 ${err.name} \u2014 ${err.message}`));
 
-    // Show errors
-    for (const err of errors) {
-      console.log(chalk.red(`    ✗ ${err.name} — ${err.message}`));
+    // Build index — skip if up to date
+    const indexFile = join(root, ".llm-kb", "wiki", "index.md");
+    let indexUpToDate = false;
+    if (parsed === 0 && existsSync(indexFile)) {
+      try {
+        const indexMtime = (await stat(indexFile)).mtimeMs;
+        const sourceFiles = await readdir(sourcesDir);
+        const mtimes = await Promise.all(sourceFiles.map((f) => stat(join(sourcesDir, f)).then((s) => s.mtimeMs)));
+        indexUpToDate = mtimes.every((mt) => indexMtime >= mt);
+      } catch {}
     }
 
-    // Build index
-    console.log(`\n  Building index...`);
-    try {
-      await buildIndex(root, sourcesDir);
-      console.log(chalk.green(`  Index built: .llm-kb/wiki/index.md`));
-    } catch (err: any) {
-      console.error(chalk.red(`  Index failed: ${err.message}`));
+    if (indexUpToDate) {
+      console.log(chalk.dim(`\n  Index up to date.`));
+    } else {
+      console.log(`\n  Building index... ${chalk.dim(`(${config.indexModel})`)}`);
+      try {
+        await buildIndex(root, sourcesDir, undefined, auth.authStorage, config.indexModel);
+        console.log(chalk.green(`  Index built: .llm-kb/wiki/index.md`));
+      } catch (err: any) {
+        console.error(chalk.red(`  Index failed: ${err.message}`));
+      }
     }
 
     console.log(`\n  ${chalk.dim("Output:")} ${sourcesDir}`);
 
-    // Start watching for new files
-    console.log(chalk.dim(`\n  Watching for new files... (Ctrl+C to stop)`));
-    startWatcher({ folder: root, sourcesDir });
+    // Start watchers
+    startWatcher({ folder: root, sourcesDir, authStorage: auth.authStorage, indexModel: config.indexModel });
+    startSessionWatcher(root);
+
+    // TUI chat
+    const chatUI = new ChatDisplay();
+    const { session, display } = await createChat(root, {
+      authStorage: auth.authStorage,
+      modelId: config.queryModel,
+      tuiDisplay: chatUI,
+    });
+
+    chatUI.onSubmit = (text) => {
+      display.setQuestion(text);
+      // Fire-and-forget — don't await, TUI must stay responsive
+      session.prompt(text).catch(() => {});
+    };
+
+    chatUI.onExit = () => {
+      display.flush().then(() => {
+        session.dispose();
+        process.exit(0);
+      });
+    };
+
+    console.log(`\n${chalk.bold("Ready.")} Ask a question or drop files in to re-index.\n`);
+    chatUI.start();
   });
 
 program
   .command("query")
-  .description("Ask a question across your knowledge base")
+  .description("Ask a single question (non-interactive, stdout)")
   .argument("<question>", "Your question")
   .option("--folder <path>", "Path to document folder (auto-detects if omitted)")
   .option("--save", "Save the answer to wiki/outputs/ (research mode)")
   .action(async (question: string, options: { folder?: string; save?: boolean }) => {
-    const root = resolveKnowledgeBase(options.folder || process.cwd());
+    const auth = checkAuth();
+    if (!auth.ok) exitWithAuthError();
 
+    const root = resolveKnowledgeBase(options.folder || process.cwd());
     if (!root) {
       console.error(chalk.red("No knowledge base found. Run 'llm-kb run <folder>' first."));
       process.exit(1);
     }
 
+    const config = await loadConfig(root);
     try {
-      await query(root, question, { save: options.save });
+      await query(root, question, {
+        save: options.save,
+        authStorage: auth.authStorage,
+        modelId: config.queryModel,
+      });
     } catch (err: any) {
       console.error(chalk.red(err.message));
       process.exit(1);
     }
   });
 
+program
+  .command("eval")
+  .description("Analyze sessions for quality issues, wiki gaps, and performance")
+  .option("--folder <path>", "Path to document folder (auto-detects if omitted)")
+  .option("--last <n>", "Only check last N sessions", parseInt)
+  .action(async (options: { folder?: string; last?: number }) => {
+    const auth = checkAuth();
+    if (!auth.ok) exitWithAuthError();
+
+    const root = resolveKnowledgeBase(options.folder || process.cwd());
+    if (!root) {
+      console.error(chalk.red("No knowledge base found. Run 'llm-kb run <folder>' first."));
+      process.exit(1);
+    }
+
+    console.log(`\n${chalk.bold("llm-kb eval")}\n`);
+
+    const result = await runEval(root, {
+      authStorage: auth.authStorage,
+      last: options.last,
+      onProgress: (msg) => console.log(chalk.dim(`  ${msg}`)),
+    });
+
+    const { metrics, issues, wikiGaps } = result;
+    const errors = issues.filter((i) => i.severity === "error").length;
+    const warnings = issues.filter((i) => i.severity === "warning").length;
+
+    console.log();
+    console.log(`  ${chalk.bold("Results:")}`);
+    console.log(`  Queries analyzed:  ${metrics.totalQAs}`);
+    console.log(`  Wiki hit rate:     ${metrics.totalQAs > 0 ? Math.round(metrics.wikiHits / metrics.totalQAs * 100) : 0}%`);
+    console.log(`  Wasted reads:      ${metrics.wastedReads}`);
+    console.log(`  Issues:            ${errors > 0 ? chalk.red(`${errors} errors`) : chalk.green("0 errors")}  ${warnings > 0 ? chalk.yellow(`${warnings} warnings`) : chalk.dim("0 warnings")}`);
+    console.log(`  Wiki gaps:         ${wikiGaps.length > 0 ? chalk.yellow(String(wikiGaps.length)) : chalk.green("0")}`);
+    console.log();
+    console.log(chalk.green(`  Report: .llm-kb/wiki/outputs/eval-report.md`));
+    console.log();
+  });
+
+program
+  .command("status")
+  .description("Show knowledge base stats and current config")
+  .option("--folder <path>", "Path to document folder (auto-detects if omitted)")
+  .action(async (options: { folder?: string }) => {
+    const root = resolveKnowledgeBase(options.folder || process.cwd());
+    if (!root) {
+      console.error(chalk.red("No knowledge base found. Run 'llm-kb run <folder>' first."));
+      process.exit(1);
+    }
+
+    const auth = checkAuth();
+    const config = await loadConfig(root);
+
+    const sourcesDir  = join(root, ".llm-kb", "wiki", "sources");
+    const indexFile   = join(root, ".llm-kb", "wiki", "index.md");
+    const articlesDir = join(root, ".llm-kb", "wiki", "articles");
+    const outputsDir  = join(root, ".llm-kb", "wiki", "outputs");
+
+    let sourceCount = 0;
+    try { sourceCount = (await readdir(sourcesDir)).filter((f) => f.endsWith(".md")).length; } catch {}
+
+    let indexAge = "not built yet";
+    try {
+      const diffMin = Math.round((Date.now() - (await stat(indexFile)).mtimeMs) / 60000);
+      indexAge = diffMin < 1 ? "just now" : diffMin < 60 ? `${diffMin} min ago` : `${Math.round(diffMin / 60)} hr ago`;
+    } catch {}
+
+    let outputCount = 0;
+    try { outputCount = (await readdir(outputsDir)).filter((f) => f.endsWith(".md")).length; } catch {}
+
+    console.log(`\n${chalk.bold("Knowledge Base Status")}`);
+    console.log(`  ${chalk.dim("Folder:")}  ${root}`);
+    console.log(`  ${chalk.dim("Sources:")} ${sourceCount > 0 ? `${sourceCount} parsed source${sourceCount !== 1 ? "s" : ""}` : chalk.yellow("none yet")}`);
+    console.log(`  ${chalk.dim("Index:")}   ${indexAge}`);
+    let articleCount = 0;
+    try { articleCount = (await readdir(articlesDir)).filter((f) => f.endsWith(".md") && f !== "index.md").length; } catch {}
+
+    if (articleCount > 0) console.log(`  ${chalk.dim("Articles:")} ${articleCount} compiled`);
+    if (outputCount > 0) console.log(`  ${chalk.dim("Outputs:")} ${outputCount} saved answer${outputCount !== 1 ? "s" : ""}`);
+    console.log(`  ${chalk.dim("Models:")}  ${chalk.cyan(config.queryModel)} ${chalk.dim("(query)")}  ${chalk.cyan(config.indexModel)} ${chalk.dim("(index)")}`);
+    console.log(`  ${chalk.dim("Auth:")}    ${auth.ok ? (auth.method === "pi-sdk" ? "Pi SDK" : "ANTHROPIC_API_KEY") : chalk.red("not configured")}`);
+    console.log();
+  });
+
 program.parse();