@lernapps/tooling 0.3.1 → 0.5.0

package/generator/create.ts

@@ -8,8 +8,9 @@
 // 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
 // with those of the tooling it moves the app to.
-// To move to a new app-templates: set the exact version of @lernapps/app-templates in package.json; the generator's
-// tests then run on that version.
+// To move to a new app-templates: set the exact version of @lernapps/app-templates in package.json, or a commit
+// (github:lernapps/app-templates#<commit>, which Renovate moves) until a release has what the tooling needs; the
+// generator's tests then run on that version. An app gets the same: ^ the version, or the same commit (runtimeSpec).
 import { spawnSync } from "node:child_process";
 import {
   cpSync,
@@ -49,7 +50,8 @@ node_modules init wrote). From the installed package @lernapps/app-templates, th
 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.
+node_modules/@lernapps/app-templates/<name>/, to look up. The app depends on the runtime of the same version (or
+the same commit, while @lernapps/tooling depends on an unreleased one).
 
 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
@@ -74,7 +76,10 @@ publish action to the repo's GitHub Pages), an issue form for content errors, LI
 Renovate preset of lernapps). The installed skills and skills-lock.json are committed with the app, like the
 content guide; lernapps update replaces the lernapps-* skills.
 
-Then: git init (if <dir> is not a repository yet), npm install (installs the git hooks), and the first commit.
+It installs nothing and commits nothing. Its last lines say what to do next, in this order: git init
+--initial-branch=work (only if <dir> is not a repository yet; lernapps init made one), npm install (installs the
+runtime and the git hooks), git add -A and git commit (the first commit, on work; the hooks check it), then follow
+the plan.
 
 Exit codes: 0 when the app is written, 1 when it cannot be (the message says why), 2 on a usage error.
 
@@ -84,8 +89,8 @@ Options:
                       its file name <NN>-<short name>.md, else 01-plan.md (default: the one in <dir>)
   --templates <dir>   the package @lernapps/app-templates to copy from: its folder, or a clone of its repository
                       (default: the environment variable LERNAPPS_TEMPLATES, else the installed package)
-  --tooling <spec>    the npm spec of @lernapps/tooling the app depends on (default: ^ the version of this
-                      @lernapps/tooling)
+  --tooling <spec>    the npm spec of @lernapps/tooling the app depends on (default: the one lernapps init
+                      installed, else ^ the version of this @lernapps/tooling)
   -h, --help          print this help
 `;
 
@@ -98,6 +103,7 @@ export const fromPackage = (...path: string[]) => join(packageRoot, ...path);
 export interface Manifest {
   name?: string;
   version?: string;
+  dependencies?: Record<string, string>;
   devDependencies?: Record<string, string>;
   scripts?: Record<string, string>;
   lernapps?: { archetypes?: string[]; scaffold?: Record<string, string[]>; init?: boolean };
@@ -147,6 +153,19 @@ export function templatesPackage(dir?: string): Templates {
   };
 }
 
+/** The version of a package built from a commit, not released: its package.json in the repository says 0.0.0. */
+const UNRELEASED = "0.0.0";
+
+/**
+ * The spec of the runtime an app depends on, for templates of `version`: ^ that version; for templates built from a
+ * commit (version 0.0.0, which the registry does not have) the spec this tooling depends on, the same commit
+ * (github:lernapps/app-templates#<commit>), so that template and runtime match.
+ */
+export function runtimeSpec(version: string): string {
+  if (version !== UNRELEASED) return `^${version}`;
+  return readJson(fromPackage("package.json")).dependencies?.[RUNTIME] ?? `^${version}`;
+}
+
 /** The archetypes of the installed templates. */
 export const archetypes = (): string[] => templatesPackage().archetypes;
 
@@ -241,6 +260,9 @@ export function writeScaffold(templates: Templates, archetype: string, dir: stri
   cpSync(start, dir, { recursive: true });
 }
 
+/** The branch the plan works on (rule 8 of the plan template). */
+export const WORK_BRANCH = "work";
+
 /** This package, as an app depends on it. */
 export const TOOLING = "@lernapps/tooling";
 
@@ -453,7 +475,7 @@ export function create(args: string[]): number {
   // the template uses the runtime of its own checkout (file:.., installed as a copy through .npmrc); the app the
   // version of the runtime it was copied from
   if (app.devDependencies?.[RUNTIME] !== undefined) {
-    app.devDependencies = { ...app.devDependencies, [RUNTIME]: `^${templates.version}` };
+    app.devDependencies = { ...app.devDependencies, [RUNTIME]: runtimeSpec(templates.version) };
   }
   // 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
@@ -463,8 +485,9 @@ export function create(args: string[]): number {
     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()}`;
+  // the tooling the app depends on: the one named, else the one init installed (maybe a local one, --tooling of
+  // init), else this version
+  const tooling = values.tooling ?? initialised?.devDependencies?.[TOOLING] ?? `^${ownVersion()}`;
   app.devDependencies = {
     ...app.devDependencies,
     ...ARCHETYPE_DEV_DEPENDENCIES[archetype],
@@ -490,7 +513,13 @@ export function create(args: string[]): number {
       `lernapps create: the ${archetype} app ${name} in ${dir} (app-templates ${templates.version})`,
       ...guide.map((line) => `Content guide: ${line}`),
       ...(moved ? [`Plan: moved ${LEGACY_PLAN} to ${relative(dir, plan.target)}`] : []),
-      `Next: ${existsSync(join(dir, ".git")) ? "" : "git init, "}npm install, then follow ${relative(dir, plan.target)}`,
+      "Next, in this order (create installs and commits nothing):",
+      ...[
+        ...(existsSync(join(dir, ".git")) ? [] : [`git init --initial-branch=${WORK_BRANCH}`]),
+        "npm install (the runtime and the git hooks)",
+        "git add -A, then git commit (the first commit; the hooks check it)",
+        `follow ${relative(dir, plan.target)}`,
+      ].map((step, index) => `  ${index + 1}. ${step}`),
       "",
     ].join("\n"),
   );

package/generator/init.ts

@@ -6,25 +6,28 @@
 // plan has chosen one: `skills --archetype <name>` then adds that archetype's. `lernapps create` later takes over the
 // package.json (the marker lernapps.init) and the installed packages.
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
 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";
-import { CreateError, fromPackage, ownVersion, readJson, TOOLING, writeJson } from "./create.ts";
+import { CreateError, fromPackage, ownVersion, readJson, TOOLING, WORK_BRANCH, writeJson } from "./create.ts";
 
 /** The options of `lernapps init`, as node:util parseArgs takes them. */
 export const INIT_OPTIONS = {
   addon: { type: "string" },
+  tooling: { type: "string" },
   help: { type: "boolean", short: "h", default: false },
 } as const satisfies ParseArgsOptionsConfig;
 
-export const INIT_USAGE = `Usage: lernapps init <short name> [--addon <package>]
+export const INIT_USAGE = `Usage: lernapps init <short name> [--addon <package>] [--tooling <spec>]
 
 Starts an app in the current folder, which must be empty except for .git. It needs git, Node and the npm registry; nothing
 else. In order:
-  git repository               on the branch work, which the plan names (unless the folder is one already; no commit)
+  git repository               on the branch work, which the plan names; no commit. A repository without commits
+                                switches to work; one with commits stays, and init warns: git switch -c work
   package.json                  names the folder, depends on @lernapps/tooling (this version) and the add-on
   npm install                   installs them
   .vibe/plans/01-<short name>.md
@@ -36,6 +39,12 @@ Then follow the plan: it says what to do, and when to wait for the creator.
 
 Options:
   --addon <package>  a package that extends the tooling, e.g. @lernapps/practice: its plan template and its skills
+  --tooling <spec>   for maintainers: the npm spec of @lernapps/tooling to install instead of this version, e.g.
+                     file:/path/to/lernapps-tooling-0.0.0.tgz or github:lernapps/tooling#<commit>; give the same
+                     to lernapps create. Without it, a tooling of version 0.0.0 (a local build, not on the
+                     registry) is packed with npm pack into a temporary folder and installed from that tarball
+                     when its folder is a git checkout (file:<tarball>), with its dependencies, as from the
+                     registry
   -h, --help         print this help
 `;
 
@@ -62,22 +71,45 @@ const SKILLS_BIN = () => {
   return join(dirname(manifest), bin?.["skills"] ?? "bin/cli.mjs");
 };
 
-/** The branch the plan works on (rule 8 of the plan template). */
-export const WORK_BRANCH = "work";
+export { WORK_BRANCH };
+
+/** A git command in `dir`; a git that cannot run is an error of init. */
+function git(dir: string, args: string[]) {
+  const result = spawnSync("git", args, { cwd: dir, encoding: "utf8" });
+  if (result.error) throw new CreateError(`git cannot run: ${result.error.message}. Install git, then run init again`);
+  return { ok: result.status === 0, out: `${result.stdout}${result.stderr}`.trim() };
+}
+
+/** What `ensureRepository` did: a line for the output, and a warning when the plan's branch is not checked out. */
+export interface Repository {
+  done?: string;
+  warning?: string;
+}
 
 /**
- * Makes the folder a git repository on the branch `work`, which the plan names, unless it is one already: `create` and
- * the hooks need it, and the plan's first rule is to work there. Returns what it did, for the output; no commit.
+ * Puts the folder on the branch `work`, which the plan names: `create` and the hooks need a repository, and the plan's
+ * first rule is to work there. No repository yet → `git init` on `work`. A repository without commits (a fresh
+ * `git init` on master or main, a clone of an empty GitHub repo) → its unborn branch becomes `work`: nothing is lost,
+ * since there is nothing on it. A repository with commits on another branch is left as it is, with a warning that
+ * names the command. No commit.
  */
-export function ensureRepository(dir: string): string | undefined {
-  if (existsSync(join(dir, ".git"))) return undefined;
-  const result = spawnSync("git", ["init", "--quiet", `--initial-branch=${WORK_BRANCH}`], {
-    cwd: dir,
-    encoding: "utf8",
-  });
-  if (result.error) throw new CreateError(`git cannot run: ${result.error.message}. Install git, then run init again`);
-  if (result.status !== 0) throw new CreateError(`git init failed: ${`${result.stdout}${result.stderr}`.trim()}`);
-  return `a git repository on the branch ${WORK_BRANCH}`;
+export function ensureRepository(dir: string): Repository {
+  if (!existsSync(join(dir, ".git"))) {
+    const result = git(dir, ["init", "--quiet", `--initial-branch=${WORK_BRANCH}`]);
+    if (!result.ok) throw new CreateError(`git init failed: ${result.out}`);
+    return { done: `a git repository on the branch ${WORK_BRANCH}` };
+  }
+  const branch = git(dir, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  if (branch.ok && branch.out === WORK_BRANCH) return {};
+  if (!git(dir, ["rev-parse", "--verify", "--quiet", "HEAD"]).ok) {
+    const result = git(dir, ["symbolic-ref", "HEAD", `refs/heads/${WORK_BRANCH}`]);
+    if (!result.ok) throw new CreateError(`git could not switch to the branch ${WORK_BRANCH}: ${result.out}`);
+    return { done: `the repository had no commit yet: now on the branch ${WORK_BRANCH}` };
+  }
+  const where = branch.ok ? `on the branch ${branch.out}` : "on no branch (detached HEAD)";
+  return {
+    warning: `the repository has commits and is ${where}, not on ${WORK_BRANCH}, which the plan works on. Run next: git switch -c ${WORK_BRANCH}`,
+  };
 }
 
 /** The names of the skills of the archetypes, with the archetype each belongs to (lernapps-<archetype>[-…]). */
@@ -121,6 +153,42 @@ function syncSkills(dir: string, exclude: string[]): void {
   );
 }
 
+/** The version of a build that is not on the registry: package.json of the repository says 0.0.0. */
+const LOCAL_VERSION = "0.0.0";
+
+/**
+ * The tarball of the package in `root`, packed by npm pack (with its prepare script, so the build is current) into a
+ * new temporary folder.
+ */
+export function packBuild(root: string): string {
+  const out = mkdtempSync(join(tmpdir(), "lernapps-tooling-"));
+  run("npm", ["pack", "--silent", "--pack-destination", out], (message) => new CreateError(message), root);
+  const tarball = readdirSync(out).find((name) => name.endsWith(".tgz"));
+  if (tarball === undefined) throw new CreateError(`npm pack in ${root} wrote no tarball into ${out}`);
+  return join(out, tarball);
+}
+
+/**
+ * The spec of @lernapps/tooling that init installs: the one given, else this version. A local build (version 0.0.0,
+ * which the registry does not have) is packed when its folder is a git checkout and installed from the tarball, else
+ * init says to name one with --tooling. Not the folder itself (file:<folder>): npm links it, so the app's
+ * node_modules lacks the tooling's dependencies (Playwright for the end-to-end tests, @lernapps/app-templates with
+ * the templates and their READMEs); from a tarball they are installed into the app, as from the registry.
+ */
+export function toolingSpec(
+  given: string | undefined,
+  version = ownVersion(),
+  root = fromPackage(),
+  pack: (root: string) => string = packBuild,
+): string {
+  if (given !== undefined && given !== "") return given;
+  if (version !== LOCAL_VERSION) return version;
+  if (existsSync(join(root, ".git"))) return `file:${pack(resolve(root))}`;
+  throw new CreateError(
+    `this @lernapps/tooling is a local build (version ${LOCAL_VERSION}), which the npm registry does not have: name the tooling to install with --tooling <spec>, e.g. file:/path/to/lernapps-tooling-${LOCAL_VERSION}.tgz (npm pack) or github:lernapps/tooling#<commit>, and give the same to lernapps create`,
+  );
+}
+
 export function init(args: string[]): number {
   const { values, positionals } = parseArgs({ args, options: INIT_OPTIONS, strict: true, allowPositionals: true });
   if (values.help) {
@@ -139,6 +207,7 @@ export function init(args: string[]): number {
     );
   }
   const addon = values.addon;
+  const tooling = toolingSpec(values.tooling);
   const repository = ensureRepository(dir);
   writeJson(join(dir, "package.json"), {
     name,
@@ -149,7 +218,7 @@ export function init(args: string[]): number {
   const fail = (message: string) => new CreateError(message);
   run(
     "npm",
-    ["install", "--save-dev", "--no-audit", "--no-fund", `${TOOLING}@${ownVersion()}`, ...(addon ? [addon] : [])],
+    ["install", "--save-dev", "--no-audit", "--no-fund", `${TOOLING}@${tooling}`, ...(addon ? [addon] : [])],
     fail,
   );
 
@@ -167,8 +236,9 @@ export function init(args: string[]): number {
     dir,
     archetypeSkills().map((skill) => skill.name),
   );
+  if (repository.warning !== undefined) process.stderr.write(`lernapps init: warning: ${repository.warning}\n`);
   process.stdout.write(
-    `lernapps init: ${relative(dir, target)} from ${relativeTemplate(template, dir)}; the skills of the packages are installed${repository ? `; ${repository}` : ""}\nNext: read ${relative(dir, target)} completely and follow it\n`,
+    `lernapps init: ${relative(dir, target)} from ${relativeTemplate(template, dir)}; the skills of the packages are installed${repository.done ? `; ${repository.done}` : ""}\nNext: ${repository.warning ? `git switch -c ${WORK_BRANCH}, then ` : ""}read ${relative(dir, target)} completely and follow it\n`,
   );
   return 0;
 }

package/generator/update.ts

@@ -7,7 +7,8 @@
 // them replaced with versions.
 // It never moves the runtime back: a newer version (Renovate moves the runtime too) stays. An app made before the
 // generator wrote the content guide gets its skeleton (generator/create.ts), and one made before the plans had a
-// folder gets its plan .vibe/plan.md moved to .vibe/plans/01-first-version.md (src/plan.ts). The app's lernapps-*
+// folder gets its plan .vibe/plan.md moved to .vibe/plans/01-first-version.md (src/plan.ts). An explainer in format 1 gets `format: 2` and `strand: none` in src/app.yaml where the runtime knows
+// format 2. The app's lernapps-*
 // skills, which the app commits, are replaced with those of this tooling (its skills/), in the layout of
 // `npx skills add`; the app's own skills (app-content, any other) stay as they are. An interactive app's architecture
 // is replaced outside its app sections, which stay as they are (generator/architecture.ts).
@@ -40,6 +41,7 @@ import {
   ownVersion,
   readJson,
   RUNTIME,
+  runtimeSpec,
   SKILLS_LOCK,
   templatesPackage,
   TOOLING,
@@ -57,13 +59,16 @@ export const UPDATE_USAGE = `Usage: lernapps update
 Moves the app in the current folder to the versions of this @lernapps/tooling, then runs npm install. npm update
 moves the app within its version ranges; this moves the ranges, and what npm does not know:
   @lernapps/app-templates  to the version this tooling depends on: the runtime its tests ran with. A newer version
-                           (e.g. from Renovate) is kept. A git commit, as apps once pinned, becomes a version
+                           (e.g. from Renovate) is kept. A git commit, as apps once pinned, becomes a version; while
+                           this tooling depends on a commit (an unreleased runtime), the app moves to that commit
   @lernapps/tooling        to the version of this tooling (unchanged when run from the app)
   .github/workflows/       the actions of lernapps/tooling at the tag of that version
   .agents/skills/app-content/SKILL.md
                            the content guide's skeleton, where the app has none yet (and its link for Claude Code)
   .vibe/plan.md            the plan of an app made before the plans had a folder: moved to
                            .vibe/plans/01-first-version.md, the first of its plans (one per piece of work)
+  src/app.yaml             of an explainer in format 1, when the runtime knows format 2: adds format: 2 and
+                           strand: none (the app is not on the learning map; its pages need no competencies)
   .agents/skills/lernapps-*, .claude/skills/lernapps-*, skills-lock.json
                            replaced with the skills of this tooling, as npx skills add lays them out: those of
                            every phase, and of the archetypes only those of the current plan's archetype; every
@@ -98,9 +103,16 @@ function lowest(range: string): [number, number, number] | undefined {
 const older = (a: [number, number, number], b: [number, number, number]) =>
   a[0] !== b[0] ? a[0] < b[0] : a[1] !== b[1] ? a[1] < b[1] : a[2] < b[2];
 
-/** The next range of a dependency at `version`, and what the output says about it. */
-export function nextRange(name: string, current: string | undefined, version: string): { spec: string; line: string } {
-  const target = `^${version}`;
+/**
+ * The next range of a dependency at `version` (target: ^ that version, or the spec given, e.g. a git commit of an
+ * unreleased runtime), and what the output says about it.
+ */
+export function nextRange(
+  name: string,
+  current: string | undefined,
+  version: string,
+  target = `^${version}`,
+): { spec: string; line: string } {
   // a local copy (a folder or a tarball of the package, as an app under development uses) is the creator's choice
   if (current !== undefined && /^(file:|link:|\.{0,2}\/)/.test(current)) {
     return { spec: current, line: `${name}: kept ${current}, a local copy` };
@@ -108,8 +120,9 @@ export function nextRange(name: string, current: string | undefined, version: st
   const now = current === undefined ? undefined : lowest(current);
   const next = lowest(version);
   if (current === target) return { spec: current, line: `${name}: unchanged (${current})` };
-  // a newer version than this tooling's stays: it must never move back
-  if (now !== undefined && next !== undefined && !older(now, next)) {
+  // a newer version than this tooling's stays: it must never move back; a commit (no version to compare) is where the
+  // tooling's tests ran, so the app moves to it
+  if (lowest(target) !== undefined && now !== undefined && next !== undefined && !older(now, next)) {
     return { spec: current ?? target, line: `${name}: kept ${current}, not moved to ${target}: it is not older` };
   }
   return { spec: target, line: `${name}: ${current ?? "none"} → ${target}` };
@@ -148,6 +161,35 @@ function migratePlan(): string[] {
   ];
 }
 
+/** The explainer's app file, and the schema file that tells the runtime knows format 2 (learning map). */
+const EXPLAINER_APP = join("src", "app.yaml");
+const EXPLAINER_V2_SCHEMA = join("runtime", "explainer", "explainer.v2.schema.json");
+
+/**
+ * Moves an explainer from format 1 to format 2 (the learning map): adds `format: 2` and `strand: none` to
+ * src/app.yaml when the app has neither, and points its schema comment to explainer.v2.schema.json. `strand: none`
+ * keeps the app off the map, so its pages need no competencies; the creator may name a strand later (skill
+ * lernapps-content-research). Only where the runtime of this tooling has the v2 schema: an older runtime does not
+ * know the fields. An app that is no explainer, or already has a `format` or a `strand`, stays as it is. What it did,
+ * as lines of the output.
+ */
+export function migrateExplainer(templatesRoot: string): string[] {
+  if (!existsSync(EXPLAINER_APP) || !existsSync(join(templatesRoot, EXPLAINER_V2_SCHEMA))) return [];
+  const text = readFileSync(EXPLAINER_APP, "utf8");
+  const top = (key: string) => new RegExp(`^${key}:`, "m").test(text);
+  if (!top("chapters") || top("format") || top("strand")) return [];
+  const schema = /^(# yaml-language-server: \$schema=.*)explainer\.v1\.schema\.json$/m;
+  const fields = "format: 2\nstrand: none\n";
+  let next: string;
+  if (schema.test(text))
+    next = text.replace(schema, (_all, head: string) => `${head}explainer.v2.schema.json\n${fields.trimEnd()}`);
+  else next = fields + text;
+  writeFileSync(EXPLAINER_APP, next);
+  return [
+    `explainer: ${EXPLAINER_APP} moved to format 2: added format: 2 and strand: none (not on the learning map; pages need no competencies). To join the map, pick a strand of https://lernapps.net/apps/map/ and give every page competencies`,
+  ];
+}
+
 /**
  * The skills of this tooling, as it ships them (skills/<group>/<name>/), and as the app keeps them (flat, by name).
  * Every app has those of the groups process, tooling and content; of the group archetypes only those of its own
@@ -371,7 +413,7 @@ export function update(args: string[]): number {
   const notMoved: string[] = [];
   const runtime = devDependencies[RUNTIME];
   if (runtime !== undefined) {
-    const next = nextRange(RUNTIME, runtime, templates.version);
+    const next = nextRange(RUNTIME, runtime, templates.version, runtimeSpec(templates.version));
     if (next.spec !== runtime) specs.push(`${RUNTIME}@${next.spec}`);
     lines.push(next.line);
   }
@@ -404,6 +446,8 @@ export function update(args: string[]): number {
   lines.push(...guide.map((line) => `content guide: ${line}`));
   const plan = migratePlan();
   lines.push(...plan);
+  const explainer = migrateExplainer(templates.root);
+  lines.push(...explainer);
   const skills = [...replaceSkills(), ...unignoreSkills()];
   lines.push(...skills);
   const architecture = updateArchitecture();
@@ -421,6 +465,7 @@ export function update(args: string[]): number {
   if (skillsMoved) files.push(SKILLS_LOCK);
   if (skills.some((line) => line.includes(".gitignore"))) files.push(".gitignore");
   if (architecture.lines.length > 0) files.push(`${ARCHITECTURE}/`);
+  if (explainer.length > 0) files.push(EXPLAINER_APP);
   if (plan.some((line) => line.startsWith("plan: moved"))) files.push(".vibe/ (git add -A .vibe, to keep the move)");
   process.stdout.write(
     `Next: npx --no -- lernapps check, then commit ${files.slice(0, -1).join(", ")} and ${files.at(-1) ?? ""}\n`,

package/guidance/increment-template.md

@@ -45,7 +45,7 @@ a correction.
 
 ## Notes
 
-<!-- Curriculum orientation, new competencies by chapter, didactic approach, scope, sources and licences, open
+<!-- Curriculum orientation, new competencies by chapter (ids of the strand), didactic approach, scope, sources and licences, open
 questions. -->
 
 ## Explore
@@ -68,12 +68,19 @@ questions. -->
       "(guess)". Topics: which competencies, chapters or rounds, for which school years; hurdles and examples;
       amount; any change of look and feel or terms.
 - [ ] Load skill `lernapps-content-research`. Research what the guide's curriculum and sources do not cover. Under
-      "Notes": curriculum orientation, new competencies by chapter as "Ich kann …", verified sources.
+      "Notes": curriculum orientation, new competencies by chapter as "Ich kann …", verified sources. The app keeps its
+      strand; with one, the new competencies are only those of that strand in the learning map (ids), as skill
+      `lernapps-content-research` says, an explainer as a rule one page each; competencies that build on each other (the
+      map's `requires`) share a chapter, in that order. None in the map → propose it to the
+      catalog. `strand: none` and a strand fits → recommend it.
 - [ ] Under "Notes": the didactic approach per competency and the scope (in, out, data range).
 - [ ] A kind of content the guide does not cover (a new page structure, screen, component or kind of exercise) →
       load skills `lernapps-<archetype>-design` and `lernapps-exercise-patterns`. Else skip this task.
-- [ ] **Checkpoint:** research. Show in plain words: curriculum orientation, new competencies by chapter, didactic
-      approach, scope, every "(guess)", sources and how you checked them, what is unchecked. Stop and wait.
+- [ ] **Checkpoint:** research. Show in plain words: curriculum orientation, new competencies by chapter (with their
+      ids), didactic
+      approach, scope, every "(guess)", sources and how you checked them, what is unchecked. With a strand, the map
+      decides the structure: new competencies that build on each other (its `requires`) share a chapter, in that
+      order; no curriculum search is needed for it. Stop and wait.
       Changes → change, ask again.
 - [ ] Set `phase: plan`: change the value line (`grep '^phase:'` prints `phase: plan`).
 
@@ -110,7 +117,8 @@ questions. -->
 ### Content method
 
 <!-- One line each: the guide's patterns, figures and components used, and where; anything new, what it does and
-cannot. Something new goes into the guide in the slice that adds it. -->
+cannot; an explainer on the map: per new page its prerequisites the app does not practise, and which get a recap
+page, which a link. Something new goes into the guide in the slice that adds it. -->
 
 ### Completed
 

package/guidance/plan-template.md

@@ -42,7 +42,7 @@ For you, the assistant.
 
 ## Notes
 
-<!-- Curriculum orientation, competencies by chapter, didactic approach, scope, sources and licences, open
+<!-- Strand (<subject>/<strand> or none), curriculum orientation, competencies by chapter (ids), didactic approach, scope, sources and licences, open
 questions. -->
 
 ## Explore
@@ -59,7 +59,7 @@ questions. -->
 
 - [ ] The skills of the phases are in `.agents/skills/` (`npx --yes @lernapps/tooling init <short name>` put them there
       and wrote this plan; the app commits them). `.agents/skills/lernapps-app` missing → stop and tell the creator
-      the folder was not started with `init`.
+      the folder was not started with `init`. `git branch --show-current` prints `work`; else `git switch -c work`.
 - [ ] Load skill `lernapps-app`. Tell the creator in two sentences what a lernapps app is and where it will live: at
       their own address, free, public, and once listed as a copy on lernapps.net. The technical part (GitHub) comes at the end, and you do it.
 - [ ] Interview: ask the topics "Goal" and "Learners" of "Answers".
@@ -74,7 +74,11 @@ questions. -->
       which. No answer → ask once more; still none → write your assumption with "(guess)". Done when every topic
       has an answer or a guess.
 - [ ] Load skill `lernapps-content-research`. Research as it says. Under "Notes": curriculum orientation,
-      competencies by chapter as "Ich kann …", verified sources. No competencies → not done.
+      competencies by chapter as "Ich kann …", verified sources. No competencies → not done. First the learning map as
+      skill `lernapps-content-research` says: recommend a strand that fits (`<subject>/<strand>`), else `none`; with a
+      strand, only its competencies, by their ids from the map. Write both under "Notes", and how they map onto
+      chapters and pages (an explainer: as a rule one page per competency; competencies that build on each other, by
+      the map's `requires`, share a chapter, in that order).
 - [ ] Under "Notes", one line per competency: how learners get there (derive, not only read off; e.g. a tree diagram
       shows how a probability comes about), which misconception the feedback catches.
 - [ ] Under "Notes", the scope: what is in, what is out and why, the data range (e.g. "all main-group elements",
@@ -82,8 +86,10 @@ questions. -->
 - [ ] Fetch https://lernapps.net/apps/schemas/entry.v1.schema.json and read each property's description. Ask what
       helps teachers and parents find the app. Fill "Entry draft". Search words: one or two words each, as people
       type them.
-- [ ] **Checkpoint:** research. Show in plain words: curriculum orientation, competencies by chapter, didactic
-      approach, scope, every "(guess)", sources and how you checked them, what is unchecked, archetype and reason.
+- [ ] **Checkpoint:** research. Show in plain words: the strand or why none, curriculum orientation, competencies by
+      chapter (with their ids) and their pages, didactic approach, scope, every "(guess)", sources and how you
+      checked them, what is unchecked, archetype and reason. With a strand, the map decides the structure: competencies
+      that build on each other (its `requires`) share a chapter, in that order; no curriculum search is needed for it.
       Stop and wait. Changes → change, ask again.
 - [ ] Set `phase: plan`: change the value line (`grep '^phase:'` prints `phase: plan`).
 
@@ -132,11 +138,12 @@ questions. -->
 - [ ] Map the content as skill `lernapps-<archetype>-design` says; reread it if it is no longer in view.
 - [ ] Choose a pattern per competency as skill `lernapps-exercise-patterns` says (loaded in Explore; reread it if it
       is no longer in view). Write "Content method".
-- [ ] Write the Code tasks under "Code": pages or screens, their content, what each shows. Each ends in a commit.
+- [ ] Write the Code tasks under "Code": pages or screens, their content, what each shows. Each ends in a commit:
+      one task, one commit. Steps too small for a commit of their own → one task.
       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. 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
+- [ ] Show the creator, short: goal, competencies by chapter (chapters along the map's `requires`), 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
       explicit yes. Changes → change, ask again. No `create` before the yes.
@@ -145,7 +152,8 @@ questions. -->
 ### Content method
 
 <!-- One line each: exercise patterns and where; figures and how they are made; data files; each component, what it
-checks and cannot; how a later agent adds a chapter. Becomes the content guide in Code. -->
+checks and cannot; how a later agent adds a chapter. An explainer on the map: per page its prerequisites (`requires`)
+the app does not practise, and which get a recap page, which a link. Becomes the content guide in Code. -->
 
 ### Completed
 
@@ -153,7 +161,8 @@ checks and cannot; how a later agent adds a chapter. Becomes the content guide i
 
 <!--
 - Build the app from the archetype and the confirmed plan, locally on `work`. Work on your own.
-- Commit after each task; the hooks check. A check fails → skill `lernapps-cli`. Fix from the message; never
+- Commit after each task, literally: one task, one commit, its box ticked in it; the hooks check. Never one commit
+  for several tasks: join them into one task in the plan first. A check fails → skill `lernapps-cli`. Fix from the message; never
   bypass a hook.
 - Undecidable → choose, mark "(guess)" under "Key decisions", go on.
 - Creator asks for a change → first say your reading in one sentence ("Ich nehme alle 44 Hauptgruppenelemente
@@ -168,10 +177,15 @@ checks and cannot; how a later agent adds a chapter. Becomes the content guide i
 - [ ] Load skill `lernapps-cli`. Create the app in this plan's folder as it says. `create` keeps this plan. Never
       write the app by hand.
 - [ ] Fill the content guide `.agents/skills/app-content/SKILL.md` from "Notes" and "Content method"
-      (`app-content-guide`). `grep -c "FILL IN" .agents/skills/app-content/SKILL.md` prints 0. Commit it before
-      any content.
+      (`app-content-guide`). Keep its nine headings and fill each: Curriculum, Competencies, Content structure,
+      Terminology, Exercise patterns, Figures, Sources, Adding a chapter or round, Rules learned from mistakes
+      ("None yet." until the first). `grep -c "FILL IN" .agents/skills/app-content/SKILL.md` prints 0. Commit it
+      before any content.
 - [ ] Load skill `lernapps-<archetype>` and the content guide. Questions with options and feedback: also skill
       `lernapps-content-questions`.
+- [ ] An explainer: decide on `scope` as `references/structure.md` of skill `lernapps-explainer` says. Needed with an
+      `open-task` or the creator's material: then `scope` in `src/app.yaml` and on every page
+      (`explainer-scope-matches`). Write the choice under "Key decisions".
 - [ ] <the tasks written in Plan; after each, commit on `work`; after the first with real content, show the
       creator a first look (`early-preview`) and go on>
 - [ ] The content guide matches what was built (`app-content-matches`).

package/guidance/workflow-rules.md

@@ -87,7 +87,9 @@ scope: tooling
 severity: error
 ```
 
-- Keep `.agents/skills/app-content/SKILL.md` with its fixed headings.
+- Keep `.agents/skills/app-content/SKILL.md` with its fixed headings, in this order, each filled: Curriculum,
+  Competencies, Content structure, Terminology, Exercise patterns, Figures, Sources, Adding a chapter or round,
+  Rules learned from mistakes ("None yet." until the first rule).
 - After the plan is confirmed and before content: replace every placeholder ("FILL IN") with concrete instructions
   for writing new content: files, ids, data files, an example of this app. Not how the app works, no general advice.
 - A content decision changes (pattern, figure type, source rule) → change the guide in the same commit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lernapps/tooling",
-  "version": "0.3.1",
+  "version": "0.5.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": {
@@ -107,7 +107,7 @@
     "arc42": "arc42 --dir docs/arc42"
   },
   "dependencies": {
-    "@lernapps/app-templates": "0.2.1",
+    "@lernapps/app-templates": "github:lernapps/app-templates#4fdc214e60ce4523d8233d3ed9b37641601b2fa9",
     "axe-core": "4.14.0",
     "playwright": "1.64.1",
     "skills": "1.7.4",
@@ -115,7 +115,7 @@
   },
   "devDependencies": {
     "@doctc/arc42": "0.38.0",
-    "@lernapps/site": "github:lernapps/lernapps.github.io#8b6c98f76170c313519d04b38937a48747c05b09",
+    "@lernapps/site": "github:lernapps/lernapps.github.io#0f6257d3dffcbf69ffe962d0b80bd7298a62de02",
     "@types/node": "26.6.5",
     "ajv": "8.20.0",
     "vite-plus": "1.4.0"