Skip to content

Qwen3.8-Flash-Next on any consumer hardware: one-click install for Windows / Linux. Strata inference engine, OpenAI/Anthropic API on localhost, optional image input.

C++

docs: models, NVFP4, Gyro, Qwen3.6 and troubleshooting for 0.2.0

Niko1221afe92c17275b
diff --git a/docs/GYRO.md b/docs/GYRO.md
index 0a513905a..e8238a5c1 100644
--- a/docs/GYRO.md
+++ b/docs/GYRO.md
@@ -39,7 +39,19 @@ APR port, and the released 0.1.45 stops at v4. A ready-made engine that is older
**Supported:** NVIDIA (CUDA, Linux and Windows) and AMD (HIP, experimental: the authors validated gfx1151; we ran
gfx1201 with identical output to rc2). **Not supported:** Intel Arc (SYCL) and Apple Metal: the engines there have no
-trellis kernels; the Metal engine refuses the file at load with the reason. Images are off for these files.
+trellis kernels; the Metal engine refuses the file at load with the reason.
+
+**Pictures.** Gyro reads pictures with the original model's picture reader file (the same one every Qwen3.8-Flash-Next
+model uses; setup downloads it with the model). The reader opens only the vocabulary and the header of the Gyro file, so
+the trellis tensors do not matter to it. Pictures are on by default, with the CPU reader under 24 GB of graphics memory and
+the card's reader from 24 GB. This needs engine 0.1.45.1 or newer, like the Gyro files themselves.
+
+**RTX 50 cards (sm_120).** Gyro gives correct output on them with engine 0.1.45.3. The fused gate/up SwiGLU kernel, which
+is the default on compute capability 12.0 cards, handles only rows of 80 dot products; Gyro's trellis rows have 160, and
+before the fix they went through it anyway. Gyro-S then answered with loops, garbage or nothing: on an RTX PRO 5000, 0 of
+8 test questions were answered right before the fix and 8 of 8 after it (greedy and with the app's sampling). Now those
+rows use the full-warp kernel, and the identity gate (10 prompts, 4K and 20K prompts) is identical to the run with the fused
+kernel off. If Gyro misbehaves on an RTX 50 card, update the engine.
**Prompt speed and the ggml build.** The trellis prompt kernels (MMQ) are agentionai's, from their llama.cpp fork (MIT).
Strata builds against upstream ggml, which does not have them, so it adds them itself at configure time:
diff --git a/docs/MODELS.md b/docs/MODELS.md
index d07691e22..d1b075a7c 100644
--- a/docs/MODELS.md
+++ b/docs/MODELS.md
@@ -1,11 +1,14 @@
# Which model? Sizes, versions and what fits
-Strata runs one model, [Qwen3.8-Flash-Next](https://huggingface.co/Qwen/Qwen3.8-Flash-Next), in several **sizes**
-(the same model, compressed more or less) and several **versions** (the original, a coding version, a fine-tune).
-The installer recommends one for your PC; this page explains the choice. Back to the [README](../README.md).
+Strata's main model is [Qwen3.8-Flash-Next](https://huggingface.co/Qwen/Qwen3.8-Flash-Next), in several **sizes**
+(the same model, compressed more or less) and several **versions** (the original, a coding version, a fine-tune, other
+makers' compressions). It also runs a smaller model, [Qwen3.6-35B-A3B](#qwen36-35b-a3b). The desktop app, the Terminal
+(`strata launch`) and the installer recommend one for your PC; this page explains the choice. Back to the
+[README](../README.md).
> **On this page:** [Pick by RAM](#pick-by-ram) · [Speed](#how-fast-is-each-size) · [The sizes](#the-sizes) ·
-> [Will it fit?](#will-it-fit) · [The versions](#the-versions) · [Adding another model](#adding-or-switching-models)
+> [Will it fit?](#will-it-fit) · [The versions](#the-versions) · [Qwen3.6](#qwen36-35b-a3b) ·
+> [Adding another model](#adding-or-switching-models)
## Pick by RAM
@@ -23,7 +26,10 @@ your RAM allows, take a full model (Q2_0, IQ2_XS or IQ3_S).
## How fast is each size
-Measured on an RTX 5070 (12 GB), a Ryzen 5 7600 and 64 GB of RAM:
+These are older numbers, kept because they compare the sizes with each other. Newer engines are faster on some cards
+(each change is listed with its own measurement in the [details](DETAILS.md)); the 0.2.0 engine (0.1.45.3) has not been
+re-measured on the whole table. Measured on an RTX 5070 (12 GB), a Ryzen 5 7600 and 64 GB of RAM, engine 0.1.26 (the
+Q2_0 row: engine 0.1.36, which made Q2_0 prompts faster):
| Size | Writes answers (short chat) | Writes answers (128K context) | Reads your prompt |
| --- | ---: | ---: | ---: |
@@ -33,8 +39,8 @@ Measured on an RTX 5070 (12 GB), a Ryzen 5 7600 and 64 GB of RAM:
| **IQ3_S** | 53 tokens/s | 46 tokens/s | 1,620 tokens/s |
| **Coder** (IQ1_M) | 55 tokens/s | 43 tokens/s | 2,180 tokens/s |
-Measured on an AMD RX 9070 XT (16 GB), a Ryzen 9 3900X and 47 GB of RAM (Linux, setup's own install; Q2_0 is
-above setup's RAM estimate for 47 GB and was installed with `--model Q2_0 --yes`):
+Measured on an AMD RX 9070 XT (16 GB), a Ryzen 9 3900X and 47 GB of RAM (Linux, setup's own install, 2026-10-02, an engine
+from before 0.1.40; Q2_0 is above setup's RAM estimate for 47 GB and was installed with `--model Q2_0 --yes`):
| Size | Writes answers (short chat) | Writes answers (128K context) | Reads your prompt |
| --- | ---: | ---: | ---: |
@@ -46,13 +52,14 @@ above setup's RAM estimate for 47 GB and was installed with `--model Q2_0 --yes`
- **Reads your prompt** = how fast it takes in what you send (long documents, code, chat history), measured on a
32K-token prompt; a 4K prompt reads at 910-1,580 tokens/s. A 32K prompt takes about 15 seconds with Q2_0.
-A card with more VRAM is faster, because more of the model fits on the GPU: an RTX 3090 (24 GB) should do roughly
-100-140 tokens per second. All measurements, long-context numbers and estimates for other cards are in the
-[details](DETAILS.md#speed-measured). The AMD measurements per card (RX 9070 XT, Radeon AI PRO R9700, RX 7800 XT,
-RX 9060 XT, RX 6900 XT) are in [AMD_HIP.md](AMD_HIP.md#rdna4-gfx1201).
+A card with more VRAM is faster, because more of the model fits on the GPU. For an RTX 3090 (24 GB) the
+[details](DETAILS.md#other-gpus-estimated) give an estimate, not a measurement. All measurements, long-context numbers
+and estimates for other cards are in the [details](DETAILS.md#speed-measured). The AMD measurements per card (RX 9070 XT,
+Radeon AI PRO R9700, RX 7800 XT, RX 9060 XT, RX 6900 XT) are in [AMD_HIP.md](AMD_HIP.md#rdna4-gfx1201).
Every PC is different: `START-HERE.bat --calibrate` measures a few engine settings on yours and keeps the fastest
-(about 15-30 minutes, longer on a slow card; on the PC above it made the Coder 7% faster; NVIDIA cards for now). Measured Strata on your own
+(about 15-30 minutes, longer on a slow card; on the PC above it made the Coder 7% faster; NVIDIA cards for now).
+`strata launch` and the app have their own tuning step (quick: about 20 minutes). Measured Strata on your own
PC? See [Community benchmark results](COMMUNITY_BENCHMARKS.md) for a report template and how to share your results
in a pull request.
@@ -87,6 +94,14 @@ Coder. With a small card most experts then come from the SSD and it is much slow
## The versions
+**Pictures.** The versions in setup's menu read pictures, and pictures are **on by default** wherever a model can
+read them. The picture reader runs on the CPU when the graphics card has less than 24 GB (a few seconds per
+picture, nothing taken from the card) and on the graphics card from 24 GB (about 1-1.4 GB of VRAM; 0.1-0.5 s per
+picture). The rule is the same for every make of card. `--vision off` (or "No" in the app and in `strata launch`) turns
+pictures off; `--vision cpu` or `--vision gpu` picks the reader. On AMD, `strata-vision-hip` is the card's reader; if it
+cannot start, Strata uses the CPU reader by itself ([AMD_HIP.md](AMD_HIP.md)). **The Mac app and the Mac Terminal have no
+picture reader yet** ([MAC.md](MAC.md)). More: [Images](DETAILS.md#images-vision).
+
### Qwen3.8-Flash-Next
The original, in all four sizes. With images, and with the
@@ -125,8 +140,8 @@ START-HERE.bat --setup --family swift --model IQ2_XS
The fourth version in setup's menu (`--family unsloth`) is **Unsloth's quantizations** of the same model, from ~4 to 8
bits. They keep the original's experts at more bits than the 2-3-bit sizes above, so they need more RAM. Setup keeps
every expert in RAM where they and 16 GB more fit (the fastest way); with less RAM it keeps as many as fit and reads
-the rest from the SSD while it answers (much slower), and for the bigger files it asks first. Images are on by default
-on an NVIDIA card of 16 GB or more (and on AMD with the CPU encoder where the experts fit in RAM).
+the rest from the SSD while it answers (much slower), and for the bigger files it asks first. Pictures are on by default
+(the CPU reader under 24 GB of graphics memory, the card's reader from 24 GB).
| Size | Download | Experts | RAM for all of them in RAM | Same top token as Q8_0 | AMD R9700 (32 GB): story / code / 32K prompt |
| --- | ---: | ---: | ---: | ---: | --- |
@@ -136,7 +151,8 @@ on an NVIDIA card of 16 GB or more (and on AMD with the CPU encoder where the ex
| **UD-Q6_K_XL** | 169 GB | 102 GiB | ~118 GB | 94.6% | 54 / 76 / 1,020 |
| **Q8_0** | 188 GB | 120 GiB | ~136 GB | 100% (the reference) | 53-57 / 66-74 / 1,230-1,300 |
-For comparison, IQ3_S on the same card: 75 / 95 tok/s, 87.7% the same top token as Q8_0. The quality numbers, the
+For comparison, IQ3_S on the same card: 75 / 95 tok/s, 87.7% the same top token as Q8_0. The speed figures come from
+engines older than 0.1.45.3 (the conditions are in [QUANTS.md](QUANTS.md)). The quality numbers, the
speed bound and NVIDIA/AMD/Intel details: [QUANTS.md](QUANTS.md); the files: [UD-Q4_K_XL](UNSLOTH_Q4.md),
[UD-Q6_K_XL](UNSLOTH_Q6.md).
@@ -157,16 +173,39 @@ experts in a rotated basis. They are the smallest options and never setup's defa
| **Gyro-S** | 58.5 GB | 27.6 GB | the smallest option, for PCs with little memory; lower quality |
| **Gyro-M** | 92.0 GB | 35 GB | about IQ3_XXS quality with about 20% less GPU memory; decodes about 20% slower than Q2_0 on 12 GB cards |
-NVIDIA, and AMD (experimental); not Intel Arc or the Mac. Images are off. Details, measurements and credit:
+NVIDIA, and AMD (experimental); not Intel Arc or the Mac. Gyro **reads pictures** (the same rule as above). It needs
+engine 0.1.45.1 or newer; if the engine is older, the app says "This model needs a newer engine" and offers Update
+engine. Gyro gives correct output on RTX 50 cards with engine 0.1.45.3. Details, measurements and credit:
[GYRO.md](GYRO.md).
```
START-HERE.bat --setup --family gyro --model Gyro-S
```
+<a id="nvfp4"></a>
+
+### NVFP4: three versions (NVIDIA cards)
+
+The sixth version in setup's menu (`--family nvfp4`) keeps the experts in NVIDIA's 4-bit NVFP4 format. There are three
+versions of it. The app shows them by who made the weights:
+
+| App name | Setup name (`--model`) | What it is | Download |
+| --- | --- | --- | ---: |
+| **NVFP4 (Strata's version)** | `NVFP4` | Strata's own conversion (GPTQ; the ready-made pack is sergqwer's strata-nvfp4). The best quality of the three | 128 GB |
+| **NVFP4 (NVIDIA's version)** | `NVFP4-NVIDIA` | NVIDIA's own NVFP4 checkpoint (plain rounding), converted for Strata. The same size and speed as the first | 128 GB |
+| **NVFP4 (NVIDIA, trained for FP4)** | `NVFP4-QAD` | NVIDIA's retrained 4-bit model, slightly faster on short prompts ([below](#nvfp4-qad)) | 102 GB (+110 GB of disk to prepare) |
+
+All three need about 80 GB of RAM to keep every expert in RAM, run on **NVIDIA cards only**, and read pictures (the
+same rule as above). RTX 50 cards have FP4 tensor cores; other NVIDIA cards run NVFP4 at 8-bit precision. The first two
+need engine 0.1.44 or newer, the third 0.1.45 or newer. Details and measurements: [NVFP4.md](NVFP4.md).
+
+```
+START-HERE.bat --setup --family nvfp4 --model NVFP4
+```
+
<a id="nvfp4-qad"></a>
-### NVIDIA's retrained 4-bit model (NVFP4-QAD)
+#### NVIDIA's retrained 4-bit model (NVFP4-QAD)
NVIDIA retrained Qwen3.8-Flash-Next for 4-bit experts (quantization-aware distillation) and published it as
[Qwen3.8-Flash-Next-FP4-Local](https://huggingface.co/nvidia/Qwen3.8-Flash-Next-FP4-Local). In setup's NVFP4 family it is
@@ -176,9 +215,9 @@ afterwards). Nothing of NVIDIA's weights is redistributed by Strata.
| Size | Download | Memory it needs | In plain words |
| --- | ---: | ---: | --- |
-| **NVFP4-QAD** | 102 GB (+110 GB of disk to prepare) | like NVFP4: ~80 GB of RAM keeps every expert in RAM | NVIDIA's FP4, trained for FP4 - slightly faster on short prompts than NVFP4 (GPTQ is the best quality of the NVFP4 versions); RTX 50 cards have FP4 tensor cores, other NVIDIA cards run it at 8-bit precision |
+| **NVFP4-QAD** (app: NVFP4 (NVIDIA, trained for FP4)) | 102 GB (+110 GB of disk to prepare) | like NVFP4: ~80 GB of RAM keeps every expert in RAM | NVIDIA's FP4, trained for FP4 - slightly faster on short prompts than the other two NVFP4 versions (Strata's version has the best quality) |
-NVIDIA cards only. Images are off for now. Its licenses are the NVIDIA Open Model Agreement and Qwen's Community License.
+NVIDIA cards only. It reads pictures (through the original model's picture reader file, which setup downloads with it). Its licenses are the NVIDIA Open Model Agreement and Qwen's Community License.
Technical details and measurements: [NVFP4.md](NVFP4.md#nvidias-fp4-local-checkpoint).
```
@@ -190,9 +229,39 @@ START-HERE.bat --setup --family nvfp4 --model NVFP4-QAD
For **OrcaRouter's Flash-Next Uncensored IQ3_XXS**, see the [manual compatibility setup](ORCA.md). It needs an
explicit packing conversion and is not an installer menu option.
+## Qwen3.6-35B-A3B
+
+A smaller model from the same maker: [Qwen3.6-35B-A3B](https://huggingface.co/Qwen/Qwen3.6-35B-A3B) (35 billion
+parameters, 3 billion active per token, 256 experts, Apache 2.0 license). Strata runs [Unsloth's GGUFs with the MTP
+draft layer](https://huggingface.co/unsloth/Qwen3.6-35B-A3B-MTP-GGUF) on its own engine path, chosen by the file. It is
+in the app's model list and in setup (`--family qwen36`). It runs on NVIDIA and AMD cards; the Intel Arc engine and the
+Mac engine do not run it. It reads pictures and serves several requests at once.
+
+| Size | File | RAM setup plans for | In plain words |
+| --- | ---: | ---: | --- |
+| **UD-Q4_K_XL** | 22.9 GB | 32 GB | 4-bit (Unsloth Dynamic), the smallest |
+| **UD-Q6_K_XL** | 32.6 GB | 44 GB | 6-bit, closer to the full model |
+| **Q8_0** | 37.8 GB | 52 GB | 8-bit, the closest to the full model |
+
+The picture reader file adds 0.9 GB. The engine keeps every expert it can on the graphics card and computes the rest on
+the CPU. Measured with engine 0.1.45 and UD-Q4_K_XL: decode 117.8 tokens/s on a Radeon AI PRO R9700 (32 GB) and 59.7
+tokens/s on an RTX 3060 (12 GB, most experts on the CPU). Pictures, requests at once, the full measurements and the
+limits: [QWEN36.md](QWEN36.md).
+
+```
+START-HERE.bat --setup --family qwen36 --model UD-Q4_K_XL
+```
+
## Adding or switching models
-You can add another model any time with `SETUP.bat` (the same as `START-HERE.bat --setup`; on Linux
-`./setup.sh --setup`). Files another model shares are not downloaded again (the Coder uses the original's shard 2 and
-vision encoder). With more than one model installed, `START-HERE.bat` asks which one to start; `run-<model>.bat`
-(Linux: `run-<model>.sh`) starts one directly.
+- **In the app:** the Models page lists every model with its size and whether it fits your computer; pick one and press
+ the install button.
+- **In the Terminal:** `strata launch` has a Model step with the same list (and "Use model files I already have").
+ `strata models list` shows what is installed; `strata models import <folder or .gguf> --plan` shows what a set of files
+ you already have would be, without changing anything.
+- **With the installer:** `SETUP.bat` (the same as `START-HERE.bat --setup`; on Linux `./setup.sh --setup`) adds another
+ model any time.
+
+Files another model shares are not downloaded again (the Coder uses the original's shard 2 and vision encoder). With more
+than one model installed, `START-HERE.bat` asks which one to start; `run-<model>.bat` (Linux: `run-<model>.sh`) starts one
+directly.
diff --git a/docs/NVFP4.md b/docs/NVFP4.md
index a56288941..f64ffd1a7 100644
--- a/docs/NVFP4.md
+++ b/docs/NVFP4.md
@@ -5,6 +5,11 @@ blocks of E2M1 codes with four UE4M3 sub-block scales, plus one FP32 `weight_sca
Everything else (attention, GDN, shared experts, routers, the head) stays in the formats the native path already
reads. Measured on Windows 11, RTX 5090 (32 GB), Ryzen 9 9950X3D, 128 GB DDR5-5600.
+**The three NVFP4 versions in setup and the app.** `NVFP4` is "NVFP4 (Strata's version)", `NVFP4-NVIDIA` is "NVFP4
+(NVIDIA's version)", and `NVFP4-QAD` is "NVFP4 (NVIDIA, trained for FP4)" ([the short guide](MODELS.md#nvfp4)). All three
+read pictures, through the original model's picture reader file that setup downloads with them (see "Images" below and
+the FP4-Local section). The other sections of this page apply to all three unless they say otherwise.
+
## Getting a model
```
@@ -38,7 +43,7 @@ original model therefore work as they are.
Tested end to end with `jpezzulli/OrcaRouter-Qwen3.8-Flash-Next-Uncensored-ModelOpt-NVFP4`. By its
`hf_quant_config.json`, NVIDIA's `nvidia/Qwen3.8-Flash-Next-NVFP4` quantizes the routed experts the same way
(NVFP4, group 16; the other layers BF16, the PLE table FP8, the MTP experts FP8), so it takes the same path. It has
-not been run here.
+not been run here as downloaded. Setup offers it as a ready-made pack, the size `NVFP4-NVIDIA`.
## Measured
@@ -111,7 +116,8 @@ Images: the packs keep Qwen's vision tower unquantized, so the original's image
(`--vision`; strata-vision opens the dense GGUF for the vocabulary). Checked on an RTX 5070 and an RTX 3060 against
IQ3_XXS's answers on the same picture (a number in the picture read, two shapes with their colours and sides). The
encoder on the GPU takes ~1.1 GiB of VRAM: on the 3060 at 8K context the cache held 1,293 experts with images against
-1,734 without.
+1,734 without. Pictures are on by default; setup and the app pick the CPU reader under 24 GB of graphics memory and the
+GPU reader from 24 GB (`--vision cpu` / `--vision gpu` change it).
## Where the global scales go
@@ -232,7 +238,7 @@ What the checkpoint holds, and what `tools/nvfp4_local_pack.py` does with it:
| attention, GDN projections, shared experts, indexer: MXFP8 (E4M3 values, E8M0 scale per 32) | dequantized exactly, then Q8_0 (same 32-value blocks; +0.6% RMS on top of MXFP8's own ~3%), or BF16 for the small projections the BF16 kernels read |
| n-gram (PLE) table, 26.8 GiB: NVFP4 rows of 160 values | a one-tensor GGUF of 90-byte rows (80 B codes + 10 E4M3 scales, one F32 for the table), read by the new PLE format `NVFP4` (`strata.ple.format = nvfp4x16`) in `ngram.cpp`; same row size as IQ4_NL |
| MTP head: NVFP4 experts, BF16 rest | a Q2_0 draft layer built with `mtp_pack.py` / `mtp_rt.py` (88.7% of drafts accepted over 225 test requests) |
-| vision tower | not converted yet (text only) |
+| vision tower | not converted. Pictures are read by the original model's picture reader (the shared `mmproj` file that setup downloads, as for the other NVFP4 versions); the dense GGUF supplies the vocabulary |
`python tools/nvfp4_local_pack.py prepare --model <checkpoint> --out <dir>` runs every step (setup does this): the n-gram
table, the dense GGUF (no experts), the pack (experts written straight from the checkpoint) and the draft layer. It needs
diff --git a/docs/QWEN36.md b/docs/QWEN36.md
index 1830493e4..c39c86922 100644
--- a/docs/QWEN36.md
+++ b/docs/QWEN36.md
@@ -2,7 +2,7 @@
Strata runs [Qwen3.6-35B-A3B](https://huggingface.co/Qwen/Qwen3.6-35B-A3B) (35B mixture of experts, 3B active, 256 experts, top-8) from
[Unsloth's GGUFs with the MTP layer](https://huggingface.co/unsloth/Qwen3.6-35B-A3B-MTP-GGUF) (UD-Q4_K_XL, UD-Q6_K_XL, Q8_0) on its own
-engine path (`src/qwen35`; `strata` switches to it from the file's architecture). Pick it in setup (`--family qwen36`). Besides text it
+engine path (`src/qwen35`; `strata` switches to it from the file's architecture). Pick it in the app's model list, in `strata launch` or in setup (`--family qwen36`). Besides text it
reads **pictures** and serves **several requests at once**, the same two options the Flash-Next models have.
Measured on an AMD Radeon AI PRO R9700 32 GB (HIP, Linux, UD-Q4_K_XL, every expert in VRAM) and on an RTX 3060 12 GB (CUDA, 20 threads,
@@ -13,10 +13,11 @@ UD-Q4_K_XL in the hybrid mode: 22-37 of 256 experts per layer in VRAM, the rest
The vision encoder is Unsloth's `mmproj-F16.gguf` (0.9 GB, pinned revision, SHA-256 checked by setup): a 27-layer ViT with a 2x2 merger,
the same projector family as the Flash-Next models' (`qwen3vl_merger`; only its output width differs: 2048 here, 2560 there). Strata runs
it with the same helper (`strata-vision`, llama.cpp's `mtmd`), so the encoder choices are the Flash-Next ones
-([Images](DETAILS.md#images-vision)): **setup asks "Do you want images?"**, the default answer is yes on an NVIDIA card of 16 GB or more
-(GPU encoder, ~1.2 GB of VRAM at up to 1,024 image tokens) and on AMD under Linux (CPU encoder, no VRAM); `--vision yes|no|gpu|cpu`
-and `--vision-tokens N` work as there. A card under 16 GB is recommended the CPU encoder (the GPU one takes room from the experts);
-`--vision gpu` is kept as asked, with a note.
+([Images](DETAILS.md#images-vision)). **Pictures are on by default**, the same rule as for every model and every make of card:
+the CPU reader under 24 GB of graphics memory (a few seconds per picture, no VRAM), the card's reader from 24 GB (GPU encoder,
+~1.2 GB of VRAM at up to 1,024 image tokens; on AMD it is `strata-vision-hip`, with the CPU reader as its fallback).
+`--vision yes|no|gpu|cpu` and `--vision-tokens N` work as there; what you ask for is kept, with a note. The Mac engine does
+not run this model.
| Encoder | Time per picture (640x400 = 260 tokens / 800x450 = 350 tokens) | VRAM |
| --- | --- | --- |
@@ -171,7 +172,7 @@ prompt state: KL against the 512 chunk on six real 1.5-3.2K-token documents (48
4096 3.6e-3 (per prompt 2.3e-3 .. 5.9e-3), top-1 agreement 44-48 of 48 rows - the size of the llama.cpp CPU-vs-HIP difference on the same
file (4.2e-3), not a quality loss. Greedy 64 tokens after those six documents: the default chunk gives the base engine's text for 2 of 6,
`--prefill 512` for 6 of 6. A prompt shorter than the chunk (every chat turn after the first) is one chunk either way: unchanged.
-The new default's goldens are `phaseA-tests/q36speed/golden/` (six documents, greedy 64): later changes are checked against them.
+The maintainers keep the new default's reference outputs (six documents, greedy 64) and check later changes against them.
**Tried and dropped.** The MTP drafts' head over a subset of the vocabulary (`--draft-vocab N`, kept as an opt-in; the answer never
changes): the first 16K-131K rows gain 5-8% on English and code but lose 10-15% on Chinese / Russian / Arabic / Hindi (70% of a Chinese
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 799ad8e5f..fa814f144 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -1,8 +1,53 @@
# Something went wrong?
-The common problems and what to do. Back to the [README](../README.md#something-went-wrong). The full table of
+The common problems and what to do, for the desktop app, the Terminal (`strata launch`) and the installer. Back to the [README](../README.md#something-went-wrong). The full table of
error messages, with the older engine fixes, is in the [details](DETAILS.md#troubleshooting).
+## The desktop app and the Terminal
+
+**A warning says Strata "couldn't find an engine for this computer".**
+The engine is the part that talks to your graphics card. This is a warning, not a refusal: Strata still downloads the
+model, and the model files stay on your computer, but the model may not run until the right engine is installed. The usual
+reasons are that no engine is installed yet and the update source has none for your card, that the engine found is for
+another make of card, or that the graphics driver is too old. In the app, open Settings, then Engine. In the Terminal, the
+message names the next step: run `strata update --feed <address>` with the update source you were given (or ask whoever sent
+you Strata for the engine that matches your card), then run `strata launch` again.
+
+**"This model needs a newer engine." (the app), or a button called Update engine.**
+Some models need an engine newer than the one installed: Gyro needs 0.1.45.1 or newer, NVFP4 needs 0.1.44, and NVFP4 (NVIDIA,
+trained for FP4) needs 0.1.45. In the app, open Settings, then Engine, and press Update engine. It asks first, keeps your
+model files and settings, and wants running models unloaded. In the Terminal: `strata update --check` says what would
+change, `strata update` installs it (it switches to the new engine only after a test start). If the engine you
+installed is the newest and the message stays, the update source has no newer engine for your card yet.
+
+**On a Mac: "Strata is damaged and can't be opened", "cannot be opened", or "unidentified developer".**
+Nothing is wrong with the file. macOS marks everything a browser downloads, and only lets a marked program run if Apple
+has checked it. Strata's release builds are checked by Apple ("notarised"): drag Strata onto Applications and open it; the
+first time, macOS asks "Are you sure you want to open it?" and you press Open. A test build that is not notarised says
+"damaged". Do not move it to the Trash. Open the Terminal app and remove the mark, with the line that matches what you have
+(drag the file from Finder into the Terminal window to type its path):
+
+ xattr -dr com.apple.quarantine ~/Downloads/<the .dmg file> # the .dmg, before opening it
+ xattr -dr com.apple.quarantine /Applications/Strata.app # the app, after dragging it over
+ xattr -dr com.apple.quarantine <the folder you unzipped> # an unzipped Terminal folder
+
+Then open it again. If macOS says only "the developer cannot be verified", you can instead try to open it once, then open
+System Settings > Privacy & Security and press "Open Anyway" next to the message about Strata. Installs made with
+`curl ... | sh` carry no mark and need none of this. To see which kind you have: `spctl -a -vv /Applications/Strata.app`
+answers "accepted" and "Notarized Developer ID" for a notarised build. (How the builds are signed: `packaging/mac/README.md`.)
+
+**Checking what is installed: `strata doctor`.**
+It is a read-only check of the installed engine parts (it changes nothing): which engine and helper files a saved model
+needs, and whether they are there. `strata doctor --live` also asks the computer which graphics cards it sees and compares
+them with the cards the model is set to use; `--output json` prints the same as data. Put its output into a bug report.
+
+**Sending logs for a bug report.**
+In the app: Settings, Engine, Diagnostics, View logs, then Save logs. It writes one text file,
+`strata-diagnostics-<date>.txt`, into your Downloads folder and shows where. It holds the engine's messages, the failed
+steps and the end of each model's server log. In the Terminal, send the output of `strata doctor`. If the Linux app window
+crashes or will not open, run the AppImage with `--save-logs` in a terminal instead; it writes the crash log and the other
+logs to one file in Downloads. Look through a log before you send it, and never send an API key.
+
## While installing or starting
**My PC froze, or got very slow, the first time Strata started.**
@@ -131,10 +176,14 @@ with 13.0. If you compile it yourself, use CUDA 13.0, 13.1 or 13.2.2 (13.2.2, nv
setup warns when it finds 13.2.0 or 13.2.1 for such a card, and takes an older 13.x when one is installed.
**Pictures are refused, or slow.**
-"this server was started without the vision encoder": the model was set up for text only - run setup again with
-`--vision gpu` (or `--vision cpu`). Pictures that take several seconds (about 3 s at 300 image tokens on 8 cores, more with more tokens) are read by the encoder on the CPU; `--vision gpu`
-(NVIDIA and AMD, ~1.4 GB of VRAM) makes it 0.1-0.5 s. On AMD the GPU reader is the default; if it cannot start, the server
-prints "the GPU picture reader did not start (...); pictures are read on the CPU" and goes on with the CPU reader.
+"this server was started without the vision encoder": the model was set up for text only (someone chose "No", or the
+engine has no picture reader) - run setup again with `--vision yes` (or `--vision gpu` / `--vision cpu`), or switch pictures
+on in the app or on the Pictures step of `strata launch`. Pictures are on by default wherever a model can read them. The
+reader runs on the CPU under 24 GB of graphics memory and on the card from 24 GB, on every make of card. Pictures that take
+several seconds (about 3 s at 300 image tokens on 8 cores, more with more tokens) are read by the encoder on the CPU;
+`--vision gpu` (NVIDIA and AMD, ~1.4 GB of VRAM) makes it 0.1-0.5 s. On AMD the card's reader is `strata-vision-hip`; if it
+cannot start, the server prints "the GPU picture reader did not start (...); pictures are read on the CPU" and goes on with
+the CPU reader. The Mac app and the Mac Terminal have no picture reader yet.
## AMD cards
@@ -193,4 +242,7 @@ R9700) in the `env` block of the server JSON, then a restart. Experimental, one
## Still stuck?
Look in the [full troubleshooting table](DETAILS.md#troubleshooting), or open an
-[issue](https://github.com/Niko1221/Strata/issues) and attach `strata-<model>.log` from the Strata folder.
+[issue](https://github.com/Niko1221/Strata/issues) and attach the log: in the app, the file Save logs writes (see
+[above](#the-desktop-app-and-the-terminal)); in the Terminal, the output of `strata doctor`; with the installer,
+`strata-<model>.log` from the Strata folder. Say which one you use (app, Terminal or the installer), your Strata and
+engine versions and your card.