docs(site): MkDocs Material documentation site for GitHub Pages

[hideyukiMORI]

Summary

Stands up a browsable, searchable documentation site (MkDocs Material) for publishing to GitHub Pages at docs.nene-php.com. Directly targets the #1 gap named in docs/publication-strategy.md — "The main gap is not implementation depth. The main gap is discovery." — by surfacing the ~80 how-to guides that currently only exist as raw .md in docs/development/.

nene-php.com stays the live demo app; the docs site is a separate subdomain.

What's included

• mkdocs.yml — Material theme (light/dark toggle, search, code copy, GitHub edit links), docs/ as the source.
• Curated nav via awesome-pages (docs/.pages): Home → Overview → Getting Started → How-to Guides. Unlisted pages (ADR, roadmap, field-trials, …) are still built so cross-links keep resolving — they're just omitted from the navigation (validation.nav.omitted_files: ignore).
• docs/index.md — a landing page with cards. The in-repo docs/README.md is excluded from the build to avoid an index/README URL collision (nothing links to the top-level README).
• docs/CNAME — docs.nene-php.com.
• .github/workflows/docs.yml — builds on PR (validation only) and on push to main, deploys to Pages via actions/deploy-pages on main only.
• requirements-docs.txt — mkdocs-material, mkdocs-awesome-pages-plugin.

Scope (as agreed)

How-to guides (docs/development) + tutorial (building-a-service) + overview (project.md). Easy to widen later (deployment/api/frontend) by editing docs/.pages.

Manual steps after merge (owner)

1. Settings → Pages → Source: GitHub Actions (enables the deploy).
2. DNS: add CNAME docs.nene-php.com → hideyukimori.github.io.

Until step 1, the build job passes but deploy has nothing to publish to.

Test plan

• YAML syntax validated locally (mkdocs.yml, workflow, all .pages).
• CI build job on this PR confirms mkdocs build succeeds (couldn't run mkdocs in the dev sandbox — no pip).
• Post-merge: site renders at the Pages URL, then at docs.nene-php.com once DNS propagates.

Note: the two file pairs I earlier flagged as possible duplicates (cors.md/cors-and-csrf.md, invitation-token.md/invitation-tokens.md) turned out to be distinct (class guide vs. concept/pattern guide) — no cleanup needed.

🤖 Generated with Claude Code