ce-proof

An interface to Proof, a collaborative markdown editor for humans and agents, used to publish, read, comment on, or edit documents. It is scoped to the Proof product specifically and is meant for sharing specs, plans, and drafts or publishing handoffs from planning workflows, while deliberately excluding unrelated meanings of the word proof such as proofreading, mathematical proof, or proof-of-concept. Proof works in two modes: a no-install Web API over HTTP and a Local Bridge that drives the macOS Proof app on localhost:9847.

The primary use is one-way publishing: read the full contents of an existing local markdown file (a brainstorm, unified plan, learning, or draft) and post them as a new Proof document's body, then hand the user a shareable tokenUrl. The local file stays canonical and publishing does not sync back to disk. There are two entry points with identical mechanics — a direct user request naming a local markdown file (for example "share this to proof"), and an upstream handoff from skills like ce-brainstorm, ce-ideate, or ce-plan. Only markdown is published; an HTML unified plan is not uploaded but returned as a local open path, and plan titles are labeled by readiness such as requirements-only or implementation-ready. Every write is attributed via a stable machine ID (ai:compound-engineering, sent as X-Agent-Id) and a human-readable display name (Compound Engineering) set once per session through the presence endpoint.

For reading and editing, shared documents are fetched directly with content negotiation (JSON or text/markdown), and the /state endpoint supplies mutation metadata, marks, and presence, with a ?kinds=comment filter to separate review comments from provenance marks. Comment, suggestion, and rewrite operations go to /api/agent/{slug}/ops (top-level type field) while block edits go to /api/agent/{slug}/edit/v2 (an operations array with op), and mixing the two wire formats returns 422. Every mutation requires a baseToken reused from the latest read and refreshed from responses, with defined retry handling for stale-base and anchor-not-found errors. The edit strategy explicitly discourages whole-document rewrites, recommending the narrowest primitive: find_replace_in_doc for literal repeated changes, block operations from a fresh snapshot for known sections, suggestion marks for visible track changes, and rewrite.apply only as a last resort when no live clients are present.