From 02d7baeb7c819374a13366f7324fcb7053fc29b6 Mon Sep 17 00:00:00 2001 From: Bernardo Magri Date: Thu, 9 Jul 2026 09:33:51 +0100 Subject: [PATCH] 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. --- CLAUDE.md | 44 ++++++++----- README.md | 31 +++++---- agent/BACKLOG.md | 28 +++++--- agent/GOALS.md | 4 +- agent/LOOP.md | 6 +- agent/README.md | 42 ++++++++++++ docs/HARDWARE.md | 7 +- docs/README.md | 40 ++++++++++++ docs/ROADMAP.md | 23 ++++--- docs/VISION.md | 167 +++++++++++++++++++++++++++++++++++++++++++++++ 10 files changed, 340 insertions(+), 52 deletions(-) create mode 100644 agent/README.md create mode 100644 docs/README.md create mode 100644 docs/VISION.md diff --git a/CLAUDE.md b/CLAUDE.md index 1916461..a20f69d 100644 --- 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. diff --git a/README.md b/README.md index 49b4905..0cc4a75 100644 --- 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. diff --git a/agent/BACKLOG.md b/agent/BACKLOG.md index 5591281..7debed3 100644 --- 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 § "); 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 § ` 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 diff --git a/agent/GOALS.md b/agent/GOALS.md index 7c38226..6bd4f36 100644 --- 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) diff --git a/agent/LOOP.md b/agent/LOOP.md index 61ac152..b7f8d1d 100644 --- 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.** diff --git a/agent/README.md b/agent/README.md new file mode 100644 index 0000000..d3140e2 --- /dev/null +++ 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. diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md index 58579fb..f7a1404 100644 --- 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) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e1b1b10 --- /dev/null +++ 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 § …`. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index af7585a..6f13a2c 100644 --- 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 § ". 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 § \**. 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 diff --git a/docs/VISION.md b/docs/VISION.md new file mode 100644 index 0000000..600fad4 --- /dev/null +++ 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 § `. +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.