docs: document docs +fetch comment contract

[zhangheng023]

Summary

Add a Tips section to the docs +fetch affordance covering three implicit contracts that were implemented in #2341 but never surfaced outside shortcuts/doc and the skill reference: comments are always included in the response with no flag to disable it, XML marks commented content inline via a comment-refs attribute, and markdown/im-markdown surface comments only through reference_map.comments.

Changes

• Add ### Tips under ## +fetch in affordance/docs.md
• Sync the golden affordance test in content_embed_affordance_test.go that previously pinned +fetch to an empty Tips list

Test Plan

• make unit-test passed
• validate passed
• regression test: go test ./tests/cli_e2e/docs/... -run "TestDocsFetchCommentsFlagIsRemovedFromHelpAndRejected|TestDocsCommandsHideFormatHelpButKeepCompatibility|TestDocsFetchDryRun" passed
• manual verification: make build && ./lark-cli docs +fetch --help — confirms the two new Tips render correctly

Related Issues

N/A

Summary by CodeRabbit

• Documentation

  • Added guidance explaining how comments are included in +fetch responses.
  • Documented differences in how comments are represented in XML and Markdown formats.

• Tests

  • Updated validation to confirm the new +fetch documentation tips are present.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f1c3e4ec-e98b-4666-be1f-3eb44ace50cc

📥 Commits

Reviewing files that changed from the base of the PR and between 679ebd5 and 70ccaf4.

📒 Files selected for processing (2)

• affordance/docs.md
• content_embed_affordance_test.go

Included review availability: Your plan includes up to 10 reviews per rolling hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds +fetch documentation and test expectations for comment inclusion in reference_map.comments and format-specific inline comment references.

Changes

+fetch comment references

Layer / File(s)	Summary
Document +fetch comment behavior affordance/docs.md, content_embed_affordance_test.go	The documentation and test expectations state that comments are always returned in reference_map.comments. They also describe inline comment references in XML and their absence in Markdown.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to 70cca

This change documents existing docs +fetch comment behavior and updates its golden test; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: sunpeiyang996

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the documentation change for the docs +fetch comment contract.
Description check	✅ Passed	The description includes the required summary, changes, test plan, and related-issues sections with specific verification details.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/fetch-comment-help-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Quality Summary

CI did not complete successfully. Use the failed check links below to decide whether this PR needs a code change or a rerun.

Failed checks

• sidecar-integration — cancelled — details
• script-test — cancelled — details
• unit-test — cancelled — details
• deterministic-gate — cancelled — details
• coverage — cancelled — details
• plugin-integration — cancelled — details
• deadcode — cancelled — details
• lint — cancelled — details
• e2e-dry-run — cancelled — details
• e2e-live — cancelled — details
• results — failure — details

deterministic-gate

• System issue: deterministic-gate failed, but quality-gate facts were unavailable. expected exactly one base-bound quality gate facts artifact, got 0

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@70ccaf4f853aa2ee52ab727eab62f176b4b96605

🧩 Skill update

npx skills add larksuite/cli#docs/fetch-comment-help-contract -y -g

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.42%. Comparing base (679ebd5) to head (70ccaf4).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2382   +/-   ##
=======================================
  Coverage   76.42%   76.42%           
=======================================
  Files        1046     1046           
  Lines      115260   115260           
=======================================
  Hits        88082    88082           
  Misses      20401    20401           
  Partials     6777     6777           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.