docs: add Timezones section to README - #2
Merged
Merged
Conversation
All wall-clock times (--at, --remind, deadlines, short-syntax times) are parsed in the process's local timezone via naive strptime().timestamp(). Document how to detect a host/SP-client timezone mismatch, the per-invocation TZ= fix for the CLI, and the env-based fix for the sp-mcp server (MCP clients filter TZ out of the subprocess environment). Includes related gotchas: schedule without --remind clears remindAt, display commands render in the process timezone, repeat configs are unaffected (interpreted by the app). Closes #1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1
What
Adds a Timezones section to the README (between "Utility" and "Write safety") covering:
--at,--remindoffsets, deadline times and short-syntax times (@friday 15:00) are parsed in the process's local timezone (TZenv var) via naivestrptime().timestamp()— not UTC, not the SP client's timezone. A host/client timezone mismatch shifts every scheduled task and reminder.timedatectl/cat /etc/timezone— headless hosts are very often UTC.TZ=Europe/Belgrade ./sp schedule ...TZ) — setenv: TZ:in the client's server config; requires an agent restart since MCP servers spawn at startup.sp schedulewithout--remindsilently clearsremindAt(re-arm with--remind 0m— bites during TZ-fix reschedules); display commands render timestamps in the process timezone (a correct file looks wrong on a UTC host); repeatstartTimeis interpreted by the app, unaffected by host TZ.Verification
Written from a real incident: headless host in
Etc/UTC, SP clients inEurope/Belgrade— tasks scheduled as "20:00" showed up as 22:00 in the app. Fixes were verified live: per-invocationTZ=reschedule produced correctdueWithTimeunix-ms values (checked in the raw sync file), and the MCPenv.TZfix was confirmed by creating a test task through the MCP tool and checking its timestamp (UTC 13:00 = BGD 15:00, as intended).