Best possible solution:

Review and land this PR if the remaining CI and maintainer validation are acceptable, keeping the related issue open until the candidate fix merges.

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

Not applicable: this is a feature PR, not a reported current-main bug. Source inspection shows current main lacks the dedicated command while the related issue describes the desired workflow.

Is this the best way to solve the issue?

Yes: the PR takes a narrow path by adding a dedicated command while reusing existing image enumeration and upload helpers. The remaining question is ordinary merge validation, not a different implementation direction.

AGENTS.md: found and applied where relevant.

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

Label changes:

• add P2: This is a normal-priority Docs automation feature with useful layout-preserving behavior and limited blast radius.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster 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 includes live Google Docs proof for URL/object-id/single-image replacement and mocked Drive coverage for local-file cleanup.

Label justifications:

• P2: This is a normal-priority Docs automation feature with useful layout-preserving behavior and limited blast radius.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster 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 includes live Google Docs proof for URL/object-id/single-image replacement and mocked Drive coverage for local-file cleanup.

What I checked:

• Repository policy read: AGENTS.md was read fully; its PR-review and parseable-output guidance is relevant because this PR adds a CLI command and generated command docs. (AGENTS.md:1, ab9a331d4c07)
• Collaborator-authored PR: GitHub reports author_association=COLLABORATOR, so this cleanup workflow should keep the PR open for normal project handling.
• New command registration: The PR adds ReplaceImage DocsReplaceImageCmd under the Docs command tree. (internal/cmd/docs.go:41, 87029ed0507c)
• Core replacement implementation: The new command builds a Docs ReplaceImageRequest with object ID, URI, CENTER_CROP, optional tab ID, and required revision write control. (internal/cmd/docs_replace_image.go:207, 87029ed0507c)
• Current main lacks dedicated command: Current main has InsertImage but no ReplaceImage command registration, so the PR is not duplicating an already-merged command. (internal/cmd/docs.go:40, ab9a331d4c07)
• Related issue remains open: The PR uses closing syntax for feat(docs): replace-image command (replaceImage) — swap image bytes in place without losing position/size #853, whose discussion says a collaborator stopped the queued implementation because the item was being taken locally.

Likely related people:

• steipete: Current-main blame/log history ties the existing Docs insert-image, image enumerator, and sed image replacement surface to Peter Steinberger, and this branch continues that same area. (role: recent Docs image area contributor; confidence: high; commits: 508a4d3cd368, 87029ed0507c; files: internal/cmd/docs_insert_image.go, internal/cmd/docs_enumerators.go, internal/cmd/docs_sed_images.go)
• sebsnyk: Sebastian Roth authored the linked feature request and adjacent Docs workflow reports that define the user-facing replace-image need. (role: workflow reporter; confidence: low; commits: ab9a331d4c07; files: docs/docs-editing.md, internal/cmd/docs_edit.go, internal/cmd/docs_mutation.go)

• 🦀 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.

• 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.