docs(appliance): correct the appliance docs against the shipped code

[VijitSingh97]

Quality pass over the appliance work merged to develop-v2 in the last day, across three axes: testing, documentation accuracy, and concise code. This PR carries only the safe mechanical fixes. Everything needing judgment is in the report / filed as issues.

What this fixes

Docs that disagree with the code (repo rule: fix the doc)

• tests/os/README.md — documented rugix-ctrl, an image path os/build-image.sh does not produce (it claimed os/bakery/build/…/system.img; the script emits os/build/pithead-root.tar, and the bootable image comes from os/rauc/mkimage.sh), and two of the harness's five phases. Its Status section still said the update phase was an open leg that "fails loudly" — os/KNOWN-ISSUES.md records it green. Rewritten against run.sh as it stands, plus the verify-image.sh gate it never mentioned.
• os/KNOWN-ISSUES.md:5 — battery counts said "boot 3/3, update 11/11 and fault 11/11": the wrong update figure and three of five phases. Now matches the maintained per-phase table in appliance-release.md, and links to it rather than re-stating it.
• os/KNOWN-ISSUES.md — the stick/disk label-collision bullet claimed /data and the ESP are still mounted by LABEL from a static fstab. os/overlay/pithead-mount-generator supersedes that: it resolves both mounts from the booted disk's partition numbers. Every sibling bullet in that file is genuinely open, so the resolved one is dropped; the invariant it protected is already the generator's own header comment.
• docs/dev/dual-distribution-plan.md — the decision table, channel table, appliance-architecture bullet, reset tiers and repo tree still named Rugix, which the 2026-07-25 bake-off in that same document replaced with RAUC. Only current-state claims moved; the bake-off appendix is a historical record and keeps its Rugix prose. The repo tree also showed an os/bakery/ that never shipped.
• os/rauc/mkimage.sh:110 — pointed at pithead-dataprep.service, which does not exist anywhere in os/. The /var overlay directories are seeded by systemd-repart at format time via os/rootfs/repart.d/40-data.conf.
• docs/appliance.md — the appliance arms the hardware watchdog (RuntimeWatchdogSec=20s) and pins the performance CPU governor on every boot, whether or not you mine. Both are operator-visible and were undocumented; the only governor mentions in the docs were RigForge's miner tuning.

Dead code

• tests/os/run.sh — _gen_certs and CERT_DIR, zero call sites. Vestigial since signing moved into mkbundle.sh / populate-slot.sh with the explicit-key custody rule. A sweep of every shell function defined across pithead, os/** and tests/os/** found this as the only dead one, and no dead Python or JS.

Lint gap

• os/overlay/pithead-mount-generator is a shipped /bin/sh script that no lint target covered. Added to lint-sh; it was already clean.

Not in this PR

No behavior was refactored and no test was restructured. Filed separately: the untested fail-closed paths in install.sh, and the appliance's absence from the four-tier map in docs/dev/testing-strategy.md.

Verification

make lint-sh, make lint-md, make lint-docs-voice, make lint-operator-strings pass. make test-stack is 2016 passed / 0 failed. tests/os/run.sh needs KVM and was not run; it is syntax-checked and the deletion has no callers.

🤖 Generated with Claude Code

[VijitSingh97]

Second commit pushed: six comments in the shipped image still named Rugix as current tooling.

• os/rootfs/Dockerfile:2 — the header said the exported tarball is "fed to Rugix Bakery". It is fed to os/rauc/mkimage.sh / mkbundle.sh.
• os/rootfs/Dockerfile:179 — "rugix-ctrl arrives via the bakery layer's core recipe".
• os/rootfs/Dockerfile:217 — "so the harness can drive rugix-ctrl in the guest"; the harness drives rauc (tests/os/run.sh _install_cmd/_commit_cmd).
• os/rootfs/Dockerfile:240 — the file's last line claimed the updater "lands via the bakery layer's core recipes, not here", directly contradicting the apt-get install rauc rauc-service eight lines above. Deleted rather than reworded.
• os/rootfs/Dockerfile:142 and os/overlay/pithead-sync.service:7 — attributed the discarded root overlay to Rugix.

The updater-agnostic design intent is real and is kept; only its attribution moved. Comments only, no build change.

One deliberately left alone: os/rootfs/Dockerfile:35 keeps the apt lists on purpose and justifies it with "the Rugix core recipes run apt-get install in the build chroot ... deleting them fails the bake". Under RAUC, mkimage.sh partitions with host tools rather than in a chroot, so that justification may no longer hold — but whether the lists are still needed is a question a build answers, not a reading. Left as-is rather than rewritten into a guess.

[VijitSingh97]

Third commit: tests/os/run.sh's header claimed "Exit non-zero on the first failed assertion". It does not — bad() increments FAIL and returns, every phase runs to completion, and the script exits non-zero at the end via [ "$FAIL" -eq 0 ].

Continue-on-error is the correct design here and is the repo's own stated standard ("continue-on-error to collect the whole matrix", docs/dev/testing-strategy.md § Engineering standards) — one bench boot is expensive, so collecting the whole battery beats stopping at the first fault. The comment was describing the wrong design, not a missing one.

Caught because I had propagated the same claim into the tests/os/README.md rewrite in the first commit; both are corrected.

[VijitSingh97]

Rebased onto the current develop-v2 — factory reset (#862) and the update-safety work (#863) landed while this was open. Three things changed as a result, all of them corrections to my own edits:

• Makefile — kept os/overlay/pithead-data-reset (added upstream) alongside my os/overlay/pithead-mount-generator. Both are now shellchecked.
• docs/dev/dual-distribution-plan.md — my first pass wrote that RAUC has no integrated state reset so "an on-box tier-2 path is still to build". That was true against the base I branched from and is now wrong: pithead config-reset / pithead factory-reset ship, with os/overlay/pithead-data-reset reformatting /data one layer under the running system off an ESP marker that survives the wipe. The bullet describes what exists.
• os/rootfs/Dockerfile — kept upstream's pithead-data-reset chmod, applied my updater-comment correction on top.

Re-verified on the rebased branch: make lint-sh, make lint-md, make lint-docs-voice pass, and make test-stack is 2073 passed / 0 failed (up from 2016 — the reset work brought its own cases).

The one CI failure on the previous push was infrastructure, not this change: Build image (xmrig-proxy) timed out resolving the pinned base from Docker Hub (dial tcp 44.196.217.182:443: i/o timeout on registry-1.docker.io) 68 seconds in, before any build step ran. Nothing in this PR touches build/xmrig-proxy.