nimmo/nixos-config
nimmo/nixos-config
Watch
1
0
Fork
You've already forked nixos-config
 0
Code Issues 15 Pull requests Wiki Activity Actions
Page: 49 Documentation Maintenance
Pages
00 Documentation Map and Scope 00 Documentation Standards 00 Start Here and Governance 10 System Atlas 11 Fleet Overview 12 Host Inventory 13 Service Catalogue 14 Network and Access Topology 15 Storage and Data Map 16 Automation and Control Plane 20 Architecture Decisions 21 ADR 001 Electra Hardware Specialisations 22 ADR 002 Workload Placement 23 ADR 003 Network Exposure 23 Project Tracking 24 ADR 004 Engram Durable Agent Memory 24 Security Baseline 25 ADR 005 Auto Update Control Plane 26 ADR 006 Scoped Secret Files 30 Operations and Runbooks 31 Routine Fleet Operations 32 Safe Testing and Deployment 33 Host Provisioning 34 Monitoring and Service Investigation 35 Backup Verification and Partial Restore 36 Full Host Recovery 37 Electra Boot Trust Recovery 38 Secret Editing and Recipient Rotation 39 Auto Update Incident Response 39a Service Migration and Cutover 39b Wrapper Repository Packaging 40 Engineering Handbook 41 Repository Structure and Import Chain 42 Configuration Ownership Boundaries 43 Adding Packages and Flake Inputs 44 Adding a Module or Profile 45 Adding a Host 46 Adding or Migrating a Service 47 Testing and CI Contracts 48 Secrets Implementation Conventions 49 Documentation Maintenance 50 NixOS Learning Path 51 Guided Repository Tour 52 Nix Language Essentials 53 Declarative Configuration Store and Generations 54 Flakes and Inputs 55 NixOS Modules and Option Merging 56 SpecialArgs and Home Manager Argument Flow 57 Electra Specialisations Worked Example 58 Nix Troubleshooting Primer 90 Historical Material 91 Electra Secure Boot Hardening Record Home
4 49 Documentation Maintenance
Nimmo edited this page 2026-09-14 07:42:33 +01:00
Table of contents

Documentation Maintenance

  • Type: Runbook
  • Status: Current
  • Scope: Maintaining the separate nixos-config Forgejo wiki alongside source changes
  • Canonical sources: AGENTS.md; README.md; .agents/skills/update-wiki/SKILL.md; Documentation Map and Scope; Documentation Standards; Project and Change Governance; wiki rebuild issue #223
  • Last verified: Source commit ef4ae2ce2f1b3fd8fc22262ded9c2374ac78c6ef (2026-09-14); wiki structure and workflow checked 2026-09-14
  • Review triggers: Documentation ownership policy, page templates/status rules, wiki repository layout, source-change workflow, Forgejo issue conventions, or wiki publishing method

Purpose

Keep the wiki useful as a curated knowledge layer without making it a stale copy of the Nix repository, a second issue tracker, or a claim about live state. The source repository owns executable configuration; Forgejo issues own active work and acceptance evidence; the wiki owns durable reference, policy, rationale, runbooks, engineering guidance, and learning material. See Documentation Map and Scope for the full boundary, including BookStack and Engram.

This runbook applies to routine source-driven updates and structural wiki changes. The current sections are on Home. Follow Documentation Standards for types, metadata, slugs, templates, and transition rules. A page's Last verified field is per page, not a wiki-wide sync assertion.

Prerequisites and safety boundary

  • Have the current nixos-config checkout and its separately cloned wiki repository. Review both worktrees and upstream state before editing. Do not overwrite unrelated user edits or assume one repository's commit updates the other.
  • Identify the source revision(s) and exact paths behind the subject. A memory, old wiki paragraph, README summary, or issue comment is a lead, not evidence of current implementation. For a live-state claim, obtain deployment/health evidence; a Nix module or passing build alone is not it.
  • Never publish decrypted secrets, private keys, tokens, authentication material, raw sensitive logs, or a speculative diagnosis. The repository may expose public topology and implementation patterns, but permission to document them does not make secret values publishable.
  • Do not perform deployments or data migrations merely to update prose. Where live verification is unavailable, state that limit and keep the claim scoped to declared configuration.

Ordered procedure

1. Triage the knowledge change

Decide whether it is a correction to an existing page, a new durable page, an ADR, or only issue progress. Use one canonical purpose per page. Link different page types about the same subject instead of copying content. Put procedures that will be reused after an issue closes into the wiki; leave project-specific checklists, pending choices, transient logs, and completion evidence in the issue. Prefer a concise README pointer over duplicating a handbook chapter there.

For an existing wiki page, read its Canonical sources, Last verified, Review triggers, and Status first. Find all affected pages through their source paths and inbound links. During the rebuild, a Transitional page remains discoverable but is not the current operational contract. A Superseded page should point to its replacement. Retain historical prose only if it still explains a decision or rollback; Git history is the normal archive.

2. Verify source and edit the owning page

In the source checkout, compare the page's recorded revision with current HEAD for relevant paths. A useful starting point is:

git log --reverse --oneline VERIFIED_COMMIT..HEAD -- . ':!flake.lock'
git diff --name-only VERIFIED_COMMIT..HEAD -- . ':!flake.lock'

Replace VERIFIED_COMMIT with that page's full source commit. Inspect meaningful diffs, not merely filenames. A lock-only change may need no prose change unless it changes a documented channel, input, package, or update contract. Verify commands against justfiles/, host registration against flake.nix, import paths and options against modules, CI against workflows, and storage/access statements against the relevant current source. Treat Nova's staged NixOS configuration as source intent, not proof it runs NixOS.

Edit the smallest canonical page set. Include the required metadata and concrete review triggers; update Last verified to the full source revision actually checked, with any narrower live-state caveat. Use Forgejo wiki slugs for internal links (no .md suffix), and link new pages from the appropriate section index and Home when they are common entry points. Do not link a merely planned page as though it already exists.

3. Review and publish independently

Read the diff as a user following the instructions. Check commands, paths, host/service names, page status, links, and whether the page accidentally asserts deployment. In the wiki clone, use git diff --check and a link check; stage only intended files, then run git diff --cached --check. For documentation-only changes, focused review is the required gate; running nix flake check against the source solely for wiki prose adds no evidence. For source changes, select the relevant gates from Testing and CI Contracts.

Before committing or publishing, refresh the separate wiki clone with git pull --rebase --autostash, resolve any actual conflicts without discarding user changes, and verify the staged result again. Commit and push the wiki separately from the source repository. Record the wiki commit, source revision, verification limits, and next work item in the relevant Forgejo issue. No wiki edit should silently close an issue whose required live evidence remains outstanding.

The update-wiki agent skill uses this per-page provenance convention and does not require a Home-page sync marker. Its source change was merged in MR #229. Do not assert wiki-wide freshness from one source revision.

Success checks, recovery, and troubleshooting

  • The changed page has one clear owner/type, current links, accurate status, source revision, review triggers, and an explicit declared-versus-live boundary where it matters. Section navigation leads to it; superseded material does not compete as a current procedure.
  • The wiki diff has no accidental secret or unrelated changes, whitespace errors, or broken internal links. The wiki commit is pushed and its relationship to the source change is recorded in the issue where relevant.
  • If a source path no longer exists, trace its replacement from Git history and live imports before editing. If two pages conflict, identify which page type owns the claim and cross-link the other. If live status cannot be verified, mark it unknown rather than choosing the more convenient story.
  • If publication fails or the remote wiki moved, fetch/rebase and inspect the combined diff; do not force-push away someone else's work. A wrong published page should be corrected with a follow-up wiki commit and linked issue note. Retired pages can be recovered from wiki Git history.

Canonical source map

Concern Source
Surface ownership and knowledge promotion Documentation Map and Scope, AGENTS.md
Page types, metadata, slugs, and transition Documentation Standards
Issue/MR lifecycle and evidence Project and Change Governance, AGENTS.md
Validation selection Testing and CI Contracts
Rebuild audit and cutover Home, phase-5 issue #223