docs: explain the Beaufort index arithmetic and why compass exists

Two comments, no behaviour change.

`force - 1` reads as an off-by-one until you know the scale starts at 0
while ipairs starts at 1, so the loop index is already force + 1. Said
plainly now, along with why the fall-through returns 12.

compass() has no caller: the card draws arrow(). It is kept because it
shares arrow()'s binning exactly, so testing both pins that shared logic
from two angles, and switching the card to "S 9 km/h" becomes a one-word
change. Without this note the next reader finds an unused function and
has to reconstruct the reasoning.

Raised by code review as the only two points worth acting on; no
Critical or Important issues were found.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2 files changed, 18 insertions, 0 deletions

diff --git a/docs/superpowers/plans/2026-09-17-weather-widget.md b/docs/superpowers/plans/2026-09-17-weather-widget.md
index a7c9ef3..cf485ee 100644
--- a/docs/superpowers/plans/2026-09-17-weather-widget.md
+++ b/docs/superpowers/plans/2026-09-17-weather-widget.md
@@ -315,6 +315,10 @@ end
 
 -- Beaufort force from km/h. Upper bounds carried over from the polybar
 -- script; a value equal to a bound stays in the lower force.
+--
+-- The scale starts at 0 and ipairs starts at 1, so force N's upper bound is
+-- BEAUFORT[N + 1] and the loop index is already N + 1. Hence `force - 1`
+-- below. The scale tops out at 12, which is why the fall-through returns it.
 local BEAUFORT = { 1, 5, 11, 19, 28, 38, 49, 61, 74, 88, 102, 117 }
 
 function M.beaufort(kmh)
@@ -328,6 +332,11 @@ end
 -- Eight compass points. The half-step offset is what makes north straddle
 -- zero: without it, 350 degrees would land in NW and 10 in NE, leaving north
 -- with only half its arc.
+--
+-- Nothing calls compass() yet: the card draws arrow() instead. It is kept
+-- because it shares arrow()'s binning exactly, so testing both pins that
+-- shared logic from two angles, and swapping the card to read "S 9 km/h"
+-- instead of an arrow is then a one-word change rather than new code.
 local POINTS = { 'N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW' }
 
 function M.compass(deg)
diff --git a/lib/weather.lua b/lib/weather.lua
index 6e2741a..ac1f4cf 100644
--- a/lib/weather.lua
+++ b/lib/weather.lua
@@ -71,6 +71,10 @@ end
 
 -- Beaufort force from km/h. Upper bounds carried over from the polybar
 -- script; a value equal to a bound stays in the lower force.
+--
+-- The scale starts at 0 and ipairs starts at 1, so force N's upper bound is
+-- BEAUFORT[N + 1] and the loop index is already N + 1. Hence `force - 1`
+-- below. The scale tops out at 12, which is why the fall-through returns it.
 local BEAUFORT = { 1, 5, 11, 19, 28, 38, 49, 61, 74, 88, 102, 117 }
 
 function M.beaufort(kmh)
@@ -84,6 +88,11 @@ end
 -- Eight compass points. The half-step offset is what makes north straddle
 -- zero: without it, 350 degrees would land in NW and 10 in NE, leaving north
 -- with only half its arc.
+--
+-- Nothing calls compass() yet: the card draws arrow() instead. It is kept
+-- because it shares arrow()'s binning exactly, so testing both pins that
+-- shared logic from two angles, and swapping the card to read "S 9 km/h"
+-- instead of an arrow is then a one-word change rather than new code.
 local POINTS = { 'N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW' }
 
 function M.compass(deg)