@lernapps/tooling 0.0.1 → 0.1.0

package/skills/content/lernapps-exercise-patterns/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: lernapps-exercise-patterns
+description: Use in Explore, after the goal and the learners are known and before you choose the archetype - how learners of a lernapps.net app practise each kind of competency, which points to the archetype - and again in Plan to choose a pattern per competency, share material as data and say what a wrong answer is told. In an increment, for a kind of exercise the app's content guide lacks. For every archetype.
+license: MIT
+---
+
+# Exercise patterns
+
+- Learners act on every page or screen (`learners-act`).
+- Learners derive, not only read off: show how a value comes about (tree diagram, step, model), then let them do it.
+- The content guide `.agents/skills/app-content/SKILL.md` names the app's patterns. It takes precedence.
+- Three levels. Take the next level only when the one before cannot express the competency.
+
+## The kind of practice and the archetype
+
+- In Explore, read the patterns of the subject before the archetype is chosen. How learners practise points to the
+  archetype; the README of each template decides:
+  - every competency fits a question with options or an input and feedback per answer, no page needs to explain
+    first → `quiz`;
+  - learners need explanations, figures or derivations on pages before they practise, with exercises in between →
+    `explainer`;
+  - learners act in a model of their own: a game, a simulation, a timed drill, something they move or build →
+    `interactive`.
+- Mixed: the kind most competencies need decides; tell the creator what the others become.
+
+## 1. Data files
+
+- Each fact once, as a record with the same fields as its neighbours (elements, circuit parts, events, organs).
+- The skill `lernapps-<archetype>-design` says where data lives in the archetype.
+
+## 2. Patterns
+
+- A pattern is a kind of exercise for one kind of competency, written down once and varied per use (values,
+  records, context).
+- Choose by the competency's verb:
+
+| The learner can … | Pattern |
+|---|---|
+| compute, convert, estimate | a computed task with unit; typical mistakes diagnosed; numbers drawn where possible |
+| assign, name, recognise | match pairs, or pick one of things of the same kind |
+| order, compare | put items in order by size, date or step |
+| judge, decide | true or false with the reason in the feedback, or pick the right statement |
+| read off, interpret | a figure or table given, a value or statement asked |
+| explain | pick the right explanation among plausible wrong ones, each with background |
+
+- Read the patterns of your subject before you choose: [mathematics](references/mathematics.md),
+  [physics](references/physics.md), [chemistry](references/chemistry.md),
+  [biology and geography](references/biology-geography.md), [history](references/history.md),
+  [computer science](references/computer-science.md). Another subject: the one closest to it.
+- Explainer: read [references/page-structures.md](references/page-structures.md) when you plan the sections of a
+  page; any archetype with figures: [references/figures.md](references/figures.md).
+- Write each pattern into "Content method": name, kind of competency, form in the archetype (what is fixed, what
+  varies), one example, data file. In Code it goes into the content guide.
+
+## 3. Beyond the notation
+
+- What the archetype's notation cannot express: the skill `lernapps-<archetype>-design` says the way out (a component
+  of the explainer; code of an interactive app). Say in the plan why no pattern fits.
+- A need other apps share (figure kind, block, question type) → an issue at
+  <https://github.com/lernapps/app-templates/issues> with an example. Tell the creator; use the nearest pattern.
+- Never code beyond the archetype; note the gap under "Where I had to guess".
+
+## Checking answers
+
+- Read [references/success.md](references/success.md) when you decide how an exercise checks an answer and what each
+  wrong answer is told.
+
+## Every pattern
+
+- Works without seeing the figure: the figure explains, the check checks.
+- The figure shows what is given, never the answer.
+- Numbers fit the story; units are named; rounding is said.
+- Wrong options and mistakes are real ones, each with a reason.
+- Every figure works at 360 px and has a text alternative (`usable-at-360px`, `accessible`).

package/skills/content/lernapps-exercise-patterns/references/biology-geography.md

@@ -0,0 +1,13 @@
+# Patterns: Biology and geography
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Parts and functions | an organ, a cell or a landscape with numbered parts | `labelled-figure`; `table` of parts and functions from a data file; `matching` part ↔ function |
+| Classification | living things or places by a feature | `multiple-choice` "which of these are …" |

package/skills/content/lernapps-exercise-patterns/references/chemistry.md

@@ -0,0 +1,16 @@
+# Patterns: Chemistry
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Particle model | the states of matter as dots with their spacing | three `image`s with captions; `matching` state ↔ description; a component with a temperature slider |
+| Atom model | shells with electrons for the elements 1 to 20, valence electrons marked | a data file of elements (protons, shells, valence electrons); `generated` `pick: 1` with a number answer |
+| Reaction equations | atom counts left and right; balance by coefficients | `formula` with `\ce{…}`; `number` or `generated` asking one coefficient from a data file of reactions; a component that shows the counts |
+| Stoichiometry | mol, g and particles as three boxes with the molar mass between them | `formula` with `\pu{…}`; `generated` from a data file of substances, the mistake "multiplied instead of divided by M" |
+| pH scale | a coloured scale; where substances lie | `image` of the scale; `ordering` of substances by pH from a data file |

package/skills/content/lernapps-exercise-patterns/references/computer-science.md

@@ -0,0 +1,13 @@
+# Patterns: Computer science
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Reading code | a short program; what it prints | `code`; `single-choice` or `number` on its output |
+| Number systems | a number in binary; convert it | `generated` with `int` drawn and the answer computed; the mistake "read from the wrong end" |

package/skills/content/lernapps-exercise-patterns/references/figures.md

@@ -0,0 +1,10 @@
+# Figures
+
+- Shows what the text next to it says; caption: what to look at; `alt`: what it shows (`explainer-figure-explains`).
+- Drawn from the given, never the answer (`explainer-figure-hides-answer`).
+- Bundled; nothing from other servers before a click (`no-request-before-click`); others' images with source and
+  licence (`third-party-licence`).
+- Works at 360 px: trees top to bottom; too wide → table, or split by stage.
+- Same conventions (colours, labels, units, orientation) across the app; write them into the guide, "Figures".
+- The same figures work in a quiz question (`material`, skill `lernapps-content-questions`): an image of `src/images/` with
+  `alt`, `caption`, `source` and `licence`.

package/skills/content/lernapps-exercise-patterns/references/history.md

@@ -0,0 +1,13 @@
+# Patterns: History
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Source and context | a quotation with its origin; what it says about its time | `quote` with `origin`, `source` and `licence`; `single-choice` on its meaning |
+| Chronology | events on a timeline; put them in order | `timeline` from a data file of events; `generated` with `pick: 3, distinct: true` and `compare: order` |

package/skills/content/lernapps-exercise-patterns/references/mathematics.md

@@ -0,0 +1,19 @@
+# Patterns: Mathematics
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Part of a whole (percent, fractions) | a 10×10 grid with the part filled; compute the part, the whole or the rate | `figure` `hundred-grid` on the page; `generated` with `compare: { number: { format: percent } }`; a figure that changes with the task: an exercise component |
+| Before and after a change | two bars, old and new value; compute the change or the new value | `figure` `bar` (`part`, `whole`) on the page; `generated` with the typical mistake "added the rate instead of the amount" |
+| Product of brackets (binomial formulas) | a rectangle split into a², ab, ab, b², lengths from the task | `image` (SVG) for the rule; `generated` for the task; a component only for lengths that follow the task |
+| Difference of squares | a² − b² as an L-shape, rearranged into (a + b)(a − b) | two `image`s side by side with captions; `ordering` of the steps |
+| Outcome set (Laplace) | die faces, wheel sectors or balls, the favourable ones marked | `table` or `image`; `generated` drawing from a data file of experiments, answer as a fraction |
+| Multi-stage experiment | a tree from top to bottom with branch probabilities; multiply along a path | `image` (SVG) of the tree; `generated` with the path rule; a clickable tree as a component |
+| Drawing without replacement | an urn before and after one ball is taken | two `image`s; `generated` with `pick: 2, distinct: true` from a data file of balls |
+| Unit conversion | a value with one unit; give it in another | `generated` with `compare: { number: { unit } }` and the mistake "factor in the wrong direction" |

package/skills/content/lernapps-exercise-patterns/references/page-structures.md

@@ -0,0 +1,8 @@
+# Page structures (explainer)
+
+- Recommended; keep alike across the app's pages.
+- Maths, sciences: Warum, Regel (formula, figure), Beispiel (`example` box), Übung.
+- History: Quelle (`quote`), Einordnung, Zeitleiste (`timeline` from data), Übung (ordering or `generated`).
+- Biology, geography: Überblick, Aufbau (`labelled-figure`), Funktion (`table`), Übung (matching).
+- Computer science: Idee, Beispiel, Code (`code`), Übung (output of the code).
+- Quiz: one round per chapter, questions in the patterns above a question type can express.

package/skills/content/lernapps-exercise-patterns/references/physics.md

@@ -0,0 +1,18 @@
+# Patterns: Physics
+
+- A start, not a rule. Columns: idea; what learners see and do; how it is expressed.
+- Means: explainer blocks (`figure` `hundred-grid`/`bar`/`image`, `labelled-figure`, `table`, `timeline`, `formula`
+  with `\ce{…}`/`\pu{…}`, `definition`, `quote`, `code`); question types (`single-choice`, `multiple-choice`,
+  `true-false`, `number`, `ordering`, `matching`); `generated` (task per seed, `given` or data-file records,
+  `mistakes`, optional drawn figure); component (`vue-component` + `nojs`) last, each with a static form first.
+- New pattern in an app → its content guide, with example and data file.
+
+| Idea | Learners see and do | Expressed with |
+|---|---|---|
+| Circuit symbols | the symbol of a part and its name and function | `table` from a data file of parts; `matching` symbol ↔ part; `generated` `pick` from the data file |
+| Series and parallel circuit | two circuits with the same parts; where is the current larger | `labelled-figure` of both schematics; `single-choice` with the reason in each option's `info`; `ordering` of currents |
+| Ohm's law and quantities | U, R and I of a circuit; compute the missing one with its unit | `formula` `U = R \cdot I`; `generated` with `\pu{…}` units, `where` for realistic values, mistakes "U · I instead of U / I", "mA not converted" |
+| Linear motion | s-t and v-t graphs side by side; read off or compute speed | `image` of the graphs with a `table` of values; `generated` for s = v · t; a component with a slider for v |
+| Lever and moment | a beam with weights at distances; does it balance | `image` of the beam; `generated` for F₁ · a₁ = F₂ · a₂; a component with draggable weights |
+| Optics | a ray diagram of a convex lens; where the image forms | `labelled-figure` of the rays; `true-false` on image properties; a component with a draggable object |
+| Density | blocks of equal mass and different volumes; float or sink | `table` from a data file of materials; `generated` with `compare: { choice: [schwimmt, sinkt] }` |

package/skills/content/lernapps-exercise-patterns/references/success.md

@@ -0,0 +1,28 @@
+# How an exercise checks success
+
+## Property, not model solution
+
+- Check what the text asks: "a fraction equal to 1/2" accepts 2/4 and 3/6; "a conductor" accepts every conductor.
+- "Order the steps" only where the order is fixed.
+- A type that cannot accept every correct answer (ordering with a free order, single choice with two defensible
+  options) → another type or another text.
+
+## Write down first, in the content method
+
+1. The answers that fulfil the text, including correct ones other than yours.
+2. The typical wrong answers.
+3. The feedback for each.
+
+## Feedback on a wrong answer
+
+- Every wrong option says why it does not fit.
+- Computed tasks: 2–3 common mistakes, each with its message.
+- Optionally a hint: where to look, not the answer.
+- A component of your own: right or wrong, plus a short reason.
+
+## Examples as tests
+
+- Each exercise lists other correct answers the text allows as accepted, and typical wrong ones as rejected. The
+  build runs them through the real check; learners never see them.
+- An accepted example fails → the exercise checks the wrong thing: change the type or the check, not the example.
+- The archetype's skill says the notation (`examples`, `mistakes`, component tests).

package/skills/process/lernapps-app/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: lernapps-app
+description: Use in Explore, when a creator wants a learning app for lernapps.net, even if they only say "Lern-App", "Übungs-App" or "für meine Klasse". What every app on lernapps.net must be, how to choose an archetype, and where to read what each one can and cannot do.
+license: MIT
+---
+
+# lernapps app
+
+## What an app is
+
+- A small learning app for school: static, runs in the browser, no account, no tracking, no ads, free.
+- Accessible (WCAG 2.1 AA) and usable at 360 px. A deviation the idea needs (a time limit, a keyboard) is allowed; the
+  catalog entry then says it in `limits`.
+- Other servers (video, map) only after the learner's click. Nothing about a real learner in any text.
+- Published at its creator's own address, usually `https://<owner>.github.io/<repo>/`. Once listed, lernapps.net
+  serves a copy at `https://lernapps.net/apps/start/<id>/`, built from the commit the entry names; the creator stays the author.
+- Licence that allows the copy (MIT or Apache 2.0 for code, CC BY 4.0 for content); files referenced relatively.
+
+## Rules
+
+- Each rule is a section with a rule block: `id`, `scope`, `severity`. Follow every rule in scope, checked or not.
+- Scope: `listing` every listed app; `tooling` every app built with `@lernapps/tooling`; `archetype:<name>` that
+  archetype.
+- Severity: `error` never break; `warning` only with a reason in place; `hint` advice. At the listing, a `tooling`
+  rule counts as a warning.
+- Each skill holds the rules of its phase. All rules: <https://lernapps.net/tooling/rules/>.
+
+## What each archetype can do
+
+| Archetype | Learners … | Can and cannot (README of its template) |
+|---|---|---|
+| `quiz` | answer questions with options and feedback | <https://raw.githubusercontent.com/lernapps/app-templates/main/quiz/README.md> |
+| `explainer` | read pages that explain, each with exercises | <https://raw.githubusercontent.com/lernapps/app-templates/main/explainer/README.md> |
+| `interactive` | act in one app page, by turns or in real time | <https://raw.githubusercontent.com/lernapps/app-templates/main/interactive/README.md> |
+
+## Choose the archetype
+
+- Choose after the interview topics "Goal" and "Learners", from what learners do. Read the patterns of the subject
+  first (skill `lernapps-exercise-patterns`): how learners practise points to the archetype.
+- Before you choose, read the README of each archetype in question, in full. Tell the creator in plain words what the
+  chosen one can and cannot do, before you ask about content, amount and look.
+- A few background sections on the start page keep an app `interactive`.
+- Explanation pages with one interactive exercise → `explainer` with a component.
+
+## Gotchas
+
+- A typing game or a trainer is `interactive`, never `explainer`.
+- What an archetype cannot do is no plan task: tell the creator, choose another archetype or leave it out.
+- The archetype decides what you may write later. Choose it from what learners do, not from what is quickest.

package/skills/process/lernapps-commit/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: lernapps-commit
+description: Use in Commit, when you bring the branch of the first version or an increment into main - the history of main stays linear (one squash commit per piece of work, never a merge commit) and every message is a conventional commit with the sections Intent, Key changes, Dependencies and side effects.
+license: MIT
+---
+
+# Commits of a lernapps app
+
+## Linear history
+
+Bring a branch into `main` by squash: squash-merge its pull request, or `git switch main`, `git merge --squash <branch>`,
+`git commit`. One piece of work is one commit on `main`; never a merge commit. The commit message of the squash
+describes the whole piece of work, not the last step. When you merge yourself, you squash and write it.
+
+## Content from the plan
+
+Do not invent the message: take it from the current plan (`.vibe/plans/<NN>-<short name>.md`). Intent comes from
+"Goal", Key changes from "Key decisions" and the content method, Dependencies and side effects from "Notes". Write it
+in the creator's terms, short.
+
+## Message
+
+A conventional commit: `type(scope): summary` (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`), imperative, under 72
+characters. Then this body, in the language of the repo's history. Say why and what behaves differently; never list
+files.
+
+```markdown
+## Intent
+
+What problem does it solve? What was the motivation to introduce this change?
+
+## Key changes
+
+The conceptual overview: how does the system behave differently now?
+
+## Dependencies and side effects
+
+Only if applicable: effects on other parts of the system.
+```

package/skills/process/lernapps-content-growth/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: lernapps-content-growth
+description: Use in Plan of an increment that adds several competencies, chapters, pages, rounds or questions to a published lernapps.net app. How to cut the work into slices, one per competency, and which slices sub-agents can write in parallel without touching each other's files. For every archetype.
+license: MIT
+---
+
+# Content growth
+
+## One slice per competency
+
+Each slice is one Code task and ends in one commit:
+
+1. Competency: into the content guide, in its chapter, as "Ich kann …", with its Lehrplan unit where used.
+2. Content: a page or section (explainer), questions (quiz), in the guide's structure.
+3. Exercise: a pattern of the guide, varied. A new pattern goes into the guide in the same slice, with example and
+   data file.
+4. Entry topic: the page or section path into the plan's entry draft (`entry-links-resolve`).
+5. Check: `npx lernapps check` passes.
+6. Commit, guide changes included.
+
+- A new chapter or round: its slices in the order of the guide's procedure.
+- The procedure no longer fits → its fix is part of the slice that shows it (`app-content-matches`).
+
+## Parallel slices
+
+- No two agents change the same file.
+- Yours alone: the content guide, the plan, the shared files (explainer `src/app.yaml`, each `chapter.yaml`,
+  `src/data/`; quiz `src/quiz.json`).
+- A sub-agent's: one chapter (its pages, its own data file); in a quiz, the question drafts of one round.
+- Each sub-agent works in its own git worktree, branch and browser port. You merge one by one, add the shared parts
+  and run the check.
+- In Code, each sub-agent gets the brief `@lernapps/tooling/guidance/subagent-brief.md`, filled in. Write in Plan
+  which slices go to sub-agents.

package/skills/process/lernapps-github/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: lernapps-github
+description: Use in Commit, when a lernapps.net app or increment goes on GitHub and online, or a GitHub step fails - repo and branches, Pages from gh-pages, the preview pull request and its checks, bringing the branch into main, the run of the workflow Pages, the fork for the listing pull request. Which tool first, what you may do yourself, which click you ask the creator for.
+license: MIT
+---
+
+# GitHub
+
+- Branches: `main` is published; `work` holds the first version until its publish (an increment:
+  `increment/<NN>-<short name>`); `gh-pages` is served. A push to `main` publishes.
+- Until Commit everything is local. You do the GitHub part; the creator need not know GitHub. On request:
+  <https://lernapps.net/tooling/github/>.
+
+## Tools, in this order
+
+1. `gh` over REST: `gh api`, `gh run`, `gh workflow`. GraphQL may be blocked, and with it the commands that use it
+   (repo view, repo edit, pr create): that is no reason to drop `gh`; use `gh api`.
+2. GitHub MCP tools, if present.
+3. `curl -s https://api.github.com/repos/<owner>/<repo>/…`: public reads, no token.
+
+## 1. Repo and Pages (first version)
+
+1. Ask the creator in one message: the repo name (a later rename can cost your access), and, if you cannot create
+   repos or change Pages, the clicks below.
+2. No repo on GitHub: `gh api user/repos -f name=<repo>`. Refused → the creator creates an empty public repo and
+   gives you its address.
+3. `git remote add origin <address>`.
+4. No `main` on the remote: `git switch --orphan main`, `git commit --allow-empty -m "chore: start"`,
+   `git push -u origin main`.
+5. No `gh-pages`: `git switch --orphan gh-pages`, `git commit --allow-empty -m "chore: gh-pages"`,
+   `git push -u origin gh-pages`.
+6. `git switch work`; it has its own root: `git rebase --root --onto main`.
+7. Pages from `gh-pages`, root (`pages-from-gh-pages`):
+   `gh api -X POST repos/<owner>/<repo>/pages -f build_type=legacy -f "source[branch]=gh-pages" -f "source[path]=/"`.
+   Verify: `gh api repos/<owner>/<repo>/pages --jq '.build_type, .source.branch, .source.path'` prints `legacy`,
+   `gh-pages`, `/`. "Not Found" means off.
+8. Default branch: `gh api repos/<owner>/<repo> --jq .default_branch` prints `main`. Else (admin):
+   `gh api -X PATCH repos/<owner>/<repo> -f default_branch=main`.
+
+## 2. Preview and checks
+
+1. `git push -u origin <branch>`. The pre-push hook runs the heavy checks; fix failures (skill `lernapps-cli`).
+2. Open the pull request over REST:
+   `gh api repos/<owner>/<repo>/pulls -f base=main -f head=<branch> -f title=<"Erste Version" or the increment> -f body=Vorschau`.
+   Its comment "Vorschau der App" links the preview.
+3. Watch the checks of the head commit:
+   `gh api repos/<owner>/<repo>/commits/<sha>/check-runs --jq '.check_runs[] | [.name, .status, .conclusion]'`.
+   A check fails → `gh run view <id> --log-failed`; fix, commit, push. Green before the checkpoint "publish".
+
+## 3. Publish
+
+1. Only after the creator's yes at the checkpoint "publish".
+2. One squash commit on `main`, its message as skill `lernapps-commit` says; never a merge commit.
+   First version: `git switch main`, `git merge --squash work`, `git commit`, `git push origin main`; the pull
+   request closes with it. Increment: squash-merge its pull request
+   (`gh api -X PUT repos/<owner>/<repo>/pulls/<n>/merge -f merge_method=squash -f commit_title=… -f commit_message=…`).
+3. Run started? `gh run list --workflow Pages --branch main --commit "$(git rev-parse HEAD)"`. None after a minute
+   → `gh workflow run Pages --ref main`.
+4. Watch it: `gh run watch <id>`. It fails → read the failed step, fix, push.
+5. The job `deploy` prints "published at …" (also in the run summary). Use that address; follow redirects.
+
+## "403 Resource not accessible by integration"
+
+- The token may not change this setting or start this run. It is a click for the creator; put it into your next
+  question, once:
+  - Pages: Settings → Pages → Build and deployment → Source: Deploy from a branch → Branch: gh-pages, folder:
+    / (root) → Save.
+  - Default branch: Settings → General → Default branch → ⇄ → main → Update.
+  - Run: Actions → Pages → Run workflow, or the run → Re-run all jobs.
+- Never work around it: no dummy push, no new branch to pass a setting.
+
+## 4. Listing pull request from a fork
+
+- Never push a branch to lernapps/apps, even if allowed. You open the pull request from the creator's fork at the
+  checkpoint "list", without asking first: it publishes nothing.
+- Find the fork by its owner, never by its name (it may be renamed):
+  `curl -s "https://api.github.com/repos/lernapps/apps/forks?per_page=100" | jq -r '.[] | select(.owner.login=="<owner>") | .clone_url'`.
+- No fork, or no access to it: first add the repos your environment needs (e.g. `add_repo` with push access for the
+  fork and lernapps/apps); then `gh repo fork lernapps/apps --clone=false`, or MCP. Only when both fail: the creator's
+  click (github.com/lernapps/apps → Fork), asked for once.
+- Push `add-<id>` to the fork; open the pull request over REST:
+  `gh api repos/lernapps/apps/pulls -f base=main -f head=<owner>:add-<id> -f title=… -f body=…`.
+- From a fork the pull request gets the results comment, but no preview.
+
+## Gotchas
+
+- The creator merged the pull request themselves → no second merge: check the `Pages` run of that commit and confirm
+  the address.
+- Never `git commit-tree` or `--no-verify` to get past a hook; an empty start commit passes the hook as it is.
+
+## `pages-from-gh-pages`: Publish from `gh-pages`, served from its root
+
+```rule
+id: pages-from-gh-pages
+scope: [archetype:explainer, archetype:interactive, archetype:quiz]
+severity: error
+```
+
+- GitHub Pages serves the branch `gh-pages` from `/`: usually `https://<owner>.github.io/<repo>/`; only repos of
+  the lernapps organisation at `https://lernapps.net/<repo>/`.
+- Previews of pull requests go below `pr-preview/` on that branch: leave the setting.
+- Hosted elsewhere → the entry's `url` points there.

package/skills/process/lernapps-listing/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: lernapps-listing
+description: Use in Commit when the creator wants their app in the lernapps.net app overview, or when the listing pull request gets a results comment - even if they only say "eintragen" or "veröffentlichen". The steps to the listing pull request and how to act on its results.
+license: MIT
+---
+
+# Listing
+
+- A pull request to [lernapps/apps](https://github.com/lernapps/apps) adds the app's entry.
+- Rules: `entry-from-schema`, `entry-links-resolve`, `entry-fitness-matches` (skill `lernapps-cli`,
+  `references/platform-rules.md`).
+
+## Open the pull request
+
+At the checkpoint "list", without asking first: the pull request publishes nothing and is the review. After
+"bestanden", show the creator the pull request and its result; change nothing in it without their word.
+
+1. Follow the listing guide <https://lernapps.net/apps/enter/llms.txt> step by step: where the entry goes, how to
+   check it, how to open the pull request.
+2. Fill the entry from the plan's entry draft and <https://lernapps.net/apps/schemas/entry.v1.schema.json>, fetched
+   now. The schema describes every field.
+3. Run the check the guide names. Fix its findings first: the pull request runs the same check.
+4. Open the pull request from the creator's fork as skill `lernapps-github` says.
+
+## Results comment
+
+- The listing guide says how to read it. Repeat until "bestanden".
+- A fix of the app counts only once it is published (plan, Commit); then push to the pull request's branch.
+- Then the owner of lernapps.net reviews and decides. Wait; tell the creator the comment and the decision.
+
+## After the merge
+
+- lernapps.net builds a copy of the app from the entry's `commit` and serves it at
+  `https://lernapps.net/apps/start/<id>/`; the catalog links it once it is checked there. Tell the creator: the app
+  stays theirs, at their own address too.
+- Tell the creator once how to keep the app up to date: two GitHub Apps and a few settings of their repo, in
+  [references/keeping-updated.md](references/keeping-updated.md). Without them the app gets no tooling updates, and
+  lernapps/apps lists it in an issue. It is advice; the listing does not wait for it.
+- A new version needs no new pull request from you. Publish it as usual (plan, Commit). Once the app's address
+  serves the new commit, lernapps/apps opens an update pull request for the entry within about 30 minutes; the
+  listing check runs on it.
+- It merges itself when nothing else changed than what `lernapps update` makes, versions of npm dependencies and
+  Markdown outside `src/` and `public/`. Anything else (content, code, workflows edited by hand, the licence) waits
+  for the owner's review. Tell the creator which of the two to expect.

package/skills/process/lernapps-listing/references/keeping-updated.md

@@ -0,0 +1,33 @@
+# Keeping a listed app up to date
+
+Tell the creator once, at the listing. It is advice; the listing does not wait for it. The creator owns the repo, so
+these are their clicks. Offer to go through them together.
+
+## 1. Two GitHub Apps, on the app's repo only
+
+Each opens a page: choose the creator's account, "Only select repositories", the app's repo, Install.
+
+- `https://github.com/apps/lernapps-updater/installations/new`: every day lernapps/apps runs `lernapps update` in the
+  app and opens a pull request that merges once the app's check is green. Without it the app gets no tooling updates,
+  and lernapps/apps lists it in an issue.
+- `https://github.com/apps/renovate/installations/new`: third-party packages, using the app's `renovate.json`. The
+  file does nothing without the App.
+
+## 2. Pull request settings
+
+Settings → General → Pull Requests: select **Allow auto-merge** and **Allow squash merging** (a linear history
+needs squash or rebase).
+
+## 3. One ruleset for `main`
+
+Settings → Rules → Rulesets → New ruleset → New branch ruleset. Name `main`, enforcement **Active**, Target branches
+→ Add a target → include the default branch (pattern `main`). Rules:
+
+- **Require a pull request before merging**: no approvals needed; as merge type squash.
+- **Require linear history**.
+- **Require status checks to pass before merging**: add the check `app` (the job of the workflow `Pages`). GitHub
+  offers a check only after it has run once, so the app must have had a pull request or a push first.
+- **Block force pushes** (on by default).
+- Bypass list → Add bypass → the repository admins, so the creator can still push by hand.
+
+A required check the repo does not produce blocks every pull request for good: use `app`, no other name.