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 changes before merge. Reviewed May 28, 2026, 5:50 PM ET / 21:50 UTC.

Summary
The PR adds docs update --markdown, --replace-range, tab-aware insertion/replacement plumbing, generated command docs, gog skill docs, and focused command tests.

Reproducibility: yes. Source inspection shows the markdown range helper sends delete, insert, and formatting requests, while DocsUpdateCmd.Run reports a hard-coded count of 2 for that path.

Review metrics: 1 noteworthy metric.

• User-facing flags: 2 added. The PR expands the docs update CLI surface, so maintainers should review help text, docs, and output behavior together.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🐚 platinum hermit
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

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

Rank-up moves:

• [P2] Fix request-count reporting for markdown range replacement and add a focused output assertion.

Risk before merge

• [P1] Until fixed, scripts reading requests from --json or plain output receive misleading telemetry for formatted markdown range replacements.

Maintainer options:

1. Decide the mitigation before merge
   Land the feature after markdown range replacement derives its request count from the actual batch requests and covers that output with a focused assertion.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] A narrow automated repair can make markdown range replacement report its actual batch request count and add an output assertion.

Security
Cleared: The diff adds CLI/docs/test logic only and does not introduce a concrete security or supply-chain concern.

Review findings

• [P2] Report the actual markdown replace request count — internal/cmd/docs_edit.go:639

Review details

Best possible solution:

Land the feature after markdown range replacement derives its request count from the actual batch requests and covers that output with a focused assertion.

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

Yes. Source inspection shows the markdown range helper sends delete, insert, and formatting requests, while DocsUpdateCmd.Run reports a hard-coded count of 2 for that path.

Is this the best way to solve the issue?

No. The feature direction is maintainable, but the implementation should return or compute the actual markdown replace batch request count instead of hard-coding it.

Full review comments:

• [P2] Report the actual markdown replace request count — internal/cmd/docs_edit.go:639
  For docs update --markdown --replace-range, replaceDocsMarkdownRange sends the delete, insert, and every formatting request in one batch, and the focused heading/bold/link case produces more than two requests. This line still hard-codes requestCount = 2, so --json and plain output under-report formatted markdown replacements. Return the helper's actual request count and assert it in the focused tests.
  Confidence: 0.94

Overall correctness: patch is incorrect
Overall confidence: 0.88

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
• add status: 🛠️ actively grinding: The PR author has acted after the latest ClawSweeper review and work remains. Sufficient (live_output): The PR body and follow-up comment report live temporary Google Doc smoke tests for the changed insertion and range replacement paths with raw Docs readback verification.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 👀 ready for maintainer look: Current PR status label is status: 🛠️ actively grinding.

Label justifications:

• P2: This is a useful user-facing Docs CLI improvement with one bounded output correctness blocker.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
• status: 🛠️ actively grinding: The PR author has acted after the latest ClawSweeper review and work remains. Sufficient (live_output): The PR body and follow-up comment report live temporary Google Doc smoke tests for the changed insertion and range replacement paths with raw Docs readback verification.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body and follow-up comment report live temporary Google Doc smoke tests for the changed insertion and range replacement paths with raw Docs readback verification.

Evidence reviewed

Acceptance criteria:

• [P1] go test ./internal/cmd -run 'TestDocsUpdate_(MarkdownWithTab|ReplaceRangePlainWithTab|ReplaceRangeMarkdownWithTab)|TestDocsWriteUpdate_JSON'.
• [P1] git diff --check 9987f8b...HEAD.

What I checked:

• Repository policy read: Full AGENTS.md was read; its guidance to keep stdout parseable informed the output-contract review. (AGENTS.md:1, 929e26b4a999)
• Current main lacks this docs update surface: On current main, DocsUpdateCmd is the existing plain insertion command and does not define --markdown or --replace-range; the same code traces to the v0.19.0 release commit. (internal/cmd/docs_edit.go:523, b25a3c029b37)
• PR adds the requested feature surface: The PR diff adds two user-facing docs update flags, tab-aware range replacement behavior, docs regeneration, and tests across 9 files. (internal/cmd/docs_edit.go:523, 67925f03f3f3)
• Remaining request-count defect: PR head hard-codes requestCount = 2 after markdown range replacement, while replaceDocsMarkdownRange builds delete, insert, and all formatting requests before sending the batch. (internal/cmd/docs_edit.go:639, 67925f03f3f3)
• Focused test exercises formatted markdown path: The markdown range replacement test uses heading, bold, and link markdown and verifies the outgoing batch requests, which makes the under-reported request count source-reproducible. (internal/cmd/docs_write_update_test.go:248, 67925f03f3f3)
• Contributor proof: The PR body and follow-up comment report focused tests, make test, and live temporary Google Doc smoke tests for markdown tab insertion and plain/markdown range replacement with raw Docs readback showing heading, bold, and link formatting. (67925f03f3f3)

Likely related people:

• steipete: Current-main blame and log history for the Docs update command, Docs markdown mutation helpers, and adjacent gog skill guidance point to Peter Steinberger's recent work in this area. (role: feature-history owner; confidence: medium; commits: b25a3c029b37, fe7eccd15e07; files: internal/cmd/docs_edit.go, internal/cmd/docs_mutation.go, .agents/skills/gog/SKILL.md)

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