Authoring for agents

This page is written for agents (and the humans directing them) producing superlore content. If you are an agent asked to "write the docs," follow this.

The superlore format

A superlore document is MDX: a YAML frontmatter block, then Markdown prose enriched with superlore components. Same format whether a human or an agent writes it.

---
title: Page title
summary: One-line, plain-text gloss used for search and the MCP.
tags: [topic, area]
---

Prose, then components.

Frontmatter fields

Field	Required	Purpose
title	yes	Page title; the unit of MCP get_page
summary	no	Plain-text gloss for search + MCP snippets
tags	no	Faceting and MCP list filters
description	no	Rendered under the title (falls back to summary)

The one rule: think in data

superlore components are dual-representation — each renders for humans and serializes to a typed knowledge face for the MCP. So author the data, not a picture:

Use <Timeline items={[...]} />, <EntityCard fields={[...]} />, <DataTable rows={[...]} />. The agent reading your KB later gets clean records.

Don't

Don't paste a screenshot of a roadmap, or describe a table in prose. That data is then invisible to agents and unsearchable.

Choosing a component

Dated events, status over time

Timeline

A typed thing with fields + relations

EntityCard — makes the KB a graph

Rows you'd want to sort or compare

DataTable (type numeric columns)

A flow, sequence, or dependency graph

Canvas (typed nodes + edges)

An ordered procedure

Steps

Links to related pages

CardGroup + Card

A caveat, tip, or warning

Callout (Note/Tip/Warning/Danger)

Best practices

Lead with a summary

Give every page a summary. It powers search ranking and the snippet an agent sees first.

Prefer structural components over prose tables

If you're about to write a Markdown table or a bulleted list of facts, reach for DataTable or KeyFacts so the data survives into the knowledge face.

Use refs to connect things

Link entities and pages with relations (depends-on, part-of, related). The MCP's navigate tool follows them.

Keep ids stable

Titles become ids. Renaming a heading changes its address — keep them stable so links hold.

One accent, no emoji

superlore core UI uses a single violet accent and no emoji. Let structure carry hierarchy.

Verify with the MCP

After authoring, point an agent at the MCP and confirm search finds your page and get_page returns the structure you intended. If the data isn't there, you wrote a picture.