Document recovery from the 0.3.1 software update refusal

docs/INSTALL.md

@@ -220,6 +220,18 @@ if an install fails, the previous installed copy remains in place.
 - **Setup refused to do something.** Read what it printed. It refuses rather
   than guesses, and it names the reason: an unrecognised volume, a menu slot
   another mod is already using, or a file that did not read back byte for byte.
+- **Software update says “the address or credentials are invalid” on 0.3.1.**
+  When updating a pre-bootstrap installation to a current release, this can
+  mean the old updater rejected the new standalone launcher in the package;
+  it does not necessarily mean your Wi-Fi credentials are wrong. The old
+  updater refuses that path before replacing Cobalt. Reinstall the current
+  stable release once using the universal installer and USB `kobo setup`, as
+  described under [Updating or building from source](#updating-or-building-from-source).
+  Running `kobo update` alone updates the host command, not the reader.
+  After setup, open Settings > Software update, confirm the installed version,
+  and check again. If the error persists on a current installation, report the
+  installed version and selected channel: this generic message can also have
+  other causes. See [issue #154](https://github.com/BandarLabs/Cobalt/issues/154).
 - **The screen looks wrong, or nothing draws.** Cobalt declines to write to a
   panel it does not recognise exactly. Hold the power button to reboot, and you
   are back in the stock reader with nothing to undo.

docs/testing/software-update-154/README.md

@@ -0,0 +1,37 @@
+# Manual recovery from Cobalt 0.3.1 — issue #154
+
+On 2026-09-07, the maintainer requested a manual installation of 0.3.9 after
+Settings > Software update on an Elipsa 2E reported “the address or credentials
+are invalid”. The device was N605/code 389, firmware 4.38.23697, kernel 4.9.77.
+
+The GitHub Pages universal installer was downloaded, inspected and run on
+macOS arm64 with `--version 0.3.9 --yes --non-interactive --no-setup --no-path`
+and a temporary `--install-dir`. It verified the signed release metadata and
+installed the host CLI and cached device package successfully. The release
+metadata and device UI label 0.3.9 as Stable. USB setup, shell profile changes,
+Linux and browser installation were not exercised.
+
+With Cobalt stopped, the old installation was backed up. The published package
+was inspected and deployed over SSH using the released CLI. That developer
+command omits the standalone launcher, so the reviewed launcher from the same
+verified package was installed separately and the exact managed NickelMenu
+entry migrated to it. All 27 packaged files then matched their SHA-256 digests.
+Owner data and installed store applications were retained.
+
+Cobalt launched, Settings showed 0.3.9, and Check for updates completed over
+Wi-Fi. [The device framebuffer capture](stable-039-check.png) shows Stable and
+“0.3.9 is the newest published release, and it is what this reader is running.”
+This is a successful manual migration and update-discovery check, not a test
+of a subsequent OTA installation or Beta channel switching.
+
+The downloaded 0.3.9 archive starts with the plain file
+`mnt/onboard/.adds/cobalt-launch.sh`. The 0.3.1 updater permits files only below
+`mnt/onboard/.adds/cobalt/` and returns `DeviceError::InvalidInput` for that
+member. Current source deliberately tests this refusal before installation
+swap (`f49b32c_updater_rejects_bootstrap_release_before_swap`). This is a concrete
+package incompatibility consistent with the original screen error; the old
+session log did not identify its internal failure stage.
+
+The recovery guidance uses the supported USB setup path. The manual SSH steps
+above describe the attended developer test, not a complete first-migration
+capability of `kobo deploy`.