Bernardo Magri
786a8ad30e
Completes the three dark/light pairs for v1 (batch: 0ba1762, e51c8a7). Kiln is a potter's workshop at night, lit only by the kiln: warm near-black (#1D1815), copper accent (#D68C5C, 6.5:1), brass accentAlt, CaskaydiaCove, rounding 8. Kiln Clay is the same studio at midday: cream plaster (#F4EDE3), espresso text (11.1:1 AAA), fired-copper accent (#A34F1F, 4.89:1), brick-red bad. Both waybars are a NEW whole-swap identity — 'the workbench': ONE continuous floating plank (window#waybar carries the surface, modules transparent) — deliberately distinct from boreal's three pills and slate's edge-to-edge strip; module set verbatim-parity with the generated config. Matched rofi, btop themes. The wallpapers share identical ring geometry — banked-coal heat rings at night, terracotta glaze rings at noon — so the autoTheme flip visibly rhymes. Sync sweep in this commit (LOOP §5): README 24->28 presets + the whole-swap list now names the three pairs; CONVENTIONS waybar parity list gains the four new slugs; OVERRIDES autoTheme table points at the pairs; HARDWARE-QUEUE gains the batch V3 entry (real-GL blur, btop visual, launcher grid, tray menus, pair flip); BACKLOG files #153 (PROPOSED: per-theme desktop widgets — the conky idea, engine spike needed, not v1). Verification: V2. Full targeted set green on the final tree: theme-contrast, theme-wholeswap (previews + backgrounds + CSS self-containment), waybar-language, waybar-swap-env, rofi-text-width, state-sync-validate, auto-theme VM; nix flake check --no-build green. Visual protocol: theme-shot VM desktop + menu viewed for BOTH themes (plank renders as one island, copper/terracotta semantics, legible menus; /nix/store/2fizd945...theme-shot-kiln and /nix/store/0126yd48...theme-shot-kiln-clay). audit-theme-design: CVD-only findings (≤ executive-slate's own baseline); ANSI slots in-family after the magenta retune. V3 pending: HARDWARE-QUEUE entry above. btop visual is VM-blocked (GL terminal never starts under softGL) — file-level assertions only, listed for hardware. Design + wallpapers on Fable; assets by a Sonnet subagent to a written identity spec; reviewed on Fable. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
76 lines
4.0 KiB
Markdown
76 lines
4.0 KiB
Markdown
# Conventions — how Nomarchy code is written
|
||
|
||
The standing rules an agent must follow while coding. GOALS.md says what
|
||
we're building; this says how. Details/rationale live in docs/ROADMAP.md's
|
||
decision records and the README.
|
||
|
||
## Repo layout (the rule of thumb)
|
||
`modules/` is the distro (reusable, no machine specifics) · `hosts/` is a
|
||
machine · `themes/` is data · `pkgs/` is code · `tools/` is maintainer-only
|
||
· `agent/` is loop state. If a new file doesn't obviously belong to one of
|
||
those, it probably shouldn't exist.
|
||
|
||
## Nix style
|
||
- **No formatter.** Files use deliberate aligned hand-formatting — match
|
||
the surrounding style exactly; never reflow a file you're only touching
|
||
a line of.
|
||
- Distro defaults use `lib.mkDefault` so a plain downstream assignment
|
||
wins; bind/exec lists concatenate. Behaviour options overridable,
|
||
appearance flows from the state JSON.
|
||
- Options live in the existing surfaces: `nomarchy.system.*` /
|
||
`nomarchy.hardware.*` / `nomarchy.services.*` (NixOS, `system.nix`),
|
||
everything else `nomarchy.*` (HM, `home.nix`). Update the README tables
|
||
when the surface changes.
|
||
|
||
## Feature design
|
||
- **In-flake state:** any user-settable config gets a menu writer that
|
||
lands it in `state.json` (`settings.*`), git-tracked. No
|
||
`~/.local/state`, no side files. Instant-effect where possible
|
||
(`--no-switch` + flip the service; the service reads the *live* working
|
||
tree at start — the night-light `ExecCondition` pattern). Rebuild-baked
|
||
values graduate via `mkDefault` reads of the settings key.
|
||
- **Toggle vs package:** a `nomarchy.*` toggle only when there's real
|
||
config behind it (units, groups, udev, firewall). A bare package goes
|
||
in the downstream template's `home.packages` — opt-out is deleting the
|
||
line.
|
||
- **Opt-in features** ship a commented example in
|
||
`templates/downstream/home.nix` or `system.nix`. That template is the
|
||
single source of truth for machine files: `nomarchy-install` copies it
|
||
and patches install-time values only (never a thinner second catalog).
|
||
- **Menu:** new entries go in the right submenu (Tools › / System ›; root
|
||
stays six entries), end lists with the shared `↩ Back`, self-gate on
|
||
the feature's availability, and add the direct
|
||
`SUPER+CTRL+<mnemonic>` bind in `keybinds.nix` (single source — it
|
||
feeds both Hyprland and the SUPER+? cheatsheet).
|
||
- **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,
|
||
executive-slate, executive-ivory, boreal, boreal-dawn, kiln and
|
||
kiln-clay (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.
|
||
|
||
## Testing
|
||
- docs/TESTING.md is canonical; LOOP.md's ladder (V0–V3) sets the
|
||
required tier. Cheap first: `nix flake check --no-build`, `bash -n`,
|
||
`py_compile`.
|
||
- Prefer a permanent `checks.*` runNixOSTest over a one-off manual poke;
|
||
reusable recipes (headless Hyprland with software GL, QMP screenshots,
|
||
udev-event fakes) are indexed in MEMORY.md and demonstrated by the
|
||
existing checks (`distro-id`, `hardware-toggles`,
|
||
`battery-charge-limit`).
|
||
- The honesty rule: report exactly what you verified and at which tier.
|
||
|
||
## Git
|
||
- `main` is development (direct commits, pushed); `v1` is the release
|
||
pointer — **human-only, fast-forward-only, never touched by agents**.
|
||
- Commit style: `feat|fix|test|docs|chore(scope): summary`, body with
|
||
what/why + verification tier + what remains. Bookkeeping (`agent/`
|
||
updates) rides in the same commit as the change.
|
||
- `flake.lock` moves only when the task *is* a lock bump. The release
|
||
inputs stay within their pinned release branches; the `nixpkgs-unstable`
|
||
input (#134, feeds `unstable.*`) tracks `nixos-unstable` and bumps
|
||
together with the rest — never alone, never `nix flake update`.
|