proof

Proof - Collaborative Markdown Editor

Proof is a collaborative document editor for humans and agents. It supports two modes:

1. Web API - Create and edit shared documents via HTTP (no install needed)
2. Local Bridge - Drive the macOS Proof app via localhost:9847

Identity and Attribution

Every write to a Proof doc must be attributed. Two fields carry the agent's identity:

• Machine ID (by on every op, X-Agent-Id header): ai:compound-engineering — stable, lowercase-hyphenated, machine-parseable. Appears in marks, events, and the API response.
• Display name (name on POST /presence): Compound Engineering — human-readable, shown in Proof's presence chips and comment-author badges.

Set the display name once per doc session by posting to presence with the X-Agent-Id header; Proof binds the name to that agent ID for the session. These values are the defaults for any caller of this skill; callers running HITL review (references/hitl-review.md) may pass a different identity pair if a distinct sub-agent should own the doc. Do not use ai:compound or other ad-hoc variants — identity stays uniform unless a caller explicitly overrides it.

Human-in-the-Loop Review Mode

When a caller (e.g., ce-brainstorm, ce-plan) needs to upload a local markdown doc, collect structured human feedback in Proof, and sync the final doc back to disk, load references/hitl-review.md for the full loop spec: invocation contract, mark classification (change / question / objection / ambiguous), idempotent ingest passes, exception-based terminal reporting, and end-sync atomic write.

Web API (Primary for Sharing)

Create a Shared Document

No authentication required. Returns a shareable URL with access token.

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

Response format:

{
  "slug": "abc123",
  "tokenUrl": "https://www.proofeditor.ai/d/abc123?token=xxx",
  "accessToken": "xxx",
  "ownerSecret": "yyy",
  "_links": {
    "state": "https://www.proofeditor.ai/api/agent/abc123/state",
    "ops": "https://www.proofeditor.ai/api/agent/abc123/ops"
  }
}

Use the tokenUrl as the shareable link. The _links give you the exact API paths.

Read a Shared Document

curl -s "https://www.proofeditor.ai/api/agent/{slug}/state" \
  -H "x-share-token: <token>"

Edit a Shared Document

All operations go to POST https://www.proofeditor.ai/api/agent/{slug}/ops

Note: Use the /api/agent/{slug}/ops path (from _links in create response), NOT /api/documents/{slug}/ops.

Authentication for protected docs:

• Header: x-share-token: <token> or Authorization: Bearer <token>
• Token comes from the URL parameter: ?token=xxx or the accessToken from create response
• Header: X-Agent-Id: ai:compound-engineering (required for presence; include on ops for consistent attribution)

Wire-format reminder. /api/agent/{slug}/ops uses a top-level type field; /api/agent/{slug}/edit/v2 uses an operations array where each entry has op. Do not mix — sending op to /ops returns 422.

Every mutation requires a baseToken. Read it from /state.mutationBase.token (or /snapshot.mutationBase.token) immediately before each write, and include it in the request body. On BASE_TOKEN_REQUIRED or STALE_BASE, re-read and retry once. See the baseToken recipe in references/hitl-review.md.

Idempotency-Key header is recommended on every mutation for safe automation retries; required when /state.contract.idempotencyRequired is true.

Comment on text:

{"type": "comment.add", "quote": "text to comment on", "by": "ai:compound-engineering", "text": "Your comment here", "baseToken": "<token>"}

Reply to a comment:

{"type": "comment.reply", "markId": "<id>", "by": "ai:compound-engineering", "text": "Reply text", "baseToken": "<token>"}

Resolve / unresolve a comment:

{"type": "comment.resolve", "markId": "<id>", "by": "ai:compound-engineering", "baseToken": "<token>"}
{"type": "comment.unresolve", "markId": "<id>", "by": "ai:compound-engineering", "baseToken": "<token>"}

Suggest a replacement (pending — user must accept/reject):

{"type": "suggestion.add", "kind": "replace", "quote": "original text", "by": "ai:compound-engineering", "content": "replacement text", "baseToken": "<token>"}

Suggest and immediately apply (tracked but committed — user can reject to revert):

{"type": "suggestion.add", "kind": "replace", "quote": "original text", "by": "ai:compound-engineering", "content": "replacement text", "status": "accepted", "baseToken": "<token>"}

status: "accepted" creates the suggestion mark and commits the change in one call. The mark persists as an audit trail with per-edit attribution and a reject-to-revert affordance. Works with kind: "insert" | "delete" | "replace".

Accept or reject an existing suggestion:

{"type": "suggestion.accept", "markId": "<id>", "by": "ai:compound-engineering", "baseToken": "<token>"}
{"type": "suggestion.reject", "markId": "<id>", "by": "ai:compound-engineering", "baseToken": "<token>"}

suggestion.resolve is not supported — use accept or reject instead.

Bulk rewrite (whole-doc replacement):

{"type": "rewrite.apply", "content": "full new markdown", "by": "ai:compound-engineering", "baseToken": "<token>"}

Block-level edits via /edit/v2 (separate endpoint, separate shape):

curl -X POST "https://www.proofeditor.ai/api/agent/{slug}/edit/v2" \
  -H "Content-Type: application/json" \
  -H "x-share-token: <token>" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "by": "ai:compound-engineering",
    "baseToken": "mt1:<token>",
    "operations": [
      {"op": "replace_block", "ref": "b3", "block": {"markdown": "Updated paragraph."}},
      {"op": "insert_after", "ref": "b3", "block": {"markdown": "## New section"}}
    ]
  }'

Supported op kinds inside operations: replace_block, insert_before, insert_after, delete_block, replace_range (uses fromRef + toRef), find_replace_in_block (takes occurrence: "first" | "all"). Read /snapshot to get stable block ref IDs and the mutationBase.token.

Editing while a client is connected is fine. /edit/v2, suggestion.add (including status: "accepted"), and all comment ops work during active collab. Only rewrite.apply is blocked by LIVE_CLIENTS_PRESENT — it would clobber in-flight Yjs edits.

When the loop breaks. If a mutation keeps failing after a fresh read and one retry, or state across reads looks inconsistent, call POST https://www.proofeditor.ai/api/bridge/report_bug with the failing request ID, slug, and raw response. The server enriches and files an issue.

Known Limitations (Web API)

• Bridge-style endpoints (/d/{slug}/bridge/*) require client version headers (x-proof-client-version, x-proof-client-build, x-proof-client-protocol) and return 426 CLIENT_UPGRADE_REQUIRED without them. Use /api/agent/{slug}/ops instead.

Local Bridge (macOS App)

Requires Proof.app running. Bridge at http://localhost:9847.

Required headers:

• X-Agent-Id: claude (identity for presence)
• Content-Type: application/json
• X-Window-Id: <uuid> (when multiple docs open)

Key Endpoints

Method	Endpoint	Purpose
GET	/windows	List open documents
GET	/state	Read markdown, cursor, word count
GET	/marks	List all suggestions and comments
POST	/marks/suggest-replace	{"quote":"old","by":"ai:compound-engineering","content":"new"}
POST	/marks/suggest-insert	{"quote":"after this","by":"ai:compound-engineering","content":"insert"}
POST	/marks/suggest-delete	{"quote":"delete this","by":"ai:compound-engineering"}
POST	/marks/comment	{"quote":"text","by":"ai:compound-engineering","text":"comment"}
POST	/marks/reply	{"markId":"<id>","by":"ai:compound-engineering","text":"reply"}
POST	/marks/resolve	{"markId":"<id>","by":"ai:compound-engineering"}
POST	/marks/accept	{"markId":"<id>"}
POST	/marks/reject	{"markId":"<id>"}
POST	/rewrite	{"content":"full markdown","by":"ai:compound-engineering"}
POST	/presence	{"status":"reading","summary":"..."}
GET	/events/pending	Poll for user actions

Presence Statuses

thinking, reading, idle, acting, waiting, completed

Workflow: Review a Shared Document

When given a Proof URL like https://www.proofeditor.ai/d/abc123?token=xxx:

1. Extract the slug (abc123) and token from the URL
2. Read the document state via the API
3. Add comments or suggest edits using the ops endpoint
4. The author sees changes in real-time

# Read
curl -s "https://www.proofeditor.ai/api/agent/abc123/state" \
  -H "x-share-token: xxx"

# Get baseToken for the next mutation
BASE=$(curl -s "https://www.proofeditor.ai/api/agent/abc123/state" \
  -H "x-share-token: xxx" | jq -r '.mutationBase.token')

# Comment
curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops" \
  -H "Content-Type: application/json" \
  -H "x-share-token: xxx" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -d "$(jq -n --arg base "$BASE" '{type:"comment.add",quote:"text",by:"ai:compound-engineering",text:"comment",baseToken:$base}')"

# Suggest edit (tracked, pending)
curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops" \
  -H "Content-Type: application/json" \
  -H "x-share-token: xxx" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -d "$(jq -n --arg base "$BASE" '{type:"suggestion.add",kind:"replace",quote:"old",by:"ai:compound-engineering",content:"new",baseToken:$base}')"

# Suggest and immediately apply (tracked, committ

---

*Content truncated.*