milestone 20: declarative configuration for iac

docs/reference/files-and-directories.md

@@ -10,11 +10,9 @@ snapshots), `src/platform/logging.zig` (the log file).
 Default `/var/lib/nxdns`, overridable with `--data-dir DIR`. `nxdns run` and
 `nxdns import` create it and its parents at mode 0700 when it is missing;
 `nxdns check` and `nxdns export` do not create it. `export` fails if it is not
-there. `check` opens it only on the branch that resolved to the database, so an
-absent data directory is not in itself a failure: an explicit `--config FILE`
-never looks at the directory, and without one `check` falls back to the default
-configuration file, or prints "nothing to check" and exits 2 when neither source
-exists.
+there. `check` opens it only when no `--config FILE` was given: with that flag it
+grades the file and never looks at the directory at all. Without it, an absent
+`config.db` is a failure naming the two ways to get one, exit 2.
 
 `run`, `import` and `export` go through `DataDir.openConfigDb`, which opens
 `config.db` read/write, chmods it to 0600, enables WAL — creating
@@ -39,7 +37,7 @@ older ones from the main file. That is the "uncheckpointed changes" failure in
 
 | Path | What it is | Mode |
 | --- | --- | --- |
-| `config.db` | The configuration database — the single source of truth, including `web.password_hash`. | 0600 |
+| `config.db` | The configuration database, including `web.password_hash`. The source of truth in database mode; in file mode it is the runtime substrate the file is reconciled onto (see [the configuration file](#the-configuration-file)). | 0600 |
 | `config.db-wal`, `config.db-shm` | SQLite write-ahead log and shared-memory index for `config.db`. Created by `run`, `import` and `export` when WAL is enabled, inheriting the main file's permissions. `check` creates neither. | 0600 |
 | `querylog.db` | The query log: every domain every client asked for. Expendable — if it is missing or unusable it is recreated empty. | 0600 |
 | `querylog.db-wal`, `querylog.db-shm` | WAL sidecars for `querylog.db`. | 0600 |
@@ -112,9 +110,20 @@ than being created world-readable.
 
 ## The configuration file
 
-Default `/etc/nxdns/config.zon`, overridable with `--config FILE`. nxdns reads
-it and never writes it: it seeds an unconfigured database once and is ignored
-afterwards. nxdns does not create the file or its directory.
+There is no default path. `--config FILE` names the file, and without that flag
+no file is read at all — a `config.zon` sitting in `/etc/nxdns` that no
+invocation names is inert. `/etc/nxdns/config.zon` is a convention the packaging
+follows, not a location nxdns probes.
+
+nxdns reads the file and never writes it, in either authority mode. It does not
+create the file or its directory either; the systemd unit's
+`ConfigurationDirectory=nxdns` creates `/etc/nxdns`, and the same unit's
+`ReadOnlyPaths=/etc/nxdns` denies the service write access to it, so the file
+cannot be modified by the process that reads it.
+
+Under `run --config FILE` the file is the configuration and the database is the
+runtime substrate the server reads from: every start reconciles the one onto the
+other. So in that mode `config.db` is not the backup — the file is.
 
 `nxdns export --out FILE` writes a ZON file at mode 0600 through a temporary
 file and a rename. That file carries `web.password_hash`, so treat exports as