20260913-2340-air-docs-consolidation Consolidate the Air and Air Hub documents into two files

• status: completed
• createdAt: 2026-09-13 23:40
• relatedTask: 20260914-0010-air-subghz-lora-and-consistency

Context

• Today Air and Air Hub are spread over eight files, 795 lines. Air: P05-air-switch.md (78), P05-air-switch-design.md (77), P05-air-switch-platform-options.md (48), P05-air-switch-esp32h2-evaluation.md (121). Air Hub: P05-air-hub.md (81), P05-air-hub-design.md (79), P05-air-hub-platform-options.md (76). Shared: P05-air-supplier-guide.md (235), which covers both halves because one manufacturing scope quotes them together.
• Reading either product means chaining four files. The Level 1 record states a target, the design appendix expands it, the platform-options file argues the choice, and the supplier guide restates the whole thing as an RFQ. The same figure appears in three registers, which is how the drift below happened.
• The consolidation collides with a package rule. product/index.md mandates Level 1 (Pxx-<name>.md) versus Level 2 (Pxx-<name>-design.md) separation and states "Level 2 不得改动任何 Level-1 数值". Two self-contained documents abandon that split for this product line only, so it needs a recorded deviation under docs/decisions/ per CLAUDE.md.
• 29 documents link into these files, 19 of them outside product/switch/: PRODUCT-PLAN, OPEN-QUESTIONS, product index, Mate (3), Studio (2), Control (2), Tag (2), shared X01/X02, Key (2), research (3). Every link must be rewritten, most to a section anchor rather than a file.
• Merging forces the contradictions into the open. The five defects recorded in task 20260914-0010 currently survive because they sit in different files. Put side by side in one document, three of them become direct self-contradiction on the same page — which is the point, but it means the merge cannot be purely mechanical.

Proposal

A. Recommended: two self-contained documents, contradictions marked rather than silently resolved

A1 — Target structure.

New file	Replaces	Approx. size
P05-air.md — Air 无线开关	P05-air-switch.md, P05-air-switch-design.md, P05-air-switch-platform-options.md, plus the Air-only clauses of P05-air-supplier-guide.md	~330 lines
P05-air-hub.md — Air Hub 共用中枢	current P05-air-hub.md, P05-air-hub-design.md, P05-air-hub-platform-options.md, plus the Air-Hub-only clauses of the supplier guide	~300 lines

Both follow the same eight-part outline: 1 产品边界与定位 · 2 目标规格 · 3 功能与状态行为 · 4 平台与选型（含方案对比与否决理由） · 5 设计要点（架构、功耗、引脚、固件） · 6 安全、配对与接口 · 7 供应商交付与验收 · 8 待决事项 · 9 变更记录.

A2 — What happens to the two files that do not fit the split.

• P05-air-switch-esp32h2-evaluation.md (121 lines) is a device evaluation with datasheet sourcing, not a specification. Move it to research/ as an evidence report and link it from P05-air.md §4. Keeping it inline would make the Air document 450 lines and mix evidence with requirements.
• P05-air-supplier-guide.md is deleted, and its clauses are split. Its genuinely common sections — file usage, responsibility boundary, EOL, deliverables, quoting format — are short; they are restated in both documents rather than kept as a third file, because a third file is exactly what this task removes. Each document then stands alone as an RFQ package for its own manufacturing scope.

A3 — How the contradictions are handled. Not by choosing for you. Where the sources disagree, the merged document states both readings and marks the item 待决, so the conflict is visible in one place instead of hidden across three:

Conflict	Sources	Treatment in the merged file
Air primary MCU	PRODUCT-PLAN says nRF54L15; P05-air-switch.md §6 says ESP32-H2; supplier guide labels its only Air MCU row 备选 and computes the battery budget against ESP32-H2's 3.6 V ceiling	§4 lists both with their evidence and marks the primary choice 待决 before D0; the battery budget keeps its ESP32-H2 basis with that dependency stated
Air Hub platform	PRODUCT-PLAN and P05-air-hub.md say Linux SSD202D + 2×ESP32-C6; supplier guide and design appendix still recommend STM32G0B1CE + nRF54L15	§4 carries the Linux direction as current and the STM32 pair as the demoted comparison, matching the governing document; the design appendix content is rewritten against the Linux direction and the parts that only hold for the STM32 pair are marked
Air Hub power target	P05-air-hub.md and design appendix say ≤15 mA / ≤30 mA; plan and platform options say 125–210 mA for Linux	§2 carries the Linux figure as the current target and records the ≤15/≤30 pair as superseded, so the acceptance table stops holding suppliers to an unreachable number
sub-GHz chip	Only Air has one (CC1312R); Air Hub names no part	§4 of both files states the gap explicitly and points at the open item
LoRa	No candidate anywhere; CC1312R cannot provide LoRa because it is Semtech CSS	§8 records this as an unclosed gap, not as an assumed capability

A4 — Reference rewrite. All 29 inbound references updated, most to anchors (P05-air.md#4-平台与选型). product/switch/index.md and P05-switch.md rebuilt around two Air files plus the three Key files. Historical docs/task/ and docs/plan/ records keep the old names.

A5 — Recorded deviation. docs/decisions/2026-09-13-air-docs-single-file.md records that P05 Air and Air Hub drop the Level 1/Level 2 split, why, and a sunset date at which the choice is reviewed against the rest of the package.

B. Alternative: two documents, contradictions resolved during the merge

Same structure, but the merge picks one reading per conflict. Faster to read afterwards, but it puts a product decision — which MCU Air is quoted against — into a documentation task. Not recommended without your call on each of the five.

C. Rejected: keep the supplier guide as a third file

It is the single largest source of drift: 235 lines restating figures that also live in the Level 1 and Level 2 files. Keeping it means the consolidation does not solve the problem it was asked to solve.

Scope

• New: P05-air.md, P05-air-hub.md (rewritten), docs/decisions/2026-09-13-air-docs-single-file.md, one research report moved.
• Deleted: P05-air-switch.md, P05-air-switch-design.md, P05-air-switch-platform-options.md, P05-air-hub-design.md, P05-air-hub-platform-options.md, P05-air-supplier-guide.md.
• Updated: 29 referring documents, product/switch/index.md, P05-switch.md, product/index.md (the template section must note the exception).
• No specification value changes except the three superseded/duplicated figures named in A3, each of which is recorded rather than silently dropped.

Verification

1. Every requirement ID in the old files (AIR-nn, GW-nn, SYS-nn, AIR-O-nn, V-nn) appears in the merged files → verify: ID-by-ID diff, no ID lost.
2. No inbound link points at a deleted file → verify: grep for each old filename returns hits only in docs/ history.
3. The five contradictions are each visible in exactly one place and marked 待决 → verify: read §4 and §8 of both files.
4. bun run docs:build and git diff --check → verify: both pass, no dead links.

Open Items

• Whether the ESP32-H2 evaluation moves to research/ or stays inline.
• The sunset date for the Level 1/2 deviation.
• Whether Key should follow the same consolidation later, which would make the line three documents instead of six.

Annotations

• 2026-09-14 01:30 owner: approved together with the documentation-standard plan. Option A implemented; the ESP32-H2 evaluation went to switch/air/evaluations/ (the package slot) instead of research/; the sunset for the Level 1/2 deviation is 2026-12-31; Key keeps its three files. Completed 2026-09-14 03:20.