Skip to main content
Write a research report that cites its evidence, review the edits agents suggest, and share or export it. A writeup is a Markdown (.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

  1. Choose File > New File… or press Cmd/Ctrl+N.
  2. Enter a name and choose Write-up.
Qualia creates a .md file titled with the name you entered. Any Markdown file opens as a writeup when its frontmatter says so:
The first # 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-in writeups 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. 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.
Qualia displays the citation by name. Click it to preview its source beside the document, such as the notebook cell and output a value came from. From the preview, open the underlying file or the full claim in Knowledge. A citation travels with its sentence, so rewriting or deleting the sentence takes the citation with it.

Add tables and figures

Give a table or figure a caption line, which also carries its citation. Source shows the Table: or Figure: prefix that marks a caption.

Live tables

Add [live] to a table caption to link the table to its source in Knowledge:
Keep real rows in the Markdown table, so the values stay readable outside Qualia. A live table keeps its saved rows until you update it. When the source has newer rows, the table shows a notice, and editors can update it.

Captured figures

Insert a captured figure by its claim ID, in its own paragraph. The caption is optional.
The same syntax works for Matplotlib, seaborn, and Plotly figures and captured static images. Use [[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:
Images use relative paths, so you can copy, zip, or commit the folder and they still resolve. Keep the asset folder with the report when you copy it, because captured figure embeds depend on it.

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 @Qualia filled 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.
Type @ to mention an agent, or a teammate in your cloud workspace. Choose Create a new agent: … to start a new agent for the request. Post with Comment, Reply, or Cmd/Ctrl+Enter. Each mentioned agent receives the request, and the thread shows which agent is working on it. If the agent is busy, it takes your request when it finishes. To ask for more work in the same thread, mention the agent again.

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.
The link opens a standalone, read-only page with the saved document, and later saves appear at the same link. Shared writeups show saved tables and figures, with hover and series toggles for supported Matplotlib figures. They leave out comments, unresolved suggestions, and links to evidence sources. An unresolved suggestion shows its original text. Sharing a writeup doesn’t give access to the rest of the project. Switch back to Project viewers to turn off anonymous access. To manage project membership, see Shared workspaces.

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:
  1. Choose Anyone with the link.
  2. Review the curves listed under Future figure data.
  3. Click Share future data for these curves.
Adding sources or curves to a figure requires approving it again. Click Stop sharing future data to stop updates; the curve list stays, so you can approve it again later. Readers keep anything they already downloaded. Qualia doesn’t automatically upload data that exists only on your computer. The same controls apply to shared dashboards.

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.
Exports are snapshots. Live tables keep their saved values and figures use saved images. Exports use the original text of pending suggestions and leave out comment threads, so accept the changes you want first. The source Markdown keeps pending suggestions for later review.