docs(web): drop migration-history framing from store docstrings (LUM-1752)

[ashleeradka]

Summary

Clean up the 5 module-level docstrings (and one inline comment) flagged in LUM-1752 — opens with "Replaces the React Context-based X with..." / "previously lived in Y" / "Matches the old React Query behavior" are now rewritten to describe what each store does today.

Per the STYLE_GUIDE rule added in #31354.

Files

• apps/web/src/stores/auth-store.ts — module docstring leads with session lifecycle (allauth probe, focus/visibility refresh, cross-tab BroadcastChannel) instead of the React-Context-replacement narrative.
• apps/web/src/stores/organization-store.ts — module docstring + the setupOrganizationStore focus-refetch comment. Behavior described directly (refetch on focus when older than STALE_TIME_MS) instead of by comparison to React Query.
• apps/web/src/domains/nudges/nudge-store.ts — module docstring (kept the persist + cross-tab sync detail, dropped the "useSyncExternalStore that previously lived in..." opener and the "platform deployment" reference). Also retitled the section header above computeInitialFromLegacy to avoid framing the on-first-load seeding step as "legacy".
• apps/web/src/domains/onboarding/onboarding-store.ts — module docstring (kept the substantive "why not Zustand persist" rationale, dropped the migration narrative and the "preserving the original" framing). The privacy-safe-default reasoning that motivates the per-key writes is now self-contained.

Out of scope (intentionally not touched)

• computeInitialFromLegacy function name — renaming the symbol is a wider change than the ticket asked for (docstrings + one inline comment).
• // Initial state ... seeded from per-key localStorage entries on first load is the surviving section header for that block; the function still describes a real runtime concern (seeding the store on first load from per-key entries), so the seeding step itself is documented, just without the "legacy" framing.

Test plan

• bun test src/stores/ src/domains/nudges/ src/domains/onboarding/ — 32 / 32 pass
• bunx tsc --noEmit — clean
• bun run lint on the 4 touched files — clean
• Acceptance grep: grep -rnE 'Replaces the|previously lived|Matches the old' apps/web/src --include='*.ts' --include='*.tsx' returns nothing

https://claude.ai/code/session_018S9mQ5rmtUAvixYCcmXJaZ

---

Generated by Claude Code

[linear]

LUM-1752

[vex-assistant-bot]

✦ APPROVE

Documentation-only — no behavior changes. All four files follow the STYLE_GUIDE rule from #31354: docstrings lead with what the store does today, not where it came from.

Each rewrite is an improvement:

• auth-store.ts — new opener leads with session lifecycle behavior (allauth probe, focus/visibility refresh, BroadcastChannel) instead of the "Replaces React Context" frame. The "read from anywhere" rationale is now embedded in the lifecycle sentence where it belongs.
• organization-store.ts — "Owns the organization list and active-organization selection" is immediately useful. The dropped inline comment ("Matches the old React Query refetchOnWindowFocus + staleTime behavior") is replaced by a behavior description that's actually more informative — it explains why the stale check exists (rapid focus events on fresh data).
• nudge-store.ts — "Owns whether each nudge has been actioned or dismissed and when" is much clearer than the useSyncExternalStore archaeology. Seed-from-per-key description now explains the keys without "legacy" or "platform deployment" framing. Section header ("hydrate from legacy per-key localStorage entries" → "seeded from per-key localStorage entries on first load") adds timing context and drops the loaded word.
• onboarding-store.ts — the new per-key write rationale is actually more informative: "so a field that was never explicitly set stays absent in localStorage — keeping the privacy-safe default intact" makes the invariant explicit where before it was implied by migration history.

computeInitialFromLegacy name left as-is — correct call. Renaming a function is wider than a docstring pass and the PR body calls it out explicitly.

Anti-patterns KB: nothing to flag (no code changes).

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.