feat(calendar): add --timezone flag to event create

[malob]

Summary

calendar create requires --start-timezone and --end-timezone to be set
separately to label an event's start/end with a named IANA zone. This adds a
single --timezone/--tz flag that applies one zone to both endpoints.

• --timezone <IANA> / --tz <IANA> sets the timezone on both --from and --to.
• Mutually exclusive with --start-timezone/--end-timezone — passing it
  alongside either is a usage error (the granular flags remain for the
  asymmetric case).
• Mirrors the existing --timezone/--tz flag on calendar create-calendar.
• Invalid-zone / all-day errors are attributed to the flag the user actually set.

This flag is specific to calendar create. calendar update could gain the same
convenience later, but its timezone handling is more involved — it depends on
which of --from/--to is being changed — so it's intentionally left out of
scope here.

Why

For most events the start and end are in the same timezone — wanting different
zones for each is the unusual case. Setting that single zone today means
repeating it across both --start-timezone and --end-timezone, which is fiddly
and easy to get half-right (one set, the other forgotten). --timezone collapses
the common case to one flag and removes that easy mistake, while the
mutual-exclusivity check keeps the rarer split-zone case explicit.

Behavior proof

Live round-trip against a real account (account/event id redacted; throwaway
event deleted afterward). Both endpoints persist the named zone, and the event
is gone after delete:

$ ./bin/gog calendar create primary --summary "tz flag test" \
    --from 2026-08-13T13:40:00-07:00 --to 2026-08-13T14:40:00-07:00 \
    --timezone America/Los_Angeles --send-updates none --account <redacted> --json
# created — event id <event-id>

# read it back (start/end excerpt of the --json event) — both carry the named zone:
$ ./bin/gog calendar event primary <event-id> --account <redacted> --json
  "start": { "dateTime": "2026-08-13T13:40:00-07:00", "timeZone": "America/Los_Angeles" },
  "end":   { "dateTime": "2026-08-13T14:40:00-07:00", "timeZone": "America/Los_Angeles" },

$ ./bin/gog calendar delete primary <event-id> --force --send-updates none --account <redacted> --json
{"calendarId":"primary","deleted":true,"eventId":"<event-id>"}

# confirm gone (soft-deleted):
$ ./bin/gog calendar event primary <event-id> --account <redacted> --json
  "status": "cancelled"

Testing

• make fmt-check, make lint, make docs-check clean; regenerated the command
  reference with make docs-commands.
• go test ./internal/cmd -run 'UnifiedTimezone|ResolveUnifiedTimezone' — covers
  set-both, the conflict error (exit 2), and invalid-zone/all-day error attribution.

Compatibility

Additive and non-breaking — --timezone is new and existing
--start-timezone/--end-timezone usage is unchanged. Kong scopes the --tz
alias per command, so there's no collision with create-calendar.

No CHANGELOG.md entry — left to the release/landing process per repo convention.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 19, 2026, 3:10 AM ET / 07:10 UTC.

Summary
Adds calendar create --timezone/--tz to apply one IANA timezone to both event endpoints, with mutual-exclusion validation, command docs, tests, and an unreleased changelog note.

Reproducibility: not applicable. as a bug reproduction: this PR adds a convenience flag rather than fixing broken documented behavior. Source inspection confirms current main lacks the flag, and the PR body/tests demonstrate the new behavior.

Review metrics: 3 noteworthy metrics.

• CLI surface: 1 flag, 1 alias added. The main maintainer-visible change is a new scriptable calendar create convenience surface.
• Changed scope: 8 files, +189/-3. The PR spans command plumbing, tests, generated command docs, spec docs, and an unreleased changelog note.
• Real behavior proof: 1 redacted live round trip. The proof directly exercises the Google Calendar create/read/delete path that the new flag is meant to simplify.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
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 automated repair is needed; maintainers can handle this through normal review and merge checks.

Security
Cleared: The diff only changes calendar CLI plumbing, tests, generated/user docs, and changelog text; no concrete security or supply-chain concern is visible.

Review details

Best possible solution:

Land the focused additive flag if maintainers want this calendar-create convenience, while keeping granular start/end timezone flags for asymmetric zones.

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

Not applicable as a bug reproduction: this PR adds a convenience flag rather than fixing broken documented behavior. Source inspection confirms current main lacks the flag, and the PR body/tests demonstrate the new behavior.

Is this the best way to solve the issue?

Yes technically: the patch reuses the existing event DateTime timezone validation path, leaves granular flags intact, and adds focused coverage. The remaining decision is product acceptance of the new flag surface, with a maintainer-authored changelog entry already providing positive signal.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P3: This is a low-blast-radius additive calendar CLI convenience feature with tests, docs, and live proof, not an urgent regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes redacted copied live output showing create, read-back, delete, and cancelled read-back with both endpoint time zones set after creation.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted copied live output showing create, read-back, delete, and cancelled read-back with both endpoint time zones set after creation.

Evidence reviewed

What I checked:

• Repository policy read: Read the full target AGENTS.md and applied its PR-review guidance by inspecting the PR with gh without switching branches or editing the checkout. (AGENTS.md:1, c172741709aa)
• Current main lacks unified flag: On current main, CalendarCreateCmd exposes only --start-timezone and --end-timezone for event creation; no --timezone/--tz field exists there. (internal/cmd/calendar_edit.go:23, c172741709aa)
• Current main routes granular flags separately: Current main builds event start and end DateTime values from separate start/end timezone inputs, so the set-both behavior is not already implemented. (internal/cmd/calendar_event_plan.go:361, c172741709aa)
• Latest release also lacks unified flag: The v0.28.0 release commit has only the granular event-create timezone flags, so this PR is not obsolete due to a shipped implementation. (internal/cmd/calendar_edit.go:23, 6bc67d7dd770)
• PR adds the requested CLI surface: The PR head adds Timezone string with name:"timezone" aliases:"tz" to CalendarCreateCmd and passes it into the create input. (internal/cmd/calendar_edit.go:25, c28d11423656)
• PR reuses existing timezone validation path: The PR resolves the unified flag before calling buildEventDateTimeWithTimezone, preserving the existing validation and all-day rejection path with adjusted flag attribution. (internal/cmd/calendar_event_plan.go:362, c28d11423656)

Likely related people:

• steipete: Current blame for the event-create command and timezone builder paths points to the v0.28.0 release work by Peter Steinberger, and the PR head also includes his changelog commit for this feature. (role: recent area contributor; confidence: high; commits: 6bc67d7dd770, 28d9e9873a4e, c28d11423656; files: internal/cmd/calendar_edit.go, internal/cmd/calendar_event_plan.go, internal/cmd/calendar_build.go)
• salmonumbrella: Repository history shows multiple earlier calendar event and timezone-related changes in the same central create/update and builder area. (role: adjacent calendar/timezone contributor; confidence: medium; commits: bc6d342e6095, f3a957a1bc1d, 4f29d8e25000; files: internal/cmd/calendar_edit.go, internal/cmd/calendar_event_plan.go, internal/cmd/calendar_build.go)
• visionik: The merged recurring EventDateTime timezone fix introduced earlier timezone behavior in the same builder family this PR extends. (role: timezone behavior introducer; confidence: medium; commits: 6ec670d0df47; files: internal/cmd/calendar_build.go)
• alexknowshtml: The merged secondary-calendar creation work added the existing --timezone/--tz command pattern that this PR mirrors. (role: adjacent feature contributor; confidence: medium; commits: db3a32432cfc; files: internal/cmd/calendar_create_calendar.go, docs/spec.md, docs/commands/gog-calendar-create-calendar.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.

[malob]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[steipete]

Landed after maintainer review and exact-head validation.

• Local: focused timezone tests and full make ci passed.
• Review: autoreview clean; no accepted/actionable findings.
• Live: reviewed the recorded create/read/delete proof showing both event endpoints persisted Europe/London.
• CI: exact-head CI and Docker runs passed on Linux, Windows, macOS/cgo, and the worker job.
• Caveat: maintainer live rerun could not access this machine's encrypted file keyring noninteractively, so the recorded live proof remains the API-level evidence.