diff --git a/docs/a2a-mock.html b/docs/a2a-mock/index.html
similarity index 99%
rename from docs/a2a-mock.html
rename to docs/a2a-mock/index.html
index 05c374b..f710a6c 100644
--- a/docs/a2a-mock.html
+++ b/docs/a2a-mock/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/aimock-cli.html b/docs/aimock-cli/index.html
similarity index 99%
rename from docs/aimock-cli.html
rename to docs/aimock-cli/index.html
index d562635..cc87f8c 100644
--- a/docs/aimock-cli.html
+++ b/docs/aimock-cli/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/aws-bedrock.html b/docs/aws-bedrock/index.html
similarity index 99%
rename from docs/aws-bedrock.html
rename to docs/aws-bedrock/index.html
index 17d57f7..b51f937 100644
--- a/docs/aws-bedrock.html
+++ b/docs/aws-bedrock/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/azure-openai.html b/docs/azure-openai/index.html
similarity index 99%
rename from docs/azure-openai.html
rename to docs/azure-openai/index.html
index 7181e55..36f41c8 100644
--- a/docs/azure-openai.html
+++ b/docs/azure-openai/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/chaos-testing.html b/docs/chaos-testing/index.html
similarity index 99%
rename from docs/chaos-testing.html
rename to docs/chaos-testing/index.html
index b15f984..bab37ad 100644
--- a/docs/chaos-testing.html
+++ b/docs/chaos-testing/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/chat-completions.html b/docs/chat-completions/index.html
similarity index 99%
rename from docs/chat-completions.html
rename to docs/chat-completions/index.html
index 53ad16f..efae496 100644
--- a/docs/chat-completions.html
+++ b/docs/chat-completions/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank">
               <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/claude-messages.html b/docs/claude-messages/index.html
similarity index 99%
rename from docs/claude-messages.html
rename to docs/claude-messages/index.html
index a728865..ef58aa3 100644
--- a/docs/claude-messages.html
+++ b/docs/claude-messages/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/cohere.html b/docs/cohere/index.html
similarity index 99%
rename from docs/cohere.html
rename to docs/cohere/index.html
index 2ca790f..e82835e 100644
--- a/docs/cohere.html
+++ b/docs/cohere/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/compatible-providers.html b/docs/compatible-providers/index.html
similarity index 97%
rename from docs/compatible-providers.html
rename to docs/compatible-providers/index.html
index 81d44b6..3f63077 100644
--- a/docs/compatible-providers.html
+++ b/docs/compatible-providers/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
@@ -95,14 +95,14 @@ <h2>Supported Providers</h2>
               <td>Cohere</td>
               <td><code>/v1/chat/completions</code></td>
               <td>
-                OpenAI-compatible endpoint; see <a href="cohere.html">Cohere page</a> for native
+                OpenAI-compatible endpoint; see <a href="/cohere">Cohere page</a> for native
                 endpoints
               </td>
             </tr>
             <tr>
               <td>Vertex AI</td>
               <td><code>/v1/projects/.../models/:model:*</code></td>
-              <td>Uses Gemini handler; see <a href="vertex-ai.html">Vertex AI page</a></td>
+              <td>Uses Gemini handler; see <a href="/vertex-ai">Vertex AI page</a></td>
             </tr>
           </tbody>
         </table>
@@ -275,7 +275,7 @@ <h2>Example Fixture</h2>
             <strong>Ollama native endpoints:</strong> In addition to the OpenAI-compatible endpoint
             listed above, Ollama has its own native <code>/api/chat</code> and
             <code>/api/generate</code> endpoints. aimock supports these natively &mdash; see the
-            <a href="ollama.html">Ollama page</a> for details on the native endpoint format.
+            <a href="/ollama">Ollama page</a> for details on the native endpoint format.
           </p>
         </div>
       </main>
diff --git a/docs/docker.html b/docs/docker/index.html
similarity index 99%
rename from docs/docker.html
rename to docs/docker/index.html
index 09d7b76..ee2c452 100644
--- a/docs/docker.html
+++ b/docs/docker/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/docs.html b/docs/docs/index.html
similarity index 85%
rename from docs/docs.html
rename to docs/docs/index.html
index 55e4e90..eaae094 100644
--- a/docs/docs.html
+++ b/docs/docs/index.html
@@ -248,7 +248,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank">
               <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
@@ -266,22 +266,22 @@
     <!-- ═══ Section Bar ══════════════════════════════════════════════ -->
     <div class="section-bar">
       <div class="section-bar-inner">
-        <a href="chat-completions.html" class="section-pill pill-green">
+        <a href="/chat-completions" class="section-pill pill-green">
           <span class="section-pill-icon">&#128225;</span> LLM Mocking
         </a>
-        <a href="mcp-mock.html" class="section-pill pill-blue">
+        <a href="/mcp-mock" class="section-pill pill-blue">
           <span class="section-pill-icon">&#128268;</span> MCP Protocol
         </a>
-        <a href="a2a-mock.html" class="section-pill pill-purple">
+        <a href="/a2a-mock" class="section-pill pill-purple">
           <span class="section-pill-icon">&#129309;</span> A2A Protocol
         </a>
-        <a href="vector-mock.html" class="section-pill pill-amber">
+        <a href="/vector-mock" class="section-pill pill-amber">
           <span class="section-pill-icon">&#128230;</span> Vector DBs
         </a>
-        <a href="services.html" class="section-pill pill-red">
+        <a href="/services" class="section-pill pill-red">
           <span class="section-pill-icon">&#128269;</span> Search &amp; Rerank
         </a>
-        <a href="chaos-testing.html" class="section-pill pill-gray">
+        <a href="/chaos-testing" class="section-pill pill-gray">
           <span class="section-pill-icon">&#9881;</span> Chaos &amp; DevOps
         </a>
       </div>
@@ -311,15 +311,13 @@ <h2>The Suite</h2>
             </div>
             <p class="suite-card-desc">Mock 10+ LLM providers with fixture-driven responses</p>
             <ul class="suite-card-links">
-              <li><a href="chat-completions.html">Chat Completions</a></li>
-              <li><a href="claude-messages.html">Claude Messages</a></li>
-              <li><a href="gemini.html">Gemini</a></li>
-              <li><a href="aws-bedrock.html">Bedrock</a></li>
-              <li><a href="record-replay.html">Record &amp; Replay</a></li>
+              <li><a href="/chat-completions">Chat Completions</a></li>
+              <li><a href="/claude-messages">Claude Messages</a></li>
+              <li><a href="/gemini">Gemini</a></li>
+              <li><a href="/aws-bedrock">Bedrock</a></li>
+              <li><a href="/record-replay">Record &amp; Replay</a></li>
             </ul>
-            <a href="chat-completions.html" class="suite-card-cta"
-              >Get started <span>&rarr;</span></a
-            >
+            <a href="/chat-completions" class="suite-card-cta">Get started <span>&rarr;</span></a>
           </div>
 
           <!-- MCP Protocol -->
@@ -330,12 +328,12 @@ <h2>The Suite</h2>
             </div>
             <p class="suite-card-desc">Mock MCP servers with tools, resources, and prompts</p>
             <ul class="suite-card-links">
-              <li><a href="mcp-mock.html">Tool handlers</a></li>
-              <li><a href="mcp-mock.html">Resources</a></li>
-              <li><a href="mcp-mock.html">Prompts</a></li>
-              <li><a href="mcp-mock.html">Session management</a></li>
+              <li><a href="/mcp-mock">Tool handlers</a></li>
+              <li><a href="/mcp-mock">Resources</a></li>
+              <li><a href="/mcp-mock">Prompts</a></li>
+              <li><a href="/mcp-mock">Session management</a></li>
             </ul>
-            <a href="mcp-mock.html" class="suite-card-cta">Get started <span>&rarr;</span></a>
+            <a href="/mcp-mock" class="suite-card-cta">Get started <span>&rarr;</span></a>
           </div>
 
           <!-- A2A Protocol -->
@@ -346,11 +344,11 @@ <h2>The Suite</h2>
             </div>
             <p class="suite-card-desc">Mock agent-to-agent interactions with streaming</p>
             <ul class="suite-card-links">
-              <li><a href="a2a-mock.html">Agent cards</a></li>
-              <li><a href="a2a-mock.html">Message routing</a></li>
-              <li><a href="a2a-mock.html">Task streaming</a></li>
+              <li><a href="/a2a-mock">Agent cards</a></li>
+              <li><a href="/a2a-mock">Message routing</a></li>
+              <li><a href="/a2a-mock">Task streaming</a></li>
             </ul>
-            <a href="a2a-mock.html" class="suite-card-cta">Get started <span>&rarr;</span></a>
+            <a href="/a2a-mock" class="suite-card-cta">Get started <span>&rarr;</span></a>
           </div>
 
           <!-- Vector Databases -->
@@ -361,11 +359,11 @@ <h2>The Suite</h2>
             </div>
             <p class="suite-card-desc">Mock Pinecone, Qdrant, and ChromaDB endpoints</p>
             <ul class="suite-card-links">
-              <li><a href="vector-mock.html">Upsert &amp; query</a></li>
-              <li><a href="vector-mock.html">Collections</a></li>
-              <li><a href="vector-mock.html">Custom handlers</a></li>
+              <li><a href="/vector-mock">Upsert &amp; query</a></li>
+              <li><a href="/vector-mock">Collections</a></li>
+              <li><a href="/vector-mock">Custom handlers</a></li>
             </ul>
-            <a href="vector-mock.html" class="suite-card-cta">Get started <span>&rarr;</span></a>
+            <a href="/vector-mock" class="suite-card-cta">Get started <span>&rarr;</span></a>
           </div>
 
           <!-- Services -->
@@ -376,11 +374,11 @@ <h2>The Suite</h2>
             </div>
             <p class="suite-card-desc">Search, rerank, and moderation API mocks</p>
             <ul class="suite-card-links">
-              <li><a href="services.html">Tavily search</a></li>
-              <li><a href="services.html">Cohere rerank</a></li>
-              <li><a href="services.html">OpenAI moderation</a></li>
+              <li><a href="/services">Tavily search</a></li>
+              <li><a href="/services">Cohere rerank</a></li>
+              <li><a href="/services">OpenAI moderation</a></li>
             </ul>
-            <a href="services.html" class="suite-card-cta">Get started <span>&rarr;</span></a>
+            <a href="/services" class="suite-card-cta">Get started <span>&rarr;</span></a>
           </div>
 
           <!-- Testing & Operations -->
@@ -391,12 +389,12 @@ <h2>The Suite</h2>
             </div>
             <p class="suite-card-desc">Chaos testing, metrics, drift detection, Docker</p>
             <ul class="suite-card-links">
-              <li><a href="chaos-testing.html">Chaos testing</a></li>
-              <li><a href="metrics.html">Prometheus</a></li>
-              <li><a href="drift-detection.html">Drift detection</a></li>
-              <li><a href="docker.html">Docker &amp; Helm</a></li>
+              <li><a href="/chaos-testing">Chaos testing</a></li>
+              <li><a href="/metrics">Prometheus</a></li>
+              <li><a href="/drift-detection">Drift detection</a></li>
+              <li><a href="/docker">Docker &amp; Helm</a></li>
             </ul>
-            <a href="chaos-testing.html" class="suite-card-cta">Get started <span>&rarr;</span></a>
+            <a href="/chaos-testing" class="suite-card-cta">Get started <span>&rarr;</span></a>
           </div>
         </div>
 
@@ -418,7 +416,7 @@ <h3>I want to mock LLM APIs</h3>
 
 <span class="op">mock</span>.<span class="fn">onMessage</span>(<span class="str">"hello"</span>, { <span class="prop">content</span>: <span class="str">"Hi there!"</span> });</code></pre>
             </div>
-            <p><a href="docs.html">Quick Start: LLM &rarr;</a></p>
+            <p><a href="/docs">Quick Start: LLM &rarr;</a></p>
           </div>
 
           <!-- Path 2: Full suite -->
@@ -436,7 +434,7 @@ <h3>I want to mock my entire AI stack</h3>
   <span class="key">"vector"</span>: { <span class="key">"provider"</span>: <span class="str">"pinecone"</span> }
 }</code></pre>
             </div>
-            <p><a href="aimock-cli.html">Quick Start: aimock suite &rarr;</a></p>
+            <p><a href="/aimock-cli">Quick Start: aimock suite &rarr;</a></p>
           </div>
         </div>
       </main>
diff --git a/docs/drift-detection.html b/docs/drift-detection/index.html
similarity index 99%
rename from docs/drift-detection.html
rename to docs/drift-detection/index.html
index a6636ae..78908bc 100644
--- a/docs/drift-detection.html
+++ b/docs/drift-detection/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/embeddings.html b/docs/embeddings/index.html
similarity index 99%
rename from docs/embeddings.html
rename to docs/embeddings/index.html
index 80379ba..e43627a 100644
--- a/docs/embeddings.html
+++ b/docs/embeddings/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/error-injection.html b/docs/error-injection/index.html
similarity index 98%
rename from docs/error-injection.html
rename to docs/error-injection/index.html
index 9073023..39afa3b 100644
--- a/docs/error-injection.html
+++ b/docs/error-injection/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
@@ -179,7 +179,7 @@ <h2>Interruption Behavior</h2>
 
         <div class="info-box">
           <p>
-            <strong>See also: <a href="chaos-testing.html">Chaos Testing</a></strong> &mdash; for
+            <strong>See also: <a href="/chaos-testing">Chaos Testing</a></strong> &mdash; for
             probabilistic failure injection. Chaos testing adds configurable error rates, random
             latency spikes, and stream corruption that trigger based on probability rather than
             deterministic fixture matching. Use error injection for specific, reproducible failure
diff --git a/docs/fixtures.html b/docs/fixtures/index.html
similarity index 98%
rename from docs/fixtures.html
rename to docs/fixtures/index.html
index 647970e..e9088d1 100644
--- a/docs/fixtures.html
+++ b/docs/fixtures/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
@@ -203,7 +203,7 @@ <h2>Fixture Options</h2>
               <td>object</td>
               <td>
                 Streaming physics profile: <code>{ ttftMs, tps, jitter }</code>. See
-                <a href="streaming-physics.html">Streaming Physics</a>
+                <a href="/streaming-physics">Streaming Physics</a>
               </td>
             </tr>
             <tr>
@@ -211,7 +211,7 @@ <h2>Fixture Options</h2>
               <td>object</td>
               <td>
                 Per-fixture chaos config: <code>{ errorRate, latencyMs, ... }</code>. See
-                <a href="chaos-testing.html">Chaos Testing</a>
+                <a href="/chaos-testing">Chaos Testing</a>
               </td>
             </tr>
           </tbody>
diff --git a/docs/gemini.html b/docs/gemini/index.html
similarity index 97%
rename from docs/gemini.html
rename to docs/gemini/index.html
index f1b5efe..e0811b2 100644
--- a/docs/gemini.html
+++ b/docs/gemini/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
@@ -154,8 +154,7 @@ <h2>Request Translation</h2>
         <h2>Gemini Live (WebSocket)</h2>
         <p>
           Gemini Live uses WebSocket at <code>/ws/google.ai.generativelanguage.*</code> for
-          bidirectional streaming. See the <a href="websocket.html">WebSocket APIs</a> page for
-          details.
+          bidirectional streaming. See the <a href="/websocket">WebSocket APIs</a> page for details.
         </p>
 
         <div class="info-box">
@@ -183,7 +182,7 @@ <h2>Vertex AI</h2>
         </div>
         <p>
           The same fixtures work for both Gemini AI Studio and Vertex AI endpoints. See the
-          <a href="vertex-ai.html">Vertex AI</a> page for configuration details.
+          <a href="/vertex-ai">Vertex AI</a> page for configuration details.
         </p>
       </main>
     </div>
diff --git a/docs/index.html b/docs/index.html
index e4fc411..4531500 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1068,7 +1068,7 @@
           <li><a href="#features" class="nav-hide-mobile">Features</a></li>
           <li><a href="#comparison" class="nav-hide-mobile">Comparison</a></li>
           <li><a href="#switch" class="nav-hide-mobile">Switch</a></li>
-          <li><a href="docs.html">Docs</a></li>
+          <li><a href="/docs">Docs</a></li>
           <li>
             <a
               href="https://github.com/CopilotKit/aimock"
@@ -1197,9 +1197,7 @@ <h3>Replay</h3>
               </div>
             </div>
 
-            <a href="record-replay.html" class="btn-primary"
-              >Learn about Record &amp; Replay &rarr;</a
-            >
+            <a href="/record-replay" class="btn-primary">Learn about Record &amp; Replay &rarr;</a>
           </div>
 
           <div class="fade-in" style="transition-delay: 0.15s">
@@ -1236,31 +1234,31 @@ <h2 class="fade-in">
         </h2>
 
         <div class="service-strip fade-in" style="transition-delay: 0.1s">
-          <a href="mcp-mock.html" class="service-card-link">
+          <a href="/mcp-mock" class="service-card-link">
             <div class="service-card blue">
               <span class="service-icon">&#128268;</span>
               <span class="service-label">MCP Tools</span>
             </div>
           </a>
-          <a href="a2a-mock.html" class="service-card-link">
+          <a href="/a2a-mock" class="service-card-link">
             <div class="service-card purple">
               <span class="service-icon">&#129309;</span>
               <span class="service-label">A2A Agents</span>
             </div>
           </a>
-          <a href="vector-mock.html" class="service-card-link">
+          <a href="/vector-mock" class="service-card-link">
             <div class="service-card amber">
               <span class="service-icon">&#128230;</span>
               <span class="service-label">Vector DBs</span>
             </div>
           </a>
-          <a href="services.html" class="service-card-link">
+          <a href="/services" class="service-card-link">
             <div class="service-card red">
               <span class="service-icon">&#128269;</span>
               <span class="service-label">Search &amp; Rerank</span>
             </div>
           </a>
-          <a href="services.html#moderation" class="service-card-link">
+          <a href="/services#moderation" class="service-card-link">
             <div class="service-card gray">
               <span class="service-icon">&#128737;</span>
               <span class="service-label">Moderation</span>
@@ -1423,7 +1421,7 @@ <h3>Fix &amp; ship</h3>
         </div>
 
         <div class="reliability-cta fade-in" style="transition-delay: 0.3s">
-          <a href="drift-detection.html" class="btn-primary">Learn about drift detection &rarr;</a>
+          <a href="/drift-detection" class="btn-primary">Learn about drift detection &rarr;</a>
         </div>
       </div>
     </section>
@@ -1666,7 +1664,7 @@ <h2 class="fade-in">Ready to switch? We got you.</h2>
           class="fade-in"
           style="display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap"
         >
-          <a href="migrate-from-msw.html" class="btn btn-secondary"
+          <a href="/migrate-from-msw" class="btn btn-secondary"
             ><img
               src="https://mswjs.io/icon.svg"
               alt=""
@@ -1675,10 +1673,10 @@ <h2 class="fade-in">Ready to switch? We got you.</h2>
               style="vertical-align: -2px; margin-right: 6px; filter: grayscale(1) brightness(2)"
             />MSW</a
           >
-          <a href="migrate-from-vidaimock.html" class="btn btn-secondary">VidaiMock</a>
-          <a href="migrate-from-mock-llm.html" class="btn btn-secondary">mock-llm</a>
-          <a href="migrate-from-piyook.html" class="btn btn-secondary">piyook</a>
-          <a href="migrate-from-python-mocks.html" class="btn btn-secondary"
+          <a href="/migrate-from-vidaimock" class="btn btn-secondary">VidaiMock</a>
+          <a href="/migrate-from-mock-llm" class="btn btn-secondary">mock-llm</a>
+          <a href="/migrate-from-piyook" class="btn btn-secondary">piyook</a>
+          <a href="/migrate-from-python-mocks" class="btn btn-secondary"
             ><img
               src="https://www.python.org/static/favicon.ico"
               alt=""
@@ -1687,7 +1685,7 @@ <h2 class="fade-in">Ready to switch? We got you.</h2>
               style="vertical-align: -2px; margin-right: 6px"
             />Python</a
           >
-          <a href="migrate-from-mokksy.html" class="btn btn-secondary">Mokksy</a>
+          <a href="/migrate-from-mokksy" class="btn btn-secondary">Mokksy</a>
         </div>
       </div>
     </section>
@@ -1722,7 +1720,7 @@ <h2 class="fade-in">Built for production</h2>
       <div class="container">
         <div class="footer-brand"><span class="prompt">$</span> aimock &middot; MIT License</div>
         <ul class="footer-links">
-          <li><a href="docs.html">Docs</a></li>
+          <li><a href="/docs">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" target="_blank" rel="noopener">GitHub</a>
           </li>
diff --git a/docs/mcp-mock.html b/docs/mcp-mock/index.html
similarity index 99%
rename from docs/mcp-mock.html
rename to docs/mcp-mock/index.html
index 15c5e50..96942bc 100644
--- a/docs/mcp-mock.html
+++ b/docs/mcp-mock/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/metrics.html b/docs/metrics/index.html
similarity index 99%
rename from docs/metrics.html
rename to docs/metrics/index.html
index ae51423..d5e16c0 100644
--- a/docs/metrics.html
+++ b/docs/metrics/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/migrate-from-mock-llm.html b/docs/migrate-from-mock-llm/index.html
similarity index 99%
rename from docs/migrate-from-mock-llm.html
rename to docs/migrate-from-mock-llm/index.html
index fd58940..743bfc2 100644
--- a/docs/migrate-from-mock-llm.html
+++ b/docs/migrate-from-mock-llm/index.html
@@ -123,7 +123,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank">
               <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
@@ -469,7 +469,7 @@ <h2>Kubernetes migration</h2>
           <p>
             If you were using mock-llm's ConfigMap for inline responses, convert each response to a
             fixture JSON file and load them via a PVC. See the
-            <a href="fixtures.html">Fixtures</a> documentation for the full schema.
+            <a href="/fixtures">Fixtures</a> documentation for the full schema.
           </p>
         </div>
 
diff --git a/docs/migrate-from-mokksy.html b/docs/migrate-from-mokksy/index.html
similarity index 99%
rename from docs/migrate-from-mokksy.html
rename to docs/migrate-from-mokksy/index.html
index 1a62258..05d4439 100644
--- a/docs/migrate-from-mokksy.html
+++ b/docs/migrate-from-mokksy/index.html
@@ -108,7 +108,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank">
               <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/migrate-from-msw.html b/docs/migrate-from-msw/index.html
similarity index 99%
rename from docs/migrate-from-msw.html
rename to docs/migrate-from-msw/index.html
index d61ecb2..f02fd3c 100644
--- a/docs/migrate-from-msw.html
+++ b/docs/migrate-from-msw/index.html
@@ -124,7 +124,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank">
               <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/migrate-from-piyook.html b/docs/migrate-from-piyook/index.html
similarity index 99%
rename from docs/migrate-from-piyook.html
rename to docs/migrate-from-piyook/index.html
index aaffc5b..9dd293c 100644
--- a/docs/migrate-from-piyook.html
+++ b/docs/migrate-from-piyook/index.html
@@ -123,7 +123,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank">
               <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/migrate-from-python-mocks.html b/docs/migrate-from-python-mocks/index.html
similarity index 99%
rename from docs/migrate-from-python-mocks.html
rename to docs/migrate-from-python-mocks/index.html
index ca93cda..70a62d6 100644
--- a/docs/migrate-from-python-mocks.html
+++ b/docs/migrate-from-python-mocks/index.html
@@ -124,7 +124,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank">
               <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/migrate-from-vidaimock.html b/docs/migrate-from-vidaimock/index.html
similarity index 99%
rename from docs/migrate-from-vidaimock.html
rename to docs/migrate-from-vidaimock/index.html
index b5f201f..421fe06 100644
--- a/docs/migrate-from-vidaimock.html
+++ b/docs/migrate-from-vidaimock/index.html
@@ -32,7 +32,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/mount.html b/docs/mount/index.html
similarity index 95%
rename from docs/mount.html
rename to docs/mount/index.html
index a069912..85d3ccc 100644
--- a/docs/mount.html
+++ b/docs/mount/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
@@ -227,21 +227,21 @@ <h2>Built-in Services</h2>
         </p>
         <ul>
           <li>
-            <a href="mcp-mock.html"><strong>MCPMock</strong></a> &mdash; Mock MCP tool server with
+            <a href="/mcp-mock"><strong>MCPMock</strong></a> &mdash; Mock MCP tool server with
             JSON-RPC dispatch, session management, and tool/resource/prompt support
           </li>
           <li>
-            <a href="a2a-mock.html"><strong>A2AMock</strong></a> &mdash; Mock A2A agent-to-agent
+            <a href="/a2a-mock"><strong>A2AMock</strong></a> &mdash; Mock A2A agent-to-agent
             protocol server with agent cards, message routing, and streaming
           </li>
           <li>
-            <a href="vector-mock.html"><strong>VectorMock</strong></a> &mdash; Mock vector database
-            with Pinecone, Qdrant, and ChromaDB endpoints
+            <a href="/vector-mock"><strong>VectorMock</strong></a> &mdash; Mock vector database with
+            Pinecone, Qdrant, and ChromaDB endpoints
           </li>
         </ul>
         <p>
           All implement the <code>Mountable</code> interface and work with <code>mount()</code>,
-          <code>createMockSuite()</code>, and the <a href="aimock-cli.html">aimock CLI</a>.
+          <code>createMockSuite()</code>, and the <a href="/aimock-cli">aimock CLI</a>.
         </p>
       </main>
     </div>
diff --git a/docs/ollama.html b/docs/ollama/index.html
similarity index 99%
rename from docs/ollama.html
rename to docs/ollama/index.html
index c054ba3..f6999f0 100644
--- a/docs/ollama.html
+++ b/docs/ollama/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/record-replay.html b/docs/record-replay/index.html
similarity index 99%
rename from docs/record-replay.html
rename to docs/record-replay/index.html
index 29c4a83..2fe22c2 100644
--- a/docs/record-replay.html
+++ b/docs/record-replay/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/responses-api.html b/docs/responses-api/index.html
similarity index 98%
rename from docs/responses-api.html
rename to docs/responses-api/index.html
index a005ee8..f3e518b 100644
--- a/docs/responses-api.html
+++ b/docs/responses-api/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
@@ -158,7 +158,7 @@ <h2>SSE Event Sequence</h2>
         <div class="info-box">
           <p>
             The same fixtures work for both HTTP SSE and WebSocket transports. See the
-            <a href="websocket.html">WebSocket APIs</a> page for WebSocket-specific details.
+            <a href="/websocket">WebSocket APIs</a> page for WebSocket-specific details.
           </p>
         </div>
       </main>
diff --git a/docs/sequential-responses.html b/docs/sequential-responses/index.html
similarity index 99%
rename from docs/sequential-responses.html
rename to docs/sequential-responses/index.html
index 517180b..bbb8b9c 100644
--- a/docs/sequential-responses.html
+++ b/docs/sequential-responses/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/services.html b/docs/services/index.html
similarity index 99%
rename from docs/services.html
rename to docs/services/index.html
index 1d9e3e2..4f69628 100644
--- a/docs/services.html
+++ b/docs/services/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/sidebar.js b/docs/sidebar.js
index 2af1d7d..33a2287 100644
--- a/docs/sidebar.js
+++ b/docs/sidebar.js
@@ -5,90 +5,94 @@
     {
       title: "Getting Started",
       links: [
-        { label: "Overview", href: "docs.html" },
-        { label: "Record & Replay", href: "record-replay.html" },
-        { label: "Quick Start: LLM", href: "chat-completions.html" },
-        { label: "Quick Start: aimock", href: "aimock-cli.html" },
+        { label: "Overview", href: "/docs" },
+        { label: "Record & Replay", href: "/record-replay" },
+        { label: "Quick Start: LLM", href: "/chat-completions" },
+        { label: "Quick Start: aimock", href: "/aimock-cli" },
       ],
     },
     {
       title: "LLM Providers",
       links: [
-        { label: "Chat Completions (OpenAI)", href: "chat-completions.html" },
-        { label: "Responses API (OpenAI)", href: "responses-api.html" },
-        { label: "Claude Messages", href: "claude-messages.html" },
-        { label: "Gemini", href: "gemini.html" },
-        { label: "Azure OpenAI", href: "azure-openai.html" },
-        { label: "AWS Bedrock", href: "aws-bedrock.html" },
-        { label: "Ollama", href: "ollama.html" },
-        { label: "Cohere", href: "cohere.html" },
-        { label: "Vertex AI", href: "vertex-ai.html" },
-        { label: "Compatible Providers", href: "compatible-providers.html" },
+        { label: "Chat Completions (OpenAI)", href: "/chat-completions" },
+        { label: "Responses API (OpenAI)", href: "/responses-api" },
+        { label: "Claude Messages", href: "/claude-messages" },
+        { label: "Gemini", href: "/gemini" },
+        { label: "Azure OpenAI", href: "/azure-openai" },
+        { label: "AWS Bedrock", href: "/aws-bedrock" },
+        { label: "Ollama", href: "/ollama" },
+        { label: "Cohere", href: "/cohere" },
+        { label: "Vertex AI", href: "/vertex-ai" },
+        { label: "Compatible Providers", href: "/compatible-providers" },
       ],
     },
     {
       title: "LLM Features",
       links: [
-        { label: "Embeddings", href: "embeddings.html" },
-        { label: "Structured Output", href: "structured-output.html" },
-        { label: "Sequential Responses", href: "sequential-responses.html" },
-        { label: "Fixtures", href: "fixtures.html" },
-        { label: "Error Injection", href: "error-injection.html" },
-        { label: "Chaos Testing", href: "chaos-testing.html" },
-        { label: "Streaming Physics", href: "streaming-physics.html" },
-        { label: "WebSocket APIs", href: "websocket.html" },
-        { label: "Prometheus Metrics", href: "metrics.html" },
-        { label: "Mount & Composition", href: "mount.html" },
+        { label: "Embeddings", href: "/embeddings" },
+        { label: "Structured Output", href: "/structured-output" },
+        { label: "Sequential Responses", href: "/sequential-responses" },
+        { label: "Fixtures", href: "/fixtures" },
+        { label: "Error Injection", href: "/error-injection" },
+        { label: "Chaos Testing", href: "/chaos-testing" },
+        { label: "Streaming Physics", href: "/streaming-physics" },
+        { label: "WebSocket APIs", href: "/websocket" },
+        { label: "Prometheus Metrics", href: "/metrics" },
+        { label: "Mount & Composition", href: "/mount" },
       ],
     },
     {
       title: "Additional Mocks",
       links: [
-        { label: "MCPMock", href: "mcp-mock.html" },
-        { label: "A2AMock", href: "a2a-mock.html" },
-        { label: "VectorMock", href: "vector-mock.html" },
-        { label: "Services", href: "services.html" },
+        { label: "MCPMock", href: "/mcp-mock" },
+        { label: "A2AMock", href: "/a2a-mock" },
+        { label: "VectorMock", href: "/vector-mock" },
+        { label: "Services", href: "/services" },
       ],
     },
     {
       title: "Orchestration",
       links: [
-        { label: "aimock CLI & Config", href: "aimock-cli.html" },
-        { label: "Docker & Helm", href: "docker.html" },
-        { label: "Drift Detection", href: "drift-detection.html" },
+        { label: "aimock CLI & Config", href: "/aimock-cli" },
+        { label: "Docker & Helm", href: "/docker" },
+        { label: "Drift Detection", href: "/drift-detection" },
       ],
     },
     {
       title: "Switching to aimock",
       links: [
-        { label: "From MSW", href: "migrate-from-msw.html" },
-        { label: "From VidaiMock", href: "migrate-from-vidaimock.html" },
-        { label: "From mock-llm", href: "migrate-from-mock-llm.html" },
-        { label: "From piyook/llm-mock", href: "migrate-from-piyook.html" },
-        { label: "From Python Mocks", href: "migrate-from-python-mocks.html" },
-        { label: "From Mokksy", href: "migrate-from-mokksy.html" },
+        { label: "From MSW", href: "/migrate-from-msw" },
+        { label: "From VidaiMock", href: "/migrate-from-vidaimock" },
+        { label: "From mock-llm", href: "/migrate-from-mock-llm" },
+        { label: "From piyook/llm-mock", href: "/migrate-from-piyook" },
+        { label: "From Python Mocks", href: "/migrate-from-python-mocks" },
+        { label: "From Mokksy", href: "/migrate-from-mokksy" },
       ],
     },
   ];
 
   // ─── Section Bar Items ──────────────────────────────────────────
   var sectionBarItems = [
-    { icon: "&#128225;", label: "LLM Mocking", color: "pill-green", href: "chat-completions.html" },
-    { icon: "&#128268;", label: "MCP Protocol", color: "pill-blue", href: "mcp-mock.html" },
-    { icon: "&#129309;", label: "A2A Protocol", color: "pill-purple", href: "a2a-mock.html" },
-    { icon: "&#128230;", label: "Vector DBs", color: "pill-amber", href: "vector-mock.html" },
-    { icon: "&#128269;", label: "Search &amp; Rerank", color: "pill-red", href: "services.html" },
+    { icon: "&#128225;", label: "LLM Mocking", color: "pill-green", href: "/chat-completions" },
+    { icon: "&#128268;", label: "MCP Protocol", color: "pill-blue", href: "/mcp-mock" },
+    { icon: "&#129309;", label: "A2A Protocol", color: "pill-purple", href: "/a2a-mock" },
+    { icon: "&#128230;", label: "Vector DBs", color: "pill-amber", href: "/vector-mock" },
+    { icon: "&#128269;", label: "Search &amp; Rerank", color: "pill-red", href: "/services" },
     {
       icon: "&#9881;",
       label: "Chaos &amp; DevOps",
       color: "pill-gray",
-      href: "chaos-testing.html",
+      href: "/chaos-testing",
     },
   ];
 
   // ─── Detect current page ────────────────────────────────────────
-  var currentPage = window.location.pathname.split("/").pop() || "index.html";
-  if (currentPage === "" || currentPage === "/") currentPage = "index.html";
+  var pathParts = window.location.pathname
+    .replace(/\/index\.html$/, "/")
+    .replace(/\/$/, "")
+    .split("/");
+  var currentPage = "/" + (pathParts[pathParts.length - 1] || "");
+  if (currentPage === "/") currentPage = "index.html";
 
   // ─── Build Sidebar HTML ─────────────────────────────────────────
   function buildSidebar() {
diff --git a/docs/streaming-physics.html b/docs/streaming-physics/index.html
similarity index 99%
rename from docs/streaming-physics.html
rename to docs/streaming-physics/index.html
index d39ec56..2793f5c 100644
--- a/docs/streaming-physics.html
+++ b/docs/streaming-physics/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/structured-output.html b/docs/structured-output/index.html
similarity index 99%
rename from docs/structured-output.html
rename to docs/structured-output/index.html
index 35e89bb..e4307ee 100644
--- a/docs/structured-output.html
+++ b/docs/structured-output/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/vector-mock.html b/docs/vector-mock/index.html
similarity index 99%
rename from docs/vector-mock.html
rename to docs/vector-mock/index.html
index cdbfe3e..c529e83 100644
--- a/docs/vector-mock.html
+++ b/docs/vector-mock/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/docs/vertex-ai.html b/docs/vertex-ai/index.html
similarity index 97%
rename from docs/vertex-ai.html
rename to docs/vertex-ai/index.html
index 5e13e0e..f6bcc68 100644
--- a/docs/vertex-ai.html
+++ b/docs/vertex-ai/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
@@ -133,8 +133,8 @@ <h2>Same Wire Format as Gemini</h2>
           Vertex AI uses the exact same request and response wire format as the consumer Gemini API.
           The request body uses <code>contents</code> with <code>parts</code>, and responses use
           <code>candidates</code> with <code>content.parts</code>. See the
-          <a href="gemini.html">Gemini documentation</a> for full details on the wire format,
-          streaming events, and fixture examples.
+          <a href="/gemini">Gemini documentation</a> for full details on the wire format, streaming
+          events, and fixture examples.
         </p>
         <p>
           Internally, both consumer Gemini and Vertex AI routes are handled by the same
diff --git a/docs/websocket.html b/docs/websocket/index.html
similarity index 99%
rename from docs/websocket.html
rename to docs/websocket/index.html
index 0d9c074..81131b3 100644
--- a/docs/websocket.html
+++ b/docs/websocket/index.html
@@ -28,7 +28,7 @@
         </div>
         <ul class="nav-links">
           <li><a href="/">Home</a></li>
-          <li><a href="docs.html" style="color: var(--accent)">Docs</a></li>
+          <li><a href="/docs" style="color: var(--accent)">Docs</a></li>
           <li>
             <a href="https://github.com/CopilotKit/aimock" class="gh-link" target="_blank"
               ><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
diff --git a/src/__tests__/docs-clean-urls.test.ts b/src/__tests__/docs-clean-urls.test.ts
new file mode 100644
index 0000000..1010064
--- /dev/null
+++ b/src/__tests__/docs-clean-urls.test.ts
@@ -0,0 +1,166 @@
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const DOCS_DIR = path.resolve(import.meta.dirname, "../../docs");
+
+/** Recursively collect all HTML files under a directory. */
+function collectHtmlFiles(dir: string): string[] {
+  const results: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectHtmlFiles(full));
+    } else if (entry.name.endsWith(".html")) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/** Extract all href values from an HTML string (excludes external links and anchors). */
+function extractInternalHrefs(html: string): string[] {
+  const hrefRegex = /href="([^"]+)"/g;
+  const hrefs: string[] = [];
+  let match;
+  while ((match = hrefRegex.exec(html)) !== null) {
+    const href = match[1];
+    // Skip external links, anchors, and protocol-relative URLs
+    if (href.startsWith("http") || href.startsWith("#") || href.startsWith("//")) continue;
+    hrefs.push(href);
+  }
+  return hrefs;
+}
+
+const allHtmlFiles = collectHtmlFiles(DOCS_DIR);
+const SKIP_FILES = ["index.html", "og-image.html"];
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("docs clean URLs", () => {
+  it("docs directory exists and contains HTML files", () => {
+    expect(fs.existsSync(DOCS_DIR)).toBe(true);
+    expect(allHtmlFiles.length).toBeGreaterThan(0);
+  });
+
+  describe("file structure", () => {
+    it("only index.html and og-image.html exist at root level", () => {
+      const rootHtmlFiles = fs
+        .readdirSync(DOCS_DIR, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith(".html"))
+        .map((e) => e.name);
+
+      for (const file of rootHtmlFiles) {
+        expect(SKIP_FILES).toContain(file);
+      }
+    });
+
+    it("each doc page lives in its own directory as index.html", () => {
+      // Non-page directories (specs, assets, etc.) are excluded
+      const NON_PAGE_DIRS = new Set(["superpowers"]);
+      const subdirs = fs
+        .readdirSync(DOCS_DIR, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !NON_PAGE_DIRS.has(e.name));
+
+      expect(subdirs.length).toBeGreaterThan(0);
+
+      for (const dir of subdirs) {
+        const indexPath = path.join(DOCS_DIR, dir.name, "index.html");
+        expect(fs.existsSync(indexPath), `${dir.name}/index.html should exist`).toBe(true);
+      }
+    });
+
+    it("no stale .html files remain at the docs root (besides allowed ones)", () => {
+      const rootHtmlFiles = fs
+        .readdirSync(DOCS_DIR, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith(".html"))
+        .map((e) => e.name);
+
+      const unexpected = rootHtmlFiles.filter((f) => !SKIP_FILES.includes(f));
+      expect(unexpected, `Unexpected root-level HTML files: ${unexpected.join(", ")}`).toEqual([]);
+    });
+  });
+
+  describe("internal links have no .html extension", () => {
+    for (const filePath of allHtmlFiles) {
+      const relative = path.relative(DOCS_DIR, filePath);
+
+      it(`${relative} — no .html in internal hrefs`, () => {
+        const html = fs.readFileSync(filePath, "utf-8");
+        const hrefs = extractInternalHrefs(html);
+
+        const badHrefs = hrefs.filter((h) => /\.html/.test(h));
+        expect(badHrefs, `Found .html hrefs in ${relative}: ${badHrefs.join(", ")}`).toEqual([]);
+      });
+    }
+  });
+
+  describe("sidebar.js links have no .html extension", () => {
+    it("no .html in sidebar href values", () => {
+      const sidebarPath = path.join(DOCS_DIR, "sidebar.js");
+      const content = fs.readFileSync(sidebarPath, "utf-8");
+
+      // Extract all href: "..." values
+      const hrefRegex = /href:\s*"([^"]+)"/g;
+      const hrefs: string[] = [];
+      let match;
+      while ((match = hrefRegex.exec(content)) !== null) {
+        hrefs.push(match[1]);
+      }
+
+      const badHrefs = hrefs.filter((h) => /\.html/.test(h));
+      expect(badHrefs, `Found .html hrefs in sidebar.js: ${badHrefs.join(", ")}`).toEqual([]);
+    });
+  });
+
+  describe("homepage replaceState redirect exists", () => {
+    it("index.html contains history.replaceState for /index.html cleanup", () => {
+      const indexPath = path.join(DOCS_DIR, "index.html");
+      const html = fs.readFileSync(indexPath, "utf-8");
+
+      expect(html).toContain("replaceState");
+      expect(html).toContain("index.html");
+    });
+  });
+
+  describe("all internal link targets resolve to existing pages", () => {
+    const knownPages = new Set<string>();
+
+    // Build set of known page slugs from directory names
+    const subdirs = fs
+      .readdirSync(DOCS_DIR, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+      .map((e) => e.name);
+
+    for (const dir of subdirs) {
+      knownPages.add(`/${dir}`);
+    }
+
+    for (const filePath of allHtmlFiles) {
+      const relative = path.relative(DOCS_DIR, filePath);
+
+      it(`${relative} — all internal links point to existing pages`, () => {
+        const html = fs.readFileSync(filePath, "utf-8");
+        const hrefs = extractInternalHrefs(html);
+
+        for (const href of hrefs) {
+          // Strip anchor
+          const base = href.split("#")[0];
+          if (base === "" || base === "/") continue; // root or anchor-only
+          if (base.startsWith("/")) {
+            expect(
+              knownPages.has(base),
+              `${relative} links to ${href} but no page directory exists for "${base}"`,
+            ).toBe(true);
+          }
+        }
+      });
+    }
+  });
+});