signalk-polar-performance-plugin 0.0.59 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-07-21
+
+### Added
+- Plotter webapp (plotter.html) now has a settings panel accessible via a gear button: active polar selector, performance percentage stepper (±5%, range 50–200%), and a toggle to show or hide all TWS library curves.
+- `PolarCanvas.setShowAllTwsLines()` method to toggle library curve visibility at runtime; when off, only the live (current-TWS) curve is drawn.
+
+### Fixed
+- `perfAdjust` was not applied to the `/polars/:id/queries/curve` (and `/speed`, `/targets`, `/performance`) endpoints because each request loaded a fresh `PolarTable` from disk without calling `setPerformanceAdjustment()`. Polar curves in the webapp now correctly scale when performance is changed.
+- App Store icon was missing (monogram fallback shown): added `icon.png` at the package root so the App Store CDN can fetch it from the npm tarball via unpkg.com. The runtime `signalk.appIcon: ./icon.png` path is unchanged - the server still serves it from `public/icon.png` via the webapp mount.
+
+### Changed
+- Polar query endpoints (`/queries/curve`, `/speed`, `/targets`, `/performance`) now use a size-1 in-memory cache keyed by polar ID, avoiding repeated disk reads when consecutive requests target the same polar (e.g. the parallel curve fetches on startup). The cache is invalidated on `PUT` or `DELETE` for that polar ID.
+
+## [1.0.1] - 2026-07-20
+
+### Fixed
+- `plotter.html` updated to use the current `/polars/:id/axes/tws` and `/polars/:id/queries/curve` API routes; the TWS line was no longer rendered after the polar management API redesign in 1.0.0.
+
+## [1.0.0] - 2026-07-20
+
+### Added
+- Full polar file management: store, activate, copy, delete, and hot-swap polar files without restarting the plugin.
+- Import polars from the ORC (Offshore Racing Congress) database by sail number, boat name, or boat type.
+- Redesigned webapp polar management UI for canonical polar files and ORC imports.
+- OpenAPI spec covering polar-manager, polar-query, and legacy polar-data endpoints.
+- Custom plugin icon assets.
+
+### Fixed
+- Legacy `csvTable` in v0 settings is now converted to a canonical polar file during the v0→v1 migration; if conversion fails the migration retries on next start rather than silently discarding the data.
+- ORC availability check now short-circuits immediately when the certificate cache is already fresh, avoiding a redundant network round-trip; status check timeout raised from 2 s to 15 s.
+- Sidebar toggler was unreachable on mobile viewports.
+
+### Changed
+- `trueWindSpeedPath` legacy field is now removed during v0→v1 migration.
+- README and developer reference updated for canonical polar management and import flow.
+- Developer reference split into a separate file from the user guide.
+- Version bumped to 1.0.0 to reflect the stable, production-ready polar management API.
+
+## [0.0.60] - 2026-07-06
+
+### Added
+- Added runtime configuration of the plugin via the webapp.
+- Added support for managing multiple polar  files —  switch between polars directly from the webapp.
+- Added runtime inspection of the plugin via the webapp.
+- Added ability to import polars from the ORC (Offshore Racing Congress) database by searching on sail number, boat name or boat type.
+- Added extrapolation of the polar beyond the boundaries of the polar file.
+- Added comprehensive warnings in the webapp.
+- Added a full-screen polar diagram plotter page for a clean, chart-plotter-style view of your polar.
+- Added new smoother types for sensor input smoothing: Moving Average and Kalman filter, in addition to the existing Exponential smoother.
+- Added GitHub Actions CI workflow for automated testing across multiple platforms and Node.js versions.
+- Added support for display units. Polar data and polar diagrams now use the preferred units.
+
+### Changed
+- Polar diagram changed to a rader style diagram.
+- The separate damping settings for True Wind Speed, True Wind Angle, and Boat Speed have been replaced by a single smoother type with one tuning parameter. Existing settings are migrated automatically on first start.
+- source selection replaced by source priorities.
+
+## [0.0.59] - 2026-06-03
+
+### Added
+- Added informative error messages in the plugin log when polar or wind data is missing or unavailable.
+
+### Fixed
+- Fixed incorrect tack/gybe true wind angle calculation.
+- Improved reliability of CSV polar file loading with strengthened parsing.
+
+## [0.0.58] - 2026-01-21
+
+### Added
+- Added Signal K metadata (units and descriptions) for all plugin output paths, making values easier to read in compatible displays.
+
+## [0.0.57] - 2026-01-03
+
+### Added
+- Added ability to select which True Wind Speed source ID to use for calculations.
+- Added option to specify which GPS/SOG source to use for boat speed calculations.
+- Added an example CSV polar file to help with initial setup.
+
+### Changed
+- Performance data is now only sent when values actually change, reducing network traffic.
+
+### Fixed
+- Fixed incorrect units for target velocity made good (VMG).
+- Updated dashboard webapp jQuery dependency for compatibility.
+
+## [0.0.45] - 2024-06-22
+
+### Changed
+- Signal K metadata is now sent only once at startup rather than with every update, reducing bandwidth usage.
+
+## [0.0.44] - 2024-06-22
+
+### Added
+- Added target boat speed output based on the current polar and wind conditions.
+- The performance dashboard now automatically reconnects when the server connection is lost.
+
+### Changed
+- Beat angle, gybe angle, and target true wind angle are now shown as signed values (positive/negative depending on tack).
+- True wind angle in the dashboard is now displayed as an absolute value for clarity.
+
+## [0.0.40] - 2023-05-30
+
+### Added
+- Added Signal K logo to the performance dashboard webapp.
+- Added visual dots on the polar diagram showing current boat speed and polar target speed.
+
+### Changed
+- When sailing beyond the fastest polar heading, the plugin now uses the highest available polar speed.
+- Polar diagram speed values are rounded for a cleaner display.
+
+### Fixed
+- Fixed plugin not restarting correctly after configuration changes are applied.
+- Fixed plugin not stopping cleanly when disabled.
+- Fixed erratic Speed over Ground and Boat Speed readings caused by damping misconfiguration.
+
+## [0.0.35] - 2023-05-21
+
+### Added
+- Added interactive polar diagram visualization in the performance dashboard webapp.
+- Added Velocity Made Good (VMG), polar VMG, and VMG ratio as Signal K output paths.
+- Added configurable damping (smoothing) for True Wind Speed, True Wind Angle, and Boat Speed, using time constants for consistent behaviour.
+- Added configurable polar adjustment ratio for fine-tuning performance targets to your specific boat.
+- Added tack true wind angle and beat/run angle calculations, including automatic estimation when not present in the polar file.
+- Added polar speed extrapolation towards zero wind speed.
+
+### Changed
+- Polar VMG is now calculated using the optimal true wind angle for improved accuracy.
+- Polar diagram now displays all wind speeds in distinct colours.
+- Polar diagram has a dark theme.
+
+### Fixed
+- Fixed beat and run angle errors when the polar file does not include them.
+- Fixed polar diagram generation bug at the zero-wind baseline.
+- Fixed CSV polar file loading and chart display precision.
+- Fixed heading damping instability near ±180°.
+
+## [0.0.9] - 2023-04-30
+
+### Fixed
+- Fixed optimum wind angle calculation producing incorrect results.
+
+## [0.0.7] - 2023-04-29
+
+### Added
+- Added option to use Speed over Ground (SOG) instead of Speed through Water (STW) for performance calculations.
+- Added polar maximum speed and the wind angle at which it occurs as output paths.
+
+### Changed
+- Renamed Signal K paths from 'optimal' to 'optimum' to align with B&G instrument terminology.
+
+---
+
+[0.0.60]: https://github.com/htool/signalk-polar-performance-plugin/compare/3593e2b...d051c34
+[0.0.59]: https://github.com/htool/signalk-polar-performance-plugin/compare/c0a8958...3593e2b
+[0.0.58]: https://github.com/htool/signalk-polar-performance-plugin/compare/ad9c8b5...c0a8958
+[0.0.57]: https://github.com/htool/signalk-polar-performance-plugin/compare/ed1217d...ad9c8b5
+[0.0.45]: https://github.com/htool/signalk-polar-performance-plugin/compare/a1d99ec...ed1217d
+[0.0.44]: https://github.com/htool/signalk-polar-performance-plugin/compare/51ba34f...a1d99ec
+[0.0.40]: https://github.com/htool/signalk-polar-performance-plugin/compare/858cd66...51ba34f
+[0.0.35]: https://github.com/htool/signalk-polar-performance-plugin/compare/21de4ab...858cd66
+[0.0.9]: https://github.com/htool/signalk-polar-performance-plugin/compare/0d1eb6a...21de4ab
+[0.0.7]: https://github.com/htool/signalk-polar-performance-plugin/compare/cd2e367...0d1eb6a

package/README.md

@@ -1,31 +1,182 @@
-# Polar performance plugin
-Generate performance information based on a polar diagram.
+# Polar Performance — Signal K Plugin
 
-## Data correctness
-It's assumed data is already corrected when it's read by this plugin. This can be sometimes be done by the sensor, sometimes upon entry into SignalK using the [calibration plugin](https://www.npmjs.com/package/@signalk/calibration).
+Polar Performance reads your boat's true wind speed, true wind angle, and boat speed from Signal K, looks up the corresponding target values from your polar diagram, and publishes performance metrics — beat angle, run angle, VMG, polar speed ratio, and others — back to the Signal K bus in real time. An integrated webapp lets you inspect the live values, manage polars, and configure the plugin while it is running.
 
-## Data sources
-The following paths are read
- - navigation.speedThroughWater
- - environment.wind.speedTrue
- - environment.wind.angleTrueWater
- - navigation.speedOverGround (optional)
+---
 
-## Plugin configuration
-### Polar diagram
-The polar diagram can be configured through CSV notation as used on [ORC sailboat data](https://jieter.github.io/orc-data/site/).
+## Installation
 
-## Example csv
+Install from the Signal K App Store, or manually:
+
+```sh
+cd ~/.signalk
+npm install signalk-polar-performance-plugin
+```
+
+Then restart Signal K and enable the plugin in **Server → Plugin Config → Polar Performance**.
+
+---
+
+## Quick start
+
+1. Open the webapp from **Webapps → Polar Performance**.
+2. Go to the **Polars** tab and either import a polar from the ORC database or import a text polar.
+3. Go to the **Settings** tab and select the polar you just added as the active polar.
+4. The **Overview** tab now shows live performance numbers and a polar diagram.
+5. Enable the outputs you want in the **Outputs** tab.
+
+---
+
+## The webapp
+
+The webapp is the primary interface for the plugin. Open it from the Signal K dashboard.
+
+### Overview
+
+A polar diagram on the left and live performance numbers on the right. The diagram shows a live TWS curve interpolated for the current wind speed, and two dots — the polar target speed (what the polar says you should be doing) and your actual boat speed — both at the current TWA. The targets section shows the beat and run angle and VMG interpolated from the polar for the current wind speed. Any data quality warnings appear at the bottom.
+
+### Inputs
+
+Shows the raw instrument values as they arrive from Signal K (before smoothing) and the smoothed values actually used for computation, side by side. Useful for spotting stale sensors or checking whether the smoother settings make sense for your data. Any missing inputs are listed as warnings.
+
+### Outputs
+
+Shows the current value of each output path and lets you enable or disable each group with a toggle. Only enabled outputs are published to the Signal K bus. 
+
+### Settings
+
+Lets you alter the settings of the plugin. Polar selection, performance adjustment, smoother type and parameter, and speed source. The polar diagram of the selected polar is shown.
+
+### Polars
+
+Manage stored polars, import polars from the ORC database, and import text polars in supported formats.
+---
+
+## Configuration
+
+All configuration is done through the webapp. The settings available are:
+
+### Active polar
+
+Select the polar to use for calculations. The polar diagram in the Settings tab updates when you change this. If no polar is selected the plugin runs but publishes nothing; any previously published values are nullified immediately.
+
+### Performance adjustment
+
+A multiplier applied to all polar speeds before they are used. `1.0` means use the polar as-is. `0.90` means the plugin assumes your boat achieves 90 % of the polar values — useful when your polar is optimistic or you are sailing conservatively. The polar diagram in the Settings tab reflects this adjustment. Step size is 0.05.
+
+### Smoother
+
+Input smoothing prevents noisy instrument data from producing erratic outputs. The available smoothers are:
+
+| Type | Parameter | Best for |
+|------|-----------|----------|
+| **Exponential (EMA)** | Time constant τ (seconds) | General use. Smooth but responsive. |
+| **Moving average** | Window size (seconds) | Uniform weighting over a fixed time window. |
+| **Kalman filter** | Steady-state gain (0–1) | Automatically balances noise and responsiveness. |
+| **None** | — | When your instruments already filter their output. |
+
+All three input channels — true wind speed, true wind angle, and boat speed — use the same smoother type and parameter. 
+
+### Speed source
+
+Choose between **speed through water** (`navigation.speedThroughWater`) and **speed over ground** (`navigation.speedOverGround`). Use SOG when a working paddlewheel is not available, but be aware that SOG includes current — this makes boat speed appear higher or lower depending on the tidal state.
+
+---
+
+## Outputs
+
+Enable each group in the **Outputs** tab. 
+
+### Beat and run angles
+
+| Path | Description |
+|------|-------------|
+| `performance.beatAngle` | Optimal upwind TWA for the current TWS. Negative = port tack. |
+| `performance.gybeAngle` | Optimal downwind TWA for the current TWS. Negative = port tack. |
+
+These are the angles at which VMG is maximised, read directly from the polar. Use these as target wind angles for optimal upwind and downwind sailing.
+
+### Beat and run VMG
+
+| Path | Description |
+|------|-------------|
+| `performance.beatAngleVelocityMadeGood` | Best achievable VMG upwind for the current TWS. |
+| `performance.gybeAngleVelocityMadeGood` | Best achievable VMG downwind for the current TWS. |
+
+### Target TWA and VMG
+
+Automatically selects between beat and run depending on whether you are sailing upwind or downwind (TWA < 90° = upwind).
+
+| Path | Description |
+|------|-------------|
+| `performance.targetAngle` | Target TWA for the current point of sail. Negative = port. |
+| `performance.targetVelocityMadeGood` | Target VMG for the current point of sail. |
+
+### Optimum wind angle
+
+| Path | Description |
+|------|-------------|
+| `performance.optimumWindAngle` | Difference between your current TWA and the optimal angle. Negative = bear away, positive = head up. Zero means you are sailing at the optimal angle. |
+
+### VMG and polar VMG ratio
+
+| Path | Description |
+|------|-------------|
+| `performance.velocityMadeGood` | Your actual VMG: `boatSpeed × cos(TWA)`. |
+| `performance.polarVelocityMadeGood` | Polar target VMG for the current TWS. |
+| `performance.polarVelocityMadeGoodRatio` | Actual VMG divided by polar VMG. `1.0` = perfect; `0.85` = 85 % of theoretical optimum. |
+
+### Polar speed and speed ratio
+
+| Path | Description |
+|------|-------------|
+| `performance.polarSpeed` | The polar target boat speed for the current TWS and TWA. |
+| `performance.targetSpeed` | The boat speed you would need at the optimal angle to achieve target VMG. |
+| `performance.polarSpeedRatio` | Actual boat speed divided by polar speed. `1.0` = on target; `<1.0` = below target. |
+
+### Maximum speed
+
+| Path | Description |
+|------|-------------|
+| `performance.maxSpeed` | Maximum polar boat speed achievable at the current TWS. |
+| `performance.maxSpeedAngle` | The TWA at which maximum speed is achieved. |
+
+### Opposite tack heading
+
+| Path | Description |
+|------|-------------|
+| `performance.tackTrue` | True heading on the opposite tack, calculated from the beat angle and current heading. Useful for tactical displays and layline charts. |
+
+Requires `navigation.headingTrue` to be available.
+
+### Smoothed inputs
+
+| Path | Description |
+|------|-------------|
+| `environment.wind.angleTrueWaterDamped` | Smoothed TWA as used internally by the plugin. |
+| `performance.boatSpeedDamped` | Smoothed boat speed as used internally by the plugin. |
+
+Useful when you want downstream instruments to use the same smoothed values that drive the performance calculation.
+
+---
+
+## Managing polars
+
+### Importing from ORC
+
+The plugin can search the official ORC active certificate source directly. Go to **Polars → Import ORC Certificate**, type part of the certificate RefNo, boat name, class, or sail number and click Search. When you find your boat, click Import. The polar is saved locally and immediately available for selection.
+
+Internet access is required only while searching or importing from ORC. In an isolated Signal K installation the ORC source is simply shown as unavailable; that is not treated as a plugin error. After import the polar is stored locally and no further internet access is needed.
+
+### Importing text polars
+
+If you have a polar in a supported text format, you can import it directly from the **Polars** tab. The plugin currently supports Jieter-style semicolon CSV and Expedition-style delimited text. Optional metadata such as display name, sail number, boat type, year, source label, and notes can be added during text import.
+
+The Jieter CSV format uses semicolons as separators. The first row is a header with `twa/tws` in the first column followed by wind speeds in knots. Each subsequent row is a TWA in degrees followed by boat speeds in knots. Beat and run angles appear as separate rows with one non-zero speed per row (the VMG for that wind speed column).
+
+**Example:**
 ```
 twa/tws;6;8;10;12;14;16;20
-0;0;0;0;0;0;0;0
-46.9;4.23;0;0;0;0;0;0
-44.8;0;5.09;0;0;0;0;0
-43.5;0;0;5.72;0;0;0;0
-42.6;0;0;0;6.22;0;0;0
-41.8;0;0;0;0;6.57;0;0
-40.8;0;0;0;0;0;6.75;0
-41.1;0;0;0;0;0;0;6.93
 52;4.57;5.59;6.33;6.87;7.23;7.45;7.65
 60;4.93;5.93;6.66;7.15;7.47;7.68;7.94
 75;5.17;6.18;6.91;7.37;7.68;7.92;8.31
@@ -34,70 +185,104 @@ twa/tws;6;8;10;12;14;16;20
 120;5.2;6.38;7.23;7.76;8.16;8.55;9.36
 135;4.65;5.84;6.78;7.43;7.87;8.25;9.03
 150;3.92;5.05;5.97;6.7;7.2;7.58;8.17
+46.9;4.23;0;0;0;0;0;0
+44.8;0;5.09;0;0;0;0;0
 144.2;4.19;0;0;0;0;0;0
 146.4;0;5.25;0;0;0;0;0
-146.9;0;0;6.17;0;0;0;0
-147.1;0;0;0;6.91;0;0;0
-148.3;0;0;0;0;7.33;0;0
-171.2;0;0;0;0;0;6.76;0
-176.3;0;0;0;0;0;0;7.59
 ```
 
-The resulting polar after processing can be seen here in the WebApp, looking something like:
-![](https://raw.githubusercontent.com/htool/signalk-polar-performance-plugin/main/doc/BandG_polar.png)
-
-
-### Plugin options
-In the plugin configuration you can toggle the following options:
- - Enable calculation/sending of beat/upwind and run/gybe/downwind angle
- - Enable calculation/sending of beat/upwind and run/gybe/downwind VMG
- - Enable sending Target TWA
- - Enable calculation of Optimum Wind Angle (difference between TWA and beat/run angle (depends on beat/run angle)
- - Enable sending of maximum speed angle and boat speed for a given TWS
- - Enable calculation of Optimum Wind Angle (difference between TWA and beat/run angle (depends on beat/run angle)
-
-## Calculated performance data
-### Currently supported
- - Upwind / beat angle (performance.beatAngle) 
- - Downwind / run / gybe angle (performance.gybeAngle) 
- - Upwind / beat VMG (performance.beatAngleVelocityMadeGood) 
- - Downwind / run / gybe VMG (performance.gybeAngleVelocityMadeGood) 
- - Target TWA (performance.targetAngle) (equals upwind or downwind angle)
- - Optimal Wind Angle (diff between TWA and environment.wind.directionTrue)
- - Polar Boat Speed (performance.polarSpeed)
- - Polar Speed Ratio (performance.polarSpeedRatio)
- - Plugin option to use SOG as boat speed
- - Wind angle for maximum speed at this wind speed
- - Fill up the ends of the polar diagram
- - Visualisation of the polar diagram
- - Configurable damping alorithm on inputs
- - Extrapolation of polar data towards 0
- - Configurable overall performance adjustment ratio
- - Dots in webapp indicating Polar Speed and Boat Speed
- - Use highest polar speed when going north of Polar
-
-### To-do list
- - Improved interpolation
- - Make moment to do calculation smarter/configurable
- - API to see JSON of polar
- - Create polar from live data
- -- Save polar info to file
- -- Save new record speed for angle in polar
- -- Determine if we're on a steady course to avoid fake records
- -- Configure the resolution of the polar diagram
- - Support multiple polar diagrams
- - Capture heel in polar diagram
-
-## MFD configuration
-
-### B&G
-To get the values calculated by this plugin from SignalK to your B&G MFD/Triton2, you need to install the [B&G performance plugin](https://www.npmjs.com/package/signalk-bandg-performance-plugin) and select at least the following values:
- - Polar Speed (Polar Speed - POL SPD)
- - Polar Speed Ratio (Polar Performance - POL PERF))
- - Target TWA (TARG TWA)
-
-To see lay lines you need to set:
- - Settings -> Chart -> Laylines -> Targets... -> True wind angle to 'Actual'
+### Extrapolation
+
+The polar table covers a finite range of TWA values. The plugin extrapolates outside this range in two ways:
+
+- **Close to the wind (beat zone):** A quadratic curve fitted to ensure continuity with the first measured point. The boat speed reaches zero at 25° (the assumed hard pinching angle).
+- **Deep downwind (run zone):** A cosine-VMG model extending 30 % of the angular gap between the run angle and dead downwind. Beyond this limit the plugin returns no value rather than extrapolate further.
+
+Values derived from extrapolated regions are indicated in the webapp warnings.
+
+### Performance adjustment
+
+The performance adjustment multiplier scales all polar speeds proportionally. Use it to calibrate the polar to your boat's actual performance. A value of `0.95` tells the plugin your boat achieves 95 % of the published polar — the polar diagram in Settings reflects this visually.
+
+---
+
+## Connecting to plotters and instruments
+
+### B&G / Navico
+
+Install the [B&G Performance Plugin](https://www.npmjs.com/package/signalk-bandg-performance-plugin). Map at minimum:
+
+| Signal K path | B&G label |
+|---------------|-----------|
+| `performance.polarSpeed` | Polar Speed (POL SPD) |
+| `performance.polarSpeedRatio` | Polar Performance (POL PERF) |
+| `performance.targetAngle` | Target TWA (TARG TWA) |
+| `performance.beatAngle` | Beat Angle |
+| `performance.gybeAngle` | Gybe Angle |
+
+For laylines on charts: **Settings → Chart → Laylines → Targets → True wind angle → Actual**.
+
+### Garmin / Raymarine / other NMEA 2000
+
+Use a Signal K → NMEA 2000 gateway plugin (such as `canboat` or `signalk-to-n2k`) to forward paths to the PGN fields your plotter expects for performance data. Consult your plotter's documentation for the relevant PGNs — most support Polar Speed, Target TWA, and VMG.
+
+### OpenCPN / KIP / other Signal K displays
+
+Subscribe directly to the paths listed in the Outputs section above. 
+
+### Full-screen polar plotter
+
+The plugin includes a separate full-screen polar plotter page at:
+
+```
+http://<your-server>:<port>/signalk-polar-performance-plugin/plotter.html
+```
+
+This is a dark-themed, full-screen canvas display suitable for a chartplotter or secondary monitor. It shows all library curves, the live TWS curve, and the performance dots, and updates in real time.
+
+---
+
+## Data quality and warnings
+
+The webapp shows warnings whenever something prevents accurate calculation:
+
+| Warning | Cause |
+|---------|-------|
+| *True wind speed — no data* | `environment.wind.speedTrue` is not arriving from Signal K.  |
+| *True wind angle — no data* | `environment.wind.angleTrueWater` is not arriving.  |
+| *Boat speed — no data* | `navigation.speedThroughWater` (or SOG) is not arriving.  |
+| *No polar loaded* | No active polar is configured. Select a polar from the settings tab. Or go to the Polars tab and store a canonical polar resource first. |
+| *Sailing in irons* | TWA is below the minimum angle in the polar. No output is produced. |
+| *Pinching* | TWA is between the minimum polar angle and the beat angle. Values come from the extrapolated beat zone. |
+| *Extrapolated beyond run angle* | TWA is deeper than the run angle. Values come from the cosine-VMG extrapolation model. |
+| *Wind speed below/above polar range* | TWS is outside the range covered by the polar. Values are extrapolated from the nearest TWS entry. |
+
+---
+
+## Input data quality
+
+Performance calculations are only as good as the inputs. A few things are worth checking before relying on the output:
+
+- **True wind** must already be correctly calculated. If your setup uses a basic instrument or the Signal K Derived Data plugin, check that the calculation is using the right boat speed source and that heading is calibrated. The [Advanced Wind plugin](https://github.com/htool/advancedWind) provides additional corrections for sensor mounting angle, heel, mast movement, and upwash if your true wind data quality is poor.
+- **Boat speed calibration** has a direct effect on polar ratio calculations. A 3 % paddlewheel error produces a 3 % offset in `performance.polarSpeedRatio`. The [Speed and Current plugin](https://github.com/htool/speedandcurrent) can automate paddlewheel calibration.
+- **Data consistency:** the plugin uses its own internal smoother for all inputs. 
+
+---
+
+## For integrators and API users
+
+If you want to automate polar management or consume the plugin as a canonical polar provider, use the developer reference:
+
+- [Developer reference](docs/developer-reference.md) for the canonical `polarTable` structure and the plugin REST API.
+- [openApi.json](openApi.json) for the authoritative machine-readable contract.
+
+---
+
+## Known limitations
+
+- Heel angle is not taken into account in the polar lookup. Most ORC polars are upright polars.
+- Polar storage is canonical-only. Text and ORC imports are conversion inputs; they are stored internally as canonical `polarTable` resources.
+
 
  ![](https://raw.githubusercontent.com/htool/signalk-polar-performance-plugin/main/doc/BandG_Laylines_Target_TWA_to_Active.png)