@novedu/cli 0.12.1 → 0.13.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
@@ -473,118 +461,151 @@ 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 aliasCounts = /* @__PURE__ */ new Map();
-	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) {
-		const byId = /* @__PURE__ */ new Map();
-		for (const frag of file.fragments) {
-			if (byId.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);
-		}
-		fragmentIndex.set(alias, byId);
+	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 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
+	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
 		}));
-		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
+		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 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 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;
 		}
-		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
+		if (!(name in merged)) merged[name] = prop.default;
+	}
+	return merged;
+}
+/**
+* Cross-check every inline placement against the declared libraries: duplicate
+* aliases, duplicate fragment ids within a file, each placement's `alias.id`
+* resolution + variable validation (via `resolveAndMerge`), and a warning for any
+* declared library no placement ever uses. Errors block the build; the rest are
+* warnings. Order-independent — placements carry their own textual position.
+*/
+function checkPlacements(placements, filesByAlias, fileRefs) {
+	const errors = [];
+	const warnings = [];
+	const aliasCounts = /* @__PURE__ */ new Map();
+	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 }));
+	for (const [alias, file] of filesByAlias) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const frag of file.fragments) {
+			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;
 			}
-			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
-		});
+			seen.add(frag.id);
+		}
 	}
-	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);
+	const usedAliases = /* @__PURE__ */ new Set();
+	for (const placement of placements) {
+		usedAliases.add(splitFragmentRef(placement.ref).alias);
+		const resolved = resolveAndMerge(placement.ref, placement.args, filesByAlias);
+		errors.push(...resolved.errors);
+		warnings.push(...resolved.warnings);
 	}
-	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 }));
 	return {
 		errors,
-		warnings,
-		plan
+		warnings
 	};
 }
 //#endregion
@@ -704,8 +725,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 +737,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,22 +746,15 @@ 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." })
-}).meta({
-	id: "fragmentRef",
-	description: "Selects one fragment from a referenced library."
-});
 //#endregion
 //#region ../lib/prompt-fragments/fragment.ts
 /**
@@ -793,8 +805,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 +847,142 @@ function checkFragmentFileValue(parsed, url) {
 	};
 }
 //#endregion
+//#region ../lib/prompt-fragments/host-template.ts
+const FRAGMENT_HELPER = "fragment";
+const ARRAY_HELPER = "array";
+const isFragmentNode = (node) => node.path?.original === FRAGMENT_HELPER;
+/** A structural 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
+	});
+}
+/**
+* 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({
+		ref: first.value,
+		args,
+		line: node.loc.start.line,
+		column: node.loc.start.column + 1
+	});
+}
+/** Reject a `fragment` 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"));
+	for (const p of sub.params ?? []) visitExpression(p, out);
+	for (const pair of sub.hash?.pairs ?? []) visitExpression(pair.value, out);
+}
+/** Collect every `{{fragment}}` 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 {
+			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 marker whose reference is not
+* a quoted string literal becomes a per-marker `FRAGMENT_REF_NOT_LITERAL`.
+*/
+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` helpers. */
+function createHostInstance(resolver) {
+	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);
+	});
+	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` marker fails closed instead of rendering empty; `noEscape` so
+* the prompt text (ASCII diagrams, quotes) passes through verbatim. Each placement is
+* replaced by its `resolver` result. May throw — the caller wraps it as ASSEMBLY_ERROR.
+*/
+function renderHostTemplate(text, resolver) {
+	return createHostInstance(resolver).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;
@@ -926,23 +1074,27 @@ 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 no `fragment_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).
 */
-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) return {
 		ok: true,
-		prompt: assembleSystemPrompt([], trailingInstructions),
+		prompt: hostText,
 		warnings
 	};
 	const settled = await Promise.all(block.fragment_files.map(async (ref) => {
@@ -1012,18 +1164,28 @@ 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: [...libraryErrors, ...parsed.errors],
+		warnings
+	};
+	const placementCheck = checkPlacements(parsed.placements, fragmentFilesByAlias, block.fragment_files);
+	warnings.push(...placementCheck.warnings);
+	const preRenderErrors = [...libraryErrors, ...placementCheck.errors];
+	if (preRenderErrors.length > 0) return {
 		ok: false,
-		errors: preAssemblyErrors,
+		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);
+			}),
 			warnings
 		};
 	} catch (e) {
@@ -1065,8 +1227,7 @@ 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." })
+	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 are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} markers (escape a literal {{ as \\{{)." })
 });
 //#endregion
 //#region ../lib/coding-validate.ts
@@ -1105,13 +1266,10 @@ async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
 	};
 	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, {
+	const assembled = await assembleFragmentPrompt({ fragment_files: valid.data.fragment_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 +1341,7 @@ 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." }),
+	instructions: z.string().optional().meta({ description: "Optional quiz-level preamble prepended to BOTH the grader prompt and the discussion chat. When any fragment_files are declared, place fragments inline here with {{fragment \"alias.id\" …}} markers (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
@@ -1248,13 +1406,10 @@ async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 	};
 	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, {
+	const assembled = await assembleFragmentPrompt({ fragment_files: valid.data.fragment_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 +1458,10 @@ 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." })
+		tutor_instructions: z.string().meta({ description: "The tutor's system prompt. When any fragment_files are declared this is a Handlebars template: place fragments inline with {{fragment \"alias.id\" key=\"v\"}} markers (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 +1520,7 @@ 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." }),
+	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 are declared it is a Handlebars template: place fragments inline with {{fragment \"alias.id\" …}} markers (escape a literal {{ as \\{{)." }),
 	placeholder: z.string().optional().meta({ description: "Optional starter text prefilled into the editor. Empty for a blank page." })
 });
 //#endregion
@@ -1410,13 +1563,10 @@ async function loadAndCheckWriting(url, fetchImpl, opts = {}) {
 	};
 	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, {
+	const assembled = await assembleFragmentPrompt({ fragment_files: valid.data.fragment_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.13.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": {