Proof

Proof is a collaborative markdown editor for agents and humans. Use the hosted web API at https://www.proofeditor.ai.

Every write must include by: "ai:<agent-name>" so Proof can track who wrote what.

This skill is web-only. Do not use a local Mac app bridge or localhost:9847 from this skill.

Default Behavior

If the user shares a Proof URL:

Join the doc immediately.
Show presence right away.
Read the current state before editing.
Work in the Proof doc unless the user explicitly asks you to move elsewhere.

When creating new docs, follow this priority order:

If persistent instructions already define a Proof default mode, use it.
Otherwise default to collaborative_docs.

Supported default modes:

all_new_markdown: new markdown artifacts you create go to Proof by default.
collaborative_docs: plans, specs, bug writeups, reports, memos, proposals, drafts, and similar iterative docs go to Proof by default.
explicit_only: only use Proof when the user explicitly asks.

Boundary rules:

Existing repo-tracked markdown files stay local unless the user explicitly asks to move or share them in Proof.
Do not silently replace local project docs with Proof links.
If the task is code-adjacent local documentation, keep it local unless the user asks for Proof.

Shared URLs And Auth

Shared URL format:

https://www.proofeditor.ai/d/<slug>?token=<token>

Use one of:

Authorization: Bearer <token> (preferred)
x-share-token: <token>
?token=<token>

by controls authorship. X-Agent-Id controls presence identity.

Existing Proof Docs

When a Proof URL is provided:

Extract slug and token.
Join immediately by reading state with X-Agent-Id or by posting presence.
Read the doc.
Reply with a short confirmation like Connected in Proof and ready.
Then keep working inside Proof.

Read state and show presence on read:

curl -sS "https://www.proofeditor.ai/api/agent/<slug>/state" \
  -H "Authorization: Bearer <token>" \
  -H "X-Agent-Id: <your-agent-id>"

Update presence explicitly:

curl -sS -X POST "https://www.proofeditor.ai/api/agent/<slug>/presence" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "X-Agent-Id: <your-agent-id>" \
  -d '{
    "agentId":"<your-agent-id>",
    "status":"reading",
    "summary":"Joining the doc"
  }'

Common statuses: reading, thinking, acting, waiting, completed, error.

Creating A New Proof Doc

Create a shared document:

curl -sS -X POST https://www.proofeditor.ai/share/markdown \
  -H "Content-Type: application/json" \
  -d '{"title":"My Document","markdown":"# Hello\n\nFirst draft."}'

Save:

slug
accessToken
shareUrl
tokenUrl
_links

When Proof is the default for the task:

Create the doc.
Return the live Proof link to the user.
Join the doc immediately.
Keep working there.

Choosing An Edit Strategy

| Task | Recommended API | Why | |---|---|---| | Precise paragraph or section rewrite | edit/v2 | Block refs plus revision locking | | Simple append or replace | edit | Minimal payload | | Human-reviewed edits | ops | Suggestions and comments in track changes | | Large rewrite proposal | ops + rewrite.apply | Produces reviewable changes |

Snapshot And Edit V2

Get a snapshot:

curl -sS "https://www.proofeditor.ai/api/agent/<slug>/snapshot" \
  -H "Authorization: Bearer <token>"

Apply block operations:

curl -sS -X POST "https://www.proofeditor.ai/api/agent/<slug>/edit/v2" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: <unique-key>" \
  -d '{
    "by":"ai:<your-agent-name>",
    "baseRevision":42,
    "operations":[
      {"op":"replace_block","ref":"b3","block":{"markdown":"Updated paragraph."}},
      {"op":"insert_after","ref":"b3","blocks":[{"markdown":"## New section"}]}
    ]
  }'

Supported ops:

replace_block
insert_before
insert_after
delete_block
replace_range
find_replace_in_block

Simple Edit V1

Use this for quick append or replace flows:

curl -sS -X POST "https://www.proofeditor.ai/api/agent/<slug>/edit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "by":"ai:<your-agent-name>",
    "operations":[
      {"op":"append","section":"Notes","content":"\n\nNew note."},
      {"op":"replace","search":"old","content":"new"}
    ]
  }'

Comments, Suggestions, And Rewrites

Primary endpoint:

POST /api/agent/<slug>/ops

Compatibility endpoint:

POST /api/documents/<slug>/ops

Examples:

{"type":"comment.add","by":"ai:<your-agent-name>","quote":"anchor text","text":"Comment body"}
{"type":"suggestion.add","by":"ai:<your-agent-name>","kind":"replace","quote":"old text","content":"new text"}
{"type":"suggestion.add","by":"ai:<your-agent-name>","kind":"replace","quote":"old text","content":"new text","status":"accepted"}
{"type":"rewrite.apply","by":"ai:<your-agent-name>","content":"# Rewritten markdown"}

Use ops when you want the human to review changes in track changes.

Events And Presence

Poll for pending events:

curl -sS "https://www.proofeditor.ai/api/agent/<slug>/events/pending?after=0" \
  -H "Authorization: Bearer <token>"

Ack processed events:

curl -sS -X POST "https://www.proofeditor.ai/api/agent/<slug>/events/ack" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"upToId":123,"by":"ai:<your-agent-name>"}'

If you are staying in the loop while a human reviews changes, keep presence updated so the doc shows what you are doing.

Error Handling

| Error | Meaning | Action | |---|---|---| | 401/403 | Bad or missing auth | Re-read token from URL and retry with bearer token | | 404 | Slug not found | Verify slug and environment | | 409 PROJECTION_STALE | Metadata catching up | Re-read state or snapshot, then retry | | 409 STALE_REVISION | Snapshot out of date | Use the fresh snapshot or state and retry | | 409 ANCHOR_NOT_FOUND | V1 search anchor missing | Re-read state and choose a tighter anchor | | 422 | Invalid payload | Fix required fields and schema | | 429 | Rate limit | Back off and retry with jitter |

Guidelines:

Re-read state before retries that depend on anchors or revisions.
Include by on every write.
Prefer content and markdown payloads as canonical text input.
Use Idempotency-Key on edit/v2 requests so retries stay safe.

Discovery

Discovery JSON: https://www.proofeditor.ai/.well-known/agent.json
Docs: https://www.proofeditor.ai/agent-docs
Setup: https://www.proofeditor.ai/agent-setup