sailkick-boat 0.13.4 → 0.14.3

package/README.md

@@ -1,18 +1,20 @@
 # sailkick-boat
 
-> ## ⚠️ Project status: early alpha — no public service yet
+> ## ⚠️ Project status: early alpha — invite only
 >
-> This plugin is the **boat-side companion of the sailkick platform** (a self-hosted
-> 3D sailing app + a central telemetry sync server). **That platform is not publicly
-> available yet** — there is no public cloud endpoint to point this plugin at, and it
-> is currently developed and tested only against sailkick's own development
-> environment (a private LAN).
+> This plugin is the **boat-side companion of the sailkick platform**: **cloud
+> telemetry** (gapless boat→shore sync of your vessel's data into a central InfluxDB)
+> and a **local proxy that keeps the sailkick app and its charts/maps fully usable
+> offline** on board. The service runs at **[www.sailkick.io](https://www.sailkick.io)**.
 >
-> It is published this early for development visibility and for adventurous
-> **self-hosters**: to use it today you must run your own sailkick app server and
-> central InfluxDB v2. Expect breaking changes while the version is 0.x. If you found
-> this in the Signal K Appstore and don't run a sailkick server, it will not do
-> anything useful yet — watch the repo for the public launch.
+> **Registration is invite-only** and happens on the website, not in the plugin — so
+> installing this from the Signal K Appstore is not enough on its own. Expect breaking
+> changes while the version is 0.x.
+>
+> **Want an invite, or more information?** Get in touch:
+> **[info@sailkick.io](mailto:info@sailkick.io)**. Early testers are welcome.
+> Self-hosters can point the plugin at their own sailkick server and InfluxDB v2
+> instead — see [Config](#config).
 
 One Signal K plugin, independently-toggleable modules — so the boat stays
 "just SignalK + plugins":
@@ -79,7 +81,7 @@ POST /plugins/sailkick-boat/cache/clear                            # default kee
 POST /plugins/sailkick-boat/cache/clear?keep=tiles,terrain,history # refresh app shell; keep tiles + ring log
 POST /plugins/sailkick-boat/cache/clear?prefix=tiles/seamap        # nuke one tileset
 ```
-(The persistent history ring log lives under `<storeDir>/history`, so keep `history`
+(The persistent history ring log lives under `<dataDir>/history`, so keep `history`
 when clearing — the default keep already does. A hand-typed `find` clear should add
 `! -name history` alongside `! -name tiles ! -name terrain`.)
 
@@ -94,13 +96,14 @@ passage area on demand.
   `coastlineMaxZoom 8` (~12k tiles) + `seabedMaxZoom 6` (~5.5k). Idempotent (re-runs
   hit cache only) and self-throttling — it reuses the circuit breaker, so it goes quiet
   offline and resumes when back online. Progress shows in the plugin status line.
-  Config: `proxy.seed.{enabled,coastlineMaxZoom,seabedMaxZoom,concurrency}`.
+  Config: **Download a worldwide base map on start** (`seedEnabled`); zoom levels and
+  concurrency are constants (hand-editable as `proxy.seed.*`).
 - **Download around the boat** (settings dropdowns, no token) — the easiest way to
   cache a passage area: in Plugin Config pick a **Radius around boat** (25/50/100/200 nm)
   and a **Detail level** (Overview z12 … Harbor z15), then save. The plugin reads the
   boat's current position from local SignalK, builds a box, and warms the chart layers
   in the background (progress in the status line). Idempotent; re-saving tops up. An
-  oversized radius+detail is refused (reduce one). Config `proxy.prefetch.{radiusNm,detailZoom,concurrency}`.
+  oversized radius+detail is refused (reduce one). Config `prefetchRadiusNm` / `prefetchDetailZoom`.
 - **Region prefetch (API)** — for scripted/arbitrary boxes, warm the detailed chart layers for an area:
   ```
   POST /plugins/sailkick-boat/prefetch/region
@@ -123,8 +126,8 @@ cookie on HTTP, so login just loops. Since the boat is single-tenant and its dat
 endpoints aren't server-gated, the proxy serves `/api/config` with `auth.required`
 forced to `false` (and `historyAvailable` forced on when history is served locally),
 so the boat's own app opens with no password, fully offline. Everything else in the
-config passes through untouched. Toggle off with `proxy.openAccess: false` to keep
-the cloud login gate.
+config passes through untouched. (Hand-edit `proxy.openAccess: false` to keep the cloud
+login gate — there is no toggle, since the gate cannot complete over the mirror anyway.)
 
 ## Local history (offline Trends + track)
 Two ways, chosen automatically:
@@ -135,7 +138,7 @@ Two ways, chosen automatically:
   **SignalK on a Victron GX / Venus OS**. Same JSON contract, fully offline, no database.
   (`historyAvailable` reports true either way, so the app shows the Trends panel.)
   - **Persistent (append-log):** the ring is saved as a JSONL append-log at
-    `<storeDir>/history/history-ring.jsonl` (on the SSD/USB with the tiles; override with
+    `<dataDir>/history/history-ring.jsonl` (on the SSD/USB with the tiles; override with
     `proxy.history.ringDir`), so it **survives restarts**. Each sample appends one line; the file is
     compacted (atomic rewrite to the current window) only rarely, so a long passage
     writes < ~1 GB (vs the ~600 GB a full-rewrite snapshot would). Config
@@ -156,26 +159,57 @@ works **offline** with the boat's own data. Only when neither a local InfluxDB n
 telemetry is available do these paths **fall through to the cloud mirror**, so an
 online boat is never worse off than before.
 
-## Easiest setup: log in with your sailkick account
-Instead of pasting InfluxDB URL / org / bucket / write-token, fill the **Sailkick
-account** section — **host URL + slug + password** — and the plugin fetches the rest of
-its cloud config on start (`POST <host>/api/boat/config`): the scoped write token,
-bucket, org, and InfluxDB URL for your boat. The bundle is cached (0600) in the plugin
-data dir, so sync keeps working **offline** after the first connect. Leave the account
-section blank to configure `sync`/`proxy` manually (advanced / self-hosted). Account
-values take precedence over the manual sync fields; the mirror upstream (`sailkickUrl`)
-is set from the account host.
-
-## Config (each section toggleable)
-- **Telemetry sync → InfluxDB**: `enabled`, `influxUrl`, `org`, `bucket`, `token`, `spoolDir`, …
-- **Sailkick caching proxy**: `enabled`, `sailkickUrl` (the one upstream), `storeDir`, …
-  - `serveTelemetry` (default on) — provide `/ws/telemetry` from local SignalK.
-  - **Cache manifest** (default on): `path` (default `/api/cache-manifest`),
-    `pollIntervalSec` (default 300) — auto-refresh datasets when the cloud
-    announces a new bake.
-  - **Local history** (default on): `influxUrl` (default `http://127.0.0.1:8086`),
-    `org`, `bucket`, `token` (a read token — set to serve full history from a local
-    InfluxDB; blank = the DB-less telemetry ring), plus the ring settings above.
+## Setup: register on the web, then paste the token
+1. Register your boat at **[www.sailkick.io](https://www.sailkick.io)** (an invite code
+   is needed — see above). The signup screen shows your boat's ingest credentials.
+2. **Copy the "Write token"** — it is shown **once** and cannot be recovered. If you
+   lose it you need a new one minted.
+3. In Plugin Config, fill the **Sailkick account** section — **boat name + write
+   token** — and save.
+
+That is the whole handshake. The plugin resolves everything else locally (`bucket` =
+`<slug>_raw`, `org` = `sailkick`) and never calls the app for configuration, so setup
+works with no internet and there is nothing to re-fetch after a restart.
+
+> **Ignore the "Influx URL", "Organization" and "Bucket" on that screen** — they are for
+> the community `signalk-to-influxdb-v2` plugin. This plugin always writes to
+> `https://sync.sailkick.io`; the endpoint is fleet-wide and cannot be set from the UI,
+> so a wrong value can never redirect your telemetry. (Self-hosters: hand-edit
+> `sync.influxUrl` in the plugin config JSON.) If the status line ever warns that sync is
+> writing to a local address, telemetry is not leaving the boat.
+
+Registration deliberately happens **only** in the web app. The plugin cannot sign up,
+so there is no way to half-create an account or burn an invite from the boat.
+
+> Changing the token later — after a rotation, say — is just editing the field and
+> saving. Pasted values are trimmed, and the boat name is lower-cased for you.
+
+## Config
+The page is deliberately small — everything else has a right answer and is a constant
+in `index.js`.
+
+- **Sailkick account**: `slug` (boat name), `writeToken`
+- **Telemetry sync → cloud**: `enabled`
+- **Offline app & maps**: `enabled`, `proxyPort` (default 8080), `localSignalkUrl`
+  (default `http://127.0.0.1:3000`), `dataDir`, `seedEnabled`, `prefetchRadiusNm`,
+  `prefetchDetailZoom`, `historyToken`
+
+`dataDir` is the one storage location — cached maps, the telemetry spool and the
+history ring log all live under it. **Put it on the SSD/USB disk, not the SD card.**
+Leave it blank and each part falls back to its historical spot under the plugin data
+dir.
+
+`historyToken` is optional and only matters if the boat already runs its own InfluxDB.
+Blank — the normal case — uses the built-in DB-less ring.
+
+Cache-manifest polling is always on (no toggle): tile freshness comes from the cloud
+announcing bakes, and without it a re-baked dataset would never refresh.
+
+**Self-hosting / advanced.** Every module still reads its option before falling back to
+the constant, so anything removed from the page can be set by hand in
+`~/.signalk/plugin-config-data/sailkick-boat.json` — `sync.influxUrl`, `sync.token`,
+`proxy.sailkickUrl`, `proxy.seed.coastlineMaxZoom`, the ring window, the retry backoff,
+and so on. Values saved by earlier versions keep working after an upgrade.
 
 Point your chart app / browser at:
 `http://<boat>:3000/plugins/sailkick-boat/p/`
@@ -185,7 +219,17 @@ Point your chart app / browser at:
 cd ~/.signalk && npm install sailkick-boat   # or a packed tarball
 ```
 Enable + configure under **Server → Plugin Config → "Sailkick boat companion"**.
-Put `spoolDir`/`storeDir` on the SSD (or leave blank for the plugin data dir).
+Set **Data directory** to a path on the SSD (or leave blank for the plugin data dir).
+
+### Victron GX / Venus OS (Cerbo, Ekrano)
+Works on Venus OS Large (Signal K enabled). Point **Data directory** at USB/SD storage
+(internal flash is small). Leave the history token
+blank — the DB-less telemetry ring is used automatically. **Note:** a GX only sees
+Victron data (batteries, solar, tanks) by default; **position/wind/speed/depth
+require the boat's NMEA2000 backbone on the VE.Can port** (250 kbit/s N2K profile +
+a VE.Can↔Micro-C drop cable; leave the spare RJ45 unterminated) or a USB GPS/N2K
+gateway. Without a position source, the live boat / trends / area-download stay
+idle — energy telemetry still syncs to the cloud.
 
 ## Dev / tests
 ```bash
@@ -193,5 +237,11 @@ npm install && npm test   # proxy: mirror/cache/offline + Express route; sync: s
 ```
 Supersedes the separate `signalk-to-influxdb-gapless` + `signalk-tile-cache` plugins.
 
+## Contact
+Questions, feedback, or want to test the app on your own boat?
+Email **[info@sailkick.io](mailto:info@sailkick.io)** — happy to help with setup, and
+early testers are very welcome. Bug reports and feature requests are also fine as
+[GitHub issues](https://github.com/lauchat/sailkick-boat/issues).
+
 ## License
 MIT

package/index.js

@@ -1,16 +1,61 @@
 'use strict'
 
+const path = require('path')
+
 const { createSync } = require('./lib/sync')
 const { createProxy } = require('./lib/proxy')
 const { createTelemetry } = require('./lib/telemetry')
 const { createHistory } = require('./lib/history')
-const { resolveAccountConfig, accountConfigured } = require('./lib/account')
+const { resolveAccountConfig } = require('./lib/account')
 
 // sailkick-boat: one Signal K plugin, two independently-toggleable modules —
 //   sync : gapless store-and-forward of self telemetry to InfluxDB (data OUT)
 //   proxy: offline-first caching mirror of the sailkick host (data IN)
 // Kept as separate modules so a proxy fault can't wedge the data-critical sync.
 
+// Fixed cloud endpoints. Boats never choose these, so they are constants rather than
+// config fields — but every module still reads its option first (see startModules), so
+// a hand-edited plugin-config JSON can override any of them for self-hosting.
+const SAILKICK_APP_URL = 'https://www.sailkick.io' // signup + mirror upstream
+const SAILKICK_INFLUX_URL = 'https://sync.sailkick.io' // data egress; pairing overrides this
+
+// Tuning that has a right answer. Deliberately NOT on the config page: a boat owner has
+// no basis to choose these, and a wrong value silently degrades sync or the cache.
+const SYNC_TUNING = {
+  org: 'sailkick',
+  batchSize: 1000,
+  flushIntervalMs: 1000,
+  maxBufferBytes: 500 * 1024 * 1024,
+  subscribePeriodMs: 1000,
+  requestTimeoutMs: 30000,
+  retryMinMs: 1000,
+  retryMaxMs: 60000
+}
+const PROXY_TUNING = { requestTimeoutMs: 20000, localPaths: ['/signalk'], telemetryPath: '/ws/telemetry' }
+const MANIFEST = { enabled: true, path: '/api/cache-manifest', pollIntervalSec: 300 }
+const SEED_TUNING = { coastlineMaxZoom: 8, seabedMaxZoom: 6, concurrency: 4 }
+const PREFETCH_TUNING = { concurrency: 4 }
+const HISTORY_TUNING = {
+  influxUrl: 'http://127.0.0.1:8086',
+  org: 'signalk',
+  bucket: 'signalk',
+  requestTimeoutMs: 15000,
+  ringPersist: true,
+  ringWindowSec: 86400,
+  ringSampleSec: 15
+}
+
+// A *cloud* endpoint on loopback means telemetry never leaves the boat. On the wire it
+// is indistinguishable from a normal offline backlog — the spool just grows — so it has
+// to be called out explicitly. (The local history DB is legitimately on 127.0.0.1; this
+// check is only ever applied to the sync path.)
+function isLoopbackUrl (u) {
+  try {
+    const h = new URL(u).hostname.replace(/^\[|\]$/g, '')
+    return h === 'localhost' || h === '::1' || /^127\./.test(h)
+  } catch { return false }
+}
+
 module.exports = function (app) {
   let sync = null
   let proxy = null
@@ -18,13 +63,14 @@ module.exports = function (app) {
   let history = null
   let statusTimer = null
   let accountStatus = null
+  let syncWarning = null
 
   const plugin = {
     id: 'sailkick-boat',
     name: 'Sailkick boat companion',
     description:
-      'Boat-side sailkick: gapless telemetry sync to InfluxDB + an offline-first ' +
-      'caching mirror of the sailkick host. Each feature can be toggled on/off.'
+      'Boat-side sailkick: gapless telemetry sync to the cloud + an offline-first ' +
+      'caching mirror of the sailkick app. Each feature can be toggled on/off.'
   }
 
   plugin.schema = {
@@ -32,106 +78,47 @@ module.exports = function (app) {
     properties: {
       account: {
         type: 'object',
-        title: 'Sailkick account (auto-configure)',
-        description: 'Log in with your sailkick account and the plugin fetches its cloud config (write token, bucket, org, InfluxDB URL) automatically — no manual token entry. Leave blank to configure sync/mirror manually below. The last-good config is cached, so sync keeps working offline.',
+        title: 'Sailkick account',
+        description: 'Register your boat at www.sailkick.io first — the signup screen shows a write token. Paste it here together with your boat name. Keep that token safe: it is shown only once and cannot be recovered.',
         properties: {
-          sailkickUrl: { type: 'string', title: 'Sailkick host URL', description: 'e.g. https://app.sailkick.com — used for login and as the mirror upstream.' },
-          slug: { type: 'string', title: 'Boat slug (username)' },
-          password: { type: 'string', title: 'Password' }
+          slug: { type: 'string', title: 'Boat name', description: 'Exactly as registered on the website.' },
+          writeToken: { type: 'string', title: 'Write token', description: 'From the signup screen ("Write token"). Everything else — Influx URL, organization, bucket — is derived from it and your boat name.' }
         }
       },
       sync: {
         type: 'object',
-        title: 'Telemetry sync → InfluxDB',
+        title: 'Telemetry sync → cloud',
+        description: 'Send this vessel\'s data to your sailkick account. Buffered on disk, so an offline passage or a restart loses nothing. Requires pairing above.',
         properties: {
-          enabled: { type: 'boolean', title: 'Enable telemetry sync', default: true },
-          influxUrl: { type: 'string', title: 'InfluxDB URL' },
-          org: { type: 'string', title: 'Organization', default: 'sailkick' },
-          bucket: { type: 'string', title: 'Bucket (your <slug>_raw)' },
-          token: { type: 'string', title: 'Write token (scoped to your bucket)' },
-          spoolDir: { type: 'string', title: 'Buffer directory', description: 'Default: plugin data dir. Put on the SSD.' },
-          batchSize: { type: 'number', title: 'Batch size (points/file)', default: 1000 },
-          flushIntervalMs: { type: 'number', title: 'Flush interval (ms)', default: 1000 },
-          maxBufferBytes: { type: 'number', title: 'Max on-disk buffer (bytes)', default: 524288000 },
-          subscribePeriodMs: { type: 'number', title: 'Min interval per path (ms)', default: 1000 },
-          requestTimeoutMs: { type: 'number', title: 'Upload timeout (ms)', default: 30000 },
-          retryMinMs: { type: 'number', title: 'Retry backoff min (ms)', default: 1000 },
-          retryMaxMs: { type: 'number', title: 'Retry backoff max (ms)', default: 60000 }
+          enabled: { type: 'boolean', title: 'Enable telemetry sync', default: true }
         }
       },
       proxy: {
         type: 'object',
-        title: 'Sailkick caching proxy',
+        title: 'Offline app & maps',
+        description: 'Serve the sailkick app on board — charts, trends and live data keep working with no internet.',
         properties: {
-          enabled: { type: 'boolean', title: 'Enable caching proxy', default: true },
-          serveTelemetry: { type: 'boolean', title: 'Serve /ws/telemetry from local SignalK', description: 'Provide the app\'s telemetry bus from the boat\'s SignalK, so the app uses the same contract as the cloud server.', default: true },
-          openAccess: { type: 'boolean', title: 'No login on the boat', description: 'Serve /api/config with the cloud login disabled, so the boat\'s own app opens without a password (single-tenant, offline-first). Turn off to keep the cloud login gate.', default: true },
-          sailkickUrl: { type: 'string', title: 'Sailkick host URL', description: 'The one upstream this boat mirrors (usually set automatically from the account section). e.g. https://app.sailkick.com' },
-          proxyPort: { type: 'number', title: 'Mirror server port', description: 'Standalone HTTP server serving the mirror at origin root (no SignalK auth). With host networking it is directly on the Pi. 0 = disable.', default: 8080 },
-          localSignalkUrl: { type: 'string', title: 'Local SignalK URL (live telemetry)', description: 'Live data + WebSocket stream are proxied here (not cached, not mirrored).', default: 'http://127.0.0.1:3000' },
-          localPaths: { type: 'array', title: 'Paths served by LOCAL SignalK', description: 'Prefixes routed to local SignalK instead of the mirror.', items: { type: 'string' }, default: ['/signalk'] },
-          storeDir: { type: 'string', title: 'Cache directory', description: 'Default: plugin data dir. Put on the SSD.' },
-          requestTimeoutMs: { type: 'number', title: 'Fetch timeout (ms)', default: 20000 },
-          manifest: {
-            type: 'object',
-            title: 'Auto-refresh on new bakes (cache manifest)',
-            description: 'Poll the cloud\'s bake manifest so tiles/app refresh lazily when a dataset is re-baked. Tiles are otherwise pinned (never expire by time).',
-            properties: {
-              enabled: { type: 'boolean', title: 'Poll the cache manifest', default: true },
-              path: { type: 'string', title: 'Manifest path on the sailkick host', default: '/api/cache-manifest' },
-              pollIntervalSec: { type: 'number', title: 'Poll interval (s)', default: 300 }
-            }
+          enabled: { type: 'boolean', title: 'Enable the offline mirror', default: true },
+          proxyPort: { type: 'number', title: 'Mirror port', description: 'Open the app at http://<boat>:<port>/. 0 = disable the standalone server.', default: 8080 },
+          localSignalkUrl: { type: 'string', title: 'Local SignalK URL', description: 'Where this plugin reaches SignalK for live data. Change only if SignalK is not on the default port.', default: 'http://127.0.0.1:3000' },
+          dataDir: { type: 'string', title: 'Data directory', description: 'Where cached maps, the telemetry buffer and local history live. Put this on the SSD/USB disk — not the SD card. Blank = the plugin data dir.' },
+          seedEnabled: { type: 'boolean', title: 'Download a worldwide base map on start', description: 'Caches a low-zoom coastline + seabed base (~17k tiles) so a usable map exists offline everywhere. Runs once, resumes if interrupted.', default: true },
+          prefetchRadiusNm: {
+            type: 'number',
+            title: 'Download detailed charts around the boat',
+            description: 'On save, caches the full chart detail for this radius around the boat\'s current position. Progress shows in the status line.',
+            enum: [0, 25, 50, 100, 200],
+            enumNames: ['Off', '25 nm', '50 nm', '100 nm', '200 nm'],
+            default: 0
           },
-          history: {
-            type: 'object',
-            title: 'Local history (app Trends panel + track)',
-            description: 'Serve the app\'s /api/history endpoints locally so trends + track work offline. With a read token → full history from a local InfluxDB. Without one → a DB-less ~1h ring sampled from live telemetry (e.g. SignalK on a Victron GX with no InfluxDB).',
-            properties: {
-              enabled: { type: 'boolean', title: 'Serve /api/history locally', default: true },
-              influxUrl: { type: 'string', title: 'Local InfluxDB URL', default: 'http://127.0.0.1:8086' },
-              org: { type: 'string', title: 'Organization', default: 'signalk' },
-              bucket: { type: 'string', title: 'Bucket', default: 'signalk' },
-              token: { type: 'string', title: 'Read token (scoped to the bucket)', description: 'Set to serve full history from a local InfluxDB. Leave blank to use the DB-less live-telemetry ring (Victron GX / no InfluxDB).' },
-              requestTimeoutMs: { type: 'number', title: 'Query timeout (ms)', default: 15000 },
-              ringPersist: { type: 'boolean', title: 'Persist the DB-less ring across restarts', description: 'Append-log in the plugin data dir. Off = in-memory only (lost on restart). Ignored when a token is set (InfluxDB is used).', default: true },
-              ringWindowSec: { type: 'number', title: 'DB-less ring window (s)', description: 'How much history the ring keeps: 86400 = 24h (default), up to 2592000 = 30d for long passages. Resolution auto-coarsens for large windows. NB: the app currently caps history requests at 24h.', default: 86400 },
-              ringSampleSec: { type: 'number', title: 'DB-less ring sample interval (s)', description: 'Auto-raised for large windows so the ring stays bounded (~50k samples).', default: 15 },
-              ringDir: { type: 'string', title: 'Ring log directory (override)', description: 'Where the persistent ring log lives. Default: a "history" folder under the cache directory (storeDir), so it sits on the SSD/USB with the tiles. Set to override.' }
-            }
+          prefetchDetailZoom: {
+            type: 'number',
+            title: '…at this detail level',
+            enum: [12, 13, 14, 15],
+            enumNames: ['Overview (z12)', 'Coastal (z13)', 'Detailed (z14)', 'Harbor (z15)'],
+            default: 13
           },
-          seed: {
-            type: 'object',
-            title: 'Offline base seed (global coastline + seabed)',
-            description: 'On start, cache a worldwide low-zoom base so a usable map exists offline everywhere. Idempotent; self-throttles when offline. Enable the "Coastline"/depth layers in the app to see it.',
-            properties: {
-              enabled: { type: 'boolean', title: 'Seed the global base on start', default: true },
-              coastlineMaxZoom: { type: 'number', title: 'Coastline max zoom', description: 'Sparse vector coastline z0..N (z8 ≈ 12k tiles).', default: 8 },
-              seabedMaxZoom: { type: 'number', title: 'Seabed (bathy) max zoom', description: 'Dense depth raster z0..N (z6 ≈ 5.5k tiles).', default: 6 },
-              concurrency: { type: 'number', title: 'Parallel fetches', default: 4 }
-            }
-          },
-          prefetch: {
-            type: 'object',
-            title: 'Offline area download (around the boat)',
-            description: 'On save, cache the detailed chart layers for a radius around the boat\'s current position (from local SignalK), so a passage area is fully offline. Progress shows in the status line above.',
-            properties: {
-              radiusNm: {
-                type: 'number',
-                title: 'Radius around boat',
-                enum: [0, 25, 50, 100, 200],
-                enumNames: ['Off', '25 nm', '50 nm', '100 nm', '200 nm'],
-                default: 0
-              },
-              detailZoom: {
-                type: 'number',
-                title: 'Detail level',
-                enum: [12, 13, 14, 15],
-                enumNames: ['Overview (z12)', 'Coastal (z13)', 'Detailed (z14)', 'Harbor (z15)'],
-                default: 13
-              },
-              concurrency: { type: 'number', title: 'Parallel fetches', default: 4 }
-            }
-          }
+          historyToken: { type: 'string', title: 'Local InfluxDB read token (optional)', description: 'Only if this boat already runs its own InfluxDB (e.g. signalk-to-influxdb-v2) and you want full history from it. Leave blank — the plugin then keeps its own lightweight history, which is what most boats want.' }
         }
       }
     }
@@ -139,59 +126,135 @@ module.exports = function (app) {
 
   plugin.start = function (options) {
     const opts = options || {}
-    // If a sailkick account is configured, fetch the cloud config first (write token,
-    // bucket, org, InfluxDB URL) and merge it in — then start the modules. Otherwise
-    // start immediately with the manually-entered config (unchanged behaviour).
-    ;(async () => {
-      if (accountConfigured(opts.account)) {
-        const r = await resolveAccountConfig(app, opts.account)
-        if (r.bundle) {
-          opts.sync = { ...(opts.sync || {}), influxUrl: r.bundle.influxUrl, org: r.bundle.org, bucket: r.bundle.bucket, token: r.bundle.writeToken }
-          opts.proxy = { ...(opts.proxy || {}), sailkickUrl: opts.account.sailkickUrl }
-          accountStatus = `account: ${opts.account.slug} (${r.source})`
-        } else {
-          accountStatus = `account: ${opts.account.slug} — no config (${r.error || 'not reachable, no cache'})`
-        }
-      }
-      startModules(opts)
-    })().catch((e) => (app.error || console.error)('[sailkick-boat] start failed: ' + e.message))
+    try {
+      // Purely local: the boat registers on the website, the owner pastes the write
+      // token here. Nothing to fetch, so nothing that can fail while offline.
+      const r = resolveAccountConfig(app, opts.account)
+      if (r.bundle) accountStatus = `account: ${r.bundle.slug}`
+      else if (r.error) accountStatus = `account: ${r.error}`
+      else accountStatus = 'account: not configured — register at www.sailkick.io, then paste your write token'
+      startModules(opts, r.bundle)
+    } catch (e) {
+      (app.error || console.error)('[sailkick-boat] start failed: ' + e.message)
+    }
   }
 
-  function startModules (opts) {
+  function startModules (opts, bundle) {
+    const s = opts.sync || {}
+    const p = opts.proxy || {}
+    const b = bundle || {}
+    // One "Data directory" now drives cache + spool + ring log. `storeDir` is its
+    // pre-0.14 name — keep honouring it so an upgrade doesn't strand an existing tile
+    // cache. When nothing is set we pass undefined and let each module apply its own
+    // historical default (<pluginData>/store, <pluginData>/spool), so an upgrade never
+    // orphans a populated cache or a spool full of unsent telemetry.
+    const store = p.dataDir || p.storeDir || undefined
+    const spoolDir = s.spoolDir || (p.dataDir ? path.join(p.dataDir, 'spool') : undefined)
+
     // --- sync module (isolated: its failure must not affect the proxy) ---
-    if (opts.sync && opts.sync.enabled !== false && opts.sync.influxUrl) {
-      try { sync = createSync(app, opts.sync); sync.start() } catch (e) {
+    // Pairing wins over hand-written fields; hand-written fields win over the constants.
+    if (s.enabled !== false) {
+      const syncOpts = {
+        ...SYNC_TUNING,
+        // The cloud endpoint is fleet-wide and fixed. A pasted or cached bundle can
+        // never set it — the app's signup screen hands out its own http://localhost:8086,
+        // and a boat that believed it would spool to loopback forever, looking healthy.
+        // `sync.influxUrl` survives only as a self-hosting escape hatch: it is not in
+        // the schema, so it cannot arrive by pasting, only by editing the config JSON.
+        influxUrl: s.influxUrl || SAILKICK_INFLUX_URL,
+        org: b.org || s.org || SYNC_TUNING.org,
+        bucket: b.bucket || s.bucket,
+        token: b.writeToken || s.token,
+        spoolDir,
+        batchSize: s.batchSize || SYNC_TUNING.batchSize,
+        flushIntervalMs: s.flushIntervalMs || SYNC_TUNING.flushIntervalMs,
+        maxBufferBytes: s.maxBufferBytes || SYNC_TUNING.maxBufferBytes,
+        subscribePeriodMs: s.subscribePeriodMs || SYNC_TUNING.subscribePeriodMs,
+        requestTimeoutMs: s.requestTimeoutMs || SYNC_TUNING.requestTimeoutMs,
+        retryMinMs: s.retryMinMs || SYNC_TUNING.retryMinMs,
+        retryMaxMs: s.retryMaxMs || SYNC_TUNING.retryMaxMs
+      }
+      if (isLoopbackUrl(syncOpts.influxUrl)) {
+        syncWarning = `sync: ⚠ writing to ${syncOpts.influxUrl} — telemetry is NOT reaching the cloud`
+        ;(app.error || console.error)(`[sailkick-boat] sync target ${syncOpts.influxUrl} is a local address — telemetry will not reach the cloud`)
+      }
+      try { sync = createSync(app, syncOpts); sync.start() } catch (e) {
         (app.error || console.error)('[sailkick-boat] sync start failed: ' + e.message)
         sync = null
       }
     }
 
     // --- proxy module (+ /ws/telemetry provider and /api/history from local sources) ---
-    if (!opts.proxy || opts.proxy.enabled !== false) {
-      const pOpts = { ...(opts.proxy || {}) }
-      if (pOpts.serveTelemetry !== false) {
+    if (p.enabled !== false) {
+      const oldSeed = p.seed || {}
+      const oldPrefetch = p.prefetch || {}
+      const oldHistory = p.history || {}
+      const pOpts = {
+        sailkickUrl: p.sailkickUrl || SAILKICK_APP_URL,
+        storeDir: store,
+        proxyPort: p.proxyPort == null ? 8080 : p.proxyPort,
+        localSignalkUrl: p.localSignalkUrl || 'http://127.0.0.1:3000',
+        localPaths: (p.localPaths && p.localPaths.length) ? p.localPaths : PROXY_TUNING.localPaths,
+        telemetryPath: p.telemetryPath || PROXY_TUNING.telemetryPath,
+        requestTimeoutMs: p.requestTimeoutMs || PROXY_TUNING.requestTimeoutMs,
+        openAccess: p.openAccess !== false, // single-tenant boat: the cloud login gate can't work over plain HTTP
+        manifest: MANIFEST, // always on — freshness comes from the cloud announcing bakes
+        seed: {
+          ...SEED_TUNING,
+          // Never seed an unpaired boat: it would pull ~17k tiles from a host this
+          // install has no account on, and retry forever behind the circuit breaker.
+          // Pair first, then the worldwide base downloads on the next start.
+          enabled: !!b.writeToken && (p.seedEnabled != null ? p.seedEnabled !== false : oldSeed.enabled !== false),
+          coastlineMaxZoom: oldSeed.coastlineMaxZoom || SEED_TUNING.coastlineMaxZoom,
+          seabedMaxZoom: oldSeed.seabedMaxZoom || SEED_TUNING.seabedMaxZoom,
+          concurrency: oldSeed.concurrency || SEED_TUNING.concurrency
+        },
+        prefetch: {
+          radiusNm: p.prefetchRadiusNm != null ? p.prefetchRadiusNm : oldPrefetch.radiusNm,
+          detailZoom: p.prefetchDetailZoom != null ? p.prefetchDetailZoom : oldPrefetch.detailZoom,
+          concurrency: oldPrefetch.concurrency || PREFETCH_TUNING.concurrency
+        },
+        history: {
+          ...HISTORY_TUNING,
+          enabled: oldHistory.enabled !== false,
+          influxUrl: oldHistory.influxUrl || HISTORY_TUNING.influxUrl,
+          org: oldHistory.org || HISTORY_TUNING.org,
+          bucket: oldHistory.bucket || HISTORY_TUNING.bucket,
+          token: p.historyToken || oldHistory.token || '',
+          ringPersist: oldHistory.ringPersist !== false,
+          ringWindowSec: oldHistory.ringWindowSec || HISTORY_TUNING.ringWindowSec,
+          ringSampleSec: oldHistory.ringSampleSec || HISTORY_TUNING.ringSampleSec,
+          ringDir: oldHistory.ringDir
+        }
+      }
+
+      if (p.serveTelemetry !== false) {
         try {
           telemetry = createTelemetry(app, {})
           telemetry.start()
-          pOpts.telemetryUpgrade = (req, s, h) => telemetry.handleUpgrade(req, s, h)
+          pOpts.telemetryUpgrade = (req, sock, head) => telemetry.handleUpgrade(req, sock, head)
         } catch (e) {
           (app.error || console.error)('[sailkick-boat] telemetry start failed: ' + e.message)
           telemetry = null
         }
       }
-      if (!pOpts.history || pOpts.history.enabled !== false) {
+      if (pOpts.history.enabled !== false) {
         try {
-          // ringSource = the telemetry module: when no local InfluxDB is configured
-          // (e.g. a Victron GX), history serves a DB-less ring from live telemetry.
-          // storeDir lets the persistent ring log default onto the SSD with the tiles.
-          history = createHistory(app, { ...(pOpts.history || {}), ringSource: telemetry, storeDir: pOpts.storeDir })
+          // ringSource = the telemetry module: when no local InfluxDB token is set
+          // (the common case, e.g. a Victron GX), history serves a DB-less ring from
+          // live telemetry. storeDir puts the persistent ring log on the SSD.
+          history = createHistory(app, { ...pOpts.history, ringSource: telemetry, storeDir: store })
           history.start()
           pOpts.history = history // proxy dispatches /api/history to it when available()
         } catch (e) {
           (app.error || console.error)('[sailkick-boat] history start failed: ' + e.message)
           history = null
+          pOpts.history = null
         }
+      } else {
+        pOpts.history = null
       }
+
       try { proxy = createProxy(app, pOpts); proxy.start() } catch (e) {
         (app.error || console.error)('[sailkick-boat] proxy start failed: ' + e.message)
         proxy = null
@@ -206,6 +269,7 @@ module.exports = function (app) {
     if (!app.setPluginStatus) return
     const parts = []
     if (accountStatus) parts.push(accountStatus)
+    if (syncWarning) parts.push(syncWarning)
     if (sync) parts.push(sync.status())
     if (proxy) parts.push(proxy.status())
     if (telemetry) parts.push(telemetry.status())
@@ -225,6 +289,7 @@ module.exports = function (app) {
     history = null
     proxy = null
     accountStatus = null
+    syncWarning = null
   }
 
   // Mounted by Signal K at /plugins/sailkick-boat. Handlers dispatch to the live

package/lib/account/index.js

@@ -1,65 +1,87 @@
 'use strict'
 
-// Sailkick account auto-config. Instead of pasting InfluxDB URL/org/bucket/write-token
-// into the plugin, the owner enters host + slug + password; on start the plugin POSTs
-// them to the sailkick app's /api/boat/config and gets its cloud config back. The
-// last-good bundle is cached (0600) so sync keeps working offline after the first
-// connect. Dependency-free; never throws.
+// Sailkick account config — a pure local resolver, no network.
+//
+// Registration happens in the web app: the user redeems an invite there, and the
+// signup screen shows the boat's ingest credentials once (see the app's
+// public/ui/login-overlay.js). They paste the write token into this plugin, and that
+// is the whole handshake. The plugin deliberately does NOT sign up on its own —
+// one registration path means no half-created accounts and no spent-invite dead ends.
+//
+// Everything else about the bundle is derivable, so only two fields are asked for:
+//   bucket = "<slug>_raw"   (the app's convention — server/auth/registry.js bucketFor)
+//   org    = "sailkick"     (single org, fleet-wide)
+//
+// This bundle deliberately carries NO Influx URL. "Which boat am I" and "where is the
+// cloud" are separate questions, and the second one has a single fleet-wide answer that
+// index.js owns. Letting a pasted or cached value set the host is how telemetry ends up
+// spooling to a loopback address forever while the status line looks healthy — the app's
+// signup screen has been handing out its own internal http://localhost:8086.
+//
+// NB the write token cannot be re-fetched: the app shows it once at signup and never
+// stores it (registry.js keeps only passwordHash + influxReadToken). Losing it means
+// minting a new one, so the pasted value is the source of truth here.
 
 const fs = require('fs')
 const path = require('path')
 
-function accountConfigured (account) {
-  return !!(account && account.sailkickUrl && account.slug && account.password)
-}
+const DEFAULT_ORG = 'sailkick'
 
 function cacheFileFor (app) {
   const dataDir = (app.getDataDirPath && app.getDataDirPath()) || '.'
   return path.join(dataDir, 'account.json')
 }
 
+// Legacy/manual escape hatch: a hand-written (or pre-0.14.2) account.json still works,
+// so an install that was set up before the token field existed keeps syncing. Any
+// influxUrl in such a file is dropped — those were copied off the signup screen, which
+// was showing the server's own loopback address.
 function readCache (file) {
   try {
     const j = JSON.parse(fs.readFileSync(file, 'utf8'))
-    return (j && j.writeToken) ? j : null
+    if (!j || !j.writeToken) return null
+    const { influxUrl, ...rest } = j
+    return rest
   } catch { return null }
 }
 
-function writeCache (file, bundle) {
-  try {
-    fs.mkdirSync(path.dirname(file), { recursive: true })
-    const tmp = `${file}.tmp-${process.pid}`
-    fs.writeFileSync(tmp, JSON.stringify(bundle), { mode: 0o600 })
-    fs.renameSync(tmp, file)
-  } catch {}
-}
+const clean = (v) => String(v == null ? '' : v).trim()
 
-// Returns { bundle, source: 'live'|'cache'|null, error? }.
-// bundle = { influxUrl, org, bucket, writeToken, readToken }.
-async function resolveAccountConfig (app, account, opts = {}) {
-  const timeoutMs = opts.timeoutMs || 15000
-  const file = cacheFileFor(app)
-  const url = String(account.sailkickUrl).replace(/\/+$/, '') + '/api/boat/config'
-  const fallback = (error) => { const c = readCache(file); return { bundle: c, source: c ? 'cache' : null, error } }
-  try {
-    const resp = await fetch(url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ slug: account.slug, password: account.password }),
-      signal: AbortSignal.timeout(timeoutMs)
-    })
-    if (!resp.ok) {
-      const body = await resp.text().catch(() => '')
-      return fallback(`HTTP ${resp.status}: ${body.slice(0, 120)}`) // offline-safe: keep the cached bundle
+// Returns one of:
+//   { bundle, source: 'config' }   token pasted into the plugin config
+//   { bundle, source: 'cache' }    from a hand-written/legacy account.json
+//   { bundle: null, source: null, error? }
+//
+// bundle = { slug, org, bucket, writeToken } — no influxUrl by design, see above.
+function resolveAccountConfig (app, account) {
+  const acct = account || {}
+  const slug = clean(acct.slug).toLowerCase()
+  const writeToken = clean(acct.writeToken)
+
+  if (slug && writeToken) {
+    return {
+      source: 'config',
+      bundle: {
+        slug,
+        org: clean(acct.org) || DEFAULT_ORG,
+        bucket: clean(acct.bucket) || `${slug}_raw`,
+        writeToken
+      }
     }
-    const j = await resp.json().catch(() => null)
-    if (!j || j.ok === false || !j.writeToken) return fallback('unexpected /api/boat/config response')
-    const bundle = { influxUrl: j.influxUrl, org: j.org, bucket: j.bucket, writeToken: j.writeToken, readToken: j.readToken }
-    writeCache(file, bundle)
-    return { bundle, source: 'live' }
-  } catch (e) {
-    return fallback(e.message) // offline / unreachable → use the cached bundle
   }
+
+  const cached = readCache(cacheFileFor(app))
+  if (cached) return { bundle: cached, source: 'cache' }
+
+  // Half-filled: say which half, so the status line is actionable.
+  if (writeToken) return { bundle: null, source: null, error: 'boat name is missing' }
+  if (slug) return { bundle: null, source: null, error: 'write token is missing' }
+  return { bundle: null, source: null }
+}
+
+// True when sync has credentials to work with.
+function accountConfigured (app, account) {
+  return !!resolveAccountConfig(app, account).bundle
 }
 
-module.exports = { resolveAccountConfig, accountConfigured }
+module.exports = { resolveAccountConfig, accountConfigured, cacheFileFor, DEFAULT_ORG }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sailkick-boat",
-  "version": "0.13.4",
-  "description": "EARLY ALPHA — boat-side companion for the sailkick platform (not yet publicly available; self-hosters only). Gapless telemetry sync to InfluxDB, offline-first caching mirror of the sailkick host, and local telemetry + history endpoints from the boat's own data.",
+  "version": "0.14.3",
+  "description": "EARLY ALPHA — cloud telemetry + offline maps for sailkick boats (www.sailkick.io; register on the web, paste the write token). Gapless boat→cloud telemetry sync to InfluxDB, and a local proxy that keeps the sailkick app and its charts/maps working fully offline on board.",
   "main": "index.js",
   "scripts": {
     "test": "node --test"