Nomarchy/docs/VISION.md

# 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 is the seed theme (shipped 2026-07-09); picker should have `preview.png` |
| **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.
Most of this theme **shipped** mid-2026; residual is V3 hardware QA +
optional polish.

| Idea | Intent | Status |
|------|--------|--------|
| **System › Firmware** ✓ | fwupd menu: refresh → list → confirm → update (never auto-flash) | ✓ shipped #43 (+ V2 #43 render) |
| **Fingerprint menu** ✓ | Enroll/list when fprintd present; optional PAM + rebuild note | ✓ shipped #55; V3 enroll HARDWARE-QUEUE |
| **Doctor hardware section** ✓ | NM, sink, GPU smoke, fprintd, fwupd, charge, battery health, hibernate | ✓ shipped #44 + #77 + #80 + #83 |
| **Machine health entry** ✓ | One System row → doctor | ✓ System › Doctor + Waybar tripwire |
| **Human rebuild errors** ✓ | Failed switch → last log lines + `nomarchy-doctor` | ✓ shipped #56 |
| **HM pre-activate fail flag** ✓ | Recovery one-liner if theme bake failed | ✓ shipped #83 |

Reference: [HARDWARE.md](HARDWARE.md) §4–§5, §11 (doctor).

---

## Theme B — First week experience

| Idea | Intent | Notes |
|------|--------|-------|
| **Silent first-week card** ✓ | One dismissible “you’re set” (menu, themes, keys, network) — not a wizard | ✓ shipped #81 — `settings.firstBootShown` + notify; live ISO keeps its own toast |
| **Boreal as default** ✓ | Identity on first boot | ✓ seed `theme-state.json` + install path use Boreal (2026-07-09) |
| **Generation readability** ✓ | “What changed last rebuild” in plain language | ✓ shipped #82 — nvd toast + System › What changed? |
| **Post-install hints** | One-shot MOTD/notify for fwupd / fprintd when relevant | Partial: MOTD + control-center tips; still no self-gated *first-session* toast when hardware is present (see BACKLOG PROPOSED) |

---

## Theme C — Laptop daily driver

| Idea | Intent | Notes |
|------|--------|-------|
| **Dock life** ✓ | Lid closed + external only, wake, default audio sink on undock | ✓ #86 clamshell logind; ✓ #87 WirePlumber HDMI/USB priority (V3 hotplug QA) |
| **Hibernate/sleep confidence** ✓ | Doctor: resume device, swap size, clean suspend journal | ✓ shipped #77 (+ #76 agent V0–V2; V3 power-cycle HARDWARE-QUEUE) |
| **Battery health readout** ✓ | Cycles + design capacity % in doctor where sysfs allows | ✓ shipped #80 (report-only; charge limit is a separate row) |
| **Charge-limit instant apply** | Live sysfs write without rebuild | Shipped menu live-write path 2026-07-10; residual V3 Dell Adaptive / non-BAT* in HARDWARE-QUEUE |

---

## Theme D — Beauty without theme sprawl

| Idea | Intent | Notes |
|------|--------|-------|
| **Fewer themes, sharper** ✓ | Finish or quarantine neon-glass; invest in whole-swap quality | ✓ #88 finish — glass rofi (proper @colors), btop, preview; bar stays generated (no broken waybar.css) |
| **Time-of-day pair** ✓ | Auto light/dark (e.g. summer-day ↔ summer-night) from schedule | ✓ shipped #79 (2026-07-10) — `settings.autoTheme` + timer; still one 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 | ✓ shipped `docs/OMARCHY.md` (#78, 2026-07-10) |
| **Hardware hall of fame** ✓ | Install-tested models; invite DMI PRs | ✓ shipped #85 — HARDWARE.md §9 table + DMI PR invite |
| **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)

**Still open** (as of 2026-07-11). Shipped items above are *not* open work.

1. `VISION § B` — post-install hardware hints (self-gated first-session
   toast when `fwupdmgr` / `fprintd-list` exist; one-shot markers; no nag)
2. `VISION § D` / LATER — wallpapers artifact split (decided deferred;
   promote only if theme-switch latency still hurts after measurement)
3. `VISION § H` — HARDWARE-QUEUE burn-down (human-only V3; agents only
   append exact steps)
4. `VISION § v1.0` — install P0 re-verify before any `v1` fast-forward
   (swap=0 / unattended LUKS contracts; human ships the pointer)

Do **not** re-open Theme A firmware/fingerprint/doctor/rebuild rows —
those shipped. Dock/hibernate agent work is done; residual is V3 hardware.