How these docs work

This is a Starlight (Astro) documentation site — a traditional, scalable docs UI (sidebar tree, on-page table of contents, offline search, cross-links) for the written documentation, themed to the LumicIQ brand. It complements the standalone decks (pitch, cost, interactive diagrams), which stay as self-contained HTML and are linked from the sidebar.

Authoring a page

1. Add a Markdown (.md) or MDX (.mdx) file under src/content/docs/. The folder structure maps to URLs (architecture/overview.md → /architecture/overview/).
2. Every page needs frontmatter:

   ---
   title: My page
   description: One line for search + social.
   ---

3. Add it to the sidebar in astro.config.mjs (or use autogenerate for a whole folder).
4. Commit + push — Cloudflare Pages rebuilds and redeploys.

What you get for free

• Sidebar navigation + on-page table of contents + prev/next links.
• Offline search (Pagefind) — fully client-side, so it works behind the Cloudflare Access login with no external crawler. Press / to search.
• Light / dark themes (LumicIQ-warm), responsive, accessible.
• Components via MDX — callouts, cards, tabs, code blocks with syntax highlighting:

  Tip

  Use callouts (:::note, :::tip, :::caution, :::danger) to highlight things.

Linking the interactive decks

Each deck lives in public/ as <name>/index.html, so it serves at a clean directory URL. Link them from any page or the sidebar, e.g. the architecture flow or the cost model. Keep building those as self-contained HTML with the shared tokens.css — they don’t need the docs framework.

Build & deploy

• Local authoring: npm install then npm run dev (hot-reload). To click through the decks, use npm run preview — the dev server doesn’t serve directory-index files from public/.
• Production: npm run build → static output in dist/ → Cloudflare Pages, behind the same Cloudflare Access policy that gates @lumiciq.com.