Document weatherfeeder CLI and configuration

docs/cli.md

@@ -0,0 +1,70 @@
+# CLI Reference
+
+## Shortest Useful Command
+
+Run `weatherfeeder` from a directory containing `config.yml`:
+
+```sh
+cd cmd/weatherfeeder
+go run .
+```
+
+When using a built binary:
+
+```sh
+./weatherfeeder
+```
+
+## Command Overview
+
+`weatherfeeder` starts a long-running polling daemon. On startup it:
+
+1. reads `config.yml` from the current working directory;
+2. builds configured sources, sinks, and routes;
+3. starts polling sources on their configured intervals;
+4. normalizes and deduplicates events;
+5. dispatches matching events to configured sinks.
+
+The command logs startup, runtime, and shutdown messages to stderr using the Go
+standard logger.
+
+## Flags
+
+There are currently no CLI flags, subcommands, or environment-variable based
+configuration controls.
+
+The config path is fixed at `config.yml` relative to the process current working
+directory. To run with a different config, change the working directory or place
+the desired file at that path.
+
+## Common Workflows
+
+Run the checked-in sample config:
+
+```sh
+cd cmd/weatherfeeder
+go run .
+```
+
+Build and run a local binary:
+
+```sh
+go build -o weatherfeeder ./cmd/weatherfeeder
+cp cmd/weatherfeeder/config.yml .
+./weatherfeeder
+```
+
+Run in the project container image with a mounted config:
+
+```sh
+docker run --rm -v "$PWD/config.yml:/weatherfeeder/config.yml:ro" weatherfeeder
+```
+
+The Docker image sets `/weatherfeeder` as the working directory, so the mounted
+file must appear at `/weatherfeeder/config.yml`.
+
+## Shutdown
+
+Stop the daemon with `Ctrl-C` or `SIGTERM`. The process uses context-aware
+shutdown for scheduler, dispatcher, processors, sources, and sinks, then logs
+`shutdown complete`.