---
name: dock-editor
description: >
  Agent-native document workspace for AgentDock Dock Editor.
  Use when: creating, editing, citing, or publishing documents programmatically.
  Triggers: document creation, writing, academic writing, research paper, citations,
  DOI lookup, PMID, arXiv, publishing, track changes, suggest edits, version history,
  folders, prompt library, bibliography, references, write a paper, add sources.
---

# Dock Editor — Agent Skill

Create, edit, cite, and publish documents through three access layers:
MCP (38 tools), CLI (46 commands), REST API (36 HTTP handlers across 26 route files).

Docs: https://agentdock.ai/docs/dock-agent-api

## Authentication

Tokens are created at `app.agentdock.ai/account/api-tokens`.

| Prefix | Scope | Use when |
|--------|-------|----------|
| `ak_usr_` | All documents | Agent needs full workspace access |
| `ak_doc_` | One document | Sharing a specific document |
| `ak_org_` | Organization | CI/CD and team automation |

Note: Document-scoped tokens (`ak_doc_`) cannot create new documents.

## Before You Start

Execute operations directly. Do not present tool calls as suggestions for the user to run manually.

Verify your token works by calling `list_documents`. If it returns 401, create a token at `app.agentdock.ai/account/api-tokens`.

Assess the workspace state before acting:

- Does the user want autonomous writing? → **Direct Write** mode
- Does the user want to review before changes apply? → **Suggest** mode
- Is this a new document or editing an existing one?
- Does the document need citations? Search first, then write with `{{cite: doi=...}}` inline
- Is the document shared with others? Prefer **Suggest** mode (safer)

## Document Lifecycle

```
create → write → cite → publish
                    ↘ suggest (track changes for human review)
```

1. **Create** — new blank document or import from URL
2. **Write** — send markdown, server converts to TipTap JSON, version snapshot auto-created
3. **Cite** — add citations by DOI, PMID, arXiv ID, or URL. 7 styles (APA, MLA, Chicago, Harvard, IEEE, AMA, Vancouver). Use `{{cite: doi=...}}` inline in your markdown.
4. **Publish** — document goes live at `/p/{slug}` with SEO metadata. The document must have a non-empty title first (write `# Title` as the opening line, or set it explicitly); publishing an untitled document is rejected with "Add a title before publishing."

## Two Writing Modes

**Direct Write** — agent writes content, version snapshot created automatically. User sees the result.

**Suggest** — agent proposes a specific text change (find/replace). Server computes diff, stores as pending suggestion. Document owner reviews in the editor and accepts or rejects. Use this when the agent should NOT directly modify content.

For details, see `references/writing-modes.md`.

## Title Convention

Title is metadata, stored separately from body content.
The server handles the boundary automatically:

- **Read**: Returns `# {title}\n\n{body}` — title is always the first H1
- **Write**: If your markdown starts with `# Title`, the server extracts it as the document title and stores the rest as body
- **Round-trip**: read → edit → write back produces no duplicates

## Agent Workflow: Write a Research Paper

```
1. search_citations(query: "climate change crop yields")
   → [{ doi: "10.1038/...", title: "Global Crop Yields" }]

2. create_document(title: "Impact Analysis")
   → { id: "abc-123" }

3. write_document(id: "abc-123", content: "# Impact Analysis\n\n
   Crop yields declined by 6% {{cite: doi=10.1038/s41586-024-1234}}.")
   → server extracts "Impact Analysis" as title, body starts after

4. publish_document(id: "abc-123", slug: "impact-analysis")
   → { url: "https://agentdock.ai/p/impact-analysis" }
```

## Agent Workflow: Edit an Existing Document

```
1. read_document(id: "abc-123")
   → "# Impact Analysis\n\nCrop yields declined by 6%..."

2. Option A — Direct Write:
   write_document(id: "abc-123", content: "# Impact Analysis\n\nupdated body...")

3. Option B — Suggest:
   suggest_edits(id: "abc-123", find: "old text", replace: "new text")
   → owner reviews in editor
```

## Interface Routing

MCP, CLI, and REST are three clients over **one shared service layer**, so the
same operation behaves identically on all of them: same validation, same errors
(the publish title gate, scope checks), and the same document, node, and version
ids. Use whichever interface fits your runtime, at full capacity. The only
differences are client conveniences (CLI adds `login`/`config`/`whoami`; MCP adds
protocol calls like `tools/list`), never document capability.

Use whichever interface fits your runtime:

| Intent | MCP Tool | CLI Command | REST |
|--------|----------|-------------|------|
| List documents | `list_documents` | `agentdock docs list` | `GET /api/d` |
| Read document | `read_document` | `agentdock docs read <id>` | `GET /api/d/<id>` |
| Write content | `write_document` | `agentdock docs write <id> <file>` | `PATCH /api/d/<id>` |
| Create document | `create_document` | `agentdock docs create` | `POST /api/d` |
| Delete document | `delete_document` | `agentdock docs delete <id>` | `DELETE /api/d/<id>` |
| Import from URL | `import_web_page` | `agentdock docs import-url <url>` | `POST /api/d/import-url` |
| Duplicate | `duplicate_document` | `agentdock docs duplicate <id>` | `POST /api/d/<id>/duplicate` |
| Suggest edit | `suggest_edits` | `agentdock docs suggest <id> <find> <replace>` | `PATCH /api/d/<id>` (mode=suggest_replace) |
| Add citation | `add_citation` | `agentdock docs cite <id> <identifier>` | `POST /api/d/<id>/cite` |
| Publish | `publish_document` | `agentdock docs publish <id>` | `POST /api/d/<id>/publish` |
| Unpublish | `unpublish_document` | `agentdock docs unpublish <id>` | `DELETE /api/d/<id>/publish` |
| List versions | `list_versions` | `agentdock docs versions <id>` | `GET /api/d/<id>/versions` |
| List folders | `list_folders` | `agentdock docs folders list` | `GET /api/d/folders` |

Full catalogs: `references/mcp-tools.md`, `references/cli-commands.md`, `references/rest-api.md`.

## URL Patterns

After creating or writing a document, share these URLs with the human:

| URL | Domain | When to share |
|-----|--------|---------------|
| `https://app.agentdock.ai/editor/{id}` | Dashboard | Always — after create, write, duplicate |
| `https://agentdock.ai/p/{slug}` | Marketing | Only when document is published |

API responses include `url` (editor) and `publishedUrl` (published page) fields.
CLI prints them automatically. After unpublishing, `publishedUrl` becomes null.

## Content Format

Send content as **markdown** (default). The server converts to TipTap JSON.
Tables use GFM syntax. Math uses `$...$` inline, `$$...$$` block.
Inline citations: `{{cite: doi=10.1038/...}}` resolved by the server automatically.

## Errors and Rate Limits

- MCP: errors return `isError: true` in content array
- REST: 4xx/5xx HTTP status codes with `{ error: "message" }`
- CLI: non-zero exit code with error message to stderr
- Rate limits: read 120/min, write 60/min

## References

Full interface catalogs (loaded on demand):

- `references/mcp-tools.md` — all 38 MCP tools with parameters
- `references/cli-commands.md`: all 46 CLI commands with syntax
- `references/rest-api.md`: all 36 REST handlers across 26 route files
- `references/citations.md` — citation system, 7 styles, DOI/PMID/arXiv resolution
- `references/writing-modes.md` — direct write vs suggest, conflict rules, provenance