.md) document for prose: findings, conclusions, and the argument that connects them. Use notebooks for the code and analysis, and a writeup for the story you tell about it.
A writeup is an ordinary .md file. You can read it in any editor, diff it in Git, and open it outside Qualia.
Create a writeup
- Choose File > New File… or press Cmd/Ctrl+N.
- Enter a name and choose Write-up.
.md file titled with the name you entered. Any Markdown file opens as a writeup when its frontmatter says so:
# heading is the document’s title. Markdown files without qualia: writeup open in the standard source-and-preview editor.
Ask Qualia to write
Ask in chat to write up your findings or revise a passage. For example, try “Write up the model comparison for a reader who hasn’t seen the notebooks.” Qualia uses the built-inwriteups skill whenever it drafts or edits writeup prose, including revisions requested in comments. A skill is a saved set of instructions an agent follows for one kind of task. You can also run it yourself by typing /writeups in chat. To change when it runs, open Customize agent > Skills and change its mode.
Edit a writeup
A writeup opens in a visual editor. Click Source in the top right to edit the Markdown underneath. Both views edit the same document, and switching never loses unsaved work. Markdown syntax formats as you type. For example, type three backticks to start a code block, or#### for a level-four heading.
For math, use $$x^2$$ inline, or put $$ on separate lines around a display equation. Single dollar signs stay literal, so amounts such as $100k read normally.
Select text to open the formatting menu. Formatting requires edit access, and comments require comment access. For what each role can do, see Shared workspaces.
Autosave and outside changes
Writeups save automatically. If an agent or another person changes the file while you have unsaved edits, Qualia keeps your draft and offers to reload. If a save conflicts with the version on disk, choose Keep mine or Use theirs.Older .qua writeups
Files in the older .qua format open in a block editor. You can’t share .qua files, so ask the agent to recreate one as a Markdown writeup first.
Link to workspace files
In Source, write[[file:notebooks/m1_sequential.ipynb]] to add a file reference. In the visual editor, click the file name to open that file or switch to its tab. Paths are relative to the workspace root, not the writeup’s folder.
Add a label after a second colon, such as [[file:notebooks/m1_sequential.ipynb:Sequential experiment]]. Shared reports show the label without giving access to the linked file.
Cite evidence
Cite a claim from Knowledge by its ID. A claim is a recorded finding or piece of evidence, such as a captured value or a quoted line from a file.Add tables and figures
Give a table or figure a caption line, which also carries its citation. Source shows theTable: or Figure: prefix that marks a caption.
Live tables
Add[live] to a table caption to link the table to its source in Knowledge:
Captured figures
Insert a captured figure by its claim ID, in its own paragraph. The caption is optional.[[claim:C-…]] to cite a figure without embedding it, and ordinary Markdown image links for screenshots.
Captured Matplotlib and seaborn figures support hover readouts and series toggles. Plotly figures support interactions such as axis zoom and 3D rotation. Ask the agent for the library that suits your presentation.
The figure token is a Qualia extension, so plain Markdown viewers show the token itself. To get ordinary image links, use Export > Markdown.
Explore live curves
A live figure updates as new data arrives, for example from a training run. Drag a rectangle across the chart to zoom, and double-click the plot to reset. Click a series name below the chart to hide it, and hover the plot to read values. Your zoom and hidden series survive incoming updates.Images and assets
Click an image to focus it, then click it again to open it in an image-viewer tab. Qualia keeps a writeup’s images in a folder beside it, named after the document:Comments and suggestions
Select text to open the selection menu, then choose how to comment:- Ask Qualia: Click the Qualia icon. A comment opens on the right with
@Qualiafilled in. Write your request and click Comment, and Qualia replies in the same thread. - Leave a comment: Click the comment icon to start an ordinary thread.
Review suggested edits
Agents propose edits as Add, Delete, or Replace suggestions. The thread previews the change, and the document shows the proposed text before the struck-through original.- Hover or select the thread, then click ✓ to accept or × to reject. Review each suggestion separately.
- You can edit the proposed text before accepting. Accept keeps your edits, and Reject restores the original.
- Suggestions stay pending when you close and reopen the document. Review a pending suggestion before requesting another change to the same passage, so the two edits don’t collide.
Resolve threads
Click Resolve beside a thread’s first comment to archive it. Resolving a thread doesn’t accept its suggestions. A thread also archives itself once you review its last suggestion. To reopen one, click the comment-history button beside Source, select the thread, and click its restore icon. Commenters can post and reply. Requesting agent work and accepting or rejecting edits require edit access. For workspace roles, see Shared workspaces.Share a writeup
In a cloud workspace, click Share at the top right of the writeup, then Copy beside the link. Only the project owner can choose who may open it:- Project viewers (default): People with view access to the project, after signing in.
- Anyone with the link: Anyone, without signing in.
Share live figure data
A shared writeup shows each live figure as of its last save. To let readers see new data as it arrives:- Choose Anyone with the link.
- Review the curves listed under Future figure data.
- Click Share future data for these curves.
Export a writeup
Use the Export menu in the writeup header:
Resolve any save conflict before you export. If Qualia can’t prepare a figure, the download stops and names the chart that needs attention.
- PDF and Word include figures as static images and tables as native tables, with their captions attached. Table cells stay editable in Word. These formats leave out citations.
- Markdown and LaTeX keep citations as footnotes. Markdown bundles include saved Matplotlib figure data, so the extracted report keeps hover and series toggles when you open it in Qualia.

