docs: VISION for v1.0 + clarify docs/ vs agent/ vs .claude

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.

agent/BACKLOG.md

@@ -1,22 +1,24 @@
 # Backlog — the prioritized task queue
 
-The forward-looking half of the old docs/ROADMAP.md, reworked as a queue
-agents can execute. Detailed design notes and decision records stay in
-`docs/ROADMAP.md` (referenced as "ROADMAP § <item>"); this file is *what's
-next, in what order*.
+**This is the only executable work list for agents.** Product themes and
+v1.0 intent live in [`docs/VISION.md`](../docs/VISION.md); design history
+in [`docs/ROADMAP.md`](../docs/ROADMAP.md); map in
+[`docs/README.md`](../docs/README.md) and [`agent/README.md`](README.md).
 
 **Rules:**
 - Agents take the topmost actionable item (see LOOP.md). Finished items
   are **deleted** here — the journal + git log are the record; durable
-  design notes get a ✓-entry in docs/ROADMAP.md if worth keeping.
+  design notes get a ✓-entry in docs/ROADMAP.md (and/or a note in VISION)
+  if worth keeping.
 - Item numbers are **stable IDs** — never renumbered or reused. A gap in
   the sequence means shipped (or dropped) work; new items take the next
   free number regardless of tier.
 - Tags: `[blocked:hw]` needs real hardware (see HARDWARE-QUEUE.md) ·
   `[human]` needs Bernardo · `[stuck]` two failed attempts, needs help ·
   `[big]` must be split before starting.
-- Agents may append to **PROPOSED** and **Decisions** freely; only
-  Bernardo moves items *out* of PROPOSED into the tiers.
+- Agents may append to **PROPOSED** and **Decisions** freely (include
+  `VISION § …` or `ROADMAP § …` when relevant); only Bernardo moves items
+  *out* of PROPOSED into the tiers.
 
 ---
 
@@ -101,9 +103,19 @@ actually float once seen (regex tolerance for the `.…-wrapped` form).
 *Agents: append here with a one-paragraph pitch (what/why/cost). Do not
 implement. Bernardo moves accepted items into a tier.*
 
+### v1.0 track — see `docs/VISION.md`
+
+Product themes and the release bar live in **VISION**. Many slices
+already have pitches below (Hardware product, Installer bugs, Default
+theme → boreal). When adding new product work, reference
+`VISION § <theme>` and prefer the north-star laptop user. Suggested
+next promotions (human picks order): install P0 contracts · boreal
+default · System › Firmware · doctor hardware · fingerprint menu ·
+first-boot tips · human rebuild errors · neon-glass quarantine.
+
 ### Pre-existing
 
-- **Default theme → boreal**
+- **Default theme → boreal** (`VISION § B` / v1.0 bar)
   Ship Boreal as the distro default instead of Tokyo Night: root
   `theme-state.json`, `templates/downstream/theme-state.json` (and any
   greeter/plymouth fallbacks that hardcode Tokyo Night when state is

agent/GOALS.md

@@ -1,7 +1,9 @@
 # Goals — what "done" looks like for Nomarchy
 
 The north star every loop iteration serves. When two options conflict,
-the earlier pillar wins.
+the earlier pillar wins. Product *themes* toward a **v1.0** ship (day-2
+confidence, default identity, release bar) live in
+[`docs/VISION.md`](../docs/VISION.md) — still subordinate to these pillars.
 
 ## The four pillars (in priority order)
 

agent/LOOP.md

@@ -57,7 +57,11 @@ Spend expensive tokens on judgment, not mechanics.
 
 ### 0. Orient
 1. Read `GOALS.md`, `CONVENTIONS.md`, `MEMORY.md`, the **last 3–5 entries**
-   of `JOURNAL.md`, and `BACKLOG.md`.
+   of `JOURNAL.md`, and `BACKLOG.md`. If the top task is product-shaped
+   (UX, release bar, day-2 confidence), also read the matching section of
+   **`docs/VISION.md`** — do not invent work from VISION; only execute
+   BACKLOG items. Map of docs vs agent state: `docs/README.md`,
+   `agent/README.md`.
 2. `git pull --ff-only` (skip silently if offline). Confirm you are on
    `main` with a clean tree. **A dirty tree you didn't create → stop and
    report; never stash or discard someone else's work.**

agent/README.md

@@ -0,0 +1,42 @@
+# Agent loop state
+
+Git-tracked state for autonomous and assisted work on Nomarchy.
+Protocol: **[LOOP.md](LOOP.md)**. Entry for most harnesses: repo-root
+**[CLAUDE.md](../CLAUDE.md)**.
+
+## Files
+
+| File | Who writes | Role |
+|------|------------|------|
+| [LOOP.md](LOOP.md) | Human | One-iteration protocol (orient → pick → work → verify → commit → record) |
+| [GOALS.md](GOALS.md) | Human (agents propose) | Pillars, quality bars, non-goals |
+| [CONVENTIONS.md](CONVENTIONS.md) | Human (agents propose) | How to write code/menu/state while shipping |
+| [BACKLOG.md](BACKLOG.md) | Both | **Prioritized queue** — only executable work list |
+| [JOURNAL.md](JOURNAL.md) | Agents | Append-only iteration log (read last 3–5 entries) |
+| [MEMORY.md](MEMORY.md) | Agents | Curated durable gotchas |
+| [HARDWARE-QUEUE.md](HARDWARE-QUEUE.md) | Agents append, human checks | On-hardware V3 tests only Bernardo can run |
+
+## Product / design docs (not a queue)
+
+| File | Role |
+|------|------|
+| [../docs/VISION.md](../docs/VISION.md) | v1.0 product themes — agents slice into BACKLOG PROPOSED |
+| [../docs/ROADMAP.md](../docs/ROADMAP.md) | Design history + shipped log |
+| [../docs/README.md](../docs/README.md) | Full docs map |
+
+## Claude Code only
+
+| Path | Role |
+|------|------|
+| [../.claude/settings.json](../.claude/settings.json) | Tool permissions |
+| [../.claude/agents/](../.claude/agents/) | `nomarchy-scout` / `nomarchy-runner` subagent defs |
+
+Do **not** put backlog items or vision text under `.claude/` — it is not
+shared with other agent runners.
+
+## Rules of thumb
+
+1. **Execute** from BACKLOG only (NOW → NEXT; never PROPOSED without human triage).
+2. **Orient** with GOALS + CONVENTIONS + MEMORY + last journal + BACKLOG; when the task is product-shaped, also read the relevant **VISION §**.
+3. **Record** lasting design in ROADMAP ✓ when something ships that future humans should know; delete the BACKLOG line.
+4. **v1 branch** is human-only — never advance from an agent session.