Spec

1. Read the request, relevant code, and linked material.
2. Resolve decisions that would change behavior, interfaces, data, errors, or tests. Ask one question at a time and recommend an answer. Stop if broad architecture is still undecided.
3. Write docs/<feature-slug>/spec.md using the template below. Keep it short and omit sections that do not apply.
4. Stop for human review. Do not plan or implement.

# <Title>

## Summary
What we are building, why, and the chosen approach.

## Requirements
- Observable, testable behavior.

## Design
Important components, data flow, and implementation decisions.