---
name: documents
description: |
  Read DOCX, PPTX, and PDF files by converting to markdown. Uses pandoc for Office
  files and Mistral OCR for PDFs. Use when the user asks to read, convert, extract,
  or OCR a document, PDF, DOCX, or PPTX.
---

# Documents

Convert documents to `<name>.md` beside the source file. If that `.md` already exists, read it — do not re-convert.

| Format | Tool |
|--------|------|
| `.docx`, `.pptx` | pandoc (`brew install pandoc`) |
| `.pdf` | Mistral OCR |
| images | read directly (vision); use Mistral OCR only if the user says it is a long text image that needs OCR |

## DOCX / PPTX

For reading DOCX/PPTX files, use the CLI: `pandoc <file> --o <file>.md  --extract-media=./images/<file>` — never write a Python script to parse them. Put output in the same project folder to prevent future rerun.

```bash
pandoc report.docx -o report.md --extract-media=./images/report
```

## PDF (Mistral OCR)

API key: user provides it in the message, or set `$MISTRAL_API_KEY`. Ask if neither is available.

```bash
BASE64=$(base64 -i file.pdf | tr -d '\n')

curl -s "https://api.mistral.ai/v1/ocr" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"mistral-ocr-latest\",\"document\":{\"type\":\"document_url\",\"document_url\":\"data:application/pdf;base64,${BASE64}\"}}" \
  | jq -r '.pages[].markdown' > file.md
```

For remote PDFs, pass a public URL as `document_url` instead of base64.

## Workflow

1. If `<name>.md` exists beside the source, read it.
2. `.docx`/`.pptx` → pandoc. `.pdf` → Mistral OCR. Images → read natively unless the user requests OCR.
3. Write `<name>.md` next to the source, then read it.