explico 0.8.0 → 0.11.1

package/docs/authoring/structure.md

@@ -75,63 +75,315 @@ naming collision both stayed invisible.
 
 ```
 Course        Explico Playground
-├── Part 1    Motion in the plane                     content/docs/motion/
-│   ├── Ch 1  Position and Coordinate Systems         position-and-coordinates.mdx
-│   │   ├── § Locating a point in the plane           ##
-│   │   ├── § Two ways to name the same point         ##
-│   │   │   ├── §§ From Cartesian to polar            ###
-│   │   │   └── §§ From polar to Cartesian            ###
-│   │   ├── § Velocity and acceleration as derivatives ##
-│   │   └── § The special case: constant acceleration  ##
-│   │       ├── §§ Integrating once: velocity          ###
-│   │       └── §§ Integrating twice: position         ###
-│   └── Ch 2  Velocity Under Constant Acceleration    constant-acceleration.mdx
-└── Part 2    Projectile motion                       content/docs/projectiles/
-    ├── Ch 1  Projectile Range                        projectile-range.mdx
-    └── Ch 2  Optimal Launch Angle                    optimal-launch-angle.mdx
+├── Part 1    Motion in the plane                           content/docs/motion/
+│   ├── Ch 1  Position and Coordinate Systems               position-and-coordinates.mdx
+│   │   ├── § 1.1.1    Locating a point in the plane         ##
+│   │   ├── § 1.1.2    Two ways to name the same point       ##
+│   │   │   ├── § 1.1.2.1  From Cartesian to polar           ###
+│   │   │   └── § 1.1.2.2  From polar to Cartesian           ###
+│   │   ├── § 1.1.3    Velocity and acceleration as derivatives ##
+│   │   ├── § 1.1.4    The special case: constant acceleration  ##
+│   │   │   ├── § 1.1.4.1  Integrating once: velocity        ###
+│   │   │   └── § 1.1.4.2  Integrating twice: position       ###
+│   │   └── § 1.1.5    Try it                                ##
+│   └── Ch 2  Velocity Under Constant Acceleration          constant-acceleration.mdx
+└── Part 2    Projectile motion                             content/docs/projectiles/
+    ├── Ch 1  Projectile Range                              projectile-range.mdx
+    └── Ch 2  Optimal Launch Angle                          optimal-launch-angle.mdx
 ```
 
-Which numbers every float like this — the part supplies the prefix, and the
-index carries on across the part's chapters:
+Which numbers every float like this — the part and the chapter supply the
+prefix, and each chapter counts from 1:
 
 ```
 Part 1  Motion in the plane
-  Ch 1  Position and Coordinate Systems   (1.1) (1.2) (1.3) (1.4) (1.5) (1.6) (1.7)
-  Ch 2  Velocity Under Constant Accel.    (1.8)
+  Ch 1  Position and Coordinate Systems   (1.1.1) (1.1.2) … (1.1.7)
+  Ch 2  Velocity Under Constant Accel.    (1.2.1)
 Part 2  Projectile motion
-  Ch 1  Projectile Range                  (2.1) (2.2)
-  Ch 2  Optimal Launch Angle              (2.3) (2.4) (2.5) (2.6)
+  Ch 1  Projectile Range                  (2.1.1) (2.1.2) (2.1.3)
+  Ch 2  Optimal Launch Angle              (2.2.1) (2.2.2) (2.2.3) (2.2.4)
 ```
 
+## Part pages
+
+A part is a directory, so `/<part>/` is a URL a reader will eventually type,
+follow, or be handed by a search engine. Without a page it is a 404, and the
+part exists only as a sidebar heading that cannot be linked to.
+
+Give a part a page by authoring **`content/docs/<dir>/index.mdx`**:
+
+```mdx
+---
+title: Motion in the plane
+description: Locate a moving point, then predict where it goes next.
+---
+
+import PartBridge from 'explico/components/PartBridge.astro';
+import PartOverview from 'explico/components/PartOverview.astro';
+import PartScope from 'explico/components/PartScope.astro';
+
+<PartBridge>
+
+How the earlier parts lead into this one — omitted on the first part.
+
+</PartBridge>
+
+<PartScope>
+
+What this part covers, in the course's own voice.
+
+</PartScope>
+
+<PartOverview
+  chain={[
+    'A point in the plane gets a name: Cartesian, or polar',
+    'Velocity and acceleration are that name differentiated',
+  ]}
+/>
+```
+
+**The two paragraphs are required** ([S2](structure-rules.md#s2)): every part
+page after the first opens with a `<PartBridge>` paragraph that links the
+earlier parts to this one, and every part page carries a `<PartScope>`
+paragraph on its own content. `pnpm validate:content` fails when one is
+missing, holds more than one paragraph, or falls outside the course's
+`rules.S2` word range (30–150 words unless the course sets its own).
+
+**An overview page is not a chapter.** `isLessonSlug` has always excluded
+`<dir>/index`, so the page teaches no competency, carries no knowledge check,
+takes no float numbers, and never appears in `manifest.lessons` or a track. A
+course adds one part at a time; a part without one behaves exactly as before.
+
+`<PartOverview>` reads the manifest for everything it lists — chapters in
+reading order with their descriptions, the competencies the part teaches, the
+parts it builds on and leads to — so the page cannot fall out of date with the
+content. Only the two paragraphs and the optional `chain` (the part's argument,
+one step per line, which no manifest field knows) are authored. `rail={false}` drops the
+side rail and keeps the reading list.
+
+### Study time
+
+A chapter may state how long it takes, and only the chapter can know:
+
+```yaml
+studyMinutes: 40        # or a range
+studyMinutes: [30, 40]
+```
+
+`<PartOverview>` prints it beside each chapter and totals the part;
+`<CourseContents>` totals the course in hours. **A total appears only when
+every chapter in that part states one**, so a half-annotated course shows the
+chapters it knows about and no misleading sum. Nothing derives the field and
+nothing requires it — it is the reader-facing half of the old
+`estimatedMinutes`, which was dropped when there was nowhere to add it up.
+
+### Reaching the page
+
+Three routes lead to it, and a course gets all three at once:
+
+| Route | Where it comes from | Works without JavaScript |
+| --- | --- | --- |
+| The `Overview` row leading the part's sidebar group | the compiled `sidebar` | yes |
+| The `»` control in the sidebar group's header | `LayoutSidebar.astro`'s script | no |
+| The part's name above every chapter title | `LayoutPageTitle.astro` | yes |
+
+The part label in the sidebar keeps collapsing the group when clicked — the
+control sits beside the caret rather than taking either gesture. The breadcrumb
+needs one line of wiring in the course's `astro.config.mjs`:
+
+```js
+components: {
+  PageTitle: 'explico/components/starlight/LayoutPageTitle.astro',
+}
+```
+
+Name the sidebar row with `overviewLabel` on the part when `Overview` is wrong
+for a course: `{ dir: 'bonds', label: 'Bonds', overviewLabel: 'All bonds' }`.
+
+## The course's own contents
+
+A landing page that links only the first chapter hides the rest of the course.
+`<CourseContents>` lists every part with its chapters, in reading order, each
+part heading linking its overview page:
+
+```mdx
+import CourseContents from 'explico/components/CourseContents.astro';
+
+<CourseContents />
+```
+
+It reads the same manifest the sidebar does, so a renamed chapter or a new part
+cannot leave a stale copy behind on the front page. `descriptions={false}`
+drops the one-line summaries; `headingLevel={3}` fits it under an existing
+`##`.
+
+## Where the reader is
+
+Two marks, both derived, neither authored:
+
+- **The navigation rail** colours the segment beside every chapter already
+  passed, so the boundary between accent and hairline is the reader's position
+  in the course. A part whose chapters are all behind them is marked whole.
+  Reading order is the sidebar's own order, which is the merged track order.
+- **The contents rail** does the same down one page, following Starlight's
+  scroll-spy as the reader travels.
+
+Both are progressive enhancements: without JavaScript the rails are simply
+uncoloured.
+
+The part header carries the third mark, and that one is pure CSS, so it is
+right in the first painted frame: a standing tint while the open page belongs
+to that part. Together the three never read as the same thing — a solid accent
+row is the chapter you are on, a tint is the part holding it, a neutral fill
+comes and goes with the pointer.
+
 ## Numbering
 
-A display equation, `<Table>`, `<Figure>`, `<Diagram>`, or knowledge check is
-numbered **`‹part›.‹n›`**:
+Every number follows the book's outline: part, then chapter, then the thing
+numbered. A course sets the details in `course.settings.json` → `numbering`;
+every key is optional, and these are the defaults:
 
-- **`part`** is the part's 1-based position in `courseConfig.parts`.
-- **`n`** counts that kind of numbered item across the *whole part*, in document
-  order, running unbroken from one chapter into the next. Each kind counts on
-  its own, so a `<Table>` never advances the `<Figure>`, `<Diagram>`, or
-  knowledge-check sequence.
+```json
+"numbering": {
+  "sections": { "show": true, "depth": 4 },
+  "floats": "chapter",
+  "aliases": true
+}
+```
+
+A number is for a reader to see and say. It is never the anchor: a heading's
+anchor is its slug (`#two-ways-to-name-the-same-point`) and a float's is its
+`id` (`#tab-kinematics-summary`), so a link survives a section inserted above
+its target.
+
+### Section numbers
+
+A lesson's top-level `##` to `######` headings are numbered
+**`‹part›.‹chapter›.‹section›[.‹subsection›…]`**:
+
+- **`part`** is the part's 1-based position in `courseConfig.parts`, and
+  **`chapter`** the lesson's position in its part, in sidebar order.
+- `##` counts within the chapter, `###` within its `##`, and so on; a deeper
+  counter restarts under every shallower heading. Headings descend one level
+  at a time (rule S6), so no level is skipped; where one is anyway (S6 off or
+  waived), it counts as 0 (`##` then `####` is `1.1.1.0.1`), as in LaTeX.
+- A heading deeper than `numbering.sections.depth` (default `4`, `####`) is
+  unnumbered. A heading inside a component — a `<Memo>`, a `<CompactExample>` —
+  belongs to that component, not to the outline, so it is neither numbered nor
+  counted. The generated "References" section and a knowledge check's own
+  heading are not numbered either.
+
+Where a section number shows:
+
+| | Wide screen | Narrow screen (under 50em) | Print |
+| --- | :-: | :-: | :-: |
+| An open section's heading | ✓ | — | ✓ |
+| A collapsed section's bar | ✓ | ✓ | ✓ |
+| The chain icon's "Link copied · § 1.1.2" | ✓ | ✓ | — |
+
+`numbering.sections.show: false` shows no section numbers anywhere.
+
+**The chain icon copies the link.** Clicking (or tapping) a heading's chain
+icon puts the page's URL with the heading's named anchor on the clipboard,
+sets the address bar to it, highlights the section, and says "Link copied ·
+§ 1.1.2" beside the icon. On a narrow screen, where an open heading shows no
+number, that confirmation is where the number surfaces, and the icon is always
+visible there. If the browser refuses the clipboard, the click still navigates
+and highlights. Tapping a heading's title only folds or unfolds a collapsible
+section; it never changes the URL.
+
+**Citing a section.** `[[sec-‹anchor›]]` on the same page, or
+`[[lesson/slug#sec-‹anchor›]]` from another lesson, prints `§ 1.1.2` as a link
+to the section, with a hover card showing its title and first paragraph. The
+anchor is the heading's slug: its text in lowercase, spaces as hyphens,
+punctuation dropped, so `## Two ways to name the same point` is
+`[[sec-two-ways-to-name-the-same-point]]`, and a title that repeats takes
+`-1`, `-2`. A reference to a heading without a number (deeper than `depth`, or
+with `show: false`) prints the heading's title in quotes instead: a reader
+could not find the number. A reference that names no top-level heading fails
+`pnpm validate:content` (`sec-ref-resolves`) and the build.
+
+### Structure from the bottom up
+
+A heading's level says where it sits in the outline: rule S6 lets it go one
+level deeper than the heading before it, and rule S7 puts body content
+between two headings. Neither is a way to get structure where the outline
+has run out. When a section near the bottom of the outline holds two parallel
+enumerations — the assumptions of a model and its conclusions, the steps of
+two methods — do not open `#####` headings for them, and do not climb back
+to `##` for the look of it. Structure them from the bottom up, the way LaTeX
+does with `\paragraph` and its `description` environment:
+
+- a **run-in label** — a bold phrase that opens its paragraph (`**Level
+  ground.** The launch and landing heights are equal …`), for a few items
+  that each take a paragraph;
+- a **description list** — one line per item, the label in bold and its
+  explanation after it — for many short items;
+- a `<Table>`, when the items share the same attributes.
+
+A run-in label is not in the outline, "On this page" or the numbering, and it
+needs none of that: it names a paragraph for the reader who is already
+reading the section, not a place to jump to. Promote it to a heading only
+when it deserves a link, a number or folding of its own.
+
+### Float numbers
+
+A display equation, `<Table>`, `<Figure>`, `<Diagram>`, knowledge check or
+worked-example set (`<CompactExamples>`) is numbered **`‹part›.‹chapter›.‹n›`**:
+
+- **`n`** counts that kind of numbered item in the chapter, in document order.
+  Each kind counts on its own, so a `<Table>` never advances the `<Figure>`,
+  `<Diagram>`, knowledge-check or example sequence.
 - **Sections and subsections do not participate.** Neither `##` nor `###`
   resets `n` or appears in the number.
 - **Keyed or not, everything counts.** An equation with no `\label{eq:…}` still
-  takes a number and a positional anchor (`#eq-2-4`); it just cannot be
+  takes a number and a positional anchor (`#eq-2-1-4`); it just cannot be
   referenced by name.
-
-In the playground: part 1 runs `1.1` … `1.7` through chapter 1 and continues
-`1.8` in chapter 2; part 2 opens at `2.1`.
-
-`manifest.lessons[]` carries what the render path needs to reproduce this:
-`part`, `chapter`, and `numbering.{equations,tables,figures,diagrams,checks}` —
-the running count each chapter starts from.
+- **The number sits with the caption.** A figure or diagram prints it in the
+  caption line below its picture, a table in the caption line above, and a
+  display equation beside it. What names each
+  float — its long `caption` and optional `short` caption, an equation's
+  `\caption{…}` — is [components.md § The caption pair](components.md#the-caption-pair).
+- **A check's and an example set's number shows like a section's.** Both are
+  sections of the page with a heading of their own, so their number follows
+  [§ Section numbers](#section-numbers) — wide screen, print, folded bar, and
+  not at all with `numbering.sections.show` off — while a float's stays in its
+  caption at every width, because prose names a float by its number.
+
+In the playground: part 1 runs `1.1.1` … `1.1.7` through chapter 1, and
+chapter 2 starts again at `1.2.1`; part 2 opens at `2.1.1`.
+
+`numbering.floats: "part"` keeps the older scheme, **`‹part›.‹n›`**, with `n`
+running on from one chapter of the part into the next — the first equation of
+a chapter that follows one with seven is `1.8`.
+
+`manifest.lessons[]` carries what the render path needs to reproduce all of
+this: `part`, `chapter`, `numbering.prefix` and the per-kind count each chapter
+starts from (`numbering.{equations,tables,figures,diagrams,checks,examples}`,
+all 0 under the chapter scope), and `headings`, every top-level heading with
+its anchor and number.
+
+### Number aliases
+
+A number is not an anchor, but a reader may still type one. With
+`numbering.aliases` on (the default), a fragment in number form — `#sec-1.1.2`,
+`#fig-2.2.1`, `#eq-1.1.4`, `#tab-…`, `#dia-…`, `#check-…`, `#ex-…` — lands on the
+section or float that shows that number on the page, and the address bar
+switches to its named anchor. This works inbound only: nothing the site links
+or copies is in number form. An alias is only as stable as the content: once a
+section is inserted above it, `§ 1.1.2` names a different section, so a number
+quoted outside the course belongs next to the knowledge version the About
+`[?]` panel shows.
 
 ### The invariant, and why it is build-enforced
 
 The number a page prints beside an equation and the number a cross-page
 `[[slug#eq-key]]` prints for it are computed by two code paths from the same
 content. `remarkNotation` cross-checks them for every keyed float and fails the
-build on any disagreement, naming the key and both numbers.
+build on any disagreement, naming the key and both numbers. Sections get the
+same guard: a page takes its headings' anchors and numbers from the manifest,
+and the build fails if the page's top-level headings are not the ones the
+manifest numbered.
 
 This exists because the disagreement is otherwise silent and shipped: a course
 config that passed the manifest number tables without the placement map
@@ -156,8 +408,8 @@ could still silently fall back to `##`-section numbering with no error at all.
 `strict: true` closes that: it fails the build when a catalogued lesson
 contains any equation, `<Table>`, or `<Figure>` — keyed or not — but has no
 `numbering` placement or no cross-page number table entry for its slug.
-`<Diagram>` is exempt, since `Diagram.astro` already renders one without a
-number by design when it has none. `strict` defaults to `false`, so existing
+`<Diagram>` and `<CompactExamples>` are exempt, since both components already
+render one without a number by design when it has none. `strict` defaults to `false`, so existing
 non-strict wiring keeps building unchanged; turn it on once a course's
 manifest covers every catalogued lesson.
 
@@ -182,14 +434,135 @@ inside `<Memo>`/`<ShortNote>`), or wrap it in `<Figure>`.
 
 ### Knowledge checks
 
-An assessment title is authored once, in `content/assessments/<id>.json`. Put
-that id in the lesson's colocated `.checks.yml`, then render `<AssessmentSet />`;
-do not add a separate “Check yourself” heading. The component renders
-`Knowledge check ‹number› — ‹title›` as a permalinked, collapsible section at
-`#check-<id>`. Cite it on the same page with `[[check-<id>]]`, or from another
-lesson with `[[lesson/slug#check-<id>]]`. Single-choice options are shuffled
-when the browser views the check; option ids, correctness, and authored content
-remain unchanged.
+An assessment title is authored once, in `content/assessments/<id>.json`, and
+names the topic alone ("Position and coordinates"). Put that id in the lesson's
+colocated `.checks.yml`, then render `<AssessmentSet />`; do not add a
+separate “Check yourself” heading. The component draws the check's `<h2>` —
+the check-mark icon and the title, with "Knowledge check" and the number as a
+label in the card's corner
+([components.md § Knowledge checks and worked
+examples](components.md#knowledge-checks-and-worked-examples)) — as a
+permalinked section at `#check-<id>`, collapsible and open unless the course's
+`disclosure.knowledgeChecks` says otherwise ([§ Collapsing](#collapsing-two-mechanisms)),
+and "On this page" lists it. Cite it on the same page with `[[check-<id>]]`, or
+from another lesson with `[[lesson/slug#check-<id>]]`. Single-choice options are
+shuffled when the browser views the check; option ids, correctness, and
+authored content remain unchanged.
+
+### Worked examples
+
+A `<CompactExamples id="…" short="…">` is a numbered set of worked examples,
+`Example ‹part›.‹chapter›.‹n›`, one `<CompactExample label="…">` tab each. Both
+props are required: the `id` anchors it at `#ex-<id>` and is what
+`[[ex-<id>]]` (or `[[lesson/slug#ex-<id>]]`) cites; `short` is its topic. The
+component draws the set's `<h2>` — the "Example" badge, the number, the topic
+— so no heading goes above it. The set folds like a section, closed on a first
+visit unless `disclosure.workedExamples` says otherwise, and "On this page"
+lists it.
+
+## Containers: plain, meta, accent, aside
+
+Every box the engine draws belongs to one of four tiers, and the tier says
+what the content *is* — the reader learns one visual language, not one per
+component:
+
+| Tier | Looks like | Means | Used by |
+| --- | --- | --- | --- |
+| **plain** | no card | material a book would print in its main flow | sections, figures, tables, equations, diagrams, References |
+| **meta** | grey surface, thin border | logistics, or generated for the reader | the notation panel, a part page's rail, the About panel, the glossary and curriculum-map cards, a Starlight `<Card>` |
+| **accent** | accent tint, thin border, shadow | enrichment the author marked | knowledge checks, worked examples, a `[card]` section |
+| **aside** | a left rule (a memo is also tinted) | an annotation beside the flow | `<Memo>`, an opened `<ShortNote>`, a Starlight aside |
+
+A tier is fixed per kind; a course has no setting to change it. No container
+has a top rule, and the shadow never grows with heading depth: hierarchy is in
+type size and numbers. An interactive figure has no card of its own either —
+its lab is plain figure material.
+
+**Heading markers.** A heading takes up to two markers at the end of its
+line, one of each kind, in either order. They never render, never reach the
+anchor (`### Explore the range [card]` is `#explore-the-range`), and rule S1
+does not count them.
+
+| Marker | Effect |
+| --- | --- |
+| `[collapsible]` | collapsible, starts open, whatever the `disclosure` default |
+| `[collapsed]` | collapsible, starts closed |
+| `[no-collapsible]` | never collapsible |
+| `[card]` | the section — heading and body, down to the next heading of the same or a higher rank — becomes one **accent** card |
+| `[card=meta]` | the same, in the **meta** tier, and unnumbered: logistics — what a chapter builds on, how to read it — is outside the outline, like References, and so is every heading inside it |
+
+```mdx
+### Explore the range [collapsed] [card]
+
+Move the sliders; the section folds and unfolds as one card.
+```
+
+Use `[card]` to set a stretch of the lesson apart as something to try or
+explore — a lab with the prose that frames it, say. It is not for emphasis:
+a section that matters more is a better heading, not a box.
+
+**Starlight asides and cards.** `:::note`, `:::tip`, `:::caution` and
+`:::danger` (and `<Aside type="…">`) render in the aside tier with
+Starlight's own icon per type; `note` and `tip` take the course accent,
+`caution` and `danger` keep a warning and a danger hue. Name any Starlight
+built-in icon to replace it (`:::note{icon="heart"}`), or leave it empty to
+drop it (`:::note{icon=""}`, `<Aside icon="">`). The `:::` form needs
+`remarkAsides` (`explico/reference/remark-asides.mjs`) last in the course's
+`remarkPlugins`: Starlight renders directives only under its own
+`src/content/docs/`, and this pass hands them to Starlight's `<Aside>`. In a
+`.md` lesson (no JSX) an aside has no icon. A `<Card>` / `<CardGrid>` renders
+in the meta tier. Rule S8 says when a `<Memo>` is the better choice than an
+aside.
+
+## Collapsing: two mechanisms
+
+A block folds in one of two ways, and every default lives in one place, the
+`disclosure` block of `course.settings.json`
+(`CourseConfig.disclosure`, published as `manifest.disclosure`):
+
+- **A section folds away whole.** Its heading stays as a bar with a chevron;
+  its body hides behind a "Hidden here: 2 paragraphs, 1 equation" line and
+  peeks on hover. `##` … `######` sections, a knowledge check, a set of worked
+  examples, the generated References, a `<Memo>` (a `######`-rank section
+  of its own) and a `<Fold>` (the same, with no marker, letter or frame, and
+  a bar that names the floats it holds — [components.md](components.md#folding-content-away-fold))
+  fold this way; the notation panel folds the same way.
+- **A float folds what follows its caption line, never the line.** A table
+  folds to its caption line and header row, and starts truncated when it is
+  long. A table's fold button is at the top right of its caption line, next
+  to a widen button ↔ when the table is wider than the column; the column at
+  its right edge widens it too. A figure or a diagram does not fold: it is
+  its picture and then its caption line — number, link, caption
+  ([components.md § The caption pair](components.md#the-caption-pair)) — in
+  every state, as LaTeX lays a figure out; a diagram's line ends with a widen
+  button ↔ while the graph is wider than the column. What a figure can fold
+  is what follows its caption line: a lab's tools, with the fold button ⌃ /
+  ⌄ at the line's end and a "Hidden here: 2 sliders, 1 equation" line while
+  folded. To fold a float away
+  entirely, wrap it in a `<Fold>` or put it in a collapsible section.
+
+| Block | Mechanism | Setting | Engine default | One place overrides with |
+| --- | --- | --- | --- | --- |
+| `##` section | section | `disclosure.sections` | not collapsible | a heading marker |
+| `###`–`######` section | section | `disclosure.subsections` | not collapsible | a heading marker |
+| Knowledge check | section | `disclosure.knowledgeChecks` | collapsible, open | — |
+| References | section | `disclosure.references` | closed | — |
+| Notation panel | section | `disclosure.notation` | closed | — |
+| `<Memo>` | section, `######` rank | `disclosure.memos` | closed | `defaultOpen` |
+| `<Fold>` | section, `######` rank | `disclosure.folds` | closed | `defaultOpen` |
+| A lab's tools (`<Figure>`'s `tools` slot) | a float's fold, after its caption line | `disclosure.figures` | open | `defaultOpen` |
+| `<CompactExamples>` | section, `##` rank | `disclosure.workedExamples` | closed | `defaultOpen` |
+| `<Table>` | minimize + truncation | `disclosure.tables.truncateAfter` | truncated above 6 rows | — |
+
+`sections`, `subsections` and `knowledgeChecks` take `{ collapsible,
+defaultOpen }`; the others take `{ defaultOpen }`; `tables` takes
+`{ truncateAfter }` — a table with more rows shows that many, half from each
+end, and a "… N more rows …" line. There is no `disclosure.diagrams`: a
+diagram does not fold. Every collapsible remembers the reader's own choice,
+per page, over the default (`rememberState={false}` on a memo, a fold, a
+figure's tools or an example set opts that one out). A short note's in-place
+reveal and a question's show/hide button are inline affordances, not
+containers, and are not settings.
 
 ## Detailed memos and inline short notes
 
@@ -197,8 +570,11 @@ Headings define the page's conceptual hierarchy: they belong in the outline and
 should help every reader navigate the main argument. A `<Memo>` instead holds
 optional depth — a long derivation, proof, robustness check, edge case, or
 alternative method — without pretending that material is another section of
-the lecture. It keeps the subsection-like card, background, and border, but is
-collapsed and independently numbered.
+the lecture. It sits in the aside tier (a left rule and the accent tint), is
+independently lettered, and folds like a `######` section — the same chevron,
+peek and "Hidden here" line — starting closed unless the course's
+`disclosure.memos` says otherwise. Its bar is not a heading of the lesson: it
+is not in the outline, "On this page" or the heading rules.
 
 Register `remarkShortNote` and then `remarkMemo` after `remarkMath` in
 `astro.config.mjs`. Import `explico/components/memo/Memo.astro`, cite a memo with
@@ -209,7 +585,7 @@ The full calculation is available in [[memo-supporting-check]].
 
 Several paragraphs may intervene before the detailed material.
 
-<Memo id="supporting-check" title="Supporting check" description="The detailed calculation behind the claim.">
+<Memo id="supporting-check" short="Supporting check" caption="The detailed calculation behind the claim">
 
 The body can contain ordinary Markdown, display equations, `<Table>`, and
 `<Figure>` components.
@@ -217,19 +593,26 @@ The body can contain ordinary Markdown, display equations, `<Table>`, and
 </Memo>
 ```
 
-`[[memo-supporting-check]]` renders as `[1]`. Clicking it opens and scrolls to
-the block and updates the URL to `#memo-supporting-check`; the `[1]` shown on
-the memo itself remains a numbered permalink, and the chain icon beside its
-title provides the same explicit anchor affordance used by headings and
-figures. `id`, `title`, and `description` are required literal strings. The
-block is collapsed on a reader's first visit and remembers later open/closed
-choices unless `rememberState={false}` is set. Memo numbering is independent
-of equation, table, figure, and diagram numbering. Those numbered items remain
-in their normal page/part streams inside a memo.
-
-For print and PDF export, the memo opens at its reading-order position. It does
-not move to the bottom of the page: browser support for CSS footnote floats is
-not reliable enough to make that layout portable.
+`[[memo-supporting-check]]` renders as a superscript letter, *ᵃ* — the footnote
+convention, so it never reads as a citation's `[1]`; memos are lettered `a`,
+`b`, … per page. Clicking it opens and scrolls to the block and updates the
+URL to `#memo-supporting-check`; clicking it again folds the memo. The memo's
+bar shows the same letter, and the chain icon beside it copies the memo's
+link, as a heading's does. A memo is named like every float
+([components.md § The caption pair](components.md#the-caption-pair)): `id` and
+`caption` are required literal strings — the caption is the memo's bar and
+heads its marker's preview — and an optional `short` caption is the marker's
+tooltip. The block starts as `disclosure.memos` says (closed by default;
+`defaultOpen` overrides it at one memo) and remembers later open/closed
+choices unless `rememberState={false}` is set. Memo lettering is
+independent of equation, table, figure, and diagram numbering. Those numbered
+items remain in their normal page/part streams inside a memo.
+
+For print and PDF export, the memo prints as the reader left it on screen. An
+open memo prints at its reading-order position. It does not move to the bottom
+of the page: browser support for CSS footnote floats is not reliable enough to
+make that layout portable. A closed memo prints its caption and a "(content
+collapsed — full text: …)" note that links its permalink.
 
 Use `<ShortNote>` for the smaller, genuinely inline interaction. Import
 `explico/components/memo/ShortNote.astro` and put it exactly where its collapsed

package/docs/authoring/versioning.md

@@ -63,7 +63,7 @@ reader, a course that forks this one) needs the same "did this break me?" signal
 from the knowledge version that a library gets from a package version.
 
 _How to apply._ Decide the bump when you move `## [Unreleased]` to a dated
-heading ([C4](#c4)); set `about.version` to match.
+heading ([C3](#c3)); set `about.version` to match.
 
 _Enforcement._ Review-only.
 
@@ -74,36 +74,18 @@ _Exceptions._ None. If a change does not fit a tier, it is PATCH.
 ## C3
 
 **`about.version` equals the newest `## [x.y.z]` heading in
-`content/CHANGELOG.md`.**
+`content/CHANGELOG.md`, and a release moves `## [Unreleased]` and bumps
+`about.version` in one commit.**
 
 _Rationale._ Two sources of the same fact must not drift. The manifest — and so
 the `[?]` panel — reads `about.version`; a reader chasing "what changed" reads
-the changelog. If they disagree, one is lying.
+the changelog. If they disagree, one is lying. A release is the atomic moment
+they agree again; splitting it across commits leaves a window where the build
+warns and the panel is wrong.
 
-_How to apply._ On a release, edit both in the same commit ([C4](#c4)). Between
-releases, `about.version` stays at the last released value while
-`## [Unreleased]` accumulates bullets.
-
-_Enforcement._ Build-enforced (Tier-3). `pnpm validate:content` emits
-`knowledge-version-mismatch` when they differ, `knowledge-changelog-missing`
-when there is no released heading, and `knowledge-version-invalid` when
-`about.version` is not `x.y.z`. All are warnings — they never fail the build, but
-CI may choose to.
-
-_Exceptions._ None.
-
----
-
-## C4
-
-**On a release, move `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD` and bump
-`about.version` in the same commit.**
-
-_Rationale._ A release is the atomic moment the two records agree again
-([C3](#c3)). Splitting it across commits leaves a window where the build warns
-and the panel is wrong.
-
-_How to apply._
+_How to apply._ Between releases, `about.version` stays at the last released
+value while `## [Unreleased]` accumulates bullets ([C1](#c1)). On a release, in
+one commit:
 
 1. Choose `x.y.z` from the accumulated `## [Unreleased]` bullets and [C2](#c2).
 2. Rename the heading to `## [x.y.z] - <today>`; add a fresh empty
@@ -111,6 +93,16 @@ _How to apply._
 3. Set `about.version` in `content/course.config.ts` to `x.y.z`.
 4. `pnpm validate:content` — no `knowledge-*` warning.
 
-_Enforcement._ Review-only (the end state is checked by [C3](#c3)).
+`pnpm release:content` does steps 2 and 3 for you.
+
+_Enforcement._ Build-enforced (Tier-3, `knowledge-version.ts`
+`resolveKnowledgeVersion`). `pnpm validate:content` emits
+`knowledge-version-mismatch` when they differ, `knowledge-changelog-missing`
+when there is no released heading — which is also what a half-finished release
+looks like — and `knowledge-version-invalid` when `about.version` is not
+`x.y.z`. All are warnings; they never fail the build, but CI may choose to.
+Partial: the build only ever sees the end state, so it cannot tell that the two
+edits landed in one commit — it warns until the second half lands.
 
 _Exceptions._ None.
+