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
Wiring a new project to this repo	adopting-in-a-new-project.md
What is published, what is in it, the feature matrix	overview.md
Prerequisites, tests, roadmap, contribution, contact	project-info.md
Why the pack is 154 MB, what is large, and why history is not rewritten	project-info.md § Repository size
Licences of bundled software, what each one obliges this project to do, and the corresponding source for copyleft components	third-party-licenses.md
Known vulnerabilities — running grype, and why the raw count misleads on these images	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 — the curated half (source-built components, which no image scanner can see)	deps/sbom-curated.spdx.json, generated by scripts/generate_sbom.py
SBOM — the scanner half (apt/pip/npm, thousands of packages)	../.github/workflows/sbom.yml runs syft against the published image
Rules an automated agent must follow	../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

Windows

Looking for	Read
The image itself: what is installed, entrypoint, known traps	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
Rules you must not regress when editing the Windows chain (49, grouped)	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
CPU/memory envelope, the sccache wiring, GPU in containers, the 125-layer budget	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
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, § 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
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
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
The home network’s addresses: placeholders in docs and examples, the real values in the gitignored site.local.env	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
Stevedore post-install fixes, ghcr login, service recovery	windows-stevedore-and-docker.md
Open refactor work on the Windows chain	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
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
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
Signing a consumer’s MSIX — Invoke-MsixPackage -Sign -SigningRoot <repo root> and the certificate scripts	adopting-in-a-new-project.md § 7
Bind mount vs tar-pipe, Dev Drive filter setup, container reuse, measured timings	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
The CI prologue on hosted runners — the Windows cleanup after the pull, the Linux pull first, measured per mode	windows-container-build-performance.md
Setting up a brand-new Windows host	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
The agentic loop’s PowerShell module and its API	windows-agentic-loop.md
ghcr.io login failing on Windows (--password-stdin, credsStore), --network=host, host.docker.internal	windows-stevedore-and-docker.md
Defender performance mode, ExecutionPolicy, PATH reload, VS/winget updates, bcdedit one-time boot	windows-host-setup.md
General Windows / PowerShell commands — disk, exe debugging, SSH server, WoL, media capture. Not repo-specific	windows-reference.md
Build matrix and sanitizer env for the loop	agentic-loop-build-matrix.md

Linux

Looking for	Read
Building in the Linux image, presets, the basics	linux-build-basics.md
Running Linux containers on a Windows host	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
Setting up WSL2 itself: store-less install, wsl.conf interop, VHD reclaim, usbipd passthrough	rancher-desktop-linux-containers.md
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
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
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
Cross-compilation chain and its stages	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
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
Failure classes seen in cross builds	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
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
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
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
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
Prepared upstream submissions — the artefacts too big to inline in the register, and the verification behind them	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	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 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
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
CUDA / ROCm / accelerator image variants	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
DeepStream in the nvidia variant: what ships, TensorRT 10 beside 11, the gates, the licence decision	linux-accelerator-images.md
Setting up a Linux build host: GPU drivers, CUDA, runtime config, performance mode, GRUB recovery	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
Hailo .hef compilation and Jetson board procedures	linux-accelerator-images.md
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
Raw gst-launch-1.0 pipelines, and building GStreamer from source on a device	runtime-services.md
Removing a stale GStreamer source install; Android GStreamer (built with cerbero; the prebuilt tarball is the fallback)	runtime-services.md
Detached containers, tmux, and bind-mount file ownership	rancher-desktop-linux-containers.md
Slow apt update, unattended-upgrade policy, excluding Docker from auto-upgrades	linux-host-setup.md
What filled the disk, and /tmp exhaustion during a build	linux-host-setup.md
UFW dropping container traffic, host suspend during a build, APT pinning	linux-host-setup.md
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
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

Build, CI and tooling

Looking for	Read
What is cached where, and which tier a miss came from	build-cache-tiers.md
Wiring a new project to this repo — start here	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
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 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
Code quality: C++ formatter guidance + this repo’s own gates (design notes per slug)	code-quality-tooling.md
Which preflight gate has a test, a mutation, or neither — the derived table	code-quality-gates.md
Which repos consume this hub, and which entry points they actually reach	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
Compiling a Slang shader tree to SPIR-V and WGSL	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
Job counts, per-job memory, why a build got OOM-killed	build-parallelism-memory-tuning.md
Watching resource use during a build	build-resource-monitoring.md
Giving a build a credential without baking it into a layer	build-secrets.md
Finding the real error in a large build log	build-resource-monitoring.md
Capping CPU so a build leaves the host usable	build-parallelism-memory-tuning.md
Building on an SBC or small VM: swap, zram, forcing -j1	build-parallelism-memory-tuning.md
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
Submodule conflicts on merge, bumping the pin, shallow fetches	adopting-in-a-new-project.md
Broken submodule checkout, core.longpaths, git clean -fdx, ssh-agent on Windows	adopting-in-a-new-project.md
Branches, CI rounds and releases — develop runs Linux x64 on every push, [ci <lane>] 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
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
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
Reading pipeline status from the terminal	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
GenieX on Snapdragon — on-device OpenAI-compatible server (Adreno GPU / Hexagon NPU), serving a coding agent inside WSL2	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
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
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
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, tool: inspect_gguf.py

Also owned here, not under docs/

Looking for	Where
The five shell-safety bug classes (all found live)	../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
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
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
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
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/linux/templates/, ../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-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, ../.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/workflows/actions-selftest.yml
The submodule-pin invariant as a lane a consumer can uses:	adopting-in-a-new-project.md § 9, ../.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
One Linux arch per caller of the Python lane (arches)	python-ci.md § One arch per caller

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
Every open gap in the published images	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	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	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
What changed and why, current wave	../CHANGELOG.md
Changelog entries 2026-10-08 … 2026-10-12	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	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	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 entries 2026-08-29 … 2026-09-07	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 entries through 2026-08-13	changelog-archive-2026-08-13.md
Settled Windows backlog items	2026-08-11 · 2026-08-17 · 2026-08-21 · 2026-08-26 · 2026-08-31 · 2026-09-17
Settled Linux refactor items	refactoring-backlog-archive-2026-08-10.md
Closed Linux refactor items (2026-08-27)	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	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	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	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	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	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	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	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/windows-containers-lsm-session-event-hang.md, ../windows/upstream/README.md
The libstdc++ -nostdinc++ note	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).

docs/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 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 § 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.