docs: migration-page quality sweep (follow-up to #121)

docs/chaos-testing/index.html

@@ -217,7 +217,7 @@ <h2>CLI Flags</h2>
               <div class="code-block-header">
                 CLI chaos flags <span class="lang-tag">shell</span>
               </div>
-              <pre><code>$ npx @copilotkit/aimock --fixtures ./fixtures \
+              <pre><code>$ npx -p @copilotkit/aimock llmock --fixtures ./fixtures \
   --chaos-drop 0.1 \
   --chaos-malformed 0.05 \
   --chaos-disconnect 0.02</code></pre>
@@ -254,7 +254,7 @@ <h2>Journal Tracking</h2>
   "path": "/v1/chat/completions",
   "response": {
     "status": 500,
-    "fixture": { "..." },
+    "fixture": { "...": "elided for brevity" },
     "chaosAction": "drop"
   }
 }</code></pre>

docs/migrate-from-mock-llm/index.html

@@ -242,7 +242,7 @@ <h3>Zero dependencies</h3>
           <div class="feature-card">
             <div class="feature-icon purple">&#128230;</div>
             <h3>Vector DB mocking</h3>
-            <p>Mock Pinecone, Qdrant, Weaviate, and ChromaDB endpoints for RAG pipeline testing.</p>
+            <p>Mock Pinecone, Qdrant, and ChromaDB endpoints for RAG pipeline testing.</p>
           </div>
           <div class="feature-card">
             <div class="feature-icon amber">&#9210;</div>
@@ -446,6 +446,20 @@ <h2>Kubernetes migration</h2>
   <span class="prop">mountPath</span>: <span class="str">/app/fixtures</span>
   <span class="prop">existingClaim</span>: <span class="str">""</span>  <span class="cm"># PVC for fixture files</span>
 
+<span class="prop">livenessProbe</span>:
+  <span class="prop">httpGet</span>:
+    <span class="prop">path</span>: <span class="str">/health</span>
+    <span class="prop">port</span>: <span class="num">4010</span>
+  <span class="prop">initialDelaySeconds</span>: <span class="num">5</span>
+  <span class="prop">periodSeconds</span>: <span class="num">10</span>
+
+<span class="prop">readinessProbe</span>:
+  <span class="prop">httpGet</span>:
+    <span class="prop">path</span>: <span class="str">/ready</span>
+    <span class="prop">port</span>: <span class="num">4010</span>
+  <span class="prop">initialDelaySeconds</span>: <span class="num">2</span>
+  <span class="prop">periodSeconds</span>: <span class="num">5</span>
+
 <span class="prop">resources</span>: {}
   <span class="cm"># limits:</span>
   <span class="cm">#   cpu: 200m</span>
@@ -477,8 +491,8 @@ <h2>CLI / Docker quick start</h2>
               <div class="code-block-header">
                 Install &amp; run <span class="lang-tag">sh</span>
               </div>
-              <pre><code><span class="cm"># Run the mock server</span>
-npx @copilotkit/aimock -p <span class="num">4010</span> -f ./fixtures
+              <pre><code><span class="cm"># Run the mock server (flag-driven llmock bin)</span>
+npx -p @copilotkit/aimock llmock -p <span class="num">4010</span> -f ./fixtures
 
 <span class="cm"># With a full config file</span>
 npx @copilotkit/aimock --config aimock.json --port <span class="num">4010</span>

docs/migrate-from-mokksy/index.html

@@ -153,16 +153,19 @@ <h2>The quick switch</h2>
         <span class="str">"-p"</span>, <span class="str">"4010:4010"</span>, <span class="str">"-v"</span>, <span class="str">"./fixtures:/fixtures"</span>,
         <span class="str">"ghcr.io/copilotkit/aimock"</span>, <span class="str">"-f"</span>, <span class="str">"/fixtures"</span>, <span class="str">"-h"</span>, <span class="str">"0.0.0.0"</span>)
         .<span class="fn">start</span>().<span class="fn">waitFor</span>()
-    <span class="cm">// Wait for server to be ready</span>
+    <span class="cm">// Wait for server to be ready — fail loudly if it never comes up</span>
+    <span class="kw">var</span> <span class="op">lastError</span>: <span class="type">Exception</span>? = <span class="kw">null</span>
     <span class="kw">repeat</span>(<span class="num">30</span>) {
         <span class="kw">try</span> {
-            <span class="type">java.net.URL</span>(<span class="str">"http://localhost:4010/__aimock/health"</span>)
+            <span class="type">java.net.URL</span>(<span class="str">"http://localhost:4010/health"</span>)
                 .<span class="fn">readText</span>()
             <span class="kw">return</span>
-        } <span class="kw">catch</span> (_: <span class="type">Exception</span>) {
+        } <span class="kw">catch</span> (<span class="op">e</span>: <span class="type">Exception</span>) {
+            <span class="op">lastError</span> = <span class="op">e</span>
             <span class="type">Thread</span>.<span class="fn">sleep</span>(<span class="num">200</span>)
         }
     }
+    <span class="kw">throw</span> <span class="type">IllegalStateException</span>(<span class="str">"aimock did not become healthy after 30 attempts"</span>, <span class="op">lastError</span>)
 }
 
 <span class="kw">@AfterAll</span>
@@ -403,7 +406,7 @@ <h2>CLI / Docker quick start</h2>
           <div class="tab-cli">
             <div class="code-block">
               <div class="code-block-header">CLI <span class="lang-tag">sh</span></div>
-              <pre><code>npx @copilotkit/aimock -p <span class="num">4010</span> -f ./fixtures</code></pre>
+              <pre><code>npx -p @copilotkit/aimock llmock -p <span class="num">4010</span> -f ./fixtures</code></pre>
             </div>
           </div>
           <div class="tab-docker">

docs/migrate-from-msw/index.html

@@ -250,14 +250,21 @@ <h3>Built-in SSE for 8 providers</h3>
           <div class="feature-card">
             <div class="feature-icon purple">&#128268;</div>
             <h3>WebSocket APIs</h3>
-            <p>OpenAI Realtime, Responses WS, Gemini Live. MSW cannot intercept WebSocket.</p>
+            <p>
+              OpenAI Realtime, Responses WS, Gemini Live &mdash; all built in. MSW v2 added
+              WebSocket interception via <code>ws.link()</code>, but you still handwrite every
+              frame; aimock ships the full provider handshakes.
+            </p>
           </div>
           <div class="feature-card">
             <div class="feature-icon amber">&#9210;</div>
             <h3>Record &amp; Replay</h3>
             <p>
               Proxy real APIs, save as fixtures, replay forever.
-              <code>npx @copilotkit/aimock --record --provider-openai https://api.openai.com</code>
+              <code
+                >npx -p @copilotkit/aimock llmock --record --provider-openai
+                https://api.openai.com</code
+              >
             </p>
           </div>
           <div class="feature-card">
@@ -311,9 +318,9 @@ <h2>What you keep (or lose)</h2>
             </tr>
             <tr>
               <td>WebSocket</td>
-              <td style="color: var(--error)">&#10007;</td>
-              <td style="color: var(--accent)">&#10003;</td>
-              <td>3 protocols</td>
+              <td style="color: var(--text-dim)">Manual (ws.link, v2+)</td>
+              <td style="color: var(--accent)">Built-in</td>
+              <td>3 AI protocols</td>
             </tr>
             <tr>
               <td>Record &amp; replay</td>
@@ -347,6 +354,7 @@ <h2>Using aimock alongside MSW</h2>
           <div class="code-block-header">test-setup.ts <span class="lang-tag">ts</span></div>
           <pre><code><span class="cm">// test setup</span>
 <span class="kw">import</span> { <span class="fn">setupServer</span> } <span class="kw">from</span> <span class="str">'msw/node'</span>
+<span class="kw">import</span> { <span class="fn">http</span>, <span class="type">HttpResponse</span> } <span class="kw">from</span> <span class="str">'msw'</span>
 <span class="kw">import</span> { <span class="type">LLMock</span> } <span class="kw">from</span> <span class="str">'@copilotkit/aimock'</span>
 
 <span class="cm">// MSW for REST APIs</span>
@@ -372,7 +380,7 @@ <h2>CLI / Docker quick start</h2>
           <div class="tab-cli">
             <div class="code-block">
               <div class="code-block-header">CLI <span class="lang-tag">sh</span></div>
-              <pre><code>npx @copilotkit/aimock -p <span class="num">4010</span> -f ./fixtures</code></pre>
+              <pre><code>npx -p @copilotkit/aimock llmock -p <span class="num">4010</span> -f ./fixtures</code></pre>
             </div>
           </div>
           <div class="tab-docker">

docs/migrate-from-openai-responses/index.html

@@ -183,7 +183,7 @@ <h2>Before / After</h2>
             <pre><code><span class="kw">from</span> openai <span class="kw">import</span> OpenAI
 
 <span class="kw">def</span> <span class="fn">test_chat</span>(aimock):
-    aimock.on_message(<span class="str">"hi"</span>, content=<span class="str">"Hello!"</span>)
+    aimock.on_message(<span class="str">"hi"</span>, {<span class="str">"content"</span>: <span class="str">"Hello!"</span>})
     client = OpenAI(base_url=aimock.url + <span class="str">"/v1"</span>, api_key=<span class="str">"test"</span>)
     result = client.chat.completions.create(
         model=<span class="str">"gpt-4o"</span>, messages=[{<span class="str">"role"</span>: <span class="str">"user"</span>, <span class="str">"content"</span>: <span class="str">"hi"</span>}]
@@ -266,7 +266,7 @@ <h2>Feature mapping</h2>
             </tr>
             <tr>
               <td><code>openai_mock.chat.completions.create.response = {...}</code></td>
-              <td><code>aimock.on_message("pattern", content="...")</code></td>
+              <td><code>aimock.on_message("pattern", {"content": "..."})</code></td>
             </tr>
             <tr>
               <td>Partial envelope (choices required, other fields auto-filled)</td>

docs/migrate-from-piyook/index.html

@@ -191,14 +191,14 @@ <h2>Fixture format comparison</h2>
             <pre><code>{
   <span class="prop">"match"</span>: { <span class="prop">"userMessage"</span>: <span class="str">"hello"</span> },
   <span class="prop">"response"</span>: { <span class="prop">"content"</span>: <span class="str">"Hello there"</span> }
-}
-
-<span class="cm">// aimock auto-generates:</span>
-<span class="cm">//   - id, object, created, model</span>
-<span class="cm">//   - choices[].index, finish_reason</span>
-<span class="cm">//   - usage (prompt_tokens, completion_tokens)</span>
-<span class="cm">//   - SSE streaming chunks (when stream: true)</span></code></pre>
+}</code></pre>
           </div>
+          <p style="color: var(--text-dim); font-size: 0.9em; margin-top: 0.5em">
+            aimock auto-generates <code>id</code>, <code>object</code>, <code>created</code>,
+            <code>model</code>, <code>choices[].index</code>, <code>finish_reason</code>,
+            <code>usage</code> (prompt / completion tokens), and SSE streaming chunks when
+            <code>stream: true</code>.
+          </p>
         </div>
 
         <p>
@@ -391,8 +391,8 @@ <h2>CLI / Docker quick start</h2>
               <div class="code-block-header">
                 Install &amp; run <span class="lang-tag">sh</span>
               </div>
-              <pre><code><span class="cm"># Run the mock server</span>
-npx @copilotkit/aimock -p <span class="num">4010</span> -f ./fixtures
+              <pre><code><span class="cm"># Run the mock server (flag-driven llmock bin)</span>
+npx -p @copilotkit/aimock llmock -p <span class="num">4010</span> -f ./fixtures
 
 <span class="cm"># With a full config file</span>
 npx @copilotkit/aimock --config aimock.json --port <span class="num">4010</span>

docs/migrate-from-python-mocks/index.html

@@ -255,21 +255,41 @@ <h3>aimock (after)</h3>
         <span class="str">"ghcr.io/copilotkit/aimock:latest"</span>,
         <span class="str">"-f"</span>, <span class="str">"/fixtures"</span>, <span class="str">"-h"</span>, <span class="str">"0.0.0.0"</span>
     ])
-    <span class="cm"># Wait for health endpoint</span>
+    <span class="cm"># Wait for health endpoint — fail loudly if aimock never comes up</span>
     <span class="kw">import</span> requests
     <span class="kw">for</span> _ <span class="kw">in</span> range(<span class="num">30</span>):
+        <span class="kw">if</span> proc.poll() <span class="kw">is not None</span>:
+            <span class="kw">raise</span> RuntimeError(<span class="str">f"aimock exited early with code {proc.returncode}"</span>)
         <span class="kw">try</span>:
-            <span class="kw">if</span> requests.get(<span class="str">"http://localhost:4010/__aimock/health"</span>).ok:
+            <span class="kw">if</span> requests.get(<span class="str">"http://localhost:4010/health"</span>).ok:
                 <span class="kw">break</span>
         <span class="kw">except</span> requests.ConnectionError:
-            time.sleep(<span class="num">0.2</span>)
-
+            <span class="kw">pass</span>
+        time.sleep(<span class="num">0.2</span>)
+    <span class="kw">else</span>:
+        <span class="kw">raise</span> RuntimeError(<span class="str">"aimock did not become healthy after 30 attempts"</span>)
+
+    <span class="cm"># Save originals so we don't clobber real credentials in the test process</span>
+    prev_base = os.environ.get(<span class="str">"OPENAI_BASE_URL"</span>)
+    prev_key = os.environ.get(<span class="str">"OPENAI_API_KEY"</span>)
     os.environ[<span class="str">"OPENAI_BASE_URL"</span>] = <span class="str">"http://localhost:4010/v1"</span>
     os.environ[<span class="str">"OPENAI_API_KEY"</span>] = <span class="str">"mock-key"</span>
 
-    <span class="kw">yield</span> <span class="str">"http://localhost:4010"</span>
-    proc.terminate()
-    proc.wait()</code></pre>
+    <span class="kw">try</span>:
+        <span class="kw">yield</span> <span class="str">"http://localhost:4010"</span>
+    <span class="kw">finally</span>:
+        proc.terminate()
+        <span class="kw">try</span>:
+            proc.wait(timeout=<span class="num">10</span>)
+        <span class="kw">except</span> subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=<span class="num">5</span>)
+        <span class="cm"># Restore originals (or remove if there were none)</span>
+        <span class="kw">for</span> name, val <span class="kw">in</span> ((<span class="str">"OPENAI_BASE_URL"</span>, prev_base), (<span class="str">"OPENAI_API_KEY"</span>, prev_key)):
+            <span class="kw">if</span> val <span class="kw">is None</span>:
+                os.environ.pop(name, <span class="kw">None</span>)
+            <span class="kw">else</span>:
+                os.environ[name] = val</code></pre>
           </div>
 
           <div class="code-block">
@@ -435,8 +455,8 @@ <h2>CLI / Docker quick start</h2>
               <div class="code-block-header">
                 Install &amp; run <span class="lang-tag">sh</span>
               </div>
-              <pre><code><span class="cm"># Run the mock server (requires Node.js)</span>
-npx @copilotkit/aimock -p <span class="num">4010</span> -f ./fixtures
+              <pre><code><span class="cm"># Run the mock server (requires Node.js, flag-driven llmock bin)</span>
+npx -p @copilotkit/aimock llmock -p <span class="num">4010</span> -f ./fixtures
 
 <span class="cm"># Point your Python app at the mock</span>
 <span class="kw">export</span> OPENAI_BASE_URL=http://localhost:4010/v1
@@ -490,24 +510,44 @@ <h2>Alternative: npx fixture (no Docker)</h2>
 <span class="op">@pytest.fixture</span>(scope=<span class="str">"session"</span>)
 <span class="kw">def</span> <span class="fn">aimock_server</span>():
     proc = subprocess.Popen(
-        [<span class="str">"npx"</span>, <span class="str">"aimock"</span>, <span class="str">"-p"</span>, <span class="str">"4010"</span>, <span class="str">"-f"</span>, <span class="str">"./fixtures"</span>],
-        stdout=subprocess.PIPE, stderr=subprocess.STDOUT
+        [<span class="str">"npx"</span>, <span class="str">"-p"</span>, <span class="str">"@copilotkit/aimock"</span>, <span class="str">"llmock"</span>, <span class="str">"-p"</span>, <span class="str">"4010"</span>, <span class="str">"-f"</span>, <span class="str">"./fixtures"</span>],
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
     )
-    <span class="cm"># Wait for health endpoint</span>
+    <span class="cm"># Wait for health endpoint — fail loudly if aimock never comes up</span>
     <span class="kw">import</span> requests
     <span class="kw">for</span> _ <span class="kw">in</span> range(<span class="num">30</span>):
+        <span class="kw">if</span> proc.poll() <span class="kw">is not None</span>:
+            <span class="kw">raise</span> RuntimeError(<span class="str">f"aimock exited early with code {proc.returncode}"</span>)
         <span class="kw">try</span>:
-            <span class="kw">if</span> requests.get(<span class="str">"http://localhost:4010/__aimock/health"</span>).ok:
+            <span class="kw">if</span> requests.get(<span class="str">"http://localhost:4010/health"</span>).ok:
                 <span class="kw">break</span>
         <span class="kw">except</span> requests.ConnectionError:
-            time.sleep(<span class="num">0.2</span>)
-
+            <span class="kw">pass</span>
+        time.sleep(<span class="num">0.2</span>)
+    <span class="kw">else</span>:
+        <span class="kw">raise</span> RuntimeError(<span class="str">"aimock did not become healthy after 30 attempts"</span>)
+
+    <span class="cm"># Save originals so we don't clobber real credentials in the test process</span>
+    prev_base = os.environ.get(<span class="str">"OPENAI_BASE_URL"</span>)
+    prev_key = os.environ.get(<span class="str">"OPENAI_API_KEY"</span>)
     os.environ[<span class="str">"OPENAI_BASE_URL"</span>] = <span class="str">"http://localhost:4010/v1"</span>
     os.environ[<span class="str">"OPENAI_API_KEY"</span>] = <span class="str">"mock-key"</span>
 
-    <span class="kw">yield</span> <span class="str">"http://localhost:4010"</span>
-    proc.terminate()
-    proc.wait()</code></pre>
+    <span class="kw">try</span>:
+        <span class="kw">yield</span> <span class="str">"http://localhost:4010"</span>
+    <span class="kw">finally</span>:
+        proc.terminate()
+        <span class="kw">try</span>:
+            proc.wait(timeout=<span class="num">10</span>)
+        <span class="kw">except</span> subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=<span class="num">5</span>)
+        <span class="cm"># Restore originals (or remove if there were none)</span>
+        <span class="kw">for</span> name, val <span class="kw">in</span> ((<span class="str">"OPENAI_BASE_URL"</span>, prev_base), (<span class="str">"OPENAI_API_KEY"</span>, prev_key)):
+            <span class="kw">if</span> val <span class="kw">is None</span>:
+                os.environ.pop(name, <span class="kw">None</span>)
+            <span class="kw">else</span>:
+                os.environ[name] = val</code></pre>
         </div>
       </main>
       <aside class="page-toc" id="page-toc"></aside>

docs/migrate-from-vidaimock/index.html

@@ -78,7 +78,7 @@ <h2>The quick switch</h2>
                 aimock (equivalent)
                 <span class="lang-tag">shell</span>
               </div>
-              <pre><code>npx @copilotkit/aimock -p 4010 -f ./fixtures</code></pre>
+              <pre><code>npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures</code></pre>
             </div>
           </div>
           <div class="tab-docker">
@@ -286,8 +286,8 @@ <h2>CLI / Docker quick start</h2>
                 Install &amp; run
                 <span class="lang-tag">shell</span>
               </div>
-              <pre><code><span class="cm"># Run the mock server</span>
-npx @copilotkit/aimock -p 4010 -f ./fixtures
+              <pre><code><span class="cm"># Run the mock server (flag-driven llmock bin)</span>
+npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures
 
 <span class="cm"># Point your app at it</span>
 <span class="kw">export</span> OPENAI_BASE_URL=http://localhost:4010/v1