feat(docs): add --link and --no-link to docs format

[sebsnyk]

Motivation

gog docs format --match "X" --bold --italic works today; the missing --link <url> is the same shape (UpdateTextStyle with textStyle.link, fields=link). The brace DSL in gog docs sed ({u=https://...}) covers it, but users discovering format first reasonably expect a flag.

Verified against current source: DocsFormatFlags in internal/cmd/docs_format.go enumerates bold/italic/underline/strike/font-family/font-size/text-color/bg-color/alignment/line-spacing/heading-level/named-style — no link.

Repro

# Today, no --link on format:
gog docs format <DOC_ID> --match "click here" --link "https://example.com"
# error: unknown long flag '--link'

# Workaround:
gog docs sed <DOC_ID> 's/click here/{u=https:\/\/example.com}click here/'
# Works but requires escaping forward slashes; awkward for URLs.

Proposed surface

gog docs format <docId> --match <text> [--match-all] [--match-case]
  --link <url>     Wrap match in a hyperlink. Accepts http://, https://, mailto:, #bookmarkId, #headingId
  --no-link        Remove any existing hyperlink on the match range

Acceptance criteria

• --link https://... emits one UpdateTextStyle request with textStyle.link.url and fields=link.
• --link #heading-slug resolves the slug against doc headings (same code path as the existing [text](#slug) markdown anchor resolver, Drive markdown converter: resolve [text](#slug) to heading IDs instead of leaving raw fragment #633) and writes textStyle.link.headingId.
• --link mailto:foo@bar.com writes a mailto link (separate from the Person-chip path).
• --no-link clears the link by setting textStyle.link=null and fields=link.
• --link and --no-link are mutually exclusive.

References

• UpdateTextStyleRequest + TextStyle.link: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#UpdateTextStyleRequest
• Link shape (url / bookmarkId / headingId): https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#Link

[clawsweeper]

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

Summary
Keep open: current main and the latest release do not expose --link or --no-link on gog docs format, and this is a small in-scope Docs command primitive with existing link-handling patterns nearby.

Reproducibility: yes. from source inspection: DocsFormatFlags and the generated command docs lack --link and --no-link, so the reported flag surface is absent on current main.

Next step
Source confirms a narrow missing Docs command flag surface with existing local link-handling patterns and no linked implementation PR in the provided context.

Review details

Best possible solution:

Add focused docs format link/no-link flags that reuse existing Docs link request patterns and slug-to-heading resolution where applicable.

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

Yes from source inspection: DocsFormatFlags and the generated command docs lack --link and --no-link, so the reported flag surface is absent on current main.

Is this the best way to solve the issue?

Yes: adding link/no-link to docs format is the narrowest maintainable solution if it reuses the existing UpdateTextStyle link patterns and markdown heading resolver rather than creating a separate link system.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3d5c9cef65fa.

Label changes

Label changes:

• add P3: This is a low-risk ergonomics feature for an existing Docs command with a working docs sed workaround.
• add impact:other: The issue affects CLI usability for applying Google Docs hyperlinks, which is meaningful but outside the specific owned impact categories.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk ergonomics feature for an existing Docs command with a working docs sed workaround.
• impact:other: The issue affects CLI usability for applying Google Docs hyperlinks, which is meaningful but outside the specific owned impact categories.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd -run 'TestDocsFormat|TestDocsWrite_MarkdownHeadingLinks|TestBuildBraceTextStyleRequests' -count=1
• make docs-commands
• make test

What I checked:

• Repository policy read: AGENTS.md was read fully and its CLI-output/testing guidance was applied to the work-lane recommendation. (AGENTS.md:1, 3d5c9cef65fa)
• Vision fit: VISION.md allows small useful primitives in already-supported Google Workspace areas, including Docs commands. (VISION.md:8, 3d5c9cef65fa)
• Docs format flags lack link support: DocsFormatFlags includes font, color, boolean style, alignment, spacing, and heading/named-style fields, but no link or no-link field. (internal/cmd/docs_format.go:25, 3d5c9cef65fa)
• Generated command docs lack link flags: The generated gog docs format flag table lists current user-facing flags and does not include --link or --no-link. (docs/commands/gog-docs-format.md:17, 3d5c9cef65fa)
• Existing sed link pattern: The sed brace formatter already emits UpdateTextStyle requests with TextStyle.Link and Fields: link for {u=...} expressions. (internal/cmd/docs_sed_brace_format.go:97, 3d5c9cef65fa)
• Existing heading-link resolver: Markdown heading-link rewriting maps heading slugs to Docs heading IDs and emits TextStyle.Link.HeadingId with Fields: link. (internal/cmd/docs_markdown_links.go:28, 3d5c9cef65fa)

Likely related people:

• Peter Steinberger: Introduced the docs format command, added markdown heading-link improvements, and authored the current release snapshot containing these files. (role: introduced behavior and recent area contributor; confidence: high; commits: b4d6f559c399, b26e19003ebd, 2c84d8981dd5; files: internal/cmd/docs_format.go, internal/cmd/docs_markdown_links.go, docs/commands/gog-docs-format.md)
• chrischall: Extended docs format with heading/named-style support in the same request-building path. (role: recent docs-format contributor; confidence: medium; commits: dff8bb00c37e; files: internal/cmd/docs_format.go, internal/cmd/docs_format_headings_test.go)
• Vinston: Introduced the sedmat DSL and tests that currently provide the hyperlink workaround via {u=...}. (role: adjacent feature introducer; confidence: medium; commits: e2d41ad87c56, 2853ff564ee3; files: internal/cmd/docs_sed_brace_format.go, internal/cmd/docs_sed_brace_format_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.

[steipete]

Fixed in cfddf881e38055013e983243f4b53535dc0849b6.

What changed:

• docs format --link now sets textStyle.link for URL and mailto targets.
• --link #heading-slug resolves the slug through the existing markdown heading-link resolver path and writes a Docs heading link.
• --link #h.* writes a heading ID link; other #... targets remain bookmark links.
• --no-link clears the link by sending textStyle.link: null with fields=link.
• --link and --no-link are mutually exclusive.

Proof:

• go test ./internal/cmd -run 'TestDocsFormat|TestRewriteMarkdownHeadingLinks|TestDocsWrite_MarkdownHeadingLinks|TestBuildBraceTextStyleRequests' -count=1
• make docs-commands
• make ci
• autoreview --mode uncommitted --base origin/main: clean, no accepted/actionable findings

Live Docs smoke was not run: this shell cannot unlock the file keyring non-interactively, and GOG_KEYRING_PASSWORD is unset.

Thanks @sebsnyk.