@lernapps/tooling 0.4.0 → 0.5.0

package/generator/init.ts

@@ -6,25 +6,28 @@
 // plan has chosen one: `skills --archetype <name>` then adds that archetype's. `lernapps create` later takes over the
 // package.json (the marker lernapps.init) and the installed packages.
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { parseArgs, type ParseArgsOptionsConfig } from "node:util";
 import { UsageError } from "../src/usage.ts";
 import { PLANS } from "../src/plan.ts";
-import { CreateError, fromPackage, ownVersion, readJson, TOOLING, writeJson } from "./create.ts";
+import { CreateError, fromPackage, ownVersion, readJson, TOOLING, WORK_BRANCH, writeJson } from "./create.ts";
 
 /** The options of `lernapps init`, as node:util parseArgs takes them. */
 export const INIT_OPTIONS = {
   addon: { type: "string" },
+  tooling: { type: "string" },
   help: { type: "boolean", short: "h", default: false },
 } as const satisfies ParseArgsOptionsConfig;
 
-export const INIT_USAGE = `Usage: lernapps init <short name> [--addon <package>]
+export const INIT_USAGE = `Usage: lernapps init <short name> [--addon <package>] [--tooling <spec>]
 
 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)
+  git repository               on the branch work, which the plan names; no commit. A repository without commits
+                                switches to work; one with commits stays, and init warns: git switch -c work
   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
@@ -36,6 +39,12 @@ Then follow the plan: it says what to do, and when to wait for the creator.
 
 Options:
   --addon <package>  a package that extends the tooling, e.g. @lernapps/practice: its plan template and its skills
+  --tooling <spec>   for maintainers: the npm spec of @lernapps/tooling to install instead of this version, e.g.
+                     file:/path/to/lernapps-tooling-0.0.0.tgz or github:lernapps/tooling#<commit>; give the same
+                     to lernapps create. Without it, a tooling of version 0.0.0 (a local build, not on the
+                     registry) is packed with npm pack into a temporary folder and installed from that tarball
+                     when its folder is a git checkout (file:<tarball>), with its dependencies, as from the
+                     registry
   -h, --help         print this help
 `;
 
@@ -62,22 +71,45 @@ 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";
+export { WORK_BRANCH };
+
+/** A git command in `dir`; a git that cannot run is an error of init. */
+function git(dir: string, args: string[]) {
+  const result = spawnSync("git", args, { cwd: dir, encoding: "utf8" });
+  if (result.error) throw new CreateError(`git cannot run: ${result.error.message}. Install git, then run init again`);
+  return { ok: result.status === 0, out: `${result.stdout}${result.stderr}`.trim() };
+}
+
+/** What `ensureRepository` did: a line for the output, and a warning when the plan's branch is not checked out. */
+export interface Repository {
+  done?: string;
+  warning?: string;
+}
 
 /**
- * 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.
+ * Puts the folder on the branch `work`, which the plan names: `create` and the hooks need a repository, and the plan's
+ * first rule is to work there. No repository yet → `git init` on `work`. A repository without commits (a fresh
+ * `git init` on master or main, a clone of an empty GitHub repo) → its unborn branch becomes `work`: nothing is lost,
+ * since there is nothing on it. A repository with commits on another branch is left as it is, with a warning that
+ * names the command. 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}`;
+export function ensureRepository(dir: string): Repository {
+  if (!existsSync(join(dir, ".git"))) {
+    const result = git(dir, ["init", "--quiet", `--initial-branch=${WORK_BRANCH}`]);
+    if (!result.ok) throw new CreateError(`git init failed: ${result.out}`);
+    return { done: `a git repository on the branch ${WORK_BRANCH}` };
+  }
+  const branch = git(dir, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  if (branch.ok && branch.out === WORK_BRANCH) return {};
+  if (!git(dir, ["rev-parse", "--verify", "--quiet", "HEAD"]).ok) {
+    const result = git(dir, ["symbolic-ref", "HEAD", `refs/heads/${WORK_BRANCH}`]);
+    if (!result.ok) throw new CreateError(`git could not switch to the branch ${WORK_BRANCH}: ${result.out}`);
+    return { done: `the repository had no commit yet: now on the branch ${WORK_BRANCH}` };
+  }
+  const where = branch.ok ? `on the branch ${branch.out}` : "on no branch (detached HEAD)";
+  return {
+    warning: `the repository has commits and is ${where}, not on ${WORK_BRANCH}, which the plan works on. Run next: git switch -c ${WORK_BRANCH}`,
+  };
 }
 
 /** The names of the skills of the archetypes, with the archetype each belongs to (lernapps-<archetype>[-…]). */
@@ -121,6 +153,42 @@ function syncSkills(dir: string, exclude: string[]): void {
   );
 }
 
+/** The version of a build that is not on the registry: package.json of the repository says 0.0.0. */
+const LOCAL_VERSION = "0.0.0";
+
+/**
+ * The tarball of the package in `root`, packed by npm pack (with its prepare script, so the build is current) into a
+ * new temporary folder.
+ */
+export function packBuild(root: string): string {
+  const out = mkdtempSync(join(tmpdir(), "lernapps-tooling-"));
+  run("npm", ["pack", "--silent", "--pack-destination", out], (message) => new CreateError(message), root);
+  const tarball = readdirSync(out).find((name) => name.endsWith(".tgz"));
+  if (tarball === undefined) throw new CreateError(`npm pack in ${root} wrote no tarball into ${out}`);
+  return join(out, tarball);
+}
+
+/**
+ * The spec of @lernapps/tooling that init installs: the one given, else this version. A local build (version 0.0.0,
+ * which the registry does not have) is packed when its folder is a git checkout and installed from the tarball, else
+ * init says to name one with --tooling. Not the folder itself (file:<folder>): npm links it, so the app's
+ * node_modules lacks the tooling's dependencies (Playwright for the end-to-end tests, @lernapps/app-templates with
+ * the templates and their READMEs); from a tarball they are installed into the app, as from the registry.
+ */
+export function toolingSpec(
+  given: string | undefined,
+  version = ownVersion(),
+  root = fromPackage(),
+  pack: (root: string) => string = packBuild,
+): string {
+  if (given !== undefined && given !== "") return given;
+  if (version !== LOCAL_VERSION) return version;
+  if (existsSync(join(root, ".git"))) return `file:${pack(resolve(root))}`;
+  throw new CreateError(
+    `this @lernapps/tooling is a local build (version ${LOCAL_VERSION}), which the npm registry does not have: name the tooling to install with --tooling <spec>, e.g. file:/path/to/lernapps-tooling-${LOCAL_VERSION}.tgz (npm pack) or github:lernapps/tooling#<commit>, and give the same to lernapps create`,
+  );
+}
+
 export function init(args: string[]): number {
   const { values, positionals } = parseArgs({ args, options: INIT_OPTIONS, strict: true, allowPositionals: true });
   if (values.help) {
@@ -139,6 +207,7 @@ export function init(args: string[]): number {
     );
   }
   const addon = values.addon;
+  const tooling = toolingSpec(values.tooling);
   const repository = ensureRepository(dir);
   writeJson(join(dir, "package.json"), {
     name,
@@ -149,7 +218,7 @@ export function init(args: string[]): number {
   const fail = (message: string) => new CreateError(message);
   run(
     "npm",
-    ["install", "--save-dev", "--no-audit", "--no-fund", `${TOOLING}@${ownVersion()}`, ...(addon ? [addon] : [])],
+    ["install", "--save-dev", "--no-audit", "--no-fund", `${TOOLING}@${tooling}`, ...(addon ? [addon] : [])],
     fail,
   );
 
@@ -167,8 +236,9 @@ export function init(args: string[]): number {
     dir,
     archetypeSkills().map((skill) => skill.name),
   );
+  if (repository.warning !== undefined) process.stderr.write(`lernapps init: warning: ${repository.warning}\n`);
   process.stdout.write(
-    `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`,
+    `lernapps init: ${relative(dir, target)} from ${relativeTemplate(template, dir)}; the skills of the packages are installed${repository.done ? `; ${repository.done}` : ""}\nNext: ${repository.warning ? `git switch -c ${WORK_BRANCH}, then ` : ""}read ${relative(dir, target)} completely and follow it\n`,
   );
   return 0;
 }

package/generator/update.ts

@@ -7,7 +7,8 @@
 // them replaced with versions.
 // It never moves the runtime back: a newer version (Renovate moves the runtime too) stays. An app made before the
 // generator wrote the content guide gets its skeleton (generator/create.ts), and one made before the plans had a
-// folder gets its plan .vibe/plan.md moved to .vibe/plans/01-first-version.md (src/plan.ts). The app's lernapps-*
+// folder gets its plan .vibe/plan.md moved to .vibe/plans/01-first-version.md (src/plan.ts). An explainer in format 1 gets `format: 2` and `strand: none` in src/app.yaml where the runtime knows
+// format 2. The app's lernapps-*
 // skills, which the app commits, are replaced with those of this tooling (its skills/), in the layout of
 // `npx skills add`; the app's own skills (app-content, any other) stay as they are. An interactive app's architecture
 // is replaced outside its app sections, which stay as they are (generator/architecture.ts).
@@ -40,6 +41,7 @@ import {
   ownVersion,
   readJson,
   RUNTIME,
+  runtimeSpec,
   SKILLS_LOCK,
   templatesPackage,
   TOOLING,
@@ -57,13 +59,16 @@ export const UPDATE_USAGE = `Usage: lernapps update
 Moves the app in the current folder to the versions of this @lernapps/tooling, then runs npm install. npm update
 moves the app within its version ranges; this moves the ranges, and what npm does not know:
   @lernapps/app-templates  to the version this tooling depends on: the runtime its tests ran with. A newer version
-                           (e.g. from Renovate) is kept. A git commit, as apps once pinned, becomes a version
+                           (e.g. from Renovate) is kept. A git commit, as apps once pinned, becomes a version; while
+                           this tooling depends on a commit (an unreleased runtime), the app moves to that commit
   @lernapps/tooling        to the version of this tooling (unchanged when run from the app)
   .github/workflows/       the actions of lernapps/tooling at the tag of that version
   .agents/skills/app-content/SKILL.md
                            the content guide's skeleton, where the app has none yet (and its link for Claude Code)
   .vibe/plan.md            the plan of an app made before the plans had a folder: moved to
                            .vibe/plans/01-first-version.md, the first of its plans (one per piece of work)
+  src/app.yaml             of an explainer in format 1, when the runtime knows format 2: adds format: 2 and
+                           strand: none (the app is not on the learning map; its pages need no competencies)
   .agents/skills/lernapps-*, .claude/skills/lernapps-*, skills-lock.json
                            replaced with the skills of this tooling, as npx skills add lays them out: those of
                            every phase, and of the archetypes only those of the current plan's archetype; every
@@ -98,9 +103,16 @@ function lowest(range: string): [number, number, number] | undefined {
 const older = (a: [number, number, number], b: [number, number, number]) =>
   a[0] !== b[0] ? a[0] < b[0] : a[1] !== b[1] ? a[1] < b[1] : a[2] < b[2];
 
-/** The next range of a dependency at `version`, and what the output says about it. */
-export function nextRange(name: string, current: string | undefined, version: string): { spec: string; line: string } {
-  const target = `^${version}`;
+/**
+ * The next range of a dependency at `version` (target: ^ that version, or the spec given, e.g. a git commit of an
+ * unreleased runtime), and what the output says about it.
+ */
+export function nextRange(
+  name: string,
+  current: string | undefined,
+  version: string,
+  target = `^${version}`,
+): { spec: string; line: string } {
   // a local copy (a folder or a tarball of the package, as an app under development uses) is the creator's choice
   if (current !== undefined && /^(file:|link:|\.{0,2}\/)/.test(current)) {
     return { spec: current, line: `${name}: kept ${current}, a local copy` };
@@ -108,8 +120,9 @@ export function nextRange(name: string, current: string | undefined, version: st
   const now = current === undefined ? undefined : lowest(current);
   const next = lowest(version);
   if (current === target) return { spec: current, line: `${name}: unchanged (${current})` };
-  // a newer version than this tooling's stays: it must never move back
-  if (now !== undefined && next !== undefined && !older(now, next)) {
+  // a newer version than this tooling's stays: it must never move back; a commit (no version to compare) is where the
+  // tooling's tests ran, so the app moves to it
+  if (lowest(target) !== undefined && now !== undefined && next !== undefined && !older(now, next)) {
     return { spec: current ?? target, line: `${name}: kept ${current}, not moved to ${target}: it is not older` };
   }
   return { spec: target, line: `${name}: ${current ?? "none"} → ${target}` };
@@ -148,6 +161,35 @@ function migratePlan(): string[] {
   ];
 }
 
+/** The explainer's app file, and the schema file that tells the runtime knows format 2 (learning map). */
+const EXPLAINER_APP = join("src", "app.yaml");
+const EXPLAINER_V2_SCHEMA = join("runtime", "explainer", "explainer.v2.schema.json");
+
+/**
+ * Moves an explainer from format 1 to format 2 (the learning map): adds `format: 2` and `strand: none` to
+ * src/app.yaml when the app has neither, and points its schema comment to explainer.v2.schema.json. `strand: none`
+ * keeps the app off the map, so its pages need no competencies; the creator may name a strand later (skill
+ * lernapps-content-research). Only where the runtime of this tooling has the v2 schema: an older runtime does not
+ * know the fields. An app that is no explainer, or already has a `format` or a `strand`, stays as it is. What it did,
+ * as lines of the output.
+ */
+export function migrateExplainer(templatesRoot: string): string[] {
+  if (!existsSync(EXPLAINER_APP) || !existsSync(join(templatesRoot, EXPLAINER_V2_SCHEMA))) return [];
+  const text = readFileSync(EXPLAINER_APP, "utf8");
+  const top = (key: string) => new RegExp(`^${key}:`, "m").test(text);
+  if (!top("chapters") || top("format") || top("strand")) return [];
+  const schema = /^(# yaml-language-server: \$schema=.*)explainer\.v1\.schema\.json$/m;
+  const fields = "format: 2\nstrand: none\n";
+  let next: string;
+  if (schema.test(text))
+    next = text.replace(schema, (_all, head: string) => `${head}explainer.v2.schema.json\n${fields.trimEnd()}`);
+  else next = fields + text;
+  writeFileSync(EXPLAINER_APP, next);
+  return [
+    `explainer: ${EXPLAINER_APP} moved to format 2: added format: 2 and strand: none (not on the learning map; pages need no competencies). To join the map, pick a strand of https://lernapps.net/apps/map/ and give every page competencies`,
+  ];
+}
+
 /**
  * The skills of this tooling, as it ships them (skills/<group>/<name>/), and as the app keeps them (flat, by name).
  * Every app has those of the groups process, tooling and content; of the group archetypes only those of its own
@@ -371,7 +413,7 @@ export function update(args: string[]): number {
   const notMoved: string[] = [];
   const runtime = devDependencies[RUNTIME];
   if (runtime !== undefined) {
-    const next = nextRange(RUNTIME, runtime, templates.version);
+    const next = nextRange(RUNTIME, runtime, templates.version, runtimeSpec(templates.version));
     if (next.spec !== runtime) specs.push(`${RUNTIME}@${next.spec}`);
     lines.push(next.line);
   }
@@ -404,6 +446,8 @@ export function update(args: string[]): number {
   lines.push(...guide.map((line) => `content guide: ${line}`));
   const plan = migratePlan();
   lines.push(...plan);
+  const explainer = migrateExplainer(templates.root);
+  lines.push(...explainer);
   const skills = [...replaceSkills(), ...unignoreSkills()];
   lines.push(...skills);
   const architecture = updateArchitecture();
@@ -421,6 +465,7 @@ export function update(args: string[]): number {
   if (skillsMoved) files.push(SKILLS_LOCK);
   if (skills.some((line) => line.includes(".gitignore"))) files.push(".gitignore");
   if (architecture.lines.length > 0) files.push(`${ARCHITECTURE}/`);
+  if (explainer.length > 0) files.push(EXPLAINER_APP);
   if (plan.some((line) => line.startsWith("plan: moved"))) files.push(".vibe/ (git add -A .vibe, to keep the move)");
   process.stdout.write(
     `Next: npx --no -- lernapps check, then commit ${files.slice(0, -1).join(", ")} and ${files.at(-1) ?? ""}\n`,

package/guidance/increment-template.md

@@ -45,7 +45,7 @@ a correction.
 
 ## Notes
 
-<!-- Curriculum orientation, new competencies by chapter, didactic approach, scope, sources and licences, open
+<!-- Curriculum orientation, new competencies by chapter (ids of the strand), didactic approach, scope, sources and licences, open
 questions. -->
 
 ## Explore
@@ -68,12 +68,19 @@ questions. -->
       "(guess)". Topics: which competencies, chapters or rounds, for which school years; hurdles and examples;
       amount; any change of look and feel or terms.
 - [ ] Load skill `lernapps-content-research`. Research what the guide's curriculum and sources do not cover. Under
-      "Notes": curriculum orientation, new competencies by chapter as "Ich kann …", verified sources.
+      "Notes": curriculum orientation, new competencies by chapter as "Ich kann …", verified sources. The app keeps its
+      strand; with one, the new competencies are only those of that strand in the learning map (ids), as skill
+      `lernapps-content-research` says, an explainer as a rule one page each; competencies that build on each other (the
+      map's `requires`) share a chapter, in that order. None in the map → propose it to the
+      catalog. `strand: none` and a strand fits → recommend it.
 - [ ] Under "Notes": the didactic approach per competency and the scope (in, out, data range).
 - [ ] A kind of content the guide does not cover (a new page structure, screen, component or kind of exercise) →
       load skills `lernapps-<archetype>-design` and `lernapps-exercise-patterns`. Else skip this task.
-- [ ] **Checkpoint:** research. Show in plain words: curriculum orientation, new competencies by chapter, didactic
-      approach, scope, every "(guess)", sources and how you checked them, what is unchecked. Stop and wait.
+- [ ] **Checkpoint:** research. Show in plain words: curriculum orientation, new competencies by chapter (with their
+      ids), didactic
+      approach, scope, every "(guess)", sources and how you checked them, what is unchecked. With a strand, the map
+      decides the structure: new competencies that build on each other (its `requires`) share a chapter, in that
+      order; no curriculum search is needed for it. Stop and wait.
       Changes → change, ask again.
 - [ ] Set `phase: plan`: change the value line (`grep '^phase:'` prints `phase: plan`).
 
@@ -110,7 +117,8 @@ questions. -->
 ### Content method
 
 <!-- One line each: the guide's patterns, figures and components used, and where; anything new, what it does and
-cannot. Something new goes into the guide in the slice that adds it. -->
+cannot; an explainer on the map: per new page its prerequisites the app does not practise, and which get a recap
+page, which a link. Something new goes into the guide in the slice that adds it. -->
 
 ### Completed
 

package/guidance/plan-template.md

@@ -42,7 +42,7 @@ For you, the assistant.
 
 ## Notes
 
-<!-- Curriculum orientation, competencies by chapter, didactic approach, scope, sources and licences, open
+<!-- Strand (<subject>/<strand> or none), curriculum orientation, competencies by chapter (ids), didactic approach, scope, sources and licences, open
 questions. -->
 
 ## Explore
@@ -59,7 +59,7 @@ questions. -->
 
 - [ ] The skills of the phases are in `.agents/skills/` (`npx --yes @lernapps/tooling init <short name>` put them there
       and wrote this plan; the app commits them). `.agents/skills/lernapps-app` missing → stop and tell the creator
-      the folder was not started with `init`.
+      the folder was not started with `init`. `git branch --show-current` prints `work`; else `git switch -c work`.
 - [ ] Load skill `lernapps-app`. Tell the creator in two sentences what a lernapps app is and where it will live: at
       their own address, free, public, and once listed as a copy on lernapps.net. The technical part (GitHub) comes at the end, and you do it.
 - [ ] Interview: ask the topics "Goal" and "Learners" of "Answers".
@@ -74,7 +74,11 @@ questions. -->
       which. No answer → ask once more; still none → write your assumption with "(guess)". Done when every topic
       has an answer or a guess.
 - [ ] Load skill `lernapps-content-research`. Research as it says. Under "Notes": curriculum orientation,
-      competencies by chapter as "Ich kann …", verified sources. No competencies → not done.
+      competencies by chapter as "Ich kann …", verified sources. No competencies → not done. First the learning map as
+      skill `lernapps-content-research` says: recommend a strand that fits (`<subject>/<strand>`), else `none`; with a
+      strand, only its competencies, by their ids from the map. Write both under "Notes", and how they map onto
+      chapters and pages (an explainer: as a rule one page per competency; competencies that build on each other, by
+      the map's `requires`, share a chapter, in that order).
 - [ ] Under "Notes", one line per competency: how learners get there (derive, not only read off; e.g. a tree diagram
       shows how a probability comes about), which misconception the feedback catches.
 - [ ] Under "Notes", the scope: what is in, what is out and why, the data range (e.g. "all main-group elements",
@@ -82,8 +86,10 @@ questions. -->
 - [ ] Fetch https://lernapps.net/apps/schemas/entry.v1.schema.json and read each property's description. Ask what
       helps teachers and parents find the app. Fill "Entry draft". Search words: one or two words each, as people
       type them.
-- [ ] **Checkpoint:** research. Show in plain words: curriculum orientation, competencies by chapter, didactic
-      approach, scope, every "(guess)", sources and how you checked them, what is unchecked, archetype and reason.
+- [ ] **Checkpoint:** research. Show in plain words: the strand or why none, curriculum orientation, competencies by
+      chapter (with their ids) and their pages, didactic approach, scope, every "(guess)", sources and how you
+      checked them, what is unchecked, archetype and reason. With a strand, the map decides the structure: competencies
+      that build on each other (its `requires`) share a chapter, in that order; no curriculum search is needed for it.
       Stop and wait. Changes → change, ask again.
 - [ ] Set `phase: plan`: change the value line (`grep '^phase:'` prints `phase: plan`).
 
@@ -132,11 +138,12 @@ questions. -->
 - [ ] Map the content as skill `lernapps-<archetype>-design` says; reread it if it is no longer in view.
 - [ ] Choose a pattern per competency as skill `lernapps-exercise-patterns` says (loaded in Explore; reread it if it
       is no longer in view). Write "Content method".
-- [ ] Write the Code tasks under "Code": pages or screens, their content, what each shows. Each ends in a commit.
+- [ ] Write the Code tasks under "Code": pages or screens, their content, what each shows. Each ends in a commit:
+      one task, one commit. Steps too small for a commit of their own → one task.
       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. 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
+- [ ] Show the creator, short: goal, competencies by chapter (chapters along the map's `requires`), 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
       explicit yes. Changes → change, ask again. No `create` before the yes.
@@ -145,7 +152,8 @@ questions. -->
 ### Content method
 
 <!-- One line each: exercise patterns and where; figures and how they are made; data files; each component, what it
-checks and cannot; how a later agent adds a chapter. Becomes the content guide in Code. -->
+checks and cannot; how a later agent adds a chapter. An explainer on the map: per page its prerequisites (`requires`)
+the app does not practise, and which get a recap page, which a link. Becomes the content guide in Code. -->
 
 ### Completed
 
@@ -153,7 +161,8 @@ checks and cannot; how a later agent adds a chapter. Becomes the content guide i
 
 <!--
 - Build the app from the archetype and the confirmed plan, locally on `work`. Work on your own.
-- Commit after each task; the hooks check. A check fails → skill `lernapps-cli`. Fix from the message; never
+- Commit after each task, literally: one task, one commit, its box ticked in it; the hooks check. Never one commit
+  for several tasks: join them into one task in the plan first. A check fails → skill `lernapps-cli`. Fix from the message; never
   bypass a hook.
 - Undecidable → choose, mark "(guess)" under "Key decisions", go on.
 - Creator asks for a change → first say your reading in one sentence ("Ich nehme alle 44 Hauptgruppenelemente
@@ -168,10 +177,15 @@ checks and cannot; how a later agent adds a chapter. Becomes the content guide i
 - [ ] Load skill `lernapps-cli`. Create the app in this plan's folder as it says. `create` keeps this plan. Never
       write the app by hand.
 - [ ] Fill the content guide `.agents/skills/app-content/SKILL.md` from "Notes" and "Content method"
-      (`app-content-guide`). `grep -c "FILL IN" .agents/skills/app-content/SKILL.md` prints 0. Commit it before
-      any content.
+      (`app-content-guide`). Keep its nine headings and fill each: Curriculum, Competencies, Content structure,
+      Terminology, Exercise patterns, Figures, Sources, Adding a chapter or round, Rules learned from mistakes
+      ("None yet." until the first). `grep -c "FILL IN" .agents/skills/app-content/SKILL.md` prints 0. Commit it
+      before any content.
 - [ ] Load skill `lernapps-<archetype>` and the content guide. Questions with options and feedback: also skill
       `lernapps-content-questions`.
+- [ ] An explainer: decide on `scope` as `references/structure.md` of skill `lernapps-explainer` says. Needed with an
+      `open-task` or the creator's material: then `scope` in `src/app.yaml` and on every page
+      (`explainer-scope-matches`). Write the choice under "Key decisions".
 - [ ] <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`).

package/guidance/workflow-rules.md

@@ -87,7 +87,9 @@ scope: tooling
 severity: error
 ```
 
-- Keep `.agents/skills/app-content/SKILL.md` with its fixed headings.
+- Keep `.agents/skills/app-content/SKILL.md` with its fixed headings, in this order, each filled: Curriculum,
+  Competencies, Content structure, Terminology, Exercise patterns, Figures, Sources, Adding a chapter or round,
+  Rules learned from mistakes ("None yet." until the first rule).
 - After the plan is confirmed and before content: replace every placeholder ("FILL IN") with concrete instructions
   for writing new content: files, ids, data files, an example of this app. Not how the app works, no general advice.
 - A content decision changes (pattern, figure type, source rule) → change the guide in the same commit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lernapps/tooling",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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": {
@@ -107,7 +107,7 @@
     "arc42": "arc42 --dir docs/arc42"
   },
   "dependencies": {
-    "@lernapps/app-templates": "0.2.1",
+    "@lernapps/app-templates": "github:lernapps/app-templates#4fdc214e60ce4523d8233d3ed9b37641601b2fa9",
     "axe-core": "4.14.0",
     "playwright": "1.64.1",
     "skills": "1.7.4",

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

@@ -9,9 +9,10 @@ license: MIT
 - You write YAML in `src/`; a Vue component only where the plan names one. Rendering, navigation, formulas, figures,
   exercises, accessibility, languages and the no-JS page come from the runtime `@lernapps/app-templates`.
 - `create` writes a placeholder: one chapter with one page and one exercise. Replace it with the planned content. The complete example, the chapter "Prozent" with a component, is in `node_modules/@lernapps/app-templates/explainer/`: look things up there, never copy it.
-- Schema: `node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json`. Start every YAML file with
-  `# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json`
-  (one `../` less in `src/app.yaml`).
+- Schema: `node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json` (format 2: `format: 2`
+  in `src/app.yaml`, as `create` writes it). Start every YAML file with
+  `# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json`
+  (one `../` less in `src/app.yaml`). Only an app that has not moved to format 2 keeps `explainer.v1.schema.json`.
 - Questions of the quiz's types: also skill `lernapps-content-questions`.
 
 ## Read when
@@ -22,7 +23,8 @@ license: MIT
 - [references/components.md](references/components.md): only when the plan names a component.
 - [references/runtime.md](references/runtime.md): when the build or a runtime test fails, and before you set up the
   tutor.
-- [references/rules.md](references/rules.md): when a check names an `explainer-*` or `vue-component-*` rule.
+- [references/rules.md](references/rules.md): when a check names an `explainer-*`, `vue-component-*` or
+  `competencies-on-map` rule, and before you write a page with `competencies`.
 
 ## Gotchas
 
@@ -30,6 +32,10 @@ license: MIT
 - 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 page with `competencies` teaches what their "Ich kann …" in the map says, not clearly more or other
+  (`content-matches-competencies`).
+- A page with formulas written through the shell: a heredoc with an unquoted delimiter replaces `$…` and `\`
+  (`<<EOF`). Quote the delimiter (`<<'EOF'`), or write the file with the file tool.
 - 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/references/blocks.md

@@ -10,7 +10,7 @@
 | `section` | `id`, `title`, `blocks` | heading and blocks |
 | `text` | `text` | prose |
 | `formula` | `formula` (LaTeX subset, no `$`) | formula on its own line, MathML |
-| `figure` | `draw` (`hundred-grid` with `filled`, `bar` with `part`, `whole`) or `image` (`images/<name>.svg`, `source`, `licence`); `alt`, `caption` | inline SVG or bundled image |
+| `figure` | `draw` (`hundred-grid` with `filled`, `bar` with `part`, `whole`) or `image` (`images/<name>.svg`, `source`, `licence`); `alt`, `caption` | inline SVG or bundled image; `bar` is one strip, the whole, with the part shaded and labelled with its percentage: a part of a whole only, never two quantities side by side or a value above the whole (an `image` or a `table` instead) |
 | `labelled-figure` | `image`, `alt`, `caption`, `labels` (`x`, `y` in %, `text`, optional `marker` of 1 to 3 characters, e.g. the material's `A` to `E`, else the number), `legend` (default `true`; `false` shows only the markers, then `alt` names every marker), `source`, `licence` | image with markers (letters or numbers) and a legend of the texts |
 | `table` | `caption`, `header`, `rowHeaders`, `rows` | table with caption |
 | `timeline` | `events` (`date`, `title`, `label`, `text`) or `data` | dated events, earliest first |
@@ -62,6 +62,10 @@
 - LaTeX subset → MathML; `formula` block or inline `$…$`.
 - Commands: `\frac`, `\cdot`, `\times`, `\div`, `\%`, `\text`, `^`, `_`, `\sqrt`, `\approx`, `\pm`, `\le`, `\ge`,
   `\neq`, `\,`, parentheses, braces (`\{`, `\}`).
+- Trigonometry and more: `\sin`, `\cos`, `\tan`, `\arcsin` (or `\sin^{-1}`), `\arccos`, `\arctan`, Greek letters
+  (`\alpha`, `\varphi`, `\pi`, `\Delta`, …), degrees (`30^\circ`), spaces (`\ `, `\quad`, `\qquad`), `\Rightarrow`,
+  `\Leftrightarrow`, `\left(` … `\right)`:
+  `'\sin \alpha = \frac{a}{c} \quad \Rightarrow \quad a = c \cdot \sin \alpha'`.
 - Chemistry (mhchem): `\ce{2H2 + O2 -> 2H2O}`, `\ce{CO2 + H2O <=> H2CO3}`, units `\pu{123 kJ/mol}`.
 - Other command or parse error → build fails with the place.
 - YAML formulas in single quotes. Same in every language unless `\text{…}` differs (then a map).
@@ -80,6 +84,6 @@
 
 ## Data files
 
-- `src/data/<name>.yaml`: list of records, same lowercase fields; values number, boolean, text (map if several
-  languages).
+- `src/data/<name>.yaml`: list of records, same fields; a field name starts with a lower-case letter, then letters
+  and digits (`masse`, `hoeheM`; not `Masse`, `h_m`); values number, boolean, text (map if several languages).
 - Used by `timeline` (`data: ereignisse`) and `generated` (`from: { data: elemente }`). Each fact once, there.

package/skills/archetypes/lernapps-explainer/references/exercises.md

@@ -27,6 +27,9 @@
 - New task per seed.
 - `given`: `int: [min, max]` + `step`; `decimal: [min, max]` + `step`; `oneOf: [...]`; `pick: <n>` `from:` list or
   `{ data: <name> }` (`distinct: true`; `pick: 1` = one record).
+- An inline `from:` list holds numbers or texts only: a record in it (`{ de: …, en: … }`) is read as a text by
+  language and takes text values only. Records with numbers (`{ name: Stein, masse: 2 }`) → a data file
+  (`src/data/<name>.yaml`, `blocks.md`) and `from: { data: <name> }`.
 - `where`: boolean expressions; failing draws are redrawn.
 - `task`: `text`. A figure that changes with the task: an exercise component (`components.md`).
 - `answer`: `value` (expression) and `compare`: `number` or
@@ -36,6 +39,9 @@
 - Expressions (no eval): exact fractions, `+ - * /`, parentheses, `== != < <= > >=`, `and`, `or`, `not`, strings,
   fields (`e.year`), index (`xs[0]`), lists, `round(x, n)`, `decimals`, `map(xs, field)`,
   `sortBy(xs, field)`, `reverse`.
+- `sqrt(x)`, `pow(x, n)`, `sin(x)`, `cos(x)`, `tan(x)`, `asin(x)`, `acos(x)`, `atan(x)`, angles in degrees
+  (`sin(30)` is `1/2`, `asin(0.5)` is `30`). A rational result is exact; any other (`sqrt(2)`, `sin(10)`) has 12
+  decimal places: give the answer with `round(…, n)` and `compare: { number: { decimals: n, tolerance } }`.
 
 ### Placeholders
 

package/skills/archetypes/lernapps-explainer/references/rules.md

@@ -283,3 +283,32 @@ severity: warning
   belong to it.
 - Each page's scope says what the page teaches, no more and no less; "Gehört nicht dazu" names what a learner or tutor
   might expect but the material does not teach.
+
+## `content-matches-competencies`: Each page teaches its competencies
+
+```rule
+id: content-matches-competencies
+scope: tooling
+severity: hint
+```
+
+- A page of a format-2 explainer with a strand teaches what the "Ich kann …" (`iCan`) of its competencies says in
+  `https://lernapps.net/apps/map/<subject>.json`: not clearly more, not something else.
+- More to teach → a page of the competency that says it; none in the map → propose it to `lernapps/apps`
+  (`map/<subject>.yaml`), never invent it in the app.
+- The review reads each page with the `iCan` of its competencies.
+
+## `competencies-on-map`: The strand and the page competencies are on the map
+
+```rule
+id: competencies-on-map
+scope: tooling
+severity: warning
+```
+
+- `strand` in `src/app.yaml` is a strand of the subject's map; each page's `competencies` are ids of that strand.
+- A recap page's `recap` (`<subject>/<competency>`) is on the map, of any strand, and the app does not practise it
+  on a page of its own.
+- `lernapps check` loads `https://lernapps.net/apps/map/<subject>.json` and warns before the push. Not reachable or
+  no map yet → one hint that it could not check.
+- At the listing an unknown id or one of another strand is an error of the catalog (`entry-learning-map`).