The observation
Three hand-written pages under content/docs/ enumerate @objectstack/spec's subpaths or protocol namespaces, and nothing holds them equal to the package's exports map:
| page |
what it enumerates |
content/docs/deployment/troubleshooting.mdx ("Bundle size is too large" → "Available subpaths") |
the importable subpaths |
content/docs/plugins/packages.mdx (@objectstack/spec → Exports) |
the 15 protocol namespaces |
content/docs/getting-started/glossary.mdx ("Protocol Namespace", the layers table, and the per-namespace ### X Protocol sections) |
the 15 protocol namespaces, twice, plus one section per namespace |
When PR #17372 (step 3 of #16325 — which remains open there; this card does not close it) deleted the ./cloud exports entry and added ./marketplace, every mechanical counter of the subpath set moved with it (packages/runtime/src/spec-subpath-alias-coverage.pin.test.ts, packages/spec/scripts/export-origins.test.ts, root-meta.test.ts, llms.txt via check:llms-txt, quick-reference.mdx via check:quick-reference-counts) — and all three pages above kept advertising cloud and never listed marketplace, because no gate reads them. The contract-review pass on that PR caught troubleshooting.mdx; the sweep it asked for found the other two. They were corrected by hand in the PR's patch round (ef1fda259).
Measured on that head: git grep -n -E 'Kernel, Cloud|Security, Cloud|cloud, qa' -- content/docs returns 0 lines (same-shape control naming Marketplace returns 4), so the pages are current today — the finding is that nothing keeps them current.
What a fix could look like
Any one of these; the first is the cheapest:
- Extend
packages/runtime/src/spec-subpath-alias-coverage.pin.test.ts (it already reads packages/spec/package.json's exports and derives PUBLISHED_SUBPATHS) — or a root check:docs-* gate — to read the three enumerations and hold them equal to the derived set, the way check:quick-reference-counts holds quick-reference.mdx's per-section counts.
- Have
packages/spec/scripts/build-docs.ts emit a generated subpath / namespace snippet that the three pages include, so the enumeration is produced rather than typed.
- Reduce the hand-written enumerations to one page and link the other two to it.
Note the troubleshooting list and the namespace lists are two different sets: the exports map has 16 ./* entries (meta-spelling is a subpath but not a protocol namespace), the namespace lists have 15.
Generated by Claude Code
The observation
Three hand-written pages under
content/docs/enumerate@objectstack/spec's subpaths or protocol namespaces, and nothing holds them equal to the package'sexportsmap:content/docs/deployment/troubleshooting.mdx("Bundle size is too large" → "Available subpaths")content/docs/plugins/packages.mdx(@objectstack/spec→ Exports)content/docs/getting-started/glossary.mdx("Protocol Namespace", the layers table, and the per-namespace### X Protocolsections)When PR #17372 (step 3 of #16325 — which remains open there; this card does not close it) deleted the
./cloudexports entry and added./marketplace, every mechanical counter of the subpath set moved with it (packages/runtime/src/spec-subpath-alias-coverage.pin.test.ts,packages/spec/scripts/export-origins.test.ts,root-meta.test.ts,llms.txtviacheck:llms-txt,quick-reference.mdxviacheck:quick-reference-counts) — and all three pages above kept advertisingcloudand never listedmarketplace, because no gate reads them. The contract-review pass on that PR caughttroubleshooting.mdx; the sweep it asked for found the other two. They were corrected by hand in the PR's patch round (ef1fda259).Measured on that head:
git grep -n -E 'Kernel, Cloud|Security, Cloud|cloud,qa' -- content/docsreturns 0 lines (same-shape control namingMarketplacereturns 4), so the pages are current today — the finding is that nothing keeps them current.What a fix could look like
Any one of these; the first is the cheapest:
packages/runtime/src/spec-subpath-alias-coverage.pin.test.ts(it already readspackages/spec/package.json'sexportsand derivesPUBLISHED_SUBPATHS) — or a rootcheck:docs-*gate — to read the three enumerations and hold them equal to the derived set, the waycheck:quick-reference-countsholdsquick-reference.mdx's per-section counts.packages/spec/scripts/build-docs.tsemit a generated subpath / namespace snippet that the three pages include, so the enumeration is produced rather than typed.Note the troubleshooting list and the namespace lists are two different sets: the exports map has 16
./*entries (meta-spellingis a subpath but not a protocol namespace), the namespace lists have 15.Generated by Claude Code