# easymarkdown

> easymarkdown (https://easymarkdown.io) keeps Markdown documents in projects and folders, each with a status (draft, review, approved, done, archived) and a full revision history. Subscribers get a REST API (/api/v1, Bearer keys from Settings -> API keys) and the `emd` CLI. Agents use it to keep the main plan for a piece of work where the user can review it.

## How agents should use it

- Store only the main plan for a piece of work: the one the user approves or acts on, and needs again later. Save it when the user asks, or offer once right after they approve it.
- Save a new revision only when the plan is approved or materially changes. Never after each step, on a timer or in a loop. Update the existing document instead of creating "Plan v2".
- Never use it as a scratchpad: no notes, research dumps, drafts, todo or progress logs, command output, code, or secrets.
- One project (a top-level folder) per repository, named after the repo. Plans go directly in it. Add subfolders by area only once a project holds more than about 8 plans, one level deep. Never a folder per document, date, session or run. Reuse existing folders.
- Statuses: draft while shaping, review when waiting for the user, approved only when they say so, done when the work has shipped.
- Send `updated_at` from your last read when updating, so browser edits are never overwritten (409 means re-read and merge). Reply with the document's link (`url`).
- Limits: 60 requests a minute per key (on 429 wait `Retry-After`, never loop), 512 KB per document, 10,000 documents and 500 MB per account.

## Docs

- [API reference](https://easymarkdown.io/docs/api): endpoints, errors, limits, examples
- [OpenAPI 3.1 spec](https://easymarkdown.io/docs/api/openapi.json)
- [emd CLI](https://github.com/imgerson/emd): `brew install imgerson/emd/emd`
- [Agent skill (SKILL.md)](https://github.com/imgerson/emd/blob/main/plugins/emd/skills/easymarkdown-plans/SKILL.md): Claude Code: `/plugin install emd --marketplace imgerson/emd`; or `emd skill install`