fix: run the suite so its package setup applies

The documented command, discover tests, makes tests/ the top level,
so tests/__init__.py never ran and the variable it sets to keep tests
offline was missing from every local run. Every documented and CI
run now passes -s tests -t ., and a test requires it.

.github/workflows/validate.yml

@@ -156,7 +156,7 @@ jobs:
         # resolved. The download tests mock the network and clear it.
         env:
           RETROBIOS_OFFLINE: "1"
-        run: python -m unittest discover tests -v
+        run: python -m unittest discover -s tests -t . -v
 
   label-pr:
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -42,7 +42,7 @@ Full walkthrough: [profiling guide](https://abdess.github.io/retrobios/wiki/prof
 ## Before opening a PR
 
 ```bash
-python -m unittest discover tests
+python -m unittest discover -s tests -t .
 python scripts/pipeline.py --offline
 ```
 

scripts/generate_readme.py

@@ -722,7 +722,7 @@ Full walkthrough: [profiling guide]({link("wiki/profiling")}).
 ## Before opening a PR
 
 ```bash
-python -m unittest discover tests
+python -m unittest discover -s tests -t .
 python scripts/pipeline.py --offline
 ```
 

tests/test_audit_regressions.py

@@ -3563,6 +3563,20 @@ class TestsRunOffline(unittest.TestCase):
     def test_the_package_forbids_downloads(self):
         self.assertTrue(os.environ.get("RETROBIOS_OFFLINE"))
 
+    def test_every_documented_run_imports_the_package(self):
+        """`discover tests` makes tests/ the top level, so tests/__init__.py,
+        which sets RETROBIOS_OFFLINE, never ran: a local run of the documented
+        command queried the release and wrote into the shared cache. Only CI,
+        which sets the variable itself, was offline."""
+        import subprocess
+
+        listed = subprocess.run(
+            ["git", "grep", "-n", "unittest discover", "--", ":!tests"],
+            capture_output=True, text=True, cwd=ROOT, check=False,
+        ).stdout.splitlines()
+        self.assertTrue(listed)
+        self.assertEqual([line for line in listed if "-t ." not in line], [])
+
 
 
 class TheWantedPageCountsRomsetMembers(unittest.TestCase):

wiki/architecture.md

@@ -339,7 +339,7 @@ subset:
 | artifact modules | deterministic ZIPs, locking, large-file cache, pack integrity and portable paths |
 
 ```bash
-python -m unittest discover tests -v      # full suite
+python -m unittest discover -s tests -t . -v   # full suite
 python -m unittest tests.test_e2e -v      # single module
 ```
 

wiki/release-process.md

@@ -103,7 +103,7 @@ every emulator profile against `schemas/emulator.schema.json`. Both schemas set
 `additionalProperties: false`, so a typo in a field name fails the job instead
 of being silently ignored.
 
-**run-tests.** Runs `python -m unittest discover tests -v`. Must pass before a
+**run-tests.** Runs `python -m unittest discover -s tests -t . -v`. Must pass before a
 merge, and again on the commit a direct push puts at the head of main.
 
 **label-pr** (pull requests only). Auto-labels the PR based on changed paths:

wiki/testing-guide.md

@@ -12,7 +12,7 @@ not require network access. Most build synthetic fixtures under the repository's
 Run the full suite:
 
 ```bash
-python -m unittest discover tests -v
+python -m unittest discover -s tests -t . -v
 ```
 
 Run a single module:
@@ -237,7 +237,7 @@ README generation). Requires packs in `dist/`; skip with `--skip-packs`.
 
 The test suite is one layer of verification. The full quality gate is:
 
-1. All unit tests pass (`python -m unittest discover tests`)
+1. All unit tests pass (`python -m unittest discover -s tests -t .`)
 2. The full pipeline completes without error (`python scripts/pipeline.py --offline`)
 3. No unexpected CRITICAL entries in the verify output
 4. Pack file counts match verification file counts (consistency check)
@@ -250,7 +250,7 @@ Ideally, tests, code, and documentation ship together. When profiles and platfor
 
 ## CI integration
 
-The `validate.yml` workflow runs `python -m unittest discover tests -v` on both
+The `validate.yml` workflow runs `python -m unittest discover -s tests -t . -v` on both
 roads into main: every pull request, and every direct push, that touches
 `bios/`, `platforms/`, `emulators/`, `schemas/`, `scripts/`, `tests/` or
 `install.py`. Work reaches main by push as often as by pull request, so a suite
@@ -264,10 +264,10 @@ of main passes, not every commit under it.
 
 Modules that need real artifacts skip themselves when those artifacts are absent,
 so `test_pack_integrity` is a no-op in CI (no `dist/`) and a real check locally.
-Run `python -m unittest discover tests` before pushing.
+Run `python -m unittest discover -s tests -t .` before pushing.
 
 Tests must pass before merge. If a test fails in CI, reproduce locally with:
 
 ```bash
-python -m unittest discover tests -v
+python -m unittest discover -s tests -t . -v
 ```