signalk-wakelogger 0.2.0-beta.1 → 0.2.0-beta.10

package/CHANGELOG.md

@@ -1,47 +1,197 @@
-# Changelog
+# What's new in Wake Logger for Signal K
 
-All notable changes follow [Keep a Changelog](https://keepachangelog.com/) and semantic versioning.
+Updates for boat owners and crew: what's new, what's improved, and anything you need to do.
 
-## [Unreleased]
+## [0.2.0-beta.10] - 2026-10-11
 
-## [0.2.0-beta.1] - 2026-09-02
+### Race-day navigation survives course activation failures
 
-### Changed
+- The Race tab always shows live navigation — true wind, boat speed, heading and VMG — plus the next-mark bearing and distance worked out from the cached course, even when course activation is rejected or conflicted, a Race Pack is missing, or offline readiness is not ready.
+- Readiness is now two separate things: **live navigation** (a selected course with points) and **offline maps/forecast preparation**. A missing Race Pack or unverified chart is reported as an informational banner and never reads as "you cannot navigate".
+- **Activate** now clears a leftover or malformed route parked at the Wake Logger route id, with a confirmation that names the occupying resource. Implicit course delivery still never overwrites a foreign or unowned resource, and another app's active route still needs an explicit activation.
+- Rejections and conflicts report the exact blocker — occupied target, malformed target or foreign active route — with the occupying resource's id, name and owner when readable, so the reason is clear instead of a generic conflict.
 
-- Replaced the placeholder Signal K App Store artwork with Wake Logger's official 512 px blue-wave app icon.
-- Reworked the App Store summary and README to introduce Wake Logger's live tracking, trip replay, vessel/crew workspace, environmental context and optional performance-analysis features.
-- Clarified how accepted Signal K telemetry appears in Wake Logger's private and optionally shared live vessel views.
-- Updated App Store publication guidance for the npm `latest` alias required by Signal K discovery during the beta period.
+### Updating
 
-### Validated
+- Update Wake Logger in the Signal K App Store and restart Signal K if prompted. Existing settings and recorded trips are retained. If a leftover route blocks activation, choose **Activate** and review the named replacement before confirming.
+- Live instrument values still depend on available, current Signal K data. A cached course can show the next mark while activation is blocked, but advancing the native course stays unavailable until activation succeeds. Offline forecast and chart readiness remain separate requirements.
 
-- Confirmed an active production association transmitted all supported fields and received application-level durable acknowledgements with no pending queue; the synthetic Signal K source was disabled immediately after the check.
+## [0.2.0-beta.9] - 2026-10-09
 
-## [0.2.0-beta.0] - 2026-09-02
+### Under the hood
+
+- No user-facing changes. The plugin's test suite now skips the SQLite durability checks when the native module isn't built and retries temporary-directory cleanup, so source installs and the Signal K plugin registry test suite run cleanly without a compiler.
+
+## [0.2.0-beta.8] - 2026-10-06
+
+### Finish a trip onboard
+
+- A new **Finish trip** control closes the recording cleanly and asks Wake Logger to confirm it on the current connection, so the finished trip is processed and marked ready without waiting for the next reconnect.
+- The onboard recorder keeps serialising samples if persisting a receipt fails, so a momentary storage error cannot stall the upload queue.
+
+### The right course, every time
+
+- Wake Logger's own Signal K course is reconciled without treating it as a foreign route, and a newer Race Pack identity is surfaced before the course is delivered, so a previous race's course cannot silently win.
+
+### Guides on the onboard map
+
+- True heading and mirrored apparent-wind tack/gybe guides are drawn on the chartplotter, so the tack or gybe angle is visible against the boat's heading.
+
+## [0.2.0-beta.7] - 2026-10-01
+
+### A new recording never shows the previous trip
+
+- If a fresh recording starts (or the boat records before a browser connects), the onboard map no longer treats a browser-drawn tail as the whole trip: an empty or failed archive read is reconciled on the next poll, so the full recovered track appears promptly instead of after hundreds of fixes.
+- The map keeps an explicit viewport intent. Fullscreen, rotation, resizing and course changes no longer re-frame the map or drop the selected recording, the archive identity is guarded so a delayed response for a previous recording cannot appear, and a new recording's positions are never appended to the recording still on screen. Fit course, Fit track and Centre on vessel stay separate.
+
+### See the whole trip from wherever you open the map
+
+- Opening the onboard map part-way through a passage (or reloading, or connecting a second device) now shows the recorded track from the real departure through the latest position, sourced from the durable onboard archive rather than from page-open time. This works with no internet and with Live tracking off, and it survives a plugin restart without its graceful stop path.
+- A labelled **Fit track** control fits the whole sailed track, independent of any course, and the map automatically fits the full track on first load unless you have already panned or zoomed. Fit course and Centre on vessel stay separate, so course overlays never hide the sailed history.
+
+### Completed trips stay on the map after upload
+
+- The onboard map archive keeps its own recording index, independent of the upload queue. A completed trip remains available on the map after its telemetry has been uploaded and acknowledged and after the pending-upload records are removed, and it survives a reload or plugin restart. Starting a new trip never mixes it with the previous one.
+- The archive repairs an interrupted write when it next opens or appends: a partial header is rewritten, a partial final record is trimmed, and a corrupt file is quarantined, so records stay aligned. Writes are ordered and bounded, and pending writes are flushed on orderly shutdown. Power-loss durability is not claimed per sample; the last flushed data is retained and the tail is repaired.
+
+### Navigation can only be advanced by the controlling device
+
+- Taking navigation control returns a generation. A permit from the plugin is an authorisation, not an application: `already_applied`/`superseded` are reported only from observed native state, the actual pending detection is validated, and the detection is accepted only after a confirm step re-reads native state. A stale point, changed course, expired/handed-over controller, or missing detection is rejected, and a merely permitted-but-unexecuted attempt stays pending and retryable.
+- Automatic application is disabled in this candidate, because Signal K 2.31 has no plugin point-index API or compare-and-set to fence a client-performed native write. Detections are offered for explicit acceptance by the controlling device. Each browser tab has its own identity, so a newly opened tab is a viewer until someone deliberately takes control.
+
+### Trustworthy instrument values
+
+- Every input used by a derived wind or VMG value — including speed over ground/through water and the heading used to convert an apparent angle — now participates in the freshness and time-skew bound, so a stale input cannot be hidden by a fresh one.
+- Signal K request deadlines now stay active while the response body is being read, so a stalled body times out instead of hanging, and the next poll recovers.
+
+### A broken source clock can no longer hide the trip
+
+- A source time more than 30 days before the delta was delivered is treated as a broken clock and replaced by receipt time, instead of being queued and later rejected by Wake Logger as outside the vessel's entitled capture window (for example a GPS reporting a stale 2014 default date).
+- The database outbox now declares sequences skipped by a seed or reset as dropped when it opens, matching the file outbox, so the cloud's contiguous acknowledgement can advance and later trips are not left waiting for history.
+
+## [Unreleased] - 2026-09-27
+
+### Offline race readiness you can trust
+
+- One clear **Offline race ready** status now checks that the selected course is applied, the expected Signal K route is active, and a Race Pack that matches the course (id, race plan and course definition) is prepared with supported rules and a current forecast. Changing the course immediately invalidates readiness for the old pack, even though that pack is kept for history.
+- Switching Live tracking off stays possible for radio silence, but if readiness is incomplete the app now shows a prominent pre-switch warning that names exactly what is missing instead of implying onboard sail planning will work.
+
+### Clearer navigation failures
+
+- Failed Signal K requests now keep the operation, method, path, HTTP status and a bounded, credential-safe reason. Advancing, setting or activating a course shows a human-readable message such as "Could not advance to the next course point to Mark 3 — Signal K rejected the active route update: <reason>", and the bounded detail is written to the plugin log. Tokens and passwords are never logged or displayed.
+
+### A track that survives reload
+
+- The onboard map now rebuilds the current recording's track from an independent durable onboard archive on open or reload, rather than starting at page-open time and rather than depending on whether telemetry has already been uploaded. New fixes append incrementally; long trips are decimated for display without changing the recording; and the complete geometry survives browser reload, page-resume and plugin restart with no Wake Logger/cloud connection. A tail-only cloud trip is marked "Reconstructing trip · N% history received" until its history converges.
+
+### Standalone vessel instruments
+
+- A new **Instruments** tab is the default when no course is selected. It reads position, speed and course over ground, heading (true or magnetic), speed through water, depth (with its reference), and apparent and true wind directly from the local Signal K server.
+- Instruments are independent of the course, Race Pack, recording and Wake Logger connection: a failed course request, a mismatched pack or Live tracking off does not stop them. Freshness is tracked per measurement, stale and missing values are marked, and no wind is invented from forecast data. Wind-relative VMG is labelled as such.
+- "No course selected" is a normal state: the instrument view stays clean, and course controls and race warnings remain in the race panel.
+
+## [0.2.0-beta.6] - 2026-09-26
+
+### Onboard race planning matches Wake Logger exactly
+
+- The onboard planner now starts the current leg from your boat's actual position, uses the real current in its speed and arrival estimates, and no longer assumes a fixed six-knot midpoint speed. Remaining distance and arrival times reflect where you actually are.
+- Onboard wind is only used for the current leg once a genuine five-minute observation window is ready (30 good samples across at least four minutes, newest within 30 seconds). Until then the downloaded forecast is used, with a clear note.
+- A downloaded course is only used when its course definition matches the Race Pack, so an edited course can't be planned against an old pack. Reversed courses are not planned rather than being calculated the wrong way round.
+- Wake Logger cloud now calculates the remaining race with exactly the same rules as the onboard planner, so the two agree. Raw instrument samples are aggregated with the same method on both sides, and the Live tracking ON and OFF views show the same plan and sail recommendation.
 
-### Changed
+### Reliable Race Pack and race-plan hand-over
 
-- Separated npm beta publication from Raspberry Pi, real-vessel and target-hardware validation; those remain first-vessel and stable-production gates collected through the beta.
+- A removed or archived course now clears the onboard Race Pack durably, so a stale copy can't reappear after a restart or reconnect.
+- Onboard race-plan updates are only removed once Wake Logger confirms it stored them; if the confirmation is missed they are sent again after reconnecting or restarting.
+- Onboard race-plan updates now carry the recording session they came from, so Wake Logger links them to the right outing even when they arrive late.
+- Switching Live tracking off sends one final onboard status and then stops transmitting immediately. The final onboard status is kept by the server after the plugin disconnects, and an unexpected connection loss still reports the vessel offline.
+- Added a production-like broker test (`npm run test:broker:dynsec`) that runs against a real Mosquitto dynamic-security broker and the Wake Logger cloud provisioning/framing functions.
+
+## [0.2.0-beta.5] - 2026-09-16
+
+### Live tracking when you want it
+
+- Turn live tracking on or off directly from the onboard map. When it's off, your trip still records on board and uploads later; turn it back on to resume live updates.
+- The setting is remembered across restarts, and changing it does not split a trip.
+
+### A clearer map and upload status
+
+- The onboard map now matches Wake Logger's live instrument view, with layouts for phones and tablets and a full-screen option.
+- Historical uploads show percentage progress and an estimated time remaining once upload speed can be measured. A coloured live-tracking indicator makes connection status easier to see.
+- Expandable recording details keep the main upload view compact, and only real trips are created from your recordings.
+
+### Crew can use their own Signal K accounts
+
+- The onboard map no longer requires the Signal K administrator login. Any crew member with a Signal K account can sign in and view the map.
+- Changing live tracking or activating a course needs an account with read/write access — ask your Signal K administrator to set this for your account. Unpairing the vessel still requires an administrator.
+- If your crew don't have Signal K accounts yet, an administrator can add them in Signal K's **Security** settings.
+
+
+## [0.2.0-beta.4] - 2026-09-14
+
+### Clearer help in Signal K
+
+- Rewritten the App Store guide around pairing, recording trips, uploading later, using courses and preparing offline maps.
+- Replaced technical release summaries with customer-facing notes. Developer setup remains in the separate development documentation.
+
+## [0.2.0-beta.3] - 2026-09-14
+
+### Record your trip now, upload later
+
+Keep recording when internet access is unavailable, or choose **Record locally** to defer uploading. Switch back to **Automatic upload** when you are ready. Stored readings and recording details are retained through plugin restarts.
+
+With the supporting Wake Logger service update, you can see historical upload progress and processing status. Trips are finalised once their complete recording has arrived; missing data is clearly flagged.
+
+Local storage is limited: by default, queued readings are kept for up to seven days or 250 MB. Keep Signal K and the plugin running to record your trip.
+
+### Take your race course onboard
+
+Select a course in Wake Logger and synchronise it to your vessel before departure. Once downloaded, it remains available without internet access.
+
+Your course is available to other Signal K applications. You can advance or correct the current mark manually, and Wake Logger respects route selections made by other apps. Automatic detection of start crossings, mark roundings and finishes is not included in this release.
+
+### Follow your course on an onboard map
+
+The new mobile-friendly webapp displays your vessel, course, marks and current leg. It shows distance, bearing, cross-track error, VMG and arrival estimates when Signal K provides them.
+
+### Prepare for sailing offline
+
+Use locally installed Signal K charts and check coverage around your course before departure. Your vessel and course remain visible even without a basemap.
+
+**Before you update:** Upload progress and course synchronisation require the supporting Wake Logger service update. Offline basemaps require suitable charts installed through Signal K Charts; verification checks existing coverage and does not download missing maps.
+
+This remains a beta release.
+
+## [0.2.0-beta.2] - 2026-09-02
+
+### Easier to preview before installing
+
+- Fixed App Store screenshots that could fail to display after installation.
+- Added screenshots of live vessel tracking and trip review, alongside connection status and pairing settings.
+- Clarified how Wake Logger helps you track your vessel and revisit your trips.
+
+## [0.2.0-beta.1] - 2026-09-02
+
+### A clearer App Store introduction
+
+- Added Wake Logger's blue-wave app icon and improved the product introduction.
+- Explained live tracking, trip replay, crew access and optional trip analysis more clearly.
+- Clarified which navigation readings appear in private and owner-shared live views.
+
+## [0.2.0-beta.0] - 2026-09-02
 
-### Added
+### First public beta
 
-- Retained, credential-free plugin/outbox diagnostics for the Wake Logger administration dashboard.
-- Database API-preferred `OutboxStore` with a portable file fallback and sequence-safe backend selection.
-- Remotely managed, path-specific telemetry profiles and retained application acknowledgements.
-- Adaptive `NORMAL`, `CONSTRAINED` and `OFFLINE` sampling and rate-limited live/backlog scheduling.
-- Public-repository leakage checks, AppStore screenshots and beta-only trusted publishing preparation.
-- Disposable real-Mosquitto CI coverage and credential-bound outbox protection against partial-state sequence resets.
-- Idempotent beta-only npm release checks with exact tag/main ancestry, protected environment and trusted-publisher bootstrap documentation.
-- Disposable packaged-plugin Docker testing with real Signal K NMEA 2000 playback, generated HTTPS/MQTT TLS, durable ACKs, broker outage and abrupt-restart recovery.
-- Bounded retry for temporary pairing failures, explicit revoked-device status and a protected local credential-forget action that preserves retired outboxes and sequence state.
+- Made Wake Logger available through the Signal K App Store for beta use.
+- Improved connection and queued-upload status so support can help diagnose interrupted uploads.
+- Added centrally managed recording profiles to adapt uploads to changing connectivity.
+- Improved recovery of stored readings after outages and restarts.
+- Added clearer feedback for expired pairing codes and revoked device connections.
 
 ## [0.1.0] - 2026-08-31
 
-### Added
+### Initial version
 
-- Signal K lifecycle, configuration and supported navigation subscriptions.
-- SI normalization, validation and one-second sampling.
-- Checksummed segmented outbox with durable sequences and recovery.
-- MQTT 5 TLS/QoS 1 transport, current-state priority and application acknowledgements.
-- HTTPS pairing, protected credential persistence, trip evidence and status metrics.
-- Unit tests, CI, protocol and operational documentation.
+- Connected Signal K position and supported navigation readings to Wake Logger.
+- Added pairing, live updates and onboard storage for readings waiting to upload.
+- Added automatic retries and connection status information.

package/README.md

@@ -1,61 +1,104 @@
 # Wake Logger for Signal K
 
-[Wake Logger](https://wakelogger.com/) streams a vessel's live navigation, apparent wind and depth data from Signal K to the vessel's Wake Logger workspace. It is designed for intermittent marine internet connections: every sample is written to a durable local outbox before transmission, current position takes priority after reconnect, and historical data remains queued until Wake Logger durably acknowledges it.
+**Keep a record of your time on the water—even when you leave internet coverage.**
 
-This repository handles live telemetry only. It does not upload full-resolution NMEA archives, control vessel equipment or implement Wake Logger account and trip-editing business logic.
+[Wake Logger](https://wakelogger.com/) connects your boat's Signal K data to live vessel tracking and trip history. Record your outings, review your route afterward, and share the experience with authorised crew. Bring a selected race course onboard and follow it on a map using the navigation data already available on your boat.
 
-## Make more of your time on the water
+## What you can do
 
-Wake Logger turns raw GPS and onboard instrument data into a useful vessel history. Follow the latest position while the boat is connected, then review trips with route, speed, course, heading, depth and wind context. Wake Logger also provides private vessel and crew workspaces, trip photos, historical weather and tide context, and optional sailing-performance analysis—including race analytics and AI-assisted coaching where available.
+- **Track your boat live.** See its latest position, speed, heading, depth and apparent wind in Wake Logger when those sensors and an internet connection are available.
+- **Record without uploading.** Keep recording during an internet outage, or choose when uploads are allowed. Upload stored history when you reconnect.
+- **Review your trips.** Return to your route and recorded navigation data after the outing. With the supporting Wake Logger update, see upload progress and when a trip is being processed.
+- **Take your race course with you.** Download the selected course before departure and retain it onboard through internet outages and restarts.
+- **Use an onboard map.** View your boat, course, marks and current leg on a phone or tablet connected to the boat's Signal K server.
 
-The richer the Signal K data, the richer the review: this plugin supplies a resilient live feed directly from the onboard server, even when marine internet drops in and out. Features depend on the vessel's Wake Logger access, plan and available sensors. [Explore Wake Logger](https://wakelogger.com/) to see the wider trip-replay and vessel-management platform.
+This is a **beta release**. Upload progress and course synchronisation need the supporting Wake Logger service update. If those controls are not yet available in your account, contact Wake Logger support.
 
-## Requirements
+## What you need
 
-- Signal K Server with Node.js 20 or newer
-- An eligible Wake Logger vessel and a single-use pairing code
-- Outbound HTTPS for pairing and outbound MQTT over TLS on port 8883
+- A running Signal K server receiving your boat's position. Other navigation sensors are optional.
+- A Wake Logger account with permission to pair a device to your vessel.
+- Internet access for initial pairing, course downloads and uploads. Once paired, recording can continue without internet access.
+- For onboard course and map features, Signal K's route and course services. These features have been tested with Signal K Server 2.31.1.
+- For an offline basemap, suitable local charts installed through Signal K Charts. Charts are not included with Wake Logger.
 
-No inbound vessel connection is required. The plugin starts successfully when unpaired, offline, or when Wake Logger is unavailable.
+The plugin requires Node.js 20 or newer on the Signal K server. Your boat does not need to accept incoming connections from the internet.
 
-## Install and pair
+## Get started
 
-Install `signalk-wakelogger` from the Signal K AppStore, then open **Server → Plugin Config → Wake Logger**. Generate a pairing code in the Wake Logger vessel settings, enter it in the plugin configuration, and save. The public Wake Logger pairing endpoint is configured by default; non-production overrides must never be committed to this repository.
+1. In Signal K's **App Store**, install **Wake Logger** (`signalk-wakelogger`).
+2. In Wake Logger, open your vessel's settings and generate a Signal K pairing code.
+3. Open **Wake Logger** in Signal K's plugin configuration, enter the code and save. Enable the plugin if it is disabled.
+4. Check the connection status. When your boat supplies a position and the connection is online, it will appear in the vessel's **Signal K Live** view in Wake Logger.
 
-The pairing code is single-use. Temporary pairing-service failures are retried up to six times with bounded exponential delays while the code remains usable; an invalid or expired code stops immediately and requires a fresh code. MQTT credentials are returned once and stored with owner-only filesystem permissions under the plugin data directory. They never appear in normal logs or status messages.
+Pairing codes are single-use. If a code expires or is rejected, generate a new one. You do not need to pair again after an ordinary internet outage or plugin update.
 
-Use Wake Logger's **Replace device** workflow to move to another Signal K installation: the current association remains active until the replacement is fully provisioned. **Revoke association** stops the old device immediately without deleting its telemetry history. New pairings include a device-scoped status credential, allowing the plugin to report `Device revoked — enter a new pairing code` instead of a generic authentication error.
+## Record now, upload later
 
-## Telemetry and privacy
+Recording and uploading are separate. Keep Signal K and the Wake Logger plugin running, with your boat's navigation data available, for the trip to be recorded.
 
-Version 1 sends position and source time, with SOG, COG, heading, depth and apparent wind when supplied by the vessel. It does not collect battery, fuel, engine temperature or other machinery data. Signal K SI values are converted to Wake Logger's documented units. Missing optional sensors are normal. Wake Logger derives true wind, VMG and final trip boundaries in the cloud.
+**For normal use:** Leave **Upload mode** set to **Automatic upload**. If internet access drops, the plugin stores readings onboard and uploads them when the connection returns.
 
-The plugin does not decide who can see vessel data. Private crew access and any owner-controlled public live-sharing option are enforced by Wake Logger.
+**To deliberately defer uploading:** Pair first, then turn **Live tracking** off on the onboard Wake Logger map. The plugin keeps recording locally, up to your storage and age limits. Turn it on when you are ready to send your live position and upload stored history. Changing the switch does not end a trip or restart recording, and the setting survives restarts.
 
-## Live vessel tracking
+You can also choose **Record locally** or **Automatic upload** in the plugin's **Upload mode** setting. These controls change the same setting.
 
-After the first accepted position arrives, the vessel's **Signal K Live** panel in Wake Logger shows its latest position on a map together with SOG, COG, heading, depth and apparent wind when those values are available. The display refreshes as new telemetry arrives; missing optional sensors are shown as unavailable rather than preventing position tracking.
+On reconnecting, the latest position is sent promptly while stored history uploads in the background. With the supporting Wake Logger service update, your vessel view shows the percentage of stored history uploaded and an estimated time remaining once there is enough upload progress to measure. Estimates pause when the connection is lost. Detailed recording updates are available under **Upload details**. Wake Logger uses the recorded movement and times to identify trips; switching live tracking does not itself create a new trip. Missing or rejected readings are flagged rather than presented as a complete trip.
 
-The private live panel is read-only for vessel crew. Device pairing and management require the appropriate vessel role, while public live sharing is off by default and remains under the vessel owner's control. Live telemetry is for situational awareness and trip logging, not as a certified navigation display.
+**When you dock:** Tap **Finish trip** before switching off boat power. The plugin saves the trip’s actual final recorded sequence and capture time immediately, including offline and with Live tracking off. **Saved onboard · upload pending** is local success, not cloud confirmation. Keep power and Live tracking on until **Trip confirmed ready by cloud** appears if you need confirmation now; the same connection checks receipt coverage and processing. Otherwise the pending finish survives restart and uploads later. The automatic 15-minute stationary stop remains the fallback. Finish trip does not change the active Signal K route, and fresh movement can start a new recording.
 
-## Offline operation
+**Before a long outing:** Check available storage and your queue limits. The default limits are seven days or 250 MB, whichever is reached first. If a limit is reached, the oldest queued readings are discarded; plugin status reports the dropped count. The dropped count is a **lifetime** total across every upload, not the number lost from the current trip—losses that belong to the current upload are shown separately, and a recording affected by them is marked as not complete. Recording locally controls this plugin's Wake Logger connections only—it does not switch off other apps or your boat's internet access.
 
-The default queue retains up to seven days or 250 MB. Records have persistent device-scoped sequence numbers and checksums. MQTT broker acknowledgement is not enough to remove a record: Wake Logger must acknowledge that the database commit completed. If a configured limit is reached, the oldest backlog is discarded, the newest data is preserved, and the dropped count is shown in plugin status.
+## Bring your race course onboard
 
-Useful status examples include `Not paired`, `connecting`, `online`, `offline`, `degraded`, queue count/size, and dropped-record count. Enable telemetry debug logging only while troubleshooting; it does not log payloads or secrets.
+Select a saved race course for your vessel in Wake Logger while internet access is available. Check that the course has synchronised before departure. The downloaded course stays on the Signal K server and remains available offline.
 
-An authenticated Signal K administrator can call `POST /plugins/signalk-wakelogger/forget-credentials` to forget the local cloud credential before entering a fresh pairing code. This intentionally preserves the installation identity, consumed-code fingerprint, retired device outboxes, sequence records and diagnostics; it does not revoke the cloud association, so revoke it in Wake Logger as well when retiring a device. A forgotten pairing code must be replaced with a new one.
+Open the **Wake Logger webapp** from Signal K's Web Apps list, using a phone, tablet or computer connected to the boat's network. Sign in to Signal K if prompted. Any Signal K user account can view the onboard map; changing live tracking or activating a course requires an account with read/write access.
 
-Wake Logger administrators maintain approved telemetry profiles. Vessel Owners and First Mates can select one; other crew can see the selection but cannot change it. Navigation stays at its configured priority while depth and apparent wind can slow under constrained or offline conditions. Profile revisions and application results are visible to Wake Logger operations.
+The onboard map uses the same instrument styling as Wake Logger's live view, adapts to phone and tablet screens, and includes a full-screen view. It shows the complete course, your boat, the next mark and current leg. Distance, bearing, cross-track error, VMG and arrival estimates appear when Signal K can calculate them; unavailable readings are left clearly marked. Your recorded track is loaded from durable onboard storage when the page opens and then updated live, so reloading the app mid-passage still shows the whole trip rather than only the track since the page opened.
 
-## Development
+Alongside the map, the webapp shows an **onboard race plan**. While **Live tracking** is on, Wake Logger cloud calculates the remaining race: it starts the current leg from your boat's actual position, samples the downloaded forecast at each leg's estimated time, and accounts for current, so the suggested heading, sail plan and arrival estimate keep up with how the race is actually going. When **Live tracking** is off, the vessel performs the same calculation on board from the Race Pack synchronised before departure, so the plan is still available with no internet access. If no Race Pack has synchronised yet, the map and course still work and the plan is clearly marked as unavailable.
 
-```sh
-npm ci --ignore-scripts
-npm run check
-npm run test:docker
-```
+Use **Advance point** to move to the next course point, or select a point and choose **Set point** to correct your progress. When mark detection is set to Automatic, a detected rounding advances only on the device that has explicitly taken **Navigation control**; other phones or tablets stay viewers and never advance the course. Detection suggests or holds when it is unsure, and manual controls always win.
 
-The Docker test builds the exact local npm tarball and installs it in a pinned official Signal K image. It plays Signal K's sample NMEA 2000 stream through verified HTTPS pairing and TLS MQTT, then proves durable acknowledgement, current-state priority, offline buffering and recovery after an abrupt Signal K stop. All certificates, credentials, broker data and volumes are disposable and local to the test stack.
+Your course is also available as a standard Signal K route for other onboard applications. If another app selects a different active route, Wake Logger shows that state. Choose **Activate Wake Logger course** when you want to return to it.
 
-See the complete [refined implementation plan](docs/implementation-plan.md), [original-plan gap audit](docs/original-plan-gap-audit.md), [validation evidence](docs/validation.md), [development](docs/development.md), [release process](docs/release.md), [architecture](docs/architecture.md), [protocol](docs/telemetry-protocol.md), [pairing](docs/pairing.md), and [trip detection](docs/trip-detection.md). Security issues should follow [SECURITY.md](SECURITY.md).
+Before going offshore, check the onboard app's status. **Offline race ready** means the selected course has been applied, its Signal K route is active (and not reversed), a Race Pack that matches the course is stored with supported rules and a forecast valid now, and onboard sail planning will work with no internet. The app distinguishes a forecast that is merely valid now from one whose declared coverage spans the expected race window, and says so when it cannot confirm the whole window. If anything is missing the app says so; you can still switch Live tracking off for radio silence, but you will see a warning naming what is missing.
+
+## Watch your instruments with no course and no internet
+
+Open the **Wake Logger webapp** and choose the **Instruments** tab (the default when no course is selected). It reads directly from your boat's Signal K server and shows position, speed and course over ground, heading (true or magnetic), speed through water, depth (with its stated reference), and apparent and true wind, with units and a clear measured/derived label.
+
+Instrument readings are independent of the course, Race Pack, recording and cloud connection. Each reading tracks its own freshness, so a stale sensor is marked with its age while the others stay live, and a missing value is shown as unavailable rather than guessed. Wind-relative VMG is labelled separately from VMG to a waypoint (ground- and water-referenced where available). Viewing instruments on another phone or tablet is read-only by default: it will not activate a course, advance a mark, change upload mode or start a recording.
+
+## Prepare your map for offline use
+
+The onboard map can show your boat and course without internet access. Basemap coverage needs a little preparation:
+
+1. Install Signal K Charts and add local charts that you are licensed to use, such as a suitable MBTiles chart.
+2. In the Wake Logger webapp, select a **Chart source**.
+3. Choose the surrounding course margin and zoom range, then select **Verify local chart coverage**.
+4. Check the result before leaving coverage. Verification applies to the selected area and zoom range, not every possible view of the map.
+
+Verification checks existing local chart coverage; it does not download missing maps. Automatic online map downloads are not included in this release. An online chart working at the dock does not by itself mean it will work offshore.
+
+If chart tiles are unavailable, the map still shows your vessel, course and marks. You can fit the map to the course or centre it on your boat.
+
+## Your data and privacy
+
+Wake Logger records position and time, plus speed over ground, course over ground, heading, depth and apparent wind when supplied. Missing optional sensors do not prevent position tracking. This plugin does not collect engine, fuel or battery readings.
+
+Vessel roles and sharing settings in Wake Logger control who can see your data. Public live sharing is off by default and stays under the vessel owner's control.
+
+## If something is not working
+
+- **Not paired:** Generate a pairing code in Wake Logger and enter it in the plugin settings.
+- **Offline or waiting to upload:** Check **Upload mode**, your internet connection and the plugin's queue status. Leave the plugin running so it can record and retry.
+- **No vessel position:** Check that Signal K itself is receiving a valid position from your boat.
+- **Course not active:** Check whether another app selected a route. Reactivate the Wake Logger course when appropriate.
+- **Blank basemap:** Check your selected chart source and local coverage. Course and vessel information can still be displayed.
+- **Moving to a different Signal K server:** Use **Replace device** in Wake Logger. Use **Revoke association** when retiring an old connection; your existing trip history is retained.
+
+For help with your account, pairing or trips, contact support through [Wake Logger](https://wakelogger.com/). When reporting a problem, include your plugin version, Signal K version and the status shown—never your pairing code or credentials.
+
+See the **Changelog** tab for what's new in each release.

package/dist/config/defaults.d.ts

@@ -8,11 +8,13 @@ export declare const DEFAULTS: {
     readonly segmentBytes: number;
 };
 export interface PluginConfig {
+    uploadMode: 'automatic' | 'local_only';
     pairingCode?: string;
     pairingApiUrl: string;
     samplePeriodMs: number;
     maxOutboxMb: number;
     maxOutboxDays: number;
     debugTelemetry: boolean;
+    raceProgressionMode: 'auto' | 'suggest' | 'off';
 }
 export declare function parseConfig(value: object): PluginConfig;

package/dist/config/defaults.js

@@ -14,6 +14,7 @@ exports.DEFAULTS = {
 function parseConfig(value) {
     const input = value;
     return {
+        uploadMode: input.uploadMode === 'local_only' ? 'local_only' : 'automatic',
         pairingCode: typeof input.pairingCode === 'string' && input.pairingCode.trim() ? input.pairingCode.trim() : undefined,
         pairingApiUrl: typeof input.pairingApiUrl === 'string' && /^https:\/\//.test(input.pairingApiUrl)
             ? input.pairingApiUrl
@@ -21,7 +22,8 @@ function parseConfig(value) {
         samplePeriodMs: boundedNumber(input.samplePeriodMs, exports.DEFAULTS.samplePeriodMs, 250, 60_000),
         maxOutboxMb: boundedNumber(input.maxOutboxMb, 250, 10, 4096),
         maxOutboxDays: boundedNumber(input.maxOutboxDays, 7, 1, 30),
-        debugTelemetry: input.debugTelemetry === true
+        debugTelemetry: input.debugTelemetry === true,
+        raceProgressionMode: input.raceProgressionMode === 'suggest' || input.raceProgressionMode === 'off' ? input.raceProgressionMode : 'auto'
     };
 }
 function boundedNumber(value, fallback, min, max) {

package/dist/config/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":";;;AAmBA,kCAaC;AAhCY,QAAA,QAAQ,GAAG;IACtB,aAAa,EAAE,gDAAgD;IAC/D,cAAc,EAAE,IAAI;IACpB,SAAS,EAAE,EAAE;IACb,eAAe,EAAE,EAAE,GAAG,IAAI;IAC1B,cAAc,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IACjC,cAAc,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IACvC,YAAY,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI;CACrB,CAAA;AAWV,SAAgB,WAAW,CAAC,KAAa;IACvC,MAAM,KAAK,GAAG,KAAgC,CAAA;IAC9C,OAAO;QACL,WAAW,EAAE,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS;QACrH,aAAa,EACX,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC;YAChF,CAAC,CAAC,KAAK,CAAC,aAAa;YACrB,CAAC,CAAC,gBAAQ,CAAC,aAAa;QAC5B,cAAc,EAAE,aAAa,CAAC,KAAK,CAAC,cAAc,EAAE,gBAAQ,CAAC,cAAc,EAAE,GAAG,EAAE,MAAM,CAAC;QACzF,WAAW,EAAE,aAAa,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC;QAC5D,aAAa,EAAE,aAAa,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3D,cAAc,EAAE,KAAK,CAAC,cAAc,KAAK,IAAI;KAC9C,CAAA;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc,EAAE,QAAgB,EAAE,GAAW,EAAE,GAAW;IAC/E,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAA;AAC/G,CAAC"}
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":";;;AAqBA,kCAeC;AApCY,QAAA,QAAQ,GAAG;IACtB,aAAa,EAAE,gDAAgD;IAC/D,cAAc,EAAE,IAAI;IACpB,SAAS,EAAE,EAAE;IACb,eAAe,EAAE,EAAE,GAAG,IAAI;IAC1B,cAAc,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IACjC,cAAc,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IACvC,YAAY,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI;CACrB,CAAA;AAaV,SAAgB,WAAW,CAAC,KAAa;IACvC,MAAM,KAAK,GAAG,KAAgC,CAAA;IAC9C,OAAO;QACL,UAAU,EAAE,KAAK,CAAC,UAAU,KAAK,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW;QAC1E,WAAW,EAAE,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS;QACrH,aAAa,EACX,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC;YAChF,CAAC,CAAC,KAAK,CAAC,aAAa;YACrB,CAAC,CAAC,gBAAQ,CAAC,aAAa;QAC5B,cAAc,EAAE,aAAa,CAAC,KAAK,CAAC,cAAc,EAAE,gBAAQ,CAAC,cAAc,EAAE,GAAG,EAAE,MAAM,CAAC;QACzF,WAAW,EAAE,aAAa,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC;QAC5D,aAAa,EAAE,aAAa,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3D,cAAc,EAAE,KAAK,CAAC,cAAc,KAAK,IAAI;QAC7C,mBAAmB,EAAE,KAAK,CAAC,mBAAmB,KAAK,SAAS,IAAI,KAAK,CAAC,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC,MAAM;KACzI,CAAA;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc,EAAE,QAAgB,EAAE,GAAW,EAAE,GAAW;IAC/E,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAA;AAC/G,CAAC"}

package/dist/config/schema.d.ts

@@ -2,6 +2,14 @@ export declare const configSchema: {
     readonly type: "object";
     readonly additionalProperties: false;
     readonly properties: {
+        readonly uploadMode: {
+            readonly type: "string";
+            readonly title: "Upload mode";
+            readonly enum: readonly ["automatic", "local_only"];
+            readonly enumNames: readonly ["Automatic upload", "Record locally"];
+            readonly default: "automatic";
+            readonly description: "local_only records on this boat without any Wake Logger network traffic. Pair first. Save automatic when ready to upload the queue.";
+        };
         readonly pairingCode: {
             readonly type: "string";
             readonly title: "Wake Logger pairing code";
@@ -39,5 +47,13 @@ export declare const configSchema: {
             readonly title: "Enable telemetry debug logging";
             readonly default: false;
         };
+        readonly raceProgressionMode: {
+            readonly type: "string";
+            readonly title: "Mark detection mode";
+            readonly enum: readonly ["auto", "suggest", "off"];
+            readonly enumNames: readonly ["Automatic", "Suggest", "Off"];
+            readonly default: "auto";
+            readonly description: "Automatic advances the active course point when the onboard app detects a rounding, start or finish; it also records evidence for Wake Logger. Suggest asks the crew first. Off records evidence only.";
+        };
     };
 };

package/dist/config/schema.js

@@ -5,6 +5,14 @@ exports.configSchema = {
     type: 'object',
     additionalProperties: false,
     properties: {
+        uploadMode: {
+            type: 'string',
+            title: 'Upload mode',
+            enum: ['automatic', 'local_only'],
+            enumNames: ['Automatic upload', 'Record locally'],
+            default: 'automatic',
+            description: 'local_only records on this boat without any Wake Logger network traffic. Pair first. Save automatic when ready to upload the queue.'
+        },
         pairingCode: {
             type: 'string',
             title: 'Wake Logger pairing code',
@@ -41,6 +49,14 @@ exports.configSchema = {
             type: 'boolean',
             title: 'Enable telemetry debug logging',
             default: false
+        },
+        raceProgressionMode: {
+            type: 'string',
+            title: 'Mark detection mode',
+            enum: ['auto', 'suggest', 'off'],
+            enumNames: ['Automatic', 'Suggest', 'Off'],
+            default: 'auto',
+            description: 'Automatic advances the active course point when the onboard app detects a rounding, start or finish; it also records evidence for Wake Logger. Suggest asks the crew first. Off records evidence only.'
         }
     }
 };

package/dist/config/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":";;;AAAa,QAAA,YAAY,GAAG;IAC1B,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,0BAA0B;YACjC,WAAW,EAAE,qFAAqF;SACnG;QACD,aAAa,EAAE;YACb,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,iBAAiB;YACxB,OAAO,EAAE,gDAAgD;YACzD,OAAO,EAAE,WAAW;SACrB;QACD,cAAc,EAAE;YACd,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,gCAAgC;YACvC,OAAO,EAAE,GAAG;YACZ,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,IAAI;SACd;QACD,WAAW,EAAE;YACX,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,iCAAiC;YACxC,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,GAAG;SACb;QACD,aAAa,EAAE;YACb,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,kCAAkC;YACzC,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,CAAC;SACX;QACD,cAAc,EAAE;YACd,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,gCAAgC;YACvC,OAAO,EAAE,KAAK;SACf;KACF;CACO,CAAA"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":";;;AAAa,QAAA,YAAY,GAAG;IAC1B,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,aAAa;YACpB,IAAI,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;YACjC,SAAS,EAAE,CAAC,kBAAkB,EAAE,gBAAgB,CAAC;YACjD,OAAO,EAAE,WAAW;YACpB,WAAW,EAAE,qIAAqI;SACnJ;QACD,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,0BAA0B;YACjC,WAAW,EAAE,qFAAqF;SACnG;QACD,aAAa,EAAE;YACb,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,iBAAiB;YACxB,OAAO,EAAE,gDAAgD;YACzD,OAAO,EAAE,WAAW;SACrB;QACD,cAAc,EAAE;YACd,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,gCAAgC;YACvC,OAAO,EAAE,GAAG;YACZ,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,IAAI;SACd;QACD,WAAW,EAAE;YACX,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,iCAAiC;YACxC,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,GAAG;SACb;QACD,aAAa,EAAE;YACb,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,kCAAkC;YACzC,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,CAAC;SACX;QACD,cAAc,EAAE;YACd,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,gCAAgC;YACvC,OAAO,EAAE,KAAK;SACf;QACD,mBAAmB,EAAE;YACnB,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,qBAAqB;YAC5B,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC;YAChC,SAAS,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,KAAK,CAAC;YAC1C,OAAO,EAAE,MAAM;YACf,WAAW,EAAE,wMAAwM;SACtN;KACF;CACO,CAAA"}

package/dist/courses/course-store.d.ts

@@ -0,0 +1,19 @@
+import { NativeCourseService } from './native-course';
+import { type CourseAcknowledgement } from './protocol';
+export declare class CourseStore {
+    private readonly target;
+    private readonly native;
+    private snapshot;
+    private operation;
+    constructor(target: string, native: NativeCourseService);
+    open(): Promise<void>;
+    acknowledgement(): Promise<CourseAcknowledgement | undefined>;
+    status(): Promise<object>;
+    receive(payload: Buffer): Promise<CourseAcknowledgement>;
+    activate(): Promise<void>;
+    setMapReadiness(revision: unknown, status: unknown): Promise<void>;
+    close(): Promise<void>;
+    private activation;
+    private persist;
+    private exclusive;
+}