Explanation¶

Explanation pages are understanding-oriented — the why, not the how. Each one distils one or more decision records into a readable account of a design choice and the reasoning behind it. If you want the how, see How-To Guides or Reference; the exhaustive, dated source material is the decision log.

Pages¶

• Spec-first development — why every change starts as a dated spec, and what that buys.
• The token-input convention — why every credential-needing input defaults to $CI_JOB_TOKEN and never hardcodes a variable name.
• OpenTofu state and caching — OIDC plan/apply, the GitLab-managed HTTP backend, provider and module caching.
• The dev-tools image — why Go/Rust/Svelte components consolidated onto one baked toolchain image instead of installing tools at job time.
• Change-detection — the rules:changes mechanism, its reliability constraints, and why it's default-on everywhere except security.
• Security: always-on — why every security scanner is exempt from change-detection and runs on every MR regardless.
• Release automation — the shape shared by goreleaser, release-plz, tofu-module-publish, and releaser-pleaser, and where they differ.
• Renovate automation — the renovate-self component and the bundled preset that keeps every consumer's component pins current.
• Static sites — zensical-pages and hugo-pages, and why hugo-pages is the one component that deploys on a schedule.
• The Svelte frontend track — embedding a Svelte UI in a Go binary, and the go:generate-vs-svelte-build decision.

The exhaustive, dated source material every page above draws from is the decision log.