# Proof — Agent Setup

Start here for the primary flow:
  https://www.proofeditor.ai/

The homepage tabs include agent-specific install instructions. This page is the
short fallback reference.

## Web-first Quickstart (Recommended)

1) Install the unified Proof skill:

Claude Code:
  mkdir -p ~/.claude/skills/proof && curl -fsSL https://www.proofeditor.ai/proof.SKILL.md -o ~/.claude/skills/proof/SKILL.md

Codex:
  mkdir -p ~/.codex/skills/proof && curl -fsSL https://www.proofeditor.ai/proof.SKILL.md -o ~/.codex/skills/proof/SKILL.md

2) Create a shared web doc:

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

3) Use the returned URL and token with:
- GET the shared URL with Accept: application/json or Accept: text/markdown
- GET /api/agent/<slug>/v3/document
- POST /api/agent/<slug>/v3/edit
- GET /api/agent/<slug>/events/pending
- GET /api/agent/<slug>/events/stream
- POST /api/agent/<slug>/presence
- PUT /api/documents/<slug>/title

Read and edit (v3):
- Read everything in one call: GET /api/agent/<slug>/v3/document returns { ok, revision, title, markdown, comments[], suggestions[] }.
- Edit in one call: POST /api/agent/<slug>/v3/edit with { by, operations: [...] }.
- Targets are the visible text in markdown, not raw markdown syntax or opaque refs. You never send a base token.
- Content ops: replace {find, with}, insert {after|before, markdown}, delete {find}, set_document {markdown}.
- Review ops: comment {on, body}, reply {comment, body, resolve?}, resolve/unresolve {comment}, suggest {kind, find, with?}, accept/reject {suggestion}.
- baseRevision (the integer from v3/document) and Idempotency-Key are optional.
- Errors use one envelope { ok:false, error:{ code, message, retryable, current? } }. When retryable is true, error.current carries the fresh document; re-resolve and retry against it.

Event streams:
- Omit a cursor to receive only new events; pass after=<id> or Last-Event-ID only for replay.
- Event frames include id:, event: <type>, and JSON data:. Streams send heartbeat comments and close periodically; planned closes include an id-only event: cursor frame so clients can reconnect with the last seen id.

Presence identity:
- Bearer/share tokens authenticate document access.
- Include X-Agent-Id: ai:<agent-id> when joining the doc or posting /presence.
- POST /presence accepts X-Agent-Id, agentId, or agent.id.
- by records authorship.

Title:
- PUT /api/documents/<slug>/title uses Authorization: Bearer <token> or x-share-token.

Comment reading:
- Read comment bodies, replies, and resolved state from GET /api/agent/<slug>/v3/document via comments[].
- Read pending suggestions from the same response via suggestions[].
- Use the comment id as the reply/resolve target.
- v3 review ops support resolving and unresolving comments; they do not support deleting comments.
- Use /events/pending or /events/stream to notice activity. Do not treat it as the canonical source of comment thread text.
- text.settled is a sparse wake signal for normal text edits after collab persistence settles; re-read v3/document before interpreting or editing.

Docs:
- https://www.proofeditor.ai/agent-docs
- https://www.proofeditor.ai/.well-known/agent.json
- https://www.proofeditor.ai/api/bridge/report_bug

## If Proof Looks Wrong

Call:

  POST https://www.proofeditor.ai/api/bridge/report_bug

Send a short summary, free-form context, and any raw evidence you have like request/response pairs, request IDs, or stale state/snapshot payloads.

If the response says:
- status=needs_more_info

Ask those questions and call the same endpoint again.

Optional reference code while debugging:
- https://github.com/EveryInc/proof-sdk
  (point-in-time snapshot; lags production — verify any bug against proofeditor.ai before filing)