learnforge 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,3549 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { spawn as spawn2 } from "node:child_process";
+import { existsSync as existsSync6, readFileSync as readFileSync5, statSync as statSync5 } from "node:fs";
+import { tmpdir as tmpdir3 } from "node:os";
+import { dirname as dirname3, extname as extname3, join as join8, resolve as resolve4 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { serve } from "@hono/node-server";
+import { Hono as Hono2 } from "hono";
+
+// src/server/app.ts
+import { existsSync as existsSync5, statSync as statSync4 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { Hono } from "hono";
+
+// src/core/agent/index.ts
+import { execFileSync } from "node:child_process";
+
+// src/core/agent/cli.ts
+import { spawn } from "node:child_process";
+function runCli(command, args, opts2) {
+  return new Promise((resolve5, reject) => {
+    const child = spawn(command, args, { cwd: opts2.cwd, env: { ...process.env, ...opts2.env }, stdio: ["pipe", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error(`model call timed out after ${Math.round(opts2.timeoutMs / 1e3)}s`));
+    }, opts2.timeoutMs);
+    child.stdout.on("data", (d) => out += d);
+    child.stderr.on("data", (d) => err += d);
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve5(out);
+      else reject(new Error(`${command} exited ${code}: ${(err || out).trim().slice(-600)}`));
+    });
+    child.stdin.end(opts2.stdin ?? "");
+  });
+}
+
+// src/core/agent/claude.ts
+var ClaudeCliAgent = class {
+  constructor(command, model, timeoutMs, planModel = "") {
+    this.command = command;
+    this.model = model;
+    this.timeoutMs = timeoutMs;
+    this.planModel = planModel;
+  }
+  name = "Claude Code CLI";
+  complete(req) {
+    const args = ["-p", "--output-format", "text", "--tools", "Read", "Grep", "Glob", "--append-system-prompt", req.system];
+    const model = req.role === "plan" && this.planModel ? this.planModel : this.model;
+    if (model) args.push("--model", model);
+    return runCli(this.command, args, { cwd: req.cwd, stdin: req.prompt, timeoutMs: this.timeoutMs });
+  }
+};
+
+// src/core/agent/codex.ts
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+var CodexCliAgent = class {
+  constructor(command, model, timeoutMs) {
+    this.command = command;
+    this.model = model;
+    this.timeoutMs = timeoutMs;
+  }
+  name = "Codex CLI";
+  async complete(req) {
+    const out = join(mkdtempSync(join(tmpdir(), "learnforge-codex-")), "last.md");
+    const args = ["exec", "--sandbox", "read-only", "--skip-git-repo-check", "--cd", req.cwd, "--output-last-message", out];
+    if (this.model) args.push("--model", this.model);
+    args.push("-");
+    const stdout = await runCli(this.command, args, { cwd: req.cwd, stdin: `${req.system}
+
+---
+
+${req.prompt}`, timeoutMs: this.timeoutMs });
+    try {
+      return readFileSync(out, "utf8");
+    } catch {
+      return stdout;
+    }
+  }
+};
+
+// src/core/agent/copilot.ts
+import { mkdtempSync as mkdtempSync2, writeFileSync } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join2 } from "node:path";
+var CopilotCliAgent = class {
+  constructor(command, model, timeoutMs) {
+    this.command = command;
+    this.model = model;
+    this.timeoutMs = timeoutMs;
+  }
+  name = "GitHub Copilot CLI";
+  async complete(req) {
+    const dir = mkdtempSync2(join2(tmpdir2(), "learnforge-copilot-"));
+    const file = join2(dir, "task.md");
+    writeFileSync(file, `${req.system}
+
+---
+
+${req.prompt}`);
+    const prompt = `Read the file ${file} and do exactly what it says. Reply with the answer only.`;
+    const args = ["-p", prompt, "-s", "--no-ask-user", "--allow-tool=read", "--deny-tool=shell", "--deny-tool=write", `--add-dir=${dir}`];
+    if (this.model) args.push(`--model=${this.model}`);
+    return runCli(this.command, args, { cwd: req.cwd, timeoutMs: this.timeoutMs });
+  }
+};
+
+// src/core/agent/fake.ts
+var FakeAgent = class {
+  name = "fake";
+  async complete(req) {
+    const task = /^TASK: (\w+)/m.exec(req.system)?.[1] ?? "";
+    const file = /=== FILE (\S+)/.exec(req.prompt)?.[1] ?? "file";
+    if (process.env.LEARNFORGE_FAKE_FAIL === task) throw new Error(`fake failure for ${task}`);
+    const delay = Number(process.env.LEARNFORGE_FAKE_DELAY_MS ?? 0);
+    if (delay) await new Promise((r) => setTimeout(r, delay));
+    return "```json\n" + JSON.stringify(this.reply(task, file, req.prompt, req.system), null, 2) + "\n```";
+  }
+  reply(task, file, prompt, system) {
+    switch (task) {
+      case "lens": {
+        const sketch = /SKETCH/.test(prompt) ? { differences: ["Your sketch is close; you missed the error path at line 3."] } : {};
+        const traceInput = /TRACE INPUT: (.*)/.exec(prompt)?.[1];
+        const trace = /"trace":/.test(system) ? {
+          trace: {
+            input: traceInput && !traceInput.startsWith("(") ? traceInput : "n = 3",
+            steps: [1, 2, 3].map((i) => ({ file, line: i, state: { n: String(3 - i + 1), total: String(i * 2) }, note: `Step ${i}: line ${i} runs.` }))
+          }
+        } : {};
+        return {
+          ...sketch,
+          ...trace,
+          tldr: `The one idea: ${file} turns input into output in a single pass.`,
+          whyItMatters: "Without this model you will change the wrong line.",
+          gotchas: ["Line 3 runs even when the input is empty."],
+          nextSteps: [{ file, why: "Read it again with the steps in mind." }],
+          title: `How ${file} works`,
+          summary: `This is a fake lesson about ${file}. It shows the shape of a real one.`,
+          concepts: [
+            { term: "Entry point", explain: "Where the work starts.", example: "Like the front door of a house.", file, line: 1 },
+            { term: "Side effect", explain: "A change outside the function, like a file write." }
+          ],
+          intuition: "Input flows to output:\n\n```mermaid\nflowchart LR\n  A[input] --> B[transform] --> C[output]\n```",
+          deepDives: [
+            { title: "The top of the file sets up what the rest needs", file, line: 1, startLine: 1, endLine: 4, body: "Imports and setup.", check: { q: "What does line 1 bring in?", a: "The types the rest uses." } },
+            { title: "The main logic", file, line: 3, startLine: 3, endLine: 8, body: "Where the work happens.", pitfall: "Changing the order here breaks the output." }
+          ]
+        };
+      }
+      case "walkPlan":
+        return { blocks: [1, 2].map((i) => ({ startLine: i, endLine: i + 2, title: `Block ${i} does one thing`, covers: ["a fact"], example: "n = 3", question: "what happens for n = 3?" })) };
+      case "walkBlocks": {
+        const m = /WRITE BLOCKS (\d+)-(\d+)/.exec(prompt);
+        const [a, b] = m ? [Number(m[1]), Number(m[2])] : [0, 0];
+        return {
+          blocks: Array.from({ length: b - a + 1 }, (_, k) => ({
+            index: a + k,
+            why: `Block ${a + k} follows the last one.`,
+            explain: `Fake explanation for block ${a + k}.`,
+            example: "With `n = 3`:\n\n```\nresult = f(3)  # 6\n```",
+            question: `Fake question ${a + k}: what does f(3) give?`
+          }))
+        };
+      }
+      case "plan":
+        return { outline: "1. Start with the entry point.\n2. Cover the main branch.\n3. End with the error path." };
+      case "lensPlan":
+        return {
+          title: `How ${file} works`,
+          tldr: `The one idea: ${file} turns input into output in a single pass.`,
+          whyItMatters: "Without this model you will change the wrong line.",
+          concepts: [{ term: "Entry point", note: "Where the work starts.", file, line: 1 }],
+          intuition: { example: "n = 3", diagram: "input to output" },
+          steps: [1, 2, 3, 4].map((i) => ({
+            title: `Step ${i} is one idea about ${file}`,
+            file,
+            startLine: i,
+            endLine: i + 3,
+            line: i,
+            covers: [`Fact ${i}`],
+            example: "n = 3",
+            edge: "",
+            why: "It keeps the output stable.",
+            pitfall: "",
+            check: "what if empty?"
+          })),
+          gotchas: ["Line 3 runs even when the input is empty."],
+          nextSteps: [{ file, why: "Read it again with the steps in mind." }]
+        };
+      case "lensIntro": {
+        const sketch = /SKETCH/.test(prompt) ? { differences: ["Your sketch is close; you missed the error path at line 3."] } : {};
+        const traceInput = /TRACE INPUT: (.*)/.exec(prompt)?.[1];
+        const trace = /"trace":/.test(system) ? { trace: { input: traceInput && !traceInput.startsWith("(") ? traceInput : "n = 3", steps: [1, 2, 3].map((i) => ({ file, line: i, state: { n: String(i) }, note: `Step ${i}: line ${i} runs.` })) } } : {};
+        return {
+          ...sketch,
+          ...trace,
+          summary: `This is a fake lesson about ${file}. It shows the shape of a real one.`,
+          concepts: [
+            { term: "Entry point", explain: "Where the work starts.", example: "Like the front door of a house.", file, line: 1 },
+            { term: "Side effect", explain: "A change outside the function, like a file write." }
+          ],
+          intuition: "Input flows to output:\n\n```mermaid\nflowchart LR\n  A[input] --> B[transform] --> C[output]\n```",
+          gotchas: ["Line 3 runs even when the input is empty."],
+          nextSteps: [{ file, why: "Read it again with the steps in mind." }]
+        };
+      }
+      case "lensSteps": {
+        const m = /WRITE STEPS (\d+)-(\d+)/.exec(prompt);
+        const [a, b] = m ? [Number(m[1]), Number(m[2])] : [0, 0];
+        return {
+          steps: Array.from({ length: b - a + 1 }, (_, k) => ({
+            index: a + k,
+            body: `Fake body for step ${a + k}. It explains the idea with real values.`,
+            pitfall: "Changing the order here breaks the output.",
+            check: { q: `What does step ${a + k} do?`, a: "It does the thing." }
+          }))
+        };
+      }
+      case "quiz": {
+        const n = Number(/exactly (\d+) items/.exec(system)?.[1] ?? 3);
+        const weak = [...prompt.matchAll(/^\[(\w+)\] /gm)].map((m) => m[1]);
+        return {
+          title: weak.length ? "Your weak spots" : `Quiz on ${file}`,
+          questions: Array.from({ length: n || 3 }, (_, i) => ({
+            targets: weak[i],
+            prompt: `Fake question ${i + 1}: what does line ${i + 1} of ${file} do?`,
+            file,
+            line: i + 1,
+            focus: "line purpose"
+          }))
+        };
+      }
+      case "grade": {
+        const ids = [...prompt.matchAll(/^\[(q\d+)\] Q:/gm)].map((m) => m[1]);
+        const answers = [...prompt.matchAll(/^A: (.*)$/gm)].map((m) => m[1]);
+        return {
+          grades: ids.map((qid, i) => {
+            const a = answers[i] ?? "";
+            const verdict3 = a.length > 20 ? "right" : a.length > 3 && a !== "(no answer)" ? "partial" : "wrong";
+            return {
+              qid,
+              verdict: verdict3,
+              feedback: `Fake grade (${a.length} chars).`,
+              modelAnswer: "The model answer.",
+              ...verdict3 === "right" ? {} : { misconception: `You think question ${qid} is about names, but it is about behaviour.` }
+            };
+          })
+        };
+      }
+      case "practice":
+        const block = prompt.split("=== FILE ")[1] ?? "";
+        const body = [...block.matchAll(/^\s*(\d+)\| (.*)$/gm)].map((m) => ({ n: Number(m[1]), text: m[2] }));
+        const real = (t) => !!t.trim() && !/^\s*(\/\/|#|\*|\/\*|import\b|from\b|[{}()\[\];,]+\s*$)/.test(t);
+        const at = body.findIndex((l, i) => l.n >= 2 && real(l.text) && real(body[i + 1]?.text ?? ""));
+        const start = at >= 0 ? body[at].n : 2;
+        return { concept: "Fake concept.", holes: [{ file: /=== FILE (\S+)/.exec(prompt)?.[1], startLine: start, endLine: start + 1, intent: "Do the main step.", hints: ["Look at the names.", "Return the result."] }] };
+      case "review": {
+        const ids = [...prompt.matchAll(/^hole (\d+):/gm)].map((m) => Number(m[1]));
+        return { summary: "Fake review.", holes: ids.map((id) => ({ id, verdict: "partial", feedback: "Close." })) };
+      }
+      case "teachback": {
+        const text2 = /THE LEARNER'S EXPLANATION:\n([\s\S]*?)\n\nCODE:/.exec(prompt)?.[1] ?? "";
+        const score = text2.length > 120 ? 4 : text2.length > 40 ? 3 : 2;
+        return {
+          score,
+          summary: "Fake teach-back grade.",
+          right: ["You name the main step."],
+          missing: ["The error path."],
+          wrong: score < 4 ? ["You say it retries, but it gives up after one try (line 3)."] : []
+        };
+      }
+      case "tutor": {
+        const tell = /tell them/.test(system);
+        return { reply: tell ? "Here is the answer: line 2 does the work. What would change if it were missing?" : "What do you see on line 2? What does it return?" };
+      }
+      case "walk":
+        return {
+          blocks: [
+            { startLine: 1, endLine: 2, title: "Setup", why: "Where it starts.", question: "What does the first line bring in?" },
+            { startLine: 3, endLine: 4, title: "Main step", why: "The work.", question: "What does the main step return?" }
+          ]
+        };
+      case "walkcheck": {
+        const a = /^ANSWER: (.*)$/m.exec(prompt)?.[1] ?? "";
+        const v = a.length > 20 ? "right" : a.length > 3 && a !== "(no answer)" ? "partial" : "wrong";
+        return { verdict: v, feedback: `Fake check (${a.length} chars).`, ...v === "right" ? {} : { misconception: "You think the block sets up state, but it returns a value." } };
+      }
+      case "hunt": {
+        const m = /^\s*(\d+)\| (.*\S.*)$/m.exec(prompt);
+        const line2 = Number(m?.[1] ?? 1);
+        const original = m?.[2] ?? "";
+        return { bugs: [{ line: line2, original, buggy: `${original} // changed`, what: "The fake bug changes the first line." }] };
+      }
+      case "huntgrade": {
+        const found = [...prompt.matchAll(/-> bug line (\d+)/g)].map((m) => ({ line: Number(m[1]), feedback: "Right line, right reason." }));
+        const fa = /FALSE ALARMS:\n([\s\S]*?)\n\nTHE FILE/.exec(prompt)?.[1] ?? "";
+        const falseAlarms = [...fa.matchAll(/^line (\d+):/gm)].map((m) => ({ line: Number(m[1]), feedback: "This line is fine." }));
+        return { found, falseAlarms };
+      }
+      case "path": {
+        const files = (/ALL FILES:\n([\s\S]*?)(\n\n|$)/.exec(prompt)?.[1] ?? "").split("\n").filter(Boolean);
+        const pick = files.filter((f) => /\.(ts|js|py|md)$/.test(f)).slice(0, 3);
+        return {
+          title: "Fake onboarding path",
+          stops: pick.map((f, i) => ({ title: `Stop ${i + 1}: ${f}`, files: [f], why: "Fake reason.", activity: i === 2 ? "quiz" : "lens" }))
+        };
+      }
+      default:
+        return {};
+    }
+  }
+};
+
+// src/core/agent/sdk.ts
+import Anthropic from "@anthropic-ai/sdk";
+var SdkAgent = class {
+  constructor(model, timeoutMs, planModel = "") {
+    this.model = model;
+    this.planModel = planModel;
+    this.client = new Anthropic({ timeout: timeoutMs });
+  }
+  name = "Anthropic API";
+  client;
+  async complete(req) {
+    const msg = await this.client.messages.create({
+      model: req.role === "plan" && this.planModel ? this.planModel : this.model,
+      max_tokens: 16e3,
+      system: req.system,
+      messages: [{ role: "user", content: req.prompt }]
+    });
+    return msg.content.map((b) => b.type === "text" ? b.text : "").join("");
+  }
+};
+
+// src/core/agent/index.ts
+function hasCommand(cmd) {
+  try {
+    execFileSync(cmd, ["--version"], { stdio: "ignore", timeout: 1e4 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function providers(s, timeoutMs) {
+  return [
+    {
+      id: "claude",
+      label: "Claude Code CLI",
+      available: () => hasCommand(s["agent.claudeCommand"]),
+      make: () => new ClaudeCliAgent(s["agent.claudeCommand"], s["agent.model"], timeoutMs, s["agent.planModel"]),
+      detail: `${s["agent.claudeCommand"]} -p, model ${s["agent.model"] || "CLI default"}, read-only tools, your Claude Code login`,
+      missing: `"${s["agent.claudeCommand"]}" not found. Install Claude Code and run it once to log in.`
+    },
+    {
+      id: "codex",
+      label: "Codex CLI",
+      available: () => hasCommand(s["agent.codexCommand"]),
+      make: () => new CodexCliAgent(s["agent.codexCommand"], s["agent.codexModel"], timeoutMs),
+      detail: `${s["agent.codexCommand"]} exec, read-only sandbox, model ${s["agent.codexModel"] || "CLI default"}, your codex login`,
+      missing: `"${s["agent.codexCommand"]}" not found. Install it (npm i -g @openai/codex) and run "codex login".`
+    },
+    {
+      id: "copilot",
+      label: "GitHub Copilot CLI",
+      available: () => hasCommand(s["agent.copilotCommand"]),
+      make: () => new CopilotCliAgent(s["agent.copilotCommand"], s["agent.copilotModel"], timeoutMs),
+      detail: `${s["agent.copilotCommand"]} -p, read tool only, model ${s["agent.copilotModel"] || "CLI default"}, your GitHub login`,
+      missing: `"${s["agent.copilotCommand"]}" not found. Install it (npm i -g @github/copilot) and log in once.`
+    },
+    {
+      id: "sdk",
+      label: "Anthropic API",
+      available: () => !!process.env.ANTHROPIC_API_KEY,
+      make: () => new SdkAgent(s["agent.model"], timeoutMs, s["agent.planModel"]),
+      detail: `model ${s["agent.model"]}, key from the ANTHROPIC_API_KEY environment variable`,
+      missing: "Set ANTHROPIC_API_KEY in the environment, then restart learnforge."
+    }
+  ];
+}
+function makeAgent(s) {
+  const mode = process.env.LEARNFORGE_AGENT || s["agent.mode"];
+  const timeoutMs = s["agent.timeoutSec"] * 1e3;
+  const all = providers(s, timeoutMs);
+  const available = Object.fromEntries(all.map((p) => [p.id, p.available()]));
+  if (mode === "fake") {
+    return { agent: new FakeAgent(), info: { mode, name: "fake", ready: true, detail: "Canned answers for tests and demos.", available } };
+  }
+  const pick = mode === "auto" ? all.find((p) => available[p.id]) : all.find((p) => p.id === mode && available[p.id]);
+  if (pick) return { agent: pick.make(), info: { mode, name: pick.label, ready: true, detail: pick.detail, available } };
+  const wanted = all.find((p) => p.id === mode);
+  const detail = wanted ? wanted.missing : "No model found. Install Claude Code, Codex or Copilot CLI, or set ANTHROPIC_API_KEY, then restart.";
+  return { agent: null, info: { mode, name: "none", ready: false, detail, available } };
+}
+
+// src/core/insights.ts
+import { createEmptyCard, fsrs, Rating as R } from "ts-fsrs";
+
+// src/core/store.ts
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync as readFileSync2, readdirSync, renameSync, utimesSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { join as join3, basename, resolve } from "node:path";
+var DEFAULT_SETTINGS = {
+  "agent.mode": "auto",
+  "agent.model": "claude-sonnet-5-5",
+  "agent.planModel": "claude-opus-5-5",
+  "generate.plan": true,
+  "agent.claudeCommand": "claude",
+  "agent.codexCommand": "codex",
+  "agent.codexModel": "",
+  "agent.copilotCommand": "copilot",
+  "agent.copilotModel": "",
+  "agent.timeoutSec": 300,
+  "quiz.questions": 4,
+  "quiz.passMark": 0.67,
+  "context.maxBytes": 16e4,
+  "cards.fromMisses": true,
+  "progress.fadeDays": 21,
+  "notes.inPrompts": false,
+  "storage.archiveDays": 30,
+  "storage.cacheMB": 50,
+  "storage.maxAttempts": 20
+};
+var COLLECTIONS = [
+  "lenses",
+  "quizzes",
+  "practice",
+  "cards",
+  "misconceptions",
+  "teachbacks",
+  "threads",
+  "walks",
+  "hunts",
+  "paths",
+  "notes"
+];
+function newId() {
+  return Date.now().toString(36) + randomBytes(3).toString("hex");
+}
+function projectIdFor(root) {
+  const slug2 = basename(root).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "project";
+  return `${slug2}-${createHash("sha1").update(root).digest("hex").slice(0, 6)}`;
+}
+var Store = class {
+  home;
+  constructor(home = process.env.LEARNFORGE_HOME || join3(homedir(), ".learnforge")) {
+    this.home = resolve(home);
+    mkdirSync(join3(this.home, "projects"), { recursive: true });
+  }
+  // ---- low level -------------------------------------------------------
+  read(path2, fallback) {
+    if (!existsSync(path2)) return fallback;
+    try {
+      return JSON.parse(readFileSync2(path2, "utf8"));
+    } catch {
+      return fallback;
+    }
+  }
+  /** Write to a temp file then rename, so a crash never leaves half a file. */
+  write(path2, data) {
+    const tmp = `${path2}.${process.pid}.tmp`;
+    writeFileSync2(tmp, JSON.stringify(data, null, 2));
+    renameSync(tmp, path2);
+  }
+  // ---- settings --------------------------------------------------------
+  settings() {
+    return { ...DEFAULT_SETTINGS, ...this.read(join3(this.home, "settings.json"), {}) };
+  }
+  saveSettings(patch) {
+    const next = { ...this.settings() };
+    for (const [k, v] of Object.entries(patch)) {
+      if (k in DEFAULT_SETTINGS && v !== void 0 && v !== null) next[k] = v;
+    }
+    this.write(join3(this.home, "settings.json"), next);
+    return next;
+  }
+  // ---- projects --------------------------------------------------------
+  projects() {
+    return this.read(join3(this.home, "projects.json"), []).sort(
+      (a, b) => b.openedAt.localeCompare(a.openedAt)
+    );
+  }
+  project(id) {
+    return this.projects().find((p) => p.id === id);
+  }
+  saveProjects(list) {
+    this.write(join3(this.home, "projects.json"), list);
+  }
+  /** Add a folder, or touch it if it is already known. */
+  openProject(root, name) {
+    const abs = resolve(root);
+    const list = this.projects();
+    const now2 = (/* @__PURE__ */ new Date()).toISOString();
+    let p = list.find((x) => x.root === abs);
+    if (p) {
+      p.openedAt = now2;
+      if (name) p.name = name;
+    } else {
+      p = { id: projectIdFor(abs), name: name || basename(abs), root: abs, contexts: [], addedAt: now2, openedAt: now2 };
+      list.push(p);
+      const old = join3(this.home, "archive", "projects", p.id);
+      const live = join3(this.home, "projects", p.id);
+      if (existsSync(old) && !existsSync(live)) renameSync(old, live);
+    }
+    this.saveProjects(list);
+    return p;
+  }
+  updateProject(id, patch) {
+    const list = this.projects();
+    const p = list.find((x) => x.id === id);
+    if (!p) return void 0;
+    if (patch.name) p.name = patch.name;
+    if (patch.contexts) p.contexts = [...new Set(patch.contexts.map((c) => resolve(c)))].filter((c) => c !== p.root);
+    this.saveProjects(list);
+    return p;
+  }
+  /**
+   * Forget the folder. Its data moves to archive/projects/ and is removed after
+   * storage.archiveDays, so forgotten projects do not pile up. Opening the folder again
+   * within that time brings the history back.
+   */
+  forgetProject(id) {
+    this.saveProjects(this.projects().filter((p) => p.id !== id));
+    if (!/^[a-z0-9-]+$/.test(id)) return;
+    const src = join3(this.home, "projects", id);
+    if (!existsSync(src)) return;
+    const dst = join3(this.home, "archive", "projects");
+    mkdirSync(dst, { recursive: true });
+    const target = join3(dst, id);
+    if (existsSync(target)) renameSync(target, `${target}-${Date.now()}`);
+    renameSync(src, target);
+    const now2 = /* @__PURE__ */ new Date();
+    utimesSync(target, now2, now2);
+  }
+  // ---- collections -----------------------------------------------------
+  dir(projectId, c) {
+    if (!/^[a-z0-9-]+$/.test(projectId)) throw new Error("bad project id");
+    const d = join3(this.home, "projects", projectId, c);
+    mkdirSync(d, { recursive: true });
+    return d;
+  }
+  list(projectId, c) {
+    const d = this.dir(projectId, c);
+    return readdirSync(d).filter((f) => f.endsWith(".json")).map((f) => this.read(join3(d, f), null)).filter((x) => x !== null).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  }
+  get(projectId, c, id) {
+    if (!/^[a-z0-9]+$/.test(id)) return void 0;
+    return this.read(join3(this.dir(projectId, c), `${id}.json`), void 0);
+  }
+  put(projectId, c, item) {
+    this.write(join3(this.dir(projectId, c), `${item.id}.json`), item);
+    return item;
+  }
+  /** Move to an archive folder instead of erasing. */
+  archive(projectId, c, id) {
+    if (!/^[a-z0-9]+$/.test(id)) return false;
+    const src = join3(this.dir(projectId, c), `${id}.json`);
+    if (!existsSync(src)) return false;
+    const dst = join3(this.home, "projects", projectId, "archive", c);
+    mkdirSync(dst, { recursive: true });
+    const to = join3(dst, `${id}.json`);
+    renameSync(src, to);
+    const now2 = /* @__PURE__ */ new Date();
+    utimesSync(to, now2, now2);
+    return true;
+  }
+};
+
+// src/core/storage.ts
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync as readdirSync2, rmSync, statSync, utimesSync as utimesSync2 } from "node:fs";
+import { join as join4, sep } from "node:path";
+var DAY = 864e5;
+var CARD_REVIEW_CAP = 50;
+var THREAD_MESSAGE_CAP = 200;
+function walk(dir, each) {
+  const out = { bytes: 0, files: 0 };
+  if (!existsSync2(dir)) return out;
+  for (const e of readdirSync2(dir, { withFileTypes: true })) {
+    const p = join4(dir, e.name);
+    if (e.isDirectory()) {
+      const sub = walk(p, each);
+      out.bytes += sub.bytes;
+      out.files += sub.files;
+    } else if (e.isFile()) {
+      const st = statSync(p);
+      out.bytes += st.size;
+      out.files++;
+      each?.(p, st.size, st.mtimeMs);
+    }
+  }
+  return out;
+}
+function usage(store2) {
+  const home = store2.home;
+  const parts = [];
+  const byName = /* @__PURE__ */ new Map();
+  const add = (name, w) => {
+    const cur = byName.get(name) ?? { bytes: 0, files: 0 };
+    byName.set(name, { bytes: cur.bytes + w.bytes, files: cur.files + w.files });
+  };
+  const projects = join4(home, "projects");
+  if (existsSync2(projects)) {
+    for (const pid of readdirSync2(projects)) {
+      for (const c of [...COLLECTIONS, "archive"]) add(c, walk(join4(projects, pid, c)));
+    }
+  }
+  add("cache", walk(join4(home, "cache")));
+  add("forgotten projects", walk(join4(home, "archive")));
+  for (const [name, w] of byName) if (w.files) parts.push({ name, ...w });
+  parts.sort((a, b) => b.bytes - a.bytes);
+  const total = walk(home);
+  return { home, totalBytes: total.bytes, parts, lastPrune: store2.read(join4(home, "prune.json"), null) };
+}
+function prune(store2, now2 = Date.now()) {
+  const s = store2.settings();
+  const home = store2.home;
+  let removed = 0;
+  let freedBytes = 0;
+  const drop = (path2, size, dir = false) => {
+    rmSync(path2, { recursive: dir, force: true });
+    removed++;
+    freedBytes += size;
+  };
+  walk(home, (p, size, mtime) => {
+    if (p.endsWith(".tmp") && now2 - mtime > 36e5) drop(p, size);
+  });
+  const days = s["storage.archiveDays"];
+  if (days > 0) {
+    const cutoff = now2 - days * DAY;
+    const projects = join4(home, "projects");
+    if (existsSync2(projects)) {
+      for (const pid of readdirSync2(projects)) {
+        walk(join4(projects, pid, "archive"), (p, size, mtime) => mtime < cutoff && drop(p, size));
+      }
+    }
+    const forgotten = join4(home, "archive", "projects");
+    if (existsSync2(forgotten)) {
+      for (const name of readdirSync2(forgotten)) {
+        const p = join4(forgotten, name);
+        if (statSync(p).mtimeMs < cutoff) drop(p, walk(p).bytes, true);
+      }
+    }
+  }
+  const cap = Math.max(0, s["storage.cacheMB"]) * 1024 * 1024;
+  const cached = [];
+  const total = walk(join4(home, "cache"), (p, size, mtime) => cached.push({ p, size, mtime })).bytes;
+  let over = total - cap;
+  for (const c of cached.sort((a, b) => a.mtime - b.mtime)) {
+    if (over <= 0) break;
+    drop(c.p, c.size);
+    over -= c.size;
+  }
+  const maxAttempts = Math.max(1, s["storage.maxAttempts"]);
+  for (const p of store2.projects()) {
+    for (const q of store2.list(p.id, "quizzes")) {
+      if (q.attempts.length <= maxAttempts) continue;
+      const best = q.attempts.reduce((b, a) => a.score > b.score ? a : b);
+      const keep = q.attempts.slice(-maxAttempts);
+      if (!keep.includes(best)) keep.splice(0, 1, best);
+      removed += q.attempts.length - keep.length;
+      q.attempts = keep.sort((a, b) => a.at.localeCompare(b.at));
+      store2.put(p.id, "quizzes", q);
+    }
+  }
+  store2.write(join4(home, "prune.json"), { at: new Date(now2).toISOString(), removed, freedBytes });
+  return { removed, freedBytes };
+}
+var ReplyCache = class {
+  constructor(store2) {
+    this.store = store2;
+    this.dir = join4(store2.home, "cache");
+  }
+  dir;
+  key(...parts) {
+    const h = createHash2("sha256");
+    for (const p of parts) h.update(p).update("\0");
+    return h.digest("hex").slice(0, 32);
+  }
+  get(key) {
+    const p = join4(this.dir, `${key}.json`);
+    const hit = this.store.read(p, null);
+    if (!hit) return void 0;
+    const t = /* @__PURE__ */ new Date();
+    utimesSync2(p, t, t);
+    return hit.text;
+  }
+  set(key, text2) {
+    mkdirSync2(this.dir, { recursive: true });
+    this.store.write(join4(this.dir, `${key}.json`), { text: text2, at: (/* @__PURE__ */ new Date()).toISOString() });
+  }
+};
+var SHAPES = [
+  new RegExp(`^projects/[a-z0-9-]+/(archive/)?(${COLLECTIONS.join("|")})/[A-Za-z0-9_.-]+\\.json$`),
+  /^cache\/[a-f0-9]+\.json$/,
+  /^archive\/projects\/[A-Za-z0-9_.-]+$/
+];
+function labelOf(v, fallback) {
+  const o = v ?? {};
+  for (const k of ["title", "question", "text", "front", "term", "name", "file"]) {
+    if (typeof o[k] === "string" && o[k]) return o[k].replace(/\s+/g, " ").slice(0, 100);
+  }
+  return fallback;
+}
+function items(store2) {
+  const out = [];
+  const home = store2.home;
+  const projects = new Map(store2.projects().map((p) => [p.id, p.name]));
+  const addDir = (dir, group, project) => {
+    if (!existsSync2(dir)) return;
+    for (const f of readdirSync2(dir)) {
+      if (!f.endsWith(".json")) continue;
+      const p = join4(dir, f);
+      const st = statSync(p);
+      const rel = p.slice(home.length + 1).split(sep).join("/");
+      out.push({ id: rel, group, project, label: labelOf(store2.read(p, null), f), bytes: st.size, at: st.mtime.toISOString() });
+    }
+  };
+  const root = join4(home, "projects");
+  if (existsSync2(root)) {
+    for (const pid of readdirSync2(root)) {
+      const name = projects.get(pid) ?? pid;
+      for (const c of COLLECTIONS) {
+        addDir(join4(root, pid, c), c, name);
+        addDir(join4(root, pid, "archive", c), `archived ${c}`, name);
+      }
+    }
+  }
+  addDir(join4(home, "cache"), "reply cache");
+  const forgotten = join4(home, "archive", "projects");
+  if (existsSync2(forgotten)) {
+    for (const f of readdirSync2(forgotten)) {
+      const p = join4(forgotten, f);
+      const st = statSync(p);
+      out.push({ id: `archive/projects/${f}`, group: "forgotten projects", label: f, bytes: walk(p).bytes, at: st.mtime.toISOString() });
+    }
+  }
+  return out.sort((a, b) => b.at.localeCompare(a.at));
+}
+function remove(store2, ids) {
+  let removed = 0;
+  let freedBytes = 0;
+  for (const id of ids) {
+    if (id.includes("..") || !SHAPES.some((r) => r.test(id))) continue;
+    const p = join4(store2.home, ...id.split("/"));
+    if (!existsSync2(p)) continue;
+    const st = statSync(p);
+    freedBytes += st.isDirectory() ? walk(p).bytes : st.size;
+    rmSync(p, { recursive: st.isDirectory(), force: true });
+    removed++;
+  }
+  return { removed, freedBytes };
+}
+
+// src/core/workspace.ts
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { createHash as createHash3 } from "node:crypto";
+import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
+import { dirname as dirname2, extname as extname2, join as join6, relative as relative2, resolve as resolve3, sep as sep2, basename as basename2 } from "node:path";
+
+// src/core/graph.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, statSync as statSync2 } from "node:fs";
+import { dirname, extname, join as join5, relative, resolve as resolve2 } from "node:path";
+var JS_EXT = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+var JS_RE = /(?:^|\n)\s*(?:import|export)\s[^'"`;]*?from\s*['"]([^'"]+)['"]|(?:^|[^\w.])(?:require|import)\(\s*['"]([^'"]+)['"]\s*\)|(?:^|\n)\s*import\s*['"]([^'"]+)['"]/g;
+var PY_FROM = /^\s*from\s+(\.*)([\w.]*)\s+import\s+([\w*, ()]+)/gm;
+var PY_IMPORT = /^\s*import\s+([\w.]+(?:\s*,\s*[\w.]+)*)/gm;
+var MAX_FILE = 3e5;
+var MAX_FILES = 6e3;
+function isFile(p) {
+  try {
+    return statSync2(p).isFile();
+  } catch {
+    return false;
+  }
+}
+function readAliases(root, files) {
+  const configs = files.filter((f) => {
+    const rel = f.slice(root.length + 1);
+    return /(^|\/)tsconfig[\w.-]*\.json$/.test(rel) && rel.split("/").length <= 2;
+  });
+  const out = [];
+  for (const cfg of configs) {
+    try {
+      const text2 = readFileSync3(cfg, "utf8").replace(/\/\*[\s\S]*?\*\/|(^|[^:"])\/\/.*$/gm, "$1").replace(/,(\s*[}\]])/g, "$1");
+      const co = JSON.parse(text2).compilerOptions ?? {};
+      const base = resolve2(dirname(cfg), co.baseUrl ?? ".");
+      for (const [k, v] of Object.entries(co.paths ?? {})) {
+        out.push({ prefix: k.replace(/\*$/, ""), targets: v.map((t) => resolve2(base, t.replace(/\*$/, ""))), dir: dirname(cfg) });
+      }
+    } catch {
+    }
+  }
+  return out.sort((a, b) => b.prefix.length - a.prefix.length);
+}
+function resolveJs(from, spec, known, aliases = []) {
+  if (!spec.startsWith(".")) {
+    const matching = aliases.filter((x) => x.prefix && spec.startsWith(x.prefix)).sort((a, b) => Number(from.startsWith(b.dir + "/")) * b.dir.length - Number(from.startsWith(a.dir + "/")) * a.dir.length);
+    for (const a of matching) {
+      for (const t of a.targets) {
+        const hit = resolveJs(from, `./${relativeTo(from, join5(t, spec.slice(a.prefix.length)))}`, known);
+        if (hit) return hit;
+      }
+    }
+    return null;
+  }
+  const base = resolve2(dirname(from), spec);
+  const tries = [base];
+  const ext = extname(base);
+  if (ext === ".js" || ext === ".mjs" || ext === ".jsx") for (const e of [".ts", ".tsx", ".mts"]) tries.push(base.slice(0, -ext.length) + e);
+  for (const e of JS_EXT) tries.push(base + e);
+  for (const e of JS_EXT) tries.push(join5(base, `index${e}`));
+  return tries.find((t) => known.has(t)) ?? null;
+}
+function relativeTo(from, to) {
+  return relative(dirname(from), to) || ".";
+}
+function pyRoots(root, files) {
+  const roots = /* @__PURE__ */ new Set([root]);
+  for (const f of files) {
+    const m = /^(.*?\/src)\//.exec(f);
+    if (m && f.endsWith(".py")) roots.add(m[1]);
+  }
+  return [...roots];
+}
+function resolvePyModule(mod, roots, known) {
+  const rel = mod.split(".").join("/");
+  for (const r of roots) {
+    for (const t of [join5(r, `${rel}.py`), join5(r, rel, "__init__.py")]) if (known.has(t)) return t;
+  }
+  return null;
+}
+function pyImports(from, src, roots, known) {
+  const out = [];
+  for (const m of src.matchAll(PY_FROM)) {
+    const [, dots, mod, names] = m;
+    if (dots) {
+      let dir = dirname(from);
+      for (let i = 1; i < dots.length; i++) dir = dirname(dir);
+      const base = mod ? join5(dir, ...mod.split(".")) : dir;
+      const hit = [`${base}.py`, join5(base, "__init__.py")].find((t) => known.has(t));
+      if (hit) out.push(hit);
+      for (const n of names.replace(/[()]/g, "").split(",").map((x) => x.trim().split(/\s+/)[0]).filter(Boolean)) {
+        const sib = join5(base, `${n}.py`);
+        if (known.has(sib)) out.push(sib);
+      }
+    } else {
+      const hit = resolvePyModule(mod, roots, known);
+      if (hit) out.push(hit);
+      for (const n of names.replace(/[()]/g, "").split(",").map((x) => x.trim().split(/\s+/)[0]).filter(Boolean)) {
+        const sub = resolvePyModule(`${mod}.${n}`, roots, known);
+        if (sub) out.push(sub);
+      }
+    }
+  }
+  for (const m of src.matchAll(PY_IMPORT)) {
+    for (const mod of m[1].split(",").map((x) => x.trim().split(/\s+/)[0])) {
+      const hit = resolvePyModule(mod, roots, known);
+      if (hit) out.push(hit);
+    }
+  }
+  return out;
+}
+function importGraph(root, files) {
+  const list = files.filter((f) => /\.(m?[jt]sx?|cjs|mts|py)$/.test(f)).slice(0, MAX_FILES);
+  const aliases = readAliases(root, files);
+  const known = new Set(list);
+  const roots = pyRoots(root, list);
+  const edges = /* @__PURE__ */ new Map();
+  for (const f of list) {
+    if (!existsSync3(f) || !isFile(f)) continue;
+    let src;
+    try {
+      const buf = readFileSync3(f);
+      if (buf.length > MAX_FILE) continue;
+      src = buf.toString("utf8");
+    } catch {
+      continue;
+    }
+    const to = /* @__PURE__ */ new Set();
+    if (f.endsWith(".py")) {
+      for (const t of pyImports(f, src, roots, known)) if (t !== f) to.add(t);
+    } else {
+      for (const m of src.matchAll(JS_RE)) {
+        const t = resolveJs(f, m[1] ?? m[2] ?? m[3], known, aliases);
+        if (t && t !== f) to.add(t);
+      }
+    }
+    if (to.size) edges.set(f, to);
+  }
+  const fanIn = /* @__PURE__ */ new Map();
+  for (const to of edges.values()) for (const t of to) fanIn.set(t, (fanIn.get(t) ?? 0) + 1);
+  const used = /* @__PURE__ */ new Set();
+  for (const [f, to] of edges) {
+    used.add(f);
+    for (const t of to) used.add(t);
+  }
+  return {
+    nodes: [...used].map((path2) => ({ path: path2, fanIn: fanIn.get(path2) ?? 0, fanOut: edges.get(path2)?.size ?? 0 })),
+    edges: [...edges].flatMap(([from, to]) => [...to].map((t) => ({ from, to: t })))
+  };
+}
+
+// src/core/workspace.ts
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  "node_modules",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".ruff_cache",
+  "dist",
+  "build",
+  "out",
+  "target",
+  ".next",
+  ".turbo",
+  ".cache",
+  "cdk.out",
+  ".idea",
+  ".tox",
+  "coverage"
+]);
+var MAX_FILE_BYTES = 4e5;
+var EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+var REPO_SCAN_DEPTH = 4;
+var MAX_TREE_FILES = 2e4;
+var LANGS = {
+  ".ts": "typescript",
+  ".tsx": "tsx",
+  ".js": "javascript",
+  ".jsx": "jsx",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".py": "python",
+  ".go": "go",
+  ".rs": "rust",
+  ".java": "java",
+  ".kt": "kotlin",
+  ".rb": "ruby",
+  ".php": "php",
+  ".cs": "csharp",
+  ".c": "c",
+  ".h": "c",
+  ".cpp": "cpp",
+  ".hpp": "cpp",
+  ".swift": "swift",
+  ".scala": "scala",
+  ".sh": "bash",
+  ".zsh": "bash",
+  ".bash": "bash",
+  ".sql": "sql",
+  ".json": "json",
+  ".yaml": "yaml",
+  ".yml": "yaml",
+  ".toml": "toml",
+  ".md": "markdown",
+  ".html": "html",
+  ".css": "css",
+  ".scss": "scss",
+  ".vue": "vue",
+  ".svelte": "svelte",
+  ".tf": "hcl",
+  ".hcl": "hcl",
+  ".xml": "xml",
+  ".ini": "ini",
+  ".dockerfile": "docker",
+  ".lua": "lua",
+  ".r": "r",
+  ".dart": "dart",
+  ".ex": "elixir",
+  ".exs": "elixir",
+  ".jinja": "jinja",
+  ".j2": "jinja"
+};
+function langOf(path2) {
+  const name = basename2(path2).toLowerCase();
+  if (name === "dockerfile") return "docker";
+  if (name === "makefile") return "make";
+  return LANGS[extname2(name)] ?? "text";
+}
+function hashText(text2) {
+  return createHash3("sha1").update(text2).digest("hex").slice(0, 12);
+}
+function git(cwd, args) {
+  return execFileSync2("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+}
+function isGitRepo(dir) {
+  try {
+    return git(dir, ["rev-parse", "--is-inside-work-tree"]).trim() === "true";
+  } catch {
+    return false;
+  }
+}
+var Workspace = class {
+  constructor(project) {
+    this.project = project;
+  }
+  get roots() {
+    return [this.project.root, ...this.project.contexts];
+  }
+  /** Throw unless `path` is inside one of the project's folders. Returns the absolute path. */
+  guard(path2) {
+    const abs = resolve3(path2);
+    const ok = this.roots.some((r) => abs === r || abs.startsWith(r.endsWith(sep2) ? r : r + sep2));
+    if (!ok) throw new Error(`outside the project: ${path2}`);
+    return abs;
+  }
+  rel(path2) {
+    const abs = resolve3(path2);
+    for (const r of this.roots) {
+      if (abs.startsWith(r + sep2)) {
+        const inner = relative2(r, abs);
+        return r === this.project.root ? inner : `${basename2(r)}/${inner}`;
+      }
+    }
+    return abs;
+  }
+  /** Inverse of rel(): a path the model wrote back to an absolute one, or undefined if unknown. */
+  absFromRel(rel) {
+    if (!rel) return void 0;
+    const clean = rel.replace(/^\.\//, "");
+    const candidates = [join6(this.project.root, clean)];
+    for (const c of this.project.contexts) {
+      const name = basename2(c);
+      if (clean.startsWith(name + "/")) candidates.push(join6(c, clean.slice(name.length + 1)));
+    }
+    if (clean.startsWith("/")) candidates.unshift(clean);
+    for (const c of candidates) {
+      try {
+        if (statSync3(this.guard(c)).isFile()) return c;
+      } catch {
+      }
+    }
+    return void 0;
+  }
+  // ---- tree ------------------------------------------------------------
+  tree() {
+    return this.roots.filter((r) => existsSync4(r)).map((r) => ({
+      name: r === this.project.root ? this.project.name : basename2(r),
+      path: r,
+      kind: "dir",
+      children: buildTree(r, listFiles(r))
+    }));
+  }
+  /** Every file in the main folder, absolute paths. */
+  files() {
+    const r = this.project.root;
+    return existsSync4(r) ? listFiles(r).map((f) => join6(r, f)) : [];
+  }
+  graph() {
+    return importGraph(this.project.root, this.files());
+  }
+  /**
+   * The file's recent git history with patches, newest first, cut to `maxBytes`.
+   * Throws when the file is not in a git repo.
+   */
+  history(path2, maxBytes) {
+    const abs = this.guard(path2);
+    const dir = dirname2(abs);
+    if (!isGitRepo(dir)) throw new Error("the history lens needs a file inside a git repo");
+    const out = git(dir, ["log", "--follow", "-n", "15", "-p", "--format=--- commit %h, %an, %cr%n%s%n%n%b", "--", abs]);
+    if (!out.trim()) throw new Error("this file has no commits yet");
+    return out.length > maxBytes ? `${out.slice(0, maxBytes)}
+(older history cut)` : out;
+  }
+  // ---- files -----------------------------------------------------------
+  read(path2) {
+    const abs = this.guard(path2);
+    const st = statSync3(abs);
+    if (!st.isFile()) throw new Error("not a file");
+    const buf = readFileSync4(abs);
+    const truncated = buf.length > MAX_FILE_BYTES;
+    const slice = truncated ? buf.subarray(0, MAX_FILE_BYTES) : buf;
+    const text2 = slice.includes(0) ? "(binary file)" : slice.toString("utf8");
+    return { path: abs, rel: this.rel(abs), lang: langOf(abs), text: text2, hash: hashText(text2), truncated };
+  }
+  hash(path2) {
+    try {
+      return this.read(path2).hash;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Files with line numbers, for a prompt. Stops at `maxBytes` and says which files were cut,
+   * so the model knows it did not see everything.
+   */
+  bundle(paths, maxBytes) {
+    const parts = [];
+    let used = 0;
+    const cut = [];
+    for (const p of paths) {
+      let f;
+      try {
+        f = this.read(p);
+      } catch {
+        continue;
+      }
+      const numbered = f.text.split("\n").map((l, i) => `${String(i + 1).padStart(4)}| ${l}`).join("\n");
+      const block = `=== FILE ${f.rel} (${f.lang}) ===
+${numbered}
+`;
+      if (used + block.length > maxBytes) {
+        cut.push(f.rel);
+        continue;
+      }
+      used += block.length;
+      parts.push(block);
+    }
+    if (cut.length) parts.push(`(Not included, too large for one prompt: ${cut.join(", ")})`);
+    return parts.join("\n");
+  }
+  // ---- git -------------------------------------------------------------
+  /**
+   * Git repos in the project: a folder that is itself in a repo counts as one; otherwise
+   * sub-folders are scanned (up to REPO_SCAN_DEPTH levels, not inside a found repo), so a
+   * workspace folder that holds many repos lists each of them.
+   */
+  repos() {
+    const found = [];
+    const scan = (dir, depth) => {
+      let entries;
+      try {
+        entries = readdirSync3(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith(".") || SKIP_DIRS.has(e.name)) continue;
+        const p = join6(dir, e.name);
+        if (existsSync4(join6(p, ".git"))) found.push(p);
+        else if (depth < REPO_SCAN_DEPTH) scan(p, depth + 1);
+      }
+    };
+    for (const r of this.roots) {
+      if (!existsSync4(r)) continue;
+      if (isGitRepo(r)) found.push(r);
+      else scan(r, 1);
+    }
+    return found.map((path2) => {
+      let branch = "";
+      try {
+        branch = git(path2, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+      } catch {
+      }
+      const name = path2 === this.project.root ? this.project.name : this.project.contexts.includes(path2) ? basename2(path2) : this.rel(path2);
+      return { path: path2, name, branch };
+    });
+  }
+  /** The repo folder for a request: the given one (checked), or the project root. */
+  repo(path2) {
+    const dir = path2 ? this.guard(path2) : this.project.root;
+    return isGitRepo(dir) ? dir : null;
+  }
+  refs(repoPath) {
+    const root = this.repo(repoPath);
+    if (!root) return { branches: [], commits: [], current: "" };
+    let current = "";
+    try {
+      current = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    } catch {
+    }
+    let branches = [];
+    let commits = [];
+    try {
+      branches = git(root, ["for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes"]).split("\n").filter(Boolean).filter((b) => !b.endsWith("/HEAD"));
+      commits = git(root, ["log", "-30", "--format=%h%x09%s%x09%cr"]).split("\n").filter(Boolean).map((l) => {
+        const [sha, subject, when] = l.split("	");
+        return { sha, subject, when };
+      });
+    } catch {
+    }
+    return { branches, commits, current };
+  }
+  /**
+   * A ref git can diff. HEAD in a repo with no commits becomes the empty tree, so a new repo
+   * shows all its files as added.
+   */
+  resolveRef(root, ref) {
+    if (!/^[\w./~^@{}-]+$/.test(ref) || ref.startsWith("-")) throw new Error(`bad ref: ${ref}`);
+    try {
+      git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+      return ref;
+    } catch {
+      if (ref === "HEAD") return EMPTY_TREE;
+      throw new Error(`bad ref: ${ref} is not a commit`);
+    }
+  }
+  /**
+   * Changed files between `base` and `head` (empty head = working tree, untracked files included).
+   * `--relative` keeps paths relative to the folder, also when it sits inside a bigger repo.
+   */
+  diff(spec) {
+    const root = this.repo(spec.repo);
+    if (!root) return [];
+    const range = (spec.head ? [spec.base, spec.head] : [spec.base]).map((r) => this.resolveRef(root, r));
+    const files = [];
+    const numstat = git(root, ["diff", "--relative", "--numstat", "-M", ...range, "--"]).split("\n").filter(Boolean);
+    const status = /* @__PURE__ */ new Map();
+    for (const l of git(root, ["diff", "--relative", "--name-status", "-M", ...range, "--"]).split("\n").filter(Boolean)) {
+      const parts = l.split("	");
+      status.set(parts[parts.length - 1], parts[0][0]);
+    }
+    for (const l of numstat) {
+      const [add, del, ...rest] = l.split("	");
+      let path2 = rest.join("	");
+      if (path2.includes(" => ")) path2 = path2.replace(/\{[^}]* => ([^}]*)\}/, "$1").replace(/^.* => /, "");
+      const s = status.get(path2) ?? "M";
+      const patch = git(root, ["diff", "--relative", "-M", ...range, "--", path2]);
+      files.push({
+        path: join6(root, path2),
+        status: s === "A" ? "added" : s === "D" ? "deleted" : s === "R" ? "renamed" : "modified",
+        additions: Number(add) || 0,
+        deletions: Number(del) || 0,
+        patch
+      });
+    }
+    if (!spec.head) {
+      const untracked = git(root, ["ls-files", "--others", "--exclude-standard"]).split("\n").filter(Boolean);
+      for (const rel of untracked.slice(0, 200)) {
+        const abs = join6(root, rel);
+        let text2 = "";
+        try {
+          text2 = this.read(abs).text;
+        } catch {
+          continue;
+        }
+        const lines = text2.split("\n");
+        const patch = `--- /dev/null
++++ b/${rel}
+@@ -0,0 +1,${lines.length} @@
+${lines.map((l) => "+" + l).join("\n")}`;
+        files.push({ path: abs, status: "added", additions: lines.length, deletions: 0, patch });
+      }
+    }
+    return files;
+  }
+};
+function listFiles(root) {
+  if (isGitRepo(root)) {
+    try {
+      const out2 = git(root, ["ls-files", "--cached", "--others", "--exclude-standard"]);
+      return out2.split("\n").filter(Boolean).filter((p) => existsSync4(join6(root, p))).slice(0, MAX_TREE_FILES);
+    } catch {
+    }
+  }
+  const out = [];
+  const walk2 = (dir) => {
+    if (out.length >= MAX_TREE_FILES) return;
+    let entries;
+    try {
+      entries = readdirSync3(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".") && e.name !== ".github") continue;
+      const p = join6(dir, e.name);
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk2(p);
+      } else if (e.isFile()) out.push(relative2(root, p));
+    }
+  };
+  walk2(root);
+  return out;
+}
+function buildTree(root, files) {
+  const top = { name: "", path: root, kind: "dir", children: [] };
+  for (const rel of files) {
+    const parts = rel.split("/");
+    let node = top;
+    parts.forEach((part, i) => {
+      const isFile2 = i === parts.length - 1;
+      node.children ??= [];
+      let child = node.children.find((c) => c.name === part && c.kind === (isFile2 ? "file" : "dir"));
+      if (!child) {
+        child = { name: part, path: join6(node.path, part), kind: isFile2 ? "file" : "dir" };
+        if (!isFile2) child.children = [];
+        node.children.push(child);
+      }
+      node = child;
+    });
+  }
+  const sort = (n) => {
+    n.children?.sort((a, b) => a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === "dir" ? -1 : 1);
+    n.children?.forEach(sort);
+  };
+  sort(top);
+  return top.children ?? [];
+}
+function browse(dir) {
+  const abs = resolve3(dir);
+  const dirs = readdirSync3(abs, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".") && !SKIP_DIRS.has(e.name)).map((e) => e.name).sort((a, b) => a.localeCompare(b));
+  const parent = resolve3(abs, "..");
+  return { path: abs, parent: parent === abs ? null : parent, dirs, isGit: existsSync4(join6(abs, ".git")) };
+}
+
+// src/core/insights.ts
+var DAY2 = 864e5;
+var scheduler = fsrs();
+var RATINGS = { again: R.Again, hard: R.Hard, good: R.Good, easy: R.Easy };
+function toFsrs(s) {
+  return { ...s, due: new Date(s.due), last_review: s.last_review ? new Date(s.last_review) : void 0 };
+}
+function fromFsrs(c) {
+  return {
+    due: c.due.toISOString(),
+    stability: c.stability,
+    difficulty: c.difficulty,
+    elapsed_days: c.elapsed_days,
+    scheduled_days: c.scheduled_days,
+    learning_steps: c.learning_steps,
+    reps: c.reps,
+    lapses: c.lapses,
+    state: c.state,
+    last_review: c.last_review?.toISOString()
+  };
+}
+function newCardState(now2 = /* @__PURE__ */ new Date()) {
+  return fromFsrs(createEmptyCard(now2));
+}
+function previewCard(card, now2 = /* @__PURE__ */ new Date()) {
+  const p = scheduler.repeat(toFsrs(card.fsrs), now2);
+  return {
+    again: p[R.Again].card.due.toISOString(),
+    hard: p[R.Hard].card.due.toISOString(),
+    good: p[R.Good].card.due.toISOString(),
+    easy: p[R.Easy].card.due.toISOString()
+  };
+}
+function rateCard(card, rating, now2 = /* @__PURE__ */ new Date()) {
+  const next = scheduler.next(toFsrs(card.fsrs), now2, RATINGS[rating]);
+  card.fsrs = fromFsrs(next.card);
+  card.reviews = [...card.reviews, { at: now2.toISOString(), rating }].slice(-CARD_REVIEW_CAP);
+  return card;
+}
+function makeCard(projectId, c) {
+  return {
+    id: newId(),
+    projectId,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    kind: c.kind,
+    front: c.front.slice(0, 2e3),
+    back: c.back.slice(0, 4e3),
+    file: c.file,
+    line: c.line,
+    source: c.source,
+    fsrs: newCardState(),
+    reviews: []
+  };
+}
+function dueCards(store2, projectId, now2 = /* @__PURE__ */ new Date()) {
+  return store2.list(projectId, "cards").filter((c) => !c.suspended && Date.parse(c.fsrs.due) <= now2.getTime()).sort((a, b) => a.fsrs.due.localeCompare(b.fsrs.due));
+}
+var norm = (s) => s.toLowerCase().replace(/[^a-z0-9 ]+/g, " ").replace(/\s+/g, " ").trim();
+function recordMisconception(store2, projectId, m) {
+  const text2 = m.text.trim().slice(0, 500);
+  if (text2.length < 8) return null;
+  const all = store2.list(projectId, "misconceptions");
+  const same = all.find((x) => !x.resolvedAt && (x.sourceId === m.sourceId || norm(x.text) === norm(text2)));
+  if (same) {
+    same.seen++;
+    same.text = text2;
+    return store2.put(projectId, "misconceptions", same);
+  }
+  return store2.put(projectId, "misconceptions", {
+    id: newId(),
+    projectId,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    text: text2,
+    file: m.file,
+    line: m.line,
+    from: m.from,
+    sourceId: m.sourceId,
+    seen: 1
+  });
+}
+function resolveMisconception(store2, projectId, pick) {
+  let n = 0;
+  for (const m of store2.list(projectId, "misconceptions")) {
+    if (m.resolvedAt || !pick(m)) continue;
+    m.resolvedAt = (/* @__PURE__ */ new Date()).toISOString();
+    store2.put(projectId, "misconceptions", m);
+    n++;
+  }
+  return n;
+}
+function openMisconceptions(store2, projectId) {
+  return store2.list(projectId, "misconceptions").filter((m) => !m.resolvedAt).sort((a, b) => b.seen - a.seen || b.createdAt.localeCompare(a.createdAt));
+}
+function signals(store2, project, passMark) {
+  const out = [];
+  const pid = project.id;
+  for (const l of store2.list(pid, "lenses")) for (const f of l.files) out.push({ file: f, at: l.createdAt, pass: false, recall: false, kind: "lens" });
+  for (const q of store2.list(pid, "quizzes")) {
+    for (const f of q.files) {
+      if (!q.attempts.length) out.push({ file: f, at: q.createdAt, pass: false, recall: false, kind: "quiz" });
+      for (const a of q.attempts) out.push({ file: f, at: a.at, pass: a.score >= passMark, recall: true, hash: q.fileHashes[f], kind: "quiz", score: a.score });
+    }
+  }
+  for (const p of store2.list(pid, "practice")) {
+    const allRight = !!p.review && p.review.holes.every((h) => h.verdict === "right");
+    out.push({ file: p.file, at: p.review?.at ?? p.createdAt, pass: allRight, recall: !!p.review, hash: hashText(p.original), kind: "practice" });
+  }
+  for (const t of store2.list(pid, "teachbacks")) {
+    if (!t.grade) continue;
+    for (const f of t.files) out.push({ file: f, at: t.createdAt, pass: t.grade.score >= 4, recall: true, hash: t.fileHashes[f], kind: "other" });
+  }
+  for (const w of store2.list(pid, "walks")) {
+    const answered = w.blocks.filter((b) => b.verdict);
+    if (!answered.length) {
+      out.push({ file: w.file, at: w.createdAt, pass: false, recall: false, kind: "other" });
+      continue;
+    }
+    const pts = answered.reduce((s, b) => s + (b.verdict === "right" ? 1 : b.verdict === "partial" ? 0.5 : 0), 0);
+    const done = answered.length === w.blocks.length;
+    out.push({ file: w.file, at: w.createdAt, pass: done && pts / w.blocks.length >= passMark, recall: true, hash: w.fileHash, kind: "other" });
+  }
+  for (const h of store2.list(pid, "hunts")) {
+    if (!h.grade) out.push({ file: h.file, at: h.createdAt, pass: false, recall: false, kind: "other" });
+    else out.push({ file: h.file, at: h.grade.at, pass: h.grade.score >= passMark, recall: true, hash: h.fileHash, kind: "other" });
+  }
+  for (const c of store2.list(pid, "cards")) {
+    const last = c.reviews[c.reviews.length - 1];
+    if (c.file && last) out.push({ file: c.file, at: last.at, pass: false, recall: true, kind: "card" });
+  }
+  return out;
+}
+function progress(store2, project, now2 = Date.now()) {
+  const s = store2.settings();
+  const ws = new Workspace(project);
+  const map = /* @__PURE__ */ new Map();
+  const hashes = /* @__PURE__ */ new Map();
+  const hashOf = (f) => {
+    if (!hashes.has(f)) hashes.set(f, ws.hash(f));
+    return hashes.get(f);
+  };
+  for (const sig of signals(store2, project, s["quiz.passMark"])) {
+    let fp = map.get(sig.file);
+    if (!fp) {
+      fp = { path: sig.file, level: "new", lenses: 0, quizzes: 0, bestScore: null, practices: 0, other: 0, lastRetrieval: null, fresh: false, passed: false };
+      map.set(sig.file, fp);
+    }
+    if (sig.kind === "lens") fp.lenses++;
+    if (sig.kind === "practice") fp.practices++;
+    if (sig.kind === "other") fp.other++;
+    if (sig.kind === "quiz" && sig.score !== void 0) fp.bestScore = Math.max(fp.bestScore ?? 0, sig.score);
+    if (sig.recall && (!fp.lastRetrieval || sig.at > fp.lastRetrieval)) fp.lastRetrieval = sig.at;
+    if (sig.pass) {
+      fp.passed = true;
+      if (sig.hash && sig.hash === hashOf(sig.file)) fp.fresh = true;
+    }
+  }
+  for (const q of store2.list(project.id, "quizzes")) for (const f of q.files) {
+    const fp = map.get(f);
+    if (fp) fp.quizzes++;
+  }
+  const fadeMs = s["progress.fadeDays"] * DAY2;
+  const out = [];
+  for (const { fresh, passed, ...fp } of map.values()) {
+    let level = "seen";
+    if (fresh) level = fadeMs > 0 && fp.lastRetrieval && now2 - Date.parse(fp.lastRetrieval) > fadeMs ? "fading" : "understood";
+    else if (passed) level = "stale";
+    out.push({ ...fp, level });
+  }
+  return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+function pathDone(store2, path2) {
+  const pid = path2.projectId;
+  const since = path2.createdAt;
+  const passMark = store2.settings()["quiz.passMark"];
+  const covers = (have, want) => want.every((f) => have.includes(f));
+  const lenses = store2.list(pid, "lenses").filter((l) => l.createdAt >= since);
+  const quizzes = store2.list(pid, "quizzes").filter((q) => q.createdAt >= since);
+  const walks = store2.list(pid, "walks").filter((w) => w.createdAt >= since);
+  const teach = store2.list(pid, "teachbacks").filter((t) => t.createdAt >= since);
+  return path2.stops.map((st) => {
+    switch (st.activity) {
+      case "lens":
+        return lenses.some((l) => covers(l.files, st.files));
+      case "walk":
+        return walks.some((w) => st.files.includes(w.file) && w.blocks.every((b) => b.verdict));
+      case "quiz":
+        return quizzes.some((q) => covers(q.files, st.files) && q.attempts.some((a) => a.score >= passMark));
+      case "teachback":
+        return teach.some((t) => covers(t.files, st.files) && (t.grade?.score ?? 0) >= 3);
+      default:
+        return false;
+    }
+  });
+}
+function glossary(store2, projectId) {
+  const map = /* @__PURE__ */ new Map();
+  for (const l of store2.list(projectId, "lenses")) {
+    for (const c of l.concepts) {
+      const key = norm(c.term);
+      if (!key) continue;
+      let t = map.get(key);
+      if (!t) map.set(key, t = { term: c.term, explains: [], files: [] });
+      if (!t.explains.some((e) => norm(e.text) === norm(c.explain))) t.explains.push({ text: c.explain, lensId: l.id, lensTitle: l.title });
+      for (const f of l.files) if (!t.files.includes(f)) t.files.push(f);
+    }
+  }
+  return [...map.values()].sort((a, b) => a.term.localeCompare(b.term, void 0, { sensitivity: "base" }));
+}
+var dayKey = (iso) => {
+  const d = new Date(iso);
+  return `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`;
+};
+function streak(store2, projectId, now2 = Date.now()) {
+  const days = /* @__PURE__ */ new Set();
+  const add = (iso) => iso && days.add(dayKey(iso));
+  for (const l of store2.list(projectId, "lenses")) add(l.createdAt);
+  for (const q of store2.list(projectId, "quizzes")) q.attempts.forEach((a) => add(a.at));
+  for (const c of store2.list(projectId, "cards")) c.reviews.forEach((r) => add(r.at));
+  for (const t2 of store2.list(projectId, "teachbacks")) add(t2.createdAt);
+  for (const w of store2.list(projectId, "walks")) add(w.createdAt);
+  for (const h of store2.list(projectId, "hunts")) add(h.grade?.at);
+  for (const p of store2.list(projectId, "practice")) add(p.review?.at);
+  let n = 0;
+  let t = now2;
+  if (!days.has(dayKey(t))) t -= DAY2;
+  while (days.has(dayKey(t))) {
+    n++;
+    t -= DAY2;
+  }
+  return n;
+}
+function today(store2, project, hubs, now2 = /* @__PURE__ */ new Date()) {
+  const cards = store2.list(project.id, "cards").filter((c) => !c.suspended);
+  const due = cards.filter((c) => Date.parse(c.fsrs.due) <= now2.getTime());
+  const weak = openMisconceptions(store2, project.id).slice(0, 5);
+  const prog = progress(store2, project, now2.getTime());
+  const attention = prog.filter((p) => p.level === "stale" || p.level === "fading").sort((a, b) => (a.lastRetrieval ?? "").localeCompare(b.lastRetrieval ?? "")).slice(0, 6);
+  let nextStop = null;
+  const path2 = store2.list(project.id, "paths")[0];
+  if (path2) {
+    const done = pathDone(store2, path2);
+    const i = done.findIndex((d) => !d);
+    if (i >= 0) nextStop = { pathId: path2.id, title: path2.title, index: i, stop: path2.stops[i] };
+  }
+  let suggestion = null;
+  if (due.length) suggestion = { text: `Review ${due.length} card${due.length === 1 ? "" : "s"} (about ${Math.max(1, Math.round(due.length / 3))} min).`, files: [], activity: "review" };
+  else if (weak.length) suggestion = { text: "Quiz your weak spots: questions aimed at what you got wrong before.", files: [], activity: "weak" };
+  else if (attention.length) suggestion = { text: `${attention[0].level === "stale" ? "The code changed since you passed" : "It has been a while since you recalled"} ${new Workspace(project).rel(attention[0].path)}. Quiz it again.`, files: [attention[0].path], activity: "quiz" };
+  else if (nextStop) suggestion = { text: `Next stop on "${nextStop.title}": ${nextStop.stop.title}.`, files: nextStop.stop.files, activity: nextStop.stop.activity };
+  else if (!prog.length) {
+    const start = hubs()[0];
+    if (start) suggestion = { text: `Start with the file most of the code depends on: ${new Workspace(project).rel(start)}. Read a lens, then quiz it.`, files: [start], activity: "lens" };
+  }
+  return {
+    due: due.length,
+    newCards: cards.filter((c) => c.fsrs.reps === 0).length,
+    weak,
+    attention,
+    nextStop,
+    streak: streak(store2, project.id, now2.getTime()),
+    suggestion
+  };
+}
+
+// src/core/jobs.ts
+import { join as join7 } from "node:path";
+var JOB_CAP = 100;
+var Jobs = class {
+  constructor(store2) {
+    this.store = store2;
+    if (!store2) return;
+    this.file = join7(store2.home, "jobs.json");
+    for (const j of store2.read(this.file, [])) {
+      if (j.status === "running") Object.assign(j, { status: "failed", error: "learnforge stopped while this ran", endedAt: j.startedAt });
+      this.jobs.set(j.id, j);
+    }
+  }
+  jobs = /* @__PURE__ */ new Map();
+  file;
+  save() {
+    while (this.jobs.size > JOB_CAP) {
+      const oldest = [...this.jobs.values()].find((j) => j.status !== "running");
+      if (!oldest) break;
+      this.jobs.delete(oldest.id);
+    }
+    if (this.store && this.file) this.store.write(this.file, [...this.jobs.values()]);
+  }
+  start(kind, projectId, work) {
+    const job = { id: newId(), kind, projectId, status: "running", startedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    this.jobs.set(job.id, job);
+    this.save();
+    work().then((r) => Object.assign(job, { status: "done", resultId: r.id })).catch((e) => Object.assign(job, { status: "failed", error: e instanceof Error ? e.message : String(e) })).finally(() => {
+      job.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.save();
+    });
+    return job;
+  }
+  get(id) {
+    return this.jobs.get(id);
+  }
+  running(projectId) {
+    return [...this.jobs.values()].filter((j) => j.projectId === projectId && j.status === "running");
+  }
+  /** Newest first. */
+  history(limit = 50) {
+    return [...this.jobs.values()].reverse().slice(0, limit);
+  }
+};
+
+// src/core/prompts.ts
+var LENS_KINDS = [
+  {
+    id: "explain",
+    label: "Explain",
+    question: "What does this code do, and what do I need to know to read it?",
+    blurb: "The tour: purpose, main pieces, how they connect."
+  },
+  {
+    id: "flow",
+    label: "Data flow",
+    question: "How does data move through this code, from input to output?",
+    blurb: "Follow one value from where it enters to where it leaves."
+  },
+  {
+    id: "state",
+    label: "State over time",
+    question: "What state does this code keep, and how does it change step by step?",
+    blurb: "What is stored, who changes it, in which order."
+  },
+  {
+    id: "failure",
+    label: "Failure modes",
+    question: "How can this code fail, and what happens when it does?",
+    blurb: "Bad input, timeouts, partial writes, retries."
+  },
+  {
+    id: "contracts",
+    label: "Contracts",
+    question: "What does this code promise its callers, and what does it expect from what it calls?",
+    blurb: "Inputs, outputs, invariants, the edges between parts."
+  },
+  {
+    id: "concepts",
+    label: "Concepts",
+    question: "Which ideas, APIs or patterns must I know to understand this code?",
+    blurb: "The vocabulary first, with the line where each one shows up."
+  },
+  {
+    id: "change",
+    label: "The change",
+    question: "What changed, why might it have changed, and what could it break?",
+    blurb: "Best with a diff: intent, risk, what to check."
+  },
+  {
+    id: "trace",
+    label: "Trace a run",
+    question: "Step through this code on a small input: which line runs, and what does each variable hold?",
+    blurb: "A debugger without running: line by line, with the state."
+  },
+  {
+    id: "history",
+    label: "History",
+    question: "Why is this code the way it is? Explain it through its git history.",
+    blurb: "What changed over time and why, from the commits."
+  }
+];
+var STYLE = `Write for a capable engineer who is new to this code. Plain, short sentences. Name real
+files and line numbers from the input (the numbers before "|"). Never invent code that is not in the input.
+Return ONLY one JSON object inside a single \`\`\`json fence. No text outside the fence.`;
+var DEPTH = {
+  overview: {
+    steps: "3-4",
+    words: 60,
+    concepts: "2-4",
+    gotchas: "0-3",
+    note: "The reader wants the big picture in 3 minutes. Skip details that do not change the mental model."
+  },
+  standard: {
+    steps: "5-8",
+    words: 120,
+    concepts: "3-6",
+    gotchas: "2-5",
+    note: "The reader wants to be able to change this code safely after reading. Give one concrete example with real values in the steps that carry logic."
+  },
+  deep: {
+    steps: "9-14",
+    words: 260,
+    concepts: "5-9",
+    gotchas: "5-8",
+    note: `The reader will own this code and debug it at 2am. This is a long, thorough lesson, not a summary:
+- Every step is 2-4 paragraphs: (1) what it does and why it exists, (2) a worked example with concrete values
+  from a small input ("if \`rows\` is [3, 0], then ..."), (3) the edge cases, ordering rules or failure path that
+  touch this part, (4) why it was built this way instead of the obvious way, and what a change would break.
+- Cover EVERY branch, early return, try/except, fallback and default in the files, not only the happy path. If the
+  code has an "if this fails, do that" path, it gets its own step.
+- Every step has a "pitfall" (a real mistake or a change that would break it) and a "check" question that needs
+  reasoning, not recall ("what happens if X is empty?"), never "what does line 12 do?".
+- "intuition" has BOTH a worked example with toy data walked through as numbered steps AND a mermaid diagram.
+- "gotchas" lists real traps (ordering, mutation, silent fallbacks, error swallowing). "nextSteps" is required
+  (2-3 real files that callers, types or tests live in) so the reader knows where to go after this.
+- Prefer more steps over longer steps when an idea has two halves. Do not pad: every sentence must teach.`
+  }
+};
+function lensSystem0(depth = "standard") {
+  const d = DEPTH[depth];
+  return `TASK: lens
+You build a "lens": a lesson that teaches code through ONE question, like a senior engineer walking a new
+teammate through it at a whiteboard. ${d.note}
+
+How to teach (this matters more than coverage):
+- Lead with the mental model. "tldr" is the one idea that makes the rest make sense, in one sentence a newcomer
+  can repeat. Answer the question directly; no hedging, no "this file is not X".
+- Explain WHY, not WHAT. The reader can read the code; tell them what it is for, what would break without it,
+  and why it is done this way rather than the obvious way. Never paraphrase a line ("line 12 sets x to y").
+- Concrete over abstract: real values, a small example input, "if you change A, B happens".
+- Define every term at first use, in plain words. Short sentences. No filler ("This is important because...").
+- Write like a good engineering blog post: second person ("you"), short paragraphs of 2-3 sentences with a
+  blank line between them, a bullet list when there are 3+ parallel items. Never one long block of text.
+- Every field is markdown. Put identifiers, file names, functions, fields and values in \`backticks\`.
+  Use **bold** at most once per field, for the one phrase that matters.
+- One idea per step. The step title is that idea as a CLAIM the reader learns ("Layer 1 only sees manifests, so
+  code edits never bust it"), not a label ("Layer 1").
+- Steps go in the order that builds understanding (entry point and data shapes first), not file order. Each
+  step's "explain" connects to the step before.
+- Each step points at a SHORT line range (3-25 lines) that shows the idea; the page shows those lines next to
+  your text, so do not repeat the code.
+- If you have file tools, you may open other files in the repo (callers, the types it uses, its tests) to explain
+  how this code is used. Cite them with real paths. If you cannot see something, leave it out instead of
+  guessing or saying you did not look.
+Name real files and line numbers from the input (the numbers before "|"). Never invent code.
+Return ONLY one JSON object inside a single \`\`\`json fence. No text outside the fence.
+
+JSON shape:
+{
+  "title": "short title, max 8 words",
+  "tldr": "ONE sentence: the mental model that answers the question",
+  "whyItMatters": "1-2 sentences: what goes wrong for someone who does not know this",
+  "summary": "markdown, at most 3 short sentences: the answer in plain words, expanding the tldr. If there is more to say, it belongs in the steps",
+  "concepts": [{"term": "name", "explain": "1-2 plain sentences", "example": "a tiny concrete example or analogy", "file": "relative/path", "line": 12}],  // ${d.concepts} items, only terms the reader needs first
+  "intuition": "markdown: the core idea with toy data walked through as numbered steps, and/or a small mermaid diagram (\`\`\`mermaid fenced, max 12 nodes, flowchart or sequenceDiagram, short sentence-case labels, never ALL CAPS; prefer flowchart TD when it has more than 5 nodes)",
+  "deepDives": [{
+    "title": "the idea of this step as a claim",
+    "file": "relative/path", "startLine": 10, "endLine": 24, "line": 12,   // line = the single key line
+    "body": "markdown, up to ${d.words} words, in short paragraphs: why this part exists and how it works; connect to the previous step",
+    "pitfall": "optional: a mistake people make here, or what breaks if you change it",
+    "check": {"q": "a short question the reader should now be able to answer", "a": "the answer, 1-2 sentences"}
+  }],  // ${d.steps} items, in teaching order
+  "gotchas": ["surprising behaviour, edge cases or traps, 1 sentence each, with the line"],   // ${d.gotchas} items
+  "nextSteps": [{"file": "relative/path", "why": "what reading it next will teach"}]       // 1-3 items, files that exist
+}`;
+}
+var SCREENS = {
+  overview: { size: "about 1.5 screens", steps: "3-4", paras: "1-2 short paragraphs", concepts: "2-4", gotchas: "1-3" },
+  standard: { size: "at least 3 screens", steps: "6-9", paras: "2-3 paragraphs", concepts: "4-6", gotchas: "3-5" },
+  deep: { size: "5 to 6 screens, a long blog post", steps: "11-15", paras: "3-5 paragraphs", concepts: "5-9", gotchas: "5-8" }
+};
+var TEACH = `How to teach (this matters more than coverage):
+- Lead with the mental model. Answer the question directly; no hedging.
+- Explain WHY, not WHAT. The reader can read the code; tell them what it is for, what would break without it,
+  and why it is done this way rather than the obvious way. Never paraphrase a line ("line 12 sets x to y").
+- Concrete over abstract: real values, a small example input, "if you change A, B happens".
+- Define every term at first use, in plain words. Short sentences. No filler.
+- Write like a good engineering blog post: second person ("you"), short paragraphs of 2-3 sentences with a blank
+  line between them, a bullet list when there are 3+ parallel items. Never one long block of text.
+- Every field is markdown. Put identifiers, file names, functions, fields and values in \`backticks\`.
+  Use **bold** at most once per field.
+- Name real files and line numbers from the input (the numbers before "|"). Never invent code.`;
+function lensPlanSystem(x = {}) {
+  const d = SCREENS[x.depth ?? "standard"];
+  return `TASK: lensPlan
+You are the PLANNER of a "lens": a lesson that teaches code through ONE question. A second writer model will
+write the prose from your plan, so the plan decides how good the lesson is. You do not write the prose.
+Read all the code first. If you have file tools, open callers, the types it uses and its tests so the plan
+covers how this code is really used.
+
+Target size of the finished page: ${d.size}. Choose the number of steps for that size (${d.steps} steps).
+Do not cut short: for a longer page, cover every branch, early return, fallback, error path and default, not only
+the happy path, and give each its own step. Teach in the order that builds understanding (entry point and data
+shapes first), not file order. Each step is ONE idea, titled as a CLAIM the reader learns ("Layer 1 only sees
+manifests, so code edits never bust it"), not a label.
+
+${TEACH}
+${STYLE}
+
+JSON shape:
+{
+  "title": "short title, max 8 words",
+  "tldr": "ONE sentence: the mental model that answers the question",
+  "whyItMatters": "1-2 sentences: what goes wrong for someone who does not know this",
+  "reader": "who this is for and what they can do after reading, 1 sentence",
+  "concepts": [{"term": "name", "note": "what to explain and the line it shows up at", "file": "relative/path", "line": 12}],  // ${d.concepts} terms the reader needs first
+  "intuition": {"example": "a toy input with real values to walk through, and the numbered stages it goes through", "diagram": "what a mermaid diagram should show (flowchart TD or sequenceDiagram, max 12 nodes), or empty"},
+  "steps": [{
+    "title": "the idea as a claim",
+    "file": "relative/path", "startLine": 10, "endLine": 24, "line": 12,   // a SHORT range (3-25 lines) that shows the idea
+    "covers": ["each concrete fact, branch or rule this step must explain, in order"],
+    "example": "concrete values to use in this step, or empty",
+    "edge": "the edge case, ordering rule or failure path that touches this part, or empty",
+    "why": "why it is built this way and what a change would break",
+    "pitfall": "a real mistake or breaking change to warn about, or empty",
+    "check": "an idea for a question that needs reasoning, not recall"
+  }],
+  "gotchas": ["a trap, 1 sentence, with the line"],   // ${d.gotchas}
+  "nextSteps": [{"file": "relative/path", "why": "what reading it next will teach"}]   // 2-3 real files
+}`;
+}
+function lensIntroSystem(x = {}) {
+  const d = SCREENS[x.depth ?? "standard"];
+  const extra = [
+    x.sketch ? `  "differences": ["where the learner's take (SKETCH) is wrong, missing something, or right for the wrong reason; 1-2 sentences each, name the line"],  // 1-6 items` : "",
+    x.trace ? `  "trace": {"input": "the toy input used, one line", "steps": [{"file": "relative/path", "line": 12, "state": {"var": "value as short text"}, "note": "what happens, 1 sentence"}]},  // 5-40 steps in run order` : ""
+  ].filter(Boolean).join("\n");
+  return `TASK: lensIntro
+You are the WRITER of the opening of a lens (a lesson on code). A planner already decided what the lesson says;
+follow its PLAN and write the opening parts well. The steps are written separately, so do not write them.
+The whole page will be ${d.size}; the opening sets it up, it does not try to say everything.
+
+${TEACH}
+${STYLE}
+
+JSON shape:
+{
+${extra ? extra + "\n" : ""}  "summary": "markdown, at most 3 short sentences: the answer in plain words, expanding the tldr",
+  "concepts": [{"term": "name", "explain": "1-2 plain sentences", "example": "a tiny concrete example or analogy", "file": "relative/path", "line": 12}],  // the planner's terms, ${d.concepts} items
+  "intuition": "markdown: the core idea walked through with the planner's toy input as numbered stages${x.depth === "overview" ? "" : ", AND a mermaid diagram (```mermaid fenced, max 12 nodes, short sentence-case labels, flowchart TD when more than 5 nodes)"}",
+  "gotchas": ["surprising behaviour or trap, 1 sentence each, with the line"],   // ${d.gotchas} items, from the plan
+  "nextSteps": [{"file": "relative/path", "why": "what reading it next will teach"}]   // the planner's files that exist
+}`;
+}
+function lensStepsSystem(x = {}) {
+  const d = SCREENS[x.depth ?? "standard"];
+  return `TASK: lensSteps
+You are the WRITER of some steps of a lens (a lesson on code). A planner outlined every step; you write only the
+steps you are asked for, in full, following the plan for each one: its "covers" list, "example", "edge" and "why".
+Write each step's "body" as ${d.paras}. Take the space the idea needs; do not compress, and do not pad.
+Use the example's real values, walk the edge case, and say why it is built this way. Connect each step to the one
+before it (the earlier titles are given). The page shows the cited code lines next to your text, so do not repeat
+the code; explain it.
+"pitfall": one real mistake or breaking change, 1-3 sentences (omit if the plan has none).
+"check": a short question that needs reasoning (what happens if X is empty? what breaks first if Y?), and "a", the
+answer in 1-2 sentences.
+
+${TEACH}
+${STYLE}
+
+JSON shape:
+{ "steps": [{"index": 3, "body": "markdown", "pitfall": "...", "check": {"q": "...", "a": "..."}}] }   // one item per requested step, same "index" as in the plan (0-based)`;
+}
+function lensWritePrompt(question, plan, files, x = {}) {
+  const e = x.extras;
+  return `QUESTION: ${question}
+
+${e?.sketch ? `SKETCH (the learner's own take, written before the lesson):
+${e.sketch}
+
+` : ""}${e?.traceInput !== void 0 ? `TRACE INPUT: ${e.traceInput || "(pick a small, typical input that exercises the main path)"}
+
+` : ""}PLAN (from the planner; follow it):
+${JSON.stringify(plan, null, 1)}
+
+${x.steps ? `WRITE STEPS ${x.steps[0]}-${x.steps[1]} (0-based, both included).${x.titles?.length ? `
+Earlier steps, for continuity:
+${x.titles.map((t) => `- ${t}`).join("\n")}` : ""}
+
+` : ""}CODE:
+${files}`;
+}
+function planSystem(writerSystem) {
+  const task = writerSystem.split("JSON shape:")[0].trim();
+  return `TASK: plan
+You are the PLANNER. A second model will do the task below and follows your outline, so make it specific.
+Read the code (open related files if you can). Decide what the output must cover and in what order, which files
+and line ranges matter, the common traps to include, and what to leave out. Do not write the final output.
+
+THE TASK THE WRITER WILL DO:
+${task}
+
+${STYLE}
+
+JSON shape:
+{ "outline": "markdown, 6-20 lines: the plan, with real files and line numbers" }`;
+}
+function lensSystem(x = {}) {
+  const extra = [
+    x.sketch ? `  "differences": ["where the learner's take (SKETCH) is wrong, missing something, or right for the wrong reason; 1-2 sentences each, name the line"],  // 1-6 items; if the sketch is fully right say so in one item` : "",
+    x.trace ? `  "trace": {"input": "the toy input used, one line", "steps": [{"file": "relative/path", "line": 12, "state": {"var": "value as short text"}, "note": "what happens, 1 sentence"}]}  // 5-40 steps in run order; state lists only variables in scope that matter` : ""
+  ].filter(Boolean);
+  const base = lensSystem0(x.depth);
+  if (!extra.length) return base;
+  const end = `"why": "what reading it next will teach"}]`;
+  return base.replace(end, `${end},`).replace(/\n}$/, `
+${extra.join(",\n")}
+}`);
+}
+function lensPrompt(question, files, x = {}) {
+  return `QUESTION: ${question}
+
+${x.sketch ? `SKETCH (the learner's own take, written before reading your lesson):
+${x.sketch}
+
+` : ""}${x.traceInput !== void 0 ? `TRACE INPUT: ${x.traceInput || "(pick a small, typical input that exercises the main path)"}
+
+` : ""}${x.previous ? `AN EARLIER LESSON ON THIS CODE SAID (the code has changed since; say what is different now):
+${x.previous}
+
+` : ""}${x.history ? `GIT HISTORY (newest first):
+${x.history}
+
+` : ""}${x.diff ? `THE CHANGE (unified diff):
+${x.diff}
+
+` : ""}${x.notes ? `THE LEARNER'S NOTES:
+${x.notes}
+
+` : ""}CODE:
+${files}`;
+}
+function quizSystem(n) {
+  return `TASK: quiz
+You write a short quiz that checks real understanding of the given code, not recall of names.
+Ask about behaviour, reasons, edge cases and consequences ("what happens when...", "why does... ",
+"which line breaks first if..."). Each question must be answerable from the code shown, in 1-4 sentences.
+Do not put the answer in the question. Mix easy and hard.
+${STYLE}
+
+JSON shape:
+{
+  "title": "short title",
+  "questions": [{"prompt": "the question", "file": "relative/path", "line": 12, "focus": "what it tests, 3-6 words", "targets": "weak spot id, only if WEAK SPOTS are given"}]  // exactly ${n} items
+}`;
+}
+function quizPrompt(files, diff, lensSummary, weak) {
+  const w = weak?.length ? `WEAK SPOTS: this learner got these wrong before. Write questions that probe exactly these gaps, in new words
+and from a new angle (not the old question). Put the weak spot's id in "targets".
+${weak.map((m) => `[${m.id}] ${m.text}`).join("\n")}
+
+` : "";
+  return `${w}${lensSummary ? `The learner just read this lesson summary:
+${lensSummary}
+
+` : ""}${diff ? `THE CHANGE (unified diff):
+${diff}
+
+` : ""}CODE:
+${files}`;
+}
+function gradeSystem() {
+  return `TASK: grade
+You grade a learner's free-text answers about code. Be fair and lenient on wording: if the core idea is right,
+it is "right"; if part is right, "partial"; a wrong conclusion is "wrong". Feedback: 1-3 sentences, name the
+line that settles it. modelAnswer: the best short answer, 1-3 sentences.
+misconception (only for partial or wrong): what the learner seems to BELIEVE that is not true, as one line in
+the second person ("You think X, but Y"). Not the fact they missed; the wrong model in their head. Omit if the
+answer is empty or just "I don't know".
+${STYLE}
+
+JSON shape:
+{ "grades": [{"qid": "q1", "verdict": "right|partial|wrong", "feedback": "...", "modelAnswer": "...", "misconception": "..."}] }`;
+}
+function gradePrompt(items2, files) {
+  const qa = items2.map((i) => `[${i.qid}] Q: ${i.question}
+A: ${i.answer || "(no answer)"}`).join("\n\n");
+  return `ANSWERS TO GRADE:
+${qa}
+
+CODE:
+${files}`;
+}
+var LEVELS = {
+  1: "1 hole: one short, central expression or condition (1-3 lines).",
+  2: "2 holes: a key condition and a key computation (2-6 lines each).",
+  3: "3 holes: the core logic of the main function(s) (3-12 lines each).",
+  4: "3-4 holes: whole function bodies of the most important logic."
+};
+function practiceSystem(level, hasConcept = false, multi = false) {
+  return `TASK: practice
+You turn real code into a practice exercise that trains ONE concept. ${hasConcept ? "The learner named the concept; cut the lines where the code applies it." : "Name the one concept the code is built around (the idea worth learning), then cut the lines where the code applies it."}
+${multi ? "The concept usually shows up in several files (definition, use, wiring, test). Spread the holes over the files where it matters, and say in each intent how this hole fits the whole." : ""}
+The holes are lines the learner must write back. Total size: ${LEVELS[level]}
+Rules: holes must not overlap; each hole is a range of whole lines (1-based, inclusive) from the numbers before "|"
+in ONE code file; set "file" to the path in that file's "=== FILE" header. CONTEXT FILES are read only.
+Good holes: a branch with a decision, a loop that builds or filters something, a transformation, error handling
+that changes the result, a guard that protects an invariant. Bad holes: imports, type declarations, constants and
+tables, logging, plain getters, glue, comments, closing brackets.
+Each hole must be solvable from the code around it: the learner sees the signature, the neighbouring lines and
+the names, but not the cut lines. Do not cut a line whose meaning cannot be guessed from the rest.
+intent: what the hole must do (inputs, outputs, edge cases) and what part of the concept it tests, without giving
+the code; 2-4 sentences. hints: 2-3, from gentle (where to look) to nearly the answer.
+concept: one sentence naming what this practice trains.
+${STYLE}
+
+JSON shape:
+{ "concept": "...", "holes": [{"file": "src/a.ts", "startLine": 10, "endLine": 14, "intent": "...", "hints": ["...", "..."]}] }`;
+}
+function reviewSystem() {
+  return `TASK: review
+You check a learner's attempt to fill holes in code. Compare each hole with the original. Judge behaviour,
+not style: a different but correct solution is "right"; pseudo-code that has the right logic is "partial" or
+"right". Feedback: 1-3 sentences per hole, say what differs and what it would break.
+${STYLE}
+
+JSON shape:
+{ "summary": "1-2 sentences", "holes": [{"id": 1, "verdict": "right|partial|wrong", "feedback": "..."}] }`;
+}
+function reviewPrompt(files) {
+  const list = files.flatMap((f) => f.holes.map((h) => `hole ${h.id}: file ${f.rel}, original lines ${h.startLine}-${h.endLine}; must: ${h.intent}`)).join("\n");
+  const texts = files.map((f) => `=== ${f.rel} ===
+ORIGINAL:
+${f.original}
+
+LEARNER'S VERSION (holes filled in):
+${f.attempt}`).join("\n\n");
+  return `HOLES:
+${list}
+
+${texts}`;
+}
+function teachbackSystem() {
+  return `TASK: teachback
+The learner explains the given code in their own words, as if teaching a new teammate. Grade the explanation
+against the code. Be fair on wording; judge the mental model.
+right: claims that are correct and important. missing: important things a good explanation would have said.
+wrong: claims that are false, each as "You say X, but Y (line N)". score: 1-5 (1 = mostly wrong or empty,
+3 = right but shallow, 4 = right and covers the important parts, 5 = also the why and the edge cases).
+${STYLE}
+
+JSON shape:
+{ "score": 4, "summary": "1-2 sentences", "right": ["..."], "missing": ["..."], "wrong": ["..."] }`;
+}
+function teachbackPrompt(text2, files) {
+  return `THE LEARNER'S EXPLANATION:
+${text2}
+
+CODE:
+${files}`;
+}
+function tutorSystem(level, tell) {
+  const how = tell ? "The learner asked you to tell them. Give the full answer now, clearly, with the lines that show it. Then ask one short question that checks they got it." : level <= 1 ? "Do NOT give the answer. Reply with ONE guiding question or a pointer to where to look (a line or a name), so the learner can find it." : level === 2 ? "Do NOT give the full answer yet. Give a concrete hint: name the mechanism or the line that matters and what to notice there. End with a question." : "The learner has tried twice. Walk through the answer step by step, but leave the last step for them, as a question.";
+  return `TASK: tutor
+You are a Socratic tutor for code. The learner is trying to understand the code below. Never lecture.
+Keep replies short (2-6 sentences). Use the learner's own words back to them when they are close.
+If the learner states something wrong, do not just correct it: ask a question that makes them test it against the code.
+This turn: ${how}
+Name real files and line numbers from the input. Never invent code.
+Return ONLY one JSON object inside a single \`\`\`json fence.
+
+JSON shape:
+{ "reply": "markdown" }`;
+}
+function tutorPrompt(history, files, notes) {
+  const h = history.map((m) => `${m.role === "user" ? "LEARNER" : "TUTOR"}: ${m.text}`).join("\n\n");
+  return `CONVERSATION SO FAR:
+${h}
+
+${notes ? `THE LEARNER'S NOTES:
+${notes}
+
+` : ""}CODE:
+${files}`;
+}
+function walkSystem() {
+  return `TASK: walk
+Split the file into 4-10 blocks for a guided walkthrough, in READING order (the order that makes it easiest to
+understand: entry point and data shapes first, helpers when they are first needed), not file order.
+Each block is a range of whole lines (1-based, inclusive, from the numbers before "|"). Blocks may skip
+boilerplate (imports, logging). why: why this block matters and how it connects to the previous one (1-2 sentences).
+question: one check question about the block's behaviour or reason, answerable from the block in 1-2 sentences.
+Do not put the answer in the question.
+${STYLE}
+
+JSON shape:
+{ "blocks": [{"startLine": 10, "endLine": 30, "title": "short", "why": "...", "question": "..."}] }`;
+}
+function walkPlanSystem() {
+  return `TASK: walkPlan
+You are the PLANNER of a guided walkthrough of one file. A second writer model writes each block from your plan.
+Read the whole file (and, if you have file tools, its callers and tests) and split it into 5-12 blocks in READING
+order: entry point and data shapes first, helpers when they are first needed, not file order. A block is a range
+of whole lines (1-based, inclusive, from the numbers before "|"), usually 5-30 lines, that holds ONE idea. Skip
+boilerplate (imports, logging) unless it matters. Cover every branch, fallback and error path that matters.
+For each block decide what the writer must teach and which concrete example will make it click: a call with real
+values ("push(3) on an empty queue"), a small usage snippet, or a before/after. Plan a question that asks the
+learner to PREDICT or REASON about a concrete case ("what does it return for ...? why?"), never one that asks
+them to paraphrase the code.
+${STYLE}
+
+JSON shape:
+{ "blocks": [{
+  "startLine": 10, "endLine": 30, "title": "the idea as a short claim",
+  "covers": ["each fact, branch or rule the block must explain, in order"],
+  "example": "the concrete input and the result to walk through, or a small usage snippet to show",
+  "question": "the question idea, about a concrete case"
+}] }`;
+}
+function walkBlocksSystem() {
+  return `TASK: walkBlocks
+You are the WRITER of some blocks of a guided code walkthrough. A planner outlined every block; write only the
+blocks you are asked for, following the plan for each one. The page shows the block's own code above your text, so
+do not repeat the code; explain it.
+For each block write:
+- "why": 1-2 sentences: why this block matters and how it connects to the previous one.
+- "explain": markdown, 2-4 short paragraphs for a capable engineer who is new to this code: what it does, why it
+  exists, why it is done this way, and what to notice. Identifiers in \`backticks\`. Second person.
+- "example": markdown. A worked example with real values: the call or input, what happens step by step through the
+  block, and the result. Include at least one fenced code block (a small usage snippet, a tiny table of values, or
+  before/after). The snippet may be illustrative calling code, but it must match the real names and signatures.
+- "question": one check question about a concrete case the learner must predict or reason about, answerable in 1-3
+  sentences from the block and your text. Do not put the answer in the question.
+${STYLE}
+
+JSON shape:
+{ "blocks": [{"index": 0, "why": "...", "explain": "...", "example": "...", "question": "..."}] }   // one item per requested block, same "index" as in the plan (0-based)`;
+}
+function walkWritePrompt(plan, range, titles, files) {
+  return `PLAN (from the planner; follow it):
+${JSON.stringify(plan, null, 1)}
+
+WRITE BLOCKS ${range[0]}-${range[1]} (0-based, both included).${titles.length ? `
+Earlier blocks, for continuity:
+${titles.map((t) => `- ${t}`).join("\n")}` : ""}
+
+CODE:
+${files}`;
+}
+function walkcheckSystem() {
+  return `TASK: walkcheck
+Grade one answer to a check question about a block of code. Lenient on wording: core idea right = "right".
+feedback: 1-2 sentences; if not right, say what the block really does and name the line.
+misconception (only for partial or wrong): what the learner seems to believe that is not true, one line, "You think X, but Y".
+${STYLE}
+
+JSON shape:
+{ "verdict": "right|partial|wrong", "feedback": "...", "misconception": "..." }`;
+}
+function walkcheckPrompt(question, answer, block, file) {
+  return `QUESTION: ${question}
+ANSWER: ${answer || "(no answer)"}
+
+THE BLOCK:
+${block}
+
+WHOLE FILE FOR CONTEXT:
+${file}`;
+}
+var HUNT_LEVELS = {
+  1: "1 bug, fairly visible to a careful reader (wrong comparison, off-by-one, wrong variable).",
+  2: "2 bugs: one visible, one that needs understanding of the logic (wrong default, swapped arguments, missing await, wrong boolean).",
+  3: "2-3 subtle bugs that only show with real understanding (edge case, ordering, state not reset, wrong branch taken)."
+};
+function huntSystem(level) {
+  return `TASK: hunt
+Plant realistic bugs in the code for a debugging exercise. ${HUNT_LEVELS[level]}
+Each bug changes exactly ONE line. "original" must be that line copied exactly from the input (without the
+number and "|"). "buggy" is the full replacement line, same indent, still valid syntax, plausible as a real
+mistake (no comments that give it away, no weird names). Pick lines in the core logic, not imports or logging.
+"what": what the bug breaks, 1-2 sentences, for after the learner answers.
+${STYLE}
+
+JSON shape:
+{ "bugs": [{"line": 12, "original": "exact line", "buggy": "changed line", "what": "..."}] }`;
+}
+function huntgradeSystem() {
+  return `TASK: huntgrade
+A learner hunted for planted bugs. You get the planted bugs and the learner's marks (line + why).
+For each FOUND bug (the learner marked that line or the one next to it), judge their reason: feedback says if the
+reason is right and what the full effect is (1-2 sentences).
+For each FALSE ALARM (a mark on a line with no bug), explain in 1-2 sentences why that line is fine.
+${STYLE}
+
+JSON shape:
+{ "found": [{"line": 12, "feedback": "..."}], "falseAlarms": [{"line": 40, "feedback": "..."}] }`;
+}
+function huntgradePrompt(bugs, found, falseAlarms, text2) {
+  return `PLANTED BUGS:
+${bugs.map((b) => `line ${b.line}: was \`${b.original.trim()}\`, now \`${b.buggy.trim()}\` (${b.what})`).join("\n")}
+
+FOUND (learner's mark -> bug line):
+${found.map((f) => `mark line ${f.line} -> bug line ${f.bugLine}: "${f.why}"`).join("\n") || "(none)"}
+
+FALSE ALARMS:
+${falseAlarms.map((f) => `line ${f.line}: "${f.why}"`).join("\n") || "(none)"}
+
+THE FILE WITH THE BUGS:
+${text2}`;
+}
+function pathSystem() {
+  return `TASK: path
+Plan an onboarding path through this codebase for an engineer new to it: 6-12 stops, in the order to learn them.
+Start where the reader gets the big picture (entry points, core data shapes), then the most depended-on modules,
+then the interesting logic. Each stop: 1-4 files (relative paths EXACTLY as listed), why it comes now (1-2
+sentences), and the activity that fits: "lens" (read an explanation), "walk" (guided walkthrough of one file),
+"quiz" (check understanding), "teachback" (explain it yourself; good after 2-3 stops on one area).
+${STYLE}
+
+JSON shape:
+{ "title": "short", "stops": [{"title": "short", "files": ["relative/path"], "why": "...", "activity": "lens|walk|quiz|teachback"}] }`;
+}
+function pathPrompt(files, hubs, docs, goal) {
+  return `${goal ? `THE LEARNER'S GOAL: ${goal}
+
+` : ""}MOST IMPORTED FILES (import graph, most first):
+${hubs.join("\n") || "(no import data)"}
+
+ALL FILES:
+${files.join("\n")}
+
+${docs ? `DOCS:
+${docs}` : ""}`;
+}
+function parseJson(text2) {
+  const fences = [...text2.matchAll(/```(?:json)?\s*\n([\s\S]*?)```/g)];
+  const candidates = fences.map((m) => m[1]).reverse();
+  const first = text2.indexOf("{");
+  const last = text2.lastIndexOf("}");
+  if (first >= 0 && last > first) candidates.push(text2.slice(first, last + 1));
+  for (const c of candidates) {
+    try {
+      return JSON.parse(c);
+    } catch {
+    }
+  }
+  throw new Error(`model reply had no valid JSON: ${text2.slice(0, 300)}`);
+}
+
+// src/core/schemas.ts
+import { z } from "zod";
+var text = z.string();
+var line = z.coerce.number().int().positive();
+var verdict = z.enum(["right", "partial", "wrong"]);
+var SCHEMAS = {
+  lens: z.object({
+    title: text,
+    tldr: text.min(10),
+    summary: text,
+    concepts: z.array(z.object({ term: text, explain: text })).optional(),
+    intuition: text.optional(),
+    deepDives: z.array(z.object({ title: text, body: text })).min(1)
+  }),
+  lensPlan: z.object({
+    title: text,
+    tldr: text.min(10),
+    steps: z.array(z.object({ title: text })).min(1)
+  }),
+  lensIntro: z.object({ summary: text, intuition: text.optional() }),
+  lensSteps: z.object({ steps: z.array(z.object({ body: text })).min(1) }),
+  plan: z.object({ outline: text.min(10) }),
+  lensSketch: z.object({ differences: z.array(text).min(1) }),
+  lensTrace: z.object({
+    trace: z.object({ input: text, steps: z.array(z.object({ note: text, state: z.record(z.unknown()).optional() })).min(1) })
+  }),
+  quiz: z.object({ questions: z.array(z.object({ prompt: text })).min(1) }),
+  grade: z.object({ grades: z.array(z.object({ qid: text, verdict })).min(1) }),
+  practice: z.object({ holes: z.array(z.object({ startLine: line, endLine: line, intent: text })).min(1) }),
+  review: z.object({ holes: z.array(z.object({ id: z.coerce.number(), verdict })) }),
+  teachback: z.object({ score: z.coerce.number().min(1).max(5), right: z.array(text), missing: z.array(text), wrong: z.array(text) }),
+  tutor: z.object({ reply: text.min(1) }),
+  walk: z.object({ blocks: z.array(z.object({ startLine: line, endLine: line, question: text })).min(2) }),
+  walkPlan: z.object({ blocks: z.array(z.object({ startLine: line, endLine: line, title: text })).min(2) }),
+  walkBlocks: z.object({ blocks: z.array(z.object({ question: text })).min(1) }),
+  walkcheck: z.object({ verdict, feedback: text }),
+  hunt: z.object({ bugs: z.array(z.object({ line, original: text, buggy: text, what: text })).min(1) }),
+  huntgrade: z.object({ found: z.array(z.object({ line })), falseAlarms: z.array(z.object({ line })) }),
+  path: z.object({ title: text, stops: z.array(z.object({ title: text, files: z.array(text).min(1), why: text })).min(2) })
+};
+function problems(task, value) {
+  const r = SCHEMAS[task].safeParse(value);
+  if (r.success) return null;
+  return r.error.issues.slice(0, 6).map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+}
+
+// src/core/services.ts
+var VERDICTS = ["right", "partial", "wrong"];
+var str = (v, max = 4e3) => typeof v === "string" ? v.slice(0, max) : "";
+var arr = (v) => Array.isArray(v) ? v : [];
+var num = (v) => {
+  const n = typeof v === "string" ? Number(v) : v;
+  return typeof n === "number" && Number.isFinite(n) ? Math.round(n) : void 0;
+};
+var verdict2 = (v) => VERDICTS.includes(v) ? v : "wrong";
+var strs = (v, max = 600, n = 12) => arr(v).map((x) => str(x, max)).filter(Boolean).slice(0, n);
+var now = () => (/* @__PURE__ */ new Date()).toISOString();
+var ACTIVITIES = ["lens", "walk", "quiz", "teachback"];
+var Learn = class {
+  constructor(store2, agent) {
+    this.store = store2;
+    this.agent = agent;
+    this.cache = new ReplyCache(store2);
+  }
+  cache;
+  settings() {
+    return this.store.settings();
+  }
+  /**
+   * One model call, parsed and checked. `cache` reuses an earlier reply to the exact same prompt
+   * (a lens on an unchanged file is free the second time).
+   */
+  async ask(ws, tasks, system, prompt0, opts2 = {}) {
+    const key = opts2.cache ? this.cache.key(this.agent.name, system, prompt0) : "";
+    let prompt = prompt0;
+    if (opts2.plan && this.settings()["generate.plan"]) {
+      const o = await this.ask(ws, ["plan"], planSystem(system), prompt0, { role: "plan" });
+      prompt = `${prompt0}
+
+PLAN (from the planner; follow it):
+${o.outline}`;
+    }
+    const hit = key ? this.cache.get(key) : void 0;
+    if (hit) {
+      try {
+        const v = parseJson(hit);
+        if (tasks.every((t) => !problems(t, v))) return v;
+      } catch {
+      }
+    }
+    let text2 = await this.agent.complete({ system, prompt, cwd: ws.project.root, role: opts2.role });
+    let value;
+    let issue = null;
+    try {
+      value = parseJson(text2);
+      issue = tasks.map((t) => problems(t, value)).find(Boolean) ?? null;
+    } catch (e) {
+      issue = e instanceof Error ? e.message.slice(0, 200) : "no JSON";
+    }
+    if (issue) {
+      const retry = `${prompt}
+
+YOUR LAST REPLY COULD NOT BE USED: ${issue}
+Reply again with the full JSON object in the required shape.`;
+      text2 = await this.agent.complete({ system, prompt: retry, cwd: ws.project.root, role: opts2.role });
+      value = parseJson(text2);
+      const again = tasks.map((t) => problems(t, value)).find(Boolean);
+      if (again) throw new Error(`the model reply did not have the expected shape: ${again}`);
+    }
+    if (key) this.cache.set(key, text2);
+    return value;
+  }
+  bundle(ws, files) {
+    return ws.bundle(files, this.settings()["context.maxBytes"]);
+  }
+  /** The learner's margin notes on these files, when the setting is on. */
+  notes(ws, files) {
+    if (!this.settings()["notes.inPrompts"]) return void 0;
+    const want = new Set(files);
+    const lines = this.store.list(ws.project.id, "notes").filter((n) => n.file && want.has(n.file)).map((n) => `${ws.rel(n.file)}${n.line ? `:${n.line}` : ""}: ${n.text}`);
+    return lines.length ? lines.join("\n").slice(0, 8e3) : void 0;
+  }
+  diffText(ws, diff, files) {
+    if (!diff) return void 0;
+    const want = new Set(files);
+    const patches = ws.diff(diff).filter((f) => want.size === 0 || want.has(f.path)).map((f) => f.patch);
+    return patches.join("\n").slice(0, this.settings()["context.maxBytes"] / 2);
+  }
+  hashes(ws, files) {
+    return Object.fromEntries(files.map((f) => [f, ws.hash(f) ?? ""]));
+  }
+  /** Rough size of a prompt for these files, for the "~N tokens" line before a job. */
+  estimate(project, files) {
+    const ws = new Workspace(project);
+    const max = this.settings()["context.maxBytes"];
+    const text2 = ws.bundle(files.map((f) => ws.guard(f)), max);
+    return { bytes: text2.length, tokens: Math.round(text2.length / 3.5), cut: text2.includes("(Not included, too large") };
+  }
+  // ---- lens ------------------------------------------------------------
+  async lens(project, req) {
+    const ws = new Workspace(project);
+    const old = req.refreshOf ? this.store.get(project.id, "lenses", req.refreshOf) : void 0;
+    if (req.refreshOf && !old) throw new Error("lens not found");
+    const r = old ? { files: old.files, kind: old.kind, question: old.question, diff: old.diff, sketch: void 0, traceInput: old.trace?.input, depth: old.depth } : req;
+    const depth = r.depth === "overview" || r.depth === "deep" ? r.depth : "standard";
+    const files = r.files.map((f) => ws.guard(f));
+    if (!files.length) throw new Error("pick at least one file");
+    const kind = LENS_KINDS.find((k) => k.id === r.kind);
+    const question = r.question?.trim() || kind?.question || LENS_KINDS[0].question;
+    const sketch = r.sketch?.trim() || void 0;
+    const trace = kind?.id === "trace";
+    const max = this.settings()["context.maxBytes"];
+    const extras = {
+      diff: this.diffText(ws, r.diff, files),
+      sketch,
+      traceInput: trace ? (r.traceInput ?? "").trim() : void 0,
+      history: kind?.id === "history" ? ws.history(files[0], max / 2) : void 0,
+      previous: old ? `${old.summary}
+${old.deepDives.map((d) => `- ${d.title}`).join("\n")}` : void 0,
+      notes: this.notes(ws, files)
+    };
+    const tasks = ["lens", ...sketch ? ["lensSketch"] : [], ...trace ? ["lensTrace"] : []];
+    const cache = !old && !sketch;
+    const raw = this.settings()["generate.plan"] ? await this.lensStaged(ws, { question, files, depth, extras, sketch: !!sketch, trace, cache }) : await this.ask(
+      ws,
+      tasks,
+      lensSystem({ sketch: !!sketch, trace, depth }),
+      lensPrompt(question, this.bundle(ws, files), extras),
+      { cache }
+    );
+    const lens = {
+      id: newId(),
+      projectId: project.id,
+      createdAt: now(),
+      kind: kind?.id ?? "custom",
+      question,
+      files,
+      diff: r.diff,
+      title: str(raw.title, 120) || question,
+      summary: str(raw.summary),
+      concepts: arr(raw.concepts).map((c) => {
+        const o = c;
+        return {
+          term: str(o.term, 120),
+          explain: str(o.explain),
+          example: str(o.example, 1e3) || void 0,
+          file: ws.absFromRel(str(o.file, 500)),
+          line: num(o.line)
+        };
+      }).filter((c) => c.term),
+      intuition: str(raw.intuition, 12e3),
+      deepDives: arr(raw.deepDives).map((d) => cleanDive(d, ws)).filter((d) => d.title || d.body),
+      tldr: str(raw.tldr, 400) || void 0,
+      whyItMatters: str(raw.whyItMatters, 800) || void 0,
+      gotchas: strs(raw.gotchas, 400, 8),
+      nextSteps: arr(raw.nextSteps).map((n) => {
+        const o = n;
+        return { file: ws.absFromRel(str(o.file, 500)) ?? "", why: str(o.why, 400) };
+      }).filter((n) => n.file).slice(0, 4),
+      depth,
+      fileHashes: this.hashes(ws, files),
+      sketch,
+      differences: sketch ? strs(raw.differences) : void 0,
+      trace: trace ? cleanTrace(raw.trace, ws) : void 0
+    };
+    this.store.put(project.id, "lenses", lens);
+    if (old) this.store.archive(project.id, "lenses", old.id);
+    return lens;
+  }
+  /**
+   * A lens in parts instead of one call: the planner outlines (title, tldr, every step with its lines and
+   * what it must cover), then the writer fills in the opening and the steps, a few steps per call, side by
+   * side. The result has the same shape as the one-shot reply, so the caller does not care which ran.
+   */
+  async lensStaged(ws, x) {
+    const code = this.bundle(ws, x.files);
+    const plan = await this.ask(
+      ws,
+      ["lensPlan"],
+      lensPlanSystem({ depth: x.depth, trace: x.trace }),
+      lensPrompt(x.question, code, x.extras),
+      { cache: x.cache, role: "plan" }
+    );
+    const planned = arr(plan.steps).map((st) => st);
+    const introTasks = ["lensIntro", ...x.sketch ? ["lensSketch"] : [], ...x.trace ? ["lensTrace"] : []];
+    const chunk = x.depth === "overview" ? 4 : 3;
+    const ranges = [];
+    for (let i = 0; i < planned.length; i += chunk) ranges.push([i, Math.min(planned.length, i + chunk) - 1]);
+    const jobs = [
+      () => this.ask(
+        ws,
+        introTasks,
+        lensIntroSystem({ depth: x.depth, sketch: x.sketch, trace: x.trace }),
+        lensWritePrompt(x.question, plan, code, { extras: x.extras }),
+        { cache: x.cache }
+      ),
+      ...ranges.map((r) => () => this.ask(
+        ws,
+        ["lensSteps"],
+        lensStepsSystem({ depth: x.depth }),
+        lensWritePrompt(x.question, plan, code, { steps: r, titles: planned.slice(0, r[0]).map((st) => str(st.title, 200)) }),
+        { cache: x.cache }
+      ))
+    ];
+    const [intro, ...written] = await inParallel(jobs, 3);
+    const bodies = /* @__PURE__ */ new Map();
+    written.forEach((w, n) => arr(w.steps).forEach((st, k) => {
+      const o = st;
+      bodies.set(num(o.index) ?? ranges[n][0] + k, o);
+    }));
+    const deepDives = planned.map((st, i) => {
+      const w = bodies.get(i) ?? {};
+      const covers = strs(st.covers, 400, 12);
+      return {
+        title: st.title,
+        file: st.file,
+        line: st.line,
+        startLine: st.startLine,
+        endLine: st.endLine,
+        // If a part never came back, fall back to the plan's own notes so the step is not empty.
+        body: str(w.body, 12e3) || covers.map((c) => `- ${c}`).join("\n") || str(st.why, 800),
+        pitfall: w.pitfall ?? (str(st.pitfall, 800) || void 0),
+        check: w.check
+      };
+    });
+    return {
+      ...intro,
+      title: plan.title,
+      tldr: plan.tldr,
+      whyItMatters: plan.whyItMatters,
+      concepts: arr(intro.concepts).length ? intro.concepts : arr(plan.concepts).map((c) => ({ ...c, explain: str(c.note) })),
+      gotchas: arr(intro.gotchas).length ? intro.gotchas : plan.gotchas,
+      nextSteps: arr(intro.nextSteps).length ? intro.nextSteps : plan.nextSteps,
+      deepDives
+    };
+  }
+  // ---- quiz ------------------------------------------------------------
+  async quiz(project, req) {
+    const ws = new Workspace(project);
+    const lens = req.lensId ? this.store.get(project.id, "lenses", req.lensId) : void 0;
+    const weak = req.weak ? openMisconceptions(this.store, project.id).slice(0, 6) : [];
+    if (req.weak && !weak.length) throw new Error("no open weak spots: nothing to aim at yet");
+    const weakFiles = weak.map((m) => m.file).filter((f) => !!f);
+    const files = [...new Set((req.files.length ? req.files : lens?.files ?? weakFiles).map((f) => ws.guard(f)))];
+    if (!files.length && !weak.length) throw new Error("pick at least one file");
+    const n = Math.min(Math.max(req.count ?? (weak.length || this.settings()["quiz.questions"]), 1), 10);
+    const raw = await this.ask(
+      ws,
+      ["quiz"],
+      quizSystem(n),
+      quizPrompt(this.bundle(ws, files), this.diffText(ws, req.diff ?? lens?.diff, files), lens?.summary, weak.map((m) => ({ id: m.id, text: m.text }))),
+      { plan: true }
+    );
+    const weakIds = new Set(weak.map((m) => m.id));
+    const questions = arr(raw.questions).slice(0, n).map((q, i) => {
+      const o = q;
+      const target = str(o.targets, 40);
+      return {
+        id: `q${i + 1}`,
+        prompt: str(o.prompt, 2e3),
+        file: ws.absFromRel(str(o.file, 500)),
+        line: num(o.line),
+        focus: str(o.focus, 120),
+        misconceptionId: weakIds.has(target) ? target : void 0
+      };
+    }).filter((q) => q.prompt);
+    if (!questions.length) throw new Error("the model wrote no questions");
+    const quiz = {
+      id: newId(),
+      projectId: project.id,
+      createdAt: now(),
+      title: str(raw.title, 120) || (weak.length ? "Your weak spots" : "Quiz"),
+      files,
+      fileHashes: this.hashes(ws, files),
+      diff: req.diff ?? lens?.diff,
+      lensId: lens?.id,
+      questions,
+      attempts: []
+    };
+    return this.store.put(project.id, "quizzes", quiz);
+  }
+  async grade(project, quizId, answers) {
+    const ws = new Workspace(project);
+    const quiz = this.store.get(project.id, "quizzes", quizId);
+    if (!quiz) throw new Error("quiz not found");
+    const byId = new Map(answers.map((a) => [a.qid, a]));
+    const items2 = quiz.questions.map((q) => ({ qid: q.id, question: q.prompt, answer: str(byId.get(q.id)?.answer, 4e3) }));
+    const raw = await this.ask(ws, ["grade"], gradeSystem(), gradePrompt(items2, this.bundle(ws, quiz.files)));
+    const got = new Map(arr(raw.grades).map((g) => {
+      const o = g;
+      return [str(o.qid, 20), o];
+    }));
+    const grades = quiz.questions.map((q) => {
+      const o = got.get(q.id) ?? {};
+      const answered = !!byId.get(q.id)?.answer?.trim();
+      const v = answered ? verdict2(o.verdict) : "wrong";
+      const mis = v !== "right" && answered ? str(o.misconception, 500) : "";
+      return { qid: q.id, verdict: v, feedback: str(o.feedback), modelAnswer: str(o.modelAnswer), ...mis ? { misconception: mis } : {} };
+    });
+    const attempt = {
+      at: now(),
+      answers: quiz.questions.map((q) => ({ qid: q.id, answer: byId.get(q.id)?.answer ?? "", sure: !!byId.get(q.id)?.sure })),
+      grades,
+      score: scoreOf(grades)
+    };
+    quiz.attempts.push(attempt);
+    this.store.put(project.id, "quizzes", quiz);
+    this.afterGrade(project, quiz, grades);
+    return quiz;
+  }
+  /** Misses become misconceptions and review cards; a right answer resolves what it targeted. */
+  afterGrade(project, quiz, grades) {
+    const pid = project.id;
+    const cards = this.settings()["cards.fromMisses"] ? this.store.list(pid, "cards") : null;
+    for (const g of grades) {
+      const q = quiz.questions.find((x) => x.id === g.qid);
+      if (!q) continue;
+      const sourceId = `${quiz.id}:${q.id}`;
+      if (g.verdict === "right") {
+        resolveMisconception(this.store, pid, (m) => m.id === q.misconceptionId || m.sourceId === sourceId);
+        continue;
+      }
+      if (g.misconception) recordMisconception(this.store, pid, { text: g.misconception, file: q.file, line: q.line, from: "quiz", sourceId });
+      if (cards && g.modelAnswer && !cards.some((c) => c.source?.quizId === quiz.id && c.source?.qid === q.id)) {
+        this.store.put(pid, "cards", makeCard(pid, { kind: "miss", front: q.prompt, back: g.modelAnswer, file: q.file, line: q.line, source: { quizId: quiz.id, qid: q.id } }));
+      }
+    }
+  }
+  // ---- practice --------------------------------------------------------
+  async practice(project, req) {
+    const ws = new Workspace(project);
+    const level = Math.min(Math.max(Math.round(req.level || 2), 1), 4);
+    const paths = [...new Set([...req.files ?? [], ...req.file ? [req.file] : []].map((f) => ws.guard(f)))];
+    const DATA = /\.(json|ya?ml|toml|ini|cfg|lock|csv|tsv|md|txt|svg|xml|html?|css)$/i;
+    const code = paths.filter((f) => !DATA.test(f));
+    if (!code.length) throw new Error("practice needs at least one file with logic (code). These are data, config or text; add a source file.");
+    const texts = new Map(paths.map((f) => [f, ws.read(f).text]));
+    const concept = (req.concept ?? "").trim().slice(0, 300);
+    const prompt = (concept ? `CONCEPT TO PRACTISE: ${concept}
+
+` : "") + `CODE FILES (holes may be cut from these):
+${this.bundle(ws, code)}` + (paths.length > code.length ? `
+
+CONTEXT FILES (read only, no holes):
+${this.bundle(ws, paths.filter((f) => DATA.test(f)))}` : "");
+    const raw = await this.ask(ws, ["practice"], practiceSystem(level, !!concept, code.length > 1), prompt, { plan: true });
+    const byFile = /* @__PURE__ */ new Map();
+    for (const h of arr(raw.holes)) {
+      const want = str(h.file, 500);
+      const hit = want ? code.find((f) => ws.rel(f) === want || ws.rel(f).endsWith(want) || want.endsWith(ws.rel(f))) : code.length === 1 ? code[0] : void 0;
+      if (hit) byFile.set(hit, [...byFile.get(hit) ?? [], h]);
+    }
+    const holes = [];
+    const files = [];
+    for (const f of paths) {
+      const original = texts.get(f);
+      const lines = original.split("\n");
+      const mine = cleanHoles(byFile.get(f) ?? [], lines.length, lines).map((h, i) => ({ ...h, id: holes.length + i + 1, file: f }));
+      holes.push(...mine);
+      const holed = mine.length ? applyHoles(original, mine, langOf(f)) : original;
+      files.push({ path: f, original, holed, attempt: holed });
+    }
+    if (!holes.length) throw new Error("the model found no lines with real logic to turn into holes; try other files or a higher level");
+    files.sort((x, y) => Number(holes.some((h) => h.file === y.path)) - Number(holes.some((h) => h.file === x.path)));
+    const first = files[0];
+    const p = {
+      id: newId(),
+      projectId: project.id,
+      createdAt: now(),
+      concept: concept || str(raw.concept, 300) || void 0,
+      files,
+      file: first.path,
+      level,
+      original: first.original,
+      holed: first.holed,
+      holes,
+      attempt: first.holed
+    };
+    return this.store.put(project.id, "practice", p);
+  }
+  saveAttempt(project, id, text2, file) {
+    const got = this.store.get(project.id, "practice", id);
+    if (!got) throw new Error("practice not found");
+    const p = normalizePractice(got);
+    const f = p.files.find((x) => x.path === file) ?? p.files[0];
+    f.attempt = text2.slice(0, 1e6);
+    if (f.path === p.file) p.attempt = f.attempt;
+    return this.store.put(project.id, "practice", p);
+  }
+  async review(project, id) {
+    const ws = new Workspace(project);
+    const got = this.store.get(project.id, "practice", id);
+    if (!got) throw new Error("practice not found");
+    const p = normalizePractice(got);
+    const parts = p.files.map((f) => ({ rel: ws.rel(f.path), original: f.original, attempt: f.attempt, holes: p.holes.filter((h) => h.file === f.path) })).filter((f) => f.holes.length);
+    const raw = await this.ask(ws, ["review"], reviewSystem(), reviewPrompt(parts));
+    const got2 = new Map(arr(raw.holes).map((h) => [num(h.id), h]));
+    const holes = p.holes.map((h) => {
+      const o = got2.get(h.id) ?? {};
+      return { id: h.id, verdict: verdict2(o.verdict), feedback: str(o.feedback) };
+    });
+    p.review = { at: now(), holes, summary: str(raw.summary) };
+    return this.store.put(project.id, "practice", p);
+  }
+  // ---- teach-back ------------------------------------------------------
+  async teachback(project, req) {
+    const ws = new Workspace(project);
+    const files = req.files.map((f) => ws.guard(f));
+    if (!files.length) throw new Error("pick at least one file");
+    const text2 = (req.text ?? "").trim().slice(0, 2e4);
+    if (text2.length < 20) throw new Error("write a few sentences first");
+    const raw = await this.ask(ws, ["teachback"], teachbackSystem(), teachbackPrompt(text2, this.bundle(ws, files)));
+    const t = {
+      id: newId(),
+      projectId: project.id,
+      createdAt: now(),
+      files,
+      fileHashes: this.hashes(ws, files),
+      text: text2,
+      grade: {
+        score: Math.min(5, Math.max(1, num(raw.score) ?? 1)),
+        summary: str(raw.summary, 800),
+        right: strs(raw.right),
+        missing: strs(raw.missing),
+        wrong: strs(raw.wrong)
+      }
+    };
+    this.store.put(project.id, "teachbacks", t);
+    t.grade.wrong.forEach((w, i) => recordMisconception(this.store, project.id, { text: w, file: files[0], from: "teachback", sourceId: `${t.id}:${i}` }));
+    return t;
+  }
+  // ---- tutor -------------------------------------------------------------
+  async startThread(project, req) {
+    const ws = new Workspace(project);
+    const files = req.files.map((f) => ws.guard(f));
+    if (!files.length) throw new Error("pick at least one file");
+    const text2 = (req.text ?? "").trim();
+    if (!text2) throw new Error("ask a question first");
+    const t = { id: newId(), projectId: project.id, createdAt: now(), title: text2.split("\n")[0].slice(0, 80), files, messages: [] };
+    return this.tutorTurn(project, t, text2, false);
+  }
+  async tutorReply(project, id, text2, tell) {
+    const t = this.store.get(project.id, "threads", id);
+    if (!t) throw new Error("thread not found");
+    return this.tutorTurn(project, t, (text2 ?? "").trim() || (tell ? "Just tell me." : ""), tell);
+  }
+  async tutorTurn(project, t, text2, tell) {
+    if (!text2) throw new Error("write something first");
+    const ws = new Workspace(project);
+    t.messages.push({ role: "user", text: text2.slice(0, 8e3), at: now() });
+    const since = t.messages.slice(t.messages.map((m) => m.hintLevel === 4).lastIndexOf(true) + 1);
+    const level = Math.min(3, since.filter((m) => m.role === "tutor").length + 1);
+    const raw = await this.ask(ws, ["tutor"], tutorSystem(level, tell), tutorPrompt(t.messages, this.bundle(ws, t.files), this.notes(ws, t.files)));
+    t.messages.push({ role: "tutor", text: str(raw.reply, 8e3), at: now(), hintLevel: tell ? 4 : level });
+    if (t.messages.length > THREAD_MESSAGE_CAP) t.messages = [t.messages[0], ...t.messages.slice(-(THREAD_MESSAGE_CAP - 1))];
+    return this.store.put(project.id, "threads", t);
+  }
+  // ---- walkthrough ---------------------------------------------------------
+  async walk(project, req) {
+    const ws = new Workspace(project);
+    const file = ws.guard(req.file);
+    const content = ws.read(file);
+    const lines = content.text.split("\n").length;
+    const code = this.bundle(ws, [file]);
+    let rawBlocks;
+    if (this.settings()["generate.plan"]) {
+      const plan = await this.ask(ws, ["walkPlan"], walkPlanSystem(), `CODE:
+${code}`, { cache: true, role: "plan" });
+      const planned = arr(plan.blocks).slice(0, 14).map((b) => b);
+      const ranges = [];
+      for (let i = 0; i < planned.length; i += 3) ranges.push([i, Math.min(planned.length, i + 3) - 1]);
+      const written = await inParallel(
+        ranges.map((r) => () => this.ask(
+          ws,
+          ["walkBlocks"],
+          walkBlocksSystem(),
+          walkWritePrompt({ blocks: planned }, r, planned.slice(0, r[0]).map((b) => str(b.title, 160)), code),
+          { cache: true }
+        )),
+        3
+      );
+      const byIndex = /* @__PURE__ */ new Map();
+      written.forEach((w, n) => arr(w.blocks).forEach((b, k) => {
+        const o = b;
+        byIndex.set(num(o.index) ?? ranges[n][0] + k, o);
+      }));
+      rawBlocks = planned.map((b, i) => ({ ...b, ...byIndex.get(i) ?? {}, question: str(byIndex.get(i)?.question, 800) || str(b.question, 800) }));
+    } else {
+      rawBlocks = (await this.ask(ws, ["walk"], walkSystem(), `CODE:
+${code}`, { cache: true })).blocks ?? [];
+    }
+    const blocks = arr(rawBlocks).map((b) => {
+      const o = b;
+      const startLine = num(o.startLine) ?? 0;
+      return {
+        startLine,
+        endLine: Math.min(lines, num(o.endLine) ?? startLine),
+        title: str(o.title, 120),
+        why: str(o.why, 800),
+        explain: str(o.explain, 6e3) || void 0,
+        example: str(o.example, 6e3) || void 0,
+        question: str(o.question, 800)
+      };
+    }).filter((b) => b.startLine >= 1 && b.endLine >= b.startLine && b.question).slice(0, 12);
+    if (blocks.length < 2) throw new Error("the model could not split this file into blocks");
+    return this.store.put(project.id, "walks", { id: newId(), projectId: project.id, createdAt: now(), file, fileHash: content.hash, blocks });
+  }
+  async walkcheck(project, id, index, answer) {
+    const ws = new Workspace(project);
+    const w = this.store.get(project.id, "walks", id);
+    if (!w) throw new Error("walkthrough not found");
+    const b = w.blocks[index];
+    if (!b) throw new Error("block not found");
+    const text2 = ws.read(w.file).text.split("\n");
+    const block = text2.slice(b.startLine - 1, b.endLine).map((l, i) => `${String(b.startLine + i).padStart(4)}| ${l}`).join("\n");
+    const raw = await this.ask(ws, ["walkcheck"], walkcheckSystem(), walkcheckPrompt(b.question, answer, block, this.bundle(ws, [w.file])));
+    b.answer = answer.slice(0, 4e3);
+    b.verdict = answer.trim() ? verdict2(raw.verdict) : "wrong";
+    b.feedback = str(raw.feedback, 1500);
+    this.store.put(project.id, "walks", w);
+    const mis = str(raw.misconception, 500);
+    if (b.verdict !== "right" && mis && answer.trim()) recordMisconception(this.store, project.id, { text: mis, file: w.file, line: b.startLine, from: "walk", sourceId: `${w.id}:${index}` });
+    if (b.verdict === "right") resolveMisconception(this.store, project.id, (m) => m.sourceId === `${w.id}:${index}`);
+    return w;
+  }
+  // ---- bug hunt --------------------------------------------------------------
+  async hunt(project, req) {
+    const ws = new Workspace(project);
+    const file = ws.guard(req.file);
+    const content = ws.read(file);
+    const level = Math.min(3, Math.max(1, Math.round(req.level || 1)));
+    const raw = await this.ask(ws, ["hunt"], huntSystem(level), `CODE:
+${this.bundle(ws, [file])}`, { plan: true });
+    const { text: text2, planted } = plantBugs(content.text, arr(raw.bugs));
+    if (!planted.length) throw new Error("the model's bugs did not match the file; try again");
+    return this.store.put(project.id, "hunts", {
+      id: newId(),
+      projectId: project.id,
+      createdAt: now(),
+      file,
+      fileHash: content.hash,
+      level,
+      text: text2,
+      planted,
+      marks: []
+    });
+  }
+  saveMarks(project, id, marks) {
+    const h = this.store.get(project.id, "hunts", id);
+    if (!h) throw new Error("bug hunt not found");
+    if (h.grade) throw new Error("already graded");
+    h.marks = marks.map((m) => ({ line: num(m.line) ?? 0, why: str(m.why, 1e3) })).filter((m) => m.line >= 1).slice(0, 20);
+    return this.store.put(project.id, "hunts", h);
+  }
+  async huntgrade(project, id) {
+    const ws = new Workspace(project);
+    const h = this.store.get(project.id, "hunts", id);
+    if (!h) throw new Error("bug hunt not found");
+    const { found, falseAlarms, missed } = matchMarks(h.planted, h.marks);
+    let fb = /* @__PURE__ */ new Map();
+    let fa = /* @__PURE__ */ new Map();
+    if (found.length || falseAlarms.length) {
+      const numbered = h.text.split("\n").map((l, i) => `${String(i + 1).padStart(4)}| ${l}`).join("\n");
+      const raw = await this.ask(
+        ws,
+        ["huntgrade"],
+        huntgradeSystem(),
+        huntgradePrompt(h.planted, found.map((f) => ({ line: f.mark.line, why: f.mark.why, bugLine: f.bug.line })), falseAlarms, numbered)
+      );
+      fb = new Map(arr(raw.found).map((x) => [num(x.line) ?? 0, str(x.feedback, 1e3)]));
+      fa = new Map(arr(raw.falseAlarms).map((x) => [num(x.line) ?? 0, str(x.feedback, 1e3)]));
+    }
+    const score = Math.max(0, (found.length - 0.5 * falseAlarms.length) / h.planted.length);
+    h.grade = {
+      at: now(),
+      found: found.map((f) => ({ line: f.bug.line, what: f.bug.what, feedback: fb.get(f.bug.line) ?? fb.get(f.mark.line) ?? "" })),
+      missed: missed.map((b) => ({ line: b.line, what: b.what })),
+      falseAlarms: falseAlarms.map((m) => ({ line: m.line, feedback: fa.get(m.line) ?? "" })),
+      score: Math.round(score * 100) / 100
+    };
+    return this.store.put(project.id, "hunts", h);
+  }
+  // ---- learning path -----------------------------------------------------------
+  async path(project, req) {
+    const ws = new Workspace(project);
+    const all = ws.files();
+    const rels = all.map((f) => ws.rel(f)).slice(0, 1500);
+    const docs = all.filter((f) => /(^|\/)(readme|architecture|contributing|design)[^/]*\.md$/i.test(ws.rel(f))).slice(0, 3);
+    const docText = docs.length ? ws.bundle(docs, 24e3) : "";
+    const raw = await this.ask(
+      ws,
+      ["path"],
+      pathSystem(),
+      pathPrompt(rels, req.hubs.slice(0, 20).map((f) => ws.rel(f)), docText, req.goal?.trim()),
+      { cache: true, plan: true }
+    );
+    const stops = arr(raw.stops).map((s) => {
+      const o = s;
+      const files = arr(o.files).map((f) => ws.absFromRel(str(f, 500))).filter((f) => !!f).slice(0, 4);
+      const activity = ACTIVITIES.includes(o.activity) ? o.activity : "lens";
+      return { title: str(o.title, 120), files, why: str(o.why, 800), activity };
+    }).filter((s) => s.files.length && s.title).slice(0, 14);
+    if (stops.length < 2) throw new Error("the model's path named no files that exist here");
+    return this.store.put(project.id, "paths", { id: newId(), projectId: project.id, createdAt: now(), title: str(raw.title, 120) || "Onboarding path", stops });
+  }
+  // ---- progress --------------------------------------------------------
+  progress(project) {
+    return progress(this.store, project);
+  }
+};
+async function inParallel(jobs, limit) {
+  const out = new Array(jobs.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < jobs.length) {
+      const i = next++;
+      out[i] = await jobs[i]();
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, jobs.length) }, worker));
+  return out;
+}
+function cleanDive(o, ws) {
+  const file = ws.absFromRel(str(o.file, 500));
+  const line2 = num(o.line);
+  let startLine = num(o.startLine);
+  let endLine = num(o.endLine);
+  if (!startLine || !endLine || endLine < startLine) {
+    startLine = line2 ? Math.max(1, line2 - 3) : void 0;
+    endLine = line2 ? line2 + 6 : void 0;
+  }
+  if (startLine && endLine && endLine - startLine > 40) endLine = startLine + 40;
+  const chk = o.check ?? {};
+  const q = str(chk.q, 600);
+  const a = str(chk.a, 1e3);
+  return {
+    title: str(o.title, 200),
+    file,
+    line: line2 ?? startLine,
+    startLine,
+    endLine,
+    body: str(o.body, 12e3),
+    pitfall: str(o.pitfall, 800) || void 0,
+    check: q && a ? { q, a } : void 0
+  };
+}
+function cleanTrace(v, ws) {
+  const o = v ?? {};
+  const steps = arr(o.steps).slice(0, 60).map((s) => {
+    const x = s;
+    const state = Object.fromEntries(
+      Object.entries(x.state ?? {}).slice(0, 16).map(([k, val]) => [k.slice(0, 60), (typeof val === "string" ? val : JSON.stringify(val) ?? "").slice(0, 200)])
+    );
+    return { file: ws.absFromRel(str(x.file, 500)), line: num(x.line), state, note: str(x.note, 600) };
+  });
+  return steps.length ? { input: str(o.input, 600), steps } : void 0;
+}
+function plantBugs(original, raw) {
+  const lines = original.split("\n");
+  const planted = [];
+  for (const b of raw) {
+    const o = b;
+    const want = str(o.original, 2e3).trim();
+    const buggy = str(o.buggy, 2e3);
+    if (!want || !buggy.trim() || buggy.trim() === want) continue;
+    let at = (num(o.line) ?? 0) - 1;
+    if (lines[at]?.trim() !== want) {
+      const hits = lines.map((l, i) => l.trim() === want ? i : -1).filter((i) => i >= 0);
+      if (hits.length !== 1) continue;
+      at = hits[0];
+    }
+    if (planted.some((p) => p.line === at + 1)) continue;
+    const indent = /^\s*/.exec(lines[at])?.[0] ?? "";
+    planted.push({ line: at + 1, original: lines[at], buggy: indent + buggy.trimStart(), what: str(o.what, 800) });
+    lines[at] = indent + buggy.trimStart();
+  }
+  return { text: lines.join("\n"), planted: planted.sort((a, b) => a.line - b.line) };
+}
+function matchMarks(planted, marks) {
+  const left = [...planted];
+  const found = [];
+  const falseAlarms = [];
+  for (const m of [...marks].sort((a, b) => a.line - b.line)) {
+    const i = left.map((b) => Math.abs(b.line - m.line)).reduce((best, d, j, all) => d <= 1 && (best < 0 || d < all[best]) ? j : best, -1);
+    if (i >= 0) found.push({ bug: left.splice(i, 1)[0], mark: m });
+    else falseAlarms.push(m);
+  }
+  return { found, falseAlarms, missed: left };
+}
+function scoreOf(grades) {
+  if (!grades.length) return 0;
+  const pts = grades.reduce((s, g) => s + (g.verdict === "right" ? 1 : g.verdict === "partial" ? 0.5 : 0), 0);
+  return Math.round(pts / grades.length * 100) / 100;
+}
+function normalizePractice(p) {
+  if (p.files?.length) return p;
+  return {
+    ...p,
+    files: [{ path: p.file, original: p.original, holed: p.holed, attempt: p.attempt }],
+    holes: p.holes.map((h) => ({ ...h, file: h.file ?? p.file }))
+  };
+}
+var TRIVIAL = /^\s*(?:$|\/\/|#|\*|\/\*|\*\/|[{}()\[\];,]+\s*$|import\b|from\s+\S+\s+import\b|export\s*\{|@\w+|"""|'\'\'\')/;
+function cleanHoles(raw, lineCount, lines) {
+  const holes = raw.map((h) => h).map((o) => ({
+    startLine: num(o.startLine) ?? 0,
+    endLine: num(o.endLine) ?? num(o.startLine) ?? 0,
+    intent: str(o.intent, 500),
+    hints: arr(o.hints).map((x) => str(x, 500)).filter(Boolean).slice(0, 3)
+  })).filter((h) => h.startLine >= 1 && h.endLine >= h.startLine && h.endLine <= lineCount).filter((h) => !lines || lines.slice(h.startLine - 1, h.endLine).filter((l) => !TRIVIAL.test(l)).length >= Math.min(2, h.endLine - h.startLine + 1)).sort((a, b) => a.startLine - b.startLine);
+  const out = [];
+  for (const h of holes) {
+    const prev = out[out.length - 1];
+    if (prev && h.startLine <= prev.endLine) continue;
+    out.push({ id: out.length + 1, ...h });
+  }
+  return out;
+}
+var COMMENT = {
+  python: "#",
+  bash: "#",
+  yaml: "#",
+  toml: "#",
+  ruby: "#",
+  r: "#",
+  elixir: "#",
+  make: "#",
+  docker: "#",
+  hcl: "#",
+  ini: ";",
+  sql: "--",
+  lua: "--",
+  html: "<!--",
+  xml: "<!--",
+  markdown: "<!--",
+  css: "/*",
+  scss: "//",
+  jinja: "{#"
+};
+var CLOSE = { "<!--": " -->", "/*": " */", "{#": " #}" };
+function applyHoles(original, holes, lang) {
+  const lines = original.split("\n");
+  const open = COMMENT[lang] ?? "//";
+  const close = CLOSE[open] ?? "";
+  for (const h of [...holes].sort((a, b) => b.startLine - a.startLine)) {
+    const first = lines[h.startLine - 1] ?? "";
+    const indent = /^\s*/.exec(first)?.[0] ?? "";
+    const prev = lines.slice(0, h.startLine - 1).reverse().find((l) => l.trim());
+    const next = lines.slice(h.endLine).find((l) => l.trim());
+    const nextIndent = next === void 0 ? -1 : /^\s*/.exec(next)?.[0].length ?? 0;
+    const emptyBlock = lang === "python" && !!prev && /:\s*(#.*)?$/.test(prev) && nextIndent < indent.length;
+    lines.splice(h.startLine - 1, h.endLine - h.startLine + 1, `${indent}${emptyBlock ? "pass  " : ""}${open} HOLE ${h.id}: ${h.intent}${close}`);
+  }
+  return lines.join("\n");
+}
+
+// src/server/export.ts
+function lensMarkdown(l, ws) {
+  const out = [`# ${l.title}`, "", `> ${l.question}`, "", `Covers: ${l.files.map((f) => ws.rel(f)).join(", ")}`, ""];
+  if (l.tldr) out.push(`**TL;DR:** ${l.tldr}`, "");
+  if (l.whyItMatters) out.push(`*Why it matters:* ${l.whyItMatters}`, "");
+  if (l.summary) out.push(l.summary, "");
+  if (l.sketch) {
+    out.push("## Your take first", "", l.sketch, "");
+    if (l.differences?.length) out.push("### Differences", "", ...l.differences.map((d) => `- ${d}`), "");
+  }
+  if (l.concepts.length) out.push("## Concepts", "", ...l.concepts.map((c) => `- **${c.term}**: ${c.explain}${c.example ? ` *Example:* ${c.example}` : ""}`), "");
+  if (l.intuition) out.push("## Intuition", "", l.intuition, "");
+  if (l.trace) {
+    out.push("## Trace", "", `Input: \`${l.trace.input}\``, "", "| # | Line | State | Note |", "|---|---|---|---|");
+    l.trace.steps.forEach((s, i) => {
+      const state = Object.entries(s.state).map(([k, v]) => `${k}=${v}`).join(", ").replace(/\|/g, "\\|");
+      out.push(`| ${i + 1} | ${s.file ? ws.rel(s.file) : ""}${s.line ? `:${s.line}` : ""} | ${state} | ${s.note.replace(/\|/g, "\\|")} |`);
+    });
+    out.push("");
+  }
+  if (l.deepDives.length) {
+    out.push("## Deep dives", "");
+    for (const d of l.deepDives) {
+      const where = d.file ? ` (${ws.rel(d.file)}${d.startLine ? `:${d.startLine}-${d.endLine}` : d.line ? `:${d.line}` : ""})` : "";
+      out.push(`### ${d.title}${where}`, "", d.body, "");
+      if (d.pitfall) out.push(`> **Pitfall:** ${d.pitfall}`, "");
+      if (d.check) out.push(`<details><summary>Check yourself: ${d.check.q}</summary>
+
+${d.check.a}
+</details>`, "");
+    }
+  }
+  if (l.gotchas?.length) out.push("## Gotchas", "", ...l.gotchas.map((g) => `- ${g}`), "");
+  if (l.nextSteps?.length) out.push("## Read next", "", ...l.nextSteps.map((n) => `- \`${ws.rel(n.file)}\`: ${n.why}`), "");
+  return out.join("\n");
+}
+function quizMarkdown(q, ws) {
+  const out = [`# ${q.title}`, "", `Covers: ${q.files.map((f) => ws.rel(f)).join(", ")}`, ""];
+  const last = q.attempts[q.attempts.length - 1];
+  if (last) out.push(`Result: ${Math.round(last.score * 100)}% on ${last.at.slice(0, 16).replace("T", " ")}`, "");
+  q.questions.forEach((qq, i) => {
+    out.push(`## Q${i + 1}. ${qq.prompt}`, "");
+    const g = last?.grades.find((x) => x.qid === qq.id);
+    const a = last?.answers.find((x) => x.qid === qq.id);
+    if (a?.answer) out.push(`**Your answer** (${a.sure ? "sure" : "guess"}): ${a.answer}`, "");
+    if (g) out.push(`**Verdict:** ${g.verdict}. ${g.feedback}`, "", `**A good answer:** ${g.modelAnswer}`, "");
+  });
+  return out.join("\n");
+}
+
+// src/server/app.ts
+function createApi(store2, opts2 = {}) {
+  const api = new Hono();
+  const jobs = new Jobs(store2);
+  const sweep = () => {
+    try {
+      prune(store2);
+    } catch {
+    }
+  };
+  sweep();
+  if (opts2.pruneEveryMs) setInterval(sweep, opts2.pruneEveryMs).unref();
+  const graphs = /* @__PURE__ */ new Map();
+  const graphOf = (p) => {
+    const hit = graphs.get(p.id);
+    if (hit && Date.now() - hit.at < 6e4) return hit.g;
+    const g = new Workspace(p).graph();
+    graphs.set(p.id, { at: Date.now(), g });
+    return g;
+  };
+  const hubs = (p) => graphOf(p).nodes.filter((n) => n.fanIn > 0).sort((a, b) => b.fanIn - a.fanIn).map((n) => n.path);
+  const offline = () => new Learn(store2, { name: "none", complete: async () => "" });
+  let current = null;
+  const agent = () => current ??= makeAgent(store2.settings());
+  const fail = (c, status, error) => c.json({ error }, status);
+  const project = (c) => {
+    const p = store2.project(c.req.param("pid") ?? "");
+    if (!p) throw new HttpError(404, "project not found");
+    return p;
+  };
+  const startJob = (c, kind, p, work) => {
+    const a = agent();
+    if (!a.agent) return fail(c, 503, a.info.detail);
+    const learn = new Learn(store2, a.agent);
+    return c.json(jobs.start(kind, p.id, () => work(learn)), 202);
+  };
+  const body = async (c) => {
+    try {
+      return await c.req.json();
+    } catch {
+      throw new HttpError(400, "body must be JSON");
+    }
+  };
+  api.onError((err, c) => {
+    if (err instanceof HttpError) return c.json({ error: err.message }, err.status);
+    const msg = err instanceof Error ? err.message : String(err);
+    const status = /outside the project|bad ref|not a file|pick at least|already graded|write a few|ask a question|write something|no open weak|needs a file inside a git repo|no commits yet/.test(msg) ? 400 : /ENOENT|not found/.test(msg) ? 404 : 500;
+    return c.json({ error: msg }, status);
+  });
+  api.get("/health", (c) => c.json({ ok: true, home: store2.home, agent: agent().info }));
+  api.get("/lens-kinds", (c) => c.json(LENS_KINDS));
+  api.get("/settings", (c) => c.json({ settings: store2.settings(), agent: agent().info, home: store2.home }));
+  api.put("/settings", async (c) => {
+    const s = store2.saveSettings(await body(c));
+    current = null;
+    return c.json({ settings: s, agent: agent().info, home: store2.home });
+  });
+  api.get("/browse", (c) => {
+    const path2 = c.req.query("path") || homedir2();
+    if (!existsSync5(path2) || !statSync4(path2).isDirectory()) return fail(c, 404, "folder not found");
+    return c.json(browse(path2));
+  });
+  api.get("/jobs", (c) => c.json(jobs.history()));
+  api.get("/storage", (c) => c.json(usage(store2)));
+  api.get("/storage/items", (c) => c.json(items(store2)));
+  api.post("/storage/remove", async (c) => {
+    const body2 = await c.req.json().catch(() => ({ ids: [] }));
+    const ids = Array.isArray(body2.ids) ? body2.ids.filter((x) => typeof x === "string") : [];
+    return c.json({ ...remove(store2, ids), usage: usage(store2) });
+  });
+  api.post("/storage/prune", (c) => c.json({ ...prune(store2), usage: usage(store2) }));
+  api.get("/jobs/:id", (c) => {
+    const j = jobs.get(c.req.param("id"));
+    return j ? c.json(j) : fail(c, 404, "job not found");
+  });
+  api.get("/projects", (c) => c.json(store2.projects()));
+  api.post("/projects", async (c) => {
+    const { root, name } = await body(c);
+    if (!root || !existsSync5(root) || !statSync4(root).isDirectory()) return fail(c, 400, "not a folder");
+    return c.json(store2.openProject(root, name));
+  });
+  api.get("/projects/:pid", (c) => {
+    const p = project(c);
+    return c.json({ ...p, running: jobs.running(p.id) });
+  });
+  api.patch("/projects/:pid", async (c) => {
+    const p = project(c);
+    const patch = await body(c);
+    for (const ctx of patch.contexts ?? []) {
+      if (!existsSync5(ctx) || !statSync4(ctx).isDirectory()) return fail(c, 400, `not a folder: ${ctx}`);
+    }
+    return c.json(store2.updateProject(p.id, patch));
+  });
+  api.delete("/projects/:pid", (c) => {
+    store2.forgetProject(project(c).id);
+    return c.json({ ok: true });
+  });
+  api.get("/projects/:pid/tree", (c) => c.json(new Workspace(project(c)).tree()));
+  api.get("/projects/:pid/file", (c) => c.json(new Workspace(project(c)).read(c.req.query("path") ?? "")));
+  api.get("/projects/:pid/repos", (c) => c.json(new Workspace(project(c)).repos()));
+  api.get("/projects/:pid/refs", (c) => c.json(new Workspace(project(c)).refs(c.req.query("repo") || void 0)));
+  api.get("/projects/:pid/diff", (c) => {
+    const spec = { repo: c.req.query("repo") || void 0, base: c.req.query("base") || "HEAD", head: c.req.query("head") ?? "" };
+    return c.json(new Workspace(project(c)).diff(spec));
+  });
+  api.get("/projects/:pid/lenses", (c) => c.json(store2.list(project(c).id, "lenses")));
+  api.get("/projects/:pid/lenses/:id", (c) => {
+    const p = project(c);
+    const l = store2.get(p.id, "lenses", c.req.param("id"));
+    if (!l) return fail(c, 404, "lens not found");
+    const ws = new Workspace(p);
+    const changed = l.fileHashes ? l.files.filter((f) => ws.hash(f) !== l.fileHashes[f]) : [];
+    return c.json({ ...l, changed });
+  });
+  api.post("/projects/:pid/lenses", async (c) => {
+    const p = project(c);
+    const req = await body(c);
+    return startJob(c, "lens", p, (l) => l.lens(p, { ...req, files: req.files ?? [] }));
+  });
+  api.post("/projects/:pid/lenses/:id/refresh", (c) => {
+    const p = project(c);
+    const id = c.req.param("id");
+    if (!store2.get(p.id, "lenses", id)) return fail(c, 404, "lens not found");
+    return startJob(c, "lens", p, (l) => l.lens(p, { files: [], kind: "", refreshOf: id }));
+  });
+  api.get("/projects/:pid/lenses/:id/export", (c) => {
+    const p = project(c);
+    const l = store2.get(p.id, "lenses", c.req.param("id"));
+    if (!l) return fail(c, 404, "lens not found");
+    return download(c, `${slug(l.title)}.md`, lensMarkdown(l, new Workspace(p)));
+  });
+  api.delete("/projects/:pid/lenses/:id", (c) => c.json({ ok: store2.archive(project(c).id, "lenses", c.req.param("id")) }));
+  api.get("/projects/:pid/quizzes", (c) => c.json(store2.list(project(c).id, "quizzes")));
+  api.get("/projects/:pid/quizzes/:id", (c) => {
+    const q = store2.get(project(c).id, "quizzes", c.req.param("id"));
+    return q ? c.json(q) : fail(c, 404, "quiz not found");
+  });
+  api.post("/projects/:pid/quizzes", async (c) => {
+    const p = project(c);
+    const req = await body(c);
+    return startJob(c, "quiz", p, (l) => l.quiz(p, { ...req, files: req.files ?? [] }));
+  });
+  api.post("/projects/:pid/quizzes/:id/attempts", async (c) => {
+    const p = project(c);
+    const { answers } = await body(c);
+    const id = c.req.param("id");
+    if (!store2.get(p.id, "quizzes", id)) return fail(c, 404, "quiz not found");
+    return startJob(c, "grade", p, (l) => l.grade(p, id, answers ?? []));
+  });
+  api.delete("/projects/:pid/quizzes/:id", (c) => c.json({ ok: store2.archive(project(c).id, "quizzes", c.req.param("id")) }));
+  api.get("/projects/:pid/quizzes/:id/export", (c) => {
+    const p = project(c);
+    const q = store2.get(p.id, "quizzes", c.req.param("id"));
+    if (!q) return fail(c, 404, "quiz not found");
+    return download(c, `${slug(q.title)}.md`, quizMarkdown(q, new Workspace(p)));
+  });
+  api.get("/projects/:pid/practice", (c) => c.json(store2.list(project(c).id, "practice")));
+  api.get("/projects/:pid/practice/:id", (c) => {
+    const x = store2.get(project(c).id, "practice", c.req.param("id"));
+    return x ? c.json(normalizePractice(x)) : fail(c, 404, "practice not found");
+  });
+  api.post("/projects/:pid/practice", async (c) => {
+    const p = project(c);
+    const req = await body(c);
+    return startJob(c, "practice", p, (l) => l.practice(p, req));
+  });
+  api.put("/projects/:pid/practice/:id/attempt", async (c) => {
+    const p = project(c);
+    const { text: text2, file } = await body(c);
+    return c.json(offline().saveAttempt(p, c.req.param("id"), text2 ?? "", file));
+  });
+  api.post("/projects/:pid/practice/:id/review", (c) => {
+    const p = project(c);
+    const id = c.req.param("id");
+    if (!store2.get(p.id, "practice", id)) return fail(c, 404, "practice not found");
+    return startJob(c, "review", p, (l) => l.review(p, id));
+  });
+  api.delete("/projects/:pid/practice/:id", (c) => c.json({ ok: store2.archive(project(c).id, "practice", c.req.param("id")) }));
+  api.get("/projects/:pid/progress", (c) => {
+    const p = project(c);
+    return c.json(offline().progress(p));
+  });
+  api.post("/projects/:pid/estimate", async (c) => {
+    const { files } = await body(c);
+    return c.json(offline().estimate(project(c), files ?? []));
+  });
+  const crud = (name, col, view = (x) => x) => {
+    api.get(`/projects/:pid/${name}`, (c) => c.json(store2.list(project(c).id, col).map((x) => view(x))));
+    api.get(`/projects/:pid/${name}/:id`, (c) => {
+      const x = store2.get(project(c).id, col, c.req.param("id"));
+      return x ? c.json(view(x)) : fail(c, 404, `${name} item not found`);
+    });
+    api.delete(`/projects/:pid/${name}/:id`, (c) => c.json({ ok: store2.archive(project(c).id, col, c.req.param("id")) }));
+  };
+  const withPreview = (card) => ({ ...card, next: previewCard(card) });
+  api.get("/projects/:pid/cards/due", (c) => c.json(dueCards(store2, project(c).id).map(withPreview)));
+  crud("cards", "cards");
+  api.post("/projects/:pid/cards", async (c) => {
+    const p = project(c);
+    const b = await body(c);
+    if (!b.front?.trim() || !b.back?.trim()) return fail(c, 400, "a card needs a front and a back");
+    const ws = new Workspace(p);
+    const file = b.file ? ws.guard(b.file) : void 0;
+    const kind = b.kind === "concept" || b.kind === "miss" ? b.kind : "own";
+    return c.json(store2.put(p.id, "cards", makeCard(p.id, { kind, front: b.front.trim(), back: b.back.trim(), file, line: b.line, source: b.source })));
+  });
+  api.post("/projects/:pid/cards/:id/review", async (c) => {
+    const p = project(c);
+    const card = store2.get(p.id, "cards", c.req.param("id"));
+    if (!card) return fail(c, 404, "card not found");
+    const { rating } = await body(c);
+    if (!["again", "hard", "good", "easy"].includes(rating)) return fail(c, 400, "rating must be again, hard, good or easy");
+    return c.json(store2.put(p.id, "cards", rateCard(card, rating)));
+  });
+  api.patch("/projects/:pid/cards/:id", async (c) => {
+    const p = project(c);
+    const card = store2.get(p.id, "cards", c.req.param("id"));
+    if (!card) return fail(c, 404, "card not found");
+    const b = await body(c);
+    if (b.front?.trim()) card.front = b.front.trim().slice(0, 2e3);
+    if (b.back?.trim()) card.back = b.back.trim().slice(0, 4e3);
+    if (typeof b.suspended === "boolean") card.suspended = b.suspended;
+    return c.json(store2.put(p.id, "cards", card));
+  });
+  api.get("/projects/:pid/misconceptions", (c) => {
+    const p = project(c);
+    return c.json(c.req.query("all") ? store2.list(p.id, "misconceptions") : openMisconceptions(store2, p.id));
+  });
+  api.post("/projects/:pid/misconceptions/:id/resolve", (c) => {
+    const p = project(c);
+    const m = store2.get(p.id, "misconceptions", c.req.param("id"));
+    if (!m) return fail(c, 404, "not found");
+    m.resolvedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return c.json(store2.put(p.id, "misconceptions", m));
+  });
+  api.delete("/projects/:pid/misconceptions/:id", (c) => c.json({ ok: store2.archive(project(c).id, "misconceptions", c.req.param("id")) }));
+  crud("teachbacks", "teachbacks");
+  api.post("/projects/:pid/teachbacks", async (c) => {
+    const p = project(c);
+    const req = await body(c);
+    return startJob(c, "teachback", p, (l) => l.teachback(p, { files: req.files ?? [], text: req.text ?? "" }));
+  });
+  crud("threads", "threads");
+  api.post("/projects/:pid/threads", async (c) => {
+    const p = project(c);
+    const req = await body(c);
+    return startJob(c, "tutor", p, (l) => l.startThread(p, { files: req.files ?? [], text: req.text ?? "" }));
+  });
+  api.post("/projects/:pid/threads/:id/messages", async (c) => {
+    const p = project(c);
+    const id = c.req.param("id");
+    if (!store2.get(p.id, "threads", id)) return fail(c, 404, "thread not found");
+    const req = await body(c);
+    return startJob(c, "tutor", p, (l) => l.tutorReply(p, id, req.text ?? "", !!req.tell));
+  });
+  crud("walks", "walks");
+  api.post("/projects/:pid/walks", async (c) => {
+    const p = project(c);
+    const req = await body(c);
+    return startJob(c, "walk", p, (l) => l.walk(p, req));
+  });
+  api.post("/projects/:pid/walks/:id/blocks/:i", async (c) => {
+    const p = project(c);
+    const id = c.req.param("id");
+    if (!store2.get(p.id, "walks", id)) return fail(c, 404, "walkthrough not found");
+    const { answer } = await body(c);
+    return startJob(c, "walkcheck", p, (l) => l.walkcheck(p, id, Number(c.req.param("i")), answer ?? ""));
+  });
+  const huntView = (h) => h.grade ? h : { ...h, planted: h.planted.map(() => null) };
+  crud("hunts", "hunts", huntView);
+  api.post("/projects/:pid/hunts", async (c) => {
+    const p = project(c);
+    const req = await body(c);
+    return startJob(c, "hunt", p, (l) => l.hunt(p, req));
+  });
+  api.put("/projects/:pid/hunts/:id/marks", async (c) => {
+    const p = project(c);
+    const { marks } = await body(c);
+    return c.json(huntView(offline().saveMarks(p, c.req.param("id"), marks ?? [])));
+  });
+  api.post("/projects/:pid/hunts/:id/grade", (c) => {
+    const p = project(c);
+    const id = c.req.param("id");
+    if (!store2.get(p.id, "hunts", id)) return fail(c, 404, "bug hunt not found");
+    return startJob(c, "huntgrade", p, (l) => l.huntgrade(p, id));
+  });
+  api.get("/projects/:pid/graph", (c) => c.json(graphOf(project(c))));
+  api.get("/projects/:pid/glossary", (c) => c.json(glossary(store2, project(c).id)));
+  const pathView = (x) => ({ ...x, done: pathDone(store2, x) });
+  crud("paths", "paths", pathView);
+  api.post("/projects/:pid/paths", async (c) => {
+    const p = project(c);
+    const { goal } = await body(c);
+    return startJob(c, "path", p, (l) => l.path(p, { goal, hubs: hubs(p) }));
+  });
+  api.patch("/projects/:pid/paths/:id", async (c) => {
+    const p = project(c);
+    const x = store2.get(p.id, "paths", c.req.param("id"));
+    if (!x) return fail(c, 404, "path not found");
+    const b = await body(c);
+    if (b.title?.trim()) x.title = b.title.trim().slice(0, 120);
+    if (Array.isArray(b.stops)) {
+      const ws = new Workspace(p);
+      x.stops = b.stops.filter((s) => s && Array.isArray(s.files)).map((s) => ({ ...s, files: s.files.map((f) => ws.guard(f)) }));
+    }
+    return c.json(pathView(store2.put(p.id, "paths", x)));
+  });
+  api.get("/projects/:pid/notes", (c) => {
+    const file = c.req.query("file");
+    const list = store2.list(project(c).id, "notes");
+    return c.json(file ? list.filter((n) => n.file === file) : list);
+  });
+  api.post("/projects/:pid/notes", async (c) => {
+    const p = project(c);
+    const b = await body(c);
+    if (!b.text?.trim()) return fail(c, 400, "a note needs text");
+    const note = {
+      id: newId(),
+      projectId: p.id,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      text: b.text.trim().slice(0, 8e3),
+      file: b.file ? new Workspace(p).guard(b.file) : void 0,
+      line: b.line,
+      lensId: b.lensId
+    };
+    return c.json(store2.put(p.id, "notes", note));
+  });
+  api.patch("/projects/:pid/notes/:id", async (c) => {
+    const p = project(c);
+    const n = store2.get(p.id, "notes", c.req.param("id"));
+    if (!n) return fail(c, 404, "note not found");
+    const b = await body(c);
+    if (b.text?.trim()) n.text = b.text.trim().slice(0, 8e3);
+    return c.json(store2.put(p.id, "notes", n));
+  });
+  api.delete("/projects/:pid/notes/:id", (c) => c.json({ ok: store2.archive(project(c).id, "notes", c.req.param("id")) }));
+  api.get("/projects/:pid/today", (c) => {
+    const p = project(c);
+    return c.json(today(store2, p, () => hubs(p)));
+  });
+  api.get("/projects/:pid/export", (c) => {
+    const p = project(c);
+    const all = { project: p, exportedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    for (const col of ["lenses", "quizzes", "practice", "cards", "misconceptions", "teachbacks", "threads", "walks", "hunts", "paths", "notes"]) {
+      all[col] = store2.list(p.id, col);
+    }
+    return download(c, `learnforge-${p.id}.json`, JSON.stringify(all, null, 2), "application/json");
+  });
+  return api;
+}
+var slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "export";
+function download(c, name, text2, type = "text/markdown; charset=utf-8") {
+  return c.body(text2, 200, { "content-type": type, "content-disposition": `attachment; filename="${name}"` });
+}
+var HttpError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+};
+
+// src/cli.ts
+var HELP = `learnforge - understand any codebase
+
+Usage: learnforge [folder] [options]
+
+  folder           Folder to open (default: show the project list)
+  --port <n>       Port (default 4711, or LEARNFORGE_PORT)
+  --host <addr>    Address to bind (default 127.0.0.1)
+  --no-open        Do not open the browser
+  --demo           Try it with a small sample repo and canned answers (no model, temp data)
+  -h, --help       Show this help
+
+Data lives in ~/.learnforge (LEARNFORGE_HOME). Your folders are never written. Old archive
+and cache entries are cleaned up on their own (Settings > Storage).
+Model: the claude, codex or copilot CLI if installed (their own login), else ANTHROPIC_API_KEY.`;
+function parseArgs(argv) {
+  const out = { folder: "", port: Number(process.env.LEARNFORGE_PORT) || 4711, host: "127.0.0.1", open: true, demo: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") {
+      console.log(HELP);
+      process.exit(0);
+    } else if (a === "--port") out.port = Number(argv[++i]);
+    else if (a === "--host") out.host = argv[++i];
+    else if (a === "--no-open") out.open = false;
+    else if (a === "--demo") out.demo = true;
+    else if (!a.startsWith("-")) out.folder = a;
+    else {
+      console.error(`unknown option: ${a}
+
+${HELP}`);
+      process.exit(2);
+    }
+  }
+  return out;
+}
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript",
+  ".css": "text/css",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".json": "application/json",
+  ".ico": "image/x-icon",
+  ".wasm": "application/wasm"
+};
+function webDir() {
+  const here = dirname3(fileURLToPath(import.meta.url));
+  for (const d of [join8(here, "web"), join8(here, "..", "dist", "web")]) if (existsSync6(join8(d, "index.html"))) return d;
+  return null;
+}
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn2(cmd, args, { stdio: "ignore", detached: true }).on("error", () => {
+    }).unref();
+  } catch {
+  }
+}
+function demoDir() {
+  const here = dirname3(fileURLToPath(import.meta.url));
+  for (const d of [join8(here, "..", "demo", "sample"), join8(here, "demo", "sample")]) if (existsSync6(d)) return d;
+  return null;
+}
+var opts = parseArgs(process.argv.slice(2));
+if (opts.demo) {
+  const sample = demoDir();
+  if (!sample) {
+    console.error("demo sample not found in this install");
+    process.exit(2);
+  }
+  process.env.LEARNFORGE_AGENT = "fake";
+  process.env.LEARNFORGE_HOME = join8(tmpdir3(), "learnforge-demo");
+  process.env.LEARNFORGE_FAKE_DELAY_MS ??= "1500";
+  opts.folder = sample;
+}
+var store = new Store();
+var app = new Hono2();
+app.route("/api", createApi(store, { pruneEveryMs: 6 * 36e5 }));
+var web = webDir();
+app.get("*", (c) => {
+  if (!web) return c.text("Web app not built. Run `npm run build`, or `npm run dev` and open http://localhost:5173.", 503);
+  const rel = decodeURIComponent(new URL(c.req.url).pathname).replace(/^\/+/, "");
+  const file = resolve4(web, rel);
+  const target = file.startsWith(web) && existsSync6(file) && statSync5(file).isFile() ? file : join8(web, "index.html");
+  const type = MIME[extname3(target)] ?? "application/octet-stream";
+  const cache = target.includes(`${join8(web, "assets")}`) ? "public, max-age=31536000, immutable" : "no-cache";
+  return c.body(readFileSync5(target), 200, { "content-type": type, "cache-control": cache });
+});
+var path = "/";
+if (opts.folder) {
+  const root = resolve4(opts.folder);
+  if (!existsSync6(root) || !statSync5(root).isDirectory()) {
+    console.error(`not a folder: ${root}`);
+    process.exit(2);
+  }
+  path = `/p/${store.openProject(root).id}/today`;
+}
+serve({ fetch: app.fetch, port: opts.port, hostname: opts.host }, (info) => {
+  const url = `http://${opts.host === "0.0.0.0" ? "localhost" : opts.host}:${info.port}${path}`;
+  console.log(`learnforge running at ${url}
+data: ${store.home}
+Ctrl+C to stop.`);
+  if (opts.open && web) openBrowser(url);
+});