diff --git a/README.md b/README.md
index 8c029ec..94ca50a 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,77 @@
-# CartoLite Server
+
+ 
+
-CartoLite Server is a small, self-hosted live map for standard MeshCore MQTT traffic. It accepts valid coordinates worldwide and serves the map, sanitized API, and live SSE stream from one dependency-light Go process.
+CartoLite Server
-This edition has no country boundary, default region allowlist, Android app, Labs, analytics, database, chat, message history, or operator dashboard. It is intended for community operators who want to connect their own MQTT broker and publish a privacy-safe live topology.
+
+ A calm, musical live map for your MeshCore network.
+ Turn a standard MQTT feed into a fast, privacy-safe topology experience you can host yourself.
+
-## Features
+
+ 
+ 
+ 
+
-- worldwide MapLibre map with CARTO vector geography;
-- live packet trails, route glow, packet-type heat, node clusters, and 24-hour routes;
-- opt-in Aurora, Wood, and Chimes Web Audio scenes;
-- node search, node inspector, newest-first neighbours, Live Follow, hillshade, and 3D terrain;
-- automatic snapshot and SSE recovery after sleep or network loss;
-- one atomic checkpoint at `/data/state-v1.json` and no database;
-- non-root, read-only, capability-free container with bounded memory and logs;
-- no public keys, raw paths, packet bodies, message text, or visitor tracking.
+
+ Start self-hosting ·
+ Deployment guide ·
+ Privacy boundary ·
+ Latest release
+
+
+
+
+Real CartoLite interface shown with synthetic demonstration traffic. No production network data is included.
+
+## See your mesh move
+
+CartoLite Server renders public MeshCore activity as a living map: packet trails travel hop by hop, recently heard routes hold a restrained glow, and packet types keep distinct colours. Optional Web Audio turns every visible live hop into a musical articulation.
+
+
+
+
+ 
+ |
+
+ 
+ |
+
+
+ | Inspect a node, its newest neighbours, and connected routes. |
+ Touch-friendly controls keep the map primary on phones. |
+
+
+
+## Built for community operators
+
+| | |
+|---|---|
+| **Live topology** | Vector geography, packet trails, route glow, packet-type heat, clusters, hillshade, and 3D terrain. |
+| **Find and inspect** | Search downloaded node labels, open node details, and browse neighbours sorted by last heard. |
+| **Musical traffic** | Opt-in Aurora, Wood, and Chimes scenes using native browser audio and visible live hops only. |
+| **Works worldwide** | Accept valid coordinates anywhere, or apply an exact region allowlist for a shared broker. |
+| **Responsive and resilient** | Desktop and phone layouts, Live Follow, saved views, and automatic recovery after sleep or network loss. |
+| **Small operational footprint** | One dependency-light Go service, one atomic checkpoint, no database, and a hardened container. |
+
+## Privacy is the product boundary
+
+The public API exposes only the minimum sanitized data needed to draw the live topology. CartoLite Server does **not** publish public keys, observer keys, raw paths, packet bodies, decoded messages, or resolver details. It includes no visitor analytics, accounts, chat, or message history.
+
+See the exact guarantees in the [privacy documentation](docs/privacy.md) and the stable [public API v2 contract](docs/public-api.md).
## Quick start
-Requirements: Docker Engine, Docker Compose v2, a standard MeshCore MQTT feed, and a CARTO Basemaps API key.
+You need Docker Engine, Docker Compose v2, a standard MeshCore MQTT feed, and your own CARTO Basemaps browser key.
+
+> [!IMPORTANT]
+> No API keys, passwords, or tokens are bundled with this repository. `.env` and `.secrets/` are excluded from Git and the Docker build context.
1. Copy `.env.example` to `.env`.
-2. Create `.secrets/carto-basemap-api-key` and place only your CARTO browser key in it. The directory is excluded from Git and the Docker build context.
-3. Set `MQTT_BROKER_URL`, `MQTT_TOPIC`, and optional MQTT credentials in `.env`.
+2. Create `.secrets/carto-basemap-api-key` and place only your CARTO browser key in it.
+3. Set `MQTT_BROKER_URL`, `MQTT_TOPIC`, and any optional MQTT credentials in `.env`.
4. Build and start your instance:
```sh
@@ -30,9 +80,9 @@ docker compose up -d
curl --fail http://127.0.0.1:8080/readyz
```
-The default bind is loopback-only. Set `CARTOLITE_BIND_ADDR=0.0.0.0` only when you intentionally want LAN access or have placed the service behind a TLS reverse proxy.
+The default bind is loopback-only. Keep it that way behind a TLS reverse proxy, or deliberately set `CARTOLITE_BIND_ADDR=0.0.0.0` for trusted LAN access. The [deployment guide](docs/deployment.md) covers production configuration and updates.
-## MQTT contract
+## MQTT input
The subscriber defaults to `meshcore/#` and accepts the standard topic shape:
@@ -41,15 +91,19 @@ meshcore///packets
meshcore///status
```
-`REGION_ALLOWLIST` is empty by default, so every syntactically valid region is accepted. Set it to exact comma-separated labels such as `EU_WEST,AU_NSW` when one broker carries traffic that should be separated into different public maps. Wildcards are intentionally rejected in this setting; use `MQTT_TOPIC` for subscription scope.
+`REGION_ALLOWLIST` is empty by default, so every syntactically valid region is accepted. Set it to exact comma-separated labels such as `EU_WEST,AU_NSW` when a shared broker should feed separate public maps. Use `MQTT_TOPIC` to narrow the subscription itself.
-The server expects the same packet/status JSON or raw packet hex published by the standard MeshCore MQTT bridge. Unknown topic shapes and malformed messages are counted and ignored.
+The server accepts the standard packet/status JSON or raw packet hex published by a MeshCore MQTT bridge. Unknown topic shapes and malformed messages are counted and ignored.
## Basemap key
-The CARTO key is supplied to Docker as a BuildKit secret. It stays out of source, Compose, image labels, and build logs, but it is necessarily visible in browser tile requests. Use a key whose CARTO project restrictions match your deployment.
+Docker supplies the CARTO key to the web build through a BuildKit secret. It stays out of source, Compose, image labels, and build logs. Like any browser map credential, it is visible to visitors in tile requests after deployment, so use a CARTO project key restricted for your site.
-CartoLite Server does not publish a universal prebuilt image because each operator should build with their own browser-visible basemap key.
+CartoLite Server does not publish a universal prebuilt image because each operator builds the frontend with their own browser-visible basemap key.
+
+## Project scope
+
+This repository contains the standalone server and browser map. It has no country boundary, default region allowlist, Android app, Labs, analytics, database, chat, history, or operator dashboard.
## Documentation
@@ -63,4 +117,4 @@ CartoLite Server does not publish a universal prebuilt image because each operat
## License
-MIT. CartoLite Server is derived from the CartoLite map system and keeps its privacy-first public-data boundary.
+[MIT](LICENSE). CartoLite Server is derived from the CartoLite map system and keeps its privacy-first public-data boundary.
diff --git a/docs/assets/cartolite-inspector.webp b/docs/assets/cartolite-inspector.webp
new file mode 100644
index 0000000..f8b7bda
Binary files /dev/null and b/docs/assets/cartolite-inspector.webp differ
diff --git a/docs/assets/cartolite-mobile.webp b/docs/assets/cartolite-mobile.webp
new file mode 100644
index 0000000..189b48e
Binary files /dev/null and b/docs/assets/cartolite-mobile.webp differ
diff --git a/docs/assets/cartolite-overview.webp b/docs/assets/cartolite-overview.webp
new file mode 100644
index 0000000..ec84d8c
Binary files /dev/null and b/docs/assets/cartolite-overview.webp differ
diff --git a/docs/assets/cartolite-server-logo.png b/docs/assets/cartolite-server-logo.png
new file mode 100644
index 0000000..7431681
Binary files /dev/null and b/docs/assets/cartolite-server-logo.png differ