feat: add custom user-provided markdown lessons

Implement support for user-provided markdown lessons loaded from custom directories.
Users can now create personalized typing practice content with preserved formatting.

Core Features:
- Load lessons from ~/.config/typer-cli/custom/ and ./custom/
- YAML front matter support for metadata (title, description)
- Manual YAML parser (zero new dependencies)
- Automatic title deduplication with (1), (2) suffix
- Graceful error handling with stderr warnings
- Empty state UI with helpful instructions

Implementation:
- New module: src/content/custom.rs (350+ lines)
- Custom category with Blue color scheme
- Preserved formatting (line breaks, spacing, indentation)
- Statistics tracking using lesson title as identifier
- File size limit (1MB) with validation

Testing:
- 11 new unit tests (146 total passing)
- Zero clippy warnings
- Full code formatting compliance

Documentation:
- Feature docs (requirements.md, design.md, tasks.md)
- User guide in README.md with examples
- Updated contributor docs and AI context
- Complete tasks checklist

Files Modified:
- New: src/content/custom.rs
- New: docs/features/custom-lessons/ (3 files)
- Modified: 10 existing files
- Updated: .gitignore (ignore /custom directory)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Author: jrollin

.gitignore

@@ -1 +1,2 @@
 /target
+/custom

CLAUDE.md

@@ -18,12 +18,14 @@ Quick reference for AI assistants working on this project.
 **Phase 3.2: Finger Training** - ✅ Completed
 **Phase 3.3: Two-Level Menu System** - ✅ Completed
 **Phase 3.4: Menu Grouping** - ✅ Completed
+**Phase 3.5: Statistics Dashboard** - ✅ Completed
 **Phase 3.6: AltGr Modifier Support** - ✅ Completed
+**Phase 3.7: Custom Lessons** - ✅ Completed
 **Current Focus**: Phase 3+ (Analytics visualization, data export, gamification)
 
 ## Dead Code Annotations
 
-The codebase contains **28 intentional `#[allow(dead_code)]` annotations** marking Phase 3+ features that are:
+The codebase contains **29 intentional `#[allow(dead_code)]` annotations** marking Phase 3+ features that are:
 - Fully tested and ready for future implementation
 - Strategic placeholders for planned features (analytics, export, multi-layout support)
 - Preserved to avoid reimplementation work
@@ -40,6 +42,7 @@ These are NOT technical debt - they represent well-architected future functional
 - Test Utilities (3): Reusable drill generation patterns
 - Adaptive Features (2): WeaknessDetector (fully tested, ready for UI)
 - Scoring Utilities (1): calculate_accuracy() reference implementation
+- Custom Lesson Validation (1): ParseError::InvalidFrontMatter for future strict YAML validation
 
 ## Project Overview
 
@@ -52,7 +55,7 @@ This project uses feature-based documentation. See [docs/README.md](docs/README.
 - Steering documents (product, tech, structure)
 - Feature documentation organization
 
-**77 lessons** across 5 categories: Adaptive, Finger Training, Key Training, Languages, Code
+**77 lessons** across 6 categories: Adaptive, Finger Training, Key Training, Languages, Code, Custom
 
 | Feature | Module | Status |
 |---------|--------|--------|
@@ -65,6 +68,7 @@ This project uses feature-based documentation. See [docs/README.md](docs/README.
 | Finger Training | `src/content/finger_generator.rs` | ✅ Phase 3.2 |
 | Two-Level Menu | `src/content/category.rs`, `app.rs` | ✅ Phase 3.3 |
 | Statistics Dashboard | `src/ui/render.rs` | ✅ Phase 3.5 |
+| Custom Lessons | `src/content/custom.rs` | ✅ Phase 3.7 |
 
 See [docs/README.md#features-overview](docs/README.md#features-overview) for detailed feature descriptions.
 
@@ -73,7 +77,7 @@ See [docs/README.md#features-overview](docs/README.md#features-overview) for det
 ```bash
 # Development
 cargo run              # Launch application
-cargo test             # Run test suite (129 tests)
+cargo test             # Run test suite (146 tests)
 cargo check            # Fast compilation check
 
 # Testing Adaptive Mode
@@ -96,7 +100,7 @@ git push origin v0.2.0 # Push tag to trigger automated release
 ## CI/CD Workflows
 
 ### Continuous Integration
-Runs on every push to `main` and all PRs: formatting, linting, tests (129 passing), security audit.
+Runs on every push to `main` and all PRs: formatting, linting, tests (146 passing), security audit.
 
 ### Release Automation
 Triggers on git tag `v*.*.*`:
@@ -130,6 +134,7 @@ src/
 │   ├── adaptive_generator.rs  # Personalized content
 │   ├── bigram_generator.rs    # Bigram practice
 │   ├── code_generator.rs      # Code symbols
+│   ├── custom.rs              # User-provided markdown lessons
 │   ├── finger_generator.rs    # Finger-based drills
 │   ├── lesson.rs              # Lesson types, definitions
 │   └── generator.rs           # Home row drills
@@ -163,9 +168,9 @@ See [docs/features/session-storage/](docs/features/session-storage/) for complet
 
 ## Current Status
 
-**Phase**: 3.5 Complete (Statistics Dashboard)
+**Phase**: 3.7 Complete (Custom Lessons)
 **Next**: Phase 3+ (Analytics visualization, data export, gamification)
-**Tests**: 129 passing
-**Lessons**: 77 total
+**Tests**: 146 passing
+**Lessons**: 77 built-in + user custom lessons
 
 See [docs/README.md#project-status](docs/README.md#project-status) for complete roadmap.

README.md

@@ -178,6 +178,58 @@ Session statistics are saved to `~/.config/typer-cli/stats.json`.
 The file contains session history and adaptive analytics for personalized training.
 See [docs/features/session-storage/](docs/features/session-storage/) for data schema details.
 
+## Custom Lessons
+
+Create your own typing lessons by placing markdown files in `~/.config/typer-cli/custom/` or `./custom/` (current directory).
+
+### Markdown Format
+
+Custom lessons use markdown files with optional YAML front matter:
+
+```markdown
+---
+title: My Custom Lesson
+description: Practice domain-specific vocabulary
+---
+
+Your custom content to practice goes here.
+Line breaks and spacing are preserved.
+Multiple lines are supported.
+```
+
+### Features
+
+- **Two locations**: Config directory (`~/.config/typer-cli/custom/`) or current directory (`./custom/`)
+- **YAML front matter**: Optional metadata with `title` and `description` fields
+- **Title fallback**: If no front matter, filename (without .md) is used as title
+- **Preserved formatting**: Line breaks, spacing, and indentation are maintained during practice
+- **Automatic deduplication**: Duplicate titles get (1), (2) suffix
+- **Statistics tracking**: Session stats saved using lesson title as identifier
+- **Error handling**: Invalid files show warnings but don't crash the application
+
+### Example
+
+1. Create `~/.config/typer-cli/custom/git-commands.md`:
+   ```markdown
+   ---
+   title: Git Commands Practice
+   description: Common git operations
+   ---
+
+   git status
+   git add .
+   git commit -m "feat: add feature"
+   git push origin main
+   git pull --rebase
+   git branch -d feature-branch
+   ```
+
+2. Launch Typer CLI and select "Custom" category
+3. Choose "Git Commands Practice" from the lesson list
+4. Practice with preserved formatting and line breaks
+
+See [docs/features/custom-lessons/](docs/features/custom-lessons/) for complete documentation.
+
 ## Development
 
 ### Build and Run
@@ -188,7 +240,7 @@ cargo build --release  # Build optimized binary
 
 ### Tests
 ```bash
-cargo test             # Run test suite (129 passing tests)
+cargo test             # Run test suite (146 passing tests)
 ```
 
 ### Code Quality

docs/README.md

@@ -210,6 +210,20 @@ Performance analytics dashboard with visual keyboard heatmap.
 - Accessible via 's' key from main menu
 - Graceful placeholder when no analytics data exists
 
+#### [custom-lessons/](features/custom-lessons/) ✅ COMPLETED
+User-provided markdown lessons for personalized typing practice.
+
+**Module**: `src/content/custom.rs`
+
+- Load from `~/.config/typer-cli/custom/` and `./custom/`
+- YAML front matter support (title, description)
+- Automatic deduplication of titles with (1), (2) suffix
+- Preserved formatting (line breaks, spacing, indentation)
+- New "Custom" category in menu
+- Stats tracking with lesson title as identifier
+- Graceful error handling with warning messages
+- No external dependencies (uses std library only)
+
 ### Future Features (Phase 3+)
 
 - **Enhanced analytics** - Trend graphs, progress charts over time, session history visualization
@@ -283,9 +297,9 @@ Module locations are documented in each feature's design.md:
 
 ## Project Status
 
-**Current Phase**: Phase 3.5 Complete (Statistics Dashboard) ✓
+**Current Phase**: Phase 3.6 Complete (Custom Lessons) ✓
 
-**Total Tests**: 129 passing
+**Total Tests**: 146 passing
 - 13 tests: typing-session
 - 7 tests: home-row-lessons
 - 12 tests: bigram-training
@@ -297,6 +311,8 @@ Module locations are documented in each feature's design.md:
 - 2 tests: keyboard-layout
 - 3 tests: content generation
 - 1 test: data structures
+- 11 tests: custom lessons
+- 54 tests: other features (trigrams, common words, finger training, etc.)
 
 **Completed Features**:
 - Phase 1: Home row Level 1 ✓
@@ -312,6 +328,7 @@ Module locations are documented in each feature's design.md:
 - Phase 3.3: Two-level menu system ✓
 - Phase 3.4: Menu grouping ✓
 - Phase 3.5: Statistics dashboard ✓
+- Phase 3.6: Custom lessons ✓
 
 **Total Lessons**: 77 (52 standard + 24 finger training + 1 adaptive)