Engineering Handbook

• Type: Index
• Status: Current
• Scope: nixos-config repository
• Canonical sources: AGENTS.md, README.md, flake.nix, repository layout, justfiles/, tests, and CI workflows
• Last verified: Source commit 556df88494686003b1c4f20c8e0b99b5afc16a6e (2026-09-12)
• Review triggers: Changes to repository boundaries, module composition, development workflow, validation, CI, deployment, or documentation maintenance

The Engineering Handbook explains how to change the repository safely. It is separate from the Operations section: engineering changes the declared system; operations runs and recovers the deployed system.

Current pages

• Repository Structure and Import Chain — where evaluation begins, how host and shared imports compose, and how Home Manager joins each registered target.
• Configuration Ownership Boundaries — choose the natural owner for a capability, composition, host value, account privilege, user setting, or package helper.
• Adding Packages and Flake Inputs — choose package scope and source, classify new root inputs for guarded updates, and verify actual consumer builds.
• Adding a Module or Profile — choose an import-to-enable or option-gated interface, wire intended consumers, and validate the selected host closures.
• Adding a Host — prepare the host composition, register the shared builder, update input/secret policy, and hand off to provisioning.
• Adding or Migrating a Service — choose placement, declare runtime and fleet integration, validate the target, and hand live moves to the cutover runbook.
• Testing and CI Contracts — select local gates, understand current Forgejo coverage, and record live evidence.
• Secrets Implementation Conventions — choose file/recipient scope and deliver credentials at runtime.
• Documentation Maintenance — verify source, update the owning page, review links and provenance, and publish separately.

The superseded workflows and quick-reference chapters remain in wiki Git history. The current change contract is in AGENTS.md and the pages above; the handbook rebuild is tracked by issue #222.