docs-s4: hardening + authoring guide + close-out

[JArmandoAnaya]

Part of the Documentation Site workstream (see the epic) · decided in ADR-0009 · specified in the roadmap. Depends on docs-s1, docs-s2, docs-s3. Closes the workstream.

The sprint that makes the two-pipeline model survivable by someone who was not here when it was built.

Deliverables

1. Link-check hardening

Internal link check across the assembled tree (not just one build): every internal link and image reference resolves, in dev/ and in every version directory, including cross-tier reference→guide bridge links.

External links are a non-blocking report — a job that lists dead outbound links without failing the build, so link rot in third-party URLs never blocks a merge.

2. Contributor authoring guide

A page in docs/ (linked from docs/README.md and from the contributing docs) that answers "I want to document a thing — where does it go?" Must cover:

• The two tiers and how to choose. Reference = short per-tool/per-panel page rendered in-app by F1. Guides = tutorials and workflows, site-only.
• Strict CommonMark rules for reference/ — stated concretely, from what the in-app renderer actually supports. The renderer is md4c with MD_DIALECT_GITHUB: tables, strikethrough, task lists and autolinks work; there are no footnotes, no front-matter, no admonition syntax, no code-fence transforms, and no heading anchors (so page.md#section lands at the top of the page). Also settle the <kbd> inconsistency: 7 pages use <kbd> inline HTML, which QTextBrowser renders unstyled, while most reference pages use backticks for the same thing. Specify the rule here; applying it repo-wide is a separate PR.
• Allowed Starlight syntax for guides/ — Markdown plus asides. MDX and JS components stay deferred; say so and say why (the local file:// build stays simple).
• The bridge-section convention from docs-s2: exact form, and that CI verifies the target exists.
• Image placement per tier, and the constraint that the .qhp bundles only png/gif/jpg and that its <files> patterns do not recurse — a new folder needs its own patterns.
• The rule: author once — both outputs are generated. Adapted content under docs-site/ is generated and gitignored; hand-editing it is forbidden.
• index.md is the ordering manifest: a reference page not linked from it is invisible to the in-app help pipeline, and the coverage gate greps for the literal (<slug>.md).

3. Dependency hygiene, scoped to docs-site/

Committed package-lock.json, npm ci everywhere, a documented monthly update cadence, and licenses recorded per docs/standards/dependencies.md (MIT/BSD/Apache-2.0-compatible only). Zero noise for the C++ side: no npm advisory or update automation may open PRs against, or fail jobs for, the kernel/editor/Python build.

4. IP-rule sweep

Sweep all content, issues, commits, config, and site copy added by this workstream against docs/standards/product-parity.md: no third-party product names — RoadMaker vocabulary and ASAM OpenDRIVE/OpenSCENARIO concepts only. Naming build dependencies (Astro, Starlight, Node, Pagefind, Amplify) in tooling and configuration is fine, exactly as for Eigen or Manifold.

5. Drift check

Verify the roadmap's Documentation site section, ADR-0009, and the release-gate wording match what was actually built across docs-s1–docs-s3; fix the drift in whichever direction is right (the docs may be wrong, or the implementation may have quietly diverged from an accepted decision — say which in the PR).

Known stale text to fix: docs/README.md's conventions section still says the tree is "structured so a static-site generator (e.g. MkDocs) could be adopted later."

Acceptance

• The guide is executable: a reviewer following it adds one reference page and one guide page and sees each appear in its correct pipeline(s) — the reference page reachable in-app via F1 and on the site, the guide page on the site only — with no extra steps beyond what the guide states. Record the walkthrough in the PR.
• Internal link check green across the assembled tree; the external-link report runs and does not block.
• IP sweep clean.
• Roadmap section, ADR-0009, and gate wording match as-built reality.
• docs-site/ dependency automation produces no noise on the C++ side.

Out of scope — do not touch

• Rewriting existing page content beyond what the drift check requires. Applying the <kbd> normalization repo-wide is a separate PR — this sprint specifies the rule.
• Splitting objects-signals.md (noted in the epic as separate content work).
• Help pipeline: tutorial pages' parent-relative links rewrite to wrong guide-root URLs #297 — not fixed, not closed here.
• New features on the site (analytics, comments, i18n, versioned search across versions).
• The ToolId-enum coverage hole noted in the epic.

Closing the workstream

When this merges, tick all four sprints in the epic and close it, per the CLAUDE.md rule that a fully-ticked epic never stays open. Note in the epic's status line that the workstream's release-gate items are maintainer hand-runs (local reader from file:// on macOS/Linux/Windows; Help-menu action in the packaged app), which are recorded at the gate, not here.

---

Epic: #344