Skip to content

Coverage TODO

Living checklist and remaining-work ground truth. Historical campaign phases (0–4, 6, 7) are closed; ongoing work is Phase 5.1 cadence via release-checklist.md.

Meta truth snapshot (2026-08-01 — post gold-thicken): leaf articles mostly status: complete (quality audit); intentional drafts: self-healing-config-mesh + living sources.md; ~49 folder READMEs status: index (includes 16-configuration-examples). Relative .md links: 0 broken in repo root (see Audit hook). Site: zemdregon.github.io/nix-docs. Active: Phase 5.1 cadence (release-checklist.md). Status lives in YAML frontmatter.

Weeks below are historical draft-campaign checkoffs. Phase 7 batches A–L are closed (see below). Track ongoing work under Remaining work.

Structure / Week 0 (bootstrap)

  • [x] Numbered domain directories and stub leaves
  • [x] Root map and conventions.md
  • [x] 00-roadmap/ draft paths (chooser + beginner / operator / contributor)
  • [x] Concrete URLs in sources.md
  • [x] Week-keyed checklist (this file)
  • [x] research-method.md

Week 1 — 01-philosophy + 02-concepts

Mental model domain to draft.

01-philosophy/

02-concepts/

Week 2 — 03-language syntax + semantics

Week 3 — 03-language builtins/idioms + 04-store-and-build

Week 4 — 09-nixos architecture + configuration

Week 5 — rest of 09-nixos

Week 6 — 07-flakes + 08-experimental-features

Week 7 — 06-nixpkgs + start 05-cli-and-tooling

Week 8 — finish CLI; 10-home-and-user + 11-development

Week 9 — 12-deployment-and-infra + 14-security-and-trust

Week 10 — 13-implementations + 15-history-and-governance

Week 11 — cross-cutting + polish

Complete pass (Phase 1) — status checkoff

Rubric: quality-checklist.md. Checked = leaf has frontmatter status: complete (2026-07-30 tree scan). Historical quality deepenings are recorded under Remaining work and closed Phase sections below.

Tier A — Beginner path

Tier B — Operator path

Tier C — Contributor path

Tier D — Periphery

Phase M — Mesh / interconnect / inter-trust

Leaves below are complete and now carry cousin links to machine-mesh, inter-machine-trust, and (where relevant) clan-and-mesh / overlay-networks.

M.1 New leaves

M.3 Exit

  • [x] Concept + inter-trust + Clan + overlay leaves exist; glossary/READMEs/sources updated for mesh vocabulary
  • [x] M.0 cousin cross-link pass finished (see M.0 above) — 2026-07-30
  • [x] Promote Phase M leaves draft → complete on verify pass

Remaining work

Still open

  1. Cadence (ongoing) — use release-checklist.md each Nix/NixOS release and on quarterly triggers.
  2. Intentional drafts — self-healing-config-mesh; living sources.md.
  3. Site — live at zemdregon.github.io/nix-docs; ops in site.md.
  4. Optional further gold — more thin-audience deepenings (language packaging hubs remain candidates). Score by audience pain, uniqueness, link leverage, churn risk, and source quality.

Gold thicken thin audiences (2026-08-01)

Closed rubric batch:

Phase 7 — Toward definitive (closed 2026-08-01)

Batches A–L complete; closeout verify + audits 2026-08-01.

Batch A — Cadence + first audience gaps (2026-08-01)

Batch B — Language ecosystems + org flakes (2026-08-01)

Batch C — Gold thicken + getting help (2026-08-01)

Batch D — Site / GitHub Pages (2026-08-01)

Batch E — Post-publish polish (2026-08-01)

Batch F — Configuration examples domain (2026-08-01)

New top-level domain 16-configuration-examples — multi-file walkthroughs that compose 00–15 (distinct from meta/examples fixtures).

Batch L — Configuration examples expand (2026-08-01)

Second wave under 16-configuration-examples — compose Batches G–J deepenings into worked configs.

Batch G — CI / Hydra / cross / builders cheatsheet (2026-08-01)

Batch H — Install bootstrap + secrets tools + VM tests (2026-08-01)

Batch I — Fleet deploy navigation (2026-08-01)

Batch J — Disk layout + impermanence (2026-08-01)

Batch K — Binary cache navigation (2026-08-01)

Closeout (2026-08-01)

  • [x] Subagent quality verify on new G–L leaves (5 cheatsheets + 4 worked configs)
  • [x] Parent review: sources rows, Batch L + Phase 7 exit, coverage sync
  • [x] Audits: broken-links.mjs → broken=0; quality-audit.mjs green

Batch D (historical note)

  • [x] Batch D — site generator (live) — see Batch D section above / site.md

Phase 6 — Homelab and config-repo gaps (2026-08-01)

New leaves from gap analysis (homelab / daily-driver config patterns):

Cross-links: operator + beginner roadmaps; common-service-examples, nixos-configurations, imports-and-profiles, flatpak-and-fhs See also updated.

Landed (2026-07-31 installer/store/frontend gold)

3i. Installer / store / frontend gold (done 2026-07-31) — graphical-installer, firmware-and-microcode, content-addressed-store, nixos-rebuild frontend; evaluator README maturity table (Snix ≠ Tvix).

Landed (2026-07-31 experimental/contributor gold)

3h. Experimental/contributor gold (done 2026-07-31) — cgroups, auto-allocate-uids, maintainers-and-teams, flake-parts, custom-options; named-args pitfall + Digga/Hive vs mesh disambiguation on flake-parts.

Landed (2026-07-31 operator/module gold)

3g. Operator/module/HM gold (done 2026-07-31) — declarative-containers, assertions-and-warnings, writing-hm-modules, manual-install, nixpkgs lib.md; overlay-vs-override See also mesh.

Landed (2026-07-31 further gold + corpus)

3e. Beginner-concept gold (done 2026-07-31) — profile, generation, channel, overlay, configuration-nix deepened toward derivation density; cousin links + CLI stamps. 3f. Example corpus expand (done 2026-07-31) — minimal-configuration.nix, simple-package.nix, fod-fetchurl.nix; linked from configuration-nix, callPackage, simple-package, fixed-output-derivation, overlay.

Landed (2026-07-31 post-v1 cadence / gold / corpus)

3a. Phase 5.1 cadence pass (done 2026-07-31) — experimental hub re-stamped Nix 2.34.x; release-cadence + evaluator maturity stamps; Clan/mesh + nh/lsp freshness (Clan cite stay on 26.05). 3b. Lix glossary parity (done 2026-07-31) — glossary Lix/Tvix/Snix + Flake CppNix/Lix wording. 3c. Broader gold calibration (done 2026-07-31) — derivation/store-path/closure/flake concepts; rebuild/hermetic/functional-PM/hashing; evaluator leaves (Snix ≠ Tvix rename). 3d. Example corpus (done 2026-07-31; expanded 2026-07-31) — meta/examples/ hello-flake, overlay-snippet, shell.nix, flake-with-checks, minimal-module.nix; linked from packages-apps-devShells, shells-and-direnv, checks-and-hydraJobs, writing-a-module, overlay-vs-override. 3e. Tier A concept deepen (done 2026-07-31) — profile, generation, overlay, channel thickened toward gold density; cross-links between profile/generation/channel.

Landed this batch (2026-07-31 v1 polish)

  1. Phase 1 quality deepen (done 2026-07-31) — high-traffic / high-churn walk: roadmaps + glossary; cheatsheets; nix-conf / trust; store protocols / builders / narinfo; upgrades / troubleshooting; experimental hub; colmena / deploy-rs / signing / supply-chain; CI / VM tests / shells / simple-package. Phase M.0 was already done 2026-07-30.
  2. Phase 2 deepen + consistency (done 2026-07-31) — gold deepen: callPackage, overlays-pattern, anti-patterns, pure-eval-and-impure, checks-and-hydraJobs, packages-apps-devShells; tree consistency sweep (CLI preference, hive/mesh wording, 26.05 illustrative pins, CppNix glossary hook).

Landed (Phases 2–4 — keep for history; do not reopen)

  1. Phase 3 slice A (done 2026-07-30) — Under 09-nixos/configuration/, all complete: impermanence, secure-boot-and-lanzaboote, tpm-and-measured-boot, nixos-hardware, firmware-and-microcode, zfs-and-btrfs, disko-recipes.
  2. Phase 3 slice B (done 2026-07-30) — all complete: faq-common-errors, import-from-derivation, lazy-trees-and-eval-perf.
  3. Phase 3 slice C (done 2026-07-30) — all complete: nix-copy-and-bundles, airgap-and-offline, specialisations. Skipped hosted-Garnix leaf: hosted Garnix shut down 2026-07-15 (see Discourse); FlakeHub remains vendor CI/cache.
  4. Phase 3 desktop (§3.2, done 2026-07-30) — under 09-nixos/desktop/, all complete: wayland-and-compositors, audio-pipewire, fonts-and-locales, flatpak-and-fhs, gaming-steam-proton, printing-and-scanning.
  5. Phase 3 §3.3 workloads (done 2026-07-30) — under 11-development/, all complete: cuda-rocm-ml, scientific-and-hpc, android-and-mobile, emacs-neovim-tooling.
  6. Phase 3 §3.4 virt/edge (done 2026-07-31) — all complete: libvirt-and-vms, microvms, netboot-and-pxe, wsl-and-foreign-os. (specialisations already complete in slice C.)
  7. Phase 3 §3.5 / §3.6 (done 2026-07-31) — all complete: enterprise-identity, fetchers-and-pinning, lsp-and-ide, module-system-internals, experimental-backlog. Skipped: hosted Garnix leaf (shut down 2026-07-15); Attic/Harmonia/Cachix stay on binary-cache-hosting.
  8. Phase 3 §3.7 comparisons (done 2026-07-31) — all complete: nix-vs-bazel-buck, nix-vs-ansible-terraform, nix-vs-containers-orchestrators, ubuntu-arch-to-nixos. (faq-common-errors already complete in slice B.)
  9. Phase 3 §3.8 security (done 2026-07-31) — all complete: apparmor-selinux, ssh-and-age-plugins, reproducible-builds-audit.
  10. Phase 4 products (done 2026-07-31) — nix-conf-knobs; glossary enrichment (mesh/IFD/specialisation/AppArmor/freeform/age); beginner/operator/contributor roadmap refresh.

Cadence / churn detail (same as item 2 above):

Audit hook

From repo root (needs Node; no Python required):

node meta/audit/broken-links.mjs
node meta/audit/quality-audit.mjs
node meta/examples/validate.mjs   # requires Nix; skips if absent

CI runs the same checks on push/PR via .github/workflows/docs-audit.yml.

Legacy inline snippets (equivalent to broken-links.mjs):

# Status histogram from YAML frontmatter (leaves + indexes + meta)
node -e '
const fs=require("fs"),path=require("path");
function walk(d,a=[]){for(const e of fs.readdirSync(d,{withFileTypes:true})){
  if(e.name.startsWith("."))continue;const p=path.join(d,e.name);
  if(e.isDirectory())walk(p,a);else if(e.name.endsWith(".md"))a.push(p);}return a;}
const counts={}; let missing=0;
for(const file of walk(".")){const t=fs.readFileSync(file,"utf8");
  const fm=t.match(/^---\n([\s\S]*?)\n---\n/);
  if(!fm){missing++;continue;}
  const m=fm[1].match(/^status:\s*(\S+)/m);
  if(!m){missing++;continue;}
  counts[m[1]]=(counts[m[1]]||0)+1;}
console.log(Object.entries(counts).sort((a,b)=>b[1]-a[1]).map(([k,v])=>`${String(v).padStart(4)} ${k}`).join("\n"));
console.log(`missing_frontmatter_status=${missing}`);
'

# Broken relative .md links (should print broken=0) — prefer: node meta/audit/broken-links.mjs
node -e '
const fs=require("fs"),path=require("path");
const re=/\[([^\]]*)\]\(([^)]+\.md)(#[^)]*)?\)/g;
function walk(d,a=[]){for(const e of fs.readdirSync(d,{withFileTypes:true})){
  if(e.name.startsWith("."))continue;const p=path.join(d,e.name);
  if(e.isDirectory())walk(p,a);else if(e.name.endsWith(".md"))a.push(p);}return a;}
const root=process.cwd();let checked=0,broken=[];
for(const file of walk(".")){const t=fs.readFileSync(file,"utf8");let m;
  while((m=re.exec(t))){const target=m[2];if(/^(https?:|mailto:)/.test(target))continue;checked++;
    const dest=path.resolve(path.dirname(file),target);
    if(!dest.startsWith(root+path.sep)&&dest!==root){broken.push([file,target,"outside"]);continue;}
    if(!fs.existsSync(dest)||!fs.statSync(dest).isFile())broken.push([file,target,"missing"]);}}
console.log(`checked=${checked} broken=${broken.length}`);
broken.forEach(b=>console.log(" ",b.join(" -> ")));
'

Last run (2026-07-31, post installer/store/frontend gold): frontmatter status histogram — 247 complete, 2 draft (self-healing-config-mesh + sources.md), 48 index, meta active/superseded; relative .md links broken=0.

Quality audit (Phase 6+): node meta/audit/broken-links.mjs · node meta/audit/quality-audit.mjs · node meta/examples/validate.mjs (Nix). CI: .github/workflows/docs-audit.yml. See quality-checklist.md Complete+ bar.

Definition of done (per article)

See research-method.md, quality-checklist.md, and AGENTS.md.

  • Draft: not stub; accurate Overview + Details; ≥1 relative wiki link; ≥1 upstream Reference; frontmatter status: draft
  • Complete: verified minimal example (or version-noted); no uncited absolute claims; this checklist updated; frontmatter status: complete