diff --git a/.issueflows/01-current-issues/issue397_original.md b/.issueflows/03-solved-issues/issue397_original.md
similarity index 100%
rename from .issueflows/01-current-issues/issue397_original.md
rename to .issueflows/03-solved-issues/issue397_original.md
diff --git a/.issueflows/01-current-issues/issue397_status.md b/.issueflows/03-solved-issues/issue397_status.md
similarity index 68%
rename from .issueflows/01-current-issues/issue397_status.md
rename to .issueflows/03-solved-issues/issue397_status.md
index 4a1c002..e2ed817 100644
--- a/.issueflows/01-current-issues/issue397_status.md
+++ b/.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`.
diff --git a/.issueflows/04-designs-and-guides/docs-diagrams.md b/.issueflows/04-designs-and-guides/docs-diagrams.md
index 34b3310..eb16ad5 100644
--- a/.issueflows/04-designs-and-guides/docs-diagrams.md
+++ b/.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. `
` 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
diff --git a/HISTORY.md b/HISTORY.md
index 70f20f8..774879d 100644
--- a/HISTORY.md
+++ b/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)
diff --git a/docs/concepts.md b/docs/concepts.md
index 3d67d64..04e3f6c 100644
--- a/docs/concepts.md
+++ b/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
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
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` |