Bullet Heaven — Documentation Site Design

Bullet Heaven — Documentation Site Design

Problem

Chris keeps losing agent-produced research (most recently a Nova Drift / bullet-heaven genre-mechanics investigation) because it only ever lands in a conversation transcript or gets compressed into a short auto-memory index pointer — neither is a durable, git-tracked record. Separately, this project’s documentation already exists but is scattered: CLAUDE.md (condensed status + a table of pointers), docs/architecture/*.md, docs/godot-gotchas.md, docs/ROADMAP.md, docs/ideas/*.md, docs/superpowers/*.md (brainstorming specs/plans), top-level DESIGN.md/PRODUCT.md, and NEXT_TASKS.md. There’s no single place that’s easy for a human to browse, and no established convention for where research output goes.

Goals

• A durable, git-tracked home for future research/investigation output — the direct fix for “research keeps getting lost.”
• One browsable site (sidebar nav + full-text search) surfacing all existing documentation without duplicating it.
• Zero dual-source-of-truth risk — reuse the symlink pattern this repo already trusts (the tvOS platform fold: gameplay dirs symlinked into platform/tvos/, never copied).
• Deployed to Cloudflare Pages so viewing it doesn’t require a locally-running dev server.

Non-goals (v1)

• An auto-generated weapon/upgrade/enemy data catalog sourced live from data/bible.json. Genuinely useful, but a distinct, larger piece of work — deferred to its own follow-up spec.
• Access control / login gate — not needed per Chris (not sensitive enough at this stage).
• Replacing tools/design-bible/ (the interactive balance-editing tool over bible.json). It stays exactly as-is; the new site is a read-only reference and links out to it.
• Versioning, i18n, multi-audience concerns — single project, effectively two readers (Chris and Claude), no need for either.

Platform choice: Astro Starlight

Confirmed current via web search (2026): actively maintained, 8,400+ GitHub stars and climbing, filesystem-derived sidebar navigation, built-in full-text search (Pagefind), zero client-side JS by default, Markdown/MDX content. Chris already knows Astro (it’s his default web stack), so this reuses existing knowledge and tooling rather than introducing a new ecosystem.

Rejected alternatives:

• Material for MkDocs / Zensical — Python-based, simple, but MkDocs 1.x is now unmaintained and 2.0 is still pre-release as of 2026 — bad timing for a new dependency.
• Docusaurus — React-based; bundles a React runtime and ships versioning/i18n features this single-project, single-audience reference site doesn’t need.

Structure

A new docs-site/ directory at the repo root, with its own package.json — the same self-contained-tool convention already used by tools/design-bible/. Scaffolded via the current Astro Starlight starter template.

Its content directory (docs-site/src/content/docs/) is populated almost entirely by symlinks back to existing files, never copies:

Site section	Symlinked from
Architecture	docs/architecture/*.md, docs/godot-gotchas.md
Roadmap & Ideas	docs/ROADMAP.md, docs/ideas/*.md
Specs & Plans	docs/superpowers/*.md, docs/superpowers/specs/*.md, docs/superpowers/plans/*.md — 70+ files today, includes future brainstorming/writing-plans output
Design & Product	DESIGN.md, PRODUCT.md
Housekeeping	NEXT_TASKS.md
Research	docs/research/ (see below)

The homepage is a thin, hand-written landing page (not a symlink) — CLAUDE.md lacks the frontmatter Starlight requires, so the homepage instead summarizes/links to it rather than trying to render it directly.

The “Game Bible” (weapons/upgrades/how-things-work) section for v1 is just the existing docs/architecture/weapons-and-buildcraft.md, symlinked in under Architecture — it already documents how the systems work. The auto-generated concrete-numbers catalog from data/bible.json is explicitly deferred (see Non-goals).

New durable research convention

A new real (non-symlinked) directory, docs/research/, holds one markdown file per investigation, named YYYY-MM-DD-<topic>.md. This is the actual fix for the stated problem: going forward, any substantial multi-source research/investigation output gets written here as a durable file — not left only in conversation or squeezed into a short memory-index pointer. The auto-memory system continues to hold short session-continuity pointers only; anything substantial gets a durable git-tracked file, which the site then surfaces automatically since docs/research/ is symlinked into the site’s content tree.

CLAUDE.md’s on-demand docs table gets one line added pointing at this convention.

The first entry, docs/research/2026-07-04-bullet-heaven-genre-mechanics-survey.md (Nova Drift and seven peer bullet-heaven games), is written as part of this same change, ahead of the rest of the site scaffold, given the explicit urgency behind this request.

Deployment

• New Cloudflare Pages project, GitHub auto-deploy, project root docs-site/, build command astro build, output directory dist/.
• Chris’s own Cloudflare account (standing convention for every project).
• No CF Access gate (per decision — not sensitive enough to bother with).
• No GitHub Actions layered on top — CF Pages’ own build pipeline is sufficient, per this project’s standing CF-Pages-only rule for static sites.

Verification

• npm run build (i.e. astro build) succeeds locally before the first deploy.
• Every symlink resolves — find docs-site/src/content/docs -xtype l prints nothing (a broken symlink would silently drop a doc from the site with no build error).
• astro dev locally: sidebar renders all six sections; Pagefind search returns a hit for a known term (e.g. “elemental reaction”).
• CF Pages deploy succeeds and the live URL loads with working navigation and search.

Explicit follow-ups (not in this spec)

• Auto-generated weapon/upgrade/enemy catalog page sourced directly from data/bible.json (own spec, own plan).
• A light theming pass to match the neon-cyan accent from DESIGN.md (cosmetic, optional, not required for the site to be useful).