# Examples and workflows

> End-to-end flows for reading notes, appending text safely and annotating a PDF.

- Source: https://rooqi.cn/docs/developers/examples/
- Platforms: Mac only (macOS 14 or later)
- Version: MCP server “RooQi” 0.1.0 · bridge protocol v1
- Status: Preview — not yet publicly released
- Last verified: 2026-10-26 against the RooQi Mac source; flows not yet re-run on a public release
- Known limitations: Try new workflows on a separate test project first.

## Summarise notes with an assistant (read-only)

1. `rooqi_request_read_access` → `approvalRequired`. Approve the window in RooQi and choose the project.
2. `rooqi_request_read_access` again → `ready`.
3. `rooqi_list_approved_documents` → `{ "<id>": "Lecture 3", … }`
4. `rooqi_read_note` with `{ "documentID": "<id>" }` → saved text and revision.

The assistant only sees saved text — not handwriting, images or PDF source text.

## Append a summary safely

1. Request write access and approve it.
2. Read the note to learn its current `revision`.
3. Generate fresh UUIDs for `operationID` and **store them before calling**.
4. Call `rooqi_append_text`:

```json
{
  "operationID": "3B1F7A2C-9E44-4D51-A0C6-1E2F3A4B5C6D",
  "documentID": "<id>",
  "text": "Summary: …",
  "expectedVersion": 7,
  "provider": "example-assistant",
  "model": "example-model-1",
  "promptVersion": "summary-v1"
}
```

5. On `mutationUncertain` or a timeout, call again with the **same** body. On `mutationRejected`, read again and use a new `operationID` only if you intend a new write.

## Highlight a sentence in a PDF

1. `rooqi_request_pdf_annotation_access`, approve, call again.
2. `rooqi_list_pdf_targets` with the document → pick a `surfaceID` and page from `availableSourcePages`.
3. `rooqi_read_pdf_page` with a region, e.g. the top half of page 0:

```json
{ "documentID": "<doc>", "surfaceID": "<surface>", "pageIndex": 0,
  "rect": { "x": 0, "y": 0, "width": 1000000, "height": 500000 } }
```

4. Narrow `rect` to the lines you want using the returned `lines[].rect`, read again, then call `rooqi_annotate_pdf` with the same `query`, the returned `revision` as `expectedVersion`, `sourceAssetID` and the three digests, `kind: "highlight"` and an empty `comment`.
5. If the result is uncertain, call `rooqi_query_pdf_operation` with the same `operationID`.