docs: simplify API usage guidance

Author: andrepimpao

AGENTS.md

@@ -10,13 +10,13 @@ Composer with PSR-4 autoloading under the
 ## Sources Of Truth
 
 - Use the official OpenWeather documentation for endpoint paths, parameters,
-  response fields, availability, and subscription constraints.
+  response fields, and current access requirements.
 - Use the installed PHP API SDK documentation and source for its supported
   authoring patterns.
 - Read existing resources, entities, tests, and documentation before changing
   related behavior.
-- Do not infer API availability from OpenWeather documentation sidebars; verify
-  it against the current official API catalog or pricing information.
+- Do not infer API access from documentation sidebars; verify it against the
+  current official API documentation.
 
 ## Code Changes
 
@@ -71,6 +71,7 @@ Composer with PSR-4 autoloading under the
 - Update public documentation alongside implemented API areas.
 - Keep method signatures, examples, supported endpoints, and response entities
   aligned with the implementation.
-- Clearly distinguish standard free-plan APIs from APIs requiring separate or
-  paid subscriptions.
-- Document potentially billable or destructive behavior prominently.
+- Avoid hard-coded claims about plans, prices, quotas, or allowances. Link to
+  the official OpenWeather documentation for current access requirements.
+- Document destructive behavior and actions that send additional requests
+  prominently.

README.md

@@ -5,9 +5,8 @@
 [![Tests](https://github.com/programmatordev/openweathermap-php-api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/programmatordev/openweathermap-php-api/actions/workflows/ci.yml?query=branch%3Amain)
 
 A fluent PHP client for OpenWeather APIs covering current and forecast weather,
-air pollution, geocoding, maps, stations, and One Call. Responses are mapped to
-typed entities that safely handle conditional, missing, and `null` data while
-keeping common requests concise.
+air pollution, geocoding, maps, stations, and One Call. Responses use typed
+entities that safely handle conditional, missing, and `null` data.
 
 The library is built on
 [`programmatordev/php-api-sdk`](https://github.com/programmatordev/php-api-sdk)
@@ -45,9 +44,9 @@ echo $current->temperature();
 echo $current->temperatureWithUnit();
 ```
 
-Response properties may be missing or explicitly `null`, so entity getters
-return nullable values where appropriate. Collection getters return empty
-arrays when the corresponding response collection is absent or `null`.
+Response properties may be missing or `null`, so getters return nullable values
+where appropriate. Collection getters return empty arrays when the response
+does not contain that collection.
 
 ## Configuration
 

UPGRADE-4.0.md

@@ -1,16 +1,15 @@
 # Upgrading To 4.0
 
-Version 4 is a complete rewrite of the library. Backward compatibility with
-earlier releases is intentionally not preserved, and existing integrations
-should treat this release as a new implementation even where the usage remains
-familiar.
+Version 4 is a complete rewrite. It is not backward compatible with earlier
+releases. Existing integrations should adopt it as a new implementation, even
+where the usage looks familiar.
 
 ## Upgrade Expectations
 
 - Previous resources, entities, methods, namespaces, and configuration are not
   part of the current public contract.
-- Compatibility aliases, deprecated transitional APIs, and an old-to-new API
-  mapping are not provided.
+- Compatibility aliases, transitional APIs, and an old-to-new API mapping are
+  not provided.
 - Integrations should be rebuilt against the current [README](README.md) and
   [API guides](README.md#apis).
 - Application tests should be reviewed and updated before adopting the new
@@ -22,13 +21,11 @@ familiar.
 - The client is built on
   [`programmatordev/php-api-sdk` 3](https://github.com/programmatordev/php-api-sdk).
 - Current weather, forecasts, air pollution, geocoding, maps, stations, and One
-  Call 4.0 are supported. Access depends on the OpenWeather products enabled for
-  the API key.
-- Metric units and English are the defaults, with client-wide configuration and
-  immutable request-local overrides where supported.
-- Response entities tolerate missing, explicitly `null`, conditional, and
-  unknown fields. Known non-null fields with invalid types produce hydration
-  errors.
+  Call 4.0 are supported.
+- Metric units and English are the defaults. They can be configured for the
+  client or changed for one request chain where supported.
+- Response entities accept missing, `null`, conditional, and unknown fields.
+  Known non-null fields with invalid types produce hydration errors.
 - OpenWeather API failures use a documented exception hierarchy; transport,
   decoding, and hydration failures remain distinguishable. See
   [Error Handling](docs/errors.md).

docs/air-pollution.md

@@ -1,7 +1,6 @@
 # Air Pollution
 
-Current, forecast, and historical air pollution are included in OpenWeather's
-standard free and paid subscriptions.
+This guide covers current, forecast, and historical air pollution.
 
 ## Current
 
@@ -103,7 +102,7 @@ Forecast periods use the same OpenWeather Air Quality Index and fixed
 The Historical Air Pollution API returns hourly observations for a coordinate
 and date range. See the
 [official Air Pollution API documentation](https://openweathermap.org/api/air-pollution)
-for availability and API details.
+for API details.
 
 Use `history()` with a latitude, longitude, start date, and end date. The date
 arguments accept any `DateTimeInterface` implementation. The end must be after

docs/errors.md

@@ -1,7 +1,7 @@
 # Error Handling
 
-The library distinguishes unsuccessful OpenWeather responses from local input,
-transport, decoding, and response-mapping failures.
+The library separates OpenWeather API errors from invalid input, HTTP client
+failures, decoding errors, and invalid response data.
 
 ## OpenWeather API Errors
 
@@ -54,7 +54,7 @@ try {
 } catch (TooManyRequestsException $exception) {
     // Defer or slow down further requests.
 } catch (UnauthorizedException $exception) {
-    // Check the API key and its access to the requested product.
+    // Check the API key and whether it can use this endpoint.
 } catch (ApiException $exception) {
     // Handle any other unsuccessful OpenWeather response.
 }
@@ -71,7 +71,7 @@ extend `ApiException`:
 | `Psr\Http\Client\ClientExceptionInterface` | The PSR-18 client could not complete the HTTP request. |
 | `JsonException` | A successful response expected to contain JSON could not be decoded. |
 | `HydrationException` | A known response property contains an invalid type or value. |
-| `UnexpectedValueException` | A non-JSON response, such as a map tile, has an unexpected payload or media type. |
+| `UnexpectedValueException` | A non-JSON response, such as a map tile, has unexpected content or a wrong content type. |
 
 Missing, explicitly `null`, conditional, and unknown response properties are
 tolerated. `HydrationException` is reserved for known non-null properties whose

docs/geocoding.md

@@ -1,7 +1,6 @@
 # Geocoding
 
-The Geocoding API is available on OpenWeather's standard free and paid
-subscriptions. See the
+See the
 [official Geocoding API documentation](https://openweathermap.org/api/geocoding-api)
 for API details.
 

docs/maps.md

@@ -1,8 +1,7 @@
 # Maps
 
 Weather Maps API 1.0 provides current cloud, precipitation, sea-level pressure,
-wind-speed, and temperature overlays. It is available on OpenWeather's standard
-free and paid subscriptions. See the
+wind-speed, and temperature overlays. See the
 [official Weather Maps documentation](https://openweathermap.org/api/weathermaps)
 for API details.
 
@@ -85,7 +84,7 @@ The returned format can be passed to
 [Leaflet](https://leafletjs.com/reference.html#tilelayer),
 [OpenLayers](https://openlayers.org/en/latest/apidoc/module-ol_source_XYZ-XYZ.html),
 or a [MapLibre raster source](https://maplibre.org/maplibre-style-spec/sources/).
-Like a concrete tile URL, the template contains the API key and does not make an
+Like a specific tile URL, the template contains the API key and does not make an
 HTTP request when generated.
 
 ## Tile Coordinates

docs/one-call.md

@@ -1,15 +1,14 @@
 # One Call 4.0
 
-One Call 4.0 requires a separate OpenWeather subscription and includes free
-daily API calls. Consult OpenWeather's official documentation for the current
-allowance, pricing, usage limits, and account configuration before using these
-endpoints in production.
+OpenWeather manages access and usage terms for One Call 4.0. Consult the
+[official One Call documentation](https://openweathermap.org/api/one-call-4)
+for current requirements before using these endpoints.
 
 ## Current
 
 See OpenWeather's
 [official One Call API 4.0 documentation](https://openweathermap.org/api/one-call-4#current)
-for API details and current subscription terms.
+for API details.
 
 Use `current()` with a latitude and longitude.
 
@@ -24,9 +23,9 @@ $current = $api->oneCall()->current(
 );
 ```
 
-Every response property may be absent or explicitly `null`. Coordinates and
-timezone metadata describe the requested location, while `dateTime()` and the
-astronomical timestamps remain UTC values.
+Every response property may be absent or `null`. Coordinates and timezone
+details describe the requested location. `dateTime()`, sunrise, and sunset use
+UTC.
 
 ```php
 echo $current->coordinates()?->latitude();
@@ -53,7 +52,7 @@ $current = $api
     ->current(38.7223, -9.1393);
 ```
 
-Measurement getters return nullable values. Companion methods provide the unit
+Measurement getters return nullable values. Related methods provide the unit
 and a formatted value. With the default metric configuration, for example:
 
 ```php
@@ -80,7 +79,7 @@ $timeline = $api->oneCall()->minuteTimeline(
 );
 ```
 
-The response exposes location metadata and forecast periods. Each period
+The response contains location details and forecast periods. Each period
 provides its UTC date and time, precipitation, and any referenced alert IDs.
 
 ```php
@@ -124,7 +123,7 @@ Use `startAt` to select a future starting point and `count` to limit the number
 of periods returned. Both are optional, and `count` must be positive when
 provided.
 
-The response exposes location metadata, up to 50 periods, and pagination when
+The response contains location details, up to 50 periods, and pagination when
 OpenWeather provides it.
 
 ```php
@@ -138,8 +137,8 @@ foreach ($timeline->periods() as $period) {
 }
 ```
 
-The 15-minute, one-hour, and one-day timelines normalize OpenWeather's
-fractional precipitation probability to a percentage:
+Precipitation probability follows the same getter pattern as other
+measurements:
 
 ```php
 $period->precipitationProbability();          // 91.0
@@ -177,8 +176,8 @@ $timeline = $api->oneCall()->hourTimeline(
 );
 ```
 
-The response contains up to 20 periods. Historical and forecast periods expose
-their UTC date and time through `dateTime()`.
+The response contains up to 20 periods. `dateTime()` returns each period's UTC
+date and time.
 
 ```php
 foreach ($timeline->periods() as $period) {
@@ -220,9 +219,9 @@ $timeline = $api->oneCall()->dayTimeline(
 );
 ```
 
-The response contains up to 10 periods. Daily periods provide UTC dates,
-astronomy, daily temperatures, weather measurements, conditions, precipitation
-probability, rain, snow, and alert references.
+The response contains up to 10 periods. Daily periods provide UTC dates, sun
+and moon times, daily temperatures, weather measurements, conditions,
+precipitation probability, rain, snow, and alert references.
 
 ```php
 foreach ($timeline->periods() as $period) {
@@ -237,12 +236,12 @@ foreach ($timeline->periods() as $period) {
 }
 ```
 
-OpenWeather does not currently define units for the daily scalar rain and snow
-values, so these getters return raw nullable floats.
+OpenWeather does not define units for the daily `rain` and `snow` values, so
+these getters return nullable floats without conversion.
 
 ## Timeline Pagination
 
-The 15-minute, one-hour, and one-day timelines provide explicit pagination.
+The 15-minute, one-hour, and one-day timelines support pagination.
 
 ```php
 $timeline = $api->oneCall()->hourTimeline(
@@ -266,11 +265,8 @@ echo $pagination->nextPageUrl();
 
 The availability checks and URL getters do not make another API request.
 `previousPage()` and `nextPage()` request the corresponding page when its URL
-is available and otherwise return `null`. Pagination does not iterate
-automatically. Every pagination request counts as a separate One Call API call
-under your OpenWeather subscription; consult the
-[official documentation](https://openweathermap.org/api/one-call-4#pagination)
-for current usage and billing terms.
+is available and otherwise return `null`. The library does not fetch every page
+automatically. Each page navigation sends a separate API request.
 
 ## Alert
 
@@ -308,7 +304,7 @@ foreach ($current->alertIds() as $id) {
 }
 ```
 
-Alerts provide sender and event information, validity dates, localized
+Alerts provide sender and event information, start and end times, localized
 descriptions, and tags.
 
 `description()` returns the first exact language-code match or `null`.

docs/setup.md

@@ -2,16 +2,16 @@
 
 `OpenWeatherMap` uses PHP API SDK's `setup()` method for client-wide HTTP
 configuration. Most applications can rely on PHP-HTTP discovery and use the
-client without additional setup. Configure the following extension points when
-the application needs to provide its own infrastructure or request behavior.
+client without additional setup. Use the options below when the application
+needs its own HTTP services or request behavior.
 
 ```php
 use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
 
 $api = new OpenWeatherMap($_ENV['OPENWEATHERMAP_API_KEY']);
 ```
 
-The examples below use infrastructure supplied by the application:
+The examples below use objects supplied by the application:
 `$httpClient` implements PSR-18, `$cachePool` implements PSR-6, and `$logger`
 implements PSR-3.
 
@@ -31,7 +31,7 @@ Use `client()` to provide a specific PSR-18 client instead.
 $api->setup()->client($httpClient);
 ```
 
-The returned client builder can also receive custom request and stream
+`client()` returns a builder that can also receive custom request and stream
 factories.
 
 See the official PHP API SDK
@@ -40,9 +40,9 @@ for all client and factory options.
 
 ## Cache
 
-Use `cache()` with a PSR-6 cache pool to cache eligible HTTP responses. The
-fallback TTL is used when a response does not provide a supported cache
-directive. GET and HEAD requests are cacheable by default. Packagist lists
+Use `cache()` with a PSR-6 cache pool to cache supported HTTP responses. The
+default TTL sets the cache lifetime when a response does not provide one. GET
+and HEAD requests are cacheable by default. Packagist lists
 available [PSR-6 cache implementations](https://packagist.org/providers/psr/cache-implementation).
 
 ```php
@@ -53,7 +53,8 @@ $api
 ```
 
 Cache configuration is client-wide. After configuring a pool, `withCache()` can
-override cache behavior for one immutable request chain.
+change cache behavior for one request chain without changing the client-wide
+settings.
 
 ```php
 use ProgrammatorDev\Api\Builder\CacheBuilder;
@@ -99,7 +100,7 @@ $retryPlugin = new RetryPlugin([
 $api->setup()->plugins()->add($retryPlugin, priority: 25);
 ```
 
-Retries make additional OpenWeather requests and can affect quotas or billing.
+Retries may send additional OpenWeather requests.
 Plugin priority controls middleware order. Priority `25` places this retry
 plugin after authentication and before cache; consult the linked documentation
 when choosing priorities for other plugins.
@@ -128,9 +129,9 @@ $api->setup()->hooks()->beforeRequest(
 );
 ```
 
-Return a PSR-7 request to replace it for the remainder of the request pipeline,
-or return `null` when no replacement is required. Response hooks follow the
-same pattern with a PSR-7 response.
+Return a PSR-7 request to use it for the current request, or return `null` to
+keep the original request. Response hooks follow the same pattern with a PSR-7
+response.
 
 See the official PHP API SDK
 [hook documentation](https://github.com/programmatordev/php-api-sdk/blob/main/docs/13-hooks.md)