feat: add multi-modal learning infrastructure — tools, templates, guides

Add 4 new CI tools (modality hub generator, hub link checker, solution
skeleton generator, doc length auditor), 4 content templates, 4 guide
pages (learning style selector, video/diagram/walkthrough indexes),
CI validation step, mkdocs nav updates, README value prop rewrite for
multi-modal identity, and --learning-style flag on study plan generator.

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

Author: travisjneuman

.github/workflows/curriculum-checks.yml

@@ -57,6 +57,9 @@ jobs:
       - name: Portable path contract checks
         run: python tools/check_portable_paths.py
 
+      - name: Modality hub link validation
+        run: python tools/check_modality_hubs.py
+
       - name: Run representative pytest sample
         run: |
           pytest --tb=short --no-header -q \

README.md

@@ -29,13 +29,15 @@
 
 ## What Makes This Different
 
-This is not a video course — **you build real things**.
+**Every learning style is first-class.** Read concepts, build projects, watch walkthroughs, test with quizzes, review with flashcards, visualize with diagrams, or try code in the browser — all following the same sequential path. However you learn best, there is a pathway through this curriculum for you.
 
-This is not a bootcamp — **you go at your own pace**.
+**You build real things.** 251 projects, not toy examples. Every project has tests, starter code, and "Alter it / Break it / Fix it" challenges that force you past copy-paste into actual understanding.
 
-This is not a reference manual — **it is a complete guided path**.
+**You go at your own pace.** This is not a bootcamp with deadlines. Follow the click chain, take breaks, come back. The spaced repetition system tracks what you have forgotten so you can review efficiently.
 
-251 projects, not toy examples. Every document, concept guide, project, quiz, and challenge is connected through a single click chain. Start at the beginning and follow the "Next" links. That's it.
+**Every step is connected.** Every document, concept guide, project, quiz, walkthrough, and challenge is linked through a single click chain with a "Learn Your Way" navigation table at every stop. Start at the beginning and follow the "Next" links. That's it.
+
+Not sure how you learn best? Take the [Learning Style Selector](./guides/LEARNING_STYLE_SELECTOR.md) quiz to get a personalized path through the material.
 
 ---
 
@@ -241,11 +243,17 @@ Within each project directory, you'll find:
 
 ## 🎮 Choose Your Learning Mode
 
-**Play-First** — Open a project, tinker, break things, figure it out. Read the concept doc when you get stuck. Good for people who learn by doing.
+**Play-First (Builder)** — Open a project, tinker, break things, figure it out. Read the concept doc when you get stuck. Watch the walkthrough only if you are truly blocked. Good for people who learn by doing.
+
+**Structured (Reader)** — Read the concept doc, take the quiz, then do the projects in order. Use the checklist and mastery gates. Good for people who like clear progress markers.
+
+**Watch-First (Watcher)** — Watch the curated video for each concept, read the walkthrough to see the thinking process, then build the project. Good for people who learn by observing first.
+
+**Visual-First (Visualizer)** — Start with the Mermaid diagrams to see the big picture, read the concept guide with the diagram as your mental map, then build. Good for people who think in pictures and systems.
 
-**Structured** — Read the concept doc, take the quiz, then do the projects in order. Use the checklist and mastery gates. Good for people who like clear progress markers.
+**Hybrid (Recommended)** — Follow the structured path on weekdays. Explore expansion modules and challenges on weekends. Review flashcards daily. Mix modalities as needed.
 
-**Hybrid (Recommended)** — Follow the structured path on weekdays. Explore expansion modules and challenges on weekends. Review flashcards daily.
+Take the [Learning Style Selector](./guides/LEARNING_STYLE_SELECTOR.md) to find your best starting approach.
 
 ---
 

_templates/CONCEPT_DIAGRAMS_TEMPLATE.md

@@ -0,0 +1,29 @@
+# Diagrams: [CONCEPT_NAME]
+
+[Back to concept](../[concept-slug].md)
+
+---
+
+## Overview
+
+```mermaid
+[Main concept map or flowchart — shows the big picture of how this concept fits together]
+```
+
+## How It Works Step by Step
+
+```mermaid
+[Process or sequence diagram showing execution flow — what Python does internally]
+```
+
+## Decision Guide: When to Use This
+
+```mermaid
+[Decision tree for choosing between this concept and related alternatives]
+```
+
+## Common Patterns
+
+```mermaid
+[Diagram showing the most common usage patterns or data flow]
+```

_templates/CONCEPT_VIDEOS_TEMPLATE.md

@@ -0,0 +1,40 @@
+# Videos: [CONCEPT_NAME]
+
+[Back to concept](../[concept-slug].md)
+
+---
+
+## Best single video
+
+- **[Video Title]** by [Creator] ([duration])
+  [Why this video is the best starting point for this concept]
+  [YouTube link]
+
+## Alternative explanations
+
+Different teachers explain things differently. Try these if the first video did not click:
+
+- **[Video Title]** by [Creator] ([duration])
+  [What makes this explanation different — different angle, pace, or style]
+  [YouTube link]
+
+- **[Video Title]** by [Creator] ([duration])
+  [What makes this explanation different]
+  [YouTube link]
+
+## Deep dives
+
+For learners who want more depth after understanding the basics:
+
+- **[Video Title]** by [Creator] ([duration])
+  [What advanced topics this covers]
+  [YouTube link]
+
+## Interactive practice
+
+- [Python Tutor visualization for this concept](https://pythontutor.com/...)
+- [Related Exercism exercise](https://exercism.org/tracks/python/...)
+
+---
+
+*Last verified: [YYYY-MM-DD]. If a link is broken, please [open an issue](https://github.com/travisjneuman/learn.python/issues).*

_templates/SOLUTION_TEMPLATE.md

@@ -0,0 +1,78 @@
+# Solution: [PROJECT_TITLE]
+
+> **STOP** — Have you attempted this project yourself first?
+>
+> Learning happens in the struggle, not in reading answers.
+> Spend at least 20 minutes trying before reading this solution.
+> If you are stuck, try the [Walkthrough](./WALKTHROUGH.md) first — it guides
+> your thinking without giving away the answer.
+
+---
+
+## Complete solution
+
+```python
+"""[Module docstring].
+
+WHY this module exists: [Context from README]
+"""
+
+# WHY we import X: [Reason for this import]
+import x
+
+
+def function_name(param: type) -> return_type:
+    """[Docstring].
+
+    WHY this function: [Design reason — why a separate function?]
+    WHY this signature: [Parameter choices — why these inputs?]
+    """
+    # WHY this check: [Guard clause reason]
+    if not param:
+        raise ValueError("param cannot be empty")
+
+    # WHY this approach: [Algorithm or pattern choice]
+    result = param.process()
+
+    return result
+```
+
+## Design decisions
+
+| Decision | Why | Alternative considered |
+|----------|-----|----------------------|
+| [Decision 1] | [Reason] | [What else could work] |
+| [Decision 2] | [Reason] | [What else could work] |
+| [Decision 3] | [Reason] | [What else could work] |
+
+## Alternative approaches
+
+### Approach B: [Name]
+
+```python
+# Different valid approach with trade-offs explained
+```
+
+**Trade-off:** [When you would prefer this approach vs the primary one]
+
+### Approach C: [Name] (advanced)
+
+```python
+# More sophisticated approach — come back to this after learning [concept]
+```
+
+**Trade-off:** [This approach is better when X, but worse when Y]
+
+## What could go wrong
+
+| Scenario | What happens | Prevention |
+|----------|-------------|------------|
+| [Bad input 1] | [Error/behavior] | [How to handle] |
+| [Edge case 1] | [Behavior] | [How to handle] |
+| [Edge case 2] | [Behavior] | [How to handle] |
+
+## Key takeaways
+
+1. [Most important lesson from this project]
+2. [Second lesson]
+3. [Connection to future concepts — "You will use this pattern again in Level X"]

_templates/WALKTHROUGH_TEMPLATE.md

@@ -0,0 +1,85 @@
+# Walkthrough: [PROJECT_TITLE]
+
+> This guide walks through the **thinking process** for building this project.
+> It does NOT give you the complete solution. For that, see [SOLUTION.md](./SOLUTION.md).
+
+## Before reading this
+
+**Try the project yourself first.** Spend at least 20 minutes.
+
+This walkthrough is for AFTER you have attempted the project. If you have not tried yet, close this file and open the [project README](./README.md).
+
+---
+
+## Understanding the problem
+
+[Restate the problem in plain language. What inputs do we have? What output do we need? What constraints exist?]
+
+## Planning before code
+
+Before writing a single line of Python, think about the steps:
+
+1. [First logical step]
+2. [Second logical step]
+3. [Third logical step]
+
+```mermaid
+flowchart TD
+    A[Step 1: Read input] --> B[Step 2: Process data]
+    B --> C[Step 3: Format output]
+    C --> D[Step 4: Return result]
+```
+
+## Step 1: [First subproblem]
+
+[Explain what this step accomplishes and why it comes first.]
+
+```python
+# Just this one piece — not the whole solution
+def first_piece():
+    ...
+```
+
+### Predict before you scroll
+
+What do you think the next step needs to handle? Think about it before reading on.
+
+## Step 2: [Second subproblem]
+
+[Continue building incrementally. Show the thinking, not just the code.]
+
+```python
+# Building on step 1
+```
+
+## Step 3: Connecting the pieces
+
+[How steps 1 and 2 fit together. Show the structure, not the full implementation.]
+
+## Common mistakes
+
+| Mistake | Why it happens | How to fix |
+|---------|---------------|------------|
+| [Mistake 1] | [Reason] | [Fix] |
+| [Mistake 2] | [Reason] | [Fix] |
+| [Mistake 3] | [Reason] | [Fix] |
+
+## Testing your solution
+
+Run the tests to check your work:
+
+```bash
+cd <repo-root>/projects/[LEVEL]/[PROJECT]
+pytest -q
+```
+
+What each test verifies:
+- [Test 1]: [What it checks]
+- [Test 2]: [What it checks]
+
+## What to explore next
+
+Now that you have a working solution, try these extensions:
+
+1. [Extension idea 1 — builds on what you just learned]
+2. [Extension idea 2 — introduces a new concept]

guides/DIAGRAM_INDEX.md

@@ -0,0 +1,58 @@
+# Diagram Index
+
+Visual diagrams for every concept in the curriculum. Diagrams use Mermaid syntax, which renders automatically on GitHub and in the mkdocs documentation site.
+
+Each diagram page includes: an overview map, step-by-step execution flow, decision guides for choosing between related patterns, and comparison diagrams.
+
+---
+
+## Beginner Concepts
+
+| Concept | Diagram Page | Diagram Types |
+|---------|-------------|---------------|
+| Variables | [Diagrams](../concepts/diagrams/what-is-a-variable.md) | Memory model, type conversion flow |
+| Loops | [Diagrams](../concepts/diagrams/how-loops-work.md) | For/while flowcharts, loop selection decision tree |
+| Types & Conversions | [Diagrams](../concepts/diagrams/types-and-conversions.md) | Type hierarchy, conversion paths |
+| Functions | [Diagrams](../concepts/diagrams/functions-explained.md) | Call stack, parameter flow |
+| Collections | [Diagrams](../concepts/diagrams/collections-explained.md) | Collection comparison, selection decision tree |
+| Files & Paths | [Diagrams](../concepts/diagrams/files-and-paths.md) | File I/O flow, path resolution |
+| Errors & Debugging | [Diagrams](../concepts/diagrams/errors-and-debugging.md) | Exception hierarchy, try/except flow |
+| Reading Error Messages | [Diagrams](../concepts/diagrams/reading-error-messages.md) | Traceback anatomy, error type decision tree |
+
+## Intermediate Concepts
+
+| Concept | Diagram Page | Diagram Types |
+|---------|-------------|---------------|
+| Imports | [Diagrams](../concepts/diagrams/how-imports-work.md) | Import resolution, package structure |
+| Classes & Objects | [Diagrams](../concepts/diagrams/classes-and-objects.md) | Class hierarchy, MRO, composition |
+| Decorators | [Diagrams](../concepts/diagrams/decorators-explained.md) | Decorator call chain, wrapper flow |
+| Virtual Environments | [Diagrams](../concepts/diagrams/virtual-environments.md) | Venv isolation, package resolution |
+| Comprehensions | [Diagrams](../concepts/diagrams/comprehensions-explained.md) | Data transformation flow |
+| Type Hints | [Diagrams](../concepts/diagrams/type-hints-explained.md) | Type annotation decision tree |
+| Dataclasses | [Diagrams](../concepts/diagrams/dataclasses-explained.md) | Dataclass vs dict vs namedtuple |
+
+## Advanced Concepts
+
+| Concept | Diagram Page | Diagram Types |
+|---------|-------------|---------------|
+| HTTP | [Diagrams](../concepts/diagrams/http-explained.md) | Request/response sequence, status code flow |
+| APIs | [Diagrams](../concepts/diagrams/api-basics.md) | REST flow, authentication sequence |
+| Async/Await | [Diagrams](../concepts/diagrams/async-explained.md) | Event loop, async state machine |
+| Generators | [Diagrams](../concepts/diagrams/generators-and-iterators.md) | Iterator protocol, yield flow |
+| Collections Deep Dive | [Diagrams](../concepts/diagrams/collections-deep-dive.md) | Specialized collection selection |
+
+---
+
+## How to Read Mermaid Diagrams
+
+Mermaid diagrams render automatically on GitHub. If you are viewing these files locally in a text editor, you will see the raw Mermaid syntax. To render them:
+
+1. **GitHub:** Just open the file — diagrams render automatically
+2. **VS Code:** Install the "Mermaid Markdown Syntax Highlighting" extension
+3. **mkdocs site:** Visit the [documentation site](https://travisjneuman.github.io/learn.python)
+4. **Mermaid Live Editor:** Paste the code at [mermaid.live](https://mermaid.live)
+
+---
+
+| [Home](../README.md) |
+|:---:|