diff --git a/ROADMAP.md b/ROADMAP.md
index 1f94bcc92..19c2bc550 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -39,7 +39,7 @@ docs, adapters, services, plugins, and the bundled console integration.
 | P0 | Keep public docs aligned with the environment rename. | Prevent users from copying stale `project` route/header/env examples. |
 | P0 | Keep CLI/docs/examples aligned with actual scripts: `pnpm dev`, `pnpm dev:crm`, `os dev`, `os start`, `os serve`, `os publish`. | Avoid broken onboarding. |
 | P0 | Remove references to deleted app/service packages from current docs. | `apps/cloud`, `apps/objectos`, `apps/studio`, and `service-tenant` no longer exist in this repo. |
-| P1 | Document Flow-first automation and workflow state-machine semantics. | Old Workflow Rule docs imply a retired Salesforce-style rule engine. |
+| ~~P1~~ done | ~~Document Flow-first automation and workflow state-machine semantics.~~ Flow automation is documented in [guides/metadata/flow](content/docs/guides/metadata/flow.mdx) (triggers, nodes, structured control flow, durable pause/resume, parallel + batch approval, run observability) and the ADR-0019/0031/0039 series; state-machine semantics in [guides/metadata/workflow](content/docs/guides/metadata/workflow.mdx) + [validation](content/docs/guides/metadata/validation.mdx). | Old Workflow Rule docs implied a retired Salesforce-style rule engine. |
 | P1 | Document explicit AI action opt-in via action metadata. | AI tool exposure is no longer automatic for every action. |
 | P1 | Document implemented formula, summary, autonumber, notifications, and master-detail behavior. | Recent runtime work is under-documented and older status pages still mark it missing. |
 | P2 | Regenerate reference docs after Zod description updates. | Keeps generated schema pages consistent without hand-editing them. |
diff --git a/content/docs/guides/metadata/flow.mdx b/content/docs/guides/metadata/flow.mdx
index 8880a9076..528c333e2 100644
--- a/content/docs/guides/metadata/flow.mdx
+++ b/content/docs/guides/metadata/flow.mdx
@@ -113,6 +113,7 @@ Each node performs a specific action in the flow.
 | `screen` | Display a user form/screen (durable pause) |
 | `wait` | Pause for a timer or named signal (durable pause; timers auto-resume) |
 | `subflow` | Invoke another flow — a pause inside the child suspends both runs as a linked chain |
+| `map` | Sequential multi-instance — run a per-item subflow for each element, one at a time (each may pause); batch approval (ADR-0039) |
 | `connector_action` | Execute an external connector action |
 
 ### Node Structure