docs: WHOOP 4 protocol parity, contract-to-implementation map and source-reference check

[bhelm]

What this PR does

Follows #2183. It brings the WHOOP 4 side of the protocol reference to the same topical depth as WHOOP 5/MG, and it changes the direction of the protocol pages: they now read as an interoperability reference for the wire protocol, while NOOP's own implementation is described in one place and linked by file and symbol.

• WHOOP 4 coverage. A comparative command matrix lists every ID 1–159 for both generations. WHOOP 4 now has its own contracts for transport, history, battery, identity, records (types 40, 43 and 47 v24/v25), configuration, alarms and haptics, and the update container, version-bounded to the 41.17.6.0 MAXIM / 17.2.2.0 NORDIC package. Commands outside the documented 41.17.6.0 set are marked as such. Where device captures show an older command working, as for history offload (20/22/23) and clock (10/11), that observation is kept beside the status instead of overriding it.
• One structure for both generations. Every topic chapter has a ## WHOOP 4 and a ## WHOOP 5/MG section, and the large chapters have a contents list. Renamed headings keep their previous anchors, so all 174 anchors on main still resolve.
• Protocol pages describe the wire, not the client. Swift/Kotlin symbols, timers, guards and decoder selection moved from the profile and topic pages to PROTOCOL_IMPLEMENTATION.md. What remains on the protocol pages are support statements such as "supported by NOOP". The acknowledgement-versus-effect statements you pointed at in docs: expand protocol coverage and clarify WHOOP 4/5 compatibility #2183 are kept on every page.
• Contract-to-implementation map. PROTOCOL_IMPLEMENTATION.md now maps 57 contracts to the Swift and Android file and symbol that implement them. A dash marks a contract a platform does not implement: type-43 variants on Android, R22 versions and gyro mode on both, and firmware updates on both by design.
• Hardware overview on both profile pages, limited to parts a decoder needs in order to interpret values: Analog Devices MAX86176 (optical and ECG front end), TDK InvenSense ICM-45686 (IMU and pedometer), TI DRV2625 (haptics), onsemi LC709205F (fuel gauge), ams OSRAM AS6221 (skin temperature), and on WHOOP 4 the Nordic nRF52840 that carries the BLE services and its own update image. Each part is tied to the contracts it explains; none of this implies calibration.
• Corrections to the merged reference, among others:
  • GET_DATA_RANGE values sit at cmdOff + 12/16/24, matching DataRange.swift; the implementation notes had them two bytes early.
  • The implementation notes now show the 9-byte WHOOP 4 alarm body the client actually sends.
  • Format-1 bytes 6–7 are the header CRC16; there is no format tag at byte 6.
  • Packet types 37/38 are not confirmed as the current command path; commands and responses are 35/36.
  • The WHOOP 4 type-43 variant is keyed by payload length (declared length − 7), and the IMU scales are an interpretation the WHOOP 4 client does not apply.
  • Command 97 is sent by the Swift stuck-strap watchdog, not on every connect. GET_FF_VALUE (128) is sent as the R22 disable read-back.
  • The WHOOP 4 connect sequence includes REPORT_VERSION_INFO (7), and the sender table no longer lists IDs that have no sender.

The credits section on the entry page and the existing attribution are unchanged.

CI

docs/protocol-examples/check_source_references.py is stdlib-only. For every file-plus-symbol link in PROTOCOL_IMPLEMENTATION.md it checks that the file exists and that the symbol occurs as a whole word; backtick paths are checked for existence. It runs as one more step in Source Hygiene, beside the example validator, on every PR and in under a second. Six unit tests in Tools/test_check_source_references.py cover it, and the core Tools floor moves from 108 to 114.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Documentation
• CI / tooling

How it was tested

• python3 docs/protocol-examples/validate_examples.py passes.
• python3 docs/protocol-examples/check_source_references.py: 163 references in 46 files, 0 failures. The new unit tests cover missing files, missing symbols, missing backtick paths and whole-word matching.
• Core Tools/ suite: 115 tests pass locally.
• Link and anchor check over docs/**/*.md and README.md: 642 links into the protocol pages, 0 broken; every anchor present on main still resolves.
• Command matrix: 159 rows, one per ID; the counts in the prose are recomputed from the table.
• Three independent review passes: internal consistency, reader path and wording, and documentation against the Swift and Kotlin code. Findings were corrected and the checks rerun.
• No new real-hardware test. Swift and Android were not built, because no application or package source changed.

Checklist

• Swift package tests pass for any package I touched (swift test in Packages/<name>) — N/A; no packages changed.
• Android unit tests pass if I touched android/ (./gradlew testFullDebugUnitTest) — N/A; Android unchanged.
• No new build warnings introduced — application builds not run; no application or build sources changed.
• UI changes use only StrandDesign tokens — no hardcoded colors, fonts, or spacing — N/A; no UI changes.
• No hardcoded hex frame bytes; protocol facts live in the schema / decoders — N/A to runtime code; this PR documents wire layouts only.
• Follows the conventions in docs/CONTRIBUTING.md.
• I did not commit generated output (Strand.xcodeproj/) or any secrets/keystores.

Related issues

No issue is closed by this PR.