Refine model card flow and CTA assets

README.md

@@ -16,37 +16,29 @@ tags:
 ---
 
 <p align="center">
-  <img src="./assets/thestage-edge-models-header.png" width="100%" alt="TheStageAI Edge Models — the right model at every memory budget">
+  <img src="./assets/thestage-edge-models-header.png" width="100%" alt="TheStageAI Edge Models: the right model at every memory budget">
 </p>
 
-<h1 align="center">Qwen3.5 2B — TheStageAI GGUF</h1>
+<h1 align="center">Qwen3.5 2B</h1>
 
 <p align="center">
-  Four deployment tiers for local inference with llama.cpp · 738 MB–2.01 GB
+  Four GGUF checkpoints for llama.cpp, from 738 MB to 2.01 GB.
   <br>
-  <strong>Start with M: 1.07 GB and ≈100% of BF16 instruction-strict IFEval.</strong>
+  <strong>Start with M: 1.07 GB and ≈100% of the BF16 instruction-strict IFEval score.</strong>
 </p>
 
-<div style="display: flex; gap: 8px; justify-content: center; align-items: center; margin: 16px 0;">
-  <a href="https://github.com/TheStageAI/edge-lm"><img src="./assets/cta-edge-lm.svg" width="104" height="36" alt="Explore edge-lm on GitHub"></a>
-  <a href="https://docs.thestage.ai/"><img src="./assets/cta-docs.svg" width="83" height="36" alt="Read TheStageAI documentation"></a>
-  <a href="https://app.thestage.ai/"><img src="./assets/cta-platform.svg" width="110" height="36" alt="Open TheStageAI Platform"></a>
-</div>
-
-<p align="center"><strong>Qwen 3.5 family:</strong> <a href="https://huggingface.co/TheStageAI/Qwen3.5-0.8B-GGUF">0.8B</a> &nbsp;·&nbsp; <strong><a href="https://huggingface.co/TheStageAI/Qwen3.5-2B-GGUF">2B</a></strong> &nbsp;·&nbsp; <a href="https://huggingface.co/TheStageAI/Qwen3.5-4B-GGUF">4B</a> &nbsp;·&nbsp; <a href="https://huggingface.co/TheStageAI/Qwen3.5-9B-GGUF">9B</a></p>
-
-## Start here
+## Choose a checkpoint
 
 | Tier | Size | Best for | File |
 | --- | ---: | --- | --- |
 | XS | 738 MB | Minimum footprint | [Download](./Qwen3.5-2B-XS-TS-Q3_K_S.gguf) |
 | S | 967 MB | Compact | [Download](./Qwen3.5-2B-S-TS-Q4_K_S.gguf) |
-| **M** | **1.07 GB** | **Recommended · Balanced** | [Download](./Qwen3.5-2B-M-TS-Q4_K_M.gguf) |
+| **M** | **1.07 GB** | **Recommended** | [Download](./Qwen3.5-2B-M-TS-Q4_K_M.gguf) |
 | L | 2.01 GB | High-precision Q8 | [Download](./Qwen3.5-2B-L-TS-Q8_0.gguf) |
 
-Exact byte counts, SHA-256 hashes, and tensor metadata: [`release-manifest.json`](./release-manifest.json).
+**Other Qwen 3.5 sizes:** <a href="https://huggingface.co/TheStageAI/Qwen3.5-0.8B-GGUF">0.8B</a> &nbsp;·&nbsp; <a href="https://huggingface.co/TheStageAI/Qwen3.5-4B-GGUF">4B</a> &nbsp;·&nbsp; <a href="https://huggingface.co/TheStageAI/Qwen3.5-9B-GGUF">9B</a>
 
-## Run with llama.cpp
+## Quickstart
 
 ```bash
 llama-cli \
@@ -54,11 +46,17 @@ llama-cli \
   --hf-file Qwen3.5-2B-M-TS-Q4_K_M.gguf
 ```
 
-## Why M is the default
+<div style="display: flex; gap: 8px; justify-content: center; align-items: center; margin: 12px 0 24px;">
+  <a href="https://github.com/TheStageAI/edge-lm"><img src="./assets/cta-edge-lm.svg" width="104" height="36" alt="Explore edge-lm on GitHub"></a>
+  <a href="https://docs.thestage.ai/"><img src="./assets/cta-docs.svg" width="83" height="36" alt="Read TheStageAI documentation"></a>
+  <a href="https://app.thestage.ai/"><img src="./assets/cta-platform.svg" width="110" height="36" alt="Open TheStageAI Platform"></a>
+</div>
+
+## Why we recommend M
 
-At 1.07 GB, M matches the BF16 instruction-strict IFEval score within evaluation variation. It uses 47% less disk than L, making it the default for this release.
+At 1.07 GB, M matches the BF16 instruction-strict IFEval score within evaluation variation. It uses 47% less disk than L.
 
-| Tier | IFEval strict — prompt / instruction (%) | MMLU-Pro (%) |
+| Tier | IFEval P / I (%) | MMLU-Pro (%) |
 | --- | ---: | ---: |
 | BF16 reference | 65.43 / 74.70 | — |
 | XS | 52.68 / 64.15 | — |
@@ -66,9 +64,9 @@ At 1.07 GB, M matches the BF16 instruction-strict IFEval score within evaluation
 | **M** | 66.54 / 75.54 | — |
 | L | 65.80 / 74.94 | — |
 
-IFEval measures deterministic non-thinking instruction following; MMLU-Pro measures sampled long-form reasoning. Only complete scores are shown; `—` means not reported.
+P / I means prompt-strict / instruction-strict. IFEval uses deterministic non-thinking decoding; MMLU-Pro uses sampled long-form reasoning. Only complete model-level scores are reported. A dash means not reported.
 
-> **XS and reasoning:** use S, M, or L for long-form reasoning. Run Qwen XS with `--reasoning off`.
+> **Reasoning:** XS is intended for non-thinking use. Run it with `--reasoning off`. Choose S, M, or L for long-form reasoning.
 
 <details>
 <summary><b>Evaluation protocol</b></summary>
@@ -77,40 +75,36 @@ IFEval measures deterministic non-thinking instruction following; MMLU-Pro measu
 - **MMLU-Pro:** 12,032 questions, native chat template, `enable_thinking=true`, temperature 1, top-p 0.95, 32,768-token output limit.
 - The headline BF16 comparison uses instruction-strict IFEval; the raw scores are shown in the table.
 
-In matched long-thinking diagnostics, XS produced longer trajectories and reached the 32,768-token output limit more often than S. For Qwen 0.8B and 2B, a complete comparable MMLU-Pro matrix was not available at release time; incomplete subject runs are not promoted to model-level scores.
+In matched long-form reasoning diagnostics, XS produced longer trajectories and reached the 32,768-token output limit more often than S. For Qwen 0.8B and 2B, a complete comparable MMLU-Pro matrix was not available at release time. The table omits incomplete subject runs.
 
 </details>
 
-## From source weights to deployment tiers
-
-All four tiers are produced by the same production PTQ pipeline; only the precision map changes. The process moves from **native code fitting**, through **sequential reconstruction** and **budget-aware scheduling**, to a final **model-wide alignment** pass.
+## How the checkpoints are built
 
-### 1. Fit native discrete codes
+All four checkpoints use the same production PTQ pipeline. The precision map is the only tier-specific part.
 
-Calibration activations define a curvature objective weighted by true Fisher information for each quantized projection. [NeUQI](https://arxiv.org/abs/2505.17595) initializes every affine group's scale and minimum on that objective, so sensitive weight directions influence the grid more strongly.
+### 1. Fit native GGUF codes
 
-With the grid fixed, a guarded cyclic coordinate-descent solver inspired by [QuantEase](https://arxiv.org/abs/2309.01885) searches the integer codes. Continuous sweeps can escape a poor initial projection; projected sweeps return to a valid discrete solution. Round-to-nearest remains a non-regression baseline, and a final K-quant refinement optimizes the stored scales and minima while keeping packed codes fixed.
+Calibration activations produce a curvature objective weighted by true Fisher information for each quantized projection. We adapt the scale and minimum initialization from [NeUQI](https://arxiv.org/abs/2505.17595) to that objective, then solve integer codes on the target GGUF grid with a guarded cyclic coordinate-descent solver inspired by [QuantEase](https://arxiv.org/abs/2309.01885). A final K-quant pass tunes stored scales and minima while keeping packed codes fixed.
 
-### 2. Reconstruct the trajectory the model will run
+### 2. Reconstruct the deployed trajectory
 
-Layers are processed in execution order. Every projection is calibrated against activations from the already-quantized prefix, while a dense reference path measures accumulated drift. [Quantization Error Propagation (QEP)](https://arxiv.org/abs/2504.09629) folds that drift into the next reconstruction target, allowing later layers to compensate for errors they will actually receive at inference time.
+Layers are calibrated in execution order against activations from the already-quantized prefix. A dense reference path measures accumulated drift. [Quantization Error Propagation (QEP)](https://arxiv.org/abs/2504.09629) adds that drift to the next reconstruction target, so later layers optimize for the inputs they receive at inference time.
 
-### 3. Allocate the encoded byte budget
+### 3. Allocate the byte budget
 
-For XS and S, each quantizable group can select among native Q2_K through Q8_0 representations. The schedule optimizer trades changes in the teacher distribution against **exact encoded byte cost**, including scale and minimum metadata. Sensitive groups keep more precision; robust groups carry more compression.
+XS and S can choose Q2_K through Q8_0 for each quantizable group. The optimizer trades changes in the teacher distribution against the actual encoded byte cost, including scale and minimum metadata. [ANNA](https://docs.thestage.ai/qlip/docs/source/anna_api.html) provides constrained configuration search. [RCO](https://arxiv.org/abs/2605.00649) provides an exact-budget route ([code](https://github.com/IST-DASLab/RCO)). For this model, ANNA selected both the XS and S precision maps. M and L keep the decoder qtypes at Q4_K_M and Q8_0, respectively, and use the same reconstruction and scale-tuning stages.
 
-[ANNA](https://docs.thestage.ai/qlip/docs/source/anna_api.html) provides TheStageAI's automated constrained configuration search, while [RCO](https://arxiv.org/abs/2605.00649) supplies an exact-budget search route ([reference implementation](https://github.com/IST-DASLab/RCO)). For this model, [ANNA](https://docs.thestage.ai/qlip/docs/source/anna_api.html) selected both the XS and S precision maps. M and L use fixed Q4_K_M and Q8_0 decoder qtype choices, respectively, while retaining the same reconstruction and scale-tuning stages.
+After schedule selection, PTQ runs again from the source weights. Each layer is then calibrated with the final upstream precision choices.
 
-Once the map is selected, PTQ is rerun from the original source weights. Every layer therefore sees the final upstream precision choices rather than a collection of independently prepared bank tensors.
+### 4. Align the full model
 
-### 4. Align the complete model
+A short affine distillation pass tunes native FP16 scales and minima while qtypes, packed codes, dense weights, and tensor layouts stay fixed. The loss matches the teacher's next-token distribution without changing file size or runtime layout.
 
-A short affine distillation pass freezes qtypes, packed codes, dense weights, and tensor layouts while tuning native FP16 scales and minima. The loss matches the teacher's next-token distribution—including high-probability tokens and the remaining tail mass—without changing file size or runtime layout.
-
-Every shipping GGUF is hashed, load-tested, and evaluated on a held-out set of 3,072 sequences using next-token KL. Downstream harnesses use a deterministic HF mirror reconstructed from that exact GGUF; its source SHA-256 and evaluation IDs are recorded in [`release-manifest.json`](./release-manifest.json). The recommended tier is chosen from complete-model results, not from a local reconstruction proxy.
+We load-test the shipping GGUF and evaluate it on a held-out set of 3,072 sequences with next-token KL. [`release-manifest.json`](./release-manifest.json) records its SHA-256, downstream evaluation IDs, and tensor metadata. Final recommendations use complete-model benchmarks.
 
 <details>
-<summary><b>Technical file details</b></summary>
+<summary><b>File details</b></summary>
 
 | Tier | Hub selector | GGUF file type | Whole-file BPW |
 | --- | --- | --- | ---: |
@@ -119,20 +113,17 @@ Every shipping GGUF is hashed, load-tested, and evaluated on a held-out set of 3
 | M | `Q4_K_M` | `MOSTLY_Q4_K_M` | 4.562 |
 | L | `Q8_0` | `MOSTLY_Q8_0` | 8.558 |
 
-The Hub selector controls sidebar grouping and download discovery. For XS and S it approximates the whole-file size class; [`release-manifest.json`](./release-manifest.json) is authoritative for the internal tensor mix. M and L use fixed Q4_K_M and Q8_0 decoder qtype choices within the same production PTQ pipeline.
+The Hub selector controls sidebar grouping and download discovery. For XS and S it approximates the whole-file size class; [`release-manifest.json`](./release-manifest.json) contains the exact tensor mix. M and L keep their decoder qtypes at Q4_K_M and Q8_0 within the same production PTQ pipeline.
 
 Runtime memory also includes KV cache and buffers, which grow with context length.
 
 </details>
 
-## TheStageAI Edge Stack
+## TheStageAI deployment stack
 
-- **Portable local inference:** these GGUF files for llama.cpp-compatible runtimes.
-- **Native Apple Silicon:** [edge-lm](https://github.com/TheStageAI/edge-lm) for compressed MLX models on Macs and iPhones.
-- **Automated compression search:** [ANNA](https://docs.thestage.ai/qlip/docs/source/anna_api.html) for budget-constrained configuration discovery.
-- **Custom deployment:** the [TheStageAI Platform](https://app.thestage.ai/) and [documentation](https://docs.thestage.ai/) for compression, compilation, and serving workflows.
+These GGUF files target llama.cpp-compatible runtimes. [edge-lm](https://github.com/TheStageAI/edge-lm) runs compressed MLX models on Macs and iPhones. [ANNA](https://docs.thestage.ai/qlip/docs/source/anna_api.html) searches compression configurations under size or compute constraints. The [TheStageAI Platform](https://app.thestage.ai/) and [documentation](https://docs.thestage.ai/) cover compression, compilation, and serving workflows.
 
-**Have a device, latency, or memory target? [Talk to our team →](https://app.thestage.ai/contact)**
+For a specific device, latency target, or memory budget, [talk to our team](https://app.thestage.ai/contact).
 
 ## Reproducibility
 
@@ -143,12 +134,12 @@ Runtime memory also includes KV cache and buffers, which grow with context lengt
 
 ## Citation
 
-If you use this checkpoint, please cite the upstream base model and this release:
+If you use this checkpoint, cite this release and follow the upstream model's citation guidance:
 
 ```bibtex
 @misc{thestageai2026qwen3p52bgguf,
   author       = {{TheStageAI}},
-  title        = {Qwen3.5 2B — TheStageAI GGUF Release},
+  title        = {Qwen3.5 2B: TheStageAI GGUF Release},
   year         = {2026},
   month        = {jul},
   howpublished = {Hugging Face model release},
@@ -157,13 +148,17 @@ If you use this checkpoint, please cite the upstream base model and this release
 }
 ```
 
-### Methods and tools
+<details>
+<summary><b>References</b></summary>
+
+- [ANNA](https://docs.thestage.ai/qlip/docs/source/anna_api.html), TheStageAI's constrained compression configuration search.
+- [RCO: Model Compression with Exact Budget Constraints via Riemannian Manifolds](https://arxiv.org/abs/2605.00649) ([code](https://github.com/IST-DASLab/RCO)).
+- [NeUQI: Near-Optimal Uniform Quantization Parameter Initialization for Low-Bit LLMs](https://arxiv.org/abs/2505.17595).
+- [QuantEase: Optimization-based Quantization for Language Models](https://arxiv.org/abs/2309.01885).
+- [Quantization Error Propagation: Revisiting Layer-Wise Post-Training Quantization](https://arxiv.org/abs/2504.09629).
 
-- **Schedule selection:** [ANNA](https://docs.thestage.ai/qlip/docs/source/anna_api.html), TheStageAI's automated constrained compression configuration search.
-- **Exact-budget optimization:** [RCO: Model Compression with Exact Budget Constraints via Riemannian Manifolds](https://arxiv.org/abs/2605.00649) ([code](https://github.com/IST-DASLab/RCO)).
-- **Discrete PTQ:** [NeUQI: Near-Optimal Uniform Quantization Parameter Initialization for Low-Bit LLMs](https://arxiv.org/abs/2505.17595) and [QuantEase: Optimization-based Quantization for Language Models](https://arxiv.org/abs/2309.01885).
-- **Sequential reconstruction:** [Quantization Error Propagation: Revisiting Layer-Wise Post-Training Quantization](https://arxiv.org/abs/2504.09629).
+</details>
 
 ## License
 
-The model weights are released under the upstream model's **Apache-2.0** license. llama.cpp and other runtime software retain their own licenses.
+The checkpoint weights use the upstream model's **Apache-2.0** license. llama.cpp and other runtime software keep their own licenses.

release-manifest.json

@@ -36,7 +36,7 @@
   },
   "display_name": "Qwen3.5 2B",
   "family": "Qwen 3.5",
-  "generated_at": "2026-07-21T12:22:14.106699+00:00",
+  "generated_at": "2026-07-21T13:33:50.063649+00:00",
   "license": "apache-2.0",
   "model_key": "qwen3p5_2b",
   "reasoning_policy": {