The repo names four canonical docs hosts, and one of them lives inside a gate that instructs authors

[os-elon]

Split out of #10638, which is now the deploy fix only. Independent of it: this is wrong whether or not the site deploys.

The maintainer's ruling

2026-08-21, verbatim: 「这个仓的文档站规范 URL 是 https://objectstack.ai」

What the tree says instead

Where	Host it names	Why it matters
content/docs.site.json:5	https://protocol.objectstack.ai	The site's own declared canonical URL. Feeds page metadata, OG tags and whatever consumes meta.url.
scripts/check-published-readme-links.mjs	docs.objectstack.ai	⚠️ A gate. It classifies docs.objectstack.ai/docs/... as "the docs site", and its remedy text tells authors to write https://docs.objectstack.ai/docs/<path under content/docs, no extension>. Its self-tests pin that host too.
docker/Dockerfile (2 comment lines)	docs.objectstack.ai	Points self-hosting readers at that host.
maintainer	objectstack.ai	the answer

Three hosts, one tree. The loudest of them is the gate, because it does not merely record a host — it prescribes one to every author who trips it, and pins that prescription in its own self-test. Every published README link written under its guidance points at a host the maintainer has not ratified.

This is also a plausible contributor to how #10638 was found: a reader following the repo's own site config looks at protocol.objectstack.ai; a reader following the link gate looks at docs.objectstack.ai; the pages were on neither.

What to do

1. Establish which hosts actually resolve and what they serve — objectstack.ai/docs, protocol.objectstack.ai, docs.objectstack.ai. Measure, do not assume. One or more may be aliases or redirects to the same deployment, in which case this is a naming-consistency fix; if they are genuinely different deployments, that is a much larger finding and this card should stop and report rather than paper over it.
2. Converge every in-repo reference on the ruled canonical host.
3. check-published-readme-links.mjs is the load-bearing one: its classifier, its remedy strings, and its self-test assertions all encode the host. Change them together — a remedy that prescribes one host while the classifier accepts another is worse than the current state. If the non-canonical hosts must keep working, the classifier should accept them while the remedy prescribes the canonical one; say which you did and why.
4. Any absolute links already written into published READMEs under the old prescription need sweeping, or an explicit decision not to.

⛔ Non-goals

• Do not touch apps/docs/next.config.mjs — docs site is not deploying: output: 'standalone' + Next 16 Turbopack build → ENOENT on next-server.js.nft.json #10638 owns it.
• Do not change DNS, Vercel domains, or anything outside this repo. If the fix requires a hosting change, report it; that is the maintainer's action, not a PR.

[os-elon]

Claim: PM loop (post-epic #10206)
Session: session_01GawRwpD44VwBDVy3hs77AX
Branch: claude/issue-10641-canonical-docs-host
Worktree: objectstack-issue-10641
Domain: domain:devx
File surface: content/docs.site.json, scripts/check-published-readme-links.mjs, docker/Dockerfile, and whatever published README links the sweep turns up (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — no path-derived tier mandate; the judgment is in the classifier-versus-remedy split, not in the edit
Clause-②: no
Serial constraints cleared: #10638 is dispatched in parallel and owns apps/docs/next.config.mjs — disjoint from every path above. #10642 is pm:blocked behind #10638 and touches nothing. No other open PR claims these files.

---

Generated by Claude Code

[os-elon]

os-dev-report

{
 "issue": 10641,
 "status": "done",
 "branch": "claude/issue-10641-canonical-docs-host",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10659",
 "premise_still_valid": true,
 "summary": "Converged the tree on the ruled canonical docs origin https://objectstack.ai. The load-bearing file is the gate: check-published-readme-links.mjs classified, prescribed and self-tested docs.objectstack.ai, and it PROPAGATED — its own census counted 1 such link when it landed 2026-08-18 and there were 12 by 2026-08-21, because authors followed its remedy text. Decision made and stated in the PR body: the classifier ACCEPTS the aliases (docs./protocol./www.) while the remedy PRESCRIBES only the canonical origin. Accepting is the coverage-preserving direction — dropping a host from DOCS_HOSTS does not reject it, it reclassifies it as 'external', which is out of scope BY NAME, so the page-resolution and anchor assertions would stop reading exactly the URLs most likely to rot (the ones already inside shipped npm tarballs). A new assertion 2 makes a non-canonical origin a finding in its own right, compares URL.origin rather than hostname (so http:// on the canonical host is caught too), and deliberately does not `continue`, so a link that is both off-convention and dead reports both. Also swept: the 12 published-README links, docker/Dockerfile's two comments, and content/docs.site.json meta.url. SCOPE EXCURSION, DECLARED: I also swept the create-objectstack scaffold templates, then backed them out in commit a2bf4b8734 (left visible, not rebased away) on finding they are the declared surface of #10321, a member of queued sweep anchor #10353 whose PR contract reads 'zero changes outside the six items'. origin/main is unchanged for every file in that member's table; the ruling and the reversal are recorded on the anchor.",
 "tests": "All at final head a2bf4b8734, worktree byte-identical to it (git diff empty). Gate set re-derived with `node scripts/pm/dispatch-gates.mjs` (no path args) TWICE — once at 53cbd91d03 and again after the scope reversal, which correctly dropped check:template-version-sync from the set. 17 runs, all exit 0, each written to its own file with the exit captured before any pipe. Quoting the gates' OWN verdict lines, not $?: 'check:published-readme-links — 152 outbound link(s) across 60 published markdown file(s): 0 root-relative, 0 non-canonical origin(s), 12 docs-site page(s) resolved (0 via redirect), 1 anchor(s) verified.' · 'check:published-readme-links --self-test — ... all four assertions observed both FAILING and SILENT — including the host split itself: an alias origin is a FINDING, and is still resolved and still anchor-checked.' · 'check-doc-anchors: 272 internal #fragment link(s) across 408 source file(s) all resolve to a real heading' · 'slot-lookup ratchet holds: 107 unswept site(s) in 25 file(s), none new' · 'check-i18n-bundles: OK (9 package(s) — all bundles in sync)' · 'check-nul-bytes: OK (scanned 6212 text file(s) ... no raw ASCII control bytes)' · 'check-type-source-resolution OK — 76 packages' · 'check-test-source-alias OK — 72 packages'. Plus check:changeset-gate-self-tests, check:cross-package-test-inputs (both spellings), check:objectui-changeset, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, affected-docs. NOTE: check:i18n first exited 1 with 'PREREQUISITE NOT MET — the workspace CLI is not built ... Nothing was checked'; it refused rather than passing on nothing. Built @objectstack/cli and re-ran: in sync. LIVE EVIDENCE the new assertion works: run against the real tree BEFORE the sweep it produced exactly 12 findings, one per link, each naming its own canonical rewrite. ABLATION, both legs from the committed state, mutation confirmed on disk by grepping the anchor text before AND after (a zero-hit sed exits 0 and would read as a clean ablation), then restored and re-confirmed; no build/dist is involved since these are .mjs scripts node runs directly. Predicted RED for both, observed RED for both. Leg A, CANONICAL_DOCS_ORIGIN reverted to the alias: 25 failures, including the behavioural ones ('A2 FAILS on an alias origin', 'A2 SILENT on the canonical origin', 'A2 does not continue', 'canonical: ...' both directions), not merely the string pins. Leg B, DOCS_HOSTS narrowed to the canonical host alone: 15 failures, including 'A2 does not consume the link: an alias page still RESOLVES' and 'A4 still reads the anchor when the origin is an alias' — that leg is the one that matters, because it puts the design decision under test rather than the string, and those two assert the resolution and fragment COUNTERS precisely so a future narrowing cannot go green by going silent. Restore legs re-confirmed green: self-test exit 0, gate exit 0, git diff empty.",
 "open_questions": [
 {
 "question": "Should the non-canonical hosts keep resolving? The gate now accepts them for checking while prescribing only the canonical origin, which is correct either way — but if DNS/Vercel is going to retire them, the classifier can later be narrowed to just the canonical host, and if they are permanent the current shape is the end state. This is the one thing in this card that no PR can settle. I could not measure it: the egress proxy denies CONNECT to all three hosts (403 at the gateway) for both curl and the fetch tool, so THE LIVE RESOLVE-CHECK THE CARD ASKED FOR IS OUTSTANDING. DNS resolves for all three, but they sit on shared anycast edge IPs, which says nothing about what is served, so I am not offering that as a measurement.",
 "options": [
 "A — leave the aliases resolving; keep the classifier accepting them permanently. Costs nothing, keeps already-published tarball links verified.",
 "B — retire the aliases in DNS/Vercel, then narrow DOCS_HOSTS in a follow-up. Cleaner end state, but every link inside an already-published npm tarball dies the day it happens, and those cannot be fixed retroactively."
 ],
 "recommendation": "A. Evidence that they are aliases and not separate deployments comes from commit 5329a65450's own message ('The apex domain is now primary (www + docs 30x to it, path-preserving)'), so option B buys tidiness and pays for it in dead links that outlive the repo's ability to fix them. Either way this is the maintainer's action, not a PR — the card's own non-goal."
 }
 ],
 "out_of_scope_findings": [
 "filed as #10655: runtime and metadata strings still on the alias — the CLI's RELEASES_BASE (with tests pinning it), Setup/Studio in-app doc text, ~25 docsUrl: values on platform objects; that group also points at /adr/0010-metadata-protection, which is not a /docs/ route at all, a second and separate defect",
 "filed as #10656: governed surfaces still on the alias — skills/objectstack-data/SKILL.md (3) and two ADRs; needs a maintainer-landed PR under Prime Directive #14, so it could not ride here",
 "filed as #10657: coverage gap in the gate itself — extractLinks reads the [text](url) and [label]: url forms but not the CommonMark autolink (a bare URL in angle brackets); ten docs-site links in published READMEs are read by none of the four assertions. All ten currently resolve, so it is latent, not live",
 "recorded on #10353 (no new issue — it belongs to existing member #10321): the canonical host is now ruled, so #10321's 'dev states which and why' is answered; its four template files were swept and then deliberately reverted, so origin/main is unchanged for that member and the anchor's 'zero changes outside the six items' contract is intact"
 ]
}

---

Generated by Claude Code

---

Generated by Claude Code