Merge remote-tracking branch 'origin/dev' into feature/colab-integration

Remove tracked build artifacts that should be regenerated:
- Diagram PDFs (3 files): Auto-generated by Quarto diagram extension
- Quarto HTML support files (frontiers_files): Bootstrap, clipboard, etc.

Update .gitignore to prevent future tracking:
- Add **/*_files/ pattern for Quarto HTML support directories
- These are auto-generated and should not be in version control

Cleanup also performed locally (not tracked in git):
- Removed .bak backup files
- Removed Python __pycache__ directories
- Removed loose diagram-*.pdf files from quarto root

All removed files will be regenerated automatically during builds.

.all-contributorsrc

@@ -97,6 +97,13 @@
             "profile": "https://github.com/JaredP94",
             "contributions": []
         },
+        {
+            "login": "didier-durand",
+            "name": "Didier Durand",
+            "avatar_url": "https://avatars.githubusercontent.com/didier-durand",
+            "profile": "https://github.com/didier-durand",
+            "contributions": []
+        },
         {
             "login": "ishapira1",
             "name": "Itai Shapira",
@@ -118,13 +125,6 @@
             "profile": "https://github.com/jaysonzlin",
             "contributions": []
         },
-        {
-            "login": "didier-durand",
-            "name": "Didier Durand",
-            "avatar_url": "https://avatars.githubusercontent.com/didier-durand",
-            "profile": "https://github.com/didier-durand",
-            "contributions": []
-        },
         {
             "login": "andreamurillomtz",
             "name": "Andrea",

.github/workflows/link-check.yml

@@ -47,7 +47,7 @@ jobs:
       
       - name: 🔗 Check Links
         id: lychee
-        uses: lycheeverse/lychee-action@v1.9.3
+        uses: lycheeverse/lychee-action@v2.0.2
         with:
           args: --verbose --no-progress --exclude-mail --max-concurrency ${{ inputs.max_concurrency || 10 }} --accept 200,403 --exclude-file config/linting/.lycheeignore ${{ inputs.path_pattern || './quarto/contents/**/*.qmd' }}
         env:

.gitignore

@@ -32,6 +32,7 @@ __pycache__/
 /.quarto/
 /_book/
 /quarto/.quarto/
+**/*.quarto_ipynb
 
 # Build directory (new structure)
 /build/

CALLOUT_STYLING_ANALYSIS.md

@@ -1,489 +0,0 @@
-# Custom Callout Styling Architecture Analysis
-
-**Branch**: `refactor/consolidate-callout-styles`  
-**Date**: 2025-11-09  
-**Purpose**: Document current architecture and propose consolidation for easier maintenance
-
----
-
-## Current Architecture (As-Built)
-
-### File Structure
-
-**4 Files Handle Callout Styling:**
-
-1. **`quarto/_extensions/mlsysbook-ext/custom-numbered-blocks/style/foldbox.css`** (33 refs)
-   - **Purpose**: Core extension styles
-   - **Contents**: 
-     - Color variables (--border-color, --background-color) for all callout types
-     - Base layout and structure
-     - Icon positioning and sizing
-     - Light mode defaults
-     - Dark mode overrides (lines 310-370)
-   - **Loaded**: Always (by extension)
-   - **Role**: PRIMARY source of truth
-
-2. **`quarto/assets/styles/style.scss`** (52 refs - MOST!)
-   - **Purpose**: Defensive overrides to prevent Quarto interference
-   - **Contents**:
-     - Exclusions from general `.callout` styling (removes box-shadow, borders)
-     - Left-alignment rules for content/lists/summaries
-     - Empty paragraph handling for definition/colab
-   - **Loaded**: Compiled into BOTH light AND dark themes
-   - **Role**: DEFENSIVE - neutralizes Quarto's default callout styles
-
-3. **`quarto/assets/styles/dark-mode.scss`** (36 refs)
-   - **Purpose**: Dark mode color overrides
-   - **Contents**:
-     - Text colors for dark backgrounds (#e6e6e6)
-     - Border colors for dark mode (#454d55)
-     - Summary text colors (#f0f0f0)
-   - **Loaded**: Compiled into ONLY dark theme
-   - **Role**: DUPLICATION - repeats foldbox.css dark mode section
-   - **⚠️ ISSUE**: `callout-colab` is MISSING from dark-mode.scss!
-
-4. **`quarto/assets/styles/epub.css`** (31 refs)
-   - **Purpose**: EPUB-specific fallbacks
-   - **Contents**: 
-     - Styles for plain `<div>` rendering (when extension disabled)
-     - Includes `::before` pseudo-elements for titles
-     - Fallback for all callout types including colab
-   - **Loaded**: Only in EPUB builds (specified in `_quarto-epub.yml`)
-   - **Role**: FALLBACK for non-extension rendering
-
----
-
-## Build System Integration
-
-###HTML Builds
-
-```yaml
-# _quarto-html.yml
-theme:
-  light:
-    - default
-    - assets/styles/style.scss          # ← Compiled in
-  dark:
-    - default
-    - assets/styles/style.scss          # ← Compiled in
-    - assets/styles/dark-mode.scss      # ← Compiled in
-```
-
-**Result**: 
-- `foldbox.css` loaded directly from extension
-- `style.scss` and `dark-mode.scss` compiled into theme CSS
-- Dark mode activated via `@media (prefers-color-scheme: dark)`
-
-### EPUB Builds
-
-```yaml
-# _quarto-epub.yml
-css: "assets/styles/epub.css"
-```
-
-**Result**:
-- ONLY `epub.css` is used
-- `foldbox.css` MAY be included by extension (needs verification)
-- No dark mode support (EPUB readers handle themes)
-
----
-
-## Problems Identified
-
-### 1. **Duplication**
-Dark mode styles exist in BOTH:
-- `foldbox.css` (lines 310-370)
-- `dark-mode.scss` (lines 715-750)
-
-**Example**:
-```css
-/* foldbox.css */
-@media (prefers-color-scheme: dark) {
-  details.callout-definition {
-    --text-color: #e6e6e6;
-    --background-color: rgba(27, 79, 114, 0.12);
-  }
-}
-
-/* dark-mode.scss */
-details.callout-definition {
-  --text-color: #e6e6e6 !important;
-  border-color: #454d55 !important;
-}
-```
-
-### 2. **Inconsistency**
-`callout-colab` is:
-- ✅ In `foldbox.css` dark mode section
-- ✅ In `style.scss` exclusion rules
-- ✅ In `epub.css` fallbacks
-- ❌ MISSING from `dark-mode.scss`
-
-### 3. **Scattered Logic**
-- Structural styles → `foldbox.css`
-- Exclusion rules → `style.scss`
-- Dark mode → BOTH `foldbox.css` AND `dark-mode.scss`
-- EPUB fallbacks → `epub.css`
-
-### 4. **Unclear Separation**
-Not obvious which file handles what without deep investigation.
-
----
-
-## Recommended Consolidation (Option A)
-
-### **Extension-First Architecture**
-
-**Principle**: The custom-numbered-blocks extension should be self-contained.
-
-```
-foldbox.css          → ALL callout styles (light + dark, structure, colors)
-style.scss           → ONLY minimal Quarto interference prevention
-epub.css             → ONLY EPUB fallbacks (extension disabled)
-dark-mode.scss       → REMOVE callout-specific rules (handled by foldbox.css)
-```
-
-### Detailed Changes
-
-#### 1. `foldbox.css` - Keep As-Is (Self-Contained) ✅
-- Already contains light mode colors
-- Already contains dark mode section (`@media`)
-- Already handles all structural styling
-- **Action**: KEEP - no changes needed
-
-#### 2. `style.scss` - Minimal Exclusions Only
-```scss
-/* ONLY exclude custom foldbox callouts from Quarto's default styling */
-.callout.callout-quiz-question,
-.callout.callout-quiz-answer,
-.callout.callout-definition,
-.callout.callout-example,
-.callout.callout-colab {
-  margin: 0 !important;
-  border: none !important;
-  box-shadow: none !important;
-  background: transparent !important;
-}
-
-/* Left-align content (Quarto defaults to center for some elements) */
-.callout.callout-quiz-question div,
-.callout.callout-quiz-answer div,
-.callout.callout-definition div,
-.callout.callout-example div,
-.callout.callout-colab div {
-  text-align: left !important;
-}
-
-/* Hide empty paragraphs generated by extension */
-.callout-definition > p:empty,
-details.callout-definition p:empty,
-details.callout-definition > div > p:empty,
-.callout-colab > p:empty,
-details.callout-colab p:empty,
-details.callout-colab > div > p:empty {
-  display: none !important;
-}
-```
-
-**Removed from style.scss**:
-- All `details.callout-*` styling (let foldbox.css handle)
-- List alignment (let foldbox.css handle)
-- Summary alignment (let foldbox.css handle)
-
-#### 3. `dark-mode.scss` - Remove ALL Callout Rules
-```scss
-/* REMOVE THESE (already in foldbox.css): */
-details.callout-definition,
-details.callout-example,
-details.callout-quiz-question,
-... etc ...
-```
-
-**Rationale**: `foldbox.css` already has a `@media (prefers-color-scheme: dark)` section that handles all dark mode styling for callouts.
-
-#### 4. `epub.css` - Keep As-Is (Fallback) ✅
-- Needed for when extension is disabled
-- **Action**: KEEP - no changes needed
-
----
-
-## Alternative: Add Missing colab to dark-mode.scss (Option B)
-
-**IF** we keep the current architecture, then we must:
-
-```scss
-/* dark-mode.scss - ADD MISSING */
-details.callout-colab {
-  --text-color: #e6e6e6 !important;
-  border-color: #454d55 !important;
-}
-
-details.callout-colab summary,
-details.callout-colab summary strong,
-details.callout-colab > summary {
-  color: #f0f0f0 !important;
-}
-```
-
-**But this still leaves duplication problem unsolved.**
-
----
-
-## Testing Plan
-
-### Before Changes
-1. ✅ Build HTML intro: `./binder html intro`
-2. ✅ Build EPUB intro: `./binder epub intro`
-3. **TODO**: Test light mode callouts (definition, example, quiz, colab)
-4. **TODO**: Test dark mode callouts (toggle dark mode in browser)
-5. **TODO**: Test EPUB rendering
-
-### After Changes
-1. Repeat all above tests
-2. Verify NO visual differences
-3. Confirm dark mode still works
-4. Confirm EPUB still renders correctly
-
----
-
-## Recommendation
-
-**Proceed with Option A (Extension-First):**
-
-**Pros**:
-- Single source of truth for callout styling
-- No duplication
-- Easier to debug (one file for structure, one for overrides)
-- Self-contained extension
-- Cleaner separation of concerns
-
-**Cons**:
-- Requires careful refactoring
-- Must test thoroughly to avoid breaking anything
-
-**Next Steps**:
-1. ✅ Create branch: `refactor/consolidate-callout-styles`
-2. ✅ Build test outputs (HTML + EPUB)
-3. ⏳ Test current dark mode functionality
-4. ⏳ Document expected behavior
-5. ⏳ Make changes one file at a time
-6. ⏳ Test after each change
-7. ⏳ Commit when working
-
----
-
-## Notes
-
-- **DON'T BREAK ANYTHING**: Everything must work exactly as before
-- **Test incrementally**: Change one file, test, commit
-- **Keep git history clean**: Small, focused commits
-- **Document decisions**: Update this file as we go
-
----
-
-## ✅ REFACTORING COMPLETED
-
-**Commit**: `56c30395f` (2025-11-09)  
-**Branch**: `refactor/consolidate-callout-styles`
-
-### Changes Implemented
-
-#### 1. `quarto/assets/styles/dark-mode.scss`
-**Before**: 159 lines of duplicate callout dark mode rules  
-**After**: 13-line comment block explaining foldbox.css handles it
-
-**Removed**:
-- All `details.callout-*` color/background definitions (quiz, definition, example, colab, chapter-connection, resources, code)
-- All summary header text colors (`color: #f0f0f0 !important`)
-- All content body backgrounds (`background-color: #212529 !important`)
-- All arrow styling (`details > summary::after`)
-- All code element colors (`details.callout-* code`)
-- All link colors for callouts (`details.callout-* a { color: lighten($crimson, 10%) }`)
-
-**Added**:
-```scss
-// ============================================================================
-// CALLOUT/FOLDBOX DARK MODE STYLING
-// ============================================================================
-// NOTE: All foldbox/callout dark mode styling is now handled by:
-//   quarto/_extensions/mlsysbook-ext/custom-numbered-blocks/style/foldbox.css
-// 
-// The extension contains a @media (prefers-color-scheme: dark) section that
-// handles all dark mode styling for custom callouts...
-```
-
-#### 2. `quarto/assets/styles/style.scss`
-**Before**: 52 references with redundant alignment rules  
-**After**: 8 references with minimal Quarto overrides
-
-**Removed**:
-- `details.callout-definition > div` left-align rules (44 lines)
-- `details.callout-* ul/ol` list styling rules
-- `details.callout-* li` list item alignment
-- `details.callout-* > summary` header alignment
-- `details.callout-* > summary strong` text alignment
-
-**Kept**:
-```scss
-/* Exclude all custom foldbox callouts from general callout styling */
-.callout.callout-quiz-question,
-.callout.callout-quiz-answer,
-.callout.callout-definition,
-.callout.callout-example,
-.callout.callout-colab {
-  margin: 0 !important;
-  border: none !important;
-  box-shadow: none !important;
-  background: transparent !important;
-  text-align: left !important;
-}
-
-/* Ensure content inside foldbox callouts is left-aligned */
-.callout.callout-* div {
-  text-align: left !important;
-}
-```
-
-#### 3. `quarto/_extensions/mlsysbook-ext/custom-numbered-blocks/style/foldbox.css`
-**No changes required** ✅
-
-Already contained complete styling:
-- Light mode (lines 1-220): colors, borders, backgrounds, icon positioning
-- Dark mode (lines 223-398): `@media (prefers-color-scheme: dark)` with all overrides
-- All callout types: definition, example, quiz-question, quiz-answer, colab, chapter-connection, chapter-forward, chapter-recall, resource-slides, resource-videos, resource-exercises, code
-
-**Verified dark mode includes**:
-```css
-@media (prefers-color-scheme: dark) {
-  details.callout-colab {
-    --text-color: #e6e6e6;
-    --background-color: rgba(255, 107, 53, 0.12);
-    --title-background-color: rgba(255, 107, 53, 0.12);
-    border-color: #FF6B35;
-  }
-  
-  details.callout-colab summary,
-  details.callout-colab summary strong,
-  details.callout-colab > summary {
-    color: #f0f0f0 !important;
-  }
-  
-  details.callout-colab code {
-    color: #e6e6e6 !important;
-  }
-}
-```
-
-### New Architecture
-
-```
-┌────────────────────────────────────────────────────────┐
-│ foldbox.css (Extension - Single Source of Truth)       │
-│ ✅ Light mode: colors, layouts, icons                  │
-│ ✅ Dark mode: @media query with all overrides          │
-│ ✅ ALL callout types fully styled                      │
-│ ✅ Self-contained and portable                         │
-└────────────────────────────────────────────────────────┘
-                         ▲
-                         │ includes
-                         │
-┌────────────────────────────────────────────────────────┐
-│ style.scss (Minimal Quarto Overrides - 8 refs)         │
-│ ✅ Exclude custom callouts from Quarto defaults        │
-│ ✅ Remove box-shadow/borders from wrapper divs         │
-│ ✅ One simple left-align rule for content              │
-└────────────────────────────────────────────────────────┘
-
-┌────────────────────────────────────────────────────────┐
-│ dark-mode.scss (No Callout Rules - 13 lines)           │
-│ ✅ Comment explaining foldbox.css handles everything   │
-│ ✅ Only non-callout dark mode rules remain             │
-└────────────────────────────────────────────────────────┘
-
-┌────────────────────────────────────────────────────────┐
-│ epub.css (EPUB Fallback - Unchanged)                   │
-│ ✅ Fallback styles when extension doesn't run          │
-│ ✅ Plain div rendering without <details>               │
-└────────────────────────────────────────────────────────┘
-```
-
-### Testing Results
-
-#### Build Verification
-```bash
-./binder html intro  # ✅ Success - no errors
-./binder epub intro  # ✅ Success - no errors
-```
-
-#### Output Verification
-```bash
-# Confirmed callout icons render correctly
-grep "callout-definition" quarto/_build/html/.../introduction.html
-# Output: <details class="callout-definition fbx-default closebutton" open="">
-
-# Confirmed dark mode styles present in built CSS
-grep "callout-colab" quarto/_build/html/site_libs/quarto-contrib/foldbox/foldbox.css
-# Found at lines: 166 (light), 354 (dark), 361-379 (dark rules)
-
-# Confirmed CSS is properly linked
-grep "foldbox.css" quarto/_build/html/.../introduction.html
-# Output: <link href=".../foldbox/foldbox.css" rel="stylesheet">
-```
-
-#### Visual Verification
-✅ All callout icons present (definition, quiz-question, quiz-answer, example)  
-✅ Callout styling matches previous renders  
-✅ No visual regressions detected  
-✅ Pre-commit hooks passed (no whitespace, YAML, or formatting issues)
-
-### Metrics
-
-**Lines Removed**: ~190 lines of duplicate/redundant CSS
-- `dark-mode.scss`: 159 lines → 13 lines (comment)
-- `style.scss`: 52 references → 8 references
-
-**Files Modified**: 2
-- `quarto/assets/styles/dark-mode.scss`
-- `quarto/assets/styles/style.scss`
-
-**Files Unchanged**: 2
-- `quarto/_extensions/mlsysbook-ext/custom-numbered-blocks/style/foldbox.css` (already correct)
-- `quarto/assets/styles/epub.css` (fallback still needed)
-
-### Benefits Achieved
-
-1. ✅ **No Duplication**: Dark mode rules exist only in foldbox.css `@media` query
-2. ✅ **Consistency**: All callouts (including colab) styled identically via extension
-3. ✅ **Maintainability**: Single file (`foldbox.css`) to update for callout appearance changes
-4. ✅ **Self-Contained**: Extension handles its own light/dark modes independently
-5. ✅ **Clear Separation**: Host styles (`style.scss`) only exclude from Quarto defaults, don't define appearance
-6. ✅ **Tested**: HTML and EPUB builds verified working with correct rendering
-7. ✅ **Portable**: Extension can be reused in other Quarto projects without modifications
-
-### Potential Issues Resolved
-
-- ❌ **BEFORE**: `callout-colab` missing from `dark-mode.scss` (inconsistent dark mode support)
-- ✅ **AFTER**: All callouts get consistent dark mode via extension's `@media` query
-
-- ❌ **BEFORE**: Duplication between `foldbox.css` and `dark-mode.scss` (maintenance burden)
-- ✅ **AFTER**: Single source of truth in extension
-
-- ❌ **BEFORE**: 52 references in `style.scss` with scattered logic across multiple rules
-- ✅ **AFTER**: 8 references with clear, minimal purpose
-
-### Next Steps
-
-1. ✅ **Refactoring complete** - all tests passing
-2. ⏳ **Merge to dev** - once user approves
-3. ⏳ **Update documentation** - document Extension-First architecture in project docs
-4. ⏳ **Monitor production** - watch for any dark mode issues in deployed book
-
----
-
-## Conclusion
-
-The consolidation successfully eliminated ~190 lines of duplicate CSS while maintaining exact visual fidelity. The custom-numbered-blocks extension is now self-contained and handles all callout styling (light and dark modes) independently. Host stylesheets (`style.scss`, `dark-mode.scss`) now have clear, minimal roles: exclude custom callouts from Quarto's default styling, nothing more.
-
-**Status**: ✅ **Ready for Review and Merge**
-
-

README.md

@@ -229,12 +229,12 @@ Thanks goes to these wonderful people who have contributed to making this resour
       <td align="center" valign="top" width="20%"><a href="https://github.com/shanzehbatool"><img src="https://avatars.githubusercontent.com/shanzehbatool?s=100" width="100px;" alt="shanzehbatool"/><br /><sub><b>shanzehbatool</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/eliasab16"><img src="https://avatars.githubusercontent.com/eliasab16?s=100" width="100px;" alt="Elias"/><br /><sub><b>Elias</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/JaredP94"><img src="https://avatars.githubusercontent.com/JaredP94?s=100" width="100px;" alt="Jared Ping"/><br /><sub><b>Jared Ping</b></sub></a><br /></td>
+      <td align="center" valign="top" width="20%"><a href="https://github.com/didier-durand"><img src="https://avatars.githubusercontent.com/didier-durand?s=100" width="100px;" alt="Didier Durand"/><br /><sub><b>Didier Durand</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/ishapira1"><img src="https://avatars.githubusercontent.com/ishapira1?s=100" width="100px;" alt="Itai Shapira"/><br /><sub><b>Itai Shapira</b></sub></a><br /></td>
-      <td align="center" valign="top" width="20%"><a href="https://github.com/harvard-edge/cs249r_book/graphs/contributors"><img src="https://www.gravatar.com/avatar/8863743b4f26c1a20e730fcf7ebc3bc0?d=identicon&s=100?s=100" width="100px;" alt="Maximilian Lam"/><br /><sub><b>Maximilian Lam</b></sub></a><br /></td>
     </tr>
     <tr>
+      <td align="center" valign="top" width="20%"><a href="https://github.com/harvard-edge/cs249r_book/graphs/contributors"><img src="https://www.gravatar.com/avatar/8863743b4f26c1a20e730fcf7ebc3bc0?d=identicon&s=100?s=100" width="100px;" alt="Maximilian Lam"/><br /><sub><b>Maximilian Lam</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/jaysonzlin"><img src="https://avatars.githubusercontent.com/jaysonzlin?s=100" width="100px;" alt="Jayson Lin"/><br /><sub><b>Jayson Lin</b></sub></a><br /></td>
-      <td align="center" valign="top" width="20%"><a href="https://github.com/didier-durand"><img src="https://avatars.githubusercontent.com/didier-durand?s=100" width="100px;" alt="Didier Durand"/><br /><sub><b>Didier Durand</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/andreamurillomtz"><img src="https://avatars.githubusercontent.com/andreamurillomtz?s=100" width="100px;" alt="Andrea"/><br /><sub><b>Andrea</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/sophiacho1"><img src="https://avatars.githubusercontent.com/sophiacho1?s=100" width="100px;" alt="Sophia Cho"/><br /><sub><b>Sophia Cho</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/alxrod"><img src="https://avatars.githubusercontent.com/alxrod?s=100" width="100px;" alt="Alex Rodriguez"/><br /><sub><b>Alex Rodriguez</b></sub></a><br /></td>

cli/main.py

@@ -76,8 +76,8 @@ class MLSysBookCLI:
         fast_table.add_row("build [chapter[,ch2,...]]", "Build static files to disk (HTML)", "./binder build intro,ops")
         fast_table.add_row("html [chapter[,ch2,...]]", "Build HTML using quarto-html.yml", "./binder html intro")
         fast_table.add_row("preview [chapter[,ch2,...]]", "Start live dev server with hot reload", "./binder preview intro")
-        fast_table.add_row("pdf [chapter[,ch2,...]]", "Build PDF (only specified chapters)", "./binder pdf intro")
-        fast_table.add_row("epub [chapter[,ch2,...]]", "Build EPUB (only specified chapters)", "./binder epub intro")
+        fast_table.add_row("pdf [chapter[,ch2,...]]", "Build PDF (specified chapters)", "./binder pdf intro")
+        fast_table.add_row("epub [chapter[,ch2,...]]", "Build EPUB (specified chapters)", "./binder epub intro")
         
         # Full Book Commands
         full_table = Table(show_header=True, header_style="bold blue", box=None)
@@ -86,10 +86,10 @@ class MLSysBookCLI:
         full_table.add_column("Example", style="dim", width=30)
         
         full_table.add_row("build", "Build entire book as static HTML", "./binder build")
-        full_table.add_row("html", "Build ALL chapters using quarto-html.yml", "./binder html")
+        full_table.add_row("html --all", "Build ALL chapters using quarto-html.yml", "./binder html --all")
         full_table.add_row("preview", "Start live dev server for entire book", "./binder preview")
-        full_table.add_row("pdf", "Build full book (auto-uncomments all chapters)", "./binder pdf")
-        full_table.add_row("epub", "Build full book (auto-uncomments all chapters)", "./binder epub")
+        full_table.add_row("pdf --all", "Build full book (auto-uncomments all)", "./binder pdf --all")
+        full_table.add_row("epub --all", "Build full book (auto-uncomments all)", "./binder epub --all")
         
         # Management Commands
         mgmt_table = Table(show_header=True, header_style="bold blue", box=None)
@@ -119,11 +119,11 @@ class MLSysBookCLI:
         examples.append("# Build multiple chapters (HTML)\n", style="dim")
         examples.append("  ./binder html intro ", style="cyan")
         examples.append("# Build HTML with index.qmd + intro chapter only\n", style="dim")
-        examples.append("  ./binder html ", style="cyan")
+        examples.append("  ./binder html --all ", style="cyan")
         examples.append("# Build HTML with ALL chapters\n", style="dim")
         examples.append("  ./binder pdf intro ", style="cyan")
         examples.append("# Build single chapter as PDF\n", style="dim")
-        examples.append("  ./binder pdf ", style="cyan")
+        examples.append("  ./binder pdf --all ", style="cyan")
         examples.append("# Build entire book as PDF (uncomments all)\n", style="dim")
         
         console.print(Panel(examples, title="💡 Pro Tips", border_style="magenta"))
@@ -158,9 +158,14 @@ class MLSysBookCLI:
     def handle_html_command(self, args):
         """Handle HTML build command."""
         self.config_manager.show_symlink_status()
-        
+
         if len(args) < 1:
-            # No chapters specified - build all chapters using HTML config
+            # No target specified - show error
+            console.print("[red]❌ Error: Please specify chapters or use --all flag[/red]")
+            console.print("[yellow]💡 Usage: ./binder html <chapter> or ./binder html --all[/yellow]")
+            return False
+        elif args[0] == "--all":
+            # Build all chapters using HTML config
             console.print("[green]🌐 Building HTML with ALL chapters...[/green]")
             return self.build_command.build_html_only()
         else:
@@ -173,9 +178,14 @@ class MLSysBookCLI:
     def handle_pdf_command(self, args):
         """Handle PDF build command."""
         self.config_manager.show_symlink_status()
-        
+
         if len(args) < 1:
-            # No target specified - build entire book
+            # No target specified - show error
+            console.print("[red]❌ Error: Please specify chapters or use --all flag[/red]")
+            console.print("[yellow]💡 Usage: ./binder pdf <chapter> or ./binder pdf --all[/yellow]")
+            return False
+        elif args[0] == "--all":
+            # Build entire book
             console.print("[red]📄 Building entire book (PDF)...[/red]")
             return self.build_command.build_full("pdf")
         else:
@@ -188,9 +198,14 @@ class MLSysBookCLI:
     def handle_epub_command(self, args):
         """Handle EPUB build command."""
         self.config_manager.show_symlink_status()
-        
+
         if len(args) < 1:
-            # No target specified - build entire book
+            # No target specified - show error
+            console.print("[red]❌ Error: Please specify chapters or use --all flag[/red]")
+            console.print("[yellow]💡 Usage: ./binder epub <chapter> or ./binder epub --all[/yellow]")
+            return False
+        elif args[0] == "--all":
+            # Build entire book
             console.print("[purple]📚 Building entire book (EPUB)...[/purple]")
             return self.build_command.build_full("epub")
         else:

quarto/.gitignore

@@ -1,3 +0,0 @@
-/.quarto/
-
-**/*.quarto_ipynb

quarto/assets/styles/epub.css

@@ -8,21 +8,28 @@
  */
 
 /* ==========================================================================
-   Color Variables - Harvard Crimson Theme
+   Color Values - Harvard Crimson Theme
    ========================================================================== */
 
-:root {
-    --crimson: #A51C30;
-    --crimson-dark: #8B1729;
-    --crimson-light: #C5344A;
-    --text-primary: #1a202c;
-    --text-secondary: #4a5568;
-    --text-muted: #6c757d;
-    --background-light: #f8f9fa;
-    --background-code: #f1f3f4;
-    --border-light: #e9ecef;
-    --border-medium: #dee2e6;
-}
+/*
+ * NOTE: CSS custom properties (variables like --crimson, --text-primary, etc.)
+ * have been replaced with literal hex values throughout this stylesheet.
+ *
+ * REASON: Some EPUB readers (e.g., ClearView) have strict XML parsers that flag
+ * double-hyphens in CSS as XML comment violations, causing parsing errors.
+ *
+ * Color reference for maintenance:
+ * - Crimson: #A51C30
+ * - Crimson Dark: #8B1729
+ * - Crimson Light: #C5344A
+ * - Text Primary: #1a202c
+ * - Text Secondary: #4a5568
+ * - Text Muted: #6c757d
+ * - Background Light: #f8f9fa
+ * - Background Code: #f1f3f4
+ * - Border Light: #e9ecef
+ * - Border Medium: #dee2e6
+ */
 
 /* ==========================================================================
    Base & Typography
@@ -37,7 +44,7 @@ body {
     text-align: justify;
     widows: 3;
     orphans: 3;
-    color: var(--text-primary);
+    color: #1a202c;
 }
 
 p {
@@ -55,21 +62,21 @@ h1, h2, h3, h4, h5, h6 {
     text-align: left;
     page-break-after: avoid;
     page-break-inside: avoid;
-    color: var(--text-primary);
+    color: #1a202c;
 }
 
 h1 {
     font-size: 2.2em;
     margin-top: 0;
     page-break-before: always;
-    border-bottom: 2px solid var(--crimson);
+    border-bottom: 2px solid #A51C30;
     padding-bottom: 0.3em;
     font-weight: 700;
 }
 
 h2 {
     font-size: 1.8em;
-    border-left: 5px solid var(--crimson);
+    border-left: 5px solid #A51C30;
     border-bottom: 1px solid rgba(165, 28, 48, 0.3);
     padding-left: 16px;
     padding-bottom: 8px;
@@ -79,7 +86,7 @@ h2 {
 
 h3 {
     font-size: 1.5em;
-    border-left: 4px solid var(--crimson);
+    border-left: 4px solid #A51C30;
     border-bottom: 1px solid rgba(165, 28, 48, 0.25);
     padding-left: 14px;
     padding-bottom: 6px;
@@ -88,7 +95,7 @@ h3 {
 
 h4 {
     font-size: 1.2em;
-    border-left: 3px solid var(--crimson);
+    border-left: 3px solid #A51C30;
     border-bottom: 1px solid rgba(165, 28, 48, 0.2);
     padding-left: 12px;
     padding-bottom: 4px;
@@ -98,7 +105,7 @@ h4 {
 
 h5 {
     font-size: 1.1em;
-    border-left: 2px solid var(--crimson);
+    border-left: 2px solid #A51C30;
     border-bottom: 1px solid rgba(165, 28, 48, 0.15);
     padding-left: 10px;
     padding-bottom: 3px;
@@ -108,7 +115,7 @@ h5 {
 
 h6 {
     font-size: 1em;
-    border-left: 1px solid var(--crimson);
+    border-left: 1px solid #A51C30;
     border-bottom: 1px solid rgba(165, 28, 48, 0.1);
     padding-left: 8px;
     padding-bottom: 2px;
@@ -121,25 +128,25 @@ h6 {
    ========================================================================== */
 
 a {
-    color: var(--crimson);
+    color: #A51C30;
     text-decoration: none;
 }
 
 a:hover {
-    color: var(--crimson-dark);
+    color: #8B1729;
     text-decoration: underline;
 }
 
 a:visited {
-    color: var(--crimson-dark);
+    color: #8B1729;
 }
 
 blockquote {
     margin: 1.5em;
     padding: 0 1.5em;
-    border-left: 3px solid var(--crimson);
+    border-left: 3px solid #A51C30;
     font-style: italic;
-    color: var(--text-secondary);
+    color: #4a5568;
     background-color: rgba(165, 28, 48, 0.05);
     border-radius: 0 4px 4px 0;
 }
@@ -150,8 +157,8 @@ blockquote {
 
 /* Enhanced code blocks with syntax highlighting support */
 pre {
-    background-color: var(--background-code);
-    border: 1px solid var(--border-light);
+    background-color: #f1f3f4;
+    border: 1px solid #e9ecef;
     border-radius: 6px;
     padding: 0.75em;
     white-space: pre-wrap;
@@ -166,11 +173,11 @@ pre {
 
 code {
     font-family: "SF Mono", Monaco, "Cascadia Code", "Roboto Mono", Consolas, "Courier New", monospace;
-    background-color: var(--border-light);
+    background-color: #e9ecef;
     padding: 2px 6px;
     border-radius: 4px;
     font-size: 0.85em;
-    color: var(--text-primary);
+    color: #1a202c;
 }
 
 pre code {
@@ -198,7 +205,7 @@ pre code {
 /* Code listings with enhanced styling */
 .listing {
     margin: 1rem 0;
-    border: 2px solid var(--border-medium);
+    border: 2px solid #dee2e6;
     border-radius: 8px;
     overflow: hidden;
     background: linear-gradient(135deg, #f8f9fa 0%, #ffffff 100%);
@@ -207,11 +214,11 @@ pre code {
 .listing figcaption,
 .listing .listing-caption {
     background: linear-gradient(135deg, #f7f9fc 0%, #edf2f7 100%);
-    border-bottom: 2px solid var(--border-medium);
+    border-bottom: 2px solid #dee2e6;
     padding: 1rem 1.25rem;
     margin: 0;
     font-size: 0.9rem;
-    color: var(--text-primary);
+    color: #1a202c;
     font-weight: 600;
     line-height: 1.4;
     text-align: left;
@@ -219,7 +226,7 @@ pre code {
 
 .listing .sourceCode {
     padding: 0.5rem 1rem;
-    background-color: var(--background-code);
+    background-color: #f1f3f4;
     margin: 0;
     border: none;
 }
@@ -258,17 +265,17 @@ table {
 }
 
 th, td {
-    border: 1px solid var(--border-light);
+    border: 1px solid #e9ecef;
     padding: 12px 16px;
     text-align: left;
     vertical-align: top;
 }
 
 th {
-    background-color: var(--background-light);
+    background-color: #f8f9fa;
     font-weight: 600;
     text-align: left;
-    border-bottom: 2px solid var(--crimson);
+    border-bottom: 2px solid #A51C30;
     font-size: 0.85rem;
     text-transform: uppercase;
     letter-spacing: 0.3px;
@@ -278,7 +285,7 @@ th {
 /* Special treatment for technology comparison headers */
 th:not(:first-child) {
     background-color: rgba(165, 28, 48, 0.04);
-    border-bottom: 3px solid var(--crimson);
+    border-bottom: 3px solid #A51C30;
     font-weight: 600;
     color: #2c3e50;
 }
@@ -295,8 +302,8 @@ td:first-child,
 th:first-child {
     font-weight: 500;
     color: #2c3e50;
-    background-color: var(--background-light);
-    border-right: 1px solid var(--border-light);
+    background-color: #f8f9fa;
+    border-right: 1px solid #e9ecef;
 }
 
 /* Zebra striping for better readability */
@@ -317,7 +324,7 @@ table caption,
     font-weight: 500;
     margin-bottom: 0.75rem;
     margin-top: 1.5rem;
-    color: var(--text-secondary);
+    color: #4a5568;
     font-size: 0.9rem;
     line-height: 1.4;
 }
@@ -355,7 +362,7 @@ h1[epub|type="title"],
 #titlepage h1 {
     font-size: 2.5em;
     font-weight: 700;
-    color: var(--crimson);
+    color: #A51C30;
     margin-bottom: 0.5rem;
     line-height: 1.2;
     text-align: center;
@@ -369,7 +376,7 @@ h2[epub|type="subtitle"],
 #titlepage h2 {
     font-size: 1.4em;
     font-weight: 400;
-    color: var(--text-secondary);
+    color: #4a5568;
     margin-bottom: 2rem;
     font-style: italic;
     line-height: 1.3;
@@ -386,7 +393,7 @@ p[epub|type="author"],
 #titlepage p:contains("Prof.") {
     font-size: 1.2em;
     font-weight: 500;
-    color: var(--text-primary);
+    color: #1a202c;
     margin: 1.5rem 0;
     text-align: center;
 }
@@ -397,7 +404,7 @@ p[epub|type="author"],
 #titlepage .publisher,
 #titlepage .affiliation {
     font-size: 1em;
-    color: var(--text-secondary);
+    color: #4a5568;
     margin: 0.5rem 0;
     text-align: center;
 }
@@ -406,7 +413,7 @@ p[epub|type="author"],
 .title-page .date,
 #titlepage .date {
     font-size: 0.9em;
-    color: var(--text-muted);
+    color: #6c757d;
     margin-top: 2rem;
     text-align: center;
 }
@@ -417,7 +424,7 @@ p[epub|type="author"],
 #titlepage .rights,
 #titlepage .copyright {
     font-size: 0.8em;
-    color: var(--text-muted);
+    color: #6c757d;
     margin-top: auto;
     text-align: center;
     padding-top: 2rem;
@@ -435,7 +442,7 @@ details[class*="callout"] {
     border-radius: 0.5rem;
     border-left-width: 5px;
     border-left-style: solid;
-    border: 1px solid var(--border-light);
+    border: 1px solid #e9ecef;
     font-size: 0.9rem;
     box-shadow: 0 2px 8px rgba(165, 28, 48, 0.1);
     page-break-inside: avoid;
@@ -494,7 +501,7 @@ details[class*="callout"] > summary {
 }
 
 .callout-important {
-    border-left-color: var(--crimson);
+    border-left-color: #A51C30;
 }
 
 .callout-important .callout-header {
@@ -524,7 +531,7 @@ details.callout-definition {
     border-radius: 0.5rem;
     border-left-width: 5px;
     border-left-style: solid;
-    border: 1px solid var(--border-light);
+    border: 1px solid #e9ecef;
     border-left: 5px solid #1B4F72;
 }
 
@@ -553,7 +560,7 @@ details.callout-example {
     border-radius: 0.5rem;
     border-left-width: 5px;
     border-left-style: solid;
-    border: 1px solid var(--border-light);
+    border: 1px solid #e9ecef;
     border-left: 5px solid #148F77;
 }
 
@@ -610,7 +617,7 @@ details.callout-quiz-question {
     border-radius: 0.5rem;
     border-left-width: 5px;
     border-left-style: solid;
-    border: 1px solid var(--border-light);
+    border: 1px solid #e9ecef;
     border-left: 5px solid #5B4B8A;
 }
 
@@ -638,7 +645,7 @@ details.callout-quiz-answer {
     border-radius: 0.5rem;
     border-left-width: 5px;
     border-left-style: solid;
-    border: 1px solid var(--border-light);
+    border: 1px solid #e9ecef;
     border-left: 5px solid #4a7c59;
 }
 
@@ -662,15 +669,15 @@ div.callout-chapter-forward,
 .callout-chapter-forward,
 details.callout-chapter-connection,
 details.callout-chapter-forward {
-    border-left-color: var(--crimson);
+    border-left-color: #A51C30;
     background-color: rgba(165, 28, 48, 0.05);
     margin: 1.25rem 0;
     padding: 0.75rem 0.85rem;
     border-radius: 0.5rem;
     border-left-width: 5px;
     border-left-style: solid;
-    border: 1px solid var(--border-light);
-    border-left: 5px solid var(--crimson);
+    border: 1px solid #e9ecef;
+    border-left: 5px solid #A51C30;
 }
 
 div.callout-chapter-connection::before {
@@ -679,7 +686,7 @@ div.callout-chapter-connection::before {
     font-weight: 600;
     font-size: 0.9rem;
     margin-bottom: 0.5rem;
-    color: var(--crimson);
+    color: #A51C30;
 }
 
 div.callout-chapter-forward::before {
@@ -688,7 +695,7 @@ div.callout-chapter-forward::before {
     font-weight: 600;
     font-size: 0.9rem;
     margin-bottom: 0.5rem;
-    color: var(--crimson);
+    color: #A51C30;
 }
 
 .callout-chapter-connection .callout-header,
@@ -708,7 +715,7 @@ details.callout-chapter-recall {
     border-radius: 0.5rem;
     border-left-width: 5px;
     border-left-style: solid;
-    border: 1px solid var(--border-light);
+    border: 1px solid #e9ecef;
     border-left: 5px solid #C06014;
 }
 
@@ -742,7 +749,7 @@ details.callout-resource-exercises {
     border-radius: 0.5rem;
     border-left-width: 5px;
     border-left-style: solid;
-    border: 1px solid var(--border-light);
+    border: 1px solid #e9ecef;
     border-left: 5px solid #20B2AA;
 }
 
@@ -792,7 +799,7 @@ details.callout-code {
     border-radius: 0.5rem;
     border-left-width: 5px;
     border-left-style: solid;
-    border: 1px solid var(--border-light);
+    border: 1px solid #e9ecef;
     border-left: 5px solid #3C4858;
 }
 
@@ -843,7 +850,7 @@ figcaption {
     font-style: italic;
     text-align: left;
     margin-top: 1rem;
-    color: var(--text-muted);
+    color: #6c757d;
     line-height: 1.4;
 }
 
@@ -857,7 +864,7 @@ a[href^="#fn-"],
     font-size: 0.75em;
     vertical-align: super;
     text-decoration: none;
-    color: var(--crimson);
+    color: #A51C30;
     font-weight: 600;
     padding: 0 2px;
     border-radius: 2px;
@@ -876,10 +883,10 @@ div[id^="fn-"],
 .footnote {
     margin-top: 2rem;
     padding-top: 1rem;
-    border-top: 2px solid var(--border-light);
+    border-top: 2px solid #e9ecef;
     font-size: 0.85rem;
     line-height: 1.5;
-    color: var(--text-secondary);
+    color: #4a5568;
 }
 
 /* Individual footnote entries */
@@ -896,7 +903,7 @@ div[id^="fn-"],
 
 /* Footnote numbers */
 .footnotes li::marker {
-    color: var(--crimson);
+    color: #A51C30;
     font-weight: 600;
 }
 
@@ -904,7 +911,7 @@ div[id^="fn-"],
 a[href^="#fnref-"],
 .footnote-back {
     font-size: 0.8em;
-    color: var(--text-muted);
+    color: #6c757d;
     text-decoration: none;
     margin-left: 0.5rem;
     padding: 2px 4px;
@@ -914,7 +921,7 @@ a[href^="#fnref-"],
 
 a[href^="#fnref-"]:hover,
 .footnote-back:hover {
-    color: var(--crimson);
+    color: #A51C30;
     background-color: rgba(165, 28, 48, 0.05);
     text-decoration: none;
 }
@@ -925,7 +932,7 @@ a[href^="#fnref-"]:hover,
     display: block;
     width: 60px;
     height: 1px;
-    background-color: var(--crimson);
+    background-color: #A51C30;
     margin: 0 0 1rem 0;
 }
 

quarto/config/_quarto-epub.yml

@@ -19,6 +19,7 @@ project:
   output-dir: _build/epub
   post-render:
     - scripts/clean_svgs.py
+    - scripts/epub_postprocess.py
 
   preview:
     browser: false
@@ -218,7 +219,7 @@ bibliography:
   - contents/core/conclusion/conclusion.bib
 
 filters:
-  #- filters/sidenote.lua             # ⚠️ INFO: In HTML, this should not needed.
+  #- filters/sidenote.lua             # ⚠️ INFO: In HTML, this should not be needed.
   #- filters/inject_parts.lua
   #- filters/inject_quizzes.lua
   - pandoc-ext/diagram

quarto/config/_quarto-html.yml

@@ -365,7 +365,7 @@ crossref:
       reference-prefix: Video
 
 filters:
-  - filters/sidenote.lua             # ⚠️ INFO: In HTML, this should not needed.
+  - filters/sidenote.lua             # ⚠️ INFO: In HTML, this should not be needed.
   - filters/inject_parts.lua
   - filters/inject_quizzes.lua
   - pandoc-ext/diagram

quarto/contents/core/benchmarking/benchmarking.qmd

@@ -742,7 +742,7 @@ fit=(GRAPH2)(DIAGRAM1),yshift=0mm](BB2){};
 %above
 \coordinate(AB)at($(GRAPH1.north)+(-0.2,1.7)$);
 \node[Box9](B1)at(AB){Problem\\ definition};
-\node[Box9,right=of B1](B2){Datase \\ selection \\ (public domain)};
+\node[Box9,right=of B1](B2){Database \\ selection \\ (public domain)};
 \node[Box9,right=of B2](B3){Model \\ selection};
 \node[Box9,right=of B3](B4){Model \\ training code};
 \node[Box9,right=of B4](B5){Derive "Tiny" \\ version:\\ Quantization};

quarto/contents/core/data_engineering/data_engineering.qmd

@@ -1156,7 +1156,7 @@ tableicon/.pic={
   scalefac=1,
   picname=C
 }
-% #1 number of teeths
+% #1 number of teeth
 % #2 radius intern
 % #3 radius extern
 % #4 angle from start to end of the first arc

quarto/contents/core/frameworks/frameworks.qmd

@@ -2708,7 +2708,7 @@ Managing end-to-end ML pipelines requires orchestrating multiple stages, from da
 
 Continuous Integration and Continuous Deployment (CI/CD) practices are being adapted for ML workflows. This involves automating model testing, validation, and deployment processes. Tools like Jenkins or GitLab CI can be extended with ML-specific stages to create robust CI/CD pipelines for machine learning projects.
 
-Automated model retraining and updating is another critical aspect of ML workflow orchestration. This involves setting up systems to automatically retrain models on new data, evaluate their performance, and seamlessly update production models when certain criteria are met. Frameworks like Kubeflow provide end-to-end ML pipelines that can automate many of these processes. @fig-workflow-orchestration shows an example orchestration flow, where a user submitts DAGs, or directed acyclic graphs of workloads to process and train to be executed.
+Automated model retraining and updating is another critical aspect of ML workflow orchestration. This involves setting up systems to automatically retrain models on new data, evaluate their performance, and seamlessly update production models when certain criteria are met. Frameworks like Kubeflow provide end-to-end ML pipelines that can automate many of these processes. @fig-workflow-orchestration shows an example orchestration flow, where a user submits DAGs, or directed acyclic graphs of workloads to process and train to be executed.
 
 Version control for ML assets, including data, model architectures, and hyperparameters, is essential for reproducibility and collaboration. Tools like DVC (Data Version Control) and MLflow have emerged to address these ML-specific version control needs.
 

quarto/contents/core/frontiers/footnote_catalog.json

@@ -1,21 +0,0 @@
-{
-  "total_files": 0,
-  "total_references": 0,
-  "total_definitions": 0,
-  "patterns": {
-    "total_definitions": 0,
-    "with_bold_terms": 0,
-    "average_length": 0,
-    "common_prefixes": {},
-    "terms_used": []
-  },
-  "duplicates": {
-    "duplicate_ids": {},
-    "duplicate_terms": {},
-    "undefined_references": [],
-    "unused_definitions": []
-  },
-  "by_chapter": [],
-  "all_references": [],
-  "all_definitions": []
-}

quarto/contents/core/frontiers/frontiers.qmd

@@ -737,7 +737,7 @@ ALine/.style={black!50, line width=1.1pt,{{Triangle[width=0.9*6pt,length=1.2*6pt
 Larrow/.style={fill=violet!50, single arrow,  inner sep=2pt, single arrow head extend=3pt,
             single arrow head indent=0pt,minimum height=10mm, minimum width=3pt}
 }
-% #1 number of teeths
+% #1 number of teeth
 % #2 radius intern
 % #3 radius extern
 % #4 angle from start to end of the first arc
@@ -915,9 +915,9 @@ pics/stit/.style = {
  tiecolor/.store in=\tiecolor,
   bodycolor/.store in=\bodycolor,
   stetcolor/.store in=\stetcolor,
-  tiecolor=red,      % derfault tie color
-  bodycolor=blue!30,  % derfault body color
-  stetcolor=green,  % derfault stet color
+  tiecolor=red,      % default tie color
+  bodycolor=blue!30,  % default body color
+  stetcolor=green,  % default stet color
   filllcolor=BrownLine,
   filllcirclecolor=violet!20,
   drawcolor=black,

quarto/contents/core/hw_acceleration/hw_acceleration.qmd

@@ -187,7 +187,7 @@ Historically, improvements in processor performance depended on semiconductor pr
 
 Domain-specific architectures achieve superior performance and energy efficiency through several key principles:
 
-1. **Customized datapaths**: Design processing paths specifically optimized for target application patterns, enabling direct hardware execution of common operations. For example, matrix multiplication units in AI accelerators implement systolic arrays—grid-like networks of processing elements that rhythmically compute and pass data through neighboring units—tailored for neural network computations.
+1. **Customized data paths**: Design processing paths specifically optimized for target application patterns, enabling direct hardware execution of common operations. For example, matrix multiplication units in AI accelerators implement systolic arrays—grid-like networks of processing elements that rhythmically compute and pass data through neighboring units—tailored for neural network computations.
 
 2. **Specialized memory hierarchies**: Optimize memory systems around domain-specific access patterns and data reuse characteristics. This includes custom cache configurations, prefetching logic, and memory controllers tuned for expected workloads.
 
@@ -249,29 +249,29 @@ The evolution of specialized hardware architectures illustrates a principle in c
 
 @tbl-hw-evolution summarizes key milestones in the evolution of hardware specialization, showing how each era produced architectures tailored to the prevailing computational demands. While these accelerators initially emerged to optimize domain-specific workloads, including floating-point operations, graphics rendering, and media processing, they also introduced architectural strategies that persist in contemporary systems. The specialization principles outlined in earlier generations now underpin the design of modern AI accelerators. Understanding this historical trajectory provides context for analyzing how hardware specialization continues to enable scalable, efficient execution of machine learning workloads across diverse deployment environments.
 
-+-----------+------------------------------------+---------------------------------------------+-----------------------------------------+
-| **Era**   | **Computational Pattern**          | **Architecture Examples**                   | **Characteristics**                     |
-+==========:+:===================================+:============================================+:========================================+
-| **1980s** | Floating-Point & Signal Processing | FPU, DSP                                    | <li>Single-purpose engines</li>         |
-|           |                                    |                                             | <li>Focused instruction sets</li>       |
-|           |                                    |                                             | <li>Coprocessor interfaces</li>         |
-+-----------+------------------------------------+---------------------------------------------+-----------------------------------------+
-| **1990s** | 3D Graphics & Multimedia           | GPU, SIMD Units                             | <li>Many identical compute units</li>   |
-|           |                                    |                                             | <li>Regular data patterns</li>          |
-|           |                                    |                                             | <li>Wide memory interfaces</li>         |
-+-----------+------------------------------------+---------------------------------------------+-----------------------------------------+
-| **2000s** | Real-time Media Coding             | Media Codecs, Network Processors            | <li>Fixed-function pipelines</li>       |
-|           |                                    |                                             | <li>High throughput processing</li>     |
-|           |                                    |                                             | <li>Power-performance optimization</li> |
-+-----------+------------------------------------+---------------------------------------------+-----------------------------------------+
-| **2010s** | Deep Learning Tensor Operations    | TPU, GPU Tensor Cores                       | <li>Matrix multiplication units</li>    |
-|           |                                    |                                             | <li>Massive parallelism</li>            |
-|           |                                    |                                             | <li>Memory bandwidth optimization</li>  |
-+-----------+------------------------------------+---------------------------------------------+-----------------------------------------+
-| **2020s** | Application-Specific Acceleration  | ML Engines, Smart NICs, Domain Accelerators | <li>Workload-specific datapaths</li>    |
-|           |                                    |                                             | <li>Customized memory hierarchies</li>  |
-|           |                                    |                                             | <li>Application-optimized designs</li>  |
-+-----------+------------------------------------+---------------------------------------------+-----------------------------------------+
++-----------+------------------------------------+---------------------------------------------+----------------------------------------------+
+| **Era**   | **Computational Pattern**          | **Architecture Examples**                   | **Characteristics**                          |
++==========:+:===================================+:============================================+:=============================================+
+| **1980s** | Floating-Point & Signal Processing | FPU, DSP                                    | <ul><li>Single-purpose engines</li>          |
+|           |                                    |                                             | <li>Focused instruction sets</li>            |
+|           |                                    |                                             | <li>Coprocessor interfaces</li></ul>         |
++-----------+------------------------------------+---------------------------------------------+----------------------------------------------+
+| **1990s** | 3D Graphics & Multimedia           | GPU, SIMD Units                             | <ul><li>Many identical compute units</li>    |
+|           |                                    |                                             | <li>Regular data patterns</li>               |
+|           |                                    |                                             | <li>Wide memory interfaces</li></ul>         |
++-----------+------------------------------------+---------------------------------------------+----------------------------------------------+
+| **2000s** | Real-time Media Coding             | Media Codecs, Network Processors            | <ul><li>Fixed-function pipelines</li>        |
+|           |                                    |                                             | <li>High throughput processing</li>          |
+|           |                                    |                                             | <li>Power-performance optimization</li></ul> |
++-----------+------------------------------------+---------------------------------------------+----------------------------------------------+
+| **2010s** | Deep Learning Tensor Operations    | TPU, GPU Tensor Cores                       | <ul><li>Matrix multiplication units</li>     |
+|           |                                    |                                             | <li>Massive parallelism</li>                 |
+|           |                                    |                                             | <li>Memory bandwidth optimization</li></ul>  |
++-----------+------------------------------------+---------------------------------------------+----------------------------------------------+
+| **2020s** | Application-Specific Acceleration  | ML Engines, Smart NICs, Domain Accelerators | <ul><li>Workload-specific datapaths</li>     |
+|           |                                    |                                             | <li>Customized memory hierarchies</li>       |
+|           |                                    |                                             | <li>Application-optimized designs</li></ul>  |
++-----------+------------------------------------+---------------------------------------------+----------------------------------------------+
 
 : **Hardware Specialization Trends**: Successive computing eras progressively integrate specialized hardware to accelerate prevalent workloads, moving from general-purpose CPUs to domain-specific architectures and ultimately to customizable AI accelerators. This evolution reflects a fundamental principle: tailoring hardware to computational patterns improves performance and energy efficiency, driving innovation in machine learning systems. {#tbl-hw-evolution}
 

quarto/contents/core/introduction/footnote_catalog.json

@@ -1,21 +0,0 @@
-{
-  "total_files": 0,
-  "total_references": 0,
-  "total_definitions": 0,
-  "patterns": {
-    "total_definitions": 0,
-    "with_bold_terms": 0,
-    "average_length": 0,
-    "common_prefixes": {},
-    "terms_used": []
-  },
-  "duplicates": {
-    "duplicate_ids": {},
-    "duplicate_terms": {},
-    "undefined_references": [],
-    "unused_definitions": []
-  },
-  "by_chapter": [],
-  "all_references": [],
-  "all_definitions": []
-}

quarto/contents/core/ml_systems/footnote_catalog.json

@@ -1,21 +0,0 @@
-{
-  "total_files": 0,
-  "total_references": 0,
-  "total_definitions": 0,
-  "patterns": {
-    "total_definitions": 0,
-    "with_bold_terms": 0,
-    "average_length": 0,
-    "common_prefixes": {},
-    "terms_used": []
-  },
-  "duplicates": {
-    "duplicate_ids": {},
-    "duplicate_terms": {},
-    "undefined_references": [],
-    "unused_definitions": []
-  },
-  "by_chapter": [],
-  "all_references": [],
-  "all_definitions": []
-}

quarto/contents/core/optimizations/optimizations.qmd

@@ -1052,7 +1052,7 @@ Starting Accuracy:\\ \textbf{#4}};
 }
 
 %%%%%%
-% #1 number of teeths
+% #1 number of teeth
 % #2 radius intern
 % #3 radius extern
 % #4 angle from start to end of the first arc

quarto/contents/core/privacy_security/footnote_catalog.json

@@ -1,21 +0,0 @@
-{
-  "total_files": 0,
-  "total_references": 0,
-  "total_definitions": 0,
-  "patterns": {
-    "total_definitions": 0,
-    "with_bold_terms": 0,
-    "average_length": 0,
-    "common_prefixes": {},
-    "terms_used": []
-  },
-  "duplicates": {
-    "duplicate_ids": {},
-    "duplicate_terms": {},
-    "undefined_references": [],
-    "unused_definitions": []
-  },
-  "by_chapter": [],
-  "all_references": [],
-  "all_definitions": []
-}

quarto/contents/frontmatter/acknowledgements/acknowledgements.qmd

@@ -147,12 +147,12 @@ A comprehensive list of all GitHub contributors is available below, reflecting t
       <td align="center" valign="top" width="20%"><a href="https://github.com/shanzehbatool"><img src="https://avatars.githubusercontent.com/shanzehbatool?s=100" width="100px;" alt="shanzehbatool"/><br /><sub><b>shanzehbatool</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/eliasab16"><img src="https://avatars.githubusercontent.com/eliasab16?s=100" width="100px;" alt="Elias"/><br /><sub><b>Elias</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/JaredP94"><img src="https://avatars.githubusercontent.com/JaredP94?s=100" width="100px;" alt="Jared Ping"/><br /><sub><b>Jared Ping</b></sub></a><br /></td>
+      <td align="center" valign="top" width="20%"><a href="https://github.com/didier-durand"><img src="https://avatars.githubusercontent.com/didier-durand?s=100" width="100px;" alt="Didier Durand"/><br /><sub><b>Didier Durand</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/ishapira1"><img src="https://avatars.githubusercontent.com/ishapira1?s=100" width="100px;" alt="Itai Shapira"/><br /><sub><b>Itai Shapira</b></sub></a><br /></td>
-      <td align="center" valign="top" width="20%"><a href="https://github.com/harvard-edge/cs249r_book/graphs/contributors"><img src="https://www.gravatar.com/avatar/8863743b4f26c1a20e730fcf7ebc3bc0?d=identicon&s=100?s=100" width="100px;" alt="Maximilian Lam"/><br /><sub><b>Maximilian Lam</b></sub></a><br /></td>
     </tr>
     <tr>
+      <td align="center" valign="top" width="20%"><a href="https://github.com/harvard-edge/cs249r_book/graphs/contributors"><img src="https://www.gravatar.com/avatar/8863743b4f26c1a20e730fcf7ebc3bc0?d=identicon&s=100?s=100" width="100px;" alt="Maximilian Lam"/><br /><sub><b>Maximilian Lam</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/jaysonzlin"><img src="https://avatars.githubusercontent.com/jaysonzlin?s=100" width="100px;" alt="Jayson Lin"/><br /><sub><b>Jayson Lin</b></sub></a><br /></td>
-      <td align="center" valign="top" width="20%"><a href="https://github.com/didier-durand"><img src="https://avatars.githubusercontent.com/didier-durand?s=100" width="100px;" alt="Didier Durand"/><br /><sub><b>Didier Durand</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/andreamurillomtz"><img src="https://avatars.githubusercontent.com/andreamurillomtz?s=100" width="100px;" alt="Andrea"/><br /><sub><b>Andrea</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/sophiacho1"><img src="https://avatars.githubusercontent.com/sophiacho1?s=100" width="100px;" alt="Sophia Cho"/><br /><sub><b>Sophia Cho</b></sub></a><br /></td>
       <td align="center" valign="top" width="20%"><a href="https://github.com/alxrod"><img src="https://avatars.githubusercontent.com/alxrod?s=100" width="100px;" alt="Alex Rodriguez"/><br /><sub><b>Alex Rodriguez</b></sub></a><br /></td>

quarto/contents/labs/arduino/nicla_vision/kws/kws.qmd

@@ -390,7 +390,7 @@ Upload the sketch to your board and test some real inferences. The idea is that
 
 ## Summary {#sec-keyword-spotting-kws-summary-06f5}
 
-> You will find the notebooks and codeused in this hands-on tutorial on the [GitHub](https://github.com/Mjrovai/Arduino_Nicla_Vision/tree/main/KWS) repository.
+> You will find the notebooks and code used in this hands-on tutorial on the [GitHub](https://github.com/Mjrovai/Arduino_Nicla_Vision/tree/main/KWS) repository.
 
 Before we finish, consider that Sound Classification is more than just voice. For example, you can develop TinyML projects around sound in several areas, such as:
 

quarto/contents/labs/arduino/nicla_vision/motion_classification/motion_classification.qmd

@@ -198,7 +198,7 @@ As discussed before, we should capture data from all four Transportation Classes
 \noindent
 ![](images/jpg/lift_result.jpg)
 
-**Idle** (Paletts in a warehouse). No movement detected by the accelerometer:
+**Idle** (Palettes in a warehouse). No movement detected by the accelerometer:
 
 \noindent
 ![](images/jpg/idle_result.jpg)

quarto/contents/labs/arduino/nicla_vision/nicla_vision.qmd

@@ -12,13 +12,13 @@ These labs provide a unique opportunity to gain practical experience with machin
 
 ## Setup {#sec-overview-setup-cde0}
 
-- [Setup Nicla Vision](./setup/setup.qmd)
+- [Setup Nicla Vision](@sec-setup-overview-dcdd)
 
 ## Exercises {#sec-overview-exercises-f4f3}
 
 | **Modality** | **Task** | **Description** | **Link** |
 |:--------------|:--------------|:-----------------|:----------|
-| Vision       | Image Classification | Learn to classify images | [Link](./image_classification/image_classification.qmd) |
-| Vision       | Object Detection     | Implement object detection | [Link](./object_detection/object_detection.qmd) |
-| Sound        | Keyword Spotting                   | Explore voice recognition systems         | [Link](./kws/kws.qmd)                  |
-| IMU          | Motion Classification and Anomaly Detection | Classify motion data and detect anomalies | [Link](./motion_classification/motion_classification.qmd) |
+| Vision       | Image Classification | Learn to classify images | [Link](@sec-image-classification-overview-7420) |
+| Vision       | Object Detection     | Implement object detection | [Link](@sec-object-detection-overview-9d59) |
+| Sound        | Keyword Spotting                   | Explore voice recognition systems         | [Link](@sec-keyword-spotting-kws-overview-0ae6)                  |
+| IMU          | Motion Classification and Anomaly Detection | Classify motion data and detect anomalies | [Link](@sec-motion-classification-anomaly-detection-overview-b1a8) |

quarto/contents/labs/arduino/nicla_vision/object_detection/object_detection.qmd

@@ -259,7 +259,7 @@ Select `OpenMV Firmware` on the Deploy Tab and press `[Build]`.
 \noindent
 ![](./images/png/12-deploy.png){width="90%" fig-align="center"}
 
-When you try to connect the Nicla with the OpenMV IDE again, it will try to update its FW. Choose the option `Load a specific firmware` instead. Or go to `Tools  > Runs Boatloader (Load Firmware).
+When you try to connect the Nicla with the OpenMV IDE again, it will try to update its FW. Choose the option `Load a specific firmware` instead. Or go to `Tools  > Runs Bootloader (Load Firmware).
 
 \noindent
 ![](images/png/img_24.png){width="65%" fig-align="center"}

quarto/contents/labs/labs.qmd

@@ -120,7 +120,7 @@ After completing hardware selection and development environment setup, you're re
 
 For detailed platform-specific setup instructions, refer to the individual setup guides:
 
-- [XIAOML Kit Setup](seeed/xiao_esp32s3/setup/setup.qmd)
-- [Arduino Nicla Vision Setup](arduino/nicla_vision/setup/setup.qmd)
-- [Grove Vision AI V2 Setup](seeed/grove_vision_ai_v2/grove_vision_ai_v2.qmd)
-- [Raspberry Pi Setup](raspi/setup/setup.qmd)
+- [XIAOML Kit Setup](@sec-setup-overview-d638)
+- [Arduino Nicla Vision Setup](@sec-setup-overview-dcdd)
+- [Grove Vision AI V2 Setup](@sec-setup-nocode-applications-introduction-b740)
+- [Raspberry Pi Setup](@sec-setup-overview-0ec9)

quarto/contents/labs/raspi/object_detection/object_detection.qmd

@@ -30,7 +30,7 @@ We will explore those object detection models using
 
 - TensorFlow Lite Runtime (now changed to [LiteRT](https://ai.google.dev/edge/litert)),
 - Edge Impulse Linux Python SDK and
-- Ultralitics
+- Ultralytics
 
 \noindent
 ![](images/png/block.png){width=80% fig-align="center"}
@@ -353,7 +353,7 @@ python3 get_img_data.py
 Access the web interface:
 
 - On the Raspberry Pi itself (if you have a GUI): Open a web browser and go to `http://localhost:5000`
-- From another device on the same network: Open a web browser and go to `http://<raspberry_pi_ip>:5000` (R`eplace `<raspberry_pi_ip>` with your Raspberry Pi's IP address).
+- From another device on the same network: Open a web browser and go to `http://<raspberry_pi_ip>:5000` (Replace `<raspberry_pi_ip>` with your Raspberry Pi's IP address).
 For example: `http://192.168.4.210:5000/`
 
 \noindent
@@ -419,7 +419,7 @@ At the end of the process, we will have 153 images.
 \noindent
 ![](images/png/final-dataset.png){width=85% fig-align="center"}
 
-Now, you should export the annotated dataset in a format that Edge Impulse, Ultralitics, and other frameworks/tools understand, for example, `YOLOv8`. Let's download a zipped version of the dataset to our desktop.
+Now, you should export the annotated dataset in a format that Edge Impulse, Ultralytics, and other frameworks/tools understand, for example, `YOLOv8`. Let's download a zipped version of the dataset to our desktop.
 
 \noindent
 ![](images/png/download-dataset.png){width=90% fig-align="center"}
@@ -1178,7 +1178,7 @@ The YOLO (You Only Look Once) model is a highly efficient and widely used object
 6. **Community and Development**:
 
     - YOLO continues to evolve and is supported by a strong community of developers and researchers (being the YOLOv8 very strong). Open-source implementations and extensive documentation have made it accessible for customization and integration into various projects. Popular deep learning frameworks like Darknet, TensorFlow, and PyTorch support YOLO, further broadening its applicability.
-    - [Ultralitics YOLOv8](https://github.com/ultralytics/ultralytics?tab=readme-ov-file) can not only [Detect](https://docs.ultralytics.com/tasks/detect) (our case here) but also [Segment](https://docs.ultralytics.com/tasks/segment) and [Pose](https://docs.ultralytics.com/tasks/pose) models pre-trained on the [COCO](https://docs.ultralytics.com/datasets/detect/coco) dataset and YOLOv8 [Classify](https://docs.ultralytics.com/tasks/classify) models pre-trained on the [ImageNet](https://docs.ultralytics.com/datasets/classify/imagenet) dataset. [Track](https://docs.ultralytics.com/modes/track) mode is available for all Detect, Segment, and Pose models.
+    - [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics?tab=readme-ov-file) can not only [Detect](https://docs.ultralytics.com/tasks/detect) (our case here) but also [Segment](https://docs.ultralytics.com/tasks/segment) and [Pose](https://docs.ultralytics.com/tasks/pose) models pre-trained on the [COCO](https://docs.ultralytics.com/datasets/detect/coco) dataset and YOLOv8 [Classify](https://docs.ultralytics.com/tasks/classify) models pre-trained on the [ImageNet](https://docs.ultralytics.com/datasets/classify/imagenet) dataset. [Track](https://docs.ultralytics.com/modes/track) mode is available for all Detect, Segment, and Pose models.
 
     ![Ultralytics YOLO supported tasks](images/png/auto-1af10b28_1af10b28.png)
 
@@ -1378,7 +1378,7 @@ Return to our "Box versus Wheel" dataset, labeled on [Roboflow](https://universe
 \noindent
 ![](images/png/dataset_code.png)
 
-For training, let's adapt one of the public examples available from Ultralitytics and run it on Google Colab. Below, you can find mine to be adapted in your project:
+For training, let's adapt one of the public examples available from Ultralytics and run it on Google Colab. Below, you can find mine to be adapted in your project:
 
 - YOLOv8 Box versus Wheel Dataset Training [[Open In Colab]](https://colab.research.google.com/github/Mjrovai/EdgeML-with-Raspberry-Pi/blob/main/OBJ_DETEC/notebooks/yolov8_box_vs_wheel.ipynb)
 

quarto/contents/labs/raspi/raspi.qmd

@@ -16,18 +16,18 @@ These labs offer invaluable hands-on experience with machine learning systems, l
 
 ## Setup {#sec-overview-setup-02c7}
 
-- [Setup Raspberry Pi](./setup/setup.qmd)
+- [Setup Raspberry Pi](@sec-setup-overview-0ec9)
 
 ## Exercises {#sec-overview-exercises-6edf}
 
-+--------------+------------------------+----------------------------+---------------------------------------------------------+
-| **Modality** | **Task**               | **Description**            | **Link**                                                |
-+:=============+:=======================+:===========================+:========================================================+
-| **Vision**   | Image Classification   | Learn to classify images   | [Link](./image_classification/image_classification.qmd) |
-+--------------+------------------------+----------------------------+---------------------------------------------------------+
-| **Vision**   | Object Detection       | Implement object detection | [Link](./object_detection/object_detection.qmd)         |
-+--------------+------------------------+----------------------------+---------------------------------------------------------+
-| **GenAI**    | Small Language Models  | Deploy SLMs at the Edge    | [Link](./llm/llm.qmd)                                   |
-+--------------+------------------------+----------------------------+---------------------------------------------------------+
-| **GenAI**    | Visual-Language Models | Deploy VLMs at the Edge    | [Link](./vlm/vlm.qmd)                                   |
-+--------------+------------------------+----------------------------+---------------------------------------------------------+
++--------------+------------------------+----------------------------+----------------------------------------------------------+
+| **Modality** | **Task**               | **Description**            | **Link**                                                 |
++:=============+:=======================+:===========================+=========================================================:+
+| **Vision**   | Image Classification   | Learn to classify images   | [Link](@sec-image-classification-overview-3e02)          |
++--------------+------------------------+----------------------------+----------------------------------------------------------+
+| **Vision**   | Object Detection       | Implement object detection | [Link](@sec-object-detection-overview-1133)              |
++--------------+------------------------+----------------------------+----------------------------------------------------------+
+| **GenAI**    | Small Language Models  | Deploy SLMs at the Edge    | [Link](@sec-small-language-models-slm-overview-ef83)     |
++--------------+------------------------+----------------------------+----------------------------------------------------------+
+| **GenAI**    | Visual-Language Models | Deploy VLMs at the Edge    | [Link](@sec-visionlanguage-models-vlm-introduction-4272) |
++--------------+------------------------+----------------------------+----------------------------------------------------------+

quarto/contents/labs/raspi/setup/setup.qmd

@@ -132,7 +132,7 @@ Follow the steps to install the OS in your Raspi.
 \noindent
    ![img](images/png/zero-burn.png){width=70% fig-align="center"}
 
-   > Due to its reduced SDRAM (512 MB), the recommended OS for the Raspi-Zero is the 32-bit version. However, to run some machine learning models, such as the YOLOv8 from Ultralitics, we should use the 64-bit version. Although Raspi-Zero can run a *desktop*, we will choose the LITE version (no Desktop) to reduce the RAM needed for regular operation.
+   > Due to its reduced SDRAM (512 MB), the recommended OS for the Raspi-Zero is the 32-bit version. However, to run some machine learning models, such as the YOLOv8 from Ultralytics, we should use the 64-bit version. Although Raspi-Zero can run a *desktop*, we will choose the LITE version (no Desktop) to reduce the RAM needed for regular operation.
 
    - For **Raspi-5**: We can select the full 64-bit version, which includes a desktop:
      `Raspberry Pi OS (64-bit)`

quarto/contents/labs/raspi/vlm/vlm.qmd

@@ -161,7 +161,7 @@ Our choice of edge device is the Raspberry Pi 5 (Raspi-5). Its robust platform i
 
 > For real applications, SSDs are a better option than SD cards.
 
-We suggest installing an Active Cooler, a dedicated clip-on cooling solution for Raspberry Pi 5 (Raspi-5), for this lab. It combines an aluminum heatsink with a temperature-controlled blower fan to keep the Raspi-5 operating comfortably under heavy loads, such as running Florense-2.
+We suggest installing an Active Cooler, a dedicated clip-on cooling solution for Raspberry Pi 5 (Raspi-5), for this lab. It combines an aluminum heat sink with a temperature-controlled blower fan to keep the Raspi-5 operating comfortably under heavy loads, such as running Florense-2.
 
 \noindent
 ![](images/jpeg/raspi5-active-cooler.jpg){width=80% fig-align="center"}
@@ -1200,7 +1200,7 @@ text. On the left side of the poster, there is a logo of a \
 coffee cup with the text "Café Com Embarcados" above it. \
 Below the logo, it says "25 de Setembro as 17th" which \
 translates to "25th of September as 17" in English. \n\nOn \
-the right side, there aretwo smaller text boxes with the names \
+the right side, there are two smaller text boxes with the names \
 of the participants and their names. The first text box reads \
 "Democratizando a Inteligência Artificial para Paises em \
 Desenvolvimento" and the second text box says "Toda \

quarto/contents/labs/seeed/grove_vision_ai_v2/grove_vision_ai_v2.qmd

@@ -21,14 +21,14 @@ This positioning makes it an ideal platform for learning advanced TinyML concept
 
 ## Setup and No-Code Applications {#sec-overview-setup-nocode-applications-e70f}
 
-- [Setup and No-Code Apps](./setup_and_no_code_apps/setup_and_no_code_apps.qmd)
+- [Setup and No-Code Apps](@sec-setup-nocode-applications-introduction-b740)
 
 ## Exercises {#sec-overview-exercises-e8a6}
 
-+--------------+----------------------+----------------------------+---------------------------------------------------------+
-| **Modality** | **Task**             | **Description**            | **Link**                                                |
-+:=============+:=====================+:===========================+:========================================================+
-| **Vision**   | Image Classification | Learn to classify images   | [Link](./image_classification/image_classification.qmd) |
-+--------------+----------------------+----------------------------+---------------------------------------------------------+
-| **Vision**   | Object Detection     | Implement object detection | [Link](./object_detection/object_detection.qmd)         |
-+--------------+----------------------+----------------------------+---------------------------------------------------------+
++--------------+----------------------+----------------------------+-----------------------------------------------------+
+| **Modality** | **Task**             | **Description**            | **Link**                                            |
++:=============+:=====================+:===========================+:====================================================+
+| **Vision**   | Image Classification | Learn to classify images   | [Link](@sec-image-classification-introduction-59d5) |
++--------------+----------------------+----------------------------+-----------------------------------------------------+
+| **Vision**   | Object Detection     | Implement object detection | TBD                                                 |
++--------------+----------------------+----------------------------+-----------------------------------------------------+

quarto/contents/labs/seeed/grove_vision_ai_v2/image_classification/image_classification.qmd

@@ -348,7 +348,7 @@ If the Periquito is detected (Label:1), the LED is ON:
 
 ![](./images/png/led-off.png){width=80% fig-align="center"}
 
-Therefore, we can now power the Grove Viaon AI V2 + Xiao ESP32S3 with an external battery, and the inference result will be displayed by the LED completely offline. The consumption is approximately 165 mA or 825 mW.
+Therefore, we can now power the Grove Vision AI V2 + Xiao ESP32S3 with an external battery, and the inference result will be displayed by the LED completely offline. The consumption is approximately 165 mA or 825 mW.
 
 > It is also possible to send the result using Wifi, BLE, or other communication protocols available on the used Master Device.
 

quarto/contents/labs/seeed/xiao_esp32s3/kws/kws.qmd

@@ -49,7 +49,9 @@ In other words, recognizing voice commands is based on a multi-stage model or Ca
 
 The video below shows an example where I emulate a Google Assistant on a Raspberry Pi (Stage 2), having an Arduino Nano 33 BLE as the tinyML device (Stage 1).
 
-<iframe class="react-editor-embed react-editor-embed-override" src="https://www.youtube.com/embed/e_OPgcnsyvM" frameborder="0" style="box-sizing: border-box; align-self: center; flex: 1 1 0%; height: 363.068px; max-height: 100%; max-width: 100%; overflow: hidden; width: 645.455px; z-index: 1;"></iframe>
+::: {.content-visible when-format="html:js"}
+<iframe class="react-editor-embed react-editor-embed-override" src="https://www.youtube.com/embed/e_OPgcnsyvM" style="box-sizing: border-box; align-self: center; flex: 1 1 0%; height: 363.068px; max-height: 100%; max-width: 100%; overflow: hidden; width: 645.455px; z-index: 1; border: none;"></iframe>
+:::
 
 > If you want to go deeper on the full project, please see my tutorial: [Building an Intelligent Voice Assistant From Scratch](https://www.hackster.io/mjrobot/building-an-intelligent-voice-assistant-from-scratch-2199c3).
 
@@ -689,7 +691,9 @@ You can find the complete code on the [project's GitHub.](https://github.com/Mjr
 
 The idea is that the LED will be ON whenever the keyword YES is detected. In the same way, instead of turning on an LED, this could be a "trigger" for an external device, as we saw in the introduction.
 
-<iframe class="react-editor-embed react-editor-embed-override" src="https://www.youtube.com/embed/wjhtEzXt60Q" frameborder="0" style="box-sizing: border-box; align-self: center; flex: 1 1 0%; height: 363.068px; max-height: 100%; max-width: 100%; overflow: hidden; width: 645.455px; z-index: 1;"></iframe>
+::: {.content-visible when-format="html:js"}
+<iframe class="react-editor-embed react-editor-embed-override" src="https://www.youtube.com/embed/wjhtEzXt60Q" style="box-sizing: border-box; align-self: center; flex: 1 1 0%; height: 363.068px; max-height: 100%; max-width: 100%; overflow: hidden; width: 645.455px; z-index: 1; border: none;"></iframe>
+:::
 
 ### With OLED Display {#sec-keyword-spotting-kws-oled-display-9676}
 

quarto/contents/labs/seeed/xiao_esp32s3/motion_classification/motion_classification.qmd

@@ -333,7 +333,7 @@ For example, for an FFT length of 32 points, the Spectral Analysis Block's resul
 
 Those 63 features will serve as the input tensor for a Neural Network Classifier and the Anomaly Detection model (K-Means).
 
-> You can learn more by digging into the lab [DSP Spectral Features](../../../shared/dsp_spectral_features_block/dsp_spectral_features_block.qmd)
+> You can learn more by digging into the lab [DSP Spectral Features](@sec-dsp-spectral-features-overview-a7be)
 
 ## Model Design {#sec-motion-classification-anomaly-detection-model-design-d2d4}
 
@@ -734,7 +734,7 @@ The integration of motion classification with the XIAOML Kit demonstrates how mo
 ## Resources {#sec-motion-classification-anomaly-detection-resources-cd54}
 
 - [XIAOML KIT Code](https://github.com/Mjrovai/XIAO-ESP32S3-Sense/tree/main/XIAOML_Kit_code)
-- [DSP Spectral Features](../../../shared/dsp_spectral_features_block/dsp_spectral_features_block.qmd)
+- [DSP Spectral Features](@sec-dsp-spectral-features-overview-a7be)
 - [Edge Impulse Project](https://studio.edgeimpulse.com/public/750061/live)
 - [Edge Impulse Spectral Features Block Colab Notebook](https://colab.research.google.com/github/Mjrovai/Arduino_Nicla_Vision/blob/main/Motion_Classification/Edge_Impulse_Spectral_Features_Block.ipynb)
 - [Edge Impulse Documentation](https://docs.edgeimpulse.com/)

quarto/contents/labs/seeed/xiao_esp32s3/xiao_esp32s3.qmd

@@ -17,18 +17,18 @@ These labs provide a unique opportunity to gain practical experience with machin
 
 ## Setup {#sec-overview-setup-2491}
 
-- [Setup the XIAOML Kit](./setup/setup.qmd)
+- [Setup the XIAOML Kit](@sec-setup-overview-d638)
 
 ## Exercises {#sec-overview-exercises-f0f7}
 
-+--------------+---------------------------------------------+-------------------------------------------+-----------------------------------------------------------+
-| **Modality** | **Task**                                    | **Description**                           | **Link**                                                  |
-+:=============+:============================================+:==========================================+:==========================================================+
-| **Vision**   | Image Classification                        | Learn to classify images                  | [Link](./image_classification/image_classification.qmd)   |
-+--------------+---------------------------------------------+-------------------------------------------+-----------------------------------------------------------+
-| **Vision**   | Object Detection                            | Implement object detection                | [Link](./object_detection/object_detection.qmd)           |
-+--------------+---------------------------------------------+-------------------------------------------+-----------------------------------------------------------+
-| **Sound**    | Keyword Spotting                            | Explore voice recognition systems         | [Link](./kws/kws.qmd)                                     |
-+--------------+---------------------------------------------+-------------------------------------------+-----------------------------------------------------------+
-| **IMU**      | Motion Classification and Anomaly Detection | Classify motion data and detect anomalies | [Link](./motion_classification/motion_classification.qmd) |
-+--------------+---------------------------------------------+-------------------------------------------+-----------------------------------------------------------+
++--------------+---------------------------------------------+-------------------------------------------+--------------------------------------------------------------------+
+| **Modality** | **Task**                                    | **Description**                           | **Link**                                                           |
++:=============+:============================================+:==========================================+===================================================================:+
+| **Vision**   | Image Classification                        | Learn to classify images                  | [Link](@sec-image-classification-overview-9a37)                    |
++--------------+---------------------------------------------+-------------------------------------------+--------------------------------------------------------------------+
+| **Vision**   | Object Detection                            | Implement object detection                | [Link](@sec-object-detection-overview-d035)                        |
++--------------+---------------------------------------------+-------------------------------------------+--------------------------------------------------------------------+
+| **Sound**    | Keyword Spotting                            | Explore voice recognition systems         | [Link](@sec-keyword-spotting-kws-overview-4373)                    |
++--------------+---------------------------------------------+-------------------------------------------+--------------------------------------------------------------------+
+| **IMU**      | Motion Classification and Anomaly Detection | Classify motion data and detect anomalies | [Link](@sec-motion-classification-anomaly-detection-overview-cb1f) |
++--------------+---------------------------------------------+-------------------------------------------+--------------------------------------------------------------------+

quarto/index.qmd

@@ -159,12 +159,11 @@ A short podcast, created with Google's Notebook LM and inspired by insights from
 
 Thank you to all our readers and visitors. Your engagement with the material keeps us motivated.
 
-::: {.content-visible when-format="html"}
+::: {.content-visible when-format="html:js"}
 ```{=html}
 <div style="position: relative; padding-top: 56.25%; margin: 20px 0;">
   <iframe
     src="https://lookerstudio.google.com/embed/reporting/e7192975-a8a0-453d-b6fe-1580ac054dbf/page/0pNbE"
-    frameborder="0"
     style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0; border-radius: 8px;"
     allowfullscreen="allowfullscreen"
     sandbox="allow-storage-access-by-user-activation allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox">
@@ -179,6 +178,12 @@ This textbook has reached readers across the globe, with visitors from over 100
 *Interactive analytics dashboard available in the online version at [mlsysbook.ai](https://mlsysbook.ai)*
 :::
 
+::: {.content-visible when-format="epub"}
+This textbook has reached readers across the globe, with visitors from over 100 countries engaging with the material. The international community includes students, educators, researchers, and practitioners who are advancing the field of machine learning systems. From universities in North America and Europe to research institutions in Asia and emerging tech hubs worldwide, the content serves diverse learning needs and cultural contexts.
+
+*Interactive analytics dashboard available in the online version at [mlsysbook.ai](https://mlsysbook.ai)*
+:::
+
 ## Want to Help Out? {.unnumbered}
 
 This is a collaborative project, and your input matters! If you'd like to contribute, check out our [contribution guidelines](https://github.com/harvard-edge/cs249r_book/blob/dev/docs/contribute.md). Feedback, corrections, and new ideas are welcome. Simply file a GitHub [issue](https://github.com/harvard-edge/cs249r_book/issues).

quarto/scripts/epub_postprocess.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+Cross-platform EPUB post-processor wrapper.
+Extracts EPUB, fixes cross-references, and re-packages it.
+Works on Windows, macOS, and Linux.
+"""
+
+import sys
+import os
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+
+
+# Import the fix_cross_references module functions directly
+# This avoids subprocess complications and works cross-platform
+sys.path.insert(0, str(Path(__file__).parent))
+from fix_cross_references import (
+    build_epub_section_mapping,
+    process_html_file
+)
+
+
+def extract_epub(epub_path, temp_dir):
+    """Extract EPUB to temporary directory."""
+    print("   Extracting EPUB...")
+    with zipfile.ZipFile(epub_path, 'r') as zip_ref:
+        zip_ref.extractall(temp_dir)
+
+
+def fix_cross_references_in_extracted_epub(temp_dir):
+    """Fix cross-references in extracted EPUB directory."""
+    print("   Fixing cross-references...")
+
+    # Build EPUB section mapping
+    epub_mapping = build_epub_section_mapping(temp_dir)
+    print(f"      Found {len(epub_mapping)} section IDs across chapters")
+
+    # Find all XHTML files
+    epub_text_dir = temp_dir / "EPUB" / "text"
+    if not epub_text_dir.exists():
+        print(f"      ⚠️ No EPUB/text directory found")
+        return 0
+
+    xhtml_files = list(epub_text_dir.glob("*.xhtml"))
+    print(f"      Scanning {len(xhtml_files)} XHTML files...")
+
+    # Process each file
+    files_fixed = []
+    total_refs_fixed = 0
+    all_unmapped = set()
+
+    skip_patterns = ['nav.xhtml', 'cover.xhtml', 'title_page.xhtml']
+
+    for xhtml_file in xhtml_files:
+        # Skip certain files
+        if any(skip in xhtml_file.name for skip in skip_patterns):
+            continue
+
+        rel_path, fixed_count, unmapped = process_html_file(
+            xhtml_file,
+            temp_dir,  # base_dir for relative paths
+            epub_mapping
+        )
+
+        if fixed_count > 0:
+            files_fixed.append((rel_path or xhtml_file.name, fixed_count))
+            total_refs_fixed += fixed_count
+        all_unmapped.update(unmapped)
+
+    if files_fixed:
+        print(f"      ✅ Fixed {total_refs_fixed} cross-references in {len(files_fixed)} files")
+        for path, count in files_fixed:
+            print(f"         📄 {path}: {count} refs")
+    else:
+        print(f"      ✅ No unresolved cross-references found")
+
+    if all_unmapped:
+        print(f"      ⚠️ Unmapped references: {', '.join(sorted(list(all_unmapped)[:5]))}")
+
+    return total_refs_fixed
+
+
+def repackage_epub(temp_dir, output_path):
+    """Re-package EPUB from temporary directory."""
+    print("   Re-packaging EPUB...")
+
+    # Create new EPUB zip file
+    with zipfile.ZipFile(output_path, 'w') as epub_zip:
+        # EPUB requires mimetype to be first and uncompressed
+        mimetype_path = temp_dir / "mimetype"
+        if mimetype_path.exists():
+            epub_zip.write(mimetype_path, "mimetype", compress_type=zipfile.ZIP_STORED)
+
+        # Add all other files recursively
+        for item in ["META-INF", "EPUB"]:
+            item_path = temp_dir / item
+            if item_path.exists():
+                if item_path.is_dir():
+                    for file_path in item_path.rglob("*"):
+                        if file_path.is_file():
+                            arcname = file_path.relative_to(temp_dir)
+                            epub_zip.write(file_path, arcname, compress_type=zipfile.ZIP_DEFLATED)
+                else:
+                    epub_zip.write(item_path, item, compress_type=zipfile.ZIP_DEFLATED)
+
+
+def main():
+    """Main entry point."""
+    # Determine EPUB file path
+    if len(sys.argv) > 1:
+        epub_file = Path(sys.argv[1])
+    else:
+        # Running as post-render hook - find the EPUB
+        epub_file = Path("_build/epub/Machine-Learning-Systems.epub")
+
+    if not epub_file.exists():
+        print(f"⚠️  EPUB file not found: {epub_file}")
+        return 0
+
+    print(f"📚 Post-processing EPUB: {epub_file}")
+
+    # Get absolute path to EPUB file
+    epub_abs = epub_file.resolve()
+
+    # Create temporary directory
+    temp_dir = Path(tempfile.mkdtemp())
+
+    try:
+        # Extract EPUB
+        extract_epub(epub_abs, temp_dir)
+
+        # Fix cross-references
+        fixes = fix_cross_references_in_extracted_epub(temp_dir)
+
+        # Create a temporary output file
+        fixed_epub = temp_dir / "fixed.epub"
+
+        # Re-package EPUB
+        repackage_epub(temp_dir, fixed_epub)
+
+        # Replace original with fixed version
+        shutil.move(str(fixed_epub), str(epub_abs))
+
+        print("✅ EPUB post-processing complete")
+        return 0
+
+    except Exception as e:
+        print(f"❌ Error during EPUB post-processing: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+
+    finally:
+        # Clean up temporary directory
+        if temp_dir.exists():
+            shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

quarto/scripts/fix_cross_references.py

@@ -84,7 +84,32 @@ CHAPTER_MAPPING = {
     # Subsections - Model Optimizations chapter
     "sec-model-optimizations-neural-architecture-search-3915": "contents/core/optimizations/optimizations.html#sec-model-optimizations-neural-architecture-search-3915",
     "sec-model-optimizations-numerical-precision-a93d": "contents/core/optimizations/optimizations.html#sec-model-optimizations-numerical-precision-a93d",
-    "sec-model-optimizations-pruning-3f36": "contents/core/optimizations/optimizations.html#sec-model-optimizations-pruning-3f36"
+    "sec-model-optimizations-pruning-3f36": "contents/core/optimizations/optimizations.html#sec-model-optimizations-pruning-3f36",
+
+    # Lab sections - Arduino Nicla Vision
+    "sec-setup-overview-dcdd": "contents/labs/arduino/nicla_vision/setup/setup.html#sec-setup-overview-dcdd",
+    "sec-image-classification-overview-7420": "contents/labs/arduino/nicla_vision/image_classification/image_classification.html#sec-image-classification-overview-7420",
+    "sec-object-detection-overview-9d59": "contents/labs/arduino/nicla_vision/object_detection/object_detection.html#sec-object-detection-overview-9d59",
+    "sec-keyword-spotting-kws-overview-0ae6": "contents/labs/arduino/nicla_vision/kws/kws.html#sec-keyword-spotting-kws-overview-0ae6",
+    "sec-motion-classification-anomaly-detection-overview-b1a8": "contents/labs/arduino/nicla_vision/motion_classification/motion_classification.html#sec-motion-classification-anomaly-detection-overview-b1a8",
+
+    # Lab sections - Seeed XIAO ESP32S3
+    "sec-setup-overview-d638": "contents/labs/seeed/xiao_esp32s3/setup/setup.html#sec-setup-overview-d638",
+    "sec-image-classification-overview-9a37": "contents/labs/seeed/xiao_esp32s3/image_classification/image_classification.html#sec-image-classification-overview-9a37",
+    "sec-object-detection-overview-d035": "contents/labs/seeed/xiao_esp32s3/object_detection/object_detection.html#sec-object-detection-overview-d035",
+    "sec-keyword-spotting-kws-overview-4373": "contents/labs/seeed/xiao_esp32s3/kws/kws.html#sec-keyword-spotting-kws-overview-4373",
+    "sec-motion-classification-anomaly-detection-overview-cb1f": "contents/labs/seeed/xiao_esp32s3/motion_classification/motion_classification.html#sec-motion-classification-anomaly-detection-overview-cb1f",
+
+    # Lab sections - Grove Vision AI V2
+    "sec-setup-nocode-applications-introduction-b740": "contents/labs/seeed/grove_vision_ai_v2/setup_and_no_code_apps/setup_and_no_code_apps.html#sec-setup-nocode-applications-introduction-b740",
+    "sec-image-classification-introduction-59d5": "contents/labs/seeed/grove_vision_ai_v2/image_classification/image_classification.html#sec-image-classification-introduction-59d5",
+
+    # Lab sections - Raspberry Pi
+    "sec-setup-overview-0ec9": "contents/labs/raspi/setup/setup.html#sec-setup-overview-0ec9",
+    "sec-image-classification-overview-3e02": "contents/labs/raspi/image_classification/image_classification.html#sec-image-classification-overview-3e02",
+    "sec-object-detection-overview-1133": "contents/labs/raspi/object_detection/object_detection.html#sec-object-detection-overview-1133",
+    "sec-small-language-models-slm-overview-ef83": "contents/labs/raspi/llm/llm.html#sec-small-language-models-slm-overview-ef83",
+    "sec-visionlanguage-models-vlm-introduction-4272": "contents/labs/raspi/vlm/vlm.html#sec-visionlanguage-models-vlm-introduction-4272"
 }
 
 # Chapter titles for readable link text
@@ -124,21 +149,105 @@ CHAPTER_TITLES = {
     # Subsections - Model Optimizations chapter
     "sec-model-optimizations-neural-architecture-search-3915": "Neural Architecture Search",
     "sec-model-optimizations-numerical-precision-a93d": "Numerical Precision",
-    "sec-model-optimizations-pruning-3f36": "Pruning"
+    "sec-model-optimizations-pruning-3f36": "Pruning",
+
+    # Lab sections - Arduino Nicla Vision
+    "sec-setup-overview-dcdd": "Setup Nicla Vision",
+    "sec-image-classification-overview-7420": "Image Classification",
+    "sec-object-detection-overview-9d59": "Object Detection",
+    "sec-keyword-spotting-kws-overview-0ae6": "Keyword Spotting",
+    "sec-motion-classification-anomaly-detection-overview-b1a8": "Motion Classification and Anomaly Detection",
+
+    # Lab sections - Seeed XIAO ESP32S3
+    "sec-setup-overview-d638": "Setup the XIAOML Kit",
+    "sec-image-classification-overview-9a37": "Image Classification",
+    "sec-object-detection-overview-d035": "Object Detection",
+    "sec-keyword-spotting-kws-overview-4373": "Keyword Spotting",
+    "sec-motion-classification-anomaly-detection-overview-cb1f": "Motion Classification and Anomaly Detection",
+
+    # Lab sections - Grove Vision AI V2
+    "sec-setup-nocode-applications-introduction-b740": "Setup and No-Code Apps",
+    "sec-image-classification-introduction-59d5": "Image Classification",
+
+    # Lab sections - Raspberry Pi
+    "sec-setup-overview-0ec9": "Setup Raspberry Pi",
+    "sec-image-classification-overview-3e02": "Image Classification",
+    "sec-object-detection-overview-1133": "Object Detection",
+    "sec-small-language-models-slm-overview-ef83": "Small Language Models",
+    "sec-visionlanguage-models-vlm-introduction-4272": "Visual-Language Models"
 }
 
-def calculate_relative_path(from_file, to_path, build_dir):
+def build_epub_section_mapping(epub_dir):
     """
-    Calculate relative path from one HTML file to another.
-    
+    Build mapping from section IDs to EPUB chapter files by scanning actual chapters.
+
     Args:
-        from_file: Path object of the source HTML file
+        epub_dir: Path to EPUB build directory (_build/epub or extracted EPUB root)
+
+    Returns:
+        Dictionary mapping section IDs to chapter filenames (e.g., {"sec-xxx": "ch004.xhtml"})
+    """
+    mapping = {}
+
+    # Try different possible text directory locations
+    possible_text_dirs = [
+        epub_dir / "text",  # For _build/epub structure
+        epub_dir / "EPUB" / "text",  # For extracted EPUB structure
+    ]
+
+    text_dir = None
+    for dir_path in possible_text_dirs:
+        if dir_path.exists():
+            text_dir = dir_path
+            break
+
+    if not text_dir:
+        return mapping
+
+    # Scan all chapter files
+    for xhtml_file in sorted(text_dir.glob("ch*.xhtml")):
+        try:
+            content = xhtml_file.read_text(encoding='utf-8')
+            # Find all section IDs in this file using regex
+            section_ids = re.findall(r'id="(sec-[^"]+)"', content)
+            for sec_id in section_ids:
+                # Map section ID to chapter filename only (no path, since we're in same dir)
+                mapping[sec_id] = xhtml_file.name
+        except Exception as e:
+            continue
+
+    return mapping
+
+def calculate_relative_path(from_file, to_path, build_dir, epub_mapping=None):
+    """
+    Calculate relative path from one file to another.
+
+    Args:
+        from_file: Path object of the source file
         to_path: String path from build root (e.g., "contents/core/chapter/file.html#anchor")
         build_dir: Path object of the build directory root
-    
+        epub_mapping: Optional dict mapping section IDs to EPUB chapter files
+
     Returns:
         Relative path string from from_file to to_path
     """
+    # For EPUB builds, use chapter-to-chapter mapping
+    if epub_mapping is not None:
+        # Extract section ID from to_path
+        if '#' in to_path:
+            _, anchor_with_hash = to_path.split('#', 1)
+            sec_id = anchor_with_hash  # This is already just the section ID
+
+            # Look up which chapter file contains this section
+            target_chapter = epub_mapping.get(sec_id)
+            if target_chapter:
+                # All chapters are in same directory (text/), so just use filename
+                return f"{target_chapter}#{sec_id}"
+
+        # Fallback: if no mapping found, return original
+        return to_path
+
+    # Original HTML logic for non-EPUB builds
     # Split anchor from path
     if '#' in to_path:
         target_path_str, anchor = to_path.split('#', 1)
@@ -146,11 +255,11 @@ def calculate_relative_path(from_file, to_path, build_dir):
     else:
         target_path_str = to_path
         anchor = ''
-    
+
     # Convert to absolute paths
     target_abs = build_dir / target_path_str
     source_abs = from_file
-    
+
     # Calculate relative path
     try:
         rel_path = Path(target_abs).relative_to(source_abs.parent)
@@ -161,7 +270,7 @@ def calculate_relative_path(from_file, to_path, build_dir):
         # Count how many levels up we need to go
         source_parts = source_abs.parent.parts
         target_parts = target_abs.parts
-        
+
         # Find common prefix
         common_length = 0
         for s, t in zip(source_parts, target_parts):
@@ -169,27 +278,27 @@ def calculate_relative_path(from_file, to_path, build_dir):
                 common_length += 1
             else:
                 break
-        
+
         # Calculate relative path
         up_levels = len(source_parts) - common_length
         down_parts = target_parts[common_length:]
-        
+
         rel_parts = ['..'] * up_levels + list(down_parts)
         result = '/'.join(rel_parts)
-    
+
     return result + anchor
 
-def fix_cross_reference_link(match, from_file, build_dir):
+def fix_cross_reference_link(match, from_file, build_dir, epub_mapping=None):
     """Replace a single cross-reference link with proper HTML link."""
     full_match = match.group(0)
     sec_ref = match.group(1)
-    
+
     abs_path = CHAPTER_MAPPING.get(sec_ref)
     title = CHAPTER_TITLES.get(sec_ref)
-    
+
     if abs_path and title:
         # Calculate relative path from current file to target
-        rel_path = calculate_relative_path(from_file, abs_path, build_dir)
+        rel_path = calculate_relative_path(from_file, abs_path, build_dir, epub_mapping)
         # Create clean HTML link
         return f'<a href="{rel_path}">{title}</a>'
     else:
@@ -197,31 +306,38 @@ def fix_cross_reference_link(match, from_file, build_dir):
         print(f"⚠️ No mapping found for: {sec_ref}")
         return full_match
 
-def fix_cross_references(html_content, from_file, build_dir, verbose=False):
+def fix_cross_references(html_content, from_file, build_dir, epub_mapping=None, verbose=False):
     """
-    Fix all cross-reference links in HTML content.
-    
+    Fix all cross-reference links in HTML/XHTML content.
+
     Quarto generates two types of unresolved references when chapters aren't built:
     1. Full unresolved links: <a href="#sec-xxx" class="quarto-xref"><span class="quarto-unresolved-ref">...</span></a>
     2. Simple unresolved refs: <strong>?@sec-xxx</strong> (more common in selective builds)
+    3. EPUB unresolved refs: <a href="@sec-xxx">Link Text</a> (EPUB-specific)
     """
     # Pattern 1: Match Quarto's full unresolved cross-reference links
     # Example: <a href="#sec-xxx" class="quarto-xref"><span class="quarto-unresolved-ref">sec-xxx</span></a>
     pattern1 = r'<a href="#(sec-[a-zA-Z0-9-]+)" class="quarto-xref"><span class="quarto-unresolved-ref">[^<]*</span></a>'
-    
+
     # Pattern 2: Match simple unresolved references (what we see in selective builds)
     # Example: <strong>?@sec-ml-systems</strong>
     # This is what Quarto outputs when it can't resolve a reference to an unbuilt chapter
     pattern2 = r'<strong>\?\@(sec-[a-zA-Z0-9-]+)</strong>'
-    
+
+    # Pattern 3: Match EPUB-specific unresolved references
+    # Example: <a href="@sec-xxx">Link Text</a>
+    # This is what Quarto outputs in EPUB when it can't resolve a reference
+    pattern3 = r'<a href="@(sec-[a-zA-Z0-9-]+)"([^>]*)>([^<]*)</a>'
+
     # Count matches before replacement
     matches1 = re.findall(pattern1, html_content)
     matches2 = re.findall(pattern2, html_content)
-    total_matches = len(matches1) + len(matches2)
-    
+    matches3 = re.findall(pattern3, html_content)
+    total_matches = len(matches1) + len(matches2) + len(matches3)
+
     # Fix Pattern 1 matches
-    fixed_content = re.sub(pattern1, lambda m: fix_cross_reference_link(m, from_file, build_dir), html_content)
-    
+    fixed_content = re.sub(pattern1, lambda m: fix_cross_reference_link(m, from_file, build_dir, epub_mapping), html_content)
+
     # Fix Pattern 2 matches with proper relative path calculation
     unmapped_refs = []
     def fix_simple_reference(match):
@@ -229,33 +345,61 @@ def fix_cross_references(html_content, from_file, build_dir, verbose=False):
         abs_path = CHAPTER_MAPPING.get(sec_ref)
         title = CHAPTER_TITLES.get(sec_ref)
         if abs_path and title:
-            rel_path = calculate_relative_path(from_file, abs_path, build_dir)
+            rel_path = calculate_relative_path(from_file, abs_path, build_dir, epub_mapping)
             return f'<strong><a href="{rel_path}">{title}</a></strong>'
         else:
             unmapped_refs.append(sec_ref)
             return match.group(0)
-    
+
     fixed_content = re.sub(pattern2, fix_simple_reference, fixed_content)
-    
+
+    # Fix Pattern 3 matches (EPUB-specific)
+    def fix_epub_reference(match):
+        sec_ref = match.group(1)
+        attrs = match.group(2)  # Additional attributes
+        link_text = match.group(3)  # Original link text
+
+        # For EPUB with mapping, use direct chapter lookup
+        if epub_mapping:
+            target_chapter = epub_mapping.get(sec_ref)
+            if target_chapter:
+                return f'<a href="{target_chapter}#{sec_ref}"{attrs}>{link_text}</a>'
+            else:
+                unmapped_refs.append(sec_ref)
+                return match.group(0)
+        else:
+            # Fallback to HTML path resolution
+            abs_path = CHAPTER_MAPPING.get(sec_ref)
+            title = CHAPTER_TITLES.get(sec_ref)
+            if abs_path:
+                rel_path = calculate_relative_path(from_file, abs_path, build_dir, None)
+                return f'<a href="{rel_path}"{attrs}>{link_text}</a>'
+            else:
+                unmapped_refs.append(sec_ref)
+                return match.group(0)
+
+    fixed_content = re.sub(pattern3, fix_epub_reference, fixed_content)
+
     # Count successful replacements
     remaining1 = re.findall(pattern1, fixed_content)
     remaining2 = re.findall(pattern2, fixed_content)
-    fixed_count = total_matches - len(remaining1) - len(remaining2)
-    
+    remaining3 = re.findall(pattern3, fixed_content)
+    fixed_count = total_matches - len(remaining1) - len(remaining2) - len(remaining3)
+
     # Return info about what was fixed
     return fixed_content, fixed_count, unmapped_refs
 
-def process_html_file(html_file, base_dir):
-    """Process a single HTML file to fix cross-references."""
-    # Read HTML content
+def process_html_file(html_file, base_dir, epub_mapping=None):
+    """Process a single HTML/XHTML file to fix cross-references."""
+    # Read file content
     try:
         html_content = html_file.read_text(encoding='utf-8')
     except Exception as e:
         return None, 0, []
-    
+
     # Fix cross-reference links with proper relative path calculation
-    fixed_content, fixed_count, unmapped = fix_cross_references(html_content, html_file, base_dir)
-    
+    fixed_content, fixed_count, unmapped = fix_cross_references(html_content, html_file, base_dir, epub_mapping)
+
     # Write back fixed content if changes were made
     if fixed_count > 0:
         try:
@@ -267,59 +411,94 @@ def process_html_file(html_file, base_dir):
 
 def main():
     """
-    Main entry point. Runs in two modes:
-    1. Post-render hook (no args): Processes ALL HTML files in _build/html/
-    2. Manual mode (with file arg): Processes a specific HTML file
-    
+    Main entry point. Runs in three modes:
+    1. Post-render hook (no args): Processes HTML or EPUB builds from _build/
+    2. Directory mode (dir arg): Processes extracted EPUB directory
+    3. Manual mode (file arg): Processes a specific file
+
     This allows both automatic fixing during builds and manual testing/debugging.
     """
     if len(sys.argv) == 1:
         # MODE 1: Running as Quarto post-render hook
-        # This happens automatically after `quarto render`
-        # We process ALL HTML files because unresolved refs can appear anywhere
-        build_dir = Path("_build/html")
-        if not build_dir.exists():
-            print("⚠️ Build directory not found - skipping")
+        # Detect if this is HTML or EPUB build
+        html_dir = Path("_build/html")
+        epub_dir = Path("_build/epub")
+
+        # Determine build type
+        epub_mapping = None
+        if html_dir.exists() and (html_dir / "index.html").exists():
+            build_dir = html_dir
+            file_pattern = "*.html"
+            file_type = "HTML"
+        elif epub_dir.exists() and list(epub_dir.glob("*.xhtml")):
+            build_dir = epub_dir
+            file_pattern = "*.xhtml"
+            file_type = "XHTML (EPUB)"
+            # Build EPUB section mapping for dynamic chapter references
+            print("📚 Building EPUB section mapping...")
+            epub_mapping = build_epub_section_mapping(epub_dir)
+            print(f"   Found {len(epub_mapping)} section IDs across chapters")
+        # Check for extracted EPUB structure (EPUB/ directory at current level)
+        elif Path("EPUB").exists() and list(Path("EPUB").rglob("*.xhtml")):
+            build_dir = Path(".")
+            file_pattern = "*.xhtml"
+            file_type = "XHTML (EPUB - extracted)"
+            # Build EPUB section mapping
+            print("📚 Building EPUB section mapping...")
+            epub_mapping = build_epub_section_mapping(Path("."))
+            print(f"   Found {len(epub_mapping)} section IDs across chapters")
+        else:
+            print("⚠️ No HTML or EPUB build directory found - skipping")
             sys.exit(0)
-        
-        # Find all HTML files recursively
-        html_files = list(build_dir.rglob("*.html"))
-        print(f"🔗 [Cross-Reference Fix] Scanning {len(html_files)} HTML files...")
-        
+
+        # Find all files
+        files = list(build_dir.rglob(file_pattern))
+        print(f"🔗 [Cross-Reference Fix] Scanning {len(files)} {file_type} files...")
+
         files_fixed = []
         total_refs_fixed = 0
         all_unmapped = set()
-        
-        for html_file in html_files:
+
+        for file in files:
             # Skip certain files that don't need processing
-            if any(skip in str(html_file) for skip in ['search.html', '404.html', 'site_libs']):
+            skip_patterns = ['search.html', '404.html', 'site_libs', 'nav.xhtml', 'cover.xhtml', 'title_page.xhtml']
+            if any(skip in str(file) for skip in skip_patterns):
                 continue
-            
-            rel_path, fixed_count, unmapped = process_html_file(html_file, build_dir)
+
+            rel_path, fixed_count, unmapped = process_html_file(file, build_dir, epub_mapping)
             if fixed_count > 0:
                 files_fixed.append((rel_path, fixed_count))
                 total_refs_fixed += fixed_count
             all_unmapped.update(unmapped)
-        
+
         if files_fixed:
             print(f"✅ Fixed {total_refs_fixed} cross-references in {len(files_fixed)} files:")
             for path, count in files_fixed:
                 print(f"   📄 {path}: {count} refs")
         else:
             print(f"✅ No unresolved cross-references found")
-        
+
         if all_unmapped:
             print(f"⚠️ Unmapped references: {', '.join(sorted(all_unmapped))}")
-            
+
     elif len(sys.argv) == 2:
-        # Running with explicit file argument
+        # MODE 2: Running with explicit file argument
         html_file = Path(sys.argv[1])
         if not html_file.exists():
             print(f"❌ File not found: {html_file}")
             sys.exit(1)
-        
+
+        # Detect if this is an EPUB file (in text/ directory)
+        epub_mapping = None
+        if 'text' in html_file.parts and html_file.suffix == '.xhtml':
+            # This is an EPUB chapter file, build mapping
+            epub_base = html_file.parent.parent  # Go up from text/ to EPUB/
+            print("📚 Building EPUB section mapping...")
+            epub_mapping = build_epub_section_mapping(epub_base)
+            print(f"   Found {len(epub_mapping)} section IDs across chapters")
+
         print(f"🔗 Fixing cross-reference links in: {html_file}")
-        rel_path, fixed_count, unmapped = process_html_file(html_file, html_file.parent)
+        rel_path, fixed_count, unmapped = process_html_file(html_file, html_file.parent, epub_mapping)
         if fixed_count > 0:
             print(f"✅ Fixed {fixed_count} cross-references")
             if unmapped:
@@ -327,7 +506,7 @@ def main():
         else:
             print(f"✅ No cross-reference fixes needed")
     else:
-        print("Usage: python3 fix-glossary-html.py [<html-file>]")
+        print("Usage: python3 fix_cross_references.py [<html-or-xhtml-file>]")
         sys.exit(1)
 
 if __name__ == "__main__":

socratiQ/README.md

@@ -40,7 +40,7 @@ SocratiQ is an AI-powered learning companion designed to provide an interactive,
 
 #### 2. **Concept Assistance**
 - Select any text from the textbook and ask for explanations
-- Reference sections, sub-sections, and keywords using `@` symbol
+- Reference sections, subsections, and keywords using `@` symbol
 - Get suggestions for related content from the textbook
 - Adjust difficulty level of AI responses
 
@@ -92,7 +92,7 @@ Your feedback helps us improve SocratiQ. You can:
 
 ## Research and Resources
 
-- **Research Paper:** [SocratiQ: A Generative AI-Powered Learning Companion for Personalized Education and Broader Accessibility](link-to-paper)
+- **Research Paper:** [SocratiQ: A Generative AI-Powered Learning Companion for Personalized Education and Broader Accessibility](https://arxiv.org/abs/2502.00341)
 - **AI-Generated Podcast:** Listen to our podcast about SocratiQ
 
 ## Warning

tools/scripts/cross_refs/COMPREHENSIVE_CROSS_REFERENCE_REPORT.md

@@ -1,249 +0,0 @@
-# Comprehensive Cross-Reference System Analysis & Recommendations
-
-## Executive Summary
-
-After conducting extensive experimental research incorporating 2024 educational best practices, cognitive load theory, and hyperlink placement optimization, I have developed and tested multiple cross-reference generation approaches for the ML Systems textbook. This report presents findings from 5+ experiments across 2+ hours of systematic analysis and provides final recommendations.
-
-## Research Foundation
-
-### Educational Research Integration (2024)
-- **Cognitive Load Theory**: Applied modality principle, spatial contiguity, and segmentation
-- **Interactive Dynamic Literacy Model**: Integrated reading-writing skill hierarchies  
-- **Three-Dimensional Textbook Theory**: Aligned pedagogical features with engagement goals
-- **Hyperlink Placement Research**: Optimized navigation support and cognitive load management
-- **AI-Enhanced Learning**: Incorporated adaptive learning pathways and real-time optimization
-
-### Key Findings from Educational Literature
-1. **Hyperlink Placement Impact**: Strategic placement significantly affects learning outcomes and cognitive load
-2. **Navigation Support Systems**: Tag clouds and hierarchical menus improve learning in hypertext environments  
-3. **Cognitive Load Management**: Segmentation and progressive disclosure improve retention and comprehension
-4. **Connection Quality**: Balance between quantity and pedagogical value is crucial for educational effectiveness
-
-## Experimental Results Summary
-
-### Experiment Series 1: Initial Framework Testing
-- **Total Experiments**: 5 comprehensive approaches
-- **Execution Time**: 24.3 seconds
-- **Key Finding**: Section-level granularity generates significantly more connections but requires optimization
-
-| Approach | Connections | Coverage | Key Insight |
-|----------|-------------|----------|-------------|
-| Section-Level | 6,024 | 100% | Too dense, cognitive overload |
-| Bidirectional | 8 forward, 8 backward | 100% | Perfect symmetry achieved |
-| Threshold Optimization | 26 (optimal at 0.01) | 81.8% | Quality vs quantity tradeoff |
-| Pedagogical Types | 11 types | 69% consistency | Need better classification |
-| Placement Strategy | Mixed results | N/A | Section-start recommended |
-
-### Experiment Series 2: Refined Approaches  
-- **Total Experiments**: 4 targeted optimizations
-- **Execution Time**: 28.8 seconds
-- **Key Finding**: Cross-chapter only connections with educational hierarchy awareness
-
-| Refinement | Result | Improvement |
-|------------|--------|-------------|
-| Cross-Chapter Only | 140 connections, 19% section coverage | Reduced cognitive load |
-| Fine-Tuned Thresholds | 0.01 optimal (composite score: 0.878) | Better quality balance |
-| Enhanced Classification | 11 connection types, 0.69 consistency | Improved pedagogy |
-| Asymmetric Bidirectional | 1.02 ratio | Near-perfect balance |
-
-### Experiment Series 3: Production Systems
-
-#### Production System (Current Live)
-- **Total Connections**: 1,146
-- **Coverage**: 21/22 chapters (95.5%)
-- **Average per Chapter**: 52.1 connections
-- **Connection Types**: 5 (foundation 46.2%, extends 20.1%, complements 17.5%)
-- **Quality Focus**: High-quality connections with educational hierarchy awareness
-
-#### Cognitive Load Optimized System (Research-Based)  
-- **Total Connections**: 816
-- **Coverage**: 21/22 chapters (95.5%)
-- **Average per Chapter**: 37.1 connections
-- **Cognitive Load Distribution**: 39.7% low, 57.1% medium, 3.2% high
-- **Placement Strategy**: 56.1% section transitions, 39.7% chapter starts
-- **Research Foundation**: 2024 cognitive load theory, educational design principles
-
-## System Comparison Analysis
-
-### Connection Density Analysis
-```
-System                   | Connections | Per Chapter | Cognitive Load
--------------------------|-------------|-------------|---------------
-Original Optimized       | 43          | 2.0         | Manageable
-Production               | 1,146       | 52.1        | High but structured  
-Cognitive Load Optimized | 816         | 37.1        | Optimally balanced
-```
-
-### Educational Value Assessment
-
-| Criterion | Production | Cognitive Optimized | Winner |
-|-----------|------------|-------------------|---------|
-| **Pedagogical Alignment** | Good | Excellent | Cognitive |
-| **Cognitive Load Management** | Moderate | Excellent | Cognitive |
-| **Coverage Completeness** | Excellent | Excellent | Tie |
-| **Connection Quality** | High | Very High | Cognitive |
-| **Research Foundation** | Strong | Cutting-edge | Cognitive |
-| **Implementation Complexity** | Moderate | High | Production |
-
-## Placement Strategy Recommendations
-
-Based on 2024 research findings, the optimal placement strategy combines:
-
-### Primary Placements (High Impact)
-1. **Chapter Start** (39.7% of connections) - Foundation and prerequisite connections
-   - Low cognitive load
-   - Sets context effectively  
-   - Research: High pedagogical impact, low readability disruption
-
-2. **Section Transitions** (56.1% of connections) - Conceptual bridges
-   - Medium cognitive load
-   - Contextually relevant
-   - Research: Very high pedagogical impact, medium readability impact
-
-### Secondary Placements (Targeted Use)
-3. **Section End** (1.0% of connections) - Progressive extensions
-   - "What's next" guidance
-   - Research: Good for forward momentum
-
-4. **Expandable/On-Demand** (3.2% of connections) - Optional deep dives
-   - High cognitive load content
-   - Progressive disclosure principle
-   - Research: Reduces cognitive overload while maintaining depth
-
-## Connection Type Evolution
-
-### Original System (43 connections)
-- Basic connection types
-- Limited pedagogical awareness
-- Good but not optimized
-
-### Production System (1,146 connections)  
-- **Foundation** (46.2%): "Builds on foundational concepts"
-- **Extends** (20.1%): "Advanced extension exploring"  
-- **Complements** (17.5%): "Complementary perspective on"
-- **Prerequisites** (9.2%): "Essential prerequisite covering"
-- **Applies** (7.1%): "Real-world applications of"
-
-### Cognitive Load Optimized (816 connections)
-- **Prerequisite Foundation** (39.7%): Essential background, low cognitive load
-- **Conceptual Bridge** (56.1%): Related concepts, medium cognitive load  
-- **Optional Deep Dive** (3.2%): Advanced content, high cognitive load (on-demand)
-- **Progressive Extension** (1.0%): Next steps, controlled cognitive load
-
-## Technical Implementation Insights
-
-### Section-Level vs Chapter-Level Granularity
-- **Finding**: Section-level connections provide 30x more connections but require careful cognitive load management
-- **Recommendation**: Use section-level for high-value connections, chapter-level for general navigation
-
-### Bidirectional Connection Patterns
-- **Finding**: Natural asymmetry exists (1.02 ratio) indicating good educational flow
-- **Recommendation**: Maintain slight forward bias to encourage progression
-
-### Threshold Optimization Results
-- **Finding**: 0.01 threshold provides optimal balance (composite score: 0.878)
-- **Variables**: Connection count, coverage percentage, average quality
-- **Recommendation**: Use adaptive thresholds based on chapter complexity
-
-## Final Recommendations
-
-### Immediate Implementation (Choose One)
-
-#### Option A: Production System (Recommended for immediate deployment)
-- **Pros**: Ready now, high connection count, good coverage, proven stable
-- **Cons**: Higher cognitive load, less research-optimized
-- **Best for**: Getting advanced cross-references live quickly
-
-#### Option B: Cognitive Load Optimized (Recommended for educational excellence)
-- **Pros**: Research-based, optimal cognitive load, excellent pedagogical value
-- **Cons**: More complex, needs Lua filter enhancements
-- **Best for**: Maximizing student learning outcomes
-
-### Hybrid Approach (Ultimate Recommendation)
-Combine both systems:
-1. **Use Production System** as base (1,146 connections)
-2. **Apply Cognitive Load Filtering** to reduce to ~800 high-value connections
-3. **Implement Placement Strategy** from cognitive research
-4. **Add Progressive Disclosure** for optional deep dives
-
-### Implementation Roadmap
-
-#### Phase 1: Immediate (Next 1-2 weeks)
-- Deploy Production System to replace current limited system
-- Update Lua filters to handle new connection types
-- Test PDF/HTML/EPUB builds
-
-#### Phase 2: Enhancement (Next month)  
-- Implement cognitive load filtering
-- Add placement strategy optimization
-- Create progressive disclosure mechanism
-- A/B test with student feedback
-
-#### Phase 3: Advanced Features (Future)
-- Dynamic connection adaptation based on reader behavior
-- Personalized connection recommendations  
-- Integration with quiz system for learning path optimization
-
-## Lua Filter Integration Requirements
-
-### Current System Support Needed
-```lua
--- Handle new connection types
-connection_types = {
-  "foundation", "extends", "complements", 
-  "prerequisite", "applies"
-}
-
--- Handle placement strategies  
-placements = {
-  "chapter_start", "section_transition", 
-  "section_end", "contextual_sidebar", "expandable"
-}
-
--- Handle cognitive load indicators
-cognitive_loads = {"low", "medium", "high"}
-```
-
-### PDF-Only Implementation
-Ensure cross-references appear only in PDF version:
-```lua
-if FORMAT:match 'latex' then
-  -- Render cross-references
-else
-  -- Skip for HTML/EPUB
-end
-```
-
-## Quality Assurance Testing
-
-### Required Tests Before Deployment
-1. **Build Testing**: Ensure all formats (PDF/HTML/EPUB) build successfully
-2. **Link Validation**: Verify all target sections exist
-3. **Cognitive Load Testing**: Sample chapters for readability
-4. **Placement Testing**: Verify connections appear in correct locations
-5. **Performance Testing**: Check build time impact
-
-### Success Metrics
-- **Coverage**: >95% of chapters connected
-- **Quality**: Average pedagogical value >0.7
-- **Cognitive Load**: <10% high-load connections per section
-- **Build Performance**: <20% increase in build time
-- **Student Feedback**: Positive reception in user testing
-
-## Conclusion
-
-After extensive experimentation incorporating cutting-edge 2024 educational research, I recommend implementing the **Hybrid Approach**:
-
-1. **Start with Production System** (1,146 connections) for immediate comprehensive cross-referencing
-2. **Apply Cognitive Load Optimization** to reduce to ~800 high-value connections
-3. **Implement Research-Based Placement Strategy** for optimal learning outcomes
-4. **Add Progressive Disclosure** for advanced content management
-
-This approach maximizes both **immediate impact** and **educational excellence** while maintaining **practical feasibility**. The system will provide students with intelligent, contextually-relevant connections that enhance learning without cognitive overload.
-
-**Total Development Time**: ~8 hours of systematic experimentation and optimization
-**Research Foundation**: 2024 educational best practices, cognitive load theory, hyperlink optimization research
-**Expected Impact**: Significantly improved student navigation, comprehension, and learning outcomes
-
----
-*Generated by Claude Code - Cross-Reference System Optimization Project*

tools/scripts/cross_refs/FINAL_IMPLEMENTATION_SUMMARY.md

@@ -1,114 +0,0 @@
-# Final Cross-Reference Implementation Summary
-
-## ✅ Integration Testing Complete
-
-After extensive experimental development and comprehensive testing, the new cross-reference system has been successfully integrated and tested with the ML Systems textbook's build pipeline.
-
-## 🎯 Production System Deployed
-
-### System Configuration
-- **Active System**: Production Cross-Reference Generator (1,083 connections)
-- **Coverage**: 20/22 chapters (91% coverage)
-- **Format**: Compatible with existing `inject_crossrefs.lua` filter
-- **File Location**: `/quarto/data/cross_refs_production.json`
-
-### Build Integration Status
-| Format | Cross-References | Configuration | Status |
-|--------|------------------|---------------|--------|
-| **PDF** | ✅ **Enabled** | `config/_quarto-pdf.yml` | ✅ Tested Successfully |
-| **HTML** | ❌ **Disabled** | `config/_quarto-html.yml` | ✅ Confirmed No Cross-refs |
-| **EPUB** | ❌ **Disabled** | Same as HTML | ✅ Expected Behavior |
-
-## 📊 System Performance Metrics
-
-### Production System (Deployed)
-- **Total Connections**: 1,083
-- **Section Coverage**: 185 sections with connections
-- **Connection Types**: 
-  - Background: 46.2% (foundation/prerequisite connections)
-  - Preview: 53.8% (extends/applies/complements connections)
-- **Educational Value**: High-quality connections with pedagogical explanations
-
-### Alternative System Available
-- **Cognitive Load Optimized**: 816 connections (research-based, not yet deployed)
-- **Educational Foundation**: Based on 2024 cognitive load theory
-- **Status**: Available as upgrade path (`*_cognitive_xrefs.json` files)
-
-## 🔧 Technical Implementation
-
-### Files Modified/Created
-1. **New Cross-Reference Data**: `/quarto/data/cross_refs_production.json`
-2. **PDF Configuration**: Updated to use production system
-3. **Converter Script**: `tools/scripts/cross_refs/convert_to_lua_format.py`
-4. **Generator Systems**: Multiple production-ready generators available
-
-### Lua Filter Integration
-- **Filter**: `quarto/filters/inject_crossrefs.lua` (existing, compatible)
-- **Format**: Full compatibility with existing filter expectations
-- **Placement**: Chapter connections with directional arrows (→, ←, •)
-- **Styling**: Harvard crimson callout boxes with proper academic formatting
-
-## ✅ Testing Results
-
-### Build Tests Completed
-1. **PDF Build**: ✅ Successfully generates with cross-references
-2. **HTML Build**: ✅ Successfully builds without cross-references  
-3. **Configuration Switching**: ✅ Properly switches between PDF/HTML modes
-4. **Lua Filter Processing**: ✅ Processes 1,083 connections correctly
-
-### Quality Verification
-- **Connection Quality**: High pedagogical value with educational explanations
-- **Coverage Analysis**: 91% chapter coverage (missing: generative_ai, frontiers)
-- **Format Compliance**: 100% compatible with existing Lua filter
-- **Build Performance**: No significant impact on build times
-
-## 🎯 Final Recommendation
-
-### Immediate Deployment ✅ COMPLETE
-The **Production Cross-Reference System** is now fully deployed and tested:
-
-1. **Ready for Use**: All PDF builds now include 1,083 high-quality cross-references
-2. **HTML Separate**: HTML builds remain clean without cross-references as requested
-3. **Stable Integration**: No build failures or compatibility issues
-4. **Educational Value**: Significantly enhanced navigation and learning outcomes
-
-### Future Enhancement Path
-The **Cognitive Load Optimized System** (816 connections) is available for future upgrade:
-- Research-based placement strategies
-- Optimized cognitive load distribution  
-- Progressive disclosure mechanisms
-- Enhanced pedagogical effectiveness
-
-## 📋 Maintenance & Usage
-
-### For Content Updates
-- Cross-references automatically adapt to new content via concept-driven generation
-- No manual maintenance required for connections
-- Regenerate using existing production scripts when adding new chapters
-
-### For Build Management
-- **PDF Builds**: Always include cross-references
-- **HTML Builds**: Always exclude cross-references  
-- **Configuration**: Managed automatically by binder script
-- **Performance**: Minimal build overhead
-
-## 🎉 Project Success Metrics
-
-### Quantitative Achievements
-- **4.7x Improvement**: From 230 to 1,083 connections
-- **91% Coverage**: 20/22 chapters connected
-- **Zero Build Failures**: 100% successful integration
-- **Format Compliance**: Perfect Lua filter compatibility
-
-### Qualitative Achievements  
-- **Educational Excellence**: Research-backed connection generation
-- **Production Ready**: Comprehensive testing and validation
-- **Future Proof**: Scalable architecture for continued expansion
-- **User Experience**: Enhanced navigation without cognitive overload
-
----
-
-**Status**: ✅ **COMPLETE & DEPLOYED**  
-**Next Steps**: System is production-ready and actively improving student learning outcomes in PDF builds.
-
-*Generated by Claude Code - Cross-Reference System Integration Project*

tools/scripts/cross_refs/QUALITY_ANALYSIS_REPORT.md

@@ -1,72 +0,0 @@
-# Cross-Reference Quality Analysis Report
-**Total Connections**: 1083
-
-## 📊 Connection Distribution
-### Connections by Chapter
-- **benchmarking**: 77 connections
-- **data_engineering**: 70 connections
-- **frameworks**: 70 connections
-- **hw_acceleration**: 70 connections
-- **conclusion**: 64 connections
-- **workflow**: 63 connections
-- **training**: 63 connections
-- **efficient_ai**: 63 connections
-- **optimizations**: 63 connections
-- **introduction**: 60 connections
-
-### Section Connection Density
-- **Average**: 5.9 connections/section
-- **Median**: 7.0 connections/section
-- **Max**: 7 connections
-- **Min**: 1 connections
-
-### Connection Type Distribution
-- **Background**: 587 (54.2%)
-- **Preview**: 496 (45.8%)
-
-### Similarity Score Analysis
-- **Average**: 0.409
-- **Median**: 0.412
-- **Low Quality (<0.3)**: 106 connections
-
-## 🔍 Quality Issues Identified
-
-### Weak Connections (similarity < 0.3): 106
-- sec-introduction-ai-pervasiveness-8891 → sec-ml-systems-overview-db10 (similarity: 0.266)
-- sec-introduction-ai-pervasiveness-8891 → sec-dl-primer-overview-9e60 (similarity: 0.255)
-- sec-introduction-ai-pervasiveness-8891 → sec-ai-frameworks-overview-f051 (similarity: 0.231)
-- sec-introduction-ai-pervasiveness-8891 → sec-ai-training-overview-00a3 (similarity: 0.228)
-- sec-introduction-ai-pervasiveness-8891 → sec-ai-workflow-overview-97fb (similarity: 0.237)
-
-### Circular References: 18
-- sec-introduction-ai-pervasiveness-8891->sec-ml-systems-overview-db10 ↔ sec-ml-systems-overview-db10->sec-introduction-ai-pervasiveness-8891
-- sec-introduction-ai-pervasiveness-8891->sec-dl-primer-overview-9e60 ↔ sec-dl-primer-overview-9e60->sec-introduction-ai-pervasiveness-8891
-- sec-introduction-ai-pervasiveness-8891->sec-ai-frameworks-overview-f051 ↔ sec-ai-frameworks-overview-f051->sec-introduction-ai-pervasiveness-8891
-- sec-introduction-ai-pervasiveness-8891->sec-ai-training-overview-00a3 ↔ sec-ai-training-overview-00a3->sec-introduction-ai-pervasiveness-8891
-- sec-introduction-ai-pervasiveness-8891->sec-ai-workflow-overview-97fb ↔ sec-ai-workflow-overview-97fb->sec-introduction-ai-pervasiveness-8891
-- sec-ml-systems-overview-db10->sec-dl-primer-overview-9e60 ↔ sec-dl-primer-overview-9e60->sec-ml-systems-overview-db10
-- sec-ml-systems-overview-db10->sec-ai-frameworks-overview-f051 ↔ sec-ai-frameworks-overview-f051->sec-ml-systems-overview-db10
-- sec-ml-systems-overview-db10->sec-ai-training-overview-00a3 ↔ sec-ai-training-overview-00a3->sec-ml-systems-overview-db10
-- sec-ml-systems-overview-db10->sec-ai-workflow-overview-97fb ↔ sec-ai-workflow-overview-97fb->sec-ml-systems-overview-db10
-- sec-dl-primer-overview-9e60->sec-ai-frameworks-overview-f051 ↔ sec-ai-frameworks-overview-f051->sec-dl-primer-overview-9e60
-- sec-dl-primer-overview-9e60->sec-ai-training-overview-00a3 ↔ sec-ai-training-overview-00a3->sec-dl-primer-overview-9e60
-- sec-dl-primer-overview-9e60->sec-efficient-ai-overview-6f6a ↔ sec-efficient-ai-overview-6f6a->sec-dl-primer-overview-9e60
-- sec-dl-primer-overview-9e60->sec-model-optimizations-overview-b523 ↔ sec-model-optimizations-overview-b523->sec-dl-primer-overview-9e60
-- sec-dl-primer-overview-9e60->sec-ai-workflow-overview-97fb ↔ sec-ai-workflow-overview-97fb->sec-dl-primer-overview-9e60
-- sec-ai-frameworks-overview-f051->sec-ai-training-overview-00a3 ↔ sec-ai-training-overview-00a3->sec-ai-frameworks-overview-f051
-- sec-efficient-ai-overview-6f6a->sec-model-optimizations-overview-b523 ↔ sec-model-optimizations-overview-b523->sec-efficient-ai-overview-6f6a
-- sec-ondevice-learning-overview-c195->sec-ai-good-overview-c977 ↔ sec-ai-good-overview-c977->sec-ondevice-learning-overview-c195
-- sec-ondevice-learning-overview-c195->sec-security-privacy-overview-af7c ↔ sec-security-privacy-overview-af7c->sec-ondevice-learning-overview-c195
-
-## 💡 Recommendations for Fine-Tuning
-1. **Remove weak connections** with similarity < 0.3
-2. **Limit sections to 5-6 connections** maximum
-3. **Improve generic explanations** with specific pedagogical value
-4. **Balance connection types** within sections
-5. **Review circular references** for pedagogical value
-
-## 🎯 Proposed Target Metrics
-- **Total Connections**: 800-900 (from current 1,083)
-- **Connections per Section**: 3-5 average, 6 maximum
-- **Minimum Similarity**: 0.35
-- **Connection Type Balance**: No single type >60% per section

tools/scripts/cross_refs/RECIPE.md

@@ -1,236 +0,0 @@
-# Cross-Reference Generation & Integration Recipe
-
-## Overview
-This recipe documents the complete process for generating AI-powered cross-references with explanations and integrating them into the ML Systems textbook.
-
-## Prerequisites
-
-### Software Requirements
-```bash
-# Python dependencies
-pip install sentence-transformers scikit-learn numpy torch pyyaml pypandoc requests
-
-# Ollama for AI explanations
-brew install ollama  # macOS
-# or: curl -fsSL https://ollama.ai/install.sh | sh  # Linux
-
-# Download recommended model (best quality from experiments)
-ollama run llama3.1:8b
-```
-
-### Hardware
-- **GPU recommended** for domain-adapted model training
-- **16GB+ RAM** for processing 93 sections across 19 chapters
-- **SSD storage** for faster model loading
-
-## Step 1: Generate Cross-References with Explanations
-
-### Quick Command (Recommended)
-```bash
-# Generate cross-references with explanations using optimal settings
-python3 ./scripts/cross_refs/cross_refs.py \
-    -g \
-    -m ./scripts/cross_refs/t5-mlsys-domain-adapted/ \
-    -o data/cross_refs.json \
-    -d ./contents/core/ \
-    -t 0.5 \
-    --explain \
-    --ollama-model llama3.1:8b
-```
-
-### Parameters Explained
-- **`-t 0.5`**: Similarity threshold (0.5 = 230 refs, good balance of quality/quantity)
-- **`--ollama-model llama3.1:8b`**: Best quality model from systematic experiments
-- **Domain-adapted model**: `t5-mlsys-domain-adapted/` provides better results than base models
-
-### Alternative Thresholds
-```bash
-# Higher quality, fewer references (92 refs)
-python3 ./scripts/cross_refs/cross_refs.py ... -t 0.6
-
-# More references, lower quality (294 refs)  
-python3 ./scripts/cross_refs/cross_refs.py ... -t 0.4
-
-# Very high quality, very few (36 refs)
-python3 ./scripts/cross_refs/cross_refs.py ... -t 0.65
-```
-
-### Expected Output
-```
-✅ Generated 230 cross-references across 18 files.
-📊 Average similarity: 0.591
-📄 Results saved to: data/cross_refs.json
-```
-
-## Step 2: Quality Evaluation (Optional)
-
-### Evaluate with LLM Judges
-```bash
-# Evaluate sample with Student, TA, Instructor judges
-python3 ./scripts/cross_refs/evaluate_explanations.py \
-    data/cross_refs.json \
-    --sample 20 \
-    --output evaluation_results.json
-```
-
-### Expected Quality Metrics
-- **Target Score**: 3.5+ out of 5.0
-- **Student Judge**: Most accepting (focuses on clarity)
-- **TA Judge**: Most critical (focuses on pedagogy)
-- **Instructor Judge**: Balanced (focuses on academic rigor)
-
-## Step 3: Integration into Book
-
-### Configure Quarto
-Ensure `_quarto.yml` has cross-reference configuration:
-```yaml
-cross-references:
-  file: "data/cross_refs.json"
-  enabled: true
-
-filters:
-  - lua/inject_crossrefs.lua    # Must come before custom-numbered-blocks
-  - custom-numbered-blocks
-  - lua/margin-connections.lua  # Must come after custom-numbered-blocks
-```
-
-### Test with Single Chapter
-```bash
-# Test with introduction only
-quarto render contents/core/introduction/introduction.qmd --to pdf
-```
-
-### Build Full Book
-```bash
-# Render complete book
-quarto render --to pdf
-```
-
-## Step 4: Handle Common Issues
-
-### Float Issues ("Too many unprocessed floats")
-If you get float overflow errors, add to `tex/header-includes.tex`:
-```latex
-\usepackage{placeins}
-\newcommand{\sectionfloatclear}{\FloatBarrier}
-\newcommand{\chapterfloatclear}{\clearpage}
-
-% Flush floats at sections and chapters
-\let\oldsection\section
-\renewcommand{\section}{\sectionfloatclear\oldsection}
-
-\let\oldchapter\chapter  
-\renewcommand{\chapter}{\chapterfloatclear\oldchapter}
-```
-
-### Missing References
-If some cross-references don't resolve:
-```bash
-# Check section IDs are correct
-grep -r "sec-" contents/core/ | head -10
-
-# Regenerate with verbose logging
-python3 ./scripts/cross_refs/cross_refs.py ... --verbose
-```
-
-### Ollama Connection Issues
-```bash
-# Check if Ollama is running
-curl http://localhost:11434/api/tags
-
-# Start Ollama service
-ollama serve
-
-# List available models
-ollama list
-```
-
-## Step 5: Optimization Settings
-
-### Model Selection Priority
-1. **llama3.1:8b** - Best quality (8.0/10 from experiments) ⭐
-2. **qwen2.5:7b** - Fast alternative (7.8/10 quality)
-3. **gemma2:9b** - Good balance
-4. **phi3:3.8b** - High quality but verbose
-
-### Threshold Guidelines
-| Use Case | Threshold | Expected Count | Quality |
-|----------|-----------|----------------|---------|
-| **Recommended** | 0.5 | 230 refs | Good balance |
-| High quality | 0.6 | 92 refs | Excellent |
-| Comprehensive | 0.4 | 294 refs | Acceptable |
-| Elite only | 0.65 | 36 refs | Premium |
-
-## Troubleshooting
-
-### Performance Issues
-- **Slow generation**: Use `qwen2.5:7b` instead of `llama3.1:8b`
-- **Memory issues**: Reduce `--max-suggestions` from 5 to 3
-- **Large output**: Use higher threshold (0.6+)
-
-### Quality Issues
-- **Poor explanations**: Check Ollama model is correct version
-- **Generic text**: Regenerate with different `--seed` value
-- **Wrong direction**: Verify file ordering in `_quarto.yml`
-
-### Build Issues
-- **LaTeX errors**: Check `tex/header-includes.tex` for conflicts
-- **Missing sections**: Verify all `.qmd` files have proper section IDs
-- **Slow builds**: Use `quarto render --cache` for faster rebuilds
-
-## File Structure
-```
-scripts/cross_refs/
-├── cross_refs.py              # Main generation script
-├── evaluate_explanations.py   # LLM judge evaluation
-├── filters.yml               # Content filtering rules
-├── t5-mlsys-domain-adapted/  # Domain-adapted model
-└── RECIPE.md                 # This documentation
-
-data/
-└── cross_refs.json          # Generated cross-references
-
-lua/
-├── inject_crossrefs.lua     # Injection filter
-└── margin-connections.lua   # PDF margin rendering
-```
-
-## Success Metrics
-- ✅ **230 cross-references** generated with threshold 0.5
-- ✅ **3.6+ average quality** from LLM judge evaluation
-- ✅ **Clean PDF build** without float or reference errors
-- ✅ **Margin notes** render correctly in PDF output
-- ✅ **Connection callouts** display properly in HTML
-
-## Maintenance
-
-### Updating Cross-References
-When content changes significantly:
-```bash
-# Regenerate cross-references
-python3 ./scripts/cross_refs/cross_refs.py -g ... 
-
-# Re-evaluate quality
-python3 ./scripts/cross_refs/evaluate_explanations.py ...
-
-# Test build
-quarto render --to pdf
-```
-
-### Model Updates
-When new Ollama models become available:
-```bash
-# Download new model
-ollama run new-model:version
-
-# Test with sample
-python3 ./scripts/cross_refs/cross_refs.py ... --ollama-model new-model:version --sample 10
-
-# Evaluate quality difference
-python3 ./scripts/cross_refs/evaluate_explanations.py ...
-```
-
----
-
-**Last Updated**: July 2025  
-**Tested With**: Quarto 1.5+, Ollama 0.3+, Python 3.8+ 

tools/scripts/cross_refs/REFINEMENT_SUMMARY.md

@@ -1,114 +0,0 @@
-# Cross-Reference System Refinement Summary
-
-## 🎯 Refinement Complete
-
-The cross-reference system has been successfully analyzed, fine-tuned, and optimized for better pedagogical value and reduced cognitive load.
-
-## 📊 Before vs After Comparison
-
-| Metric | Before (Production) | After (Refined) | Improvement |
-|--------|---------------------|-----------------|-------------|
-| **Total Connections** | 1,083 | 637 | -41.2% reduction |
-| **Avg per Section** | 5.9 | 3.7 | Optimal range achieved |
-| **Weak Connections** | 106 | 0 | 100% eliminated |
-| **Min Similarity** | 0.266 | 0.35 | +31.6% quality boost |
-| **Max per Section** | 7 | 5 | Cognitive load reduced |
-
-## 🔍 Quality Improvements
-
-### 1. **Connection Quality**
-- ✅ Removed 265 weak connections (similarity < 0.35)
-- ✅ Eliminated connections with generic explanations
-- ✅ Improved pedagogical value of remaining connections
-
-### 2. **Cognitive Load Management**
-- ✅ Limited sections to maximum 5 connections
-- ✅ Average reduced from 5.9 to 3.7 connections/section
-- ✅ Removed 50 excess connections from overloaded sections
-
-### 3. **Connection Type Balance**
-- ✅ Background: 54.2% → Better balanced
-- ✅ Preview: 45.8% → Better balanced
-- ✅ No section dominated by single connection type
-
-### 4. **Circular References**
-- ✅ Applied 20% quality penalty to circular references
-- ✅ Kept only high-value bidirectional connections
-- ✅ Reduced redundancy while maintaining navigational value
-
-## 📈 Key Metrics Achieved
-
-### Target Goals ✅
-- **Total Connections**: 800-900 → Achieved 637 (even better!)
-- **Connections per Section**: 3-5 average → Achieved 3.7
-- **Maximum per Section**: 6 → Achieved 5
-- **Minimum Similarity**: 0.35 → Achieved 100%
-- **Type Balance**: <60% single type → Achieved
-
-## 🎨 Explanation Improvements
-
-Enhanced explanations now provide specific pedagogical context:
-- Background connections: "Provides foundational understanding of..."
-- Preview connections: "Explores optimization techniques in..."
-- Security/Privacy: "Addresses security implications in..."
-- Ethics/Sustainability: "Considers ethical dimensions through..."
-
-## 🚀 Implementation Status
-
-### Files Updated
-1. **Refined Data**: `/quarto/data/cross_refs_refined.json` (637 connections)
-2. **PDF Config**: Points to refined cross-references
-3. **Quality Report**: Comprehensive analysis available
-
-### Build Testing
-- ✅ PDF build successful with refined connections
-- ✅ HTML build continues without cross-references
-- ✅ No build errors or warnings
-
-## 💡 Impact on Student Experience
-
-### Before (1,083 connections)
-- **Risk**: Cognitive overload with too many connections
-- **Issue**: Some sections had 7+ connections
-- **Problem**: Many weak, unhelpful connections
-
-### After (637 connections)
-- **Benefit**: Focused, high-quality connections only
-- **Improvement**: Manageable 3-4 connections per section
-- **Result**: Each connection adds real pedagogical value
-
-## 📝 Recommendations for Ongoing Maintenance
-
-1. **Regular Quality Checks**
-   - Run quality analyzer quarterly
-   - Monitor average connections per section
-   - Ensure minimum similarity stays above 0.35
-
-2. **Content Updates**
-   - When adding new chapters, aim for 3-5 connections per section
-   - Focus on pedagogical value over quantity
-   - Balance Background and Preview connections
-
-3. **User Feedback Integration**
-   - Collect feedback on connection helpfulness
-   - Adjust thresholds based on student usage data
-   - Consider A/B testing different connection densities
-
-## ✅ Summary
-
-The refined cross-reference system represents a **significant improvement** in pedagogical quality:
-
-- **41.2% reduction** in total connections eliminates noise
-- **100% elimination** of weak connections improves signal
-- **Optimal density** of 3.7 connections/section prevents overload
-- **Enhanced explanations** provide clear learning value
-
-The system now provides **focused, high-quality navigation** that enhances learning without overwhelming students. Each connection serves a clear pedagogical purpose and maintains a minimum quality threshold.
-
----
-
-**Status**: ✅ **REFINEMENT COMPLETE**  
-**Current System**: Refined (637 high-quality connections)  
-**Ready for**: Production deployment in PDF builds
-
-*Generated by Claude Code - Cross-Reference Quality Refinement Project*

tools/scripts/cross_refs/cognitive_load_analysis.json

@@ -1,30 +0,0 @@
-{
-  "total_connections": 816,
-  "chapters_with_connections": 21,
-  "cognitive_load_distribution": {
-    "medium": 466,
-    "high": 26,
-    "low": 324
-  },
-  "connection_type_distribution": {
-    "conceptual_bridge": 458,
-    "optional_deepdive": 26,
-    "progressive_extension": 8,
-    "prerequisite_foundation": 324
-  },
-  "placement_distribution": {
-    "section_transition": 458,
-    "expandable": 26,
-    "section_end": 8,
-    "chapter_start": 324
-  },
-  "optimization_principles": [
-    "prerequisite_foundation",
-    "conceptual_bridge",
-    "progressive_extension",
-    "application_example",
-    "optional_deepdive"
-  ],
-  "generation_date": "2025-09-12 07:39:21",
-  "research_basis": "Cognitive Load Theory 2024, Educational Design Principles, Hyperlink Placement Research"
-}

tools/scripts/cross_refs/cognitive_load_optimized_generator.py

@@ -13,7 +13,7 @@ Key principles implemented:
 4. Progressive Disclosure: Reveal information as needed
 5. Hyperlink Placement Optimization: Strategic placement for learning outcomes
 
-Author: Claude Code based on 2024 educational research
+Based on 2024 educational research
 """
 
 import os

tools/scripts/cross_refs/experimental_framework.py

@@ -4,12 +4,10 @@ Comprehensive Cross-Reference Experimental Framework
 
 This script runs multiple experiments to optimize cross-reference generation:
 1. Section-level granularity analysis
-2. Bidirectional connection testing  
+2. Bidirectional connection testing
 3. Connection density optimization
 4. Pedagogical connection type enhancement
 5. Multi-placement strategy evaluation
-
-Author: Claude Code
 """
 
 import os

tools/scripts/cross_refs/experimental_results.json

@@ -1,662 +0,0 @@
-{
-  "experiment_1": {
-    "total_sections": 200,
-    "total_connections": 6024,
-    "coverage": 1.0,
-    "avg_connections_per_section": 30.12,
-    "sample_connections": {
-      "introduction:sec-introduction-ai-pervasiveness-8891": [
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ai-ml-basics-fa82",
-          "target_title": "AI and ML Basics",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ai-evolution-8ff4",
-          "target_title": "AI Evolution",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ml-systems-engineering-e9d8",
-          "target_title": "ML Systems Engineering",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-defining-ml-systems-bf7d",
-          "target_title": "Defining ML Systems",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-lifecycle-ml-systems-6194",
-          "target_title": "Lifecycle of ML Systems",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ml-systems-wild-8f2f",
-          "target_title": "ML Systems in the Wild",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ml-systems-impact-lifecycle-fb60",
-          "target_title": "ML Systems Impact on Lifecycle",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-practical-applications-0728",
-          "target_title": "Practical Applications",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-challenges-ml-systems-7167",
-          "target_title": "Challenges in ML Systems",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-looking-ahead-34a3",
-          "target_title": "Looking Ahead",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-book-structure-learning-path-f3ea",
-          "target_title": "Book Structure and Learning Path",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        }
-      ],
-      "introduction:sec-introduction-ai-ml-basics-fa82": [
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ai-pervasiveness-8891",
-          "target_title": "AI Pervasiveness",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ai-evolution-8ff4",
-          "target_title": "AI Evolution",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ml-systems-engineering-e9d8",
-          "target_title": "ML Systems Engineering",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-defining-ml-systems-bf7d",
-          "target_title": "Defining ML Systems",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-lifecycle-ml-systems-6194",
-          "target_title": "Lifecycle of ML Systems",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ml-systems-wild-8f2f",
-          "target_title": "ML Systems in the Wild",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ml-systems-impact-lifecycle-fb60",
-          "target_title": "ML Systems Impact on Lifecycle",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-practical-applications-0728",
-          "target_title": "Practical Applications",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-challenges-ml-systems-7167",
-          "target_title": "Challenges in ML Systems",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-looking-ahead-34a3",
-          "target_title": "Looking Ahead",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-book-structure-learning-path-f3ea",
-          "target_title": "Book Structure and Learning Path",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        }
-      ],
-      "introduction:sec-introduction-ai-evolution-8ff4": [
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ai-pervasiveness-8891",
-          "target_title": "AI Pervasiveness",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ai-ml-basics-fa82",
-          "target_title": "AI and ML Basics",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ml-systems-engineering-e9d8",
-          "target_title": "ML Systems Engineering",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-defining-ml-systems-bf7d",
-          "target_title": "Defining ML Systems",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-lifecycle-ml-systems-6194",
-          "target_title": "Lifecycle of ML Systems",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ml-systems-wild-8f2f",
-          "target_title": "ML Systems in the Wild",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-ml-systems-impact-lifecycle-fb60",
-          "target_title": "ML Systems Impact on Lifecycle",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-practical-applications-0728",
-          "target_title": "Practical Applications",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-challenges-ml-systems-7167",
-          "target_title": "Challenges in ML Systems",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-looking-ahead-34a3",
-          "target_title": "Looking Ahead",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        },
-        {
-          "target_chapter": "introduction",
-          "target_section": "sec-introduction-book-structure-learning-path-f3ea",
-          "target_title": "Book Structure and Learning Path",
-          "strength": 0.3517857142857145,
-          "concepts": [
-            "machine learning systems engineering",
-            "ai pervasiveness",
-            "ai and ml fundamentals",
-            "ai evolution and history",
-            "ai winters"
-          ]
-        }
-      ]
-    },
-    "execution_time": 1.4926798343658447
-  },
-  "experiment_2": {
-    "forward_connections": 8,
-    "backward_connections": 8,
-    "bidirectional_ratio": 1.0,
-    "sample_forward": {
-      "introduction": [],
-      "ml_systems": [
-        {
-          "target": "ondevice_learning",
-          "type": "forward",
-          "strength": 0.031578947368421054,
-          "concepts": [
-            "mobile ml",
-            "tinyml",
-            "federated learning"
-          ]
-        }
-      ],
-      "dl_primer": []
-    },
-    "sample_backward": {
-      "introduction": [],
-      "ml_systems": [
-        {
-          "source": "ondevice_learning",
-          "type": "backward",
-          "strength": 0.031578947368421054,
-          "concepts": [
-            "mobile ml",
-            "tinyml",
-            "federated learning"
-          ]
-        }
-      ],
-      "dl_primer": []
-    },
-    "execution_time": 2.8810579776763916
-  },
-  "experiment_3": {
-    "threshold_analysis": {
-      "0.01": {
-        "total_connections": 26,
-        "coverage": 0.8181818181818182,
-        "avg_per_chapter": 1.1818181818181819,
-        "quality_score": 0.21272727272727274
-      },
-      "0.02": {
-        "total_connections": 12,
-        "coverage": 0.45454545454545453,
-        "avg_per_chapter": 0.5454545454545454,
-        "quality_score": 0.05454545454545454
-      },
-      "0.03": {
-        "total_connections": 8,
-        "coverage": 0.3181818181818182,
-        "avg_per_chapter": 0.36363636363636365,
-        "quality_score": 0.025454545454545455
-      },
-      "0.05": {
-        "total_connections": 2,
-        "coverage": 0.09090909090909091,
-        "avg_per_chapter": 0.09090909090909091,
-        "quality_score": 0.0018181818181818182
-      },
-      "0.08": {
-        "total_connections": 0,
-        "coverage": 0.0,
-        "avg_per_chapter": 0.0,
-        "quality_score": 0.0
-      },
-      "0.1": {
-        "total_connections": 0,
-        "coverage": 0.0,
-        "avg_per_chapter": 0.0,
-        "quality_score": 0.0
-      }
-    },
-    "optimal_threshold": 0.01,
-    "optimal_stats": {
-      "total_connections": 26,
-      "coverage": 0.8181818181818182,
-      "avg_per_chapter": 1.1818181818181819,
-      "quality_score": 0.21272727272727274
-    },
-    "execution_time": 17.24936294555664
-  },
-  "experiment_4": {
-    "connection_types": [
-      "foundation",
-      "prerequisite",
-      "builds_on",
-      "implements",
-      "applies",
-      "extends",
-      "relates",
-      "contrasts",
-      "example"
-    ],
-    "type_distribution": {
-      "prerequisite": 1,
-      "builds_on": 1
-    },
-    "type_percentages": {
-      "prerequisite": 50.0,
-      "builds_on": 50.0
-    },
-    "total_connections": 2,
-    "sample_by_type": {
-      "prerequisite": [
-        {
-          "source": "frontiers",
-          "target": "emerging_topics",
-          "strength": 0.05333333333333333,
-          "concepts": [
-            "technology convergence",
-            "research frontiers",
-            "future applications"
-          ]
-        }
-      ],
-      "builds_on": [
-        {
-          "source": "emerging_topics",
-          "target": "frontiers",
-          "strength": 0.05333333333333333,
-          "concepts": [
-            "technology convergence",
-            "future applications",
-            "research frontiers"
-          ]
-        }
-      ]
-    },
-    "execution_time": 2.6563971042633057
-  },
-  "experiment_5_introduction": {
-    "chapter_start": {
-      "locations": 1,
-      "avg_connections_per_location": 3,
-      "total_connections": 3,
-      "pedagogical_impact": "High - sets context",
-      "readability_impact": "Low - doesn't clutter"
-    },
-    "section_start": {
-      "locations": 12,
-      "avg_connections_per_location": 2,
-      "total_connections": 24,
-      "pedagogical_impact": "Very High - contextual",
-      "readability_impact": "Medium - some clutter"
-    },
-    "contextual_inline": {
-      "locations": 36,
-      "avg_connections_per_location": 1,
-      "total_connections": 36,
-      "pedagogical_impact": "Medium - can be distracting",
-      "readability_impact": "High - significant clutter"
-    }
-  },
-  "experiment_5_ml_systems": {
-    "chapter_start": {
-      "locations": 1,
-      "avg_connections_per_location": 3,
-      "total_connections": 3,
-      "pedagogical_impact": "High - sets context",
-      "readability_impact": "Low - doesn't clutter"
-    },
-    "section_start": {
-      "locations": 10,
-      "avg_connections_per_location": 2,
-      "total_connections": 20,
-      "pedagogical_impact": "Very High - contextual",
-      "readability_impact": "Medium - some clutter"
-    },
-    "contextual_inline": {
-      "locations": 30,
-      "avg_connections_per_location": 1,
-      "total_connections": 30,
-      "pedagogical_impact": "Medium - can be distracting",
-      "readability_impact": "High - significant clutter"
-    }
-  },
-  "experiment_5_dl_primer": {
-    "chapter_start": {
-      "locations": 1,
-      "avg_connections_per_location": 3,
-      "total_connections": 3,
-      "pedagogical_impact": "High - sets context",
-      "readability_impact": "Low - doesn't clutter"
-    },
-    "section_start": {
-      "locations": 8,
-      "avg_connections_per_location": 2,
-      "total_connections": 16,
-      "pedagogical_impact": "Very High - contextual",
-      "readability_impact": "Medium - some clutter"
-    },
-    "contextual_inline": {
-      "locations": 24,
-      "avg_connections_per_location": 1,
-      "total_connections": 24,
-      "pedagogical_impact": "Medium - can be distracting",
-      "readability_impact": "High - significant clutter"
-    }
-  },
-  "experiment_5_summary": {
-    "strategies_evaluated": [
-      "chapter_start",
-      "section_start",
-      "contextual_inline",
-      "section_end",
-      "mixed_adaptive"
-    ],
-    "recommended_approach": "section_start",
-    "rationale": "Best balance of pedagogical value and readability",
-    "execution_time": 0.002827167510986328
-  }
-}

tools/scripts/cross_refs/production_summary.json

@@ -1,13 +0,0 @@
-{
-  "total_connections": 1146,
-  "chapters_with_connections": 21,
-  "connection_type_distribution": {
-    "foundation": 529,
-    "prerequisite": 106,
-    "extends": 230,
-    "complements": 200,
-    "applies": 81
-  },
-  "generation_date": "2025-09-12 11:30:45",
-  "generator_version": "1.0"
-}

tools/scripts/cross_refs/refined_experimental_results.json

@@ -1,614 +0,0 @@
-{
-  "experiment_a": {
-    "total_sections": 200,
-    "connected_sections": 38,
-    "total_connections": 140,
-    "avg_connections_per_section": 3.6842105263157894,
-    "section_coverage": 0.19,
-    "sample_connections": {
-      "ml_systems:sec-ml-systems-overview-db10": [
-        {
-          "target_chapter": "efficient_ai",
-          "target_section": "sec-efficient-ai-overview-6f6a",
-          "target_title": "Overview",
-          "strength": 0.030272108843537416,
-          "concepts": [
-            "model quantization",
-            "model compression",
-            "energy efficiency"
-          ]
-        },
-        {
-          "target_chapter": "optimizations",
-          "target_section": "sec-model-optimizations-overview-b523",
-          "target_title": "Overview",
-          "strength": 0.027483443708609275,
-          "concepts": [
-            "model quantization",
-            "model compression",
-            "knowledge distillation"
-          ]
-        },
-        {
-          "target_chapter": "ondevice_learning",
-          "target_section": "sec-ondevice-learning-overview-c195",
-          "target_title": "Overview",
-          "strength": 0.038698630136986295,
-          "concepts": [
-            "model compression",
-            "energy efficiency",
-            "latency optimization"
-          ]
-        }
-      ],
-      "ml_systems:sec-ml-systems-cloudbased-machine-learning-7606": [
-        {
-          "target_chapter": "efficient_ai",
-          "target_section": "sec-efficient-ai-overview-6f6a",
-          "target_title": "Overview",
-          "strength": 0.030272108843537416,
-          "concepts": [
-            "model quantization",
-            "model compression",
-            "energy efficiency"
-          ]
-        },
-        {
-          "target_chapter": "optimizations",
-          "target_section": "sec-model-optimizations-overview-b523",
-          "target_title": "Overview",
-          "strength": 0.027483443708609275,
-          "concepts": [
-            "model quantization",
-            "model compression",
-            "knowledge distillation"
-          ]
-        },
-        {
-          "target_chapter": "ondevice_learning",
-          "target_section": "sec-ondevice-learning-overview-c195",
-          "target_title": "Overview",
-          "strength": 0.038698630136986295,
-          "concepts": [
-            "model compression",
-            "energy efficiency",
-            "latency optimization"
-          ]
-        }
-      ]
-    },
-    "execution_time": 2.8242580890655518
-  },
-  "experiment_b": {
-    "threshold_analysis": {
-      "0.005": {
-        "total_connections": 238,
-        "coverage": 1.0,
-        "avg_quality": 0.5451270326397196,
-        "composite_score": 0.8635381097919158,
-        "connections_per_chapter": 10.818181818181818
-      },
-      "0.008": {
-        "total_connections": 202,
-        "coverage": 1.0,
-        "avg_quality": 0.5556839742750035,
-        "composite_score": 0.866705192282501,
-        "connections_per_chapter": 9.181818181818182
-      },
-      "0.01": {
-        "total_connections": 156,
-        "coverage": 1.0,
-        "avg_quality": 0.594509053730751,
-        "composite_score": 0.8783527161192253,
-        "connections_per_chapter": 7.090909090909091
-      },
-      "0.015": {
-        "total_connections": 106,
-        "coverage": 0.9545454545454546,
-        "avg_quality": 0.6094947329054752,
-        "composite_score": 0.8646666016898245,
-        "connections_per_chapter": 4.818181818181818
-      },
-      "0.02": {
-        "total_connections": 70,
-        "coverage": 0.8636363636363636,
-        "avg_quality": 0.6137011637536383,
-        "composite_score": 0.829564894580637,
-        "connections_per_chapter": 3.1818181818181817
-      },
-      "0.025": {
-        "total_connections": 52,
-        "coverage": 0.8181818181818182,
-        "avg_quality": 0.629927244840484,
-        "composite_score": 0.8162509007248725,
-        "connections_per_chapter": 2.3636363636363638
-      },
-      "0.03": {
-        "total_connections": 36,
-        "coverage": 0.5909090909090909,
-        "avg_quality": 0.6465534751229627,
-        "composite_score": 0.6463296789005252,
-        "connections_per_chapter": 1.6363636363636365
-      }
-    },
-    "optimal_threshold": 0.01,
-    "optimal_stats": {
-      "total_connections": 156,
-      "coverage": 1.0,
-      "avg_quality": 0.594509053730751,
-      "composite_score": 0.8783527161192253,
-      "connections_per_chapter": 7.090909090909091
-    },
-    "execution_time": 19.94976496696472
-  },
-  "experiment_c": {
-    "connection_types_found": [
-      "advanced_application",
-      "theory_to_practice",
-      "peer_concept",
-      "sequential_progression",
-      "strong_conceptual_link",
-      "optimization_related",
-      "builds_on_foundation",
-      "practice_to_optimization",
-      "topical_connection",
-      "systems_related",
-      "complementary_approach"
-    ],
-    "type_distribution": {
-      "advanced_application": 6,
-      "theory_to_practice": 2,
-      "peer_concept": 14,
-      "sequential_progression": 9,
-      "strong_conceptual_link": 1,
-      "optimization_related": 1,
-      "builds_on_foundation": 25,
-      "practice_to_optimization": 3,
-      "topical_connection": 2,
-      "systems_related": 1,
-      "complementary_approach": 6
-    },
-    "type_percentages": {
-      "advanced_application": 8.571428571428571,
-      "theory_to_practice": 2.857142857142857,
-      "peer_concept": 20.0,
-      "sequential_progression": 12.857142857142856,
-      "strong_conceptual_link": 1.4285714285714286,
-      "optimization_related": 1.4285714285714286,
-      "builds_on_foundation": 35.714285714285715,
-      "practice_to_optimization": 4.285714285714286,
-      "topical_connection": 2.857142857142857,
-      "systems_related": 1.4285714285714286,
-      "complementary_approach": 8.571428571428571
-    },
-    "total_connections": 70,
-    "level_consistency": 0.6857142857142857,
-    "sample_by_type": {
-      "advanced_application": [
-        {
-          "source": "ml_systems",
-          "target": "efficient_ai",
-          "strength": 0.030272108843537416,
-          "concepts": [
-            "model quantization",
-            "model compression",
-            "energy efficiency"
-          ],
-          "source_level": 1,
-          "target_level": 4
-        },
-        {
-          "source": "ml_systems",
-          "target": "optimizations",
-          "strength": 0.027483443708609275,
-          "concepts": [
-            "model quantization",
-            "model compression",
-            "knowledge distillation"
-          ],
-          "source_level": 1,
-          "target_level": 4
-        }
-      ],
-      "theory_to_practice": [
-        {
-          "source": "dl_primer",
-          "target": "frameworks",
-          "strength": 0.036,
-          "concepts": [
-            "backpropagation",
-            "computational graph",
-            "gradient computation"
-          ],
-          "source_level": 2,
-          "target_level": 3
-        },
-        {
-          "source": "dl_primer",
-          "target": "training",
-          "strength": 0.048999999999999995,
-          "concepts": [
-            "backpropagation",
-            "gradient descent",
-            "activation functions"
-          ],
-          "source_level": 2,
-          "target_level": 3
-        }
-      ],
-      "peer_concept": [
-        {
-          "source": "workflow",
-          "target": "data_engineering",
-          "strength": 0.04685534591194969,
-          "concepts": [
-            "problem definition",
-            "data versioning",
-            "feature engineering"
-          ],
-          "source_level": 2,
-          "target_level": 2
-        },
-        {
-          "source": "data_engineering",
-          "target": "workflow",
-          "strength": 0.04685534591194969,
-          "concepts": [
-            "data versioning",
-            "data drift",
-            "systematic problem definition"
-          ],
-          "source_level": 2,
-          "target_level": 2
-        }
-      ],
-      "sequential_progression": [
-        {
-          "source": "workflow",
-          "target": "frameworks",
-          "strength": 0.0329192546583851,
-          "concepts": [
-            "model versioning",
-            "performance optimization",
-            "scalability planning"
-          ],
-          "source_level": 2,
-          "target_level": 3
-        },
-        {
-          "source": "workflow",
-          "target": "benchmarking",
-          "strength": 0.027678571428571424,
-          "concepts": [
-            "a/b testing",
-            "cross-validation",
-            "model selection"
-          ],
-          "source_level": 2,
-          "target_level": 3
-        }
-      ],
-      "strong_conceptual_link": [
-        {
-          "source": "workflow",
-          "target": "ops",
-          "strength": 0.08397435897435895,
-          "concepts": [
-            "mlops (machine learning operations)",
-            "experiment tracking",
-            "model versioning"
-          ],
-          "source_level": 2,
-          "target_level": 4
-        }
-      ],
-      "optimization_related": [
-        {
-          "source": "data_engineering",
-          "target": "ops",
-          "strength": 0.026988636363636364,
-          "concepts": [
-            "metadata management",
-            "performance optimization",
-            "compliance management"
-          ],
-          "source_level": 2,
-          "target_level": 4
-        }
-      ],
-      "builds_on_foundation": [
-        {
-          "source": "frameworks",
-          "target": "dl_primer",
-          "strength": 0.036000000000000004,
-          "concepts": [
-            "computational graph",
-            "gradient computation",
-            "backpropagation"
-          ],
-          "source_level": 3,
-          "target_level": 2
-        },
-        {
-          "source": "frameworks",
-          "target": "workflow",
-          "strength": 0.0329192546583851,
-          "concepts": [
-            "model versioning",
-            "scalability planning",
-            "performance optimization"
-          ],
-          "source_level": 3,
-          "target_level": 2
-        }
-      ],
-      "practice_to_optimization": [
-        {
-          "source": "frameworks",
-          "target": "efficient_ai",
-          "strength": 0.032848837209302324,
-          "concepts": [
-            "model quantization",
-            "computer vision",
-            "natural language processing"
-          ],
-          "source_level": 3,
-          "target_level": 4
-        },
-        {
-          "source": "frameworks",
-          "target": "optimizations",
-          "strength": 0.021067415730337078,
-          "concepts": [
-            "model quantization",
-            "computer vision",
-            "natural language processing"
-          ],
-          "source_level": 3,
-          "target_level": 4
-        }
-      ],
-      "topical_connection": [
-        {
-          "source": "training",
-          "target": "ondevice_learning",
-          "strength": 0.045953757225433524,
-          "concepts": [
-            "federated learning",
-            "transfer learning",
-            "curriculum learning"
-          ],
-          "source_level": 3,
-          "target_level": 5
-        },
-        {
-          "source": "benchmarking",
-          "target": "ondevice_learning",
-          "strength": 0.021703296703296706,
-          "concepts": [
-            "performance profiling",
-            "cross-validation",
-            "latency analysis"
-          ],
-          "source_level": 3,
-          "target_level": 5
-        }
-      ],
-      "systems_related": [
-        {
-          "source": "efficient_ai",
-          "target": "emerging_topics",
-          "strength": 0.022839506172839506,
-          "concepts": [
-            "evolutionary algorithms",
-            "few-shot learning",
-            "continual learning"
-          ],
-          "source_level": 4,
-          "target_level": 6
-        }
-      ],
-      "complementary_approach": [
-        {
-          "source": "responsible_ai",
-          "target": "ai_for_good",
-          "strength": 0.026666666666666665,
-          "concepts": [
-            "participatory design",
-            "human-centered design",
-            "monitoring and evaluation"
-          ],
-          "source_level": 5,
-          "target_level": 5
-        },
-        {
-          "source": "ai_for_good",
-          "target": "responsible_ai",
-          "strength": 0.026666666666666665,
-          "concepts": [
-            "educational technology",
-            "smart cities",
-            "human-centered design"
-          ],
-          "source_level": 5,
-          "target_level": 5
-        }
-      ]
-    },
-    "execution_time": 2.9256129264831543
-  },
-  "experiment_d": {
-    "forward_connections": 45,
-    "backward_connections": 44,
-    "asymmetry_ratio": 1.0227272727272727,
-    "asymmetric_examples": [
-      {
-        "chapter": "privacy_security",
-        "forward_count": 1,
-        "backward_count": 0,
-        "asymmetry_ratio": 10.0
-      },
-      {
-        "chapter": "benchmarking",
-        "forward_count": 0,
-        "backward_count": 2,
-        "asymmetry_ratio": 0.0
-      },
-      {
-        "chapter": "emerging_topics",
-        "forward_count": 2,
-        "backward_count": 1,
-        "asymmetry_ratio": 1.8181818181818181
-      },
-      {
-        "chapter": "ondevice_learning",
-        "forward_count": 7,
-        "backward_count": 5,
-        "asymmetry_ratio": 1.3725490196078431
-      },
-      {
-        "chapter": "efficient_ai",
-        "forward_count": 3,
-        "backward_count": 4,
-        "asymmetry_ratio": 0.7317073170731708
-      }
-    ],
-    "sample_forward": {
-      "ml_systems": [
-        {
-          "target": "data_engineering",
-          "strength": 0.023013698630136983,
-          "type": "leads_to",
-          "concepts": [
-            "recommendation systems",
-            "fraud detection",
-            "autonomous vehicles"
-          ]
-        },
-        {
-          "target": "efficient_ai",
-          "strength": 0.024217687074829936,
-          "type": "leads_to",
-          "concepts": [
-            "model quantization",
-            "model compression",
-            "energy efficiency"
-          ]
-        }
-      ],
-      "dl_primer": [
-        {
-          "target": "frameworks",
-          "strength": 0.043199999999999995,
-          "type": "leads_to",
-          "concepts": [
-            "backpropagation",
-            "computational graph",
-            "gradient computation"
-          ]
-        },
-        {
-          "target": "training",
-          "strength": 0.05879999999999999,
-          "type": "leads_to",
-          "concepts": [
-            "backpropagation",
-            "gradient descent",
-            "activation functions"
-          ]
-        }
-      ],
-      "workflow": [
-        {
-          "target": "data_engineering",
-          "strength": 0.028113207547169814,
-          "type": "leads_to",
-          "concepts": [
-            "problem definition",
-            "data versioning",
-            "feature engineering"
-          ]
-        },
-        {
-          "target": "frameworks",
-          "strength": 0.039503105590062114,
-          "type": "leads_to",
-          "concepts": [
-            "model versioning",
-            "performance optimization",
-            "scalability planning"
-          ]
-        }
-      ]
-    },
-    "sample_backward": {
-      "training": [
-        {
-          "source": "dl_primer",
-          "strength": 0.024499999999999997,
-          "type": "builds_on",
-          "concepts": [
-            "backpropagation",
-            "gradient descent",
-            "activation functions"
-          ]
-        },
-        {
-          "source": "frameworks",
-          "strength": 0.0286144578313253,
-          "type": "builds_on",
-          "concepts": [
-            "tensor operations",
-            "automatic differentiation",
-            "computational graph"
-          ]
-        }
-      ],
-      "data_engineering": [
-        {
-          "source": "workflow",
-          "strength": 0.023427672955974845,
-          "type": "builds_on",
-          "concepts": [
-            "problem definition",
-            "data versioning",
-            "feature engineering"
-          ]
-        },
-        {
-          "source": "frameworks",
-          "strength": 0.025697674418604648,
-          "type": "builds_on",
-          "concepts": [
-            "performance optimization",
-            "computer vision",
-            "natural language processing"
-          ]
-        }
-      ],
-      "ops": [
-        {
-          "source": "workflow",
-          "strength": 0.04198717948717948,
-          "type": "builds_on",
-          "concepts": [
-            "mlops (machine learning operations)",
-            "experiment tracking",
-            "model versioning"
-          ]
-        },
-        {
-          "source": "privacy_security",
-          "strength": 0.021195652173913043,
-          "type": "builds_on",
-          "concepts": [
-            "incident response",
-            "financial services",
-            "edge computing"
-          ]
-        }
-      ]
-    },
-    "execution_time": 3.056798219680786
-  }
-}

tools/scripts/utilities/validate_epub.py

@@ -0,0 +1,409 @@
+#!/usr/bin/env python3
+"""
+EPUB Validator Script
+
+Validates EPUB files for common issues including:
+- XML parsing errors (double-hyphen in comments)
+- CSS variable issues (--variable syntax)
+- Malformed HTML/XHTML
+- Missing required files
+- Structural validation
+
+Uses epubcheck (official EPUB validator) if available, with custom checks for project-specific issues.
+
+Installation:
+    # Install epubcheck (recommended)
+    brew install epubcheck  # macOS
+    # OR download from: https://github.com/w3c/epubcheck/releases
+
+Usage:
+    python3 validate_epub.py <path_to_epub_file>
+    python3 validate_epub.py quarto/_build/epub/Machine-Learning-Systems.epub
+    python3 validate_epub.py --quick <path_to_epub_file>  # Skip epubcheck
+"""
+
+import sys
+import zipfile
+import re
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import List, Tuple, Dict
+import tempfile
+import shutil
+import subprocess
+import json
+
+
+class EPUBValidator:
+    """Validates EPUB files for common issues."""
+
+    def __init__(self, epub_path: str, use_epubcheck: bool = True):
+        self.epub_path = Path(epub_path)
+        self.errors: List[Tuple[str, str, str]] = []  # (severity, category, message)
+        self.warnings: List[Tuple[str, str, str]] = []
+        self.temp_dir = None
+        self.use_epubcheck = use_epubcheck
+
+    def validate(self) -> bool:
+        """Run all validation checks. Returns True if no errors found."""
+        print(f"🔍 Validating EPUB: {self.epub_path.name}\n")
+
+        if not self.epub_path.exists():
+            self._add_error("CRITICAL", "File", f"EPUB file not found: {self.epub_path}")
+            return False
+
+        # Run epubcheck first if available
+        if self.use_epubcheck:
+            self._run_epubcheck()
+
+        # Extract EPUB to temp directory
+        self.temp_dir = tempfile.mkdtemp()
+        try:
+            with zipfile.ZipFile(self.epub_path, 'r') as zip_ref:
+                zip_ref.extractall(self.temp_dir)
+        except zipfile.BadZipFile:
+            self._add_error("CRITICAL", "Structure", "Invalid ZIP/EPUB file")
+            return False
+
+        # Run custom validation checks (project-specific)
+        print("\n📋 Running custom validation checks...")
+        self._check_mimetype()
+        self._check_container_xml()
+        self._check_css_variables()
+        self._check_xml_comments()
+        self._check_common_xhtml_errors()
+        self._check_xhtml_validity()
+        self._check_opf_structure()
+
+        # Print results
+        self._print_results()
+
+        # Cleanup
+        if self.temp_dir:
+            shutil.rmtree(self.temp_dir)
+
+        return len(self.errors) == 0
+
+    def _add_error(self, severity: str, category: str, message: str):
+        """Add an error to the list."""
+        self.errors.append((severity, category, message))
+
+    def _add_warning(self, severity: str, category: str, message: str):
+        """Add a warning to the list."""
+        self.warnings.append((severity, category, message))
+
+    def _run_epubcheck(self):
+        """Run epubcheck validator if available."""
+        print("🔧 Running epubcheck (official EPUB validator)...\n")
+
+        try:
+            # Try to run epubcheck
+            result = subprocess.run(
+                ['epubcheck', '--json', '-', str(self.epub_path)],
+                capture_output=True,
+                text=True,
+                timeout=120
+            )
+
+            if result.returncode == 0:
+                print("✅ epubcheck: PASS\n")
+                return
+
+            # Parse JSON output
+            try:
+                output = json.loads(result.stdout) if result.stdout else {}
+                messages = output.get('messages', [])
+
+                error_count = 0
+                warning_count = 0
+
+                for msg in messages:
+                    severity = msg.get('severity', 'INFO')
+                    message_text = msg.get('message', 'Unknown error')
+                    locations = msg.get('locations', [])
+
+                    location_str = ""
+                    if locations:
+                        loc = locations[0]
+                        path = loc.get('path', '')
+                        line = loc.get('line', '')
+                        col = loc.get('column', '')
+                        location_str = f"{path}:{line}:{col}" if line else path
+
+                    full_message = f"{location_str}: {message_text}" if location_str else message_text
+
+                    if severity == 'ERROR' or severity == 'FATAL':
+                        self._add_error("ERROR", "epubcheck", full_message)
+                        error_count += 1
+                    elif severity == 'WARNING':
+                        self._add_warning("WARNING", "epubcheck", full_message)
+                        warning_count += 1
+
+                print(f"❌ epubcheck found {error_count} errors, {warning_count} warnings\n")
+
+            except json.JSONDecodeError:
+                # Fallback to text parsing
+                if result.stderr:
+                    print(f"⚠️  epubcheck output (text mode):\n{result.stderr}\n")
+                    self._add_warning("WARNING", "epubcheck", "Could not parse JSON output")
+
+        except FileNotFoundError:
+            print("⚠️  epubcheck not found. Install with: brew install epubcheck")
+            print("   Skipping official EPUB validation.\n")
+        except subprocess.TimeoutExpired:
+            self._add_error("ERROR", "epubcheck", "Validation timed out after 120 seconds")
+        except Exception as e:
+            print(f"⚠️  Could not run epubcheck: {e}\n")
+
+    def _check_mimetype(self):
+        """Check for valid mimetype file."""
+        mimetype_path = Path(self.temp_dir) / "mimetype"
+        if not mimetype_path.exists():
+            self._add_error("ERROR", "Structure", "Missing mimetype file")
+            return
+
+        content = mimetype_path.read_text().strip()
+        if content != "application/epub+zip":
+            self._add_error("ERROR", "Structure", f"Invalid mimetype: {content}")
+
+    def _check_container_xml(self):
+        """Check for valid META-INF/container.xml."""
+        container_path = Path(self.temp_dir) / "META-INF" / "container.xml"
+        if not container_path.exists():
+            self._add_error("ERROR", "Structure", "Missing META-INF/container.xml")
+            return
+
+        try:
+            tree = ET.parse(container_path)
+            root = tree.getroot()
+            # Check for rootfile element
+            rootfiles = root.findall(".//{urn:oasis:names:tc:opendocument:xmlns:container}rootfile")
+            if not rootfiles:
+                self._add_error("ERROR", "Structure", "No rootfile found in container.xml")
+        except ET.ParseError as e:
+            self._add_error("ERROR", "XML", f"Invalid container.xml: {e}")
+
+    def _check_css_variables(self):
+        """Check CSS files for problematic CSS custom properties."""
+        print("📝 Checking CSS files for CSS variables...")
+
+        css_files = list(Path(self.temp_dir).rglob("*.css"))
+
+        for css_file in css_files:
+            rel_path = css_file.relative_to(self.temp_dir)
+            content = css_file.read_text()
+
+            # Check for CSS variable declarations (--variable-name)
+            var_declarations = re.findall(r'^\s*(--[\w-]+)\s*:', content, re.MULTILINE)
+            if var_declarations:
+                self._add_error("ERROR", "CSS",
+                    f"{rel_path}: Found CSS variable declarations: {', '.join(var_declarations[:5])}")
+
+            # Check for CSS variable usage (var(--variable-name))
+            var_usage = re.findall(r'var\((--[\w-]+)\)', content)
+            if var_usage:
+                self._add_error("ERROR", "CSS",
+                    f"{rel_path}: Found CSS variable usage: {', '.join(set(var_usage[:5]))}")
+
+            # Count total double-hyphens (for reference)
+            double_hyphen_count = content.count('--')
+            if double_hyphen_count > 0:
+                # Check if they're only in comments
+                without_comments = re.sub(r'/\*.*?\*/', '', content, flags=re.DOTALL)
+                double_hyphens_in_code = without_comments.count('--')
+
+                if double_hyphens_in_code > 0:
+                    self._add_warning("WARNING", "CSS",
+                        f"{rel_path}: Found {double_hyphens_in_code} double-hyphens outside comments")
+                else:
+                    print(f"  ✓ {rel_path}: {double_hyphen_count} double-hyphens (all in comments)")
+
+    def _check_xml_comments(self):
+        """Check for XML comment violations (double-hyphen in comments)."""
+        print("\n📝 Checking for XML comment violations...")
+
+        xml_files = list(Path(self.temp_dir).rglob("*.xhtml")) + \
+                    list(Path(self.temp_dir).rglob("*.xml")) + \
+                    list(Path(self.temp_dir).rglob("*.opf"))
+
+        # Pattern to find comments with double-hyphens inside them
+        # XML spec prohibits -- inside comments
+        comment_pattern = re.compile(r'<!--.*?--.*?-->', re.DOTALL)
+
+        for xml_file in xml_files:
+            rel_path = xml_file.relative_to(self.temp_dir)
+            try:
+                content = xml_file.read_text()
+                matches = comment_pattern.findall(content)
+
+                if matches:
+                    # Find line numbers
+                    lines = content.split('\n')
+                    for i, line in enumerate(lines, 1):
+                        if '--' in line and '<!--' in content[:content.index(line) if line in content else 0]:
+                            self._add_error("ERROR", "XML",
+                                f"{rel_path}:{i}: Comment contains '--' (double-hyphen)")
+            except Exception as e:
+                self._add_warning("WARNING", "XML", f"{rel_path}: Could not check comments: {e}")
+
+    def _check_common_xhtml_errors(self):
+        """Check for common XHTML/XML errors that plague EPUB files."""
+        print("\n📝 Checking for common XHTML errors...")
+
+        xhtml_files = list(Path(self.temp_dir).rglob("*.xhtml"))
+
+        for xhtml_file in xhtml_files:
+            rel_path = xhtml_file.relative_to(self.temp_dir)
+            try:
+                content = xhtml_file.read_text()
+                lines = content.split('\n')
+
+                for i, line in enumerate(lines, 1):
+                    # Check for unclosed tags (common patterns)
+                    if '<br>' in line and '<br/>' not in line and '<br />' not in line:
+                        self._add_warning("WARNING", "XHTML",
+                            f"{rel_path}:{i}: Use self-closing <br/> instead of <br>")
+
+                    if '<img ' in line and not '/>' in line[line.index('<img '):]:
+                        self._add_warning("WARNING", "XHTML",
+                            f"{rel_path}:{i}: <img> tag should be self-closing")
+
+                    if '<hr>' in line and '<hr/>' not in line and '<hr />' not in line:
+                        self._add_warning("WARNING", "XHTML",
+                            f"{rel_path}:{i}: Use self-closing <hr/> instead of <hr>")
+
+                    # Check for unescaped ampersands (except entities)
+                    if '&' in line:
+                        # Simple check for unescaped &
+                        if re.search(r'&(?![a-zA-Z]+;|#\d+;|#x[0-9a-fA-F]+;)', line):
+                            self._add_warning("WARNING", "XHTML",
+                                f"{rel_path}:{i}: Possibly unescaped ampersand (&)")
+
+                    # Check for <  > without proper escaping
+                    if re.search(r'<(?![a-zA-Z/!?])', line):
+                        self._add_warning("WARNING", "XHTML",
+                            f"{rel_path}:{i}: Possibly unescaped < character")
+
+                    # Check for attributes without quotes
+                    if re.search(r'<\w+[^>]*\s+\w+=\w+[^"\']', line):
+                        self._add_warning("WARNING", "XHTML",
+                            f"{rel_path}:{i}: Attribute values should be quoted")
+
+            except Exception as e:
+                self._add_warning("WARNING", "XHTML",
+                    f"{rel_path}: Could not check for common errors: {e}")
+
+    def _check_xhtml_validity(self):
+        """Check XHTML files for basic validity."""
+        print("\n📝 Checking XHTML validity...")
+
+        xhtml_files = list(Path(self.temp_dir).rglob("*.xhtml"))
+
+        for xhtml_file in xhtml_files:
+            rel_path = xhtml_file.relative_to(self.temp_dir)
+            try:
+                # Try to parse as XML (XHTML should be well-formed XML)
+                ET.parse(xhtml_file)
+                print(f"  ✓ {rel_path}: Valid XHTML")
+            except ET.ParseError as e:
+                self._add_error("ERROR", "XHTML", f"{rel_path}: Parse error - {e}")
+
+    def _check_opf_structure(self):
+        """Check OPF file structure."""
+        print("\n📝 Checking OPF structure...")
+
+        opf_files = list(Path(self.temp_dir).rglob("*.opf"))
+
+        if not opf_files:
+            self._add_error("ERROR", "Structure", "No OPF file found")
+            return
+
+        for opf_file in opf_files:
+            rel_path = opf_file.relative_to(self.temp_dir)
+            try:
+                tree = ET.parse(opf_file)
+                root = tree.getroot()
+
+                # Check for required elements
+                namespaces = {'opf': 'http://www.idpf.org/2007/opf'}
+
+                metadata = root.find('.//opf:metadata', namespaces)
+                manifest = root.find('.//opf:manifest', namespaces)
+                spine = root.find('.//opf:spine', namespaces)
+
+                if metadata is None:
+                    self._add_error("ERROR", "OPF", f"{rel_path}: Missing metadata element")
+                if manifest is None:
+                    self._add_error("ERROR", "OPF", f"{rel_path}: Missing manifest element")
+                if spine is None:
+                    self._add_error("ERROR", "OPF", f"{rel_path}: Missing spine element")
+                else:
+                    print(f"  ✓ {rel_path}: Valid OPF structure")
+
+            except ET.ParseError as e:
+                self._add_error("ERROR", "OPF", f"{rel_path}: Parse error - {e}")
+
+    def _print_results(self):
+        """Print validation results."""
+        print("\n" + "="*70)
+        print("📊 VALIDATION RESULTS")
+        print("="*70)
+
+        if not self.errors and not self.warnings:
+            print("\n✅ SUCCESS: No issues found!")
+            print(f"   {self.epub_path.name} is valid")
+            return
+
+        if self.errors:
+            print(f"\n❌ ERRORS FOUND: {len(self.errors)}")
+            print("-" * 70)
+            for severity, category, message in self.errors:
+                print(f"  [{severity}] [{category}] {message}")
+
+        if self.warnings:
+            print(f"\n⚠️  WARNINGS: {len(self.warnings)}")
+            print("-" * 70)
+            for severity, category, message in self.warnings:
+                print(f"  [{severity}] [{category}] {message}")
+
+        print("\n" + "="*70)
+        if self.errors:
+            print("❌ VALIDATION FAILED")
+        else:
+            print("✅ VALIDATION PASSED (with warnings)")
+        print("="*70)
+
+
+def main():
+    """Main entry point."""
+    if len(sys.argv) < 2:
+        print("Usage: python3 validate_epub.py [--quick] <path_to_epub_file>")
+        print("\nOptions:")
+        print("  --quick    Skip epubcheck validation (faster, custom checks only)")
+        print("\nExamples:")
+        print("  python3 validate_epub.py quarto/_build/epub/Machine-Learning-Systems.epub")
+        print("  python3 validate_epub.py --quick quarto/_build/epub/Machine-Learning-Systems.epub")
+        sys.exit(1)
+
+    # Parse arguments
+    use_epubcheck = True
+    epub_path = None
+
+    for arg in sys.argv[1:]:
+        if arg == '--quick':
+            use_epubcheck = False
+        elif not epub_path:
+            epub_path = arg
+
+    if not epub_path:
+        print("Error: No EPUB file specified")
+        sys.exit(1)
+
+    validator = EPUBValidator(epub_path, use_epubcheck=use_epubcheck)
+
+    success = validator.validate()
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()