Architecture
How superlore serves humans and agents from one structured source.
superlore is content-first. Your MDX, plus a typed frontmatter schema, is the source of truth. A build step derives a structured index (pages → sections → components, plus a relationship graph) — the corpus — and both the human site and the agent MCP are projections of it. The board below is itself a superlore Canvas: one authored graph, rendered for you and served to agents.
The dual-representation contract
This is the core invariant. Every component has two faces, produced from one authored instance:
Render face
A polished React component for the human site — tokens only, light and dark co-equal.
Knowledge face
A typed serialization the MCP exposes to agents — the records and relations behind the visual, never a description of a picture.
If you add a component, you implement both faces. A component that can't serialize to the MCP isn't done. This is what existing tools can't cross: their components are render-only, and the MCP was retrofitted over the output.
Building blocks
Principles
- Source of truth
- Content, not render output
- Two faces
- Render + knowledge, never drifting
- Tokens
- No raw hex; never branch on theme in JS
- Reuse
- Lives in the superlore package, not copy-pasted
- Deploy
- Yours — Vercel or any Next host
For the full component catalog and the knowledge-face shapes, see Components — the structural differentiators (Timeline, EntityCard, DataTable, Canvas) each carry a typed knowledge face.
Migrate to superlore
Move your existing docs — Mintlify, Docusaurus, Fumadocs, Nextra, GitBook, or plain Markdown — into superlore. Plan-first, you review and comment, then it migrates and proves it built.
Dual representation
The core invariant — every superlore component renders for humans and serializes a typed knowledge face for the MCP, from one authored instance.