docs: factual-drift pass + i2c option docs (#47, #48)

Fix documentation drift (each claim verified against code): theme count
21→24; waybar whole-swap lists (waybar.css=5 incl. neon-glass vs
waybar.jsonc parity=4 + boreal); idle "suspend 30"→"15 min battery-only";
Tailscale sudo→operator; hosts/live.nix "No installer yet" header; link
docs/MIGRATION.md + fix its placeholder URL; README layout tree
(+doctor/control-center/battery-notify); OVERRIDES swappy→satty; document
always-on home pieces. String fixes: keybind cheatsheet
nmtui→networkmanager_dmenu; complete nomarchy-menu usage string
(+doctor/firmware/controlcenter/rollback). Add README rows for
nomarchy.hardware.i2c.* (#48) — closes checks.option-docs.

Implemented by a worktree agent; diff reviewed and cherry-picked.
Verified V0 (flake check) + checks.option-docs green + V1 (HM build).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -36,7 +36,7 @@ Flat on purpose. Two module trees, one options file each, no hidden layers.
 ├── flake.nix                      # inputs + the downstream API (exports below)
 ├── lib.nix                        # nomarchy.lib.mkFlake — one-call downstream wrapper
 ├── theme-state.json               # ★ THE single source of truth (git-tracked!)
-├── themes/                        # 21 presets: <slug>.json + optional <slug>/ assets
+├── themes/                        # 24 presets: <slug>.json + optional <slug>/ assets
 │   ├── nord.json                  #   palette (required, works alone)
 │   └── nord/                      #   assets (optional, fixed filenames)
 │       ├── backgrounds/           #     wallpapers (auto-picked, SUPER+SHIFT+T cycles)
@@ -62,6 +62,7 @@ Flat on purpose. Two module trees, one options file each, no hidden layers.
 │       ├── keybinds.nix           #   single source: Hyprland binds + SUPER+? sheet
 │       ├── swaync.nix             #   notifications, same JSON
 │       ├── idle.nix               #   hyprlock + hypridle, same JSON
+│       ├── battery-notify.nix     #   low-battery toasts at the bar's thresholds
 │       ├── yazi.nix               #   flagship TUI file manager + plugins
 │       ├── osd.nix                #   swayosd volume/brightness OSD
 │       ├── shell.nix              #   zsh + starship + bat/eza/zoxide
@@ -72,7 +73,10 @@ Flat on purpose. Two module trees, one options file each, no hidden layers.
 │   └── live.nix                   # bootable live ISO (try the distro, no install)
 ├── pkgs/
 │   ├── nomarchy-theme-sync/       # state writer + rebuild dispatcher (Python)
-│   └── nomarchy-install/          # live-ISO installer (gum + disko + mkFlake)
+│   ├── nomarchy-install/          # live-ISO installer (gum + disko + mkFlake)
+│   ├── nomarchy-doctor/           # read-only health sheet, one command per failure
+│   ├── nomarchy-control-center/   # TUI settings front-end over nomarchy-theme-sync (gum)
+│   └── nomarchy-battery-notify/   # low-battery toast watcher backing battery-notify.nix
 ├── templates/downstream/          # machine flake SoT (`flake init` + installer copy/patch)
 ├── docs/                          # human docs — map: docs/README.md
 │   ├── VISION.md                  #   product themes toward v1.0 (not a queue)
@@ -141,6 +145,10 @@ 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.)
 
+Already running NixOS on this machine? No reinstall needed — adopt
+Nomarchy in place, reusing your existing `hardware-configuration.nix`:
+**[docs/MIGRATION.md](docs/MIGRATION.md)**.
+
 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:
@@ -219,7 +227,7 @@ two tables below are split along exactly that line.
 | `nomarchy.rofi.enable` | `true` | Themed rofi launcher + `nomarchy-menu` dispatcher |
 | `nomarchy.swaync.enable` | `true` | swaync notifications, themed |
 | `nomarchy.batteryNotify.enable` | `true` | Low-battery toasts at the bar's thresholds — 25% low, 10% critical (stays up until dismissed); silent no-op on machines without a battery |
-| `nomarchy.idle.enable` | `true` | hyprlock + hypridle (idle lock 5 min, display off 10, suspend 30) |
+| `nomarchy.idle.enable` | `true` | hyprlock + hypridle (idle lock 5 min, display off 10, suspend 15 min — battery-only) |
 | `nomarchy.yazi.enable` | `true` | yazi TUI file manager, themed + curated plugins |
 | `nomarchy.osd.enable` | `true` | swayosd on-screen display for volume/brightness/mute |
 | `nomarchy.shell.enable` | `true` | zsh + starship prompt + bat/eza/zoxide (zsh is the default login shell) |
@@ -237,6 +245,14 @@ two tables below are split along exactly that line.
 | `nomarchy.themesDir` | Nomarchy's `themes/` | Where per-theme app overrides are probed |
 | `nomarchy.package` | overlay's `nomarchy-theme-sync` | The theme/state tool package, overridable if you fork it |
 
+**Always-on, no toggle by design:** `services.cliphist`, `services.udiskie`
+(automount + safe-removal toasts) and `services.easyeffects` (mic noise
+cancellation) ship unconditionally — small, low-risk pieces with no
+Nomarchy-specific config behind them (the toggle-vs-package rule in
+`agent/CONVENTIONS.md`). Disable one from `home.nix` with the plain HM
+option, e.g. `services.easyeffects.enable = lib.mkForce false;` — see
+**[docs/OVERRIDES.md](docs/OVERRIDES.md)**.
+
 **`system.nix`** (NixOS — the machine):
 
 | Option | Default | Purpose |
@@ -264,7 +280,9 @@ two tables below are split along exactly that line.
 | `nomarchy.hardware.npu.enable` | `false` | Opt-in/experimental: load the on-die NPU driver (`amdxdna`/`intel_vpu`); userspace runtime is BYO |
 | `nomarchy.hardware.latestKernel` | `false` | Opt-in: ship `linuxPackages_latest` instead of the default kernel — for very new hardware whose drivers landed recently |
 | `nomarchy.hardware.camera.hideIrSensor` | `false` | Hide a dual-sensor webcam's IR node from PipeWire so apps only ever see the colour camera (the "second, dark Integrated Camera"); installer-set on a paired RGB+IR webcam. `/dev/video*` stays open, so Howdy-style face unlock still works; `.irMatch` overrides the IR-name regex |
-| `nomarchy.services.tailscale.enable` | `false` | Opt-in: Tailscale mesh VPN (then `sudo tailscale up`) |
+| `nomarchy.hardware.i2c.enable` | `false` | I2C devices support — access to `/dev/i2c-*` (RGB controllers, sensors, DDC/CI monitor control) |
+| `nomarchy.hardware.i2c.ddcci` | `false` (distro default: **`true`**) | the ddcci-driver kernel module, exposing external monitors as standard backlight devices via DDC/CI so brightness keys and swayosd natively control them |
+| `nomarchy.services.tailscale.enable` | `false` | Opt-in: Tailscale mesh VPN — the login user is made the operator, so `tailscale up/down/set` and the System › VPN menu work without sudo |
 | `nomarchy.services.syncthing.enable` | `false` | Opt-in: Syncthing file sync as the login user (GUI at `127.0.0.1:8384`) |
 | `nomarchy.services.podman.enable` | `false` | Opt-in: rootless Podman (`docker` aliased to it) |
 | `nomarchy.services.flatpak.enable` | `false` | Opt-in: Flatpak + the Flathub remote |
@@ -365,15 +383,15 @@ per theme — a single place to look, unlike the old distro's split:
 | `waybar.jsonc` | whole-swap for the bar *layout* (must be plain JSON) |
 | `rofi.rasi` | **whole-swap**: replaces the generated launcher/menu theme entirely |
 
-Six ported themes ship a `waybar.css` identity (catppuccin, lumon, nord,
+Five themes ship a `waybar.css` identity (summer-day, summer-night,
-retro-82, summer-day, summer-night). Custom user themes can live in
+executive-slate, boreal, neon-glass). Custom user themes can live in
 `$NOMARCHY_PATH/themes/` (preset lookup) and `nomarchy.themesDir` (eval-time
 asset probe).
 
 ## 5. Day-to-day
 
 ```sh
-nomarchy-theme-sync list               # 21 presets (nord, gruvbox, rose-pine, …)
+nomarchy-theme-sync list               # 24 presets (nord, gruvbox, rose-pine, …)
 nomarchy-theme-sync apply kanagawa     # whole desktop, one generation (~a switch)
 nomarchy-theme-sync set ui.gapsOut 16  # tweak one knob (also a switch)
 nomarchy-theme-sync bg next            # cycle wallpapers — instant, no rebuild

agent/BACKLOG.md

@@ -114,32 +114,6 @@ Next slice: on hardware, run `hyprctl clients` while each is open, read
 the real `class`, then append rules. Also revisit whether blueman/s-c-p
 actually float once seen (regex tolerance for the `.…-wrapped` form).
 
-### 47. Docs + string factual-drift pass (promoted 2026-07-09)
-Pure docs (V0) plus two `.nix` string fixes (V1: HM build). One pass or split:
-- **README/docs drift:** theme count **21 → 24** (`README.md`,
-  `docs/TESTING.md`, `templates/downstream/README.md`); waybar whole-swap
-  list → summer-day/summer-night/executive-slate/boreal/neon-glass (drop the
-  catppuccin/lumon/nord/retro-82 stubs); idle table "suspend **30**" →
-  **15 min battery-only** (`idle.nix`); Tailscale row `sudo tailscale up` →
-  operator/no-sudo; `hosts/live.nix` header "No installer yet" → current;
-  CONVENTIONS parity list add **boreal**.
-- **Secondary docs:** README layout tree add doctor/control-center/
-  battery-notify; link `docs/MIGRATION.md` from README nav + fix its
-  placeholder flake-init URL; OVERRIDES.md screenshot pipe swappy → **satty**.
-- **Document always-on home pieces:** easyeffects/udiskie/cliphist ship with
-  no toggle by design — a short README note + override pointer.
-- **String fixes (V1):** keybind cheatsheet `desc = "Network (nmtui)"` →
-  networkmanager_dmenu (`keybinds.nix`); complete the `nomarchy-menu` usage
-  string (add doctor/controlcenter/rollback/firmware/…, `rofi.nix`).
-Verify any documented command by running it.
-
-### 48. Document `nomarchy.hardware.i2c.*` — close checks.option-docs (promoted 2026-07-09)
-`nomarchy.hardware.i2c.enable` and `.ddcci` (`modules/nixos/hardware.nix`)
-have no README table rows → `checks.option-docs` is red. Add rows (+ note the
-effective default: option default `false` but distro `mkDefault true` for
-ddcci in `modules/nixos/default.nix`). Optional template opt-in comment.
-V0 — `checks.option-docs` verifies (pure runCommand, no VM).
-
 ### 49. Pure-contract `checks.*` batch — no VM (promoted 2026-07-09)
 Add pure runCommand checks (all V0):
 - Expand CI `py_compile` to **all** tracked `*.py` (compose-lock, tools/*,

agent/CONVENTIONS.md

@@ -45,8 +45,8 @@ those, it probably shouldn't exist.
 - **Waybar:** new indicators self-gate (hidden when irrelevant), use
   named `writeShellScriptBin`s on PATH (so static configs can exec them
   by bare name), and are added to **both** the generated `waybar.nix`
-  config **and** every `waybar.jsonc` whole-swap — summer-day, summer-night
+  config **and** every `waybar.jsonc` whole-swap — summer-day, summer-night,
-  and executive-slate (the parity rule).
+  executive-slate and boreal (the parity rule).
 - **Theming:** every new visual surface consumes the palette from the
   state JSON. There is no second renderer to keep in sync — add the key
   to the JSON, consume it in the module.

agent/JOURNAL.md

@@ -17,6 +17,24 @@ Template:
 
 ---
 
+## 2026-07-09 — #47+#48 docs/string factual-drift pass (delegated, worktree)
+- **Task:** NEXT #47 (docs + string drift) + #48 (i2c option-docs). Delegated
+  to a worktree sonnet agent, parallel with #46 VM + the #49 agent, no shared
+  files.
+- **Did:** Agent fixed every drift after verifying each claim against code:
+  theme count 21→24 (README ×3, TESTING, template), waybar whole-swap list
+  (correctly split waybar.css=5 incl. neon-glass vs waybar.jsonc parity=4 +
+  boreal), idle 30→15min-battery-only, Tailscale sudo→operator, live.nix
+  header, MIGRATION link + URL, README layout tree (+doctor/CC/battery-notify),
+  OVERRIDES swappy→satty, always-on note; keybind nmtui→networkmanager_dmenu;
+  nomarchy-menu usage string (+doctor/firmware/controlcenter/rollback). Added
+  README i2c rows (#48). Reviewed the diff, cherry-picked onto main.
+- **Verified:** V0 flake check green; `checks.option-docs` now **green** (85
+  options, no stale rows) — closes #48; V1 HM generation builds (usage string +
+  keybind label confirmed in the built output). Re-run on main after cherry-pick.
+- **Pending:** none — docs/config, fully verified at their tier.
+- **Next suggestion:** land #49 (checks batch); then #50.
+
 ## 2026-07-09 — Promote V0/V1 PROPOSED items → NEXT #47–50 (Bernardo-directed)
 - **Task:** Bernardo asked to bump the non-V2 PROPOSED items into NEXT (to
   feed parallel worktree agents that can't touch the VM). Triage is his call;

docs/MIGRATION.md

@@ -88,7 +88,8 @@ before anything touches the running system.
 git clone https://git.bemagri.xyz/bernardo/nomarchy.git ~/nomarchy-migrate
 cd ~/nomarchy-migrate
 # Or start from the downstream template:
-#   nix flake init -t github:.../nomarchy   (produces flake.nix/system.nix/home.nix/…)
+#   nix flake init -t "git+https://git.bemagri.xyz/bernardo/nomarchy.git?ref=v1"
+#   (produces flake.nix/system.nix/home.nix/…)
 ```
 
 A Nomarchy downstream flake owns exactly five files. Assemble them:

docs/OVERRIDES.md

@@ -66,7 +66,7 @@ autostarts run *alongside* the defaults:
   wayland.windowManager.hyprland.settings = {
     bind = [
       "$mod, B, exec, firefox"
-      "$mod SHIFT, S, exec, grim -g \"$(slurp)\" - | swappy -f -"
+      "$mod SHIFT, S, exec, grim -g \"$(slurp)\" - | satty --filename -"
     ];
     exec-once = [ "nm-applet --indicator" ];
   };

docs/TESTING.md

@@ -69,7 +69,7 @@ Work through these in order; each one exercises a different layer.
 | 2 | Waybar shows at top, themed (blue accent on dark) | HM waybar module, palette baking |
 | 3 | `SUPER+Return` opens Ghostty with the default theme colors (Boreal) | terminal default, ANSI palette |
 | 4 | `btop` in the terminal is themed | per-theme asset baking |
-| 5 | `nomarchy-theme-sync list` prints 21 presets | package, baked themes dir |
+| 5 | `nomarchy-theme-sync list` prints 24 presets | package, baked themes dir |
 | 6 | `nomarchy-theme-sync apply gruvbox` → state written, `home-manager switch` runs, desktop re-themes, wallpaper changes | the whole engine: state write, pure eval, HM rebuild, wallpaper hook |
 | 7 | `SUPER+SHIFT+T` cycles wallpapers instantly (try `tokyo-night` for 4, or `boreal` for its set) | the runtime wallpaper path |
 | 8 | `nomarchy-theme-sync apply summer-night` → after the switch the bar has its own identity (light bar, different styling) | whole-swap waybar.css assets |

hosts/live.nix

@@ -1,6 +1,7 @@
 # Live ISO host — boot the full Nomarchy desktop from a USB stick or QEMU
-# without touching the disk. No installer yet (see roadmap); this target
+# without touching the disk. The live session bundles nomarchy-install
-# exists to test the distro end-to-end on real hardware.
+# (gum + disko + mkFlake) for a real install; this target also lets you
+# test the distro end-to-end on real hardware before committing to disk.
 { lib, pkgs, username, nomarchySrc, ... }:
 
 let

modules/home/keybinds.nix

@@ -48,7 +48,7 @@
     { mods = "$mod CTRL";   key = "W";      action = "exec, nomarchy-menu web";       desc = "Web search"; }
     { mods = "$mod CTRL";   key = "F";      action = "exec, nomarchy-menu files";     desc = "File search"; }
     { mods = "$mod CTRL";   key = "E";      action = "exec, nomarchy-menu emoji";     desc = "Emoji picker"; }
-    { mods = "$mod CTRL";   key = "N";      action = "exec, nomarchy-menu network";   desc = "Network (nmtui)"; }
+    { mods = "$mod CTRL";   key = "N";      action = "exec, nomarchy-menu network";   desc = "Network (networkmanager_dmenu)"; }
     { mods = "$mod CTRL";   key = "B";      action = "exec, nomarchy-menu bluetooth"; desc = "Bluetooth"; }
     { mods = "$mod CTRL";   key = "S";      action = "exec, nomarchy-menu capture";   desc = "Screenshot / capture"; }
     { mods = "$mod CTRL";   key = "P";      action = "exec, nomarchy-menu colorpicker"; desc = "Color picker (→ clipboard)"; }

modules/home/rofi.nix

@@ -872,7 +872,7 @@ ${themeRows}
         esac ;;
 
       *)
-        echo "usage: nomarchy-menu [lookfeel|tools|system|power|power-profile|powermgmt|batterylimit|theme|clipboard|calc|files|emoji|web|network|bluetooth|audio|display|display-profile|printers|capture|colorpicker|keybinds|ask|dnd|nightlight|autotimezone|autocommit|vpn|snapshot]" >&2
+        echo "usage: nomarchy-menu [lookfeel|tools|system|power|power-profile|powermgmt|batterylimit|theme|clipboard|calc|files|emoji|web|network|bluetooth|audio|display|display-profile|printers|capture|colorpicker|keybinds|ask|dnd|nightlight|autotimezone|autocommit|vpn|snapshot|doctor|firmware|controlcenter|rollback]" >&2
         exit 64 ;;
     esac
   '';

templates/downstream/README.md

@@ -25,7 +25,7 @@ keyboard, detected hardware, password hash, …). Keep commented opt-ins and
 Day-to-day:
 
 ```sh
-nomarchy-theme-sync list             # 21 shipped presets
+nomarchy-theme-sync list             # 24 shipped presets
 nomarchy-theme-sync apply gruvbox    # writes state + home-manager switch
 nomarchy-theme-sync bg next          # cycle wallpapers (instant, no rebuild)
 ```