signalk-edge-link 1.0.0 → 2.0.0

package/README.md

@@ -1,538 +1,282 @@
 # Signal K Edge Link
 
-Secure, encrypted UDP data transmission between Signal K servers with advanced bandwidth optimization.
-
-[![Tests](https://img.shields.io/badge/tests-209%20passed-brightgreen)](https://github.com/KEGustafsson/signalk-edge-link)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org/)
-
-![Data Connector Concept](https://raw.githubusercontent.com/KEGustafsson/signalk-edge-link/refs/heads/main/doc/dataconnectorconcept.jpg)
-
-**Create a digital twin of your vessel in the cloud.** Signal K Edge Link sends vessel data from an onboard Signal K server to a remote cloud server using UDP — designed for challenging network conditions where TCP struggles, such as cellular network edge areas with intermittent connectivity. Data is queued and transmitted when the network allows, keeping latency low and bandwidth usage minimal. All traffic is encrypted and outbound-only, requiring no open inbound ports on the vessel. Simple to configure, efficient to run.
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Getting Started](#getting-started)
-  - [Installation](#installation)
-  - [Quick Start](#quick-start)
-- [Configuration](#configuration)
-  - [Server Mode](#server-mode-receiver)
-  - [Client Mode](#client-mode-sender)
-  - [Web Dashboard](#web-dashboard)
-  - [Configuration Files](#configuration-files)
-- [Network Monitoring](#network-monitoring)
-- [Performance](#performance)
-  - [Bandwidth Comparison](#bandwidth-comparison)
-  - [Smart Batching](#smart-batching)
-  - [Optimization Tips](#optimization-tips)
-- [Security](#security)
-  - [Encryption](#encryption)
-  - [Secret Key Requirements](#secret-key-requirements)
-  - [Best Practices](#best-practices)
-- [Troubleshooting](#troubleshooting)
-- [Development](#development)
-  - [Architecture](#architecture)
-  - [Project Structure](#project-structure)
-  - [Build Commands](#build-commands)
-  - [Testing](#testing)
-  - [Technical Reference](#technical-reference)
-  - [Contributing](#contributing)
-- [License](#license)
-
----
-
-## Overview
-
-Signal K Edge Link is a Signal K Node Server plugin that enables real-time data sharing between vessels or shore stations over UDP. It combines AES-256-GCM authenticated encryption with Brotli compression to deliver secure, bandwidth-efficient transmission — achieving up to **97% bandwidth reduction** compared to raw data.
-
-**Key capabilities:**
-
-| Feature | Description |
-|---------|-------------|
-| Encrypted transport | AES-256-GCM authenticated encryption with per-message unique IV |
-| Brotli compression | Quality-10 compression with 85–97% reduction on typical data |
-| Binary protocol | Zero JSON overhead in the wire format |
-| Path dictionary | 170+ Signal K paths mapped to numeric IDs (10–20% savings) |
-| MessagePack | Optional binary serialization (15–25% additional savings) |
-| Smart batching | Adaptive packet sizing that prevents UDP fragmentation |
-| Sentence filtering | Exclude NMEA sentences (GSV, GSA, etc.) to reduce bandwidth |
-| Network monitoring | TCP ping with RTT measurement published to Signal K |
-| Web dashboard | Real-time bandwidth, compression, and path analytics |
-| Hot-reload config | Configuration files reload automatically on change |
-
----
-
-## Getting Started
-
-### Installation
-
-```bash
-cd ~/.signalk/node_modules/
-git clone https://github.com/KEGustafsson/signalk-edge-link.git
-cd signalk-edge-link
-npm install
-npm run build
-```
-
-Restart your Signal K server after installation.
-
-### Quick Start
-
-1. Open **Admin UI → Plugin Config → Signal K Edge Link**
-2. Choose an operation mode:
-   - **Server** — receives data from remote clients
-   - **Client** — sends data to a remote server
-3. Set the **UDP port** (must match between client and server)
-4. Enter a **32-character encryption key** (must be identical on both ends)
-5. For client mode, enter the **server IP address**
-6. Enable the plugin and verify data flow in the web dashboard
-
-> **Tip:** Start with the default settings. Enable path dictionary and MessagePack later for additional bandwidth savings.
-
----
-
-## Configuration
-
-The plugin provides a custom React-based configuration UI that dynamically adapts to the selected operation mode, showing only relevant settings.
-
-**Access:** Admin UI → Plugin Config → Signal K Edge Link
-
-### Server Mode (Receiver)
-
-| Setting | Description |
-|---------|-------------|
-| Operation Mode | Server/Client selector |
-| UDP Port | Port to listen on (1024–65535) |
-| Encryption Key | 32-character secret key |
-| MessagePack | Enable binary serialization |
-| Path Dictionary | Enable path encoding |
-
-### Client Mode (Sender)
-
-| Setting | Description |
-|---------|-------------|
-| Operation Mode | Server/Client selector |
-| UDP Port | Port to send to |
-| Encryption Key | 32-character secret key (must match server) |
-| Destination Address | Server IP or hostname |
-| Heartbeat Interval | Keep-alive message frequency (seconds) |
-| Connectivity Test Target | Address to ping for network monitoring |
-| Connectivity Test Port | Port to test (80, 443, etc.) |
-| Check Interval | How often to test connectivity (minutes) |
-| MessagePack | Enable binary serialization |
-| Path Dictionary | Enable path encoding |
-
-Additional client settings are available in the web dashboard:
-- **Delta timer** — collection interval (100–10000 ms)
-- **Subscription paths** — Signal K paths to transmit
-- **Sentence filter** — NMEA sentences to exclude (e.g., `GSV, GSA, VTG`)
-
-### Web Dashboard
-
-**Access:** `http://[signalk-server]:3000/plugins/signalk-edge-link`
-
-The dashboard provides real-time monitoring and configuration controls.
-
-**Client mode:**
-- Delta timer and subscription management
-- Sentence filter configuration
-- Upload/download bandwidth with compression ratio
-- Bandwidth savings display (actual bytes saved)
-- Path analytics with per-path data volume breakdown
-- Performance metrics (errors, uptime, deltas sent)
-- Rate history chart (last 150 seconds)
-
-**Server mode:**
-- Download bandwidth and packet rate
-- Bandwidth savings display
-- Incoming path analytics
-- Performance metrics (deltas received, errors)
-- Compression effectiveness tracking
-
-### Configuration Files
-
-These JSON files are stored in the plugin data directory and support hot-reload — changes take effect automatically without restarting.
-
-| File | Purpose | Default |
-|------|---------|---------|
-| `delta_timer.json` | Collection interval in ms | `{"deltaTimer": 1000}` |
-| `subscription.json` | Signal K paths to subscribe | `{"context": "*", "subscribe": [...]}` |
-| `sentence_filter.json` | NMEA sentences to exclude | `{"sentences": []}` |
-
-### API Endpoints
-
-All endpoints are rate-limited to 20 requests per minute per IP.
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/plugins/signalk-edge-link/config/:filename` | Read a configuration file |
-| POST | `/plugins/signalk-edge-link/config/:filename` | Update a configuration file |
-| GET | `/plugins/signalk-edge-link/metrics` | Real-time statistics and performance data |
-| GET | `/plugins/signalk-edge-link/paths` | Path dictionary information |
-| GET | `/plugins/signalk-edge-link/plugin-config` | Current plugin configuration |
-| POST | `/plugins/signalk-edge-link/plugin-config` | Update plugin configuration |
-| GET | `/plugins/signalk-edge-link/plugin-schema` | Plugin schema definition |
-
----
-
-## Network Monitoring
-
-In client mode, the plugin measures **Round Trip Time (RTT)** using TCP ping to monitor connectivity and latency.
-
-**How it works:**
-1. TCP ping is sent to the configured test address and port at the configured interval
-2. RTT is published to local Signal K at `networking.modem.rtt` (value in seconds)
-3. If subscribed, RTT data is transmitted to the remote server with other data
-
-**To enable RTT transmission:** Add `networking.modem.rtt` to your subscription paths.
-
-**Use cases:**
-- Monitor cellular or satellite modem latency
-- Track connection quality over time
-- Trigger alerts on high latency
-- Analyze network performance trends
-
----
-
-## Performance
-
-### Bandwidth Comparison
-
-![Data Rate Comparison](https://raw.githubusercontent.com/KEGustafsson/signalk-edge-link/refs/heads/main/doc/datarate.jpg)
-
-| Mode | Bandwidth | Reduction vs. WebSocket |
-|------|-----------|------------------------|
-| 1000 ms collection | ~44.1 kb/s | ~70% |
-| 100 ms collection | ~107.7 kb/s | ~28% |
-| WebSocket real-time | ~149.5 kb/s | — |
-
-Typical compression results on Signal K data:
-
+[![npm version](https://img.shields.io/npm/v/signalk-edge-link)](https://www.npmjs.com/package/signalk-edge-link)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen)](https://nodejs.org)
+
+Signal K Edge Link is a Signal K plugin that transfers vessel deltas between Signal K servers over encrypted UDP.
+
+It is designed for links where latency, packet loss, and bandwidth usage matter (cellular, satellite, and other unstable WAN paths).
+
+![Data Connector Concept](docs/assets/dataconnectorconcept.jpg)
+
+## Why use it?
+
+- **Secure transport** using AES-256-GCM
+- **Bandwidth optimization** with Brotli compression (plus optional MessagePack and path dictionary)
+- **Two operating modes**:
+  - **Client**: subscribes to local deltas and sends packets
+  - **Server**: receives packets, decrypts, and forwards to local Signal K
+- **Protocol v2/v3 features** for difficult links:
+  - ACK/NAK-based reliability
+  - congestion control
+  - optional primary/backup bonding
+  - monitoring and alerting endpoints
+- **Multi-connection support** on one Signal K instance
+
+## How data flows
+
+```text
+Client Signal K
+  -> subscribe + batch deltas
+  -> optional path dictionary + MessagePack
+  -> Brotli compress
+  -> AES-256-GCM encrypt
+  -> UDP send
+
+Server Signal K
+  <- UDP receive
+  <- AES-256-GCM decrypt
+  <- Brotli decompress
+  <- optional MessagePack + path decode
+  <- inject into local Signal K
 ```
-Original: 19,293 bytes → Encrypted + Compressed: 622 bytes (96.78% reduction)
-```
-
-### Smart Batching
-
-The plugin uses adaptive smart batching to keep UDP packets under the MTU limit (1400 bytes), preventing fragmentation that can cause data loss.
-
-1. **Rolling average** — tracks bytes-per-delta using exponential smoothing
-2. **Dynamic batch sizing** — calculates optimal deltas per packet based on recent sizes
-3. **Early send trigger** — sends immediately when a batch reaches the predicted size limit
-4. **Self-learning** — continuously adapts as data patterns change
-
-```
-Example: Initial estimate 5 deltas/batch → After learning: 11 deltas/batch
-         All packets stay well under 1400 bytes
-```
-
-### Optimization Tips
 
-For the best bandwidth efficiency:
+## Requirements
 
-1. **Increase delta timer** — 1000 ms gives optimal compression; lower values increase bandwidth
-2. **Enable path dictionary** — saves 10–20% by replacing path strings with numeric IDs
-3. **Enable MessagePack** — saves 15–25% with binary serialization
-4. **Filter NMEA sentences** — exclude GSV, GSA, VTG to remove unnecessary data
-5. **Review subscriptions** — subscribe only to paths you need
+- Two Signal K instances (source and destination)
+- UDP reachability from client to server on your chosen port
+- Shared encryption key on both ends (32-character ASCII, 64-character hex, or 44-character base64)
+- Node.js 16+ (if installing from source: dev dependencies including TypeScript are installed automatically via `npm install`)
 
----
+## Installation
 
-## Security
+### Option A: Signal K Plugin Manager
 
-### Encryption
+Install **Signal K Edge Link** from your Signal K plugin catalog.
 
-All data is encrypted with **AES-256-GCM**, providing authenticated encryption in a single operation.
-
-| Property | Detail |
-|----------|--------|
-| Algorithm | AES-256-GCM |
-| IV | 12 bytes, unique per message |
-| Auth tag | 16 bytes, tamper detection |
-| Wire format | `[IV (12 bytes)][Encrypted Data][Auth Tag (16 bytes)]` |
-| Overhead | 28 bytes per packet |
-
-**Security features:**
-- Tamper detection — any modification causes decryption failure
-- Rate-limited API endpoints (20 req/min/IP)
-- Input validation on all parameters
-- Key entropy checking — rejects weak keys
-- XSS protection in the web UI
-- Stateless UDP — no session state to compromise
-
-### Secret Key Requirements
-
-- Exactly **32 characters** (256 bits)
-- Minimum **8 unique characters**
-- Must match on both client and server
-
-Generate a secure key:
+### Option B: Manual install from source
 
 ```bash
-openssl rand -base64 32 | cut -c1-32
+cd ~/.signalk/node_modules
+git clone https://github.com/KEGustafsson/signalk-edge-link.git
+cd signalk-edge-link
+npm install
+npm run build
 ```
 
-**Valid examples:**
-```
-Abc123!@#XYZ456$%^uvw789&*()pqr0
-K9#mP2$nQ7@rS4%tU6^vW8*xY3!zA5&
-abcdefgh12345678901234567890abcd
-```
+Restart Signal K after installation.
 
-**Invalid examples:**
-```
-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa   # All same character
-abababababababababababababababab   # Insufficient diversity
-MySecretKey123                     # Too short
-```
+## Quick start
 
-### Best Practices
+### 1) Configure the destination (Server mode)
 
-1. Use strong, randomly generated keys (`openssl rand` recommended)
-2. Never commit keys to version control
-3. Rotate keys periodically (every 6–12 months)
-4. Monitor logs for decryption failures (may indicate attacks or key mismatch)
-5. Restrict UDP access with firewall rules to known IP addresses
-6. Test configuration in a safe environment before production deployment
+In Signal K Admin UI:
 
----
+1. Open `Server -> Plugin Config -> Signal K Edge Link`
+2. Click **Add Server**
+3. Set:
+   - `Connection Name` (for example `shore-server`)
+   - `UDP Port` (default `4446`)
+   - `Encryption Key` (same shared secret used by client)
+   - `Protocol Version` (`3` recommended for new deployments; use `2` only for compatibility with an existing v2 peer)
+4. Save
 
-## Troubleshooting
+### 2) Configure the source (Client mode)
 
-### Plugin Not Loading
+On the sending Signal K instance:
 
-- Verify `npm install` completed successfully
-- Check Signal K server logs for errors
-- Ensure plugin directory is `~/.signalk/node_modules/signalk-edge-link`
-- Verify Node.js version ≥ 14.0.0
+1. Open `Server -> Plugin Config -> Signal K Edge Link`
+2. Click **Add Client**
+3. Set:
+   - `Connection Name` (for example `vessel-client`)
+   - `Server Address` (destination host/IP)
+   - `UDP Port` (must match server)
+   - `Encryption Key` (must match server)
+   - `Protocol Version` (`3` recommended for new deployments; use `2` only for compatibility with an existing v2 peer)
+4. Save
 
-### Web UI Not Accessible
+### 3) Verify traffic
 
-- Run `npm run build` to generate UI files
-- Verify `public/` directory exists with built files
-- Clear browser cache and refresh
+Open the runtime UI:
 
-### No Data Transmission
+`http://<signalk-host>:3000/plugins/signalk-edge-link/`
 
-**Client side:**
-1. Confirm encryption keys match on both ends
-2. Verify UDP port and destination address
-3. Check firewall allows UDP traffic on the configured port
-4. Confirm subscription paths are valid Signal K paths
-5. Verify delta timer is running (check metrics in web dashboard)
+Check that:
 
-**Server side:**
-1. Verify UDP port is not blocked by firewall
-2. Confirm encryption key matches the client
-3. Check Signal K logs for decryption errors
-4. Verify client is sending data (check client metrics)
+- client `Deltas Sent` increases
+- server `Deltas Received` increases
+- encryption/decryption errors remain stable at zero
 
-**Common error messages:**
+## Protocol version guidance
 
-| Message | Cause |
-|---------|-------|
-| `Unsupported state or unable to authenticate data` | Mismatched encryption keys |
-| `Invalid packet size` | Corrupted data or network issues |
-| `Secret key must be exactly 32 characters` | Invalid key length |
+| Version | Use when                                                  | Notes                                                                       |
+| ------- | --------------------------------------------------------- | --------------------------------------------------------------------------- |
+| v1      | stable local links, simplest setup                        | lower overhead, no ACK/NAK reliability layer                                |
+| v2      | packet loss, variable latency, WAN links                  | adds retransmission, congestion control, bonding, richer monitoring         |
+| v3      | same use cases as v2 when both peers can upgrade together | keeps v2 features and authenticates ACK/NAK/HEARTBEAT/HELLO control packets |
 
-### Poor Performance
+For unstable links, start with **v3** when both peers support it; fall back to **v2** only when you need compatibility with an already deployed v2 peer.
 
-- Increase delta timer for better compression (1000 ms recommended)
-- Enable path dictionary and MessagePack
-- Filter unnecessary NMEA sentences
-- Check network latency with the ping monitor
-- Monitor CPU usage (Brotli compression at quality 10 is CPU-intensive)
+## Runtime UI and API
 
-### Debug Logging
+- Runtime UI: `/plugins/signalk-edge-link/`
+- API base path: `/plugins/signalk-edge-link`
+- Default API rate limit: **120 requests/minute/IP**
 
-Enable in Signal K plugin settings to see:
-- Connection monitor status and ping results
-- Configuration file changes (automatic reload)
-- Delta transmission statistics
-- Compression ratios and packet sizes
-- Error messages with full context
+Most used endpoints:
 
----
+- `GET /metrics`
+- `GET /network-metrics`
+- `GET /monitoring/alerts`
+- `GET /connections`
+- `GET /instances`
+- `GET /instances/:id`
+- `GET /connections/:id/metrics`
+- `GET /connections/:id/network-metrics`
+- `GET /bonding`
+- `POST /bonding`
 
-## Development
+For full endpoint details, use `docs/api-reference.md
 
-### Architecture
+## Configuration model (summary)
 
-**Data pipeline:**
+Configuration is an array of independent connections:
 
+```json
+{
+  "connections": [
+    {
+      "name": "shore-server",
+      "serverType": "server",
+      "udpPort": 4446,
+      "secretKey": "<32-byte key>",
+      "protocolVersion": 3
+    },
+    {
+      "name": "sat-client",
+      "serverType": "client",
+      "udpPort": 4447,
+      "udpAddress": "10.0.0.1",
+      "secretKey": "<32-byte key>",
+      "protocolVersion": 3
+    }
+  ]
+}
 ```
-Client (Sender):
-  Signal K Deltas → Filter → [Path Encode] → [MessagePack] → Brotli → AES-256-GCM → UDP
 
-Server (Receiver):
-  UDP → AES-256-GCM → Brotli → [MessagePack] → [Path Decode] → Signal K
-```
+- Each connection runs independently.
+- Legacy single-object config is auto-normalized to one connection.
+- Client runtime JSON files (`delta_timer.json`, `subscription.json`, `sentence_filter.json`) are stored per connection and can be edited via API.
 
-The plugin core is decomposed into focused modules:
+For complete setting definitions and ranges, use `docs/configuration-reference.md`.
 
-| Module | Responsibility |
-|--------|---------------|
-| `index.js` | Plugin entry point, shared state, file watchers, lifecycle |
-| `lib/constants.js` | Shared constants and batch size calculation |
-| `lib/CircularBuffer.js` | Fixed-size circular buffer for O(1) metrics history |
-| `lib/crypto.js` | AES-256-GCM encryption and decryption |
-| `lib/metrics.js` | Bandwidth tracking, path analytics, error recording |
-| `lib/pathDictionary.js` | Signal K path encoding (170+ paths) |
-| `lib/pipeline.js` | Compress → encrypt → send / receive → decrypt → decompress |
-| `lib/routes.js` | HTTP route handlers, rate limiting, config file I/O |
+Schema and migration helpers:
 
-Modules are wired together via factory functions that receive a shared `state` object by reference, enabling cross-module state access without globals.
+- `schemas/config.schema.json` (machine-readable config schema)
+- `src/scripts/migrate-config.ts` (convert legacy flat config to `connections[]`)
+- `npm run migrate:config -- <input.json> [output.json]`
 
-### Project Structure
+## Security notes
 
-```
-signalk-edge-link/
-├── index.js                    # Plugin entry, state, watchers, lifecycle
-├── lib/
-│   ├── CircularBuffer.js       # Fixed-size circular buffer
-│   ├── constants.js            # Shared constants and utilities
-│   ├── crypto.js               # AES-256-GCM encryption module
-│   ├── metrics.js              # Metrics, bandwidth, path analytics
-│   ├── pathDictionary.js       # Signal K path encoding (170+ paths)
-│   ├── pipeline.js             # Pack/unpack pipeline (compress, encrypt, UDP)
-│   └── routes.js               # HTTP routes and rate limiting
-├── src/
-│   ├── webapp/
-│   │   ├── index.js            # Web dashboard (vanilla JS)
-│   │   └── styles.css
-│   └── components/
-│       └── PluginConfigurationPanel.jsx  # React config panel
-├── __tests__/                  # 209 tests across 9 files
-│   ├── crypto.test.js
-│   ├── pathDictionary.test.js
-│   ├── compression.test.js
-│   ├── full-pipeline.test.js
-│   ├── smartBatching.test.js
-│   ├── config.test.js
-│   ├── index.test.js
-│   ├── webapp.test.js
-│   └── integration-pipe.test.js
-└── public/                     # Built UI files (generated)
-```
+- Uses AES-256-GCM authenticated encryption.
+- Keys must match exactly and can be entered as 32-character ASCII, 64-character hex, or 44-character base64.
+- Restrict UDP ingress to trusted source addresses whenever possible.
 
-### Build Commands
+Example key generation:
 
 ```bash
-npm run dev            # Development build with watch mode
-npm run build          # Production build
-npm test               # Run all 209 tests
-npm run test:watch     # Run tests in watch mode
-npm run test:coverage  # Generate coverage report
-npm run lint           # Check code style
-npm run lint:fix       # Auto-fix linting issues
-npm run format         # Format code with Prettier
+openssl rand -hex 32
 ```
 
-### Testing
-
-The test suite covers all critical paths with 209 tests across 9 files:
-
-| Test file | Scope |
-|-----------|-------|
-| `crypto.test.js` | Encryption, decryption, key validation |
-| `pathDictionary.test.js` | Path encoding and decoding |
-| `compression.test.js` | Brotli compression effectiveness |
-| `full-pipeline.test.js` | End-to-end compression + encryption round-trip |
-| `smartBatching.test.js` | Rolling average, batch limits, size verification |
-| `config.test.js` | Configuration file creation, loading, hot-reload |
-| `index.test.js` | Plugin lifecycle, schema validation |
-| `webapp.test.js` | Web UI metrics and API endpoints |
-| `integration-pipe.test.js` | Full input → backend → frontend data flow |
+## Troubleshooting
 
-Run a specific test suite:
+Common checks:
 
-```bash
-npm test -- crypto.test.js
-npm test -- full-pipeline.test.js
-npm test -- --coverage
-```
+- Verify `udpAddress`, `udpPort`, and `secretKey` match both ends.
+- Confirm server UDP port is reachable and not already in use.
+- If link quality is poor, switch to `protocolVersion: 3` when both peers can upgrade together, or `2` if you must stay compatible with an existing v2 peer.
 
-### Technical Reference
+For issue-oriented diagnostics, use `docs/troubleshooting.md`.
 
-**Packet format:**
+## Developer commands
 
-```
-[IV (12 bytes)][Encrypted Data][Auth Tag (16 bytes)]
-Total overhead: 28 bytes per packet
+```bash
+npm run build
+npm run dev
+npm test
+npm run test:v2
+npm run test:integration
+npm run lint
+npm run lint:fix
+npm run cli -- help
+npm run cli -- instances list --token=$EDGE_LINK_TOKEN --state=running --limit=10 --page=1 --format=table
+npm run cli -- instances show alpha --token=$EDGE_LINK_TOKEN --format=table
+npm run cli -- instances create --config ./new-instance.json --token=$EDGE_LINK_TOKEN
+npm run cli -- instances update alpha --patch '{"udpAddress":"10.0.0.2"}' --token=$EDGE_LINK_TOKEN
+npm run cli -- instances delete alpha --token=$EDGE_LINK_TOKEN
+npm run cli -- bonding status --token=$EDGE_LINK_TOKEN --format=table
+npm run cli -- bonding update --patch '{"failoverThreshold":300}' --token=$EDGE_LINK_TOKEN
+npm run cli -- status --token=$EDGE_LINK_TOKEN --format=table
 ```
 
-**Compression pipeline (detailed):**
+## Management API security
 
-```
-Client side:
-  JSON.stringify(delta)           → Serialization
-  → [pathDictionary.encode()]     → Optional: numeric path IDs
-  → [msgpack.encode()]            → Optional: binary format
-  → brotli.compress(quality=10)   → Maximum compression
-  → encryptBinary(key)            → AES-256-GCM
-  → UDP send
-
-Server side:
-  UDP receive
-  → decryptBinary(key)            → Verify + decrypt
-  → brotli.decompress()
-  → [msgpack.decode()]
-  → [pathDictionary.decode()]
-  → JSON.parse()
-  → Signal K handleMessage()
-```
+Set `managementApiToken` in plugin options (or the environment variable `SIGNALK_EDGE_LINK_MANAGEMENT_TOKEN`). Protected routes include:
 
-**Smart batching constants:**
+- `/instances`, `/bonding`, `/status`, `/plugin-config`
+- `/config/*`, `/connections/:id/config/*`
+- `/connections/:id/metrics`, `/connections/:id/network-metrics`
+- `/connections/:id/bonding`, `/connections/:id/congestion`
+- `/connections/:id/monitoring/*`, `/monitoring/alerts`
+- `/capture/*`, `/delta-timer`
 
-| Constant | Value | Purpose |
-|----------|-------|---------|
-| Safety margin | 85% | Target 85% of MTU (1190 bytes effective) |
-| Smoothing factor | 0.2 | Rolling average weight (20% new, 80% old) |
-| Initial estimate | 200 bytes | Starting bytes-per-delta assumption |
-| Min deltas | 1 | Always send at least 1 delta |
-| Max deltas | 50 | Cap to prevent excessive batching latency |
+Send the token as either:
 
-**Performance characteristics:**
+- `X-Edge-Link-Token: <token>`
+- `Authorization: Bearer <token>`
 
-| Metric | Value |
-|--------|-------|
-| Compression ratio | 85–97% on typical Signal K data |
-| Packet latency | 20–30 ms (serialize → compress → encrypt) |
-| Throughput | 10–100 Hz update rates |
-| Memory | Constant O(1) with circular buffers |
+CLI commands support `--token=<token>` or the `SIGNALK_EDGE_LINK_MANAGEMENT_TOKEN` environment variable.
 
-### Contributing
+## Web UI token injection
 
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/name`
-3. Make changes and add tests
-4. Run `npm test` and `npm run lint` (all must pass)
-5. Run `npm run build` (must succeed)
-6. Commit with clear messages using conventional format
-7. Submit a pull request
+Management pages automatically attach auth headers when a token is available. Token sources are checked in this order:
 
-**Requirements for all contributions:**
-- All 209 tests pass
-- No ESLint errors or warnings
-- Code formatted with Prettier
-- Test coverage for new features
-- README updated if adding features
+1. `window.__EDGE_LINK_AUTH__.token` — injected global (preferred for server-side injection)
+2. URL query parameter `?edgeLinkToken=<token>`
+3. `localStorage.setItem("signalkEdgeLinkManagementToken", "<token>")`
 
-**Commit message format:**
+The UI sends both `X-Edge-Link-Token` and `Authorization: Bearer <token>` by default. Override with:
 
+```javascript
+window.__EDGE_LINK_AUTH__ = {
+  token: "<token>",
+  queryParam: "edgeLinkToken",
+  localStorageKey: "signalkEdgeLinkManagementToken",
+  headerMode: "both" // "both" | "authorization" | "x-edge-link-token"
+};
 ```
-type: description
 
-Types: feat, fix, docs, style, refactor, perf, test, chore
-```
-
----
+## Documentation map
+
+- `docs/README.md` (documentation index)
+- `docs/architecture-overview.md` (system architecture and lifecycle)
+- `docs/configuration-reference.md` (settings and defaults)
+- `docs/api-reference.md
+- `docs/protocol-v2.md` (reliable protocol operational overview)
+- `docs/protocol-v3-spec.md` (authenticated control-plane details)
+- `docs/bonding.md` (bonding concepts and API usage)
+- `docs/congestion-control.md` (congestion-control behavior and tuning)
+- `docs/metrics.md` (metrics and monitoring reference)
+- `docs/management-tools.md` (instance/bonding API + CLI operations)
+- `docs/security.md` (security guidance and deployment hardening)
+- `docs/performance-tuning.md` (deployment tuning recommendations by hardware profile)
+- `samples/` (example JSON configurations for minimal/dev/v2-bonding setups)
+- `grafana/dashboards/edge-link.json` (starter Grafana dashboard)
+- `schemas/config.schema.json` (unified plugin config schema)
+- `src/scripts/migrate-config.ts` (legacy config migration utility)
+- `src/bin/edge-link-cli.ts` (CLI wrapper for migration and instance/bonding management)
 
 ## License
 
-MIT License — Copyright (c) 2024 Karl-Erik Gustafsson
-
-See [LICENSE](LICENSE) file for details.
+MIT. See `LICENSE`.