docs(rfc): RFC-CLIENT-0003 — one installer core: Linux-first, thin OS adapters

[LukasWodka]

Summary

Adds RFC-CLIENT-0003 — One installer core: Linux-first, thin OS adapters (docs/rfcs/0003-one-installer-core.md), the strategy decision from the 2026-07 multi-environment installer sweep (epic tracebloc/backend#1285, 25 children).

Core proposal:

• D1/D2: the Linux bash core is the implementation; macOS stays a thin adapter (brew bypass consolidated via fix(installer): macOS installs tools via bare brew — version pins inoperative, no checksums, no execute-gate #429); the Windows PowerShell monolith is replaced by a WSL2 bootstrap adapter running the bash core inside WSL — gated on the RFC-CLIENT-0001 rootless validation passing inside WSL2 on managed hardware (direction already stated in tracebloc/backend#1179; also removes the Docker Desktop licensing burden for large orgs).
• D3/D4 (immediate): single-source installer facts (versions, hosts, timeouts, floors) + a CI behavior-parity gate — the k3d-pin drift (fix(installer): pin the k3d release (K3D_VERSION) — deterministic, rate-limit-proof installs #382 → fix(installer): pin k3d + helm versions in install-k8s.ps1 — drop api.github.com latest lookups #410) is the motivating incident.
• D5 (immediate): a real Windows e2e leg regardless of the gate outcome — Windows lags structurally because windows-latest can't nest virtualization, so the PS installer only ever gets mocked Pester.
• Interim rule: Wave-1/2 PS correctness fixes proceed (hospital installs are live); no new large PS-only subsystems — feat(installer): resume after reboot + install state file (fast idempotent re-runs) #420 is explicitly gated.

Type

Docs (RFC — decision record)

Test plan

Docs-only; no installer script, chart, or workflow touched. Verified the document renders, the qualified-ID header matches the RFC-CLIENT-0001/0002 convention, next free number in this repo is 0003 (0002 is in-flight on #369), and no customer names or internal hostnames appear (public repo).

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only RFC; no installer scripts, CI workflows, or runtime behavior change in this PR.

Overview
Adds RFC-CLIENT-0003 (docs/rfcs/0003-one-installer-core.md), a decision record for installer architecture after the tracebloc/backend#1285 multi-OS sweep.

It proposes D1/D2: treat the Linux bash core as the single behavioral implementation, keep macOS as a thin adapter (brew paths consolidated per #429), and eventually replace the Windows PowerShell monolith with a WSL2 bootstrap that runs the bash core inside WSL—gated on RFC-CLIENT-0001 rootless validation on managed Windows hardware; PowerShell stays the supported path until then.

D3–D5 are called out for near-term adoption: a shared machine-readable facts spec with CI drift checks, a feature×OS parity matrix in CI, and a real Windows e2e leg (not mocked Pester only). An interim rule allows Wave-1/2 PS fixes for live installs but blocks new large PS-only subsystems (e.g. #420 gated on the D2 outcome).

^{Reviewed by Cursor Bugbot for commit dfa7fa1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit dfa7fa1. Configure here.}

[shujaatTracebloc]

Reviewed — approving.

Docs-only RFC (single new file docs/rfcs/0003-one-installer-core.md), CI fully green including Cursor Bugbot (0 findings), no open review threads.

Verified the content, not just the format:

• All 8 client-side references are accurate — #382 (closed, k3d pin in bash), #410 (pin missing in PS install-k8s.ps1), #429 (macOS bare-brew bypass), #411 (execute-gate), #426 (k3d/helm timeouts), #423 (Windows error-surface), #412 (Windows infinite spinner), #420 (resume/state engine, correctly flagged as gated by the interim rule). Each title matches the claim it supports.
• Backend epic refs check out — #1285 (installer sweep epic), #1179 (Windows/WSL2 least-privilege child), #1168 (least-privilege epic).
• Numbering is correct — 0003 is the next free slot; 0002 is legitimately in-flight on #369, which adds the file at 0002-least-privilege-install.md — exactly the path this RFC's relative link targets, so that link resolves once #369 merges.
• No customer names or internal hostnames (public repo). Renders correctly.

Non-blocking: the ./0002-least-privilege-install.md link is a soft-dangling reference on develop until #369 merges, but the filename matches and the in-flight status is noted inline — it self-heals on merge order. Nothing to change here.