CI, Linux scanners, catalog validation, case export, TUI guides, update rollback, and a real README

[lizTheDeveloper]

What this changes

Works through the things docs/ROADMAP_STATUS.md records as unimplemented, and gives the repository the CI and documentation it did not have. After this merges: every push runs the suite on three operating systems and three Python versions; Linux has a real module set instead of a nominal one; the shipped catalog validates itself; a rescue produces a redacted report you can hand to someone; the TUI can actually open the recovery walkthroughs; a content update can be backed out; and the README answers "will this download something malicious?" with file paths rather than reassurance.

Type of change

• Bug fix
• New module
• New or changed profile / guide
• Engine change (anything under rescue/)
• Documentation
• Tests or CI only

What's in it

CI, where there was no .github/ at all — the documented consequence was that three files did not parse on the declared minimum Python and 30 call sites used a 3.13-only keyword, both shipped, because the suite only ever ran on one developer's macOS box. Jobs: a 3.11 byte-compile floor, pytest across 3.11/3.12/3.13 × ubuntu/macos/windows, ruff, integrity-manifest freshness, catalog validation, and a clean-venv install that runs rescue from outside the source tree (the packaging bug in P0#1 is invisible any other way).

Nine Linux modules. 17 of 281 modules declared Platform.LINUX, mostly cross-platform checks that happened not to exclude it — a Linux user got a disk-space number. Now: firewall state, SSH exposure, account and sudo audit, disk encryption, boot persistence, package updates and release EOL, systemd health, journal errors that precede hardware failure, and memory pressure. All read-only, all bounded through rescue.command.run, plus a linux_security_checkup profile that runs the lot in one command.

rescue validate (P1#3) — unique names, dependency cycles, platform and risk declarations, profiles selecting real modules, guides not advertising automation nothing can perform.

rescue export (P1#2) — a rescue case as redacted JSON and Markdown. Redacted by construction, not by review, since an export is the artifact most likely to be pasted into a chat window.

TUI guides (P1#5) — the guide screen was three disabled checkboxes and "coming in Plan 3", and nothing ever pushed it. Now a working checklist sharing session state with rescue guide on the CLI.

rescue update --rollback / --use-bundled (P0#2) — rollback re-verifies approval rather than trusting the earlier one, and the bundled fallback deliberately avoids the trust machinery so it works when that is the thing that broke.

Documentation. A MkDocs Material site (mkdocs.yml, docs/, deployed by the docs workflow) with a quickstart, a page per built-in scenario, a CLI reference, a module catalog generated from the live registry and checked for drift in CI, a module-authoring guide, and a trust-and-safety page that traces every safety claim to the file implementing it. Plus a rewritten README, SECURITY.md, CONTRIBUTING.md, and issue/PR templates — every command run against the checkout, every number from the live registry, and the limits stated as plainly as the guarantees.

Nine pre-existing defects the new CI found

The matrix earned its place on the first run. Everything here was already in the tree except where noted:

Defect	Impact before the fix
os.getuid() at module import scope	Collection aborted; all three Windows jobs ran zero tests
win_user_profiles treated a PowerShell SID object as a string	Windows-only module raised TypeError on every real Windows machine
No .gitattributes	LF→CRLF on checkout made the integrity manifest report the whole package as tampered on Windows
read_text()/open() without an encoding	Guides, profiles, signer JSON and generated docs read and written through cp1252 — silent mojibake in recovery text a frightened person reads
getattr(None, "__doc__", "") returns NoneType's docstring on 3.13	Version-dependent validator behaviour (introduced in this PR, caught by the matrix)
Four invalid escape sequences in Windows-path docstrings	SyntaxWarnings today, errors in a future Python
BSOD fixture built exactly on the 24-hour boundary	Latent coin-flip, resolved by clock granularity — one way on Linux, the other on Windows
dir="/tmp" in a gpg test; seven POSIX-assuming test files	Failed for the platform rather than for the code
A TUI test that started a real scan of the module tree	Passed, then spent 16 minutes reaping orphaned powershell/manage-bde processes

Also fixed: a date-bomb fixture in test_module_win_windows_update_status that aged into a failure, a pytest.main call in a file that never imported pytest, and test_module_code_consistency matching only code="security.…" — so every non-security category was exempt by not being looked at.

And one that mattered more than a test failure: all three AI providers told users to pip install multiverse-device-rescue[ai] when their SDK was missing. This project is not on PyPI, so that error message instructed people to install whatever an unrelated party had uploaded under that name — the exact supply-chain hazard the trust page says the tool protects them from, shipped inside the tool's own remediation advice.

Test plan

$ .venv/bin/python -m pytest -q
3676 passed in 363.16s (0:06:03)

$ .venv/bin/python -m rescue.cli validate
287 modules, 7 profiles, 110 guide phases checked: 0 error(s), 1 warning(s).
Catalog is consistent.

$ .venv/bin/ruff check .
All checks passed!

$ .venv/bin/mkdocs build --strict
Documentation built in 1.10 seconds

Also run green on 3.12 and 3.13 locally, which is how the None.__doc__ divergence was confirmed fixed.

Clean-install check, matching what the package CI job does:

$ python3 -m venv /tmp/pkgtest && /tmp/pkgtest/bin/pip install .
$ cd /tmp && /tmp/pkgtest/bin/rescue profiles | head -1
ai_worm_response — AI Worm & Spyware Response
$ /tmp/pkgtest/bin/rescue run disk_space --yes
=== disk_space === Found 4 issue(s): ...

Manual verification: Ubuntu 24.04, all nine Linux modules run end to end against the real host, and rescue --auto --profile linux_security_checkup reports findings and changes nothing. rescue update --use-bundled verified to succeed on this repository, whose signer configuration is still placeholders — which is precisely the case it exists for.

Checklist

• .venv/bin/python -m pytest -q passes
• .venv/bin/python -m rescue.cli validate exits 0 (0 errors)
• .venv/bin/ruff check . is clean
• Integrity manifest: regenerated and committed after every change under rescue/
• Not applicable — nothing under rescue/ changed

Safety review

• Every mutation is confirmed by the user, or gated behind --yes
• Instructional actions use ActionKind.GUIDANCE and are never reported as completed changes
• Checks that cannot run return supported=False with a reason, or set error — never an empty healthy result
• No new module sets auto_apply = True
• External commands go through rescue.command.run; filesystem recursion goes through rescue.fsbounds.bounded_walk
• Traversal roots and command paths are class attributes so tests can point them at a fixture tree
• Nothing new reaches the network outside the opt-in AI layer and rescue update
• Nothing prompts for a password, one-time code, recovery key, or API token
• emits_codes matches the code= literals in the module

Anything a reviewer should look at closely

The lint gate is narrow on purpose. Ruff's defaults produce 4000 findings here, so ruff.toml selects only defect-class rules. Widening it is worth doing as its own change; a gate that is red on arrival gets ignored.

CI runs rescue validate, not --strict. The one outstanding warning is that 264 of 287 modules have no docstring. Real debt, but failing every PR on it would make the check something people route around. The workflow comment says what has to be true before --strict goes back on.

Seven test files now skip off POSIX. Each tests a macOS-only or Linux-only module and asserts on POSIX paths or file modes, so there is nothing for a Windows job to exercise — but it is worth a second opinion that none of them was masking a real cross-platform gap.

The Linux modules' severity choices. Whether "no firewall front-end installed" deserves WARNING, and whether the linux_persistence_audit heuristics (fetch-and-pipe-to-shell, execution from /tmp, world-writable units) are tight enough to avoid the false-positive problem the roadmap warns about, are judgement calls worth reviewing.

rescue update --rollback refuses a previous version whose signer has since been revoked. Deliberate — revocation has to apply to content already on the machine — but it does mean the only path left in that case is --use-bundled.