docs: reframe drift detection for users + add drift report output

- Headline: 'Your mocks never go stale'
- Lead reframed for users, not maintainers
- Restored drift report output block from v1.5.0 homepage
- Removed 'Running Drift Tests' key export section
- Feature card: 'Fixtures stay accurate as providers evolve'

Author: jpr5

docs/drift-detection.html

@@ -281,20 +281,91 @@ <h4>All three agree</h4>
           </div>
         </div>
 
-        <h2>Running Drift Tests</h2>
+        <h2>What Drift Looks Like</h2>
 
-        <div class="code-block">
-          <div class="code-block-header">Run drift tests <span class="lang-tag">shell</span></div>
-          <pre><code><span class="cm"># Set API keys for providers you want to test</span>
-<span class="kw">export</span> OPENAI_API_KEY=sk-...
-<span class="kw">export</span> ANTHROPIC_API_KEY=sk-ant-...
-<span class="kw">export</span> GOOGLE_API_KEY=AI...
-
-<span class="cm"># Run all drift tests</span>
-pnpm test:drift
+        <style>
+          .drift-report {
+            background: var(--bg-deep);
+            border: 1px solid var(--border);
+            border-radius: 8px;
+            padding: 1.25rem 1.5rem;
+            margin-top: 2rem;
+            font-family: var(--font-mono);
+            font-size: 0.75rem;
+            line-height: 1.8;
+            color: var(--text-secondary);
+            overflow-x: auto;
+          }
+          .drift-report .report-header {
+            color: var(--text-primary);
+            font-weight: 600;
+            margin-bottom: 0.75rem;
+            font-size: 0.8rem;
+          }
+          .drift-report .severity-critical {
+            color: var(--error);
+          }
+          .drift-report .severity-warning {
+            color: var(--warning);
+          }
+          .drift-report .severity-ok {
+            color: var(--accent);
+          }
+          .drift-report .field-path {
+            color: var(--blue);
+          }
+          .drift-report .drift-label {
+            color: var(--text-primary);
+          }
+          .drift-report .report-summary {
+            color: var(--text-dim);
+          }
+          .drift-report .field-label {
+            color: var(--text-dim);
+          }
+          .drift-report .divider {
+            border-top: 1px solid var(--border);
+            margin: 0.6rem 0;
+          }
+        </style>
 
-<span class="cm"># Run for a specific provider</span>
-pnpm test:drift -- --grep "OpenAI Chat"</code></pre>
+        <div class="drift-report">
+          <div class="report-header">$ pnpm test:drift</div>
+          <span class="severity-critical">[critical]</span>
+          <span class="drift-label">AIMOCK DRIFT</span> &mdash; field in SDK + real API but missing
+          from mock<br />
+          <span class="field-label">Path:</span>&nbsp;&nbsp;&nbsp;&nbsp;<span class="field-path"
+            >choices[].message.refusal</span
+          ><br />
+          <span class="field-label">SDK:</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;null &nbsp;&nbsp;
+          <span class="field-label">Real:</span> null &nbsp;&nbsp;
+          <span class="field-label">Mock:</span> &lt;absent&gt;<br />
+          <div class="divider"></div>
+          <span class="severity-critical">[critical]</span>
+          <span class="drift-label">TYPE MISMATCH</span> &mdash; real API and mock disagree on
+          type<br />
+          <span class="field-label">Path:</span>&nbsp;&nbsp;&nbsp;&nbsp;<span class="field-path"
+            >content[].input</span
+          ><br />
+          <span class="field-label">SDK:</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;object &nbsp;&nbsp;
+          <span class="field-label">Real:</span> object &nbsp;&nbsp;
+          <span class="field-label">Mock:</span> string<br />
+          <div class="divider"></div>
+          <span class="severity-warning">[warning]</span>
+          <span class="drift-label">PROVIDER ADDED FIELD</span> &mdash; in real API but not in SDK
+          or mock<br />
+          <span class="field-label">Path:</span>&nbsp;&nbsp;&nbsp;&nbsp;<span class="field-path"
+            >choices[].message.annotations</span
+          ><br />
+          <span class="field-label">SDK:</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;absent&gt;
+          &nbsp;&nbsp; <span class="field-label">Real:</span> array &nbsp;&nbsp;
+          <span class="field-label">Mock:</span> &lt;absent&gt;<br />
+          <div class="divider"></div>
+          <span class="severity-ok" style="font-size: 0.85rem">&#10003;</span>
+          <span class="report-summary"
+            >2 critical (test fails) &middot; 1 warning (logged) &middot; detected before any user
+            reported it</span
+          >
         </div>
 
         <h2>Test Files</h2>

docs/index.html

@@ -1363,10 +1363,7 @@ <h3>Chaos Testing</h3>
           <div class="feature-card fade-in" style="transition-delay: 0.4s">
             <div class="feature-icon">&#128202;</div>
             <h3>Drift Detection</h3>
-            <p>
-              Daily CI validation against real APIs. Know immediately when provider behavior changes
-              break your fixtures.
-            </p>
+            <p>Fixtures stay accurate as providers evolve. Fixes ship before your tests break.</p>
           </div>
         </div>
       </div>
@@ -1375,35 +1372,35 @@ <h3>Drift Detection</h3>
     <!-- ─── Section 6: Drift Detection / Reliability ──────────────── -->
     <section class="section-reliability" id="reliability">
       <div class="container">
-        <h2 class="fade-in">Verified against real APIs, every day</h2>
+        <h2 class="fade-in">Your mocks never go stale</h2>
         <p class="reliability-sub fade-in" style="transition-delay: 0.1s">
-          aimock's drift detection runs daily against live provider APIs. When response formats
-          change, you know immediately &mdash; not when your tests break in production.
+          LLM providers change their response formats without warning. aimock catches it within 24
+          hours and ships the fix before your tests break.
         </p>
 
         <div class="drift-flow fade-in" style="transition-delay: 0.2s">
           <div class="drift-step">
             <div class="drift-step-num">1</div>
             <h3>Real API calls</h3>
             <p>
-              Daily CI hits actual OpenAI, Anthropic, Gemini endpoints to capture current response
-              formats.
+              Daily CI hits actual OpenAI, Anthropic, Gemini endpoints to detect response format
+              changes.
             </p>
           </div>
           <div class="drift-step">
             <div class="drift-step-num">2</div>
-            <h3>Response validation</h3>
+            <h3>Compare &amp; detect</h3>
             <p>
-              Compares real responses against aimock's fixture format. Schema changes are caught
-              instantly.
+              Response schemas are validated against aimock's builders. Any drift is flagged
+              automatically.
             </p>
           </div>
           <div class="drift-step">
             <div class="drift-step-num">3</div>
-            <h3>Auto-remediation</h3>
+            <h3>Fix &amp; ship</h3>
             <p>
-              Drift detected &rarr; PR opened &rarr; fixtures, skills, and docs updated
-              automatically. Zero manual effort.
+              Drift detected &rarr; fixtures, builders, skills, and docs updated &rarr; PR shipped.
+              Always current, within a day.
             </p>
           </div>
         </div>