From fe30aff7ad662fb44f06ff2ced31dfa3d2f885c7 Mon Sep 17 00:00:00 2001
From: Sean Koval <seanmkoval@gmail.com>
Date: Fri, 13 Feb 2026 21:16:54 -0500
Subject: [PATCH] Add notebook workflow docs page and navigation links

---
 docs-site/src/layouts/Layout.astro            |  1 +
 docs-site/src/pages/examples.astro            |  7 ++
 docs-site/src/pages/getting-started.astro     |  7 ++
 .../pages/notebook-research-workflow.astro    | 70 +++++++++++++++++++
 4 files changed, 85 insertions(+)
 create mode 100644 docs-site/src/pages/notebook-research-workflow.astro

diff --git a/docs-site/src/layouts/Layout.astro b/docs-site/src/layouts/Layout.astro
index 2f846e0..205954b 100644
--- a/docs-site/src/layouts/Layout.astro
+++ b/docs-site/src/layouts/Layout.astro
@@ -14,6 +14,7 @@ const nav = [
   { href: `${base}/module`, label: "Module Pages" },
   { href: `${base}/api-reference`, label: "API by Subject" },
   { href: `${base}/examples`, label: "Examples by Subject" },
+  { href: `${base}/notebook-research-workflow`, label: "Notebook Workflow" },
   { href: `${base}/coverage`, label: "Coverage" },
   { href: `${base}/performance`, label: "Performance" },
   { href: `${base}/publishing`, label: "Publishing" },
diff --git a/docs-site/src/pages/examples.astro b/docs-site/src/pages/examples.astro
index 921609d..e31c1bf 100644
--- a/docs-site/src/pages/examples.astro
+++ b/docs-site/src/pages/examples.astro
@@ -1,10 +1,17 @@
 ---
 import Layout from "../layouts/Layout.astro";
+const base = import.meta.env.BASE_URL.endsWith("/")
+  ? import.meta.env.BASE_URL.slice(0, -1)
+  : import.meta.env.BASE_URL;
 ---
 <Layout title="Examples • OpenQuant-rs" description="Practical OpenQuant-rs examples for quant workflows.">
   <section class="hero">
     <h1>Examples by Subject</h1>
     <p class="muted">Examples follow the same five subject dividers used in the index, subjects, and API pages.</p>
+    <p>
+      Promotion path and controls:
+      <a href={`${base}/notebook-research-workflow`}>Notebook-First Research Workflow</a>.
+    </p>
   </section>
 
   <h2>1. Event-Driven Data and Labeling</h2>
diff --git a/docs-site/src/pages/getting-started.astro b/docs-site/src/pages/getting-started.astro
index ad1eef0..926e2d6 100644
--- a/docs-site/src/pages/getting-started.astro
+++ b/docs-site/src/pages/getting-started.astro
@@ -1,5 +1,8 @@
 ---
 import Layout from '../layouts/Layout.astro';
+const base = import.meta.env.BASE_URL.endsWith("/")
+  ? import.meta.env.BASE_URL.slice(0, -1)
+  : import.meta.env.BASE_URL;
 ---
 <Layout title="Getting Started • OpenQuant-rs">
   <section class="hero">
@@ -57,6 +60,10 @@ cargo test -p openquant --test structural_breaks test_sadf_test -- --ignored</co
   </table>
 
   <h2>First Quant Workflow</h2>
+  <p>
+    For notebook-first strategy research and promotion criteria, see
+    <a href={`${base}/notebook-research-workflow`}>Notebook-First Research Workflow</a>.
+  </p>
   <pre><code class="language-rust">use openquant::risk_metrics::RiskMetrics;
 
 let returns = vec![-0.02, 0.01, 0.015, -0.01, 0.005];
diff --git a/docs-site/src/pages/notebook-research-workflow.astro b/docs-site/src/pages/notebook-research-workflow.astro
new file mode 100644
index 0000000..1afadb3
--- /dev/null
+++ b/docs-site/src/pages/notebook-research-workflow.astro
@@ -0,0 +1,70 @@
+---
+import Layout from "../layouts/Layout.astro";
+---
+<Layout
+  title="Notebook Research Workflow • OpenQuant-rs"
+  description="Notebook-first research workflow for OpenQuant-rs with reproducibility and leakage controls."
+>
+  <section class="hero">
+    <h1>Notebook-First Research Workflow</h1>
+    <p class="muted">
+      Promotion path from exploratory notebook to reproducible candidate strategy,
+      aligned with <code>docs/research_workflow.md</code>.
+    </p>
+  </section>
+
+  <h2>Promotion Path</h2>
+  <ol>
+    <li>Exploratory notebook in <code>notebooks/python/*.ipynb</code>.</li>
+    <li>
+      Scripted experiment in <code>experiments/run_pipeline.py</code> with a TOML
+      config.
+    </li>
+    <li>
+      Artifact and parity checks in <code>python/tests/test_experiment_scaffold.py</code>.
+    </li>
+    <li>
+      Candidate decision recorded as <code>decision.md</code> in the run artifact
+      directory.
+    </li>
+  </ol>
+
+  <h2>Local Commands</h2>
+  <pre><code class="language-bash"># setup
+uv venv --python 3.11 .venv
+uv sync --group dev
+uv run --python .venv/bin/python maturin develop --manifest-path crates/pyopenquant/Cargo.toml
+
+# notebook logic smoke
+uv run --python .venv/bin/python python notebooks/python/scripts/smoke_all.py
+
+# reproducible experiment run
+uv run --python .venv/bin/python python experiments/run_pipeline.py --config experiments/configs/futures_oil_baseline.toml --out experiments/artifacts
+
+# parity + scaffold tests
+uv run --python .venv/bin/python pytest python/tests/test_experiment_scaffold.py -q</code></pre>
+
+  <h2>Leakage and Reproducibility Checklist</h2>
+  <ul>
+    <li>Use event-based sampling and leakage-safe validation paths.</li>
+    <li>Keep deterministic seeds and config-hashed run directories.</li>
+    <li>Report gross and net metrics with turnover and cost estimates.</li>
+    <li>Require statistical and economic gates before promotion.</li>
+    <li>
+      Confirm leakage checks pass: <code>inputs_aligned</code> and
+      <code>event_indices_sorted</code>.
+    </li>
+    <li>
+      Artifact bundle includes <code>manifest.json</code>, parquet outputs, and
+      <code>decision.md</code>.
+    </li>
+  </ul>
+
+  <h2>Anti-Patterns</h2>
+  <ul>
+    <li>Random CV splits on overlapping financial labels.</li>
+    <li>Promoting on gross-only metrics without cost accounting.</li>
+    <li>Notebook-only logic that cannot be reproduced from config.</li>
+    <li>Hidden mutable state across notebook cells.</li>
+  </ul>
+</Layout>