docs insert-image --at <text> deletes the matched anchor text (no insert-without-replace mode; help wording understates it)

[sebsnyk]

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.

[sebsnyk]

Live-confirmed on v0.28.1-dev (commit 21ca030d). The matched anchor text is deleted and replaced by the image, exactly as the issue describes.

Before / after (scratch doc)

Seed a paragraph, then anchor an image at it:

gog docs write "$DOC" --replace --markdown --file seed.md   # seed.md ends with a line: "Plain trailing paragraph."
gog docs insert-image "$DOC" --url https://www.gstatic.com/webp/gallery/1.png --at "Plain trailing paragraph." --width 100

insert-image reports requests 2 (the DeleteContentRange + InsertInlineImage pair).

Before — the paragraph exists:

{ "t": "Plain trailing paragraph.\n" }

After — the text run is gone, replaced by an inline image element:

{ "text": null, "img": "kix.ocm23f5o18q" }
{ "text": "\n",  "img": null }

The anchor prose is not recoverable. Confirms the buildInsertRequests analysis: the DeleteContentRange over [placeholder.StartIndex, placeholder.EndIndex] fires unconditionally before the insert.

Suggestion stands: add a non-destructive mode (--before / --after, or an --at variant that inserts at the index without deleting the match), and meanwhile sharpen the --at help from "Placeholder text to replace" to something that says the matched text is deleted.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 18, 2026, 6:49 AM ET / 10:49 UTC.

Summary
Keep open: current main still deletes the matched range before inserting the image, including the restricted-sharing link fallback, and no non-destructive image-anchor flags are present yet. #843 is an open linked implementation candidate, so this issue should wait for that PR to land or be closed by maintainers.

Reproducibility: yes. Source inspection on current main shows a deterministic delete-then-insert request pair, and the reporter added live before/after proof; I did not mutate a live Google Doc in this read-only review.

Root-cause cluster
Relationship: canonical
Canonical: #839
Summary: This issue is the canonical user-facing report; the open linked PR is the candidate fix, while related QA work tracks broader regression coverage.

Members:

• fixed_by_candidate: feat(docs): add non-destructive image anchors #843 - The PR body and closing reference directly target non-destructive image anchors for this issue.
• partial_overlap: QA: no structure-preservation regression suite for mutating commands (seed-fixture + raw-diff invariants); covers the #838/#839 class #840 - The QA issue tracks broader structure-preservation coverage and cites this issue as one known instance, but it does not replace the product fix.
• partial_overlap: test(live): add Docs structure-preservation regressions #841 - The draft live-test skeleton references future coverage for this issue but is not the implementation fix.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Next step
A linked open PR already owns the implementation path, so ClawSweeper should not queue a competing repair PR from this issue.

Review details

Best possible solution:

Review and land #843 if its compatibility-preserving --before and --after behavior holds up, then leave broader structure-preservation coverage to #840.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection on current main shows a deterministic delete-then-insert request pair, and the reporter added live before/after proof; I did not mutate a live Google Doc in this read-only review.

Is this the best way to solve the issue?

Yes. Adding explicit non-destructive --before and --after modes while preserving existing --at replacement is the narrowest compatibility-safe solution visible from the linked candidate PR.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against c02fdf7bc1a1.

Label changes

Label changes:

• add P2: This is a bounded but real Docs editing problem with an open candidate fix rather than an emergency core-runtime failure.
• add impact:data-loss: Using the current anchor mode on prose deletes matched document text and replaces it with an image or fallback link.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.

Label justifications:

• P2: This is a bounded but real Docs editing problem with an open candidate fix rather than an emergency core-runtime failure.
• impact:data-loss: Using the current anchor mode on prose deletes matched document text and replaces it with an image or fallback link.

Evidence reviewed

What I checked:

• Current direct image insertion deletes the anchor: buildInsertRequests appends DeleteContentRange for a resolved placeholder before InsertInlineImage, so a text match is replaced rather than preserved on current main. (internal/cmd/docs_insert_image.go:321, c02fdf7bc1a1)
• Restricted fallback has the same destructive shape: buildLinkFallbackRequests also emits DeleteContentRange before inserting the fallback link, matching the issue's second affected path. (internal/cmd/docs_insert_image.go:340, c02fdf7bc1a1)
• Current help has only destructive --at wording: The command struct exposes --at as placeholder replacement and does not expose --before or --after on current main. (internal/cmd/docs_insert_image.go:27, c02fdf7bc1a1)
• Unit coverage currently expects replacement: TestDocsInsertImageBuildsPlaceholderReplacement asserts the builder returns two requests with DeleteContentRange first and InsertInlineImage second. (internal/cmd/docs_remaining_features_test.go:353, c02fdf7bc1a1)
• Open candidate fix exists: feat(docs): add non-destructive image anchors #843 is open, mergeable, references this issue as its closing issue, and its diff adds --before and --after while preserving --at replacement behavior. (a12e38652105)
• Relevant release/main check: The latest release tag contains the destructive implementation, and git log v0.28.0..HEAD shows no changes to the relevant insert-image code, docs, or tests on current main. (6bc67d7dd770)

Likely related people:

• steipete: Introduced the Docs insert-image command, later expanded its public URL support, release-prepared the current generated docs/tests, and authored the open non-destructive-anchor candidate PR. (role: feature/history owner and current fix author; confidence: high; commits: 3bed2b06e788, 65ad08422a89, 6bc67d7dd770; files: internal/cmd/docs_insert_image.go, internal/cmd/docs_insert_image_test.go, internal/cmd/docs_remaining_features_test.go)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.