docs(reality): surface mock fidelity preview and evidence scope

index.html

@@ -304,8 +304,9 @@ <h3 class="mt-4 text-lg font-semibold text-brand-dark">Latency &amp; fault injec
           <!-- Conformance / validation -->
           <article class="rounded-2xl p-7 bg-white ring-1 ring-black/5 shadow-soft">
             <i class="ph-duotone ph-seal-check text-3xl text-brand-orange"></i>
-            <h3 class="mt-4 text-lg font-semibold text-brand-dark">OpenAPI conformance</h3>
-            <p class="mt-2 text-sm text-text-secondary leading-relaxed">Validate requests against your spec with deep schema resolution across path, query, header, cookie and body.</p>
+            <h3 class="mt-4 text-lg font-semibold text-brand-dark">Reality: mock fidelity preview</h3>
+            <p class="mt-2 text-sm text-text-secondary leading-relaxed">Find changed fields, types and operations before an outdated mock gives you a passing test. Definition comparisons and the fidelity panel are in development.</p>
+            <a href="/note-api-drift-detection-and-contract-alerting.html#mock-fidelity" class="mt-4 inline-flex text-sm font-medium text-brand-orange hover:opacity-80">Explore the fidelity preview</a>
           </article>
 
           <!-- Record & replay -->

note-api-drift-detection-and-contract-alerting.html

@@ -157,6 +157,15 @@ <h1 class="mt-3 text-3xl font-semibold tracking-tight text-brand-ink sm:text-4xl
         <p class="mt-6 text-lg leading-8 text-slate-700">Most integration failures are not sudden outages. They are slow contract drift that nobody sees until deployment day.</p>
         <p class="mt-5 leading-8 text-slate-700">Our current model is to run spec-driven checks continuously and treat schema mismatch as an alerting event, not a debugging surprise. This catches nullable flips, enum additions, and response-shape regressions while teams still have rollback room.</p>
         <p class="mt-5 leading-8 text-slate-700">The practical win is faster triage: failures now include endpoint, expected shape, observed payload, and severity metadata so operators can route to the right service owner immediately.</p>
+        <h2 id="mock-fidelity" class="mt-8 text-2xl font-semibold text-brand-ink">Reality: keep mocks aligned with the API</h2>
+        <p class="mt-5 leading-8 text-slate-700"><strong>Mock fidelity is in development.</strong> The definition comparison, fixture checks and admin panel below require an upcoming release. Follow <a href="https://github.com/SaaSy-Solutions/mockforge/issues/849" class="font-medium text-brand-orange underline underline-offset-4 hover:opacity-80">the fidelity implementation</a> for availability.</p>
+        <p class="mt-5 leading-8 text-slate-700">Keep the definition used to generate your mock, then compare it with the current OpenAPI or AsyncAPI contract. Add a recent upstream capture to check the traffic you actually observed. The report identifies changed fields, types and operations so an old response shape cannot quietly become your test's source of truth.</p>
+        <pre class="mt-5 rounded-xl bg-slate-950 p-4 text-sm leading-6 text-slate-200 overflow-x-auto"><code>mockforge verify-mocks --spec upstream-current.yaml \
+  --mock-spec mock-generated-from.yaml \
+  --capture-db upstream-recordings.db --fail-on-drift \
+  --output fidelity.json</code></pre>
+        <p class="mt-5 leading-8 text-slate-700">Per-route results distinguish <strong>Verified</strong>, <strong>Drift detected</strong>, <strong>Not verified</strong> and <strong>Not sampled</strong>. Verification covers the supplied contract and captured sample. Missing capture data or unsupported formats stay visible as incomplete evidence. A matching definition alone does not prove that every production behavior was exercised.</p>
+        <p class="mt-5 leading-8 text-slate-700">Use the CI gate to make drift fail the build, inspect field-level changes in the admin panel, and refresh the affected mocks from the source you checked. Captures remain read-only, with timestamps in the report so the team can see which evidence supported the result.</p>
         <div class="mt-8 flex flex-wrap gap-3 text-sm">
           <a href="https://docs.mockforge.dev" class="inline-flex items-center rounded-xl bg-brand-orange px-4 py-2 font-medium text-white hover:opacity-90 transition">Docs</a>
           <a href="https://github.com/SaaSy-Solutions/mockforge" class="inline-flex items-center rounded-xl border border-black/10 px-4 py-2 font-medium text-text-primary hover:bg-black/5 dark:hover:bg-white/10 transition">GitHub</a>

src/pages/index.html

@@ -214,8 +214,9 @@ <h3 class="mt-4 text-lg font-semibold text-brand-dark">Latency &amp; fault injec
           <!-- Conformance / validation -->
           <article class="rounded-2xl p-7 bg-white ring-1 ring-black/5 shadow-soft">
             <i class="ph-duotone ph-seal-check text-3xl text-brand-orange"></i>
-            <h3 class="mt-4 text-lg font-semibold text-brand-dark">OpenAPI conformance</h3>
-            <p class="mt-2 text-sm text-text-secondary leading-relaxed">Validate requests against your spec with deep schema resolution across path, query, header, cookie and body.</p>
+            <h3 class="mt-4 text-lg font-semibold text-brand-dark">Reality: mock fidelity preview</h3>
+            <p class="mt-2 text-sm text-text-secondary leading-relaxed">Find changed fields, types and operations before an outdated mock gives you a passing test. Definition comparisons and the fidelity panel are in development.</p>
+            <a href="/note-api-drift-detection-and-contract-alerting.html#mock-fidelity" class="mt-4 inline-flex text-sm font-medium text-brand-orange hover:opacity-80">Explore the fidelity preview</a>
           </article>
 
           <!-- Record & replay -->

src/pages/note-api-drift-detection-and-contract-alerting.html

@@ -25,6 +25,15 @@ <h1 class="mt-3 text-3xl font-semibold tracking-tight text-brand-ink sm:text-4xl
         <p class="mt-6 text-lg leading-8 text-slate-700">Most integration failures are not sudden outages. They are slow contract drift that nobody sees until deployment day.</p>
         <p class="mt-5 leading-8 text-slate-700">Our current model is to run spec-driven checks continuously and treat schema mismatch as an alerting event, not a debugging surprise. This catches nullable flips, enum additions, and response-shape regressions while teams still have rollback room.</p>
         <p class="mt-5 leading-8 text-slate-700">The practical win is faster triage: failures now include endpoint, expected shape, observed payload, and severity metadata so operators can route to the right service owner immediately.</p>
+        <h2 id="mock-fidelity" class="mt-8 text-2xl font-semibold text-brand-ink">Reality: keep mocks aligned with the API</h2>
+        <p class="mt-5 leading-8 text-slate-700"><strong>Mock fidelity is in development.</strong> The definition comparison, fixture checks and admin panel below require an upcoming release. Follow <a href="https://github.com/SaaSy-Solutions/mockforge/issues/849" class="font-medium text-brand-orange underline underline-offset-4 hover:opacity-80">the fidelity implementation</a> for availability.</p>
+        <p class="mt-5 leading-8 text-slate-700">Keep the definition used to generate your mock, then compare it with the current OpenAPI or AsyncAPI contract. Add a recent upstream capture to check the traffic you actually observed. The report identifies changed fields, types and operations so an old response shape cannot quietly become your test's source of truth.</p>
+        <pre class="mt-5 rounded-xl bg-slate-950 p-4 text-sm leading-6 text-slate-200 overflow-x-auto"><code>mockforge verify-mocks --spec upstream-current.yaml \
+  --mock-spec mock-generated-from.yaml \
+  --capture-db upstream-recordings.db --fail-on-drift \
+  --output fidelity.json</code></pre>
+        <p class="mt-5 leading-8 text-slate-700">Per-route results distinguish <strong>Verified</strong>, <strong>Drift detected</strong>, <strong>Not verified</strong> and <strong>Not sampled</strong>. Verification covers the supplied contract and captured sample. Missing capture data or unsupported formats stay visible as incomplete evidence. A matching definition alone does not prove that every production behavior was exercised.</p>
+        <p class="mt-5 leading-8 text-slate-700">Use the CI gate to make drift fail the build, inspect field-level changes in the admin panel, and refresh the affected mocks from the source you checked. Captures remain read-only, with timestamps in the report so the team can see which evidence supported the result.</p>
         <div class="mt-8 flex flex-wrap gap-3 text-sm">
           <a href="https://docs.mockforge.dev" class="inline-flex items-center rounded-xl bg-brand-orange px-4 py-2 font-medium text-white hover:opacity-90 transition">Docs</a>
           <a href="https://github.com/SaaSy-Solutions/mockforge" class="inline-flex items-center rounded-xl border border-black/10 px-4 py-2 font-medium text-text-primary hover:bg-black/5 dark:hover:bg-white/10 transition">GitHub</a>