ce-proof

Publish a local markdown file to a shareable Proof URL, or read, comment on, and edit an existing Proof doc.

Proof is a real-time markdown editor where humans and agents work in the same document. ce-proof is the plugin’s bridge to it. Despite the name, it does not proofread, check math, gather evidence, or build proofs of concept.

The usual job is a one-way publish: take a local markdown file (a brainstorm, a plan, a learning, a draft), create a shared Proof doc, and hand back a URL. The local file stays canonical. Publishing writes nothing back to disk.

Given a Proof URL instead of a file, it reads the doc and can comment, suggest, or edit through Proof’s hosted v3 API. Pulling remote content down to a local file is a separate, explicit action.

TL;DR

Question Answer
What does it do? Publishes local markdown to a shareable Proof URL, or reads, comments on, and edits a Proof doc you point it at
When to use it You want a shareable link, a wrap-up menu offered “Publish to Proof”, or the agent should work from a Proof URL
What it produces A shareable tokenUrl (publish), comments or edits on a shared doc, or a local markdown file (explicit pull)
What’s next Open the URL, share it, or return to the skill that handed off. The local file is unchanged.
Sync One-way by default. A pull is a separate, confirmed write.

Example invocations

Publishing creates a new shared doc. A URL argument reads or edits that doc. A pull writes remote content to disk.

# Publish a named markdown file and keep the local file canonical
/ce-proof share docs/plans/notification-mute.md to Proof

# Same request in everyday language; the file is the one just created or edited
/ce-proof share this to Proof

# Publish a learning or other draft, not only a plan
/ce-proof publish docs/solutions/notification-mute-race.md to Proof

# Read, comment on, or edit an existing shared doc
/ce-proof https://www.proofeditor.ai/d/example?token=example

# Pull current Proof content onto disk. This overwrites the local file.
/ce-proof pull this Proof document to docs/reviews/notification-mute.md

# Remove an unclaimed doc this session created
/ce-proof delete the Proof doc we just published

Only markdown is published. An HTML plan stays local; the skill returns the local browser path instead of uploading it. Don’t put secrets or private personal data in Proof unless you explicitly approve the upload.

The Problem

Sharing a long markdown draft for review is awkward. Chat loses structure, and a 2,000-line plan pasted into a thread is hard to comment on. “See the bullet on line 47” does not stay attached to that bullet a week later. Suggested edits need accept/reject, not a second copy of the file.

The API side has its own traps. Agent edits need a stable identity, or the comment trail looks like several different authors. Create returns an ownerSecret that is the only delete credential for an unclaimed doc; drop it and the doc can never be cleaned up. And an upload is a real third-party transfer, so you should know what is leaving disk.

The Solution

ce-proof talks to Proof’s hosted API at proofeditor.ai. Publish reads the local markdown, posts it to POST /share/markdown, binds the display name, and returns the tokenUrl. Nothing syncs back.

For collaboration it reads v3/document and writes through v3/edit, choosing the narrowest operation that expresses the change: a scoped replace, insert, or delete first, then suggestions, then whole-doc replace only when you asked for it or a narrow edit cannot express the change.

A pull is explicit. It reads the current Proof markdown and writes it atomically to a local path. If the pull is a side effect of something else, the skill asks first.

Cleanup deletes an unclaimed doc with the session ownerSecret when you ask. Publish handoffs never auto-delete; review docs need to linger.

If typed proof_* MCP tools are already available, the skill prefers those. Otherwise it uses HTTP.

What Makes It Novel

One-way publish is the default

The chain use is “give me a link.” The local file remains the record. Two entries land here: a direct request (“share this to proof”, “get me a proof link for this doc”) and an upstream handoff from ce-ideate (markdown output) or a non-software ce-brainstorm or ce-plan.

Software brainstorm and software plan menus do not offer Proof. Invoke /ce-proof yourself on the markdown file. HTML artifacts are never uploaded.

When the source is a unified plan and its readiness metadata is known, the Proof title carries it: Plan: <title> (requirements-only) or Plan: <title> (implementation-ready).

Two credentials, different jobs

Create returns accessToken (everyday read, edit, presence) and ownerSecret (delete, while the doc is unclaimed). The skill keeps ownerSecret in session memory only and never writes tokens into the repo. It always shares the tokenUrl, not a bare /d/<slug>, because the editor token doubles as the claim capability.

If someone claims the doc in the Proof UI, ownerSecret is revoked for good. accessToken still works, and delete then belongs to the owner’s Every account.

Narrow edits before big ones

Edit targets are visible text, not raw markdown syntax. Ambiguous matches fail closed rather than guessing at the first occurrence. set_document comes last and is applied as a minimal diff, so it is safe with live collaborators. Emptying the markdown does not remove comment marks; a privacy cleanup means deleting the document.

Every write is attributed as by: "ai:compound-engineering" with display name Compound Engineering. Callers can override the pair on purpose; improvised variants like ai:compound are not allowed.

Quick Example

You ask to share a notification-mute plan. The skill reads the markdown, posts it to /share/markdown, keeps accessToken and ownerSecret in session memory, binds the display name, and prints the tokenUrl. The local plan file is untouched.

You open the URL, leave inline comments, and send the link to a teammate. Nothing syncs back. If a wrap-up menu handed this off, that menu comes back so you can start work, create an issue, or stop.

Later, /ce-proof pull this Proof document to docs/reviews/notification-mute.md writes the current Proof markdown to that path.

When to Reach For It

Use ce-proof when:

  • You want a shareable URL for a markdown brainstorm, plan, learning, or draft
  • A wrap-up menu offered “Publish to Proof” (ce-ideate markdown, non-software brainstorm, non-software plan)
  • You have a Proof URL and want the agent to read, comment, or edit
  • You want the current Proof state on disk as a deliberate pull

Skip it when:

  • You want a document reviewed for gaps or quality. That is /ce-doc-review, or /ce-code-review for code.
  • The artifact is HTML. Open the local file; Proof does not ingest HTML.
  • The doc is small enough that chat is enough.
  • You are offline. The skill needs proofeditor.ai.
  • The content is too sensitive to upload.

Use as Part of the Workflow

Wrap-up menus that offer Proof: non-software /ce-brainstorm, non-software /ce-plan, and /ce-ideate Phase 5 on markdown output.

The handoff is one-way. ce-proof publishes, prints the URL, and returns control. The originating skill’s local file stays canonical, so that menu can re-render as it was.

Software brainstorm and software plan menus do not include Proof. Publish those markdown files with a direct /ce-proof invoke.

Use Standalone

  • Publish a file: /ce-proof share docs/plans/foo.md to Proof
  • Publish the file just edited: share this to proof
  • Work from a URL: /ce-proof https://www.proofeditor.ai/d/abc123?token=xxx
  • Pull to disk: an explicit path, atomic write, confirmed when it is a side effect
  • Cleanup: delete an unclaimed doc this session created, using the session ownerSecret

Reference

Argument Effect
(empty) or share this to Proof Publishes the markdown file just created, edited, or referenced. Asks which file if that is unclear.
<path> / share <path> to Proof Publishes that markdown file. HTML is refused.
<Proof URL> Reads the doc, then comments or edits if that is what you asked.
pull … to <path> Writes current Proof markdown to that local path. Confirms first when the pull is a side effect.
delete / clean up Deletes an unclaimed doc this session created. After claim, ask the owner.
API When
POST /share/markdown Create / publish
GET /api/agent/{slug}/v3/document Read markdown, comments, suggestions
POST /api/agent/{slug}/v3/edit Content and review mutations
DELETE /api/documents/{slug} Owner delete (ownerSecret or Every owner session)

Content ops: replace / insert / delete, then set_document last. Review ops: comment / reply / resolve / unresolve (no comment delete), suggest (text, plus typed table/format/atom/node forms) / modify_suggestion / accept / reject. Limits: 100 ops per request, 2 MiB per set_document.

Identity defaults: by: "ai:compound-engineering", X-Agent-Id: ai:compound-engineering, name: "Compound Engineering".

FAQ

Does publishing sync edits back to my local file? No. Publishing creates a shared doc and returns a URL. Pull explicitly if you want the current Proof state on disk.

Why two tokens on create? accessToken is the everyday bearer. ownerSecret is the only credential that can delete an ownerless agent-created doc. Dropping ownerSecret leaves an undeletable orphan.

Should I rewrite the whole doc? Almost never as a first move. Prefer replace / insert / delete. Use suggest when visible track changes matter. Use set_document only for a full replacement you asked for, or a change that cannot be expressed narrowly.

Can I edit a doc while a user is connected? Yes. v3 content and review ops work during live collab. set_document is applied as a minimal diff.

Does emptying a doc remove comments? No. Delete the document with ownerSecret while it is unclaimed, or ask the owner after claim.

What if the upload fails? The skill retries once. After that you get an error and can stay in the originating menu without the Proof link. Persistent failures can be reported to Proof via POST /api/bridge/report_bug.

See Also