Add orientation CLI and config documentation

README.md

@@ -1,36 +1,37 @@
 # weatherapi
 
-A small HTTP API that serves a variety of weather-related endpoints.
+`weatherapi` is a read-only HTTP API for weather data already stored by
+`weatherfeeder` in PostgreSQL. It exposes the latest observations, current
+conditions, alerts, forecasts, discussions, and weather stories as JSON, XML,
+or text.
 
-## Endpoints
+## Quickstart
 
-- `GET /observations`
-- `GET /conditions/current`
-- `GET /alerts/active`
-- `GET /discussion`
-- `GET /discussion/key-messages`
-- `GET /discussion/short-term`
-- `GET /discussion/long-term`
-- `GET /weatherstories`
-- `GET /weatherstories/latest`
-- `GET /forecast/hourly`
-- `GET /forecast/hourly/today`
-- `GET /forecast/hourly/tomorrow`
-- `GET /forecast/narrative`
-- `GET /forecast/narrative/today`
-- `GET /forecast/narrative/tomorrow`
+The service needs a reachable Postgres database with weatherfeeder-owned tables
+and the configured text template directory.
 
-## Query Parameters
+```sh
+go run ./cmd/weatherapi -config config.yml
+```
 
-Shared weather query parameters:
+The checked-in `config.yml` is a local sample. For new deployments, start from
+[`examples/config.minimal.yml`](examples/config.minimal.yml) or
+[`examples/config.production.yml`](examples/config.production.yml) and provide
+database credentials through your normal secret-management process.
 
-- `format` (`json`, `xml`, `text`)
-- `units` (`metric`, `us`)
+## Endpoint Families
 
-Forecast endpoint query parameters:
+- Observations and current conditions
+- Active alerts
+- Hourly and narrative forecasts
+- Forecast discussions
+- Weather stories
 
-- `precision` (`0`-`2`)
+See [`docs/api.md`](docs/api.md) for the HTTP contract.
 
-Forecast, discussion, and weather stories endpoint query parameters:
+## Documentation
 
-- `tz` / `TZ` (IANA timezone, US abbreviation, or UTC offset)
+- [`docs/api.md`](docs/api.md): public HTTP API reference
+- [`docs/cli.md`](docs/cli.md): command-line usage
+- [`docs/config.md`](docs/config.md): YAML configuration reference
+- [`docs/policy/architecture.md`](docs/policy/architecture.md): development architecture and invariants