FE-1418: Build @apps/petrinaut-docs on Vercel

[kube]

🌟 What is the purpose of this PR?

Adds the Vercel build for @apps/petrinaut-docs. The app shipped in #9206 with no vercel.json and no build or install script, so a Vercel project pointed at it has nothing to run.

Follows up the two items #9206 left open: adding d2 to the Vercel install step, and deciding where the site deploys. The first is done here. The second is proposed rather than settled, covered under Known issues.

This host serves the whole manifest behind SSO. FE-1157 publishes a subset of the same bundle to hash.dev/docs/petrinaut. The two run side by side.

🔗 Related links

• FE-1418
• SRE-955, creating the Vercel project, assigning the domain and configuring the Cloudflare Access gate. Blocked by this PR.
• FE-1157, publishing a subset of the same bundle to hash.dev/docs/petrinaut. Runs alongside this host rather than replacing it.
• FE-1322: Add a Starlight site that renders the docs bundle #9206, which added the app.

🔍 What does this change?

The build graph is three tasks:

flowchart LR
  A["@local/petrinaut-arch-docs#doc:architecture"] --> B["sync:bundle"]
  B --> C["@apps/petrinaut-docs#build"]

Loading

tsx, a node copy step, and astro build. Nothing compiles, and .yarnrc.yml sets enableScripts: false, so no dependency builds during install either. vercel-install.sh installs Node, Turborepo and d2, and leaves out the Rust toolchain, wasm32 target, wasm-pack, binaryen, java, protoc and redocly that hash-frontend and petrinaut-website install.

d2 renders the architecture diagrams. canRenderDiagrams probes for it before pages are emitted, and a bundle built without it has no diagrams and exits 0, so dropping it loses all 44 SVGs behind a passing build.

vercel-build.sh runs turbo build rather than the package script, which alone skips sync:bundle and builds whatever content was last on disk. It also removes the repo-root .env first, matching the other two apps and the TODOs they link. The generator probes d2 through mise exec --env dev, which still resolves once that file is gone.

cleanUrls and trailingSlash: false in vercel.json follow build.format: "file" and trailingSlash: "never" in astro.config.mjs. The build writes architecture.html and architecture/core.html with no index.html inside a directory, and the bundle's inter-page links are relative, so Vercel serves /architecture from architecture.html and redirects /architecture/ instead of 404ing.

site moves from petrinaut-docs.hash.dev to architecture.petrinaut.org, which sets the canonical URL and every sitemap entry. petrinaut.org already serves demo.petrinaut.org.

This host serves all 48 pages in the manifest, behind SSO. FE-1157 publishes a subset to hash.dev/docs/petrinaut, so the two run side by side and a page can appear on one and not the other. The README says so explicitly, because the alternative reading, that one host replaces the other, changes whether SRE-955 is worth doing at all.

The README gains a Deployment section covering what cannot live in the repo:

Setting	Value
Root Directory	apps/petrinaut-docs
Include files outside of the Root Directory in the Build Step	enabled
Domain	architecture.petrinaut.org (proposed)
Access	Cloudflare Access, SSO required

Both scripts cd ../.., so the build fails without the second.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

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

Adds build configuration to a private app. @apps/* is in the changesets ignore list.

📜 Does this require a change to the docs?

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

apps/petrinaut-docs/README.md gains a Deployment section: the Vercel project settings, the domain and its gate, that hash.dev serves a subset of the same manifest, why the install list is short, and the .env removal.

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

• do not affect the execution graph

No turbo.json or package.json scripts changes. vercel-build.sh calls the existing build task.

⚠️ Known issues

• architecture.petrinaut.org is a proposal. It is written into astro.config.mjs so the build produces consistent canonical and sitemap URLs, not because the host is agreed. Changing it later is a one-line edit plus a redeploy.
• Nothing records which pages are public. FE-1157 publishes a subset, and ManifestPage carries only kind, which is generated or authored, a source distinction rather than an audience one. Until FE-1157 decides how pages are selected, the split lives in whatever consumes the manifest. This PR does not add a field for it, since the selection rule is FE-1157's to choose.
• SSO reaches the machine-readable artefacts. sync:bundle copies architecture.md and architecture.json into public/ so any host of the bundle serves the same bytes an agent would read from a checkout. Behind Cloudflare Access, fetching either over HTTP needs a session. Both also describe the whole model rather than the public subset, so they cannot be reused as-is by the hash.dev host.
• The canonical tag keeps the .html extension. Starlight emits rel="canonical" pointing at /architecture.html while the sitemap lists /architecture, a consequence of build.format: "file" that predates this PR. With cleanUrls the canonical now redirects to the extensionless form rather than serving directly. Behind an SSO gate no crawler sees either, so this is left alone.
• The scripts have not run on Vercel. The project does not exist, so the first deployment under SRE-955 is what tests them. Verified locally with the exact build command.
• d2 stays probed rather than required. A deployment where the mise install line silently fails still produces a site, without diagrams. SRE-955 asks whoever creates the project to check the first deployment renders them.
• rm .env is inherited from hash-frontend and petrinaut-website, with the same three TODO links. Worth knowing if you run the Vercel CLI locally and keep secrets there.

🐾 Next steps

• SRE-955 creates the Vercel project, assigns the domain and puts Cloudflare Access in front of it.
• FE-1157 publishes the public subset to hash.dev/docs/petrinaut, and decides how a page is marked as belonging to it.

🛡 What tests cover this?

None. CI does not run Vercel build configuration, and the two existing apps' scripts are not covered either.

Verified by hand: turbo build --filter='@apps/petrinaut-docs' --env-mode=loose in a worktree with no node_modules, after yarn install --immutable. 3 tasks, 28s, 49 pages and 44 diagrams into apps/petrinaut-docs/dist, with canonical and sitemap URLs on the new host. Separately, the d2 probe with the repo-root .env deleted, which is the state the build script leaves behind.

❓ How to test this?

turbo build --filter='@apps/petrinaut-docs' --env-mode=loose

apps/petrinaut-docs/dist should hold architecture.html, architecture/core.html and 44 SVGs under _astro/, and sitemap-0.xml should list architecture.petrinaut.org. To see what a Vercel install without d2 would produce, build with it off the path and check that the bundle has no diagrams/ and the command still exits 0.

[vercel]

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

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hash	Ignored	Preview	Aug 17, 2026 11:00am
hashdotdesign-tokens	Ignored	Preview	Aug 17, 2026 11:00am
petrinaut	Skipped		Aug 17, 2026 11:00am