feat(docs): add non-destructive image anchors

[steipete]

Summary

• add non-destructive docs insert-image --before and --after anchor modes
• preserve existing --at placeholder replacement and default end append behavior
• apply placement consistently to direct images and restricted-sharing link fallback
• clarify generated and editing docs

Fixes #839.

Testing

• go test ./internal/cmd -run 'TestDocsInsertImage' -count=1
• make ci
• autoreview: clean
• live Google Docs proof: inserted public images before and after a literal anchor, preserved the anchor text, observed two inline objects, and trashed the scratch document

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 18, 2026, 6:53 AM ET / 10:53 UTC.

Summary
The PR adds docs insert-image --before and --after anchor modes, refactors image target resolution, updates docs and CHANGELOG, and adds unit coverage for direct-image and restricted-link fallback placement.

Reproducibility: yes. The linked issue provides scratch-doc commands and live confirmation, and current main source shows matched ranges are deleted before image or fallback-link insertion; I did not run live Google API tests in this read-only review.

Review metrics: 2 noteworthy metrics.

• User-facing flags: 2 added (--before, --after). The command surface changes, so help text, docs, and backwards compatibility need explicit review before merge.
• Anchor paths tested: 2 request paths covered. The PR covers both direct inline image insertion and restricted-sharing link fallback for non-destructive placement.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #839
Summary: This PR is the candidate fix for the open docs insert-image anchor-deletion issue; the broader structure-preservation suite request is adjacent, not the same required fix.

Members:

• canonical: docs insert-image --at <text> deletes the matched anchor text (no insert-without-replace mode; help wording understates it) #839 - The PR body uses closing syntax for this open issue, and the diff directly addresses its requested non-destructive image anchor modes.
• adjacent_distinct: QA: no structure-preservation regression suite for mutating commands (seed-fixture + raw-diff invariants); covers the #838/#839 class #840 - Search found this broader QA-suite issue covering the same class, but it asks for a generalized live regression harness rather than the specific image-anchor behavior changed here.

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

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] Required CI was still unstable or in progress in GitHub status at review time, so merge should wait for the normal check gate.

Maintainer options:

1. Decide the mitigation before merge
   Land this PR after maintainer review and green required checks, keeping --at replacement semantics while adding documented --before and --after non-destructive anchors with focused regression coverage.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• This collaborator-authored PR has no discrete repair finding and closes an open linked issue, so it should continue through normal maintainer review and CI rather than ClawSweeper cleanup or repair.

Security
Cleared: No concrete security or supply-chain concern was found; the diff adds CLI flags, docs, and tests without changing credential handling or broadening Drive sharing behavior.

Review details

Best possible solution:

Land this PR after maintainer review and green required checks, keeping --at replacement semantics while adding documented --before and --after non-destructive anchors with focused regression coverage.

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

Yes. The linked issue provides scratch-doc commands and live confirmation, and current main source shows matched ranges are deleted before image or fallback-link insertion; I did not run live Google API tests in this read-only review.

Is this the best way to solve the issue?

Yes. Separate --before and --after modes are a narrow maintainable fix because they preserve existing --at replacement behavior while adding the missing non-destructive placement option.

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 normal-priority Docs CLI improvement and linked bug fix with limited blast radius.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this collaborator-authored PR; the body nevertheless reports a live Google Docs check for before/after insertion.

Label justifications:

• P2: This is a normal-priority Docs CLI improvement and linked bug fix with limited blast radius.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this collaborator-authored PR; the body nevertheless reports a live Google Docs check for before/after insertion.

Evidence reviewed

What I checked:

• Repository policy read: Read the full target AGENTS.md and applied its PR review guidance by using gh view/diff without switching branches or editing files. (AGENTS.md:1, c02fdf7bc1a1)
• Maintainer notes check: The repository has skill files under .agents but no matching .agents/maintainer-notes directory to apply for this PR. (c02fdf7bc1a1)
• Current main lacks non-destructive image anchors: Current main exposes only --at with default end for docs insert-image; no --before or --after flags exist on the command struct. (internal/cmd/docs_insert_image.go:27, c02fdf7bc1a1)
• Current main deletes matched image anchors: The current implementation appends DeleteContentRange before InsertInlineImage and does the same shape for link fallback, matching the linked issue's reported behavior. (internal/cmd/docs_insert_image.go:320, 6bc67d7dd770)
• Latest release lacks the PR behavior: The v0.28.0 release copy of docs_insert_image.go has the same pre-PR At string and delete-then-insert implementation, so the central change has not shipped in the latest release. (internal/cmd/docs_insert_image.go:23, 6bc67d7dd770)
• PR implementation evidence: The PR adds pointer-backed --at, --before, and --after flags plus target resolution that keeps --at replacement/default append while resolving before/after as non-deleting insert locations. (internal/cmd/docs_insert_image.go:27, a12e38652105)

Likely related people:

• steipete: Git blame shows the current docs insert-image command and destructive anchor behavior dating to the v0.28.0 release commit, and shortlog shows the central docs insert-image files are authored by Peter Steinberger on main. (role: current main feature owner and recent area contributor; confidence: high; commits: 6bc67d7dd770; files: internal/cmd/docs_insert_image.go, internal/cmd/docs_insert_image_test.go, internal/cmd/docs_remaining_features_test.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

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.