docs: build a documentation site with MkDocs and deploy it to Pages

[twu3202]

Purpose

The first part of #45: the site itself, built from the existing pages.

• mkdocs.yml: MkDocs with the Material theme and its search. The navigation has the README (overview and architecture), the frontend documentation, the recipes and this contributing guide. The model and backend READMEs, which describe planned work, stay on GitHub for now.
• docs/hooks.py: MkDocs only builds files under docs_dir and refuses the repository root there, so the hook sets the root after the config is checked. That publishes the existing pages where they are, instead of moving them or copying them into stubs whose relative links break, and their links work on the site as they do on GitHub. Inline links to files that are not published, and to directories without a README, go to GitHub; on main that covers 6 links, such as .github/workflows/ci.yml and src/models/. mkdocs serve watches only the published directories, so target/ does not trigger rebuilds.
• .github/workflows/docs.yml: builds the site with mkdocs build --strict on pull requests, which fails on broken links and anchors in the published pages. On main of this repository it also deploys the site to GitHub Pages.
• docs/requirements.txt: exact versions. MkDocs 1.6.1 is the current release, and Material requires mkdocs<2.
• A link to the site in the README, and how to build and preview it in CONTRIBUTING.

The other pages in #45 follow in separate PRs.

Deploying needs Settings → Pages → Source: GitHub Actions, ideally before this merges. If it merges first, the deploy job fails with "Ensure GitHub Pages has been enabled", and running the workflow on main again after enabling it deploys the site.

Test Plan

• mkdocs build --strict with the pinned versions: Python 3.13 on macOS, and Python 3.10 on Ubuntu 22.04 following the new CONTRIBUTING steps. Then a crawl of every href and src in the built site, including theme files and anchors.
• Negative checks: a missing page, a missing anchor on the same page and on another page, a directory without a README, an absolute link and an unpublished image, each added to a page. Also a Markdown file inside a hidden directory under recipe/.
• Every open PR merged onto this branch and built the same way.
• mkdocs serve on Ubuntu: pages, assets and search load, and editing or adding a file under recipe/ rebuilds the site. Also a cargo build --release --locked while it serves.
• actionlint 1.7.12 on docs.yml and ci.yml, and git diff --check.

System1-Omni Version / Commit: head 396a025 on b50aa28. The Ubuntu, mkdocs serve and actionlint checks ran on the same change before a rebase onto b50aa28 (the merge of #12, which changes no Markdown or workflows); the strict build, the crawl and the open-PR merges ran again after it.

Test Result

• Strict build: 0 warnings, 5 pages. The crawl finds no broken links, anchors or assets, and the GitHub links it finds point to files on main.
• Each negative check fails the strict build with a warning that names the file and the link, and the file in the hidden directory is not published.
• All 25 open PRs merge without conflicts and build with 0 warnings and no broken links.
• mkdocs serve: all as expected; the cargo build caused no rebuilds.
• actionlint and git diff --check are clean.
• Not run: the deploy job, since Pages is not enabled here yet and the job runs only on main. No Rust code changed, so the Rust checks are not affected.

Self-review

Before marking this PR ready for review or requesting maintainer review, complete
the self-review checklist.
Keep the PR in draft while this work is incomplete.
For agent assistance, use the optional precheck-pr skill.

• I have reviewed the full diff and addressed the issues I found.
• I have checked that the change follows the project's architecture and stays focused on the stated purpose.
• I have run the checks appropriate to this change and reported commands, results, and anything I could not verify above.
• I have checked that the PR description, documentation, and any accuracy or performance claims match the implementation and available evidence.

[hsliuustc0106]

thanks

[twu3202]

Since this merged, the docs build passes on every push to main, but the deploy job fails because GitHub Pages isn't enabled for the repo (all five pushes so far, up to ce38770). Enabling Pages with GitHub Actions as the source should fix it, and the next push will then publish the site. If you'd rather not turn Pages on yet, I can make the deploy job skip until it is, so main stays green.