@lernapps/practice 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 the lernapps.net contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,24 @@
-# @lernapps/practice
+# practice
 
-Placeholder that reserves the name. The first release follows from CI with provenance; the source is at <https://github.com/lernapps/practice>.
+lernapps.net bietet zwei Wege: **Lernen** mit den dauerhaften Apps im [Katalog](https://lernapps.net/apps/) und **Üben** für einen Anlass, etwa die nächste Arbeit. Dieses Repo ist der Weg zum Üben. Der KI-Assistent eines Creators macht aus Fotos von Schulmaterial eine App zum Üben nach Maß (Archetyp `explainer`). Der Creator reicht sie als ZIP-Datei über ein Issue-Formular ein. Ein Workflow veröffentlicht sie unter `https://lernapps.net/practice/i/<Issue-Nummer>/` und räumt sie nach 14 Tagen ab.
+
+Das Repo enthält keine Apps und keine Laufzeit. Die Vorlagen kommen aus [lernapps/app-templates](https://github.com/lernapps/app-templates), die Regeln und Prüfungen aus [lernapps/tooling](https://github.com/lernapps/tooling).
+
+## Einstieg
+
+- **Für Creator:** <https://lernapps.net/practice/>, Quelle in [docs/index.md](docs/index.md) und [docs/en/index.md](docs/en/index.md).
+- **Für KI-Assistenten:** [docs/llms.txt](docs/llms.txt). Sie führt zur Plan-Vorlage [guidance/plan-template.md](guidance/plan-template.md) und zu den Skills in `skills/`.
+- **Einreichung und Vorschau:** `.github/workflows/` und die Composite-Actions in `actions/`.
+- **Betrieb:** [docs/operations.md](docs/operations.md). **Architektur:** [docs/arc42/](docs/arc42/). **Bewertung der Anleitung:** [docs/evaluation.md](docs/evaluation.md).
+
+## Mitarbeiten
+
+- `npm test`: alle Tests (Node 22.18 oder neuer).
+- `npm ci && npm run build && npm run check`: die Seite bauen und prüfen.
+- `npm run try -- <zip>`: eine ZIP-Datei lokal prüfen und bauen.
+
+`AGENTS.md` nennt die Regeln für Assistenten.
+
+## Lizenz
+
+MIT, siehe [LICENSE](LICENSE).

package/bin/lernapps-practice.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// `lernapps-practice init <short name>`: starts an app for an occasion, from the npm registry alone. It is the init of
+// @lernapps/tooling with this package as its add-on: the plan template of lernapps practice instead of the tooling's,
+// and its skills next to those of the tooling. The tooling is a dependency of this package, so it is installed already
+// when `npx --yes @lernapps/practice init <short name>` runs; nothing else is downloaded.
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const USAGE = `Usage: lernapps-practice init <short name>
+
+Starts an app for an occasion in the current folder, which must be empty except for .git: the plan template of lernapps
+practice as .vibe/plans/01-<short name>.md, and the skills of lernapps practice and of the tooling. Then follow the plan.
+Every other command is one of lernapps, the CLI of @lernapps/tooling (npx lernapps --help), in the app that init made.
+`;
+
+const [command, ...rest] = process.argv.slice(2);
+if (command === "-h" || command === "--help") {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+if (command !== "init" || rest.length !== 1) {
+  process.stderr.write(`lernapps-practice: ${command === undefined ? "no command given" : `unknown command or arguments: ${[command, ...rest].join(" ")}`}\n\n${USAGE}`);
+  process.exit(2);
+}
+const manifest = createRequire(import.meta.url).resolve("@lernapps/tooling/package.json");
+const bin = JSON.parse(readFileSync(manifest, "utf8")).bin?.lernapps ?? "dist/cli.mjs";
+const result = spawnSync(process.execPath, [join(dirname(manifest), bin), "init", rest[0], "--addon", "@lernapps/practice"], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/dist/skills/lernapps-practice-explore/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: lernapps-practice-explore
+description: Use in Explore of a lernapps practice plan when someone needs a learning app for an occasion - a class test, a cover lesson, finding out where a class stands, missed work - even if they only say "Klassenarbeit", "Vertretung" or "für die Arbeit üben". Ask once what only the creator knows, search the catalog, say what the preview means for privacy, set the scope from the material and stick to it, then move on to Plan without asking.
+license: MIT
+---
+
+# Anlass, Katalog und Umfang
+
+## Wann benutzen
+
+- Explore des Plans aus der Plan-Vorlage von lernapps practice (`.vibe/plans/01-<anlass>.md`). Der Plan sagt, wann Du
+  diesen Skill lädst und wann Du wartest.
+- Das Ergebnis: Anlass, Lernende und der Umfang aus dem Material, unter „Answers“ und „Notes“ des Plans.
+
+## Der Creator hat wenig Zeit
+
+Eltern haben keine Zeit für viele Rückfragen. Frage nur, was nur der Creator weiß, in einer Nachricht:
+
+- wofür die App gebraucht wird (der Anlass),
+- Fach, Klassenstufe (1 bis 13), Bundesland; bei Religion die Konfession, denn Zählweisen (Bücher der Bibel, Gebote)
+  hängen davon ab,
+- nach dem Material (Fotos von Arbeitsblättern, Buchseiten, Selbsttests).
+
+Sage in derselben Nachricht, was der Creator vorher wissen muss:
+
+- Die App ist zwei Wochen lang öffentlich erreichbar, unter einer Adresse mit Nummer. Das Issue, in dem sie
+  eingereicht wird, ist ebenfalls öffentlich.
+- Namen, Schule, Klasse, Lehrkraft und die Handschrift des Kindes kommen nicht in die App.
+- Am meisten hilft die App, wenn das Kind vorher selbst sein Material durchsieht. Das ist ein Tipp; Du wartest nicht
+  darauf.
+
+Frage nicht nach Lehrwerk oder Verlag und nenne beides nirgends. Gewichtung, Abbildungen und Aufgabenformen
+entscheidest Du im Plan selbst.
+
+## Den Katalog durchsuchen
+
+Lies den Katalog vollständig: https://lernapps.net/apps/llms.txt (mit curl laden, dann lesen). Suche nach Fach, Stufe
+und Thema. Passt eine App zum Anlass, nenne den Link und frage, ob sie reicht. Reicht sie, endet der Plan.
+
+## Beim Umfang bleiben
+
+Der Umfang ist das Material des Creators: seine Themen, seine Begriffe, seine Aufgaben. Recherchiere nur, um diesen
+Stoff zu erklären und Fakten zu prüfen, nie, um weiteren Stoff oder weitere Fragen zu finden. Das hält die App
+fokussiert, und das Kind übt genau das, was in der Arbeit drankommt.
+
+## Weiter zum Plan
+
+Steht der Umfang, gehst Du ohne Rückfrage in den Plan. Sage dem Creator in einem Satz, dass Du jetzt den Vorschlag
+für die App vorbereitest.
+
+## Typische Stolpersteine
+
+- Der Anlass fehlt, und die App wird zu breit. Frage ihn zuerst, auch wenn schon Fotos da sind.
+- Eine fertige App im Katalog passt fast. Nenne sie trotzdem; der Creator entscheidet.
+- Eine Quelle bringt interessanten Stoff, der nicht im Material steht. Lass ihn weg.

package/dist/skills/lernapps-practice-photos/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: lernapps-practice-photos
+description: Use in Explore of a lernapps practice plan when you read photos of school material (worksheets, book pages, self-tests), and in Code when you redraw its figures for the explainer. How to order and divide the pages, how to treat highlighted boxes, cut-off margins and the child's handwriting, which block a task of the material becomes, and how to rebuild a figure with the same content and labels as a generated image or an SVG drawing.
+license: MIT
+---
+
+# Fotos von Schulmaterial lesen und Abbildungen nachbauen
+
+## Wann benutzen
+
+- In Explore: Du bekommst Fotos von Arbeitsblättern, Buchseiten oder Selbsttests und leitest daraus die Themen und eine
+  Seitenliste ab. Lies erst alle Fotos, schreibe erst danach die Seitenliste.
+- In Code: Du baust die Abbildungen des Materials für die App nach.
+- Schreibe keinen Text der Fotos ab. Du schreibst eigene Texte und Aufgaben zu denselben Themen.
+- Die Fotos kommen nie in die App, nie in das Repo und nie in die ZIP-Datei, auch keine Ausschnitte. Beschreibungen
+  des Materials kommen nicht in den Plan.
+
+## Fotos lesen
+
+### Reihenfolge
+
+- Die Reihenfolge ist die der Dateinamen oder der Aufnahmezeit, nicht die der Nachricht. Lies erst alle Fotos, dann
+  schreibe die Seitenliste.
+
+### Seiten gliedern
+
+- Gliedere jede Seite: Titel, Spalten, Text, Abbildungen, Aufgaben. Kennzeichne hervorgehobene Kästen (Info, Merke,
+  nummerierte Kurztexte), damit sie in der App wieder als Kasten erscheinen.
+- Notiere jede Abbildung mit ihrem Inhalt: was sie zeigt, ihre Beschriftungen, Zahlen und die Anordnung.
+
+### Ränder
+
+- Am Rand hereinragende Nachbarseiten sind abgeschnitten. Nimm nur die Hauptseite.
+
+### Handschrift des Kindes
+
+- Kreuze, Durchstreichungen, Zahlen und ausgefüllte Felder stammen vom Kind und können falsch sein. Leite Lösungen aus
+  den Fakten ab.
+- Hängt eine Lösung an der Vorlage selbst (welcher Buchstabe welcher Teil ist, welches Feld wohin gehört) und lässt sie
+  sich nicht sicher ablesen, frage den Creator in Explore. Buchstaben, Nummern und Beschriftungen des Materials änderst
+  Du nie: Das Kind übt für dieselbe Vorlage.
+
+### Aufgaben des Materials
+
+- Welche Aufgabe des Materials welcher Block wird: [references/aufgabentypen.md](references/aufgabentypen.md).
+
+## Abbildungen nachbauen
+
+Eine Abbildung des Materials baust Du inhaltsgleich nach: dieselben Teile, dieselbe Anordnung, dieselben
+Beschriftungen und Zahlen. Nur die Gestaltung ist Deine.
+
+1. **Kannst Du Bilder erzeugen,** erzeuge die Abbildung neu, nach Deiner Beschreibung des Inhalts, nicht nach dem
+   Foto als Vorlage. Speichere sie als `.png`, `.jpg` oder `.webp`.
+2. **Sonst zeichne sie schematisch als SVG** von Hand: Formen, Linien, Pfeile, Text mit `<text>`. Ein SVG darf nur
+   zeichnen: kein `<script>`, kein `on…=`, kein `<foreignObject>`, kein `<iframe>`, `<embed>` oder `<object>`, kein
+   `javascript:`, kein Verweis nach außen (`href` und `url(…)` nur auf `#…` in derselben Datei), kein `@import`, kein
+   `<!ENTITY`. Sonst lehnt die Einreichung das Bild ab.
+3. **Ablage:** `src/images/<name>.svg` (oder `.png`, `.jpg`, `.webp`), der Name aus Kleinbuchstaben, Ziffern und
+   Bindestrichen.
+4. **Block:** `figure` mit `image`, `alt`, `caption`, `source` und `licence`; mit nummerierten Markern
+   `labelled-figure` (`labels` mit `x`, `y` in Prozent und `text`). Wie, sagt der Skill `lernapps-explainer`.
+   - `source`: `eigene Zeichnung` für ein SVG von Hand, `KI-generiert` für ein erzeugtes Bild.
+   - `licence`: `CC-BY-4.0`, die Lizenz der Einreichung.
+   - `alt` beschreibt den Inhalt so, dass er ohne Bild verständlich ist; die Beschriftungen gehören dazu.
+5. Prüfe am Ende jede Abbildung einzeln in voller Größe, nicht im Screenshot der ganzen Seite: Stimmen alle
+   Beschriftungen und Zahlen mit dem Material überein? Fehlt ein Teil? Passt jeder Buchstabe zu Form und Ort seines
+   Teils, zeigt jede Linie auf das Richtige? Nennen Abbildung, `alt` und Text dieselben Fakten? Ändert sich eine
+   Zuordnung, prüfe die Zeichnung erneut.
+
+## Typische Stolpersteine
+
+- Ein Selbsttest sieht oft wie die Fortsetzung der Seite davor aus, ist aber ein eigenes Blatt. Darum erst alle Fotos
+  lesen, dann gliedern.
+- Seiten liegen übereinander und Nachbarseiten schauen heraus: Randtext ist abgeschnitten und nicht verlässlich.
+- Kinderschrift steht mitten in der Vorlage (Kreuze im Selbsttest, Zahlen an Diagrammen, ausgefüllte Tabellen, Datum
+  am Rand). Übernimm nichts davon, auch nicht in eine Abbildung. Sind im Selbsttest mehrere Kreuze falsch oder
+  durchgestrichen, lässt sich daraus keine Lösung ablesen. Leite sie aus den Fakten ab.
+- Zählweisen unterscheiden sich (nach Konfession, Bundesland, Lehrwerk). Eine Zahl auf dem Foto ist eine Zählung, nicht
+  das einzige richtige Ergebnis. Schreibe dann beide Zählungen mit dem Hinweis auf die Zählung.
+- Eine Abbildung mit Beschriftungen zum Eintragen („Beschrifte A bis E“): eine `labelled-figure` mit den Buchstaben
+  des Materials als `marker` und `legend: false`, die Zeichnung selbst ohne Buchstaben; dazu ein `matching` mit
+  `pairsFrom: material`. So stehen Buchstaben und Bezeichnungen nur einmal da, und die Lösung steht nicht daneben.
+- Hervorgehobene Kästen früh erkennen (Info-Kasten, nummerierte Kurztexte, Kästen mit Buchstaben). Jeder bekommt einen
+  eigenen Block (`note`), damit er auf der Seite wieder sichtbar ist.
+- Die Bildanalyse und das Schreiben der Seitenliste dauern lange, wenn Seiten dicht sind. Plane Zeit ein.

package/dist/skills/lernapps-practice-photos/references/aufgabentypen.md

@@ -0,0 +1,20 @@
+# Welcher Block für welche Aufgabe des Materials
+
+| Aufgabe im Material | Block im Explainer |
+|---|---|
+| Kreuze die richtige Antwort an (eine) | `single-choice` |
+| Mehrere Antworten können richtig sein | `multiple-choice` (mindestens eine richtige Option) |
+| Ordne Bezeichnungen den Kurzbeschreibungen zu | `matching` mit `pairs` (2 bis 8 Paare) |
+| Bringe in die richtige Reihenfolge | `ordering` mit `items` (2 bis 8) |
+| Wie viele …? | `number` mit `answer`, `tolerance`, `mistakes` (je mit `answer` und `message`) |
+| Stimmt die Aussage? | `true-false` mit `answer` |
+| Rechne aus (mit neuen Zahlen je Versuch) | `generated` (Skill `lernapps-explainer`) |
+| Beschreibe, erkläre, vergleiche, begründe; schreibe einen Text (offen) | `open-task`: Aufgabe, 2 bis 5 Punkte einer guten Antwort, jeder Punkt des Inhalts mit seiner `source` (der Abschnitt, in dem er steht), Punkte der Form mit `kind: form`, Musterlösung als `solution` (Skill `lernapps-explainer`). Das Kind schreibt erst selbst, auch auf Papier mit Foto, dann vergleicht es |
+| Beschrifte den Plan mit A bis E | `labelled-figure` mit den Buchstaben als Marker und `matching` der Bezeichnungen |
+| Info-Kasten des Materials | `note` mit Titel „Info: …“ |
+| Fachwort mit Erklärung | `definition` (kommt ins Glossar) |
+| Tabelle, Datumsliste | `table` |
+| Zeitleiste | `timeline` mit `events` (`date` als Jahr, `label` für die Anzeige) |
+| Zeichnung, Kreisdiagramm, Plan | nachgebaute Abbildung als `figure` (siehe „Abbildungen nachbauen“) und eine Aufgabe dazu |
+| Etwas einzeichnen, verschieben, ablesen | eine Komponente, nur wenn kein Block passt (Skill `lernapps-explainer`, Komponenten) |
+| Selbsttest des Materials | `selfAssessment` im Kapitel (Skill `lernapps-explainer-self-assessment`): Aufgaben der Seiten, das Ergebnis je Seite |

package/dist/skills/lernapps-practice-plan/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: lernapps-practice-plan
+description: Use in Plan of a lernapps practice plan when the occasion and the scope of the material are clear - decide the app yourself and propose it to the creator for one yes, briefly and with your guesses highlighted - pages that explain before they practise, a self-assessment, figures, richer and interactive forms beyond choice and true-false.
+license: MIT
+---
+
+# Die App vorschlagen
+
+## Wann benutzen
+
+- Plan des Plans aus der Plan-Vorlage von lernapps practice (`.vibe/plans/01-<anlass>.md`), wenn Anlass und Umfang
+  aus Explore feststehen.
+- Das Ergebnis ist ein Vorschlag, dem der Creator mit einem Ja zustimmt. Er steht unter „Key decisions“ und in den
+  Aufgaben von Code.
+
+## Ein Vorschlag, kurz
+
+Eltern haben keine Zeit für Rückfragen. Entscheide selbst und lege einen Vorschlag vor, den der Creator in einem Zug
+liest. Nicht Seite für Seite: Hebe hervor, was besonders ist, kurz und gegliedert, zum Beispiel:
+
+- der Schwerpunkt und warum,
+- was die App erklärt, bevor das Kind übt,
+- die reicheren Formen und die nachgebauten Abbildungen,
+- Deine Vermutungen, sichtbar markiert („(Vorschlag)“), damit der Creator sie mit einem Blick findet,
+- die Fakten, die er prüfen sollte.
+
+Bleib beim Umfang aus Explore. Was nicht im Material steht, kommt nicht hinzu.
+
+## Erst erklären, dann üben
+
+Die App vermittelt den Stoff und prüft ihn dann. Jede Themenseite erklärt zuerst: herleiten, ein Beispiel, eine
+Abbildung, wo sie hilft. Danach kommen die Aufgaben zu genau dem, was die Seite erklärt hat. Nur die
+Selbsteinschätzung prüft ohne zu erklären.
+
+| Anlass | Seiten |
+| --- | --- |
+| Eine Arbeit steht an | Selbsteinschätzung zuerst, dann je Thema eine Seite; die Themen mit viel Raum im Material oder vielen Fehlern im Selbsttest ausführlicher |
+| Eine Vertretungsstunde | wenige Seiten in der Reihenfolge der Stunde; eine Seite zum Abschluss |
+| Den Stand einer Klasse feststellen | Fragen quer durch den Stoff mit Auswertung zuerst, dann je Thema eine Seite zum Nacharbeiten |
+| Verpasster Stoff | je Thema eine Seite in der Reihenfolge des Unterrichts |
+
+- **Selbsteinschätzung:** die Selbsteinschätzung des Explainers (`selfAssessment`, Skill
+  `lernapps-explainer-self-assessment`): Aufgaben quer durch den Stoff, und am Ende sagt sie je Seite, ob das Kind sie
+  schon kann oder noch einmal ansehen sollte.
+- Keine Seite nur mit Plan, Etappen oder Inhaltsverzeichnis: Die App hat ihre Navigation schon, und eine Aufgabe
+  dazu prüft nichts vom Stoff.
+
+Sage dem Creator dabei: Die App speichert nichts über die Lernenden außerhalb ihres Browsers. Antworten zählt die
+Seite nur, solange sie offen ist; eine offene Antwort bleibt, bis der Tab geschlossen wird. Auf einem anderen Gerät
+beginnt man von vorn.
+
+## Reichere Formen vorschlagen
+
+Über Auswahl und Wahr-oder-falsch hinaus ist viel möglich. Wähle selbst, was zu diesem Material passt, und schlage es
+mit einer groben Skizze vor: was das Kind tut und was ihm das bringt.
+
+Reichhaltige Blöcke des Explainers (wie, sagt der Skill `lernapps-explainer`):
+
+- `labelled-figure` mit den Buchstaben des Materials als `marker` und `legend: false`; dazu ein `matching` mit
+  `pairsFrom: material`: Das Kind beschriftet die Abbildung.
+- `matching` mit `distractors`: Zuordnen, bei dem nicht alles aufgeht.
+- `ordering` und `timeline`: Ereignisse, Schritte, Feste in ihre Reihenfolge bringen.
+- `generated`: Aufgaben, die bei jedem Durchgang neu sind.
+- `number` mit `mistakes`: Rückmeldung genau auf den typischen Fehler.
+- `open-task`: Das Kind antwortet in eigenen Worten, getippt oder auf Papier mit Foto, und vergleicht dann mit den
+  Punkten einer guten Antwort. Schlage sie vor, wo das Material beschreiben, erklären, vergleichen oder einen eigenen
+  Text verlangt, besonders in Deutsch, Fremdsprachen und Fächern wie Religion; nicht für das, was eine Auswahl
+  prüfen kann. Mit oder ohne Tutor.
+- `video` und `figure`: zeigen, was ein Text nur beschreibt.
+- `vue-component`: alles, wofür kein Block passt.
+
+Ideen zum Weiterdenken: auf eine Abbildung, eine Karte oder einen Kreis ziehen; Fehler in einem Text finden; in
+Gruppen sortieren; erst schätzen, dann prüfen; eine kleine Geschichte mit Entscheidungen; eine Simulation, an der das
+Kind dreht.
+
+## Typische Stolpersteine
+
+- Eine Seite beginnt mit Aufgaben. Dann rät das Kind, statt zu lernen. Erst erklären, dann üben.
+- Du fragst nach Gewichtung oder Aufgabenformen. Schlage sie vor; der Creator ändert, was ihm nicht passt.
+- Der Vorschlag beschreibt jede Seite. Der Creator liest ihn dann nicht. Nenne das Besondere.
+- Fragen zu Stoff, der nicht im Material steht. Die App wird breit und unscharf. Bleib beim Umfang.

package/dist/skills/lernapps-practice-submit/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: lernapps-practice-submit
+description: Use in Commit of a lernapps practice plan when the explainer builds and checks locally and the creator should submit it - show the creator every page and go through the declarations, make the ZIP file of src/ (pages, data, images, components), give the link to the form of lernapps/practice, explain the declarations, read the bot's answer, correct and resubmit, and tell the creator about the two weeks and the thumbs-up.
+license: MIT
+---
+
+# Einreichen über lernapps practice
+
+## Wann benutzen
+
+- Commit des Plans aus der Plan-Vorlage von lernapps practice. `npm run build` und `npm run check` sind grün.
+- Die App kommt nicht über ein eigenes Repo ins Netz: Der Creator reicht den Ordner `src/` als ZIP-Datei in einem Issue
+  von `lernapps/practice` ein. GitHub prüft und baut ihn und kommentiert die Adresse. Kein Push, kein Listing.
+
+## Alle Seiten zeigen
+
+Der Creator bestätigt im Formular, dass der Inhalt selbst erstellt ist, keine persönlichen Daten enthält und zwei
+Wochen öffentlich sein darf. Das kann er nur, wenn er jede Seite gesehen hat. Zeige sie ihm vor der ZIP-Datei, nach
+`npm run build`, auf dem besten Weg, den Deine Umgebung erlaubt:
+
+1. Läufst Du auf dem Rechner des Creators: Starte die App mit `npm run dev` und gib ihm die Adresse.
+2. Sonst Bilder aller Seiten mit `npx lernapps screenshots`, wie der Skill `lernapps-cli` sagt. Zeige die Übersicht
+   `screenshots/index.html`, wo Du HTML zeigen kannst, sonst die Bilder der Reihe nach. Der Ordner kommt nicht in die
+   ZIP-Datei.
+
+Dann geh mit ihm die drei Erklärungen durch, in einfachen Worten:
+
+- Texte und Abbildungen sind neu geschrieben und gezeichnet, nichts aus dem Buch oder vom Arbeitsblatt abgeschrieben,
+  keine Fotos.
+- Keine Namen, keine Schule, keine Klasse, keine Lehrkraft, keine Handschrift.
+- Er ist einverstanden, dass die App zwei Wochen öffentlich ist.
+
+Nenne, worauf er besonders schauen soll: die nachgebauten Abbildungen, die Fakten, die er prüfen sollte, die Punkte
+der offenen Aufgaben und den Scope (`scope:` in jeder Seite und in `src/app.yaml`: stimmt, was die Seiten lehren und was nicht dazugehört?). Erst nach
+seinem Ja geht es weiter.
+
+## ZIP-Datei erzeugen
+
+Im Ordner der App, nachdem alles committet ist:
+
+```sh
+git archive --format=zip --output=../<anlass>.zip HEAD src
+```
+
+- Oben in der ZIP-Datei steht `src/` mit `app.yaml`, den Kapiteln, `data/`, `images/` und `components/`. `src/main.ts`
+  darf darin stehen; die Einreichung ignoriert es und nimmt das der Vorlage.
+- Erlaubt: `.yaml`, `.yml`, `.md`, `.png`, `.jpg`, `.webp`; `.svg` nur in `src/images/`; `.vue` und `.ts` nur in
+  `src/components/` (`<Name>.vue`, `<Name>.ts`, `<Name>.test.ts`). Höchstens 300 Dateien und 10 MB.
+- Keine Fotos des Materials, keine Namen.
+- Die Regeln: https://lernapps.net/practice/rules/
+
+## Einreichen
+
+Erkläre ohne Fachwörter:
+
+1. Die Eltern brauchen ein kostenloses GitHub-Konto (https://github.com/signup), nur mit E-Mail-Adresse. Kinder unter
+   13 dürfen keins haben, deshalb legen es die Eltern an.
+2. Gib den Link zum Formular:
+   `https://github.com/lernapps/practice/issues/new?template=submit.yml&subject=<Fach>&grade=<Zahl>&federalState=<Name>`
+   (Leerzeichen und Umlaute URL-kodiert).
+3. Die ZIP-Datei in das Feld „ZIP-Datei“ ziehen, warten, bis ein Link erscheint, die drei Erklärungen anhaken (selbst
+   erstellt, keine persönlichen Daten, zwei Wochen veröffentlichen), absenden.
+4. Veröffentlicht wird unter CC BY 4.0, die Eltern sind Urheber. Das bestätigen sie im Formular.
+
+## Antwort und Korrektur
+
+- Nach einigen Minuten kommentiert ein Bot das Issue. Bitte den Creator, Dir den Kommentar zu geben.
+- Nennt er Probleme (Datei, Zeile, Regel): Korrigiere `src/`, prüfe mit `npm run build` und `npm run check`, committe,
+  erzeuge eine neue ZIP-Datei. Die Eltern hängen sie als Kommentar an das Issue an (ins Kommentarfeld ziehen, auf den
+  Link warten, „Comment“). GitHub prüft und baut dann neu; es zählt die zuletzt angehängte ZIP-Datei.
+- Nennt er die Adresse (`https://lernapps.net/practice/i/<Nummer>/`): Öffne sie und prüfe, dass die App erscheint.
+- Wünscht der Creator danach eine Änderung: wie bei Problemen. Die Vorschau zeigt sie erst nach dem neuen Kommentar des
+  Bots; prüfe sie dort, bevor Du sie als erledigt meldest.
+
+## Danach
+
+Sage ehrlich:
+
+- Das ist eine Vorschau. Sie wird nach zwei Wochen gelöscht.
+- Hat sie geholfen, soll jemand eine 👍-Reaktion auf das erste Feld des Issues setzen. Dann bleibt sie erhalten und
+  wird für den Katalog geprüft. Dieses Feedback hilft auch anderen, die vor demselben Stoff stehen.
+- Die App speichert nichts über die Lernenden. Die Selbsteinschätzung zählen sie selbst.
+- Die App erklärt den Stoff Schritt für Schritt und prüft dann, was sitzt. Am meisten hilft sie, wenn das Kind vorher
+  selbst sein Material durchgesehen hat.
+
+## Typische Stolpersteine
+
+- Eine ZIP-Datei aus dem Ordner über `src/` (mit `node_modules/`) ist zu groß. Packe nur `src/`.
+- Ein SVG-Bild mit Skript, Ereignis-Attribut oder Verweis nach außen wird abgelehnt. Zeichne es ohne.
+- Eine Datei, die nicht committet ist, fehlt in `git archive`. Committe vorher.

package/guidance/plan-template.md

@@ -0,0 +1,216 @@
+---
+# Read by the hooks, the review, the evals. Schema: @lernapps/tooling/guidance/plan-front-matter.v1.schema.json
+# Keep all four keys.
+# Archetype, null until Explore ends; then explainer, the only archetype of lernapps practice. Never another value.
+archetype: null
+# Current phase. Allowed values: explore, plan, code, commit. Change the value line below, never this comment.
+phase: explore
+# prePushFailures: written by the pre-push hook. Never change it.
+prePushFailures: 0
+# failedChecks: failed rules and runs, written by lernapps check and the hooks. Never change it.
+failedChecks: {}
+---
+
+# Plan: <occasion>, a learning app through lernapps practice
+
+<!--
+For you, the assistant. lernapps practice: the creator has an occasion (a class test, a cover lesson, …) and no app
+of the catalog fits. You make a small explainer for it on this computer; the creator submits its src/ as a ZIP file
+in an issue of lernapps/practice, and GitHub serves it for two weeks at https://lernapps.net/practice/i/<number>/.
+1. Path: `.vibe/plans/01-<occasion>.md`, in a new, empty folder. A correction after the submission is no new plan:
+   it is a task of Commit.
+2. Read this plan before each step. One phase at a time, tasks in order.
+3. Task done → tick `[x]` at once and move it to "Completed" of its phase. An unticked box counts as not done.
+4. New task found → add it.
+5. Each phase names its skills. They are in `.agents/skills/` (`init` put them there); load a skill when its task
+   comes, not before. Read it in full, from its file. Install no other skill: this app is not published through GitHub
+   and not listed.
+6. Checkpoint: stop, ask, wait for the creator's answer. A message sent before the question is no yes.
+   Only a checkpoint waits. A phase's last box → set the next phase and go on in the same message.
+7. At most 2 questions per message, one topic each. No questions inside drafts or lists.
+8. Work locally, in this folder. Push nothing, create no repository, list nothing: the submission is the ZIP file.
+9. Plan in the creator's language. Keep headings and front matter keys. Delete a comment once its part is filled.
+10. Begin each reply to the creator with the phase in `phase:`, and at a checkpoint the word checkpoint:
+    "**Plan · Checkpoint**", "**Code**". The creator always knows where you are.
+11. You need a shell with Node 22.18 or newer, git and the network (registry.npmjs.org). Blocked → ask the creator to
+    allow it, then run again.
+-->
+
+*Explore, Plan, Code, Commit.*
+
+## Goal
+
+<!-- 1–2 sentences: the occasion, who learns, what they can do afterwards. -->
+
+## Key decisions
+
+<!-- One line each: decision and reason. Archetype explainer first (lernapps practice). Scope and weighting from
+the occasion. Your own choice without the creator: mark "(Vorschlag)". -->
+
+## Notes
+
+<!-- Occasion, subject, school year, Land; the topics from the material; facts to check and their sources; scope;
+open questions. Never the material itself, never a name. -->
+
+## Explore
+
+<!--
+- Find out the occasion, whether an app exists and what the material holds: that is the scope. Ask only what only the
+  creator knows, in one message; decide the rest yourself and propose it in Plan.
+- Stick to the scope: research only to explain the material and to check facts, never to find more to ask.
+- Write no code, run no `create`.
+- An answer counts only in the creator's words under "Answers". What you decided is a proposal, marked "(Vorschlag)".
+- Skills: `lernapps-practice-explore`, `lernapps-practice-photos`, `lernapps-content-research`.
+-->
+
+### Tasks
+
+- [ ] The skills of the phases are in `.agents/skills/` (`npx --yes @lernapps/practice init <short name>` put them
+      there and wrote this plan). `.agents/skills/lernapps-practice-explore` missing → stop and tell the creator the
+      folder was not started with `init`.
+- [ ] Load skill `lernapps-practice-explore`. In one message, as it says: ask the occasion, subject, school year,
+      Land and the material; say what the creator must know before. Wait for the answer.
+- [ ] Search the catalog as the skill says. An app fits → give the creator its link and ask whether it is enough;
+      yes → the plan ends here.
+- [ ] Load skill `lernapps-practice-photos`. Read the material as it says. Under "Notes": the topics, page by page;
+      each figure of the material and how you redraw it.
+- [ ] Load skill `lernapps-content-research`. Every fact you are not sure of (numbers, dates, names, ways of
+      counting): a source you opened, under "Notes". Open it now, not later. Only what no source you opened settles
+      goes to the creator to check. Research only what explains the material; nothing beyond it.
+- [ ] Write the answers under "Answers" and the scope under "Notes": the topics of the material, nothing else.
+- [ ] Set `archetype: explainer` and `phase: plan`: change the value lines (`grep -E '^(archetype|phase):'` prints
+      `archetype: explainer` and `phase: plan`). Tell the creator in one sentence that you now prepare the proposal;
+      do not ask. Go on in the same message.
+
+### Answers
+
+<!-- The creator's answers, in their words. Keep the topics. -->
+
+- Occasion: what is coming (a class test, a cover lesson, the state of a class, missed work), for whom.
+- Learners: subject, school year, Land; for religion the denomination.
+- Material: what the creator gives (photos of worksheets, book pages, a self-test) and what of it counts.
+- Changes: what the creator changed in your proposal.
+
+### Completed
+
+## Plan
+
+<!--
+- Decide the app and map it onto the explainer: chapters, pages, blocks, exercises, figures, components.
+- No new questions. A gap → decide and mark it "(Vorschlag)". Stay within the scope of Explore.
+- One proposal, confirmable in one read; the only checkpoint before the app is built. After the yes, work on your
+  own until Commit.
+- Skills: `lernapps-practice-plan`, `lernapps-exercise-patterns`, `lernapps-explainer-design`; and
+  `lernapps-content-research`, loaded in Explore; reread it if it is no longer in view.
+-->
+
+### Tasks
+
+- [ ] `grep '^phase:'` prints `phase: plan`; else set it.
+- [ ] Install the skills of the archetype: `npx lernapps skills --archetype explainer`.
+- [ ] Load skills `lernapps-practice-plan`, `lernapps-exercise-patterns` and `lernapps-explainer-design`. Map the
+      content as skill `lernapps-explainer-design` says: chapters and pages, with the pages skill
+      `lernapps-practice-plan` names for the occasion.
+- [ ] Choose a pattern per topic as skill `lernapps-exercise-patterns` says. Write "Content method".
+- [ ] Each figure: what it shows, its labels as in the material, how you make it (generated image or SVG drawing,
+      as skill `lernapps-practice-photos` says). Each component: what it shows and checks, and why no block fits.
+- [ ] Choose richer, interactive forms for this material, as skill `lernapps-practice-plan` says, and sketch them
+      roughly.
+- [ ] Fill "Goal" and "Key decisions": the occasion and what learners can do afterwards; each decision with its
+      reason, your own choices marked "(Vorschlag)".
+- [ ] The facts to check: each with its source (skill `lernapps-content-research`), or marked for the creator.
+- [ ] Write the Code tasks under "Code": one per page or component, with its content and exercises.
+- [ ] **Checkpoint:** proposal. Brief and structured, as skill `lernapps-practice-plan` says: only what is special
+      or conceptual, not page by page; your guesses ("(Vorschlag)") highlighted; the facts the creator should check.
+      Ask for one yes or for changes. Stop and wait. Changes → change, write them under "Answers", show
+      only what changed. No `create` before the yes.
+- [ ] Set `phase: code`: change the value line (`grep '^phase:'` prints `phase: code`).
+
+### Content method
+
+<!-- One line each: exercise patterns and where; figures and how they are made; data files; each component, what it
+checks and cannot. Becomes the content guide in Code. -->
+
+### Completed
+
+## Code
+
+<!--
+- Build the app from the explainer and the confirmed plan, in this folder. Work on your own.
+- A check fails → skill `lernapps-cli`. Fix from the message; never bypass a check.
+- Undecidable → choose, mark "(Vorschlag)" under "Key decisions", go on.
+- Creator asks for a change → first say your reading in one sentence; never narrow it silently.
+- Skills: `lernapps-cli`, `lernapps-explainer`, `lernapps-content-questions`, `lernapps-practice-photos` (the
+  figures), and the app's content guide `app-content`.
+-->
+
+### Tasks
+
+- [ ] `grep '^phase:'` prints `phase: code`; else set it.
+- [ ] Load skill `lernapps-cli`. Create the app in this folder as it says, with
+      `npx lernapps create --archetype explainer`; then `git init`, `npm install`, the
+      first commit. `create` keeps this plan and the skills. Never write the app by hand.
+- [ ] Fill the content guide `.agents/skills/app-content/SKILL.md` from "Notes" and "Content method". Add under
+      "Rules learned from mistakes" the line: "Diese App wird über lernapps/practice eingereicht: eine Änderung ist
+      ein neues ZIP im Issue; kein Push, kein Listing." `grep -c "FILL IN" .agents/skills/app-content/SKILL.md`
+      prints 0.
+- [ ] Load skill `lernapps-explainer` and the content guide. Questions with options and feedback: also skill
+      `lernapps-content-questions`.
+- [ ] Replace the example chapter "Prozent" and the example component `ProzentFeld` with the planned content.
+- [ ] <the tasks written in Plan; each: write it in `src/`, then `npm run build`>
+- [ ] The figures: as skill `lernapps-practice-photos` says, in `src/images/`, with `source` and `licence`.
+- [ ] The scope, once the pages stand: `scope:` in each page, what it teaches from the material in your own words, as
+      prose; and `scope: { text, out }` in `src/app.yaml`, what the app is about and what does not belong to it (skill
+      `lernapps-explainer`, `runtime.md`). The tutor judges open answers by it. `npm run build` checks it.
+- [ ] `npm run build` and `npm run check` pass.
+- [ ] The content guide matches what was built.
+- [ ] Every box of Explore, Plan and Code ticked.
+- [ ] Set `phase: commit`: change the value line (`grep '^phase:'` prints `phase: commit`).
+      No checkpoint here: set it before you ask or report anything, then start Commit in the same message.
+
+### Completed
+
+## Commit
+
+<!--
+- Hand the app over: the creator submits the ZIP file of `src/` through the form of lernapps/practice. GitHub checks
+  it, builds it and comments the address.
+- Skill: `lernapps-practice-submit`.
+-->
+
+### Tasks
+
+- [ ] `grep '^phase:'` prints `phase: commit`; else set it.
+- [ ] Load skill `lernapps-practice-submit`. Show the creator every page of the built app as it says.
+- [ ] **Checkpoint:** pages, and the declarations. The creator has seen every page; highlight what you decided in Code
+      ("(Vorschlag)" under "Key decisions"); go through the three declarations of the form with them, as the skill
+      says. Stop and wait for a yes. Changes → change, build, check,
+      show the changed pages again.
+- [ ] Make the ZIP file of `src/` as the skill says.
+- [ ] **Checkpoint:** submit. Give the creator the ZIP file and the link to the form as the skill says; wait for the
+      bot's comment.
+- [ ] The comment names problems → correct them in `src/`, `npm run build` and `npm run check`, a new ZIP file; the
+      creator attaches it as a comment of the issue. Repeat until the comment gives the address.
+- [ ] The creator asks for a change after the address → add a task here; change, build, check and attach as above.
+      Done only when the bot's new comment is there and the preview shows the change.
+- [ ] **Checkpoint:** address. The comment gives the address: open it, confirm the app shows, give the creator the
+      address and what the skill says about two weeks and the 👍.
+- [ ] Fill the retrospective.
+
+### Completed
+
+## Retrospective
+
+<!-- At the end of Commit. Facts, short, no names. Read by review and evals. -->
+
+### Phases reached
+
+<!-- Last phase completed, checkpoints passed. E.g. "commit; submitted, address received". -->
+
+### Creator turns after the plan
+
+<!-- Number of creator messages after the confirmation, topic of each. -->
+
+### Where I had to guess
+
+<!-- Each gap in plan, skills, messages or answers, and your choice. "None" if none. -->

package/package.json

@@ -1,8 +1,48 @@
 {
   "name": "@lernapps/practice",
-  "version": "0.0.1",
-  "description": "Placeholder that reserves the name. The first release (0.1.0) follows from CI with provenance; see https://github.com/lernapps/practice",
+  "version": "0.1.0",
+  "description": "The assistant's side of lernapps practice: the plan template and the skills with which a creator's AI assistant builds an app for an occasion (a class test, a cover lesson), which the creator submits as a ZIP file in an issue; documentation at https://lernapps.net/practice/",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/lernapps/practice.git" },
-  "publishConfig": { "access": "public" }
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lernapps/practice.git"
+  },
+  "bin": {
+    "lernapps-practice": "./bin/lernapps-practice.mjs"
+  },
+  "files": [
+    "bin",
+    "dist/skills",
+    "guidance/plan-template.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./guidance/plan-template.md": "./guidance/plan-template.md"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "scripts": {
+    "build": "./scripts/build.sh",
+    "check": "site-check --site /practice/",
+    "test": "node --test --test-reporter=spec \"test/*.test.ts\"",
+    "try": "node scripts/try.ts",
+    "prepack": "node scripts/dist-skills.ts"
+  },
+  "engines": {
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
+  },
+  "devDependencies": {
+    "@doctc/arc42": "0.38.0",
+    "@lernapps/site": "github:lernapps/lernapps.github.io#00b7891b625342ace8cc8cff3f295ed19e46f289",
+    "marked": "18.1.2"
+  },
+  "dependencies": {
+    "@lernapps/tooling": "0.1.0"
+  },
+  "lernapps": {
+    "planTemplate": "guidance/plan-template.md"
+  }
 }