superlore-author

Authoring superlore content ("vibe your docs")

Once a superlore KB exists (see superlore-scaffold), this skill turns a user's intent into real content. The user describes what they want — "add a page on our deployment process", "make a Q3 roadmap", "document the auth service" — and you write MDX that is correct, well-structured, and upholds the dual-representation contract. They never have to learn MDX or the component API.

The one rule: author the data, not a picture

Every superlore component is dual-representation — one authored instance renders for humans and serializes to a typed knowledge face the MCP serves to agents. So you must author the data:

• ✅ <Timeline items={[…]} />, <EntityCard fields={[…]} />, <DataTable rows={[…]} />, <KeyFacts items={[…]} />, <Comparison options={[…]} rows={[…]} />.
• ❌ A screenshot of a roadmap, an ASCII table, or a paragraph that describes a table. That data is then invisible to agents and unsearchable.

If you're about to write a Markdown table or a bulleted list of facts, reach for DataTable or KeyFacts instead so the data survives into the knowledge face. If you're about to describe a system, a flow, or a brainstorm visually, use a Canvas — and invoke the superlore-canvas skill, which knows the full Canvas spec.

Write the natural markdown — superlore upgrades it

Don't reach for a verbose component when plain markdown says it. superlore auto-upgrades the markdown everyone already writes into the styled, dual-representation component — same knowledge face, zero props to remember:

• Task list → Checklist. Write - [ ] todo / - [x] done. (Reach for <Checklist items={…}> only for owners, groups, or refs.)
• GitHub alert → Callout. Write > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION] → Note / Tip / Info / Warning / Danger.
• Fenced ```superlore-canvas `` →Canvas` (the headline visual path).
• A code block is always rendered dark, in any page theme — just fence it with its language.

So: prefer the markdown form first; use the explicit component only when you need a capability the markdown can't express (typed columns, owners, a custom title). A plain Markdown table still renders, but DataTable is better when the rows are real data an agent should read.

Lead with a visual — always include a Canvas

Default to opening the page with (or placing inline) a Canvas that visualizes the thing — the system, the flow, the relationships, the plan. A wall of prose is the failure mode: a reader (and an agent) should grasp the shape at a glance, then read the detail beneath it. Put the Canvas at the top when it frames the whole page; place it inline next to the section it illustrates otherwise.

• Documenting a system or service → a Canvas of its architecture, up top.
• A process / onboarding / runbook → a Canvas of the flow.
• A decision, comparison, or plan → a Canvas mapping the options or the roadmap.
• Even a concept page is clearer with a small Canvas of how the pieces relate.

Invoke superlore-canvas for the spec. The bar: visualize first. Only skip the Canvas when a page is genuinely non-visual (a pure changelog, a glossary) — and then do it deliberately, not by default.

The shape of a superlore page

A page is MDX: a typed frontmatter block, then prose enriched with components.

---
title: Deploying Acme
icon: Rocket
description: How we ship Acme to production — environments, gates, rollback.
summary: Acme deploys via GitHub Actions to Vercel; staging auto-deploys, prod needs an approval, rollback is one click.
tags: [ops, deploy]
---

Prose connective tissue, then components.

<Steps>
  <Step title="Open a PR">…</Step>
</Steps>

Frontmatter (the knowledge envelope)

Field	Required	Purpose
title	yes	H1, nav label, and the unit of MCP get_page
summary	no*	Plain-text gloss — powers search ranking and the first thing agents see
tags	no	Faceting in the UI and MCP list filters
icon	no	lucide icon name in PascalCase (e.g. Rocket, LayoutTemplate)
description	no	Rendered under the title; falls back to summary if unset

* Not schema-required, but always write a summary — it's the single highest-leverage field for search and for what an agent reads first. One plain, specific line.

Anything beyond these is the KB's own — if source.config.ts extends superloreFrontmatterSchema with custom fields, carry them; don't invent fields that aren't in the schema.

Before you author: reconcile the installed version (upgrade if trivial)

superlore moves fast, and the docs/MCP always reflect the latest release — an out-of-date install means missing components, stale props, and silent drift. At the start of an authoring task, reconcile the KB's installed version against latest:

1. Installed — node_modules/superlore/package.json version (or <pm> ls superlore).
2. Latest — curl -s https://superlore.vercel.app/api/version → { "name": "superlore", "version": "x.y.z" }. (Fallback if unreachable: npm view superlore version.)
3. Act on the gap. superlore is 0.x, where a caret pin (^0.14.0) locks the minor — so patch bumps are in-pin and safe, but a minor/major bump is a deliberate, possibly-breaking change:
   • Up to date → proceed; trust the doc page/MCP for props.
   • Patch behind, same major.minor (e.g. 0.14.0 → 0.14.3) → trivial: just upgrade it. Run the KB's package manager — match the lockfile (pnpm up superlore · npm i superlore@latest · yarn up superlore · bun update superlore) — tell the user you did, then author against latest.
   • Minor/major behind (e.g. 0.14 → 0.15; may change props/MDX) → don't silently upgrade. Tell the user a newer version is out, point them at the release notes (/docs/releases), and offer to do the upgrade and fix any pages it affects. Until they accept, author against the installed version (its dist/*.d.mts is the prop source — see below).

This is the same comparison the props lookup keys off: knowing installed-vs-latest tells you whether to trust the MCP or pin to the installed declarations.

Workflow

0. Reconcile the installed version (above) — upgrade if trivial, else note it — so you author against the right component API.
1. Understand the intent and the audience. Internal company KB vs public product docs changes register. Ask only what you genuinely need (the topic, where it lives in the nav).
2. Pick the right surface for the knowledge (see the chooser below). Don't default everything to prose.
3. Find where it goes. Content lives under the KB's docs content dir (in superlore's own docs that's apps/docs/content/docs/**; in a scaffolded KB it's the project's content/docs/**). Add the new page to the section's meta.json so it appears in the nav.
4. Write the MDX — frontmatter first (with a real summary), then prose + components carrying the data.
5. Verify against the MCP if one is connected (see below).

Choosing a component

The knowledge is…	Reach for
Dated events / status over time	Timeline
A typed thing with fields + relations	EntityCard (makes the KB a graph)
Rows you'd sort or compare	DataTable (type numeric columns) / Comparison
Headline numbers	StatGrid
A few key attributes of one thing	KeyFacts
A sprint / sales / hiring board, a retro	Board
A decision with options + criteria	Decision / Comparison
An ordered procedure	Steps / Checklist
Links to related pages	CardGroup + Card
A caveat, tip, or warning	Callout (Note / Tip / Warning / Danger)
A flow, system, brainstorm, or map (visual)	Canvas → invoke the superlore-canvas skill

Browse the full library in superlore's component docs — /docs/components/**, via the superlore-docs MCP or the live site; each page has a live example and shows its knowledge face. For a component's exact API, see Look up a component's props below — get it the version-safe way.

Look up a component's props (version-safe)

When you need a component's exact props or a real usage example, don't read the package's React source, and never dig through ~/.claude/plugins/cache/** — that's the plugin's version line, not the KB's, and it will drift. Use this order:

1. Read the component's reference page — /docs/components/<name> — for the prop table, a live example, and the knowledge face. Fastest via the superlore-docs MCP: get_page (or search "<Component>"). In superlore's own repo it's the local file apps/docs/content/docs/components/<name>.mdx.
2. Mind the version. That MCP serves superlore.vercel.app's latest docs, which can be ahead of the version this KB has installed. Check the KB's pin — node_modules/superlore/package.json version.
   • Matches latest → trust the doc page.
   • Behind → the installed package is authoritative. Read the typed prop interface (it carries JSDoc) from node_modules/superlore/dist/components/<name>.d.mts (e.g. ComparisonProps). Use the doc page only for usage shape/examples, and don't author a prop the installed declarations lack.

The binding contract is always the version the KB's build uses — props can change across releases.

Connect related things

Use relations (depends-on, part-of, related, links) on entities and edges so the corpus is a graph, not a pile of pages — the MCP's navigate tool follows them. Keep headings (and thus section ids) stable, because titles become addresses (${path}#${id}) and inbound links + navigate targets depend on them.

Style (match superlore)

• No emoji in content UI. One accent (violet by default); let structure carry hierarchy.
• Light and dark are co-equal — never hand-author theme-specific values; it's a token swap.
• Lead every page with a summary. Prefer structural components over prose tables and screenshots.

Themes & brand (config, not content)

The whole-site look is a superlore.json choice, never authored per page — keep content theme-agnostic so it works in any skin:

• theme picks the visual skin: default · mint · geist · ledger · obsidian · prism · paste (chrome, type, surfaces, radius/density). accent is one hue that drives the entire palette (light + dark). font / logo / favicon are optional brand overrides that ride any theme.
• These touch presentation only — the Canvas, every component's knowledge face, and the MCP are identical across themes. So author the data; let the theme dress it.
• Document/showcase themes with <ThemeGallery /> if the KB ships it; otherwise the /themes page.

MDX safety — never emit unescaped { … } or <Tag> in prose

In MDX an unescaped { opens a JavaScript expression, so prose like ### GET /users/{id} compiles fine but throws at render (ReferenceError: id is not defined) and can blank the page. This is the mainline for API/SRS content. Neutralize hazards in non-code text:

• API paths / params → wrap in inline code: `/users/{id}` (highest-value rule), or escape: \{id\}.
• ${…} shell/template and {{ … }} mustache → fence or inline-code them.
• <Foo> that isn't a real superlore/HTML component → inline-code or escape (\<).
• Braces inside fenced/inline code are already literal — leave them.

Lint generated MDX before writing it and self-correct. The package ships the check:

import { findMdxProblems } from "superlore/mdx-lint"; // dependency-free; returns string[]
const problems = findMdxProblems(mdx); // e.g. ["line 3: \"{id}\" … wrap in backticks or escape as \\{."]

(The runtime also wraps each doc in an error boundary, so a missed case degrades to a fallback instead of crashing the host — but escape at author time; don't rely on the floor.)

Verify with the MCP

After authoring, if the KB's MCP is connected, point an agent at it and confirm search finds the new page and get_page returns the structure you intended (the timeline's items, the table's rows, the canvas's nodes/edges). If the data isn't there, you wrote a picture — fix it by moving the knowledge into a component. (To connect the MCP, use superlore-connect-mcp.)

Remember

• One source, two faces. Author the data.
• Lead with a Canvas — visualize the thing at the top or inline; prose supports the picture.
• A summary on every page; structural components over prose; stable headings.
• Visual/diagram/whiteboard work → hand off to superlore-canvas.