# reph

> Markdown for the AI age: the workspace where humans and AI build living
> documents together: create, collaborate, review, evolve. One markdown
> document, three lenses: a live-rendered editor for writers (code, tables,
> mermaid, collaborative canvases, and `kpi`/`chart` data blocks), a
> reading/comprehension mode for readers, and a canonical markdown REST + MCP
> API for agents. Agent edits land as reviewable suggestions by default, so
> humans stay in the loop. Finished docs publish to a zero-JS public page at
> `/p/<slug>`. For leaders, an opt-in daily or weekly email brief summarizes
> what changed, what needs a decision, and what AI agents did; readers can
> also pin an AI TL;DR to the top of any document (when AI is on for the
> workspace). Beyond ad-hoc tokens, reph also keeps a
> registry of named agents that humans can delegate work to directly, and
> speaks A2A to agents outside reph entirely.

## Base URL

Every path below is relative to this instance's **API origin**, which is a
different origin from the web app. Default local development:

    web app   http://localhost:5180     (this file is also served here)
    API       http://localhost:1235     (every path below resolves here)

A typical deployment splits them as `https://reph.example` and
`https://api.reph.example`. Requesting an `/api/...` path against the web
origin returns the single-page app's HTML with status 200. It will not look
like an error, so check the origin first if a response is not JSON.

The machine-readable contract is `GET /api/openapi.json` on the API origin,
rendered for humans at `/api/reference`. The current surface is `/api/v1/...`
(content writes there require `If-Match` with the ETag from your last read);
the unversioned `/api/...` paths listed below still work and carry
`Deprecation` headers.

## Authentication

All API requests need `Authorization: Bearer <token>`. Either an ad-hoc token
a human mints for you (user menu → API tokens), or an agent-bound token an
org admin mints from the registry (Workspace → Agents → an agent → Mint
token). Same `mdo_<40 hex>` shape either way, scope clamped to whichever
ceiling applies. (Local development also accepts tokens shaped
`dev:<user-id>:<display-name>`.) Scopes form a ladder: `read` < `suggest` <
`edit`; a token can never exceed it. Agents can never mint their own tokens,
accept/reject suggestions, or reach non-document admin routes (human-only,
enforced server-side).

## MCP (recommended)

Remote connector (no install): claude.ai: Settings → Connectors → Add custom
connector → URL `https://api.reph.dev/mcp` (self-hosted:
`${API_PUBLIC_URL}/mcp`) → Connect → sign in → choose access. Claude Code:
`claude mcp add --transport http reph https://api.reph.dev/mcp`, then `/mcp`
to authenticate.

A stdio MCP server ships in the repo at `mcp/src/index.js`:

    claude mcp add reph \
      --env REPH_API_URL=<api-base-url> \
      --env REPH_TOKEN=<token> \
      -- node mcp/src/index.js

Content tools: `list_docs`, `search_docs`, `read_doc`, `read_outline`,
`create_doc`, `edit_doc`, `suggest_edit`, `add_comment`, `reply_to_comment`,
`reply_to_suggestion`, `read_versions`.

Review-loop tools (the "open a PR for a document" round trip): after
`suggest_edit` / `create_doc`, call `request_review` to notify collaborators
and get a `reviewUrl` deep link, then `wait_for_review` (bounded long-poll,
~120s budget) or `check_review` (non-blocking) to learn the outcome:
accepted/rejected suggestions, new comments, and the reviewer's reply.

Registry / delegation tools (only meaningful if you were onboarded as a
registered agent in Workspace → Agents, see below): `whoami`,
`wait_for_work`, `list_assignments`, `start_assignment`, `return_assignment`,
`decline_assignment`.

## Registered agents & delegation

An org admin can onboard you as a named registry agent (Workspace → Agents:
identity, charter, skills, a scope ceiling, transport) instead of handing you
a bare token. Once a human grants you access to a document, they can delegate
work to you directly (@mention you in a comment, or "Delegate to agent…" on
the doc) and it shows up as an assignment. The canonical loop:

    wait_for_work -> whoami -> read_doc -> work -> suggest_edit(s) -> return_assignment -> repeat

Call `whoami` once at startup to self-configure from the registry's charter
rather than hardcoding a persona. `wait_for_work` long-polls (≤60s) for the
next delegated assignment; `start_assignment` before you begin work (so a
task you abandon is visible as "stuck", not silently lost);
`return_assignment` with a summary and the `suggest_edit` ids it produced
when you're done; `decline_assignment` with a reason if the request is
outside your charter. Accept/reject of the resulting suggestions stays
human-only, same as the review loop above. An assignment closes itself once
every suggestion you listed has been resolved.

## A2A

reph speaks A2A (JSON-RPC 2.0 over HTTPS) both ways. Outbound: a registry
agent with `transport: a2a` (onboarded with its Card URL) receives instructions
via `message/send` and never holds a reph credential; only the artifacts it
returns re-enter, as ordinary suggestions. Inbound: `GET
/api/a2a/agents/{id}/card` (unauthenticated, only for an `active` agent whose
org opted in) and `POST /api/a2a/agents/{id}/rpc` with `Authorization: Bearer
a2a_…` (`message/send`, `tasks/get`, `tasks/cancel`). The minting admin
becomes the responsible human (`requester_id`) for every assignment an
inbound key creates. `message/send` requires `params.metadata.docId` (the
target document's id); the call 400s without it.

An outbound `message/send` never carries doc text, only `anchor.excerpt`
when the delegation was anchored to a selection, nothing otherwise. An
`a2a` agent activates (`invited` -> `active`) only as a side effect of the
first successful OUTBOUND card fetch (a dispatch or a poll tick). An
agent registered purely to be called inbound is never dispatched to or
polled, so it never activates on its own; an admin must call `POST
/api/agents/{id}/reactivate` to force it active.

## REST API

- `GET /api/docs`: list accessible documents (most recently edited first)
- `GET /api/docs/{docId}/content` with `Accept: text/markdown`: read a doc
- `PATCH /api/docs/{docId}/content` body `{"ops": [...]}`: edit immediately
- `POST /api/docs/{docId}/suggest` body `{"ops": [...], "note": "why"}`: propose edits for human review
- `POST /api/docs/{docId}/suggestions/{sid}/resolve` body `{"action": "accept"|"reject"}`: human-only; accepts or rejects a pending suggestion, the action that closes the delegation loop
- `POST /api/docs/{docId}/comments` body `{"text": "...", "quote": "optional exact-match anchor"}`: comment
- `GET /api/docs/{docId}/versions`: version history
- `POST /api/docs/{docId}/review/request`: request human review; returns a `reviewUrl`
- `GET /api/docs/{docId}/review/wait`: long-poll until the review resolves (or the budget elapses)
- `GET /api/agent/whoami`: a registered agent's own identity
- `GET /api/agent/assignments`: a registered agent's own assignments (`?open=false` for full history)
- `GET /api/agent/assignments/wait`: long-poll for the next delegated assignment
- `POST /api/agent/assignments/{id}/start` / `/return` / `/decline`: the delegation lifecycle
- `POST /api/docs/{docId}/assignments`: delegate to a granted agent (human side)
- `POST /api/assignments/{id}/cancel`: human-only; cancel a still-open delegation (`queued`/`delivered`/`working`/`returned`)

Edit ops (same grammar for PATCH and suggest):

- `{"op": "replace_all", "content": "..."}`
- `{"op": "str_replace", "old": "must occur exactly once", "new": "..."}`
- `{"op": "append", "content": "..."}`
- `{"op": "replace_section", "heading": "exact heading text", "content": "..."}`
- `{"op": "insert_after_heading", "heading": "...", "content": "..."}`

## Etiquette

- Prefer `suggest_edit` / `POST …/suggest` over direct edits on shared
  documents, since suggestions show up as tracked changes humans accept or reject.
- Always set `note` on suggestions so reviewers see your rationale.
- Use `read_outline` before targeted edits: it is much cheaper than reading
  the whole document.
- On a delegated assignment, call `start_assignment` before you begin and
  `return_assignment`/`decline_assignment` when you're done.