fix(docs): preserve text-run hyperlink URLs

[clawsweeper]

Summary

• detect external TextRun.TextStyle.Link.Url values in the existing rendered-text traversal
• keep default docs cat and --plain text unchanged
• render linked text through the opt-in --chips path and expose additive structured link metadata in JSON
• avoid rendering [url](url) when visible text already equals the destination
• cover paragraph links, table-cell links, unlinked text, mixed links and smart chips, escaping, JSON output, and backward-compatible default output

Scope

This intentionally covers external URL links on ordinary text runs. Heading and bookmark links remain out of scope. Smart-chip behavior, raw output, Docs export behavior, and unrelated formatting remain unchanged.

Validation

• go test ./internal/cmd
• make ci

Closes #917

Related: #907 and #909

Thanks @neo-wanderer for the focused reproduction and @TurboTheTurtle for the adjacent smart-chip rendering foundation.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 13, 2026, 8:52 PM ET / July 14, 2026, 00:52 UTC.

Summary
The PR detects external URLs on Google Docs text runs, renders them through the existing opt-in --chips path, and adds structured JSON link metadata with focused regression tests.

Reproducibility: yes. at source level: current main appends ordinary text-run content without preserving TextStyle.Link.Url, and the linked issue provides a concrete docs cat reproduction across output modes. I did not independently run a live Google Docs setup, so this is source-reproducible rather than runtime-reproduced.

Review metrics: 3 noteworthy metrics.

• Patch surface: 3 files changed. The behavior change stays concentrated in the Docs reader, focused command tests, and one small constant extraction.
• Diff size: 190 additions, 18 deletions. Most added lines are regression fixtures and assertions rather than a broad production refactor.
• Validation: 11 successful check runs. The exact PR head passed cross-platform build/test and supply-chain reporting checks.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #917
Summary: This PR is the focused candidate fix for the canonical text-run hyperlink-loss issue; the smart-chip reports and PR are adjacent foundation work rather than duplicates.

Members:

• canonical: docs cat drops hyperlink URLs on text runs in all output modes (plain, --plain, --chips, --json); readable only via --raw #917 - The PR explicitly closes this issue and implements its requested external text-run URL behavior.
• adjacent_distinct: docs cat drops person smart chips from all output modes (plain, --plain, --json); readable only via --raw #907 - That issue concerned non-text smart-chip elements rather than external URLs attached to ordinary text runs.
• adjacent_distinct: Support Docs smart chips in cat output #909 - That PR established smart-chip rendering and metadata but did not preserve ordinary text-run hyperlinks.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

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.

Next step before merge

• [P2] No repair job is needed; keep this clean PR open for ordinary maintainer merge review.

Security
Cleared: The diff only changes Docs output traversal, tests, and a local constant, with no dependency, workflow, secret, download, permission, or code-execution changes.

Review details

Best possible solution:

Merge the focused traversal extension and its regression tests so --chips and JSON preserve external text-run URLs while default and --plain output remain backward-compatible.

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

Yes at source level: current main appends ordinary text-run content without preserving TextStyle.Link.Url, and the linked issue provides a concrete docs cat reproduction across output modes. I did not independently run a live Google Docs setup, so this is source-reproducible rather than runtime-reproduced.

Is this the best way to solve the issue?

Yes; extending the existing opt-in rendered traversal and additive JSON sidecar is the narrowest maintainable fix and avoids breaking default or --plain consumers.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P2: This fixes bounded but misleading URL information loss in the Docs read path without changing default output.
• 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. Not applicable: The external-contributor proof gate does not apply to this bot-generated PR; focused regression tests and successful checks provide supplemental validation.

Evidence reviewed

What I checked:

• Current-main gap: The current Docs rendered-text traversal handles text-run content but does not preserve TextRun.TextStyle.Link.Url, matching the linked issue’s source-level reproduction. (internal/cmd/docs_read.go:414, e4239f8c57a5)
• Focused implementation: The PR extends the existing rendered-text result with link metadata and threads link collection through document, tab, paragraph, and table traversal rather than adding a competing output path. (internal/cmd/docs_read.go:323, 478f5b46c1ca)
• Compatibility coverage: Regression tests cover paragraph and table-cell links, mixed links and smart chips, escaping, JSON metadata, URL-equals-text behavior, and unchanged default and --plain output. (internal/cmd/docs_commands_test.go:386, 478f5b46c1ca)
• Validation state: All reported GitHub checks completed successfully, including test, Windows, Darwin CGO build, image, worker, and Socket Security checks. (478f5b46c1ca)
• Adjacent feature provenance: The linked smart-chip work in Support Docs smart chips in cat output #909 established the opt-in rendering and structured metadata pattern that this PR extends to ordinary text-run hyperlinks. (internal/cmd/docs_read.go:323, 00f47e4c2717)
• Repository policy: The full root AGENTS.md was read and its guidance on focused changes, parseable output, unit tests, and read-only PR review was applied. (AGENTS.md:1, e4239f8c57a5)

Likely related people:

• TurboTheTurtle: Their earlier smart-chip cat-output work introduced the rendering and metadata pattern directly extended by this PR. (role: adjacent feature contributor; confidence: high; commits: 00f47e4c2717; files: internal/cmd/docs_read.go, internal/cmd/docs_commands_test.go)
• steipete: The adjacent smart-chip behavior shipped in the v0.34.0 release they published, making them a likely routing candidate for compatibility and release acceptance. (role: release owner and recent Docs area contributor; confidence: medium; commits: 836378754862; files: internal/cmd/docs_read.go, CHANGELOG.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.

Review history (2 earlier review cycles)

• reviewed 2026-07-14T00:34:25.842Z sha 478f5b4 :: passed. :: none
• reviewed 2026-07-14T00:42:35.028Z sha 478f5b4 :: passed. :: none

[clawsweeper]

🦞🧹
ClawSweeper autofix is enabled.

• Head: 478f5b46c1ca
• Label: clawsweeper:autofix
• Action: exact-head review queued (workflow sweep.yml, event repository_dispatch).
• Flow: review this head, repair/rebase only if needed, then re-review the exact repaired head until no actionable findings remain.

This is fix-only; I will not merge this PR.

Re-review progress:

• State: Complete
• Detail: The targeted re-review published an exact durable review comment and queued an executing target-wide serialized router scan.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/29296477687
• Updated: 2026-07-14T00:44:37.660Z

[clawsweeper]

🦞✅
ClawSweeper autofix is complete for this exact head.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=478f5b46c1ca648f1c400dc78b3d3f38de01ecb1)
Head: 478f5b46c1ca

No actionable findings remain. I removed the repair-loop label and left the PR open for maintainer review and merge.

Automerge progress:

• 2026-07-14 00:44:18 UTC review passed 478f5b46c1ca (structured ClawSweeper verdict: pass (sha=478f5b46c1ca648f1c400dc78b3d3f38de01e...)