---
name: truetime
description: Ensure real-time accurate scheduling and planning across UTC, server time, NTP-sourced time, user local time, and arbitrary time zones. Use for timers, reminders, cron planning, in X minutes or months or years calculations, absolute timestamp conversion, Chinese lunar date awareness, and cross-timezone coordination. Enforce exact duration fidelity so user values are never replaced by example values, compute target times in UTC first, and verify deltas before execution.
---

# TrueTime

Use this skill to avoid time mistakes caused by stale examples, wrong units, timezone drift, or DST confusion.

## Non-Negotiable Rules

- Treat user-provided duration values as authoritative.
- Never copy numeric values from examples into real execution.
- Read current time from the runtime clock before calculating.
- Compute canonical target time in UTC first.
- Convert for display second (server timezone, user timezone, other timezone).
- Ask for clarification when timezone context is missing and outcome can change.

## Required Workflow

1. Extract timing intent exactly.
   - Capture literal phrase, value, unit, timezone hint, and target date/time.
   - Keep the original requested value unchanged (for example `1 minute` stays `1 minute`).
2. Read current real time.
   - Use the bundled script for deterministic calculations:
     - Relative: `node {baseDir}/scripts/true_time.mjs --plus 1m --user-tz Asia/Shanghai`
     - Relative (calendar units): `node {baseDir}/scripts/true_time.mjs --plus 1month2weeks --user-tz America/New_York --calendar-tz America/New_York`
     - Absolute: `node {baseDir}/scripts/true_time.mjs --target 2026-02-17T09:30:00 --target-tz Asia/Shanghai --user-tz America/Los_Angeles`
     - NTP time source: `node {baseDir}/scripts/true_time.mjs --plus 1h --time-source ntp`
3. Parse the expression into one precise delta or one precise absolute timestamp.
4. Compute UTC target first.
5. Convert UTC target to server/user/other requested timezone for presentation.
6. Verify the result before execution.
   - Confirm `target_utc - now_utc` equals requested delta.
   - Confirm timezone offset conversion is consistent.
7. Execute schedules using UTC unless the target scheduler explicitly needs local timezone.
8. Report both absolute and relative interpretation in the final response.

## Relative Time Guardrails

- Accept explicit units only:
  - milliseconds: `ms`, `msec`, `msecs`, `millisecond`, `milliseconds`
  - seconds: `s`, `sec`, `second`, `seconds`
  - minutes: `m`, `min`, `minute`, `minutes`
  - hours: `h`, `hr`, `hour`, `hours`
  - days: `d`, `day`, `days`
  - weeks: `w`, `week`, `weeks`
  - months: `mo`, `mon`, `month`, `months`
  - years: `y`, `yr`, `year`, `years`
  - decades: `decade`, `decades`
  - centuries: `century`, `centuries`
- Reject ambiguous units instead of guessing.
- All units support decimal values, including calendar units.
  - Examples: `1.5m`, `0.25h`, `2.5day`, `250.5ms`, `1.5month`, `0.1year`, `0.5decade`, `0.01century`.
  - Decimal separator `.` is preferred; `,` is accepted as input and normalized.
- Fixed-unit decimals are computed to millisecond precision.
- Calendar-unit policy:
  - `month/year/decade/century` are calendar-aware, not fixed seconds.
  - Calendar arithmetic uses `--calendar-tz` (fallback: user timezone -> server timezone).
  - Decimal calendar values are split into integer and fractional parts.
  - Integer months use calendar shift; fractional months use the shifted month length to compute milliseconds.
  - End-of-month handling clamps to the last valid day (for example Jan 31 + 1 month -> Feb 28/29).
- Keep verification examples explicit:
  - `1.5m = 90s`
  - `250ms = 0.25s`
  - `1m = 60s`
  - `1h30m = 5400s`
  - `2d = 172800s`
  - `1.5year = 18 months`
  - `1decade = 10 years`
  - `0.5decade = 5 years`
  - `1century = 100 years`
  - `0.01century = 1 year`

## Absolute Time Guardrails

- Prefer IANA timezone names (`Asia/Shanghai`, `America/Los_Angeles`, `UTC`).
- Avoid ambiguous abbreviations (`CST`, `IST`) unless user confirms meaning.
- If user gives a naive datetime with no timezone, ask once or apply an explicit assumption.
- For DST transition windows, state that the chosen timezone rules were applied.

## Timezone Catalog and Customization

- List all available runtime timezones:
  - `node {baseDir}/scripts/true_time.mjs --list-timezones`
- Filter common choices quickly:
  - `node {baseDir}/scripts/true_time.mjs --list-timezones | rg -i '^(UTC|Asia/(Shanghai|Tokyo|Kolkata)|America/(Los_Angeles|New_York)|Europe/(London|Paris|Berlin))$'`
- User custom timezone:
  - Accept any valid IANA timezone from `--list-timezones`.
  - Pass user timezone via `--user-tz <IANA>`.
  - If user timezone is unknown, ask before executing time-sensitive actions.

Common timezones to use in examples and user-facing confirmations:

- `UTC` (no DST)
- `Asia/Shanghai` (Beijing time, UTC+08:00, no DST)
- `Asia/Tokyo` (Tokyo time, UTC+09:00, no DST)
- `Asia/Kolkata` (India time, UTC+05:30, no DST)
- `America/Los_Angeles` (US West: PST UTC-08:00 / PDT UTC-07:00, DST applies)
- `America/New_York` (US East: EST UTC-05:00 / EDT UTC-04:00, DST applies)
- `America/Chicago` (US Central: CST UTC-06:00 / CDT UTC-05:00, DST applies)
- `America/Denver` (US Mountain: MST UTC-07:00 / MDT UTC-06:00, DST applies)
- `America/Phoenix` (Arizona: MST UTC-07:00, typically no DST)
- `America/Anchorage` (Alaska: AKST UTC-09:00 / AKDT UTC-08:00, DST applies)
- `Pacific/Honolulu` (Hawaii: HST UTC-10:00, no DST)
- `Europe/London` (UK: GMT UTC+00:00 / BST UTC+01:00, DST applies)
- `Europe/Paris` (CET UTC+01:00 / CEST UTC+02:00, DST applies)
- `Europe/Berlin` (CET UTC+01:00 / CEST UTC+02:00, DST applies)
- `Europe/Amsterdam` (CET UTC+01:00 / CEST UTC+02:00, DST applies)

## DST and Standard-Time Rules

- Never assume fixed offsets for DST regions (`America/*`, many `Europe/*`).
- Always compute with the actual target date, not "current offset."
- For DST fall-back overlaps (ambiguous local time), require explicit offset:
  - `2026-11-01T01:30:00` in `America/Los_Angeles` is ambiguous.
  - Ask user to choose `-07:00` (before fallback) or `-08:00` (after fallback), or provide explicit offset in `--target`.
- For DST spring-forward gaps (invalid local time), require correction:
  - `2026-03-08T02:30:00` in `America/Los_Angeles` does not exist.
  - Ask user to use a valid local time (for example `01:30` or `03:30`).
- Prefer explicit-offset absolute targets when DST risk is high:
  - `--target 2026-11-01T01:30:00-07:00`
  - `--target 2026-11-01T01:30:00-08:00`

## Chinese Lunar Calendar

- This tool outputs Chinese lunar datetime fields by default:
  - `lunar_timezone` (default `Asia/Shanghai`, configurable via `--lunar-tz`)
  - `now_lunar`
  - `target_lunar`
- Use these fields when the user asks for Chinese lunar context.
- For execution/scheduling, still use Gregorian UTC fields as canonical.
- If a user gives only lunar date text and no Gregorian equivalent, ask for confirmation or a Gregorian target before execution.

## Time Source Policy (Server vs NTP)

- Default time source is server clock (`--time-source server`).
- If user explicitly requests "do not use server time", switch to public NTP:
  - `--time-source ntp`
- Optional NTP controls:
  - `--ntp-server <host>` (repeatable or comma-separated)
  - `--ntp-timeout-ms <ms>`
- NTP mode example:
  - `node {baseDir}/scripts/true_time.mjs --plus 30m --time-source ntp --ntp-server time.google.com`
- If all NTP servers fail, stop and report failure instead of silently falling back to server time.

## Mandatory Integration Points

Use TrueTime calculations before any of the following:

- Cron operations (`cron add`, `cron update`, `cron wake`, `cron run`) when time or schedule is involved.
- Calendar operations (create/update events, convert invite times, multi-timezone meeting planning).
- Reminder operations (in X minutes/hours, tomorrow at HH:mm, next weekday, repeating reminders).
- Planning tasks that include ETA, deadline conversion, or cross-timezone commitments.

## Server Execution Policy

- Persist canonical time as UTC (`target_utc_iso` and optionally epoch seconds).
- Include human-facing fields for user timezone and server timezone.
- If the scheduler supports timezone-aware execution, pass timezone explicitly.
- If the scheduler only accepts UTC, keep execution in UTC and show converted local preview.
- Runtime note: this skill's helper script uses Node (`node .../true_time.mjs`).
- Sandbox note: default `openclaw-sandbox:bookworm-slim` may not include Node; use `openclaw-sandbox-common:bookworm-slim` or install Node in `agents.defaults.sandbox.docker.setupCommand`.

## High-Frequency Examples

Relative calculations:

- Beijing time, 1 minute later:
  - `node {baseDir}/scripts/true_time.mjs --plus 1m --user-tz Asia/Shanghai`
- Beijing time, 1.5 minutes later:
  - `node {baseDir}/scripts/true_time.mjs --plus 1.5m --user-tz Asia/Shanghai`
- Tokyo time, 250.5 milliseconds later:
  - `node {baseDir}/scripts/true_time.mjs --plus 250.5ms --user-tz Asia/Tokyo`
- Tokyo time, 90 minutes later:
  - `node {baseDir}/scripts/true_time.mjs --plus 1h30m --user-tz Asia/Tokyo`
- US West time, 2 hours later:
  - `node {baseDir}/scripts/true_time.mjs --plus 2h --user-tz America/Los_Angeles`
- US East time, 45 minutes later:
  - `node {baseDir}/scripts/true_time.mjs --plus 45m --user-tz America/New_York`
- India time, 1 day later:
  - `node {baseDir}/scripts/true_time.mjs --plus 1d --user-tz Asia/Kolkata`
- US Central, 1 month later:
  - `node {baseDir}/scripts/true_time.mjs --plus 1month --user-tz America/Chicago --calendar-tz America/Chicago`
- US Central, 1.5 months later:
  - `node {baseDir}/scripts/true_time.mjs --plus 1.5month --user-tz America/Chicago --calendar-tz America/Chicago`
- US Mountain, 1 year later:
  - `node {baseDir}/scripts/true_time.mjs --plus 1year --user-tz America/Denver --calendar-tz America/Denver`
- US Mountain, 0.1 years later:
  - `node {baseDir}/scripts/true_time.mjs --plus 0.1year --user-tz America/Denver --calendar-tz America/Denver`
- Hawaii, 1 decade later:
  - `node {baseDir}/scripts/true_time.mjs --plus 1decade --user-tz Pacific/Honolulu --calendar-tz Pacific/Honolulu`
- Hawaii, 0.5 decades later:
  - `node {baseDir}/scripts/true_time.mjs --plus 0.5decade --user-tz Pacific/Honolulu --calendar-tz Pacific/Honolulu`
- UTC, 1 century later:
  - `node {baseDir}/scripts/true_time.mjs --plus 1century --user-tz UTC --calendar-tz UTC`
- UTC, 0.01 centuries later:
  - `node {baseDir}/scripts/true_time.mjs --plus 0.01century --user-tz UTC --calendar-tz UTC`

Absolute and cross-timezone calculations:

- Beijing local absolute time:
  - `node {baseDir}/scripts/true_time.mjs --target 2026-02-18T09:00:00 --target-tz Asia/Shanghai --user-tz Asia/Shanghai`
- London meeting shown to US East:
  - `node {baseDir}/scripts/true_time.mjs --target 2026-05-20T14:00:00 --target-tz Europe/London --user-tz America/New_York`
- UTC target shown to Europe/Berlin:
  - `node {baseDir}/scripts/true_time.mjs --target 2026-04-15T16:00:00Z --user-tz Europe/Berlin`
- DST ambiguity resolved by explicit offset:
  - `node {baseDir}/scripts/true_time.mjs --target 2026-11-01T01:30:00-07:00 --user-tz America/Los_Angeles`
  - `node {baseDir}/scripts/true_time.mjs --target 2026-11-01T01:30:00-08:00 --user-tz America/Los_Angeles`
- NTP-based reminder time:
  - `node {baseDir}/scripts/true_time.mjs --plus 15m --time-source ntp --user-tz Asia/Shanghai`

## Output Contract

When sending or scheduling time-sensitive actions, always include:

- `now_utc`
- `target_utc`
- `target_user_tz` (if known)
- `target_server_tz`
- `delta_milliseconds`
- `delta_seconds`
- `time_source` (server | ntp | override)
- `ntp_server` (when `time_source=ntp`)
- `now_lunar`
- `target_lunar`
- assumptions (if any)

Do not continue with execution when any required field is unknown and may change the target time materially.