@lernapps/tooling 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,133 @@
+---
+name: lernapps-content-questions
+description: Use in Code whenever you write or review questions with options and feedback for a lernapps.net app - the question bank of a quiz, or the quiz-type exercises of an explainer. The fields of the six question types, and how to write one clear question, options a learner could believe, feedback that explains, further reading, numbers with unit and rounding, and how to check every fact.
+license: MIT
+---
+
+# Writing questions
+
+- Read [references/question-types.md](references/question-types.md) before you write the first question of a type:
+  the fields of each type, the same in a quiz and in an explainer.
+- Write all questions of a round, then check every fact against its linked page, then commit.
+
+## Gotchas
+
+- Read every page you link before you commit: the meant article (no "Begriffsklärung"), saying what question and
+  options say.
+- Never guess an address. Never fill a fact from memory.
+- Link resolution is the check's job: no scraper, script or API loop over the links.
+
+## `quiz-bank-valid`: The question bank validates
+
+```rule
+id: quiz-bank-valid
+scope: [archetype:quiz, archetype:explainer]
+severity: error
+```
+
+- Valid against the schema. Build also checks: exactly one correct in single choice, at least one in multiple
+  choice; unique ids and options.
+- Broken bank: one line per problem (position, id); fix in `src/quiz.json`. Explainer exercise: named by file and
+  block path.
+
+
+## `quiz-clear-question`: One clear question at a time
+
+```rule
+id: quiz-clear-question
+scope: [archetype:quiz, archetype:explainer]
+severity: warning
+```
+
+- One thing per question, answerable before reading the options.
+- Positive; avoid "nicht", never two negations. No trick questions.
+- Plain, short sentences in every language (`learner-text-german`).
+
+## `quiz-plausible-options`: Options a learner could believe
+
+```rule
+id: quiz-plausible-options
+scope: [archetype:quiz, archetype:explainer]
+severity: warning
+```
+
+- Wrong options are real things of the same kind (a river for a river), with true background.
+- Options alike in length and form. No "Alle genannten", "Keine davon" or jokes. Three or four options.
+
+## `quiz-feedback-explains`: Background and explanation say why
+
+```rule
+id: quiz-feedback-explains
+scope: [archetype:quiz, archetype:explainer]
+severity: hint
+```
+
+- Every option has an `info` of 1–3 sentences about the option, true either way ("Der Nil fließt durch mehrere
+  Länder Afrikas und mündet in Ägypten ins Mittelmeer."). A wrong option's `info` also says why it does not fit.
+- `explanation`: 1–3 sentences why the answer is right; for true-false, number, ordering and matching also the
+  background.
+- `number`: typical wrong numbers as `mistakes` (`answer`, `message`). Any question: an optional `hint`, not the
+  answer.
+- A wrong answer's `message` (and an exercise component's `reason`) says what does not fit and where to look, never
+  the solution itself: the solution comes after the answer, with "Lösung" or the tutor.
+
+## `quiz-further-reading`: Every question links to further reading
+
+```rule
+id: quiz-further-reading
+scope: archetype:quiz
+severity: warning
+```
+
+- At least one link per question, best the German Wikipedia (`https://de.wikipedia.org/wiki/...`).
+- `title` names the page ("Uluru (Wikipedia)").
+- HTTP 429 → tell the creator which; mark the facts "not checked" in the plan; go on.
+
+## `quiz-own-words`: Write in your own words
+
+```rule
+id: quiz-own-words
+scope: archetype:quiz
+severity: warning
+```
+
+- Take facts, never sentences: Wikipedia is CC BY-SA (copying needs attribution and relicenses).
+- `info` and `explanation`: new, shorter, plainer, for the app's school year. Sources in `sources`
+  (`third-party-licence`).
+
+## `quiz-number-precision`: Numbers with unit and rounding
+
+```rule
+id: quiz-number-precision
+scope: [archetype:quiz, archetype:explainer]
+severity: warning
+```
+
+- The text says how exact the answer must be ("Bis zu 100 m daneben zählt noch als richtig"); `tolerance` matches
+  it.
+- The unit goes into `unit`, not into the answer.
+- Sources differ → the tolerance covers them.
+
+## `quiz-fitting-type`: The type that fits the question
+
+```rule
+id: quiz-fitting-type
+scope: [archetype:quiz, archetype:explainer]
+severity: hint
+```
+
+- One fact among things of a kind: `single-choice`; several facts: `multiple-choice`; estimate a size: `number`;
+  compare sizes or dates: `ordering`; connect: `matching`; judge a statement: `true-false`.
+- Mix the types. The type must accept every answer the text allows (`ordering` only for a fixed order).
+
+## `quiz-answers-checked`: Check every fact
+
+```rule
+id: quiz-answers-checked
+scope: archetype:quiz
+severity: hint
+```
+
+- Check every marked option, number and `info` against the linked article before you commit.
+- A source does not open → say so in the plan, mark it "not checked"; never fill it from memory.
+- Learners report errors through `.github/ISSUE_TEMPLATE/inhaltsfehler.yml`.

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

@@ -0,0 +1,69 @@
+# Question types
+
+| `type` | You write |
+|---|---|
+| `single-choice` | `options`: exactly one `"correct": true`; `info` each, `link` where useful |
+| `multiple-choice` | `options`: at least one correct; `info` each, `link` where useful |
+| `true-false` | `answer` (true or false) |
+| `number` | `answer`, `tolerance` (0 = exact), `unit` if any; the learner may type a comma or a point |
+| `ordering` | `items` in the right order; the page mixes them |
+| `matching` | `pairs` as they belong; the page mixes the right side. `distractors` (1 to 4): wrong right entries that match no left one. `pairsFrom: material` instead of `pairs` takes them from the `labelled-figure` in `material` (marker left, text right; the figure needs `legend: false`) |
+
+- Every question: `id`, `text`, `explanation`, at least one link in `links`. 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`
+  (or `.png`, `.jpg`, `.webp`; the file is in `src/images/`) or drawn from numbers (`draw`), with `alt` (what it
+  shows), `caption` (what to look at) and, for an image, `source` and `licence` (`third-party-licence`). Use it where
+  the question needs the content (what does the image show, what does the table say); not as decoration. The build
+  fails for a missing file, a text missing in a language, raw HTML or a link to a page of the app.
+- Optional `examples: { accepted, rejected }`: options and items by index from 0 or German text; numbers as number or
+  as typed (`"12,5"`; point = decimal mark: `8900`, never `8.900`). Build checks them; learners never see them.
+  Mistakes and wrong options' `info` already count as rejected.
+
+```json
+{
+  "id": "ring",
+  "type": "single-choice",
+  "text": "Welche Form zeigt das Bild?",
+  "material": [
+    {
+      "type": "figure",
+      "image": "images/kreis.svg",
+      "alt": "Ein blauer Kreis mit einem weißen Kreis in der Mitte",
+      "caption": "Zwei Kreise mit demselben Mittelpunkt.",
+      "source": "eigene Zeichnung",
+      "licence": "CC0-1.0"
+    }
+  ],
+  "options": [
+    { "text": "Ein Ring", "correct": true, "info": "Ein Ring liegt zwischen zwei Kreisen mit demselben Mittelpunkt." },
+    { "text": "Eine Ellipse", "correct": false, "info": "Eine Ellipse hat zwei Brennpunkte." }
+  ],
+  "explanation": "Die weiße Fläche in der Mitte macht aus der Kreisscheibe einen Ring.",
+  "links": [{ "title": "Kreisring (Wikipedia)", "url": "https://de.wikipedia.org/wiki/Kreisring" }]
+}
+```
+
+```json
+{
+  "id": "grand-canyon",
+  "type": "single-choice",
+  "text": "Welcher Fluss hat den Grand Canyon in den USA geformt?",
+  "options": [
+    {
+      "text": "Colorado",
+      "correct": true,
+      "info": "Der Colorado ist der größte Fluss im Südwesten Nordamerikas. Er ist gut 2300 km lang.",
+      "link": { "title": "Colorado River (Wikipedia)", "url": "https://de.wikipedia.org/wiki/Colorado_River" }
+    },
+    {
+      "text": "Nil",
+      "correct": false,
+      "info": "Der Nil fließt durch mehrere Länder Afrikas und mündet in Ägypten ins Mittelmeer. Mit rund 6650 km gilt er als längster Fluss der Erde."
+    }
+  ],
+  "explanation": "Der Grand Canyon ist eine steile Schlucht in Arizona, etwa 450 km lang. Der Colorado hat sie über Millionen von Jahren in das Gestein gegraben.",
+  "links": [{ "title": "Grand Canyon (Wikipedia)", "url": "https://de.wikipedia.org/wiki/Grand_Canyon" }]
+}
+```

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

@@ -0,0 +1,50 @@
+---
+name: lernapps-content-research
+description: Use in Explore whenever you need to know what a lernapps.net app teaches - school year, Lehrplan, competencies, sources - even if the creator only names a topic; in the first version and in each increment that adds a chapter. How to use the Lehrplan as orientation, write competencies as "Ich kann …", verify sources by opening them, and keep the creator's material private. For every archetype.
+license: MIT
+---
+
+# Content research
+
+- A filled-in content guide `.agents/skills/app-content/SKILL.md` comes first: its decisions stand; research only
+  the gaps.
+- Content comes from the curriculum, the creator and sources you opened, never from memory.
+- The questions to the creator are the plan's interview. Read every file the creator gives you.
+
+## 1. Lehrplan
+
+- Orientation for grade and order, not a condition. None found → say so once; go on.
+- Only the Land's official document (Kerncurriculum, Lehrplan, Bildungsplan, Rahmenlehrplan) from the ministry or
+  state institute. No publisher, schoolbook or portal. No Land known → KMK-Bildungsstandards.
+- Download and read it yourself.
+- 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
+
+- 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.
+- Write them under "Notes". Show them at the checkpoint "research".
+
+## 3. 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.
+
+## 4. 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.
+- No learner's name, class, school, grades, picture, or one learner's goal such as a test date
+  (`no-learner-data-in-texts`). School year, school type and Lehrplan may stay.
+
+## Gotchas
+
+- Read the primary source before you write a fact. A secondary text that seems to fit is no proof.
+- Several sources disagree → report the disagreement to the creator. Never bend a fact to fit the plan.
+- Never guess a Lehrplan unit, a wording or an id (video, article, unit number): look it up or leave it out, and
+  mark it unchecked.
+- HTTP 429 or a site down → tell the creator which; mark it "not checked"; go on. No scraper, no loop.

package/dist/skills/lernapps-content-research/references/sources.md

@@ -0,0 +1,16 @@
+# Verifying a second source
+
+## Check by opening
+
+1. It loads: no error, no empty page, no redirect to a start or search page.
+2. It is the article or video itself: no search result, category, list or disambiguation.
+3. It covers exactly this competency: resistance for "Ich kann den Widerstand berechnen", not electricity in
+   general.
+
+## Rules
+
+- No weak matches. Nothing fits → leave it out and say so under "Notes".
+- Video: check channel and title through the platform's metadata (YouTube: oEmbed), never through a search result.
+- A video loads only after a click (`no-request-before-click`).
+- Note per source: address, exact title, "verified".
+- Take facts, never sentences. Name source and licence of what you take (`third-party-licence`).

package/dist/skills/lernapps-exercise-patterns/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: lernapps-exercise-patterns
+description: Use in Explore, after the goal and the learners are known and before you choose the archetype - how learners of a lernapps.net app practise each kind of competency, which points to the archetype - and again in Plan to choose a pattern per competency, share material as data and say what a wrong answer is told. In an increment, for a kind of exercise the app's content guide lacks. For every archetype.
+license: MIT
+---
+
+# Exercise patterns
+
+- Learners act on every page or screen (`learners-act`).
+- Learners derive, not only read off: show how a value comes about (tree diagram, step, model), then let them do it.
+- The content guide `.agents/skills/app-content/SKILL.md` names the app's patterns. It takes precedence.
+- Three levels. Take the next level only when the one before cannot express the competency.
+
+## The kind of practice and the archetype
+
+- In Explore, read the patterns of the subject before the archetype is chosen. How learners practise points to the
+  archetype; the README of each template decides:
+  - every competency fits a question with options or an input and feedback per answer, no page needs to explain
+    first → `quiz`;
+  - learners need explanations, figures or derivations on pages before they practise, with exercises in between →
+    `explainer`;
+  - learners act in a model of their own: a game, a simulation, a timed drill, something they move or build →
+    `interactive`.
+- Mixed: the kind most competencies need decides; tell the creator what the others become.
+
+## 1. Data files
+
+- Each fact once, as a record with the same fields as its neighbours (elements, circuit parts, events, organs).
+- The skill `lernapps-<archetype>-design` says where data lives in the archetype.
+
+## 2. Patterns
+
+- A pattern is a kind of exercise for one kind of competency, written down once and varied per use (values,
+  records, context).
+- Choose by the competency's verb:
+
+| The learner can … | Pattern |
+|---|---|
+| compute, convert, estimate | a computed task with unit; typical mistakes diagnosed; numbers drawn where possible |
+| assign, name, recognise | match pairs, or pick one of things of the same kind |
+| order, compare | put items in order by size, date or step |
+| judge, decide | true or false with the reason in the feedback, or pick the right statement |
+| read off, interpret | a figure or table given, a value or statement asked |
+| explain | pick the right explanation among plausible wrong ones, each with background |
+
+- Read the patterns of your subject before you choose: [mathematics](references/mathematics.md),
+  [physics](references/physics.md), [chemistry](references/chemistry.md),
+  [biology and geography](references/biology-geography.md), [history](references/history.md),
+  [computer science](references/computer-science.md). Another subject: the one closest to it.
+- Explainer: read [references/page-structures.md](references/page-structures.md) when you plan the sections of a
+  page; any archetype with figures: [references/figures.md](references/figures.md).
+- Write each pattern into "Content method": name, kind of competency, form in the archetype (what is fixed, what
+  varies), one example, data file. In Code it goes into the content guide.
+
+## 3. Beyond the notation
+
+- What the archetype's notation cannot express: the skill `lernapps-<archetype>-design` says the way out (a component
+  of the explainer; code of an interactive app). Say in the plan why no pattern fits.
+- A need other apps share (figure kind, block, question type) → an issue at
+  <https://github.com/lernapps/app-templates/issues> with an example. Tell the creator; use the nearest pattern.
+- Never code beyond the archetype; note the gap under "Where I had to guess".
+
+## Checking answers
+
+- Read [references/success.md](references/success.md) when you decide how an exercise checks an answer and what each
+  wrong answer is told.
+
+## Every pattern
+
+- Works without seeing the figure: the figure explains, the check checks.
+- The figure shows what is given, never the answer.
+- Numbers fit the story; units are named; rounding is said.
+- Wrong options and mistakes are real ones, each with a reason.
+- Every figure works at 360 px and has a text alternative (`usable-at-360px`, `accessible`).

package/dist/skills/lernapps-exercise-patterns/references/biology-geography.md

@@ -0,0 +1,13 @@
+# Patterns: Biology and geography
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Parts and functions | an organ, a cell or a landscape with numbered parts | `labelled-figure`; `table` of parts and functions from a data file; `matching` part ↔ function |
+| Classification | living things or places by a feature | `multiple-choice` "which of these are …" |

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

@@ -0,0 +1,16 @@
+# Patterns: Chemistry
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Particle model | the states of matter as dots with their spacing | three `image`s with captions; `matching` state ↔ description; a component with a temperature slider |
+| Atom model | shells with electrons for the elements 1 to 20, valence electrons marked | a data file of elements (protons, shells, valence electrons); `generated` `pick: 1` with a number answer |
+| Reaction equations | atom counts left and right; balance by coefficients | `formula` with `\ce{…}`; `number` or `generated` asking one coefficient from a data file of reactions; a component that shows the counts |
+| Stoichiometry | mol, g and particles as three boxes with the molar mass between them | `formula` with `\pu{…}`; `generated` from a data file of substances, the mistake "multiplied instead of divided by M" |
+| pH scale | a coloured scale; where substances lie | `image` of the scale; `ordering` of substances by pH from a data file |

package/dist/skills/lernapps-exercise-patterns/references/computer-science.md

@@ -0,0 +1,13 @@
+# Patterns: Computer science
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Reading code | a short program; what it prints | `code`; `single-choice` or `number` on its output |
+| Number systems | a number in binary; convert it | `generated` with `int` drawn and the answer computed; the mistake "read from the wrong end" |

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

@@ -0,0 +1,10 @@
+# Figures
+
+- Shows what the text next to it says; caption: what to look at; `alt`: what it shows (`explainer-figure-explains`).
+- Drawn from the given, never the answer (`explainer-figure-hides-answer`).
+- Bundled; nothing from other servers before a click (`no-request-before-click`); others' images with source and
+  licence (`third-party-licence`).
+- Works at 360 px: trees top to bottom; too wide → table, or split by stage.
+- Same conventions (colours, labels, units, orientation) across the app; write them into the guide, "Figures".
+- The same figures work in a quiz question (`material`, skill `lernapps-content-questions`): an image of `src/images/` with
+  `alt`, `caption`, `source` and `licence`.

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

@@ -0,0 +1,13 @@
+# Patterns: History
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Source and context | a quotation with its origin; what it says about its time | `quote` with `origin`, `source` and `licence`; `single-choice` on its meaning |
+| Chronology | events on a timeline; put them in order | `timeline` from a data file of events; `generated` with `pick: 3, distinct: true` and `compare: order` |

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

@@ -0,0 +1,19 @@
+# Patterns: Mathematics
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| 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" |
+| 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" |

package/dist/skills/lernapps-exercise-patterns/references/page-structures.md

@@ -0,0 +1,8 @@
+# Page structures (explainer)
+
+- Recommended; keep alike across the app's pages.
+- Maths, sciences: Warum, Regel (formula, figure), Beispiel (`example` box), Übung.
+- History: Quelle (`quote`), Einordnung, Zeitleiste (`timeline` from data), Übung (ordering or `generated`).
+- Biology, geography: Überblick, Aufbau (`labelled-figure`), Funktion (`table`), Übung (matching).
+- Computer science: Idee, Beispiel, Code (`code`), Übung (output of the code).
+- Quiz: one round per chapter, questions in the patterns above a question type can express.

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

@@ -0,0 +1,18 @@
+# Patterns: Physics
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Circuit symbols | the symbol of a part and its name and function | `table` from a data file of parts; `matching` symbol ↔ part; `generated` `pick` from the data file |
+| Series and parallel circuit | two circuits with the same parts; where is the current larger | `labelled-figure` of both schematics; `single-choice` with the reason in each option's `info`; `ordering` of currents |
+| Ohm's law and quantities | U, R and I of a circuit; compute the missing one with its unit | `formula` `U = R \cdot I`; `generated` with `\pu{…}` units, `where` for realistic values, mistakes "U · I instead of U / I", "mA not converted" |
+| Linear motion | s-t and v-t graphs side by side; read off or compute speed | `image` of the graphs with a `table` of values; `generated` for s = v · t; a component with a slider for v |
+| 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] }` |

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

@@ -0,0 +1,28 @@
+# How an exercise checks success
+
+## Property, not model solution
+
+- Check what the text asks: "a fraction equal to 1/2" accepts 2/4 and 3/6; "a conductor" accepts every conductor.
+- "Order the steps" only where the order is fixed.
+- A type that cannot accept every correct answer (ordering with a free order, single choice with two defensible
+  options) → another type or another text.
+
+## Write down first, in the content method
+
+1. The answers that fulfil the text, including correct ones other than yours.
+2. The typical wrong answers.
+3. The feedback for each.
+
+## Feedback on a wrong answer
+
+- Every wrong option says why it does not fit.
+- Computed tasks: 2–3 common mistakes, each with its message.
+- Optionally a hint: where to look, not the answer.
+- A component of your own: right or wrong, plus a short reason.
+
+## Examples as tests
+
+- Each exercise lists other correct answers the text allows as accepted, and typical wrong ones as rejected. The
+  build runs them through the real check; learners never see them.
+- An accepted example fails → the exercise checks the wrong thing: change the type or the check, not the example.
+- The archetype's skill says the notation (`examples`, `mistakes`, component tests).

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

@@ -0,0 +1,33 @@
+---
+name: lernapps-explainer
+description: Use in Code of a lernapps.net explainer whenever you write or change its content in src/ - a chapter, page, block, figure, formula, exercise, data file, language or component - or a build or runtime test of the explainer fails. What you write, the notation of structure, blocks and exercises, components, the runtime, and the explainer's technical rules.
+license: MIT
+---
+
+# Explainer
+
+- 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 the example chapter "Prozent": replace it with the planned content.
+- 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`).
+- Questions of the quiz's types: also skill `lernapps-content-questions`.
+
+## Read when
+
+- [references/structure.md](references/structure.md): before you add or move a chapter or page.
+- [references/blocks.md](references/blocks.md): before you write a page.
+- [references/exercises.md](references/exercises.md): before you write an exercise, above all a `generated` one.
+- [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.
+
+## Gotchas
+
+- A build problem is one line `file:line: place (language): what to do`. Fix where it points.
+- Headings are `section` blocks, never Markdown headings.
+- 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

@@ -0,0 +1,83 @@
+# Blocks
+
+- A page = list of blocks from a closed set. Every text field: text or language map.
+- Prose: restricted Markdown: paragraphs, `**bold**`, `*italics*`, lists, links, line breaks, `$…$`.
+- No headings (use `section`), HTML, images, code, quotes, tables in Markdown: each has its block.
+- App-internal links start with `/` (`/prozent/grundwert/#regel`); the build checks them.
+
+| `type` | Fields | Shows |
+|---|---|---|
+| `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 |
+| `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 |
+| `definition` | `term`, `explanation` | term in place, in the glossary |
+| `quote` | `text`, `origin` (`author`, `work`, `year`), `source`, `licence` | quotation with origin |
+| `code` | `language` (bash, c, css, html, java, javascript, json, plaintext, python, sql, typescript), `code`, `caption` | highlighted code |
+| `example`, `note` | `title`, `blocks` | box: worked example, hint |
+| `video` | `youtube` (the 11-character id, not the address), `title`, `channel` (both as on YouTube, plain strings) | YouTube video behind two clicks: link, channel, privacy note; player only after a click |
+| exercises | quiz's six types, `generated` | `exercises.md` |
+| `vue-component` | `component`, `props`, `nojs` | `components.md` |
+
+```yaml
+- type: section
+  id: regel
+  title: Regel
+  blocks:
+    - type: formula
+      formula: 'W = \frac{G \cdot p}{100}'
+    - type: definition
+      term: Prozentwert
+      explanation: Der Prozentwert $W$ ist der Anteil am Ganzen, in der Einheit des Grundwerts.
+    - type: figure
+      draw: { kind: hundred-grid, filled: 12 }
+      alt: Ein Hunderterfeld mit 100 Kästchen, 12 davon sind gefärbt.
+      caption: Die 12 gefärbten Kästchen sind 12 % des Ganzen.
+```
+
+- Images in `src/images/`: found under a free licence (e.g. Wikimedia Commons) or your own, generated or drawn as
+  SVG. Always `source` (URL or citation, e.g. `eigene Zeichnung`, `KI-generiert`) and `licence` (SPDX id, e.g.
+  `CC-BY-SA-4.0`, or `gemeinfrei`). Several languages: a citation is a language map; a URL one string.
+
+## Videos
+
+- YouTube only, explainer only (not in a quiz question's `material`). No thumbnail, no video files in the bundle.
+- `title`, `channel`: as YouTube names them, in the video's language; the page's language does not change them.
+- What the learner should notice in the video: a `text` block before it; the block has no note field.
+- An app with a video loads from another server after a click: its catalog entry says `fitness.thirdParty: on-click`,
+  and with the choice "Videos immer direkt laden" also `fitness.storage: device`.
+
+```yaml
+- type: video
+  youtube: rkLmLaFHodo
+  title: einstufiger Zufallsversuch | Wahrscheinlichkeitsrechnung - einfach erklärt
+  channel: Lehrerschmidt
+```
+
+## Formulas
+
+- LaTeX subset → MathML; `formula` block or inline `$…$`.
+- Commands: `\frac`, `\cdot`, `\times`, `\div`, `\%`, `\text`, `^`, `_`, `\sqrt`, `\approx`, `\pm`, `\le`, `\ge`,
+  `\neq`, `\,`, parentheses, braces (`\{`, `\}`).
+- 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).
+
+## Languages
+
+- `languages` in `src/app.yaml`, German first: `[de]` or `[de, en]` (runtime texts: de, en).
+- A string = German, enough only while German is the only language. Else every text a map:
+  `title: { de: Die drei Stände, en: The three estates }`.
+- Build fails on a missing translation (`the translation is missing; write the text as a map: { de: …, en: … }`)
+  and an undeclared language.
+- Same in every language: ids, addresses, numbers, formulas, drawn figures.
+- Trees: German at root, others under `/<language>/`; `lang`, `hreflang`, plain-link switch.
+
+## Data files
+
+- `src/data/<name>.yaml`: list of records, same lowercase fields; values number, boolean, text (map if several
+  languages).
+- Used by `timeline` (`data: ereignisse`) and `generated` (`from: { data: elemente }`). Each fact once, there.