docs: factual-drift pass + i2c option docs (#47, #48)
Some checks failed
Check / eval (push) Has been cancelled
Some checks failed
Check / eval (push) Has been cancelled
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>
This commit is contained in:
Bernardo Magri
32
README.md
32
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,
|
||||
retro-82, summer-day, summer-night). Custom user themes can live in
|
||||
Five themes ship a `waybar.css` identity (summer-day, summer-night,
|
||||
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
|
||||
|
||||
@@ -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/*,
|
||||
|
||||
@@ -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
|
||||
and executive-slate (the parity rule).
|
||||
config **and** every `waybar.jsonc` whole-swap — summer-day, summer-night,
|
||||
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.
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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" ];
|
||||
};
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
# exists to test the distro end-to-end on real hardware.
|
||||
# without touching the disk. The live session bundles nomarchy-install
|
||||
# (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
|
||||
|
||||
@@ -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)"; }
|
||||
|
||||
@@ -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
|
||||
'';
|
||||
|
||||
@@ -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)
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user