20260911-0254-air-key-doc-consistency-repair Repair Air/Key documentation consistency after the supplier-guide rewrite

• status: completed
• createdAt: 2026-09-11 02:54
• approvedAt: 2026-09-11 02:50
• relatedTask: 20260911-0251-air-key-doc-consistency-repair

Context

The 2026-09-10 rewrite (task 20260910-0724-air-key-product-specifications) replaced the tri-radio Air Hub and the old Air/Key specifications, then split X03-air-key-supplier-guide.md into air-switch/P05-air-supplier-guide.md and key/P06-key-supplier-guide.md.

Verified as correct and left alone: the 29 requirement IDs map bidirectionally onto V-01…V-10; the battery arithmetic (400000/(365*24*N) = 22.83 / 15.22 / 9.13 uA); the LED channel budget (5 channels per key, 20/40 total, 1/2 x LP5024); the 32 x 4 = 128 key capacity; and the TJA1463 VBAT 4.5–28 V limit, which matches the datasheet figure already cited in X01.

The defects are in what the rewrite did not follow through:

• COMPLIANCE-MATRIX.md row for Air/Gateway still describes the retired tri-radio enclosure and requires NMEA 2000 certification, while both guides send suppliers to that file for compliance scope.
• The Gateway requires NFC antenna tuning, install accessibility and per-unit NFC EOL testing, but the guide's OOB flow puts the reader in the authorized tool, and the recommended nRF54L15 has NFC-A tag emulation only — it cannot read another device.
• X01, X02, P07-studio-architecture.md, P03-mate-data-model.md, P12-tag-design.md and two research files hold roughly thirty §n and FR-nn references into gateway/Air/Key sections deleted by the rewrite. The gateway document no longer has an FR namespace at all. VitePress validates Markdown links only, so the build does not catch these.
• Studio and Mate never got the scope notice that X01, X02 and Tag received, so they still read as if the base gateway carries standalone-mode cloud uplink, Tag rules and a signed radio allowlist.
• FR-nn means one thing in the Air specification and another in the Key specification; after the split, O-03/O-05/O-06/O-07 mean different things in each guide. The supplier response template keys on these IDs.
• The split replaced the X03 token with a bare, unlinked "供应商指南" phrase, leaving double spaces and no way to tell which guide a sentence means.
• IF-01 requires a frozen X01/X02 while both files are drafts carrying no revision identifier.
• The two guides duplicate sections 1, 2, 7, 8, 10, 11 and 12 with no statement that the common clauses must move together.
• Gateway supply, environment and bus-termination requirements have no traceable ID; only KEY-01 covers the four-wire interface.

Proposal

Nine groups, applied in the approved order.

A. Compliance scope. Rewrite the COMPLIANCE-MATRIX.md Air row to the current base product (BLE 2.4 GHz plus a replaceable primary cell), move Wi-Fi, 433 MHz, LoRa, the co-location assessment and the NMEA 2000 obligation into an explicitly separate expansion note.

B. Gateway NFC. Make the Gateway match the guide's own OOB flow: the authorized tool reads the Air's dynamic OOB data, the base Gateway carries no NFC reader. Remove NFC from the Gateway's structural row, EOL test list, RF tuning paragraph and delivery list; record "whether a Gateway-side reader is needed" under the OOB open item, noting that the recommended silicon provides tag emulation only.

C. Dangling cross-references. Repoint each §n / FR-nn reference to the section or ID that now carries the content; where the referenced capability became expansion scope, keep the technical text and point at the scope notice instead of a dead section number. Also correct the two stale silicon statements this exposes in X01 (the ESP32-C5 key manager attribution and the 128 KB KEY trimmed-image rule).

D. Scope notices. Give P07-studio.md and P03-mate-software.md the same dated scope notice already carried by X01, X02 and the Tag documents.

E. Namespaces. Drop the FR-nn aliases from the Air specification, give its three unaliased rows real IDs (AIR-08 dimming binding, AIR-09 optional double-click, AIR-10 retry and transaction reuse) and add them to the Air guide requirement table with verification evidence. Retitle the Key specification column so FR-nn reads as the live Key namespace rather than a legacy one. Prefix the open items as AIR-O-nn and KEY-O-nn, updating every referring document.

F. Guide references. Give each guide a short name (Air 指南 / Key 指南) in its header, link the first occurrence per document, and remove the replacement artifacts.

G. Interface baseline. Add a baseline identifier to X01 and X02 headers and change IF-01 and section 7 to name that baseline instead of a frozen revision that does not exist.

H. Duplication control. State in section 1 of both guides which sections are common and that a change to one must be applied to the other.

I. Gateway electrical ID. Add GW-05 (four-wire supply, 8–32 V, IP54, −20…+60 °C, branch node without fixed termination) to the Air guide requirement table under V-07/V-08 and reference it from the Gateway specification.

Then update docs/changelog.md (including the previously unrecorded X03 split) and the task and plan indexes.

Risks

• Renaming the open items touches six documents; a missed reference leaves a reader looking for O-03 with no owning document. Mitigated by grepping for the bare pattern after the rename.
• Removing Gateway NFC is the one change that alters a hardware requirement rather than a pointer. It follows the guide's own pairing flow and the recommended part's capability, and the question stays open under AIR-O-02 rather than being silently closed.
• Adding AIR-08…10 and GW-05 extends the requirement matrix; both guides' requirement-to-test mapping must stay bidirectional, which is re-checked during verification.

Scope

About sixteen files: COMPLIANCE-MATRIX.md, PRODUCT-PLAN.md, OPEN-QUESTIONS.md, the two supplier guides, the six Air/Gateway/Key specification and design files, X01, X02, Studio, Mate, Tag and two research files, plus changelog and indexes. No technical claim is introduced that is not already sourced in the package.

Alternatives

• Leave the dangling references and rely on the blanket "verify at D1" notice already added to X01/X02. Rejected: the notice is a disclaimer, and the references silently resolve to nothing for anyone reading today.
• Re-merge the two supplier guides to remove the duplication. Rejected: it reverses a deliberate restructuring from the previous session; a drift-control statement is enough for now.

Annotations

• 2026-09-11: The user reviewed the findings and approved repair in the order 2 -> 3 -> 1 -> 8 -> 4/5/7 -> remainder. The three product decisions (Key 8 power ceiling, Gateway deep-sleep mode, battery-versus-latency criterion) were reported and deliberately left out of this plan.