@lernapps/tooling 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,285 @@
+# Explainer rules
+
+- Quiz-type exercises: the rules of skill `lernapps-content-questions`.
+- The rules for planning pages, figures and numbers: skill `lernapps-explainer-design`.
+
+## `explainer-only-content`: Write only the content
+
+```rule
+id: explainer-only-content
+scope: archetype:explainer
+severity: error
+```
+
+- Write: YAML of app, chapters, pages, data; images in `src/images/`; components with logic and tests in
+  `src/components/`.
+- `src/main.ts`, `index.html`, `e2e/explainer.e2e.ts`, config as generated (`keep-the-preset`). Any other file in
+  `src/` fails the build.
+- Not expressible → "Where I had to guess", never code around the runtime.
+
+## `explainer-content-valid`: The content validates
+
+```rule
+id: explainer-content-valid
+scope: archetype:explainer
+severity: error
+```
+
+- Schema-valid; ids unique per level; references exist (data file, image, component, page or section link);
+  placeholders declared; formulas only from the command list.
+- Build names each problem with file, line, block path.
+
+## `explainer-structure-complete`: Every chapter and page listed once
+
+```rule
+id: explainer-structure-complete
+scope: archetype:explainer
+severity: error
+```
+
+- At least one chapter.
+- Every chapter folder in `chapters` of `src/app.yaml`, every page file in `pages` of its `chapter.yaml`, exactly
+  once, in reading order.
+
+## `explainer-structure-depth`: Chapter, page, two section levels
+
+```rule
+id: explainer-structure-depth
+scope: archetype:explainer
+severity: error
+```
+
+- Sections at most two deep. No heading levels set: they follow from nesting. More levels = two apps.
+
+## `explainer-structure-by-sections`: Structure only by sections
+
+```rule
+id: explainer-structure-by-sections
+scope: archetype:explainer
+severity: error
+```
+
+- Every heading = a `section` block with `id`, `title`.
+- A Markdown heading (`#`, `##`, underlined) in a text fails the build.
+
+## `explainer-stable-ids`: Keep the ids
+
+```rule
+id: explainer-stable-ids
+scope: archetype:explainer
+severity: warning
+```
+
+- Short, telling ids ("prozentwert", "regel") for chapters, pages, sections, exercises; keep them when texts
+  change (entry topics, teachers' links).
+- New content, new ids; never reuse a removed one.
+
+## `explainer-navigation`: Every page in one chain
+
+```rule
+id: explainer-navigation
+scope: archetype:explainer
+severity: error
+```
+
+- Navigation is the runtime's: from the order lists; every page in one chain, reachable from the start page.
+- Prose links: paths from the app root.
+- `lernapps check` finds unreachable pages (`pages-reachable`) and entry topics with a missing `#<section>`
+  (`entry-links-resolve`).
+
+## `explainer-languages`: German first, every language complete
+
+```rule
+id: explainer-languages
+scope: archetype:explainer
+severity: error
+```
+
+- `languages`, German first.
+- Every learner text (content, data files, component props) in each, no other. Build fails otherwise.
+
+## `explainer-readable-without-js`: Every page readable without JavaScript
+
+```rule
+id: explainer-readable-without-js
+scope: archetype:explainer
+severity: error
+```
+
+- Every fact in a block, visible without JS. No meaning only inside an exercise or component.
+- Every component a `nojs` text: what it shows, its content.
+- `lernapps check` opens every explainer page again with JS off, bundle and deployed (listing and review too):
+  headings, formulas, figures visible, figures named; every "Lösung" and `nojs` text not empty.
+
+## `explainer-formulas-static`: Formulas as formulas
+
+```rule
+id: explainer-formulas-static
+scope: archetype:explainer
+severity: error
+```
+
+- Every formula in a `formula` block or `$…$`; never plain text (`W = G * p / 100`) or a picture. MathML for
+  screen readers.
+
+## `explainer-generated-sound`: The property test passes
+
+```rule
+id: explainer-generated-sound
+scope: archetype:explainer
+severity: error
+```
+
+- `given`, `where`: `where` holds often; answer defined and in format for every draw; no mistake can equal it.
+- Failure names the seed: narrow `given` or change the mistake; never the comparator.
+
+## `vue-component-props-valid`: Props as the component declares them
+
+```rule
+id: vue-component-props-valid
+scope: archetype:explainer
+severity: error
+```
+
+- `defineProps<{ … }>()` with types; each block passes exactly the declared props, of their types.
+
+## `vue-component-nojs`: Every component block has its `nojs` text
+
+```rule
+id: vue-component-nojs
+scope: archetype:explainer
+severity: error
+```
+
+- Every non-exercise `vue-component` block: `nojs` in every language (exercise: from `describe`): what it shows
+  and does, with content; same meaning without JS.
+- Schema requires it; `lernapps check` finds empty or hidden ones (`explainer-readable-without-js`).
+
+## `vue-component-exercise-contract`: An exercise component has its logic module
+
+```rule
+id: vue-component-exercise-contract
+scope: archetype:explainer
+severity: error
+```
+
+- Emits `answer` → `src/components/<Name>.ts` with pure, deterministic `generate(seed, props)`,
+  `check(task, answer)`, `solution(task)`, `wrong(task)`, `reason(task, answer, props, lang)`; property test passes.
+- Emits no `answered` (the old contract): the explainer draws "Prüfen" and checks; a component draws none.
+- Block lists `examples` with at least one `accepted` and one `rejected`, `{ answer, seed? }` in the shape of
+  `check` (no seed: seeds 1–50), incl. another correct answer where the text allows.
+- Declares prop `seed: number`, shows `generate(seed, props)`. The explainer gives the seed, shows "Aufgabe Nr.",
+  "Neue Aufgabe", keeps `?<id>=<n>`: never draw a seed or offer "next" inside.
+- Also exports `describe(task, props, lang)` → `{ task, solution }` (restricted Markdown, task exactly as shown) and
+  `about = { task, answer, correct, mistakes }` (texts by language). The tutor reads only these (the tutor page, no-JS
+  text).
+- Any exercise may carry `examples: { accepted, rejected }`; `generated`: expressions of `given` and `answer`, per
+  seed (e.g. `reverse(answer)`).
+- With `template`, `params`, `mistakes` and `show` (all four or none, rule `vue-component-tutor-table`): `check`
+  accepts the solution and rejects each mistake's answer, `params` gives the same names for every task, each
+  placeholder of `template` is one of them.
+
+## `vue-component-tutor-table`: An exercise component declares its exercise for the tutor
+
+```rule
+id: vue-component-tutor-table
+scope: archetype:explainer
+severity: hint
+```
+
+- The logic module also exports `template(props, lang)`: the task once, `{name}` for each input;
+  `params(task, props, lang)`: the inputs by name (`{ G: 1260, p: 15 }`), numbers or texts, the same names for every
+  task; `mistakes(task, props)`: per `about.mistakes`, in order, the answer it gives, `undefined` where none;
+  `show(answer, task, props, lang)`: an answer as text, short ("C", "3 Kästchen").
+- The tutor page then has the task once, the mistakes as F1, F2 … and a table of every number (inputs, solution,
+  each mistake), like `generated`. Without them: each number's `describe` as far as 64 kB allow, and the build's hint
+  names the block.
+- Example: `src/components/ProzentFeld.ts` of the template.
+
+## `vue-component-tested`: A test per component
+
+```rule
+id: vue-component-tested
+scope: archetype:explainer
+severity: error
+```
+
+- `src/components/<Name>.test.ts` per component, testing its logic: other right answers the text allows, typical
+  wrong ones with reasons, edge cases. Run by `lernapps check`.
+
+## `vue-component-no-network`: No network
+
+```rule
+id: vue-component-no-network
+scope: [archetype:explainer, archetype:interactive]
+severity: error
+```
+
+- No request, no URL import: props or bundle.
+
+## `vue-component-no-html-injection`: No code or HTML from strings
+
+```rule
+id: vue-component-no-html-injection
+scope: [archetype:explainer, archetype:interactive]
+severity: error
+```
+
+- No `eval`, `new Function`, `innerHTML`, `v-html`: the template renders.
+
+## `vue-component-imports`: Imports only from the allowed packages
+
+```rule
+id: vue-component-imports
+scope: [archetype:explainer, archetype:interactive]
+severity: error
+```
+
+- Only `vue`, `@lernapps/app-templates`, `@lernapps/tooling/storage`, `i18n`, `a11y`, own folder. Types from
+  anywhere.
+- Interactive: also the app's `src/` files and its `dependencies`.
+
+## `vue-component-browser-globals`: Browser globals only once mounted
+
+```rule
+id: vue-component-browser-globals
+scope: [archetype:explainer, archetype:interactive]
+severity: error
+```
+
+- `window`, `document`, `localStorage` etc. only in `onMounted` or later unmount hooks (server render has none).
+
+## `vue-component-size`: Within 20 kB
+
+```rule
+id: vue-component-size
+scope: archetype:explainer
+severity: error
+```
+
+- Own code max 20 kB gzip. More → split, or a new block: write it into the retrospective.
+
+## `explainer-open-points`: An open task checks what the material teaches
+
+```rule
+id: explainer-open-points
+scope: archetype:explainer
+severity: warning
+```
+
+- 2 to 5 points, each one sentence a learner can check with yes or no; together what a good answer needs.
+- A point of the content names its section (`source`), and its content is there; a point of form has `kind: form`.
+- The model answer has every point, in the words of the class.
+
+## `explainer-scope-matches`: The scope says what the pages teach
+
+```rule
+id: explainer-scope-matches
+scope: archetype:explainer
+severity: warning
+```
+
+- `scope` of each page in your own words, never copied from the material; `scope` in `src/app.yaml` with what does not
+  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.

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

@@ -0,0 +1,79 @@
+# Explainer runtime
+
+## Build
+
+- Reads, validates, renders every page to static HTML.
+- Problem → one line `file:line: place (language): what to do`, e.g.
+  `src/prozent/prozentwert.yaml:12: blocks[0].blocks[1].text: a Markdown heading ("Regel"); use a section block with the title "Regel"`.
+  Fix where it points.
+
+## Pages
+
+- No JS: complete; text, formulas as MathML, figures, tables, navigation, sources. Exercise: task + `<details>`
+  "Lösung"; `generated`: three worked tasks; component: its `nojs` text; `open-task`: task, points with "Nachlesen",
+  model answer under "Lösung".
+- JS: controls, "Prüfen", feedback with focus. Solution only after an answer; wrong → why, retry or "Lösung". An
+  exercise component gets "Prüfen" from the explainer too, under it.
+  `generated`: live task, "Neue Aufgabe", deep link `/<chapter>/<page>/?<exercise>=<n>#<exercise>`. Components
+  hydrate. `open-task`: "Deine Lösung" (type, or paper and photo), "Vergleichen" shows the points as tick boxes and
+  opens the model answer, "Antwort ändern".
+- Video: no JS and before a click, title as a link to youtube.com, channel and a note that playing sends data to
+  YouTube/Google; nothing loads from another server. "Video abspielen" loads the player from youtube-nocookie.com.
+- Stores on the device, per app, only the assistant the learner switched on for the tutor, once ticked, "Videos
+  immer direkt laden" (every player loads without the click until unticked), and the last result of each
+  self-assessment the learner did. While the tab is open (sessionStorage), the answer of each open task: way, text and
+  ticks, so that a reload loses nothing; never the photo.
+- Self-assessment (`selfAssessment` per chapter, JS only): a chapter's on its page, the app's (every chapter's) on
+  the start page; its exercises without "Prüfen", checked together at "Auswerten"; the result per content page. With
+  `via=tutor` it keeps nothing and ends in "Zurück zum Tutor". Skill `lernapps-explainer-self-assessment`.
+
+## Addresses
+
+- Page `/<chapter>/<page>/`; section `#<section>`, subsection `#<section>/<sub>`; exercise `#<exercise>`.
+- Glossary `/glossar/`. Other languages: same tree under `/<language>/`.
+- Tutor page of a page: `/<chapter>/<page>/tutor/`, its Markdown beside it (`index.md`).
+- Scope (from `scope` in the content): `/<chapter>/<page>/scope/` (the page's), `/<chapter>/scope/` (the chapter's),
+  `/scope/` (the whole); for the tutor only, linked from the tutor page. `scope` is no chapter id.
+- Self-assessment: `/einschaetzung/` (the app's), `/<chapter>/einschaetzung/` (a chapter's), each with its tutor page
+  `tutor/`. `einschaetzung` is no chapter or page id.
+- Unknown address → 404 page to the start page. Moving or removing a page: change the entry topics in the same
+  increment.
+
+## Tests
+
+- From the runtime (`e2e/explainer.e2e.ts`, `explainerTests()`), every page, every language, run by
+  `lernapps check`.
+- No JS: headings vs nesting, sections, formulas, figures, anchors, navigation chain, languages, every solution,
+  every `nojs` text.
+- JS (German, 360 px): one exercise per type and page accepts its answer, rejects a wrong one; components hydrate
+  without error; a video sends no request to another server before its click, and loads its player after it; each
+  self-assessment: a run with every answer right, one without an answer (kept, to the tutor, deleted), and one a tutor
+  opened.
+- `lernapps check` also opens every page without JS (`explainer-readable-without-js`), bundle and deployed app.
+
+## A runtime test fails
+
+- Content validates (build passes) but a test fails = template bug: act as skill `lernapps-cli` says; go on with
+  content.
+- Never change the runtime in `node_modules` (`explainer-only-content`). The fix arrives with `lernapps update`.
+
+## Tutor
+
+- Optional: the learner's own KI assistant helps with a page and with each exercise. The build writes a tutor page
+  per page from the content; the app sends nothing.
+- The tutor reads the page's blocks as text (figures by `alt` and `caption`, a video as a link with title and channel)
+  and every exercise: task, answer format, solution, `hint` and typical mistakes with their messages. `generated`: template, `steps`, `mistakes` and each task
+  number's values; question: options with `info`, `explanation`; component: `about`, and with `template`, `params`, `mistakes`, `show`
+  the same table as `generated` (else `describe` per task number, as far as 64 kB allow).
+  `open-task`: task, points as P1, P2 … with their sources, model answer. It neither calculates nor invents: these
+  must be complete and right.
+- The scope: the whole learning path in your own words, from the material, as continuous prose with the exact
+  content (facts, terms, reasons, examples), beside what it describes. `scope` in each page's YAML: what the page
+  teaches; optionally `scope` in `chapter.yaml`; and in `src/app.yaml`
+  `scope: { text, out: [...] }`: what the app is about and where its weight lies, and what does not belong to it (what
+  belongs to it is what the pages say). With
+  the app's scope the build requires a scope on every page. The tutor judges open answers by it, never from general
+  knowledge.
+- `src/app.yaml`: `tutor.rules`, the app's rules for the tutor; never send it to another address.
+- Task numbers 1 to N (max 67) are what learner, tutor and address (`?<id>=<n>`) share; changing a generator changes
+  what a number points to. `seed`, `via`, `uebung`, `abschnitt` are no exercise ids.

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

@@ -0,0 +1,24 @@
+# Structure
+
+| Level | File | Holds |
+|---|---|---|
+| App | `src/app.yaml` | `title`, `intro`, `languages`, order of `chapters`, `sources` |
+| Chapter | `src/<chapter>/chapter.yaml` | `title`, `summary`, order of its `pages` |
+| Page | `src/<chapter>/<page>.yaml` | `title`, `description`, `blocks` |
+| Section | `section` block in a page | `id`, `title`, `blocks`; one more section level inside |
+| Scope | `scope` in app, chapter and page (optional) | the whole learning path for the tutor, beside each page (`runtime.md`) |
+
+- Chapters mandatory. One chapter: hidden in navigation; addresses keep it (`/<chapter>/<page>/`).
+- Order lists complete: `chapters`, `pages` list every folder or file exactly once. No sorting by name.
+- Ids: lowercase, digits, hyphens; unique per level; stable once published. Not chapter ids: `data`, `images`,
+  `glossar`, `components`, `assets`, `scope`.
+- Depth: page, section, subsection; headings follow from nesting (h1–h3). Boxes (`example`, `note`) take the next
+  level, hold no sections. More levels = two apps.
+- Navigation generated: contents on start and chapter pages, breadcrumbs, previous/next across chapters, page
+  contents from three sections, glossary from `definition` blocks.
+
+## Entry topics
+
+- 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

@@ -0,0 +1,57 @@
+---
+name: lernapps-explainer-design
+description: Use in Explore right after choosing the `explainer` archetype - how the content of a lernapps.net explainer maps onto chapters, pages, blocks and exercises, which the plan then applies.
+license: MIT
+---
+
+# Designing an explainer
+
+## What an explainer is
+
+- Chapters of pages that explain a topic, with exercises on every page. Every page is complete without JavaScript;
+  with it, exercises check answers and give feedback.
+- Generated around your content: navigation, contents, glossary, a tutor prompt per page, other languages.
+- You will write the content as YAML; a Vue component only where no block fits.
+
+## Can and cannot
+
+- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/explainer/README.md>.
+  Read it before this skill's mapping, if you have not yet.
+
+## Map the content
+
+- A chapter of competencies → an app chapter. A competency → a page or a section.
+- 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").
+- Shared material → a data file (`src/data/<name>.yaml`), each fact once.
+- A pattern → a block or an exercise with fixed parts, varied in its drawn values or the records it picks.
+- One chapter only: it is hidden in the navigation; its pages keep their addresses.
+
+## Blocks
+
+- 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
+  `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.
+- Something no block can show or check → a component: read a value off a scale, label a figure, drag into place,
+  build a circuit. Logic in its own module, tested; a text for readers without JavaScript.
+- Wanted, not only allowed: all that makes the content attractive - figures, drawings, labelled figures, tables,
+  timelines, videos; a component where no block fits.
+
+## Decide
+
+- Languages: German; English as a second language is supported. Each declared language complete.
+- The tutor: the build writes it from the content. Plan only app-specific tutor rules, if any.
+
+## Gotchas
+
+- Each component costs a module, a test and a no-JS text: plan one only where it teaches what no block can.
+
+## Read when
+
+- [references/rules.md](references/rules.md): before you write "Content method"; it holds the rules for pages,
+  figures, numbers, mistakes and components.

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

@@ -0,0 +1,75 @@
+# Explainer rules for planning
+
+## `topic-has-exercises`: Every page has exercises
+
+```rule
+id: topic-has-exercises
+scope: archetype:explainer
+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.
+
+## `prefer-built-in-block`: A component only where no block fits
+
+```rule
+id: prefer-built-in-block
+scope: archetype:explainer
+severity: hint
+```
+
+- Built-in blocks and exercises first. A component only for what none can express; say why in the plan.
+
+## `explainer-figure-hides-answer`: The figure does not give the answer away
+
+```rule
+id: explainer-figure-hides-answer
+scope: archetype:explainer
+severity: error
+```
+
+- A task's figure shows the given values, never the answer.
+
+## `explainer-figure-explains`: The figure shows what the text says
+
+```rule
+id: explainer-figure-explains
+scope: archetype:explainer
+severity: hint
+```
+
+- Each figure shows what the text next to it explains. The caption says what to look at; `alt` says what it shows.
+
+## `explainer-plausible-numbers`: Numbers that fit the story
+
+```rule
+id: explainer-plausible-numbers
+scope: archetype:explainer
+severity: warning
+```
+
+- Ranges fit the thing: prices in whole cents, people whole, a bicycle 150–1500 €.
+- Preconditions rule out misfits (90.91 people).
+
+## `explainer-mistakes-diagnosed`: Typical mistakes with their message
+
+```rule
+id: explainer-mistakes-diagnosed
+scope: archetype:explainer
+severity: hint
+```
+
+- Computed tasks list real mistakes. Each message says what went wrong and how to fix it ("Du hast vergessen, durch
+  100 zu teilen", not "Falsch").
+
+## `explainer-quote-sourced`: Quotes exact, with their origin
+
+```rule
+id: explainer-quote-sourced
+scope: archetype:explainer
+severity: warning
+```
+
+- Quote exactly. Name its origin (author, work, year), source and licence.

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

@@ -0,0 +1,93 @@
+---
+name: lernapps-explainer-self-assessment
+description: Use in Commit of a lernapps.net explainer, once its content and its forms of teaching are final, to add, change or leave out its self-assessment (selfAssessment in each chapter.yaml) - which exercises it asks, how many on each of its pages, and what the build checks. Also when a build problem names selfAssessment.
+license: MIT
+---
+
+# Self-assessment of an explainer
+
+## What it is
+
+- Two kinds of page: a content page of the app (`/<chapter>/<page>/`), and a step, one page of the
+  self-assessment with a few exercises.
+- Optional, for the learner and for the app. Before learning, the learner answers exercises of the content pages,
+  without the page around them, a few on each step.
+- No exercise is checked alone. "Auswerten" checks all of them together. The result per content page:
+  "Kannst du wahrscheinlich schon" (all right), "Schau sie dir noch einmal an" (at least half), "Lies sie genau"
+  (less), "Nicht abgefragt" (none of its exercises asked).
+- JavaScript only: without it, it is not offered. The last result stays on the device; a new run replaces it.
+- The chapter is the unit: each chapter declares its own in its `chapter.yaml` (at `<chapter>/einschaetzung/`,
+  offered on the chapter's page). The app's (at `einschaetzung/`, offered on the start page) is every chapter's
+  together; you write nothing for it. In an app with one chapter, the app's is the chapter's.
+- The learner may take the result to their KI tutor. The tutor then guides chapter by chapter: to the pages that do
+  not stick, then into a new round of the chapter's self-assessment. The build writes the tutor's page; you write
+  nothing for the tutor.
+
+## Decide
+
+- Default: one in every chapter.
+- None in a chapter whose pages teach what no exercise can check (an open activity, a discussion, making something):
+  the tutor goes through it page by page. None in any chapter: write the reason under "Key decisions" and tell the
+  creator in one sentence.
+- Leave a page out when its competency cannot be checked by one of its exercises. The result says "Nicht
+  abgefragt"; that is right for such a page.
+
+## Choose the exercises
+
+- Read each content page's competency under "Notes" ("Ich kann …"). No "Notes": take it from the page's title,
+  description and rule. Ask the exercises that check it best.
+- Prefer what draws a new task in each run: `generated`, or an exercise component (a `vue-component` block whose
+  component emits an answer, by its anchor). Then `number`, `ordering`, `matching`, `multiple-choice`,
+  `single-choice`. A content page asked only by exercises that can be guessed (`true-false`, a `single-choice` or a
+  small `matching`) gives a weak result: add a `generated`, a component or a `number` one of the same page.
+- Each must be clear without its page: no "wie im Beispiel oben", no figure that stands elsewhere on the page. A
+  question carries its figure in `material`. Not clear alone → take another exercise of the page, or leave the page
+  out.
+- An exercise component shows its task without "Prüfen", feedback or task number. Take it only when its task is
+  clear in the component itself (the task text is in the component, not in a block around it), and when it needs
+  nothing the page has to play or show first.
+- 2 or 3 exercises per content page asked: with one alone, the page is never "Kannst du wahrscheinlich schon". A page
+  with one fitting `generated` exercise or exercise component: list it twice, each listing draws a task of its own.
+  A question is listed once.
+
+## Write it
+
+- Steps: 2 to 5 exercises each, best 3; fewer or more gives a build hint. Keep the order of the course, also within a
+  content page.
+- About 3 to 8 exercises per chapter; the app's, every chapter's together, at most about 15 to 20: about ten minutes.
+- Each exercise by its page and id: `/<chapter>/<page>/#<exercise>`, of the chapter's own pages.
+
+```yaml
+# src/prozent/chapter.yaml
+selfAssessment:
+  pages:
+    - exercises:
+        - /prozent/prozentwert/#prozentwert-ueben
+        - /prozent/prozentsatz/#welche-rechnung
+        - /prozent/prozentsatz/#prozentsatz-ueben
+    - exercises:
+        - /prozent/grundwert/#klammern
+        - /prozent/grundwert/#grundwert-ueben
+```
+
+- In the content guide (`.agents/skills/app-content/SKILL.md`), in the procedure for a new chapter or page, add the
+  step: "1 bis 3 ihrer Übungen in `selfAssessment` aufnehmen, wie Skill `lernapps-explainer-self-assessment` sagt."
+  None in the app → the content guide says why.
+
+## Check
+
+- Build and `lernapps check`: one line per problem (the hint on the size of a step names its file and place), e.g.
+  `src/prozent/chapter.yaml:9: selfAssessment.pages[0].exercises[0]: /prozent/prozentwert/#prozent-raten names no exercise of src/prozent/prozentwert.yaml; …`.
+  Fix where it points.
+- Do one run yourself in `npm run dev` at `/einschaetzung/`, and one at `/<chapter>/einschaetzung/?via=tutor`: it
+  ends in "Zurück zum Tutor". For each exercise: no "oben", "im Beispiel" or other
+  reference to its page; its figure shows with it; the task is the whole question. For each content page asked: one
+  exercise at least that cannot be guessed. Then write the commit.
+- The end-to-end tests do three runs of each self-assessment: every answer right; none; one a tutor opened.
+
+## Gotchas
+
+- An exercise renamed or moved → change its reference in the same commit.
+- `einschaetzung` is reserved: no chapter or page may have that id.
+- 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`).