# Docs by AI Computer Company — Complete Agent Manual

Collaborative markdown documents that AI agents read and edit over REST while
humans edit the same document live in the browser. Server-side writes are
applied as minimal diffs into the shared CRDT, so human collaborators' cursors
survive every agent edit.

API base: https://docs.aicomputercompany.com/api
Share link for humans: https://docs.aicomputercompany.com/<doc_id>

AUTHORIZATION
  None. Possession of the unguessable document id (doc_<nanoid18>) is the
  capability: anyone who knows the id can read and write that document.
  No API keys, no signup, no Authorization header needed.

IDENTITY HEADERS (optional but recommended)
  x-actor-id:   stable agent identity, must start with "agent_"
                (e.g. x-actor-id: agent_claude_main). 400 otherwise.
  x-actor-name: display name shown to humans (e.g. x-actor-name: Claude).
  Send both on every request so your edits, annotations, and revisions are
  attributed consistently. Omitting them creates a fresh anonymous agent
  actor per request.

CONTENT
  The document body is plain markdown. Review state (annotations, comments,
  suggestions) is stored inline as CriticMarkup/RFM markup plus a YAML
  endmatter block; the editor hides it and clean export strips it.

================================================================================
LIFECYCLE: CREATE → READ → EDIT → PUSH
================================================================================

CREATE A DOCUMENT
  POST /api/docs
  Body: {"markdown": "# My Doc\n\n...", "title": "My Doc"}   (both optional)
  → 201 {"document": {"id": "doc_…", …}, "latestRevision": {…},
         "actor": {…}, "shareUrl": "https://docs.aicomputercompany.com/doc_…", "yjsWsUrl": "wss://…"}
  Give the shareUrl to humans; use document.id for all API calls.

  curl -X POST https://docs.aicomputercompany.com/api/docs \
    -H 'Content-Type: application/json' \
    -H 'x-actor-id: agent_demo' -H 'x-actor-name: Demo Agent' \
    -d '{"markdown": "# Plan\n\nDraft.\n", "title": "Plan"}'

READ (always read before editing)
  GET /api/docs/:id/raw                → current markdown, text/plain
  GET /api/docs/:id/raw?numbered=1     → cat -n style: 6-char right-aligned
                                         line number, tab, line content
  GET /api/docs/:id                    → {"document", "latestRevision"} JSON

  curl https://docs.aicomputercompany.com/api/docs/doc_abc123/raw?numbered=1

EDIT (preferred for changes — exact str_replace semantics)
  POST /api/docs/:id/edit
  Body: {"old_string": "exact text in doc",
         "new_string": "replacement text",
         "replace_all": false}          (replace_all optional, default false)
  Semantics (identical to the local-file Edit tool):
    - old_string must match the document text exactly, including whitespace.
    - old_string not found
        → 409 {"error": "old_string not found in document"}
    - old_string found more than once and replace_all is not true
        → 409 {"error": "old_string is not unique; provide more context or set replace_all"}
      Fix by including more surrounding context in old_string, or set
      "replace_all": true to change every occurrence.
    - old_string === new_string → 400.
    - success → 200 {"applied": true, "occurrences": n, "revisionHint": "rev_…"?}
  The edit is applied to the live document as a minimal diff — collaborators
  see it instantly and their cursors are preserved.

  curl -X POST https://docs.aicomputercompany.com/api/docs/doc_abc123/edit \
    -H 'Content-Type: application/json' \
    -H 'x-actor-id: agent_demo' \
    -d '{"old_string": "## Old heading", "new_string": "## New heading"}'

PUSH (full document replace — for wholesale rewrites)
  PUT /api/docs/:id/markdown
  Body: {"markdown": "<entire new document>",
         "checkpoint": true,            (optional, default true: save a revision)
         "message": "why"}              (optional revision message)
  → 200 {"document", "revision"}
  Server-side the new content is diff-applied into the live document (never a
  full delete+insert), so collaborator cursors survive even a full push.

  curl -X PUT https://docs.aicomputercompany.com/api/docs/doc_abc123/markdown \
    -H 'Content-Type: application/json' \
    -d '{"markdown": "# Rewritten\n\nAll new.\n", "message": "Full rewrite"}'

SAVE-TO-LOCAL + PUSH-BACK WORKFLOW
  Work on the document with your normal local file tools, then push back:
    1. curl https://docs.aicomputercompany.com/api/docs/doc_abc123/raw > doc.md
    2. Edit doc.md locally (any editor/tool).
    3. curl -X PUT https://docs.aicomputercompany.com/api/docs/doc_abc123/markdown \
         -H 'Content-Type: application/json' \
         -d "$(jq -Rs '{markdown: .}' < doc.md)"
  Prefer POST /api/docs/:id/edit for targeted changes while humans are
  editing — smaller diffs merge more gracefully than a full push.

================================================================================
HISTORY: CHECKPOINTS, REVISIONS, REVERT, EXPORT
================================================================================

  POST /api/docs/:id/checkpoints
    Body: {"markdown"?: "...", "reason"?: "manual-save", "message"?: "..."}
    (markdown defaults to the latest revision content)
    → 201 {"document", "revision"}      named save point

  GET /api/docs/:id/revisions           → {"revisions": [...], "actors": {...}}
  GET /api/docs/:id/revisions/:revId    → {"revision"}
  GET /api/docs/:id/revisions/:revId/raw → that revision's markdown

  POST /api/docs/:id/revert
    Body: {"revisionId": "rev_…"}
    → 201 {"document", "revision"}      creates a new revision with the old
    content and diff-applies it to the live document.

  GET /api/docs/:id/export.md           → markdown download
  GET /api/docs/:id/export.md?clean=1   → publishing export: strips all review
    markup (annotations/comments unwrapped, pending suggestions rejected,
    endmatter removed)
  GET /api/docs/:id/export.clean.md     → clean export of the LIVE document
    content (export.md exports the latest saved revision)

  curl https://docs.aicomputercompany.com/api/docs/doc_abc123/export.md?clean=1

================================================================================
REVIEW API — ANNOTATIONS, COMMENTS, SUGGESTIONS, VIEWS
================================================================================

REVIEW INDEX (read everything review-related)
  GET /api/docs/:id/review-index
  → {"source": "live"|"revision", "fileVersion": "rev_…",
     "index": {"items": [...]},        all review items with line numbers
     "annotations": [...]}             items carrying a verdict, each with
                                       {id, line, verdict, refs, body, …}

ANNOTATIONS (Layer 1 — spec-review verdicts anchored to exact text)
  POST /api/docs/:id/annotations
    Body: {"anchorText": "exact text to anchor to",   (required)
           "occurrence": 1,                            (optional, disambiguates)
           "verdict": "valid" | "question" | "conflict",  (required)
           "body": "your explanation",                 (required)
           "refs": ["a7"],                             (optional, ids of
                                                        conflicting annotations)
           "checkpoint": false, "message": "..."}      (optional)
    → 201 {"id": "a1", "line": 12, "revision": null|{…}}
    → 409 if anchorText is not found outside existing markup.
    Verdicts: valid = requirement is clear & consistent,
              question = needs clarification,
              conflict = conflicts with another requirement (use refs).

  POST /api/docs/:id/annotations/bulk        (primary verb for a review pass)
    Body: {"annotations": [ ...same shape as above... ],
           "checkpoint": true,                          (default true)
           "message": "AI spec review"}
    → 201 {"created": [{id, …}], "failed": [{input, error}], "revision"}
    One revision for the whole pass; failed anchors don't abort the rest.

  POST /api/docs/:id/annotations/:targetId/resolve   {"resolution"?: "..."}
    → {"ok": true, "revision"}          marks status=resolved in endmatter
  DELETE /api/docs/:id/annotations/:targetId
    → {"ok": true, "revision"}          removes markup + endmatter entry

  curl -X POST https://docs.aicomputercompany.com/api/docs/doc_abc123/annotations/bulk \
    -H 'Content-Type: application/json' -H 'x-actor-id: agent_demo' \
    -d '{"annotations": [
          {"anchorText": "must support offline mode", "verdict": "valid",
           "body": "Confirmed in section 3.2"},
          {"anchorText": "sync every 5 minutes", "verdict": "conflict",
           "body": "Conflicts with the realtime requirement", "refs": ["a1"]}
        ]}'

COMMENTS & REPLIES (Layer 2 — verdict-less discussion)
  POST /api/docs/:id/comments
    Body: {"body": "comment text",                  (required)
           "anchorText": "...", "occurrence": 1}    (optional; omit both for a
                                                     document-level comment)
    → 201 {"id": "c1"|null, "revision"}
  POST /api/docs/:id/comments/:parentId/replies     {"body": "reply text"}
    → 201 {"ok": true, "revision"}                  threaded under the parent
  POST /api/docs/:id/comments/:targetId/resolve     {"resolution"?: "..."}
    → {"ok": true, "revision"}

SUGGESTIONS (tracked changes humans accept/reject in the editor)
  Stored as CriticMarkup in the document text:
    {++added text++}   {--deleted text--}   {~~old~>new~~}
  POST /api/docs/:id/suggestions
    Body: {"kind": "addition" | "deletion" | "substitution",
           "anchorText": "insert after this text",   (addition)
           "targetText": "text to delete/replace",   (deletion/substitution)
           "occurrence": 1,                          (optional)
           "text": "new text",                       (addition/substitution)
           "body": "rationale shown in the review rail"}  (optional)
    → 201 {"id": "s1", "revision"}
    → 409 if anchorText/targetText is not found.
  POST /api/docs/:id/suggestions/:targetId/accept   → {"ok": true, "revision"}
  POST /api/docs/:id/suggestions/:targetId/reject   → {"ok": true, "revision"}

  curl -X POST https://docs.aicomputercompany.com/api/docs/doc_abc123/suggestions \
    -H 'Content-Type: application/json' \
    -d '{"kind": "substitution", "targetText": "5 minutes",
         "text": "30 seconds", "body": "Match the SLA in section 2"}'

VIEWS (Layer 3 — agent-generated side panels: gantt, coverage, prompts,
       digest, custom — see CUSTOM VIEWS below for pushing your own HTML UI)
  GET    /api/docs/:id/views             → {"views": [...], "currentRevisionId"}
  POST   /api/docs/:id/views
    Body: {"kind": "gantt"|"coverage"|"prompts"|"digest"|<custom string>,
           "title"?: "...", "payload": <kind-specific JSON>,
           "replace"?: true}             (default true: upsert by kind)
    → 201 {"view"}
  DELETE /api/docs/:id/views/:viewId     → {"ok": true}
  POST   /api/docs/:id/views/:viewId/refresh-request
    → {"ok": true}                       human asked for a regenerate; emits a
                                         "refresh-requested" event for you
  GET    /api/docs/:id/view-events?since=0&timeoutMs=25000
    → {"events": [{seq, type, viewId, at}], "seq"}
    Long-poll: blocks until events newer than `since` arrive (or timeout).
    Event types: view-updated, view-deleted, refresh-requested.
    Loop on this to close the cycle: human edits → clicks refresh → you
    regenerate the view payload and POST it back.

================================================================================
CUSTOM VIEWS — PUSH YOUR OWN UI
================================================================================

Need a visualization that no built-in view kind covers? Push kind "custom"
with a self-contained HTML/JS document and the app renders it in the Views
pane. Build whatever you and the user need: charts, kanban boards, decision
matrices, timelines.

PAYLOAD
  POST /api/docs/:id/views
  Body: {"kind": "custom",
         "title": "Effort vs impact",            (card header, optional)
         "payload": {"html": "<!doctype html>…",  (required, string, ≤ 1MB)
                     "title": "..."}}             (optional iframe title)
  → 201 {"view"}; 400 if payload.html is missing, not a string, or > 1MB.
  Upserts by kind like other views (one custom view per document by default;
  pass "replace": false to keep several).

SANDBOX (the rules your HTML runs under)
  The document renders in <iframe sandbox="allow-scripts"> via srcdoc — no
  same-origin access. Your code CANNOT touch the parent page, cookies, auth
  tokens, or the collaboration socket, and has an opaque origin (no
  localStorage; fetch to most APIs is subject to CORS). Inline all CSS/JS or
  load it from CDNs. Talk to the host app only through the bridge below.

POSTMESSAGE BRIDGE (protocol v1 — every message carries docsBridge: 1)
  iframe → parent: {"docsBridge": 1, "type": "getDocument", "requestId": "<any string>"}
  parent → iframe: {"docsBridge": 1, "type": "document", "requestId": "<echoed>",
                    "markdown": "<current doc text>",
                    "reviewIndex": {"items": [...]},   review items w/ verdicts
                    "actors": {<actorId>: {...}},      known collaborators
                    "views": [...]}                    all pushed views
  iframe → parent: {"docsBridge": 1, "type": "requestRefresh"}
                   → the app fires the refresh-request endpoint for this view,
                     which reaches you as a "refresh-requested" view-event.

COMPLETE MINIMAL EXAMPLE (renders a live word count from the document)
  <!doctype html>
  <html>
  <body style="font-family: system-ui; padding: 16px">
    <h3>Word count</h3>
    <div id="out">loading…</div>
    <button id="refresh">Ask agent to refresh</button>
    <script>
      const requestId = String(Math.random())
      addEventListener('message', (event) => {
        const msg = event.data
        if (!msg || msg.docsBridge !== 1) return
        if (msg.type === 'document' && msg.requestId === requestId) {
          const words = msg.markdown.split(/\s+/).filter(Boolean).length
          document.getElementById('out').textContent = words + ' words'
        }
      })
      parent.postMessage({ docsBridge: 1, type: 'getDocument', requestId }, '*')
      document.getElementById('refresh').onclick = () =>
        parent.postMessage({ docsBridge: 1, type: 'requestRefresh' }, '*')
    </script>
  </body>
  </html>

  Push it (jq packs the HTML file into the JSON payload):
  curl -X POST https://docs.aicomputercompany.com/api/docs/doc_abc123/views \
    -H 'Content-Type: application/json' -H 'x-actor-id: agent_demo' \
    -d "$(jq -Rs '{kind: "custom", title: "Word count", payload: {html: .}}' < view.html)"

  Note: the parent answers with targetOrigin '*' (sandboxed frames have an
  opaque origin), and only messages originating from your iframe are honored.
  The bridge exposes nothing the human viewer cannot already see.

================================================================================
THE REVIEW PROCESS — RECOMMENDED METHODOLOGY
================================================================================

Follow this when a human gives you requirements, specs, plans, or meeting
notes to work through. It is the workflow this product is built around.

STEP 1 — CONSOLIDATE
  Gather every requirement and piece of context the human has provided and
  write it into ONE well-structured document: numbered sections, one
  requirement per statement, owners and dates where known. Create the doc,
  give the human the shareUrl. From here on the document is the single
  source of truth — work in it, not in chat.

STEP 2 — REVIEW EVERY REQUIREMENT, LINE BY LINE
  Read with GET /:id/raw?numbered=1 and walk the document top to bottom.
  For each requirement check the logic: clear? testable? complete? Does it
  contradict another requirement elsewhere in the document? Then post ONE
  bulk pass so the human gets a single review revision:
    POST /:id/annotations/bulk
    {"annotations": [{"anchorText": "<exact phrase>", "verdict": "...",
                      "body": "<your reasoning>", "refs": ["a3"]}],
     "message": "AI requirements review"}
  Verdict guide:
    valid    — clear, consistent, testable; say WHY it holds up
    question — needs follow-up from the human; ask the precise question
    conflict — contradicts another requirement; link the counterpart via
               refs so the UI renders jump-links between the two anchors
  ANCHORING RULES:
    - Status of a task/requirement line (confirmed, verified, done,
      blocked): anchor the ENTIRE line, first character to last. A status
      applies to the whole task; a partial-line anchor reads as if only
      that fragment were confirmed.
    - A specific issue WITHIN a line (ambiguous phrase, wrong value):
      anchor exactly that phrase, not the whole line.
    - No emojis in annotations, comments, or document content unless the
      human asks for them.

STEP 3 — SURFACE BLOCKERS AND USER ACTIONS
  Post a document-level comment (POST /:id/comments with no anchorText)
  that a busy human can act on without opening every card:
    - verdict counts (e.g. "9 valid · 3 questions · 1 conflict pair")
    - which items BLOCK progress vs. can proceed in parallel
    - a short numbered "decisions needed from you" list
  Where you can resolve an issue yourself, propose it as a suggestion the
  human accepts or rejects with one click:
    POST /:id/suggestions {"kind": "substitution", "targetText": "...",
                           "text": "...", "body": "why this resolves it"}

STEP 4 — BUILD THE UI THE REVIEW DESERVES
  Push side-panel views so the human sees the whole picture at a glance
  (POST /:id/views — see VIEWS above for full schemas):
    gantt   — timeline derived from the requirements (tasks, owners,
              dependencies); click-through to the source text
    digest  — stakeholder brief: TL;DR, decisions made, open questions,
              blockers, next checkpoint
    custom  — ANY visualization you or the user need: risk heatmaps,
              decision trees, coverage matrices, burn-down charts —
              self-contained HTML/JS, sandboxed (see CUSTOM VIEWS)
  The coverage matrix is generated live from your annotations for free.

STEP 5 — CREATE PROMPTS AND DELEGATE THE WORK
  Turn reviewed requirements into per-task handoff prompts other agents
  can execute without further context:
    POST /:id/views {"kind": "prompts", "payload": {"cards": [
      {"id": "p1", "title": "<task>", "prompt": "<context + task +
       acceptance criteria, fully self-contained>"}]}}
  Each card renders copy buttons for GitHub Copilot, Cursor, OpenAI Codex,
  Claude Code, and Google Gemini. Include the document's shareUrl inside
  every prompt so the executing agent can read the source of truth.

STEP 6 — CLOSE THE LOOP
  Long-poll GET /:id/view-events?since=<seq> for "refresh-requested" —
  the human clicked refresh on one of your views; regenerate its payload
  from the current document and POST it again. Re-read the document
  before every later edit. When the review settles, hand back clean copy:
  GET /:id/export.md?clean=1 (annotations, comments, and pending
  suggestions stripped for publishing).

================================================================================
TIPS FOR AGENTS
================================================================================
  - Always GET /api/docs/:id/raw (use ?numbered=1) immediately before editing;
    humans may have changed the document since you last read it.
  - Prefer /edit (str_replace) 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.