# Documentation index — who owns which topic **This page exists so consumer repos can link ONE hop.** A consuming project's `AGENTS.md` should point here (or at a heading in one of these files) instead of restating a procedure. Then reorganising the docs means fixing this page, not hunting links across every consumer repository. Why it matters, concretely: on 2026-08-11 the Dev Drive filter command was written out in three separate places — `windows-builds.md` here, plus OmniAccelerANT's `AGENTS.md` and `docs/source/platforms.md`. All three copies were **wrong** in the same way (unquoted filter list, missing `/volume`), and `windows-container-build-performance.md` had the correct version the whole time *plus* a warning that people get it wrong exactly that way. Copying is what caused it. ## Where does a piece of knowledge belong? One question decides it: > **Would this still be true in a different project?** - **Yes** → it belongs here. The consumer links to it. - **No** → it belongs in the consumer. The two halves of one topic often split: | Knowledge | Owner | Why | |---|---|---| | How to allow the `bindFlt`/`wcifs` filters on a Dev Drive | **here** | True for any repo on a Dev Drive | | Dart's `copySync`/`renameSync` failing on a bind mount | OmniAccelerANT | Only matters because that app is Flutter | | `--isolation process` caps, and never using it for `docker build` | **here** | A property of the engine and image | | Which CMake presets a project ships | the project | Nobody else has those presets | | The `#requires -Version 7.0` rule for the build modules | **here** | A property of the modules | | Which of those modules a project imports | the project | Its own build | ## Topic → owning document ### Start here | Looking for | Read | |---|---| | **An error message** — symptom → cause → fix, both lanes | [`failure-modes.md`](failure-modes.md) | | **Wiring a new project to this repo** | [`adopting-in-a-new-project.md`](adopting-in-a-new-project.md) | | What is published, what is in it, the feature matrix | [`overview.md`](overview.md) | | Prerequisites, tests, roadmap, contribution, contact | [`project-info.md`](project-info.md) | | **Why the pack is 154 MB, what is large, and why history is not rewritten** | [`project-info.md` § Repository size](project-info.md#repository-size-and-large-files) | | Licences of bundled software, what each one **obliges this project to do**, and the corresponding source for copyleft components | [`third-party-licenses.md`](third-party-licenses.md) | | **Known vulnerabilities** — running `grype`, and why the raw count misleads on these images | [`vulnerability-scanning.md`](vulnerability-scanning.md) | | **SBOM** — how to generate it, and what you can do with it (CVE scanning, procurement, release diffs, policy gates) | [`sbom.md`](sbom.md) | | **SBOM** — the curated half (source-built components, which no image scanner can see) | [`deps/sbom-curated.spdx.json`](deps/sbom-curated.spdx.json), generated by [`scripts/generate_sbom.py`](scripts/generate_sbom.py) | | **SBOM** — the scanner half (apt/pip/npm, thousands of packages) | [`../.github/workflows/sbom.yml`](../.github/workflows/sbom.yml) runs `syft` against the published image | | Rules an automated agent must follow | [`../AGENTS.md`](../AGENTS.md) | | **ONNX Runtime has one source: the chain** — every ORT consumer on both lanes and how it reaches the chain build, the six guards (census, build gate + stamp, crate env, static denylist, invariant, bundle census) and what each cannot see, and how to add a consumer | [`onnxruntime-single-source.md`](onnxruntime-single-source.md) | ### Windows | Looking for | Read | |---|---| | The image itself: what is installed, entrypoint, known traps | [`windows-builds.md`](windows-builds.md) | | **ROCm on Windows** (`-Variant rocm`): the layer in the sdk slot, `-rocm` tags, what each media component enables, redistribution | [`windows-rocm.md`](windows-rocm.md) | | **Rules you must not regress** when editing the Windows chain (49, grouped) | [`windows-build-invariants.md`](windows-build-invariants.md) | | **Which lane to build on**: BuildKit, nerdctl, the removed classic docker lane; isolation policy, preflight gates, RDNA4 A/B history | [`windows-build-lanes.md`](windows-build-lanes.md) | | CPU/memory envelope, the sccache wiring, GPU in containers, the 125-layer budget | [`windows-build-resources.md`](windows-build-resources.md) | | **sccache across build hosts**: the host's WebDAV as level 0, a shared S3 bucket as level 1, the key as BuildKit secrets, the upload drain, the client scripts | [`windows-build-resources.md` § Two cache levels](windows-build-resources.md#two-cache-levels) | | **Bazel's action cache** on the host's dufs (the LiteRT builds), and ORT's nvcc keeping sccache but for its PTX-only targets | [`windows-build-resources.md` § Bazel's cache](windows-build-resources.md#bazels-cache), [§ Persistent compile cache (sccache)](windows-build-resources.md#persistent-compile-cache-sccache) | | **The shared bucket's server**: Garage on a VPS behind the FritzBox's WireGuard, firewall, size cap, rebuild runbook | [`linux/sccache-s3/README.md`](../linux/sccache-s3/README.md) | | **The home fleet's weekly update**: Ansible on pi-1, the inventory's obfuscated names, the schedule, a host that is off, Garage, and each run's log and status | [`linux/ansible/README.md`](../linux/ansible/README.md) | | **Home Assistant on pi-1**: tracked vs live config, secrets, one file per feature in `packages/`, the Ansible page, the energy meter | [`linux/homeassistant/README.md`](../linux/homeassistant/README.md) | | **The home network's addresses**: placeholders in docs and examples, the real values in the gitignored `site.local.env` | [`site.local.env.example`](../site.local.env.example) | | **clang-cl sanitizers**: why `-shared-libsan`, trap-mode UBSan, Microsoft's ASan runtime over LLVM's, and who stages the DLL | [`windows-clang-cl-sanitizers.md`](windows-clang-cl-sanitizers.md) | | Stevedore post-install fixes, ghcr login, service recovery | [`windows-stevedore-and-docker.md`](windows-stevedore-and-docker.md) | | Open refactor work on the Windows chain | [`windows-refactor-backlog.md`](windows-refactor-backlog.md) | | **Local fixes to upstream projects** — every third-party source change the Windows chain carries, graded, and the 12 prepared-but-unsent submissions | [`upstream-windows-patches.md`](upstream-windows-patches.md) | | **Building for Windows-on-ARM**: why there is no arm64 image, the clang-cl cross lane, arch gates, what reached runtime parity with amd64 and what stays amd64-only | [`windows-cross-builds.md`](windows-cross-builds.md) | | **A consumer's Windows products**: the reusable `container-ci-windows.yml` lane, the product folder and its DLL closure (`Copy-PeImportClosure`), and CPack's `KATAGLYPHIS_PACKAGE_DLL_DIR` | [`windows-cross-builds.md` § Consumer cross lanes](windows-cross-builds.md#consumer-cross-lanes-container-ci-windowsyml) | | **Signing a consumer's MSIX** — `Invoke-MsixPackage -Sign -SigningRoot ` and the certificate scripts | [`adopting-in-a-new-project.md` § 7](adopting-in-a-new-project.md#7-certificates--packaging-windows) | | Bind mount vs tar-pipe, **Dev Drive filter setup**, container reuse, measured timings | [`windows-container-build-performance.md`](windows-container-build-performance.md) | | **The image does not fit on C:** — moving Docker's data-root to the big drive | [`windows-container-build-performance.md`](windows-container-build-performance.md#the-image-does-not-fit-on-c-and-that-is-the-default) | | **The CI prologue on hosted runners** — the Windows cleanup after the pull, the Linux pull first, measured per mode | [`windows-container-build-performance.md`](windows-container-build-performance.md#the-prologue-on-hosted-runners) | | Setting up a brand-new Windows host | [`windows-host-setup.md`](windows-host-setup.md) | | **`git@github.com` auth on Windows** — two OpenSSH agents, why `ssh-add` reaches the wrong one, and the two different causes behind one `Permission denied (publickey)` | [`windows-host-setup.md`](windows-host-setup.md#b0-ssh-agent--one-passphrase-then-never-again) | | The agentic loop's PowerShell module and its API | [`windows-agentic-loop.md`](windows-agentic-loop.md) | | **ghcr.io login failing on Windows** (`--password-stdin`, `credsStore`), `--network=host`, `host.docker.internal` | [`windows-stevedore-and-docker.md`](windows-stevedore-and-docker.md#docker-on-windows-registry-auth-networking-service-recovery) | | Defender performance mode, `ExecutionPolicy`, PATH reload, VS/winget updates, `bcdedit` one-time boot | [`windows-host-setup.md`](windows-host-setup.md#appendix--host-odds-and-ends) | | **General Windows / PowerShell commands** — disk, exe debugging, SSH server, WoL, media capture. Not repo-specific | [`windows-reference.md`](windows-reference.md) | | Build matrix and sanitizer env for the loop | [`agentic-loop-build-matrix.md`](agentic-loop-build-matrix.md) | ### Linux | Looking for | Read | |---|---| | Building in the Linux image, presets, the basics | [`linux-build-basics.md`](linux-build-basics.md) | | Running Linux containers on a Windows host | [`rancher-desktop-linux-containers.md`](rancher-desktop-linux-containers.md) | | **A bind mount that resolves but is empty** — containerd's own mount namespace, Windows vs WSL path form, and why the obvious `/mnt` probe misleads | [`rancher-desktop-linux-containers.md`](rancher-desktop-linux-containers.md#an-empty-mount-is-not-a-missing-drive) | | **Setting up WSL2 itself**: store-less install, `wsl.conf` interop, VHD reclaim, `usbipd` passthrough | [`rancher-desktop-linux-containers.md`](rancher-desktop-linux-containers.md#setting-up-wsl2-itself) | | **A named volume that is silently a directory** — `-v name:/path` is a bind under Windows nerdctl; use the long `--mount type=volume` form | [`rancher-desktop-linux-containers.md`](rancher-desktop-linux-containers.md#-v-namepath-is-a-bind-under-windows-nerdctl) | | **Running an arm64 container locally** — Rancher's VM ships no emulators, so `binfmt` must be registered once per VM boot | [`rancher-desktop-linux-containers.md`](rancher-desktop-linux-containers.md#registering-arm64-emulation-in-ranchers-vm-per-vm-boot) | | **flatpak/AppImage fail on emulated arm64** — bubblewrap's user namespace and static-PIE loading, neither of which `qemu-user` carries | [`rancher-desktop-linux-containers.md`](rancher-desktop-linux-containers.md#emulated-arm64-cannot-run-bubblewrap-or-static-pie) | | Cross-compilation chain and its stages | [`linux-cross-builds.md`](linux-cross-builds.md) | | **Vulkan SDK on foreign arches** — LunarG ships x86_64 only, so arm64/riscv64 are cross-built; what the target prefix contains, why it used to hold two binaries, and how the cross set grew to the vendor's own 24 components (VK2, VK4) | [`vulkan-foreign-arch-sdk.md`](vulkan-foreign-arch-sdk.md) | | **Artifact-copy completeness** — why a built component can vanish between the build stage and `:latest` (Flutter, ArmNN), and the gate + manifest + smoke that prevent it | [`artifact-copy-completeness.md`](artifact-copy-completeness.md) | | Failure classes seen in cross builds | [`cross-build-verification.md`](cross-build-verification.md) | | **GCC sanitizers in the Linux image** — which GCC ships libsanitizer on each arch, the three gates, and why a sanitized binary runs only natively | [`cross-build-verification.md`](cross-build-verification.md#the-native-gcc-ships-libsanitizer) | | **What `:latest` promises a consuming repo** — the cache/rustup/ANDROID_HOME/`/opt/flutter`-ownership contract, its acceptance check, and the per-arch exemption table | [`consumer-image-contract.md`](consumer-image-contract.md) | | **onnxruntime-genai on riscv64** (GEN1) — the self-built lane, its upstream patch, the `GENAI_ALLOW_RISCV64` escape hatch, the four-tier smoke, and the 2026-09-03 measurement that closed it | [`gen1-riscv64-genai.md`](gen1-riscv64-genai.md) | | **QNN / QAIRT on Linux** — the arm64-only opt-in lane: staging the login-gated SDK, the `QAIRT_HEADERS_DIR` trap that must name the dir *holding* `Qnn*.h`, upstream's unhashed 1.5 GB download, and which framework switches are real | [`qnn-linux.md`](qnn-linux.md) | | **riscv64 venv parity** — the `/opt/venv` package set measured on the shipped images, and what riscv64 carries that the other arches do not | [`riscv64-venv-parity.md`](riscv64-venv-parity.md) | | **Prepared upstream submissions** — the artefacts too big to inline in the register, and the verification behind them | [`upstream/README.md`](upstream/README.md) | | **Which local patches to send upstream** — every third-party source change the *Linux* chain carries, graded by how much work stands between it and a merge request. The Windows half is [`upstream-windows-patches.md`](upstream-windows-patches.md) | [`upstreamable-patches.md`](upstreamable-patches.md) | | **riscv64 builds at RVA23 (with vector)** — why enabling RVV costs no compatibility, why `rva23u64_zifencei` and not `rv64gcv`, and the four consumers that need more than `-march` | [`riscv64-rva23-baseline.md`](riscv64-rva23-baseline.md) | | **riscv64 consumer lanes** (CON48) — cross-build on the amd64 runner, run the tests under QEMU: the sysroot from the image's riscv64 child, the distro clang, the QEMU CPU model, and the arch-specific variables the lane overrides | [`riscv64-cross-test-lanes.md`](riscv64-cross-test-lanes.md) | | **IREE's two-stage cross build** — why the host stage runs COMPILER=ON in the default (runtime-only target) configuration, the three tools it must install, and the WERROR / OUTPUT_FORMAT_C flags stage 2 requires | [`iree-two-stage-build.md`](iree-two-stage-build.md) | | CUDA / ROCm / accelerator image variants | [`linux-accelerator-images.md`](linux-accelerator-images.md) | | **NVIDIA on arm64 (SBSA)**: building natively on an arm64 host, and running the image on a Jetson | [`linux-accelerator-images.md`](linux-accelerator-images.md#nvidia-on-arm64-sbsa-one-image-for-servers-and-jetson) | | **DeepStream** in the nvidia variant: what ships, TensorRT 10 beside 11, the gates, the licence decision | [`linux-accelerator-images.md`](linux-accelerator-images.md#deepstream-nvidia-variant) | | **Setting up a Linux build host**: GPU drivers, CUDA, runtime config, performance mode, GRUB recovery | [`linux-host-setup.md`](linux-host-setup.md) | | **General Linux commands** — disk, text/log filtering, users, networking, SSH, media/OCR, remote desktop, git. Not repo-specific | [`linux-reference.md`](linux-reference.md) | | Hailo `.hef` compilation and Jetson board procedures | [`linux-accelerator-images.md`](linux-accelerator-images.md#edge-accelerators) | | **Hailo in the image chain** — plan, upstream matrix (device families and branches, licences, TAPPAS's GStreamer gap) and the stage/gate design | [`hailo-support.md`](hailo-support.md) | | Raw `gst-launch-1.0` pipelines, and building GStreamer from source on a device | [`runtime-services.md`](runtime-services.md#raw-gst-launch-10-pipelines-debugging-below-the-app) | | Removing a stale GStreamer source install; Android GStreamer (built with cerbero; the prebuilt tarball is the fallback) | [`runtime-services.md`](runtime-services.md#removing-a-previous-source-install) | | Detached containers, tmux, and bind-mount file ownership | [`rancher-desktop-linux-containers.md`](rancher-desktop-linux-containers.md#long-running-work-detached-containers--tmux) | | Slow `apt update`, unattended-upgrade policy, excluding Docker from auto-upgrades | [`linux-host-setup.md`](linux-host-setup.md#phase-e--package-sources-and-automatic-updates) | | What filled the disk, and `/tmp` exhaustion during a build | [`linux-host-setup.md`](linux-host-setup.md#finding-what-filled-the-disk) | | **UFW dropping container traffic**, host suspend during a build, APT pinning | [`linux-host-setup.md`](linux-host-setup.md#b6-ufw-silently-breaks-container-networking) | | **Installing the container stack rootless** — the nerdctl-full bundle into `$HOME/.local` with no sudo, repointing the systemd --user units, and the CNI plugins rootless nerdctl looks for under the prefix | [`linux-host-setup.md`](linux-host-setup.md#b3c-install-rootless-into-homelocal-no-sudo) | | **Installing a Python CLI tool on a riscv64 host** (no wheels → source builds: Rust target, OpenSSL/libffi headers, dropping optional accelerators). Worked example: Mistral Vibe | [`linux-host-setup.md`](linux-host-setup.md#d4-python-cli-tools-that-build-from-source-on-riscv64) | ### Build, CI and tooling | Looking for | Read | |---|---| | **What is cached where**, and which tier a miss came from | [`build-cache-tiers.md`](build-cache-tiers.md) | | **Wiring a new project to this repo** — start here | [`adopting-in-a-new-project.md`](adopting-in-a-new-project.md) | | **A Linux package that runs outside the image** — `kataglyphis_install_linux_closure`, what still needs glibc 2.43, and the `clean-host-package-check` action on `ubuntu-26.04` | [`linux-build-basics.md`](linux-build-basics.md#linux-packages-that-run-outside-the-image) | | **A Python app as a relocatable folder** — the input to its zip/MSI/MSIX/tar.gz/deb/AppImage packages: `packaging/app.json`, both builders, the import walk + G6 + self-test gates, and why Windows ships the image's OpenCV instead of PyPI's | [`python-app-bundles.md`](python-app-bundles.md) | | Python CI: the shared lanes, and the three `uv` traps (`--all-extras` vs declared conflicts, `UV_PYTHON` beating the venv, a synced venv's ONNX Runtime reconciled onto the chain wheels), and GIL vs free-threaded legs in one container | [`python-ci.md`](python-ci.md) | | Code quality: C++ formatter guidance + this repo's own gates (design notes per slug) | [`code-quality-tooling.md`](code-quality-tooling.md) | | Which preflight gate has a test, a mutation, or neither — the derived table | [`code-quality-gates.md`](code-quality-gates.md) | | Which repos consume this hub, and which entry points they actually reach | [`consumer-inventory.md`](consumer-inventory.md) | | **Upgrading dependencies** — Renovate as a local CLI, why `--apply` refuses some submodules, and lock file maintenance (every lock to its newest in-range release) | [`dependency-updates.md`](dependency-updates.md) | | Compiling a Slang shader tree to SPIR-V and WGSL | [`slang-shader-compilation.md`](slang-shader-compilation.md) | | The sourceable cores in `linux/scripts/lib/` — cmake-build, ctest-run, docs-build, app-packaging, compiler-llvm-tools, linker-select (`KATAGLYPHIS_LINKER`, lld or mold) and the rest — and the consumer entry points beside them (`run-lint-gates.sh`, `run-in-ci-image.sh`, `ci-image-ref.sh`) | [`shared-script-libraries.md`](shared-script-libraries.md) | | Job counts, per-job memory, why a build got OOM-killed | [`build-parallelism-memory-tuning.md`](build-parallelism-memory-tuning.md) | | Watching resource use during a build | [`build-resource-monitoring.md`](build-resource-monitoring.md) | | **Giving a build a credential** without baking it into a layer | [`build-secrets.md`](build-secrets.md) | | Finding the real error in a large build log | [`build-resource-monitoring.md`](build-resource-monitoring.md#mining-a-build-log-for-the-actual-failure) | | Capping CPU so a build leaves the host usable | [`build-parallelism-memory-tuning.md`](build-parallelism-memory-tuning.md#capping-cpu-so-the-host-stays-usable) | | Building on an SBC or small VM: swap, zram, forcing `-j1` | [`build-parallelism-memory-tuning.md`](build-parallelism-memory-tuning.md#the-other-end-building-on-a-memory-constrained-host) | | **Every checkout on its branch tip** — the superproject and every submodule, recursively, fast-forward only (`git-sync-branches.sh`) | [`adopting-in-a-new-project.md`](adopting-in-a-new-project.md#putting-every-checkout-on-its-branch) | | **Submodule conflicts on merge**, bumping the pin, shallow fetches | [`adopting-in-a-new-project.md`](adopting-in-a-new-project.md#submodule-maintenance) | | Broken submodule checkout, `core.longpaths`, `git clean -fdx`, ssh-agent on Windows | [`adopting-in-a-new-project.md`](adopting-in-a-new-project.md#recovering-a-broken-submodule-checkout) | | **Branches, CI rounds and releases** — `develop` runs Linux x64 on every push, `[ci ]` or a dispatch runs the rest, `main` moves by fast-forward to a fully green commit and every push to it releases only when every lane is green | [`branch-and-release-strategy.md`](branch-and-release-strategy.md) | | Which CI lanes run when, per repository, while the repositories move to that rule; what is still path-filtered or gated | [`ci-build-triggers.md`](ci-build-triggers.md) | | **Publishing docs or a site over FTP** — the one composite action, its pin, and why a failed publish always fails the job | [`ftp-deploys.md`](ftp-deploys.md) | | Reading pipeline status from the terminal | [`github-cli-pipeline-monitoring.md`](github-cli-pipeline-monitoring.md) | | **Mistral Vibe + GLM-5.2** — setting up the Z.ai GLM-5.2 coding agent (CLI + VS Code) on Mistral La Plateforme | [`mistral-vibe-glm-setup.md`](mistral-vibe-glm-setup.md) | | **GenieX on Snapdragon** — on-device OpenAI-compatible server (Adreno GPU / Hexagon NPU), serving a coding agent inside WSL2 | [`geniex-local-ai-setup.md`](geniex-local-ai-setup.md) | | **The LLM gateway** — APISIX in front of the GenieX lanes: aliases, per-client keys, the GenieX rules (tools prompt, overflow fallback, T=0, timeouts), `serve-stack.sh`, the e2e test and the acceptance procedure | [llm-stack README, Gateway](../linux/llm-stack/README.md#gateway) | | **Benchmarking an LLM endpoint** — speed *and* correctness, TTFT vs decode, concurrent lanes, named backends (`ollama`, `geniex-*`), and the capability benchmarks (coding, tool calling, the agent loop, embeddings, sweeps). **Lives in OrchestrANT now**: the `orchestrant.benchmark` runner plus `benchmarks/` (tools, viewer, tracked results, roadmap and the 2026-09-05 panel review) | [OrchestrANT benchmarks](https://github.com/Kataglyphis/OrchestrANT/tree/main/benchmarks) | | **Connecting a model to the NAS** (Word/Excel/PDF/images) — why the Hexagon NPU cannot read a page, the OCR-model shortlist and file-type routing, the `bench_docs.py` bake-off design, and the machine-topology corrections. **Lives in OrchestrANT now**, beside the census tool and its tests | [OrchestrANT benchmarks](https://github.com/Kataglyphis/OrchestrANT/tree/main/benchmarks/docs/nas-document-ai.md) | | **A model answers fast but wrong** (whitespace, random multilingual tokens) — GGUF tensor types, the sub-4-bit i-quant bug | [`geniex-local-ai-setup.md` § Debugged: i-quants](geniex-local-ai-setup.md), tool: [inspect_gguf.py](https://github.com/Kataglyphis/OrchestrANT/tree/main/benchmarks/inspect_gguf.py) | ### Also owned here, not under `docs/` | Looking for | Where | |---|---| | The five shell-safety bug classes (all found live) | [`../AGENTS.md`](../AGENTS.md) § *Shell safety conventions* | | Reusable PowerShell modules | `windows/scripts/modules/` — resolved via the consumer's `Resolve-BuildModule.ps1` | | Which hub function to call before writing your own helper: container, MSIX/MSI, config, build-step, logging, cargo, packaging, CI | [`adopting-in-a-new-project.md` § *Reach for these before writing a helper*](adopting-in-a-new-project.md#reach-for-these-before-writing-a-helper) | | Reusable bash libraries | `linux/scripts/lib/` and `linux/scripts/01-core/` | | Generic Python CI drivers | `linux/scripts/02-toolchain/python/ci_*.sh` | | CI composite actions | [`../.github/actions/README.md`](../.github/actions/README.md) | | Where a repo's Sphinx sources live | `docs/source/` in every consumer (`docs-build.sh`'s default); `docs/conf.py` beside the pages here and in DocumANTation — see [`adopting-in-a-new-project.md` § 8](adopting-in-a-new-project.md) | | Canonical `.clang-format`, `.clang-tidy`, `.cmake-format.yaml`, `gcovr.cfg`, `.pre-commit-config.yaml`, and the Dart `analysis_options.yaml` consumers `include:` by reference | [`../shared/config/README.md`](../shared/config/README.md) | | Copy-and-edit templates (`Resolve-BuildModule.ps1`, `antfrastructure.sh`, the `renovate-local.sh` wrapper, `AGENTS.md` skeleton, agentic-loop config), and the consumer pre-commit hook used by reference | [`../shared/windows/templates/`](../shared/windows/templates/README.md), [`../shared/linux/templates/`](../shared/linux/templates/README.md), `../shared/templates/`, `../shared/agentic-loop/templates/` | | Reusable CI workflows (`workflow_call`) — the Python lanes, the Windows container lane (x64, and the arm64 cross lanes with their `windows-11-arm` run job), the docs build, the lint aggregator, the submodule-pin suite | [`../.github/workflows/python-ci-linux.yml`](../.github/workflows/python-ci-linux.yml), [`../.github/workflows/python-ci-windows.yml`](../.github/workflows/python-ci-windows.yml), [`../.github/workflows/container-ci-windows.yml`](../.github/workflows/container-ci-windows.yml), `../.github/workflows/build-docs.yml`, `../.github/workflows/lint-gates.yml`, `../.github/workflows/submodule-pins.yml` | | Who still calls each hub entry point (weekly, every consumer cloned) | [`consumer-inventory.md`](consumer-inventory.md), `../.github/workflows/consumer-inventory.yml` | | The composite actions exercised against themselves — what a green tick does and does not prove | [`../.github/actions/README.md`](../.github/actions/README.md), `../.github/workflows/actions-selftest.yml` | | The submodule-pin invariant as a lane a consumer can `uses:` | [`adopting-in-a-new-project.md` § 9](adopting-in-a-new-project.md), `../.github/workflows/submodule-pins.yml` | | Workflow file and display names across the family (`linux-x64.yml`, `Linux x64 · …`), and the 2026-09-24 rename table | [`adopting-in-a-new-project.md` § Workflow file names and display names](adopting-in-a-new-project.md#workflow-file-names-and-display-names) | | One Linux arch per caller of the Python lane (`arches`) | [`python-ci.md` § One arch per caller](python-ci.md#one-arch-per-caller-the-arches-input) | ### Backlogs, history and archives Everything here is *record*, not instruction. If you find a live rule that exists only in one of these, promote it to its owning page above. | Looking for | Read | What's in it | |---|---|---| | Open refactor work, Linux side | [`refactoring-backlog.md`](refactoring-backlog.md) | | Every open gap in the published images | [`BACKLOG.md`](../BACKLOG.md) | What a consumer lane hits or works around in `:latest`, `:winamd64` and the `:winarm64` bundle, each with its evidence and what closes it, plus what a 2026-09-25 re-measurement closed and what is deliberate. | | What the images deliberately leave out, and gaps checked closed | [`image-decisions.md`](image-decisions.md) | The decided non-gaps (no GTK4 dev headers, CPython 3.14 only, the CUDA arch set, riscv64 omissions …) and the 2026-09-25 checks that closed stale consumer notes; not a task list | | What to read in a running chain's log | [`build-watch-list.md`](build-watch-list.md) | The 2026-09-05 wave's closure changes, grouped by stage: the exact log line that proves each one worked and the exact line that means it failed, plus the read-only probes to run on the shipped bytes afterwards. Written because eleven backlog entries closed on static proof and a first rebuild attempt still found two build-killing bugs. | | Open refactor work, Windows chain | [`windows-refactor-backlog.md`](windows-refactor-backlog.md) | | What changed and why, current wave | [`../CHANGELOG.md`](../CHANGELOG.md) | | Changelog entries 2026-10-08 … 2026-10-12 | [`changelog-archive-2026-10-12.md`](changelog-archive-2026-10-12.md) | CON90's Python 3.15 and the Windows chain following it (CON91), pinned pip installs and clang-cl sdists there (CON88, CON89, CON93), LiteRT-LM's checked bazel tools, GStreamer through sccache. | | Changelog entries 2026-10-01 … 2026-10-07 | [`changelog-archive-2026-10-07.md`](changelog-archive-2026-10-07.md) | The free-threaded CPython and its cp314t wheel twins (CON66, CON74, CON79), ROCm 10.1 (CON73), the Renovate bumps (CON72), `git-sync-branches.sh`, DeepStream in the nvidia builds (CON42). | | Changelog entries 2026-09-22 … 2026-09-30 | [`changelog-archive-2026-09-30.md`](changelog-archive-2026-09-30.md) | The Windows arm64 cross lanes and their DLL closures, the ORT census, the ROCm and MIGraphX Windows builds, compiler caches kept across Linux runs, one-line comments in every language. | | Changelog entries 2026-09-08 … 2026-09-21 | [`changelog-archive-2026-09-21.md`](changelog-archive-2026-09-21.md) | | Changelog entries 2026-08-29 … 2026-09-07 | [`changelog-archive-2026-09-07.md`](changelog-archive-2026-09-07.md) | The 2026-09-07 backlog-audit day, the 2026-09-03 reconstruction, the GenieX/QNN rounds and everything back to 2026-08-29. | | Changelog entries 2026-08-14 … 2026-08-28 | [`changelog-archive-2026-08-28.md`](changelog-archive-2026-08-28.md) | | Changelog entries through 2026-08-13 | [`changelog-archive-2026-08-13.md`](changelog-archive-2026-08-13.md) | | Settled Windows backlog items | [`2026-08-11`](windows-backlog-archive-2026-08-11.md) · [`2026-08-17`](windows-backlog-archive-2026-08-17.md) · [`2026-08-21`](windows-backlog-archive-2026-08-21.md) · [`2026-08-26`](windows-backlog-archive-2026-08-26.md) · [`2026-08-31`](windows-backlog-archive-2026-08-31.md) · [`2026-09-17`](windows-backlog-archive-2026-09-17.md) | | Settled Linux refactor items | [`refactoring-backlog-archive-2026-08-10.md`](refactoring-backlog-archive-2026-08-10.md) | | Closed Linux refactor items (2026-08-27) | [`refactoring-backlog-archive-2026-08-27.md`](refactoring-backlog-archive-2026-08-27.md) | Everything the backlog closed up to 2026-08-27, including the entries that were REFUTED or RETRACTED rather than fixed. | | Closed Linux refactor items (2026-08-30) | [`refactoring-backlog-archive-2026-08-30.md`](refactoring-backlog-archive-2026-08-30.md) | The OpenCV-sccache REFUTATION (pre-UDS wrong-server bug, not OpenCV-specific) and the F2 one-resolver cache consolidation. | | Closed Linux refactor items (2026-08-31) | [`refactoring-backlog-archive-2026-08-31.md`](refactoring-backlog-archive-2026-08-31.md) | The A1 closure window: the logging.sh ERR-trap bug, the complexity queue, the modules.sh dir-walker REFUTATION, the IREE toothless-gate finding, and GEN1 (riscv64 GenAI built + wired ON). | | Closed Linux refactor items (2026-09-02) | [`refactoring-backlog-archive-2026-09-02.md`](refactoring-backlog-archive-2026-09-02.md) | The RVA23 rebuild window: libyuv's RVV rows, the cache-key blast radius, the duplication baseline review, and the riscv64 venv gate's dangling ORT edges. | | Closed Linux refactor items (2026-09-03) | [`refactoring-backlog-archive-2026-09-03.md`](refactoring-backlog-archive-2026-09-03.md) | A1 (riscv64 GenAI token sanity) and A2 (QNN fan-out) closed by real builds; the WA–WJ and XK–XR rounds | | Closed Linux refactor items (2026-09-07) | [`refactoring-backlog-archive-2026-09-07.md`](refactoring-backlog-archive-2026-09-07.md) | The thirteen the 2026-09-05 chain and the wave after it closed: CC1/CL1/VK1/AB1/APP1 with what the chain measured on the shipped bytes, then CS1 (owner decision), VK3, CS2, CS3, DISK3, R1, YB and F3 -- all landed on an idle tree and none proven by a build. | | Closed Linux refactor items (2026-09-09) | [`refactoring-backlog-archive-2026-09-09.md`](refactoring-backlog-archive-2026-09-09.md) | VK2 closed by two sdk runs: 20/20 Vulkan cross-components on both foreign arches, verified on the shipped bytes, plus the host/target apt pocket asymmetry that kept riscv64 at 19/20. | | Closed Linux refactor items (2026-09-17) | [`refactoring-backlog-archive-2026-09-17.md`](refactoring-backlog-archive-2026-09-17.md) | AS1's three apt-source neighbours, CON1/CON2/CON3/CON5/CON6, the two F1 seams and the full F4 27-extraction window — all landed on an idle tree, none proven by a build — plus the Windows-Python extent-gate quirk recorded not fixed. | | Upstream submissions and issue drafts | [`upstream/hcsshim-lost-shutdown-notification-issue.md`](upstream/hcsshim-lost-shutdown-notification-issue.md), [`upstream/windows-containers-lsm-session-event-hang.md`](upstream/windows-containers-lsm-session-event-hang.md), [`../windows/upstream/README.md`](../windows/upstream/README.md) | | The libstdc++ `-nostdinc++` note | [`upstream-libstdcxx-c++23-nostdinc++.md`](upstream-libstdcxx-c++23-nostdinc++.md) | ## Where does a piece of knowledge belong? (from AGENTS.md) Moved out of `AGENTS.md` on 2026-09-15 (owner decision D10), unedited except for this heading, the relative links and the repository count. The RULES stayed there; this is the reference behind them. The reuse rules below are about code. The same discipline applies to **what you write down**, and one question decides it: > **Would this still be true in a different project?** - **Yes** → it belongs here, and the consumer LINKS to it. - **No** → it belongs in the consumer. Most topics split down the middle. "Allow the `bindFlt`/`wcifs` filters on a Dev Drive" is ours; "Dart's `copySync` fails on a bind mount" is OmniAccelerANT's, because it only matters for a Flutter app. **Link rather than restate** — restating has produced three broken copies of one command before (the 2026-08-11 Dev Drive filter incident; the story lives in [`docs/INDEX.md`](INDEX.md)). [`docs/INDEX.md`](INDEX.md) maps topic → owning document. Consumers link one hop through it, so reorganising docs here means editing that page instead of hunting links across every consumer repository. [`shared/templates/AGENTS.md.template`](../shared/templates/README.md) is the consumer-side skeleton that keeps the split visible. One caution against automating this: a keyword check ("this consumer doc mentions wcifs") cannot tell *restating* from *applying*. OmniAccelerANT's AddressSanitizer section legitimately discusses image-level runtimes, because which ASan runtime a Flutter/COM app can survive is a property of that app. A human has to read it. ## Documentation maintenance, as AGENTS.md carried it Moved out of `AGENTS.md` on 2026-09-15 (owner decision D10), unedited except for this heading and the relative links. The RULES stayed there; this is the reference behind them. - **Pre-commit hooks:** Run **`make hooks`** once after clone; it points `core.hooksPath` at `linux/host-config/git-hooks`. See § Validation for what it runs. - **Four gates guard the docs; none of them is optional.** They exist because this tree lost a licence page, a doc index and ~50 cross-references to silent drift on a single day. Run them with `PREFLIGHT_ONLY=doc-links,doc-dupes,sbom,version-snapshot bash linux/scripts/preflight.sh`. - `doc-links` — every relative link, deep-link anchor, `file.md § Heading` prose reference, and index coverage against BOTH `docs/INDEX.md` and the Sphinx toctree. **Rename a heading and this fails**, which is the point. - `doc-dupes` — a passage copied into a second page. Deliberate rule-page / mechanism-page overlap is budgeted in `docs/scripts/doc-dupes.allow`, which also fails when an entry goes stale, so it cannot decay into a blanket exemption. **Do not add an entry to silence a finding**; give the passage one owner and link to it. `docs/INDEX.md` decides which page owns what. - `sbom` / `version-snapshot` — the generated licence pages and the curated SBOM must match `deps.json` + `versions.env`. - **Adding a dependency is a docs change.** A new component needs an entry in `docs/deps/deps.json` with an `spdx` id, and — if that licence is copyleft — a `source` block, or the build fails. If this repo patches it, a `modified` marker too. The procedure, schema and worked examples are [`docs/third-party-licenses.md`](third-party-licenses.md) § Maintaining this list. Regenerate with `sync_versions.py --write` and `generate_sbom.py --write`. - **Never hand-edit a generated block.** The licence tables, the version snapshot and `docs/deps/sbom-curated.spdx.json` are all rewritten from `deps.json` + `versions.env`; edits between the `generated:` markers are lost on the next run and the gate will say so. - If Dockerfiles or Linux helpers change, update `docs/linux-cross-builds.md`, `docs/linux-build-basics.md`, `docs/project-info.md`. - If Windows Dockerfiles/scripts change, update `docs/windows-builds.md`. - If version defaults change, run `python3 docs/scripts/sync_versions.py --write` then `python3 docs/scripts/generate-website-licenses.py --write`. - The canonical `custom.css` lives in the DocumANTation submodule — change it there and commit in that repo, then `cd docs && make html` to verify. ## If you are about to write a procedure in a consumer repo Check this page first. If the topic is listed, link instead — one sentence of orientation plus the link, then whatever is genuinely specific to your project. BeschleunigerBallett's `AGENTS.md`, in its submodule-pins invariant section, does this well: it states the one project-specific coupling (FUZZTEST and the Abseil pin move together), links the shared suite for the mechanism, and keeps only its own measured numbers locally.