@northguild/gmt 1.18.0 → 1.19.0

package/skills/gmt-basics/SKILL.md

@@ -4,12 +4,19 @@ description: >
   Core date/time basics — get current values, parse components, read ISO week,
   ordinal, quarter and fiscal-period identifiers, format for display, format
   relative time, compare dates, and validate strings/timezones/intervals. Reads
-  the installed package README.md and source JSDoc for API details; this skill
-  is a routing pointer, not an API dump.
+  the docs site (llms.txt and each page's .md twin) and the installed package's
+  JSDoc for API details; this skill is a routing pointer, not an API dump.
 sources:
-  - 'northguild/gmt:README.md'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/get-current.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/parsing.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/formatting.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/relative-time.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/comparisons.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/validation.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/zoned-date-operations/calendar-boundaries.mdx'
   - 'northguild/gmt:packages/gmt/src/plain/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/plain/parse/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/two-digit-year.ts'
   - 'northguild/gmt:packages/gmt/src/plain/format/index.ts'
   - 'northguild/gmt:packages/gmt/src/plain/locale/index.ts'
   - 'northguild/gmt:packages/gmt/src/plain/compare/index.ts'
@@ -17,6 +24,9 @@ sources:
   - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/format/index.ts'
   - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/parse/index.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/parse/index.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/validate/index.ts'
   - 'northguild/gmt:packages/gmt/src/unix/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/calculate/index.ts'
@@ -24,7 +34,7 @@ sources:
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.18.0'
+  library_version: '1.19.0'
 ---
 
 # GMT Basics
@@ -52,26 +62,36 @@ input before you act on it.
    `false` for booleans, `[]` for arrays. Always check before using. This holds
    for a `null` or wrong-typed argument too (`addDate(x, null)` is `""`), so a
    `try`/`catch` around a GMT call is dead code.
-3. **Read the README.** This skill is a routing pointer. For full API
-   signatures, locale matrices, and code examples, read the installed package's
-   `README.md` and the source JSDoc of the function you intend to call.
+3. **Read the docs site.** This skill is a routing pointer. For full API
+   signatures, locale matrices, and code examples, read these:
+   - `https://gmt-dox.northguild.workers.dev/llms.txt` is the map of every docs page.
+   - Each page has a `.md` twin that holds its text, for example
+     `https://gmt-dox.northguild.workers.dev/guides/core-date-operations/parsing.md`.
+   - The JSDoc of the function you intend to call ships in the installed
+     package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
 
 ## Key functions
 
 - **Current values**: `getNow`, `getToday`, `getUtcNow`, `getUnixNow`,
   `getSystemTimeZone`, `getTimeZones`
 - **Parsing**: `parseYearFromDate`, `parseMonthFromDate`,
-  `parseDateTimeWithPattern`, `parseRfc3339`, `parseHttp`, `parseSql`
+  `parseDateTimeWithPattern`, `parseRfc3339`, `parseRfc2822`,
+  `parseHttpDate`, `parseSqlDateTime`
 - **Calendar identifiers**: `getIsoWeekDate`, `getOrdinalDate`, `getQuarter`,
   `getFiscalPeriod`
 - **Formatting**: `formatDate`, `formatTime`, `formatDateTime`,
-  `formatRelativeDate`, `formatCalendar`, `formatRfc3339`
+  `formatRelativeDate`, `formatCalendar`, `formatRfc3339`, `formatRfc2822`,
+  `formatHttpDate`, `formatSqlDateTime`
 - **Locale names**: `getLocaleMonthNames`, `getLocaleWeekdayNames`,
   `getLocaleMeridiems`, `getLocaleEraNames`
 - **Comparison**: `isAfterDate`, `isBeforeDate`, `areDatesEqual`,
   `areDatesEqualBy`, `isWeekend`, `isBusinessDay`, `nextWeekday`
 - **Validation**: `isValidDate`, `isValidTime`, `isValidTimeZone`,
   `isValidZonedDateTime`, `isValidDateInterval`, `isValidFiscalPattern`
+- **Interchange-format validation**: `isValidRfc3339DateTime`,
+  `isValidRfc2822DateTime`, `isValidHttpDate`, `isValidSqlDateTime`
+- **UTC timestamp validation**: `isValidUtcTimestamp` (a UTC instant written
+  `YYYY-MM-DDTHH:MM:SS[.f]Z` and nothing else; it has no parser)
 
 ## Common pitfalls
 
@@ -82,21 +102,41 @@ input before you act on it.
   second to hour, the others second to year. Any other unit returns `""`.
   `roundingMethod` is `"floor"`, `"ceil"` or `"round"`: any other value returns `""`.
 - In a `parse*WithPattern` pattern, `''` is one literal quote, inside or outside
-  quoted text (UTS #35): `"MMM d, ''yy"` reads `"Mar 15, '24"`. It is not an empty
-  separator. Write adjacent fields with nothing between them, as in `"yyyyMMdd"`.
+  quoted text (UTS #35), and not an empty separator: `"''yyyy-MM-dd''"` reads
+  `"'2024-01-15'"`. Write adjacent fields with nothing between them, as in `"yyyyMMdd"`.
+- A `yy` token in a `parse*WithPattern` pattern needs the caller's hundred-year window:
+  `{ yearWindow: 2000 }` reads `"03/15/24"` against `"MM/dd/yy"` as `"2024-03-15"`, and
+  `"rolling"` is the hundred years around the current UTC year. A `yy` pattern with no
+  `yearWindow` returns `""`; a pattern with no `yy` never reads the option.
 - `getZonedNow` reads `smallestUnit` only, and writes milliseconds when it is
   omitted or `undefined`. The string always carries the offset and the zone.
-- `parseDateWithPattern`, `parseRfc2822` and `parseHttp` return `""` on
+- `parseDateWithPattern`, `parseRfc2822` and `parseHttpDate` return `""` on
   shape-valid-but-unreal dates such as 31 February (regex only proves shape;
   Temporal validates the real value). Parsers reject; only arithmetic clamps.
 - `parseRfc2822` reads everything RFC 5322 says a receiver must: comments,
   folding whitespace, any case, two-digit years and zone names such as `EST`
-  (an unknown name reads as `+00:00`). `parseHttp` reads all three HTTP-date
+  (an unknown name reads as `+00:00`). `parseHttpDate` reads all three HTTP-date
   forms, including `rfc850-date` and `asctime-date`. Both return `""` when the
   day name contradicts the date (`"Sat, 15 Mar 2024 …"`), so do not synthesise
   a day name; omit it. The `rfc2822DateTime` and `httpDate` regexes stay strict
   and match only what GMT writes, so do not use them to pre-filter parser input.
-- `formatRfc2822`, `formatHttp` and `formatRfc3339` return `""` for a year their
+- To check an interchange string, call its validator, not its regex.
+  `isValidRfc3339DateTime`, `isValidRfc2822DateTime`, `isValidHttpDate` and
+  `isValidSqlDateTime` are each true exactly when the parser returns a value.
+  A regex proves shape only: `rfc3339DateTime.test("2023-02-29T10:00:00Z")`
+  is `true` and `isValidRfc3339DateTime` returns `false` for it.
+- `isValidUtcTimestamp` matches no parser: it is a narrower `isValidUtc`. It is true
+  only for a real UTC instant written `YYYY-MM-DDTHH:MM:SS[.f]Z`: a four-digit year
+  `0000` to `9999`, upper-case `T` and `Z`, seconds, an optional dot fraction of one to
+  nine digits, and nothing after the `Z`. Use it for a string headed for storage or for
+  a reader that is not Temporal. `isValidUtc` also accepts a time without seconds, a
+  comma before the fraction, an expanded `±YYYYYY` year and RFC 9557 annotations
+  (`"2026-10-06T12:00:00Z[Europe/Paris]"`); all four are `false` here. A numeric offset,
+  `+00:00` included, is `false` too: `isValidRfc3339DateTime` checks the whole RFC 3339
+  grammar, with the same two GMT limits (no second `60`, at most nine fraction digits).
+  The check is on the spelling and the instant. A reader's own range and precision
+  still apply.
+- `formatRfc2822`, `formatHttpDate` and `formatRfc3339` return `""` for a year their
   grammar cannot hold (before 0000, or after 9999 for RFC 3339 and HTTP).
   `formatRfc3339` writes a sub-minute historical offset as the same instant at
   `+00:00`. Use Temporal's `toString()` when you need any year.
@@ -132,5 +172,7 @@ input before you act on it.
 
 ## References
 
-- [README — API Surface and Quick Start](README.md)
+- [Docs map for agents (llms.txt)](https://gmt-dox.northguild.workers.dev/llms.txt)
+- [API reference](https://gmt-dox.northguild.workers.dev/reference/)
+- [Core date operations guides index](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/)
 - [Core date operations guides](/guides/core-date-operations/get-current/)

package/skills/gmt-integration/SKILL.md

@@ -4,11 +4,16 @@ description: >
   Application integration patterns — stable cache keys, router/query params,
   table-sort keys, nanosecond timestamps across JSON and storage boundaries,
   foreign epoch bridges (NTP, FILETIME, .NET ticks, Excel, PostgreSQL), and lint
-  package selection (ESLint, Biome, Oxlint). Reads the installed package
-  README.md and lint-package READMEs for API details; this skill is a routing
-  pointer, not an API dump.
+  package selection (ESLint, Biome, Oxlint). Reads the docs site (llms.txt and
+  each page's .md twin) and the installed package's JSDoc for API details, and
+  the lint-package READMEs for lint setup; this skill is a routing pointer, not
+  an API dump.
 sources:
-  - 'northguild/gmt:README.md'
+  - 'northguild/gmt:apps/dox/src/content/docs/install.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/integration/app-integration.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/integration/linting.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/nanosecond-precision.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/conversion/foreign-epoch-bridges.mdx'
   - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
   - 'northguild/gmt:packages/gmt/src/precision/convert/index.ts'
   - 'northguild/gmt:packages/gmt/src/precision/format/index.ts'
@@ -17,7 +22,7 @@ sources:
 metadata:
   type: composition
   library: '@northguild/gmt'
-  library_version: '1.18.0'
+  library_version: '1.19.0'
 ---
 
 # GMT Integration
@@ -84,9 +89,15 @@ which lint package to install for Date-ban enforcement.
      names the instant the zone gives.
 6. **Lint packages are toolchain-specific, not mutually exclusive.** Recommend
    only the one matching the project's existing linter; do not force all three.
-7. **Read the READMEs.** This skill is a routing pointer. For full integration
-   guidance, read the installed package's `README.md` and the matching
-   `@northguild/gmt-eslint` / `gmt-oxlint` / `gmt-biome` README.
+7. **Read the docs site and the lint README.** This skill is a routing pointer.
+   For full integration guidance, read these:
+   - `https://gmt-dox.northguild.workers.dev/llms.txt` is the map of every docs page.
+   - Each page has a `.md` twin that holds its text, for example
+     `https://gmt-dox.northguild.workers.dev/guides/integration/app-integration.md`.
+   - The JSDoc ships in the installed package:
+     `node_modules/@northguild/gmt/dist/**/*.d.ts`.
+   - For lint setup, read the matching `@northguild/gmt-eslint` / `gmt-oxlint` /
+     `gmt-biome` README.
 
 ## Lint package selection
 
@@ -119,6 +130,10 @@ the pattern.
 
 ## References
 
-- [README — Install and Design Philosophy](README.md)
+- [Docs map for agents (llms.txt)](https://gmt-dox.northguild.workers.dev/llms.txt)
+- [Install](https://gmt-dox.northguild.workers.dev/install/)
+- [App integration guide](https://gmt-dox.northguild.workers.dev/guides/integration/app-integration/)
+- [Nanosecond precision guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/nanosecond-precision/)
+- [Foreign epoch bridges guide](https://gmt-dox.northguild.workers.dev/guides/conversion/foreign-epoch-bridges/)
 - [Lint Package Selection guide](/guides/integration/linting/)
 - [Core Rules](/core-rules/)

package/skills/gmt-timezone/SKILL.md

@@ -1,22 +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,
+  real boundaries (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a
+  local day, floorToZone/bucketRange, calendar-annotated strings, transport legs
+  (transitTime, etaAtZone, dwellTime, crossingTime, scheduleDelivery), cut-offs
+  (cutoffAt, cutoffSchedule, isPastCutoff, timeToCutoff), punctuality
+  (scheduleDeviation, classifyPunctuality, punctualityRate, bestAvailable,
+  estimateDrift over PLN/EST/REQ/ACT, nextDeparture), free time (freeTimeExpiry,
+  chargeableDays, demurrageClock), billingTimeline, bolTimestamp, multimodalETA,
+  EDI timestamps (parseEdifactDateTime, parseX12DateAndTime, x12TimeCodeOffset,
+  parseEpcisEvent, classify*/format*/isValid*), operating hours
+  (OperatingSchedule, recurringWindows, operatingIntervals, isOpenAt,
+  nextOpenAt, nextCloseAt, operatingTimeBetween, addOperatingTime), and daylight
+  time (isInDaylightSaving, hasDaylightSaving).
 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:apps/dox/src/content/docs/guides/industries/*.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'
@@ -31,6 +34,7 @@ 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'
@@ -40,10 +44,16 @@ sources:
   - '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'
+  - 'northguild/gmt:packages/gmt/src/intermodal/format/index.ts'
+  - 'northguild/gmt:packages/gmt/src/intermodal/parse/index.ts'
+  - 'northguild/gmt:packages/gmt/src/intermodal/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/edi.ts'
+  - 'northguild/gmt:packages/gmt/src/types/epcis.ts'
+  - 'northguild/gmt:packages/gmt/src/types/two-digit-year.ts'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.18.0'
+  library_version: '1.19.0'
 ---
 
 # GMT Timezone
@@ -69,6 +79,9 @@ converting between time zones, or doing arithmetic that must respect DST.
 - 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 reading or writing a UN/EDIFACT `DTM` value, an X12 date, time,
+  time code or date time period, or a GS1 EPCIS event time, and must know
+  whether its offset was stated.
 - 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
@@ -115,11 +128,11 @@ 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.
 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
@@ -291,7 +304,83 @@ converting between time zones, or doing arithmetic that must respect DST.
     `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
+20. **A B/L date is a local date; a multimodal ETA keeps transit and dwell
+    apart.** `bolTimestamp(value, event, { timeZone })` returns the
+    `YYYY-MM-DD` date on the local clock in `timeZone` at the instant `value`:
+    DCSA Bill of Lading 3.0 types `issueDate`, `receivedForShipmentDate` and
+    `shippedOnBoardDate` as dates with no time or offset. `event` is
+    `"issue" | "received" | "shippedOnBoard"`, one per DCSA date field; all
+    three render the same way and anything else is `""`. `timeZone` is
+    required (no UTC default): the place of issue for `issue`, the loading
+    terminal for `received` and `shippedOnBoard`. 21:00 in New York
+    is 01:00Z the next day, so the UTC date is wrong. Only the instant is read;
+    a zoneless value is `""`. `multimodalETA(legs, { startTimeZone? })` takes
+    `scheduleDelivery`'s `Leg[]` and returns `{ eta, totalLegs, totalTransit,
+    totalDwell }`: transit is the legs' durations added up, dwell the time
+    actually spent at handoffs (a wait for a scheduled departure included; the
+    last leg's `dwellAfter` excluded), both with hours as the largest unit, and
+    they sum to the elapsed time. Every `scheduleDelivery` rule applies, so a
+    missed connection is `null`. An empty array is `{ eta: "", totalLegs: 0,
+    totalTransit: "PT0S", totalDwell: "PT0S" }`. Dwell is never estimated.
+21. **An EDI timestamp is read by the function for its kind of value, and
+    nothing the code does not state is guessed.** Each kind has a `parse…`,
+    `format…` and `isValid…` function named for it (`parseEdifactDate`,
+    `formatEdifactDate`, `isValidEdifactDate`), and `format` is typed to that
+    kind's codes. UN/EDIFACT `DTM` (value 2380 against format code 2379):
+    `EdifactDate` (`102`), `EdifactTime` (`401`, `402`), `EdifactDateTime`
+    (`203`, `204`), `EdifactOffsetDateTime` (`205`, `208`, `303`, `304`),
+    `EdifactDatePeriod` (`718`), `EdifactDateTimePeriod` (`719`). X12 (element
+    1251 against qualifier 1250, in `DTP` and `DTM-05`/`06`): `X12Date` (`D8`,
+    `DB`), `X12Time` (`TM`, `TS`), `X12DateTime` (`DT`, `RTS`), `X12DateRange`
+    (`RD8`, `RD`), `X12DateTimeRange` (`RDT`, `DTS`). `parseX12Time(value)`
+    with no `format` reads element 337, tenths and hundredths included
+    (`"14300012"` is `"14:30:00.12"`), and `formatX12TimeElement(value, form)`
+    writes it in the mask named: `HHMM`, `HHMMSS`, `HHMMSSD` or `HHMMSSDD`
+    (`"14:30:00"` under `HHMMSSDD` is `"14300000"`). A parser returns one value:
+    `"2024-06-15"`, `"14:30:00"`, `"2024-06-15T14:30:00"`,
+    `"2024-06-15T14:30:00+02:00"` (the string `toOffsetInstant` reads), or
+    `{ start, end }` for a period or range. The sentinel is `""`, or `null`
+    for a period, a range, a zone or a classifier. A period formatter takes
+    `(start, end, format)`. No EDI function takes options. X12 freight is
+    three calls: `parseX12DateAndTime("20240615", "1430")` is
+    `"2024-06-15T14:30:00"` (elements 373 and 337 of `AT7`, `G62` or `DTM`,
+    both required), `x12TimeCodeOffset("20")` is `"-05:00"`, and
+    `resolveLocal(local, offset)` is `"2024-06-15T19:30:00Z"`. For a code
+    held as a plain string, `classifyEdifactDtmFormat`,
+    `classifyX12DateTimePeriodFormat` and `classifyX12TimeCode` return
+    `{ kind, format }` or `{ kind, timeCode }`, or `null` for a code no
+    function reads; testing `kind` narrows the code with no cast.
+    `parseEpcisEvent({ eventTime, eventTimeZoneOffset })` returns
+    `{ instant, offset, local }`; both fields are required and need not
+    agree. Five no-guess rules. (a) An offsetless value never becomes UTC:
+    `203`, `204`, `DT`, `RTS` and `parseX12DateAndTime` return a local
+    date-time; pass it and an IANA zone to `resolveLocal`. (b) A named X12
+    time code is a zone name, not an offset: `x12TimeCodeZone("ES")` is
+    `{ zone: "Eastern", daylight: false }` and `ET` has `daylight: null`,
+    while `x12TimeCodeOffset` reads `01`–`29`, `UT` and `GM`, and `13`–`24`
+    count down (`13` is `-12:00`). Each returns its sentinel for the other's
+    codes. (c) The `ZZZ` of `303` and `304` is an offset only: `+02`, `UTC`
+    and `GMT` are read, and letters such as `CET` return `""`. (d) A
+    two-digit year is not read by any EDI function: `101`, `201`, `202`,
+    `206`, `207`, `301`, `302`, `713`, `717`, `D6`, `TT`, `TR`, `RD6` and
+    `TU`. Read one with `parseDateWithPattern` or `parseDateTimeWithPattern`,
+    a `yy` pattern and `{ yearWindow }`: a start year such as `2000` (a fixed
+    window, for stored data) or `"rolling"` (50 years before the current UTC
+    year to 49 after). Without `yearWindow` a `yy` pattern returns `""`. (e)
+    `209`, `404`, `406`, `TC`, `EH`, `DDT`, `DTD`, `RTM` and `UN` are not
+    read: none states one date, time or date-time. A UN/EDIFACT period has no
+    hyphen (`2024061520240620` under `718`) and an X12 range has one
+    (`20240615-20240620` under `RD8`); a reversed one returns the sentinel.
+    Pass a UN/EDIFACT parser the unescaped value (`+02`, not `?+02`). A
+    formatter cuts seconds and fractions to its mask and never rounds.
+    It writes `ZZZ` as `±HH`, and `+05:30` under `303` or `304` returns `""`:
+    use `205` or `208`. Each value validator is true exactly when its parser
+    returns a value (`isValidX12DateAndTime(date, time)` for the freight
+    pair), and `isValidEdifactDtmFormat`, `isValidX12DateTimePeriodFormat`
+    and `isValidX12TimeCode` check a code alone. `isValidEpcisEvent` is
+    `isValidEpcisEventTime` and `isValidEpcisTimeZoneOffset` together: the
+    `epcisEventTime` regex matches `2024-02-30`, the validator does not.
+22. **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,7 +396,7 @@ 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
+23. **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`
@@ -329,7 +418,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.**
+24. **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 +437,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.
+25. **Read the docs site.** This skill is a routing pointer. The map of the
+    docs is `https://gmt-dox.northguild.workers.dev/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,7 +460,8 @@ 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`
+- **Offset-preserving instants**: `toOffsetInstant`, `fromOffsetInstant`,
+  `isValidUtcOffset` (the pair's `±HH:MM[:SS]` offset; not `Z`, not `+0530`)
 - **Local-time resolution**: `classifyLocal`, `resolveLocal`
 - **Zone-aware buckets**: `floorToZone`, `bucketRange`,
   `isValidZoneBucketUnit`
@@ -384,10 +475,24 @@ converting between time zones, or doing arithmetic that must respect DST.
 - **Free time and demurrage**: `freeTimeExpiry`, `chargeableDays`,
   `demurrageClock`
 - **Billing deadlines**: `billingTimeline`
+- **Bill of lading dates and multimodal ETA**: `bolTimestamp`, `multimodalETA`
+- **EDI and event timestamps**: `parseEdifactDate`, `parseEdifactTime`,
+  `parseEdifactDateTime`, `parseEdifactOffsetDateTime`,
+  `parseEdifactDatePeriod`, `parseEdifactDateTimePeriod`, `parseX12Date`,
+  `parseX12Time`, `parseX12DateTime`, `parseX12DateRange`,
+  `parseX12DateTimeRange`, `parseX12DateAndTime`, `x12TimeCodeOffset`,
+  `x12TimeCodeZone`, `classifyEdifactDtmFormat`,
+  `classifyX12DateTimePeriodFormat`, `classifyX12TimeCode`,
+  `parseEpcisEvent`; a `format…` and an `isValid…` for each `parseEdifact…`
+  kind, for `X12Date`, `X12Time`, `X12DateTime`, `X12DateRange` and
+  `X12DateTimeRange`, and for `EpcisEvent`; `formatX12TimeElement`,
+  `isValidX12DateAndTime`, `isValidEpcisEventTime`,
+  `isValidEpcisTimeZoneOffset`, `isValidEdifactDtmFormat`,
+  `isValidX12DateTimePeriodFormat`, `isValidX12TimeCode`
 - **Operating hours**: `recurringWindows`, `operatingIntervals`, `isOpenAt`,
   `nextOpenAt`, `nextCloseAt`, `operatingTimeBetween`, `addOperatingTime`
 
 ## References
 
-- [README — Timezone and Calendar examples](README.md)
+- [Zoned operations guide](https://gmt-dox.northguild.workers.dev/guides/zoned-date-operations/zoned-operations/)
 - [DST Disambiguation guide](https://gmt-dox.northguild.workers.dev/guides/concepts/dst-disambiguation/)

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;

package/dist/internal/utcZonedDateTime.js

@@ -1,31 +0,0 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../utc/validate/isValidUtc.js";
-import { normalizeTimeZone } from "./normalizeTimeZone.js";
-/**
- * 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 function utcZonedDateTime(value, options) {
-    if (!isValidUtc(value))
-        return null;
-    const timeZone = normalizeTimeZone(options?.timeZone);
-    if (timeZone === "")
-        return null;
-    try {
-        return Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
-    }
-    catch {
-        return null;
-    }
-}