dsh-plugin-lookatstudy 0.8.1

package/lib/index.mjs

@@ -0,0 +1,4447 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, sep } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { readFile, readdir } from "node:fs/promises";
+import https from "node:https";
+//#region src/config.ts
+/**
+* Plugin configuration schema (Schemastery) for dsh-plugin-lookatstudy.
+* @module dsh-plugin-lookatstudy/config
+*/
+/** Schemastery configuration validated at plugin load. */
+const Config = z.object({
+	mode: z.union([
+		"direct",
+		"guide",
+		"practice"
+	]).default("guide"),
+	statePath: z.string().default("")
+});
+//#endregion
+//#region src/markdown.ts
+/**
+* Server-side markdown → HTML for the study workbench's 讲解 view. Escapes
+* every HTML character first, then renders a pragmatic GFM subset (headings,
+* fenced code, inline code, bold/italic, links, lists, blockquotes, tables,
+* hr, paragraphs). Lesson bodies are imported teaching material, so raw HTML
+* never passes through.
+* @module dsh-plugin-lookatstudy/markdown
+*/
+/** Escape all HTML-significant characters. */
+function escapeHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** Render inline markup (code, bold, italic, links) over escaped text. */
+function inline(escaped) {
+	return escaped.replace(/`([^`]+)`/g, "<code>$1</code>").replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>").replace(/\*([^*]+)\*/g, "<em>$1</em>").replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, "<a href=\"$2\" target=\"_blank\" rel=\"noreferrer\">$1</a>");
+}
+/** True when the line opens a GFM table row (pipes with a delimiter row next). */
+function isTableRow(line) {
+	return line.trim().startsWith("|") && line.trim().endsWith("|") && line.includes("|", 1);
+}
+function isDelimiterRow(line) {
+	const trimmed = line.trim();
+	if (!trimmed.startsWith("|") || !trimmed.endsWith("|")) return false;
+	const cells = trimmed.replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+	return cells.length > 0 && cells.every((c) => /^:?-+:?$/.test(c));
+}
+/** Split a table row into trimmed cells (leading/trailing pipes removed). */
+function rowCells(line) {
+	return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+}
+/**
+* Render markdown text to sanitized HTML.
+* @param md - markdown source (lesson body).
+* @returns HTML string safe to inject into the page.
+*/
+function renderMarkdown(md) {
+	const lines = escapeHtml(md).split(/\r?\n/);
+	const out = [];
+	let i = 0;
+	const flushParagraph = (buffer) => {
+		if (buffer.length > 0) out.push(`<p>${inline(buffer.join(" "))}</p>`);
+	};
+	let paragraph = [];
+	while (i < lines.length) {
+		const line = lines[i];
+		const fence = /^```(\w*)\s*$/.exec(line.trim());
+		if (fence) {
+			flushParagraph(paragraph);
+			paragraph = [];
+			const lang = fence[1] ?? "";
+			const code = [];
+			i++;
+			while (i < lines.length && lines[i].trim() !== "```") {
+				code.push(lines[i]);
+				i++;
+			}
+			i++;
+			out.push(`<pre><code${lang === "" ? "" : ` class="lang-${lang}"`}>${code.join("\n")}</code></pre>`);
+			continue;
+		}
+		const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+		if (heading) {
+			flushParagraph(paragraph);
+			paragraph = [];
+			const level = heading[1].length;
+			out.push(`<h${level}>${inline(heading[2])}</h${level}>`);
+			i++;
+			continue;
+		}
+		if (/^\s*(-{3,}|\*{3,}|_{3,})\s*$/.test(line)) {
+			flushParagraph(paragraph);
+			paragraph = [];
+			out.push("<hr>");
+			i++;
+			continue;
+		}
+		if (/^\s*&gt;\s?/.test(line)) {
+			flushParagraph(paragraph);
+			paragraph = [];
+			const quote = [];
+			while (i < lines.length && /^\s*&gt;\s?/.test(lines[i])) {
+				quote.push(lines[i].replace(/^\s*&gt;\s?/, ""));
+				i++;
+			}
+			out.push(`<blockquote><p>${inline(quote.join(" "))}</p></blockquote>`);
+			continue;
+		}
+		if (/^\s*[-*+]\s+/.test(line)) {
+			flushParagraph(paragraph);
+			paragraph = [];
+			const items = [];
+			while (i < lines.length && /^\s*[-*+]\s+/.test(lines[i])) {
+				items.push(`<li>${inline(lines[i].replace(/^\s*[-*+]\s+/, ""))}</li>`);
+				i++;
+			}
+			out.push(`<ul>${items.join("")}</ul>`);
+			continue;
+		}
+		if (/^\s*\d+\.\s+/.test(line)) {
+			flushParagraph(paragraph);
+			paragraph = [];
+			const items = [];
+			while (i < lines.length && /^\s*\d+\.\s+/.test(lines[i])) {
+				items.push(`<li>${inline(lines[i].replace(/^\s*\d+\.\s+/, ""))}</li>`);
+				i++;
+			}
+			out.push(`<ol>${items.join("")}</ol>`);
+			continue;
+		}
+		if (isTableRow(line) && i + 1 < lines.length && isDelimiterRow(lines[i + 1])) {
+			flushParagraph(paragraph);
+			paragraph = [];
+			const headers = rowCells(line);
+			i += 2;
+			const rows = [];
+			while (i < lines.length && isTableRow(lines[i])) {
+				const cells = rowCells(lines[i]);
+				rows.push(`<tr>${cells.map((c) => `<td>${inline(c)}</td>`).join("")}</tr>`);
+				i++;
+			}
+			out.push(`<table><thead><tr>${headers.map((h) => `<th>${inline(h)}</th>`).join("")}</tr></thead><tbody>${rows.join("")}</tbody></table>`);
+			continue;
+		}
+		if (line.trim() === "") {
+			flushParagraph(paragraph);
+			paragraph = [];
+			i++;
+			continue;
+		}
+		paragraph.push(line.trim());
+		i++;
+	}
+	flushParagraph(paragraph);
+	return out.join("\n");
+}
+//#endregion
+//#region src/vendor/sm2.ts
+function computeSm2(prev, quality, now = /* @__PURE__ */ new Date()) {
+	let { easeFactor, intervalDays, repetitions } = prev;
+	if (quality < 3) {
+		repetitions = 0;
+		intervalDays = 1;
+	} else {
+		repetitions += 1;
+		if (repetitions === 1) intervalDays = 1;
+		else if (repetitions === 2) intervalDays = 6;
+		else intervalDays = Math.round(intervalDays * easeFactor);
+	}
+	const q = quality;
+	const delta = .1 - (5 - q) * (.08 + (5 - q) * .02);
+	easeFactor = Math.max(1.3, Math.min(3, easeFactor + delta));
+	const dueAt = new Date(now.getTime() + intervalDays * 24 * 60 * 60 * 1e3);
+	return {
+		easeFactor,
+		intervalDays,
+		repetitions,
+		dueAt: dueAt.toISOString()
+	};
+}
+//#endregion
+//#region src/vendor/bkt.ts
+/** 文献默认参数（ROADMAP R1：先验用文献默认，数据多后再调） */
+const BKT_DEFAULTS = {
+	pInit: .5,
+	pTransit: .1,
+	pSlip: .1,
+	pGuess: .2
+};
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+/**
+* 单次观测后的掌握度更新。
+*
+* @param prev   更新前的 P(L)。null/undefined → 用 params.pInit
+* @param correct 这次观测是否答对
+* @param params BKT 四参数（默认文献值）
+* @returns 新的 P(L)，已 clamp 到 [0,1]
+*/
+function updateMastery(prev, correct, params = BKT_DEFAULTS) {
+	const pL = clamp01(prev ?? params.pInit);
+	const { pTransit, pSlip, pGuess } = params;
+	const pObsGivenL = correct ? 1 - pSlip : pSlip;
+	const pObsGivenNotL = correct ? pGuess : 1 - pGuess;
+	const pObs = pObsGivenL * pL + pObsGivenNotL * (1 - pL);
+	if (pObs === 0) return pL;
+	const pLGivenObs = pObsGivenL * pL / pObs;
+	return clamp01(pLGivenObs + pTransit * (1 - pLGivenObs));
+}
+/**
+* 把 mastery 概率映射成 crown level（1-5）给 UI 用。
+* < 0.3 → 1, <0.5 → 2, <0.7 → 3, <0.9 → 4, ≥0.9 → 5。null → 0。
+*/
+function masteryToCrown(mastery) {
+	if (mastery == null) return 0;
+	if (mastery < .3) return 1;
+	if (mastery < .5) return 2;
+	if (mastery < .7) return 3;
+	if (mastery < .9) return 4;
+	return 5;
+}
+//#endregion
+//#region src/state.ts
+/**
+* Learning state: courses → sections → lessons with mastery-driven gating,
+* per-concept (KC) BKT tracking aggregated as the weakest concept, SM-2
+* spaced repetition, pending mastery proposals, friction log, learner
+* memory, and Cornell-style notes. Persisted as one JSON file; every
+* mutation is saved synchronously.
+* @module dsh-plugin-lookatstudy/state
+*/
+const DAY_MS = 864e5;
+/** Mastery at or above this graduates the lesson automatically (LookatStudy MASTERED_MASTERY_THRESHOLD). */
+const MASTERED_THRESHOLD = .9;
+/** Concepts below this mastery are flagged weak (LookatStudy kcContext). */
+const WEAK_CONCEPT_THRESHOLD = .7;
+const FRICTION_CAP = 10;
+/** Fresh empty state for a first run. */
+function emptyState() {
+	return {
+		version: 2,
+		courses: [],
+		mode: "guide",
+		focus: null,
+		memoryGlobal: null,
+		memoryPatterns: {},
+		proposals: [],
+		lessonSessions: {}
+	};
+}
+/**
+* Resolve the state-file location: explicit config path wins, otherwise
+* `$DSH_HOME ?? ~/.dsh` under a plugin-named subdirectory.
+* @param configured - Config `statePath` (empty means default).
+* @returns absolute state-file path.
+*/
+function resolveStatePath(configured) {
+	if (configured !== "") return configured;
+	return join(process.env.DSH_HOME ?? join(homedir(), ".dsh"), "lookatstudy-plugin", "state.json");
+}
+/**
+* Load persisted state; a missing file yields empty state, a corrupt file fails loud.
+* v1 → v2 migration: `completed` lessons become `mastered`, lessons gain `kind`
+* (default `study`). Newer files than this code knows are rejected.
+* @param path - state-file path.
+* @returns the loaded state.
+*/
+function loadState(path) {
+	if (!existsSync(path)) return emptyState();
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		throw new Error(`lookatstudy-plugin: state file is not valid JSON: ${path} (${String(error)})`);
+	}
+	if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.courses)) throw new Error(`lookatstudy-plugin: state file has an unexpected shape: ${path}`);
+	const raw = parsed;
+	if (raw.version !== void 0 && raw.version > 2) throw new Error(`lookatstudy-plugin: state file version ${raw.version} is newer than this plugin supports: ${path}`);
+	const courses = raw.courses.map((course) => ({
+		...course,
+		sections: course.sections.map((section) => ({
+			...section,
+			lessons: section.lessons.map((lesson) => ({
+				...lesson,
+				kind: lesson.kind ?? "study",
+				status: lesson.status === "completed" ? "mastered" : lesson.status
+			}))
+		}))
+	}));
+	for (const course of courses) course.sections.forEach((section, si) => {
+		const hasExam = section.lessons.some((l) => l.kind === "exam");
+		const studyCount = section.lessons.filter((l) => l.kind === "study").length;
+		if (!hasExam && studyCount >= 2) section.lessons.push({
+			...freshLesson(`${section.title} · 章节测验`, `${section.anchor}#exam`, "", "exam"),
+			id: `${course.id}:${si}:${section.lessons.length}`,
+			status: "available"
+		});
+	});
+	return {
+		version: 2,
+		courses,
+		mode: raw.mode ?? "guide",
+		focus: raw.focus ?? null,
+		memoryGlobal: raw.memoryGlobal ?? null,
+		memoryPatterns: raw.memoryPatterns ?? {},
+		proposals: raw.proposals ?? [],
+		lessonSessions: raw.lessonSessions ?? {}
+	};
+}
+/**
+* Persist state atomically (write a sibling temp file, then rename).
+* @param path - state-file path.
+* @param state - state to persist.
+*/
+function saveState(path, state) {
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+	renameSync(tmp, path);
+}
+/**
+* Slugify a course title into an id prefix: lowercase alphanumerics joined by `-`.
+* @param title - course title.
+* @returns slug, at least `course`.
+*/
+function slugify(title) {
+	const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return slug === "" ? "course" : slug;
+}
+function freshLesson(title, anchor, body, kind = "study") {
+	return {
+		id: "",
+		title,
+		anchor,
+		body,
+		kind,
+		status: "locked",
+		concepts: null,
+		conceptMastery: null,
+		mastery: null,
+		attempts: 0,
+		correctCount: 0,
+		lastAnsweredAt: null,
+		completedAt: null,
+		sm2: null,
+		dueAt: null,
+		friction: [],
+		memory: null,
+		notes: []
+	};
+}
+/**
+* Import a parsed course. Idempotent: the id is the title slug, so importing
+* the same source again returns the existing course unchanged (LookatStudy's
+* pasted-markdown contract, applied to every source). Study lessons are gated
+* (first available, rest locked); every study section with ≥2 lessons also
+* gets a 章节测验 exam node (available in state, gated on sibling mastery in
+* the UI — LookatStudy's rule).
+* @param state - state to mutate.
+* @param parsed - course tree from an importer.
+* @param source - import origin.
+* @param sourceRef - markdown/folder/repo reference for display.
+* @returns the imported (or pre-existing) course.
+*/
+function importCourse(state, parsed, source, sourceRef) {
+	const id = slugify(parsed.title);
+	const existing = state.courses.find((c) => c.id === id);
+	if (existing) return existing;
+	const course = {
+		id,
+		title: parsed.title,
+		source,
+		sourceRef,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+		sections: parsed.sections.map((section) => {
+			const lessons = section.lessons.map((lesson) => freshLesson(lesson.title, lesson.anchor, lesson.body, lesson.world === "practice" ? "practice" : "study"));
+			if (section.world !== "practice" && lessons.filter((l) => l.kind === "study").length >= 2) lessons.push(freshLesson(`${section.title} · 章节测验`, `${section.anchor}#exam`, section.examBody ?? "", "exam"));
+			return {
+				title: section.title,
+				anchor: section.anchor,
+				lessons
+			};
+		})
+	};
+	let first = true;
+	for (let si = 0; si < course.sections.length; si++) {
+		const lessons = course.sections[si].lessons;
+		for (let li = 0; li < lessons.length; li++) {
+			const lesson = lessons[li];
+			lesson.id = `${id}:${si}:${li}`;
+			if (lesson.kind === "exam" || lesson.kind === "practice") lesson.status = "available";
+			else if (first) {
+				lesson.status = "available";
+				first = false;
+			}
+		}
+	}
+	state.courses.push(course);
+	return course;
+}
+/**
+* Drop a course from state; unknown ids fail loud.
+* @param state - state to mutate.
+* @param courseId - course to remove.
+*/
+function deleteCourse(state, courseId) {
+	const i = state.courses.findIndex((c) => c.id === courseId);
+	if (i < 0) throw new Error(`lookatstudy-plugin: unknown course id ${JSON.stringify(courseId)}`);
+	state.courses.splice(i, 1);
+	state.proposals = state.proposals.filter((p) => !p.lessonId.startsWith(`${courseId}:`));
+}
+/**
+* Locate a course; unknown ids fail loud.
+* @param state - state to search.
+* @param courseId - course id.
+* @returns the course.
+*/
+function findCourse(state, courseId) {
+	const course = state.courses.find((c) => c.id === courseId);
+	if (!course) throw new Error(`lookatstudy-plugin: unknown course id ${JSON.stringify(courseId)}`);
+	return course;
+}
+/**
+* Locate a lesson by its hierarchical id; unknown ids fail loud.
+* @param state - state to search.
+* @param lessonId - lesson id (`courseId:sectionIndex:lessonIndex`).
+* @returns course/section/lesson references.
+*/
+function findLesson(state, lessonId) {
+	const parts = lessonId.split(":");
+	const li = parts.pop();
+	const si = parts.pop();
+	const course = findCourse(state, parts.join(":"));
+	const sectionIndex = Number.parseInt(si ?? "", 10);
+	const lessonIndex = Number.parseInt(li ?? "", 10);
+	if (Number.isInteger(sectionIndex) && Number.isInteger(lessonIndex)) {
+		const section = course.sections[sectionIndex];
+		const lesson = section?.lessons[lessonIndex];
+		if (lesson && lesson.id === lessonId) return {
+			course,
+			section,
+			lesson
+		};
+	}
+	throw new Error(`lookatstudy-plugin: unknown lesson id ${JSON.stringify(lessonId)}`);
+}
+/**
+* Find the next STUDY lesson after the given one in flat course order
+* (practice/exam nodes never gate the path).
+* @param course - course to walk.
+* @param lessonId - current lesson id.
+* @returns the next study lesson, or null at the end of the path.
+*/
+function nextLesson(course, lessonId) {
+	const flat = course.sections.flatMap((s) => s.lessons);
+	const i = flat.findIndex((l) => l.id === lessonId);
+	for (let j = i + 1; j < flat.length; j++) if (flat[j].kind === "study") return flat[j];
+	return null;
+}
+/**
+* LookatStudy's dual-track unlock, fired whenever the current lesson reaches
+* mastery ≥0.5 (which includes the 0.5 seed from the first attempt): unlock
+* (1) the next locked study lesson later in the same section AND (2) the
+* first study lesson of the next section. Only `locked` nodes ever change;
+* nothing re-locks.
+* @param ref - the lesson that reached the threshold.
+* @returns the lessons unlocked by this call.
+*/
+function unlockAfter(ref) {
+	const unlocked = [];
+	const lessons = ref.section.lessons;
+	const li = lessons.indexOf(ref.lesson);
+	for (let i = li + 1; i < lessons.length; i++) {
+		const next = lessons[i];
+		if (next.kind !== "study") continue;
+		if (next.status === "locked") {
+			next.status = "available";
+			unlocked.push({
+				id: next.id,
+				title: next.title
+			});
+		}
+		break;
+	}
+	const si = ref.course.sections.indexOf(ref.section);
+	const nextSection = ref.course.sections[si + 1];
+	if (nextSection !== void 0) {
+		const first = nextSection.lessons.find((l) => l.kind === "study");
+		if (first !== void 0 && first.status === "locked") {
+			first.status = "available";
+			unlocked.push({
+				id: first.id,
+				title: first.title
+			});
+		}
+	}
+	return unlocked;
+}
+/** Recompute lesson mastery as the weakest concept once KCs exist. */
+function aggregateMastery(lesson) {
+	if (lesson.concepts === null || lesson.conceptMastery === null) return;
+	const values = lesson.concepts.map((_, i) => lesson.conceptMastery[i] ?? .5);
+	lesson.mastery = Math.min(...values);
+}
+/**
+* Graduate a lesson: mark mastered, seed its SM-2 schedule if absent (first
+* review due tomorrow), and run the dual-track unlock.
+*/
+function graduate(lesson, course, now) {
+	if (lesson.status !== "mastered") {
+		lesson.status = "mastered";
+		lesson.completedAt = now.toISOString();
+		if (lesson.sm2 === null) {
+			lesson.sm2 = {
+				easeFactor: 2.5,
+				intervalDays: 1,
+				repetitions: 0
+			};
+			lesson.dueAt = new Date(now.getTime() + DAY_MS).toISOString();
+		}
+	}
+	const si = course.sections.findIndex((s) => s.lessons.includes(lesson));
+	return unlockAfter({
+		course,
+		section: course.sections[si],
+		lesson
+	});
+}
+/** Whether every study lesson of the course is mastered. */
+function courseComplete(course) {
+	return course.sections.every((s) => s.lessons.every((l) => l.kind !== "study" || l.status === "mastered"));
+}
+/** Describe the path effects of a mastery change (early unlock, graduation). */
+function applyProgression(ref, now) {
+	const before = ref.lesson.status;
+	const graduated = ref.lesson.mastery !== null && ref.lesson.mastery >= .9;
+	let unlocked = [];
+	if (graduated && before !== "mastered") unlocked = graduate(ref.lesson, ref.course, now);
+	else if (ref.lesson.mastery !== null && ref.lesson.mastery >= .5) unlocked = unlockAfter(ref);
+	return {
+		graduated: graduated && before !== "mastered",
+		unlocked,
+		nextDue: ref.lesson.dueAt,
+		courseComplete: courseComplete(ref.course)
+	};
+}
+/**
+* Open a lesson for study (LookatStudy markNodeAttempted): locked lessons
+* fail loud; the first open of an `available` lesson marks it `in_progress`,
+* seeds mastery at the BKT prior (0.5), and — because 0.5 already meets the
+* unlock threshold — runs the dual-track unlock, so merely starting a lesson
+* lights up the next ones.
+* @param state - state to mutate.
+* @param lessonId - lesson to open.
+* @param now - current time.
+* @returns the lesson ref, whether this open started it, and what unlocked.
+*/
+function attemptLesson(state, lessonId, now) {
+	const ref = findLesson(state, lessonId);
+	if (ref.lesson.status === "locked") throw new Error(`lookatstudy-plugin: lesson ${JSON.stringify(lessonId)} is locked; complete earlier lessons first`);
+	if (ref.lesson.status !== "available") return {
+		ref,
+		started: false,
+		unlocked: []
+	};
+	ref.lesson.status = "in_progress";
+	ref.lesson.lastAnsweredAt = now.toISOString();
+	if (ref.lesson.mastery === null) ref.lesson.mastery = .5;
+	return {
+		ref,
+		started: true,
+		unlocked: unlockAfter(ref)
+	};
+}
+/**
+* Record one graded answer against a lesson: attribute it to one knowledge
+* component when named, update BKT (per-KC, aggregated as the weakest),
+* nudge the SM-2 schedule when one exists, and apply mastery-driven
+* progression (early unlock at 0.5, graduation at 0.9). Locked lessons fail
+* loud — open the lesson first (study_lesson does).
+* @param state - state to mutate.
+* @param lessonId - lesson to update.
+* @param correct - whether the learner answered correctly.
+* @param concept - concept title the question tested, when attributable.
+* @param now - current time.
+* @returns mastery transition, KC attribution, and progression effects.
+*/
+function recordAnswer(state, lessonId, correct, concept, now) {
+	const ref = findLesson(state, lessonId);
+	if (ref.lesson.status === "locked") throw new Error(`lookatstudy-plugin: lesson ${JSON.stringify(lessonId)} is locked; open it with study_lesson first`);
+	if (ref.lesson.status === "available") ref.lesson.status = "in_progress";
+	const kcIndex = concept === void 0 ? void 0 : ref.lesson.concepts?.findIndex((c) => c.title === concept);
+	if (concept !== void 0 && (ref.lesson.concepts === null || kcIndex === void 0 || kcIndex < 0)) throw new Error(`lookatstudy-plugin: unknown concept ${JSON.stringify(concept)} on lesson ${JSON.stringify(lessonId)} — define concepts with study_define_concepts first`);
+	const prev = ref.lesson.mastery;
+	if (ref.lesson.concepts !== null && kcIndex !== void 0) {
+		const masteries = ref.lesson.conceptMastery ?? {};
+		masteries[kcIndex] = updateMastery(masteries[kcIndex], correct);
+		ref.lesson.conceptMastery = masteries;
+		aggregateMastery(ref.lesson);
+	} else if (ref.lesson.concepts !== null) {
+		const masteries = ref.lesson.conceptMastery ?? {};
+		ref.lesson.concepts.forEach((_, i) => {
+			masteries[i] = updateMastery(masteries[i], correct);
+		});
+		ref.lesson.conceptMastery = masteries;
+		aggregateMastery(ref.lesson);
+	} else ref.lesson.mastery = updateMastery(prev, correct);
+	ref.lesson.attempts += 1;
+	if (correct) ref.lesson.correctCount += 1;
+	ref.lesson.lastAnsweredAt = now.toISOString();
+	if (ref.lesson.sm2 !== null) {
+		const result = computeSm2(ref.lesson.sm2, correct ? 5 : 2, now);
+		ref.lesson.sm2 = {
+			easeFactor: result.easeFactor,
+			intervalDays: result.intervalDays,
+			repetitions: result.repetitions
+		};
+		ref.lesson.dueAt = result.dueAt;
+	}
+	const progression = applyProgression(ref, now);
+	return {
+		ref,
+		concept: kcIndex === void 0 ? null : {
+			title: concept,
+			mastery: ref.lesson.conceptMastery[kcIndex]
+		},
+		prevMastery: prev ?? 0,
+		newMastery: ref.lesson.mastery ?? 0,
+		crown: masteryToCrown(ref.lesson.mastery),
+		mastered: (ref.lesson.mastery ?? 0) >= MASTERED_THRESHOLD,
+		progression
+	};
+}
+/**
+* Complete a lesson explicitly (the manual path; mastery graduation is the
+* automatic one). Locked lessons fail loud.
+* @param state - state to mutate.
+* @param lessonId - lesson to complete.
+* @param now - current time.
+* @returns completion result including the unlocked lessons.
+*/
+function completeLesson(state, lessonId, now) {
+	const ref = findLesson(state, lessonId);
+	if (ref.lesson.status === "locked") throw new Error(`lookatstudy-plugin: lesson ${JSON.stringify(lessonId)} is locked; complete earlier lessons first`);
+	return {
+		ref,
+		unlocked: graduate(ref.lesson, ref.course, now),
+		dueAt: ref.lesson.dueAt ?? new Date(now.getTime() + DAY_MS).toISOString(),
+		courseComplete: courseComplete(ref.course)
+	};
+}
+/**
+* Define (or replace) a lesson's knowledge components — the independently
+* quizzable units per-KC mastery tracks. Existing per-KC mastery resets.
+* @param state - state to mutate.
+* @param lessonId - lesson to describe.
+* @param concepts - 2–7 short concepts.
+*/
+function defineConcepts(state, lessonId, concepts) {
+	const ref = findLesson(state, lessonId);
+	if (concepts.length < 2 || concepts.length > 7) throw new Error(`lookatstudy-plugin: define 2–7 concepts (got ${concepts.length})`);
+	for (const def of concepts) if (def.title.trim() === "" || def.description.trim() === "") throw new Error("lookatstudy-plugin: every concept needs a non-empty title and description");
+	ref.lesson.concepts = concepts.map((c) => ({
+		title: c.title.trim(),
+		description: c.description.trim()
+	}));
+	ref.lesson.conceptMastery = {};
+	aggregateMastery(ref.lesson);
+}
+/**
+* Log one silent friction event (confusion / block / frustration).
+* @param state - state to mutate.
+* @param lessonId - lesson it happened on, when attributable.
+* @param category - friction category.
+* @param summary - optional one-line description.
+* @param now - current time.
+*/
+function addFriction(state, lessonId, category, summary, now) {
+	const entry = {
+		category,
+		summary,
+		at: now.toISOString()
+	};
+	if (lessonId === null) return;
+	const ref = findLesson(state, lessonId);
+	ref.lesson.friction.push(entry);
+	if (ref.lesson.friction.length > FRICTION_CAP) ref.lesson.friction.splice(0, ref.lesson.friction.length - FRICTION_CAP);
+}
+/**
+* Set a memory slot. The tutor merges mentally before writing (read the
+* current slot, then send the merged 1–3 sentence text).
+* @param state - state to mutate.
+* @param category - which slot.
+* @param lessonId - lesson for the `lesson` slot.
+* @param content - merged slot content.
+* @returns the previous content, for the tutor's merge flow.
+*/
+function setMemory(state, category, content, lessonId) {
+	if (category === "global") {
+		const prev = state.memoryGlobal;
+		state.memoryGlobal = content;
+		return prev;
+	}
+	if (category === "pattern") {
+		const course = findCourse(state, lessonId === void 0 ? "" : lessonId.slice(0, lessonId.lastIndexOf(":")));
+		const prev = state.memoryPatterns[course.id] ?? null;
+		state.memoryPatterns[course.id] = content;
+		return prev;
+	}
+	if (lessonId === void 0) throw new Error("lookatstudy-plugin: the lesson memory slot needs a lessonId");
+	const ref = findLesson(state, lessonId);
+	const prev = ref.lesson.memory;
+	ref.lesson.memory = content;
+	return prev;
+}
+/**
+* Add one notebook entry to a lesson's Cornell zones.
+* @param state - state to mutate.
+* @param lessonId - lesson the note belongs to (required: notes anchor to material).
+* @param zone - Cornell zone.
+* @param title - short entry title.
+* @param text - entry body (markdown for the understand zone).
+* @param source - where the content came from.
+* @param quote - verbatim source quote for record-zone notes.
+* @param now - current time.
+* @returns the created note.
+*/
+function addNote(state, lessonId, zone, title, text, source, quote, now) {
+	const ref = findLesson(state, lessonId);
+	const note = {
+		id: `${lessonId}:n${ref.lesson.notes.length}`,
+		zone,
+		title,
+		text,
+		source,
+		quote,
+		at: now.toISOString()
+	};
+	ref.lesson.notes.push(note);
+	return note;
+}
+/**
+* Propose early mastery graduation for the learner to accept or reject in chat.
+* @param state - state to mutate.
+* @param lessonId - lesson judged mastered.
+* @param rationale - why the tutor believes it is mastered.
+* @param now - current time.
+* @returns the pending proposal.
+*/
+function proposeMastery(state, lessonId, rationale, now) {
+	if (findLesson(state, lessonId).lesson.status === "locked") throw new Error(`lookatstudy-plugin: lesson ${JSON.stringify(lessonId)} is locked`);
+	const pending = state.proposals.find((p) => p.lessonId === lessonId && p.status === "pending");
+	if (pending) return pending;
+	const proposal = {
+		id: `prop-${randomBytes(3).toString("hex")}`,
+		lessonId,
+		rationale,
+		status: "pending",
+		createdAt: now.toISOString()
+	};
+	state.proposals.push(proposal);
+	return proposal;
+}
+/**
+* Resolve a pending proposal: acceptance floors every concept (and the
+* lesson) to 0.95 and graduates; rejection changes nothing.
+* @param state - state to mutate.
+* @param proposalId - proposal to resolve.
+* @param accept - learner's decision.
+* @param now - current time.
+* @returns the resolved proposal.
+*/
+function resolveProposal(state, proposalId, accept, now) {
+	const proposal = state.proposals.find((p) => p.id === proposalId);
+	if (!proposal) throw new Error(`lookatstudy-plugin: unknown proposal id ${JSON.stringify(proposalId)}`);
+	if (proposal.status !== "pending") throw new Error(`lookatstudy-plugin: proposal ${JSON.stringify(proposalId)} is already ${proposal.status}`);
+	if (accept) {
+		const ref = findLesson(state, proposal.lessonId);
+		if (ref.lesson.concepts !== null && ref.lesson.conceptMastery !== null) {
+			for (let i = 0; i < ref.lesson.concepts.length; i++) ref.lesson.conceptMastery[i] = Math.max(ref.lesson.conceptMastery[i] ?? 0, .95);
+			aggregateMastery(ref.lesson);
+		} else ref.lesson.mastery = Math.max(ref.lesson.mastery ?? 0, .95);
+		graduate(ref.lesson, ref.course, now);
+		if (ref.lesson.sm2 !== null) {
+			const review = computeSm2(ref.lesson.sm2, 5, now);
+			ref.lesson.sm2 = {
+				easeFactor: review.easeFactor,
+				intervalDays: review.intervalDays,
+				repetitions: review.repetitions
+			};
+			ref.lesson.dueAt = review.dueAt;
+		}
+	}
+	proposal.status = accept ? "applied" : "rejected";
+	return proposal;
+}
+/**
+* Record an SM-2 review grade and advance the schedule.
+* @param state - state to mutate.
+* @param lessonId - lesson being reviewed.
+* @param quality - SM-2 quality grade 0–5.
+* @param now - current time.
+* @returns the advanced schedule.
+*/
+function recordReview(state, lessonId, quality, now) {
+	const ref = findLesson(state, lessonId);
+	if (!ref.lesson.sm2) throw new Error(`lookatstudy-plugin: lesson ${JSON.stringify(lessonId)} has no review schedule; complete it first`);
+	const result = computeSm2(ref.lesson.sm2, quality, now);
+	ref.lesson.sm2 = {
+		easeFactor: result.easeFactor,
+		intervalDays: result.intervalDays,
+		repetitions: result.repetitions
+	};
+	ref.lesson.dueAt = result.dueAt;
+	return {
+		ref,
+		intervalDays: result.intervalDays,
+		repetitions: result.repetitions,
+		easeFactor: result.easeFactor,
+		dueAt: result.dueAt
+	};
+}
+/**
+* List mastered lessons whose SM-2 review is due, oldest first.
+* @param state - state to scan.
+* @param courseId - restrict to one course when provided.
+* @param now - current time.
+* @returns due items across the requested scope.
+*/
+function dueReviews(state, courseId, now) {
+	const courses = courseId ? [findCourse(state, courseId)] : state.courses;
+	const due = [];
+	for (const course of courses) for (const lesson of course.sections.flatMap((s) => s.lessons)) {
+		if (lesson.status !== "mastered" || lesson.dueAt === null) continue;
+		if (Date.parse(lesson.dueAt) > now.getTime()) continue;
+		due.push({
+			lessonId: lesson.id,
+			courseId: course.id,
+			courseTitle: course.title,
+			lessonTitle: lesson.title,
+			dueAt: lesson.dueAt,
+			overdueDays: Math.floor((now.getTime() - Date.parse(lesson.dueAt)) / DAY_MS)
+		});
+	}
+	due.sort((a, b) => Date.parse(a.dueAt) - Date.parse(b.dueAt));
+	return due;
+}
+/**
+* Summarize every course: counts, average mastery, due reviews, and the
+* current (first not-yet-mastered study) lesson.
+* @param state - state to summarize.
+* @param now - current time.
+* @returns one summary per course, in import order.
+*/
+function courseSummaries(state, now) {
+	return state.courses.map((course) => {
+		const lessons = course.sections.flatMap((s) => s.lessons);
+		const answered = lessons.filter((l) => l.mastery !== null);
+		const due = dueReviews({
+			...emptyState(),
+			courses: [course]
+		}, course.id, now);
+		const current = lessons.find((l) => l.kind === "study" && l.status !== "mastered") ?? null;
+		const avg = answered.length === 0 ? null : answered.reduce((sum, l) => sum + (l.mastery ?? 0), 0) / answered.length;
+		return {
+			courseId: course.id,
+			title: course.title,
+			source: course.source,
+			createdAt: course.createdAt,
+			total: lessons.length,
+			mastered: lessons.filter((l) => l.status === "mastered").length,
+			available: lessons.filter((l) => l.status === "available").length,
+			avgMasteryPct: avg === null ? null : Math.round(avg * 100),
+			dueCount: due.length,
+			currentLessonId: current?.id ?? null
+		};
+	});
+}
+/**
+* Teaching-strategy band for a mastery level (LookatStudy learner-model bands).
+* @param mastery - lesson mastery, null before any answer.
+* @returns the strategy instruction for the tutor.
+*/
+function strategyBand(mastery) {
+	if (mastery === null || mastery < .1) return "先建立直觉再讲细节:用类比引入概念,分步骤引导,不堆术语。";
+	if (mastery < .4) return "用提问检验理解,发现误解时立即纠正,多给实际例子。";
+	if (mastery < .7) return "深化理解:对比相似概念的区别,考察边界情况,可以出有迷惑性的问题。";
+	return "综合应用阶段:让学习者尝试用自己的话教回来(费曼技巧),考虑提议标记掌握。";
+}
+/**
+* Project a lesson's concepts with mastery and weak flags.
+* @param lesson - lesson to project.
+* @returns concept views in definition order, or null before concepts exist.
+*/
+function conceptViews(lesson) {
+	if (lesson.concepts === null) return null;
+	return lesson.concepts.map((c, i) => {
+		const mastery = lesson.conceptMastery?.[i] ?? .5;
+		return {
+			title: c.title,
+			masteryPct: Math.round(mastery * 100),
+			weak: mastery < WEAK_CONCEPT_THRESHOLD,
+			tested: lesson.conceptMastery !== null && i in lesson.conceptMastery ? 1 : 0
+		};
+	});
+}
+/** The four consolidation starters attached to a lesson (LookatStudy templates). */
+function starterPrompts(lessonTitle) {
+	return [
+		{
+			label: "🔬 深入这点",
+			message: `帮我深入讲讲「${lessonTitle}」刚才那个核心点——展开它的结构、细节和容易忽略的边界。`,
+			effect: "none"
+		},
+		{
+			label: "💡 举个例子",
+			message: `给我一个「${lessonTitle}」的实际例子或用法,让我更具体地理解。`,
+			effect: "none"
+		},
+		{
+			label: "📝 考考我",
+			message: `出一道关于「${lessonTitle}」的应用题考考我,看我是否真懂了——我答完请判断对错。`,
+			effect: "mastery"
+		},
+		{
+			label: "🤔 我没太懂",
+			message: `关于「${lessonTitle}」,我有地方不太懂,帮我理一理——先问我是哪里不清楚。`,
+			effect: "friction"
+		}
+	];
+}
+/**
+* Compose the learner snapshot for the focused lesson (or course-wide when
+* no focus): strategy band, weak concepts, recent friction, memory slots,
+* due count, pending proposal. The tutor persona's volatile tail.
+* @param state - state to read.
+* @param now - current time.
+* @returns the snapshot value.
+*/
+function learnerSnapshot(state, now) {
+	let ref = state.focus === null ? null : tryFindLesson(state, state.focus.lessonId);
+	if (ref === null && state.courses.length > 0) {
+		const lessons = state.courses[0].sections.flatMap((s) => s.lessons);
+		const current = lessons.find((l) => l.kind === "study" && l.status === "in_progress") ?? lessons.find((l) => l.kind === "study" && l.status === "available") ?? null;
+		ref = current === null ? null : {
+			course: state.courses[0],
+			section: state.courses[0].sections.find((s) => s.lessons.includes(current)),
+			lesson: current
+		};
+	}
+	return {
+		focus: ref === null ? null : {
+			lessonId: ref.lesson.id,
+			courseTitle: ref.course.title,
+			lessonTitle: ref.lesson.title,
+			masteryPct: ref.lesson.mastery === null ? null : Math.round(ref.lesson.mastery * 100),
+			status: ref.lesson.status
+		},
+		strategy: ref === null ? null : strategyBand(ref.lesson.mastery),
+		concepts: ref === null ? null : conceptViews(ref.lesson),
+		friction: ref === null ? [] : ref.lesson.friction.slice(-5),
+		memoryGlobal: state.memoryGlobal,
+		memoryLesson: ref?.lesson.memory ?? null,
+		memoryPattern: ref === null ? null : state.memoryPatterns[ref.course.id] ?? null,
+		dueCount: dueReviews(state, void 0, now).length,
+		pendingProposal: state.proposals.find((p) => p.status === "pending") ?? null
+	};
+}
+/** findLesson that returns null instead of throwing (snapshot focus may be stale). */
+function tryFindLesson(state, lessonId) {
+	try {
+		return findLesson(state, lessonId);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/dashboard.ts
+/**
+* The study tab's HTTP API under `/lookatstudy/api/*`: the polled state feed
+* and the tab's write actions (focus, mode, lesson-session binding, course
+* deletion, study-workspace path), reading the same live plugin state the
+* tutor tools write. The v0.3 standalone workbench page and its reverse
+* message channel were removed once the in-client study tab superseded them.
+* @module dsh-plugin-lookatstudy/dashboard
+*/
+/**
+* Assemble the whole workbench state (pure read; the lesson HTML is rendered
+* server-side from the sanitized markdown pipeline).
+* @param state - live learning state.
+* @param now - current time.
+* @returns the page's data contract.
+*/
+function workbenchState(state, now) {
+	const focusId = state.focus?.lessonId ?? null;
+	const dueIds = new Set(dueReviews(state, void 0, now).map((d) => d.lessonId));
+	const courses = state.courses.map((course) => {
+		const lessons = course.sections.flatMap((s) => s.lessons);
+		const answered = lessons.filter((l) => l.mastery !== null);
+		return {
+			courseId: course.id,
+			title: course.title,
+			mastered: lessons.filter((l) => l.status === "mastered").length,
+			total: lessons.length,
+			avgMasteryPct: answered.length === 0 ? null : Math.round(answered.reduce((sum, l) => sum + (l.mastery ?? 0), 0) / answered.length * 100),
+			sections: course.sections.map((section, index) => ({
+				title: section.title,
+				index,
+				lessons: section.lessons.map((lesson) => ({
+					id: lesson.id,
+					title: lesson.title,
+					kind: lesson.kind,
+					status: lesson.status,
+					masteryPct: lesson.mastery === null ? null : Math.round(lesson.mastery * 100),
+					weakConcepts: (conceptViews(lesson) ?? []).filter((c) => c.weak).length,
+					frictionCount: lesson.friction.length,
+					due: dueIds.has(lesson.id),
+					focus: lesson.id === focusId
+				}))
+			}))
+		};
+	});
+	let lesson = null;
+	if (focusId !== null) try {
+		const ref = findLesson(state, focusId);
+		lesson = {
+			lessonId: ref.lesson.id,
+			courseTitle: ref.course.title,
+			sectionTitle: ref.section.title,
+			title: ref.lesson.title,
+			status: ref.lesson.status,
+			masteryPct: ref.lesson.mastery === null ? null : Math.round(ref.lesson.mastery * 100),
+			strategy: strategyBand(ref.lesson.mastery),
+			concepts: conceptViews(ref.lesson) ?? [],
+			starters: starterPrompts(ref.lesson.title).map((s) => ({
+				label: s.label,
+				message: s.message
+			})),
+			notes: ref.lesson.notes.map((n) => ({
+				id: n.id,
+				zone: n.zone,
+				title: n.title,
+				text: n.text,
+				source: n.source,
+				quote: n.quote
+			})),
+			html: renderMarkdown(ref.lesson.body)
+		};
+	} catch {
+		lesson = null;
+	}
+	const due = dueReviews(state, void 0, now);
+	return {
+		mode: state.mode,
+		courses,
+		focusLessonId: focusId,
+		lesson,
+		dueCount: due.length,
+		due: due.map((d) => ({
+			lessonId: d.lessonId,
+			lessonTitle: d.lessonTitle,
+			courseTitle: d.courseTitle,
+			overdueDays: d.overdueDays
+		})),
+		pendingProposals: state.proposals.filter((p) => p.status === "pending").map((p) => {
+			try {
+				return {
+					id: p.id,
+					lessonTitle: findLesson(state, p.lessonId).lesson.title,
+					rationale: p.rationale
+				};
+			} catch {
+				return {
+					id: p.id,
+					lessonTitle: p.lessonId,
+					rationale: p.rationale
+				};
+			}
+		}),
+		memory: (() => {
+			const snap = learnerSnapshot(state, now);
+			return {
+				global: snap.memoryGlobal,
+				lesson: snap.memoryLesson,
+				pattern: snap.memoryPattern
+			};
+		})(),
+		lessonSessions: state.lessonSessions
+	};
+}
+const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
+function sendJson(res, status, value) {
+	res.writeHead(status, JSON_HEADERS).end(JSON.stringify(value));
+}
+/**
+* Read one JSON body, answering 400 on malformed or oversized input so the
+* handler never throws into the HTTP layer.
+* @returns the parsed value, or undefined when the response is already sent.
+*/
+async function readJsonBodySafe(req, res) {
+	try {
+		return await readJsonBody(req);
+	} catch (error) {
+		sendJson(res, 400, {
+			ok: false,
+			error: error instanceof Error ? error.message : "bad request"
+		});
+		return;
+	}
+}
+/** Read one JSON request body with a hard 64 kB cap; malformed bodies reject. */
+function readJsonBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		req.on("data", (chunk) => {
+			chunks.push(chunk);
+			if (chunks.reduce((n, c) => n + c.length, 0) > 65536) {
+				reject(/* @__PURE__ */ new Error("request body too large"));
+				return;
+			}
+		});
+		req.on("end", () => {
+			try {
+				resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+			} catch {
+				reject(/* @__PURE__ */ new Error("request body is not valid JSON"));
+			}
+		});
+	});
+}
+/**
+* Register the study tab's API routes under `/lookatstudy/api/*`: the polling
+* state feed plus the tab's write actions.
+* @param webServer - the composed webserver's route registry.
+* @param deps - store plus the study-workspace directory.
+* @returns the disposer removing every route.
+*/
+function registerDashboard(webServer, deps) {
+	const disposeRoutes = webServer.register({
+		kind: "prefix",
+		path: "/lookatstudy",
+		handler: async (req, res) => {
+			const pathname = new URL(req.url ?? "/", "http://x").pathname;
+			if (req.method === "GET" && pathname === "/lookatstudy/api/state") {
+				sendJson(res, 200, workbenchState(deps.store.get(), /* @__PURE__ */ new Date()));
+				return;
+			}
+			if (req.method === "POST" && pathname === "/lookatstudy/api/focus") {
+				const body = await readJsonBodySafe(req, res);
+				if (body === void 0) return;
+				if (typeof body.lessonId !== "string") {
+					sendJson(res, 400, {
+						ok: false,
+						error: "lessonId (string) required"
+					});
+					return;
+				}
+				try {
+					const ref = findLesson(deps.store.get(), body.lessonId);
+					deps.store.get().focus = { lessonId: ref.lesson.id };
+					deps.store.save();
+					sendJson(res, 200, { ok: true });
+				} catch (error) {
+					sendJson(res, 404, {
+						ok: false,
+						error: error instanceof Error ? error.message : String(error)
+					});
+				}
+				return;
+			}
+			if (req.method === "GET" && pathname === "/lookatstudy/api/study-workspace") {
+				sendJson(res, 200, {
+					ok: true,
+					path: deps.studyAreaPath
+				});
+				return;
+			}
+			if (req.method === "POST" && pathname === "/lookatstudy/api/course/delete") {
+				const body = await readJsonBodySafe(req, res);
+				if (body === void 0) return;
+				if (typeof body.courseId !== "string") {
+					sendJson(res, 400, {
+						ok: false,
+						error: "courseId (string) required"
+					});
+					return;
+				}
+				try {
+					const course = findCourse(deps.store.get(), body.courseId);
+					deleteCourse(deps.store.get(), course.id);
+					if (deps.store.get().focus?.lessonId.startsWith(`${course.id}:`)) deps.store.get().focus = null;
+					deps.store.save();
+					sendJson(res, 200, { ok: true });
+				} catch (error) {
+					sendJson(res, 404, {
+						ok: false,
+						error: error instanceof Error ? error.message : String(error)
+					});
+				}
+				return;
+			}
+			if (req.method === "POST" && pathname === "/lookatstudy/api/lesson-session") {
+				const body = await readJsonBodySafe(req, res);
+				if (body === void 0) return;
+				if (typeof body.lessonId !== "string" || typeof body.sessionId !== "string") {
+					sendJson(res, 400, {
+						ok: false,
+						error: "lessonId and sessionId (strings) required"
+					});
+					return;
+				}
+				deps.store.get().lessonSessions[body.lessonId] = body.sessionId;
+				deps.store.save();
+				sendJson(res, 200, { ok: true });
+				return;
+			}
+			if (req.method === "POST" && pathname === "/lookatstudy/api/mode") {
+				const body = await readJsonBodySafe(req, res);
+				if (body === void 0) return;
+				if (body.mode !== "direct" && body.mode !== "guide" && body.mode !== "practice") {
+					sendJson(res, 400, {
+						ok: false,
+						error: "mode must be direct | guide | practice"
+					});
+					return;
+				}
+				deps.store.get().mode = body.mode;
+				deps.store.save();
+				sendJson(res, 200, {
+					ok: true,
+					mode: body.mode
+				});
+				return;
+			}
+			sendJson(res, 404, {
+				ok: false,
+				error: "not found"
+			});
+		}
+	});
+	return () => {
+		disposeRoutes();
+	};
+}
+//#endregion
+//#region src/vendor/markdown-course.ts
+/**
+* GitHub 风格的 anchor 生成：小写、去一组标点（保留中文等 unicode）、每个空格单独转 -。
+* 注意：**不合并多 -**（"A & B" → 去 & 留两空格 → "a--b"，与 GitHub slugger 一致）。
+* 与 seed.ts 的锚点对齐。
+*/
+function titleToAnchor(title) {
+	return title.toLowerCase().trim().replace(/[!"#$%&'()*+,.\/:;<=>?@[\\\]^`{|}~]/g, "").replace(/ /g, "-").replace(/^-|-$/g, "");
+}
+/**
+* 清洗课时/章节标题 — 去 emoji、多余空格、markdown 格式符号。
+* "🛠 The Modern FDE Stack" → "The Modern FDE Stack"
+* "## [Pre-lecture quiz](url)" → "Pre-lecture quiz"
+*/
+function cleanTitle(raw) {
+	return raw.replace(/[\u{1F000}-\u{1FFFF}\u{2600}-\u{27BF}\u{2190}-\u{21FF}\u{2B00}-\u{2BFF}]/gu, "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/^#+\s*/, "").trim().replace(/\s+/g, " ").replace(/^[·\-\.\s]+|[·\-\.\s]+$/g, "").trim();
+}
+/**
+* 解析 markdown 为课程树。
+* 容错：H3 出现在任何 H2 之前 → 归到一个 "(前言)" section。
+*/
+function parseMarkdownToCourse(md) {
+	const lines = md.split(/\r?\n/);
+	const sections = [];
+	let title = "(untitled)";
+	let currentSection = null;
+	let bodyBuffer = [];
+	let inCodeFence = false;
+	const flushLessonBody = () => {
+		if (currentSection && currentSection.lessons.length > 0) currentSection.lessons[currentSection.lessons.length - 1].body = bodyBuffer.join("\n").trim();
+		bodyBuffer = [];
+	};
+	for (const line of lines) {
+		if (/^(\s*)(```|~~~)/.test(line)) {
+			inCodeFence = !inCodeFence;
+			bodyBuffer.push(line);
+			continue;
+		}
+		if (inCodeFence) {
+			bodyBuffer.push(line);
+			continue;
+		}
+		if (/^#\s+/.test(line) && title === "(untitled)") {
+			title = cleanTitle(line.replace(/^#\s+/, "").trim());
+			continue;
+		}
+		if (/^##\s+/.test(line)) {
+			flushLessonBody();
+			const sectionTitle = cleanTitle(line.replace(/^##\s+/, "").trim());
+			currentSection = {
+				title: sectionTitle,
+				anchor: titleToAnchor(sectionTitle),
+				lessons: []
+			};
+			sections.push(currentSection);
+			continue;
+		}
+		if (/^###\s+/.test(line)) {
+			flushLessonBody();
+			const lessonTitle = cleanTitle(line.replace(/^###\s+/, "").trim());
+			if (!currentSection) {
+				currentSection = {
+					title: "(前言)",
+					anchor: titleToAnchor("前言"),
+					lessons: []
+				};
+				sections.push(currentSection);
+			}
+			currentSection.lessons.push({
+				title: lessonTitle,
+				anchor: titleToAnchor(lessonTitle),
+				body: ""
+			});
+			continue;
+		}
+		bodyBuffer.push(line);
+	}
+	flushLessonBody();
+	return {
+		title,
+		sections
+	};
+}
+//#endregion
+//#region src/vendor/local-folder-scanner.ts
+/**
+* 本地文件夹通用扫描器 —— 把任意课程文件夹(如 Coursera 下载包)递归扫描成文档清单。
+*
+* 设计原则:通用,不硬编码某一种文件夹结构。
+*   - 扫描文档类:.txt/.md/.mdx/.markdown/.html/.htm/.pdf/.ipynb/.rst/.rmd/.org/.adoc/.asciidoc
+*   - 扫描代码类:.py/.js/.ts/.go/.rs/.java/.c/.cpp/.rb/.sh/.lua/.sql/.r/.jl/.dart/... (30+ 语言, code-parser 转 markdown)
+*   - 图片文件:.png/.jpg/.jpeg/.gif/.webp/.svg/.bmp/.avif/.ico/.tiff/.heic(多模态 flag on 时收集)
+*   - 中文优先去重(同内容 .zh-CN 和 .en 只留中文)
+*   - 按文件名 NN_ 前缀排序
+*   - HTML 去标签转纯文本(<co-content> 富文本质量足够)
+*   - PDF 用 pdf-renderer 提取文字 + 图片(纯文字/纯图片/混合自动分类)
+*
+* 纯函数为主(htmlToText/标题推断/去重/图片引用解析),便于 verify 脚本测。
+* scanFolder 本身用 fs(异步),verify 用临时目录造文件测。
+*/
+/** 支持的扩展名 → kind 映射 */
+const EXT_KIND = {
+	txt: "txt",
+	md: "md",
+	mdx: "md",
+	markdown: "md",
+	html: "html",
+	htm: "html",
+	pdf: "pdf",
+	pptx: "pptx",
+	ipynb: "ipynb",
+	rst: "rst",
+	rmd: "rmd",
+	org: "org",
+	adoc: "adoc",
+	asciidoc: "adoc",
+	py: "code",
+	js: "code",
+	jsx: "code",
+	ts: "code",
+	tsx: "code",
+	mjs: "code",
+	cjs: "code",
+	go: "code",
+	rs: "code",
+	java: "code",
+	kt: "code",
+	kts: "code",
+	scala: "code",
+	c: "code",
+	h: "code",
+	cpp: "code",
+	cc: "code",
+	cxx: "code",
+	hpp: "code",
+	cs: "code",
+	rb: "code",
+	php: "code",
+	swift: "code",
+	sh: "code",
+	bash: "code",
+	zsh: "code",
+	ps1: "code",
+	lua: "code",
+	r: "code",
+	jl: "code",
+	dart: "code",
+	clj: "code",
+	ex: "code",
+	exs: "code",
+	erl: "code",
+	hs: "code",
+	ml: "code",
+	fs: "code",
+	sql: "code",
+	pl: "code",
+	elm: "code"
+};
+/** 图片扩展名 → MIME 映射 */
+const IMAGE_EXT_MIME = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	webp: "image/webp",
+	svg: "image/svg+xml",
+	bmp: "image/bmp",
+	avif: "image/avif",
+	ico: "image/x-icon",
+	tiff: "image/tiff",
+	tif: "image/tiff",
+	heic: "image/heic"
+};
+/** 排除的目录(非教学内容) */
+const EXCLUDED_DIRS = new Set([
+	"node_modules",
+	".git",
+	".svn",
+	"dist",
+	"build",
+	"__pycache__",
+	".DS_Store",
+	"translations",
+	".venv",
+	"venv",
+	"env",
+	"vendor",
+	"target",
+	"out",
+	"coverage",
+	".next",
+	".nuxt",
+	".gradle",
+	".idea",
+	".vscode",
+	".cache",
+	".pytest_cache",
+	".mypy_cache",
+	".turbo",
+	".svelte-kit",
+	"bin",
+	"obj",
+	"__pypackages__",
+	".docusaurus"
+]);
+/** HTML 转纯文本:去 script/style,标签转段落,<li> 加 •,decode 常见实体。纯函数,可测。 */
+function htmlToText(html) {
+	let s = html;
+	s = s.replace(/<script[\s\S]*?<\/script>/gi, "");
+	s = s.replace(/<style[\s\S]*?<\/style>/gi, "");
+	s = s.replace(/<head[\s\S]*?<\/head>/gi, "");
+	s = s.replace(/<\/(p|div|section|article|h[1-6]|li|tr|br)>/gi, "\n");
+	s = s.replace(/<br\s*\/?>/gi, "\n");
+	s = s.replace(/<li[^>]*>/gi, "• ");
+	s = s.replace(/<\/td>/gi, "	");
+	s = s.replace(/<\/th>/gi, "	");
+	s = s.replace(/<[^>]+>/g, "");
+	s = s.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&hellip;/g, "…").replace(/&mdash;/g, "—");
+	s = s.replace(/[ \t]+/g, " ");
+	s = s.replace(/\n[ \t]+/g, "\n");
+	s = s.replace(/\n{3,}/g, "\n\n");
+	return s.trim();
+}
+/** 从文件名推断语言(用于中文优先去重)。 */
+function detectLang(filename) {
+	const lower = filename.toLowerCase();
+	if (/\.zh[-_]?cn\./.test(lower) || /\.zh[-_]?hans\./.test(lower) || /\.zh[-_]?tw\./.test(lower) || /\.zh[-_]?hant\./.test(lower) || /\.zh\./.test(lower)) return "zh";
+	if (/\.en[-_]?us\./.test(lower) || /\.en[-_]?gb\./.test(lower) || /\.en\./.test(lower)) return "en";
+	if (/\.ja\./.test(lower) || /\.ko\./.test(lower) || /\.de\./.test(lower) || /\.fr\./.test(lower) || /\.es\./.test(lower) || /\.pt[-_]?br\./.test(lower) || /\.pt\./.test(lower) || /\.it\./.test(lower) || /\.ru\./.test(lower) || /\.ar\./.test(lower)) return "other";
+	return "other";
+}
+/** 从路径推断标题:
+*   07_derivatives-and-tangents.zh-CN.txt → "Derivatives And Tangents"
+*   01_lesson-1-intro/README.md → "Lesson 1 Intro"
+* 去数字前缀 + 扩展名 + 语言后缀,- _ 转空格,首字母大写。纯函数,可测。 */
+function inferTitle(relPath) {
+	const filename = basename(relPath);
+	let name = filename.replace(/\.(txt|md|mdx|markdown|html?|pdf|ipynb|rst|rmd|org|adoc|asciidoc|py|js|jsx|ts|tsx|mjs|cjs|go|rs|java|kt|kts|scala|c|h|cpp|cc|cxx|hpp|cs|rb|php|swift|sh|bash|zsh|ps1|lua|r|jl|dart|clj|ex|exs|erl|hs|ml|fs|sql|pl|elm)$/i, "");
+	name = name.replace(/\.(zh[-_]?cn|zh[-_]?hans|zh|en[-_]?us|en)$/i, "");
+	if (/^(readme|index)$/i.test(name)) {
+		const parts = relPath.split("/").filter(Boolean);
+		const parent = parts[parts.length - 2];
+		if (parent) name = parent;
+	}
+	name = name.replace(/^(\d+[_-]\s*)/, "");
+	name = name.replace(/[-_]+/g, " ").trim();
+	if (/^[a-z]/.test(name)) name = name.charAt(0).toUpperCase() + name.slice(1);
+	return name || filename;
+}
+/** 算 basename 的去重 key(去掉语言后缀 + 扩展名)。
+*  06_motivation.en.txt 和 06_motivation.zh-CN.txt → key "06_motivation" */
+function dedupKey(relPath) {
+	const dir = dirname(relPath).toLowerCase();
+	let name = basename(relPath).replace(/\.(txt|md|mdx|markdown|html?|pdf|ipynb|rst|rmd|org|adoc|asciidoc|py|js|jsx|ts|tsx|mjs|cjs|go|rs|java|kt|kts|scala|c|h|cpp|cc|cxx|hpp|cs|rb|php|swift|sh|bash|zsh|ps1|lua|r|jl|dart|clj|ex|exs|erl|hs|ml|fs|sql|pl|elm)$/i, "");
+	name = name.replace(/\.(zh[-_]?cn|zh[-_]?hans|zh|en[-_]?us|en)$/i, "");
+	return (dir === "." ? "" : dir + "/") + name.toLowerCase();
+}
+/**
+* 递归扫描一个目录,返回所有文本类文档(可选:同时收集图片)。
+* 中文优先去重:同 dedupKey 的多语言文件只保留中文(.zh 优先于 .en/other)。
+* 按相对路径排序(保持目录顺序 + 文件名 NN_ 前缀)。
+*
+* @param rootDir 根目录绝对路径
+* @param onProgress 可选进度回调(已扫文件数,当前路径)
+* @param options.collectImages true 时同时收集图片文件 + markdown 图片引用(多模态 flag)
+* @returns 文档数组,或 { docs, images }(collectImages=true 时)
+*/
+async function scanFolder(rootDir, onProgress, options) {
+	const allFiles = [];
+	await walkDir(rootDir, rootDir, allFiles);
+	allFiles.sort((a, b) => naturalPathCompare(a.relPath, b.relPath));
+	const docFiles = allFiles.filter((f) => !f.isImage);
+	const imageFiles = allFiles.filter((f) => f.isImage);
+	const docs = [];
+	let count = 0;
+	for (const f of docFiles) {
+		onProgress?.(++count, f.relPath);
+		const kind = EXT_KIND[f.relPath.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? ""];
+		if (!kind) continue;
+		try {
+			const content = await readFileWithKind(f.absPath, kind);
+			if (!content || content.trim().length < 5) continue;
+			const lang = detectLang(f.relPath);
+			docs.push({
+				path: f.relPath,
+				title: inferTitle(f.relPath),
+				content,
+				lang,
+				kind
+			});
+		} catch {}
+	}
+	const dedupedDocs = dedupByLang(docs);
+	if (!options?.collectImages) return dedupedDocs;
+	const fileImages = imageFiles.map((f) => {
+		const ext = f.relPath.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? "";
+		return {
+			path: f.relPath,
+			absPath: f.absPath,
+			title: inferImageTitle(f.relPath),
+			mime: IMAGE_EXT_MIME[ext] ?? "image/png",
+			source: "image_file",
+			altText: inferImageTitle(f.relPath)
+		};
+	});
+	const refImages = [];
+	for (const doc of dedupedDocs) {
+		if (doc.kind === "txt" || doc.kind === "html") continue;
+		const refs = extractImageRefs(doc.content);
+		for (const ref of refs) {
+			const resolvedPath = resolveImageRef(ref.refPath, doc.path);
+			const ext = resolvedPath.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? "";
+			refImages.push({
+				path: resolvedPath,
+				absPath: join(rootDir, resolvedPath),
+				title: ref.alt || inferImageTitle(resolvedPath),
+				mime: IMAGE_EXT_MIME[ext] ?? "image/png",
+				source: "markdown_ref",
+				altText: ref.alt || inferImageTitle(resolvedPath)
+			});
+		}
+	}
+	const dedupedFileAndRefImages = dedupImages(fileImages, refImages);
+	const pdfImages = [];
+	for (const doc of dedupedDocs) {
+		if (doc.kind !== "pdf") continue;
+		try {
+			const { processPdf } = await import("../lib/pdf-renderer.js");
+			const result = await processPdf(await readFile(join(rootDir, doc.path)));
+			for (const img of result.images) pdfImages.push({
+				path: `${doc.path}#page${img.pageNumber}.png`,
+				absPath: "",
+				title: `${doc.title} - 图(第${img.pageNumber}页)`,
+				mime: img.mimeType,
+				source: "pdf_page",
+				altText: `${doc.title} 第${img.pageNumber}页`,
+				buffer: img.buffer,
+				pageNumber: img.pageNumber
+			});
+		} catch {}
+	}
+	const pptxImages = [];
+	for (const doc of dedupedDocs) {
+		if (doc.kind !== "pptx") continue;
+		try {
+			const { parsePptx } = await import("../lib/pptx-parser.js");
+			const result = await parsePptx(await readFile(join(rootDir, doc.path)));
+			for (const img of result.images) pptxImages.push({
+				path: `${doc.path}#slide${img.slideNumber}.png`,
+				absPath: "",
+				title: `${doc.title} - 图(第${img.slideNumber}页)`,
+				mime: img.mimeType,
+				source: "pdf_page",
+				altText: `${doc.title} 第${img.slideNumber}页`,
+				buffer: img.buffer,
+				pageNumber: img.slideNumber
+			});
+		} catch {}
+	}
+	const notebookImages = [];
+	for (const doc of dedupedDocs) {
+		if (!doc.path.toLowerCase().endsWith(".ipynb")) continue;
+		try {
+			const { parseNotebook } = await import("./notebook-parser-ChbZBIKJ.mjs");
+			const nbResult = parseNotebook(await readFile(join(rootDir, doc.path), "utf8"));
+			for (const img of nbResult.images) {
+				const buf = Buffer.from(img.base64, "base64");
+				notebookImages.push({
+					path: `${doc.path}#cell${img.cellIndex}.png`,
+					absPath: "",
+					title: `${doc.title} - 输出图(cell ${img.cellIndex})`,
+					mime: img.mimeType,
+					source: "image_file",
+					altText: img.altText,
+					buffer: buf
+				});
+			}
+		} catch {}
+	}
+	return {
+		docs: dedupedDocs,
+		images: [
+			...dedupedFileAndRefImages,
+			...pdfImages,
+			...pptxImages,
+			...notebookImages
+		]
+	};
+}
+/**
+* 同语言类别内部去重（保留双语配对）。
+*
+* 历史：旧版是跨语言的"中文优先"（同 dedupKey 只留 zh）——那是翻译管线诞生前的
+* hack，xxx.en.txt / xxx.zh-CN.txt 成对时英文原稿被直接丢掉，双语信息在扫描层
+* 就没了，翻译管线永远拿不到配对。现在分类层（excludeSuffixTranslations 规则
+* 分流 + LLM translation 角色）负责把成对双语分流为 原文+翻译，所以扫描器必须
+* 把配对双方都保留，只合并同一语言类别内部的真重复（如 08.en.txt vs 08.en.md）。
+*/
+function dedupByLang(docs) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const d of docs) {
+		const key = `${dedupKey(d.path)}|${d.lang}`;
+		if (!byKey.has(key)) byKey.set(key, d);
+	}
+	return docs.filter((d) => byKey.get(`${dedupKey(d.path)}|${d.lang}`) === d);
+}
+/**
+* 从 markdown 内容里提取图片引用 ![alt](path)。
+* 纯函数,便于测试。
+*
+* 解析规则:
+*   - 匹配 ![可选alt](路径) 格式
+*   - 去掉路径里的锚点和查询参数后缀
+*   - 只保留图片扩展名(.png/.jpg/.jpeg/.gif/.webp/.svg/.bmp)
+*   - 跳过 http(s) 绝对 URL(这些是外部资源,本地没有文件)
+*   - 跳过 data: URL
+*/
+function extractImageRefs(md) {
+	const refs = [];
+	const seen = /* @__PURE__ */ new Set();
+	const mdPattern = /!\[([^\]]*)\]\(([^)]+)\)/g;
+	let m;
+	while ((m = mdPattern.exec(md)) !== null) {
+		const alt = m[1].trim();
+		let url = m[2].trim();
+		const titleMatch = url.match(/\s+"[^"]*"$/);
+		if (titleMatch) url = url.slice(0, titleMatch.index).trim();
+		url = url.split("#")[0];
+		if (!url || url.startsWith("http://") || url.startsWith("https://") || url.startsWith("data:")) continue;
+		if (!((url.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? "") in IMAGE_EXT_MIME)) continue;
+		const key = alt + "|" + url;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		refs.push({
+			alt,
+			refPath: url
+		});
+	}
+	const htmlPattern = /<img\s+[^>]*>/gi;
+	let hm;
+	while ((hm = htmlPattern.exec(md)) !== null) {
+		const tag = hm[0];
+		const url = (tag.match(/src=['"]([^'"]+)['"]/i)?.[1] ?? "").trim().split("#")[0];
+		const alt = (tag.match(/alt=['"]([^'"]*)['"]/i)?.[1] ?? "").trim();
+		if (!url || url.startsWith("http://") || url.startsWith("https://") || url.startsWith("data:")) continue;
+		if (!((url.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? "") in IMAGE_EXT_MIME)) continue;
+		const key = alt + "|" + url;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		refs.push({
+			alt: alt || (url.split("/").pop() ?? url),
+			refPath: url
+		});
+	}
+	return refs;
+}
+/**
+* 把 markdown 图片引用解析成相对于扫描根目录的路径。
+* 处理 ./ ../ 等相对引用。
+*
+* @param refPath markdown 里的原始引用(如 ./img.png)
+* @param docRelPath 引用所在文档的相对路径(如 ch1/lesson1/notes.md)
+* @returns 相对根目录的标准化路径(如 ch1/lesson1/img.png),用 / 分隔
+*
+* 纯函数,便于测试。
+*/
+function resolveImageRef(refPath, docRelPath) {
+	const docDir = dirname(docRelPath).replace(/\\/g, "/");
+	const normalized = refPath.replace(/\\/g, "/").replace(/^\.\//, "");
+	const parts = docDir === "." ? [] : docDir.split("/").filter(Boolean);
+	const refParts = normalized.split("/");
+	for (const p of refParts) if (p === "..") parts.pop();
+	else if (p !== "." && p !== "") parts.push(p);
+	return parts.join("/");
+}
+/** 从图片文件名推断 alt 文本(去扩展名 + 数字前缀) */
+function inferImageTitle(filename) {
+	let name = basename(filename);
+	name = name.replace(/\.(png|jpe?g|gif|webp|svg|bmp)$/i, "");
+	name = name.replace(/^(\d+[_-]\s*)/, "");
+	name = name.replace(/[-_]+/g, " ").trim();
+	if (/^[a-z]/.test(name)) name = name.charAt(0).toUpperCase() + name.slice(1);
+	return name || basename(filename);
+}
+/**
+* 把独立图片文件 + markdown 引用合并去重。
+* 去重规则:按相对根目录路径归一。同一图既被 .md 引用又是独立文件 → 只留一份(image_file 优先,因为它肯定存在)。
+*
+* 纯函数,便于测试。
+*/
+function dedupImages(fileImages, refImages) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const img of fileImages) if (!seen.has(img.path)) seen.set(img.path, img);
+	for (const img of refImages) if (!seen.has(img.path)) seen.set(img.path, img);
+	return Array.from(seen.values());
+}
+async function walkDir(root, current, acc) {
+	let entries;
+	try {
+		entries = await readdir(current, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (EXCLUDED_DIRS.has(entry.name)) continue;
+		const abs = join(current, entry.name);
+		if (entry.isDirectory()) await walkDir(root, abs, acc);
+		else if (entry.isFile()) {
+			const ext = entry.name.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? "";
+			if (ext in EXT_KIND) {
+				const rel = relative(root, abs).split(sep).join("/");
+				acc.push({
+					absPath: abs,
+					relPath: rel,
+					isImage: false
+				});
+			} else if (ext in IMAGE_EXT_MIME) {
+				const rel = relative(root, abs).split(sep).join("/");
+				acc.push({
+					absPath: abs,
+					relPath: rel,
+					isImage: true
+				});
+			}
+		}
+	}
+}
+async function readFileWithKind(absPath, kind) {
+	if (kind === "pdf") {
+		const buf = await readFile(absPath);
+		const { parsePdfText } = await import("../lib/pdf-text.js");
+		return parsePdfText(buf);
+	}
+	if (kind === "pptx") {
+		const buf = await readFile(absPath);
+		const { parsePptx } = await import("../lib/pptx-parser.js");
+		return (await parsePptx(buf)).markdown;
+	}
+	if (kind === "ipynb") {
+		const raw = await readFile(absPath, "utf8");
+		const { parseNotebook } = await import("./notebook-parser-ChbZBIKJ.mjs");
+		return parseNotebook(raw).markdown;
+	}
+	if (kind === "rst" || kind === "rmd" || kind === "org" || kind === "adoc") {
+		const raw = await readFile(absPath, "utf8");
+		const parser = {
+			rst: "rst-parser",
+			rmd: "rmd-parser",
+			org: "org-parser",
+			adoc: "adoc-parser"
+		}[kind];
+		if (parser) try {
+			const mod = await import(`./${parser}.js`);
+			return (mod.parseRst ?? mod.parseRmd ?? mod.parseOrg ?? mod.parseAdoc)(raw).markdown;
+		} catch {
+			return raw;
+		}
+		return raw;
+	}
+	if (kind === "code") {
+		const raw = await readFile(absPath, "utf8");
+		const ext = absPath.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? "";
+		try {
+			const { parseCode } = await import("./code-parser-BOOk9IWV.mjs");
+			return parseCode(raw, ext).markdown;
+		} catch {
+			return "```\n" + raw + "\n```";
+		}
+	}
+	const raw = await readFile(absPath, "utf8");
+	return kind === "html" ? htmlToText(raw) : raw;
+}
+/** 路径自然排序:按段拆分,数字段按数值比较(02_ 在 10_ 前,不是字典序)。 */
+function naturalPathCompare(a, b) {
+	const pa = a.split("/");
+	const pb = b.split("/");
+	for (let i = 0; i < Math.min(pa.length, pb.length); i++) {
+		const na = pa[i].match(/^(\d+)/)?.[1];
+		const nb = pb[i].match(/^(\d+)/)?.[1];
+		if (na && nb && na !== nb) return Number(na) - Number(nb);
+		if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+	}
+	return pa.length - pb.length;
+}
+//#endregion
+//#region src/vendor/file-classifier.ts
+/** 仓库元数据文件名（忽略大小写，匹配文件名 stem） */
+const META_FILE_NAMES = new Set([
+	"license",
+	"licence",
+	"contributing",
+	"code_of_conduct",
+	"security",
+	"changelog",
+	"authors",
+	"maintainers",
+	"pull_request_template",
+	"issue_template",
+	"support",
+	"citation"
+]);
+/** 配套练习目录/文件名关键词（路径含这些子串即判定） */
+const LAB_KEYWORDS = [
+	"/lab/",
+	"/labs/",
+	"/exercise/",
+	"/exercises/",
+	"/assignment/",
+	"/assignments/",
+	"/quiz/",
+	"/quizzes/",
+	"/homework/",
+	"/practice/",
+	"/solution/",
+	"labs/",
+	"exercises/",
+	"assignments/"
+];
+/** 示例代码目录关键词（路径含这些子串即判定，含根目录开头） */
+const EXAMPLE_KEYWORDS = [
+	"/examples/",
+	"/example/",
+	"/demo/",
+	"/demos/",
+	"/samples/",
+	"/sample/",
+	"examples/",
+	"example/",
+	"demo/",
+	"demos/",
+	"samples/"
+];
+/**
+* 判断一个文件是否是 section-intro：它是某个 section 的 README.md，
+* 且同 section 下有**更深一级的 README.md lesson**（不是 lab/notebook）。
+*
+* 例:
+*   `lessons/3-NN/README.md` 是 section-intro ← 因为有 `lessons/3-NN/03-Perceptron/README.md`
+*   `lessons/3-NN/03-Perceptron/README.md` 不是 ← 虽然 03-Perceptron/ 下有 lab/README.md，
+*      但 lab 不是 lesson，不能用来判定 lesson 是 intro
+*/
+function isSectionIntro(path, siblingPaths) {
+	const parts = path.split("/").filter(Boolean);
+	const last = parts[parts.length - 1];
+	if (!last || !(/^readme/i.test(last) || last === "index.md")) return false;
+	const myDepth = parts.length;
+	if (myDepth < 3) return false;
+	const prefix = parts.slice(0, -1).join("/");
+	return siblingPaths.some((sib) => {
+		if (sib === path) return false;
+		const sibLower = sib.toLowerCase();
+		if (sibLower.includes("/lab/") || sibLower.includes("/exercise/") || sibLower.includes("/assignment/")) return false;
+		if (sibLower.endsWith(".ipynb")) return false;
+		const sibParts = sib.split("/").filter(Boolean);
+		return sibParts.slice(0, -1).join("/").startsWith(prefix + "/") && sibParts.length > myDepth;
+	});
+}
+/**
+* 主分类函数：first-match-wins 级联规则。
+*
+* @param path 文件路径（相对 repo 根，/ 分隔）
+* @param md 文件正文（已转成 markdown）
+* @param context 分类上下文（siblingPaths = 同批次所有文件路径）
+*/
+function classifyFile(path, _md, context) {
+	const lowerPath = path.toLowerCase();
+	const parts = path.split("/").filter(Boolean);
+	const stem = (parts[parts.length - 1] ?? path).replace(/\.[^.]+$/, "").toLowerCase();
+	if (lowerPath.includes("translations/") || lowerPath.includes("translated_images/")) return {
+		role: "translation",
+		confidence: "high",
+		keepAsLesson: false,
+		world: null,
+		reason: "路径含 translations/，是翻译副本"
+	};
+	if (META_FILE_NAMES.has(stem)) return {
+		role: "meta",
+		confidence: "high",
+		keepAsLesson: false,
+		world: null,
+		reason: `文件名 ${stem} 是仓库元数据`
+	};
+	if (lowerPath.endsWith(".ipynb")) return {
+		role: "uncertain",
+		confidence: "low",
+		keepAsLesson: true,
+		world: null,
+		reason: ".ipynb notebook——可能是主课程(fast.ai/d2l 风格)也可能是补充代码，交给 LLM 判断"
+	};
+	for (const kw of LAB_KEYWORDS) if (lowerPath.includes(kw)) return {
+		role: "uncertain",
+		confidence: "low",
+		keepAsLesson: true,
+		world: null,
+		reason: `路径含 ${kw}——可能是配套练习也可能是课时正文，交给 LLM 判断`
+	};
+	for (const kw of EXAMPLE_KEYWORDS) if (lowerPath.includes(kw)) return {
+		role: "uncertain",
+		confidence: "low",
+		keepAsLesson: true,
+		world: null,
+		reason: `路径含 ${kw}——可能是示例代码也可能是课时正文，交给 LLM 判断`
+	};
+	if (isSectionIntro(path, context.siblingPaths)) return {
+		role: "section-intro",
+		confidence: "high",
+		keepAsLesson: false,
+		world: "study",
+		reason: "章节介绍页（同 section 有更深的 lesson 文件）"
+	};
+	return {
+		role: "uncertain",
+		confidence: "low",
+		keepAsLesson: true,
+		world: null,
+		reason: "规则未命中高置信度分类，交给 LLM 判断"
+	};
+}
+//#endregion
+//#region src/vendor/repo-fetcher.ts
+/**
+* 仓库导入器 —— 从学习型 GitHub 仓库构建课程结构。
+*
+* 核心策略:不依赖文件列表 API（api.github.com / api.jsdelivr.net 在很多网络环境下不可达），
+* 而是从 README.md 的 markdown 内部链接发现课程结构。
+*
+* 学习仓库的 README 通常有完整的课程大纲，链接指向每个课时:
+*   - 形态 A（课程型）: 链接指向 lessons/N-Topic/README.md + .ipynb
+*   - 形态 B（单文件型）: README 本身是超长文档，无子文件链接
+*
+* 数据源: cdn.jsdelivr.net/gh/{owner}/{repo}@{branch}/{path}（全球 CDN，无速率限制，
+* 在大多数网络环境下可用，包括 raw.githubusercontent.com 被墙的情况）
+*
+* 纯函数设计: fetchFn 由调用方注入（生产用 global fetch，测试用 mock）。
+*/
+/** CDN URL 构造 */
+function cdnUrl(owner, repo, branch, path) {
+	return `https://cdn.jsdelivr.net/gh/${owner}/${repo}@${branch}/${path.replace(/^\.\//, "").replace(/^\//, "")}`;
+}
+/** 代码文件扩展名（代码即教学内容） */
+const CODE_EXTENSIONS = [
+	".py",
+	".js",
+	".jsx",
+	".ts",
+	".tsx",
+	".mjs",
+	".cjs",
+	".go",
+	".rs",
+	".java",
+	".kt",
+	".kts",
+	".scala",
+	".c",
+	".h",
+	".cpp",
+	".cc",
+	".cxx",
+	".hpp",
+	".cs",
+	".rb",
+	".php",
+	".swift",
+	".sh",
+	".bash",
+	".zsh",
+	".ps1",
+	".lua",
+	".r",
+	".jl",
+	".dart",
+	".clj",
+	".ex",
+	".exs",
+	".erl",
+	".hs",
+	".ml",
+	".fs",
+	".sql",
+	".pl",
+	".elm"
+];
+/**
+* 从 README 的 markdown 链接提取内部文件引用。
+* 只看相对路径（非 http/锚点），且指向 .md/.ipynb 文件。
+*/
+function extractInternalLinks(readmeMd) {
+	const linkPattern = /\[([^\]]*)\]\(([^)]+)\)/g;
+	const seen = /* @__PURE__ */ new Set();
+	const files = [];
+	let m;
+	while ((m = linkPattern.exec(readmeMd)) !== null) {
+		const title = m[1].trim();
+		let href = m[2].trim();
+		href = href.split("#")[0];
+		if (!href || href.startsWith("http") || href.startsWith("mailto:")) continue;
+		href = href.replace(/^\.\//, "");
+		let kind = "other";
+		if (href.endsWith(".md") || href.endsWith(".mdx")) kind = "md";
+		else if (href.endsWith(".ipynb")) kind = "ipynb";
+		else if (href.endsWith(".rst")) kind = "rst";
+		else if (href.endsWith(".rmd")) kind = "rmd";
+		else if (href.endsWith(".org")) kind = "org";
+		else if (href.endsWith(".adoc") || href.endsWith(".asciidoc")) kind = "adoc";
+		else if (CODE_EXTENSIONS.some((ext) => href.endsWith(ext))) kind = "code";
+		else continue;
+		if (seen.has(href)) continue;
+		seen.add(href);
+		files.push({
+			path: href,
+			title: title || href,
+			kind
+		});
+	}
+	return files;
+}
+/**
+* 过滤:只保留像课时文件的（排除 translations/、lab/、translations、LICENSE 等）
+*/
+function filterLessonFiles(files) {
+	return files.filter((f) => {
+		const p = f.path.toLowerCase();
+		if (p.includes("translations/")) return false;
+		if (p.endsWith("license.md") || p.endsWith("contributing.md") || p.endsWith("code_of_conduct.md")) return false;
+		return true;
+	});
+}
+/**
+* 规则高置信度检测：仓库是否已用编号目录组织好课程结构。
+*
+* 判定依据：文件路径里有 ≥3 个不同的编号顶层目录（如 lessons/1-Intro/,
+* lessons/2-Symbolic/, lessons/3-NeuralNetworks/）。编号前缀 = 作者刻意组织。
+*
+* 这是确定性判断（规则管），不交给 LLM。
+* 命中 → pattern: "well-organized"，下游只判 world 不重组章节。
+*/
+function detectWellOrganized(files) {
+	const topicDirs = /* @__PURE__ */ new Set();
+	const ORGANIZED_PREFIXES = /^(week|unit|part|topic|lecture|session|day|step)(\d|[-_])/i;
+	for (const f of files) {
+		const parts = f.path.split("/").filter(Boolean);
+		for (const part of parts) {
+			if (part.includes(".")) continue;
+			if (part.match(/^(\d+[-_])/i)) {
+				topicDirs.add(part.toLowerCase());
+				break;
+			}
+			if (ORGANIZED_PREFIXES.test(part)) {
+				topicDirs.add(part.toLowerCase());
+				break;
+			}
+		}
+	}
+	return topicDirs.size >= 3;
+}
+/**
+* 检测仓库形态。
+*
+* 原则:规则管确定性，不确定的给 LLM 兜底（通过下游 analyzeCourseStructure）。
+*
+* - well-organized: README 链接 ≥1 个且路径有编号/组织目录(数字/week/unit/topic) → 保留原始结构
+* - course: README 链接里有 ≥1 个课程文件(.md/.ipynb/.py 等) → LLM 重组
+* - single-file: 无子文件链接但 README 有实质教学正文（prose >1000 字）
+* - docs-rich: README 无链接但文件树可能有内容 → 不急着拒绝，让 fetchRepoInventory 用文件树补全
+* - unsupported: awesome-list（外链占比>60%且正文极少）
+*/
+function detectRepoPattern(readmeMd) {
+	const lessonLinks = filterLessonFiles(extractInternalLinks(readmeMd)).filter((f) => f.kind !== "other");
+	if (lessonLinks.length >= 1) {
+		if (detectWellOrganized(lessonLinks)) return {
+			pattern: "well-organized",
+			reason: `README 含 ${lessonLinks.length} 个文件,路径有编号目录组织,判定为已组织好的课程仓库`,
+			lessonFiles: lessonLinks
+		};
+		return {
+			pattern: "course",
+			reason: `README 含 ${lessonLinks.length} 个内部课程文件链接，判定为课程型仓库`,
+			lessonFiles: lessonLinks
+		};
+	}
+	const proseChars = readmeMd.replace(/!\[[^\]]*\]\([^)]*\)/g, "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<[^>]+>/g, "").replace(/^---[\s\S]*?---/m, "").replace(/\s/g, "").length;
+	if (proseChars > 1e3) return {
+		pattern: "single-file",
+		reason: `README 无子文件链接，但实质正文 ${proseChars} 字，判定为单文件型`,
+		readmeLength: readmeMd.length
+	};
+	const externalLinks = (readmeMd.match(/\]\(https?:\/\//g) || []).length;
+	const totalLinks = (readmeMd.match(/\]\(/g) || []).length;
+	if (totalLinks > 10 && externalLinks / totalLinks > .6 && proseChars < 500) return {
+		pattern: "unsupported",
+		reason: `README 外链占比 ${(externalLinks / totalLinks * 100).toFixed(0)}%，实质正文仅 ${proseChars} 字，疑似 awesome-list 资源索引（非课程）`
+	};
+	return {
+		pattern: "docs-rich",
+		reason: `README 无课程文件链接，实质正文 ${proseChars} 字 → 将用文件树补全课程文件`
+	};
+}
+/**
+* 并发拉取多个 markdown 文件（5 并发，防 CDN 过载）。
+*
+* @param files 要拉取的文件列表
+* @param owner repo owner
+* @param repo repo name
+* @param branch 分支名
+* @param fetchFn 注入的 fetch 函数
+* @param onProgress 进度回调 (done, total, currentPath)
+*/
+async function fetchMarkdownContents(files, owner, repo, branch, fetchFn, onProgress) {
+	const ok = [];
+	const failed = [];
+	const CONCURRENCY = 5;
+	let done = 0;
+	for (let i = 0; i < files.length; i += CONCURRENCY) {
+		const batch = files.slice(i, i + CONCURRENCY);
+		const results = await Promise.allSettled(batch.map(async (f) => {
+			const r = await fetchFn(cdnUrl(owner, repo, branch, f.path));
+			if (!r.ok) throw new Error(`HTTP ${r.status}`);
+			const text = await r.text();
+			if (f.path.toLowerCase().endsWith(".ipynb")) try {
+				const { parseNotebook } = await import("./notebook-parser-ChbZBIKJ.mjs");
+				const nbResult = parseNotebook(text);
+				return {
+					path: f.path,
+					title: f.title,
+					md: nbResult.markdown
+				};
+			} catch {
+				return {
+					path: f.path,
+					title: f.title,
+					md: text
+				};
+			}
+			const lowerPath = f.path.toLowerCase();
+			if (lowerPath.endsWith(".rst") || lowerPath.endsWith(".rmd") || lowerPath.endsWith(".org") || lowerPath.endsWith(".adoc") || lowerPath.endsWith(".asciidoc")) {
+				const parserName = {
+					".rst": "rst-parser",
+					".rmd": "rmd-parser",
+					".org": "org-parser",
+					".adoc": "adoc-parser",
+					".asciidoc": "adoc-parser"
+				}[lowerPath.match(/\.[^.]+$/)?.[0] ?? ""];
+				if (parserName) try {
+					const mod = await import(`./${parserName}.js`);
+					const fn = mod.parseRst ?? mod.parseRmd ?? mod.parseOrg ?? mod.parseAdoc;
+					return {
+						path: f.path,
+						title: f.title,
+						md: fn(text).markdown
+					};
+				} catch {
+					return {
+						path: f.path,
+						title: f.title,
+						md: text
+					};
+				}
+			}
+			if (CODE_EXTENSIONS.some((ext) => lowerPath.endsWith(ext))) {
+				const ext = lowerPath.split(".").pop() ?? "";
+				try {
+					const { parseCode } = await import("./code-parser-BOOk9IWV.mjs");
+					return {
+						path: f.path,
+						title: f.title,
+						md: parseCode(text, ext).markdown
+					};
+				} catch {
+					return {
+						path: f.path,
+						title: f.title,
+						md: "```\n" + text + "\n```"
+					};
+				}
+			}
+			return {
+				path: f.path,
+				title: f.title,
+				md: text
+			};
+		}));
+		for (let j = 0; j < results.length; j++) {
+			done++;
+			const file = batch[j];
+			const result = results[j];
+			if (file) onProgress?.(done, files.length, file.path);
+			if (result && result.status === "fulfilled") ok.push(result.value);
+			else if (result && result.status === "rejected") failed.push({
+				path: file?.path ?? "(unknown)",
+				error: result.reason instanceof Error ? result.reason.message : String(result.reason)
+			});
+		}
+	}
+	return {
+		ok,
+		failed
+	};
+}
+/**
+* 把课程型仓库的多个课时文件合并成 ParsedCourse 结构。
+*
+* v3 改进:集成 file-classifier 规则引擎。
+*   - 先对每个文件调 classifyFile 判定角色（lesson/notebook/lab/section-intro/uncertain 等）
+*   - keepAsLesson=false 的文件（translation/meta/notebook/lab/example/section-intro）不进 lesson 列表
+*   - section-intro 的正文追加到同 section 摘要（作为章节概述）
+*   - uncertain 的文件进 lesson 列表但标 uncertain=true，后续 LLM 结构化时优先判断 keep/skip
+*
+* 分组策略保留 v2 的"第一个非通用目录"启发式（减少碎片）。
+*
+* 每个文件的内部 H2/H3 → 该 section 下的 lessons;无 H2/H3 则整个文件作一个 lesson。
+*/
+function buildCourseFromFiles(courseTitle, files) {
+	const allPaths = files.map((f) => f.path);
+	for (const file of files) if (!file.classification) file.classification = classifyFile(file.path, file.md, { siblingPaths: allPaths });
+	const groupMap = /* @__PURE__ */ new Map();
+	const groupOrder = [];
+	const GENERIC_DIRS = new Set([
+		"lessons",
+		"docs",
+		"doc",
+		"src",
+		"content",
+		"modules",
+		"chapters",
+		"tutorials",
+		"guide",
+		"week",
+		"unit",
+		"part",
+		"topic",
+		"lecture",
+		"session",
+		"day",
+		"step"
+	]);
+	/**
+	* 计算文件的 section 分组键（和 lesson 用同一个逻辑）。
+	*/
+	function sectionKeyOf(path) {
+		const parts = path.split("/").filter(Boolean);
+		const dirParts = parts[parts.length - 1]?.match(/^readme/i) || parts[parts.length - 1] === "index.md" ? parts.slice(0, -1) : parts;
+		const specificDir = dirParts.find((p) => !GENERIC_DIRS.has(p.toLowerCase()) && !/\.(md|mdx)$/i.test(p));
+		if (dirParts.length >= 2 && specificDir) {
+			const gk = specificDir.replace(/\.md$/i, "");
+			return {
+				groupKey: gk,
+				sectionTitle: gk
+			};
+		} else if (dirParts.length === 1) return {
+			groupKey: path,
+			sectionTitle: dirParts[0].replace(/\.md$/i, "")
+		};
+		return {
+			groupKey: path,
+			sectionTitle: parts[parts.length - 1] ?? path
+		};
+	}
+	const sortedFiles = [...files].sort((a, b) => a.path.localeCompare(b.path));
+	for (const file of sortedFiles) {
+		const classification = file.classification;
+		const { groupKey, sectionTitle } = sectionKeyOf(file.path);
+		if (!groupMap.has(groupKey)) {
+			groupMap.set(groupKey, {
+				sectionTitle,
+				orderKey: file.path,
+				lessons: []
+			});
+			if (!groupOrder.includes(groupKey)) groupOrder.push(groupKey);
+		}
+		const group = groupMap.get(groupKey);
+		if (!classification.keepAsLesson) {
+			if (classification.role === "section-intro") group.pendingIntro = file.md;
+			continue;
+		}
+		const lowerP = file.path.toLowerCase();
+		const isNotebook = lowerP.endsWith(".ipynb");
+		const isLab = /\/lab\//.test(lowerP) || /\/labs\//.test(lowerP) || /\/exercise/.test(lowerP);
+		const isExample = /\/examples?\//.test(lowerP) || /\/demos?\//.test(lowerP);
+		if (isNotebook || isLab || isExample) {
+			const h1Match = file.md.match(/^#\s+(.+)$/m);
+			const lessonTitle = h1Match ? h1Match[1].trim() : file.title;
+			group.lessons.push({
+				title: lessonTitle,
+				anchor: file.path.toLowerCase().replace(/[^a-z0-9]+/g, "-"),
+				body: file.md,
+				uncertain: true,
+				sourceFilePath: file.path,
+				world: null
+			});
+			continue;
+		}
+		const parsed = parseMarkdownToCourse(file.md);
+		const parsedLessonCount = parsed.sections.reduce((sum, s) => sum + s.lessons.length, 0);
+		const isUncertain = classification.role === "uncertain";
+		const fileWorld = classification.world;
+		const lessonCandidates = parsedLessonCount > 0 ? parsed.sections.filter((s) => s.lessons.length > 0).flatMap((s) => s.lessons.map((l) => ({
+			title: l.title,
+			anchor: l.title.toLowerCase().replace(/\s+/g, "-"),
+			body: l.body,
+			uncertain: isUncertain,
+			sourceFilePath: file.path,
+			world: fileWorld
+		}))) : (() => {
+			const h1Match = file.md.match(/^#\s+(.+)$/m);
+			const lessonTitle = h1Match ? h1Match[1].trim() : file.title;
+			return [{
+				title: lessonTitle,
+				anchor: lessonTitle.toLowerCase().replace(/\s+/g, "-"),
+				body: file.md,
+				uncertain: isUncertain,
+				sourceFilePath: file.path,
+				world: fileWorld
+			}];
+		})();
+		group.lessons.push(...lessonCandidates);
+	}
+	for (const key of groupOrder) {
+		const g = groupMap.get(key);
+		if (g.pendingIntro && g.lessons.length > 0) g.lessons[0].body = `> **📖 章节概述**\n>\n> ${g.pendingIntro.replace(/\n/g, "\n> ")}\n\n---\n\n${g.lessons[0].body}`;
+	}
+	return {
+		title: courseTitle,
+		sections: groupOrder.filter((key) => groupMap.get(key).lessons.length > 0).map((key) => {
+			const g = groupMap.get(key);
+			const practiceCount = g.lessons.filter((l) => l.world === "practice").length;
+			const studyCount = g.lessons.filter((l) => l.world === "study").length;
+			return {
+				title: g.sectionTitle,
+				anchor: g.sectionTitle.toLowerCase().replace(/\s+/g, "-"),
+				world: practiceCount > 0 && studyCount === 0 ? "practice" : "study",
+				lessons: g.lessons
+			};
+		})
+	};
+}
+/** 从 .md 路径列表构造 DiscoveredFile[](复用 filterLessonFiles 排除规则 + 标题推断)。 */
+function pathsToDiscoveredFiles(paths) {
+	const files = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const p of paths) {
+		const lower = p.toLowerCase();
+		if (seen.has(p)) continue;
+		let kind = "other";
+		if (lower.endsWith(".md") || lower.endsWith(".mdx")) kind = "md";
+		else if (lower.endsWith(".ipynb")) kind = "ipynb";
+		else if (lower.endsWith(".rst")) kind = "rst";
+		else if (lower.endsWith(".rmd")) kind = "rmd";
+		else if (lower.endsWith(".org")) kind = "org";
+		else if (lower.endsWith(".adoc") || lower.endsWith(".asciidoc")) kind = "adoc";
+		else if (CODE_EXTENSIONS.some((ext) => lower.endsWith(ext))) kind = "code";
+		else continue;
+		if (lower.includes("node_modules/") || lower.startsWith(".git/") || lower.includes("translations/")) continue;
+		if (lower.endsWith("license.md") || lower.endsWith("contributing.md") || lower.endsWith("code_of_conduct.md")) continue;
+		seen.add(p);
+		const parts = p.split("/").filter(Boolean);
+		const last = parts[parts.length - 1] ?? p;
+		const title = last.replace(/\.(md|mdx|ipynb|rst|rmd|org|adoc|asciidoc|py|js|jsx|ts|tsx|go|rs|java|c|cpp|rb|sh|sql|lua|r|jl|dart|scala|kt|cs|php|swift|hs|clj|ex|erl|ml|fs|pl|elm)$/i, "").replace(/^readme$/i, parts[parts.length - 2] ?? last);
+		files.push({
+			path: p,
+			title,
+			kind
+		});
+	}
+	return files;
+}
+/**
+* 主方式:GitHub Tree API 一次拿全仓文件树。
+* https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1
+* 返回 { tree: [{ path, type }] }。筛 blob + .md/.ipynb。
+* 网络失败/限流 → 抛错(由调用方降级)。
+*/
+/**
+* 用 Node 的 https 模块拉取（可单独控制 SSL 验证）。
+* GitHub Tree API 的证书链在部分环境（Node 内置 CA）验证失败（中间证书缺失），
+* 对这一个获取公开文件树的请求用 rejectUnauthorized:false 绕过。
+* 风险可控：获取的是公开文件路径列表（无敏感数据），且只用于此请求。
+*/
+function httpsGet(url, opts = {}) {
+	return new Promise((resolve) => {
+		const req = https.get(url, {
+			headers: {
+				"User-Agent": "lookatstudy-import",
+				...opts.headers
+			},
+			rejectUnauthorized: opts.rejectUnauthorized ?? true,
+			timeout: 2e4
+		}, (res) => {
+			let body = "";
+			res.on("data", (d) => {
+				body += d.toString();
+			});
+			res.on("end", () => resolve({
+				ok: res.statusCode === 200,
+				status: res.statusCode,
+				body
+			}));
+		});
+		req.on("error", (e) => resolve({
+			ok: false,
+			error: e.message
+		}));
+		req.on("timeout", () => {
+			req.destroy();
+			resolve({
+				ok: false,
+				error: "timeout"
+			});
+		});
+	});
+}
+async function fetchRepoFileTree(owner, repo, branch, _fetchFn) {
+	const apiUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
+	try {
+		const r = await httpsGet(apiUrl, { rejectUnauthorized: false });
+		console.error(`[import] GitHub Tree API: HTTP ${r.status ?? r.error}`);
+		if (r.ok && r.body) {
+			const paths = (JSON.parse(r.body).tree ?? []).filter((n) => n.type === "blob").map((n) => n.path);
+			if (paths.length > 0) return {
+				paths,
+				source: "github-tree-api"
+			};
+		}
+	} catch (e) {
+		console.error(`[import] GitHub Tree API 异常: ${e instanceof Error ? e.message : e}`);
+	}
+	return {
+		paths: [],
+		source: "none"
+	};
+}
+/** 文件数上限（防爆，和 IPC handler 一致） */
+const MAX_FILES = 500;
+/**
+* 从 GitHub 仓库构建课程结构 —— 纯编排函数。
+*
+* 流程: fetch README → detectRepoPattern → 发现文件树 → fetchMarkdownContents
+*       → classifyFile（在 buildCourseFromFiles 内）→ buildCourseFromFiles
+*
+* 不落库、不发进度事件（onProgress 回调只传消息字符串，由调用方决定怎么用）。
+*
+* @param owner GitHub owner
+* @param repo GitHub repo
+* @param branch 起始分支（README 先试 main 再试 master）
+* @param fetchFn 注入的 fetch（生产用 global fetch，测试用 mock）
+* @param onProgress 进度回调（可选）
+*/
+async function importRepoToParsedCourse(owner, repo, branch, fetchFn, onProgress) {
+	const send = (msg) => onProgress?.(msg);
+	send("正在拉取 README…");
+	const branches = branch === "master" ? ["master", "main"] : ["main", "master"];
+	let readmeMd = null;
+	let readmeBranch = branch;
+	for (const br of branches) try {
+		const r = await fetchFn(cdnUrl(owner, repo, br, "README.md"));
+		if (r.ok) {
+			readmeMd = await r.text();
+			readmeBranch = br;
+			break;
+		}
+	} catch {}
+	if (!readmeMd) throw new Error(`无法拉取 README（试过分支: ${branches.join(", ")}）`);
+	send(`README 拉取成功（${readmeMd.length} 字符，分支 ${readmeBranch}）`);
+	const detection = detectRepoPattern(readmeMd);
+	if (detection.pattern === "unsupported") throw new Error(`仓库不支持: ${detection.reason}`);
+	if (detection.pattern === "single-file") return {
+		course: parseMarkdownToCourse(readmeMd),
+		detection,
+		fetchedFiles: [],
+		readmeBranch,
+		readmeMd
+	};
+	let lessonFiles = filterLessonFiles(detection.lessonFiles ?? []);
+	const readmeLinkCount = lessonFiles.length;
+	if (readmeLinkCount < 5) try {
+		send("README 链接较少，扫描文件树补充…");
+		const tree = await fetchRepoFileTree(owner, repo, readmeBranch, fetchFn);
+		if (tree.paths.length > 0) {
+			const treeLessonFiles = filterLessonFiles(pathsToDiscoveredFiles(tree.paths)).filter((f) => f.kind !== "other");
+			if (treeLessonFiles.length > lessonFiles.length) {
+				lessonFiles = treeLessonFiles;
+				send(`文件树发现 ${lessonFiles.length} 个课时文件（来源: ${tree.source}）`);
+			}
+		}
+	} catch {
+		send("文件树拉取失败，使用 README 链接发现");
+	}
+	else send(`README 链接发现 ${readmeLinkCount} 个课时文件（人工策展，优先使用）`);
+	if (lessonFiles.length === 0) {
+		send("未发现课时文件，降级为单文件导入");
+		return {
+			course: parseMarkdownToCourse(readmeMd),
+			detection: {
+				...detection,
+				pattern: "single-file",
+				reason: "无课时文件，降级"
+			},
+			fetchedFiles: [],
+			readmeBranch,
+			readmeMd
+		};
+	}
+	if (lessonFiles.length > MAX_FILES) {
+		send(`文件数 ${lessonFiles.length} 超过上限 ${MAX_FILES}，截断`);
+		if (readmeLinkCount > 0 && readmeLinkCount < MAX_FILES) {
+			const readmePaths = new Set(filterLessonFiles(detection.lessonFiles ?? []).map((f) => f.path));
+			const fromReadme = lessonFiles.filter((f) => readmePaths.has(f.path));
+			const fromTree = lessonFiles.filter((f) => !readmePaths.has(f.path)).slice(0, MAX_FILES - fromReadme.length);
+			lessonFiles = [...fromReadme, ...fromTree];
+		} else lessonFiles = lessonFiles.slice(0, MAX_FILES);
+	}
+	send(`检测到课程型仓库（${lessonFiles.length} 个文件），开始拉取…`);
+	const fetchResult = await fetchMarkdownContents(lessonFiles, owner, repo, readmeBranch, fetchFn, (done, total, path) => send(`拉取 ${done}/${total}: ${path}`));
+	if (fetchResult.ok.length === 0) throw new Error(`检测到 ${lessonFiles.length} 个课时文件，但全部拉取失败。可能是网络受限。请稍后重试或改用「粘贴 Markdown」方式手动导入。`);
+	const h1Match = readmeMd.match(/^#\s+(.+)$/m);
+	const course = buildCourseFromFiles(h1Match ? h1Match[1].trim() : repo, fetchResult.ok);
+	send(`解析完成：${course.sections.length} 章节，构建课程…`);
+	return {
+		course,
+		detection,
+		fetchedFiles: fetchResult.ok,
+		readmeBranch,
+		readmeMd
+	};
+}
+//#endregion
+//#region src/cards.ts
+/**
+* Status glyph for one lesson line on the map (LookatStudy's map icons).
+* @param kind - lesson kind.
+* @param status - lesson status.
+* @returns the glyph prefix.
+*/
+function statusGlyph(kind, status) {
+	if (kind === "exam") return "🎯";
+	if (status === "mastered") return "👑";
+	if (status === "in_progress") return "📖";
+	if (status === "available") return "⭐";
+	return "🔒";
+}
+/**
+* Display lines for an import result.
+* @param value - import tool value.
+* @returns card lines.
+*/
+function importLines(value) {
+	const lines = [`📘 ${value.title}`, `${value.sections} sections · ${value.lessons} lessons · id ${value.courseId}`];
+	if (value.firstLessonId !== null) lines.push(`Start at “${value.firstLessonTitle}” (${value.firstLessonId})`);
+	return lines;
+}
+/**
+* Display lines for the skill-tree map.
+* @param value - map tool value.
+* @returns card lines.
+*/
+function mapLines(value) {
+	const lines = [`🗺 ${value.title} — ${value.counts.mastered}/${value.counts.total} mastered`];
+	for (const section of value.tree) {
+		lines.push(`▍${section.title}`);
+		for (const lesson of section.lessons) {
+			const mastery = lesson.masteryPct === null ? "" : ` · ${lesson.masteryPct}%${lesson.crown >= 4 ? " 👑" : ""}`;
+			const weak = lesson.weakConcepts > 0 ? ` · ⚡${lesson.weakConcepts}` : "";
+			const friction = lesson.frictionCount > 0 ? ` · 😣${lesson.frictionCount}` : "";
+			lines.push(`  ${statusGlyph(lesson.kind, lesson.status)} ${lesson.title}${mastery}${weak}${friction}`);
+		}
+	}
+	return lines;
+}
+/**
+* Display line for a graded answer.
+* @param value - answer tool value.
+* @returns single feedback line.
+*/
+function answerLine(value) {
+	const mark = value.correct ? "✓ correct" : "✗ incorrect";
+	const crown = value.mastered ? " · 👑 mastered" : "";
+	return `${mark} — mastery ${value.prevMasteryPct}% → ${value.newMasteryPct}% (crown ${value.crown})${crown}`;
+}
+/**
+* Display lines for the due-review list.
+* @param value - due tool value.
+* @returns card lines.
+*/
+function dueLines(value) {
+	if (value.total === 0) return ["🎉 No reviews due — everything is scheduled ahead."];
+	const lines = [`🔁 ${value.total} due`];
+	for (const item of value.due) {
+		const overdue = item.overdueDays > 0 ? ` · ${item.overdueDays}d overdue` : "";
+		lines.push(`  ⏰ ${item.lessonTitle} — ${item.courseTitle}${overdue}`);
+	}
+	return lines;
+}
+/**
+* Display line for a recorded review grade.
+* @param value - review tool value.
+* @returns single schedule line.
+*/
+function reviewLine(value) {
+	return `🔁 quality ${value.quality}/5 — next review in ${value.intervalDays}d (${value.repetitions} in a row), due ${value.dueAt.slice(0, 10)}`;
+}
+/**
+* Display lines for a completed lesson.
+* @param value - complete tool value.
+* @returns card lines.
+*/
+function completeLines(value) {
+	const lines = [`🎓 Mastered “${value.lessonTitle}”`];
+	for (const title of value.unlockedLessonTitles) lines.push(`🔓 Unlocked “${title}”`);
+	lines.push(`🔁 First review due ${value.reviewDueAt.slice(0, 10)}`);
+	if (value.courseComplete) lines.push("🏁 Course complete!");
+	return lines;
+}
+//#endregion
+//#region src/tools.ts
+/**
+* The `study_*` tool surface, ported from LookatStudy's agent contract:
+* import (markdown / folder / GitHub), course map, lesson content with
+* concepts/starters/memory, KC-attributed answer recording with
+* mastery-driven progression, spaced reviews, mastery proposals, friction
+* logging, learner memory, Cornell notes, and soul switching. All state
+* mutations persist synchronously through the shared store.
+* @module dsh-plugin-lookatstudy/tools
+*/
+/** SM-2 quality grades, shared by the parameter enum and the state layer. */
+const QUALITIES = [
+	0,
+	1,
+	2,
+	3,
+	4,
+	5
+];
+const LESSON_STATUSES = [
+	"locked",
+	"available",
+	"in_progress",
+	"mastered"
+];
+const LESSON_KINDS = [
+	"study",
+	"practice",
+	"exam"
+];
+const FRICTION_CATEGORIES = [
+	"confused",
+	"blocked",
+	"frustrated"
+];
+const MEMORY_CATEGORIES = [
+	"global",
+	"pattern",
+	"lesson"
+];
+const NOTE_ZONES = [
+	"understand",
+	"record",
+	"practice"
+];
+const NOTE_SOURCES = [
+	"ai",
+	"content",
+	"chat"
+];
+const MODES = [
+	"direct",
+	"guide",
+	"practice"
+];
+const nullableInteger = { oneOf: [{ type: "integer" }, { type: "null" }] };
+const nullableString = { oneOf: [{ type: "string" }, { type: "null" }] };
+/**
+* Fail loud when an importer produced no lessons — a course with an empty
+* path is useless and hides upstream parsing problems. Runs before any state
+* mutation so a failed import leaves persisted state untouched.
+* @param parsed - parsed course about to be imported.
+*/
+function requireParsedLessons(parsed) {
+	if (parsed.sections.reduce((n, s) => n + s.lessons.length, 0) === 0) throw new Error("lookatstudy-plugin: import produced 0 lessons — the source needs ## sections containing ### lessons, or lesson-like files in a folder");
+}
+/** Canonical value shared by the three import tools. */
+function toImportValue(course) {
+	const lessons = course.sections.flatMap((s) => s.lessons);
+	const first = lessons.find((l) => l.status === "available") ?? lessons[0];
+	return {
+		courseId: course.id,
+		title: course.title,
+		sections: course.sections.length,
+		lessons: lessons.length,
+		firstLessonId: first.id,
+		firstLessonTitle: first.title
+	};
+}
+/** Canonical value of `study_map`. */
+function toMapValue(course) {
+	const lessons = course.sections.flatMap((s) => s.lessons);
+	return {
+		courseId: course.id,
+		title: course.title,
+		counts: {
+			total: lessons.length,
+			mastered: lessons.filter((l) => l.status === "mastered").length,
+			available: lessons.filter((l) => l.status === "available").length
+		},
+		tree: course.sections.map((section) => ({
+			title: section.title,
+			lessons: section.lessons.map((lesson) => ({
+				id: lesson.id,
+				title: lesson.title,
+				kind: lesson.kind,
+				status: lesson.status,
+				masteryPct: lesson.mastery === null ? null : Math.round(lesson.mastery * 100),
+				crown: masteryToCrown(lesson.mastery),
+				weakConcepts: (conceptViews(lesson) ?? []).filter((c) => c.weak).length,
+				frictionCount: lesson.friction.length
+			}))
+		}))
+	};
+}
+/** Canonical value of `study_lesson`. */
+function toLessonValue(ref, state) {
+	const next = nextLesson(ref.course, ref.lesson.id);
+	const pending = state.proposals.find((p) => p.lessonId === ref.lesson.id && p.status === "pending");
+	return {
+		lessonId: ref.lesson.id,
+		courseId: ref.course.id,
+		courseTitle: ref.course.title,
+		sectionTitle: ref.section.title,
+		title: ref.lesson.title,
+		kind: ref.lesson.kind,
+		status: ref.lesson.status,
+		body: ref.lesson.body,
+		masteryPct: ref.lesson.mastery === null ? null : Math.round(ref.lesson.mastery * 100),
+		crown: masteryToCrown(ref.lesson.mastery),
+		attempts: ref.lesson.attempts,
+		correctCount: ref.lesson.correctCount,
+		strategy: strategyBand(ref.lesson.mastery),
+		concepts: conceptViews(ref.lesson),
+		starters: starterPrompts(ref.lesson.title),
+		memory: {
+			lesson: ref.lesson.memory,
+			global: state.memoryGlobal,
+			pattern: state.memoryPatterns[ref.course.id] ?? null
+		},
+		noteCount: ref.lesson.notes.length,
+		pendingProposal: pending === void 0 ? null : {
+			id: pending.id,
+			rationale: pending.rationale
+		},
+		nextLessonId: next?.id ?? null
+	};
+}
+/**
+* Parse a GitHub repository URL into owner/repo.
+* @param url - `https://github.com/<owner>/<repo>` (`.git` suffix and subpaths tolerated).
+* @returns owner and repo.
+*/
+function parseGithubUrl(url) {
+	const match = url.match(/^(?:https?:\/\/)?github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?(?:[/?#].*)?$/);
+	if (!match) throw new Error(`lookatstudy-plugin: not a GitHub repository URL: ${JSON.stringify(url)} (expected https://github.com/<owner>/<repo>)`);
+	return {
+		owner: match[1],
+		repo: match[2]
+	};
+}
+/** Wrap `fetch` so cancellation of the tool call aborts in-flight repo fetches. */
+function signalFetch(signal) {
+	return (input, init) => fetch(input, {
+		...init,
+		signal
+	});
+}
+/** Total over a missing `meta` (events logged before a presentationMeta existed): renders nothing instead of throwing into the presenter fallback. */
+const textBlocks = (lines) => (lines ?? []).map((text) => ({
+	type: "text",
+	text
+}));
+/**
+* Build the full study tool set over one store.
+* @param store - state store owned by `apply`.
+* @returns tool definitions ready for `ctx.tools.register`.
+*/
+function studyTools(store) {
+	/** Run a mutating state operation and persist. */
+	const mutate = (fn) => {
+		const result = fn(store.get());
+		store.save();
+		return result;
+	};
+	const importOutput = { schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			courseId: {
+				type: "string",
+				required: true
+			},
+			title: {
+				type: "string",
+				required: true
+			},
+			sections: {
+				type: "integer",
+				required: true
+			},
+			lessons: {
+				type: "integer",
+				required: true
+			},
+			firstLessonId: {
+				type: "string",
+				required: true
+			},
+			firstLessonTitle: {
+				type: "string",
+				required: true
+			}
+		}
+	} };
+	const importPresent = {
+		presentationMeta: (_args, value) => importLines(value),
+		presentResult: (_args, result) => ({
+			card: "generic",
+			content: textBlocks(result.meta)
+		})
+	};
+	return [
+		defineTool({
+			name: "study_import_markdown",
+			description: "Import pasted markdown as a structured course: H2 (##) becomes a section, H3 (###) a lesson. Use for notes, single long documents, or content fetched by other means.",
+			parameters: {
+				markdown: {
+					type: "string",
+					required: true,
+					description: "The full markdown source of the course."
+				},
+				title: {
+					type: "string",
+					description: "Optional course title overriding the first H1."
+				}
+			},
+			output: {
+				...importOutput,
+				render: (_args, value) => [{
+					type: "text",
+					text: `Imported course “${value.title}” (${value.sections} sections, ${value.lessons} lessons). First lesson: “${value.firstLessonTitle}” (id ${value.firstLessonId}).`
+				}]
+			},
+			async execute(args) {
+				const parsed = parseMarkdownToCourse(args.markdown);
+				if (args.title !== void 0) parsed.title = args.title;
+				requireParsedLessons(parsed);
+				return mutate((state) => toImportValue(importCourse(state, parsed, "markdown", "pasted markdown")));
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Import markdown course${args.title === void 0 ? "" : `: ${args.title}`}`,
+				kind: "read"
+			}),
+			...importPresent
+		}),
+		defineTool({
+			name: "study_import_folder",
+			description: "Import a local folder as a course: markdown, txt, html, Jupyter notebooks, rst/Rmd/org/adoc, and 30+ code file types become lessons grouped into sections by directory (code is teaching material too). PDF/PPTX are not supported in this edition.",
+			parameters: {
+				path: {
+					type: "string",
+					required: true,
+					description: "Absolute path of the folder to scan."
+				},
+				title: {
+					type: "string",
+					description: "Optional course title overriding the folder name."
+				}
+			},
+			output: {
+				...importOutput,
+				render: (_args, value) => [{
+					type: "text",
+					text: `Imported folder course “${value.title}” (${value.sections} sections, ${value.lessons} lessons). First lesson: “${value.firstLessonTitle}” (id ${value.firstLessonId}).`
+				}]
+			},
+			async execute(args) {
+				if (!existsSync(args.path)) throw new Error(`lookatstudy-plugin: folder does not exist: ${args.path}`);
+				const files = (await scanFolder(args.path)).map((doc) => ({
+					path: doc.path,
+					title: doc.title,
+					md: doc.content
+				}));
+				const parsed = buildCourseFromFiles(args.title ?? basename(args.path.replaceAll("\\", "/")), files);
+				requireParsedLessons(parsed);
+				return mutate((state) => toImportValue(importCourse(state, parsed, "folder", args.path)));
+			},
+			timeoutMs: 6e4,
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Scan folder: ${args.path}`,
+				kind: "read",
+				rawInput: args.path
+			}),
+			...importPresent
+		}),
+		defineTool({
+			name: "study_import_github",
+			description: "Import a GitHub learning repository as a course. Discovery follows the README outline, files are fetched through the jsDelivr CDN (works where github.com is unreachable). Best for curated curricula (e.g. microsoft/AI-For-Beginners); awesome-lists are rejected.",
+			parameters: {
+				url: {
+					type: "string",
+					required: true,
+					description: "Repository URL, e.g. https://github.com/microsoft/AI-For-Beginners."
+				},
+				branch: {
+					type: "string",
+					description: "Branch to read (main tried, then master); defaults to main."
+				}
+			},
+			output: {
+				...importOutput,
+				render: (_args, value) => [{
+					type: "text",
+					text: `Imported GitHub course “${value.title}” (${value.sections} sections, ${value.lessons} lessons). First lesson: “${value.firstLessonTitle}” (id ${value.firstLessonId}).`
+				}]
+			},
+			async execute(args, exec) {
+				const { owner, repo } = parseGithubUrl(args.url);
+				const result = await importRepoToParsedCourse(owner, repo, args.branch ?? "main", signalFetch(exec.signal));
+				requireParsedLessons(result.course);
+				return mutate((state) => toImportValue(importCourse(state, result.course, "github", args.url)));
+			},
+			timeoutMs: 18e4,
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Import GitHub course: ${args.url}`,
+				kind: "fetch"
+			}),
+			...importPresent
+		}),
+		defineTool({
+			name: "study_courses",
+			description: "List imported courses with progress, average mastery, due reviews, and the current lesson id.",
+			parameters: {},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						total: {
+							type: "integer",
+							required: true
+						},
+						courses: {
+							type: "array",
+							required: true,
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									courseId: {
+										type: "string",
+										required: true
+									},
+									title: {
+										type: "string",
+										required: true
+									},
+									source: {
+										type: "string",
+										required: true,
+										enum: [
+											"markdown",
+											"folder",
+											"github"
+										]
+									},
+									total: {
+										type: "integer",
+										required: true
+									},
+									mastered: {
+										type: "integer",
+										required: true
+									},
+									avgMasteryPct: {
+										...nullableInteger,
+										required: true
+									},
+									dueCount: {
+										type: "integer",
+										required: true
+									},
+									currentLessonId: {
+										...nullableString,
+										required: true
+									}
+								}
+							}
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: value.courses.length === 0 ? "No courses imported yet. Import one with study_import_markdown, study_import_folder, or study_import_github." : value.courses.map((c) => `“${c.title}” (${c.source}) — ${c.mastered}/${c.total} lessons mastered${c.avgMasteryPct === null ? "" : `, avg mastery ${c.avgMasteryPct}%`}${c.dueCount === 0 ? "" : `, ${c.dueCount} reviews due`}${c.currentLessonId === null ? "" : `, current lesson ${c.currentLessonId}`}`).join("\n")
+				}]
+			},
+			async execute() {
+				const summaries = courseSummaries(store.get(), /* @__PURE__ */ new Date());
+				return {
+					total: summaries.length,
+					courses: summaries.map((s) => ({
+						courseId: s.courseId,
+						title: s.title,
+						source: s.source,
+						total: s.total,
+						mastered: s.mastered,
+						avgMasteryPct: s.avgMasteryPct,
+						dueCount: s.dueCount,
+						currentLessonId: s.currentLessonId
+					}))
+				};
+			},
+			isConcurrencySafe: () => true,
+			presentCall: () => ({
+				card: "generic",
+				title: "List courses",
+				kind: "read"
+			})
+		}),
+		defineTool({
+			name: "study_map",
+			description: "Show one course's skill tree: sections, lessons with locked/available/in_progress/mastered status, mastery, weak-concept count (⚡), and friction count — the weak spots to target.",
+			parameters: { courseId: {
+				type: "string",
+				required: true,
+				description: "Course id from an import result or study_courses."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						courseId: {
+							type: "string",
+							required: true
+						},
+						title: {
+							type: "string",
+							required: true
+						},
+						counts: {
+							type: "object",
+							required: true,
+							additionalProperties: false,
+							properties: {
+								total: {
+									type: "integer",
+									required: true
+								},
+								mastered: {
+									type: "integer",
+									required: true
+								},
+								available: {
+									type: "integer",
+									required: true
+								}
+							}
+						},
+						tree: {
+							type: "array",
+							required: true,
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									title: {
+										type: "string",
+										required: true
+									},
+									lessons: {
+										type: "array",
+										required: true,
+										items: {
+											type: "object",
+											additionalProperties: false,
+											properties: {
+												id: {
+													type: "string",
+													required: true
+												},
+												title: {
+													type: "string",
+													required: true
+												},
+												kind: {
+													type: "string",
+													required: true,
+													enum: [...LESSON_KINDS]
+												},
+												status: {
+													type: "string",
+													required: true,
+													enum: [...LESSON_STATUSES]
+												},
+												masteryPct: {
+													...nullableInteger,
+													required: true
+												},
+												crown: {
+													type: "integer",
+													required: true
+												},
+												weakConcepts: {
+													type: "integer",
+													required: true
+												},
+												frictionCount: {
+													type: "integer",
+													required: true
+												}
+											}
+										}
+									}
+								}
+							}
+						}
+					}
+				},
+				render: (_args, value) => textBlocks(mapLines(value))
+			},
+			async execute(args) {
+				return toMapValue(findCourse(store.get(), args.courseId));
+			},
+			isConcurrencySafe: () => true,
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Course map: ${args.courseId}`,
+				kind: "read"
+			}),
+			presentationMeta: (_args, value) => mapLines(value),
+			presentResult: (_args, result) => ({
+				card: "generic",
+				content: textBlocks(result.meta)
+			})
+		}),
+		defineTool({
+			name: "study_lesson",
+			description: "Open one lesson and make it the focus: returns its markdown content (the source of truth to teach from), teaching strategy band, knowledge concepts with mastery/weak flags, four consolidation starters, memory slots, and any pending mastery proposal.",
+			parameters: { lessonId: {
+				type: "string",
+				required: true,
+				description: "Lesson id from a map, import, or courses call."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						lessonId: {
+							type: "string",
+							required: true
+						},
+						courseId: {
+							type: "string",
+							required: true
+						},
+						courseTitle: {
+							type: "string",
+							required: true
+						},
+						sectionTitle: {
+							type: "string",
+							required: true
+						},
+						title: {
+							type: "string",
+							required: true
+						},
+						kind: {
+							type: "string",
+							required: true,
+							enum: [...LESSON_KINDS]
+						},
+						status: {
+							type: "string",
+							required: true,
+							enum: [...LESSON_STATUSES]
+						},
+						body: {
+							type: "string",
+							required: true
+						},
+						masteryPct: {
+							...nullableInteger,
+							required: true
+						},
+						crown: {
+							type: "integer",
+							required: true
+						},
+						attempts: {
+							type: "integer",
+							required: true
+						},
+						correctCount: {
+							type: "integer",
+							required: true
+						},
+						strategy: {
+							type: "string",
+							required: true
+						},
+						concepts: {
+							oneOf: [{ type: "null" }, {
+								type: "array",
+								items: {
+									type: "object",
+									additionalProperties: false,
+									properties: {
+										title: {
+											type: "string",
+											required: true
+										},
+										masteryPct: {
+											type: "integer",
+											required: true
+										},
+										weak: {
+											type: "boolean",
+											required: true
+										},
+										/** 1 once this concept has been quizzed at least once, else 0 (ConceptView.tested). */
+										tested: {
+											type: "integer",
+											required: true
+										}
+									}
+								}
+							}],
+							required: true
+						},
+						starters: {
+							type: "array",
+							required: true,
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									label: {
+										type: "string",
+										required: true
+									},
+									message: {
+										type: "string",
+										required: true
+									},
+									effect: {
+										type: "string",
+										required: true,
+										enum: [
+											"mastery",
+											"friction",
+											"none"
+										]
+									}
+								}
+							}
+						},
+						memory: {
+							type: "object",
+							required: true,
+							additionalProperties: false,
+							properties: {
+								lesson: {
+									...nullableString,
+									required: true
+								},
+								global: {
+									...nullableString,
+									required: true
+								},
+								pattern: {
+									...nullableString,
+									required: true
+								}
+							}
+						},
+						noteCount: {
+							type: "integer",
+							required: true
+						},
+						pendingProposal: {
+							oneOf: [{ type: "null" }, {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									id: {
+										type: "string",
+										required: true
+									},
+									rationale: {
+										type: "string",
+										required: true
+									}
+								}
+							}],
+							required: true
+						},
+						nextLessonId: {
+							...nullableString,
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `Lesson “${value.title}” — ${value.courseTitle} / ${value.sectionTitle}\nstatus ${value.status}${value.masteryPct === null ? "" : `, mastery ${value.masteryPct}%`}, ${value.correctCount}/${value.attempts} answers correct\nstrategy: ${value.strategy}\n` + (value.concepts === null ? "" : `concepts: ${value.concepts.map((c) => `${c.title} ${c.masteryPct}%${c.weak ? " ⚡weak" : ""}`).join(" · ")}\n`) + `starters: ${value.starters.map((s) => s.label).join(" / ")}\n\n${value.body}${value.nextLessonId === null ? "\n\n(this is the last lesson)" : `\n\n(next lesson: ${value.nextLessonId})`}`
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					const { ref } = attemptLesson(state, args.lessonId, /* @__PURE__ */ new Date());
+					state.focus = { lessonId: ref.lesson.id };
+					return toLessonValue(ref, state);
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Open lesson: ${args.lessonId}`,
+				kind: "read"
+			})
+		}),
+		defineTool({
+			name: "study_record_answer",
+			description: "Record one graded answer and update mastery — call after EVERY learner answer to a scored question. Name the `concept` the question tested (from study_lesson / study_define_concepts) so per-concept mastery stays accurate; lesson mastery is the WEAKEST concept. Mastery ≥50% unlocks the next lesson early; ≥90% graduates automatically and schedules the first review. Also pass the question text and the learner's answer to keep a practice log.",
+			parameters: {
+				lessonId: {
+					type: "string",
+					required: true,
+					description: "Lesson the question tested."
+				},
+				correct: {
+					type: "boolean",
+					required: true,
+					description: "Whether the learner answered correctly."
+				},
+				concept: {
+					type: "string",
+					description: "Concept title the question tested (required once concepts are defined)."
+				},
+				rationale: {
+					type: "string",
+					description: "One line: why you graded it this way."
+				},
+				question: {
+					type: "string",
+					description: "The question text, for the practice log."
+				},
+				givenAnswer: {
+					type: "string",
+					description: "The learner's answer, for the practice log."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						lessonId: {
+							type: "string",
+							required: true
+						},
+						lessonTitle: {
+							type: "string",
+							required: true
+						},
+						correct: {
+							type: "boolean",
+							required: true
+						},
+						concept: {
+							oneOf: [{ type: "null" }, {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									title: {
+										type: "string",
+										required: true
+									},
+									masteryPct: {
+										type: "integer",
+										required: true
+									},
+									weak: {
+										type: "boolean",
+										required: true
+									}
+								}
+							}],
+							required: true
+						},
+						prevMasteryPct: {
+							type: "integer",
+							required: true
+						},
+						newMasteryPct: {
+							type: "integer",
+							required: true
+						},
+						crown: {
+							type: "integer",
+							required: true
+						},
+						mastered: {
+							type: "boolean",
+							required: true
+						},
+						attempts: {
+							type: "integer",
+							required: true
+						},
+						correctCount: {
+							type: "integer",
+							required: true
+						},
+						graduated: {
+							type: "boolean",
+							required: true
+						},
+						unlockedLessonIds: {
+							type: "array",
+							required: true,
+							items: { type: "string" }
+						},
+						reviewDueAt: {
+							...nullableString,
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: answerLine(value) + (value.concept === null ? "" : `\nconcept: ${value.concept.title} ${value.concept.masteryPct}%${value.concept.weak ? " ⚡weak" : ""}`) + (value.graduated ? "\n🎓 mastery ≥90% — lesson graduated, first review scheduled." : "") + (value.unlockedLessonIds.length === 0 ? "" : `\n🔓 unlocked: ${value.unlockedLessonIds.join(", ")}`)
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					const r = recordAnswer(state, args.lessonId, args.correct, args.concept, /* @__PURE__ */ new Date());
+					if (args.question !== void 0) addNote(state, args.lessonId, "practice", args.question.slice(0, 80), `${args.question}\n\nlearner answered: ${args.givenAnswer ?? "(not recorded)"} — ${args.correct ? "✓ correct" : "✗ incorrect"}${args.rationale === void 0 ? "" : `\nrationale: ${args.rationale}`}`, "ai", null, /* @__PURE__ */ new Date());
+					return {
+						lessonId: r.ref.lesson.id,
+						lessonTitle: r.ref.lesson.title,
+						correct: args.correct,
+						concept: r.concept === null ? null : {
+							title: r.concept.title,
+							masteryPct: Math.round(r.concept.mastery * 100),
+							weak: r.concept.mastery < .7
+						},
+						prevMasteryPct: Math.round(r.prevMastery * 100),
+						newMasteryPct: Math.round(r.newMastery * 100),
+						crown: r.crown,
+						mastered: r.mastered,
+						attempts: r.ref.lesson.attempts,
+						correctCount: r.ref.lesson.correctCount,
+						graduated: r.progression.graduated,
+						unlockedLessonIds: r.progression.unlocked.map((u) => u.id),
+						reviewDueAt: r.progression.nextDue
+					};
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Record answer (${args.correct ? "correct" : "incorrect"}): ${args.lessonId}`
+			}),
+			presentationMeta: (_args, value) => [answerLine(value)],
+			presentResult: (_args, result) => ({
+				card: "generic",
+				content: textBlocks(result.meta)
+			})
+		}),
+		defineTool({
+			name: "study_complete_lesson",
+			description: "Mark a lesson mastered manually (graduation at 90% mastery is the automatic path — this is the override). Unlocks the next lesson and schedules the first spaced review for tomorrow. Call only when the learner has genuinely worked through the lesson.",
+			parameters: { lessonId: {
+				type: "string",
+				required: true,
+				description: "Lesson to complete."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						lessonId: {
+							type: "string",
+							required: true
+						},
+						lessonTitle: {
+							type: "string",
+							required: true
+						},
+						unlockedLessonIds: {
+							type: "array",
+							required: true,
+							items: { type: "string" }
+						},
+						unlockedLessonTitles: {
+							type: "array",
+							required: true,
+							items: { type: "string" }
+						},
+						reviewDueAt: {
+							type: "string",
+							required: true
+						},
+						courseComplete: {
+							type: "boolean",
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: completeLines(value).join("\n")
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					const r = completeLesson(state, args.lessonId, /* @__PURE__ */ new Date());
+					return {
+						lessonId: r.ref.lesson.id,
+						lessonTitle: r.ref.lesson.title,
+						unlockedLessonIds: r.unlocked.map((u) => u.id),
+						unlockedLessonTitles: r.unlocked.map((u) => u.title),
+						reviewDueAt: r.dueAt,
+						courseComplete: r.courseComplete
+					};
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Complete lesson: ${args.lessonId}`
+			}),
+			presentationMeta: (_args, value) => completeLines(value),
+			presentResult: (_args, result) => ({
+				card: "generic",
+				content: textBlocks(result.meta)
+			})
+		}),
+		defineTool({
+			name: "study_due_reviews",
+			description: "List mastered lessons whose spaced-repetition review is due (optionally within one course), oldest first. Start every session here.",
+			parameters: { courseId: {
+				type: "string",
+				description: "Restrict to one course; omit to scan all courses."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						total: {
+							type: "integer",
+							required: true
+						},
+						due: {
+							type: "array",
+							required: true,
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									lessonId: {
+										type: "string",
+										required: true
+									},
+									courseTitle: {
+										type: "string",
+										required: true
+									},
+									lessonTitle: {
+										type: "string",
+										required: true
+									},
+									dueAt: {
+										type: "string",
+										required: true
+									},
+									overdueDays: {
+										type: "integer",
+										required: true
+									}
+								}
+							}
+						}
+					}
+				},
+				render: (_args, value) => textBlocks(dueLines(value))
+			},
+			async execute(args) {
+				const due = dueReviews(store.get(), args.courseId, /* @__PURE__ */ new Date());
+				return {
+					total: due.length,
+					due: due.map((d) => ({
+						lessonId: d.lessonId,
+						courseTitle: d.courseTitle,
+						lessonTitle: d.lessonTitle,
+						dueAt: d.dueAt,
+						overdueDays: d.overdueDays
+					}))
+				};
+			},
+			isConcurrencySafe: () => true,
+			presentCall: () => ({
+				card: "generic",
+				title: "List due reviews",
+				kind: "search"
+			}),
+			presentationMeta: (_args, value) => dueLines(value),
+			presentResult: (_args, result) => ({
+				card: "generic",
+				content: textBlocks(result.meta)
+			})
+		}),
+		defineTool({
+			name: "study_record_review",
+			description: "Record an SM-2 review grade for a mastered lesson and advance its schedule. Grade how well the learner recalled the material: 5 perfect, 4 hesitant, 3 recalled with effort, 2 incorrect but recognized, 1 incorrect, 0 complete blackout. Target weak concepts (⚡) first.",
+			parameters: {
+				lessonId: {
+					type: "string",
+					required: true,
+					description: "Lesson being reviewed."
+				},
+				quality: {
+					type: "integer",
+					required: true,
+					enum: [...QUALITIES],
+					description: "SM-2 recall quality, 0 (blackout) to 5 (perfect)."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						lessonId: {
+							type: "string",
+							required: true
+						},
+						lessonTitle: {
+							type: "string",
+							required: true
+						},
+						quality: {
+							type: "integer",
+							required: true
+						},
+						intervalDays: {
+							type: "integer",
+							required: true
+						},
+						repetitions: {
+							type: "integer",
+							required: true
+						},
+						easeFactor: {
+							type: "number",
+							required: true
+						},
+						dueAt: {
+							type: "string",
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: reviewLine(value)
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					const r = recordReview(state, args.lessonId, args.quality, /* @__PURE__ */ new Date());
+					return {
+						lessonId: r.ref.lesson.id,
+						lessonTitle: r.ref.lesson.title,
+						quality: args.quality,
+						intervalDays: r.intervalDays,
+						repetitions: r.repetitions,
+						easeFactor: r.easeFactor,
+						dueAt: r.dueAt
+					};
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Record review (quality ${args.quality}): ${args.lessonId}`
+			}),
+			presentationMeta: (_args, value) => [reviewLine(value)],
+			presentResult: (_args, result) => ({
+				card: "generic",
+				content: textBlocks(result.meta)
+			})
+		}),
+		defineTool({
+			name: "study_delete_course",
+			description: "Delete one course and all its progress. Ask the learner before calling.",
+			parameters: { courseId: {
+				type: "string",
+				required: true,
+				description: "Course to delete."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						deletedCourseId: {
+							type: "string",
+							required: true
+						},
+						remaining: {
+							type: "integer",
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `Deleted course ${value.deletedCourseId}. ${value.remaining} courses remain.`
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					findCourse(state, args.courseId);
+					deleteCourse(state, args.courseId);
+					return {
+						deletedCourseId: args.courseId,
+						remaining: state.courses.length
+					};
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Delete course: ${args.courseId}`,
+				kind: "delete",
+				rawInput: args.courseId
+			})
+		}),
+		defineTool({
+			name: "study_define_concepts",
+			description: "Define a lesson's knowledge components — the 2–7 independently quizzable units mastery tracks. Call this the FIRST time you teach a lesson, derived from its content. Titles ≤10 characters; descriptions say what understanding this concept means. Lesson mastery is the WEAKEST concept; cover weak ones (⚡) first when quizzing.",
+			parameters: {
+				lessonId: {
+					type: "string",
+					required: true,
+					description: "Lesson to describe."
+				},
+				concepts: {
+					type: "array",
+					required: true,
+					description: "2–7 concepts.",
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							title: {
+								type: "string",
+								required: true,
+								description: "Short concept title (≤10 chars)."
+							},
+							description: {
+								type: "string",
+								required: true,
+								description: "What understanding this concept means."
+							}
+						}
+					}
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						lessonId: {
+							type: "string",
+							required: true
+						},
+						concepts: {
+							type: "array",
+							required: true,
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									title: {
+										type: "string",
+										required: true
+									},
+									masteryPct: {
+										type: "integer",
+										required: true
+									}
+								}
+							}
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `Concepts defined: ${value.concepts.map((c) => `${c.title} (${c.masteryPct}%)`).join(" · ")}. Attribute quiz answers with the \`concept\` parameter.`
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					defineConcepts(state, args.lessonId, args.concepts);
+					const ref = findLesson(state, args.lessonId);
+					return {
+						lessonId: ref.lesson.id,
+						concepts: (conceptViews(ref.lesson) ?? []).map((c) => ({
+							title: c.title,
+							masteryPct: c.masteryPct
+						}))
+					};
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Define concepts: ${args.lessonId}`
+			})
+		}),
+		defineTool({
+			name: "study_propose_mastery",
+			description: "Propose graduating a lesson as mastered ahead of the 90% threshold — use when mastery is ≥85% and the learner has convincingly demonstrated understanding (e.g. a Feynman-style explanation back to you). Creates a PENDING proposal: present it with your rationale and WAIT for the learner's decision, then resolve with study_resolve_proposal. Never apply it yourself.",
+			parameters: {
+				lessonId: {
+					type: "string",
+					required: true,
+					description: "Lesson judged mastered."
+				},
+				rationale: {
+					type: "string",
+					required: true,
+					description: "Why you believe it is mastered — the learner reads this."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						proposalId: {
+							type: "string",
+							required: true
+						},
+						lessonTitle: {
+							type: "string",
+							required: true
+						},
+						status: {
+							type: "string",
+							required: true,
+							enum: [
+								"pending",
+								"applied",
+								"rejected"
+							]
+						},
+						rationale: {
+							type: "string",
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `Proposal ${value.proposalId} (${value.status}): “${value.lessonTitle}” — ${value.rationale}\nPresent this to the learner and wait; resolve via study_resolve_proposal.`
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					const ref = findLesson(state, args.lessonId);
+					const proposal = proposeMastery(state, args.lessonId, args.rationale, /* @__PURE__ */ new Date());
+					return {
+						proposalId: proposal.id,
+						lessonTitle: ref.lesson.title,
+						status: proposal.status,
+						rationale: proposal.rationale
+					};
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Propose mastery: ${args.lessonId}`
+			}),
+			presentationMeta: (_args, value) => ({
+				kind: "study-proposal-created",
+				proposalId: value.proposalId,
+				lessonTitle: value.lessonTitle,
+				rationale: value.rationale
+			}),
+			presentResult: (_args, result) => ({
+				card: "generic",
+				content: textBlocks([`🎓 Proposed mastery for “${result.meta?.lessonTitle ?? "lesson"}”: ${result.meta?.rationale ?? ""}`])
+			})
+		}),
+		defineTool({
+			name: "study_resolve_proposal",
+			description: "Resolve a pending mastery proposal with the learner's explicit decision (they said yes / no in chat). Accepting floors every concept to 95%, graduates the lesson, and unlocks the next one.",
+			parameters: {
+				proposalId: {
+					type: "string",
+					required: true,
+					description: "Proposal id from study_propose_mastery."
+				},
+				accept: {
+					type: "boolean",
+					required: true,
+					description: "The learner's decision."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						proposalId: {
+							type: "string",
+							required: true
+						},
+						lessonId: {
+							type: "string",
+							required: true
+						},
+						status: {
+							type: "string",
+							required: true,
+							enum: ["applied", "rejected"]
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: value.status === "applied" ? `🎓 Proposal applied — lesson ${value.lessonId} mastered (all concepts ≥95%), next lesson unlocked, review scheduled.` : `Proposal rejected — continuing practice on ${value.lessonId}.`
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					const proposal = resolveProposal(state, args.proposalId, args.accept, /* @__PURE__ */ new Date());
+					return {
+						proposalId: proposal.id,
+						lessonId: proposal.lessonId,
+						status: proposal.status
+					};
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Resolve proposal: ${args.proposalId}`
+			}),
+			presentationMeta: (_args, value) => ({
+				kind: "study-proposal-resolved",
+				proposalId: value.proposalId,
+				status: value.status
+			}),
+			presentResult: (_args, result) => ({
+				card: "generic",
+				content: textBlocks([`Proposal ${result.meta?.proposalId ?? "?"} ${result.meta?.status ?? ""}.`])
+			})
+		}),
+		defineTool({
+			name: "study_report_friction",
+			description: "SILENTLY log a learning-friction moment — call when the learner seems confused (糊涂), stuck (卡住), or frustrated (受挫), or when they say \"我没太懂\". One short line. Never mention that you logged it; it feeds the weak-spot map and adapts difficulty.",
+			parameters: {
+				category: {
+					type: "string",
+					required: true,
+					enum: [...FRICTION_CATEGORIES],
+					description: "confused | blocked | frustrated."
+				},
+				summary: {
+					type: "string",
+					description: "One short line: what specifically is hard."
+				},
+				lessonId: {
+					type: "string",
+					description: "Lesson it happened on, when known."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: { logged: {
+						type: "boolean",
+						required: true
+					} }
+				},
+				render: () => [{
+					type: "text",
+					text: "Noted."
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					addFriction(state, args.lessonId ?? null, args.category, args.summary ?? null, /* @__PURE__ */ new Date());
+					return { logged: true };
+				});
+			},
+			presentCall: () => ({
+				card: "generic",
+				title: "Log friction"
+			})
+		}),
+		defineTool({
+			name: "study_remember",
+			description: "Write a learner-memory slot — call only when you learn something worth keeping across sessions (how they best learn, a recurring pattern, a specific gap). NOT for transient chat. To merge: read the current slot first (study_lesson's memory field), then send the merged 1–3 sentence version — this REPLACES the slot.",
+			parameters: {
+				category: {
+					type: "string",
+					required: true,
+					enum: [...MEMORY_CATEGORIES],
+					description: "global (cross-course style) | pattern (per-course recurring pattern) | lesson (this lesson's specific gap)."
+				},
+				content: {
+					type: "string",
+					required: true,
+					description: "The merged 1–3 sentence slot content."
+				},
+				lessonId: {
+					type: "string",
+					description: "Lesson (for the lesson slot) or any lesson of the course (for the pattern slot)."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						previous: {
+							...nullableString,
+							required: true
+						},
+						stored: {
+							type: "string",
+							required: true
+						}
+					}
+				},
+				render: () => [{
+					type: "text",
+					text: "Remembered."
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => ({
+					previous: setMemory(state, args.category, args.content, args.lessonId),
+					stored: args.content
+				}));
+			},
+			presentCall: () => ({
+				card: "generic",
+				title: "Update learner memory"
+			})
+		}),
+		defineTool({
+			name: "study_note_save",
+			description: "Save an entry to the learner's Cornell notebook. Zones: `understand` (knowledge structures you generated — concept maps as mermaid, compare tables, diagrams; sediment your best structures here after showing them), `record` (the learner's own words — when they ask to take a note, or when they write something worth keeping, with the verbatim `quote`), `practice` (quiz log — normally written automatically by study_record_answer).",
+			parameters: {
+				lessonId: {
+					type: "string",
+					required: true,
+					description: "Lesson the note belongs to."
+				},
+				zone: {
+					type: "string",
+					required: true,
+					enum: [...NOTE_ZONES],
+					description: "understand | record | practice."
+				},
+				title: {
+					type: "string",
+					required: true,
+					description: "Short entry title."
+				},
+				text: {
+					type: "string",
+					required: true,
+					description: "Entry body — markdown for the understand zone."
+				},
+				source: {
+					type: "string",
+					required: true,
+					enum: [...NOTE_SOURCES],
+					description: "ai (you generated) | content (quoted from lesson) | chat (quoted from conversation)."
+				},
+				quote: {
+					type: "string",
+					description: "Verbatim source quote, for record-zone notes."
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						noteId: {
+							type: "string",
+							required: true
+						},
+						zone: {
+							type: "string",
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `Saved ${value.zone}-zone note ${value.noteId}.`
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					const note = addNote(state, args.lessonId, args.zone, args.title, args.text, args.source, args.quote ?? null, /* @__PURE__ */ new Date());
+					return {
+						noteId: note.id,
+						zone: note.zone
+					};
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Save ${args.zone} note: ${args.title}`
+			})
+		}),
+		defineTool({
+			name: "study_notes",
+			description: "Read the learner's Cornell notebook: three zones per lesson (understand structures, learner records, practice log).",
+			parameters: { lessonId: {
+				type: "string",
+				description: "One lesson's notes; omit for all lessons (most recent last)."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						total: {
+							type: "integer",
+							required: true
+						},
+						notes: {
+							type: "array",
+							required: true,
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									id: {
+										type: "string",
+										required: true
+									},
+									lessonTitle: {
+										type: "string",
+										required: true
+									},
+									zone: {
+										type: "string",
+										required: true,
+										enum: [...NOTE_ZONES]
+									},
+									title: {
+										type: "string",
+										required: true
+									},
+									text: {
+										type: "string",
+										required: true
+									},
+									source: {
+										type: "string",
+										required: true,
+										enum: [...NOTE_SOURCES]
+									},
+									quote: {
+										...nullableString,
+										required: true
+									}
+								}
+							}
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: value.total === 0 ? "Notebook is empty." : value.notes.map((n) => `[${n.zone}] ${n.lessonTitle} — ${n.title}${n.quote === null ? "" : ` (quote: “${n.quote.slice(0, 60)}”)`}`).join("\n")
+				}]
+			},
+			async execute(args) {
+				const state = store.get();
+				const notes = (args.lessonId === void 0 ? state.courses.flatMap((c) => c.sections.flatMap((s) => s.lessons)) : [findLesson(state, args.lessonId).lesson]).flatMap((l) => l.notes.map((n) => ({
+					id: n.id,
+					lessonTitle: l.title,
+					zone: n.zone,
+					title: n.title,
+					text: n.text,
+					source: n.source,
+					quote: n.quote
+				})));
+				return {
+					total: notes.length,
+					notes
+				};
+			},
+			isConcurrencySafe: () => true,
+			presentCall: () => ({
+				card: "generic",
+				title: "Read notebook",
+				kind: "read"
+			})
+		}),
+		defineTool({
+			name: "study_set_mode",
+			description: "Switch the tutoring soul when the learner asks for a different style: `direct` 精讲 (explain first, then verify), `guide` 引导 (questions first, hand over steps), `practice` 实战 (learn inside real, messy problems). Takes effect from the next reply.",
+			parameters: { mode: {
+				type: "string",
+				required: true,
+				enum: [...MODES],
+				description: "direct | guide | practice."
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: { mode: {
+						type: "string",
+						required: true,
+						enum: [...MODES]
+					} }
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `Tutoring soul switched to ${value.mode} (effective next reply).`
+				}]
+			},
+			async execute(args) {
+				return mutate((state) => {
+					state.mode = args.mode;
+					return { mode: state.mode };
+				});
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Switch soul: ${args.mode}`
+			})
+		})
+	];
+}
+//#endregion
+//#region src/index.ts
+/**
+* dsh-plugin-lookatstudy — turn any markdown, local folder, or GitHub learning
+* repo into a guided course inside DeepSeek Harness. Registers the `study_*`
+* tool surface (ported from LookatStudy's agent contract), a stable tutor
+* persona plus a switchable soul section, and a dynamic learner-snapshot
+* context. Learning state persists in one JSON file shared across sessions.
+* @module dsh-plugin-lookatstudy
+*/
+const name = "lookatstudy-plugin";
+const inject = ["tools", "systemPrompt"];
+/**
+* Stable tutor core (ported from LookatStudy's BASE_AGENT_PROMPT plus its
+* tool contract). Deliberately static so the prefix hits the provider's
+* prompt cache; volatile facts live in the learner-snapshot context below.
+*/
+const TUTOR_CORE = `## Study tutor (lookatstudy-plugin)
+
+You are the learner's AI study tutor for a course imported via the study tools. Your job is genuine understanding, not reciting the material. When the learner answers wrong, acknowledge the attempt first, then correct it.
+
+### Grounding (hard rule)
+Teach strictly from the current lesson's content (study_lesson's body is the source of truth). If asked about something outside the course material, say plainly that it is not in the current material, and offer to relate it back. Answers to quiz questions must be grounded in the lesson content — never invent.
+
+### Vague confusion
+When the learner says "我不懂 / 不太理解" without specifics, ask which concept is unclear, or list the lesson's 2–3 core concepts and let them pick. Log it silently with study_report_friction.
+
+### Interaction form
+- ONE question or interactive block per reply — never a wall of quiz questions.
+- Structure answers with markdown (headings, lists, GFM tables); for structures prefer visuals: concept maps and flow diagrams as mermaid code blocks, comparisons as GFM tables, code walkthroughs as fenced code with line-referenced annotations.
+- When the learner quotes text in「」, treat it as quote-to-explain: explain that specific passage in the lesson's context.
+- Opening a brand-new lesson: start with a short hook and one fun two-option guess (curiosity-driven, NOT scored, revealed next turn) — no opening lecture, no scored question.
+- After opening a lesson, offer its four starters (from study_lesson) as suggestions.
+- Celebrate graduations and crowns briefly — earned joy, no confetti spam.
+
+### The tutoring loop
+1. Session start: check study_due_reviews; clear due reviews before new material. Open the focus lesson with study_lesson. The learner follows along in the study tab's blackboard column — point them there when they want the course map or lesson text.
+2. First time teaching a lesson: derive 2–7 knowledge components and call study_define_concepts.
+3. Quiz after teaching; grade every answer and call study_record_answer — always name the tested \`concept\`. Lesson mastery is the WEAKEST concept, so target ⚡weak ones first.
+4. Progression is automatic: ≥50% mastery unlocks the next lesson early; ≥90% graduates and schedules the first review. study_complete_lesson is only the manual override.
+5. Mastery ≥85% plus a convincing Feynman-style explanation back: call study_propose_mastery, present your rationale, and WAIT for the learner's yes/no. Resolve only with their explicit answer via study_resolve_proposal. You never graduate a lesson on your own judgment alone.
+6. Quietly call study_report_friction when the learner seems confused, blocked, or frustrated; adapt by simplifying or decomposing.
+7. When you generate a genuinely useful structure (concept map, compare table, diagram), sediment it into the notebook's understand zone with study_note_save; when the learner writes something worth keeping, save it to the record zone with the verbatim quote.
+8. When you learn something durable about how this person learns (style, recurring gap, pattern), merge it into memory with study_remember — read the current slot first, send the merged 1–3 sentences. No transient chat.
+
+### Quiz quality
+3–4 questions per quiz block is best (5 max), 4 options each. Distractors must come from real misconceptions, not absurd fillers. Test understanding, not recall: "in scenario Y, use X or Z?" rather than "define X". Every question carries an explanation of why the right answer is right. One scored block at a time.
+
+### Integrity
+Never claim progress you did not record through the tools. Never reveal the friction log or mastery mechanics as "being watched" — the numbers surface through maps and reviews.
+`;
+/** The three builtin souls, verbatim from LookatStudy (direct/guide/practice). */
+const SOULS = {
+	direct: `### Soul: direct 精讲
+你是讲解型教练。核心原则:**先讲清楚,再确认懂没懂**。
+1. 学习者问什么,先用一两句把核心讲透——不绕弯子、不反问让他猜。给定义时配一个最小例子。
+2. 讲完一个点,立刻出一个轻量确认题(是非/选择,不计掌握度),答对再往下;答错针对性补一句,不换题海。
+3. 抽象概念优先给完整范例(worked example),再让他在范例上动手改一个数。
+4. 他说"懂了"时,让他用自己的话复述一遍(费曼检验)——复述不出就再讲。
+5. 一次只推进一个核心点。讲透一个,不扫过一片。`,
+	guide: `### Soul: guide 引导
+你是引导型教练。核心原则:**让他自己往前推一步,你只递台阶**。
+1. 学习者问"X 是什么/为什么",不直接给答案,先抛一个引导性问题让他用已有知识推。
+2. 推对往深推一层;推偏给更具体的提示(不是答案),让他再试。
+3. 连着两次推不动、或他明说"直接告诉我",才给答案——给时附一句"为什么",建因果链。
+4. 检测到他连续答对三次,主动提议进入更深的子主题(不让他停舒适区)。
+5. 鼓励他费曼式复述刚推出的结论,验是否真懂。`,
+	practice: `### Soul: practice 实战
+你是实战型 mentor。核心原则:**在真实世界的乱问题里学,不在干净的练习题里学**。
+1. 每个概念落在一个真实的、边界模糊的问题上——不是"已知 A 求 B",而是"给你一笔预算/一个真实场景/一堆乱数据,你怎么决策"这类没有标准答案的问题。
+2. 先让他面对问题自己想思路(哪怕错),再把他卡住的地方和刚学的概念连起来——概念是工具,问题是主。
+3. 他卡住时给"下一步具体动作"(如"先把你要的变量列出来"),不给完整解;做完一步再推进。
+4. 一个问题走完,要求他复盘:哪步用了哪个概念、重来会怎么改。复盘比答对更重要。
+5. 主动串联:把当前问题和已学概念织成网,让他看到知识点在真实任务里怎么协作。`
+};
+/**
+* Render the learner snapshot (LookatStudy's per-turn volatile tail) as the
+* dynamic runtime context: focus, strategy band, concepts with weak flags,
+* recent friction, memory slots, due count, pending proposal.
+*/
+function snapshotText(store) {
+	const snap = learnerSnapshot(store.get(), /* @__PURE__ */ new Date());
+	if (snap.focus === null) return snap.dueCount === 0 ? "" : `【学习者当前状态】\n今日待复习: ${snap.dueCount} 项(study_due_reviews)`;
+	const lines = ["【学习者当前状态】"];
+	lines.push(`焦点: ${snap.focus.courseTitle} / ${snap.focus.lessonTitle}(${snap.focus.status}${snap.focus.masteryPct === null ? "" : `, 掌握度 ${snap.focus.masteryPct}%`})`);
+	if (snap.strategy !== null) lines.push(`教学策略: ${snap.strategy}`);
+	if (snap.concepts !== null && snap.concepts.length > 0) lines.push(`知识点(课级掌握度 = 最薄弱知识点): ${snap.concepts.map((c) => `${c.title} ${c.masteryPct}%${c.weak ? " ⚡薄弱" : ""}`).join(" · ")}`);
+	if (snap.friction.length > 0) lines.push(`近期卡点(共 ${snap.friction.length} 条): ${snap.friction.map((f) => `${f.category}${f.summary === null ? "" : `: ${f.summary}`}`).join(" / ")}`);
+	const memory = [
+		snap.memoryGlobal === null ? "" : `整体: ${snap.memoryGlobal}`,
+		snap.memoryLesson === null ? "" : `本课: ${snap.memoryLesson}`,
+		snap.memoryPattern === null ? "" : `模式: ${snap.memoryPattern}`
+	].filter(Boolean);
+	if (memory.length > 0) lines.push(`记忆: ${memory.join(" | ")}`);
+	if (snap.dueCount > 0) lines.push(`今日待复习: ${snap.dueCount} 项`);
+	if (snap.pendingProposal !== null) lines.push(`待决提案 ${snap.pendingProposal.id}: ${snap.pendingProposal.rationale}(等学习者表态)`);
+	return lines.join("\n");
+}
+/**
+* Register the study tools, the tutor persona (stable core + soul), and the
+* dynamic learner-snapshot context.
+* @param ctx - plugin context carrying the tool registry and system prompt.
+* @param config - validated plugin configuration.
+*/
+function apply(ctx, config) {
+	const statePath = resolveStatePath(config.statePath);
+	const fresh = !existsSync(statePath);
+	const state = loadState(statePath);
+	if (fresh) state.mode = config.mode;
+	const store = {
+		get: () => state,
+		save: () => saveState(statePath, state)
+	};
+	for (const tool of studyTools(store)) ctx.tools.register(tool);
+	ctx.systemPrompt.section({
+		name: "lookatstudy:tutor-core",
+		order: 120,
+		text: TUTOR_CORE
+	});
+	ctx.systemPrompt.section({
+		name: "lookatstudy:soul",
+		order: 121,
+		text: () => SOULS[store.get().mode]
+	});
+	ctx.systemPrompt.context({
+		name: "lookatstudy:learner-snapshot",
+		order: 50,
+		text: () => snapshotText(store)
+	});
+	ctx.inject(["webServer"], (webCtx) => {
+		const studyAreaPath = join(dirname(statePath), "study-area");
+		mkdirSync(studyAreaPath, { recursive: true });
+		const disposeDashboard = registerDashboard(webCtx.webServer, {
+			store,
+			studyAreaPath
+		});
+		webCtx.effect(() => disposeDashboard, "lookatstudy.dashboard()");
+	});
+}
+//#endregion
+export { Config, apply, inject, name };
+
+//# sourceMappingURL=index.mjs.map