Found while verifying #7303 (references/contracts/). Out of that card's scope, filed separately per Prime Directive #10. Not self-claimed.
Observation
content/docs/kernel/index.mdx:44 publishes a link into the generated reference tree:
- **Schema reference:** [Kernel](/docs/references/kernel), [System](/docs/references/system), [Contracts](/docs/references/contracts)
/docs/references/contracts does not resolve. content/docs/references/contracts/ contains only meta.json — it is the one category directory under content/docs/references/ with no index.mdx:
$ for d in content/docs/references/*/; do [ -f "$d/index.mdx" ] || echo "NO index.mdx: $(basename $d)"; done
NO index.mdx: contracts
Fumadocs resolves a folder route from its index.mdx — packages/spec/scripts/build-docs.ts says so itself at the emit site:
Fumadocs treats folder/index.mdx as the page for the folder, so this is what makes /docs/references/<category> resolve.
and that emit is guarded by if (zodFiles.size === 0) return;, so a category with no pages never gets one. content/docs/references/meta.json also omits contracts from its pages array, so the category is absent from the sidebar as well.
Why it is a real (if quiet) defect
A reader on the Kernel landing page following "Schema reference → Contracts" lands on nothing. The other two links in the same sentence (kernel, system) both resolve, so the dead one is not visually distinguishable.
Check Documentation Links (lychee) is green today, so this is not caught: the route is internal and unbuilt rather than an HTTP 404 lychee can see. That is the reason it has survived — it is invisible to the only gate that looks at links.
Note on the target
The content the link is reaching for exists, at content/docs/kernel/contracts/ (auth-service / cache-service / data-engine / index / metadata-service / storage-service), and the same page already links there correctly twelve lines up:
<Card href="/docs/kernel/contracts" title="Service Contracts" description="The interfaces services implement" />
So the likely fix is to drop [Contracts](/docs/references/contracts) from the "Schema reference" list — that list is specifically about the generated schema tree, and contracts/ publishes no schema pages into it (all its schemas are unrepresentable in JSON Schema; see #7303 for the mechanism). Dropping it loses no reachability. Deciding that is triage's, not mine.
Scope note
⛔ This is not a request to delete or change content/docs/references/contracts/ — that directory is a generated artifact that pnpm --filter @objectstack/spec gen:docs rewrites, as measured on #7303. Only the hand-written link on content/docs/kernel/index.mdx is in question here.
Generated by Claude Code
Found while verifying #7303 (
references/contracts/). Out of that card's scope, filed separately per Prime Directive #10. Not self-claimed.Observation
content/docs/kernel/index.mdx:44publishes a link into the generated reference tree:/docs/references/contractsdoes not resolve.content/docs/references/contracts/contains onlymeta.json— it is the one category directory undercontent/docs/references/with noindex.mdx:Fumadocs resolves a folder route from its
index.mdx—packages/spec/scripts/build-docs.tssays so itself at the emit site:and that emit is guarded by
if (zodFiles.size === 0) return;, so a category with no pages never gets one.content/docs/references/meta.jsonalso omitscontractsfrom itspagesarray, so the category is absent from the sidebar as well.Why it is a real (if quiet) defect
A reader on the Kernel landing page following "Schema reference → Contracts" lands on nothing. The other two links in the same sentence (
kernel,system) both resolve, so the dead one is not visually distinguishable.Check Documentation Links(lychee) is green today, so this is not caught: the route is internal and unbuilt rather than an HTTP 404 lychee can see. That is the reason it has survived — it is invisible to the only gate that looks at links.Note on the target
The content the link is reaching for exists, at
content/docs/kernel/contracts/(auth-service/cache-service/data-engine/index/metadata-service/storage-service), and the same page already links there correctly twelve lines up:So the likely fix is to drop
[Contracts](/docs/references/contracts)from the "Schema reference" list — that list is specifically about the generated schema tree, andcontracts/publishes no schema pages into it (all its schemas are unrepresentable in JSON Schema; see #7303 for the mechanism). Dropping it loses no reachability. Deciding that is triage's, not mine.Scope note
⛔ This is not a request to delete or change
content/docs/references/contracts/— that directory is a generated artifact thatpnpm --filter @objectstack/spec gen:docsrewrites, as measured on #7303. Only the hand-written link oncontent/docs/kernel/index.mdxis in question here.Generated by Claude Code