llm-kb 0.1.0 → 0.2.0

package/PHASE2_SPEC.md

@@ -0,0 +1,274 @@
+# llm-kb — Phase 2: Query Engine
+
+> **Goal:** `llm-kb query "question" --folder ./research` works from the terminal.
+> **Depends on:** Phase 1 (ingest pipeline — complete)
+> **Blog:** Part 3 of the series
+
+---
+
+## What Success Looks Like
+
+```bash
+llm-kb query "what are the reserve requirements?" --folder ./research
+```
+
+```
+Reading index... 12 sources
+Selected: reserve-policy.md, q3-results.md, board-deck.md
+Reading 3 files...
+
+Reserve requirements are defined in two documents:
+
+1. **Reserve Policy** (reserve-policy.md, p.3): Minimum reserve
+   ratio of 12% of total assets, reviewed quarterly.
+
+2. **Q3 Results** (q3-results.md, p.8): Current reserve ratio
+   is 14.2%, above the 12% minimum. Management notes this
+   provides a 2.2% buffer against regulatory changes.
+
+Sources: reserve-policy.md (p.3), q3-results.md (p.8)
+```
+
+That's the shape: file selection visible, citations inline, synthesis across sources.
+
+---
+
+## Two Modes
+
+### Query (read-only)
+
+```bash
+llm-kb query "what changed in Q4 guidance?" --folder ./research
+```
+
+The agent reads `index.md`, picks files, reads them, answers. **Cannot modify anything.** Tools: `createReadTool` only.
+
+### Research (read + write)
+
+```bash
+llm-kb query "compare pipeline coverage to revenue target" --folder ./research --save
+```
+
+Same as query, but the answer is also saved to `.llm-kb/wiki/outputs/`. The watcher detects the new file and re-indexes. Next query can reference the analysis.
+
+Tools: `createReadTool` + `createWriteTool` + `createBashTool`.
+
+The `--save` flag switches from query mode to research mode.
+
+---
+
+## Architecture
+
+Same pattern as the indexer — a Pi SDK session with different tools:
+
+```typescript
+export async function query(
+  folder: string,
+  question: string,
+  options: { save?: boolean }
+) {
+  const sourcesDir = join(folder, ".llm-kb", "wiki", "sources");
+  const outputsDir = join(folder, ".llm-kb", "wiki", "outputs");
+
+  // Build AGENTS.md for query context
+  const agentsContent = buildQueryAgents(sourcesDir, options.save);
+
+  const loader = new DefaultResourceLoader({
+    cwd: folder,
+    agentsFilesOverride: (current) => ({
+      agentsFiles: [
+        ...current.agentsFiles,
+        { path: ".llm-kb/AGENTS.md", content: agentsContent },
+      ],
+    }),
+  });
+  await loader.reload();
+
+  const tools = [createReadTool(folder)];
+  if (options.save) {
+    tools.push(createWriteTool(folder), createBashTool(folder));
+  }
+
+  const { session } = await createAgentSession({
+    cwd: folder,
+    resourceLoader: loader,
+    tools,
+    sessionManager: SessionManager.inMemory(),
+    settingsManager: SettingsManager.inMemory({
+      compaction: { enabled: false },
+    }),
+  });
+
+  // Stream output to terminal
+  session.subscribe((event) => {
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "text_delta"
+    ) {
+      process.stdout.write(event.assistantMessageEvent.delta);
+    }
+  });
+
+  await session.prompt(question);
+  session.dispose();
+}
+```
+
+### The Query AGENTS.md
+
+The injected `AGENTS.md` for query mode tells the agent:
+
+```markdown
+# llm-kb Knowledge Base — Query Mode
+
+## How to answer questions
+
+1. FIRST read .llm-kb/wiki/index.md to see all available sources
+2. Based on the question, select the most relevant source files
+3. Read those files in full (not just the first 500 chars)
+4. Answer with inline citations: (filename, page/section)
+5. If the answer requires cross-referencing, read additional files
+6. Prefer primary sources over previous analyses in outputs/
+
+## Available sources
+(dynamically generated list of .md files in sources/)
+
+## Available libraries for non-PDF files
+- exceljs — for .xlsx/.xls
+- mammoth — for .docx
+- officeparser — for .pptx
+Write a quick Node.js script via bash to read these when needed.
+
+## Rules
+- Always cite sources with filename and page number
+- If you can't find the answer, say so — don't hallucinate
+- Read the FULL file, not just the beginning
+```
+
+For research mode, add:
+
+```markdown
+## Research Mode
+You can save your analysis to .llm-kb/wiki/outputs/.
+Use a descriptive filename (e.g., coverage-analysis.md).
+The file watcher will detect it and update the index.
+```
+
+---
+
+## CLI Integration
+
+Add `query` command to Commander:
+
+```typescript
+program
+  .command("query")
+  .description("Ask a question across your knowledge base")
+  .argument("<question>", "Your question")
+  .option("--folder <path>", "Path to document folder", ".")
+  .option("--save", "Save the answer to wiki/outputs/ (research mode)")
+  .action(async (question, options) => {
+    const folder = resolve(options.folder);
+
+    // Check if .llm-kb exists
+    if (!existsSync(join(folder, ".llm-kb"))) {
+      console.error(chalk.red("No knowledge base found. Run 'llm-kb run' first."));
+      process.exit(1);
+    }
+
+    await query(folder, question, { save: options.save });
+  });
+```
+
+---
+
+## Trace Logging (Prep for Eval — Phase 4)
+
+Every query gets logged to `.llm-kb/traces/`:
+
+```json
+{
+  "timestamp": "2026-04-05T14:30:00Z",
+  "question": "what are the reserve requirements?",
+  "mode": "query",
+  "filesRead": ["index.md", "reserve-policy.md", "q3-results.md"],
+  "filesAvailable": ["reserve-policy.md", "q3-results.md", "board-deck.md", "pipeline.md"],
+  "answer": "Reserve requirements are defined in two documents...",
+  "citations": [
+    { "file": "reserve-policy.md", "location": "p.3", "claim": "Minimum reserve ratio of 12%" },
+    { "file": "q3-results.md", "location": "p.8", "claim": "Current reserve ratio is 14.2%" }
+  ],
+  "tokensUsed": 3800,
+  "durationMs": 4200,
+  "model": "claude-sonnet-4"
+}
+```
+
+Implementation: wrap the session to intercept tool calls and capture which files were read. Save trace JSON after session completes.
+
+The eval agent (Phase 4) reads these traces to check citations against sources.
+
+---
+
+## Streaming Output
+
+Terminal query should stream — the user sees the answer appear word by word, not wait for the full response. The `session.subscribe()` handler writes deltas to stdout.
+
+For the `run` command (when we add query to the web UI in Phase 3), streaming goes through the Vercel AI SDK protocol.
+
+---
+
+## Constraints
+
+1. **Query must work without the web server running.** `llm-kb query` is standalone — it reads `.llm-kb/` directly. No dependency on `llm-kb run`.
+
+2. **Read-only by default.** Query mode cannot modify files. Only `--save` enables write.
+
+3. **Index must exist.** If `.llm-kb/wiki/index.md` doesn't exist, error out: "No knowledge base found. Run 'llm-kb run' first."
+
+4. **Graceful on empty results.** If the agent can't find relevant files, it should say "I couldn't find sources relevant to this question" — not hallucinate.
+
+5. **Token-conscious.** The agent reads index.md (~200 tokens for 50 sources) first, then only the files it selects (3-7 typically). Don't read all sources.
+
+---
+
+## Build Order (Slices)
+
+| Slice | What | Demoable? |
+|---|---|---|
+| 1 | `query` command + read-only session + streaming | ✅ Ask questions, get answers |
+| 2 | `--save` flag + research mode + write to outputs/ | ✅ Answers compound in wiki |
+| 3 | Trace logging (JSON per query) | Prep for eval |
+| 4 | `status` command (show KB stats) | ✅ Nice-to-have |
+
+---
+
+## Definition of Done
+
+- [ ] `llm-kb query "question" --folder ./research` returns a cited answer
+- [ ] Answer streams to terminal (word by word, not all at once)
+- [ ] Agent reads index.md first, then selects and reads relevant source files
+- [ ] `--save` flag saves the answer to `.llm-kb/wiki/outputs/`
+- [ ] Saved answers get detected by watcher and re-indexed
+- [ ] Query traces logged to `.llm-kb/traces/` as JSON
+- [ ] Error if no `.llm-kb/` exists ("run 'llm-kb run' first")
+- [ ] Non-PDF files (Excel, Word) readable by agent via bundled libraries
+- [ ] Blog Part 3 written with real terminal output
+
+---
+
+## What This Enables
+
+With query working, the demo becomes:
+
+```bash
+npx llm-kb run ./my-documents    # ingest
+llm-kb query "what changed?"     # ask
+llm-kb query "compare X vs Y" --save  # research (compounds)
+```
+
+Three commands. Ingest → Query → Research. That's a product, not a script.
+
+---
+
+*Phase 2 spec written April 4, 2026. DeltaXY.*

package/README.md

@@ -22,12 +22,14 @@ Pi handles the LLM auth — no separate API key configuration needed.
 
 ## What It Does
 
-```
+### Ingest
+
+```bash
 llm-kb run ./my-documents
 ```
 
 ```
-llm-kb v0.0.1
+llm-kb v0.2.0
 
 Scanning ./my-documents...
   Found 9 files (9 PDF)
@@ -46,6 +48,24 @@ Scanning ./my-documents...
 3. **Builds an index** — Pi SDK agent reads all sources and writes `index.md` with summaries
 4. **Watches** — drop a new PDF in while it's running, it gets parsed and indexed automatically
 
+### Query
+
+```bash
+# From inside the documents folder (auto-detects .llm-kb/)
+llm-kb query "what are the key findings?"
+
+# From anywhere, with explicit folder
+llm-kb query "compare Q3 vs Q4" --folder ./my-documents
+
+# Research mode — saves the answer to wiki/outputs/ and re-indexes
+llm-kb query "summarize all revenue data" --save
+```
+
+The agent reads `index.md`, selects relevant files, and streams a cited answer to the terminal.
+
+**Query mode** — read-only. The agent can only read your files.
+**Research mode** (`--save`) — read + write + bash. The agent saves answers to `outputs/`, re-indexes, and can write scripts to read Excel/Word files. Answers compound over time.
+
 ### What It Creates
 
 ```

package/bin/chunk-MYQ36JJB.js

@@ -0,0 +1,118 @@
+// src/indexer.ts
+import {
+  createAgentSession,
+  createBashTool,
+  createReadTool,
+  createWriteTool,
+  DefaultResourceLoader,
+  SessionManager,
+  SettingsManager
+} from "@mariozechner/pi-coding-agent";
+import { readdir, readFile } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+function getNodeModulesPath() {
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, "node_modules");
+    try {
+      return candidate;
+    } catch {
+      dir = dirname(dir);
+    }
+  }
+  return join(process.cwd(), "node_modules");
+}
+function buildAgentsContent(sourcesDir, files) {
+  const sourceList = files.filter((f) => f.endsWith(".md")).map((f) => `  - ${f}`).join("\n");
+  return `# llm-kb Knowledge Base
+
+## How to access documents
+
+### PDFs (pre-parsed)
+PDFs have been parsed to markdown with bounding boxes.
+Read the markdown versions in \`.llm-kb/wiki/sources/\` instead of the raw PDFs.
+
+Available parsed sources:
+${sourceList}
+
+### Other file types (Excel, Word, PowerPoint, CSV, images)
+You have bash and read tools. These libraries are pre-installed and available:
+- **exceljs** \u2014 for .xlsx/.xls files
+- **mammoth** \u2014 for .docx files  
+- **officeparser** \u2014 for .pptx files
+- **csv-parse** \u2014 built into Node.js, use fs + split for .csv
+
+Write a quick Node.js script to extract content when needed.
+
+## Index file
+Write the index to \`.llm-kb/wiki/index.md\`.
+
+The index should be a markdown file with:
+1. A title and last-updated timestamp
+2. A summary table with columns: Source, Type, Pages/Size, Summary, Key Topics
+3. Each source gets a one-line summary (read the first ~500 chars of each file to generate it)
+4. Total word count across all sources
+`;
+}
+async function buildIndex(folder, sourcesDir, onOutput) {
+  const files = await readdir(sourcesDir);
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+  if (mdFiles.length === 0) {
+    throw new Error("No source files found to index");
+  }
+  const agentsContent = buildAgentsContent(sourcesDir, files);
+  const nodeModulesPath = getNodeModulesPath();
+  process.env.NODE_PATH = nodeModulesPath;
+  const loader = new DefaultResourceLoader({
+    cwd: folder,
+    agentsFilesOverride: (current) => ({
+      agentsFiles: [
+        ...current.agentsFiles,
+        { path: ".llm-kb/AGENTS.md", content: agentsContent }
+      ]
+    })
+  });
+  await loader.reload();
+  const { session } = await createAgentSession({
+    cwd: folder,
+    resourceLoader: loader,
+    tools: [
+      createReadTool(folder),
+      createBashTool(folder),
+      createWriteTool(folder)
+    ],
+    sessionManager: SessionManager.inMemory(),
+    settingsManager: SettingsManager.inMemory({
+      compaction: { enabled: false }
+    })
+  });
+  if (onOutput) {
+    session.subscribe((event) => {
+      if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+        onOutput(event.assistantMessageEvent.delta);
+      }
+    });
+  }
+  const prompt = `Read each file in .llm-kb/wiki/sources/ (one at a time, just the first 500 characters of each).
+Then write .llm-kb/wiki/index.md with a summary table of all sources.
+
+Include: Source filename, Type (PDF/Excel/Word/etc), Pages (from the JSON if available), a one-line summary, and key topics.
+Add a total word count estimate at the bottom.`;
+  await session.prompt(prompt);
+  const indexPath = join(sourcesDir, "..", "index.md");
+  try {
+    const content = await readFile(indexPath, "utf-8");
+    session.dispose();
+    return content;
+  } catch {
+    session.dispose();
+    throw new Error("Agent did not create index.md");
+  }
+}
+
+export {
+  buildIndex
+};

package/bin/cli.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import {
+  buildIndex
+} from "./chunk-MYQ36JJB.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -123,121 +126,6 @@ ${p.text}`).join("\n\n---\n\n");
   };
 }
 
-// src/indexer.ts
-import {
-  createAgentSession,
-  createBashTool,
-  createReadTool,
-  createWriteTool,
-  DefaultResourceLoader,
-  SessionManager,
-  SettingsManager
-} from "@mariozechner/pi-coding-agent";
-import { readdir as readdir2, readFile } from "fs/promises";
-import { join as join2, dirname } from "path";
-import { fileURLToPath } from "url";
-var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname(__filename);
-function getNodeModulesPath() {
-  let dir = __dirname;
-  for (let i = 0; i < 5; i++) {
-    const candidate = join2(dir, "node_modules");
-    try {
-      return candidate;
-    } catch {
-      dir = dirname(dir);
-    }
-  }
-  return join2(process.cwd(), "node_modules");
-}
-function buildAgentsContent(sourcesDir, files) {
-  const sourceList = files.filter((f) => f.endsWith(".md")).map((f) => `  - ${f}`).join("\n");
-  return `# llm-kb Knowledge Base
-
-## How to access documents
-
-### PDFs (pre-parsed)
-PDFs have been parsed to markdown with bounding boxes.
-Read the markdown versions in \`.llm-kb/wiki/sources/\` instead of the raw PDFs.
-
-Available parsed sources:
-${sourceList}
-
-### Other file types (Excel, Word, PowerPoint, CSV, images)
-You have bash and read tools. These libraries are pre-installed and available:
-- **exceljs** \u2014 for .xlsx/.xls files
-- **mammoth** \u2014 for .docx files  
-- **officeparser** \u2014 for .pptx files
-- **csv-parse** \u2014 built into Node.js, use fs + split for .csv
-
-Write a quick Node.js script to extract content when needed.
-
-## Index file
-Write the index to \`.llm-kb/wiki/index.md\`.
-
-The index should be a markdown file with:
-1. A title and last-updated timestamp
-2. A summary table with columns: Source, Type, Pages/Size, Summary, Key Topics
-3. Each source gets a one-line summary (read the first ~500 chars of each file to generate it)
-4. Total word count across all sources
-`;
-}
-async function buildIndex(folder, sourcesDir, onOutput) {
-  const files = await readdir2(sourcesDir);
-  const mdFiles = files.filter((f) => f.endsWith(".md"));
-  if (mdFiles.length === 0) {
-    throw new Error("No source files found to index");
-  }
-  const agentsContent = buildAgentsContent(sourcesDir, files);
-  const nodeModulesPath = getNodeModulesPath();
-  process.env.NODE_PATH = nodeModulesPath;
-  const loader = new DefaultResourceLoader({
-    cwd: folder,
-    agentsFilesOverride: (current) => ({
-      agentsFiles: [
-        ...current.agentsFiles,
-        { path: ".llm-kb/AGENTS.md", content: agentsContent }
-      ]
-    })
-  });
-  await loader.reload();
-  const { session } = await createAgentSession({
-    cwd: folder,
-    resourceLoader: loader,
-    tools: [
-      createReadTool(folder),
-      createBashTool(folder),
-      createWriteTool(folder)
-    ],
-    sessionManager: SessionManager.inMemory(),
-    settingsManager: SettingsManager.inMemory({
-      compaction: { enabled: false }
-    })
-  });
-  if (onOutput) {
-    session.subscribe((event) => {
-      if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-        onOutput(event.assistantMessageEvent.delta);
-      }
-    });
-  }
-  const prompt = `Read each file in .llm-kb/wiki/sources/ (one at a time, just the first 500 characters of each).
-Then write .llm-kb/wiki/index.md with a summary table of all sources.
-
-Include: Source filename, Type (PDF/Excel/Word/etc), Pages (from the JSON if available), a one-line summary, and key topics.
-Add a total word count estimate at the bottom.`;
-  await session.prompt(prompt);
-  const indexPath = join2(sourcesDir, "..", "index.md");
-  try {
-    const content = await readFile(indexPath, "utf-8");
-    session.dispose();
-    return content;
-  } catch {
-    session.dispose();
-    throw new Error("Agent did not create index.md");
-  }
-}
-
 // src/watcher.ts
 import { watch } from "chokidar";
 import { extname as extname2, basename as basename2 } from "path";
@@ -307,18 +195,145 @@ function startWatcher({ folder, sourcesDir, debounceMs = 2e3 }) {
   return watcher;
 }
 
-// src/cli.ts
+// src/query.ts
+import {
+  createAgentSession,
+  createBashTool,
+  createReadTool,
+  createWriteTool,
+  DefaultResourceLoader,
+  SessionManager,
+  SettingsManager
+} from "@mariozechner/pi-coding-agent";
+import { readdir as readdir2, mkdir as mkdir2 } from "fs/promises";
+import { join as join3, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function getNodeModulesPath() {
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    const candidate = join3(dir, "node_modules");
+    try {
+      return candidate;
+    } catch {
+      dir = dirname(dir);
+    }
+  }
+  return join3(process.cwd(), "node_modules");
+}
+function buildQueryAgents(sourceFiles, save) {
+  const sourceList = sourceFiles.map((f) => `  - ${f}`).join("\n");
+  let content = `# llm-kb Knowledge Base \u2014 Query Mode
+
+## How to answer questions
+
+1. FIRST read .llm-kb/wiki/index.md to understand all available sources
+2. Based on the question, select the most relevant source files (usually 2-5)
+3. Read those source files in full from .llm-kb/wiki/sources/
+4. Answer with inline citations: (filename, page number)
+5. If the answer requires cross-referencing multiple files, read additional ones
+6. If you can't find the answer, say so \u2014 don't hallucinate
+
+## Available parsed sources
+${sourceList}
+
+## Non-PDF files
+If the user's folder has Excel, Word, or PowerPoint files, these libraries are available:
+- **exceljs** \u2014 for .xlsx/.xls files
+- **mammoth** \u2014 for .docx files
+- **officeparser** \u2014 for .pptx files
+Write a quick Node.js script via bash to read them.
+
+## Rules
+- Always cite sources with filename and page number
+- Read the FULL source file, not just the beginning
+- Prefer primary sources over previous analyses
+`;
+  if (save) {
+    content += `
+## Research Mode
+Save your analysis to .llm-kb/wiki/outputs/ with a descriptive filename (e.g., comparison-analysis.md).
+Include the question at the top and all citations.
+`;
+  }
+  return content;
+}
+async function query(folder, question, options) {
+  const sourcesDir = join3(folder, ".llm-kb", "wiki", "sources");
+  const files = await readdir2(sourcesDir);
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+  if (mdFiles.length === 0) {
+    throw new Error("No sources found. Run 'llm-kb run' first to parse documents.");
+  }
+  if (options.save) {
+    await mkdir2(join3(folder, ".llm-kb", "wiki", "outputs"), { recursive: true });
+  }
+  process.env.NODE_PATH = getNodeModulesPath();
+  const agentsContent = buildQueryAgents(mdFiles, !!options.save);
+  const loader = new DefaultResourceLoader({
+    cwd: folder,
+    agentsFilesOverride: (current) => ({
+      agentsFiles: [
+        ...current.agentsFiles,
+        { path: ".llm-kb/AGENTS.md", content: agentsContent }
+      ]
+    })
+  });
+  await loader.reload();
+  const tools = [createReadTool(folder)];
+  if (options.save) {
+    tools.push(createBashTool(folder), createWriteTool(folder));
+  }
+  const { session } = await createAgentSession({
+    cwd: folder,
+    resourceLoader: loader,
+    tools,
+    sessionManager: SessionManager.inMemory(),
+    settingsManager: SettingsManager.inMemory({
+      compaction: { enabled: false }
+    })
+  });
+  session.subscribe((event) => {
+    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+      process.stdout.write(event.assistantMessageEvent.delta);
+    }
+  });
+  await session.prompt(question);
+  console.log();
+  session.dispose();
+  if (options.save) {
+    const { buildIndex: buildIndex2 } = await import("./indexer-LSYSZXZX.js");
+    await buildIndex2(folder, sourcesDir);
+  }
+}
+
+// src/resolve-kb.ts
 import { existsSync } from "fs";
-import { mkdir as mkdir2 } from "fs/promises";
-import { resolve as resolve2, join as join4 } from "path";
+import { resolve as resolve2, join as join4, dirname as dirname2 } from "path";
+function resolveKnowledgeBase(startDir) {
+  let dir = resolve2(startDir);
+  while (true) {
+    if (existsSync(join4(dir, ".llm-kb"))) {
+      return dir;
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// src/cli.ts
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir3 } from "fs/promises";
+import { resolve as resolve3, join as join5 } from "path";
 import chalk2 from "chalk";
 var program = new Command();
-program.name("llm-kb").description("Drop files into a folder. Get a knowledge base you can query.").version("0.1.0");
+program.name("llm-kb").description("Drop files into a folder. Get a knowledge base you can query.").version("0.2.0");
 program.command("run").description("Scan, parse, index, and watch a folder").argument("<folder>", "Path to your documents folder").action(async (folder) => {
   console.log(`
-${chalk2.bold("llm-kb")} v0.1.0
+${chalk2.bold("llm-kb")} v0.2.0
 `);
-  if (!existsSync(folder)) {
+  if (!existsSync2(folder)) {
     console.error(chalk2.red(`Error: Folder not found: ${folder}`));
     process.exit(1);
   }
@@ -331,16 +346,16 @@ ${chalk2.bold("llm-kb")} v0.1.0
   const pdfs = files.filter((f) => f.ext === ".pdf");
   console.log(`  Found ${chalk2.bold(files.length.toString())} files (${summarize(files)})`);
   if (pdfs.length === 0) return;
-  const root = resolve2(folder);
-  const sourcesDir = join4(root, ".llm-kb", "wiki", "sources");
-  await mkdir2(sourcesDir, { recursive: true });
+  const root = resolve3(folder);
+  const sourcesDir = join5(root, ".llm-kb", "wiki", "sources");
+  await mkdir3(sourcesDir, { recursive: true });
   let parsed = 0;
   let skipped = 0;
   let failed = 0;
   const errors = [];
   for (let i = 0; i < pdfs.length; i++) {
     const pdf = pdfs[i];
-    const fullPath = join4(root, pdf.path);
+    const fullPath = join5(root, pdf.path);
     const progress = `  Parsing... ${i + 1}/${pdfs.length} \u2014 ${pdf.name}`;
     process.stdout.write(`\r${progress.padEnd(80)}`);
     try {
@@ -378,4 +393,17 @@ ${chalk2.bold("llm-kb")} v0.1.0
   Watching for new files... (Ctrl+C to stop)`));
   startWatcher({ folder: root, sourcesDir });
 });
+program.command("query").description("Ask a question across your knowledge base").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, options) => {
+  const root = resolveKnowledgeBase(options.folder || process.cwd());
+  if (!root) {
+    console.error(chalk2.red("No knowledge base found. Run 'llm-kb run <folder>' first."));
+    process.exit(1);
+  }
+  try {
+    await query(root, question, { save: options.save });
+  } catch (err) {
+    console.error(chalk2.red(err.message));
+    process.exit(1);
+  }
+});
 program.parse();

package/bin/indexer-LSYSZXZX.js

@@ -0,0 +1,6 @@
+import {
+  buildIndex
+} from "./chunk-MYQ36JJB.js";
+export {
+  buildIndex
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-kb",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "LLM-powered knowledge base. Drop documents, build a wiki, ask questions. Inspired by Karpathy.",
   "bin": {
     "llm-kb": "./bin/cli.js"

package/plan.md

@@ -45,7 +45,11 @@ Config file has no readers yet. Deferred to Phase 2/3. README updated instead.
 - OCR via env var (local Tesseract or remote Azure bridge)
 - Auth via Pi SDK (zero config)
 
-**What's next (Phase 2):**
-- `llm-kb query "question" --folder ./research` — terminal query
-- Pi SDK agent session for Q&A with read-only tools
-- Research mode — agent writes answers to `outputs/`
+**Phase 2 complete ✅:**
+- `llm-kb query "question"` — auto-detects KB, streams cited answers
+- `--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

package/src/cli.ts

@@ -5,6 +5,8 @@ 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 { resolveKnowledgeBase } from "./resolve-kb.js";
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { resolve, join } from "node:path";
@@ -15,14 +17,14 @@ const program = new Command();
 program
   .name("llm-kb")
   .description("Drop files into a folder. Get a knowledge base you can query.")
-  .version("0.1.0");
+  .version("0.2.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.1.0\n`);
+    console.log(`\n${chalk.bold("llm-kb")} v0.2.0\n`);
 
     if (!existsSync(folder)) {
       console.error(chalk.red(`Error: Folder not found: ${folder}`));
@@ -105,4 +107,26 @@ program
     startWatcher({ folder: root, sourcesDir });
   });
 
+program
+  .command("query")
+  .description("Ask a question across your knowledge base")
+  .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());
+
+    if (!root) {
+      console.error(chalk.red("No knowledge base found. Run 'llm-kb run <folder>' first."));
+      process.exit(1);
+    }
+
+    try {
+      await query(root, question, { save: options.save });
+    } catch (err: any) {
+      console.error(chalk.red(err.message));
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/src/query.ts

@@ -0,0 +1,132 @@
+import {
+  createAgentSession,
+  createBashTool,
+  createReadTool,
+  createWriteTool,
+  DefaultResourceLoader,
+  SessionManager,
+  SettingsManager,
+} from "@mariozechner/pi-coding-agent";
+import { readdir, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function getNodeModulesPath(): string {
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, "node_modules");
+    try { return candidate; } catch { dir = dirname(dir); }
+  }
+  return join(process.cwd(), "node_modules");
+}
+
+function buildQueryAgents(sourceFiles: string[], save: boolean): string {
+  const sourceList = sourceFiles.map((f) => `  - ${f}`).join("\n");
+
+  let content = `# llm-kb Knowledge Base — Query Mode
+
+## How to answer questions
+
+1. FIRST read .llm-kb/wiki/index.md to understand all available sources
+2. Based on the question, select the most relevant source files (usually 2-5)
+3. Read those source files in full from .llm-kb/wiki/sources/
+4. Answer with inline citations: (filename, page number)
+5. If the answer requires cross-referencing multiple files, read additional ones
+6. If you can't find the answer, say so — don't hallucinate
+
+## Available parsed sources
+${sourceList}
+
+## Non-PDF files
+If the user's folder has Excel, Word, or PowerPoint files, these libraries are available:
+- **exceljs** — for .xlsx/.xls files
+- **mammoth** — for .docx files
+- **officeparser** — for .pptx files
+Write a quick Node.js script via bash to read them.
+
+## Rules
+- Always cite sources with filename and page number
+- Read the FULL source file, not just the beginning
+- Prefer primary sources over previous analyses
+`;
+
+  if (save) {
+    content += `
+## Research Mode
+Save your analysis to .llm-kb/wiki/outputs/ with a descriptive filename (e.g., comparison-analysis.md).
+Include the question at the top and all citations.
+`;
+  }
+
+  return content;
+}
+
+export async function query(
+  folder: string,
+  question: string,
+  options: { save?: boolean }
+): Promise<void> {
+  const sourcesDir = join(folder, ".llm-kb", "wiki", "sources");
+
+  const files = await readdir(sourcesDir);
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+
+  if (mdFiles.length === 0) {
+    throw new Error("No sources found. Run 'llm-kb run' first to parse documents.");
+  }
+
+  if (options.save) {
+    await mkdir(join(folder, ".llm-kb", "wiki", "outputs"), { recursive: true });
+  }
+
+  process.env.NODE_PATH = getNodeModulesPath();
+
+  const agentsContent = buildQueryAgents(mdFiles, !!options.save);
+
+  const loader = new DefaultResourceLoader({
+    cwd: folder,
+    agentsFilesOverride: (current) => ({
+      agentsFiles: [
+        ...current.agentsFiles,
+        { path: ".llm-kb/AGENTS.md", content: agentsContent },
+      ],
+    }),
+  });
+  await loader.reload();
+
+  const tools = [createReadTool(folder)];
+  if (options.save) {
+    tools.push(createBashTool(folder), createWriteTool(folder));
+  }
+
+  const { session } = await createAgentSession({
+    cwd: folder,
+    resourceLoader: loader,
+    tools,
+    sessionManager: SessionManager.inMemory(),
+    settingsManager: SettingsManager.inMemory({
+      compaction: { enabled: false },
+    }),
+  });
+
+  session.subscribe((event) => {
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "text_delta"
+    ) {
+      process.stdout.write(event.assistantMessageEvent.delta);
+    }
+  });
+
+  await session.prompt(question);
+  console.log();
+  session.dispose();
+
+  // Re-index after save so the compounding loop works
+  if (options.save) {
+    const { buildIndex } = await import("./indexer.js");
+    await buildIndex(folder, sourcesDir);
+  }
+}

package/src/resolve-kb.ts

@@ -0,0 +1,19 @@
+import { existsSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+
+/**
+ * Walk up from startDir looking for a .llm-kb/ directory.
+ * Returns the folder containing .llm-kb/, or null if not found.
+ */
+export function resolveKnowledgeBase(startDir: string): string | null {
+  let dir = resolve(startDir);
+
+  while (true) {
+    if (existsSync(join(dir, ".llm-kb"))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}