docs: update documentation for BLE transport, DM retry scenarios, and path_hash_mode

Add new docs to README table (DM retry logic, BLE pairing guide), update
architecture diagram and DB schema for BLE/delivery tracking, rewrite DM
retry settings section in user guide to reflect 4-scenario matrix, add BLE
troubleshooting reference, and update .claude/context files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -31,7 +31,7 @@ A lightweight web interface providing browser-based access to MeshCore mesh netw
 - **@Mentions autocomplete** - Type @ to see contact suggestions with fuzzy search
 - **Echo tracking** - "Heard X repeats" with repeater IDs for sent messages, all route paths for incoming messages with deterministic payload matching (persisted across restarts)
 - **MeshCore Analyzer** - View packet details on analyzer.letsmesh.net directly from channel messages
-- **DM delivery tracking** - ACK-based delivery confirmation with SNR and route info
+- **DM delivery tracking** - ACK-based delivery confirmation with SNR, route, and hop count details
 - **Multi-device support** - Database file named after device public key for easy multi-device setups
 - **PWA support** - Browser notifications and installable app (experimental)
 - **Full offline support** - Works without internet (local Bootstrap, icons, emoji picker)
@@ -300,6 +300,8 @@ sudo ~/mc-webui/scripts/updater/install.sh --uninstall
 | [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
 | [Docker Installation](docs/docker-install.md) | How to install Docker on Debian/Ubuntu |
 | [Container Watchdog](docs/watchdog.md) | Auto-restart for unhealthy containers |
+| [DM Delivery & Retry Logic](docs/dm-retry-logic.md) | How DM delivery confirmation and retry strategies work |
+| [Bluetooth Pairing Guide](docs/meshcore_bluetooth_pairing.md) | How to pair MeshCore devices via BLE on Linux |
 
 ---
 

docs/architecture.md

@@ -37,7 +37,7 @@ mc-webui uses a **single-container architecture** for simplified deployment and
 │  │                       mc-webui                        │   │
 │  │                                                       │   │
 │  │  - Flask web app (Port 5000)                          │   │
-│  │  - DeviceManager (Direct USB/TCP access)              │   │
+│  │  - DeviceManager (Direct USB/BLE/TCP access)          │   │
 │  │  - Database (SQLite)                                  │   │
 │  │                                                       │   │
 │  └─────────┬─────────────────────────────────────────────┘   │
@@ -46,11 +46,13 @@ mc-webui uses a **single-container architecture** for simplified deployment and
              │
              ▼
       ┌──────────────┐
-      │  USB/TCP     │
+      │ USB/BLE/TCP  │
-      │  Device      │
+      │    Device    │
       └──────────────┘
 ```
 
+Three transport options are supported with the following priority: **BLE > TCP > Serial (USB)**. Set the `MC_BLE_ADDRESS` or `MC_TCP_HOST` environment variable to activate BLE or TCP transport respectively; otherwise, USB serial is used by default.
+
 This v2 architecture eliminates the need for a separate bridge container and relies on the native `meshcore` Python library for direct communication, ensuring lower latency and greater stability.
 
 ---
@@ -111,9 +113,10 @@ Location: `./data/meshcore/<pubkey_prefix>.db`
 
 Key tables:
 - `messages` - All channel and direct messages (with FTS5 index for full-text search)
-- `contacts` - Contact list with sync status, types, block/ignore flags
+- `contacts` - Contact list with sync status, types, block/ignore flags, `no_auto_flood` flag
 - `channels` - Channel configuration and keys
-- `echoes` - Sent message tracking and repeater paths
+- `echoes` - Sent message tracking and repeater paths, `hash_size` for path_hash_mode
+- `direct_messages` - DM messages with delivery tracking (`delivery_status`, `delivery_attempt`, `delivery_max_attempts`, `delivery_path`)
 - `acks` - DM delivery status
 - `settings` - Application settings (migrated from .webui_settings.json)
 
@@ -198,7 +201,7 @@ The use of SQLite allows for fast queries, reliable data storage, full-text sear
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/status` | Connection status (device name, serial port) |
+| GET | `/api/status` | Connection status (device name, transport type, serial port / BLE address) |
 | GET | `/api/device/info` | Device information |
 | GET | `/api/device/stats` | Device statistics |
 | GET | `/api/device/settings` | Get device settings |
@@ -259,8 +262,12 @@ Real-time message delivery via Socket.IO.
 **Server → Client:**
 - `new_channel_message` - New channel message received
 - `new_dm_message` - New DM received
-- `message_echo` - Echo/ACK update for sent message
+- `message_echo` - Echo/ACK update for sent message (includes `hash_size`)
 - `dm_ack` - DM delivery confirmation
+- `dm_retry_status` - Real-time retry progress (`dm_id`, `attempt`, `max_attempts`)
+- `dm_retry_failed` - All retry attempts exhausted (`dm_id`)
+- `dm_delivered_info` - Delivery details after ACK (`dm_id`, `attempt`, `max_attempts`, `path`, `hash_size`)
+- `path_changed` - Contact path discovered/updated (`public_key`)
 
 ### Logs Namespace (`/logs`)
 

docs/troubleshooting.md

@@ -130,6 +130,16 @@ This can happen after a power failure during OTA update, flash memory corruption
 
 ---
 
+### BLE Connection Issues
+
+If using Bluetooth Low Energy (BLE) transport, see the dedicated [Bluetooth Pairing Guide](meshcore_bluetooth_pairing.md) for setup and troubleshooting, including:
+- Host preparation (BlueZ configuration, `ControllerMode = le`)
+- Pairing with fixed PIN
+- Trusting the device for automatic reconnection
+- Diagnosing connection loops and stale BlueZ connections
+
+---
+
 ### Contact Management Issues
 
 **Check logs:**

docs/user-guide.md

@@ -177,10 +177,15 @@ Access the Direct Messages feature:
 
 ### Message Status Indicators
 
-- ✓ **Delivered** (green checkmark) - Recipient confirmed receipt (ACK). Tap/hover for SNR and route details
+- ✓ **Delivered** (green checkmark) - Recipient confirmed receipt (ACK). Tap/hover for SNR, route, and hop count details
+- ✗ **Failed** (red X) - All retry attempts exhausted with no ACK
 - ? **Unknown** (gray question mark) - No ACK received. Message may still have been delivered — ACK packets are often lost over multi-hop routes. Tap the icon for details
 - ⏳ **Pending** (clock icon, yellow) - Message sent, awaiting delivery confirmation
 
+### Real-time Delivery Progress
+
+While a message is being retried, the UI shows a live counter below the message bubble (e.g., "Attempt 3/11"). When delivery is confirmed, the route used is displayed (e.g., `5E->05->58->D1`) and can be clicked to show a popup with full path details.
+
 ### DM Notifications
 
 - The bell icon shows a secondary green badge for unread DMs
@@ -505,11 +510,21 @@ Access the Settings modal to configure application behavior:
 
 ### DM Retry Settings
 
-Configure how direct messages are retried when delivery is not confirmed:
+Configure how direct messages are retried when delivery is not confirmed. Settings are organized into two groups based on whether the contact has a known route:
-- **Retry count** - Number of retry attempts (includes initial send)
+
-- **Retry interval** - Seconds between retries
+**When path is known:**
-- **Flood fallback attempt** - After which attempt to switch from DIRECT to FLOOD routing
+- **Direct retries** - How many times to resend via the current route before trying alternatives (default: 3)
-- **Grace period** - Seconds to wait for late ACKs after all retries complete
+- **Flood retries** - How many flood attempts after direct retries when no extra paths are configured (default: 1)
+- **Interval (s)** - Minimum seconds between direct retry attempts (default: 30)
+
+**When no path:**
+- **Max retries** - How many flood retry attempts (default: 3)
+- **Interval (s)** - Minimum seconds between flood retry attempts (default: 60)
+
+**Other:**
+- **Grace period (s)** - After all retries fail, keep listening for a late ACK this long before giving up (default: 60)
+
+The app automatically picks one of four retry strategies depending on the contact's route status and configured paths. For full details, see [DM Delivery & Retry Logic](dm-retry-logic.md).
 
 ### Quote Settings
 
@@ -666,6 +681,8 @@ To get the full PWA experience with app badge counters:
 
 - **Full README:** [README.md](../README.md)
 - **Repeater Management:** [rpt-mgmt.md](rpt-mgmt.md)
+- **DM Delivery & Retry Logic:** [dm-retry-logic.md](dm-retry-logic.md)
+- **Bluetooth Pairing Guide:** [meshcore_bluetooth_pairing.md](meshcore_bluetooth_pairing.md)
 - **Troubleshooting:** [troubleshooting.md](troubleshooting.md)
 - **Architecture:** [architecture.md](architecture.md)
 - **Container Watchdog:** [watchdog.md](watchdog.md)