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

[felixfelix-bot]

Adds docs/rc-tester-guide.md, the document a tester with a supported OpenWrt router follows to install the v0.6.0-alpha2 release candidate from the package feed, upgrade, remove, roll back, and report a result we can act on.

Stacking: this branch is cut from release/v0.6.0-alpha2-prep (PR #380), so the PR view also shows that branch's 18 files. Merge #380 first, or rebase this branch onto main once it lands; the guide's own diff is docs/rc-tester-guide.md plus the CHANGELOG.md / README.md / RELEASE-NOTES.md link lines.

• Supported matrix, stated first and honestly. The table is a clearly marked placeholder holding the current 25.12/apk proposal, to be set by what the acceptance test actually passes. 24.10 and earlier are documented as NOT supported (their SDK toolchains ship Go 1.21/1.23 and cannot build this module), with a pointer to the file-download channel and no support promise. Anything built but not tested on hardware is labelled "built, untested", not supported.
• Install via the feed. Signing key first, then the repository line as a full URL to packages.adb (the 25.12 index format, not a directory), apk update, apk add tollgate-wrt, and what a successful install looks like: package listed, files present, service running, CLI responding, version string. Includes why --allow-untrusted must never be used, and what happens when the index is unsigned.
• Upgrade, remove, rollback. Each destructive step carries a "do not do this unless" warning and an explicit way back; the rollback command is the executed one, plus the version pin it leaves behind and how to drop it.
• Failure modes reproduced in practice, with the real apk messages, rather than a generic troubleshooting list.
• How to report. The exact commands whose output we need, severity S1/S2/S3, and what never to paste: no nsec, seed, mnemonic, wallet file or token.
• What to expect from an alpha — known limitations, the wallet path being hardened, funds-loss reports as stop-ship.

Verification, as required by the release gates: every command was executed against a real OpenWrt 25.12.5 userland (apk-tools 3.0.5, x86_64) installing a rehearsal package from a local copy of the feed layout. Two corrections came out of that run: apk-tools 3.x has no --force-downgrade (the working rollback is apk add 'tollgate-wrt=<version>', which also pins the package in the apk world file and blocks later upgrades), and RELEASE-NOTES.md no longer suggests installing with the trust check disabled. Two markers are used throughout, and every step that needs router hardware is marked UNTESTED ON A ROUTER; section 10 lists what a real-router test still has to confirm. The published feed host and channel path are marked provisional — the serving side is still being built, and the announcement wins if it prints a different path.

CHANGELOG.md [Unreleased] entry in the same commit; README.md and RELEASE-NOTES.md link the guide.

[felixfelix-bot]

Summary. Adds docs/rc-tester-guide.md — the document an external tester follows to install the v0.6.0-alpha2 candidate from the package feed, upgrade, remove, roll back and report a result, with an honestly labelled supported matrix (24.10-and-earlier unsupported, "built, untested" kept distinct from "supported"). Guide delta only: docs/rc-tester-guide.md + the CHANGELOG/README/RELEASE-NOTES link lines; the #380 files in this diff are out of scope.

Review — two text fixes before a tester reads it, then land (posted as a comment: GitHub refuses formal approve/request-changes from the author's own account). I reproduced the guide's own mechanics on a real 25.12 userland with apk-tools 3.0.5 rather than trusting the quotes — the pin, the downgrade and the --force-downgrade error all behave as documented. Three things are wrong:

1. [BLOCK] No build of this repo produces -r1. Building v0.6.0-alpha2 through the repo's own packaging/Makefile in the 25.12.5 SDK yields tollgate-wrt-0.6.0_alpha2-r0.apk (normalize-apk-version.sh appends -r0; nothing sets PKG_RELEASE). So the rollback command — apk add 'tollgate-wrt=0.6.0_alpha2-r1' — fails with ERROR: unable to select packages: (no such package) for anyone who copies it, and the same string appears in the §3.4/§3.5/§4/§5 outputs and in RELEASE-NOTES.md#L334-L340 (#380 had -r0). Please use -r0 throughout.
2. [BLOCK] RELEASE-NOTES.md#L334-L340 now offers apk add ./tollgate-wrt_v0.6.0-alpha2_<arch>.apk while forbidding --allow-untrusted. Verified on 25.12.4/apk 3.0.5: that install fails with ERROR: …: UNTRUSTED signature and installs nothing — only --allow-untrusted works. That removes the last offline path for 25.12 testers while §1 sends 24.10-and-earlier users to the same "file-download channel". Either sign the packages or keep the flag with a "verify the announced sha256 first" gate.
3. [BLOCK] /etc/config/tollgate does not exist in this repo — the string appears only in this guide and RELEASE-NOTES.md#L328. The config is /etc/tollgate/config.json (src/main.go#L141-L146), and 99-tollgate-setup commits UCI for network/wireless/dhcp/firewall/uhttpd/nodogsplash — never a tollgate UCI config. §2 tells testers to back it up, §4 says it survives an upgrade, §10 item 6 asks them to confirm it was created.
4. [RISK] §3.4's two-line install transcript omits the package's post-install, which restarts /etc/init.d/network, reloads wifi/firewall/dnsmasq/uhttpd and starts the service — a tester SSH'd in over the LAN being configured can lose the session mid-install. One line in §3 covering it would help.
5. [RISK] §9 requires logread -e tollgate | tail -50, and the daemon logs token_preview= (first 50 chars of a Cashu token — src/merchant/merchant.go#L934, also #L1113-L1117); the never-paste list should say to redact it, plus /tmp/tollgate-setup.log, which holds the generated private-WiFi PSK.

Standing offer: re-review the delta — everything else reproduces. (Full internal report including the remaining RISKs and NITs kept out of the thread.)

[Amperstrand]

Informal docs pass (per PR-REVIEW Step 1, a thirteen-point review is overkill for docs-only changes; this is the one-paragraph version):

Both PRs are docs-only, bot-authored, and companion pieces (#381 the tester guide, #382 the intake channel/triage rules that reference it). I scanned every added line in both for credential leakage (nsec/npub keys, private keys, embedded passwords, API keys, internal IPs presented as credentials): clean. The install/upgrade/rollback instructions in #381 line up with the artifact names and channels this repo actually produces (apk add --allow-untrusted / opkg install, stable vs alpha channels), and #382's report template asks for the fields the maintainers need (version strings that --version now emits reliably, thanks to #383).

One sequencing note: land #381 before #382 so the intake-channel terminology lands with its guide in tree.

Disposition: land both, #381 then #382.

[felixfelix-bot]

Conflicts resolved — merged current main (60530c6, which carries #379, #380, #385 and #387) into docs/rc-tester-guide.

Only CHANGELOG.md needed manual resolution (RELEASE-NOTES.md auto-merged). Both sides kept; sections follow this file's own released-section order; ([#N](…)) links preserved; nobody's entries removed or reworded.

Facts re-checked against the current tree: package version string, config path (/etc/tollgate/config.json), and the install warnings all match the tree as it stands.

Two items left deliberately untouched, flagged rather than rewritten:

1. The quoted pre-recorded output block still shows PKG_LICENSE:=CC0-1.0. That is accurate for the current tree (packaging/Makefile:29) — it becomes stale only if feat(build): reproducible package builds — pinned inputs, SOURCE_DATE_EPOCH, reproducibility test #383's licence change lands. Quoted output was not edited.
2. §1 marks 24.10/opkg as unsupported, while the merged RELEASE-NOTES.md documents an .ipk path for "24.10 and earlier". Both are the authors' text and neither contradicts the tree, so this is flagged as a possible inconsistency rather than silently changed.

Merge is a fast-forward from 585f00c to 6895002 — no force-push, no history rewrite.

PR is now MERGEABLE; the only remaining gate is the approval.