keating 0.3.6

package/dist/src/core/benchmark.js

@@ -0,0 +1,253 @@
+import { Prng } from "./random.js";
+import { benchmarkTopics } from "./topics.js";
+import { clamp, mean } from "./util.js";
+import { DEFAULT_WEIGHTS, clampWeights } from "./policy.js";
+function buildLearnerPopulation(seed, count) {
+    const prng = new Prng(seed);
+    const learners = [];
+    for (let index = 0; index < count; index += 1) {
+        learners.push({
+            id: `learner-${seed}-${index}`,
+            priorKnowledge: prng.next(),
+            abstractionComfort: prng.next(),
+            analogyNeed: prng.next(),
+            dialoguePreference: prng.next(),
+            diagramAffinity: prng.next(),
+            persistence: prng.next(),
+            transferDesire: prng.next(),
+            anxiety: prng.next()
+        });
+    }
+    return learners;
+}
+import { piCompleteJson } from "./pi-agent.js";
+export async function simulateTeaching(cwd, policy, topic, learner, weights = DEFAULT_WEIGHTS) {
+    // Use pure math to calculate initial constraints as baseline context
+    const intuitionFit = 1 - Math.abs(policy.analogyDensity - learner.analogyNeed);
+    const rigorTarget = clamp((topic.formalism + learner.abstractionComfort) / 2);
+    const rigorFit = 1 - Math.abs(policy.formalism - rigorTarget);
+    const dialogueFit = 1 - Math.abs(policy.socraticRatio - learner.dialoguePreference);
+    const diagramTarget = topic.visualizable ? learner.diagramAffinity : 0.2;
+    const diagramFit = 1 - Math.abs(policy.diagramBias - diagramTarget);
+    const practiceNeed = clamp(1 - learner.priorKnowledge + learner.anxiety * 0.2);
+    const practiceFit = 1 - Math.abs(policy.exerciseCount / 5 - practiceNeed);
+    const reflectionFit = 1 - Math.abs(policy.reflectionBias - learner.transferDesire);
+    const overload = clamp(policy.formalism * 0.35 +
+        (policy.exerciseCount / 5) * 0.15 +
+        policy.challengeRate * 0.3 -
+        learner.persistence * 0.2 +
+        learner.anxiety * 0.25 -
+        learner.priorKnowledge * 0.15);
+    const prompt = `Simulate an educational interaction based on the following context.
+Teacher Policy: ${JSON.stringify(policy, null, 2)}
+Topic: ${topic.title} (${topic.domain}) - ${topic.summary}
+Learner Traits: ${JSON.stringify(learner, null, 2)}
+
+Evaluate the teaching outcomes from 0.0 to 1.0 (masteryGain, retention, engagement, transfer, confusion). Also provide an overall 'score' (0.0=failure to 1.0=mastery) computed as: score = masteryGain*${weights.masteryGain.toFixed(2)} + retention*${weights.retention.toFixed(2)} + engagement*${weights.engagement.toFixed(2)} + transfer*${weights.transfer.toFixed(2)} - confusion*${weights.confusion.toFixed(2)}
+Provide 1 to 3 string sentences explaining the outcome in the 'explanation' array. 
+Respond ONLY as a JSON matching:
+{
+  "masteryGain": number,
+  "retention": number,
+  "engagement": number,
+  "transfer": number,
+  "confusion": number,
+  "score": number,
+  "explanation": string[]
+}`;
+    try {
+        const evaluation = await piCompleteJson(cwd, prompt, { thinking: "low" });
+        if (typeof evaluation.masteryGain !== "number" || Number.isNaN(evaluation.masteryGain)) {
+            throw new Error("LLM returned invalid evaluation metrics");
+        }
+        return {
+            learner,
+            topic,
+            masteryGain: clamp(evaluation.masteryGain, 0, 1),
+            retention: clamp(evaluation.retention, 0, 1),
+            engagement: clamp(evaluation.engagement, 0, 1),
+            transfer: clamp(evaluation.transfer, 0, 1),
+            confusion: clamp(evaluation.confusion, 0, 1),
+            score: clamp(evaluation.score, 0, 1),
+            breakdown: {
+                intuitionFit,
+                rigorFit,
+                dialogueFit,
+                diagramFit,
+                practiceFit,
+                reflectionFit,
+                overload
+            },
+            explanation: evaluation.explanation
+        };
+    }
+    catch (error) {
+        console.error("LLM simulation failed, falling back to algebraic baseline", error);
+        const masteryGain = clamp(0.14 + intuitionFit * 0.18 + rigorFit * 0.2 + dialogueFit * 0.12 + diagramFit * 0.09 + practiceFit * 0.12 + (1 - overload) * 0.18);
+        const retention = clamp(masteryGain * (0.55 + policy.retrievalPractice * 0.45));
+        const engagement = clamp(0.12 + intuitionFit * 0.16 + dialogueFit * 0.16 + diagramFit * 0.1 + reflectionFit * 0.14 + (1 - overload) * 0.18);
+        const transfer = clamp(masteryGain * (0.55 + policy.interdisciplinaryBias * 0.25 + learner.transferDesire * 0.2));
+        const confusion = clamp(0.04 + overload * 0.55 + Math.abs(policy.formalism - learner.abstractionComfort) * 0.18 + Math.abs(policy.challengeRate - learner.persistence) * 0.12);
+        const score = clamp(masteryGain * weights.masteryGain +
+            retention * weights.retention +
+            engagement * weights.engagement +
+            transfer * weights.transfer -
+            confusion * weights.confusion, 0, 1);
+        return {
+            learner,
+            topic,
+            masteryGain,
+            retention,
+            engagement,
+            transfer,
+            confusion,
+            score,
+            breakdown: {
+                intuitionFit,
+                rigorFit,
+                dialogueFit,
+                diagramFit,
+                practiceFit,
+                reflectionFit,
+                overload
+            },
+            explanation: ["Fallback deterministic explanation."]
+        };
+    }
+}
+function classifyDominantSignal(simulations, kind) {
+    const metrics = {
+        intuitionFit: mean(simulations.map((entry) => entry.breakdown.intuitionFit)),
+        rigorFit: mean(simulations.map((entry) => entry.breakdown.rigorFit)),
+        dialogueFit: mean(simulations.map((entry) => entry.breakdown.dialogueFit)),
+        diagramFit: mean(simulations.map((entry) => entry.breakdown.diagramFit)),
+        practiceFit: mean(simulations.map((entry) => entry.breakdown.practiceFit)),
+        reflectionFit: mean(simulations.map((entry) => entry.breakdown.reflectionFit)),
+        overload: mean(simulations.map((entry) => entry.breakdown.overload))
+    };
+    const ordered = Object.entries(metrics).sort((left, right) => kind === "strength" ? right[1] - left[1] : left[1] - right[1]);
+    const [name] = ordered[0] ?? ["unknown"];
+    return name;
+}
+export function summarizeTopic(topic, simulations, traceLimit) {
+    const ranked = [...simulations].sort((left, right) => right.score - left.score);
+    const scores = simulations.map((entry) => entry.score).filter(s => !Number.isNaN(s));
+    const meanScore = mean(scores) * 100;
+    return {
+        topic,
+        learnerCount: simulations.length,
+        meanScore,
+        meanMasteryGain: mean(simulations.map((entry) => entry.masteryGain).filter(m => !Number.isNaN(m))),
+        meanRetention: mean(simulations.map((entry) => entry.retention).filter(r => !Number.isNaN(r))),
+        meanEngagement: mean(simulations.map((entry) => entry.engagement).filter(e => !Number.isNaN(e))),
+        meanTransfer: mean(simulations.map((entry) => entry.transfer).filter(t => !Number.isNaN(t))),
+        meanConfusion: mean(simulations.map((entry) => entry.confusion).filter(c => !Number.isNaN(c))),
+        topLearners: ranked.slice(0, traceLimit),
+        strugglingLearners: ranked.slice(-traceLimit).reverse(),
+        dominantStrength: classifyDominantSignal(simulations, "strength"),
+        dominantWeakness: classifyDominantSignal(simulations, "weakness")
+    };
+}
+export async function runBenchmarkSuite(cwd, policy, focusTopic, seed = 20260401, traceLimit = 3, weights = DEFAULT_WEIGHTS) {
+    const topics = benchmarkTopics(focusTopic);
+    const topicTraces = [];
+    // Reduce learner count to 3 instead of 18 to save LLM tokens and time
+    const NUM_LEARNERS = 3;
+    const topicBenchmarks = await Promise.all(topics.map(async (topic, index) => {
+        const learners = buildLearnerPopulation(seed + index * 97, NUM_LEARNERS);
+        const simulations = await Promise.all(learners.map((learner) => simulateTeaching(cwd, policy, topic, learner, weights)));
+        const summary = summarizeTopic(topic, simulations, traceLimit);
+        topicTraces.push({
+            topic: topic.title,
+            topLearners: summary.topLearners.map((entry) => ({
+                learnerId: entry.learner.id,
+                score: entry.score,
+                explanation: entry.explanation || ["unknown"]
+            })),
+            strugglingLearners: summary.strugglingLearners.map((entry) => ({
+                learnerId: entry.learner.id,
+                score: entry.score,
+                explanation: entry.explanation || ["unknown"]
+            })),
+            metricMeans: {
+                masteryGain: summary.meanMasteryGain,
+                retention: summary.meanRetention,
+                engagement: summary.meanEngagement,
+                transfer: summary.meanTransfer,
+                confusion: summary.meanConfusion
+            },
+            dominantStrength: summary.dominantStrength,
+            dominantWeakness: summary.dominantWeakness
+        });
+        return summary;
+    }));
+    const weakest = [...topicBenchmarks].sort((left, right) => left.meanScore - right.meanScore)[0];
+    const overallScores = topicBenchmarks.map((entry) => entry.meanScore).filter(s => !Number.isNaN(s));
+    return {
+        policy,
+        suiteName: focusTopic ? `focused:${focusTopic}` : "core-suite",
+        topicBenchmarks,
+        overallScore: mean(overallScores),
+        weakestTopic: weakest?.topic.title ?? "n/a",
+        trace: {
+            seed,
+            learnerCountPerTopic: NUM_LEARNERS,
+            topicTraces
+        }
+    };
+}
+export function benchmarkToMarkdown(result) {
+    const lines = [
+        `# Benchmark Report: ${result.policy.name}`,
+        "",
+        `- Suite: ${result.suiteName}`,
+        `- Overall score: ${result.overallScore.toFixed(2)}`,
+        `- Weakest topic: ${result.weakestTopic}`,
+        "",
+        "| Topic | Score | Mastery | Retention | Engagement | Transfer | Confusion |",
+        "| --- | ---: | ---: | ---: | ---: | ---: | ---: |"
+    ];
+    for (const benchmark of result.topicBenchmarks) {
+        lines.push(`| ${benchmark.topic.title} | ${benchmark.meanScore.toFixed(2)} | ${benchmark.meanMasteryGain.toFixed(2)} | ${benchmark.meanRetention.toFixed(2)} | ${benchmark.meanEngagement.toFixed(2)} | ${benchmark.meanTransfer.toFixed(2)} | ${benchmark.meanConfusion.toFixed(2)} |`);
+    }
+    lines.push("");
+    lines.push("## Interpretation");
+    lines.push("");
+    lines.push(`- The policy currently underperforms most on ${result.weakestTopic}, which is a useful anchor for mutation and curriculum repair.`);
+    lines.push("- Invariants tracked here favor durable learning signals: mastery, retention, engagement, transfer, and bounded confusion.");
+    lines.push("- Debug traces below explain which learners the policy helped most, where it struggled, and which signal dominated.");
+    lines.push("");
+    lines.push("## Debug Trace");
+    lines.push("");
+    for (const benchmark of result.topicBenchmarks) {
+        lines.push(`### ${benchmark.topic.title}`);
+        lines.push(`- Dominant strength: ${benchmark.dominantStrength}`);
+        lines.push(`- Dominant weakness: ${benchmark.dominantWeakness}`);
+        lines.push("- Top learners:");
+        for (const learner of benchmark.topLearners) {
+            lines.push(`  - ${learner.learner.id}: ${(learner.score * 100).toFixed(1)} because ${(learner.explanation || ["unknown"]).join("; ")}`);
+        }
+        lines.push("- Struggling learners:");
+        for (const learner of benchmark.strugglingLearners) {
+            lines.push(`  - ${learner.learner.id}: ${(learner.score * 100).toFixed(1)} because ${(learner.explanation || ["unknown"]).join("; ")}`);
+        }
+        lines.push("");
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+export function applyFeedbackBias(feedback) {
+    if (feedback.sampleSize < 5)
+        return { ...DEFAULT_WEIGHTS };
+    const weights = { ...DEFAULT_WEIGHTS };
+    weights.confusion = clamp(weights.confusion + feedback.confusionRate * 0.08);
+    weights.engagement = clamp(weights.engagement + feedback.satisfactionRate * 0.04);
+    const positiveSum = weights.masteryGain + weights.retention + weights.engagement + weights.transfer;
+    const targetPositive = 1 - weights.confusion;
+    const scale = targetPositive / positiveSum;
+    weights.masteryGain *= scale;
+    weights.retention *= scale;
+    weights.engagement *= scale;
+    weights.transfer *= scale;
+    return clampWeights(weights);
+}

package/dist/src/core/commands.js

@@ -0,0 +1,57 @@
+export const extensionCommandSpecs = [
+    { name: "plan", args: "<topic>", section: "Teaching", description: "Generate a deterministic lesson plan artifact." },
+    { name: "map", args: "<topic>", section: "Teaching", description: "Generate a Mermaid concept map with oxdraw rendering." },
+    { name: "animate", args: "<topic>", section: "Teaching", description: "Generate a manim-web animation bundle." },
+    { name: "learn", args: "<topic>", section: "Teaching", description: "Start a Socratic teaching session.", shellOnly: true },
+    { name: "diagnose", args: "<topic>", section: "Teaching", description: "Map prerequisites and knowledge gaps.", shellOnly: true },
+    { name: "quiz", args: "<topic>", section: "Assessment", description: "Generate retrieval practice questions." },
+    { name: "verify", args: "<topic>", section: "Assessment", description: "Generate a fact-checking checklist before teaching." },
+    { name: "bench", args: "[topic]", section: "Optimization", description: "Benchmark the current teaching policy." },
+    { name: "evolve", args: "[topic]", section: "Optimization", description: "Evolve teaching policies via MAP-Elites." },
+    { name: "prompt-evolve", args: "[name]", section: "Optimization", description: "Evolve a prompt template with ACE." },
+    { name: "prompt-eval", args: "<prompt>", section: "Optimization", description: "Evaluate a prompt template in a single pass." },
+    { name: "improve", args: "", section: "Self-Improvement", description: "Generate a self-improvement proposal." },
+    { name: "auto-improve", args: "[topic]", section: "Self-Improvement", description: "Run full self-improvement loop: bench → evolve → prompt-evolve → bench." },
+    { name: "feedback", args: "<up|down|confused> [topic] [--comment=text]", section: "Session", description: "Record session feedback with optional comment." },
+    { name: "timeline", args: "", section: "Review", description: "Show engagement timeline for all topics." },
+    { name: "learner-state", args: "", section: "Review", description: "Show learner profile and session history." },
+    { name: "due", args: "", section: "Review", description: "Show topics due for spaced-review." },
+    { name: "policy", args: "", section: "Session", description: "Show the active hyperteacher policy." },
+    { name: "speech", args: "", section: "Session", description: "Show optional voice-tool status." },
+    { name: "trace", args: "[query]", section: "Session", description: "Browse debug traces and artifacts." },
+    { name: "outputs", args: "", section: "Session", description: "Browse all Keating artifacts.", shellOnly: true },
+];
+export const cliCommandSpecs = [
+    { name: "shell", args: "[prompt]", section: "Core", description: "Launch the AI-powered hyperteacher shell." },
+    { name: "web", args: "[port]", section: "Core", description: "Start the browser UI dev server." },
+    { name: "doctor", args: "", section: "Core", description: "Inspect AI runtime and oxdraw availability." },
+    ...extensionCommandSpecs.filter(s => !s.shellOnly),
+];
+export function shellCommandSections() {
+    const map = new Map();
+    for (const spec of extensionCommandSpecs) {
+        if (spec.cliOnly)
+            continue;
+        const usage = `/${spec.name}${spec.args ? ` ${spec.args}` : ""}`;
+        if (!map.has(spec.section))
+            map.set(spec.section, []);
+        map.get(spec.section).push({ usage, description: spec.description });
+    }
+    return Array.from(map.entries()).map(([title, commands]) => ({ title, commands }));
+}
+export function cliCommandSections() {
+    const map = new Map();
+    for (const spec of cliCommandSpecs) {
+        const usage = `keating ${spec.name}${spec.args ? ` ${spec.args}` : ""}`;
+        if (!map.has(spec.section))
+            map.set(spec.section, []);
+        map.get(spec.section).push({ usage, description: spec.description });
+    }
+    return Array.from(map.entries()).map(([title, commands]) => ({ title, commands }));
+}
+export function formatSlashUsage(spec) {
+    return `/${spec.name}${spec.args ? ` ${spec.args}` : ""}`;
+}
+export function formatCliUsage(spec) {
+    return `keating ${spec.name}${spec.args ? ` ${spec.args}` : ""}`;
+}

package/dist/src/core/config.js

@@ -0,0 +1,120 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+export const DEFAULT_PI_PROVIDER = "google";
+export const DEFAULT_PI_MODEL = "gemini-3.1-pro-preview";
+export const FALLBACK_PI_MODELS = {
+    google: DEFAULT_PI_MODEL,
+    openai: "gpt-5.2",
+    anthropic: "claude-sonnet-4-5"
+};
+export const DEFAULT_KEATING_CONFIG = {
+    pi: {
+        runtimePreference: "prefer-standalone",
+        defaultProvider: DEFAULT_PI_PROVIDER,
+        defaultModel: DEFAULT_PI_MODEL,
+        defaultThinking: "medium"
+    },
+    speech: {
+        enabled: false,
+        defaultVoice: "conversational",
+        fastModel: "gemini-3.1-flash-live-preview",
+        steeringModel: "default"
+    },
+    debug: {
+        persistTraces: true,
+        traceTopLearners: 3,
+        consoleSummary: false
+    }
+};
+export function configPath(cwd) {
+    return resolve(cwd, "keating.config.json");
+}
+function sanitizeRuntimePreference(value) {
+    if (value === "standalone-only" || value === "prefer-standalone" || value === "embedded-only") {
+        return value;
+    }
+    return DEFAULT_KEATING_CONFIG.pi.runtimePreference;
+}
+function sanitizeOptionalString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function normalizeProvider(value) {
+    if (value === "google-gemini-cli")
+        return DEFAULT_PI_PROVIDER;
+    return value;
+}
+export async function loadKeatingConfig(cwd) {
+    const path = configPath(cwd);
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return {
+            pi: {
+                runtimePreference: sanitizeRuntimePreference(parsed.pi?.runtimePreference),
+                defaultProvider: normalizeProvider(sanitizeOptionalString(parsed.pi?.defaultProvider)) ?? DEFAULT_KEATING_CONFIG.pi.defaultProvider,
+                defaultModel: sanitizeOptionalString(parsed.pi?.defaultModel) ?? DEFAULT_KEATING_CONFIG.pi.defaultModel,
+                defaultThinking: sanitizeOptionalString(parsed.pi?.defaultThinking) ?? DEFAULT_KEATING_CONFIG.pi.defaultThinking
+            },
+            speech: {
+                enabled: typeof parsed.speech?.enabled === "boolean"
+                    ? parsed.speech.enabled
+                    : DEFAULT_KEATING_CONFIG.speech.enabled,
+                defaultVoice: sanitizeOptionalString(parsed.speech?.defaultVoice) ?? DEFAULT_KEATING_CONFIG.speech.defaultVoice,
+                fastModel: sanitizeOptionalString(parsed.speech?.fastModel) ?? DEFAULT_KEATING_CONFIG.speech.fastModel,
+                steeringModel: sanitizeOptionalString(parsed.speech?.steeringModel) ?? DEFAULT_KEATING_CONFIG.speech.steeringModel
+            },
+            debug: {
+                persistTraces: typeof parsed.debug?.persistTraces === "boolean"
+                    ? parsed.debug.persistTraces
+                    : DEFAULT_KEATING_CONFIG.debug.persistTraces,
+                traceTopLearners: typeof parsed.debug?.traceTopLearners === "number" && parsed.debug.traceTopLearners > 0
+                    ? Math.round(parsed.debug.traceTopLearners)
+                    : DEFAULT_KEATING_CONFIG.debug.traceTopLearners,
+                consoleSummary: typeof parsed.debug?.consoleSummary === "boolean"
+                    ? parsed.debug.consoleSummary
+                    : DEFAULT_KEATING_CONFIG.debug.consoleSummary
+            }
+        };
+    }
+    catch {
+        return DEFAULT_KEATING_CONFIG;
+    }
+}
+export async function writeKeatingConfig(cwd, config) {
+    await writeFile(configPath(cwd), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+export async function ensureConfig(cwd) {
+    const path = configPath(cwd);
+    if (!existsSync(path)) {
+        await writeKeatingConfig(cwd, DEFAULT_KEATING_CONFIG);
+    }
+}
+export function mergePiDefaults(config, args) {
+    const merged = [...args];
+    const hasProvider = merged.includes("--provider");
+    const hasModel = merged.includes("--model");
+    const hasThinking = merged.includes("--thinking");
+    if (!hasProvider && config.pi.defaultProvider) {
+        merged.unshift(config.pi.defaultProvider);
+        merged.unshift("--provider");
+    }
+    if (!hasModel && config.pi.defaultModel) {
+        merged.unshift(config.pi.defaultModel);
+        merged.unshift("--model");
+    }
+    if (!hasThinking && config.pi.defaultThinking) {
+        merged.unshift(config.pi.defaultThinking);
+        merged.unshift("--thinking");
+    }
+    return merged;
+}
+export function mergePiDefaultsWithOverrides(config, args, overrides = {}) {
+    return mergePiDefaults({
+        ...config,
+        pi: {
+            ...config.pi,
+            defaultProvider: overrides.provider ?? config.pi.defaultProvider,
+            defaultModel: overrides.model ?? config.pi.defaultModel
+        }
+    }, args);
+}

package/dist/src/core/engagement.js

@@ -0,0 +1,235 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { mean } from "./util.js";
+import { titleCase, slugify } from "./util.js";
+export const DEFAULT_ENGAGEMENT_POLICY = {
+    name: "spaced-revisit-default",
+    retentionHalfLifeDays: 7,
+    dueThreshold: 0.5,
+    minReviewIntervalDays: 1,
+    urgencyTiers: [21, 14, 7, 3]
+};
+const MS_PER_DAY = 86_400_000;
+function daysBetween(a, b) {
+    if (!a)
+        return 0;
+    const msA = typeof a === "string" ? new Date(a).getTime() : a.getTime();
+    const msB = typeof b === "string" ? new Date(b).getTime() : b.getTime();
+    if (!Number.isFinite(msA) || !Number.isFinite(msB))
+        return 0;
+    return Math.abs(msB - msA) / MS_PER_DAY;
+}
+/**
+ * Estimate retention using an exponential decay model inspired by Ebbinghaus.
+ * retention = mastery × e^(-t / (halfLife × masteryFactor))
+ *
+ * Higher mastery extends the half-life: a topic mastered at 0.9 decays
+ * more slowly than one mastered at 0.3.
+ */
+function estimateRetention(masteryEstimate, daysSinceLastSeen, halfLifeDays) {
+    const masteryFactor = 0.5 + masteryEstimate * 1.5; // range: 0.5–2.0
+    const effectiveHalfLife = halfLifeDays * masteryFactor;
+    const decay = Math.exp((-daysSinceLastSeen * Math.LN2) / effectiveHalfLife);
+    return Math.max(0, Math.min(1, masteryEstimate * decay));
+}
+/**
+ * Compute urgency: 0 = not urgent, 1 = critically overdue.
+ * Based on how far retention has fallen below the due threshold.
+ */
+function computeUrgency(estimatedRetention, dueThreshold, daysSinceLastSeen, tiers) {
+    if (daysSinceLastSeen < 1) {
+        return { urgency: 0, label: "fresh" };
+    }
+    if (estimatedRetention >= dueThreshold) {
+        return { urgency: Math.max(0, 1 - estimatedRetention / dueThreshold) * 0.3, label: "low" };
+    }
+    // Retention is below threshold — compute urgency based on how far below
+    const deficit = dueThreshold - estimatedRetention;
+    const rawUrgency = Math.min(1, deficit / dueThreshold + 0.3);
+    let label;
+    if (daysSinceLastSeen >= tiers[0]) {
+        label = "critical";
+    }
+    else if (daysSinceLastSeen >= tiers[1]) {
+        label = "high";
+    }
+    else if (daysSinceLastSeen >= tiers[2]) {
+        label = "moderate";
+    }
+    else {
+        label = "low";
+    }
+    return { urgency: rawUrgency, label };
+}
+/**
+ * Estimate when the next review should happen based on current mastery
+ * and the retention decay model.
+ */
+function estimateNextReview(lastSeen, masteryEstimate, halfLifeDays, dueThreshold) {
+    if (!lastSeen)
+        return new Date().toISOString();
+    if (masteryEstimate <= dueThreshold) {
+        return new Date().toISOString();
+    }
+    const masteryFactor = 0.5 + masteryEstimate * 1.5;
+    const effectiveHalfLife = halfLifeDays * masteryFactor;
+    const daysUntilDue = (-effectiveHalfLife * Math.log(dueThreshold / masteryEstimate)) / Math.LN2;
+    const lastSeenMs = new Date(lastSeen).getTime();
+    if (!Number.isFinite(lastSeenMs))
+        return new Date().toISOString();
+    return new Date(lastSeenMs + daysUntilDue * MS_PER_DAY).toISOString();
+}
+export function computeTopicEngagement(topic, policy, now = new Date()) {
+    const daysSince = daysBetween(topic.lastSeen, now);
+    const retention = estimateRetention(topic.masteryEstimate, daysSince, policy.retentionHalfLifeDays);
+    const isDue = retention < policy.dueThreshold && daysSince >= policy.minReviewIntervalDays;
+    const { urgency, label } = computeUrgency(retention, policy.dueThreshold, daysSince, policy.urgencyTiers);
+    const nextReview = estimateNextReview(topic.lastSeen, topic.masteryEstimate, policy.retentionHalfLifeDays, policy.dueThreshold);
+    // Defensive: older learner.json files (or partial writes) can have a topic
+    // entry missing `slug`. Derive one from any available label so the timeline
+    // never crashes the extension at session_start.
+    const rawSlug = topic.slug ||
+        (topic.title ? slugify(topic.title) : null) ||
+        "unknown-topic";
+    return {
+        slug: rawSlug,
+        title: titleCase(rawSlug.replace(/-/g, " ")),
+        domain: topic.domain,
+        lastSeen: topic.lastSeen,
+        daysSinceLastSeen: daysSince,
+        masteryEstimate: topic.masteryEstimate,
+        estimatedRetention: retention,
+        isDue,
+        urgency,
+        urgencyLabel: label,
+        sessionCount: topic.sessionCount,
+        nextReviewAt: nextReview
+    };
+}
+export function buildEngagementTimeline(state, policy = DEFAULT_ENGAGEMENT_POLICY, now = new Date()) {
+    const topics = (state.coveredTopics ?? [])
+        .filter((t) => Boolean(t))
+        .map(t => computeTopicEngagement(t, policy, now));
+    // Sort by urgency descending (most urgent first)
+    topics.sort((a, b) => b.urgency - a.urgency);
+    const dueCount = topics.filter(t => t.isDue).length;
+    const criticalCount = topics.filter(t => t.urgencyLabel === "critical").length;
+    const averageRetention = topics.length > 0 ? mean(topics.map(t => t.estimatedRetention)) : 1;
+    const oldestUnreviewedDays = topics.length > 0
+        ? Math.max(...topics.map(t => t.daysSinceLastSeen))
+        : 0;
+    return {
+        generatedAt: now.toISOString(),
+        policy,
+        topics,
+        summary: {
+            totalTopics: topics.length,
+            dueCount,
+            criticalCount,
+            averageRetention,
+            oldestUnreviewedDays
+        }
+    };
+}
+export function dueTopics(state, policy = DEFAULT_ENGAGEMENT_POLICY, now = new Date()) {
+    const timeline = buildEngagementTimeline(state, policy, now);
+    return timeline.topics.filter(t => t.isDue);
+}
+function retentionBar(retention) {
+    const filled = Math.round(retention * 10);
+    return "█".repeat(filled) + "░".repeat(10 - filled);
+}
+function urgencyEmoji(label) {
+    switch (label) {
+        case "critical": return "🔴";
+        case "high": return "🟠";
+        case "moderate": return "🟡";
+        case "low": return "🟢";
+        case "fresh": return "✨";
+    }
+}
+function formatDays(days) {
+    if (days < 1)
+        return "today";
+    if (days < 2)
+        return "1 day ago";
+    if (days < 7)
+        return `${Math.floor(days)} days ago`;
+    if (days < 14)
+        return "1 week ago";
+    if (days < 30)
+        return `${Math.floor(days / 7)} weeks ago`;
+    if (days < 60)
+        return "1 month ago";
+    return `${Math.floor(days / 30)} months ago`;
+}
+export function engagementTimelineToMarkdown(timeline) {
+    const lines = [
+        "# Engagement Timeline",
+        "",
+        `Generated: ${new Date(timeline.generatedAt).toLocaleString()}`,
+        "",
+        "## Summary",
+        "",
+        `- **Topics tracked:** ${timeline.summary.totalTopics}`,
+        `- **Due for review:** ${timeline.summary.dueCount}`,
+        `- **Critical:** ${timeline.summary.criticalCount}`,
+        `- **Average retention:** ${(timeline.summary.averageRetention * 100).toFixed(1)}%`,
+        `- **Oldest unreviewed:** ${formatDays(timeline.summary.oldestUnreviewedDays)}`,
+        ""
+    ];
+    if (timeline.topics.length === 0) {
+        lines.push("No topics covered yet. Start a lesson to begin tracking.");
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push("## Topics");
+    lines.push("");
+    lines.push("| Status | Topic | Last Seen | Retention | Mastery | Sessions | Next Review |");
+    lines.push("| :---: | --- | --- | --- | ---: | ---: | --- |");
+    for (const topic of timeline.topics) {
+        lines.push(`| ${urgencyEmoji(topic.urgencyLabel)} | **${topic.title}** (${topic.domain}) | ${formatDays(topic.daysSinceLastSeen)} | ${retentionBar(topic.estimatedRetention)} ${(topic.estimatedRetention * 100).toFixed(0)}% | ${(topic.masteryEstimate * 100).toFixed(0)}% | ${topic.sessionCount} | ${topic.isDue ? "**NOW**" : new Date(topic.nextReviewAt).toLocaleDateString()} |`);
+    }
+    lines.push("");
+    // Legend
+    lines.push("### Legend");
+    lines.push("");
+    lines.push("- 🔴 Critical — severely overdue, retention critically low");
+    lines.push("- 🟠 High — significantly overdue, review soon");
+    lines.push("- 🟡 Moderate — approaching review threshold");
+    lines.push("- 🟢 Low — retention adequate, no rush");
+    lines.push("- ✨ Fresh — recently covered");
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+export function dueTopicsToMarkdown(topics) {
+    if (topics.length === 0) {
+        return "# Due Topics\n\n✅ All topics are up to date! No reviews needed right now.\n";
+    }
+    const lines = [
+        "# Due Topics",
+        "",
+        `${topics.length} topic${topics.length === 1 ? "" : "s"} due for review:`,
+        ""
+    ];
+    for (const topic of topics) {
+        lines.push(`### ${urgencyEmoji(topic.urgencyLabel)} ${topic.title}`);
+        lines.push(`- Domain: ${topic.domain}`);
+        lines.push(`- Last seen: ${formatDays(topic.daysSinceLastSeen)}`);
+        lines.push(`- Retention: ${retentionBar(topic.estimatedRetention)} ${(topic.estimatedRetention * 100).toFixed(0)}%`);
+        lines.push(`- Mastery at last review: ${(topic.masteryEstimate * 100).toFixed(0)}%`);
+        lines.push(`- Sessions: ${topic.sessionCount}`);
+        lines.push("");
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function loadEngagementPolicy(filePath) {
+    try {
+        const raw = await readFile(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return DEFAULT_ENGAGEMENT_POLICY;
+    }
+}
+export async function saveEngagementPolicy(filePath, policy) {
+    await writeFile(filePath, `${JSON.stringify(policy, null, 2)}\n`, "utf8");
+}

package/dist/src/core/env.js

@@ -0,0 +1,9 @@
+import * as dotenv from "dotenv";
+const DEBUG_ENV_VALUES = new Set(["1", "true", "yes", "on"]);
+function envFlagEnabled(value) {
+    return value !== undefined && DEBUG_ENV_VALUES.has(value.toLowerCase());
+}
+export function loadEnv() {
+    const debug = envFlagEnabled(process.env.KEATING_DEBUG) || envFlagEnabled(process.env.DEBUG);
+    dotenv.config({ debug, quiet: !debug });
+}