Inline components are the heart of the editor. Instead of describing an endpoint or a DTO in flat text, you reference the real entity — and the editor renders it as a live chip or card that links to the source and updates when the entity changes. In your markdown file they're plain, readable XML tags, so they diff cleanly in git and your agent can read and write them too.
You rarely type these tags by hand: insert them from the slash menu and edit them with alt-click (option-click on a Mac). The tags below are simply what ends up in your file.
Reference an entity
There are five ways to reference your entities, from a tiny inline mention to a dynamic, self-updating list.
inline_mentionAn inline chip in your prose. Click it to open the entity.single_elementA block-level card showing one entity's full details.element_listA fixed, ordered list of entities you choose by slug.tagged_listA live list of one type, filtered by tags — updates as entities are tagged.tagged_list_mixedA live list across every type, filtered by tags.An inline mention sits in a sentence and renders as a chip:
Endpoint <inline_mention type="endpoint" slug="get-users-list"/> returns the user list.A single element pulls in the whole entity as a card:
<single_element type="endpoint" slug="get-users-list"/>An element list shows a handful of entities in the exact order you list them:
<element_list type="endpoint" slugs="get-users-list,create-user,delete-user"/>A tagged list is dynamic — it asks for a type and a set of tags, and stays
current as you tag and untag entities. filter is optional and defaults to and
(every tag must match); use or to match any:
<tagged_list type="endpoint" tags="auth,public" filter="or"/>A mixed tagged list drops the type and gathers matching entities of every kind into one list:
<tagged_list_mixed tags="auth" filter="and"/>Link to a heading
A section reference points at a heading — on the current page or another one. It
renders as a chip showing the heading's text; clicking it scrolls to that heading
with a brief highlight pulse. Insert one with /section:
See <section_ref anchor="diag9000"/> for the diagram rules.Link to another page
To reference a whole spec page, type @ and start typing its path — autocomplete
suggests matching files, and Enter inserts a chip showing the page's title. Add a
#anchor to jump to a specific heading on that page:
See @modules/m05-chat-agent.md for the chat flow.Two older forms are recognised automatically, so existing specs light up without any
migration: a path in inline code becomes a chip if the file exists, and a standard
markdown link [label](modules/m05.md) becomes a chip with your own label. Whichever
form you use is preserved in the file. If you later rename a page, every link to it
updates itself within about a second.
Not every @ is a page link. A scoped npm package like @scope/package and an
email like user@example.com aren't files in your spec, so they stay as plain
text — only real paths in your pages directory turn into chips.
When a reference breaks
References are checked but never block you. If an entity is deleted, its type is
turned off, or a section anchor no longer exists, the reference renders as a
red-bordered chip — [broken: slug] for an entity, [not found: path] for a page
link. Clicking a broken reference offers to fix it: create the missing entity or
page, or remove the reference. Your page still saves; nothing is lost.