Round 2 of the bib audit, covering paper subprojects (mlsysim,
tinytorch, periodic-table, mlperf-edu) that the textbook-focused first
pass deferred. Same pattern as round 1: surname/year prefixes did not
match the entry's actual paper, plus several corrupt entries from
Crossref misidentification.
Renames:
- mlsysim/{docs,paper}: barrett2024 -> zheng2024sglang (SGLang paper,
Zheng is first author).
- mlsysim/paper: zhao2025 -> deepseek2025v3 (DeepSeek-V3 ISCA paper,
corporate author DeepSeek-AI).
- tinytorch: key499f5624 -> tanenbaum1987os (hash-fallback for
Tanenbaum OS textbook); fry1985 -> abelson1996sicp (SICP 2nd ed,
Fry is not in author list); wooster1982 -> papert1980mindstorms
(Mindstorms by Papert, Wooster not in author list); collins2018 ->
collins1989apprenticeship (Cognitive Apprenticeship paper is 1989).
- tinytorch + periodic-table: vaswani2025 -> vaswani2017attention
(Attention paper is 2017; entries had a corrupt publisher and bogus
DOI from Crossref misidentification).
Body fixes accompanying renames:
- tanenbaum1987os, abelson1996sicp, papert1980mindstorms: rebuilt as
@book entries (were @article with stale review/journal DOIs).
- vaswani2017attention: rebuilt with canonical NeurIPS 2017 metadata
(Curran Associates, vol 30, pp 5998-6008); dropped corrupt DOI.
Orphan deletions:
- tinytorch keybe9561f4 (hash-fallback, no cite sites).
- mlperf-edu vaswani2017attention (orphan).
21 cite-site updates across 4 paper subprojects. bib_lint reports 0
errors across all 5 modified bibs.
Wraps up the bib-verify sweep across vol1, vol2, and the paper sub-projects,
and corrects three citation issues introduced earlier in the branch:
- Restore tang20211bit (1-bit Adam, Tang et al. ICML 2021) in vol2 bib and
in collective_communication.qmd. The earlier sweep had renamed the cite
to li2022, which now resolved to AlphaCode or 1-Bit LAMB.
- Restore micikevicius2018mixed in vol1 bib to point at "Mixed Precision
Training" (Micikevicius et al. ICLR 2018). The entry had been overwritten
with an unrelated OpenSeq2Seq paper while the cite key stayed the same.
- Drop the unused li2022 (AlphaCode) entry and the duplicate li2022 (1-Bit
LAMB) entry from vol2 bib.
Also remove eight same-paper duplicate entries that the sweep had left
behind (vol1: lawson1979, gholami2022, lange2009, ribeiro2016; vol2:
bursztein2024, rasley2020, sevilla2022, narayanan2019).
After this commit the bibs have zero duplicate keys and zero orphan
citations across both volumes and all five paper sub-projects.
Deleted reddi2024mlsysbook from tinytorch/paper and rafailov2023direct from
periodic-table/paper. Both were identified as true orphans (not cited in
any .qmd or .tex) and out of scope for their respective papers.
The previous scope was .qmd only, which made every paper-bib entry not
cited from a chapter look orphan even when paper.tex cited it. Adds
\cite/\citep/\citet/\citeauthor/\citeyear pattern matching for the four
paper.tex files (interviews, tinytorch, periodic-table, mlsysim).
Also fixes 6 broken links in tinytorch/paper/paper.tex caused by earlier
bib-audit deletions of keys that had year/surname mismatches. Restored
these entries with corrected keys (appel2002tiger, reddi2021widening,
pfaff2009pintos, rush2020minitorch, zhang2023dive) and updated the .tex
file to match. Replaced kannan2022astrasim with won2023astrasim2.
The original hardening got the structural selectors right, but the
labs/kits/book sidebar still had two divergences from the instructors
reference: (a) section headers and leaf links rendered with the same
muted color (no hierarchy) because the section-header rule only matched
the chevron `<a class="sidebar-item-toggle">` and missed the section
text `<a class="sidebar-link text-start">`, and (b) the active-state
rule colored the text in the accent color rather than white on a subtle
accent tint, so active links read as loud accent fills instead of the
clean instructors look.
Changes per file:
* labs/, kits/: extend section-header selector list to include
`a.sidebar-link.text-start`; drop `font-weight: 400 !important` from
the leaf rule so the section-header weight (600) wins on elements
matching both; move active-state color/background/weight into the
high-specificity `#quarto-sidebar` guard block to beat Bootstrap's
default `.sidebar-link.active { color: var(--bs-primary) }`.
* book/quarto/: same treatment, plus include `.part-divider` in the
section-header selector list to keep the part-divider hierarchy.
* tinytorch/quarto/: same active-state hardening, plus rename
`$accent` → `$accent-dark` throughout (the theme partial
shared/styles/themes/_theme-tinytorch.scss declares both variables;
since Quarto auto-`!default`s every scss:defaults declaration, the
reassignment of `$accent` here was silently ignored and rgba calls
resolved with the light #D4740C value). Drop the unused
`$link-color-dark` definition that referenced `$accent-dark` from
scss:defaults — Quarto hoists user defaults above shared partial
defaults, so `$accent-dark` isn't yet defined when that line runs.
Rules in scss:rules resolve `$accent-dark` correctly because rules
are processed after all defaults are merged.
Verified with Playwright probes on /vol1.html (slides), /index.html
(labs, kits), /big-picture.html (tinytorch), /api-stability.html
(mlsysim), /foundations-syllabus.html (instructors): all six now show
white active text on rgba(accent, 0.15) tint, weight 500, with bright
section headers (#e6e6e6) at weight 600 and muted leaf links (#888888
or #cbd5e1).
Extends PR #1633's instructors fix to the rest of the Quarto ecosystem.
Quarto renders floating sidebars with `<a class="sidebar-link">` and
`<a class="sidebar-item-toggle">` directly (not nested inside an
`.sidebar-item a` wrapper), so the legacy selector missed all real DOM
nodes.
Sites updated:
* slides, interviews, tinytorch/quarto, mlsysim/docs: full hardening
(toggle, leaf-link, active-state, search input, TOC rail).
* labs, kits, book/quarto: added missing search-input theming
(core sidebar and TOC fix already present from earlier work).
Each site's accent color is preserved: indigo for instructors and
interviews, pink for slides, amber for tinytorch, cyan for mlsysim,
teal for kits and labs, crimson for book.
- Remove retired _archive/ and scripts/archive/ trees (site, book filters, games, vault); vault CHANGELOG points to git history for old scripts.
- CONTRIBUTING: site project row, site/ in area map, root vs TinyTorch pre-commit, vault schema drift wording.
- Newsletter CLI: path-agnostic news alias; tinytorch pre-commit comments; add tools/ and staffml-vault-types READMEs for maintainers.
#1617 unseeded the module-level rng in tinytorch/src/03_layers/03_layers.py
to make the perceptron milestone produce different weights on every run.
But Linear.__init__ reads weight init from that rng, so the change made
Linear init nondeterministic across the entire codebase. The integration
test tests/integration/test_training_flow.py::test_deep_network_gradient_chain
specifically depends on Linear having stable init; empirical sweep over
5000 random draws shows the test fails 27.5% of the time under unseeded
init, which is why the Windows CI run failed in #1617.
Restore the seed=7 default in 03_layers.py and instead rebind layers.rng
to an unseeded RNG locally inside the perceptron milestone, mirroring
the pattern already used by the XOR milestone (#1618). This keeps the
perceptron's "different weights every run" promise without breaking
unrelated tests.
Milestone 3 (XOR Solved) was unconditionally announcing
'✅ Training Complete - XOR Solved!' and a green '🎉 Success! You Ended
the AI Winter!' panel showing 'Final accuracy: 75.0% (Perfect XOR
solution!)' even when the network was stuck at the classic 75%
dead-ReLU saddle point and had clearly not solved XOR.
Gate both messages on a 0.95 convergence threshold:
- On convergence: keep the existing celebration panel.
- Below threshold: show a yellow warning that training did not
converge, explain the dead-ReLU saddle-point symptom, and tell
the student to re-run the milestone or use a larger hidden
layer instead of moving on to Milestone 03 on a broken result.
Relates to #1613
The migration from np.random.seed() to default_rng() (commit d30257577c)
inadvertently broke the XOR convergence guarantee in milestone 3 (XOR
Solved). The intended seeding line became dead code:
rng = np.random.default_rng(7) # local var, never used
The active weight-init RNG lives at tinytorch.core.layers.rng. With its
default seed (7), the 4-unit hidden layer initializes into a dead-ReLU
saddle point: training stalls at 75% accuracy (one XOR case stuck at
p~=0.5) regardless of how long it runs.
Re-seed tinytorch.core.layers.rng to 1986 (the year of the backprop
paper) immediately before building the model. This restores deterministic
100% convergence in 500 epochs while preserving the original
hidden_size=4 pedagogy and all surrounding educational text.
Verified: before -> 75.0% test accuracy, after -> 100.0% test accuracy.
Relates to #1614
The module-level `rng = np.random.default_rng(7)` at the top of
`src/03_layers/03_layers.py` was reused for every `Linear(...)` weight
init, so every run produced identical weights. Milestone 1's UI text
("No random seed - each run will be different!") contradicted this, and
the issue reporter rightly expected weights to vary.
Drop the seed in two places:
- `src/03_layers/03_layers.py`: the module-level `rng` is now unseeded.
Local seeded RNGs inside test/demo blocks (around lines 829, 848, 981)
are unchanged - those want determinism for reproducible self-tests.
- `milestones/01_1958_perceptron/01_rosenblatt_forward.py`: the data-gen
RNG is also unseeded so the cluster points vary too, matching the
on-screen claim.
Verified by running the milestone twice: cluster positions, predictions,
and accuracy now differ between runs (e.g., 100% "got lucky" vs 0%
"random guessing"). `Linear(...)` weights also differ across fresh
constructions within a single run.
Relates to #1611
The status display sliced the milestone list with `[:3]`, so once any three
milestones were unlocked or ready, every milestone after that vanished from
the output. After unlocking milestones 01, 02, 03 the student would no longer
see that milestones 04, 05, 06 were ready to unlock — they appeared to drop
off the dashboard entirely.
Iterate over the full readiness list instead. The list has at most six
entries, so output stays compact, and "ready" milestones beyond the third
unlocked one are now visible.
Relates to #1615
`_check_milestone_readiness` carried its own copy of the milestone-to-modules
mapping that had drifted from the canonical `MILESTONE_SCRIPTS` definition in
`tito/commands/milestone.py` (and from `_get_milestone_for_module` above in
the same file). The status display said milestone 03 (MLP Revival) was ready
to unlock once modules 1-6 were complete, even though the milestone actually
needs the full training stack through module 8. Milestones 04-06 had similar
gaps that omitted modules 7 and 8.
Update the list to match the canonical requirements:
03: [1..6] -> [1..8]
04: [1..6, 8, 9] -> [1..9]
05: [1..6, 11..13] -> [1..8, 11..13]
06: [1..6, 14..19] -> [1..8, 14..19]
Add a docstring noting that this list is a mirror and must be kept in sync.
Relates to #1612
The h3 and pre code rules set near-white colors unconditionally, which
made these elements unreadable in light mode. Gate them on
[data-bs-theme="dark"] so light mode falls back to its own contrast.
Adopt the shared release-versioning pattern. Pure additions: no
existing build steps, configs, or sources are touched. The 6-place
manual version sprawl in the publish workflow stays as-is —
pyproject.toml remains the canonical source the manifest READS from.
quarto/_quarto.yml:
- <meta name="release-manifest" content="/tinytorch/release-manifest.json">
added to include-in-header so the pill's runtime fetch resolves
correctly under /tinytorch/.
- shared/release/release-pill.html added to include-after-body so
every rendered page carries the pill in the DOM.
.github/workflows/tinytorch-publish-live.yml:
- New "📦 Emit release manifest" step inserted between the slide-deck
download and the gh-pages deploy. Runs scripts/version/release.py
compute-hash over modules/, quarto/ (excluding _build), pyproject.toml,
MANIFEST.in. Writes release-manifest.json into the site build dir
so it deploys at /tinytorch/release-manifest.json.
The pill is best-effort chrome — silent if the manifest is missing,
which keeps preview-dev and local renders from breaking. Production
publishes always emit it before deploy, so the live site shows
"TinyTorch v0.1.10 · Apr 28, 2026" in the footer once this lands.
Same regression as vol1/vol2 references.bib (commit 42bc54275 figure-audit
feat) — five auxiliary bib files (interviews/paper, mlsysim/docs,
mlsysim/paper, periodic-table/paper, tinytorch/paper) had brace patterns
mangled in titles, e.g. 'Throughput-Latency Tradeoff in {LLM} Inference'
became 'Throughput-Latency Tradeoff in {LLM}} Inference', which
bibtex-tidy refuses to parse.
Restored to the parent of 42bc54275 (state at 9ebdf77d0) and
re-formatted via the bib_apply_mechanical + bibtex-tidy hooks.
Three small but layered fixes that together make every page under the
tito CLI module fully readable in light mode, dark mode, and the hybrid
state where data-bs-theme="dark" stays sticky on <html> while the light
stylesheet is the active bundle.
- Light-fill panel text-color safety net (style.scss). Pairs with the
bg-flip safety net upstream introduced in 2707c0546. The bg-flip only
fires in dark mode; this rule fires in both modes and pins text
inside inline-styled light-fill cards (tito/modules.qmd, tito/data.qmd,
etc.) to #1e293b regardless of what --bs-body-color resolves to.
Without it, cards stayed light-fill in the hybrid state but text
inherited the dark-palette light body color = invisible. The matching
!important `color: #e6e6e6` line in dark-mode.scss flips back when
the card flips to #2d2d2d.
- Code blocks inside cards. The previously-merged
`pre code { color: #e6e6e6 }` rule was painting plain (no-language)
fenced blocks light grey on the light card surface — visible on the
box-drawing console output blocks under "Understanding the Export
Process" on tito/modules.qmd. Nest a `pre code, code` override inside
the safety-net selector list so card code is dark in light/hybrid and
light in true dark mode.
- Scope existing global h3 + pre code overrides to [data-bs-theme="dark"].
Both rules were left unscoped previously to compensate for the hybrid
state. The card safety net above now handles hybrid for cards, so the
global rules can be properly scoped — fixes the "### Milestone
Achievements: `tito milestone status`" h3 on tito/data.qmd which was
rendering #d0d0d0 on white in true light mode.
- Table zebra-stripe override (style.scss). shared/styles/partials/_tables.scss
sets the even-row bg to #fafbfc unconditionally; on the dark body the
light text inheriting from --bs-body-color was invisible against the
light row stripe. Add a [data-bs-theme="dark"]-scoped rule using a
subtle white-overlay rgba so striping survives without hard-coding
a specific dark hue.
Light mode unchanged on every page that doesn't use inline-styled cards.
Map inline 700/600 Material accent text to 400-shade variants for WCAG on
#2d2d2d surfaces; add linear-gradient(e3f2fd...) panel rule missed by
solid background hex selectors.
Reverts solution stripping added for #1508 (ff870d5f3). tito module start again
builds notebooks from complete src, including BEGIN/END SOLUTION blocks, so
nb_export output matches the source-of-truth and user-journey CI stays valid.
Iterates on the post-merge 404 redesign across all 8 sub-sites:
- SVG roofline-plot fonts bumped for readability without changing
layout: axis labels 9.5pt to 14pt, region labels 9.5pt to 14pt,
title and "your page (404)" annotation 11pt to 16pt.
- Random-joke font shrunk from 1.6rem to 1.3rem (1.1rem on mobile)
so the joke no longer dominates the SVG above it.
- Removed the static "Looks like this page slipped past our load
balancer" subline from 6 sub-sites — it read as a competing static
joke alongside the random rotation. Slides and instructors keep
their informational sublines.
- Joke pool tightened 97 to 79 via a strict ML-systems-centric test:
if you could swap "page" for any generic web/ops resource and the
joke still works, cut. Cuts removed the H&P canonical material
(Amdahl's Law, TLB miss, Dennard scaling, false sharing, fat-tree
topology) that is general computer architecture rather than ML
systems specifically. 19 borderline jokes were rewritten to anchor
punchlines in concepts only ML practitioners decode (KV cache,
gradient AllReduce, prefill, ZeRO, speculative-decode acceptance,
1F1B schedule, ridge point, BPE merges).
Three small follow-ups on top of the recent dark-mode UX work
(#1529 / #1532-style fixes already on dev):
- _quarto.yml: split `highlight-style: github` into
`light: github` / `dark: github-dark` so code blocks pick up
proper dark theme tokens instead of the light theme over a
dark surface.
- style.scss: pin .who-card paragraphs to #475569 (slate-500)
so they stay readable on the #fafafa card surface even when
the page is in the hybrid state where data-bs-theme="dark"
is set on <html> but the light stylesheet is active — body
color flips to #dee2e6 in that case and inheriting it
invisibly bleached the cards. Also add the global
`#quarto-content h3 { color: #d0d0d0 !important }` and
`pre code { color: #e6e6e6 }` overrides so subheadings and
code text remain readable in dark mode (h3 here is needed
because Quarto re-loads the light bundle as
quarto-color-scheme-extra after the dark bundle, so equal-
specificity rules from _headers.scss otherwise win).
- dark-mode.scss: pair the .who-card paragraph fix above —
when the card flips to #2d2d2d in dark mode, paragraphs
go to #e6e6e6 to match.
Replace the inline-game 404 across all 8 sub-sites with a unified
design: roofline-plot illustration, random pick from a 97-joke
editorial-curated pool, dual CTA (home + playground), and a
GitHub-issue-backed contribute link for community submissions.
The joke pool was curated through a multi-agent editorial process:
4 generators (each with a different ML systems lens) produced 240
candidates; 5 reviewer personas (architect, NLP researcher, production
engineer, undergrad, copy editor) scored each; the synthesizer kept 92
surviving jokes plus 5 new canonical-architecture additions (Amdahl,
TLB, Dennard, false sharing, fat-tree topology) the architect flagged
as missing from the H&P-tradition canon.
Self-contained CSS with prefers-color-scheme: dark adapts to host
themes without coupling to each sub-site's bespoke styling. SVG
follows the book's semantic palette (blue memory-bound slope, green
compute roof, MIT red error annotation). Per-site navigation
preserved across all sub-sites.
Adds .github/ISSUE_TEMPLATE/404_joke.yml so contributions arrive
structured (joke text, theme dropdown, license checkbox) and
auto-tagged (site, 404-joke, good-first-issue) for triage.
