FE-1500: Document Petrinaut website in architecture docs

[kube]

🌟 What is the purpose of this PR?

Brings @apps/petrinaut-website into the Petrinaut architecture docs, and documents the two things the import graph cannot explain: how the site drives Petrinaut's app location from the URL, and how a third-party site embeds an example through oEmbed. Stacked on #9363.

🔗 Related links

• FE-1500
• oEmbed 1.0

🔍 What does this change?

• Registers the website as a scanned package. Its source root is the app root rather than src, because the Vercel functions in api/ are part of the architecture and deploy separately from the SPA.
• Declares five layers next to the code they describe: website (the app's README frontmatter), website.routes, website.examples, website.api, and website.demo. Everything else in the app inherits from the nearest declaring ancestor, so 5 declarations cover the package.
• Declares one edge no import produces: website.api reaches website.routes through the embed URL it hands to consumers.
• Adds content/website/router-integration.mdx (attached to website.routes): the router-neutral navigation contract, validateSearch as the single entry point for raw query input, why the location splits between the URL and page state, validation as normalization, what a URL carries, and hosting Petrinaut without a router at all.
• Adds content/website/oembed.mdx (attached to website.api): the endpoint's contract and validation, the embed route and its HTTP framing policy, why both sandbox tokens are required, and a copy-pasteable iframe for embedding an example.
• Adds two hand-written D2 diagrams: one navigation round trip, and one oEmbed request through to the rendered iframe.
• Wires the website into the docs build the way the other scanned packages are wired: as a devDependency of @local/petrinaut-arch-docs, so turbo prune keeps its source in the pruned CI workspace.
• Declares web-worker in @hashintel/petrinaut-core, with a patch changeset. elkjs imports it from the entry the graph-layout helper uses, and it resolved only because apps/hash-frontend happened to install it; the pruned workspace this PR creates has no such neighbour, and neither would an external consumer of the published package.
• Review fixes (first round, self-review): corrected three false claims — the docs landing page still said @apps/petrinaut-website was "not covered at all", the page said every route declares validateSearch (three of six do), and it credited the embed with resolving scenario=none when the embed honours it and the oEmbed endpoint is what drops it. Moved @layerRoot website.routes from src/router.ts to src/routes/__root.tsx, since a declaration scopes to its own directory and this one was claiming all of src/, and declared the three subtrees it had absorbed (website.brunch, website.optimization, website.telemetry); renamed website.demo to website.local-storage-demo, as it is one of three demos. Excluded scripts/ and root *.config.ts from scanning so sourceDirectory: "." buys api/ without the build tooling, and exempted private packages from the "no importable exports" warning, which this package triggered on every build. Added a website class to the generated-diagram palette so the hand-written diagrams match it, and fixed the onNavigate signature in one diagram label.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• yarn workspace @local/petrinaut-arch-docs lint:arch-docs covers the model: it fails on an unannotated file, an undeclared ancestor, a rule violation, and a @talksTo target the imports already prove.
• The docs-site build compiles the MDX and renders the D2 sources; both run in CI for this package.

❓ How to test this?

1. yarn workspace @local/petrinaut-arch-docs lint:arch-docs — expect no errors.
2. mise x -- yarn exec turbo run dev --filter @apps/petrinaut-docs, then open the website section.
3. Confirm the five website layers appear with their dependencies, and that both authored pages render with their diagrams.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 1, 2026 11:20am UTC
petrinaut	Ready	Preview	Sep 1, 2026 11:20am UTC
petrinaut-docs	Ready	Preview	Sep 1, 2026 11:20am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 1, 2026 11:20am UTC

[cursor]

PR Summary

Low Risk
Changes are mostly documentation, arch scanning, and layer annotations; the only runtime-facing tweak is an explicit web-worker dependency on petrinaut-core, which fixes resolution rather than altering behavior.

Overview
Brings @apps/petrinaut-website into the Petrinaut architecture docs so its import graph, layers, and non-import boundaries are generated and checked like the other packages.

The arch-docs generator now scans the whole app root (sourceDirectory: ".") so Vercel handlers under api/ count as architecture, while scripts/ and *.config.* files are excluded so build tooling is not pulled into layers. private apps no longer trigger the “no importable exports” graph warning. The website is wired in as a devDependency of @local/petrinaut-arch-docs, and diagram styling gains a website palette class for hand-written D2.

Layer annotations land on the site: README frontmatter for website, @layerRoot / @role on routes, examples, API (@talksTo → embed routes), demos, and telemetry. Authored guides attached to website.routes and website.api explain TanStack Router ↔ Petrinaut navigation and the JSON oEmbed / iframe embed flow, with two new D2 diagrams. The docs index is updated to point at those pages instead of saying the website is uncovered.

Separately, @hashintel/petrinaut-core declares web-worker as a direct dependency so elkjs layout still resolves when the arch-docs pruned workspace (or external consumers) no longer inherit it transitively from another app.

^{Reviewed by Cursor Bugbot for commit 779ffec. Bugbot is set up for automated code reviews on this repo. Configure here.}