docs: make Astro content canonical and retire MkDocs adapter

.gitignore

@@ -159,8 +159,6 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
-/site
 
 # mypy
 .mypy_cache/
@@ -186,8 +184,16 @@ cython_debug/
 
 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/byot.md
+astro-site/src/content/docs/guides/train-ecg-segmentation.md
+astro-site/src/content/docs/guides/train-arrhythmia-model.md
+astro-site/src/content/docs/guides/ecg-foundation-model.md
+astro-site/src/content/docs/guides/train-ecg-denoiser.md

AGENTS.md

@@ -2,7 +2,7 @@
 
 Repo-specific notes for automation and maintenance:
 - Python target is 3.12; use `uv sync` for installs and `uv run pytest tests/` for tests.
-- Docs use Astro/Starlight in `astro-site/`, generated from Markdown under `docs/`, saved notebooks and Python docstrings. Edit sources rather than generated content.
+- Docs use Astro/Starlight in `astro-site/`, with authored Markdown/MDX in `astro-site/src/content/docs/` and navigation in `astro-site/src/navigation.mjs`. Only notebook guides and Python API pages are generated; edit their sources.
 - Use Node 24. From `astro-site/`, run `npm ci`, `npm run check`, `npm run build`, `npm run check:output` and `npm test`. Builds need Python and uv for static API extraction; notebook training is not executed.
 - The documentation workflow deploys Pages from main independently of package releases. Preserve historical URL redirects and keep headings plain Markdown.
 - Prefer `rg` for searches and avoid touching binary assets unless requested.

HANDOFF.md

@@ -1,45 +1,9 @@
-# heartKIT Astro migration
+# Canonical Astro documentation
 
-## Goal and scope
+Goal: retire the MkDocs compatibility layer while preserving public content and routes.
 
-Migrate public docs to Astro/Starlight using the sleepKIT layout and conversion fixes. Preserve content and URLs, render saved notebook outputs, generate public Python reference, and deploy docs independently of package releases. Runtime updates, model refreshes and Hugging Face deployment are separate follow-ups.
+PR: https://github.com/AmbiqAI/heartkit/pull/48. 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.
 
-## References
+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.
 
-- Issue: https://github.com/AmbiqAI/heartkit/issues/43 (creation approved).
-- Worktree: /Users/adam.page/Ambiq/adks/heartkit-docs
-- Branch: codex/heartkit-astro; baseline 64cd51b, version 1.8.0.
-- Preview: http://127.0.0.1:8777/heartkit/
-- Primary checkout untouched. PR: https://github.com/AmbiqAI/heartkit/pull/44 (250c9e7). Both independent reviews complete; findings resolved. Python CI and documentation CI passed on 250c9e7; heartKIT merge remains for user approval.
-
-## Implemented
-
-Astro site under astro-site, scoped navigation, branded dark hero and independent Pages workflow. Preserved MkDocs sources and repaired malformed syntax, missing model-zoo snippet includes and docstring formatting. Python edits affect docstrings only.
-
-Migrated 44 standalone Markdown pages, five notebooks and 122 public API modules (161 catalog symbols). All five docs/notebooks pairs are identical. Downloads preserve original bytes; all 18 saved PNG figures render. Notebooks were not executed. Rich HTML outputs use plain-text fallbacks. Private modules are excluded from API pages and exports. Historical API and notebook URLs redirect.
-
-## Verified
-
-Production build and internal links across 334 HTML documents pass. Astro check: zero errors, warnings or hints. Four converter tests and seven browser tests pass. All 49 authored/notebook routes loaded at desktop and mobile widths without horizontal overflow or broken images; selected landing, Quickstart and notebook screenshots inspected. All 32 copied non-theme assets are byte-identical. git diff --check and notebook-renderer Ruff checks pass.
-
-## Follow-up refinements
-
-Restored the shared heliaEDGE/heartKIT red token mapping and a brighter red hero accent. Added uvx/pipx installation tabs with reduced-motion-aware transitions, replaced task recap tabs with a comparison table, and removed obsolete code annotation markers. Missing snippet includes now fail the build instead of silently emitting placeholder content. Desktop/mobile hero and installation screenshots inspected; installation tabs exercised. Retained interactive ECG traces and confusion matrices.
-
-Hero copy approved: “Turn heart signals into on-device intelligence.” Introduction describes heartKIT as a Python-based AI Development Kit for heart monitoring on Ambiq devices.
-
-Latest browser feedback resolved: mobile section switcher with only active-section pages, clearer workflow labels and no duplicate modes entry, compact footer pagination and explicit source link. Workflow recap is a comparison table; rhythm descriptions use headings. Shared configuration snippet was mislabeled JavaScript; now validated JSON with collapsed preview/download everywhere included. Train/evaluate/export diagrams use readable vertical flows. Added browser regressions for mobile section switching and configuration expansion/downloads.
-
-Published-site audit: all 190 original sitemap routes now resolve; added 19 missing legacy redirects (API summary and standalone snippets). Checked 50 authored content tables and 348 public API names with no missing content. Original assets page was also empty; docstrings now explain bundled noise resources. Legacy route fixture guards URL coverage. See MIGRATION.md for evidence and review limits.
-
-## Review and release status
-
-Two independent content and delivery reviews completed. Fixed BYOT introduction loss from badge-cell skipping and preserved query/fragment on legacy redirects. Added two notebook regression tests and an eighth browser test. Delivery reviewer rechecked redirect security and JavaScript-disabled fallback; no remaining findings. Python behavior is unchanged; Ruff 0.11.12 passed.
-
-Shared UI #185 and release PR #186 are merged. Publication workflow 36793695398 passed; v0.1.0-alpha.22 points to a62e8d45505dd3bbcdf1c4a03dfd1ec863322ecf. heartKIT package.json and regenerated lockfile pin that exact released commit. This replaces the temporary local preview package. Compact terminals within tabs retain copy controls without redundant headers.
-
-Clean npm ci, Astro check, build, output checks and all eight browser tests pass on alpha.22. Rendered installation panel inspected; screenshot /tmp/heartkit-alpha22-terminal.png. CI on the dependency update is the remaining qualification step before final user merge approval.
-
-## Next steps and limits
-
-Push the dependency update and verify GitHub CI, then request final owner approval for heartKIT #44. Do not merge heartKIT without approval. Keep package release workflows unchanged. Other product consistency PRs follow heartKIT landing. Runtime updates, model refreshes and Hugging Face deployment are separate follow-ups. External links, runtime examples, dataset access, historical metrics and training were not revalidated. See astro-site/MIGRATION.md and README.md for coverage and commands.
+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.

astro-site/MIGRATION.md

@@ -33,3 +33,7 @@ Inspected original-site screenshots for the homepage, assets API, guide index an
 Content review identified two migration regressions: removing a Colab toolbar discarded BYOT prose in the same cell, and static redirects discarded API symbol fragments. The renderer now removes only toolbar markup; redirects preserve query strings and fragments with a meta-refresh fallback when JavaScript is disabled. Both changes have regression coverage. Delivery review checked Pages permissions and triggers, shared section matching, notebook assets, public API coverage and Python AST parity. No additional blocking findings remained after fix review.
 
 Dependency qualification: shared UI alpha.21 is pinned by immutable commit `6cdbea0c594c955e6aeef232af1fbb15e395ab2d` (AmbiqAI/helia-ui#183 and #184). Clean installation, type checks, build, output checks and all eight browser tests pass with this dependency.
+
+## 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 @@
 # heartKIT documentation
 
-Astro/Starlight renders Markdown from `../docs`, five saved notebooks and a static Griffe Python API reference. Runtime training dependencies are not imported. Private implementation modules are excluded before rendering.
+Astro/Starlight renders Markdown/MDX from `src/content/docs/`, five saved notebooks and a static Griffe Python API reference. Runtime training dependencies are not imported. Private implementation modules are excluded before rendering.
 
 Use Node24, Python3.12 and uv. From this directory:
 
@@ -14,8 +14,10 @@ npm run check:output
 npm test
 ```
 
-Edit source Markdown, notebook sources or owning scripts. `src/content/docs`, `src/data`, `public`, `.cache` and `dist` are generated. Existing navigation labels come from `mkdocs.yml`; `src/navigation.mjs` assigns public pages to five scoped sections.
+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 five notebook pairs in `docs/guides` and `notebooks` were identical at migration. Documentation copies supply the rendered pages and byte-identical downloads. Saved outputs include 18 PNG figures, logs and plain-text fallbacks for rich HTML. No notebook execution occurs during builds. Notebook timestamps and measurements are historical, not current model qualification.
+`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 five notebooks in `notebooks/` supply rendered pages and byte-identical downloads. Duplicate documentation copies have been removed. Saved outputs include 18 PNG figures, logs and plain-text fallbacks for rich HTML. No notebook execution occurs during builds. Notebook timestamps and measurements are historical, not current model qualification.
 
 PRs build and test the site. Main pushes and manual main dispatches publish Pages independently of package releases. Package release workflows are unchanged.

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/test-build-notebooks.py && node --test scripts/normalize-markdown.test.mjs && node scripts/check-output.mjs",
+    "check:output": "node --test scripts/canonical-content.test.mjs && python3 scripts/test-build-notebooks.py && node scripts/check-output.mjs",
     "test": "playwright test"
   },
   "dependencies": {