Ade Proof Artifacts

ADE proof and artifacts

Rule

When the user asks to capture, send, attach, or provide proof, create evidence with the relevant tool, then register it through ADE so it appears in the proof drawer for the active chat or lane.

Attach, then confirm. A filing command is not done until you have read its confirmation. Run the attach, check that the last line says Attached 1 artifact to lane <id> / chat <id> (<title>) and copy the cite: line above it, then run ade proof list --text and see the row. If the output contains failed, or the list does not show it, the drawer is empty — fix it now rather than reporting proof you did not file.

Show the proof in your answer

The user reads your answer, not the drawer. Put each proof directly under the claim it proves. Every proof command prints a cite: line with the artifact id:

cite: ![Preferences shows the new key](ade-proof://3f2c9a41-…)

Paste that line into your final message, on a line of its own (not inside a sentence or a list item: the phone shows a citation only on its own line). A picture shows inline, and a video plays inline, on the desktop, the web client and the phone.

For a before/after, write a proof-compare block. The two pictures show side by side:

```proof-compare
before: <artifact-id> The old sidebar
after: <artifact-id> The new sidebar
caption: The rows now use the lane color.
```

You can also compose a picture yourself (a crop, a side-by-side, an annotation), file it with ade proof attach, and cite it.

How to write it:

• Put the proof under the claim, not in a pile at the end.
• Give each item a caption that says what it shows.
• Add an honest caveat when the picture does not show everything: mock data, a partial state, a step you could not check.
• Cite as many items as your claims need. There is no limit. Choose the items that show the claim; do not paste every capture.
• Prefer proof that ADE captured or recorded over a file you made yourself.

A citation of an id ADE does not have shows "ADE has no proof with the id …". Copy the id from the cite: line; do not type it.

Put proof on the PR

ade proof publish --pr <number or URL> <id> <id> posts the items you pick as one PR comment, with each picture and video under its caption, and marks them in the drawer. See the ade-pr-workflows skill for the limits.

Commands

ade proof attach "$TMPDIR/checkout.png" --caption "Checkout completes" --text
ade proof list --text          # confirm the row is there
ade proof status --text
ade proof capture --caption "Checkout confirmation visible" --text     # the lane's display
ade proof record --seconds 20 --caption "Retry flow recovers" --text  # the lane's display
ade help proof

Each surface files its own proof. Use the one you worked on:

# Apple device (ade apple)
ade apple proof --caption "Onboarding shows the new step" --text
ade apple record-start --text
ade apple record-stop --keep --text
# Mac Desktop (ade mac-desktop) — the lane's own screen
ade mac-desktop proof --caption "Preferences shows the new key" --text
ade mac-desktop record start --caption "Note saved in TextEdit" --text
ade mac-desktop record stop --text
# App Control (ade app-control) — the controlled app's own window
ade app-control proof --caption "Settings saved" --text
ade app-control record start --caption "Settings save the API key" --text
ade app-control record stop --text
# ADE browser (ade browser)
ade --socket browser proof --tab <tab-id> --caption "Verified" --text
ade --socket browser proof --browser-session <session-id> --caption "Verified" --text
ade --socket browser record start --tab <tab-id> --caption "Checkout flow" --text
ade --socket browser record stop --tab <tab-id> --text

Every recording becomes a demo when it stops: still time cut, waits sped up, zoom to where the actions happen (a phone only with --zoom), a pointer and click rings, under 10 MB (GitHub's limit for a PR video). Mark the steps while recording with ade proof step "<what happens next>"; each one is a caption in the video and a chapter in ADE's player. record start --plain keeps a recording as it was recorded; use it only when the user asks. A recording stops itself after 5 minutes, or after 2 minutes with no action, so record the flow that proves the claim and not the whole task: set up first, start recording, run the flow, and stop as soon as the result is on screen. Retries, saving and troubleshooting stay out of the video; if the flow went wrong, record again.

ade proof capture and ade proof record capture the lane's display. They refuse the user's real screen unless you pass --real-screen. Pass it only when the user asks for proof of their own screen. To pick a surface, see the ade-computer-use skill.

Where the file may live

attach/ingest only import from these roots: the project root, the lane worktree, .ade/artifacts, .ade/cache, .ade/tmp, the OS temp dir ($TMPDIR, which on macOS resolves under /var/folders), the conventional temp dir /tmp (/private/tmp on macOS), and ~/.agent-browser. Anywhere else — ~/Desktop, ~/Downloads — is rejected; copy the file into one of the roots first. .ade/secrets is denied even though it sits inside the project root, and both sides of that check are resolved through symlinks, so a link pointing into it is refused too.

Which directory the call claims

You do not have to be standing in the lane worktree. ADE_WORKSPACE_ROOT (the lane worktree) beats the shell cwd, and with only ADE_LANE_ID set the runtime resolves the worktree itself. If a call is still refused, the error names the path used, where it came from (cwd vs env …), and the authorized root — read those three before retrying.

Confirming it landed

attach, capture, ingest, and record re-read the record they filed and, with --text, end with:

Attached 1 artifact to lane improving-browser-4bb19b3f / chat 8f3c2a11 (Checkout completes)

They exit 0 only when that record exists. Any failure exits non-zero and prints one line containing failed, e.g. ade: proof attach failed — Artifact path is outside allowed import roots: …. ade proof list --text names the scope it listed and carries an owner column, so you can see whether you are looking at your own lane and chat.