docs: document the block config format + mkpasswd/checkconfig/rehash CLIs in README and configuration.md

README.md

@@ -57,8 +57,10 @@ operational limit exposed as a config key.
 ```sh
 git clone https://git.devtronic.pro/fedserv/echoIRCd
 cd echoIRCd
-cp echoircd.conf.example echoircd.conf     # edit: oper pass, cloak_key, TLS paths
+cargo build --release
-cargo run --release                        # reads ./echoircd.conf
+cp echoircd.conf.example echoircd.conf     # edit: servername, cloak_key, TLS paths
+printf '%s' 'my-oper-pass' | ./target/release/echoircd mkpasswd   # → bcrypt hash for the oper block
+./target/release/echoircd                  # start (reads ./echoircd.conf)
 ```
 
 Then point a client at it: `/server 127.0.0.1 6667` (or `6697` for TLS once a
@@ -75,13 +77,27 @@ The full manual lives in [`docs/`](docs/):
 
 ## Configuration
 
-Configuration is a plain `key = value` file; see
+Configuration is a single file (default `./echoircd.conf`) in a **brace/block
-[`echoircd.conf.example`](echoircd.conf.example) for the full, annotated set of
+format** — or the original flat `key = value` form; both are accepted and the
-keys. Every operational limit is a config key with a built-in default, and most
+parser auto-detects which one a file uses:
-settings apply on `REHASH` without a restart. Your live `echoircd.conf` is
+
-gitignored — it holds secrets (oper password, cloak key, link password), so never
+```text
-commit it. Generate a TLS certificate into `tls/` with the one-liner in the example
+server { name "irc.example.net"; network "ExampleNet"; }
-config.
+listen { ip "*"; port 6697; tls yes; }
+oper   { name "admin"; password "$2b$…"; type netadmin; }
+```
+
+See [`echoircd.conf.example`](echoircd.conf.example) for the full, annotated set of
+keys — every operational limit is a config key with a built-in default, and most
+settings apply on `REHASH` without a restart. Three helper subcommands round it out:
+
+- `echoircd mkpasswd` — read a password from stdin, print a bcrypt hash for an `oper` block.
+- `echoircd checkconfig [file]` — parse a config and dump its keys, to validate one or diff two.
+- `echoircd rehash` — signal the running server to reload its config in place.
+
+Your live `echoircd.conf` is gitignored — it holds secrets (oper password, cloak
+key, link password), so never commit it. Generate a TLS certificate into `tls/`
+with the one-liner in the example config.
 
 ## Architecture
 

docs/configuration.md

@@ -1,8 +1,10 @@
 # Configuration
 
-The config is a plain `key = value` text file (default `./echoircd.conf`). Some
+echoircd reads a single config file (default `./echoircd.conf`), written in a
-keys repeat to build a list (`motd`, `oper`, `link`, `connectclass`, `dnsbl`,
+brace/block format (below); the original flat `key = value` form also works and is
-`securitygroup`, …). Comments start with `#`.
+auto-detected. Some keys repeat to build a list (`motd`, `oper`, `link`,
+`connectclass`, `dnsbl`, `securitygroup`, …). Comments start with `#` (also `//`
+and `/* */`).
 
 The shipped [`echoircd.conf.example`](../echoircd.conf.example) is the fully
 annotated master reference — every key with its default. This page organizes those
@@ -12,6 +14,33 @@ Most settings apply on `REHASH` without a restart.
 > `echoircd.conf` is gitignored because it holds secrets (oper password, cloak
 > key, link password). Never commit your live config.
 
+## File format
+
+Structural entities and grouped settings go in `{ }` blocks; values end with `;`,
+booleans are `yes`/`no`:
+
+```text
+server { name "irc.example.net"; network "ExampleNet"; sid "0AA"; }
+listen { ip "*"; port 6667; }
+listen { ip "*"; port 6697; tls yes; }
+oper   { name "admin"; password "$2b$…"; type netadmin; }
+link   { name "hub.example.net"; ip 10.0.0.1; port 7000; password "…"; services yes; }
+```
+
+Structural blocks — `server`, `listen`, `tls`, `oper`, `opertype`, `class`,
+`link`, `cloak`, `webirc`, `motd`, `opermotd` — take the short field names shown
+throughout this page. Any other block name (`set`, `limits`, `modules`, …) is just
+a group whose fields are the flat keys documented below, so the scalar settings can
+be organized however you like. The flat and block forms are equivalent.
+
+Three subcommands help manage a config:
+
+| Command | Purpose |
+|---------|---------|
+| `echoircd mkpasswd [cost]` | Read a password from stdin, print a bcrypt hash for an `oper` block. |
+| `echoircd checkconfig [file]` | Parse a config and print a sorted key/value dump — validate one, or diff two. |
+| `echoircd rehash [file]` | Signal the running server (found via its `pidfile`) to reload config in place. |
+
 ## Server identity
 
 | Key | Meaning |
@@ -93,7 +122,7 @@ connectclass_required = yes    # refuse clients matching no allow class (default
 
 | Key | Meaning |
 |-----|---------|
-| `oper = <name> <password> [level]` | An oper account; the password may be hashed (see `MKPASSWD`). Optional numeric [oper level](operators.md). |
+| `oper { name; password; type; fingerprint; level }` | An oper account. `password` takes plaintext, `sha256:<hex>`, `pbkdf2:…` or a bcrypt `$2b$` hash (make one with `echoircd mkpasswd`, or `MKPASSWD` in-band); `fingerprint` requires a matching TLS client-cert SHA-256 (with, or instead of, a password); `type` names an [opertype](operators.md); `level` is a numeric [oper level](operators.md). |
 | `opermotd` | A line shown to opers via `/OPERMOTD` (repeatable). |
 | `operprefix` | Give every oper a `!` prefix in their channels. |
 | `ojoin` / `ojoin_op` | Enable `/OJOIN` (join as staff, with op unless `ojoin_op = no`). |