Add shared/config/_ecosystem-cards.qmd: one source of truth for the
'Part of the MLSysBook Ecosystem' section (full 7-member set). Each landing
page includes it; a small script marks the current site 'You are here' by
reading that site's own release-manifest meta, so one block shows each page
its own state. Replace the divergent inline sections in kits (3 hand-written
cards) and labs (prose paragraph); add the section to slides, instructors,
and mlsysim.
Add shared/config/footer-common.yml (mirrors navbar-common.yml) and point
slides, labs, kits, and instructors at it via metadata-files, replacing their
drifted inline footers. The release pill now lives in the footer right slot
(not dangling below the page) as a fixed muted-gray chip, pinned so it looks
identical regardless of each site's theme accent. mlsysim and the book keep
their own footers (dual license / build stamp) but carry the same pill span.
release-pill.html is now assets-only and populates every data-release-pill
span from each site's own release-manifest.
Replace pointers to the private project rules/docs tree (relative .claude/rules
and .claude/docs paths) in code comments and docstrings with neutral phrasing
("the project prose style guide", etc.). Load-bearing runtime paths that the
tooling reads or writes are left intact.
Pedagogical alignment pass across all 35 Beamer decks (Vol I + Vol II),
auditing each deck against its source textbook chapter and the project's
slide/speaker-note standards.
Content alignment:
- 92 numeric/equation corrections to match the chapter's canonical
(mlsysim-computed) values: e.g. Iron Law of Scale restored to 4 terms
(T_sync coordination term), 175B checkpoint 1,050->1,750 GB / 4.5->7.6 PB,
H100 ridge point made internally consistent (989 FP16), GPT-4 memory
FP32->FP16 label, twelve->thirteen invariants in the conclusion.
- 119 chapter-grounded additions: missing war stories (Amazon recruiting,
Knight Capital, OVH fire, OpenAI gang-scheduling, Google Photos, etc.),
thinner-than-chapter Fallacies & Pitfalls slides, and named equations /
lighthouse archetypes folded back in.
- Course-overview rebuilds: Bitter Lesson, Software 2.0, silent-vs-loud
failure (Vol I); Three Walls and Iron Law of Scale through-line (Vol II).
Lecture/render quality:
- Added [N min] timing tags to 958 speaker notes that lacked them.
- Reconciled learning objectives in 17 decks to the chapters' current LOs.
- Fixed 3 compile failures (corrupt image regen, \mlsysfocus un-nesting,
literal # escaping) and drove every overfull hbox/vbox to zero across all
35 decks, preferring slide-splits over content cuts (no content removed).
- New thirteen-invariants figure for the conclusion deck.
All 35 decks compile with 0 errors and 0 overfull boxes.
Add fix_lightbox_paths.py post-render script to rewrite lightbox hrefs
for mediabag SVGs — Quarto generates the wrong path, causing 404 on
click-to-enlarge. Fixes 210 links across 30 chapter files in both
volumes. Also replace stale scholar.harvard.edu URL in slides README.
Every subsite's announcement bar Line 1 carried a 'Start reading →' / 'Start building →' / 'Get started →' link that pointed at the very subsite the reader was already on. Clicking it was a no-op self-navigation.
Strip the CTA from Line 1 across all 8 sites that have the regression:
- announcement-vol1.yml drop 'Start reading →'
- announcement-vol2.yml drop 'Start reading →'
- tinytorch drop 'Start building →'
- mlsysim drop 'Get started →'
- kits drop 'Get started →'
- labs drop 'Preview →'
- slides drop 'Browse decks →'
- instructors drop 'Start here →'
Line 1 keeps the bold identity statement, which is what readers came for. The other lines (Vol I / II links, sibling row, newsletter CTA) keep their navigations since they DO lead somewhere new.
announcement-book.yml is unchanged — its Line 1 already points at the ecosystem root (https://mlsysbook.ai/), not at /book/ where the reader is.
01_intro_test.tex and 01_introduction_test.tex were copies of
01_introduction.tex used during the pdflatex migration's local
verification step (commit 65c27263d8). The cleanup rm in the
verification script didn't fire in time before `git add slides/vol1`
picked them up. Removing here as a follow-up.
Switches 35 chapter decks (slides/vol1 + slides/vol2) and 2 mlsysim
tutorial decks (mlsysim/tutorial/slides/tutorial_part{1,2}.tex) from
xelatex+fontspec+texgyreheros to pdflatex+helvet+courier.
Why
---
Yesterday's slides-publish-live shipped PDFs with completely blank text
(see https://github.com/harvard-edge/cs249r_book/releases/download/
slides-latest/vol1_00_course_overview.pdf — Liberation Sans was
embedded but glyphs were missing because xelatex on Ubuntu CI could
not find texgyreheros.otf and silently fell back). The mlsysim
tutorial decks fared no better, requiring four rounds of fixes
(Helvetica Neue → texgyreheros → tex-gyre apt + mktexlsr → Latin
Modern) before they would even compile.
The root cause is engine choice: fontspec on xelatex makes runtime
OS-font discovery the build's critical path. If the host TeX install
or fontconfig doesn't have the requested font, fontspec either errors
hard (mlsysim's experience) or silently substitutes (slides' silent
broken-PDF failure mode). Either way the build is fragile.
paper.tex has been using pdflatex+helvet+mathpazo+courier for months
without a single font issue. Bringing slides + mlsysim tutorial onto
the same engine + font convention eliminates the entire failure class.
Changes
-------
* 35 chapter decks: replace
\usepackage{fontspec}
\setsansfont{texgyreheros}[Extension=.otf, ...]
\setmonofont{texgyrecursor}[Extension=.otf, ...]
with
\usepackage[T1]{fontenc}
\usepackage[scaled=0.9]{helvet}
\usepackage{courier}
\renewcommand{\familydefault}{\sfdefault}
Same Helvetica-class look (NimbusSans = URW's Helvetica clone in
helvet), shipped via texlive-fonts-recommended Depends.
* 2 mlsysim tutorial decks: same swap (was Latin Modern from the prior
retry).
* slides/Makefile: LATEX := xelatex → pdflatex.
* mlsysim/tutorial/Makefile: same.
* slides-build-pdfs.yml: drop texlive-xetex (engine), drop
texlive-fonts-extra (was for tex-gyre). Result: smaller apt-install,
no fontspec silent-fallback class of bugs.
* mlsysim-build-pdfs.yml: same engine + apt cleanup; drop JetBrains
Mono manual fc-cache step (we no longer reference JetBrains Mono).
Bar copy
--------
* mlsysim/docs/config/announcement.yml: append Lecture Slides to the
"Alongside the book" row — the mlsysim tutorial deliverable IS slides,
so cross-linking is natural.
* site/config/announcement.yml: drop the "🎓 Teach with it: Lecture
Slides · Instructor Hub" line entirely from the landing bar. Landing
is for learners; teachers find Instructor Hub via the navbar Teach
menu, and Slides via Instructor Hub.
Verification
------------
Local Mac builds with pdflatex:
- vol1/01_introduction: 52 pages, NimbusSans-Regu/Bold embedded
- vol2/05_distributed_training: 48 pages, NimbusSans embedded
- mlsysim tutorial_part1: 90 pages, NimbusSans embedded
- mlsysim tutorial_part2: 47 pages, NimbusSans embedded
All Type 1, sub-set, Unicode tag yes — renders cleanly.
The .inv-table cells on slides/index.qmd hardcoded light-mode colors,
leaving the What's Included and Related Resources rows with text that
disappears on the dark background. Added dark-mode overrides for
column text, row hover, and last-column action links.
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.
Two issues caused the deployed slide PDFs to be unusable:
1. Every chapter .tex declared `\setsansfont{Helvetica Neue}` — proprietary
to Apple, not installed on the Ubuntu CI runner. xelatex bombed mid-frame,
the workflow's `|| true` swallowed the error, and the resulting PDF had
most text never typeset (blank pages with only logos/rules surviving).
Switch all 35 decks to TeX Gyre Heros (sans) and TeX Gyre Cursor (mono),
both bundled with texlive-fonts-extra — no external font downloads needed.
Drop the JetBrains Mono wget step and fonts-liberation from both slide
workflows accordingly.
2. Vol1 and Vol2 each ship `00_course_overview.pdf` and `01_introduction.pdf`.
The publish workflow uploaded them to a flat GitHub Release namespace, so
the second upload silently overwrote the first — clicking Vol I's Course
Overview actually downloaded Vol II's deck. Stage prefixed copies
(vol1_*.pdf, vol2_*.pdf) before upload, and update slides/vol{1,2}.qmd
plus the mlsysim cross-links to point at the new prefixed URLs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Follow-up to #1424. The link-rot tracker reported 405 broken URLs on
the Slides site, dominated by `tinyMLx/courseware/raw/master/edX/...`
references. After de-duplicating, only 6 unique URLs were actually
broken — the other ~325 occurrences were references to those same
6 dead targets repeated across the deck inventory pages.
Cross-checking each broken path against the upstream repo's actual
contents (via the GitHub Contents API) revealed two categories:
CATEGORY A — file exists with extended title; URL needs encoding
- readings/5-11-1.pdf → readings/5-11-1%20Responsible%20AI%20Intro.pdf
- readings/5-11-3.pdf → readings/5-11-3%20Sustainable%20AI.pdf
Both upstream files contain the title in the filename
(e.g. "5-11-1 Responsible AI Intro.pdf"). The bare-number form in our
source matched the upstream README, which is itself broken; the
URL-encoded extended form returns 200.
CATEGORY B — file genuinely missing in upstream repo
- other/2-1-14.pdf ("Assignment Solution")
- readings/4-7-11.pdf ("Deploying a Multi-Tenant Application")
- slides/3-1-6.pdf ("What You'll Learn in This Course")
- slides/5-6-X.pdf ("Model Conversion") — `X` is a literal placeholder
in the upstream README too
No correct URL exists; the upstream README references these as
broken links. Replaced the entire `<a>` cell content with an em-dash
(—), preserving the table layout and the topic name in the adjacent
cell, but removing the broken link.
Files touched:
slides/tinyml-mlops.qmd (2 URL fixes + 1 em-dash)
slides/tinyml-applications.qmd (1 em-dash)
slides/tinyml-deploying.qmd (1 em-dash)
slides/tinyml-fundamentals.qmd (1 em-dash)
After this lands, the next nightly link-rot run should report Slides
site clean of `tinyMLx/courseware` failures.
Two surgical fixes for the nightly link-rot tracker (#1424):
1. **shared/config/.lycheeignore**: add two patterns that suppress
confirmed false positives reported in the tracker.
- JS template literals (`${m.github}`): when Lychee parses a .qmd
containing JavaScript with template literals like
`https://github.com/${m.github}`, the literal is URL-encoded in
the AST as `$%7B…%7D` and reported as broken. The literal is
substituted at runtime; it is never a real URL. Pattern matches
any `${ANY.ANY}` template-literal residue.
- GitHub avatar URLs (`github.com/<user>.png?size=N`): manually
verified that every avatar URL flagged by the tracker
(profvjreddi, Mjrovai, etc.) returns 200 in a browser. Lychee
unreliably HEADs them due to GitHub's avatar throttling.
Together these cover the 8 remaining "broken" links on the Unified
Site that are not real failures.
2. **slides/teaching.qmd**: replace a markdown link to
`.claude/rules/svg-style.md` with plain prose. The `.claude/`
directory is gitignored in this repo, so the URL
github.com/harvard-edge/cs249r_book/blob/main/.claude/rules/svg-style.md
404s. Mention the SVG style guide in prose without the broken link.
Out of scope for this patch: the 329 `tinyMLx/courseware/raw/master/...`
links in slides/, which point to PDFs that don't exist in the upstream
repo (the directory exists, but the specific file numbers don't). That
is a content/strategic question — needs a decision on whether to
upload missing PDFs, switch repos, or remove the links — and is left
for a separate workstream.
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).
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.
Align the MLSys·im code, docs, paper, website, workflows, and lab wheel for the 0.1.1 release. This also fixes runtime/API issues found during release review and prepares the paper PDF plus archive package.
Align public README and site messaging around the curriculum components, adoption paths, and current early-release status so newcomers can move from reading to building, deployment, practice, and teaching.
- Added font-family='Arial, Helvetica, sans-serif' to all SVG root tags to ensure clean, consistent textbook styling.
- Enforced strict high-contrast text colors, replacing pure black with a slightly softer dark gray (#333) for primary labels to adhere to the semantic style guide.
Audited all SVG figures in Volume 2 to align with textbook aesthetic guidelines.
- Replaced rounded corners (rx, ry) on <rect> elements with sharp corners.
- Converted assorted unapproved colors to the rigorous semantic palette
defined in the style guide (e.g. #cfe2f3 for compute, #d4edda for data,
#f9d6d5 for errors, plus standard grays).
- Automated a headless browser check (Puppeteer) to evaluate the rendered
layout, identifying and rectifying ~87 text element overlaps caused by
the font or box shifting. Adjusted coordinate spacing on problem files
such as the WSE and HBM architecture diagrams.
Every site's announcement bar now follows one template:
Line 1 — identity + primary CTA (what is THIS site)
Line 2 — the book (or, on book sites, the other volume)
Line 3 — "Alongside the book:" sibling row (3 most-relevant verbs)
Line 4 — newsletter
The book is the anchor of the curriculum; every other site is a verb
applied to it — TinyTorch (build), Hardware Kits (deploy), MLSys·im
(simulate), Labs (explore), Slides + Instructors (teach). Making that
shape visible in every bar turns nine independent sites into chapters
of one curriculum.
Removed stale copy: "Happy New Year!" on kits + labs, "coming in 2026"
on labs (we are in 2026; replaced with "Coming Summer 2026"), TinyTorch
v0.1.10 single-line release notice (belonged in a release changelog,
not the always-visible nav bar).
Normalized outbound links: /book -> /vol1/ and /vol2/, consistent
trailing-slash hygiene on every URL. Newsletter link points to
https://mlsysbook.ai/newsletter/ (the actual Quarto page) instead of
#subscribe (which only resolves on the landing page).
The landing site (mlsysbook.ai) uses a 5-line variant that covers all
four learner verbs + the teacher-tools row; every other site uses the
4-line form.
StaffML is a Next.js app, not a Quarto site, so its banner is out of
scope for this PR and will ship as a separate React component change.
Add `text` language tag to 25 unlabeled fenced code blocks across the
public-facing READMEs. Mostly directory-tree listings, all-contributors
bot instructions, and pseudo-output ASCII blocks — none were getting
syntax highlighting anyway, but the explicit tag silences markdownlint
MD040 and signals intent ("this is plain text, not a forgotten lang").
GitHub's github-markdown-css applies:
.markdown-body table { display: block; width: max-content; max-width: 100%; }
The HTML width="100%" attribute is a presentational hint with lower
specificity than the class selector, so tables with short cell content
were sizing to max-content and not stretching to fill the column.
Tables with long sentences per cell stretched fine, masking the bug.
Add inline style="width:100%" (specificity 1,0,0,0) which overrides
the class-selector rule. Keep width="100%" attribute as a fallback for
non-GitHub renderers (VSCode preview, GitLab, plain HTML viewers).
54 tables updated across 10 READMEs + the two contributor-sync scripts
that regenerate auto-managed tables.
The sub-project READMEs used an old-school nested-table card design
with hardcoded bgcolor="#ffffff", "#cfd6dd", "#eef2f7" plus deprecated
HTML4 attributes (cellpadding, cellspacing, border). It looked good in
light mode but produced harsh white islands in GitHub's dark theme,
which is what most readers see today.
Across 11 sub-READMEs:
- Strip the card wrapper so data tables are just clean
<table width="100%"> with semantic <thead>/<tbody>. Headers keep
their column widths; bgcolor/valign/zebra-stripe cruft is removed
(GitHub provides its own theme-aware striping).
- Convert the early-release callouts (and mlperf-edu's two-tier
status block + "source of truth" note + interviews' two info boxes)
to GitHub-native > [!NOTE] / > [!WARNING] / > [!TIP] callouts.
These are theme-aware, get proper icons, and render correctly in
light AND dark mode.
Net result: 528 lines of HTML cruft removed, 230 lines of clean
markdown added. Visual identity is preserved (callouts still stand
out, tables still stretch full-width) while becoming dark-mode safe
and consistent with the main README.
Add `width="100%"` to every HTML content and contributor table across all
project READMEs so they render full-width on GitHub instead of collapsing
to natural content width. Cell-level `width="X%"` percentages were already
in place but only take effect once the table itself has an explicit width.
Also update the contributor-sync scripts so the auto-generated tables stay
consistent on the next bot run:
- .github/workflows/contributors/generate_main_readme.py
- .github/workflows/contributors/generate_readme_tables.py
Scope: 27 files, 85 tables. Sub-project READMEs that already use the
"card" pattern (labs/, kits/ content sections with <table width="98%">
wrappers) are intentionally untouched.
- Add wrap_readme_data_tables.py to frame <table>+<thead>/<tbody> blocks in a
98% width panel (#cfd6dd border, #eef2f7 headers, zebra body rows where
applied manually in converted tables).
- Apply wraps to book, kits, labs, slides, tinytorch; tbody wraps for kits
docs/related and instructors overview.
- Convert remaining Markdown tables in mlsysim, mlperf-edu, and interviews to
the same HTML pattern; replace StaffML markdown callouts with HTML panels.
- Add thead rows to kits/instructors body-only tables for clearer hierarchy.
- mlperf-edu: stacked HTML panels (amber under construction + gray early-work
note) at top; replace workload-table markdown quote with HTML callout.
- slides, labs, mlsysim: rename DEV-BANNER comments to EARLY-RELEASE-CALLOUT
for consistency with other project READMEs.
Replace markdown blockquotes with a shared centered table pattern
(cellpadding, bgcolor panel, h3 + aligned paragraphs) so GitHub renders
consistent spacing. Align labs and mlsysim DEV-BANNER with the same layout
and 2026 messaging.
Use a short top-of-README callout for periodic-table, StaffML, TinyTorch,
slides, and instructors: live with the 2026 release, expect steady iteration,
link to GitHub issues. Slides banner replaces dev-only wording with the same
framing while keeping dev/live badges.
* feat(footer): build-time "last updated" stamp
Add a small build-time stamp to the page footer ("Last updated YYYY-MM-DD
· <site> · <commit>") so readers can see at a glance that the site is
fresh. Quarto's per-page `date-modified` already exists for chapter
pages, but it doesn't capture site-level rebuilds (theme tweaks,
navbar changes, deploy reruns).
Pieces:
- shared/scripts/inject-build-stamp.sh: wraps a token-replace over a
build directory. Search-and-replace on `<!-- MLSB_BUILD_STAMP -->`
means sites that haven't adopted the token are unaffected — opt-in
rollout per subsite.
- book/quarto/config/shared/html/footer-common.yml: token added next
to the existing copyright line in the shared book footer.
- shared/config/footer-site.yml: token added next to the copyright
in the unified-site footer.
- shared/config/site-head.html: minimal CSS for `.mlsb-build-stamp`
(small, neutral, dark-mode aware).
- .github/workflows/kits-publish-live.yml: representative wiring —
runs the stamp step after build and before deploy. Other publish-
live workflows can adopt the step the same way as they roll
through release-prep validation.
* feat(navbar): expose paper.pdf for TinyTorch / MLSys·im / StaffML
Each of these subsites already builds a companion paper.tex in CI and
ships the PDF alongside the HTML site. Surface those papers in the
navbar dropdowns where readers actually look for them:
Build menu:
- TinyTorch → site
- TinyTorch Paper (file-pdf icon, opens in new tab)
→ /tinytorch/assets/downloads/TinyTorch-Paper.pdf
- MLSys·im → site
- MLSys·im Paper (file-pdf icon, opens in new tab)
→ /mlsysim/mlsysim-paper.pdf
Prepare menu (after a separator):
- StaffML Paper (file-pdf icon, opens in new tab)
→ /staffml/downloads/StaffML-Paper.pdf
Paper URLs are intentionally kept in lockstep with the build steps in
tinytorch-publish-live (assets/downloads/), mlsysim-publish-live
(site root), and staffml-publish-live (out/downloads/). If a build
path moves, both the workflow and this navbar entry need to move
together — there is no single source.
* feat(404): per-site 404 pages for slides / instructors / unified site
The book, kits, labs, mlsysim, and tinytorch subsites already have
flavored 404.qmd pages that route lost readers to the right
neighborhood. Add the missing three so every subsite under
mlsysbook.ai has a coherent recovery experience instead of falling
back to GitHub Pages' default white-page 404.
- slides/404.qmd — slide-deck flavored copy, pointers back to
the deck index, the volumes, and the hub.
- instructors/404.qmd — instructor-flavored copy, pointers to the
course map, slides, and both volumes.
- site/404.qmd — landing-page flavored copy, the most
ecosystem-wide nav (links to every subsite)
because this is the most common 404 source
for inbound links from the legacy single-
volume mlsysbook.ai.
StaffML already has its own React not-found.tsx so no work needed.
TinyTorch's legacy Sphinx 404.md is preserved for now (still wired on
the Sphinx site that hasn't migrated yet).
* ci(precommit): block subsite-mirror drift on shared assets
Add a pre-commit hook that runs `shared/scripts/sync-mirrors.sh --check`
on every commit. The hook fails if any of the per-subsite real-file
mirrors (subscribe-modal.js, theme SCSS partials, logo) has drifted
from its canonical source in `shared/`.
Why a guard, not just a sync: Quarto's resource-copy step preserves
symlinks instead of dereferencing them, so we have to keep real
copies. Without the guard, "I'll edit the canonical and forget to
re-sync" silently re-introduces the duplicate-divergence bug we just
spent effort fixing. `always_run: true` because a mirror can drift via
deletion of the canonical, not just by editing the canonical itself.
To re-sync after a deliberate change:
bash shared/scripts/sync-mirrors.sh
* refactor(audit): duplicate-file finder + clean up obvious leftover
Add shared/scripts/find-duplicates.py as a periodic duplication
auditor. It SHA-1 hashes every source-y file across the ecosystem
roots, groups identical contents, subtracts the intentional groups
declared in shared/scripts/sync-mirrors.sh, and reports the rest as
unintended duplicates. JSON report written to .audit/duplicates.json
for CI ingest later; --strict makes it exit non-zero.
Defaults err on the side of being useful out of the box:
- Skips symlinks (those are deliberate aliases, not duplicates).
- Skips small files (<256B) — LICENSE stubs, .gitkeep, etc.
- Skips _site / _build / node_modules / .next / out / .git.
- Source-y suffix list (.js, .ts, .scss, .css, .html, .yml, .py, .sh).
Binary assets (images, PDFs) are NOT scanned because their dup
story is different (logos, icons are intentionally repeated).
Initial-cleanup pass:
- Delete tinytorch/scripts/cleanup_repo_history.sh — byte-identical
leftover; the canonical version lives at
tinytorch/tools/maintenance/cleanup_history.sh and is the one
referenced by tinytorch/tools/maintenance/README.md.
After this commit the only remaining unintended duplicate is
runHistoryProvider.ts in three vscode-ext packages (kits / labs /
tinytorch). Promoting that into a shared vscode-ext package is real
refactor work — out of scope for release-prep, captured for later.
Add .audit/ and _audit/ (the latter from the Playwright site-audit
script) to .gitignore.
* docs(release-prep): handoff notes covering all five PR groupings
Add a single document at the worktree root that walks through what
this branch contains, why each piece is there, the recommended PR
split (PR-1 safety-net, PR-2 visual polish, PR-3 scripts/audits/
cleanup, PR-4 TinyTorch prep, PR-5 cutover skeletons), what was
intentionally LEFT OUT (and why), and what verification was done
locally vs. what still needs the dev mirror to exercise.
Treat this as the cover memo for the staged-rollout foundation
work; once the five PRs are individually merged into dev, this file
will outlive the branch but the per-PR sections still document why
each piece exists for anyone debugging months from now.
Audit of the eight sub-project READMEs showed inconsistent surrounding
text around the auto-managed contributor table — some had a Legend line,
some didn't; instructors used a different heading style; interviews was
missing the thanks blurb and CTA; mlsysim was missing the END marker
and the recognition CTA.
Standardize all eight to the same template: heading + thanks blurb +
legend + ALL-CONTRIBUTORS markers + Recognize-a-contributor CTA.
Per-project quirks preserved: interviews keeps its closing author
sign-off paragraph; CTA wording stays project-specific (e.g. labs
suggests "code, tutorial, test, or doc" while kits suggests
"tool, test, video, or doc").
Per-project sections kept (not consolidated into root). Sub-READMEs
are landing pages, sub-projects could be extracted to standalone repos
later, and recognition is more meaningful where the work lives. The
root README continues to aggregate everything via the existing
sectioned tables.
Closes the gap where Slides and Instructor Site were first-class Quarto
sites but invisible to the contributor recognition pipeline, and fixes
two pre-existing holes for mlsysim/interviews.
Workflows
- all-contributors-add.yml: add `slides` and `instructors` to PROJECTS;
add `slide`/`instructor` aliases. Tighten the LLM prompt with explicit
multi-type and emoji/punctuation rules, and add a deterministic regex
fallback that scans the trigger comment for type keywords and unions
them with the LLM result so a flaky classification never drops a tag.
- update-contributors.yml: add `mlsysim`, `interviews`, `slides`,
`instructors` to the push trigger paths and to the file/commit lists,
so edits to those configs actually rebuild and push READMEs.
Generators
- generate_main_readme.py: refactor the per-section block to a single
PROJECT_SECTIONS table so adding a project is one line; add Slides
and Instructor Site sections.
- generate_readme_tables.py: register `slides` and `instructors`.
Configs / READMEs
- New `slides/.all-contributorsrc` and `instructors/.all-contributorsrc`
seeded with profvjreddi.
- Add ALL-CONTRIBUTORS-LIST markers + recognize-a-contributor blurb to
`slides/README.md` and `instructors/README.md`.
- Regenerate root, slides, instructors, and (sorted-badge drift) the
interviews README via the generators.
Docs
- Refresh `.github/workflows/contributors/README.md` to list all 8
projects and document the canonical-list-in-PROJECTS contract.
- Replace inline Google Fonts <link> tags in all 8 site configs with
a single `- file: shared/config/site-head.html` reference, so fonts
(Inter 400-800, JetBrains Mono) and Font Awesome are inherited from
one shared file instead of duplicated across every _quarto.yml
- Add missing Inter weight 800 (was only in site-head.html, not configs)
- Add carousel CSS + JS for MLSys·im landing page (arrows, dots, slides,
auto-rotation, keyboard nav) — fixes non-functional < > buttons
All 7 public-facing Quarto sites now have consistent announcement
bars with icon: megaphone, type: primary, position: below-navbar.
Previously only tinytorch, labs, kits, book, and mlsysim had them.
Establish a consistent convention across all subsite preview workflows:
- Every site uses SUBSITE_ROOT for source directory path
- Every site uses DEV_SUBSITE_PATH for deploy target path
- All output directories standardized to _build (slides was _build/html)
GitHub variables created/updated:
- INSTRUCTORS_ROOT=instructors (new)
- SLIDES_ROOT=slides (new)
- DEV_INSTRUCTORS_PATH=instructors (new)
- TINYTORCH_SITE=tinytorch/site-quarto (updated from tinytorch/site)
Updated workflows: instructors-preview-dev, slides-preview-dev,
slides-validate-dev, tinytorch-preview-dev. Also added announcement
modification step to instructors and tinytorch (matching kits pattern).
Add dark-mode.scss and enable dark theme in _quarto.yml so the slides
portal has the same dark mode toggle as all other Quarto sites.
Uses brightened Deep Rose (#F472B6) accent for dark backgrounds.
Replace duplicated navbar/mobile responsive rules in satellite sites
(instructors, kits, labs, mlsysim, slides) with a single import of
shared/styles/partials/_mobile.scss. Removes ~169 lines of copy-pasted
CSS that would drift out of sync when the shared partial is updated.
- instructors: remove rogue desktop padding, add _mobile import
- kits: remove ~50 lines of duplicated mobile rules, add _mobile import
- labs: remove ~55 lines of duplicated mobile rules, add _mobile import
- mlsysim: remove ~55 lines of duplicated mobile rules, add _mobile import
- slides: add _mobile import (had no mobile rules before)
Every subsite now sets $accent to its brand color and imports
shared/styles/partials/_navbar.scss instead of duplicating the
~40-line navbar block locally. Single source of truth for link
color, hover/active states, brand image height, icon-collapse
media query, and color-scheme toggle.
Drift fix: before this, instructors had font-size: 0.9rem +
weight 500 (making navbar look smaller than peer sites) and
slides had no navbar CSS at all (fell back to Bootstrap defaults).
Both now match the ecosystem.
Also renames $accent in labs/style.scss (previously hot pink
#e94560, used only by .coming-badge) to $coming-badge-pink to
free $accent for the ecosystem convention.
Net: -168 lines of duplicated SCSS across 6 files.
- interviews/staffml/LICENSE — MIT (app code, fork freely)
- interviews/LICENSE — All Rights Reserved (corpus, taxonomy, pipeline)
- book/LICENSE — CC BY-NC-ND 4.0 (educational content)
- kits/LICENSE — CC BY-NC-ND 4.0 (educational content)
- labs/LICENSE — CC BY-NC-ND 4.0 (educational content)
- slides/LICENSE — CC BY-NC-ND 4.0 (educational content)
- instructors/LICENSE — CC BY-NC-ND 4.0 (educational content)
The moat is the vault data, not the viewer. MIT for the app encourages
adoption and contributions. Proprietary for the corpus protects the IP.
Vijay Janapa Reddi
Rocky
Farhan AsgharandGitHub
