[Skill Submission] proof-docs

skills/proof-docs/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: proof-docs
+description: >
+  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.
+tags: [writing, collaboration, documents, editor]
+---
+
+# 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.

skills/proof-docs/references/api.md

@@ -0,0 +1,185 @@
+# Proof Agent API Reference
+
+Source: https://www.proofeditor.ai/agent-docs (fetched 2026-02-20)
+
+## Reading a Document
+
+If you have a shared link like `https://www.proofeditor.ai/d/<slug>?token=<token>`, use content negotiation:
+
+**Fetch JSON (recommended):**
+```bash
+curl -H "Accept: application/json" "https://www.proofeditor.ai/d/<slug>?token=<token>"
+```
+
+**Fetch raw markdown:**
+```bash
+curl -H "Accept: text/markdown" "https://www.proofeditor.ai/d/<slug>?token=<token>"
+```
+
+The JSON response includes:
+- `markdown` (document content)
+- `_links` (state, ops, docs)
+- `agent.auth` hints (how to use the token)
+
+## Auth
+
+If a URL contains `?token=`, treat it as an access token:
+- Preferred: `Authorization: Bearer <token>`
+- Also accepted: `x-share-token: <token>`
+
+## Create a New Document
+
+```bash
+curl -sS -X POST https://www.proofeditor.ai/share/markdown \
+  -H "Content-Type: application/json" \
+  -d '{"title":"My Doc","markdown":"# Hello\n\nFirst draft.","by":"ai:<your-name>"}'
+```
+
+Response includes: `slug`, `accessToken`, `ownerSecret`, `tokenUrl`
+
+## Edit Via Ops (Comments, Suggestions, Rewrite)
+
+**Endpoint:** `POST /api/agent/<slug>/ops`
+
+### Add a comment
+```bash
+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
+```bash
+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"}'
+```
+
+### Rewrite the whole document
+```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":"# New markdown..."}'
+```
+
+## Edit Via Structured Operations (Append, Replace, Insert)
+
+**Endpoint:** `POST /api/agent/<slug>/edit`
+
+All requests require `Content-Type: application/json` and auth via `Authorization: Bearer <token>`.
+Body must include an `operations` array (max 50 ops) and a `by` field.
+
+### Append to a section
+```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 here."}
+    ]
+  }'
+```
+
+### Replace text
+```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": "replace", "search": "old text to find", "content": "new replacement text"}
+    ]
+  }'
+```
+
+### Insert after text
+```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": "insert", "after": "anchor text to find", "content": "\n\nContent to insert after the anchor."}
+    ]
+  }'
+```
+
+### Multiple operations
+```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": "Notes", "content": "\n\nNew note."},
+      {"op": "replace", "search": "(placeholder)", "content": "Actual content here."}
+    ]
+  }'
+```
+
+### Response
+```json
+{
+  "success": true,
+  "slug": "<slug>",
+  "updatedAt": "<ISO timestamp>",
+  "collabApplied": true,
+  "presenceApplied": true
+}
+```
+
+### Optimistic locking (optional)
+Pass `baseUpdatedAt` from a prior state response to detect concurrent edits:
+```json
+{"by": "ai:<your-name>", "baseUpdatedAt": "2026-02-16T...", "operations": [...]}
+```
+If stale, returns `409` with `retryWithState`.
+
+## Edit V2 (Block IDs + Revision Locking)
+
+### Get a snapshot
+```bash
+curl -H "Authorization: Bearer <token>" "https://www.proofeditor.ai/api/agent/<slug>/snapshot"
+```
+Response includes `revision` and ordered `blocks` array with deterministic refs (`b1`, `b2`, ...).
+
+### Apply edits
+```bash
+curl -X POST "https://www.proofeditor.ai/api/agent/<slug>/edit/v2" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -H "Idempotency-Key: <uuid>" \
+  -d '{
+    "by": "ai:<your-name>",
+    "baseRevision": 128,
+    "operations": [
+      {"op": "replace_block", "ref": "b3", "block": {"markdown": "Updated paragraph."}},
+      {"op": "insert_after", "ref": "b3", "blocks": [{"markdown": "## New Section"}]}
+    ]
+  }'
+```
+On stale `baseRevision`: returns `STALE_REVISION` + latest snapshot for retry.
+
+## Presence and Event Polling
+
+**Poll for changes:**
+```bash
+GET /api/agent/<slug>/events/pending?after=<cursor>&limit=100
+```
+
+**Ack processed events:**
+```bash
+POST /api/agent/<slug>/events/ack
+Body: {"upToId": <cursor>, "by": "ai:<your-name>"}
+```
+
+## State Endpoint
+
+```bash
+curl -H "Authorization: Bearer <token>" "https://www.proofeditor.ai/api/agent/<slug>/state"
+```