sailkick-boat 0.13.4 → 0.14.1

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.
+> **Pairing needs an invite code** — there is no open registration yet, so installing
+> this plugin 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,43 @@ 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: pair the boat once
+Fill the **Sailkick account** section — **invite code + boat name + password** — and
+save. The plugin calls the app's `POST /api/auth/signup` once: that creates your
+account, provisions its cloud storage, and returns the write token, bucket, org and
+InfluxDB URL for your boat. The bundle is cached (0600) in the plugin data dir and
+reused on every later start, so sync keeps working **offline** and across restarts.
+
+Pairing is **one-time by design** — the invite code is single-use, so the plugin never
+calls signup twice. Once `account.json` exists the account fields are no longer read;
+delete that file to re-pair (which needs a fresh invite).
+
+## Config
+The page is deliberately small — everything else has a right answer and is a constant
+in `index.js`.
+
+- **Sailkick account**: `invite`, `slug` (boat name), `password`
+- **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 +205,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 +223,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,50 @@
 '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
+}
+
 module.exports = function (app) {
   let sync = null
   let proxy = null
@@ -23,8 +57,8 @@ module.exports = function (app) {
     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 +66,48 @@ 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 (one-time pairing)',
+        description: 'Pair this boat with your sailkick account once. The plugin creates the account, provisions its cloud storage, and stores the result locally — so it keeps syncing offline and after restarts. Your invite code is single-use; once paired these fields are no longer read.',
         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' }
+          invite: { type: 'string', title: 'Invite code' },
+          slug: { type: 'string', title: 'Boat name', description: '2–40 characters: lowercase letters, numbers, dashes. This is your permanent boat id.' },
+          password: { type: 'string', title: 'Password', description: 'At least 8 characters.' }
         }
       },
       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 }
-            }
-          },
-          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.' }
-            }
+          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
           },
-          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 }
-            }
+          prefetchDetailZoom: {
+            type: 'number',
+            title: '…at this detail level',
+            enum: [12, 13, 14, 15],
+            enumNames: ['Overview (z12)', 'Coastal (z13)', 'Detailed (z14)', 'Harbor (z15)'],
+            default: 13
           },
-          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 +115,132 @@ 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).
+    // Pairing first: on the very first start this provisions the account and caches the
+    // bundle; on every later start it is a disk read (see lib/account — signup is
+    // single-use and must never run twice).
     ;(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'})`
-        }
+      const r = await resolveAccountConfig(app, opts.account, { appUrl: SAILKICK_APP_URL })
+      if (r.bundle) {
+        accountStatus = r.source === 'paired'
+          ? `account: paired as ${r.bundle.slug}`
+          : `account: ${r.bundle.slug}`
+      } else if (r.error) {
+        accountStatus = `account: pairing failed — ${r.error}${r.terminal ? '' : ' (will retry on restart)'}`
+        ;(app.error || console.error)('[sailkick-boat] pairing failed: ' + r.error)
+      } else {
+        accountStatus = 'account: not paired — enter your invite code'
       }
-      startModules(opts)
+      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,
+        influxUrl: b.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
+      }
+      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

package/lib/account/index.js

@@ -1,17 +1,26 @@
 '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 pairing — ONE TIME, then cached forever.
+//
+// The owner enters an invite code + boat name + password once. The plugin POSTs them to
+// the app's /api/auth/signup, which provisions the boat's InfluxDB bucket + write token
+// and returns an `ingest` bundle. That bundle is cached (0600) in the plugin data dir
+// and reused on every subsequent start.
+//
+// Cache-first is NOT an optimisation here, it is correctness: signup consumes a
+// single-use invite and creates the account, so calling it twice returns 403
+// bad-invite / 409 slug-taken. The cached bundle is the only repeatable path —
+// /auth/login issues a session cookie but no token, and the app never persists the
+// write token, so there is nothing to re-fetch.
+//
+// Dependency-free; never throws.
 
 const fs = require('fs')
 const path = require('path')
 
-function accountConfigured (account) {
-  return !!(account && account.sailkickUrl && account.slug && account.password)
-}
+// Terminal = re-running with the same input can only fail the same way; the owner has
+// to change something (new invite, different boat name, longer password).
+const TERMINAL_CODES = new Set(['bad-invite', 'slug-taken', 'bad-slug', 'weak-password'])
 
 function cacheFileFor (app) {
   const dataDir = (app.getDataDirPath && app.getDataDirPath()) || '.'
@@ -34,32 +43,71 @@ function writeCache (file, bundle) {
   } catch {}
 }
 
-// Returns { bundle, source: 'live'|'cache'|null, error? }.
-// bundle = { influxUrl, org, bucket, writeToken, readToken }.
+// True when we could pair right now (nothing cached yet, but all three fields present).
+function pairable (account) {
+  return !!(account && account.invite && account.slug && account.password)
+}
+
+// Returns one of:
+//   { bundle, source: 'cache' }             already paired — no network call was made
+//   { bundle, source: 'paired' }            just provisioned; bundle now cached
+//   { bundle: null, source: null }          not configured (nothing to do)
+//   { bundle: null, source: null, error, terminal }   pairing attempted and failed
+//
+// bundle = { slug, influxUrl, org, bucket, writeToken }
 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 } }
+
+  const cached = readCache(file)
+  if (cached) return { bundle: cached, source: 'cache' } // paired already — never call signup again
+
+  if (!pairable(account)) return { bundle: null, source: null }
+
+  const appUrl = String(opts.appUrl || '').replace(/\/+$/, '')
+  const url = appUrl + '/api/auth/signup'
+  const slug = String(account.slug).trim().toLowerCase()
+
+  let resp
   try {
-    const resp = await fetch(url, {
+    resp = await fetch(url, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ slug: account.slug, password: account.password }),
-      signal: AbortSignal.timeout(timeoutMs)
+      body: JSON.stringify({ invite: account.invite, slug, password: account.password, name: slug }),
+      signal: AbortSignal.timeout(opts.timeoutMs || 20000)
     })
-    if (!resp.ok) {
-      const body = await resp.text().catch(() => '')
-      return fallback(`HTTP ${resp.status}: ${body.slice(0, 120)}`) // offline-safe: keep the cached bundle
-    }
-    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
+    return { bundle: null, source: null, error: `cannot reach ${appUrl} (${e.message})`, terminal: false }
+  }
+
+  const j = await resp.json().catch(() => null)
+
+  if (!resp.ok || !j || j.ok === false) {
+    const code = (j && j.code) || `http-${resp.status}`
+    const message = (j && j.message) || `HTTP ${resp.status}`
+    return { bundle: null, source: null, error: `${message} (${code})`, terminal: TERMINAL_CODES.has(code) }
+  }
+
+  const ingest = j.ingest || {}
+  if (!ingest.writeToken) {
+    return { bundle: null, source: null, error: 'signup returned no write token', terminal: false }
   }
+
+  // NB: signup returns no readToken (the app keeps it in its own registry), so local
+  // history falls back to the DB-less ring unless a read token is set by hand.
+  const bundle = {
+    slug: (j.boat && j.boat.slug) || slug,
+    influxUrl: ingest.url,
+    org: ingest.org,
+    bucket: ingest.bucket,
+    writeToken: ingest.writeToken
+  }
+  writeCache(file, bundle)
+  return { bundle, source: 'paired' }
+}
+
+// True when the plugin either holds a bundle or has enough input to obtain one.
+function accountConfigured (app, account) {
+  return !!readCache(cacheFileFor(app)) || pairable(account)
 }
 
-module.exports = { resolveAccountConfig, accountConfigured }
+module.exports = { resolveAccountConfig, accountConfigured, cacheFileFor }

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.1",
+  "description": "EARLY ALPHA — cloud telemetry + offline maps for sailkick boats (www.sailkick.io; pairing is invite-only). 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"