docs: Flows map with knobs (#397)

.issueflows/01-current-issues/issue397_original.md

@@ -0,0 +1,11 @@
+# Issue #397: Iterative fixes: docs-flow-diagram
+
+Source: https://github.com/jepegit/issue-flow/issues/397
+
+## Original issue text
+
+Interactive `/iflow-fix` session for iterative small fixes.
+
+Individual fixes are recorded in the status markdown and landed together via `/iflow-close`.
+
+**First intent:** Add a flow diagram of the available flows in the docs, including configuration knobs.

.issueflows/01-current-issues/issue397_status.md

@@ -0,0 +1,9 @@
+# Issue #397: Iterative fixes: docs-flow-diagram
+
+Interactive `/iflow-fix` session. Fixes recorded below; land together via `/iflow-close`.
+
+- [ ] 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`.

docs/concepts.md

@@ -128,6 +128,91 @@ starts it for you. That includes:
 `iflow` may *mention* an off-path command (for example "run `iflow cleanup`
 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).
+
+```mermaid
+flowchart TB
+    subgraph start [Start work]
+        setup(["setup"])
+        pick(["pick"])
+        issueCmd(["issue"])
+        fix(["fix"])
+    end
+
+    subgraph onpath [On-path — dispatcher iflow]
+        capture["capture"]
+        plan["plan"]
+        build["build"]
+        close["close"]
+        capture --> plan --> build --> close
+    end
+
+    subgraph hands [Hands-off / batch]
+        yolo(["yolo"])
+        cycle(["cycle"])
+        auto(["auto"])
+        drive(["drive"])
+        ops(["ops"])
+    end
+
+    subgraph big [Bigger than one issue]
+        epic(["epic"])
+        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
+
+    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
+```
+
+| Knob | Steers | Default |
+| --- | --- | --- |
+| `mode` | Which commands exist at all (`standard` / `novice` / `simple`) | `standard` |
+| `worktree_first` | `pick` / `issue` / `fix` start in a sibling worktree vs `inplace` | `true` |
+| `auto_plan` | After pick, chain into plan | `true` |
+| `auto_build` | After plan approval, chain into build | `true` |
+| `auto_close` | After build (or end of fix), chain into close | `false` |
+| `early_pr` | Build opens a draft PR after the first push | `false` |
+| `label_flows` | Pick routes by issue label (`yolo_label` → yolo, `ops_label` → ops) | `true` |
+| `publish_label` | Close bumps + creates a GitHub release after merge | `"publish"` |
+| `auto_cleanup` | After a PR exists, watch merge then run cleanup | `false` |
+| `auto_switchback` | After close opens a PR, switch home to the default branch | `true` |
+| `auto_remove_worktree` | Close removes the issue worktree when the tree is clean | `true` |
+| `pr_merge_method` | How hands-off closes merge (`squash` / `merge` / `rebase`) | `squash` |
+| `cycle_max_issues` / `cycle_onfail` / `cycle_nonyolo` | Cycle queue size, failure policy, non-yolo merge policy | `10` / `stop` / `merge` |
+| `auto_adversarial_loops` | Auto review-and-fix loops per stage before it asks | `2` |
+| `model_label_flows` | Pick announces deep/fast model from labels | `false` |
+
+Per-run tokens (`inplace`, `worktree`, `noplan`, `nobuild`, `noearly`, …) override
+the matching knob for that run only. See [Configuration](configuration.md) and
+[Work in a sibling worktree](how-to/worktrees.md).
+
 ## Where the agent always stops to ask
 
 The workflow is built so that nothing surprising happens without you seeing it

docs/how-to/index.md

@@ -6,7 +6,9 @@ title: How-to guides
 
 Short, task-oriented paths. Each page is goal → steps → related links — not a
 full command reference. Unfamiliar terms (focus issue, off-path, yolo, epic
-stage …) are explained in [Concepts](../concepts.md). For every slash command in detail, see
+stage …) are explained in [Concepts](../concepts.md). For a single diagram of
+every flow and the knobs that steer them, see
+[Flows map](../concepts.md#flows-map). For every slash command in detail, see
 [Command reference](../issue-workflow.md).
 
 ## Quick recipes

docs/index.md

@@ -30,7 +30,8 @@ In your editor's chat window:
 
 Forgot where you are? Type `iflow` and it runs the next step. For small issues,
 larger changes split into stages, and batch runs, see the
-[How-to guides](how-to/index.md).
+[How-to guides](how-to/index.md). A map of every flow and the knobs that steer
+them is in [Flows map](concepts.md#flows-map).
 
 ## Start here