Carry the municipality on a not-found CEPHEADv0.2.0main

A CEP that fails is rarely a random number: it is usually someone who
knows the city and guessed, most often the -000 that 957 municipalities
never received. The API now answers 404 with an optional faixa naming
the municipality that number would have belonged to, so the caller can
say "you are in Areal, but not at that number" instead of a dead end.

It stays an error. Cepis.Faixa hangs off Cepis.NotFoundError as context
for the failure, never as an address, and parsing is deliberately
tolerant: an absent, truncated or unreadable faixa yields nil rather
than costing the caller a clean definitive answer.

The bounds are the smallest and largest CEP that actually exist there,
not the range the Correios publish, and almost nothing between them is
valid — hence ceps and density/1, so nobody reads the pair as a list of
numbers to try.

1 files changed, 40 insertions, 1 deletions

diff --git a/README.md b/README.md
index bb79b2a..837251a 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ Correios data (DNE), refreshed every two weeks.
 
 ```elixir
 def deps do
-  [{:cepis, git: "https://git.cep.is/elixir.git", tag: "v0.1.0"}]
+  [{:cepis, git: "https://git.cep.is/elixir.git", tag: "v0.2.0"}]
 end
 ```
 
@@ -185,6 +185,45 @@ end
 API is answering instead of it — a captive Wi-Fi portal, a corporate proxy, an
 HTML error page. Useful as a diagnosis: the problem is not in your code.
 
+### When the CEP does not exist
+
+A failing CEP is rarely random: it is usually someone who knows the city and
+guessed the number, most often the `-000`, which 957 municipalities never
+received. So `Cepis.NotFoundError` carries a `faixa` naming the municipality
+that number *would* have belonged to, when there is one:
+
+```elixir
+{:error, %Cepis.NotFoundError{faixa: faixa}} = Cepis.lookup("25845-000")
+
+if faixa do
+  faixa.localidade   # "Areal"
+  faixa.uf           # "RJ"
+  faixa.ibge         # "3300225"
+  faixa.ceps         # 118
+  faixa.cep_ini      # "25845001"
+  faixa.cep_fim      # "25849899"
+end
+```
+
+This is **still a not-found**. The CEP is not in the database, `lookup/2` still
+returns `{:error, _}`, and `faixa` is context for the failure — never an
+address. What it buys you is a better answer to the user: "you are in Areal,
+but not at that number", instead of a dead end.
+
+Two things about it:
+
+- `cep_ini` and `cep_fim` are the smallest and the largest CEP that **actually
+  exist** in the municipality, not the bounds the Correios publish. The DNE's
+  own start for Areal is `25845000` — exactly the CEP that just failed.
+- **The range is sparse.** Almost nothing between the two bounds is a valid
+  CEP: Areal has 118 across thousands of numbers. That is what `ceps` is for,
+  and `Cepis.Faixa.density/1` measures it. Never expand the pair into a list of
+  CEPs to try.
+
+`faixa` is `nil` whenever the number falls in a band no municipality owns — the
+API omits the field there rather than sending null — so every caller has to
+handle its absence.
+
 ## Development
 
 Everything runs through `make`, which shells out to `mix`: