milestone 24: persist and surface the unsupported-line count

docs/reference/configuration.md

@@ -287,6 +287,21 @@ first, so a downloaded list can reopen only a hole another downloaded list dug.
 Each source reports how many it carried as `exceptions`; there is no way to write
 one by hand, and no reason to want one — write an allow rule instead.
 
+Two counters report what a compile skipped, and they are different facts.
+`skipped_regex` counts regex lines: nxdns has a regex engine, but it takes
+patterns only from the operator, so a regex line in a downloaded list is counted,
+skipped and surfaced — adopt the ones you trust as `regex` rules.
+`skipped_unsupported` counts lines nxdns cannot safely translate into a DNS
+decision: cosmetic element hiding (`##`, `#@#`, `#?#`), rules carrying a `$`
+modifier (except `$important` on an exception line, tolerated above), scheme
+anchors, non-anchored `@@` forms — and, in a `domains`-format
+list, a line holding more than one field before its inline comment, which usually
+means the list is really a hosts file that was declared as `domains`. Neither is
+an error, and the two are never one number. A large `skipped_unsupported` beside
+a small `domain_count` usually means the list is written for browser extensions,
+and its DNS or hosts variant will block more here. Both appear per source in the
+blocklists UI and on `/api/blocklists`.
+
 ### group_sources
 
 Which groups consult which blocklist sources.

docs/tutorial/first-run.md

@@ -220,15 +220,18 @@ curl -s -X POST http://127.0.0.1:8080/api/blocklists/update
 ```
 
 ```json
-{"sources":[{"id":1,"state":"ok","loaded":true,"last_attempt":1786629237,"last_success":1786629238,"url":"https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts","last_error":"","domains":97648,"wildcards":0,"exceptions":0,"skipped_regex":0}]}
+{"sources":[{"id":1,"state":"ok","loaded":true,"last_attempt":1786629237,"last_success":1786629238,"url":"https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts","last_error":"","domains":97648,"wildcards":0,"exceptions":0,"skipped_regex":0,"skipped_unsupported":0}]}
 ```
 
-The three zeros are the parts of this list that a hosts file cannot have.
+The four zeros describe this particular download, not the hosts format.
 `wildcards` counts entries covering a name and its subdomains, `exceptions`
 counts the `@@` lines an Adblock Plus list uses to lift a name another list
 blocks, and `skipped_regex` counts the regex lines nxdns declines to take from a
-downloaded list. Only the Adblock Plus syntax writes any of them; a hosts file is
-one name per line.
+downloaded list. `skipped_unsupported` counts lines nxdns cannot translate into a
+DNS decision, and a large value next to a small `domains` means the list targets
+browsers rather than DNS. Only `exceptions` is Adblock-Plus-only: a hosts list
+can carry regex lines, `*.`-prefixed wildcards, and bare sink addresses that
+count as unsupported. This one carries none of them.
 
 The download is about 3 MB and takes a few seconds. Watch the first terminal
 until this appears: