Skip to main content
These are Verify beta features, available to the closed beta cohort only. They may change or move out of the core MCP without notice.
Proof Docs are permanent, structured records that your agent creates to document what it did, why, and what the outcome looked like. Each document can hold prose, metadata, and attached evidence — screenshots, replays, diffs, and logs — organized into named sections. Once closed, a Proof Doc becomes an immutable snapshot that your team can read, diff, and link to from tickets or PRs long after the work is done.

​
What Proof Docs Are

A Proof Doc is a living document while work is in progress and a permanent record once finalized. It is not a log file or a raw screenshot dump — it is a readable, structured artifact that combines your agent’s narrative with concrete visual and data evidence. Key properties:
  • Persistent identity — every document has an ID you can reference from tickets, PRs, and comments
  • Versioned — every doc-update and doc-attach creates a new version; doc-diff compares any two
  • Evidence-backed — attach screenshots, replays, logs, or diffs into named sections alongside prose
  • Immutable on close — doc-close writes a permanent snapshot; the document is read-only afterward

​
The Document Lifecycle

Proof Docs follow a simple, predictable lifecycle:
  1. doc-create opens the document and optionally seeds it with markdown.
  2. doc-update and doc-attach can be called any number of times to add content and evidence as work progresses.
  3. doc-close finalizes the document and writes the permanent snapshot.
The /subtext:proof skill automates this entire lifecycle. It instructs your agent to call doc-create, take a BEFORE snapshot, make changes, take an AFTER snapshot, and call doc-close — without you having to coordinate each step manually. See the Skills page for details.

​
When to Use Proof Docs

Bug Fix Documentation

Create a doc before touching code. Attach a BEFORE screenshot showing the broken state, make your fix, attach an AFTER screenshot, then close. The PR reviewer has full context at a glance.

UI Verification Run

Record the outcome of a full verification pass — which views were checked, what passed, what failed — with screenshots attached per section.

Audit Trail

Create a doc for any compliance-sensitive change. Close it when done. The permanent snapshot satisfies audit requirements without extra tooling.

Regression Baseline

Document the expected UI state as a named Proof Doc. Diff against it in future runs to spot regressions early.

​
Tools Reference

​
doc-create

Open a new proof document with a title and an optional seed markdown body. Returns the document ID you’ll pass to all subsequent calls. Parameters: title (required), body (optional markdown string used to pre-populate the document).

​
doc-update

Edit the document after it is open. You can replace a specific section of text, append new content, or update metadata fields like status or assignee. When to use it: After each significant step in your work — add a summary of what you just did, update the status field, or revise earlier prose as the picture becomes clearer.

​
doc-attach

Attach evidence into a named section of the document. Supported evidence types include screenshots (base64 PNG), replays, logs, and diffs. When to use it: Immediately after capturing a screenshot with live-view-screenshot, after exporting a log, or after generating a diff. Each attachment is stored under a section name you choose (e.g. before, after, error-log).

​
doc-close

Finalize the document and write the permanent snapshot. Once closed, the document is read-only. Returns the canonical URL of the closed record. When to use it: When your task is complete and all evidence is attached. Do not close a doc prematurely — you cannot attach further evidence afterward.

​
doc-read

Read the current contents of a document, or a specific past version by version number. Returns the full document body and metadata. When to use it: To review what the agent wrote, to share the current state of an in-progress doc, or to retrieve an older version for comparison.

​
doc-diff

Diff two versions of a document and return a structured list of changes — additions, deletions, and attachment changes between the two snapshots. When to use it: To see what changed between two points in the work, or to compare the current state of an open doc against a previous checkpoint.

​
doc-list

List open or closed documents, optionally filtered by status, title substring, or date range. Returns document IDs, titles, and creation timestamps. When to use it: To find a specific past record, to audit how many open docs are in flight, or to locate the doc associated with a particular task.

​
Typical Workflow

1

Open the document

Call doc-create with a descriptive title (e.g. "Fix: modal close button misaligned on mobile"). Optionally seed it with a markdown summary of the task. Save the returned document ID.
2

Attach a BEFORE screenshot

Navigate to the affected view in the live browser, call live-view-screenshot, and pass the result to doc-attach under a section named before. This records the broken or pre-change state.
3

Make your changes

Edit the code, apply the fix, or complete the task — whatever the work requires. Update the document with doc-update to narrate what you did.
4

Attach an AFTER screenshot

Navigate back to the affected view, take a fresh screenshot, and call doc-attach under a section named after. This records the resolved or post-change state.
5

Finalize the record

Call doc-close to write the permanent snapshot. Share the returned URL in your PR description, ticket, or Slack thread so reviewers have the full evidence record.
Use doc-diff after closing to generate a summary of every change the agent made to the document during the task. Paste the diff into the PR body for a concise, auto-generated change log.