feat: add phase-1 human heat helpers

README.md

@@ -312,6 +312,31 @@ Dedicated method guide:
 
 - [docs/thi_workflow.md](docs/thi_workflow.md)
 
+Human heat first-pass note:
+
+- toolkit now also exposes xclim-backed `humidex` helper functions for people
+- this is phase-1 continuous metric support, not full human hazard
+  classification
+- `WBGT` and `UTCI` are intentionally deferred until wind/radiation support is
+  more coherent across intended workflows
+
+Python users can inspect current human-heat choice directly:
+
+```python
+from climate_tookit.climatology import (
+    compute_daily_humidex,
+    describe_human_heat_method,
+    describe_human_heat_source_support,
+)
+
+print(describe_human_heat_method()["metric"])
+print(describe_human_heat_source_support())
+```
+
+Dedicated method guide:
+
+- [docs/human_heat_workflow.md](docs/human_heat_workflow.md)
+
 Example:
 
 ```bash

analysis/issues/issue_human_heat_propagation.md

@@ -0,0 +1,46 @@
+## Summary
+
+Propagate phase-1 human heat metric support through package workflows.
+
+Current state:
+- `climate_tookit.climatology.human_heat_stress` now provides xclim-backed
+  `humidex` helpers
+- method choice and source audit resolved in `#91`
+
+Missing:
+- `climate_statistics` summaries
+- `compare_periods` outputs
+- `calculate_hazards` decision on whether generic human heat classes belong in
+  hazard workflow yet
+
+## Scope
+
+Use `humidex` as current human heat metric. Do not reopen `WBGT` / `UTCI`
+selection here.
+
+## Tasks
+
+1. `climate_statistics`
+- add optional human heat summary block when humidity or dewpoint-backed inputs
+  exist
+- keep output explicit that this is continuous metric support
+
+2. `compare_periods`
+- add human heat summary in baseline/focal/future comparisons where source
+  support exists
+
+3. `calculate_hazards`
+- decide whether phase-1 stops at continuous metric
+- if any bands are added, label them as generic screening, not definitive
+  occupational-health thresholds
+
+4. docs/tests
+- update docs and CLI examples
+- add regression tests across supported and unsupported source patterns
+
+## Acceptance criteria
+
+- human heat summary available in at least `climate_statistics`
+- compare-period reporting path documented or implemented
+- hazard-layer stance explicit
+- no false claim that toolkit supports full `WBGT`/`UTCI` workflow

analysis/issues/issue_human_heat_stress_planning.md

@@ -0,0 +1,118 @@
+## Issue #91 human heat-stress method note
+
+## Decision
+
+Phase 1 human heat metric should be `humidex`, implemented through `xclim`.
+
+Phase 1 scope:
+- continuous metric support only
+- no hazard-band semantics yet
+- no claim that `humidex` is globally best physiological metric
+
+Reason:
+- package can support `humidex` from daily mean temperature plus humidity or
+  dewpoint
+- this works across current historical source paths better than `WBGT` or
+  `UTCI`
+- future-path support is possible where `nex_gddp` has `hurs`
+
+## Candidate review
+
+### `humidex`
+
+Selected first.
+
+Pros:
+- available in `xclim`
+- accepts dewpoint or relative humidity path
+- fits current package input coverage
+- feasible for:
+  - `agera_5`
+  - `nasa_power`
+  - humidity-enabled stations / custom uploads
+  - conditional `nex_gddp` runs with `hurs`
+
+### `heat_index`
+
+Not selected as first default.
+
+Reason:
+- `xclim` supports it, but notes validity only for temperatures above `20C`
+- equation assumes instantaneous temperature and humidity, while toolkit mostly
+  works with daily summaries
+- less attractive as first global default for mixed tropical / highland /
+  Andean workflows
+
+### `UTCI`
+
+Deferred.
+
+Reason:
+- `xclim` supports it
+- operational workflow needs temperature, humidity, wind, and mean radiant
+  temperature or radiation terms
+- current package does not have coherent future-path support for those broader
+  inputs
+
+### `WBGT`
+
+Deferred.
+
+Reason:
+- broader radiation / wind treatment needed for operational use
+- current package source coverage is not coherent enough for first-pass future
+  workflow
+
+## Source audit
+
+### Strong first-pass support
+
+- `agera_5`
+  - humidity available through current dewpoint + air-temperature derivation
+- `nasa_power`
+  - humidity available in current fetch path
+- `ghcn_daily`, `gsod`, `custom_station`
+  - supported when humidity / dewpoint fields exist
+
+### Conditional support
+
+- `nex_gddp`
+  - usable for `humidex` only when Earth Engine `hurs` exists for selected
+    model / scenario / period
+
+### Weak or unsupported
+
+- `era_5`
+  - current runtime path does not expose operational humidity support clearly
+- `chirps_v2`, `chirps_v3_daily_rnl`, `imerg`, `tamsat`
+  - no human heat metric support as standalone sources
+- `chirts`
+  - temperature-only path, insufficient for `humidex`
+
+## Package direction
+
+Immediate implementation slice:
+1. add `climate_tookit.climatology.human_heat_stress`
+2. expose `compute_daily_humidex()` helper
+3. expose source-support + method-description helpers
+4. add tests
+
+Later propagation:
+1. `climate_statistics`
+2. `compare_periods`
+3. `calculate_hazards`
+
+## References used for decision
+
+- local `xclim` runtime/docstrings:
+  - `humidex(tas, tdps=None, hurs=None)`
+  - `heat_index(tas, hurs)` with validity note above `20C`
+  - `universal_thermal_climate_index(tas, hurs, sfcWind, mrt|radiation...)`
+- toolkit source audit in current repo
+
+## Closing logic
+
+`#91` can close once:
+- method choice accepted
+- helper lands
+- remaining propagation work split into implementation follow-up if needed

climate_tookit/climatology/__init__.py

@@ -11,10 +11,13 @@
 __all__ = [
     "build_thi_hazard_thresholds",
     "classify_thi_values",
+    "compute_daily_humidex",
     "compute_monthly_spei",
     "compute_monthly_spi",
     "compute_daily_thi",
     "compute_daily_vpd",
+    "describe_human_heat_method",
+    "describe_human_heat_source_support",
     "describe_thi_method",
     "DEFAULT_LIVESTOCK_CLIMATE_PROFILE",
     "DEFAULT_LIVESTOCK_TYPE",
@@ -24,6 +27,7 @@
     "prepare_monthly_climatic_water_balance",
     "prepare_monthly_precipitation_totals",
     "resolve_thi_profile",
+    "summarize_humidex_period",
     "summarize_vpd_period",
     "summarize_thi_periods",
     "assess_xclim_precip_annual_readiness",
@@ -38,6 +42,14 @@
 
 
 def __getattr__(name: str):
+    if name in {
+        "compute_daily_humidex",
+        "describe_human_heat_method",
+        "describe_human_heat_source_support",
+        "summarize_humidex_period",
+    }:
+        module = import_module(".human_heat_stress", __name__)
+        return getattr(module, name)
     if name in {
         "build_thi_hazard_thresholds",
         "classify_thi_values",