# 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 /api/agent/<slug>/state
- POST /api/agent/<slug>/edit/v2
- POST /api/agent/<slug>/ops
- GET /api/agent/<slug>/events/pending
- POST /api/agent/<slug>/presence

Comment reading:
- Read comment bodies, replies, and resolved state from GET /api/agent/<slug>/state via marks.
- Use /snapshot for block refs and edit/v2 only.
- Use /events/pending to notice activity, not as the source of comment thread text.

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

## Optional: Local Mac App Bridge (localhost:9847)

Only needed when collaborating inside the native Proof macOS app.

Install latest app:
  pkill -f "Proof.app" 2>/dev/null; sleep 1
  curl -fsSL "https://api.amore.computer/v1/apps/com.every.Proof/download" -o /tmp/Proof.zip
  # (fallback) curl -fsSL "https://github.com/EveryInc/proof/releases/latest/download/Proof.zip" -o /tmp/Proof.zip
  cd /tmp && unzip -o Proof.zip
  cp -R /tmp/Proof.app /Applications/
  rm -f /tmp/Proof.zip /tmp/Proof.app

If you are Claude Code, install hooks:
  bash <(curl -sL https://www.proofeditor.ai/install-hooks.sh)

Open welcome doc:
  WELCOME_SRC="/Applications/Proof.app/Contents/Resources/Welcome.md"
  WELCOME_DST=~/Documents/Welcome\ to\ Proof.md
  if [ -f "$WELCOME_SRC" ]; then cp "$WELCOME_SRC" "$WELCOME_DST"; else curl -sL https://www.proofeditor.ai/welcome.md -o "$WELCOME_DST"; fi
  open /Applications/Proof.app "$WELCOME_DST"

Check bridge:
  curl -s http://localhost:9847/windows

Common bridge actions:
- GET /state
- POST /marks/comment
- POST /marks/suggest-replace
- GET /events/pending
- POST /presence

Always set:
- X-Agent-Id: <agent-id>
- by: "ai:<agent-id>" on write payloads