@lernapps/tooling 0.1.2 → 0.2.0

package/dist/cli.mjs

@@ -809,7 +809,7 @@ const SCREENSHOTS_OPTIONS = {
 	},
 	width: {
 		type: "string",
-		default: "390"
+		default: "360"
 	},
 	desktop: {
 		type: "boolean",
@@ -846,8 +846,8 @@ which shows the figures with their page, in the folder --out. The folder is empt
 
 Options:
   --out <dir>    the folder of the images (default screenshots)
-  --width <px>   the width of the images in pixels (default 390, a phone)
-  --desktop      also images 1280 px wide; every image is then named with its width (01-index-390.png,
+  --width <px>   the width of the images in pixels (default 360, a phone)
+  --desktop      also images 1280 px wide; every image is then named with its width (01-index-360.png,
                  01-index-1280.png, 01-index-figure-1-1280.png)
   -h, --help     print this help
 `;
@@ -1445,7 +1445,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 folder (its prepare script, lernapps hooks,
+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,
 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,
@@ -1527,7 +1527,7 @@ function contents(dir) {
 		if (name === ".git" || name === "skills-lock.json" && skills.size > 0) return [];
 		if (name === "node_modules" || name === "package-lock.json") return [];
 		if (name === "package.json" && readJson(join(dir, name)).lernapps?.init === true) return [];
-		if (name === ".vibe") return within(name, (file) => file === "plan.md" || file === "plans").concat(existsSync(join(dir, ".vibe/plans")) ? within(PLANS, (file) => PLAN_NAME.test(file)) : []);
+		if (name === ".vibe") return existsSync(join(dir, ".vibe/plans")) ? within(PLANS, (file) => PLAN_NAME.test(file)) : [];
 		if ((name === ".agents" || name === ".claude") && skills.size > 0) return within(name, (folder) => folder === "skills").concat(existsSync(join(dir, name, "skills")) ? within(`${name}/skills`, (skill) => skills.has(skill)) : []);
 		return [name];
 	});
@@ -1691,7 +1691,7 @@ function create(args) {
 	if (positionals.length > 1) throw new UsageError(`one <dir> at most, not ${positionals.join(" ")}`);
 	const dir = resolve(positionals[0] ?? ".");
 	const found = contents(dir);
-	if (found.length > 0) throw new CreateError(`${dir} is not empty (${found.slice(0, 5).join(", ")}${found.length > 5 ? ", ..." : ""}): create the app in an empty folder; only .git, the first version's plan .vibe/plans/01-<short name>.md and what lernapps init wrote (its skills, package.json, package-lock.json and node_modules) may be there`);
+	if (found.length > 0) throw new CreateError(`${dir} is not empty (${found.slice(0, 5).join(", ")}${found.length > 5 ? ", ..." : ""}): create the app in an empty folder; only .git, .vibe/ (the first version's plan .vibe/plans/01-<short name>.md, and its sketches) and what lernapps init wrote (its skills, package.json, package-lock.json and node_modules) may be there`);
 	const plan = confirmedPlan(dir, archetype, values.plan);
 	const architecture = ARCHITECTURE_ARCHETYPES.includes(archetype);
 	if (!existsSync(join(templates.root, archetype, "package.json"))) throw new CreateError(`${templates.root} has no template ${archetype}/ (version ${templates.version})`);
@@ -1711,7 +1711,7 @@ function create(args) {
 	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 = packageName(dir);
+	const name = initialised?.lernapps?.init === true && typeof initialised.name === "string" ? initialised.name : packageName(dir);
 	app.name = name;
 	app.scripts = {
 		...app.scripts,
@@ -1860,8 +1860,6 @@ function syncSkills(dir, exclude) {
 		...filters.length > 0 ? ["--exclude", ...filters] : []
 	], (message) => new CreateError(message), dir);
 }
-/** A package name from the folder's name: lower case, letters, digits and hyphens. */
-const slug = (dir) => basename(dir).toLowerCase().normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "app";
 function init(args) {
 	const { values, positionals } = parseArgs({
 		args,
@@ -1881,7 +1879,7 @@ function init(args) {
 	const addon = values.addon;
 	const repository = ensureRepository(dir);
 	writeJson(join(dir, "package.json"), {
-		name: slug(dir),
+		name,
 		version: "0.0.0",
 		private: true,
 		lernapps: { init: true }

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

@@ -44,7 +44,7 @@ a submission they declare something about.
   (`…-figure-<n>.png`): a page image is scaled down, its details are not readable. `--desktop` adds 1280 px images.
   Options: `npx --no -- lernapps screenshots --help`. The folder ignores itself in git, so a later check never sees it.
 - Interactive app: `screenshots` does not support it. Open the built app with the Playwright the tooling installs
-  (`import { chromium } from "playwright"`), at 390 px width, and take `page.screenshot({ fullPage: true })` of each
+  (`import { chromium } from "playwright"`), at 360 px width, and take `page.screenshot({ fullPage: true })` of each
   state the creator should see, from a short script outside the app.
 
 ## A check fails

package/dist/skills/lernapps-content-questions/references/question-types.md

@@ -7,7 +7,7 @@
 | `true-false` | `answer` (true or false) |
 | `number` | `answer`, `tolerance` (0 = exact), `unit` if any; the learner may type a comma or a point |
 | `ordering` | `items` in the right order; the page mixes them |
-| `matching` | `pairs` as they belong; the page mixes the right side. `distractors` (1 to 4): wrong right entries that match no left one. `pairsFrom: material` instead of `pairs` takes them from the `labelled-figure` in `material` (marker left, text right; the figure needs `legend: false`) |
+| `matching` | `pairs` as they belong, each pair an object `{ left, right }`; the page mixes the right side. `distractors` (1 to 4): wrong right entries that match no left one. `pairsFrom: material` instead of `pairs` takes them from the `labelled-figure` in `material` (marker left, text right; the figure needs `legend: false`) |
 
 - Every question: `id`, `text`, `explanation`, at least one link in `links`. Optional quiz `sources`.
 - Types without options carry their background in `explanation`.

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

@@ -5,6 +5,7 @@
 - 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.
+- Check each in its own image of `npx --no -- lernapps screenshots`, not in the page image.
 - 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/dist/skills/lernapps-explainer/SKILL.md

@@ -28,6 +28,8 @@ license: MIT
 
 - A build problem is one line `file:line: place (language): what to do`. Fix where it points.
 - Headings are `section` blocks, never Markdown headings.
+- YAML: quote a text that has `: ` in it or looks like a number (`"8."`, `"01000001"`, `"0"`). Unquoted, YAML reads a map or a
+  number: the build stops, or the digits change. A table cell, a header cell too, is a text and never empty.
 - A new chapter: a folder with `chapter.yaml`, listed in `src/app.yaml`, each page listed in `chapter.yaml`.
 - `selfAssessment` in a `chapter.yaml`: written in Commit, skill
   `lernapps-explainer-self-assessment`. An exercise it names renamed or moved → change the reference too.

package/generator/create.ts

@@ -57,7 +57,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 folder (its prepare script, lernapps hooks,
+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,
 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,
@@ -174,9 +174,9 @@ function contents(dir: string): string[] {
     if (name === "node_modules" || name === "package-lock.json") return [];
     if (name === "package.json" && readJson(join(dir, name)).lernapps?.init === true) return [];
     if (name === ".vibe") {
-      return within(name, (file) => file === "plan.md" || file === "plans").concat(
-        existsSync(join(dir, PLANS)) ? within(PLANS, (file) => PLAN_NAME.test(file)) : [],
-      );
+      // the planning folder: the plans are checked (a first version has one), what the planning leaves beside them stays
+      // (the sketches of the plan, .vibe/sketches/)
+      return existsSync(join(dir, PLANS)) ? within(PLANS, (file) => PLAN_NAME.test(file)) : [];
     }
     if ((name === ".agents" || name === ".claude") && skills.size > 0) {
       return within(name, (folder) => folder === "skills").concat(
@@ -384,7 +384,7 @@ export function create(args: string[]): number {
   const found = contents(dir);
   if (found.length > 0) {
     throw new CreateError(
-      `${dir} is not empty (${found.slice(0, 5).join(", ")}${found.length > 5 ? ", ..." : ""}): create the app in an empty folder; only .git, the first version's plan .vibe/plans/01-<short name>.md and what lernapps init wrote (its skills, package.json, package-lock.json and node_modules) may be there`,
+      `${dir} is not empty (${found.slice(0, 5).join(", ")}${found.length > 5 ? ", ..." : ""}): create the app in an empty folder; only .git, .vibe/ (the first version's plan .vibe/plans/01-<short name>.md, and its sketches) and what lernapps init wrote (its skills, package.json, package-lock.json and node_modules) may be there`,
     );
   }
   const plan = confirmedPlan(dir, archetype, values.plan);
@@ -416,7 +416,9 @@ export function create(args: string[]): number {
   else rmSync(join(dir, ".arc42ignore"), { force: true });
 
   const app = readJson(join(dir, "package.json"));
-  const name = packageName(dir);
+  // the short name the creator gave `lernapps init` stays the app's name; without init, the folder names it
+  const name =
+    initialised?.lernapps?.init === true && typeof initialised.name === "string" ? initialised.name : packageName(dir);
   app.name = name;
   // npm install installs the hooks of this package, in the app's own repository only (lernapps hooks); the
   // template needs no prepare script of its own, which would install them in app-templates

package/generator/init.ts

@@ -8,7 +8,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { basename, dirname, join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { parseArgs, type ParseArgsOptionsConfig } from "node:util";
 import { UsageError } from "../src/usage.ts";
 import { PLANS } from "../src/plan.ts";
@@ -121,15 +121,6 @@ function syncSkills(dir: string, exclude: string[]): void {
   );
 }
 
-/** A package name from the folder's name: lower case, letters, digits and hyphens. */
-const slug = (dir: string) =>
-  basename(dir)
-    .toLowerCase()
-    .normalize("NFKD")
-    .replace(/[̀-ͯ]/g, "")
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "") || "app";
-
 export function init(args: string[]): number {
   const { values, positionals } = parseArgs({ args, options: INIT_OPTIONS, strict: true, allowPositionals: true });
   if (values.help) {
@@ -150,7 +141,7 @@ export function init(args: string[]): number {
   const addon = values.addon;
   const repository = ensureRepository(dir);
   writeJson(join(dir, "package.json"), {
-    name: slug(dir),
+    name,
     version: "0.0.0",
     private: true,
     lernapps: { init: true },

package/guidance/AGENTS.md

@@ -15,6 +15,8 @@ Learning app for lernapps.net: static, runs in the browser, collects nothing, ac
 
 - Read guidance and skills from the file, in full. Never use a fetch tool that summarises.
 - Push only the branch the current plan names. A push to `main` publishes.
+- Tick a box only after you did what it says, and only as far as it says. A box you did in part stays open, with a line
+  saying what is missing.
 - Never `--no-verify`. Never edit `prePushFailures` or `failedChecks`.
 - Never edit a `lernapps-*` skill: `lernapps update` replaces them. The app's own skills (`app-content`, `app-*`)
   take precedence; app rules go there.

package/guidance/increment-template.md

@@ -100,7 +100,7 @@ questions. -->
       `lernapps-<archetype>-design` says, choose its pattern with skill `lernapps-exercise-patterns` (both loaded
       in Explore), and say why the guide's patterns do not fit.
 - [ ] Each new component or interactive exercise: a sketch (static SVG or image, or the steps). Words alone are not
-      enough.
+      enough. Keep sketch files in `.vibe/sketches/`.
 - [ ] Show the creator, short: goal, new competencies by chapter, slices; in plain words what learners see and do,
       what is new. At most 2 questions.
 - [ ] **Checkpoint:** confirm the plan and the content method. Stop and wait for an explicit yes. Changes → change,
@@ -138,6 +138,7 @@ cannot. Something new goes into the guide in the slice that adds it. -->
 - [ ] The content guide describes the app as it is now (`app-content-matches`). `grep -c "FILL IN"
       .agents/skills/app-content/SKILL.md` prints 0.
 - [ ] `npx --no -- lernapps check` passes.
+- [ ] Look at `npx --no -- lernapps screenshots --desktop`, each figure in its own image.
 - [ ] Every box of Explore, Plan and Code ticked.
 - [ ] Set `phase: commit`: change the value line (`grep '^phase:'` prints `phase: commit`).
       No checkpoint here: set it before you ask or report anything, then start Commit in the same message.

package/guidance/plan-template.md

@@ -133,7 +133,7 @@ questions. -->
 - [ ] Write the Code tasks under "Code": pages or screens, their content, what each shows. Each ends in a commit.
       After the first task that shows real content: the task "Show the creator a first look (`early-preview`)".
 - [ ] Each screen, component or interactive exercise: a sketch (static SVG or image, or the steps with what
-      learners see after each). Words alone are not enough.
+      learners see after each). Words alone are not enough. Keep sketch files in `.vibe/sketches/`, which `create` leaves alone.
 - [ ] Show the creator, short: goal, competencies by chapter, entry draft, tasks, sketches; the content method in
       plain words (what learners see and do, what it cannot do). At most 2 questions.
 - [ ] **Checkpoint:** confirm the plan and the content method, with the sketches shown. Stop and wait for an
@@ -175,7 +175,7 @@ checks and cannot; how a later agent adds a chapter. Becomes the content guide i
 - [ ] The content guide matches what was built (`app-content-matches`).
 - [ ] `npx --no -- lernapps check` passes.
 - [ ] Look at a screenshot of every screen and state (start, each mode, pause, end), desktop and 360 px. Compare
-      each with the confirmed sketches.
+      each with the confirmed sketches; each figure in its own image (`npx --no -- lernapps screenshots --desktop`).
 - [ ] Every box of Explore, Plan and Code ticked.
 - [ ] Set `phase: commit`: change the value line (`grep '^phase:'` prints `phase: commit`).
       No checkpoint here: set it before you ask or report anything, then start Commit in the same message.

package/guidance/workflow-rules.md

@@ -60,8 +60,8 @@ severity: hint
 ```
 
 - In Code, as soon as the first screen or page shows real content: send the creator a short "Zwischenstand".
-- Show screenshots, desktop and 360 px. On the creator's machine also the address of `npm run dev`, started in the
-  background.
+- Show screenshots, desktop and 360 px (`npx --no -- lernapps screenshots --desktop`). On the creator's machine also the
+  address of `npm run dev`, started in the background.
 - No checkpoint, no question: go on in the same message. The creator may stop you or ask for a change.
 - Example: "Zwischenstand: So sieht die erste Seite aus. Ich baue weiter; sag Bescheid, wenn etwas nicht passt."
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lernapps/tooling",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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": {
@@ -115,7 +115,7 @@
   },
   "devDependencies": {
     "@doctc/arc42": "0.38.0",
-    "@lernapps/site": "github:lernapps/lernapps.github.io#96912a0b6691d90a538ac8336ac808152a7a2227",
+    "@lernapps/site": "github:lernapps/lernapps.github.io#15473cb8e782c69b2a38d45208bbe7eaf8a6c698",
     "@types/node": "26.6.5",
     "ajv": "8.20.0",
     "vite-plus": "1.4.0"

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

@@ -28,6 +28,8 @@ license: MIT
 
 - A build problem is one line `file:line: place (language): what to do`. Fix where it points.
 - Headings are `section` blocks, never Markdown headings.
+- YAML: quote a text that has `: ` in it or looks like a number (`"8."`, `"01000001"`, `"0"`). Unquoted, YAML reads a map or a
+  number: the build stops, or the digits change. A table cell, a header cell too, is a text and never empty.
 - A new chapter: a folder with `chapter.yaml`, listed in `src/app.yaml`, each page listed in `chapter.yaml`.
 - `selfAssessment` in a `chapter.yaml`: written in Commit, skill
   `lernapps-explainer-self-assessment`. An exercise it names renamed or moved → change the reference too.

package/skills/content/lernapps-content-questions/references/question-types.md

@@ -7,7 +7,7 @@
 | `true-false` | `answer` (true or false) |
 | `number` | `answer`, `tolerance` (0 = exact), `unit` if any; the learner may type a comma or a point |
 | `ordering` | `items` in the right order; the page mixes them |
-| `matching` | `pairs` as they belong; the page mixes the right side. `distractors` (1 to 4): wrong right entries that match no left one. `pairsFrom: material` instead of `pairs` takes them from the `labelled-figure` in `material` (marker left, text right; the figure needs `legend: false`) |
+| `matching` | `pairs` as they belong, each pair an object `{ left, right }`; the page mixes the right side. `distractors` (1 to 4): wrong right entries that match no left one. `pairsFrom: material` instead of `pairs` takes them from the `labelled-figure` in `material` (marker left, text right; the figure needs `legend: false`) |
 
 - Every question: `id`, `text`, `explanation`, at least one link in `links`. Optional quiz `sources`.
 - Types without options carry their background in `explanation`.

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

@@ -5,6 +5,7 @@
 - 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.
+- Check each in its own image of `npx --no -- lernapps screenshots`, not in the page image.
 - 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/tooling/lernapps-cli/SKILL.md

@@ -44,7 +44,7 @@ a submission they declare something about.
   (`…-figure-<n>.png`): a page image is scaled down, its details are not readable. `--desktop` adds 1280 px images.
   Options: `npx --no -- lernapps screenshots --help`. The folder ignores itself in git, so a later check never sees it.
 - Interactive app: `screenshots` does not support it. Open the built app with the Playwright the tooling installs
-  (`import { chromium } from "playwright"`), at 390 px width, and take `page.screenshot({ fullPage: true })` of each
+  (`import { chromium } from "playwright"`), at 360 px width, and take `page.screenshot({ fullPage: true })` of each
   state the creator should see, from a short script outside the app.
 
 ## A check fails