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
@@ -3,9 +3,10 @@
|
||||
How Nomarchy enables CPUs, GPUs, laptops, firmware, and peripherals — and
|
||||
what to do when your machine is not in the happy path.
|
||||
|
||||
> **Queue:** product follow-ups live in [`agent/BACKLOG.md`](../agent/BACKLOG.md)
|
||||
> (PROPOSED › Hardware product). Design history: [`ROADMAP.md`](ROADMAP.md).
|
||||
> Migration without reinstall: [`MIGRATION.md`](MIGRATION.md).
|
||||
> **Queue:** [`agent/BACKLOG.md`](../agent/BACKLOG.md) (PROPOSED › Hardware
|
||||
> product). Product framing: [`VISION.md`](VISION.md) § A. Design history:
|
||||
> [`ROADMAP.md`](ROADMAP.md). Docs map: [`README.md`](README.md).
|
||||
> Migration: [`MIGRATION.md`](MIGRATION.md).
|
||||
|
||||
## 1. Architecture (three layers)
|
||||
|
||||
|
||||
40
docs/README.md
Normal file
40
docs/README.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Docs map
|
||||
|
||||
Where human and agent documentation lives. **Do not** invent a third
|
||||
tree for the same facts.
|
||||
|
||||
| Path | Audience | Role |
|
||||
|------|----------|------|
|
||||
| [../README.md](../README.md) | Everyone | What Nomarchy is, install, options tables |
|
||||
| [VISION.md](VISION.md) | Maintainers + agents | Product north star toward **v1.0** and beyond — themes, not a task queue |
|
||||
| [ROADMAP.md](ROADMAP.md) | Maintainers + agents | Design/decision records + shipped log (historical ✓) |
|
||||
| [HARDWARE.md](HARDWARE.md) | Users + agents | Firmware, profiles, drivers, unsupported machines |
|
||||
| [TESTING.md](TESTING.md) | Maintainers + agents | Verification ladder, honesty rule, ISO/VM recipes |
|
||||
| [RECOVERY.md](RECOVERY.md) | Users | Broken theme/desktop/boot → undo |
|
||||
| [OVERRIDES.md](OVERRIDES.md) | Users | Downstream Nix overrides |
|
||||
| [MIGRATION.md](MIGRATION.md) | Users | Existing NixOS → Nomarchy without reinstall |
|
||||
|
||||
## Related (not under `docs/`)
|
||||
|
||||
| Path | Role |
|
||||
|------|------|
|
||||
| [../agent/README.md](../agent/README.md) | **Executable** agent loop state: BACKLOG, LOOP, MEMORY, … |
|
||||
| [../CLAUDE.md](../CLAUDE.md) | Agent entry point (any harness that reads it) |
|
||||
| [../.claude/](../.claude/) | Claude Code only: permissions + subagent defs |
|
||||
|
||||
## How work flows
|
||||
|
||||
```
|
||||
VISION (what we want the product to feel like)
|
||||
│
|
||||
▼ human triages slices into…
|
||||
BACKLOG (what's next, ordered — agents execute only this)
|
||||
│
|
||||
▼ lasting design notes after ship →
|
||||
ROADMAP ✓ entries
|
||||
```
|
||||
|
||||
Agents **do not** implement directly from VISION or ROADMAP. They take
|
||||
the top actionable item in `agent/BACKLOG.md` (see `agent/LOOP.md`).
|
||||
They **may** append PROPOSED pitches that reference `VISION § …` or
|
||||
`ROADMAP § …`.
|
||||
@@ -1,15 +1,20 @@
|
||||
# Roadmap & changelog
|
||||
|
||||
Forward-looking plans, plus a running log of shipped fixes (the
|
||||
"Known issues & follow-ups" section). Split out of the README so that
|
||||
stays a focused entry point — what Nomarchy is, how to install it, and
|
||||
how to override it. Items marked ✓ are shipped.
|
||||
Design/decision records and a running log of shipped work (items marked
|
||||
✓). Split out of the README so that stays a focused entry point.
|
||||
|
||||
> **The live, prioritized queue now lives in [`agent/BACKLOG.md`](../agent/BACKLOG.md)**
|
||||
> (part of the autonomous-agent loop, `agent/LOOP.md`). This file remains
|
||||
> the detailed design/decision record and the shipped log — backlog items
|
||||
> reference it as "ROADMAP § <item>". When a backlog item ships, its
|
||||
> lasting design notes get a ✓ entry here.
|
||||
> **Where to look**
|
||||
>
|
||||
> | Need | File |
|
||||
> |------|------|
|
||||
> | Product themes toward **v1.0** (not a queue) | [`docs/VISION.md`](VISION.md) |
|
||||
> | **What agents execute next** | [`agent/BACKLOG.md`](../agent/BACKLOG.md) |
|
||||
> | Docs map | [`docs/README.md`](README.md) |
|
||||
> | Agent loop protocol | [`agent/LOOP.md`](../agent/LOOP.md) |
|
||||
>
|
||||
> Backlog items may reference this file as **ROADMAP § \<item\>**. When
|
||||
> something ships, lasting design notes get a ✓ entry here; the BACKLOG
|
||||
> line is deleted.
|
||||
|
||||
## Roadmap
|
||||
- **Menu system** (apps launcher + theme switching + system actions), built
|
||||
|
||||
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