proof-collab

Skill Instructions

# Proof Collaboration

Proof is Every's agent-native markdown editor. It tracks who wrote what (human vs AI) and lets agents collaborate through suggestions, comments, and rewrites — all via HTTP API.

## Create a New Doc

```bash
curl -sS -X POST https://www.proofeditor.ai/share/markdown \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg title "Doc Title" --arg markdown "# Content here" '{title: $title, markdown: $markdown}')"
```

Returns: `{shareUrl, slug, ownerSecret, accessToken}`

Share URL format: `https://www.proofeditor.ai/d/<slug>`

**Always write markdown to a temp file and use jq to build the JSON payload** — shell escaping breaks with inline heredocs for complex content.

```bash
# Recommended pattern for complex content:
cat > /tmp/content.md << 'EOF'
# Your Content Here
...
EOF
CONTENT=$(cat /tmp/content.md)
curl -sS -X POST https://www.proofeditor.ai/share/markdown \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg title "Title" --arg markdown "$CONTENT" '{title: $title, markdown: $markdown}')"
```

## Read a Doc

Given a URL like `https://www.proofeditor.ai/d/abc123`:

```bash
curl -s https://www.proofeditor.ai/api/agent/abc123/state
```

Returns `{content: "markdown..."}` — use `content` as source of truth, not `plainText`.

## Edit a Doc (Ops)

```bash
curl -s -X POST https://www.proofeditor.ai/api/documents/abc123/ops \
  -H "Content-Type: application/json" \
  -d '{"type": "comment.add", "quote": "text to comment on", "text": "your comment", "by": "ai:your-name"}'
```

Always include `"by": "ai:<your-name>"` for attribution.

### Supported op types

- `comment.add` — leave a comment on specific text
- `comment.reply` — reply to a comment thread
- `comment.resolve` — resolve a comment thread
- `suggestion.add` with `kind: "insert" | "delete" | "replace"` — tracked change suggestion
- `suggestion.accept` / `suggestion.reject` — accept or reject a suggestion
- `rewrite.apply` — bulk rewrite with automatic diff (use for large edits)

### Rewrite (bulk edits)

```json
{
  "type": "rewrite.apply",
  "content": "# Full new markdown content here",
  "by": "ai:your-name"
}
```

Or use changes mode for targeted replacements:

```json
{
  "type": "rewrite.apply",
  "changes": [{"find": "old text", "replace": "new text"}],
  "by": "ai:your-name"
}
```

## Auth

- Public docs: no token needed for comments/suggestions
- Protected actions: `x-bridge-token: <ownerSecret>` or `Authorization: Bearer <accessToken>`

## Safety Rules

- Use `content` from `/state`, not `plainText`, as your source of truth
- For table edits, update one cell at a time or use `rewrite.apply` with changes mode
- Never edit the underlying markdown file directly — always use the API
- `POST /share/markdown` is the canonical create route (not `/api/documents`, which is legacy)

## Workflow Pattern

1. Create doc → get `slug` and `shareUrl`
2. Share the `shareUrl` with the human
3. For later edits: `GET /api/agent/<slug>/state` to read, `POST /api/documents/<slug>/ops` to write
4. Always attribute with `"by": "ai:<your-name>"`

Raw SKILL.md