@novedu/cli 0.12.1 → 0.14.0

package/dist/main.js

@@ -396,25 +396,13 @@ const COMPILE_OPTIONS = {
 	noEscape: true
 };
 /**
-* 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.
+* Compile and render a single fragment's `content` with the merged variables. Shared
+* by the host-template `fragment` helper (real render) so the produced text is
+* byte-identical to what the standalone fragment check exercises. May throw if the
+* template references a variable not in `variables` (strict mode).
 */
-function assembleSystemPrompt(plan, trailingInstructions) {
-	const parts = plan.map((fragment) => {
-		return Handlebars.compile(fragment.content, COMPILE_OPTIONS)(fragment.variables).trimEnd();
-	});
-	if (trailingInstructions !== void 0) parts.push(trailingInstructions.trimEnd());
-	if (parts.length === 0) return "";
-	return `${parts.join("\n\n")}\n`;
+function renderFragmentContent(content, variables) {
+	return Handlebars.compile(content, COMPILE_OPTIONS)(variables);
 }
 //#endregion
 //#region ../lib/prompt-fragments/errors.ts
@@ -454,6 +442,41 @@ function formatZodIssues(zodIssues) {
 	return out;
 }
 //#endregion
+//#region ../lib/prompt-fragments/text-files.ts
+/**
+* Split a body into logical lines for range slicing. `body.split("\n")` yields a
+* trailing empty element for a body that ends in a newline (`"a\n"` → `["a", ""]`); we
+* drop exactly ONE such trailing element so a conventional newline-terminated file
+* reports its real line count (`"a\n"` is one line, not two). An empty body is zero
+* lines. NB: this is ONLY for line-range math — a no-range `{{file}}` renders the body
+* byte-for-byte (see `load.ts`), trailing newline and all.
+*/
+function toLines(body) {
+	if (body === "") return [];
+	const lines = body.split("\n");
+	if (lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+/** The number of logical lines in `body` (a newline-terminated final line is not double-counted). */
+function countLines(body) {
+	return toLines(body).length;
+}
+/**
+* Slice `body` to the 1-based inclusive line range `[from, to]` and re-join with `"\n"`,
+* appending nothing. `from` alone means "line `from` to end of file"; `to` alone means
+* "line 1 to `to`". `to` beyond EOF CLAMPS to end-of-file (native `Array.slice`
+* behaviour) — the runtime's graceful-degradation contract when a source file was
+* shortened after validation. The `from` lower bound is enforced by the caller
+* (`checkPlacements` errors on `from` beyond EOF), because an empty splice would
+* silently drop material.
+*/
+function sliceLines(body, from, to) {
+	const lines = toLines(body);
+	const start = from !== void 0 ? from - 1 : 0;
+	const end = to !== void 0 ? to : lines.length;
+	return lines.slice(start, end).join("\n");
+}
+//#endregion
 //#region ../lib/prompt-fragments/consistency.ts
 /** Compare a supplied value against its declared property type. Returns null when it matches. */
 function typeMismatch(prop, value) {
@@ -473,120 +496,197 @@ function typeMismatch(prop, value) {
 		};
 	}
 }
-function checkConsistency(block, fragmentFilesByAlias) {
+/** Split an inline reference at the FIRST dot: aliases cannot contain dots, ids may. */
+function splitFragmentRef(ref) {
+	const dot = ref.indexOf(".");
+	if (dot === -1) return {
+		alias: ref,
+		fragmentId: ""
+	};
+	return {
+		alias: ref.slice(0, dot),
+		fragmentId: ref.slice(dot + 1)
+	};
+}
+/**
+* Resolve one `"alias.id"` reference against the fetched libraries and validate its
+* inline args against the fragment's `input_schema` — required present, types correct,
+* undeclared flagged, optional defaults filled in (a supplied value always wins). The
+* same required/type/undeclared/defaults machinery that ran per document-level ref
+* before, now per placement.
+*/
+function resolveAndMerge(ref, args, filesByAlias) {
+	const errors = [];
+	const warnings = [];
+	const { alias, fragmentId } = splitFragmentRef(ref);
+	const file = filesByAlias.get(alias);
+	if (!file) {
+		errors.push(error("UNKNOWN_FRAGMENT_FILE_ALIAS", `Fragment marker "${ref}" uses unknown file alias "${alias}"`, {
+			fileAlias: alias,
+			fragmentId
+		}));
+		return {
+			errors,
+			warnings,
+			variables: args,
+			content: null
+		};
+	}
+	const fragment = file.fragments.find((f) => f.id === fragmentId);
+	if (!fragment) {
+		errors.push(error("FRAGMENT_NOT_FOUND", `Fragment "${fragmentId}" not found in file "${alias}"`, {
+			fileAlias: alias,
+			fragmentId
+		}));
+		return {
+			errors,
+			warnings,
+			variables: args,
+			content: null
+		};
+	}
+	return {
+		errors,
+		warnings,
+		variables: mergeVariables(alias, fragment, args, errors, warnings),
+		content: fragment.content
+	};
+}
+/** Validate `args` against `fragment.input_schema` and merge in optional defaults. */
+function mergeVariables(alias, fragment, args, errors, warnings) {
+	const merged = { ...args };
+	const schema = fragment.input_schema;
+	const id = fragment.id;
+	if (!schema) {
+		for (const name of Object.keys(args)) warnings.push(warning("UNDECLARED_VARIABLE", `Variable "${name}" supplied to "${id}", which declares no input schema`, {
+			fileAlias: alias,
+			fragmentId: id,
+			variable: name
+		}));
+		return merged;
+	}
+	for (const name of schema.required) if (!(name in args)) errors.push(error("MISSING_REQUIRED_VARIABLE", `Fragment "${id}" requires variable "${name}", which is not supplied`, {
+		fileAlias: alias,
+		fragmentId: id,
+		variable: name
+	}));
+	for (const [name, value] of Object.entries(args)) {
+		const prop = schema.properties[name];
+		if (!prop) {
+			warnings.push(warning("UNDECLARED_VARIABLE", `Variable "${name}" supplied to "${id}" is not declared in its input schema`, {
+				fileAlias: alias,
+				fragmentId: id,
+				variable: name
+			}));
+			continue;
+		}
+		const mismatch = typeMismatch(prop, value);
+		if (mismatch) errors.push(error("VARIABLE_TYPE_MISMATCH", `Variable "${name}" of "${id}" should be ${mismatch.expected} but got ${mismatch.actual}`, {
+			fileAlias: alias,
+			fragmentId: id,
+			variable: name,
+			expectedType: mismatch.expected,
+			actualType: mismatch.actual
+		}));
+	}
+	const requiredSet = new Set(schema.required);
+	for (const [name, prop] of Object.entries(schema.properties)) {
+		if (prop.default === void 0) continue;
+		if (requiredSet.has(name)) {
+			warnings.push(warning("REQUIRED_PROPERTY_HAS_DEFAULT", `Variable "${name}" of "${id}" is required, so its default is never used`, {
+				fileAlias: alias,
+				fragmentId: id,
+				variable: name
+			}));
+			continue;
+		}
+		if (!(name in merged)) merged[name] = prop.default;
+	}
+	return merged;
+}
+/**
+* Cross-check every inline placement against the declared libraries AND text files:
+* duplicate aliases (fragment libraries, text files, and collisions ACROSS the two —
+* one shared alias namespace), duplicate fragment ids within a file, each `{{fragment}}`
+* placement's `alias.id` resolution + variable validation (via `resolveAndMerge`), each
+* `{{file}}` placement's alias resolution + line-range bounds, and a warning for any
+* declared library / text file no placement ever uses. Errors block the build; the rest
+* are warnings. Order-independent — placements carry their own textual position.
+*
+* `textFilesByAlias` maps a declared text-file alias to its FETCHED body (needed for the
+* range bounds check); `strict` is the authoring-strictness flag — when set (authoring
+* validators / CLI), a `to` beyond EOF is an error too, whereas at runtime (`strict:
+* false`) the render layer clamps `to` to EOF instead. A `from` beyond EOF is ALWAYS an
+* error (an empty splice would silently drop material). The new params default so the
+* legacy fragment-only call sites (and their tests) need no change; the one real caller
+* (`load.ts`) always passes the text side explicitly.
+*/
+function checkPlacements(placements, filesByAlias, fileRefs, textFilesByAlias = /* @__PURE__ */ new Map(), textFileRefs = [], strict = false) {
 	const errors = [];
 	const warnings = [];
 	const aliasCounts = /* @__PURE__ */ new Map();
-	for (const ref of block.fragment_files) aliasCounts.set(ref.id, (aliasCounts.get(ref.id) ?? 0) + 1);
+	for (const ref of fileRefs) 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) {
-		const byId = /* @__PURE__ */ new Map();
+	const fragmentAliases = new Set(fileRefs.map((r) => r.id));
+	const textAliasCounts = /* @__PURE__ */ new Map();
+	for (const ref of textFileRefs) textAliasCounts.set(ref.id, (textAliasCounts.get(ref.id) ?? 0) + 1);
+	for (const [alias, count] of textAliasCounts) if (count > 1) errors.push(error("DUPLICATE_TEXT_FILE_ALIAS", `Text-file alias "${alias}" is declared ${count} times`, { fileAlias: alias }));
+	else if (fragmentAliases.has(alias)) errors.push(error("DUPLICATE_TEXT_FILE_ALIAS", `Alias "${alias}" is declared as both a fragment library and a text file`, { fileAlias: alias }));
+	for (const [alias, file] of filesByAlias) {
+		const seen = /* @__PURE__ */ new Set();
 		for (const frag of file.fragments) {
-			if (byId.has(frag.id)) {
+			if (seen.has(frag.id)) {
 				errors.push(error("DUPLICATE_FRAGMENT_ID_IN_FILE", `Fragment "${frag.id}" is declared more than once in file "${alias}"`, {
 					fileAlias: alias,
 					fragmentId: frag.id
 				}));
 				continue;
 			}
-			byId.set(frag.id, frag);
+			seen.add(frag.id);
 		}
-		fragmentIndex.set(alias, byId);
 	}
-	const resolved = [];
-	const seenRefs = /* @__PURE__ */ new Set();
-	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,
-			fragmentId: ref.id
-		}));
-		seenRefs.add(refKey);
-		const byId = fragmentIndex.get(ref.file);
-		if (!byId) {
-			errors.push(error("UNKNOWN_FRAGMENT_FILE_ALIAS", `Fragment reference uses unknown file alias "${ref.file}"`, {
-				fileAlias: ref.file,
-				fragmentId: ref.id
-			}));
-			continue;
-		}
-		const fragment = byId.get(ref.id);
-		if (!fragment) {
-			errors.push(error("FRAGMENT_NOT_FOUND", `Fragment "${ref.id}" not found in file "${ref.file}"`, {
-				fileAlias: ref.file,
-				fragmentId: ref.id
-			}));
+	const usedAliases = /* @__PURE__ */ new Set();
+	const usedTextAliases = /* @__PURE__ */ new Set();
+	for (const placement of placements) {
+		if (placement.kind === "file") {
+			checkFilePlacement(placement, textFilesByAlias, strict, errors);
+			usedTextAliases.add(placement.ref);
 			continue;
 		}
-		const variables = ref.variables ?? {};
-		const schema = fragment.input_schema;
-		const merged = { ...variables };
-		if (schema) {
-			for (const name of schema.required) if (!(name in variables)) errors.push(error("MISSING_REQUIRED_VARIABLE", `Fragment "${ref.id}" requires variable "${name}", which is not supplied`, {
-				fileAlias: ref.file,
-				fragmentId: ref.id,
-				variable: name
-			}));
-			for (const [name, value] of Object.entries(variables)) {
-				const prop = schema.properties[name];
-				if (!prop) {
-					warnings.push(warning("UNDECLARED_VARIABLE", `Variable "${name}" supplied to "${ref.id}" is not declared in its input schema`, {
-						fileAlias: ref.file,
-						fragmentId: ref.id,
-						variable: name
-					}));
-					continue;
-				}
-				const mismatch = typeMismatch(prop, value);
-				if (mismatch) errors.push(error("VARIABLE_TYPE_MISMATCH", `Variable "${name}" of "${ref.id}" should be ${mismatch.expected} but got ${mismatch.actual}`, {
-					fileAlias: ref.file,
-					fragmentId: ref.id,
-					variable: name,
-					expectedType: mismatch.expected,
-					actualType: mismatch.actual
-				}));
-			}
-			const requiredSet = new Set(schema.required);
-			for (const [name, prop] of Object.entries(schema.properties)) {
-				if (prop.default === void 0) continue;
-				if (requiredSet.has(name)) {
-					warnings.push(warning("REQUIRED_PROPERTY_HAS_DEFAULT", `Variable "${name}" of "${ref.id}" is required, so its default is never used`, {
-						fileAlias: ref.file,
-						fragmentId: ref.id,
-						variable: name
-					}));
-					continue;
-				}
-				if (!(name in merged)) merged[name] = prop.default;
-			}
-		} else for (const name of Object.keys(variables)) warnings.push(warning("UNDECLARED_VARIABLE", `Variable "${name}" supplied to "${ref.id}", which declares no input schema`, {
-			fileAlias: ref.file,
-			fragmentId: ref.id,
-			variable: name
-		}));
-		resolved.push({
-			fileAlias: ref.file,
-			fragmentId: ref.id,
-			priority: fragment.priority,
-			content: fragment.content,
-			variables: merged
-		});
+		usedAliases.add(splitFragmentRef(placement.ref).alias);
+		const resolved = resolveAndMerge(placement.ref, placement.args, filesByAlias);
+		errors.push(...resolved.errors);
+		warnings.push(...resolved.warnings);
 	}
-	const plan = [...resolved].sort((a, b) => a.priority - b.priority);
-	const priorityOwners = /* @__PURE__ */ new Map();
-	for (const r of resolved) {
-		const owners = priorityOwners.get(r.priority) ?? [];
-		owners.push(r.fragmentId);
-		priorityOwners.set(r.priority, owners);
-	}
-	for (const [priority, owners] of priorityOwners) if (owners.length > 1) errors.push(error("DUPLICATE_PRIORITY", `Priority ${priority} is shared by fragments: ${owners.join(", ")} — ordering is ambiguous`));
+	for (const ref of fileRefs) if (!usedAliases.has(ref.id)) warnings.push(warning("UNUSED_FRAGMENT_FILE", `Fragment library "${ref.id}" is declared but no {{fragment}} marker uses it`, { fileAlias: ref.id }));
+	for (const ref of textFileRefs) if (!usedTextAliases.has(ref.id)) warnings.push(warning("UNUSED_TEXT_FILE", `Text file "${ref.id}" is declared but no {{file}} marker embeds it`, { fileAlias: ref.id }));
 	return {
 		errors,
-		warnings,
-		plan
+		warnings
 	};
 }
+/**
+* Validate one `{{file}}` placement: the alias must be a declared text file, and its
+* line range must fit. `from` beyond EOF is ALWAYS an error (an empty splice would
+* silently drop material); `to` beyond EOF is an error ONLY under `strict` (authoring) —
+* at runtime the render layer clamps `to` to EOF so a shortened source degrades gracefully.
+*/
+function checkFilePlacement(placement, textFilesByAlias, strict, errors) {
+	const body = textFilesByAlias.get(placement.ref);
+	if (body === void 0) {
+		errors.push(error("UNKNOWN_TEXT_FILE_ALIAS", `File marker "${placement.ref}" uses unknown text-file alias`, { fileAlias: placement.ref }));
+		return;
+	}
+	const lineCount = countLines(body);
+	if (placement.from !== void 0 && placement.from > lineCount) errors.push(error("TEXT_FILE_RANGE_OUT_OF_BOUNDS", `File "${placement.ref}" has ${lineCount} line(s), but from=${placement.from} is past the end`, {
+		fileAlias: placement.ref,
+		line: placement.line
+	}));
+	if (strict && placement.to !== void 0 && placement.to > lineCount) errors.push(error("TEXT_FILE_RANGE_OUT_OF_BOUNDS", `File "${placement.ref}" has ${lineCount} line(s), but to=${placement.to} is past the end`, {
+		fileAlias: placement.ref,
+		line: placement.line
+	}));
+}
 //#endregion
 //#region ../lib/prompt-fragments/fetcher.ts
 const DEFAULT_TIMEOUT_MS = 1e4;
@@ -704,8 +804,7 @@ const ClassificationSchema = z.strictObject({
 });
 const FragmentSchema = z.strictObject({
 	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." }),
+	version: z.number().optional().meta({ description: "Optional fragment version number." }),
 	input_schema: InputSchema.optional(),
 	classification: ClassificationSchema.optional(),
 	content: z.string().meta({ description: "Prompt text as a Handlebars template." })
@@ -717,8 +816,7 @@ const FragmentFileSchema = z.strictObject({
 	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.union([
 	z.string(),
 	z.boolean(),
 	z.array(z.string())
@@ -727,21 +825,36 @@ const VariableValueSchema = z.union([
 	description: "A literal variable value: a string, a boolean, or an array of strings."
 });
 const FragmentFileRefSchema = z.strictObject({
-	id: z.string().meta({ description: "Local alias for this library, referenced by each fragment's `file`." }),
+	id: z.string().regex(/^[^.]+$/, { message: "Alias must not contain a dot" }).meta({
+		pattern: "^[^.]+$",
+		description: "Local alias for this library, used before the dot in `{{fragment \"alias.id\"}}`. Must not contain a dot."
+	}),
 	url: FragmentUrlRef
 }).meta({
 	id: "fragmentFileRef",
 	description: "A reference to a fragment library by alias + URL."
 });
-const FragmentRefSchema = z.strictObject({
-	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." })
+/**
+* A plain-text file reference: an `id` alias + a `url`, mirroring `FragmentFileRefSchema`
+* exactly (same no-dot alias regex, same http(s)-or-relative `FragmentUrlRef`). Unlike a
+* fragment library, a text file is arbitrary content (markdown course material, a
+* sample-solution source file) fetched over HTTP(S) and spliced VERBATIM into the host
+* text by an inline `{{file "alias"}}` marker — there is nothing to select inside it, so
+* the alias carries no dot. Text-file and fragment-file aliases share ONE namespace (an
+* `id` may not collide across the two lists), so every marker alias resolves unambiguously.
+*/
+const TextFileRefSchema = z.strictObject({
+	id: z.string().regex(/^[^.]+$/, { message: "Alias must not contain a dot" }).meta({
+		pattern: "^[^.]+$",
+		description: "Local alias for this text file, used in `{{file \"alias\"}}`. Must not contain a dot."
+	}),
+	url: FragmentUrlRef.meta({
+		pattern: "^(https?://|(?![A-Za-z][A-Za-z0-9+.-]*:).+)$",
+		description: "HTTP(S) URL or relative path to the plain-text file."
+	})
 }).meta({
-	id: "fragmentRef",
-	description: "Selects one fragment from a referenced library."
+	id: "textFileRef",
+	description: "A reference to a plain-text file (markdown / source) by alias + URL."
 });
 //#endregion
 //#region ../lib/prompt-fragments/fragment.ts
@@ -793,8 +906,8 @@ function checkFragmentTemplates(file, opts = {}) {
 }
 /**
 * Fragment ids declared more than once within a single file. The standalone
-* validator runs this directly; the tutor path gets the same check from
-* `checkConsistency` (so the whole-library pass must NOT repeat it).
+* validator runs this directly; the activity path gets the same check from
+* `checkPlacements` (so the whole-library pass must NOT repeat it).
 */
 function findDuplicateFragmentIds(file) {
 	const errors = [];
@@ -835,6 +948,218 @@ function checkFragmentFileValue(parsed, url) {
 	};
 }
 //#endregion
+//#region ../lib/prompt-fragments/host-template.ts
+const FRAGMENT_HELPER = "fragment";
+const ARRAY_HELPER = "array";
+const FILE_HELPER = "file";
+const isFragmentNode = (node) => node.path?.original === FRAGMENT_HELPER;
+const isFileNode = (node) => node.path?.original === FILE_HELPER;
+/** A structural `{{fragment}}` error stamped with the node's 1-based position. */
+function markerInvalid(loc, detail) {
+	return error("FRAGMENT_MARKER_INVALID", `${detail} (line ${loc.start.line})`, {
+		line: loc.start.line,
+		column: loc.start.column + 1
+	});
+}
+/**
+* A structural `{{file}}` error stamped with the node's 1-based position. Every
+* `{{file}}` violation collapses to this ONE code (there is deliberately no separate
+* not-literal variant, unlike `{{fragment}}`): a file marker either parses into a valid
+* `alias`/`from`/`to` shape or fails closed here.
+*/
+function fileMarkerInvalid(loc, detail) {
+	return error("TEXT_FILE_MARKER_INVALID", `${detail} (line ${loc.start.line})`, {
+		line: loc.start.line,
+		column: loc.start.column + 1
+	});
+}
+/**
+* Read a hash-pair value into a supported literal. The supported set IS the contract:
+* a string, a boolean, or an `(array "…" …)` of string literals. Anything else — a
+* number, a path reference, a nested `(fragment …)`, an array with a non-string
+* element — is a hard error, because at RENDER time the real Handlebars runtime hands
+* the helper the raw value regardless, so silently dropping it here would let the
+* placement validate against different args than it renders with (fail-open drift).
+*/
+function readHashValue(key, node, loc) {
+	switch (node.type) {
+		case "StringLiteral": return { value: node.value };
+		case "BooleanLiteral": return { value: node.value };
+		case "SubExpression": {
+			const sub = node;
+			if (sub.path.original !== ARRAY_HELPER) return { error: markerInvalid(loc, `Argument "${key}" must be a string, boolean, or (array …)`) };
+			if (!sub.params.every((p) => p.type === "StringLiteral")) return { error: markerInvalid(loc, `Every element of (array …) for "${key}" must be a string`) };
+			return { value: sub.params.map((p) => p.value) };
+		}
+		default: return { error: markerInvalid(loc, `Argument "${key}" must be a string, boolean, or (array …)`) };
+	}
+}
+/** Extract one inline `{{fragment "alias.id" …}}` mustache's ref + validated args. */
+function extractInlineMarker(node, out) {
+	const first = node.params?.[0];
+	if (first?.type !== "StringLiteral") {
+		out.errors.push(error("FRAGMENT_REF_NOT_LITERAL", `A {{fragment}} marker at line ${node.loc.start.line} needs a quoted "alias.id" reference`, {
+			line: node.loc.start.line,
+			column: node.loc.start.column + 1
+		}));
+		return;
+	}
+	if ((node.params?.length ?? 0) > 1) {
+		out.errors.push(markerInvalid(node.loc, "A {{fragment}} marker takes exactly one \"alias.id\" reference"));
+		return;
+	}
+	const args = {};
+	for (const pair of node.hash?.pairs ?? []) {
+		const read = readHashValue(pair.key, pair.value, node.loc);
+		if ("error" in read) {
+			out.errors.push(read.error);
+			return;
+		}
+		args[pair.key] = read.value;
+	}
+	out.placements.push({
+		kind: "fragment",
+		ref: first.value,
+		args,
+		line: node.loc.start.line,
+		column: node.loc.start.column + 1
+	});
+}
+/**
+* Extract one inline `{{file "alias" from=N to=M}}` mustache's alias + optional range.
+* Structural contract (all TEXT_FILE_MARKER_INVALID, recording no placement on failure):
+* the first positional must be a quoted string literal, there is exactly one positional,
+* hash keys are restricted to `from` / `to`, each value must be an integer NumberLiteral
+* >= 1, and when both are present `from <= to`. A `from`/`to` beyond the file's actual
+* line count is NOT checked here (that needs the fetched body — see `checkPlacements`).
+*/
+function extractFileMarker(node, out) {
+	const first = node.params?.[0];
+	if (first?.type !== "StringLiteral") {
+		out.errors.push(fileMarkerInvalid(node.loc, "A {{file}} marker needs a quoted \"alias\" reference"));
+		return;
+	}
+	if ((node.params?.length ?? 0) > 1) {
+		out.errors.push(fileMarkerInvalid(node.loc, "A {{file}} marker takes exactly one \"alias\" reference"));
+		return;
+	}
+	let from;
+	let to;
+	for (const pair of node.hash?.pairs ?? []) {
+		if (pair.key !== "from" && pair.key !== "to") {
+			out.errors.push(fileMarkerInvalid(node.loc, `A {{file}} marker accepts only from= / to=, not "${pair.key}"`));
+			return;
+		}
+		if (pair.value.type !== "NumberLiteral" || !Number.isInteger(pair.value.value) || pair.value.value < 1) {
+			out.errors.push(fileMarkerInvalid(node.loc, `"${pair.key}" must be an integer line number >= 1`));
+			return;
+		}
+		if (pair.key === "from") from = pair.value.value;
+		else to = pair.value.value;
+	}
+	if (from !== void 0 && to !== void 0 && from > to) {
+		out.errors.push(fileMarkerInvalid(node.loc, `"from" (${from}) must not be greater than "to" (${to})`));
+		return;
+	}
+	out.placements.push({
+		kind: "file",
+		ref: first.value,
+		args: {},
+		...from !== void 0 ? { from } : {},
+		...to !== void 0 ? { to } : {},
+		line: node.loc.start.line,
+		column: node.loc.start.column + 1
+	});
+}
+/** Reject a `fragment` / `file` helper used anywhere but a simple inline mustache. */
+function visitExpression(node, out) {
+	if (node.type !== "SubExpression") return;
+	const sub = node;
+	if (isFragmentNode(sub)) out.errors.push(markerInvalid(sub.loc, "{{fragment}} must be a standalone inline marker, not a subexpression"));
+	else if (isFileNode(sub)) out.errors.push(fileMarkerInvalid(sub.loc, "{{file}} must be a standalone inline marker, not a subexpression"));
+	for (const p of sub.params ?? []) visitExpression(p, out);
+	for (const pair of sub.hash?.pairs ?? []) visitExpression(pair.value, out);
+}
+/** Collect every `{{fragment}}` / `{{file}}` marker in a program body (recursing into blocks). */
+function collectPlacements(program, out) {
+	for (const node of program.body) {
+		if (isFragmentNode(node)) if (node.type === "MustacheStatement") extractInlineMarker(node, out);
+		else out.errors.push(markerInvalid(node.loc, "{{fragment}} must be a simple inline marker, not a block {{#fragment}}…{{/fragment}}"));
+		else if (isFileNode(node)) if (node.type === "MustacheStatement") extractFileMarker(node, out);
+		else out.errors.push(fileMarkerInvalid(node.loc, "{{file}} must be a simple inline marker, not a block {{#file}}…{{/file}}"));
+		else {
+			for (const p of node.params ?? []) visitExpression(p, out);
+			for (const pair of node.hash?.pairs ?? []) visitExpression(pair.value, out);
+		}
+		if (node.program) collectPlacements(node.program, out);
+		if (node.inverse) collectPlacements(node.inverse, out);
+	}
+}
+/**
+* Parse the host text and extract every inline `{{fragment}}` placement in textual
+* order, WITHOUT rendering. A whole-template syntax error (a malformed marker, an
+* unescaped literal `{{`) becomes a single `HOST_TEMPLATE_PARSE_ERROR`; its position
+* is regexed out of Handlebars' message (`Parse error on line N:` — the parser
+* carries no structured position fields). A well-formed `{{fragment}}` marker whose
+* reference is not a quoted string literal becomes a per-marker `FRAGMENT_REF_NOT_LITERAL`;
+* a structurally wrong `{{file}}` marker becomes a per-marker `TEXT_FILE_MARKER_INVALID`.
+*/
+function parseHostPlacements(text) {
+	const result = {
+		placements: [],
+		errors: []
+	};
+	let program;
+	try {
+		program = Handlebars.parse(text);
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		const lineMatch = message.match(/line (\d+)/i);
+		result.errors.push(error("HOST_TEMPLATE_PARSE_ERROR", `Host text is not a valid template: ${message}`, { ...lineMatch ? { line: Number(lineMatch[1]) } : {} }));
+		return result;
+	}
+	collectPlacements(program, result);
+	return result;
+}
+/** Build the isolated Handlebars instance carrying ONLY the `fragment` + `array` + `file` helpers. */
+function createHostInstance(resolver, fileResolver) {
+	const hb = Handlebars.create();
+	hb.registerHelper(FRAGMENT_HELPER, (...args) => {
+		const ref = args.length >= 2 ? args[0] : void 0;
+		if (typeof ref !== "string") throw new Error("a {{fragment}} marker needs a quoted \"alias.id\" reference");
+		const options = args[args.length - 1];
+		return resolver(ref, options?.hash ?? {});
+	});
+	hb.registerHelper(ARRAY_HELPER, (...args) => {
+		return args.slice(0, -1);
+	});
+	hb.registerHelper(FILE_HELPER, (...args) => {
+		const alias = args.length >= 2 ? args[0] : void 0;
+		if (typeof alias !== "string") throw new Error("a {{file}} marker needs a quoted \"alias\" reference");
+		const options = args[args.length - 1];
+		return fileResolver(alias, options?.hash?.from, options?.hash?.to);
+	});
+	return hb;
+}
+/**
+* Compile + render the host text with the isolated instance under
+* `{ strict: true, noEscape: true }` — `strict` so any stray `{{…}}` that is not a
+* `fragment` / `array` / `file` marker fails closed instead of rendering empty; `noEscape`
+* so the prompt text (ASCII diagrams, quotes) passes through verbatim. Each `{{fragment}}`
+* placement is replaced by its `resolver` result, each `{{file}}` by its `fileResolver`
+* result. May throw — the caller wraps it as ASSEMBLY_ERROR. `fileResolver` defaults to a
+* thrower: a template with no `{{file}}` markers never invokes it, but one that does
+* without a resolver fails closed rather than rendering wrong.
+*/
+function renderHostTemplate(text, resolver, fileResolver = () => {
+	throw new Error("a {{file}} marker was rendered without a file resolver");
+}) {
+	return createHostInstance(resolver, fileResolver).compile(text, {
+		strict: true,
+		noEscape: true
+	})({});
+}
+//#endregion
 //#region ../lib/relative-url.ts
 /**
 * Resolve a reference to an absolute URL. An absolute http(s) ref is used as-is;
@@ -848,6 +1173,8 @@ function resolveRelativeUrl(ref, baseUrl) {
 }
 //#endregion
 //#region ../lib/prompt-fragments/load.ts
+/** The 200 KB (UTF-8 bytes) per-file cap on an embedded `text_files:` body — fail closed above it. */
+const MAX_TEXT_FILE_BYTES = 200 * 1024;
 /**
 * 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 activity URL — standard URL resolution
@@ -926,26 +1253,33 @@ async function loadYaml(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`.
+* Render an activity's host text (`tutor_instructions` / `instructions`) into a
+* finished prompt string, inserting each inline `{{fragment "alias.id" …}}` marker in
+* place. Fetches every declared fragment library in parallel (relative refs resolved
+* against `baseUrl`), schema-validates each, (optionally) runs the thorough
+* whole-library check, extracts + checks the placements, then compiles + renders the
+* host template under strict Handlebars.
 *
 * 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.
+* → check → render pipeline. `hostText` IS the template: fragments appear only where
+* the author placed a marker; there is no ordering concept and no prepend fallback.
+*
+* TEMPLATE-SEMANTICS OPT-IN: an activity that declares NEITHER `fragment_files:` NOR
+* `text_files:` is NEVER compiled — its host text returns byte-verbatim (protecting plain
+* activities and the authoring tutors whose prose contains sample markers as teaching
+* content). Text files are fetched in parallel with the fragment libraries; each is kept
+* as a RAW string (no YAML parse) and spliced verbatim at render — never re-compiled as
+* Handlebars, so a literal `{{` in course material can never execute.
 */
-async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, trailingInstructions) {
+async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, hostText = "") {
 	const warnings = [];
 	const allowedSchemes = opts.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
-	if (block.fragment_files.length === 0 && block.fragments.length === 0) return {
+	if (block.fragment_files.length === 0 && block.text_files.length === 0) return {
 		ok: true,
-		prompt: assembleSystemPrompt([], trailingInstructions),
+		prompt: hostText,
 		warnings
 	};
-	const settled = await Promise.all(block.fragment_files.map(async (ref) => {
+	const fragmentSettledPromise = Promise.all(block.fragment_files.map(async (ref) => {
 		let fragmentUrl;
 		try {
 			fragmentUrl = resolveFragmentUrl(ref.url, baseUrl);
@@ -990,14 +1324,57 @@ async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, trai
 			url: fragmentUrl
 		};
 	}));
+	const textSettledPromise = Promise.all(block.text_files.map(async (ref) => {
+		let fileUrl;
+		try {
+			fileUrl = resolveFragmentUrl(ref.url, baseUrl);
+		} catch {
+			return {
+				alias: ref.id,
+				error: error("INVALID_URL", `Invalid text-file URL: ${ref.url}`, {
+					url: ref.url,
+					fileAlias: ref.id
+				})
+			};
+		}
+		const schemeError = schemeGate(fileUrl, allowedSchemes);
+		if (schemeError) return {
+			alias: ref.id,
+			error: {
+				...schemeError,
+				fileAlias: ref.id
+			}
+		};
+		const fetched = await fetchText(fileUrl, fetchImpl);
+		if (!fetched.ok) return {
+			alias: ref.id,
+			error: fetched.error
+		};
+		const byteLength = new TextEncoder().encode(fetched.text).length;
+		if (byteLength > MAX_TEXT_FILE_BYTES) return {
+			alias: ref.id,
+			error: error("TEXT_FILE_TOO_LARGE", `Text file "${ref.id}" is ${byteLength} bytes, over the ${MAX_TEXT_FILE_BYTES}-byte limit`, {
+				url: fileUrl,
+				fileAlias: ref.id
+			})
+		};
+		return {
+			alias: ref.id,
+			body: fetched.text
+		};
+	}));
+	const [fragmentSettled, textSettled] = await Promise.all([fragmentSettledPromise, textSettledPromise]);
 	const fragmentFilesByAlias = /* @__PURE__ */ new Map();
 	const fragmentUrlByAlias = /* @__PURE__ */ new Map();
+	const textFilesByAlias = /* @__PURE__ */ new Map();
 	const fileErrors = [];
-	for (const result of settled) if ("error" in result) fileErrors.push(result.error);
+	for (const result of fragmentSettled) if ("error" in result) fileErrors.push(result.error);
 	else {
 		fragmentFilesByAlias.set(result.alias, result.file);
 		fragmentUrlByAlias.set(result.alias, result.url);
 	}
+	for (const result of textSettled) if ("error" in result) fileErrors.push(result.error);
+	else textFilesByAlias.set(result.alias, result.body);
 	if (fileErrors.length > 0) return {
 		ok: false,
 		errors: fileErrors,
@@ -1012,18 +1389,33 @@ async function assembleFragmentPrompt(block, baseUrl, fetchImpl, opts = {}, trai
 		libraryErrors.push(...checked.errors);
 		warnings.push(...checked.warnings);
 	}
-	const consistency = checkConsistency(block, fragmentFilesByAlias);
-	warnings.push(...consistency.warnings);
-	const preAssemblyErrors = [...libraryErrors, ...consistency.errors];
-	if (preAssemblyErrors.length > 0) return {
+	const parsed = parseHostPlacements(hostText);
+	if (parsed.errors.length > 0) return {
 		ok: false,
-		errors: preAssemblyErrors,
+		errors: [...libraryErrors, ...parsed.errors],
+		warnings
+	};
+	const placementCheck = checkPlacements(parsed.placements, fragmentFilesByAlias, block.fragment_files, textFilesByAlias, block.text_files, opts.validateLibraries ?? false);
+	warnings.push(...placementCheck.warnings);
+	const preRenderErrors = [...libraryErrors, ...placementCheck.errors];
+	if (preRenderErrors.length > 0) return {
+		ok: false,
+		errors: preRenderErrors,
 		warnings
 	};
 	try {
 		return {
 			ok: true,
-			prompt: assembleSystemPrompt(consistency.plan, trailingInstructions),
+			prompt: renderHostTemplate(hostText, (ref, args) => {
+				const resolved = resolveAndMerge(ref, args, fragmentFilesByAlias);
+				if (resolved.content === null || resolved.errors.length > 0) throw new Error(`Fragment "${ref}" could not be resolved`);
+				return renderFragmentContent(resolved.content, resolved.variables);
+			}, (alias, from, to) => {
+				const body = textFilesByAlias.get(alias);
+				if (body === void 0) throw new Error(`Text file "${alias}" was not prefetched`);
+				if (from === void 0 && to === void 0) return body;
+				return sliceLines(body, from, to);
+			}),
 			warnings
 		};
 	} catch (e) {
@@ -1065,8 +1457,8 @@ const CodingYamlSchema = z.strictObject({
 		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." }),
-	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." })
+	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
@@ -1107,11 +1499,11 @@ async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
 	if (!checked.ok) return checked;
 	const assembled = await assembleFragmentPrompt({
 		fragment_files: valid.data.fragment_files,
-		fragments: valid.data.fragments
+		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,
@@ -1183,7 +1575,8 @@ const QuizYamlSchema = z.strictObject({
 		description: "Optional guidance for the per-question follow-up discussion chat."
 	}),
 	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this quiz pulls shared prompt fragments from." }),
-	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." }),
+	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
+	instructions: z.string().optional().meta({ description: "Optional quiz-level preamble prepended to BOTH the grader prompt and the discussion chat. When any fragment_files or text_files are declared, place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." }),
 	questions: z.array(QuizQuestionSchema).min(1).meta({ description: "The quiz questions. Each is open-ended and graded by the LLM via its evaluation prompt." })
 });
 //#endregion
@@ -1250,11 +1643,11 @@ async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 	if (!checked.ok) return checked;
 	const assembled = await assembleFragmentPrompt({
 		fragment_files: valid.data.fragment_files,
-		fragments: valid.data.fragments
+		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,
@@ -1303,11 +1696,11 @@ const TutorSchema = z.strictObject({
 	}),
 	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." })
+		text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim via {{file \"alias\"}} markers." }),
+		tutor_instructions: z.string().meta({ description: "The tutor's system prompt. When any fragment_files or text_files are declared this is a Handlebars template: place fragments inline with {{fragment \"alias.id\" key=\"v\"}} markers and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{). For single-file tutors it is the whole prompt." })
 	}).meta({
 		id: "prompt",
-		description: "The assembled system prompt: fragments plus tutor instructions."
+		description: "The tutor system prompt: a host template with inline fragment markers."
 	})
 });
 //#endregion
@@ -1366,8 +1759,8 @@ const WritingYamlSchema = z.strictObject({
 		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." }),
-	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." }),
+	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
@@ -1412,11 +1805,11 @@ async function loadAndCheckWriting(url, fetchImpl, opts = {}) {
 	if (!checked.ok) return checked;
 	const assembled = await assembleFragmentPrompt({
 		fragment_files: valid.data.fragment_files,
-		fragments: valid.data.fragments
+		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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novedu/cli",
-  "version": "0.12.1",
+  "version": "0.14.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": {