@novedu/cli 0.18.0 → 0.20.0

package/dist/main.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { Command } from "commander";
 import { readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
+import { globSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
 import { CryptoProvider, PublicClientApplication } from "@azure/msal-node";
 import { parse, stringify } from "yaml";
 import { z } from "zod";
-import { fileURLToPath, pathToFileURL } from "node:url";
 import Handlebars from "handlebars";
+import { fileURLToPath, pathToFileURL } from "node:url";
 //#region src/auth.ts
 const DEFAULT_TENANT_ID = "91fc072c-edef-4f97-bdc5-cfb67718ae3a";
 const DEFAULT_CLIENT_ID = "4d44fc4b-0434-4981-9765-62e2074ceecb";
@@ -226,18 +226,19 @@ function failJson(value) {
 * not abort the run).
 */
 async function performApiRequest(options) {
-	const fail = (value) => {
+	const fail = (value, extra = {}) => {
 		if (!options.quiet) failJson(value);
 		return {
 			ok: false,
-			error: value
+			error: value,
+			...extra
 		};
 	};
 	let token;
 	try {
 		token = await getAccessToken();
 	} catch (error) {
-		if (error instanceof NotSignedInError) return fail({ message: error.message });
+		if (error instanceof NotSignedInError) return fail({ message: error.message }, { authFailed: true });
 		throw error;
 	}
 	const server = resolveServerUrl(options.server);
@@ -260,7 +261,10 @@ async function performApiRequest(options) {
 	} catch {
 		payload = void 0;
 	}
-	if (!response.ok) return fail(payload ?? { message: `${server} rejected the request: HTTP ${response.status}` });
+	if (!response.ok) return fail(payload ?? { message: `${server} rejected the request: HTTP ${response.status}` }, {
+		status: response.status,
+		...response.status === 401 || response.status === 403 ? { authFailed: true } : {}
+	});
 	return {
 		ok: true,
 		payload
@@ -278,7 +282,11 @@ async function runApiRequest(options) {
 //#endregion
 //#region ../lib/llm/provider.ts
 const LLM_PROVIDERS = ["SCCH", "Azure Foundry"];
-const providerSchema = z.enum(LLM_PROVIDERS).default("SCCH").meta({ description: "The LLM provider serving the model. For Azure Foundry, model is the deployment name." });
+const DEFAULT_PROVIDER = "SCCH";
+const providerSchema = z.enum(LLM_PROVIDERS).default(DEFAULT_PROVIDER).meta({ description: "The LLM provider serving the model. For Azure Foundry, model is the deployment name." });
+function parseLenientProvider(value) {
+	return value === "SCCH" || value === "Azure Foundry" ? value : void 0;
+}
 //#endregion
 //#region ../lib/registry-schema.ts
 /** The fixed group names and the code module each one mints for. */
@@ -872,205 +880,182 @@ function registerCodes(program) {
 	});
 }
 //#endregion
-//#region src/commands/files.ts
-const SERVER_OPTION$2 = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
-async function readStdin() {
-	const chunks = [];
-	for await (const chunk of process.stdin) chunks.push(chunk);
-	return Buffer.concat(chunks).toString("utf8");
+//#region ../lib/quiz-verdict-schema.ts
+const QUIZ_VERDICT_SCHEMA = z.object({
+	result: z.enum([
+		"correct",
+		"partial",
+		"incorrect"
+	]),
+	feedback: z.string()
+});
+const QUIZ_VERDICT_ENUM = QUIZ_VERDICT_SCHEMA.shape.result;
+//#endregion
+//#region ../lib/eval-schema.ts
+/** The three verdicts in canonical order (best → worst); the sort key for expected sets. */
+const EVAL_VERDICTS = QUIZ_VERDICT_ENUM.options;
+/**
+* Eval ids share the flat namespace of report headers and `--out` files, so they stay
+* URL- and YAML-plain: an alphanumeric start, then alphanumerics, `.`, `-` or `_`.
+*/
+const EVAL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MAX_ID_LENGTH = 128;
+const expectSchema = z.union([QUIZ_VERDICT_ENUM, z.array(QUIZ_VERDICT_ENUM).min(1)]).meta({ description: "The verdict this answer must be graded with: one of \"correct\", \"partial\", \"incorrect\", or a non-empty list of acceptable verdicts (e.g. [correct, partial]) when more than one grading is defensible." });
+/** One golden answer: the student text plus the verdict(s) the grader must produce. */
+const EvalAnswerSchema = z.strictObject({
+	expect: expectSchema,
+	answer: z.string().min(1).meta({ description: "The student answer to grade, verbatim. Written as a YAML block scalar (|) for multi-line answers." })
+});
+/** All golden answers for ONE question of the target quiz. */
+const EvalQuestionSchema = z.strictObject({
+	question: z.string().min(1).meta({ description: "The question id in the target quiz. For a question imported through quiz_files this is the namespaced \"<alias>/<id>\" form." }),
+	answers: z.array(EvalAnswerSchema).min(1).meta({ description: "The golden answers for this question — at least one." })
+});
+/** The whole eval file. */
+const EvalYamlSchema = z.strictObject({
+	id: z.string().regex(EVAL_ID_PATTERN).max(MAX_ID_LENGTH).meta({ description: "Stable identifier of this eval, shown in the run report. Letters, digits, dot, dash and underscore." }),
+	target: z.string().min(1).meta({ description: "The quiz YAML this eval grades against — a path relative to THIS file, or an absolute http(s) URL." }),
+	questions: z.array(EvalQuestionSchema).min(1).meta({ description: "The evaluated questions — at least one, each with its golden answers." })
+});
+/**
+* The canonical expected-verdict SET of one golden answer: a single verdict or a list,
+* deduped and sorted into `EVAL_VERDICTS` order. Canonical because the confusion
+* matrix keys its rows by this set — `correct|partial` must be one row no matter which
+* order the author happened to write it in.
+*/
+function normalizeExpect(expect) {
+	return [...new Set(Array.isArray(expect) ? expect : [expect])].sort((a, b) => EVAL_VERDICTS.indexOf(a) - EVAL_VERDICTS.indexOf(b));
 }
-function registerFiles(program) {
-	const files = program.command("files").description("Manage app-hosted YAML files on the Novedu server");
-	files.command("upload <name>").description("Create or update an app-hosted YAML file from --file or stdin (validated server-side)").option("--kind <kind>", "file kind (tutor, fragment, quiz, writing, coding) — required when creating").option("--file <path>", "read the YAML from this path instead of stdin").option(...SERVER_OPTION$2).action(async (name, options) => {
-		let content;
-		try {
-			content = options.file === void 0 ? await readStdin() : await readFile(options.file, "utf8");
-		} catch (error) {
-			failJson({ message: `Could not read ${options.file}: ${error instanceof Error ? error.message : error}` });
-			return;
-		}
-		await runApiRequest({
-			server: options.server,
-			path: `/api/files/${encodeURIComponent(name)}`,
-			method: "PUT",
-			body: {
-				...options.kind === void 0 ? {} : { kind: options.kind },
-				content
-			}
-		});
-	});
-	files.command("list").description("List app-hosted YAML files (defaults to only your own, like the web list)").option("--search <q>", "contains-filter over name/title/description").option("--all", "include files last written by other teachers").option(...SERVER_OPTION$2).action(async (options) => {
-		const params = new URLSearchParams();
-		if (options.search) params.set("q", options.search);
-		if (options.all) params.set("mine", "0");
-		const query = params.toString();
-		await runApiRequest({
-			server: options.server,
-			path: `/api/files${query ? `?${query}` : ""}`
-		});
-	});
+/** The confusion matrix's row key for an expected set (already canonical). */
+function expectedKey(expected) {
+	return expected.join("|");
 }
 //#endregion
-//#region ../lib/file-name.ts
+//#region ../lib/coding-proxy.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /**
-* Maps a filename or bare extension (with or without a leading dot, any case)
-* to an {@link ImageMime}; returns `null` for anything unrecognized. `jpg`/`jpeg`
-* both map to `image/jpeg`, `svg` to `image/svg+xml`.
+* Appends the teacher's instructions to the END of an existing system-message
+* `content`, handling both the string form and OpenAI's content-parts array form.
+* Falls back to the instructions alone when there is no usable existing content.
 */
-function imageMimeFromExtension(filename) {
-	const lastDot = filename.lastIndexOf(".");
-	switch ((lastDot >= 0 ? filename.slice(lastDot + 1) : filename).toLowerCase()) {
-		case "png": return "image/png";
-		case "jpg":
-		case "jpeg": return "image/jpeg";
-		case "svg": return "image/svg+xml";
-		default: return null;
-	}
+function appendInstructions(existing, instructions) {
+	if (typeof existing === "string") return existing.trim() === "" ? instructions : `${existing}\n\n${instructions}`;
+	if (Array.isArray(existing)) return [...existing, {
+		type: "text",
+		text: instructions
+	}];
+	return instructions;
 }
-//#endregion
-//#region src/commands/images.ts
-const SERVER_OPTION$1 = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
-function registerImages(program) {
-	const images = program.command("images").description("Manage app-hosted images on the Novedu server");
-	images.command("upload <name>").description("Upload a NEW image (.png, .jpg/.jpeg or .svg, max 5 MB) from --file").option("--file <path>", "the image file to upload (required — images are binary, no stdin)").option("--credit <text>", "optional attribution shown with the image (max 512 chars)").option(...SERVER_OPTION$1).action(async (name, options) => {
-		if (options.file === void 0) {
-			failJson({ message: "Pass --file <path> — images are binary, stdin is not supported." });
-			return;
-		}
-		const mime = imageMimeFromExtension(options.file);
-		if (mime === null) {
-			failJson({ message: "Only .png, .jpg/.jpeg and .svg files can be uploaded." });
-			return;
-		}
-		let bytes;
-		try {
-			bytes = await readFile(options.file);
-		} catch (error) {
-			failJson({ message: `Could not read ${options.file}: ${error instanceof Error ? error.message : error}` });
-			return;
-		}
-		const slot = await performApiRequest({
-			server: options.server,
-			path: `/api/images/${encodeURIComponent(name)}`,
-			method: "POST",
-			body: {
-				mime,
-				byteSize: bytes.length
-			}
-		});
-		if (!slot.ok) return;
-		const { uploadUrl, blobPath } = slot.payload ?? {};
-		if (typeof uploadUrl !== "string" || typeof blobPath !== "string") {
-			failJson({ message: "Unexpected response from the server." });
-			return;
-		}
-		let putResponse;
-		try {
-			putResponse = await fetch(uploadUrl, {
-				method: "PUT",
-				headers: {
-					"x-ms-blob-type": "BlockBlob",
-					"content-type": mime
-				},
-				body: new Uint8Array(bytes)
-			});
-		} catch (error) {
-			failJson({ message: `Could not reach storage: ${error instanceof Error ? error.message : error}` });
-			return;
-		}
-		if (!putResponse.ok) {
-			failJson({ message: `The upload to storage failed: HTTP ${putResponse.status}. Try again.` });
-			return;
-		}
-		await runApiRequest({
-			server: options.server,
-			path: `/api/images/${encodeURIComponent(name)}/confirm`,
-			method: "POST",
-			body: {
-				blobPath,
-				mime,
-				...options.credit === void 0 ? {} : { credit: options.credit }
-			}
-		});
-	});
-	images.command("list").description("List app-hosted images (defaults to only your own, like the web list)").option("--search <q>", "contains-filter over the name").option("--all", "include images uploaded by other teachers").option(...SERVER_OPTION$1).action(async (options) => {
-		const params = new URLSearchParams();
-		if (options.search) params.set("q", options.search);
-		if (options.all) params.set("mine", "0");
-		const query = params.toString();
-		await runApiRequest({
-			server: options.server,
-			path: `/api/images${query ? `?${query}` : ""}`
-		});
-	});
+/**
+* Builds the upstream Chat Completions body from the client's body: PIN the model and
+* fold in the teacher's system prompt. The teacher's instructions are appended to the
+* END of the client's LAST system message, so the teacher has the final word: a client
+* cannot smuggle a later system message after the teacher's to override it. If the
+* client sent no system message, a leading one carrying only the teacher's instructions
+* is added. Everything else (messages, tools, tool_choice, temperature, stream, …)
+* passes through verbatim, so client-side tools and streaming are all preserved.
+*/
+function buildUpstreamChatBody(clientBody, opts) {
+	const clientMessages = Array.isArray(clientBody.messages) ? clientBody.messages : [];
+	const systemIndex = clientMessages.findLastIndex((m) => isRecord(m) && m.role === "system");
+	let messages;
+	if (systemIndex === -1) messages = [{
+		role: "system",
+		content: opts.instructions
+	}, ...clientMessages];
+	else {
+		const existing = clientMessages[systemIndex];
+		messages = [...clientMessages];
+		messages[systemIndex] = {
+			...existing,
+			content: appendInstructions(existing.content, opts.instructions)
+		};
+	}
+	const upstream = {
+		...clientBody,
+		model: opts.model,
+		messages
+	};
+	if (clientBody.stream === true) upstream.stream_options = {
+		...isRecord(clientBody.stream_options) ? clientBody.stream_options : {},
+		include_usage: true
+	};
+	return upstream;
 }
 //#endregion
-//#region src/commands/login.ts
-function registerLogin(program) {
-	program.command("login").description("Sign in to Microsoft Entra ID (opens your browser)").option("--device-code", "sign in with the device code flow instead (for machines without a browser; the tenant must allow it)").addHelpText("after", `
-Sign-in is the one human-assisted step: by default a browser window opens for
-the Microsoft sign-in (first-time users see a one-time consent prompt). On a
-machine without a browser, --device-code prints a verification URL and a code
-to enter from any other device — note that some tenants block the device code
-flow by policy (error 53003). Every other command then works non-interactively
-from the cached credentials. Already signed in? The command says so and exits
-— it never blocks.`).action(async (options) => {
-		const pca = buildPca();
-		const cached = await acquireSilent(pca);
-		if (cached) {
-			console.log(`Already signed in as ${displayName(cached)}.`);
-			return;
-		}
-		const result = options.deviceCode ? await acquireByDeviceCode(pca, (message) => console.log(message)) : await acquireInteractive(pca, (url) => {
-			console.log("A browser window should open for the Microsoft sign-in.");
-			console.log(`If it does not, open this URL yourself:\n${url}`);
-		});
-		console.log(`Signed in as ${displayName(result)}.`);
-	});
+//#region ../lib/prompt-fragments/block.ts
+/**
+* The consumed/empty block a runtime loader leaves behind after resolving fragments
+* into its own field (`Quiz.instructionsPreamble`, or folded into writing/coding
+* `instructions`), so no stale unresolved block lingers as a second source of truth
+* on the loaded object.
+*/
+const EMPTY_FRAGMENT_BLOCK = {
+	fragment_files: [],
+	text_files: []
+};
+function readFragmentBlock(root) {
+	return {
+		fragment_files: Array.isArray(root.fragment_files) ? root.fragment_files : [],
+		text_files: Array.isArray(root.text_files) ? root.text_files : []
+	};
 }
 //#endregion
-//#region src/commands/logout.ts
-function registerLogout(program) {
-	program.command("logout").description("Sign out: remove the cached credentials from this machine").addHelpText("after", `
-Purely local — already-issued access tokens stay valid until they expire
-(about an hour). Running it while signed out is fine.`).action(async () => {
-		const cache = buildPca().getTokenCache();
-		for (const account of await cache.getAllAccounts()) await cache.removeAccount(account);
-		rmSync(TOKEN_CACHE_PATH, { force: true });
-		console.log("Signed out.");
-	});
+//#region ../lib/coding-yaml.ts
+function asString$2(value) {
+	if (typeof value === "string") return value.trim() !== "" ? value : void 0;
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : void 0;
+	if (typeof value === "boolean") return String(value);
 }
-//#endregion
-//#region src/commands/reports.ts
-const SERVER_OPTION = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
-function registerReports(program) {
-	const reports = program.command("reports").description("Triage student reports on the Novedu server");
-	reports.command("list").description("List reports (defaults to open reports on your own codes, like the web inbox)").option("--status <status>", "open (default), resolved or all").option("--reaction <reaction>", "filter by reaction: good, omg, bad or holysh").option("--search <q>", "contains-filter over description, reporter, code and note").option("--all", "include reports on codes created by other teachers").option(...SERVER_OPTION).action(async (options) => {
-		const params = new URLSearchParams();
-		if (options.status) params.set("status", options.status);
-		if (options.reaction) params.set("reaction", options.reaction);
-		if (options.search) params.set("q", options.search);
-		if (options.all) params.set("mine", "0");
-		const query = params.toString();
-		await runApiRequest({
-			server: options.server,
-			path: `/api/reports${query ? `?${query}` : ""}`
-		});
-	});
-	reports.command("show <id>").description("Show one report; a chat report embeds its conversation transcript").option(...SERVER_OPTION).action(async (id, options) => {
-		await runApiRequest({
-			server: options.server,
-			path: `/api/reports/${encodeURIComponent(id)}`
-		});
-	});
-	reports.command("resolve <id...>").description("Resolve one or more reports by id (bulk, in a single request)").option(...SERVER_OPTION).action(async (ids, options) => {
-		await runApiRequest({
-			server: options.server,
-			path: "/api/reports/resolve",
-			method: "POST",
-			body: { ids }
-		});
-	});
+/**
+* Parses and lightly validates a coding YAML. Returns a friendly error message
+* (not structured errors) when an essential field is missing — the proxy and the
+* student page surface it as a notice.
+*/
+function parseCoding(content) {
+	let doc;
+	try {
+		doc = parse(content);
+	} catch {
+		return {
+			ok: false,
+			message: "This coding activity could not be read — its YAML is not valid."
+		};
+	}
+	if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return {
+		ok: false,
+		message: "This coding activity is empty or malformed."
+	};
+	const root = doc;
+	const llm = root.llm;
+	const model = asString$2(llm?.model);
+	if (!model) return {
+		ok: false,
+		message: "This coding activity does not specify a model (llm.model)."
+	};
+	const provider = llm?.provider === void 0 ? DEFAULT_PROVIDER : parseLenientProvider(llm.provider);
+	if (!provider) return {
+		ok: false,
+		message: "This coding activity uses an unsupported llm.provider (use \"SCCH\" or \"Azure Foundry\")."
+	};
+	const instructions = asString$2(root.instructions);
+	if (!instructions) return {
+		ok: false,
+		message: "This coding activity has no instructions for the assistant."
+	};
+	return {
+		ok: true,
+		coding: {
+			id: asString$2(root.id) ?? "coding",
+			title: asString$2(root.title),
+			model,
+			provider,
+			instructions,
+			fragmentBlock: readFragmentBlock(root)
+		}
+	};
 }
 //#endregion
 //#region ../lib/prompt-fragments/assemble.ts
@@ -2152,353 +2137,459 @@ async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	return checkFragmentFileValue(yaml.value, url);
 }
 //#endregion
-//#region ../lib/coding-schema.ts
-const CodingYamlSchema = z.strictObject({
-	id: z.string().min(1).meta({ description: "Short machine-readable activity id, e.g. beginner-typescript." }),
-	name: z.string().optional().meta({ description: "Optional human-readable label (not shown to the student)." }),
-	title: z.string().optional().meta({ description: "Optional label shown to the student on the /<code> connection page." }),
-	llm: z.strictObject({
-		model: z.string().min(1).meta({ description: "The model that answers. SERVER-ONLY and PINNED: the proxy always uses this model and ignores whatever model the coding agent sends." }),
-		provider: providerSchema
-	}).meta({
-		id: "llm",
-		description: "The pinned model and provider that answer coding requests."
-	}),
-	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
-	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source, e.g. a sample solution) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
-	instructions: z.string().min(1).meta({ description: "The assistant's system prompt. SERVER-ONLY: never sent to the browser or the coding agent, and appended AFTER the coding tool's own prompt (so the teacher has the final word). Constrain the assistant to what your class has learned. When any fragment_files or text_files are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." })
-});
-//#endregion
-//#region ../lib/coding-validate.ts
-/**
-* Extract metadata from an already-schema-validated coding value. Split from
-* `checkCodingValue` so `loadAndCheckCoding` can reuse the single `validate` it already
-* ran (no second parse of the same document against the same schema).
+//#region ../lib/coding-resolve.ts
+const DEFAULT_SCHEMES$2 = ["http:", "https:"];
+function schemeAllowed$2(url, allowed) {
+	try {
+		return allowed.includes(new URL(url).protocol);
+	} catch {
+		return false;
+	}
+}
+/**
+* Resolve a leniently parsed coding activity into the runnable one. Per-request
+* streaming hot path: consistency over the referenced fragments only
+* (`validateLibraries: false`); no extra passes.
 */
-function checkCodingParsed(coding) {
+async function resolveCoding(coding, url, fetcher, opts = {}) {
+	const resolved = await assembleFragmentPrompt(coding.fragmentBlock, url, fetcher, {
+		validateLibraries: false,
+		allowedSchemes: opts.allowedSchemes ?? DEFAULT_SCHEMES$2
+	}, coding.instructions);
+	if (!resolved.ok) return {
+		ok: false,
+		message: "This coding activity's prompt fragments could not be loaded."
+	};
 	return {
 		ok: true,
-		codingId: coding.id,
-		model: coding.llm.model,
-		provider: coding.llm.provider,
-		title: coding.title ?? null,
-		warnings: []
+		coding: {
+			...coding,
+			fragmentBlock: EMPTY_FRAGMENT_BLOCK,
+			instructions: resolved.prompt
+		}
 	};
 }
 /**
-* Validate a coding FILE: scheme-gate + fetch + parse (shared `loadYaml`), then the
-* pure `checkCodingValue`. The web app passes the default http(s)-only schemes; the
-* CLI adds `file:` so a local coding YAML on disk validates too.
+* Fetch + lenient-parse + `resolveCoding`, all through the CALLER's fetcher — the
+* app-free counterpart of `loadCoding` (`lib/coding-fetch.ts`) used by the prompt dump
+* and the CLI, where there is no database and an activity may live on disk (`file:`).
 */
-async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
-	const yaml = await loadYaml(url, fetchImpl, opts);
-	if (!yaml.ok) return {
-		ok: false,
-		errors: [yaml.error],
-		warnings: []
-	};
-	const valid = validate(yaml.value, CodingYamlSchema, "CODING_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
-	};
-	const checked = checkCodingParsed(valid.data);
-	if (!checked.ok) return checked;
-	const assembled = await assembleFragmentPrompt({
-		fragment_files: valid.data.fragment_files,
-		text_files: valid.data.text_files
-	}, url, fetchImpl, {
-		allowedSchemes: opts.allowedSchemes,
-		validateLibraries: opts.validateLibraries ?? true
-	}, valid.data.instructions);
-	const warnings = [...checked.warnings, ...assembled.warnings];
-	if (!assembled.ok) return {
+async function loadCodingFrom(url, fetcher, opts = {}) {
+	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_SCHEMES$2;
+	if (!schemeAllowed$2(url, allowedSchemes)) return {
 		ok: false,
-		errors: assembled.errors,
-		warnings
-	};
-	return {
-		...checked,
-		warnings
+		message: `This coding activity's URL is not allowed: ${url}`
 	};
+	try {
+		const res = await fetcher(url);
+		if (!res.ok) return res.status === 404 ? {
+			ok: false,
+			message: "This coding activity could not be found."
+		} : {
+			ok: false,
+			message: `This coding activity could not be loaded (HTTP ${res.status}).`
+		};
+		const parsed = parseCoding(await res.text());
+		if (!parsed.ok) return parsed;
+		return await resolveCoding(parsed.coding, url, fetcher, { allowedSchemes });
+	} catch {
+		return {
+			ok: false,
+			message: "This coding activity could not be loaded. Try again."
+		};
+	}
 }
 //#endregion
-//#region ../lib/quiz-schema.ts
+//#region ../lib/quiz-types.ts
+/** The student-facing wording for a verdict — `partial` reads as "partly correct". */
+function verdictLabel(verdict) {
+	switch (verdict) {
+		case "correct": return "correct";
+		case "partial": return "partly correct";
+		case "incorrect": return "wrong";
+	}
+}
+//#endregion
+//#region ../lib/quiz-discussion-prompt.ts
 /**
-* A live quiz include: alias + URL, mirroring `FragmentFileRefSchema` (same URL
-* contract). The alias prefixes every imported question id as `"<alias>/<id>"`, so
-* on top of the no-dot rule it may not contain a `/` either. Aliases live in their
-* OWN namespace (they never appear in `{{…}}` markers — only in question ids).
+* The discussion chat's system prompt: the quiz-level `instructionsPreamble` (the
+* rendered `instructions` host text — shared safety/persona/language rules, the SAME
+* preamble the grader receives) followed by a default frame and the quiz's optional
+* `discussionInstructions`. The question/answer/verdict are the thread's seed messages,
+* recalled from memory, NOT repeated here.
+*
+* A compound quiz's imported questions each carry their SOURCE quiz's preamble
+* (`sourcePreamble`), but that applies to GRADING only (`buildGradingPrompt`): the
+* discussion prompt uses ONLY the compound file's own instructions — consistent with
+* every other include-level field (`llm`, `anonymous`, `shuffle`, ...), which the
+* compound file governs too. Mixing all chapters' preambles into one prompt would put
+* conflicting persona/language rules in force at once; the question/answer/verdict the
+* discussion needs are recalled from the thread's seed messages regardless.
 */
-const QuizFileRefSchema = z.strictObject({
-	id: z.string().regex(/^[^./]+$/, { message: "Alias must not contain a dot or a slash" }).meta({
-		pattern: "^[^./]+$",
-		description: "Local alias for this included quiz. Prefixes every imported question id as \"<alias>/<id>\", so it may not contain a dot or a slash."
-	}),
-	url: FragmentFileRefSchema.shape.url.meta({
-		pattern: "^(https?://|(?![A-Za-z][A-Za-z0-9+.-]*:).+)$",
-		description: "HTTP(S) URL or relative path to the included quiz file."
-	})
-}).meta({
-	id: "quizFileRef",
-	description: "A reference to another quiz file whose questions are included live."
-});
-/** An optional content image attached to a question (carries no secret). */
-const ImageRefSchema = z.strictObject({
-	hosted: z.boolean().optional().meta({
-		default: false,
-		description: "When true, src is an app-hosted image NAME resolved server-side; otherwise src is an absolute URL or a path relative to the quiz's own URL."
-	}),
-	src: z.string().min(1).meta({ description: "The hosted image name (when hosted) or the image URL / relative path." }),
-	alt: z.string().optional().meta({ description: "Accessible description shown if the image cannot be loaded." }),
-	credit: z.string().optional().meta({ description: "Optional attribution (\"Content Credentials\") shown small below the image." })
-}).meta({
-	id: "image",
-	description: "An optional content image attached to a question."
-});
+function buildDiscussionInstructions(quiz) {
+	const base = "You are helping a student understand a single quiz question. The conversation already contains the question, the student's submitted answer, and the verdict with feedback — use that context. Be concise and encouraging, and stay on this question.";
+	const frame = quiz.discussionInstructions ? `${base}\n\n${quiz.discussionInstructions.trim()}` : base;
+	return [quiz.instructionsPreamble, frame].filter(Boolean).join("\n\n");
+}
 /**
-* One question. `id` keys the per-question stats (must be unique — see
-* `lib/quiz-validate.ts`); `question` is the Markdown shown to the student;
-* `evaluation` is the server-only grading prompt.
+* Seed message 1 (assistant): the question, as the SERVER knows it (authoritative).
+* `{question}` is the question's trimmed markdown.
 */
-const QuizQuestionSchema = z.strictObject({
-	id: z.string().min(1).meta({ description: "Stable question id, unique within the quiz (the per-question stats key)." }),
-	title: z.string().optional().meta({ description: "Optional short label for the stats table and progress display." }),
-	question: z.string().min(1).meta({ description: "The Markdown shown to the student." }),
-	evaluation: z.string().min(1).meta({ description: "The grading prompt. SERVER-ONLY: never sent to the browser, so it may embed the expected answer and the grading rubric." }),
-	image: ImageRefSchema.optional(),
-	imageInput: z.boolean().optional().meta({ description: "Overrides the quiz-level llm.imageInput for this question only (photo answers on/off)." })
-}).meta({
-	id: "question",
-	description: "One open-ended, LLM-graded quiz question."
-});
-const QuizYamlSchema = z.strictObject({
-	id: z.string().min(1).meta({ description: "Short machine-readable quiz id, e.g. countries-basics. Used as the per-quiz identity." }),
-	name: z.string().optional().meta({ description: "Optional human-readable quiz title (used as a label)." }),
-	title: z.string().optional().meta({ description: "Optional greeting shown to students on the welcome screen instead of the default message." }),
-	description: z.string().optional().meta({ description: "Optional description shown to students below the welcome greeting (Markdown)." }),
-	anonymous: z.boolean().optional().meta({
-		default: true,
-		description: "Quizzes are anonymous by default: answers are recorded for aggregate stats but not linked to a student. Set to false to attribute each attempt to the signed-in student."
-	}),
-	shuffle: z.boolean().optional().meta({
-		default: true,
-		description: "Present questions in a random order per attempt. Set to false to keep the authored order."
-	}),
-	question_count: z.number().int().min(1).optional().meta({ description: "How many questions one attempt asks (default: every question exactly once). May exceed the pool size — then questions repeat (drill mode). With shuffle off, fewer than the pool means the first N in authored order." }),
-	quiz_files: z.array(QuizFileRefSchema).default([]).meta({ description: "Other quiz files whose questions are ALL included live into this quiz (a compound/final quiz). One level deep — an included quiz may not itself declare quiz_files." }),
-	llm: z.strictObject({
-		model: z.string().min(1).meta({ description: "The model that grades answers and drives the per-question discussion chat." }),
-		provider: providerSchema,
-		imageInput: z.boolean().optional().meta({
-			default: false,
-			description: "Default for all questions: students may attach photos (up to 3, 5 MB each) to their answers. The model must be vision-capable. A per-question imageInput overrides it."
-		})
-	}).meta({
-		id: "llm",
-		description: "The single model + provider that grades and discusses answers."
-	}),
-	discussion: z.strictObject({ instructions: z.string().min(1).meta({ description: "Optional guidance appended to the per-question follow-up discussion chat's system prompt. When any fragment_files or text_files are declared, place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (escape a literal {{ as \\{{) — same rules as instructions." }) }).optional().meta({
-		id: "discussion",
-		description: "Optional guidance for the per-question follow-up discussion chat."
-	}),
-	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this quiz pulls shared prompt fragments from." }),
-	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
-	instructions: z.string().optional().meta({ description: "Optional quiz-level preamble prepended to BOTH the grader prompt and the discussion chat. When any fragment_files or text_files are declared, place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." }),
-	questions: z.array(QuizQuestionSchema).default([]).meta({ description: "The quiz questions. Each is open-ended and graded by the LLM via its evaluation prompt. May be omitted when quiz_files supplies the questions." })
-});
+const QUIZ_SEED_QUESTION_TEMPLATE = "Answer the following question: {question}";
+/**
+* Seed message 3 (assistant): the graded outcome. `{verdictLabel}` is the student-facing
+* wording from `verdictLabel()` (correct / partly correct / wrong), `{feedback}` the
+* grader's markdown feedback. (Seed message 2 is the student's own answer verbatim, so
+* it has no template.)
+*/
+const QUIZ_SEED_VERDICT_TEMPLATE = "Your answer is {verdictLabel}. {feedback}";
 //#endregion
-//#region ../lib/quiz-validate.ts
-/** Quizzes default to anonymous — answers are recorded for stats but not attributed. */
-const DEFAULT_ANONYMOUS$1 = true;
-/** Question ids declared on more than one question (the per-question stats key). */
-function findDuplicateQuestionIds(quiz) {
-	const errors = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const question of quiz.questions) {
-		if (seen.has(question.id)) {
-			errors.push(error("DUPLICATE_QUIZ_QUESTION_ID", `Question id "${question.id}" is declared more than once`, { questionId: question.id }));
-			continue;
-		}
-		seen.add(question.id);
-	}
-	return errors;
-}
+//#region ../lib/quiz-grading-prompt.ts
 /**
-* Own question ids containing `/` — reserved as the namespace delimiter for
-* questions imported via `quiz_files` (`"<alias>/<id>"`), so an own id can never
-* collide with (or masquerade as) an imported one.
+* The grading system prompt. The question's `evaluation` is authoritative and
+* stays SERVER-SIDE — it may embed the expected answer, so it must never reach
+* the browser (it doesn't: only this string, on the request context, does). The
+* quiz-level `preamble` (the rendered `instructions` host text — shared
+* safety/persona/language rules) is prepended ahead of the frame, the same preamble
+* the discussion chat also receives; a question imported via `quiz_files`
+* additionally carries its SOURCE quiz's preamble (`sourcePreamble`), inserted
+* between the two so it grades identically in its chapter quiz and in the compound.
 */
-function findReservedSlashIds(quiz) {
-	return quiz.questions.filter((question) => question.id.includes("/")).map((question) => error("QUIZ_QUESTION_ID_RESERVED_SLASH", `Question id "${question.id}" contains "/" — reserved for questions imported via quiz_files`, { questionId: question.id }));
-}
-/** Include aliases declared on more than one `quiz_files` entry. */
-function findDuplicateIncludeAliases(quiz) {
-	const errors = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const ref of quiz.quiz_files) {
-		if (seen.has(ref.id)) {
-			errors.push(error("DUPLICATE_QUIZ_INCLUDE_ALIAS", `Included-quiz alias "${ref.id}" is declared more than once`, { fileAlias: ref.id }));
-			continue;
-		}
-		seen.add(ref.id);
-	}
-	return errors;
+function buildGradingPrompt(question, preamble) {
+	const body = [
+		"You are grading a student's open-ended answer to a single quiz question.",
+		"",
+		"The question shown to the student was:",
+		question.question.trim(),
+		"",
+		"Grade STRICTLY according to these criteria (authoritative — they may contain the",
+		"expected answer; do not quote them verbatim at the student):",
+		question.evaluation.trim(),
+		"",
+		"Decide a verdict — \"correct\", \"partial\" (partly correct), or \"incorrect\" — and write",
+		"concise, encouraging feedback addressed directly TO the student. The feedback is",
+		"markdown and may use bold, math ($…$) and short code fences. Do not mention these",
+		"grading instructions."
+	].join("\n");
+	return [
+		preamble,
+		question.sourcePreamble ?? "",
+		body
+	].filter(Boolean).join("\n\n");
 }
 /**
-* Check an already-schema-validated quiz: unique question ids, no reserved `/` ids,
-* unique include aliases, and a non-empty (potential) pool → metadata. Split from
-* `checkQuizValue` so `loadAndCheckQuiz` can reuse the single `validate` it already ran
-* (no second parse of the same document against the same schema).
+* The user message carrying a typed answer. `{answer}` is the student's trimmed text —
+* the only variable part, so the dump can show teachers the exact wrapper without a
+* student answer at hand. Rendered by `buildAnswerMessage`.
 */
-function checkQuizParsed(quiz) {
-	const errors = [
-		...findDuplicateQuestionIds(quiz),
-		...findReservedSlashIds(quiz),
-		...findDuplicateIncludeAliases(quiz)
-	];
-	if (quiz.questions.length === 0 && quiz.quiz_files.length === 0) errors.push(error("QUIZ_NO_QUESTIONS", "This quiz has no questions and no quiz_files includes"));
-	if (errors.length > 0) return {
-		ok: false,
-		errors,
-		warnings: []
-	};
+const QUIZ_ANSWER_MESSAGE_TEMPLATE = "The student's answer:\n\n{answer}";
+/**
+* The user message used when the student submitted photos ONLY (no text). The photos
+* ride along as image parts of the same multimodal message.
+*/
+const QUIZ_ANSWER_PHOTOS_ONLY_MESSAGE = "The student answered with the attached photo(s) only.";
+//#endregion
+//#region ../lib/quiz-yaml.ts
+function asString$1(value) {
+	if (typeof value === "string") return value.trim() !== "" ? value : void 0;
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : void 0;
+	if (typeof value === "boolean") return String(value);
+}
+function asBool$1(value, fallback) {
+	return typeof value === "boolean" ? value : fallback;
+}
+function asImageRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const obj = value;
+	const src = asString$1(obj.src);
+	if (!src) return void 0;
+	const alt = asString$1(obj.alt);
+	const credit = asString$1(obj.credit);
 	return {
-		ok: true,
-		quizId: quiz.id,
-		model: quiz.llm.model,
-		provider: quiz.llm.provider,
-		questionCount: quiz.questions.length,
-		anonymous: quiz.anonymous ?? DEFAULT_ANONYMOUS$1,
-		title: quiz.title ?? null,
-		warnings: []
+		hosted: asBool$1(obj.hosted, false),
+		src,
+		...alt ? { alt } : {},
+		...credit ? { credit } : {}
 	};
 }
-/** Wrap an include's nested failures into ONE error carrying the alias + URL. */
-function includeUnreadable(alias, url, nested) {
-	return error("QUIZ_INCLUDE_UNREADABLE", `Included quiz "${alias}" is not usable: ${nested.map((e) => e.message).join("; ")}`, url === void 0 ? { fileAlias: alias } : {
-		fileAlias: alias,
-		url
-	});
-}
 /**
-* Deep-check ONE `quiz_files` include: resolve + fetch + parse + the FULL strict
-* quiz check (schema, consistency passes, its own fragment-block authoring gate),
-* plus the one-level rule (`QUIZ_INCLUDE_NESTED`). Every other failure is wrapped
-* as `QUIZ_INCLUDE_UNREADABLE` with the alias + resolved URL.
+* Parses and lightly validates a quiz YAML. Returns a friendly error message
+* (not structured errors) when an essential field is missing — the student page
+* shows it as a notice. `anonymous` and `shuffle` default to `true`.
 */
-async function checkInclude(ref, baseUrl, fetchImpl, opts) {
-	let includeUrl;
+function parseQuiz(content) {
+	let doc;
 	try {
-		includeUrl = resolveFragmentUrl(ref.url, baseUrl);
+		doc = parse(content);
 	} catch {
 		return {
 			ok: false,
-			errors: [includeUnreadable(ref.id, void 0, [error("INVALID_URL", `Invalid include URL: ${ref.url}`)])],
-			warnings: []
+			message: "This quiz could not be read — its YAML is not valid."
 		};
 	}
-	const yaml = await loadYaml(includeUrl, fetchImpl, opts);
-	if (!yaml.ok) return {
+	if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return {
 		ok: false,
-		errors: [includeUnreadable(ref.id, includeUrl, [yaml.error])],
-		warnings: []
+		message: "This quiz is empty or malformed."
 	};
-	const valid = validate(yaml.value, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", includeUrl);
-	if (!valid.ok) return {
+	const root = doc;
+	const llm = root.llm;
+	const model = asString$1(llm?.model);
+	if (!model) return {
 		ok: false,
-		errors: [includeUnreadable(ref.id, includeUrl, [valid.error])],
-		warnings: []
+		message: "This quiz does not specify a model (llm.model)."
 	};
-	if (valid.data.quiz_files.length > 0) return {
+	const provider = llm?.provider === void 0 ? DEFAULT_PROVIDER : parseLenientProvider(llm.provider);
+	if (!provider) return {
 		ok: false,
-		errors: [error("QUIZ_INCLUDE_NESTED", `Included quiz "${ref.id}" itself declares quiz_files — includes are one level deep`, {
-			fileAlias: ref.id,
-			url: includeUrl
-		})],
-		warnings: []
+		message: "This quiz uses an unsupported llm.provider (use \"SCCH\" or \"Azure Foundry\")."
 	};
-	const checked = checkQuizParsed(valid.data);
-	if (!checked.ok) return {
+	const quizFiles = Array.isArray(root.quiz_files) ? root.quiz_files : [];
+	const rawQuestions = Array.isArray(root.questions) ? root.questions : [];
+	if (rawQuestions.length === 0 && quizFiles.length === 0) return {
 		ok: false,
-		errors: [includeUnreadable(ref.id, includeUrl, checked.errors)],
-		warnings: checked.warnings
+		message: "This quiz has no questions."
 	};
-	const assembled = await assembleFragmentPrompts({
-		fragment_files: valid.data.fragment_files,
-		text_files: valid.data.text_files
-	}, includeUrl, fetchImpl, {
-		allowedSchemes: opts.allowedSchemes,
-		validateLibraries: opts.validateLibraries ?? true
-	}, [valid.data.instructions ?? "", valid.data.discussion?.instructions ?? ""]);
-	if (!assembled.ok) return {
+	const questions = [];
+	const seenIds = /* @__PURE__ */ new Set();
+	for (const raw of rawQuestions) {
+		if (typeof raw !== "object" || raw === null) continue;
+		const q = raw;
+		const id = asString$1(q.id);
+		const question = asString$1(q.question);
+		const evaluation = asString$1(q.evaluation);
+		if (!id || !question || !evaluation || seenIds.has(id)) continue;
+		seenIds.add(id);
+		questions.push({
+			id,
+			title: asString$1(q.title),
+			question,
+			evaluation,
+			image: asImageRef(q.image),
+			...typeof q.imageInput === "boolean" ? { imageInput: q.imageInput } : {}
+		});
+	}
+	if (questions.length === 0 && quizFiles.length === 0) return {
 		ok: false,
-		errors: [includeUnreadable(ref.id, includeUrl, assembled.errors)],
-		warnings: assembled.warnings
+		message: "This quiz has no complete questions (each needs an id, question and evaluation)."
 	};
+	const rawCount = root.question_count;
+	const questionCount = typeof rawCount === "number" && Number.isInteger(rawCount) && rawCount >= 1 ? rawCount : void 0;
 	return {
 		ok: true,
-		questionCount: valid.data.questions.length,
-		warnings: assembled.warnings
+		quiz: {
+			id: asString$1(root.id) ?? asString$1(root.name) ?? "quiz",
+			name: asString$1(root.name),
+			title: asString$1(root.title),
+			description: asString$1(root.description),
+			anonymous: asBool$1(root.anonymous, true),
+			shuffle: asBool$1(root.shuffle, true),
+			model,
+			provider,
+			questionCount,
+			imageInput: asBool$1(llm?.imageInput, false),
+			discussionInstructions: asString$1(root.discussion?.instructions),
+			instructions: asString$1(root.instructions),
+			fragmentBlock: readFragmentBlock(root),
+			quizFiles,
+			instructionsPreamble: "",
+			questions
+		}
 	};
 }
 /**
-* Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), the pure
-* `checkQuizValue`, the document-level fragment block's authoring gate — fetch
-* every referenced library, run the THOROUGH whole-library check, consistency, and an
-* assembly dry-run (the strict-Handlebars backstop) — and a DEEP check of every
-* `quiz_files` include. On success `questionCount` is the RESOLVED pool size
-* (own + imported), so the `/files` save UI and code-create metadata reflect the
-* real exam size. The web app passes the default http(s)-only schemes; the CLI adds
-* `file:` so a local quiz YAML on disk validates too.
+* A question's EFFECTIVE photo-answers flag: the per-question override when set, the
+* quiz-level `llm.imageInput` otherwise. The ONE definition of that two-level rule —
+* re-exported by `lib/quiz-verify.ts` for the server actions (which re-derive it on
+* every request, never trusting the client), applied by `toPublicQuiz` below, and
+* reported per question by the prompt dump.
 */
-async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
-	const yaml = await loadYaml(url, fetchImpl, opts);
-	if (!yaml.ok) return {
+function effectiveImageInput(quiz, question) {
+	return question.imageInput ?? quiz.imageInput;
+}
+//#endregion
+//#region ../lib/quiz-resolve.ts
+const DEFAULT_SCHEMES$1 = ["http:", "https:"];
+function schemeAllowed$1(url, allowed) {
+	try {
+		return allowed.includes(new URL(url).protocol);
+	} catch {
+		return false;
+	}
+}
+/**
+* Renders ONE quiz document's `instructions` host text against its OWN fragment
+* block, relative to its OWN URL (`validateLibraries: false` — the hot path). Used
+* for each included source quiz, so an imported question's `sourcePreamble` is
+* exactly what its chapter quiz would grade with. (The root document renders its
+* two host texts — `instructions` + `discussion.instructions` — in `resolveQuiz`.)
+*/
+async function renderPreamble(quiz, url, fetcher, allowedSchemes) {
+	const resolved = await assembleFragmentPrompt(quiz.fragmentBlock, url, fetcher, {
+		validateLibraries: false,
+		allowedSchemes
+	}, quiz.instructions ?? "");
+	if (!resolved.ok) return { ok: false };
+	return {
+		ok: true,
+		preamble: resolved.prompt.trimEnd()
+	};
+}
+/**
+* Absolutize an imported question's content image against the SOURCE quiz URL, so
+* a `./diagram.png` next to the chapter quiz still resolves from the compound quiz
+* (whose own `file_url` is elsewhere). Hosted NAMES and absolute URLs pass through
+* unchanged — they resolve the same from anywhere.
+*/
+function absolutizeImage(image, sourceUrl) {
+	if (!image || image.hosted === true || /^https?:\/\//i.test(image.src)) return image;
+	try {
+		return {
+			...image,
+			src: resolveFragmentUrl(image.src, sourceUrl)
+		};
+	} catch {
+		return image;
+	}
+}
+/** Resolve ONE `quiz_files` include into its namespaced, import-transformed questions. */
+async function resolveInclude(ref, baseUrl, fetcher, allowedSchemes) {
+	const alias = typeof ref?.id === "string" ? ref.id.trim() : "";
+	const rawUrl = typeof ref?.url === "string" ? ref.url.trim() : "";
+	if (!alias || /[./]/.test(alias) || !rawUrl) return {
 		ok: false,
-		errors: [yaml.error],
-		warnings: []
+		message: "This quiz declares an invalid quiz_files entry."
 	};
-	const valid = validate(yaml.value, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
+	let sourceUrl;
+	try {
+		sourceUrl = resolveFragmentUrl(rawUrl, baseUrl);
+	} catch {
+		return {
+			ok: false,
+			message: `The included quiz "${alias}" has an invalid URL.`
+		};
+	}
+	if (!schemeAllowed$1(sourceUrl, allowedSchemes)) return {
 		ok: false,
-		errors: [valid.error],
-		warnings: []
+		message: `The included quiz "${alias}" has an invalid URL.`
 	};
-	const checked = checkQuizParsed(valid.data);
-	if (!checked.ok) return checked;
-	const assembled = await assembleFragmentPrompts({
-		fragment_files: valid.data.fragment_files,
-		text_files: valid.data.text_files
-	}, url, fetchImpl, {
-		allowedSchemes: opts.allowedSchemes,
-		validateLibraries: opts.validateLibraries ?? true
-	}, [valid.data.instructions ?? "", valid.data.discussion?.instructions ?? ""]);
-	const warnings = [...checked.warnings, ...assembled.warnings];
-	if (!assembled.ok) return {
+	let body;
+	try {
+		const res = await fetcher(sourceUrl);
+		if (!res.ok) return {
+			ok: false,
+			message: `The included quiz "${alias}" could not be loaded.`
+		};
+		body = await res.text();
+	} catch {
+		return {
+			ok: false,
+			message: `The included quiz "${alias}" could not be loaded.`
+		};
+	}
+	const parsed = parseQuiz(body);
+	if (!parsed.ok) return {
 		ok: false,
-		errors: assembled.errors,
-		warnings
+		message: `The included quiz "${alias}" is not a usable quiz file.`
 	};
-	const includes = await Promise.all(valid.data.quiz_files.map((ref) => checkInclude(ref, url, fetchImpl, opts)));
-	const includeErrors = [];
-	let importedCount = 0;
+	if (parsed.quiz.quizFiles.length > 0) return {
+		ok: false,
+		message: `The included quiz "${alias}" itself includes other quizzes — includes cannot be nested.`
+	};
+	const preamble = await renderPreamble(parsed.quiz, sourceUrl, fetcher, allowedSchemes);
+	if (!preamble.ok) return {
+		ok: false,
+		message: `The included quiz "${alias}"'s prompt fragments could not be loaded.`
+	};
+	const source = parsed.quiz;
+	return {
+		ok: true,
+		questions: source.questions.map((q) => ({
+			...q,
+			id: `${alias}/${q.id}`,
+			imageInput: q.imageInput ?? source.imageInput,
+			image: absolutizeImage(q.image, sourceUrl),
+			...preamble.preamble ? { sourcePreamble: preamble.preamble } : {}
+		}))
+	};
+}
+/**
+* Resolve a leniently parsed quiz into the runnable one: render its two host texts,
+* then merge in every `quiz_files` include. `url` is the quiz's own URL (the base for
+* relative fragment/include refs); `fetcher` is the caller's network seam.
+*/
+async function resolveQuiz(quiz, url, fetcher, opts = {}) {
+	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_SCHEMES$1;
+	const resolved = await assembleFragmentPrompts(quiz.fragmentBlock, url, fetcher, {
+		validateLibraries: false,
+		allowedSchemes
+	}, [quiz.instructions ?? "", quiz.discussionInstructions ?? ""]);
+	if (!resolved.ok) return {
+		ok: false,
+		message: "This quiz's prompt fragments could not be loaded."
+	};
+	const [instructionsPreamble = "", discussionInstructions = ""] = resolved.prompts;
+	const refs = quiz.quizFiles;
+	const aliases = /* @__PURE__ */ new Set();
+	for (const ref of refs) {
+		const alias = typeof ref?.id === "string" ? ref.id.trim() : "";
+		if (aliases.has(alias)) return {
+			ok: false,
+			message: `This quiz declares the included-quiz alias "${alias}" twice.`
+		};
+		aliases.add(alias);
+	}
+	const includes = await Promise.all(refs.map((ref) => resolveInclude(ref, url, fetcher, allowedSchemes)));
+	const imported = [];
 	for (const include of includes) {
-		warnings.push(...include.warnings);
-		if (include.ok) importedCount += include.questionCount;
-		else includeErrors.push(...include.errors);
+		if (!include.ok) return include;
+		imported.push(...include.questions);
 	}
-	if (includeErrors.length > 0) return {
+	const questions = [...quiz.questions, ...imported];
+	if (questions.length === 0) return {
 		ok: false,
-		errors: includeErrors,
-		warnings
+		message: "This quiz has no questions."
 	};
 	return {
-		...checked,
-		questionCount: checked.questionCount + importedCount,
-		warnings
+		ok: true,
+		quiz: {
+			...quiz,
+			fragmentBlock: EMPTY_FRAGMENT_BLOCK,
+			quizFiles: [],
+			instructionsPreamble: instructionsPreamble.trimEnd(),
+			discussionInstructions: discussionInstructions.trim() !== "" ? discussionInstructions.trimEnd() : void 0,
+			questions
+		}
+	};
+}
+/**
+* Fetch + lenient-parse + `resolveQuiz`, all through the CALLER's fetcher — the
+* app-free counterpart of `loadQuiz` (`lib/quiz-fetch.ts`) used by the prompt dump and
+* the CLI, where there is no database and a quiz may live on disk (`file:`).
+*/
+async function loadQuizFrom(url, fetcher, opts = {}) {
+	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_SCHEMES$1;
+	if (!schemeAllowed$1(url, allowedSchemes)) return {
+		ok: false,
+		message: `This quiz's URL is not allowed: ${url}`
 	};
+	try {
+		const res = await fetcher(url);
+		if (!res.ok) return res.status === 404 ? {
+			ok: false,
+			message: "This quiz could not be found."
+		} : {
+			ok: false,
+			message: `This quiz could not be loaded (HTTP ${res.status}).`
+		};
+		const parsed = parseQuiz(await res.text());
+		if (!parsed.ok) return parsed;
+		return await resolveQuiz(parsed.quiz, url, fetcher, { allowedSchemes });
+	} catch {
+		return {
+			ok: false,
+			message: "This quiz could not be loaded. Try again."
+		};
+	}
 }
 //#endregion
 //#region ../lib/tutors/schemas.ts
@@ -2570,6 +2661,7 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 	};
 	return {
 		ok: true,
+		id: tutor.id,
 		prompt: assembled.prompt,
 		model: tutor.llm.model,
 		provider: tutor.llm.provider,
@@ -2582,348 +2674,2288 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 	};
 }
 //#endregion
-//#region ../lib/writing-schema.ts
-const WritingYamlSchema = z.strictObject({
-	id: z.string().min(1).meta({ description: "Short machine-readable activity id, e.g. human-animal-short-story." }),
-	name: z.string().optional().meta({ description: "Optional human-readable title (used as a label)." }),
-	title: z.string().optional().meta({ description: "Optional greeting shown to students on the welcome screen instead of the default message." }),
-	description: z.string().optional().meta({ description: "Optional description shown to students below the welcome greeting (Markdown)." }),
-	anonymous: z.boolean().optional().meta({
-		default: false,
-		description: "Writing DIVERGES: it defaults to false (attributed), because review and the Save feature need to know whose text it is. Set to true for ephemeral, unattributed writing — which also disables saving."
-	}),
-	llm: z.strictObject({
-		model: z.string().min(1).meta({ description: "The model that drives the feedback chat." }),
-		provider: providerSchema
-	}).meta({
-		id: "llm",
-		description: "The model and provider that back the writing coach."
-	}),
-	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
-	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
-	instructions: z.string().min(1).meta({ description: "The writing coach's system prompt. SERVER-ONLY: never sent to the browser, so it may describe the assessment criteria and coaching strategy. When any fragment_files or text_files are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." }),
-	placeholder: z.string().optional().meta({ description: "Optional starter text prefilled into the editor. Empty for a blank page." })
-});
-//#endregion
-//#region ../lib/writing-validate.ts
-/** Writing DIVERGES from tutor/quiz: it defaults to attributed (`anonymous: false`). */
-const DEFAULT_ANONYMOUS = false;
-/**
-* Extract metadata from an already-schema-validated writing value. Split from
-* `checkWritingValue` so `loadAndCheckWriting` can reuse the single `validate` it already
-* ran (no second parse of the same document against the same schema).
-*/
-function checkWritingParsed(writing) {
-	return {
-		ok: true,
-		writingId: writing.id,
-		model: writing.llm.model,
-		provider: writing.llm.provider,
-		anonymous: writing.anonymous ?? DEFAULT_ANONYMOUS,
-		title: writing.title ?? null,
-		warnings: []
-	};
+//#region ../lib/writing-yaml.ts
+function asString(value) {
+	if (typeof value === "string") return value.trim() !== "" ? value : void 0;
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : void 0;
+	if (typeof value === "boolean") return String(value);
+}
+function asBool(value, fallback) {
+	return typeof value === "boolean" ? value : fallback;
 }
 /**
-* Validate a writing FILE: scheme-gate + fetch + parse (shared `loadYaml`), then the
-* pure `checkWritingValue`. The web app passes the default http(s)-only schemes; the
-* CLI adds `file:` so a local writing YAML on disk validates too.
+* Parses and lightly validates a writing YAML. Returns a friendly error message
+* (not structured errors) when an essential field is missing — the student page
+* shows it as a notice. `anonymous` DEFAULTS to `false` (the writing divergence).
 */
-async function loadAndCheckWriting(url, fetchImpl, opts = {}) {
-	const yaml = await loadYaml(url, fetchImpl, opts);
-	if (!yaml.ok) return {
+function parseWriting(content) {
+	let doc;
+	try {
+		doc = parse(content);
+	} catch {
+		return {
+			ok: false,
+			message: "This writing activity could not be read — its YAML is not valid."
+		};
+	}
+	if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return {
 		ok: false,
-		errors: [yaml.error],
-		warnings: []
+		message: "This writing activity is empty or malformed."
 	};
-	const valid = validate(yaml.value, WritingYamlSchema, "WRITING_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
+	const root = doc;
+	const llm = root.llm;
+	const model = asString(llm?.model);
+	if (!model) return {
 		ok: false,
-		errors: [valid.error],
-		warnings: []
+		message: "This writing activity does not specify a model (llm.model)."
 	};
-	const checked = checkWritingParsed(valid.data);
-	if (!checked.ok) return checked;
-	const assembled = await assembleFragmentPrompt({
-		fragment_files: valid.data.fragment_files,
-		text_files: valid.data.text_files
-	}, url, fetchImpl, {
-		allowedSchemes: opts.allowedSchemes,
-		validateLibraries: opts.validateLibraries ?? true
-	}, valid.data.instructions);
-	const warnings = [...checked.warnings, ...assembled.warnings];
-	if (!assembled.ok) return {
+	const provider = llm?.provider === void 0 ? DEFAULT_PROVIDER : parseLenientProvider(llm.provider);
+	if (!provider) return {
 		ok: false,
-		errors: assembled.errors,
-		warnings
+		message: "This writing activity uses an unsupported llm.provider (use \"SCCH\" or \"Azure Foundry\")."
+	};
+	const instructions = asString(root.instructions);
+	if (!instructions) return {
+		ok: false,
+		message: "This writing activity has no instructions for the assistant."
 	};
 	return {
-		...checked,
-		warnings
+		ok: true,
+		writing: {
+			id: asString(root.id) ?? asString(root.name) ?? "writing",
+			name: asString(root.name) ?? "writing",
+			title: asString(root.title),
+			description: asString(root.description),
+			anonymous: asBool(root.anonymous, false),
+			model,
+			provider,
+			instructions,
+			fragmentBlock: readFragmentBlock(root),
+			placeholder: asString(root.placeholder)
+		}
 	};
 }
 //#endregion
-//#region src/file-fetcher.ts
-const cliFetcher = async (url) => {
-	if (url.startsWith("file:")) try {
-		const text = await readFile(fileURLToPath(url), "utf8");
-		return {
-			ok: true,
-			status: 200,
-			text: async () => text
+//#region ../lib/writing-resolve.ts
+const DEFAULT_SCHEMES = ["http:", "https:"];
+function schemeAllowed(url, allowed) {
+	try {
+		return allowed.includes(new URL(url).protocol);
+	} catch {
+		return false;
+	}
+}
+/**
+* Resolve a leniently parsed writing activity into the runnable one. `url` is the
+* activity's own URL (the base for relative fragment refs); `fetcher` the network seam.
+*/
+async function resolveWriting(writing, url, fetcher, opts = {}) {
+	const resolved = await assembleFragmentPrompt(writing.fragmentBlock, url, fetcher, {
+		validateLibraries: false,
+		allowedSchemes: opts.allowedSchemes ?? DEFAULT_SCHEMES
+	}, writing.instructions);
+	if (!resolved.ok) return {
+		ok: false,
+		message: "This writing activity's prompt fragments could not be loaded."
+	};
+	return {
+		ok: true,
+		writing: {
+			...writing,
+			fragmentBlock: EMPTY_FRAGMENT_BLOCK,
+			instructions: resolved.prompt
+		}
+	};
+}
+/**
+* Fetch + lenient-parse + `resolveWriting`, all through the CALLER's fetcher — the
+* app-free counterpart of `loadWriting` (`lib/writing-fetch.ts`) used by the prompt dump
+* and the CLI, where there is no database and an activity may live on disk (`file:`).
+*/
+async function loadWritingFrom(url, fetcher, opts = {}) {
+	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_SCHEMES;
+	if (!schemeAllowed(url, allowedSchemes)) return {
+		ok: false,
+		message: `This writing activity's URL is not allowed: ${url}`
+	};
+	try {
+		const res = await fetcher(url);
+		if (!res.ok) return res.status === 404 ? {
+			ok: false,
+			message: "This writing activity could not be found."
+		} : {
+			ok: false,
+			message: `This writing activity could not be loaded (HTTP ${res.status}).`
 		};
+		const parsed = parseWriting(await res.text());
+		if (!parsed.ok) return parsed;
+		return await resolveWriting(parsed.writing, url, fetcher, { allowedSchemes });
 	} catch {
 		return {
 			ok: false,
-			status: 404,
-			text: async () => ""
+			message: "This writing activity could not be loaded. Try again."
 		};
 	}
-	return defaultFetcher(url);
-};
-//#endregion
-//#region src/format.ts
-const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
-const paint = (code, s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : s;
-const green = (s) => paint("32", s);
-const red = (s) => paint("31", s);
-const yellow = (s) => paint("33", s);
-const dim = (s) => paint("2", s);
-/** Append the context fields an error/warning carries, when present. */
-function context(item) {
-	const parts = [];
-	if (item.fileAlias) parts.push(`file=${item.fileAlias}`);
-	if (item.fragmentId) parts.push(`fragment=${item.fragmentId}`);
-	if ("questionId" in item && item.questionId) parts.push(`question=${item.questionId}`);
-	if (item.variable) parts.push(`variable=${item.variable}`);
-	if ("url" in item && item.url) parts.push(`url=${item.url}`);
-	if ("expectedType" in item && item.expectedType) parts.push(`expected=${item.expectedType}`);
-	if ("actualType" in item && item.actualType) parts.push(`actual=${item.actualType}`);
-	return parts.length ? dim(` (${parts.join(", ")})`) : "";
 }
-function renderWarnings(warnings) {
-	return warnings.map((w) => `  ${yellow("⚠")} ${yellow(w.code)} ${w.message}${context(w)}`);
+//#endregion
+//#region ../lib/prompt-dump.ts
+const PROMPT_KINDS = [
+	"tutor",
+	"quiz",
+	"writing",
+	"coding"
+];
+/** Wrap a runtime loader's friendly message as the structured failure shape. */
+function loadFailed(message, url) {
+	return {
+		ok: false,
+		errors: [error("ACTIVITY_LOAD_FAILED", message, { url })]
+	};
 }
 /**
-* Render each error as a line, with any flattened Zod schema-issue detail
+* The verdict schema as plain JSON Schema, generated from the zod source of truth with
+* zod 4's native converter — the same mechanism `lib/schema-gen` uses for the authoring
+* schemas, so there is no second conversion story in the repo.
+*/
+function verdictResponseJsonSchema() {
+	return z.toJSONSchema(QUIZ_VERDICT_SCHEMA, { target: "draft-2020-12" });
+}
+/** The seam: one dumper per prompt-producing `FileKind`. */
+const promptDumpers = {
+	tutor: { async dump(url, fetcher, opts = {}) {
+		const result = await loadAndBuildTutorPrompt(url, fetcher, opts);
+		if (!result.ok) return {
+			ok: false,
+			errors: result.errors
+		};
+		return {
+			ok: true,
+			dump: {
+				kind: "tutor",
+				id: result.id,
+				llm: {
+					provider: result.provider,
+					model: result.model
+				},
+				system: result.prompt
+			}
+		};
+	} },
+	quiz: { async dump(url, fetcher, opts = {}) {
+		const loaded = await loadQuizFrom(url, fetcher, { allowedSchemes: opts.allowedSchemes });
+		if (!loaded.ok) return loadFailed(loaded.message, url);
+		const quiz = loaded.quiz;
+		return {
+			ok: true,
+			dump: {
+				kind: "quiz",
+				id: quiz.id,
+				llm: {
+					provider: quiz.provider,
+					model: quiz.model
+				},
+				grading: {
+					userMessageTemplate: QUIZ_ANSWER_MESSAGE_TEMPLATE,
+					userMessagePhotosOnly: QUIZ_ANSWER_PHOTOS_ONLY_MESSAGE,
+					responseSchema: verdictResponseJsonSchema(),
+					questions: quiz.questions.map((question) => ({
+						id: question.id,
+						...question.title ? { title: question.title } : {},
+						system: buildGradingPrompt(question, quiz.instructionsPreamble),
+						imageInput: effectiveImageInput(quiz, question)
+					}))
+				},
+				discussion: {
+					system: buildDiscussionInstructions(quiz),
+					seedMessages: {
+						question: QUIZ_SEED_QUESTION_TEMPLATE,
+						answer: "{answer}",
+						verdict: QUIZ_SEED_VERDICT_TEMPLATE
+					},
+					verdictLabels: {
+						correct: verdictLabel("correct"),
+						partial: verdictLabel("partial"),
+						incorrect: verdictLabel("incorrect")
+					}
+				}
+			}
+		};
+	} },
+	writing: { async dump(url, fetcher, opts = {}) {
+		const loaded = await loadWritingFrom(url, fetcher, { allowedSchemes: opts.allowedSchemes });
+		if (!loaded.ok) return loadFailed(loaded.message, url);
+		const writing = loaded.writing;
+		return {
+			ok: true,
+			dump: {
+				kind: "writing",
+				id: writing.id,
+				llm: {
+					provider: writing.provider,
+					model: writing.model
+				},
+				system: writing.instructions
+			}
+		};
+	} },
+	coding: { async dump(url, fetcher, opts = {}) {
+		const loaded = await loadCodingFrom(url, fetcher, { allowedSchemes: opts.allowedSchemes });
+		if (!loaded.ok) return loadFailed(loaded.message, url);
+		const coding = loaded.coding;
+		const upstream = buildUpstreamChatBody({ messages: [] }, {
+			instructions: coding.instructions,
+			model: coding.model
+		});
+		const system = (Array.isArray(upstream.messages) ? upstream.messages : []).find((m) => typeof m === "object" && m !== null && m.role === "system");
+		return {
+			ok: true,
+			dump: {
+				kind: "coding",
+				id: coding.id,
+				llm: {
+					provider: coding.provider,
+					model: coding.model
+				},
+				system: coding.instructions,
+				upstreamSystemMessage: typeof system?.content === "string" ? system.content : ""
+			}
+		};
+	} }
+};
+/** Dump the prompts of ONE activity file — the single entry point callers use. */
+function dumpPrompts(kind, url, fetcher, opts = {}) {
+	return promptDumpers[kind].dump(url, fetcher, opts);
+}
+/**
+* The dump's prompts as a flat, kind-agnostic list — what a summary renderer walks so it
+* never has to switch on the kind. Order is stable (and, for a quiz, question order).
+*/
+function promptSections(dump) {
+	switch (dump.kind) {
+		case "quiz": return [...dump.grading.questions.map((q) => ({
+			name: `grading: ${q.id}`,
+			text: q.system
+		})), {
+			name: "discussion",
+			text: dump.discussion.system
+		}];
+		case "coding": return [{
+			name: "system (injected upstream)",
+			text: dump.system
+		}];
+		default: return [{
+			name: "system",
+			text: dump.system
+		}];
+	}
+}
+//#endregion
+//#region ../lib/quiz-schema.ts
+/**
+* A live quiz include: alias + URL, mirroring `FragmentFileRefSchema` (same URL
+* contract). The alias prefixes every imported question id as `"<alias>/<id>"`, so
+* on top of the no-dot rule it may not contain a `/` either. Aliases live in their
+* OWN namespace (they never appear in `{{…}}` markers — only in question ids).
+*/
+const QuizFileRefSchema = z.strictObject({
+	id: z.string().regex(/^[^./]+$/, { message: "Alias must not contain a dot or a slash" }).meta({
+		pattern: "^[^./]+$",
+		description: "Local alias for this included quiz. Prefixes every imported question id as \"<alias>/<id>\", so it may not contain a dot or a slash."
+	}),
+	url: FragmentFileRefSchema.shape.url.meta({
+		pattern: "^(https?://|(?![A-Za-z][A-Za-z0-9+.-]*:).+)$",
+		description: "HTTP(S) URL or relative path to the included quiz file."
+	})
+}).meta({
+	id: "quizFileRef",
+	description: "A reference to another quiz file whose questions are included live."
+});
+/** An optional content image attached to a question (carries no secret). */
+const ImageRefSchema = z.strictObject({
+	hosted: z.boolean().optional().meta({
+		default: false,
+		description: "When true, src is an app-hosted image NAME resolved server-side; otherwise src is an absolute URL or a path relative to the quiz's own URL."
+	}),
+	src: z.string().min(1).meta({ description: "The hosted image name (when hosted) or the image URL / relative path." }),
+	alt: z.string().optional().meta({ description: "Accessible description shown if the image cannot be loaded." }),
+	credit: z.string().optional().meta({ description: "Optional attribution (\"Content Credentials\") shown small below the image." })
+}).meta({
+	id: "image",
+	description: "An optional content image attached to a question."
+});
+/**
+* One question. `id` keys the per-question stats (must be unique — see
+* `lib/quiz-validate.ts`); `question` is the Markdown shown to the student;
+* `evaluation` is the server-only grading prompt.
+*/
+const QuizQuestionSchema = z.strictObject({
+	id: z.string().min(1).meta({ description: "Stable question id, unique within the quiz (the per-question stats key)." }),
+	title: z.string().optional().meta({ description: "Optional short label for the stats table and progress display." }),
+	question: z.string().min(1).meta({ description: "The Markdown shown to the student." }),
+	evaluation: z.string().min(1).meta({ description: "The grading prompt. SERVER-ONLY: never sent to the browser, so it may embed the expected answer and the grading rubric." }),
+	image: ImageRefSchema.optional(),
+	imageInput: z.boolean().optional().meta({ description: "Overrides the quiz-level llm.imageInput for this question only (photo answers on/off)." })
+}).meta({
+	id: "question",
+	description: "One open-ended, LLM-graded quiz question."
+});
+const QuizYamlSchema = z.strictObject({
+	id: z.string().min(1).meta({ description: "Short machine-readable quiz id, e.g. countries-basics. Used as the per-quiz identity." }),
+	name: z.string().optional().meta({ description: "Optional human-readable quiz title (used as a label)." }),
+	title: z.string().optional().meta({ description: "Optional greeting shown to students on the welcome screen instead of the default message." }),
+	description: z.string().optional().meta({ description: "Optional description shown to students below the welcome greeting (Markdown)." }),
+	anonymous: z.boolean().optional().meta({
+		default: true,
+		description: "Quizzes are anonymous by default: answers are recorded for aggregate stats but not linked to a student. Set to false to attribute each attempt to the signed-in student."
+	}),
+	shuffle: z.boolean().optional().meta({
+		default: true,
+		description: "Present questions in a random order per attempt. Set to false to keep the authored order."
+	}),
+	question_count: z.number().int().min(1).optional().meta({ description: "How many questions one attempt asks (default: every question exactly once). May exceed the pool size — then questions repeat (drill mode). With shuffle off, fewer than the pool means the first N in authored order." }),
+	quiz_files: z.array(QuizFileRefSchema).default([]).meta({ description: "Other quiz files whose questions are ALL included live into this quiz (a compound/final quiz). One level deep — an included quiz may not itself declare quiz_files." }),
+	llm: z.strictObject({
+		model: z.string().min(1).meta({ description: "The model that grades answers and drives the per-question discussion chat." }),
+		provider: providerSchema,
+		imageInput: z.boolean().optional().meta({
+			default: false,
+			description: "Default for all questions: students may attach photos (up to 3, 5 MB each) to their answers. The model must be vision-capable. A per-question imageInput overrides it."
+		})
+	}).meta({
+		id: "llm",
+		description: "The single model + provider that grades and discusses answers."
+	}),
+	discussion: z.strictObject({ instructions: z.string().min(1).meta({ description: "Optional guidance appended to the per-question follow-up discussion chat's system prompt. When any fragment_files or text_files are declared, place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (escape a literal {{ as \\{{) — same rules as instructions." }) }).optional().meta({
+		id: "discussion",
+		description: "Optional guidance for the per-question follow-up discussion chat."
+	}),
+	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this quiz pulls shared prompt fragments from." }),
+	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
+	instructions: z.string().optional().meta({ description: "Optional quiz-level preamble prepended to BOTH the grader prompt and the discussion chat. When any fragment_files or text_files are declared, place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." }),
+	questions: z.array(QuizQuestionSchema).default([]).meta({ description: "The quiz questions. Each is open-ended and graded by the LLM via its evaluation prompt. May be omitted when quiz_files supplies the questions." })
+});
+//#endregion
+//#region ../lib/quiz-validate.ts
+/** Quizzes default to anonymous — answers are recorded for stats but not attributed. */
+const DEFAULT_ANONYMOUS$1 = true;
+/** Question ids declared on more than one question (the per-question stats key). */
+function findDuplicateQuestionIds(quiz) {
+	const errors = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const question of quiz.questions) {
+		if (seen.has(question.id)) {
+			errors.push(error("DUPLICATE_QUIZ_QUESTION_ID", `Question id "${question.id}" is declared more than once`, { questionId: question.id }));
+			continue;
+		}
+		seen.add(question.id);
+	}
+	return errors;
+}
+/**
+* Own question ids containing `/` — reserved as the namespace delimiter for
+* questions imported via `quiz_files` (`"<alias>/<id>"`), so an own id can never
+* collide with (or masquerade as) an imported one.
+*/
+function findReservedSlashIds(quiz) {
+	return quiz.questions.filter((question) => question.id.includes("/")).map((question) => error("QUIZ_QUESTION_ID_RESERVED_SLASH", `Question id "${question.id}" contains "/" — reserved for questions imported via quiz_files`, { questionId: question.id }));
+}
+/** Include aliases declared on more than one `quiz_files` entry. */
+function findDuplicateIncludeAliases(quiz) {
+	const errors = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const ref of quiz.quiz_files) {
+		if (seen.has(ref.id)) {
+			errors.push(error("DUPLICATE_QUIZ_INCLUDE_ALIAS", `Included-quiz alias "${ref.id}" is declared more than once`, { fileAlias: ref.id }));
+			continue;
+		}
+		seen.add(ref.id);
+	}
+	return errors;
+}
+/**
+* Check an already-schema-validated quiz: unique question ids, no reserved `/` ids,
+* unique include aliases, and a non-empty (potential) pool → metadata. Split from
+* `checkQuizValue` so `loadAndCheckQuiz` can reuse the single `validate` it already ran
+* (no second parse of the same document against the same schema).
+*/
+function checkQuizParsed(quiz) {
+	const errors = [
+		...findDuplicateQuestionIds(quiz),
+		...findReservedSlashIds(quiz),
+		...findDuplicateIncludeAliases(quiz)
+	];
+	if (quiz.questions.length === 0 && quiz.quiz_files.length === 0) errors.push(error("QUIZ_NO_QUESTIONS", "This quiz has no questions and no quiz_files includes"));
+	if (errors.length > 0) return {
+		ok: false,
+		errors,
+		warnings: []
+	};
+	return {
+		ok: true,
+		quizId: quiz.id,
+		model: quiz.llm.model,
+		provider: quiz.llm.provider,
+		questionCount: quiz.questions.length,
+		anonymous: quiz.anonymous ?? DEFAULT_ANONYMOUS$1,
+		title: quiz.title ?? null,
+		warnings: []
+	};
+}
+/** Wrap an include's nested failures into ONE error carrying the alias + URL. */
+function includeUnreadable(alias, url, nested) {
+	return error("QUIZ_INCLUDE_UNREADABLE", `Included quiz "${alias}" is not usable: ${nested.map((e) => e.message).join("; ")}`, url === void 0 ? { fileAlias: alias } : {
+		fileAlias: alias,
+		url
+	});
+}
+/**
+* Deep-check ONE `quiz_files` include: resolve + fetch + parse + the FULL strict
+* quiz check (schema, consistency passes, its own fragment-block authoring gate),
+* plus the one-level rule (`QUIZ_INCLUDE_NESTED`). Every other failure is wrapped
+* as `QUIZ_INCLUDE_UNREADABLE` with the alias + resolved URL.
+*/
+async function checkInclude(ref, baseUrl, fetchImpl, opts) {
+	let includeUrl;
+	try {
+		includeUrl = resolveFragmentUrl(ref.url, baseUrl);
+	} catch {
+		return {
+			ok: false,
+			errors: [includeUnreadable(ref.id, void 0, [error("INVALID_URL", `Invalid include URL: ${ref.url}`)])],
+			warnings: []
+		};
+	}
+	const yaml = await loadYaml(includeUrl, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, [yaml.error])],
+		warnings: []
+	};
+	const valid = validate(yaml.value, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", includeUrl);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, [valid.error])],
+		warnings: []
+	};
+	if (valid.data.quiz_files.length > 0) return {
+		ok: false,
+		errors: [error("QUIZ_INCLUDE_NESTED", `Included quiz "${ref.id}" itself declares quiz_files — includes are one level deep`, {
+			fileAlias: ref.id,
+			url: includeUrl
+		})],
+		warnings: []
+	};
+	const checked = checkQuizParsed(valid.data);
+	if (!checked.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, checked.errors)],
+		warnings: checked.warnings
+	};
+	const assembled = await assembleFragmentPrompts({
+		fragment_files: valid.data.fragment_files,
+		text_files: valid.data.text_files
+	}, includeUrl, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	}, [valid.data.instructions ?? "", valid.data.discussion?.instructions ?? ""]);
+	if (!assembled.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, assembled.errors)],
+		warnings: assembled.warnings
+	};
+	return {
+		ok: true,
+		questionCount: valid.data.questions.length,
+		warnings: assembled.warnings
+	};
+}
+/**
+* Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), the pure
+* `checkQuizValue`, the document-level fragment block's authoring gate — fetch
+* every referenced library, run the THOROUGH whole-library check, consistency, and an
+* assembly dry-run (the strict-Handlebars backstop) — and a DEEP check of every
+* `quiz_files` include. On success `questionCount` is the RESOLVED pool size
+* (own + imported), so the `/files` save UI and code-create metadata reflect the
+* real exam size. The web app passes the default http(s)-only schemes; the CLI adds
+* `file:` so a local quiz YAML on disk validates too.
+*/
+async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
+	const yaml = await loadYaml(url, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [yaml.error],
+		warnings: []
+	};
+	const valid = validate(yaml.value, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkQuizParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompts({
+		fragment_files: valid.data.fragment_files,
+		text_files: valid.data.text_files
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	}, [valid.data.instructions ?? "", valid.data.discussion?.instructions ?? ""]);
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	const includes = await Promise.all(valid.data.quiz_files.map((ref) => checkInclude(ref, url, fetchImpl, opts)));
+	const includeErrors = [];
+	let importedCount = 0;
+	for (const include of includes) {
+		warnings.push(...include.warnings);
+		if (include.ok) importedCount += include.questionCount;
+		else includeErrors.push(...include.errors);
+	}
+	if (includeErrors.length > 0) return {
+		ok: false,
+		errors: includeErrors,
+		warnings
+	};
+	return {
+		...checked,
+		questionCount: checked.questionCount + importedCount,
+		warnings
+	};
+}
+//#endregion
+//#region ../lib/eval-validate.ts
+function fail(errors, warnings = []) {
+	return {
+		ok: false,
+		errors,
+		warnings
+	};
+}
+/** Zod issues as one error each, the dotted path leading the message. */
+function schemaErrors(issues, url) {
+	return issues.map((issue) => {
+		const path = issue.path.map((segment) => String(segment)).join(".");
+		return error("EVAL_SCHEMA", path ? `${path}: ${issue.message}` : issue.message, { url });
+	});
+}
+/**
+* Check ONE eval file end to end. `fetcher` is the caller's network seam and
+* `allowedSchemes` the usual SSRF gate (the CLI adds `file:` so an on-disk eval
+* resolves the quiz sitting next to it).
+*/
+async function loadAndCheckEval(url, fetchImpl, opts = {}) {
+	const allowedSchemes = opts.allowedSchemes;
+	const yaml = await loadYaml(url, fetchImpl, { allowedSchemes });
+	if (!yaml.ok) return fail([error(yaml.error.code === "YAML_PARSE_ERROR" ? "EVAL_PARSE" : "EVAL_READ", yaml.error.message, { url })]);
+	const parsed = EvalYamlSchema.safeParse(yaml.value);
+	if (!parsed.success) return fail(schemaErrors(parsed.error.issues, url));
+	const evalFile = parsed.data;
+	let targetUrl;
+	try {
+		targetUrl = new URL(evalFile.target, url).href;
+	} catch {
+		return fail([error("EVAL_TARGET_ERROR", `The target "${evalFile.target}" is not a usable URL.`, { url })]);
+	}
+	if (allowedSchemes !== void 0) {
+		let scheme = "";
+		try {
+			scheme = new URL(targetUrl).protocol;
+		} catch {
+			scheme = "";
+		}
+		if (!allowedSchemes.includes(scheme)) return fail([error("EVAL_TARGET_ERROR", `The target URL is not allowed: ${targetUrl}`, { url: targetUrl })]);
+	}
+	const warnings = [];
+	if (opts.strictTarget) {
+		const strict = await loadAndCheckQuiz(targetUrl, fetchImpl, {
+			allowedSchemes,
+			validateLibraries: opts.validateLibraries ?? true
+		});
+		warnings.push(...strict.warnings);
+		if (!strict.ok) return fail(strict.errors, warnings);
+	}
+	const dumped = await dumpPrompts("quiz", targetUrl, fetchImpl, { allowedSchemes });
+	if (!dumped.ok) return fail(dumped.errors.map((e) => error("EVAL_TARGET_ERROR", `The target quiz could not be loaded: ${e.message}`, { url: targetUrl })), warnings);
+	const quizDump = dumped.dump;
+	if (quizDump.kind !== "quiz") return fail([error("EVAL_TARGET_ERROR", "The target is not a quiz.", { url: targetUrl })], warnings);
+	const known = new Set(quizDump.grading.questions.map((question) => question.id));
+	const unknown = evalFile.questions.filter((question) => !known.has(question.question)).map((question) => error("EVAL_UNKNOWN_QUESTION", `The target quiz has no question "${question.question}".`, {
+		questionId: question.question,
+		url: targetUrl
+	}));
+	if (unknown.length > 0) return fail(unknown, warnings);
+	const resolved = await loadQuizFrom(targetUrl, fetchImpl, { allowedSchemes });
+	const quizQuestions = resolved.ok ? resolved.quiz.questions.map((question) => ({
+		id: question.id,
+		text: question.question
+	})) : [];
+	return {
+		ok: true,
+		evalFile,
+		targetUrl,
+		quizDump,
+		quizQuestions,
+		caseCount: evalFile.questions.reduce((sum, question) => sum + question.answers.length, 0),
+		warnings
+	};
+}
+//#endregion
+//#region src/retry.ts
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Runs `work` up to `attempts` times, waiting a LINEARLY growing delay between tries
+* (the shape the Python PoC used against SCCH's occasional 504s). Returns the first
+* outcome `shouldRetry` rejects, or the last outcome when the budget runs out.
+*/
+async function withRetry(work, options) {
+	const attempts = Math.max(1, options.attempts ?? 4);
+	const baseDelayMs = options.baseDelayMs ?? 5e3;
+	const sleep = options.sleep ?? defaultSleep;
+	let last;
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		if (attempt > 1) await sleep(baseDelayMs * (attempt - 1));
+		last = await work(attempt);
+		if (!options.shouldRetry(last)) return last;
+	}
+	return last;
+}
+/**
+* Maps `items` through `fn` with at most `limit` in flight, preserving INPUT order in
+* the result (a worker pool, not `Promise.all` in chunks — a slow item never stalls the
+* pool behind it). `fn` receives the item's original index so callers can report
+* progress meaningfully.
+*/
+async function mapWithConcurrency(items, limit, fn) {
+	const results = new Array(items.length);
+	const workers = Math.max(1, Math.min(Math.floor(limit) || 1, items.length));
+	let next = 0;
+	async function worker() {
+		for (;;) {
+			const index = next++;
+			if (index >= items.length) return;
+			results[index] = await fn(items[index], index);
+		}
+	}
+	await Promise.all(Array.from({ length: workers }, () => worker()));
+	return results;
+}
+//#endregion
+//#region src/eval-run.ts
+const ZERO_USAGE = {
+	input: 0,
+	cachedInput: 0,
+	output: 0
+};
+/** Add one call's usage into an accumulator (mutating it — internal to the sums below). */
+function addUsage(total, usage) {
+	if (!usage) return;
+	total.input += usage.input;
+	total.cachedInput += usage.cachedInput;
+	total.output += usage.output;
+}
+/** Consecutive fully-errored cases that mean "the server is down, stop now". */
+const CIRCUIT_BREAKER_LIMIT = 3;
+/** Flatten questions × answers into cases, each carrying its grading prompt. */
+function planCases(checked) {
+	const systemById = new Map(checked.quizDump.grading.questions.map((question) => [question.id, question.system]));
+	const cases = [];
+	for (const question of checked.evalFile.questions) question.answers.forEach((answer, answerIndex) => {
+		cases.push({
+			questionId: question.question,
+			answerIndex,
+			expected: normalizeExpect(answer.expect),
+			answer: answer.answer,
+			system: systemById.get(question.question)
+		});
+	});
+	return cases;
+}
+/**
+* The majority verdict over the graded repeats. Returns the winner plus whether the
+* case PASSES: a unique majority passes when it is expected; a TIE passes only when
+* every tied verdict is expected (so a coin-flip between two acceptable gradings is a
+* pass, and one between an acceptable and an unacceptable one is not).
+*/
+function majority(graded, expected) {
+	if (graded.length === 0) return void 0;
+	const counts = /* @__PURE__ */ new Map();
+	for (const verdict of graded) counts.set(verdict, (counts.get(verdict) ?? 0) + 1);
+	const top = Math.max(...counts.values());
+	const tied = [...counts.entries()].filter(([, count]) => count === top).map(([verdict]) => verdict).sort((a, b) => EVAL_VERDICTS.indexOf(a) - EVAL_VERDICTS.indexOf(b));
+	return {
+		verdict: tied[0],
+		passed: tied.every((verdict) => expected.includes(verdict))
+	};
+}
+/** The seam: one runner per eval kind (mirrors `promptDumpers`). */
+const evalRunners = { quiz: { async run(checked, options) {
+	const repeats = Math.max(1, Math.floor(options.repeats ?? 1));
+	const concurrency = Math.max(1, Math.floor(options.concurrency ?? 4));
+	const planned = planCases(checked);
+	const total = planned.length * repeats;
+	const questionTexts = new Map(checked.quizQuestions.map((q) => [q.id, q.text]));
+	let done = 0;
+	let consecutiveErrored = 0;
+	let aborted;
+	const progress = () => {
+		done += 1;
+		options.onProgress?.({
+			done,
+			total
+		});
+	};
+	const results = await mapWithConcurrency(planned, concurrency, async (plan) => {
+		const rows = [];
+		for (let repeatIndex = 0; repeatIndex < repeats; repeatIndex++) {
+			if (aborted) break;
+			if (plan.system === void 0) {
+				rows.push({
+					repeatIndex,
+					error: { message: `The quiz has no question "${plan.questionId}".` }
+				});
+				progress();
+				continue;
+			}
+			const outcome = await withRetry(() => options.grade({
+				system: plan.system,
+				answer: plan.answer
+			}), {
+				attempts: options.retry?.attempts,
+				baseDelayMs: options.retry?.baseDelayMs,
+				sleep: options.retry?.sleep,
+				shouldRetry: (value) => !value.ok && value.retryable && value.auth !== true
+			});
+			progress();
+			if (outcome.ok) {
+				rows.push({
+					repeatIndex,
+					got: outcome.verdict,
+					feedback: outcome.feedback,
+					...outcome.usage ? { usage: outcome.usage } : {}
+				});
+				continue;
+			}
+			rows.push({
+				repeatIndex,
+				error: outcome.error
+			});
+			if (outcome.auth) {
+				aborted ??= {
+					reason: "auth",
+					message: "Authentication failed — the run was aborted. Run `novedu-cli login`."
+				};
+				break;
+			}
+		}
+		const graded = rows.flatMap((row) => row.got ? [row.got] : []);
+		const winner = majority(graded, plan.expected);
+		const status = rows.length === 0 ? "skipped" : !winner ? "errored" : winner.passed ? "passed" : "failed";
+		if (status === "errored") {
+			consecutiveErrored += 1;
+			if (consecutiveErrored >= CIRCUIT_BREAKER_LIMIT) aborted ??= {
+				reason: "circuit-breaker",
+				message: `${CIRCUIT_BREAKER_LIMIT} cases failed in a row — the run was aborted.`
+			};
+		} else if (status !== "skipped") consecutiveErrored = 0;
+		return {
+			questionId: plan.questionId,
+			answerIndex: plan.answerIndex,
+			expected: plan.expected,
+			answer: plan.answer,
+			status,
+			...winner ? { verdict: winner.verdict } : {},
+			unstable: new Set(graded).size > 1,
+			repeats: rows
+		};
+	});
+	const usage = { ...ZERO_USAGE };
+	for (const result of results) for (const row of result.repeats) addUsage(usage, row.usage);
+	const totals = {
+		cases: results.length,
+		passed: results.filter((c) => c.status === "passed").length,
+		failed: results.filter((c) => c.status === "failed").length,
+		errored: results.filter((c) => c.status === "errored").length,
+		skipped: results.filter((c) => c.status === "skipped").length,
+		unstable: results.filter((c) => c.unstable).length,
+		repeats,
+		calls: total,
+		usage
+	};
+	const confusionCounts = /* @__PURE__ */ new Map();
+	for (const result of results) {
+		if (!result.verdict) continue;
+		const key = `${expectedKey(result.expected)}${result.verdict}`;
+		confusionCounts.set(key, (confusionCounts.get(key) ?? 0) + 1);
+	}
+	const confusion = [...confusionCounts.entries()].map(([key, count]) => {
+		const [expected = "", got = ""] = key.split("\0");
+		return {
+			expected,
+			got,
+			count
+		};
+	}).sort((a, b) => a.expected.localeCompare(b.expected) || a.got.localeCompare(b.got));
+	const strictCases = results.filter((result) => !result.expected.includes("correct"));
+	const falseCorrectCount = strictCases.filter((result) => result.verdict === "correct").length;
+	return {
+		id: checked.evalFile.id,
+		target: checked.targetUrl,
+		llm: options.llm,
+		totals,
+		questions: [...new Set(checked.evalFile.questions.map((question) => question.question))].map((id) => ({
+			id,
+			text: questionTexts.get(id) ?? ""
+		})),
+		mismatches: results.filter((result) => result.status === "failed" || result.status === "errored"),
+		cases: results,
+		confusion,
+		falseCorrect: {
+			count: falseCorrectCount,
+			denominator: strictCases.length,
+			rate: strictCases.length === 0 ? 0 : falseCorrectCount / strictCases.length
+		},
+		...aborted ? { aborted } : {}
+	};
+} } };
+/** Run ONE checked eval file — the single entry point the command uses. */
+function runEval(kind, checked, options) {
+	return evalRunners[kind].run(checked, options);
+}
+/** One file's own verdict: valid, graded, and not a single non-passing case. */
+function filePassed(file) {
+	if (file.status === "invalid" || !file.result) return false;
+	const { failed, errored, skipped } = file.result.totals;
+	return failed === 0 && errored === 0 && skipped === 0;
+}
+/**
+* Grand totals across a batch. This is the ONE machine-readable shape `--json` /
+* `--out` emit, single file or not, so scripts never branch on the file count.
+*/
+function summarizeBatch(files) {
+	const totals = {
+		files: files.length,
+		invalid: files.filter((file) => file.status === "invalid").length,
+		cases: 0,
+		passed: 0,
+		failed: 0,
+		errored: 0,
+		skipped: 0,
+		unstable: 0,
+		usage: { ...ZERO_USAGE }
+	};
+	for (const file of files) {
+		if (!file.result) continue;
+		totals.cases += file.result.totals.cases;
+		totals.passed += file.result.totals.passed;
+		totals.failed += file.result.totals.failed;
+		totals.errored += file.result.totals.errored;
+		totals.skipped += file.result.totals.skipped;
+		totals.unstable += file.result.totals.unstable;
+		addUsage(totals.usage, file.result.totals.usage);
+	}
+	return {
+		files: files.map((file) => ({
+			...file,
+			passed: filePassed(file)
+		})),
+		passed: batchPassed({ totals }),
+		totals
+	};
+}
+/**
+* The CI gate: every file valid, and not a single failed, errored, or skipped CASE —
+* an aborted (and therefore incomplete) run must never read as a pass. The single
+* source of truth for the exit code AND for `EvalBatchResult.passed`.
+*/
+function batchPassed(batch) {
+	return batch.totals.invalid === 0 && batch.totals.failed === 0 && batch.totals.errored === 0 && batch.totals.skipped === 0;
+}
+//#endregion
+//#region src/file-fetcher.ts
+const cliFetcher = async (url) => {
+	if (url.startsWith("file:")) try {
+		const text = await readFile(fileURLToPath(url), "utf8");
+		return {
+			ok: true,
+			status: 200,
+			text: async () => text
+		};
+	} catch {
+		return {
+			ok: false,
+			status: 404,
+			text: async () => ""
+		};
+	}
+	return defaultFetcher(url);
+};
+//#endregion
+//#region src/format.ts
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code, s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : s;
+const green = (s) => paint("32", s);
+const red = (s) => paint("31", s);
+const yellow = (s) => paint("33", s);
+const dim = (s) => paint("2", s);
+/** Append the context fields an error/warning carries, when present. */
+function context(item) {
+	const parts = [];
+	if (item.fileAlias) parts.push(`file=${item.fileAlias}`);
+	if (item.fragmentId) parts.push(`fragment=${item.fragmentId}`);
+	if ("questionId" in item && item.questionId) parts.push(`question=${item.questionId}`);
+	if (item.variable) parts.push(`variable=${item.variable}`);
+	if ("url" in item && item.url) parts.push(`url=${item.url}`);
+	if ("expectedType" in item && item.expectedType) parts.push(`expected=${item.expectedType}`);
+	if ("actualType" in item && item.actualType) parts.push(`actual=${item.actualType}`);
+	return parts.length ? dim(` (${parts.join(", ")})`) : "";
+}
+function renderWarnings(warnings) {
+	return warnings.map((w) => `  ${yellow("⚠")} ${yellow(w.code)} ${w.message}${context(w)}`);
+}
+/**
+* Render each error as a line, with any flattened Zod schema-issue detail
 * indented beneath it — so a generic "Document does not match the expected
 * structure" is followed by the actual field paths (e.g. `Unrecognized key:
 * "nae"`), matching what the web UI shows.
 */
-function renderErrors(errors) {
+function renderErrors(errors) {
+	const lines = [];
+	for (const e of errors) {
+		lines.push(`  ${red("✗")} ${red(e.code)} ${e.message}${context(e)}`);
+		if (e.zodIssues) for (const issue of formatZodIssues(e.zodIssues)) lines.push(`      ${dim(issue)}`);
+	}
+	return lines;
+}
+function formatResult(result, source) {
+	const lines = [];
+	if (result.ok) {
+		lines.push(green(`✔ Valid tutor`) + dim(` — ${source}`));
+		lines.push(`  model: ${result.model}`);
+		lines.push(`  system prompt: ${result.prompt.length} chars`);
+		lines.push(`  imageInput: ${result.imageInput}   anonymous: ${result.anonymous}` + (result.exampleQuestions.length ? `   exampleQuestions: ${result.exampleQuestions.length}` : ""));
+		if (result.warnings.length) {
+			lines.push("");
+			lines.push(yellow(`${result.warnings.length} warning(s):`));
+			lines.push(...renderWarnings(result.warnings));
+		}
+		return lines.join("\n");
+	}
+	lines.push(red(`✘ Invalid tutor`) + dim(` — ${source}`));
+	lines.push("");
+	lines.push(red(`${result.errors.length} error(s):`));
+	lines.push(...renderErrors(result.errors));
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
+/** Same renderer, for a standalone fragment-FILE check (`--kind fragment`). */
+function formatFragmentResult(result, source) {
+	const lines = [];
+	if (result.ok) {
+		lines.push(green(`✔ Valid fragment file`) + dim(` — ${source}`));
+		lines.push(`  id: ${result.fragmentFileId}`);
+		lines.push(`  fragments: ${result.fragmentIds.length}` + (result.fragmentIds.length ? ` (${result.fragmentIds.join(", ")})` : ""));
+		if (result.warnings.length) {
+			lines.push("");
+			lines.push(yellow(`${result.warnings.length} warning(s):`));
+			lines.push(...renderWarnings(result.warnings));
+		}
+		return lines.join("\n");
+	}
+	lines.push(red(`✘ Invalid fragment file`) + dim(` — ${source}`));
+	lines.push("");
+	lines.push(red(`${result.errors.length} error(s):`));
+	lines.push(...renderErrors(result.errors));
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
+/**
+* Shared tail for the quiz/writing renderers: on failure, the error list (with any
+* flattened Zod issues); plus any warnings on either branch.
+*/
+function renderFailureAndWarnings(result, label, source) {
+	const lines = [red(`✘ Invalid ${label}`) + dim(` — ${source}`), ""];
+	lines.push(red(`${result.errors.length} error(s):`));
+	lines.push(...renderErrors(result.errors));
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
+/** Renderer for a quiz check (`--kind quiz`). */
+function formatQuizResult(result, source) {
+	if (!result.ok) return renderFailureAndWarnings(result, "quiz", source);
+	const lines = [green(`✔ Valid quiz`) + dim(` — ${source}`)];
+	lines.push(`  id: ${result.quizId}`);
+	lines.push(`  model: ${result.model}`);
+	lines.push(`  questions: ${result.questionCount}   anonymous: ${result.anonymous}`);
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
+/** Renderer for a writing-activity check (`--kind writing`). */
+function formatWritingResult(result, source) {
+	if (!result.ok) return renderFailureAndWarnings(result, "writing activity", source);
+	const lines = [green(`✔ Valid writing activity`) + dim(` — ${source}`)];
+	lines.push(`  id: ${result.writingId}`);
+	lines.push(`  model: ${result.model}`);
+	lines.push(`  anonymous: ${result.anonymous}`);
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
+/**
+* Renderer for a coding-activity check (`--kind coding`). Coding is ALWAYS anonymous
+* (the API path carries no per-student identity), so — unlike quiz/writing — that is
+* shown as a fixed note, not a per-file value.
+*/
+function formatCodingResult(result, source) {
+	if (!result.ok) return renderFailureAndWarnings(result, "coding activity", source);
+	const lines = [green(`✔ Valid coding activity`) + dim(` — ${source}`)];
+	lines.push(`  id: ${result.codingId}`);
+	lines.push(`  model: ${result.model}`);
+	lines.push(`  anonymous: true ${dim("(always — the API path carries no identity)")}`);
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
+/**
+* Renderer for a golden-answer eval check (`--kind eval`). An eval describes a quiz it
+* does not contain, so the summary names the resolved target and the size of the run
+* the file would produce.
+*/
+function formatEvalResult(result, source) {
+	if (!result.ok) return renderFailureAndWarnings(result, "eval", source);
+	const lines = [green(`✔ Valid eval`) + dim(` — ${source}`)];
+	lines.push(`  id: ${result.evalFile.id}`);
+	lines.push(`  target: ${result.targetUrl}`);
+	lines.push(`  questions: ${result.evalFile.questions.length}   cases: ${result.caseCount}`);
+	lines.push(`  quiz model: ${result.quizDump.llm.provider} / ${result.quizDump.llm.model}`);
+	if (result.warnings.length) {
+		lines.push("");
+		lines.push(yellow(`${result.warnings.length} warning(s):`));
+		lines.push(...renderWarnings(result.warnings));
+	}
+	return lines.join("\n");
+}
+/** One-line answer snippet for a mismatch line (single-line, bounded). */
+function snippet(text, max = 60) {
+	const flat = text.replace(/\s+/g, " ").trim();
+	return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+/** Thousands-separated, en-US so a report reads the same on every machine. */
+function formatTokenCount(count) {
+	return count.toLocaleString("en-US");
+}
+/**
+* `tokens: 15,420 in (12,300 cached) / 2,810 out` — or `undefined` when nothing was
+* reported at all (no server usage, or none of the calls succeeded), in which case the
+* reports print no token line rather than a misleading row of zeros. The cached
+* parenthetical is dropped when the provider reported no cache reads. Counts SUCCESSFUL
+* grading calls only, so it is a lower bound (docs/cli-eval.md).
+*/
+function formatUsageLine(usage) {
+	if (usage.input === 0 && usage.cachedInput === 0 && usage.output === 0) return void 0;
+	const cached = usage.cachedInput ? ` (${formatTokenCount(usage.cachedInput)} cached)` : "";
+	return `tokens: ${formatTokenCount(usage.input)} in${cached} / ${formatTokenCount(usage.output)} out`;
+}
+/** `question#index expected … got … "answer…"` — one line per non-passing case. */
+function mismatchLines(result) {
+	return result.mismatches.map((c) => {
+		const head = `${c.questionId}#${c.answerIndex}`;
+		const expected = c.expected.join("|");
+		if (c.status === "errored") {
+			const first = c.repeats.find((row) => row.error !== void 0)?.error;
+			const message = typeof first === "object" && first !== null && "message" in first ? String(first.message) : "no verdict";
+			return `  ${red("✗")} ${head} expected ${expected} got ${red("error")} ${dim(message)}`;
+		}
+		return `  ${red("✗")} ${head} expected ${expected} got ${red(c.verdict ?? "?")}` + dim(` "${snippet(c.answer)}"`);
+	});
+}
+/**
+* The human report for ONE eval run: header (id, target, the EFFECTIVE llm — rendered
+* as `quiz-llm → override-llm` when `--llm-provider`/`--llm-model` was used, so a
+* comparison report can never be mistaken for a baseline one), one line per
+* mismatch/error, totals, the confusion matrix and the false-correct rate.
+*/
+function formatEvalReport(result, source) {
+	const { totals } = result;
+	const lines = [
+		(totals.failed === 0 && totals.errored === 0 && totals.skipped === 0 ? green("✔ Eval passed") : red("✘ Eval failed")) + dim(` — ${source}`),
+		`  id: ${result.id}`,
+		`  target: ${result.target}`
+	];
+	const llm = result.llm.overrides ? `${result.llm.overrides.provider} / ${result.llm.overrides.model} ${yellow("→")} ${result.llm.provider} / ${result.llm.model} ${yellow("(override)")}` : `${result.llm.provider} / ${result.llm.model}`;
+	lines.push(`  llm: ${llm}`);
+	lines.push(`  cases: ${totals.cases} × ${totals.repeats} repeat(s) = ${totals.calls} grading call(s)`);
+	if (result.aborted) {
+		lines.push("");
+		lines.push(red(`Run aborted: ${result.aborted.message}`));
+	}
+	if (result.mismatches.length) {
+		lines.push("");
+		lines.push(red(`${result.mismatches.length} mismatch(es):`));
+		lines.push(...mismatchLines(result));
+	}
+	lines.push("");
+	lines.push(`  passed: ${totals.passed}   failed: ${totals.failed}   errored: ${totals.errored}` + (totals.skipped ? red(`   skipped: ${totals.skipped} (run aborted)`) : "") + (totals.unstable ? dim(`   unstable: ${totals.unstable}`) : ""));
+	const tokens = formatUsageLine(totals.usage);
+	if (tokens) lines.push(dim(`  ${tokens}`));
+	if (result.confusion.length) {
+		lines.push("");
+		lines.push("  confusion (expected → got):");
+		for (const row of result.confusion) lines.push(`    ${row.expected} → ${row.got}: ${row.count}`);
+	}
+	const { count, denominator, rate } = result.falseCorrect;
+	lines.push("");
+	lines.push(`  false-correct: ${count}/${denominator}` + (denominator ? ` (${(rate * 100).toFixed(1)}%)` : ""));
+	return lines.join("\n");
+}
+/**
+* The human report for a MULTI-file run: a per-file summary table, grand totals, then
+* the per-file detail sections only for files that had mismatches. The confusion matrix
+* and false-correct rate stay per file — mixing verdicts across unrelated quizzes is
+* not meaningful. A single-file run keeps the plain {@link formatEvalReport}.
+*/
+function formatEvalBatchReport(batch) {
+	const lines = [];
+	lines.push(`Evaluated ${batch.totals.files} file(s):`);
+	for (const file of batch.files) {
+		const name = shortSource$1(file.source);
+		if (file.status === "invalid" || !file.result) {
+			lines.push(`  ${red("✘")} ${name}: ${red("invalid")} (${file.errors?.length ?? 0} error(s))`);
+			continue;
+		}
+		const t = file.result.totals;
+		const mark = t.failed === 0 && t.errored === 0 && t.skipped === 0 ? green("✔") : red("✗");
+		lines.push(`  ${mark} ${name}: ${t.cases} case(s), ${t.passed} passed, ${t.failed} failed, ${t.errored} errored` + (t.skipped ? red(`, ${t.skipped} skipped`) : "") + (t.unstable ? dim(`, ${t.unstable} unstable`) : ""));
+	}
+	const g = batch.totals;
+	lines.push("");
+	lines.push(`  TOTAL: ${g.cases} case(s), ${g.passed} passed, ${g.failed} failed, ${g.errored} errored` + (g.skipped ? red(`, ${g.skipped} skipped`) : "") + (g.invalid ? red(`, ${g.invalid} invalid file(s)`) : ""));
+	const tokens = formatUsageLine(g.usage);
+	if (tokens) lines.push(dim(`  ${tokens}`));
+	for (const file of batch.files) {
+		if (file.status === "invalid") {
+			lines.push("");
+			lines.push(red(`✘ ${shortSource$1(file.source)} — not a usable eval:`));
+			lines.push(...renderErrors(file.errors ?? []));
+			continue;
+		}
+		if (!file.result || file.result.mismatches.length === 0) continue;
+		lines.push("");
+		lines.push(formatEvalReport(file.result, shortSource$1(file.source)));
+	}
+	return lines.join("\n");
+}
+/** The last path segment of a source URL — enough to tell files apart in a table. */
+function shortSource$1(source) {
+	try {
+		const { pathname } = new URL(source);
+		return decodeURIComponent(pathname.split("/").pop() || source);
+	} catch {
+		return source;
+	}
+}
+/**
+* Renderer for a prompt dump (`prompts`). Kind-agnostic by construction: the envelope
+* (kind / id / provider+model) plus one line per prompt with its character count — the
+* sections come from `promptSections`, so a new kind needs no change here. `--json`
+* carries the prompt text itself.
+*/
+function formatPromptDump(dump, sections, source) {
+	const lines = [green(`✔ Prompts — ${dump.kind}`) + dim(` — ${source}`)];
+	lines.push(`  id: ${dump.id}`);
+	lines.push(`  provider: ${dump.llm.provider}   model: ${dump.llm.model}`);
+	lines.push(`  prompts: ${sections.length}`);
+	for (const section of sections) lines.push(`    ${section.name}: ${section.text.length} chars`);
+	lines.push("");
+	lines.push(dim("  Run again with --json for the full prompt text."));
+	return lines.join("\n");
+}
+//#endregion
+//#region src/report-md.ts
+/** `2026-08-08 14:32 UTC` — UTC always, so two reports are comparable across machines. */
+function timestamp(at) {
+	return `${at.toISOString().slice(0, 16).replace("T", " ")} UTC`;
+}
+/** Thousands-separated, en-US so the report reads the same on every machine. */
+function count(value) {
+	return value.toLocaleString("en-US");
+}
+/**
+* A teacher-authored string made safe for a TABLE CELL: newlines collapse to spaces
+* (a raw newline would end the row) and pipes are escaped (they would split it).
+*/
+function cell(text) {
+	return text.replace(/\s+/g, " ").replace(/\|/g, "\\|").trim();
+}
+/** The same neutralization for a LIST ITEM, where only the newline is structural. */
+function inline(text) {
+	return text.replace(/\s+/g, " ").trim();
+}
+/**
+* A verbatim blockquote: every line prefixed, so the text keeps its own line breaks and
+* can never escape into the surrounding document structure.
+*/
+function quote(text) {
+	return text.replace(/\s+$/, "").split(/\r?\n/).map((line) => line ? `> ${line}` : ">").join("\n");
+}
+/** `SCCH / gemma-4`, or `SCCH / gemma-4 → Azure Foundry / gpt-5-mini (override)`. */
+function llmText(llm) {
+	const effective = `${llm.provider} / ${llm.model}`;
+	return llm.overrides ? `${llm.overrides.provider} / ${llm.overrides.model} → ${effective} (override)` : effective;
+}
+/** `15,420 / 12,300 / 2,810`, or an em dash when nothing was reported. */
+function usageCell(usage) {
+	if (usage.input === 0 && usage.cachedInput === 0 && usage.output === 0) return "—";
+	return `${count(usage.input)} / ${count(usage.cachedInput)} / ${count(usage.output)}`;
+}
+/** The last path segment of a source URL — how a file is named throughout the report. */
+function shortSource(source) {
+	try {
+		const { pathname } = new URL(source);
+		return decodeURIComponent(pathname.split("/").pop() || source);
+	} catch {
+		return source;
+	}
+}
+/** `1/12 (8.3%)` — the false-correct rate, or `0/0` when nothing could be false-correct. */
+function falseCorrectCell(result) {
+	const { count: hits, denominator, rate } = result.falseCorrect;
+	return denominator === 0 ? `${hits}/0` : `${hits}/${denominator} (${(rate * 100).toFixed(1)}%)`;
+}
+const OVERVIEW_HEADER = [
+	"File",
+	"Eval",
+	"Cases",
+	"Passed",
+	"Failed",
+	"Errored",
+	"Skipped",
+	"Unstable",
+	"False-correct",
+	"Tokens (in / cached / out)"
+];
+/** `| a | b |` for one row of the overview table. */
+function row(cells) {
+	return `| ${cells.join(" | ")} |`;
+}
+/** The overview table: one row per file, plus a grand TOTAL row for a real batch. */
+function overview(batch) {
+	const lines = [row(OVERVIEW_HEADER), row([
+		"---",
+		"---",
+		"---:",
+		"---:",
+		"---:",
+		"---:",
+		"---:",
+		"---:",
+		"---:",
+		"---:"
+	])];
+	for (const file of batch.files) {
+		const name = cell(shortSource(file.source));
+		if (!file.result) {
+			lines.push(row([
+				name,
+				"**invalid**",
+				"—",
+				"—",
+				"—",
+				"—",
+				"—",
+				"—",
+				"—",
+				"—"
+			]));
+			continue;
+		}
+		const t = file.result.totals;
+		lines.push(row([
+			`${file.passed ? "✅" : "❌"} ${name}`,
+			`\`${cell(file.result.id)}\``,
+			count(t.cases),
+			count(t.passed),
+			count(t.failed),
+			count(t.errored),
+			count(t.skipped),
+			count(t.unstable),
+			falseCorrectCell(file.result),
+			usageCell(t.usage)
+		]));
+	}
+	if (batch.files.length > 1) {
+		const g = batch.totals;
+		lines.push(row([
+			"**TOTAL**",
+			g.invalid ? `${count(g.invalid)} invalid` : "",
+			`**${count(g.cases)}**`,
+			`**${count(g.passed)}**`,
+			`**${count(g.failed)}**`,
+			`**${count(g.errored)}**`,
+			`**${count(g.skipped)}**`,
+			`**${count(g.unstable)}**`,
+			"",
+			`**${usageCell(g.usage)}**`
+		]));
+	}
+	return lines;
+}
+/** The one-line error message an errored repeat row carries. */
+function errorMessage(error) {
+	if (typeof error === "string") return error;
+	if (typeof error === "object" && error !== null && "message" in error) return String(error.message);
+	return JSON.stringify(error ?? null);
+}
+/** `expected correct, got incorrect` — the heading's verdict half. */
+function verdictSummary(evalCase) {
+	return `expected ${evalCase.expected.join(" | ")}, got ${evalCase.status === "errored" ? "error" : evalCase.verdict ?? "no verdict"}`;
+}
+/** Whether a case belongs in the details section at all (§ details only for problems). */
+function needsDetail(evalCase) {
+	return evalCase.status === "failed" || evalCase.status === "errored" || evalCase.unstable;
+}
+/**
+* One case's section: the question it belongs to, the golden answer, and what the
+* grader said — plus every repeat when they disagreed (the `--repeats` signal is
+* exactly what a teacher wants to read here, not a majority hidden behind one line).
+*/
+function caseSection(evalCase, questionText) {
 	const lines = [];
-	for (const e of errors) {
-		lines.push(`  ${red("✗")} ${red(e.code)} ${e.message}${context(e)}`);
-		if (e.zodIssues) for (const issue of formatZodIssues(e.zodIssues)) lines.push(`      ${dim(issue)}`);
+	const unstable = evalCase.unstable ? " *(unstable)*" : "";
+	lines.push(`### \`${evalCase.questionId}\` #${evalCase.answerIndex} — ${verdictSummary(evalCase)}${unstable}`);
+	lines.push("");
+	if (questionText) {
+		lines.push("**Question**");
+		lines.push("");
+		lines.push(quote(questionText));
+		lines.push("");
+	}
+	lines.push("**Golden answer**");
+	lines.push("");
+	lines.push(quote(evalCase.answer));
+	lines.push("");
+	const graded = evalCase.repeats.filter((r) => r.got !== void 0);
+	const disagreed = new Set(graded.map((r) => r.got)).size > 1;
+	if (evalCase.repeats.length > 1 && (disagreed || graded.length !== evalCase.repeats.length)) {
+		lines.push("**Repeats**");
+		lines.push("");
+		for (const repeat of evalCase.repeats) {
+			const verdict = repeat.got ? `\`${repeat.got}\`` : "**error**";
+			const detail = repeat.got ? inline(repeat.feedback ?? "") : inline(errorMessage(repeat.error));
+			lines.push(`- #${repeat.repeatIndex + 1} — ${verdict}${detail ? ` — ${detail}` : ""}`);
+		}
+		lines.push("");
+		return lines;
+	}
+	const feedback = graded.find((r) => r.feedback)?.feedback;
+	if (feedback) {
+		lines.push("**Grader feedback**");
+		lines.push("");
+		lines.push(quote(feedback));
+		lines.push("");
+	}
+	const failure = evalCase.repeats.find((r) => r.error !== void 0);
+	if (failure) {
+		lines.push("**Error**");
+		lines.push("");
+		lines.push(quote(errorMessage(failure.error)));
+		lines.push("");
+	}
+	return lines;
+}
+/** One file's details section, or `[]` when the file has nothing to report. */
+function fileDetails(file) {
+	const name = shortSource(file.source);
+	if (!file.result) {
+		const errors = file.errors ?? [];
+		return [
+			`## ${cell(name)} — invalid`,
+			"",
+			"This file was not graded; fix the problems below and run it again.",
+			"",
+			...errors.map((issue) => `- \`${cell(issue.code)}\` — ${inline(issue.message)}`),
+			""
+		];
+	}
+	const result = file.result;
+	const detailed = result.cases.filter(needsDetail);
+	const skipped = result.totals.skipped;
+	if (detailed.length === 0 && skipped === 0 && !result.aborted) return [];
+	const questionText = new Map(result.questions.map((question) => [question.id, question.text]));
+	const lines = [`## ${cell(name)} — \`${cell(result.id)}\``, ""];
+	if (result.aborted) {
+		lines.push("> [!WARNING]");
+		lines.push(`> The run was aborted: ${inline(result.aborted.message)}`);
+		lines.push("");
+	}
+	for (const evalCase of detailed) lines.push(...caseSection(evalCase, questionText.get(evalCase.questionId)));
+	if (skipped > 0) {
+		const reason = result.aborted ? ` (${inline(result.aborted.message)})` : "";
+		lines.push(`**${count(skipped)} case(s) were never attempted**${reason} — the run is incomplete, so it cannot pass.`);
+		lines.push("");
+	}
+	return lines;
+}
+/**
+* Render the whole run as Markdown: verdict headline, the run's facts, the overview
+* table, then the details of everything that needs a teacher's attention.
+*/
+function renderEvalMarkdownReport(batch, meta) {
+	const lines = [];
+	lines.push(`# Eval report — ${batch.passed ? "✅ passed" : "❌ failed"}`);
+	lines.push("");
+	lines.push(`- **Generated** ${timestamp(meta.generatedAt)} · novedu-cli ${meta.cliVersion}`);
+	const llms = [...new Set(batch.files.filter((f) => f.result).map((f) => llmText(f.result.llm)))];
+	for (const llm of llms) lines.push(`- **LLM** ${llm}`);
+	lines.push(`- **Run** ${count(batch.totals.files)} file(s), ${count(batch.totals.cases)} case(s) × ${count(meta.repeats)} repeat(s), concurrency ${count(meta.concurrency)}`);
+	const tokens = batch.totals.usage;
+	if (tokens.input || tokens.cachedInput || tokens.output) lines.push(`- **Tokens** ${count(tokens.input)} in (${count(tokens.cachedInput)} cached) / ${count(tokens.output)} out — successful grading calls only, so a lower bound`);
+	lines.push("");
+	if (batch.files.filter((file) => file.result?.aborted).length > 0) {
+		lines.push("> [!WARNING]");
+		lines.push(`> The run was ABORTED — ${count(batch.totals.skipped)} case(s) were never graded, so this report is incomplete.`);
+		lines.push("");
+	}
+	lines.push("## Overview");
+	lines.push("");
+	lines.push(...overview(batch));
+	lines.push("");
+	const details = batch.files.flatMap((file) => fileDetails(file));
+	if (details.length === 0) {
+		lines.push("_Nothing else to report — every case matched its expected verdict. The `--json` report carries every case, including the passing ones._");
+		lines.push("");
+	} else {
+		lines.push("_Below: only the mismatched, errored and unstable cases. Passing cases live in the `--json` report._");
+		lines.push("");
+		lines.push(...details);
+	}
+	return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+}
+//#endregion
+//#region src/version.ts
+let cached;
+/** The `version` field of the CLI's package.json; `"unknown"` if it cannot be read. */
+function cliVersion() {
+	if (cached !== void 0) return cached;
+	try {
+		const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+		cached = version ?? "unknown";
+	} catch {
+		cached = "unknown";
+	}
+	return cached;
+}
+//#endregion
+//#region ../lib/coding-schema.ts
+const CodingYamlSchema = z.strictObject({
+	id: z.string().min(1).meta({ description: "Short machine-readable activity id, e.g. beginner-typescript." }),
+	name: z.string().optional().meta({ description: "Optional human-readable label (not shown to the student)." }),
+	title: z.string().optional().meta({ description: "Optional label shown to the student on the /<code> connection page." }),
+	llm: z.strictObject({
+		model: z.string().min(1).meta({ description: "The model that answers. SERVER-ONLY and PINNED: the proxy always uses this model and ignores whatever model the coding agent sends." }),
+		provider: providerSchema
+	}).meta({
+		id: "llm",
+		description: "The pinned model and provider that answer coding requests."
+	}),
+	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
+	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source, e.g. a sample solution) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
+	instructions: z.string().min(1).meta({ description: "The assistant's system prompt. SERVER-ONLY: never sent to the browser or the coding agent, and appended AFTER the coding tool's own prompt (so the teacher has the final word). Constrain the assistant to what your class has learned. When any fragment_files or text_files are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." })
+});
+//#endregion
+//#region ../lib/coding-validate.ts
+/**
+* Extract metadata from an already-schema-validated coding value. Split from
+* `checkCodingValue` so `loadAndCheckCoding` can reuse the single `validate` it already
+* ran (no second parse of the same document against the same schema).
+*/
+function checkCodingParsed(coding) {
+	return {
+		ok: true,
+		codingId: coding.id,
+		model: coding.llm.model,
+		provider: coding.llm.provider,
+		title: coding.title ?? null,
+		warnings: []
+	};
+}
+/**
+* Validate a coding FILE: scheme-gate + fetch + parse (shared `loadYaml`), then the
+* pure `checkCodingValue`. The web app passes the default http(s)-only schemes; the
+* CLI adds `file:` so a local coding YAML on disk validates too.
+*/
+async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
+	const yaml = await loadYaml(url, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [yaml.error],
+		warnings: []
+	};
+	const valid = validate(yaml.value, CodingYamlSchema, "CODING_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkCodingParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		text_files: valid.data.text_files
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	}, valid.data.instructions);
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
+}
+//#endregion
+//#region ../lib/writing-schema.ts
+const WritingYamlSchema = z.strictObject({
+	id: z.string().min(1).meta({ description: "Short machine-readable activity id, e.g. human-animal-short-story." }),
+	name: z.string().optional().meta({ description: "Optional human-readable title (used as a label)." }),
+	title: z.string().optional().meta({ description: "Optional greeting shown to students on the welcome screen instead of the default message." }),
+	description: z.string().optional().meta({ description: "Optional description shown to students below the welcome greeting (Markdown)." }),
+	anonymous: z.boolean().optional().meta({
+		default: false,
+		description: "Writing DIVERGES: it defaults to false (attributed), because review and the Save feature need to know whose text it is. Set to true for ephemeral, unattributed writing — which also disables saving."
+	}),
+	llm: z.strictObject({
+		model: z.string().min(1).meta({ description: "The model that drives the feedback chat." }),
+		provider: providerSchema
+	}).meta({
+		id: "llm",
+		description: "The model and provider that back the writing coach."
+	}),
+	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
+	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
+	instructions: z.string().min(1).meta({ description: "The writing coach's system prompt. SERVER-ONLY: never sent to the browser, so it may describe the assessment criteria and coaching strategy. When any fragment_files or text_files are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." }),
+	placeholder: z.string().optional().meta({ description: "Optional starter text prefilled into the editor. Empty for a blank page." })
+});
+//#endregion
+//#region ../lib/writing-validate.ts
+/** Writing DIVERGES from tutor/quiz: it defaults to attributed (`anonymous: false`). */
+const DEFAULT_ANONYMOUS = false;
+/**
+* Extract metadata from an already-schema-validated writing value. Split from
+* `checkWritingValue` so `loadAndCheckWriting` can reuse the single `validate` it already
+* ran (no second parse of the same document against the same schema).
+*/
+function checkWritingParsed(writing) {
+	return {
+		ok: true,
+		writingId: writing.id,
+		model: writing.llm.model,
+		provider: writing.llm.provider,
+		anonymous: writing.anonymous ?? DEFAULT_ANONYMOUS,
+		title: writing.title ?? null,
+		warnings: []
+	};
+}
+/**
+* Validate a writing FILE: scheme-gate + fetch + parse (shared `loadYaml`), then the
+* pure `checkWritingValue`. The web app passes the default http(s)-only schemes; the
+* CLI adds `file:` so a local writing YAML on disk validates too.
+*/
+async function loadAndCheckWriting(url, fetchImpl, opts = {}) {
+	const yaml = await loadYaml(url, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [yaml.error],
+		warnings: []
+	};
+	const valid = validate(yaml.value, WritingYamlSchema, "WRITING_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkWritingParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		text_files: valid.data.text_files
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	}, valid.data.instructions);
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
+}
+//#endregion
+//#region src/commands/validate.ts
+/** Every kind the `--kind` flag accepts (used for the option help + guard). */
+const VALIDATE_KINDS = [
+	"tutor",
+	"fragment",
+	"quiz",
+	"writing",
+	"coding",
+	"eval"
+];
+/**
+* Turn the CLI argument into a URL the tutor core understands: an http(s) URL is
+* used as-is; anything else is treated as a filesystem path and converted to an
+* absolute `file://` URL.
+*/
+function toUrl(pathOrUrl) {
+	if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
+	return pathToFileURL(resolve(pathOrUrl)).href;
+}
+/**
+* The validate command's pure core: run the requested pipeline over a local file or
+* public URL. `file:` is allowed in addition to http(s) so local YAML can be
+* validated (the web app deliberately stays http(s)-only). As an authoring tool, the
+* tutor path runs the THOROUGH check (`validateLibraries`), so every fragment in every
+* referenced library is rendered — not just the ones the tutor uses.
+*/
+function runValidate(pathOrUrl, kind) {
+	const url = toUrl(pathOrUrl);
+	const allowedSchemes = [
+		"http:",
+		"https:",
+		"file:"
+	];
+	switch (kind) {
+		case "fragment": return loadAndCheckFragmentFile(url, cliFetcher, { allowedSchemes }).then((result) => ({
+			kind,
+			result
+		}));
+		case "quiz": return loadAndCheckQuiz(url, cliFetcher, { allowedSchemes }).then((result) => ({
+			kind,
+			result
+		}));
+		case "writing": return loadAndCheckWriting(url, cliFetcher, { allowedSchemes }).then((result) => ({
+			kind,
+			result
+		}));
+		case "coding": return loadAndCheckCoding(url, cliFetcher, { allowedSchemes }).then((result) => ({
+			kind,
+			result
+		}));
+		case "eval": return loadAndCheckEval(url, cliFetcher, {
+			allowedSchemes,
+			validateLibraries: true,
+			strictTarget: true
+		}).then((result) => ({
+			kind,
+			result
+		}));
+		default: return loadAndBuildTutorPrompt(url, cliFetcher, {
+			allowedSchemes,
+			validateLibraries: true
+		}).then((result) => ({
+			kind,
+			result
+		}));
 	}
-	return lines;
 }
-function formatResult(result, source) {
-	const lines = [];
-	if (result.ok) {
-		lines.push(green(`✔ Valid tutor`) + dim(` — ${source}`));
-		lines.push(`  model: ${result.model}`);
-		lines.push(`  system prompt: ${result.prompt.length} chars`);
-		lines.push(`  imageInput: ${result.imageInput}   anonymous: ${result.anonymous}` + (result.exampleQuestions.length ? `   exampleQuestions: ${result.exampleQuestions.length}` : ""));
-		if (result.warnings.length) {
-			lines.push("");
-			lines.push(yellow(`${result.warnings.length} warning(s):`));
-			lines.push(...renderWarnings(result.warnings));
+function registerValidate(program) {
+	program.command("validate").description("Validate a tutor (default), fragment library, quiz, writing, coding or eval YAML by local path or public http(s) URL").argument("<pathOrUrl>", "path to a tutor, fragment, quiz, writing, coding or eval YAML file, or a public http(s) URL").option("--kind <kind>", `what the file is: ${VALIDATE_KINDS.map((k) => `'${k}'`).join(", ")} ('tutor' is the default)`, "tutor").option("--json", "print the raw validation result as JSON").addHelpText("after", `
+Examples:
+  # Validate a tutor (also strict-renders every fragment in every referenced library)
+  $ novedu-cli validate ./activities/tutors/my-tutor.yaml
+
+  # Validate a fragment library on its own
+  $ novedu-cli validate ./activities/tutors/my-fragments.yaml --kind fragment
+
+  # Validate a quiz, a writing activity, or a coding activity
+  $ novedu-cli validate ./activities/quizzes/my-quiz.yaml --kind quiz
+  $ novedu-cli validate ./activities/writings/my-writing.yaml --kind writing
+  $ novedu-cli validate ./activities/coding/my-coding.yaml --kind coding
+
+  # Validate a golden-answer eval (also strict-checks the quiz it targets)
+  $ novedu-cli validate ./my-quiz.eval.yaml --kind eval
+
+  # Machine-readable output for CI
+  $ novedu-cli validate https://example.com/tutor.yaml --json`).action(async (pathOrUrl, options) => {
+		if (options.kind !== void 0 && !VALIDATE_KINDS.includes(options.kind)) {
+			console.error(`Invalid --kind "${options.kind}": expected ${VALIDATE_KINDS.map((k) => `"${k}"`).join(", ")}.`);
+			process.exitCode = 1;
+			return;
 		}
-		return lines.join("\n");
-	}
-	lines.push(red(`✘ Invalid tutor`) + dim(` — ${source}`));
-	lines.push("");
-	lines.push(red(`${result.errors.length} error(s):`));
-	lines.push(...renderErrors(result.errors));
-	if (result.warnings.length) {
-		lines.push("");
-		lines.push(yellow(`${result.warnings.length} warning(s):`));
-		lines.push(...renderWarnings(result.warnings));
+		const outcome = await runValidate(pathOrUrl, options.kind ?? "tutor");
+		if (options.json) console.log(JSON.stringify(outcome.result, null, 2));
+		else console.log(formatOutcome(outcome, pathOrUrl));
+		process.exitCode = outcome.result.ok ? 0 : 1;
+	});
+}
+/** Pick the formatter for the outcome's kind (each result type has its own renderer). */
+function formatOutcome(outcome, source) {
+	switch (outcome.kind) {
+		case "fragment": return formatFragmentResult(outcome.result, source);
+		case "quiz": return formatQuizResult(outcome.result, source);
+		case "writing": return formatWritingResult(outcome.result, source);
+		case "coding": return formatCodingResult(outcome.result, source);
+		case "eval": return formatEvalResult(outcome.result, source);
+		default: return formatResult(outcome.result, source);
 	}
-	return lines.join("\n");
 }
-/** Same renderer, for a standalone fragment-FILE check (`--kind fragment`). */
-function formatFragmentResult(result, source) {
-	const lines = [];
-	if (result.ok) {
-		lines.push(green(`✔ Valid fragment file`) + dim(` — ${source}`));
-		lines.push(`  id: ${result.fragmentFileId}`);
-		lines.push(`  fragments: ${result.fragmentIds.length}` + (result.fragmentIds.length ? ` (${result.fragmentIds.join(", ")})` : ""));
-		if (result.warnings.length) {
-			lines.push("");
-			lines.push(yellow(`${result.warnings.length} warning(s):`));
-			lines.push(...renderWarnings(result.warnings));
+//#endregion
+//#region src/commands/eval.ts
+const CONCURRENCY_DEFAULT = 4;
+/** Shell metacharacters that make a plain argument a PATTERN rather than a path. */
+const GLOB_MAGIC = /[*?[\]{}]/;
+/**
+* Turn the positional arguments into the list of sources to evaluate. A `file:` /
+* `http(s):` URL and a plain path pass through untouched (so a shell-expanded glob —
+* which arrives as plain paths — behaves identically); an argument carrying glob magic
+* is expanded relative to the cwd and sorted, which is what makes `"./**\/*.eval.yaml"`
+* and PowerShell/cmd work. A pattern that matches NOTHING is a hard failure: it is
+* almost certainly a typo, and silently evaluating zero files would exit 0.
+*/
+function expandSources(args) {
+	const expanded = [];
+	for (const arg of args) {
+		if (/^(?:https?|file):/i.test(arg) || !GLOB_MAGIC.test(arg)) {
+			expanded.push(arg);
+			continue;
 		}
-		return lines.join("\n");
+		let matches;
+		try {
+			matches = [...globSync(arg)];
+		} catch (error) {
+			return {
+				ok: false,
+				message: `Could not expand the pattern "${arg}": ${error instanceof Error ? error.message : error}`
+			};
+		}
+		if (matches.length === 0) return {
+			ok: false,
+			message: `The pattern "${arg}" matched no files.`
+		};
+		expanded.push(...matches.sort((a, b) => a.localeCompare(b)));
 	}
-	lines.push(red(`✘ Invalid fragment file`) + dim(` — ${source}`));
-	lines.push("");
-	lines.push(red(`${result.errors.length} error(s):`));
-	lines.push(...renderErrors(result.errors));
-	if (result.warnings.length) {
-		lines.push("");
-		lines.push(yellow(`${result.warnings.length} warning(s):`));
-		lines.push(...renderWarnings(result.warnings));
+	const sources = [];
+	const duplicates = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of expanded) {
+		const url = toUrl(entry);
+		if (seen.has(url)) {
+			duplicates.push(url);
+			continue;
+		}
+		seen.add(url);
+		sources.push(url);
 	}
-	return lines.join("\n");
+	return {
+		ok: true,
+		sources,
+		duplicates
+	};
+}
+/** The `--llm-provider`/`--llm-model` pair: strictly both-or-nothing, provider checked. */
+function parseOverride(options) {
+	const { llmProvider, llmModel } = options;
+	if (llmProvider === void 0 && llmModel === void 0) return { ok: true };
+	if (llmProvider === void 0 || llmModel === void 0) return {
+		ok: false,
+		message: "Pass --llm-provider and --llm-model together, or neither."
+	};
+	if (!LLM_PROVIDERS.includes(llmProvider)) return {
+		ok: false,
+		message: `Unknown --llm-provider "${llmProvider}": expected ${LLM_PROVIDERS.map((p) => `"${p}"`).join(" or ")}.`
+	};
+	return {
+		ok: true,
+		llm: {
+			provider: llmProvider,
+			model: llmModel
+		}
+	};
 }
 /**
-* Shared tail for the quiz/writing renderers: on failure, the error list (with any
-* flattened Zod issues); plus any warnings on either branch.
+* The optional `usage: { input, cachedInput, output }` of a 200 response, defensively:
+* anything that is not three finite numbers is simply absent (an older server, or one
+* whose provider reports nothing, must never break a run).
 */
-function renderFailureAndWarnings(result, label, source) {
-	const lines = [red(`✘ Invalid ${label}`) + dim(` — ${source}`), ""];
-	lines.push(red(`${result.errors.length} error(s):`));
-	lines.push(...renderErrors(result.errors));
-	if (result.warnings.length) {
-		lines.push("");
-		lines.push(yellow(`${result.warnings.length} warning(s):`));
-		lines.push(...renderWarnings(result.warnings));
-	}
-	return lines.join("\n");
+function parseUsage(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const { input, cachedInput, output } = value;
+	const counts = [
+		input,
+		cachedInput,
+		output
+	].map((count) => typeof count === "number" && Number.isFinite(count) ? Math.max(0, count) : void 0);
+	if (counts.some((count) => count === void 0)) return void 0;
+	const [inputCount = 0, cachedCount = 0, outputCount = 0] = counts;
+	return {
+		input: inputCount,
+		cachedInput: cachedCount,
+		output: outputCount
+	};
 }
-/** Renderer for a quiz check (`--kind quiz`). */
-function formatQuizResult(result, source) {
-	if (!result.ok) return renderFailureAndWarnings(result, "quiz", source);
-	const lines = [green(`✔ Valid quiz`) + dim(` — ${source}`)];
-	lines.push(`  id: ${result.quizId}`);
-	lines.push(`  model: ${result.model}`);
-	lines.push(`  questions: ${result.questionCount}   anonymous: ${result.anonymous}`);
-	if (result.warnings.length) {
-		lines.push("");
-		lines.push(yellow(`${result.warnings.length} warning(s):`));
-		lines.push(...renderWarnings(result.warnings));
-	}
-	return lines.join("\n");
+/**
+* The HTTP seam for ONE grading call, with the run's effective llm closed in — so the
+* runner itself never learns whether the pair came from the quiz or from `--llm-*`.
+* Classifies the failure for the retry policy: 5xx and true network failures are
+* retryable, auth failures abort the run, every other 4xx is terminal.
+*/
+function makeGradeFn(server, llm) {
+	return async ({ system, answer }) => {
+		const response = await performApiRequest({
+			server,
+			path: "/api/eval/grade",
+			method: "POST",
+			body: {
+				llm,
+				system,
+				answer
+			},
+			quiet: true
+		});
+		if (response.ok) {
+			const payload = response.payload;
+			const verdict = payload?.result;
+			if (verdict === "correct" || verdict === "partial" || verdict === "incorrect") {
+				const usage = parseUsage(payload?.usage);
+				return {
+					ok: true,
+					verdict,
+					feedback: typeof payload?.feedback === "string" ? payload.feedback : "",
+					...usage ? { usage } : {}
+				};
+			}
+			return {
+				ok: false,
+				retryable: false,
+				error: { message: "The server's response is not a grading verdict — it may not offer /api/eval/grade at all (does it run a Novedu version with the eval feature?). Check the target server, e.g. --server http://localhost:3000." }
+			};
+		}
+		return {
+			ok: false,
+			retryable: response.status === void 0 || response.status >= 500,
+			...response.authFailed ? { auth: true } : {},
+			error: response.error
+		};
+	};
 }
-/** Renderer for a writing-activity check (`--kind writing`). */
-function formatWritingResult(result, source) {
-	if (!result.ok) return renderFailureAndWarnings(result, "writing activity", source);
-	const lines = [green(`✔ Valid writing activity`) + dim(` — ${source}`)];
-	lines.push(`  id: ${result.writingId}`);
-	lines.push(`  model: ${result.model}`);
-	lines.push(`  anonymous: ${result.anonymous}`);
-	if (result.warnings.length) {
-		lines.push("");
-		lines.push(yellow(`${result.warnings.length} warning(s):`));
-		lines.push(...renderWarnings(result.warnings));
+/** stderr progress, suppressed off a TTY so CI logs stay readable. */
+function progressWriter(prefix) {
+	if (!process.stderr.isTTY) return void 0;
+	return ({ done, total }) => {
+		process.stderr.write(`\r${prefix}${done}/${total}   `);
+	};
+}
+/**
+* The command's core, exported for the unit tests. `seams` exists only so tests can
+* shrink the retry backoff — the CLI itself never passes it (PoC parity: 4 attempts,
+* 5 s linear).
+*/
+async function runEvalCommand(pathsOrUrls, options, seams = {}) {
+	const override = parseOverride(options);
+	if (!override.ok) {
+		failJson({ message: override.message });
+		return;
 	}
-	return lines.join("\n");
+	const expansion = expandSources(pathsOrUrls);
+	if (!expansion.ok) {
+		failJson({ message: expansion.message });
+		return;
+	}
+	for (const duplicate of expansion.duplicates) process.stderr.write(`Warning: ${duplicate} was given more than once — ignoring the copy.\n`);
+	const repeats = Math.max(1, Number.parseInt(options.repeats ?? "1", 10) || 1);
+	const concurrency = Math.max(1, Number.parseInt(options.concurrency ?? String(CONCURRENCY_DEFAULT), 10) || CONCURRENCY_DEFAULT);
+	const checked = /* @__PURE__ */ new Map();
+	const files = [];
+	for (const source of expansion.sources) {
+		const result = await loadAndCheckEval(source, cliFetcher, { allowedSchemes: [
+			"http:",
+			"https:",
+			"file:"
+		] });
+		if (!result.ok) {
+			files.push({
+				source,
+				status: "invalid",
+				errors: result.errors
+			});
+			continue;
+		}
+		checked.set(source, result);
+		files.push({
+			source,
+			status: "ok"
+		});
+	}
+	if (checked.size === 0) {
+		failJson({
+			message: files.length === 1 ? "The eval file is not usable." : "None of the eval files are usable.",
+			files: files.map((file) => ({
+				source: file.source,
+				errors: file.errors ?? []
+			})),
+			errors: files.flatMap((file) => file.errors ?? [])
+		});
+		return;
+	}
+	{
+		const totalCases = [...checked.values()].reduce((sum, file) => sum + file.caseCount, 0);
+		process.stderr.write(`${totalCases} case(s) × ${repeats} repeat(s) = ${totalCases * repeats} grading call(s)\n`);
+	}
+	let fileIndex = 0;
+	for (const file of files) {
+		fileIndex += 1;
+		const check = checked.get(file.source);
+		if (!check) continue;
+		const quizLlm = {
+			provider: check.quizDump.llm.provider,
+			model: check.quizDump.llm.model
+		};
+		const effective = override.llm ?? quizLlm;
+		const llm = {
+			...effective,
+			...override.llm ? { overrides: quizLlm } : {}
+		};
+		const prefix = files.length > 1 ? `(${fileIndex}/${files.length}) ${check.evalFile.id}: ` : "";
+		file.result = await runEval("quiz", check, {
+			grade: makeGradeFn(options.server, effective),
+			concurrency,
+			repeats,
+			llm,
+			onProgress: progressWriter(prefix),
+			...seams.retry ? { retry: seams.retry } : {}
+		});
+		if (process.stderr.isTTY) process.stderr.write("\n");
+	}
+	const batch = summarizeBatch(files);
+	const payload = JSON.stringify(batch, null, 2);
+	if (options.json) console.log(payload);
+	else if (files.length === 1 && files[0]?.result) console.log(formatEvalReport(files[0].result, files[0].source));
+	else console.log(formatEvalBatchReport(batch));
+	if (options.out) try {
+		await writeFile(options.out, `${payload}\n`, "utf8");
+	} catch (error) {
+		failJson({ message: `Could not write ${options.out}: ${error instanceof Error ? error.message : error}` });
+		return;
+	}
+	if (options.report) try {
+		await writeFile(options.report, renderEvalMarkdownReport(batch, {
+			generatedAt: /* @__PURE__ */ new Date(),
+			cliVersion: cliVersion(),
+			repeats,
+			concurrency
+		}), "utf8");
+	} catch (error) {
+		failJson({ message: `Could not write ${options.report}: ${error instanceof Error ? error.message : error}` });
+		return;
+	}
+	process.exitCode = batchPassed(batch) ? 0 : 1;
+}
+function registerEval(program) {
+	program.command("eval").description("Grade a file of golden answers against its quiz's real rubric and report the result").argument("<evalPathOrUrl...>", "one or more eval YAML files (paths, http(s)/file URLs, or a quoted glob pattern)").option("--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)").option("--concurrency <n>", "grading calls in flight per file", String(CONCURRENCY_DEFAULT)).option("--repeats <n>", "grade every answer N times and take the majority verdict", "1").option("--llm-provider <provider>", "grade with this provider instead of the quiz's (\"SCCH\" or \"Azure Foundry\"; needs --llm-model)").option("--llm-model <model>", "grade with this model instead of the quiz's (needs --llm-provider)").option("--json", "print the machine-readable batch report on stdout").option("--out <file>", "additionally write the machine-readable batch report to a file").option("--report <file>", "additionally write a readable Markdown report to a file").addHelpText("after", `
+Examples:
+  # Evaluate one quiz's golden answers
+  $ novedu-cli eval ./0010-welcome-quiz.eval.yaml
+
+  # A whole course part (quote the pattern so the CLI expands it, ** included)
+  $ novedu-cli eval "./part-1/**/*.eval.yaml"
+
+  # Measure grader stability: 3 runs per answer, majority verdict
+  $ novedu-cli eval ./my-quiz.eval.yaml --repeats 3
+
+  # How would this rubric perform on another model? (both flags, always together)
+  $ novedu-cli eval ./my-quiz.eval.yaml --llm-provider "Azure Foundry" --llm-model gpt-5-mini
+
+  # Machine-readable, for CI
+  $ novedu-cli eval ./my-quiz.eval.yaml --json --out eval-report.json
+
+  # A readable Markdown report (questions, golden answers, grader feedback, tokens)
+  $ novedu-cli eval ./my-quiz.eval.yaml --report eval-report.md`).action(async (pathsOrUrls, options) => {
+		await runEvalCommand(pathsOrUrls, options);
+	});
+}
+//#endregion
+//#region src/commands/files.ts
+const SERVER_OPTION$2 = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+function registerFiles(program) {
+	const files = program.command("files").description("Manage app-hosted YAML files on the Novedu server");
+	files.command("upload <name>").description("Create or update an app-hosted YAML file from --file or stdin (validated server-side)").option("--kind <kind>", "file kind (tutor, fragment, quiz, writing, coding) — required when creating").option("--file <path>", "read the YAML from this path instead of stdin").option(...SERVER_OPTION$2).action(async (name, options) => {
+		let content;
+		try {
+			content = options.file === void 0 ? await readStdin() : await readFile(options.file, "utf8");
+		} catch (error) {
+			failJson({ message: `Could not read ${options.file}: ${error instanceof Error ? error.message : error}` });
+			return;
+		}
+		await runApiRequest({
+			server: options.server,
+			path: `/api/files/${encodeURIComponent(name)}`,
+			method: "PUT",
+			body: {
+				...options.kind === void 0 ? {} : { kind: options.kind },
+				content
+			}
+		});
+	});
+	files.command("list").description("List app-hosted YAML files (defaults to only your own, like the web list)").option("--search <q>", "contains-filter over name/title/description").option("--all", "include files last written by other teachers").option(...SERVER_OPTION$2).action(async (options) => {
+		const params = new URLSearchParams();
+		if (options.search) params.set("q", options.search);
+		if (options.all) params.set("mine", "0");
+		const query = params.toString();
+		await runApiRequest({
+			server: options.server,
+			path: `/api/files${query ? `?${query}` : ""}`
+		});
+	});
 }
+//#endregion
+//#region ../lib/file-name.ts
 /**
-* Renderer for a coding-activity check (`--kind coding`). Coding is ALWAYS anonymous
-* (the API path carries no per-student identity), so — unlike quiz/writing — that is
-* shown as a fixed note, not a per-file value.
+* Maps a filename or bare extension (with or without a leading dot, any case)
+* to an {@link ImageMime}; returns `null` for anything unrecognized. `jpg`/`jpeg`
+* both map to `image/jpeg`, `svg` to `image/svg+xml`.
 */
-function formatCodingResult(result, source) {
-	if (!result.ok) return renderFailureAndWarnings(result, "coding activity", source);
-	const lines = [green(`✔ Valid coding activity`) + dim(` — ${source}`)];
-	lines.push(`  id: ${result.codingId}`);
-	lines.push(`  model: ${result.model}`);
-	lines.push(`  anonymous: true ${dim("(always — the API path carries no identity)")}`);
-	if (result.warnings.length) {
-		lines.push("");
-		lines.push(yellow(`${result.warnings.length} warning(s):`));
-		lines.push(...renderWarnings(result.warnings));
+function imageMimeFromExtension(filename) {
+	const lastDot = filename.lastIndexOf(".");
+	switch ((lastDot >= 0 ? filename.slice(lastDot + 1) : filename).toLowerCase()) {
+		case "png": return "image/png";
+		case "jpg":
+		case "jpeg": return "image/jpeg";
+		case "svg": return "image/svg+xml";
+		default: return null;
 	}
-	return lines.join("\n");
 }
 //#endregion
-//#region src/commands/validate.ts
-/** Every kind the `--kind` flag accepts (used for the option help + guard). */
-const VALIDATE_KINDS = [
-	"tutor",
-	"fragment",
-	"quiz",
-	"writing",
-	"coding"
-];
-/**
-* Turn the CLI argument into a URL the tutor core understands: an http(s) URL is
-* used as-is; anything else is treated as a filesystem path and converted to an
-* absolute `file://` URL.
-*/
-function toUrl(pathOrUrl) {
-	if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
-	return pathToFileURL(resolve(pathOrUrl)).href;
+//#region src/commands/images.ts
+const SERVER_OPTION$1 = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
+function registerImages(program) {
+	const images = program.command("images").description("Manage app-hosted images on the Novedu server");
+	images.command("upload <name>").description("Upload a NEW image (.png, .jpg/.jpeg or .svg, max 5 MB) from --file").option("--file <path>", "the image file to upload (required — images are binary, no stdin)").option("--credit <text>", "optional attribution shown with the image (max 512 chars)").option(...SERVER_OPTION$1).action(async (name, options) => {
+		if (options.file === void 0) {
+			failJson({ message: "Pass --file <path> — images are binary, stdin is not supported." });
+			return;
+		}
+		const mime = imageMimeFromExtension(options.file);
+		if (mime === null) {
+			failJson({ message: "Only .png, .jpg/.jpeg and .svg files can be uploaded." });
+			return;
+		}
+		let bytes;
+		try {
+			bytes = await readFile(options.file);
+		} catch (error) {
+			failJson({ message: `Could not read ${options.file}: ${error instanceof Error ? error.message : error}` });
+			return;
+		}
+		const slot = await performApiRequest({
+			server: options.server,
+			path: `/api/images/${encodeURIComponent(name)}`,
+			method: "POST",
+			body: {
+				mime,
+				byteSize: bytes.length
+			}
+		});
+		if (!slot.ok) return;
+		const { uploadUrl, blobPath } = slot.payload ?? {};
+		if (typeof uploadUrl !== "string" || typeof blobPath !== "string") {
+			failJson({ message: "Unexpected response from the server." });
+			return;
+		}
+		let putResponse;
+		try {
+			putResponse = await fetch(uploadUrl, {
+				method: "PUT",
+				headers: {
+					"x-ms-blob-type": "BlockBlob",
+					"content-type": mime
+				},
+				body: new Uint8Array(bytes)
+			});
+		} catch (error) {
+			failJson({ message: `Could not reach storage: ${error instanceof Error ? error.message : error}` });
+			return;
+		}
+		if (!putResponse.ok) {
+			failJson({ message: `The upload to storage failed: HTTP ${putResponse.status}. Try again.` });
+			return;
+		}
+		await runApiRequest({
+			server: options.server,
+			path: `/api/images/${encodeURIComponent(name)}/confirm`,
+			method: "POST",
+			body: {
+				blobPath,
+				mime,
+				...options.credit === void 0 ? {} : { credit: options.credit }
+			}
+		});
+	});
+	images.command("list").description("List app-hosted images (defaults to only your own, like the web list)").option("--search <q>", "contains-filter over the name").option("--all", "include images uploaded by other teachers").option(...SERVER_OPTION$1).action(async (options) => {
+		const params = new URLSearchParams();
+		if (options.search) params.set("q", options.search);
+		if (options.all) params.set("mine", "0");
+		const query = params.toString();
+		await runApiRequest({
+			server: options.server,
+			path: `/api/images${query ? `?${query}` : ""}`
+		});
+	});
+}
+//#endregion
+//#region src/commands/login.ts
+function registerLogin(program) {
+	program.command("login").description("Sign in to Microsoft Entra ID (opens your browser)").option("--device-code", "sign in with the device code flow instead (for machines without a browser; the tenant must allow it)").addHelpText("after", `
+Sign-in is the one human-assisted step: by default a browser window opens for
+the Microsoft sign-in (first-time users see a one-time consent prompt). On a
+machine without a browser, --device-code prints a verification URL and a code
+to enter from any other device — note that some tenants block the device code
+flow by policy (error 53003). Every other command then works non-interactively
+from the cached credentials. Already signed in? The command says so and exits
+— it never blocks.`).action(async (options) => {
+		const pca = buildPca();
+		const cached = await acquireSilent(pca);
+		if (cached) {
+			console.log(`Already signed in as ${displayName(cached)}.`);
+			return;
+		}
+		const result = options.deviceCode ? await acquireByDeviceCode(pca, (message) => console.log(message)) : await acquireInteractive(pca, (url) => {
+			console.log("A browser window should open for the Microsoft sign-in.");
+			console.log(`If it does not, open this URL yourself:\n${url}`);
+		});
+		console.log(`Signed in as ${displayName(result)}.`);
+	});
+}
+//#endregion
+//#region src/commands/logout.ts
+function registerLogout(program) {
+	program.command("logout").description("Sign out: remove the cached credentials from this machine").addHelpText("after", `
+Purely local — already-issued access tokens stay valid until they expire
+(about an hour). Running it while signed out is fine.`).action(async () => {
+		const cache = buildPca().getTokenCache();
+		for (const account of await cache.getAllAccounts()) await cache.removeAccount(account);
+		rmSync(TOKEN_CACHE_PATH, { force: true });
+		console.log("Signed out.");
+	});
 }
+//#endregion
+//#region src/commands/prompts.ts
 /**
-* The validate command's pure core: run the requested pipeline over a local file or
-* public URL. `file:` is allowed in addition to http(s) so local YAML can be
-* validated (the web app deliberately stays http(s)-only). As an authoring tool, the
-* tutor path runs the THOROUGH check (`validateLibraries`), so every fragment in every
-* referenced library is rendered — not just the ones the tutor uses.
+* The command's pure core: dump the prompts of a local file or public URL. `file:` is
+* allowed in addition to http(s) so an on-disk activity dumps (the web app deliberately
+* stays http(s)-only), and relative `fragment_files` / `quiz_files` resolve against the
+* activity's own location.
+*
+* This is the RUNTIME path — the lenient loaders the app runs when a student opens the
+* activity — so the output is what the model really receives. Use `validate` for the
+* strict authoring gate.
 */
-function runValidate(pathOrUrl, kind) {
-	const url = toUrl(pathOrUrl);
-	const allowedSchemes = [
+function runPrompts(pathOrUrl, kind) {
+	return dumpPrompts(kind, toUrl(pathOrUrl), cliFetcher, { allowedSchemes: [
 		"http:",
 		"https:",
 		"file:"
-	];
-	switch (kind) {
-		case "fragment": return loadAndCheckFragmentFile(url, cliFetcher, { allowedSchemes }).then((result) => ({
-			kind,
-			result
-		}));
-		case "quiz": return loadAndCheckQuiz(url, cliFetcher, { allowedSchemes }).then((result) => ({
-			kind,
-			result
-		}));
-		case "writing": return loadAndCheckWriting(url, cliFetcher, { allowedSchemes }).then((result) => ({
-			kind,
-			result
-		}));
-		case "coding": return loadAndCheckCoding(url, cliFetcher, { allowedSchemes }).then((result) => ({
-			kind,
-			result
-		}));
-		default: return loadAndBuildTutorPrompt(url, cliFetcher, {
-			allowedSchemes,
-			validateLibraries: true
-		}).then((result) => ({
-			kind,
-			result
-		}));
-	}
+	] });
 }
-function registerValidate(program) {
-	program.command("validate").description("Validate a tutor (default), fragment library, quiz, writing or coding YAML by local path or public http(s) URL").argument("<pathOrUrl>", "path to a tutor, fragment, quiz, writing or coding YAML file, or a public http(s) URL").option("--kind <kind>", `what the file is: ${VALIDATE_KINDS.map((k) => `'${k}'`).join(", ")} ('tutor' is the default)`, "tutor").option("--json", "print the raw validation result as JSON").addHelpText("after", `
+function registerPrompts(program) {
+	program.command("prompts").description("Print the exact LLM prompts a tutor (default), quiz, writing or coding YAML produces").argument("<pathOrUrl>", "path to a tutor, quiz, writing or coding YAML file, or a public http(s) URL").option("--kind <kind>", `what the file is: ${PROMPT_KINDS.map((k) => `'${k}'`).join(", ")} ('tutor' is the default)`, "tutor").option("--json", "print the full prompt dump as JSON").addHelpText("after", `
 Examples:
-  # Validate a tutor (also strict-renders every fragment in every referenced library)
-  $ novedu-cli validate ./activities/tutors/my-tutor.yaml
+  # The tutor's assembled system prompt (fragments resolved in place)
+  $ novedu-cli prompts ./activities/tutors/my-tutor.yaml
 
-  # Validate a fragment library on its own
-  $ novedu-cli validate ./activities/tutors/my-fragments.yaml --kind fragment
+  # Every grading prompt of a quiz, plus its discussion prompt, as JSON
+  $ novedu-cli prompts ./activities/quizzes/my-quiz.yaml --kind quiz --json
 
-  # Validate a quiz, a writing activity, or a coding activity
-  $ novedu-cli validate ./activities/quizzes/my-quiz.yaml --kind quiz
-  $ novedu-cli validate ./activities/writings/my-writing.yaml --kind writing
-  $ novedu-cli validate ./activities/coding/my-coding.yaml --kind coding
+  # A writing activity's coach prompt / a coding activity's injected system prompt
+  $ novedu-cli prompts ./activities/writings/my-writing.yaml --kind writing
+  $ novedu-cli prompts ./activities/coding/my-coding.yaml --kind coding
 
-  # Machine-readable output for CI
-  $ novedu-cli validate https://example.com/tutor.yaml --json`).action(async (pathOrUrl, options) => {
-		if (options.kind !== void 0 && !VALIDATE_KINDS.includes(options.kind)) {
-			console.error(`Invalid --kind "${options.kind}": expected ${VALIDATE_KINDS.map((k) => `"${k}"`).join(", ")}.`);
+  # One question's grading prompt, straight out of the JSON dump
+  $ novedu-cli prompts ./my-quiz.yaml --kind quiz --json | jq -r '.grading.questions[0].system'`).action(async (pathOrUrl, options) => {
+		if (options.kind !== void 0 && !PROMPT_KINDS.includes(options.kind)) {
+			console.error(`Invalid --kind "${options.kind}": expected ${PROMPT_KINDS.map((k) => `"${k}"`).join(", ")}.`);
 			process.exitCode = 1;
 			return;
 		}
-		const outcome = await runValidate(pathOrUrl, options.kind ?? "tutor");
-		if (options.json) console.log(JSON.stringify(outcome.result, null, 2));
-		else console.log(formatOutcome(outcome, pathOrUrl));
-		process.exitCode = outcome.result.ok ? 0 : 1;
+		const result = await runPrompts(pathOrUrl, options.kind ?? "tutor");
+		if (!result.ok) {
+			console.error(JSON.stringify({ errors: result.errors }, null, 2));
+			process.exitCode = 1;
+			return;
+		}
+		if (options.json) console.log(JSON.stringify(result.dump, null, 2));
+		else console.log(formatPromptDump(result.dump, promptSections(result.dump), pathOrUrl));
+		process.exitCode = 0;
 	});
 }
-/** Pick the formatter for the outcome's kind (each result type has its own renderer). */
-function formatOutcome(outcome, source) {
-	switch (outcome.kind) {
-		case "fragment": return formatFragmentResult(outcome.result, source);
-		case "quiz": return formatQuizResult(outcome.result, source);
-		case "writing": return formatWritingResult(outcome.result, source);
-		case "coding": return formatCodingResult(outcome.result, source);
-		default: return formatResult(outcome.result, source);
-	}
+//#endregion
+//#region src/commands/reports.ts
+const SERVER_OPTION = ["--server <url>", "Novedu server base URL (defaults to the NOVEDU_SERVER env var, then production)"];
+function registerReports(program) {
+	const reports = program.command("reports").description("Triage student reports on the Novedu server");
+	reports.command("list").description("List reports (defaults to open reports on your own codes, like the web inbox)").option("--status <status>", "open (default), resolved or all").option("--reaction <reaction>", "filter by reaction: good, omg, bad or holysh").option("--search <q>", "contains-filter over description, reporter, code and note").option("--all", "include reports on codes created by other teachers").option(...SERVER_OPTION).action(async (options) => {
+		const params = new URLSearchParams();
+		if (options.status) params.set("status", options.status);
+		if (options.reaction) params.set("reaction", options.reaction);
+		if (options.search) params.set("q", options.search);
+		if (options.all) params.set("mine", "0");
+		const query = params.toString();
+		await runApiRequest({
+			server: options.server,
+			path: `/api/reports${query ? `?${query}` : ""}`
+		});
+	});
+	reports.command("show <id>").description("Show one report; a chat report embeds its conversation transcript").option(...SERVER_OPTION).action(async (id, options) => {
+		await runApiRequest({
+			server: options.server,
+			path: `/api/reports/${encodeURIComponent(id)}`
+		});
+	});
+	reports.command("resolve <id...>").description("Resolve one or more reports by id (bulk, in a single request)").option(...SERVER_OPTION).action(async (ids, options) => {
+		await runApiRequest({
+			server: options.server,
+			path: "/api/reports/resolve",
+			method: "POST",
+			body: { ids }
+		});
+	});
 }
 //#endregion
 //#region src/commands/whoami.ts
@@ -2962,10 +4994,11 @@ function registerWhoami(program) {
 }
 //#endregion
 //#region src/main.ts
-const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const program = new Command();
-program.name("novedu-cli").description("Command-line companion for the Novedu chat app").version(version);
+program.name("novedu-cli").description("Command-line companion for the Novedu chat app").version(cliVersion());
 registerValidate(program);
+registerPrompts(program);
+registerEval(program);
 registerLogin(program);
 registerLogout(program);
 registerWhoami(program);