Project architecture¶
How the workspace is organized, and the tooling that supports it.
Content layers¶
Organize information by the reader's task, with one maintained home for each subject:
| Location | Owns | Does not own |
|---|---|---|
docs/using/ |
Installation, invocation and the current audit workflow | Experiment logs or speculative install commands |
docs/reference/ |
Implemented checks, browser protocols and report/data contracts | General research or past campaign conclusions |
docs/reports/ |
Entry point to current and historical per-site reports | Model benchmark rankings |
docs/knowledge-base/ |
Reusable methodology, evidence interpretation and tool research | A chronological account of implementation |
docs/feasibility-study/ |
Research questions, design rationale and proposed architecture | Current setup instructions |
docs/initial-implementation/ |
Implementation scope, roadmap, detailed backlog and evidence history | The default home for every new page |
docs/evaluation/ |
Benchmark design, model protocol, case inventory and campaign index | Live-site judgments presented as reference truth |
docs/contributing/ |
Development, documentation and skill maintenance | End-user audit installation |
Section README.md files serve both MkDocs and GitHub. Existing reports, campaign pages and immutable bundles retain their published paths under initial-implementation/; navigation and indexes give them their appropriate reader-facing home. Do not move or reformat hashed evidence for cosmetic consistency.
Update the canonical guide or reference when behavior changes. Add a campaign page only for a distinct reproducible experiment, and link it from the evaluation or report index. Keep completed experiment observations intact, label them historical, and reduce their search prominence when superseded. The roadmap owns sequence; the backlog owns detailed follow-ups. Avoid another rolling checkpoint page that repeats both.
Documentation build¶
The site is built with MkDocs and the Material for MkDocs theme, configured in mkdocs.yml. Beyond rendering Markdown to HTML, the build applies a few transforms contributors should be aware of:
- Last-modified dates – each page footer shows the last commit date from git, taken via
mkdocs-git-revision-date-localized-plugin. - Folder metadata – Material's
metaplugin applies.meta.ymlvalues to pages in that folder and its subfolders. The knowledge base defines a shared tag. Page-specific tags are merged with folder tags. - Tag index – the
tagsplugin collects page and folder tags intotags.jsonand renders the listing marker in the Tags page. See the style guide for authoring syntax. llms-full.txt– themkdocs-llmstxtplugin concatenates select pages intollms-full.txtat the site root, so LLMs and agents can ingest the workspace in one file. The plugin'ssectionskey inmkdocs.ymlmirrorsnav; keep both in sync when adding or removing sections.- Abbreviation tooltips –
contributing/abbreviations.mdis auto-appended to every page bypymdownx.snippets, so any abbreviation registered there is available as a hover tooltip across the site. - Strict validation –
mkdocs build --strict(just build-docs) fails on pages missing fromnav, broken anchors, unrecognized links, root-relative links, and missing snippets. Use file patterns in the top-levelnot_in_navsetting inmkdocs.ymlfor published pages intentionally omitted from navigation. Snippet sources are excluded from page generation withexclude_docs.
The Markdown-facing syntax for these features is documented in the style guide; mkdocs.yml carries inline comments explaining each option.
Agent skill publishing¶
The native MkDocs hook in scripts/publish_skills.py copies .agents/skills/ to site/.well-known/agent-skills/ and generates the discovery index and AI catalog after each build. Skill metadata provides descriptions and versions; MkDocs configuration provides publisher details. The Pages upload includes hidden files so the catalogs reach the deployed site. See skill maintenance for publishing and the audit guide for installation.
Continuous integration¶
.github/workflows/ci.yml runs on every push to main and on pull requests:
- Python linting and formatting checks (
ruff), type checking (mypy,ty). - Non-Python formatting checks (
prettier). - Prose checks (Vale, configured in
.vale.iniwith repository-owned rules). - Local link checking (lychee, configured in
lychee.toml). - Rendering fixtures and agent skill publishing tests.
- A strict documentation build, then upload and deployment of the built
site/to GitHub Pages.
Python dependencies are installed from the committed lockfile with uv sync --locked --dev. The separate workflow in .github/workflows/external-links.yml checks HTTP(S) sources on pull requests, pushes to main, a weekly schedule, and manual dispatch. Its failures are reported separately and do not block site deployment.