@lernapps/tooling 0.1.1 → 0.1.3

package/README.md

@@ -39,7 +39,7 @@ lernapps.net's own websites, and the update policy for dependencies.
 - **The CLI `lernapps`:** `init` starts an app's plan in an empty folder and syncs the skills of the packages into the agent directories, `skills --archetype` adds those of the chosen archetype, `create` writes a new app for an archetype once the creator confirmed the plan, `check`
   checks an app the same way in its git hooks and in CI, `update` moves an app to the runtime and tooling versions of the latest
   tooling and replaces the app's `lernapps-*` skills with that tooling's (and an older app's single plan into
-  `.vibe/plans/`), `changes` tells what a change can affect, so that hooks and CI run only that, `screenshots` writes an image of every page and every figure of a built explainer or quiz, to show a creator what a learner sees (`npx lernapps screenshots --help`). `npx --yes @lernapps/tooling --help` before an app exists, `npx lernapps --help` in one.
+  `.vibe/plans/`), `changes` tells what a change can affect, so that hooks and CI run only that, `screenshots` writes an image of every page and every figure of a built explainer or quiz, to show a creator what a learner sees (`npx --no -- lernapps screenshots --help`). `npx --yes @lernapps/tooling --help` before an app exists, `npx --no -- lernapps --help` in one.
 - **The actions in [`actions/`](actions/):** the app check, app publish and app preview actions of every app, and the site
   actions with which lernapps.net's own websites are checked, published and previewed. Each says what it does in its
   `action.yml`. The reusable workflow [`changes.yml`](.github/workflows/changes.yml) gives other workflows the

package/dist/cli.mjs

@@ -632,7 +632,7 @@ the app cannot be created, 2 on a usage error.
 
 The package @lernapps/tooling comes from the npm registry. Before an app exists, run a command with
   npx --yes @lernapps/tooling <command> ...
-In an app, it is a development dependency: npx lernapps <command> ...
+In an app, it is a development dependency: npx --no -- lernapps <command> ...
 `;
 /** The options of `lernapps check`, as node:util parseArgs takes them. */
 const CHECK_OPTIONS = {
@@ -1441,7 +1441,7 @@ It needs the plan of the first version, confirmed by the creator: started from t
 tooling is moved to .vibe/plans/01-first-version.md. Without a plan, it writes nothing and says what to do.
 
 Run it in the folder lernapps init prepared, from the tooling init installed:
-  npx lernapps create --archetype <name> [<dir>]
+  npx --no -- lernapps create --archetype <name> [<dir>]
 It needs git, and the npm registry for the npm install that follows. The app then depends on the version of
 @lernapps/tooling that created it, and its workflows use the actions of that version's tag.
 
@@ -1527,7 +1527,7 @@ function contents(dir) {
 		if (name === ".git" || name === "skills-lock.json" && skills.size > 0) return [];
 		if (name === "node_modules" || name === "package-lock.json") return [];
 		if (name === "package.json" && readJson(join(dir, name)).lernapps?.init === true) return [];
-		if (name === ".vibe") return within(name, (file) => file === "plan.md" || file === "plans").concat(existsSync(join(dir, ".vibe/plans")) ? within(PLANS, (file) => PLAN_NAME.test(file)) : []);
+		if (name === ".vibe") return existsSync(join(dir, ".vibe/plans")) ? within(PLANS, (file) => PLAN_NAME.test(file)) : [];
 		if ((name === ".agents" || name === ".claude") && skills.size > 0) return within(name, (folder) => folder === "skills").concat(existsSync(join(dir, name, "skills")) ? within(`${name}/skills`, (skill) => skills.has(skill)) : []);
 		return [name];
 	});
@@ -1691,7 +1691,7 @@ function create(args) {
 	if (positionals.length > 1) throw new UsageError(`one <dir> at most, not ${positionals.join(" ")}`);
 	const dir = resolve(positionals[0] ?? ".");
 	const found = contents(dir);
-	if (found.length > 0) throw new CreateError(`${dir} is not empty (${found.slice(0, 5).join(", ")}${found.length > 5 ? ", ..." : ""}): create the app in an empty folder; only .git, the first version's plan .vibe/plans/01-<short name>.md and what lernapps init wrote (its skills, package.json, package-lock.json and node_modules) may be there`);
+	if (found.length > 0) throw new CreateError(`${dir} is not empty (${found.slice(0, 5).join(", ")}${found.length > 5 ? ", ..." : ""}): create the app in an empty folder; only .git, .vibe/ (the first version's plan .vibe/plans/01-<short name>.md, and its sketches) and what lernapps init wrote (its skills, package.json, package-lock.json and node_modules) may be there`);
 	const plan = confirmedPlan(dir, archetype, values.plan);
 	const architecture = ARCHITECTURE_ARCHETYPES.includes(archetype);
 	if (!existsSync(join(templates.root, archetype, "package.json"))) throw new CreateError(`${templates.root} has no template ${archetype}/ (version ${templates.version})`);
@@ -1765,6 +1765,7 @@ const INIT_USAGE = `Usage: lernapps init <short name> [--addon <package>]
 
 Starts an app in the current folder, which must be empty except for .git. It needs git, Node and the npm registry; nothing
 else. In order:
+  git repository               on the branch work, which the plan names (unless the folder is one already; no commit)
   package.json                  names the folder, depends on @lernapps/tooling (this version) and the add-on
   npm install                   installs them
   .vibe/plans/01-<short name>.md
@@ -1802,6 +1803,26 @@ const SKILLS_BIN = () => {
 	const bin = readJson(manifest)["bin"];
 	return join(dirname(manifest), bin?.["skills"] ?? "bin/cli.mjs");
 };
+/** The branch the plan works on (rule 8 of the plan template). */
+const WORK_BRANCH = "work";
+/**
+* Makes the folder a git repository on the branch `work`, which the plan names, unless it is one already: `create` and
+* the hooks need it, and the plan's first rule is to work there. Returns what it did, for the output; no commit.
+*/
+function ensureRepository(dir) {
+	if (existsSync(join(dir, ".git"))) return void 0;
+	const result = spawnSync("git", [
+		"init",
+		"--quiet",
+		`--initial-branch=${WORK_BRANCH}`
+	], {
+		cwd: dir,
+		encoding: "utf8"
+	});
+	if (result.error) throw new CreateError(`git cannot run: ${result.error.message}. Install git, then run init again`);
+	if (result.status !== 0) throw new CreateError(`git init failed: ${`${result.stdout}${result.stderr}`.trim()}`);
+	return `a git repository on the branch ${WORK_BRANCH}`;
+}
 /** The names of the skills of the archetypes, with the archetype each belongs to (lernapps-<archetype>[-…]). */
 function archetypeSkills() {
 	const dir = fromPackage("skills", "archetypes");
@@ -1858,6 +1879,7 @@ function init(args) {
 	const present = readdirSync(dir).filter((entry) => entry !== ".git");
 	if (present.length > 0) throw new CreateError(`${dir} is not empty (${present.slice(0, 5).join(", ")}${present.length > 5 ? ", ..." : ""}): start in a new, empty folder`);
 	const addon = values.addon;
+	const repository = ensureRepository(dir);
 	writeJson(join(dir, "package.json"), {
 		name: slug(dir),
 		version: "0.0.0",
@@ -1883,7 +1905,7 @@ function init(args) {
 	mkdirSync(dirname(target), { recursive: true });
 	writeFileSync(target, readFileSync(template));
 	syncSkills(dir, archetypeSkills().map((skill) => skill.name));
-	process.stdout.write(`lernapps init: ${relative$1(dir, target)} from ${relativeTemplate(template, dir)}; the skills of the packages are installed\nNext: read ${relative$1(dir, target)} completely and follow it\n`);
+	process.stdout.write(`lernapps init: ${relative$1(dir, target)} from ${relativeTemplate(template, dir)}; the skills of the packages are installed${repository ? `; ${repository}` : ""}\nNext: read ${relative$1(dir, target)} completely and follow it\n`);
 	return 0;
 }
 const relative$1 = (from, to) => to.startsWith(from) ? to.slice(from.length + 1) : to;
@@ -1939,8 +1961,8 @@ moves the app within its version ranges; this moves the ranges, and what npm doe
 
 Run it from the latest tooling, in the app's folder, e.g. to pick up a fixed runtime:
   ${LATEST}
-Run as the app's own tooling (npx lernapps update), it knows only the versions the app already has.
-Then run npx lernapps check, and commit package.json, package-lock.json, .github/workflows/ and what else it names.
+Run as the app's own tooling (npx --no -- lernapps update), it knows only the versions the app already has.
+Then run npx --no -- lernapps check, and commit package.json, package-lock.json, .github/workflows/ and what else it names.
 
 Exit codes: 0 when the app is updated (or was up to date), 1 when it cannot be or only partly (the message says
 what was not moved and why), 2 on a usage error.
@@ -2238,7 +2260,7 @@ function update(args) {
 			2
 		] });
 		if (install.error || install.status !== 0) throw new UpdateError(`npm install ${specs.join(" ")} failed${install.error ? `: ${install.error.message}` : ` (exit ${install.status})`}; its output is above. Fix the cause, then run lernapps update again`);
-		if (installHooks([]) !== 0) throw new UpdateError("lernapps hooks failed (see above); run npx lernapps hooks again");
+		if (installHooks([]) !== 0) throw new UpdateError("lernapps hooks failed (see above); run npx --no -- lernapps hooks again");
 	}
 	const changed = moveActions(`v${version}`);
 	if (changed.length > 0) lines.push(`the actions of lernapps/tooling in ${changed.join(", ")}: v${version}`);
@@ -2264,7 +2286,7 @@ function update(args) {
 	if (skills.some((line) => line.includes(".gitignore"))) files.push(".gitignore");
 	if (architecture.lines.length > 0) files.push(`${ARCHITECTURE}/`);
 	if (plan.some((line) => line.startsWith("plan: moved"))) files.push(".vibe/ (git add -A .vibe, to keep the move)");
-	process.stdout.write(`Next: npx lernapps check, then commit ${files.slice(0, -1).join(", ")} and ${files.at(-1) ?? ""}\n`);
+	process.stdout.write(`Next: npx --no -- lernapps check, then commit ${files.slice(0, -1).join(", ")} and ${files.at(-1) ?? ""}\n`);
 	return 0;
 }
 // src/screenshots.ts
@@ -2431,6 +2453,7 @@ async function screenshots(args) {
 			force: true
 		});
 		mkdirSync(out, { recursive: true });
+		writeFileSync(join(out, ".gitignore"), "*\n");
 		const shots = [];
 		for (const [index, page] of pages.entries()) {
 			const images = [];

package/dist/skills/lernapps-app/SKILL.md

@@ -27,11 +27,13 @@ license: MIT
 
 ## What each archetype can do
 
+The READMEs are files of the package `@lernapps/app-templates`, which `init` installed: read them from the folder, in full.
+
 | Archetype | Learners … | Can and cannot (README of its template) |
 |---|---|---|
-| `quiz` | answer questions with options and feedback | <https://raw.githubusercontent.com/lernapps/app-templates/main/quiz/README.md> |
-| `explainer` | read pages that explain, each with exercises | <https://raw.githubusercontent.com/lernapps/app-templates/main/explainer/README.md> |
-| `interactive` | act in one app page, by turns or in real time | <https://raw.githubusercontent.com/lernapps/app-templates/main/interactive/README.md> |
+| `quiz` | answer questions with options and feedback | `node_modules/@lernapps/app-templates/quiz/README.md` |
+| `explainer` | read pages that explain, each with exercises | `node_modules/@lernapps/app-templates/explainer/README.md` |
+| `interactive` | act in one app page, by turns or in real time | `node_modules/@lernapps/app-templates/interactive/README.md` |
 
 ## Choose the archetype
 

package/dist/skills/lernapps-cli/SKILL.md

@@ -14,7 +14,7 @@ license: MIT
 ## Create
 
 1. Only after the creator's yes to the plan (`explore-before-code`). In the plan's folder:
-   `npx lernapps create --archetype <archetype>`.
+   `npx --no -- lernapps create --archetype <archetype>`.
 2. No git repo yet: `git init --initial-branch=work`. Then `npm install` (dependencies, git hooks), and commit
    everything on `work`.
 3. Needs git, Node ≥ 22.18, registry.npmjs.org. Blocked → ask the creator to allow it, run again. Never write the
@@ -29,20 +29,20 @@ license: MIT
 
 ## Check
 
-- `npx lernapps check`: format, lint, types, unit tests, build, checks of the built app, end-to-end tests. The hooks
+- `npx --no -- lernapps check`: format, lint, types, unit tests, build, checks of the built app, end-to-end tests. The hooks
   run its parts (`--pre-commit`, `--pre-push`); CI runs it whole.
-- Report: `node_modules/.cache/lernapps/validation-report.yaml`. Options: `npx lernapps check --help`.
+- Report: `node_modules/.cache/lernapps/validation-report.yaml`. Options: `npx --no -- lernapps check --help`.
 
 ## Look at the app
 
 A check says the rules hold; only a look says what a learner sees. Show the creator the pages before a push, and before
 a submission they declare something about.
 
-- Explainer or quiz: build (`npx vp build`), then `npx lernapps screenshots`. It writes one image of every page, one of
+- Explainer or quiz: build (`npx vp build`), then `npx --no -- lernapps screenshots`. It writes one image of every page, one of
   every figure, and an `index.html` that shows them in order to `screenshots/` (not part of the app: do not commit it).
   Show the images, or the `index.html` where you can show HTML. Check every figure in its own image
   (`…-figure-<n>.png`): a page image is scaled down, its details are not readable. `--desktop` adds 1280 px images.
-  Options: `npx lernapps screenshots --help`.
+  Options: `npx --no -- lernapps screenshots --help`. The folder ignores itself in git, so a later check never sees it.
 - Interactive app: `screenshots` does not support it. Open the built app with the Playwright the tooling installs
   (`import { chromium } from "playwright"`), at 390 px width, and take `page.screenshot({ fullPage: true })` of each
   state the creator should see, from a short script outside the app.

package/dist/skills/lernapps-content-growth/SKILL.md

@@ -15,7 +15,7 @@ Each slice is one Code task and ends in one commit:
 3. Exercise: a pattern of the guide, varied. A new pattern goes into the guide in the same slice, with example and
    data file.
 4. Entry topic: the page or section path into the plan's entry draft (`entry-links-resolve`).
-5. Check: `npx lernapps check` passes.
+5. Check: `npx --no -- lernapps check` passes.
 6. Commit, guide changes included.
 
 - A new chapter or round: its slices in the order of the guide's procedure.

package/dist/skills/lernapps-content-questions/references/question-types.md

@@ -7,7 +7,7 @@
 | `true-false` | `answer` (true or false) |
 | `number` | `answer`, `tolerance` (0 = exact), `unit` if any; the learner may type a comma or a point |
 | `ordering` | `items` in the right order; the page mixes them |
-| `matching` | `pairs` as they belong; the page mixes the right side. `distractors` (1 to 4): wrong right entries that match no left one. `pairsFrom: material` instead of `pairs` takes them from the `labelled-figure` in `material` (marker left, text right; the figure needs `legend: false`) |
+| `matching` | `pairs` as they belong, each pair an object `{ left, right }`; the page mixes the right side. `distractors` (1 to 4): wrong right entries that match no left one. `pairsFrom: material` instead of `pairs` takes them from the `labelled-figure` in `material` (marker left, text right; the figure needs `legend: false`) |
 
 - Every question: `id`, `text`, `explanation`, at least one link in `links`. Optional quiz `sources`.
 - Types without options carry their background in `explanation`.

package/dist/skills/lernapps-content-research/SKILL.md

@@ -15,8 +15,8 @@ license: MIT
 
 - Orientation for grade and order, not a condition. None found → say so once; go on.
 - Only the Land's official document (Kerncurriculum, Lehrplan, Bildungsplan, Rahmenlehrplan) from the ministry or
-  state institute. No publisher, schoolbook or portal. No Land known → KMK-Bildungsstandards.
-- Download and read it yourself.
+  state institute. No publisher, schoolbook or portal. No Land known → KMK-Bildungsstandards. The KMK has none for the subject or level (e.g. Informatik in Sekundarstufe II) → cite no unit, write "not checked" and follow the creator's material.
+- Download and read it yourself. A document you cannot read here (a PDF and no tool to read it) → mark it "not checked"; never cite it from its title alone.
 - Cite it under "Notes": title, issuer, year, address; page and unit (Inhaltsfeld, Lernbereich, Kompetenz).
 - The creator's material differs → follow the material; say so in one sentence.
 
@@ -33,6 +33,7 @@ license: MIT
 
 - Per competency one article or video (serlo.org, a channel the creator trusts, Wikipedia).
 - Read [references/sources.md](references/sources.md) before you choose, cite or rely on a source.
+- A text source (Wikipedia, a schoolbook site): take facts, never sentences. Copying a sentence needs the licence the page states; if you cannot read it, do not copy.
 
 ## 4. The creator's material and privacy
 

package/dist/skills/lernapps-explainer/SKILL.md

@@ -28,6 +28,8 @@ license: MIT
 
 - A build problem is one line `file:line: place (language): what to do`. Fix where it points.
 - Headings are `section` blocks, never Markdown headings.
+- YAML: quote a text that has `: ` in it or looks like a number (`"8."`, `"01000001"`, `"0"`). Unquoted, YAML reads a map or a
+  number: the build stops, or the digits change. A table cell, a header cell too, is a text and never empty.
 - A new chapter: a folder with `chapter.yaml`, listed in `src/app.yaml`, each page listed in `chapter.yaml`.
 - `selfAssessment` in a `chapter.yaml`: written in Commit, skill
   `lernapps-explainer-self-assessment`. An exercise it names renamed or moved → change the reference too.

package/dist/skills/lernapps-explainer-design/SKILL.md

@@ -15,7 +15,7 @@ license: MIT
 
 ## Can and cannot
 
-- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/explainer/README.md>.
+- The README of the template says it: `node_modules/@lernapps/app-templates/explainer/README.md` (in the folder `init` made).
   Read it before this skill's mapping, if you have not yet.
 
 ## Map the content

package/dist/skills/lernapps-interactive-design/SKILL.md

@@ -15,7 +15,7 @@ license: MIT
 
 ## Can and cannot
 
-- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/interactive/README.md>.
+- The README of the template says it: `node_modules/@lernapps/app-templates/interactive/README.md` (in the folder `init` made).
   Read it before this skill's mapping, if you have not yet.
 
 ## Parts

package/dist/skills/lernapps-quiz-design/SKILL.md

@@ -15,7 +15,7 @@ license: MIT
 
 ## Can and cannot
 
-- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/quiz/README.md>.
+- The README of the template says it: `node_modules/@lernapps/app-templates/quiz/README.md` (in the folder `init` made).
   Read it before this skill's mapping, if you have not yet.
 
 ## Map the content

package/generator/create.ts

@@ -53,7 +53,7 @@ It needs the plan of the first version, confirmed by the creator: started from t
 tooling is moved to .vibe/plans/01-first-version.md. Without a plan, it writes nothing and says what to do.
 
 Run it in the folder lernapps init prepared, from the tooling init installed:
-  npx lernapps create --archetype <name> [<dir>]
+  npx --no -- lernapps create --archetype <name> [<dir>]
 It needs git, and the npm registry for the npm install that follows. The app then depends on the version of
 @lernapps/tooling that created it, and its workflows use the actions of that version's tag.
 
@@ -174,9 +174,9 @@ function contents(dir: string): string[] {
     if (name === "node_modules" || name === "package-lock.json") return [];
     if (name === "package.json" && readJson(join(dir, name)).lernapps?.init === true) return [];
     if (name === ".vibe") {
-      return within(name, (file) => file === "plan.md" || file === "plans").concat(
-        existsSync(join(dir, PLANS)) ? within(PLANS, (file) => PLAN_NAME.test(file)) : [],
-      );
+      // the planning folder: the plans are checked (a first version has one), what the planning leaves beside them stays
+      // (the sketches of the plan, .vibe/sketches/)
+      return existsSync(join(dir, PLANS)) ? within(PLANS, (file) => PLAN_NAME.test(file)) : [];
     }
     if ((name === ".agents" || name === ".claude") && skills.size > 0) {
       return within(name, (folder) => folder === "skills").concat(
@@ -384,7 +384,7 @@ export function create(args: string[]): number {
   const found = contents(dir);
   if (found.length > 0) {
     throw new CreateError(
-      `${dir} is not empty (${found.slice(0, 5).join(", ")}${found.length > 5 ? ", ..." : ""}): create the app in an empty folder; only .git, the first version's plan .vibe/plans/01-<short name>.md and what lernapps init wrote (its skills, package.json, package-lock.json and node_modules) may be there`,
+      `${dir} is not empty (${found.slice(0, 5).join(", ")}${found.length > 5 ? ", ..." : ""}): create the app in an empty folder; only .git, .vibe/ (the first version's plan .vibe/plans/01-<short name>.md, and its sketches) and what lernapps init wrote (its skills, package.json, package-lock.json and node_modules) may be there`,
     );
   }
   const plan = confirmedPlan(dir, archetype, values.plan);

package/generator/init.ts

@@ -24,6 +24,7 @@ export const INIT_USAGE = `Usage: lernapps init <short name> [--addon <package>]
 
 Starts an app in the current folder, which must be empty except for .git. It needs git, Node and the npm registry; nothing
 else. In order:
+  git repository               on the branch work, which the plan names (unless the folder is one already; no commit)
   package.json                  names the folder, depends on @lernapps/tooling (this version) and the add-on
   npm install                   installs them
   .vibe/plans/01-<short name>.md
@@ -61,6 +62,24 @@ const SKILLS_BIN = () => {
   return join(dirname(manifest), bin?.["skills"] ?? "bin/cli.mjs");
 };
 
+/** The branch the plan works on (rule 8 of the plan template). */
+export const WORK_BRANCH = "work";
+
+/**
+ * Makes the folder a git repository on the branch `work`, which the plan names, unless it is one already: `create` and
+ * the hooks need it, and the plan's first rule is to work there. Returns what it did, for the output; no commit.
+ */
+export function ensureRepository(dir: string): string | undefined {
+  if (existsSync(join(dir, ".git"))) return undefined;
+  const result = spawnSync("git", ["init", "--quiet", `--initial-branch=${WORK_BRANCH}`], {
+    cwd: dir,
+    encoding: "utf8",
+  });
+  if (result.error) throw new CreateError(`git cannot run: ${result.error.message}. Install git, then run init again`);
+  if (result.status !== 0) throw new CreateError(`git init failed: ${`${result.stdout}${result.stderr}`.trim()}`);
+  return `a git repository on the branch ${WORK_BRANCH}`;
+}
+
 /** The names of the skills of the archetypes, with the archetype each belongs to (lernapps-<archetype>[-…]). */
 export function archetypeSkills(): { name: string; archetype: string }[] {
   const dir = fromPackage("skills", "archetypes");
@@ -129,6 +148,7 @@ export function init(args: string[]): number {
     );
   }
   const addon = values.addon;
+  const repository = ensureRepository(dir);
   writeJson(join(dir, "package.json"), {
     name: slug(dir),
     version: "0.0.0",
@@ -157,7 +177,7 @@ export function init(args: string[]): number {
     archetypeSkills().map((skill) => skill.name),
   );
   process.stdout.write(
-    `lernapps init: ${relative(dir, target)} from ${relativeTemplate(template, dir)}; the skills of the packages are installed\nNext: read ${relative(dir, target)} completely and follow it\n`,
+    `lernapps init: ${relative(dir, target)} from ${relativeTemplate(template, dir)}; the skills of the packages are installed${repository ? `; ${repository}` : ""}\nNext: read ${relative(dir, target)} completely and follow it\n`,
   );
   return 0;
 }

package/generator/update.ts

@@ -75,8 +75,8 @@ moves the app within its version ranges; this moves the ranges, and what npm doe
 
 Run it from the latest tooling, in the app's folder, e.g. to pick up a fixed runtime:
   ${LATEST}
-Run as the app's own tooling (npx lernapps update), it knows only the versions the app already has.
-Then run npx lernapps check, and commit package.json, package-lock.json, .github/workflows/ and what else it names.
+Run as the app's own tooling (npx --no -- lernapps update), it knows only the versions the app already has.
+Then run npx --no -- lernapps check, and commit package.json, package-lock.json, .github/workflows/ and what else it names.
 
 Exit codes: 0 when the app is updated (or was up to date), 1 when it cannot be or only partly (the message says
 what was not moved and why), 2 on a usage error.
@@ -395,7 +395,7 @@ export function update(args: string[]): number {
     }
     // npm install <spec> runs no prepare script: the hooks of the new tooling, as npm install would install them
     if (installHooks([]) !== 0)
-      throw new UpdateError("lernapps hooks failed (see above); run npx lernapps hooks again");
+      throw new UpdateError("lernapps hooks failed (see above); run npx --no -- lernapps hooks again");
   }
   const changed = moveActions(`v${version}`);
   if (changed.length > 0) lines.push(`the actions of lernapps/tooling in ${changed.join(", ")}: v${version}`);
@@ -423,7 +423,7 @@ export function update(args: string[]): number {
   if (architecture.lines.length > 0) files.push(`${ARCHITECTURE}/`);
   if (plan.some((line) => line.startsWith("plan: moved"))) files.push(".vibe/ (git add -A .vibe, to keep the move)");
   process.stdout.write(
-    `Next: npx lernapps check, then commit ${files.slice(0, -1).join(", ")} and ${files.at(-1) ?? ""}\n`,
+    `Next: npx --no -- lernapps check, then commit ${files.slice(0, -1).join(", ")} and ${files.at(-1) ?? ""}\n`,
   );
   return 0;
 }

package/guidance/increment-template.md

@@ -100,7 +100,7 @@ questions. -->
       `lernapps-<archetype>-design` says, choose its pattern with skill `lernapps-exercise-patterns` (both loaded
       in Explore), and say why the guide's patterns do not fit.
 - [ ] Each new component or interactive exercise: a sketch (static SVG or image, or the steps). Words alone are not
-      enough.
+      enough. Keep sketch files in `.vibe/sketches/`.
 - [ ] Show the creator, short: goal, new competencies by chapter, slices; in plain words what learners see and do,
       what is new. At most 2 questions.
 - [ ] **Checkpoint:** confirm the plan and the content method. Stop and wait for an explicit yes. Changes → change,
@@ -137,7 +137,7 @@ cannot. Something new goes into the guide in the slice that adds it. -->
       Parallel slices: send each sub-agent `@lernapps/tooling/guidance/subagent-brief.md`, filled in.
 - [ ] The content guide describes the app as it is now (`app-content-matches`). `grep -c "FILL IN"
       .agents/skills/app-content/SKILL.md` prints 0.
-- [ ] `npx lernapps check` passes.
+- [ ] `npx --no -- lernapps check` passes.
 - [ ] Every box of Explore, Plan and Code ticked.
 - [ ] Set `phase: commit`: change the value line (`grep '^phase:'` prints `phase: commit`).
       No checkpoint here: set it before you ask or report anything, then start Commit in the same message.
@@ -158,7 +158,7 @@ cannot. Something new goes into the guide in the slice that adds it. -->
 
 - [ ] `grep '^phase:'` prints `phase: commit`; else set it.
 - [ ] An explainer whose pages or exercises changed: load skill `lernapps-explainer-self-assessment`
-      (missing → `npx lernapps skills --archetype explainer`). Update the
+      (missing → `npx --no -- lernapps skills --archetype explainer`). Update the
       self-assessment as it says (add one, if the app has none and the skill says so). Commit; the hooks check.
 - [ ] Load skill `lernapps-github`. Push the branch, open the preview pull request, see its checks to green as it
       says.

package/guidance/plan-template.md

@@ -68,7 +68,7 @@ questions. -->
 - [ ] Choose the archetype as skill `lernapps-app` says, from the kind of practice: read the README of each
       archetype in question, tell the creator what the chosen one can and cannot do. Write it and its reason under
       "Key decisions". Set `archetype`.
-- [ ] Install the archetype's skills: `npx lernapps skills --archetype <archetype>`. Load skill
+- [ ] Install the archetype's skills: `npx --no -- lernapps skills --archetype <archetype>`. Load skill
       `lernapps-<archetype>-design`.
 - [ ] Interview: ask the other topics of "Answers" in order. Skip a topic only when an earlier answer covers it; note
       which. No answer → ask once more; still none → write your assumption with "(guess)". Done when every topic
@@ -133,7 +133,7 @@ questions. -->
 - [ ] Write the Code tasks under "Code": pages or screens, their content, what each shows. Each ends in a commit.
       After the first task that shows real content: the task "Show the creator a first look (`early-preview`)".
 - [ ] Each screen, component or interactive exercise: a sketch (static SVG or image, or the steps with what
-      learners see after each). Words alone are not enough.
+      learners see after each). Words alone are not enough. Keep sketch files in `.vibe/sketches/`, which `create` leaves alone.
 - [ ] Show the creator, short: goal, competencies by chapter, entry draft, tasks, sketches; the content method in
       plain words (what learners see and do, what it cannot do). At most 2 questions.
 - [ ] **Checkpoint:** confirm the plan and the content method, with the sketches shown. Stop and wait for an
@@ -173,7 +173,7 @@ checks and cannot; how a later agent adds a chapter. Becomes the content guide i
 - [ ] <the tasks written in Plan; after each, commit on `work`; after the first with real content, show the
       creator a first look (`early-preview`) and go on>
 - [ ] The content guide matches what was built (`app-content-matches`).
-- [ ] `npx lernapps check` passes.
+- [ ] `npx --no -- lernapps check` passes.
 - [ ] Look at a screenshot of every screen and state (start, each mode, pause, end), desktop and 360 px. Compare
       each with the confirmed sketches.
 - [ ] Every box of Explore, Plan and Code ticked.
@@ -195,7 +195,7 @@ checks and cannot; how a later agent adds a chapter. Becomes the content guide i
 ### Tasks
 
 - [ ] `grep '^phase:'` prints `phase: commit`; else set it.
-- [ ] An explainer: load skill `lernapps-explainer-self-assessment` (missing → `npx lernapps skills --archetype
+- [ ] An explainer: load skill `lernapps-explainer-self-assessment` (missing → `npx --no -- lernapps skills --archetype
       explainer`). Add the self-assessment as it says, or
       write under "Key decisions" why the app has none. Commit; the hooks check.
 - [ ] Load skill `lernapps-github`. Repo and Pages as it says: ask the repo name and every click only the creator can

package/guidance/subagent-brief.md

@@ -18,7 +18,7 @@ Competencies, one slice each, in this order:
 Change only: <the files of this chapter or round>. Do not change: the content guide, the plan, <the shared files>.
 Write what the shared files need into your report instead.
 
-Per slice: content, exercise, `npx lernapps check` green, one commit. Never bypass a hook.
+Per slice: content, exercise, `npx --no -- lernapps check` green, one commit. Never bypass a hook.
 
 Report: branch, commits, per competency the ids of its page or questions and exercises, the patterns used, what the
 shared files need, what you could not verify.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lernapps/tooling",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Shared tooling of the lernapps.net apps and sites: the CLI lernapps, site actions, Renovate preset, guidance for building apps; documentation at https://lernapps.net/tooling/",
   "license": "MIT",
   "repository": {
@@ -115,7 +115,7 @@
   },
   "devDependencies": {
     "@doctc/arc42": "0.38.0",
-    "@lernapps/site": "github:lernapps/lernapps.github.io#4c677cc9949b22bcd24b168dfb00098f3ccae624",
+    "@lernapps/site": "github:lernapps/lernapps.github.io#96912a0b6691d90a538ac8336ac808152a7a2227",
     "@types/node": "26.6.5",
     "ajv": "8.20.0",
     "vite-plus": "1.4.0"

package/skills/archetypes/lernapps-explainer/SKILL.md

@@ -28,6 +28,8 @@ license: MIT
 
 - A build problem is one line `file:line: place (language): what to do`. Fix where it points.
 - Headings are `section` blocks, never Markdown headings.
+- YAML: quote a text that has `: ` in it or looks like a number (`"8."`, `"01000001"`, `"0"`). Unquoted, YAML reads a map or a
+  number: the build stops, or the digits change. A table cell, a header cell too, is a text and never empty.
 - A new chapter: a folder with `chapter.yaml`, listed in `src/app.yaml`, each page listed in `chapter.yaml`.
 - `selfAssessment` in a `chapter.yaml`: written in Commit, skill
   `lernapps-explainer-self-assessment`. An exercise it names renamed or moved → change the reference too.

package/skills/archetypes/lernapps-explainer-design/SKILL.md

@@ -15,7 +15,7 @@ license: MIT
 
 ## Can and cannot
 
-- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/explainer/README.md>.
+- The README of the template says it: `node_modules/@lernapps/app-templates/explainer/README.md` (in the folder `init` made).
   Read it before this skill's mapping, if you have not yet.
 
 ## Map the content

package/skills/archetypes/lernapps-interactive-design/SKILL.md

@@ -15,7 +15,7 @@ license: MIT
 
 ## Can and cannot
 
-- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/interactive/README.md>.
+- The README of the template says it: `node_modules/@lernapps/app-templates/interactive/README.md` (in the folder `init` made).
   Read it before this skill's mapping, if you have not yet.
 
 ## Parts

package/skills/archetypes/lernapps-quiz-design/SKILL.md

@@ -15,7 +15,7 @@ license: MIT
 
 ## Can and cannot
 
-- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/quiz/README.md>.
+- The README of the template says it: `node_modules/@lernapps/app-templates/quiz/README.md` (in the folder `init` made).
   Read it before this skill's mapping, if you have not yet.
 
 ## Map the content

package/skills/content/lernapps-content-questions/references/question-types.md

@@ -7,7 +7,7 @@
 | `true-false` | `answer` (true or false) |
 | `number` | `answer`, `tolerance` (0 = exact), `unit` if any; the learner may type a comma or a point |
 | `ordering` | `items` in the right order; the page mixes them |
-| `matching` | `pairs` as they belong; the page mixes the right side. `distractors` (1 to 4): wrong right entries that match no left one. `pairsFrom: material` instead of `pairs` takes them from the `labelled-figure` in `material` (marker left, text right; the figure needs `legend: false`) |
+| `matching` | `pairs` as they belong, each pair an object `{ left, right }`; the page mixes the right side. `distractors` (1 to 4): wrong right entries that match no left one. `pairsFrom: material` instead of `pairs` takes them from the `labelled-figure` in `material` (marker left, text right; the figure needs `legend: false`) |
 
 - Every question: `id`, `text`, `explanation`, at least one link in `links`. Optional quiz `sources`.
 - Types without options carry their background in `explanation`.

package/skills/content/lernapps-content-research/SKILL.md

@@ -15,8 +15,8 @@ license: MIT
 
 - Orientation for grade and order, not a condition. None found → say so once; go on.
 - Only the Land's official document (Kerncurriculum, Lehrplan, Bildungsplan, Rahmenlehrplan) from the ministry or
-  state institute. No publisher, schoolbook or portal. No Land known → KMK-Bildungsstandards.
-- Download and read it yourself.
+  state institute. No publisher, schoolbook or portal. No Land known → KMK-Bildungsstandards. The KMK has none for the subject or level (e.g. Informatik in Sekundarstufe II) → cite no unit, write "not checked" and follow the creator's material.
+- Download and read it yourself. A document you cannot read here (a PDF and no tool to read it) → mark it "not checked"; never cite it from its title alone.
 - Cite it under "Notes": title, issuer, year, address; page and unit (Inhaltsfeld, Lernbereich, Kompetenz).
 - The creator's material differs → follow the material; say so in one sentence.
 
@@ -33,6 +33,7 @@ license: MIT
 
 - Per competency one article or video (serlo.org, a channel the creator trusts, Wikipedia).
 - Read [references/sources.md](references/sources.md) before you choose, cite or rely on a source.
+- A text source (Wikipedia, a schoolbook site): take facts, never sentences. Copying a sentence needs the licence the page states; if you cannot read it, do not copy.
 
 ## 4. The creator's material and privacy
 

package/skills/process/lernapps-app/SKILL.md

@@ -27,11 +27,13 @@ license: MIT
 
 ## What each archetype can do
 
+The READMEs are files of the package `@lernapps/app-templates`, which `init` installed: read them from the folder, in full.
+
 | Archetype | Learners … | Can and cannot (README of its template) |
 |---|---|---|
-| `quiz` | answer questions with options and feedback | <https://raw.githubusercontent.com/lernapps/app-templates/main/quiz/README.md> |
-| `explainer` | read pages that explain, each with exercises | <https://raw.githubusercontent.com/lernapps/app-templates/main/explainer/README.md> |
-| `interactive` | act in one app page, by turns or in real time | <https://raw.githubusercontent.com/lernapps/app-templates/main/interactive/README.md> |
+| `quiz` | answer questions with options and feedback | `node_modules/@lernapps/app-templates/quiz/README.md` |
+| `explainer` | read pages that explain, each with exercises | `node_modules/@lernapps/app-templates/explainer/README.md` |
+| `interactive` | act in one app page, by turns or in real time | `node_modules/@lernapps/app-templates/interactive/README.md` |
 
 ## Choose the archetype
 

package/skills/process/lernapps-content-growth/SKILL.md

@@ -15,7 +15,7 @@ Each slice is one Code task and ends in one commit:
 3. Exercise: a pattern of the guide, varied. A new pattern goes into the guide in the same slice, with example and
    data file.
 4. Entry topic: the page or section path into the plan's entry draft (`entry-links-resolve`).
-5. Check: `npx lernapps check` passes.
+5. Check: `npx --no -- lernapps check` passes.
 6. Commit, guide changes included.
 
 - A new chapter or round: its slices in the order of the guide's procedure.

package/skills/tooling/lernapps-cli/SKILL.md

@@ -14,7 +14,7 @@ license: MIT
 ## Create
 
 1. Only after the creator's yes to the plan (`explore-before-code`). In the plan's folder:
-   `npx lernapps create --archetype <archetype>`.
+   `npx --no -- lernapps create --archetype <archetype>`.
 2. No git repo yet: `git init --initial-branch=work`. Then `npm install` (dependencies, git hooks), and commit
    everything on `work`.
 3. Needs git, Node ≥ 22.18, registry.npmjs.org. Blocked → ask the creator to allow it, run again. Never write the
@@ -29,20 +29,20 @@ license: MIT
 
 ## Check
 
-- `npx lernapps check`: format, lint, types, unit tests, build, checks of the built app, end-to-end tests. The hooks
+- `npx --no -- lernapps check`: format, lint, types, unit tests, build, checks of the built app, end-to-end tests. The hooks
   run its parts (`--pre-commit`, `--pre-push`); CI runs it whole.
-- Report: `node_modules/.cache/lernapps/validation-report.yaml`. Options: `npx lernapps check --help`.
+- Report: `node_modules/.cache/lernapps/validation-report.yaml`. Options: `npx --no -- lernapps check --help`.
 
 ## Look at the app
 
 A check says the rules hold; only a look says what a learner sees. Show the creator the pages before a push, and before
 a submission they declare something about.
 
-- Explainer or quiz: build (`npx vp build`), then `npx lernapps screenshots`. It writes one image of every page, one of
+- Explainer or quiz: build (`npx vp build`), then `npx --no -- lernapps screenshots`. It writes one image of every page, one of
   every figure, and an `index.html` that shows them in order to `screenshots/` (not part of the app: do not commit it).
   Show the images, or the `index.html` where you can show HTML. Check every figure in its own image
   (`…-figure-<n>.png`): a page image is scaled down, its details are not readable. `--desktop` adds 1280 px images.
-  Options: `npx lernapps screenshots --help`.
+  Options: `npx --no -- lernapps screenshots --help`. The folder ignores itself in git, so a later check never sees it.
 - Interactive app: `screenshots` does not support it. Open the built app with the Playwright the tooling installs
   (`import { chromium } from "playwright"`), at 390 px width, and take `page.screenshot({ fullPage: true })` of each
   state the creator should see, from a short script outside the app.