git clone https://github.com/aniruddhaadak80/swellread
cd swellread
npm ci
npm run dev

npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm test            # vitest — 137 deterministic tests
npm run build       # next build
npm run check       # all three gates in sequence

curl -s "https://swellread.vercel.app/api/conditions?breakId=pago-pago&hour=8" | head -c 400

{
  "status": "live",                       // "live" | "mixed" | "fallback" — never hidden
  "snapshot": {
    "date": "2026-10-03",
    "hours": [ /* 24 normalised hourly rows */ ],
    "sources": [
      { "id": "open-meteo-marine", "status": "live", "stale": false, "url": "https://open-meteo.com/…" },
      { "id": "noaa-coops",        "status": "live", "stale": false, "url": "https://tidesandcurrents.noaa.gov/…" }
    ]
  },
  "points": [ { "localLabel": "08:00", "score": 0.68, "band": "worth-the-drive", "tideM": 0.17 } ]
}

# the real verdict for one hour
curl -s "https://swellread.vercel.app/api/engine?breakId=pago-pago&hour=8"

# "what if the tide were 2.4 m?" — never writes anything back
curl -s -X POST "https://swellread.vercel.app/api/engine" \
  -H "content-type: application/json" \
  -d '{"breakId":"pago-pago","hour":8,"tideM":2.4}'

{
  "whatIf": { "tideM": 2.4 },
  "engine": {
    "version": "swellread-engine/2026.10.1",
    "score": 0.68,
    "band": "worth-the-drive",
    "factors": [
      {
        "key": "peelSpeed", "available": true, "raw": 21.1, "rawLabel": "21.1 km/h",
        "weight": 0.2, "effectiveWeight": 0.2, "contribution": 0.1806,
        "evidence": "c = sqrt(g · depth) = sqrt(9.81 · 4.60 m) = 21.1 km/h over a 4.60 m take-off…"
      }
    ],
    "gates": [],
    "derived": { "breakHeightM": 0.9, "peelSpeedKmh": 21.1, "powerKwM": 14.1, "depthAtBreakM": 4.6 },
    "window": { "bestStart": "…", "goodHours": ["…"] },
    "seal": "700589816acc…"
  }
}

BASE=https://swellread.vercel.app

# 1. create (the response carries the first audit seal)
ID=$(curl -s -X POST "$BASE/api/sessions" \
  -H "content-type: application/json" \
  -d '{"breakId":"pago-pago","plannedFor":"2026-10-03T18:00:00.000Z","status":"committed","idempotencyKey":"demo-1"}' \
  | sed -n 's/.*"id":"\([^"]*\)".*/\1/p')
echo "created $ID"

# 2. read back
curl -s "$BASE/api/sessions/$ID" | head -c 300

# 3. update — bumps the version and appends a sealed event
curl -s -X PATCH "$BASE/api/sessions/$ID" \
  -H "content-type: application/json" -d '{"call":"in","confidence":4}'

# 4. log a ride from the WebGL lab
curl -s -X POST "$BASE/api/sessions/$ID/rides" \
  -H "content-type: application/json" \
  -d '{"durationSec":210,"longestRideSec":42,"topSpeedKmh":28.4,"completed":true}'

# 5. replay the integrity chain
curl -s "$BASE/api/integrity/$ID" | head -c 300

# 6. export the brief as a file
curl -s "$BASE/api/brief/$ID?format=json" -o brief.json

# 7. soft delete — keeps a tombstone so the chain still replays
curl -s -X DELETE "$BASE/api/sessions/$ID"

curl -s https://swellread.vercel.app/api/health

{
  "ok": true,
  "store": { "kind": "neon", "productionStore": true, "label": "Hosted Postgres (Neon serverless driver)" },
  "persistence": { "probe": "SELECT 1 succeeded; sessions table holds 12 row(s)" }
}

curl -s https://swellread.vercel.app/api/mcp \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "serverInfo": { "name": "Swellread", "engineVersion": "swellread-engine/2026.10.1" },
    "capabilities": { "tools": { "listChanged": false } }
  }
}

{
  "mcpServers": {
    "swellread": {
      "type": "http",
      "url": "https://swellread.vercel.app/api/mcp"
    }
  }
}

graph LR
  Browser["Visitor"]:::live
  Pages["Server pages<br/>landing, breaks, sessions"]:::ai
  Client["Client islands<br/>tide drag, lab, console"]:::live
  API["REST routes"]:::agent
  MCP["MCP JSON-RPC"]:::agent
  Service["Service layer<br/>one write path"]:::ai
  Engine["Engine<br/>scoreHour"]:::ai
  DB["Postgres<br/>Neon in prod"]:::risk
  Feed["NOAA + Open-Meteo<br/>keyless"]:::warn
  Audit["Audit chains<br/>SHA-384"]:::agent
  Model["MiniLM<br/>in the tab"]:::ai

  Browser --> Pages
  Browser --> Client
  Client --> API
  Browser --> MCP
  API --> Service
  MCP --> Service
  Service --> Engine
  Service --> DB
  Service --> Audit
  Engine --> Feed
  Service --> Feed
  Browser --> Model
  Engine -.->|seal| Audit
  API --> Service

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef warn fill:#fbbf24,stroke:#b45309,color:#451a03
  classDef risk fill:#fb7185,stroke:#be123c,color:#4c0519

graph TB
  Land["Open today"]:::live
  Pick["Pick a break and an hour"]:::live
  Drag["Drag the tide<br/>see the peel change"]:::ai
  Commit["Commit the window"]:::agent
  Inspect["Inspect the frozen<br/>snapshot and factors"]:::ai
  Ride["Ride it in the lab<br/>log the ride"]:::live
  Recall["Feel match<br/>find earlier sessions"]:::ai
  Brief["Export the brief"]:::agent
  Share["Hand it to a friend"]:::agent
  Delete["Delete, keeping<br/>a replayable tombstone"]:::risk

  Land --> Pick --> Drag --> Commit --> Inspect
  Inspect --> Ride --> Recall --> Brief --> Share
  Inspect --> Delete

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef risk fill:#fb7185,stroke:#be123c,color:#4c0519

graph TB
  NOAA["NOAA CO-OPS<br/>predictions, MLLW"]:::warn
  Meteo["Open-Meteo<br/>marine + forecast"]:::warn
  Norm["Normalise<br/>nested hourly arrays"]:::ai
  Join["Join on the UTC hour"]:::ai
  Tally["Hourly slice<br/>+ tide rate"]:::ai
  Status["Status per source<br/>live or fallback"]:::agent
  Used["Snapshot used<br/>by pages and MCP"]:::live
  Sample["Sealed sample<br/>dated, synthetic"]:::risk
  Drop["Drop the factor,<br/>renormalise"]:::risk
  Engine["Engine"]:::ai

  NOAA --> Norm
  Meteo --> Norm
  Norm --> Join --> Tally --> Status --> Used
  Norm -.->|all upstreams failed| Sample --> Used
  Join -.->|no station in range| Drop --> Engine
  Used --> Engine

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef warn fill:#fbbf24,stroke:#b45309,color:#451a03
  classDef risk fill:#fb7185,stroke:#be123c,color:#4c0519

graph TB
  In["Hour + break"]:::live
  Phys["Green's law<br/>Hb = Hs0·(γ·tanβ)^¼"]:::ai
  Cap["Cap by water<br/>min Hb, γ·depth"]:::ai
  Peel["Peel speed<br/>c = √(g·depth)"]:::ai
  Pow["Power<br/>⅟₁₆ρgHs²Tp"]:::ai
  Wind["Wind alignment<br/>× speed envelope"]:::ai
  Dir["Direction match"]:::ai
  Per["Period cleanliness"]:::ai
  Renorm["Renormalise over<br/>available factors"]:::ai
  Sum["Weighted score"]:::ai
  Gates["Hard gates<br/>flat, exposed, blown out"]:::risk
  Band["Band + seal"]:::agent
  Window["Best window"]:::agent

  In --> Phys --> Cap --> Peel
  In --> Pow
  In --> Wind
  In --> Dir
  In --> Per
  Peel --> Renorm
  Pow --> Renorm
  Wind --> Renorm
  Dir --> Renorm
  Per --> Renorm
  Renorm --> Sum --> Gates --> Band --> Window

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef risk fill:#fb7185,stroke:#be123c,color:#4c0519

graph TB
  Create["session.create<br/>seq 1, prev = genesis"]:::agent
  Update["session.decide<br/>seq 2, prev = seal 1"]:::agent
  Ride["ride.log<br/>seq 3"]:::agent
  Kill["session.delete<br/>tombstone kept"]:::risk
  Can["canonicalJson<br/>sorted keys"]:::ai
  Seal["seal_n = SHA-384<br/>prevSeal ‖ body"]:::ai
  Chain["Append-only chain"]:::agent
  Replay["Replay endpoint<br/>first broken link"]:::ai
  Verify["verify_integrity<br/>via MCP too"]:::agent

  Create --> Update --> Ride --> Kill
  Create --> Can --> Seal
  Update --> Can
  Ride --> Can
  Kill --> Can
  Seal --> Chain
  Chain --> Replay --> Verify

  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef risk fill:#fb7185,stroke:#be123c,color:#4c0519

seal_n = SHA-384( UTF-8(prevSeal) || canonicalJson(event_n) )
genesis = 96 zeros

graph LR
  Real["Real Hs, Tp, direction"]:::live
  Break["Depth from tide"]:::live
  Gerstner["Gerstner sum<br/>4 components"]:::ai
  Shoal["Shoal where shallow"]:::ai
  Break2["Break where H/d ≥ 0.78"]:::ai
  Foam["Foam behind the peel"]:::warn
  Peel3["Peel at c = √(g·depth)"]:::ai
  You["You: steer, pump, kick out"]:::agent
  Ride["Ride result"]:::agent
  Save["POST /rides"]:::agent

  Real --> Gerstner
  Break --> Gerstner
  Gerstner --> Shoal --> Break2 --> Foam
  Break2 --> Peel3
  Peel3 --> You --> Ride --> Save
  You --> Gerstner

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef warn fill:#fbbf24,stroke:#b45309,color:#451a03

graph TB
  Agent["Any MCP client"]:::agent
  Init["initialize"]:::agent
  List["tools/list"]:::agent
  Read["analyse_break<br/>read + seal"]:::ai
  Create["create_session<br/>idempotent"]:::ai
  Service2["Same service layer<br/>as the web UI"]:::agent
  Row["Row + audit link"]:::agent
  Read2["GET /sessions/:id"]:::live
  Verify["verify_integrity"]:::agent
  Clean["delete_session<br/>tombstone"]:::risk

  Agent --> Init --> List --> Read
  Read --> Create --> Service2 --> Row
  Service2 --> Read2
  Row --> Read2
  Read2 --> Verify
  Read2 --> Clean

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef risk fill:#fb7185,stroke:#be123c,color:#4c0519

graph LR
  Push["Push to main"]:::live
  CI["GitHub Actions<br/>typecheck, lint, test, build"]:::agent
  Vercel["Vercel production"]:::agent
  Env["DATABASE_URL"]:::warn
  Neon["Hosted Postgres"]:::ai
  Live["Public alias"]:::live
  Verify["verify-live.mjs"]:::ai
  Smoke["browser-smoke.mjs"]:::ai

  Push --> CI --> Vercel
  Env --> Vercel
  Neon --> Env
  Vercel --> Live
  Live --> Verify
  Live --> Smoke
  Verify --> Push

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef warn fill:#fbbf24,stroke:#b45309,color:#451a03

# 36 assertions: health, live data, CRUD, idempotency, engine, MCP, integrity,
# delete, the repository link in nav and footer, and every primary route.
SWELLREAD_BASE_URL=https://swellread.vercel.app npm run verify

# 14 assertions through real visible controls: the tide drag, committing a
# session, deciding, the brief, the agent console, delete, keyboard focus,
# the WebGL ride loop, mobile, reduced motion — and zero console errors.
SWELLREAD_BASE_URL=https://swellread.vercel.app node scripts/browser-smoke.mjs

graph TB
  A["Keyless NOAA + Open-Meteo"]:::live
  B["Six-factor explainable engine"]:::ai
  C["Tide drag + cross-section"]:::live
  D["WebGL ride lab"]:::live
  E["Sealed sessions + brief"]:::agent
  F["MCP with 8 tools"]:::agent
  G["In-browser MiniLM"]:::ai
  H["137 tests + 2 verifiers"]:::agent
  A --> B --> C --> D
  B --> E --> F
  E --> G
  E --> H

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22

graph TB
  A["Wider break coverage<br/>more tide stations"]:::live
  B["Riders you can trust<br/>per-user feel model"]:::ai
  C["Saved watchlists<br/>alert me when it hits"]:::agent
  D["Buoy observations<br/>blend measured with modelled"]:::warn
  E["WebGPU renderer<br/>for bigger meshes"]:::ai
  F["Export the brief as a<br/>signed image card"]:::agent
  A --> C
  B --> C
  D --> A
  E --> D
  C --> F

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef warn fill:#fbbf24,stroke:#b45309,color:#451a03

graph TB
  A["Instrument the reef<br/>crowd and hazard context"]:::risk
  B["Regional ensembles<br/>probability, not a verdict"]:::ai
  C["Pass to pass<br/>session hand-over"]:::live
  D["Open dataset<br/>of sealed sessions"]:::agent
  E["Local-first offline mode<br/>sync when you surface"]:::ai
  A --> B
  C --> D
  B --> D
  D --> E

  classDef live fill:#22d3ee,stroke:#0e7490,color:#083344
  classDef ai fill:#a78bfa,stroke:#6d28d9,color:#2e1065
  classDef agent fill:#34d399,stroke:#047857,color:#022c22
  classDef risk fill:#fb7185,stroke:#be123c,color:#4c0519