@lernapps/tooling 0.0.1 → 0.1.0

package/dist/skills/lernapps-explainer-design/references/rules.md

@@ -0,0 +1,75 @@
+# Explainer rules for planning
+
+## `topic-has-exercises`: Every page has exercises
+
+```rule
+id: topic-has-exercises
+scope: archetype:explainer
+severity: error
+```
+
+- Every page has at least one exercise that practises what the page explains, with solution or feedback; best in a
+  last section "Übung".
+- The schema requires it; start, chapter and glossary pages are generated. The review judges the fit.
+
+## `prefer-built-in-block`: A component only where no block fits
+
+```rule
+id: prefer-built-in-block
+scope: archetype:explainer
+severity: hint
+```
+
+- Built-in blocks and exercises first. A component only for what none can express; say why in the plan.
+
+## `explainer-figure-hides-answer`: The figure does not give the answer away
+
+```rule
+id: explainer-figure-hides-answer
+scope: archetype:explainer
+severity: error
+```
+
+- A task's figure shows the given values, never the answer.
+
+## `explainer-figure-explains`: The figure shows what the text says
+
+```rule
+id: explainer-figure-explains
+scope: archetype:explainer
+severity: hint
+```
+
+- Each figure shows what the text next to it explains. The caption says what to look at; `alt` says what it shows.
+
+## `explainer-plausible-numbers`: Numbers that fit the story
+
+```rule
+id: explainer-plausible-numbers
+scope: archetype:explainer
+severity: warning
+```
+
+- Ranges fit the thing: prices in whole cents, people whole, a bicycle 150–1500 €.
+- Preconditions rule out misfits (90.91 people).
+
+## `explainer-mistakes-diagnosed`: Typical mistakes with their message
+
+```rule
+id: explainer-mistakes-diagnosed
+scope: archetype:explainer
+severity: hint
+```
+
+- Computed tasks list real mistakes. Each message says what went wrong and how to fix it ("Du hast vergessen, durch
+  100 zu teilen", not "Falsch").
+
+## `explainer-quote-sourced`: Quotes exact, with their origin
+
+```rule
+id: explainer-quote-sourced
+scope: archetype:explainer
+severity: warning
+```
+
+- Quote exactly. Name its origin (author, work, year), source and licence.

package/dist/skills/lernapps-explainer-self-assessment/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: lernapps-explainer-self-assessment
+description: Use in Commit of a lernapps.net explainer, once its content and its forms of teaching are final, to add, change or leave out its self-assessment (selfAssessment in each chapter.yaml) - which exercises it asks, how many on each of its pages, and what the build checks. Also when a build problem names selfAssessment.
+license: MIT
+---
+
+# Self-assessment of an explainer
+
+## What it is
+
+- Two kinds of page: a content page of the app (`/<chapter>/<page>/`), and a step, one page of the
+  self-assessment with a few exercises.
+- Optional, for the learner and for the app. Before learning, the learner answers exercises of the content pages,
+  without the page around them, a few on each step.
+- No exercise is checked alone. "Auswerten" checks all of them together. The result per content page:
+  "Kannst du wahrscheinlich schon" (all right), "Schau sie dir noch einmal an" (at least half), "Lies sie genau"
+  (less), "Nicht abgefragt" (none of its exercises asked).
+- JavaScript only: without it, it is not offered. The last result stays on the device; a new run replaces it.
+- The chapter is the unit: each chapter declares its own in its `chapter.yaml` (at `<chapter>/einschaetzung/`,
+  offered on the chapter's page). The app's (at `einschaetzung/`, offered on the start page) is every chapter's
+  together; you write nothing for it. In an app with one chapter, the app's is the chapter's.
+- The learner may take the result to their KI tutor. The tutor then guides chapter by chapter: to the pages that do
+  not stick, then into a new round of the chapter's self-assessment. The build writes the tutor's page; you write
+  nothing for the tutor.
+
+## Decide
+
+- Default: one in every chapter.
+- None in a chapter whose pages teach what no exercise can check (an open activity, a discussion, making something):
+  the tutor goes through it page by page. None in any chapter: write the reason under "Key decisions" and tell the
+  creator in one sentence.
+- Leave a page out when its competency cannot be checked by one of its exercises. The result says "Nicht
+  abgefragt"; that is right for such a page.
+
+## Choose the exercises
+
+- Read each content page's competency under "Notes" ("Ich kann …"). No "Notes": take it from the page's title,
+  description and rule. Ask the exercises that check it best.
+- Prefer what draws a new task in each run: `generated`, or an exercise component (a `vue-component` block whose
+  component emits an answer, by its anchor). Then `number`, `ordering`, `matching`, `multiple-choice`,
+  `single-choice`. A content page asked only by exercises that can be guessed (`true-false`, a `single-choice` or a
+  small `matching`) gives a weak result: add a `generated`, a component or a `number` one of the same page.
+- Each must be clear without its page: no "wie im Beispiel oben", no figure that stands elsewhere on the page. A
+  question carries its figure in `material`. Not clear alone → take another exercise of the page, or leave the page
+  out.
+- An exercise component shows its task without "Prüfen", feedback or task number. Take it only when its task is
+  clear in the component itself (the task text is in the component, not in a block around it), and when it needs
+  nothing the page has to play or show first.
+- 2 or 3 exercises per content page asked: with one alone, the page is never "Kannst du wahrscheinlich schon". A page
+  with one fitting `generated` exercise or exercise component: list it twice, each listing draws a task of its own.
+  A question is listed once.
+
+## Write it
+
+- Steps: 2 to 5 exercises each, best 3; fewer or more gives a build hint. Keep the order of the course, also within a
+  content page.
+- About 3 to 8 exercises per chapter; the app's, every chapter's together, at most about 15 to 20: about ten minutes.
+- Each exercise by its page and id: `/<chapter>/<page>/#<exercise>`, of the chapter's own pages.
+
+```yaml
+# src/prozent/chapter.yaml
+selfAssessment:
+  pages:
+    - exercises:
+        - /prozent/prozentwert/#prozentwert-ueben
+        - /prozent/prozentsatz/#welche-rechnung
+        - /prozent/prozentsatz/#prozentsatz-ueben
+    - exercises:
+        - /prozent/grundwert/#klammern
+        - /prozent/grundwert/#grundwert-ueben
+```
+
+- In the content guide (`.agents/skills/app-content/SKILL.md`), in the procedure for a new chapter or page, add the
+  step: "1 bis 3 ihrer Übungen in `selfAssessment` aufnehmen, wie Skill `lernapps-explainer-self-assessment` sagt."
+  None in the app → the content guide says why.
+
+## Check
+
+- Build and `lernapps check`: one line per problem (the hint on the size of a step names its file and place), e.g.
+  `src/prozent/chapter.yaml:9: selfAssessment.pages[0].exercises[0]: /prozent/prozentwert/#prozent-raten names no exercise of src/prozent/prozentwert.yaml; …`.
+  Fix where it points.
+- Do one run yourself in `npm run dev` at `/einschaetzung/`, and one at `/<chapter>/einschaetzung/?via=tutor`: it
+  ends in "Zurück zum Tutor". For each exercise: no "oben", "im Beispiel" or other
+  reference to its page; its figure shows with it; the task is the whole question. For each content page asked: one
+  exercise at least that cannot be guessed. Then write the commit.
+- The end-to-end tests do three runs of each self-assessment: every answer right; none; one a tutor opened.
+
+## Gotchas
+
+- An exercise renamed or moved → change its reference in the same commit.
+- `einschaetzung` is reserved: no chapter or page may have that id.
+- Never `selfAssessment` in `src/app.yaml` (build problem): the app's comes from the chapters.
+- Nothing about a real learner in any file (`no-learner-data-in-texts`).

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