feat(site): GitHub Pages — cosmic-green landing + MkDocs Material docs

[ancongui]

What

A public GitHub Pages site for PyFly, in two parts:

1. Landing page (web/) — a hand-crafted, brand-matched single page in the cosmic-green firefly identity: animated firefly hero, an at-a-glance stats band, a tabbed pre-highlighted code panel (DI · CQRS · Saga), the four philosophy pillars, the existing architecture / hexagonal / auto-config / distributed-patterns / ecosystem brand diagrams, a 39-module layered grid, the 4-step quickstart, a PyFly by Example book callout, and a footer. Self-contained, relative URLs, prefers-reduced-motion aware.
2. Docs site (mkdocs.yml + overrides/ + docs/stylesheets/pyfly.css + docs/assets/pyfly-mark.svg) — MkDocs + Material rendering the existing docs/*.md with a layered nav over 43 module + 10 adapter pages, a cosmic-green palette, Maven Pro headings, dark mode, and client-side search. The docs logo links back to the landing page.

Both are assembled into _site/ by scripts/build_site.py — the single source of truth used identically locally and in CI — and deployed by .github/workflows/pages.yml.

URL & base path

Served at https://fireflyframework.github.io/fireflyframework-pyfly/ (docs at …/docs/). The landing page uses relative URLs and the docs config is base-path-aware, so repointing at pyfly.io later is a CNAME + two config values.

The install command uses the GitHub raw install.sh URL (not get.pyfly.io).

⚠️ One-time step to go live

Settings → Pages → Source: GitHub Actions. After that, merging to main deploys automatically (the workflow triggers on push to main and on manual dispatch). Pushing this branch does not deploy.

Preview locally

pip install -r requirements-docs.txt
python scripts/build_site.py
python -m http.server -d _site 8000   # → http://localhost:8000/

Verification

• build_site.py builds cleanly (docs compile in ~2.5s); every landing → docs link target resolves under use_directory_urls.
• Rendered in a browser: hero, stats band, Why cards, and code panel confirmed; docs theme confirmed (deep-green header #1f5e16, Maven Pro headings, firefly logo linking home, working search). No console errors.
• All landing copy fact-checked against README / book.yaml / CHANGELOG / pyproject.toml / samples/lumen — version, "18 chapters in five parts", Lumen wallet & ledger, 39 modules across 5 layers, the six patterns, code samples, CLI archetypes/commands, and the ecosystem family all verified accurate.

Notes / possible follow-ups

• The MkDocs build logs a few pre-existing in-doc anchor-link warnings (non-fatal; not introduced here).
• docs/superpowers/ and the duplicate docs/README.md are excluded from the public docs.
• Could later optimize the 441 KB pyfly-logo.png used for OG/social.