explico 0.14.0 → 0.15.0

package/docs/authoring/deck.md

@@ -586,3 +586,27 @@ that says what the student can now do.
 _Enforcement._ Review-only: the engine writes both frames.
 
 _Exceptions._ None.
+
+## D11
+
+**A deck is flagged when its chapter changed, by rule C5’s version, after the deck itself last did.**
+
+Two files mean the chapter and the deck can drift apart with nothing to notice
+it: `deck-stale` is an info diagnostic naming a lesson's own deck whose
+chapter's version (rule C5) is newer than the deck's.
+
+_Rationale._ The deck recalls the chapter's results and follows its argument; a
+chapter that moved on is easy to miss from inside the deck file, which never
+changed itself.
+
+_How to apply._ When `deck-stale` names a deck, read what changed in the
+chapter since, and judge whether the deck's frames, notes or recalls need the
+same update. A deck the lecturer knows is still correct needs nothing further;
+there is no build failure to clear.
+
+_Enforcement._ Build-enforced (`page-versions.ts`, `pnpm validate:content`):
+`deck-stale`, info. Needs rule C5 on — it is what gives a chapter and a deck
+each their own version to compare.
+
+_Exceptions._ A part's deck, which covers more than one chapter: it has no
+single chapter to compare against, so it is never flagged.

package/docs/authoring/migrating.md

@@ -30,9 +30,11 @@ The pattern every time:
 4. Make every required course-side change named by those sections, including
    changes under `content/`, Astro/source configuration, and course scripts; do
    not stop after changing the dependency declaration.
-5. `pnpm validate:content` (it passes on its first run: it rewrites
-   `build/resolution/*` and fails only on a report git tracks that it had to
-   rewrite), then `pnpm content check --changed`, then `astro check`, then
+5. `pnpm content verify` (0.15 and later), or by hand: `pnpm validate:content`
+   (it rewrites `build/resolution/*` and fails only on a report git tracks that
+   it had to rewrite: a course whose `build/` is git-ignored passes on the
+   first run, one that commits it commits the rewritten reports and runs it
+   again), then `pnpm content check --changed`, then `astro check`, then
    `astro build`.
    Each stage names what it doesn't like; fix and re-run.
 
@@ -41,6 +43,128 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.14.0 → 0.15.0
+
+**No course changes required.** This release adds verbs (`content help
+<verb>`, `content verify`, `content release`, `content fix --all`), rule D11's
+`deck-stale` info, and better messages; the manifest schema stays v37. Two
+steps are conditional: a course that ran `content move --write` on 0.14.0
+(step 4), and a course whose tests read the CLI's text output (step 6).
+
+### 1. Update the dependency
+
+```bash
+pnpm add explico@<this version>
+```
+
+pnpm 11 holds back a release younger than its `minimumReleaseAge`: either
+`pnpm add` stops with `ERR_PNPM_NO_MATURE_MATCHING_VERSION`, or pnpm adds an
+`explico@<version>` line to `minimumReleaseAgeExclude` in
+`pnpm-workspace.yaml` itself. Add that line when it does not, and commit it.
+
+### 2. Rule D11: a deck whose chapter moved on — nothing to do
+
+Rule D11 adds an info diagnostic, `deck-stale`, naming a lesson's own deck
+whose chapter changed, by rule C5's version, after the deck itself last did. A
+part's deck covers several chapters and is never flagged. Nothing to
+configure; a course without decks sees nothing.
+
+### 3. Optional: let `pnpm content verify` be the course's verification
+
+`pnpm content verify` runs `validate:content`, `content check --changed`,
+`astro check`, the course's `test` script and `astro build` (with `--e2e`, its
+`test:e2e` script too), and answers at once on a tree its last pass covered. It
+reaches a course through the `scripts/content.ts` shim of 0.14.0 step 14 and
+needs nothing else. Where the course's `AGENTS.md`, README or `package.json`
+spells that sequence out by hand, it can say `pnpm content verify` instead; a
+`verify` script becomes `"verify": "pnpm content verify"`. The pass record and
+the logs go to `node_modules/.cache/explico/verify/`, never into the tree.
+`astro check` is skipped, by name, when `@astrojs/check` is not installed.
+
+### 4. Only if you ran `content move --write` on 0.14.0: the card's placeholder body
+
+0.14.0's `content move` wrote every card it created a placeholder body,
+"Promoted from `<lesson>`'s `notation.local`; the meaning above is what that
+page said. Extend this body with what a glossary reader needs.", which the
+glossary publishes. Find them:
+
+```bash
+grep -rl "Extend this body with what a glossary reader needs" content/notation
+```
+
+Replace each with what a reader needs beyond the meaning, or delete the body
+(a card needs none). Check those cards' `domain:` too: 0.14.0 wrote `general`
+for a key without a prefix. From this release `move` writes no body, takes the
+domain the course's own cards use, and says what the author still owes.
+
+### 5. Rule N4's lints: better advice, and the run log counts them — nothing to do
+
+`definition-repeated` on a local entry whose glyph a shared card already owns
+no longer says "move one copy to `content/notation/`": the entry is a reused
+letter (rule N4), and promoting it would put two shared cards on one glyph. It
+says how to acknowledge the copies instead (`definition-repeated:<key> — <why>`
+in `lint-ignore.yml`), and `content move` cautions before writing such a card.
+`validate:content`'s run log records each consistency warning at WARNING now,
+so the `Run log: (… warning(s))` line it prints matches `pnpm content status`
+where it used to say 1; nothing fails on a warning.
+
+The `explain-redundant` infos an upgrade to 0.14.0 left (a thousand, in one
+course) clear in one plan: `pnpm content fix --all` shows the diff and
+`--write` applies it. It edits lessons, so it is a content change: a bullet in
+`content/CHANGELOG.md` (rule C1) and the version bump rule C2 asks for.
+
+### 6. Only if a course test reads the CLI's text output
+
+The `--json` reports did not change; a test that reads them keeps passing, and
+`pnpm content help <verb> --json` now prints each one's JSON Schema. The text
+did change:
+
+- `pnpm content help`: every usage line ends in `[--json]`; `release`,
+  `verify` and `help` are listed, and `fix` reads `<lesson>… | --all`.
+- `content check`: a lesson's info is one line counted by code
+  (`+ 28 info (…)`); errors and warnings are listed as before.
+- `content status`: at most six of the pages with unreleased changes, then
+  `… N more in --json`.
+- `content context`: `diagnostics: N (M in <file>, K in the shared cards it
+  shows)` when some come from the cards.
+- `content init-agent`: `new` or `differs from the engine's copy` where it
+  said `installed` or `refreshed from the engine`; after `--write` every edit
+  verb prints a `next:` line.
+- `dia-too-wide` on `<CurriculumMap>`'s graph (rule V8) names the map's props.
+
+Match the `--json` instead of the text.
+
+### 7. Optional: refresh the agent procedures; content releases with `content release`
+
+`pnpm content release [major|minor|patch]` cuts a content release (rule C3):
+`## [Unreleased]` in `content/CHANGELOG.md` becomes a dated `## [x.y.z]` and
+`about.version` becomes `x.y.z`, as a diff that `--write` applies. With no
+argument the bump is what the section's headings imply under rule C2
+(`### Breaking` or `### Removed` a MAJOR, `### Added` a MINOR, else a PATCH);
+check it against the rule. Then `pnpm validate:content` and commit the three
+files together. 0.14.0's `release-content` skill called
+`pnpm release:content`, a script only the playground had; a course that wrote
+its own can make it `"release:content": "pnpm content release --write"`.
+
+`pnpm content init-agent --write` refreshes the installed skills:
+`draft-lesson` and `migrate-course` now end on `pnpm content verify`, and
+`release-content` runs `pnpm content release`. It never edits an existing
+`AGENTS.md`; the shipped baseline
+(`node_modules/explico/docs/course-agent/AGENTS.md`) shows the two lines to
+copy: `pnpm content verify` before handing back (step 3), and
+`pnpm content help <verb>`, which prints a verb's flags and the shape of its
+`--json` ([`cli.md`](cli.md) has every verb).
+
+### 8. Verify
+
+```bash
+pnpm content verify          # add --e2e when the course has browser tests
+```
+
+The manifest schema did not move, so a course that commits
+`build/resolution/` sees no rewritten report, and `content/versions.json`
+changes only where step 4 or step 5 edited content.
+
 ## 0.13.1 → 0.14.0
 
 **One course change is required, two are recommended, and a rare page needs
@@ -95,16 +219,24 @@ warning needs no course workaround.
 
 ### 1. Update the dependency
 
+**A course on 0.13.0 or 0.13.1, first:** delete the downstream patch that
+added `dist/components/float-name.js` to the installed package
+(`patches/explico@0.13.1.patch`) and its `patchedDependencies` entry, in
+`pnpm-workspace.yaml` or under `pnpm` in `package.json`, and any test that
+pins the old path. This release compiles the module as
+`dist/reference/float-name.js`, which the export serializers import, and
+pnpm refuses the upgrade with `ERR_PNPM_UNUSED_PATCH` while an entry names a
+patch for a version no longer installed. Then:
+
 ```bash
 pnpm add explico@<this version>
 ```
 
-**A course on 0.13.0 or 0.13.1** also stops needing the downstream patch that
-added `dist/components/float-name.js` to the installed package
-(`patches/explico@0.13.1.patch`, or a `pnpm.patchedDependencies` entry): this
-release compiles the module as `dist/reference/float-name.js`, which the
-export serializers import. Delete the patch and its `patchedDependencies`
-entry, reinstall, and delete any test that pins the old path.
+pnpm 11 holds back a release younger than its `minimumReleaseAge`: either
+`pnpm add` stops with `ERR_PNPM_NO_MATURE_MATCHING_VERSION`, or pnpm adds an
+`explico@<version>` line to `minimumReleaseAgeExclude` in
+`pnpm-workspace.yaml` itself. Add that line when it does not, and commit it
+with the upgrade.
 
 **Coming from 0.12.0 or earlier:** apply "0.13.0 → 0.13.1" and "0.12.0 →
 0.13.0" below first.
@@ -358,7 +490,10 @@ until the commit carries the file. The first record has no history to draw
 on: while `## [Unreleased]` holds bullets, every page reads "with changes after
 version `x.y.z`, not yet released", `x.y.z` being `about.version`, until the
 next release stamps them all; with an empty `## [Unreleased]`, every page reads
-"unchanged since version `x.y.z`". Earlier releases are not reconstructed.
+"unchanged since version `x.y.z`". Earlier releases are not reconstructed. So
+the order matters: write the first record before adding the upgrade's own
+bullet under `## [Unreleased]` (rule C1), or every page reads "not yet
+released" although none changed.
 
 What counts as a page's content: its file, its `.checks.yml` and the
 assessments it lists, the shared notation entries its text uses, the sources
@@ -580,7 +715,9 @@ now fails only on a report git tracks that it had to rewrite, so a course whose
 `build/` is git-ignored passes on the first run; delete any "run it twice"
 instruction from the course's own AGENTS.md. A course that commits
 `build/resolution/` (credit-and-derivatives) keeps committing the rewritten
-files with the change, as before.
+files with the change, as before — and this upgrade rewrites every one (the
+schema version moved), so its first run fails with a `[resolution-report] …
+out of date` line per report. Commit them; the next run passes.
 
 Optional, in `scripts/content.ts`: print diagnostics through
 `formatCliDiagnostic` (and `ownerTag` in the `check` case), both exported from
@@ -832,6 +969,10 @@ To write a part's deck:
   declared exception and is no longer reported, so every
   `glyph-unique-in-corpus:<glyph> — …` line in `lint-ignore.yml` that
   acknowledged a page-local reuse can be deleted (they are harmless if kept).
+  It can also report a pair 0.13.1 did not: two shared cards on one glyph
+  where one card is named only in the other's `formula:` (data-science-I's
+  `\pi`, a prior density and the circle constant). Give one a different glyph,
+  or acknowledge the pair.
 - `definition-repeated` (warning): one `notation.local` key declared in two
   or more chapters (a deck beside its chapter never counts). Run
   `pnpm content diagnostics warning --code definition-repeated`; each line
@@ -849,6 +990,14 @@ To write a part's deck:
   is for a compound or a colliding glyph. Optional to clear.
 - `gloss-wants-promoting` is gone; delete any `lint-ignore.yml` line for it.
 
+Nothing reports a `lint-ignore.yml` line that no longer matches: search the
+file for `glyph-unique-in-corpus` and `gloss-wants-promoting` yourself. A
+course test that pins the list of consistency codes, or exercises
+`gloss-wants-promoting`, needs the new list. And reread the course's own
+notation guidance (its AGENTS.md, a style guide): advice such as "gloss
+first", or a local entry as the default for a new symbol, now contradicts N4 —
+one shared card per glyph, a local entry or a gloss only for a reused letter.
+
 ### 21. The glossary: nothing to do, unless your CSS or tests read it
 
 The glossary page gains a section "On one page only" (`.glossary-page-meanings`)
@@ -942,11 +1091,9 @@ editUrl: false
 
 import { LinkButton } from '@astrojs/starlight/components';
 
-<div style="display: flex; justify-content: center;">
-  <LinkButton href={import.meta.env.BASE_URL} icon="left-arrow" iconPlacement="start">
-    Return to the course
-  </LinkButton>
-</div>
+<LinkButton href={import.meta.env.BASE_URL} icon="left-arrow" iconPlacement="start">
+  Return to the course
+</LinkButton>
 ```
 
 `import.meta.env.BASE_URL` points home from the originally requested URL and
@@ -990,8 +1137,11 @@ shadow, a step lighter than the page in the dark theme (`appearance.slides:
 darker than before, so it stays visible on the grey. The manifest schema is
 now v37, with `appearance`.
 
-No course change is required. To choose another look, add the block to
-`content/course.settings.json`:
+No course change is required, except in a browser test that compares a
+sidebar's background with the page's: they now differ by a step of grey (in
+the dark theme `rgb(32, 35, 42)` against `rgb(23, 24, 28)`), so the test reads
+the zone's own colour or the course sets `"zones": "none"`. To choose another
+look, add the block to `content/course.settings.json`:
 
 ```json
 "appearance": { "zones": "paper", "slides": "edge" }

package/docs/authoring/versioning.md

@@ -97,7 +97,8 @@ one commit:
    `content/versions.json`, where every page changed since the last release
    takes `x.y.z` ([C5](#c5)); commit it in the same commit.
 
-`pnpm release:content` does steps 2 and 3 for you.
+`pnpm content release [major|minor|patch]` does steps 2 and 3 for you: it
+shows the diff, and `--write` applies it.
 
 _Enforcement._ Build-enforced (Tier-3, `knowledge-version.ts`
 `resolveKnowledgeVersion`). `pnpm validate:content` emits

package/docs/course-agent/AGENTS.md

@@ -10,15 +10,18 @@ https://danieltuzes.github.io/explico/start/ ([`sources.json`](https://danieltuz
 
 ## The loop
 
-- `pnpm content help` lists the CLI. Start every task there, not with a file
-  hunt: `content context <lesson>` for a lesson's scope, `content rules
-  [--element …]` for the rules this course has on, `content rule <ID>` for one
-  of them whole, `content symbol <latex>` before declaring any notation.
+- `pnpm content help` lists the CLI, and `pnpm content help <verb>` gives one
+  verb's flags and the shape of its `--json`. Start every task there, not with
+  a file hunt: `content context <lesson>` for a lesson's scope,
+  `content rules [--element …]` for the rules this course has on,
+  `content rule <ID>` for one of them whole, `content symbol <latex>` before
+  declaring any notation.
 - While writing math: `content equation "<latex>" --lesson <id>`; after:
   `content bindings <lesson>` and `content check <lesson>`.
-- Before handing back: `pnpm validate:content` (passes on its first run; commit
-  `content/versions.json` if it changed), `pnpm content check --changed`,
-  `astro check`, `astro build`.
+- Before handing back: `pnpm content verify` — `validate:content`,
+  `content check --changed`, `astro check`, the course's tests, `astro build`;
+  `--e2e` adds the browser tests. A rerun on an unchanged tree answers at once. Commit
+  `content/versions.json` if `validate:content` changed it.
 - Every content change adds a bullet under `## [Unreleased]` in
   `content/CHANGELOG.md` (rule C1).
 - Upgrading `explico`: `pnpm content migrate` prints exactly the sections to

package/docs/course-agent/agents/rules-reviewer.md

@@ -22,8 +22,8 @@ with `pnpm -s content …`.
    read the lesson file (`content/docs/<slug>.mdx`) with line numbers.
 3. `pnpm -s content rules --enforcement guide` lists the rules this course has
    on that no script checks, by element, each with a one-line summary. Apply
-   only those; a rule absent from the list is off. Open `pnpm -s content rule
-   <ID>` only when a summary does not settle a doubt.
+   only those; a rule absent from the list is off. Open
+   `pnpm -s content rule <ID>` only when a summary does not settle a doubt.
 4. Read the lesson once, rule list beside it, and note each place a guide-only
    rule is not followed: the rule id, the line, what you saw, the fix in one
    clause. A JSX prop string (`caption="…"`) is not prose for the math rules.

package/docs/course-agent/skills/draft-lesson/SKILL.md

@@ -13,9 +13,9 @@ whose `package.json` has the `content` script); `pnpm content help` lists them.
    notation, references, assumptions and sources (a new lesson:
    `pnpm content new lesson <id>` scaffolds it).
 2. **Rules.** `pnpm content rules --element <prose,table,…>` lists only the
-   rules this course has on, with enforcement and codes; `pnpm content rule
-   <ID>` prints one whole, example included. A rule absent from the list is
-   off: neither apply it nor flag it.
+   rules this course has on, with enforcement and codes;
+   `pnpm content rule <ID>` prints one whole, example included. A rule absent
+   from the list is off: neither apply it nor flag it.
 3. **Notation, one question per symbol: is it already defined?**
    `pnpm content symbol <latex>`. A card with this meaning exists → reference
    it: `[[key]]` once in prose, bare math after; `\explain{key}{…}` only for a
@@ -32,6 +32,7 @@ whose `package.json` has the `content` script); `pnpm content help` lists them.
    for the rest; the counts come first, the lines on request.
 6. **Record.** A bullet under `## [Unreleased]` in `content/CHANGELOG.md`
    (rule C1); `pnpm validate:content` rewrites `content/versions.json`, which
-   is committed with the change (rule C5). Guide-only rules (`enforcement
-   guide`) have no check: before handing back, have the `rules-reviewer`
-   agent review the lesson, or review the draft against them yourself.
+   is committed with the change (rule C5). Guide-only rules
+   (`enforcement guide`) have no check: before handing back, have the
+   `rules-reviewer` agent review the lesson, or review the draft against them
+   yourself, and run `pnpm content verify`.

package/docs/course-agent/skills/migrate-course/SKILL.md

@@ -23,9 +23,10 @@ work or says no course changes are required.
    whose `scripts/content.ts` predates the shim), read the sections from
    `node_modules/explico/docs/authoring/migrating.md`; the section that
    introduced the shim says how to switch to it.
-4. The checks each section ends with, then: `pnpm validate:content` (passes on
-   its first run; commit `content/versions.json` if it changed),
-   `pnpm content check --changed`, `astro check`, `astro build`, and the
-   course's browser tests if it has any.
+4. The checks each section ends with, then `pnpm content verify --e2e`:
+   `validate:content` (passes on its first run; commit `content/versions.json`
+   if it changed), `content check --changed`, `astro check`, the course's
+   tests, `astro build` and its browser tests. An engine older than the
+   `verify` verb: run those by hand.
 5. Commit the dependency change, the migration edits and the generated files
    together, naming the versions in the message.

package/docs/course-agent/skills/release-content/SKILL.md

@@ -15,9 +15,11 @@ each page's own version in `content/versions.json` (rule C5).
 2. Pick the bump (rule C2): MAJOR when a lesson, competency or notation key
    was removed or renamed or a stated outcome changed; MINOR for something
    new; PATCH for a fix or clarification.
-3. From the course package: `pnpm release:content [major|minor|patch]`. It
-   moves `[Unreleased]` to a dated `## [x.y.z]` heading and sets
-   `about.version` to match in the same change (rule C3).
+3. From the course package: `pnpm content release [major|minor|patch]` shows
+   the release as a diff: `[Unreleased]` moved to a dated `## [x.y.z]`
+   heading and `about.version` set to match, in one change (rule C3). With no
+   bump it takes the one the section's headings imply; check that it agrees
+   with step 2. Add `--write` to apply it.
 4. `pnpm validate:content`: no `knowledge-*` warning; it rewrites
    `content/versions.json` — commit that file with the release, never edit it
    by hand.

package/docs/diagram-scaling.md

@@ -1,11 +1,11 @@
 # Diagram scaling on touch screens
 
-> **Status.** In `[Unreleased]` (see [`CHANGELOG.md`](../CHANGELOG.md)).
+> **Status.** Released in [0.14.0](../CHANGELOG.md).
 > Checked in Chromium, in the end-to-end suite and by measurement. **Not
 > checked in WebKit** (Safari, every iOS browser): no WebKit build is available
 > to the agent sessions that wrote it. It uses the technique the print path
 > already uses for WebKit, but a person should look at a diagram on an iPhone
-> before a release ([Checking it](#checking-it)).
+> to confirm it ([Checking it](#checking-it)).
 
 A diagram is drawn in px at build time. On a phone, the reader's own text-size
 menu shrinks the whole drawing, boxes and text together, so that a wide diagram

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
   "type": "module",
   "license": "UNLICENSED",