Document outlook v2 behavior

docs/api.md

@@ -230,19 +230,22 @@ GET /outlooks/convective/location
 ```
 
 Returns the latest SPC convective outlook run reconstructed from
-weatherfeeder-owned Postgres tables.
+weatherfeeder-owned `weather.outlook.v2` Postgres tables.
 
 Route behavior:
 
-- `/outlooks/convective` returns the latest run with all stored outlook
-  polygons unless user filters are supplied.
+- `/outlooks/convective` returns the latest run with stored location-filtered
+  outlook polygons unless user filters are supplied.
 - `/outlooks/convective/active` adds an active-time filter using the server's
   current UTC time. Outlooks are active when `validFrom <= now < validTo`.
 - `/outlooks/convective/location` adds the same active-time filter and
-  `containsLocation=true`.
+  `containsLocation=true`. It remains as an active local-outlook compatibility
+  route under the v2 weatherfeeder contract.
 
 When no latest run exists, `data` is null. When a run exists but filters match
-no outlooks, `data` remains an object and `outlooks` is an empty array.
+no outlooks, `data` remains an object and `outlooks` and `discussions` are
+empty arrays. Outlook endpoints use latest-run semantics and do not accumulate
+historical active outlooks across older runs.
 
 Query parameters:
 
@@ -253,9 +256,12 @@ Query parameters:
 | `outlookType` | all outlook routes | `categorical`, `tornado`, `hail`, or `wind` |
 | `containsLocation` | `/outlooks/convective`, `/outlooks/convective/active` | boolean |
 
-`outlookType` values are normalized case-insensitively. `containsLocation` is
-rejected on `/outlooks/convective/location` because that route always applies
-`containsLocation=true`. `precision` and unknown parameters are rejected.
+`outlookType` values are normalized case-insensitively. Weatherfeeder v2
+outlooks are already filtered for the configured location, so
+`containsLocation` is expected to be true for stored v2 outlooks.
+`containsLocation` is rejected on `/outlooks/convective/location` because that
+route always applies `containsLocation=true`. `precision` and unknown
+parameters are rejected.
 
 Run `data` fields:
 
@@ -266,6 +272,7 @@ Run `data` fields:
 | `asOf` | RFC3339 datetime | required when `data` is not null |
 | `issuedAt` | RFC3339 datetime | optional |
 | `outlooks` | array | ordered outlook polygons, possibly empty |
+| `discussions` | array | ordered day-level discussions, possibly empty |
 
 Outlook fields:
 
@@ -280,10 +287,20 @@ Outlook fields:
 | `containsLocation` | boolean | whether the outlook polygon contains the configured location |
 | `geometry` | GeoJSON | stored outlook geometry |
 
+Discussion fields:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `day` | integer | SPC outlook day |
+| `headline`, `summary`, `discussion` | string | optional |
+| `updatedAt` | RFC3339 datetime | optional |
+
 GeoJSON coordinates use standard GeoJSON coordinate order: longitude, then
 latitude. Timezone conversion applies to run `asOf`, run `issuedAt`, and each
-outlook's `validFrom`, `validTo`, `issuedAt`, and `expiresAt`. Active filtering
-compares instants and is not changed by the presentation timezone.
+outlook's `validFrom`, `validTo`, `issuedAt`, and `expiresAt`, and discussion
+`updatedAt`. Active filtering compares instants and is not changed by the
+presentation timezone. Endpoint filters also filter `discussions` to days
+represented by retained outlooks.
 
 Examples:
 
@@ -328,6 +345,15 @@ Example JSON response:
           ]
         }
       }
+    ],
+    "discussions": [
+      {
+        "day": 1,
+        "headline": "Severe storms possible",
+        "summary": "Scattered severe storms are possible.",
+        "discussion": "SPC discussion text.",
+        "updatedAt": "2026-06-11T17:30:00Z"
+      }
     ]
   }
 }
@@ -354,10 +380,25 @@ Example location-filtered JSON response:
         "expiresAt": "2026-06-12T12:00:00Z",
         "containsLocation": true,
         "geometry": {
-          "type": "Point",
-          "coordinates": [-90.2, 38.6]
+          "type": "Polygon",
+          "coordinates": [
+            [
+              [-90.6, 38.4],
+              [-90.0, 38.4],
+              [-90.0, 38.8],
+              [-90.6, 38.4]
+            ]
+          ]
         }
       }
+    ],
+    "discussions": [
+      {
+        "day": 1,
+        "headline": "Tornado risk near the configured location",
+        "discussion": "SPC tornado outlook discussion text.",
+        "updatedAt": "2026-06-11T17:30:00Z"
+      }
     ]
   }
 }