README.md

@@ -9,19 +9,38 @@ table in real time. It works like this:
 
 ## Rationale
 
-RIPE RIS Live streams the BGP updates that RIPE's route collectors receive, as
-they happen, from the moment a client connects. It reports changes, not the
-routing table they add up to, so it cannot say which AS an IP address is routed
-to now or which routes a prefix has. RouteWatch applies the feed's updates to a
-routing table that it keeps in memory, with a copy in its own SQLite database.
-It answers IP-to-AS lookups and prefix pages from that table.
+RouteWatch exists to serve our other services as an internal API for information
+about IP addresses.
 
-The feed sends no table when a client connects. So the routing table holds only
-the routes announced since RouteWatch first started. An IP-to-AS lookup finds
-nothing for an address whose routes have not been announced since then. The
-routing table also misses updates RouteWatch drops when it falls behind, and
-updates sent while it is stopped. So a lookup or a prefix page can show a route
-the feed has withdrawn.
+RouteWatch follows BGP routing table updates from RIPE RIS Live. RIS Live
+streams the updates that RIPE's route collectors receive, as they happen, from
+the moment a client connects. It reports changes, not the routing table they add
+up to. RouteWatch applies those changes to a routing table that it keeps in
+memory, with a copy in its own SQLite database. From that table, RouteWatch sees
+directly:
+
+- which AS each IP address is routed to
+- which announced prefix holds each IP address, and how big that prefix is
+
+RouteWatch adds details of each AS from WHOIS, the public directory of the
+internet registries. The details include the organisation that holds the AS.
+RouteWatch keeps them in its database and looks them up again once they are 30
+days old. An IP lookup answers from those stored details and never waits for
+WHOIS.
+
+So our own services can ask RouteWatch about an IP address, instead of each
+working it out for itself.
+
+RIS Live sends no routing table when a client connects. So the routing table
+holds only the routes announced since RouteWatch first started. An IP lookup
+finds no route for an address until a prefix that holds it is announced. The
+routing table also misses these updates:
+
+- those sent while RouteWatch is stopped
+- those that RouteWatch drops when it falls behind
+
+A lookup or a prefix page can therefore show a route that has since been
+withdrawn.
 
 ## Features
 

TODO.md

@@ -35,6 +35,10 @@ tested.
 
 # Completed Steps
 
+- 2026-10-27: README "Rationale" says why RouteWatch exists: to answer our other
+  services' questions about IP addresses, from its own routing table and the
+  WHOIS details it keeps. It still says what RIS Live does not give (closes
+  #204)
 - 2026-10-27: every JSON answer carries `@meta`. A panic on a JSON route answers
   500 with the JSON error body. `/status.json` and the health check answer 405
   with the JSON error body to any method they do not take. The 500 and the 405