@openwaters/noaa-current-stations 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan Clark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# NOAA Current Stations
+
+**NOAA CO-OPS tidal-current station data — the extractor, the schema, and the API's
+undocumented behaviour, in one place.**
+
+NOAA publishes harmonic constituents for **856 tidal-current stations** in US waters,
+plus offset tables for **1,700-odd subordinate** stations. That is enough to predict slack
+water and max flood/ebb offline, anywhere in US waters, with no network at runtime.
+
+This package extracts that data, ships it as a versioned bundle, and documents the
+schema — so you don't have to talk to the API at all.
+
+## Install
+
+```bash
+npm install @openwaters/noaa-current-stations
+```
+
+## Use it as a CLI
+
+```bash
+# every US current station → currents.json  (~2,800 stations, several minutes, paced)
+npx noaa-current-stations extract currents.json
+
+# one region
+npx noaa-current-stations extract salish.json --box 47,-125,49.2,-122
+
+# just the stations you care about
+npx noaa-current-stations extract mine.json --stations PUG1717,PUG1701
+
+# capture a validation fixture: constituents + NOAA's own predictions, one file
+npx noaa-current-stations golden pug1741.json --station PUG1741 --bin 27 \
+  --start 2026-07-19 --end 2026-07-21
+
+# has NOAA's station list changed since the bundle was built? (one request; exit 1 if so)
+npx noaa-current-stations check
+```
+
+> A full US extraction is ~2,800 paced requests and takes several minutes. NOAA
+> throttles bulk callers — leave the pacing alone unless you have a reason.
+
+## Use it as a library
+
+```js
+import { extractBundle, fetchCurrentPredictions, fetchHarcon } from '@openwaters/noaa-current-stations';
+
+// A bundle you can ship and predict from offline.
+const { bundle, skipped } = await extractBundle({ stations: ['PUG1717'] });
+
+// Or NOAA's own published predictions, live.
+const events = await fetchCurrentPredictions(
+  'PUG1717', 35, new Date('2026-07-19'), new Date('2026-07-21'),
+);
+// → [{ time: '2026-07-19T01:44:00.000Z', kind: 'flood', velocityMajor: 2.85, … }]
+```
+
+Ships TypeScript types. No dependencies.
+
+## What a bundle looks like
+
+```json
+{
+  "note": "Generated from NOAA CO-OPS mdapi …",
+  "crossFlow": {
+    "measured": "…", "records": 856, "gte0_25kn": 61, "gte0_50kn": 12,
+    "worstRatio": { "id": "BOS1130", "crossFlow": 0.178, "alongAxisPeak": 0.74, "ratio": 0.241 },
+    "worstAbsolute": { "id": "PUG1619", "crossFlow": 0.8 }
+  },
+  "stations": [
+    {
+      "id": "PUG1717", "name": "Turn Point, Boundary Pass", "type": "harmonic",
+      "floodDirection": 23.2, "ebbDirection": 203.2,
+      "offset": 0.297,
+      "constituents": [{ "name": "M2", "amplitude": 1.63, "phase": 295.3 }]
+    },
+    {
+      "id": "PCT0236", "name": "…", "type": "subordinate",
+      "reference": "SFB1201@10",
+      "slackBeforeFloodOffset": -720, "slackBeforeEbbOffset": 480,
+      "floodSpeedRatio": 0.7, "ebbSpeedRatio": 1.2
+    }
+  ]
+}
+```
+
+Speeds in knots, directions degrees true, time offsets in seconds. Full schema:
+[schema/currents.schema.json](schema/currents.schema.json) ·
+[docs/schema.md](docs/schema.md).
+
+Four details that are easy to get wrong and expensive to debug:
+
+- **`offset` is Z₀**, the station's net mean flow (NOAA `majorMeanSpeed`). Slack is
+  where the velocity curve crosses zero, so dropping this moves every slack time. The
+  Salish passes carry −0.74 to +0.30 kn of it. Measured cost of omitting it: **15.6 →
+  7.4 min** mean timing error.
+- **A reference is `(station, bin)`**, hence `SFB1201@10`. Constituents vary by depth
+  bin and a station may publish several; keying by station id alone silently predicts
+  from the wrong depth.
+- **A `type: S` station is not necessarily subordinate.** A few carry their own harcon
+  and NOAA predicts them harmonically; the offset reduction overshoots them badly
+  (89 min vs 6.8 min at PUG1716). Rare — 1 of 1,706 — but you can't tell which without
+  asking, and the ask is one request.
+- **The model is one axis, and the bundle says how much that costs.** `crossFlow` is a
+  census of NOAA's `minorMeanSpeed`, the flow perpendicular to the flood axis that runs
+  even at slack. `validate` fails above a 0.5 ratio. Bundling the full minor axis was
+  measured and rejected: a 2D magnitude series never crosses zero, so slack detection
+  silently returns nothing.
+
+## Maintenance
+
+`currents.json` is committed, pretty-printed, so a change in NOAA's data is reviewable
+as a diff. [`update-stations`](.github/workflows/update-stations.yml) keeps it current:
+
+| Cadence | What runs | Catches |
+|---|---|---|
+| Weekly | pre-flight — **one** request for the station list | stations added, removed, or reclassified |
+| Monthly | forced full extraction (~2,800 paced requests, ~25 min) | NOAA revising an existing station's constituents in place |
+
+The weekly pre-flight only escalates to a full extraction when something moved, so the
+common case costs a single request. Either way, a change opens a **pull request** with
+the validation summary — nothing updates silently.
+
+`stations.lock.json` pins the current list; `noaa-current-stations check` is the same
+pre-flight you can run yourself, and exits non-zero on drift.
+
+```bash
+npx noaa-current-stations check                    # has NOAA's list moved?
+npx noaa-current-stations validate currents.json   # structural check on a bundle
+```
+
+`validate` is what gates the automated PR: it fails on a subordinate whose reference
+went missing, duplicate ids, a harmonic station with no constituents, or a bundle that
+lost its Z₀ offsets — the shapes a truncated extraction takes.
+
+## Don't trust it until you've diffed it
+
+Both halves of a validation come from NOAA, so the check is self-contained: predict from
+`harcon` constituents, compare against NOAA's own `currents_predictions` for the same
+days. `noaa-current-stations golden` captures both into one fixture that replays offline.
+
+Expect ~10 min / 0.05 kn at a clean reversing station. Measured results, realistic
+tolerances, and the list of convention questions this method settled:
+[docs/validation.md](docs/validation.md).
+
+## Who uses this
+
+- [slackwater-engine](https://github.com/openwatersio/slackwater-engine) — Swift tide
+  and current engine; vendors the released bundle for offline prediction.
+- [signalk-currents](https://github.com/sailingnaturali/signalk-currents) — SignalK
+  plugin serving live and offline currents to a boat's instruments.
+
+## Scope
+
+US waters only — this is a NOAA client, and NOAA publishes US stations. Other national
+hydrographic offices publish current data under their own terms; that is out of scope
+here.
+
+## If you're calling the NOAA API yourself
+
+You probably don't need to — that's what the bundle is for. But if you are, the API has
+undocumented behaviours that make the data look like it doesn't exist. The worst one:
+
+```
+GET /stations/PUG1701/harcon.json?bin=0   → { "HarmonicConstituents": [] }
+GET /stations/PUG1701/harcon.json?bin=18  → 26 constituents
+```
+
+`bin=0` is the natural thing to try, and the empty array reads as "NOAA doesn't publish
+current constituents." It does — at each station's `currbin`, and nowhere else.
+
+**[→ docs/noaa-api.md](docs/noaa-api.md)** has the rest, including the widely-repeated
+User-Agent-blocking claim that turns out **not** to be true.
+
+## Licence and disclaimer
+
+Code MIT. NOAA CO-OPS data is **public domain**.
+
+**Predictions derived from this data are UNOFFICIAL.** They are not NOAA products, they
+are not certified for navigation, and they should not be presented as either. Slack
+timing at constricted passes can be off by 15 minutes or more. Use official published
+tables to time anything that matters.

package/bin/noaa-current-stations.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// CLI: extract a station bundle, or capture a validation fixture.
+import { writeFileSync, readFileSync } from 'node:fs';
+import { extractBundle } from '../src/extract.js';
+import { captureGolden } from '../src/golden.js';
+import { checkDrift, buildLock } from '../src/drift.js';
+import { validateBundle } from '../src/validate.js';
+import { fetchStationList } from '../src/noaa.js';
+
+const USAGE = `noaa-current-stations — NOAA CO-OPS tidal-current station data
+
+  noaa-current-stations extract <out.json> [--box S,W,N,E] [--stations ID,ID] [--pace ms]
+  noaa-current-stations golden  <out.json> --station ID --bin N --start ISO --end ISO
+  noaa-current-stations check   [lock.json]   exit 1 if NOAA's list has drifted from the lock
+  noaa-current-stations lock    <out.json>    re-pin the lock to NOAA's current list
+  noaa-current-stations validate <bundle.json> structural check on a bundle
+
+Examples:
+  noaa-current-stations extract currents.json                       # all US stations
+  noaa-current-stations extract salish.json --box 47,-125,49.2,-122 # one region
+  noaa-current-stations extract mine.json --stations PUG1717,PUG1701
+  noaa-current-stations golden pug1741.json --station PUG1741 --bin 27 \\
+    --start 2026-07-19 --end 2026-07-21
+
+A full extraction is thousands of paced requests. NOAA throttles bulk callers.
+`;
+
+const [cmd, out, ...rest] = process.argv.slice(2);
+const flags = {};
+for (let i = 0; i < rest.length; i += 2) flags[rest[i].replace(/^--/, '')] = rest[i + 1];
+
+// `check` is the one command with a sensible default output path.
+if (!cmd || (!out && cmd !== 'check') || flags.help !== undefined) {
+  console.log(USAGE);
+  process.exit(cmd ? 1 : 0);
+}
+
+const log = (m) => console.error(m);
+const logCrossFlow = (cf) => {
+  if (!cf?.worstRatio) return log('cross-flow: not measured');
+  log(`cross-flow (${cf.records} harmonic records): `
+    + `${cf.gte0_25kn} >= 0.25 kn, ${cf.gte0_50kn} >= 0.50 kn`);
+  log(`  worst ratio    ${cf.worstRatio.ratio} at ${cf.worstRatio.id} `
+    + `(${cf.worstRatio.crossFlow} kn across a ${cf.worstRatio.alongAxisPeak} kn axis)`);
+  log(`  worst absolute ${cf.worstAbsolute.crossFlow} kn at ${cf.worstAbsolute.id}`);
+};
+const paceMs = flags.pace !== undefined ? Number(flags.pace) : undefined;
+
+if (cmd === 'extract') {
+  const { bundle, skipped } = await extractBundle({
+    box: flags.box?.split(',').map(Number),
+    stations: flags.stations?.split(','),
+    ...(paceMs !== undefined ? { paceMs } : {}),
+    log,
+  });
+  // Pretty-printed on purpose: this file is committed and its diff is how a NOAA
+  // revision gets reviewed. Release artifacts are minified from it.
+  writeFileSync(out, JSON.stringify(bundle, null, 2) + '\n');
+  log(`wrote ${out} — ${bundle.stations.length} stations`);
+  logCrossFlow(bundle.crossFlow);
+  if (skipped.failed.length) process.exitCode = 1;
+} else if (cmd === 'golden') {
+  const fixture = await captureGolden(
+    flags.station, Number(flags.bin), new Date(flags.start), new Date(flags.end),
+    { ...(paceMs !== undefined ? { paceMs } : {}) },
+  );
+  writeFileSync(out, JSON.stringify(fixture, null, 2) + '\n');
+  log(`wrote ${out} — ${fixture.constituents.length} constituents, ${fixture.events.length} events`);
+  if (fixture.predictionsError) {
+    log(`WARNING: no predictions captured (${fixture.predictionsError}) — re-run later`);
+    process.exitCode = 1;
+  }
+} else if (cmd === 'check') {
+  const lockPath = out ?? new URL('../stations.lock.json', import.meta.url).pathname;
+  const lock = JSON.parse(readFileSync(lockPath, 'utf8'));
+  const d = await checkDrift(lock);
+  const c = d.counts;
+  log(`NOAA now: ${c.total} stations (H ${c.H}, S ${c.S}, W ${c.W})`);
+  if (!d.drifted) {
+    log('No drift — matches the lock.');
+  } else {
+    log(`Pinned:   ${d.expected.total} stations (H ${d.expected.H}, S ${d.expected.S}, W ${d.expected.W})`);
+    for (const [label, ids] of [['ADDED', d.added], ['REMOVED', d.removed], ['RETYPED', d.retyped]]) {
+      if (ids.length) log(`\n${label} (${ids.length}):\n  ${ids.join('\n  ')}`);
+    }
+    log('\nNOAA\'s station list has changed. Re-extract the bundle, re-run `noaa-current-stations lock`, and '
+      + 'release — consumers are pinned to a bundle that no longer matches NOAA.');
+    process.exitCode = 1;
+  }
+} else if (cmd === 'validate') {
+  const v = validateBundle(JSON.parse(readFileSync(out, 'utf8')));
+  log(`${out}: ${v.counts.harmonic} harmonic, ${v.counts.subordinate} subordinate`);
+  logCrossFlow(v.crossFlow);
+  for (const e of v.errors) log(`  ERROR: ${e}`);
+  if (!v.ok) process.exitCode = 1;
+} else if (cmd === 'lock') {
+  const lock = buildLock(await fetchStationList({ paceMs: 0 }));
+  writeFileSync(out, JSON.stringify(lock, null, 2) + '\n');
+  log(`wrote ${out} — ${lock.counts.total} stations`);
+} else {
+  console.log(USAGE);
+  process.exit(1);
+}

package/docs/noaa-api.md

@@ -0,0 +1,233 @@
+# The NOAA CO-OPS currents API, as it actually behaves
+
+Everything here was found by building against the API and validating the output against
+NOAA's own published predictions. Several of these behaviours are undocumented, and at
+least two of them will make you conclude — wrongly — that the data you want doesn't
+exist. That conclusion is why this document exists.
+
+NOAA data is **public domain**. Predictions you derive from it are **unofficial** and
+must not be presented as NOAA's own or used as a primary means of navigation.
+
+---
+
+## The one that costs everyone a day
+
+**`harcon.json` returns an empty constituent list unless you query the station's
+`currbin`.**
+
+```
+GET /mdapi/prod/webapi/stations/PUG1701/harcon.json?units=english&bin=0
+→ { "HarmonicConstituents": [] }
+
+GET /mdapi/prod/webapi/stations/PUG1701/harcon.json?units=english&bin=18
+→ 26 constituents
+```
+
+There is no error, no hint, and `bin=0` is the natural thing to try. The empty array
+reads as "NOAA doesn't publish harmonic constituents for currents" — which is what we
+concluded, and it is wrong. NOAA publishes constituents for **856 current stations** in
+US waters (2026-07; the count drifts as NOAA revises its list).
+
+`currbin` comes from the station list. It is per-station and unguessable.
+
+---
+
+## Endpoints
+
+Base: `https://api.tidesandcurrents.noaa.gov`
+
+| Purpose | Path |
+|---|---|
+| Station list | `/mdapi/prod/webapi/stations.json?type=currentpredictions&units=english` |
+| Harmonic constituents | `/mdapi/prod/webapi/stations/<id>/harcon.json?units=english&bin=<currbin>` |
+| Subordinate offsets | `/mdapi/prod/webapi/stations/<id>_<currbin>/currentpredictionoffsets.json` |
+| Published predictions | `/api/prod/datagetter?product=currents_predictions&interval=max_slack&bin=<currbin>&…` |
+
+Note the subordinate-offsets path takes a **composite `<id>_<currbin>`**, unlike every
+other station path. `stations/PCT0236/currentpredictionoffsets.json` 404s;
+`stations/PCT0236_1/currentpredictionoffsets.json` works.
+
+## The station list repeats itself
+
+Each station appears **once per depth bin**. De-dup by `id` keeping the **first**
+entry — that one carries the primary `currbin`. Fields that matter:
+
+```
+id, name, lat, lng, type, currbin
+```
+
+`type` is `H` (harmonic), `S` (subordinate), or `W` (weak and variable / rotary —
+NOAA doesn't publish a usable reversing model for these; we skip them).
+
+## `harcon.json` fields
+
+```
+constituentName, description,
+majorAmplitude, majorPhase (local °), majorPhaseGMT (Greenwich °),
+minorAmplitude, minorPhase, minorPhaseGMT,
+majorMeanSpeed, minorMeanSpeed,
+azi (major-axis azimuth, ° true), binNbr, binDepth, constNum
+```
+
+Mapping that produces predictions matching NOAA's own:
+
+| You want | Use | Notes |
+|---|---|---|
+| amplitude | `majorAmplitude` | **knots** under `units=english`, **cm/s** under `units=metric` (÷ 51.4444) |
+| phase | `majorPhaseGMT` | Greenwich phase. Pairs with a Greenwich V₀ — confirmed empirically, see below |
+| flood direction | `azi` | ebb is `azi + 180` |
+| **Z₀ / mean flow** | `majorMeanSpeed` | signed, knots. **Do not drop this** — see below |
+| minor axis | `minorAmplitude`/`minorPhaseGMT` | for a 2D/rotary model; unused by a major-axis model — but see `minorMeanSpeed` below |
+| cross-flow | `minorMeanSpeed` | DC flow perpendicular to the axis, running at ALL times including slack. Not carried per station; summarised in the bundle's `crossFlow` census |
+
+### Z₀ is not optional
+
+`majorMeanSpeed` is the station's net mean flow along the major axis. It is a DC offset
+on the whole velocity curve, and **slack is defined by where that curve crosses zero** —
+so dropping it moves every slack time and skews peak speeds.
+
+It is not a small correction. The Salish Sea passes run **−0.74 to +0.30 kn** of mean
+flow (net ebb, as you would expect where a large river system drains to sea). Measured
+at Turn Point (PUG1717) against NOAA's own predictions over three days:
+
+| | mean timing error | worst | mean speed error |
+|---|---|---|---|
+| without Z₀ | 15.6 min | 55 min | 0.147 kn |
+| with Z₀ | **7.4 min** | **21 min** | **0.066 kn** |
+
+If your predictions are "close but consistently off around slack", this is why.
+
+### Phase convention
+
+`majorPhaseGMT` is correct for an engine using a Greenwich V₀. This was settled
+empirically rather than from documentation: predict a station from its constituents and
+compare against NOAA's `currents_predictions` for the same days. With the right
+convention the max flood/ebb events land within ~10 minutes; with the wrong one the
+error is structural and obvious.
+
+## Subordinate stations
+
+```
+refStationId, refStationBin, meanFloodDir, meanEbbDir,
+sbfTimeAdjMin (slack before flood),  sbeTimeAdjMin (slack before ebb),
+mfcTimeAdjMin (max flood current),   mecTimeAdjMin (max ebb current),
+mfcAmpAdj, mecAmpAdj
+```
+
+Two things people get wrong:
+
+- **There are two slack offsets, not one.** A slack event takes the offset for the phase
+  it *precedes* — `sbfTimeAdjMin` for a slack before flood, `sbeTimeAdjMin` before ebb.
+- **`mfcAmpAdj` / `mecAmpAdj` are ratios**, applied to the reference peak speed. Not
+  deltas. (Confirmed by validation: treating them as deltas fails immediately.)
+
+### A reference is a (station, **bin**) pair
+
+A reference station can publish several bins with **different constituents**, and the
+subordinate names the one it wants in `refStationBin`:
+
+```
+SFB1201 currbin list: [26, 20, 10]
+  bin 26 → M2 2.359 kn @ 165.5°
+  bin 10 → M2 1.935 kn @ 161.7°
+```
+
+Store references keyed by `(id, bin)`. Keying by `id` alone silently predicts from the
+wrong depth — and it will *pass* a single-station test whenever that station's reference
+happened to use the primary bin, then be ~50 min wrong elsewhere. Validate against a
+diverse batch: mixed regions, positive and negative offsets, ratios from 0.2 to 1.5.
+
+### `type: S` does not mean "use the offset reduction"
+
+Some type-S stations carry their **own** harmonic constituents, and NOAA predicts those
+**harmonically**. Applying the offset reduction to them overshoots badly:
+
+| PUG1716 predicted as | error vs NOAA |
+|---|---|
+| offset reduction | 89 min / 0.72 kn |
+| own harmonics | **6.8 min / 0.06 kn** |
+
+**Rule:** for any type-S station, fetch its own `harcon.json` at its `currbin` first. If
+it comes back non-empty, treat it as harmonic. Only fall back to
+`currentpredictionoffsets.json` for stations whose harcon is genuinely empty — the true
+table-subordinates.
+
+**How often does this bite?** Measured across the full US set (2026-07): **1 of 1,706**
+type-S stations — `PUG1716`, Waldron Island. Earlier notes of ours said "many"; that was
+generalizing from the single case we happened to hit. The rule still stands, because the
+check is one request you are already making and the cost of skipping it is an 89-minute
+error at whichever station it turns out to be. But calibrate your expectations: this is a
+rare-but-severe trap, not a widespread one.
+
+---
+
+## A correction
+
+One widely-repeated claim that **does not reproduce**, recorded here because acting on
+it costs real work.
+
+### "NOAA 404s the default fetch/curl User-Agent"
+
+**Not reproducible.** Tested 2026-07-19 from a residential connection with Node 24's
+built-in `fetch`, default User-Agent, against five endpoints:
+
+| endpoint | default UA | browser UA |
+|---|---|---|
+| `harcon.json` | 200, 10898 B | 200, 10898 B |
+| `datagetter` (`max_slack`) | 200, 2023 B | 200, 2023 B |
+| `stations.json` | 200, 3.75 MB | 200, 3.75 MB |
+| `currentpredictionoffsets.json` | 200, 375 B | 200, 375 B |
+
+Byte-identical responses. The original observation was almost certainly rate-limiting
+from high-volume probing, coinciding with a `currents_predictions` product outage on
+2026-07-18. This client still sends a browser User-Agent — it costs nothing and NOAA
+may well throttle unfamiliar clients under load — but **a missing User-Agent is not the
+cause of a 404 you are debugging.** Look at your `bin` first.
+
+The supported way to identify yourself is the `application` parameter on `datagetter`.
+
+### What *is* real about access
+
+- **Datacenter IPs are *not* blocked**, contrary to what we believed. A GitHub-hosted
+  runner fetched all four endpoint families — `stations.json` (3.75 MB), `harcon`,
+  `currentpredictionoffsets`, and `datagetter` — with 200s and byte counts identical to
+  a residential connection (2026-07-19). A **full US extraction also completes from a
+  GitHub-hosted runner** — 2,785 stations, ~2,800 paced requests, 25 minutes, zero
+  throttling failures — so this is safe to automate in CI.
+- **NOAA throttles bulk callers.** A full US extraction is thousands of requests. Pace
+  them (this client defaults to 400 ms) or you will get intermittent failures that look
+  like missing data.
+- **The predictions product does go down.** It was unavailable on 2026-07-18. If
+  `currents_predictions` returns "not available" for a station you believe is served,
+  check a known-good station before concluding anything about yours.
+
+---
+
+## Dead ends, ruled out
+
+- **XTide / Harmbase2 as the constituent source.** Unnecessary. NOAA publishes current
+  constituents directly, public domain, at `currbin`.
+- **`harcon.json?bin=0`.** Empty for currents. Always use `currbin`.
+- **`currents_predictions` for observation/survey stations.** Real-time buoys (e.g.
+  `cb0102`) aren't served by the predictions product; it is a published-tables product.
+  Note that station *type* alone doesn't tell you: PUG1717 is survey-flagged and **is**
+  served at bin 35. Ask the API rather than inferring.
+
+## Validating your own implementation
+
+Don't trust a currents engine that hasn't been diffed against NOAA. The method is
+self-contained, since both halves come from NOAA:
+
+1. Pull a station's constituents from `harcon.json` at its `currbin`.
+2. Pull NOAA's own `currents_predictions` (`interval=max_slack`) for a window.
+3. Predict that window from the constituents and diff the events.
+
+`noaa-current-stations golden` captures both halves into one fixture so the comparison
+replays offline. Expect ~10 min / 0.05 kn at a clean reversing station; see
+[validation.md](validation.md) for measured results and realistic tolerances.
+
+## Prior art
+
+- [`RyanCardin15/Perigee-Tides`](https://github.com/RyanCardin15/Perigee-Tides) — an MCP
+  server over the same API. Comparing its request format against ours confirmed the
+  request shape was never the problem, which is what pointed us at `currbin`.

package/docs/releasing.md

@@ -0,0 +1,27 @@
+# Releasing
+
+Each release ships the npm package (code, schema, and docs) and a minified
+`currents.json` GitHub release asset. The reviewable `currents.json` source bundle stays
+outside the npm tarball.
+
+```bash
+npm test
+npm run bundle:min
+npm run validate:bundle
+npm pack --dry-run
+
+mkdir -p /tmp/noaa-current-stations-release
+cp currents.min.json /tmp/noaa-current-stations-release/currents.json
+gh release create vX.Y.Z --notes "..."
+gh release upload vX.Y.Z /tmp/noaa-current-stations-release/currents.json
+gh release download vX.Y.Z --pattern currents.json --output /tmp/currents.json --clobber
+```
+
+Run `node bin/noaa-current-stations.mjs check` before releasing a stale bundle. The scheduled
+`update-stations` workflow creates a review issue when NOAA's station list changes.
+
+## First publish
+
+Publish `@openwaters/noaa-current-stations` once with an OTP, then configure npm Trusted
+Publishing for `openwatersio/noaa-current-stations`, workflow `publish.yml`, with no
+environment. Later GitHub releases publish through OIDC.

package/docs/schema.md

@@ -0,0 +1,107 @@
+# Bundle schema
+
+Machine-readable: [`schema/currents.schema.json`](../schema/currents.schema.json).
+
+A bundle is `{ note, generated, stations[] }`. Every station is either **harmonic** (has
+its own constituents) or **subordinate** (reduces against a harmonic reference).
+
+Units throughout: **speeds knots**, **directions degrees true**, **time offsets
+seconds**, **phases degrees Greenwich**.
+
+## Harmonic station
+
+```json
+{
+  "id": "PUG1717",
+  "name": "Turn Point, Boundary Pass",
+  "type": "harmonic",
+  "floodDirection": 23.2,
+  "ebbDirection": 203.2,
+  "offset": 0.297,
+  "constituents": [{ "name": "M2", "amplitude": 1.63, "phase": 295.3 }]
+}
+```
+
+| Field | From NOAA | Notes |
+|---|---|---|
+| `id` | station id | `id` at the primary bin, **`id@bin`** for a reference at another bin |
+| `floodDirection` | `azi` | major-axis azimuth — the flood set |
+| `ebbDirection` | `azi + 180` | the reciprocal |
+| `offset` | `majorMeanSpeed` | **Z₀**, signed net mean flow. Not optional — see below |
+| `constituents[].amplitude` | `majorAmplitude` | knots (`units=english`) |
+| `constituents[].phase` | `majorPhaseGMT` | Greenwich phase — pairs with a Greenwich V₀ |
+
+### Predicting from it
+
+Signed velocity along the major axis, at time *t*:
+
+```
+v(t) = Z₀ + Σ  fᵢ · Aᵢ · cos(ωᵢ·t + (V₀ᵢ + uᵢ) − φᵢ)
+```
+
+…the same sum-of-cosines as a tide station, with nodal corrections *f*, *u* applied as
+usual. Then:
+
+- **positive** velocity = flood, along `floodDirection`
+- **negative** = ebb, along `ebbDirection`
+- **max flood / max ebb** = the slope-zeros (extrema)
+- **slack** = the **value**-zeros — where `v(t)` crosses zero
+
+Label an extremum by the **sign of its velocity**, not by whether it's a curve high or
+low. With Z₀ applied, a relaxation peak during a long ebb is a local maximum but is
+still an ebb; NOAA labels it `maxEbb` and so should you.
+
+That `Z₀` term is why slack is where it is. Drop it and every zero crossing moves —
+measured at 15.6 min mean / 55 min worst error, versus 7.4 / 21 with it.
+
+## Subordinate station
+
+```json
+{
+  "id": "PCT0236",
+  "name": "…",
+  "type": "subordinate",
+  "reference": "SFB1201@10",
+  "floodDirection": 60, "ebbDirection": 240,
+  "slackBeforeFloodOffset": -720,
+  "slackBeforeEbbOffset": 480,
+  "floodTimeOffset": -300,
+  "ebbTimeOffset": 180,
+  "floodSpeedRatio": 0.7,
+  "ebbSpeedRatio": 1.2
+}
+```
+
+Predict the **reference** station's events, then transform each:
+
+| Event | Time shift | Speed |
+|---|---|---|
+| max flood | `+ floodTimeOffset` | `× floodSpeedRatio` |
+| max ebb | `+ ebbTimeOffset` | `× ebbSpeedRatio` |
+| slack before flood | `+ slackBeforeFloodOffset` | 0 |
+| slack before ebb | `+ slackBeforeEbbOffset` | 0 |
+
+Two traps:
+
+- **Two slack offsets.** A slack takes the offset for the phase it *precedes* — which
+  means you must know what follows it before you can place it.
+- **Speed fields are ratios**, multipliers on the reference peak. Not deltas.
+
+`reference` is a key into `stations[]` **including any `@bin` suffix**. Resolve it
+exactly; a reference station may appear at several bins with different constituents.
+
+## Not in the bundle
+
+- **Type-W (weak and variable / rotary) stations.** NOAA doesn't publish a usable
+  reversing model for them. The extractor counts them in `skipped.typeW` rather than
+  emitting something misleading.
+- **Subordinates whose reference didn't resolve.** Counted in `skipped.unresolvable`. A
+  healthy full-US run drops zero.
+- **Minor-axis constituents.** NOAA publishes `minorAmplitude`/`minorPhaseGMT` for a 2D
+  rotary model; a major-axis model doesn't use them, so they aren't carried per station.
+  Bundling them was measured and rejected — worth a median 4% of peak speed, and a 2D
+  magnitude series never crosses zero, which silently yields no slack events at all.
+
+  The bundle does carry a **`crossFlow` census** at the root: how much perpendicular flow
+  the major-axis model drops, and the worst station by ratio and by knots. `validate`
+  fails a bundle whose worst ratio exceeds 0.5.