@lernapps/tooling 0.0.1 → 0.1.1

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

@@ -0,0 +1,66 @@
+# Components
+
+- Only for what no block or `generated` can express (label a figure, drag into place). Blocks are readable without
+  JS, accessible, tested by construction.
+
+## Files (`src/components/`)
+
+- Only `<Name>.vue`, `<Name>.ts`, `<Name>.test.ts`; PascalCase; no subfolders, no other files.
+- Every `.vue`: `<script setup lang="ts">` and its `<Name>.test.ts` (run by `lernapps check`; `.vue` type-checked
+  with `vue-tsc`).
+- Exercise: logic in `<Name>.ts`. Shared helpers: a `<Name>.ts` here, imported with extension (`./Circuit.ts`).
+
+## Block and props
+
+- `type: vue-component`, `component: <Name>`, `props`, `nojs` (not for an exercise).
+- `defineProps<{ … }>()`: `string`, `number`, `boolean`, literals, unions, arrays, object types of them; declared in
+  the component or a local type alias. No `null`, no `undefined` union (make it optional), no imported alias.
+- The build checks each block's `props`. A `string` prop is a learner text: a map with several languages.
+- A list prop may be `{ data: <name> }`: the records of `src/data/<name>.yaml`, cut to the fields the item type declares
+  (`events: { title: string }[]`). Each record needs them; a missing file or field fails the build. One data file,
+  many blocks: never copy records into `props`. A field of a record may be a list or a record of values
+  (`compounds: [{ formula, text }]`) for this; exercises and timelines use the flat fields.
+
+## `nojs`
+
+- Restricted Markdown: what it shows plus its content (diagram described, or task with solution); carries the
+  meaning alone.
+- Replaced once the component runs; `defineOptions({ nojs: "caption" })` keeps it folded as a description.
+- Never in an exercise component (it would give the solution; build fails). Its text comes from `describe` for task 1.
+
+## Exercise contract
+
+- Emits `answer` → exercise. It is only the input: emit the learner's answer on every change (`undefined` while
+  none). No own "Prüfen", no own `<form>`, no call of `check`: the explainer draws "Prüfen" under it (Enter in a field
+  checks), calls `check`, `reason` and `show`, shows the feedback. Own controls ("Zurücksetzen", tools) stay, as
+  `type="button"`. Optional prop `checked: boolean`: true once the current answer is checked.
+- `answered` is gone: the build fails on it.
+- Does not count as the page's required exercise: the page also needs a question or a `generated` exercise.
+- `<Name>.ts`, pure: `generate(seed, props)`, `check(task, answer)` (boolean), `solution(task)`, `wrong(task)`,
+  `reason(task, answer, props, lang)` (the app's message for a wrong answer from the props' texts, `undefined` for
+  none; what does not fit, never the solution). A component shows nothing after "Prüfen" that gives the solution away. Check the asked property, not equality with `solution`.
+- Build tests 50 fixed seeds per block: same task per seed, solution passes, wrong fails, nothing throws.
+- `about.mistakes` from the same wrong answers as `examples.rejected`; `describe` states the task exactly as shown
+  for that task number (no-JS text).
+- For the tutor: `template(props, lang)` (task with `{name}`), `params(task, props, lang)` (inputs by name),
+  `mistakes(task, props)` (per `about.mistakes` its one fixed answer, else `undefined`: never an invented example),
+  `show(answer, task, props, lang)` (answer as text). An input of `params` that is no placeholder shows as
+  "(verdeckt)": the tutor knows it, the child does not. One `template` per block: prefer one kind of task per block;
+  else give the sentence that changes as an input (`{Aufgabe}`). `about.answer` names what the child does and "Prüfen". The build checks them against `check` for every number; rule `vue-component-tutor-table`. Model:
+  `ProzentFeld` of the template.
+- More: rule `vue-component-exercise-contract`.
+
+## Rendering
+
+- Server-rendered into the page, hidden until hydrated. First render identical on server and browser:
+  `generate(1, props)`; randomness only in `onMounted`.
+- No headings in its markup (also hidden parts). Texts via props, not strings in code.
+
+## Limits (build and lint check, same ids)
+
+- No network: no `fetch`, XMLHttpRequest, WebSocket, EventSource, `sendBeacon`, URL imports.
+- No `eval`, `new Function`, `innerHTML`, `v-html`.
+- Imports: `vue`, `@lernapps/app-templates`, `@lernapps/tooling/storage`, `i18n`, `a11y`, own folder.
+- Browser globals only in `onMounted` or later unmount hooks.
+- Storage only via `createStorage`.
+- Max 20 kB gzip own code (Vue not counted); more → split, or ask for a block.

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

@@ -0,0 +1,115 @@
+# Exercises
+
+- Every page at least one, best in a last section "Übung".
+- What counts as right and each wrong answer's feedback: from "Content method" of the plan.
+- Wrong answer gets the most specific reason: chosen option's `info`, a matching `mistakes` entry (`generated`;
+  `number` with `answer`, `message`), the `hint`, else "look again". Write `info` per wrong option, 2–3 mistakes,
+  a `hint`.
+
+## Quiz types
+
+- `single-choice`, `multiple-choice`, `true-false`, `number`, `ordering`, `matching`: blocks with the quiz fields
+  (`id`, `type`, `text`, `explanation`, `links`, type fields). Fields and how to write them: skill
+  `lernapps-content-questions`.
+
+```yaml
+- type: ordering
+  id: staende-ordnen
+  text: Bringe die Stände in ihre Rangfolge, den ersten Stand zuerst.
+  items: [die Geistlichen, der Adel, alle anderen]
+  explanation: Der erste Stand waren die Geistlichen, der zweite der Adel, der dritte alle anderen.
+  links:
+    - { title: Ständegesellschaft (Wikipedia), url: "https://de.wikipedia.org/wiki/Ständegesellschaft" }
+```
+
+## `generated`
+
+- 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).
+- `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
+  `{ number: { format: integer|decimal|money|percent, decimals, tolerance, unit } }`, `{ choice: <options> }`,
+  `order`, `pairs` or `{ pairs: { left, right } }`.
+- `mistakes`: `value` + `message` each. `hint`, `steps`: help, the way to the solution.
+- 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`.
+
+### Placeholders
+
+- Always two braces around a declared name or field: `{{G}}`, `{{e.name}}`, `{{answer}}` in steps. Prose and
+  formulas alike.
+- One brace is never a placeholder: `G`, `{G}`, `\frac{W}{G}` are letters. Group around a value stays:
+  `$\frac{{{W}}}{{{G}}} \cdot 100 = {{answer}}$`.
+- Build fails on: undeclared name; `{G}` or `{{ G }}` in prose; a `given` variable nothing uses (`where` does not
+  count); a placeholder left after filling.
+
+```yaml
+- type: generated
+  id: prozentwert-ueben
+  given:
+    G: { int: [150, 1500], step: 5 }
+    p: { oneOf: [5, 10, 12, 15, 20, 25, 30, 40] }
+  where: ["decimals(G * p / 100) <= 2"]
+  task:
+    text: "Ein Fahrrad kostet {{G}} €. Im Angebot gibt es {{p}} % Rabatt. Wie viel Euro sparst du?"
+  answer: { value: "G * p / 100", compare: { number: { format: money } } }
+  mistakes:
+    - { value: "G * p", message: "Du hast vergessen, durch 100 zu teilen: {{p}} % sind {{p}} Hundertstel." }
+    - { value: "G - G * p / 100", message: "Das ist der neue Preis, nicht der Rabatt." }
+  hint: "Rechne erst 1 % aus: {{G}} € geteilt durch 100."
+  steps:
+    - '$W = \frac{G \cdot p}{100}$'
+    - '$W = \frac{{{G}} \cdot {{p}}}{100} = {{answer}}$, also {{answer}} € Rabatt.'
+```
+
+- Data-file example: `given: { events: { pick: 3, distinct: true, from: { data: ereignisse } } }`,
+  `where: ["events[0].date != events[1].date"]`, `answer: { value: "map(sortBy(events, date), title)", compare: order }`,
+  mistake `map(reverse(sortBy(events, date)), title)`.
+
+### Property test (200 fixed seeds; first problem with its seed)
+
+- `where` holds in at least 1 of 10 draws.
+- Answer defined, in its format, passes its own comparator.
+- No mistake equals the answer (`for seed 17 the mistake equals the answer (20); …`); each mistake is enterable.
+- Same task for the same seed; no placeholder left.
+- Mistake equal to the answer for some values = range too wide (`G - G * p / 100` = `G * p / 100` at 50 %: so `p`
+  ≤ 40).
+
+## `open-task`
+
+- For what learners answer in their own words: describe, explain, compare, argue; a short text in German or a foreign
+  language. Not for what a quiz type can check.
+- The learner answers first, typed or on paper with a photo (`answer: [text, photo]`, both by default), then compares:
+  the points show as tick boxes, each point of the content with its link "Nachlesen", and the model answer opens.
+  The ticks give right, partly right or wrong for the self-assessment and the tutor.
+- `task`: what to write and how long ("in zwei bis vier Sätzen").
+- `points`: 2 to 5, each one checkable sentence a good answer has, in its order. A point of the content has `source`,
+  the section of the app where its content is, `/<chapter>/<page>/#<section>` (the build checks it like a link); a
+  point of form (whole sentences, a thread, the words to use, the tense) has `kind: form` and no source. Only what the
+  material teaches.
+- `solution`: the model answer, in the words a learner of the class would write, with every point. `hint` optional.
+
+```yaml
+- type: open-task
+  id: tauschen-erklaeren
+  task: Erkläre in zwei bis vier Sätzen, warum 20 % von 50 € genauso viel sind wie 50 % von 20 €.
+  points:
+    - text: Der Prozentwert ist Grundwert mal Prozentsatz, geteilt durch 100.
+      source: /prozent/prozentwert/#regel
+    - text: Beim Malnehmen darf man die Zahlen tauschen, darum ist das Ergebnis gleich.
+      source: /prozent/prozentwert/#regel
+    - text: Ganze Sätze mit einer Begründung (weil …, darum …).
+      kind: form
+  solution: |
+    Den Prozentwert rechnet man mit $W = \frac{G \cdot p}{100}$. Für 20 % von 50 € ist das
+    $\frac{50 \cdot 20}{100} = 10$, für 50 % von 20 € ebenso 10. Weil man beim Malnehmen tauschen darf, kommt beide
+    Male 10 € heraus.
+```
+
+## Examples
+
+- Any exercise: `examples: { accepted, rejected }`, checked by the build, never shown. `generated`: expressions of
+  `given` and `answer`, checked per seed (e.g. `reverse(answer)`).

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