Coview agent instructions

Coview is an agent-human collaboration canvas. Use high-level tools to read, write, inspect, and screenshot canvas documents. Do not send raw operation batches through the agent or MCP APIs.
Agents: use the Coview Agent API. Do not write directly to document sync endpoints.

Fast flow:

1. Use the document id from the URL. In https://coview.dev/d/my-document-id, use documentId "my-document-id". For write_html, you can pass documentUrl directly.
2. Call get_basic_info, use get_tree_summary to choose targets, then inspect specific nodes with get_node.
3. Create or replace full sections quickly with write_html.
4. Refine with update_styles, set_text_content, rename_nodes, duplicate_nodes, move_nodes, or delete_nodes.
5. Call get_screenshot to check layout, clipping, contrast, and spacing. It defaults to fast SVG rendering without Browser Rendering.

For creating or replacing a presentation, use write_html with full HTML frames. Send multiple 1280x720 section elements and pass targetNodeId "root" when replacing the canvas directly. Use mode "insert-children" to append top-level objects to root or append inside an existing frame/flex-frame.

Layout guidance:

- Coview supports frame, flex-frame, rectangle, text, and image nodes.
- Prefer flex-frame or normal document flow for padded groups, cards, rows, columns, navs, and repeated content. Use display:flex, flex-direction, gap, padding, align-items, and justify-content for those layouts.
- Use position:absolute only when an element must be placed on the artboard independently. Absolute left/top/right/bottom values are measured from the positioned parent's outer box, not from the parent's padding/content box.
- Do not expect parent padding to automatically offset absolute children. If a parent has padding:78px and a child has position:absolute; left:0; top:0, the child starts at the parent's outer corner. Use normal/flex flow inside the padded parent, or include the padding in the absolute coordinates yourself.
- Background layers can use position:absolute; inset:0 because they intentionally cover the whole parent.

Agent access options:

1. Direct agent API: https://coview.dev/api/agents
2. Remote MCP server: https://coview.dev/mcp

Direct agent API:

Use POST https://coview.dev/api/agents/{method} with a JSON body matching the method input schema. Read the full method catalog at /agent-api.txt or GET https://coview.dev/api/agents.
For a generic presentation example, call GET https://coview.dev/api/agents/examples/presentation.

High-level direct agent API method URLs:

- POST https://coview.dev/api/agents/get_guide
- POST https://coview.dev/api/agents/get_basic_info
- POST https://coview.dev/api/agents/create_document
- POST https://coview.dev/api/agents/request_access_token
- POST https://coview.dev/api/agents/request_user_validation
- POST https://coview.dev/api/agents/update_document_metadata
- POST https://coview.dev/api/agents/get_selection
- POST https://coview.dev/api/agents/get_node
- POST https://coview.dev/api/agents/get_children
- POST https://coview.dev/api/agents/get_tree_summary
- POST https://coview.dev/api/agents/get_screenshot
- POST https://coview.dev/api/agents/get_jsx
- POST https://coview.dev/api/agents/get_computed_styles
- POST https://coview.dev/api/agents/get_font_family_info
- POST https://coview.dev/api/agents/write_html
- POST https://coview.dev/api/agents/create_artboard
- POST https://coview.dev/api/agents/insert_nodes
- POST https://coview.dev/api/agents/update_styles
- POST https://coview.dev/api/agents/set_text_content
- POST https://coview.dev/api/agents/rename_nodes
- POST https://coview.dev/api/agents/duplicate_nodes
- POST https://coview.dev/api/agents/move_nodes
- POST https://coview.dev/api/agents/delete_nodes

move_nodes moves, reparents, or reorders nodes without resizing them. Use {"x":120,"y":80} for canvas moves, {"parentId":"frame","x":24,"y":32} for parent-local moves, {"parentId":"frame","index":0} for reparent/reorder, or {"beforeNodeId":"headline"} / {"afterNodeId":"body"} for sibling ordering. Use it for layer order, reparent/group, and computed alignment.

Example direct API calls:

curl -s https://coview.dev/api/agents/create_artboard \
  -H "content-type: application/json" \
  -d '{"documentId":"my-document-id","name":"Poster","styles":{"width":390,"height":844,"background":"#ffffff"}}'

curl -s https://coview.dev/api/agents/write_html \
  -H "content-type: application/json" \
  -d '{"documentUrl":"https://coview.dev/d/my-document-id","targetNodeId":"root","html":"<section id=\"slide-one\" style=\"width:1280px;height:720px;background:#f8fafc;color:#0f172a;font-family:Inter,Arial,sans-serif;position:relative\"><h1 style=\"position:absolute;left:72px;top:180px;font-size:64px;line-height:1.05\">Project plan</h1><p style=\"position:absolute;left:76px;top:320px;width:640px;font-size:24px;line-height:1.35\">A clear opening frame.</p></section><section id=\"slide-two\" style=\"width:1280px;height:720px;background:#ffffff;color:#111827;font-family:Inter,Arial,sans-serif;display:flex;flex-direction:column;gap:28px;padding:72px\"><h2 style=\"font-size:52px;line-height:1.08;margin:0\">Agenda</h2><p style=\"font-size:24px;line-height:1.4;margin:0;color:#4b5563\">Context, approach, and next steps.</p></section>"}'

write_html returns inserted node geometry, warnings, and recommendedNextCall for get_screenshot. It defaults to mode "replace", which replaces the selected node or root canvas content when no targetNodeId is passed. Pass targetNodeId "root" to force root canvas replacement even when another node is selected. Replace mode accepts one or more root HTML elements. Use mode "insert-children" to append top-level objects to root or add nodes inside an existing frame/flex-frame. It uses one conversion path and preserves normalized CSS intent: property names become camelCase, authored CSS values stay CSS strings, mixed direct text is preserved in flow order, and data-coview-name sets the Coview layer name. Rendering computes browser-like text flow and intrinsic sizes; write_html does not write inferred text width/height or expand clipped text into node data.

Direct edit calls return the persisted version plus method-specific ids or geometry. They do not repeat the request document id, current selection, or low-level operation summary. Direct get_screenshot returns JSON with image metadata and base64 data, not MCP content blocks.

For private documents, request_access_token creates a short-lived token from an authenticated context. If the agent needs the user to approve access, request_user_validation returns a consent URL and pending bearer token; the token only becomes active after the user approves the consent screen.

curl -s https://coview.dev/api/agents/get_node \
  -H "content-type: application/json" \
  -d '{"documentId":"my-document-id","nodeId":"root"}'

Remote MCP server:

https://coview.dev/mcp

If your runtime supports remote MCP and does not already have callable Coview MCP tools, register or connect this remote MCP server URL before using MCP tools.

- Claude Code: claude mcp add --transport http coview https://coview.dev/mcp
- Generic Streamable HTTP MCP config: add a server named "coview" with url "https://coview.dev/mcp".
- OpenAI Agents SDK: configure a hosted MCP tool with serverLabel "coview" and serverUrl "https://coview.dev/mcp".

The document changes API under https://coview.dev/api/v1/documents/... is for the Coview app runtime. Agents should use the direct agent API or MCP tools above.

Do not infer the document from bundled asset names in index.html. The document is identified by the URL path id and edited through one of the high-level agent access options above.