#16 gave the Workspace Manager and the MCP server references of their own, at /<port>/<version>/workspace/reference/ and /<port>/<version>/mcp/reference/. They are now addressable the same way the core library's is, but they do not read like it: 1,818 declarations across the eight ports get a plainer page than the 10,000 in the core tree.
What a core reference page has that a product page does not
site/src/pages/reference/[...slug].astro is 965 lines; site/src/components/api/ProductApiPage.astro is 35. Both render the same ApiEntry, so a single declaration looks right in either. Everything around it differs:
|
Core reference |
Product reference |
| Sidebar tree |
ApiTree, opened at the page, with tree.json for the rest |
none — the product's prose sidebar |
| Examples |
ApiExampleTabs, one tab per port |
none |
| Equivalents in other ports |
PagePortSwitcher plus an "In other ports" block |
alternativesFor, entry-level only |
| Sections |
seven: members, examples, references, mentions, source, equivalents, module |
two: the entry and its members |
| Index page |
buckets, counts, "By module", symbol cards |
a flat list of roots |
| Markdown twin |
rendered and source, with index.md for the tree |
source only |
Why it matters
The MCP server is the surface an agent discovers the project through, and it is the one with the least navigation: no tree, no examples, no module grouping. Its reference is also the largest of the three products — 1,204 declarations against the Workspace Manager's 614.
The measurement says the same thing. check-xrefs counts cross-references that resolve, and moving Python's 627 product declarations out of the core tree cost 1,102 of them: 13,027 to 11,925. Those references did not stop resolving; the pages that carried them stopped being rendered. Every other port rose, because its product pages were never counted before.
Shape of the work
The product page should be the reference page, parameterised by which tree it belongs to, rather than a second implementation of it:
- Lift the reference route's body into a component both routes render, with the product as a parameter.
- Compile a nav sidecar per product, so each tree has its own buckets.
navSidecar(port, model) already takes a model; it needs a product filter and a third sidecar per port, and check-nav needs to cover all three.
- Serve
tree.json per tree — one already exists per port shell at reference/tree.json.
- Carry the examples and the cross-port equivalents through, which is what the xref count is measuring.
Verification
check-xrefs should recover most of Python's 1,102, and the floor moves up rather than down.
check-type-links, check-canonicals and check-api-fidelity already read all three trees through scripts/reference-trees.mjs, so they cover the new pages without changes.
- The visual baselines gain a product reference page; today all six sample pages are core ones.
Out of scope
Nothing about the URLs, which #16 settled, and nothing about the core reference's own layout.
#16 gave the Workspace Manager and the MCP server references of their own, at
/<port>/<version>/workspace/reference/and/<port>/<version>/mcp/reference/. They are now addressable the same way the core library's is, but they do not read like it: 1,818 declarations across the eight ports get a plainer page than the 10,000 in the core tree.What a core reference page has that a product page does not
site/src/pages/reference/[...slug].astrois 965 lines;site/src/components/api/ProductApiPage.astrois 35. Both render the sameApiEntry, so a single declaration looks right in either. Everything around it differs:ApiTree, opened at the page, withtree.jsonfor the restApiExampleTabs, one tab per portPagePortSwitcherplus an "In other ports" blockalternativesFor, entry-level onlyindex.mdfor the treeWhy it matters
The MCP server is the surface an agent discovers the project through, and it is the one with the least navigation: no tree, no examples, no module grouping. Its reference is also the largest of the three products — 1,204 declarations against the Workspace Manager's 614.
The measurement says the same thing.
check-xrefscounts cross-references that resolve, and moving Python's 627 product declarations out of the core tree cost 1,102 of them: 13,027 to 11,925. Those references did not stop resolving; the pages that carried them stopped being rendered. Every other port rose, because its product pages were never counted before.Shape of the work
The product page should be the reference page, parameterised by which tree it belongs to, rather than a second implementation of it:
navSidecar(port, model)already takes a model; it needs a product filter and a third sidecar per port, andcheck-navneeds to cover all three.tree.jsonper tree — one already exists per port shell atreference/tree.json.Verification
check-xrefsshould recover most of Python's 1,102, and the floor moves up rather than down.check-type-links,check-canonicalsandcheck-api-fidelityalready read all three trees throughscripts/reference-trees.mjs, so they cover the new pages without changes.Out of scope
Nothing about the URLs, which #16 settled, and nothing about the core reference's own layout.