Concept diagrams and computed hypothetical outcomes. Every chart below is generated by a seeded mini-simulation running the suite's documented mechanics and constants — bands 95/85/70, the 10-entry window (act at 5), 3-entry cooldowns, 40 points per ladder position, gate-release streaks, the 2× prescription threshold. In the testing doc's spirit (13-TESTING): these are the machine's consequences, not illustrations of wishes. (One deliberate light look; a communication artifact like the mockups, never shipped.)
The learning model — three engines and a coach
00-OVERVIEW §the learning model · 02-ITEM-MODEL §6 · 09-PRESCRIPTIONS
Why three engines: piano fluency is three learning problems. A schedules true memories (FSRS on atoms answered at the keyboard), B schedules pattern classes whose concrete instances are always fresh (reading material must stay novel), C generates never-repeated passages under a per-axis difficulty staircase (not SRS — you never see a passage twice). Everything they grade lands in one evidence stream, which layer D reads back as diagnoses and prescriptions — the loop, not a suggestion box.
One rep through the spine
10-ARCHITECTURE §3 — the practice loop
The chooser–computer seam, drawn. The block-filler chooses; the generator proposes and the difficulty referee verifies; the keyboard answers; the grader judges; the scheduler and the staircase update memory and skill state. Everything appends to the logs, and the scoreboard and the coach read those logs asynchronously — never inside the loop. Ratings and diagnoses can lag; a rep never waits.
One scale, three vocabularies — positions, points, leagues
05-DIFFICULTY §1 · 07-RATINGS §2–3
Ranks say how hard the material is; leagues say how far you've climbed. The 45 ladder positions (9 ranks × 5 subranks) map linearly onto the 100–1900 scale at 40 points each — 100 is the unplaced floor, F-- = 140, SSS+++ = 1900 — and the same axis buckets into six 300-point leagues with divisions III–I. One number, three honest readings.
The band controller at work — one axis, 140 reads
05-DIFFICULTY §3 — computed with the documented constants
per-read entry (% clean)rolling mean (last ≤10)
The working band is home. Each dot is one read's clean-percentage on this axis's own terms; the dark line is the rolling mean the controller acts on. Sustained ≥95 promotes a subrank (the position steps below, then a 3-entry cooldown); the 85–95 band holds — where practice pays; <85 would demote. Difficulty rises exactly as fast as the player earns it, and the observed clean rate keeps oscillating high — perfect practice as a control target.data
Three climbers, six months
05-DIFFICULTY §5's named scenarios — computed
the workerthe overreacherthe crawler
Same controller, three learners. The worker climbs steadily inside the band. The overreacher starts placed above their skill (~80% clean): the controller steps them down within a handful of reads, then they climb honestly from where they belong. The crawler learns slowly but cleanly — slow-but-clean is legitimate slow practice, and the ladder waits. Nobody flaps: one subrank's difficulty step (~4 pts) is smaller than the 10-point hold band.data
The oscillation sawtooth — what "held at near-perfect" looks like
03-GRADING §1.4 · 05-DIFFICULTY §3 — and the step-size probe (05-DIFFICULTY §5, 13-TESTING §5.4)
Clean rate breathes with the ladder. Between moves, accuracy climbs toward ~97; each promotion buys ~4 points of difficulty and drops it back into the band. Note the honest tension this chart makes visible: with the calibrated 3–5-point step, the sawtooth spans roughly 92–97 — while the grading doc's prose describes ~87–97 (03-GRADING §1.4). Which is right is an empirical question: the step-size probe, resolved by the sim spike, not on paper.
Ratings emerge — Reading and Keys & Chords, six months
07-RATINGS §3 — the 80/20 Reading blend and the attainment ramp, computed
Two constructions, one scale. Reading moves with the five-axis skill profile (span at half weight) plus a fifth of knowledge attainment; Keys & Chords is pure attainment over a fixed denominator, so early numbers are honestly small and every graduated atom nudges it — the Big-Brain-Academy room-to-grow flavor. Both are quiet by construction: a bad evening can move an axis at most one subrank ≈ 40 points on one domain.data
Ratings never move on silence — evidence moves them. Practice builds the number; six months of silence leave it exactly flat (the map's weak counts tell the away story, never the rating). Monthly benchmarks then re-verify — and the draw is **staleness-first** (log #71), so streaks build on exactly the gates that have gone longest unproven: a gauntlet prompt is an ordinary rep, three consecutive misses on the same atom release its gate, and honest dips begin by the third checkpoint instead of a months-long drip. The big correction still lands when practice resumes: serving hammers the weak pool, rotted gates release fast, the number falls to the truth, and then rebuilds as gates are re-earned. Held, not owned.data
A prescription closes its loop
09-PRESCRIPTIONS §2 rule 1 · §3 — computed
The differentiator, end to end. Accidental errors in flat keys drift above the personal baseline; at 2× the rule fires and a card lands on the shelf. Acceptance opens the 14-day active window (shaded) — targets get a serving boost, generation biases toward flats — the rate falls, and the prescription retires with credit ("that drill paid off — accidentals in flats down 60%"). Decline instead, and it expires quietly; unchanged, and the pattern is simply surfaced. A loop with its homework showing.data
Toolchain: edit docs/figures/src/, run node build.mjs — never the built file. Charts follow the data-viz method (validated categorical trio, single-hue series, hairline grid, direct labels + legends, native hover titles, data tables); the seeded simulations implement the difficulty controller (05-DIFFICULTY §3), the gate streaks (02-ITEM-MODEL §1), and the rating formulas (07-RATINGS §3) verbatim, with a simple ground-truth learner per the testing doc (13-TESTING §2).