Skip to content

Give the Workspace Manager and MCP references the treatment the core one gets #17

Description

@tony

#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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions