arul28/ade/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.

Scratch or showcase

• Scratch: what you capture to check your own work (screenshots,

observes, quick recordings). Keep it out of the drawer and off PRs.

• Showcase: what a person will see, in your answer or on a PR. The bar: they

could post it to Twitter as is. File only showcase proof.

Make showcase proof (any app)

1. Choose what to show. A visible fix: before and after. A feature: one

demo per thing worth seeing. Anything that moves (a drag, live filtering, a panel opening, an animation) is a video; a still is for a state. An internal or tiny change may need none.

1. Stage first. Only the subject on screen:

• Dismiss banners, toasts, notifications, update prompts, dev overlays and

element inspectors. Close unrelated windows, tabs and panels.

• Make the subject big and whole: size the window to it (at least 1280

wide, 2× scale), collapse sidebars, open the panel full size, zoom the page. Nothing the demo uses may be cut off at an edge, and the subject fills the frame: no big empty areas (shrink the window or viewport to the content, or zoom the page). Text must read at phone size.

• Real or demo data is fine; secrets never (tokens, keys, passwords,

private messages). Use demo data when the user asks or the app has it.

• Get to the starting state (signed in, data loaded) before recording.

1. Script 3–6 beats. Before each one: ade proof step "<caption>", at most

60 characters, saying what happens ("Fold it. The app follows."), not what you click. Add --focus x,y,w,h (fractions of the recorded frame, judged from a screenshot of the same surface) to hold the camera on a small subject for that beat.

1. Record only the flow. Start, run the beats, stop when the result

shows. Every visible change gets its own beat; do nothing unscripted on camera. A mistake means record again, not carry on.

1. Check it. ade proof review <id> --text, then open the image it

prints and fix everything it lists. Anything off: fix the stage, record again, ade proof rm the old one.

1. Pictures: crop to the subject with a little context; one picture per

claim. Before/after is always one proof-compare block, never two separate pictures.

1. Publish once, the final set: see Put proof on the PR.

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:

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

Cite proof in the PR body, under the claim it proves, the same way as in a chat answer: ade prs create and ade prs body upload it. Only proof made after the body is final goes up as a comment, with ade proof publish --pr <number or URL> <id> <id> (--replace when you post again). See the ade-pr-workflows skill for both.

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 review <id> --text   # a sheet of a video's key moments (or the picture) to check
ade proof review <id> --from 12 --to 18 --text   # a closer look at part of it
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
# The lane's own screen (ade screen)
ade screen proof --caption "Preferences shows the new key" --text
ade screen record start --caption "Note saved in TextEdit" --text
ade screen 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 browser proof --tab <tab-id> --caption "Verified" --text
ade browser proof --browser-session <session-id> --caption "Verified" --text
ade browser record start --tab <tab-id> --caption "Checkout flow" --text
ade 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, or any surface with ade proof step --focus), a pointer and click rings, under 10 MB (GitHub's limit for a PR video). Only ade proof step captions show, at the bottom, or at the top when the action is low; each is also 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.

What counts as proof — and what does not

Only a proof-named command files a drawer entry. Taking a screenshot is not the same as filing proof:

• ade proof capture --caption "…", ade proof record, ade proof attach <path> --caption "…", ade apple proof, ade app-control proof, ade browser proof, ade screen proof --caption "…", a captioned ade screen record and a captioned ade app-control record do file.
• ade proof capture and ade proof record never take the user's real screen unless you pass --real-screen. For desktop app work on a Mac host, work on the lane's own screen (see the ade-computer-use skill) and record there.
• A bare screenshot_environment / record_environment call does not — it hands you a scratch file path for your own look at the screen. Promote one with ade proof attach <that path> --caption "…" when a reviewer should see it. (There is no captureScreenshot tool; if you have seen it named somewhere, it does not exist and calling it fails.)

Artifacts worth filing:

• Screenshot or video of the UI state.
• App Control, iOS Simulator, or ADE browser capture.
• Test output or log bundle when visual proof is not the right artifact.

Proof must be new

Proof shows what you did for this request. ADE checks:

• An attach whose bytes are already proof (an earlier recording copied to a

new name, say) fails with PROOF_DUPLICATE and names the earlier proof. Do not work around it. Record a new one, or tell the user the recording failed.

• An attached MP4/MOV whose own creation time is before this request still

files, but prints warning: This video was recorded at …, before this request. and the drawer marks it older. Repeat that warning to the user.

• The drawer says where each proof came from: recorded by ADE, captured by

ADE, or attached by the agent. ade proof attach of a fresh, unchanged ADE capture keeps ADE's label; any other file is "attached by the agent", whatever label you pass.

Keep the drawer clean

Delete proof that is no longer true, with ade proof rm <id> --text. Do not ask first and do not keep it "just in case": you can always capture it again, but a drawer full of old proof hides the proof that matters.

Delete it when:

• a new recording or capture replaces it (you recorded the flow again);
• it shows a mistake, a failed attempt or a wrong result;
• the code changed after it, so it no longer shows the current behavior.

Delete only proof of this same work. Proof of other work in the lane is not yours to delete. Before your final reply, run ade proof list --text and delete what is stale; cite only what stays.

Gotchas