feat(docs): seed Docusaurus site at /site, deploy to docs.fallout.build via Cloudflare Pages (#41)

[ChrisonSimtian]

Summary

Phase 1 of the documentation site migration (#41). Stands up Docusaurus 3.10 in /site/, reading from the existing ../docs/ tree (single source of truth, no fork). Deploys to docs.fallout.build via Cloudflare Pages.

What's in this PR

Area	Change
/site/	Docusaurus 3.10 scaffold (TypeScript). path: '../docs', routeBasePath: '/docs', url: 'https://docs.fallout.build'. Drops the placeholder blog.
/site/src/theme/MDXComponents.tsx	Globally registers Tabs, TabItem, CodeBlock, Admonition — same pattern as NUKE's site, so docs don't need new imports.
/site/src/components/	Stubs for AsciinemaPlayer, DownloadButton, ControlKey, ToolConfirmation (referenced by existing docs). Functional, not polished.
.github/workflows/docs-deploy.yml	Build /site + push to Cloudflare Pages via cloudflare/wrangler-action@v3. Triggers on push to main when site/** or docs/** change.
.gitignore	Excludes site/node_modules, site/build, site/.docusaurus.
docs/ (8 files)	HTML comments → MDX comments (<!-- --> → {/* */}) and two {#anchor} IDs removed from introduction.md. Pure parser-compat changes; no rendered output changes.

Why Cloudflare Pages, not GitHub Pages

GitHub Pages allows one site per repo, and fallout.build (apex) already serves from gh-pages on this repo. Cloudflare Pages handles docs.fallout.build via a CNAME on the fallout.build DNS pointing to the Pages project. Apex stays untouched.

CD POC framing

The deploy step (wrangler pages deploy site/build) is the v13 CD reference shape — build artifact, authenticated push to an external system's API. Exactly what ADR-0001's tasks → REST pattern targets. Kept minimal so it lifts cleanly into a Fallout primitive later ([CloudflarePagesDeploy] attribute, CloudflarePagesTasks.DeployPages(...)).

Manual setup needed before the workflow can deploy

1. Cloudflare Pages project named fallout-docs (one-time, Cloudflare dashboard).
2. Repo secrets:
   • CLOUDFLARE_API_TOKEN (scope: Pages:Edit)
   • CLOUDFLARE_ACCOUNT_ID
3. DNS on fallout.build: CNAME docs → fallout-docs.pages.dev.
4. Custom domain on Cloudflare Pages project → add docs.fallout.build.

The workflow merges and runs immediately; first run will fail at the deploy step until 1+2 are done. That's fine — the site can be merged and the secrets added afterwards without rebasing.

What's deferred to follow-up PRs

• Broken-link cleanup. onBrokenLinks: 'warn' (not 'throw') so CI passes. Many internal links use the source path (/docs/01-getting-started/01-installation) but Docusaurus serves the stripped path (/docs/getting-started/installation). Content-touch only.
• Algolia DocSearch wiring (apply for OSS plan first).
• Custom favicon / logo / OG image (placeholder retained).
• Per-PR preview deploys (Cloudflare Pages supports it; needs wrangler-action invoked on pull_request with preview branch arg).
• AsciinemaPlayer wired to actual asciinema-player (cast files need to live somewhere accessible first).

Test plan

• cd site && npm install && npm run build succeeds locally (42 HTML files generated).
• Build output includes index.html, 404.html, docs/*, sitemap.xml.
• After Cloudflare project + secrets are set up, push to this branch and confirm wrangler pages deploy succeeds.
• After merge, confirm production deploy lands at https://docs.fallout.build.

Refs

• [P7] Documentation site migration #41 (P7 — Documentation site migration)
• ADR-0001 (CD primitives — this deploy is the v13 reference shape)
• v11 milestone (rebrand-completion track)

🤖 Generated with Claude Code

[ChrisonSimtian]

Closing — wrong architecture.

I assumed Cloudflare Pages would host the docs subdomain. The maintainer clarified that Cloudflare is DNS-only (wildcard `*.fallout.build` → GitHub Pages), and the GH Pages slot on this repo is taken by the apex. So a sibling `docs.fallout.build` site can't share this repo's GH Pages.

Decision: docs site moves to a new `Falloutdocs` repo with its own GH Pages and `docs.fallout.build` as custom domain. Markdown source stays in this repo's `docs/` folder; Falloutdocs's deploy workflow checks out Fallout@main at build time.

What carries forward

• The MDX-compat fixes to 8 docs/ files (HTML → MDX comments, 2 anchor removals in `introduction.md`) — opening as a separate small PR against this repo since the new Falloutdocs builds depend on them.
• The /site/ scaffold + component stubs + global MDXComponents — moving to the Falloutdocs repo.
• The docs-deploy workflow — being rewritten for the new repo (GH Pages target, not Cloudflare Pages).

Tracking under #41 still.