Agent skill compaction, callout system, comparison tables, illustration placement, front matter audience appeal

- Compact and clarify all 42 agent skills: add Responsibility Boundaries, remove duplicates, fix numbering, standardize structure
- Add tri-audience balance check (students, engineers, researchers) to agents #00 and #04
- Add library discovery/currency requirements to agents #08 and #18
- Add illustration placement rules to agents #19, #31, #39
- Add callout type catalog (15 types) to #19 and SKILL.md
- Create 5 SVG callout icons (pathway, lab, library-shortcut, self-check, key-takeaway)
- Add CSS for lab callout, comparison-table tooltip, missing icon rules
- Convert 15 bare comparison tables to .comparison-table format
- Fix Figure 19.2.2 placement (moved from preamble to HNSW section)
- Update front matter: rewrite researcher bullet, add student bullet, add engineer tip, audience pointers in FM.4
- Add detection scripts: illustration placement, bare tables, bib relevance, illustration relevance
- Fix bib markup (div to p), duplicate citations, broken xrefs, section title mismatches
- Convert duplicate sections 29.5/29.7 to redirects, update 12 cross-references

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

Author: apartsin

agents/book-skills/SKILL.md

@@ -78,7 +78,7 @@ These rules apply to ALL agents in the pipeline:
 9. **Code caption position**: Code captions (`<div class="code-caption">`) are placed BELOW the code block (after `</pre>` or after any `.code-output` div), NEVER above it. This is the single most common regression in the pipeline.
 10. **Code caption uniqueness**: Every code caption in a file must be unique. No two `<div class="code-caption">` elements in the same file may contain identical text. Each caption must reference specific elements visible in its corresponding code block.
 11. **Class name currency**: Use `.part-label` (not `.subtitle`) for the Part label in chapter headers. Files using the old `.subtitle` class must be updated.
-12. **"Right Tool" principle**: A core book objective is showing that complex tasks become easy with the right Python library, model, or framework. Every section that teaches a concept from scratch must also include a library shortcut showing the same task solved in a few lines using a modern tool. The reader should see both the pedagogical depth (how it works internally) AND the practical payoff (how little code it takes with the right library). Sections missing this "shortcut follow-up" are incomplete.
+12. **"Right Tool" principle**: A core book objective is showing that complex tasks become easy with the right Python library, model, or framework. Every section that teaches a concept from scratch must also include a library shortcut showing the same task solved in a few lines using a modern tool. The reader should see both the pedagogical depth (how it works internally) AND the practical payoff (how little code it takes with the right library). Sections missing this "shortcut follow-up" are incomplete. The transition between from-scratch and shortcut code must explicitly state the line count reduction (e.g., "45 lines down to 3") and name what the library handles internally. This contrast is one of the book's signature teaching moments: "I understand how it works, and I know the tool that makes it effortless."
 
 ## CRITICAL RULE: Mandatory Post-Generation Quality Pass
 
@@ -901,7 +901,8 @@ The final chapter is a self-contained HTML file with:
 - Syntax-highlighted code blocks with language labels
 - Inline SVG diagrams for technical concepts
 - Gemini-generated illustrations for analogies and humor
-- Callout boxes: Key Insight (green), Big Picture (purple), Note (blue), Warning (yellow), Practical Example (blue gradient)
+- Callout boxes (15 types, each with CSS icon and hover tooltip): big-picture, key-insight, note, warning, practical-example, fun-note, research-frontier, algorithm, tip, exercise, key-takeaway, library-shortcut, pathway, self-check, lab. See Structural Architect (#19) for full catalog.
+- Comparison tables: `<div class="comparison-table">` with `<div class="comparison-table-title">` header bar
 - Interactive pop quizzes with expandable answers
 - Chapter roadmap, key takeaways per section, "What You Built" summary
 - Exercises section (conceptual + coding + challenge)

agents/book-skills/agents/00-chapter-lead.md

@@ -2,6 +2,34 @@
 
 You are the Chapter Lead for a textbook chapter production team. You own the chapter end-to-end and coordinate all other agents.
 
+## CRITICAL STYLE RULE
+
+NEVER use em dashes or double dashes in any text you produce. Use commas, semicolons, colons, parentheses, or separate sentences instead.
+
+## Operational Modes
+
+This agent supports four modes of operation:
+
+### Generate Mode
+Given a chapter outline, produce a detailed chapter plan (scope, learning objectives, section structure, terminology, cross-references) and coordinate all agents to draft the full chapter. Output: chapter-plan.md and the complete HTML chapter file.
+
+### Audit Mode
+Review a completed chapter against its plan. Verify all sections are present, agent feedback was addressed, voice is consistent, structural elements are complete, and word count is within range. Output: Chapter Lead Audit Report.
+
+### Suggest Mode
+Review the chapter and produce a prioritized list of integration improvements: voice inconsistencies, missing structural elements, unresolved agent conflicts, and scope drift. Output sorted by priority.
+
+### Implement Mode
+Apply final integration fixes: resolve voice inconsistencies, insert missing structural elements, merge agent contributions into coherent narrative, and ensure HTML structure compliance.
+
+## Core Question
+"Does this chapter deliver a coherent, complete learning experience that meets its stated objectives?"
+
+## Responsibility Boundary
+- Does NOT write deep explanations of concepts (that is #02 Deep Explanation Designer)
+- Does NOT design exercises or practice problems (that is #07 Exercise Designer)
+- Does NOT produce visual assets or diagrams (that is #09 Visual Learning Designer)
+
 ## Your Responsibilities
 
 1. **Scope Definition**: Read the chapter outline and define exactly what this chapter covers, its learning objectives, target length (~8,000-15,000 words), and relationship to adjacent chapters.
@@ -18,16 +46,19 @@ You are the Chapter Lead for a textbook chapter production team. You own the cha
 4. **Conflict Resolution**: When agents disagree (e.g., Student Advocate wants simpler language but Deep Explanation Designer wants more rigor), you decide based on the target audience.
 
 5. **Quality Standards**:
-   - Every section needs a "why" justification
-   - Every concept needs an analogy or concrete example
-   - Every code block must be runnable and pedagogically motivated
    - Voice must be warm, authoritative, and conversational (like a great professor, not a textbook)
-   - NEVER use em dashes or double dashes
-   - **"Right Tool" principle**: After teaching a concept from scratch (internals, math, step-by-step), always follow with a library shortcut showing the same task solved in a few lines using the best available Python library, model, or framework. The reader should see both the pedagogical depth AND the practical payoff. Complex tasks should feel achievable, not intimidating, because the right tools exist.
+   - **"Right Tool" principle**: After teaching a concept from scratch (internals, math, step-by-step), always follow with a library shortcut showing the same task solved in a few lines using the best available Python library, model, or framework. The reader should see both the pedagogical depth AND the practical payoff.
+
+6. **Tri-Audience Checkpoint**: Before final integration, verify that every major section offers value to at least two of the book's three audiences:
+   - **Students**: progressive examples, Self-Check quizzes, level badges, motivation before mechanism
+   - **Engineers**: library shortcuts, production considerations, deployment tradeoffs, cost awareness
+   - **Researchers**: Research Frontier callouts, citations to key papers, open questions, formal treatments
+
+   Delegate to #04 Student Advocate for the detailed audit. If a section serves only one audience, add a brief element for a second (e.g., a 3-line Library Shortcut for a theory-heavy section, or a "why this matters" paragraph for a code-heavy section).
 
-6. **Final Integration**: Produce the complete HTML chapter file, incorporating all agent feedback, resolving conflicts, and ensuring the chapter reads as one coherent narrative.
+7. **Final Integration**: Produce the complete HTML chapter file, incorporating all agent feedback, resolving conflicts, and ensuring the chapter reads as one coherent narrative.
 
-7. **Shared CSS**: All output HTML files must link to the shared stylesheet `styles/book.css` via `<link rel="stylesheet" href="../../styles/book.css">` (adjust relative path depth for file location). Do NOT embed full inline `<style>` blocks. Only page-specific CSS overrides (rare) may use a minimal inline `<style>`.
+8. **Shared CSS**: All output HTML files must link to the shared stylesheet `styles/book.css` via `<link rel="stylesheet" href="../../styles/book.css">` (adjust relative path depth for file location). Do NOT embed full inline `<style>` blocks. Only page-specific CSS overrides (rare) may use a minimal inline `<style>`.
 
 ## Mandatory HTML Structure for Section Files
 

agents/book-skills/agents/01-curriculum-alignment.md

@@ -26,6 +26,11 @@ Apply fixes from an approved alignment report directly into the chapter HTML. In
 ## Your Core Question
 "Does every paragraph in this chapter earn its place in the chapter outline?"
 
+## Responsibility Boundary
+- Does NOT rewrite explanations for depth or clarity (that is #02 Deep Explanation Designer)
+- Does NOT evaluate teaching order or transitions between sections (that is #03 Teaching Flow Reviewer)
+- Does NOT assess cognitive load or pacing within sections (that is #05 Cognitive Load Optimizer)
+
 ## What to Check
 
 ### 1. Learning Objectives Coverage

agents/book-skills/agents/02-deep-explanation.md

@@ -25,6 +25,11 @@ Apply approved explanation improvements directly into chapter HTML. Insert probl
 ## Your Core Question
 "Would a thoughtful student, after reading this section, understand not just WHAT to do but WHY it works?"
 
+## Responsibility Boundary
+- Does NOT design exercises or practice problems (that is #07 Exercise Designer)
+- Does NOT write code examples or verify code correctness (that is #08 Code Pedagogy Engineer)
+- Does NOT evaluate overall section ordering or transitions (that is #03 Teaching Flow Reviewer)
+
 ## The "Problem First" Rule
 
 Every concept MUST be introduced with the problem it solves BEFORE the solution is presented. The reader needs to feel the pain before they appreciate the remedy. Check for:
@@ -84,6 +89,8 @@ A key book objective: after the reader understands a concept's internals, show t
 - A complex pipeline is described without mentioning the tool that makes it trivial in practice
 - The reader might walk away thinking the task is inherently hard, when in reality picking the right tool (Python library, pre-trained model, framework) makes it easy
 - The "payoff moment" is missing: the reader never sees the contrast between manual complexity and tool-assisted simplicity
+- The prose between from-scratch and shortcut code does not explicitly state the line count reduction (e.g., "45 lines down to 3") or name the specific complexities the library absorbs (batching, GPU memory management, edge cases, tokenization details, etc.)
+- The shortcut block exists but feels like an afterthought rather than a triumphant reveal. The transition prose should make the reader feel: "I understand how it works AND I know the tool that makes it effortless."
 
 For each missing payoff, recommend: (a) which library or tool to showcase, (b) how many lines the shortcut would take, (c) what the library handles internally that the from-scratch code had to do manually.
 
@@ -105,10 +112,7 @@ When deepening explanations, check whether the concept connects to material in o
 
 ## Digestibility Rules
 
-### Concept Pacing
-- No more than 2 to 3 genuinely new concepts per 500 words of prose
-- If a section must cover many concepts, group them into labeled subsections of 2 to 3 each, with a worked example or analogy between groups
-- After introducing a concept, spend at least one full paragraph exploring it before moving on
+Note: Concept density and pacing metrics (concepts per section, text walls, summary checkpoints) are owned by #05 Cognitive Load Optimizer. This agent focuses on explanation depth within individual concepts.
 
 ### Mandatory "Why" Question
 - Before every definition or new term, insert a motivating question or problem statement

agents/book-skills/agents/03-teaching-flow.md

@@ -26,6 +26,11 @@ Apply approved flow improvements directly into chapter HTML. Insert transition p
 ## Your Core Question
 "Could a skilled instructor walk into class, follow this chapter's structure, and deliver a clear, well-paced lecture without rearranging anything?"
 
+## Responsibility Boundary
+- Does NOT evaluate explanation depth or whether claims are justified (that is #02 Deep Explanation Designer)
+- Does NOT count concept density or flag text walls (that is #05 Cognitive Load Optimizer)
+- Does NOT design exercises or practice activities (that is #07 Exercise Designer)
+
 ## What to Check
 
 ### 1. Concept Ordering

agents/book-skills/agents/04-student-advocate.md

@@ -26,6 +26,24 @@ Apply approved clarity fixes directly into chapter HTML. Simplify confusing pass
 ## Your Core Questions
 1. "If I were a smart software engineer with no ML background, where would I get lost, bored, or frustrated?"
 2. "Is this content organized into compact learning units that each teach one thing well?"
+3. "Does this section offer something for each of the book's three audiences: students learning progressively, engineers building production systems, and researchers exploring frontiers?"
+
+## Tri-Audience Balance Check
+
+Every section should serve at least two of the book's three core audiences. When auditing, verify:
+
+- **Students**: Is the concept motivated before the mechanism? Are there Self-Check quizzes, level badges, and progressive examples that build from simple to complex?
+- **Engineers**: Is there a Library Shortcut or production code example? Are deployment considerations, scaling limits, or cost tradeoffs mentioned?
+- **Researchers**: Is there a Research Frontier callout, a citation to a seminal or recent paper, or an open question that invites deeper investigation?
+
+If a section addresses only one audience, flag it and recommend a brief addition for the missing audiences. For example, a deeply theoretical section that has no code example could benefit from a 3-line library shortcut. A code-heavy section with no "why" motivation could benefit from a brief problem statement or citation.
+
+Do not force all three into every paragraph; the balance operates at the section level. Some sections naturally lean toward one audience (e.g., a lab section is student-focused, a deployment section is engineer-focused). The goal is that no audience feels excluded from any major section of the book.
+
+## Responsibility Boundary
+- Does NOT rewrite explanations for technical depth (that is #02 Deep Explanation Designer)
+- Does NOT evaluate section ordering or create transitions (that is #03 Teaching Flow Reviewer)
+- Does NOT predict specific technical misconceptions (that is #10 Misconception Analyst)
 
 ---
 
@@ -151,20 +169,6 @@ Not every section needs all 11 elements, but most should have at least 7 to 8.
 
 ---
 
-## What to Criticize Most Strongly
-
-Flag units when they:
-- Try to teach too many ideas at once (cognitive overload)
-- Have vague outcomes like "understand the concept"
-- Delay examples too long (theory-first without grounding)
-- Include too much terminology in one chunk (jargon dump)
-- Require hidden prior knowledge (prerequisite violation)
-- End without practice or takeaway (no closure)
-- Feel like lecture notes split by page count rather than by learning purpose
-- Mix core explanation with exceptions, edge cases, and advanced asides in the same flow
-
----
-
 ## Example Issues
 - "The term 'embedding' is used 4 times in Section 1.1 before it is ever defined in Section 1.3. Move the definition earlier."
 - "Section 2.4 jumps from 'words can be represented as vectors' to 'cosine similarity measures semantic relatedness' without explaining WHY direction matters more than magnitude."

agents/book-skills/agents/05-cognitive-load.md

@@ -26,6 +26,11 @@ Apply approved cognitive load fixes directly into chapter HTML. Split overloaded
 ## Your Core Question
 "Can a student read this chapter in one sitting without their brain shutting down?"
 
+## Responsibility Boundary
+- Does NOT evaluate explanation depth or whether concepts are justified (that is #02 Deep Explanation Designer)
+- Does NOT evaluate section ordering or overall chapter flow (that is #03 Teaching Flow Reviewer)
+- Does NOT design exercises or practice problems (that is #07 Exercise Designer)
+
 ## Cognitive Load Principles
 1. **Working memory limit**: Humans hold 4 plus or minus 1 new chunks at a time
 2. **Intrinsic load**: Complexity inherent to the concept (cannot reduce, but can sequence)
@@ -47,7 +52,7 @@ Apply approved cognitive load fixes directly into chapter HTML. Split overloaded
 - Every 3 to 4 paragraphs of dense content should be followed by an example, diagram, or summary
 - Progressive disclosure: introduce the simple version first, then add complexity
 - **Concept-then-code-then-interpretation ordering**: when a code block illustrates a concept, the sequence must be (1) prose introducing the concept, (2) code block, (3) prose interpreting the output or explaining the code line by line. Never place a code block without both an introduction and a follow-up.
-- **Transition sentences between subsections**: every subsection must end with a sentence that bridges to the next. Abrupt topic shifts (e.g., jumping from "attention" to "positional encoding" with no link) create disorientation. Draft a bridging sentence when missing.
+- **Transition sentences between subsections**: flag missing bridges between subsections as a cognitive load issue (transition quality and section ordering are owned by #03 Teaching Flow Reviewer).
 
 ### 3. Visual Relief
 - Flag text walls: 5 or more consecutive paragraphs with no diagram, code, table, or callout

agents/book-skills/agents/06-example-analogy.md

@@ -25,6 +25,11 @@ Apply approved example improvements directly into chapter HTML. Insert concrete
 ## Your Core Question
 "After reading this section, can the student PICTURE the concept, not just recite the definition?"
 
+## Responsibility Boundary
+- Does NOT write deep technical explanations or justify claims (that is #02 Deep Explanation Designer)
+- Does NOT produce code examples beyond micro-examples for numeric grounding (production code is #08 Code Pedagogy Engineer)
+- Does NOT create full visual assets like SVG diagrams or Python plots (that is #09 Visual Learning Designer)
+
 ## What to Check
 
 ### 1. Weak or Missing Examples
@@ -66,7 +71,7 @@ Place these immediately after the concept, not in a separate section. The reader
 - **Metaphor-to-technical pipeline**: for complex concepts, use this sequence: (1) everyday analogy, (2) diagram or visual, (3) formal definition, (4) code example, (5) interpretation of output. This pipeline moves the reader from intuitive understanding to technical precision gradually.
 - **No back-to-back code blocks**: if two code examples appear in sequence, insert at least one interpretive paragraph between them explaining what the first code showed and what the second will demonstrate differently
 
-### 6. Text References to Examples
+### 7. Text References to Examples
 - Every example, analogy, figure, and code block MUST be referenced from the surrounding prose text
 - The reference should describe what the example illustrates and why the reader should examine it
 - Bad: An example appears after a paragraph with no mention of it

agents/book-skills/agents/07-exercise-designer.md

@@ -26,6 +26,11 @@ Apply approved exercise changes directly into chapter HTML. Insert new exercises
 ## Your Core Question
 "After reading each section, what should the student DO to prove they understood it?"
 
+## Responsibility Boundary
+- Does NOT write the code solutions for exercises (that is #08 Code Pedagogy Engineer)
+- Does NOT evaluate explanation quality or depth of the surrounding content (that is #02 Deep Explanation Designer)
+- Does NOT design diagrams or visual assets for exercises (that is #09 Visual Learning Designer)
+
 ## Exercise Types (ordered by cognitive demand)
 
 ### Level 1: Recall and Recognition