FE-1457: Point source links at the branch being built

[kube]

🌟 What is the purpose of this PR?

Implements FE-1457: every generated page links to the file that declared a layer, and the target was hardcoded to main. On a preview build those links showed the pre-change file, or 404'd for a file the branch adds.

The ref now comes from the build environment:

no environment   → https://github.com/hashintel/hash/blob/main/libs/…
GITHUB_HEAD_REF  → https://github.com/hashintel/hash/blob/cf/fe-1457-…/libs/…
GITHUB_SHA       → https://github.com/hashintel/hash/blob/deadbeef…/libs/…

Top of stack #9226, on FE-1456.

🔗 Related links

• FE-1457 (internal): this PR
• FE-1418 (internal): the Vercel deployment whose previews this fixes

🔍 What does this change?

• src/source-url.ts (new): resolves the ref from the first variable that holds a value, in order PETRINAUT_ARCH_DOCS_SOURCE_REF, VERCEL_GIT_COMMIT_SHA, GITHUB_SHA, VERCEL_GIT_COMMIT_REF, GITHUB_HEAD_REF, GITHUB_REF_NAME, defaulting to main. A SHA beats a branch name so the link survives the branch moving or being deleted. Slashes stay literal (they separate path segments in a blob URL) while # and % are encoded.
• architecture.config.ts: sourceUrlPrefix calls the resolver. No literal main remains.
• turbo.json: the six variables are declared in doc:architecture's env, since Turborepo's strict env mode would otherwise hide them from the task.
• vercel-build.sh and the generator's "Wrote" line: both name the resolved ref, so a preview build's log shows which commit its links point at.

No workflow changes: nothing under .github/workflows/ builds the bundle, and GitHub Actions exports the variables the resolver reads.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a workspace but not a publishable library

📜 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
  • The package README documents the variables, the precedence, and the default.

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

The changes in this PR:

• affected the execution graph, and the turbo.json's have been updated to reflect this
  • doc:architecture declares the ref variables. The task and its consumers are uncached, so a ref change cannot serve stale links.

🛡 What tests cover this?

• source-url.test.ts: the default, blank values skipped, SHA over branch for both providers, the local override over both, a branch name containing a slash, and # encoding.

❓ How to test this?

1. yarn workspace @local/petrinaut-arch-docs doc:architecture and grep a declaredInUrl in bundle/pages/architecture/cli.mdx: it points at blob/main/.
2. Repeat with GITHUB_HEAD_REF=<a branch>: the same link points at that branch. Adding GITHUB_SHA=<sha> switches it to the SHA.

🐾 Next steps

Four hand-written blob/main/... links remain in authored MDX. Those name specific files as references rather than being generated source links; giving them the same treatment needs a link helper in the authoring syntax.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 21, 2026 12:19am
petrinaut	Ready	Preview	Aug 21, 2026 12:19am
petrinaut-docs	Ready	Preview	Aug 21, 2026 12:19am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 21, 2026 12:19am