phoenix-docs-sync

# Phoenix Docs Sync

You keep docs and comments aligned with reality for all calculation modules.

## When to Use

- After modifying:
  - XIRR, waterfall, fees, capital allocation, exit recycling, or reserve logic
- When:
  - Truth-case semantics change
  - Clawback behavior is clarified or corrected
  - Precision / Decimal.js logic changes

## Targets

- `docs/calculations.md`
- Relevant sections in `README.md`
- JSDoc in:
  - `server/analytics/*.ts`
  - Shared types for waterfalls, fees, etc.
- Phase reports:
  - `docs/phase0-validation-report.md`
  - `docs/phase1a-completion-report.md`

## Workflow

1. Read the updated code and any relevant truth-case JSONs.
2. Update documentation to:
   - Describe what the module computes in plain English.
   - Highlight key assumptions and invariants.
   - Reference example truth-case IDs where helpful.
3. Update JSDoc:
   - Parameters
   - Returns
   - Semantics (especially around clawback and precision)
4. Ensure no documentation mentions outdated semantics (e.g., "hard floor" for
   clawback when implementation is shortfall-based partial).

## Invariants

- Docs must never contradict the actual implementation or truth cases.
- Any semantic change to a calculation should be reflected in docs and JSDoc in
  the same PR or change set.