@lernapps/tooling 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,137 @@
 {
   "name": "@lernapps/tooling",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Shared tooling of the lernapps.net apps and sites: the CLI lernapps, site actions, Renovate preset, guidance for building apps; documentation at https://lernapps.net/tooling/",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lernapps/tooling.git"
+  },
+  "bin": {
+    "lernapps": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "archetypes",
+    "check/validation-report.v1.schema.json",
+    "generator",
+    "review/verdict.v1.schema.json",
+    "guidance",
+    "skills"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./preset": {
+      "types": "./archetypes/shared/preset.ts",
+      "default": "./dist/preset.mjs"
+    },
+    "./playwright": {
+      "types": "./archetypes/shared/playwright.ts",
+      "default": "./dist/playwright.mjs"
+    },
+    "./storage": {
+      "types": "./archetypes/shared/storage.ts",
+      "default": "./dist/storage.mjs"
+    },
+    "./i18n": {
+      "types": "./archetypes/shared/i18n.ts",
+      "default": "./dist/i18n.mjs"
+    },
+    "./a11y": {
+      "types": "./archetypes/shared/a11y.ts",
+      "default": "./dist/a11y.mjs"
+    },
+    "./lint": {
+      "default": "./dist/lint.mjs"
+    },
+    "./tsconfig.json": "./archetypes/shared/tsconfig.json",
+    "./check/validation-report.v1.schema.json": "./check/validation-report.v1.schema.json",
+    "./review/verdict.v1.schema.json": "./review/verdict.v1.schema.json",
+    "./guidance/AGENTS.md": "./guidance/AGENTS.md",
+    "./guidance/plan-template.md": "./guidance/plan-template.md",
+    "./guidance/increment-template.md": "./guidance/increment-template.md",
+    "./guidance/plan-front-matter.v1.schema.json": "./guidance/plan-front-matter.v1.schema.json",
+    "./guidance/workflow-rules.md": "./guidance/workflow-rules.md",
+    "./guidance/subagent-brief.md": "./guidance/subagent-brief.md",
+    "./skills/archetypes/lernapps-explainer-design/SKILL.md": "./skills/archetypes/lernapps-explainer-design/SKILL.md",
+    "./skills/archetypes/lernapps-explainer-design/references/rules.md": "./skills/archetypes/lernapps-explainer-design/references/rules.md",
+    "./skills/archetypes/lernapps-explainer-self-assessment/SKILL.md": "./skills/archetypes/lernapps-explainer-self-assessment/SKILL.md",
+    "./skills/archetypes/lernapps-explainer/SKILL.md": "./skills/archetypes/lernapps-explainer/SKILL.md",
+    "./skills/archetypes/lernapps-explainer/references/blocks.md": "./skills/archetypes/lernapps-explainer/references/blocks.md",
+    "./skills/archetypes/lernapps-explainer/references/components.md": "./skills/archetypes/lernapps-explainer/references/components.md",
+    "./skills/archetypes/lernapps-explainer/references/exercises.md": "./skills/archetypes/lernapps-explainer/references/exercises.md",
+    "./skills/archetypes/lernapps-explainer/references/rules.md": "./skills/archetypes/lernapps-explainer/references/rules.md",
+    "./skills/archetypes/lernapps-explainer/references/runtime.md": "./skills/archetypes/lernapps-explainer/references/runtime.md",
+    "./skills/archetypes/lernapps-explainer/references/structure.md": "./skills/archetypes/lernapps-explainer/references/structure.md",
+    "./skills/archetypes/lernapps-interactive-design/SKILL.md": "./skills/archetypes/lernapps-interactive-design/SKILL.md",
+    "./skills/archetypes/lernapps-interactive/SKILL.md": "./skills/archetypes/lernapps-interactive/SKILL.md",
+    "./skills/archetypes/lernapps-interactive/references/frame.md": "./skills/archetypes/lernapps-interactive/references/frame.md",
+    "./skills/archetypes/lernapps-quiz-design/SKILL.md": "./skills/archetypes/lernapps-quiz-design/SKILL.md",
+    "./skills/archetypes/lernapps-quiz/SKILL.md": "./skills/archetypes/lernapps-quiz/SKILL.md",
+    "./skills/content/lernapps-content-questions/SKILL.md": "./skills/content/lernapps-content-questions/SKILL.md",
+    "./skills/content/lernapps-content-questions/references/question-types.md": "./skills/content/lernapps-content-questions/references/question-types.md",
+    "./skills/content/lernapps-content-research/SKILL.md": "./skills/content/lernapps-content-research/SKILL.md",
+    "./skills/content/lernapps-content-research/references/sources.md": "./skills/content/lernapps-content-research/references/sources.md",
+    "./skills/content/lernapps-exercise-patterns/SKILL.md": "./skills/content/lernapps-exercise-patterns/SKILL.md",
+    "./skills/content/lernapps-exercise-patterns/references/biology-geography.md": "./skills/content/lernapps-exercise-patterns/references/biology-geography.md",
+    "./skills/content/lernapps-exercise-patterns/references/chemistry.md": "./skills/content/lernapps-exercise-patterns/references/chemistry.md",
+    "./skills/content/lernapps-exercise-patterns/references/computer-science.md": "./skills/content/lernapps-exercise-patterns/references/computer-science.md",
+    "./skills/content/lernapps-exercise-patterns/references/figures.md": "./skills/content/lernapps-exercise-patterns/references/figures.md",
+    "./skills/content/lernapps-exercise-patterns/references/history.md": "./skills/content/lernapps-exercise-patterns/references/history.md",
+    "./skills/content/lernapps-exercise-patterns/references/mathematics.md": "./skills/content/lernapps-exercise-patterns/references/mathematics.md",
+    "./skills/content/lernapps-exercise-patterns/references/page-structures.md": "./skills/content/lernapps-exercise-patterns/references/page-structures.md",
+    "./skills/content/lernapps-exercise-patterns/references/physics.md": "./skills/content/lernapps-exercise-patterns/references/physics.md",
+    "./skills/content/lernapps-exercise-patterns/references/success.md": "./skills/content/lernapps-exercise-patterns/references/success.md",
+    "./skills/process/lernapps-app/SKILL.md": "./skills/process/lernapps-app/SKILL.md",
+    "./skills/process/lernapps-commit/SKILL.md": "./skills/process/lernapps-commit/SKILL.md",
+    "./skills/process/lernapps-content-growth/SKILL.md": "./skills/process/lernapps-content-growth/SKILL.md",
+    "./skills/process/lernapps-github/SKILL.md": "./skills/process/lernapps-github/SKILL.md",
+    "./skills/process/lernapps-listing/SKILL.md": "./skills/process/lernapps-listing/SKILL.md",
+    "./skills/process/lernapps-listing/references/keeping-updated.md": "./skills/process/lernapps-listing/references/keeping-updated.md",
+    "./skills/tooling/lernapps-cli/SKILL.md": "./skills/tooling/lernapps-cli/SKILL.md",
+    "./skills/tooling/lernapps-cli/references/platform-rules.md": "./skills/tooling/lernapps-cli/references/platform-rules.md"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "prepare": "vp pack && node scripts/dist-skills.ts && vp config --no-agent",
+    "lernapps": "node src/cli.ts",
+    "check": "npm run --silent lernapps -- check",
+    "rules": "node scripts/rules.ts list",
+    "verdict": "node scripts/verdict.ts",
+    "build": "./scripts/build.sh",
+    "check:site": "lernapps-check --site /tooling/",
+    "arc42": "arc42 --dir docs/arc42"
+  },
+  "dependencies": {
+    "@lernapps/app-templates": "0.1.0",
+    "axe-core": "4.14.0",
+    "playwright": "1.64.1",
+    "skills": "1.7.4",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@doctc/arc42": "0.38.0",
+    "@lernapps/site": "github:lernapps/lernapps.github.io#4c677cc9949b22bcd24b168dfb00098f3ccae624",
+    "@types/node": "26.6.5",
+    "ajv": "8.20.0",
+    "vite-plus": "1.4.0"
+  },
+  "peerDependencies": {
+    "vite-plus": "1.0.0 || 1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "vite-plus": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0"
+  },
+  "engines": {
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
+  }
+}

package/review/verdict.v1.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lernapps.net/tooling/schemas/verdict.v1.schema.json",
+  "title": "Review verdict of lernapps, version 1",
+  "description": "What the review agent judged on an app that asks to be listed, as YAML (verdict.yaml): the reviewed commit, the rules judged, and every finding with its rule id or a proposed new rule. Written by the agent that follows review/prompt.md of @lernapps/tooling, checked with `npm run verdict -- <file>`. A breaking change gets a new version of this schema.",
+  "type": "object",
+  "properties": {
+    "reviewed": {
+      "description": "What was reviewed: the commit of the app's repo, and where the app and its listing are.",
+      "type": "object",
+      "properties": {
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$",
+          "description": "The full id of the reviewed commit"
+        },
+        "repo": { "type": "string", "minLength": 1, "description": "The app's repo: a URL, or a directory" },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where the app is deployed, if it was reviewed there"
+        },
+        "listing": { "type": "string", "minLength": 1, "description": "The listing pull request, if there is one" }
+      },
+      "required": ["commit"],
+      "additionalProperties": false
+    },
+    "report": {
+      "description": "The validation report of `lernapps check` the review started from: its file, or the URL of the listing comment that holds it.",
+      "type": "string",
+      "minLength": 1
+    },
+    "archetype": {
+      "description": "The archetype from the plan's front matter; null when the app has no plan file. It selects review/archetypes/<archetype>.md.",
+      "enum": ["explainer", "interactive", "quiz", null]
+    },
+    "outcome": {
+      "description": "fail when a finding has severity error, else pass. The owner decides on the listing.",
+      "enum": ["pass", "fail"]
+    },
+    "rules": {
+      "description": "The ids of the rubric items judged: those of review/rubric.md and of the archetype's file.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/id" },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "findings": {
+      "description": "Every finding, sorted by severity and rule id. Each names a rule of the catalog (rule, link), or proposes a new rule (proposal).",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "rule": { "$ref": "#/$defs/id", "description": "The id of the broken rule, as `npm run rules` lists it" },
+          "link": {
+            "type": "string",
+            "pattern": "^https://lernapps\\.net/tooling/rules/#[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+            "description": "The rule's entry on the rule page"
+          },
+          "proposal": {
+            "description": "A new rule, when no rule of the catalog covers the finding.",
+            "type": "object",
+            "properties": {
+              "id": { "$ref": "#/$defs/id", "description": "A stable name that is no rule id yet" },
+              "title": { "type": "string", "minLength": 1 },
+              "text": { "type": "string", "minLength": 1, "description": "The rule, as a skill would tell it" },
+              "scope": {
+                "type": "array",
+                "items": { "type": "string", "pattern": "^(listing|archetype:[a-z][a-z0-9-]*)$" },
+                "minItems": 1,
+                "uniqueItems": true
+              },
+              "severity": { "enum": ["error", "warning", "hint"] },
+              "actsIn": { "$ref": "#/$defs/artifacts", "description": "Where the rule would act" }
+            },
+            "required": ["id", "actsIn"],
+            "additionalProperties": false
+          },
+          "severity": { "enum": ["error", "warning", "hint"] },
+          "where": {
+            "type": "string",
+            "minLength": 1,
+            "description": "File of the bundle or repo and element, page, or the plan's section"
+          },
+          "found": { "type": "string", "minLength": 1, "description": "What was found" },
+          "fix": { "type": "string", "minLength": 1, "description": "How to fix it" },
+          "moveTo": {
+            "$ref": "#/$defs/artifacts",
+            "description": "For a rule of the catalog: where it could be decided or prevented next time, so that it moves down from the review"
+          }
+        },
+        "required": ["severity", "where", "found", "fix"],
+        "additionalProperties": false,
+        "dependentRequired": { "rule": ["link"], "link": ["rule"] },
+        "oneOf": [
+          { "properties": { "rule": true }, "required": ["rule"] },
+          { "properties": { "proposal": true }, "required": ["proposal"] }
+        ]
+      }
+    },
+    "at": { "type": "string", "description": "ISO 8601 date of the review" }
+  },
+  "required": ["reviewed", "report", "archetype", "outcome", "rules", "findings"],
+  "additionalProperties": false,
+  "if": { "type": "object", "properties": { "outcome": { "const": "pass" } }, "required": ["outcome"] },
+  "then": {
+    "properties": {
+      "findings": {
+        "type": "array",
+        "not": {
+          "type": "array",
+          "contains": { "type": "object", "properties": { "severity": { "const": "error" } }, "required": ["severity"] }
+        }
+      }
+    }
+  },
+  "else": {
+    "properties": {
+      "findings": {
+        "type": "array",
+        "contains": { "type": "object", "properties": { "severity": { "const": "error" } }, "required": ["severity"] }
+      }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$" },
+    "artifacts": {
+      "type": "array",
+      "items": { "enum": ["skill", "lint rule", "check", "rubric item"] },
+      "minItems": 1,
+      "uniqueItems": true
+    }
+  }
+}

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

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