diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index 40df57d..bffd3e0 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -8,46 +8,55 @@ ModelDock is a **management layer** that sits above local model runtimes. It doe
 
 Dependencies point inward — Clean Architecture with SOLID principles:
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Interface / Delivery Layer                                   │
-│  - Python SDK (modeldock/__init__.py public API)              │
-│  - CLI (modeldock/cli)  → Typer                               │
-└─────────────────────────────────────────────────────────────┘
-                          │ uses
-┌─────────────────────────────────────────────────────────────┐
-│  Application / Use-Case Layer (modeldock/core)                │
-│  - ModelService, RegistryService, DownloadService,           │
-│    CacheService, ConfigService, LifecycleOrchestrator        │
-│  - Orchestrates "load missing → download → verify → load"    │
-└─────────────────────────────────────────────────────────────┘
-                          │ depends on (abstractions)
-┌─────────────────────────────────────────────────────────────┐
-│  Domain Layer (modeldock/domain) — pure, no I/O               │
-│  - Model, ModelSpec, ModelAlias, Capability, Category,       │
-│    RuntimeBackend, DownloadStatus, exceptions                 │
-└─────────────────────────────────────────────────────────────┘
-                          │ implemented by
-┌─────────────────────────────────────────────────────────────┐
-│  Port / Abstraction Layer (modeldock/ports)                   │
-│  - RuntimePort, RegistryPort, DownloaderPort, CachePort,     │
-│    ProgressPort, EventPort                                    │
-└─────────────────────────────────────────────────────────────┘
-                          │ adapters
-┌─────────────────────────────────────────────────────────────┐
-│  Adapter / Infrastructure Layer (modeldock/adapters)         │
-│  - runtimes/ollama.py (first), lmstudio, llamacpp, jan,      │
-│    gpt4all, vllm (future)                                     │
-│  - registry/ (dynamic Ollama catalog + bundled fallback)      │
-│  - downloaders/ (http, ollama-native pull)                   │
-│  - cache/ (filesystem cache)                                 │
-│  - progress/ (rich, tqdm, silent)                            │
-└─────────────────────────────────────────────────────────────┘
-                          │
-┌─────────────────────────────────────────────────────────────┐
-│  Cross-cutting (modeldock/common)                            │
-│  - config, logging, errors, platform utils, http client      │
-└─────────────────────────────────────────────────────────────┘
+```mermaid
+graph TB
+    subgraph Interface["Interface / Delivery Layer"]
+        SDK["Python SDK<br/>modeldock/__init__.py"]
+        CLI["CLI<br/>modeldock/cli → Typer"]
+    end
+
+    subgraph Application["Application / Use-Case Layer"]
+        CORE["modeldock/core/<br/>ModelManager · LifecycleOrchestrator<br/>RegistryService · DownloadService<br/>CacheService · ConfigService"]
+    end
+
+    subgraph Domain["Domain Layer — pure, no I/O"]
+        DOMAIN["modeldock/domain/<br/>Model · ModelSpec · ModelAlias<br/>Capability · Category<br/>RuntimeBackend · Exceptions"]
+    end
+
+    subgraph Ports["Port / Abstraction Layer"]
+        PORTS["modeldock/ports/<br/>RuntimePort · RegistryPort<br/>DownloaderPort · CachePort<br/>ProgressPort · EventPort"]
+    end
+
+    subgraph Adapters["Adapter / Infrastructure Layer"]
+        RUNTIMES["runtimes/<br/>ollama · lmstudio<br/>llamacpp · jan · gpt4all · vllm"]
+        REGISTRY["registry/<br/>dynamic catalog + bundled fallback"]
+        DOWNLOADERS["downloaders/<br/>http · ollama-native pull"]
+        CACHE["cache/<br/>filesystem cache"]
+        PROGRESS["progress/<br/>rich · tqdm · silent"]
+    end
+
+    subgraph Common["Cross-cutting"]
+        COMMON["modeldock/common/<br/>config · logging · errors<br/>platform utils · http client"]
+    end
+
+    SDK --> CORE
+    CLI --> CORE
+    CORE --> PORTS
+    CORE --> DOMAIN
+    PORTS --> RUNTIMES
+    PORTS --> REGISTRY
+    PORTS --> DOWNLOADERS
+    PORTS --> CACHE
+    PORTS --> PROGRESS
+    COMMON -.-> CORE
+    COMMON -.-> ADAPTERS
+
+    style Interface fill:#37474f,stroke:#26a69a,color:#fff
+    style Application fill:#455a64,stroke:#26a69a,color:#fff
+    style Domain fill:#546e7a,stroke:#26a69a,color:#fff
+    style Ports fill:#607d8b,stroke:#26a69a,color:#fff
+    style Adapters fill:#78909c,stroke:#26a69a,color:#fff
+    style Common fill:#90a4ae,stroke:#26a69a,color:#fff
 ```
 
 ---
diff --git a/docs/index.md b/docs/index.md
index 52b99ed..fa2d9f9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,6 +8,8 @@ hide:
 
 <div class="hero-banner" markdown>
 
+<img src="images/modeldock.png" alt="ModelDock" width="320" style="margin-bottom: 1rem;">
+
 ### The package manager for local AI models
 
 Lightweight. Python-first. Zero-config.
diff --git a/mkdocs.yml b/mkdocs.yml
index 18578a1..123e5e8 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -107,7 +107,11 @@ markdown_extensions:
   # Built-in
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
@@ -151,3 +155,6 @@ extra:
 
 extra_css:
   - stylesheets/custom.css
+
+extra_javascript:
+  - https://unpkg.com/mermaid@10/dist/mermaid.min.js