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. 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 §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 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 tips; first-session toast is #81; still refine self-gated hardware hints if needed

---

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 (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.