learn-loops 0.1.0 → 0.4.0

package/dist/flows/learn.js

@@ -1,12 +1,16 @@
 import * as p from "@clack/prompts";
 import { join } from "node:path";
 import { askJson, askText } from "../llm.js";
+import { PERSONAS } from "../prompts.js";
 import { bigPicturePrompt, deepLessonPrompt, mapPrompt, outlinePrompt, reexplainPrompt, surveyLessonPrompt } from "../prompts.js";
-import { lessonMarkdown, mapMarkdown, writeIndex } from "../markdown.js";
-import { createTopic, listCategories, saveTopic, slugify, writeText } from "../store.js";
+import { clean, lessonMarkdown, materializeFigures, mapMarkdown, mistakesMarkdown, nodeId, writeIndex } from "../markdown.js";
+import { renderDiagram } from "../diagram.js";
+import { addMistake, createTopic, listCategories, saveTopic, slugify, writeText } from "../store.js";
+import { recordActivity } from "../stats.js";
 import { addCards, isDue } from "../srs.js";
-import { bar, must, renderMd, t, withSpinner } from "../ui.js";
+import { bar, m, must, renderMd, t, withSpinner } from "../ui.js";
 import { reviewCards, runChecks, teachBack } from "./quiz.js";
+import { applicationChallenge, diagnose, predictThenReveal, socraticWarmup, thinkDeeper } from "./think.js";
 const str = (v, name) => {
     if (typeof v !== "string" || !v.trim())
         throw new Error(`missing string "${name}"`);
@@ -24,7 +28,7 @@ function validateMap(x) {
     }));
     return { overview: String(x.overview ?? ""), areas };
 }
-function validateLesson(x) {
+export function validateLesson(x) {
     const checks = (Array.isArray(x.checks) ? x.checks : []).map((c) => {
         if (!Array.isArray(c.options) || c.options.length < 2 || !Number.isInteger(c.answer) || c.answer < 0 || c.answer >= c.options.length)
             throw new Error("bad check options/answer");
@@ -37,6 +41,9 @@ function validateLesson(x) {
         teachBack: str(x.teachBack, "teachBack"),
         keyPoints: (Array.isArray(x.keyPoints) ? x.keyPoints : []).map(String),
         cards: (Array.isArray(x.cards) ? x.cards : []).filter((c) => c?.front && c?.back).map((c) => ({ front: String(c.front), back: String(c.back) })),
+        prediction: x.prediction?.scenario && x.prediction?.question && x.prediction?.outcome ? { scenario: String(x.prediction.scenario), question: String(x.prediction.question), outcome: String(x.prediction.outcome) } : undefined,
+        deeper: x.deeper?.question ? { question: String(x.deeper.question), considerations: (Array.isArray(x.deeper.considerations) ? x.deeper.considerations : []).map(String) } : undefined,
+        socratic: Array.isArray(x.socratic) ? x.socratic.filter((q) => q?.q).map((q) => ({ q: String(q.q), hint: String(q.hint ?? ""), idea: String(q.idea ?? "") })) : undefined,
     };
 }
 const validateOutline = (x) => {
@@ -58,7 +65,12 @@ export async function newTopic(profile, title) {
         message: `Brain dump: what do you already know (or think you know) about ${name}?`,
         placeholder: "anything — even guesses. Blank if nothing. This sets the starting point.",
     }));
+    const useCase = must(await p.text({
+        message: `Where do you hope to use ${name}? (a project, a job, a problem you have)`,
+        placeholder: "optional — examples will be drawn from this",
+    }));
     const topic = await createTopic(profile, name.trim(), category, prior.trim());
+    topic.state.useCase = useCase.trim() || undefined;
     await buildMap(profile, topic);
     return topic;
 }
@@ -81,6 +93,13 @@ export function printMap(topic) {
         a.concepts.forEach((c, j) => lines.push(`${t.dim(last ? "   " : "│  ")} ${t.dim(j === a.concepts.length - 1 ? "└─" : "├─")} ${c.name}`));
     });
     p.note(lines.join("\n"), `${topic.state.title} — the map`);
+    const edges = map.areas.flatMap((a) => a.prereqs.filter((q) => map.areas.some((x) => x.id === q)).map((q) => `  ${nodeId(q)} --> ${nodeId(a.id)}`));
+    if (edges.length) {
+        const flow = ["flowchart LR", ...map.areas.map((a) => `  ${nodeId(a.id)}["${clean(a.title)}"]`), ...edges].join("\n");
+        const art = renderDiagram(flow);
+        if (art)
+            p.note(art, "Suggested order (arrow = learn first)");
+    }
     p.log.info(t.dim(`Saved with mermaid diagrams: ${join(topic.dir, "map.md")}`));
 }
 /** Warm-up retrieval of older material before new learning (spacing + interleaving). */
@@ -96,23 +115,30 @@ async function warmUp(topic) {
         ],
     }));
     if (go)
-        await reviewCards([topic], 5);
+        await reviewCards([topic], 5, "due");
 }
 async function teach(ctx) {
     const { profile, topic } = ctx;
     const lesson = await withSpinner(`Preparing "${ctx.title}"...`, ctx.load);
     p.log.step(t.bold(t.accent(ctx.title)));
+    const extras = {};
+    // 0. Socratic mode: work toward the idea through leading questions first.
+    const socratic = ctx.deep && profile.socratic && lesson.socratic?.length ? lesson.socratic : undefined;
+    if (socratic)
+        extras.socratic = await socraticWarmup(socratic);
     // 1. Pretest: guessing before reading primes attention even when wrong.
-    if (lesson.primer) {
-        must(await p.text({ message: `${t.pink("Guess first")} — ${lesson.primer}`, placeholder: "a rough guess is fine (enter to skip)" }));
+    if (lesson.primer && !socratic) {
+        must(await p.text({ message: `${t.pink("Guess first")} — ${m(lesson.primer)}`, placeholder: "a rough guess is fine (enter to skip)" }));
     }
     // 2. The chunk, with an escape hatch.
+    if (socratic)
+        p.log.message(t.dim("Here's how the pieces fit together:"));
     console.log(renderMd(lesson.markdown) + "\n");
     while (true) {
         const next = must(await p.select({
             message: "Does it make sense?",
             options: [
-                { value: "go", label: "Yes — quiz me" },
+                { value: "go", label: "Yes — continue" },
                 { value: "again", label: "Not really — explain it differently" },
             ],
         }));
@@ -122,13 +148,66 @@ async function teach(ctx) {
         console.log(renderMd(alt) + "\n");
         lesson.markdown += `\n\n---\n\n### Another angle\n\n${alt}`;
     }
-    // 3. Retrieval practice, then 4. teach-back.
-    const missed = await runChecks(lesson.checks);
-    const attempts = await teachBack(profile, ctx.title, lesson.teachBack, lesson.keyPoints);
-    const cards = [...lesson.cards, ...missed.map((m) => ({ front: m.q, back: `${m.options[m.answer]} — ${m.explain}` }))];
+    // 3. Predict-then-reveal.
+    if (ctx.deep && lesson.prediction)
+        extras.prediction = await predictThenReveal(lesson.prediction);
+    // 4. Retrieval practice with confidence.
+    const result = await runChecks(lesson.checks);
+    extras.missed = result.missed.map((m) => m.q);
+    for (const m of result.missed) {
+        const over = result.overconfident.includes(m);
+        addMistake(topic, { lesson: ctx.title, kind: over ? "overconfident" : "quiz", what: m.q, correction: `${m.options[m.answer]} — ${m.explain}` });
+    }
+    // 5. Teach-back, to a persona on deep lessons.
+    const persona = ctx.deep ? PERSONAS[Math.floor(Math.random() * PERSONAS.length)] : undefined;
+    extras.attempts = await teachBack(profile, ctx.title, lesson.teachBack, lesson.keyPoints, persona);
+    const last = extras.attempts.at(-1)?.grade;
+    if (last && last.score <= 1) {
+        for (const g of last.misconceptions.length ? last.misconceptions : last.missing.slice(0, 2)) {
+            addMistake(topic, { lesson: ctx.title, kind: "explanation", what: g, correction: last.feedback });
+        }
+    }
+    // 6. Stuck? Diagnose the mental model instead of repeating the lesson.
+    if (result.missed.length >= 2 || (last && last.score <= 1)) {
+        const go = must(await p.select({
+            message: "This one's tripping you up. Want me to find out why?",
+            options: [
+                { value: true, label: "Yes — diagnose it", hint: "2 quick questions" },
+                { value: false, label: "Skip" },
+            ],
+        }));
+        if (go) {
+            const m = await diagnose(profile, ctx.title, result.missed, last?.feedback ?? "");
+            if (m)
+                addMistake(topic, m);
+        }
+    }
+    // 7. Think deeper: trade-offs, failure modes, second-order effects.
+    if (ctx.deep) {
+        const rounds = await thinkDeeper(profile, topic.state, ctx.title, lesson.deeper);
+        if (rounds.length)
+            extras.deeper = rounds;
+        // 8. Personal connection.
+        const conn = must(await p.text({ message: `${t.pink("Where could you use this?")}`, placeholder: "a project, a decision, something you've seen (blank to skip)" })).trim();
+        if (conn) {
+            extras.connection = conn;
+            topic.state.connections = [...(topic.state.connections ?? []), conn].slice(-20);
+        }
+    }
+    // Cards: lesson cards plus everything missed; confident mistakes are flagged to resurface first.
+    const cards = [...lesson.cards, ...result.missed.map((m) => ({ front: m.q, back: `${m.options[m.answer]} — ${m.explain}` }))];
     const added = addCards(topic.state.cards, cards, ctx.title);
-    await writeText(join(topic.dir, ctx.file), lessonMarkdown(ctx.title, lesson, attempts, missed.map((m) => m.q)));
+    for (const m of result.overconfident) {
+        const c = topic.state.cards.find((x) => x.front.trim().toLowerCase() === m.q.trim().toLowerCase());
+        if (c)
+            c.flag = "overconfident";
+    }
+    await writeText(join(topic.dir, ctx.file), await materializeFigures(lessonMarkdown(ctx.title, lesson, extras), topic.dir, ctx.file));
+    await writeText(join(topic.dir, "mistakes.md"), mistakesMarkdown(topic));
     p.log.success(`${added} flashcard${added === 1 ? "" : "s"} added to your review queue ${t.dim("→ " + ctx.file)}`);
+    const streak = await recordActivity();
+    if (streak.message)
+        p.log.success(t.warn("🔥 ") + t.bold(streak.message));
 }
 const overTime = (start, profile) => (Date.now() - start) / 60_000 >= profile.minutesPerSession;
 export async function continueTopic(profile, topic) {
@@ -160,6 +239,7 @@ export async function continueTopic(profile, topic) {
             profile,
             topic,
             title: next.title,
+            deep: false,
             file: `survey/${next.id}.md`,
             load: () => askJson(profile, surveyLessonPrompt(profile, s, next), validateLesson),
         });
@@ -175,6 +255,10 @@ export async function continueTopic(profile, topic) {
         if (!area)
             return;
         const pr = s.progress[area.id];
+        if (pr.outline && pr.done.length >= pr.outline.length) {
+            p.log.info(t.dim(`${area.title} is already complete — pick another.`));
+            continue;
+        }
         if (!pr.outline) {
             pr.outline = await withSpinner(`Planning your deep dive into ${area.title}...`, () => askJson(profile, outlinePrompt(profile, s, area), validateOutline));
             await saveTopic(topic);
@@ -189,6 +273,7 @@ export async function continueTopic(profile, topic) {
                 profile,
                 topic,
                 title: l.title,
+                deep: true,
                 file: `deep/${area.id}/${String(i + 1).padStart(2, "0")}-${l.id}.md`,
                 load: () => askJson(profile, deepLessonPrompt(profile, s, area, l, doneTitles), validateLesson),
             });
@@ -199,6 +284,22 @@ export async function continueTopic(profile, topic) {
                 return;
         }
         p.log.success(t.ok(`You finished the deep dive on ${area.title}. 🎉`));
+        const take = must(await p.select({
+            message: "Test it on a real-world scenario with trade-offs?",
+            options: [
+                { value: true, label: "Yes — application challenge" },
+                { value: false, label: "Skip" },
+            ],
+        }));
+        if (take) {
+            const res = await applicationChallenge(profile, s, area, pr.outline.map((l) => l.title));
+            if (res) {
+                await writeText(join(topic.dir, "deep", area.id, "challenge.md"), `# Challenge — ${area.title}\n\n${res.scenario}\n\n**Task:** ${res.task}\n\n## My answer\n\n${res.answer.split("\n").map((l) => "> " + l).join("\n")}\n\n## Feedback\n\n${res.critique.feedback}\n\n${res.critique.blindSpots.map((b) => `- Overlooked: ${b}`).join("\n")}\n`);
+                const r = await recordActivity();
+                if (r.message)
+                    p.log.success(t.warn("🔥 ") + t.bold(r.message));
+            }
+        }
         const more = must(await p.select({ message: "Next?", options: [{ value: true, label: "Pick another area to go deep on" }, { value: false, label: "Stop here" }] }));
         if (!more)
             return;
@@ -224,7 +325,7 @@ async function pickArea(topic) {
         p.log.success("You've gone deep on every area. Review your cards to keep it fresh with `loops review`.");
         return null;
     }
-    const started = open.find((a) => s.progress[a.id].done.length > 0);
+    const started = open.find((a) => s.progress[a.id].done.length > 0) ?? open[0];
     const choice = must(await p.select({
         message: "Which area do you want to go deep on?",
         initialValue: started?.id,

package/dist/flows/onboard.js

@@ -98,13 +98,26 @@ export async function onboard(existing) {
             { value: "socratic", label: "Socratic — ask me questions" },
         ],
     }));
+    const socratic = must(await p.select({
+        message: "How should new ideas be introduced?",
+        initialValue: d?.socratic ?? false,
+        options: [
+            { value: false, label: "Explain, then quiz me", hint: "classic" },
+            { value: true, label: "Socratic — ask me leading questions first", hint: "slower, sticks better" },
+        ],
+    }));
+    const context = must(await p.text({
+        message: "What are you working on or hoping to use this for? (job, project, problem)",
+        initialValue: d?.context,
+        placeholder: "optional — examples will be drawn from this",
+    }));
     const minutesPerSession = must(await p.select({
         message: "How long is a typical study session?",
         initialValue: d?.minutesPerSession ?? 25,
         options: [10, 15, 25, 45, 60].map((m) => ({ value: m, label: `${m} min` })),
     }));
     const rootDir = must(await p.text({ message: "Where should your learning folders live?", initialValue: d?.rootDir ?? join(homedir(), "Learning").replace(homedir(), "~") }));
-    const profile = { name: name.trim(), provider, goal, level, minutesPerSession, styles, order, diagrams, challenge, tone, rootDir };
+    const profile = { name: name.trim(), provider, goal, level, minutesPerSession, styles, order, diagrams, challenge, tone, rootDir, socratic, context: context.trim() || undefined };
     await saveProfile(profile);
     p.outro(t.ok(`Profile saved. Nice to meet you, ${profile.name}!`));
     return profile;

package/dist/flows/quiz.js

@@ -1,8 +1,8 @@
 import * as p from "@clack/prompts";
 import { askJson } from "../llm.js";
-import { gradeLabel, gradePrompt } from "../prompts.js";
+import { gradeLabel, gradePrompt, personaPrompt } from "../prompts.js";
 import { schedule, isDue } from "../srs.js";
-import { must, t, withSpinner } from "../ui.js";
+import { m, must, t, withSpinner } from "../ui.js";
 import { saveTopic } from "../store.js";
 export function validateGrade(x) {
     const score = Number(x.score);
@@ -11,42 +11,93 @@ export function validateGrade(x) {
     const arr = (v) => (Array.isArray(v) ? v.map(String) : []);
     return { score: score, right: arr(x.right), missing: arr(x.missing), misconceptions: arr(x.misconceptions), feedback: String(x.feedback ?? ""), followUp: String(x.followUp ?? "") };
 }
-/** Multiple-choice checks. Returns the questions the learner got wrong. */
+/** Multiple-choice checks with a confidence rating, so confident mistakes are caught and flagged. */
 export async function runChecks(checks) {
-    const missed = [];
+    const res = { missed: [], overconfident: [], correct: 0, total: checks.length };
+    let sure = 0;
+    let sureRight = 0;
     for (const [i, c] of checks.entries()) {
-        const picked = must(await p.select({
-            message: `${t.accent(`Q${i + 1}/${checks.length}`)}  ${c.q}`,
-            options: c.options.map((o, idx) => ({ value: idx, label: o })),
+        // Models over-favour option A: shuffle what's shown, keep `c` untouched for logging.
+        const order = c.options.map((_, idx) => idx).sort(() => Math.random() - 0.5);
+        const shown = must(await p.select({
+            message: `${t.accent(`Q${i + 1}/${checks.length}`)}  ${m(c.q)}`,
+            options: order.map((orig, pos) => ({ value: pos, label: m(c.options[orig]) })),
         }));
-        if (picked === c.answer)
-            p.log.success(t.ok("Correct. ") + t.dim(c.explain));
+        const picked = order[shown];
+        const confidence = must(await p.select({
+            message: "How sure are you?",
+            options: [
+                { value: 1, label: "Guessing" },
+                { value: 2, label: "Not sure" },
+                { value: 3, label: "Pretty sure" },
+                { value: 4, label: "Certain" },
+            ],
+        }));
+        const right = picked === c.answer;
+        if (confidence >= 3) {
+            sure++;
+            if (right)
+                sureRight++;
+        }
+        if (right) {
+            res.correct++;
+            p.log.success(t.ok("Correct. ") + t.dim(m(c.explain)));
+        }
         else {
-            missed.push(c);
-            p.log.error(t.bad("Not quite. ") + `Answer: ${c.options[c.answer]}\n  ${t.dim(c.explain)}`);
+            res.missed.push(c);
+            if (confidence >= 3) {
+                res.overconfident.push(c);
+                p.log.error(t.bad("Wrong — and you were sure. ") + t.warn("Those are the most valuable mistakes to catch.") + `\n  Answer: ${m(c.options[c.answer])}\n  ${t.dim(m(c.explain))}`);
+            }
+            else
+                p.log.error(t.bad("Not quite. ") + `Answer: ${m(c.options[c.answer])}\n  ${t.dim(m(c.explain))}`);
         }
     }
-    return missed;
+    if (sure > 0 && checks.length > 1)
+        p.log.info(t.dim(`Calibration: right on ${sureRight} of ${sure} answers you were sure about.`));
+    return res;
 }
 export function showGrade(g) {
     const color = g.score >= 3 ? t.ok : g.score === 2 ? t.cyan : g.score === 1 ? t.warn : t.bad;
     const lines = [
         `${color(`${"●".repeat(g.score)}${"○".repeat(3 - g.score)} ${gradeLabel(g)}`)}`,
         "",
-        g.feedback,
-        ...g.right.map((r) => `${t.ok("✓")} ${r}`),
-        ...g.missing.map((r) => `${t.warn("△")} missing: ${r}`),
-        ...g.misconceptions.map((r) => `${t.bad("✗")} ${r}`),
+        m(g.feedback),
+        ...g.right.map((r) => `${t.ok("✓")} ${m(r)}`),
+        ...g.missing.map((r) => `${t.warn("△")} missing: ${m(r)}`),
+        ...g.misconceptions.map((r) => `${t.bad("✗")} ${m(r)}`),
     ];
     p.note(lines.join("\n"), "Feedback");
 }
-/** Feynman-style teach-back with one optional retry. */
-export async function teachBack(profile, title, prompt, keyPoints) {
+/**
+ * Feynman-style teach-back. With a persona, you explain to a character who then asks a follow-up
+ * question about your biggest gap; the whole exchange is graded. Without, you get one graded retry.
+ */
+export async function teachBack(profile, title, prompt, keyPoints, persona) {
+    if (persona) {
+        const first = must(await p.text({ message: `${t.pink("Explain it to " + persona.label)} — ${m(prompt)}`, placeholder: "in your own words (enter to submit, blank to skip)" })).trim();
+        if (!first)
+            return [];
+        let transcript = first;
+        try {
+            const turn = await withSpinner(`${persona.label[0].toUpperCase() + persona.label.slice(1)} is thinking...`, () => askJson(profile, personaPrompt(profile, persona, title, keyPoints, first), (x) => ({ reaction: String(x.reaction ?? ""), question: String(x.question ?? "") })));
+            p.log.message(`${t.pink(persona.label)}: ${m(turn.reaction)}\n${t.bold(m(turn.question))}`);
+            const second = must(await p.text({ message: "Your reply", placeholder: "answer their question (blank to skip)" })).trim();
+            if (second)
+                transcript += `\n\n[Follow-up: ${turn.question}]\n${second}`;
+        }
+        catch {
+            /* persona is a bonus; fall through to grading the first answer */
+        }
+        const grade = await withSpinner("Reading your explanation...", () => askJson(profile, gradePrompt(profile, title, prompt, keyPoints, transcript), validateGrade));
+        showGrade(grade);
+        return [{ answer: transcript, grade }];
+    }
     const attempts = [];
     let ask = prompt;
     for (let i = 0; i < 2; i++) {
         const answer = must(await p.text({
-            message: `${t.pink("In your own words")} — ${ask}`,
+            message: `${t.pink("In your own words")} — ${m(ask)}`,
             placeholder: "type your explanation (enter to submit, leave blank to skip)",
         })).trim();
         if (!answer)
@@ -69,14 +120,37 @@ export async function teachBack(profile, title, prompt, keyPoints) {
     }
     return attempts;
 }
-/** Spaced-repetition review: attempt recall, reveal, self-rate. */
-export async function reviewCards(topics, limit = 20) {
-    const due = topics.flatMap((tp) => tp.state.cards.filter((c) => isDue(c)).map((card) => ({ tp, card }))).sort(() => Math.random() - 0.5).slice(0, limit);
+/** Round-robin across sources so related cards aren't back-to-back (interleaving). Stable per source order. */
+export function interleave(items) {
+    const groups = new Map();
+    for (const it of items)
+        groups.set(it.card.source, [...(groups.get(it.card.source) ?? []), it]);
+    const queues = [...groups.values()].sort(() => Math.random() - 0.5);
+    const out = [];
+    while (queues.some((q) => q.length))
+        for (const q of queues)
+            if (q.length)
+                out.push(q.shift());
+    return out;
+}
+/** Weak spots first: confident mistakes, lapses, then overdue. */
+const weakness = (c) => (c.flag === "overconfident" ? 4 : 0) + c.lapses * 1.5 + (isDue(c) ? 2 : 0) + Math.random();
+export function pickCards(topics, limit, mode) {
+    const all = topics.flatMap((tp) => tp.state.cards.map((card) => ({ tp, card })));
+    const pool = mode === "due" ? all.filter((e) => isDue(e.card)) : all;
+    const flagged = pool.filter((e) => e.card.flag === "overconfident").sort(() => Math.random() - 0.5);
+    const rest = pool.filter((e) => e.card.flag !== "overconfident").sort((a, b) => weakness(b.card) - weakness(a.card));
+    const chosen = [...flagged, ...rest].slice(0, limit);
+    return [...chosen.filter((e) => e.card.flag === "overconfident"), ...interleave(chosen.filter((e) => e.card.flag !== "overconfident"))];
+}
+/** Spaced-repetition review (due cards) or an interleaved mixed quiz (any cards, weakest first). */
+export async function reviewCards(topics, limit = 20, mode = "due") {
+    const queue = pickCards(topics, limit, mode);
     let n = 0;
-    for (const { tp, card } of due) {
-        console.log(t.dim(`\n  ${tp.state.title} · ${card.source}`));
-        must(await p.text({ message: `${t.accent("Recall")}  ${card.front}`, placeholder: "type what you remember (enter to just think)" }));
-        p.log.info(`${t.bold("Answer:")} ${card.back}`);
+    for (const { tp, card } of queue) {
+        console.log(t.dim(`\n  ${tp.state.title} · ${card.source}${card.flag ? " · " + t.warn("you were sure and wrong here before") : ""}`));
+        must(await p.text({ message: `${t.accent("Recall")}  ${m(card.front)}`, placeholder: "type what you remember (enter to just think)" }));
+        p.log.info(`${t.bold("Answer:")} ${m(card.back)}`);
         const rating = must(await p.select({
             message: "How did that go?",
             options: [
@@ -90,7 +164,10 @@ export async function reviewCards(topics, limit = 20) {
         if (rating === "stop")
             break;
         const idx = tp.state.cards.findIndex((c) => c.id === card.id);
-        tp.state.cards[idx] = schedule(card, rating);
+        const next = schedule(card, rating);
+        if (card.flag && (rating === "good" || rating === "easy"))
+            delete next.flag; // earned its way out
+        tp.state.cards[idx] = next;
         await saveTopic(tp);
         n++;
     }

package/dist/flows/think.js

@@ -0,0 +1,120 @@
+import * as p from "@clack/prompts";
+import { askJson } from "../llm.js";
+import { LENSES, challengePrompt, critiquePrompt, deeperPrompt, diagnoseQuestionsPrompt, diagnoseResultPrompt } from "../prompts.js";
+import { m, must, renderMd, t, withSpinner } from "../ui.js";
+import { runChecks } from "./quiz.js";
+const arr = (v) => (Array.isArray(v) ? v.map(String) : []);
+const validateCritique = (x) => ({ strong: arr(x.strong), blindSpots: arr(x.blindSpots), pushback: String(x.pushback ?? ""), feedback: String(x.feedback ?? "") });
+function showCritique(c) {
+    p.note([m(c.feedback), "", ...c.strong.map((s) => `${t.ok("✓")} ${m(s)}`), ...c.blindSpots.map((s) => `${t.warn("△ overlooked:")} ${m(s)}`), ...(c.pushback ? ["", `${t.pink("Push back:")} ${m(c.pushback)}`] : [])].join("\n"), "Thinking check");
+}
+/**
+ * Trade-offs, failure modes, scale and second-order effects. Round one uses the lesson's own question;
+ * further rounds rotate through different lenses so the learner practises seeing a topic from many sides.
+ */
+export async function thinkDeeper(profile, s, title, seed, maxRounds = 3) {
+    const rounds = [];
+    let lensIdx = Math.floor(Math.random() * LENSES.length);
+    let current = seed ? { lens: "Think deeper", ...seed } : undefined;
+    for (let r = 0; r < maxRounds; r++) {
+        if (!current) {
+            const lens = LENSES[lensIdx % LENSES.length];
+            const q = await withSpinner(`Finding a new angle (${lens.label.toLowerCase()})...`, () => askJson(profile, deeperPrompt(profile, s, title, lens, rounds.map((x) => x.question)), (x) => ({ question: String(x.question), considerations: arr(x.considerations) })));
+            current = { lens: lens.label, ...q };
+        }
+        p.log.step(t.bold(t.accent(`Think deeper · ${current.lens}`)));
+        const answer = must(await p.text({ message: m(current.question), placeholder: "no single right answer: weigh both sides, name what could go wrong (blank to skip)" })).trim();
+        if (!answer)
+            break;
+        const c = await withSpinner("Weighing your reasoning...", () => askJson(profile, critiquePrompt(profile, title, current.question, current.considerations, answer), validateCritique));
+        showCritique(c);
+        rounds.push({ lens: current.lens, question: current.question, answer, feedback: c.feedback, blindSpots: c.blindSpots });
+        // Let them answer the pushback, which is the real second-order step.
+        if (c.pushback) {
+            const reply = must(await p.text({ message: `${t.pink("Your response to the push back?")}`, placeholder: "optional (blank to skip)" })).trim();
+            if (reply)
+                rounds[rounds.length - 1].answer += `\n\n[Push back: ${c.pushback}]\n${reply}`;
+        }
+        if (r === maxRounds - 1)
+            break;
+        lensIdx++;
+        const next = LENSES[lensIdx % LENSES.length];
+        const more = must(await p.select({
+            message: "Keep stretching your thinking?",
+            options: [
+                { value: true, label: `Another angle: ${next.label}` },
+                { value: false, label: "That's enough" },
+            ],
+        }));
+        if (!more)
+            break;
+        current = undefined;
+    }
+    return rounds;
+}
+/** End-of-area scenario with no single right answer: apply what you learned and weigh trade-offs. */
+export async function applicationChallenge(profile, s, area, covered) {
+    const ch = await withSpinner("Designing a real-world challenge...", () => askJson(profile, challengePrompt(profile, s, area, covered), (x) => ({ scenario: String(x.scenario), task: String(x.task), considerations: arr(x.considerations) })));
+    p.note(`${m(ch.scenario)}\n\n${t.bold("Your task:")} ${m(ch.task)}`, `Challenge · ${area.title}`);
+    const answer = must(await p.text({ message: "What would you do, and why? What could go wrong?", placeholder: "reason it through (blank to skip)" })).trim();
+    if (!answer)
+        return null;
+    const c = await withSpinner("Reviewing your reasoning...", () => askJson(profile, critiquePrompt(profile, area.title, ch.task, ch.considerations, answer), validateCritique));
+    showCritique(c);
+    return { ...ch, answer, critique: c };
+}
+/**
+ * When a learner keeps missing, find the mental model that's wrong instead of repeating the lesson.
+ * Returns the logged mistake (with the learner's corrected idea in their own words).
+ */
+export async function diagnose(profile, title, missed, explanationFeedback) {
+    const questions = await withSpinner("Working out where the confusion is...", () => askJson(profile, diagnoseQuestionsPrompt(profile, title, missed.map((m) => m.q), explanationFeedback), (x) => arr(x.questions).slice(0, 2)));
+    const qa = [];
+    for (const q of questions) {
+        const a = must(await p.text({ message: `${t.pink("Quick question")} — ${m(q)}`, placeholder: "just say what you picture or believe (blank to skip)" })).trim();
+        qa.push({ q, a });
+    }
+    const res = await withSpinner("Finding the misconception...", () => askJson(profile, diagnoseResultPrompt(profile, title, qa, missed.map((m) => m.q)), (x) => {
+        const rt = x.retest;
+        if (!rt || !Array.isArray(rt.options) || !Number.isInteger(rt.answer) || rt.answer < 0 || rt.answer >= rt.options.length)
+            throw new Error("bad retest");
+        return {
+            misconception: String(x.misconception),
+            reteach: String(x.reteach),
+            retest: { q: String(rt.q), options: rt.options.map(String), answer: rt.answer, explain: String(rt.explain ?? "") },
+        };
+    }));
+    p.note(`${t.warn("Likely snag:")} ${m(res.misconception)}`, "Diagnosis");
+    console.log(renderMd(res.reteach) + "\n");
+    await runChecks([res.retest]);
+    const inMyWords = must(await p.text({ message: `${t.pink("Say the corrected idea in your own words")}`, placeholder: "one or two sentences (blank to skip)" })).trim();
+    return {
+        lesson: title,
+        kind: "diagnosis",
+        what: res.misconception,
+        correction: res.reteach.split("\n").find((l) => l.trim() && !l.startsWith("#") && !l.startsWith("`")) ?? res.misconception,
+        inMyWords: inMyWords || undefined,
+    };
+}
+/** Socratic opener: leading questions the learner works through before the explanation. */
+export async function socraticWarmup(items) {
+    p.log.message(t.dim("Socratic mode: work toward the idea yourself first. Answers needn't be right."));
+    const out = [];
+    for (const [i, item] of items.entries()) {
+        let answer = must(await p.text({ message: `${t.pink(`${i + 1}/${items.length}`)}  ${m(item.q)}`, placeholder: "think out loud (type ? for a hint, blank to skip)" })).trim();
+        if (answer === "?") {
+            p.log.info(`${t.warn("Hint:")} ${m(item.hint)}`);
+            answer = must(await p.text({ message: item.q, placeholder: "try again with the hint (blank to skip)" })).trim();
+        }
+        p.log.message(`${t.accent("→")} ${m(item.idea)}`);
+        out.push({ q: item.q, answer });
+    }
+    return out;
+}
+/** Predict-then-reveal: a wrong guess followed by the truth is memorable. */
+export async function predictThenReveal(pred) {
+    p.note(m(pred.scenario), t.pink("Predict"));
+    const guess = must(await p.text({ message: m(pred.question), placeholder: "commit to a guess before the reveal (blank to skip)" })).trim();
+    p.log.message(`${t.accent("Reveal:")} ${m(pred.outcome)}`);
+    return guess;
+}

package/dist/llm.js

@@ -47,13 +47,24 @@ export async function complete(provider, prompt, timeoutMs = 240_000) {
         await rm(dir, { recursive: true, force: true });
     }
 }
+/**
+ * Models often forget to double LaTeX backslashes inside JSON strings. `\theta` would silently parse as a
+ * tab + "heta", `\nabla` as newline + "abla", `\frac` as form feed + "rac". Double the backslash of any
+ * known command that collides with a JSON escape, and any lone backslash that isn't a valid escape at all.
+ */
+const COLLIDING = "theta|tau|times|text|textbf|textit|textrm|tan|tanh|tilde|to|top|triangle|therefore|tfrac|thinspace|frac|forall|flat|beta|bar|begin|boldsymbol|bot|binom|big|bigg|Big|Bigg|bmod|bullet|bigcup|bigcap|bigoplus|bf|rho|right|rightarrow|rangle|rbrace|rceil|rfloor|rm|nabla|neq|nu|ne|not|notin|newcommand|ni|neg|nleq|ngeq|nmid|nearrow";
+export function repairLatexEscapes(json) {
+    const re = new RegExp(`\\\\\\\\|\\\\(?:(?=(?:${COLLIDING})(?![a-zA-Z]))|u(?![0-9a-fA-F]{4})|(?![\\\\"/bfnrtu]))`, "g");
+    return json.replace(re, (m) => (m === "\\\\" ? m : "\\\\" + m.slice(1)));
+}
 export function extractJson(text) {
-    const cleaned = text.replace(/```(?:json)?/gi, "");
-    const start = cleaned.indexOf("{");
-    const end = cleaned.lastIndexOf("}");
+    // Slice between the outermost braces; an outer ```json fence falls outside them. Don't strip
+    // backticks globally: lesson markdown inside the JSON contains ```mermaid fences.
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
     if (start === -1 || end <= start)
         throw new Error("no JSON object in model output");
-    return JSON.parse(cleaned.slice(start, end + 1));
+    return JSON.parse(repairLatexEscapes(text.slice(start, end + 1)));
 }
 /** Ask for JSON, validate it, and retry once telling the model what was wrong. */
 export async function askJson(profile, prompt, validate) {