docs: VISION for v1.0 + clarify docs/ vs agent/ vs .claude

Add docs/VISION.md (product themes, v1.0 bar, agent slice hints) and README maps under docs/ and agent/. Point ROADMAP, BACKLOG, LOOP, CLAUDE, HARDWARE, and the root README at the split: VISION = intent, BACKLOG = executable queue, ROADMAP = design history, .claude = harness only. Mark v1.0 track in BACKLOG PROPOSED for human triage.
2026-07-09 09:33:51 +01:00
parent caaac88da9
commit 02d7baeb7c
10 changed files with 340 additions and 52 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,29 +4,38 @@ Nomarchy is a NixOS-based distro: rock-stable, fully reproducible, themed
 from one JSON, configured through a menu that writes into the user's own
 flake checkout. Read the README for the architecture.

+## Where things live (read this first)
+
+| Path | Role |
+|------|------|
+| **`agent/`** | Loop state — **only executable queue is `BACKLOG.md`** |
+| **`docs/VISION.md`** | Product themes toward **v1.0** (not a queue) |
+| **`docs/ROADMAP.md`** | Design history + shipped log |
+| **`docs/README.md`** | Full documentation map |
+| **`agent/README.md`** | Map of loop files |
+| **`.claude/`** | Claude Code only (permissions + subagents) — not the backlog |
+
 ## If you're here to work autonomously (the loop)
-Follow **`agent/LOOP.md`** — it defines one iteration: orient
-(GOALS/BACKLOG/JOURNAL/MEMORY), take the top actionable BACKLOG item,
-verify up the V0–V3 ladder, commit+push on `main`, record. All loop state
-is git-tracked in `agent/`.
+Follow **`agent/LOOP.md`** — one iteration: orient → pick one BACKLOG
+item → work → verify → commit+push on `main` → record. All loop state is
+git-tracked in `agent/`.

 ## Rules that apply to every session, loop or not
- **Honesty rule** (docs/TESTING.md): for visual/interactive changes,
-  evaluation is not rendering — state exactly what you verified and at
-  which tier. Cheap check first, always: `nix flake check --no-build`.
+- **Honesty rule** (`docs/TESTING.md`): for visual/interactive changes,
+  evaluation is not rendering — state the tier you reached. Cheap first:
+  `nix flake check --no-build`.
 - **Conventions** (`agent/CONVENTIONS.md`): in-flake state, menu
-  placement, Waybar parity with the summer whole-swaps, toggle-vs-package
-  discipline, commented template examples for opt-ins.
- **Git:** direct commits on `main`, pushed; `v1` is the human-only
-  release pointer — never touch it. Never run `nix flake update` unless
-  the task is a lock bump. No formatter — match the aligned
-  hand-formatting.
- Machine-specifics live in `hosts/`, the distro in `modules/`, data in
-  `themes/`, code in `pkgs/`, maintainer tools in `tools/`.
+  placement, Waybar parity with whole-swaps, toggle-vs-package discipline,
+  template as SoT for opt-in comments (`templates/downstream`).
+- **Git:** direct commits on `main`, pushed; **`v1` is human-only** —
+  never touch it. Never `nix flake update` unless the task is a lock bump.
+  No formatter — match aligned hand-formatting.
+- Layout: `hosts/` machine · `modules/` distro · `themes/` data ·
+  `pkgs/` code · `tools/` maintainer · `agent/` loop · `docs/` human docs.

 ## Delegation

-The higher your tier, the more you delegate. Push the work down, keep your own context for judgment. Brief every child: the context, the why, what done looks like. It starts blank and inherits nothing.
+Push mechanical work down; keep judgment. Brief every child cold.

 | Model | Best for | Delegate? | Effort |
 |---|---|---|---|
@@ -39,4 +48,5 @@ Fable goes xhigh only for the hardest calls. Skip high.

 ## Escalation

-The parent doesn't have to be the top model. An Opus parent spawns a Fable child for the one hard call. The child answers and returns. Work above your tier? Return it, don't burn tokens on it.
+An Opus parent can spawn a Fable child for one hard call. Work above your
+tier? Return it — don't burn tokens.
--- a/README.md
+++ b/README.md
@@ -74,13 +74,15 @@ Flat on purpose. Two module trees, one options file each, no hidden layers.
 │   ├── nomarchy-theme-sync/       # state writer + rebuild dispatcher (Python)
 │   └── nomarchy-install/          # live-ISO installer (gum + disko + mkFlake)
 ├── templates/downstream/          # machine flake SoT (`flake init` + installer copy/patch)
-├── docs/TESTING.md                # how to verify changes (incl. AI-agent rules)
-├── docs/HARDWARE.md               # firmware, drivers, profiles, unsupported machines
-├── docs/OVERRIDES.md              # how downstream users override defaults
-├── docs/RECOVERY.md               # runbook: broken theme/desktop/boot → undo it
-├── docs/ROADMAP.md                # design/decision records + shipped-fixes log
-├── agent/                         # autonomous-agent loop: protocol (LOOP.md),
-│                                  #   prioritized BACKLOG, journal, memory
+├── docs/                          # human docs — map: docs/README.md
+│   ├── VISION.md                  #   product themes toward v1.0 (not a queue)
+│   ├── ROADMAP.md                 #   design/decision records + shipped log
+│   ├── HARDWARE.md                #   firmware, profiles, drivers
+│   ├── TESTING.md · RECOVERY.md · OVERRIDES.md · MIGRATION.md
+├── agent/                         # agent loop state — map: agent/README.md
+│                                  #   BACKLOG (executable queue), LOOP, GOALS, …
+├── CLAUDE.md                      # agent harness entry (points at agent/ + docs/)
+├── .claude/                       # Claude Code only: permissions + subagents
 └── tools/                         # maintainer-only
    ├── import-palettes.py         #   converts old-distro themes → JSON + assets
    ├── test-live-iso.sh           #   build the ISO + boot it in QEMU
@@ -442,9 +444,12 @@ reload                          # exec zsh (reload the shell)

 ## Roadmap & known issues

-The prioritized queue of what's next lives in
-**[agent/BACKLOG.md](agent/BACKLOG.md)**; the detailed design/decision
-records and the log of shipped fixes stay in
-**[docs/ROADMAP.md](docs/ROADMAP.md)**. Development runs on an
-agent-driven loop — see **[agent/LOOP.md](agent/LOOP.md)**. Kept out of
-the README so this stays a focused entry point.
+| Doc | Role |
+|-----|------|
+| **[agent/BACKLOG.md](agent/BACKLOG.md)** | What to do next (agent queue) |
+| **[docs/VISION.md](docs/VISION.md)** | Product themes toward **v1.0** |
+| **[docs/ROADMAP.md](docs/ROADMAP.md)** | Design history + shipped log |
+| **[docs/README.md](docs/README.md)** · **[agent/README.md](agent/README.md)** | Maps |
+| **[agent/LOOP.md](agent/LOOP.md)** | Autonomous iteration protocol |
+
+Kept out of the README body so this stays a focused entry point.
--- a/agent/BACKLOG.md
+++ b/agent/BACKLOG.md
@@ -1,22 +1,24 @@
 # Backlog — the prioritized task queue

-The forward-looking half of the old docs/ROADMAP.md, reworked as a queue
-agents can execute. Detailed design notes and decision records stay in
-`docs/ROADMAP.md` (referenced as "ROADMAP § <item>"); this file is *what's
-next, in what order*.
+**This is the only executable work list for agents.** Product themes and
+v1.0 intent live in [`docs/VISION.md`](../docs/VISION.md); design history
+in [`docs/ROADMAP.md`](../docs/ROADMAP.md); map in
+[`docs/README.md`](../docs/README.md) and [`agent/README.md`](README.md).

 **Rules:**
 - Agents take the topmost actionable item (see LOOP.md). Finished items
  are **deleted** here — the journal + git log are the record; durable
-  design notes get a ✓-entry in docs/ROADMAP.md if worth keeping.
+  design notes get a ✓-entry in docs/ROADMAP.md (and/or a note in VISION)
+  if worth keeping.
 - Item numbers are **stable IDs** — never renumbered or reused. A gap in
  the sequence means shipped (or dropped) work; new items take the next
  free number regardless of tier.
 - Tags: `[blocked:hw]` needs real hardware (see HARDWARE-QUEUE.md) ·
  `[human]` needs Bernardo · `[stuck]` two failed attempts, needs help ·
  `[big]` must be split before starting.
- Agents may append to **PROPOSED** and **Decisions** freely; only
-  Bernardo moves items *out* of PROPOSED into the tiers.
+- Agents may append to **PROPOSED** and **Decisions** freely (include
+  `VISION § …` or `ROADMAP § …` when relevant); only Bernardo moves items
+  *out* of PROPOSED into the tiers.

 ---

@@ -101,9 +103,19 @@ actually float once seen (regex tolerance for the `.…-wrapped` form).
 *Agents: append here with a one-paragraph pitch (what/why/cost). Do not
 implement. Bernardo moves accepted items into a tier.*

+### v1.0 track — see `docs/VISION.md`
+
+Product themes and the release bar live in **VISION**. Many slices
+already have pitches below (Hardware product, Installer bugs, Default
+theme → boreal). When adding new product work, reference
+`VISION § <theme>` and prefer the north-star laptop user. Suggested
+next promotions (human picks order): install P0 contracts · boreal
+default · System › Firmware · doctor hardware · fingerprint menu ·
+first-boot tips · human rebuild errors · neon-glass quarantine.
+
 ### Pre-existing

- **Default theme → boreal**
+- **Default theme → boreal** (`VISION § B` / v1.0 bar)
  Ship Boreal as the distro default instead of Tokyo Night: root
  `theme-state.json`, `templates/downstream/theme-state.json` (and any
  greeter/plymouth fallbacks that hardcode Tokyo Night when state is
--- a/agent/GOALS.md
+++ b/agent/GOALS.md
@@ -1,7 +1,9 @@
 # Goals — what "done" looks like for Nomarchy

 The north star every loop iteration serves. When two options conflict,
-the earlier pillar wins.
+the earlier pillar wins. Product *themes* toward a **v1.0** ship (day-2
+confidence, default identity, release bar) live in
+[`docs/VISION.md`](../docs/VISION.md) — still subordinate to these pillars.

 ## The four pillars (in priority order)

--- a/agent/LOOP.md
+++ b/agent/LOOP.md
@@ -57,7 +57,11 @@ Spend expensive tokens on judgment, not mechanics.

 ### 0. Orient
 1. Read `GOALS.md`, `CONVENTIONS.md`, `MEMORY.md`, the **last 3–5 entries**
-   of `JOURNAL.md`, and `BACKLOG.md`.
+   of `JOURNAL.md`, and `BACKLOG.md`. If the top task is product-shaped
+   (UX, release bar, day-2 confidence), also read the matching section of
+   **`docs/VISION.md`** — do not invent work from VISION; only execute
+   BACKLOG items. Map of docs vs agent state: `docs/README.md`,
+   `agent/README.md`.
 2. `git pull --ff-only` (skip silently if offline). Confirm you are on
   `main` with a clean tree. **A dirty tree you didn't create → stop and
   report; never stash or discard someone else's work.**
--- a/agent/README.md
+++ b/agent/README.md
@@ -0,0 +1,42 @@
+# Agent 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)**.
+
+## Files
+
+| File | Who writes | Role |
+|------|------------|------|
+| [LOOP.md](LOOP.md) | Human | One-iteration protocol (orient → pick → work → verify → commit → record) |
+| [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 |
+| [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) |
+| [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 |
+
+## Product / design docs (not a queue)
+
+| File | Role |
+|------|------|
+| [../docs/VISION.md](../docs/VISION.md) | v1.0 product themes — agents slice into BACKLOG PROPOSED |
+| [../docs/ROADMAP.md](../docs/ROADMAP.md) | Design history + shipped log |
+| [../docs/README.md](../docs/README.md) | Full docs map |
+
+## Claude Code only
+
+| Path | Role |
+|------|------|
+| [../.claude/settings.json](../.claude/settings.json) | Tool permissions |
+| [../.claude/agents/](../.claude/agents/) | `nomarchy-scout` / `nomarchy-runner` subagent defs |
+
+Do **not** put backlog items or vision text under `.claude/` — it is not
+shared with other agent runners.
+
+## Rules of thumb
+
+1. **Execute** from BACKLOG only (NOW → NEXT; never PROPOSED without human triage).
+2. **Orient** with GOALS + CONVENTIONS + MEMORY + last journal + BACKLOG; when the task is product-shaped, also read the relevant **VISION §**.
+3. **Record** lasting design in ROADMAP ✓ when something ships that future humans should know; delete the BACKLOG line.
+4. **v1 branch** is human-only — never advance from an agent session.
--- a/docs/HARDWARE.md
+++ b/docs/HARDWARE.md
@@ -3,9 +3,10 @@
 How Nomarchy enables CPUs, GPUs, laptops, firmware, and peripherals — and
 what to do when your machine is not in the happy path.

-> **Queue:** product follow-ups live in [`agent/BACKLOG.md`](../agent/BACKLOG.md)
-> (PROPOSED › Hardware product). Design history: [`ROADMAP.md`](ROADMAP.md).
-> Migration without reinstall: [`MIGRATION.md`](MIGRATION.md).
+> **Queue:** [`agent/BACKLOG.md`](../agent/BACKLOG.md) (PROPOSED › Hardware
+> product). Product framing: [`VISION.md`](VISION.md) § A. Design history:
+> [`ROADMAP.md`](ROADMAP.md). Docs map: [`README.md`](README.md).
+> Migration: [`MIGRATION.md`](MIGRATION.md).

 ## 1. Architecture (three layers)

--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,40 @@
+# Docs map
+
+Where human and agent documentation lives. **Do not** invent a third
+tree for the same facts.
+
+| Path | Audience | Role |
+|------|----------|------|
+| [../README.md](../README.md) | Everyone | What Nomarchy is, install, options tables |
+| [VISION.md](VISION.md) | Maintainers + agents | Product north star toward **v1.0** and beyond — themes, not a task queue |
+| [ROADMAP.md](ROADMAP.md) | Maintainers + agents | Design/decision records + shipped log (historical ✓) |
+| [HARDWARE.md](HARDWARE.md) | Users + agents | Firmware, profiles, drivers, unsupported machines |
+| [TESTING.md](TESTING.md) | Maintainers + agents | Verification ladder, honesty rule, ISO/VM recipes |
+| [RECOVERY.md](RECOVERY.md) | Users | Broken theme/desktop/boot → undo |
+| [OVERRIDES.md](OVERRIDES.md) | Users | Downstream Nix overrides |
+| [MIGRATION.md](MIGRATION.md) | Users | Existing NixOS → Nomarchy without reinstall |
+
+## Related (not under `docs/`)
+
+| Path | Role |
+|------|------|
+| [../agent/README.md](../agent/README.md) | **Executable** agent loop state: BACKLOG, LOOP, MEMORY, … |
+| [../CLAUDE.md](../CLAUDE.md) | Agent entry point (any harness that reads it) |
+| [../.claude/](../.claude/) | Claude Code only: permissions + subagent defs |
+
+## How work flows
+
+```
+VISION  (what we want the product to feel like)
+   │
+   ▼  human triages slices into…
+BACKLOG (what's next, ordered — agents execute only this)
+   │
+   ▼  lasting design notes after ship →
+ROADMAP ✓ entries
+```
+
+Agents **do not** implement directly from VISION or ROADMAP. They take
+the top actionable item in `agent/BACKLOG.md` (see `agent/LOOP.md`).
+They **may** append PROPOSED pitches that reference `VISION § …` or
+`ROADMAP § …`.
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -1,15 +1,20 @@
 # Roadmap & changelog

-Forward-looking plans, plus a running log of shipped fixes (the
-"Known issues & follow-ups" section). Split out of the README so that
-stays a focused entry point — what Nomarchy is, how to install it, and
-how to override it. Items marked ✓ are shipped.
+Design/decision records and a running log of shipped work (items marked
+✓). Split out of the README so that stays a focused entry point.

-> **The live, prioritized queue now lives in [`agent/BACKLOG.md`](../agent/BACKLOG.md)**
-> (part of the autonomous-agent loop, `agent/LOOP.md`). This file remains
-> the detailed design/decision record and the shipped log — backlog items
-> reference it as "ROADMAP § <item>". When a backlog item ships, its
-> lasting design notes get a ✓ entry here.
+> **Where to look**
+>
+> | Need | File |
+> |------|------|
+> | Product themes toward **v1.0** (not a queue) | [`docs/VISION.md`](VISION.md) |
+> | **What agents execute next** | [`agent/BACKLOG.md`](../agent/BACKLOG.md) |
+> | Docs map | [`docs/README.md`](README.md) |
+> | Agent loop protocol | [`agent/LOOP.md`](../agent/LOOP.md) |
+>
+> Backlog items may reference this file as **ROADMAP § \<item\>**. When
+> something ships, lasting design notes get a ✓ entry here; the BACKLOG
+> line is deleted.

 ## Roadmap
 - **Menu system** (apps launcher + theme switching + system actions), built
--- a/docs/VISION.md
+++ b/docs/VISION.md
@@ -0,0 +1,167 @@
+# Product vision — toward Nomarchy v1.0
+
+North star for **what the product should feel like**, not a task queue.
+Pillars stay in [`agent/GOALS.md`](../agent/GOALS.md). Executable work
+lives only in [`agent/BACKLOG.md`](../agent/BACKLOG.md).
+
+**How agents use this file**
+
+1. Read the relevant section when orienting on product work.
+2. Slice concrete work into **PROPOSED** (or wait for human triage into
+   NOW/NEXT) with a one-paragraph pitch and `VISION § <heading>`.
+3. Do **not** implement multi-week themes in one iteration — split.
+4. When a slice ships, leave a ✓ note here or in ROADMAP if the design
+   decision should outlive the backlog line.
+
+**Philosophy reminder:** opinionated and stable over option sprawl. Prefer
+safer defaults, one golden path, and menu/doctor surfaces over install-time
+questionnaires and `nomarchy.apps.*` toggles for bare packages.
+
+---
+
+## North-star user (v1 window)
+
+> **Framework / modern AMD-or-Intel laptop, little or no Nix, wants a
+> beautiful desktop that never bricks, configured from the menu.**
+
+Work that does not serve this user for the v1.0 window should stay LATER
+or PROPOSED unless it unblocks stability.
+
+---
+
+## v1.0 release bar
+
+Ship the **v1** branch pointer only when these are honestly true (human
+judgment; agents prepare, do not advance `v1`):
+
+| Bar | Done looks like |
+|-----|-----------------|
+| **Install golden path** | Offline (or documented online) install → first boot themed desktop; swap=0 and unattended LUKS contracts correct |
+| **Default identity** | Boreal (or chosen default) is the seed theme; picker has preview |
+| **Day-2 confidence** | Doctor covers real failure modes; firmware and fingerprint are discoverable without reading the README |
+| **Hardware story** | `docs/HARDWARE.md` matches code; option-docs green; i2c/ddcci documented |
+| **Honesty** | No “done” claims past verified tier; HARDWARE-QUEUE cleared or consciously deferred |
+| **Docs map** | README + `docs/README.md` + agent README agree on where things live |
+
+Not required for v1.0: dual-boot, Secure Boot, multi-disk RAID, aarch64,
+Steam Deck, docs website, binary cache.
+
+---
+
+## Theme A — Day-2 confidence (highest product ROI)
+
+The install is already strong. The gap is **after** first boot.
+
+| Idea | Intent | Likely home |
+|------|--------|-------------|
+| **System › Firmware** | fwupd is on but CLI-only; menu: refresh → list → confirm → update (never auto-flash) | BACKLOG Hardware product |
+| **Fingerprint menu** | Enroll/list when fprintd present; optional PAM + rebuild note | BACKLOG Hardware product |
+| **Doctor hardware section** | NM, sink, optional GPU smoke, fprintd, fwupd pending, charge threshold | BACKLOG Hardware product |
+| **Machine health entry** | One System row → doctor (not five submenus) | Menu / doctor |
+| **Human rebuild errors** | On failed switch, point at last log lines + `nomarchy-doctor` | pkgs / menu |
+| **HM pre-activate fail flag** | Durable recovery one-liner on target if bake failed | Installer |
+
+Reference: [HARDWARE.md](HARDWARE.md) §4–§5, §10.
+
+---
+
+## Theme B — First week experience
+
+| Idea | Intent | Notes |
+|------|--------|-------|
+| **Silent first-week card** | One dismissible “you’re set” (menu, theme, wallpaper, network) — not a wizard | Prefer notify or doctor “first boot” section |
+| **Boreal as default** | Identity on first boot | BACKLOG PROPOSED already |
+| **Generation readability** | “What changed last rebuild” in plain language | Rollback exists; story is incomplete |
+| **Post-install hints** | One-shot MOTD/notify for fwupd / fprintd when relevant | Avoid permanent nag |
+
+---
+
+## Theme C — Laptop daily driver
+
+| Idea | Intent | Notes |
+|------|--------|-------|
+| **Dock life** | Lid closed + external only, wake, default audio sink on undock | Display profiles exist — polish edge cases |
+| **Hibernate/sleep confidence** | Doctor: resume device, swap size, clean suspend journal | Trust > new power UI |
+| **Battery health readout** | Cycles / charge limit where sysfs allows | Report-only |
+| **Charge-limit instant apply** | Already PROPOSED `[blocked:hw]` | Keep privilege tradeoff explicit |
+
+---
+
+## Theme D — Beauty without theme sprawl
+
+| Idea | Intent | Notes |
+|------|--------|-------|
+| **Fewer themes, sharper** | Finish or quarantine neon-glass; invest in whole-swap quality | Contrast stays gated |
+| **Time-of-day pair** | Auto light/dark (e.g. summer-day ↔ summer-night) from schedule | Still one theme engine |
+| **Theme switch speed** | Wallpapers artifact split (LATER) if switches still feel slow | GOALS: no second pipeline |
+
+---
+
+## Theme E — Menu as the product
+
+| Idea | Intent | Notes |
+|------|--------|-------|
+| Root stays six entries | New features go Tools › / System › | CONVENTIONS |
+| Secrets module | Only if a vault story is adopted (rofi-rbw deferred) | Don’t tease |
+| Look & Feel group | Night-light, wallpaper, blur — when enough toggles exist | ROADMAP optional |
+
+---
+
+## Theme F — Narrative & community
+
+| Idea | Intent | Notes |
+|------|--------|-------|
+| **Omarchy migrant one-pager** | Bindings/theme/install map | `docs/` short guide |
+| **Hardware hall of fame** | Install-tested models; invite DMI PRs | Ties to HARDWARE.md §9 |
+| **60s demo** | Live → install → theme → menu | Outside repo OK |
+
+---
+
+## Theme G — Deliberate non-sprawl
+
+| Idea | Intent |
+|------|--------|
+| Starter apps: curate yearly, don’t grow `nomarchy.apps.*` | Template SoT already |
+| Gaming/creator: comment blocks in template, not new modules | Steam/OBS already services |
+| Installer stays golden-path | No dual-boot/partition wizard for v1 |
+
+---
+
+## Theme H — Quality bar when ideas run dry
+
+1. Burn down [HARDWARE-QUEUE.md](../agent/HARDWARE-QUEUE.md) (V3 only you can close).
+2. Fix install contracts (swap=0, unattended LUKS fail-closed).
+3. Visual ritual: default-theme screenshots before each `v1` fast-forward.
+4. option-docs + theme-contrast always green on `main`.
+
+---
+
+## Out of scope (reaffirm)
+
+From GOALS non-goals and installer audits — do not “fill the roadmap” with:
+
+- Binary cache as a product
+- Multi-DE / GTK4 launcher / second theming pipeline
+- Repo-wide formatter without a Decision
+- nixpkgs major bump on `main` (that’s a deliberate `v2`)
+- Option sprawl for bare package installs
+
+---
+
+## Suggested agent slices (promote via PROPOSED → NEXT)
+
+Small enough for one iteration each; reference this file:
+
+1. `VISION § v1.0` — default theme → boreal (seed state + fallbacks)
+2. `VISION § A` — System › Firmware (fwupd wrapper)
+3. `VISION § A` — doctor hardware section (read-only checks)
+4. `VISION § A` — fingerprint enroll menu (self-gated)
+5. `VISION § B` — first-boot dismissible tips (one surface)
+6. `VISION § A` — human-facing rebuild failure hint
+7. `VISION § v1.0` — install P0 contracts (swap / unattended LUKS)
+8. `VISION § D` — neon-glass quarantine or finish
+9. `VISION § F` — Omarchy migrant doc (short)
+10. `VISION § H` — HARDWARE-QUEUE session notes only Bernardo runs
+
+Larger themes (dock life, time-of-day theme, wallpapers split) stay
+`[big]` until split.