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

[kube]

🌟 What is the purpose of this PR?

Every generated page links to the file that declared its layer, and the link 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/…

FE-1456 (#9266) sits below in this stack and FE-1455 (#9268) above.

🔗 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 holding 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 because the link still resolves after the branch moves or is deleted. Slashes stay literal as blob-path separators, # and % are encoded, and empty or dot-only segments are dropped, which git refnames forbid anyway.
• architecture.config.ts: sourceUrlPrefix calls the resolver, and no literal main remains.
• turbo.json: the six variables are declared in doc:architecture's env, which strict env mode would otherwise hide from the task. A comment on each side says to keep the two lists identical.
• Logging: 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.
• Forks: the branch-name fallbacks assume the branch lives in hashintel/hash, so GITHUB_HEAD_REF names a branch this repository does not have and the link 404s. The SHA variables win when present and resolve regardless.

No workflow changes: nothing under .github/workflows/ builds the bundle, and GitHub Actions already 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

Two 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 26, 2026 4:40pm
petrinaut	Ready	Preview	Aug 26, 2026 4:40pm
petrinaut-docs	Ready	Preview	Aug 26, 2026 4:40pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 26, 2026 4:40pm

[cursor]

PR Summary

Low Risk
Docs-only link resolution and build logging; no runtime auth, data, or product API changes.

Overview
Generated architecture doc source links no longer hardcode main. A new resolveSourceUrlPrefix / resolveSourceRef layer picks the git ref from CI/Vercel env vars (with PETRINAUT_ARCH_DOCS_SOURCE_REF override, SHA preferred over branch names, main when unset) and builds https://github.com/hashintel/hash/blob/<ref>/ with safe ref encoding.

architecture.config.ts wires that into sourceUrlPrefix; turbo.json lists the same six variables on doc:architecture so strict Turbo env mode does not strip them on preview builds. The CLI and vercel-build.sh log which ref/prefix was used, and the package README documents precedence and fork caveats. source-url.test.ts covers defaults, precedence, slashes, and encoding.

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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.