Document SPC convective outlook behavior

docs/integrations/weatherapi.md

@@ -60,6 +60,60 @@ Alerts do not receive `precision` or `tz`. Weather story requests receive only
 `format=json`. SPC convective outlook requests receive only `format=json` and
 `tz`; they do not receive `units` or `precision`.
 
+## SPC Convective Outlooks
+
+The adapter fetches SPC convective outlook data from:
+
+```text
+GET /outlooks/convective?format=json&tz=<weather_api.timezone>
+```
+
+The response uses the standard `data` envelope. `data: null` means no latest
+run is available and follows missing-source policy. A non-null object with
+empty `outlooks` and `discussions` arrays is accepted as checked empty data.
+
+Run fields consumed by weatherreporter:
+
+- `locationId`
+- `locationName`
+- `asOf`
+- `issuedAt`
+- `updatedAt`
+- `product`
+- `outlooks`
+- `discussions`
+
+Outlook fields consumed:
+
+- `id`
+- `provider`
+- `product`
+- `day`
+- `outlookType`
+- `label`
+- `labelText`
+- `forecaster`
+- `severityRank`
+- `validFrom`
+- `validTo`
+- `issuedAt`
+- `expiresAt`
+- `sourceUrl`
+- `imageUrl`
+- `containsLocation`
+- `geometry`
+
+Discussion fields consumed:
+
+- `day`
+- `headline`
+- `summary`
+- `discussion`
+- `updatedAt`
+
+GeoJSON `geometry` is decoded into collected weather facts and persisted in
+bundle/debug artifacts, but prompt-facing SPC module output omits geometry.
+
 ## Endpoints Used
 
 The adapter fetches these endpoints once per bundle:
@@ -126,8 +180,8 @@ warnings list.
 
 ## Compatibility Assumptions
 
-The adapter expects payload fields compatible with the internal forecast bundle
-types in `internal/forecast/bundle.go`, including:
+The adapter expects payload fields compatible with the internal weather data
+bundle types in `internal/weatherdata/bundle.go`, including:
 
 - observation timestamps and observation values
 - current condition values

docs/internal/briefing.md

@@ -61,6 +61,17 @@ builders run. Configured `location` values are prompt context only; Weather API
 `area_forecast_discussion` uses optional `sections` configuration to include a
 subset of discussion fields.
 
+`spc_convective_outlooks` uses collected SPC run metadata and derived
+report-period outlooks. It emits `checked: true` for a successfully fetched
+empty run, reports `outlook_count`, and includes prompt-facing outlook fields
+such as risk label, severity rank, valid times, source URL, image URL, and
+whether the outlook contains the configured location. It does not emit GeoJSON
+geometry.
+
+`spc_convective_discussion` uses the same derived report-period outlooks and
+discussion records. It is omitted unless at least one retained outlook has
+severity rank `3` or higher and matching discussion text exists.
+
 ## External Adapters Used
 
 None directly.
@@ -91,8 +102,8 @@ return an error for invalid required inputs.
 - SPC convective outlook output distinguishes checked empty outlook data from
   missing outlook source data and omits GeoJSON geometry from prompt-facing
   fields.
-- SPC convective discussion output is omitted unless a retained outlook meets
-  the internal severity threshold and matching discussion text is available.
+- SPC convective discussion output is omitted unless a retained outlook has
+  severity rank `3` or higher and matching discussion text is available.
 
 ## Tests
 

docs/internal/facts.md

@@ -21,7 +21,8 @@ Outputs:
 
 - `facts.CollectedFacts` with normalized source facts plus separate source
   provenance and warnings. SPC convective outlook source data is carried
-  through when present in the bundle.
+  through when present in the bundle, including upstream geometry and source
+  provenance.
 - `facts.DerivedFacts` with valid-period forecast slices, alert overlaps,
   report-period SPC convective outlooks and discussions, daily summaries,
   daypart summaries, and Storm Report window summary
@@ -33,6 +34,9 @@ Outputs:
 - SPC convective outlook derivation selects already-collected outlooks whose
   half-open valid intervals overlap the resolved report period and retains
   discussions for represented outlook days.
+- Derived SPC outlook records preserve the collected outlook fields, including
+  geometry, for downstream components that need source-level facts. Prompt
+  modules decide which fields are exposed to Scriptorium.
 - It does not fetch upstream data, build prompt wording, compare prior
   snapshots, write workflow state, invoke Scriptorium, or define modules.
 
@@ -75,8 +79,8 @@ Inspect:
 
 - Collected facts are built once from a fetched bundle.
 - Derived facts are scoped to one resolved report.
-- SPC convective outlook selection uses the resolved report period, not
-  server-current active filtering.
+- SPC convective outlook selection uses the resolved report period and the
+  already-collected outlook run.
 - Source provenance and warnings stay separate from ordinary fact fields.
 - Prompt-specific wording and one-off presentation decisions stay outside this
   package.

docs/internal/module.md

@@ -49,7 +49,9 @@ unknown or unimplemented module IDs fail validation instead of being skipped.
 
 ## Options
 
-Most modules use an empty options struct. `area_forecast_discussion` accepts:
+Most modules use an empty options struct, including
+`spc_convective_outlooks` and `spc_convective_discussion`.
+`area_forecast_discussion` accepts:
 
 ```yaml
 sections:
@@ -63,6 +65,28 @@ An omitted or empty `sections` list includes all available discussion sections.
 Invalid option shapes fail during config normalization or composition
 validation.
 
+## SPC Convective Module Outputs
+
+`spc_convective_outlooks` emits a prompt-facing risk-product stanza with:
+
+- `checked`
+- `as_of`
+- `issued_at`
+- `location_id`
+- `location_name`
+- `outlook_count`
+- `outlooks`
+
+Each outlook entry may include `day`, `outlook_type`, `label`, `label_text`,
+`severity_rank`, `valid_start`, `valid_end`, `issued_at`, `expires_at`,
+`contains_location`, `source_url`, and `image_url`. It omits GeoJSON geometry.
+
+`spc_convective_discussion` emits a narrative stanza only when a retained
+report-period outlook has severity rank `3` or higher and matching discussion
+text is available. Its output includes `included_because` and `discussions`;
+each discussion may include `day`, `headline`, `summary`, `discussion`, and
+`updated_at`.
+
 ## Boundaries
 
 - This package owns module identifiers, config item envelopes, output

docs/internal/prompt-input.md

@@ -68,9 +68,13 @@ Within each category, stanza order follows the module snapshot output order.
 Current categories are:
 
 - `applicable_risk_products`: location-applicable alerts, warnings, outlooks,
-  discussions, and similar risk products.
+  and similar risk products. Current stanzas include `alert_digest` and
+  `spc_convective_outlooks`.
 - `derived_summaries`: deterministic summaries and calculated report facts.
 - `narrative_products`: official narrative text products and forecast stories.
+  Current stanzas include `narrative_forecast`,
+  `area_forecast_discussion`, `spc_convective_discussion`, and
+  `weather_story`.
 - `raw_data`: minimally transformed underlying weather data.
 
 ## Boundaries

docs/internal/weather-data.md

@@ -60,6 +60,14 @@ non-null `/outlooks/convective` responses with empty outlook and discussion
 arrays represent checked empty outlook data.
 `app.FetchAndSaveBundle` can write bundle JSON atomically for inspection.
 
+SPC convective outlook data is stored on
+`weatherdata.Bundle.SPCConvectiveOutlooks`. The collected run keeps upstream
+run metadata, location identifiers, ordered outlook records, discussion
+records, and each outlook's raw GeoJSON geometry. Source provenance for this
+payload uses the `spc_convective_outlooks` source name, endpoint
+`/outlooks/convective`, the query sent by the adapter, timestamps, and a hash
+of the raw `data` object.
+
 ## Skip And Resume Behavior
 
 No resume behavior. Optional missing or malformed sources may be omitted,