@lernapps/tooling 0.2.2 → 0.3.1

package/archetypes/shared/playwright.ts

@@ -32,6 +32,11 @@ const base: PlaywrightTestConfig = {
   // another number of workers: the tooling's own tests set 1, because they run many apps' checks at the same time.
   fullyParallel: true,
   workers: Number(process.env["LERNAPPS_PLAYWRIGHT_WORKERS"]) || "75%",
+  // On CI (a small shared runner) a single interaction can now and then wait past the timeout under load
+  // (lernapps/app-templates#125): a failed test runs up to twice more there. One that passes on a retry counts as
+  // "flaky" in the output, not as passed, so it stays visible; a test that fails every time still fails the check.
+  // Locally no retry, so that a test that only sometimes passes shows up while the app is written.
+  retries: process.env["CI"] ? 2 : 0,
   reporter: [["line"]],
   // LERNAPPS_CHROMIUM: an installed Chromium that lernapps check starts where Playwright's own is missing
   // (check/visit.ts)

package/dist/cli.mjs

@@ -1432,8 +1432,11 @@ const CREATE_USAGE = `Usage: lernapps create --archetype <name> [<dir>] [--plan
 Writes a new app from the archetype's template into <dir> (default: the current folder), which must be empty
 except for .git, the first version's plan .vibe/plans/01-<short name>.md and the skills that
 lernapps init synced (.agents/skills/, .claude/skills/, skills-lock.json, and the package.json, package-lock.json and
-node_modules init wrote). The template is the folder <name>/ of the installed package @lernapps/app-templates, the
-version @lernapps/tooling depends on; the app depends on the runtime of the same version.
+node_modules init wrote). From the installed package @lernapps/app-templates, the version @lernapps/tooling depends
+on, it writes the archetype's scaffold: the files of the template folder <name>/ that the package's lernapps.scaffold
+lists (the entry, the configuration, the end-to-end tests of the content) and a placeholder as start content
+(scaffold/<name>/), which the planned content replaces. The template folder itself is the example app: it stays in
+node_modules/@lernapps/app-templates/<name>/, to look up. The app depends on the runtime of the same version.
 
 It needs the plan of the first version, confirmed by the creator: started from the plan template as
 .vibe/plans/01-<short name>.md, the only plan there, worked through Explore and Plan, now in the phase code
@@ -1445,7 +1448,7 @@ Run it in the folder lernapps init prepared, from the tooling init installed:
 It needs git, and the npm registry for the npm install that follows. The app then depends on the version of
 @lernapps/tooling that created it, and its workflows use the actions of that version's tag.
 
-It writes, besides the template: package.json named after the short name given to init (the folder's name without init) (its prepare script, lernapps hooks,
+It writes, besides the scaffold: package.json named after the short name given to init (the folder's name without init) (its prepare script, lernapps hooks,
 installs the git hooks; for an explainer and an interactive app also vue-tsc and typescript, with which lernapps
 check type-checks its Vue components; for an interactive app also @doctc/arc42, which checks its architecture),
 for an interactive app its architecture docs/arc42/ (the generic part and the interactive extension of app-templates,
@@ -1497,7 +1500,8 @@ function templatesPackage(dir) {
 	return {
 		root,
 		version: manifest.version ?? "0.0.0",
-		archetypes: [...manifest.lernapps?.archetypes ?? []].sort()
+		archetypes: [...manifest.lernapps?.archetypes ?? []].sort(),
+		scaffold: manifest.lernapps?.scaffold ?? {}
 	};
 }
 /** The version of this package. */
@@ -1545,6 +1549,27 @@ function git(args, cwd) {
 }
 /** A package name from the folder's name: lower case, letters, digits and hyphens. */
 const packageName = (dir) => basename(dir).toLowerCase().normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "app";
+/**
+* The scaffold of the archetype into `dir` (decision dec-scaffold of app-templates): the paths of its template folder
+* that lernapps.scaffold.<archetype> of the package lists (the entry, the configuration, the e2e entry), then the start
+* content scaffold/<archetype>/, a placeholder the creator replaces. The rest of the template folder is the example
+* app; it stays in node_modules/@lernapps/app-templates/<archetype>/ for the creator's assistant to look up.
+*/
+function writeScaffold(templates, archetype, dir) {
+	const paths = templates.scaffold[archetype];
+	if (paths === void 0 || paths.length === 0) throw new CreateError(`${templates.root} (version ${templates.version}) names no scaffold for ${archetype} (lernapps.scaffold in its package.json): use the version of ${RUNTIME} this tooling depends on`);
+	const template = join(templates.root, archetype);
+	for (const path of paths) {
+		const shipped = basename(path) === ".gitignore" ? join(template, dirname(path), "_gitignore") : void 0;
+		const source = shipped !== void 0 && existsSync(shipped) ? shipped : join(template, path);
+		if (!existsSync(source)) throw new CreateError(`${template} has no ${path}, which its scaffold lists`);
+		mkdirSync(dirname(join(dir, path)), { recursive: true });
+		cpSync(source, join(dir, path));
+	}
+	const start = join(templates.root, "scaffold", archetype);
+	if (!existsSync(start)) throw new CreateError(`${templates.root} has no start content scaffold/${archetype}/`);
+	cpSync(start, dir, { recursive: true });
+}
 /** This package, as an app depends on it. */
 const TOOLING = "@lernapps/tooling";
 /**
@@ -1698,18 +1723,9 @@ function create(args) {
 	const initialised = existsSync(join(dir, "package.json")) ? readJson(join(dir, "package.json")) : void 0;
 	const initialLock = existsSync(join(dir, "package-lock.json")) ? readFileSync(join(dir, "package-lock.json"), "utf8") : void 0;
 	mkdirSync(dir, { recursive: true });
-	cpSync(join(templates.root, archetype), dir, { recursive: true });
-	rmSync(join(dir, "package-lock.json"), { force: true });
+	writeScaffold(templates, archetype, dir);
 	if (initialLock !== void 0) writeFileSync(join(dir, "package-lock.json"), initialLock);
-	if (existsSync(join(dir, "_gitignore"))) renameSync(join(dir, "_gitignore"), join(dir, ".gitignore"));
-	rmSync(join(dir, "README.md"), { force: true });
-	rmSync(join(dir, ARCHITECTURE), {
-		recursive: true,
-		force: true
-	});
-	if (existsSync(join(dir, "docs")) && readdirSync(join(dir, "docs")).length === 0) rmSync(join(dir, "docs"), { recursive: true });
 	if (architecture) writeArchitecture(dir, templates.root, archetype, templates.version);
-	else rmSync(join(dir, ".arc42ignore"), { force: true });
 	const app = readJson(join(dir, "package.json"));
 	const name = initialised?.lernapps?.init === true && typeof initialised.name === "string" ? initialised.name : packageName(dir);
 	app.name = name;
@@ -1717,12 +1733,15 @@ function create(args) {
 		...app.scripts,
 		prepare: "lernapps hooks"
 	};
-	if (app.devDependencies?.["@lernapps/app-templates"] !== void 0) {
-		app.devDependencies = {
-			...app.devDependencies,
-			[RUNTIME]: `^${templates.version}`
-		};
-		rmSync(join(dir, ".npmrc"), { force: true });
+	if (app.devDependencies?.["@lernapps/app-templates"] !== void 0) app.devDependencies = {
+		...app.devDependencies,
+		[RUNTIME]: `^${templates.version}`
+	};
+	const overrides = app["overrides"];
+	if (typeof overrides === "object" && overrides !== null && "@lernapps/app-templates" in overrides) {
+		const kept = Object.fromEntries(Object.entries(overrides).filter(([name]) => name !== RUNTIME));
+		if (Object.keys(kept).length > 0) app["overrides"] = kept;
+		else delete app["overrides"];
 	}
 	const tooling = values.tooling ?? `^${ownVersion()}`;
 	app.devDependencies = {

package/dist/playwright.mjs

@@ -18,6 +18,7 @@ const base = {
 	forbidOnly: true,
 	fullyParallel: true,
 	workers: Number(process.env["LERNAPPS_PLAYWRIGHT_WORKERS"]) || "75%",
+	retries: process.env["CI"] ? 2 : 0,
 	reporter: [["line"]],
 	use: {
 		baseURL: URL,

package/dist/skills/lernapps-cli/references/platform-rules.md

@@ -147,6 +147,7 @@ severity: error
 ```
 
 - Texts for learners, teachers, parents: German, plain (short sentences, active voice, no jargon).
+- Never English only: an app in English is German and English, German first.
 - More languages only where the archetype supports them (explainer, quiz: `languages`, German first); each declared
   language complete, no other.
 - Texts out of code: in the content (explainer YAML, quiz bank) or message files (`src/messages/de.json`, shown

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

@@ -8,7 +8,7 @@ license: MIT
 
 - You write YAML in `src/`; a Vue component only where the plan names one. Rendering, navigation, formulas, figures,
   exercises, accessibility, languages and the no-JS page come from the runtime `@lernapps/app-templates`.
-- `create` writes the example chapter "Prozent": replace it with the planned content.
+- `create` writes a placeholder: one chapter with one page and one exercise. Replace it with the planned content. The complete example, the chapter "Prozent" with a component, is in `node_modules/@lernapps/app-templates/explainer/`: look things up there, never copy it.
 - Schema: `node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json`. Start every YAML file with
   `# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json`
   (one `../` less in `src/app.yaml`).

package/dist/skills/lernapps-explainer/references/blocks.md

@@ -69,6 +69,8 @@
 ## Languages
 
 - `languages` in `src/app.yaml`, German first: `[de]` or `[de, en]` (runtime texts: de, en).
+- Never English only: with `[de]` the pages and the runtime's texts are German, so English strings mix both.
+  English wanted → `[de, en]`.
 - A string = German, enough only while German is the only language. Else every text a map:
   `title: { de: Die drei Stände, en: The three estates }`.
 - Build fails on a missing translation (`the translation is missing; write the text as a map: { de: …, en: … }`)

package/dist/skills/lernapps-explainer/references/components.md

@@ -47,7 +47,7 @@
   `show(answer, task, props, lang)` (answer as text). An input of `params` that is no placeholder shows as
   "(verdeckt)": the tutor knows it, the child does not. One `template` per block: prefer one kind of task per block;
   else give the sentence that changes as an input (`{Aufgabe}`). `about.answer` names what the child does and "Prüfen". The build checks them against `check` for every number; rule `vue-component-tutor-table`. Model:
-  `ProzentFeld` of the template.
+  `ProzentFeld` of the template, in `node_modules/@lernapps/app-templates/explainer/src/components/`.
 - More: rule `vue-component-exercise-contract`.
 
 ## Rendering

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

@@ -194,7 +194,7 @@ severity: hint
 - The tutor page then has the task once, the mistakes as F1, F2 … and a table of every number (inputs, solution,
   each mistake), like `generated`. Without them: each number's `describe` as far as 64 kB allow, and the build's hint
   names the block.
-- Example: `src/components/ProzentFeld.ts` of the template.
+- Example: `node_modules/@lernapps/app-templates/explainer/src/components/ProzentFeld.ts`, the template's.
 
 ## `vue-component-tested`: A test per component
 

package/dist/skills/lernapps-explainer-design/SKILL.md

@@ -44,7 +44,8 @@ license: MIT
 
 ## Decide
 
-- Languages: German; English as a second language is supported. Each declared language complete.
+- Languages: German; English as a second language is supported. Each declared language complete. Never English
+  only: without `languages` the page and the runtime's texts are German. English wanted → `[de, en]`.
 - The tutor: the build writes it from the content. Plan only app-specific tutor rules, if any.
 
 ## Gotchas

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

@@ -7,7 +7,7 @@ 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.
+- `create` writes a placeholder: a counter as core, component and playthrough. Replace it with the planned parts. The complete example, a typing game, is in `node_modules/@lernapps/app-templates/interactive/`: look things up there, never copy it.
 
 ## What you write
 

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

@@ -39,7 +39,8 @@ license: MIT
 - 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.
+- Languages: German; each declared language complete; learner texts in message files, never in code. Never English
+  only: German comes first. English wanted → German and English.
 
 ## Gotchas
 

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

@@ -9,7 +9,7 @@ license: MIT
 - You write `src/quiz.json` and, for the content of its questions, the image files in `src/images/`. Engine, question
   types, feedback, scoring, order, accessibility and the no-JS page come from the runtime `@lernapps/app-templates`.
 - Schema: `node_modules/@lernapps/app-templates/runtime/quiz/quiz.v1.schema.json`.
-- `create` writes the example bank "Naturwunder der Welt": replace it with the planned questions.
+- `create` writes a placeholder bank with one question. Replace it with the planned questions. The complete example, the bank "Naturwunder der Welt", is in `node_modules/@lernapps/app-templates/quiz/`: look things up there, never copy it.
 - The fields of each question type and how to write good questions: skill `lernapps-content-questions`.
 
 ## Gotchas
@@ -50,7 +50,8 @@ license: MIT
 - German; more with `"languages": ["de", "en"]`, German first (runtime texts: de, en).
 - Then every learner text is a map with each language: title, intro, source titles; per question text, options,
   `info`, items, pairs, unit, explanation, link titles.
-- Without `languages`: German strings.
+- Without `languages`: German strings. The page is German then (`lang="de"`, the runtime's own texts such as
+  "Frage 1 von 5"); English strings give a page that mixes both. Never English only: English wanted → `[de, en]`.
 - Link `url`: one address, or a map per language (own Wikipedia).
 - Build errors, one line each, e.g.
   `questions[1].explanation (en) (question "totes-meer"): the translation is missing; write the text as a map: { de: …, en: … }`;

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

@@ -42,7 +42,8 @@ license: MIT
 
 ## Decide
 
-- Languages: German; English as a second language is supported. Each declared language complete.
+- Languages: German; English as a second language is supported. Each declared language complete. Never English
+  only: without `languages` the page and the runtime's texts are German. English wanted → `[de, en]`.
 - Keep the last score on the device (`rememberLastResult`) or nothing. Keeping it → the entry says
   `fitness.storage: device`.
 - Order: shuffled per seed; a link with `?seed=42` gives every learner the same order.

package/generator/app/.github/workflows/pages.yml

@@ -15,7 +15,9 @@ name: Pages
 # paths filter: a check skipped by a paths filter stays "Pending" and blocks a pull request that requires it. GitHub
 # may start no run for a push that creates main from commits it already has (the first publish): then start it by
 # hand, Actions → Pages → Run workflow on main (gh workflow run Pages --ref main), as the plan says; a run started by
-# hand checks and publishes everything.
+# hand checks and publishes everything. A push to main whose commit has the same tree as the pull request that the job
+# `app` checked already (the pull request was up to date with main when it was merged) takes that run's bundle and
+# report instead of checking again.
 on:
   push:
     branches: [main]
@@ -34,6 +36,9 @@ jobs:
   app:
     if: github.event.action != 'closed'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read # on main: find the run of the pull request that checked the same tree, and take its result
     steps:
       - uses: lernapps/tooling/actions/app-check@{{tooling}}
   deploy:

package/generator/create.ts

@@ -1,8 +1,9 @@
 // The generator, `lernapps create --archetype <name> [<dir>]`: writes a new app into an empty folder, once the creator
 // has confirmed the first version's plan (.vibe/plans/01-<short name>.md, in the phase code, for this archetype). It
-// copies the archetype's folder out of the installed package @lernapps/app-templates (a dependency of this package, at
-// an exact version), and makes the app depend on that same version of the runtime, so template and runtime always
-// match. Then it writes what every app has: AGENTS.md, the
+// writes the archetype's scaffold out of the installed package @lernapps/app-templates (a dependency of this package,
+// at an exact version): the paths of the template folder its lernapps.scaffold lists and the placeholder in
+// scaffold/<archetype>/, not the example app, which stays in node_modules for the assistant to look up. It makes the
+// app depend on that same version of the runtime, so template and runtime always match. Then it writes what every app has: AGENTS.md, the
 // plan, the content guide (an app-local skill), the workflows, LICENSE, an issue form for content errors and the
 // Renovate configuration (generator/app/); an interactive app also its architecture (generator/architecture.ts). The
 // skills `lernapps init` synced into the folder stay, and are committed with the app; `lernapps update` replaces them
@@ -26,7 +27,7 @@ import { createRequire } from "node:module";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, type ParseArgsOptionsConfig } from "node:util";
-import { ARCHITECTURE, ARCHITECTURE_ARCHETYPES, writeArchitecture } from "./architecture.ts";
+import { ARCHITECTURE_ARCHETYPES, writeArchitecture } from "./architecture.ts";
 import { LEGACY_PLAN, MIGRATED_PLAN, PLAN_NAME, PLANS, planFrontMatter, plans } from "../src/plan.ts";
 import { UsageError } from "../src/usage.ts";
 
@@ -44,8 +45,11 @@ export const CREATE_USAGE = `Usage: lernapps create --archetype <name> [<dir>] [
 Writes a new app from the archetype's template into <dir> (default: the current folder), which must be empty
 except for .git, the first version's plan .vibe/plans/01-<short name>.md and the skills that
 lernapps init synced (.agents/skills/, .claude/skills/, skills-lock.json, and the package.json, package-lock.json and
-node_modules init wrote). The template is the folder <name>/ of the installed package @lernapps/app-templates, the
-version @lernapps/tooling depends on; the app depends on the runtime of the same version.
+node_modules init wrote). From the installed package @lernapps/app-templates, the version @lernapps/tooling depends
+on, it writes the archetype's scaffold: the files of the template folder <name>/ that the package's lernapps.scaffold
+lists (the entry, the configuration, the end-to-end tests of the content) and a placeholder as start content
+(scaffold/<name>/), which the planned content replaces. The template folder itself is the example app: it stays in
+node_modules/@lernapps/app-templates/<name>/, to look up. The app depends on the runtime of the same version.
 
 It needs the plan of the first version, confirmed by the creator: started from the plan template as
 .vibe/plans/01-<short name>.md, the only plan there, worked through Explore and Plan, now in the phase code
@@ -57,7 +61,7 @@ Run it in the folder lernapps init prepared, from the tooling init installed:
 It needs git, and the npm registry for the npm install that follows. The app then depends on the version of
 @lernapps/tooling that created it, and its workflows use the actions of that version's tag.
 
-It writes, besides the template: package.json named after the short name given to init (the folder's name without init) (its prepare script, lernapps hooks,
+It writes, besides the scaffold: package.json named after the short name given to init (the folder's name without init) (its prepare script, lernapps hooks,
 installs the git hooks; for an explainer and an interactive app also vue-tsc and typescript, with which lernapps
 check type-checks its Vue components; for an interactive app also @doctc/arc42, which checks its architecture),
 for an interactive app its architecture docs/arc42/ (the generic part and the interactive extension of app-templates,
@@ -96,7 +100,7 @@ export interface Manifest {
   version?: string;
   devDependencies?: Record<string, string>;
   scripts?: Record<string, string>;
-  lernapps?: { archetypes?: string[]; init?: boolean };
+  lernapps?: { archetypes?: string[]; scaffold?: Record<string, string[]>; init?: boolean };
   [key: string]: unknown;
 }
 
@@ -108,6 +112,8 @@ export interface Templates {
   root: string;
   version: string;
   archetypes: string[];
+  /** Per archetype, the paths of its template folder a new app gets (lernapps.scaffold of the package). */
+  scaffold: Record<string, string[]>;
 }
 
 /** The runtime package, which also carries the templates. */
@@ -133,7 +139,12 @@ export function templatesPackage(dir?: string): Templates {
     throw new CreateError(`${root} is no package ${RUNTIME}: it has no package.json`);
   }
   const manifest = readJson(join(root, "package.json"));
-  return { root, version: manifest.version ?? "0.0.0", archetypes: [...(manifest.lernapps?.archetypes ?? [])].sort() };
+  return {
+    root,
+    version: manifest.version ?? "0.0.0",
+    archetypes: [...(manifest.lernapps?.archetypes ?? [])].sort(),
+    scaffold: manifest.lernapps?.scaffold ?? {},
+  };
 }
 
 /** The archetypes of the installed templates. */
@@ -202,6 +213,34 @@ const packageName = (dir: string) =>
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "") || "app";
 
+/**
+ * The scaffold of the archetype into `dir` (decision dec-scaffold of app-templates): the paths of its template folder
+ * that lernapps.scaffold.<archetype> of the package lists (the entry, the configuration, the e2e entry), then the start
+ * content scaffold/<archetype>/, a placeholder the creator replaces. The rest of the template folder is the example
+ * app; it stays in node_modules/@lernapps/app-templates/<archetype>/ for the creator's assistant to look up.
+ */
+export function writeScaffold(templates: Templates, archetype: string, dir: string): void {
+  const paths = templates.scaffold[archetype];
+  if (paths === undefined || paths.length === 0) {
+    throw new CreateError(
+      `${templates.root} (version ${templates.version}) names no scaffold for ${archetype} (lernapps.scaffold in its package.json): use the version of ${RUNTIME} this tooling depends on`,
+    );
+  }
+  const template = join(templates.root, archetype);
+  for (const path of paths) {
+    // npm never ships a .gitignore: the package carries it as _gitignore (app-templates, scripts/pack-dotfiles.ts);
+    // a clone of the repository has the .gitignore itself
+    const shipped = basename(path) === ".gitignore" ? join(template, dirname(path), "_gitignore") : undefined;
+    const source = shipped !== undefined && existsSync(shipped) ? shipped : join(template, path);
+    if (!existsSync(source)) throw new CreateError(`${template} has no ${path}, which its scaffold lists`);
+    mkdirSync(dirname(join(dir, path)), { recursive: true });
+    cpSync(source, join(dir, path));
+  }
+  const start = join(templates.root, "scaffold", archetype);
+  if (!existsSync(start)) throw new CreateError(`${templates.root} has no start content scaffold/${archetype}/`);
+  cpSync(start, dir, { recursive: true });
+}
+
 /** This package, as an app depends on it. */
 export const TOOLING = "@lernapps/tooling";
 
@@ -399,21 +438,9 @@ export function create(args: string[]): number {
     ? readFileSync(join(dir, "package-lock.json"), "utf8")
     : undefined;
   mkdirSync(dir, { recursive: true });
-  cpSync(join(templates.root, archetype), dir, { recursive: true });
-  rmSync(join(dir, "package-lock.json"), { force: true }); // the template's lock, of another name and tooling
+  writeScaffold(templates, archetype, dir);
   if (initialLock !== undefined) writeFileSync(join(dir, "package-lock.json"), initialLock);
-  // npm never ships a .gitignore: the package carries it as _gitignore (app-templates, scripts/pack-dotfiles.ts)
-  if (existsSync(join(dir, "_gitignore"))) renameSync(join(dir, "_gitignore"), join(dir, ".gitignore"));
-  // the template's README says what the archetype can do, for choosing one; it is no part of the app
-  rmSync(join(dir, "README.md"), { force: true });
-  // the template folder's architecture is the extension of app-templates' own: an interactive app gets the
-  // combination as its reference, the other archetypes none
-  rmSync(join(dir, ARCHITECTURE), { recursive: true, force: true });
-  if (existsSync(join(dir, "docs")) && readdirSync(join(dir, "docs")).length === 0) {
-    rmSync(join(dir, "docs"), { recursive: true });
-  }
   if (architecture) writeArchitecture(dir, templates.root, archetype, templates.version);
-  else rmSync(join(dir, ".arc42ignore"), { force: true });
 
   const app = readJson(join(dir, "package.json"));
   // the short name the creator gave `lernapps init` stays the app's name; without init, the folder names it
@@ -427,7 +454,14 @@ export function create(args: string[]): number {
   // version of the runtime it was copied from
   if (app.devDependencies?.[RUNTIME] !== undefined) {
     app.devDependencies = { ...app.devDependencies, [RUNTIME]: `^${templates.version}` };
-    rmSync(join(dir, ".npmrc"), { force: true });
+  }
+  // the template keeps its checkout's runtime with an override (file:..), which npm would otherwise swap for the
+  // version this tooling depends on; the app has no checkout to point at
+  const overrides = app["overrides"];
+  if (typeof overrides === "object" && overrides !== null && RUNTIME in overrides) {
+    const kept = Object.fromEntries(Object.entries(overrides).filter(([name]) => name !== RUNTIME));
+    if (Object.keys(kept).length > 0) app["overrides"] = kept;
+    else delete app["overrides"];
   }
   // the tooling the app depends on: the one named, else this version (init may have installed it already)
   const tooling = values.tooling ?? `^${ownVersion()}`;

package/guidance/plan-template.md

@@ -101,7 +101,9 @@ questions. -->
   research, a data format).
 - Amount: how much content per level or chapter in the first version (e.g. "one text per school year"); what comes
   later.
-- Languages: German only, or more (texts, code).
+- Languages: German only, or German and English (texts, code). Never English only: an app without German still has
+  German pages and runtime texts, so it mixes both. The creator wants English → offer German and English,
+  both complete, and say why.
 - Look and feel: calm like a worksheet, or like a game (colours, praise, effects); dark mode.
 - Terms: the creator's words for the main things in the app, used everywhere.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lernapps/tooling",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Shared tooling of the lernapps.net apps and sites: the CLI lernapps, site actions, Renovate preset, guidance for building apps; documentation at https://lernapps.net/tooling/",
   "license": "MIT",
   "repository": {
@@ -107,7 +107,7 @@
     "arc42": "arc42 --dir docs/arc42"
   },
   "dependencies": {
-    "@lernapps/app-templates": "0.1.1",
+    "@lernapps/app-templates": "0.2.1",
     "axe-core": "4.14.0",
     "playwright": "1.64.1",
     "skills": "1.7.4",

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

@@ -8,7 +8,7 @@ license: MIT
 
 - You write YAML in `src/`; a Vue component only where the plan names one. Rendering, navigation, formulas, figures,
   exercises, accessibility, languages and the no-JS page come from the runtime `@lernapps/app-templates`.
-- `create` writes the example chapter "Prozent": replace it with the planned content.
+- `create` writes a placeholder: one chapter with one page and one exercise. Replace it with the planned content. The complete example, the chapter "Prozent" with a component, is in `node_modules/@lernapps/app-templates/explainer/`: look things up there, never copy it.
 - Schema: `node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json`. Start every YAML file with
   `# yaml-language-server: $schema=../../node_modules/@lernapps/app-templates/runtime/explainer/explainer.v1.schema.json`
   (one `../` less in `src/app.yaml`).

package/skills/archetypes/lernapps-explainer/references/blocks.md

@@ -69,6 +69,8 @@
 ## Languages
 
 - `languages` in `src/app.yaml`, German first: `[de]` or `[de, en]` (runtime texts: de, en).
+- Never English only: with `[de]` the pages and the runtime's texts are German, so English strings mix both.
+  English wanted → `[de, en]`.
 - A string = German, enough only while German is the only language. Else every text a map:
   `title: { de: Die drei Stände, en: The three estates }`.
 - Build fails on a missing translation (`the translation is missing; write the text as a map: { de: …, en: … }`)

package/skills/archetypes/lernapps-explainer/references/components.md

@@ -47,7 +47,7 @@
   `show(answer, task, props, lang)` (answer as text). An input of `params` that is no placeholder shows as
   "(verdeckt)": the tutor knows it, the child does not. One `template` per block: prefer one kind of task per block;
   else give the sentence that changes as an input (`{Aufgabe}`). `about.answer` names what the child does and "Prüfen". The build checks them against `check` for every number; rule `vue-component-tutor-table`. Model:
-  `ProzentFeld` of the template.
+  `ProzentFeld` of the template, in `node_modules/@lernapps/app-templates/explainer/src/components/`.
 - More: rule `vue-component-exercise-contract`.
 
 ## Rendering

package/skills/archetypes/lernapps-explainer/references/rules.md

@@ -194,7 +194,7 @@ severity: hint
 - The tutor page then has the task once, the mistakes as F1, F2 … and a table of every number (inputs, solution,
   each mistake), like `generated`. Without them: each number's `describe` as far as 64 kB allow, and the build's hint
   names the block.
-- Example: `src/components/ProzentFeld.ts` of the template.
+- Example: `node_modules/@lernapps/app-templates/explainer/src/components/ProzentFeld.ts`, the template's.
 
 ## `vue-component-tested`: A test per component
 

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

@@ -44,7 +44,8 @@ license: MIT
 
 ## Decide
 
-- Languages: German; English as a second language is supported. Each declared language complete.
+- Languages: German; English as a second language is supported. Each declared language complete. Never English
+  only: without `languages` the page and the runtime's texts are German. English wanted → `[de, en]`.
 - The tutor: the build writes it from the content. Plan only app-specific tutor rules, if any.
 
 ## Gotchas

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

@@ -7,7 +7,7 @@ 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.
+- `create` writes a placeholder: a counter as core, component and playthrough. Replace it with the planned parts. The complete example, a typing game, is in `node_modules/@lernapps/app-templates/interactive/`: look things up there, never copy it.
 
 ## What you write
 

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

@@ -39,7 +39,8 @@ license: MIT
 - 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.
+- Languages: German; each declared language complete; learner texts in message files, never in code. Never English
+  only: German comes first. English wanted → German and English.
 
 ## Gotchas
 

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

@@ -9,7 +9,7 @@ license: MIT
 - You write `src/quiz.json` and, for the content of its questions, the image files in `src/images/`. Engine, question
   types, feedback, scoring, order, accessibility and the no-JS page come from the runtime `@lernapps/app-templates`.
 - Schema: `node_modules/@lernapps/app-templates/runtime/quiz/quiz.v1.schema.json`.
-- `create` writes the example bank "Naturwunder der Welt": replace it with the planned questions.
+- `create` writes a placeholder bank with one question. Replace it with the planned questions. The complete example, the bank "Naturwunder der Welt", is in `node_modules/@lernapps/app-templates/quiz/`: look things up there, never copy it.
 - The fields of each question type and how to write good questions: skill `lernapps-content-questions`.
 
 ## Gotchas
@@ -50,7 +50,8 @@ license: MIT
 - German; more with `"languages": ["de", "en"]`, German first (runtime texts: de, en).
 - Then every learner text is a map with each language: title, intro, source titles; per question text, options,
   `info`, items, pairs, unit, explanation, link titles.
-- Without `languages`: German strings.
+- Without `languages`: German strings. The page is German then (`lang="de"`, the runtime's own texts such as
+  "Frage 1 von 5"); English strings give a page that mixes both. Never English only: English wanted → `[de, en]`.
 - Link `url`: one address, or a map per language (own Wikipedia).
 - Build errors, one line each, e.g.
   `questions[1].explanation (en) (question "totes-meer"): the translation is missing; write the text as a map: { de: …, en: … }`;

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

@@ -42,7 +42,8 @@ license: MIT
 
 ## Decide
 
-- Languages: German; English as a second language is supported. Each declared language complete.
+- Languages: German; English as a second language is supported. Each declared language complete. Never English
+  only: without `languages` the page and the runtime's texts are German. English wanted → `[de, en]`.
 - Keep the last score on the device (`rememberLastResult`) or nothing. Keeping it → the entry says
   `fitness.storage: device`.
 - Order: shuffled per seed; a link with `?seed=42` gives every learner the same order.

package/skills/tooling/lernapps-cli/references/platform-rules.md

@@ -147,6 +147,7 @@ severity: error
 ```
 
 - Texts for learners, teachers, parents: German, plain (short sentences, active voice, no jargon).
+- Never English only: an app in English is German and English, German first.
 - More languages only where the archetype supports them (explainer, quiz: `languages`, German first); each declared
   language complete, no other.
 - Texts out of code: in the content (explainer YAML, quiz bank) or message files (`src/messages/de.json`, shown