@novedu/cli 0.12.0 → 0.13.0

package/README.md

@@ -1,43 +1,46 @@
 # @novedu/cli
 
 Command-line companion for the Novedu chat app (installed command: `novedu-cli`;
-requires Node >= 20). It validates every activity YAML the app accepts — **tutors**,
-**fragment libraries**, **quizzes**, **writing activities**, and **coding
-activities** — and signs in to Microsoft Entra ID (`login` / `logout` / `whoami`)
-to call the app's protected APIs; more commands will follow. Validating a tutor
-also fully validates every fragment library it references; pass `--kind` to
-validate any other kind on its own.
+requires Node >= 20). It covers two jobs:
 
-It reuses the app's exact validation pipeline (`lib/tutors`, `lib/quiz-validate`,
-`lib/writing-validate`, `lib/coding-validate`), so an activity that passes here is
-the same one the app would accept — no separate, drifting rules.
+- **Validate activity YAML** — tutors, fragment libraries, quizzes, writing
+  activities, and coding activities — with the app's exact validation pipeline,
+  offline and without signing in.
+- **Manage the app as a teacher** — sign in with Microsoft Entra ID, then mint
+  activity codes, upload app-hosted YAML files, and triage student reports,
+  straight from the terminal (or from a coding agent, see below).
 
-## Usage
+No install needed:
 
 ```bash
-# Validate a local file (relative fragment_files resolve against the file's location)
+npx @novedu/cli --help
+```
+
+## Validating activities: `validate`
+
+```bash
+# Validate a local tutor (relative fragment_files resolve against the file's location)
 npx @novedu/cli validate ./activities/examples/sorting-algorithms/sorting-tutor.yaml
 
-# Validate a published tutor by URL
+# Validate a published activity by URL
 npx @novedu/cli validate https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/examples/sorting-algorithms/sorting-tutor.yaml
 
-# Validate a fragment library on its own
+# Other kinds: fragment library, quiz, writing activity, coding activity
 npx @novedu/cli validate ./activities/examples/shared/general-fragments.yaml --kind fragment
-
-# Validate a quiz, a writing activity, or a coding activity
 npx @novedu/cli validate ./activities/examples/sorting-algorithms/sorting-quiz.yaml --kind quiz
-npx @novedu/cli validate ./activities/examples/review-writing/restaurant-review-letter.yaml --kind writing
-npx @novedu/cli validate ./activities/examples/sorting-algorithms/sorting-visualizer.yaml --kind coding
 
 # Machine-readable output (the raw validation result)
-npx @novedu/cli validate ./activities/examples/sorting-algorithms/sorting-tutor.yaml --json
+npx @novedu/cli validate ./my-quiz.yaml --kind quiz --json
 ```
 
-`--kind` accepts `tutor` (default), `fragment`, `quiz`, `writing`, or `coding`; it
-is caller-declared, not auto-detected.
-
-Exit code is `0` when the activity is valid and `1` when it has errors, so it works
-as a pre-commit / CI gate.
+- `--kind` accepts `tutor` (default), `fragment`, `quiz`, `writing`, or
+  `coding`; it is caller-declared, not auto-detected.
+- The CLI reuses the app's exact validation pipeline (`lib/prompt-fragments`,
+  `lib/tutors`, `lib/quiz-validate`, `lib/writing-validate`,
+  `lib/coding-validate`), so an activity that passes here is the same one the
+  app accepts — no separate, drifting rules. Validating a tutor also fully
+  validates every fragment library it references.
+- Exit code `0` = valid, `1` = errors found — usable as a pre-commit / CI gate.
 
 ## Authentication
 
@@ -61,6 +64,9 @@ npx @novedu/cli logout   # remove the cached credentials from this machine
   file `0600`). The cache holds a refresh token, so after the one sign-in every
   command runs non-interactively; treat the file like a credential. `logout`
   is purely local — issued tokens expire on their own (~1 h).
+- `whoami` proves the full round-trip and shows your display name, user id, and
+  whether the account is a teacher (`Teacher: yes/no`) — the management
+  commands below need a teacher account.
 - The server defaults to the production app; override per command with
   `--server <url>` or the `NOVEDU_SERVER` env var (e.g.
   `http://localhost:3000` for development). Other deployments of the app can
@@ -69,6 +75,94 @@ npx @novedu/cli logout   # remove the cached credentials from this machine
 - Not signed in (or the cached token expired for good)? Commands exit 1 with
   `Not signed in — run "novedu-cli login".`
 
+## Managing codes & files (teacher account required)
+
+The `codes` and `files` groups call the app's API as the signed-in teacher. The
+server runs the identical validation pipeline as the web forms and is
+authoritative — the CLI sends your input as-is and relays the server's answer.
+
+```
+codes create --module <tutor|quiz|writing|coding> --file <url>
+             [--start <iso>] [--end <iso>] [--note <text>]
+             [--llm-provider <p> --llm-model <m>]
+codes list   [--search <q>] [--module <m>] [--all]
+files upload <name> [--kind <tutor|fragment|quiz|writing|coding>]
+             (--file <path> | reads stdin)
+files list   [--search <q>] [--all]
+```
+
+- **Output is JSON only.** Success: the API's objects verbatim on stdout, exit
+  0 (pipe into `jq`). Failure: JSON on stderr — `{ message }` or
+  `{ errors: [...] }` with the full structured validation detail — and exit 1.
+- `codes create` mints a shareable code for an activity YAML at a public URL
+  (or an app-hosted `…/api/files/<name>` URL); the YAML is validated
+  server-side before the code is stored, and the response includes the
+  shareable `url`. `--start`/`--end` must be ISO 8601 **with an explicit
+  offset or `Z`** (e.g. `2026-07-07T08:00:00Z`); the
+  `--llm-provider`/`--llm-model` override pair is both-or-nothing.
+- `files upload <name>` is an **upsert**: creating a new file requires
+  `--kind`; an existing file's kind is frozen at create time (a contradicting
+  `--kind` fails with 409). The YAML comes from `--file <path>` or stdin.
+  Every hosted file is public at the `url` the list returns — no download
+  command needed.
+- Both `list` commands default to **only your own** codes/files (like the web
+  lists); `--all` widens to every teacher's, `--search` is a contains-filter.
+
+Example — host a quiz and share it:
+
+```bash
+npx @novedu/cli files upload sorting-quiz --kind quiz --file ./sorting-quiz.yaml
+# { "name": "sorting-quiz", "kind": "quiz", "url": "https://…/api/files/sorting-quiz", "action": "created" }
+
+npx @novedu/cli codes create --module quiz \
+  --file https://…/api/files/sorting-quiz \
+  --start 2026-07-07T08:00:00Z --note "3A Monday"
+# { "code": "…", "url": "https://…/<code>", … }   — hand the url to students
+```
+
+## Triaging student reports (teacher account required)
+
+Students can flag an AI interaction — a chat or a graded quiz answer — with a
+reaction and an optional note. The `reports` group reads and resolves those
+flags; same JSON stdout/stderr contract as above.
+
+```
+reports list    [--status <open|resolved|all>] [--reaction <good|omg|bad|holysh>]
+                [--search <q>] [--all]
+reports show    <id>
+reports resolve <id...>
+```
+
+- `reports list` defaults to **open reports on your own codes** (like the web
+  inbox), most urgent first; `--all` widens to every teacher's codes.
+- `reports show <id>` prints one report in full. A **chat** report embeds the
+  conversation transcript as a `messages` array; a **quiz-answer** report
+  already carries its question / answer / feedback snapshot inline.
+- `reports resolve <id...>` resolves one or more reports in a single request;
+  unknown or already-resolved ids are silently ignored.
+- The CLI deliberately cannot file, reopen, or delete a report — those stay in
+  the web `/reports` inbox.
+
+The typical loop for turning a report into a better activity:
+
+```bash
+npx @novedu/cli reports list --reaction holysh        # find the urgent flags
+npx @novedu/cli reports show 3f2c…                    # read the report + transcript
+# fix the activity YAML, then check it offline:
+npx @novedu/cli validate ./sorting-quiz.yaml --kind quiz
+npx @novedu/cli files upload sorting-quiz --file ./sorting-quiz.yaml
+npx @novedu/cli reports resolve 3f2c…                 # existing codes already serve the fix
+```
+
+## Using the CLI from a coding agent
+
+The app repo ships a Claude Code skill that teaches coding agents the full CLI
+workflow — validation, the sign-in hand-off, code/file management, and the
+report-triage loop:
+[`.claude/skills/novedu-tutor-cli/SKILL.md`](https://github.com/Teaching-HTL-Leonding/novedu-chat-mvp/blob/main/.claude/skills/novedu-tutor-cli/SKILL.md)
+(mirrored at `.agents/skills/novedu-tutor-cli/`). Agents working inside that
+repo pick it up automatically.
+
 ## Development
 
 The CLI lives in the app repo as an npm workspace.
@@ -79,5 +173,5 @@ npm run cli:build                                    # bundle to cli/dist via ts
 npm run test:cli                                     # build + integration tests (local & live URLs)
 ```
 
-The fast in-process unit test (`cli/src/commands/validate.unit.test.ts`) runs in
-CI; the integration tests hit the network and are local-only.
+The fast in-process unit tests (`cli/src/commands/*.unit.test.ts`) run in CI;
+the integration tests hit the network and are local-only.

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.0",
+  "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": {