docs: make Astro content canonical and retire MkDocs adapter

.gitignore

@@ -161,8 +161,6 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
-/site
 
 # mypy
 .mypy_cache/
@@ -188,8 +186,13 @@ cython_debug/
 # Generated documentation
 astro-site/node_modules/
 astro-site/.astro/
-astro-site/src/content/docs/
 astro-site/src/data/
-astro-site/public/
 astro-site/test-results/
 astro-site/playwright-report/
+
+astro-site/src/content/docs/reference/
+astro-site/public/reference/
+astro-site/public/notebooks/
+astro-site/public/examples/
+astro-site/src/content/docs/guides/train-detect-model.md
+astro-site/public/evidence/

HANDOFF.md

@@ -0,0 +1,9 @@
+# Canonical Astro documentation
+
+Goal: retire the MkDocs compatibility layer while preserving public content and routes.
+
+PR: https://github.com/AmbiqAI/sleepkit/pull/49. Authored Markdown/MDX, navigation, redirects and static assets now belong to Astro. API pages, notebooks and downloads remain generated. MkDocs configuration and unused dependencies are removed.
+
+Review: notebook source links, download command examples and generation regression coverage corrected. Local build, type checks, content checks and browser tests pass. Independent final review and CI on the fix commit gate merging. CompressionKIT follows this cleanup.
+
+Ownership: edit astro-site/src/content/docs for authored pages, src/navigation.mjs for navigation and notebooks/ for notebook sources. See astro-site/README.md for generated paths and validation commands.

README.md

@@ -115,40 +115,40 @@ Checkout the [Guides](https://ambiqai.github.io/sleepkit/guides) to see detailed
 
 ### Hugging Face baseline artifacts
 
-See [the artifact publishing guide](docs/huggingface-artifacts.md) for the additive
+See [the artifact publishing guide](astro-site/src/content/docs/huggingface-artifacts.mdx) for the additive
 `python -m sleepkit.artifacts` workflow, starting with the historical SD-2-TCN-SM
 TFLite baseline. Staging and publication dry runs require no training runtime.
 
 ### Python detection recipe
 
-See [the detection recipe guide](docs/detection-recipe.md) for a sensor-to-artifact
+See [the detection recipe guide](astro-site/src/content/docs/detection-recipe.mdx) for a sensor-to-artifact
 pipeline with built-in feature generation, fitted preprocessing, held-out evaluation,
 and unlabeled inference. It is additive to the legacy task CLI.
 
-The [first golden experiment](docs/detection-golden.md) pins the membership
-baseline's config and dataset evidence. The [profiling harness](docs/detection-profiling.md)
+The [first golden experiment](astro-site/src/content/docs/detection-golden.mdx) pins the membership
+baseline's config and dataset evidence. The [profiling harness](astro-site/src/content/docs/detection-profiling.mdx)
 measures preparation, loading and training while preserving its finite sampling contract.
 
 ### Saved-feature sleep staging
 
-The [staging baseline guide](docs/staging-baseline.md) provides an explicit
+The [staging baseline guide](astro-site/src/content/docs/staging-baseline.mdx) provides an explicit
 read → preprocess → window → evaluate path for the historical SS-3 Keras model.
 It records cohort/input hashes and coverage while keeping historical provenance
-limitations visible. The [staging training recipe](docs/staging-training.md) adds
+limitations visible. The [staging training recipe](astro-site/src/content/docs/staging-training.mdx) adds
 explicit subject splits, Keras training, and prospective golden declarations.
 
 ### Licensing
 
 The code and Ambiq-authored documentation/site content use [BSD-3-Clause](LICENSE),
 except material with a separate notice. Model weights and datasets have their own
 terms; public availability does not imply commercial-use permission. See the
-[model licensing policy](docs/model-licensing-policy.md) for per-model choices,
+[model licensing policy](astro-site/src/content/docs/model-licensing-policy.mdx) for per-model choices,
 research restrictions and proposed optional Ambiq device terms.
 
 ### Shared foundation direction
 
-The [cross-KIT architecture proposal](docs/shared-foundation.md) describes the path
+The [cross-KIT architecture proposal](docs-maintainers/shared-foundation.md) describes the path
 toward reusable heliaEDGE blocks, first-class TensorFlow/PyTorch workflows, measured
 input-pipeline improvements, and traceable golden releases across the KITs.
-The [reusable-block candidates](docs/reusable-blocks.md) and synthetic signal recipe
+The [reusable-block candidates](docs-maintainers/reusable-blocks.md) and synthetic signal recipe
 exercise the first local interfaces with Git-pinned heliaEDGE backend profiles.

astro-site/MIGRATION.md

@@ -45,3 +45,7 @@ Landing installation examples are copyable Bash commands with no Termynal progre
 ## Public documentation boundary
 
 Private implementation API modules and their redirects are excluded. Shared architecture proposals, reusable-component experiments, feature-preparation implementation notes and unadopted draft license terms stay in the repository and are not published. Public task workflows and model licensing guidance remain. The public site now contains 55 authored Markdown pages, one notebook and 110 API modules (216 catalog symbols). Output checks reject internal routes and private modules in the catalog/reference model.
+
+## Canonical sources
+
+The one-time MkDocs adapter has been retired. Authored pages are now in `src/content/docs/`, navigation in `src/navigation.mjs`, and static assets in `public/`. API and notebook generation remain. See README.md for source ownership.

astro-site/README.md

@@ -1,6 +1,6 @@
 # sleepKIT documentation site
 
-The Astro/Starlight site reads the authored Markdown in `../docs` and the saved notebook in `../notebooks` and generates Python reference pages with Griffe. The Python package is inspected statically; no training dependencies or notebook execution are required.
+The Astro/Starlight site reads the authored Markdown/MDX in `src/content/docs/` and the saved notebook in `../notebooks` and generates Python reference pages with Griffe. The Python package is inspected statically; no training dependencies or notebook execution are required.
 
 Use Node 24, Python 3.12 and uv:
 
@@ -19,10 +19,14 @@ npm run check:output
 npm test
 ```
 
-`prepare:docs` regenerates `src/content/docs`, `src/data` and `public`. Do not edit those directories. Edit Markdown under `../docs`, Python docstrings, or the owning scripts. `mkdocs.yml` supplies the existing navigation during migration. `.cache/conversion.json` records syntax conversions and items requiring visual inspection.
+Edit authored Markdown/MDX in `src/content/docs/`, navigation in `src/navigation.mjs`, static redirects in `src/redirects.json`, and static assets in `public/`. These are canonical sources and are never replaced by the build.
 
-The notebook page uses `notebooks/train-detect-model.ipynb`, preserving its saved outputs, three figures and downloadable original. The earlier `docs/guides/` copy is retained as an archive download. Neither source is overwritten. Historical notebook outputs do not establish validation against the latest package.
+`prepare:docs` generates only downloadable configuration examples, notebook guides/assets, and Python API pages/data. API output under `src/content/docs/reference/`, notebook `.md` pages under `guides/`, `src/data/`, and `public/{reference,notebooks,examples}/` are ignored. Edit Python docstrings or the notebooks in `../notebooks/` for those outputs. There is no MkDocs configuration or Markdown conversion step.
+
+The notebook page uses `notebooks/train-detect-model.ipynb`, preserving its saved outputs, three figures and downloadable original. The earlier documentation copy is retained in `notebooks/archive/` as an archive download. Neither source is overwritten. Historical notebook outputs do not establish validation against the latest package.
 
 The documentation workflow checks pull requests and publishes main to GitHub Pages. It can also be dispatched manually on main. It does not publish Python packages. Package publishing remains in the release workflows; documentation no longer depends on a package release.
 
 Public reference generation excludes underscore-prefixed implementation modules before rendering, so they do not appear in pages, catalog, search or machine-readable exports. `scripts/public-docs.mjs` lists repository-only maintainer/proposal pages omitted from publication. Their sources remain in the repository.
+
+Golden-contract evidence remains canonical under `../docs/evidence/` because experiment declarations reference those paths. The build copies it to `public/evidence/`; do not edit the generated copy.

astro-site/package.json

@@ -9,15 +9,15 @@
     "npm": ">=11"
   },
   "scripts": {
-    "prepare:docs": "node scripts/build-content.mjs && python3 scripts/build-notebooks.py && node scripts/build-reference.mjs",
+    "prepare:docs": "node scripts/build-examples.mjs && python3 scripts/build-notebooks.py && node scripts/build-reference.mjs",
     "predev": "npm run prepare:docs",
     "dev": "astro dev",
     "prebuild": "npm run prepare:docs",
     "build": "astro build",
     "postbuild": "node scripts/publish-reference.mjs",
     "precheck": "npm run prepare:docs",
     "check": "astro check",
-    "check:output": "python3 scripts/check-doc-examples.py && node --test scripts/normalize-markdown.test.mjs && node scripts/check-output.mjs",
+    "check:output": "node --test scripts/canonical-content.test.mjs && python3 scripts/check-doc-examples.py && node scripts/check-output.mjs",
     "test": "playwright test"
   },
   "dependencies": {

astro-site/scripts/build-examples.mjs

@@ -0,0 +1,25 @@
+import { cpSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join, basename } from "node:path";
+
+const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
+  entry.isDirectory() ? walk(join(dir, entry.name)) : [join(dir, entry.name)],
+);
+rmSync("public/examples", { recursive: true, force: true });
+mkdirSync("public/examples", { recursive: true });
+const downloads = new Map();
+for (const file of walk("src/content/docs").filter((path) => path.endsWith(".mdx"))) {
+  const source = readFileSync(file, "utf8");
+  for (const match of source.matchAll(/<ConfigExample code=\{("(?:[^"\\]|\\.)*")\} lang="[^"]+" filename=("(?:[^"\\]|\\.)*")/g)) {
+    const code = JSON.parse(match[1]);
+    const name = JSON.parse(match[2]);
+    if (basename(name) !== name) throw new Error(`Invalid example filename in ${file}`);
+    if (downloads.has(name) && downloads.get(name) !== code) throw new Error(`Conflicting example: ${name}`);
+    if (name.endsWith(".json")) JSON.parse(code);
+    downloads.set(name, code);
+  }
+}
+for (const [name, code] of downloads) writeFileSync(join("public/examples", name), code + "\n");
+console.log(`Generated ${downloads.size} downloads from authored examples.`);
+
+rmSync("public/evidence", { recursive: true, force: true });
+cpSync("../docs/evidence", "public/evidence", { recursive: true });

astro-site/scripts/build-notebooks.py

@@ -12,7 +12,7 @@
 shutil.rmtree(assets, ignore_errors=True)
 assets.mkdir(parents=True, exist_ok=True)
 shutil.copyfile(source, assets / source.name)
-shutil.copyfile(Path("../docs/guides/train-detect-model.ipynb"), assets / "previous-docs-train-detect-model.ipynb")
+shutil.copyfile(Path("../notebooks/archive/previous-docs-train-detect-model.ipynb"), assets / "previous-docs-train-detect-model.ipynb")
 parts = [
     "---\ntitle: Train Sleep Detection Model\ndescription: Train a wrist-based sleep detection model with saved notebook code and outputs.\n---",
     f'<div class="sleepkit-actions"><a class="md-button" href="/sleepkit/notebooks/{source.name}">Download notebook</a> <a class="md-button" href="https://github.com/AmbiqAI/sleepkit/blob/main/notebooks/{source.name}">View source</a> <a class="md-button" href="https://colab.research.google.com/github/AmbiqAI/sleepkit/blob/main/notebooks/{source.name}">Open in Colab</a></div>',

astro-site/scripts/build-reference.mjs

@@ -12,6 +12,8 @@ const run = (cmd, args) =>
 rmSync("public/reference", { recursive: true, force: true });
 const commit = run("git", ["rev-parse", "HEAD"]).trim();
 mkdirSync(".cache", { recursive: true });
+mkdirSync("src/data", { recursive: true });
+rmSync("src/content/docs/reference/api", { recursive: true, force: true });
 const dump = JSON.parse(
   run("uv", [
     "tool",
@@ -107,14 +109,13 @@ writeFileSync(
 );
 writeFileSync(
   "src/data/redirects.json",
-  JSON.stringify(
-    Object.fromEntries(
-      modules.map((m) => [
-        "/api/" + m.path.replaceAll(".", "/"),
-        "/sleepkit/" + route(m) + "/",
-      ]),
-    ),
-  ),
+  JSON.stringify({
+    ...JSON.parse(readFileSync("src/redirects.json", "utf8")),
+    ...Object.fromEntries(modules.map((m) => [
+      "/api/" + m.path.replaceAll(".", "/"),
+      "/sleepkit/" + route(m) + "/",
+    ])),
+  }),
 );
 writeFileSync(
   "src/content/docs/reference/index.mdx",