@lernapps/tooling 0.4.0 → 0.5.0

package/skills/archetypes/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/skills/archetypes/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/skills/archetypes/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/skills/archetypes/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/skills/content/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/skills/content/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/skills/content/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/skills/content/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/skills/content/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/skills/process/lernapps-app/SKILL.md

@@ -39,7 +39,8 @@ The READMEs are files of the package `@lernapps/app-templates`, which `init` ins
 
 - Choose after the interview topics "Goal" and "Learners", from what learners do. Read the patterns of the subject
   first (skill `lernapps-exercise-patterns`): how learners practise points to the archetype.
-- Before you choose, read the README of each archetype in question, in full. Tell the creator in plain words what the
+- Before you choose, read the README of every archetype you consider, in full. One you rule out from the kind of
+  practice alone needs no README: say in one sentence why it does not fit. Tell the creator in plain words what the
   chosen one can and cannot do, before you ask about content, amount and look.
 - A few background sections on the start page keep an app `interactive`.
 - Explanation pages with one interactive exercise → `explainer` with a component.

package/skills/process/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/skills/tooling/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.