docs(tests): map the test estate in the parent README

[Amperstrand]

Small docs fix, self-explanatory: the parent tests/README.md documented only the hardware data-measurement harness — a newcomer (human or agent) had no way to discover the cloud-lab, contract, packaging, sim, or happy-path suites. Now it's a one-table map of the estate, names the cloud-lab as the default for logic-level work, and points at the shared-host runbook.

Docs-only; no battery needed (nothing executable changed) — verified by reading the rendered table against the actual directory contents.

[Amperstrand]

Technical review (evidence pass) — PR head 0193b3987036a0a06d79771a920c643db0db1a6c (merge base 2796d96c, #574; main has since moved 21 commits). GitHub reports the PR CONFLICTING with main.

This PR does not contain the change it describes. The body advertises a docs-only rewrite of tests/README.md into a one-table map of the test estate. The diff touches 22 files, +954/−2, and not one hunk touches tests/README.md — the file at this head is unchanged from before the fork point. All three body claims (the table, naming the cloud-lab as the default for logic-level work, the runbook pointer) are absent, which means the stated verification — "reading the rendered table against the actual directory contents" — cannot have run against this head.

What the diff actually is: a frozen prefix of #549. The eight commits here are byte-identical (same SHAs, d711275c…0193b398) to the first eight commits of open #549 (feat/wallet-recover, since advanced to a15be70f). It is the full wallet-recover chain — CheckTokenSpendable on the WalletPort (src/tollwallet/checkstate.go), the merchant seam, the socket action (src/cli/server.go#L219-L220) and client command, the wedged-mint bound, and the PENDING/full-coverage fix, changelog entry included (CHANGELOG.md#L27-L35). The branch name says docs/tests-readme-map, but the head is feat/wallet-recover's tip as of Sept 24 — the docs commit was never added, or the wrong local branch was pushed. That stale feature tip is also why the PR conflicts; a one-file docs edit would rebase clean.

I am deliberately not reviewing the wallet-recover content here. That code is money-path (NUT-07 checkstate, drain-journal token strings printed to the operator) and belongs to #549's review under the fund-safety rules; it rides the existing seams (WalletPort, MerchantInterface, CLIResponse), carries its own tests, and adds no new dependency surface — but none of that is this PR's question, and nothing here should be read as a verdict on it. Same for the commit messages: well-structured, accurate, no assistant attribution — they're just #549's commits. No CI rollup is visible on the GitHub side, consistent with ngit being the build of record; also moot once the branch is repointed.

Blocking fix — repoint the branch at the real docs commit:

git switch -C docs/tests-readme-map origin/main
git cherry-pick <the-map-commit>      # the commit that actually holds the table
git push --force-with-lease origin docs/tests-readme-map

The conflict evaporates along with the feature payload. If the map commit doesn't exist yet, two things to fold in when writing it against current main: tests/README.md gained a "Router Happy-Path Harness" section after this fork point (4b8be2b8 #563, d649d91f #590), and the estate keeps growing (#557 runbook, #569 crash-window lane, #586 second-purchase happy path) — enumerate suites by directory rather than by PR number so the table doesn't rot. Once re-pushed, a Changed / Internal changelog one-liner is sufficient (doc-only entries may be batched per AGENTS.md), or say so in the body and skip it deliberately. No issue Closes #N appears to exist for the map; if the estate map was discussed somewhere, referencing it would help discovery.

Disposition: request-changes — one blocker: force-push the branch that contains the advertised tests/README.md map and only that commit. Once it's up I'll do the short docs pass the PR actually deserves.

[Amperstrand]

Branch restored and rebased (post-review maintenance). This branch had been force-pushed over with #549-series commits; the README map survived only as a dangling commit. Restored from f8b20b89, rebased onto current main (afc86b3f). The one conflict — tests/README.md vs #586's newly-landed happy-path harness section — was resolved by keeping both: the map structure plus the harness section appended intact. Head is now a1a20ade. The prior review's blocker ("force-push the branch that contains the advertised map") is thereby addressed.

[Amperstrand]

Self-QA pass (author's account) — head a1a20ade797160d27763a08aa68ed7f6b0078fb9.

Verified the table against the tree: every suite it names exists (cloud-lab, contract, packaging, sim, router-happy-path, happy-path, plus the hardware harness scripts), the cloud-lab-first guidance for logic-level work matches AGENTS.md's own instruction to extend cloud-lab lanes rather than invent harnesses, and the shared-host runbook pointer matches #557's runbook. Docs-only, no executable change, no battery applicable. The branch is 5 behind main — trivial docs merge-forward before squash.

Disposition: land (needs one outside approval — author's own PR).

[felixfelix-bot]

Conflict resolved in #670 — it merges main (44 commits, through #648) into docs/tests-readme-map and keeps both sides of the single CHANGELOG.md hunk under ### Changed / Internal: this PR's tests-README bullet first, then main's #573 session-ticket bullet, verbatim. tests/README.md merged cleanly, and the merged map is still complete (main added no new test environment). The PR's own diff is unchanged (2 files, +54/−14). Merging #670 into this branch makes #570 mergeable.

[felixfelix-bot]

Conflicts resolved on a rebase of the single commit onto current main (6247731f).

Replacement PR: #674 — #674 — base main, head pr/docs-tests-readme-rebased @ 925e4635, 2 files, +54/−14.

• CHANGELOG.md was the only conflict: main's release commit pulled the list into ## [v0.6.0-rc1] → ### Changed / Internal, where the bullet now leads main's MAC-rotation entry. Kept verbatim; git diff main -- CHANGELOG.md is that bullet alone. One blank line is absorbed because main's section already supplies the separator (+7 → +6), no text lost.
• tests/README.md is byte-identical to git merge-tree main <this PR> — git's own three-way merge, +48/−14, untouched by hand.

Verified on the rebased head: every relative link in the map resolves (the cloud-lab/RUNBOOK.md reference is explicitly hedged as "on the runner branch"), offline contract suite green over this tree (build-purity 3/3 incl. go vet -tags testenv, import paths 213 ok, deps-sync 124 in sync), and the six environments in the table all exist as written in main's tests/.

Scope note (pre-existing, unchanged here): the table does not name the root-level shell families (13 uci-defaults-*_test.sh, the two ngit-*_test.sh, verify_publication_test.sh) nor size//docs/ — an exhaustive map of those would be a follow-up, not something to add to an approved PR.

#670 (the earlier merge-forward rebase of this branch) is closed as superseded — its base is the branch, so merging it would flatten main into it. Merge #674 and this PR closes as superseded, or force-push pr/docs-tests-readme-rebased onto docs/tests-readme-map (recipe in #674's body).

[felixfelix-bot]

This PR's content is already in main, landed as #674 (squash 90821fb1, merged 19:1xZ — docs(tests): map the test estate in the parent README (#674)).

• tests/README.md in main carries the mapped table and the runner-reference paragraph from this branch; CHANGELOG.md carries the entry (the +7 here vs +6 landed is only the blank separator, which main's section supplies).
• So the CONFLICTING flag is cosmetic: GitHub is diffing against a pre-landing base, and merging would try to re-apply what is already there.

One follow-up nit while it is fresh: the merged text still says the cloud-lab runbook is "on the runner branch; until it merges, the short version: …" — tests/cloud-lab/RUNBOOK.md is in main now (it arrived with #557, merged just before #674). Worth a one-line fix-up: drop the hedge and link it directly.

Recommended action: close this PR as landed (I lack the permission to close it — felixfelix-bot gets a ClosePullRequest permissions error).

[felixfelix-bot]

Follow-up filed for the one stale claim in the text that landed here: tests/cloud-lab/RUNBOOK.md is in main (arrived with #557, merged just before the map landed as #674), so the "on the runner branch; until it merges" parenthetical is no longer true.

#677 — #677 — links the runbook directly and keeps the summary (+2/−3, one file). Separate PR so this one can simply be closed as landed.

[Amperstrand]

Superseded by #674 — same docs change (test-estate map in parent README), rebased onto current main and merged there. Closing to keep the queue clean.