docs(v0.3): add #22 Windows support candidate (WSL2 callout + demand-…

docs/planning/v0.3.md

@@ -253,6 +253,71 @@ agent.
 
 ---
 
+### #22 Windows support (WSL2 callout now, native port conditional)
+
+**What**: two-phase Windows story.
+
+- **Phase A (v0.2.x stopgap, ~1hr)**: ship a one-paragraph WSL2 callout
+  in `INSTALL.md` (and a README link). Tells Windows users explicitly:
+  use WSL2 (or Git Bash for read-only commands); native PowerShell is
+  not supported today. Closes the "does atom work on Windows?" question
+  without committing to a port.
+- **Phase B (v0.3+, demand-gated)**: native Windows port — but only if
+  real user demand surfaces. Not speculative.
+
+**Why**: today the README has a single line ("Windows users need Git
+Bash, WSL, or similar") buried at line 53. That's not enough for a
+Windows user to know whether to invest. The cheap callout fixes that.
+The native port is a different question that depends on demand.
+
+**Findings from 2026-05-18 evaluation session** (nucleus session
+`windows-port-eval-1779112103`):
+
+- *Runtime is portable*. The 5 atom CLIs (atom, atom-setup, nucleus,
+  learnings, model-race) are pure Node ESM using `os.homedir()` —
+  `~/.atom` resolves correctly on Windows already.
+- *Bootstrap is where the cost lives*. The bash `atom-setup` bootstrap
+  (shebang + `tr`/`grep`/`sed` PATH-scan) and the symlink-based dev/use
+  globals from the 2026-05-07 separation work are the real blockers.
+  These need PowerShell equivalents or a Node rewrite.
+- *Half-port is a trap*. A native Windows port done halfway is **worse
+  UX than "use WSL2"** — atom-setup installs cleanly, then the user
+  hits Claude Code (officially macOS/Linux/WSL only), Multica, VHS, or
+  Freeze and dead-ends two steps later. If committing to native, the
+  **full downstream chain must be validated on a real Windows box**,
+  not just atom itself.
+- *Cross-platform porting framework*. Separate **bootstrap layer**
+  (bash/PowerShell — where Unix-isms like sudo/EACCES/PATH-scan/
+  symlinks/chmod/exec accumulate) from **runtime layer** (already
+  portable via stdlib abstractions). Audit each independently.
+
+**Open questions** (for Phase B only):
+
+- Is there real user demand, or is this maintainer speculation? Phase A
+  is the demand-detection mechanism — if Windows users hit the WSL2
+  callout and complain, that's signal.
+- Downstream-chain validation: which of Claude Code / Codex / Gemini /
+  Multica / VHS / Freeze actually work on native Windows? Without this
+  audit, a native port is a trap (see above).
+- Bootstrap rewrite path: PowerShell port of `atom-setup` bash, or
+  Node rewrite of the bootstrap so there's one implementation? Node
+  rewrite probably wins long-term but is bigger work.
+- Symlink alternative: Windows symlinks need admin or Developer Mode.
+  Replace with copy-on-install or `.cmd` shims?
+
+**Effort**:
+- Phase A: small (~1hr — one paragraph in INSTALL.md + README link).
+- Phase B: large (bootstrap rewrite + downstream-chain validation +
+  Windows CI). Don't size precisely until Phase A surfaces demand.
+
+**Decision**: Phase A ships in v0.2.x as a cheap stopgap. Phase B is
+**conditionally deferred** — gated on real user demand, not
+speculative porting. Decision pattern: ship the cheap option to keep
+optionality open; the deep option only pays off if users actually
+exist.
+
+---
+
 ## Pre-existing v0.3 deferrals (locked decisions, build deferred)
 
 These were locked during v0.2 planning with full design surface
@@ -288,7 +353,10 @@ it — the embedding column belongs in the DB.
    (semantic) is in scope and on whether scale demands it yet.
 6. **Decide on #17 (research)**. Lowest urgency; defer to v0.4 if
    v0.3 already fills up.
-7. **#19, #20** ride along with whichever wave fits.
+7. **Ship #22 Phase A now (out-of-band v0.2.x)**. WSL2 callout is a
+   ~1hr stopgap independent of the v0.3 wave. Phase B (native port) is
+   demand-gated — re-evaluate after Phase A surfaces signal.
+8. **#19, #20** ride along with whichever wave fits.
 
 ---