learn-loops 0.0.0-stage → 0.4.1

package/dist/flows/learn.js

@@ -0,0 +1,344 @@
+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 { 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, 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}"`);
+    return v;
+};
+function validateMap(x) {
+    if (!Array.isArray(x.areas) || x.areas.length < 3)
+        throw new Error("need at least 3 areas");
+    const areas = x.areas.map((a, i) => ({
+        id: slugify(a.id ?? a.title ?? `area-${i}`),
+        title: str(a.title, "title"),
+        summary: String(a.summary ?? ""),
+        prereqs: Array.isArray(a.prereqs) ? a.prereqs.map((s) => slugify(String(s))) : [],
+        concepts: (Array.isArray(a.concepts) ? a.concepts : []).map((c) => ({ name: str(c.name, "concept"), blurb: String(c.blurb ?? "") })),
+    }));
+    return { overview: String(x.overview ?? ""), areas };
+}
+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");
+        return { q: str(c.q, "q"), options: c.options.map(String), answer: c.answer, explain: String(c.explain ?? "") };
+    });
+    return {
+        primer: String(x.primer ?? ""),
+        markdown: str(x.markdown, "markdown"),
+        checks,
+        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) => {
+    if (!Array.isArray(x.lessons) || !x.lessons.length)
+        throw new Error("no lessons");
+    return x.lessons.map((l, i) => ({ id: slugify(l.id ?? l.title ?? `l${i}`), title: str(l.title, "title"), objective: String(l.objective ?? "") }));
+};
+export async function newTopic(profile, title) {
+    p.intro(t.bold(t.accent(" New topic ")));
+    const name = title ?? must(await p.text({ message: "What do you want to learn?", placeholder: "e.g. How databases work, Music theory, Game theory", validate: (v) => (v?.trim() ? undefined : "Tell me something!") }));
+    const cats = await listCategories(profile);
+    let category = "general";
+    const choice = must(await p.select({
+        message: "Which folder should this live in?",
+        options: [...cats.map((c) => ({ value: c, label: c })), { value: "__new", label: t.accent("+ New folder") }],
+    }));
+    category = choice === "__new" ? must(await p.text({ message: "Folder name", placeholder: "e.g. programming, science, languages", validate: (v) => (v?.trim() ? undefined : "Required") })) : choice;
+    const prior = must(await p.text({
+        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;
+}
+async function buildMap(profile, topic) {
+    topic.state.map = await withSpinner("Mapping the territory...", () => askJson(profile, mapPrompt(profile, topic.state.title, topic.state.priorKnowledge), validateMap));
+    topic.state.phase = "survey";
+    for (const a of topic.state.map.areas)
+        topic.state.progress[a.id] ??= { surveyed: false, done: [] };
+    await writeText(join(topic.dir, "map.md"), mapMarkdown(topic));
+    await writeIndex(topic);
+    await saveTopic(topic);
+    printMap(topic);
+}
+export function printMap(topic) {
+    const map = topic.state.map;
+    const lines = [t.italic(map.overview), ""];
+    map.areas.forEach((a, i) => {
+        const last = i === map.areas.length - 1;
+        lines.push(`${t.accent(last ? "└─" : "├─")} ${t.bold(a.title)}  ${t.dim(a.summary)}`);
+        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). */
+async function warmUp(topic) {
+    const due = topic.state.cards.filter((c) => isDue(c)).length;
+    if (!due)
+        return;
+    const go = must(await p.select({
+        message: `${due} card${due > 1 ? "s are" : " is"} due. Start with a quick warm-up? (recalling old stuff first makes new stuff stick)`,
+        options: [
+            { value: true, label: "Warm up (5 cards)" },
+            { value: false, label: "Skip" },
+        ],
+    }));
+    if (go)
+        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 && !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 — continue" },
+                { value: "again", label: "Not really — explain it differently" },
+            ],
+        }));
+        if (next === "go")
+            break;
+        const alt = await withSpinner("Finding another angle...", () => askText(profile, reexplainPrompt(profile, topic.state.title, ctx.title, lesson.markdown)));
+        console.log(renderMd(alt) + "\n");
+        lesson.markdown += `\n\n---\n\n### Another angle\n\n${alt}`;
+    }
+    // 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);
+    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) {
+    const s = topic.state;
+    const started = Date.now();
+    if (!s.map)
+        await buildMap(profile, topic);
+    await warmUp(topic);
+    // Survey phase: breadth first.
+    const areas = s.map.areas;
+    while (s.phase === "survey") {
+        const next = areas.find((a) => !s.progress[a.id].surveyed);
+        if (!next) {
+            if (!s.bigPictureDone) {
+                const bp = bigPicturePrompt(s);
+                p.log.step(t.bold(t.accent("Survey complete — zoom out")));
+                const attempts = await teachBack(profile, `${s.title}: big picture`, bp.prompt, bp.keyPoints);
+                s.bigPictureDone = true;
+                if (attempts.length)
+                    await writeText(join(topic.dir, "survey", "big-picture.md"), `# Big picture\n\n> ${bp.prompt}\n\n${attempts.map((a) => `${a.answer}\n\n*${a.grade.feedback}*`).join("\n\n")}\n`);
+            }
+            s.phase = "deep";
+            await saveTopic(topic);
+            break;
+        }
+        const idx = areas.indexOf(next);
+        console.log(`\n  ${t.dim("Survey")} ${bar(areas.filter((a) => s.progress[a.id].surveyed).length, areas.length)}`);
+        await teach({
+            profile,
+            topic,
+            title: next.title,
+            deep: false,
+            file: `survey/${next.id}.md`,
+            load: () => askJson(profile, surveyLessonPrompt(profile, s, next), validateLesson),
+        });
+        s.progress[next.id].surveyed = true;
+        await writeIndex(topic);
+        await saveTopic(topic);
+        if (idx < areas.length - 1 && !(await keepGoing(profile, started)))
+            return;
+    }
+    // Deep phase: pick where to go deep.
+    while (true) {
+        const area = await pickArea(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);
+        }
+        for (const [i, l] of pr.outline.entries()) {
+            if (pr.done.includes(l.id))
+                continue;
+            console.log(`\n  ${t.dim(area.title)} ${bar(pr.done.length, pr.outline.length)}`);
+            p.log.message(t.dim(`Goal: ${l.objective}`));
+            const doneTitles = pr.outline.filter((x) => pr.done.includes(x.id)).map((x) => x.title);
+            await teach({
+                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),
+            });
+            pr.done.push(l.id);
+            await writeIndex(topic);
+            await saveTopic(topic);
+            if (pr.done.length < pr.outline.length && !(await keepGoing(profile, started)))
+                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;
+    }
+}
+async function keepGoing(profile, started) {
+    const over = overTime(started, profile);
+    const mins = Math.round((Date.now() - started) / 60_000);
+    return must(await p.select({
+        message: over ? `${t.warn(`${mins} min in`)} — a good place to stop. Spacing sessions beats cramming.` : "Continue?",
+        initialValue: !over,
+        options: [
+            { value: true, label: "Keep going" },
+            { value: false, label: "Stop here (progress is saved)" },
+        ],
+    }));
+}
+async function pickArea(topic) {
+    const s = topic.state;
+    const areas = s.map.areas;
+    const open = areas.filter((a) => (s.progress[a.id].outline?.length ?? 1) > s.progress[a.id].done.length);
+    if (!open.length) {
+        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) ?? open[0];
+    const choice = must(await p.select({
+        message: "Which area do you want to go deep on?",
+        initialValue: started?.id,
+        options: areas.map((a) => {
+            const pr = s.progress[a.id];
+            const total = pr.outline?.length;
+            const finished = total !== undefined && pr.done.length >= total;
+            return {
+                value: a.id,
+                label: `${finished ? t.ok("✓ ") : ""}${a.title}`,
+                hint: finished ? "done" : total ? `${pr.done.length}/${total} lessons` : a.prereqs.length ? `after: ${a.prereqs.join(", ")}` : a.summary.slice(0, 50),
+            };
+        }),
+    }));
+    return areas.find((a) => a.id === choice);
+}

package/dist/flows/onboard.js

@@ -0,0 +1,124 @@
+import * as p from "@clack/prompts";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { saveProfile } from "../store.js";
+import { must, t } from "../ui.js";
+const has = (bin) => {
+    try {
+        execFileSync("which", [bin], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export async function onboard(existing) {
+    p.intro(t.bold(t.accent(existing ? " Edit your learner profile " : " Let's set up how YOU learn ")));
+    if (!existing)
+        p.note("Answer a few questions so every lesson, quiz and diagram fits you.\nYou can change any of this later with `loops profile`.", "Welcome");
+    const d = existing;
+    const name = must(await p.text({ message: "What should I call you?", initialValue: d?.name, validate: (v) => (v?.trim() ? undefined : "Required") }));
+    const installed = ["claude", "codex"].filter(has);
+    const provider = must(await p.select({
+        message: "Which AI tutor should power your lessons?",
+        initialValue: d?.provider ?? installed[0] ?? "claude",
+        options: [
+            { value: "claude", label: "Claude Code", hint: has("claude") ? "detected" : "not found on PATH" },
+            { value: "codex", label: "Codex CLI", hint: has("codex") ? "detected" : "not found on PATH" },
+        ],
+    }));
+    const goal = must(await p.select({
+        message: "Why do you learn things, mostly?",
+        initialValue: d?.goal,
+        options: [
+            { value: "curiosity — understand it for its own sake", label: "Curiosity" },
+            { value: "career — apply it at work", label: "Career / work" },
+            { value: "exam or certification", label: "Exam / certification" },
+            { value: "building a specific project", label: "Build a project" },
+            { value: "teach it to others", label: "Teach others" },
+        ],
+    }));
+    const level = must(await p.select({
+        message: "When you start something new, you usually are…",
+        initialValue: d?.level ?? "beginner",
+        options: [
+            { value: "beginner", label: "A true beginner", hint: "assume nothing" },
+            { value: "some-background", label: "Some background", hint: "skip the very basics" },
+            { value: "experienced", label: "Experienced in adjacent areas", hint: "move fast, draw parallels" },
+        ],
+    }));
+    const styles = must(await p.multiselect({
+        message: "What helps ideas stick for you? (space to toggle)",
+        initialValues: d?.styles ?? ["concrete examples"],
+        required: false,
+        options: [
+            { value: "concrete examples", label: "Concrete examples" },
+            { value: "analogies to things I know", label: "Analogies" },
+            { value: "diagrams and visuals", label: "Diagrams & visuals" },
+            { value: "first-principles reasoning", label: "First principles" },
+            { value: "history and stories", label: "History & stories" },
+            { value: "small hands-on exercises", label: "Hands-on exercises" },
+            { value: "step-by-step walkthroughs", label: "Step-by-step walkthroughs" },
+        ],
+    }));
+    const order = must(await p.select({
+        message: "How should explanations be ordered?",
+        initialValue: d?.order ?? "big-picture-first",
+        options: [
+            { value: "examples-first", label: "Example first, then the idea" },
+            { value: "theory-first", label: "Principle first, then examples" },
+            { value: "big-picture-first", label: "Big picture first, then zoom in" },
+        ],
+    }));
+    const diagrams = must(await p.select({
+        message: "Mermaid diagrams in your notes?",
+        initialValue: d?.diagrams ?? "some",
+        options: [
+            { value: "lots", label: "Lots — I think visually" },
+            { value: "some", label: "Some — when they help" },
+            { value: "minimal", label: "Minimal" },
+        ],
+    }));
+    const challenge = must(await p.select({
+        message: "How hard should quizzes be?",
+        initialValue: d?.challenge ?? "balanced",
+        options: [
+            { value: "gentle", label: "Gentle", hint: "build confidence" },
+            { value: "balanced", label: "Balanced" },
+            { value: "tough", label: "Tough", hint: "desirable difficulty" },
+        ],
+    }));
+    const tone = must(await p.select({
+        message: "How should I give feedback on your own-words answers?",
+        initialValue: d?.tone ?? "encouraging",
+        options: [
+            { value: "encouraging", label: "Encouraging & specific" },
+            { value: "direct", label: "Direct — tell me what's wrong" },
+            { 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, 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

@@ -0,0 +1,175 @@
+import * as p from "@clack/prompts";
+import { askJson } from "../llm.js";
+import { gradeLabel, gradePrompt, personaPrompt } from "../prompts.js";
+import { schedule, isDue } from "../srs.js";
+import { m, must, t, withSpinner } from "../ui.js";
+import { saveTopic } from "../store.js";
+export function validateGrade(x) {
+    const score = Number(x.score);
+    if (![0, 1, 2, 3].includes(score))
+        throw new Error("score must be 0-3");
+    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 with a confidence rating, so confident mistakes are caught and flagged. */
+export async function runChecks(checks) {
+    const res = { missed: [], overconfident: [], correct: 0, total: checks.length };
+    let sure = 0;
+    let sureRight = 0;
+    for (const [i, c] of checks.entries()) {
+        // 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]) })),
+        }));
+        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 {
+            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))}`);
+        }
+    }
+    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)}`)}`,
+        "",
+        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 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")} — ${m(ask)}`,
+            placeholder: "type your explanation (enter to submit, leave blank to skip)",
+        })).trim();
+        if (!answer)
+            break;
+        const grade = await withSpinner("Reading your explanation...", () => askJson(profile, gradePrompt(profile, title, prompt, keyPoints, answer), validateGrade));
+        attempts.push({ answer, grade });
+        showGrade(grade);
+        if (grade.score >= 2 || i === 1)
+            break;
+        const again = must(await p.select({
+            message: "Want another try with the feedback in mind? (struggling first is how it sticks)",
+            options: [
+                { value: true, label: "Try again" },
+                { value: false, label: "Move on" },
+            ],
+        }));
+        if (!again)
+            break;
+        ask = grade.followUp || prompt;
+    }
+    return attempts;
+}
+/** 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 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: [
+                { value: "again", label: t.bad("Again"), hint: "forgot — see it in 10 min" },
+                { value: "hard", label: t.warn("Hard"), hint: "got it with effort" },
+                { value: "good", label: t.ok("Good") },
+                { value: "easy", label: t.cyan("Easy"), hint: "push it further out" },
+                { value: "stop", label: "Stop for now" },
+            ],
+        }));
+        if (rating === "stop")
+            break;
+        const idx = tp.state.cards.findIndex((c) => c.id === card.id);
+        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++;
+    }
+    return n;
+}