diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4a2a804..e8cf19d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,13 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Documentation
+
+- **Visual flow diagrams in the entry-point docs.** A "one source → every tool + pre-action gate"
+  mermaid in `README.md` and a "your day with Forge" loop in `ONBOARDING.md` (alongside the
+  propose→verify diagram in the substrate README) — making the model easier to grasp at a glance,
+  while preserving the docs' existing dry-precise voice.
+
 ### Added
 
 - **Uniform `--json`.** `doctor`, `route`, `preflight`, `verify`, and `scope` now accept `--json`
diff --git a/ONBOARDING.md b/ONBOARDING.md
index 61d4c15..94afd25 100644
--- a/ONBOARDING.md
+++ b/ONBOARDING.md
@@ -4,6 +4,16 @@
 > agents (Claude Code, Codex, Cursor, Gemini, Aider…). Author your rules once; it
 > configures every tool and adds memory, blast-radius checks, and guardrails.
 
+```mermaid
+flowchart TD
+    I["forge init"] --> Cfg["every tool configured<br/>from one source"]
+    Cfg --> Work["you work as usual"]
+    Work --> Gate["substrate checks each task:<br/>ask first? · which model? · what breaks?"]
+    Gate --> Edit["agent edits, with guardrails"]
+    Edit --> Learn["cortex learns from corrections"]
+    Learn -.->|next task is smarter| Work
+```
+
 ## 1. Install (once)
 
 The recommended paths need no token and no clone:
diff --git a/README.md b/README.md
index 745cbf7..b09ca6e 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,21 @@ a cost governor, and a **cognitive substrate** that checks a task *before* the a
 touches your code. Works with **Claude Code, Codex, Cursor, Gemini, Aider, Copilot,
 Windsurf, Zed, and Continue** (plus MCP config for Roo and VS Code).
 
+```mermaid
+flowchart LR
+    S["source/rules.json<br/>(author once)"] -->|forge sync| E{{emit}}
+    E --> C["CLAUDE.md"]
+    E --> A["AGENTS.md"]
+    E --> R[".cursor / .gemini<br/>.aider / …"]
+    E --> M["MCP config"]
+    S -.->|forge substrate| G["pre-action gate<br/>assumptions · route · impact · verify"]
+    G -.-> Agent(("your AI agent"))
+    C --> Agent
+    A --> Agent
+    R --> Agent
+    M --> Agent
+```
+
 > **Status: beta.** The core (`init`, `sync`, `substrate`, `impact`, `cortex`, guards)
 > is tested and in daily use; some flags may change before `1.0`.