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

[Wiki 1/5] Establish the new information architecture and durable execution contract #219

New issue
Closed
opened 2026-09-12 09:42:32 +01:00 by nimmo · 2 comments
nimmo commented 2026-09-12 09:42:32 +01:00
Owner
Copy link

Objective

Establish the durable information architecture, navigation, templates, and execution contract for the repository wiki rebuild. This phase makes later work independently resumable and prevents the old manual structure from constraining the new wiki.

Project context

  • Milestone: Wiki Knowledge Architecture Rebuild
  • Project label: project:wiki-rebuild
  • Source repository: nimmo/nixos-config
  • Local source checkout: ~/nixos-config
  • Local wiki checkout: ~/nixos-config.wiki
  • Planning baselines: source 556df88494686003b1c4f20c8e0b99b5afc16a6e; wiki 0740498f335157fd3636ab73083263be3af6e852
  • The live source repository is authoritative. Planning baselines record where this project began; always pull and use the current source revision when verifying a page.
  • Preserve the old wiki through Git history. Do not create a visible archive containing every stale page.

Target information architecture

  1. 00 Start Here and Governance
  2. 10 System Atlas
  3. 20 Architecture Decisions
  4. 30 Operations and Runbooks
  5. 40 Engineering Handbook
  6. 50 NixOS Learning Path
  7. 90 selected historical material only

The system atlas is the centre of gravity. Governance and ADRs explain constraints; runbooks operate the fleet; the engineering handbook changes it; the learning path teaches it.

Documentation boundaries

  • Repository: executable configuration and tests.
  • README: entry point, essential commands, concise repository map, and links onward.
  • Forgejo issues/milestones: planned and active work, execution state, and acceptance evidence.
  • Repository wiki: curated durable human knowledge.
  • BookStack Project Logs: chronological generated project reports.
  • Engram: confirmed agent context that is useful across sessions but is not automatically canonical documentation.

Required page metadata

Every substantive page must identify:

  • Type: Reference, Runbook, ADR, Policy, or Tutorial
  • Status: Current, Transitional, or Superseded
  • Scope: fleet, repository, host, service, or subsystem
  • Canonical sources: exact repository paths or external authority
  • Last verified: full source commit and date
  • Review triggers: source changes that require reassessment

ADRs instead use Status, Context, Decision, Consequences, Alternatives, References, and Supersession.

Scope and checklist

  • Pull both repositories and confirm both working trees are clean before editing.
  • Inventory current wiki pages and record one disposition for each: retain, split, condense, replace, or retire.
  • Create the new Home page with navigation by intent and emergency entry points.
  • Create section index pages for 00, 10, 20, 30, 40, 50, and 90.
  • Create reusable page templates for reference, runbook, ADR, policy, and tutorial pages.
  • Document the source-of-truth boundaries above.
  • Define stable page naming and cross-linking conventions suitable for Forgejo's flat wiki namespace. Do not use dated export filenames.
  • Decide how transitional links behave while old and new pages coexist.
  • Run git -C ~/nixos-config.wiki diff --check and verify every new internal link.
  • Commit and push this phase as one coherent wiki commit; record the wiki commit in an issue comment.

Completion criteria

  • The new Home page makes the whole model visible without presenting the learning manual as the primary product.
  • Every later phase has a named destination and page contract.
  • Old content remains reachable during migration or has an explicit disposition.
  • No page implies that one global source marker proves the entire wiki current.
  • The phase is committed and pushed, and the execution ledger comment identifies the next phase.

Resume and handoff protocol

At the start of every work session, read this issue, the milestone's other phase issues, and the latest issue comments. Pull both repositories, inspect both working trees, and continue from the first unchecked item whose prerequisite is complete. At every stopping point, leave an issue comment containing: current source commit, current wiki commit, pages changed, validation performed, unresolved facts, and the exact next checklist item. Never mark a checklist item complete unless its result is present in a committed wiki or source-repository change. Do not rely on conversation context or Engram alone for execution state.

# Objective Establish the durable information architecture, navigation, templates, and execution contract for the repository wiki rebuild. This phase makes later work independently resumable and prevents the old manual structure from constraining the new wiki. ## Project context - Milestone: `Wiki Knowledge Architecture Rebuild` - Project label: `project:wiki-rebuild` - Source repository: `nimmo/nixos-config` - Local source checkout: `~/nixos-config` - Local wiki checkout: `~/nixos-config.wiki` - Planning baselines: source `556df88494686003b1c4f20c8e0b99b5afc16a6e`; wiki `0740498f335157fd3636ab73083263be3af6e852` - The live source repository is authoritative. Planning baselines record where this project began; always pull and use the current source revision when verifying a page. - Preserve the old wiki through Git history. Do not create a visible archive containing every stale page. ## Target information architecture 1. `00` Start Here and Governance 2. `10` System Atlas 3. `20` Architecture Decisions 4. `30` Operations and Runbooks 5. `40` Engineering Handbook 6. `50` NixOS Learning Path 7. `90` selected historical material only The system atlas is the centre of gravity. Governance and ADRs explain constraints; runbooks operate the fleet; the engineering handbook changes it; the learning path teaches it. ## Documentation boundaries - Repository: executable configuration and tests. - README: entry point, essential commands, concise repository map, and links onward. - Forgejo issues/milestones: planned and active work, execution state, and acceptance evidence. - Repository wiki: curated durable human knowledge. - BookStack Project Logs: chronological generated project reports. - Engram: confirmed agent context that is useful across sessions but is not automatically canonical documentation. ## Required page metadata Every substantive page must identify: - `Type`: Reference, Runbook, ADR, Policy, or Tutorial - `Status`: Current, Transitional, or Superseded - `Scope`: fleet, repository, host, service, or subsystem - `Canonical sources`: exact repository paths or external authority - `Last verified`: full source commit and date - `Review triggers`: source changes that require reassessment ADRs instead use Status, Context, Decision, Consequences, Alternatives, References, and Supersession. ## Scope and checklist - [ ] Pull both repositories and confirm both working trees are clean before editing. - [ ] Inventory current wiki pages and record one disposition for each: retain, split, condense, replace, or retire. - [ ] Create the new Home page with navigation by intent and emergency entry points. - [ ] Create section index pages for `00`, `10`, `20`, `30`, `40`, `50`, and `90`. - [ ] Create reusable page templates for reference, runbook, ADR, policy, and tutorial pages. - [ ] Document the source-of-truth boundaries above. - [ ] Define stable page naming and cross-linking conventions suitable for Forgejo's flat wiki namespace. Do not use dated export filenames. - [ ] Decide how transitional links behave while old and new pages coexist. - [ ] Run `git -C ~/nixos-config.wiki diff --check` and verify every new internal link. - [ ] Commit and push this phase as one coherent wiki commit; record the wiki commit in an issue comment. ## Completion criteria - The new Home page makes the whole model visible without presenting the learning manual as the primary product. - Every later phase has a named destination and page contract. - Old content remains reachable during migration or has an explicit disposition. - No page implies that one global source marker proves the entire wiki current. - The phase is committed and pushed, and the execution ledger comment identifies the next phase. ## Resume and handoff protocol At the start of every work session, read this issue, the milestone's other phase issues, and the latest issue comments. Pull both repositories, inspect both working trees, and continue from the first unchecked item whose prerequisite is complete. At every stopping point, leave an issue comment containing: current source commit, current wiki commit, pages changed, validation performed, unresolved facts, and the exact next checklist item. Never mark a checklist item complete unless its result is present in a committed wiki or source-repository change. Do not rely on conversation context or Engram alone for execution state.
nimmo commented 2026-09-12 09:43:43 +01:00
Author
Owner
Copy link

Durable phase index:

  1. #219 — foundation, navigation, templates, and execution contract
  2. #220 — fleet System Atlas
  3. #221 — governance, security policy, and ADRs
  4. #222 — operational runbooks and engineering handbook
  5. #223 — learning path, legacy retirement, maintenance changes, and final audit

Normal order is 219 → 220 → 221 → 222 → 223. Phase 221 may overlap with 220 only after phase 219 fixes terminology and page contracts. Each issue body is self-contained; its latest comments are the execution ledger. Resume from Forgejo state and committed repository/wiki state, never from chat context alone.

Durable phase index: 1. #219 — foundation, navigation, templates, and execution contract 2. #220 — fleet System Atlas 3. #221 — governance, security policy, and ADRs 4. #222 — operational runbooks and engineering handbook 5. #223 — learning path, legacy retirement, maintenance changes, and final audit Normal order is 219 → 220 → 221 → 222 → 223. Phase 221 may overlap with 220 only after phase 219 fixes terminology and page contracts. Each issue body is self-contained; its latest comments are the execution ledger. Resume from Forgejo state and committed repository/wiki state, never from chat context alone.
nimmo commented 2026-09-12 09:54:23 +01:00
Author
Owner
Copy link

Phase 1 completion checkpoint

Source verified: 556df88494 (2026-09-12)
Wiki published: 5da1a97 (docs(wiki): establish knowledge architecture)

Created:

  • 00-Start-Here-and-Governance
  • 00-Documentation-Map-and-Scope
  • 00-Documentation-Standards
  • 10-System-Atlas
  • 20-Architecture-Decisions
  • 30-Operations-and-Runbooks
  • 40-Engineering-Handbook
  • 50-NixOS-Learning-Path
  • 90-Historical-Material

Replaced Home with intent-based navigation. Removed the obsolete wiki-wide sync claim and established page-local provenance/review triggers. Legacy pages remain reachable and are explicitly transitional.

Legacy disposition ledger:

  • Home: replaced by the new knowledge-base entry point.
  • 01 Configuration Structure: split between System Atlas reference and Engineering Handbook.
  • 02 Workflows: collapse and rewrite into focused Operations and Engineering pages.
  • 03 Host Configurations: replace with Fleet/Host reference plus linked runbooks and ADRs.
  • 04 Specialisations: split among host reference, ADR, runbook, and worked tutorial.
  • 05 Package Management: condense into Engineering and Learning material.
  • 06 Secrets Management: split into topology reference, scoped-secrets ADR, rotation runbook, and tutorial material.
  • 07 Troubleshooting: collapse into operational investigation plus a smaller learning primer.
  • 08 Quick Reference: collapse into section-specific entry points; retain only genuinely useful command reference.
  • 09 Nix Language: condense into the Learning Path.
  • 10 Declarative Configuration: condense into the Learning Path.
  • 11 Flakes: condense into Learning and Engineering pages.
  • 12 Modules: condense into Learning and Engineering pages.
  • 13 specialArgs: condense into the Learning Path.
  • 20 Disaster Recovery: retain and reverify as a runbook.
  • 21 Electra Secure Boot: retain and reverify as a runbook, moving rationale to ADRs where appropriate.
  • 22 Wrapper-Repo Packaging: retain and reverify as a runbook, with placement rationale separated into ADR-002.
  • 23 Project Tracking: retain and rewrite as governance policy.
  • 24 Security Baseline: retain and rewrite as policy/review gates.

Validation:

  • git diff --cached --check passed before commit.
  • All internal links from the new foundation pages resolve to existing wiki files.
  • Both repositories were pulled before work; the wiki was pulled again immediately before commit.
  • Wiki main was pushed successfully and both working trees are clean.

Unresolved facts: none for phase 1. System facts intentionally remain transitional until phase 2 verifies them.

Next action: begin #220 by deriving Fleet Overview and Host Inventory from current flake.nix, nixosConfig.host metadata, host imports, and deployment-status evidence. Use wiki commit 5da1a97 as the phase-2 starting baseline.

Phase 1 completion checkpoint Source verified: 556df88494686003b1c4f20c8e0b99b5afc16a6e (2026-09-12) Wiki published: 5da1a97 (docs(wiki): establish knowledge architecture) Created: - 00-Start-Here-and-Governance - 00-Documentation-Map-and-Scope - 00-Documentation-Standards - 10-System-Atlas - 20-Architecture-Decisions - 30-Operations-and-Runbooks - 40-Engineering-Handbook - 50-NixOS-Learning-Path - 90-Historical-Material Replaced Home with intent-based navigation. Removed the obsolete wiki-wide sync claim and established page-local provenance/review triggers. Legacy pages remain reachable and are explicitly transitional. Legacy disposition ledger: - Home: replaced by the new knowledge-base entry point. - 01 Configuration Structure: split between System Atlas reference and Engineering Handbook. - 02 Workflows: collapse and rewrite into focused Operations and Engineering pages. - 03 Host Configurations: replace with Fleet/Host reference plus linked runbooks and ADRs. - 04 Specialisations: split among host reference, ADR, runbook, and worked tutorial. - 05 Package Management: condense into Engineering and Learning material. - 06 Secrets Management: split into topology reference, scoped-secrets ADR, rotation runbook, and tutorial material. - 07 Troubleshooting: collapse into operational investigation plus a smaller learning primer. - 08 Quick Reference: collapse into section-specific entry points; retain only genuinely useful command reference. - 09 Nix Language: condense into the Learning Path. - 10 Declarative Configuration: condense into the Learning Path. - 11 Flakes: condense into Learning and Engineering pages. - 12 Modules: condense into Learning and Engineering pages. - 13 specialArgs: condense into the Learning Path. - 20 Disaster Recovery: retain and reverify as a runbook. - 21 Electra Secure Boot: retain and reverify as a runbook, moving rationale to ADRs where appropriate. - 22 Wrapper-Repo Packaging: retain and reverify as a runbook, with placement rationale separated into ADR-002. - 23 Project Tracking: retain and rewrite as governance policy. - 24 Security Baseline: retain and rewrite as policy/review gates. Validation: - git diff --cached --check passed before commit. - All internal links from the new foundation pages resolve to existing wiki files. - Both repositories were pulled before work; the wiki was pulled again immediately before commit. - Wiki main was pushed successfully and both working trees are clean. Unresolved facts: none for phase 1. System facts intentionally remain transitional until phase 2 verifies them. Next action: begin #220 by deriving Fleet Overview and Host Inventory from current flake.nix, nixosConfig.host metadata, host imports, and deployment-status evidence. Use wiki commit 5da1a97 as the phase-2 starting baseline.
nimmo closed this issue 2026-09-12 09:54:34 +01:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
feat/issue-236-electra-nova-vega
feat/issue-233-nova-builder-credentials
docs/wiki-final-cutover
fix/remediation-evaluation-evidence
fix/remediation-evidence-review
fix/chaos-synthseek-queue
pre-electra-disko-migration
Labels
Clear labels   
area:authentication
Issues related to authentication area

  
area:flake-utilities
Issues related to flake utilities area

  
area:performance
Issues related to performance area

  
area:tbd
Area to be determined

  
host:chaos
Issues specific to the chaos host.

  
host:electra
Issues specific to the electra host.

  
host:fleet
Issues that span multiple hosts or the fleet as a whole.

  
host:lyra
Issues specific to the lyra host.

  
host:nova
Issues specific to the nova host.

  
host:vega
Issues specific to the vega host.

  
investigation
Issue is an investigation task

  
phase:cutover
The service cutover execution phase.

  
phase:deploy

   
phase:mcp

   
phase:module

   
phase:packaging

   
phase:prep
Preparation and preflight work before service cutover.

  
phase:validation
Post-cutover validation and rollback-window work.

  
priority:high
High priority issue

  
priority:medium
Medium priority issue

  
project:attic-postgres-lyra-rollout
Issues in the Attic PostgreSQL migration and Lyra rollout workstream.

  
project:auto-update-reliability
Work arising from the automated update reliability review.

  
project:auto-update-remediation
Guarded Nova-assisted diagnosis and remediation of failed automated updates.

  
project:declarative-purity-cleanup
Issues in the declarative purity cleanup workstream.

  
project:external-review
Review of external configurations for ideas and improvements

  
project:fleet-boundary-cleanup
Maintainability work that clarifies fleet configuration and automation boundaries.

  
project:host-facts-refactor
Issues in the host facts refactor workstream.

  
project:lyra-nixos-deploy
Issues in the Lyra NixOS deployment workstream.

  
project:lyra-service-stack-migration
Issues in the lyra service stack migration workstream.

  
project:nebula-mesh-network
Issues in the Nebula mesh network workstream.

  
project:nixos-build-deployment-pipeline
Issues in the NixOS Build & Deployment Pipeline workstream.

  
project:security-hardening
Work belonging to the Security Hardening milestone

  
project:service-stack-migration
Issues in the service stack migration workstream.

  
project:vega-sillytavern-cutover
Issues in the Vega SillyTavern cutover workstream.

  
project:wiki-rebuild
Re-found the repository wiki as the fleet's curated knowledge architecture.

  
repo:numtide/flake-utils
Issues related to numtide/flake-utils repository

  
repo:numtide/nix-auth
Issues related to numtide/nix-auth repository

  
repo:numtide/nixos-passthru-cache
Issues related to numtide/nixos-passthru-cache repository

  
repo:numtide/nix-relay
Issues related to numtide/nix-relay repository

  
service:auto-update
NixOS flake update, cache build, and consumer deployment automation.

  
service:mem0

   
service:nix
Issues concerning Nix build, store, cache, or deployment infrastructure.

  
service:sillytavern
Issues related to the SillyTavern service.

  
service:slskd
Soulseek daemon (slskd) work.

  
service:synthseek
Synthseek music discovery/library manager work.

No labels
area:authentication
area:flake-utilities
area:performance
area:tbd
host:chaos
host:electra
host:fleet
host:lyra
host:nova
host:vega
investigation
phase:cutover
phase:deploy
phase:mcp
phase:module
phase:packaging
phase:prep
phase:validation
priority:high
priority:medium
project:attic-postgres-lyra-rollout
project:auto-update-reliability
project:auto-update-remediation
project:declarative-purity-cleanup
project:external-review
project:fleet-boundary-cleanup
project:host-facts-refactor
project:lyra-nixos-deploy
project:lyra-service-stack-migration
project:nebula-mesh-network
project:nixos-build-deployment-pipeline
project:security-hardening
project:service-stack-migration
project:vega-sillytavern-cutover
project:wiki-rebuild
repo:numtide/flake-utils
repo:numtide/nix-auth
repo:numtide/nixos-passthru-cache
repo:numtide/nix-relay
service:auto-update
service:mem0
service:nix
service:sillytavern
service:slskd
service:synthseek
Milestone
Clear milestone
No items
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
nimmo/nixos-config#219
No description provided.