docs(agent): vendor-neutral agent docs — AGENTS.md entry, agent/ SoT, .claude shims

The repo is maintained by agents from multiple vendors, so agent
instructions move out of vendor-specific locations into shared,
git-tracked markdown:

- AGENTS.md is the new entry point for any harness; CLAUDE.md becomes a
  symlink to it (Claude Code keeps working unchanged).
- Skill bodies relocate to agent/: VERIFICATION.md (the enforcement
  rules, ex .claude/skills/nomarchy), DELEGATION.md (capability tiers
  light/standard/frontier, scout/runner role contracts, token economy,
  parallel fan-out — consolidates the CLAUDE.md model table, LOOP.md's
  economy section, and skill §6.5 into one place; vendor model names
  survive only in the per-harness mapping table), THEME-DESIGN.md
  (ex .claude/skills/theme, which previously lacked frontmatter).
- .claude/ shrinks to a thin Claude Code adapter: settings, subagent
  defs, and skill shims that route into agent/.
- Maps updated: agent/README.md (instructions vs state vs adapters),
  docs/README.md, README.md layout tree.

Cleanup: stale old_distro .gitignore entry dropped (dir long gone);
local result*/__pycache__ artifacts removed; JOURNAL.md rotated (29
recent entries kept, 120 older moved to agent/JOURNAL-ARCHIVE.md,
rotation rule documented in the header).

Verification: V0 (docs/meta only) — nix flake check --no-build exit 0
with the tracked symlink; grep sweep confirms no vendor model names
outside DELEGATION.md's mapping table.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

agent/DELEGATION.md

@@ -0,0 +1,112 @@
+# Delegation — capability tiers, roles, token economy
+
+How to spend model capacity in this repo, for **any** agent harness.
+Tasks are matched to capability *tiers*, not vendor model names; each
+harness maps tiers to its own models (table at the bottom). GOALS says
+what to build, CONVENTIONS how to write it — this says who does which
+part.
+
+## The dividing line: evidence vs judgment
+
+Cheap models gather evidence; they never make verification claims or
+design decisions. The following always stay on the **frontier** tier and
+are never delegated downward:
+
+- deciding what to test and the regression scope (VERIFICATION.md)
+- interpreting an ambiguous or flaky failure
+- viewing screenshots and judging visual quality — aesthetic judgment is
+  exactly what small models do badly, and it's load-bearing here
+- writing non-trivial Nix (module structure, overlays, cross-cutting
+  refactors)
+- the final diff review and report
+
+Product calls ("finish vs quarantine", promoting PROPOSED items) sit
+above even that: they belong to the human.
+
+## Tiers
+
+| Tier | Best for | Delegate to it? |
+|------|----------|-----------------|
+| **light** | bulk mechanical: search, summarize, audit sweeps, running the harness | freely — never for judgment |
+| **standard** | well-specified scoped edits, routine research | when the spec is already written |
+| **frontier** | design, novel code, ambiguous failures, taste | this is the loop's own tier |
+
+Reasoning effort: default moderate; go maximum only for the hardest
+calls. A frontier parent may spawn a frontier child for one hard call.
+Work above your tier gets returned, not attempted.
+
+## Standing roles
+
+Two mechanical roles exist for any harness that supports subagents
+(Claude Code implementations: `.claude/agents/`; other harnesses
+implement the same contracts in their own format):
+
+- **scout** (light, read-only): locate where things are defined, map
+  which files touch a subsystem, scan build logs / serial output for
+  error lines, docs-vs-code drift sweeps. Reports facts with paths and
+  line numbers, quotes the minimum snippet, says "not found" plainly —
+  never guesses, never recommends.
+- **runner** (light, executes): builds, VM boots, screenshot capture,
+  the scripted `tools/` checks. Headless and unattended, every wait
+  bounded by a timeout. Returns commands, exit codes, wall time, and
+  artifact paths — never marks anything passed or verified; the caller
+  makes the verification claim.
+
+Use them for pure information-gathering or pure execution instead of
+pulling bulk (log files, wide scans) into the main context. When a
+result surprises you, spot-check it yourself before building on it —
+cheap models are allowed to be wrong about hard things, which is
+precisely why they're not allowed to make claims.
+
+## Economy rules
+
+- **Only delegate when writing the spec is cheaper than doing the
+  work** — a spawned agent starts cold and must re-derive context. A
+  one-file read is cheaper done directly.
+- **Brief every child cold; point at the spec, don't restate it.** "The
+  spec is in `agent/BACKLOG.md` #NN — implement it" plus only the
+  *constraints* (scope files, branch, no-VM, no-push).
+- **Match the tier to the task, not the prestige.** An item whose spec
+  is already written (exact files, exact fixes) is standard-tier work;
+  reserve frontier children for genuine multi-step reasoning. This is
+  the single biggest saving.
+- The strong model writes the spec, reviews the result, and owns the
+  commit.
+
+## Fanning out parallel work (V0/V1, no VM)
+
+When several NEXT items are independent and don't need the VM, spread
+them across worktree-isolated subagents in parallel:
+
+- **Disjoint file lanes.** Partition items so no two agents touch the
+  same file (map the touched files first). If two items must share a
+  file (README, flake.nix, rofi.nix), give both to one agent or keep
+  one for yourself.
+- **Isolation + you own landing.** Each agent works in an isolated
+  worktree, commits to its own branch, and **never pushes or touches
+  `main`/`v1`**. You review each diff, cherry-pick onto `main`, and do
+  the bookkeeping — a single landing agent can't race itself. Clean up
+  worktrees and branches after landing.
+- **Lean on scriptable checks as primary evidence.** Where a
+  deterministic `tools/` check or `checks.*` guard already proves the
+  property, that near-free run *is* the V0/V1 evidence.
+- **Batch V2 at the end, once.** Delegated visual/behavioural items come
+  back "V2 pending"; collect the landed changes and do **one** VM pass
+  covering all of them — the VM render + screenshot review is the most
+  expensive step in the loop; amortise it.
+- **Re-verify on `main`, but leanly.** After landing, confirm the
+  agent's V0/V1 on the merged tree with a targeted build, not a full
+  re-run. Trust-but-spot-check scales; blind re-running doesn't.
+
+The judgment list above still holds: *you* review every diff before it
+lands.
+
+## Per-harness model mapping
+
+| Tier | Claude Code |
+|------|-------------|
+| light | `haiku` |
+| standard | `sonnet` |
+| frontier | the session's top model (`opus` and up) |
+
+Other harnesses: add a column when one is actually used on this repo.

agent/LOOP.md

@@ -2,12 +2,12 @@
 
 How an AI agent works on Nomarchy unattended. One **iteration** = pick one
 task, do it, verify it, commit it, record it. The protocol is
-runner-agnostic; the same iteration works under any of:
+harness- and vendor-agnostic; the same iteration works under any of:
 
-- **Interactive `/loop`** in a Claude Code session in this repo — the agent
-  self-paces iterations until stopped.
-- **Headless** (`claude -p`, cron/systemd-timer) — one invocation runs one
-  iteration (or a small fixed number) and exits.
+- **An interactive self-paced loop** in any agent harness (e.g. `/loop`
+  in Claude Code) — the agent iterates until stopped.
+- **Headless** (a one-shot CLI invocation, cron/systemd-timer) — one
+  invocation runs one iteration (or a small fixed number) and exits.
 - **A fresh manual session** — a human says "do a loop iteration"; the
   files below carry all the state, so any session can pick up where the
   last left off.
@@ -26,23 +26,25 @@ outside the checkout (the distro's own philosophy, applied to its agents).
 | `HARDWARE-QUEUE.md` | Pending on-hardware checks only Bernardo can run | Agents append, human checks off |
 | `CONVENTIONS.md` | Repo/design conventions to follow while coding | Human (agents propose edits) |
 
+Instructions live next to the state: `VERIFICATION.md` (enforcement),
+`DELEGATION.md` (tiers/roles/economy), `GOALS.md`, `THEME-DESIGN.md`.
+
 ## Model & token economy
 
-Spend expensive tokens on judgment, not mechanics.
+Spend expensive tokens on judgment, not mechanics. Tiers, roles, and the
+full delegation rules are in **`DELEGATION.md`**; the loop-specific
+habits:
 
 - **Plan and reason on the strong model.** Orientation, task selection,
   design, debugging, Nix eval semantics, verification judgment, and
   anything that would land in a commit unreviewed stay with the
-  top-tier model running the loop (Fable 5).
-- **Delegate mechanical subtasks to cheaper models.** When a subtask is
-  fully specified and needs no design judgment — grep/audit sweeps,
+  frontier-tier model running the loop.
+- **Delegate mechanical subtasks down.** When a subtask is fully
+  specified and needs no design judgment — grep/audit sweeps,
   README-option-table reconciliation, a repeated edit applied across
-  files, summarizing long logs or check output — hand it to a subagent
-  with a `model` override: `haiku` for search/summarize/audit, `sonnet`
-  for routine well-specified edits. The strong model writes the spec,
-  reviews the result, and owns the commit. Only delegate when writing
-  the spec is cheaper than doing the work — a spawned agent starts cold
-  and must re-derive context.
+  files, summarizing long logs or check output — hand it to a
+  light/standard-tier subagent per `DELEGATION.md`. The strong model
+  writes the spec, reviews the result, and owns the commit.
 - **Read narrowly.** Step 0's list is the whole orientation read (the
   *last 3–5 entries* of the journal, never the full file). Read large
   files by section, don't re-read what's already in context, and tail
@@ -50,7 +52,7 @@ Spend expensive tokens on judgment, not mechanics.
 - **Write tersely.** Journal entries follow the template and no more;
   commit bodies state what/why/tier, not a narrative.
 - **Headless runners** may run whole low-stakes iterations (QA sweeps,
-  docs-drift passes) on a cheaper `--model`; iterations touching
+  docs-drift passes) on a cheaper model; iterations touching
   `modules/` or `pkgs/` behavior keep the strong model.
 
 ## One iteration, step by step

agent/MEMORY.md

@@ -162,8 +162,9 @@ iteration would otherwise rediscover.
   effects carry a value, matchers take `match:` (§ windowrule migration).
 - grub `loadfont`s every `.pf2` in a theme dir — reuse a bundled DejaVu
   rather than shipping fonts (§ Distro branding).
-- `.claude/skills/*/SKILL.md` are now **tracked** (the `.gitignore`
-  `.claude/skills/` line was un-commented→removed, 7d52d4b) — commit skill
-  edits like any repo doc. Still never `git add -A` blindly: check
-  `git status --short` for genuine strangers first (`settings.local.json`,
-  harness-dropped files) and commit with explicit pathspecs (§ loop hygiene).
+- `.claude/skills/*/SKILL.md` are **tracked thin shims** — the actual
+  instruction bodies live vendor-neutrally in `agent/` (VERIFICATION,
+  DELEGATION, THEME-DESIGN); edit those, not the shims. Still never
+  `git add -A` blindly: check `git status --short` for genuine strangers
+  first (`settings.local.json`, harness-dropped files) and commit with
+  explicit pathspecs (§ loop hygiene).

agent/README.md

@@ -1,18 +1,26 @@
-# Agent loop state
+# Agent instructions + loop state
 
-Git-tracked state for autonomous and assisted work on Nomarchy.
-Protocol: **[LOOP.md](LOOP.md)**. Entry for most harnesses: repo-root
-**[CLAUDE.md](../CLAUDE.md)**.
+Everything an AI agent needs to work on Nomarchy, vendor-neutral and
+git-tracked. Protocol: **[LOOP.md](LOOP.md)**. Entry point for every
+harness: repo-root **[AGENTS.md](../AGENTS.md)**.
 
-## Files
+## Instructions (how to work)
 
 | File | Who writes | Role |
 |------|------------|------|
-| [LOOP.md](LOOP.md) | Human | One-iteration protocol (orient → pick → work → verify → commit → record) |
+| [LOOP.md](LOOP.md) | Human | One-iteration protocol (orient → pick → work → verify → commit → record) + the V0–V3 ladder |
+| [VERIFICATION.md](VERIFICATION.md) | Human (agents propose) | Enforcement: preflight, honesty rules, visual protocol, hardware-blocked checks, reporting |
+| [DELEGATION.md](DELEGATION.md) | Human (agents propose) | Capability tiers, scout/runner roles, token economy, parallel fan-out |
 | [GOALS.md](GOALS.md) | Human (agents propose) | Pillars, quality bars, non-goals |
 | [CONVENTIONS.md](CONVENTIONS.md) | Human (agents propose) | How to write code/menu/state while shipping |
+| [THEME-DESIGN.md](THEME-DESIGN.md) | Human (agents propose) | Theme/visual design instructions |
+
+## State (what's happening)
+
+| File | Who writes | Role |
+|------|------------|------|
 | [BACKLOG.md](BACKLOG.md) | Both | **Prioritized queue** — only executable work list |
-| [JOURNAL.md](JOURNAL.md) | Agents | Append-only iteration log (read last 3–5 entries) |
+| [JOURNAL.md](JOURNAL.md) | Agents | Append-only iteration log (read last 3–5 entries; older → [JOURNAL-ARCHIVE.md](JOURNAL-ARCHIVE.md)) |
 | [MEMORY.md](MEMORY.md) | Agents | Curated durable gotchas |
 | [HARDWARE-QUEUE.md](HARDWARE-QUEUE.md) | Agents append, human checks | On-hardware V3 tests only Bernardo can run |
 
@@ -24,15 +32,20 @@ Protocol: **[LOOP.md](LOOP.md)**. Entry for most harnesses: repo-root
 | [../docs/ROADMAP.md](../docs/ROADMAP.md) | Design history + shipped log |
 | [../docs/README.md](../docs/README.md) | Full docs map |
 
-## Claude Code only
+## Harness adapters (vendor-specific, thin)
 
-| Path | Role |
-|------|------|
-| [../.claude/settings.json](../.claude/settings.json) | Tool permissions |
-| [../.claude/agents/](../.claude/agents/) | `nomarchy-scout` / `nomarchy-runner` subagent defs |
+Shared content never lives in an adapter — adapters only register/route
+into the files above, in whatever format their harness requires.
 
-Do **not** put backlog items or vision text under `.claude/` — it is not
-shared with other agent runners.
+| Path | Harness | Role |
+|------|---------|------|
+| [../AGENTS.md](../AGENTS.md) | any | Entry point (`CLAUDE.md` is a symlink to it) |
+| [../.claude/settings.json](../.claude/settings.json) | Claude Code | Tool permissions |
+| [../.claude/agents/](../.claude/agents/) | Claude Code | `nomarchy-scout` / `nomarchy-runner` role defs (contracts in [DELEGATION.md](DELEGATION.md)) |
+| [../.claude/skills/](../.claude/skills/) | Claude Code | Skill shims → VERIFICATION/DELEGATION/THEME-DESIGN |
+
+Do **not** put backlog items, vision text, or policy under an adapter
+directory — it is not shared with other agent runners.
 
 ## Rules of thumb
 

agent/THEME-DESIGN.md

@@ -0,0 +1,49 @@
+# Theme design — instructions for visual work
+
+For creating, updating, refining, or troubleshooting Nomarchy themes and
+visual design. Act as an experienced UI/UX designer and Linux ricing
+expert for Wayland environments: themes here must be cohesive,
+intentional, and visually striking — aesthetics are a load-bearing
+feature of this distro (`agent/GOALS.md` pillar 4).
+
+## Context & architecture
+
+All theme data lives in `themes/` at the repo root — one JSON palette per
+theme plus per-app assets (whole-swap `waybar.jsonc`/CSS, btop themes,
+wallpapers). Before generating any new configuration, read the existing
+files there: learn how current themes are structured, how the syntax is
+formatted for each application, and how they integrate into the NixOS/HM
+modules. Always match the established pattern — there is no second
+theming pipeline (`agent/GOALS.md` non-goals), so a new visual surface
+consumes the palette from the state JSON, never a side file.
+
+## Design responsibilities
+
+1. **Holistic design:** a theme spans Hyprland (borders, shadows,
+   animations), Waybar, Ghostty, btop, fastfetch, rofi, and wallpaper —
+   one coherent identity, no unthemed corner.
+2. **Color theory:** create or adapt advanced palettes. Draw inspiration
+   from established aesthetics (Everforest, Nord, Gruvbox) or r/unixporn
+   trends, but innovate. Ensure harmony between background, foreground,
+   accents, and warning/error colors.
+3. **Typography & iconography:** pair UI and monospace fonts and icon
+   themes to the specific vibe of the palette.
+4. **Accessibility:** high contrast for text readability; status
+   information is never color-only (see `agent/MEMORY.md` design
+   invariants — glyph/shape carries state, and identity themes are
+   deliberately not traffic-lights).
+
+## Process
+
+1. Read `themes/` to understand the current structure.
+2. State the "vibe", the primary palette (hex codes), and typography
+   choices of the proposed design before implementing.
+3. Implement by generating or updating files within the `themes/`
+   structure, following `agent/CONVENTIONS.md` (Waybar parity rule:
+   whole-swap `waybar.jsonc` files stay in sync with the generated
+   config).
+4. Verify per `agent/VERIFICATION.md` §3 — scripted checks first
+   (`tools/check-theme-contrast.py`, `tools/audit-theme-design.py`), then
+   headless before/after screenshots you actually view, under at least
+   two themes. New themes are imported via `tools/import-palettes.py` and
+   round-tripped through the theme switcher.

agent/VERIFICATION.md

@@ -0,0 +1,178 @@
+# Verification — the enforcement rules
+
+Nomarchy's promise to its user: a rock-stable, fully functional, beautiful
+workstation that is reproducible, easy to recover, and never requires the
+user to become a Nix expert. Every rule below exists to protect that
+promise. A change that works but degrades stability, aesthetics, or
+user-simplicity is a regression, not a feature.
+
+This document is an **enforcer**, not the workflow itself: the ladder and
+iteration protocol live in `agent/LOOP.md`, VM instructions and gotchas in
+`docs/TESTING.md`. It applies to **every** change to this repo — features,
+fixes, theming, module changes, lock bumps, docs, backlog grooming.
+"Small" or "obvious" changes are exactly where verification gets skipped,
+so they trigger it too. If this file and those docs ever disagree, fix the
+discrepancy in the same or a follow-up commit so they can't disagree
+twice.
+
+## 1. Preflight (once per session)
+
+Before starting work, establish what verification tier this environment
+can reach, so you never promise verification you can't deliver:
+
+1. Linux x86_64 host? `/dev/kvm` present and readable?
+2. Enough free disk for an image/ISO build (multi-GB)?
+3. Network access for a cold Nix store?
+
+If the environment cannot reach V2 (no KVM, no disk, etc.): say so
+immediately, do the V0/V1 work honestly, mark the change **"V2 pending"**
+exactly as you would mark a hardware-blocked change "V3 pending" (§4),
+and stop short of claiming the change is done. Never simulate, guess, or
+describe what a VM test "would" show.
+
+## 2. The verification ladder (enforcement rules)
+
+Climb the V0–V3 ladder as defined in `agent/LOOP.md`. Four non-negotiable
+enforcement rules on top:
+
+1. **V2 is mandatory for anything user-visible.** If a user of the
+   installed system could perceive the change — behavior, layout, colors,
+   keybinds, timing, error messages — it must be exercised in the local
+   VM before commit. Docs-only, comment-only, or agent-notes changes may
+   stop at the tier LOOP.md assigns them; user-visible changes may not.
+2. **Every "done" report names the tier reached and shows the evidence.**
+   Evidence means: the command run and its relevant output, the checklist
+   items exercised, and for visual work the screenshots viewed (§3). "It
+   builds" is a V1 claim, not a V2 claim. Never let a report imply a
+   higher tier than was actually reached.
+3. **A failed or flaky test is a result, not an obstacle.** Distinguish
+   real failures from environment flakes using the known-gotchas section
+   of `docs/TESTING.md` (e.g. no-KVM slowness, missing guest GL). If you
+   cannot confidently classify a failure, report it as unresolved — do
+   not retry until green and report only the green run.
+4. **VM runs are headless and unattended.** Use the repo's headless
+   harness — `tools/test-live-iso.sh` and `tools/test-install.sh` for
+   boot/install runs, `tools/vm/qmp.py` for programmatic VM control and
+   `tools/vm/vncshot.py` for screen capture — never a graphical VM window
+   or any flow that needs a human at the console. The human is not part
+   of the test loop: do not pause mid-run to ask them to look at the VM,
+   click something, or confirm what is on screen. A run must complete on
+   its own and leave auditable artifacts behind (logs, serial console
+   output, exit codes, screenshots), with every wait bounded by a timeout
+   so a hang becomes a recorded failure instead of a stalled session.
+   Prefer scripted assertions (process up, file exists, service/D-Bus
+   state, the checks in `tools/`) over eyeballing; where judgment is
+   genuinely needed — visual quality — *you* view the captured
+   screenshots (§3), not the human. The human reviews evidence in the
+   final report, never the live run.
+
+### Regression scope after a change
+
+Re-running the full checklist for every change wastes VM time; running
+nothing invites regressions. Default rule:
+
+- Always: the session-sanity items (boot to session, bar renders).
+- Plus: every checklist item touching the layer you changed.
+- Plus: the theming end-to-end item whenever theming plumbing changed,
+  even indirectly (palette generation, symlinks, reload hooks).
+- Lock bumps and toolchain changes: run the full checklist — their blast
+  radius is unknowable by construction.
+
+## 3. Visual verification protocol
+
+Visual quality is a core feature of Nomarchy, so "it probably looks fine"
+is never verification. A visual/UI change is not V2-verified until all of
+the following are true:
+
+1. **Before/after screenshots** of the changed surface were captured
+   headlessly — `tools/theme-shot.nix` for reproducible theme renders,
+   `tools/vm/vncshot.py` (driven via `tools/vm/qmp.py`) for captures from
+   a running VM. No VM window, no human interaction. Capture the "before"
+   from the base branch or prior generation, not from memory.
+2. **Scripted checks first**: run `tools/check-theme-contrast.py` and
+   `tools/audit-theme-design.py` against the affected theme(s) before any
+   eyeballing — machine-checkable legibility/design violations should
+   never survive to the judgment stage. Use `tools/vm/gap-analysis.py`
+   where it applies.
+3. **Two themes**: repeat the "after" capture under at least two themes,
+   one with a generated palette and one whole-swap theme (e.g.
+   summer-night). These exercise different code paths in the bar/launcher
+   theming; a change that looks right under one can silently break the
+   other.
+4. **You actually viewed the images** — open the screenshot files and
+   look at them. State concretely what you inspected: alignment, spacing,
+   contrast/legibility against the palette, icon rendering, no clipped or
+   overlapping elements, and that the change looks intentional next to
+   the "before".
+5. Keep the screenshots in the run's working area and reference their
+   paths in the report, so the human can audit the same evidence.
+
+If the VM cannot render the surface faithfully (known GL/compositor gaps
+in the guest — see `docs/TESTING.md`), that specific visual aspect is
+hardware-blocked: verify everything the VM *can* show, and queue the rest
+per §4.
+
+## 4. Hardware-blocked checks
+
+Some checks genuinely require real hardware (GPU behavior, multi-monitor
+hotplug, audio devices, power/suspend, firmware). For those:
+
+1. Add an entry to `agent/HARDWARE-QUEUE.md` with: what changed, **exact**
+   reproduction steps a human can follow verbatim, the expected
+   observation (what "pass" looks like), and the commit hash once known.
+2. Mark the commit body **"V3 pending: <one-line summary>"**.
+3. Say it plainly in your report. A hardware-blocked check is not a
+   failure and not something to hide — hiding it is the failure.
+4. When the human reports back, close the queue entry in the next commit
+   and record the outcome; if it failed on hardware, that's a new bug at
+   the top of the backlog.
+
+Do not use the hardware queue as an escape hatch: if a check *can* be
+done in the VM, it must be. "The VM is slow" does not qualify.
+
+## 5. Maintenance work
+
+Maintenance follows the same ladder:
+
+- **Flake lock bumps**: treat as maximum-blast-radius changes. Build,
+  boot the VM, run the full regression checklist, and do a visual
+  spot-check of the session (themes can shift with upstream package
+  changes). Never merge a lock bump on "it evaluates".
+- **Theme imports / new themes**: import via `tools/import-palettes.py`,
+  then the full §3 visual protocol; additionally verify the theme-switch
+  round trip (into the new theme and back out).
+- **Docs drift**: run `tools/check-option-docs.py` after any change that
+  adds or modifies options, and fix drift in the same commit as the code
+  change that created it. Doc-only fixes are V0 — but verify any command
+  you document by actually running it.
+- **Backlog grooming / agent-notes**: V0; keep entries consistent with
+  the conventions in `agent/`.
+
+## 6. Guarding the philosophy
+
+Before committing, check the change against the distro's promises
+(`agent/GOALS.md` is the full statement):
+
+- **User is not a Nix expert.** If the change requires the user to write
+  or read Nix to use the feature day-to-day, redesign it. Configuration
+  the user touches must stay in the simple, documented surface the repo
+  defines.
+- **Rock-stable and recoverable.** Prefer boring, reproducible mechanisms
+  over clever ones. Any change that could break boot or the session must
+  have an obvious rollback story (NixOS generations count, but say so).
+- **Aesthetics are load-bearing.** A functionally correct but visually
+  regressive change fails review by definition — that's what §3 is for.
+
+When a requested change conflicts with these promises, stop and raise the
+conflict instead of implementing it quietly.
+
+## 7. Reporting format
+
+End every unit of work with a short report containing:
+
+1. What changed (one paragraph, plain language).
+2. Verification tier reached, with evidence (commands + key output,
+   checklist items run, screenshot paths viewed).
+3. Anything pending: "V2 pending" (environment) or "V3 pending"
+   (hardware, with queue entry reference).
+4. Follow-ups added to the backlog, if any.