zig-build-system-complexity

# Zig Build System Complexity ## Operating Mode Use this skill when the build graph is part of the product contract. First prove the active toolchain, pinned version, and visible build surface: ```bash zig version zig env zig build --help test -f build.zig.zon && sed -n '1,180p' build.zig.zon ``` As of 2026-05-13, Zig `0.16.0` is the latest tagged release. Orca-style repos may still be pinned to `0.15.2`; do not silently rewrite build APIs for a newer Zig unless the task is an upgrade. ## Build Graph Rules - Treat `build.zig` as a DAG, not as an imperative shell script. Model compile, run, install, check, test, fuzz, bench, package, and generated-file steps explicitly. - Keep host tools, target artifacts, generated sources, and installed artifacts separate. A host tool may run during the build; a target binary may only run when it matches the host. - Prefer named steps with clear descriptions: `check`, `test`, `bench`, `release`, `docs`, `package`, `smoke`. - Use `check` steps that compile without installing artifacts so editors and CI can report errors quickly. - Run `zig build --help` after build changes; it is the user-facing contract for options and steps. ## Package Surface - Treat `build.zig.zon` as the source of package truth: `name`, `version`, `minimum_zig_version`, `dependencies`, `paths`, and fingerprints/hashes. - Keep `paths` strict. Include source, docs, examples, schemas, generated assets, and package scripts that consumers need; exclude caches, local s...