nimmo commented

Owner

Objective

Create a smaller repository-oriented NixOS learning path, retire superseded manual pages, align repository entry-point documentation and wiki-maintenance instructions, and perform the final whole-wiki audit and cutover.

Prerequisites and durable context

Milestone: Wiki Knowledge Architecture Rebuild
Begin after the System Atlas, ADR, operations, and engineering structures are stable enough to link from tutorials.
Project label: project:wiki-rebuild
General Nix material should link to authoritative upstream documentation. The local wiki teaches how those concepts appear in this repository.
Nova remains staged on Fedora 43 until deployment is explicitly confirmed.

Learning path checklist

Learning Path and Guided Repository Tour.
Nix Language Essentials.
Declarative Configuration, Store, and Generations.
Flakes and Inputs.
NixOS Modules and Option Merging.
specialArgs and Home Manager argument flow.
Electra Specialisations as a worked repository example.
Nix Troubleshooting Primer.
Condense useful material from old chapters 09-13 and retire duplicated generic exposition.

Cutover and maintenance checklist

Ensure Home navigation covers: understand, operate, recover, change, learn, and understand rationale.
Remove obsolete pages from the current wiki tree once their durable content is represented; rely on Git history rather than a complete visible archive.
Retain only historically significant migration/decommissioning material under the historical index.
Audit for duplicate ownership, contradictory facts, orphan pages, broken links, dated export filenames, and stale module/service/recipe names.
Compare host/service coverage against current flake.nix, host imports, and service modules.
Review README and reduce material that now belongs canonically in the wiki, while retaining essential commands and repository entry points.
Update the repository's wiki-maintenance skill/instructions to understand per-page provenance and review triggers rather than relying solely on one global source marker.
Use the repository's normal branch/MR lifecycle for source-repository README, skill, or policy changes; keep wiki commits independently reviewable.
Run focused documentation review, git diff --check in both repositories, wiki link validation, and any relevant tests for changed maintenance scripts/instructions.
Pull/rebase before final commits and publication in each repository.
Record final source and wiki commit IDs, validation, and any accepted gaps in the issue.
Close all phase issues and then the milestone only when the rebuilt wiki is the default navigable documentation set.

Completion criteria

The learning manual is useful but visibly subordinate to the overall fleet knowledge architecture.
Current navigation contains no knowingly stale legacy page.
README, AGENTS/policy material, wiki, Forgejo tracking, BookStack logs, and Engram have explicit non-overlapping responsibilities.
Future wiki maintenance can identify affected pages from their canonical sources and review triggers.
The final execution comment provides a durable audit record and identifies any deliberately deferred work.

Resume and handoff protocol

At session start, read this issue, all earlier phase outcomes, and latest comments. Pull both repositories and confirm which source/wiki commits the last worker validated. Resume from the first unchecked item. At every stopping point, comment with current source commit, wiki commit, pages and repository files changed, validation performed, accepted gaps or blockers, and the exact next checklist item. Do not close this issue or the milestone on the basis of chat context; closure requires committed, pushed, and audited artifacts.

# Objective Create a smaller repository-oriented NixOS learning path, retire superseded manual pages, align repository entry-point documentation and wiki-maintenance instructions, and perform the final whole-wiki audit and cutover. ## Prerequisites and durable context - Milestone: `Wiki Knowledge Architecture Rebuild` - Begin after the System Atlas, ADR, operations, and engineering structures are stable enough to link from tutorials. - Project label: `project:wiki-rebuild` - General Nix material should link to authoritative upstream documentation. The local wiki teaches how those concepts appear in this repository. - Nova remains staged on Fedora 43 until deployment is explicitly confirmed. ## Learning path checklist - [ ] Learning Path and Guided Repository Tour. - [ ] Nix Language Essentials. - [ ] Declarative Configuration, Store, and Generations. - [ ] Flakes and Inputs. - [ ] NixOS Modules and Option Merging. - [ ] `specialArgs` and Home Manager argument flow. - [ ] Electra Specialisations as a worked repository example. - [ ] Nix Troubleshooting Primer. - [ ] Condense useful material from old chapters 09-13 and retire duplicated generic exposition. ## Cutover and maintenance checklist - [ ] Ensure Home navigation covers: understand, operate, recover, change, learn, and understand rationale. - [ ] Remove obsolete pages from the current wiki tree once their durable content is represented; rely on Git history rather than a complete visible archive. - [ ] Retain only historically significant migration/decommissioning material under the historical index. - [ ] Audit for duplicate ownership, contradictory facts, orphan pages, broken links, dated export filenames, and stale module/service/recipe names. - [ ] Compare host/service coverage against current `flake.nix`, host imports, and service modules. - [ ] Review README and reduce material that now belongs canonically in the wiki, while retaining essential commands and repository entry points. - [ ] Update the repository's wiki-maintenance skill/instructions to understand per-page provenance and review triggers rather than relying solely on one global source marker. - [ ] Use the repository's normal branch/MR lifecycle for source-repository README, skill, or policy changes; keep wiki commits independently reviewable. - [ ] Run focused documentation review, `git diff --check` in both repositories, wiki link validation, and any relevant tests for changed maintenance scripts/instructions. - [ ] Pull/rebase before final commits and publication in each repository. - [ ] Record final source and wiki commit IDs, validation, and any accepted gaps in the issue. - [ ] Close all phase issues and then the milestone only when the rebuilt wiki is the default navigable documentation set. ## Completion criteria - The learning manual is useful but visibly subordinate to the overall fleet knowledge architecture. - Current navigation contains no knowingly stale legacy page. - README, AGENTS/policy material, wiki, Forgejo tracking, BookStack logs, and Engram have explicit non-overlapping responsibilities. - Future wiki maintenance can identify affected pages from their canonical sources and review triggers. - The final execution comment provides a durable audit record and identifies any deliberately deferred work. ## Resume and handoff protocol At session start, read this issue, all earlier phase outcomes, and latest comments. Pull both repositories and confirm which source/wiki commits the last worker validated. Resume from the first unchecked item. At every stopping point, comment with current source commit, wiki commit, pages and repository files changed, validation performed, accepted gaps or blockers, and the exact next checklist item. Do not close this issue or the milestone on the basis of chat context; closure requires committed, pushed, and audited artifacts.

nimmo added this to the Wiki Knowledge Architecture Rebuild milestone

2026-09-12 09:42:50 +01:00

nimmo added the

project:wiki-rebuild

host:fleet

labels

2026-09-12 09:42:50 +01:00

nimmo referenced this issue

2026-09-12 09:43:43 +01:00

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

nimmo referenced this issue

2026-09-13 12:56:32 +01:00

[Wiki 4/5] Rebuild operational runbooks and the engineering handbook #222

nimmo referenced this issue

2026-09-13 12:57:42 +01:00

[Wiki 4/5] Rebuild operational runbooks and the engineering handbook #222

nimmo commented

2026-09-13 12:59:22 +01:00

Author

Owner

Phase 5 started: published Guided Repository Tour in wiki commit 99cd455, linked from Home and Learning Path. Verified against source b2831d3313 (content baseline 556df88494; only flake.lock differs). Tour follows flake registration/shared builder, Vega host imports, option-gated service, Home Manager path, update policy, and the single-target Electra specialisations; staged Nova is distinct from deployed NixOS. Focused review, whitespace and internal-link checks passed; no configuration was activated. Next item: Nix Language Essentials.

Phase 5 started: published Guided Repository Tour in wiki commit 99cd455, linked from Home and Learning Path. Verified against source b2831d33132967b4c4fb69e6068b2b05fff8fdff (content baseline 556df88494686003b1c4f20c8e0b99b5afc16a6e; only flake.lock differs). Tour follows flake registration/shared builder, Vega host imports, option-gated service, Home Manager path, update policy, and the single-target Electra specialisations; staged Nova is distinct from deployed NixOS. Focused review, whitespace and internal-link checks passed; no configuration was activated. Next item: Nix Language Essentials.

nimmo commented

2026-09-13 13:00:39 +01:00

Author

Owner

Phase 5: published Nix Language Essentials in wiki commit 7acf3c8 (source b2831d3313; only flake.lock differs from content baseline 556df88494). Uses checked examples from current Jellyfin, Home Manager, default-config, Electra, and flake modules; links to official nix.dev language tutorial/reference. Focused review and wiki whitespace/internal-link checks passed. Next item: Declarative Configuration, Store, and Generations.

Phase 5: published Nix Language Essentials in wiki commit 7acf3c8 (source b2831d33132967b4c4fb69e6068b2b05fff8fdff; only flake.lock differs from content baseline 556df88494686003b1c4f20c8e0b99b5afc16a6e). Uses checked examples from current Jellyfin, Home Manager, default-config, Electra, and flake modules; links to official nix.dev language tutorial/reference. Focused review and wiki whitespace/internal-link checks passed. Next item: Declarative Configuration, Store, and Generations.

nimmo commented

2026-09-13 13:02:26 +01:00

Author

Owner

Phase 5: published Declarative Configuration, Store, and Generations in wiki commit e67251c. Verified source b2831d3313 (content baseline 556df88494). Lesson distinguishes source/evaluation/host build/test activation/system generation from mutable service state and backup; cites current deploy recipes and GC policy. Focused review plus whitespace/internal-link checks passed; no host build or activation done. Next item: Flakes and Inputs.

Phase 5: published Declarative Configuration, Store, and Generations in wiki commit e67251c. Verified source b2831d33132967b4c4fb69e6068b2b05fff8fdff (content baseline 556df88494686003b1c4f20c8e0b99b5afc16a6e). Lesson distinguishes source/evaluation/host build/test activation/system generation from mutable service state and backup; cites current deploy recipes and GC policy. Focused review plus whitespace/internal-link checks passed; no host build or activation done. Next item: Flakes and Inputs.

nimmo commented

2026-09-13 13:04:15 +01:00

Author

Owner

Phase 5: published Flakes and Inputs in wiki commit 09b8714 (source b2831d3313; only flake.lock differs from content baseline 556df88494). Verified current root inputs/outputs, shared builder, stable Cosmos/Chaos selection, narrow Lyra Jellyfin override, Redview output shape and update-policy group. Focused review plus whitespace/internal-link checks passed; no input update performed. Next item: NixOS Modules and Option Merging.

Phase 5: published Flakes and Inputs in wiki commit 09b8714 (source b2831d33132967b4c4fb69e6068b2b05fff8fdff; only flake.lock differs from content baseline 556df88494686003b1c4f20c8e0b99b5afc16a6e). Verified current root inputs/outputs, shared builder, stable Cosmos/Chaos selection, narrow Lyra Jellyfin override, Redview output shape and update-policy group. Focused review plus whitespace/internal-link checks passed; no input update performed. Next item: NixOS Modules and Option Merging.

nimmo commented

2026-09-13 13:06:09 +01:00

Author

Owner

Phase 5: published NixOS Modules and Option Merging in wiki commit b2b0f40. Checked current Lyra/Jellyfin enable gate and merged backup/monitor lists, common import graph, generated hardware mkDefault, and Electra mkForce examples against source b2831d3313. Focused review and whitespace/internal-link checks passed; no Nix change or activation. Next item: specialArgs and Home Manager Argument Flow.

Phase 5: published NixOS Modules and Option Merging in wiki commit b2b0f40. Checked current Lyra/Jellyfin enable gate and merged backup/monitor lists, common import graph, generated hardware mkDefault, and Electra mkForce examples against source b2831d33132967b4c4fb69e6068b2b05fff8fdff. Focused review and whitespace/internal-link checks passed; no Nix change or activation. Next item: specialArgs and Home Manager Argument Flow.

nimmo commented

2026-09-13 13:07:30 +01:00

Author

Owner

Phase 5: published specialArgs and Home Manager Argument Flow in wiki commit ee02c53. Verified source b2831d3313: NixOS specialArgs, Home Manager extraSpecialArgs/sharedModules/useGlobalPkgs, host-role-derived isServer, primary-user entry point, and actual Home Manager input consumer. Focused review plus whitespace/internal-link checks passed; no source change or activation. Next item: Electra Specialisations worked example.

Phase 5: published specialArgs and Home Manager Argument Flow in wiki commit ee02c53. Verified source b2831d33132967b4c4fb69e6068b2b05fff8fdff: NixOS specialArgs, Home Manager extraSpecialArgs/sharedModules/useGlobalPkgs, host-role-derived isServer, primary-user entry point, and actual Home Manager input consumer. Focused review plus whitespace/internal-link checks passed; no source change or activation. Next item: Electra Specialisations worked example.

nimmo commented

2026-09-13 13:08:45 +01:00

Author

Owner

Phase 5: published Electra Specialisations worked example in wiki commit 663fd31. Verified single Electra flake target, base and igpu/dgpu module composition, shared profile imports, DGPU-only hardware imports, and current-mode preservation in just test/build-diff against source b2831d3313. Links to ADR-001, Safe Testing, and boot-trust recovery; no hardware mode changed. Focused review plus whitespace/internal-link checks passed. Next item: Nix Troubleshooting Primer.

Phase 5: published Electra Specialisations worked example in wiki commit 663fd31. Verified single Electra flake target, base and igpu/dgpu module composition, shared profile imports, DGPU-only hardware imports, and current-mode preservation in just test/build-diff against source b2831d33132967b4c4fb69e6068b2b05fff8fdff. Links to ADR-001, Safe Testing, and boot-trust recovery; no hardware mode changed. Focused review plus whitespace/internal-link checks passed. Next item: Nix Troubleshooting Primer.

nimmo commented

2026-09-13 13:10:06 +01:00

Author

Owner

Phase 5: published Nix Troubleshooting Primer in wiki commit 4442292. Learning path now has all eight planned new pages. Primer classifies parse/evaluation, host build, activation, and runtime failures; cross-links current validation, deployment, monitoring, and migration procedures. Verified recipe/output names against source b2831d3313. Focused review plus whitespace/internal-link checks passed; no failure induced or host changed. Next: condense/retire legacy chapters 09-13 and other duplicated manual pages, then final cutover audit.

Phase 5: published Nix Troubleshooting Primer in wiki commit 4442292. Learning path now has all eight planned new pages. Primer classifies parse/evaluation, host build, activation, and runtime failures; cross-links current validation, deployment, monitoring, and migration procedures. Verified recipe/output names against source b2831d33132967b4c4fb69e6068b2b05fff8fdff. Focused review plus whitespace/internal-link checks passed; no failure induced or host changed. Next: condense/retire legacy chapters 09-13 and other duplicated manual pages, then final cutover audit.

nimmo commented

2026-09-13 13:15:04 +01:00

Author

Owner

Phase 5 cutover: published wiki commit 5d79be5 retiring 15 superseded manual chapters (01-13, legacy disaster recovery, legacy wrapper redirect), with content recoverable in wiki Git history. Moved the historically significant Electra Secure Boot rollout record to 91-Electra-Secure-Boot-Hardening-Record and updated current references/indexes. Atlas, Operations, Engineering, Learning, and Historical indexes now point only to current guidance or explicitly historical material. Verified staged diff whitespace, all internal links, and inbound links for every surviving page. No source configuration or live host changed. Next: whole-wiki contradiction/coverage audit, Home cutover, README and maintenance-skill source changes via branch/MR.

nimmo referenced this issue

2026-09-14 07:28:11 +01:00

docs: align source entry points with rebuilt wiki #229

nimmo referenced this issue

2026-09-14 07:35:52 +01:00

[Wiki 4/5] Rebuild operational runbooks and the engineering handbook #222

nimmo commented

2026-09-14 07:36:50 +01:00

Author

Owner

Cutover checkpoint (2026-09-14): all eight 50-series learning pages are published. Fifteen superseded manual pages were removed from current wiki and preserved in Git history; the Electra boot-trust rollout record alone remains visible under 90. Home is now Current and routes understand, operate, recover, change, learn, and rationale. Latest published wiki commit is 3cc52b7 (navigation cutover e976d14; Vega ytdl-sub service/storage delta and rebased MR provenance 3cc52b7). Source documentation MR #229 is at bc711db on docs/wiki-final-cutover; README was reduced, implementation-adjacent remediation notes preserved under docs/, update-wiki skill moved to per-page provenance, and AGENTS host/Paseo/module map corrected. Source main used for current service audit is 937e7fd02a. Final structural pass: 53 wiki Markdown pages, no orphan or broken internal links, no missing required metadata among current pages, no dated export filenames, clean wiki/source diff checks; all literal just recipe references exist except the explicitly warned nonexistent migrate-host-key tracked by #224. The only other non-existing literal source path is scripts/nixos-update-common.sh, mentioned only as an obsolete path not to edit; remaining non-existing path matches are placeholders. New ytdl-sub is covered in Service Catalogue and Storage and Data Map. Known implementation defects remain in #224, #225, #226, #227, not as untracked wiki tasks. Next: wait for fresh MR #229 review after bc711db, verify findings/checks, merge source docs if clear, update wiki provenance, then close phase #223 and milestone 24 with final commit IDs.

Cutover checkpoint (2026-09-14): all eight 50-series learning pages are published. Fifteen superseded manual pages were removed from current wiki and preserved in Git history; the Electra boot-trust rollout record alone remains visible under 90. Home is now Current and routes understand, operate, recover, change, learn, and rationale. Latest published wiki commit is 3cc52b7 (navigation cutover e976d14; Vega ytdl-sub service/storage delta and rebased MR provenance 3cc52b7). Source documentation MR #229 is at bc711db on docs/wiki-final-cutover; README was reduced, implementation-adjacent remediation notes preserved under docs/, update-wiki skill moved to per-page provenance, and AGENTS host/Paseo/module map corrected. Source main used for current service audit is 937e7fd02aad450a006b49f592c156e75888db7a. Final structural pass: 53 wiki Markdown pages, no orphan or broken internal links, no missing required metadata among current pages, no dated export filenames, clean wiki/source diff checks; all literal just recipe references exist except the explicitly warned nonexistent migrate-host-key tracked by #224. The only other non-existing literal source path is scripts/nixos-update-common.sh, mentioned only as an obsolete path not to edit; remaining non-existing path matches are placeholders. New ytdl-sub is covered in Service Catalogue and Storage and Data Map. Known implementation defects remain in #224, #225, #226, #227, not as untracked wiki tasks. Next: wait for fresh MR #229 review after bc711db, verify findings/checks, merge source docs if clear, update wiki provenance, then close phase #223 and milestone 24 with final commit IDs.

nimmo commented

2026-09-14 07:44:11 +01:00

Author

Owner

Final wiki cutover audit (2026-09-14). Source main: ef4ae2ce2f, merged from documentation MR #229. Wiki main: 8b544104d9b9061e80091fc5bc093d9ad1d35923. The eight-page repository-oriented learning path is published; Home is Current and routes understanding, operations, recovery, change, learning, and rationale. Fifteen superseded manual pages were retired into wiki Git history; only the explicitly historical Electra boot-trust rollout record remains visible under 90. README is now an entry point, not a second manual; implementation-adjacent auto-update details live in source docs/auto-update-remediation.md; the update-wiki skill and wiki maintenance runbook both use per-page provenance and review triggers. The current six flake hosts, host imports, and declared services were compared to the System Atlas; a new Vega ytdl-sub delta was added to the service and storage maps. Final focused checks: both worktrees clean; git diff --check in both; all 53 wiki pages have status metadata and inbound navigation, no broken internal links or dated export filenames; current just references checked against just --list. Placeholder paths and explicitly obsolete scripts/nixos-update-common.sh are not current instructions. No Nix configuration was changed by MR #229; its deterministic PR test passed at 741d0dd, and focused documentation review passed. The final advisory AI review failed parsing its own Ollama JSON (Invalid backslash escape), not from a documentation finding; this exception and prior actionable findings were recorded on the MR before merge. No live deployment or service-health claims were inferred from source. Accepted implementation follow-ups remain open: #224 SOPS/new-host helpers, #225 stale Vega OpenCode monitor entry, and #226 unsafe Backrest restore behavior. They are not unfinished wiki pages. Issue #227 tracks auto-update recovery-control clarification outside this milestone; #228 tracks one-time import scaffolding under its own service-migration milestone. The wiki rewrite deliverables are complete. Milestone 24 still contains open implementation follow-ups #224-#226, so milestone disposition is intentionally left open pending a tracking decision.

Final wiki cutover audit (2026-09-14). Source main: ef4ae2ce2f1b3fd8fc22262ded9c2374ac78c6ef, merged from documentation MR #229. Wiki main: 8b544104d9b9061e80091fc5bc093d9ad1d35923. The eight-page repository-oriented learning path is published; Home is Current and routes understanding, operations, recovery, change, learning, and rationale. Fifteen superseded manual pages were retired into wiki Git history; only the explicitly historical Electra boot-trust rollout record remains visible under 90. README is now an entry point, not a second manual; implementation-adjacent auto-update details live in source docs/auto-update-remediation.md; the update-wiki skill and wiki maintenance runbook both use per-page provenance and review triggers. The current six flake hosts, host imports, and declared services were compared to the System Atlas; a new Vega ytdl-sub delta was added to the service and storage maps. Final focused checks: both worktrees clean; git diff --check in both; all 53 wiki pages have status metadata and inbound navigation, no broken internal links or dated export filenames; current just references checked against just --list. Placeholder paths and explicitly obsolete scripts/nixos-update-common.sh are not current instructions. No Nix configuration was changed by MR #229; its deterministic PR test passed at 741d0dd, and focused documentation review passed. The final advisory AI review failed parsing its own Ollama JSON (Invalid backslash escape), not from a documentation finding; this exception and prior actionable findings were recorded on the MR before merge. No live deployment or service-health claims were inferred from source. Accepted implementation follow-ups remain open: #224 SOPS/new-host helpers, #225 stale Vega OpenCode monitor entry, and #226 unsafe Backrest restore behavior. They are not unfinished wiki pages. Issue #227 tracks auto-update recovery-control clarification outside this milestone; #228 tracks one-time import scaffolding under its own service-migration milestone. The wiki rewrite deliverables are complete. Milestone 24 still contains open implementation follow-ups #224-#226, so milestone disposition is intentionally left open pending a tracking decision.

nimmo closed this issue

2026-09-14 07:44:11 +01:00

nimmo commented

2026-09-14 07:47:03 +01:00

Author

Owner

Milestone disposition resolved after the final audit: implementation defects #224, #225, and #226 remain open with their original acceptance criteria and have been moved to new milestone #25, Wiki Audit Implementation Follow-ups. Rebuild milestone #24 now contains six closed issues and zero open issues. No source or wiki content changed for this tracking-only closeout; final source ef4ae2ce2f and wiki 8b544104d9b9061e80091fc5bc093d9ad1d35923 remain the published artifacts. Closing rebuild milestone #24.

Milestone disposition resolved after the final audit: implementation defects #224, #225, and #226 remain open with their original acceptance criteria and have been moved to new milestone #25, Wiki Audit Implementation Follow-ups. Rebuild milestone #24 now contains six closed issues and zero open issues. No source or wiki content changed for this tracking-only closeout; final source ef4ae2ce2f1b3fd8fc22262ded9c2374ac78c6ef and wiki 8b544104d9b9061e80091fc5bc093d9ad1d35923 remain the published artifacts. Closing rebuild milestone #24.

Rows
Columns

[Wiki 5/5] Condense the learning path and complete the wiki cutover #223

Objective

Prerequisites and durable context

Learning path checklist

Cutover and maintenance checklist

Completion criteria

Resume and handoff protocol