proof-docs
Create and manage collaborative documents in Proof (proofeditor.ai). Use whenever working on plans, proposals, drafts, specs, brainstorms, or any collaborative writing. Proof tracks who wrote what (human vs AI provenance). Triggers: "let's plan", "write up", "create a doc", "draft", "document this", "put this in a doc", "proof doc", or any task that produces a structured written artifact worth sharing.
writingcollaborationdocumentseditor
Security Vetted
Reviewed by AI agents and approved by humans.
Skill Instructions
# Proof Docs
Proof is a collaborative editor for humans and AI that tracks who wrote what. Use the HTTP API at https://www.proofeditor.ai â no install needed.
When working on plans, specs, proposals, or any structured writing, create a Proof doc instead of dumping text into chat.
## When to Use Proof
- Planning sessions (features, projects, strategies)
- Drafts (blog posts, emails, proposals)
- Specs and technical documents
- Meeting notes or brainstorm captures
- Anything your human might want to revisit, edit, or share
## When NOT to Use Proof
- Quick answers or status checks
- Simple lists that fit in a message
- Transient information (weather, reminders)
## Provenance
Always use `"by": "ai:<your-name>"` for all API calls. This powers Proof's provenance tracking â the human sees exactly what the agent wrote vs what they wrote.
## Workflow
### 1. Create the doc
```bash
curl -sS -X POST 'https://www.proofeditor.ai/share/markdown' \
-H 'Content-Type: application/json' \
-d '{"title":"<title>","markdown":"<full markdown content>","by":"ai:<your-name>"}'
```
Write the full initial content upfront â don't create empty docs.
### 2. Share the link
Send your human the private share URL: `https://www.proofeditor.ai/d/<slug>?token=<accessToken>`
### 3. Save credentials for editing
Store `slug`, `accessToken`, and `ownerSecret` in your notes for future edits.
### 4. Read a doc
```bash
# JSON (recommended â includes metadata + API links)
curl -H "Accept: application/json" "https://www.proofeditor.ai/d/<slug>?token=<token>"
# Raw markdown
curl -H "Accept: text/markdown" "https://www.proofeditor.ai/d/<slug>?token=<token>"
```
### 5. Edit (surgical)
Use the `/edit` endpoint for targeted changes:
```bash
curl -X POST "https://www.proofeditor.ai/api/agent/<slug>/edit" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"by": "ai:<your-name>",
"operations": [
{"op": "append", "section": "Section Name", "content": "\n\nNew content."},
{"op": "replace", "search": "old text", "content": "new text"},
{"op": "insert", "after": "anchor text", "content": "\n\nInserted content."}
]
}'
```
### 6. Edit (full rewrite)
Use the `/ops` endpoint with `rewrite.apply`:
```bash
curl -X POST "https://www.proofeditor.ai/api/agent/<slug>/ops?token=<token>" \
-H "Content-Type: application/json" \
-d '{"type":"rewrite.apply","by":"ai:<your-name>","content":"# Full new markdown..."}'
```
### 7. Comments and Suggestions
```bash
# Add a comment
curl -X POST "https://www.proofeditor.ai/api/agent/<slug>/ops?token=<token>" \
-H "Content-Type: application/json" \
-d '{"type":"comment.add","by":"ai:<your-name>","quote":"text to anchor","text":"comment body"}'
# Suggest a replace (human accepts or rejects)
curl -X POST "https://www.proofeditor.ai/api/agent/<slug>/ops?token=<token>" \
-H "Content-Type: application/json" \
-d '{"type":"suggestion.add","by":"ai:<your-name>","kind":"replace","quote":"old text","content":"new text"}'
```
## Content Guidelines
- Write like a real document, not chat output
- Use clear headings and structure
- Include context â the doc should stand alone
- Always set `"by": "ai:<your-name>"` for provenance tracking
## Doc Registry
Track all created docs in your notes with: title, slug, ownerSecret, accessToken, and purpose. This ensures future sessions can find and edit them.
## Full API Reference
See `references/api.md` for the complete API including Edit V2 (block IDs + revision locking), event polling, and optimistic locking.