NixOS Fleet Knowledge Base

Type: Index

Status: Current

Scope: Fleet and repository

Canonical sources: flake.nix, hosts/, modules/, justfiles/, AGENTS.md, and the section-specific sources named on each page

Last verified: Source commit ef4ae2ce2f1b3fd8fc22262ded9c2374ac78c6ef (2026-09-14); wiki navigation audited 2026-09-14

Review triggers: Changes to the fleet inventory, documentation boundaries, or top-level wiki structure

This wiki is the curated knowledge layer for the nixos-config fleet. It explains what the system is, why important choices were made, how to operate and recover it, how to change it safely, and how its NixOS model works.

The live repository remains authoritative for configuration. Every current page records its own canonical sources, verification revision, and review triggers. A configured service is not automatically a deployed or healthy one.

Choose by intent

Understand the fleet: start with the System Atlas.
Operate or troubleshoot it: use Operations and Runbooks.
Respond to data loss or a failed host: go directly to Full-Host Recovery.
Recover Electra's boot trust or TPM unlock: use Electra Boot-Trust and TPM Recovery.
Edit or rotate encrypted secrets: use Secret Editing and Recipient Rotation.
Investigate an automatic update: use Auto-Update Incident Response.
Move a service or its data: use Service Migration and Cutover.
Package an upstream service independently: use Wrapper-Repository Packaging.
Change the configuration: use the Engineering Handbook.
Find where a file enters a host build: use Repository Structure and Import Chain.
Decide where a change belongs: use Configuration Ownership Boundaries.
Add a package or flake input: use Adding Packages and Flake Inputs.
Add a module or profile: use Adding a Module or Profile.
Add a NixOS host: use Adding a Host, then Host Provisioning for installation.
Add or re-engineer a service: use Adding or Migrating a Service; use the cutover runbook for a live move.
Choose validation for a change: use Testing and CI Contracts.
Add a secret consumer: use Secrets Implementation Conventions.
Maintain the wiki: use Documentation Maintenance.
Learn NixOS through this repository: follow the NixOS Learning Path.
Take a first source-code tour: start with Guided Repository Tour.
Understand why a constraint exists: consult Architecture Decisions.
Plan or review work: use Start Here and Governance and the live Forgejo issues and milestones.

Knowledge architecture

Section	Question it answers
00 — Start Here and Governance	Where does information and work belong?
10 — System Atlas	What exists, where does it run, and how is it connected?
20 — Architecture Decisions	Why were consequential choices made?
30 — Operations and Runbooks	How is the fleet operated, repaired, or recovered?
40 — Engineering Handbook	How is the repository changed safely?
50 — NixOS Learning Path	How do Nix and NixOS concepts appear here?
90 — Historical Material	Which superseded records still have lasting value?

Source-of-truth rule

The repository, wiki, Forgejo, BookStack, and Engram have deliberately different responsibilities. See Documentation Map and Scope before adding or moving material. See Documentation Standards for page types, metadata, naming, linking, and templates.

Cutover record

The five-phase rebuild is tracked under the Forgejo milestone Wiki Knowledge Architecture Rebuild:

The former manual chapters have been removed from current navigation after their durable material was placed in the sections above. Git history preserves retired pages. The only deliberately visible legacy page is the Electra Secure Boot hardening record, clearly labelled historical. Final audit and source-documentation alignment are recorded in issue #223 and the merged source-documentation MR #229.