docs(spec): the protocol upgrade guide's public address is one docs-site page per protocol major; docs/protocol-upgrade-guide.md becomes a pointer stub (#22449 B′, condition 2)

.changeset/22483-upgrade-guide-docs-address.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the protocol upgrade guide has a public address, one docs-site page per protocol major
+
+Clause-②: no
+
+The guide is published on the docs site, one page per protocol major, at `https://objectstack.ai/docs/protocol-upgrade/N`; `https://objectstack.ai/docs/protocol-upgrade` lists them all. A link to one major keeps resolving after the next major opens. The site builds from `main`, so each page says whether its major is released, in prerelease, or not released yet.
+
+`docs/protocol-upgrade-guide.md` in the repository, which earlier READMEs and changelog entries point at, is now a short pointer naming that address.
+
+What a release shipped is unchanged: `protocol-upgrade-guide.md` inside the package and attached to its GitHub Release. Its only change is the header comment, which now names the command that writes the file.
+
+Nothing changes for an author, and nothing is renamed or removed.

.gitattributes

@@ -17,22 +17,37 @@
 # stay routed here as directories: the driver still owns a same-category
 # collision, which is the residue sharding cannot remove.
 #
-# Two entries below are still SINGLE files — spec-changes.json and
-# docs/protocol-upgrade-guide.md — and #8344 asked what the driver-less queue does
-# to them. MEASURED (2026-08-13, the real in-flight case plus four synthetic pairs,
-# each merged in a clone with no merge.os-regen.driver): it never leaves them
-# stale-but-clean. Both are sorted unions and an ADR-0087 registration is
-# insertion-only, so the queue's text merge either takes both sides — byte-identical
-# to the regeneration, gates green — or conflicts outright. It conflicts only when
-# the two in-flight entries are ADJACENT in registry sort order; one existing entry
-# between them is already enough to merge clean AND current.
-#
-# Sharding them would not buy back an ejection, which is why they are still single
-# files: every conflicting case also conflicts in
+# One entry below is still a SINGLE file — spec-changes.json — and #8344 asked
+# what the driver-less queue does to it. MEASURED (2026-08-13, the real in-flight
+# case plus four synthetic pairs, each merged in a clone with no
+# merge.os-regen.driver, over it and the protocol upgrade guide, then a second
+# committed single file): the queue leaves neither stale-but-clean. Both were sorted
+# unions and an ADR-0087 registration is insertion-only, so the queue's text merge
+# either takes both sides — byte-identical to the regeneration, gates green — or
+# conflicts outright. It conflicts only when the two in-flight entries are ADJACENT
+# in registry sort order; one existing entry between them is already enough to
+# merge clean AND current.
+#
+# Sharding it would not buy back an ejection, which is why it is still a single
+# file: every conflicting case also conflicts in
 # packages/spec/src/migrations/registry.ts — generated, committed, unsharded,
 # NOT_DRIVER_MANAGED — and every registration touches it by construction. The table
 # and the reproduction are in packages/spec/src/migrations/entries/README.md.
 #
+# docs/protocol-upgrade-guide.md LEFT this list at #22483 because nothing generates
+# it any more. It is a hand-written pointer stub naming the guide's public address,
+# and `gen:upgrade-guide` writes the gitignored docs pages under
+# content/docs/protocol-upgrade/ instead (NOT_DRIVER_MANAGED records that path). A
+# route there was harmful, not idle: the driver kept OURS whole, and the pre-commit
+# discharge then passed it, because `check:upgrade-guide` compares no committed
+# copy — so a branch carrying a generated guide merged the stub away in silence.
+# Unrouted, a merge made from a checkout that carries this file conflicts on the
+# stub. ⚠️ git reads the route from the checkout DOING the merge, so a branch
+# forked before #22483 still defers the guide on its first merge of main; the merged
+# tree has no row to discharge it against, so the next commit and the push are
+# refused instead of passed (measured on PR #22556 with the previous head as the
+# control, both merge directions).
+#
 # `merge=os-regen` hands those paths to `scripts/git-merge-regen.mjs`, which does
 # NOT text-merge them. See that file for why it also does not regenerate them
 # in place (git runs merge drivers BEFORE the sources are merged, so anything
@@ -173,7 +188,6 @@ packages/spec/src/meta-spelling/meta-url-data.generated.ts   merge=os-regen
 packages/spec/export-origins/**                              merge=os-regen
 packages/spec/declaration-map/**                             merge=os-regen
 packages/spec/api-surface-signatures.json                    merge=os-regen
-docs/protocol-upgrade-guide.md                               merge=os-regen
 docs/audits/2026-07-unknown-key-strictness-ledger.counts/**  merge=os-regen
 content/docs/references/**                                   merge=os-regen
 content/docs/permissions/system-context.mdx                  merge=os-regen

.gitignore

@@ -103,6 +103,9 @@ next-env.d.ts
 .source/
 apps/*/. source/
 apps/*/.next/docs/
+# The protocol upgrade guide's docs pages: generated at docs build by
+# `pnpm --filter @objectstack/spec gen:upgrade-guide`, never committed.
+content/docs/protocol-upgrade/
 .turbo
 
 # Local env overrides (may contain secrets)

apps/docs/package.json

@@ -6,7 +6,7 @@
   "license": "Apache-2.0",
   "scripts": {
     "dev": "next dev",
-    "build": "pnpm --filter @objectstack/spec gen:schema && pnpm --filter @objectstack/spec gen:docs && NODE_OPTIONS='--max-old-space-size=4096' next build",
+    "build": "pnpm --filter @objectstack/spec gen:schema && pnpm --filter @objectstack/spec gen:docs && pnpm --filter @objectstack/spec gen:upgrade-guide && NODE_OPTIONS='--max-old-space-size=4096' next build",
     "start": "next start",
     "site:lint": "next lint",
     "postinstall": "fumadocs-mdx",

content/docs/meta.json

@@ -14,6 +14,7 @@
     "ai",
     "api",
     "upgrading",
+    "protocol-upgrade",
     "---Platform---",
     "deployment",
     "plugins",