head-quant docs: per-block-32 absmax ship shape (per-channel = beta delegate bug; naming note)

README.md

@@ -27,17 +27,24 @@ engine** — the first non-Qwen architecture on that fast path, with zero custom
 
 | Surface | Bundle | Prefill | Decode |
 |---|---|---:|---:|
-| **M4 Max**, release `llm-benchmark` | `gpu-pipelined/lfm2_5_1_2b_instruct_decode_int8lin/` (1.5 GB) | 253.3 tok/s | **253.3 tok/s** |
-| **iPhone 17 Pro**, one-shot runner | same bundle | 39.2–39.4 | **38.0–39.6 tok/s** |
-| iPhone 17 Pro, chat app (CoreAIChat LFM mode, 200-tok turn) | same bundle | 30.7 | **35.8 tok/s** |
-
-- ~39 tok/s on iPhone ≈ **~87% of the naive bandwidth ceiling** (~60 GB/s ÷ ~1.4 GB/token) —
-  effectively memory-bandwidth saturated. Cold GPU specialization 6.8 s, warm load 1.6 s; no
-  AOT compile needed.
+| **M4 Max**, release `llm-benchmark` | ★★★ `gpu-pipelined/lfm2_5_1_2b_instruct_decode_int8hu_block32_sym/` (1.6 GB) | 277.8 tok/s | **276.5 tok/s** |
+| **iPhone 17 Pro**, one-shot runner | ★★★ same bundle | 44.2–46.6 | **44.1–46.6 tok/s** |
+| M4 Max, release `llm-benchmark` | ★★ `gpu-pipelined/lfm2_5_1_2b_instruct_decode_int8lin/` (1.5 GB) | 253.3 tok/s | **253.3 tok/s** |
+| iPhone 17 Pro, one-shot runner | ★★ same bundle | 39.2–39.4 | **38.0–39.6 tok/s** |
+| iPhone 17 Pro, chat app (CoreAIChat LFM mode, 200-tok turn) | int8lin bundle | 30.7 | **35.8 tok/s** |
+
+- **★★★ = the ship config** (`int8hu_block32_sym`): int8lin + the tied lm_head untied and
+  quantized **absmax per-block-32 int8** (`symmetric`, no clipping — clipping corrupts
+  big-vocab heads). +9% on M4 Max, **+15–20% on iPhone** (44.1–46.6 ≈ ~94–98% of the naive
+  bandwidth ceiling, ~60 GB/s ÷ ~1.27 GB/token); warm engine load 0.3 s. Greedy rollouts are
+  token-identical to the int8lin bundle on both verification prompts; oracle gate 16/16 +
+  decode step, device numerics 24/24 ≡ Mac-GPU on all 3 runs.
+- ★★ int8lin: the fp16-head variant (what CoreAIChat currently downloads); ~87% of its
+  ceiling on iPhone. Cold GPU specialization 6.8 s, warm load 1.6 s; no AOT compile needed.
 - iPhone greedy sequences are **24/24 token-identical to the M4 Max GPU** on both fixed
-  verification prompts.
-- For scale: our Qwen3.5-0.8B on the same engine does 204 tok/s on M4 Max — this 1.2B does
-  253.
+  verification prompts (both bundles).
+- For scale: our Qwen3.5-0.8B on the same engine does 210 tok/s on M4 Max — this 1.2B does
+  276.5.
 
 ## What the bundle is
 
@@ -46,7 +53,11 @@ One full **LanguageBundle** (`.aimodel` + `tokenizer/` + `metadata.json`): decod
 `coreai-pipelined`: async non-blocking encode, on-GPU argmax sampling, on-device KV growth).
 Weights are **int8 linear per-block-32** (scale-multiply dequant — no LUT; k-means LUT
 gathers measure slower on this GPU delegate) with the embedding, depthwise convs, norms,
-lm_head, and the four attention projections kept high-precision. The attention projections
+and the four attention projections kept high-precision; in the ★★★ bundle the lm_head is
+untied and quantized absmax per-block-32 int8 too (in the ★★ bundle it stays fp16/tied).
+Do NOT re-quantize the head per-channel: per-channel (axis-0) int8 weights are broken on
+the current beta GPU delegate (garbage logits — delegate lowering bug, documented in the
+zoo knowledge base). The attention projections
 are fp32 on purpose: under a dynamic-shape graph the delegate's fp16 attention-prologue
 matmuls lose ~1.3% relative accuracy, which LFM2.5's large q/k-norm gains amplify into wrong
 logits — fp32 there restores layer-level exactness (+126 MB). Full write-up:
@@ -64,7 +75,7 @@ git -C coreai-models apply ../coreai-model-zoo/apps/coreai-shared-product.patch
 # download this bundle into coreai-models/exports/, then:
 cd coreai-models && swift build -c release
 COREAI_CHUNK_THRESHOLD=1 ./.build/release/llm-benchmark \
-    --model exports/lfm2_5_1_2b_instruct_decode_int8lin -p 128 -g 256 -n 3
+    --model exports/lfm2_5_1_2b_instruct_decode_int8hu_block32_sym -p 128 -g 256 -n 3
 ```
 
 Run contract (each of these matters):