update readme

README.md

@@ -2,10 +2,21 @@
 
 Access the Temporal namespace safely, even in environments where it's not natively available.
 
-@agape/temporal provides a drop-in mechanism for working with Temporal objects 
-without requiring the native Temporal API to be installed. If Temporal is 
-unavailable, this library provides stub implementations that raise clear runtime
-errors (`TemporalNotAvailableError`), allowing your code to fail gracefully or fall back to alternatives.
+`@agape/temporal` is designed primarily for **library authors** who need to work with Temporal but can’t guarantee it’s installed in the consumer’s runtime. It provides a drop-in `Temporal` namespace that either uses the real implementation (native or polyfill) or falls back to stubs that throw clear runtime errors. This lets your library **safely reference Temporal types**, fail gracefully when it’s unavailable, and let consumers decide whether to install a polyfill.
+
+Example pattern for library authors:
+
+```typescript
+import { Temporal, hasTemporal } from '@agape/temporal';
+
+export function addHours(hours: number) {
+  if (!hasTemporal()) {
+    throw new Error('Temporal support required for addHours');
+  }
+
+  return Temporal.Now.plainDateTimeISO().add({ hours });
+}
+```
 
 ## 🚀 Get Started
 
@@ -23,7 +34,7 @@ if (hasTemporal()) {
 
 ### With Polyfill
 
-If the native Temporal exists, or  polyfill has been set on the `globalThis`, that
+If the native Temporal exists, or a polyfill has been set on the `globalThis`, that
 will be the implementation used.
 
 ```typescript
@@ -54,7 +65,7 @@ const duration = Temporal.Duration.from('PT1H30M');
 ## 📖 API
 
 ### `Temporal` Namespace
-Use the full Temporal API - `Temporal.PlainDateTime`, `Temporal.PlainDate`, `Temporal.Duration`, etc. Works with real Temporal or provides helpful error stubs.
+Use the full Temporal API — `Temporal.PlainDateTime`, `Temporal.PlainDate`, `Temporal.Duration`, etc. Works with real Temporal or provides helpful error stubs.
 
 ### `hasTemporal(): boolean`
 Check if Temporal is available before using it.
@@ -85,10 +96,24 @@ The error message includes guidance on resolving the issue:
 
 ---
 
+## 🔗 Dependency on `@js-temporal/polyfill`
+
+This package lists `@js-temporal/polyfill` as a dependency so that its **type definitions** are always available at build time.
+
+- **No Runtime Code Included:** The polyfill’s runtime is **never imported or bundled** by `@agape/temporal`.
+- **Safe for Library Authors:** Your consumers remain free to install or omit a polyfill — you are not forcing one into their build.
+- **Tree-Shakable:** Modern bundlers will include nothing from `@js-temporal/polyfill` at runtime unless you explicitly call `setTemporal` with it or attach it to `globalThis` yourself.
+
+This means you can confidently use `Temporal` types in your library’s API surface without bloating your downstream consumers’ bundles.
+
+---
+
 ## 📚 Documentation
 
 See the full API documentation at [agape.dev/api](https://agape.dev/api).
 
+---
+
 ## 📦 Agape Toolkit
 
-This package is part of the [Agape Toolkit](https://github.com/AgapeToolkit/AgapeToolkit) - a comprehensive collection of TypeScript utilities and libraries for modern web development.
+This package is part of the [Agape Toolkit](https://github.com/AgapeToolkit/AgapeToolkit) — a comprehensive collection of TypeScript utilities and libraries for modern web development.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agape/temporal",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Temporal namespace",
   "main": "./cjs/index.js",
   "module": "./es2020/index.js",

src/lib/temporal.spec.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 // Test the temporal library functionality
 describe('@agape/temporal', () => {