# Verifying image embedding in Google Docs

Use this when a task requires images to exist *inside* a Google Document, especially when editing through an anonymous link or browser automation.

## Completion criterion

A visible URL, filename, placeholder, or successful paste event is not an embedded image. Completion requires both:

1. Visual confirmation that the actual image object appears at the intended location.
2. Artifact confirmation that an exported DOCX contains binary media under `word/media/`.

## Deterministic DOCX probe

```python
import io, urllib.request, zipfile

DOC_ID = "..."
url = f"https://docs.google.com/document/d/{DOC_ID}/export?format=docx"
data = urllib.request.urlopen(url, timeout=60).read()
with zipfile.ZipFile(io.BytesIO(data)) as zf:
    media = [n for n in zf.namelist() if n.startswith("word/media/")]
print(media)
```

Interpretation:

- `[]` means the document contains no embedded image binaries.
- A non-empty list confirms media exists, but not its order or placement. Inspect `word/document.xml` and relationships, or visually review the relevant pages, to verify position.
- Run the probe after one test image before attempting a large batch.

## Anonymous-editor pitfall

Anonymous edit permission can be asymmetric: text editing may work while **Insert → Image** is disabled. Check the menu before promising completion. If disabled:

- Do not replace placeholders with image URLs and call that complete.
- Do not infer success from `Ctrl+V` returning without an error.
- Preserve the original image files and placeholders.
- Report the exact blocker and request authenticated edit access, or prepare an alternate DOCX with images for the user to import.

## Safe sequence for chronological transcripts

1. Put unique markers in the assembled transcript, e.g. `[[IMAGE_1_NATAL_CHART]]`.
2. Verify all markers occur exactly once before upload.
3. Probe media insertion with one image.
4. Replace markers one at a time at their original positions.
5. After each replacement, confirm the image visually and ensure the marker disappeared.
6. Export DOCX and count `word/media/` entries; compare with the expected number of embedded images.
7. Only then report the Google Document as complete.

## Reporting rule

Use explicit partial-state language when necessary: “The text is uploaded; 0 of 4 images are embedded.” Never use “done,” “ready,” or “uploaded successfully” when a required media check failed.