@lernapps/tooling 0.4.0 → 0.5.0

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

@@ -15,11 +15,18 @@ license: MIT
 
 1. Only after the creator's yes to the plan (`explore-before-code`). In the plan's folder:
    `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`.
+2. `create` installs nothing and commits nothing; its last lines say what follows, in this order: no git repo yet
+   (`lernapps init` makes one): `git init --initial-branch=work`; then `npm install` (runtime, git hooks); then commit
+   everything on `work` (`git add -A`, `git commit`; the hooks check it).
 3. Needs git, Node ≥ 22.18, registry.npmjs.org. Blocked → ask the creator to allow it, run again. Never write the
    app by hand.
 4. It keeps the plan and the installed skills, and writes the content guide's skeleton.
+5. Maintainers only, to try a tooling that is not on the registry (a local build has version `0.0.0`): give it to
+   both, `lernapps init <short name> --tooling <spec>` and `create --tooling <spec>`, e.g.
+   `file:/path/to/lernapps-tooling-0.0.0.tgz` (from `npm pack`) or `github:lernapps/tooling#<commit>`. Run from a
+   checkout of the tooling, `init` packs it into a temporary folder and installs that tarball by itself; `create`
+   takes the same from `package.json`. A sandbox without a server for the map: `LERNAPPS_TEST_MAP_URL=<folder>` (or a
+   `file:` URL) makes `lernapps check` read `<folder>/<subject>.json`.
 
 ## Update
 
@@ -38,8 +45,10 @@ license: MIT
 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 --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).
+- Explainer or quiz: build (`npx vp build` writes `dist/`; `npm run build` writes `_site/`), then
+  `npx --no -- lernapps screenshots`: it takes the newer of `dist/` and `_site/`, or the folder you name. 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 --no -- lernapps screenshots --help`. The folder ignores itself in git, so a later check never sees it.

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

@@ -81,6 +81,8 @@ severity: warning
 
 - At least one link per question, best the German Wikipedia (`https://de.wikipedia.org/wiki/...`).
 - `title` names the page ("Uluru (Wikipedia)").
+- No page of its own (a term like "Wortgleichung"): the page that fits best, preferably the one the question's facts
+  came from. Never no link (the schema needs one).
 - HTTP 429 → tell the creator which; mark the facts "not checked" in the plan; go on.
 
 ## `quiz-own-words`: Write in your own words

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

@@ -9,7 +9,8 @@
 | `ordering` | `items` in the right order; the page mixes them |
 | `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`.
+- Every question: `id`, `text`, `explanation`, at least one link in `links` (no fitting page: `quiz-further-reading`).
+  Optional quiz `sources`.
 - Types without options carry their background in `explanation`.
 - Optional `material`: what the question shows between its text and its answers, a list of blocks: `text` (restricted
   Markdown), `formula`, `figure`, `labelled-figure`, `table`, `quote`, `code`. A `figure` is `image: images/<name>.svg`

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

@@ -20,22 +20,58 @@ license: MIT
 - 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.
 
-## 2. Competencies
+## 2. The learning map
 
-- One per line: "Ich kann …" with one observable verb (berechnen, zuordnen, erklären, unterscheiden, ablesen,
+Before you write competencies, look at the learning map of the subject. A strand is recommended, not required.
+
+- Open `https://lernapps.net/apps/map/<subject>.json` (for you); people see it at `https://lernapps.net/apps/map/<subject>/`.
+  `<subject>` is the file name in the catalog, e.g. `mathematik`. Read it from the file or the page, in full.
+- A strand fits the app → recommend it to the creator: one app, one strand. A strand runs over several school years;
+  a topic that spans two strands is two apps. Show the strand and its competencies (Bausteine), with the ones still
+  no app practises.
+- The creator takes the strand → the app practises only competencies of that strand. Write each with its id from the
+  map. The app's "Ich kann …" competencies are those of the map, in its words: do not reword or invent them. The
+  map's `requires` shows what learners need first; a prerequisite the app does not practise, of any strand, gets a
+  recap page or a link to the map (skill `lernapps-explainer-design`).
+- The map lacks a competency the creator wants → do not invent it in the app. Propose it to the catalog: an issue or a
+  pull request in `lernapps/apps` (`map/<subject>.yaml`, the strand's list). Say so to the creator; go on with the
+  ones the map has, or wait for the answer.
+- No strand fits, the creator wants none, or the subject has no map (the address answers "not found") →
+  `strand: none`. The app is listed as usual, only not on the map; write its competencies as in the next section.
+- Write the strand (`<subject>/<strand>`, or `none`) and the competency ids under "Notes".
+- Tell the creator now how the content will be structured: a competency is one teachable thing (one or two lessons);
+  in an explainer as a rule one page per competency, chapters of competencies that build on each other (skill
+  `lernapps-explainer-design`).
+
+### `strand-from-map`: Recommend a strand of the learning map
+
+```rule
+id: strand-from-map
+scope: tooling
+severity: hint
+```
+
+- The subject has a learning map → check its strands and recommend the one that fits the app.
+- `strand: none` only when no strand fits or the creator wants none; say why under "Notes".
+- With a strand: only that strand's competencies, by their ids; a missing one is proposed to `lernapps/apps`.
+
+## 3. Competencies
+
+- With a strand: those of the map, see above. Without: one per line: "Ich kann …" with one observable verb (berechnen, zuordnen, erklären, unterscheiden, ablesen,
   zeichnen). Never "verstehen" or "kennen".
   - Yes: "Ich kann die Stromstärke in einem Reihenstromkreis berechnen."
   - No: "Ich verstehe den elektrischen Strom."
-- Group them into chapters, in the order of the Lehrplan or the material. Many chapters are still one app.
+- Group them into chapters of competencies that build on each other, in the order of the Lehrplan, the material
+  or the map's `requires`. Many chapters are still one app.
 - Write them under "Notes". Show them at the checkpoint "research".
 
-## 3. Second sources
+## 4. Second sources
 
 - 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
+## 5. The creator's material and privacy
 
 - The creator's material stays local: never commit or quote it. Only the competencies derived from it go into the
   repo.

package/dist/skills/lernapps-exercise-patterns/references/mathematics.md

@@ -10,10 +10,34 @@
 | Idea | Learners see and do | Expressed with |
 |---|---|---|
 | Part of a whole (percent, fractions) | a 10×10 grid with the part filled; compute the part, the whole or the rate | `figure` `hundred-grid` on the page; `generated` with `compare: { number: { format: percent } }`; a figure that changes with the task: an exercise component |
-| Before and after a change | two bars, old and new value; compute the change or the new value | `figure` `bar` (`part`, `whole`) on the page; `generated` with the typical mistake "added the rate instead of the amount" |
+| Before and after a change | old and new value; compute the change or the new value | a decrease: `figure` `bar` (`part` the new value, `whole` the old; it draws only a part of a whole); an increase: a `table` or an `image` of two bars; `generated` with the typical mistake "added the rate instead of the amount" |
 | Product of brackets (binomial formulas) | a rectangle split into a², ab, ab, b², lengths from the task | `image` (SVG) for the rule; `generated` for the task; a component only for lengths that follow the task |
 | Difference of squares | a² − b² as an L-shape, rearranged into (a + b)(a − b) | two `image`s side by side with captions; `ordering` of the steps |
 | Outcome set (Laplace) | die faces, wheel sectors or balls, the favourable ones marked | `table` or `image`; `generated` drawing from a data file of experiments, answer as a fraction |
 | Multi-stage experiment | a tree from top to bottom with branch probabilities; multiply along a path | `image` (SVG) of the tree; `generated` with the path rule; a clickable tree as a component |
 | Drawing without replacement | an urn before and after one ball is taken | two `image`s; `generated` with `pick: 2, distinct: true` from a data file of balls |
 | Unit conversion | a value with one unit; give it in another | `generated` with `compare: { number: { unit } }` and the mistake "factor in the wrong direction" |
+| Sides and angles in a right triangle (trigonometry) | a right triangle, the angle α marked, its sides named from α (Gegenkathete, Ankathete, Hypotenuse); compute a side from an angle and a side, or an angle from two sides | `image` (SVG) of the triangle with the right angle and α marked, the sides labelled; `formula` with `\sin`, `\cos`, `\tan`, `\arcsin`, Greek letters and `^\circ`; `generated` with `sin`/`cos`/`tan`, `asin`/`acos`/`atan` (degrees) and `sqrt`, answer rounded (`round`, `decimals`, `tolerance`); mistakes: opposite and adjacent side swapped (`cos` instead of `sin`), calculator in radians (the value of `sin` of α taken as radians), sin⁻¹ confused with 1/sin; a triangle that changes with the task: an exercise component |
+
+## Example: a side in a right triangle
+
+```yaml
+- type: generated
+  id: gegenkathete-berechnen
+  given:
+    c: { int: [5, 20] }
+    alpha: { int: [20, 70], step: 5 }
+  task:
+    text: "In einem rechtwinkligen Dreieck ist die Hypotenuse c = {{c}} cm lang, der Winkel α = {{alpha}}°. Wie lang ist die Gegenkathete a von α? Runde auf eine Stelle nach dem Komma."
+  answer:
+    value: "round(c * sin(alpha), 1)"
+    compare: { number: { format: decimal, decimals: 1, tolerance: 0.1, unit: cm } }
+  mistakes:
+    - { value: "round(c * cos(alpha), 1)", message: "Das ist die Ankathete: die Gegenkathete liegt α gegenüber, also Sinus." }
+    - { value: "round(c * sin(alpha * 57.29578), 1)", message: "Dein Taschenrechner rechnet im Bogenmaß (RAD): stelle ihn auf Grad (DEG)." }
+    - { value: "round(c / sin(alpha), 1)", message: "sin α = a : c, also a = c · sin α: mal, nicht geteilt." }
+```
+
+An angle from two sides: `answer: { value: "round(asin(a / c), 1)" }`, in degrees. Mistakes: opposite and adjacent
+swapped (`round(acos(a / c), 1)`, the other angle); sin⁻¹ taken as 1 : sin (`round(c / a, 1)`: "sin⁻¹ ist die
+Umkehrfunktion, nicht 1 : sin"). A mistake value must have a value: `asin(c / a)` with c > a has none.

package/dist/skills/lernapps-exercise-patterns/references/physics.md

@@ -16,3 +16,4 @@
 | Lever and moment | a beam with weights at distances; does it balance | `image` of the beam; `generated` for F₁ · a₁ = F₂ · a₂; a component with draggable weights |
 | Optics | a ray diagram of a convex lens; where the image forms | `labelled-figure` of the rays; `true-false` on image properties; a component with a draggable object |
 | Density | blocks of equal mass and different volumes; float or sink | `table` from a data file of materials; `generated` with `compare: { choice: [schwimmt, sinkt] }` |
+| Energy and efficiency | forms of energy before and after; how much is useful | `figure` `bar` only for a part of a whole (useful energy of the energy put in, the efficiency); energies side by side or a transfer chain → `table` or an `image` (SVG); `generated` with the values from a data file (`from: { data: … }`, records with numbers never inline) |

package/dist/skills/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/dist/skills/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/dist/skills/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/dist/skills/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`).

package/dist/skills/lernapps-explainer/references/structure.md

@@ -17,8 +17,70 @@
 - Navigation generated: contents on start and chapter pages, breadcrumbs, previous/next across chapters, page
   contents from three sections, glossary from `definition` blocks.
 
+### When `scope` is needed
+
+- All or nothing: `scope` in `src/app.yaml` → every page needs its own `scope`, else the build stops; none in
+  `src/app.yaml` → no page has one.
+- Needed when the app has an `open-task` (the tutor judges open answers by the scope, never from general knowledge),
+  or follows the creator's material (the scope keeps the tutor to it). Else optional; the plan says which.
+- Each page's `scope`: what the page teaches, in your own words; `src/app.yaml`: `scope: { text, out: [...] }` with
+  what does not belong (`explainer-scope-matches`, form in `runtime.md`).
+
+## Format 2: strand and competencies
+
+An explainer on the learning map is in format 2. `src/app.yaml` starts with:
+
+```yaml
+# yaml-language-server: $schema=../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v2.schema.json
+format: 2
+strand: mathematik/stochastik   # "<subject>/<strand>" of the map, or none
+title: Stochastik
+```
+
+| Field | Where | Rule |
+|---|---|---|
+| `format` | `src/app.yaml` | `2`; absent means format 1 (an app that has not moved) |
+| `strand` | `src/app.yaml` | required in format 2: `<subject>/<strand>` (two ids of the map) or `none` |
+| `competencies` | every page | strand set: required, ids of the app's strand; as a rule one. `none`: not allowed |
+
+- A page: `competencies: [laplace]` beside `title` and `blocks`. One page per competency; a large one may take
+  several pages; several on one page are not recommended (`one-competency-per-page`).
+- Chapters group competencies that build on each other; pages follow the map's `requires`.
+- One app, one strand. The ids are those of `https://lernapps.net/apps/map/<subject>.json`; the build cannot know
+  them. `lernapps check` compares them with the map before the push (`competencies-on-map`); the listing checks
+  them again.
+- The build writes `lernapps-pages.json` (path, title, competencies or recap per page, in the app's order) beside
+  `index.html`; the catalog lists the pages from it.
+
+### A recap page
+
+A competency of the app may require one the app does not practise: of another strand, or of the app's strand outside
+the app's scope. The app may repeat it on a recap page, placed before the page that needs it:
+
+```yaml
+title: Brüche – kurz wiederholt
+recap: mathematik/brueche-anteile   # "<subject>/<competency>", one the app does not practise
+blocks: [...]                       # descriptive blocks only: no exercise
+```
+
+| Rule | Checked by |
+|---|---|
+| A page has either `competencies` or `recap`, never both | schema v2 |
+| A recap page has no exercise; `topic-has-exercises` does not apply to it | schema v2, build |
+| The link to the competency's page on the map is written by the runtime, so it cannot be missing | runtime |
+| The recapped competency exists, and the app does not practise it on a page of its own | `lernapps check` (`competencies-on-map`, warning), listing (error) |
+
+- A recap page counts as nothing on the map and is left out of the self-assessment.
+- A prerequisite the app does not practise (of any strand) with neither a recap page nor a link in the page's text to
+  `https://lernapps.net/apps/map/<subject>/c/<id>/`: a hint of `lernapps check` (`prerequisites-linked`).
+- Format 1 stays valid. `lernapps update` adds `format: 2` and `strand: none` to a format-1 app when its runtime
+  knows format 2.
+
 ## Entry topics
 
+- An explainer in format 2 has no hand-written topics: the catalog takes its pages from `lernapps-pages.json`. The
+  rest of this section holds for the other apps.
+
 - Path of a page or section relative to the app's `url`: `prozent/prozentwert/`, `prozent/prozentwert/#regel`
   (`entry-links-resolve`; `lernapps check --entry` checks the section).
 - From the stable ids (`explainer-stable-ids`).

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

@@ -20,7 +20,20 @@ license: MIT
 
 ## Map the content
 
-- A chapter of competencies → an app chapter. A competency → a page or a section.
+- A competency (one teachable thing, one or two lessons) → a page. A large competency may take several pages.
+- A chapter → competencies that build on each other. Order chapters and pages along the map's `requires`: what
+  learners need first comes first.
+- Prerequisites: for each page's competency, read its `requires` in the map.
+  - The app practises it (a page of its own) → it orders the pages; the text may link the page that teaches it.
+  - The app does not practise it → of another strand (one app, one strand), or of the app's strand outside the
+    app's scope. The page names it. The app may repeat it on a recap page (`recap: <subject>/<competency>`):
+    descriptive blocks only, no exercise; the runtime writes the link to its page on the map. Place the recap page
+    before the page that needs it ([structure](../lernapps-explainer/references/structure.md)). Never both: a
+    competency the app practises gets no recap page.
+- The app has one strand of the subject's learning map (recommended, skill `lernapps-content-research`), or `none`.
+  Every page names the competency of the map it practises (`competencies`, ids of the app's strand). A competency
+  the map lacks is proposed to the catalog, not invented here. With `strand: none` pages name none.
+- Show the creator this structure in Explore: which competency on which page, which pages in which chapter.
 - Depth: chapter, page, section, subsection. Need more levels → two apps.
 - The content structure → the same sections on every page, with fixed ids and titles (e.g. "Regel", "Beispiel",
   "Übung").
@@ -33,7 +46,7 @@ license: MIT
 - Text: prose (restricted Markdown), `definition` (also in the glossary), `example` and `note` boxes, `quote`,
   `code`.
 - Formulas: `formula` and inline `$…$`, LaTeX subset incl. chemistry (`\ce`), rendered as MathML.
-- Figures: drawn (`hundred-grid`, `bar`), an image (`images/<name>.svg`, with source and licence), a
+- Figures: drawn (`hundred-grid`, `bar`: both a part of a whole), an image (`images/<name>.svg`, with source and licence), a
   `labelled-figure` with numbered markers, a `table`, a `timeline`.
 - Exercises: the six question types of the quiz; `generated` (a new task per seed, with drawn values, typical
   mistakes, hint and steps); a component.
@@ -44,10 +57,41 @@ license: MIT
 
 ## Decide
 
+- Strand: `<subject>/<strand>` from the map where one fits, or `none`. The plan records it, the competency ids of
+  each page, each page's prerequisites the app does not practise and which of them get a recap page (format 2,
+  [structure](../lernapps-explainer/references/structure.md)).
 - Languages: German; English as a second language is supported. Each declared language complete. Never English
   only: without `languages` the page and the runtime's texts are German. English wanted → `[de, en]`.
 - The tutor: the build writes it from the content. Plan only app-specific tutor rules, if any.
 
+## `one-competency-per-page`: One page per competency
+
+```rule
+id: one-competency-per-page
+scope: tooling
+severity: hint
+```
+
+- Each page teaches one competency of the map: `competencies` with one id. Several pages for one large competency
+  are fine.
+- Several competencies on one page: allowed by the schema, not recommended. Split the page, one per competency.
+- `lernapps check` gives a hint for every page of a format-2 explainer with more than one competency.
+
+## `prerequisites-linked`: Prerequisites the app does not practise are recapped or linked
+
+```rule
+id: prerequisites-linked
+scope: tooling
+severity: hint
+```
+
+- A competency of a page requires one the app does not practise (`requires` in the map), of another strand or of
+  the app's own: learners find it from the app.
+- Either a recap page of the app repeats it (`recap: <subject>/<competency>`), or the page's text names it with a link
+  to its page on the map: `https://lernapps.net/apps/map/<subject>/c/<id>/`.
+- `lernapps check` gives a hint for each such prerequisite with neither, naming the page and the prerequisite. Without
+  the map it finds nothing (`competencies-on-map` says it could not check).
+
 ## Gotchas
 
 - Each component costs a module, a test and a no-JS text: plan one only where it teaches what no block can.

package/dist/skills/lernapps-explainer-design/references/rules.md

@@ -11,6 +11,7 @@ severity: error
 - Every page has at least one exercise that practises what the page explains, with solution or feedback; best in a
   last section "Übung".
 - The schema requires it; start, chapter and glossary pages are generated. The review judges the fit.
+- Except a recap page (`recap`, format 2): it repeats a prerequisite the app does not practise and has no exercise.
 
 ## `prefer-built-in-block`: A component only where no block fits
 

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

@@ -89,5 +89,6 @@ selfAssessment:
 
 - An exercise renamed or moved → change its reference in the same commit.
 - `einschaetzung` is reserved: no chapter or page may have that id.
+- A recap page (`recap`) has no exercise: it is never part of a self-assessment.
 - Never `selfAssessment` in `src/app.yaml` (build problem): the app's comes from the chapters.
 - Nothing about a real learner in any file (`no-learner-data-in-texts`).

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

@@ -19,6 +19,15 @@ At the checkpoint "list", without asking first: the pull request publishes nothi
    check it, how to open the pull request.
 2. Fill the entry from the plan's entry draft and <https://lernapps.net/apps/schemas/entry.v1.schema.json>, fetched
    now. The schema describes every field.
+   - An explainer in format 2: its pages come from `lernapps-pages.json` of the build, not from a hand-written list. The
+     listing checks the competency ids against the map and that they belong to the app's `strand`. A `strand` in
+     the entry, if given, equals the one in that file.
+   - Any other app may give `strand` (`<subject>/<strand>`) and `competencies` (ids of that subject) in the entry;
+     `competencies` needs a `strand`. An app without a strand is not on the map; that is valid.
+   - An unknown id or one of another strand is an error of the listing (`entry-learning-map`, lernapps/apps).
+     The review adds two hints, never errors: a strand that could fit an app with `strand: none`
+     (`strand-from-map`), a page that teaches more or other than its competencies say
+     (`content-matches-competencies`). `lernapps check` warns about unknown ids before (`competencies-on-map`).
 3. Run the check the guide names. Fix its findings first: the pull request runs the same check.
 4. Open the pull request from the creator's fork as skill `lernapps-github` says.
 

package/generator/create.ts

@@ -8,8 +8,9 @@
 // Renovate configuration (generator/app/); an interactive app also its architecture (generator/architecture.ts). The
 // skills `lernapps init` synced into the folder stay, and are committed with the app; `lernapps update` replaces them
 // with those of the tooling it moves the app to.
-// To move to a new app-templates: set the exact version of @lernapps/app-templates in package.json; the generator's
-// tests then run on that version.
+// To move to a new app-templates: set the exact version of @lernapps/app-templates in package.json, or a commit
+// (github:lernapps/app-templates#<commit>, which Renovate moves) until a release has what the tooling needs; the
+// generator's tests then run on that version. An app gets the same: ^ the version, or the same commit (runtimeSpec).
 import { spawnSync } from "node:child_process";
 import {
   cpSync,
@@ -49,7 +50,8 @@ node_modules init wrote). From the installed package @lernapps/app-templates, th
 on, it writes the archetype's scaffold: the files of the template folder <name>/ that the package's lernapps.scaffold
 lists (the entry, the configuration, the end-to-end tests of the content) and a placeholder as start content
 (scaffold/<name>/), which the planned content replaces. The template folder itself is the example app: it stays in
-node_modules/@lernapps/app-templates/<name>/, to look up. The app depends on the runtime of the same version.
+node_modules/@lernapps/app-templates/<name>/, to look up. The app depends on the runtime of the same version (or
+the same commit, while @lernapps/tooling depends on an unreleased one).
 
 It needs the plan of the first version, confirmed by the creator: started from the plan template as
 .vibe/plans/01-<short name>.md, the only plan there, worked through Explore and Plan, now in the phase code
@@ -74,7 +76,10 @@ publish action to the repo's GitHub Pages), an issue form for content errors, LI
 Renovate preset of lernapps). The installed skills and skills-lock.json are committed with the app, like the
 content guide; lernapps update replaces the lernapps-* skills.
 
-Then: git init (if <dir> is not a repository yet), npm install (installs the git hooks), and the first commit.
+It installs nothing and commits nothing. Its last lines say what to do next, in this order: git init
+--initial-branch=work (only if <dir> is not a repository yet; lernapps init made one), npm install (installs the
+runtime and the git hooks), git add -A and git commit (the first commit, on work; the hooks check it), then follow
+the plan.
 
 Exit codes: 0 when the app is written, 1 when it cannot be (the message says why), 2 on a usage error.
 
@@ -84,8 +89,8 @@ Options:
                       its file name <NN>-<short name>.md, else 01-plan.md (default: the one in <dir>)
   --templates <dir>   the package @lernapps/app-templates to copy from: its folder, or a clone of its repository
                       (default: the environment variable LERNAPPS_TEMPLATES, else the installed package)
-  --tooling <spec>    the npm spec of @lernapps/tooling the app depends on (default: ^ the version of this
-                      @lernapps/tooling)
+  --tooling <spec>    the npm spec of @lernapps/tooling the app depends on (default: the one lernapps init
+                      installed, else ^ the version of this @lernapps/tooling)
   -h, --help          print this help
 `;
 
@@ -98,6 +103,7 @@ export const fromPackage = (...path: string[]) => join(packageRoot, ...path);
 export interface Manifest {
   name?: string;
   version?: string;
+  dependencies?: Record<string, string>;
   devDependencies?: Record<string, string>;
   scripts?: Record<string, string>;
   lernapps?: { archetypes?: string[]; scaffold?: Record<string, string[]>; init?: boolean };
@@ -147,6 +153,19 @@ export function templatesPackage(dir?: string): Templates {
   };
 }
 
+/** The version of a package built from a commit, not released: its package.json in the repository says 0.0.0. */
+const UNRELEASED = "0.0.0";
+
+/**
+ * The spec of the runtime an app depends on, for templates of `version`: ^ that version; for templates built from a
+ * commit (version 0.0.0, which the registry does not have) the spec this tooling depends on, the same commit
+ * (github:lernapps/app-templates#<commit>), so that template and runtime match.
+ */
+export function runtimeSpec(version: string): string {
+  if (version !== UNRELEASED) return `^${version}`;
+  return readJson(fromPackage("package.json")).dependencies?.[RUNTIME] ?? `^${version}`;
+}
+
 /** The archetypes of the installed templates. */
 export const archetypes = (): string[] => templatesPackage().archetypes;
 
@@ -241,6 +260,9 @@ export function writeScaffold(templates: Templates, archetype: string, dir: stri
   cpSync(start, dir, { recursive: true });
 }
 
+/** The branch the plan works on (rule 8 of the plan template). */
+export const WORK_BRANCH = "work";
+
 /** This package, as an app depends on it. */
 export const TOOLING = "@lernapps/tooling";
 
@@ -453,7 +475,7 @@ export function create(args: string[]): number {
   // the template uses the runtime of its own checkout (file:.., installed as a copy through .npmrc); the app the
   // version of the runtime it was copied from
   if (app.devDependencies?.[RUNTIME] !== undefined) {
-    app.devDependencies = { ...app.devDependencies, [RUNTIME]: `^${templates.version}` };
+    app.devDependencies = { ...app.devDependencies, [RUNTIME]: runtimeSpec(templates.version) };
   }
   // the template keeps its checkout's runtime with an override (file:..), which npm would otherwise swap for the
   // version this tooling depends on; the app has no checkout to point at
@@ -463,8 +485,9 @@ export function create(args: string[]): number {
     if (Object.keys(kept).length > 0) app["overrides"] = kept;
     else delete app["overrides"];
   }
-  // the tooling the app depends on: the one named, else this version (init may have installed it already)
-  const tooling = values.tooling ?? `^${ownVersion()}`;
+  // the tooling the app depends on: the one named, else the one init installed (maybe a local one, --tooling of
+  // init), else this version
+  const tooling = values.tooling ?? initialised?.devDependencies?.[TOOLING] ?? `^${ownVersion()}`;
   app.devDependencies = {
     ...app.devDependencies,
     ...ARCHETYPE_DEV_DEPENDENCIES[archetype],
@@ -490,7 +513,13 @@ export function create(args: string[]): number {
       `lernapps create: the ${archetype} app ${name} in ${dir} (app-templates ${templates.version})`,
       ...guide.map((line) => `Content guide: ${line}`),
       ...(moved ? [`Plan: moved ${LEGACY_PLAN} to ${relative(dir, plan.target)}`] : []),
-      `Next: ${existsSync(join(dir, ".git")) ? "" : "git init, "}npm install, then follow ${relative(dir, plan.target)}`,
+      "Next, in this order (create installs and commits nothing):",
+      ...[
+        ...(existsSync(join(dir, ".git")) ? [] : [`git init --initial-branch=${WORK_BRANCH}`]),
+        "npm install (the runtime and the git hooks)",
+        "git add -A, then git commit (the first commit; the hooks check it)",
+        `follow ${relative(dir, plan.target)}`,
+      ].map((step, index) => `  ${index + 1}. ${step}`),
       "",
     ].join("\n"),
   );