- Add war story callout definition in custom-numbered-blocks.yml
- Create war story icon in all three formats (SVG, PNG, PDF) matching
the 64x64 stroke-only style used by all other callout icons
- Add war story bibliography and PDF config entry
- Add first war story ("The Quadratic Wall") in nn_architectures
- Include icon conversion utility script
Aligns the Distributed Training chapter with the Volume 2 'Systems Sandwich'
framework, establishing it as the 'Operational Layer' of the Machine Learning Fleet.
Key changes:
- Refactors 'Purpose' and 'Learning Objectives' to use rhetorical pivots and
focus on the 'Physics of the Fleet'.
- Updates Python setup cell to use the 'Safe Class Namespace' pattern (P.I.C.O.)
and adds Archetype A (GPT-4) constants.
- Rewrites 'Multi-Machine Scaling Fundamentals' to center on the
'Communication-Computation Ratio' and the 'Law of Distributed Efficiency'.
- Cross-references the Volume 2 Introduction definitions to create a cohesive narrative.
Aligns the rhetorical style and quantitative rigor of the Volume 2
Introduction with the established Volume 1 standards.
Introduces the "Machine Learning Fleet" narrative as the central
engineering challenge of Volume 2, shifting from single-node
optimization to cluster-scale orchestration.
Key changes:
- Establishes the "Law of Distributed Efficiency" and "CI Ratio"
(Communication Intensity) as new quantitative frameworks.
- Defines the "Reliability Gap" to address statistical failure
certainty in massive clusters.
- Refactors all TikZ diagrams (Systems Sandwich, Roadmap, AI Triad)
to use project-standard colors and Helvetica font.
- Updates the "Lighthouse Archetypes" to focus on throughput,
latency, and resource-bound fleet challenges.
- Implements P.I.C.O. math patterns for fleet-scale calculations.
Renames and restructures the framework evolution section to
"The Ladder of Abstraction," emphasizing the problem-solving
nature of each abstraction layer.
Clarifies the role of each layer (BLAS/LAPACK, NumPy,
Deep Learning Frameworks) in solving specific problems related
to performance, usability, and differentiation, respectively.
Highlights the trade-offs between productivity and transparency
as we move up the abstraction ladder.
Refines the notation section to explicitly state the use
of decimal SI prefixes for data, memory, and compute.
Updates wording for clarity and consistency, specifically
addressing units, storage, and compute contexts.
Ensures that the book uses only decimal SI prefixes and
specifies the formatting of numbers and units.
- debugCommands: prompt for format (PDF, HTML, EPUB) in Build All Chapters (Parallel)
- parallelDebug: clearer success/fail messages, Open Reports Folder, REPORT.md header
- README: document volume + format selection for parallel builds
Checkpoint the branch-wide content/config revisions together with workbench enhancements so chapter rendering and developer workflows stay aligned. This captures the current validation-driven formatting and parallel build/debug improvements in one commit.
Use a file watcher to detect when the PDF is created/modified during
build, then automatically open it in VS Code. Build still runs in the
visible terminal so users see progress. Also fix LaTeX comma-in-title
bug in foldbox.tex by bracing the title argument inside tcolorbox options.
Convert all remaining lowercase 'x' used as multiplication (e.g.,
"1000x faster") to $\times$ across 17 vol2 chapters. These were
flagged by the new lowercase_x_multiplication validator check.
Simplifies the validator regex from a fragile word-list approach to a
broader pattern matching digit-x-lowercase (e.g., \dx\s+[a-z]) which
naturally excludes hardware counts (8x A100) and hex literals (0x61).
Includes the conversion script in _archive.
Convert all Unicode × (U+00D7) to LaTeX $\times$ in prose, tables, and
math contexts across both volumes. Unicode × is preserved only inside
fig-alt text for accessibility screen readers. One instance inside a
plain markdown backtick code span (frameworks.qmd) was reverted to
Unicode × since LaTeX doesn't render in code spans.
Updates validate.py with a new lowercase-x-as-multiplication check and
refines the latex_adjacent warning to distinguish _str variables (safe)
from raw inline Python. Updates validate_inline_refs.py comments to
reflect the new convention. Includes the conversion script in _archive.
Audited all 52 backward-looking prose references ("recall", "as we saw",
"introduced earlier") across all 16 Vol I chapters. Found 46 valid and
6 with issues; fixed the 4 actionable ones:
- benchmarking: fix dual attribution for energy-movement claim
- hw_acceleration: fix imprecise "100x" energy gap to "orders-of-magnitude"
- hw_acceleration: change "introduced in" to "mentioned in" for HBM ref
- conclusion: correct invariant attribution from data_engineering to Part I
Audit report: .claude/_reviews/2026-02-15_backward-reference-audit.yaml
Add a persistent health indicator to the extension: a status bar item
that shows pass/warn/error at a glance, plus a health summary node at
the top of the Pre-commit tree view. Fast in-process TypeScript checks
run on file save, editor switch, and startup (<100ms per file).
Checks: duplicate labels, unclosed div fences, missing figure alt-text,
and unresolved in-file cross-references.
- Add src/validation/qmdChecks.ts with four pure check functions
- Add src/validation/healthManager.ts with central status tracker
- Wire HealthManager into extension.ts with status bar and event hooks
- Add expandable health summary node to PrecommitTreeProvider
- Register showHealthDetails command in package.json
Second pass catching ~37 additional instances missed in the initial
cleanup, including prose in frameworks, glossary definitions, footnotes,
fig-caps, fig-alts, table cells, and callout content.
All remaining `Nx` patterns are now exclusively inside Python code
blocks (comments, docstrings, f-strings) or are mathematical variable
expressions (e.g., derivative = 2x), which are correct as-is.
Integrate figure rendering into the binder CLI so plots can be previewed
without a full Quarto build. Extracts Python code blocks with fig-* labels
from QMD files, renders them to PNG, and outputs a browsable gallery at
_output/plots/<chapter>/. Also fixes the package import chain so `binder`
works correctly as an installed entry point.
- Add book/cli/commands/render.py with RenderCommand class
- Wire into main.py with help table entry and command dispatch
- Add matplotlib>=3.7.0 to pyproject.toml dependencies
- Add book/quarto/_output/ to .gitignore
- Archive standalone render_figures.py to _archive/
Every callout-takeaways block across Vol 1 now has a title attribute
that captures the chapter's core insight rather than repeating the
chapter name. Titles are drawn from each chapter's purpose question
or central thesis, answering "what should a student remember six
months from now?" Examples: "Constraints Drive Architecture" (Intro),
"Perfectly Available, Perfectly Wrong" (ML Ops), "Architecture Is
Infrastructure" (Network Architectures).
Typed references (@tbl-, @fig-, @sec-, @lst-, @eq-) and label
definitions ({#tbl-...}, {#fig-...}) were all rendering in generic
blue because overlapping decorations overrode the typed colors.
Fix by collecting typed matches first and excluding them from
generic/structural buckets. Also fix label-definition regexes to
match labels with trailing attributes (e.g. {#fig-foo fig-env=...}).
Change footnote colors from invisible slate-gray to distinct pink/rose
for clear visual separation from other reference types.
Remove all 27 individual color-override settings (mlsysbook.color*)
since only the preset picker (subtle/balanced/vivid) is needed.
Remove QmdDiagnosticsManager and WorkspaceLabelIndex which caused
false-positive blue squiggles during workspace index loading. Pre-commit
hooks already validate cross-references and inline Python at commit time.
Also remove div fence marker highlighting (Quarto handles natively),
add !inFence guards to label line checks, remove broken reference
decoration, and change footnote colors from gold to muted slate-gray
to convey their marginal/supplementary nature.
Remove redundant ml_ prefix from ml_workflow chapter files and update all
Quarto config references. Consolidate custom scripts into native binder
subcommands and archive obsolete tooling.
- Default label types now include Equation (was missing from default set)
- --check-patterns now defaults to True for inline-refs
- Removed redundant --all-types from VSCode extension command
All five label types (Figure, Table, Section, Equation, Listing) are
now always checked unless explicitly filtered with --figures/--tables/etc.
Port all custom validation and maintenance scripts into the binder CLI
as native subcommands, eliminating the need for standalone scripts.
New `binder validate` subcommands (10):
- section-ids: verify all headers have {#sec-...} IDs
- forbidden-footnotes: check footnotes in tables/captions/divs
- footnotes: validate footnote refs/defs (undefined, unused, duplicate)
- figure-completeness: check figures have captions and alt-text
- figure-placement: audit figure/table proximity to first reference
- index-placement: check LaTeX \index{} placement
- render-patterns: detect problematic rendering patterns
- dropcap: validate drop cap compatibility
- part-keys: validate \part{key:...} against summaries.yml
- image-refs: validate image references exist on disk
New `binder maintain` subcommands (2):
- section-ids (add/repair/list/remove): full section ID lifecycle
- footnotes (cleanup/reorganize/remove): footnote management
Updated 11 pre-commit hooks to use binder commands instead of scripts.
Updated VSCode extension commands to use binder CLI.
All validators verified against original script output (parity confirmed).
- Add WorkspaceLabelIndex: scans all .qmd files on activation, updates
incrementally on save, provides hasLabel() for cross-file validation
- Extend QmdDiagnosticsManager to validate references against workspace
index (not just current file); triggered on save only, not keystrokes
- Add broken reference decoration (red wavy underline) in chunk
highlighter for refs that don't resolve to any label in the workspace
- Add commands: Add Missing Section IDs, Verify Section IDs,
Validate Cross-References (command palette)
- Enable diagnostics by default (save-triggered, not noisy)
- Support YAML-style label definitions (#| label:, #| fig-label:, etc.)
- Run manage_section_ids.py to add 294 missing section IDs and
standardize 62 non-conforming IDs to hierarchy-based format
- Fix 12 double-hash bugs (e.g., -cbb8-cbb8 -> -cbb8) from script
- All cross-references updated to match new IDs (19 refs across files)
- Verified clean: check_unreferenced_labels.py and check_duplicate_labels.py pass
- Add book-verify-section-ids pre-commit hook (runs --verify mode, ~1.5s)
- Add Python value resolver that executes QMD code blocks and resolves
inline `{python} var` references to their actual values
- Display resolved values as ghost text, hover tooltips, and CodeLens
- Unwrap IPython.display.Markdown objects (.data) and display_value dicts
for readable output instead of object reprs
- Suppress matplotlib plot windows during resolution (Agg backend)
- Split inline Python highlighting into keyword + variable decorations
- Disable callout/div body and table region background highlights by
default (too noisy); fence markers and cross-references still colored
- Add settings: showInlinePythonValues, showInlinePythonCodeLens,
highlightCalloutBackground, highlightTables (default: false)
Moves common diagram and PDF title/build settings into shared metadata layers, simplifies per-volume configs to keep only volume-specific values, and carries related chapter figure text/asset updates needed in the current working set.
Unifies Quarto metadata into shared base/format/volume fragments while carrying through chapter path, asset, and tooling updates to keep the repository consistent and easier to maintain.
- Completed full standardization of 150+ calculation headers across all 16 Volume 1 chapters.
- Replaced legacy 'Why:' blocks with the 'Goal/Show/How' documentation pattern.
- Finalized P.I.C.O. class refactors for complex cells in frameworks and serving.
- Verified header consistency across introduction, ml_systems, training, and optimizations.
- Performed minor stabilization in book/vscode-ext logic.
Standardize Quarto config/style handling for HTML/EPUB volume builds, add explicit binder reset commands by format, and align QMD reference/label highlighting so structural tokens share consistent visual semantics.
Treat internal spacing changes as real formatting differences and normalize separator padding so table prettification is applied consistently. Save files before running pre-commit fixers from the extension so results match editor state.
- Refactored ops_scale.qmd to P.I.C.O. pattern and standardized constants.
- Standardized TikZ colors in storage.qmd (fig-storage-hierarchy) and distributed_training.qmd.
- Verified elimination of magic numbers (1e9, 3600, etc.) across all Volume 2 Python cells.
- Completed full conversion of narrative guards to check() helper in Volume 2.
- Refactored appendix_algorithm.qmd, appendix_data.qmd, and appendix_dam.qmd to P.I.C.O. pattern.
- Integrated standardized constants (BILLION, THOUSAND, SEC_PER_HOUR) in all appendix calculations.
- Simplified narrative guards in appendices using the check() helper.
- Verified backmatter consistency across both volumes.
- Refactored Volume 2 core chapters (Intro, Dist Training, Storage) to P.I.C.O. pattern.
- Moved Young-Daly checkpoint optimization logic from Storage to Distributed Training.
- Eliminated magic numbers (1e9, 3600, etc.) from all Volume 2 calculation cells.
- Implemented central 'chapter-start' cells with shared imports for consistency with Vol 1.
- Standardized time (SEC_PER_HOUR, SEC_PER_DAY), memory (KIB_TO_BYTES), and scale (BILLION, TRILLION) constants in mlsys/constants.py.
- Refactor reordered time constants to fix NameError in constants.py.
- Refactored 90+ narrative guards across Volume 1 to use the simplified check() helper.
- Eliminated remaining magic numbers (1024, 3600, 1e9, etc.) from Python calculation cells.
- Adopted 'Goal / Show / How' documentation structure for key P.I.C.O. scenarios.
- Performed minor stabilization and feature polish in book/vscode-ext.
- 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.
- ml_systems.qmd: Fixed NameError in CloudEdgeTCO/EdgeSizing exports (replaced undefined '_value' vars with class attributes).
- training.qmd: Fixed IndentationError in TrainingDimensions class.
- Refactored FlashAttentionSpeedup, GradientAccumulation, and TrainingCarbonFootprint to Safe Class Namespace pattern.
- Added P.I.C.O. structure and invariant checks.
- Exported variables for prose integration.
- Fixed inline Python validation warnings (replaced LaTeX math with Unicode).
