md reph documentation
Pricing llms.txt

reph documentation

Markdown for the AI age.

reph is the workspace where humans and AI build living documents together. Generating markdown is cheap now. The hard part is what comes after: getting it reviewed, keeping it true, and letting a team and its agents change it without anyone losing track.

A reph doc isn't a file you hand around. It's a shared artifact that keeps moving through four verbs:

  1. 01Create

    Templates, imports, the / menu, diagrams, or an agent's create_doc.

  2. 02Collaborate

    Live multiplayer text and canvases, with threads anchored to the words they're about.

  3. 03Review

    Suggestions from people and agents that a human accepts or rejects, with an audit trail.

  4. 04Evolve

    Version history, source refresh, the Atlas map, and publishing to the web.

Contents

Getting started

Concepts

Workflows

AI & Agents

Developer platform

Reference

Part 1 · Getting started

From zero to a shared doc

A few minutes, no install.

1.160-second first look

  1. Open reph: the home page of this site, or your own instance's URL.
  2. Click Try it now →. On an instance that requires sign-in this opens a try-it document that lasts 25 minutes; sign in to keep it. On an open instance you enter as a guest with a persistent local identity.
  3. Type some markdown. Headings, lists and links render as you type. The raw syntax comes back when your cursor enters a line.
  4. Open the same document in a second window and type in one of them. The other updates live, with your cursor shown.
→
That's the core of it: a link that turns into a shared, live document. Everything else in these docs builds on that.

1.2Your first living doc

Template → invite → suggest → publish. This is the whole loop, start to finish.

  1. Start from a template. In the sidebar, open the caret next to + New and choose New from template…. The gallery has 52 built-in templates across 8 categories (engineering, product, design, strategy, operations, people, sales & marketing, personal). + New on its own creates a blank doc.
  2. Invite people. Open Share, add an email, and pick a role: viewer, commenter or editor. New personal docs are private until you share them.
  3. Suggest instead of overwriting. A collaborator selects text and picks Suggest an edit from the selection bubble. You review it in the Suggestions panel (Ctrl/⌘ Shift S) and accept or reject it.
  4. Publish it. As the owner, open Share → Publish to web and tick the toggle. You get a public /p/<slug> page to Copy or View page. See Publish to the web.

Press ? anywhere you aren't typing to see every keyboard shortcut. Ctrl/⌘ O jumps to any document by title.

1.3Signing in

  • Magic link. Enter your email and click the link we send. There's no password.
  • Continue with Google / GitHub. Available when the instance has OAuth configured.
  • Try it now. A try-it session with no account, as described above.
i
On a self-hosted instance with no email provider configured, magic-link URLs print to the server log instead of being emailed. Whoever runs the instance can pass them on.
Part 2 · Concepts

How reph thinks about a document

One markdown text, several ways to see it, and a history that never loses anything.

2.1Documents

Every document is canonical markdown, which is what agents read and write. You can view it in three ways:

Write

Editor

A live-render editor: formatting renders in place and the syntax shows again on the line you're editing. Source mode (Ctrl/⌘ /) shows the raw markdown.

Read

Reading mode

Ctrl/⌘ Shift M. A typographic page with a contents drawer, reading time, width and font settings, and comment-on-selection. When AI is enabled for the doc, it adds the TL;DR · Skim · Full ladder and a Check my understanding quiz.

Understand

Atlas

A structural map of the document, section by section, built from the text with no AI call. Enrich adds per-section AI summaries. Sections whose text has changed since they were enriched are marked stale.

Block kinds

BlockHow you write itNotes
Code```lang fenceSyntax highlighting and a copy button
TablePipe table, or Insert → Table grid pickerScrolls inside its own frame on narrow screens
Mermaid```mermaid fenceRendered live and follows the light/dark theme
CanvasInsert → Diagram… or / Canvas diagramA collaborative Excalidraw scene. The markdown holds only a ```diagram id="…" reference
KPI tiles```kpi fenceMetric tiles with delta and sparkline. Syntax
Chart```chart type="bar|line|area|donut"CSV rows, or from="table" to chart the table above
Collapsible<details> / <summary>Markdown still works inside the body

Per-block sizing

Diagrams, code, tables and images can be resized with grips or a size popover: column width, full width, or an exact pixel size. The size is saved in the document, so everyone sees the same layout. Text blocks store it in the markdown itself, for example width="full" on a fence or <img width>. Canvases keep it with the scene. Document-wide reading and editing width is a personal preference, set per user.

2.2Markdown

reph writes plain markdown with tables, task lists and fenced blocks. Nothing is locked in a proprietary format. Export gives you Copy as Markdown, Markdown (.md), HTML (.html) and PDF (print).

  • Authoring toolbar. Formatting buttons plus an Insert menu: Table, Image (upload or URL), Code block, Divider, Collapsible section, Chart and Diagram…. The same commands appear in the selection bubble and, on phones, in the format bar.
  • / slash menu. Type / on a line for headings, lists, task list, quote, Divider, Code block, Table, Collapsible section, Mermaid diagram, Chart, KPI tiles, Diagram… and Canvas diagram. When AI is available for the doc, the menu also lists ✨ Ask AI actions.
  • Paste and drop. Pasted rich text arrives as markdown, spreadsheet ranges become tables, and dropped images upload in place.

Allowed author HTML

Raw HTML is allowed, but every tag goes through the same allowlist in the editor preview and on published pages:

  • kbd
  • sub
  • sup
  • mark
  • u
  • ins
  • del
  • s
  • small
  • abbr
  • br
  • a
  • details
  • summary
  • div
  • p
  • img
  • hr
  • b
  • strong
  • i
  • em
  • code
  • h1-h6

align is honoured on div, p and headings. style, class, id and on* attributes are never kept. Other known elements (script, iframe, span…) are dropped but their inner text is kept. Unknown tag-like text such as Bearer <token> is escaped, so it shows up as written.

2.3Versions

reph snapshots documents as they change. Open Version history (Ctrl/⌘ Alt/⌥ Shift H) to see them grouped by day.

  • Preview. Select a version to see a word-level diff against the current text, or the raw snapshot.
  • Compare. Diff any two versions against each other.
  • Label. Name a version, for example "Approved by arch review".
  • Restore this version. reph first snapshots the current state, so a restore can itself be undone. The text and the doc's canvases restore together, and every collaborator sees the change live without reloading.

A deleted document goes to Trash, where you can restore it.

2.4Reviews

  • Comments are anchored to text. Select a passage and choose Comment on selection, in the editor or in reading mode. Threads have replies, @-mentions (which notify the person) and resolve. On wide screens, reading mode shows threads in the margin next to the text.
  • Suggestions are tracked changes. Suggest an edit proposes a change without applying it. The Suggestions panel lists each one with its author and note, Accept/Reject, and Accept all from <author>. Agents appear with a square avatar, and in-editor AI actions arrive as suggestions attributed to ✨ AI.
  • Audit trail. Accepting or rejecting writes suggestion.accept / suggestion.reject audit records, so you can always answer "what did the agent do, and who approved it?"

Document roles

RoleCan
ViewerRead
CommenterRead, comment and suggest, but not change the text
EditorEdit directly, and accept or reject suggestions

You set roles per person in Share, or for anyone with the link. Role changes apply live, without a reload.

2.5Collaboration

  • Live editing on a CRDT. Everyone's keystrokes merge without conflicts, you see each other's cursors, and offline edits reconcile when you reconnect.
  • Collaborative canvases. Excalidraw diagrams live inside the doc and sync live like the text. Comments can be pinned to a canvas element, and the pin follows the element as it moves.
  • Workspaces. A workspace holds a team's documents, members and billing. Create one with + New workspace in the sidebar. Members are admin, member or viewer, and docs created in a workspace are open to its members without an explicit share.
  • Seats. Workspaces are billed per seat, and seat limits are enforced when you invite. Viewers never use a seat.
PlanPriceNotes
Free$03 seats included
Pro$5 / seat / moBilled per seated member
EnterpriseContact salesCustom seat and deployment terms

Full breakdown on the pricing page.

2.6AI collaboration

AI in reph is set per workspace: the workspace's own key, bring-your-own, or managed. Where it's available, it follows the same rule as everything else. AI proposes and a human decides.

  • Reading ladder. TL;DR (a few bullets), Skim (one line per section, click to expand) and Full, plus a comprehension quiz.
  • Writing actions. Continue writing, Improve selection, Summarize into intro and Fix grammar, from the selection bubble or the / menu. Output streams in as a preview and lands as a suggestion.
  • AI-generated diagrams. Insert → Diagram… can start from a template, from AI (describe what you want) or from a file, as either a Canvas or a Mermaid diagram. Nothing is inserted until you confirm the preview.
  • Atlas enrichment. Per-section AI summaries on the structural map.
  • Agents as teammates. External agents (Claude, your own) connect over MCP or REST with a scoped token. They read, comment, suggest and ask for review, and they can be registered as named workspace agents that people delegate work to. See AI & Agents.
Part 3 · Workflows

Recipes

Short, concrete paths through the product, using the exact buttons and tools.

3.1Write an RFC

For proposals that need input from several people before a decision.

  1. + New caret → New from template… → Design doc, which covers context, goals, proposed design, alternatives and rollout.
  2. Draft it. Use / Mermaid diagram or Insert → Diagram… for the architecture sketch.
  3. Share → invite reviewers as commenter, so they can comment and suggest but not rewrite.
  4. Reviewers comment on passages and Suggest an edit. You work through the Suggestions panel.
  5. When it's agreed, open Version history and label that version, for example "Accepted". Later changes can be diffed against it.

3.2Review an architecture

For a decision with a diagram at its centre, reviewed by people and an agent.

  1. New from template… → ADR: one decision, its context and its consequences.
  2. Insert → Diagram… → Canvas. Start from a template, describe it to AI, or load a file. Everyone can draw on it at once.
  3. Reviewers pin comments to specific canvas elements ("this queue has no DLQ") and to specific sentences.
  4. Ask an agent for a second opinion. Use Delegate to agent… in the doc toolbar, or @-mention a registered agent in a comment. Its answer comes back as a suggestion in the same queue (see Registered agents).
  5. Accept or reject it. Both are recorded in the audit trail.

3.3Collaborate with AI

An agent working on a doc your team owns, with a human keeping the final say.

  1. The agent reads cheaply first: read_outline, then read_doc.
  2. It proposes changes with suggest_edit, including a note that explains why. These show up as tracked changes, not overwrites.
  3. It calls request_review (optionally naming a reviewer). Collaborators are notified and the agent gets back a reviewUrl and a cursor.
  4. It calls wait_for_review with that cursor as since. The reviewer accepts, rejects, comments, and clicks Return to agent… with a closing message.
  5. The agent iterates on the feedback, answering threads with reply_to_comment / reply_to_suggestion.

3.4Maintain living docs

Docs that already live in files or a git repository, and need to stay true as both sides change.

  1. + New caret → Import…. Drop .md files, Choose folder, or pick Git repository and enter the URL, with an optional branch, subdirectory, and an access token for private repos (the token is used once and not stored).
  2. The import shows up under Linked sources in My Documents or the workspace view. Click Refresh to pull the latest.
  3. On refresh, unchanged files are skipped. Docs changed only at the source are updated in place, with a version snapshot taken first. A doc changed both in reph and at the source gets a pending suggestion from "Source refresh" instead of an overwrite. Refresh never deletes docs.
  4. If something goes wrong, Version history → Restore this version brings back text and canvases together.
  5. In Atlas, sections edited since their last enrichment are flagged stale. Re-enrich just those.

3.5Turn conversations into durable artifacts

A good answer in a chat window disappears. Put it in a doc your team can review.

  1. Connect reph to Claude once (see Claude).
  2. At the end of a useful conversation, say: "Save this as a reph doc called 'Q4 pricing research'."
  3. Claude calls create_doc with the title and markdown, and replies with a reviewUrl link. The new doc is private to you.
  4. Share it. Open the link and use Share, or ask Claude to request_review with a reviewer email, which grants that person access.
  5. Later, from any chat: "Read the pricing doc and suggest an update to the Risks section." This runs search_docs → read_outline → suggest_edit.

3.6Publish to the web

A finished doc becomes a fast public page, and stays linked to the living original.

  1. As the doc's owner, open Share → Publish to web and tick the toggle. reph renders your diagrams in the background and shows "Rendering diagrams…" while it works.
  2. Copy the /p/<slug> URL or View page. The page follows the live doc (re-rendered within about a minute), and unpublishing takes it down immediately.
  3. Choose the owner settings: Show my name on the page (the byline) and Let readers duplicate this doc. Duplication defaults to on for personal docs and off for workspace docs.

What readers get

  • A zero-JavaScript page: server-rendered HTML with reading time and a "last updated" date, readable without an account.
  • A table of contents with per-section reading time once the doc has 3 or more headings. It's a sidebar on wide screens and a Contents drawer on phones.
  • Dark mode that follows the reader's system setting. Mermaid and canvas diagrams are served as light and dark SVG snapshots.
  • KPI and chart blocks, rendered on the server.
  • If duplication is allowed, a Duplicate into your reph button that copies the doc into the reader's own workspace (/duplicate/<slug>).
  • Optional frontmatter: description for the meta description, and cover (an http(s) image URL).

KPI and chart syntax

```kpi
label: ARR | value: $1.2M | delta: +18% | trend: 3,4,4,6,8
label: Churn | value: 2.1% | delta: -0.4% | good: down
```

```chart type="bar" title="Quarterly revenue"
quarter, revenue, target
Q1, 120, 100
Q2, 150, 140
Q3, 170, 160
```

Each KPI line is one tile. label and value are required. delta, a trend sparkline and good: down (for metrics where lower is better) are optional. Chart type is bar, line, area or donut. The first CSV column is the category and each further column is a series. Optional attributes are stacked="true" and, for bar charts, horizontal="true". Use from="table" with an empty body to chart the nearest table above in the same section.

Part 4 · AI & Agents

Agents as teammates, with a leash

Agents use the same documents and review queue as people, through scoped tokens they can't raise themselves.

4.1MCP overview

reph exposes 20 tools over the Model Context Protocol. The same tools are served two ways: a remote endpoint at <your API origin>/mcp, and a stdio server in the repo. Every tool calls the public API with the caller's own token, so scope limits, audit and rate limits apply exactly as they do over REST.

ToolPurposeMin scope
Read
list_docsList documents you can accessread
search_docsSearch titles and content; returns docId, title, snippetread
read_docRead a document as markdownread
read_outlineHeading structure only: cheap context before a targeted editread
read_versionsList version history (id, size, time, author of API writes). Lists only; there's no diff toolread
Write
create_docCreate a doc, optionally with markdown content; returns a reviewUrlsuggest
suggest_editPropose edit ops as pending suggestions with a note. The safe defaultsuggest
edit_docApply edit ops immediately for everyoneedit
Comment
add_commentComment, anchored to quote if it matches exactly oncesuggest
reply_to_commentReply in a comment threadsuggest
reply_to_suggestionReply on a suggestion's threadsuggest
Review loop
request_reviewAsk a human to review; returns reviewUrl and a cursorsuggest
check_reviewNon-blocking read of the review state since a cursorread
wait_for_reviewBlock until a human responds, or until the timeoutread
Delegation (registered agents)
whoamiYour registry identity: name, charter, skills, scope ceilingread
list_assignmentsYour open delegated assignmentsread
wait_for_workLong-poll (up to 60s) for the next assignmentread
start_assignmentMark an assignment in progresssuggest
return_assignmentHand back a summary and the suggestion ids it producedsuggest
decline_assignmentDecline, with a reasonsuggest

4.2Claude

claude.ai remote · no install

  1. In claude.ai, open Settings → Connectors → Add custom connector.
  2. Enter the URL <your API origin>/mcp. For the hosted service that's https://api.reph.dev/mcp.
  3. Click Connect, sign in to reph, and pick an access level on the consent screen: Read only, Suggest (recommended) or Edit. You can also limit the connection to one workspace. The choice is preselected at suggest at most, so edit access is always something you opt into.

The connection is a normal API token. To disconnect, revoke it in Profile → API tokens.

Claude Code remote

claude mcp add --transport http reph https://api.reph.dev/mcp

Then run /mcp inside Claude Code to authenticate in the browser. For a self-hosted instance, use your own <API origin>/mcp.

Claude Code stdio · from the repo

# once, in the repo root (installs the mcp workspace)
npm ci
claude mcp add reph \
  --env REPH_API_URL=<api-origin> \
  --env REPH_TOKEN=<token> \
  -- node mcp/src/index.js

Mint the token in the app under API tokens (user menu). REPH_WEB_URL (optional) sets the host used in reviewUrl links.

4.3ChatGPT & other MCP clients

The remote endpoint is standard MCP over Streamable HTTP, protected by OAuth 2.1 with dynamic client registration and PKCE (S256). Discovery metadata is at /.well-known/oauth-protected-resource/mcp on the API origin. Any client that supports remote MCP with OAuth should be able to connect using the same URL, https://api.reph.dev/mcp, including ChatGPT's developer-mode connectors and Cursor.

Clients that take a static header instead can send an API token directly as Authorization: Bearer mdo_….

!
We test against claude.ai and Claude Code. Other clients follow the same spec but haven't been verified by us. If one doesn't work, tell us which.

4.4Registered agents & delegation

An agent can be more than a token holder: a teammate with a name, a charter and a track record. A workspace admin registers one in the workspace's Agents panel with a name, a markdown charter, skills, a scope ceiling (read / suggest / edit) and a transport. The transport is either pull (the agent connects over MCP/REST with a token from Mint token) or A2A, for a push-based agent with its own card URL.

Once a document has been shared with the agent (Share → Grant an agent access…), a person can hand it work in two ways:

  • @-mention it in a comment, using the same autocomplete as for teammates. Agents show a bot icon and an "Agent" tag.
  • Delegate to agent… in the doc toolbar: pick the agent, write an instruction, and optionally attach the current selection.

Either one queues an assignment. A pull agent runs this loop:

wait_for_work → whoami → read_doc → work → suggest_edit(s) → return_assignment → repeat

Its result lands as suggestions in the same review queue a person's would. The assignment closes once every listed suggestion has been accepted or rejected.

4.5The review loop

Think of it as a pull request for a document: the agent proposes, asks for review, and learns the outcome, and no human's work is overwritten along the way.

  1. suggest_edit or create_doc: propose. Suggestions render inline as tracked changes.
  2. request_review: notifies collaborators and returns a reviewUrl and a cursor. A doc the agent created is private, so pass reviewer (an email or user id) to grant that person access. If the response says recipients: 0, nobody was notified, so fix the sharing before waiting.
  3. wait_for_review with since: cursor. It waits 120s by default, capped per call at 110s on the remote endpoint (so the remote default is effectively 110s) and 600s over stdio. On timeout, call it again with the returned cursor. check_review is the non-blocking version.
  4. Read the outcome: accepted and rejected suggestions, new comments and replies, and the reviewer's Return to agent… message. If you get awaitingReturn: true, the reviewer has acted but not yet sent that message, so keep waiting.
✓
Accepting and rejecting are human-only and audited. An agent can never approve its own suggestion.

4.6Etiquette

  • Prefer suggest_edit over edit_doc on shared documents. Suggestions are tracked changes a human accepts or rejects; direct edits are not.
  • Always set note on a suggestion, so the reviewer sees your reasoning.
  • Read the outline first. read_outline is much cheaper than a full read, and gives you exact heading text for replace_section / insert_after_heading.
  • Answer in the doc. Reply with reply_to_comment / reply_to_suggestion so the conversation stays next to the text.
  • On an assignment, call start_assignment before you begin and return_assignment or decline_assignment when you finish.
Part 5 · Developer platform

The API underneath

Everything the MCP tools do, as plain HTTPS.

5.1Authentication & scopes

Every API request needs Authorization: Bearer <token>. Someone mints a token in the app (user menu → API tokens) with a scope. A workspace admin can also mint an agent-bound token from the Agents panel, clamped to that agent's ceiling. Both look like mdo_…. A connector's OAuth access token is the same kind of token. Local development instances also accept tokens shaped dev:<user-id>:<display-name>.

Scopes form a ladder, and a token can never go above its scope:

ScopeCan do
readRead and search documents, outlines, versions and review state
suggestEverything read can, plus create suggestions, comments and replies, create docs, and request review
editEverything, including direct edits to existing docs
⚑
A suggest token that tries a direct edit gets a 403 (insufficient_scope), and the attempt is logged in the audit trail. Tokens can reach only the document surface: agents can't mint tokens, accept or reject suggestions, or reach workspace, member or billing routes.

5.2REST API

The base is your instance's API origin, which is a different origin from the web app (for example https://api.reph.example next to https://reph.example; locally, http://localhost:1235). The current surface is /api/v1. The unversioned /api/… paths still work and carry Deprecation headers. The full contract is published as OpenAPI:

  • GET /api/openapi.json: the machine-readable spec, public with no token.
  • GET /api/reference: the same spec rendered for people.
Method & pathPurpose
GET /api/v1/docsList accessible documents, most recently edited first (cursor-paginated)
POST /api/v1/docsCreate a document · {"title","content"}
GET /api/v1/search?q=Search titles and content
GET /api/v1/docs/{id}/contentRead a doc (Accept: text/markdown); returns an ETag
PATCH /api/v1/docs/{id}/contentApply edit ops immediately (needs edit) · {"ops":[…]} + If-Match
POST /api/v1/docs/{id}/suggestPropose edits for review · {"ops":[…],"note":"why"}
POST /api/v1/docs/{id}/commentsComment · {"text":"…","quote":"exact anchor"}
GET /api/v1/docs/{id}/versionsVersion history
POST /api/v1/docs/{id}/review/requestRequest human review; returns reviewUrl
GET /api/v1/docs/{id}/reviewReview state since a cursor (non-blocking)
GET /api/v1/docs/{id}/review/waitLong-poll until the review moves
GET /api/v1/agent/assignments/waitA registered agent's long-poll for work
i
On /api/v1, content writes require If-Match with the ETag from your last read. A write that would overwrite a change made in between is refused, and a write with no If-Match gets 428. POST requests also accept an Idempotency-Key header, so retries are safe.

5.3Edit ops

The same grammar is used by PATCH …/content, POST …/suggest, edit_doc and suggest_edit:

{"op": "replace_all",          "content": "…"}
{"op": "str_replace",          "old": "occurs exactly once", "new": "…"}
{"op": "append",               "content": "…"}
{"op": "replace_section",      "heading": "exact heading text",  "content": "…"}
{"op": "insert_after_heading", "heading": "…",                   "content": "…"}

5.4MCP transports

AspectStreamable HTTP (remote)stdio
WherePOST <API origin>/mcpnode mcp/src/index.js from the repo
AuthOAuth 2.1 (DCR + PKCE) or a bearer API tokenREPH_TOKEN env var
StateStateless: each request builds a fresh serverOne local process per client
Max wait_for_review110s per call600s per call
Best forclaude.ai, Claude Code, hosted clientsLocal agents and self-hosted development

Both serve the same tool registry, so the tool list above is identical on either transport.

5.5Integrations

Git import

Import markdown from a git repository (URL, branch, subdirectory) and refresh it later. Conflicts become suggestions rather than overwrites. See Maintain living docs. A workspace can store a git credential so members don't paste tokens.

A2A

reph speaks A2A (JSON-RPC 2.0 over HTTPS) in both directions.

  • Outbound. A registered agent with transport: a2a receives instructions through message/send and never holds a reph credential. Only the artifacts it returns come back, as ordinary suggestions.
  • Inbound. GET /api/a2a/agents/{id}/card and POST /api/a2a/agents/{id}/rpc with an a2a_… key (message/send, tasks/get, tasks/cancel), for workspaces that opt in. message/send requires params.metadata.docId.