@novedu/cli 0.19.0 → 0.21.0

package/dist/main.js

@@ -1,9 +1,9 @@
 #!/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";
@@ -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
@@ -876,173 +880,55 @@ 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");
-}
-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}` : ""}`
-		});
-	});
-}
+//#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/file-name.ts
+//#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;
 /**
-* 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`.
+* 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 `_`.
 */
-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;
-	}
-}
-//#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}` : ""}`
-		});
-	});
-}
-//#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)}.`);
-	});
+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));
 }
-//#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.");
-	});
+/** The confusion matrix's row key for an expected set (already canonical). */
+function expectedKey(expected) {
+	return expected.join("|");
 }
 //#endregion
 //#region ../lib/coding-proxy.ts
@@ -2705,15 +2591,9 @@ async function loadQuizFrom(url, fetcher, opts = {}) {
 		};
 	}
 }
-//#endregion
-//#region ../lib/quiz-verdict-schema.ts
-const QUIZ_VERDICT_SCHEMA = z.object({
-	result: z.enum([
-		"correct",
-		"partial",
-		"incorrect"
-	]),
-	feedback: z.string()
+const tutorToolNameSchema = z.enum(["random_number"]).meta({
+	id: "tutorToolName",
+	description: "Name of a built-in tutor tool."
 });
 //#endregion
 //#region ../lib/tutors/schemas.ts
@@ -2750,6 +2630,7 @@ const TutorSchema = z.strictObject({
 		id: "llm",
 		description: "The model and provider that back this tutor."
 	}),
+	tools: z.array(tutorToolNameSchema).default([]).meta({ description: "Optional built-in tools the tutor's model may call (e.g. random_number). Off by default; mention enabled tools in tutor_instructions so the model uses them." }),
 	prompt: z.strictObject({
 		fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries used by this tutor." }),
 		text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim via {{file \"alias\"}} markers." }),
@@ -2790,6 +2671,7 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 		model: tutor.llm.model,
 		provider: tutor.llm.provider,
 		imageInput: tutor.llm.imageInput ?? true,
+		tools: tutor.tools,
 		anonymous: tutor.anonymous ?? true,
 		title: tutor.title,
 		description: tutor.description,
@@ -2961,7 +2843,8 @@ const promptDumpers = {
 					provider: result.provider,
 					model: result.model
 				},
-				system: result.prompt
+				system: result.prompt,
+				tools: result.tools
 			}
 		};
 	} },
@@ -3074,267 +2957,12 @@ function promptSections(dump) {
 	}
 }
 //#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)}`);
-}
+//#region ../lib/quiz-schema.ts
 /**
-* 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) {
-	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 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 ../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/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).
+* 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({
@@ -3606,181 +3234,1655 @@ async function loadAndCheckQuiz(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;
+//#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 });
+	});
+}
 /**
-* 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).
+* 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).
 */
-function checkWritingParsed(writing) {
+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,
-		writingId: writing.id,
-		model: writing.llm.model,
-		provider: writing.llm.provider,
-		anonymous: writing.anonymous ?? DEFAULT_ANONYMOUS,
-		title: writing.title ?? null,
-		warnings: []
+		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));
 /**
-* 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.
+* 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 loadAndCheckWriting(url, fetchImpl, opts = {}) {
-	const yaml = await loadYaml(url, fetchImpl, opts);
-	if (!yaml.ok) return {
-		ok: false,
-		errors: [yaml.error],
-		warnings: []
+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))
 	};
-	const valid = validate(yaml.value, WritingYamlSchema, "WRITING_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
+}
+/** 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 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
+	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 {
-		...checked,
-		warnings
+		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;
 }
-//#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.
+* 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 toUrl(pathOrUrl) {
-	if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
-	return pathToFileURL(resolve(pathOrUrl)).href;
+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 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 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 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
-		}));
-		default: return loadAndBuildTutorPrompt(url, cliFetcher, {
-			allowedSchemes,
-			validateLibraries: true
-		}).then((result) => ({
-			kind,
-			result
-		}));
+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 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", `
-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
-
-  # 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;
+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) {
+	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.tools.length) lines.push(`  tools: ${result.tools.join(", ")}`);
+		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;
-	});
+		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");
 }
-/** 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);
+/** 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}`);
+	if (dump.kind === "tutor" && dump.tools.length > 0) lines.push(`  tools: ${dump.tools.join(", ")}`);
+	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 = [];
+	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
+		}));
+	}
+}
+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;
+		}
+		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);
+	}
+}
+//#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;
+		}
+		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)));
+	}
+	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 {
+		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
+		}
+	};
+}
+/**
+* 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 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
+	};
+}
+/**
+* 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
+		};
+	};
+}
+/** 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;
+	}
+	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
+/**
+* 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 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;
+	}
+}
+//#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}` : ""}`
+		});
+	});
+}
+//#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
@@ -3901,11 +5003,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);