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:" 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:

1. If persistent instructions already define a Proof default mode, use it.
2. 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 (preferred)
• x-share-token:
• ?token=

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

Existing Proof Docs

When a Proof URL is provided:

1. Extract slug and token.
2. Join immediately by reading state with X-Agent-Id or by posting presence.
3. Read the doc.
4. Reply with a short confirmation like Connected in Proof and ready.
5. 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:

1. Create the doc.
2. Return the live Proof link to the user.
3. Join the doc immediately.
4. Keep working there.

Choosing An Edit Strategy

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

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