SOF-8029: tie the three surfaces together and check the links

[timurbazhirov]

Ticket: SOF-8029 · Epic: SOF-8025
Plan: plan/review/2026-08-16-site-integration-and-release.md
Chained onto #418 — the last of five; this PR's diff is against feature/SOF-8028.

Docs, Explorer and Entity Map become one site rather than three pages that happen to share a host.

What is here

• A shared header — Docs · Explorer · Map — on all three surfaces, with the current one marked.
• "View on map" in the explorer's breadcrumb row for the open file, and welcome-screen links pointing newcomers at the documentation and the map.
• check-site-links, a build step that walks the assembled site and fails the deploy on a broken internal link. The site is stitched together from four sources that all link into each other, and until now nothing checked those links landed anywhere.
• Subresource integrity on both CDN dependencies, Monaco included.
• README covering the three surfaces, the docs/ and plan/ directories, and the schema lint.

A correction to SOF-8026

That PR recorded published-path → $id as not invertible, and shipped a lookup table instead of a function. That was wrong, and the mistake is worth stating plainly because it changed the design here.

An $id is a path with underscores replaced by dashes — so no $id ever contains an underscore, the mapping is injective, and the inverse is exact. What is genuinely unrecoverable is the source path, because a source directory may contain a literal dash that the round-trip flattens.

The practical payoff: the explorer can link into the map by string rule, without loading a 500 KB graph.json just to invert one path. publishedPathToSchemaId is now a pure function; buildPublishedPathIndex stays for callers that prefer a map.

Verified end to end in a browser on exactly the case that caused the doubt:

explorer  schema/properties_directory/non_scalar/file_content.json
   ->     map/#/entity/properties-directory%2Fnon-scalar%2Ffile-content
   ->     panel links back to ../#schema/properties_directory/non_scalar/file_content.json

Testing

The site was assembled exactly as CI does — resolved schemas, graph.json, docs, explorer, map, files.json — and driven in a browser:

EXPLORER HEADER:  Docs->docs/index.html, Explorer->index.html, Map->map/index.html
WELCOME LINKS:    2
VIEW ON MAP:      map/index.html#/entity/properties-directory%2Fnon-scalar%2Ffile-content
MAP ROUND TRIP:   panel = properties-directory/non-scalar/file-content
                  explorer link = ../#schema/properties_directory/non_scalar/file_content.json
DOCS->MAP LINK:   ../map/#/entity/in-memory-entity%2Fnamed-defaultable  -> landed
DOCS HEADER->MAP: ok
PAGE ERRORS:      none

Link checker: all internal links resolve across the whole site; a deliberately broken link fails it:

BROKEN: docs/glossary.html -> does-not-exist.html (target does not exist)
1 broken internal link(s)

Schema tests still green (25 passing), now including the pure-inverse round trip over every node.

Notes for the reviewer

• Monaco's SRI covers the loader script only. The AMD loader fetches editor.main and friends at runtime, and those requests cannot carry integrity attributes. Vendoring Monaco is the only real fix; out of scope here, and noted in the plan document.
• "View on map" sits in the breadcrumb row, not on each of 773 tree rows — one quiet affordance for the open file rather than a control repeated everywhere.
• No README screenshot. The plan called for one via Git LFS; adding LFS tracking and a binary for a decorative image is scope this work does not need. The README links to the live map instead.
• All five plan documents now sit in plan/review/ with ## Status sections recording what shipped and where it diverged.

🤖 Generated with Claude Code

---

Generated by Claude Code