docs: replace ASCII art with Mermaid diagrams, add diagram conventions

- Convert ASCII flowcharts in docs/README.md and design.md to Mermaid
- Fix \n -> <br> in Mermaid node labels
- Add Diagrams section to coding-standards.md: Mermaid only, <br> for line breaks

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: flemming-n-larsen

.agents/instructions/coding-standards.md

@@ -38,6 +38,14 @@ Rules selected: `E` (pycodestyle), `F` (pyflakes), `I` (isort), `N` (pep8-naming
 
 No additional linters. Ruff is the single lint/format tool.
 
+## Diagrams
+
+Use Mermaid for all diagrams in documentation and design files:
+
+- Use fenced ` ```mermaid ` blocks — never ASCII / box-art
+- Use `<br>` for line breaks inside node labels, not `\n`
+- File trees (directory listings) are the one exception — keep them as indented text
+
 ## Testing
 
 pytest with standard conventions:

docs/README.md

@@ -4,25 +4,13 @@ iec-cli is a Python CLI tool that validates Intent Engineering practices in any
 
 ## Design
 
-```
-┌──────────┐     ┌─────────────────┐     ┌──────────────┐
-│   User   │────▶│  iec-cli (CLI)  │────▶│  Repo files  │
-└──────────┘     └────────┬────────┘     └──────────────┘
-                          │
-                 ┌────────▼────────┐
-                 │  Deterministic   │
-                 │  checks (Python) │
-                 └────────┬────────┘
-                          │
-                 ┌────────▼────────┐
-                 │  MCP Server      │
-                 │  (agent-assisted)   │
-                 └────────┬────────┘
-                          │
-                 ┌────────▼────────┐
-                 │  User's agent       │
-                 │  Agent (BYOK)    │
-                 └─────────────────┘
+```mermaid
+flowchart LR
+    User --> CLI["iec-cli (CLI)"]
+    CLI --> Repo["Repo files"]
+    CLI --> Det["Deterministic<br>checks (Python)"]
+    Det --> MCP["MCP Server<br>(agent-assisted)"]
+    MCP --> Agent["User's agent<br>(BYOK)"]
 ```
 
 ## Two-Layer Check Architecture

openspec/changes/archive/2026-05-05-check/design.md

@@ -98,27 +98,16 @@ Registry:
 
 ## Architecture
 
-```
-iec check [--path <dir>]
-    │
-    ▼
-main.py: app.add_typer(check_app)
-    │
-    ▼
-check.py: check_app (Typer)
-    │
-    ├── registry.run_all(Path) → list[CheckResult]
-    │       │
-    │       └── for each registered Checker:
-    │               checker.check(path)
-    │
-    ├── ResultCollector aggregates results
-    │       ├── pass_count, warn_count, fail_count
-    │       └── by_severity, by_checker groupings
-    │
-    └── Output formatter prints summary
-            ├── Per-checker: ✓ PASS / ⚠ WARN / ✗ FAIL
-            └── Exit code: 0 (all pass), 1 (warnings), 2 (failures)
+```mermaid
+flowchart TD
+    CMD["iec check [--path dir]"] --> Main["main.py<br>app.add_typer(check_app)"]
+    Main --> App["check.py: check_app (Typer)"]
+    App --> Registry["registry.run_all(Path) → list[CheckResult]"]
+    Registry --> Checkers["for each Checker:<br>checker.check(path)"]
+    App --> Collector["ResultCollector<br>pass_count / warn_count / fail_count<br>by_severity, by_checker"]
+    App --> Formatter["Output formatter"]
+    Formatter --> PerCheck["Per-checker: ✓ PASS / ⚠ WARN / ✗ FAIL"]
+    Formatter --> Exit["Exit code: 0 all pass / 1 warnings / 2 failures"]
 ```
 
 ## Risks / Trade-offs