@lernapps/tooling 0.0.1 → 0.1.1

package/skills/archetypes/lernapps-interactive/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: lernapps-interactive
+description: Use in Code of a lernapps.net interactive app whenever you write or change its core, inputs, user interface, data, playthroughs, frame or arc42 architecture, or a build, playthrough or architecture check fails. What you write, the core's contract, the playthrough format, the frame and full-screen play, the architecture, and the technical rules.
+license: MIT
+---
+
+# Interactive app
+
+- Runtime: `@lernapps/app-templates` (`runtime/interactive/`); leave it untouched.
+- `create` writes a small example app: replace it with the planned parts.
+
+## What you write
+
+- `src/app.yaml` (schema `interactive.v1.schema.json`): what it does, how to play, competencies, languages, routes,
+  optional background sections. Rendered as the static start page and the app page `app/`.
+- Routes: `app/#<id>`; a seed: `app/?seed=<n>#<route>`, else random.
+- `src/core/`, `src/ui/` (root component), `src/data/`, `src/messages/`, `src/playthroughs/`, `src/main.ts`
+  (`startInteractive(core, App)`), and the app's part of `docs/arc42/`.
+
+## Read when
+
+- [references/frame.md](references/frame.md): before you build a control in the heading line, a wider frame,
+  full-screen play, keys or focus.
+
+## Gotchas
+
+- The generated `src/core/index.ts`, `src/ui/App.vue` and playthroughs follow the contract below: read them before you
+  replace them. The types are exported by `@lernapps/app-templates/interactive`.
+- Test a timer by ticks in a playthrough; never wait real time.
+- The arc42 hook fails on new code without a block: `git add` the new files and describe them. Never take back
+  architecture to get past the hook.
+- A check names an `interactive-*` rule: read its section under "Rules" below before you fix.
+
+## Core, components, data, playthroughs
+
+### Core
+
+- `src/core/index.ts`: pure TypeScript, no DOM; the state is plain JSON.
+- Exports `start(seed, route)`, `step(state, input)`, and `tick(state, dt)` if it moves on its own.
+- The runtime owns state and clock and calls `tick(state, 20)` every 20 ms.
+- Randomness only from the seed; never `Math.random` or the clock.
+
+### Inputs
+
+- `{ kind: "key", key }` (`KeyboardEvent.key`) or `{ kind: "action", name, value? }` (pointer, touch).
+- The runtime turns keydown into key inputs; the root component emits `input` (an action or a key).
+- Unknown kinds and ignored keys: return the same state object (Tab keeps moving the focus).
+
+### Components
+
+- `src/ui/`: show the `state` prop; turn actions into inputs.
+- Vue and TypeScript. The component rules apply to them and their imports: `vue-component-no-network`,
+  `vue-component-no-html-injection`, `vue-component-imports`, `vue-component-browser-globals`.
+- Learner texts from `src/messages/<language>.json` through `translator` (`@lernapps/tooling/i18n`), never strings
+  in code (`learner-text-german`).
+- Announce changes with `announce` (`@lernapps/tooling/a11y`); reduced motion with `prefersReducedMotion`.
+
+### Data
+
+- `src/data/`, own format, imported by the core.
+
+### Playthroughs
+
+- `src/playthroughs/<name>.yaml`: `seed`, `route`, `steps`.
+- A step: `keys` (short form) or `inputs`, then `ticks` (20 ms each), at least one of them; it expects a part of the
+  state, an announcement, or both. No time passes except the named ticks.
+- The build plays each twice against the core and fails on differing plays or a wrong state. The end-to-end test
+  plays the same in the browser, desktop and 360 px.
+- Expect only what the steps decide.
+
+### Storage
+
+- `createStorage` (`storage-through-wrapper`, skill `lernapps-cli`).
+
+## Architecture (arc42)
+
+- `docs/arc42/`, arc42 DSL (`@doctc/arc42`), English, minimal.
+- `create` copies the generic part and the interactive extension; `update` replaces them.
+- Write only between `<!-- app: begin … -->` and `<!-- app: end … -->`; nothing outside.
+- Chapter 5: each part of core, UI, data as a level-3 heading in section `core`, `ui` or `data`, with `parent`,
+  `path` and a diagram of the block and its parts. Each new leaf block on a deployment node in chapter 7.
+- Concepts, decisions (canvas or DOM), declared accessibility with reasons: in the sections at the chapter ends.
+- 1–2 sentences per block or decision: responsibility, reason; nothing the code says.
+- Update with every change, same commit as the code.
+- Pre-commit `arc42 diff --staged` fails on: block changed without prose (or the reverse); new `src/` code no block
+  claims and not in `.arc42ignore`. It reads staged files: `git add` new files.
+- Review hint (code under an interface's path changed): warning; read and update if needed.
+- Accept a finding with `ARC42_CONSISTENT` only for a shown consistency finding judged intended, with a note in the
+  plan. Never preset it (e.g. `$(git rev-parse HEAD)`): a bypass like `--no-verify`.
+- Unclaimed new code is never accepted: give it a block, or list config in `.arc42ignore`.
+- `lernapps check` runs `arc42 validate --strict` on the working tree: any error, warning or hint fails.
+- Your work; no creator checkpoint.
+
+## Rules
+
+### `interactive-app-valid`: The description and the playthroughs validate
+
+```rule
+id: interactive-app-valid
+scope: archetype:interactive
+severity: error
+```
+
+- `src/app.yaml` and every playthrough valid against their schemas; German first, every language complete.
+- Unique ids; at least one playthrough; each step expects a state or an announcement; playthrough routes exist.
+- Build names each problem with file and line.
+
+### `interactive-core-contract`: The core keeps its contract
+
+```rule
+id: interactive-core-contract
+scope: archetype:interactive
+severity: error
+```
+
+- `src/core/index.ts` exports `start(seed, route)`, `step(state, input)`; `tick(state, dt)` as a function if it
+  moves on its own.
+- Every route starts; nothing throws; same seed, route, inputs, ticks → same states.
+
+### `interactive-playthroughs-pass`: Every playthrough plays as written
+
+```rule
+id: interactive-playthroughs-pass
+scope: archetype:interactive
+severity: error
+```
+
+- After each step the state has the expected fields; the browser shows the expected announcement.
+- Failure → fix core or playthrough, whichever is wrong; never delete a playthrough.
+
+### `interactive-architecture-current`: The architecture is valid and current
+
+```rule
+id: interactive-architecture-current
+scope: archetype:interactive
+severity: error
+```
+
+- `docs/arc42/`: generic part and extension as `create`/`update` wrote them, unchanged outside the app sections.
+- App part describes the code: every part of `src/` has its block, every block its code.
+- `arc42 validate --strict` and `arc42 diff --staged` pass; the review checks it says what the code does.

package/skills/archetypes/lernapps-interactive/references/frame.md

@@ -0,0 +1,30 @@
+# Frame and full-screen game
+
+## Frame
+
+- App page: header (language switch only; none with one language), `<main>` (heading line: the title as h1 and a
+  slot beside it; `<noscript>` note, route links, `.interactive-app` mount), footer (imprint, privacy). At most
+  `--page-max-width` wide, 44rem by default.
+- A control in the heading line: `startInteractive(core, App, { title: Controls })`. The runtime mounts it into the
+  slot, with the root component's props (`state`, `lang`) and `input` event. Never hide or rebuild the h1. Without
+  `title` the slot stays hidden.
+- A wider frame: `--page-max-width` (e.g. `60rem`) in the app's own `:root` rule; it widens header, page and
+  footer. Never override the runtime's selectors.
+- Start page: own static page, no script; the app page never changes it.
+
+## Full-screen while playing
+
+- Own overlay only: root element class from state (e.g. `state.phase === "playing"`), `position: fixed; inset: 0`,
+  page background. Leave runtime markup and CSS.
+- Way out: visible button ("Pause"); Escape ends the overlay as a core input. Time limit or other loss → entry
+  `limits`.
+- Browser full screen (`element.requestFullscreen()`): optional, only after a click, via template ref; overlay works
+  without it. Browser globals only in `onMounted` (`vue-component-browser-globals`).
+
+## Keys and focus
+
+- Runtime gives keys to the core only when focus is not on a link, button, form field.
+- Play area focusable (`tabindex="0"`, `aria-label`); focus it via template ref (`area.value?.focus()`) when play
+  starts. Focus visible.
+- Space and arrows: runtime prevents default only for state-changing keys. Let the core take them while playing, or
+  `@keydown.space.prevent` (and arrows) on the play area.

package/skills/archetypes/lernapps-interactive-design/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: lernapps-interactive-design
+description: Use in Explore right after choosing the `interactive` archetype - how the content of a lernapps.net interactive app maps onto core, user interface, data and playthroughs, which the plan then applies.
+license: MIT
+---
+
+# Designing an interactive app
+
+## What an interactive app is
+
+- The learner's doing is the content: play, train, work in one app page. A static start page without script says
+  what it is.
+- The code is yours. The runtime renders the frame, owns state and clock, and feeds inputs to your core.
+- Write in "Content method" one line per part below; the architecture in Code follows it.
+
+## Can and cannot
+
+- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/interactive/README.md>.
+  Read it before this skill's mapping, if you have not yet.
+
+## Parts
+
+1. **Core:** pure TypeScript, no DOM; the state is plain JSON. It starts from a seed and a route, takes inputs,
+   and moves on with ticks if time matters. Randomness only from the seed: same seed, route and inputs → same
+   states.
+2. **User interface:** Vue components show the state and turn actions into inputs. They keep no game state of
+   their own. Render as DOM, SVG or canvas.
+3. **Data:** the content (levels, tasks, texts) as data files the core imports. A new level is a data change.
+4. **Playthroughs:** one per behaviour to keep, timing included: seed, route, inputs, ticks, the state expected. They
+   are the proof that the core works; the build plays each twice, the browser once.
+5. **Routes:** one per mode or level the entry may link to (`app/#<id>`).
+
+## Decide
+
+- Inputs: which keys, which buttons or touch actions. Every action works by keyboard.
+- Timing: time limits and moving parts are ticks of the core, never the clock.
+- Storage: small (at most 100 kB), the learning state only; no settings dialog.
+- Libraries: bundled from `dependencies`, open licence; never a CDN.
+- Accessibility: WCAG 2.1 AA and 360 px are the default. A deviation the idea needs (a time limit) goes into the
+  entry's `limits`, in German.
+- Look and feel: as the creator chose in Explore.
+- Languages: German; each declared language complete; learner texts in message files, never in code.
+
+## Gotchas
+
+- "Low stimulation" means no overload, not no fun: a game may look like a game (bold colours, a real board). No
+  flashing; calm motion, less with reduced motion; sound off by default. The start page stays calm.
+- A timer is a tick of the core with a playthrough that tests the end of time, not `setTimeout` in a component.
+
+## `start-page-explains`: The start page explains the app
+
+```rule
+id: start-page-explains
+scope: archetype:interactive
+severity: hint
+```
+
+- The static start page says what learners train, for whom, and how to begin.

package/skills/archetypes/lernapps-quiz/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: lernapps-quiz
+description: Use in Code of a lernapps.net quiz whenever you write or change the question bank src/quiz.json, add a language, or a build or runtime test of the quiz fails. What you write, how the runtime shows and tests the bank, languages, and the quiz's technical rules. The question types and how to write good questions are in lernapps-content-questions.
+license: MIT
+---
+
+# Quiz
+
+- You write `src/quiz.json` and, for the content of its questions, the image files in `src/images/`. Engine, question
+  types, feedback, scoring, order, accessibility and the no-JS page come from the runtime `@lernapps/app-templates`.
+- Schema: `node_modules/@lernapps/app-templates/runtime/quiz/quiz.v1.schema.json`.
+- `create` writes the example bank "Naturwunder der Welt": replace it with the planned questions.
+- The fields of each question type and how to write good questions: skill `lernapps-content-questions`.
+
+## Gotchas
+
+- The build validates the bank; the runtime's tests then answer every question in the browser. A runtime test that
+  fails while the bank validates is a template bug (skill `lernapps-cli`).
+
+## Runtime
+
+### Build and page
+
+- Build reads, validates, renders every question into `index.html`, with the content it shows (`material`), and
+  carries the images of `src/images/` to `images/`.
+- No JS: a worksheet; all questions, then solutions with background and links.
+- JS: one question at a time, right or wrong shown; then each option's `info` (right ones and the choice marked),
+  the explanation, the links. Score and solutions at the end.
+- Order shuffled by `?seed=42` (same link, same order). Deep link to a question: `#frage-<id>`.
+
+### Storage
+
+- Stores nothing, unless `"rememberLastResult": true`: then the last score stays on the device.
+
+### Tests
+
+- From the runtime (`e2e/quiz.e2e.ts`), run by `lernapps check`. Per question: deep link, a right and a wrong answer,
+  every `info`, explanation and links shown. Also full score and the no-JS page.
+- Each further language: its no-JS page (questions, solutions, switch) and one answered question in that language.
+- New runtime features or fixes: `lernapps update` (skill `lernapps-cli`).
+
+### A runtime test fails
+
+- Bank validates (build passes) but a runtime test fails = template bug: act as skill `lernapps-cli` says.
+- Never change the runtime in `node_modules` (`quiz-only-data`). Go on with the questions.
+- A question shows an image or a table with `material`: skill `lernapps-content-questions`, its reference question-types.
+
+### Languages
+
+- German; more with `"languages": ["de", "en"]`, German first (runtime texts: de, en).
+- Then every learner text is a map with each language: title, intro, source titles; per question text, options,
+  `info`, items, pairs, unit, explanation, link titles.
+- Without `languages`: German strings.
+- Link `url`: one address, or a map per language (own Wikipedia).
+- Build errors, one line each, e.g.
+  `questions[1].explanation (en) (question "totes-meer"): the translation is missing; write the text as a map: { de: …, en: … }`;
+  undeclared language: `… is not a language of the app; declare it in languages in src/quiz.json, or remove it`;
+  `languages[0]: German comes first`.
+- Pages: German `index.html`, others `<language>/index.html`, with `lang`, `hreflang`, a no-JS language switch.
+
+```json
+{
+  "id": "totes-meer",
+  "type": "true-false",
+  "text": { "de": "Im Toten Meer kann man nicht untergehen.", "en": "You cannot sink in the Dead Sea." },
+  "answer": true,
+  "explanation": {
+    "de": "Das Wasser ist so salzig, dass ein Mensch an der Oberfläche treibt.",
+    "en": "The water is so salty that a person floats on the surface."
+  },
+  "links": [
+    { "title": { "de": "Totes Meer (Wikipedia)", "en": "Dead Sea (Wikipedia)" }, "url": "https://de.wikipedia.org/wiki/Totes_Meer" }
+  ]
+}
+```
+
+## Rules
+
+### `quiz-only-data`: Write only the question bank and its images
+
+```rule
+id: quiz-only-data
+scope: archetype:quiz
+severity: error
+```
+
+- Change only `src/quiz.json` and add image files to `src/images/`. `index.html`, `src/main.ts`, `e2e/quiz.e2e.ts`,
+  config as generated (`keep-the-preset`).
+- Bank cannot say it → "Where I had to guess", never code around the runtime.
+
+### `quiz-stable-ids`: Keep the ids
+
+```rule
+id: quiz-stable-ids
+scope: archetype:quiz
+severity: warning
+```
+
+- Short, telling `id` ("grand-canyon"); keep it when the text changes (shared links `#frage-<id>`).
+- New question, new id; never reuse a removed one.

package/skills/archetypes/lernapps-quiz-design/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: lernapps-quiz-design
+description: Use in Explore right after choosing the `quiz` archetype - how the content of a lernapps.net quiz maps onto rounds, question types and patterns, which the plan then applies.
+license: MIT
+---
+
+# Designing a quiz
+
+## What a quiz is
+
+- One page of questions with options and feedback. The runtime shows one question at a time, then each option's
+  background, the explanation and links; the score at the end. Without JavaScript: a worksheet with solutions.
+- You will write the question bank `src/quiz.json` and, for what a question shows, image files in `src/images/`;
+  no code (`quiz-only-data`).
+
+## Can and cannot
+
+- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/quiz/README.md>.
+  Read it before this skill's mapping, if you have not yet.
+
+## Map the content
+
+- A chapter → a round: the questions of one chapter, next to each other in the bank.
+- A competency → one or more questions.
+- The bank is the shared material: each fact in one question.
+- A pattern → one question type with a fixed form of text, options and background, varied over a round's facts.
+- Not expressible as a question → no code: note it under "Where I had to guess"; an issue at
+  <https://github.com/lernapps/app-templates/issues> if other quizzes need it.
+
+## Question types
+
+| `type` | The learner |
+|---|---|
+| `single-choice` | chooses one option |
+| `multiple-choice` | chooses every correct option |
+| `true-false` | judges a statement |
+| `number` | types a number, within a tolerance |
+| `ordering` | puts items in their fixed order |
+| `matching` | matches left to right |
+
+- Which pattern fits which competency: skill `lernapps-exercise-patterns`.
+
+## Decide
+
+- Languages: German; English as a second language is supported. Each declared language complete.
+- Keep the last score on the device (`rememberLastResult`) or nothing. Keeping it → the entry says
+  `fitness.storage: device`.
+- Order: shuffled per seed; a link with `?seed=42` gives every learner the same order.

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