From e05e3647e6079120cb19626ec083886c502c45a3 Mon Sep 17 00:00:00 2001 From: Bernardo Magri Date: Sat, 4 Jul 2026 19:45:34 +0100 Subject: [PATCH] =?UTF-8?q?docs(install):=20stitch=20the=20README=20?= =?UTF-8?q?=E2=86=92=20template=20first-run=20handoff=20=E2=80=94=20item?= =?UTF-8?q?=206=20complete?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Slice (c), the last of the docs review: the install/first-run story read end to end against the tree. Facts held (mkFlake args match the table, disko's @snapshots + hibernation swapfile, .#default/.#me naming); the one seam — README §3 never pointed the manual path at the template README's first-run steps — got a connective paragraph. Item 6 deleted from BACKLOG; ROADMAP § Full docs review flipped to ✓. Co-Authored-By: Claude Fable 5 --- README.md | 6 ++++++ agent/BACKLOG.md | 17 +---------------- agent/JOURNAL.md | 18 ++++++++++++++++++ docs/ROADMAP.md | 21 +++++++++------------ 4 files changed, 34 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 39f54dc..563fd36 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,12 @@ mkdir my-machine && cd my-machine nix flake init -t "git+https://git.bemagri.xyz/bernardo/nomarchy.git?ref=v1" ``` +The template's own README then walks the first-run steps: a real +`hardware-configuration.nix`, `git init` (flakes only see tracked +files), the two first rebuilds, and landing the checkout at +`~/.nomarchy` so the theme CLI finds it. (The installer does all of +this for you.) + You own two files day-to-day: `system.nix` and `home.nix` (plus `theme-state.json`, written by the CLI). Your `flake.nix` is set up once — later by the installer — and never hand-edited; it's a single call: diff --git a/agent/BACKLOG.md b/agent/BACKLOG.md index 9ce25ab..4403ee3 100644 --- a/agent/BACKLOG.md +++ b/agent/BACKLOG.md @@ -22,22 +22,7 @@ next, in what order*. ## NOW -### 6. Full docs review & restructure — sliced, one slice per iteration -ROADMAP § Full docs review. Done: the roadmap/backlog split (this file); -slice (a) option-surface reconcile — README tables fixed (9 gaps) and -the diff made permanent as the `option-docs` flake check (eval-walked -surface vs tables, catches stale rows too); slice (b) drift pass over -docs/OVERRIDES.md, docs/TESTING.md, templates/downstream/README.md — -every factual claim spot-checked against the tree, all held; fixed the -two gaps (OVERRIDES now routes to `nomarchy.monitors`; TESTING §1 lists -the shell-syntax check its CI § claimed); slice (d) recovery runbook — -docs/RECOVERY.md (theme/HM generations → greetd journals → boot an older -generation → snapper restore/rollback → nixos-enter), linked from the -README tree + §5. Remaining: -- **(c) install/first-run story** read end to end (README install §§ + - template README as one narrative; fix the seams) — the last slice. -Site-vs-markdown is a Decision (below). **Verify:** V0; (c) against the -live tree, not memory. +*(empty — NEXT's top item is the queue head)* ## NEXT diff --git a/agent/JOURNAL.md b/agent/JOURNAL.md index 321508c..526655f 100644 --- a/agent/JOURNAL.md +++ b/agent/JOURNAL.md @@ -17,6 +17,24 @@ Template: --- +## 2026-07-04 — docs slice (c): install story — item 6 COMPLETE (iteration #16) +- **Task:** BACKLOG NOW#6 slice (c), the last one — install/first-run + narrative end to end. +- **Did:** read README §2 (ISO/installer) → §3 (downstream) → template + README as one story; checked the facts en route: mkFlake's arg + surface == the §3 table (src/username/hardwareProfile/system, lib.nix), + disko really makes @snapshots + the hibernation swapfile, .#default / + .#me names consistent. One seam fixed: §3 showed `nix flake init -t` + but never handed off to the template README's six first-run steps — + connective paragraph added (+ "the installer does all of this"). + Item 6 done → deleted from BACKLOG (NOW now empty); ROADMAP § Full + docs review flipped to ✓ with the slice summary. +- **Verified:** V0 (docs-only) — flake check clean pre-commit. +- **Pending:** docs-site-vs-Markdown stays a Decision. +- **Next suggestion:** NEXT#8 (viewers + mime defaults) is the new queue + head; note its "Default browser" Decision dependency — the mime module + half can proceed with mkDefault degradation regardless. + ## 2026-07-04 — docs slice (d): recovery runbook (iteration #15, item 6d) - **Task:** BACKLOG NOW#6 slice (d) — write the undo story. - **Did:** docs/RECOVERY.md, symptom-ordered: (1) bad theme/HM change → diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 034aa6f..18f20fc 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -353,18 +353,15 @@ how to override it. Items marked ✓ are shipped. hand-formatting, so `nixfmt-rfc-style --check` flags ~33 files. Adopting a formatter would be a one-time repo-wide reformat that flattens that alignment — a maintainer call, not a silent cleanup, so left untouched. -- **Full docs review & restructure:** a dedicated pass over all the prose, - not just the code-adjacent cleanup the repo-sanitize item covers. The - README has grown to ~540 lines with a ~200-line roadmap inline — the - biggest single move is likely **splitting the roadmap out** (e.g. - `ROADMAP.md` / `docs/`) so the README stays a focused "what it is / how - to install / how to override" entry point. Also: reconcile every option - table against the live `nomarchy.*` surface (snapper and others are - missing); a pass over `docs/OVERRIDES.md` + `docs/TESTING.md` and the - `templates/downstream/README.md` for drift; check the install/first-run - story reads cleanly end to end; and decide whether anything wants a real - docs site vs. staying Markdown-in-repo. Pairs with the first-boot welcome - and control-center items (shared "how do I…" surface). +- ✓ **Full docs review & restructure** (completed 2026-07-04 in four + slices): the roadmap/backlog split (this file + agent/BACKLOG.md); + option tables reconciled with the live surface and guarded permanently + by `checks.option-docs`; drift pass over OVERRIDES/TESTING/template + README (claims held; two gaps fixed); the install/first-run story now + hands off README §3 → template README explicitly; and a new + **docs/RECOVERY.md** runbook (generations → journals → older boot + generation → snapper → nixos-enter). Still open, deliberately: the + docs-site-vs-Markdown call (BACKLOG § Decisions). - **Laptop power / battery management:** a real power story behind a `nomarchy.system.power.*` surface (`modules/nixos/power.nix`), replacing the old "only `services.upower` for Waybar reporting" baseline: