* 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>
These tools (quizzes.py, footnote_assistant.py, etc.) are superseded
by the agent-based workflow. Removes 7 files (~392 KB) and updates
README references.
- Completed full Volume 1 refactor to Safe Class Namespace pattern.
- Fixed render errors and verified all 16 chapters.
- Updated 'binder' CLI with native validation and maintenance namespaces.
- Enhanced VS Code extension with Chapter Navigator and Run History.
- Integrated 'binder validate' into pre-commit workflows.
* Restructure: Move book content to book/ subdirectory
- Move quarto/ → book/quarto/
- Move cli/ → book/cli/
- Move docker/ → book/docker/
- Move socratiQ/ → book/socratiQ/
- Move tools/ → book/tools/
- Move scripts/ → book/scripts/
- Move config/ → book/config/
- Move docs/ → book/docs/
- Move binder → book/binder
Git history fully preserved for all moved files.
Part of repository restructuring to support MLSysBook + TinyTorch.
Pre-commit hooks bypassed for this commit as paths need updating.
* Update pre-commit hooks for book/ subdirectory
- Update all quarto/ paths to book/quarto/
- Update all tools/ paths to book/tools/
- Update config/linting to book/config/linting
- Update project structure checks
Pre-commit hooks will now work with new directory structure.
* Update .gitignore for book/ subdirectory structure
- Update quarto/ paths to book/quarto/
- Update assets/ paths to book/quarto/assets/
- Maintain all existing ignore patterns
* Update GitHub workflows for book/ subdirectory
- Update all quarto/ paths to book/quarto/
- Update cli/ paths to book/cli/
- Update tools/ paths to book/tools/
- Update docker/ paths to book/docker/
- Update config/ paths to book/config/
- Maintain all workflow functionality
* Update CLI config to support book/ subdirectory
- Check for book/quarto/ path first
- Fall back to quarto/ for backward compatibility
- Maintain full CLI functionality
* Create new root and book READMEs for dual structure
- Add comprehensive root README explaining both projects
- Create book-specific README with quick start guide
- Document repository structure and navigation
- Prepare for TinyTorch integration
