---
schema_version: 1
id: RAC-KTYXDVA2VG8K
type: roadmap
---
# RAC v0.11.1 — Lore Docs Site

## Status

Planned

## Context

Lore's public surface is a long README and raw Markdown under `docs/`.
The approved scoping design (`docs-site-scoping`) defines a documentation
website — landing page plus the nine existing guides with navigation and
search — hosted on GitHub Pages and governed by this corpus. ADR-042
records the hosting model: repository Markdown stays authoritative; the
site is a generated view. This release delivers that site.

## Outcomes

- A landing page at the site root presents the hero art, tagline, install
  command, and three documentation entry points above the fold.
- All nine `docs/` guides are browsable on the site with sidebar
  navigation and search, served unrewritten from their current paths.
- Every push to `main` publishes the site through a strict-gated GitHub
  Actions workflow; broken links or nav fail the build before deploy.
- The README is reduced to the ADR-022 doorway, with the relocated depth
  content living solely on the landing page and the ADR-042 drift policy
  in force.

## Initiatives

### Initiative 1 — Site platform

`mkdocs.yml` with the Material theme, pinned dependencies, explicit nav
matching the approved site map, built-in search, and assets under
`docs/images/`. Governed by `rac-docs-site-platform`.

### Initiative 2 — Landing page

`docs/index.md` per the approved wireframe: hero, install, value
proposition, primary links above the fold; relocated README depth below.
Governed by `rac-docs-site-landing-page`.

### Initiative 3 — Publish pipeline

`.github/workflows/docs.yml`: build on push to `main`, `mkdocs build
--strict` as the gate, deploy via the official Pages actions, no
`gh-pages` branch. Governed by `rac-docs-site-publish-pipeline`.

### Initiative 4 — README doorway

README reduced to ADR-022's doorway shape with site links replacing blob
links, and the drift policy enforced. Governed by
`rac-docs-site-readme-doorway`.

## Constraints

- Dependencies limited to pinned `mkdocs` and `mkdocs-material`.
- Existing `docs/` prose untouched except the seven link-target
  conversions enumerated in `rac-docs-site-platform`.
- One landing page, one docs section; no blog, versioning, analytics,
  custom domain, or i18n.
- Implementation lands as a branch and pull request; repository settings
  (enabling Pages) remain manual maintainer steps.

## Non-Goals

- Blog or news surface.
- Versioned documentation.
- Site analytics.
- Custom domain.
- Internationalization.

These are recorded as deferred in `docs-site-scoping`; none gets an
artifact until deliberately scoped in.

## Implementation Contract

New files: `mkdocs.yml`, `.github/workflows/docs.yml`, `docs/index.md`,
`overrides/home.html`, `docs/stylesheets/extra.css`, self-hosted
JetBrains Mono under `docs/fonts/`, and the vendored brand assets
`docs/images/lamplighter.png` and `docs/images/favicon.png`. Modified
files: `README.md`, `.gitignore` (ignore `site/`), plus link-only edits
to `docs/ecosystem.md` (3), `docs/mcp.md` (1), `docs/repo-workflow.md`
(1), `docs/testing.md` (2). The acceptance criteria of the four
requirement artifacts are the test plan; `mkdocs build --strict` must
exit clean, and the implementation PR maps every criterion to
pass/fail/blocked.

## Success Measures

- `mkdocs build --strict` green in CI on the implementation branch and on
  `main` after merge.
- Every acceptance criterion across the four requirement artifacts
  recorded as passing in the implementation PR.
- The site live at `https://tcballard.github.io/requirements-as-code/`
  after the maintainer enables Pages.
- `rac validate rac/`, `rac relationships rac/ --validate`, and
  `rac review rac/` remain green with the new artifacts in the corpus.

## Risks

- The deploy is inert until the maintainer flips the Pages source setting;
  sequencing is documented in the publish-pipeline requirement.
- Strict mode may surface unknown link breakage beyond the seven scoped
  conversions; any such finding is reported against the platform
  requirement rather than silently patched.

## Assumptions

- The repository stays public, keeping GitHub Pages available.
- This item ships in the active `v0.11.x-portal` series as v0.11.1, after
  v0.11.0 (portal export).

## Related Requirements

- rac-docs-site-platform
- rac-docs-site-landing-page
- rac-docs-site-publish-pipeline
- rac-docs-site-readme-doorway

## Related Decisions

- ADR-042
- ADR-022
- ADR-036

## Related Designs

- docs-site-scoping

## Dependencies

- The existing `docs/` content set and the lore-web design system
  (tokens, JetBrains Mono, lamplighter mascot) under `lore-web/`.
