docs: Tier 2 polish — variant matrix + quant trade-off

README.md

@@ -2,18 +2,16 @@
 base_model: google/gemma-4-31B
 library_name: mlx
 tags:
-- rotorquant
-- kv-cache-quantization
-- gemma
-- gemma4
-- multimodal
-- quantized
-- mlx
-- 2bit
+  - rotorquant
+  - kv-cache-quantization
+  - gemma
+  - gemma4
+  - multimodal
+  - quantized
+  - mlx
+  - 2bit
 license: apache-2.0
 pipeline_tag: image-text-to-text
-language:
-- en
 ---
 
 # Gemma 4 31B - RotorQuant MLX 2-bit
@@ -105,3 +103,41 @@ This model requires approximately 9 GB of unified memory. Recommended hardware:
 - [majentik/gemma-4-31B-TurboQuant-MLX-2bit](https://huggingface.co/majentik/gemma-4-31B-TurboQuant-MLX-2bit) -- TurboQuant MLX 2-bit variant
 - [RotorQuant GitHub](https://github.com/scrya-com/rotorquant)
 - [MLX Framework](https://github.com/ml-explore/mlx)
+
+## Quant trade-off (MLX lane)
+
+| Bits | Approx size | Use case | Recommendation |
+|---|---|---|---|
+| **2-bit** | ~8.1 GB | Aggressive quantization | **Very low-RAM Macs** |
+| 3-bit | ~11 GB | Lossy but small | Low-RAM Macs |
+| 4-bit | ~13 GB | Balanced default | Recommended for most Macs |
+| 5-bit | ~16 GB | Higher fidelity | Quality-sensitive |
+| 6-bit | ~19 GB | Approaching FP16 quality | High-fidelity |
+| 8-bit | ~24 GB | Near-lossless reference | Fidelity-critical work |
+
+(Current variant — **2bit** — is bolded.)
+
+## Variants in this family
+
+(Showing 18 sibling variants under `majentik/gemma4-31b-*`. The current variant — `RotorQuant-MLX-2bit` — is **bolded**.)
+
+| Variant | Runtime | Approx size | Use case |
+|---|---|---|---|
+| [RotorQuant](https://huggingface.co/majentik/gemma4-31b-rotorquant) | runtime modifier | n/a | KV-cache root (weight-agnostic) |
+| [RotorQuant-AWQ-4bit](https://huggingface.co/majentik/gemma4-31b-rotorquant-awq-4bit) | transformers | ~19 GB | GPU 4-bit (AutoAWQ) |
+| [RotorQuant-AWQ-8bit](https://huggingface.co/majentik/gemma4-31b-rotorquant-awq-8bit) | transformers | ~34 GB | GPU 8-bit (AutoAWQ) |
+| [RotorQuant-GGUF-IQ4_XS](https://huggingface.co/majentik/gemma4-31b-rotorquant-gguf-IQ4_XS) | llama.cpp | ~27 GB | Lossy 4-bit, low-RAM CPU/edge |
+| [RotorQuant-GGUF-Q2_K](https://huggingface.co/majentik/gemma4-31b-rotorquant-gguf-Q2_K) | llama.cpp | ~19 GB | Lossy, low-RAM CPU/edge |
+| [RotorQuant-GGUF-Q3_K_M](https://huggingface.co/majentik/gemma4-31b-rotorquant-gguf-Q3_K_M) | llama.cpp | ~24 GB | Smaller 3-bit, CPU-friendly |
+| [RotorQuant-GGUF-Q4_K_M](https://huggingface.co/majentik/gemma4-31b-rotorquant-gguf-Q4_K_M) | llama.cpp | ~34 GB | Balanced default |
+| [RotorQuant-GGUF-Q5_K_M](https://huggingface.co/majentik/gemma4-31b-rotorquant-gguf-Q5_K_M) | llama.cpp | ~41 GB | Higher fidelity, more RAM |
+| [RotorQuant-GGUF-Q8_0](https://huggingface.co/majentik/gemma4-31b-rotorquant-gguf-Q8_0) | llama.cpp | ~65 GB | Near-lossless reference |
+| **RotorQuant-MLX-2bit** | mlx-lm | ~9.9 GB | Apple Silicon, smallest |
+| [RotorQuant-MLX-4bit](https://huggingface.co/majentik/gemma4-31b-rotorquant-mlx-4bit) | mlx-lm | ~19 GB | Apple Silicon balanced |
+| [RotorQuant-MLX-8bit](https://huggingface.co/majentik/gemma4-31b-rotorquant-mlx-8bit) | mlx-lm | ~37 GB | Apple Silicon reference |
+| [TurboQuant](https://huggingface.co/majentik/gemma4-31b-turboquant) | runtime modifier | n/a | KV-cache root (weight-agnostic) |
+| [TurboQuant-AWQ-4bit](https://huggingface.co/majentik/gemma4-31b-turboquant-awq-4bit) | transformers | ~19 GB | GPU 4-bit (AutoAWQ) |
+| [TurboQuant-AWQ-8bit](https://huggingface.co/majentik/gemma4-31b-turboquant-awq-8bit) | transformers | ~34 GB | GPU 8-bit (AutoAWQ) |
+| [TurboQuant-MLX-2bit](https://huggingface.co/majentik/gemma4-31b-turboquant-mlx-2bit) | mlx-lm | ~9.9 GB | Apple Silicon, smallest |
+| [TurboQuant-MLX-4bit](https://huggingface.co/majentik/gemma4-31b-turboquant-mlx-4bit) | mlx-lm | ~19 GB | Apple Silicon balanced |
+| [TurboQuant-MLX-8bit](https://huggingface.co/majentik/gemma4-31b-turboquant-mlx-8bit) | mlx-lm | ~37 GB | Apple Silicon reference |