docs(site): tier the user guide and scaffold the Starlight site (#345)

[JArmandoAnaya]

docs-s1. Two things that are worthless apart, per the issue: split the guide
into a reference tier (dual-source: .qhp + site) and a guides/tutorials
tier (site only), and stand up the Astro Starlight project that consumes it.

1–2. Restructure, and the .qhp narrowed to the reference tier

34 tool/panel pages git mv'd into docs/user-guide/reference/ with their
img/ folder. index.md stays at the guide root because it is the manifest
both pipelines read — that shared manifest is the mechanism that stops the two
outputs drifting.

Consumers updated in the same commit: index.md targets, kToolPages/
kDockPages, the hardcoded shortcuts.md path, docs/README.md, root
README.md, ASSETS_LICENSES.md, and the qhp.cpp/main.cpp image handling.

build_toc now skips tutorials/, and what became dead is deleted rather
than left inert: the TocEntry::tutorial flag, the synthetic "Tutorials" TOC
node, the tutorials/ <files> patterns. reference/ gets its own <files>
patterns and image-copy step — fact 6's warning, and the #292 class of bug.

The link rewrite needed two passes and the first was wrong. Targets already
at ../../ (correctly reaching the repo root) needed a third level, and my
first regex's lookahead skipped exactly those. Redone from HEAD rather than
patched over.

3–5. docs-site/, adapter, CI

Pinned Astro 5.14.1 + Starlight 0.36.0, Node LTS via .nvmrc + engines,
committed lockfile, and four scripts: theme-css, adapt, licenses,
check-f1-coverage.

The theme is a parser, not a C++ generator — justifying the issue's "your
call": ADR-0009 puts site CI on Linux-only Node runners independent of the C++
matrix, and a generated-artifact dependency would couple them. Parsing
theme.cpp keeps theme::graphite_amber() the single source of truth with no
hand-transcribed hex and no build coupling. The committed help.css bytes are
untouched (QTextBrowser can't do custom properties).

The adapter synthesizes title from each page's first H1 (the same rule
build_toc uses), derives reference sidebar order from index.md, and fails
non-zero on a broken link naming source and target — proven by deliberately
breaking one.

The adapter caught 18 broken links the C++ gates structurally cannot see.
With tutorials out of the .qhp pipeline, nothing else validates them — and
every tutorial pointed at ../<page>.md for a page that had just moved.

CI is a new Linux-only Node workflow, path-triggered, uploading dist as an
artifact and stopping there (no hosting resources). No C++ job changed.

The licence gate earned its place

Astro's optional sharp pulls libvips binaries that are LGPL-3.0-or-later.
Qt is this project's only sanctioned LGPL dependency, and any other candidate
needs explicit maintainer approval — not mine to grant.

Two mechanisms that look right and are not:

• --omit=optional removes sharp and rollup's required native binary.
• @rollup/wasm-node does not engage as a fallback on this rollup.

What works: overrides pointing sharp at a local stubs/sharp no-op that
throws with a clear message if anything imports it, plus
passthroughImageService(). Narrow, declarative, and re-proven every CI run.

The gate also found zod-to-ts declaring no licence in package.json while
shipping an MIT LICENSE file, so it falls back to reading the file rather than
failing a permissive package. Final tree: 373 packages, zero copyleft.

Verification

• ctest --preset ci-macos — 3281/3281 pass, including all four help gates
  (test_help_registry, test_help_collection, test_help_style,
  test_shortcut_registry)
• npm ci && npm run build — 40 pages built, licence gate green, F1
  coverage green (20 slugs)
• Adapter fails non-zero on a deliberately broken link

Not done, and not claimed

The acceptance item "F1 resolves correctly … verify in a running editor, not
only via the gate" is outstanding: no display is available in this
environment. All four automated gates pass, and a new site-side check asserts
every F1-reachable slug exists in the adapted set — but the in-editor check is
still needed before this is considered fully accepted.

Fixes #345