# Phase 01: Project Restructuring

**Date:** 2026-02-10
**Status:** Complete

## What Changed

Restructured the project from a linear educational course (30 lessons, 18 exercises, PyQt app skeleton) into an evolving research knowledge base.

### Motivation

The original structure was built to support a Khan Academy-style desktop application. While the physics content was research-grade (91/100 quality assessment), the course format imposed:

- **Fixed linear progression** - concepts locked into lesson sequence
- **Pedagogical overhead** - difficulty levels, time estimates, grading tolerances, learning paths
- **App coupling** - content structured around a PyQt viewer that was never completed
- **Monolithic planning** - a single massive CLAUDE.md documenting every development decision

What we actually need is a **living research system** - a knowledge graph where concepts link to each other, open questions are tracked, and new findings can be integrated without restructuring an entire curriculum.

### What Was Done

1. **Archived** all course scaffolding into `_archive/course/`:
   - 30 lesson markdown files (4 parts, ~10,000 lines)
   - 18 YAML exercise files (525 assessment points)
   - course.json navigation structure
   - PyQt app skeleton (15+ Python files)
   - Learning paths, difficulty metadata, time estimates

2. **Created** `context/` with ~15 coarse topic files:
   - Each is a self-contained research document on one conceptual area
   - YAML frontmatter with relationship metadata and cross-references
   - `[[wiki-link]]` syntax for inline navigation
   - `status` field (established / provisional / speculative)
   - `source_sections` tracing back to spark-physics.txt

3. **Preserved** all research content:
   - `spark-physics.txt` unchanged at root (source of truth)
   - 5 worked examples moved to `examples/`
   - 22 matplotlib images + 15 placeholders moved to `assets/`
   - Glossary (64 terms) updated to reference topic IDs
   - Equations and physical bounds consolidated into `context/equations-and-bounds.md`

4. **Reorganized** utilities:
   - Image generation scripts moved to `tools/`
   - One-time migration script in `tools/update_glossary.py`

### Content Mapping

| Previous (Course) | New (Knowledge Graph) |
|---|---|
| lessons/01-fundamentals/01-introduction.md thru 06 | context/circuit-topology.md |
| lessons/02-optimization/01-02 | context/power-optimization.md |
| lessons/02-optimization/03-05 | context/thevenin-method.md |
| lessons/02-optimization/06 | context/coupled-resonance.md |
| lessons/03-spark-physics/01 | context/field-thresholds.md |
| lessons/03-spark-physics/02-04 | context/energy-and-growth.md |
| lessons/03-spark-physics/05 | context/thermal-physics.md |
| lessons/03-spark-physics/06 | context/streamers-and-leaders.md |
| lessons/03-spark-physics/07 | context/capacitive-divider.md |
| lessons/03-spark-physics/08 | context/empirical-scaling.md |
| lessons/04-advanced-modeling/01-02 | context/lumped-model.md |
| lessons/04-advanced-modeling/03-05 | context/distributed-model.md |
| lessons/04-advanced-modeling/02,04 | context/femm-workflow.md |
| reference/equation-sheet.md + physical-bounds.md | context/equations-and-bounds.md |
| (scattered across lessons) | context/open-questions.md |

### What Was NOT Changed

- `spark-physics.txt` - untouched, remains source of truth
- Physics content accuracy - all formulas and derivations preserved
- Sign conventions - Maxwell matrix conventions preserved
- Peak value convention - all phasors still use peak values

## Metrics

| Metric | Before | After |
|---|---|---|
| Content files | 30 lessons + 18 exercises | ~15 topic files |
| Navigation | course.json (fixed tree) | Cross-references (graph) |
| Entry point | Lesson 1 | Any topic file |
| Adding content | Create lesson, update course.json, add exercise | Edit topic file or create new one |
| Reference lookup | Separate equation-sheet.md | Inline in topic + combined reference |
| Open questions | Buried in Part 12 | Dedicated topic file + per-concept tracking |

## Next Steps

- Expand topic files as research evolves
- Split topics when they exceed ~25k tokens
- Build expert agent backed by spark-physics.txt
- Add new research phases as investigations proceed