feat(docs): support markdown in docs update

[rel]

Summary

• add a --markdown flag to docs update so inserted content can use the existing Docs markdown renderer
• support tab-scoped markdown insertion through the existing insertDocsMarkdownAt path
• regenerate docs command reference and add test coverage for markdown updates in tabs

Testing

• go test ./internal/cmd -run 'TestDocsUpdate_MarkdownWithTab|TestDocsWriteUpdate_JSON|TestDocsWrite_MarkdownReplaceWithTab|TestDocsFindReplace_MarkdownWithImage'
• make test
• live smoke test: created a temporary Google Doc, added a Data tab, ran docs update --markdown --tab Data, verified heading/bold/link/bullets in the raw tab content, then trashed the temp doc

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed May 30, 2026, 5:18 PM ET / 21:18 UTC.

Summary
The branch adds docs update --markdown and --replace-range, wires them through tab-aware Docs mutation paths, updates generated command and gog skill docs, and adds command tests.

Reproducibility: not applicable. as a feature PR rather than a bug report; source inspection confirms current main lacks the requested flags and the PR adds focused test coverage for the new paths.

Review metrics: 3 noteworthy metrics.

• CLI surface: 2 flags added. --markdown and --replace-range are new user-facing docs update behavior that maintainers should review as command API.
• Patch size: 10 files, +389/-37. The implementation is bounded but spans command code, generated docs, skill docs, changelog, and tests.
• Focused tests: 3 command tests added. The new tests cover tab-scoped markdown insertion, plain range replacement, and markdown range replacement including output telemetry.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

• none.

Next step before merge

• No repair lane is needed; the previous request-count blocker is fixed and the PR is ready for normal maintainer review and CI gating.

Security
Cleared: No concrete security or supply-chain concern found; the diff does not change dependencies, workflows, credential handling, OAuth scopes, or package execution paths.

Review details

Best possible solution:

Land the narrow Docs update surface once normal CI and maintainer review are satisfied, keeping the explicit UTF-16 range documentation so callers understand the sharp replacement primitive.

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

Not applicable as a feature PR rather than a bug report; source inspection confirms current main lacks the requested flags and the PR adds focused test coverage for the new paths.

Is this the best way to solve the issue?

Yes; reusing the existing markdown renderer and adding delete-plus-insert range replacement inside docs update is a narrow, maintainable fit for the requested command surface.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A tab-aware markdown insert and range-replacement primitive closes a practical Docs automation gap by avoiding global find-replace for precise formatted edits.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body and follow-up comment report live smoke tests on a temporary Google Doc/tab with raw Docs readback showing the inserted and range-replaced formatting.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
• remove status: 🛠️ actively grinding: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

• P2: This is a normal-priority Docs CLI feature with useful automation value and limited blast radius because existing defaults are preserved.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A tab-aware markdown insert and range-replacement primitive closes a practical Docs automation gap by avoiding global find-replace for precise formatted edits.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body and follow-up comment report live smoke tests on a temporary Google Doc/tab with raw Docs readback showing the inserted and range-replaced formatting.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body and follow-up comment report live smoke tests on a temporary Google Doc/tab with raw Docs readback showing the inserted and range-replaced formatting.

Evidence reviewed

What I checked:

• AGENTS.md policy read: The repository policy was read in full; its PR-review guidance and parseable-output guidance were relevant to this review. (AGENTS.md:35, b77da7ff559f)
• Current main lacks the requested CLI surface: On current main, DocsUpdateCmd only supports text/file/index/pageless/tab and always sends a plain InsertText request, so this PR is not obsolete on main. (internal/cmd/docs_edit.go:523, b77da7ff559f)
• PR implements markdown insert and range replacement: At the PR head, DocsUpdateCmd adds ReplaceRange and Markdown, parses START:END, routes markdown insertion/replacement through the existing markdown Docs helpers, and reports the new output fields. (internal/cmd/docs_edit.go:524, 0a6d325bd3a6)
• Previous request-count finding is repaired: The markdown range replacement helper now returns the actual initial batch request count, and the focused test asserts JSON requests equals the captured batch request length. (internal/cmd/docs_write_update_test.go:312, 0a6d325bd3a6)
• Discussion-driven scope: The PR discussion requested the matching --replace-range primitive; the contributor then added plain and markdown range replacement and reported focused, full-suite, and live smoke validation in the comments. (001a1f9025c6)
• Diff hygiene: Whitespace checking for the PR range reported no problems. (0a6d325bd3a6)

Likely related people:

• steipete: Authored much of the current Docs mutation/markdown history and the PR-head fixups for request-count reporting and lint cleanup. (role: current docs mutation area owner and recent PR fixup author; confidence: high; commits: c38fbb35921d, b04824169665, cf9c5150c0a2; files: internal/cmd/docs_edit.go, internal/cmd/docs_mutation.go, internal/cmd/docs_helpers.go)
• sebsnyk: Authored the current tab-scoped markdown replacement work and requested the range-replacement primitive in this PR discussion. (role: adjacent markdown tab contributor and discussion reviewer; confidence: high; commits: 58b866e9ac55, b646e886f6dd; files: internal/cmd/docs_edit.go, internal/cmd/docs_mutation.go)
• chrischall: Authored insert-table and markdown table offset fixes that are relevant because the markdown insertion/replacement helper can emit native table operations. (role: adjacent markdown table contributor; confidence: medium; commits: 3a1b15592f47, 97fcd480faa4, de3fd390d465; files: internal/cmd/docs_insert_table.go, internal/cmd/docs_mutation.go, internal/cmd/docs_write_update_test.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.

[clawsweeper]

ClawSweeper PR egg

✨ Hatched: 🥚 common Frosted Crabkin

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

• Merged PRs are hatchable.
• Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
• Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: watches the merge queue.
Image traits: location diff observatory; accessory tiny test log scroll; palette moonlit blue and soft silver; mood proud; pose guarding a tiny green check; shell translucent glimmer shell; lighting soft underwater shimmer; background delicate sparkle particles.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Frosted Crabkin in ClawSweeper.

What is this egg doing here?

• Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
• The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
• Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
• The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
• Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

[sebsnyk]

Really nice direction — docs update --markdown is the surgical-insert primitive that's been missing. While you're in this corner of the code, would you consider adding the matching --replace-range flag on the same command? Today gog has clean insert but no clean replace — the only options are find-replace (text-matching, has shown destructive side effects near tables and link runs) or whole-doc/tab --replace. A range-based replace would close the loop.

Proposed surface:

gog docs update <id> --markdown --replace-range START:END --file body.md

Semantics: delete content in [START, END), then render the markdown into that slot — one batchUpdate, atomic. The caller resolves the range by walking documents.get (paragraph/cell/heading boundary lookup); gog stays out of "what to replace" and only does "how to replace it cleanly".

Why it pairs with --markdown:

• Same code path you've added (insertDocsMarkdownAt) plus a deleteContentRange request prepended when the flag is set.
• Lets callers do cell-content updates, paragraph rewrites, or any byte-range surgery without falling back to find-replace.
• Composes with --tab the same way the insert path does.

Use cases (the ones I keep hitting):

• Rewriting a single PRD-header cell value (e.g. Status: Draft → Published) without touching neighbouring cells or comment anchors.
• Replacing an existing paragraph identified by its index range — for docs with extensive comments where find-replace is now untrustworthy.
• It's also the primitive a future cell-update command would be built on (see feat(docs): cell-update — non-destructive content replacement inside a specific table cell #646).

Happy to test on a live doc once it lands. Thanks again for picking this up.

[rel]

Added this in 001a1f9. The updated PR now supports both plain and markdown range replacement on docs update:

gog docs update <id> --replace-range START:END --text replacement
gog docs update <id> --markdown --replace-range START:END --file body.md

Semantics are the proposed low-level primitive: callers provide the UTF-16 Docs API range; gog deletes that range and inserts the replacement at START. It composes with --tab by resolving the tab title/ID to a tabId before issuing requests.

Validation run:

• focused tests: go test ./internal/cmd -run "TestDocsUpdate_(MarkdownWithTab|ReplaceRangePlainWithTab|ReplaceRangeMarkdownWithTab)|TestDocsWriteUpdate_JSON"
• full cmd tests: go test ./internal/cmd
• full suite: make test
• live smoke test: created a temporary Google Doc, added a Data tab, ran plain --replace-range, then markdown --replace-range; raw Docs readback showed HEADING_2, bold, and link formatting; temp doc deleted.

[rel]

Also updated the repo-local agent skill docs in .agents/skills/gog/SKILL.md (commit 67925f0) so future agents know about:

• docs write --markdown --replace --tab for whole-tab formatted writes
• docs update --markdown --tab for formatted insertion/append
• docs update --replace-range START:END for precise plain replacement
• docs update --markdown --replace-range START:END for precise formatted replacement