Document weatherfeeder CLI and configuration

README.md

@@ -1,36 +1,30 @@
 # weatherfeeder
 
-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.
+`weatherfeeder` is a config-driven daemon that polls weather providers, normalizes
+provider-specific responses into canonical weather events, and routes those
+events to configured sinks.
 
-Today, the only implemented sink is `stdout`, which prints JSON-encoded events.
+It currently supports NWS observations, alerts, hourly forecasts, narrative
+forecasts, forecast discussions, and weather stories; Open-Meteo observations
+and hourly forecasts; and OpenWeather observations. Implemented sinks are
+stdout, NATS, and Postgres.
 
-## What weatherfeeder emits
+## Quickstart
 
-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.
+Run the checked-in sample config:
 
-Canonical domain schemas emitted after normalization:
+```sh
+cd cmd/weatherfeeder
+go run .
+```
 
-- `weather.observation.v1` → `WeatherObservation`
-- `weather.forecast.v1` → `WeatherForecastRun`
-- `weather.forecast_discussion.v1` → `WeatherForecastDiscussion`
-- `weather.weather_story.v1` → `WeatherStoryRun`
-- `weather.alert.v1` → `WeatherAlertRun`
+The sample config at `cmd/weatherfeeder/config.yml` is load-tested and can be
+used as a starting point. The executable always reads `config.yml` from its
+current working directory.
 
-For the complete wire contract (event envelope + payload schemas, fields, units, and compatibility rules), see:
+## Documentation
 
-- **API.md**
-
-## Upstream providers (current MVP)
-
-- NWS: observations, hourly forecasts, narrative forecasts, forecast discussions, weather stories, 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.
+- [CLI reference](docs/cli.md)
+- [Configuration reference](docs/config.md)
+- [Architecture policy](docs/policy/architecture.md)
+- [Documentation policy](docs/policy/documentation.md)