docs: migrate heartKIT to Astro and shared HELIA navigation

.github/workflows/docs.yaml

@@ -1,60 +1,69 @@
-name: Deploy to GitHub Pages
+name: Documentation
 
 on:
-  release:
-    types:
-      - created
+  pull_request:
+  push:
+    branches: [main]
   workflow_dispatch:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
-# Default to bash
-defaults:
-  run:
-    shell: bash
+  group: docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
-  # Build job
   build:
+    name: Build and verify docs
     runs-on: ubuntu-latest
-
+    defaults:
+      run:
+        working-directory: astro-site
     steps:
-      - name: Checkout 🛎️
-        uses: actions/checkout@v4
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v4
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: astro-site/package-lock.json
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v6
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm run check
+      - run: npm run build
+      - run: npm run check:output
+      - run: npm test
+      - uses: actions/upload-artifact@v4
+        if: always()
         with:
-            enable-cache: true
-      - name: Install and Build 🔧
-        env:
-          CI: ""
-          PUBLIC_URL: "${{ steps.pages.outputs.base_url }}/"
-        run: |
-          uv sync --only-group docs
-          uv run mkdocs build
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+          name: docs-preview
+          path: |
+            astro-site/dist
+            astro-site/test-results
+      - uses: actions/upload-pages-artifact@v3
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
         with:
-          path: ./site
+          path: astro-site/dist
 
-  # Deployment job
   deploy:
+    name: Publish docs
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     steps:
-      - name: Deploy to Pages 🚀
+      - uses: actions/configure-pages@v5
+      - uses: actions/deploy-pages@v4
         id: deployment
-        uses: actions/deploy-pages@v4

.gitignore

@@ -182,3 +182,12 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+
+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/

AGENTS.md

@@ -2,6 +2,8 @@
 
 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 MkDocs Material; preview with `mkdocs serve` and keep headings plain Markdown (no span wrappers).
+- Docs use Astro/Starlight in `astro-site/`, generated from Markdown under `docs/`, saved notebooks and Python docstrings. Edit sources rather than generated content.
+- 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.
 - Commit messages follow Conventional Commits (e.g., `feat: ...`, `fix: ...`, `chore: ...`).

HANDOFF.md

@@ -0,0 +1,45 @@
+# heartKIT Astro migration
+
+## Goal and scope
+
+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.
+
+## References
+
+- 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.

astro-site/.nvmrc

@@ -0,0 +1 @@
+24

astro-site/MIGRATION.md

@@ -0,0 +1,35 @@
+# heartKIT migration
+
+Tracking: AmbiqAI/heartkit#43. Baseline 64cd51b (1.8.0).
+
+## Coverage
+
+44 standalone authored Markdown pages, five notebook pages and 122 public Python API modules (161 catalog entries). Markdown fragments under assets are included in pages. Five notebook pairs are identical; original files remain unchanged. All 18 saved PNG figures are rendered and downloads are byte-identical. Rich HTML outputs use plain-text fallbacks. No training or hardware checks performed.
+
+## Repairs
+
+Reused sleepKIT conversion fixes for tabs, Material callouts, tables, image dimensions, icon shortcodes and large configuration previews/downloads. Restored missing task model-zoo snippets from the existing model-zoo overview without changing reported values. Fixed the malformed architecture fragment and labeled commented class maps as JSONC. Repaired two unterminated docstring fences, a plotting example typo and a Material example wrapper. Corrected an inherited beat model-zoo link and Python requirement wording. No runtime behavior changed.
+
+Landing uses heartKIT branding and a version from pyproject.toml, with scoped navigation and the shared heliaEDGE/heartKIT red accent. Installation includes uv, uvx, pipx, pip and Git. Task recap tabs became a comparison table, and obsolete code annotation markers were removed. Private implementation modules do not generate pages, catalog rows, search entries or machine-readable exports. Historical public API and notebook URLs redirect to their new pages.
+
+## Validation
+
+Production build, internal links across 334 HTML documents, four converter tests, two notebook regression tests and eight browser tests pass. Astro check reports zero errors/warnings. All 49 authored/notebook pages loaded at 1440px and 390px without viewport overflow or broken images. Landing, Quickstart and notebook screenshots inspected. Broader example runtime correctness, external links, dataset access and historical metrics have not been revalidated.
+
+## Delivery
+
+PR preparation is approved. Merge and production deployment await user approval. The Pages workflow is independent of package publishing.
+
+## Published-site comparison
+
+Compared the published MkDocs sitemap and downloaded HTML with the Astro output. All 190 original URLs have a page or redirect, enforced by `scripts/legacy-routes.json`. This includes the API summary and 18 standalone snippet URLs previously published by MkDocs. Snippet URLs lead to the pages that include their content; the diagnostic results snippet had only an empty table header and redirects to the diagnostic overview.
+
+Checked the 50 non-code tables in authored pages for retained cell content, and 348 distinct public API headings for retained names. No missing table content or public API names found. Five notebook sources and their 18 saved PNG figures are preserved. The duplicate homepage logo images were intentionally replaced by the approved hero.
+
+Inspected original-site screenshots for the homepage, assets API, guide index and a model-zoo page, plus corresponding local content. The original assets API was also an empty heading; package docstrings now explain the bundled noise resources and the NstdbNoise interface. This is route/content parity and representative visual review, not exhaustive visual review of every page or runtime verification of the examples. Interactive Plotly signal plots remain; rich notebook HTML outputs use plain-text fallbacks.
+
+## Independent reviews
+
+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.

astro-site/README.md

@@ -0,0 +1,21 @@
+# 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.
+
+Use Node24, Python3.12 and uv. From this directory:
+
+```sh
+npm ci
+npx playwright install chromium
+npm run dev -- --port 8779
+npm run check
+npm run build
+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.
+
+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.
+
+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/astro.config.mjs

@@ -0,0 +1,84 @@
+import { defineConfig } from "astro/config";
+import { unified } from "@astrojs/markdown-remark";
+import starlight from "@astrojs/starlight";
+import react from "@astrojs/react";
+import { heliaStarlight } from "@ambiqai/helia-ui/starlight";
+import rehypeMermaid from "rehype-mermaid";
+import remarkMath from "remark-math";
+import rehypeKatex from "rehype-katex";
+import redirects from "./src/data/redirects.json" with { type: "json" };
+import { sections } from "./src/navigation.mjs";
+import { fileURLToPath } from "node:url";
+export default defineConfig({
+  vite: {
+    plugins: [
+      {
+        name: "heartkit-section-membership",
+        enforce: "pre",
+        resolveId(source, importer) {
+          // Historical page URLs do not share the section's URL prefix.
+          if (
+            source === "./sections" &&
+            importer?.includes("/@ambiqai/helia-ui/starlight/")
+          )
+            return fileURLToPath(
+              new URL("./src/section-matcher.ts", import.meta.url),
+            );
+        },
+      },
+    ],
+  },
+  site: "https://ambiqai.github.io",
+  base: "/heartkit",
+  redirects: {
+    ...redirects,
+    "/api": "/heartkit/reference/",
+  },
+  markdown: {
+    processor: unified({
+      remarkPlugins: [remarkMath],
+      rehypePlugins: [rehypeKatex, [rehypeMermaid, { strategy: "inline-svg" }]],
+    }),
+  },
+  integrations: [
+    react(),
+    starlight({
+      components: { Hero: "./src/components/HomeHero.astro" },
+      title: "heartKIT",
+      description: "AI development kit for heart monitoring on Ambiq devices.",
+      favicon: "/assets/favicon.png",
+      customCss: [
+        "./src/styles/site.css",
+        "@ambiqai/helia-ui/mermaid.css",
+        "katex/dist/katex.min.css",
+      ],
+      plugins: [
+        heliaStarlight({
+          accent: "kit-heart",
+          sections,
+          sidebar: "always",
+          header: {
+            title: "heartKIT",
+            hub: {
+              label: "HELIA",
+              href: "https://ambiqai.github.io/helia-developer-hub/",
+            },
+          },
+          discoverability: {
+            markdown: true,
+            llms: true,
+            jsonLd: true,
+            ogImage: true,
+          },
+          footer: {
+            logo: "ambiq",
+            tagline: "Part of the Ambiq HELIA AI platform",
+            links: [
+              { label: "heartKIT source on GitHub", href: "https://github.com/AmbiqAI/heartkit" },
+            ],
+          },
+        }),
+      ],
+    }),
+  ],
+});