[outofcoffee]

Build the user documentation as a proper site with MkDocs Material, themed in the spinloop brand, and publish it to GitHub Pages at docs.spinloop.ai.

Summary

• Build docs/ with MkDocs Material 9.7.7 (pinned), themed from the brand tokens: near-black ground, the mint accent, Poppins for headings, IBM Plex for body and code (mkdocs.yml, docs/stylesheets/main.css, overrides/main.html)
• Restructure the docs around the reader: an introduction that grows into the work, a page per area under docs/guides/ (local serving, opening the agent, Hugging Face, daemon nodes, cloud deployment, fleets, the gateway, working a backlog), a command reference with an index page, and the missing page types — troubleshooting, FAQ, and a link to the repository
• Move maintainer documentation under docs/maintainer/ so the site is user-facing by default
• Publish to GitHub Pages: a build job on every push and PR (mkdocs build --strict, so a dead page fails the build), a deploy job on main that writes the CNAME for docs.spinloop.ai
• scripts/docs-serve.sh serves the site locally in Docker, building the same pinned version CI uses

Implementation details

• The theme does not use Material's palette presets: primary and accent are set to custom, and the brand values are applied in docs/stylesheets/main.css under [data-md-color-scheme=slate], the selector Material's own palette rules target, so the overrides win the cascade. extra_css is a top-level key — a value under theme: is accepted and silently ignored.
• The CNAME is written by the deploy job rather than committed under docs/, so the domain lives with the deployment and docs/ stays pure content.
• GitHub Pages itself is not enabled yet: the first main deploy needs the repository's Pages setting pointed at the github-pages environment (Settings → Pages → Source: GitHub Actions), and docs.spinloop.ai needs a DNS CNAME to spinloop-ai.github.io.