docs: consolidate tutorials into the Python Quick Start

docs/src/data/pyQuickStart.ts

@@ -0,0 +1,19 @@
+// Section index for the Python Quick Start. Used by every page under
+// `quickstart/python/*` so the left-hand section nav stays consistent and
+// the order is defined in a single place.
+const base = (import.meta.env.BASE_URL || "/").replace(/\/$/, "");
+
+export interface PyQuickStartSection {
+  id: string;
+  label: string;
+  href: string;
+}
+
+export const pyQuickStartSections: PyQuickStartSection[] = [
+  { id: "install",          label: "§ 1 Install",                    href: `${base}/quickstart/python` },
+  { id: "stim",             label: "§ 2 Stim circuits & sampling",   href: `${base}/quickstart/python/stim` },
+  { id: "tableau",          label: "§ 3 Generalized Tableau",        href: `${base}/quickstart/python/tableau` },
+  { id: "pauli-propagation", label: "§ 4 Pauli Propagation",         href: `${base}/quickstart/python/pauli-propagation` },
+  { id: "loss-channel",     label: "§ 5 Loss channel details",       href: `${base}/quickstart/python/loss-channel` },
+  { id: "next-steps",       label: "§ 6 Next steps",                 href: `${base}/quickstart/python/next-steps` },
+];

docs/src/layouts/Base.astro

@@ -5,20 +5,27 @@ interface TocItem {
   label: string;
   href: string;
 }
+interface SectionItem {
+  id: string;
+  label: string;
+  href: string;
+}
 interface Props {
   title: string;
   description?: string;
-  current?: "home" | "quickstart" | "tutorials" | "examples" | "develop" | "api";
+  current?: "home" | "quickstart" | "examples" | "develop" | "api";
   toc?: TocItem[];
   tocTitle?: string;
+  sections?: SectionItem[];
+  currentSection?: string;
+  sectionsTitle?: string;
 }
 
-const { title, description = "ppvm — fast Pauli propagation and stabilizer-tableau quantum simulator.", current, toc, tocTitle = "On this page" } = Astro.props;
+const { title, description = "ppvm — fast Pauli propagation and stabilizer-tableau quantum simulator.", current, toc, tocTitle = "On this page", sections, currentSection, sectionsTitle = "Sections" } = Astro.props;
 const base = import.meta.env.BASE_URL.replace(/\/$/, "");
 const nav = [
   { id: "home", label: "Overview", href: `${base}/` },
   { id: "quickstart", label: "Quick Start", href: `${base}/quickstart` },
-  { id: "tutorials", label: "Tutorials", href: `${base}/tutorials` },
   { id: "examples", label: "Examples", href: `${base}/examples` },
   { id: "develop", label: "Develop", href: `${base}/develop` },
   { id: "api", label: "Reference", href: `${base}/api` },
@@ -77,7 +84,38 @@ const nav = [
       </div>
     </header>
     <main>
-      {toc && toc.length > 0 ? (
+      {sections && sections.length > 0 ? (
+        <div class="page-shell page-shell--3col">
+          <aside class="page-sections" aria-label={sectionsTitle}>
+            <div class="page-toc-label">{sectionsTitle}</div>
+            <ol>
+              {sections.map((s) => (
+                <li>
+                  <a
+                    href={s.href}
+                    aria-current={currentSection === s.id ? "page" : undefined}
+                  >{s.label}</a>
+                </li>
+              ))}
+            </ol>
+          </aside>
+          <div class="page-toc-content">
+            <slot />
+          </div>
+          {toc && toc.length > 0 ? (
+            <aside class="page-toc page-toc--right" aria-label={tocTitle}>
+              <div class="page-toc-label">{tocTitle}</div>
+              <ol>
+                {toc.map((t) => (
+                  <li><a href={t.href} data-toc-link={t.href}>{t.label}</a></li>
+                ))}
+              </ol>
+            </aside>
+          ) : (
+            <aside class="page-toc page-toc--right page-toc--empty" aria-hidden="true"></aside>
+          )}
+        </div>
+      ) : toc && toc.length > 0 ? (
         <div class="page-shell">
           <aside class="page-toc" aria-label={tocTitle}>
             <div class="page-toc-label">{tocTitle}</div>

docs/src/pages/quickstart/index.astro

@@ -27,7 +27,9 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
           <li>Install via <code>uv</code></li>
           <li>Parse and execute Stim programs</li>
           <li>Sample shots, inspect loss-aware outcomes</li>
-          <li>Try the generalized tableau with non-Clifford gates</li>
+          <li>Drive the generalized tableau gate-by-gate</li>
+          <li>Compute expectation values with Pauli propagation</li>
+          <li>Read the loss-channel math, end-to-end</li>
         </ul>
         <span class="qs-cta">Open the Python Quick Start</span>
       </a>

docs/src/pages/quickstart/python/index.astro

@@ -0,0 +1,79 @@
+---
+import Base from "../../../layouts/Base.astro";
+import { pyQuickStartSections } from "../../../data/pyQuickStart";
+const base = import.meta.env.BASE_URL.replace(/\/$/, "");
+const toc = [
+  { label: "Audience",     href: "#audience" },
+  { label: "Install ppvm", href: "#install" },
+  { label: "Verify",       href: "#verify" },
+];
+---
+<Base
+  title="Python Quick Start — Install"
+  current="quickstart"
+  toc={toc}
+  sections={pyQuickStartSections}
+  currentSection="install"
+>
+  <div class="qs-hero qs-hero--python">
+    <div class="qs-hero-inner">
+      <span class="chip"><span class="chip-dot"></span>Python · For researchers</span>
+      <h1><span class="lang">py</span>Quick Start</h1>
+      <p class="audience">
+        For physicists and students who want to <strong>run circuits under
+        noise</strong> and inspect outcomes — without writing any Rust.
+        Code you'd paste into a Jupyter cell.
+      </p>
+    </div>
+  </div>
+
+  <article class="shell narrow qs-page qs-page--python">
+    <section id="audience">
+      <h2>Audience</h2>
+      <p>
+        This Quick Start walks you through the Python interface end-to-end:
+        how to install ppvm, parse and sample Stim circuits, drive the
+        generalized stabilizer tableau gate-by-gate, compute expectation
+        values via Pauli propagation, and model neutral-atom qubit loss.
+        Each topic is its own section on the left.
+      </p>
+      <p>
+        If you'd rather embed ppvm into a Rust simulator or build on its
+        trait hierarchy, jump to the
+        <a href={`${base}/quickstart/rust`}>Rust Quick Start</a> instead.
+      </p>
+    </section>
+
+    <section id="install">
+      <h2>Install ppvm</h2>
+      <p>
+        Requires Python ≥ 3.10. The native extension is compiled
+        automatically from Rust during install. We recommend using
+        <a href="https://docs.astral.sh/uv/">uv</a> to manage your Python
+        environment.
+      </p>
+<pre><code class="language-bash">uv add git+https://github.com/QuEraComputing/ppvm.git#subdirectory=ppvm-python</code></pre>
+      <p>
+        If you prefer plain <code>pip</code> inside an existing virtualenv,
+        the same source URL works there too — the project policy in this
+        repository's own docs is <code>uv</code>, but the wheel itself
+        carries no opinions.
+      </p>
+    </section>
+
+    <section id="verify">
+      <h2>Verify the install</h2>
+      <p>Drop the following into a Python REPL or a Jupyter cell:</p>
+<pre><code class="language-python">from ppvm import GeneralizedTableau
+
+tab = GeneralizedTableau(n_qubits=1)
+tab.h(0)
+print(tab.measure(0))  # MeasurementResult.ZERO or MeasurementResult.ONE</code></pre>
+      <p>
+        If that prints a <code>MeasurementResult</code>, you're ready to
+        move on to <a href={`${base}/quickstart/python/stim`}>§ 2 Stim
+        circuits &amp; sampling</a>.
+      </p>
+    </section>
+  </article>
+</Base>