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

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Docs
+
+# Build the documentation site with MkDocs and deploy it to GitHub Pages.
+# Strict mode turns broken links and nav entries into build failures, so a
+# broken site can never deploy. First deploy requires the maintainer to set
+# Pages source to "GitHub Actions" in the repository settings.
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install MkDocs
+        run: pip install mkdocs==1.6.1 mkdocs-material==9.7.6
+      - name: Build site (strict)
+        run: mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -17,3 +17,6 @@ dist/
 .coverage
 .coverage.*
 htmlcov/
+
+# MkDocs build output (deployed from CI, never committed)
+site/

CLAUDE.md

@@ -20,5 +20,5 @@ to the corpus artifact and they load through the imports below.
 ## Working corpus
 
 - Current series: `rac/roadmaps/v0.11.x-portal/` (next up: v0.11.0)
-- Previous series: `rac/roadmaps/v0.10.x-guide/` (complete through v0.10.5)
+- Previous series: `rac/roadmaps/v0.10.x-guide/` (complete through v0.10.5; v0.10.7 docs site in flight on PR #78)
 - Decisions (ADRs): `rac/decisions/`

README.md

@@ -12,31 +12,17 @@
 
 > **Give your coding agent the decisions your team already made — so it stops re-doing things you ruled out.**
 
-Your agent reintroduces an approach you rejected months ago. It rebuilds something you deliberately removed. The decision was written down — in an ADR nobody, human or agent, ever reopened.
+Lore keeps your team's recorded knowledge — requirements, decisions, designs, roadmaps, and prompts — as typed Markdown in your repo and serves it read-only to Claude Code, Cursor, and Claude Desktop over MCP, so the agent cites your decisions instead of violating them. It is built on **RAC — Requirements as Code**, the open-source engine underneath; the package, CLI, and MCP server ship under the `rac` name.
 
-Lore stores your requirements, decisions, designs, and roadmaps as typed Markdown in your repo, and serves them to Claude Code, Cursor, and Claude Desktop over MCP. The agent cites your decisions instead of violating them.
-
-No AI in the core. No inference. No guessing. Just your team's recorded knowledge, in your Git, handed to the agent that needs it.
-
-Lore is built on **RAC — Requirements as Code** — the open-source engine underneath. For now the package, CLI, and MCP server all ship under the `rac` name:
+## Install
 
 ```bash
 pip install requirements-as-code
 ```
 
-> 📺 **[90-second demo](#)** — watch an agent violate a decision, then respect it. *(link on launch)*
-
-## Grounding your agent (start here)
-
-Lore ships a read-only MCP server. Point your agent at your repo and it can search, retrieve, and traverse your recorded knowledge mid-task.
-
-**1. Install**
-
-```bash
-pip install requirements-as-code
-```
+Requires Python 3.11+. `uv tool install requirements-as-code` also works.
 
-**2. Connect your agent**
+## Connect your agent
 
 Claude Code (from your repo root):
 
@@ -54,126 +40,32 @@ Claude Desktop / Cursor (`mcpServers` in the client config):
 }
 ```
 
-**3. Ask, and watch it ground**
-
-> *"Should I add a hard delete to the user model?"*
-
-The agent calls Lore, finds your soft-delete decision, cites it by ID, and proposes the compliant change — instead of reintroducing the thing you removed on purpose.
-
-The server exposes four read-only tools: `get_artifact`, `search_artifacts`, `get_related`, `get_summary`. It never writes to your repo.
-
-▶ **Full walkthrough + runnable example: [examples/guide/](https://github.com/tcballard/requirements-as-code/tree/main/examples/guide)**
-
-## Why this works
-
-The code is structured, the tests are automated, the infrastructure is versioned — but the *reasoning* behind what you build is scattered across tickets, chats, and dead docs. Agents can't act on what they can't read, so they re-litigate settled decisions.
-
-Lore puts that reasoning back in the repo as typed, connected artifacts, then serves it to the agent through a deterministic interface. You write the decision once, in Markdown; RAC validates it, links it, and makes it retrievable — durable context for both humans and AI, with no proprietary format and no hosted platform.
-
-## Who it's for
-
-- **Teams running coding agents heavily** (Claude Code, Cursor) who are tired of the agent ignoring decisions the team already made.
-- **Teams who already write ADRs** and want those decisions to actually shape what the agent does.
-- **Anyone who wants the *why* behind their software versioned alongside the code.**
-
-## How this relates to spec-driven development
-
-Spec-driven development (SDD) tools — GitHub Spec Kit, OpenSpec, Kiro — manage the *change*: proposal, design, tasks, carried through to implementation. They treat requirements as ephemeral inputs that are consumed and archived. RAC manages the *requirements*: a durable, versioned, governed corpus that persists across changes and is served to your agent over MCP. RAC is the layer above SDD tools, not a competitor to them — an SDD tool drives each change, while Lore holds the decisions and requirements those changes draw on.
-
-| Dimension | Lore / RAC | GitHub Spec Kit | OpenSpec |
-| --- | --- | --- | --- |
-| Requirement persistence | Requirements, decisions, designs, and roadmaps are long-lived artifacts that persist across changes | Spec, plan, and tasks are created per feature under `specs/<feature>/` | Change folders are archived on completion under `openspec/changes/archive/`; the specs directory is updated |
-| Change management | None — RAC does not manage the change cycle; pair it with an SDD tool | Slash-command workflow: specify, clarify, plan, tasks, implement | Slash-command workflow: propose, apply, archive |
-| Traceability | Typed `Related` links between artifacts; `rac relationships --validate` checks them in CI | `/speckit.analyze` runs cross-artifact consistency and coverage analysis | `openspec validate` checks changes and specs for structural issues |
-| Tool coupling | Read-only MCP server; works with any MCP client | Slash commands or skills installed per agent at init (GitHub Copilot, Claude Code, Cursor, and others) | Slash commands for 20+ AI assistants |
-| Install footprint | `pip install requirements-as-code` (Python 3.11+) | `uv tool install specify-cli` from the Git repository (Python 3.11+) | `npm install -g @fission-ai/openspec` (Node.js 20.19+) |
-
-<!--
-Comparison sources, verified 2026-06-12:
-- GitHub Spec Kit — https://github.com/github/spec-kit (README): per-feature
-  artifacts specs/<feature>/spec.md, plan.md, tasks.md; workflow
-  /speckit.specify → /speckit.clarify → /speckit.plan → /speckit.tasks →
-  /speckit.implement; /speckit.analyze described as "cross-artifact
-  consistency & coverage analysis"; agents selected at init, Copilot
-  default, Claude Code/Cursor/Gemini CLI and others listed; install via
-  `uv tool install specify-cli --from git+https://github.com/github/spec-kit.git`,
-  Python 3.11+.
-- OpenSpec — https://github.com/Fission-AI/OpenSpec (README): workflow
-  /opsx:propose → /opsx:apply → /opsx:archive; archive output
-  "Archived to openspec/changes/archive/2025-01-23-add-dark-mode/ Specs
-  updated."; "works with 20+ AI assistants via slash commands"; install
-  `npm install -g @fission-ai/openspec`, Node.js 20.19.0+.
-  https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md:
-  `openspec validate` checks changes and specs for structural issues.
-- Kiro is named in prose as part of the SDD category but excluded from
-  the table: its documentation site (https://kiro.dev/docs/specs/)
-  returned HTTP 403 to automated fetches at verification time, so its
-  cells could not be verified against the primary source.
-- Lore / RAC cells: this repository (README, docs/, rac/).
--->
-
-## Authoring artifacts (the RAC CLI)
-
-The MCP server is only as good as what it serves. RAC's CLI is how you write and maintain that knowledge — and how you enforce it in CI.
+## Author and enforce artifacts
 
 ```bash
 rac validate rac/          # check every artifact in a directory
 rac inspect requirement.md # see its type and completeness
 rac review rac/            # full repository review, worst problems first
-```
-
-New to Lore? Author your first artifact in five minutes: **[docs/quickstart.md](https://github.com/tcballard/requirements-as-code/blob/main/docs/quickstart.md)**.
-
-### Supported artifact types
-
-- **Requirements** — what needs to exist
-- **Decisions** — why choices were made (ADRs)
-- **Designs** — product experience thinking
-- **Roadmaps** — where the product is heading
-- **Prompts** — reusable AI collaboration patterns
-
-Everything stays plain Markdown — see **[docs/artifacts.md](https://github.com/tcballard/requirements-as-code/blob/main/docs/artifacts.md)**.
-
-## Sharing the corpus (the Portal)
-
-Agents read your lore over MCP; people get the Portal — a single
-self-contained HTML file of the whole corpus that opens from `file://`
-with zero network requests. Attach it to a release, send it to a
-stakeholder, open it on a plane.
-
-```bash
-rac export rac/                                  # canonical JSON to stdout
 rac export rac/ --html --out lore-export.html    # the Portal, one file
 ```
 
-The JSON payload is a stable contract (artifacts with ids, aliases,
-status, rendered bodies; relationships as edges) for anyone building
-their own viewer. The Portal ships search, type/status filters, and
-citation cross-links out of the box.
-
-## How Lore earns trust
-
-Lore asks you to trust it with your product knowledge, so it holds itself to the same standard it applies to your repository:
+## Who it's for
 
-- **The MCP server is read-only by construction.** It cannot create, modify, or delete files in your repo — enforced in code and verified by tests, not by convention.
-- **No AI in the core.** Retrieval is deterministic: the same repo state and the same query always return the same result. The reasoning is your agent's job; Lore's job is to hand it the facts.
-- **It dogfoods itself.** Lore's own planning corpus under [`rac/`](https://github.com/tcballard/requirements-as-code/tree/main/rac) is validated by RAC in CI — if the tool's rules break the tool's own artifacts, the build fails.
-- **Output is a contract.** Golden tests pin CLI and MCP output; any change to what the tools return is reviewed as a product change.
-- **Telemetry is opt-in twice over.** Local recording needs an explicit `--telemetry` flag and never includes your arguments or repository content. Remote sharing is a separate, explicit consent (`rac telemetry on`, or one honest question at `rac init`): one anonymous daily ping — a random install id, the version, and an active-repo count — never paths, queries, or content. `rac telemetry status` shows exactly what is shared, the network surface is a single readable module, and ADR-041 records the decision.
+- **Teams running coding agents heavily** (Claude Code, Cursor) who are tired of the agent ignoring decisions the team already made.
+- **Teams who already write ADRs** and want those decisions to actually shape what the agent does.
+- **Anyone who wants the *why* behind their software versioned alongside the code.**
 
 ## Documentation
 
-- [Quickstart](https://github.com/tcballard/requirements-as-code/blob/main/docs/quickstart.md) — install and author your first artifact
-- [MCP server](https://github.com/tcballard/requirements-as-code/blob/main/docs/mcp.md) — tools, client configuration, examples
-- [CLI reference](https://github.com/tcballard/requirements-as-code/blob/main/docs/cli.md) — every command, flag, and exit code
-- [Artifact types](https://github.com/tcballard/requirements-as-code/blob/main/docs/artifacts.md) — the five types and their sections
-- [Relationships](https://github.com/tcballard/requirements-as-code/blob/main/docs/relationships.md) — link artifacts and validate the links
+**Full documentation: <https://tcballard.github.io/requirements-as-code/>**
 
-Requires Python 3.11+. `uv tool install requirements-as-code` also works.
+- [Quickstart](https://tcballard.github.io/requirements-as-code/quickstart/) — install and author your first artifact
+- [MCP server](https://tcballard.github.io/requirements-as-code/mcp/) — tools, client configuration, examples
+- [CLI reference](https://tcballard.github.io/requirements-as-code/cli/) — every command, flag, and exit code
 
 ## Project status
 
-Lore is early and evolving quickly. The MCP server ships today; feedback from teams running agents in anger is exactly what shapes what comes next. Contributions, ideas, and experiments welcome — see [CONTRIBUTING.md](https://github.com/tcballard/requirements-as-code/blob/main/CONTRIBUTING.md).
+Lore is early and evolving quickly. The MCP server ships today. Contributions, ideas, and experiments welcome — see [CONTRIBUTING.md](https://github.com/tcballard/requirements-as-code/blob/main/CONTRIBUTING.md).
 
 ## License
 

docs/ecosystem.md

@@ -7,9 +7,9 @@ planned or placeholder entries.
 
 | Name | What it is | Where |
 | --- | --- | --- |
-| RAC dogfood corpus | This repository's own product knowledge — requirements, decisions, roadmaps, prompts, designs — validated in CI by the engine it specifies | [`rac/`](../rac/) |
-| `rac-artifacts` Claude Code skill | A project-level agent skill that teaches Claude Code to create, validate, and update RAC artifacts using the `rac` CLI | [`.claude/skills/rac-artifacts/`](../.claude/skills/rac-artifacts/SKILL.md) |
-| MCP grounding example | A runnable demo showing an agent connected to RAC Guide over MCP respecting a recorded decision that an unconnected agent violates | [`examples/guide/`](../examples/guide/demo.md) |
+| RAC dogfood corpus | This repository's own product knowledge — requirements, decisions, roadmaps, prompts, designs — validated in CI by the engine it specifies | [`rac/`](https://github.com/tcballard/requirements-as-code/tree/main/rac/) |
+| `rac-artifacts` Claude Code skill | A project-level agent skill that teaches Claude Code to create, validate, and update RAC artifacts using the `rac` CLI | [`.claude/skills/rac-artifacts/`](https://github.com/tcballard/requirements-as-code/blob/main/.claude/skills/rac-artifacts/SKILL.md) |
+| MCP grounding example | A runnable demo showing an agent connected to RAC Guide over MCP respecting a recorded decision that an unconnected agent violates | [`examples/guide/`](https://github.com/tcballard/requirements-as-code/blob/main/examples/guide/demo.md) |
 
 ## Adding an entry
 

docs/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.