Color the Flows map so roles and path weight are easy to scan

.issueflows/01-current-issues/issue397_status.md → .issueflows/03-solved-issues/issue397_status.md

@@ -2,8 +2,9 @@
 
 Interactive `/iflow-fix` session. Fixes recorded below; land together via `/iflow-close`.
 
-- [ ] Done
+- [x] Done
 
 ## Iterative fixes log
 
 - 2026-09-27: Added Flows map (mermaid + knobs table) to `docs/concepts.md`; linked from `docs/index.md` and `docs/how-to/index.md`.
+- 2026-09-27: Restyled the Flows map with role colours and thicker on-path arrows; noted the exception in `docs-diagrams.md`.

.issueflows/04-designs-and-guides/docs-diagrams.md

@@ -18,14 +18,15 @@ when the reader switches between light and dark mode.
 
 Current diagrams:
 
-- `docs/concepts.md`: the lifecycle (pick → cleanup), what `iflow` dispatches from which file state (with off-path commands dotted), and folder moves between `01-` / `02-` / `03-`.
+- `docs/concepts.md`: the lifecycle (pick → cleanup), what `iflow` dispatches from which file state (with off-path commands dotted), folder moves between `01-` / `02-` / `03-`, and the Flows map (role colours and stroke width).
 - `docs/how-to/epics.md`: the epic flow (anchor → plan → publish → stages). The old text tree stays underneath.
 
 Conventions:
 
 - Use `flowchart` with short labels. `<br/>` for line breaks.
 - Solid arrows for what issue-flow does on its own; dotted (`-.->`) for off-path commands the user runs.
-- No custom colours, so the theme's palette applies in both modes.
+- Leave colour to the theme, so light and dark mode both stay readable.
+- Exception (issue #397): the Flows map sets role colours with fill and text together on each node, and sets stroke width on edges (thick on-path chain, medium usual path, thin dotted knobs). A text key under the diagram repeats the encoding. Other diagrams stay on the theme palette.
 
 ## Alternatives considered
 

HISTORY.md

@@ -9,6 +9,8 @@ than the GitHub release notes they link to.
 
 ## [Unreleased]
 
+- Iterative fixes: docs-flow-diagram. (#397)
+
 ## [0.5.17] - 2026-09-26
 
 - Workspace-wide cleanup: `issue-flow workspace cleanup` classifies every member's local branches with the same code as `agent local-branches` (read-only by default; `--apply` runs Phase A1, `--apply --yes-delete-squash-landed` adds the `-D` phase with tip SHAs), skipping members with a dirty product-code tree, detached HEAD, or no `origin`, and never pulling a member whose default cannot fast-forward. `/iflow-cleanup all` consumes it with one A1 confirm and one A2 confirm for the whole workspace instead of one pair per repo. (#392)

docs/concepts.md

@@ -130,9 +130,10 @@ after the PR merges"), but it never runs one.
 
 ## Flows map
 
-How the main entry points relate, and which **knobs** steer them. Solid arrows
-are the usual path; dotted ones are opt-in or label-driven. Full knob list:
-[Configuration](configuration.md).
+How the main entry points relate, and which **knobs** steer them. Thick arrows
+are the on-path chain, medium arrows are the usual path, and thin dotted arrows
+are opt-in or label-driven. Color marks the role; the key sits under the
+diagram. Full knob list: [Configuration](configuration.md).
 
 ```mermaid
 flowchart TB
@@ -148,7 +149,7 @@ flowchart TB
         plan["plan"]
         build["build"]
         close["close"]
-        capture --> plan --> build --> close
+        capture ==> plan ==> build ==> close
     end
 
     subgraph hands [Hands-off / batch]
@@ -164,33 +165,63 @@ flowchart TB
         split(["split"])
     end
 
-    setup -.->|harness ready| pick
     pick -->|worktree_first| capture
-    pick -.->|label_flows + yolo_label| yolo
-    pick -.->|label_flows + ops_label<br/>ops wins over yolo| ops
     issueCmd -->|worktree_first| capture
     fix -->|worktree_first| capture
-    fix -.->|auto_close| close
+    close -->|PR merged| cleanup(["cleanup"])
+    yolo -->|"one confirm → full on-path chain"| capture
+    cycle -->|"each queued issue"| yolo
+    epic -->|"publish stages"| cycle
+    auto -->|"per stage"| cycle
+    drive --> epic
+    drive --> auto
+    ops --> close
 
+    setup -.->|harness ready| pick
+    pick -.->|label_flows + yolo_label| yolo
+    pick -.->|label_flows + ops_label<br/>ops wins over yolo| ops
+    fix -.->|auto_close| close
     pick -.->|auto_plan| plan
     plan -.->|auto_build| build
     build -.->|early_pr| close
     build -.->|auto_close| close
-    close -->|PR merged| cleanup(["cleanup"])
     close -.->|publish_label| release["gh release"]
     close -.->|auto_cleanup| cleanup
     close -.->|auto_switchback / auto_remove_worktree| home["default branch"]
-
-    yolo -->|"one confirm → full on-path chain"| capture
-    cycle -->|"each queued issue"| yolo
-    epic -->|"publish stages"| cycle
-    auto -->|"per stage"| cycle
-    drive --> epic
-    drive --> auto
     split -.->|"2–5 children"| pick
-    ops --> close
+
+    classDef startNode fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0c4a6e
+    classDef onpathNode fill:#dbeafe,stroke:#1d4ed8,stroke-width:2.5px,color:#1e3a8a
+    classDef handsNode fill:#ffedd5,stroke:#c2410c,stroke-width:2px,color:#7c2d12
+    classDef bigNode fill:#ede9fe,stroke:#6d28d9,stroke-width:2px,color:#4c1d95
+    classDef exitNode fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d
+
+    class setup,pick,issueCmd,fix startNode
+    class capture,plan,build,close onpathNode
+    class yolo,cycle,auto,drive,ops handsNode
+    class epic,split bigNode
+    class cleanup,release,home exitNode
+
+    %% Link order is the stroke key. Keep new edges in the matching group.
+    linkStyle 0,1,2 stroke:#1d4ed8,stroke-width:4px
+    linkStyle 3,4,5 stroke:#0369a1,stroke-width:2.5px
+    linkStyle 6 stroke:#15803d,stroke-width:3px
+    linkStyle 7 stroke:#1d4ed8,stroke-width:2.5px
+    linkStyle 8,9,10 stroke:#c2410c,stroke-width:2.5px
+    linkStyle 11 stroke:#6d28d9,stroke-width:2.5px
+    linkStyle 12 stroke:#c2410c,stroke-width:2.5px
+    linkStyle 13 stroke:#1d4ed8,stroke-width:2.5px
+    linkStyle 14 stroke:#0369a1,stroke-width:1px
+    linkStyle 15,16 stroke:#c2410c,stroke-width:1px
+    linkStyle 17,18,19,20,21 stroke:#1d4ed8,stroke-width:1px
+    linkStyle 22,23,24 stroke:#15803d,stroke-width:1px
+    linkStyle 25 stroke:#0369a1,stroke-width:1px
 ```
 
+**Key.** Blue nodes start work. Deeper blue is the on-path chain (thick arrows).
+Orange is hands-off. Purple is bigger than one issue. Green is the exit.
+Medium solid arrows are the usual path; thin dotted arrows are opt-in knobs.
+
 | Knob | Steers | Default |
 | --- | --- | --- |
 | `mode` | Which commands exist at all (`standard` / `novice` / `simple`) | `standard` |