ce-proof

Create, share, and collaboratively review markdown documents via the Proof editor API.

Updated Mar 17, 2026
One-click install
npx skills add https://github.com/Norfolk-Group/marcela-norfolk-ai --skill ce-proof-norfolk-group
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ce-proof
Source: https://github.com/Norfolk-Group/marcela-norfolk-ai/tree/main/skills/compound-engineering/skills/ce-proof
Command: npx skills add https://github.com/Norfolk-Group/marcela-norfolk-ai --skill ce-proof-norfolk-group

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Reviewing markdown drafts (specs, plans, brainstorms) with a human in the loop is awkward over chat alone. This Skill uploads local markdown files to Proof, the collaborative editor at proofeditor.ai, so a human can annotate in a web UI while the agent reads comments, replies in-thread, applies tracked edits, and syncs the final document back to disk. ## Core Features & Use Cases - Share and edit markdown via Web API: Create shareable Proof documents with a token URL, read state, add comments, and apply tracked suggestions or atomic block-level edits through the /ops and /edit/v2 endpoints. - Human-in-the-loop review loops: Run a full HITL cycle — upload a local file, ingest human feedback as in-thread replies and accepted suggestions, report open threads in the terminal, and atomically sync the reviewed doc back to the local file. - Local bridge mode: Drive the macOS Proof app over localhost:9847 for presence, marks, and rewrites when the desktop app is running. - Use Case: After drafting a plan with ce-plan, hand the markdown file off for review — the user highlights text and leaves comments in Proof, the agent applies fixes with an auditable suggestion trail, and the reviewed document is written back to disk. ## Quick Start Share the markdown file I just created to Proof so we can iterate on it together, then sync the reviewed version back to my local file.

Frequently Asked Questions about ce-proof

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I share a markdown file for collaborative review?

POST the title and markdown content to https://www.proofeditor.ai/share/markdown with no authentication. The response returns a tokenUrl you can share, plus an accessToken and API links for reading state and submitting edit operations.

How do I run a human-in-the-loop review on a markdown document?

Upload the local file to Proof, let the user highlight text and leave comments in the web UI, then run an ingest pass that replies to each human-authored mark, applies fixes as accepted suggestions, and syncs the final markdown back to the local file atomically.

What is the difference between the Proof /ops endpoint and /edit/v2?

The /ops endpoint takes a top-level type field for comments, replies, suggestions, and whole-doc rewrites. The /edit/v2 endpoint takes an operations array of block-level edits (replace_block, insert_after, delete_block) that commit atomically using block refs from /snapshot.

Why did my Proof edit fail with STALE_BASE or BASE_TOKEN_REQUIRED?

Every mutation requires a baseToken from the most recent /state or /snapshot read. On STALE_BASE or BASE_TOKEN_REQUIRED, re-read the document state and retry once with the same payload and the fresh token.

Can I edit a Proof document while a user has it open?

Yes. The /edit/v2 endpoint, suggestion.add, and all comment operations work during active collaboration. Only rewrite.apply is blocked with LIVE_CLIENTS_PRESENT because it would overwrite in-flight edits.

How do I avoid duplicate comments when retrying failed Proof API calls?

Include an Idempotency-Key header per logical write and reuse it only when retrying the identical payload. After ambiguous failures like timeouts or 5xx, re-read /state and verify the mark exists before retrying, since the write may have already landed.