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":{}}
```

In the editor, an A/B Comparison shows rows A and B. Use Select A or Select B to choose a source type (Test result, a Context object kind, Experiment, or an experiment's agent, model, agent mode, prompt, product or environment) and then the source. A source that is not a test result shows Measured by, where you choose the test result that measures it. Each choice saves immediately, and each row shows its own selection rate or the reason it has none. Blocks saved with an experiment, product and selection test keep those controls above the rows.

A/B Comparison blocks save each unfinished choice immediately. Unfinished fences keep configuration: "unconfigured" and an empty string for each source you have not chosen; they read no measurements. Once all choices are complete, the marker is removed. Changing an experiment clears copied product, version, test and scope choices in the same edit; changing a product clears copied versions. Omitting scope.experimentFingerprint or setting it to null selects all experiment versions. Switching between those representations keeps your choices.

Use report_block_kinds to choose a supported kind, then report_block_schema with the selected add or update operation and kind to read the exact schema, example and source guidance. When the corresponding write tool is available over the AX Agent connection (a read-only connection has none), the contract also carries a write envelope: the write tool (report_add_block or block_update), its input schema and the _ax_catalog_ref the call must include, so writing needs no separate read of the write tool's schema. 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>

Front matter

A front-matter group opens a report or a section by naming what it covers: a heading, a one-line lead, and three rows for the products it is about, the metric it tracks and the experiments it draws on. Each row stores ids, never names, and shows each object's current name linked to its page. The metric row names one test of one experiment version (test-<uuid> from the version's tests); a null version follows the experiment's current one.

<div data-ax-frontmatter-group>

## Checkout onboarding

How agents set up the checkout SDK.

<div data-ax-frontmatter-row data-row-kind="product" data-values="<URL_ENCODED_JSON_IDS>"></div>

<div data-ax-frontmatter-row data-row-kind="metric" data-values="<URL_ENCODED_JSON_TEST_KEY>" data-metric-source="<URL_ENCODED_JSON_SOURCE>"></div>

<div data-ax-frontmatter-row data-row-kind="experiments" data-values="<URL_ENCODED_JSON_IDS>"></div>

</div>

Use the front-matter MCP tools to configure these rows: report_frontmatter_group_sources reads a report's groups and an experiment's versions and test keys. Read report_get_content, then use report_add_block for an explicit insertion or block_update with the group's full block handle and a typed frontmatter-group patch. Both writes require expected_updated_at from that read; omitted patch fields stay unchanged. A wrapper that does not match this shape is kept verbatim as markdown.

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.