feat: explicit --mode / HOSTDOC_MODE + mode-derivation footgun warning (#39)

README.md

@@ -160,6 +160,25 @@ published docs"*, *"open aws-design"*, *"remove aws-design"*.
 
 Flags (`--bucket/--region/...`) > `HOSTDOC_*` env vars > `~/.config/hostdoc/config.json`.
 
+Precedence merges **fields**, but the **mode** is derived from the merged
+result (`domain`+`distribution` → cloudfront; `serveRoot` → self-hosted; else
+`bucket`+`region` → s3-website). So setting only `HOSTDOC_BUCKET` on top of a
+cloudfront config file does **not** switch to s3-website — the file's `domain`
+still wins the derivation, and the bucket is ignored for mode (hostdoc prints a
+warning when it detects this).
+
+To pin the mode regardless of which fields merged in, use `--mode` or
+`HOSTDOC_MODE` (`s3-website` | `cloudfront` | `self-hosted`, case-insensitive):
+
+```bash
+# force s3-website for a one-off, even though the config file is cloudfront
+HOSTDOC_BUCKET=demo-bucket HOSTDOC_REGION=us-east-1 \
+  hostdoc publish ./x.html --mode s3-website
+```
+
+A forced mode validates only that mode's required fields and ignores the
+others (printing a note about what it ignored).
+
 ## License
 
 MIT