learn-loops 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import * as p from "@clack/prompts";
+import { listTopics, loadProfile, configDir } from "./store.js";
+import { isDue } from "./srs.js";
+import { banner, bar, must, t } from "./ui.js";
+import { onboard } from "./flows/onboard.js";
+import { continueTopic, newTopic, printMap } from "./flows/learn.js";
+import { reviewCards } from "./flows/quiz.js";
+const HELP = `${t.bold("loops")} — learn anything with Claude Code or Codex as your tutor
+
+  loops                 interactive menu
+  loops new [topic]     start learning something new
+  loops continue        pick up where you left off
+  loops review          spaced-repetition review of due flashcards
+  loops topics          list your topics and progress
+  loops profile         edit how you like to learn
+  loops --help          this help
+
+Env: LOOPS_HOME (config dir), LOOPS_PROVIDER=claude|codex, NO_COLOR`;
+const dueCount = (topics) => topics.reduce((n, tp) => n + tp.state.cards.filter((c) => isDue(c)).length, 0);
+function progressOf(tp) {
+    const areas = tp.state.map?.areas ?? [];
+    const lessons = areas.reduce((n, a) => n + (tp.state.progress[a.id]?.done.length ?? 0), 0);
+    return { areas: areas.length, surveyed: areas.filter((a) => tp.state.progress[a.id]?.surveyed).length, lessons };
+}
+async function chooseTopic(topics, message) {
+    const idx = must(await p.select({
+        message,
+        options: topics.map((tp, i) => {
+            const pr = progressOf(tp);
+            return { value: i, label: `${tp.state.title}`, hint: `${tp.state.category} · ${pr.surveyed}/${pr.areas} surveyed · ${pr.lessons} deep lessons` };
+        }),
+    }));
+    return topics[idx];
+}
+async function menu(profile) {
+    while (true) {
+        const topics = await listTopics(profile);
+        const due = dueCount(topics);
+        const action = must(await p.select({
+            message: `Hi ${profile.name}, what now?`,
+            options: [
+                ...(topics.length ? [{ value: "continue", label: "Continue learning", hint: topics[0].state.title }] : []),
+                { value: "new", label: "Start a new topic" },
+                ...(due ? [{ value: "review", label: `Review flashcards`, hint: `${due} due` }] : []),
+                ...(topics.length ? [{ value: "topics", label: "My topics" }] : []),
+                { value: "profile", label: "Edit my learner profile" },
+                { value: "quit", label: "Quit" },
+            ],
+        }));
+        if (action === "quit")
+            return p.outro(t.dim("Keep the loop going ✦"));
+        await dispatch(action, profile);
+    }
+}
+async function dispatch(action, profile, arg) {
+    const topics = await listTopics(profile);
+    switch (action) {
+        case "new": {
+            const tp = await newTopic(profile, arg);
+            if (tp && must(await p.select({ message: "Start the broad survey now?", options: [{ value: true, label: "Yes, let's go" }, { value: false, label: "Later" }] })))
+                await continueTopic(profile, tp);
+            break;
+        }
+        case "continue": {
+            if (!topics.length)
+                return p.log.warn("No topics yet — try `loops new`.");
+            const tp = topics.length === 1 ? topics[0] : await chooseTopic(topics, "Which topic?");
+            if (tp.state.map && tp.state.phase === "survey" && !tp.state.progress[tp.state.map.areas[0].id]?.surveyed)
+                printMap(tp);
+            await continueTopic(profile, tp);
+            break;
+        }
+        case "review": {
+            const n = await reviewCards(topics);
+            p.log.success(n ? t.ok(`Reviewed ${n} card${n > 1 ? "s" : ""}.`) : "Nothing due right now. Come back tomorrow — that's the point.");
+            break;
+        }
+        case "topics": {
+            if (!topics.length)
+                return p.log.warn("No topics yet.");
+            const lines = topics.map((tp) => {
+                const pr = progressOf(tp);
+                return `${t.bold(tp.state.title)} ${t.dim(`(${tp.state.category})`)}\n  survey ${bar(pr.surveyed, pr.areas, 12)}  ${t.dim(`${pr.lessons} deep lessons · ${tp.state.cards.length} cards`)}\n  ${t.dim(tp.dir)}`;
+            });
+            p.note(lines.join("\n\n"), "Your topics");
+            break;
+        }
+        case "profile":
+            await onboard(profile);
+            break;
+    }
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    if (cmd === "--help" || cmd === "-h" || cmd === "help")
+        return console.log(HELP);
+    if (cmd === "--version" || cmd === "-v")
+        return console.log("0.1.0");
+    if (!process.stdin.isTTY) {
+        console.error("loops needs an interactive terminal.");
+        process.exit(1);
+    }
+    banner();
+    let profile = await loadProfile();
+    if (!profile)
+        profile = await onboard();
+    if (process.env.LOOPS_PROVIDER === "claude" || process.env.LOOPS_PROVIDER === "codex")
+        profile.provider = process.env.LOOPS_PROVIDER;
+    if (!cmd)
+        return menu(profile);
+    if (["new", "continue", "review", "topics", "profile"].includes(cmd))
+        return dispatch(cmd, profile, rest.join(" ") || undefined);
+    console.log(HELP);
+    process.exit(1);
+}
+main().catch((e) => {
+    p.log.error(t.bad(e.message));
+    console.error(t.dim(`(config: ${configDir()})`));
+    process.exit(1);
+});

package/dist/flows/learn.js

@@ -0,0 +1,243 @@
+import * as p from "@clack/prompts";
+import { join } from "node:path";
+import { askJson, askText } from "../llm.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 { addCards, isDue } from "../srs.js";
+import { bar, must, renderMd, t, withSpinner } from "../ui.js";
+import { reviewCards, runChecks, teachBack } from "./quiz.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 };
+}
+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) })),
+    };
+}
+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 topic = await createTopic(profile, name.trim(), category, prior.trim());
+    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`);
+    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);
+}
+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)));
+    // 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)" }));
+    }
+    // 2. The chunk, with an escape hatch.
+    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: "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. 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}` }))];
+    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)));
+    p.log.success(`${added} flashcard${added === 1 ? "" : "s"} added to your review queue ${t.dim("→ " + ctx.file)}`);
+}
+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,
+            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.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,
+                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 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);
+    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,111 @@
+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 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 };
+    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,98 @@
+import * as p from "@clack/prompts";
+import { askJson } from "../llm.js";
+import { gradeLabel, gradePrompt } from "../prompts.js";
+import { schedule, isDue } from "../srs.js";
+import { 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. Returns the questions the learner got wrong. */
+export async function runChecks(checks) {
+    const missed = [];
+    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 })),
+        }));
+        if (picked === c.answer)
+            p.log.success(t.ok("Correct. ") + t.dim(c.explain));
+        else {
+            missed.push(c);
+            p.log.error(t.bad("Not quite. ") + `Answer: ${c.options[c.answer]}\n  ${t.dim(c.explain)}`);
+        }
+    }
+    return missed;
+}
+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}`),
+    ];
+    p.note(lines.join("\n"), "Feedback");
+}
+/** Feynman-style teach-back with one optional retry. */
+export async function teachBack(profile, title, prompt, keyPoints) {
+    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}`,
+            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;
+}
+/** 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);
+    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}`);
+        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);
+        tp.state.cards[idx] = schedule(card, rating);
+        await saveTopic(tp);
+        n++;
+    }
+    return n;
+}

package/dist/llm.js

@@ -0,0 +1,76 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const TUTOR_SYSTEM = [
+    "You are an exceptional tutor grounded in learning science: you activate prior knowledge,",
+    "teach in small chunks, use concrete examples and diagrams, test retrieval rather than recognition,",
+    "and correct misconceptions precisely. You never pad. You are accurate: if unsure, say so.",
+    "You output exactly what is asked for, in the requested format, with no preamble.",
+].join(" ");
+function run(cmd, args, input, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { cwd: tmpdir(), stdio: ["pipe", "pipe", "pipe"] });
+        let out = "";
+        let err = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(new Error(`${cmd} timed out after ${timeoutMs / 1000}s`));
+        }, timeoutMs);
+        child.stdout.on("data", (d) => (out += d));
+        child.stderr.on("data", (d) => (err += d));
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(new Error(`Could not run "${cmd}" — is it installed and on your PATH? (${e.message})`));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(`${cmd} exited with ${code}: ${err.trim().split("\n").slice(-4).join("\n")}`));
+        });
+        child.stdin.end(input);
+    });
+}
+export async function complete(provider, prompt, timeoutMs = 240_000) {
+    if (provider === "claude") {
+        return run("claude", ["-p", "--tools", "", "--no-session-persistence", "--output-format", "text", "--system-prompt", TUTOR_SYSTEM], prompt, timeoutMs);
+    }
+    const dir = await mkdtemp(join(tmpdir(), "loops-"));
+    const outFile = join(dir, "last.txt");
+    try {
+        await run("codex", ["exec", "--skip-git-repo-check", "--ephemeral", "-s", "read-only", "-o", outFile, "-"], `${TUTOR_SYSTEM}\n\n${prompt}`, timeoutMs);
+        return await readFile(outFile, "utf8");
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+export function extractJson(text) {
+    const cleaned = text.replace(/```(?:json)?/gi, "");
+    const start = cleaned.indexOf("{");
+    const end = cleaned.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        throw new Error("no JSON object in model output");
+    return JSON.parse(cleaned.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) {
+    let lastError = "";
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const full = attempt === 0 ? prompt : `${prompt}\n\nYour previous reply was rejected: ${lastError}\nReturn ONLY valid JSON this time.`;
+        try {
+            return validate(extractJson(await complete(profile.provider, full)));
+        }
+        catch (e) {
+            lastError = e.message;
+            if (attempt === 1 || /not installed|PATH|timed out/.test(lastError))
+                throw new Error(lastError);
+        }
+    }
+    throw new Error(lastError);
+}
+export async function askText(profile, prompt) {
+    return (await complete(profile.provider, prompt)).trim();
+}

package/dist/markdown.js

@@ -0,0 +1,85 @@
+import { join } from "node:path";
+import { writeText } from "./store.js";
+/** Strip characters that break mermaid mindmap / quoted labels. */
+const clean = (s) => s.replace(/["'`()\[\]{}:;#<>]/g, "").replace(/\s+/g, " ").trim();
+const nodeId = (s) => "n_" + s.replace(/[^a-zA-Z0-9]/g, "_");
+export function mapMarkdown(topic) {
+    const { title, map } = topic.state;
+    if (!map)
+        return "";
+    const mind = [
+        "```mermaid",
+        "mindmap",
+        `  root((${clean(title)}))`,
+        ...map.areas.flatMap((a) => [`    ${clean(a.title)}`, ...a.concepts.map((c) => `      ${clean(c.name)}`)]),
+        "```",
+    ].join("\n");
+    const edges = map.areas.flatMap((a) => a.prereqs.filter((p) => map.areas.some((x) => x.id === p)).map((p) => `  ${nodeId(p)} --> ${nodeId(a.id)}`));
+    const flow = [
+        "```mermaid",
+        "flowchart LR",
+        ...map.areas.map((a) => `  ${nodeId(a.id)}["${clean(a.title)}"]`),
+        ...edges,
+        "```",
+    ].join("\n");
+    return `# ${title} — map
+
+${map.overview}
+
+## The territory
+
+${mind}
+
+## Suggested order
+
+Arrows mean "understand this first".
+
+${flow}
+
+## Areas
+
+${map.areas.map((a) => `### ${a.title}\n${a.summary}\n\n${a.concepts.map((c) => `- **${c.name}** — ${c.blurb}`).join("\n")}`).join("\n\n")}
+`;
+}
+export function lessonMarkdown(title, lesson, own, missed) {
+    const checks = lesson.checks
+        .map((c, i) => `${i + 1}. ${c.q}\n${c.options.map((o, j) => `   - ${j === c.answer ? "✅" : "▫️"} ${o}`).join("\n")}\n   - *${c.explain}*`)
+        .join("\n");
+    const ownBlock = own?.length
+        ? `\n## In my own words\n\n> ${lesson.teachBack}\n\n${own
+            .map((o, i) => `**Attempt ${i + 1}** — ${o.grade.score}/3\n\n${o.answer.split("\n").map((l) => "> " + l).join("\n")}\n\n${o.grade.feedback}${o.grade.missing.length ? `\n\nMissing: ${o.grade.missing.join("; ")}` : ""}`)
+            .join("\n\n")}\n`
+        : "";
+    return `# ${title}
+
+${lesson.markdown}
+
+## Key points
+
+${lesson.keyPoints.map((k) => `- ${k}`).join("\n")}
+
+## Check yourself
+
+${checks}
+${missed?.length ? `\n**Still shaky:** ${missed.join("; ")}\n` : ""}${ownBlock}
+## Flashcards
+
+${lesson.cards.map((c) => `- **${c.front}** → ${c.back}`).join("\n")}
+`;
+}
+export async function writeIndex(topic) {
+    const { state } = topic;
+    const lines = [`# ${state.title}`, "", state.map?.overview ?? "", "", "- [Map of the territory](map.md)", ""];
+    if (state.map) {
+        lines.push("## Progress", "");
+        for (const a of state.map.areas) {
+            const pr = state.progress[a.id];
+            const done = pr?.done.length ?? 0;
+            const total = pr?.outline?.length ?? 0;
+            const surveyed = pr?.surveyed ? "✅" : "⬜";
+            lines.push(`- ${surveyed} **${a.title}** — survey: [overview](survey/${a.id}.md)${total ? ` · deep dive ${done}/${total}: ${(pr.outline ?? []).map((l, i) => (pr.done.includes(l.id) ? `[${l.title}](deep/${a.id}/${String(i + 1).padStart(2, "0")}-${l.id}.md)` : l.title)).join(", ")}` : ""}`);
+        }
+    }
+    lines.push("", `_${state.cards.length} flashcards tracked in topic.json_`, "");
+    await writeText(join(topic.dir, "README.md"), lines.join("\n"));
+}

package/dist/prompts.js

@@ -0,0 +1,73 @@
+export function learnerBlurb(p) {
+    return [
+        `Learner: ${p.name}. Goal: ${p.goal}. Level: ${p.level}.`,
+        `Likes: ${p.styles.join(", ") || "no strong preference"}. Prefers ${p.order.replace(/-/g, " ")} ordering.`,
+        `Diagram appetite: ${p.diagrams}. Challenge: ${p.challenge}. Feedback tone: ${p.tone}.`,
+    ].join(" ");
+}
+const MERMAID_RULES = `Mermaid rules (diagrams MUST render): use only flowchart TD/LR, sequenceDiagram, stateDiagram-v2, classDiagram, or mindmap.
+Always wrap flowchart node labels in double quotes, e.g. A["Label text"]. Never put parentheses, quotes or colons inside unquoted labels. Keep diagrams under 12 nodes. Fence them as \`\`\`mermaid.`;
+const diagramRule = (p) => p.diagrams === "lots" ? "Include 1-2 mermaid diagrams." : p.diagrams === "some" ? "Include one mermaid diagram if it genuinely helps." : "Only include a diagram if essential.";
+export function mapPrompt(p, topic, prior) {
+    return `${learnerBlurb(p)}
+Create a map of the whole territory of "${topic}" for this learner. Their stated prior knowledge: ${prior || "none stated"}.
+Cover the field broadly: 5-9 areas, ordered so earlier areas support later ones. Each area has 3-6 concepts.
+Return ONLY JSON:
+{"overview":"2-3 sentence orientation: what this field is and why it matters",
+ "areas":[{"id":"short-kebab-id","title":"...","summary":"1-2 sentences","prereqs":["ids of areas that should come first"],"concepts":[{"name":"...","blurb":"one line"}]}]}`;
+}
+const lessonShape = `{"primer":"one open question that makes the learner GUESS before reading (no jargon they haven't seen)",
+ "markdown":"the lesson body in markdown",
+ "checks":[{"q":"...","options":["A","B","C","D"],"answer":0,"explain":"why the answer is right and the best distractor is wrong"}],
+ "teachBack":"a prompt asking the learner to explain the idea in their own words, ideally to a specific imagined person or via a small scenario",
+ "keyPoints":["3-5 points a correct own-words explanation should contain"],
+ "cards":[{"front":"recall question","back":"concise answer"}]}`;
+export function surveyLessonPrompt(p, s, area) {
+    return `${learnerBlurb(p)}
+Topic: "${s.title}". This is the BROAD SURVEY pass: give the learner the basic idea of the area "${area.title}" (${area.summary}).
+Concepts to touch: ${area.concepts.map((c) => c.name).join(", ")}.
+Rules: max ~250 words in markdown. ${p.order === "examples-first" ? "Open with a concrete example, then name the idea." : p.order === "theory-first" ? "State the core principle first, then illustrate." : "Open with where it fits in the whole field, then the idea, then an example."}
+Use the learner's preferred styles (${p.styles.join(", ") || "any"}). ${diagramRule(p)} ${MERMAID_RULES}
+Exactly 2 multiple-choice checks (4 options each, "answer" is the 0-based index, plausible distractors based on real misconceptions; vary the position of the right answer). 2-3 flashcards.
+Return ONLY JSON of this shape:
+${lessonShape}`;
+}
+export function outlinePrompt(p, s, area) {
+    return `${learnerBlurb(p)}
+Topic: "${s.title}". Plan a DEEP DIVE into "${area.title}" (${area.summary}); concepts: ${area.concepts.map((c) => c.name).join(", ")}.
+Design 4-7 lessons that build on each other (simple -> complex, each introduces ONE main idea), ending with a lesson that integrates everything in a realistic scenario.
+Return ONLY JSON: {"lessons":[{"id":"short-kebab-id","title":"...","objective":"By the end you can ..."}]}`;
+}
+export function deepLessonPrompt(p, s, area, lesson, doneTitles) {
+    return `${learnerBlurb(p)}
+Topic: "${s.title}", area "${area.title}". DEEP lesson: "${lesson.title}" — objective: ${lesson.objective}.
+Already covered in this area: ${doneTitles.join("; ") || "nothing yet"}. Build on that; connect back to it explicitly.
+Rules: 400-650 words of markdown with ## subheadings. ${p.order === "examples-first" ? "Start from a worked example, then abstract." : p.order === "theory-first" ? "Start from first principles, then apply." : "Start from the big picture, zoom in, then work an example."}
+Include a worked example, one common misconception to avoid, and ${p.diagrams === "minimal" ? "at least one" : "1-2"} mermaid diagram(s) showing the real mechanism/structure (not decoration). ${MERMAID_RULES}
+Challenge level: ${p.challenge}. Exactly ${p.challenge === "tough" ? 4 : 3} multiple-choice checks that test understanding/application, not trivia (4 options, "answer" is 0-based). 3-4 flashcards phrased as recall questions.
+Return ONLY JSON of this shape:
+${lessonShape}`;
+}
+export function reexplainPrompt(p, topic, lessonTitle, original) {
+    return `${learnerBlurb(p)}
+The learner is stuck on "${lessonTitle}" (topic: ${topic}). Re-explain the SAME idea differently: new analogy, simpler words, different example. Do not repeat the original framing. Max 200 words, markdown, optionally one mermaid diagram. ${MERMAID_RULES}
+Original explanation for reference:
+${original}
+Return only the markdown.`;
+}
+export function gradePrompt(p, lessonTitle, prompt, keyPoints, answer) {
+    const tone = { encouraging: "warm and specific", direct: "blunt and efficient", socratic: "mostly questions that lead them to see gaps themselves" }[p.tone];
+    return `Grade a learner's own-words explanation. Lesson: "${lessonTitle}". Prompt given: "${prompt}".
+A strong answer includes: ${keyPoints.map((k) => `- ${k}`).join("\n")}
+Learner's answer: """${answer}"""
+Be ${tone}. Judge understanding, not wording; reward correct paraphrase, penalise parroting and errors. score: 0 = off/blank, 1 = fragments, 2 = mostly right with gaps, 3 = solid.
+Return ONLY JSON: {"score":0-3,"right":["what they got right"],"missing":["key ideas absent"],"misconceptions":["things they said that are wrong, with the correction"],"feedback":"2-3 sentences","followUp":"one probing question that would deepen their understanding"}`;
+}
+export function bigPicturePrompt(s) {
+    const areas = s.map.areas;
+    return {
+        prompt: `Without looking back: how do the main areas of ${s.title} (${areas.map((a) => a.title).join(", ")}) fit together? Explain it as if briefing a smart friend.`,
+        keyPoints: areas.map((a) => `${a.title}: ${a.summary}`),
+    };
+}
+export const gradeLabel = (g) => ["Not yet", "Getting there", "Mostly there", "Solid"][g.score];

package/dist/srs.js

@@ -0,0 +1,50 @@
+const DAY = 86_400_000;
+export function newCard(front, back, source, now = new Date()) {
+    return {
+        id: Math.random().toString(36).slice(2, 10),
+        front,
+        back,
+        source,
+        ease: 2.5,
+        interval: 0,
+        reps: 0,
+        lapses: 0,
+        due: now.toISOString(),
+    };
+}
+/** Simplified SM-2: failed cards come back soon, successful ones expand the gap. */
+export function schedule(card, rating, now = new Date()) {
+    const c = { ...card };
+    if (rating === "again") {
+        c.lapses++;
+        c.reps = 0;
+        c.ease = Math.max(1.3, c.ease - 0.2);
+        c.interval = 0;
+        c.due = new Date(now.getTime() + 10 * 60_000).toISOString();
+        return c;
+    }
+    c.reps++;
+    if (rating === "hard")
+        c.ease = Math.max(1.3, c.ease - 0.15);
+    if (rating === "easy")
+        c.ease += 0.15;
+    if (c.reps === 1)
+        c.interval = rating === "easy" ? 3 : 1;
+    else if (c.reps === 2)
+        c.interval = rating === "hard" ? 2 : 4;
+    else
+        c.interval = Math.max(1, Math.round(c.interval * (rating === "hard" ? 1.2 : rating === "easy" ? c.ease * 1.3 : c.ease)));
+    c.due = new Date(now.getTime() + c.interval * DAY).toISOString();
+    return c;
+}
+export const isDue = (c, now = new Date()) => new Date(c.due).getTime() <= now.getTime();
+export function addCards(existing, fresh, source) {
+    let added = 0;
+    for (const f of fresh) {
+        if (existing.some((c) => c.front.trim().toLowerCase() === f.front.trim().toLowerCase()))
+            continue;
+        existing.push(newCard(f.front, f.back, source));
+        added++;
+    }
+    return added;
+}

package/dist/store.js

@@ -0,0 +1,80 @@
+import { mkdir, readFile, writeFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+export const configDir = () => process.env.LOOPS_HOME ?? join(homedir(), ".config", "loops");
+const profilePath = () => join(configDir(), "profile.json");
+export const slugify = (s) => s
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48) || "untitled";
+export const expandHome = (p) => (p.startsWith("~") ? join(homedir(), p.slice(1)) : p);
+export async function loadProfile() {
+    try {
+        return JSON.parse(await readFile(profilePath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveProfile(profile) {
+    await mkdir(configDir(), { recursive: true });
+    await writeFile(profilePath(), JSON.stringify(profile, null, 2));
+}
+export async function writeText(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content);
+}
+export async function saveTopic(topic) {
+    await writeText(join(topic.dir, "topic.json"), JSON.stringify(topic.state, null, 2));
+}
+/** Topics live at <root>/<category>/<slug>/topic.json. */
+export async function listTopics(profile) {
+    const root = expandHome(profile.rootDir);
+    if (!existsSync(root))
+        return [];
+    const topics = [];
+    for (const cat of await readdir(root, { withFileTypes: true })) {
+        if (!cat.isDirectory())
+            continue;
+        for (const sub of await readdir(join(root, cat.name), { withFileTypes: true })) {
+            const file = join(root, cat.name, sub.name, "topic.json");
+            if (!sub.isDirectory() || !existsSync(file))
+                continue;
+            try {
+                topics.push({ dir: join(root, cat.name, sub.name), state: JSON.parse(await readFile(file, "utf8")) });
+            }
+            catch {
+                /* skip unreadable topic */
+            }
+        }
+    }
+    return topics.sort((a, b) => lastTouched(b).localeCompare(lastTouched(a)));
+}
+const lastTouched = (t) => t.state.cards.map((c) => c.due).sort().pop() ?? t.state.createdAt;
+export async function listCategories(profile) {
+    const root = expandHome(profile.rootDir);
+    if (!existsSync(root))
+        return [];
+    return (await readdir(root, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+}
+export async function createTopic(profile, title, category, priorKnowledge) {
+    const slug = slugify(title);
+    const dir = join(expandHome(profile.rootDir), slugify(category), slug);
+    const state = {
+        title,
+        slug,
+        category: slugify(category),
+        createdAt: new Date().toISOString(),
+        priorKnowledge,
+        phase: "map",
+        progress: {},
+        bigPictureDone: false,
+        cards: [],
+    };
+    const topic = { dir, state };
+    await saveTopic(topic);
+    return topic;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui.js

@@ -0,0 +1,99 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+const useColor = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const c256 = (n) => (s) => (useColor ? `\x1b[38;5;${n}m${s}\x1b[39m` : s);
+export const t = {
+    accent: c256(141),
+    pink: c256(213),
+    cyan: c256(87),
+    ok: c256(78),
+    warn: c256(215),
+    bad: c256(203),
+    dim: pc.dim,
+    bold: pc.bold,
+    italic: pc.italic,
+};
+const LOGO = [
+    "  ██╗      ██████╗  ██████╗ ██████╗ ███████╗",
+    "  ██║     ██╔═══██╗██╔═══██╗██╔══██╗██╔════╝",
+    "  ██║     ██║   ██║██║   ██║██████╔╝███████╗",
+    "  ██║     ██║   ██║██║   ██║██╔═══╝ ╚════██║",
+    "  ███████╗╚██████╔╝╚██████╔╝██║     ███████║",
+    "  ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝     ╚══════╝",
+];
+const GRADIENT = [93, 99, 105, 141, 177, 213];
+export function banner(subtitle = "learn anything, properly") {
+    console.log();
+    LOGO.forEach((line, i) => console.log(c256(GRADIENT[i])(line)));
+    console.log(t.dim(`  ${subtitle}\n`));
+}
+/** Unwrap a clack prompt result; exit cleanly on Ctrl+C. */
+export function must(value) {
+    if (p.isCancel(value)) {
+        p.cancel("Progress saved. See you next time ✦");
+        process.exit(0);
+    }
+    return value;
+}
+export async function withSpinner(label, fn) {
+    const s = p.spinner();
+    s.start(label);
+    try {
+        const r = await fn();
+        s.stop(t.ok("✓ ") + label.replace(/\.\.\.$/, ""));
+        return r;
+    }
+    catch (e) {
+        s.stop(t.bad("✗ ") + label);
+        throw e;
+    }
+}
+export function bar(done, total, width = 20) {
+    const filled = total === 0 ? 0 : Math.round((done / total) * width);
+    return t.accent("█".repeat(filled)) + t.dim("░".repeat(width - filled)) + t.dim(` ${done}/${total}`);
+}
+/** Lightweight terminal markdown renderer. Mermaid blocks are summarised, not drawn. */
+export function renderMd(md) {
+    const out = [];
+    let fence = null;
+    const inline = (s) => s
+        .replace(/\*\*(.+?)\*\*/g, (_, x) => t.bold(x))
+        .replace(/`([^`]+)`/g, (_, x) => t.cyan(x))
+        .replace(/(?<![*\w])\*([^*]+)\*(?!\w)/g, (_, x) => t.italic(x));
+    for (const raw of md.split("\n")) {
+        const fm = raw.match(/^```(\w*)/);
+        if (fm) {
+            if (fence === null) {
+                fence = fm[1] || "code";
+                if (fence === "mermaid")
+                    out.push("  " + t.pink("◆ diagram ") + t.dim("(rendered in the markdown file)"));
+            }
+            else
+                fence = null;
+            continue;
+        }
+        if (fence === "mermaid")
+            continue;
+        if (fence !== null) {
+            out.push("  " + t.dim("│ ") + t.cyan(raw));
+            continue;
+        }
+        const h = raw.match(/^(#{1,4})\s+(.*)/);
+        if (h) {
+            out.push("", "  " + (h[1].length <= 2 ? t.bold(t.accent(h[2])) : t.bold(h[2])));
+            continue;
+        }
+        const li = raw.match(/^(\s*)[-*]\s+(.*)/);
+        if (li) {
+            out.push("  " + li[1] + t.accent("• ") + inline(li[2]));
+            continue;
+        }
+        const q = raw.match(/^>\s?(.*)/);
+        if (q) {
+            out.push("  " + t.warn("▌ ") + t.italic(inline(q[1])));
+            continue;
+        }
+        out.push(raw.trim() ? "  " + inline(raw) : "");
+    }
+    return out.join("\n");
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "learn-loops",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A learning CLI that uses Claude Code / Codex as your tutor",
+  "type": "module",
+  "bin": {
+    "loops": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "learning",
+    "cli",
+    "claude-code",
+    "codex",
+    "mermaid",
+    "spaced-repetition",
+    "tutor"
+  ]
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.