feat: `gog docs insert-image` — upload + embed local image into a Google Doc

[sebsnyk]

Problem

There is no first-class gog command to embed a local image into a Google Doc.

Today the workflow for a markdown-to-Docs pipeline looks like:

1. Pre-process the markdown to extract ![alt](relative.png) references and replace each with a unique text placeholder.
2. gog docs write --replace --markdown (the placeholder survives the write).
3. gog drive upload <local.png> --parent <folderId> — gog covers this nicely.
4. gog drive share <fileId> --to anyone --role reader — gog covers this too.
5. Call raw Docs API documents.batchUpdate with insertInlineImage ← no gog equivalent.
6. gog drive unshare <fileId> <permId> — gog covers this.

Step 5 forces every consumer to import google-api-python-client (or equivalent) and re-implement: walk the doc body, find placeholder ranges, sort descending, then issue deleteContentRange + insertInlineImage batchUpdates.

Proposal

gog docs insert-image <docId> --file <localPath> [--at <placeholder|anchor>] [--width 540pt] [--alt 'text']

Semantics:

• Upload the image to a Drive folder of the caller's choosing (default: a sibling <doc-name>-images folder).
• Issue documents.batchUpdate with insertInlineImage at the requested anchor.
• Anchor resolution options:
  • --at <placeholder-string> — replace literal text matches (most useful for markdown pre-processing pipelines).
  • --at end — append at end of document.
  • --at heading=h.<id> — insert after a named heading (matches the anchor-link resolution gog already does in docs write).
• Handle the public-permission dance internally: temporarily share, embed, revoke. Caller doesn't have to think about it.

Workspace-policy fallback

Some Google Workspaces forbid anyone sharing (publishOutNotPermitted). In that case insertInlineImage will fail because Google's image fetcher needs anonymous access.

Suggested behaviour when public sharing is blocked:

• Detect the publishOutNotPermitted error and surface it clearly.
• Optional --on-restricted=link fallback: replace the placeholder with a clickable Drive link to the uploaded image, so the user can manually Insert > Image > Drive in the editor. Today every consumer reinvents this same fallback.

Related

• v0.19 added the markdown-conversion + page-size + margins primitives (docs write --pageless: also widen pageSize.width (or add --page-width flag) #629, docs write / page-layout: --margin-left, --margin-right, --margin-top, --margin-bottom #630, Drive markdown converter renders empty header row for '| | |' tables instead of dropping it #632, Drive markdown converter: resolve [text](#slug) to heading IDs instead of leaving raw fragment #633). insert-image is the natural next building block for image-bearing documents.
• Touches docs (insert) and drive (upload + share/unshare) — sits cleanly on top of existing surface.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed May 27, 2026, 11:52 AM ET / 15:52 UTC.

Summary
Keep open: current main still lacks a first-class gog docs insert-image command, and the existing Docs image paths either require public HTTPS URLs or expose upload/share/unshare as separate Drive commands. The request is useful but needs maintainer product and security review before implementation because it would automate public sharing, revocation, and restricted-workspace fallback behavior.

Reproducibility: not applicable. as a bug reproduction: this is a feature request. Source and generated docs give a high-confidence check that gog docs insert-image is absent and local image insertion still errors unless the image is already public HTTPS.

Ways to help us reproduce this

• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
Needs maintainer product/API and security review before implementation because it adds a cross Docs/Drive command with public-sharing and restricted-workspace semantics.

Security
Needs attention: The issue is security-sensitive because it proposes automated temporary public Drive sharing for local user files; no patch is under review yet.

Review details

Best possible solution:

Design a maintainer-approved docs insert-image primitive that composes existing Docs placeholder insertion with Drive upload/share/unshare helpers, has explicit safety behavior for public permissions and cleanup, and includes focused unit tests plus live Google proof.

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

Not applicable as a bug reproduction: this is a feature request. Source and generated docs give a high-confidence check that gog docs insert-image is absent and local image insertion still errors unless the image is already public HTTPS.

Is this the best way to solve the issue?

Unclear until maintainers choose the command contract. A narrow implementation should reuse existing Docs image insertion and Drive upload/share primitives, but the public-permission dance and restricted-workspace fallback need product and security review first.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Automating temporary public Drive sharing could expose local images if confirmation, dry-run output, failure cleanup, or permission revocation semantics are not designed and live-tested carefully.
• The proposed restricted-workspace fallback and anchor modes are product/API choices, not a mechanical bug fix, and need maintainer agreement before a fix PR is safe.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 9987f8b2f053.

Label changes

Label changes:

• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.
• add clawsweeper:needs-security-review: Current issue advisory state selects this label.

Label justifications:

• P2: This is a normal-priority feature in supported Docs/Drive areas with clear user value but limited immediate blast radius.
• impact:security: The requested command would automate public Drive sharing and revocation of user-provided local images, so permission safety is central to the issue.

Evidence reviewed

Security concerns:

• [medium] Define public-sharing cleanup semantics before implementation
  A future implementation must make temporary anyone sharing explicit, revoke permissions reliably on success and failure, and handle restricted Workspace policies without silently exposing or losing user data.
  Confidence: 0.87

Acceptance criteria:

• go test ./internal/cmd
• GOG_IT_ACCOUNT=you@gmail.com go test -tags=integration ./internal/integration

What I checked:

• Repository policy read: AGENTS.md was read in full; it confirms this review should stay read-only and that stdout/stderr and testing conventions matter for any future implementation. (AGENTS.md:1, 9987f8b2f053)
• No Docs insert-image command on current main: The Docs command registry includes create/write/insert/insert-table/insert-page-break/find-replace/sed/raw/page-layout, but no insert-image subcommand. (internal/cmd/docs.go:20, 9987f8b2f053)
• Generated command docs also lack insert-image: The generated gog docs command index lists the current Docs subcommands and does not include gog docs insert-image. (docs/commands/gog-docs.md:17, 9987f8b2f053)
• Existing Docs image insertion rejects local files: The current Markdown image insertion helper resolves remote URLs but returns an actionable error for local image paths because Docs InsertInlineImage needs a publicly accessible URL. (internal/cmd/docs_import.go:217, 9987f8b2f053)
• Current implementation can insert remote images only: The helper builds InsertInlineImage requests from resolved URLs after placeholder replacement, which covers public URL insertion but not local upload/share/revoke orchestration. (internal/cmd/docs_import.go:380, 9987f8b2f053)
• Regression coverage documents the local-image gap: The current test suite expects docs write --replace --markdown with a local image to fail with a local-image/public-HTTPS error. (internal/cmd/docs_write_markdown_test.go:438, 9987f8b2f053)

Likely related people:

• Peter Steinberger: Git blame/log in this checkout maps the Docs command registry, Docs image insertion/rejection helper, and Drive upload/share commands to the v0.19.0 release commit authored by Peter Steinberger; shallow/grafted history limits finer provenance. (role: recent area contributor; confidence: medium; commits: b25a3c029b37; files: internal/cmd/docs.go, internal/cmd/docs_import.go, internal/cmd/drive_upload.go)
• vinothd-oai: CHANGELOG.md credits @vinothd-oai for adjacent Docs Markdown image behavior covering remote image sizing and the current local-path error, which is directly related to this request. (role: historical adjacent contributor; confidence: low; commits: b25a3c029b37; files: CHANGELOG.md, internal/cmd/docs_import.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.