# TimeFair Meeting Planner

> Find fair meeting times across time zones, with DST-exact local times and rotation. Enter participants with their IANA time zone and working hours. TimeFair scores every candidate slot by how far it falls outside each person’s working day (extra penalty at night), ranks slots by total and worst-case inconvenience, and builds a rotation plan for recurring meetings so the pain is shared. Exports an .ics calendar file.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://timefair.usefulweb.site/ (interactive tool at https://timefair.usefulweb.site/tool)
- JSON API: POST https://timefair.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://timefair.usefulweb.site/api/v1/tool)
- OpenAPI: https://timefair.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://timefair.usefulweb.site/mcp - tool `timefair`

## Inputs
- title (text): Meeting title
- participants (table, required): Participants - IANA time zone such as Europe/Berlin, America/New_York, Asia/Kolkata. Work end earlier than start means an overnight shift. The first participant is the organiser (date range uses their calendar).
- startDate (date): First day - In the organiser’s time zone. Defaults to today (UTC date).
- days (integer): Number of days
- durationMinutes (integer): Meeting length
- granularity (select): Slot granularity
- workdays (multiselect): Working days (local to each participant)
- recurrences (integer): Occurrences to rotate
- intervalDays (integer): Repeat every

## Method
- Time zones are IANA names validated with Intl.DateTimeFormat; every UTC↔local conversion uses the runtime’s tz database, so DST changes and +05:30 / +05:45 offsets are exact for each individual minute.
- Candidate slots start at the organiser’s local midnight of the first day and step by the chosen granularity (in UTC) until the last slot ends before midnight after the last day.
- Inconvenience per participant = weight × (minutes outside the working window + 2 × minutes outside the window between 22:00 and 07:00 local) ÷ 60, i.e. 1 point per hour outside working hours and 3 points per hour at night. A day that is not a working day counts entirely as outside.
- Overnight windows (end earlier than start) belong to the day they start on; e.g. 22:00–06:00 on a Friday covers Friday 22:00 to Saturday 06:00.
- Fairness cost of a slot = total + 1 × worst individual inconvenience + 0.5 × standard deviation (population). Lower is better; ties go to the earliest slot.
- Rotation (deterministic greedy): the 48 lowest-cost slots form the pool; each occurrence repeats the slot’s organiser-local wall time every N days, re-scored for that exact date (DST-aware). For each occurrence the slot minimising the worst cumulative burden, then the total cumulative burden, then its own cost, then start time, is picked.
- The .ics file uses UTC (Z) times, RFC 5545 escaping and 75-octet line folding; UID is a SHA-256 hash of the slot, participants and title (stable across re-imports); DTSTAMP is the computation time.