Proof - Collaborative Markdown Editor

Proof is a collaborative document editor for humans and agents. It is reached through the hosted web API at https://www.proofeditor.ai, over HTTP from Bash.

Outcome: the user holds a working tokenized Proof link, or the doc carries the read, comment, suggestion, or edit they asked for.

Done: the operation is confirmed at its own level, and the user has the result plus a short summary. A create is confirmed by the tokenUrl it returned. A mutation is confirmed by ok: true; on a 202 or a partial: true response, confirm by re-reading v3/document. A pull is confirmed by the local file it wrote, and a read by the content it returned.

Read references/api.md before the first Proof read or mutation, HTTP or MCP. It defines the endpoints: share/markdown, the v3 document and edit endpoints, presence, title, and DELETE /api/documents/<slug>. It also carries the operation tables, the error and retry classes, and the curl permission hint for Claude Code.

Read references/workflows.md before reviewing a shared doc, before creating and sharing one, and before pulling a doc to a local file. Those flows have exact recipes there.

If typed proof_* MCP tools are already available in the harness (proof_share_markdown, proof_v3_document, proof_v3_edit, proof_presence, proof_document_title, proof_document_delete, proof_report_bug), prefer them. Otherwise use the HTTP recipes. In MCP mode the server injects by, X-Agent-Id, and presence identity. Pass the ?token= value from the Proof URL as shareToken for edits and presence on docs the signed-in user does not own.

Delete authority is unchanged in MCP mode. An unclaimed doc still needs its ownerSecret, and a claimed doc needs its owner's session. An editor accessToken passed as shareToken cannot delete.

Identity

Every write is attributed with both fields, and they do not vary. The machine ID is ai:compound-engineering, sent as by on every op and as the X-Agent-Id header. The display name is Compound Engineering, sent as name on POST /presence, set once per doc session so Proof binds it to that agent ID. A caller may pass a different identity pair when a distinct sub-agent should own the doc. Never improvise a variant such as ai:compound.

Credentials and boundaries

• accessToken is the everyday bearer for read, edit, presence, and events. ownerSecret carries owner authority only — delete and other owner-level ops — and is never the everyday bearer. Capture both at create time, and persist ownerSecret for the session separately from accessToken, in shell vars or equivalent; it is required for owner delete while the doc is unclaimed. Neither belongs in repo-tracked files, commits, or durable logs, and ownerSecret never appears in user-facing copy.
• Hand humans the tokenized link (tokenUrl), never a bare /d/<slug> — the token in that link is also what lets a signed-in user claim an ownerless doc.
• Public creates are ownerless until a signed-in Every user claims the doc in the browser. Claiming permanently revokes ownerSecret while accessToken keeps working, so delete then needs the owner's Every session — ask the owner, or use their session token. Two responses mean the secret was revoked: a 403 with code: "DOCUMENT_DELETE_FORBIDDEN" and reason: "CREDENTIAL_NOT_OWNER", or a 401 when presenting the creation ownerSecret. Stop using the secret rather than retrying. reason: "DOCUMENT_HAS_NO_OWNER" is the opposite: the doc is still unclaimed, so only the original ownerSecret can delete it and an Every session cannot.
• Never put secrets, credentials, API keys, private tokens, or sensitive personal data into a Proof doc unless the user explicitly approves, and never silently replace a repo-tracked project doc with a Proof link.
• Emptying the markdown does not scrub comment marks. Quotes and commentary stay readable to anyone with the share credential, so a content wipe is not a privacy cleanup. Deleting the document is — with ownerSecret while the doc is unclaimed, or as the owner after a claim.
• Do not auto-delete after a publish handoff. Review docs must linger. Delete when the user asks, or when finishing an explicitly ephemeral scratch doc.

Publish mode

The primary use is one-way publishing. Read an existing local markdown file in full, post its contents as the new doc's body, and hand the user the shareable URL. The local file stays canonical — publishing syncs nothing back to disk.

Two entry points share those mechanics. One is a bare user request naming a local markdown file ("share this to proof", "get me a proof link for this doc"); ask which file only if it is ambiguous, and expect no upstream caller. The other is a handoff from ce-brainstorm, ce-ideate, or ce-plan passing the file path and title.

Only publish markdown. If the source is an HTML unified plan, return the local browser/open path instead of uploading it. When publishing a unified plan, label the title by readiness when it is known, e.g. Plan: <title> (requirements-only) or Plan: <title> (implementation-ready).

Publish the source file's bytes, never hand-written or placeholder content. references/workflows.md gives the jq --rawfile recipe that escapes newlines, quotes, and backticks correctly. After a publish handoff, show the user the URL and return control.

Editing

GET /api/agent/<slug>/v3/document and POST /api/agent/<slug>/v3/edit are the only endpoints an agent reads from and writes to. Comments, replies, resolutions, suggestions, and content changes are all operations in the v3 edit body, so a path you did not read in references/api.md is one you invented.

Read v3/document as the source of truth before editing. Then choose the narrowest operation that expresses the change: a scoped replace, insert, or delete for prose; suggest when the change should be visible as tracked changes; set_document only when the user asks for a whole-doc replacement, or the change cannot be expressed narrowly. Targets are visible text in markdown, never raw markdown syntax or block refs.

comments[] and suggestions[] from that read are the review state. Reply, resolve, unresolve, accept, or reject by id. v3 has no delete-comment op. A comment marked orphaned: true is still readable and replyable, but its old quote is no longer a live anchor.

Errors that mean stop and check, before retrying anything:

• TARGET_AMBIGUOUS — the anchor matched more than once and nothing changed. Disambiguate with occurrence / before / after from error.candidates; never assume silent first-match, and never blind-retry a comment.
• retryable: false — fix the request. retryable: true with error.current — re-resolve targets against current, then retry once.
• 202 / PENDING, or ok: false with partial: true — the write may have committed. Re-read v3/document before chaining or reporting success, and retry only the failed op (a repeated Idempotency-Key replays safely).
• Still failing after a fresh read and one safe retry — report the bug per references/api.md rather than looping.

Pulling a doc down to a local file overwrites that file. When the pull is a side effect of some other action rather than something the user asked for, confirm the path first.