diff --git a/src/cmdforge/web/templates/base.html b/src/cmdforge/web/templates/base.html
index 4608ca1..fe4c208 100644
--- a/src/cmdforge/web/templates/base.html
+++ b/src/cmdforge/web/templates/base.html
@@ -71,6 +71,23 @@
 
     <!-- Scripts -->
     <script src="{{ url_for('web.static', filename='js/main.js') }}" defer></script>
+
+    <!-- Mermaid.js for diagrams -->
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+    <script>
+        mermaid.initialize({
+            startOnLoad: true,
+            theme: 'base',
+            themeVariables: {
+                primaryColor: '#6366f1',
+                primaryTextColor: '#1f2937',
+                primaryBorderColor: '#4f46e5',
+                lineColor: '#6b7280',
+                secondaryColor: '#f3f4f6',
+                tertiaryColor: '#e0e7ff'
+            }
+        });
+    </script>
     {% block scripts %}{% endblock %}
 </body>
 </html>
diff --git a/src/cmdforge/web/templates/pages/philosophy.html b/src/cmdforge/web/templates/pages/philosophy.html
index 2767afb..55ccbb2 100644
--- a/src/cmdforge/web/templates/pages/philosophy.html
+++ b/src/cmdforge/web/templates/pages/philosophy.html
@@ -218,6 +218,46 @@
         </div>
     </div>
 
+    <!-- The System (Mermaid Diagram) -->
+    <div class="bg-gray-50 py-16">
+        <div class="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8">
+            <h2 class="text-3xl font-bold text-gray-900 text-center mb-8">The System</h2>
+            <p class="text-center text-gray-600 mb-8">
+                Ask for what you need. CmdForge finds it, composes it, or creates it.
+            </p>
+
+            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
+                <pre class="mermaid flex justify-center">
+flowchart TD
+    User["👤 Developer / System"]
+    AI["🤖 CmdForge AI Assistant"]
+
+    Registry["📦 Tool Registry"]
+    Tool1["🔧 Tool: Parse CSV"]
+    Tool2["🔧 Tool: Send Email"]
+    Tool3["🔧 Tool: Query API"]
+
+    NewTool["✨ Generated Tool"]
+
+    User --> AI
+    AI --> Registry
+
+    Registry --> Tool1
+    Registry --> Tool2
+    Registry --> Tool3
+
+    AI -->|Compose Tools| Execution["⚙️ Execution Pipeline"]
+
+    AI -->|If missing| NewTool
+    NewTool --> Registry
+
+    Execution --> Result["✅ Result"]
+    Result --> User
+                </pre>
+            </div>
+        </div>
+    </div>
+
     <!-- How It Works -->
     <div class="bg-slate-900 text-white py-16">
         <div class="max-w-5xl mx-auto px-4 sm:px-6 lg:px-8">
@@ -342,6 +382,67 @@
         </div>
     </div>
 
+    <!-- Tool Composition Diagram -->
+    <div class="py-16 bg-gray-50">
+        <div class="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8">
+            <h2 class="text-3xl font-bold text-gray-900 text-center mb-8">Composable By Design</h2>
+            <p class="text-center text-gray-600 mb-8">
+                Tools can call other tools. Complex systems emerge from simple parts.
+            </p>
+
+            <div class="bg-white rounded-xl p-6 shadow-sm border border-gray-200">
+                <pre class="mermaid flex justify-center">
+flowchart LR
+    A["Tool A"] --> B["Tool B"]
+    B --> C["Tool C"]
+    A --> D["Tool D"]
+
+    subgraph Composable System
+        A
+        B
+        C
+        D
+    end
+                </pre>
+            </div>
+        </div>
+    </div>
+
+    <!-- Future Vision: Distributed Tools -->
+    <div class="py-16 bg-slate-800 text-white">
+        <div class="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8">
+            <h2 class="text-3xl font-bold text-center mb-4">Future Vision</h2>
+            <p class="text-center text-slate-300 mb-8">
+                Tools shared across machines. Distributed capabilities for distributed systems.
+            </p>
+
+            <div class="bg-slate-700 rounded-xl p-6">
+                <pre class="mermaid flex justify-center">
+flowchart LR
+    Node1["🖥️ Node A"]
+    Node2["🖥️ Node B"]
+    Node3["🖥️ Node C"]
+
+    ToolA["🔧 Tools"]
+    ToolB["🔧 Tools"]
+    ToolC["🔧 Tools"]
+
+    Node1 --> ToolA
+    Node2 --> ToolB
+    Node3 --> ToolC
+
+    Node1 <-->|Call Tools| Node2
+    Node2 <-->|Call Tools| Node3
+    Node1 <-->|Call Tools| Node3
+                </pre>
+            </div>
+
+            <p class="text-center text-slate-400 mt-6 text-sm">
+                Coming soon: Expose tools over a port for distributed execution across your infrastructure.
+            </p>
+        </div>
+    </div>
+
     <!-- What CmdForge Is / Isn't -->
     <div class="py-16">
         <div class="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8">