diff --git a/README.md b/README.md
index ad3330c..42fea22 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,154 @@
-# Nominatim
+# nominatim
 
-Self-hosted Nominatim (OSM geocoding) for homelab LAN — companion to OSRM on ai-server-4080
\ No newline at end of file
+Self-hosted [Nominatim](https://nominatim.org/) (OpenStreetMap geocoding)
+for address search / soft validation on the homelab LAN. Pure OSM data,
+**no API key**, no per-request cost.
+
+Companion to [Ditch_The_Agent/OSRM](https://git.aimloperations.com/Ditch_The_Agent/OSRM)
+(routing) on **ai-server-4080** (`10.0.0.128`).
+
+> **OSRM ≠ Nominatim.** OSRM routes lat/lng. Nominatim turns addresses into
+> coordinates (and reverse). Share the **`.osm.pbf` only** — never mount
+> OSRM `.osrm*` graph files into this stack.
+
+Consumers (e.g. `monica_site`) should use:
+
+```bash
+NOMINATIM_BASE_URL=http://10.0.0.128:8089
+```
+
+Provisioning: [server-infra#16](https://git.aimloperations.com/ai_ml_operations/server-infra/issues/16).
+
+---
+
+## What you get
+
+* `mediagis/nominatim` Docker image (upstream)
+* HTTP API on host port **8089** (container `8080`):
+  * `/search` — forward geocode
+  * `/reverse` — reverse geocode
+  * structured params: `street`, `city`, `state`, `postalcode`, `country`
+* First boot imports a local PBF into an internal Postgres/PostGIS volume
+
+---
+
+## Hardware sizing (rough)
+
+| Region | PBF size | Import RAM | Serve RAM | Disk (DB) |
+|--------|----------|------------|-----------|-----------|
+| US single state (e.g. Ohio) | ~200–400 MB | ~8–16 GB | ~2–4 GB | ~10–30 GB |
+| US Midwest extract | ~1–3 GB | ~16–32 GB | ~4–8 GB | ~40–100 GB |
+| Full US | ~10+ GB | 64 GB+ | 16 GB+ | 200 GB+ |
+
+Import is one-shot and slow. Prefer the **smallest extract** that covers
+your service area (Ohio / Midwest for monica_site). Full US is optional
+and expensive on disk/RAM.
+
+---
+
+## Quick start
+
+```bash
+# from this directory
+mkdir -p data
+cp .env.example .env
+# edit NOMINATIM_PASSWORD + NOMINATIM_PBF_FILE if needed
+
+# 1. Place (or symlink) a Geofabrik PBF into ./data/
+#    Reuse the same PBF used for OSRM — copy/symlink, do not move OSRM's copy
+#    if OSRM still needs it.
+ln -sf /path/to/OSRM/data/us-latest.osm.pbf data/region.osm.pbf
+# or download a smaller extract:
+# curl -L -o data/ohio-latest.osm.pbf \
+#   https://download.geofabrik.de/north-america/us/ohio-latest.osm.pbf
+
+# 2. First up runs the import (long). Keep the container running afterward.
+docker compose up -d
+
+# 3. Watch import / API ready
+docker compose logs -f nominatim
+
+# 4. Smoke test
+curl -sG 'http://localhost:8089/search' \
+  --data-urlencode 'q=Akron, OH' -d 'format=json' -d 'limit=1'
+```
+
+Structured address check:
+
+```bash
+curl -sG 'http://localhost:8089/search' \
+  -d 'street=123 Main St' \
+  -d 'city=Akron' \
+  -d 'state=Ohio' \
+  -d 'postalcode=44301' \
+  -d 'country=USA' \
+  -d 'format=json' \
+  -d 'limit=1'
+```
+
+---
+
+## Running the container
+
+```bash
+docker compose pull
+docker compose up -d
+docker compose logs -f nominatim
+docker compose ps
+docker compose restart nominatim
+docker compose stop
+docker compose down   # keeps named volume with DB unless -v
+```
+
+Set `NOMINATIM_PBF_FILE` in `.env` to the filename under `./data/`
+(default `region.osm.pbf`).
+
+Import only runs when the Postgres data volume is empty. To re-import:
+
+```bash
+docker compose down -v   # destroys nominatim-pgdata
+# ensure data/*.osm.pbf is present
+docker compose up -d
+```
+
+---
+
+## Homelab LAN (adama / roslin → ai-server-4080)
+
+Default bind is `0.0.0.0:8089` so LAN hosts can reach it. Open UFW to the
+LAN only — **not** the public internet:
+
+```bash
+sudo ufw allow from 10.0.0.0/24 to any port 8089 proto tcp comment 'Nominatim homelab LAN'
+sudo ufw status
+```
+
+Verify from another host:
+
+```bash
+curl -sG 'http://10.0.0.128:8089/search' \
+  --data-urlencode 'q=Akron, OH' -d 'format=json' -d 'limit=1'
+```
+
+Local-only bind: set `NOMINATIM_BIND_HOST=127.0.0.1` in `.env`.
+
+---
+
+## Relation to OSRM
+
+| | OSRM (`:5000`) | Nominatim (`:8089`) |
+|--|----------------|---------------------|
+| Job | Route coordinates | Geocode addresses |
+| Input | `.osrm*` graphs | `.osm.pbf` → Postgres |
+| Share | — | **PBF only** |
+
+Typical app flow: Nominatim search → lat/lng → (optional) OSRM route.
+
+---
+
+## License / attribution
+
+Nominatim is GPL-2.0. OpenStreetMap data is © OpenStreetMap contributors,
+ODbL. Attribute on any UI that surfaces geocoded results:
+
+> "Geocoding © OpenStreetMap contributors, via Nominatim."