docs(site): present the API observations as integration notes

CONTRIBUTING.md

@@ -105,7 +105,7 @@ it, and makes only free calls unless you pass `--paid`.
 - Never commit a key, and never put one in an issue or a pull request.
 - Level 2 and above return a person's address. Do not commit captured
   responses that contain one.
-- When the live API differs from its documentation, record it in
+- When the live API does something its documentation does not describe, record it in
   `docs/api-differences.md`, with the date observed, and capture the body in
   `spec/responses.json` if it holds no personal data.
 

README.md

@@ -142,7 +142,7 @@ Input may be hyphenated, spaced or compact, in either case. The compact form mat
 - The NIPOST API needs a key for every endpoint, from the [developer dashboard](https://dashboard.postcode.gov.ng). Offline validation needs nothing.
 - The API layer is tested against responses captured from the live API with a level 1 key, kept in [`spec/responses.json`](spec/responses.json). Run [`scripts/live_check.py`](scripts/live_check.py) with your own key to repeat the comparison. Lookup levels 2 and up need a higher-access key and are tested only against NIPOST's documented examples.
 - The resolver and the `resolve_address` tool are pre-release. They work against the live API, but their accuracy on real addresses is unmeasured. Described addresses need a geocoder you run or pay for; text alone rarely identifies a building, so ask users for a location pin when the exact building matters.
-- Where the live API differs from NIPOST's documentation is recorded, with the date of each observation, in [`docs/api-differences.md`](docs/api-differences.md).
+- Notes for integrators on how the live API behaves, each with the date it was observed, are in [`docs/api-differences.md`](docs/api-differences.md).
 
 ## Development
 

docs/api-differences.md

@@ -1,18 +1,18 @@
-# Where the live API differs from its docs
+# Integration notes for the NIPOST API
 
-What `api.postcode.gov.ng` does where [NIPOST's documentation](https://docs.postcode.gov.ng) says otherwise or says nothing. Each row gives the date it was last observed. The observations from 6 October onward were made with a level 1 test key. To repeat the comparison with your own key, run [`scripts/live_check.py`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/scripts/live_check.py).
+How `api.postcode.gov.ng` behaved on the dates given, for anyone building on it. These notes add detail to [NIPOST's documentation](https://docs.postcode.gov.ng), which remains the reference. The observations from 6 October onward were made with a level 1 test key. To repeat the comparison with your own key, run [`scripts/live_check.py`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/scripts/live_check.py).
 
 | Topic | The live API | Observed |
 | --- | --- | --- |
-| Keys | Every endpoint needs a key, including search, assembly and level 1 lookup, which the docs describe as public. | 3 October 2026 |
+| Keys | Every endpoint needs a key, including search, assembly and level 1 lookup. | 3 October 2026 |
 | Lookup | Also returns `status` (`valid`, `not_found`, `invalid`) and `verified`. A malformed code is answered with HTTP 200 and `status: invalid`. | 3 October 2026 |
 | Lookup level | Asking for a level the key lacks returns `403 level_not_granted`. | 3 October 2026 |
 | Lookup level | A level the API cannot read, or `0`, is answered at level 1. | 6 October 2026 |
-| Autocomplete | Suggestions carry only `code`, the value of the next segment. The documented `label` is not sent. | 3 October 2026 |
+| Autocomplete | Suggestions carry `code`, the value of the next segment. Treat `label` as optional. | 3 October 2026 |
 | Autocomplete | An empty query is answered with no suggestions. On 3 October it never got a response, so the libraries refuse to send one. | 6 October 2026 |
 | Reverse geocoding | Also returns `depth`. | 3 October 2026 |
 | Reverse geocoding | A latitude outside -90 to 90, or a longitude outside -180 to 180, returns `500 internal`. | 9 October 2026 |
-| Nearby search | Returns a list of `postcode`, `display` and `distance_m`, nearest first. The docs leave it unspecified. | 3 October 2026 |
+| Nearby search | Returns a list of `postcode`, `display` and `distance_m`, nearest first. | 3 October 2026 |
 | Load balancer | A request it rejects, such as a 5,000-character autocomplete query, returns `403` with an HTML body. | 6 October 2026 |
-| Example code | `EK-01-A03-FK-01`, the example used throughout NIPOST's docs, is reported as not assigned. | 3 October 2026 |
+| Example code | `EK-01-A03-FK-01`, the example in NIPOST's docs, shows the format and is not an assigned building. | 3 October 2026 |
 | Test keys | With a level 1 test key, `FC-03-B06-AG-12`, autocomplete, reverse geocoding and nearby search all return empty answers where [`spec/responses.json`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/spec/responses.json) records data. | 6 October 2026 |

docs/llms-full.txt

@@ -35,7 +35,7 @@ Since 1 October 2026 a Nigerian building's postcode is this 11-character code. A
 - [Java README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/java/README.md)
 - [MCP server README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/mcp/README.md): per-client setup and configuration
 - [Resolver README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/agent/README.md)
-- [Where the live API differs from its docs](https://github.com/Adeniyikayodee/ng-postcode/blob/main/docs/api-differences.md)
+- [Integration notes for the NIPOST API](https://github.com/Adeniyikayodee/ng-postcode/blob/main/docs/api-differences.md)
 
 ## Optional
 
@@ -190,7 +190,7 @@ Input may be hyphenated, spaced or compact, in either case. The compact form mat
 - The NIPOST API needs a key for every endpoint, from the [developer dashboard](https://dashboard.postcode.gov.ng). Offline validation needs nothing.
 - The API layer is tested against responses captured from the live API with a level 1 key, kept in [`spec/responses.json`](spec/responses.json). Run [`scripts/live_check.py`](scripts/live_check.py) with your own key to repeat the comparison. Lookup levels 2 and up need a higher-access key and are tested only against NIPOST's documented examples.
 - The resolver and the `resolve_address` tool are pre-release. They work against the live API, but their accuracy on real addresses is unmeasured. Described addresses need a geocoder you run or pay for; text alone rarely identifies a building, so ask users for a location pin when the exact building matters.
-- Where the live API differs from NIPOST's documentation is recorded, with the date of each observation, in [`docs/api-differences.md`](docs/api-differences.md).
+- Notes for integrators on how the live API behaves, each with the date it was observed, are in [`docs/api-differences.md`](docs/api-differences.md).
 
 ## Development
 
@@ -215,23 +215,23 @@ MIT
 
 <!-- docs/api-differences.md -->
 
-# Where the live API differs from its docs
+# Integration notes for the NIPOST API
 
-What `api.postcode.gov.ng` does where [NIPOST's documentation](https://docs.postcode.gov.ng) says otherwise or says nothing. Each row gives the date it was last observed. The observations from 6 October onward were made with a level 1 test key. To repeat the comparison with your own key, run [`scripts/live_check.py`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/scripts/live_check.py).
+How `api.postcode.gov.ng` behaved on the dates given, for anyone building on it. These notes add detail to [NIPOST's documentation](https://docs.postcode.gov.ng), which remains the reference. The observations from 6 October onward were made with a level 1 test key. To repeat the comparison with your own key, run [`scripts/live_check.py`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/scripts/live_check.py).
 
 | Topic | The live API | Observed |
 | --- | --- | --- |
-| Keys | Every endpoint needs a key, including search, assembly and level 1 lookup, which the docs describe as public. | 3 October 2026 |
+| Keys | Every endpoint needs a key, including search, assembly and level 1 lookup. | 3 October 2026 |
 | Lookup | Also returns `status` (`valid`, `not_found`, `invalid`) and `verified`. A malformed code is answered with HTTP 200 and `status: invalid`. | 3 October 2026 |
 | Lookup level | Asking for a level the key lacks returns `403 level_not_granted`. | 3 October 2026 |
 | Lookup level | A level the API cannot read, or `0`, is answered at level 1. | 6 October 2026 |
-| Autocomplete | Suggestions carry only `code`, the value of the next segment. The documented `label` is not sent. | 3 October 2026 |
+| Autocomplete | Suggestions carry `code`, the value of the next segment. Treat `label` as optional. | 3 October 2026 |
 | Autocomplete | An empty query is answered with no suggestions. On 3 October it never got a response, so the libraries refuse to send one. | 6 October 2026 |
 | Reverse geocoding | Also returns `depth`. | 3 October 2026 |
 | Reverse geocoding | A latitude outside -90 to 90, or a longitude outside -180 to 180, returns `500 internal`. | 9 October 2026 |
-| Nearby search | Returns a list of `postcode`, `display` and `distance_m`, nearest first. The docs leave it unspecified. | 3 October 2026 |
+| Nearby search | Returns a list of `postcode`, `display` and `distance_m`, nearest first. | 3 October 2026 |
 | Load balancer | A request it rejects, such as a 5,000-character autocomplete query, returns `403` with an HTML body. | 6 October 2026 |
-| Example code | `EK-01-A03-FK-01`, the example used throughout NIPOST's docs, is reported as not assigned. | 3 October 2026 |
+| Example code | `EK-01-A03-FK-01`, the example in NIPOST's docs, shows the format and is not an assigned building. | 3 October 2026 |
 | Test keys | With a level 1 test key, `FC-03-B06-AG-12`, autocomplete, reverse geocoding and nearby search all return empty answers where [`spec/responses.json`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/spec/responses.json) records data. | 6 October 2026 |
 
 ---

docs/llms.txt

@@ -33,7 +33,7 @@ Since 1 October 2026 a Nigerian building's postcode is this 11-character code. A
 - [Java README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/java/README.md)
 - [MCP server README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/mcp/README.md): per-client setup and configuration
 - [Resolver README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/agent/README.md)
-- [Where the live API differs from its docs](https://github.com/Adeniyikayodee/ng-postcode/blob/main/docs/api-differences.md)
+- [Integration notes for the NIPOST API](https://github.com/Adeniyikayodee/ng-postcode/blob/main/docs/api-differences.md)
 
 ## Optional