Make the README a recipe, move the rationale into docs/, and publish it as a book

[tschm]

The README had grown to 552 lines and led with why the fleet is an explicit list rather than with how to get a board running. Someone who has just cloned this repo has one question, and it was buried.

1. The README is now 76 lines

What it is → what you need → the recipe (clone, up.sh, edit repos.yml, up.sh again, open the board) → a "Then what" table of the six things you actually do next → the URLs → a docs index.

The one piece of troubleshooting that bites every laptop user — every panel reading No data after the machine slept — stays on the front page, because that is the question people ask before they ask anything else.

2. Nothing is deleted

Most of what was there is recorded rationale, much of it written down precisely so nobody repeats a mistake (the or vector(0) trap, the group_left duplicate-series trap, the per_page=1 bug, why Fly.io was abandoned). It moves rather than goes:

docs/configuration.md	repos.yml, .env, dropping and purging a repo, the API budget
docs/metrics.md	how it fits together, the four subjects and why each is shaped that way, the owner/name label
docs/dashboard.md	reading tiles, editing, alerting, and the four query traps
docs/serving.md	public dashboards, the server stack, a VPS, TLS, why not Fly.io
docs/operations.md	the sign-in button, and the sleep / No data behaviour

The "Then what" table links straight into the relevant section for purging, the dashboard traps and alerting, so the warnings are one click from the action that needs them.

3. Those pages are now a book

A Material for MkDocs site at https://jebel-quant.github.io/monitoring/ — search, light/dark toggle, the org logo — so it looks like the other Jebel-Quant books. docs/index.md is a landing page rather than a copy of the README: the recipe, then a card per section.

mkdocs.yml is self-contained rather than INHERIT: docs/mkdocs-base.yml like the rhiza-managed repos. This repo is not rhiza-managed, so nothing syncs a base file into it and an INHERIT line would point at a file that does not exist. The theme block is kept close to the org's base so the books match, and the header says what to do if this repo is ever brought under rhiza.

Why the workflow builds on PRs

strict: true is what makes this worth having in CI. These pages were split out of one long README, so a stale relative link is the likeliest way they rot — strict turns that into a failed build. So .github/workflows/book.yml builds on every pull request and deploys only on a push to main, never from a fork, which must not be able to publish to this org's Pages site. mkdocs-material is pinned so an unrelated upstream release cannot redden a PR that only touched the collector.

4. Topics and keywords

Applied directly to the repo (it had none):

grafana prometheus monitoring observability dashboard metrics prometheus-exporter github-api github-actions ci-cd devops docker-compose self-hosted developer-tools repository-management python

The description and homepage are set too, and every docs page carries title / description / keywords front matter for search engines and the site search.

Verification

• Every line of the old README over 25 characters still appears in the new set. The only ones that do not are headings that were renamed and the old quickstart block the recipe replaces.
• mkdocs build --strict locally: six pages, no warnings, all five card icons render as SVG.
• CI on this PR: build passes, deploy correctly skips.

One thing to know before merging

Pages is already configured for this repo (build_type: workflow), and the repo is public on a free org plan — so the published book is public. Pages access control (private/internal) is an Enterprise Cloud feature and is not available here. Nothing in these docs is secret and all of it is already readable in this public repo, so merging discloses nothing new — but if the intent was a genuinely access-restricted page, this does not achieve that and we should host it differently.

🤖 Generated with Claude Code