Skip to content

Documents

A document is one markdown file. It is the atom of your canonical corpus: written once, versioned forever, and belonging to exactly one corpus.

Documents → Document (the + button). Enter a Title and the Markdown body, then Create.

A new document starts in Drafts, the unpublished space. Agents cannot see it there. To publish it, move it into a corpus: open it, choose Move, and pick the corpus. See Corpora.

The title is turned into a stable slug — API Style Guide becomes api-style-guide. The slug is the document’s stable internal identity, and it does not change when you rename the title later. Agents usually refer to uploaded documents by their Corpus path, while slugs remain available in MCP responses for stable low-level addressing. If a document with that slug already exists you’ll see “A document with this title already exists.” — pick a different title.

Open a document and start writing. Markdown renders inline as you type; clicking formatted text reveals its syntax. Use Source to show all Markdown syntax. Switching views preserves your draft, selection, and undo history.

The editing controls provide bold, italic, strikethrough, inline code, links, and indentation. Insert / change… adds a heading, quote, list, code block, or table, or converts selected lines to a different block type. Tables are inserted as editable Markdown; visual row and column editing is not available.

Use Cmd on macOS or Ctrl elsewhere:

Action Shortcut
Bold / italic / link Cmd/Ctrl+B / I / K
Inline code / strikethrough Cmd/Ctrl+Shift+C / X
Indent / outdent Cmd/Ctrl+] / [
Nest / unnest list items; indent / outdent code Tab / Shift+Tab
Undo Cmd/Ctrl+Z

Enter continues lists, tasks, and quotes; Enter on an empty item exits it. Tab moves a list item’s nested children with it. Outside lists and code, Tab moves keyboard focus. Press Escape, then Tab, to leave the editor from a list or code block. Keyboard shortcuts below the controls shows these bindings while you write.

The link action opens a small editor for the link text and destination. Selected text fills the label; within an existing inline link, both fields are filled for editing. Choose Insert link or Apply to make the change, or press Escape or Cancel to leave the document unchanged. A destination is required: use a complete web address, document path, or #section.

Click Save to commit, or Discard to discard the draft. Each save creates a new version (see Versioning & history).

Prefer your own editor, or editing from CI? The CLI pulls and pushes the same documents from a terminal, with the same versioning.

While editing, Corpus checks markdown links that point at other documents in this project. If a link points at a slug that doesn’t exist, the editor shows a count (e.g. “2 links to a missing document”). It’s a warning, not a block — you can still save. Fix it by correcting the slug or creating the target document.

Use Rename on the document page to change the displayed title. This is metadata only: it does not change the slug and does not create a new content version. The Corpus path comes from the document’s folder and filename, not its title.

You can put a YAML frontmatter block at the top of any document:

---
owner: platform-team
status: stable
audience: backend-agents
---
# Backend conventions
...

Frontmatter is a read-time lens, never a mutation. The canonical file an agent reads is returned verbatim — frontmatter and all. Corpus also exposes the parsed frontmatter separately (the read_document_meta MCP tool) so an agent can branch on status or audience without parsing it itself. The body and its version hash are never altered by frontmatter.

If the YAML is malformed, the save is rejected with “invalid YAML frontmatter: …”. Either fix the YAML or remove the block.

Have docs already written somewhere? Click Upload on the Documents page (or drop files into the empty-state uploader). Drag a folder, pick individual files, or drop a .zip — Corpus keeps the folder structure, imports every Markdown/text file under it, and lands you on Documents with a summary toast (12 added · 3 updated · 1 failed). Choose the corpus the files land in; leave it on Drafts to publish them later. Each imported file becomes a canonical document; re-uploading an unchanged file is a no-op, and an edited file appends a new version. The same slug-collision rule applies within a folder.

When an agent reads a document from its corpus, it gets the exact markdown you wrote, at the current version. Documents in Drafts are never returned to an agent. Write for the agent: clear headings, explicit rules, no implicit context. See Recipes for patterns.

Documents are read-only over MCP: an agent can never write one directly. It can file a proposal with suggest_edit, which a person accepts or rejects, hunk by hunk, in the web UI. That asymmetry is deliberate — your canonical documents can’t be silently rewritten by an agent.