clean up env vars

CMakeLists.txt

@@ -111,6 +111,16 @@ endif()
 option(TRANSCRIBE_BUILD_TESTS    "Build unit / smoke tests" ON)
 option(TRANSCRIBE_BUILD_EXAMPLES "Build example CLI"        ON)
 option(TRANSCRIBE_BUILD_TOOLS    "Build inspect / quantize" OFF)  # post pass 2
+# Numerical-parity validation hooks: reference-mel injection (TRANSCRIBE_MEL_FROM_REF)
+# and per-layer tensor dumps (TRANSCRIBE_DUMP_ALL_BLOCKS / _SUB_BLOCKS). OFF for
+# release so the hook code is not compiled into shipped binaries — the env-var
+# reads, ref-mel loaders, and dump scaffolding all live behind this guard, so
+# their names do not even appear in a release binary's strings. The validation
+# pipeline (scripts/validate.py, the Modal sweep image) builds with this ON;
+# validate.py hard-fails --mel-from-ref against an OFF build rather than
+# silently ignoring it.
+option(TRANSCRIBE_ENABLE_VALIDATION_HOOKS
+                                 "Compile in numerical-parity validation hooks" OFF)
 option(TRANSCRIBE_METAL          "Enable Metal backend"     ${TRANSCRIBE_IS_APPLE_SILICON})
 option(TRANSCRIBE_VULKAN         "Enable Vulkan backend"    OFF)  # post-v1
 option(TRANSCRIBE_CUDA           "Enable CUDA backend"      OFF)  # opt-in; Linux + nvcc
@@ -182,7 +192,7 @@ option(TRANSCRIBE_INSTALL
 
 # Real-model gated tests. OFF by default because the tests need a
 # converted Parakeet GGUF on disk (~2.4 GB) and CI can't ship one.
-# When ON, the test reads TRANSCRIBE_REAL_PARAKEET_GGUF from the
+# When ON, the test reads TRANSCRIBE_PARAKEET_GGUF from the
 # environment at run time. See tests/parakeet_real_smoke.cpp.
 option(TRANSCRIBE_BUILD_REAL_MODEL_TESTS
     "Build tests that load real (multi-GB) model files via env var" OFF)

CMakePresets.json

@@ -56,6 +56,15 @@
       "inherits": "wheel-linux-cpu-vulkan",
       "displayName": "Windows x86_64 default wheel: CPU + Vulkan backend modules",
       "description": "Same provider shape as wheel-linux-cpu-vulkan on Windows: conservative CPU module + Vulkan module, loaded package-locally (the Python loader calls os.add_dll_directory before CDLL). Build image needs the Vulkan SDK (glslc)."
+    },
+    {
+      "name": "validation",
+      "displayName": "Local numerical-parity validation build (build/)",
+      "description": "Dev build for scripts/validate.py: enables TRANSCRIBE_ENABLE_VALIDATION_HOOKS so the reference-mel injection (TRANSCRIBE_MEL_FROM_REF) and per-layer tensor dumps (TRANSCRIBE_DUMP_ALL_BLOCKS / TRANSCRIBE_DUMP_SUB_BLOCKS) are compiled in. Targets build/ (the dir validate.py runs build/bin/transcribe-cli from) and reuses the existing generator. NOT for release — shipped and wheel builds leave the hooks out (TRANSCRIBE_ENABLE_VALIDATION_HOOKS defaults OFF).",
+      "binaryDir": "${sourceDir}/build",
+      "cacheVariables": {
+        "TRANSCRIBE_ENABLE_VALIDATION_HOOKS": "ON"
+      }
     }
   ]
 }

README.md

@@ -119,7 +119,7 @@ Some tests require a real model file. Enable them with:
 ```bash
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
-TRANSCRIBE_REAL_PARAKEET_GGUF=path/to/model.gguf ctest --test-dir build
+TRANSCRIBE_PARAKEET_GGUF=path/to/model.gguf ctest --test-dir build
 ```
 
 For the model-family smoke-test, numerical-validation, and benchmark

docs/environment-variables.md

@@ -0,0 +1,91 @@
+# Environment Variables
+
+A single reference for the environment variables transcribe.cpp recognizes,
+split by audience. The library follows one parse convention for boolean
+toggles: a flag is **on** when it is set, non-empty, and its first character is
+not `0` (so `FOO=1`, `FOO=on`, `FOO=yes` are on; `FOO=0`, `FOO=` and unset are
+off). Path-valued vars are off when unset or empty.
+
+## Tier 1 — runtime configuration
+
+Compiled into every build, including release. These are operational knobs, not
+build-gated. Note that `TRANSCRIBE_DUMP_DIR` — while it ships — is still a
+tensor-dumping debug/validation hook: enabling it does per-tensor device→host
+copies and writes raw activations to disk, so it carries I/O cost and a
+data-leak surface. Leave it unset in production unless you are deliberately
+collecting dumps.
+
+| Variable | Effect |
+| --- | --- |
+| `TRANSCRIBE_NO_FLASH` | Disable flash attention on encoder and decoder (forces the manual F32 path). |
+| `TRANSCRIBE_FORCE_FLASH` | Force flash attention on. Wins over `TRANSCRIBE_NO_FLASH` if both are set. |
+| `TRANSCRIBE_CONV_DIRECT_DW` / `TRANSCRIBE_CONV_NO_DIRECT_DW` | Force the depthwise-conv dispatch to the direct `conv_2d_dw` path / the im2col path, overriding the per-family backend default. |
+| `TRANSCRIBE_CONV_DIRECT_PW` / `TRANSCRIBE_CONV_NO_DIRECT_PW` | Force the pointwise-conv dispatch to direct `mul_mat` / im2col, overriding the backend default. |
+| `TRANSCRIBE_DUMP_DIR=<dir>` | Enable the per-stage tensor dumper; writes `<name>.f32` + `<name>.json` per dumped tensor into `<dir>`. The basis for the numerical-comparison harness (`scripts/compare_tensors.py`). |
+| `TRANSCRIBE_PERF_DEBUG` | Print a per-stage timing breakdown to stderr (DEBUG log) on the families that profile (`cohere`, `granite`, `canary`, `canary_qwen`, `moonshine`, `moonshine_streaming`, `qwen3_asr`, `whisper`). For whisper, a value containing `cpu` or `all` additionally prints the CPU sub-section breakdown. |
+| `TRANSCRIBE_VOXTRAL_REALTIME_STREAM_TIMING` | Print a per-component streaming wall-time breakdown at stream finalize (voxtral_realtime). |
+
+## Tier 2 — validation hooks
+
+Numerical-parity hooks for porting and validation. **Compiled in only when the
+library is built with `-DTRANSCRIBE_ENABLE_VALIDATION_HOOKS=ON`** (see the CMake
+option of the same name, or the `validation` preset). Release/wheel builds leave
+them out entirely — the env-var reads, ref-mel loaders, and dump scaffolding are
+all behind the compile guard, so these names do not even appear in a release
+binary. In a build *without* the flag, setting any of these has no effect;
+`scripts/validate.py` hard-fails `--mel-from-ref` against such a build rather
+than silently falling back.
+
+| Variable | Effect |
+| --- | --- |
+| `TRANSCRIBE_MEL_FROM_REF=<dir>` | Inject a reference log-mel from `<dir>` instead of computing it, so encoder drift can be isolated from frontend drift. Each family reads its own dump filename/layout from the directory (`enc.mel.in.f32` for whisper / voxtral_realtime, `frontend.mel.out.f32` for gigaam, `mel.in.f32` for medasr). Driven by `scripts/validate.py --mel-from-ref`. |
+| `TRANSCRIBE_DUMP_ALL_BLOCKS` | Dump every encoder block output (not just mid/last) for a layer-by-layer divergence bisect (parakeet, gigaam). Requires `TRANSCRIBE_DUMP_DIR`. |
+| `TRANSCRIBE_DUMP_SUB_BLOCKS=<csv>` | Dump intermediate sub-layer activations (ff1/attn/conv/ff2) for the listed block indices, e.g. `0,12,23` (parakeet). Requires `TRANSCRIBE_DUMP_DIR`. |
+
+Build a validation-capable `build/` with:
+
+```bash
+cmake --preset validation        # configures build/ with the hooks ON
+cmake --build build --target transcribe-cli
+```
+
+When **toggling** `TRANSCRIBE_ENABLE_VALIDATION_HOOKS` on an existing `build/`,
+do a clean build of the target — an incremental build can leave a stale object
+that did not pick up the changed compile definition:
+
+```bash
+cmake --build build --clean-first --target transcribe-cli
+```
+
+(`scripts/validate.py` guards against the OFF case: it hard-fails
+`--mel-from-ref` when `build/CMakeCache.txt` has the flag off. Longer term, a
+dedicated validation build directory would avoid the toggle entirely.)
+
+## Test & tooling
+
+Not part of the library runtime.
+
+**Real-model test model paths.** Built only with
+`-DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON`; each test skips (exit code 77) when
+its var is unset. Convention: `TRANSCRIBE_<FAMILY>_GGUF`.
+
+| Variable | Test(s) |
+| --- | --- |
+| `TRANSCRIBE_PARAKEET_GGUF` | `parakeet_real_smoke`, `decoder_smoke` |
+| `TRANSCRIBE_COHERE_GGUF` | `cohere_real_smoke`, `cohere_e2e_smoke` |
+| `TRANSCRIBE_WHISPER_GGUF` | `whisper_e2e_smoke`, `whisper_tokenize_parity` |
+| `TRANSCRIBE_QWEN3_ASR_GGUF` (+ `_0_6B_GGUF` / `_1_7B_GGUF`) | qwen3_asr smokes / parity |
+| `TRANSCRIBE_MOONSHINE_STREAMING_TINY_GGUF` | moonshine_streaming smokes |
+| `TRANSCRIBE_VOXTRAL_REALTIME_GGUF` | `voxtral_realtime_real_smoke` |
+| `TRANSCRIBE_WHISPER_BIN_*` | whisper.cpp `.bin` parser/e2e fixtures |
+
+Other test/tooling vars:
+
+- `TRANSCRIBE_TEST_AUDIO` — override the `jfk.wav` path for ad-hoc e2e runs.
+- `TRANSCRIBE_TEST_SAMPLES_DIR` / `TRANSCRIBE_TEST_FIXTURES_DIR` — sample and
+  fixture directories, passed at configure time as compile definitions (not
+  runtime env vars).
+- Python tooling: `TRANSCRIBE_MODELS_DIR`, `TRANSCRIBE_DUMP_DIR` (shared with
+  the library), `HF_TOKEN`, and the binding-level `TRANSCRIBE_BACKEND` /
+  `TRANSCRIBE_LIBRARY`. See [`tools/conversion.md`](tools/conversion.md) and
+  [`tools/validate.md`](tools/validate.md).

docs/model-family-testing.md

@@ -53,7 +53,9 @@ Expected shape:
 
 - Built only when `TRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON`.
 - Skips with return code `77` when the model path is not available.
-- Uses one family-specific environment variable for the model path.
+- Uses one family-specific environment variable for the model path,
+  following the `TRANSCRIBE_<FAMILY>_GGUF` convention (see
+  [`environment-variables.md`](environment-variables.md)).
 - Verifies architecture string, variant string if applicable,
   capabilities, hparams, language list, expected tensor count or
   tensor-table coverage, and canonical weight shapes.

docs/models/cohere-transcribe-03-2026.md

@@ -179,6 +179,6 @@ uv run scripts/validate.py all --family cohere
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_COHERE_MODEL=models/cohere-transcribe-03-2026/cohere-transcribe-03-2026-BF16.gguf \
+TRANSCRIBE_COHERE_GGUF=models/cohere-transcribe-03-2026/cohere-transcribe-03-2026-BF16.gguf \
   ctest --test-dir build --output-on-failure -R 'cohere'
 ```

docs/models/parakeet-tdt-0.6b-v2.md

@@ -164,6 +164,6 @@ uv run scripts/validate.py all --family parakeet
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_PARAKEET_GGUF=models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf \
+TRANSCRIBE_PARAKEET_GGUF=models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf \
   ctest --test-dir build --output-on-failure -R 'parakeet|encoder|decoder'
 ```

docs/models/parakeet-tdt-0.6b-v3.md

@@ -166,6 +166,6 @@ uv run scripts/validate.py all --family parakeet --variant parakeet-tdt-0.6b-v3
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_PARAKEET_GGUF=models/parakeet-tdt-0.6b-v3/parakeet-tdt-0.6b-v3-F32.gguf \
+TRANSCRIBE_PARAKEET_GGUF=models/parakeet-tdt-0.6b-v3/parakeet-tdt-0.6b-v3-F32.gguf \
   ctest --test-dir build --output-on-failure -R 'parakeet|encoder|decoder'
 ```

docs/models/whisper-base.en.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-base.en
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-base.en/whisper-base.en-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-base.en/whisper-base.en-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-base.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-base
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-base/whisper-base-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-base/whisper-base-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-large-v2.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-large-v2
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-large-v2/whisper-large-v2-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-large-v2/whisper-large-v2-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-large-v3-turbo.md

@@ -174,6 +174,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-large-v3-turbo
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-large-v3-turbo/whisper-large-v3-turbo-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-large-v3-turbo/whisper-large-v3-turbo-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-large-v3.md

@@ -174,6 +174,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-large-v3
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-large-v3/whisper-large-v3-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-large-v3/whisper-large-v3-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-large.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-large
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-large/whisper-large-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-large/whisper-large-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-medium.en.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-medium.en
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-medium.en/whisper-medium.en-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-medium.en/whisper-medium.en-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-medium.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-medium
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-medium/whisper-medium-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-medium/whisper-medium-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-small.en.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-small.en
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-small.en/whisper-small.en-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-small.en/whisper-small.en-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-small.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-small
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-small/whisper-small-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-small/whisper-small-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-tiny.en.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-tiny.en
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-tiny.en/whisper-tiny.en-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-tiny.en/whisper-tiny.en-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/models/whisper-tiny.md

@@ -175,6 +175,6 @@ uv run scripts/validate.py all --family whisper --variant whisper-tiny
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_WHISPER_GGUF=$PWD/models/whisper-tiny/whisper-tiny-Q8_0.gguf \
+TRANSCRIBE_WHISPER_GGUF=$PWD/models/whisper-tiny/whisper-tiny-Q8_0.gguf \
   ctest --test-dir build --output-on-failure -R whisper
 ```

docs/porting/families/cohere.md

@@ -64,7 +64,7 @@ Real-model smokes:
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_COHERE_MODEL=models/cohere-transcribe-03-2026/cohere-transcribe-03-2026-BF16.gguf \
+TRANSCRIBE_COHERE_GGUF=models/cohere-transcribe-03-2026/cohere-transcribe-03-2026-BF16.gguf \
   ctest --test-dir build --output-on-failure -R cohere
 ```
 

docs/porting/families/parakeet.md

@@ -96,7 +96,7 @@ Real-model smokes:
 cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
 cmake --build build
 
-TRANSCRIBE_REAL_PARAKEET_GGUF=models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf \
+TRANSCRIBE_PARAKEET_GGUF=models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf \
   ctest --test-dir build --output-on-failure -R 'parakeet|encoder|decoder'
 ```
 

docs/porting/families/whisper.md

@@ -209,7 +209,7 @@ See `reports/porting/whisper/whisper-tiny/intake.json::known_risks`. Highlights:
 
 These items are real C++ work for Stage 4 / 5 but do NOT flow through intake → convert → validate (the GGUF remains the canonical numerical reference):
 
-- **C++ mel frontend (deferred).** Stage 4 bringup runs the encoder against the reference mel injected via `TRANSCRIBE_WHISPER_MEL_FROM_REF=<ref dir>`. `validate.py cpp` sets this env var automatically for the whisper family. The C++ mel frontend (slaney filterbank + Hann periodic window + whisper_logmel dynamic-range compression) is a follow-up. Tolerance file currently records `enc.mel.in` as zero-drift because we read the reference dump; the entry will need widening when the C++ frontend lands.
+- **C++ mel frontend (deferred).** Stage 4 bringup runs the encoder against the reference mel injected via `TRANSCRIBE_MEL_FROM_REF=<ref dir>`. `validate.py cpp` sets this env var automatically for the whisper family. The C++ mel frontend (slaney filterbank + Hann periodic window + whisper_logmel dynamic-range compression) is a follow-up. Tolerance file currently records `enc.mel.in` as zero-drift because we read the reference dump; the entry will need widening when the C++ frontend lands.
 - **whisper.cpp `.bin` loader compatibility (deferred).** The plan calls for accepting upstream whisper.cpp `.bin` files alongside our GGUF. Not implemented in Stage 4; tracked for a later stage.
 - **KV-cached decoder (shipped).** The decoder runs through a KV-cached path: cross K/V are precomputed once from the encoder output into the cross cache; self K/V are written per-step into the self cache. The same graph builder handles both the prompt pass (`n_tokens > 1, n_past = 0`) and per-step generation (`n_tokens = 1, n_past = current`). Self- and cross-caches are F16 by default (flip with `--kv-type f32` for tighter parity). F16 cache introduces ~8× wider per-block `max_abs` drift than F32, concentrated in a few outlier elements; transcripts and 300-sample LibriSpeech WER are unchanged within CI.
 - **Beam search / temperature fallback (deferred).** Greedy argmax with `suppress_tokens` + first-step `begin_suppress_tokens` is enough to match the reference dumps' transcripts byte-for-byte under `do_sample=False, num_beams=1`. Beam search and temperature fallback (whisper.cpp's `temperature_inc` strategy) are follow-ups for the production decode path.

docs/tools/README.md

@@ -62,6 +62,10 @@ This split mirrors `llama.cpp`'s `convert_hf_to_gguf.py` →
 
 ## Other
 
+- [**environment-variables.md**](../environment-variables.md) — the single
+  reference for every env var the library, tests, and tooling recognize, split
+  into Tier 1 runtime config, Tier 2 validation hooks (build-gated), and
+  test/tooling.
 - `scripts/envs/<family>/pyproject.toml` — per-family `uv` env. Each
   converter and reference dumper has its own env because NeMo and
   Transformers have conflicting dependency graphs.