---
name: datetime
description: >
  Timezone queries: current time in any city or timezone, time conversion between
  zones, UTC offset, and DST status. Trigger phrases: "what time is it in",
  "convert time", "timezone", "time difference", "DST".
---

# Datetime & Timezone Queries

Answer timezone-related questions using the server's `<datetime>` context and Node.js `Intl.DateTimeFormat` for cross-zone lookups.

## When to Activate

- User asks for the current time in a named city or timezone
- User asks to convert a time between timezones
- User asks about UTC offset, time difference, or DST status for a location
- User asks "what time is it?" with a location qualifier

For simple "what time is it?" without a location, answer directly from the `<datetime>` block in the system prompt — no tool use needed.

## Behaviour

Use Bash to run a Node.js one-liner with `Intl.DateTimeFormat`. The IANA timezone database is built into Node.js — no external packages are required.

### Current time in a timezone

```bash
node -e "console.log(new Intl.DateTimeFormat('en-GB', { weekday:'long', year:'numeric', month:'long', day:'numeric', hour:'2-digit', minute:'2-digit', second:'2-digit', timeZone:'IANA_TZ', timeZoneName:'longOffset' }).format(new Date()))"
```

Replace `IANA_TZ` with the target timezone identifier (e.g., `America/New_York`, `Asia/Tokyo`, `Europe/Berlin`).

### Time conversion

To convert a specific time from one zone to another, construct a `Date` object for the source time and format it in the target zone:

```bash
node -e "
const d = new Date('ISO_DATETIME');
const fmt = (tz) => new Intl.DateTimeFormat('en-GB', { weekday:'long', year:'numeric', month:'long', day:'numeric', hour:'2-digit', minute:'2-digit', timeZone:tz, timeZoneName:'short' }).format(d);
console.log(fmt('SOURCE_TZ'));
console.log(fmt('TARGET_TZ'));
"
```

### DST and offset info

```bash
node -e "
const now = new Date();
const opts = { timeZone:'IANA_TZ', timeZoneName:'longOffset' };
const parts = new Intl.DateTimeFormat('en-GB', opts).formatToParts(now);
const offset = parts.find(p => p.type === 'timeZoneName')?.value ?? 'unknown';
// Check DST by comparing Jan and Jul offsets
const jan = new Date(now.getFullYear(), 0, 1);
const jul = new Date(now.getFullYear(), 6, 1);
const janOff = new Intl.DateTimeFormat('en-GB', opts).formatToParts(jan).find(p => p.type === 'timeZoneName')?.value;
const julOff = new Intl.DateTimeFormat('en-GB', opts).formatToParts(jul).find(p => p.type === 'timeZoneName')?.value;
const dstActive = janOff !== julOff;
const inDst = dstActive && offset !== janOff;
console.log('Current offset:', offset);
console.log('DST observed:', dstActive);
console.log('Currently in DST:', inDst);
"
```

## Common City-to-Timezone Mapping

When the user names a city, map it to the IANA identifier:
- London → `Europe/London`
- New York → `America/New_York`
- Los Angeles → `America/Los_Angeles`
- Tokyo → `Asia/Tokyo`
- Sydney → `Australia/Sydney`
- Dubai → `Asia/Dubai`
- Mumbai / Delhi → `Asia/Kolkata`
- Berlin / Paris → `Europe/Berlin` / `Europe/Paris`
- Singapore → `Asia/Singapore`
- Hong Kong → `Asia/Hong_Kong`

For less common cities, use Bash to search the IANA database:
```bash
node -e "console.log(Intl.supportedValuesOf('timeZone').filter(z => z.toLowerCase().includes('SEARCH_TERM'.toLowerCase())).join('\n'))"
```

## Boundaries

- Answers timezone questions only — not scheduling, reminders, or alarms.
- Uses the server's system clock. If the server clock is wrong, answers will be wrong.
- Historical timezone data (e.g., "what time was it in Tokyo on 15 March 1990?") depends on the Node.js ICU dataset and may be inaccurate for dates before 1970.
