docs: VISION for v1.0 + clarify docs/ vs agent/ vs .claude
All checks were successful
Check / eval (push) Successful in 3m7s
All checks were successful
Check / eval (push) Successful in 3m7s
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.
This commit is contained in:
Bernardo Magri
167
docs/VISION.md
Normal file
167
docs/VISION.md
Normal file
@@ -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 § <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 (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.
|
||||
Reference in New Issue
Block a user