docs(switch): document CI selftest, fused PR builds, release hard-fail

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -239,7 +239,8 @@ target is pinned [love-nx](https://github.com/retronx-team/love-nx)
 - Players: [docs/switch-install.md](docs/switch-install.md) — download the
   NRO, copy to the SD, title-override launch, import your own legal ROM.
 - Builders: [docs/switch-build.md](docs/switch-build.md) — `--fetch` /
-  `--loose` / `--fused`, toolchain, Docker fallback, runner notes.
+  `--loose` / `--fused`, toolchain, Docker fallback, and **CI vs release**
+  (path-gated ubuntu selftest, canonical fused PR artifact, release hard-fail).
 
 For WIP status, Dusklight-derived method, limitations, and how we tested,
 see [docs/switch-development.md](docs/switch-development.md) and

docs/switch-build.md

@@ -125,18 +125,47 @@ bash scripts/switch/verify_payload.sh --self-test
 
 ---
 
-## Release Mac runner
+## CI and release
 
-GitHub Releases build the Switch artifact on the same self-hosted Mac runner
-as the other platforms (see `.github/workflows/release.yml`):
+Switch packaging has three automated surfaces (same policy as AD-010):
+
+### Path-gated PR / push CI (`.github/workflows/ci.yml`)
+
+When a change touches Switch packaging paths
+(`scripts/build_switch.sh`, `scripts/switch/**`, `docs/switch-build.md`, or the
+Switch-related workflow YAML), CI runs:
+
+1. **Offline selftest** on `ubuntu-latest` (forks **and** the canonical repo):
+   `scripts/switch/selftest_build_switch.sh`,
+   `scripts/switch/verify_payload.sh --self-test`, and
+   `luajit tests/switch_ci_workflows_test.lua`.
+2. **Fused NRO build** only on the **canonical** repository
+   (`bryanthaboi/gen1recomp`), on the self-hosted Mac runner
+   (`scripts/build_switch.sh --fetch --fused`). Forks skip the fused job —
+   they still get the ubuntu selftest.
+3. On successful PR fused builds, a follow-up workflow posts a PR comment
+   linking the Actions artifact named `gen1recomp-switch-nro`
+   (comment tag `switch-build-result`; see
+   `.github/workflows/switch-artifact-comment.yml`).
+
+Unrelated PRs do not burn the self-hosted Mac on Switch packaging.
+
+### Release hard-fail (`.github/workflows/release.yml`)
+
+GitHub Releases always build Switch on the same self-hosted Mac runner as the
+other platforms — this is a **hard gate** (no `continue-on-error`):
 
 ```sh
 scripts/build_switch.sh --fetch --fused --version "<release version>"
 ```
 
-The runner must have **native switch-tools** (`nacptool`/`elf2nro`) **and/or
-Docker** available. CI does not silently run `dkp-pacman -S`; keep the runner
-image/host provisioned per this guide.
+A Switch packaging failure fails the entire release job.
+
+### Runner provisioning
+
+The self-hosted Mac runner must have **native switch-tools** (`nacptool` /
+`elf2nro`) **and/or Docker** available. CI and release do not silently run
+`dkp-pacman -S`; keep the runner image/host provisioned per this guide.
 
 ---
 

docs/switch-development.md

@@ -79,6 +79,7 @@ Goal for a finished release is closer to Dusklight’s **single self-contained `
 | Layer | What | Where |
 | ----- | ---- | ----- |
 | Unit / headless | Platform NX flags, RomImporter inbox, dual-path input, mod zip inbox, display chords, payload/self-tests | `tests/*`, `scripts/test.sh` |
+| Switch CI / packaging | Path-gated offline selftest (`selftest_build_switch.sh`, `verify_payload.sh --self-test`, `switch_ci_workflows_test.lua`); canonical fused PR artifact | `.github/workflows/ci.yml`, [switch-build.md](switch-build.md) § CI and release |
 | Probe on hardware | `getOS()==NX`, 1280×720, save path, Joy-Con events | `tools/switch-probe` → OLED |
 | Integration on hardware | MTP inbox ROM import, Play Red/Blue, naming A/B, quit/reopen save, suspend×10, reboot, fused NRO alone + NRO-only update | `docs/switch-hardware-evidence.md` |
 | Not done yet | Docked soak, ≥30 min long-play, non-OLED, automated/`nxlink` deploy | Matrix deferred / absent rows |

tests/switch_ci_workflows_test.lua

@@ -98,6 +98,29 @@ mustContain(comment_wf, "View workflow run", "switch-artifact-comment")
 mustContain(comment_wf, "izhangzhihao/delete-comment@master", "switch-artifact-comment")
 mustContain(comment_wf, "thollander/actions-comment-pull-request@v3", "switch-artifact-comment")
 
+-- --- SWCI-08 / SWCI-09: docs CI vs release ---
+local build_doc = read("docs/switch-build.md")
+local development = read("docs/switch-development.md")
+local readme = read("README.md")
+
+mustContain(build_doc, "Path-gated", "switch-build.md")
+mustContain(build_doc, "ubuntu-latest", "switch-build.md")
+mustContain(build_doc, "selftest_build_switch.sh", "switch-build.md")
+mustContain(build_doc, "canonical", "switch-build.md")
+mustContain(build_doc, "gen1recomp-switch-nro", "switch-build.md")
+mustContain(build_doc, "switch-build-result", "switch-build.md")
+mustContain(build_doc, "hard gate", "switch-build.md")
+mustContain(build_doc, "continue-on-error", "switch-build.md")
+mustContain(build_doc, "nacptool", "switch-build.md")
+mustContain(build_doc, "Docker", "switch-build.md")
+mustContain(build_doc, "Forks skip", "switch-build.md")
+
+mustContain(development, "Switch CI", "switch-development.md")
+mustContain(development, "selftest_build_switch.sh", "switch-development.md")
+
+mustContain(readme, "CI vs release", "README.md")
+mustContain(readme, "switch-build.md", "README.md")
+
 -- --- SWCI-08: release Switch hard-fail (no continue-on-error on build/stage) ---
 do
   local start = release:find("- name: Build Switch", 1, true)