feat(docs): insert images from public URLs

[steipete]

Summary

• Add docs insert-image --url for direct public HTTPS image insertion.
• Keep --file as the existing upload/share/revoke path and make the two sources mutually exclusive.
• Skip Drive service creation, public-sharing confirmation, and upload metadata in URL mode.
• Reject embedded credentials and upload-only flags with --url.

Fixes #675.

Validation

• go test ./internal/cmd -run 'TestDocsInsertImage|TestDocsWrite_Markdown.*Image|TestDocsFindReplace_.*Image'
• make ci
• autoreview: clean

Live Proof

Ran the branch binary with clawdbot@gmail.com against a disposable Google Doc using Google's public Docs icon URL.

• docs insert-image --url ... --width 96 --height 96 succeeded.
• JSON output returned the source URL and no uploadedFileId.
• docs raw returned an inline object with the same sourceUri and a 96 by 96 PT size.
• The disposable document was moved to trash.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 11, 2026, 12:21 AM ET / 04:21 UTC.

Summary
Adds a mutually exclusive docs insert-image --url source that bypasses Drive upload and sharing, with focused tests and updated generated command documentation.

Reproducibility: not applicable. as a feature PR; the linked report provides a high-confidence reproduction of the existing enterprise Drive-sharing limitation rather than a current-main implementation bug in this branch.

Review metrics: 2 noteworthy metrics.

• Changed surface: 8 files, +274/-48. Production behavior is localized to one Docs command, while most added lines provide focused regression tests and generated documentation.
• Source modes: 1 added, 1 preserved. The new URL source is mutually exclusive with the established file-upload mode, limiting compatibility risk.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
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.

Next step before merge

• [P2] This active collaborator-authored PR has no concrete automated repair task; it is ready for ordinary maintainer review and merge judgment.

Security
Cleared: The patch introduces no dependency or workflow execution changes and rejects URLs with embedded credentials; no concrete security or supply-chain concern was found.

Review details

Best possible solution:

Merge the validated direct-HTTPS source path while retaining the existing local upload/share/revoke workflow and its output contract unchanged.

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

Not applicable as a feature PR; the linked report provides a high-confidence reproduction of the existing enterprise Drive-sharing limitation rather than a current-main implementation bug in this branch.

Is this the best way to solve the issue?

Yes. Passing a validated public HTTPS URI directly to the Docs API is the narrowest native solution and avoids introducing alternate Drive permission policies or persistent upload state.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P2: This is a bounded Docs workflow improvement that unblocks enterprise Workspace users affected by public-sharing restrictions.
• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body describes an after-fix run against a disposable real Google Doc and confirms the resulting URI and dimensions through live Docs API output.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body describes an after-fix run against a disposable real Google Doc and confirms the resulting URI and dimensions through live Docs API output.

Label justifications:

• P2: This is a bounded Docs workflow improvement that unblocks enterprise Workspace users affected by public-sharing restrictions.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body describes an after-fix run against a disposable real Google Doc and confirms the resulting URI and dimensions through live Docs API output.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body describes an after-fix run against a disposable real Google Doc and confirms the resulting URI and dimensions through live Docs API output.

Evidence reviewed

What I checked:

• Capability absent from current main: The current command requires --file and has no direct public-URL input, so the requested behavior is not already implemented on the default branch. (internal/cmd/docs_insert_image.go:24, 1cb9512e795b)
• Focused implementation: The branch validates mutually exclusive sources, requires credential-free HTTPS URLs, skips Drive service creation and sharing confirmation in URL mode, and preserves the existing file path. (internal/cmd/docs_insert_image.go:55, fbef6e7e68e0)
• Regression coverage: New tests cover missing or conflicting sources, invalid URLs, upload-only flags, Drive-service avoidance, output shape, and preservation of the file-upload path. (internal/cmd/docs_insert_image_test.go:13, fbef6e7e68e0)
• Concrete user need: The linked issue documents a reproducible publishOutNotPermitted failure in enterprise Workspace tenants and explicitly identifies direct public URLs as the preferred native Docs API workaround.
• Live provider proof: The PR body reports successful insertion into a disposable real Google Doc and verification through docs raw that the stored source URI and 96-by-96 point dimensions matched the request. (fbef6e7e68e0)
• Feature provenance: History and shortlog inspection show Peter Steinberger as the primary contributor to the current Docs command surface and insert-image implementation. (internal/cmd/docs_insert_image.go:1, 1cb9512e795b)

Likely related people:

• steipete: Peter Steinberger is the dominant contributor in the current Docs command history and authored the existing and proposed insert-image behavior. (role: feature owner and recent area contributor; confidence: high; commits: 71a8504d0add, fbef6e7e68e0; files: internal/cmd/docs_insert_image.go, internal/cmd/docs.go)
• sebsnyk: Sebastian Roth has prior merged Docs-area contributions and supplied the detailed enterprise sharing-policy reproduction that defines the required behavior. (role: adjacent Docs contributor and original reporter; confidence: medium; files: internal/cmd/docs.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.