* fix(content): clear two mitpress-above-below pre-commit failures
The "📚 Book · ✅ Validate (Dev)" workflow has been failing on dev for
8+ consecutive runs because the mitpress-above-below pre-commit hook
flags spatial references like "above"/"below" inside body prose and
figure captions (the MIT Press style guide wants @sec-/@fig- cross-refs
or "earlier"/"later" instead). Two pre-existing violations were tripping
the hook on every push:
- book/quarto/contents/vol1/responsible_engr/responsible_engr.qmd:1604
fig-cap for fig-data-governance-pillars said "obligations discussed
below: privacy, security, compliance, and transparency" — but those
four obligations are *immediately* listed in the same caption, so
"discussed below" was redundant. Reworded to "obligations of
privacy, security, compliance, and transparency …".
- book/quarto/contents/vol2/network_fabrics/network_fabrics.qmd:1217
fig-cap for fig-congestion-cascade said "the PFC backpressure
cascades described below." Reworded to "described later in this
section." which is what the hook wants.
After our 4 release-prep merges (PR-1/2/7/12) cleaned up the other
hook failures (spelling, bibtex tidy, pipe tables, contractions,
mitpress-vs-period, …), this was the last remaining failing hook.
Verified locally:
pre-commit run mitpress-above-below --all-files
MIT Press: No above/below spatial refs (use cross-refs).....Passed
These are pure copy-edits to figure captions; no semantic change to
the diagrams or surrounding text.
* fix(check-internal-links): suppress 4 categories of false positives
The Tier 1 link checker (shipped in PR #1404) was over-eager and
flagged author content as broken in four documented patterns:
1. TikZ source inside HTML comments. Link regex matched `\node[mycycle](B1)`
as a Markdown link `[mycycle](B1)`. Fix: strip `<!-- ... -->` bodies
before scanning, preserving line/column offsets so any *real* failure
we report stays accurate.
2. Quarto cross-references like `[Foo](@sec-bar)`, `@fig-x`, `@tbl-y`.
These resolve through the project xref index at render time, not the
filesystem; book/binder owns that validation. Fix: skip targets whose
first token is `@sec-/@fig-/@tbl-/@eq-/@lst-/@thm-/@cor-/@def-/@exr-/
@exm-/@prp-`.
3. Uppercase URL schemes (`HTTPS://`, `HTTP://`) — common after mobile
auto-capitalize or copied citations. Fix: case-insensitive prefix
match for the EXTERNAL_SCHEMES tuple.
4. GitHub-style emoji-prefix slugs in `.md` READMEs (e.g.
`## 🎯 20 Progressive Modules` produces anchor `#-20-progressive-modules`
on github.com, but Pandoc would slugify to `progressive-modules`).
Fix: register both Pandoc-style and GitHub-style slugs as valid
anchors so neither rendering target trips the checker.
Drops repo-wide broken-link count from 150 → 84 (false positives only;
no real link rot is masked). Real rot is fixed in a separate commit so
the checker improvement can be reviewed independently.
* fix(content): repair internal-link rot across 10 files
Concrete link rot the new checker (PR #1404) surfaced once its false
positives were cleared. None of these are stylistic; each link points
at a path or anchor that does not exist.
- README/README_{zh,ja,ko}.md (24 links): translation files live in
README/ so paths to repo-root targets need a `../` prefix
(`book/README.md` -> `../book/README.md`, etc.).
- mlsysim/docs/contributing.qmd (21 links): `../slides/...` pointed
inside `mlsysim/`; the slides root is two levels up
(`../../slides/...`).
- mlsysim/docs/cli-reference.qmd: `getting-started.qmd#bring-your-own-yaml-byoy`
removed; retarget to `#defining-custom-models` (closest surviving
section about user-supplied model specs).
- mlsysim/docs/for-engineers.qmd, for-instructors.qmd:
`solver-guide.qmd#extending-mlsysim` no longer exists; retarget to
`#writing-a-custom-solver` (the surviving custom-solver guide).
- book/tools/scripts/README.md: `../docs/BINDER.md` resolved to
`book/tools/docs/BINDER.md` (nonexistent); the file actually lives
at `book/docs/BINDER.md`, which is `../../docs/BINDER.md` from here.
- book/quarto/contents/frontmatter/index.qmd:
`about.qmd#about-the-book-unnumbered` anchor was removed when the
About heading was simplified; drop the anchor so the link lands at
the top of the page (which IS the About section).
- tinytorch/datasets/tinytalks/README.md: `scripts/README.md` was
never created; point at the directory listing instead.
* chore(pre-commit): exclude 3 forward-looking files from internal-link checker
Three files reference content that does not (yet) exist on the
filesystem; the references are intentional rather than rot, so they
should not block CI:
- labs/index.qmd: lists the 33 planned labs (vol1/lab_00..lab_16,
vol2/lab_01..lab_16) as a roadmap. Links go live as each lab ships.
De-linking now would lose the visual roadmap. When a lab lands the
exclusion narrows naturally on its own.
- labs/PROTOCOL.md, labs/TEMPLATE.md: internal authoring docs that
reference `../.claude/docs/labs/{PROTOCOL,TEMPLATE}.md`. The
`.claude/` tree is per-worktree and not always present at the same
relative path; these are author-tooling refs, not user-facing.
Net effect: the link checker is now green on a clean checkout. The
exclude block uses comments per existing convention so the rationale
is discoverable from the config alone.
* fix(content): clear codespell, contractions, and vs. pre-commit failures
Three pre-existing pre-commit hooks were failing on the dev branch
prior to the release-prep merges. Each is a small content normalization:
- codespell (2): re-declares -> redeclares (book/quarto/config/shared/README.md);
unparseable -> unparsable (handled in the check-internal-links rewrite).
- contractions (2):
* socratiq/socratiq.qmd callout: "If you're" -> "If you are".
* nn_architectures fig-alt for the attention-visualization figure:
"didn't" -> "did not". Alt-text is descriptive prose for screen
readers, not a verbatim transcription of pixels, so expanding the
contraction matches MIT Press style without changing the figure
itself.
- mitpress-vs-period (6): bare `vs` -> `vs.` per MIT Press 2026 §10.5
in benchmarking.qmd, distributed_training.qmd (x3 across two Python
docstrings rendered in code listings), fault_tolerance.qmd, and
inference.qmd. Code-listing strings are visible prose in the rendered
PDF, so the rule applies there as well.
* chore: bibtex-tidy auto-format outputs
Outputs of the bibtex-tidy pre-commit hook (which auto-fixes its own
input). Picked up here so that running pre-commit on a clean checkout
no longer reports a "files were modified" failure for the same files
on every invocation. Pure formatting; no entry semantics changed.
- Sync translated READMEs (ja, ko, zh) with renamed workflow files and
add Slides, Instructors, StaffML badges
- Fix Docker Windows README paths and workflow reference
- Rewrite book/tools/scripts README to point to Binder CLI first
- Update kits badge from kits-publish to kits-validate
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add Kits, Labs, and MLSys·im badges alongside existing Book and TinyTorch.
Switch from markdown to HTML img syntax for consistent vertical alignment.
Split into two rows: build status and meta badges. Updated across all
four language READMEs (en, zh, ja, ko).
Add README translations in Chinese (zh), Japanese (ja), and Korean (ko) with language switcher links.
Changes made by maintainer:
- Standardized file names to ISO 639-1 codes
- Fixed year target (2026 → 2030) to match main README
- Added language switcher to all READMEs
