From bb46e5a18d76d05ab1fe69416d2734758e923aa4 Mon Sep 17 00:00:00 2001
From: Michael Pilosov <consistentbayes@gmail.com>
Date: Wed, 22 Apr 2026 10:41:24 -0600
Subject: [PATCH] =?UTF-8?q?add=20=C2=A70=20introduction=20(default=20colla?=
 =?UTF-8?q?psed)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three short paragraphs framing what the notebook studies: stability of
2-D embeddings under controlled perturbation of the input over time,
the two metrics logged per run, and why the streaming/longitudinal
angle matters for both visualization and downstream classification.
---
 app/web/static/style.css     | 29 ++++++++++++++++++++
 app/web/templates/index.html | 52 +++++++++++++++++++++++++++++++++++-
 2 files changed, 80 insertions(+), 1 deletion(-)

diff --git a/app/web/static/style.css b/app/web/static/style.css
index fcaf921..6b76300 100644
--- a/app/web/static/style.css
+++ b/app/web/static/style.css
@@ -653,6 +653,35 @@ button.submit:disabled { background: var(--faint); border-color: var(--faint); c
 }
 .dataset-picker .picker-toggle::before { content: "[ edit ]"; }
 .dataset-picker[open] .picker-toggle::before { content: "[ collapse ]"; color: var(--accent); }
+.dataset-picker.intro .picker-toggle::before { content: "[ read ]"; }
+.dataset-picker.intro[open] .picker-toggle::before { content: "[ collapse ]"; color: var(--accent); }
+
+.intro-prose {
+  max-width: 72ch;
+  color: var(--ink);
+  font-family: var(--serif);
+  font-size: 0.95rem;
+  line-height: 1.65;
+  padding: 0.3rem 0 0.4rem;
+}
+.intro-prose p { margin: 0 0 0.9rem; }
+.intro-prose p:last-child { margin-bottom: 0; }
+.intro-prose strong {
+  font-family: var(--sans);
+  font-weight: 600;
+  font-style: normal;
+  font-size: 0.82rem;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  color: var(--accent);
+  margin-right: 0.2rem;
+}
+.intro-prose a {
+  color: var(--accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+.intro-prose em { font-style: italic; }
 
 .dataset-picker .picker-body {
   padding: 0.4rem 2.2rem 1.6rem;
diff --git a/app/web/templates/index.html b/app/web/templates/index.html
index 1c30ab7..9691b94 100644
--- a/app/web/templates/index.html
+++ b/app/web/templates/index.html
@@ -4,7 +4,7 @@
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width,initial-scale=1" />
   <title>embedding notebook — web1</title>
-  <link rel="stylesheet" href="/static/style.css?v=6" />
+  <link rel="stylesheet" href="/static/style.css?v=7" />
   <script src="https://unpkg.com/htmx.org@2.0.4"></script>
   <script type="importmap">
   {
@@ -38,6 +38,56 @@
   </div>
 </header>
 
+<details class="dataset-picker intro" id="intro">
+  <summary>
+    <span class="picker-meta">
+      <span class="section-number">§ 0</span>
+      <span class="picker-title">introduction</span>
+      <span class="picker-selection">
+        <span class="lbl">scope</span>
+        <code>stability of low-dim embeddings under input drift</code>
+      </span>
+    </span>
+    <span class="picker-toggle" aria-hidden="true"></span>
+  </summary>
+
+  <div class="picker-body">
+    <div class="intro-prose">
+      <p>
+        <strong>What this is.</strong> Dimensionality reduction is a workhorse
+        for both exploratory visualization and downstream prediction, yet the
+        stability of its output under small perturbations of the input is
+        rarely examined directly. This notebook takes a narrow, empirical
+        approach: a three-dimensional point cloud (§&nbsp;1) is perturbed by a
+        controlled amount at each of a short sequence of timesteps, the
+        selected reducer (§&nbsp;2) is applied independently to every snapshot,
+        and the resulting trajectory of two-dimensional embeddings is recorded.
+      </p>
+      <p>
+        <strong>What it measures.</strong> Two stability views are logged
+        alongside each run and plotted on the
+        <a href="/metrics">metrics page</a>. Per-timestep travel —
+        ‖&thinsp;y(t)&thinsp;&minus;&thinsp;y(t&minus;1)&thinsp;‖ —
+        captures how much the 2-D layout moves between consecutive frames.
+        <em>k</em>NN retention captures how much of the input-space neighborhood
+        graph survives projection. Together they separate reducers that are
+        globally stable but locally noisy from those with the opposite failure
+        mode.
+      </p>
+      <p>
+        <strong>Why this matters.</strong> A reducer that looks well-behaved on
+        a single snapshot is not automatically the right tool for a streaming
+        or longitudinal setting. Used as the substrate for a visualization,
+        frame-to-frame motion will read as change the user did not request;
+        used as a feature-extraction step inside a classification pipeline,
+        drift between training and inference will quietly erode accuracy. The
+        aim here is to build intuition for those regimes before committing the
+        reducer to either role.
+      </p>
+    </div>
+  </div>
+</details>
+
 <details class="dataset-picker" id="picker" open>
   <summary>
     <span class="picker-meta">