ci: dual-publish docs to github pages and vercel

[armcconnell]

Serves the docs at docs.doublezero.xyz (Vercel, new canonical) while docs.malbeclabs.com keeps running on GitHub Pages unchanged.

Design and plan: PR #193 (.specs/2026-08-10-docs-dual-publish-*.md).

Why a second origin

GitHub Pages allows one custom domain and matches it against the incoming Host header, so a second hostname can't just be another DNS record pointing at malbeclabs.github.io — GitHub would 404. Adding Vercel as a real second origin is the only option needing no cutover, so the existing hostname has zero downtime.

Summary

• One mkdocs build feeds both deploys via the same tar artifact, so byte-identical output across origins is provable rather than aspirational.
• site_url moves to docs.doublezero.xyz, consolidating canonical tags, sitemap.xml, robots.txt, and .well-known on the future hostname even for pages served from the legacy one.
• site_name changes to DoubleZero. Note this is a single shared build, so the header and <title> change on both origins.
• 26 absolute docs.malbeclabs.com cross-links converted to relative mkdocs links across 17 files and 8 locales. Five links in the same tenant table were already relative, so the absolute ones were the inconsistency.
• --strict added, so broken internal links now fail CI.
• Fork PRs skip the Vercel job because they can't receive secrets; they still get the build as validation. pull_request_target deliberately not used — it would expose the Vercel token to untrusted PR code.
• docs/CNAME unchanged. Pages keeps docs.malbeclabs.com.

Incidental: untracked site/ (was gitignored but still tracked, so any local build dirtied 190+ files); dropped contents: write and the git-credentials step, since Pages is build_type=workflow and deploy-pages never pushes a branch.

Current state

docs.doublezero.xyz is live and serving. docs.malbeclabs.com still serves its own build with no redirect. Merging converges them.

Testing Verification

Verified against a live Vercel deployment before CI was wired, to settle assumptions rather than trust them:

• .well-known/ dot-directory is served at the edge (index.json, SKILL.md, mcp/server-card.json all 200). This was the main risk: actions/upload-artifact drops hidden files by default, which is why both deploys route through a tar.
• Missing paths return a real 404 with the styled MkDocs page, not a 200 or a bare Vercel error.
• All 8 locales serve on both the new origin and in-build.
• Deployed .well-known SHA-256 matches the local build, confirming the edge serves the same bytes.
• /setup and /setup/ share the identical canonical, so trailing-slash variants consolidate instead of duplicating.
• Link conversion checked per locale: relative hrefs stay inside their locale prefix (../DZ%20Mainnet-beta%20Connection/ from /es/tenant/ → /es/…), and every localized target exists.
• Angle-bracket link destinations chosen empirically — percent-encoded %20 wasn't assumed to survive mkdocs' file lookup, so one link was converted and its rendered href inspected before the other 25.
• Build diff asserted programmatically as exactly the expected 35 files.
• Let's Encrypt cert valid, Cloudflare grey cloud confirmed (resolves to Vercel IPs, not proxy IPs).
• docs.malbeclabs.com confirmed returning 200 with an empty redirect target throughout.

translate.yml pushed 4921f21 (21 localized files, 1459 insertions). Confirmed it did not clobber the link conversion: no absolute links returned, all 14 localized tenant/troubleshooting files kept their relative destinations, and --strict still passes.

After merge

Digest parity across origins currently differs by design, since main still serves the old build. Post-merge, sitemap.xml and .well-known/* should match byte for byte; llms.txt embeds site_name as its H1 so it matches too under this shared build. Needs verifying once merged.

[armcconnell]

Ready to merge: docs.doublezero.xyz is live

The sequencing hazard that kept this in draft is cleared. docs.doublezero.xyz now resolves and serves the site, so merging no longer risks pointing canonical tags at a dead hostname.

Verified on the live new origin:

• Root 200, missing paths return a genuine 404 with the styled MkDocs page
• All 8 locales serving (/, /es/, /fr/, /it/, /ja/, /ko/, /pt/, /zh/)
• All machine endpoints serving: .well-known/agent-skills/index.json, .well-known/mcp/server-card.json, llms.txt, llms-full.txt, sitemap.xml, robots.txt
• Let's Encrypt certificate valid through Nov 8, Cloudflare grey cloud confirmed (resolves to Vercel IPs, not proxy IPs)

Verified the legacy origin is untouched:

• docs.malbeclabs.com returns 200 with an empty redirect target, so it serves its own content rather than redirecting
• docs/CNAME still reads docs.malbeclabs.com

Note on the auto-translate commit

translate.yml fired on this PR and pushed 4921f21, rewriting 21 localized files (1459 insertions). Checked specifically whether it clobbered the relative-link conversion, since that was the plausible failure mode:

• No absolute docs.malbeclabs.com links reappeared
• All 7 localized tenant files kept ](<DZ Mainnet-beta Connection.md>) and ](<DZ Testnet Connection.md>)
• All 7 localized troubleshooting files kept ](<setup.md>)
• mkdocs build --strict still exits 0 on the merged result

Its CI runs initially landed as action_required because github-actions[bot] triggered them; approved, and both are green on 4921f21.

Remaining after merge

Digest parity between the two origins currently differs, which is expected while main still serves the old build. Once this merges, both origins should serve byte-identical content for .well-known/agent-skills/index.json, llms.txt, and sitemap.xml. I'll run that check post-merge.

[Jared-dz]

This is certainly a PR.