docs: migrate compressionKIT to Astro and shared helia-ui #68

Goal

Migrate compressionKIT from Zensical to Astro/Starlight with the released helia-ui components, following the sleepKIT and heartKIT migrations. Keep the product's teal/gold identity and give a new customer a clear path from understanding signal compression to trying a codec, evaluating it, and integrating a deploy package.

This is a proposed implementation plan. No migration code or deployment is included in this issue.

Findings and baseline

Inspected main at 69b94d836dd8a24f227d411e99ef4ff2a7de2b7d and the published site's navigation/content.

• zensical.toml configures seven top-level areas, nested experiment families, Python API directives, KaTeX, tabs, admonitions, icons, and custom styling.
• docs/ contains 72 Markdown files. docs/experiments/ contains 38, including its index. Inventory files independently of navigation so unlisted content is not silently lost.
• Three notebooks exist in examples/; docs/examples.md links only the first two. The ECG quickstart needs an explicit disposition.
• scripts/render_experiment_docs.py owns generated experiment pages. Preserve generation from the registry rather than hand-editing copied output.
• API pages use mkdocstrings directives. They need real generated API content, not literal directives or empty package landing pages.
• Existing branding uses teal and gold/yellow, with separate light/dark colors.
• Pages deployment currently builds Zensical via .github/workflows/deploy-pages.yml.

Sources: site, site configuration, docs, notebooks, experiment generator.

Proposed information architecture

Five major sections, with a mobile section dropdown and a sidebar limited to the selected section:

1. Home: concise introduction, large product name, outlined toolkit-version badge, Get started / Explore examples, and a small capability visual. Explain PPG/ECG support and extension paths without claiming future modalities are shipped.
2. Getting started: supported installation, first codec round trip, example guides/notebooks, data setup, and links to the Developer Hub demo.
3. User guide: signal preparation, compression methods, fidelity/scorecards, evaluation, deployment, reproduction, and codec extension.
4. Models & experiments: model inventory and evidence plus a browsable experiment catalog by modality/family/ratio. Avoid putting every experiment in the top navbar.
5. Reference: public Python API, CLI, configuration, artifact contract, compatibility, and licensing.

Finalize labels and page placement after the inventory. Keep stable URLs where practical and provide tested redirects for moved pages.

Implementation stages

1. Inventory and public-content audit

• Create a source-to-destination manifest covering all authored/generated pages, assets, downloads, notebooks, and known published URLs/anchors.
• Mark each item migrated, redirected, consolidated, or intentionally excluded with a reason.
• Classify roadmap, evaluation-plan, research, and internal material before publishing. Keep public extension guidance, but exclude internal-only modules and operational notes from navigation, search, generated API, and machine-readable exports.
• Capture representative original-site screenshots and check actual rendered content as the comparison baseline.

2. Shared site and navigation

• Add an isolated Astro site using a verified immutable released helia-ui dependency, at least the mobile-section and compact-tab-terminal capability shipped in alpha.22. Do not patch installed dependencies.
• Apply teal/gold tokens with accessible contrast in both themes, a black hero, clear product introduction, compact pagination, and descriptive footer links.
• Use section-scoped sidebars on desktop/mobile. Test keyboard navigation, dropdown dismissal/focus, selected section, and sidebar refresh.

3. Content, API, and generated evidence

• Convert tabs, details/admonitions, tables, image attributes, math, code annotations, and links. Remove unsupported decorative icon syntax rather than leaking raw font-icon tokens.
• Replace low-value recap tabs with readable lists/cards/tables. Keep useful installation tabs with headerless terminal frames, copy buttons, and no fake progress output.
• Use correctly labeled code fences and collapsed long configuration examples with useful previews. Keep diagrams legible at mobile widths.
• Preserve existing plots and light/dark variants. Prefer static SVG/images for simple charts; audit embedded interactive outputs before bringing heavy chart runtimes into the site.
• Generate public Python API with supported tooling and an explicit public-surface allowlist. Preserve signatures, descriptions, parameters, returns, and links; prevent empty/internal-only pages.
• Adapt experiment/evidence generators and add drift checks. A clean docs build must not require private datasets, local results/ directories, training, credentials, or unpublished weights. Use versioned committed evidence where appropriate and clearly label unavailable evidence.
• Preserve the distinction between toolkit version, bundle version, published assets, reproducible local experiments, and research candidates.

4. Notebook and example parity

• Audit all three existing notebooks, their history, relative root paths, outputs, dependencies, data provenance, and linked codec versions.
• Generate readable documentation guides from a single canonical source; keep runnable downloads/links where appropriate. Avoid a second manually maintained notebook copy.
• Explicitly resolve the existing repository guidance against adding notebooks versus the three already documented examples. This migration should not add notebook-only business logic.
• Verify examples with synthetic or otherwise permitted fixtures; record execution coverage and any unavailable artifact/dependency rather than claiming notebooks passed from rendering alone.

5. Validation, review, and cutover

• Run clean install, build/type checks, API/CLI reference checks, content-manifest parity, link/redirect checks, and generated-output drift checks.
• Browser-check every authored page and generated page template, plus automated route coverage for the full site. Include narrow mobile/tablet/desktop, light/dark themes, search, tables, diagrams, terminals, downloadable notebooks, keyboard interaction, and overflow.
• Obtain two independent reviews focused on content/API parity and delivery/accessibility. Request the repository-required Copilot review; resolve findings and achieve green CI.
• Keep the existing published site until approval. Publish the tested artifact with the existing /compressionkit/ base path, retain a documented rollback path, and verify production URLs and rendered pages after deployment.

Related work and boundaries

• Product readiness follow-up from AITG portfolio audit #66 owns package naming/publication, versioning, licensing, provenance, and readiness. Docs must use verified install commands; do not copy the old pip install compressionkit instructions blindly or imply the proposed compression-kit distribution is already published. Source installation is acceptable until publication is verified.
• Retire the dev-site PPG codec demo page in favour of the Developer Hub #67 owns retiring the duplicate PPG demo narrative. Coordinate its redirect/pointer with this migration and link to the verified Developer Hub destination.
• Publish multi-precision RVQ encoder release assets #64 and PR feat: publish multi-precision RVQ encoders #65 concern multi-precision release assets. Reflect only verified published artifacts; migration does not publish/retrain models or change runtime behavior.
• Changes to training, compression algorithms, model refreshes, HF publication, or readiness claims are outside this issue. Do not change release facts just to make migrated pages appear complete.
• Follow repository container guidance for Python execution. Static documentation inspection does not constitute runtime or hardware validation.

Completion criteria

Every baseline page, asset, and notebook has a recorded disposition; all public routes resolve or redirect intentionally; no raw migration syntax or empty API pages remain; the new navigation and compact terminals work across viewport sizes; evidence and licensing boundaries remain intact; independent findings are resolved; CI is green; and the approved deployment is verified on the production site.