@northguild/gmt 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@northguild/gmt",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Temporal-based date and time utilities with timezone support and polyfill integration",
   "keywords": [
     "date",
@@ -35,10 +35,9 @@
     "dist",
     "LICENSE",
     "README.md",
-    "skills/gmt-basics",
-    "skills/gmt-arithmetic",
-    "skills/gmt-timezone",
-    "skills/gmt-integration"
+    "skills",
+    "!skills/_artifacts",
+    "!skills/contributor"
   ],
   "type": "module",
   "sideEffects": false,
@@ -55,6 +54,9 @@
       "calendar/calculate": [
         "./dist/calendar/calculate/index.d.ts"
       ],
+      "calendar/hours": [
+        "./dist/calendar/hours/index.d.ts"
+      ],
       "calendar/validate": [
         "./dist/calendar/validate/index.d.ts"
       ],
@@ -79,18 +81,39 @@
       "duration/validate": [
         "./dist/duration/validate/index.d.ts"
       ],
+      "duty": [
+        "./dist/duty/index.d.ts"
+      ],
+      "duty/calculate": [
+        "./dist/duty/calculate/index.d.ts"
+      ],
+      "duty/validate": [
+        "./dist/duty/validate/index.d.ts"
+      ],
       "instant": [
         "./dist/instant/index.d.ts"
       ],
       "instant/convert": [
         "./dist/instant/convert/index.d.ts"
       ],
+      "instant/validate": [
+        "./dist/instant/validate/index.d.ts"
+      ],
       "intermodal": [
         "./dist/intermodal/index.d.ts"
       ],
       "intermodal/calculate": [
         "./dist/intermodal/calculate/index.d.ts"
       ],
+      "intermodal/format": [
+        "./dist/intermodal/format/index.d.ts"
+      ],
+      "intermodal/parse": [
+        "./dist/intermodal/parse/index.d.ts"
+      ],
+      "intermodal/validate": [
+        "./dist/intermodal/validate/index.d.ts"
+      ],
       "interval": [
         "./dist/interval/index.d.ts"
       ],
@@ -175,6 +198,9 @@
       "transport/calculate": [
         "./dist/transport/calculate/index.d.ts"
       ],
+      "transport/compare": [
+        "./dist/transport/compare/index.d.ts"
+      ],
       "transport/convert": [
         "./dist/transport/convert/index.d.ts"
       ],
@@ -290,6 +316,10 @@
       "types": "./dist/calendar/calculate/index.d.ts",
       "default": "./dist/calendar/calculate/index.js"
     },
+    "./calendar/hours": {
+      "types": "./dist/calendar/hours/index.d.ts",
+      "default": "./dist/calendar/hours/index.js"
+    },
     "./calendar/validate": {
       "types": "./dist/calendar/validate/index.d.ts",
       "default": "./dist/calendar/validate/index.js"
@@ -322,6 +352,18 @@
       "types": "./dist/duration/validate/index.d.ts",
       "default": "./dist/duration/validate/index.js"
     },
+    "./duty": {
+      "types": "./dist/duty/index.d.ts",
+      "default": "./dist/duty/index.js"
+    },
+    "./duty/calculate": {
+      "types": "./dist/duty/calculate/index.d.ts",
+      "default": "./dist/duty/calculate/index.js"
+    },
+    "./duty/validate": {
+      "types": "./dist/duty/validate/index.d.ts",
+      "default": "./dist/duty/validate/index.js"
+    },
     "./instant": {
       "types": "./dist/instant/index.d.ts",
       "default": "./dist/instant/index.js"
@@ -330,6 +372,10 @@
       "types": "./dist/instant/convert/index.d.ts",
       "default": "./dist/instant/convert/index.js"
     },
+    "./instant/validate": {
+      "types": "./dist/instant/validate/index.d.ts",
+      "default": "./dist/instant/validate/index.js"
+    },
     "./intermodal": {
       "types": "./dist/intermodal/index.d.ts",
       "default": "./dist/intermodal/index.js"
@@ -338,6 +384,18 @@
       "types": "./dist/intermodal/calculate/index.d.ts",
       "default": "./dist/intermodal/calculate/index.js"
     },
+    "./intermodal/format": {
+      "types": "./dist/intermodal/format/index.d.ts",
+      "default": "./dist/intermodal/format/index.js"
+    },
+    "./intermodal/parse": {
+      "types": "./dist/intermodal/parse/index.d.ts",
+      "default": "./dist/intermodal/parse/index.js"
+    },
+    "./intermodal/validate": {
+      "types": "./dist/intermodal/validate/index.d.ts",
+      "default": "./dist/intermodal/validate/index.js"
+    },
     "./interval": {
       "types": "./dist/interval/index.d.ts",
       "default": "./dist/interval/index.js"
@@ -450,6 +508,10 @@
       "types": "./dist/transport/calculate/index.d.ts",
       "default": "./dist/transport/calculate/index.js"
     },
+    "./transport/compare": {
+      "types": "./dist/transport/compare/index.d.ts",
+      "default": "./dist/transport/compare/index.js"
+    },
     "./transport/convert": {
       "types": "./dist/transport/convert/index.d.ts",
       "default": "./dist/transport/convert/index.js"

package/skills/gmt-arithmetic/SKILL.md

@@ -11,12 +11,18 @@ description: >
   (BusinessCalendar, RollConvention, isBusinessDay, addBusinessDays,
   subtractBusinessDays, businessDaysBetween, nextBusinessDay,
   previousBusinessDay, rollDate, mergeCalendars), overflow "constrain" month-end
-  clamping, splitIntervalByUnit* stepping from the anchor, maxPieces limits,
+  clamping, splitIntervalByUnit* anchor stepping, maxPieces limits,
   intervalCount* matching bucketRange, RFC 9557 calendar strings, and the
-  correct-at-the-edges guarantees at the first and last representable instant. A
-  routing pointer, not an API dump.
+  correct-at-the-edges guarantees at the representable limits, and hours-of-work
+  rules over a duty log (evaluateDutyLog, dutyViolations, dutyDayFor).
 sources:
-  - 'northguild/gmt:README.md'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/plain-arithmetic.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/durations.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/spans.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/business-calendars.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/core-date-operations/calendar-systems.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/intervals/*.mdx'
+  - 'northguild/gmt:apps/dox/src/content/docs/guides/concepts/correct-at-the-edges.mdx'
   - 'northguild/gmt:packages/gmt/src/plain/calculate/index.ts'
   - 'northguild/gmt:packages/gmt/src/duration/index.ts'
   - 'northguild/gmt:packages/gmt/src/interval/index.ts'
@@ -29,10 +35,12 @@ sources:
   - 'northguild/gmt:packages/gmt/src/calendar/business/index.ts'
   - 'northguild/gmt:packages/gmt/src/types/business-calendar.ts'
   - 'northguild/gmt:packages/gmt/src/types/roll-convention.ts'
+  - 'northguild/gmt:packages/gmt/src/duty/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/duty.ts'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.17.0'
+  library_version: '1.19.0'
 ---
 
 # GMT Arithmetic
@@ -53,12 +61,40 @@ and full interval set operations.
   these windows?".
 - The user is measuring elapsed time — a profile, a trace span, a sensor
   interval — and wants milliseconds or nanoseconds rather than a `Duration`.
+- 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. **`add*` takes a `{ unit: number }` object, not an ISO duration string.**
    `addDate("2024-03-15", { days: 5 })` works; `addDate("2024-03-15", "P5D")`
    returns `""`. Use `diffDateAsDuration` / `addDuration` for duration strings.
+   An amount has those two shapes, and each function takes one of them:
+   - **A unit object is checked the same way everywhere.** A unit outside the
+     function's set returns the sentinel: `addDate` takes years to days,
+     `addTime` hours to nanoseconds. So does an own key that is no unit name,
+     and an amount that is not a whole finite number. A unit set to `undefined`
+     is absent, as Temporal reads it.
+   - **`durationFromUnits` is the bridge from the object to the string.** It
+     takes all ten units and carries nothing into a larger unit. Seconds and
+     smaller are written as one decimal number of seconds. Pass its result to
+     any function that takes a duration string.
+   - **`totalUnits` totals the object in one call.** It takes exact units only:
+     days down to nanoseconds, a day being 24 hours. A year, a month or a week
+     returns `null`, as a key and as the unit asked for.
+   - **`totalDuration` totals a duration string**, and takes `relativeTo` for a
+     calendar amount. To total `{ months: 1 }`, build the string with
+     `durationFromUnits` and pass it here.
+
+   ```typescript
+   durationFromUnits({ minutes: 15 }); // "PT15M"
+   durationFromUnits({ minutes: 90 }); // "PT90M" — not carried into hours
+   totalUnits({ minutes: 15 }, "seconds"); // 900
+   totalUnits({ weeks: 1 }, "days"); // null — write { days: 7 }
+   totalUnits("PT15M", "seconds"); // null — a duration string goes to totalDuration
+   totalDuration("PT36H", "days"); // 1.5
+   totalDuration(durationFromUnits({ months: 1 }), "days", { relativeTo: "2024-02-01" }); // 29
+   ```
 2. **Arithmetic clamps; parsers reject.** `overflow` defaults to `"constrain"`,
    Temporal's default: January 31 plus one month is February 29, and
    `addDate("2024-02-29", { years: 1 })` is `"2025-02-28"`. Pass
@@ -96,9 +132,10 @@ and full interval set operations.
    hour on its spring-forward counts 2 hours, and a range over `Pacific/Apia`'s
    deleted 30 December 2011 does not count that day. `intervalCountUnix` counts
    in `options.timeZone`, UTC by default (`"local"` for the system zone).
-5. **Calendar units need `relativeTo`.** `durationAs`, `normalizeDuration`, and
+5. **Calendar units need `relativeTo`.** `totalDuration`, `normalizeDuration`, and
    `compareDurations` return `null`/`""` for year/month/week arithmetic without
-   a `relativeTo` anchor — a month is not a fixed length. A calendar-annotated
+   a `relativeTo` anchor — a month is not a fixed length. `totalUnits` takes no
+   `relativeTo`, so it always returns `null` for those units. A calendar-annotated
    `relativeTo` is read as Temporal reads it: zoned when it has a time zone
    annotation, otherwise a date, and its calendar must be a `CalendarSystem`.
    - `round*` accept singular or plural `smallestUnit` names (`"hour"` or
@@ -213,9 +250,45 @@ and full interval set operations.
     survives only if it is a working day in every input, and returns `null` for an
     empty list. Narrow inputs with `isValidBusinessCalendar` /
     `isValidRollConvention`.
-13. **Read the README.** This skill is a routing pointer. For full option shapes,
-   locale matrices, and code examples, read the installed package's `README.md`
-   and the source JSDoc of the function you intend to call.
+13. **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.
+14. **Read the docs site.** This skill is a routing pointer. For full option
+    shapes, 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/plain-arithmetic.md`.
+    - The JSDoc of the function you intend to call ships in the installed
+      package: `node_modules/@northguild/gmt/dist/**/*.d.ts`.
 
 ## Key functions
 
@@ -231,9 +304,12 @@ and full interval set operations.
   `startOfQuarterForDate`, `getLocaleStartOfWeek` (zoned boundaries: see the
   `gmt-timezone` skill)
 - **Durations (ISO 8601)**: `isValidDuration`, `parseDuration`, `addDuration`,
-  `subtractDuration`, `normalizeDuration`, `durationAs`, `formatDuration`,
+  `subtractDuration`, `normalizeDuration`, `totalDuration`, `formatDuration`,
   `negateDuration`, `absDuration`, `compareDurations`, `getDurationUnit`,
   `getDurationSign`
+- **Unit objects (`{ unit: number }`)**: `durationFromUnits` (object to
+  duration string), `totalUnits` (object to one total), type
+  `ExactDurationUnit`
 - **Diff-to-duration bridge**: `diffDateAsDuration`,
   `diffZonedAsDuration`, `diffUnixAsDuration`, `diffUtcAsDuration`
 - **Interval algebra (half-open, instants)**: `isValidInterval`,
@@ -247,6 +323,11 @@ and full interval set operations.
   `intervalLengthDate`, `intervalDivideEquallyDate`, `mergeIntervalsDate` (each
   with `DateTime`/`Zoned`/`Unix`/`Utc` variants where the type supports it)
 
+- **Hours of work**: `evaluateDutyLog`, `dutyViolations`, `dutyDayFor`,
+  `dutyTotals`, `longestRun`, `qualifyingRests`, `qualifyingRestPairs`,
+  `isValidDutyLog`, types `DutyEntry`, `DutyRule`, `Period`, `LocalPeriod`,
+  `DutyReport`
+
 ## Namespace selection
 
 - `plain/*` — timezone-free dates, times, datetimes
@@ -256,9 +337,15 @@ and full interval set operations.
 - `duration/*` — ISO 8601 duration strings
 - `span/*` — elapsed and wall-clock spans as raw numbers
 - `interval/*` — half-open interval algebra over instant strings
+- `duty/*` — hours-of-work rules over a duty log
 
 ## References
 
-- [README — Quick Start](README.md)
+- [Docs map for agents (llms.txt)](https://gmt-dox.northguild.workers.dev/llms.txt)
+- [Plain arithmetic guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/plain-arithmetic/)
+- [Durations guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/durations/)
+- [Spans guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/spans/)
+- [Business calendars guide](https://gmt-dox.northguild.workers.dev/guides/core-date-operations/business-calendars/)
 - [Interval algebra reference](/reference/interval/calculate/intersectIntervals)
 - [Interval guides](/guides/intervals/interval-basics/)
+- [Hours of work guide](https://gmt-dox.northguild.workers.dev/guides/intervals/hours-of-work/)

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.17.0'
+  library_version: '1.19.0'
 ---
 
 # GMT Basics
@@ -52,42 +62,81 @@ 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
 
 - `formatRelative*` measure from now when `reference` is omitted, so the output
   changes from day to day. Pass `reference` whenever the result must be deterministic.
-- `parseDateWithPattern`, `parseRfc2822` and `parseHttp` return `""` on
+  `largestUnit` takes a singular or plural unit name (`"hour"` or `"hours"`) from the
+  units the function's values have: `formatRelativeDate` day to year, `formatRelativeTime`
+  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), 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 `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.
@@ -123,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.17.0'
+  library_version: '1.19.0'
 ---
 
 # GMT Integration
@@ -48,8 +53,11 @@ which lint package to install for Date-ban enforcement.
    `convertUtcToUnix(value, { epochUnit: "seconds" })` rather than
    dividing/multiplying by hand. An `epochUnit` option must be `"seconds"` or
    `"milliseconds"` (singular accepted): any other value returns the sentinel
-   instead of being read as milliseconds. `unix/` reads zone-dependent fields in
-   UTC unless you pass `timeZone` (`"local"` for the system zone). A
+   instead of being read as milliseconds. `unix/` and `utc/` read zone-dependent
+   fields in UTC unless you pass `timeZone` (`"local"` for the system zone); that
+   holds for the `utc/` readers and converters too, such as `parseHourFromUtc` and
+   `convertUtcToPlainDate`. `convertUtcToZoned` and `convertUnixToZoned` take a
+   required zone and do not accept `"local"`. A
    blank epoch string is invalid, not `1970`, and `sortUnix`/`minUnix`/`maxUnix`
    skip values that are not integer epochs in Temporal's range.
 4. **Nanoseconds are `bigint`, never `number`.** A `number` is exact only to
@@ -75,13 +83,21 @@ which lint package to install for Date-ban enforcement.
      unsynchronized" marker. Check for `0n` yourself before trusting it as 1900.
    - .NET ticks name an instant only when `DateTimeKind` is `Utc`. `Local` and
      `Unspecified` ticks count wall-clock time.
-   - `toNanoseconds` and `isValidInstant` read the offset and ignore a bracketed
-     zone annotation, which is not checked.
+   - `toNanoseconds` and `isValidInstant` read the offset and do not validate a
+     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
    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
 
@@ -114,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/)