.md file. You can read it in any editor, diff it in Git, and open it outside Qualia, and it still makes sense.
Creating a writeup
- Click New File in the Files sidebar
- Enter a name and choose Write-up
.md file that opens as a writeup, titled with the name you
entered. Any Markdown file becomes a writeup when its frontmatter says so:
qualia: writeup open in the standard source-and-preview editor.
The first # heading is the document’s title.
Writing with Qualia
Ask Qualia to write up your findings or revise an existing passage. The built-inwriteups skill is enabled for automatic use when Qualia drafts or edits
writeup prose, including revisions requested through comments. It helps organize
the argument, select relevant evidence, explain methodological choices, and write
for readers who have seen only the document—not your notebooks or conversations.
It guides plain, exact scientific prose while preserving your numbers, notation,
citations, and supported meaning. First drafts and structural revisions receive
document-level guidance; a local edit stays focused on the requested passage.
You can also invoke /writeups in chat. To change whether it activates
automatically, open Customize agent > Skills and change its mode. See
Skills for details.
Editing
A writeup opens in a visual editor, with a Source toggle in the top right corner for the Markdown underneath. Both edit the same document, and switching between them never loses unsaved work. The editor supports headings, paragraphs, bold, italic, strikethrough, inline code, links, lists, block quotes, syntax-highlighted code blocks, tables, images, and math. Type text between single backticks, such as`model_name`, to turn it into monospace as soon as you type the closing backtick. Continue typing to return to normal text, or press Backspace immediately to restore the backticks.
Single dollar signs are literal text, so currency such as $100k and $500k stays readable in prose, captions, tables, and suggestions. Use $$x^2$$ for explicit inline math, or put $$ on separate lines around a display equation.
The selection menu
Select text to open the formatting menu. Use its block-type menu to choose a heading, list, or quote. Type three backticks to create a code block, or#### for a level-four heading.
Use Bold, Italic, Strikethrough, and Code for inline formatting. Clear formatting removes those styles and keeps links.
Formatting requires edit access; comments require comment access.
Autosave
Writeups save automatically after editing and when you leave the tab. If someone else changes the file while you have unsaved edits, choose Keep mine or Use theirs to resolve the conflict.Writeups in .qua format
Files in .qua format use a block editor. Hover beside a block to reveal its
add and drag buttons; these controls hide while you scroll. If several blocks
are selected, Delete from a selected block’s drag-handle menu removes the
whole selection. Use Cmd/Ctrl+Z to undo.
In editable text tables, Enter moves to the cell below, pasted blocks become
inline cell content, and typing / does not open the block menu. File names and
captions update as you type. Checkboxes cannot be toggled in read-only documents.
Linking to workspace files
In Source, write[[file:notebooks/m1_sequential.ipynb]] to add a clickable
file reference. In the visual editor, clicking the filename opens that file or
focuses its existing tab. Paths are relative to the workspace root, not the
writeup’s folder.
Use [[file:notebooks/m1_sequential.ipynb:Sequential experiment]] for a custom label. Standalone shared reports show the label without granting access to linked workspace files.
Sharing a writeup
In a cloud project, click Share at the top right of the writeup, beside Export, then Copy beside the link. The project owner can choose:- Project viewers (default): people with view access to the project, after signing in.
- Anyone with the link: anyone can read the writeup without signing in.
.qua
format have no Share button; ask the agent to recreate one as a Markdown
writeup or dashboard, then share that.
This shares only the writeup. It does not grant access to the rest of the project.
Switch back to Project viewers to disable anonymous access. Use
workspace sharing to manage project membership.
Citations
Cite a claim from workspace knowledge with its ID. Qualia displays a named citation you can click to inspect the evidence:Asking about a passage
Select a passage and click the Qualia icon in the selection menu. A comment opens on the right with@Qualia already filled in. Write your question and click Comment. Qualia reads the passage and its surrounding document, then replies in the same thread.
Tables and figures
A table or figure takes a caption line, which carries its citation:Table: or Figure: prefix that identifies a caption.
Live tables and interactive figures
Add[live] to a table’s caption to refresh it from the knowledge graph:
Captured figures
Insert any captured research figure by its claim ID, in its own paragraph:[[claim:C-…]] for a citation without embedding the figure, or ordinary Markdown image links for screenshots and illustrations.
Keep the report’s asset directory when copying the Markdown. Shared reports include the saved figures without granting access to private source claims. Exports use static images.
The figure token is a Qualia extension. Plain Markdown viewers show the token;
use Export → Markdown for a bundle with ordinary image links and figure assets.
Exploring live curves
Drag a rectangle across a live chart to zoom both axes. Use Reset zoom or double-click the plot to return to the full range. Click a series name below the chart to hide or show it; these buttons also work with Tab and Enter or Space. Hover the plot to read the nearest observation from each visible series, including its own x value. Curves keep independent observations and gaps rather than being aligned or interpolated onto a shared grid. Zoom and series visibility survive incoming updates.Images and assets
Click an image once to focus it with an outline. Click it again while focused to open it in an image-viewer tab. Clicking elsewhere removes focus, so the next image click focuses it again. You can also focus an image with Tab and press Enter or Space to open it. Images live in a directory beside the document, named after it:Comments and suggestions
Select text to open the comment menu. Choose the Qualia icon to start a request with @Qualia, or the comment icon for an ordinary comment. Drafts remain available during your app session, including when you switch tabs; Cancel discards a draft. Type @ to choose an agent or a teammate in your cloud workspace. Use Create a new agent: … to request a new agent. Posting the comment sends the request to each mentioned agent. Click Comment or Reply, or press Cmd/Ctrl+Enter, to post; Enter inserts a line break. The thread shows which agent is working on your request. If it is already busy, your feedback waits in its queue. To request more work in the same thread, mention the agent again. Comments appear beside their passages. Select a thread to read it or reply. Use Resolve beside the first comment to archive it. The comment-history button beside Source opens archived threads; select one and use its restore icon to reopen it. Resolving a discussion does not accept its suggestions. Agent edits appear as Add, Delete, or Replace suggestions, with a preview in the thread and the full change in the document. Proposed text appears before the struck-through original. Hover over or select the thread for ✓ to accept or × to reject. Review each suggestion separately; the thread is archived after its last suggestion is reviewed. You can edit the proposed text before accepting it. Accept keeps your edited proposal; Reject restores the original and discards edits inside the suggestion. The struck-through original is read-only. Undo and redo work normally. Suggestions remain pending when you close and reopen the document. Review a pending suggestion before requesting another change to the same passage. Click a suggested link to preview its URL. Open the URL from the preview or use Copy link. Click a citation in a comment to inspect its source. Workspace commenters can post and reply. Requesting agent work and accepting or rejecting edits require edit access.Agents writing into a document you have open
If you have no unsaved changes when an agent writes, the document reloads with the new text. If you do, Qualia shows a changed on disk notice with a Reload action and keeps your draft. Saving while the notice is up asks whether to take the version on disk or keep yours.When to use writeups vs notebooks
Both formats live in the same workspace and can reference each other. Use notebooks for the work itself and writeups for the story you tell about it.
Exporting a writeup
Use the Export menu in the writeup header to download the document as:
Export waits for pending edits to save; resolve any save conflict before downloading. PDF and Word include figures as static images and tables as native document tables, with their
Figure: and Table: captions attached to the corresponding content. Table cells remain editable in Word.
Knowledge citations are omitted from PDF and Word; Markdown and LaTeX bundles retain them as footnotes. Exports are snapshots: live tables carry their saved values and figures use saved images, without tracking the original workspace. Markdown bundles also include saved Matplotlib figures, so opening the extracted report in Qualia preserves hover and series toggles over those saved values.
Exports use the original text of pending suggestions and omit comment threads and review markers. Accept the changes you want before exporting. The source Markdown keeps pending suggestions for further review.
If a figure cannot be prepared for export, the download stops and identifies the chart needing attention.
Dashboards
Dashboards are Markdown (.md) files using Quarto dashboard syntax. Ask the agent
to create a dashboard, or create a .md file and add format: dashboard to its
YAML frontmatter. The saved file contains the layout, text, and values.
title names a standalone dashboard. H1 headings create pages,
H2 headings create rows, and H3 headings divide a row into columns. Deeper headings
alternate between rows and columns. Add {width=60%} to a column heading to give
it a relative width. To start with columns, use
format: {dashboard: {orientation: columns}}. Add {.tabset} to a row or column
to show its cards as tabs, named by their title attributes.
Cards accept Markdown text, tables, images, and captured Plotly charts. Put
[[figure:C-123]] in its own paragraph inside a card to embed a captured figure.
Use [[claim:C-123]] to cite evidence. Keep images beside the dashboard in a
<filename>.assets/ directory, such as overview.assets/chart.png.
Qualia previews the saved Markdown and captured charts. It does not execute
Quarto code cells, inline calculations, or Shiny servers. Ask the agent to compute
results in a notebook or script and write the resulting values into the dashboard.
Editing a dashboard
Click Source at the top right to change the Markdown, then Preview to see the layout. Save source changes with Cmd/Ctrl+S. The preview updates when an agent saves changes.Pipeline runs
Each pipeline run writes its primary output toreport.md in its own run
directory. Dashboard outputs use Quarto frontmatter; prose reports use
qualia: writeup. Earlier runs retain their saved results.
Pipeline dashboards display the pipeline’s current name. Rename the pipeline to
rename its dashboard. A Runs sidebar lists runs newest first, with their
local start time and Started manually or Started on schedule labels.
Select a run to view its report and open its agent conversation.
Before a report exists, Dashboard still being prepared… appears with a
read-only preview of the agent’s notebook when available. The report replaces
that preview when saved. Click + New run to start another run; this is disabled
while the latest run is running or queued. A green check means a run finished
normally and its report.md exists. Other inactive runs show a pause icon.
Sharing a dashboard
In a cloud project, click Share to open a panel below the button, then use Copy beside the link. 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 can view the dashboard without signing in.
Value boxes
A::: {.valuebox} div displays its first paragraph as the label, its second as
the value, and the remaining paragraphs as context. Write numbers, currency,
percentages, and comparisons exactly as they should appear. Ask the agent to
calculate and verify them from notebook or script results, then cite the evidence.
Values stay as saved until you or the agent update the file.