# Marigold Draft — agent setup

You are an AI coding agent setting up Marigold Draft for your user. Marigold
Draft is a local review loop for rich HTML/SVG drafts: you write a file, it
opens in the user's browser inside a comment shell, the user highlights text,
pins comments, and edits in place, then clicks **Send feedback to agent** —
and the feedback flows back to you as JSON so you can revise. The tab
live-reloads on every save and comments re-anchor across revisions. Everything
runs on the user's machine: no cloud, no account, no telemetry.

## Install (do this now)

```sh
npm i -g marigold-draft
marigold-draft agent-setup
```

`agent-setup` wires up this machine's AI tooling: it installs a Claude Code
skill (so "spin up marigold draft" works in chat), registers the MCP server in
Claude Desktop's config if present, and prints an AGENTS.md snippet for other
agents. It is idempotent — re-run it after upgrades.

Then verify: `marigold-draft open` on any HTML file should print a localhost
URL and open a browser tab with a 🌼 comment sidebar.

## Setting yourself up (per assistant)

`agent-setup` fully wires **Claude Code** (installs the skill) and **Claude
Desktop** (registers the MCP server). For any other assistant there are two
paths — pick whichever your harness makes easier; both drive the identical loop:

- **CLI (simplest — works for any agent that can run shell commands).** The
  `marigold-draft` command *is* the whole interface; there is nothing else to
  register. Just add the [AGENTS.md snippet](#agentsmd-snippet-cli-agents) below
  so you know the loop, then run the commands. Codex, opencode, Cursor, Aider,
  and anything else with a shell can use this path with zero MCP config.
- **MCP.** Register `marigold-draft mcp` (a stdio MCP server) so the loop shows
  up as structured tools (`create_draft`, `get_feedback`, `reply_to_comment`,
  …). Use this for chat clients that can't run a shell, or if you simply prefer
  tools over shell calls. The command to spawn is `marigold-draft` with a single
  argument, `mcp`.

> If your assistant is a GUI app (Antigravity, Claude Desktop, …) it may not
> inherit your shell's `PATH`, so a bare `marigold-draft` can fail to launch.
> If it does, replace `marigold-draft` with its absolute path — run
> `which marigold-draft` (e.g. `/opt/homebrew/bin/marigold-draft` or
> `~/.npm-global/bin/marigold-draft`) and use that in `command`.

### Codex CLI

Codex speaks MCP over stdio and reads `AGENTS.md`, so either path works.

MCP — add to `~/.codex/config.toml` (or project-scoped `.codex/config.toml`):

```toml
[mcp_servers.marigold-draft]
command = "marigold-draft"
args = ["mcp"]
```

or the equivalent one-liner: `codex mcp add marigold-draft -- marigold-draft mcp`.

CLI path — drop the [AGENTS.md snippet](#agentsmd-snippet-cli-agents) into your
project's `AGENTS.md` (Codex reads it automatically) and use the `marigold-draft`
CLI directly.

### opencode

opencode reads `AGENTS.md` and registers local MCP servers in `opencode.json`
(project root, or global `~/.config/opencode/opencode.json`):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "marigold-draft": {
      "type": "local",
      "command": ["marigold-draft", "mcp"],
      "enabled": true
    }
  }
}
```

The CLI path works too — opencode can run shell commands, so the
[AGENTS.md snippet](#agentsmd-snippet-cli-agents) plus the `marigold-draft` CLI
is all you need.

### Google Antigravity

Antigravity is a GUI IDE. Open **Settings → Customizations → Open MCP Config**
(this edits `~/.gemini/config/mcp_config.json`) and add a local server:

```json
{
  "mcpServers": {
    "marigold-draft": {
      "command": "marigold-draft",
      "args": ["mcp"]
    }
  }
}
```

Then refresh the "Installed MCP Servers" panel. If the server fails to start,
it's almost certainly `PATH` — swap `marigold-draft` for the absolute path from
`which marigold-draft` (see the note above). Antigravity also reads workspace
rules (`AGENTS.md`, `.agents/rules/*.md`), so you can add the
[AGENTS.md snippet](#agentsmd-snippet-cli-agents) there as well.

### Any other MCP client

`marigold-draft mcp` is a standard stdio MCP server — any MCP-capable client can
spawn it. The generic shape (command + args) is what every client above uses:

```json
{ "command": "marigold-draft", "args": ["mcp"] }
```

If your assistant can run shell commands but you don't want to touch its MCP
config, skip MCP entirely: the `marigold-draft` CLI is self-contained.

### AGENTS.md snippet (CLI agents)

Paste this into your project's `AGENTS.md` / `CLAUDE.md` (or your assistant's
global rules file) so it knows the loop and drives the CLI directly:

```md
## Marigold Draft (local review loop)

When asked to "spin up marigold draft" (or for a local commentable draft):
1. Run `marigold-draft principles [mode]` and follow it to write a
   self-contained HTML file (inline all CSS/JS/SVG; external network is blocked
   by CSP).
2. Run `marigold-draft open <file> --json --timeout 570` in the background — it
   opens the browser, blocks until the user clicks "Send feedback to agent",
   prints the feedback JSON, and exits (exit code 2 = timed out; re-arm it).
3. Revise the file with targeted edits (the tab live-reloads and comments
   re-anchor), then `marigold-draft reply <file> <id> "<what changed>"` and
   `marigold-draft resolve <file> <id>`.
4. To share or keep a draft: `marigold-draft share <file>` posts it to hosted
   Marigold and prints a share link (anyone with it can view + comment) plus a
   claim link (sign in to keep it and control access).
Never run `marigold-draft serve` or `stop` yourself — one shared daemon backs
every draft. `marigold-draft help` lists every command.
```

## Stay connected (preferred, when your harness supports it)

If your agent harness has a persistent background monitor primitive, start one
listener at the beginning of a review session and leave it running:

```sh
marigold-draft listen
```

One stream covers every draft: each user "Send feedback to agent" prints one
JSON review round on stdout and wakes you instantly. It reconnects forever,
restarts the daemon if needed, catches up rounds submitted while nothing was
listening, and keeps the tab's "● Agent connected" indicator truthful. With a
listener running, open drafts with `open --no-wait` and skip the blocking
waits below.

## The review loop (how you work with it)

1. **Author a draft.** Write a self-contained HTML file — a full document, or
   a fragment/SVG (those get a neutral wrapper). A strict CSP blocks external
   scripts, fonts, and images, so inline everything; embed images as `data:`
   URIs. The file path is the doc's identity — keep drafts the user will
   iterate on somewhere stable (`~/.marigold-local/drafts/` works well).

2. **Open and block for feedback.** Run in the background so its exit resumes
   you the moment the user submits:

   ```sh
   marigold-draft open /abs/path/draft.html --json --timeout 570
   ```

   With `--json`, stdout is the review payload: `openComments[]` — each with
   `id`, `body`, `anchoredText` (the element text the comment is pinned to)
   and `replies` — plus an optional `overallComment`. Status and the URL go to
   stderr. Exit code 2 means the wait timed out; re-run the same command to
   keep waiting.

3. **Revise the file.** Prefer targeted edits over full rewrites — unchanged
   DOM structure is what lets the user's comments re-anchor. The open tab
   live-reloads on save.

4. **Close the loop per comment**, then wait for the next round:

   ```sh
   marigold-draft reply /abs/path/draft.html c3 "Made September green"
   marigold-draft resolve /abs/path/draft.html c3
   marigold-draft open /abs/path/draft.html --json --no-browser --timeout 570
   ```

   Use `--no-browser` on later rounds — the user's tab is already connected.

5. **Stop** when the user says they're done, or a round arrives with no open
   comments and no overall comment (that's a sign-off).

## Rules

- Never run `marigold-draft serve` yourself, and never `stop` the daemon as
  cleanup — one warm background daemon (port 4747) is shared by all drafts,
  and open tabs go dark while it's down (they self-heal when it returns).
- Comments are durable: they live in `<file>.marigold.json` next to the draft
  and survive daemon restarts. Never delete the sidecar.
- `marigold-draft comments <file> --json` reads current threads without
  blocking.

## MCP tools (reference)

Once `marigold-draft mcp` is registered (see [per-assistant setup](#setting-yourself-up-per-assistant)),
the loop shows up as these tools: `start_analysis` (load the Marigold Way before
authoring), `create_draft` (HTML in → file written → browser opens),
`open_draft`, `update_draft`, `get_feedback` (pass `waitSeconds` to block for
the user's review), `reply_to_comment`, `resolve_comment`, `read_draft`.
`agent-setup` registers the server in Claude Desktop automatically; every other
client uses the `{ "command": "marigold-draft", "args": ["mcp"] }` shape above.

## Going beyond local

The same HTML publishes unchanged to cloud Marigold — shareable, commentable
docs with the identical anchoring engine — through the Marigold MCP connector
(`https://marigold.page/api/mcp`). Draft locally, publish
when it's ready to share.