docs(agent): vendor-neutral agent docs — AGENTS.md entry, agent/ SoT, .claude shims

The repo is maintained by agents from multiple vendors, so agent instructions move out of vendor-specific locations into shared, git-tracked markdown: - AGENTS.md is the new entry point for any harness; CLAUDE.md becomes a symlink to it (Claude Code keeps working unchanged). - Skill bodies relocate to agent/: VERIFICATION.md (the enforcement rules, ex .claude/skills/nomarchy), DELEGATION.md (capability tiers light/standard/frontier, scout/runner role contracts, token economy, parallel fan-out — consolidates the CLAUDE.md model table, LOOP.md's economy section, and skill §6.5 into one place; vendor model names survive only in the per-harness mapping table), THEME-DESIGN.md (ex .claude/skills/theme, which previously lacked frontmatter). - .claude/ shrinks to a thin Claude Code adapter: settings, subagent defs, and skill shims that route into agent/. - Maps updated: agent/README.md (instructions vs state vs adapters), docs/README.md, README.md layout tree. Cleanup: stale old_distro .gitignore entry dropped (dir long gone); local result*/__pycache__ artifacts removed; JOURNAL.md rotated (29 recent entries kept, 120 older moved to agent/JOURNAL-ARCHIVE.md, rotation rule documented in the header). Verification: V0 (docs/meta only) — nix flake check --no-build exit 0 with the tracked symlink; grep sweep confirms no vendor model names outside DELEGATION.md's mapping table. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-11 08:58:25 +01:00
parent 37615c85a4
commit c0fc16e25c
15 changed files with 2382 additions and 2258 deletions
--- a/.claude/skills/nomarchy/SKILL.md
+++ b/.claude/skills/nomarchy/SKILL.md
@@ -5,268 +5,18 @@ description: Development and maintenance workflow for the Nomarchy NixOS-based d
 # Nomarchy Development Skill
-Nomarchy's promise to its user: a rock-stable, fully functional, beautiful
+This repo is maintained by agents from multiple vendors, so the skill
-workstation that is reproducible, easy to recover, and never requires the
+body lives vendor-neutrally in the repo — this file only routes you
-user to become a Nix expert. Every rule below exists to protect that promise.
+there. Read, then follow:
 A change that works but degrades stability, aesthetics, or user-simplicity is
 a regression, not a feature.
-## 0. Read the authoritative docs first
+1. **`AGENTS.md`** — entry point: where everything lives, standing rules
 2. **`agent/LOOP.md`** — the iteration protocol + the V0–V3 ladder
 3. **`agent/VERIFICATION.md`** — the enforcement rules: preflight, the
   honesty rules, the visual verification protocol, hardware-blocked
   checks, maintenance work, the reporting format
 4. **`agent/DELEGATION.md`** — capability tiers, the scout/runner roles
   (Claude Code defs: `.claude/agents/`), token economy, parallel fan-out
-This skill is an enforcer, not the workflow itself. The workflow lives in the
+Before running any VM test, also read **`docs/TESTING.md`**. The repo
-repo and is the single source of truth:
+docs always win over any cached summary of them; if docs disagree with
-
+each other, fix the discrepancy in the same or a follow-up commit.
 - `CLAUDE.md` — entry point, project conventions
 - `agent/LOOP.md` — the iteration loop and the V0–V3 verification ladder
 - `agent/` (remaining files) — philosophy, conventions, memory, backlog
 - `docs/TESTING.md` — VM instructions, the regression checklist, known
  environment gotchas
 At the start of any work session in this repo, read `CLAUDE.md` and
 `agent/LOOP.md` before touching code. Read `docs/TESTING.md` before running
 any VM test. If this skill and those docs ever disagree, the repo docs win —
 then fix the discrepancy in the same or a follow-up commit so they can't
 disagree twice.
 ## 1. Preflight (once per session)
 Before starting work, establish what verification tier this environment can
 reach, so you never promise verification you can't deliver:
 1. Linux x86_64 host? `/dev/kvm` present and readable?
 2. Enough free disk for an image/ISO build (multi-GB)?
 3. Network access for a cold Nix store?
 If the environment cannot reach V2 (no KVM, no disk, etc.): say so
 immediately, do the V0/V1 work honestly, mark the change **"V2 pending"**
 exactly as you would mark a hardware-blocked change "V3 pending" (see §4),
 and stop short of claiming the change is done. Never simulate, guess, or
 describe what a VM test "would" show.
 ## 2. The verification ladder (enforcement rules)
 Climb the V0–V3 ladder as defined in `agent/LOOP.md`. This skill adds three
 non-negotiable enforcement rules on top:
 1. **V2 is mandatory for anything user-visible.** If a user of the installed
   system could perceive the change — behavior, layout, colors, keybinds,
   timing, error messages — it must be exercised in the local VM before
   commit. Docs-only, comment-only, or agent-notes changes may stop at the
   tier LOOP.md assigns them; user-visible changes may not.
 2. **Every "done" report names the tier reached and shows the evidence.**
   Evidence means: the command run and its relevant output, the checklist
   items exercised, and for visual work the screenshots viewed (§3). "It
   builds" is a V1 claim, not a V2 claim. Never let a report imply a higher
   tier than was actually reached.
 3. **A failed or flaky test is a result, not an obstacle.** Distinguish real
   failures from environment flakes using the known-gotchas section of
   `docs/TESTING.md` (e.g. no-KVM slowness, missing guest GL). If you cannot
   confidently classify a failure, report it as unresolved — do not retry
   until green and report only the green run.
 4. **VM runs are headless and unattended.** Use the repo's headless
   harness — `tools/test-live-iso.sh` and `tools/test-install.sh` for
   boot/install runs, `tools/vm/qmp.py` for programmatic VM control and
   `tools/vm/vncshot.py` for screen capture — never a graphical VM window
   or any flow that needs a human at the console. The human is not part of
   the test loop: do not pause mid-run to ask them to look at the VM, click
   something, or confirm what is on screen. A run must complete on its own
   and leave auditable artifacts behind (logs, serial console output, exit
   codes, screenshots), with every wait bounded by a timeout so a hang
   becomes a recorded failure instead of a stalled session. Prefer scripted
   assertions (process up, file exists, service/D-Bus state, the checks in
   `tools/`) over eyeballing; where judgment is genuinely needed — visual
   quality — *you* view the captured screenshots (§3), not the human. The
   human reviews evidence in the final report, never the live run.
 ### Regression scope after a change
 Re-running the full checklist for every change wastes VM time; running
 nothing invites regressions. Default rule:
 - Always: the session-sanity items (boot to session, bar renders).
 - Plus: every checklist item touching the layer you changed.
 - Plus: the theming end-to-end item whenever theming plumbing changed,
  even indirectly (palette generation, symlinks, reload hooks).
 - Lock bumps and toolchain changes: run the full checklist — their blast
  radius is unknowable by construction.
 ## 3. Visual verification protocol
 Visual quality is a core feature of Nomarchy, so "it probably looks fine" is
 never verification. A visual/UI change is not V2-verified until all of the
 following are true:
 1. **Before/after screenshots** of the changed surface were captured
   headlessly — `tools/theme-shot.nix` for reproducible theme renders,
   `tools/vm/vncshot.py` (driven via `tools/vm/qmp.py`) for captures from a
   running VM. No VM window, no human interaction. Capture the "before"
   from the base branch or prior generation, not from memory.
 2. **Scripted checks first**: run `tools/check-theme-contrast.py` and
   `tools/audit-theme-design.py` against the affected theme(s) before any
   eyeballing — machine-checkable legibility/design violations should never
   survive to the human-judgment stage. Use `tools/vm/gap-analysis.py`
   where it applies.
 3. **Two themes**: repeat the "after" capture under at least two themes, one
   with a generated palette and one whole-swap theme (e.g. summer-night).
   These exercise different code paths in the bar/launcher theming; a change
   that looks right under one can silently break the other.
 4. **You actually viewed the images** — open the screenshot files and look
   at them. State concretely what you inspected: alignment, spacing,
   contrast/legibility against the palette, icon rendering, no clipped or
   overlapping elements, and that the change looks intentional next to the
   "before".
 5. Keep the screenshots in the run's working area and reference their paths
   in the report, so the human can audit the same evidence.
 If the VM cannot render the surface faithfully (known GL/compositor gaps in
 the guest — see `docs/TESTING.md`), that specific visual aspect is
 hardware-blocked: verify everything the VM *can* show, and queue the rest
 per §4.
 ## 4. Hardware-blocked checks
 Some checks genuinely require real hardware (GPU behavior, multi-monitor
 hotplug, audio devices, power/suspend, firmware). For those:
 1. Add an entry to `agent/HARDWARE-QUEUE.md` with: what changed, **exact**
   reproduction steps a human can follow verbatim, the expected observation
   (what "pass" looks like), and the commit hash once known.
 2. Mark the commit body **"V3 pending: <one-line summary>"**.
 3. Say it plainly in your report. A hardware-blocked check is not a failure
   and not something to hide — hiding it is the failure.
 4. When the human reports back, close the queue entry in the next commit and
   record the outcome; if it failed on hardware, that's a new bug at the top
   of the backlog.
 Do not use the hardware queue as an escape hatch: if a check *can* be done
 in the VM, it must be. "The VM is slow" does not qualify.
 ## 5. Maintenance work
 Maintenance is in scope for this skill and follows the same ladder:
 - **Flake lock bumps**: treat as maximum-blast-radius changes. Build,
  boot the VM, run the full regression checklist, and do a visual
  spot-check of the session (themes can shift with upstream package
  changes). Never merge a lock bump on "it evaluates".
 - **Theme imports / new themes**: import via `tools/import-palettes.py`,
  then the full §3 visual protocol; additionally verify the theme-switch
  round trip (into the new theme and back out).
 - **Docs drift**: run `tools/check-option-docs.py` after any change that
  adds or modifies options, and fix drift in the same commit as the code
  change that created it. Doc-only fixes are V0 — but verify any command
  you document by actually running it.
 - **Backlog grooming / agent-notes**: V0; keep entries consistent with the
  conventions in `agent/`.
 ## 6. Guarding the philosophy
 Before committing, check the change against the distro's promises:
 - **User is not a Nix expert.** If the change requires the user to write or
  read Nix to use the feature day-to-day, redesign it. Configuration the
  user touches must stay in the simple, documented surface the repo defines.
 - **Rock-stable and recoverable.** Prefer boring, reproducible mechanisms
  over clever ones. Any change that could break boot or the session must
  have an obvious rollback story (NixOS generations count, but say so).
 - **Aesthetics are load-bearing.** A functionally correct but visually
  regressive change fails review by definition — that's what §3 is for.
 When a requested change conflicts with these promises, stop and raise the
 conflict instead of implementing it quietly.
 ## 6.5 Token economy: delegate machinery, keep judgment
 Not every step needs the smartest model. Use subagents to route mechanical
 work to cheap models and keep expensive reasoning where it pays. The repo
 defines two in `.claude/agents/`:
 - **nomarchy-scout** (haiku, read-only): finding where things are defined,
  mapping which files touch a subsystem, scanning build logs and serial
  output for error lines, docs-vs-code drift sweeps. Use it for any pure
  information-gathering step instead of reading files into the main
  context yourself — it keeps the main context small, which matters more
  than the token price on long loops.
 - **nomarchy-runner** (haiku, executes the harness): builds, VM boots,
  screenshot capture, the scripted `tools/` checks. It runs commands and
  returns exit codes, logs, and artifact paths — nothing more.
 The dividing line is **evidence vs. judgment**. Cheap models gather
 evidence; they never make verification claims. The following always stay
 with the main (smart) model and are never delegated downward:
 - deciding what to test and what the regression scope is (§2)
 - interpreting an ambiguous or flaky failure (§2 rule 3)
 - viewing screenshots and judging visual quality (§3) — aesthetic judgment
  is exactly the kind of work small models do badly, and it's load-bearing
  for this distro
 - writing non-trivial Nix (module structure, overlays, cross-cutting
  refactors)
 - the final review of the diff and the §7 report
 Practical guidance: delegation is not free — each subagent has its own
 context and the tokens multiply — so delegate when the work is mechanical
 *or* would pollute the main context with bulk (log files, wide file
 scans), not reflexively for every small step. A one-file read is cheaper
 done directly. When a scout/runner result surprises you, spot-check it
 yourself before building on it: cheap models are allowed to be wrong about
 hard things, which is precisely why they're not allowed to make claims.
 ### Fanning out worktree agents (parallel V0/V1 work)
 When several NEXT items are independent and don't need the VM, spread them
 across worktree-isolated subagents that run in parallel — but keep the
 token cost down with these habits (each is a real lever, not a nicety):
 - **Match the model to the task, not the tier.** A backlog item whose spec
  is already written (exact files, exact fixes) is *well-specified* →
  **sonnet**, not opus. Reserve opus for genuine multi-step reasoning
  (novel Nix, cross-cutting design, an ambiguous failure). Haiku for bulk
  mechanical. Picking sonnet over opus for a spec'd task is the single
  biggest saving.
 - **Point at the spec; don't restate it.** The brief should say "the spec
  is in `agent/BACKLOG.md` #NN — implement it, don't re-derive," plus only
  the *constraints* (scope files, branch, no-VM, no-push). A cold agent
  re-reading the whole design into its own context is the tokens you're
  trying to avoid.
 - **Disjoint file lanes.** Partition the items so no two agents touch the
  same file (map the touched files first). Zero shared files = zero merge
  conflicts at landing = no reconciliation tokens. If two items must share
  a file (README, flake.nix, rofi.nix), give both to one agent or keep one
  for yourself.
 - **Isolation + you own landing.** Run each agent with `isolation:
  worktree`; it commits to its own branch and **never pushes or touches
  `main`/`v1`**. You review each diff, cherry-pick onto `main`, and do the
  bookkeeping. Parallel pushers race on `main`; a single landing agent
  doesn't. (Clean up: `git worktree remove --force` + `git branch -D` the
  branch and its `worktree-…` sibling after landing.)
 - **Lean on scriptable checks as the primary evidence.** Where a
  deterministic `tools/` check or a `checks.*` guard already proves the
  property (e.g. `check-theme-contrast.py` for a palette fix,
  `option-docs` for a doc row), that near-free run *is* the V0/V1
  evidence — don't spend a VM render to re-confirm what the script already
  asserts.
 - **Batch V2 at the end, once.** Visual/behavioural items delegated at
  V0/V1 come back "V2 pending." Don't boot the VM per item — collect the
  landed changes and do **one** `theme-shot`/`test-install` pass covering
  all of them. The VM render + screenshot review is the most expensive
  token sink in the loop; amortise it.
 - **Re-verify on `main`, but leanly.** After cherry-picking, confirm the
  agent's V0/V1 on the merged tree — but a tiny, obviously-correct diff
  needs a targeted build, not a full re-run of everything. Trust-but-spot-
  check scales; blind re-running doesn't.
 The judgment that never delegates (§ above) still holds: *you* review every
 diff before it lands, and *you* make the product calls (a "finish vs.
 quarantine" decision is yours or Bernardo's, never a cheap agent's).
 ## 7. Reporting format
 End every unit of work with a short report containing:
 1. What changed (one paragraph, plain language).
 2. Verification tier reached, with evidence (commands + key output,
   checklist items run, screenshot paths viewed).
 3. Anything pending: "V2 pending" (environment) or "V3 pending" (hardware,
   with queue entry reference).
 4. Follow-ups added to the backlog, if any.
--- a/.claude/skills/theme/SKILL.md
+++ b/.claude/skills/theme/SKILL.md
@@ -1,21 +1,12 @@
 ---
 name: theme
 description: Theme design and visual work for Nomarchy — use whenever the user asks to create, update, refine, or troubleshoot themes or visual design (palettes, Hyprland looks, Waybar, Ghostty, btop, rofi, wallpapers, typography, icons).
 ---
 # Nomarchy Theme Designer Skill
-**Trigger:** Use this skill whenever the user requests to create, update, refine, or troubleshoot themes and visual designs for the Nomarchy distribution.
+The skill body lives vendor-neutrally in the repo — read and follow
-
+**`agent/THEME-DESIGN.md`**. Visual work additionally climbs the
-## System Prompt / Instructions
+verification ladder and visual protocol in **`agent/VERIFICATION.md`**
-
+(scripted contrast/design checks first, then headless screenshots you
-You are an elite UI/UX designer and Linux ricing expert specializing in Wayland environments. Your role is to create cohesive, innovative, and visually stunning desktop themes for "Nomarchy," a custom Linux distribution based on NixOS and the Hyprland window manager.
+actually view).
 ### Context & Architecture
 All theme configurations for Nomarchy live inside the `themes/` directory at the root of the repository. Before generating any new configurations, you MUST read and analyze the existing files in this directory. Learn how the current themes are structured, how the syntax is formatted for each application, and how they are integrated into the broader NixOS configuration. Always match this established architectural pattern.
 ### Your Design Responsibilities
 1. **Holistic Design:** Develop unified themes that span across Hyprland (borders, shadows, animations), Waybar, Ghostty terminal, btop, fastfetch, Rofi/fuzzel, and desktop wallpapers.
 2. **Color Theory & Aesthetics:** Create or adapt advanced color palettes. You may draw inspiration from established aesthetics (e.g., Everforest, Nord, Gruvbox) or r/unixporn trends, but you should innovate. Ensure perfect harmony between background, foreground, accents, and warning/error colors. 
 3. **Typography & Iconography:** Select and pair fonts (UI vs. Monospace) and icon themes that match the specific vibe of the color palette. 
 4. **Accessibility:** Follow best practices for UI design. Ensure high contrast for text readability and avoid eye strain.
 ### Process
 1. Read the `themes/` directory to understand the codebase.
 2. Explain the "vibe," primary color palette (with hex codes), and typography choices of your proposed design.
 3. Implement the theme by generating or updating the necessary files within the `themes/` structure.
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,3 @@
 # Study material from the previous iteration — not part of the flake.
 # Delete the directory once everything worth porting has been ported.
 old_distro/
 # Nix build artifacts
 result
 result-*
@@ -11,4 +7,3 @@ __pycache__/
 # Claude Code machine-local settings (permissions etc.)
 .claude/settings.local.json
 # .claude/skills/
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,57 @@
 # Nomarchy — agent entry point
 Nomarchy is a NixOS-based distro: rock-stable, fully reproducible, themed
 from one JSON, configured through a menu that writes into the user's own
 flake checkout. Read the README for the architecture.
 This file is the entry point for **any** AI coding agent, whatever the
 vendor or harness. Everything agents need lives in vendor-neutral,
 git-tracked markdown (`agent/`, `docs/`); harness-specific config is a
 thin *adapter* (see bottom) and never holds shared content.
 ## Where things live (read this first)
 | Path | Role |
 |------|------|
 | **`agent/`** | Agent instructions + loop state — **only executable queue is `BACKLOG.md`** |
 | **`agent/README.md`** | Map of the agent files |
 | **`docs/VISION.md`** | Product themes toward **v1.0** (not a queue) |
 | **`docs/ROADMAP.md`** | Design history + shipped log |
 | **`docs/README.md`** | Full documentation map |
 | **`.claude/`** | Claude Code adapter only (permissions, subagents, skill shims) — not the backlog |
 ## If you're here to work autonomously (the loop)
 Follow **`agent/LOOP.md`** — one iteration: orient → pick one BACKLOG
 item → work → verify → commit+push on `main` → record. All loop state is
 git-tracked in `agent/`.
 ## Rules that apply to every session, loop or not
 - **Honesty rule** (`agent/VERIFICATION.md`, `docs/TESTING.md`): for
  visual/interactive changes, evaluation is not rendering — state the
  tier you reached. Cheap first: `nix flake check --no-build`.
 - **Conventions** (`agent/CONVENTIONS.md`): in-flake state, menu
  placement, Waybar parity with whole-swaps, toggle-vs-package discipline,
  template as SoT for opt-in comments (`templates/downstream`).
 - **Git:** direct commits on `main`, pushed; **`v1` is human-only** —
  never touch it. Never `nix flake update` unless the task is a lock bump.
  No formatter — match aligned hand-formatting.
 - Layout: `hosts/` machine · `modules/` distro · `themes/` data ·
  `pkgs/` code · `tools/` maintainer · `agent/` loop · `docs/` human docs.
 ## Delegation & escalation
 Push mechanical work down to cheaper models; keep judgment on the
 strongest model available. Capability tiers, standing roles (scout /
 runner), and per-harness model mappings: **`agent/DELEGATION.md`**.
 Work above your tier? Return it — don't burn tokens.
 ## Harness adapters
 One directory per harness, holding only what that harness *requires* in
 its own format (permissions, subagent/skill registration). Adapters point
 into `agent/`; they never carry policy, queue items, or vision text.
 | Harness | Adapter |
 |---------|---------|
 | Claude Code | `.claude/` — `CLAUDE.md` is a symlink to this file |
 | others | add a sibling dir + a row here; keep it a thin shim |
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,52 +0,0 @@
 # Nomarchy — agent entry point
 Nomarchy is a NixOS-based distro: rock-stable, fully reproducible, themed
 from one JSON, configured through a menu that writes into the user's own
 flake checkout. Read the README for the architecture.
 ## Where things live (read this first)
 | Path | Role |
 |------|------|
 | **`agent/`** | Loop state — **only executable queue is `BACKLOG.md`** |
 | **`docs/VISION.md`** | Product themes toward **v1.0** (not a queue) |
 | **`docs/ROADMAP.md`** | Design history + shipped log |
 | **`docs/README.md`** | Full documentation map |
 | **`agent/README.md`** | Map of loop files |
 | **`.claude/`** | Claude Code only (permissions + subagents) — not the backlog |
 ## If you're here to work autonomously (the loop)
 Follow **`agent/LOOP.md`** — one iteration: orient → pick one BACKLOG
 item → work → verify → commit+push on `main` → record. All loop state is
 git-tracked in `agent/`.
 ## Rules that apply to every session, loop or not
 - **Honesty rule** (`docs/TESTING.md`): for visual/interactive changes,
  evaluation is not rendering — state the tier you reached. Cheap first:
  `nix flake check --no-build`.
 - **Conventions** (`agent/CONVENTIONS.md`): in-flake state, menu
  placement, Waybar parity with whole-swaps, toggle-vs-package discipline,
  template as SoT for opt-in comments (`templates/downstream`).
 - **Git:** direct commits on `main`, pushed; **`v1` is human-only** —
  never touch it. Never `nix flake update` unless the task is a lock bump.
  No formatter — match aligned hand-formatting.
 - Layout: `hosts/` machine · `modules/` distro · `themes/` data ·
  `pkgs/` code · `tools/` maintainer · `agent/` loop · `docs/` human docs.
 ## Delegation
 Push mechanical work down; keep judgment. Brief every child cold.
 | Model | Best for | Delegate? | Effort |
 |---|---|---|---|
 | Haiku | bulk mechanical | never | low |
 | Sonnet | scoped research | when it helps | medium |
 | Opus 4.8 | multi-step reasoning | on clear benefit | xhigh |
 | Fable 5 | judgment, taste | by default | medium |
 Fable goes xhigh only for the hardest calls. Skip high.
 ## Escalation
 An Opus parent can spawn a Fable child for one hard call. Work above your
 tier? Return it — don't burn tokens.
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1 @@
 AGENTS.md
--- a/README.md
+++ b/README.md
@@ -83,10 +83,10 @@ Flat on purpose. Two module trees, one options file each, no hidden layers.
 │   ├── ROADMAP.md                 #   design/decision records + shipped log
 │   ├── HARDWARE.md                #   firmware, profiles, drivers
 │   ├── TESTING.md · RECOVERY.md · OVERRIDES.md · MIGRATION.md
-├── agent/                         # agent loop state — map: agent/README.md
+├── agent/                         # agent instructions + loop state — map: agent/README.md
-│                                  #   BACKLOG (executable queue), LOOP, GOALS, …
+│                                  #   BACKLOG (executable queue), LOOP, VERIFICATION, …
-├── CLAUDE.md                      # agent harness entry (points at agent/ + docs/)
+├── AGENTS.md                      # agent entry, any vendor (CLAUDE.md symlinks here)
-├── .claude/                       # Claude Code only: permissions + subagents
+├── .claude/                       # Claude Code adapter: permissions + subagent/skill shims
 └── tools/                         # maintainer-only
    ├── import-palettes.py         #   converts old-distro themes → JSON + assets
    ├── test-live-iso.sh           #   build the ISO + boot it in QEMU
--- a/agent/DELEGATION.md
+++ b/agent/DELEGATION.md
@@ -0,0 +1,112 @@
 # Delegation — capability tiers, roles, token economy
 How to spend model capacity in this repo, for **any** agent harness.
 Tasks are matched to capability *tiers*, not vendor model names; each
 harness maps tiers to its own models (table at the bottom). GOALS says
 what to build, CONVENTIONS how to write it — this says who does which
 part.
 ## The dividing line: evidence vs judgment
 Cheap models gather evidence; they never make verification claims or
 design decisions. The following always stay on the **frontier** tier and
 are never delegated downward:
 - deciding what to test and the regression scope (VERIFICATION.md)
 - interpreting an ambiguous or flaky failure
 - viewing screenshots and judging visual quality — aesthetic judgment is
  exactly what small models do badly, and it's load-bearing here
 - writing non-trivial Nix (module structure, overlays, cross-cutting
  refactors)
 - the final diff review and report
 Product calls ("finish vs quarantine", promoting PROPOSED items) sit
 above even that: they belong to the human.
 ## Tiers
 | Tier | Best for | Delegate to it? |
 |------|----------|-----------------|
 | **light** | bulk mechanical: search, summarize, audit sweeps, running the harness | freely — never for judgment |
 | **standard** | well-specified scoped edits, routine research | when the spec is already written |
 | **frontier** | design, novel code, ambiguous failures, taste | this is the loop's own tier |
 Reasoning effort: default moderate; go maximum only for the hardest
 calls. A frontier parent may spawn a frontier child for one hard call.
 Work above your tier gets returned, not attempted.
 ## Standing roles
 Two mechanical roles exist for any harness that supports subagents
 (Claude Code implementations: `.claude/agents/`; other harnesses
 implement the same contracts in their own format):
 - **scout** (light, read-only): locate where things are defined, map
  which files touch a subsystem, scan build logs / serial output for
  error lines, docs-vs-code drift sweeps. Reports facts with paths and
  line numbers, quotes the minimum snippet, says "not found" plainly —
  never guesses, never recommends.
 - **runner** (light, executes): builds, VM boots, screenshot capture,
  the scripted `tools/` checks. Headless and unattended, every wait
  bounded by a timeout. Returns commands, exit codes, wall time, and
  artifact paths — never marks anything passed or verified; the caller
  makes the verification claim.
 Use them for pure information-gathering or pure execution instead of
 pulling bulk (log files, wide scans) into the main context. When a
 result surprises you, spot-check it yourself before building on it —
 cheap models are allowed to be wrong about hard things, which is
 precisely why they're not allowed to make claims.
 ## Economy rules
 - **Only delegate when writing the spec is cheaper than doing the
  work** — a spawned agent starts cold and must re-derive context. A
  one-file read is cheaper done directly.
 - **Brief every child cold; point at the spec, don't restate it.** "The
  spec is in `agent/BACKLOG.md` #NN — implement it" plus only the
  *constraints* (scope files, branch, no-VM, no-push).
 - **Match the tier to the task, not the prestige.** An item whose spec
  is already written (exact files, exact fixes) is standard-tier work;
  reserve frontier children for genuine multi-step reasoning. This is
  the single biggest saving.
 - The strong model writes the spec, reviews the result, and owns the
  commit.
 ## Fanning out parallel work (V0/V1, no VM)
 When several NEXT items are independent and don't need the VM, spread
 them across worktree-isolated subagents in parallel:
 - **Disjoint file lanes.** Partition items so no two agents touch the
  same file (map the touched files first). If two items must share a
  file (README, flake.nix, rofi.nix), give both to one agent or keep
  one for yourself.
 - **Isolation + you own landing.** Each agent works in an isolated
  worktree, commits to its own branch, and **never pushes or touches
  `main`/`v1`**. You review each diff, cherry-pick onto `main`, and do
  the bookkeeping — a single landing agent can't race itself. Clean up
  worktrees and branches after landing.
 - **Lean on scriptable checks as primary evidence.** Where a
  deterministic `tools/` check or `checks.*` guard already proves the
  property, that near-free run *is* the V0/V1 evidence.
 - **Batch V2 at the end, once.** Delegated visual/behavioural items come
  back "V2 pending"; collect the landed changes and do **one** VM pass
  covering all of them — the VM render + screenshot review is the most
  expensive step in the loop; amortise it.
 - **Re-verify on `main`, but leanly.** After landing, confirm the
  agent's V0/V1 on the merged tree with a targeted build, not a full
  re-run. Trust-but-spot-check scales; blind re-running doesn't.
 The judgment list above still holds: *you* review every diff before it
 lands.
 ## Per-harness model mapping
 | Tier | Claude Code |
 |------|-------------|
 | light | `haiku` |
 | standard | `sonnet` |
 | frontier | the session's top model (`opus` and up) |
 Other harnesses: add a column when one is actually used on this repo.
--- a/agent/JOURNAL-ARCHIVE.md
+++ b/agent/JOURNAL-ARCHIVE.md
--- a/agent/JOURNAL.md
+++ b/agent/JOURNAL.md
--- a/agent/LOOP.md
+++ b/agent/LOOP.md
@@ -2,12 +2,12 @@
 How an AI agent works on Nomarchy unattended. One **iteration** = pick one
 task, do it, verify it, commit it, record it. The protocol is
-runner-agnostic; the same iteration works under any of:
+harness- and vendor-agnostic; the same iteration works under any of:
- **Interactive `/loop`** in a Claude Code session in this repo — the agent
+- **An interactive self-paced loop** in any agent harness (e.g. `/loop`
-  self-paces iterations until stopped.
+  in Claude Code) — the agent iterates until stopped.
- **Headless** (`claude -p`, cron/systemd-timer) — one invocation runs one
+- **Headless** (a one-shot CLI invocation, cron/systemd-timer) — one
-  iteration (or a small fixed number) and exits.
+  invocation runs one iteration (or a small fixed number) and exits.
 - **A fresh manual session** — a human says "do a loop iteration"; the
  files below carry all the state, so any session can pick up where the
  last left off.
@@ -26,23 +26,25 @@ outside the checkout (the distro's own philosophy, applied to its agents).
 | `HARDWARE-QUEUE.md` | Pending on-hardware checks only Bernardo can run | Agents append, human checks off |
 | `CONVENTIONS.md` | Repo/design conventions to follow while coding | Human (agents propose edits) |
 Instructions live next to the state: `VERIFICATION.md` (enforcement),
 `DELEGATION.md` (tiers/roles/economy), `GOALS.md`, `THEME-DESIGN.md`.
 ## Model & token economy
-Spend expensive tokens on judgment, not mechanics.
+Spend expensive tokens on judgment, not mechanics. Tiers, roles, and the
 full delegation rules are in **`DELEGATION.md`**; the loop-specific
 habits:
 - **Plan and reason on the strong model.** Orientation, task selection,
  design, debugging, Nix eval semantics, verification judgment, and
  anything that would land in a commit unreviewed stay with the
-  top-tier model running the loop (Fable 5).
+  frontier-tier model running the loop.
- **Delegate mechanical subtasks to cheaper models.** When a subtask is
+- **Delegate mechanical subtasks down.** When a subtask is fully
-  fully specified and needs no design judgment — grep/audit sweeps,
+  specified and needs no design judgment — grep/audit sweeps,
  README-option-table reconciliation, a repeated edit applied across
-  files, summarizing long logs or check output — hand it to a subagent
+  files, summarizing long logs or check output — hand it to a
-  with a `model` override: `haiku` for search/summarize/audit, `sonnet`
+  light/standard-tier subagent per `DELEGATION.md`. The strong model
-  for routine well-specified edits. The strong model writes the spec,
+  writes the spec, reviews the result, and owns the commit.
  reviews the result, and owns the commit. Only delegate when writing
  the spec is cheaper than doing the work — a spawned agent starts cold
  and must re-derive context.
 - **Read narrowly.** Step 0's list is the whole orientation read (the
  *last 3–5 entries* of the journal, never the full file). Read large
  files by section, don't re-read what's already in context, and tail
@@ -50,7 +52,7 @@ Spend expensive tokens on judgment, not mechanics.
 - **Write tersely.** Journal entries follow the template and no more;
  commit bodies state what/why/tier, not a narrative.
 - **Headless runners** may run whole low-stakes iterations (QA sweeps,
-  docs-drift passes) on a cheaper `--model`; iterations touching
+  docs-drift passes) on a cheaper model; iterations touching
  `modules/` or `pkgs/` behavior keep the strong model.
 ## One iteration, step by step
--- a/agent/MEMORY.md
+++ b/agent/MEMORY.md
@@ -162,8 +162,9 @@ iteration would otherwise rediscover.
  effects carry a value, matchers take `match:` (§ windowrule migration).
 - grub `loadfont`s every `.pf2` in a theme dir — reuse a bundled DejaVu
  rather than shipping fonts (§ Distro branding).
- `.claude/skills/*/SKILL.md` are now **tracked** (the `.gitignore`
+- `.claude/skills/*/SKILL.md` are **tracked thin shims** — the actual
-  `.claude/skills/` line was un-commented→removed, 7d52d4b) — commit skill
+  instruction bodies live vendor-neutrally in `agent/` (VERIFICATION,
-  edits like any repo doc. Still never `git add -A` blindly: check
+  DELEGATION, THEME-DESIGN); edit those, not the shims. Still never
-  `git status --short` for genuine strangers first (`settings.local.json`,
+  `git add -A` blindly: check `git status --short` for genuine strangers
-  harness-dropped files) and commit with explicit pathspecs (§ loop hygiene).
+  first (`settings.local.json`, harness-dropped files) and commit with
  explicit pathspecs (§ loop hygiene).
--- a/agent/README.md
+++ b/agent/README.md
@@ -1,18 +1,26 @@
-# Agent loop state
+# Agent instructions + loop state
-Git-tracked state for autonomous and assisted work on Nomarchy.
+Everything an AI agent needs to work on Nomarchy, vendor-neutral and
-Protocol: **[LOOP.md](LOOP.md)**. Entry for most harnesses: repo-root
+git-tracked. Protocol: **[LOOP.md](LOOP.md)**. Entry point for every
-**[CLAUDE.md](../CLAUDE.md)**.
+harness: repo-root **[AGENTS.md](../AGENTS.md)**.
-## Files
+## Instructions (how to work)
 | File | Who writes | Role |
 |------|------------|------|
-| [LOOP.md](LOOP.md) | Human | One-iteration protocol (orient → pick → work → verify → commit → record) |
+| [LOOP.md](LOOP.md) | Human | One-iteration protocol (orient → pick → work → verify → commit → record) + the V0–V3 ladder |
 | [VERIFICATION.md](VERIFICATION.md) | Human (agents propose) | Enforcement: preflight, honesty rules, visual protocol, hardware-blocked checks, reporting |
 | [DELEGATION.md](DELEGATION.md) | Human (agents propose) | Capability tiers, scout/runner roles, token economy, parallel fan-out |
 | [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 |
 | [THEME-DESIGN.md](THEME-DESIGN.md) | Human (agents propose) | Theme/visual design instructions |
 ## State (what's happening)
 | File | Who writes | Role |
 |------|------------|------|
 | [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) |
+| [JOURNAL.md](JOURNAL.md) | Agents | Append-only iteration log (read last 3–5 entries; older → [JOURNAL-ARCHIVE.md](JOURNAL-ARCHIVE.md)) |
 | [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 |
@@ -24,15 +32,20 @@ Protocol: **[LOOP.md](LOOP.md)**. Entry for most harnesses: repo-root
 | [../docs/ROADMAP.md](../docs/ROADMAP.md) | Design history + shipped log |
 | [../docs/README.md](../docs/README.md) | Full docs map |
-## Claude Code only
+## Harness adapters (vendor-specific, thin)
-| Path | Role |
+Shared content never lives in an adapter — adapters only register/route
-|------|------|
+into the files above, in whatever format their harness requires.
 | [../.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
+| Path | Harness | Role |
-shared with other agent runners.
+|------|---------|------|
 | [../AGENTS.md](../AGENTS.md) | any | Entry point (`CLAUDE.md` is a symlink to it) |
 | [../.claude/settings.json](../.claude/settings.json) | Claude Code | Tool permissions |
 | [../.claude/agents/](../.claude/agents/) | Claude Code | `nomarchy-scout` / `nomarchy-runner` role defs (contracts in [DELEGATION.md](DELEGATION.md)) |
 | [../.claude/skills/](../.claude/skills/) | Claude Code | Skill shims → VERIFICATION/DELEGATION/THEME-DESIGN |
 Do **not** put backlog items, vision text, or policy under an adapter
 directory — it is not shared with other agent runners.
 ## Rules of thumb
--- a/agent/THEME-DESIGN.md
+++ b/agent/THEME-DESIGN.md
@@ -0,0 +1,49 @@
 # Theme design — instructions for visual work
 For creating, updating, refining, or troubleshooting Nomarchy themes and
 visual design. Act as an experienced UI/UX designer and Linux ricing
 expert for Wayland environments: themes here must be cohesive,
 intentional, and visually striking — aesthetics are a load-bearing
 feature of this distro (`agent/GOALS.md` pillar 4).
 ## Context & architecture
 All theme data lives in `themes/` at the repo root — one JSON palette per
 theme plus per-app assets (whole-swap `waybar.jsonc`/CSS, btop themes,
 wallpapers). Before generating any new configuration, read the existing
 files there: learn how current themes are structured, how the syntax is
 formatted for each application, and how they integrate into the NixOS/HM
 modules. Always match the established pattern — there is no second
 theming pipeline (`agent/GOALS.md` non-goals), so a new visual surface
 consumes the palette from the state JSON, never a side file.
 ## Design responsibilities
 1. **Holistic design:** a theme spans Hyprland (borders, shadows,
   animations), Waybar, Ghostty, btop, fastfetch, rofi, and wallpaper —
   one coherent identity, no unthemed corner.
 2. **Color theory:** create or adapt advanced palettes. Draw inspiration
   from established aesthetics (Everforest, Nord, Gruvbox) or r/unixporn
   trends, but innovate. Ensure harmony between background, foreground,
   accents, and warning/error colors.
 3. **Typography & iconography:** pair UI and monospace fonts and icon
   themes to the specific vibe of the palette.
 4. **Accessibility:** high contrast for text readability; status
   information is never color-only (see `agent/MEMORY.md` design
   invariants — glyph/shape carries state, and identity themes are
   deliberately not traffic-lights).
 ## Process
 1. Read `themes/` to understand the current structure.
 2. State the "vibe", the primary palette (hex codes), and typography
   choices of the proposed design before implementing.
 3. Implement by generating or updating files within the `themes/`
   structure, following `agent/CONVENTIONS.md` (Waybar parity rule:
   whole-swap `waybar.jsonc` files stay in sync with the generated
   config).
 4. Verify per `agent/VERIFICATION.md` §3 — scripted checks first
   (`tools/check-theme-contrast.py`, `tools/audit-theme-design.py`), then
   headless before/after screenshots you actually view, under at least
   two themes. New themes are imported via `tools/import-palettes.py` and
   round-tripped through the theme switcher.
--- a/agent/VERIFICATION.md
+++ b/agent/VERIFICATION.md
@@ -0,0 +1,178 @@
 # Verification — the enforcement rules
 Nomarchy's promise to its user: a rock-stable, fully functional, beautiful
 workstation that is reproducible, easy to recover, and never requires the
 user to become a Nix expert. Every rule below exists to protect that
 promise. A change that works but degrades stability, aesthetics, or
 user-simplicity is a regression, not a feature.
 This document is an **enforcer**, not the workflow itself: the ladder and
 iteration protocol live in `agent/LOOP.md`, VM instructions and gotchas in
 `docs/TESTING.md`. It applies to **every** change to this repo — features,
 fixes, theming, module changes, lock bumps, docs, backlog grooming.
 "Small" or "obvious" changes are exactly where verification gets skipped,
 so they trigger it too. If this file and those docs ever disagree, fix the
 discrepancy in the same or a follow-up commit so they can't disagree
 twice.
 ## 1. Preflight (once per session)
 Before starting work, establish what verification tier this environment
 can reach, so you never promise verification you can't deliver:
 1. Linux x86_64 host? `/dev/kvm` present and readable?
 2. Enough free disk for an image/ISO build (multi-GB)?
 3. Network access for a cold Nix store?
 If the environment cannot reach V2 (no KVM, no disk, etc.): say so
 immediately, do the V0/V1 work honestly, mark the change **"V2 pending"**
 exactly as you would mark a hardware-blocked change "V3 pending" (§4),
 and stop short of claiming the change is done. Never simulate, guess, or
 describe what a VM test "would" show.
 ## 2. The verification ladder (enforcement rules)
 Climb the V0–V3 ladder as defined in `agent/LOOP.md`. Four non-negotiable
 enforcement rules on top:
 1. **V2 is mandatory for anything user-visible.** If a user of the
   installed system could perceive the change — behavior, layout, colors,
   keybinds, timing, error messages — it must be exercised in the local
   VM before commit. Docs-only, comment-only, or agent-notes changes may
   stop at the tier LOOP.md assigns them; user-visible changes may not.
 2. **Every "done" report names the tier reached and shows the evidence.**
   Evidence means: the command run and its relevant output, the checklist
   items exercised, and for visual work the screenshots viewed (§3). "It
   builds" is a V1 claim, not a V2 claim. Never let a report imply a
   higher tier than was actually reached.
 3. **A failed or flaky test is a result, not an obstacle.** Distinguish
   real failures from environment flakes using the known-gotchas section
   of `docs/TESTING.md` (e.g. no-KVM slowness, missing guest GL). If you
   cannot confidently classify a failure, report it as unresolved — do
   not retry until green and report only the green run.
 4. **VM runs are headless and unattended.** Use the repo's headless
   harness — `tools/test-live-iso.sh` and `tools/test-install.sh` for
   boot/install runs, `tools/vm/qmp.py` for programmatic VM control and
   `tools/vm/vncshot.py` for screen capture — never a graphical VM window
   or any flow that needs a human at the console. The human is not part
   of the test loop: do not pause mid-run to ask them to look at the VM,
   click something, or confirm what is on screen. A run must complete on
   its own and leave auditable artifacts behind (logs, serial console
   output, exit codes, screenshots), with every wait bounded by a timeout
   so a hang becomes a recorded failure instead of a stalled session.
   Prefer scripted assertions (process up, file exists, service/D-Bus
   state, the checks in `tools/`) over eyeballing; where judgment is
   genuinely needed — visual quality — *you* view the captured
   screenshots (§3), not the human. The human reviews evidence in the
   final report, never the live run.
 ### Regression scope after a change
 Re-running the full checklist for every change wastes VM time; running
 nothing invites regressions. Default rule:
 - Always: the session-sanity items (boot to session, bar renders).
 - Plus: every checklist item touching the layer you changed.
 - Plus: the theming end-to-end item whenever theming plumbing changed,
  even indirectly (palette generation, symlinks, reload hooks).
 - Lock bumps and toolchain changes: run the full checklist — their blast
  radius is unknowable by construction.
 ## 3. Visual verification protocol
 Visual quality is a core feature of Nomarchy, so "it probably looks fine"
 is never verification. A visual/UI change is not V2-verified until all of
 the following are true:
 1. **Before/after screenshots** of the changed surface were captured
   headlessly — `tools/theme-shot.nix` for reproducible theme renders,
   `tools/vm/vncshot.py` (driven via `tools/vm/qmp.py`) for captures from
   a running VM. No VM window, no human interaction. Capture the "before"
   from the base branch or prior generation, not from memory.
 2. **Scripted checks first**: run `tools/check-theme-contrast.py` and
   `tools/audit-theme-design.py` against the affected theme(s) before any
   eyeballing — machine-checkable legibility/design violations should
   never survive to the judgment stage. Use `tools/vm/gap-analysis.py`
   where it applies.
 3. **Two themes**: repeat the "after" capture under at least two themes,
   one with a generated palette and one whole-swap theme (e.g.
   summer-night). These exercise different code paths in the bar/launcher
   theming; a change that looks right under one can silently break the
   other.
 4. **You actually viewed the images** — open the screenshot files and
   look at them. State concretely what you inspected: alignment, spacing,
   contrast/legibility against the palette, icon rendering, no clipped or
   overlapping elements, and that the change looks intentional next to
   the "before".
 5. Keep the screenshots in the run's working area and reference their
   paths in the report, so the human can audit the same evidence.
 If the VM cannot render the surface faithfully (known GL/compositor gaps
 in the guest — see `docs/TESTING.md`), that specific visual aspect is
 hardware-blocked: verify everything the VM *can* show, and queue the rest
 per §4.
 ## 4. Hardware-blocked checks
 Some checks genuinely require real hardware (GPU behavior, multi-monitor
 hotplug, audio devices, power/suspend, firmware). For those:
 1. Add an entry to `agent/HARDWARE-QUEUE.md` with: what changed, **exact**
   reproduction steps a human can follow verbatim, the expected
   observation (what "pass" looks like), and the commit hash once known.
 2. Mark the commit body **"V3 pending: <one-line summary>"**.
 3. Say it plainly in your report. A hardware-blocked check is not a
   failure and not something to hide — hiding it is the failure.
 4. When the human reports back, close the queue entry in the next commit
   and record the outcome; if it failed on hardware, that's a new bug at
   the top of the backlog.
 Do not use the hardware queue as an escape hatch: if a check *can* be
 done in the VM, it must be. "The VM is slow" does not qualify.
 ## 5. Maintenance work
 Maintenance follows the same ladder:
 - **Flake lock bumps**: treat as maximum-blast-radius changes. Build,
  boot the VM, run the full regression checklist, and do a visual
  spot-check of the session (themes can shift with upstream package
  changes). Never merge a lock bump on "it evaluates".
 - **Theme imports / new themes**: import via `tools/import-palettes.py`,
  then the full §3 visual protocol; additionally verify the theme-switch
  round trip (into the new theme and back out).
 - **Docs drift**: run `tools/check-option-docs.py` after any change that
  adds or modifies options, and fix drift in the same commit as the code
  change that created it. Doc-only fixes are V0 — but verify any command
  you document by actually running it.
 - **Backlog grooming / agent-notes**: V0; keep entries consistent with
  the conventions in `agent/`.
 ## 6. Guarding the philosophy
 Before committing, check the change against the distro's promises
 (`agent/GOALS.md` is the full statement):
 - **User is not a Nix expert.** If the change requires the user to write
  or read Nix to use the feature day-to-day, redesign it. Configuration
  the user touches must stay in the simple, documented surface the repo
  defines.
 - **Rock-stable and recoverable.** Prefer boring, reproducible mechanisms
  over clever ones. Any change that could break boot or the session must
  have an obvious rollback story (NixOS generations count, but say so).
 - **Aesthetics are load-bearing.** A functionally correct but visually
  regressive change fails review by definition — that's what §3 is for.
 When a requested change conflicts with these promises, stop and raise the
 conflict instead of implementing it quietly.
 ## 7. Reporting format
 End every unit of work with a short report containing:
 1. What changed (one paragraph, plain language).
 2. Verification tier reached, with evidence (commands + key output,
   checklist items run, screenshot paths viewed).
 3. Anything pending: "V2 pending" (environment) or "V3 pending"
   (hardware, with queue entry reference).
 4. Follow-ups added to the backlog, if any.
--- a/docs/README.md
+++ b/docs/README.md
@@ -19,9 +19,9 @@ tree for the same facts.
 | Path | Role |
 |------|------|
-| [../agent/README.md](../agent/README.md) | **Executable** agent loop state: BACKLOG, LOOP, MEMORY, … |
+| [../AGENTS.md](../AGENTS.md) | Agent entry point, any vendor/harness (`CLAUDE.md` symlinks to it) |
-| [../CLAUDE.md](../CLAUDE.md) | Agent entry point (any harness that reads it) |
+| [../agent/README.md](../agent/README.md) | Agent instructions + **executable** loop state: BACKLOG, LOOP, VERIFICATION, … |
-| [../.claude/](../.claude/) | Claude Code only: permissions + subagent defs |
+| [../.claude/](../.claude/) | Claude Code adapter only: permissions + subagent/skill shims |
 ## How work flows