feat(docs): style fenced markdown code blocks

[TurboTheTurtle]

Summary

• Render fenced Markdown code blocks with Roboto Mono and dark-green text in the local Docs writer.
• Preserve existing paragraph shading and soft-line-break handling for fenced blocks.
• Update formatter, write, and find-replace tests.

Fixes #676.

Scope note

This intentionally covers the local Docs API renderer used by append, tab-replace, range update, and markdown find-replace paths. Whole-document docs write --replace --markdown still uses Drive import, so maintainers should decide whether that remains separate issue scope.

Validation

• make ci
• Exact-head GitHub Actions on 75df70592fb1f807dfc5cc38c099991ad1113aa1

Proof

Ran the exact branch binary against a disposable Google Doc using clawdbot@gmail.com. After appending a multiline fenced code block, docs raw readback returned:

• weightedFontFamily.fontFamily: Roboto Mono
• weightedFontFamily.weight: 400
• foreground color: #188038
• paragraph shading: #f2f2f2

The disposable document was moved to trash after verification.

[clawsweeper]

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

Summary
The PR changes locally rendered fenced Markdown blocks from Courier New with default text color to Roboto Mono with dark-green text, preserves existing shading and soft line breaks, and updates related tests and release notes.

Reproducibility: not applicable. as a conventional runtime failure: the linked report provides a concrete mode comparison, and exact-head live API readback verifies the proposed output.

Review metrics: 2 noteworthy metrics.

• Changed surface: 5 files, +72/-13. The patch is compact, but its sole production change affects a formatter shared by several Docs workflows.
• Style request: 2 explicit fields. Fenced blocks gain weighted font-family and foreground-color fields while preserving the existing paragraph-level shading request.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

• [P1] Existing append, range-update, tab-replace, cell-update, and Markdown find-replace users will receive a different fenced-code font and foreground color after upgrading.
• [P1] Whole-document Markdown replacement remains a separate Drive-import path, so the two rendering implementations can still diverge if Google changes its imported Markdown styling.

Maintainer options:

1. Approve the unified incremental style (recommended)
   Explicitly accept Roboto Mono and dark-green text as the new fenced-code output for every workflow using the shared local renderer.
2. Narrow the affected workflows
   Parameterize or split the formatter if append should align with replacement without changing range, tab, cell, or find-replace output.
3. Pause for a renderer policy decision
   Hold the PR if the observed Drive-import appearance should not define the local renderer's permanent visual contract.

Next step before merge

• [P2] A maintainer should explicitly accept the cross-caller visual compatibility change and then merge the already-correct patch without automated repair.

Security
Cleared: The diff changes formatter styling, tests, and release notes without touching dependencies, workflows, credentials, permissions, downloads, publishing, or other security-sensitive execution paths.

Review details

Best possible solution:

Adopt and document one fenced-code visual contract for all Markdown write modes, explicitly approve this shared incremental-renderer change, and retain the focused field-and-range regression coverage.

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

Not applicable as a conventional runtime failure: the linked report provides a concrete mode comparison, and exact-head live API readback verifies the proposed output.

Is this the best way to solve the issue?

Yes technically: updating the shared formatter is the narrowest maintainable implementation, provided maintainers explicitly accept the broader visual compatibility scope.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 7a289fe2cf70.

Label changes

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P3: This is a low-severity visual consistency improvement without data-loss, availability, or security impact.
• merge-risk: 🚨 compatibility: Merging intentionally changes established fenced-code appearance for all existing callers of the shared incremental renderer.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): Exact-head live Google Docs API readback demonstrates Roboto Mono, weight 400, dark-green foreground, and preserved paragraph shading after the change.
• proof: sufficient: Contributor real behavior proof is sufficient. Exact-head live Google Docs API readback demonstrates Roboto Mono, weight 400, dark-green foreground, and preserved paragraph shading after the change.

Evidence reviewed

What I checked:

• Implementation is focused: The fenced-code branch retains the existing text range, weight, soft-line-break handling, and paragraph shading while adding the desired font family and foreground color to the existing text-style request. (internal/cmd/docs_formatter.go:97, 75df70592fb1)
• Shared compatibility surface: MarkdownToDocsRequests is shared by mutation, write, cell-update, and Markdown find-replace paths, so the visual change intentionally applies beyond the append workflow described by the linked report. (internal/cmd/docs_mutation.go:138, 7a289fe2cf70)
• Regression coverage: The updated tests assert the exact style fields, RGB values, font weight, and UTF-16 ranges in formatter, append-write, and find-replace behavior. (internal/cmd/docs_formatter_test.go:372, 75df70592fb1)
• Feature provenance: Commit b646e88 introduced the current soft-line-break and shaded fenced-code behavior; this PR extends that established renderer rather than creating a parallel implementation. (internal/cmd/docs_formatter.go:97, b646e886f6dd)
• Real behavior proof: The exact-head branch was run against a disposable Google Doc, and live API readback showed Roboto Mono, weight 400, foreground #188038, and retained #f2f2f2 paragraph shading. (75df70592fb1)
• Read-only integrity: The checkout remained clean after the review. (7a289fe2cf70)

Likely related people:

• sebsnyk: Commit b646e88 introduced the native fenced-code paragraph, soft-line-break, and shading behavior that this PR extends. (role: introduced current fenced-code behavior; confidence: high; commits: b646e886f6dd; files: internal/cmd/docs_formatter.go, internal/cmd/docs_formatter_test.go, internal/cmd/docs_write_markdown_test.go)
• steipete: The current release-state formatter and exact reviewed PR head are authored by Peter Steinberger, making him the strongest routing candidate for the compatibility decision. (role: recent area contributor and merger; confidence: high; commits: 71a8504d0add, 75df70592fb1; files: internal/cmd/docs_formatter.go, CHANGELOG.md)
• goncaloalves: Commit 7945602 introduced the Docs update command and the original shared Markdown-to-Docs formatting path, including monospace code-block formatting. (role: introduced Docs Markdown formatter path; confidence: medium; commits: 7945602f1526; files: internal/cmd/docs_formatter.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.

[TurboTheTurtle]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27259562492
• Updated: 2026-06-10T07:15:04.329Z

[TurboTheTurtle]

@clawsweeper re-review

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27255835799
• Updated: 2026-06-10T05:47:20.970Z

[TurboTheTurtle]

Sanitized proof for this PR:

• PR head tested: 00bab20
• GitHub checks are green: test, image, worker, windows, and darwin-cgo-build
• Focused local tests passed:

go test -v ./internal/cmd -run 'TestMarkdownToDocsRequests_AppendBulletsAndCode|TestDocsWrite_MarkdownAppendUsesDocsFormatting|TestDocsWrite_MarkdownAppendStartsStyledBlocksOnFreshParagraph' -count=1

• Additional local raw request proof for a fenced Markdown code block:

{"fields":"weightedFontFamily,foregroundColor","fontFamily":"Roboto Mono","fontWeight":400,"range":{"startIndex":1,"endIndex":19},"rgbHex":"#188038"}

This verifies the generated Docs API text-style request for fenced Markdown code blocks includes Roboto Mono and #188038.

[TurboTheTurtle]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27323318257
• Updated: 2026-06-11T04:14:27.872Z