Model card: AX Engine primary, mlx-vlm alternative only

README.md

@@ -28,8 +28,11 @@ checkpoint was used only as a comparison reference; these are not repackaged
 Sahil weights.
 
 **Primary inference engine:** [AX Engine](https://github.com/defai-digital/ax-engine)
-(`model_family=unlimited_ocr`). Use it for Apple Silicon serving and native
-MXFP8 / dual-vision loads. `mlx-vlm` remains a compatibility path.
+(`model_family=unlimited_ocr`) — use this for Apple Silicon serving and native
+MXFP8 / dual-vision loads.
+
+**Alternative runtime:** `mlx-vlm` (weight-compatible; not the recommended
+production path for AutomatosX packs).
 
 **Hybrid precision (name is shorthand):** MXFP8 (group size 32) on eligible
 language linears, **affine INT8** on the LM head, **BF16** on the vision
@@ -42,7 +45,7 @@ active MoE capacity; the marketing name refers to the upstream 3B MoE family.
 - **Hub pin:** `revision="v0.2.0"` or the commit SHA after publish
 - **Repo:** [`AutomatosX/AX-Unlimited-OCR-3B-MoE-MLX-MXFP8`](https://huggingface.co/AutomatosX/AX-Unlimited-OCR-3B-MoE-MLX-MXFP8)
 - **Runtime:** [AX Engine](https://github.com/defai-digital/ax-engine)
-- **Release notes:** Sensitivity-guided MXFP8 with calibrated affine INT8 LM head; primary inference via AX Engine
+- **Release notes:** Sensitivity-guided MXFP8 with calibrated affine INT8 LM head; primary inference via AX Engine; mlx-vlm alternative only
 
 Immutable upstream source revision: `ee63731b6461c8afcdcc7b15352e7d2ffecc2ead`.  
 Reference checkpoint revision: `55b8031a6c867de675279d9604e38cc94b9882a4`.
@@ -87,11 +90,9 @@ CJK, and 3 with tables), digest
 - Small local set; some samples are synthetic. Do not treat mean CER as field accuracy.
 - The community reference may use a different `model_type` / load path; it is a
   throughput and packaging baseline, not an identical-recipe peer.
-- AX Engine is the primary runtime for AutomatosX packs. Document toolkits such
-  as AX-OCR may still call mlx-vlm for PDF/profile helpers; pin the same Hub
-  revision when comparing stacks.
-- Generation profiles in AX-OCR live in `profiles.py`; raw mlx-vlm loads use
-  library defaults unless you pass matching decode settings.
+- Prefer **AX Engine** for inference. `mlx-vlm` is an alternative load path only.
+- Document helpers (e.g. AX-OCR PDF/profiles) may still call mlx-vlm under the
+  hood; pin the same Hub revision when comparing stacks.
 
 ### Weight integrity
 
@@ -133,14 +134,18 @@ Full per-sample evidence, sensitivity results, precision rules, PRD, ADR, and
 technical specification are included under `release/`, `quantization/`, and
 `docs/`.
 
-## Usage (primary: AX Engine)
+## Usage
+
+Requires **Apple Silicon**.
 
-Requires **Apple Silicon**. Primary runtime:
-[AX Engine](https://github.com/defai-digital/ax-engine) (native `unlimited_ocr`).
+### Primary — AX Engine
 
-Tested conversion/validation stack for this weight release: mlx-vlm `0.6.6`, mlx `0.32.0`, python `3.14.6`.
+**Use [AX Engine](https://github.com/defai-digital/ax-engine) as the primary inference engine** for this
+pack (native `unlimited_ocr`: dual vision + SWA MoE + MXFP8 + R-SWA).
 
-### Install AX Engine
+Quantization/release measurements for these weights used: mlx-vlm `0.6.6`, mlx `0.32.0`, python `3.14.6`.
+
+#### Install
 
 ```bash
 # Homebrew (recommended on macOS)
@@ -152,7 +157,7 @@ ax-engine doctor
 python3 -m pip install --upgrade "ax-engine[download]>=6.11.0,<7"
 ```
 
-### Download and prepare
+#### Download and prepare
 
 ```bash
 # Managed download (writes model-manifest.json when needed)
@@ -170,7 +175,7 @@ ax-engine-bench generate-manifest ./AX-Unlimited-OCR-3B-MoE-MLX-MXFP8 --validate
 This repository ships `model-manifest.json` so downloads are AX-ready without a
 manual convert step when the file is present.
 
-### Serve with AX Engine
+#### Serve
 
 ```bash
 ax-engine serve ./AX-Unlimited-OCR-3B-MoE-MLX-MXFP8 --port 31418
@@ -180,12 +185,12 @@ ax-engine serve ./AX-Unlimited-OCR-3B-MoE-MLX-MXFP8 --port 31418
 
 OpenAI-compatible routes are exposed on the local server. See the
 [AX Engine docs](https://github.com/defai-digital/ax-engine/blob/main/docs/GETTING-STARTED.md) for
-install, doctor checks, and API details. Unlimited-OCR image paths use the
-native dual-vision prefill in AX Engine (`model_family=unlimited_ocr`).
+install, doctor checks, and API details.
 
-## Compatibility paths
+### Alternative — mlx-vlm
 
-### mlx-vlm (weight-compatible)
+`mlx-vlm` can load these weights as a **secondary / alternative** path. Prefer
+AX Engine for AutomatosX deployments.
 
 ```bash
 pip install 'mlx-vlm>=0.6.4'
@@ -197,7 +202,10 @@ python -m mlx_vlm.generate \
   --max-tokens 4096
 ```
 
-### AX-OCR toolkit (deskew, PDF, profiles)
+### Optional — AX-OCR document toolkit
+
+AX-OCR adds deskew, PDF, and generation profiles on top of the same Hub weights.
+It is a toolkit, not a replacement for AX Engine as the primary runtime.
 
 ```bash
 pip install 'ax-ocr[mlx]'