docs(tester): alpha RC tester guide (install / upgrade / rollback / report)

CHANGELOG.md

@@ -72,6 +72,18 @@ and [Semantic Versioning](https://semver.org/).
   GPL-3.0 `LICENSE`. ([#383](https://github.com/OpenTollGate/tollgate-module-basic-go/pull/383))
 ### Changed / Internal
 
+- **Tester guide for the alpha RC.** New [docs/rc-tester-guide.md](docs/rc-tester-guide.md)
+  documents the supported-matrix placeholder (honest about what is untested),
+  the feed signing key and the repository line for OpenWrt 25.12, install,
+  upgrade, remove and rollback — including the `/etc/apk/world` version pin a
+  rollback leaves behind, and the fact that `--force-downgrade` is not an
+  apk-tools 3.x option — the failure modes reproduced in practice, how to
+  report a result, and what to expect from an alpha. Every command was
+  executed against a real OpenWrt 25.12.5 userland; router-only steps are
+  marked UNTESTED. `RELEASE-NOTES.md` no longer suggests
+  `apk add --allow-untrusted`.
+  ([#381](https://github.com/OpenTollGate/tollgate-module-basic-go/pull/381))
+
 - **Packaging artifact-contents test.** New
   `tests/packaging/assert-artifact-contents.sh` asserts a built `.ipk`/`.apk`
   ships the runtime files under `packaging/files/`, and is wired into both

RELEASE-NOTES.md

@@ -328,19 +328,32 @@ changes in this release only exist on a real device.
 
 ## Upgrade notes
 
-- **Back up the wallet directory and `/etc/config/tollgate` before
+- **Back up the wallet directory and `/etc/tollgate/config.json` before
   upgrading.** The deployment backup that leaked in August is a reminder of
   what that data is worth.
 - **Package filenames are `tollgate-wrt_v0.6.0-alpha2_<arch>.ipk` and
   `…_<arch>.apk`** (the tag name verbatim; UPX variants add a `-upx-…`
   suffix before the extension).
 - **`.apk` (OpenWrt 25.x)**: install it from the testing feed — see
   [docs/rc-tester-guide.md](docs/rc-tester-guide.md) for the key, the
-  repository line and the verified install/upgrade/rollback commands. To
-  install the downloaded file directly instead, `apk add
-  ./tollgate-wrt_v0.6.0-alpha2_<arch>.apk`; inside the package apk-tools sees
-  the normalised version `0.6.0_alpha2-r1`. Never pass `--allow-untrusted`:
-  the feed index and key exist so that verification stays on.
+  repository line and the verified install/upgrade/rollback commands. Inside
+  the package apk-tools sees the normalised version `0.6.0_alpha2-r0`.
+
+  **An unsigned downloaded file is not a substitute for the feed.** `apk`
+  will refuse `apk add ./tollgate-wrt_v0.6.0-alpha2_<arch>.apk` on its own
+  (`UNTRUSTED signature`), because the file is not signed with a key the
+  router trusts. It only installs with `--allow-untrusted`, and only after
+  you have verified the file against the `sha256` published in the
+  announcement:
+
+  ```bash
+  sha256sum tollgate-wrt_v0.6.0-alpha2_<arch>.apk   # must equal the announced sha256
+  apk add --allow-untrusted ./tollgate-wrt_v0.6.0-alpha2_<arch>.apk
+  ```
+
+  Never `--allow-untrusted` a file whose `sha256` you have not checked — and
+  never use that flag on the feed path: the index and key exist so that
+  verification stays on.
 - **`.ipk` (OpenWrt 24.10 and earlier)**: `opkg install
   tollgate-wrt_v0.6.0-alpha2_<arch>.ipk`; the control-file version is the
   tag name, `v0.6.0-alpha2`.
@@ -388,8 +401,9 @@ changes in this release only exist on a real device.
   (a comment on the pinned *Tester reports — TollGate v0.6.0-alpha2 (alpha
   channel)* issue in the
   [project tracker](https://github.com/OpenTollGate/tollgate-module-basic-go/issues)),
-  carries the report template, and states the triage and severity rules. Send
-  the facts it asks for (router model, `cat /etc/openwrt_release`,
+  carries the report template, and states the triage and severity rules; the
+  tester guide's *How to report a result* section lists the exact commands to
+  run. Send the facts they ask for (router model, `cat /etc/openwrt_release`,
   `apk --print-arch`, the feed line, `apk list --installed tollgate-wrt`,
   `tollgate version`, `sha256sum` of the installed binaries,
   `logread -e tollgate | tail -50`, expected vs actual) and never a key, seed,

docs/rc-tester-guide.md

@@ -67,8 +67,8 @@ it was built for 25.12.
 - A supported router (§1) with working SSH and root access.
 - About **30 MB free** in `/overlay` (the two installed binaries are ~28 MB in
   total in the rehearsal build).
-- **Back up first** — copy `/etc/tollgate/` (wallet and identities) and
-  `/etc/config/tollgate` somewhere off the router. Removing or rolling back the
+- **Back up first** — copy `/etc/tollgate/` (the wallet, `identities.json`,
+  `config.json`) somewhere off the router. Removing or rolling back the
   package does not delete those paths (verified — see §5), but an alpha is an
   alpha; keep a copy.
 - Do not install this on a router you or anyone else depends on.
@@ -156,10 +156,17 @@ apk add tollgate-wrt
 ```
 (1/2) Installing jq (1.8.1-r2)
   Executing jq-1.8.1-r2.post-install
-(2/2) Installing tollgate-wrt (0.6.0_alpha2-r1)
+(2/2) Installing tollgate-wrt (0.6.0_alpha2-r0)
 OK: 39.1 MiB in 138 packages
 ```
 
+**If you are SSH'd in over the LAN this package configures, the install will
+drop your session.** The package's post-install script runs the `uci-defaults`
+scripts and then restarts `/etc/init.d/network`, reloads
+wifi/firewall/dnsmasq/uhttpd and starts the service. Reconnect once the router
+is back and continue at the next step — a lost session here is expected, not a
+failure.
+
 `tollgate-wrt` is the package name. It installs two binaries —
 `/usr/bin/tollgate-wrt` (the service) and `/usr/bin/tollgate` (the CLI) — plus
 `/etc/init.d/tollgate-wrt`. `jq` is a dependency and is pulled in
@@ -180,7 +187,7 @@ tollgate version
 **VERIFIED (rehearsal)** for the package listing and the files:
 
 ```
-tollgate-wrt-0.6.0_alpha2-r1 x86_64 {tollgate-wrt} (GPL-3.0-only) [installed]
+tollgate-wrt-0.6.0_alpha2-r0 x86_64 {tollgate-wrt} (GPL-3.0-only) [installed]
 -rwxr-xr-x    1 nobody   nogroup       1380 /etc/init.d/tollgate-wrt
 -rwxr-xr-x    1 nobody   nogroup   10253038 /usr/bin/tollgate
 -rwxr-xr-x    1 nobody   nogroup   17732119 /usr/bin/tollgate-wrt
@@ -206,17 +213,33 @@ wallet_ok: true
 network_ok: true
 ```
 
+**Note — the version string the published build prints.** The repository-root
+`VERSION` file (`v0.6.0-alpha2`) is injected into both binaries verbatim: CI
+passes the tag down as `PACKAGE_VERSION` and every packaging path in this tree
+(`scripts/build-sdk-package.sh`, `packaging/local-build-ipk.sh`) forwards it to
+`-X .../src/cli.Version` unchanged. A build from the current tree therefore
+prints `version: v0.6.0-alpha2` (hyphen) and `version: TollGate v0.6.0-alpha2`.
+The rehearsal block above was produced by an earlier packaging path and shows
+the underscore form; the number is the same either way, and a difference of only
+`-` versus `_`, or a trailing `-r<N>`, is not a finding (see
+[tester-intake.md](tester-intake.md)). The same block records
+`go_version: go1.26.0`; builds from the current tree are pinned to the toolchain
+in [packaging/build-inputs.json](packaging/build-inputs.json) (`go1.25.8`), so
+expect that value on a published artifact.
+
 **Version strings, so you know what you are looking at:**
 
 | where | value |
 |---|---|
 | release tag / announcement | `v0.6.0-alpha2` |
-| package version (`apk list --installed`) | `0.6.0_alpha2-r1` |
-| runtime version (`tollgate version`) | `v0.6.0_alpha2` |
-
-apk normalises the hyphen into an underscore for its own version ordering; the
-`-r1` release revision is set when the package is built. The runtime string is
-the apk-safe form as well. The exact `-r` number and commit for the published
+| package version (`apk list --installed`) | `0.6.0_alpha2-r0` |
+| runtime version (`tollgate version`) | `v0.6.0-alpha2` |
+
+apk carries no hyphen in a version, so its control value spells the tag as
+`0.6.0_alpha2`; the `-r0` release revision is what
+[packaging/normalize-apk-version.sh](packaging/normalize-apk-version.sh)
+appends (the recipe sets no `PKG_RELEASE` of its own). The runtime string is
+the tag **verbatim** — hyphen kept, no `-r0`. The exact `-r` number and commit for the published
 build are printed in the announcement — compare rather than assume.
 
 **The CLI talks to the running service over `/var/run/tollgate.sock`.** If the
@@ -264,10 +287,10 @@ and several post-upgrade scripts failed, purely because the container has no
 `procd`. `apk upgrade tollgate-wrt` keeps the blast radius at one package.
 
 **UNTESTED ON A ROUTER:** that the package's post-install logic restarts the
-service on the router, that `/etc/config/tollgate` survives an upgrade
+service on the router, that `/etc/tollgate/config.json` survives an upgrade
 byte-for-byte, and that the wallet keeps working afterwards. The config file
-is not written by the package (it is created on first run by the
-`99-tollgate-setup` script), which is normally how OpenWrt keeps it across
+is not written by the package (it is created on first run by the service, not
+by `99-tollgate-setup`), which is normally how OpenWrt keeps it across
 upgrades, but that has not been confirmed on a device.
 
 ---
@@ -281,7 +304,7 @@ apk del tollgate-wrt
 **VERIFIED (rehearsal)**
 
 ```
-(1/2) Purging tollgate-wrt (0.6.0_alpha2-r1)
+(1/2) Purging tollgate-wrt (0.6.0_alpha2-r0)
 (2/2) Purging jq (1.8.1-r2)
   Executing jq-1.8.1-r2.pre-deinstall
 OK: 11.4 MiB in 136 packages
@@ -319,12 +342,12 @@ apk add 'tollgate-wrt=<known-good-version>'
 **VERIFIED (rehearsal)**
 
 ```
-(1/1) Downgrading tollgate-wrt (0.6.0_alpha3-r1 -> 0.6.0_alpha2-r1)
+(1/1) Downgrading tollgate-wrt (0.6.0_alpha3-r0 -> 0.6.0_alpha2-r0)
 ```
 
 Exit status 0, and `apk list --installed tollgate-wrt` shows the older
-version. Ordering matters and is real: apk knows `0.6.0_alpha3-r1` is newer
-than `0.6.0_alpha2-r1`, which is why the same command upgrades, downgrades, or
+version. Ordering matters and is real: apk knows `0.6.0_alpha3-r0` is newer
+than `0.6.0_alpha2-r0`, which is why the same command upgrades, downgrades, or
 does nothing, depending on which version you name.
 
 **`--force-downgrade` does not exist on 25.12.** Older material (and some
@@ -341,7 +364,7 @@ have that flag, but there is no feed for 24.10 — §1).
 # grep tollgate /etc/apk/world     (before the pin)
 tollgate-wrt
 # ... after the rollback ...
-tollgate-wrt=0.6.0_alpha2-r1
+tollgate-wrt=0.6.0_alpha2-r0
 ```
 
 ). While that pin is there, `apk upgrade tollgate-wrt` will **not** move you
@@ -350,7 +373,7 @@ ready to follow the channel again:
 
 ```sh
 apk add tollgate-wrt            # drops the pin; /etc/apk/world goes back to "tollgate-wrt"
-apk upgrade tollgate-wrt        # VERIFIED: Upgrading tollgate-wrt (0.6.0_alpha2-r1 -> 0.6.0_alpha3-r1)
+apk upgrade tollgate-wrt        # VERIFIED: Upgrading tollgate-wrt (0.6.0_alpha2-r0 -> 0.6.0_alpha3-r0)
 ```
 
 **Do not use `apk upgrade --available` as a rollback.** VERIFIED: it is a
@@ -460,6 +483,12 @@ screenshot:**
   (identities, wallet database) — it contains your keys;
 - a wallet file, a seed phrase, a mnemonic, or an `nsec`;
 - a Cashu token, or the output of `tollgate wallet drain cashu`;
+- the `logread -e tollgate | tail -50` block before you have read it: the
+  daemon logs `token_preview=` (the first 50 characters of a Cashu token), so
+  read the block first, redact everything after `token_preview=` (and after
+  `preview:`), and say in the report that you redacted it;
+- `/tmp/tollgate-setup.log` — it records the generated private-WiFi PSK in
+  cleartext;
 - router credentials, WireGuard keys, or private network passwords.
 
 If you think you sent a secret by accident, say so immediately without pasting
@@ -477,14 +506,14 @@ this guide does not present it as verified:
    cache headers) — the serving side was still being built when this was
    written.
 2. The real, signed index and its key, downloaded over HTTPS from that host.
-3. The real `0.6.0_alpha2-r1` package bytes: filename, `sha256`, and that the
+3. The real `0.6.0_alpha2-r0` package bytes: filename, `sha256`, and that the
    provided `sha256` matches the artifact published in the announcement.
 4. `/etc/init.d/tollgate-wrt` `enable`/`status`/`start` under `procd`, the
    service starting on boot, and the daemon staying up ≥ 5 minutes.
 5. `logread` output, and `tollgate logs` (which wraps it).
 6. First-run behaviour: `99-tollgate-setup` running from `uci-defaults`,
-   `/etc/config/tollgate` being created, and WiFi/portal configuration being
-   preserved across an upgrade.
+   `/etc/tollgate/config.json` being created on first run, and WiFi/portal
+   configuration being preserved across an upgrade.
 7. The captive portal and the payment flow end to end — nothing in this guide
    exercises them, and no package install can.
 8. Rollback executed on a router with a real user configuration in place.