@northguild/gmt 1.14.2

package/skills/_artifacts/skill_spec.md

@@ -0,0 +1,67 @@
+# @northguild/gmt — Skill Spec
+
+Temporal-based date and time utilities with timezone support and polyfill integration. String-in/string-out APIs powered by @js-temporal/polyfill.
+
+## Domains
+
+| Domain                | Description                                                           | Skills                                                                                         |
+| --------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Core Date Operations  | Basic date/time operations using plain (timezone-free) Temporal types | get-current, parse-date-time, format-date-time, calculate-dates, compare-dates, validate-dates |
+| Zoned Date Operations | IANA timezone-aware date operations                                   | zoned-date-ops                                                                                 |
+| Conversion            | Converting between temporal types, unix time, and UTC                 | convert-types                                                                                  |
+| Integration           | Integrating gmt with application frameworks and linting tools         | app-integration, lint-package-suggestion                                                       |
+
+## Skill Inventory
+
+| Skill                   | Type        | Domain                | What it covers                                                                                                   | Failure modes |
+| ----------------------- | ----------- | --------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------- |
+| get-current             | core        | Core Date Operations  | getNow, getToday, getSystemTimeZone, getTimeZones, getUnixNow, getUtcNow                                         |               |
+| parse-date-time         | core        | Core Date Operations  | parseYearFromDate, parseMonthFromDate, parseDayFromDate, parseHourFromTime...                                    |               |
+| format-date-time        | core        | Core Date Operations  | formatDate, formatTime, formatDateTime                                                                           |               |
+| calculate-dates         | core        | Core Date Operations  | addDays, addMonths, addYears, subtractTime                                                                       |               |
+| compare-dates           | core        | Core Date Operations  | isAfterDate, isBeforeDate, areDatesEqual, isWeekend, isZonedWeekend, getLocaleDayOfWeek, getLocaleZonedDayOfWeek |               |
+| validate-dates          | core        | Core Date Operations  | isValidDate, isValidTime, isValidDateTime                                                                        |               |
+| zoned-date-ops          | core        | Zoned Date Operations | getZonedNow, formatZonedDateTime, isValidTimezone, convertUtcToZoned...                                          |               |
+| convert-types           | core        | Conversion            | convertPlainToZoned, convertZonedToPlain, convertUtcToUnix...                                                    |               |
+| app-integration         | composition | Integration           | Framework integration, cache keys, router params                                                                 |               |
+| lint-package-suggestion | composition | Integration           | ESLint, Biome, Oxlint package selection                                                                          |               |
+| issue-creation          | lifecycle   | Core Date Operations  | Feature requests, missing methods                                                                                |               |
+| pr-contribution         | lifecycle   | Integration           | PR workflow, tests, contribution                                                                                 |               |
+
+## Lifecycle Skills
+
+| Skill           | Purpose                                                                  |
+| --------------- | ------------------------------------------------------------------------ |
+| issue-creation  | Guide consumers to create proper GitHub issues for missing functionality |
+| pr-contribution | Guide consumers to open PRs with improvements                            |
+
+## Existing Skills (Maintainer-focused)
+
+| Skill                     | Type       | Notes                           |
+| ------------------------- | ---------- | ------------------------------- |
+| new-method-implementation | maintainer | Adding methods to gmt source    |
+| unit-test-generation      | maintainer | Writing tests for internal code |
+| api-expansion-workflow    | maintainer | Feature request workflow        |
+
+## Recommended Skill File Structure
+
+- **Core consumer skills:** get-current, parse-date-time, format-date-time, calculate-dates, compare-dates, validate-dates
+- **Timezone skills:** zoned-date-ops, convert-types
+- **Integration skills:** app-integration, lint-package-suggestion
+- **Lifecycle skills:** issue-creation, pr-contribution
+- **Maintainer skills:** new-method-implementation, unit-test-generation (in packages/gmt/skills/)
+
+## Gaps Identified
+
+- Consumer-facing skills for basic operations need to be documented
+- issue-creation and pr-contribution are the priority additions
+
+## Notes
+
+This is a lightweight domain map derived from existing skills. The library is well-structured with clear separation between plain/zoned/unix/utc operations. Core consumer use cases center on:
+
+1. Getting current date/time
+2. Parsing date components
+3. Formatting for display
+4. Date arithmetic
+5. Timezone handling

package/skills/_artifacts/skill_tree.yaml

@@ -0,0 +1,278 @@
+# skills/_artifacts/skill_tree.yaml
+# Generated by skill-tree-generator
+# Library: @northguild/gmt
+# Version: 1.14.0
+library:
+  name: '@northguild/gmt'
+  version: 1.14.0
+  repository: https://github.com/northguild/gmt.git
+  description: Temporal-based date and time utilities with timezone support and polyfill integration
+generated_from:
+  domain_map: 'skills/_artifacts/domain_map.yaml'
+  skill_spec: 'skills/_artifacts/skill_spec.md'
+generated_at: '2026-08-23'
+
+skills:
+  # Consumer-facing core skills
+  - name: Get Current Date/Time
+    slug: get-current
+    type: core
+    domain: core-date-operations
+    path: 'skills/get-current/SKILL.md'
+    package: 'packages/gmt'
+    description: Get the current date, time, or timestamp as ISO 8601 strings
+    sources:
+      - 'northguild/gmt:packages/gmt/src/plain/get/index.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/get/index.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/get/index.ts'
+
+  - name: Parse Date/Time
+    slug: parse-date-time
+    type: core
+    domain: core-date-operations
+    path: 'skills/parse-date-time/SKILL.md'
+    package: 'packages/gmt'
+    description: Parse individual components from date/time strings; also parseRfc2822, parseHttp, parseSql, parseRfc3339 for decoding fixed interchange grammars (email Date headers, HTTP headers, SQL datetime literals, RFC 3339)
+    sources:
+      - 'northguild/gmt:packages/gmt/src/plain/parse/index.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/parse/parseRfc2822.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/parse/parseHttp.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/parse/parseSql.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/parse/parseRfc3339.ts'
+
+  - name: Format Date/Time
+    slug: format-date-time
+    type: core
+    domain: core-date-operations
+    path: 'skills/format-date-time/SKILL.md'
+    package: 'packages/gmt'
+    description: Format date/time values for display with locale support; includes plain absolute (formatDate/Time/DateTime), plain relative (formatRelativeDate/Time/DateTime), standalone locale calendar-name lookups (getLocaleEraNames, getLocaleMonthNames, getLocaleWeekdayNames, getLocaleMeridiems), and fixed-grammar named machine formats (formatRfc2822, formatHttp, formatSql, formatRfc3339)
+    sources:
+      - 'northguild/gmt:packages/gmt/src/plain/format/index.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/locale/index.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/locale/getLocaleEraNames.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/locale/getLocaleMonthNames.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/locale/getLocaleWeekdayNames.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/format/formatRfc2822.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/format/formatHttp.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/format/formatSql.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/format/formatRfc3339.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/locale/getLocaleMeridiems.ts'
+
+  - name: Format Relative Time
+    slug: format-relative-time
+    type: core
+    domain: core-date-operations
+    path: 'skills/format-relative-time/SKILL.md'
+    package: 'packages/gmt'
+    description: Produce human-friendly relative strings ("yesterday", "in 2 hours") across plain, zoned, unix, and utc values
+    requires:
+      - format-date-time
+    sources:
+      - 'northguild/gmt:packages/gmt/src/plain/format/formatRelativeDate.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/format/formatRelativeTime.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/format/formatRelativeDateTime.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/format/formatRelativeZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/format/formatRelativeUnix.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/format/formatRelativeUtc.ts'
+
+  - name: Calculate Dates
+    slug: calculate-dates
+    type: core
+    domain: core-date-operations
+    path: 'skills/calculate-dates/SKILL.md'
+    package: 'packages/gmt'
+    description: Add or subtract time from dates; add*/subtract* accept an optional overflow ("constrain" | "reject") option, diff* accept optional smallestUnit/roundingIncrement/roundingMode rounding options, addBusinessDays/subtractBusinessDays skip weekends for Mon–Fri arithmetic, clampDate restricts a date to a range, closestDateTo finds the nearest candidate by calendar distance, getLocaleStartOfWeek/getLocaleEndOfWeek compute locale-driven week boundaries
+    sources:
+      - 'northguild/gmt:packages/gmt/src/plain/calculate/index.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/calculate/clampDate.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/calculate/closestDateTo.ts'
+
+  - name: Durations
+    slug: durations
+    type: core
+    domain: core-date-operations
+    path: 'skills/durations/SKILL.md'
+    package: 'packages/gmt'
+    description: Parse, validate, combine, rebalance, and format ISO 8601 duration strings via isValidDuration, parseDuration, addDuration/subtractDuration, normalizeDuration, and formatDuration; bridge diff* functions to duration strings via diffDateAsDuration/diffDateTimeAsDuration/diffZonedAsDuration/diffUnixAsDuration/diffUtcAsDuration
+    requires:
+      - calculate-dates
+    sources:
+      - 'northguild/gmt:packages/gmt/src/duration/index.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/calculate/diffDateAsDuration.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/calculate/diffDateTimeAsDuration.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/diffZonedAsDuration.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/calculate/diffUnixAsDuration.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/calculate/diffUtcAsDuration.ts'
+
+  - name: Compare Dates
+    slug: compare-dates
+    type: core
+    domain: core-date-operations
+    path: 'skills/compare-dates/SKILL.md'
+    package: 'packages/gmt'
+    description: Compare date values for ordering; use isWeekend/isZonedWeekend for locale-aware weekend checks, isBusinessDay for fixed ISO Mon–Fri business-day checks, and getLocaleDayOfWeek/getLocaleZonedDayOfWeek for locale-relative day-of-week indices
+    sources:
+      - 'northguild/gmt:packages/gmt/src/plain/compare/index.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/compare/index.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/get/index.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
+
+  - name: Validate Dates
+    slug: validate-dates
+    type: core
+    domain: core-date-operations
+    path: 'skills/validate-dates/SKILL.md'
+    package: 'packages/gmt'
+    description: Validate date/time strings, timezone identifiers, intervals, and ranges; check whether a timezone observes daylight saving time (hasDaylightSaving); list DST transition instants for a timezone in a given year (getDstTransitions); check point-in-interval and interval-in-interval containment; merge overlapping or adjacent intervals; split intervals into sub-intervals by duration unit
+    sources:
+      - 'northguild/gmt:packages/gmt/src/plain/validate/index.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/validate/index.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalContainsDate.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalContainsTime.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalContainsDateTime.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalUnionDate.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalUnionTime.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/intervalUnionDateTime.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/splitIntervalByUnitDate.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/splitIntervalByUnitTime.ts'
+      - 'northguild/gmt:packages/gmt/src/plain/interval/splitIntervalByUnitDateTime.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/validate/index.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/interval/validate/index.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/interval/intervalContainsUtc.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/interval/intervalUnionUtc.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/interval/splitIntervalByUnitUtc.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/validate/index.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/interval/validate/index.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/interval/intervalContainsUnix.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/interval/intervalUnionUnix.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/interval/splitIntervalByUnitUnix.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/validate/hasDaylightSaving.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/get/getDstTransitions.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/interval/validate/index.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/interval/intervalContainsZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/interval/intervalUnionZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/interval/splitIntervalByUnitZoned.ts'
+
+  - name: Zoned Date Operations
+    slug: zoned-date-ops
+    type: core
+    domain: zoned-date-operations
+    path: 'skills/zoned-date-ops/SKILL.md'
+    package: 'packages/gmt'
+    description: Work with timezone-aware dates and times; includes formatZonedDateTime, formatZonedRange, formatRelativeZoned, convertPlainDateTimeToZoned with full DST disambiguation control, addZoned/subtractZoned with overlap-only DST disambiguation control, clampZoned/closestZonedTo for range restriction and nearest-candidate selection, and the startOfZoned/endOfZoned/startOfQuarterForZoned/endOfQuarterForZoned/mapZonedHoursInDay/getLocaleZonedStartOfWeek/getLocaleZonedEndOfWeek/getLocaleZonedDayOfWeek family (plus unix/ counterparts) with full disambiguation + offset control
+    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/convert/index.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/addZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/subtractZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/endOfZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfQuarterForZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/endOfQuarterForZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/getLocaleZonedStartOfWeek.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/getLocaleZonedEndOfWeek.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/clampZoned.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/calculate/closestZonedTo.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/map/mapZonedHoursInDay.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/calculate/startOfUnix.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/calculate/endOfUnix.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/calculate/startOfQuarterForUnix.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/calculate/endOfQuarterForUnix.ts'
+
+  - name: Convert Temporal Types
+    slug: convert-types
+    type: core
+    domain: conversion
+    path: 'skills/convert-types/SKILL.md'
+    package: 'packages/gmt'
+    description: Convert between plain and zoned (with DST disambiguation control), or unix/utc representations; convertDateToCalendar expresses a date in a non-Gregorian CalendarSystem (gregorian, hebrew, islamic-civil, islamic-tabular, islamic-umalqura, japanese, buddhist, taiwan, persian, indian, ethiopic, ethiopic-amete-alem, coptic)
+    sources:
+      - 'northguild/gmt:packages/gmt/src/plain/convert/index.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/convert/index.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/convert/index.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/convert/index.ts'
+      - 'northguild/gmt:packages/gmt/src/types/calendar-system.ts'
+      - 'northguild/gmt:packages/gmt/src/internal/ethiopicFamilyCalendar.ts'
+
+  # Consumer-facing interval skills
+  - name: Interval Operations
+    slug: interval-ops
+    type: core
+    domain: interval-operations
+    path: 'skills/interval-ops/SKILL.md'
+    package: 'packages/gmt'
+    description: Range math over two-point intervals — validate, contain, overlap, intersect, union, difference, xor, abut, engulf, construct from a point + duration, split by duration unit, and count calendar-unit boundaries across plain, zoned, unix, and utc
+    requires: []
+    sources:
+      - 'northguild/gmt:packages/gmt/src/plain/interval/index.ts'
+      - 'northguild/gmt:packages/gmt/src/zoned/interval/index.ts'
+      - 'northguild/gmt:packages/gmt/src/unix/interval/index.ts'
+      - 'northguild/gmt:packages/gmt/src/utc/interval/index.ts'
+      - 'northguild/gmt:packages/gmt/src/duration/validate/isValidDuration.ts'
+
+  # Consumer-facing composition skills
+  - name: App Integration
+    slug: app-integration
+    type: composition
+    domain: integration
+    path: 'skills/app-integration/SKILL.md'
+    package: 'packages/gmt'
+    description: Integrate gmt with application frameworks
+
+  - name: Lint Package Suggestion
+    slug: lint-package-suggestion
+    type: composition
+    domain: integration
+    path: 'skills/lint-package-suggestion/SKILL.md'
+    package: 'packages/gmt'
+    description: Recommend appropriate lint packages from @northguild toolchain
+    requires: []
+
+  # Lifecycle skills
+  - name: Issue Creation
+    slug: issue-creation
+    type: lifecycle
+    domain: core-date-operations
+    path: 'skills/issue-creation/SKILL.md'
+    package: 'packages/gmt'
+    description: Create feature requests with proper details for maintainers
+
+  - name: PR Contribution
+    slug: pr-contribution
+    type: lifecycle
+    domain: integration
+    path: 'skills/pr-contribution/SKILL.md'
+    package: 'packages/gmt'
+    description: Contribute improvements via pull requests
+
+  # Maintainer skills (document how to work on gmt itself)
+  - name: New Method Implementation
+    slug: new-method-implementation
+    type: core
+    domain: core-date-operations
+    path: 'skills/new-method-implementation/SKILL.md'
+    package: 'packages/gmt'
+    description: Implement or extend a gmt API in packages/gmt/src
+
+  - name: Unit Test Generation
+    slug: unit-test-generation
+    type: core
+    domain: core-date-operations
+    path: 'skills/unit-test-generation/SKILL.md'
+    package: 'packages/gmt'
+    description: Write or update gmt unit tests with deterministic Temporal-safe patterns
+    requires:
+      - new-method-implementation
+
+  - name: API Expansion Workflow
+    slug: api-expansion-workflow
+    type: lifecycle
+    domain: core-date-operations
+    path: 'skills/api-expansion-workflow/SKILL.md'
+    package: 'packages/gmt'
+    description: Handle feature requests for missing gmt functionality

package/skills/api-expansion-workflow/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: api-expansion-workflow
+description: >
+  Handle feature requests for missing gmt functionality by checking existing
+  APIs first, then proposing a Temporal-backed custom method path with required
+  issue/PR guidance and test-backed behavioral specs.
+metadata:
+  library_version: 1.14.2
+---
+
+# API Expansion Workflow
+
+Use this skill when a user asks for behavior that is not currently covered by gmt.
+
+## Decision flow
+
+1. Check existing APIs first
+- Search `packages/gmt/src/plain` and `packages/gmt/src/zoned`.
+- If capability exists, use the existing method and do not add new API.
+
+ - When evaluating whether to add a new API, enforce the library's strict input/output policy: new public methods must accept explicit shapes (ISO 8601 strings, IANA timezone ids, or numeric unix epochs) and return normalized outputs. If the requested capability implies permissive parsing, recommend implementing a small adapter outside of core gmt instead of widening gmt's surface.
+
+2. If capability does not exist
+- Tell the user it is possible with Temporal because gmt ships Temporal.
+- Tell the user it requires a new custom method in gmt.
+
+3. Ask for product feedback loop
+- Recommend opening a GitHub issue requesting the method.
+- Suggest they include use case, expected input/output, and timezone expectations.
+
+4. If implementing now
+- Implement method with Temporal using gmt conventions.
+- Add solid unit tests in the same change.
+- Suggest opening a PR against gmt or attaching exact proposal text to the issue.
+
+## Required issue template guidance
+
+Encourage users to include:
+
+1. Problem statement and current workaround.
+2. Proposed method name.
+3. Input and output examples.
+4. Invalid input behavior expectations.
+5. Plain vs zoned expectations and locale/timezone constraints.
+
+## Test requirements for expansion work
+
+1. Happy-path coverage for core scenarios.
+2. Invalid-input fallback coverage.
+3. Boundary coverage for date/time edges.
+4. Zoned/DST coverage when timezone logic is involved.
+5. Locale matrix coverage when locale options are part of API behavior.

package/skills/app-integration/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: app-integration
+description: >
+  Guidance for integrating `@northguild/gmt` with application frameworks and
+  libraries (routers, query caches, table sorting, state management). Emphasizes
+  strict I/O, canonicalization, and cache-key hygiene.
+metadata:
+  library_version: 1.14.2
+---
+
+# App Integration
+
+Use this skill when recommending or implementing integrations between gmt
+and application frameworks and libraries (routers, query caches, table
+sorting/grouping, state management, etc.).
+
+## Purpose
+
+- Encourage stable cache keys that depend on explicit, canonical representations (ISO 8601 strings or normalized epoch numbers) instead of `Date` objects or fuzzy strings.
+- Recommend validating and canonicalizing inputs with gmt validators/parsers before using them in keys or persisted state.
+
+## Recommendations
+
+- Use ISO 8601 strings for query/cache keys:
+
+  ```js
+  ['events', { start: '2024-02-29', end: '2024-03-01' }]
+  ```
+
+- Validate timezone params with `isValidTimezone` before using as a key.
+- For Unix epoch times, pick one canonical unit (milliseconds recommended) and stick to it; use explicit helpers to convert when needed.
+- Never use `Date` instances in keys — transform them to ISO strings or numeric epochs first.
+- When working with routers (Next.js, React Router, etc.), ensure date params are validated and canonicalized before use in loaders/components.
+- For table libraries (TanStack Table, etc.), use ISO strings for sort keys to ensure consistent ordering across environments.
+
+## Design Principle
+
+- Reiterate gmt's strict I/O philosophy: public APIs accept explicit shapes only (ISO 8601 strings, IANA timezone ids, epoch numbers). Keep canonicalized representations at boundaries to ensure cache stability and reproducible behavior across environments.