dsh-plugin-lookatstudy 0.14.1 → 0.16.0

package/lib/index.mjs

@@ -625,6 +625,7 @@ function emptyState() {
 		focus: null,
 		memoryGlobal: null,
 		memoryPatterns: {},
+		artifacts: {},
 		proposals: [],
 		lessonSessions: {},
 		lastConsolidatedAt: null,
@@ -700,6 +701,7 @@ function loadState(path) {
 		memoryPatterns: raw.memoryPatterns ?? {},
 		proposals: raw.proposals ?? [],
 		lessonSessions: raw.lessonSessions ?? {},
+		artifacts: raw.artifacts ?? {},
 		lastConsolidatedAt: raw.lastConsolidatedAt ?? null,
 		xp: raw.xp ?? {
 			total: 0,
@@ -822,6 +824,7 @@ function deleteCourse(state, 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}:`));
+	for (const lessonId of Object.keys(state.artifacts)) if (lessonId.startsWith(`${courseId}:`)) delete state.artifacts[lessonId];
 }
 /**
 * Locate a course; unknown ids fail loud.
@@ -1188,6 +1191,28 @@ function addNote(state, lessonId, zone, title, text, source, quote, now) {
 * @param noteId - id of the note to remove.
 * @throws when the lesson or the note id is unknown (fail loud, like every id lookup).
 */
+/**
+* Record one artifact on its lesson, idempotently: the key is the content
+* hash (type + stable-stringified data) — re-importing or re-generating the
+* same artifact returns the existing row instead of duplicating it (upstream
+* learned this the hard way with message-id keys).
+* @returns the stored artifact and whether this call created it.
+*/
+function recordArtifact(state, lessonId, artifact) {
+	findLesson(state, lessonId);
+	const existing = state.artifacts[lessonId] ?? [];
+	const hit = existing.find((a) => a.hash === artifact.hash);
+	if (hit !== void 0) return {
+		artifact: hit,
+		created: false
+	};
+	const next = [...existing, artifact];
+	state.artifacts[lessonId] = next;
+	return {
+		artifact,
+		created: true
+	};
+}
 function deleteNote(state, lessonId, noteId) {
 	const ref = findLesson(state, lessonId);
 	const index = ref.lesson.notes.findIndex((n) => n.id === noteId);
@@ -1621,6 +1646,13 @@ function workbenchState(state, now) {
 			masteryPct: ref.lesson.mastery === null ? null : Math.round(ref.lesson.mastery * 100),
 			strategy: strategyBand(ref.lesson.mastery),
 			concepts: conceptViews(ref.lesson) ?? [],
+			due: dueIds.has(ref.lesson.id),
+			artifacts: (state.artifacts[ref.lesson.id] ?? []).map((a) => ({
+				id: a.id,
+				artifactType: a.artifactType,
+				title: a.title,
+				data: a.data
+			})),
 			starters: starterPrompts(ref.lesson.title).map((s) => ({
 				label: s.label,
 				message: s.message
@@ -1858,6 +1890,60 @@ function registerDashboard(webServer, deps) {
 				}
 				return;
 			}
+			if (req.method === "POST" && pathname === "/lookatstudy/api/note/user") {
+				const body = await readJsonBodySafe(req, res);
+				if (body === void 0) return;
+				if (typeof body.lessonId !== "string" || typeof body.quote !== "string" || body.quote.trim().length < 2) {
+					sendJson(res, 400, {
+						ok: false,
+						error: "lessonId and quote (a real selection) required"
+					});
+					return;
+				}
+				try {
+					const quote = body.quote.trim();
+					const text = typeof body.text === "string" && body.text.trim() !== "" ? body.text.trim() : quote;
+					const note = addNote(deps.store.get(), body.lessonId, "record", quote.slice(0, 24), text, "content", quote, /* @__PURE__ */ new Date());
+					deps.store.save();
+					sendJson(res, 200, {
+						ok: true,
+						noteId: note.id
+					});
+				} catch (error) {
+					sendJson(res, 404, {
+						ok: false,
+						error: error instanceof Error ? error.message : String(error)
+					});
+				}
+				return;
+			}
+			if (req.method === "POST" && pathname === "/lookatstudy/api/review") {
+				const body = await readJsonBodySafe(req, res);
+				if (body === void 0) return;
+				const quality = body.quality;
+				if (typeof body.lessonId !== "string" || typeof quality !== "number" || ![
+					1,
+					4,
+					5
+				].includes(quality)) {
+					sendJson(res, 400, {
+						ok: false,
+						error: "lessonId and quality (1 | 4 | 5) required"
+					});
+					return;
+				}
+				try {
+					recordReview(deps.store.get(), body.lessonId, quality, /* @__PURE__ */ new Date());
+					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;
@@ -1944,8 +2030,8 @@ const ZH = {
 	"col.tutor": "导师",
 	"col.bb": "黑板",
 	"pane.rail": "课程",
-	"pane.tutor": "导师",
-	"pane.bb": "黑板",
+	"pane.chat": "对话",
+	"pane.note": "黑板",
 	"viewtab.teach": "讲解",
 	"viewtab.cmap": "概念图",
 	"viewtab.cmap.title": "本课概念之间的关系图",
@@ -1969,6 +2055,71 @@ const ZH = {
 	"rail.empty.placeholder": "GitHub 仓库链接,如 microsoft/AI-For-Beginners",
 	"rail.empty.button": "导入",
 	"composer.send": "发送",
+	"quiz.card.title": "练习",
+	"quiz.progress": "{cur}/{total}",
+	"quiz.next": "下一题",
+	"quiz.finish": "看成绩单",
+	"quiz.score": "成绩：{correct}/{total}",
+	"quiz.right": "答对了",
+	"quiz.wrong": "答错了",
+	"quiz.youChose": "你选了",
+	"quiz.answer": "正确答案",
+	"quiz.hook": "练习卡完成：{correct}/{total} 正确。请简短点评，针对错题讲讲思路。",
+	"quiz.action.explain-wrong": "讲讲错题",
+	"quiz.action.retry": "再来一组",
+	"quiz.action.go-deeper": "深入原理",
+	"quiz.action.mark-mastered": "标记我掌握了",
+	"quiz.action.markMastered.hint": "会让导师出综合题检验，通过即标记掌握",
+	"quiz.action.next-topic": "下一个知识点",
+	"artifact.lines": "第 {from}-{to} 行：",
+	"artifact.expand": "放大查看",
+	"artifact.guess.title": "猜一猜",
+	"artifact.guess.pick": "我选「{label}」",
+	"artifact.guess.wait": "已记下你的直觉——导师下回合揭晓，看看你想得对不对",
+	"artifact.sedimented": "有新的学习产物沉淀进笔记",
+	"zone.artifacts": "AI 产物",
+	"note.quote.ask": "提问这段",
+	"note.quote.save": "加到笔记",
+	"note.quote.template": "请讲解这段：「{text}」",
+	"note.saved": "已存入记录区笔记",
+	"review.rate.title": "复习自评——这课现在记得多牢？",
+	"review.again": "再来一次",
+	"review.remembered": "记住了",
+	"review.mastered": "完全掌握",
+	"review.done.good": "已安排下次复习",
+	"review.done.again": "明天再来一遍",
+	"review.jump": "点开这一课去复习",
+	"review.nudge": "有 {n} 课到了复习时间，先回来练一遍？",
+	"review.nudge.go": "去复习",
+	"rail.search.jump": "打开这一课",
+	"proposal.banner": "《{lesson}》可以提前毕业了",
+	"proposal.accept": "接受",
+	"proposal.decline": "再练练",
+	"proposal.accept.msg": "我接受《{lesson}》的掌握度提议，帮我标记为掌握。",
+	"proposal.decline.msg": "《{lesson}》我先再练练，暂不接受提前毕业。",
+	"tutor.thinking": "导师思考中…",
+	"header.xp": "经验值 {xp}",
+	"header.streak": "连续学习天数",
+	"header.level": "等级",
+	"map.node.locked": "锁定 — 先完成前面的课时",
+	"map.node.due": "到了复习时间",
+	"map.exam.locked": "考试未解锁 — 本章节全部课时掌握度 ≥50% 后开放",
+	"companion.poke": "戳一戳伴学伙伴",
+	"companion.poked": "伴学伙伴向你眨了眨眼",
+	"companion.form.ember": "小焰",
+	"companion.form.frost": "霜绒",
+	"companion.form.moss": "苔芽",
+	"companion.form.star": "星尘",
+	"companion.form.ink": "墨墨",
+	"settings.companion": "伴学伙伴",
+	"settings.companion.hint": "选择学习面板右下角的伴学生物形态。",
+	"quiz.msg.explain-wrong": "我刚才有题答错了，帮我讲讲为什么错、正确的思路是什么。",
+	"quiz.msg.retry": "再来一组类似的题巩固一下。",
+	"quiz.msg.go-deeper": "这组我答得不错，帮我深入讲讲背后的原理和容易混淆的地方。",
+	"quiz.msg.mark-mastered": "这课我觉得掌握了，帮我确认一下——出个综合题检验，通过了就标记为掌握。",
+	"quiz.msg.next-topic": "进入下一个知识点。",
+	"toast.region": "通知",
+	"toast.close": "关闭",
 	"composer.busy": "导师正在回复…",
 	"rail.empty.demo": "导入示例课程",
 	"rail.mastered": "毕业 {mastered}/{total} 课",
@@ -4247,6 +4398,196 @@ function completeLines(value) {
 	return lines;
 }
 //#endregion
+//#region src/artifacts.ts
+/**
+* The artifact channel — the upstream artifacts system port (0.15.0 P1):
+* tools that produce display-worthy learning objects return them tagged with
+* an `artifactType` (quiz / guess / compare_table / code_walkthrough /
+* concept_map / diagram), the state records them idempotently per lesson
+* (upstream's canvas_items equivalent — content-hashed, because the lesson
+* there was burned by message-id keys duplicating saves), and the panel
+* renders them as interactive cards. Host-side pure logic + node:crypto.
+* @module dsh-plugin-lookatstudy/artifacts
+*/
+/** Deterministic stringify (sorted object keys at every depth). */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "null";
+}
+/** Short stable content hash (the dedup key — never a message id). */
+function contentHash(text) {
+	return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+const MAX_QUESTIONS = 20;
+/**
+* Sanitize a tutor-produced quiz: coerce strings, drop structurally invalid
+* questions (collecting a warning each), fail loud when nothing usable
+* remains. Mirrors upstream sanitizeArtifact('quiz') intent — the card never
+* renders a question it cannot judge.
+*/
+function sanitizeQuiz(raw) {
+	const warnings = [];
+	const input = raw ?? {};
+	const title = typeof input.title === "string" && input.title.trim() !== "" ? input.title.trim() : "练习";
+	const questions = [];
+	const list = Array.isArray(input.questions) ? input.questions : [];
+	list.slice(0, MAX_QUESTIONS).forEach((q, index) => {
+		const item = q ?? {};
+		const prompt = typeof item.prompt === "string" ? item.prompt.trim() : "";
+		const options = Array.isArray(item.options) ? item.options.map((o) => typeof o === "string" ? o.trim() : "").filter((o) => o !== "") : [];
+		const answer = typeof item.answer === "number" && Number.isInteger(item.answer) ? item.answer : -1;
+		const explanation = typeof item.explanation === "string" ? item.explanation.trim() : "";
+		if (prompt === "") {
+			warnings.push(`question ${index + 1}: empty prompt dropped`);
+			return;
+		}
+		if (options.length < 2) {
+			warnings.push(`question ${index + 1}: fewer than 2 usable options dropped`);
+			return;
+		}
+		if (answer < 0 || answer >= options.length) {
+			warnings.push(`question ${index + 1}: answer index out of range dropped`);
+			return;
+		}
+		questions.push({
+			prompt,
+			options,
+			answer,
+			explanation
+		});
+	});
+	if (questions.length === 0) throw new Error(`lookatstudy-plugin: quiz artifact has no usable questions${warnings.length > 0 ? ` (${warnings.join("; ")})` : ""}`);
+	if (list.length > MAX_QUESTIONS) warnings.push(`truncated to ${MAX_QUESTIONS} questions`);
+	const data = {
+		artifactType: "quiz",
+		title,
+		questions
+	};
+	if (warnings.length > 0) data.warnings = warnings;
+	return {
+		data,
+		warnings
+	};
+}
+/** The artifact id derived from type + content (stable across re-imports). */
+function artifactId(artifactType, data) {
+	return `${artifactType}-${contentHash(stableStringify(data))}`;
+}
+/** Coerce one string field, dropping empty. */
+function str(value) {
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+/** Sanitize a guess (the opening two-option hook; unscored, revealed next turn). */
+function sanitizeGuess(raw) {
+	const warnings = [];
+	const input = raw ?? {};
+	const prompt = str(input.prompt);
+	if (prompt === null) throw new Error("lookatstudy-plugin: guess artifact needs a prompt");
+	const list = Array.isArray(input.options) ? input.options : [];
+	const options = [];
+	list.slice(0, 2).forEach((o, index) => {
+		const item = o ?? {};
+		const id = str(item.id) ?? String.fromCharCode(97 + index);
+		const label = str(item.label);
+		if (label === null) {
+			warnings.push(`option ${index + 1}: empty label dropped`);
+			return;
+		}
+		options.push({
+			id,
+			label
+		});
+	});
+	if (options.length !== 2) throw new Error(`lookatstudy-plugin: guess artifact needs exactly 2 options (${warnings.join("; ")})`);
+	return {
+		data: {
+			artifactType: "guess",
+			prompt,
+			options
+		},
+		warnings
+	};
+}
+/** Sanitize a compare table (headers ≥2; every row matches the header width). */
+function sanitizeCompareTable(raw) {
+	const warnings = [];
+	const input = raw ?? {};
+	const title = str(input.title) ?? "对比";
+	const headers = (Array.isArray(input.headers) ? input.headers : []).map((h) => str(h)).filter((h) => h !== null);
+	if (headers.length < 2) throw new Error("lookatstudy-plugin: compare_table needs at least 2 headers");
+	const rows = [];
+	for (const row of Array.isArray(input.rows) ? input.rows : []) {
+		const cells = (Array.isArray(row) ? row : []).map((c) => typeof c === "string" ? c.trim() : "");
+		if (cells.length === headers.length) rows.push(cells);
+		else warnings.push(`row dropped (${cells.length} cells ≠ ${headers.length} headers)`);
+	}
+	if (rows.length === 0) throw new Error(`lookatstudy-plugin: compare_table has no usable rows (${warnings.join("; ")})`);
+	return {
+		data: {
+			artifactType: "compare_table",
+			title,
+			headers,
+			rows
+		},
+		warnings
+	};
+}
+/** Sanitize a mermaid diagram (type + non-empty code). */
+function sanitizeDiagram(raw) {
+	const input = raw ?? {};
+	const title = str(input.title) ?? "图示";
+	const diagramType = input.diagramType === "sequence" || input.diagramType === "state" ? input.diagramType : "flowchart";
+	const mermaid = str(input.mermaid);
+	if (mermaid === null) throw new Error("lookatstudy-plugin: diagram artifact needs mermaid code");
+	return {
+		data: {
+			artifactType: "diagram",
+			title,
+			diagramType,
+			mermaid
+		},
+		warnings: []
+	};
+}
+/** Sanitize a code walkthrough (annotations reference real 1-based line ranges). */
+function sanitizeCodeWalkthrough(raw) {
+	const warnings = [];
+	const input = raw ?? {};
+	const title = str(input.title) ?? "代码讲解";
+	const language = str(input.language) ?? "text";
+	const code = str(input.code);
+	if (code === null) throw new Error("lookatstudy-plugin: code_walkthrough artifact needs code");
+	const lineCount = code.split("\n").length;
+	const annotations = [];
+	for (const a of Array.isArray(input.annotations) ? input.annotations : []) {
+		const item = a ?? {};
+		const note = str(item.note);
+		const lineStart = typeof item.lineStart === "number" && Number.isInteger(item.lineStart) ? item.lineStart : -1;
+		const lineEnd = typeof item.lineEnd === "number" && Number.isInteger(item.lineEnd) ? item.lineEnd : lineStart;
+		if (note === null || lineStart < 1 || lineEnd < lineStart || lineEnd > lineCount) {
+			warnings.push(`annotation dropped (line ${String(lineStart)}-${String(lineEnd)} of ${String(lineCount)})`);
+			continue;
+		}
+		annotations.push({
+			lineStart,
+			lineEnd,
+			note
+		});
+	}
+	if (annotations.length === 0) throw new Error(`lookatstudy-plugin: code_walkthrough has no usable annotations (${warnings.join("; ")})`);
+	return {
+		data: {
+			artifactType: "code_walkthrough",
+			title,
+			language,
+			code,
+			annotations
+		},
+		warnings
+	};
+}
+//#endregion
 //#region src/tools.ts
 /**
 * The `study_*` tool surface, ported from LookatStudy's agent contract:
@@ -6407,211 +6748,555 @@ function studyTools(store, deps = {}) {
 			title: `Translate lesson: ${args.lessonId} → ${args.lang}`
 		})
 	});
-	return [
-		importMarkdown,
-		importFolder,
-		importGithub,
-		importUrl,
-		applyDesign,
-		listCourses,
-		courseMap,
-		lessonContent,
-		recordAnswerTool,
-		examResultTool,
-		completeLessonTool,
-		dueReviewsTool,
-		recordReviewTool,
-		deleteCourseTool,
-		defineConceptsTool,
-		proposeMasteryTool,
-		resolveProposalTool,
-		reportFrictionTool,
-		rememberTool,
-		defineTool({
-			name: "study_consolidate",
-			description: "Gather the consolidation window — friction entries and practice notes recorded since the last consolidation — and advance the watermark. You are the consolidation function (upstream runs an LLM call; here the tutor IS it): distill the window into 0–3 durable memory writes via study_remember (global style / per-course pattern / lesson-specific gaps), then tell the learner in one short line what you took away. Call when a session accumulates friction or after heavy quizzing — not every turn.",
-			parameters: {},
-			output: {
-				schema: {
-					type: "object",
-					additionalProperties: false,
-					properties: {
-						since: {
-							...nullableString,
-							required: true
-						},
-						entries: {
-							type: "array",
-							required: true,
-							items: {
-								type: "object",
-								additionalProperties: false,
-								properties: {
-									lessonId: {
-										type: "string",
-										required: true
-									},
-									lessonTitle: {
-										type: "string",
-										required: true
-									},
-									kind: {
-										type: "string",
-										required: true,
-										enum: ["friction", "practice"]
-									},
-									category: { type: "string" },
-									text: {
-										type: "string",
-										required: true
-									},
-									at: {
-										type: "string",
-										required: true
-									}
-								}
-							}
-						},
-						counts: {
+	const consolidateTool = defineTool({
+		name: "study_consolidate",
+		description: "Gather the consolidation window — friction entries and practice notes recorded since the last consolidation — and advance the watermark. You are the consolidation function (upstream runs an LLM call; here the tutor IS it): distill the window into 0–3 durable memory writes via study_remember (global style / per-course pattern / lesson-specific gaps), then tell the learner in one short line what you took away. Call when a session accumulates friction or after heavy quizzing — not every turn.",
+		parameters: {},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					since: {
+						...nullableString,
+						required: true
+					},
+					entries: {
+						type: "array",
+						required: true,
+						items: {
 							type: "object",
-							required: true,
 							additionalProperties: false,
 							properties: {
-								friction: {
-									type: "integer",
+								lessonId: {
+									type: "string",
 									required: true
 								},
-								practice: {
-									type: "integer",
+								lessonTitle: {
+									type: "string",
+									required: true
+								},
+								kind: {
+									type: "string",
+									required: true,
+									enum: ["friction", "practice"]
+								},
+								category: { type: "string" },
+								text: {
+									type: "string",
+									required: true
+								},
+								at: {
+									type: "string",
 									required: true
 								}
 							}
-						},
-						watermark: {
-							type: "string",
-							required: true
 						}
-					}
-				},
-				render: (_args, value) => [{
-					type: "text",
-					text: `Consolidation window since ${value.since ?? "(beginning)"}: ${value.counts.friction} friction, ${value.counts.practice} practice entries.` + (value.entries.length === 0 ? " Nothing to distill — tell the learner their memory is up to date." : " Distill these into 0–3 study_remember writes (global / pattern / lesson), then summarize in one line.")
-				}]
-			},
-			execute() {
-				return mutate((state) => {
-					const window = gatherConsolidationWindow(state);
-					const watermark = (/* @__PURE__ */ new Date()).toISOString();
-					state.lastConsolidatedAt = watermark;
-					return {
-						since: window.since,
-						entries: window.entries,
-						counts: window.counts,
-						watermark
-					};
-				});
-			},
-			presentCall: () => ({
-				card: "generic",
-				title: "Consolidate learner memory"
-			})
-		}),
-		translateLessonTool,
-		defineTool({
-			name: "study_export",
-			description: "Export one course as a single markdown learning pack (upstream pack-export, zero-LLM): sections and lesson bodies verbatim. The receiver imports it anywhere through study_import_markdown — same plugin, fresh machine, no network. Present the pack to the learner (a copyable block) or save it into the study workspace when they ask for a file.",
-			parameters: { courseId: {
-				type: "string",
-				required: true,
-				description: "Course id to export."
-			} },
-			output: {
-				schema: {
-					type: "object",
-					additionalProperties: false,
-					properties: {
-						courseId: {
-							type: "string",
-							required: true
-						},
-						title: {
-							type: "string",
-							required: true
-						},
-						lessonCount: {
-							type: "integer",
-							required: true
-						},
-						chars: {
-							type: "integer",
-							required: true
-						},
-						markdown: {
-							type: "string",
-							required: true
+					},
+					counts: {
+						type: "object",
+						required: true,
+						additionalProperties: false,
+						properties: {
+							friction: {
+								type: "integer",
+								required: true
+							},
+							practice: {
+								type: "integer",
+								required: true
+							}
 						}
+					},
+					watermark: {
+						type: "string",
+						required: true
 					}
-				},
-				render: (_args, value) => [{
-					type: "text",
-					text: `Course pack “${value.title}” — ${value.lessonCount} lessons, ${value.chars} chars. Give the learner the markdown below (copyable); importing it goes through study_import_markdown.
-
-` + value.markdown
-				}]
+				}
 			},
-			execute(args) {
-				const course = findCourse(store.get(), args.courseId);
-				const markdown = courseToPackMarkdown(course);
-				const lessonCount = course.sections.reduce((n, sec) => n + sec.lessons.filter((l) => l.kind !== "exam").length, 0);
+			render: (_args, value) => [{
+				type: "text",
+				text: `Consolidation window since ${value.since ?? "(beginning)"}: ${value.counts.friction} friction, ${value.counts.practice} practice entries.` + (value.entries.length === 0 ? " Nothing to distill — tell the learner their memory is up to date." : " Distill these into 0–3 study_remember writes (global / pattern / lesson), then summarize in one line.")
+			}]
+		},
+		execute() {
+			return mutate((state) => {
+				const window = gatherConsolidationWindow(state);
+				const watermark = (/* @__PURE__ */ new Date()).toISOString();
+				state.lastConsolidatedAt = watermark;
 				return {
-					courseId: course.id,
-					title: course.title,
-					lessonCount,
-					chars: markdown.length,
-					markdown
+					since: window.since,
+					entries: window.entries,
+					counts: window.counts,
+					watermark
 				};
-			},
-			isConcurrencySafe: () => true,
-			presentCall: (args) => ({
-				card: "generic",
-				title: `Export course: ${args.courseId}`,
-				kind: "read"
-			})
-		}),
-		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",
+			});
+		},
+		presentCall: () => ({
+			card: "generic",
+			title: "Consolidate learner memory"
+		})
+	});
+	const exportTool = defineTool({
+		name: "study_export",
+		description: "Export one course as a single markdown learning pack (upstream pack-export, zero-LLM): sections and lesson bodies verbatim. The receiver imports it anywhere through study_import_markdown — same plugin, fresh machine, no network. Present the pack to the learner (a copyable block) or save it into the study workspace when they ask for a file.",
+		parameters: { courseId: {
+			type: "string",
+			required: true,
+			description: "Course id to export."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					courseId: {
+						type: "string",
+						required: true
+					},
+					title: {
+						type: "string",
+						required: true
+					},
+					lessonCount: {
+						type: "integer",
+						required: true
+					},
+					chars: {
+						type: "integer",
+						required: true
+					},
+					markdown: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `Course pack “${value.title}” — ${value.lessonCount} lessons, ${value.chars} chars. Give the learner the markdown below (copyable); importing it goes through study_import_markdown.
+
+` + value.markdown
+			}]
+		},
+		execute(args) {
+			const course = findCourse(store.get(), args.courseId);
+			const markdown = courseToPackMarkdown(course);
+			const lessonCount = course.sections.reduce((n, sec) => n + sec.lessons.filter((l) => l.kind !== "exam").length, 0);
+			return {
+				courseId: course.id,
+				title: course.title,
+				lessonCount,
+				chars: markdown.length,
+				markdown
+			};
+		},
+		isConcurrencySafe: () => true,
+		presentCall: (args) => ({
+			card: "generic",
+			title: `Export course: ${args.courseId}`,
+			kind: "read"
+		})
+	});
+	const noteSaveTool = 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}`
+		})
+	});
+	const notesTool = 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"
+		})
+	});
+	const setModeTool = 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}`
+		})
+	});
+	const generateQuizTool = defineTool({
+		name: "study_generate_quiz",
+		description: "Generate an interactive practice card (quiz artifact) for the focus lesson: 3-4 questions (5 max), each with 2-6 options, the 0-based correct `answer` index, and an `explanation` of why it is right. The learner answers on the card itself (locally judged, progress kept); when they finish, a summary hook arrives in the conversation — acknowledge it, address wrong answers, do NOT re-grade these through study_record_answer. Use for practice blocks and review consolidation; single conversational questions stay as prose A-D options.",
+		parameters: {
+			lessonId: {
+				type: "string",
+				required: true,
+				description: "Lesson the practice card belongs to."
+			},
+			title: {
+				type: "string",
+				description: "Card title (defaults to 练习)."
+			},
+			questions: {
+				type: "array",
+				required: true,
+				description: "The questions, in answering order.",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						prompt: {
+							type: "string",
+							required: true
+						},
+						options: {
+							type: "array",
+							required: true,
+							items: { type: "string" }
+						},
+						answer: {
+							type: "integer",
+							required: true,
+							description: "0-based index into options."
+						},
+						explanation: {
+							type: "string",
+							required: true,
+							description: "Why the right answer is right."
+						}
+					}
+				}
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					artifactType: {
+						type: "string",
+						required: true,
+						enum: ["quiz"]
+					},
+					artifactId: {
+						type: "string",
+						required: true
+					},
+					created: {
+						type: "boolean",
+						required: true
+					},
+					title: {
+						type: "string",
+						required: true
+					},
+					questions: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								prompt: {
+									type: "string",
+									required: true
+								},
+								options: {
+									type: "array",
+									required: true,
+									items: { type: "string" }
+								},
+								answer: {
+									type: "integer",
+									required: true
+								},
+								explanation: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					warnings: {
+						type: "array",
+						items: { type: "string" }
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `Practice card (${value.questions.length} questions): ${value.title}${value.created ? "" : " (already recorded)"}${value.warnings === void 0 || value.warnings.length === 0 ? "" : ` — warnings: ${value.warnings.join("; ")}`}`
+			}]
+		},
+		async execute(args) {
+			const sanitized = sanitizeQuiz(args);
+			return mutate((state) => {
+				const id = artifactId("quiz", sanitized.data);
+				const artifact = {
+					id,
+					artifactType: "quiz",
+					title: typeof sanitized.data.title === "string" ? sanitized.data.title : "练习",
+					createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+					hash: id.slice(5),
+					data: sanitized.data
+				};
+				const result = recordArtifact(state, args.lessonId, artifact);
+				return {
+					artifactType: "quiz",
+					artifactId: result.artifact.id,
+					created: result.created,
+					title: result.artifact.title,
+					questions: result.artifact.data.questions ?? [],
+					warnings: result.artifact.data.warnings ?? []
+				};
+			});
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `Generate practice card: ${typeof args.title === "string" ? args.title : "练习"} (${args.questions?.length ?? 0} questions)`
+		})
+	});
+	/** Record one sanitized artifact on its lesson (shared by the artifact tools). */
+	const recordSanitized = (lessonId, result, type) => mutate((state) => {
+		const id = artifactId(type, result.data);
+		const stored = recordArtifact(state, lessonId, {
+			id,
+			artifactType: type,
+			title: typeof result.data.title === "string" ? result.data.title : type,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			hash: id.slice(type.length + 1),
+			data: result.data
+		});
+		return {
+			artifactType: type,
+			artifactId: stored.artifact.id,
+			created: stored.created,
+			...stored.artifact.data
+		};
+	});
+	return [
+		importMarkdown,
+		importFolder,
+		importGithub,
+		importUrl,
+		applyDesign,
+		listCourses,
+		courseMap,
+		lessonContent,
+		recordAnswerTool,
+		examResultTool,
+		completeLessonTool,
+		dueReviewsTool,
+		recordReviewTool,
+		deleteCourseTool,
+		defineConceptsTool,
+		proposeMasteryTool,
+		resolveProposalTool,
+		reportFrictionTool,
+		rememberTool,
+		consolidateTool,
+		translateLessonTool,
+		exportTool,
+		noteSaveTool,
+		notesTool,
+		generateQuizTool,
+		defineTool({
+			name: "study_pose_guess",
+			description: "Pose the opening two-option guess (the curiosity hook): one or two sentences of prose first (counter-intuitive, everyday-related), then this tool with exactly 2 short options. The learner picks one; you reveal the answer NEXT turn and teach the lesson's core point. Iron rules: unscored, never touches mastery, never say 答对/答错 — this is a hook, not a quiz.",
+			parameters: {
+				lessonId: {
+					type: "string",
 					required: true,
-					enum: [...NOTE_SOURCES],
-					description: "ai (you generated) | content (quoted from lesson) | chat (quoted from conversation)."
+					description: "Lesson the guess belongs to."
 				},
-				quote: {
+				prompt: {
 					type: "string",
-					description: "Verbatim source quote, for record-zone notes."
+					required: true,
+					description: "e.g. 你觉得：递归算阶乘会比循环——更慢，还是差不多？"
+				},
+				options: {
+					type: "array",
+					required: true,
+					description: "Exactly 2 options.",
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							id: {
+								type: "string",
+								required: true
+							},
+							label: {
+								type: "string",
+								required: true
+							}
+						}
+					}
 				}
 			},
 			output: {
@@ -6619,156 +7304,331 @@ function studyTools(store, deps = {}) {
 					type: "object",
 					additionalProperties: false,
 					properties: {
-						noteId: {
+						artifactType: {
+							type: "string",
+							required: true,
+							enum: ["guess"]
+						},
+						artifactId: {
 							type: "string",
 							required: true
 						},
-						zone: {
+						created: {
+							type: "boolean",
+							required: true
+						},
+						prompt: {
 							type: "string",
 							required: true
+						},
+						options: {
+							type: "array",
+							required: true,
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									id: {
+										type: "string",
+										required: true
+									},
+									label: {
+										type: "string",
+										required: true
+									}
+								}
+							}
 						}
 					}
 				},
 				render: (_args, value) => [{
 					type: "text",
-					text: `Saved ${value.zone}-zone note ${value.noteId}.`
+					text: `Guess posed: ${value.prompt}`
 				}]
 			},
 			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
-					};
-				});
+				return recordSanitized(args.lessonId, sanitizeGuess(args), "guess");
 			},
 			presentCall: (args) => ({
 				card: "generic",
-				title: `Save ${args.zone} note: ${args.title}`
+				title: `Pose guess: ${typeof args.prompt === "string" ? args.prompt.slice(0, 40) : ""}`
 			})
 		}),
 		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)."
-			} },
+			name: "study_compare_table",
+			description: "Generate a compare table for two or more concepts/solutions/technologies — when the learner asks A 和 B 有什么区别 or a horizontal comparison helps. Rendered as a table artifact card.",
+			parameters: {
+				lessonId: {
+					type: "string",
+					required: true,
+					description: "Lesson the table belongs to."
+				},
+				title: {
+					type: "string",
+					required: true,
+					description: "e.g. SQL vs NoSQL"
+				},
+				headers: {
+					type: "array",
+					required: true,
+					items: { type: "string" },
+					description: "Column names (first is usually the dimension)."
+				},
+				rows: {
+					type: "array",
+					required: true,
+					items: {
+						type: "array",
+						items: { type: "string" }
+					},
+					description: "Rows; each row has headers.length cells."
+				}
+			},
 			output: {
 				schema: {
 					type: "object",
 					additionalProperties: false,
 					properties: {
-						total: {
-							type: "integer",
+						artifactType: {
+							type: "string",
+							required: true,
+							enum: ["compare_table"]
+						},
+						artifactId: {
+							type: "string",
+							required: true
+						},
+						created: {
+							type: "boolean",
+							required: true
+						},
+						title: {
+							type: "string",
 							required: true
 						},
-						notes: {
+						headers: {
+							type: "array",
+							required: true,
+							items: { type: "string" }
+						},
+						rows: {
 							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
-									}
-								}
+								type: "array",
+								items: { type: "string" }
 							}
+						},
+						warnings: {
+							type: "array",
+							items: { type: "string" }
 						}
 					}
 				},
 				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")
+					text: `Compare table: ${value.title} (${value.rows.length} rows)`
 				}]
 			},
 			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
-				};
+				return recordSanitized(args.lessonId, sanitizeCompareTable(args), "compare_table");
 			},
-			isConcurrencySafe: () => true,
-			presentCall: () => ({
+			presentCall: (args) => ({
 				card: "generic",
-				title: "Read notebook",
-				kind: "read"
+				title: `Compare table: ${typeof args.title === "string" ? args.title : ""}`
 			})
 		}),
 		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."
-			} },
+			name: "study_draw_diagram",
+			description: "Draw a structured mermaid diagram: steps/decisions/causality → flowchart TD (or LR for short chains); multi-party interactions → sequenceDiagram; states/transitions → stateDiagram-v2. Return valid mermaid syntax only (no outer fences). Rendered as a diagram artifact card.",
+			parameters: {
+				lessonId: {
+					type: "string",
+					required: true,
+					description: "Lesson the diagram belongs to."
+				},
+				title: {
+					type: "string",
+					required: true
+				},
+				diagramType: {
+					type: "string",
+					required: true,
+					enum: [
+						"flowchart",
+						"sequence",
+						"state"
+					]
+				},
+				mermaid: {
+					type: "string",
+					required: true,
+					description: "Mermaid code without fences."
+				}
+			},
 			output: {
 				schema: {
 					type: "object",
 					additionalProperties: false,
-					properties: { mode: {
-						type: "string",
-						required: true,
-						enum: [...MODES]
-					} }
+					properties: {
+						artifactType: {
+							type: "string",
+							required: true,
+							enum: ["diagram"]
+						},
+						artifactId: {
+							type: "string",
+							required: true
+						},
+						created: {
+							type: "boolean",
+							required: true
+						},
+						title: {
+							type: "string",
+							required: true
+						},
+						diagramType: {
+							type: "string",
+							required: true
+						},
+						mermaid: {
+							type: "string",
+							required: true
+						}
+					}
 				},
 				render: (_args, value) => [{
 					type: "text",
-					text: `Tutoring soul switched to ${value.mode} (effective next reply).`
+					text: `Diagram: ${value.title} (${value.diagramType})`
 				}]
 			},
 			async execute(args) {
-				return mutate((state) => {
-					state.mode = args.mode;
-					return { mode: state.mode };
-				});
+				return recordSanitized(args.lessonId, sanitizeDiagram(args), "diagram");
 			},
 			presentCall: (args) => ({
 				card: "generic",
-				title: `Switch soul: ${args.mode}`
+				title: `Draw diagram: ${typeof args.title === "string" ? args.title : ""}`
 			})
-		})
+		}),
+		defineTool({
+			name: "study_code_walkthrough",
+			description: "Walk through a piece of code line-by-line / segment-by-segment — when the learner asks what the code means or the lesson contains code needing teardown. Rendered with line numbers + per-segment notes.",
+			parameters: {
+				lessonId: {
+					type: "string",
+					required: true,
+					description: "Lesson the walkthrough belongs to."
+				},
+				title: {
+					type: "string",
+					required: true
+				},
+				language: {
+					type: "string",
+					required: true,
+					description: "e.g. typescript / python"
+				},
+				code: {
+					type: "string",
+					required: true
+				},
+				annotations: {
+					type: "array",
+					required: true,
+					description: "Per-segment notes.",
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							lineStart: {
+								type: "integer",
+								required: true
+							},
+							lineEnd: {
+								type: "integer",
+								required: true
+							},
+							note: {
+								type: "string",
+								required: true
+							}
+						}
+					}
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						artifactType: {
+							type: "string",
+							required: true,
+							enum: ["code_walkthrough"]
+						},
+						artifactId: {
+							type: "string",
+							required: true
+						},
+						created: {
+							type: "boolean",
+							required: true
+						},
+						title: {
+							type: "string",
+							required: true
+						},
+						language: {
+							type: "string",
+							required: true
+						},
+						code: {
+							type: "string",
+							required: true
+						},
+						annotations: {
+							type: "array",
+							required: true,
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									lineStart: {
+										type: "integer",
+										required: true
+									},
+									lineEnd: {
+										type: "integer",
+										required: true
+									},
+									note: {
+										type: "string",
+										required: true
+									}
+								}
+							}
+						},
+						warnings: {
+							type: "array",
+							items: { type: "string" }
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `Code walkthrough: ${value.title} (${value.annotations.length} segments)`
+				}]
+			},
+			async execute(args) {
+				return recordSanitized(args.lessonId, sanitizeCodeWalkthrough(args), "code_walkthrough");
+			},
+			presentCall: (args) => ({
+				card: "generic",
+				title: `Code walkthrough: ${typeof args.title === "string" ? args.title : ""}`
+			})
+		}),
+		setModeTool
 	];
 }
 //#endregion
@@ -6816,6 +7676,12 @@ Never reveal the friction log or mastery mechanics as "being watched" — the nu
 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.
+Artifact surfaces beyond the practice card (each renders as an interactive card and settles into the notebook):
+- Opening a brand-new lesson: study_pose_guess — one or two prose sentences of hook, then exactly 2 short options; reveal the answer next turn (unscored, never 答对/答错).
+- The learner asks A 和 B 有什么区别 or a comparison clarifies: study_compare_table.
+- Structure/flow/interaction/state needs a picture: study_draw_diagram (flowchart TD / sequenceDiagram / stateDiagram-v2 — valid mermaid only).
+- The lesson contains code needing teardown, or the learner asks what code means: study_code_walkthrough (line ranges + notes).
+Practice cards: for multi-question practice blocks (3-4 questions, review consolidation, learner asks to 练一练/出一组题), call study_generate_quiz — the learner answers on the interactive card (locally judged, progress kept). When the completion hook arrives ("练习卡完成：…"), acknowledge briefly and address wrong answers; do NOT re-grade card answers through study_record_answer. Single conversational questions stay as prose options.
 Quiz option FORMAT (the study panel parses this to make options clickable): each option on its own plain line, exactly "A. <text>", "B. <text>", "C. <text>", "D. <text>" — letters consecutive from A; never tables, never nested lists, never bold/code wrapping the letter.
 
 ### 【Answer formatting · preferences】