[akol1]

What this changes

Step 6 of 6, stacked on steps 1-5 (qwen27/pair-seam, qwen27/rank-slice, qwen27/pair-lifecycle, qwen27/pair-tests, qwen27/pair-tools) and main (5897e0bc). This is the last step; nothing stacks on it.

The docs now describe what the code does, with nothing projected:

• docs/recipes/qwen3.8-27b.md gains Two Macs over Thunderbolt: the same ~/models/qwen3.8-27b checkpoint on both Macs, one speed-up settings file per rank, rank 1 started first and rank 0 within five minutes, --parallel 1, send to rank 0. It states the split exactly (12 of 24 attention heads, 2 of 4 KV heads, half the linear attention's heads and value channels, 8,704 of the 17,408-wide MLP, 124,160 of the lm_head's 248,320 rows), says there is no cross-rank partial sum and no tie policy, lists the refusals, and names the pair-vs-single gate.
• RUNBOOK.md gains the two-Mac run: rank 1 first, the harness's /health wait, pair_accept.py run, pair_supervise.sh for restarts, and what a link failure leaves behind — the request in flight fails, the pair stays down until both ranks run again.
• docs/known-issues.md records the pair's limits where a user will look for them: one greedy stream, no drafter, no prompt cache, no learning, refusals for what needs one Mac's whole state, and a pair_gather that joins bf16 halves with no arithmetic between them, so pair logits are byte-identical to one Mac's on the recorded fixtures.

No issue closes with this step; it documents the series for #1236 and #808.

Receipt

• Environment, with the TensorFold commit, MLX or PyTorch version, machine and GPU, checkpoint and revision: 5897e0bc plus steps 1-6 (0b79f9c9, 7d57101a, 277929ca, 0c2df0ec, 0b4f1f4e, 0c500376); no MLX or PyTorch; documentation only, so no GPU is involved in producing this diff. The commands it documents are the ones in step 5 and step 4.
• Exactness, from tools/bench_concurrent.py --alone --serial or token_sha against "draft": false: n/a, this commit changes no code; the receipts it refers to are step 4's four --stage 3 runs, all exit 0, with pair logits byte-equal to one Mac's and first_difference null.
• Decode speed before and after, from tools/bench_openai.py: n/a, documentation only; the recipes do not quote a pair speed, because this series has no two-Mac run to measure.
• Prompt speed before and after: n/a, same reason; the recipe says the pair leaves prompt processing on one Mac's reduction and quotes no number.
• Tests run, with pass, fail and skip counts: zig build test: 565/565 steps, exit 0. zig build test-kernel-contract: 18/18 steps, 120/120 tests. zig build dev-tools: 214/214 steps. zig fmt --check build.zig zig: clean. Lean rule: 428 problems on both 5897e0bc and this tree, 0 new (tools/zig/lean_new.py, exit 0). The series head's fresh-cache suite: 565/565 steps, 8,157 passed, 47 skipped, 0 failed of 8,204.
• Not run, and why: the two-Mac recipe itself, because this room has one Mac; it is written from the code and the loopback receipts, and the commands in it are what step 5's scripts and step 4's gate run. CUDA, HIP/RDNA, M1-M3, M5 and Windows are not here. No GLM two-Mac receipt is claimed anywhere in these docs, because GLM's transport is unchanged in this series.

Checklist

• Every token still goes through the lane rounds. No serial path, and nothing that needs drafts off. — the document says the pair serves one greedy stream and refuses the flags that would need more.
• Drafted output equals "draft": false, a resumed prompt equals a fresh one, and concurrent equals solo. — the docs state that a pair drafts nothing, caches nothing and serves one stream, so those comparisons are refused rather than documented as passing.
• No precision traded for speed. If the bits change, the description says which sums change and why. — the docs say the split moves bf16 rows and adds in fp32 with no cross-rank partial sum, and name the exactness gate.
• A new or changed GPU kernel is registered with the kernel contract (docs/kernel-contract.md); each backend's SUMMARY line is in the receipt. — none in this commit; the pair's SUMMARY is in step 1 and the docs point at the gate.
• Prompt processing is no slower than the last release. — n/a, documentation only, and the docs quote no prompt-speed claim for a pair.
• The description says which platforms I ran, Metal M1 to M5 and CUDA, and which I could not. — the docs name the Macs as Apple-silicon Metal machines, the test receipts are one M4 Pro (applegpu_g16), and they say two Macs were not available.
• New tests fail before the change, pass after it, and skip cleanly without their dependency. — no tests in this commit; the suite and gates above are unchanged from step 5.
• Comments and docstrings are one line. No measurements or history in the source. — the diff is prose, and the lean check reports 428 problems on the base too, 0 new.
• No personal data, machine names, internal hosts or local paths. No AI attribution lines. — the recipe uses ~/models/qwen3.8-27b, 127.0.0.1 and chart names, not a user path or hostname.

[ashhart]

• known-issues.md and the recipe present the chat-256 divergence as accepted behaviour, which amounts to a new tie policy. Please drop that once the seam is exact (see core: add the row-split pair seam and split simd_qmm over K #1432).
• RUNBOOK says that when rank 0 stops, rank 1 "keeps running until you end it". The code (qwen27_link.watch) exits rank 1 within about 3 s. The code matches the requirement, so please fix the text.

[akol1]

Both text bugs are fixed on 0c500376:

• docs/known-issues.md and the recipe no longer present the chat-256 divergence as accepted. They say the pair's logits are byte-identical to one Mac's on the recorded fixtures, and that no cross-rank partial sum exists, so there is no tie policy.
• RUNBOOK.md now says rank 1 exits by itself within about three seconds when rank 0 stops, matching qwen27_link.watch, and keeps the "restart both after a link failure" instruction.

[ashhart]

Thanks @akol1: the chat-256 divergence is gone from the docs, and the RUNBOOK's rank-1 exit now matches qwen27_link.watch. Three corrections so the docs describe what the code does:

1. docs/recipes/qwen3.8-27b.md:106 says the pair takes the argmax of the 248,320 logits gathered from both halves. In the code each rank takes the argmax of its own half and pair_pick chooses between the two. No logits are gathered, and until core: add the row-split pair seam and split simd_qmm over K #1432's third point lands, a NaN or Inf is handled differently from one Mac. Please describe that.
2. :113 and docs/known-issues.md:42-43 say a sampled or grammar request fails. Today a sampled request gets a greedy first token and fails on the second. Please match the text to the refusal qwen27: serve the 27B pair, refuse what a pair cannot keep, and die with the peer #1434 adds, and list --vision with the refused flags in the RUNBOOK and known issues.
3. The recipe names only TensorFold/Qwen3.8-27B-MLX-4bit, but nothing refuses other widths on a pair yet. Once qwen27: rank-slice the 27B family and gather the whole embedding table #1433 settles which formats a pair takes, please say so here.

This also needs #1432's rebase.