Updated documentation and added API.md to document the stable external wire format.

README.md

@@ -1,3 +1,34 @@
 # weatherfeeder
 
-A small daemon to poll weather observations, alerts, and forecasts from a variety of sources. 
+weatherfeeder is a small daemon that polls weather observations, forecasts, and alerts from multiple upstream
+providers, normalizes them into a provider-independent format, and emits them to a sink.
+
+Today, the only implemented sink is `stdout`, which prints JSON-encoded events.
+
+## What weatherfeeder emits
+
+weatherfeeder emits **feed events** encoded as JSON. Each event includes a schema identifier and a payload.
+Downstream consumers should key off the `schema` value and decode the `payload` accordingly.
+
+Canonical domain schemas emitted after normalization:
+
+- `weather.observation.v1` → `WeatherObservation`
+- `weather.forecast.v1` → `WeatherForecastRun`
+- `weather.alert.v1` → `WeatherAlertRun`
+
+For the complete wire contract (event envelope + payload schemas, fields, units, and compatibility rules), see:
+
+- **API.md**
+
+## Upstream providers (current MVP)
+
+- NWS: observations, hourly forecasts, alerts
+- Open-Meteo: observations, hourly forecasts
+- OpenWeather: observations
+
+## Versioning & compatibility
+
+The JSON field names on canonical payload types are treated as part of the wire contract.
+Additive changes are preferred. Renames/removals require a schema version bump.
+
+See **API.md** for details.