docs: add an index, and fix the control mode in the TNC reference

Seventeen documents in docs/ with no way in.  A reader could not tell
that ARQ.md is current reference while SPEED-REGRESSION-FINDINGS.md is a
dated investigation record -- both are just filenames.  docs/README.md
now sorts them into reference, guides and findings, says plainly which
kind is kept current, and gives each a line on the question it answers
rather than restating its title.  The README links it, and names the
three documents most people actually want.

TNC.md was wrong.  It said CALL and CQ frames go out on DATAC13 in three
places; the control mode has been DATAC16 since it replaced DATAC13
(arq_protocol.h:198), and both paths send on sess->control_mode
(arq_fsm.c:761, arq.c:535).  This is the user-facing command reference,
so someone integrating against it was being told the wrong mode.  Same
staleness the README carried -- ARQ.md and MODES.md were already right,
and the remaining DATAC13 mentions there are correct history.

Checked: every relative link in both files resolves, and the index
covers all seventeen documents with none missing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: rafael2k

README.md

@@ -260,7 +260,17 @@ See the included [mercury.ini.example](mercury.ini.example) for all available se
 
 ## Documentation
 
-Online HTML docs: https://rhizomatica.github.io/mercury/
+**[docs/](docs/README.md)** — the full index, sorted into reference (how Mercury
+works today), guides (building, signing, Reticulum, sanitizers) and findings
+(dated records of investigations and why decisions were made).
+
+The three you are most likely to want:
+
+- [docs/ARQ.md](docs/ARQ.md) — the ARQ data link, end to end
+- [docs/TNC.md](docs/TNC.md) — every TNC command, for driving Mercury from your own software
+- [docs/MODES.md](docs/MODES.md) — all modes with measured performance
+
+Rendered HTML: https://rhizomatica.github.io/mercury/
 
 ## Logging and timing traces
 

docs/README.md

@@ -0,0 +1,63 @@
+# Mercury documentation
+
+Start with the [project README](../README.md) if you are new. This page is the
+map of everything else.
+
+Documentation here falls into three kinds, and it helps to know which you are
+reading: **reference** describes how Mercury behaves today and is kept current;
+**guides** are task-oriented; **findings** are dated records of an
+investigation, kept because the reasoning and the negative results are worth
+having — they are not updated as the code moves on.
+
+## Reference — how Mercury works
+
+| Document | What it covers |
+|---|---|
+| [ARQ.md](ARQ.md) | The ARQ data link: state machine, frame formats, timers, mode ladder, and the OTA tuning guide. The main architecture document. |
+| [TNC.md](TNC.md) | Every TNC command and async status on the control socket. What you need to drive Mercury from your own software. |
+| [MODES.md](MODES.md) | All modulation modes with measured bandwidth, payload, FEC and delivery rates — including the Mercury-specific DATAC15/16/17 and QAM16C2. |
+| [watterson_model.md](watterson_model.md) | The HF channel simulator used for every measurement in these docs, and how its noise axis is calibrated. |
+
+## Guides — doing a particular thing
+
+| Document | What it covers |
+|---|---|
+| [RETICULUM.md](RETICULUM.md) | Carrying a Reticulum mesh over HF, via the broadcast port or an ARQ backbone. |
+| [MACOS-UNIVERSAL.md](MACOS-UNIVERSAL.md) | Building the self-contained universal macOS app with vendored static Hamlib. |
+| [WINDOWS-SIGNING.md](WINDOWS-SIGNING.md) | Authenticode signing for Windows releases. |
+| [MACOS-VM-GLFW-SOFTWARE-OPENGL.md](MACOS-VM-GLFW-SOFTWARE-OPENGL.md) | Running the Fyne UI on a macOS VM with no GPU. |
+| [SANITIZERS.md](SANITIZERS.md) | ASan/UBSan and TSan builds. |
+| [FUZZING.md](FUZZING.md) | Fuzzing the frame parsers. |
+
+## Findings — why things are the way they are
+
+Point-in-time investigation records. Each answers a question that was open at
+the time; the conclusions shaped the code, and the methods are reusable. Read
+them for reasoning, not for current behaviour.
+
+| Document | The question it answered |
+|---|---|
+| [HARQ-FINDINGS.md](HARQ-FINDINGS.md) | Does soft-combining repeated frames actually rescue a link at the fading cliff? (Yes — roughly half the frames, where single-shot delivers none.) |
+| [FADE-CLIFF-DECISION.md](FADE-CLIFF-DECISION.md) | Should the S1 fade-cliff fix be merged? Simulation evidence behind the decision. |
+| [SPEED-REGRESSION-FINDINGS.md](SPEED-REGRESSION-FINDINGS.md) | Why a pre-2.0 build was slower than v1.9.9 on the bench — FEC under fading and gear-shift oscillation, not the guard intervals everyone suspected. |
+| [OTA-PHASE-A-SNR-CALIB.md](OTA-PHASE-A-SNR-CALIB.md) | Why the mode ladder stuck at the bottom: per-mode SNR estimation bias. |
+| [broadcast-length-prefix-root-cause.md](broadcast-length-prefix-root-cause.md) | Why VarAC broadcasts would not decode. |
+| [ARDOP-IDEAS.md](ARDOP-IDEAS.md) | What is worth borrowing from ARDOP. |
+| [PLAN-arq-robustness-tx-gain.md](PLAN-arq-robustness-tx-gain.md) | Improvements proposed from Gary K7EK's review. |
+
+## Elsewhere
+
+- **Rendered HTML**: https://rhizomatica.github.io/mercury/
+- **Web interface**: https://rhizomatica.github.io/mercury/app/ (source in [app/](app/))
+- **Configuration**: every setting with its default is in
+  [mercury.ini.example](../mercury.ini.example)
+- **Mailing list**: https://lists.riseup.net/www/info/hermes-general
+
+## A note on the measurements
+
+Numbers in these documents come from a calibrated bench, not from estimates.
+The channel simulator is checked against published upstream figures before its
+results are trusted for our own modes — `docs/MODES.md` records that
+cross-check explicitly. Where a result was negative, it is written down as a
+negative result rather than removed; several of the most useful pages here are
+records of something that did **not** work.

docs/TNC.md

@@ -171,7 +171,8 @@ CONNECT <mycall> <theircall>\r
 
 **Response:** `OK\r` if the command was accepted, `WRONG\r` on error.
 
-Mercury will transmit CALL frames on DATAC13, advertising the local BW token,
+Mercury will transmit CALL frames on DATAC16 (the control mode), advertising
+the local BW token,
 and wait for an ACCEPT carrying the negotiated session BW.
 On success, the asynchronous response
 `CONNECTED <sourcecall> <destcall> <bandwidth>\r` is sent on the control port,
@@ -186,7 +187,7 @@ CONNECT AAAA BBBB\r
 
 ### CQFRAME
 
-Transmit a compact DATAC13 CQ frame.
+Transmit a compact CQ frame on the control mode (DATAC16).
 
 ```
 CQFRAME <sourcecall> <bandwidth>\r
@@ -421,7 +422,7 @@ the session, and `<destcall>` is always the station that was called.
 
 ### CQFRAME
 
-Sent when Mercury decodes a compact DATAC13 CQ frame on the air.
+Sent when Mercury decodes a compact CQ frame on the air.
 `<sourcecall>` is the transmitting station and `<bandwidth>` is the BW token
 advertised inside that CQ frame (`500`, `2300`, or `2750`).