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. Executable work lives only in 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 §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	✓ #86 clamshell logind ignore when docked; #87 audio still open
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 (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.