Standardize callouts, fix epigraphs, add Mermaid diagrams, revert broken SVG conversions

Major changes across 410+ files:
- Convert 5 Author's Perspective callouts to standard Note callouts, remove first-person prose
- Move 10 epigraphs from outside to inside <main> tag (part indexes + appendices index)
- Add 18 new Mermaid diagrams for prose-heavy sections (Ch 11, 12, 20, 21, 22, 25, 26, 29, 30, 31, 32, 33)
- Convert 10 inline SVGs to proper Mermaid PNGs (Fig 1.3.6, 2.2.5, 3.1.6, 3.2.4, 4.1.7, 5.2.3, 10.1.2, 10.1.5, 10.2.2, 10.2.4)
- Revert 183 broken SVG-to-Mermaid conversions (agent generated caption-only stubs)
- Delete 183 broken .mmd/.png pairs, restore original inline SVGs
- Add appendices/index.html, new Mermaid .mmd source files, matplotlib chart scripts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: apartsin

CLAUDE.md

@@ -24,14 +24,34 @@ When performing book production tasks, you MUST read the relevant agent descript
 - When **adding code captions**, read `agents/book-skills/agents/40-code-caption-agent.md`
 - When **auditing agent quality**, read `agents/book-skills/agents/36-meta-agent.md`
 
-## Image Generation
+## Visual Content (Three Pipelines)
 
-- Script: `agents/book-skills/scripts/generate_icons_gemini.py`
-- For multiple images, always use `--engine gemini --batch` (50% discount)
-- For single images, use `C:/Users/apart/.claude/skills/gemini-imagegen/scripts/generate_image.py`
+### 1. Gemini Illustrations (cartoons, visual metaphors)
+- Batch: `agents/book-skills/scripts/generate_icons_gemini.py` with `--engine gemini --batch` (50% discount)
+- Single: `C:/Users/apart/.claude/skills/gemini-imagegen/scripts/generate_image.py`
 - Prompt style: warm cartoon, whimsical, no text in images, Kurzgesagt meets XKCD
 - Embed with `<figure class="illustration">` pattern from `agents/book-skills/agents/31-illustrator.md`
 
+### 2. Mermaid Diagrams (flowcharts, architectures, pipelines)
+- Render: `mmdc -i input.mmd -o output.png -c scripts/mermaid/mermaid-config.json -w 1200 -s 3 --backgroundColor white`
+- ELK layout (complex hierarchies): use `scripts/mermaid/mermaid-config-elk.json` instead
+- Source `.mmd` files saved alongside PNGs for future editing
+- Generation script: `scripts/mermaid/generate_mermaid_diagrams.py`
+- Dependencies: `@mermaid-js/mermaid-cli`, `@mermaid-js/layout-elk`
+- Embed with `<div class="diagram-container"><img>` pattern
+
+### 3. Matplotlib Charts (data visualizations with axes)
+- Scripts: `scripts/svg_to_matplotlib/gen_figure_*.py`
+- Shared style: `scripts/svg_to_matplotlib/chart_style.py` (300 DPI, consistent fonts/colors)
+- Run: `C:/Python314/python scripts/svg_to_matplotlib/gen_figure_X_Y_Z.py`
+- Use `PchipInterpolator` for monotonic curves (avoids spline overshoot)
+
+### Decision: which pipeline?
+- Cartoon/metaphor/humor → Gemini
+- Axes/data points/quantitative → Matplotlib
+- Boxes/arrows/flows/trees → Mermaid
+- Default (uncertain) → Mermaid (free, editable, consistent)
+
 ## Global Rules
 - NEVER use em dashes or double dashes in generated text
 - Use "book", "part", "chapter", "section", "reader" (not "course", "module", "lecture", "student")

agents/book-skills/agents/31-illustrator.md

@@ -29,8 +29,116 @@ humorous cartoon, or visual metaphor) would make it click instantly?"
 
 ## Responsibility Boundary
 - Does NOT enforce CSS, layout consistency, or visual identity standards; that is #25 Visual Identity Director.
-- Does NOT create SVG diagrams, flowcharts, or technical architecture figures; those are authored directly. This agent produces Gemini-generated cartoon/illustration assets only.
-- Does NOT write prose, captions for non-illustration figures, or alt text for existing SVG diagrams; content agents handle those.
+- Does NOT write prose, captions for non-illustration figures, or alt text for existing diagrams; content agents handle those.
+
+## Three Illustration Pipelines
+
+This agent supports THREE production pipelines for visual content. Choose the right tool for each situation:
+
+### Pipeline 1: Gemini Image Generation (Cartoon Illustrations)
+**Use for:** Humorous cartoons, visual metaphors, mental model illustrations, chapter openers.
+**Tool:** Gemini Batch API (`batch_generate.py`) or single image (`generate_image.py`).
+**Output:** PNG files with warm, cartoon-like style (Kurzgesagt meets XKCD).
+**Cost:** ~$0.04/image (batch, 50% discount) or ~$0.08/image (sync).
+See the "Batch Image Generation Workflow" section below.
+
+### Pipeline 2: Mermaid Diagrams (Flowcharts, Architectures, Pipelines)
+**Use for:** Flowcharts, decision trees, sequence diagrams, architecture diagrams, pipeline flows, tree structures, grouped/classified concept maps. Any diagram with boxes, arrows, and labels.
+**Tool:** Mermaid CLI (`mmdc`) with custom theme config.
+**Output:** High-resolution PNG at 3x scale with white background.
+**Cost:** Free (local rendering).
+
+#### Mermaid Rendering Command
+```bash
+mmdc -i input.mmd -o output.png \
+  -c E:/Projects/LLMCourse/scripts/mermaid/mermaid-config.json \
+  -w 1200 -s 3 --backgroundColor white
+```
+
+For complex hierarchical diagrams with many subgroups, use the ELK layout engine config:
+```bash
+mmdc -i input.mmd -o output.png \
+  -c E:/Projects/LLMCourse/scripts/mermaid/mermaid-config-elk.json \
+  -w 1200 -s 3 --backgroundColor white
+```
+
+#### Mermaid Style Guidelines
+- Use HTML labels: `["<b>Title</b><br/><i>subtitle</i>"]`
+- Color palette (match book theme):
+  - Blues: `fill:#e3f2fd,stroke:#1565c0,color:#1a1a2e`
+  - Greens: `fill:#e8f5e9,stroke:#2e7d32,color:#1a1a2e`
+  - Purples: `fill:#f3e5f5,stroke:#6a1b9a,color:#1a1a2e`
+  - Oranges: `fill:#fff3e0,stroke:#e65100,color:#1a1a2e`
+  - Reds: `fill:#fce4ec,stroke:#c62828,color:#1a1a2e`
+  - Dark (emphasis): `fill:#1a1a2e,stroke:#0f3460,color:#fff`
+- Use `subgraph` for grouping related concepts
+- Use dashed arrows (`-.->`) for optional/feedback flows
+- Use solid arrows (`-->`) for primary flows
+- Add edge labels: `-->|"label"|`
+- Diagram types: `flowchart LR`, `flowchart TB`, `flowchart TD`, `sequenceDiagram`, `classDiagram`
+
+#### Mermaid Diagram Template
+```mermaid
+flowchart LR
+    A["<b>Step 1</b><br/><i>description</i>"]
+    B["<b>Step 2</b><br/><i>description</i>"]
+    C["<b>Step 3</b><br/><i>description</i>"]
+
+    A -->|"action"| B -->|"action"| C
+
+    style A fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1a1a2e
+    style B fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a1a2e
+    style C fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#1a1a2e
+```
+
+#### Mermaid HTML Embedding
+```html
+<div class="diagram-container">
+<img src="images/descriptive-name.png" alt="Description of diagram" loading="lazy" style="max-width: 100%;">
+<div class="diagram-caption"><strong>Figure X.Y.Z</strong>: Caption describing the concept.</div>
+</div>
+```
+
+#### Existing Mermaid Infrastructure
+- Config files: `scripts/mermaid/mermaid-config.json` (dagre, default), `scripts/mermaid/mermaid-config-elk.json` (ELK, complex layouts)
+- Generation script: `scripts/mermaid/generate_mermaid_diagrams.py` (with `render_mermaid()` helper)
+- Save `.mmd` source files alongside PNGs for future editing
+- Dependencies: `npm install -g @mermaid-js/mermaid-cli @mermaid-js/layout-elk`
+
+### Pipeline 3: Matplotlib Charts (Data Visualizations)
+**Use for:** Line charts, bar charts, scatter plots, radar charts, any diagram with axes, data points, or quantitative comparisons.
+**Tool:** Python matplotlib with shared style module.
+**Output:** 300 DPI PNG with consistent typography and colors.
+**Cost:** Free (local rendering).
+
+#### Matplotlib Rendering
+```bash
+C:/Python314/python scripts/svg_to_matplotlib/gen_figure_X_Y_Z.py
+```
+
+#### Matplotlib Style Module
+All chart scripts import `chart_style.py` from `scripts/svg_to_matplotlib/`:
+```python
+import sys, os
+sys.path.insert(0, os.path.dirname(__file__))
+from chart_style import *
+apply_style()
+```
+
+This provides: `plt`, `np`, `save_figure()`, consistent font sizes, color palette, and 300 DPI output.
+
+#### Matplotlib Guidelines
+- Use `PchipInterpolator` (not `make_interp_spline`) for monotonic curves to avoid overshoot artifacts
+- Color palette: `#1a4a80` (primary blue), `#e94560` (accent red), `#27ae60` (green), `#f39c12` (orange)
+- Always include axis labels, use `fontsize=12, color='#555'`
+- Remove top/right spines: `ax.spines['top'].set_visible(False)`
+- Use `fig, ax = plt.subplots(figsize=(10, 5.5))` for standard charts
+
+### Pipeline Selection Decision Tree
+1. Is it a **cartoon, metaphor, or humorous scene**? → Gemini
+2. Does it have **axes, data points, or quantitative data**? → Matplotlib
+3. Is it a **flowchart, architecture, pipeline, decision tree, or grouped concept map**? → Mermaid
+4. When in doubt, prefer **Mermaid** (free, editable, consistent styling)
 
 ## Batch Image Generation Workflow
 

appendices/appendix-a-mathematical-foundations/section-a.5.html

@@ -93,7 +93,9 @@ <h2>What Comes Next</h2>
     </div>
 
     <div class="bib-entry-card">
-        <p class="bib-ref">Shannon, C. E. (1948). "A Mathematical Theory of Communication." Bell System Technical Journal, 27(3), 379-423.</p>
+        <p class="bib-ref">
+ Shannon, C. E. (1948). <a href="https://doi.org/10.1002/j.1538-7305.1948.tb01338.x" target="_blank" rel="noopener">"A Mathematical Theory of Communication."</a> Bell System Technical Journal, 27(3), 379-423.
+ </p>
         <p class="bib-annotation">The founding paper of information theory. Still remarkably readable.</p>
         <span class="bib-meta">Foundational Paper</span>
     </div>

appendices/appendix-b-ml-essentials/section-b.4.html

@@ -234,13 +234,17 @@ <h2>What Comes Next</h2>
     <div class="bib-category">Metrics and Evaluation</div>
 
     <div class="bib-entry-card">
-        <p class="bib-ref">Papineni, K. et al. (2002). "BLEU: a Method for Automatic Evaluation of Machine Translation." ACL 2002.</p>
+        <p class="bib-ref">
+ Papineni, K. et al. (2002). <a href="https://doi.org/10.3115/1073083.1073135" target="_blank" rel="noopener">"BLEU: a Method for Automatic Evaluation of Machine Translation."</a> ACL 2002.
+ </p>
         <p class="bib-annotation">The original BLEU paper, still one of the most cited works in NLP evaluation.</p>
         <span class="bib-meta">Foundational Paper</span>
     </div>
 
     <div class="bib-entry-card">
-        <p class="bib-ref">Zhang, T. et al. (2020). "BERTScore: Evaluating Text Generation with BERT." ICLR 2020.</p>
+        <p class="bib-ref">
+ Zhang, T. et al. (2020). <a href="https://arxiv.org/abs/1904.09675" target="_blank" rel="noopener">"BERTScore: Evaluating Text Generation with BERT."</a> ICLR 2020.
+ </p>
         <p class="bib-annotation">Embedding-based evaluation that better captures semantic similarity than n-gram methods.</p>
         <span class="bib-meta">Research Paper</span>
     </div>

appendices/appendix-k-huggingface-ecosystem/images/chapter-opener.png

@@ -0,0 +1,15 @@
+flowchart LR
+    UI["<b>User Input</b>"]
+    LLM["<b>LLM</b><br/><i>decides action</i>"]
+    TOOL["<b>Tool</b><br/><i>execute</i>"]
+    FA["<b>Final Answer</b><br/><i>no more tools</i>"]
+
+    UI --> LLM
+    LLM -->|"tool call"| TOOL
+    TOOL -.->|"observation"| LLM
+    LLM -->|"done"| FA
+
+    style UI fill:#d6eaf8,stroke:#2980b9,stroke-width:2px,color:#1a5276
+    style LLM fill:#d5f5e3,stroke:#27ae60,stroke-width:2px,color:#1e8449
+    style TOOL fill:#fdebd0,stroke:#e67e22,stroke-width:2px,color:#935116
+    style FA fill:#e8daef,stroke:#8e44ad,stroke-width:2px,color:#4a235a

appendices/appendix-l-langchain/images/agent-execution-loop.mmd

@@ -0,0 +1,12 @@
+flowchart LR
+    A["<b>PromptTemplate</b><br/><i>fills variables</i>"]
+    B["<b>ChatModel</b><br/><i>generates response</i>"]
+    C["<b>OutputParser</b><br/><i>extracts content</i>"]
+    D["<b>Result</b><br/><i>clean string</i>"]
+
+    A -->|"&nbsp;pipe&nbsp;"| B -->|"&nbsp;pipe&nbsp;"| C -->|"&nbsp;pipe&nbsp;"| D
+
+    style A fill:#e8daef,stroke:#8e44ad,stroke-width:2px,color:#4a235a
+    style B fill:#d5f5e3,stroke:#27ae60,stroke-width:2px,color:#1e8449
+    style C fill:#fdebd0,stroke:#e67e22,stroke-width:2px,color:#935116
+    style D fill:#d6eaf8,stroke:#2980b9,stroke-width:2px,color:#1a5276

appendices/appendix-l-langchain/images/agent-execution-loop.png

@@ -0,0 +1,17 @@
+flowchart LR
+    UI["<b>User Input</b>"]
+    RWM["<b>RunnableWith<br/>MessageHistory</b>"]
+    HS["<b>History Store</b><br/><i>get_session_history</i>"]
+    CH["<b>LCEL Chain</b>"]
+    RS["<b>Response</b>"]
+
+    UI --> RWM
+    HS -.->|"load history"| RWM
+    RWM --> CH --> RS
+    CH -.->|"save exchange"| HS
+
+    style UI fill:#d6eaf8,stroke:#2980b9,stroke-width:2px,color:#1a5276
+    style RWM fill:#e8daef,stroke:#8e44ad,stroke-width:2px,color:#4a235a
+    style HS fill:#fdebd0,stroke:#e67e22,stroke-width:2px,color:#935116
+    style CH fill:#d5f5e3,stroke:#27ae60,stroke-width:2px,color:#1e8449
+    style RS fill:#d6eaf8,stroke:#2980b9,stroke-width:2px,color:#1a5276