diff --git a/README.md b/README.md
index 42e5a8c..94886ea 100644
--- a/README.md
+++ b/README.md
@@ -74,60 +74,84 @@ That's it. Setup installs hooks, scripts, templates, and scaffolds OpenSpec/cave
---
-## AGENTS.md and CLAUDE.md behavior
+## How `AGENTS.md` and `CLAUDE.md` are handled
-GitGuardex does **not** clear repo-owned guidance just because it needs to install its own contract.
+> [!IMPORTANT]
+> **GitGuardex never overwrites your guidance.** Only the content between these markers is managed:
+>
+> ```text
+>
+> ... managed content ...
+>
+> ```
+>
+> Everything outside that block is preserved byte-for-byte.
-- `AGENTS.md` is managed by marker block. `gx setup` and `gx doctor` only refresh the ` ... ` section.
-- Text before or after that marker block stays yours.
-- If `AGENTS.md` exists but has no Guardex markers yet, GitGuardex appends its contract to the end instead of replacing the file.
-- If `AGENTS.md` does not exist, GitGuardex creates it.
-- Root `CLAUDE.md` is **not** separately rewritten by setup/doctor. If your repo keeps a separate `CLAUDE.md`, GitGuardex leaves it alone. In this repo `CLAUDE.md` is a symlink to `AGENTS.md`, so Claude reads the same contract. GitGuardex also installs `.claude/commands/gitguardex.md` for Claude command guidance.
+### Behavior at a glance
-```mermaid
-flowchart TD
- A[Existing AGENTS.md] --> B{Guardex markers already present?}
- B -->|Yes| C[Refresh only the managed block]
- B -->|No| D[Append managed block to the end]
- E[No AGENTS.md yet] --> F[Create AGENTS.md with managed block]
- C --> G[Keep repo-owned text before and after]
- D --> G
-```
+
-Before / after:
+| Your repo has… | `gx setup` / `gx doctor` does… |
+| :--- | :--- |
+| `AGENTS.md` **with** markers | Refreshes **only** the managed block |
+| `AGENTS.md` **without** markers | Appends the managed block to the end |
+| No `AGENTS.md` | Creates it with the managed block |
+| A root `CLAUDE.md` | Leaves it alone |
-```md
-# AGENTS
+
-Project-specific guidance before managed block.
+> [!NOTE]
+> In this repo, `CLAUDE.md` is a symlink to `AGENTS.md`, so Claude reads the same contract. Claude-specific command guidance is installed separately at `.claude/commands/gitguardex.md`.
-
-- old managed contract
-
+### Decision flow
-Trailing repo notes after managed block.
-```
-
-```md
-# AGENTS
+```mermaid
+flowchart TD
+ Start([gx setup / gx doctor])
+ Check{AGENTS.md exists?}
+ Markers{Markers present?}
+ Create[Create AGENTS.md with managed block]
+ Refresh[Refresh the managed block]
+ Append[Append managed block to end of file]
+ Done([Repo-owned text preserved])
-Project-specific guidance before managed block.
+ Start --> Check
+ Check -- No --> Create
+ Check -- Yes --> Markers
+ Markers -- Yes --> Refresh
+ Markers -- No --> Append
+ Create --> Done
+ Refresh --> Done
+ Append --> Done
-
-- current GitGuardex-managed contract
-
+ classDef entry fill:#0b76c5,stroke:#60a5fa,stroke-width:2px,color:#fff
+ classDef decide fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#fff
+ classDef action fill:#374151,stroke:#94a3b8,stroke-width:1.5px,color:#f1f5f9
+ classDef finish fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#fff
-Trailing repo notes after managed block.
+ class Start entry
+ class Check,Markers decide
+ class Create,Refresh,Append action
+ class Done finish
```
-Visual model:
+### What actually changes
-```text
-CLAUDE.md -> AGENTS.md
- ├─ repo-owned text stays
- └─ Guardex refreshes only the marker block
+```diff
+ # AGENTS
+
+ Project-specific guidance before managed block.
+
+
+- - old managed contract
++ - current GitGuardex-managed contract
+
+
+ Trailing repo notes after managed block.
```
+Only lines **inside** the marker block change. Everything above and below is preserved exactly.
+
---
## What `gx` shows first
diff --git a/docs/images/workflow-gx-terminal-status.svg b/docs/images/workflow-gx-terminal-status.svg
index f1a0e3f..b49eac7 100644
--- a/docs/images/workflow-gx-terminal-status.svg
+++ b/docs/images/workflow-gx-terminal-status.svg
@@ -1,45 +1,80 @@
-