docs-s2: local reader build + release packaging + Help-menu action + bridge links

[JArmandoAnaya]

Part of the Documentation Site workstream (see the epic) · decided in ADR-0009 · specified in the roadmap. Depends on docs-s1 (tier restructure + Starlight scaffold + adapter).

Makes the manual something a user actually has: a browser-openable copy inside every release, reachable from the Help menu, with reference pages that link out to their full guides.

As-built facts you must know

Verified 2026-07-21.

1. Today's help staging (editor/CMakeLists.txt:272-282, POST_BUILD): macOS <bundle>/Contents/Resources/help/, Windows/Linux <exe dir>/help/ — and it copies only roadmaker.qch + roadmaker.qhc, no HTML.
2. Install rules (editor/CMakeLists.txt:288-307): install(TARGETS roadmaker-editor BUNDLE DESTINATION . RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}); then if(NOT APPLE) install(FILES ${_rm_qch} ${_rm_qhc} DESTINATION bin/help). macOS relies on the bundle being copied wholesale.
3. The release smoke test already asserts help paths — .github/workflows/release.yml:131 ("Smoke test packaged binary (--version + bundled help)") checks roadmaker-editor.app/Contents/Resources/help/roadmaker.qch (:146-147), squashfs-root/usr/bin/help/roadmaker.qch (:156-157), <root>/help/roadmaker.qch (:165-166), plus QtSql + the qsqlite driver. Extend this step for the manual; do not write a parallel one.
4. The in-app viewer is a QTextBrowser subclass resolving qthelp:// in loadResource(); the collection is located at editor/src/help/help_locator.cpp:26-35 (macOS ../Resources/help, else <exe dir>/help) and copied to a writable versioned dir under AppDataLocation (:47-64). The manual-path resolver should mirror this shape, not invent a new one.
5. Help action + F1 are registered through shortcut_registry at editor/src/app/actions.cpp:347-349; the new menu action goes through the same registry — never hardcode a shortcut.
6. The .qhp renderer emits no heading anchors, so a bridge link with a #fragment lands at the top of the target page. Design the bridge convention to not depend on fragments.

Deliverables

1. build:local — the file:// reader build

Per ADR-0009: build.format: 'file' plus fully relative asset and link references so the site opens straight off disk with no server.

Starlight does not ship this guarantee: evaluate a maintained relative-links integration versus an idempotent post-processing step, and justify the choice in the PR. If you write a post-processor, it must be idempotent (running it twice equals running it once) and covered by a test that proves it.

Search is disabled in this variant — Pagefind cannot index over file:// in mainstream browsers. Put a short note on the local landing page saying search lives on the web docs. Never ship a search box that does nothing.

CI check: fail the build if any root-absolute path (/… in href/src) survives in the local output.

2. Release packaging

Behind ROADMAKER_BUNDLE_MANUAL, default OFF, so a developer build never needs Node. CMake never invokes npm: the packaging job builds the manual with Node first and passes the prebuilt folder in as a path.

Install layout:

• macOS: RoadMaker.app/Contents/Resources/manual/
• Linux: share/roadmaker/manual/
• Windows: manual/ beside the executable

Extend the existing release smoke test (fact 3) to assert manual/index.html exists at the right place on each platform.

3. Help-menu action

"Open manual in browser" (final wording your call), opening manual/index.html via QDesktopServices::openUrl, registered through shortcut_registry.

• Per-platform path resolution, factored into a pure, unit-tested function (given an executable dir and a platform, return the expected manual path) — not inline in a slot. Follow the help_locator shape.
• Graceful dev-build fallback: when the manual folder is absent, show a friendly pointer at the web docs. It must not fail silently and must not show a raw error.
• F1 behavior is untouched.

Editor tests run headless (QT_QPA_PLATFORM=offscreen); test the resolver and the fallback decision, not the browser launch.

4. Reference→guide bridge convention

A standard trailing section on reference pages linking the matching guide:

• On the site: an ordinary link.
• In the .qch viewer: an external-browser link into the packaged manual (QDesktopServices::openUrl), i.e. it must survive helpc's link rewriting as an external URL rather than being rewritten to a qthelp:// page or a GitHub blob URL. Decide the marker (a distinct URL scheme, an absolute URL, a generator-recognized section) and document it.
• CI checks that every bridge target exists. A reference page pointing at a guide that was renamed must fail the build.
• Apply the convention to the reference pages that have a matching guide; do not invent guides that do not exist.

Acceptance

• A packaged build on at least one platform opens the manual from the Help menu, and the same build still opens in-app help with F1.
• The local build passes the no-absolute-paths check; opening index.html directly from the filesystem navigates correctly between pages and images.
• The dev-build fallback shows the friendly pointer (covered by a test).
• Bridge targets verified in CI; a deliberately broken bridge link fails the build.
• Release smoke test asserts the manual on all three platforms.
• F1 and the .qch pipeline are behaviorally unchanged.

Out of scope — do not touch

• Web publishing, versioning, versions.json, Amplify, any publishing workflow (docs-s3).
• The authoring guide, dependency cadence, IP sweep (docs-s4).
• Re-tiering or moving pages — docs-s1 owns the structure.
• Help pipeline: tutorial pages' parent-relative links rewrite to wrong guide-root URLs #297 — not fixed, not closed here.
• Embedding a web view in the app. QWebEngineView is rejected in ADR-0009; the external browser is the design.
• MDX or JS components.

---

Epic: #344

[JArmandoAnaya]

Closed by #560 (squash-merged as 09593e8, all 18 CI checks green).

Delivered

1. build:local — format: 'file', fully relative references, Pagefind off with the search UI removed alongside it and a note on the landing page saying where search lives. The integration-vs-post-processor choice is justified in the PR: a dependency-free post-processor, idempotent by construction and proved so by running it twice and comparing bytes. check-local-build.mjs gates the output, so it still fails if the transform were dropped from the build.
2. Release packaging — ROADMAKER_BUNDLE_MANUAL (default OFF) + ROADMAKER_MANUAL_DIR. CMake never invokes npm; the release job builds the manual with Node and passes a finished directory. Layout per ADR-0009 on all three platforms, asserted by the existing release smoke test (extended, not duplicated).
3. Help-menu action — "Open Manual in Browser", registered through shortcut_registry as an unbound row so F1 keeps belonging to the in-app viewer. The path is a pure function of (executable dir, platform), so all three layouts are covered by one headless test rather than only by the release job. The dev-build fallback is the same function returning nullopt.
4. The bridge — a ## Full guide section whose heading is the marker, so the authored link stays ordinary Markdown. The site emits a normal link; the help compiler emits rmmanual:<slug>, resolved at runtime against the packaged manual and opened externally. Applied to the 13 reference pages with a matching tutorial; none invented.

Three defects found on the way

• The adapter sent in-guide ../ links to GitHub. ../ means "up one directory", not "out of the guide" — and since docs-s1 the guide has subdirectories, so 15 existing tutorials/* → ../reference/* links left the site. Fixing it was a precondition for "on the site: an ordinary link", not a bonus.
• The help build's CONFIGURE_DEPENDS glob watched tutorials/ and missed reference/, so a reference-page edit left the shipped .qch stale — which would have made the new bridge gate depend on whether someone had reconfigured.
• A favicon linked by all 40 pages and shipped by none. Found by the new relativizer on its first real run, because it treats an unresolvable reference as an error rather than rewriting it quietly.

#297 is untouched and stays open — it is the help compiler's own ../ rewriting, a different pipeline from the Node adapter.

Verification

3313/3313 ctest (-Werror), 15 new gtests, 4/4 script tests, licence gate clean (374 packages, all permissive, the sharp stub untouched), clang-format via CI's exact command, and the link check run as a differential against an extracted main — 13 findings on both sides, so this adds none.

Six sabotages, each with a separately checked build exit code. One of them (if (false) around the bridge rewrite) did not compile, so the test ran a stale binary and reported green — a sabotage that was never in the build looking exactly like a test that failed to catch it. Replaced with one that compiles. Renaming a tutorial now fails the C++ gate and the site adapter independently.

Outstanding — requires a display, not attemptable in CI

Neither is claimed:

• Open the local build from file:// and navigate between pages and images by hand, on macOS, Linux and Windows.
• Trigger Help ▸ Open Manual in Browser in a packaged build and confirm the browser opens, with F1 still opening the in-app guide in that same build.

Everything mechanically checkable about both is gated: the release smoke test asserts the manual at the layout the app's own resolver computes plus a page beneath it (an empty manual/ would pass an index-only check), and check-local-build.mjs asserts no root-absolute reference survives.

Noted for docs-s4

npm audit reports 1 high on the pinned astro@5.14.1. All 17 advisories concern the dev server, SSR/middleware, server islands, adapters or the image endpoint — none of which exist in a statically prerendered, adapter-less build. Left for #348, whose deliverable 3 is dependency hygiene and the update cadence.