docs: add v0.21.0 RC testing guides for humans and agents

docs/testing-guides/v0.21.0/README.md

@@ -0,0 +1,76 @@
+# LND v0.21.0 — Release Candidate Testing Guide
+
+This directory contains structured testing guides for the v0.21.0
+release candidate. Each guide targets one feature or one high-risk
+regression surface, and follows the same template so both human RC
+testers and automated agents can work through them predictably.
+
+The RC announcement is [discussion
+#10766](https://github.com/lightningnetwork/lnd/discussions/10766).
+The full release notes are at
+[`docs/release-notes/release-notes-0.21.0.md`](../../release-notes/release-notes-0.21.0.md).
+
+## How to use this directory
+
+Each guide is self-contained and follows the layout in
+[`_template.md`](./_template.md):
+
+1. **Prerequisites** — what to build, which backend, which network,
+   which peers and config flags.
+2. **Setup** — copy-pasteable commands to reach the starting state.
+3. **Scenarios** — numbered cases, each with a deterministic
+   pass/fail signal (an exact RPC field value, log line, or exit
+   code — not "should succeed").
+4. **Failure investigation** — logs and RPCs to query when a scenario
+   fails.
+
+**Humans:** pick guides matching the surface you care about and run
+through the scenarios. Report results on
+[discussion #10766](https://github.com/lightningnetwork/lnd/discussions/10766)
+or open an issue if you find a regression.
+
+**Agents:** the fixed section order is the contract. The Pass/Fail
+signal line in each scenario is the verification target.
+
+## Guides
+
+Ordered by risk to RC testers. Start at the top.
+
+### Headline features
+
+| # | Guide | Summary |
+|---|---|---|
+| 1 | [Production simple taproot channels](./production-taproot-channels.md) | Feature bits 80/81, optimized scripts, map-based nonce encoding. |
+| 2 | [RBF cooperative close for taproot channels](./rbf-taproot-coop-close.md) | MuSig2 JIT nonces, nonce-reuse prevention, `--protocol.rbf-coop-close`. |
+| 3 | [Payment store KV→SQL migration](./payment-sql-migration.md) | Automatic migration for `--db.use-native-sql` nodes; bbolt users must `lndinit` first. |
+| 4 | [Onion messaging + rate limiting](./onion-messaging.md) | Basic onion message forwarding, pathfinding, per-peer/global rate limiters, channel-presence gate. |
+
+### High-risk regressions and breaking changes
+
+| # | Guide | Why it's risky |
+|---|---|---|
+| 5 | [Closed-channel tombstone (sqlite/postgres downgrade trap)](./closed-channel-tombstone.md) | One-way upgrade on KV-over-SQL backends; downgrading after closes resurrects channels as open. |
+| 6 | [Reorg-safe channel closes + MinCLTVDelta change](./reorg-safe-closes.md) | Closes now require 3–6 confs scaled to capacity; `MinCLTVDelta` raised 18→24 (breaking for custom-CLTV invoices). |
+| 7 | [`chain_params` network-mismatch DB guard](./chain-params-guard.md) | Native-SQL nodes refuse to start if the DB was previously used on a different network. |
+| 8 | [`GetDebugInfo` log opt-in breaking change](./getdebuginfo-log-optin.md) | Clients relying on the `log` field break unless they pass `include_log=true`. |
+
+### New RPCs / operator features
+
+| # | Guide | Summary |
+|---|---|---|
+| 9 | [New payment-adjacent RPCs](./payment-rpcs.md) | `DeleteForwardingHistory`, MuSig2 coordinator nonces, `EstimateFee` inputs, HTLC event invoice failures, `SubscribeChannelEvents` updates. |
+| 10 | [Multiple read-only middleware interceptors](./middleware-multiple-readonly.md) | More than one read-only RPC middleware interceptor can register at once. |
+
+## Reporting results
+
+- Working as expected: a 👍 reaction on the RC discussion is fine.
+- Regression or unexpected behavior: open an issue with the guide
+  name, scenario number, and the captured output. Link to the issue
+  in the discussion thread.
+
+## Authoring new guides
+
+Copy [`_template.md`](./_template.md) to `<feature-slug>.md`, fill in
+every section, and add an entry to the table above. Keep the section
+order intact. If a section genuinely doesn't apply, write `n/a` —
+don't delete the heading.

docs/testing-guides/v0.21.0/_template.md

@@ -0,0 +1,140 @@
+<!--
+This is the template for v0.21.0 RC testing guides. Copy it to
+`<feature-slug>.md` in this directory and fill in every section.
+
+Keep the section order and headings exactly as written below. Agents
+(and human reviewers) rely on the fixed layout to navigate the guides.
+
+Style rules:
+- Pass/fail signals must be deterministic: an exact RPC field value, an
+  exact log line (regex if needed), an exit code, or a state observable
+  via a specific command. "Should succeed" is not a signal.
+- Setup blocks must be copy-pasteable. Use placeholder vars
+  ($ALICE_RPC, $BOB_PUBKEY, etc.) and define them in Prerequisites.
+- Prefer regtest/signet over mainnet for setup. If mainnet is the only
+  meaningful surface, say so and call out the risks.
+- Use absolute references (PR numbers, file paths, RPC method names),
+  not "the new feature" or "this change".
+-->
+
+# <Feature title> — v0.21.0 RC Testing Guide
+
+**PRs:** #XXXX, #YYYY
+**Risk:** headline | high-regression | new-rpc | operator-feature
+**Audience:** node operators | RPC clients | LSPs | wallet integrators
+**Backends affected:** bbolt | sqlite | postgres | all
+**Networks:** regtest | signet | testnet | mainnet
+
+## What this feature does
+
+One to three sentences in plain English. No marketing language. State
+what changed in observable behavior, not internal refactors.
+
+## Why it matters / what could break
+
+Concrete failure modes a tester should look for. Examples:
+- "If X is wrong, channel force-closes."
+- "If Y is wrong, payments stall in `IN_FLIGHT`."
+- "If Z is wrong, the node refuses to start after upgrade."
+
+## Prerequisites
+
+- **lnd build:** v0.21.0-beta.rc1 or newer, built with `<tags>`.
+- **Backend:** `bitcoind` / `btcd` / `neutrino`.
+- **Network:** regtest unless noted.
+- **Peers:** N nodes (Alice, Bob, Carol). State counts, channels,
+  balances at the start of the scenarios.
+- **Config flags:**
+  ```
+  protocol.option-name=value
+  db.option-name=value
+  ```
+- **Tools:** `lncli`, `bitcoin-cli`, `jq`, ...
+
+Define every shell variable used in the Setup and Scenarios blocks:
+```
+ALICE_RPC=localhost:10001
+BOB_PUBKEY=03...
+```
+
+## Setup
+
+Numbered, copy-pasteable steps to get from "fresh nodes" to the
+starting state for the scenarios. End with a single command whose
+output proves setup succeeded.
+
+```bash
+# 1. Start nodes
+...
+
+# 2. Fund Alice
+...
+
+# 3. Open Alice→Bob channel
+...
+
+# Setup verification:
+lncli --rpcserver=$ALICE_RPC listchannels | jq '.channels | length'
+# Expected: 1
+```
+
+## Scenarios
+
+### S1: <short scenario name — happy path>
+
+**Goal:** What this scenario proves.
+
+**Steps:**
+```bash
+# 1. ...
+# 2. ...
+```
+
+**Expected:**
+- Concrete observable 1 (RPC field = value, log contains line, etc.)
+- Concrete observable 2.
+
+**Pass/Fail signal:**
+- **PASS** if `lncli ... | jq '.field'` returns `"expected_value"`.
+- **FAIL** if the command errors, returns a different value, or the
+  log shows `<exact error string>`.
+
+---
+
+### S2: <short scenario name — edge case>
+
+**Goal:** ...
+
+**Steps:** ...
+
+**Expected:** ...
+
+**Pass/Fail signal:** ...
+
+---
+
+(Add 2–5 scenarios. Cover at least one happy path, one edge case, and
+one negative-path / misconfiguration scenario.)
+
+## Failure investigation
+
+When a scenario fails, here's where to look first:
+
+- **Logs:**
+  - `grep -i "<keyword>" ~/.lnd/logs/bitcoin/mainnet/lnd.log`
+  - Subsystems to enable at `debug`: `<SUBSYSTEM_1>`, `<SUBSYSTEM_2>`.
+- **RPCs to query for state:**
+  - `lncli <command>` — what to look at and what value indicates the bug.
+- **Common bugs / prior regressions:** brief pointers, ideally with
+  PR / issue numbers.
+
+## Related itests
+
+Point to itest cases that exercise this code path. They're not a
+substitute for manual scenarios but are useful executable references:
+- `itest/lnd_<area>_test.go::Test<Name>`
+
+## Out of scope
+
+What this guide does not test (to prevent scope creep and to direct
+testers to the right guide).