feat(docs): cell-style — set tableCellStyle (backgroundColor) and inline textStyle (bold) on table cells

[sebsnyk]

Summary

gog docs exposes no way to apply visual formatting to specific table cells. The underlying Google Docs API does expose this via updateTableCellStyle (for cell-level properties like backgroundColor) and updateTextStyle (for inline run properties like bold). A wrapper would round out the doc-shaping surface alongside --page-width, --margin-*, table column-widths (#631), etc.

Use case

Tag-style badges in header tables of structured documents. For example: a header table where one row names a category and the value cell should carry a stable, consistent colour per category (pale background + bold text) so a reader can scan and immediately see which slice of the org a doc belongs to. Today this requires hand-styling via Drive UI on every doc — a per-doc tax that scales badly.

Proposed surface

gog docs cell-style <docId> \
  --tab <title-or-id> \
  --table-index N            # 0-based ordinal among tables in the tab
  --row R --col C            # 0-based cell coordinate
  --background-color <#hex>  # optional; maps to tableCellStyle.backgroundColor
  --bold                     # optional; applies updateTextStyle bold=true to cell contents
  --italic --underline       # optional; same shape
  --text-color <#hex>        # optional; maps to textStyle.foregroundColor

A range form would be nice for badge bars: --row 0 --col 0:3 styles three adjacent cells.

Underlying API

• documents.batchUpdate → updateTableCellStyle with tableCellStyle.backgroundColor.color.rgbColor and tableRange / tableCellLocation
• documents.batchUpdate → updateTextStyle with textStyle.bold / .italic / .underline / .foregroundColor and a content range spanning the cell

Workaround today

Drive UI styling (manual, doesn't survive find-replace round-trips). No CLI path.

Related

• Feature: table column-width control (FIXED_WIDTH per column, or evenly distributed) #631 (table column widths) — same theme: table styling primitives exposed via flags rather than markdown.
• feat(docs): add insert-table primitive — direct table insertion without the markdown path #602 (table insertion primitive) — direct-API path bypassing markdown.

[clawsweeper]

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

Summary
Keep open: current main has text styling and table-cell addressing through existing Docs commands, but it still lacks a coordinate-based table-cell style surface and any UpdateTableCellStyle path for cell background color.

Reproducibility: not applicable. as a bug reproduction: this is a feature request. Source inspection gives high confidence that current main lacks a cell-style command and any UpdateTableCellStyle implementation.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
A maintainer should decide the public command/API shape before a repair lane implements new Docs table-cell styling flags.

Review details

Best possible solution:

Add a maintainer-approved Docs table-cell styling primitive that reuses existing tab/color parsing, emits UpdateTableCellStyle for cell backgrounds plus UpdateTextStyle for cell text, and includes focused tests, docs, and 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 inspection gives high confidence that current main lacks a cell-style command and any UpdateTableCellStyle implementation.

Is this the best way to solve the issue?

Unclear until maintainers choose the command shape. The requested API mapping is plausible, but the narrowest maintainable solution could be a new command or an extension of docs format/docs sed.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The requested behavior overlaps existing docs format and docs sed text-styling surfaces, so maintainers should choose whether this belongs in a new docs cell-style command or as an extension of an existing Docs command.
• Live Google Docs proof will matter because tableCellStyle, tableRange, tabs, and cell text ranges are API-dependent behavior.

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

Label changes

Label changes:

• add P3: This is a useful but optional Docs formatting primitive with limited blast radius and no broken existing behavior.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: This is a useful but optional Docs formatting primitive with limited blast radius and no broken existing behavior.

Evidence reviewed

What I checked:

• Current Docs command surface: DocsCmd registers insert-table, format, and sed, but no cell-style or table-cell style command is present on current main. (internal/cmd/docs.go:20, 9987f8b2f053)
• Existing format command is text-range based: docs format exposes --text-color, --bg-color, --bold, and related flags, and builds UpdateTextStyle requests over text ranges rather than UpdateTableCellStyle over table cells. (internal/cmd/docs_format.go:25, 9987f8b2f053)
• Existing sed cell path styles text, not the cell object: docs sed can target table cells and apply text styles such as bold/background to inserted text, but the helper emits UpdateTextStyle and does not set tableCellStyle.backgroundColor. (internal/cmd/docs_sed_helpers.go:156, 9987f8b2f053)
• No table-cell style implementation found: A focused search found table-cell locations for row/column/table operations, but no UpdateTableCellStyle, TableCellStyle, or updateTableCellStyle implementation in code or docs. (9987f8b2f053)
• Feature-history provenance: Git history in this checkout attributes the current Docs command surface and existing Docs format/table paths to the v0.19.0 release commit, with no later Docs table-style implementation on main. (internal/cmd/docs.go:34, b25a3c029b37)
• Vision fit: VISION.md supports small useful primitives in already-supported areas such as Docs, but asks maintainers to discuss new API surfaces first. (VISION.md:13, 9987f8b2f053)

Likely related people:

• steipete: Current-main blame and file history attribute the existing Docs command registration, formatting flags, and table insertion surface to the v0.19.0 release commit authored by Peter Steinberger; history is shallow, so this is a routing signal rather than full provenance. (role: recent area contributor; confidence: medium; commits: b25a3c029b37; files: internal/cmd/docs.go, internal/cmd/docs_format.go, internal/cmd/docs_insert_table.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.