docs(calendar): warn against container-default timezone in time conversion

[calendar-assistant]

Summary

Calendar events created via the raw calendar events create/patch API showed a consistent 8-hour offset. When a shortcut cannot express a field (e.g. location, custom reminders), agents drop down to the raw API, which takes Unix-second timestamps. Agents then convert wall-clock time themselves, and in UTC containers this silently produces an 8-hour offset (e.g. Beijing 11:00 becomes 19:00). This PR strengthens the skill docs to steer agents onto the timezone-safe path and warn about the raw-API conversion pitfall. Docs-only, no code changes.

Changes

• SKILL.md: fold a timezone warning into the existing mandatory time-conversion note — conversion must not rely on the container default timezone (often UTC → 8-hour offset) and must specify the target timezone explicitly.
• references/lark-calendar-create.md: require --start/--end to carry an explicit timezone offset (offsets omitted are parsed in the process timezone and drift); add the same raw-API timestamp-conversion warning.
• references/lark-calendar-update.md: apply the identical --start/--end and raw-API timestamp warnings for consistency.

Test Plan

• Docs-only change; verified rendering and wording in the three skill files
• Unit tests pass (no code touched)

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Strengthened timezone guidance for calendar date/time conversions, explicitly disallowing reliance on the container’s default timezone.
  • Updated calendar +create docs to require ISO 8601 timestamps with explicit timezone offsets for --start and --end, noting missing offsets may shift times.
  • Expanded calendar event.attendees create and full API calendar +update usage notes to require explicit target timezone handling when converting Unix seconds.

[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: 764944c7-53e9-4e7f-aae5-bde40eebdecb

📥 Commits

Reviewing files that changed from the base of the PR and between 515e82e and 68ec21e.

📒 Files selected for processing (3)

• skills/lark-calendar/SKILL.md
• skills/lark-calendar/references/lark-calendar-create.md
• skills/lark-calendar/references/lark-calendar-update.md

🚧 Files skipped from review as they are similar to previous changes (3)

• skills/lark-calendar/SKILL.md
• skills/lark-calendar/references/lark-calendar-update.md
• skills/lark-calendar/references/lark-calendar-create.md

---

📝 Walkthrough

Walkthrough

Calendar documentation now requires explicit timezone offsets for command timestamps and explicit target timezones when converting Unix seconds, including warnings against relying on container defaults.

Changes

Calendar timezone guidance

Layer / File(s)	Summary
Timezone conversion policy skills/lark-calendar/SKILL.md, skills/lark-calendar/references/lark-calendar-create.md, skills/lark-calendar/references/lark-calendar-update.md	Mandatory guidance and full API examples prohibit default-timezone conversions and require an explicit target timezone.
Calendar command time inputs skills/lark-calendar/references/lark-calendar-create.md, skills/lark-calendar/references/lark-calendar-update.md	Create and update parameters require ISO 8601 start and end values with explicit timezone offsets.

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

Suggested reviewers: hugang-lark

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main docs change about timezone-safe time conversion.
Description check	✅ Passed	The description matches the required template and includes summary, changes, test plan, and related issues.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/calendar-timezone-guidance

---

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 Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@68ec21e63bd89169e8cfe2bf0d80b5e7d935df24

🧩 Skill update

npx skills add larksuite/cli#docs/calendar-timezone-guidance -y -g

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.19%. Comparing base (358cd06) to head (68ec21e).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2104      +/-   ##
==========================================
+ Coverage   75.16%   75.19%   +0.03%     
==========================================
  Files         912      914       +2     
  Lines       96475    96783     +308     
==========================================
+ Hits        72517    72778     +261     
- Misses      18381    18407      +26     
- Partials     5577     5598      +21     

☔ 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.