Agent guide

How to wire an AI agent into Docs — the str_replace edit pattern, llms.txt discovery, the copy-paste prompt, and the save-to-local workflow.

This guide is for people connecting an AI agent (Claude Code, Cursor, a custom tool-using agent — anything that can run curl) to Docs.

The bash str_replace pattern

The core design decision in the Docs edit API: POST /api/docs/:id/edit takes {old_string, new_string, replace_all?} — the exact contract agents already use for local file edits.

Why it matches agent muscle memory

Every major coding agent edits local files through an Edit tool with str_replace semantics: read the file, pick an exact unique substring, replace it. Agents have deep training and habits around this contract — including the recovery behaviors when a match fails. Docs reuses the contract verbatim, so an agent treats a remote shared document exactly like a local file:

# read (like cat -n)
curl 'https://docs.aicomputercompany.com/api/docs/doc_abc123/raw?numbered=1'

# edit (like the Edit tool)
curl -X POST https://docs.aicomputercompany.com/api/docs/doc_abc123/edit \
  -H 'Content-Type: application/json' \
  -H 'x-actor-id: agent_claude_main' -H 'x-actor-name: Claude' \
  -d '{"old_string": "sync every 5 minutes", "new_string": "sync every 30 seconds"}'

The exact error contract

The server mirrors local Edit-tool semantics precisely, so an agent’s existing failure-recovery instincts work unchanged:

old_string must match the document text exactly, including whitespace.

Under the hood the edit is applied to the live CRDT as a minimal diff, so humans editing simultaneously keep their cursors.

llm.txt discovery

An agent with zero context can bootstrap itself from the well-known plain-text manuals:

https://docs.aicomputercompany.com/llm.txt          # orientation
https://docs.aicomputercompany.com/llms-full.txt    # complete manual

Both are served from all three product domains. If you only give your agent one URL, give it llms-full.txt — it contains every endpoint contract with examples. See llms.txt endpoints.

The friendly prompt

For interactive sessions, paste this block to your AI (it’s the same one on the Quickstart):

You can create, review, and edit shared documents on Docs by AI Computer
Company. It is a collaborative markdown editor: humans edit live in the
browser, you work over REST. No API key or signup — knowing a document id
is the permission. Full manual: https://docs.aicomputercompany.com/llms-full.txt

API base: https://docs.aicomputercompany.com/api
On every request, send these headers so your work is attributed:
  x-actor-id: agent_<pick-a-stable-id>
  x-actor-name: <your name>

THE API (mechanics)

1. CREATE:  POST /api/docs   body: {"markdown": "...", "title": "..."}
   → {document: {id}, shareUrl}. Give the shareUrl to the human.
2. READ:    GET /api/docs/<id>/raw?numbered=1   (line numbers, like cat -n —
   always read before editing; humans may have changed it)
3. EDIT:    POST /api/docs/<id>/edit
   body: {"old_string": "exact text", "new_string": "replacement"}
   Exact str_replace semantics, same as your local Edit tool:
   409 not-found → re-read and fix your match; 409 not-unique → add
   surrounding context or pass "replace_all": true. Edits land instantly
   in collaborators' editors, cursors preserved.
4. PUSH:    PUT /api/docs/<id>/markdown  {"markdown": "<entire document>"}
5. CHECKPOINT: POST /api/docs/<id>/checkpoints  {"message": "why"}

THE REVIEW PROCESS (methodology — follow this when given requirements,
specs, plans, or notes)

Step 1 — CONSOLIDATE. Gather all project requirements, context, and loose
information the human has given you and write them into ONE well-structured
document (numbered sections, one requirement per statement). Create it,
share the URL. The document is now the single source of truth.

Step 2 — REVIEW EVERY REQUIREMENT, line by line. Read with ?numbered=1 and
walk the document top to bottom. For each requirement, check the logic:
is it clear, testable, complete? Does it contradict another requirement?
Post ONE bulk review pass so the human gets a single revision:
  POST /api/docs/<id>/annotations/bulk
  {"annotations": [{"anchorText": "<exact text>", "verdict": "...",
                    "body": "your reasoning", "refs": ["a3"]}, ...],
   "message": "AI requirements review"}
Verdicts: "valid" = clear and consistent · "question" = needs follow-up
from the human · "conflict" = contradicts another requirement (link the
counterpart with refs).
Anchoring rules:
- Marking the STATUS of a task/requirement line (confirmed, verified,
  done, blocked): anchor the ENTIRE line, from its first character to its
  last. A status applies to the whole task — partial-line status anchors
  are wrong and read as if only that fragment were confirmed.
- Flagging a specific issue WITHIN a line (an ambiguous phrase, a wrong
  value): anchor just that exact phrase.
- Never use emojis in annotations, comments, or document content unless
  the human asks for them.

Step 3 — SURFACE BLOCKERS AND USER ACTIONS. After the pass, post a
document-level comment (POST /api/docs/<id>/comments, no anchorText)
summarizing: counts per verdict, which conflicts BLOCK progress, and a
short "decisions needed from you" list. Humans should know what to do
without reading every card. Propose concrete fixes as suggestions the
human can accept with one click:
  POST /api/docs/<id>/suggestions
  {"kind": "substitution", "targetText": "old", "text": "new",
   "body": "why this resolves it"}

Step 4 — BUILD THE VIEWS the review deserves. Push side-panel UI so the
human can see the whole picture (POST /api/docs/<id>/views):
  {"kind": "gantt",   "payload": {"unit": "wk", "tasks": [{"id","label",
    "start","duration","owner","dependsOn"}]}}     — timeline from the spec
  {"kind": "digest",  "payload": {"markdown": "TL;DR · decisions · open
    questions · blockers"}}                        — stakeholder brief
  {"kind": "custom",  "payload": {"html": "<!doctype html>..."}}  — ANY
    visualization you or the user invent (self-contained HTML/JS, rendered
    sandboxed; see the manual's CUSTOM VIEWS section for the bridge API).
Build whatever helps: coverage matrices, decision trees, risk heatmaps.

Step 5 — DELEGATE THE WORK. Turn the reviewed requirements into per-task
handoff prompts other agents can execute:
  {"kind": "prompts", "payload": {"cards": [{"id", "title",
    "prompt": "<context + task + acceptance criteria, self-contained>"}]}}
Each card gets copy buttons for Copilot/Cursor/Codex/Claude Code/Gemini.
Include the doc's shareUrl in each prompt so workers can read the source.

Step 6 — CLOSE THE LOOP. Watch GET /api/docs/<id>/view-events?since=0 for
"refresh-requested" (human asked you to regenerate a view) and re-read the
doc before every later edit. When review is settled, export clean copy:
GET /api/docs/<id>/export.md?clean=1 (all review markup stripped).

Save-to-local + push-back

When an agent wants to work on a document with its full local toolchain (multi-file refactors, linters, scripts), pull the doc down, edit locally, and push back:

# 1. pull
curl https://docs.aicomputercompany.com/api/docs/doc_abc123/raw > doc.md

# 2. edit doc.md locally with any tools

# 3. push back (jq packs the file into the JSON body)
curl -X PUT https://docs.aicomputercompany.com/api/docs/doc_abc123/markdown \
  -H 'Content-Type: application/json' \
  -d "$(jq -Rs '{markdown: .}' < doc.md)"

The push is still diff-applied server-side, so live collaborators keep their cursors. But prefer POST /edit for targeted changes while humans are actively editing — smaller diffs merge more gracefully than a full push, and you avoid clobbering edits made between your pull and your push.

Working habits that pay off

• Read immediately before editing (GET /raw?numbered=1) — humans may have changed the document since you last looked.
• Prefer /edit over PUT for surgical changes.
• Use annotations/bulk for review passes — one revision, one summary message.
• Anchor texts must be exact substrings of the document, outside existing {==…==} / {++…++} markup.
• Set checkpoint: true on important edits so humans get named history entries.
• Send x-actor-id and x-actor-name on every request — see Actors & identity.