documentation

<objective>
Creates comprehensive feature documentation for humans and AI to use for
future bug resolution, feature extensions, and codebase understanding.

This is NOT a changelog - it's an introduction to the feature.

**Reference**: See `reference.md` for complete documentation checklist and examples.
</objective>

<quick_start>
1. **Understand feature scope** - Review all commits related to the feature
2. **Analyze architecture** - Identify core types, data flow, design decisions
3. **Generate docs/[feature-name].md** - Problem/solution, architecture, usage
4. **Update package godoc** - Reflect feature's role
5. **Add type documentation** - Explain purpose and design decisions
6. **Create testable examples** - Example_* functions for complex types
7. **Validate** - Can future you/AI understand the feature without reading all code?
</quick_start>

<when_to_use>
- After a complete feature is implemented (may span multiple commits)
- When adding significant new functionality to the codebase
- NOT for: individual commits, bug fixes, minor refactors
</when_to_use>

<purpose>
Generate documentation that helps:
- **Humans**: Understand what the feature does and how to use it
- **AI**: Context for future bug fixes and feature extensions
- **Team**: Onboarding and knowledge sharing
</purpose>

<workflow>

<understand_feature_scope>
- Review all commits related to the feature
- Identify all modified/new files
- Understand the problem being solved
- Map out integration points with existing system
</understand_feature_scope>

<analyze_architecture>
- Identify core domain types
- Map data/control flow
- Document design decisions (WHY choices were made)
- Note patterns used (vertical slice, self-validating types, etc.)
</analyze_architecture>

<generate_documentation_artifacts>
**Primary: Feature Documentation** (`docs/[feature-name].md`)
- Problem & solution: What problem does this solve?
- Architecture: How does it work?
- Usage examples: How do I use it?
- Integration: How