Say which bytes the byte limits count, and what passing one does (closes #203)

sneak asked for every document to be audited for sentences that do not say what they mean. The byte limits now say which bytes count (response bodies, request bodies or both, as `SWW_BYTES_COUNT` says, WebSocket traffic included) and what passing one does. Other unclear or false sentences in `README.md`, `SPEC.md`, `EVALUATION.md` and `docs/` are rewritten.

Documents only. `REPO_POLICIES.md` is shared policy text and stayed out.

Model: fable-5-1 (first audit); opus-5-5 (rework)

EVALUATION.md

@@ -12,8 +12,8 @@ configured only by environment variables, that provides:
 - R1: rate limits per minute, per hour and per day
 - R2: netblocks that bypass rate limiting
 - R3: alerts on attacks through webhook, Slack or ntfy
-- R4: alerts on anomalies: requests or bytes per minute or hour, for given IPs
-  or netblocks, crossing a threshold
+- R4: alerts on anomalies: requests made or bytes transferred per minute or
+  hour, for given IPs or netblocks, crossing a threshold
 - R5: temporary blocks for abusers, permanent bans for repeat offenders
 - R6: one or more RBLs or IP reputation APIs
 - R7: AS number lookup
@@ -24,14 +24,19 @@ configured only by environment variables, that provides:
 
 ## Verdict
 
-Nothing existing is suitable. No surveyed tool meets R8 (scaling limits by AS
-number or country) or the bytes half of R4 at all, and the tools that come
-closest on the rest fail R10: they need several containers, YAML or a web UI.
-The recommendation is to build a small single-binary sidecar; `SPEC.md` in this
-directory begins that spec. It reuses the mature parts of the surveyed field as
-libraries and data sources (Coraza and the OWASP Core Rule Set for attack
-detection, DNSBLs, AbuseIPDB, optionally a CrowdSec decision feed) instead of
-reimplementing them.
+Nothing existing is suitable. No surveyed tool meets R8, which asks for limits
+scaled by AS number or country. None meets R4's alerts on bytes transferred. The
+tools that come closest on the rest fail R10: they need several containers, YAML
+or a web UI. The recommendation is to build a small single-binary sidecar;
+`SPEC.md` in this directory begins that spec.
+
+The sidecar reuses the mature parts of the surveyed field instead of
+reimplementing them. It takes these as libraries and data sources:
+
+- Coraza and the OWASP Core Rule Set, for attack detection
+- DNSBLs
+- AbuseIPDB
+- optionally, a CrowdSec decision feed
 
 Closest existing options, and why each still falls short:
 
@@ -45,13 +50,16 @@ Closest existing options, and why each still falls short:
       external blacklist URLs, optional CrowdSec), R7 partly (AS number used for
       blacklist and whitelist decisions), R9 (ModSecurity with the Core Rule
       Set, or Coraza plugin), env-var settings.
-    - Fails: R8 (AS number and country can only allow or deny, never scale a
-      limit), R4 (no volume or byte threshold alerts in the free edition;
-      reporting is a paid feature), R5 escalation, and R10 in spirit: since 1.6
-      it needs a `bunkerweb` container plus a `bw-scheduler` container and a
-      database, or the all-in-one image that bundles nginx, scheduler, UI and
-      Redis in one container. It is designed to be the front door for many
-      sites, not a per-app sidecar. AGPL-3.0.
+    - Fails:
+        - R8: AS number and country can only allow or deny, never scale a limit.
+        - R4: no alerts on request-count or byte thresholds in the free edition;
+          reporting is a paid feature.
+        - R5: no escalation for repeat offenders.
+        - R10: since 1.6 it is not one plain sidecar. It needs a `bunkerweb`
+          container, a `bw-scheduler` container and a database, or the
+          all-in-one image that bundles nginx, the scheduler, the UI and Redis.
+    - It is designed as the proxy in front of many sites, not as a sidecar for
+      one app. AGPL-3.0.
     - Unverified: whether several rates (minute, hour, day) can be stacked on
       the same URL pattern; the documented design is one rate per URL pattern.
 - CrowdSec is the strongest detection and ban engine, but it is not a proxy.
@@ -66,16 +74,20 @@ Closest existing options, and why each still falls short:
       listed AS numbers is possible, but each is a hand-written YAML scenario,
       it reacts after the fact by banning, and it is not an inline limiter that
       answers 429.
-    - Fails: R10 (needs the security engine container with persistent state, log
-      acquisition from traefik, a bouncer such as the traefik plugin, and YAML
-      for acquisition, profiles, scenarios and notifications), bytes half of R4.
+    - Fails:
+        - R10, because it needs:
+            - the security engine container with persistent state
+            - log acquisition from traefik
+            - a bouncer such as the traefik plugin
+            - YAML for acquisition, profiles, scenarios and notifications
+        - R4's alerts on bytes.
 - CrowdSec plus traefik's own `rateLimit` middleware is the best combination
   with no new code. It gives inline limiting (one window per middleware, keyed
   by IP, with `sourceCriterion` exclusions), bans with escalation, alerts and
-  reputation. It still fails R8, the bytes half of R4, R1's three stacked
-  windows only by chaining three middlewares per router, and R10 entirely: the
-  configuration lives in traefik labels and CrowdSec YAML on each host, not in
-  one sidecar's environment.
+  reputation lookups. It still fails R8, R4's alerts on bytes, and R10 entirely:
+  the configuration lives in traefik labels and CrowdSec YAML on each host, not
+  in one sidecar's environment. It meets R1's three windows only by chaining
+  three middlewares per router.
 
 ## Candidate by candidate
 
@@ -87,10 +99,10 @@ Closest existing options, and why each still falls short:
       cached, streamed decision list (recommended), standalone against the
       central API, or AppSec only. Supports captcha remediation.
     - Covers: R5, R6, R9, R3 and R7 through the engine (see Verdict).
-    - Misses: the plugin itself does no rate limiting; R8; R4 bytes.
+    - Misses: the plugin itself does no rate limiting; R8; R4's alerts on bytes.
     - Configuration: traefik static config to load the plugin, dynamic config or
       labels for the middleware, CrowdSec YAML for everything else.
-    - Sidecar fit: no. It lives inside traefik, plus a separate engine
+    - Sidecar fit: no. It runs inside traefik and needs a separate engine
       container.
     - Maturity: widely used (about 900 stars, listed in the traefik plugin
       catalog, documented by CrowdSec itself), actively maintained. Traefik
@@ -115,7 +127,7 @@ Closest existing options, and why each still falls short:
     - What it is: nginx-derived (Tengine) reverse proxy with a proprietary
       semantic detection engine and a web console. About 22,000 stars.
     - Covers: R9 well, basic per-IP rate limiting with block duration, bot
-      challenge, authentication gate.
+      challenge, authentication in front of the app.
     - Misses: R8, R7, R4; R1 has one window per rule. Country blocking, alert
       messages, syslog forwarding and the better reputation database are paid
       (Lite about 10 USD per month, Pro about 100 USD per month); the free
@@ -128,7 +140,7 @@ Closest existing options, and why each still falls short:
 - Coraza (`corazawaf/coraza`) and Coraza-based proxies
     - What it is: a Go library that implements the ModSecurity rule language and
       runs the OWASP Core Rule Set. OWASP project, actively maintained, the
-      successor path now that ModSecurity is in maintenance only.
+      successor to ModSecurity, which is now in maintenance only.
     - Packagings: `coraza-caddy` (Caddy module), `coraza-spoa` (HAProxy),
       `coraza-proxy-wasm` (Envoy), a traefik WASM plugin, and
       `coreruleset/coraza-crs-docker` (Caddy plus Coraza plus the Core Rule Set,
@@ -142,7 +154,7 @@ Closest existing options, and why each still falls short:
 - ModSecurity Core Rule Set containers (`owasp/modsecurity-crs`)
     - What it is: official images of Apache or nginx with ModSecurity and the
       Core Rule Set, as a reverse proxy configured by env vars (`BACKEND`,
-      paranoia level, anomaly thresholds, many more). Current images carry
+      paranoia level, anomaly thresholds, many more). Current images contain
       ModSecurity 2.9.x on Apache and Core Rule Set 4.x.
     - Covers: R9, and R10 (single container, env vars, one backend).
     - Misses: R1 to R8.
@@ -152,8 +164,8 @@ Closest existing options, and why each still falls short:
 - Anubis (`TecharoHQ/anubis`), 1.27 current
     - What it is: a single-binary reverse proxy that makes browsers solve a
       proof-of-work challenge before passing them to `TARGET`. Aimed at
-      scrapers, which is likely a large share of unwanted traffic on a public
-      code forge.
+      scrapers, which are likely a large share of the unwanted traffic on a
+      public code forge.
     - Covers: R10 well (one container, env vars for listener, target,
       difficulty, cookies). Policy rules can match on path, user agent, headers,
       IP ranges, and with the vendor's hosted data service also AS number and
@@ -180,13 +192,13 @@ Closest existing options, and why each still falls short:
       temporary ban, no escalation, state lost on traefik restart) and R2
       (allowlist). Nothing else.
     - `juitde/traefik-plugin-fail2ban`, fail2ban connector plugins, GeoBlock
-      plugins (country allow or deny through an external lookup API): same
-      shape, each one small feature, configured in traefik, state in memory.
+      plugins (country allow or deny through an external lookup API): each adds
+      one small feature, is configured in traefik and keeps its state in memory.
     - Sidecar fit: no; they live inside traefik.
 - Traefik built-in middlewares
     - `rateLimit` (one average-and-burst window per middleware, optional Redis
       in traefik 3.x), `inFlightReq`, `ipAllowList`. No bans, alerts, reputation
-      or AS number awareness.
+      lookups or AS number lookups.
 - caddy-waf (`fabriziosalmi/caddy-waf`), 0.4.x
     - What it is: a Caddy module with regex rules and anomaly scoring, per-IP
       and per-path rate limiting with one configurable window, IP and DNS
@@ -198,12 +210,12 @@ Closest existing options, and why each still falls short:
 - open-appsec (Check Point)
     - Machine-learning WAF agent attached to nginx, Kong, Envoy or similar, with
       a declarative policy file or the vendor's cloud console. Covers R9 only;
-      rate limiting and richer features are in paid tiers. Not a sidecar in the
-      required sense.
+      rate limiting and richer features are in paid tiers. It attaches to an
+      existing proxy, so it is not the sidecar R10 asks for.
 - iocaine
     - Serves generated garbage pages to clients the fronting proxy classifies as
-      scrapers. Not a limiter, WAF or ban tool; out of scope except as a
-      curiosity for scraper traffic.
+      scrapers. Not a limiter, WAF or ban tool; out of scope, and only of
+      passing interest for scraper traffic.
 - Pangolin
     - A tunnelled access platform that bundles traefik and optionally CrowdSec.
       Replaces the ingress rather than adding a sidecar; out of scope.
@@ -214,17 +226,17 @@ Closest existing options, and why each still falls short:
   Everyone else offers one window per rule or none.
 - R2 bypass netblocks: BunkerWeb, CrowdSec, traefik, fail2ban plugins.
 - R3 alerts: CrowdSec (best), BunkerWeb (denied requests only), SafeLine (paid).
-- R4 volume and byte anomalies: none. CrowdSec can approximate request-count
-  anomalies with a custom scenario; nothing handles bytes.
-- R5 temporary then permanent: CrowdSec only. BunkerWeb has fixed or permanent,
-  not both by history.
+- R4 alerts on request counts and bytes: none. CrowdSec can approximate alerts
+  on request counts with a custom scenario; no surveyed tool alerts on bytes.
+- R5 temporary then permanent: CrowdSec only. BunkerWeb's ban is either one
+  fixed length or permanent, and does not change with a client's history.
 - R6 reputation: CrowdSec, BunkerWeb, go-away, caddy-waf (static lists).
 - R7 AS number lookup: CrowdSec (enrichment), BunkerWeb and caddy-waf (allow or
   deny), Anubis (hosted service).
 - R8 biased thresholds: none.
 - R9 attack detection: Coraza or ModSecurity with the Core Rule Set (open,
-  standard), CrowdSec AppSec, SafeLine (closed engine), BunkerWeb (wraps the
-  first).
+  standard), CrowdSec AppSec, SafeLine (closed engine), BunkerWeb (wraps Coraza
+  or ModSecurity).
 - R10 env-var sidecar: `owasp/modsecurity-crs`, `coraza-crs-docker`, Anubis.
   None of these covers anything beyond its one job.