beykyle · beykyle · Jun 12, 2026 · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026
diff --git a/DESIGN.md b/DESIGN.md
diff --git a/docs/_github_slugs.py b/docs/_github_slugs.py
@@ -0,0 +1,17 @@
+"""GitHub-style heading slugs for MyST (importable for Sphinx env pickling).
+
+DESIGN.md's table of contents uses GitHub anchor links such as
+``#1-overview-and-scope``; MyST's default slugger drops the leading digits,
+so we mirror GitHub's rule: lowercase, strip punctuation, spaces → dashes.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+def github_heading_slug(title: str) -> str:
+    """Return the GitHub anchor slug for one heading title."""
+
+    slug = re.sub(r"[^\w\- ]", "", title.strip().lower())
+    return slug.replace(" ", "-")
diff --git a/docs/api.rst b/docs/api.rst
@@ -52,8 +52,6 @@ Mesh-independent observables operating on a :class:`~lax.spectral.Spectrum`.
 
 .. autofunction:: lax.spectral.coupled_channel_parameters_from_S
 
-.. autofunction:: lax.spectral.pade_interpolate
-
 lax.models
 ----------
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -53,8 +53,22 @@
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
     "nbsphinx",
+    "myst_parser",
 ]
 
+# MyST renders the Markdown architecture reference (docs/design.md includes the
+# repository-root DESIGN.md).  dollarmath/amsmath enable its $…$/$$…$$ math;
+# heading anchors make the document's own #section links resolve.
+myst_enable_extensions = ["dollarmath", "amsmath"]
+myst_heading_anchors = 4
+
+
+# GitHub-style slugs so DESIGN.md's own #section links resolve.  Referenced
+# by import string (not a conf.py-local function) so the Sphinx environment
+# stays picklable.
+sys.path.insert(0, str(Path(__file__).parent))
+myst_heading_slug_func = "_github_slugs.github_heading_slug"
+
 # ---------------------------------------------------------------------------
 # Source / output
 # ---------------------------------------------------------------------------

diff --git a/docs/design.md b/docs/design.md
@@ -0,0 +1,13 @@
+# Architecture reference
+
+```{include} ../DESIGN.md
+:end-before: "---"
+```
+
+```{include} ../DESIGN.md
+:start-after: "[Appendix C: Implementation sharp edges](#appendix-c-implementation-sharp-edges)"
+```
+
+% The Markdown table of contents is skipped above: it forward-references
+% GitHub-style heading anchors (redundant here — Furo provides the local
+% sidebar TOC, and the anchor links only resolve on warm Sphinx rebuilds).
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -15,4 +15,3 @@ from committed outputs; run them locally with ``uv run jupyter lab`` (see
    notebooks/descouvemont_o16_ca44_demo
    notebooks/descouvemont_closed_channels_demo
    notebooks/fourier_demo
-   notebooks/energy_dependent_demo
diff --git a/docs/index.rst b/docs/index.rst
@@ -26,10 +26,11 @@ Key features:
 
    api
    examples
+   design
 
 Links
 -----
 
 - `Source code <https://github.com/beykyle/lax>`_
-- `Architecture reference (DESIGN.md) <https://github.com/beykyle/lax/blob/main/DESIGN.md>`_
+- :doc:`Architecture reference (DESIGN.md) <design>`
 - `Issue tracker <https://github.com/beykyle/lax/issues>`_
diff --git a/examples/alpha_pb_demo.ipynb b/examples/alpha_pb_demo.ipynb
diff --git a/examples/descouvemont_closed_channels_demo.ipynb b/examples/descouvemont_closed_channels_demo.ipynb
diff --git a/examples/descouvemont_np_demo.ipynb b/examples/descouvemont_np_demo.ipynb
diff --git a/examples/descouvemont_o16_ca44_demo.ipynb b/examples/descouvemont_o16_ca44_demo.ipynb
diff --git a/examples/energy_dependent_demo.ipynb b/examples/energy_dependent_demo.ipynb
diff --git a/examples/fourier_demo.ipynb b/examples/fourier_demo.ipynb
-Original file line number
+Diff line change
@@ Expand Up @@
     .. autofunction:: lax.spectral.coupled_channel_parameters_from_S
-    .. autofunction:: lax.spectral.pade_interpolate
     lax.models
     ----------
@@ Expand Down @@