feat(docs-site): Lore documentation site on GitHub Pages [roadmap:v0.10.7]

[tcballard]

Summary

Implements rac/roadmaps/v0.10.x-guide/v0.10.7-docs-site.md.

Adds:

• A documentation website (MkDocs + Material) serving the existing nine docs/ pages with sidebar nav and search, plus a new landing page at the site root
• A GitHub Actions workflow that builds with mkdocs build --strict on every push to main and deploys to GitHub Pages via the official Pages actions
• A README reduced from 163 to 72 lines: the ADR-022 doorway, with depth content relocated to the landing page under the ADR-042 drift policy
• The governing corpus artifacts authored ahead of implementation: scoping design, four requirements, ADR-042, and the v0.10.7 roadmap item

Post-v0.11.0 reconciliation: main merged the portal-export release (#77) while this PR was open. This branch has merged origin/main; the README's new "Sharing the corpus (the Portal)" section relocates to the landing page under the same drift policy, the doorway's command block gains rac export, and the two affected requirement artifacts are amended to record exactly that (commit 148cda4). The lore-web surface is untouched, and its GATE-1 (nothing public before comms review) is respected: this site publishes only after the maintainer manually enables Pages.

Roadmap / ADR Trace

Roadmap:

• rac/roadmaps/v0.10.x-guide/v0.10.7-docs-site.md

Relevant ADRs:

• rac/decisions/adr-042-docs-site-hosting.md (new — hosting model + drift policy, answering ADR-022's external-hosting review trigger)
• rac/decisions/adr-022-documentation-boundaries.md (unchanged; its three layers stand)
• rac/decisions/adr-036-lore-product-identity.md (Lore leads on the landing page; docs keep the RAC voice)

Requirements (the specification for this PR):

• rac/requirements/rac-docs-site-platform.md
• rac/requirements/rac-docs-site-landing-page.md
• rac/requirements/rac-docs-site-publish-pipeline.md
• rac/requirements/rac-docs-site-readme-doorway.md

Scope

Included

• mkdocs.yml: Material theme, light/dark palettes, built-in search only, explicit nav in the approved site-map order, pinned site_url/repo_url
• docs/index.md: landing page — hero art (light/dark via Material's stock #only-light/#only-dark), tagline as H1, install, three doc links, then the README's relocated depth sections (including the v0.11.0 Portal section)
• docs/images/lore-header-{light,dark}.png: copies of the brand art so the build is self-contained under docs/
• .github/workflows/docs.yml: build + deploy, strict mode as the gate, least-privilege permissions
• README.md: doorway only; documentation links now point at the site; command block includes rac export
• .gitignore: site/ excluded (declared addition to the approved file list — it protects the "generated HTML is never committed" requirement)

Excluded

• Blog, versioned docs, analytics, custom domain, i18n — deferred in docs-site-scoping; no artifacts, no code
• Publishing rac/ corpus content on the site (ADR-022 boundary)
• Any rewrite of existing docs prose (see content-edit list below)
• The README's "90-second demo" placeholder link: removed and not added to the landing page — the scoping design says it returns when the demo exists
• lore-web/ and the portal-export code: untouched by this branch beyond the merge from main

Product / Architecture Decisions

• Versions pinned in the workflow install step (mkdocs==1.6.1, mkdocs-material==9.7.6) rather than a new requirements file, keeping to the approved file-level change list
• Hero light/dark switching uses Material's built-in #only-light/#only-dark image fragments — zero override files shipped
• "Get started" links sit directly after Install, before "What it is": the landing-page requirement's acceptance criterion orders sections REQ-004 → REQ-006, and the rendered fold measurement made that ordering necessary (see Verification)
• The three doc links render as one line, not a bulleted list with descriptions — required to land above the 800px fold; the requirement mandates three links, not a list
• Merge-conflict resolution kept main's CLAUDE.md series pointer (v0.11.x-portal current), with a note that v0.10.7 docs site is in flight on this PR

User-Facing Contract

• Site root: hero, tagline, install, Quickstart/MCP/CLI links above the fold at 1280×800; relocated README depth below (why-it-works, SDD comparison, trust, Portal, footer)
• /quickstart/, /mcp/, /cli/, /artifacts/, /relationships/, /repo-workflow/, /examples/, /ecosystem/, /testing/ — the nine pages, served unrewritten
• README: doorway contents only; all documentation links point at https://tcballard.github.io/requirements-as-code/
• CI: pushes to main build the site; any MkDocs warning (broken link/nav) fails the workflow and blocks deploy

Verification

Ran (re-run in full after merging origin/main)

mkdocs build --strict        # exit 0, no warnings
rac validate rac/            # PASS — 129 artifacts, 0 invalid
rac relationships rac/ --validate  # 383 checked, 0 issues
rac review rac/              # exit 0, no priority 1–2 findings
pytest                       # 1062 passed (includes main's v0.11.0 export tests)

Rendered verification used headless Chromium at a 1280×800 viewport against the built site.

Acceptance criteria — pass/fail

rac-docs-site-platform — 6/6 pass

• mkdocs build --strict exits 0, no warnings
• Sidebar lists the ten nav entries in REQ-002 order (rendered HTML inspected)
• Diff of the nine existing pages touches exactly the seven link lines (3 ecosystem, 1 mcp, 1 repo-workflow, 2 testing) and nothing else
• Search returns results for "validate" (24 index entries) and "MCP" (20 entries)
• Built site contains no page sourced outside docs/ (site output audited)
• Clean environment + pinned versions builds successfully (fresh venv, mkdocs==1.6.1, mkdocs-material==9.7.6)

rac-docs-site-landing-page — 6/6 pass

• Above the fold at 1280×800: hero bottom 320px, install command bottom 600px, third doc link bottom 753px — all < 800px (re-measured after the merge; light/dark screenshots shared with maintainer in session)
• Color-scheme toggle swaps header art (dark context: dark variant visible, light hidden — stock Material CSS, verified in built stylesheets)
• Section order matches REQ-004 → REQ-006 → REQ-007 (REQ-007 as amended now includes the Portal section before the footer); no extra sections
• Relocated sections are verbatim (see content-edit notes for the two formatting-level adjustments)
• Zero theme-override files
• Strict build exit 0 with docs/index.md as Home

rac-docs-site-publish-pipeline — 6/6 pass

• docs.yml exists, parses, triggers on push to main only
• Strict failure demonstrated: a deliberate broken link produced "Aborted with 1 warnings in strict mode!", exit 1, then reverted (demonstrated against the local build rather than a scratch branch — same build step, same command)
• Deploy uses configure-pages@v5 / upload-pages-artifact@v3 / deploy-pages@v4, no third-party actions
• No gh-pages branch; site/ gitignored, no generated HTML committed
• permissions block is exactly contents: read, pages: write, id-token: write
• Manual Pages step listed below

rac-docs-site-readme-doorway — 5/5 pass

• README contains exactly the REQ-001 doorway elements (as amended: four-command block including rac export); no REQ-003 section heading appears
• All documentation links point at the site; grep finds zero blob/main/docs/ links
• Comparison table, sources comment, trust bullets, "Why this works", and the Portal section each appear once, on docs/index.md only
• 72 lines ≤ the 82-line ceiling
• Diff is removal/relocation; the condensed product summary is the one condensation, now explicitly sanctioned by REQ-005 as amended (commit 148cda4)

Artifact amendments made mid-implementation (all in commit 148cda4)

main's v0.11.0 release changed the README after the requirements were approved; the contracts were amended — not silently bypassed — to absorb it:

1. rac-docs-site-landing-page REQ-007: Portal section added to the below-fold order
2. rac-docs-site-readme-doorway REQ-001: command block is now four commands (rac export added)
3. rac-docs-site-readme-doorway REQ-003: Portal section added to the relocated-sections list
4. rac-docs-site-readme-doorway REQ-005: condensed product summary added to the drift-policy exceptions (closes the gap flagged in the original PR text)

Content edits to existing docs/ pages (complete list)

Link targets only — no prose changed:

1. docs/ecosystem.md: ../rac/ → absolute GitHub URL
2. docs/ecosystem.md: ../.claude/skills/rac-artifacts/SKILL.md → absolute GitHub URL
3. docs/ecosystem.md: ../examples/guide/demo.md → absolute GitHub URL
4. docs/mcp.md: ../examples/guide/ → absolute GitHub URL
5. docs/repo-workflow.md: ../rac/decisions/adr-022-… → absolute GitHub URL
6. docs/testing.md: ../rac/decisions/adr-023-… → absolute GitHub URL
7. docs/testing.md: ../rac/prompts/rac-agent-commit-guidelines.md → absolute GitHub URL

Landing-page formatting adjustments to relocated copy (not prose rewrites): the naming paragraph's trailing colon became a period (it no longer leads into a code block), and the walkthrough example is introduced by "Point your agent at your repo and ask:" condensed from the README's step framing.

Review Path

1. rac/designs/docs-site-scoping.md — the approved scope everything traces to
2. rac/requirements/rac-docs-site-*.md, rac/decisions/adr-042-docs-site-hosting.md, rac/roadmaps/v0.10.x-guide/v0.10.7-docs-site.md — the specification (note the amendments commit 148cda4)
3. mkdocs.yml, docs/index.md — the site
4. .github/workflows/docs.yml — the pipeline
5. README.md — the doorway diff and merge resolution
6. The seven link conversions

Notes For Reviewer — manual steps required

1. Enable GitHub Pages: Settings → Pages → Build and deployment → Source: GitHub Actions. Until this is set, the deploy job cannot publish (expected, documented in the pipeline requirement). This is also the go-public gate: merging this PR publishes nothing by itself, consistent with lore-web's GATE-1 posture.
2. Merge this PR — the first successful deploy happens once Pages is enabled and main receives a push.
3. Roadmap numbering: this item is v0.10.7 in the now-previous series, approved before v0.11.0 started the portal series. If you'd rather it be v0.11.1, it's a one-commit rename — say the word.
4. Open question from scoping (not assumed in scope): whether pyproject.toml's Homepage URL should point at the site once live.

Implementation Process

Implemented with AI assistance under the roadmap contract.
Final scope, review, and acceptance decisions were made by the maintainer.