# Plumia Agent Instructions

Plumia is a collaborative markdown editor. Agents can publish documents
with no account, no API key, and no sign-up required.

---

## Quick start

**One-line prompt** (same for every agent):

> Publish my <topic> to https://plumia.ai/new

**Then pick the path that matches the agent:**

1. **HTTP POST** (Cursor, Claude Code, Copilot, any agent with POST) — `POST https://api.plumia.ai/new` with header `Content-Type: application/json` and body `{"title":"<short title>","markdownContent":"<full markdown>"}`. Reply with `data.url` from the JSON. Legacy alias: `POST https://api.plumia.ai/api/agent-docs` (same body, same response).
2. **Browse-only** (ChatGPT browsing, Claude web, etc.) — emit a **clickable** markdown link: `https://api.plumia.ai/new?title=` + encodeURIComponent(title) + `&md=` + encodeURIComponent(markdown). The user clicks once; the browser creates the doc and lands on the viewer. Max ~8KB URL total; for larger docs use POST.
3. **ChatGPT zero-click** — one-time: create a Custom GPT, import Actions from `https://api.plumia.ai/openapi-agent-docs.json`, operation `createAgentDocument` (POST /new). Step-by-step: see **docs/custom-gpt-setup.md** in the Plumia repo, or the **Try in ChatGPT** link on https://plumia.ai.
4. **Discovery** — `GET https://api.plumia.ai/new` (no query) returns a short micro-spec (markdown, or JSON if `Accept: application/json`).

**Full playbook fetch:**

> Fetch https://plumia.ai/agents.md and follow the instructions to publish a document.

---

## OpenAPI (ChatGPT Custom GPT Actions, codegen)

Public machine-readable schema (no auth):

`https://api.plumia.ai/openapi-agent-docs.json`

In ChatGPT: create a Custom GPT → **Configure** → **Actions** → **Import from URL**. Canonical operation: `createAgentDocument` → **POST /new** on `https://api.plumia.ai`.

---

## 1. Create a document (canonical)

POST https://api.plumia.ai/new
Content-Type: application/json

```json
{
  "title": "My Document",
  "markdownContent": "# Hello\n\nYour content here."
}
```

Response:

```json
{
  "data": {
    "token": "abc123...",
    "url": "https://app.plumia.ai/p/abc123...",
    "documentId": "uuid",
    "title": "My Document",
    "expiresAt": "2026-05-05T00:00:00.000Z"
  }
}
```

Save the `token` — it is your write secret. The `url` is public and shareable.
Documents expire 7 days after creation.

**Legacy alias:** same request to `POST https://api.plumia.ai/api/agent-docs`.

---

## 2. Update your document

PATCH https://api.plumia.ai/api/agent-docs/{token}
Content-Type: application/json

```json
{
  "title": "Updated Title",
  "markdownContent": "# Updated\n\nNew content."
}
```

---

## 3. Read your document

GET https://api.plumia.ai/api/agent-docs/{token}

---

## 4. Add a comment

POST https://api.plumia.ai/api/agent-docs/{token}/comments
Content-Type: application/json

```json
{
  "guestName": "Claude",
  "body": "Here is my analysis of the document..."
}
```

Both `guestName` and `body` are plain strings. `guestName` is optional (defaults to "Agent").

---

## 5. List comments

GET https://api.plumia.ai/api/agent-docs/{token}/comments

---

## Sharing

The `url` returned on creation is publicly readable. Anyone with the link can:
- View the rendered document
- Leave anonymous comments

Authenticated Plumia users can clone the document to their workspace for
full editing, version history, and real-time collaboration.

---

## Rate limits

| Action  | Limit                     |
|---------|---------------------------|
| Create  | 10 per IP per hour        |
| Update  | 60 per token per hour     |
| Comment | 30 per IP per hour        |

---

## Need more power? Use the full MCP server

Sign in at https://app.plumia.ai to generate a personal API key, then connect to the hosted
MCP server for 24 tools covering documents, comments, version history, sharing,
and trash management.

### Option A — Hosted (no local install)

Add this to your Cursor / Claude Desktop config:

```json
{
  "mcpServers": {
    "plumia": {
      "url": "https://mcp.plumia.ai/mcp",
      "headers": {
        "Authorization": "Bearer mk_YOUR_API_KEY"
      }
    }
  }
}
```

### Option B — Local (npx)

```json
{
  "mcpServers": {
    "plumia": {
      "command": "npx",
      "args": ["-y", "@markcollab/mcp-server"],
      "env": {
        "MARKCOLLAB_API_KEY": "mk_YOUR_API_KEY"
      }
    }
  }
}
```

Generate your API key at https://app.plumia.ai → Settings → API Keys.