ADR-0011: Repository-backed SvelteKit official site

Date: 2026-09-20 Status: Accepted; replaces the generated HTML portal strategy while preserving ADR-0007 documentation authority.

Context

The current GitHub Pages surface is a repository Markdown renderer with a bespoke HTML/CSS shell. The official Nexus Cerebri website now needs route-level interactive system explanations, responsive diagrams, depth-aware explanations, accessibility checks and deterministic core-derived demonstrations without turning the website into a second source of domain truth.

ADR-0007 makes repository Markdown canonical. ADR-0010 keeps Cerebri Lab a separate typed development client and prohibits frontend planning logic.

Decision

Create apps/cerebri-site with SvelteKit, Svelte 5 and TypeScript. Use the static adapter, prerender every public route, emit the deployment into the existing root site/ output, and support the /Nexus-Cerebri GitHub Pages base path.

Repository Markdown, Cargo metadata, the current Master specification, CPIR fixtures, roadmap/ADRs and Rust core outputs remain authoritative. A build-time generator reads those sources and creates typed website data. Planner and temporal demonstrations are generated by Rust examples calling cerebri-core; TypeScript never reimplements planning or temporal semantics.

The public site has three explanation depths (Understand, Technical, Research), labels significant visualizations as REAL, EDUCATIONAL or FUTURE CONCEPT, and exposes source anchors back to repository authority. Documentation pages render canonical Markdown at build time rather than introducing a CMS or runtime GitHub dependency.

Cerebri Lab remains independently packaged under apps/cerebri-lab. The official site's /lab route explains and links to that developer surface; it does not absorb Lab behavior.

Alternatives

Extending the static HTML generator would keep a small toolchain but makes typed interaction, route composition and browser testing increasingly bespoke. Reusing the Lab as the public website would mix developer inspection with public communication. A CMS or duplicated MDX corpus would violate repository-native documentation authority.

Consequences

Node dependencies increase and the Pages build also needs the pinned Rust toolchain to produce real core fixtures. The site can remain fully static at runtime. Build failures surface drift between website claims and repository truth. The old portal generator and presentation files become obsolete.

Migration / Compatibility

The deployment artifact remains site/ and npm run docs:build remains the canonical public-site build command. Existing Markdown files and their authority do not move. Public route URLs are new and use trailing slashes for static-host compatibility. Historic generated .html documentation URLs are not a normative interface.

References

ADR-0007 · ADR-0010 · Master · Documentation/release standard