Add orientation CLI and config documentation

docs/config.md

@@ -0,0 +1,130 @@
+# weatherapi Configuration
+
+`weatherapi` uses a feedapi YAML config file. This file configures the HTTP
+server, database handles, and text template directory used by the service.
+
+## Discovery
+
+The executable chooses the config path in this order:
+
+1. `-config /path/to/config.yml`
+2. non-blank `WEATHERAPI_CONFIG`
+3. `config.yml`
+
+See [`docs/cli.md`](cli.md) for command examples.
+
+## Minimal Config
+
+```yaml
+server:
+  listen_addr: ":8080"
+  default_format: json
+
+databases:
+  - name: weatherdb
+    driver: postgres
+    uri: postgres://localhost:5432/weatherdb?sslmode=disable
+    username: weatherapi
+    password: change-me
+
+templates:
+  base_dir: templates
+```
+
+A maintained copy is available at
+[`examples/config.minimal.yml`](../examples/config.minimal.yml).
+
+## Production-Oriented Config
+
+Use explicit server timeouts, connection pool settings, and secret placeholders
+for production deployments:
+
+```yaml
+server:
+  listen_addr: ":8080"
+  default_format: json
+  read_timeout: 5s
+  write_timeout: 10s
+  idle_timeout: 120s
+
+databases:
+  - name: weatherdb
+    driver: postgres
+    uri: postgres://postgres.example.internal:5432/weatherdb?sslmode=require
+    username: weatherapi
+    password: ${WEATHERAPI_DB_PASSWORD}
+    max_open_conns: 10
+    max_idle_conns: 5
+    conn_max_lifetime: 30m
+    conn_max_idle_time: 5m
+
+templates:
+  base_dir: templates
+```
+
+A maintained copy is available at
+[`examples/config.production.yml`](../examples/config.production.yml).
+
+## Reference
+
+### `server`
+
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `listen_addr` | No | `:8080` | Address passed to the HTTP server. |
+| `default_format` | No | `json` | Response format used when neither `format` nor `Accept` selects one. Supported values are `json`, `xml`, and `text`. |
+| `read_timeout` | No | feedapi default | HTTP server read timeout. |
+| `write_timeout` | No | feedapi default | HTTP server write timeout. |
+| `idle_timeout` | No | feedapi default | HTTP keep-alive idle timeout. |
+
+### `databases`
+
+`databases` must contain at least one entry. `weatherapi` opens all configured
+databases and uses the first entry as the primary weather data store for all
+implemented reads.
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `name` | Yes | Database handle name. The first configured name is selected as primary by `cmd/weatherapi`. |
+| `driver` | Yes | Database driver. The implemented deployment uses `postgres`. |
+| `uri` | Yes | PostgreSQL connection URI. |
+| `username` | Yes | Database username. |
+| `password` | Yes | Database password. Use secret injection in real deployments. |
+| `max_open_conns` | No | Maximum open connections for the database pool. |
+| `max_idle_conns` | No | Maximum idle connections for the database pool. |
+| `conn_max_lifetime` | No | Maximum lifetime for pooled connections. |
+| `conn_max_idle_time` | No | Maximum idle time for pooled connections. |
+
+The database must already contain the weatherfeeder-owned tables read by
+`weatherapi`. This service does not ingest weather data and does not create or
+migrate those tables.
+
+### `templates`
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `base_dir` | Yes | Directory containing the `*.txt.tmpl` files used for text responses. |
+
+The repository includes templates under [`templates/`](../templates/). The
+Docker image copies this directory to `/weatherapi/templates` and runs with
+`/weatherapi` as the working directory.
+
+## Validation and Defaults
+
+Configuration is loaded by feedapi. `cmd/weatherapi` adds one local validation
+rule: at least one database entry is required.
+
+Documented server defaults come from feedapi. Unknown YAML fields are not
+documented as rejected by `weatherapi`; treat unrecognized fields as unsupported
+configuration.
+
+## Secrets
+
+Do not commit production passwords, tokens, private hostnames, or private
+connection strings. The examples use placeholders. Inject real values through
+your deployment tooling before starting the service.
+
+## Related Docs
+
+- [`docs/cli.md`](cli.md): command-line usage and config path precedence
+- [`docs/api.md`](api.md): HTTP format negotiation and API behavior