From cb63b48b7831a5f2f971aeed2efd9e6dfeb8d443 Mon Sep 17 00:00:00 2001
From: zjs81 <zacharysylvester81@gmail.com>
Date: Fri, 20 Mar 2026 02:24:02 -0700
Subject: [PATCH] Add comprehensive documentation for various app features

- Introduced "Contacts" documentation detailing the contact management system, types, list, search, and tap actions.
- Added "Map & Location" documentation covering map features, interactions, path tracing, and line-of-sight analysis.
- Created "Navigation" documentation outlining app flow, QuickSwitchBar, and device screen interactions.
- Developed "Notifications" documentation explaining notification types, in-app badges, settings, and rate limiting.
- Established "Repeater Management" documentation for managing repeaters and room servers, including CLI access and telemetry.
- Compiled "Scanner & Connection" documentation detailing BLE, USB, and TCP connection processes.
- Formulated "Settings" documentation outlining access, layout, device info, app settings, node settings, actions, debug options, export features, and about section.
---
 documentation/README.md                 |  30 +++
 documentation/additional-features.md    | 187 ++++++++++++++++++
 documentation/ble-protocol.md           | 249 ++++++++++++++++++++++++
 documentation/channels.md               | 164 ++++++++++++++++
 documentation/chat-and-messaging.md     | 120 ++++++++++++
 documentation/contacts.md               | 118 +++++++++++
 documentation/map-and-location.md       | 186 ++++++++++++++++++
 documentation/navigation.md             |  87 +++++++++
 documentation/notifications.md          |  92 +++++++++
 documentation/repeater-management.md    | 186 ++++++++++++++++++
 documentation/scanner-and-connection.md | 124 ++++++++++++
 documentation/settings.md               | 169 ++++++++++++++++
 12 files changed, 1712 insertions(+)
 create mode 100644 documentation/README.md
 create mode 100644 documentation/additional-features.md
 create mode 100644 documentation/ble-protocol.md
 create mode 100644 documentation/channels.md
 create mode 100644 documentation/chat-and-messaging.md
 create mode 100644 documentation/contacts.md
 create mode 100644 documentation/map-and-location.md
 create mode 100644 documentation/navigation.md
 create mode 100644 documentation/notifications.md
 create mode 100644 documentation/repeater-management.md
 create mode 100644 documentation/scanner-and-connection.md
 create mode 100644 documentation/settings.md

diff --git a/documentation/README.md b/documentation/README.md
new file mode 100644
index 0000000..1367013
--- /dev/null
+++ b/documentation/README.md
@@ -0,0 +1,30 @@
+# MeshCore Open - Feature Documentation
+
+MeshCore Open is an open-source Flutter client for MeshCore LoRa mesh networking devices. This documentation covers every user-facing feature, how to access it, and what it does.
+
+## Table of Contents
+
+1. [Scanner & Connection](scanner-and-connection.md) - BLE scanning, USB serial, and TCP connection
+2. [Navigation](navigation.md) - App flow, device screen, and quick-switch navigation
+3. [Contacts](contacts.md) - Contact management, groups, discovery, and sharing
+4. [Chat & Messaging](chat-and-messaging.md) - Direct messages, message status, reactions, and retries
+5. [Channels](channels.md) - Broadcast channels, communities, and channel chat
+6. [Map & Location](map-and-location.md) - Node map, path tracing, line-of-sight, and offline caching
+7. [Settings](settings.md) - Device settings, app settings, radio configuration, and exports
+8. [Notifications](notifications.md) - System notifications, unread badges, and notification preferences
+9. [Repeater Management](repeater-management.md) - Repeater hub, status, CLI, telemetry, and neighbors
+10. [Additional Features](additional-features.md) - GIF picker, localization, debug logs, SMAZ compression, and more
+11. [BLE Protocol & Data Layer](ble-protocol.md) - Technical reference for the communication protocol and data architecture
+
+## App Overview
+
+MeshCore Open connects to MeshCore LoRa mesh radios over BLE, USB, or TCP. Once connected, users can:
+
+- **Chat** with other mesh nodes via encrypted direct messages
+- **Broadcast** on shared channels (public, hashtag, private, or community-scoped)
+- **View nodes on a map** with GPS locations, predicted positions, and path traces
+- **Manage repeaters** with CLI access, telemetry, neighbor info, and settings
+- **Share contacts** via `meshcore://` URIs and QR codes
+- **Configure radio settings** including frequency, power, bandwidth, and spreading factor
+- **Cache offline maps** for use without internet connectivity
+- **Analyze line-of-sight** between nodes with terrain elevation profiles
diff --git a/documentation/additional-features.md b/documentation/additional-features.md
new file mode 100644
index 0000000..f7b8319
--- /dev/null
+++ b/documentation/additional-features.md
@@ -0,0 +1,187 @@
+# Additional Features
+
+## GIF Picker (Giphy Integration)
+
+### How to Access
+In any chat screen (direct or channel), tap the GIF button in the message input bar.
+
+### What the User Sees
+A bottom sheet with a search field and a grid of GIF thumbnails.
+
+### Key Interactions
+- On open, loads trending GIFs (G-rated, 25 results)
+- Type to search and press the keyboard submit button (search triggers on submit, not on each keystroke). Clearing the search field reloads trending GIFs
+- On network/API errors, a "Retry" button is shown in-place
+- Tap a GIF to select it — the chat input shows an inline preview with an X button to dismiss
+- Send the message to transmit the GIF reference (`g:<giphy-id>`)
+- Recipients see the GIF rendered inline via Giphy CDN
+- "Powered by Giphy" attribution is always shown at the bottom of the picker
+- The bottom sheet occupies 70% of screen height
+
+---
+
+## Localization / Multi-Language Support
+
+### How to Access
+App Settings → Appearance → Language
+
+### Supported Languages (15)
+English, French, Spanish, German, Polish, Slovenian, Portuguese, Italian, Chinese, Swedish, Dutch, Slovak, Bulgarian, Russian, Ukrainian
+
+### How It Works
+- All UI strings go through Flutter's ARB localization system
+- Language can follow the system locale or be explicitly overridden
+- Changes take effect immediately
+
+---
+
+## Discovered Contacts Screen
+
+### How to Access
+From Contacts screen → overflow menu → "Discovered Contacts"
+
+### What the User Sees
+A list of nodes heard passively over the air but not yet added as contacts. Each shows:
+- Color-coded avatar (by type)
+- Name
+- Short public key
+- Last-seen time
+
+### Key Interactions
+- Search bar with debounced filtering
+- Sort by last seen or name; filter by type
+- **Tap**: Import the contact (adds to your contact list)
+- **Long-press**: Add Contact, Copy `meshcore://` URI to clipboard, or Delete
+- Overflow menu → "Delete All" (with confirmation)
+- Already-known contacts and your own node are filtered out
+
+---
+
+## SMAZ Compression
+
+### What It Is
+An optional per-contact and per-channel text compression feature using the SMAZ algorithm (optimized for short English text).
+
+### How to Enable
+- **Per contact**: Chat screen → info button → toggle "SMAZ compression"
+- **Per channel**: Long-press channel → Edit → toggle "SMAZ compression"
+
+### How It Works
+- When enabled, compression is applied using a "compress only if smaller" strategy — the message is only transmitted compressed if the encoded result is actually shorter than the original. Otherwise, the original text is sent uncompressed
+- Compressed messages are transmitted with a `s:` prefix followed by base64-encoded data
+- Recipients using MeshCore Open will decompress automatically. **Recipients using other software** that is not SMAZ-aware will see garbled `s:...` text
+- The codec operates on ASCII. Non-ASCII / non-English text generally does not benefit from compression and may even expand. Best suited for short English messages
+- Disabled by default
+
+---
+
+## Community QR Scanner
+
+### How to Access
+From Channels screen → "+" FAB → "Scan Community QR"
+
+### What the User Sees
+A live QR scanner view with instruction text overlay.
+
+### Key Interactions
+- Scan a community QR code shared by another member
+- On valid scan: confirmation dialog showing community name and ID
+- Option to "Add public channel to device" on join
+- If already a member: shows an "Already a member" dialog
+- Invalid QR: shows an orange error snackbar
+
+---
+
+## Channel Message Path Viewing
+
+### How to Access
+In a channel chat, tap a message bubble (mobile) or use the "Path" action (desktop).
+
+### What the User Sees
+- Summary card: sender, time, repeat count, path type, observed hops
+- "Other Observed Paths" section (if multiple paths detected)
+- "Repeater Hops" section listing each hop with hex prefix, resolved name, and GPS coordinates
+
+### Actions
+- **Radar icon**: Opens path trace map for live trace
+- **Map icon**: Opens a map with hop markers and polyline
+- **Path dropdown**: Switch between observed path variants (if multiple)
+
+---
+
+## Debug Logging
+
+### BLE Debug Log
+**Access**: Settings → BLE Debug Log
+
+Two views:
+- **Frames**: Each BLE frame with direction, description, hex preview, timestamp. Long-press to copy hex.
+- **Raw Log RX**: Decoded LoRa packets with route type, payload type, path bytes, and summary.
+
+### App Debug Log
+**Access**: Settings → App Debug Log (must be enabled first in App Settings → Debug)
+
+Structured log entries with level (Info/Warning/Error), tag, message, and timestamp.
+
+Both logs support copy-all and clear operations.
+
+---
+
+## Chrome Required Screen
+
+### When It Appears
+Automatically shown on web platforms when a non-Chromium browser is detected.
+
+### What the User Sees
+A full-screen informational page explaining that Web Bluetooth requires a Chromium-based browser. No interactive elements — purely informational.
+
+---
+
+## Path History Service
+
+### What It Does (Background Service)
+Maintains an in-memory LRU cache of up to 50 contacts, each with up to 100 route history entries, tracking:
+- Hop count and trip time
+- Success/failure counts and route weights
+- Flood vs. direct discovery
+
+### Path Scoring
+Paths are scored using a weighted formula: reliability (45%), route weight (20%), latency (25%), and freshness (10%). These weights are internal and not user-configurable. Paths whose weight drops to zero or below are automatically deleted. Flood deliveries that receive an ACK give a weight boost (+0.5) to the specific return path.
+
+Used internally for:
+- **Auto route rotation**: Cycles through known paths using configurable weights on retries, with a diversity window to avoid re-using recently tried paths
+- **Path selection**: Picks the best-scored path for each retry attempt
+- **Flood statistics**: Tracks flood vs. direct discovery ratios
+
+---
+
+## Message Retry Service
+
+### What It Does (Background Service)
+Handles reliable delivery of outgoing direct messages:
+1. Assigns a UUID and sends immediately. Only one message per contact can be in-flight at a time (avoids overflowing the firmware's 8-entry ACK table); subsequent messages are queued
+2. Listens for ACK frames matched via SHA-256 hash of `[timestamp][attempt][text][sender_pubkey]`
+3. On timeout, retries with exponential backoff: `1000 × 2^retryCount` ms (1s, 2s, 4s, 8s...)
+4. Each retry may use a different path (via path history diversity window)
+5. After max retries: marks failed but keeps a **30-second grace window** during which a late ACK can still resolve the message to "delivered". Optionally clears the contact's path
+6. Reports RTT and path data for quality learning
+7. Maintains an ACK hash history (last 50 entries) to handle duplicate ACKs
+
+### Configurable Settings (App Settings → Messaging)
+- Max retries (2–10, default 5)
+- Clear path on max retry (on/off)
+- Auto route rotation with weight parameters
+
+---
+
+## Timeout Prediction (ML)
+
+### What It Does (Background Service)
+An ML-based service that predicts expected delivery timeouts:
+- Collects delivery observations (path length, message size, time since last RX, delivery time) in a sliding window of up to 100 observations (oldest evicted first)
+- Requires **10 minimum observations** before first training. After that, retrains every 5 new observations
+- Applies a **1.5x safety margin** to raw predictions (the actual timeout issued is 1.5× the model's predicted delivery time)
+- Features with zero variance are automatically excluded from training
+- Blends per-contact statistics with ML predictions
+- Falls back to `3000 + 3000 × pathLength` ms when insufficient data
+- Observations are persisted to storage via a 2-second debounced timer (observations within 2s of app termination may be lost)
diff --git a/documentation/ble-protocol.md b/documentation/ble-protocol.md
new file mode 100644
index 0000000..9f4c1d7
--- /dev/null
+++ b/documentation/ble-protocol.md
@@ -0,0 +1,249 @@
+# BLE Protocol & Data Layer
+
+This is a technical reference for the communication protocol and data architecture.
+
+## Transport Layer
+
+The app supports three transports, all sharing the same command/response protocol:
+
+| Transport | Method | Implementation |
+|---|---|---|
+| Bluetooth LE | Nordic UART Service (NUS) GATT | `flutter_blue_plus` |
+| USB Serial | Packet-framed serial | `MeshCoreUsbManager` |
+| TCP | Packet-framed socket | `MeshCoreTcpConnector` |
+
+### BLE (Nordic UART Service)
+
+- **Service UUID**: `6e400001-b5a3-f393-e0a9-e50e24dcca9e`
+- **RX Characteristic** (write to device): `6e400002-b5a3-f393-e0a9-e50e24dcca9e`
+- **TX Characteristic** (notify from device): `6e400003-b5a3-f393-e0a9-e50e24dcca9e`
+
+Raw `Uint8List` payloads are written directly to the RX characteristic. Writes use "write without response" if supported, falling back to "write with response".
+
+### USB and TCP Framing
+
+Both use a lightweight packet framing codec:
+
+```
+TX (host → device):  [0x3C][len_lo][len_hi][payload...]
+RX (device → host):  [0x3E][len_lo][len_hi][payload...]
+```
+
+- Frame start: `0x3C` (`<`) for outgoing, `0x3E` (`>`) for incoming
+- Length: 2-byte little-endian, payload only
+- Max payload: 172 bytes
+- TCP: `tcpNoDelay: true` (Nagle disabled), writes serialized to prevent interleaving
+- USB: 10ms post-write delay between frames
+
+## Connection State Machine
+
+```
+enum MeshCoreConnectionState {
+  disconnected,
+  scanning,
+  connecting,
+  connected,
+  disconnecting,
+}
+```
+
+## BLE Connection Lifecycle
+
+1. **Scan** with keyword filters `["MeshCore-", "Whisper-"]`
+2. **Connect** with 15-second timeout
+3. **Request MTU** 185 bytes (non-web only)
+4. **Discover services** and locate NUS
+5. **Enable TX notifications** (up to 3 attempts on native)
+6. **Subscribe** to TX characteristic for incoming frames
+7. **Initial sync**: device info query, time sync, channel sync
+
+## Auto-Reconnect (BLE Only)
+
+On unexpected disconnection, auto-reconnect with exponential backoff:
+- Delays: 1s, 2s, 4s, 8s, 16s, 30s, 30s...
+- Resets on successful connection
+- Disabled for manual disconnects
+- Not available for USB or TCP
+
+## Protocol Constants
+
+| Constant | Value | Description |
+|---|---|---|
+| Max frame size | 172 bytes | BLE/USB/TCP payload limit |
+| Public key size | 32 bytes | Ed25519 public key |
+| Max path size | 64 bytes | Maximum path data |
+| Max name size | 32 bytes | Maximum node name |
+| Max text payload | 160 bytes | Firmware `MAX_TEXT_LEN` |
+| App protocol version | 3 | Sent in device query |
+| Contact frame size | 148 bytes | Fixed-size contact record |
+
+## Command Codes (App → Device)
+
+| Code | Name | Description |
+|------|------|-------------|
+| 1 | CMD_APP_START | Announce app connection |
+| 2 | CMD_SEND_TXT_MSG | Send direct text message |
+| 3 | CMD_SEND_CHANNEL_TXT_MSG | Send channel text message |
+| 4 | CMD_GET_CONTACTS | Request contact list |
+| 5 | CMD_GET_DEVICE_TIME | Query device clock |
+| 6 | CMD_SET_DEVICE_TIME | Set device clock |
+| 7 | CMD_SEND_SELF_ADVERT | Broadcast own advertisement |
+| 8 | CMD_SET_ADVERT_NAME | Set node name |
+| 9 | CMD_ADD_UPDATE_CONTACT | Add or update a contact |
+| 10 | CMD_SYNC_NEXT_MESSAGE | Request next queued message |
+| 11 | CMD_SET_RADIO_PARAMS | Set radio parameters |
+| 12 | CMD_SET_RADIO_TX_POWER | Set TX power |
+| 13 | CMD_RESET_PATH | Reset contact path |
+| 14 | CMD_SET_ADVERT_LATLON | Set advertised location |
+| 15 | CMD_REMOVE_CONTACT | Remove a contact |
+| 16 | CMD_SHARE_CONTACT | Share contact to mesh |
+| 17 | CMD_EXPORT_CONTACT | Export contact as bytes |
+| 18 | CMD_IMPORT_CONTACT | Import contact from bytes |
+| 19 | CMD_REBOOT | Reboot device |
+| 20 | CMD_GET_BATT_AND_STORAGE | Query battery and storage |
+| 22 | CMD_DEVICE_QUERY | Query device info |
+| 26 | CMD_SEND_LOGIN | Login to repeater/room |
+| 27 | CMD_SEND_STATUS_REQ | Request repeater status |
+| 30 | CMD_GET_CONTACT_BY_KEY | Get contact by public key |
+| 31 | CMD_GET_CHANNEL | Get channel definition |
+| 32 | CMD_SET_CHANNEL | Set channel name and PSK |
+| 36 | CMD_SEND_TRACE_PATH | Request path trace |
+| 38 | CMD_SET_OTHER_PARAMS | Set misc parameters |
+| 39 | CMD_GET_TELEMETRY_REQ | Request sensor telemetry |
+| 40 | CMD_GET_CUSTOM_VAR | Get custom variables |
+| 41 | CMD_SET_CUSTOM_VAR | Set a custom variable |
+| 50 | CMD_SEND_BINARY_REQ | Send binary request |
+| 57 | CMD_SEND_ANON_REQ | Send anonymous request |
+| 58 | CMD_SET_AUTO_ADD_CONFIG | Set auto-add configuration |
+| 59 | CMD_GET_AUTO_ADD_CONFIG | Get auto-add configuration |
+
+## Response / Push Codes (Device → App)
+
+| Code | Name | Description |
+|------|------|-------------|
+| 0 | RESP_CODE_OK | Generic success |
+| 1 | RESP_CODE_ERR | Generic error |
+| 2 | RESP_CODE_CONTACTS_START | Contact list begins |
+| 3 | RESP_CODE_CONTACT | Single contact data |
+| 4 | RESP_CODE_END_OF_CONTACTS | Contact list complete |
+| 5 | RESP_CODE_SELF_INFO | Device self-info response |
+| 6 | RESP_CODE_SENT | Message transmitted; carries `[1]=is_flood, [2–5]=ack_hash, [6–9]=estimated_timeout_ms` |
+| 7 | RESP_CODE_CONTACT_MSG_RECV | Incoming direct message (v2) |
+| 8 | RESP_CODE_CHANNEL_MSG_RECV | Incoming channel message (v2) |
+| 10 | RESP_CODE_NO_MORE_MESSAGES | No more queued messages |
+| 11 | RESP_CODE_EXPORT_CONTACT | Exported contact data |
+| 9 | RESP_CODE_CURR_TIME | Current device time |
+| 12 | RESP_CODE_BATT_AND_STORAGE | Battery mV (uint16 LE) + storage used/total (uint32 LE each) |
+| 13 | RESP_CODE_DEVICE_INFO | Firmware info |
+| 16 | RESP_CODE_CONTACT_MSG_RECV_V3 | Incoming direct message (v3) |
+| 17 | RESP_CODE_CHANNEL_MSG_RECV_V3 | Incoming channel message (v3) |
+| 18 | RESP_CODE_CHANNEL_INFO | Channel definition |
+| 21 | RESP_CODE_CUSTOM_VARS | Custom variables |
+| 25 | RESP_CODE_AUTO_ADD_CONFIG | Auto-add flags |
+| 0x80 | PUSH_CODE_ADVERT | Known contact re-seen |
+| 0x81 | PUSH_CODE_PATH_UPDATED | Better path found; carries the 32-byte public key of the updated contact |
+| 0x82 | PUSH_CODE_SEND_CONFIRMED | Delivery ACK from remote; carries ACK hash (4 bytes) + trip time (4 bytes) |
+| 0x83 | PUSH_CODE_MSG_WAITING | Offline messages queued |
+| 0x85 | PUSH_CODE_LOGIN_SUCCESS | Repeater/room login succeeded |
+| 0x86 | PUSH_CODE_LOGIN_FAIL | Repeater/room login failed |
+| 0x87 | PUSH_CODE_STATUS_RESPONSE | Repeater status response |
+| 0x88 | PUSH_CODE_LOG_RX_DATA | Radio RX data with SNR (int8, units 1/4 dB), RSSI, and raw radio packet |
+| 0x89 | PUSH_CODE_TRACE_DATA | Path trace result |
+| 0x8A | PUSH_CODE_NEW_ADVERT | New node discovered |
+| 0x8B | PUSH_CODE_TELEMETRY_RESPONSE | Sensor telemetry data |
+| 0x8C | PUSH_CODE_BINARY_RESPONSE | Binary data response |
+
+## Data Models
+
+### Contact
+32-byte public key (primary identity), name, type (chat/repeater/room/sensor), flags, path data, GPS coordinates, last-seen timestamp. Parsed from 148-byte firmware frames with this layout:
+
+```
+[0]     = resp_code
+[1–32]  = public key (32 bytes)
+[33]    = type (1=chat, 2=repeater, 3=room, 4=sensor)
+[34]    = flags (bit 0 = favorite)
+[35]    = path_length
+[36–99] = path (64 bytes)
+[100–131] = name (32 bytes, null-padded)
+[132–135] = timestamp (uint32 LE)
+[136–139] = latitude (int32 LE, × 1e-6 degrees)
+[140–143] = longitude (int32 LE, × 1e-6 degrees)
+[144–147] = last_modified (uint32 LE)
+```
+
+### Message (Direct)
+Sender key, text, timestamp, outgoing flag, status (pending/sent/delivered/failed), message ID (UUID), retry count, ACK hash, trip time, path data, reactions.
+
+### Channel Message
+Sender name, text, timestamp, status (pending/sent/failed), repeater hops, path variants, channel index, reactions, reply threading fields.
+
+### Channel
+Index (0–7), name, 16-byte PSK, unread count. PSK derivation methods for hashtag (SHA-256) and community (HMAC-SHA256) channels.
+
+### Community
+UUID, name, 32-byte secret, hashtag channel list. Shared via QR code.
+
+## Persistence
+
+All data is stored via `SharedPreferences` (JSON-serialized). No SQLite or other database.
+
+| Data | Storage Key Pattern | Scope |
+|---|---|---|
+| Contacts | `contacts<pubKey10>` | Per device identity |
+| Messages | `messages_<pubKey10><contactKey>` | Per device + contact |
+| Channel Messages | `channel_messages_<pubKey10><index>` | Per device + channel |
+| Channels | `channels<pubKey10>` | Per device identity |
+| Channel Order | `channel_order_<pubKey10>` | Per device identity |
+| Contact Groups | `contact_groups<pubKey10>` | Per device identity |
+| Communities | `communities_v1<pubKey10>` | Per device identity |
+| Unread Counts | `contact_unread_count<pubKey10>` | Per device identity |
+| Discovered Contacts | `discovered_contacts` | Global |
+| App Settings | `app_settings` | Global |
+| Path History | `path_history_<contactKey>` | Per contact |
+
+## Auto-Add Configuration Bitmask
+
+Used by `CMD_SET_AUTO_ADD_CONFIG` (58) and `RESP_CODE_AUTO_ADD_CONFIG` (25):
+
+| Bit | Flag | Description |
+|-----|------|-------------|
+| 0 | 0x01 | Overwrite oldest contact when list is full |
+| 1 | 0x02 | Auto-add chat users |
+| 2 | 0x04 | Auto-add repeaters |
+| 3 | 0x08 | Auto-add room servers |
+| 4 | 0x10 | Auto-add sensors |
+
+## Radio Packet Payload Types
+
+Seen inside `PUSH_CODE_LOG_RX_DATA` raw packets:
+
+| Code | Type |
+|------|------|
+| 0x00 | REQ (request) |
+| 0x01 | RESPONSE |
+| 0x02 | TXTMSG (text message) |
+| 0x03 | ACK |
+| 0x04 | ADVERT |
+| 0x05 | GRPTXT (group/channel text) |
+| 0x06 | GRPDATA (group data) |
+| 0x07 | ANONREQ (anonymous request) |
+| 0x08 | PATH |
+| 0x09 | TRACE |
+| 0x0A | MULTIPART |
+| 0x0B | CONTROL |
+| 0x0F | RAW_CUSTOM |
+
+## State Management
+
+Uses Flutter `Provider` with `ChangeNotifier`. The central state holder is `MeshCoreConnector`, which owns all in-memory collections and fires debounced (50ms) `notifyListeners()` to update the UI. In-memory conversations are windowed to 200 messages per contact; older messages remain on disk and are loaded on demand.
+
+### Data Flow
+
+1. Raw frames arrive over BLE/USB/TCP
+2. First byte is parsed as response/push code
+3. Appropriate model factory (`fromFrame()`) parses the data
+4. In-memory collections are updated
+5. Storage stores are persisted (async)
+6. `notifyListeners()` triggers UI rebuilds
+7. Screens read current state via getters
diff --git a/documentation/channels.md b/documentation/channels.md
new file mode 100644
index 0000000..21fb52e
--- /dev/null
+++ b/documentation/channels.md
@@ -0,0 +1,164 @@
+# Channels
+
+## Overview
+
+Channels are broadcast group-chat spaces secured by a 16-byte pre-shared key (PSK). Any device with the same channel index and PSK will receive and decrypt channel messages. Unlike direct messages, channel messages are broadcast to the entire mesh.
+
+Up to 8 channels (indices 0–7) can be active simultaneously on one device.
+
+## How to Access
+
+QuickSwitchBar tab 1 (middle) from any main screen.
+
+## Channel Types
+
+| Type | Icon | Color | Description |
+|---|---|---|---|
+| Public | Globe | Green | Fixed well-known PSK; any device can join |
+| Hashtag | Hash tag | Blue | PSK derived from the hashtag name via SHA-256; discoverable by convention |
+| Private | Lock | Blue | Random PSK; requires out-of-band sharing of the 32-hex key |
+| Community | Groups/Tag | Purple | PSK derived via HMAC-SHA256 from a community's shared secret |
+
+## Channels List Screen
+
+### What the User Sees
+
+- **Search bar** with live text filtering (300ms debounce)
+- **Sort/filter button**
+- **Scrollable list of channel cards**, each showing:
+  - Type icon with color coding (purple badge overlay for community channels)
+  - Channel name (or "Channel N" if unnamed)
+  - Subtitle: "Public channel", "Hashtag channel", "Private channel", or "Community channel - {name}"
+  - Unread badge (if messages are unread)
+  - Drag handle (when manual sort is active)
+- **"+" FAB** to add a new channel
+- **Overflow menu**: Disconnect, Manage Communities (only shown when at least one community exists), Settings
+
+If no channels exist, an empty state with an "Add Public Channel" shortcut is shown. If a search produces no results, a separate "no results" empty state with a search-off icon is shown.
+
+Pull-to-refresh (swipe down) forces a re-fetch of channels from the device firmware.
+
+### Sorting Options
+
+- **Manual** (default): Drag-and-drop reordering, persisted (drag handles are hidden when a search query is active)
+- **A–Z**: Alphabetical
+- **Latest messages**: Most recent first
+- **Unread**: Most unread first
+
+## Adding a Channel
+
+Tap the "+" FAB to open a dialog with six options:
+
+1. **Create Private Channel** — Enter a name (max 31 characters); a random PSK is generated
+2. **Join Private Channel** — Enter a name and a 32-hex PSK (non-hex characters like spaces and dashes are silently stripped, so pasted keys with formatting are accepted)
+3. **Join Public Channel** — One tap; uses the well-known public PSK (only shown if no public channel exists)
+4. **Join Hashtag Channel** — Enter a hashtag name; PSK is derived from the name. If communities exist, choose between regular hashtag (SHA-256) or community hashtag (HMAC)
+5. **Scan Community QR** — Opens QR scanner to join a community
+6. **Create Community** — Enter a name; generates a random 32-byte secret; optionally adds a community public channel; shows QR code for sharing
+
+## Channel Actions (Long-Press / Right-Click)
+
+| Action | Description |
+|---|---|
+| Edit | Change name, PSK (with a dice icon to generate a random PSK), or SMAZ compression toggle (compresses outgoing messages to allow longer text within the byte limit) |
+| Mute / Unmute | Toggle push notification suppression for this channel |
+| Delete | Remove the channel from the device (confirmation required) |
+
+## Channel Chat
+
+Tap a channel card to open the channel chat screen.
+
+### App Bar
+
+- Type icon (public/private/hashtag)
+- Channel name
+- Subtitle: "{type} - {N} unread"
+
+### Message Display
+
+- Reverse-scrolling list (newest at bottom)
+- **Incoming messages**: Colored avatar with sender's initial (or first emoji if name starts with one; color is deterministic from sender name hash), sender name in primary color, message bubble
+- **Outgoing messages**: Primary container color bubble with a small status icon: pending (clock), sent (checkmark), or failed (red error circle)
+- Automatic older-message loading on scroll-to-top
+- Jump-to-bottom button when scrolled up
+- **Pinch-to-zoom**: Two-finger zoom (0.8x–1.8x) and double-tap to reset text size
+- **Message tracing mode** (when enabled in App Settings): Each bubble additionally shows path prefix bytes (`via XX,YY,...`), a timestamp, and a repeat count icon
+
+### Message Types in Chat
+
+- **Plain text** with linkified URLs
+- **GIFs** (`g:{gifId}`) rendered inline via Giphy CDN
+- **Location pins** (`m:{lat},{lon}|{label}|`) shown as tappable location cards
+- **Reactions** displayed as emoji pills below target messages
+
+### Replies (Channel Chat Only)
+
+- **Mobile**: Swipe an **incoming** message left to trigger reply (with haptic feedback). You cannot swipe your own outgoing messages. Swipe reply is not available on desktop.
+- **All platforms**: Long-press → "Reply"
+- Reply banner appears above the input bar with the quoted message (tap X to cancel)
+- Sent replies are prefixed `@[{senderName}] {text}`
+- Received replies show a bordered quote block inside the bubble; tapping scrolls to the original. Reply previews render GIF thumbnails and location pin icons, not just text.
+
+### Message Path Viewing
+
+- **Mobile**: Tap a message bubble to view its routing path
+- **Desktop**: Long-press/right-click → "Path" (tapping the bubble does nothing on desktop)
+- Opens the Channel Message Path Screen (see [Additional Features](additional-features.md))
+
+### Context Actions (Long-Press / Right-Click)
+
+| Action | Availability | Description |
+|---|---|---|
+| Reply | All messages | Triggers reply mode |
+| Path | Desktop only | Opens message path view |
+| Add Reaction | Incoming messages only | Opens emoji picker (cannot react to your own messages) |
+| Copy | All messages | Copies text to clipboard |
+| Delete | All messages | Removes locally (not from mesh) |
+
+### Message Path Viewing
+
+Tap a message bubble to open the Channel Message Path Screen, which shows:
+- Each hop in the path as a visual chain
+- Known contacts identified by name at each hop
+- Observed vs. declared hop counts
+- Alternative path variants (if received via multiple paths)
+- Map view buttons for geographic path visualization
+
+## Communities
+
+Communities are a layer above channels that provide a private namespace.
+
+### What is a Community?
+
+A community has a name and a 32-byte random secret. Channel PSKs are derived from this secret:
+- **Public channel**: `HMAC-SHA256(secret, "channel:v1:__public__")[:16]`
+- **Hashtag channel**: `HMAC-SHA256(secret, "channel:v1:{hashtag}")[:16]`
+
+Outsiders who don't know the secret cannot discover or join community channels.
+
+### Sharing a Community
+
+Communities are shared via QR codes containing a JSON payload:
+```json
+{"v": 1, "type": "meshcore_community", "name": "...", "k": "<base64url-secret>"}
+```
+
+### Managing Communities
+
+From the channels screen overflow menu → "Manage Communities". Opens a draggable scrollable sheet (resizable 30–90% of screen height):
+
+- Each community shows its name and a short community ID (first 8 hex characters)
+- **Tap a community** to directly show its QR code for sharing
+- **Popup menu** per community:
+  - **Show QR** — displays the QR code for sharing with new members
+  - **Delete** — removes the community locally and deletes all associated device channels (confirmation dialog warns how many channels will be removed)
+
+## How Channels Differ from Direct Messages
+
+| Aspect | Channels | Direct Messages |
+|---|---|---|
+| Addressing | Broadcast to all nodes with matching PSK | Point-to-point to a specific contact |
+| Encryption | Shared PSK (symmetric) | Contact's public key (asymmetric) |
+| Sender identity | Plain text prefix in payload | Verified via public key |
+| Replies | Supported (swipe or long-press) | Not supported |
+| Retry mechanism | No automatic retry | Exponential backoff with path rotation |
diff --git a/documentation/chat-and-messaging.md b/documentation/chat-and-messaging.md
new file mode 100644
index 0000000..22030d5
--- /dev/null
+++ b/documentation/chat-and-messaging.md
@@ -0,0 +1,120 @@
+# Chat & Messaging
+
+## Overview
+
+The app supports two chat modes:
+- **Direct messages**: Encrypted point-to-point messages to individual contacts
+- **Channel messages**: Broadcast messages to shared channels (see [Channels](channels.md))
+
+This page covers direct messaging. For channel chat, see the Channels documentation.
+
+## How to Access
+
+From the Contacts screen, tap any Chat-type contact to open the ChatScreen.
+
+## Chat Screen Layout
+
+### App Bar
+
+- **Title**: Contact name
+- **Subtitle**: Current routing path label (e.g., "2 hops", "flood (auto)", "direct (forced)") and unread count. Tapping the subtitle shows the full path details.
+- **Action buttons**:
+  - **Routing mode** (waves icon): Switch between Auto, Direct, and Flood routing
+  - **Path management** (timeline icon): View recent paths with hop count, round-trip time, age, and success count. Paths are color-coded by direct repeater (green/yellow/red/blue for ranked repeaters, grey for unknown). Tap a path to activate it (the device verifies and confirms via snackbar), long-press to view full path details, set custom paths, or force flood mode. A warning banner appears when history reaches 100 entries.
+  - **Info** (info icon): Contact info dialog showing type, path, GPS coordinates, public key, and SMAZ compression toggle
+
+### Message List
+
+- Scrollable list with newest messages at the bottom
+- **Outgoing messages**: Right-aligned, primary color background. **Failed messages** change to a red-toned error container background
+- **Incoming messages**: Left-aligned, grey background with a colored avatar (initial letter or first emoji of sender name; color is deterministic from a hash of the sender name)
+- Bubble width capped at 65% of screen width
+- Hyperlinks rendered as tappable green underlined text
+- **Pinch-to-zoom**: Two-finger zoom (0.8x–1.8x) and double-tap to reset
+- **Jump to bottom**: Floating button appears when scrolled away from the bottom
+- **Lazy loading**: Scrolling to top loads older messages from storage
+
+### Input Bar
+
+- **GIF button** (left): Opens GIF picker bottom sheet
+- **Text field** (center): Auto-capitalization, enforces UTF-8 byte limit in real-time
+- **Send button** (right): Submits the message
+- On desktop: Enter/Numpad Enter also submits
+- When a GIF is selected, the text field shows an inline GIF preview with a dismiss button
+
+## Message Types
+
+| Type | Wire Format | Display |
+|---|---|---|
+| Plain text | Raw UTF-8 string | Inline text with link detection |
+| GIF | `g:<giphy-id>` | Inline GIF image from Giphy CDN |
+| Location pin | `m:<lat>,<lon>\|<label>\|...` | Location icon + label; tap to open map |
+| Reaction | `r:<hash>:<emoji-index>` | Applied to target message as emoji pill |
+
+## Message Status
+
+Outgoing messages display a status indicator:
+
+| Status | Icon | Meaning |
+|---|---|---|
+| Pending | Grey double-check | Queued, waiting for device to transmit (visually identical to Sent) |
+| Sent | Grey double-check | Device confirmed transmission (visually identical to Pending) |
+| Delivered | Green double-check | Remote node acknowledged receipt |
+| Failed | Red X | All retries exhausted |
+
+### Message Tracing Mode
+
+When enabled in App Settings, additional metadata appears inside each bubble:
+- Timestamp (HH:MM)
+- Retry count (e.g., "Retry 2 of 4")
+- Status icon
+- Round-trip time in seconds (if delivered)
+
+## Message Length Limits
+
+- **Direct messages**: 156 bytes (UTF-8) — enforced in real-time by the input formatter
+- **Channel messages**: 160 minus sender name length minus 2 bytes for the `"<name>: "` prefix
+- Over-length paste shows a snackbar error
+
+## Send Queue
+
+Only one message per contact can be in-flight at a time (to avoid overflowing the firmware's 8-entry ACK table). If you send multiple messages rapidly, they are queued and sent sequentially — each waits for the previous one to be delivered, fail, or exhaust retries before transmitting.
+
+## Retry Mechanism
+
+When a direct message is sent:
+
+1. The app computes an expected ACK hash: `SHA256([timestamp][attempt][text][selfPubKey])[0:4]` — matching the firmware's hash calculation. If SMAZ compression is enabled, the compressed text (not the original) is hashed
+2. On device acknowledgment (`RESP_CODE_SENT`), the message transitions to "sent" and a timeout timer starts
+3. **Timeout duration**: Preferably from the ML timeout prediction service; otherwise `3000 + 3000 × path_length` milliseconds (15000ms for flood)
+4. On timeout, the message is retried with **exponential backoff**: `1000 × 2^retryCount` ms (1s, 2s, 4s, 8s, 16s...)
+5. **Max retries**: Configurable (default 5, range 2–10)
+6. After max retries, the message is marked "failed" — but a **30-second grace window** remains during which a late ACK can still resolve the message to "delivered"
+7. If **Clear Path on Max Retry** is enabled (App Settings), the contact's stored routing path is automatically cleared when max retries are exhausted
+8. **Auto route rotation**: When enabled (and no manual path override is set), the retry service uses a diversity window to avoid re-using recently tried paths, cycling through known routes on each attempt
+
+### Manual Retry
+
+Long-press a failed message → "Retry" to re-send using the current routing settings.
+
+## Reactions
+
+Add emoji reactions to incoming messages (not your own):
+
+1. Long-press (or right-click on desktop) a message
+2. Select "Add reaction" from the context menu
+3. Choose from quick emojis (thumbs up, heart, laugh, party, clap, fire) or browse the full emoji picker
+4. Reactions appear as pills below the message bubble with emoji and count
+5. Pending reactions show at 50% opacity with a spinner
+6. Failed reactions show a red retry icon (tap to retry)
+
+## Context Actions (Long-Press / Right-Click)
+
+| Action | Availability | Description |
+|---|---|---|
+| Add reaction | Incoming messages only | Opens emoji picker |
+| View path | Mobile: tap bubble directly; Desktop: long-press/right-click menu | Shows message routing path |
+| Copy | All messages | Copies text to clipboard |
+| Delete | All messages | Removes locally (not from mesh) |
+| Retry | Failed outgoing messages | Re-sends the message |
+| Open chat with sender | Room server chats | Opens 1:1 chat with the message sender |
diff --git a/documentation/contacts.md b/documentation/contacts.md
new file mode 100644
index 0000000..1a94ba2
--- /dev/null
+++ b/documentation/contacts.md
@@ -0,0 +1,118 @@
+# Contacts
+
+## Overview
+
+The Contacts screen is the primary hub for managing mesh nodes your radio has a relationship with. A "contact" is any node whose cryptographic advertisement has been received — it can be a chat user, repeater, room server, or sensor.
+
+## How to Access
+
+- Automatically shown after connecting to a device
+- QuickSwitchBar tab 0 (leftmost) from Channels or Map screens
+- Back navigation from Chat or Settings screens
+
+## Contact Types
+
+| Type | Avatar Color | Icon | Description |
+|---|---|---|---|
+| Chat | Blue | Chat bubble | Another user's mesh radio |
+| Repeater | Orange | Cell tower | A mesh repeater/relay node |
+| Room | Purple | Group | A room server for group chat |
+| Sensor | Green | Sensors | A sensor device |
+
+## Contact List
+
+Each contact is displayed as a list tile showing:
+
+- **Avatar**: Color-coded circle with type icon (or first emoji of the contact's name if it starts with one)
+- **Name**: Contact name (single line)
+- **Path label**: "Direct", "N hops", or "Flood" (with forced variants if a path override is active)
+- **Public key**: Shortened hex format `<XXXXXXXX...XXXXXXXX>`
+- **Unread badge**: Red pill with count (if unread messages exist)
+- **Last seen**: Relative timestamp ("Now", "5 mins ago", "2 hours ago", "3 days ago"). For chat contacts, this shows whichever is more recent: the last advertisement time or the last message time
+- **Favorite star**: Amber star icon if favorited
+- **Location pin**: Grey pin icon if the contact has GPS coordinates
+
+Pull-to-refresh re-fetches the full contact list from the device.
+
+## Search and Filter
+
+A toolbar at the top provides:
+
+**Search**: Matches contact name (case-insensitive) or public key hex prefix. Debounced at 300ms.
+
+**Sort options**:
+- Latest Messages (by most recent message)
+- Heard Recently (by last seen / last message)
+- A–Z (alphabetical)
+
+**Filter options**:
+- All, Favorites, Users, Repeaters, Room Servers, Unread Only
+
+## Contact Groups
+
+Groups are a client-side organizational feature for grouping contacts.
+
+- **Create a group**: Tap the group dropdown → "+" icon → enter name → select members → Save
+- **Edit a group**: Group dropdown → pencil icon next to the group
+- **Delete a group**: Group dropdown → trash icon next to the group
+- **Filter by group**: Select a group from the dropdown to show only its members
+
+Groups are stored per radio identity (scoped by public key).
+
+**Validation rules**: Group names cannot be empty, cannot be "all" (reserved, case-insensitive), and must be unique (case-insensitive). The group creation dialog includes a built-in search field to filter contacts when selecting members. Creating a new group automatically selects it as the active filter.
+
+## Tap Actions
+
+| Contact Type | Action on Tap |
+|---|---|
+| Chat / Sensor | Opens ChatScreen for direct messaging |
+| Repeater | Shows password login dialog → opens RepeaterHubScreen |
+| Room | Shows password login dialog → opens ChatScreen for room chat |
+
+## Long-Press / Right-Click Menu
+
+| Action | Availability | Description |
+|---|---|---|
+| Path Trace / Ping | Repeaters, Rooms (always); Chat if `pathLength > 0` | Opens PathTraceMapScreen. Label shows "Ping" when no path bytes are known, "Path Trace" otherwise |
+| Manage Repeater | Repeaters only | Login dialog → RepeaterHubScreen |
+| Room Login | Rooms only | Login dialog → ChatScreen |
+| Room Management | Rooms only | Login dialog → RepeaterHubScreen (management mode) |
+| Open Chat | Chat/Sensor | Same as single tap |
+| Add/Remove Favorite | All types | Toggles the favorite flag |
+| Share Contact | All types | Copies `meshcore://<hex>` URI to clipboard |
+| Share Contact Zero-Hop | All types | Broadcasts the contact's advertisement one hop |
+| Delete Contact | All types | Confirmation dialog → removes from device and clears messages |
+
+## App Bar Menus
+
+The Contacts screen has **two separate popup menus** in the app bar:
+
+**Antenna icon menu** (contact sharing):
+- Zero-Hop Advert — broadcasts your advertisement to immediately adjacent nodes
+- Flood Advert — broadcasts across the full mesh network
+- Copy Advert to Clipboard — copies your `meshcore://<hex>` URI for sharing externally
+- Add Contact from Clipboard — reads a `meshcore://<hex>` URI from clipboard and imports it
+
+**Three-dot overflow menu**:
+- Disconnect — disconnects from the device
+- Discovered Contacts — opens the DiscoveryScreen
+- Settings — opens the Settings screen
+
+## Adding Contacts
+
+### Automatic (Passive)
+When the radio hears an advertisement, the contact appears automatically if auto-add is enabled for that type (configurable in Settings → Contact Settings).
+
+### Import from Clipboard
+Antenna menu → "Add Contact from Clipboard". Reads a `meshcore://<hex>` URI from clipboard and imports it to the device.
+
+### Import from Discovered Contacts
+Overflow menu → "Discovered Contacts". Shows nodes heard passively that haven't been added yet. Tap to immediately import (no confirmation dialog), or long-press for more options (Add, Copy URI, Delete). The Discovery screen has its own search bar, type filters (Users, Repeaters, Rooms, Favorites), and sort options (Last Seen, A-Z). An overflow "Delete All" option clears all discovered contacts.
+
+## Contact Sharing Format
+
+Contacts are shared using the `meshcore://` URI scheme:
+```
+meshcore://<hex-encoded-advertisement-packet>
+```
+This contains the node's public key and metadata. Paste it into another MeshCore app to import.
diff --git a/documentation/map-and-location.md b/documentation/map-and-location.md
new file mode 100644
index 0000000..f293abe
--- /dev/null
+++ b/documentation/map-and-location.md
@@ -0,0 +1,186 @@
+# Map & Location
+
+## Overview
+
+The Map feature is a full-featured node-location visualization and radio-planning tool built on OpenStreetMap tiles. It is one of the three primary views accessible from the QuickSwitchBar.
+
+## How to Access
+
+- **QuickSwitchBar tab 2** (rightmost) from Contacts or Channels
+- **Deep-link from a chat message**: Tapping a shared location pin in a chat opens the map centered on that pin
+- **Settings → Offline Map Cache**: Opens the tile cache management screen
+
+## What the Map Displays
+
+### Self Location (Teal Circle)
+Your own node's position, obtained from the device firmware. Displayed as a teal `person_pin_circle` icon. Only appears if the device has GPS data or a manually-set location.
+
+### Contact / Node Markers (Color-Coded)
+All contacts with known GPS coordinates are plotted:
+
+| Type | Color | Icon |
+|---|---|---|
+| Chat user | Blue | Person |
+| Repeater | Green | Router |
+| Room | Purple | Meeting room |
+| Sensor | Orange | Sensors |
+
+Node name labels appear automatically at zoom level 12 and above.
+
+### Shared Map Pins (Flag Icons)
+Location pins shared in chat messages are displayed as flags:
+- **Blue flag**: From a direct message
+- **Purple flag**: From a private channel
+- **Orange flag**: From a public channel
+
+Tap a pin to see its info. Options to "Hide" (session only) or "Remove" (persistent).
+
+### Predicted / Guessed Locations (Semi-Transparent)
+
+Many contacts on the mesh don't have GPS hardware, so the map has no explicit coordinates for them. Instead of leaving these contacts invisible, the app **infers an approximate position** by analyzing the repeater path the contact's messages travel through. These inferred positions are displayed as semi-transparent markers with a `not_listed_location` icon, visually distinct from confirmed-location markers.
+
+#### Why guessed locations exist
+
+In a mesh network, every message hops through one or more repeaters on its way to the destination. Each repeater in the path is identified by the first byte of its public key. If any of those repeaters have a known GPS location (because they advertise it), then a contact that routes through those repeaters must be somewhere within radio range of them. By combining the positions of multiple repeaters a contact is known to use, the app can triangulate a rough area where the contact is likely located.
+
+#### How the algorithm works
+
+1. **Build a repeater index**: The app collects all known contacts of type Repeater that have a valid GPS position and indexes them by the first byte of their public key.
+
+2. **Collect anchor points**: For each contact that lacks GPS, the app looks at the **last-hop byte** of the contact's current path and also searches the `PathHistoryService` for recent paths. Each last-hop byte that matches a located repeater becomes an "anchor point" — a GPS coordinate the contact is likely near.
+
+3. **Resolve ambiguity**: If multiple repeaters share the same first public-key byte (a hash collision), that byte is discarded as ambiguous. Only unambiguous one-to-one matches are kept.
+
+4. **Filter geometric inconsistencies**: Two anchor points separated by more than `2 × maxRangeKm` (the estimated LoRa radio range, computed from the current frequency, bandwidth, spreading factor, and TX power using a free-space path loss model) cannot both be in range of the same node. Outlier anchors are removed to keep only a geometrically consistent set.
+
+5. **Compute the estimated position**:
+   - **Single anchor**: The contact is placed on a small circle (330m radius) around the repeater. The angle on the circle is deterministic — derived from an FNV-1a hash of the contact's public key — so the same contact always appears at the same offset, preventing markers from stacking on top of each other.
+   - **Two or more anchors**: The position is the average (centroid) of all anchor coordinates, with a smaller offset radius (80–120m) applied for visual separation.
+
+6. **Assign confidence level**:
+   - **High confidence** (2+ anchors): Displayed at 55% opacity.
+   - **Low confidence** (1 anchor): Displayed at 30% opacity.
+
+7. **Cache the result**: The computation is cached using a key derived from the contact's paths, anchor positions, path-history version, and radio parameters. The cache is only invalidated when any of these inputs change, avoiding recomputation on every UI rebuild.
+
+#### How to read guessed locations on the map
+
+- **Semi-transparent marker** with a `not_listed_location` icon: This is a guessed position, not a confirmed GPS fix.
+- **More opaque** (55%): Higher confidence — the contact was seen through 2 or more repeaters with known positions.
+- **More transparent** (30%): Lower confidence — based on a single repeater anchor only.
+- Coordinates shown in the marker info dialog are prefixed with `~` to indicate they are estimated.
+- Guessed locations can be toggled on/off in the map filter dialog (FAB → "Guessed locations" toggle).
+
+## Map Interactions
+
+### Zoom and Pan
+Standard pinch-to-zoom (range 2–18). Initial camera position is calculated from the statistical spread of all plotted points.
+
+### Tap on a Node Marker
+Opens a dialog showing: type, path (hop chain), coordinates, last-seen time, and public key. Action buttons vary by type:
+- **Chat nodes**: "Open Chat"
+- **Repeaters**: "Manage Repeater"
+- **Rooms**: "Join Room"
+
+### Long-Press on Empty Map Area
+Shows a bottom sheet with:
+- **Share marker here**: Prompts for a label, then pick a DM contact or channel to send the location to. Wire format: `m:<lat>,<lon>|<label>|poi`
+- **Set as my location**: Updates your device's advertised location
+
+### Filter Dialog (FAB)
+Toggle visibility of: chat nodes, repeaters, other nodes, guessed locations, discovery contacts.
+Additional filters:
+- **Key prefix filter**: Show only contacts whose public key starts with a given prefix
+- **Last-seen time slider**: From 1 hour to "all time"
+
+### Legend Card (Top-Right)
+Shows node count and pin count. Tappable to expand a legend of all marker types.
+
+---
+
+## Path Trace Map
+
+### How to Access
+- From the main map's radar icon
+- From a contact's long-press menu → "Path Trace / Ping"
+- From a message's path view → radar icon
+
+### What the User Sees
+A map with a polyline showing the route from your node through repeater hops to the target:
+- **Green circles**: Hops with known GPS coordinates
+- **Orange circles** (`~HH`): Inferred positions (no GPS but deducible from contacts)
+- **Red endpoint**: Target contact with known GPS
+- **Purple semi-transparent endpoint**: Target with guessed position
+
+A legend card at the bottom lists each hop pair with SNR quality icons and total path distance.
+
+### How It Works
+Sends a trace request frame over the mesh. The repeater network traces the path hop-by-hop and returns per-hop SNR data. For hops without GPS, positions are inferred by averaging GPS coordinates of contacts sharing that last-hop byte.
+
+---
+
+## Line-of-Sight (LOS) Analysis
+
+### How to Access
+From the main map, tap the terrain/antenna icon.
+
+### What the User Sees
+A full-screen map with a collapsible control panel containing:
+- **Elevation profile chart**: Terrain fill (green), LOS beam line (white), radio horizon line (yellow)
+- **Status**: Clear (green) or blocked (red) with distance and minimum clearance
+- **Options panel**: Node toggles, endpoint dropdowns, antenna height sliders (0–400 ft), Run LOS button
+
+### Key Interactions
+- **Long-press the map** to add custom endpoints (orange pushpin markers, renameable/deleteable)
+- **Tap a marker** to select it as Point A or B; LOS runs automatically when both are set
+- **Antenna heights** are adjustable for both endpoints
+- **Map line** between endpoints is colored green (clear) or red (blocked)
+- Terrain elevation is fetched from the Open-Meteo API (21–81 sample points, cached 24 hours)
+- K-factor is adjusted per radio frequency from a baseline of 4/3 at 915 MHz
+
+---
+
+## Offline Map Cache
+
+### How to Access
+Settings → App Settings → Map Display → Offline Map Cache
+
+### What the User Sees
+- Map with a blue polygon overlay showing previously selected cache bounds
+- Bounding box coordinates card
+- **Cache Area** controls: "Use Current View" and Clear buttons
+- **Zoom Range** slider (3–18) with estimated tile count
+- **Download progress** bar (when downloading)
+- **Download Tiles** and **Clear Cache** buttons
+
+### Key Interactions
+1. Pan/zoom the map to the desired area
+2. Tap "Use Current View" to capture the viewport as cache bounds
+3. Adjust the zoom range slider
+4. Tap "Download Tiles" (confirmation dialog shows estimated count)
+5. Tiles are downloaded with up to 8 concurrent connections
+6. Once cached, tiles are served from disk without internet (365-day stale period)
+
+---
+
+## GPX Export
+
+### How to Access
+Settings → Export section
+
+### What It Does
+Exports contacts with GPS coordinates to a `.gpx` file via the OS share sheet. Three export options:
+- **Export Repeaters**: Repeater and Room contacts with locations
+- **Export Contacts**: Chat contacts with locations
+- **Export All**: All contacts with locations
+
+Each waypoint includes: name, lat/lon, type label, and public key hex.
+
+---
+
+## Location Data Sources
+
+The phone's own GPS is **never used**. All location data comes from the mesh:
+
+1. **Device self-location**: Read from firmware device-info response. Set manually in Settings → Location, or updated automatically if the device has a GPS module.
+2. **Remote node locations**: Extracted from advertisement packets received over the mesh. Encoded as integer lat/lon × 1,000,000.
diff --git a/documentation/navigation.md b/documentation/navigation.md
new file mode 100644
index 0000000..9003122
--- /dev/null
+++ b/documentation/navigation.md
@@ -0,0 +1,87 @@
+# Navigation
+
+## App Flow
+
+The app follows this general flow:
+
+```
+Launch → Scanner Screen → [Connect via BLE/USB/TCP] → Contacts Screen
+```
+
+After connecting, the three main screens (Contacts, Channels, Map) are accessible via a persistent bottom navigation bar called the **QuickSwitchBar**.
+
+## Quick Switch Bar
+
+The QuickSwitchBar is a Material 3 `NavigationBar` with a frosted-glass visual treatment (blur backdrop, transparent theme, rounded corners). It appears at the bottom of all three main screens.
+
+| Index | Icon | Label | Screen |
+|---|---|---|---|
+| 0 | People | Contacts | ContactsScreen |
+| 1 | Tag | Channels | ChannelsScreen |
+| 2 | Map | Map | MapScreen |
+
+Tapping a tab replaces the current screen with a subtle fade + slight horizontal nudge transition (220ms forward, 200ms reverse). The back button is suppressed on all three main screens — navigation between them is flat, not stacked. All icons use outline variants (`people_outline`, `tag`, `map_outlined`) following Material 3 conventions.
+
+## Device Screen
+
+The Device Screen is a transitional hub that shows after connection. In practice, the app navigates directly to Contacts after connecting, but the Device Screen is reachable via the QuickSwitchBar.
+
+### What the User Sees
+
+**App Bar**:
+- Left: Battery indicator chip (tappable — toggles between percentage and voltage display). Icon changes based on level: `battery_unknown` when data unavailable, `battery_alert` (orange) at 15% or below, `battery_full` otherwise
+- Left-aligned title (`centerTitle: false`): Two-line layout — small grey "MeshCore" label above the device name in bold
+- Right: Disconnect button (`bluetooth_disabled` crossed-out icon) and Settings button (tune icon)
+
+**Body**:
+- **Connection Card**: Device avatar, device name, device ID, "Connected" chip, and battery chip
+- **Quick Switch** section: The QuickSwitchBar widget for navigating to Contacts/Channels/Map
+
+### Disconnection
+
+- The disconnect button shows a confirmation dialog before disconnecting
+- If the device disconnects unexpectedly, the app automatically navigates back to the Scanner screen (fires after the current frame completes via a post-frame callback)
+- This auto-navigation behavior (`DisconnectNavigationMixin`) is shared across all main screens
+
+## Theme and Locale
+
+- **Theme mode** is user-configurable in App Settings (System / Light / Dark) — not locked to system
+- **Language** can be overridden to one of 15 supported languages, or follow the system locale
+- On web, if a non-Chromium browser is detected, the app shows a `ChromeRequiredScreen` instead of the Scanner (Web Bluetooth requires Chromium)
+
+## Full Navigation Graph
+
+```
+ScannerScreen (root, always on stack)
+  ├─ [BLE connect] → push → ContactsScreen
+  ├─ [TCP FAB] → push → TcpScreen
+  │     └─ [TCP connected] → pushReplacement → ContactsScreen
+  └─ [USB FAB] → push → UsbScreen
+        └─ [USB connected] → pushReplacement → ContactsScreen
+
+ContactsScreen (selected=0)
+  ├─ [quick-switch 1] → pushReplacement → ChannelsScreen
+  ├─ [quick-switch 2] → pushReplacement → MapScreen
+  ├─ [tap contact] → push → ChatScreen
+  ├─ [overflow > Settings] → push → SettingsScreen
+  └─ [overflow > Discovered] → push → DiscoveryScreen
+
+ChannelsScreen (selected=1)
+  ├─ [quick-switch 0] → pushReplacement → ContactsScreen
+  ├─ [quick-switch 2] → pushReplacement → MapScreen
+  ├─ [tap channel] → push → ChannelChatScreen
+  └─ [overflow > Settings] → push → SettingsScreen
+
+MapScreen (selected=2)
+  ├─ [quick-switch 0] → pushReplacement → ContactsScreen
+  ├─ [quick-switch 1] → pushReplacement → ChannelsScreen
+  ├─ [radar button] → push → PathTraceMapScreen
+  ├─ [terrain button] → push → LineOfSightMapScreen
+  └─ [long-press] → share marker / set location
+
+Settings (push from any main screen)
+  └─ [App Settings] → push → AppSettingsScreen
+        └─ [Offline Map Cache] → push → MapCacheScreen
+```
+
+Any disconnection from any screen triggers `popUntil(route.isFirst)`, returning to the Scanner.
diff --git a/documentation/notifications.md b/documentation/notifications.md
new file mode 100644
index 0000000..0eb2574
--- /dev/null
+++ b/documentation/notifications.md
@@ -0,0 +1,92 @@
+# Notifications
+
+## Overview
+
+MeshCore Open provides both **system notifications** (push-style OS alerts) and **in-app unread badges** to inform users of new activity.
+
+## Notification Types
+
+### 1. Direct Message Notifications
+- **Triggered when**: A new incoming message arrives from a Chat or Room contact
+- **Title**: Contact's name
+- **Body**: Message text (reactions show "Reacted [emoji]", GIFs show "Sent a GIF")
+- **Priority**: High
+- **Android channel**: `messages`
+
+### 2. Channel Message Notifications
+- **Triggered when**: A new message arrives on a non-muted channel
+- **Title**: Channel name (or "Channel N" if unnamed)
+- **Body**: `"<senderName>: <message text>"`
+- **Priority**: High
+- **Android channel**: `channel_messages`
+
+### 3. Advertisement Notifications
+- **Triggered when**: A new node is discovered on the mesh for the first time
+- **Title**: "New [type] discovered" (e.g., "New chat node discovered")
+- **Body**: Contact's name
+- **Priority**: Default
+- **Android channel**: `adverts`
+
+### 4. Background Service Notification (Android Only)
+- A persistent low-priority notification: "MeshCore running — Keeping BLE connected"
+- Required by Android for foreground services to keep BLE alive in the background
+- Tap to re-launch the app
+- **Does not auto-start on reboot** — the user must re-open the app manually after a phone restart
+
+### Notification Tap Behavior
+
+Tapping a notification currently re-launches the app at the root route. It does **not** navigate directly to the relevant chat or channel.
+
+## In-App Unread Badges
+
+Red numeric badges appear throughout the UI:
+- **Contacts list**: Each contact row shows a red pill badge (e.g., "3") for unread messages
+- **Channels list**: Each channel row shows an unread badge
+- **Chat screen subtitle**: Shows unread count inline
+- Badges cap at "99+" for display
+
+### How Unread Counts Work
+
+- Stored per contact (by public key) and per channel, **scoped to the connected device's identity** (first 10 hex characters of its public key). Switching between different radios gives each its own independent unread state
+- **Suppressed when viewing**: Opening a chat resets the count to 0 and cancels the OS notification
+- **Ignored for**: Outgoing messages, CLI messages, and repeater contacts
+- Debounced writes (500ms) to avoid excessive storage I/O during message bursts
+
+## Notification Settings
+
+Access via **App Settings → Notifications**:
+
+| Setting | Default | Description |
+|---|---|---|
+| Enable Notifications | On | Master toggle; requests OS permission when turned on |
+| Message Notifications | On | DM alerts (greyed out if master is off) |
+| Channel Message Notifications | On | Channel alerts (greyed out if master is off) |
+| Advertisement Notifications | On | New node alerts (greyed out if master is off) |
+
+### Per-Channel Muting
+
+Long-press a channel in the channels list → "Mute channel" / "Unmute channel". Muted channels do not generate OS notifications.
+
+There is no per-contact muting.
+
+## Rate Limiting
+
+The notification system prevents notification storms:
+- **Minimum interval**: 3 seconds between individual notifications
+- **Batch window**: If multiple notifications arrive within 5 seconds, they are combined into a single summary notification on a fourth Android channel (`batch_summary`): "MeshCore Activity — 2 messages, 1 channel message, 3 new nodes". Note: batch summaries are Android-only; on Apple platforms individual notifications are shown
+
+## Notification Clearing
+
+- **Opening a contact chat**: Cancels the OS notification and resets unread count
+- **Opening a channel**: Cancels the channel notification and resets unread count
+- **Opening Contacts screen**: Cancels all advertisement notifications
+
+## Platform Support
+
+| Platform | Message Notifs | Badge | Background Service |
+|---|---|---|---|
+| Android | Yes | Via notification number | Yes (foreground service) |
+| iOS | Yes | Yes (app badge) | No |
+| macOS | Yes | Yes | No |
+| Windows | Yes | No | No |
+| Linux | Yes (if D-Bus available) | No | No |
diff --git a/documentation/repeater-management.md b/documentation/repeater-management.md
new file mode 100644
index 0000000..be5015f
--- /dev/null
+++ b/documentation/repeater-management.md
@@ -0,0 +1,186 @@
+# Repeater Management
+
+## Overview
+
+Repeater Management provides tools for administering MeshCore repeater and room server nodes. It includes device status monitoring, CLI access, telemetry reading, neighbor discovery, and remote configuration.
+
+## How to Access
+
+From the Contacts screen:
+1. Long-press a **Repeater** or **Room** contact
+2. Select "Manage Repeater" or "Room Management"
+3. Enter the admin password in the login dialog
+4. Navigate to the Repeater Hub Screen
+
+### Login Dialog
+
+- Password field with show/hide toggle
+- "Save password" checkbox (persists for future logins). If a saved password exists, it is pre-filled and the checkbox is pre-checked, making login one-tap
+- Routing mode selector and "Manage Paths" link are available directly in the dialog (configure routing before login)
+- Auto-retries up to 5 times on timeout, showing progress ("Attempt 2 of 5"). A wrong password stops immediately after the first attempt — only timeouts trigger retries
+- After 5 failed attempts, further login attempts are blocked
+
+---
+
+## Repeater Hub Screen
+
+The central management screen showing:
+
+- **Header card**: Repeater name, short public key, path label, GPS coordinates (if known)
+- **Battery chemistry selector**: NMC / LiFePO4 / LiPo (saved per repeater)
+- **Management tool cards** (full-width cards with chevron arrows, not a grid). Title dynamically shows "Repeater Management" or "Room Management" based on contact type:
+
+| Card | Destination |
+|---|---|
+| Status | Repeater Status Screen |
+| Telemetry | Telemetry Screen |
+| CLI | Repeater CLI Screen |
+| Neighbors | Neighbors Screen |
+| Settings | Repeater Settings Screen |
+
+---
+
+## Repeater Status
+
+### What the User Sees
+
+Three information cards:
+
+**System Information**:
+- Battery percentage
+- Uptime
+- Queue length
+- Error flags
+- Clock at login time
+
+**Radio Statistics**:
+- Last RSSI and SNR
+- Noise floor
+- TX and RX airtime
+
+**Packet Statistics**:
+- Packets sent, received, and duplicates
+- Broken down by flood vs. direct
+
+### Key Interactions
+- Auto-queries the repeater on open; shows a loading spinner until data arrives
+- On timeout: red snackbar error. On success: data appears with a green snackbar confirmation
+- Pull-to-refresh or refresh button to re-query
+- Routing mode popup and path management dialog in app bar (these controls appear on **all** management sub-screens, not just Status)
+
+---
+
+## Repeater CLI
+
+A terminal-style interface for sending commands directly to the repeater.
+
+### What the User Sees
+
+- **Quick-command bar** (horizontal scroll): Shortcut buttons for common commands (get name, get radio, get tx, neighbors, ver, advert, clock)
+- **Command history list**: Sent commands in primary color, responses in secondary color
+- **Input bar**: Up/down history arrows, monospace text field with `> ` prefix, send button
+
+### Key Interactions
+
+- Type a command and press send (or Enter on desktop)
+- Up/down arrows navigate through command history
+- Quick-command buttons populate and send common commands
+- Bug report icon: Shows raw frame debug info for the next typed command (shows error snackbar if input field is empty)
+- Help icon: Opens a scrollable reference of all known CLI commands. Tapping any command populates the input field immediately
+- Clear icon: Wipes the command/response history
+- Failed/timed-out commands are automatically retried once
+
+### Available CLI Commands
+
+**General**: `advert`, `reboot`, `clock`, `password`, `ver`, `clear stats`
+
+**Settings**: `set name`, `set af`, `set tx`, `set repeat`, `set allow.read.only`, `set flood.max`, `set int.thresh`, `set agc.reset.interval`, `set multi.acks`, `set advert.interval`, `set flood.advert.interval`, `set guest.password`, `set lat`, `set lon`, `set radio`, `set rxdelay`, `set txdelay`, `set direct.txdelay`, `set bridge.*`, `set adc.multiplier`, `tempradio`, `setperm`
+
+**Bridge**: `get bridge.type`
+
+**Logging**: `log start`, `log stop`, `log erase`
+
+**Neighbors**: `neighbors`, `neighbor.remove`
+
+**Region Management**: `region`, `region load/get/put/remove/allowf/denyf/home/save`
+
+**GPS**: `gps`, `gps on/off/sync/setloc/advert`
+
+---
+
+## Telemetry
+
+### What the User Sees
+
+A list of Cayenne LPP sensor channel cards:
+
+- **Channel 1** (special): Battery voltage (shown as percentage or raw mV) and MCU temperature
+- **Other channels**: Raw sensor values with appropriate labels
+
+Shows "No data" until a response arrives from the repeater.
+
+### Key Interactions
+- Auto-queries on open
+- Pull-to-refresh
+- Temperature respects metric/imperial setting
+- Battery readings are stored for the repeater's battery snapshot
+
+---
+
+## Neighbors
+
+### What the User Sees
+
+A card titled "Repeater's Neighbors - N" listing each neighbor as:
+- Repeater name (or hex key prefix if unknown)
+- Time since last heard
+- SNR quality icon with color coding and label
+
+### Key Interactions
+- Auto-queries up to 15 neighbors on open
+- Matches public key prefixes against known contacts to show names
+- Pull-to-refresh
+
+---
+
+## Repeater Settings
+
+### What the User Sees
+
+Five configuration cards:
+
+**1. Basic Settings**
+- Name field
+- Admin password field
+- Guest password field
+
+**2. Radio Settings**
+- Frequency (MHz)
+- TX Power (dBm)
+- Bandwidth dropdown (kHz)
+- Spreading Factor (SF5–SF12)
+- Coding Rate (4/5–4/8)
+
+**3. Location Settings**
+- Latitude and longitude fields
+
+**4. Features**
+- Packet forwarding toggle
+- Guest access toggle
+
+**5. Advertisement Settings**
+- Local advert interval slider (60–240 minutes) with enable/disable toggle
+- Flood advert interval slider (3–168 hours) with enable/disable toggle
+
+**6. Danger Zone** (red-styled card)
+- Reboot repeater
+- Erase filesystem (serial-only warning)
+
+### Key Interactions
+- **Settings are NOT auto-fetched on open**. Only name and location are pre-filled from locally cached contact data. You must tap each section's refresh button to fetch live values from the repeater
+- TX Power has its own separate refresh button, independent from the main Radio Settings refresh
+- Save button appears when changes are detected
+- Settings are sent sequentially with 200ms delays between commands (fire-and-forget, no per-command acknowledgment wait)
+- Validation prevents invalid values (e.g., frequency range, LoRa parameter compatibility)
+- Advertisement interval sliders reset to defaults when re-enabled (local: 60 min, flood: 3 hours)
+- **Erase Filesystem** does NOT send any command over the air — tapping it only shows a snackbar explaining the operation requires physical serial access. It is effectively non-functional when connected wirelessly
diff --git a/documentation/scanner-and-connection.md b/documentation/scanner-and-connection.md
new file mode 100644
index 0000000..2c5dbae
--- /dev/null
+++ b/documentation/scanner-and-connection.md
@@ -0,0 +1,124 @@
+# Scanner & Connection
+
+## BLE Scanner (Home Screen)
+
+The BLE Scanner is the app's home screen, displayed immediately on launch.
+
+### How to Access
+
+- Opens automatically when the app starts
+- Returns here when disconnecting from any device
+- Accessible by navigating back from a connected session
+
+### What the User Sees
+
+**App Bar**: Centered title "Scanner".
+
+**Bluetooth-Off Warning Banner** (conditional): Appears when the Bluetooth adapter is off, showing a `bluetooth_disabled` icon, a warning message, and on Android, an "Enable Bluetooth" button.
+
+**Status Bar**: A full-width colored strip reflecting the current connection state:
+
+| State | Text | Color |
+|---|---|---|
+| Disconnected | "Not connected" | Grey |
+| Scanning | "Scanning..." | Blue |
+| Connecting | "Connecting..." | Orange |
+| Connected | "Connected to \<device name\>" | Green |
+| Disconnecting | "Disconnecting..." | Orange |
+
+**Device List**: When no devices are found, shows a large Bluetooth icon with a prompt. The prompt text is dynamic: "Searching for devices..." while actively scanning, or "Tap Scan to search" when idle. When devices are found, shows a scrollable list of `DeviceTile` widgets.
+
+**Bottom FAB Row**: Up to three floating action buttons:
+- **USB** button - Opens USB connection screen (Android, Windows, Linux, macOS, Chrome web only)
+- **TCP/IP** button - Opens TCP connection screen (all non-web platforms)
+- **BLE Scan** button - Toggles BLE scanning on/off; shows a spinner when scanning. **Disabled** (greyed out, not tappable) when Bluetooth is off
+
+### Device Tile
+
+Each discovered device is displayed as a list tile showing:
+- **Signal strength icon** (color-coded by RSSI):
+  - Green: >= -60 dBm (excellent)
+  - Light green: -60 to -70 dBm (good)
+  - Amber: -70 to -80 dBm (fair)
+  - Orange: -80 to -90 dBm (weak)
+  - Red: < -90 dBm (poor)
+- **RSSI value** in dBm (e.g., "-72 dBm")
+- **Device name** (falls back to "Unknown Device")
+- **Device ID** (BLE MAC address on Android; a system-assigned UUID on iOS/macOS)
+- **Connect button** (the entire tile row is also tappable — both trigger connection)
+
+Note: The weak (-80 to -90 dBm) and poor (< -90 dBm) tiers share the same icon shape and are only differentiated by color (orange vs. red).
+
+### How Scanning Works
+
+- Filters for devices with names starting with `MeshCore-` or `Whisper-`
+- Uses low-latency scan mode on Android
+- Scans for 10 seconds then auto-stops
+- On iOS/macOS, waits for BLE adapter initialization before starting
+- If Bluetooth is turned off during a scan, scanning stops immediately
+
+### Connecting to a Device
+
+Tap a device tile or its Connect button:
+1. The connector stops scanning and transitions to "connecting"
+2. Connects to the device with a 15-second timeout
+3. Requests MTU 185 bytes for optimal throughput
+4. Discovers BLE services and locates the Nordic UART Service
+5. Subscribes to TX notifications for receiving data
+6. On success, automatically navigates to the Contacts screen
+7. On failure, shows a red error snackbar
+
+---
+
+## USB Connection
+
+### How to Access
+
+From the Scanner screen, tap the **USB** FAB button.
+
+### What the User Sees
+
+- A colored status bar at the top (same color scheme as BLE scanner)
+- A list of detected USB serial ports, each showing:
+  - Friendly display name
+  - Raw port name (subtitle, only shown when it differs from the display name)
+  - "Connect" button
+- FABs at the bottom to switch to BLE or TCP (these use `pushReplacement`, so back navigation returns to Scanner, not between USB/TCP)
+
+### Key Interactions
+
+- On desktop (Windows, Linux, macOS): ports are polled every 2 seconds for hot-plug detection (polling pauses while connecting/connected)
+- On mobile: tap the "Scan" FAB to manually refresh
+- Tap a port or its Connect button to connect
+- On successful connection, navigates to Contacts screen
+- On connection failure, the port list automatically refreshes
+- Platform-specific error messages for common USB failures (permission denied, device missing, device detached, device busy, driver missing, port invalid, timeout, and more)
+
+---
+
+## TCP Connection
+
+### How to Access
+
+From the Scanner screen, tap the **TCP/IP** FAB button.
+
+### What the User Sees
+
+- A colored status bar at the top
+- **Host address** text field
+- **Port number** text field
+- **Connect** button
+- FABs at the bottom to switch to USB or BLE
+
+### Key Interactions
+
+- Last-used host and port are pre-populated from saved settings
+- Tap Connect to validate inputs and connect
+  - Host must not be empty
+  - Port must be a number between 1 and 65535
+  - Validation errors are shown as red snackbars
+- The Connect button shows a spinner and "Connecting..." label while in progress
+- The status bar shows the specific host:port being connected to (e.g., "Connecting to 192.168.1.1:5000")
+- On success, navigates to Contacts screen and saves the host/port to settings
+- On connection, the status bar shows the active TCP endpoint (e.g., "Connected to 192.168.1.1:5000")
+- Error messages for timeout, unsupported platform, and connection failures
diff --git a/documentation/settings.md b/documentation/settings.md
new file mode 100644
index 0000000..70e39e2
--- /dev/null
+++ b/documentation/settings.md
@@ -0,0 +1,169 @@
+# Settings
+
+## How to Access
+
+- From the Device Screen: tap the tune/sliders icon in the app bar
+- From Contacts or Channels: overflow menu (three-dot) → Settings
+
+Settings are only accessible while a device is connected.
+
+## Settings Screen Layout
+
+The settings screen is a scrollable list of cards:
+
+1. [Device Info](#device-info)
+2. [App Settings](#app-settings) (link to sub-screen)
+3. [Node Settings](#node-settings)
+4. [Actions](#actions)
+5. [Debug](#debug)
+6. [Export](#export)
+7. [About](#about)
+
+---
+
+## Device Info
+
+A collapsible card showing read-only device information. **Collapsed by default** — tap the header to expand with an animated chevron indicator:
+
+| Field | Description |
+|---|---|
+| Name | Connected device's display name |
+| ID | Device identifier |
+| Status | Connected / Disconnected |
+| Battery | Percentage or voltage (tap to toggle) |
+| Node Name | The node's mesh identity name |
+| Public Key | First 16 hex characters + "..." |
+| Contacts Count | Number of known contacts |
+| Channel Count | Number of configured channels |
+
+Battery shows an alert icon and orange text when at 15% or below. The toggle only works when millivolt data is available from the firmware.
+
+---
+
+## App Settings
+
+A dedicated sub-screen for app-level preferences (nothing here is sent to the device). All settings persist locally via SharedPreferences.
+
+### Appearance
+- **Theme**: System / Light / Dark
+- **Language**: System default or one of 15 languages (English, French, Spanish, German, Polish, Slovenian, Portuguese, Italian, Chinese, Swedish, Dutch, Slovak, Bulgarian, Russian, Ukrainian)
+- **Enable Message Tracing**: Shows path trace overlays and extra metadata on messages
+
+### Notifications
+- **Master enable/disable**: Requests OS permission when enabling
+- **Message notifications**: New direct message alerts
+- **Channel message notifications**: New channel message alerts
+- **Advertisement notifications**: New node discovery alerts
+
+### Messaging
+- **Clear Path on Max Retry**: Erases the stored routing path after all retries fail
+- **Auto Route Rotation**: Enables weighted routing algorithm. When enabled, expands to show five slider sub-settings (hidden when off):
+  - Max Route Weight (1–10, default 5, integer steps)
+  - Initial Route Weight (0.5–5.0, default 3.0)
+  - Success Increment (0.1–2.0, default 0.5, 0.1 steps)
+  - Failure Decrement (0.1–2.0, default 0.2, 0.1 steps)
+  - Max Message Retries (2–10, default 5)
+
+### Battery
+- **Battery Chemistry**: NMC / LiFePO4 / LiPo (per device, used to calibrate percentage from voltage)
+
+### Map Display
+- **Show Repeaters**: Toggle repeater markers on map
+- **Show Chat Nodes**: Toggle chat node markers
+- **Show Other Nodes**: Toggle room/sensor markers
+- **Time Filter**: All time / Last 1h / Last 6h / Last 24h / Last week
+- **Units**: Metric / Imperial
+- **Offline Map Cache**: Navigate to tile download screen
+
+### Debug
+- **App Debug Logging**: Enable the in-app debug log
+
+---
+
+## Node Settings
+
+These settings are sent directly to the connected device firmware.
+
+### Node Name
+- Opens a dialog with a text field (max 31 characters)
+- Sends the new name to the device
+- Confirmed via snackbar
+
+### Radio Settings
+Opens a dialog pre-populated with the device's current radio settings. Contains:
+- **Preset dropdown**: 19 regional presets — selecting a preset immediately fills all fields below. Full list: Australia, Australia (Narrow), Australia SA/WA/QLD, Czech Republic, EU 433MHz, EU/UK (Long Range), EU/UK (Medium Range), EU/UK (Narrow), New Zealand, New Zealand (Narrow), Portugal 433, Portugal 869, Switzerland, USA Arizona, USA/Canada, Vietnam, Off-Grid 433, Off-Grid 869, Off-Grid 918
+- **Frequency** (MHz): Free text, validated 300–2500 MHz
+- **Bandwidth**: Dropdown (7.8 / 10.4 / 15.6 / 20.8 / 31.25 / 41.7 / 62.5 / 125 / 250 / 500 kHz)
+- **Spreading Factor**: SF5–SF12
+- **Coding Rate**: 4/5, 4/6, 4/7, 4/8
+- **TX Power** (dBm): Validated 0 to device max (typically 22 dBm)
+- **Client Repeat** toggle: Only shown on firmware v9+; requires frequency to be exactly 433.000, 869.000, or 918.000 MHz (the Off-Grid presets). Save is blocked with a warning if enabled on other frequencies
+
+### Location
+Opens a dialog pre-populated with the device's current coordinates (if known):
+- Latitude and longitude fields (decimal, 6 decimal places). If only one field is provided, the other uses the device's current value
+- If GPS-capable hardware (detected via `gps` custom variable):
+  - GPS Update Interval (seconds, 60–86399, default 900 = 15 minutes). Validated and sent separately before lat/lon
+  - Enable GPS toggle (takes effect immediately, not deferred to Save)
+- Validation: lat ±90, lon ±180
+
+### Contact Settings
+Five toggles controlling which node types are auto-added when heard:
+- Auto-add Chat Users
+- Auto-add Repeaters
+- Auto-add Room Servers
+- Auto-add Sensors
+- Overwrite Oldest (when contact list is full)
+
+### Privacy Mode
+Opens a confirmation dialog with three buttons: Cancel, Enable, and Disable. Both states can be set from the same dialog regardless of current state. A snackbar confirms which state was applied. When on, the node stops broadcasting its location in advertisements.
+
+---
+
+## Actions
+
+One-tap device operations:
+
+| Action | Description |
+|---|---|
+| Send Advertisement | Floods the mesh with your node's advertisement |
+| Sync Time | Sends current Unix timestamp to the device |
+| Refresh Contacts | Re-requests the full contact list |
+| Reboot Device | Confirmation dialog → reboots the device (shown in orange) |
+
+---
+
+## Debug
+
+Two log viewers accessible via list tiles:
+
+### BLE Debug Log
+Two views (togglable via segmented button):
+- **Frames view**: Direction icon, description, hex preview, timestamp per frame. Long-press to copy hex.
+- **Raw Log RX view**: Decoded LoRa packets with route type, payload type, path, and summary.
+- Copy-all and Clear buttons in the app bar.
+
+### App Debug Log
+Structured log entries (Info / Warning / Error), with tag, message, and timestamp.
+- Must be enabled first in App Settings → Debug
+- Copy-all and Clear buttons
+
+---
+
+## Export
+
+Three GPX export options (not available on web):
+
+| Option | Exports |
+|---|---|
+| Export Repeaters | Repeaters and Rooms with GPS coordinates |
+| Export Contacts | Chat contacts with GPS coordinates |
+| Export All | All contacts with GPS coordinates |
+
+Each creates a `.gpx` file and opens the OS share sheet. Feedback via snackbar for four outcomes: success, no contacts with coordinates, feature not available (web), or error.
+
+---
+
+## About
+
+Shows the standard Flutter about dialog with app name, version, and legal notice.