@northguild/gmt 1.18.0 → 1.20.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.20.0'
 ---
 
 # GMT Basics
@@ -52,26 +62,38 @@ 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://northguild.dev/gmt/llms.txt` is the map of every docs page.
+   - Each page has a `.md` twin that holds its text, for example
+     `https://northguild.dev/gmt/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`
+  `isValidZonedDateTime`, `isValidDateInterval`, `isValidFiscalPattern`,
+  `isValidFiscalCalendar`, `isValidFiscalExtraWeek`, `isValidFiscalYearLabel`,
+  `hasSecond60`
+- **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 +104,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.
@@ -106,8 +148,14 @@ input before you act on it.
   lacks (`timeStyle` on `formatDate`, `dateStyle` on `formatTime`) returns `""`.
   Zoned formatters return `""`/`[]` for a `timeZone` option: to show an instant
   in another zone, use `formatUtc(value, locale, { timeZone })`.
-- Leap seconds (`:60`) are invalid in every spelling (`T`, `t`, space, basic
-  format). `isLeapSecond` tells you one is there. Validators return `false`.
+- A second of `60` is invalid in every spelling (`T`, `t`, space, basic
+  format), and validators return `false` for it. Two functions tell you about
+  one. `hasSecond60` is the shape test: it is true for any second 60, real or
+  not (`"2024-06-15T12:34:60Z"` is `true`). `isLeapSecond`, from `timescale/`,
+  is the table lookup: it is true only for the 27 inserted leap seconds
+  (`"2016-12-31T23:59:60Z"` is `true`, `"2024-06-15T12:34:60Z"` is `false`).
+  Only the `timescale/` and `gnss/` functions accept a second 60, and only a
+  listed one; see the `gmt-integration` and `gmt-gnss` skills.
 - `isValidTimeZone` accepts every IANA name, including single-component links
   such as `Japan`, `Zulu` and `EST5EDT`, and ignores case. It also accepts
   offset zone ids such as `"+05:00"`, as Temporal does.
@@ -123,14 +171,28 @@ input before you act on it.
   instant has no calendar date until you name a zone — floor it with
   `floorToZone` first, or convert it in the zone you mean.
 - `getFiscalPeriod`'s `yearEndsOn` states the year-end **rule** by example, not
-  one year's end. The NRF 4-5-4 calendar is `"2026-01-31"` — a Saturday on
-  January 31, which is "the Saturday nearest to January 31".
+  one year's end. One published 4-5-4 example (NRF, US) adds a 53rd week when
+  "there are four or more days left in January", which is the Saturday nearest
+  January 31: `"2026-01-31"`, a Saturday on January 31.
+- `getFiscalPeriod` also requires `extraWeek` and `yearLabel`, with no default,
+  because published calendars disagree on both. `extraWeek` is the period a 53rd
+  week is added to: `"firstPeriod"` (ONS, UK) or `"lastPeriod"` (NRF, US).
+  `yearLabel` names the fiscal year: `"startYear"` (NRF, US), `"endYear"`, the
+  year its last day falls in, or `"majorityYear"`, the calendar year holding the
+  most of its days (ONS, UK); a 182/182 split goes to the end year. IFRS 18
+  ¶27(c) (formerly IAS 1 ¶51(c)) lets a period be identified by the date it
+  ends, which supports `"endYear"` and the tie rule. `getQuarter` with options takes
+  `fiscalYearStartMonth` and `yearLabel`, both required. A calendar missing a
+  field returns `null`; check it with `isValidFiscalCalendar`.
 - `isWeekend` is locale-aware via `Intl.Locale.weekInfo`; `isBusinessDay` is
-  fixed ISO Mon–Fri with no locale and no holidays **until you pass it a
+  a fixed Mon–Fri week (Sat–Sun off, CLDR's world default; ISO 8601 defines no
+  weekend) with no locale and no holidays **until you pass it a
   `BusinessCalendar`** — `isBusinessDay(value, { weekend, holidays, timeZone })`
   states the weekend and holidays itself. See the `gmt-arithmetic` skill.
 
 ## References
 
-- [README — API Surface and Quick Start](README.md)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [API reference](https://northguild.dev/gmt/reference/)
+- [Core date operations guides index](https://northguild.dev/gmt/guides/core-date-operations/)
 - [Core date operations guides](/guides/core-date-operations/get-current/)

package/skills/gmt-gnss/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: gmt-gnss
+description: >
+  GNSS time in @northguild/gmt/gnss — the six RINEX GNSS time scales as peers
+  (GPS, GAL, BDT, QZS, GLO, IRN: utcToGnss, gnssToUtc), broadcast weeks by named
+  counter (GnssWeekCounter) with a required rolloverEra (integer, "rolling" or {
+  notBefore }) for gnssWeekToUtc/utcToGnssWeek, and continuous RINEX navigation
+  weeks (rinexWeekToUtc, utcToRinexWeek). 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/gnss-system-time-and-week-rollover.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/maritime-gnss-time-and-week-rollover.mdx'
+  - 'northguild/gmt:packages/gmt/src/gnss/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/gnss.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.20.0'
+---
+
+# GMT GNSS
+
+Use this skill when the task is reading satellite receiver output: a GNSS
+time-scale string, a broadcast week and time of week, or a RINEX navigation
+file week. TAI and the leap-second table are in the `gmt-integration` skill.
+
+## When to load
+
+- The user is reading satellite receiver output: a GNSS time-scale string, a
+  broadcast week and time of week, or a RINEX navigation-file week.
+
+## Core rules
+
+1. **The six GNSS time scales are peers, named by their RINEX 4.02 tokens.**
+   `GPS`, `GAL` (Galileo), `BDT` (BeiDou), `QZS` (QZSS), `GLO` (GLONASS) and
+   `IRN` (NavIC). No system is a default; each goes through the same functions,
+   with the system first.
+   ```typescript
+   utcToGnss("GAL", "2024-01-01T00:00:00Z"); // "2024-01-01T00:00:18 GAL"
+   utcToGnss("BDT", "2024-01-01T00:00:00Z"); // "2024-01-01T00:00:04 BDT"
+   utcToGnss("GPS", "1980-01-06T00:00:00Z"); // "1980-01-06T00:00:00 GPS" (0 s at the epoch)
+   gnssToUtc("IRN", "2024-01-01T00:00:18 IRN"); // "2024-01-01T00:00:00Z"
+   ```
+   - `GLO` is GLONASS time as RINEX reports it: UTC's own hours, leap seconds
+     included, not UTC + 3 h. Remove the three hours from raw system time first.
+   - Each system returns the sentinel before its own epoch. Offsets are nominal:
+     broadcast nanosecond corrections are not applied.
+2. **A broadcast week needs its counter and its era.** `GnssWeekCounter` names
+   one counter with one modulus: `"GPS-LNAV"`, `"QZS-LNAV"`, `"IRN-LNAV"` 1024
+   weeks; `"GAL"` 4096; `"GPS-CNAV"`, `"QZS-CNAV"`, `"BDT"`, `"IRN-L1NV"` 8192.
+   GLONASS has no week counter. `rolloverEra` is required: an integer era for
+   stored data, `"rolling"` for live output (the era within half a counter
+   period of today, so it reads the clock), or `{ notBefore }`, the earliest
+   match at or after an instant you state, such as a firmware build date.
+   ```typescript
+   gnssWeekToUtc("GPS-LNAV", 100, 0, 0); // "1981-12-05T23:59:59Z"
+   gnssWeekToUtc("GPS-LNAV", 100, 0, 1); // "2001-07-21T23:59:47Z"
+   gnssWeekToUtc("GPS-LNAV", 1020, 0, { notBefore: "2019-04-07T00:00:00Z" }); // "2038-10-23T23:59:42Z"
+   utcToGnssWeek("GAL", "2019-04-07T00:00:00Z"); // { week: 1024, timeOfWeekSeconds: 18, era: 0 }
+   ```
+   A RINEX navigation record's week is continuous and never wraps: read it with
+   `rinexWeekToUtc` / `utcToRinexWeek`, not the broadcast functions. A RINEX
+   NavIC week read as a broadcast week is 1024 weeks off.
+   ```typescript
+   rinexWeekToUtc("IRN", 2295, 86418); // "2024-01-01T00:00:00Z"
+   gnssWeekToUtc("IRN-L1NV", 2295, 86418, 0); // "2043-08-17T00:00:00Z" (not the same week)
+   ```
+3. **Second 60 is accepted only on a listed insertion day.** `gnss/` and
+   `timescale/` accept `:60` only on a listed insertion day, and may return
+   `…T23:59:60Z`. Every other GMT function rejects `:60`, so do not pass that
+   result on.
+4. **Convert at the boundary and store the era rule.** Convert a GNSS label to
+   a UTC instant on the way in (`gnssToUtc`, `gnssWeekToUtc`, `rinexWeekToUtc`),
+   and back on the way out. Store the era rule you used with any week you
+   decode.
+5. **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
+
+- **GNSS time scales** (`@northguild/gmt/gnss`): `utcToGnss`, `gnssToUtc`,
+  `gnssWeekToUtc`, `utcToGnssWeek`, `rinexWeekToUtc`, `utcToRinexWeek`, types
+  `GnssSystem`, `GnssWeekCounter`, `RolloverEra`, `GnssWeek`,
+  `RinexWeekSystem`, `RinexWeek`
+
+## References
+
+- [gnss reference](https://northguild.dev/gmt/reference/gnss/)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [GMT Integration skill](../gmt-integration/SKILL.md)

package/skills/gmt-integration/SKILL.md

@@ -3,21 +3,29 @@ name: gmt-integration
 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
+  foreign epoch bridges (NTP, FILETIME, .NET ticks, Excel, PostgreSQL), TAI and
+  the closed IERS leap-second table (taiMinusUtc, leapSecondsBetween,
+  nextLeapSecond, isLeapSecond, toTAI, fromTAI), and lint package selection
+  (ESLint, Biome, Oxlint). GNSS time is in gmt-gnss. 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'
   - 'northguild/gmt:packages/gmt/src/precision/calculate/index.ts'
   - 'northguild/gmt:packages/gmt/src/precision/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/timescale/index.ts'
 metadata:
   type: composition
   library: '@northguild/gmt'
-  library_version: '1.18.0'
+  library_version: '1.20.0'
 ---
 
 # GMT Integration
@@ -32,6 +40,8 @@ which lint package to install for Date-ban enforcement.
 - The user is moving nanosecond timestamps across a JSON wire or into a database.
 - The user is reading or writing another system's epoch — NTP, Windows `FILETIME`,
   .NET ticks, an Excel day serial, or PostgreSQL's internal microseconds.
+- The user needs TAI, TAI − UTC on a date, or whether a `23:59:60` was a real
+  leap second.
 - The user is picking an ESLint, Biome, or Oxlint plugin to ban `Date` APIs.
 - The user has a lint package but not the gmt runtime (or vice versa).
 
@@ -82,11 +92,36 @@ which lint package to install for Date-ban enforcement.
      bracketed zone annotation. One thing is read from it: an offset written to the
      minute that is the zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`)
      names the instant the zone gives.
-6. **Lint packages are toolchain-specific, not mutually exclusive.** Recommend
+6. **Leap seconds come from the built-in table, never a literal.** `timescale/`
+   holds the IERS leap-second table as a closed record: 27 insertions, the last
+   on 2016-12-31, and TAI − UTC stays 37 s for every later date, because UTC
+   becomes continuous on 20 May 2027 (CGPM 2026). No function takes a table.
+   ```typescript
+   taiMinusUtc("2024-01-01T00:00:00Z"); // 37
+   leapSecondsBetween("2000-01-01T00:00:00Z", "2024-01-01T00:00:00Z"); // 5
+   isLeapSecond("2016-12-31T23:59:60Z"); // true (a table lookup)
+   isLeapSecond("2024-06-15T12:34:60Z"); // false (hasSecond60 is the shape test)
+   toTAI("2026-01-01T00:00:00Z"); // "2026-01-01T00:00:37 TAI"
+   fromTAI("2017-01-01T00:00:36 TAI"); // "2016-12-31T23:59:60Z"
+   ```
+   - Before 1972-01-01 TAI − UTC was fractional, so every function returns its
+     sentinel there.
+   - `timescale/` and `gnss/` accept a second 60 only on a listed insertion
+     day (for `gnss/`, see the `gmt-gnss` skill), and may return `…T23:59:60Z`. Every other GMT function rejects `:60`,
+     so do not pass that result on.
+   - A smeared clock never reads `23:59:60` and is up to a second off UTC
+     around an insertion. GMT cannot detect smearing.
+7. **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.
+8. **Read the docs site and the lint README.** This skill is a routing pointer.
+   For full integration guidance, read these:
+   - `https://northguild.dev/gmt/llms.txt` is the map of every docs page.
+   - Each page has a `.md` twin that holds its text, for example
+     `https://northguild.dev/gmt/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
 
@@ -116,9 +151,22 @@ the pattern.
 - **Foreign epochs at the boundary**: convert on the way in and on the way out with
   the `precision/convert/` bridges, and keep ISO strings or `bigint` nanoseconds
   everywhere in between — never carry another system's serial through your own code.
+- **Atomic time at the boundary**: convert a TAI label to a UTC instant on the
+  way in (`fromTAI`), and back on the way out. GNSS time scales and weeks are in
+  the `gmt-gnss` skill.
+
+## Key functions
+
+- **Leap seconds and TAI** (`@northguild/gmt/timescale`): `taiMinusUtc`,
+  `leapSecondsBetween`, `nextLeapSecond`, `isLeapSecond`, `toTAI`, `fromTAI`
 
 ## References
 
-- [README — Install and Design Philosophy](README.md)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [Install](https://northguild.dev/gmt/install/)
+- [App integration guide](https://northguild.dev/gmt/guides/integration/app-integration/)
+- [Nanosecond precision guide](https://northguild.dev/gmt/guides/core-date-operations/nanosecond-precision/)
+- [Foreign epoch bridges guide](https://northguild.dev/gmt/guides/conversion/foreign-epoch-bridges/)
+- [timescale reference](https://northguild.dev/gmt/reference/timescale/)
 - [Lint Package Selection guide](/guides/integration/linting/)
 - [Core Rules](/core-rules/)

package/skills/gmt-intermodal/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: gmt-intermodal
+description: >
+  Intermodal container and freight timing in @northguild/gmt/intermodal — free
+  time and demurrage (freeTimeExpiry, chargeableDays, demurrageClock), billing
+  deadlines (billingTimeline), bill of lading dates and multimodalETA
+  (bolTimestamp), and EDI and event timestamps: UN/EDIFACT DTM, X12 date, time
+  and time code readers and writers (parseEdifact*, parseX12*,
+  parseX12DateAndTime, x12TimeCodeOffset), EPCIS events (parseEpcisEvent). Every
+  tariff term is the caller's. 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/intermodal-bill-of-lading-and-eta.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/intermodal-billing-deadlines.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/intermodal-edi-timestamps.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/industries/intermodal-free-time-and-demurrage.mdx'
+  - '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.20.0'
+---
+
+# GMT Intermodal
+
+Use this skill when the task is container free time and demurrage, billing
+deadlines, bill of lading dates, a multimodal ETA, or reading and writing EDI
+and EPCIS timestamps. The time zone rules it builds on are in the
+`gmt-timezone` skill; leg timing is in the `gmt-transport` skill.
+
+## When to load
+
+- 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.
+
+## Core rules
+
+1. **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.
+2. **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.
+3. **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.
+4. **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.
+5. **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
+
+- **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`
+
+## References
+
+- [intermodal reference](https://northguild.dev/gmt/reference/intermodal/)
+- [Docs map for agents (llms.txt)](https://northguild.dev/gmt/llms.txt)
+- [GMT Timezone skill](../gmt-timezone/SKILL.md)
+- [GMT Transport skill](../gmt-transport/SKILL.md)