# @kody/environment — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke checks, and edge cases. No user secrets. Do not disable
live webhooks or jobs.

## Secrets

None. Uses public Open-Meteo, Nominatim, and sunrise-sunset.org. Durable caches:
`weatherCache`, `forecastHistory` in packageStorage.

## Import paths

| Export | Import |
| --- | --- |
| overview + AQI helpers | `kody:@kody/environment` |
| air-quality | `kody:@kody/environment/air-quality` |
| elevation | `kody:@kody/environment/elevation` |
| forecast-history | `kody:@kody/environment/forecast-history` |
| moon | `kody:@kody/environment/moon` |
| snapshot | `kody:@kody/environment/snapshot` |
| sun | `kody:@kody/environment/sun` |
| weather | `kody:@kody/environment/weather` |
| weather-geocode | `kody:@kody/environment/weather-geocode` |

Prefer static `kody:@kody/environment/...` imports from `execute`.
Do not lead with `packages.invoke`.

Named root helpers: `getAirQuality`, `summarizeAirQuality`. There is **no**
default home location — always pass `location` or `latitude` + `longitude`.

## Smoke test (read-only)

```ts
import { summarizeAirQuality } from 'kody:@kody/environment'

export default async function main() {
	return await summarizeAirQuality({ location: 'Reykjavík' })
}
```

Combined outdoor snapshot:

```ts
import environmentSnapshot from 'kody:@kody/environment/snapshot'

export default async function main() {
	return await environmentSnapshot({ location: 'Tokyo' })
}
```

Moon (no external API):

```ts
import moon from 'kody:@kody/environment/moon'

export default async function main() {
	return await moon({})
}
```

Geocode then weather:

```ts
import weatherGeocode from 'kody:@kody/environment/weather-geocode'
import weather from 'kody:@kody/environment/weather'

export default async function main() {
	const place = await weatherGeocode({ location: 'Denver, CO' })
	return await weather({
		latitude: place.latitude,
		longitude: place.longitude,
	})
}
```

By coordinates with a label:

```ts
import { summarizeAirQuality } from 'kody:@kody/environment'

export default async function main() {
	return await summarizeAirQuality({
		latitude: 40.7128,
		longitude: -74.006,
		label: 'New York City',
	})
}
```

## Edge cases

- Snapshot sections fail independently — a bad upstream yields `{ error }` for
  that section, not a thrown whole-call failure.
- Weather uses packageStorage cache when live Open-Meteo is degraded.
- Named ESM exports work via static `import { ... }`. For keyless
  `packages.invoke`, use a subpath whose **default export** is the function
  (for example `exportName: "weather"`), or call the root overview.