dsh-plugin-lookatstudy 0.8.1 → 0.9.1

package/lib/index.mjs

@@ -18,7 +18,12 @@ const Config = z.object({
 		"guide",
 		"practice"
 	]).default("guide"),
-	statePath: z.string().default("")
+	statePath: z.string().default(""),
+	active: z.union([
+		"auto",
+		"on",
+		"off"
+	]).default("auto")
 });
 //#endregion
 //#region src/markdown.ts
@@ -207,7 +212,8 @@ function updateMastery(prev, correct, params = BKT_DEFAULTS) {
 	const pObs = pObsGivenL * pL + pObsGivenNotL * (1 - pL);
 	if (pObs === 0) return pL;
 	const pLGivenObs = pObsGivenL * pL / pObs;
-	return clamp01(pLGivenObs + pTransit * (1 - pLGivenObs));
+	const pLAfterTransit = pLGivenObs + pTransit * (1 - pLGivenObs);
+	return clamp01(pLAfterTransit);
 }
 /**
 * 把 mastery 概率映射成 crown level（1-5）给 UI 用。
@@ -237,11 +243,12 @@ 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. */
+/** Fresh empty state for a first run: dormant until the learner clicks 开始学习. */
 function emptyState() {
 	return {
 		version: 2,
 		courses: [],
+		active: false,
 		mode: "guide",
 		focus: null,
 		memoryGlobal: null,
@@ -258,7 +265,8 @@ function emptyState() {
 */
 function resolveStatePath(configured) {
 	if (configured !== "") return configured;
-	return join(process.env.DSH_HOME ?? join(homedir(), ".dsh"), "lookatstudy-plugin", "state.json");
+	const dshHome = process.env.DSH_HOME ?? join(homedir(), ".dsh");
+	return join(dshHome, "lookatstudy-plugin", "state.json");
 }
 /**
 * Load persisted state; a missing file yields empty state, a corrupt file fails loud.
@@ -301,6 +309,7 @@ function loadState(path) {
 	return {
 		version: 2,
 		courses,
+		active: raw.active ?? true,
 		mode: raw.mode ?? "guide",
 		focus: raw.focus ?? null,
 		memoryGlobal: raw.memoryGlobal ?? null,
@@ -1053,6 +1062,7 @@ function workbenchState(state, now) {
 	}
 	const due = dueReviews(state, void 0, now);
 	return {
+		active: state.active,
 		mode: state.mode,
 		courses,
 		focusLessonId: focusId,
@@ -1147,6 +1157,25 @@ function registerDashboard(webServer, deps) {
 				sendJson(res, 200, workbenchState(deps.store.get(), /* @__PURE__ */ new Date()));
 				return;
 			}
+			if (req.method === "POST" && pathname === "/lookatstudy/api/active") {
+				const body = await readJsonBodySafe(req, res);
+				if (body === void 0) return;
+				if (typeof body.active !== "boolean") {
+					sendJson(res, 400, {
+						ok: false,
+						error: "active (boolean) required"
+					});
+					return;
+				}
+				deps.store.get().active = body.active;
+				deps.store.save();
+				deps.onActiveChange(body.active);
+				sendJson(res, 200, {
+					ok: true,
+					active: body.active
+				});
+				return;
+			}
 			if (req.method === "POST" && pathname === "/lookatstudy/api/focus") {
 				const body = await readJsonBodySafe(req, res);
 				if (body === void 0) return;
@@ -1419,7 +1448,7 @@ const IMAGE_EXT_MIME = {
 	heic: "image/heic"
 };
 /** 排除的目录(非教学内容) */
-const EXCLUDED_DIRS = new Set([
+const EXCLUDED_DIRS = /* @__PURE__ */ new Set([
 	"node_modules",
 	".git",
 	".svn",
@@ -1522,7 +1551,8 @@ async function scanFolder(rootDir, onProgress, options) {
 	let count = 0;
 	for (const f of docFiles) {
 		onProgress?.(++count, f.relPath);
-		const kind = EXT_KIND[f.relPath.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? ""];
+		const ext = f.relPath.toLowerCase().match(/\.([^.]+)$/)?.[1] ?? "";
+		const kind = EXT_KIND[ext];
 		if (!kind) continue;
 		try {
 			const content = await readFileWithKind(f.absPath, kind);
@@ -1830,156 +1860,7 @@ function naturalPathCompare(a, b) {
 	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(/^\//, "")}`;
@@ -2143,244 +2024,6 @@ function detectRepoPattern(readmeMd) {
 		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 = [];
@@ -2411,20 +2054,35 @@ function pathsToDiscoveredFiles(paths) {
 	}
 	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 = {}) {
+	if (opts.signal?.aborted) return Promise.resolve({
+		ok: false,
+		error: "aborted"
+	});
 	return new Promise((resolve) => {
+		let settled = false;
+		const done = (r) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(deadline);
+			opts.signal?.removeEventListener("abort", onAbort);
+			resolve(r);
+		};
+		const onAbort = () => {
+			req.destroy();
+			done({
+				ok: false,
+				error: "aborted"
+			});
+		};
+		opts.signal?.addEventListener("abort", onAbort, { once: true });
+		const deadline = setTimeout(() => {
+			req.destroy();
+			done({
+				ok: false,
+				error: "deadline"
+			});
+		}, opts.deadlineMs ?? 25e3);
 		const req = https.get(url, {
 			headers: {
 				"User-Agent": "lookatstudy-import",
@@ -2437,29 +2095,38 @@ function httpsGet(url, opts = {}) {
 			res.on("data", (d) => {
 				body += d.toString();
 			});
-			res.on("end", () => resolve({
+			res.on("end", () => done({
 				ok: res.statusCode === 200,
 				status: res.statusCode,
 				body
 			}));
+			res.on("error", (e) => done({
+				ok: false,
+				status: res.statusCode,
+				error: e.message
+			}));
 		});
-		req.on("error", (e) => resolve({
+		req.on("error", (e) => done({
 			ok: false,
 			error: e.message
 		}));
 		req.on("timeout", () => {
 			req.destroy();
-			resolve({
+			done({
 				ok: false,
 				error: "timeout"
 			});
 		});
 	});
 }
-async function fetchRepoFileTree(owner, repo, branch, _fetchFn) {
+async function fetchRepoFileTree(owner, repo, branch, _fetchFn, signal) {
 	const apiUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
 	try {
-		const r = await httpsGet(apiUrl, { rejectUnauthorized: false });
+		const r = await httpsGet(apiUrl, {
+			rejectUnauthorized: false,
+			deadlineMs: 24e4,
+			signal
+		});
 		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);
@@ -2471,6 +2138,22 @@ async function fetchRepoFileTree(owner, repo, branch, _fetchFn) {
 	} catch (e) {
 		console.error(`[import] GitHub Tree API 异常: ${e instanceof Error ? e.message : e}`);
 	}
+	try {
+		const r2 = await httpsGet(`https://data.jsdelivr.com/v1/packages/gh/${owner}/${repo}@${branch}?structure=flat`, {
+			rejectUnauthorized: false,
+			signal
+		});
+		if (r2.ok && r2.body) {
+			const paths = (JSON.parse(r2.body).files ?? []).map((f) => f.name);
+			if (paths.length > 0) {
+				console.error(`[import] jsdelivr data API 全树: ${paths.length} 文件(Tree API 降级)`);
+				return {
+					paths,
+					source: "jsdelivr-list"
+				};
+			}
+		}
+	} catch {}
 	return {
 		paths: [],
 		source: "none"
@@ -2479,95 +2162,512 @@ async function fetchRepoFileTree(owner, repo, branch, _fetchFn) {
 /** 文件数上限（防爆，和 IPC handler 一致） */
 const MAX_FILES = 500;
 /**
-* 从 GitHub 仓库构建课程结构 —— 纯编排函数。
-*
-* 流程: fetch README → detectRepoPattern → 发现文件树 → fetchMarkdownContents
-*       → classifyFile（在 buildCourseFromFiles 内）→ buildCourseFromFiles
+* Step 1: 拉取仓库清单 —— README 全文 + 完整目录树 + 课程文件列表。
 *
-* 不落库、不发进度事件（onProgress 回调只传消息字符串，由调用方决定怎么用）。
+* 三样东西:
+*   1. README 全文 → 给 LLM 看课程大纲
+*   2. 完整目录树(所有路径) → 给 LLM 看仓库结构(translations/、images/、lab/ 等)
+*   3. 课程文件列表(filterLessonFiles 过滤后) → 供 Step 3+5 拉正文用
 *
-* @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) {
+async function fetchRepoInventory(owner, repo, branch, fetchFn, onProgress, signal) {
 	const send = (msg) => onProgress?.(msg);
 	send("正在拉取 README…");
-	const branches = branch === "master" ? ["master", "main"] : ["main", "master"];
+	const branches = branch === "master" ? [
+		"master",
+		"main",
+		"develop",
+		"gh-pages"
+	] : branch === "main" ? [
+		"main",
+		"master",
+		"develop",
+		"gh-pages"
+	] : [
+		branch,
+		"main",
+		"master"
+	];
+	const readmeCandidates = [
+		"README.md",
+		"readme.md",
+		"README.MD",
+		"README.rst",
+		"README.adoc",
+		"index.md",
+		"home.md",
+		"SUMMARY.md"
+	];
 	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(", ")}）`);
+	outer: for (const br of branches) for (const candidate of readmeCandidates) {
+		if (signal?.aborted) throw new Error("导入已取消");
+		try {
+			const r = await fetchFn(cdnUrl(owner, repo, br, candidate));
+			if (r.ok) {
+				readmeMd = await r.text();
+				readmeBranch = br;
+				break outer;
+			}
+		} catch {}
+	}
+	if (!readmeMd) throw new Error(`无法拉取 README（试过分支: ${branches.join(", ")}，文件名: ${readmeCandidates.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);
+	let fileList = filterLessonFiles(detection.lessonFiles ?? []);
+	send(`README 链接发现 ${fileList.length} 个课程文件`);
+	let fullTree = fileList.map((f) => f.path);
+	try {
+		send("扫描仓库完整目录结构…");
+		const tree = await fetchRepoFileTree(owner, repo, readmeBranch, fetchFn, signal);
 		if (tree.paths.length > 0) {
+			fullTree = tree.paths;
 			const treeLessonFiles = filterLessonFiles(pathsToDiscoveredFiles(tree.paths)).filter((f) => f.kind !== "other");
-			if (treeLessonFiles.length > lessonFiles.length) {
-				lessonFiles = treeLessonFiles;
-				send(`文件树发现 ${lessonFiles.length} 个课时文件（来源: ${tree.source}）`);
+			const existing = new Set(fileList.map((f) => f.path));
+			const added = treeLessonFiles.filter((f) => !existing.has(f.path));
+			if (added.length > 0) {
+				fileList = [...fileList, ...added];
+				send(`文件树补充 ${added.length} 个，共 ${fileList.length} 个课程文件`);
 			}
+			send(`目录树: ${fullTree.length} 个文件/目录`);
 		}
 	} catch {
-		send("文件树拉取失败，使用 README 链接发现");
+		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 (signal?.aborted) throw new Error("导入已取消");
+	if (fileList.length === 0) throw new Error(`未找到课程文件（README 无链接且文件树无可识别的文档/代码文件）`);
+	if (fileList.length > MAX_FILES) {
+		send(`文件数 ${fileList.length} 超过上限 ${MAX_FILES}，截断`);
+		fileList = fileList.slice(0, MAX_FILES);
+	}
+	return {
+		readmeMd,
+		fileList,
+		fullTree,
+		branch: readmeBranch,
+		detection
+	};
+}
+/**
+* Step 3: 批量提取文件的标题大纲（H1/H2/H3 + 每段字符数，不含正文）。
+* 拉取完整文件文本（不只前 N 行），因为字符数统计需要全文。
+* 并发度 5，同 fetchMarkdownContents。
+*/
+async function fetchFileOutlines(filePaths, owner, repo, branch, fetchFn, onProgress, signal) {
+	const result = /* @__PURE__ */ new Map();
+	const CONCURRENCY = 5;
+	for (let i = 0; i < filePaths.length; i += CONCURRENCY) {
+		if (signal?.aborted) throw new Error("导入已取消");
+		const batch = filePaths.slice(i, i + CONCURRENCY);
+		const results = await Promise.allSettled(batch.map(async (filePath) => {
+			const r = await fetchFn(cdnUrl(owner, repo, branch, filePath));
+			if (!r.ok) return null;
+			return {
+				path: filePath,
+				outline: extractOutlineWithCharCounts(await r.text(), filePath)
+			};
+		}));
+		for (let j = 0; j < results.length; j++) {
+			const res = results[j];
+			if (res.status === "fulfilled" && res.value) result.set(res.value.path, res.value.outline);
+			onProgress?.(i + j + 1, filePaths.length, batch[j] ?? "");
+		}
 	}
-	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);
+	return result;
+}
+/**
+* 从 markdown 文本提取 H1/H2/H3 标题 + 每段字符数。
+* 字符数 = 该标题行到下一个同级或更高级标题之间的字符数。
+* H2 边界：下一个 H1/H2；H3 边界：下一个 H1/H2/H3。
+* 代码块内的 # 不算标题。
+*/
+function extractOutlineWithCharCounts(text, filePath) {
+	const lines = text.split(/\r?\n/);
+	const totalChars = text.length;
+	let h1 = "";
+	const rawHeadings = [];
+	let inCodeFence = false;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (/^(\s*)(```|~~~)/.test(line)) {
+			inCodeFence = !inCodeFence;
+			continue;
+		}
+		if (inCodeFence) continue;
+		const h1Match = line.match(/^#\s+(.+)$/);
+		if (h1Match) {
+			if (!h1) h1 = h1Match[1].trim();
+			rawHeadings.push({
+				level: 1,
+				title: h1Match[1].trim(),
+				line: i
+			});
+			continue;
+		}
+		const h2Match = line.match(/^##\s+(.+)$/);
+		if (h2Match) {
+			rawHeadings.push({
+				level: 2,
+				title: h2Match[1].trim(),
+				line: i
+			});
+			continue;
+		}
+		const h3Match = line.match(/^###\s+(.+)$/);
+		if (h3Match) {
+			rawHeadings.push({
+				level: 3,
+				title: h3Match[1].trim(),
+				line: i
+			});
+			continue;
+		}
 	}
-	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} 章节，构建课程…`);
+	const headings = [];
+	for (let idx = 0; idx < rawHeadings.length; idx++) {
+		const h = rawHeadings[idx];
+		if (h.level === 1) continue;
+		let endLine = lines.length;
+		for (let j = idx + 1; j < rawHeadings.length; j++) if (rawHeadings[j].level <= h.level) {
+			endLine = rawHeadings[j].line;
+			break;
+		}
+		const sectionText = lines.slice(h.line, endLine).join("\n");
+		headings.push({
+			level: h.level,
+			title: h.title,
+			chars: sectionText.length
+		});
+	}
+	if (!h1 && filePath.endsWith(".ipynb")) h1 = filePath.split("/").pop()?.replace(/\.ipynb$/i, "") ?? filePath;
 	return {
-		course,
-		detection,
-		fetchedFiles: fetchResult.ok,
-		readmeBranch,
-		readmeMd
+		h1: h1 || (filePath.split("/").pop() ?? filePath),
+		totalChars,
+		headings
+	};
+}
+/**
+* 拉取单个文件的完整正文（Step 5a 用）。
+* 复用 fetchMarkdownContents 的解析逻辑（.ipynb → parseNotebook, .rst → rst-parser 等），
+* 但只拉一个文件，不做批量。
+*/
+async function fetchSingleFileContent(filePath, owner, repo, branch, fetchFn) {
+	try {
+		const r = await fetchFn(cdnUrl(owner, repo, branch, filePath));
+		if (!r.ok) return null;
+		const lower = filePath.toLowerCase();
+		if (lower.endsWith(".ipynb")) {
+			const { parseNotebook } = await import("./notebook-parser-ChbZBIKJ.mjs");
+			return parseNotebook(await r.text()).markdown;
+		}
+		const text = await r.text();
+		if (lower.endsWith(".rst")) {
+			const { parseRst } = await import("./rst-parser-CV93w3Sq.mjs");
+			return parseRst(text).markdown;
+		}
+		if (lower.endsWith(".rmd")) {
+			const { parseRmd } = await import("./rmd-parser-EgaMaffn.mjs");
+			return parseRmd(text).markdown;
+		}
+		if (lower.endsWith(".org")) {
+			const { parseOrg } = await import("./org-parser-BT5yvx9h.mjs");
+			return parseOrg(text).markdown;
+		}
+		if (lower.endsWith(".adoc")) {
+			const { parseAdoc } = await import("./adoc-parser-1UxcYHid.mjs");
+			return parseAdoc(text).markdown;
+		}
+		if (CODE_EXTENSIONS.some((ext) => lower.endsWith(ext))) {
+			const ext = lower.split(".").pop() ?? "";
+			const { parseCode } = await import("./code-parser-BOOk9IWV.mjs");
+			return parseCode(text, ext).markdown;
+		}
+		return text;
+	} catch {
+		return null;
+	}
+}
+/**
+* Build the pending design from Step 1 (inventory) + Step 3 (outlines).
+* @param url - the GitHub URL the learner asked to import.
+* @param owner - repo owner.
+* @param repo - repo name.
+* @param inventory - fetchRepoInventory output (README, file list, tree).
+* @param outlines - fetchFileOutlines output, keyed by path.
+* @returns the pending design the brief renders from.
+*/
+function buildPendingDesign(url, owner, repo, inventory, outlines) {
+	const files = [];
+	for (const discovered of inventory.fileList) {
+		const outline = outlines.get(discovered.path);
+		if (outline === void 0) continue;
+		files.push({
+			path: discovered.path,
+			role: discovered.kind === "ipynb" ? "practice" : "original",
+			outline
+		});
+	}
+	const courseTitle = inventory.readmeMd.match(/^#\s+(.+)$/m)?.[1]?.trim() || repo;
+	return {
+		source: "github",
+		url,
+		owner,
+		repo,
+		branch: inventory.branch,
+		courseTitle,
+		readmeExcerpt: inventory.readmeMd.slice(0, 4e3),
+		files,
+		fullTreeCount: inventory.fullTree.length
+	};
+}
+/**
+* Build the pending design from a local folder scan — the same brief, but the
+* bodies ride along (localContents), so apply is fully offline.
+* @param path - the absolute folder path (becomes sourceRef).
+* @param title - fallback course title (the folder's name).
+* @param docs - scanFolder output (relative paths + content).
+* @returns the pending design.
+*/
+function buildPendingDesignFromFolder(path, title, docs) {
+	const files = docs.map((doc) => ({
+		path: doc.path,
+		role: doc.kind === "ipynb" ? "practice" : "original",
+		outline: extractOutlineWithCharCounts(doc.content, doc.path)
+	}));
+	const readme = docs.find((doc) => /^readme\.md$/i.test(doc.path.split("/").pop() ?? ""))?.content ?? "";
+	const courseTitle = readme.match(/^#\s+(.+)$/m)?.[1]?.trim() || title;
+	const localContents = new Map(docs.map((doc) => [doc.path, doc.content]));
+	return {
+		source: "folder",
+		url: path,
+		owner: "",
+		repo: title,
+		branch: "local",
+		courseTitle,
+		readmeExcerpt: readme.slice(0, 4e3),
+		files,
+		fullTreeCount: docs.length,
+		localContents
+	};
+}
+/**
+* Render the design brief — the ONLY channel into the tutor's context
+* (dsh models see tool results through output.render alone). Carries the
+* upstream design rules: study/practice/attached classification, the
+* 3000-8000 chars lesson pacing, sub-1000 merging, attached absorption, and
+* the strict JSON contract study_apply_design expects.
+* @param pending - the pending design to present.
+* @returns the full brief text.
+*/
+function renderDesignBrief(pending) {
+	const lines = [];
+	lines.push(`## Course design brief: ${pending.courseTitle}`);
+	lines.push(pending.source === "folder" ? `Folder import (${pending.fullTreeCount} files; ${pending.files.length} course files below).` : `Repo ${pending.owner}/${pending.repo}@${pending.branch} (${pending.fullTreeCount} paths in tree; ${pending.files.length} course files below).`);
+	lines.push("");
+	lines.push("### Repository README (first 4000 chars)");
+	lines.push(pending.readmeExcerpt.trim() === "" ? "(empty)" : pending.readmeExcerpt);
+	lines.push("");
+	lines.push("### Files (role hint · h1 · totalChars · H2/H3 outline with per-heading chars)");
+	for (const file of pending.files) {
+		lines.push(`- ${file.path} (role hint: ${file.role}, total ${file.outline.totalChars} chars, h1: ${file.outline.h1})`);
+		const headings = file.outline.headings.slice(0, 40);
+		for (const heading of headings) lines.push(`  ${"#".repeat(heading.level)} ${heading.title} [${heading.chars}]`);
+		if (file.outline.headings.length > headings.length) lines.push(`  (+${file.outline.headings.length - headings.length} more headings)`);
+	}
+	lines.push("");
+	lines.push("### Design rules (from the LookatStudy import pipeline)");
+	lines.push("Classify every lesson as exactly one of:");
+	lines.push("- **study**: explanation/theory/tutorial content — the learning-world spine, its own lesson.");
+	lines.push("- **practice**: Exercise / Lab / notebook — its own lesson.");
+	lines.push("- **attached** (NOT its own lesson): quiz links, Conclusion, Challenge, Review references. Do not drop them — let the previous study lesson's anchor range naturally include them (omit their heading from the lesson list).");
+	lines.push("Pacing by char counts (target 3000-8000 chars per lesson):");
+	lines.push("- file totalChars < 3000 → one whole-file study lesson, no anchor.");
+	lines.push("- an explanatory H2 (with its H3 children) under 8000 chars → one lesson, anchor = that H2's full title.");
+	lines.push("- an explanatory H2 over 8000 chars with H3s → split into one lesson per H3, anchor = each H3's full title.");
+	lines.push("- an explanatory H2 over 8000 chars without H3s → accept one long lesson.");
+	lines.push("- after splitting, merge any lesson under 1000 chars into the adjacent same-world lesson to avoid fragmentation.");
+	lines.push("Other rules:");
+	lines.push("- role hints are references, not verdicts — README tables usually mark real roles (Lesson link = study, Notebook/Lab = practice).");
+	lines.push("- if the directory layout is already clear (e.g. lessons/N-Topic/), keep its sections; do not over-reorganize.");
+	lines.push(`- anchor is the full heading text used to slice the body; omit it for whole-file lessons.${pending.files.length > 80 ? " This repo is large: design at file granularity (omit anchors, one lesson per file) to keep the JSON manageable." : ""}`);
+	lines.push("");
+	lines.push("Now design the course and call study_apply_design with:");
+	lines.push("{ \"sections\": [ { \"title\": \"...\", \"lessons\": [ { \"title\": \"...\", \"file\": \"<exact path from this brief>\", \"anchor\": \"<optional full heading text>\", \"world\": \"study\" | \"practice\" } ] } ] }");
+	lines.push("Use ONLY file paths that appear in this brief — anything else is dropped. Apply directly, then walk the learner through the course map.");
+	return lines.join("\n");
+}
+/**
+* Extract H2/H3 headings with line numbers; headings inside ``` / ~~~ fences
+* are body text (upstream import-pipeline.ts extractHeadings).
+* @param content - the file's markdown text.
+* @returns headings in document order.
+*/
+function extractHeadings(content) {
+	const lines = content.split(/\r?\n/);
+	const headings = [];
+	let inCodeFence = false;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (/^\s*(```|~~~)/.test(line)) {
+			inCodeFence = !inCodeFence;
+			continue;
+		}
+		if (inCodeFence) continue;
+		const h2 = line.match(/^##\s+(.+)$/);
+		if (h2) {
+			headings.push({
+				level: 2,
+				title: h2[1].trim(),
+				line: i
+			});
+			continue;
+		}
+		const h3 = line.match(/^###\s+(.+)$/);
+		if (h3) headings.push({
+			level: 3,
+			title: h3[1].trim(),
+			line: i
+		});
+	}
+	return headings;
+}
+/**
+* Locate an anchor among the file's headings by bidirectional substring
+* match (case-insensitive, leading #'s stripped) — upstream
+* import-pipeline.ts findTitleIndex.
+* @param headings - the file's headings.
+* @param anchor - the anchor text from the design.
+* @returns the heading index, or -1 when nothing matches.
+*/
+function findTitleIndex(headings, anchor) {
+	const anchorClean = anchor.replace(/^#{1,3}\s+/, "").toLowerCase().trim();
+	if (anchorClean === "") return -1;
+	for (let i = 0; i < headings.length; i++) {
+		const titleLower = headings[i].title.toLowerCase();
+		if (titleLower.includes(anchorClean) || anchorClean.includes(titleLower)) return i;
+	}
+	return -1;
+}
+/**
+* Slice one lesson's body out of a file (upstream import-pipeline.ts
+* extractSectionByIndex semantics, locked by upstream's
+* verify-section-extract suite):
+* - the file's FIRST lesson starts at line 0, absorbing the H1, preface
+*   prose, and any leading attached H2 (e.g. a pre-lecture quiz);
+* - an H2 anchor runs until the next H2/H1, swallowing its H3 subsections;
+* - an H3 anchor runs until the very next H2/H3/H1;
+* - no matching heading → the whole file.
+* @param content - the file's text.
+* @param headings - the file's headings.
+* @param titleIndex - findTitleIndex result, or -1 for whole-file.
+* @param isFirstOfFile - whether this is the first designed lesson of the file.
+* @returns the sliced, trimmed body.
+*/
+function sliceLessonBody(content, headings, titleIndex, isFirstOfFile) {
+	const lines = content.split(/\r?\n/);
+	if (titleIndex < 0) return content.trim();
+	const anchor = headings[titleIndex];
+	const startLine = isFirstOfFile ? 0 : anchor.line;
+	let endLine = lines.length;
+	for (let i = titleIndex + 1; i < headings.length; i++) if (headings[i].level <= anchor.level) {
+		endLine = headings[i].line;
+		break;
+	}
+	return lines.slice(startLine, endLine).join("\n").trim();
+}
+/**
+* Validate and clean the tutor's design JSON (upstream
+* parseStructureDesignResult rules): lessons pointing at files outside the
+* brief are dropped (anti-hallucination), worlds other than exactly
+* "practice" coerce to study, empty titles get a fallback, sections with no
+* surviving lessons are dropped.
+* @param design - the tutor's JSON (shape already enforced by the parameters schema).
+* @param validFiles - the pending design's file set.
+* @returns the cleaned design plus the dropped-lesson count.
+*/
+function validateDesign(design, validFiles) {
+	const sections = [];
+	let droppedLessons = 0;
+	for (const section of design.sections) {
+		const lessons = [];
+		for (const lesson of section.lessons ?? []) {
+			if (typeof lesson.file !== "string" || !validFiles.has(lesson.file)) {
+				droppedLessons++;
+				continue;
+			}
+			const anchor = typeof lesson.anchor === "string" && lesson.anchor.trim() !== "" ? lesson.anchor : null;
+			lessons.push({
+				title: typeof lesson.title === "string" && lesson.title.trim() !== "" ? lesson.title.trim() : "Untitled lesson",
+				file: lesson.file,
+				anchor,
+				world: lesson.world === "practice" ? "practice" : "study"
+			});
+		}
+		if (lessons.length > 0) sections.push({
+			title: typeof section.title === "string" && section.title.trim() !== "" ? section.title.trim() : "Untitled section",
+			lessons
+		});
+	}
+	if (sections.reduce((n, s) => n + s.lessons.length, 0) === 0) throw new Error(`lookatstudy-plugin: design produced 0 usable lessons (dropped ${droppedLessons} — every lesson's file must come from the design brief; call study_import_github again to re-read it)`);
+	return {
+		sections,
+		droppedLessons
+	};
+}
+/** GitHub-style anchor slug for ParsedLesson/ParsedSection anchors. */
+function slugAnchor(title) {
+	const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return slug === "" ? "section" : slug;
+}
+/**
+* Assemble the final ParsedCourse from a validated design and the fetched
+* file contents: per-file heading extraction + anchor slicing with the
+* first-lesson-absorbs-the-header rule, practice worlds per lesson, and
+* all-practice sections marked so importCourse skips their exam nodes.
+* @param courseTitle - title from the brief.
+* @param validated - validateDesign output.
+* @param contents - fetched body text per designed file (missing key = loud failure).
+* @returns the parsed course ready for importCourse.
+*/
+function buildCourseFromDesign(courseTitle, validated, contents) {
+	const headingsCache = /* @__PURE__ */ new Map();
+	const headingsOf = (file) => {
+		const cached = headingsCache.get(file);
+		if (cached === void 0) {
+			const extracted = extractHeadings(contents.get(file) ?? "");
+			headingsCache.set(file, extracted);
+			return extracted;
+		}
+		return cached;
+	};
+	const firstLessonSeen = /* @__PURE__ */ new Set();
+	return {
+		title: courseTitle,
+		sections: validated.sections.map((section) => {
+			const lessons = section.lessons.map((lesson) => {
+				const content = contents.get(lesson.file);
+				if (content === void 0) throw new Error(`lookatstudy-plugin: no fetched content for designed file ${JSON.stringify(lesson.file)} — fetch failed earlier; retry study_apply_design`);
+				const headings = headingsOf(lesson.file);
+				const titleIndex = lesson.anchor === null ? -1 : findTitleIndex(headings, lesson.anchor);
+				const isFirst = !firstLessonSeen.has(lesson.file);
+				firstLessonSeen.add(lesson.file);
+				return {
+					title: lesson.title,
+					anchor: slugAnchor(lesson.title),
+					body: sliceLessonBody(content, headings, titleIndex, isFirst),
+					sourceFilePath: lesson.file,
+					world: lesson.world
+				};
+			});
+			return {
+				title: section.title,
+				anchor: slugAnchor(section.title),
+				world: lessons.every((l) => l.world === "practice") ? "practice" : "study",
+				lessons
+			};
+		})
 	};
 }
 //#endregion
@@ -2596,6 +2696,18 @@ function importLines(value) {
 	return lines;
 }
 /**
+* Display lines for the design-required branch of a GitHub import.
+* @param value - the design_required branch value.
+* @returns card lines.
+*/
+function designBriefLines(value) {
+	return [
+		`📐 Designing: ${value.courseTitle}`,
+		`${value.repo}@${value.branch} · ${value.fileCount} course files · ${value.fullTreeCount} paths in tree`,
+		"The tutor designs the structure, then study_apply_design imports it"
+	];
+}
+/**
 * Display lines for the skill-tree map.
 * @param value - map tool value.
 * @returns card lines.
@@ -2809,9 +2921,9 @@ function parseGithubUrl(url) {
 		repo: match[2]
 	};
 }
-/** Wrap `fetch` so cancellation of the tool call aborts in-flight repo fetches. */
-function signalFetch(signal) {
-	return (input, init) => fetch(input, {
+/** Wrap a fetch transport so cancellation of the tool call aborts in-flight repo fetches. */
+function signalFetch(signal, baseFetch) {
+	return (input, init) => baseFetch(input, {
 		...init,
 		signal
 	});
@@ -2824,9 +2936,18 @@ const textBlocks = (lines) => (lines ?? []).map((text) => ({
 /**
 * Build the full study tool set over one store.
 * @param store - state store owned by `apply`.
+* @param deps - test seams (fetch stub); production leaves it default.
 * @returns tool definitions ready for `ctx.tools.register`.
 */
-function studyTools(store) {
+function studyTools(store, deps = {}) {
+	const baseFetch = deps.fetch ?? fetch;
+	/**
+	* The pending course design between study_import_github (design_required)
+	* and study_apply_design. Memory-only on purpose: it is cheap to re-fetch
+	* and state.json should not carry bulk inventories; a later import
+	* replaces an unconsumed one.
+	*/
+	let pendingDesign = null;
 	/** Run a mutating state operation and persist. */
 	const mutate = (fn) => {
 		const result = fn(store.get());
@@ -2870,44 +2991,123 @@ function studyTools(store) {
 			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."
-				}
+	const importMarkdown = 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."
 			},
-			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}).`
-				}]
+			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
+	});
+	/** Shared output for the two design-protocol import tools: already imported, or a brief is pending. */
+	const designOrImportedOutput = { schema: { oneOf: [{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			status: {
+				type: "string",
+				enum: ["imported"],
+				required: true
 			},
-			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")));
+			courseId: {
+				type: "string",
+				required: true
 			},
-			presentCall: (args) => ({
-				card: "generic",
-				title: `Import markdown course${args.title === void 0 ? "" : `: ${args.title}`}`,
-				kind: "read"
-			}),
-			...importPresent
-		}),
+			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
+			}
+		}
+	}, {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			status: {
+				type: "string",
+				enum: ["design_required"],
+				required: true
+			},
+			repo: {
+				type: "string",
+				required: true
+			},
+			branch: {
+				type: "string",
+				required: true
+			},
+			courseTitle: {
+				type: "string",
+				required: true
+			},
+			fileCount: {
+				type: "integer",
+				required: true
+			},
+			fullTreeCount: {
+				type: "integer",
+				required: true
+			}
+		}
+	}] } };
+	/** Shared render: the brief rides the design_required branch; imported stays the old summary. */
+	const designOrImportedRender = (_args, value) => [{
+		type: "text",
+		text: value.status === "design_required" ? pendingDesign === null ? "Course design required — the brief is no longer pending; call the import tool again to re-fetch it." : renderDesignBrief(pendingDesign) : `Imported course “${value.title}” (${value.sections} sections, ${value.lessons} lessons). First lesson: “${value.firstLessonTitle}” (id ${value.firstLessonId}).`
+	}];
+	const designOrImportedPresent = {
+		presentationMeta: (_args, value) => value.status === "design_required" ? designBriefLines(value) : importLines(value),
+		presentResult: (_args, result) => ({
+			card: "generic",
+			content: textBlocks(result.meta)
+		})
+	};
+	return [
+		importMarkdown,
 		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.",
+			description: "Start importing a local folder: scans markdown, txt, html, Jupyter notebooks, rst/Rmd/org/adoc, and 30+ code file types (PDF/PPTX unsupported), then returns a design brief — the TUTOR designs the course structure from it and applies the result with study_apply_design (fully offline). Re-importing an already-imported path returns the existing course directly.",
 			parameters: {
 				path: {
 					type: "string",
@@ -2916,26 +3116,32 @@ function studyTools(store) {
 				},
 				title: {
 					type: "string",
-					description: "Optional course title overriding the folder name."
+					description: "Optional course title overriding the folder name / README H1."
 				}
 			},
 			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}).`
-				}]
+				...designOrImportedOutput,
+				render: designOrImportedRender
 			},
 			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)));
+				const existing = store.get().courses.find((c) => c.source === "folder" && c.sourceRef === args.path);
+				if (existing !== void 0) return {
+					status: "imported",
+					...toImportValue(existing)
+				};
+				const docs = await scanFolder(args.path);
+				if (docs.length === 0) throw new Error(`lookatstudy-plugin: no importable files found in ${args.path}`);
+				const title = args.title ?? basename(args.path.replaceAll("\\", "/"));
+				pendingDesign = buildPendingDesignFromFolder(args.path, title, docs);
+				return {
+					status: "design_required",
+					repo: pendingDesign.repo,
+					branch: pendingDesign.branch,
+					courseTitle: pendingDesign.courseTitle,
+					fileCount: pendingDesign.files.length,
+					fullTreeCount: pendingDesign.fullTreeCount
+				};
 			},
 			timeoutMs: 6e4,
 			presentCall: (args) => ({
@@ -2944,11 +3150,11 @@ function studyTools(store) {
 				kind: "read",
 				rawInput: args.path
 			}),
-			...importPresent
+			...designOrImportedPresent
 		}),
 		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.",
+			description: "Start importing a GitHub learning repository: fetches the README outline and every course file's heading outline (with char counts) through the jsDelivr CDN, then returns a design brief — the TUTOR designs the course structure (sections/lessons/anchors/worlds) from it and applies the result with study_apply_design. Re-importing an already-imported URL returns the existing course directly. Awesome-lists are rejected.",
 			parameters: {
 				url: {
 					type: "string",
@@ -2961,17 +3167,30 @@ function studyTools(store) {
 				}
 			},
 			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}).`
-				}]
+				...designOrImportedOutput,
+				render: designOrImportedRender
 			},
 			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)));
+				const branch = args.branch ?? "main";
+				const fetchFn = signalFetch(exec.signal, baseFetch);
+				const existing = store.get().courses.find((c) => c.source === "github" && c.sourceRef === args.url);
+				if (existing !== void 0) return {
+					status: "imported",
+					...toImportValue(existing)
+				};
+				const inventory = await fetchRepoInventory(owner, repo, branch, fetchFn, void 0, exec.signal);
+				const outlines = await fetchFileOutlines(inventory.fileList.map((f) => f.path), owner, repo, inventory.branch, fetchFn, void 0, exec.signal);
+				pendingDesign = buildPendingDesign(args.url, owner, repo, inventory, outlines);
+				if (pendingDesign.files.length === 0) throw new Error("lookatstudy-plugin: course files were discovered but no outlines could be fetched (CDN unreachable?)");
+				return {
+					status: "design_required",
+					repo: `${owner}/${repo}`,
+					branch: pendingDesign.branch,
+					courseTitle: pendingDesign.courseTitle,
+					fileCount: pendingDesign.files.length,
+					fullTreeCount: pendingDesign.fullTreeCount
+				};
 			},
 			timeoutMs: 18e4,
 			presentCall: (args) => ({
@@ -2979,7 +3198,139 @@ function studyTools(store) {
 				title: `Import GitHub course: ${args.url}`,
 				kind: "fetch"
 			}),
-			...importPresent
+			...designOrImportedPresent
+		}),
+		defineTool({
+			name: "study_apply_design",
+			description: "Apply the tutor-designed course structure to the pending import (the one study_import_github or study_import_folder returned design_required for). Every lesson's file must come from the design brief — unknown paths are dropped (anti-hallucination); lesson bodies are sliced by their anchor heading and the course is imported. On a validation or fetch error the tutor fixes the design and simply calls again.",
+			parameters: { sections: {
+				type: "array",
+				required: true,
+				description: "Designed sections in learning order.",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						title: {
+							type: "string",
+							required: true,
+							description: "Section title (in the learner's language)."
+						},
+						lessons: {
+							type: "array",
+							required: true,
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									title: {
+										type: "string",
+										required: true,
+										description: "Lesson title."
+									},
+									file: {
+										type: "string",
+										required: true,
+										description: "Exact file path from the design brief."
+									},
+									anchor: {
+										type: "string",
+										description: "Full H2/H3 heading text the lesson body starts at; omit for whole-file lessons."
+									},
+									world: {
+										type: "string",
+										description: "\"study\" (explanation) or \"practice\" (exercise/lab/notebook); anything else is treated as study."
+									}
+								}
+							}
+						}
+					}
+				}
+			} },
+			output: {
+				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
+						},
+						droppedLessons: {
+							type: "integer",
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `Imported designed course “${value.title}” (${value.sections} sections, ${value.lessons} lessons${value.droppedLessons > 0 ? `, ${value.droppedLessons} hallucinated lesson(s) dropped` : ""}). First lesson: “${value.firstLessonTitle}” (id ${value.firstLessonId}). Present the course map to the learner.`
+				}]
+			},
+			async execute(args, exec) {
+				const pd = pendingDesign;
+				if (pd === null) throw new Error("lookatstudy-plugin: no pending course design — call study_import_github or study_import_folder first (a dsh restart also clears it)");
+				const validated = validateDesign(args, new Set(pd.files.map((f) => f.path)));
+				const uniqueFiles = [...new Set(validated.sections.flatMap((s) => s.lessons.map((l) => l.file)))];
+				const contents = /* @__PURE__ */ new Map();
+				if (pd.localContents !== void 0) for (const file of uniqueFiles) {
+					const text = pd.localContents.get(file);
+					if (text === void 0) throw new Error(`lookatstudy-plugin: designed file ${JSON.stringify(file)} is not in the scanned folder — use only paths from the design brief`);
+					contents.set(file, text);
+				}
+				else {
+					const failed = [];
+					const fetchFn = signalFetch(exec.signal, baseFetch);
+					for (let i = 0; i < uniqueFiles.length; i += 5) {
+						if (exec.signal.aborted) throw new Error("lookatstudy-plugin: import aborted");
+						const batch = uniqueFiles.slice(i, i + 5);
+						const texts = await Promise.all(batch.map((f) => fetchSingleFileContent(f, pd.owner, pd.repo, pd.branch, fetchFn)));
+						for (let j = 0; j < batch.length; j++) if (texts[j] === null) failed.push(batch[j]);
+						else contents.set(batch[j], texts[j]);
+					}
+					if (contents.size === 0) throw new Error(`lookatstudy-plugin: every designed file failed to fetch (${failed.length}) — the CDN path is unreachable; retry or re-import`);
+					if (failed.length > 0) throw new Error(`lookatstudy-plugin: ${failed.length} designed file(s) failed to fetch: ${failed.join(", ")} — drop or fix them and call study_apply_design again`);
+				}
+				const parsed = buildCourseFromDesign(pd.courseTitle, validated, contents);
+				requireParsedLessons(parsed);
+				const value = mutate((state) => toImportValue(importCourse(state, parsed, pd.source, pd.url)));
+				pendingDesign = null;
+				return {
+					...value,
+					droppedLessons: validated.droppedLessons
+				};
+			},
+			timeoutMs: 18e4,
+			presentCall: () => ({
+				card: "generic",
+				title: "Apply course design",
+				kind: "edit"
+			}),
+			presentationMeta: (_args, value) => [...importLines(value), ...value.droppedLessons > 0 ? [`${value.droppedLessons} dropped (files outside the brief)`] : []],
+			presentResult: (_args, result) => ({
+				card: "generic",
+				content: textBlocks(result.meta)
+			})
 		}),
 		defineTool({
 			name: "study_courses",
@@ -4303,17 +4654,7 @@ function studyTools(store) {
 	];
 }
 //#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"];
+//#region src/surface.ts
 /**
 * Stable tutor core (ported from LookatStudy's BASE_AGENT_PROMPT plus its
 * tool contract). Deliberately static so the prefix hits the provider's
@@ -4326,6 +4667,9 @@ You are the learner's AI study tutor for a course imported via the study tools.
 ### 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.
 
+### Language
+Answer in the learner's own language (the language of their interface and their messages), including quiz stems, options, and explanations. Quote course material verbatim in its original language.
+
 ### 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.
 
@@ -4347,6 +4691,9 @@ When the learner says "我不懂 / 不太理解" without specifics, ask which co
 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.
 
+### Course import design
+When study_import_github or study_import_folder returns status "design_required", it renders a design brief (files with heading outlines and per-heading char counts). Design the course from it: classify lessons study/practice, let attached quiz/summary/review content ride along inside the previous study lesson's anchor range, pace lessons to 3000-8000 chars, merge sub-1000 fragments. Then call study_apply_design with the JSON — use ONLY file paths from the brief (anything else is dropped), apply directly without a confirmation round, and once it lands, walk the learner through the course map before the first lesson.
+
 ### 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.
 
@@ -4377,13 +4724,23 @@ const SOULS = {
 4. 一个问题走完,要求他复盘:哪步用了哪个概念、重来会怎么改。复盘比答对更重要。
 5. 主动串联:把当前问题和已学概念织成网,让他看到知识点在真实任务里怎么协作。`
 };
+/** The dormant gate: an inactive surface renders no persona text at all. */
+function tutorCoreText(state) {
+	return state.active ? TUTOR_CORE : "";
+}
+/** The active soul under the same gate (inactive renders empty). */
+function soulText(state) {
+	return state.active ? SOULS[state.mode] : "";
+}
 /**
 * 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.
+* recent friction, memory slots, due count, pending proposal. Dormant
+* surfaces render nothing.
 */
-function snapshotText(store) {
-	const snap = learnerSnapshot(store.get(), /* @__PURE__ */ new Date());
+function snapshotSectionText(state) {
+	if (!state.active) return "";
+	const snap = learnerSnapshot(state, /* @__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}%`})`);
@@ -4401,8 +4758,51 @@ function snapshotText(store) {
 	return lines.join("\n");
 }
 /**
-* Register the study tools, the tutor persona (stable core + soul), and the
-* dynamic learner-snapshot context.
+* Create the activation-gated tool surface: `sync()` registers all study
+* tools when active and disposes them when not; it is idempotent per state,
+* so callers may fire it on every activation flip.
+* @param registry - the host tool registry (`ctx.tools`).
+* @param store - the live learning-state store.
+*/
+function createStudySurface(registry, store) {
+	const disposers = [];
+	let surfaceOn = false;
+	const unregisterAll = () => {
+		for (const dispose of disposers.splice(0)) dispose();
+	};
+	return {
+		sync() {
+			const want = store.get().active;
+			if (want === surfaceOn) return;
+			surfaceOn = want;
+			if (want) for (const tool of studyTools(store)) disposers.push(registry.register(tool));
+			else unregisterAll();
+		},
+		dispose() {
+			surfaceOn = false;
+			unregisterAll();
+		}
+	};
+}
+//#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 — all activation-gated: dormant installs expose none of it until
+* the learner clicks 开始学习. Learning state persists in one JSON file
+* shared across sessions.
+* @module dsh-plugin-lookatstudy
+*/
+const name = "lookatstudy-plugin";
+const inject = ["tools", "systemPrompt"];
+/**
+* Register the activation-gated study surface: the 20 `study_*` tools (kept
+* unregistered while dormant), the tutor persona (stable core + soul), and
+* the dynamic learner-snapshot context — every prompt text renders empty
+* while inactive, and empty sections are dropped at assembly.
 * @param ctx - plugin context carrying the tool registry and system prompt.
 * @param config - validated plugin configuration.
 */
@@ -4411,37 +4811,39 @@ function apply(ctx, config) {
 	const fresh = !existsSync(statePath);
 	const state = loadState(statePath);
 	if (fresh) state.mode = config.mode;
+	if (config.active !== "auto") state.active = config.active === "on";
 	const store = {
 		get: () => state,
 		save: () => saveState(statePath, state)
 	};
-	for (const tool of studyTools(store)) ctx.tools.register(tool);
+	const surface = createStudySurface(ctx.tools, store);
+	surface.sync();
+	ctx.effect(() => () => surface.dispose(), "lookatstudy.studySurface()");
 	ctx.systemPrompt.section({
 		name: "lookatstudy:tutor-core",
 		order: 120,
-		text: TUTOR_CORE
+		text: () => tutorCoreText(store.get())
 	});
 	ctx.systemPrompt.section({
 		name: "lookatstudy:soul",
 		order: 121,
-		text: () => SOULS[store.get().mode]
+		text: () => soulText(store.get())
 	});
 	ctx.systemPrompt.context({
 		name: "lookatstudy:learner-snapshot",
 		order: 50,
-		text: () => snapshotText(store)
+		text: () => snapshotSectionText(store.get())
 	});
 	ctx.inject(["webServer"], (webCtx) => {
 		const studyAreaPath = join(dirname(statePath), "study-area");
 		mkdirSync(studyAreaPath, { recursive: true });
 		const disposeDashboard = registerDashboard(webCtx.webServer, {
 			store,
-			studyAreaPath
+			studyAreaPath,
+			onActiveChange: surface.sync
 		});
 		webCtx.effect(() => disposeDashboard, "lookatstudy.dashboard()");
 	});
 }
 //#endregion
 export { Config, apply, inject, name };
-
-//# sourceMappingURL=index.mjs.map