Updated README again and added assets folder

README.md

@@ -19,7 +19,7 @@ Free Claude Code routes Anthropic Messages API traffic from Claude Code to NVIDI
 </div>
 
 <div align="center">
-  <img src="pic.png" alt="Free Claude Code in action" width="700">
+  <img src="assets/pic.png" alt="Free Claude Code in action" width="700">
 </div>
 
 ## Star History
@@ -95,7 +95,7 @@ Many terminals make these clickable. Use your configured `PORT` if it is not `80
 Open the **Admin UI** URL from the terminal output.
 
 <div align="center">
-  <img src="screenshots/admin-page.png" alt="Local admin UI for proxy settings" width="700">
+  <img src="assets/admin-page.png" alt="Local admin UI for proxy settings" width="700">
 </div>
 
 ### 5. Configure Provider And Model
@@ -347,7 +347,7 @@ Claude Code 2.1.126 or later can populate `/model` from this proxy's Gateway `/v
 Start Claude Code with that variable set (see [Quick Start](#4-run-claude-code)), run `/model`, and choose any discovered provider model.
 
 <div align="center">
-  <img src="cc-model-picker.png" alt="Claude Code model picker showing gateway models" width="700">
+  <img src="assets/cc-model-picker.png" alt="Claude Code model picker showing gateway models" width="700">
 </div>
 
 The proxy lists models for configured provider keys and referenced local providers. Picker-safe IDs are routed back to the real provider/model automatically, so no `.env` edit or separate launcher script is needed after startup.
@@ -540,17 +540,11 @@ Confirm the extension environment variables are set, then reload the extension o
 
 ## How It Works
 
-```text
-Claude Code CLI / IDE
-        |
-        | Anthropic Messages API
-        v
-Free Claude Code proxy (:8082)
-        |
-        | provider-specific request/stream adapter
-        v
-NIM / Kimi / Wafer / OpenRouter / DeepSeek / LM Studio / llama.cpp / Ollama
-```
+<div align="center">
+  <img src="assets/how-it-works.svg" alt="Free Claude Code request flow architecture" width="900">
+</div>
+
+Diagram source: [`assets/how-it-works.mmd`](assets/how-it-works.mmd).
 
 Important pieces:
 

assets/how-it-works.mmd

@@ -0,0 +1,51 @@
+%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Inter, ui-sans-serif, system-ui, Segoe UI, Arial", "background": "transparent", "primaryTextColor": "#172033", "lineColor": "#718096"}}}%%
+flowchart LR
+    client(["Claude Code<br/>CLI / IDE / Bots"])
+    api["Anthropic-compatible API<br/>/v1/messages, /v1/models"]
+
+    subgraph proxy["Free Claude Code Proxy :8082"]
+        admin["Local Admin UI<br/>keys, models, status"]
+        config[("Managed Config<br/>~/.config/free-claude-code/.env")]
+        router{"Model Router<br/>Opus / Sonnet / Haiku"}
+        optimize["Request Optimizations<br/>cheap local probes"]
+        normalize["Protocol Normalizer<br/>streaming, tools, thinking"]
+        adapters["Provider Adapters<br/>Anthropic + OpenAI-compatible"]
+    end
+
+    subgraph hosted["Hosted Providers"]
+        nim(["NVIDIA NIM"])
+        kimi(["Kimi"])
+        wafer(["Wafer"])
+        openrouter(["OpenRouter"])
+        deepseek(["DeepSeek"])
+    end
+
+    subgraph local["Local Providers"]
+        lmstudio(["LM Studio"])
+        llamacpp(["llama.cpp"])
+        ollama(["Ollama"])
+    end
+
+    client -->|"Anthropic Messages"| api
+    api --> router
+    admin --> config
+    config --> router
+    router --> optimize
+    optimize --> normalize
+    normalize --> adapters
+    adapters --> hosted
+    adapters --> local
+
+    classDef client fill:#efe7ff,stroke:#7c3aed,stroke-width:2px,color:#2e1065;
+    classDef api fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#172554;
+    classDef proxy fill:#ecfeff,stroke:#0891b2,stroke-width:2px,color:#164e63;
+    classDef config fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f;
+    classDef transform fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
+    classDef provider fill:#fff7ed,stroke:#ea580c,stroke-width:2px,color:#7c2d12;
+
+    class client client;
+    class api api;
+    class admin,router proxy;
+    class config config;
+    class optimize,normalize,adapters transform;
+    class nim,kimi,wafer,openrouter,deepseek,lmstudio,llamacpp,ollama provider;