Summary

docs insert-image --at <text> deletes the matched anchor text and replaces it with the image. There is no mode that inserts the image at the anchor while keeping the anchor text. The --at help reads "Placeholder text to replace, or 'end' to append", but a user reaching for "insert an image next to this sentence" will silently lose the sentence.

Root cause

buildInsertRequests in internal/cmd/docs_insert_image.go resolves the anchor via resolveImageTarget, which returns the matched TextRange, then unconditionally emits a DeleteContentRange over [placeholder.StartIndex, placeholder.EndIndex] before the InsertInlineImage:

if placeholder != nil {
    reqs = append(reqs, &docs.Request{DeleteContentRange: &docs.DeleteContentRangeRequest{
        Range: &docs.Range{StartIndex: placeholder.StartIndex, EndIndex: placeholder.EndIndex, TabId: tabID},
    }})
}
reqs = append(reqs, &docs.Request{InsertInlineImage: ...})

The same delete-the-anchor shape is in buildLinkFallbackRequests (the --on-restricted=link path).

Source: internal/cmd/docs_insert_image.go — buildInsertRequests, buildLinkFallbackRequests, resolveImageTarget.

Minimal reproducer

DOC=$(gog docs create "gog-repro-image-at" --json | jq -r .documentId)
printf 'Item one\nItem two\n' > /tmp/seed.md
gog docs write "$DOC" --replace --markdown --file /tmp/seed.md

# Insert an image anchored at "Item one" (any small public PNG URL)
gog docs insert-image "$DOC" --url https://www.gstatic.com/webp/gallery/1.png --at "Item one" --width 100

# Re-read: "Item one" text is gone, replaced by the inline image
gog docs raw "$DOC" | jq '.body.content[].paragraph.elements[]? | {text: .textRun.content, image: .inlineObjectElement}'

Expected vs actual

• Actual: the matched anchor text is deleted; the image takes its place.
• Expected (or at least an option): insert the image at the anchor index without deleting the anchor text — e.g. an --at mode that inserts before/after the match, or a separate --before/--after flag, leaving the anchor prose intact. At minimum the help text should warn loudly that the matched text is deleted.

Notes

This is currently only safe when --at points at a throwaway placeholder string. Compare docs insert-person --at, whose help is explicit ("Anchor by literal text, delete the match, and insert the person chip there") — insert-image's "Placeholder text to replace" wording is easy to misread as "insert near this text".

Reproducer derived from latest main source at commit 21ca030d; not run live in my environment (binary execution sandboxed) — please confirm the before/after JSON on a scratch doc.