SPEC: the one place for behaviour and reasons; docs/ as lookup lists only

docs/core-rule-set.md, docs/lookup.md, docs/reputation.md and docs/bans.md
restated the spec and are folded back into it and removed. The remaining
docs files hold only lists: settings with their defaults and value forms,
the request log's fields, the metrics, the endpoints, the state files and
their contents, the rule file format and default file, the alert events
and messages, the image's contents and pins, and the gitea notes. Every
behaviour each of them held moves to the spec, said once. The settings
groups have the same names in both files. Stale comments in
internal/state and script/example-app point at the right places.

Model: fable-5-1

docs/admin-endpoints.md

@@ -1,26 +1,20 @@
 # Admin endpoints
 
-`smallwebwaf` answers these requests itself, on the app's own address and
-through traefik like any other request. Apart from the health check, each needs
-a token, sent as `Authorization: Bearer <token>`, and goes through every check
-any other request goes through. It is answered where another request would be
-passed to the app: a banned client stays refused, and each request counts toward
-rate limiting. A missing or wrong token is answered `401`, in `observe` mode
-too. Such a refusal counts toward the error burst, so a client guessing tokens
-is soon banned. While a token is unset, its endpoints answer `404`.
+The endpoints under `/_smallwebwaf/`, what each takes and what each answers.
+"Admin endpoints" in [`SPEC.md`](../SPEC.md) says which checks they go through
+and how their tokens work.
 
-- `GET /_smallwebwaf/healthz`: `200` and `ok`, to anyone, before any check and
-  without asking the app.
+- `GET /_smallwebwaf/healthz`: `200` and `ok`, to anyone.
 - `GET /_smallwebwaf/metrics`: the metrics, for `SWWAF_METRICS_TOKEN` (see
   [`metrics.md`](metrics.md)).
 - `GET /_smallwebwaf/bans`: every ban held, under `bans`, each as `bans.json`
   lists it. Needs `SWWAF_ADMIN_TOKEN`, as do the three below.
 - `POST /_smallwebwaf/bans`: bans a netblock. The body is a JSON object of
   `netblock`, `duration` and, if you like, `reason`. `netblock` is a netblock
-  such as `203.0.113.0/24`, or a client's address. A client's address bans its
-  IPv4 netblock (`SWWAF_BAN_SCOPE_V4_PREFIX`) or its IPv6 group. `duration` is a
-  duration such as `1h` or `7d`, or `permanent`. The ban starts at once, with
-  the cause `admin`. A bad body is answered `400`, saying what is wrong:
+  such as `203.0.113.0/24`, or a client's address, which bans its IPv4 netblock
+  (`SWWAF_BAN_SCOPE_V4_PREFIX`) or its IPv6 group. `duration` is a duration such
+  as `1h` or `7d`, or `permanent`. A bad body is answered `400`, saying what is
+  wrong:
     - one that is not such an object, or has another field;
     - one longer than 4 KiB;
     - one that names an IPv4-mapped netblock, or an address with a zone.
@@ -28,8 +22,27 @@ is soon banned. While a token is unset, its endpoints answer `404`.
   address `<client>`. It answers `404` when none is active.
 - `GET /_smallwebwaf/clients/<ip>`: what `smallwebwaf` knows of the client.
   Under `client`, its counters and history as `clients.json` holds them, or
-  `null` when it has never been seen. Under `bans`, every ban covering the
-  address, with its notes.
+  `null` when `clients.json` does not hold it. Under `bans`, every ban covering
+  the address, with its notes.
 
-An admin whose own address is banned lifts that ban by editing `bans.json` (see
-[`bans.md`](bans.md)).
+## Examples
+
+With `SWWAF_ADMIN_TOKEN` set, and the token in `$TOKEN`:
+
+```sh
+# Every ban.
+curl -H "Authorization: Bearer $TOKEN" https://app.example/_smallwebwaf/bans
+
+# Ban 203.0.113.0/24 for seven days.
+curl -H "Authorization: Bearer $TOKEN" \
+    --json '{"netblock": "203.0.113.0/24", "duration": "7d", "reason": "probes for logins"}' \
+    https://app.example/_smallwebwaf/bans
+
+# Lift the bans on 203.0.113.9.
+curl -H "Authorization: Bearer $TOKEN" -X DELETE \
+    https://app.example/_smallwebwaf/bans/203.0.113.9
+
+# What smallwebwaf knows of 203.0.113.9.
+curl -H "Authorization: Bearer $TOKEN" \
+    https://app.example/_smallwebwaf/clients/203.0.113.9
+```