From b0b8a9a09bbdd7d774a908bab2998e7d945df4eb Mon Sep 17 00:00:00 2001 From: Bernardo Magri Date: Sat, 4 Jul 2026 19:36:01 +0100 Subject: [PATCH] docs(review): drift pass over OVERRIDES/TESTING/template README (item 6b) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Slice (b) of the docs review: every factual claim in the three docs spot-checked against the tree (mkDefault sites, bind priority, CLI keys, awww naming, preset/wallpaper counts, summer-night's light bar, live-ISO monitor rule, CI workflow, QEMU GL flags, template steps) — all held. Two gaps fixed: OVERRIDES §2 predated nomarchy.monitors and never routed readers to it (added, plus a quick-reference row); TESTING §1 didn't list the shell-syntax check that §1b says CI runs (added bash -n). Co-Authored-By: Claude Fable 5 --- agent/BACKLOG.md | 9 +++++---- agent/JOURNAL.md | 17 +++++++++++++++++ docs/OVERRIDES.md | 8 +++++++- docs/TESTING.md | 1 + 4 files changed, 30 insertions(+), 5 deletions(-) diff --git a/agent/BACKLOG.md b/agent/BACKLOG.md index 4513ae3..1f84503 100644 --- a/agent/BACKLOG.md +++ b/agent/BACKLOG.md @@ -26,10 +26,11 @@ next, in what order*. 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). Remaining slices: -- **(b) drift pass** over docs/OVERRIDES.md, docs/TESTING.md, - templates/downstream/README.md — read each against the current tree, - fix what lies. +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). Remaining slices: - **(c) install/first-run story** read end to end (README install §§ + template README as one narrative; fix the seams). - **(d) recovery runbook** — short doc: desktop won't start → boot an diff --git a/agent/JOURNAL.md b/agent/JOURNAL.md index 92f25cc..9d14016 100644 --- a/agent/JOURNAL.md +++ b/agent/JOURNAL.md @@ -17,6 +17,23 @@ Template: --- +## 2026-07-04 — docs slice (b): drift pass (iteration #14, item 6b) +- **Task:** BACKLOG NOW#6 slice (b) — OVERRIDES.md / TESTING.md / + templates/downstream/README.md vs the live tree. +- **Did:** spot-checked every factual claim: mkDefault sites (hyprland + behaviour knobs, ghostty paddings, waybar mainBar/style), bind-list + normal priority, `set ui.gapsOut` CLI key, awww(-daemon) naming, + 21 presets, tokyo-night's 4 wallpapers, summer-night's light @fg bar, + live `,highres` mkForce, .gitea/workflows/check.yml, QEMU gl flags, + template `.#me` + ~/.nomarchy/NOMARCHY_PATH. All accurate. Fixed the + two real gaps: OVERRIDES §2 predated `nomarchy.monitors` (now routes + there + quick-ref row); TESTING §1 lacked the shell-syntax check §1b + claims CI runs (added `bash -n`). +- **Verified:** V0 (docs-only; flake untouched — check run pre-commit). +- **Pending:** slices (c) install story, (d) recovery runbook. +- **Next suggestion:** item 6 slice (c) or (d) — (d) is self-contained + and ships user value (the runbook). + ## 2026-07-04 — docs slice (a): option-surface reconcile (iteration #13, item 6a) - **Task:** BACKLOG NOW#6, first slice — README tables vs live options. - **Did:** split item 6 into slices (a–d) in BACKLOG. Reconciled: 9 diff --git a/docs/OVERRIDES.md b/docs/OVERRIDES.md index cc917d3..ddd97a9 100644 --- a/docs/OVERRIDES.md +++ b/docs/OVERRIDES.md @@ -39,7 +39,7 @@ in your `home.nix` wins — no `mkForce` needed: input.follow_mouse = 0; # was 1 input.touchpad.natural_scroll = false; misc.disable_splash_rendering = false; - monitor = [ "DP-1,2560x1440@144,0x0,1" ]; # replaces the default rule + monitor = [ "DP-1,2560x1440@144,0x0,1" ]; # raw rule — replaces the default animations.enabled = false; }; @@ -50,6 +50,11 @@ in your `home.nix` wins — no `mkForce` needed: } ``` +For monitor layout, prefer the friendlier **`nomarchy.monitors`** (a list of +per-output submodules — resolution/position/scale/rotation — turned into +Hyprland rules and applied on hotplug; run `nwg-displays` to find the values +interactively). Assigning `settings.monitor` directly, as above, replaces it. + ### Adding vs. overriding lists `bind`, `bindel`, `bindl`, `bindm` and `exec-once` are lists kept at normal @@ -140,6 +145,7 @@ value is theme-owned at normal priority — either change it via the CLI (§1) o |---|---| | Change gaps / colors / rounding / fonts | `nomarchy-theme-sync set …` or `apply` | | Change input / misc / monitor / animations / terminal chrome | plain assignment in `home.nix` | +| Arrange monitors declaratively | `nomarchy.monitors` (values via `nwg-displays`) | | Add keybinds / autostarts | add to the `bind` / `exec-once` list (concatenates) | | Replace all keybinds | `bind = lib.mkForce [ … ]` | | Hardcode an appearance value against the theme | `lib.mkForce` in `home.nix` | diff --git a/docs/TESTING.md b/docs/TESTING.md index af301db..e4b4c62 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -14,6 +14,7 @@ than claiming success. "All Nix files parse" is not "the bar renders." nix flake check --no-build # full module-system evaluation, no builds nix-instantiate --parse # syntax-only, works even on macOS python3 -m py_compile pkgs/nomarchy-theme-sync/nomarchy-theme-sync.py +bash -n