Three small doc/template inaccuracies, all surfaced while reviewing #485. None affect behavior.
1. detect_multiplexers' "Never raises" is false
src/bmad_loop/adapters/multiplexer.py:647 promises "Never raises — this feeds diagnostics, which must work on a misconfigured host." Its two loader calls, _load_builtin_backends() and _load_external_backends() (multiplexer.py:652-653), sit outside the internal try, so the function can raise.
The caller is right and the docstring is the stale half: platform_preflight wraps the call and now reports the failure as mux.backends-detected at warning (src/bmad_loop/runsetup.py:534-543), and both the CHANGELOG and docs/FEATURES.md treat that raise as reachable. Pre-existing — #485 only made the contradiction visible by acting on it.
2. The bug-report template's diagnose fallback is unreachable before a first run
.github/ISSUE_TEMPLATE/bug-report.yaml tells a reporter whose selection: line was replaced by a forced reason that "bmad-loop diagnose reports sys.platform either way". But cmd_diagnose prints no runs found to stderr and returns 1 when no run dirs exist (src/bmad_loop/cli.py:2990-2992) — it emits no Environment block at all. Someone diagnosing a broken install before their first successful run gets sys.platform from neither surface, which is exactly the reporter this prompt is aimed at.
CodeRabbit's original suggestion on #485 covered that case (unset the env var, or bmad-loop mux set --clear, then re-run validate); the wording that landed dropped it.
Separately: the Windows (WSL) dropdown option cannot distinguish WSL-with-the-Linux-build (supported) from WSL-with-the-win32-build (the #332 bug) — both reporters pick the same option, which is the ambiguity the #332 work exists to resolve.
3. _platform_preflight is attributed to the wrong module in two docs
docs/porting-to-a-new-os.md:263 and docs/ROADMAP.md:29 point at src/bmad_loop/cli.py for _platform_preflight(project). The body lives in runsetup.platform_preflight (src/bmad_loop/runsetup.py:478); cli.py:88 is only a re-export kept so the test suite's monkeypatch bites. Pre-existing, but porting-to-a-new-os.md is precisely the doc that tells a porter where to look.
Three small doc/template inaccuracies, all surfaced while reviewing #485. None affect behavior.
1.
detect_multiplexers' "Never raises" is falsesrc/bmad_loop/adapters/multiplexer.py:647promises "Never raises — this feeds diagnostics, which must work on a misconfigured host." Its two loader calls,_load_builtin_backends()and_load_external_backends()(multiplexer.py:652-653), sit outside the internaltry, so the function can raise.The caller is right and the docstring is the stale half:
platform_preflightwraps the call and now reports the failure asmux.backends-detectedat warning (src/bmad_loop/runsetup.py:534-543), and both the CHANGELOG anddocs/FEATURES.mdtreat that raise as reachable. Pre-existing — #485 only made the contradiction visible by acting on it.2. The bug-report template's
diagnosefallback is unreachable before a first run.github/ISSUE_TEMPLATE/bug-report.yamltells a reporter whoseselection:line was replaced by a forced reason that "bmad-loop diagnosereportssys.platformeither way". Butcmd_diagnoseprintsno runs foundto stderr and returns 1 when no run dirs exist (src/bmad_loop/cli.py:2990-2992) — it emits no Environment block at all. Someone diagnosing a broken install before their first successful run getssys.platformfrom neither surface, which is exactly the reporter this prompt is aimed at.CodeRabbit's original suggestion on #485 covered that case (unset the env var, or
bmad-loop mux set --clear, then re-runvalidate); the wording that landed dropped it.Separately: the
Windows (WSL)dropdown option cannot distinguish WSL-with-the-Linux-build (supported) from WSL-with-the-win32-build (the #332 bug) — both reporters pick the same option, which is the ambiguity the #332 work exists to resolve.3.
_platform_preflightis attributed to the wrong module in two docsdocs/porting-to-a-new-os.md:263anddocs/ROADMAP.md:29point atsrc/bmad_loop/cli.pyfor_platform_preflight(project). The body lives inrunsetup.platform_preflight(src/bmad_loop/runsetup.py:478);cli.py:88is only a re-export kept so the test suite's monkeypatch bites. Pre-existing, butporting-to-a-new-os.mdis precisely the doc that tells a porter where to look.