docs: link problem generation docs to README graph

Created worksheet README and updated root README to ensure all problem generation documentation is discoverable via linked path. **Documentation Graph:** ``` README.md (root) → apps/web/src/app/create/worksheets/README.md → PROBLEM_GENERATION_ARCHITECTURE.md → USER_WARNING_IMPROVEMENTS.md → .claude/PROBLEM_GENERATION.md ``` **New Files:** - `apps/web/src/app/create/worksheets/README.md` - Overview of worksheet system with links to all documentation **Updated Files:** - `README.md` - Added "Additional Documentation" section with worksheet generator and abacus react component links - `.claude/CLAUDE.md` - Added "Documentation Graph Requirement" at top stating ALL docs must be reachable from root README **Why This Matters:** - Documentation that isn't linked gets forgotten and becomes stale - New developers start at root README and follow links - Ensures docs stay discoverable and maintained - Now enforced as a critical requirement in Claude Code instructions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-12 09:32:29 -06:00 · 2025-11-12 09:32:29 -06:00 · 1a7e81c4e2
parent 13a61e3e3e
commit 1a7e81c4e2
3 changed files with 204 additions and 3 deletions
--- a/README.md
+++ b/README.md
@ -802,13 +802,34 @@ MIT License - see LICENSE file for details.

 ## This project uses DejaVu Sans font (included), which is released under a free license.

+## 📚 Additional Documentation
+
+### Worksheet Generator
+
+**Location**: [`apps/web/src/app/create/worksheets/`](./apps/web/src/app/create/worksheets/)
+**Overview**: [`apps/web/src/app/create/worksheets/README.md`](./apps/web/src/app/create/worksheets/README.md)
+
+Create customizable math worksheets with progressive difficulty, problem space validation, and Typst-powered PDF generation.
+
+**Key Documentation**:
+- **[Problem Generation Architecture](./apps/web/src/app/create/worksheets/PROBLEM_GENERATION_ARCHITECTURE.md)** - Complete technical deep-dive on generation algorithms, strategies, and edge cases
+- **[User Warning Improvements](./apps/web/src/app/create/worksheets/USER_WARNING_IMPROVEMENTS.md)** - UX enhancement plan for problem space warnings
+
+### Abacus React Component
+
+**Package**: `@soroban/abacus-react`
+**Documentation**: [`packages/abacus-react/README.md`](./packages/abacus-react/README.md)
+**Storybook**: [Interactive Examples](https://antialias.github.io/soroban-abacus-flashcards/abacus-react/)
+
+React component library for rendering interactive and static abacus visualizations.
+
 ## 🚀 Active Development Projects

 ### Speed Complement Race Port (In Progress)

-**Status**: Planning Complete, Ready to Implement  
-**Plan Document**: [`apps/web/COMPLEMENT_RACE_PORT_PLAN.md`](./apps/web/COMPLEMENT_RACE_PORT_PLAN.md)  
-**Source**: `packages/core/src/web_generator.py` (lines 10956-15113)  
+**Status**: Planning Complete, Ready to Implement
+**Plan Document**: [`apps/web/COMPLEMENT_RACE_PORT_PLAN.md`](./apps/web/COMPLEMENT_RACE_PORT_PLAN.md)
+**Source**: `packages/core/src/web_generator.py` (lines 10956-15113)
 **Target**: `apps/web/src/app/games/complement-race/`

 A comprehensive port of the sophisticated Speed Complement Race game from standalone HTML to Next.js. Features 3 game modes, 2 AI personalities with 82 unique commentary messages, adaptive difficulty, and multiple visualization systems.
--- a/apps/web/.claude/CLAUDE.md
+++ b/apps/web/.claude/CLAUDE.md
@ -1,5 +1,31 @@
 # Claude Code Instructions for apps/web

+## CRITICAL: Documentation Graph Requirement
+
+**ALL documentation must be reachable from the main README via a linked path.**
+
+When creating new documentation:
+1. ✅ Create the document in the appropriate directory
+2. ✅ Link it from a parent README that eventually links to root README
+3. ✅ Verify the chain: Root README → Area README → Your Document
+
+**Why this matters:**
+- Documentation that isn't linked is invisible and will be forgotten
+- New developers start at root README and follow links
+- Ensures documentation stays discoverable and maintained
+
+**Example chain:**
+```
+README.md (root)
+  → apps/web/src/app/create/worksheets/README.md
+    → PROBLEM_GENERATION_ARCHITECTURE.md
+    → USER_WARNING_IMPROVEMENTS.md
+    → .claude/PROBLEM_GENERATION.md
+```
+
+**Invalid:** Creating `/docs/some-feature.md` without linking from anywhere ❌
+**Valid:** Creating `/docs/some-feature.md` AND linking from root README ✅
+
 ## CRITICAL: Production Dependencies

 **NEVER add TypeScript execution tools to production dependencies.**
--- a/apps/web/src/app/create/worksheets/README.md
+++ b/apps/web/src/app/create/worksheets/README.md
@ -0,0 +1,154 @@
+# Worksheet Generator
+
+**Create customizable math worksheets with progressive difficulty, problem space validation, and Typst-powered PDF generation.**
+
+## Features
+
+- **Addition & Subtraction**: Full support for multi-digit problems (1-5 digits)
+- **Progressive Difficulty**: Smart Mode automatically scales difficulty based on skill level
+- **Problem Space Validation**: Real-time warnings when configurations have limited unique problems
+- **Typst Integration**: High-quality PDF generation with customizable layouts
+- **Display Rules**: Configurable visual aids (carry boxes, ten frames, place-value colors, etc.)
+- **Mastery System**: Adaptive learning with skill tracking and progression
+
+## Quick Start
+
+```typescript
+// Access the worksheet studio at /create/worksheets/addition
+// Configure settings, preview problems, download PDF
+```
+
+## Architecture Documentation
+
+### Core Systems
+
+**Problem Generation** - [`PROBLEM_GENERATION_ARCHITECTURE.md`](./PROBLEM_GENERATION_ARCHITECTURE.md)
+- Complete technical documentation of problem generation algorithms
+- Two generation strategies: generate-all + shuffle (small spaces) vs retry-based (large spaces)
+- Problem space estimation and duplicate risk calculation
+- Edge cases: single-digit constraints, mixed mastery mode, subtraction borrowing
+- Performance considerations and testing guide
+
+**Quick Reference** - [`.claude/PROBLEM_GENERATION.md`](../../../.claude/PROBLEM_GENERATION.md)
+- Fast lookup for developers and Claude Code
+- Strategy selection logic with code examples
+- Debugging commands and common modifications
+- Q&A troubleshooting section
+
+**UX Improvements** - [`USER_WARNING_IMPROVEMENTS.md`](./USER_WARNING_IMPROVEMENTS.md)
+- Recommended UI enhancements for problem space warnings
+- Design mockups for config panel indicators
+- Implementation phases and component structure
+
+### Additional Documentation
+
+- **Configuration Schema** - [`CONFIG_SCHEMA_GUIDE.md`](./CONFIG_SCHEMA_GUIDE.md) - Complete guide to worksheet configuration
+- **Smart Difficulty** - [`addition/SMART_DIFFICULTY_SPEC.md`](./addition/SMART_DIFFICULTY_SPEC.md) - Smart Mode progression spec
+- **Subtraction System** - [`SUBTRACTION_AND_OPERATOR_PLAN.md`](./SUBTRACTION_AND_OPERATOR_PLAN.md) - Subtraction implementation
+
+## Key Concepts
+
+### Problem Space
+
+The "problem space" is the set of all unique problems possible given your constraints:
+
+- **1-digit 100% regrouping**: Only 45 unique problems exist (e.g., 2+8, 3+7, 4+9...)
+- **2-digit mixed regrouping**: ~4,000 unique problems
+- **3-digit problems**: ~400,000 unique problems
+
+**Why it matters**: Requesting more problems than exist in the space results in duplicates. The system warns you when this happens.
+
+### Generation Strategies
+
+**Generate-All + Shuffle** (Small spaces < 10,000)
+- Enumerates all valid problems upfront
+- Shuffles deterministically
+- Zero retries, guaranteed coverage
+- Cycles through full set when requesting more than available
+
+**Retry-Based** (Large spaces ≥ 10,000)
+- Randomly generates problems
+- Retries on duplicates (up to 100 times)
+- Allows some duplicates to prevent performance issues
+
+### Progressive Difficulty
+
+**Smart Mode** - Automatically adjusts difficulty based on:
+- Student skill level (tracked via mastery system)
+- Previous performance
+- Target regrouping/borrowing probability
+
+**Manual Mode** - You control:
+- Digit range (1-5 digits)
+- Regrouping/borrowing probability (0-100%)
+- Progressive vs constant difficulty
+
+## Common Edge Cases
+
+### Single-Digit 100% Regrouping
+
+**Problem**: Only 45 unique problems where both operands are 0-9 and result requires carrying.
+
+**Solution**:
+- Reduce pages to 1-2 (20-40 problems)
+- Lower regrouping to 50%
+- Increase to 2-digit problems
+
+### Mastery + Mixed Mode
+
+**Problem**: Addition and subtraction use separate skill-based configs, making combined problem space estimation complex.
+
+**Solution**: Validation is skipped for this mode. Each operator uses its own config independently.
+
+### Subtraction Multiple Borrowing
+
+**Problem**: 1-2 digit subtraction cannot have 2+ borrow operations (mathematical impossibility).
+
+**Solution**: System automatically falls back to single-borrow problems for these ranges.
+
+## File Structure
+
+```
+worksheets/
+├── README.md (this file)
+├── PROBLEM_GENERATION_ARCHITECTURE.md    # Technical deep-dive
+├── USER_WARNING_IMPROVEMENTS.md          # UX enhancement plan
+├── problemGenerator.ts                   # Core generation logic
+├── utils/
+│   └── validateProblemSpace.ts          # Space estimation
+├── components/
+│   ├── config-panel/                    # Configuration UI
+│   └── worksheet-preview/               # Preview + warnings
+│       ├── WorksheetPreviewContext.tsx  # Validation state
+│       └── DuplicateWarningBanner.tsx   # Warning display
+└── addition/
+    ├── SMART_DIFFICULTY_SPEC.md         # Smart Mode spec
+    └── page.tsx                         # Addition worksheet page
+```
+
+## Testing
+
+```bash
+# Type check
+npm run type-check
+
+# Run all checks before committing
+npm run pre-commit
+```
+
+See `PROBLEM_GENERATION_ARCHITECTURE.md` for comprehensive testing checklist.
+
+## Contributing
+
+When modifying problem generation:
+
+1. Read `PROBLEM_GENERATION_ARCHITECTURE.md` for complete system understanding
+2. Check `.claude/PROBLEM_GENERATION.md` for quick reference
+3. Run the testing checklist
+4. Update inline comments if changing generation strategy
+5. Consider UX impact (see `USER_WARNING_IMPROVEMENTS.md`)
+
+## Related Documentation
+
+**Parent**: [`apps/web/README.md`](../../../README.md) - Web application overview
+**Abacus Component**: [`packages/abacus-react/README.md`](../../../../../packages/abacus-react/README.md) - Abacus visualization library