# Rich Doc Agent Guide

> Use Rich Doc's HTTP API to publish and revise rich HTML documents while preserving threaded comments across versions.

The REST API is the canonical agent interface. Your main responsibility when editing an existing reviewed document is to preserve every open comment thread by keeping or moving its marker tags.

## Authentication

Act as the user who authorized you. Rich Doc uses Google OAuth for user login and issues its own `rich_doc_session` cookie. API requests made with that cookie are authorized as the same Rich Doc user as the browser session.

When calling the API directly, include the session cookie supplied by the user or runtime:

```sh
curl "$ORIGIN/auth/me" \
  -H "Cookie: rich_doc_session=$SESSION_VALUE"
```

Do not use Google access tokens as Rich Doc API credentials. Google proves identity during login; the Rich Doc session cookie authenticates API requests.

## Most Common Task: Revise A Document

If you were given a review URL such as `/d/doc_...`, extract the `doc_...` identifier and use it as `DOCUMENT_ID`.

1. Read the current document metadata and latest version:
   `GET /documents/:documentId`

2. Download the agent-editable HTML:
   `GET /documents/:documentId/editable`

3. Edit the downloaded HTML. Keep, move, or intentionally detach the Rich Doc comment marker tags as described below.

4. Publish the edited HTML as the next version:
   `POST /documents/:documentId/versions/from-editable`

Prefer multipart upload when posting an edited file from disk:

```sh
curl -X POST "$ORIGIN/documents/$DOCUMENT_ID/versions/from-editable" \
  -H "Cookie: rich_doc_session=$SESSION_VALUE" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F 'metadata={"source":"agent","summary":"Brief summary of the edit"}' \
  -F 'file=@./editable.html;type=text/html'
```

If the server rejects the upload, read the structured JSON error and fix the editable HTML instead of dropping comments. A `409 stale_editable_base_version` or `409 stale_editable_comment_set` means the document or open comment set changed while you were editing; download a fresh editable export and reapply the intended edit. A `400 invalid_comment_migration` means your submitted marker HTML is malformed; repair the current file.

## Agent Responsibilities

- Make requests with the Rich Doc session supplied by the user or runtime. A `401` response means authentication is required before continuing.
- Use an `Idempotency-Key` for document creation and version publishing.
- Respect document access. Viewing, commenting, and publishing may be denied by the document's scope or access level.
- Organization access is determined by the Rich Doc session. In Google deployments, the session organization comes from Google's hosted domain claim (`hd`); personal accounts without `hd` use the full verified email address as a single-user organization.
- Upload image assets first and reference returned asset URLs from document HTML. Asset uploads are limited to PNG, JPEG, WebP, and GIF files up to 10MB, and the bytes must match the image type.
- Prefer authored, styled documents over plain HTML dumps. Use semantic structure and self-contained CSS when it improves readability, reviewability, or visual hierarchy.
- When a document needs a neutral Rich Doc house style, start from this palette: paper `#f8f5ec`, deep paper `#f1ecdd`, panel `#fffdf7`, rule `#c9c0a6`, ink `#1b1410`, soft ink `#3d332b`, muted ink `#6b5f50`, faint ink `#948770`, accent `#7a1818`, accent wash `rgba(122, 24, 24, 0.08)`, highlight `#f4d77a`, highlight wash `rgba(244, 215, 122, 0.45)`.
- Preserve all open comment threads unless the user explicitly asks to resolve or detach them.
- Move comment markers to the best revised location when text or visuals move.
- Keep existing HTML behavior intact unless the requested edit requires changing it.
- Summarize meaningful edits in `metadata.summary` when publishing a version.
- Use structured validation errors as repair instructions.

## Comment Marker Rules

- Open threads are represented by paired marker tags:
  `<rich-doc-comment-start data-thread-id="thr_..."></rich-doc-comment-start>`
  and
  `<rich-doc-comment-end data-thread-id="thr_..."></rich-doc-comment-end>`.
- Preserve exactly one valid marker pair for every current open thread.
- Move the marker pair to wherever the comment should attach in the revised document.
- For text comments, wrap the revised text range or place an empty marker pair at a caret-like position.
- For whole visual comments, wrap exactly one `img`, `svg`, or `canvas`.
- If a visual target was intentionally deleted, leave an empty marker pair so the thread is preserved as a detached anchor.
- Do not invent, rename, duplicate, or remove thread IDs.
- Comment bodies in the exported manifest are context only; the server-side thread data is authoritative.

## Useful Endpoints

- `POST /documents`: Create a new document from JSON or multipart HTML upload.
- `GET /documents/:documentId`: Read latest document metadata and version data.
- `PUT /documents/:documentId/access`: Owner-only update for global sharing settings.
- `PATCH /documents/:documentId/access`: Same update path for changing scope or access level.
- `POST /documents/:documentId/assets`: Upload a PNG, JPEG, WebP, or GIF asset and receive a stable URL for HTML.
- `GET /documents/:documentId/editable`: Download the latest version with movable comment markers.
- `GET /documents/:documentId/versions/:versionId/editable`: Download a pinned version with movable comment markers.
- `POST /documents/:documentId/versions`: Publish raw HTML as a new version without marker migration.
- `POST /documents/:documentId/versions/from-editable`: Publish edited marker-bearing HTML and migrate open comment anchors.
- `GET /documents/:documentId/comments`: List comment threads; add `?versionId=ver_...` to scope to a version.
- `POST /documents/:documentId/comments`: Create a comment thread with optional anchor data.
- `POST /comments/:threadId/replies`: Reply to a thread.
- `POST /comments/:threadId/resolve`: Resolve a thread.
- `POST /comments/:threadId/unresolve`: Reopen a resolved thread.

## Sharing Settings

Documents use one global sharing policy:

- `accessScope`: `private`, `organization`, or `link`.
- `accessLevel`: `view`, `comment`, or `edit`.

Owners always keep edit access. Organization access depends on the caller's organization. Link access means the document URL itself grants access according to the selected level.

When link sharing is enabled, the document response includes `links.share`. It is the same review URL as `links.html`, provided as the URL to hand back to the user.

## When To Use Which Publish Endpoint

- Use `POST /documents/:documentId/versions/from-editable` when editing a reviewed document or preserving comments.
- Use `POST /documents/:documentId/versions` only when creating a new raw version that does not need comment marker validation.
- Use `POST /documents` when publishing a brand-new document.