From 256ae90371fb816853270f74049afc6ea3e052c1 Mon Sep 17 00:00:00 2001
From: Elif Demir <elif@example.org>
Date: Wed, 8 Apr 2026 16:20:00 +0300
Subject: [PATCH] docs: describe the configuration file

---
 README.md             | 11 +++++++++++
 docs/configuration.md | 28 ++++++++++++++++++++++++++++
 docs/install.md       |  2 ++
 3 files changed, 41 insertions(+)
 create mode 100644 docs/configuration.md

diff --git a/README.md b/README.md
index c6f4d571a1d1c4998658780032e52caffba0c23e..364b939983e7b9c3f0298525166ac1afcd01b2ad 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,17 @@ $ hello-hut --time-of-day Grace
 Good evening, Grace!
 ```
 
+## Configuration
+
+Defaults can live in `~/.config/hello-hut/config.toml`:
+
+```toml
+name = "Ada"
+shout = false
+```
+
+Every key is described in [docs/configuration.md](docs/configuration.md).
+
 ## License
 
 MIT — see [LICENSE](LICENSE).
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000000000000000000000000000000000000..b8e2b06b3518c3be792d124c4c10668b4b804ea6
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,28 @@
+# Configuration
+
+hello-hut reads optional defaults from
+`$XDG_CONFIG_HOME/hello-hut/config.toml`, falling back to
+`~/.config/hello-hut/config.toml`. Options given on the command line always
+win over the file.
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `name` | string | Who to greet when no `NAME` is given |
+| `shout` | boolean | Shout by default |
+
+Example:
+
+```toml
+# ~/.config/hello-hut/config.toml
+name = "Ada"
+shout = false
+```
+
+## Notes
+
+- Reading the file needs Python 3.11 or newer (for `tomllib`); on older
+  versions it is ignored.
+- Unknown keys are ignored, so you will not recieve an error for a misspelt
+  key. Double-check the spelling if a setting seems to have no effect.
+
+See also: [installation](install.md).
diff --git a/docs/install.md b/docs/install.md
index 0063cde5b106a1aba4268437a21e68e187b85eaf..719aa222cbc485b047474dd49e749c20d7d45d9b 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -21,3 +21,5 @@ To try it without installing anything:
 ```sh
 PYTHONPATH=src python3 -m hello_hut Ada
 ```
+
+Next: [configure hello-hut](configuration.md).