> ## Documentation Index
> Fetch the complete documentation index at: https://subtext.fullstory.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Proof Docs: Permanent Evidence Records of Agent Work
> Subtext Proof Docs are permanent, evidence-backed records your agent creates to document UI changes — with before/after screenshots, diffs, and logs.
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:
```
doc-create → [doc-update / doc-attach]* → doc-close
```
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](./skills) for details.
## When to Use Proof Docs
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.
Record the outcome of a full verification pass — which views were checked, what passed, what failed — with screenshots attached per section.
Create a doc for any compliance-sensitive change. Close it when done. The permanent snapshot satisfies audit requirements without extra tooling.
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
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.
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.
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.
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.
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.