@northguild/gmt 1.18.0 → 1.20.0

package/skills/gmt-timezone/SKILL.md

@@ -1,27 +1,25 @@
 ---
 name: gmt-timezone
 description: >
-  Timezone-aware operations — zoned now, formatting zoned values/ranges,
-  plain↔zoned↔UTC↔Unix conversion, DST disambiguation on construction and
-  arithmetic, the instant-plus-offset pair, classifyLocal/resolveLocal, real
-  unit boundaries (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a
-  local day, floorToZone/bucketRange, calendar-annotated zoned strings, range
-  limits, transport legs (transitTime, etaAtZone, dwellTime, crossingTime,
-  scheduleDelivery), cut-offs (cutoffAt, cutoffSchedule, isPastCutoff,
-  timeToCutoff), planned versus actual (scheduleDeviation, classifyPunctuality,
-  punctualityRate, bestAvailable and estimateDrift over PLN/EST/REQ/ACT,
-  nextDeparture), intermodal free time (freeTimeExpiry, chargeableDays,
-  demurrageClock), billingTimeline, and operating hours (OperatingSchedule,
-  recurringWindows, operatingIntervals, isOpenAt, nextOpenAt, nextCloseAt,
-  operatingTimeBetween, addOperatingTime), and daylight time
-  (isInDaylightSaving, hasDaylightSaving). Points to the README and JSDoc.
+  Timezone-aware operations — zoned now, zoned formatting, plain↔zoned↔UTC↔Unix
+  conversion, DST disambiguation, toOffsetInstant, classifyLocal/resolveLocal,
+  classifyStoredZoned (why a stored offset+zone string no longer resolves), real
+  boundaries (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a local
+  day, floorToZone/bucketRange, calendar-annotated strings, operating hours
+  (OperatingSchedule, recurringWindows, operatingIntervals, isOpenAt,
+  nextOpenAt, nextCloseAt, operatingTimeBetween, addOperatingTime), and daylight
+  time (isInDaylightSaving, hasDaylightSaving). Transport legs, intermodal free
+  time and EDI timestamps are in gmt-transport and gmt-intermodal.
 sources:
-  - 'northguild/gmt:README.md'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/zoned-date-operations/*.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/concepts/dst-disambiguation.md'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/operating-hours.mdx'
   - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/format/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/compare/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/convert/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/classify/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/calculate/addZoned.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfZoned.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/calculate/roundZoned.ts'
@@ -31,19 +29,15 @@ sources:
   - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/utc/convert/index.ts'
   - 'northguild/gmt:packages/gmt/src/instant/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/instant/validate/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/calculate/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/validate/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/hours/index.ts'
   - 'northguild/gmt:packages/gmt/src/types/operating-schedule.ts'
-  - 'northguild/gmt:packages/gmt/src/types/transport-timestamps.ts'
-  - 'northguild/gmt:packages/gmt/src/transport/calculate/index.ts'
-  - 'northguild/gmt:packages/gmt/src/transport/compare/index.ts'
-  - 'northguild/gmt:packages/gmt/src/transport/convert/index.ts'
-  - 'northguild/gmt:packages/gmt/src/intermodal/calculate/index.ts'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.18.0'
+  library_version: '1.20.0'
 ---
 
 # GMT Timezone
@@ -53,7 +47,7 @@ converting between time zones, or doing arithmetic that must respect DST.
 
 ## When to load
 
-- The user needs the current time in a specific timezone (`"America/New_York"`).
+- The user needs the current time in a specific timezone (`"Asia/Tokyo"`).
 - The user wants to format a datetime with its zone attached.
 - The user needs to convert a plain datetime to a zoned instant, or between
   timezones, or between UTC and Unix epochs.
@@ -63,12 +57,6 @@ converting between time zones, or doing arithmetic that must respect DST.
 - The user needs the start or end of a local hour, day, week, month or quarter.
 - The user is grouping or aggregating UTC timestamps by local day, hour, week or
   month — an observability rollup, a chargeable-days count.
-- The user is adding a leg's transit time to a departure, showing an arrival in
-  the zone where it lands, or counting how long cargo, a vessel or a patient sat
-  somewhere in local calendar days.
-- The user is working out when a container's free time ends, how many days of
-  demurrage or detention are chargeable and for which dates, or which events a
-  charge's clock runs between.
 - The user is asking whether a gate, desk, office or venue is open at an
   instant, when it next opens or closes, how many working hours passed between
   two instants, or when an SLA measured in open hours falls due — or is
@@ -76,8 +64,8 @@ converting between time zones, or doing arithmetic that must respect DST.
 
 ## Core rules
 
-1. **Use IANA timezone ids, not raw offsets.** `"2024-03-15T14:30:45[America/New_York]"`
-   is correct; bare `"-05:00"` loses the zone and can't observe DST rules.
+1. **Use IANA timezone ids, not raw offsets.** `"2024-03-15T14:30:45[Australia/Sydney]"`
+   is correct; bare `"+11:00"` loses the zone and can't observe DST rules.
 2. **DST disambiguation.** `convertPlainDateTimeToZoned`, `addZoned` and
    `setZoned` accept `disambiguation` (`"compatible"` | `"earlier"` |
    `"later"` | `"reject"`) for gap/overlap resolution. On `addZoned`,
@@ -115,11 +103,20 @@ converting between time zones, or doing arithmetic that must respect DST.
    on a spring-forward one. `resolveLocal(local, zone, { disambiguation })` then
    returns the instant, exact to the nanosecond, or `""` under `"reject"`. Reach
    for `convertPlainDateTimeToZoned` instead when you want the zoned string.
-6. **An offset is not a zone.** `-05:00` does not identify `America/New_York`.
-   `toOffsetInstant` splits a timestamp into `{ instant, offset, timeZone? }` —
-   the shape EPCIS 2.0, EDIFACT DTM and DICOM all exchange, because the instant
-   orders events and the offset renders them where they happened, and neither
-   derives from the other. Keep the zone for what is still to be scheduled.
+6. **An offset is not a zone, but a stored one is a rule for local time.**
+   `toOffsetInstant` gives `{ instant, offset, timeZone? }`, the pair EPCIS 2.0,
+   EDIFACT DTM and DICOM exchange. Its `±HH:MM[:SS]` offset is a valid `timeZone`
+   for `resolveLocal` and every function whose result has no zone in it. One
+   that returns a zoned string or formats with `Intl` takes none with seconds.
+   **A stored string can stop agreeing with its zone.**
+   `classifyStoredZoned("2016-12-01T09:00:00+02:00[Europe/Istanbul]")` returns
+   `kind: "offsetMismatch"` with `storedOffset`, `zoneOffset` and the instant each
+   reading gives. The other kinds are `valid`, `validInOverlap`, `ambiguous` and
+   `nonexistent`; every one carries `atStoredOffset`, and it returns `null` for a
+   string without both an offset and a zone. It picks no reading: your policy
+   chooses among those returned. The answer follows the host's time zone rules, so
+   the same string can differ between hosts. Import it from
+   `@northguild/gmt/zoned/classify`.
 7. **Bucket in the zone, not in UTC.** `floorToZone(instant, unit, zone)` and
    `bucketRange(start, end, unit, zone)` floor on the zone's own calendar
    boundaries. Flooring a UTC instant to a UTC day and calling it a local day is
@@ -142,7 +139,7 @@ converting between time zones, or doing arithmetic that must respect DST.
    local day.
 10. **Calendar annotations.** A calendar-annotated zoned string is RFC 9557,
     `Temporal.ZonedDateTime#toString()`: ISO digits, then `[timeZone]`, then
-    `[u-ca=<id>]` (`"2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"`).
+    `[u-ca=<id>]` (`"2024-10-03T14:30:45+03:00[Asia/Jerusalem][u-ca=hebrew]"`).
     A calendar annotation before the zone is rejected. Only `addZoned`, `subtractZoned`,
     `diffZoned`, `diffZonedAsDuration`, `convertZonedToCalendar`,
     `isValidCalendarZonedDateTime` and `zoned/interval/*` (including
@@ -176,122 +173,15 @@ converting between time zones, or doing arithmetic that must respect DST.
     fall-back into the previous date counts that date.
 13. **Zone names and leap seconds.** Every IANA name is a zone, including
     single-component links (`Japan`, `Zulu`, `EST5EDT`), in any case.
-    `toOffsetInstant` returns IANA casing (`"america/new_york"` gives
-    `"America/New_York"`). `:60` is invalid in every spelling (`T`, `t`, space,
+    `toOffsetInstant` returns IANA casing (`"asia/kolkata"` gives
+    `"Asia/Kolkata"`). `:60` is invalid in every spelling (`T`, `t`, space,
     basic format) and every zoned function returns its sentinel for it rather
-    than reading `:59`.
+    than reading `:59`; only `timescale/` and `gnss/` accept a listed one (for `gnss/`, see the `gmt-gnss` skill).
 14. **A zoned value formats in its own zone.** `formatZonedDateTime`,
     `formatZonedRange` and `formatZonedToParts` return `""`/`[]` for a
     `timeZone` option. To show an instant in another zone, use
     `formatUtc(convertZonedToUtc(value), locale, { timeZone })`.
-15. **Transport legs are exact time; dwell is counted in local days.**
-    `transitTime(departure, duration)` adds hours, minutes and seconds as
-    elapsed time (`P1D` is 24 exact hours) in the departure's own zone, so a leg
-    across a DST transition lands at the wall time the vehicle really arrives;
-    years, months and weeks return `""`, and a bracketed zone that contradicts
-    its offset is rejected rather than reinterpreted. `etaAtZone(instant, zone)`
-    renders a moment in the zone the caller names — no disambiguation arises,
-    the offset in the result tells the two passes of a fall-back hour apart, and
-    GMT never resolves a port, airport or station code to a zone.
-    `dwellTime(entry, exit, targetZone?)` returns `{ duration, enter, exit,
-    calendarDays }`; `calendarDays` is the number of distinct local dates the
-    half-open `[entry, exit)` touches, walked across the zone's real transitions
-    (a skipped date is not counted, a re-entered one only once), and is the
-    library's one "local days crossed" count.
-    Bare instants with no `targetZone` return `null`: an offset is not a place.
-    `crossingTime(entry, exit, targetZone)` returns `{ duration, enter, exit }`
-    with no day count (a crossing that needs one is a dwell); `targetZone` is
-    required and always the rendering zone — a bracket on the input never
-    supplies it.
-    `scheduleDelivery(legs, { startTimeZone? })` chains legs into `{ eta,
-    legTimes }`: each leg leaves at its explicit `departure` or at the previous
-    arrival plus that leg's `dwellAfter`, the minimum connect time. A scheduled
-    departure earlier than that is a missed connection and returns `null`
-    (equal passes). A departure is exact (instant or zoned string) or a
-    zoneless wall time: on the first leg it is read in `startTimeZone`, on a
-    later leg in the previous leg's `timeZone` (where that leg leaves from),
-    both with `"compatible"` resolution (ambiguous → earlier, skipped →
-    later). On a later leg, a repeated hour instead takes the earliest pass
-    at or after the previous arrival plus its dwell. A
-    negative leg `duration` is `null`; the last leg's `dwellAfter` is echoed,
-    never added. `mode`, `origin` and `destination` are opaque tags echoed on
-    each `LegTime`. An empty array returns `{ eta: "", legTimes: [] }`.
-16. **Cut-offs count back from the caller's event.**
-    `cutoffAt(anchor, offset, { timeZone, atLocalTime?, calendar?, roll? })`
-    takes an offset off the anchor (loading, departure or arrival are
-    different instants; it never guesses which). With `atLocalTime` the
-    offset's exact part comes off the anchor's instant first, its calendar
-    part off the local date, and the cut-off is that time of day: `P2D` at
-    `"17:00"` is 17:00 two days before, not 48 hours. Without it the offset
-    is `ZonedDateTime#subtract` (`P2D` keeps the wall clock, `PT96H` is 96
-    exact hours). `calendar` and `roll` go together or not at all — there is
-    no default roll, as in `rollDate`; either alone is `""`. A repeated hour
-    takes the first pass (RFC 5545 §3.3.5); a skipped hour is `""`. It does
-    not check that the cut-off is before the anchor.
-    `cutoffSchedule(anchor, [{ name, offset, atLocalTime? }], options)`
-    sorts the stack by instant and returns `[]` if any entry fails.
-    `isPastCutoff(now, cutoff)` is `true` from the cut-off instant on;
-    `timeToCutoff(now, cutoff)` is exact hours, `PT0S` at it, negative after.
-17. **Planned versus actual is exact time under the caller's tolerance.**
-    `scheduleDeviation(planned, actual)` is `actual − planned` in exact hours
-    (`"PT14M"` late, `"-PT5M"` early; a fall-back delay is `PT1H`, never
-    `PT0S`). `classifyPunctuality(planned, actual, { late, early? })` returns
-    `"early" | "onTime" | "late"`, or `null` on invalid input: both edges are
-    outside (exactly `late` is late), and without `early` every early arrival
-    is on time. There is no default tolerance; tolerances are exact durations
-    (a day is 24 hours; years, months, weeks or negative return `null`).
-    `punctualityRate(pairs, tolerance)` returns `{ onTime, total, rate }`,
-    judging every pair under a tolerance read once; an empty list or any
-    invalid pair is `null`. A `TimestampEvent` is `{ classifier: "PLN" |
-    "EST" | "REQ" | "ACT", at, recordedAt }` (DCSA vocabulary).
-    `bestAvailable(events)` returns `{ at, classifier }`: `ACT` whenever one
-    exists, else `PLN`, else `REQ`, else `EST`, newest `recordedAt` within the
-    class — never an `EST` shown as an actual. `estimateDrift(events, {
-    tolerance? })` reports first-to-last `EST` drift, `revisions` and
-    `exceedsTolerance` (strictly greater, either direction; `null` without a
-    tolerance), and is `null` with fewer than two `EST`s.
-    `nextDeparture(after, timetable, { minimumConnection? })` returns the
-    first departure at or after `after + minimumConnection`: a list entry
-    echoed as written (ready for `scheduleDelivery`'s `departure`), or for
-    `{ headway, from, to }` (a GTFS `frequencies.txt` row) `from + k × headway`
-    in the half-open `[from, to)`, written the way `from` was. Every moment
-    must carry its offset; a wall time without one is `""`.
-18. **Free time is counted in the terminal's local days; the start day and the
-    basis are tariff terms, never defaults.**
-    `freeTimeExpiry(clockStart, freeDays, { basis, timeZone, firstDay, calendar? })`
-    returns `{ freeTimeStart, lastFreeDay, expiresAt }`: local dates in
-    `timeZone`, and the first instant of the day after the last free day.
-    `firstDay` (`"eventDay"` | `"nextDay"`) has no default because the two
-    differ by a day of charges; `basis: "working"` needs a `BusinessCalendar`
-    and returns `null` without one. `chargeableDays(clockStart, clockEnd,
-    freeDays, options)` also needs `chargeBasis` (no default): many tariffs
-    count both in calendar days; where a tariff grants free time in working
-    days the days after it are mostly charged as calendar days, and some
-    tariffs charge working days only. It counts the days on or after
-    `expiresAt` the half-open dwell touched, lists them as `chargedDates`, and
-    splits them into `tiers` bands; `freeDays: 0` is allowed there.
-    `demurrageClock(events, scope, { direction, startEvent? })` selects the
-    events per leg: import demurrage and storage run discharge (or
-    availability) to gate-out, detention gate-out to empty return; export
-    demurrage gate-in to loaded, detention empty release to gate-in; `combined`
-    runs both as one period. No standard fixes how these days are counted;
-    every term is the tariff's.
-19. **Billing deadlines are dates counted from an anchor, and every window is
-    the caller's.** `billingTimeline({ anchorOn, invoiceIssuedOn?,
-    requestReceivedOn? }, { issueDays, disputeDays, resolutionDays,
-    agreedResolutionOn? })` returns `{ invoiceDeadline, issuedByDeadline,
-    disputeDeadline, requestedByDeadline, resolutionDeadline }`. Day zero is
-    the anchor and each deadline is `date + days` on the ISO calendar; a date
-    is by the deadline when it is on or before it. No window has a default (a
-    missing one returns `null`); fields whose input does not exist yet are
-    `null`, so an anchor alone is a forecast. The anchor is whatever date the
-    caller counts from: the last charged date
-    (`chargedDates.at(-1)`), or for a re-bill the issuance date of the invoice
-    received. Reduce an instant to the billing party's local date first with
-    `convertUtcToPlainDate(instant, { timeZone })`. A request before its
-    invoice, or an agreed date before the request, returns `null`. GMT
-    computes dates, not liability.
-20. **Operating hours are local windows resolved in the schedule's zone.** An
+15. **Operating hours are local windows resolved in the schedule's zone.** An
     `OperatingSchedule` is `{ timeZone, weekly, holidays?, overrides? }`:
     `weekly` maps ISO weekdays `1`–`7` to half-open `LocalWindow`s
     (`{ from: "09:00", to: "17:00" }`); a `to` at or before `from` wraps past
@@ -307,12 +197,11 @@ converting between time zones, or doing arithmetic that must respect DST.
     `addOperatingTime(start, "PT8H", schedule)` is the SLA deadline. Searches
     stop at `within` (default `"P1Y"`) and return `""` past it; `P1D` is not
     open time and returns `""`.
-21. **A zoned string names one instant in every reader.** Temporal writes a
+16. **A zoned string names one instant in every reader.** Temporal writes a
     zone's offset rounded to the minute, so a zone with a sub-minute offset
     (`Africa/Monrovia` stood at −00:44:30 until 1972) is written `-00:45`.
     Every function that reads a moment (`toNanoseconds`, `spanNs`, `Interval`
-    endpoints, `floorToZone`, `getTimeZoneOffset`, `scheduleDeviation`,
-    `timeToCutoff`, `dwellTime`) reads an offset written to the minute as the
+    endpoints, `floorToZone`, `getTimeZoneOffset`, and the `transport/` functions that read one) reads an offset written to the minute as the
     bracketed zone's real offset when it is that offset rounded (TC39
     `ToTemporalZonedDateTime`, match-minutes):
     `1960-01-01T00:20:00-00:45[Africa/Monrovia]` is `01:04:30Z`. So a zoned
@@ -320,7 +209,7 @@ converting between time zones, or doing arithmetic that must respect DST.
     the written offset fixes the instant. A function that reads only the
     instant does not validate the bracket, and the bracket never supplies its
     rendering zone. A function that keeps the zone (`isValidZonedDateTime`,
-    `transitTime`, `toOffsetInstant`, every `zoned/` function, a zoned
+    `toOffsetInstant`, every `zoned/` function, a zoned
     `relativeTo`) rejects a bracket that contradicts the offset, and an offset
     written with seconds must be the zone's offset exactly:
     `-00:45:00[Africa/Monrovia]` is invalid, `-00:44:30[Africa/Monrovia]` is
@@ -329,7 +218,7 @@ converting between time zones, or doing arithmetic that must respect DST.
     (`1952-10-15T23:59:59-11:20[Pacific/Niue]`); write the offset with seconds
     to name the second. A zoned read refuses a local date of −271821-04-19,
     which an instant reader accepts; pass that instant in `Z` form.
-22. **Daylight time is read from the zone's clock changes.**
+17. **Daylight time is read from the zone's clock changes.**
     `isInDaylightSaving(zoned)` and `hasDaylightSaving(timeZone, { at })`
     apply one rule, GMT's own definition and not the tz database's daylight
     flag (no JavaScript API exposes it): daylight time runs from a forward
@@ -348,9 +237,10 @@ converting between time zones, or doing arithmetic that must respect DST.
     read the runtime's time zone data, so an answer can change when that data
     does. The JSDoc of `isInDaylightSaving` lists what the rule reads as
     standard time.
-23. **Read the README.** This skill is a routing pointer. For the full DST
-    disambiguation walkthrough, code examples, and locale ICU notes, read the
-    installed package's `README.md` and the source JSDoc.
+18. **Read the docs site.** This skill is a routing pointer. The map of the
+    docs is `https://northguild.dev/gmt/llms.txt`, and each page
+    has a `.md` twin that holds its text. The JSDoc ships in the installed
+    package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
 
 ## Key functions
 
@@ -370,24 +260,16 @@ converting between time zones, or doing arithmetic that must respect DST.
   `endOfUnix`, `mapZonedHoursInDay`, `getHoursInZonedDay`
 - **Offset/DST reads**: `getZonedOffset`, `getZonedOffsetAs`,
   `getTimeZoneOffset`, `parseTimeZoneFromZoned`
-- **Offset-preserving instants**: `toOffsetInstant`, `fromOffsetInstant`
-- **Local-time resolution**: `classifyLocal`, `resolveLocal`
+- **Offset-preserving instants**: `toOffsetInstant`, `fromOffsetInstant`,
+  `isValidUtcOffset` (the pair's `±HH:MM[:SS]` offset; not `Z`, not `+0530`)
+- **Local-time resolution**: `classifyLocal`, `resolveLocal`,
+  `classifyStoredZoned`
 - **Zone-aware buckets**: `floorToZone`, `bucketRange`,
   `isValidZoneBucketUnit`
-- **Transport legs and dwell**: `transitTime`, `etaAtZone`, `dwellTime`,
-  `crossingTime`, `scheduleDelivery`
-- **Cut-offs and deadlines**: `cutoffAt`, `cutoffSchedule`, `isPastCutoff`,
-  `timeToCutoff`
-- **Punctuality and timestamp classes**: `scheduleDeviation`,
-  `classifyPunctuality`, `punctualityRate`, `bestAvailable`, `estimateDrift`,
-  `nextDeparture`
-- **Free time and demurrage**: `freeTimeExpiry`, `chargeableDays`,
-  `demurrageClock`
-- **Billing deadlines**: `billingTimeline`
 - **Operating hours**: `recurringWindows`, `operatingIntervals`, `isOpenAt`,
   `nextOpenAt`, `nextCloseAt`, `operatingTimeBetween`, `addOperatingTime`
 
 ## References
 
-- [README — Timezone and Calendar examples](README.md)
-- [DST Disambiguation guide](https://gmt-dox.northguild.workers.dev/guides/concepts/dst-disambiguation/)
+- [Zoned operations guide](https://northguild.dev/gmt/guides/zoned-date-operations/zoned-operations/)
+- [DST Disambiguation guide](https://northguild.dev/gmt/guides/concepts/dst-disambiguation/)

package/skills/gmt-transport/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: gmt-transport
+description: >
+  Transport timing for legs, cut-offs and punctuality — transitTime, etaAtZone,
+  dwellTime, crossingTime, scheduleDelivery (exact legs, local calendar days
+  dwelt, missed connections), cutoffAt, cutoffSchedule, isPastCutoff,
+  timeToCutoff, scheduleDeviation, classifyPunctuality, punctualityRate,
+  bestAvailable, estimateDrift over PLN/EST/REQ/ACT timestamp classes, and
+  nextDeparture, all in @northguild/gmt/transport. Every tolerance, connect time
+  and cut-off offset is the caller's. Reads the docs site (llms.txt) and the
+  installed package's JSDoc; a routing pointer, not an API dump.
+sources:
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/transport-legs-and-dwell.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/transport-multi-leg-scheduling.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/transport-punctuality-and-timestamps.mdx'
+  - 'northguild/gmt:packages/gmt/src/transport/calculate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/transport/compare/index.ts'
+  - 'northguild/gmt:packages/gmt/src/transport/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/transport-timestamps.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.20.0'
+---
+
+# GMT Transport
+
+Use this skill when the task is timing a vehicle, vessel or consignment across
+legs and zones: transit, arrival in the local zone, dwell, cut-offs, planned
+versus actual, or the next departure. The time zone rules it builds on are in
+the `gmt-timezone` skill.
+
+## When to load
+
+- The user is adding a leg's transit time to a departure, showing an arrival in
+  the zone where it lands, or counting how long cargo, a vessel or a patient sat
+  somewhere in local calendar days.
+
+## Core rules
+
+1. **Transport legs are exact time; dwell is counted in local days.**
+    `transitTime(departure, duration)` adds hours, minutes and seconds as
+    elapsed time (`P1D` is 24 exact hours) in the departure's own zone, so a leg
+    across a DST transition lands at the wall time the vehicle really arrives;
+    years, months and weeks return `""`, and a bracketed zone that contradicts
+    its offset is rejected rather than reinterpreted. `etaAtZone(instant, zone)`
+    renders a moment in the zone the caller names — no disambiguation arises,
+    the offset in the result tells the two passes of a fall-back hour apart, and
+    GMT never resolves a port, airport or station code to a zone.
+    `dwellTime(entry, exit, targetZone?)` returns `{ duration, enter, exit,
+    calendarDays }`; `calendarDays` is the number of distinct local dates the
+    half-open `[entry, exit)` touches, walked across the zone's real transitions
+    (a skipped date is not counted, a re-entered one only once), and is the
+    library's one "local days crossed" count.
+    Bare instants with no `targetZone` return `null`: an offset is not a place.
+    `crossingTime(entry, exit, targetZone)` returns `{ duration, enter, exit }`
+    with no day count (a crossing that needs one is a dwell); `targetZone` is
+    required and always the rendering zone — a bracket on the input never
+    supplies it.
+    `scheduleDelivery(legs, { startTimeZone? })` chains legs into `{ eta,
+    legTimes }`: each leg leaves at its explicit `departure` or at the previous
+    arrival plus that leg's `dwellAfter`, the minimum connect time. A scheduled
+    departure earlier than that is a missed connection and returns `null`
+    (equal passes). A departure is exact (instant or zoned string) or a
+    zoneless wall time: on the first leg it is read in `startTimeZone`, on a
+    later leg in the previous leg's `timeZone` (where that leg leaves from),
+    both with `"compatible"` resolution (ambiguous → earlier, skipped →
+    later). On a later leg, a repeated hour instead takes the earliest pass
+    at or after the previous arrival plus its dwell. A
+    negative leg `duration` is `null`; the last leg's `dwellAfter` is echoed,
+    never added. `mode`, `origin` and `destination` are opaque tags echoed on
+    each `LegTime`. An empty array returns `{ eta: "", legTimes: [] }`.
+2. **Cut-offs count back from the caller's event.**
+    `cutoffAt(anchor, offset, { timeZone, atLocalTime?, calendar?, roll? })`
+    takes an offset off the anchor (loading, departure or arrival are
+    different instants; it never guesses which). With `atLocalTime` the
+    offset's exact part comes off the anchor's instant first, its calendar
+    part off the local date, and the cut-off is that time of day: `P2D` at
+    `"17:00"` is 17:00 two days before, not 48 hours. Without it the offset
+    is `ZonedDateTime#subtract` (`P2D` keeps the wall clock, `PT96H` is 96
+    exact hours). `calendar` and `roll` go together or not at all — there is
+    no default roll, as in `rollDate`; either alone is `""`. A repeated hour
+    takes the first pass (RFC 5545 §3.3.5); a skipped hour is `""`. It does
+    not check that the cut-off is before the anchor.
+    `cutoffSchedule(anchor, [{ name, offset, atLocalTime? }], options)`
+    sorts the stack by instant and returns `[]` if any entry fails.
+    `isPastCutoff(now, cutoff)` is `true` from the cut-off instant on;
+    `timeToCutoff(now, cutoff)` is exact hours, `PT0S` at it, negative after.
+3. **Planned versus actual is exact time under the caller's tolerance.**
+    `scheduleDeviation(planned, actual)` is `actual − planned` in exact hours
+    (`"PT14M"` late, `"-PT5M"` early; a fall-back delay is `PT1H`, never
+    `PT0S`). `classifyPunctuality(planned, actual, { late, early? })` returns
+    `"early" | "onTime" | "late"`, or `null` on invalid input: both edges are
+    outside (exactly `late` is late), and without `early` every early arrival
+    is on time. There is no default tolerance; tolerances are exact durations
+    (a day is 24 hours; years, months, weeks or negative return `null`).
+    `punctualityRate(pairs, tolerance)` returns `{ onTime, total, rate }`,
+    judging every pair under a tolerance read once; an empty list or any
+    invalid pair is `null`. A `TimestampEvent` is `{ classifier: "PLN" |
+    "EST" | "REQ" | "ACT", at, recordedAt }` (DCSA vocabulary).
+    `bestAvailable(events)` returns `{ at, classifier }`: `ACT` whenever one
+    exists, else `PLN`, else `REQ`, else `EST`, newest `recordedAt` within the
+    class — never an `EST` shown as an actual. `estimateDrift(events, {
+    tolerance? })` reports first-to-last `EST` drift, `revisions` and
+    `exceedsTolerance` (strictly greater, either direction; `null` without a
+    tolerance), and is `null` with fewer than two `EST`s.
+    `nextDeparture(after, timetable, { minimumConnection? })` returns the
+    first departure at or after `after + minimumConnection`: a list entry
+    echoed as written (ready for `scheduleDelivery`'s `departure`), or for
+    `{ headway, from, to }` (a GTFS `frequencies.txt` row) `from + k × headway`
+    in the half-open `[from, to)`, written the way `from` was. Every moment
+    must carry its offset; a wall time without one is `""`.
+4. **Read the docs site.** This skill is a routing pointer. The map of the
+   docs is `https://northguild.dev/gmt/llms.txt`, and each page
+   has a `.md` twin that holds its text. The JSDoc ships in the installed
+   package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
+
+## Key functions
+
+- **Transport legs and dwell**: `transitTime`, `etaAtZone`, `dwellTime`,
+  `crossingTime`, `scheduleDelivery`
+- **Cut-offs and deadlines**: `cutoffAt`, `cutoffSchedule`, `isPastCutoff`,
+  `timeToCutoff`
+- **Punctuality and timestamp classes**: `scheduleDeviation`,
+  `classifyPunctuality`, `punctualityRate`, `bestAvailable`, `estimateDrift`,
+  `nextDeparture`
+
+## References
+
+- [transport reference](https://northguild.dev/gmt/reference/transport/)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [GMT Timezone skill](../gmt-timezone/SKILL.md)
+- [GMT Intermodal skill](../gmt-intermodal/SKILL.md)

package/skills/gmt-workforce/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: gmt-workforce
+description: >
+  Hours-of-work rules over a duty log in @northguild/gmt/workforce —
+  evaluateDutyLog and dutyViolations for cumulative caps, rolling and fixed-
+  period caps, rest requirements, free periods, quotas and patterns over the
+  caller's own status words, dutyDayFor for the operator day, dutyTotals,
+  longestRun, qualifyingRests, qualifyingRestPairs, isValidDutyLog. Every limit
+  is the caller's; GMT names no regulation. Reads the docs site (llms.txt) and
+  the installed package's JSDoc; a routing pointer.
+sources:
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/workforce-hours-of-work.mdx'
+  - 'northguild/gmt:packages/gmt/src/workforce/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/duty.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.20.0'
+---
+
+# GMT Workforce
+
+Use this skill when the task is checking hours of work against rules: driving
+or duty caps, rest in every 24 hours, a free day in seven, a monthly record of
+violations. The interval and duration rules it builds on are in the
+`gmt-arithmetic` skill.
+
+## When to load
+
+- The user checks hours of work against rules: driving or duty caps, rest in
+  every 24 hours, a free day in seven, a monthly record of violations.
+
+## Core rules
+
+1. **Hours of work are rules over a duty log, and every number is the
+    caller's.** A log is `{ status, start, end }[]` in the caller's own status
+    words, ordered and non-overlapping (`isValidDutyLog`). A rule is one of 13
+    `DutyRule` kinds (`cumulativeCap`, `elapsedWindow`, `requiredInterruption`,
+    `rollingCap`, `fixedPeriodCap`, `restRequirement`, `freePeriod`,
+    `restBeforeDuty`, `quota`, `dueBy`, `pattern`, `occurrenceCap`,
+    `usageLookback`) with no default limit; GMT names no regulation.
+    `evaluateDutyLog(log, at, rules, { timeZone, dayStartTime?, disambiguation? })`
+    reports every rule at one instant; `dutyViolations` lists each violation in a
+    range once, by its worst window, in the range it began in.
+
+    ```typescript
+    evaluateDutyLog(log, "2024-01-01T21:30:00Z", [{ label: "11 driving", kind: "cumulativeCap",
+      statuses: ["driving"], cap: "PT11H", since: { statuses: ["off"], consecutive: "PT10H" } }],
+      { timeZone: "UTC" }).violations; // [{ label: "11 driving", used: "PT11H30M", limit: "PT11H", … }]
+    ```
+
+    - `{ elapsed: "PT24H" }` slides; `{ operatorDays }`, `{ calendarDays }`,
+      `{ isoWeeks }`, `{ calendarMonths }`, `{ calendarYears }` are whole local
+      periods in `timeZone` (28 calendar days across a fall-back are 673 hours).
+    - The operator day is `dutyDayFor(instant, { timeZone, dayStartTime })`,
+      never local midnight; a rule counting `operatorDays` needs `dayStartTime`.
+    - The log is read up to `at`; unlogged time is neither work nor rest. To
+      check a roster, append the plan and set `at` to its end.
+    - A paired rest is three floors (`PairSpec`), not two integers:
+      `qualifyingRestPairs`.
+    - A count of periods is 10,000 at most, alone or times `adjacent`,
+      `lookback` or `periods`. `fixedPeriodCap.period` and `occurrenceCap.per`
+      are a `LocalPeriod`: a count, never `elapsed`.
+    - `dutyViolations` reads only the time the log covers, and each check reads
+      the log as it stood then, so a record only grows as the log does.
+    - Nested caps are separate rules, reported separately.
+2. **Read the docs site.** This skill is a routing pointer. The map of the
+   docs is `https://northguild.dev/gmt/llms.txt`, and each page
+   has a `.md` twin that holds its text. The JSDoc ships in the installed
+   package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
+
+## Key functions
+
+- **Hours of work**: `evaluateDutyLog`, `dutyViolations`, `dutyDayFor`,
+  `dutyTotals`, `longestRun`, `qualifyingRests`, `qualifyingRestPairs`,
+  `isValidDutyLog`, types `DutyEntry`, `DutyRule`, `Period`, `LocalPeriod`,
+  `DutyReport`
+
+## References
+
+- [workforce reference](https://northguild.dev/gmt/reference/workforce/)
+- [Workforce: Hours of Work guide](https://northguild.dev/gmt/guides/industries/workforce-hours-of-work/)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [GMT Arithmetic skill](../gmt-arithmetic/SKILL.md)

package/dist/internal/unixZonedDateTime.d.ts

@@ -1,22 +0,0 @@
-import type { Temporal } from "@js-temporal/polyfill";
-/**
- * Read a Unix epoch argument as a `Temporal.ZonedDateTime` under the shared `unix/` options, or
- * null when anything is invalid.
- *
- * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
- * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
- * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone is invalid
- *   (see `normalizeTimeZone`).
- *
- * @param value Unix epoch number or digit string
- * @param options optional `{ epochUnit, timeZone }`
- * @returns the zoned date-time, or null
- *
- * @example unixZonedDateTime(0)?.toString() // "1970-01-01T00:00:00+00:00[UTC]"
- * @example unixZonedDateTime("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
- * @example unixZonedDateTime(0, { timeZone: "Asia/Tokio" }) // null
- */
-export declare function unixZonedDateTime(value: unknown, options?: {
-    epochUnit?: unknown;
-    timeZone?: unknown;
-}): Temporal.ZonedDateTime | null;

package/dist/internal/unixZonedDateTime.js

@@ -1,32 +0,0 @@
-import { normalizeTimeZone } from "./normalizeTimeZone.js";
-import { resolveUnixEpochUnit, unixEpochToInstant } from "./unixEpochValue.js";
-/**
- * Read a Unix epoch argument as a `Temporal.ZonedDateTime` under the shared `unix/` options, or
- * null when anything is invalid.
- *
- * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
- * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
- * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone is invalid
- *   (see `normalizeTimeZone`).
- *
- * @param value Unix epoch number or digit string
- * @param options optional `{ epochUnit, timeZone }`
- * @returns the zoned date-time, or null
- *
- * @example unixZonedDateTime(0)?.toString() // "1970-01-01T00:00:00+00:00[UTC]"
- * @example unixZonedDateTime("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
- * @example unixZonedDateTime(0, { timeZone: "Asia/Tokio" }) // null
- */
-export function unixZonedDateTime(value, options) {
-    const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-    const timeZone = normalizeTimeZone(options?.timeZone);
-    if (epochUnit === null || !timeZone) {
-        return null;
-    }
-    try {
-        return (unixEpochToInstant(value, epochUnit)?.toZonedDateTimeISO(timeZone) ?? null);
-    }
-    catch {
-        return null;
-    }
-}

package/dist/internal/utcZonedDateTime.d.ts

@@ -1,19 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-/**
- * Read a UTC ISO string as a zoned date-time for the `parse*FromUtc` accessors: the instant it
- * names, on the wall clock of `options.timeZone`. The utc twin of `unixZonedDateTime`.
- *
- * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone is invalid
- *   (see `normalizeTimeZone`).
- *
- * @param value UTC ISO 8601 datetime string
- * @param options optional `{ timeZone }`
- * @returns the zoned date-time, or null when the value or the zone is invalid
- * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00+09:00[Asia/Tokyo]"
- * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "local" })?.timeZoneId // the system zone, e.g. "America/New_York"
- * @example utcZonedDateTime("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
- * @example utcZonedDateTime("2024-03-15T14:30:00") // null (no Z)
- */
-export declare function utcZonedDateTime(value: string, options?: {
-    timeZone?: string;
-}): Temporal.ZonedDateTime | null;