feat(docs): add --code flag to docs format for monospace + grey background

[sebsnyk]

Motivation

gog already implements "code-styled run" — inline backticks in markdown render as Courier New + grey background (internal/cmd/docs_formatter.go), and gog docs sed 's/X/{#}X/' does the same (internal/cmd/docs_sed_brace_format.go). The same single semantic unit is not reachable from gog docs format.

Repro

gog docs format <DOC_ID> --match "ImportantClass" --font-family "Courier New" --bg-color "#EEEEEE"
# Works but is two flags and the user has to know the exact font + colour. Inconsistent with sed.

Proposed surface

gog docs format <docId> --match <text> --code [--match-all]

Behaviour: sets weightedFontFamily=Courier New (matching the existing markdown converter) plus the existing grey background in one UpdateTextStyle request. Mutually exclusive with --font-family and --bg-color to avoid surprise.

Acceptance criteria

• --code produces the same visual output as a markdown backtick run pushed via gog docs write --markdown.
• One batchUpdate request, identical to what gog docs sed '{#}' emits today.

References

• UpdateTextStyleRequest: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#UpdateTextStyleRequest

[clawsweeper]

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

Summary
Keep open: current main and v0.21.0 expose the two low-level docs format flags but not the requested --code shortcut, while existing sed brace formatting already has the requested Courier New plus grey background semantics.

Reproducibility: yes. from source inspection: DocsFormatFlags has no Code field or --code tag, and generated command docs also omit the flag. I did not run the CLI because this review is read-only.

Next step
This is a narrow, aligned feature request with clear implementation files and validation, but it is not a strict bug because it adds a new CLI flag.

Review details

Best possible solution:

Add a narrow --code flag to docs format that reuses the existing sed code-style constants, rejects conflicting --font-family or --bg-color, updates generated command docs, and validates the request shape plus live Docs rendering.

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

Yes from source inspection: DocsFormatFlags has no Code field or --code tag, and generated command docs also omit the flag. I did not run the CLI because this review is read-only.

Is this the best way to solve the issue?

Yes: adding the shortcut in DocsFormatFlags.buildTextStyleRequest is the narrowest maintainable path, as long as it mirrors sed {#} semantics and does not silently alter markdown behavior.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The issue's markdown-parity wording is mixed: current markdown inline code only sets Courier New, while sed {#} adds backgroundColor; a fix should explicitly target sed-style inline code and avoid changing markdown behavior unintentionally.
• A future PR should include live Google Docs proof before merge because unit tests can confirm request shape but not rendered Docs appearance.

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, not a regression or urgent workflow break.
• 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, not a regression or urgent workflow break.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd -run 'TestDocsFormat|TestBuildBraceTextStyleRequests|TestMarkdownToDocsRequests'
• Run the repository's command-doc generation path and confirm docs/commands/gog-docs-format.md documents --code.
• Live Google Docs proof before merge: apply gog docs format <docId> --match <text> --code to a test document and show the text renders as Courier New with grey background.

What I checked:

• Repository policy read: AGENTS.md was read fully; the review followed the repository's read-only PR/issue review guidance and CLI output expectations. (AGENTS.md:1, 3d5c9cef65fa)
• Vision fit: VISION.md says small useful primitives in already-supported Google Workspace areas fit the project, with tests and live Google proof when behavior depends on Google APIs. (VISION.md:1, 3d5c9cef65fa)
• Current docs format flags: DocsFormatFlags includes --font-family and --bg-color but has no Code field or --code Kong tag. (internal/cmd/docs_format.go:25, 3d5c9cef65fa)
• Current text-style builder: docs format builds weighted font family and background color only from separate fields, so the requested single semantic unit is not implemented on current main. (internal/cmd/docs_format.go:256, 3d5c9cef65fa)
• Generated command docs: The generated gog docs format flag table lists --bg-color and --font-family but no --code, matching the source surface. (docs/commands/gog-docs-format.md:23, 3d5c9cef65fa)
• Existing sed code semantic: Sed brace formatting already treats code as weightedFontFamily plus backgroundColor using Courier New and codeBackgroundGrey. (internal/cmd/docs_sed_brace_format.go:65, 3d5c9cef65fa)

Likely related people:

• Peter Steinberger: Blame, git log -S, and git shortlog show the current docs format flags, sed code-style helpers, and generated docs page coming from the v0.21.0 release commit. (role: introduced current Docs formatting surface; confidence: medium; commits: 2c84d8981dd5; files: internal/cmd/docs_format.go, internal/cmd/docs_sed_helpers.go, internal/cmd/docs_sed_brace_format.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.