explico 0.14.0 → 0.15.0

package/dist/compiler/page-versions.js

@@ -181,11 +181,30 @@ function syncPageVersions(manifest, options = {}) {
   writeFileSync(path, expected);
   return { path, stale: true, written: true, changed };
 }
+function deckStaleDiagnostics(decks, chapterSince) {
+  const out = [];
+  for (const deck of decks) {
+    if (deck.chapter === void 0) continue;
+    const chapterVersion = chapterSince.get(deck.chapter);
+    if (chapterVersion === void 0) continue;
+    if (compareKnowledgeVersions(chapterVersion, deck.since) <= 0) continue;
+    const chapterChange = chapterVersion === null ? "has unreleased changes" : `changed in version ${chapterVersion}`;
+    out.push({
+      context: "structure",
+      severity: "info",
+      code: "deck-stale",
+      file: deck.file,
+      message: `The chapter ${chapterChange}; this deck is still from version ${deck.since}.`
+    });
+  }
+  return out;
+}
 export {
   PAGE_VERSIONS_FILE,
   PAGE_VERSIONS_FORMAT,
   PAGE_VERSIONS_GENERATED_BY,
   compareKnowledgeVersions,
+  deckStaleDiagnostics,
   newestSince,
   nextPageVersions,
   pageSourceDigest,

package/dist/compiler/validate-content.js

@@ -86,7 +86,7 @@ Run log: ${summary2.relativeDirectory}.`);
   const consistencyWarnings = consistency.filter((diagnostic) => diagnostic.severity === "warning");
   if (consistencyWarnings.length > 0) {
     console.warn(
-      log.warning(
+      log.info(
         "consistency",
         `[consistency] ${consistencyWarnings.length} Tier-3 finding(s): ` + Object.entries(consistencyCounts(consistencyWarnings)).filter(([, count]) => count > 0).map(([code, count]) => `${code}=${count}`).join(", ")
       )
@@ -94,7 +94,7 @@ Run log: ${summary2.relativeDirectory}.`);
   }
   log.infoDiagnostics(manifest.diagnostics);
   for (const diagnostic of consistencyWarnings) {
-    log.info("consistency", `[${diagnostic.code}] ${diagnostic.message}`);
+    log.warning("consistency", `[${diagnostic.code}] ${diagnostic.message}`);
   }
   const reports = syncResolutionReports(manifest);
   console.log(

package/dist/reference/consistency.js

@@ -159,6 +159,10 @@ function checkDefinitionRepeated(input, out) {
       byKey.set(definition.key, list);
     }
   }
+  const sharedByGlyph = /* @__PURE__ */ new Map();
+  for (const definition of input.notationInput.sharedDefinitions) {
+    if (!sharedByGlyph.has(definition.notation.trim())) sharedByGlyph.set(definition.notation.trim(), definition.key);
+  }
   for (const [key, copies] of [...byKey].sort(([a], [b]) => a.localeCompare(b))) {
     if (copies.length < 2) continue;
     if (input.lintIgnore.matches("definition-repeated", key)) continue;
@@ -167,6 +171,8 @@ function checkDefinitionRepeated(input, out) {
       (field) => copies.some((copy) => JSON.stringify(copy.definition[field] ?? null) !== JSON.stringify(first.definition[field] ?? null))
     );
     const lessons = copies.map((copy) => copy.lessonId).sort();
+    const owner = sharedByGlyph.get(first.definition.notation.trim());
+    const advice = owner !== void 0 && owner !== key ? ` \u2014 its glyph is already shared card ${owner}'s, so it is a reused letter (rule N4) and promoting it would put two shared cards on one glyph (glyph-unique-in-corpus): keep the copies local and acknowledge them in lint-ignore.yml ("definition-repeated:${key} \u2014 <why>"), or, if they are two meanings, give one another key` : ` \u2014 move one copy to content/notation/${key}.md and delete the others: every [[${key}]] and \\explain{${key}} keeps working; if they are two meanings, give one another key`;
     out.push({
       code: "definition-repeated",
       severity: "warning",
@@ -174,7 +180,7 @@ function checkDefinitionRepeated(input, out) {
       lessonId: first.lessonId,
       file: first.file,
       count: copies.length,
-      message: `local entry ${key} (${first.definition.notation}) is declared in ${copies.length} lessons (${lessons.join(", ")}); ` + (differing.length === 0 ? "the copies agree" : `the copies differ in ${differing.join(", ")}`) + ` \u2014 move one copy to content/notation/${key}.md and delete the others: every [[${key}]] and \\explain{${key}} keeps working; if they are two meanings, give one another key`
+      message: `local entry ${key} (${first.definition.notation}) is declared in ${copies.length} lessons (${lessons.join(", ")}); ` + (differing.length === 0 ? "the copies agree" : `the copies differ in ${differing.join(", ")}`) + advice
     });
   }
 }

package/dist/reference/diagram-fit.d.ts

@@ -29,7 +29,11 @@ declare const DEFAULT_COLUMN_WIDTH = 707;
  * `warnAboveWidth` replaces the course's column width for that diagram.
  */
 declare function diagramWidthLimit(warnAboveWidth: number | false | undefined, rules: Pick<ManifestRules, 'disabled' | 'settings'> | undefined): number | undefined;
-/** What to tell the author about one diagram wider than its limit. */
+/**
+ * What to tell the author about one diagram wider than its limit. The
+ * competency graph is `<CurriculumMap>`'s, whose nodes the author does not
+ * write, so its advice names the map's own props.
+ */
 declare function diagramTooWideMessage(id: string, width: number, limit: number): string;
 /** A diagram on a built page that is wider than its limit. */
 interface OversizedDiagram {

package/dist/reference/diagram-fit.js

@@ -7,7 +7,11 @@ function diagramWidthLimit(warnAboveWidth, rules) {
   return typeof columnWidth === "number" ? columnWidth : DEFAULT_COLUMN_WIDTH;
 }
 function diagramTooWideMessage(id, width, limit) {
-  return `Diagram "${id}" lays out ${Math.round(width)}px wide, wider than the ${limit}px it may take (rule V8), so a reader has to scroll it or widen it to see it whole. Try direction="TB", a shorter label, or a narrower node \`width\` (its label wraps inside it); set warnAboveWidth={false} only when the diagram is meant to scroll.`;
+  const head = `Diagram "${id}" lays out ${Math.round(width)}px wide, wider than the ${limit}px it may take (rule V8), so a reader has to scroll it or widen it to see it whole. `;
+  if (id.startsWith("competency-graph")) {
+    return head + `It is <CurriculumMap>'s competency graph: try graph="per-part" (one graph per part) and direction="LR" or "TB" on the map; set warnAboveWidth={false} there when no layout fits and the graph is meant to scroll.`;
+  }
+  return head + `Try direction="TB", a shorter label, or a narrower node \`width\` (its label wraps inside it); set warnAboveWidth={false} only when the diagram is meant to scroll.`;
 }
 function isElement(node) {
   return "tagName" in node;

package/dist/rules/catalog.js

@@ -1050,6 +1050,22 @@ const RULES = [
     doc: "deck.md#d10",
     summary: "The title frame (the lesson, the course, its authors and version) and the closing frame (the outcomes of the competencies the lesson teaches, `deck.outcomesFrame`) are generated: do not write them. With `deck.outcomesFrame` off, end on a `###` frame that says what the student can now do.",
     checks: []
+  },
+  {
+    kind: "rule",
+    id: "D11",
+    editions: "deck",
+    short: "A deck is flagged when its chapter changed after it did",
+    title: "A deck is flagged when its chapter changed, by rule C5\u2019s version, after the deck itself last did.",
+    elements: ["slide", "changelog"],
+    doc: "deck.md#d11",
+    summary: "No authoring action by itself: 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\u2019s own deck whose chapter\u2019s rule C5 version is newer than the deck\u2019s; read the chapter\u2019s change and judge whether the deck needs it too. Scoped to a lesson\u2019s own deck \u2014 a part\u2019s deck covers more than one chapter, so it has none to compare against.",
+    checks: [
+      check("deck-stale", "info", false, {
+        module: "src/compiler/page-versions.ts",
+        fn: "deckStaleDiagnostics"
+      })
+    ]
   }
 ];
 const RETIRED = [

package/dist/rules/in-effect.d.ts

@@ -1,4 +1,4 @@
-import { Element, Enforcement, Editions, Edition } from './catalog.js';
+import { Element, Enforcement, Edition, Editions } from './catalog.js';
 import { M as ManifestRules } from '../course-config-BLtIdkei.js';
 import './course-rules.js';
 

package/dist/rules/in-effect.js

@@ -93,7 +93,8 @@ function renderRulesInEffect(input, filter = {}) {
       ""
     ] : [],
     "Generated by `pnpm validate:content` (and `pnpm content rules`) from the rule",
-    "catalog and `rules` / `courseRules` in `course.settings.json`. Do not edit. Read this before",
+    "catalog and the course's `rules` / `courseRules` (`course.settings.json`, or",
+    "`course.config.ts`). Do not edit. Read this before",
     "drafting, and open a rule page only when it is listed here and you need the",
     "example: a rule absent from this page is either off for this course or does",
     "not exist, and is neither applied nor flagged in review.",
@@ -104,8 +105,8 @@ function renderRulesInEffect(input, filter = {}) {
     ].filter(Boolean).join("; ")} \u2014 ${visible.length} shown.` : ""),
     "",
     "A line is `ID \xB7 enforcement \xB7 codes \u2014 what to do (settings in effect) \u2192 full",
-    "text`. **course**: this course wrote the rule in `courseRules` in",
-    "`course.settings.json`, where it can be edited; the `X` area is reserved for",
+    "text`. **course**: this course wrote the rule in `courseRules` (in",
+    "`course.settings.json` or `course.config.ts`), where it can be edited; the `X` area is reserved for",
     "them. **script**: the build reports every violation under those codes.",
     "**partial**: the build reports the codes; the rest is on you. **guide**: nothing",
     "runs; it is on you. **locked**: script, and the course cannot turn it off.",
@@ -134,7 +135,7 @@ function renderRulesInEffect(input, filter = {}) {
   }
   lines.push("", "## Off", "");
   lines.push(
-    offHere.length === 0 ? "- Nothing \u2014 every rule is on." : `- ${offHere.join(", ")} \u2014 turned off in \`course.settings.json\` (\`rules\`, or \`courseRules\` for an \`X\` rule). Do not apply them; do not flag them in review.`
+    offHere.length === 0 ? "- Nothing \u2014 every rule is on." : `- ${offHere.join(", ")} \u2014 turned off in the course's \`rules\` (or \`courseRules\` for an \`X\` rule), in \`course.settings.json\` or \`course.config.ts\`. Do not apply them; do not flag them in review.`
   );
   lines.push("", "## Locked", "");
   lines.push(`- ${locked.join(", ")} \u2014 cannot be turned off; listed above under their element.`);

package/dist/rules/rules.schema.json

@@ -244,6 +244,27 @@
         }
       }
     },
+    "D11": {
+      "title": "D11 — A deck is flagged when its chapter changed after it did",
+      "description": "No authoring action by itself: 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 rule C5 version is newer than the deck’s; read the chapter’s change and judge whether the deck needs it too. Scoped to a lesson’s own deck — a part’s deck covers more than one chapter, so it has none to compare against.",
+      "x-element": "slide",
+      "x-elements": [
+        "slide",
+        "changelog"
+      ],
+      "x-enforcement": "script",
+      "x-doc": "docs/authoring/deck.md#d11",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "title": "Enabled",
+          "description": "Off: the check does not run, and the rule leaves the rules-in-effect page.",
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
     "N9": {
       "title": "N9 — A quantity/unit/operator is typeset in `$…$`, never as plain text",
       "description": "Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity's unit out: \"4 seconds\", \"2 meters per second squared\", \"30 degrees\", \"$x = 3$ meters\" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own (\"measured in meters\") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption=\"…\"`) render no math, so N9 does not apply there; nor does it apply to an assessment choice label, which may still hold math (`$30^{\\circ}$`).",

package/docs/authoring/README.md

@@ -241,6 +241,7 @@ of to the settings file.
 | [deck.md](deck.md)               | `D`  | a lesson's deck: its frames, steps, notes and recalls, and what fits a frame |
 | [components.md](components.md)   | —    | _catalog_: inline/block features available in a lesson body — tooltips, tables, figures, diagrams, memos, abbreviations, citations |
 | [agents.md](agents.md)           | —    | _guide_: working on a course repo (with an AI agent)       |
+| [cli.md](cli.md)                 | —    | _reference_, generated: every `content` verb, its flags, what it writes, and the shape of its `--json` ([cli-reference.json](cli-reference.json) as JSON Schema) |
 | [migrating.md](migrating.md)     | —    | _guide_: per-version steps when bumping the `explico` dep  |
 | [retired.md](retired.md)         | —    | _history_: one generated row per rule no longer in force, and its successor |
 
@@ -308,6 +309,7 @@ of to the settings file.
 | [D8](deck.md#d8) | slide, equation | Recall a chapter’s result; never retype it _(deck only)_ | Script — `frame-retyped` (warning) in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks` |
 | [D9](deck.md#d9) | slide, math, notation | A frame introduces at most `maxNewSymbols` symbols _(deck only)_ — settings: `maxNewSymbols` = `4` | Script — `frame-new-symbols` (info) in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks` |
 | [D10](deck.md#d10) | slide | A deck opens on its title and closes on what the student can now do _(deck only)_ | Guide |
+| [D11](deck.md#d11) | slide, changelog | A deck is flagged when its chapter changed after it did _(deck only)_ | Script — `deck-stale` (info) in [`page-versions.ts`](../../src/compiler/page-versions.ts) `deckStaleDiagnostics` |
 
 _Element_ is what the rule is about; the first tag is primary. _Enforcement_ is
 derived from the catalog: **Script** — every violation a check can see is

package/docs/authoring/agents.md

@@ -24,7 +24,7 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
 - **Read the rules in effect first, one rule at a time after that.**
   `pnpm content rule <ID>` prints one rule whole: the entry as this course
   has it and the page's own section with its example, about half a thousand
-  tokens. `pnpm --filter <course> content rules`
+  tokens (N4, the largest, about three thousand). `pnpm --filter <course> content rules`
   (or `build/rules-in-effect.md` after a `validate:content`) lists every rule
   this course has *on*, grouped by the element it is about — prose, math,
   equation, notation, heading, part-page, plot, diagram, table, assessment,
@@ -46,17 +46,22 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
   ([README.md § Rules of your own](README.md#rules-of-your-own)) — never by
   editing this folder.
 - **Start from the CLI, not a file hunt.** Run it from the course package;
-  `pnpm content help` lists every verb, and every verb takes `--json` for the
-  whole report. Read what it prints before opening files. The table under
-  "The CLI" says which verb answers which question.
+  `pnpm content help` lists every verb, `pnpm content help <verb>` prints one
+  verb's flags and the shape of its `--json` ([`cli.md`](cli.md) has them all),
+  and every verb takes `--json` for the whole report. Read what it prints
+  before opening files. The table under "The CLI" says which verb answers which
+  question.
 - **Validate once.** `pnpm --filter <course> validate:content` rewrites
-  `build/resolution/*` and passes on its first run; it fails only on a report
-  git tracks that it had to rewrite, so a course that commits `build/resolution/`
-  commits the rewritten files with the change, and a course whose `build/` is
-  git-ignored has nothing to commit from it.
-- **Before handing work back:** `validate:content` → `astro check` →
-  `astro build`. `astro build` is the only step that runs every gate the CI
-  does.
+  `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 `build/resolution/` commits the rewritten reports with the
+  change and runs it again (after an engine upgrade every report is
+  rewritten).
+- **Before handing work back:** `pnpm content verify` runs `validate:content`
+  → `content check --changed` → `astro check` → the course's tests →
+  `astro build` (`--e2e` adds the browser tests), one line per step and the
+  tail of a failed step's log; a rerun on an unchanged tree answers from its
+  last pass. `astro build` is the only step that runs every gate the CI does.
 
 ## The CLI
 
@@ -83,6 +88,8 @@ release that introduced it). Read-only except `new` and `init-agent`, and
 | the mechanical repairs | `fix <lesson> [--write]` | redundant `\explain` wraps unwrapped, as a diff |
 | a draft to start from | `new lesson <id>`, `new deck <lesson \| part>`, `new term <key>` | the files it created; never overwrites |
 | install these procedures | `init-agent [--write]` | the skills and the `rules-reviewer` agent copied into `.claude/`, a baseline `AGENTS.md` when the course has none |
+| is it ready to hand back | `verify [--e2e] [--force]` | one line per step — validate, check, `astro check`, tests, `astro build` — and a failed step's log tail; exit 1 if one failed |
+| a verb's flags and `--json` | `help [<verb>]` | the usage; with a verb, its flags, what it writes, its exit code and its `--json` type |
 
 The procedures — drafting a lesson, upgrading the engine, releasing the
 course's content, reviewing a lesson against the guide-only rules — ship in