@novedu/cli 0.8.0 → 0.10.0

package/dist/main.js

@@ -358,25 +358,34 @@ Purely local — already-issued access tokens stay valid until they expire
 	});
 }
 //#endregion
-//#region ../lib/tutors/assemble.ts
+//#region ../lib/prompt-fragments/assemble.ts
 const COMPILE_OPTIONS = {
 	strict: true,
 	noEscape: true
 };
 /**
-* Render each fragment in priority order and append the tutor-specific
-* instructions last (they carry no priority, so "after everything" is the only
-* deterministic position). May throw if a template references a missing variable.
+* Render each fragment in priority order and, when provided, append the caller's
+* trailing instructions last (they carry no priority, so "after everything" is the
+* only deterministic position — the exact role `tutor_instructions` plays for a
+* tutor, and the activity frame / `instructions` play for quiz / writing / coding).
+* May throw if a template references a missing variable.
+*
+* `trailingInstructions` is optional so a consumer can assemble a fragment-only
+* PREAMBLE (quiz / writing / coding) and concatenate its own frame afterwards. An
+* empty plan with no trailing text renders to the empty string (so an activity that
+* declares no fragments gets no stray whitespace); every non-empty result ends in a
+* single trailing newline, byte-identical to the historic tutor output.
 */
-function assembleSystemPrompt(plan, tutor) {
+function assembleSystemPrompt(plan, trailingInstructions) {
 	const parts = plan.map((fragment) => {
 		return Handlebars.compile(fragment.content, COMPILE_OPTIONS)(fragment.variables).trimEnd();
 	});
-	parts.push(tutor.prompt.tutor_instructions.trimEnd());
+	if (trailingInstructions !== void 0) parts.push(trailingInstructions.trimEnd());
+	if (parts.length === 0) return "";
 	return `${parts.join("\n\n")}\n`;
 }
 //#endregion
-//#region ../lib/tutors/errors.ts
+//#region ../lib/prompt-fragments/errors.ts
 /** Small helper to build an error object tersely at call sites. */
 function error(code, message, extra = {}) {
 	return {
@@ -413,7 +422,7 @@ function formatZodIssues(zodIssues) {
 	return out;
 }
 //#endregion
-//#region ../lib/tutors/consistency.ts
+//#region ../lib/prompt-fragments/consistency.ts
 /** Compare a supplied value against its declared property type. Returns null when it matches. */
 function typeMismatch(prop, value) {
 	const actual = Array.isArray(value) ? "array" : typeof value;
@@ -432,11 +441,11 @@ function typeMismatch(prop, value) {
 		};
 	}
 }
-function checkConsistency(tutor, fragmentFilesByAlias) {
+function checkConsistency(block, fragmentFilesByAlias) {
 	const errors = [];
 	const warnings = [];
 	const aliasCounts = /* @__PURE__ */ new Map();
-	for (const ref of tutor.prompt.fragment_files) aliasCounts.set(ref.id, (aliasCounts.get(ref.id) ?? 0) + 1);
+	for (const ref of block.fragment_files) aliasCounts.set(ref.id, (aliasCounts.get(ref.id) ?? 0) + 1);
 	for (const [alias, count] of aliasCounts) if (count > 1) errors.push(error("DUPLICATE_FRAGMENT_FILE_ALIAS", `Fragment-file alias "${alias}" is declared ${count} times`, { fileAlias: alias }));
 	const fragmentIndex = /* @__PURE__ */ new Map();
 	for (const [alias, file] of fragmentFilesByAlias) {
@@ -455,7 +464,7 @@ function checkConsistency(tutor, fragmentFilesByAlias) {
 	}
 	const resolved = [];
 	const seenRefs = /* @__PURE__ */ new Set();
-	for (const ref of tutor.prompt.fragments) {
+	for (const ref of block.fragments) {
 		const refKey = `${ref.file}::${ref.id}`;
 		if (seenRefs.has(refKey)) warnings.push(warning("DUPLICATE_FRAGMENT_REFERENCE", `Fragment "${ref.id}" from "${ref.file}" is referenced more than once`, {
 			fileAlias: ref.file,
@@ -547,7 +556,7 @@ function checkConsistency(tutor, fragmentFilesByAlias) {
 	};
 }
 //#endregion
-//#region ../lib/tutors/fetcher.ts
+//#region ../lib/prompt-fragments/fetcher.ts
 const DEFAULT_TIMEOUT_MS = 1e4;
 /** Production fetcher: global `fetch` with an abort-based timeout so a slow host can't hang the request. */
 const defaultFetcher = async (url) => {
@@ -563,7 +572,7 @@ const defaultFetcher = async (url) => {
 	}
 };
 //#endregion
-//#region ../lib/tutors/parse.ts
+//#region ../lib/prompt-fragments/parse.ts
 /** Parse a YAML document, mapping syntax errors to a structured `YAML_PARSE_ERROR`. */
 function parseYaml(text, url) {
 	try {
@@ -593,105 +602,117 @@ function validate(value, schema, code, url) {
 		})
 	};
 }
-const providerSchema = z.enum(["SCCH", "Azure Foundry"]).default("SCCH");
 //#endregion
-//#region ../lib/tutors/schemas.ts
+//#region ../lib/prompt-fragments/schemas.ts
 /**
 * A fragment-file reference: either an absolute http(s) URL or a relative path that
-* `load.ts` resolves against the tutor YAML's own URL. We reject any *other* absolute
+* `load.ts` resolves against the activity YAML's own URL. We reject any *other* absolute
 * scheme (`ftp:`, `mailto:`, …) so a typo can't smuggle in a non-http(s) target — the
 * refine reads as "if it carries a URI scheme at all, that scheme must be http(s)".
 * Strings without a scheme (relative paths) pass through and are resolved at load time.
+*
+* The `.refine()` is the RUNTIME enforcement. `z.toJSONSchema()` cannot derive a pattern
+* from a refinement, so the equivalent editor constraint is re-expressed via `.meta({ pattern })`
+* — the two MUST be kept consistent (both mean "http(s) URL or a scheme-less relative path").
 */
-const FragmentUrlRef = z.string().min(1).refine((u) => !/^[a-z][a-z0-9+.-]*:/i.test(u) || /^https?:\/\//i.test(u), { message: "Must be an http(s) URL or a relative path" });
+const FragmentUrlRef = z.string().min(1).refine((u) => !/^[a-z][a-z0-9+.-]*:/i.test(u) || /^https?:\/\//i.test(u), { message: "Must be an http(s) URL or a relative path" }).meta({
+	pattern: "^(https?://|(?![A-Za-z][A-Za-z0-9+.-]*:).+)$",
+	description: "HTTP(S) URL or relative path to the fragment library."
+});
 /**
 * A declared property is a string, a boolean, or an array of strings. Each may carry an
 * optional `default`, typed to match its `type` (a string default on a boolean property
-* is a schema error). When the tutor omits the variable, the default is used; supplying
+* is a schema error). When the activity omits the variable, the default is used; supplying
 * a value overrides it. See `consistency.ts` for where defaults are injected.
 */
+const StringPropertySchema = z.strictObject({
+	type: z.literal("string").meta({ description: "Declares a string variable." }),
+	default: z.string().optional().meta({ description: "Default string used when the activity omits this variable." })
+}).meta({
+	id: "stringProperty",
+	description: "A string variable, with an optional default."
+});
+const BooleanPropertySchema = z.strictObject({
+	type: z.literal("boolean").meta({ description: "Declares a boolean variable." }),
+	default: z.boolean().optional().meta({ description: "Default boolean used when the activity omits this variable." })
+}).meta({
+	id: "booleanProperty",
+	description: "A boolean variable, with an optional default."
+});
+const StringArrayPropertySchema = z.strictObject({
+	type: z.literal("array").meta({ description: "Declares an array-of-strings variable." }),
+	items: z.strictObject({ type: z.literal("string").meta({ description: "Array elements are strings." }) }).meta({ description: "The element type of the array (always string)." }),
+	default: z.array(z.string()).optional().meta({ description: "Default string array used when the activity omits this variable." })
+}).meta({
+	id: "stringArrayProperty",
+	description: "An array-of-strings variable, with an optional default."
+});
 const PropertySchema = z.discriminatedUnion("type", [
-	z.strictObject({
-		type: z.literal("string"),
-		default: z.string().optional()
-	}),
-	z.strictObject({
-		type: z.literal("boolean"),
-		default: z.boolean().optional()
-	}),
-	z.strictObject({
-		type: z.literal("array"),
-		items: z.strictObject({ type: z.literal("string") }),
-		default: z.array(z.string()).optional()
-	})
-]);
+	StringPropertySchema,
+	BooleanPropertySchema,
+	StringArrayPropertySchema
+]).meta({
+	id: "inputProperty",
+	description: "A declared variable: a string, a boolean, or an array of strings, each with an optional matching default."
+});
 const InputSchema = z.strictObject({
-	type: z.literal("object"),
-	required: z.array(z.string()).default([]),
-	properties: z.record(z.string(), PropertySchema).default({})
+	type: z.literal("object").meta({ description: "Always \"object\"." }),
+	required: z.array(z.string()).default([]).meta({ description: "Names of the variables that must be supplied." }),
+	properties: z.record(z.string(), PropertySchema).default({}).meta({ description: "The declared variables, keyed by variable name." })
+}).meta({
+	id: "inputSchema",
+	description: "A constrained mini JSON-schema declaring the variables a fragment accepts."
 });
 const ClassificationSchema = z.strictObject({
-	type: z.string(),
-	override_allowed: z.boolean().optional()
+	type: z.string().meta({ description: "Classification label for this fragment." }),
+	override_allowed: z.boolean().optional().meta({ description: "Whether an activity may override this classification." })
+}).meta({
+	id: "classification",
+	description: "Optional classification metadata for a fragment."
 });
 const FragmentSchema = z.strictObject({
-	id: z.string(),
-	version: z.number(),
-	priority: z.number(),
+	id: z.string().meta({ description: "Unique fragment id within this library." }),
+	version: z.number().meta({ description: "Fragment version number." }),
+	priority: z.number().meta({ description: "Assembly order. Lower priorities appear earlier." }),
 	input_schema: InputSchema.optional(),
 	classification: ClassificationSchema.optional(),
-	content: z.string()
+	content: z.string().meta({ description: "Prompt text as a Handlebars template." })
+}).meta({
+	id: "fragment",
+	description: "One reusable, parameterized prompt fragment."
 });
 const FragmentFileSchema = z.strictObject({
-	id: z.string(),
-	fragments: z.array(FragmentSchema).min(1)
+	id: z.string().meta({ description: "Machine-readable id of this fragment library." }),
+	fragments: z.array(FragmentSchema).min(1).meta({ description: "The reusable fragments this library provides (at least one)." })
 });
 /** A supplied variable value mirrors what `input_schema` can declare. */
 const VariableValueSchema = z.union([
 	z.string(),
 	z.boolean(),
 	z.array(z.string())
-]);
+]).meta({
+	id: "variableValue",
+	description: "A literal variable value: a string, a boolean, or an array of strings."
+});
 const FragmentFileRefSchema = z.strictObject({
-	id: z.string(),
+	id: z.string().meta({ description: "Local alias for this library, referenced by each fragment's `file`." }),
 	url: FragmentUrlRef
+}).meta({
+	id: "fragmentFileRef",
+	description: "A reference to a fragment library by alias + URL."
 });
 const FragmentRefSchema = z.strictObject({
-	file: z.string(),
-	id: z.string(),
-	variables: z.record(z.string(), VariableValueSchema).optional(),
-	bind: z.record(z.string(), z.string()).optional(),
-	required: z.boolean().optional()
-});
-/**
-* An example question offered to students on the welcome screen: the `title` is
-* the clickable label, the `question` is the full text placed into the chat
-* input on click. Tutors may define any number; the UI samples at most 5.
-*/
-const ExampleQuestionSchema = z.strictObject({
-	title: z.string().min(1),
-	question: z.string().min(1)
-});
-const TutorSchema = z.strictObject({
-	id: z.string(),
-	name: z.string(),
-	title: z.string().optional(),
-	description: z.string(),
-	exampleQuestions: z.array(ExampleQuestionSchema).optional(),
-	anonymous: z.boolean().optional(),
-	llm: z.strictObject({
-		model: z.string(),
-		provider: providerSchema,
-		imageInput: z.boolean().optional()
-	}),
-	prompt: z.strictObject({
-		fragment_files: z.array(FragmentFileRefSchema).default([]),
-		fragments: z.array(FragmentRefSchema).default([]),
-		tutor_instructions: z.string()
-	})
+	file: z.string().meta({ description: "The alias of the fragment library this fragment is drawn from." }),
+	id: z.string().meta({ description: "Fragment id inside the referenced library." }),
+	variables: z.record(z.string(), VariableValueSchema).optional().meta({ description: "Literal values passed into the fragment template." }),
+	bind: z.record(z.string(), z.string()).optional().meta({ description: "Accepted for compatibility but ignored by the current assembler." }),
+	required: z.boolean().optional().meta({ description: "Marker for important fragments. Accepted but not currently enforced." })
+}).meta({
+	id: "fragmentRef",
+	description: "Selects one fragment from a referenced library."
 });
 //#endregion
-//#region ../lib/tutors/fragment.ts
+//#region ../lib/prompt-fragments/fragment.ts
 /**
 * A placeholder value for a declared input, shaped to its type so the template
 * actually exercises it: a string renders, a boolean drives `{{#if}}`, an array
@@ -794,17 +815,17 @@ function resolveRelativeUrl(ref, baseUrl) {
 	return new URL(ref, baseUrl).href;
 }
 //#endregion
-//#region ../lib/tutors/load.ts
+//#region ../lib/prompt-fragments/load.ts
 /**
 * Resolve a fragment-file reference to an absolute URL. An absolute http(s) ref is used
-* as-is; anything else is treated as relative to the tutor URL — standard URL resolution
-* drops the tutor's filename and appends the relative path (so `my-fragments.yaml`
+* as-is; anything else is treated as relative to the activity URL — standard URL resolution
+* drops the activity's filename and appends the relative path (so `my-fragments.yaml`
 * next to `.../tutors/my-tutor.yaml` becomes `.../tutors/my-fragments.yaml`,
 * and `./` / `../` segments work too). Throws if a relative ref is unparseable; the schema
 * already guarantees the only inputs here are http(s) URLs or relative paths.
 */
-function resolveFragmentUrl(ref, tutorUrl) {
-	return resolveRelativeUrl(ref, tutorUrl);
+function resolveFragmentUrl(ref, baseUrl) {
+	return resolveRelativeUrl(ref, baseUrl);
 }
 async function fetchText(url, fetchImpl) {
 	try {
@@ -829,23 +850,33 @@ async function fetchText(url, fetchImpl) {
 }
 const DEFAULT_ALLOWED_SCHEMES = ["http:", "https:"];
 /**
-* The shared front of every load: enforce the URL scheme allow-list (SSRF guard),
-* fetch the document, and parse it as YAML — returning the parsed-but-not-yet-schema-
-* validated value or the first structured error. Reused by the tutor builder, the
-* standalone fragment checker, and the quiz/writing validators so they all gate
-* schemes identically.
+* The SSRF scheme gate shared by the top-level activity load (`loadYaml`) and every
+* fragment-file fetch (`assembleFragmentPrompt`): a URL is allowed only if its scheme
+* is in `allowedSchemes` (default http(s); the CLI adds `file:` for on-disk validation).
+* Returns the structured error to surface, or `null` when the scheme is allowed.
 */
-async function loadYaml(url, fetchImpl, opts = {}) {
-	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
+function schemeGate(url, allowedSchemes) {
 	let scheme;
 	try {
 		scheme = new URL(url).protocol;
 	} catch {
 		scheme = "";
 	}
-	if (!allowedSchemes.includes(scheme)) return {
+	if (allowedSchemes.includes(scheme)) return null;
+	return error("INVALID_URL", `Provide a valid ${allowedSchemes.map((s) => s.replace(/:$/, "")).join("/")} URL`, { url });
+}
+/**
+* The shared front of every load: enforce the URL scheme allow-list (SSRF guard),
+* fetch the document, and parse it as YAML — returning the parsed-but-not-yet-schema-
+* validated value or the first structured error. Reused by the activity builders, the
+* standalone fragment checker, and the quiz/writing/coding validators so they all gate
+* schemes identically.
+*/
+async function loadYaml(url, fetchImpl, opts = {}) {
+	const schemeError = schemeGate(url, opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES);
+	if (schemeError) return {
 		ok: false,
-		error: error("INVALID_URL", `Provide a valid ${allowedSchemes.map((s) => s.replace(/:$/, "")).join("/")} URL`, { url })
+		error: schemeError
 	};
 	const fetched = await fetchText(url, fetchImpl);
 	if (!fetched.ok) return {
@@ -862,25 +893,30 @@ async function loadYaml(url, fetchImpl, opts = {}) {
 		value: parsed.value
 	};
 }
-async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
+/**
+* Resolve a document-level fragment block to a finished prompt string: fetch every
+* declared fragment file in parallel (relative refs resolved against `baseUrl`),
+* schema-validate each, (optionally) run the thorough whole-library check, check
+* consistency, and assemble the priority-ordered plan followed by the optional
+* `trailingInstructions`.
+*
+* The single seam every activity kind shares — the sole owner of the fetch → validate
+* → consistency → assemble pipeline. Consumers concatenate their own frame only when
+* they pass no `trailingInstructions` (a fragment-only preamble); tutors pass their
+* `tutor_instructions` and get a complete prompt.
+*/
+async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, trailingInstructions) {
 	const warnings = [];
-	const tutorYaml = await loadYaml(url, fetchImpl, opts);
-	if (!tutorYaml.ok) return {
-		ok: false,
-		errors: [tutorYaml.error],
-		warnings
-	};
-	const tutorValid = validate(tutorYaml.value, TutorSchema, "TUTOR_SCHEMA_ERROR", url);
-	if (!tutorValid.ok) return {
-		ok: false,
-		errors: [tutorValid.error],
+	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
+	if (block.fragment_files.length === 0 && block.fragments.length === 0) return {
+		ok: true,
+		prompt: assembleSystemPrompt([], trailingInstructions),
 		warnings
 	};
-	const tutor = tutorValid.data;
-	const settled = await Promise.all(tutor.prompt.fragment_files.map(async (ref) => {
+	const settled = await Promise.all(block.fragment_files.map(async (ref) => {
 		let fragmentUrl;
 		try {
-			fragmentUrl = resolveFragmentUrl(ref.url, url);
+			fragmentUrl = resolveFragmentUrl(ref.url, baseUrl);
 		} catch {
 			return {
 				alias: ref.id,
@@ -890,6 +926,14 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 				})
 			};
 		}
+		const schemeError = schemeGate(fragmentUrl, allowedSchemes);
+		if (schemeError) return {
+			alias: ref.id,
+			error: {
+				...schemeError,
+				fileAlias: ref.id
+			}
+		};
 		const fetched = await fetchText(fragmentUrl, fetchImpl);
 		if (!fetched.ok) return {
 			alias: ref.id,
@@ -936,7 +980,7 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 		libraryErrors.push(...checked.errors);
 		warnings.push(...checked.warnings);
 	}
-	const consistency = checkConsistency(tutor, fragmentFilesByAlias);
+	const consistency = checkConsistency(block, fragmentFilesByAlias);
 	warnings.push(...consistency.warnings);
 	const preAssemblyErrors = [...libraryErrors, ...consistency.errors];
 	if (preAssemblyErrors.length > 0) return {
@@ -947,14 +991,7 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 	try {
 		return {
 			ok: true,
-			prompt: assembleSystemPrompt(consistency.plan, tutor),
-			model: tutor.llm.model,
-			provider: tutor.llm.provider,
-			imageInput: tutor.llm.imageInput ?? true,
-			anonymous: tutor.anonymous ?? true,
-			title: tutor.title,
-			description: tutor.description,
-			exampleQuestions: tutor.exampleQuestions ?? [],
+			prompt: assembleSystemPrompt(consistency.plan, trailingInstructions),
 			warnings
 		};
 	} catch (e) {
@@ -968,9 +1005,9 @@ async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
 /**
 * Validate a fragment FILE on its own (the `--kind fragment` / "Fragment library"
 * path): scheme-gate + fetch + parse, then the pure `checkFragmentFileValue`. A
-* fragment library is self-contained, so — unlike a tutor — there are no further
+* fragment library is self-contained, so — unlike an activity — there are no further
 * files to fetch. The caller already knows it asked for a fragment, so this returns
-* a `FragmentCheckResult` directly (no tutor `BuildResult`, no kind discriminator).
+* a `FragmentCheckResult` directly (no activity `BuildResult`, no kind discriminator).
 */
 async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	const yaml = await loadYaml(url, fetchImpl, opts);
@@ -981,33 +1018,32 @@ async function loadAndCheckFragmentFile(url, fetchImpl, opts = {}) {
 	};
 	return checkFragmentFileValue(yaml.value, url);
 }
+const providerSchema = z.enum(["SCCH", "Azure Foundry"]).default("SCCH").meta({ description: "The LLM provider serving the model. For Azure Foundry, model is the deployment name." });
 //#endregion
 //#region ../lib/coding-schema.ts
 const CodingYamlSchema = z.strictObject({
-	id: z.string().min(1),
-	name: z.string().optional(),
-	title: z.string().optional(),
+	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),
+		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."
 	}),
-	instructions: z.string().min(1)
+	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
+	fragments: z.array(FragmentRefSchema).default([]).meta({ description: "Optional fragments selected from fragment_files. Assembled in priority order and prepended AHEAD of instructions." }),
+	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." })
 });
 //#endregion
 //#region ../lib/coding-validate.ts
 /**
-* Validate an already-parsed coding value against its schema, then extract metadata.
-* Pure (the parsed value is passed in); `loadAndCheckCoding` wraps it with fetch +
-* YAML parse.
+* 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 checkCodingValue(parsed, url) {
-	const valid = validate(parsed, CodingYamlSchema, "CODING_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
-	};
-	const coding = valid.data;
+function checkCodingParsed(coding) {
 	return {
 		ok: true,
 		codingId: coding.id,
@@ -1029,16 +1065,46 @@ async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
 		errors: [yaml.error],
 		warnings: []
 	};
-	return checkCodingValue(yaml.value, url);
+	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,
+		fragments: valid.data.fragments
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	});
+	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
 /** An optional content image attached to a question (carries no secret). */
 const ImageRefSchema = z.strictObject({
-	hosted: z.boolean().optional(),
-	src: z.string().min(1),
-	alt: z.string().optional(),
-	credit: z.string().optional()
+	hosted: z.boolean().optional().meta({
+		default: false,
+		description: "When true, src is an app-hosted image NAME resolved server-side; otherwise src is an absolute URL or a path relative to the quiz's own URL."
+	}),
+	src: z.string().min(1).meta({ description: "The hosted image name (when hosted) or the image URL / relative path." }),
+	alt: z.string().optional().meta({ description: "Accessible description shown if the image cannot be loaded." }),
+	credit: z.string().optional().meta({ description: "Optional attribution (\"Content Credentials\") shown small below the image." })
+}).meta({
+	id: "image",
+	description: "An optional content image attached to a question."
 });
 /**
 * One question. `id` keys the per-question stats (must be unique — see
@@ -1046,25 +1112,47 @@ const ImageRefSchema = z.strictObject({
 * `evaluation` is the server-only grading prompt.
 */
 const QuizQuestionSchema = z.strictObject({
-	id: z.string().min(1),
-	title: z.string().optional(),
-	question: z.string().min(1),
-	evaluation: z.string().min(1),
-	image: ImageRefSchema.optional()
+	id: z.string().min(1).meta({ description: "Stable question id, unique within the quiz (the per-question stats key)." }),
+	title: z.string().optional().meta({ description: "Optional short label for the stats table and progress display." }),
+	question: z.string().min(1).meta({ description: "The Markdown shown to the student." }),
+	evaluation: z.string().min(1).meta({ description: "The grading prompt. SERVER-ONLY: never sent to the browser, so it may embed the expected answer and the grading rubric." }),
+	image: ImageRefSchema.optional(),
+	imageInput: z.boolean().optional().meta({ description: "Overrides the quiz-level llm.imageInput for this question only (photo answers on/off)." })
+}).meta({
+	id: "question",
+	description: "One open-ended, LLM-graded quiz question."
 });
 const QuizYamlSchema = z.strictObject({
-	id: z.string().min(1),
-	name: z.string().optional(),
-	title: z.string().optional(),
-	description: z.string().optional(),
-	anonymous: z.boolean().optional(),
-	shuffle: z.boolean().optional(),
+	id: z.string().min(1).meta({ description: "Short machine-readable quiz id, e.g. countries-basics. Used as the per-quiz identity." }),
+	name: z.string().optional().meta({ description: "Optional human-readable quiz title (used as a label)." }),
+	title: z.string().optional().meta({ description: "Optional greeting shown to students on the welcome screen instead of the default message." }),
+	description: z.string().optional().meta({ description: "Optional description shown to students below the welcome greeting (Markdown)." }),
+	anonymous: z.boolean().optional().meta({
+		default: true,
+		description: "Quizzes are anonymous by default: answers are recorded for aggregate stats but not linked to a student. Set to false to attribute each attempt to the signed-in student."
+	}),
+	shuffle: z.boolean().optional().meta({
+		default: true,
+		description: "Present questions in a random order per attempt. Set to false to keep the authored order."
+	}),
 	llm: z.strictObject({
-		model: z.string().min(1),
-		provider: providerSchema
+		model: z.string().min(1).meta({ description: "The model that grades answers and drives the per-question discussion chat." }),
+		provider: providerSchema,
+		imageInput: z.boolean().optional().meta({
+			default: false,
+			description: "Default for all questions: students may attach photos (up to 3, 5 MB each) to their answers. The model must be vision-capable. A per-question imageInput overrides it."
+		})
+	}).meta({
+		id: "llm",
+		description: "The single model + provider that grades and discusses answers."
+	}),
+	discussion: z.strictObject({ instructions: z.string().min(1).meta({ description: "Optional guidance appended to the per-question follow-up discussion chat's system prompt." }) }).optional().meta({
+		id: "discussion",
+		description: "Optional guidance for the per-question follow-up discussion chat."
 	}),
-	discussion: z.strictObject({ instructions: z.string().min(1) }).optional(),
-	questions: z.array(QuizQuestionSchema).min(1)
+	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this quiz pulls shared prompt fragments from." }),
+	fragments: z.array(FragmentRefSchema).default([]).meta({ description: "Optional fragments selected from fragment_files. Assembled in priority order and prepended to BOTH the grader prompt and the discussion chat's system prompt." }),
+	questions: z.array(QuizQuestionSchema).min(1).meta({ description: "The quiz questions. Each is open-ended and graded by the LLM via its evaluation prompt." })
 });
 //#endregion
 //#region ../lib/quiz-validate.ts
@@ -1084,18 +1172,11 @@ function findDuplicateQuestionIds(quiz) {
 	return errors;
 }
 /**
-* Validate an already-parsed quiz value: schema → unique question ids → metadata.
-* Pure (the parsed value is passed in); `loadAndCheckQuiz` wraps it with fetch +
-* YAML parse.
+* Check an already-schema-validated quiz: unique question ids → metadata. Split from
+* `checkQuizValue` so `loadAndCheckQuiz` can reuse the single `validate` it already ran
+* (no second parse of the same document against the same schema).
 */
-function checkQuizValue(parsed, url) {
-	const valid = validate(parsed, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
-	};
-	const quiz = valid.data;
+function checkQuizParsed(quiz) {
 	const errors = findDuplicateQuestionIds(quiz);
 	if (errors.length > 0) return {
 		ok: false,
@@ -1114,9 +1195,11 @@ function checkQuizValue(parsed, url) {
 	};
 }
 /**
-* Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), then the
-* pure `checkQuizValue`. The web app passes the default http(s)-only schemes; the
-* CLI adds `file:` so a local quiz YAML on disk validates too.
+* Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), the pure
+* `checkQuizValue`, then the document-level fragment block's authoring gate — fetch
+* every referenced library, run the THOROUGH whole-library check, consistency, and an
+* assembly dry-run (the strict-Handlebars backstop). The web app passes the default
+* http(s)-only schemes; the CLI adds `file:` so a local quiz YAML on disk validates too.
 */
 async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 	const yaml = await loadYaml(url, fetchImpl, opts);
@@ -1125,40 +1208,146 @@ async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 		errors: [yaml.error],
 		warnings: []
 	};
-	return checkQuizValue(yaml.value, url);
+	const valid = validate(yaml.value, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", url);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [valid.error],
+		warnings: []
+	};
+	const checked = checkQuizParsed(valid.data);
+	if (!checked.ok) return checked;
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		fragments: valid.data.fragments
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	});
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
+}
+//#endregion
+//#region ../lib/tutors/schemas.ts
+/**
+* An example question offered to students on the welcome screen: the `title` is
+* the clickable label, the `question` is the full text placed into the chat
+* input on click. Tutors may define any number; the UI samples at most 5.
+*/
+const ExampleQuestionSchema = z.strictObject({
+	title: z.string().min(1).meta({ description: "Short clickable label shown on the welcome screen." }),
+	question: z.string().min(1).meta({ description: "Full question text. Shown as a tooltip and placed into the chat input on click." })
+}).meta({
+	id: "exampleQuestion",
+	description: "An example question shown on the welcome screen."
+});
+const TutorSchema = z.strictObject({
+	id: z.string().meta({ description: "Short machine-readable tutor id, e.g. fractions-de." }),
+	name: z.string().meta({ description: "Human-readable tutor title." }),
+	title: z.string().optional().meta({ description: "Optional greeting shown to students on the empty chat instead of the default welcome message." }),
+	description: z.string().meta({ description: "Short description of what this tutor does. Shown to students below the welcome greeting." }),
+	exampleQuestions: z.array(ExampleQuestionSchema).optional().meta({ description: "Optional example questions shown to students below the description on the empty chat. Clicking one puts the question text into the chat input. At most 5 are shown; with more, a random 5 are picked per page load." }),
+	anonymous: z.boolean().optional().meta({
+		default: true,
+		description: "Chats are anonymous by default: no link between the signed-in student and their chat is stored. Set to false to record which student each chat belongs to."
+	}),
+	llm: z.strictObject({
+		model: z.string().meta({ description: "Model used for this tutor." }),
+		provider: providerSchema,
+		imageInput: z.boolean().optional().meta({
+			default: true,
+			description: "Image uploads are enabled by default. Set to false to hide the upload UI for text-only tutors or non-vision-capable models."
+		})
+	}).meta({
+		id: "llm",
+		description: "The model and provider that back this tutor."
+	}),
+	prompt: z.strictObject({
+		fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries used by this tutor." }),
+		fragments: z.array(FragmentRefSchema).default([]).meta({ description: "Optional fragments selected from fragment_files." }),
+		tutor_instructions: z.string().meta({ description: "Final tutor-specific system-prompt instructions. For single-file tutors, this can be the whole prompt." })
+	}).meta({
+		id: "prompt",
+		description: "The assembled system prompt: fragments plus tutor instructions."
+	})
+});
+//#endregion
+//#region ../lib/tutors/load.ts
+async function loadAndBuildTutorPrompt(url, fetchImpl, opts = {}) {
+	const warnings = [];
+	const tutorYaml = await loadYaml(url, fetchImpl, opts);
+	if (!tutorYaml.ok) return {
+		ok: false,
+		errors: [tutorYaml.error],
+		warnings
+	};
+	const tutorValid = validate(tutorYaml.value, TutorSchema, "TUTOR_SCHEMA_ERROR", url);
+	if (!tutorValid.ok) return {
+		ok: false,
+		errors: [tutorValid.error],
+		warnings
+	};
+	const tutor = tutorValid.data;
+	const assembled = await assembleFragmentPrompt(tutor.prompt, url, fetchImpl, opts, tutor.prompt.tutor_instructions);
+	warnings.push(...assembled.warnings);
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		ok: true,
+		prompt: assembled.prompt,
+		model: tutor.llm.model,
+		provider: tutor.llm.provider,
+		imageInput: tutor.llm.imageInput ?? true,
+		anonymous: tutor.anonymous ?? true,
+		title: tutor.title,
+		description: tutor.description,
+		exampleQuestions: tutor.exampleQuestions ?? [],
+		warnings
+	};
 }
 //#endregion
 //#region ../lib/writing-schema.ts
 const WritingYamlSchema = z.strictObject({
-	id: z.string().min(1),
-	name: z.string().optional(),
-	title: z.string().optional(),
-	description: z.string().optional(),
-	anonymous: z.boolean().optional(),
+	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),
+		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."
 	}),
-	instructions: z.string().min(1),
-	placeholder: z.string().optional()
+	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this activity pulls shared prompt fragments from." }),
+	fragments: z.array(FragmentRefSchema).default([]).meta({ description: "Optional fragments selected from fragment_files. Assembled in priority order and prepended AHEAD of instructions." }),
+	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." }),
+	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;
 /**
-* Validate an already-parsed writing value against its schema, then extract metadata.
-* Pure (the parsed value is passed in); `loadAndCheckWriting` wraps it with fetch +
-* YAML parse.
+* 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 checkWritingValue(parsed, url) {
-	const valid = validate(parsed, WritingYamlSchema, "WRITING_SCHEMA_ERROR", url);
-	if (!valid.ok) return {
-		ok: false,
-		errors: [valid.error],
-		warnings: []
-	};
-	const writing = valid.data;
+function checkWritingParsed(writing) {
 	return {
 		ok: true,
 		writingId: writing.id,
@@ -1181,7 +1370,31 @@ async function loadAndCheckWriting(url, fetchImpl, opts = {}) {
 		errors: [yaml.error],
 		warnings: []
 	};
-	return checkWritingValue(yaml.value, url);
+	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,
+		fragments: valid.data.fragments
+	}, url, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	});
+	const warnings = [...checked.warnings, ...assembled.warnings];
+	if (!assembled.ok) return {
+		ok: false,
+		errors: assembled.errors,
+		warnings
+	};
+	return {
+		...checked,
+		warnings
+	};
 }
 //#endregion
 //#region src/file-fetcher.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novedu/cli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Command-line companion for the Novedu chat app. Validates tutor, fragment, quiz, writing and coding YAML definitions; signs in with Entra ID and manages codes and app-hosted files over the app's API.",
   "type": "module",
   "repository": {
@@ -25,13 +25,13 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@azure/msal-node": "^5.3.1",
+    "@azure/msal-node": "^5.4.0",
     "commander": "^15.0.0",
     "handlebars": "^4.7.9",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "tsdown": "^0.22.3"
+    "tsdown": "^0.22.4"
   }
 }