Replace README mermaid blocks with rendered WebP diagrams

Author: ImYourBoyRoy

INSTRUCTIONS.md

@@ -198,6 +198,16 @@ Workspace hygiene helper:
 python scripts/clean_workspace.py --dry-run
 ```
 
+### 5.1 README/PyPI flow diagram rendering
+
+Render Mermaid source files to high-resolution static images:
+
+```bash
+python scripts/render_mermaid_diagrams.py --write-manifest
+```
+
+Sources live in `docs/diagrams/*.mmd` and outputs are written to `docs/assets/diagrams/`.
+
 ---
 
 ## 6) Host Learning Lifecycle (auto domain routing)

README.md

@@ -79,33 +79,15 @@ web-scraper --url https://example.com --format markdown --export
 
 ### Simple flow
 
-```mermaid
-flowchart TD
-  A[Input URL(s)] --> B[Runtime Config Resolution]
-  B --> C[Primary Fetch/Crawl Pipeline]
-  C --> D[Parse + Extract]
-  D --> E[Format + Write Output]
-```
+![Simple flow diagram](https://raw.githubusercontent.com/ImYourBoyRoy/WebScraperToolkit/main/docs/assets/diagrams/simple_flow.webp)
 
 ### Advanced flow (dynamic routing)
 
-```mermaid
-flowchart TD
-  A[Input URL(s)] --> B[Resolve Config: CLI > ENV > Files > Defaults]
-  B --> C[Host Profile Lookup]
-  C --> D[Playwright Primary Attempt]
-  D --> E{Blocked or Degraded?}
-  E -- No --> F[Parse + Extract + Save]
-  E -- Yes --> G[Native Browser Fallback Chain]
-  G --> H{Solved?}
-  H -- Yes --> I[Record Telemetry]
-  H -- No --> J[Optional Interactive Challenge Solve]
-  J --> I
-  I --> K[Host Learning Candidate/Promotion]
-  K --> F
-```
+![Advanced routing flow diagram](https://raw.githubusercontent.com/ImYourBoyRoy/WebScraperToolkit/main/docs/assets/diagrams/advanced_flow.webp)
 
-> GitHub renders Mermaid natively. Some package indexes may not render Mermaid; use `INSTRUCTIONS.md` for text flow details.
+> These diagrams are rendered from Mermaid source files for GitHub/PyPI compatibility.
+> Sources: `docs/diagrams/*.mmd`  
+> Rebuild command: `python scripts/render_mermaid_diagrams.py --write-manifest`
 
 ---
 

docs/assets/diagrams/advanced_flow.webp

@@ -0,0 +1,18 @@
+[
+  {
+    "source": "C:/Users/Roy/Desktop/AI_tools/WebScraperToolkit/docs/diagrams/advanced_flow.mmd",
+    "output": "C:/Users/Roy/Desktop/AI_tools/WebScraperToolkit/docs/assets/diagrams/advanced_flow.webp",
+    "output_width": 880,
+    "output_height": 3104,
+    "theme": "neutral",
+    "format": "webp"
+  },
+  {
+    "source": "C:/Users/Roy/Desktop/AI_tools/WebScraperToolkit/docs/diagrams/simple_flow.mmd",
+    "output": "C:/Users/Roy/Desktop/AI_tools/WebScraperToolkit/docs/assets/diagrams/simple_flow.webp",
+    "output_width": 2706,
+    "output_height": 140,
+    "theme": "neutral",
+    "format": "webp"
+  }
+]

docs/assets/diagrams/manifest.json

@@ -0,0 +1,14 @@
+%% ./docs/diagrams/advanced_flow.mmd
+flowchart TB
+  A["Input URLs"] --> B["Resolve config precedence"]
+  B --> C["Lookup host profile"]
+  C --> D["Primary Playwright attempt"]
+  D --> E{"Blocked or degraded?"}
+  E -- "No" --> F["Parse, extract, and save"]
+  E -- "Yes" --> G["Native browser fallback chain"]
+  G --> H{"Solved?"}
+  H -- "Yes" --> I["Record telemetry"]
+  H -- "No" --> J["Interactive challenge solve"]
+  J --> I
+  I --> K["Host learning promotion or demotion"]
+  K --> F

docs/assets/diagrams/simple_flow.webp

@@ -0,0 +1,6 @@
+%% ./docs/diagrams/simple_flow.mmd
+flowchart LR
+  A["Input URLs"] --> B["Resolve runtime config"]
+  B --> C["Fetch and crawl pipeline"]
+  C --> D["Parse and extract content"]
+  D --> E["Format and write output"]