# Proof SDK exposes a document editor and an agent bridge over plain HTTP

> Proof SDK is the open-source collaborative markdown editor, collaboration server, provenance model and agent HTTP bridge behind the hosted Proof editor. The interesting part is the route list, which gives agents a documented way to read state, apply edits and acknowledge events without going through the UI.

**EveryInc/proof-sdk** — Proof SDK: open-source collaborative editor, provenance model, and agent HTTP bridge

- Repository: https://github.com/EveryInc/proof-sdk
- Stars: 1,124 · Forks: 196
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/everyinc-proof-sdk

## The public surface is a list of routes, not a library API

The most concrete thing in the repository is the route list, and the README is explicit about its status. These are the canonical Proof SDK routes, and compatibility aliases remain mounted for the hosted product, but the routes above are the public SDK surface. They fall into groups. There is document creation and reads, with `POST /documents` and `GET /documents/:slug/state` plus a snapshot route. There is a write path, with edit, an edit v2 variant, and an ops route. There is presence, and there is an event queue with a pending read and an ack. Then there is the bridge group, which is the part aimed at agents: state, marks, comments, suggestions, rewrite and presence, all under `/bridge/`. The existence of a v2 edit route alongside the original, and of a bridge group with its own read and write operations, tells you the API has been through at least one redesign, and that the current shape is the one the team settled on.

## Provenance tracking is the feature the editor is built around

The included components are described as a collaborative markdown editor with provenance tracking, comments, suggestions and rewrite operations, a realtime collaboration server, an agent HTTP bridge for state, marks, edits, presence and events, and a small example app. Provenance is the word that carries the design, because it is what the bridge exists to serve. If every edit can be attributed, then a suggestion, a comment and a rewrite are all recorded as changes against a document rather than as overwrites, and an agent acting on a document leaves the same kind of trace a human does. That is also why the routes include a marks endpoint and separate comment and suggestion endpoints rather than a single generic write. The `docs/adr/` directory holds an architecture decision record dated 2026-03 about the public core of the SDK, and the README lists it alongside `AGENT_CONTRACT.md` and `docs/agent-docs.md` as the documents to read before building against this.

## A workspace of six packages rather than one app

The workspace layout explains the shape of the codebase. Under `packages/` sit `doc-core`, `doc-editor`, `doc-server`, `doc-store-sqlite`, `agent-bridge`, and under `apps/` sits `proof-example`. There are also `server/` and `src/` directories at the root. The separation follows the responsibilities: the editor, the collaboration server, the persistence layer and the bridge are independent, and the example app is the consumer that shows how they fit together. The package manifest confirms the monorepo setup with workspaces covering `packages/*` and `apps/*`, and the package name is `proof-sdk` at version 0.1.0. The version number is worth noting, since 0.1.0 with a public API described as canonical is a statement that the surface is young even though the hosted product behind it is not.

## Vite for the client, tsx for the server

The local development setup is short. The only stated requirement is Node.js 18 or newer. Installing dependencies and starting the two processes is three commands:

```bash
npm install
npm run dev
npm run serve
```

The `dev` script runs Vite and the `serve` script runs `tsx server/index.ts`, so the client is served by Vite's dev server and the API is run directly from TypeScript source without a compile step. The default arrangement serves the editor on `http://localhost:3000` and the API and server on `http://localhost:4000`, so the two run side by side during development. The build script is `vite build && node scripts/finalize-web-build.mjs`, and the README states that the build outputs the web bundle to `dist/` and writes `dist/web-artifact-manifest.json`. That manifest is a detail with a purpose: it tells a deployer exactly which artifact was produced, which matters when the output is served as a static bundle by something other than the dev server.

## The stack is Milkdown on ProseMirror with Yjs underneath

The dependency list in package.json describes the editor stack in detail. The editor is built on Milkdown, with the core and kit packages, plus plugins for clipboard, collaboration, cursor, history, listener and Prism syntax highlighting, and presets for CommonMark and GFM, with a Nord theme. Underneath, the presence of `y-prosemirror`, `y-indexeddb`, `ws` and the `y-websock` entry points to Yjs as the synchronisation layer, with IndexedDB for local persistence and a WebSocket provider for realtime. Collaboration server side, the project uses the Hocuspocus server and provider packages. Suggestions are handled by a package called `@handlewithcare/prosemirror-suggest-changes`, which is the piece that turns an edit into a suggestion rather than an overwrite. The rest of the dependencies cover rendering and export, with Satori, resvg, beautiful-mermaid and Prism, and there is an AWS S3 client, an Express server, better-sqlite3 for the store, and a `wink-nlp` package with its model for natural language work.

## Tests run as scripts, and telemetry is off by default

The test command is a chain rather than a single runner. `npm test` runs `test:proof-sdk` and then `test:server-routes-share`, and each of those executes a TypeScript test file with `tsx`, so the test files are plain scripts rather than a framework suite, and the first one is named for the agent bridge client while the second covers the server routes and sharing. The `demo:agent` script runs a demo inside the `proof-example` workspace, which is a quick way to see the bridge in action. The environment file shows that telemetry is opt-in, with `VITE_ENABLE_TELEMETRY=false` as the default, alongside `VITE_APP_VERSION=dev` for tagging events. The repository also carries a `tsconfig.json` and a separate `tsconfig.server.json`, a `vite.config.ts`, a `.env.example` and a `public/` directory for static assets.

## MIT for the code, a separate file for the trademark

Licensing is split in two. The code is under the MIT licence, with the licence text in the `LICENSE` file, and the README points to a separate `TRADEMARKS.md` for trademark guidance. That separation is a deliberate choice common to projects whose code is open but whose name is not, and it means the code licence tells you nothing about whether you may call your product Proof. The SDK carries no GitHub releases, so there is no tagged version to pin to, and the last push to the main branch was on 2026-08-27. The project is published under an MIT licence at version 0.1.0 in the package manifest, and the repository has no dedicated homepage, with the hosted product at proofeditor.ai and the company behind it at every.to. The AGENT_CONTRACT.md file at the repository root is the document an integrator should read first, since it is the contract the agent-facing routes implement.

## Conclusion

Adopt Proof SDK if you want a self-hosted collaborative markdown editor where an automated agent can read and change documents through a documented HTTP surface, since the bridge routes are the public contract and the provenance model is part of the design. Do not adopt it as a general purpose CMS, since the public surface is a fixed route list for a specific editor with no content type system beyond markdown. Verify first that the `AGENT_CONTRACT.md` file and the architecture decision record in `docs/adr/` match what you intend to build, that the SQLite store package is enough for your scale, and that the trademark guidance in `TRADEMARKS.md` is acceptable if you plan to present the result under the Proof name.

## FAQ

### What is included in the Proof SDK?

A collaborative markdown editor with provenance tracking, comments, suggestions and rewrite operations, a realtime collaboration server, an agent HTTP bridge for state, marks, edits, presence and events, and a small example app under `apps/proof-example`.

### How do I run the Proof SDK locally?

With Node.js 18 or newer, run `npm install`, then `npm run dev` to start the editor through Vite and `npm run serve` to start the API from `server/index.ts`. The editor is served on `http://localhost:3000` and the API on `http://localhost:4000`.

### What HTTP routes does the Proof SDK expose?

The public surface includes `POST /documents`, `GET /documents/:slug/state`, `GET /documents/:slug/snapshot`, `POST /documents/:slug/edit`, `POST /documents/:slug/edit/v2`, `POST /documents/:slug/ops`, `POST /documents/:slug/presence`, pending events and ack routes, and a bridge group covering state, marks, comments, suggestions, rewrite and presence. Compatibility aliases remain mounted for the hosted product.

### Which editor framework does the Proof SDK use?

The package manifest shows Milkdown with the CommonMark and GFM presets, plugins for collaboration, cursor, history, clipboard and Prism highlighting, over ProseMirror with Yjs for synchronisation, and the Hocuspocus server and provider for the collaboration server side.

### What licence applies to Proof SDK?

The code is under the MIT licence in the LICENSE file. Trademark use is handled separately in TRADEMARKS.md, so the code licence does not grant permission to use the Proof name.

## Sources

- [EveryInc/proof-sdk on GitHub](https://github.com/EveryInc/proof-sdk)
- [Issues](https://github.com/EveryInc/proof-sdk/issues)
- [License: MIT](https://github.com/EveryInc/proof-sdk/blob/main/LICENSE)
- [README](https://github.com/EveryInc/proof-sdk/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/everyinc-proof-sdk