Phase 2 of the codebase audit trilogy (phase 1 = #494). Apply the Code Documentation Policy (internal-docs/Operations/Code Documentation Policy.md) across the codebase:
- WHY-comments on non-obvious decisions, constraints, invariants, gotchas (ordering dependencies, platform quirks, security-sensitive steps) — the priority per the policy and the audit findings.
- JSDoc on exports whose purpose/contract is not evident from name + types (skip trivial ones — no noise).
- English only; never restate the code; do not strip existing comments.
Scope: src/main/, src/preload/, src/renderer/src/** (lib, hooks, components). Phase 1 audit already mapped the least-readable spots (boot/tray/close state machine, kill pipeline nuances, dirty-state machinery).
Phase 3 (health check report) follows after this lands.
Phase 2 of the codebase audit trilogy (phase 1 = #494). Apply the Code Documentation Policy (internal-docs/Operations/Code Documentation Policy.md) across the codebase:
Scope: src/main/, src/preload/, src/renderer/src/** (lib, hooks, components). Phase 1 audit already mapped the least-readable spots (boot/tray/close state machine, kill pipeline nuances, dirty-state machinery).
Phase 3 (health check report) follows after this lands.