j126: read bot settings from a .env file (default ./.env, --env-file flag, TR_ENV_FILE); file wins over shell leftovers, boot report labels (source: .env)

docs/env_reference.md

@@ -1,5 +1,29 @@
 # Environment variable reference
 
+## Putting your settings in a .env file
+
+Instead of typing `export ...` in a shell, put your settings in a file. The bot
+reads them for you. This is easier to keep tidy, and no stale shell variable can
+surprise you.
+
+1. In the bot folder, copy `.env.example` to `.env`.
+2. Open `.env` and set the knobs you want. One `KEY=VALUE` per line. Lines
+   starting with `#` are comments.
+3. Start the bot from the bot folder (`./ModularBot`). It picks up `.env`
+   automatically.
+4. To use a different file, pass it on the command line:
+   `./out/ModularBot --env-file /path/to/my.env`.
+5. If you ask for a file that does not exist, the bot stops with an error. A
+   missing default `.env` is fine and its absence is silent.
+
+**The file wins over the shell.** If the same name is set in both places with a
+different value, the file value is used, and the bot prints one line telling you
+which shell value was overridden. Start the report check with:
+`grep '^\[env\]' /tmp/modularbot_stdout.log`. Values that came from the file are
+labelled `(source: .env)`.
+
+---
+
 Every knob the bot reads. **Most are read once per process, at module init; a few
 are read lazily on first use** (`TR_TMHORIZON_SHIFT`/`_BIG_MULT`/`_LOG`/
 `_RESET_ON_TARGET` in `ensureConfig`, `TR_PATTERN_RAD_*` inside `predict`). Either