Reports

A report is a document your organization writes together: a title, a description, and a markdown body that embeds live insights, experiments, Context objects and excerpts from runs. Members edit it in the web app; agents and scripts write the same document through ax report, the HTTP API and the report_* MCP tools. Whatever surface wrote a paragraph, everyone with the report open sees it appear.

The document format

A body is CommonMark. Headings, paragraphs, lists, tables and code blocks are what you expect. Three conventions carry everything Fiveonefour-specific, so a body survives any markdown editor and reads back exactly as written.

Blocks

An embedded block is a fenced code block whose info string is ax-block and whose body is one JSON object. kind names the block; the other keys are that kind's fields.

```ax-block
{"kind":"insight","experimentId":"<EXPERIMENT_ID>","block":"scatter","scope":{},"view":{}}
```

The exact field types are published as a JSON Schema in the report_append_blocks tool description. A fence whose payload does not match its kind is kept verbatim and shown as code; nothing is dropped or rewritten.

Every block accepts an optional layout object that says how it sits in the flow. Omit it for the default: the full column width, in line with the text.

Callouts

A callout is a blockquote whose first line is a tag and a title. Three tags exist: FINDING for what the evidence showed, ACTION for what to do about it, and NOTE for anything else. Any other tag reads as a note.

> [!FINDING] Checkout is slower on Fridays
> The p95 doubles between 16:00 and 18:00 UTC across all three models.

Mentions

A mention is a link whose target is an ax:// address. The app shows the object's current name and links to it, so a renamed product or experiment stays correct in every report that cites it.

The [checkout flow](ax://context/use-cases/<USE_CASE_ID>) regressed in [Model sweep 12](ax://experiments/<EXPERIMENT_ID>).

What the app reads from the body

The report page shows two rows above the body, both derived from it as it changes. Contents lists the headings and scrolls to the one you pick. Referenced names every experiment, Context object and run the body cites, whether through a block or a mention, with each object's current name linked to its page. Nothing needs declaring: cite an object where you discuss it and it appears in Referenced.

Columns

Side-by-side content is an HTML block: a <div data-ax-columns> holding one <div data-ax-column> per column, each with an optional data-width fraction. Separate the tags from the markdown inside them with blank lines.

<div data-ax-columns>

<div data-ax-column data-width="0.5">

Left column.

</div>

<div data-ax-column data-width="0.5">

Right column.

</div>

</div>

Editing in the web app

Open a report from Reports and write into the page. Members with the report open see each other's edits as they type, and the document autosaves. Everything below writes the format above: a block you place from the menu is the same ax-block fence a script would append, so the two ways of writing never diverge.

Type / at the start of a line or after a space to open the insert menu. Keep typing to narrow it; the arrow keys move, Enter chooses, Escape closes. The menu has three groups:

Type @ to open the mentions group on its own.

Every block has a toolbar above it while you edit. It moves the block up or down, sets its width (a fraction of the column, Wide or Full width), aligns or floats a block narrower than the column, opens the block's settings, and duplicates or deletes it. Drag the block's edge to resize it to the nearest fraction. Kinds that draw at a height take one in their settings. An insight block's settings switch between the scatter, test results and metric views and set what each shows; the block re-reads its data as you change them.

Drag a block by its handle to move it. Drop it in the flow to reorder, or drop it onto the left or right edge of another block or paragraph to put the two side by side as columns. Drag the gutter between columns to change their widths; when a column empties, it is removed, and a row left with one column unwraps back into the flow. Rows never nest.

Readers who cannot edit see the same page: blocks render their live views and chips show current names, with no toolbar and no menu.

Adding evidence from the app

Wherever the app shows something a report can embed, Add to report… puts it into one. Pick a report from the list, or start a new one titled after what you are adding, and the block is appended after the report's current body. The report opens from the confirmation.

A new report starts with a section heading naming what was added; an existing report receives the block alone. Blocks take the default layout; arrange them in the editor afterwards.

Writing from the CLI, API and MCP

The three programmatic surfaces take and return the same shapes: a report row (id, title, description, createdBy, updatedBy, createdAt, updatedAt) and, for a single report, its bodyMarkdown.

Two writes exist. Append adds markdown after the current body, after a blank line, and is the usual way to add a finding or a chart from a script. Edit replaces the title, the description and/or the whole body and requires the updatedAt you last read; when the report changed since, the write is refused and nothing is written, so a stale copy never overwrites a newer body. Read the report again and retry with its new stamp. Append accepts the same stamp optionally.

# Create a report and add a finding from stdin
ax report create "Checkout latency" --description "Where the p95 went"
printf '> [!FINDING] Slower on Fridays\n> The p95 doubles after 16:00 UTC.\n' | ax report append <REPORT_ID>

# Rewrite the body from a file, guarded by the stamp you last read
ax report get <REPORT_ID> --json | jq -r .report.updatedAt
ax report edit <REPORT_ID> --body-file report.md --expected-updated-at <UPDATED_AT>

Deleting a report removes its body and the links from findings to it. The findings and the Context objects it cited stay.