docs: split the CLI reference per command, and publish the site on Pages

[Ndevu12]

Splits the oversized CLI reference into one page per command, and publishes the whole docs/ tree
as a versioned MkDocs Material site on GitHub Pages.

Closes #1467

⚠️ One manual step before the first deploy

Settings → Pages → Source: GitHub Actions. A PR cannot change repository settings, so the first
deploy job will fail until that is set. Everything else — creating gh-pages, seeding latest,
setting the default alias — the workflow does on its own.

Part 1 — the reference split

docs/reference/cli.md was 3,564 words, a third of the entire corpus on one page, while every other
page sat between 300 and 660. It is now docs/reference/cli/:

Page	Words		Page	Words
index.md	576		hook.md	248
scan.md	532		auth.md	244
guard.md	531		audit.md	185
credentials.md	417		fix.md	154
sinks.md	129		discard.md	110
db.md	103		remote.md	99
migrating.md	93		intro.md	65
doctor.md	48		completion.md	45
search.md	33

Largest page 576 words, against a 3,564-word original. Content moved verbatim — nothing was
rewritten or expanded; the only new prose is a two-sentence pointer on the index and a one-line
cross-reference on auth.md and completion.md where a section left the page they used to sit on.

docs/explanation/credential-hygiene.md is deliberately left as one 1,661-word page: it reads
end to end, and hygiene.credentials.CREDENTIAL_HYGIENE_DOC links to it as a finding's details
destination.

Judgement call worth a look. The issue enumerates one page per command. Four sections of the old
page are not commands but shared reference — Remote targeting, Report sinks, Credentials and
Migrating from the legacy scripts. Folding them into index.md would have put it at ~1,100 words,
straight back over the limit the split exists to fix, so each got its own page. Command aliases and
Environment variables are small and genuinely global, so those did fold into index.md.

Links

Every inbound link to the old page and its anchors is repointed — docs/, README.md,
SUPPORT.md, CLAUDE.md, and the two committed skills. Two links that were already broken
under a strict build are fixed on the way past:

• three same-directory cli.md#… links inside docs/reference/ (my first grep used a
  reference/ prefix and missed them; mkdocs --strict caught them);
• docs/how-to/gate-ci.md → ../../README.md#the-workflow-by-hand, which resolves on GitHub but
  points outside docs_dir, so it is now an absolute repo URL.

The three shipped doc-URL constants in src/ were imported and resolved, not grepped — all
three point at a file and anchor that exist, before and after:

hygiene.__init__._SCOPE_DOCS               docs/how-to/audit-a-machine.md#what-saw-audit-does-not-scan  ✓ file ✓ anchor
hygiene.editor._DOCS                       docs/how-to/audit-a-machine.md#what-saw-audit-does-not-scan  ✓ file ✓ anchor
hygiene.credentials.CREDENTIAL_HYGIENE_DOC docs/explanation/credential-hygiene.md                       ✓ file

Part 2 — the published site

mkdocs.yml — Material theme, site_name: saw, edit_uri: edit/main/docs/, search enabled, nav
mirroring the Diátaxis tree exactly. strict: true plus explicit validation: so a broken relative
link, a dangling #anchor, or a page missing from the nav fails the build rather than shipping.

Versioning — how a release publishes its own version

saw ships pinned releases, so an unversioned site would misdescribe every older install. mike
keeps one directory per version on gh-pages:

• push to main → mike deploy --push --update-aliases latest then mike set-default --push latest. latest is the default alias, so the bare docs URL resolves to it.
• release: published → mike deploy --push "${TAG#v}" — an immutable directory named after
  the tag with the leading v stripped (v0.6.1 → 0.6.1), and latest is left alone. Someone
  pinned to 0.6.1 keeps a page that describes 0.6.1.
• pull request → mkdocs build --strict only. No branch write, no deploy.

Pages is served from the uploaded artifact, not from the branch; gh-pages is only mike's
version store. The publish job materialises the entire versioned tree with git archive (clean,
no .git) so the version selector and every older version stay reachable, and asserts
index.html is non-empty rather than deploying a blank site.

Colour — sampled, not guessed

Sampled from public/stayawakebot-app-icon.png with Pillow, filtering to the saturated green-to-teal
band (0.25 ≤ h ≤ 0.50, s ≥ 0.35, v ≥ 0.45) to skip the near-black ground:

#80E1AB — rgb(128, 225, 171), the single most common glyph colour at 9.49% of the mint-band
pixels. The icon's ground sampled as #090E14.

#80E1AB scores 1.58:1 on white — nowhere near AA — so it is not the light-mode primary:

Scheme	Primary	Accent / links	Contrast
default (light)	#335A44	#467C5E	7.82:1 and 4.88:1 on white
slate (dark)	#090E14 (the icon's ground)	#80E1AB (the mark's mint)	11.84:1 on Material's slate

The light values are hue-preserving darkenings of the same mint, so the two schemes are the same
colour at different lightness. Both live in docs/assets/extra.css; the palette has a scheme toggle
and follows prefers-color-scheme.

Logo and favicon are the icon, copied to docs/assets/.

Workflow and dependencies

.github/workflows/docs.yml — every action pinned to a commit SHA with a trailing # vX.Y.Z
(#1453). Tags resolved from the GitHub API at authoring time:

actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0             # v7.0.0
actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1         # v6.3.0
actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d      # v6.0.0
actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128         # v5.0.0

Least privilege — the workflow default is contents: read, and each job widens only what it needs:
build stays read-only; publish takes contents: write (mike commits to gh-pages) plus
pages: read; deploy takes pages: write + id-token: write and nothing else.

No runtime dependency is added. The toolchain lives in requirements-docs.txt, read only by
this workflow — deliberately not a [project.optional-dependencies] group, so nothing about the
offline, dependency-light install changes and no docs tooling reaches the wheel's metadata. Pinned
exactly (mkdocs==1.6.1, mkdocs-material==9.7.7, mike==2.2.0) for the same reason the actions
are SHA-pinned.

pyproject.toml Documentation now points at https://ndevu12.github.io/stayAwakeBot/. site/
was already covered by /site in .gitignore; the entry is annotated so it is not mistaken for
dead config, and the local .venv-docs/ is ignored too.

Verification

• mkdocs build --strict (with validation.anchors: warn promoted to an error) — clean, 0
  warnings, on the rebased tree. It found 4 broken links on the first run; all 4 are fixed above.
• Independent link/anchor checker over all 51 tracked markdown files, relative links and
  cross-file anchors, slugified GitHub-style: 135 links, clean. Written as a script, not eyeballed.
• grep -rn "reference/cli.md" docs/ *.md → nothing stale.
• Test suite: Ran 1613 tests … OK (skipped=1), with import stayawake confirmed to resolve
  to <worktree>/src/stayawake/__init__.py first, so the green is this checkout's.
• Rebased onto 99f7b82a and every check above re-run on the rebased tree.

Not done, and why

src/stayawake/cli/__init__.py:8 and src/stayawake/cli/helptext.py:7 carry module docstrings
that name docs/reference/cli.md and docs/CLI.md. The second was already stale after #1466; the
first goes stale here. Both are comments — neither is printed, exported, or asserted by a test — and
this PR does not touch src/, so they are left for a follow-up rather than dragging a source change
into a docs PR.