feat: enhance TCP options descriptions for clarity and precision

src/ai/topics.json

@@ -7,15 +7,15 @@
 
   "tcp.drop_sack": "Strips the TCP SACK option (kind 5) AND the SACK-Permitted option (kind 4) from outgoing packets b4 reinjects. SACK-Permitted lives in the SYN, so removing it prevents the connection from negotiating SACK at all — both endpoints fall back to plain ACKs. Used to neutralize DPI that fingerprints clients by SACK behavior or treats SACK negotiation as a 'real client' signal. Side effect: throughput suffers on lossy links because retransmits become full-window resends instead of selective. Only applied when b4 is already reinjecting the packet for other reasons (fragmentation, faking, desync, etc.); has no effect on packets that pass through unmodified.",
 
-  "tcp.duplicate": "When enabled, b4 drops the original matched packet and re-emits N identical copies via raw socket. 'count' is N, range 1-10, default 3. Targets specific destination IPs configured in the duplicate IP set, not all TCP traffic. The duplicates are bit-identical, sent back-to-back. Helps against DPI that probabilistically drops packets — more copies = better odds one survives. Cost: bandwidth multiplier on the destination; may trigger anti-DDoS or duplicate-segment rejection at the server. count=1 means one copy total (original dropped, one re-sent) — equivalent to no duplication apart from the userspace round-trip cost.",
+  "tcp.duplicate": "Targeted feature: sends multiple copies of each matching packet to specific destination IPs (configured via the duplicate IP set, not all traffic). 'count' is how many copies are sent, range 1-10, default 3. Helps against DPI that probabilistically drops packets — extra copies improve the odds at least one survives the path. Costs: bandwidth multiplier on the destination, and some servers reject what looks like duplicate-segment retransmits. Only takes effect on packets going to the configured duplicate IP set; enabling this without populating the IP set changes nothing.",
 
-  "tcp.ip_block_detect": "Detects ISP-level IP blocking. Mechanism: b4 watches retransmits of the TLS ClientHello on the same (clientIP:port -> destIP:port) connection key. When count >= retransmit_threshold OR (count > 1 AND time-since-first-seen > timeout_ms), b4 declares the destination blocked: it sends a synthetic RST to the LOCAL client (so the browser fails fast instead of hanging on a silently-dropped connection) and drops the queued packet. If cache_blocked_ips is true, future ClientHellos to that destIP:port get the same RST treatment immediately, no waiting for retries. Also feeds the Escalate.To chain — if the set has an escalation target, the host is moved to that next set's bypass strategy instead of (or in addition to) being RST'd. Only triggers on packets carrying ClientHello, so HTTPS connections only.",
+  "tcp.ip_block_detect": "Detects when a destination is being silently IP-blocked by ISP-level DPI (the connection just hangs because nothing comes back) and fails it fast on the local side. Without this, the user's browser spins for 30+ seconds before giving up; with it, the user gets an immediate connection error and can retry or take a different route. If cache_blocked_ips is set, b4 remembers blocked destinations and fails subsequent connections to them immediately rather than waiting for the same evidence to accumulate again. Also feeds the Escalate.To chain — if the set has an escalation target, the blocked host is moved to that next set's bypass strategy instead of (or in addition to) failing fast. Watches HTTPS connections only.",
 
-  "tcp.ip_block_detect.retransmit_threshold": "Number of ClientHello retransmits to the same destination before b4 declares it IP-blocked (default 3, range 1-10). Lower = faster failure detection but more false positives on lossy links where retransmits are normal traffic. Higher = more tolerant but the user waits longer before getting a fast-fail RST or strategy escalation. Threshold of 1 is dangerous — any single dropped packet triggers a full block. Counted per (clientIP:port -> destIP:port) connection key, reset when the connection completes or times out.",
+  "tcp.ip_block_detect.retransmit_threshold": "Sensitivity knob for ip_block_detect. Default 3, range 1-10. Lower values make b4 declare blocks faster (better responsiveness, more false positives on lossy links where retransmits are normal). Higher values are more tolerant (fewer false positives but the user waits longer before getting a fast-fail or strategy escalation). Threshold of 1 is dangerous — a single dropped packet on the path is enough to trigger a full block. Each connection is counted independently, so unrelated traffic doesn't influence detection on a different destination.",
 
-  "tcp.rst_protection": "Drops incoming RST packets that look like middlebox injections rather than legitimate server resets. Without this, a single injected RST closes the connection and the bypass fails. Drop heuristics (any match → drop): (a) more than one RST seen on this connection, (b) RST arrived before any real server response, (c) server has been using TCP options but this RST has none, (d) server uses options and the RST is bare (no ACK flag — classic middlebox signature), (e) RST's TTL differs from the observed server TTL by more than ttl_tolerance hops. Subsequent legitimate RSTs from the real server still close the connection. Also feeds the Escalate chain: enough RST drops within Escalate.RstWindowSec trigger strategy escalation for that host.",
+  "tcp.rst_protection": "Drops incoming RST packets that look like middlebox injections rather than legitimate server resets. Without this, a single injected RST closes the connection and the bypass attempt fails. b4 distinguishes injected RSTs from legitimate ones using several signals derived from the RST and the connection's prior state; if the signals point to injection, the RST is dropped and the connection survives. Subsequent legitimate RSTs from the real server still close the connection normally. Also feeds the Escalate chain: when enough RSTs are dropped within Escalate.RstWindowSec, the host is escalated to the next set's bypass strategy.",
 
-  "tcp.rst_protection.ttl_tolerance": "Allowed absolute difference between an incoming RST's TTL and the previously observed server TTL on the same connection (default 3, range 1-20). Middleboxes injecting RSTs typically sit at a different network position from the real server, so their TTL diverges from what b4 has measured for legitimate server packets. 0 = strict (any TTL delta drops the RST) — risky because legitimate ECMP or route flap can shift TTL by 1. Higher = more lenient: fewer false RST drops but more middlebox RSTs slip through. Only used if b4 has already recorded a server TTL for this connection; if not, the TTL check is skipped and other heuristics still apply.",
+  "tcp.rst_protection.ttl_tolerance": "Tolerance knob for one of the rst_protection signals (TTL-based). Default 3, range 1-20. Lower = stricter detection of injected RSTs (more middlebox RSTs caught, but also a higher chance of dropping legitimate RSTs after a route change). Higher = more lenient (fewer false drops of legitimate RSTs, but more middlebox RSTs slip through). 0 is risky because routine network events like ECMP or a route flap can shift TTL by 1 hop. The other rst_protection signals continue to apply regardless of this value, so loosening tolerance doesn't disable RST protection entirely.",
 
   "fragmentation.strategy": "Selects the TCP-level bypass technique b4 applies to matching outgoing packets. Options: tcp, ip, oob, tls, disorder, extsplit, firstbyte, combo, hybrid, or none. Each is a different way of breaking up the TLS ClientHello so DPI middleboxes can't match it as a single record. 'none' disables fragmentation for this set — packets pass through unmodified. Choosing the right strategy is ISP-dependent: what defeats one DPI engine fails on another. The discovery feature (separate b4 tab) tests combinations against the user's network and recommends one. When fragmentation.strategy_pool is non-empty, this fixed selection is ignored and the pool is sampled per packet instead.",