milestone 21: abp list exceptions and a regex rule kind

docs/reference/api.md

@@ -277,3 +277,31 @@ included. The password then lives where the rest of the configuration lives: set
 Request and response schemas for every operation live in the OpenAPI document:
 `src/web/openapi.yaml` in the repository, or `GET /api/openapi.yaml` from a
 running server.
+
+### Block reasons
+
+Three places carry the same tag: `block_reason` on a `GET /api/queries` row,
+`block_reason` on a live-stream frame, and `reason` on a `GET /api/lookup`
+answer. The tag names the level that decided the query, and the levels are
+listed here in the order they are consulted — the first one that matches wins,
+so a rule always outranks a list.
+
+| Tag | Decided by |
+| --- | --- |
+| `rule_allow_exact` | An `exact` rule with action `allow` |
+| `rule_block_exact` | An `exact` rule with action `block` |
+| `rule_allow_wildcard` | A `wildcard` rule with action `allow` |
+| `rule_block_wildcard` | A `wildcard` rule with action `block` |
+| `rule_allow_regex` | A `regex` rule with action `allow` |
+| `rule_block_regex` | A `regex` rule with action `block` |
+| `blocklist_exception` | An `@@` exception line in a downloaded list |
+| `blocklist_domain` | A plain name in a downloaded list |
+| `blocklist_wildcard` | A domain anchor (`||name^`) in a downloaded list |
+
+`/api/lookup` also answers `none` when nothing matched. A query row never
+carries `none`: `block_reason` is null unless the query was blocked.
+
+A `cname:` prefix means the decision landed on a CNAME target rather than on
+the name the client asked for, so `cname:blocklist_domain` reads as "the list
+blocks a name this answer redirects to". Only `/api/queries` and the live
+stream show the prefix; `/api/lookup` does not follow CNAMEs.