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.

| 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 | ✓ shipped #83 — doctor first-boot row + install-time hint |

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 | BACKLOG PROPOSED already |
| **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 | 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 + design capacity % in doctor where sysfs allows | ✓ shipped #80 (report-only; charge limit is a separate row) |
| **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 | ✓ 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)

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.