Add policy documents and a roadmap to implement a full documentation set

API.md

@@ -37,14 +37,28 @@ Examples:
 
 ## Canonical schemas
 
-weatherfeeder emits three canonical domain schemas:
+weatherfeeder emits five canonical domain schemas:
 
 - `weather.observation.v1`
 - `weather.forecast.v1`
+- `weather.forecast_discussion.v1`
+- `weather.weather_story.v1`
 - `weather.alert.v1`
 
 Each payload is described below using the JSON field names as the contract.
 
+### Raw upstream schemas
+
+weatherfeeder sources also emit provider-specific raw schemas before normalization.
+Relevant raw source schemas include:
+
+- `raw.nws.forecast_discussion.v1`
+  - payload type: string
+  - payload contents: exact fetched HTML response body
+- `raw.nws.weatherstories.v1`
+  - payload type: object
+  - payload contents: exact fetched JSON response body
+
 ---
 
 ## Shared Conventions
@@ -80,34 +94,18 @@ A `WeatherObservation` represents a point-in-time observation for a station/loca
 | `stationName` | string | no | Human station name |
 | `timestamp` | timestamp string | yes | Observation timestamp |
 | `conditionCode` | int | yes | WMO code (`-1` unknown) |
-| `conditionText` | string | no | Canonical short condition text |
 | `isDay` | bool | no | Day/night hint |
-| `providerRawDescription` | string | no | Provider-specific evidence text |
+| `textDescription` | string | no | Human-facing short description |
-| `textDescription` | string | no | Legacy/transitional text description |
-| `iconUrl` | string | no | Legacy/transitional icon URL |
 | `temperatureC` | number | no | Celsius |
 | `dewpointC` | number | no | Celsius |
 | `windDirectionDegrees` | number | no | Degrees |
 | `windSpeedKmh` | number | no | km/h |
 | `windGustKmh` | number | no | km/h |
 | `barometricPressurePa` | number | no | Pascals |
-| `seaLevelPressurePa` | number | no | Pascals |
 | `visibilityMeters` | number | no | Meters |
 | `relativeHumidityPercent` | number | no | Percent |
 | `apparentTemperatureC` | number | no | Celsius |
-| `elevationMeters` | number | no | Meters |
-| `rawMessage` | string | no | Provider raw message (for example METAR) |
 | `presentWeather` | array | no | Provider-specific structured weather fragments |
-| `cloudLayers` | array | no | Cloud layer details |
-
-### Nested: `cloudLayers[]`
-
-Each `cloudLayers[]` element:
-
-| Field | Type | Required | Notes |
-|---|---:|:---:|---|
-| `baseMeters` | number | no | Cloud base altitude in meters |
-| `amount` | string | no | Provider string (e.g. FEW/SCT/BKN/OVC) |
 
 ### Nested: `presentWeather[]`
 
@@ -158,12 +156,8 @@ A `WeatherForecastPeriod` is valid for `[startTime, endTime)`.
 | `endTime` | string (timestamp) | yes | Period end |
 | `name` | string | no | Human label (often empty for hourly) |
 | `isDay` | bool | no | Day/night hint |
-| `conditionCode` | int | yes | WMO code (`-1` for unknown) |
+| `conditionCode` | int | no | WMO code when applicable (`-1` for unknown) |
-| `conditionText` | string | no | Canonical short text |
-| `providerRawDescription` | string | no | Provider-specific “evidence” text |
 | `textDescription` | string | no | Human-facing short phrase |
-| `detailedText` | string | no | Longer narrative |
-| `iconUrl` | string | no | Legacy/transitional |
 | `temperatureC` | number | no | °C |
 | `temperatureCMin` | number | no | °C (aggregated products) |
 | `temperatureCMax` | number | no | °C (aggregated products) |
@@ -237,11 +231,73 @@ A run may contain zero, one, or many alerts.
 
 ---
 
+## Schema: `weather.weather_story.v1`
+
+Payload type: `WeatherStoryRun`
+
+A `WeatherStoryRun` is a snapshot of NWS weather stories for an office as-of a point in time.
+The run may contain zero, one, or many stories.
+
+### Fields
+
+| Field | Type | Required | Notes |
+|---|---:|:---:|---|
+| `officeId` | string | no | NWS office identifier, e.g. `LSX` |
+| `asOf` | string (timestamp) | yes | Latest story update time or source fallback |
+| `stories` | array | yes | Weather stories (order provider-dependent) |
+
+### Nested: `stories[]` (`WeatherStory`)
+
+| Field | Type | Required | Notes |
+|---|---:|:---:|---|
+| `officeId` | string | no | NWS office identifier |
+| `startTime` | string (timestamp) | yes | Story validity start |
+| `endTime` | string (timestamp) | yes | Story validity end |
+| `updatedAt` | string (timestamp) | yes | Story update time |
+| `title` | string | no | Human story title |
+| `description` | string | no | Story narrative text |
+| `altText` | string | no | Accessibility text for the provider graphic |
+| `priority` | bool | yes | Provider priority flag |
+| `order` | int | yes | Provider display order |
+| `downloadUrl` | string | no | Provider download URL; weatherfeeder does not fetch the asset |
+
+---
+
+## Schema: `weather.forecast_discussion.v1`
+
+Payload type: `WeatherForecastDiscussion`
+
+A `WeatherForecastDiscussion` is an issued narrative bulletin for an NWS office.
+It is distinct from `weather.forecast.v1`, which is period-based.
+
+### Fields
+
+| Field | Type | Required | Notes |
+|---|---:|:---:|---|
+| `officeId` | string | no | NWS office identifier, e.g. `LSX` |
+| `officeName` | string | no | Human office name |
+| `product` | string | yes | Currently `afd` |
+| `issuedAt` | string (timestamp) | yes | Bulletin issue time |
+| `updatedAt` | string (timestamp) | no | Optional page/update timestamp |
+| `keyMessages` | array | no | Ordered key-message bullet list |
+| `shortTerm` | object | no | Short-term discussion section |
+| `longTerm` | object | no | Long-term discussion section |
+
+### Nested: `shortTerm` / `longTerm`
+
+| Field | Type | Required | Notes |
+|---|---:|:---:|---|
+| `qualifier` | string | no | Header qualifier such as `(Through Late Sunday Night)` |
+| `issuedAt` | string (timestamp) | no | Optional section-local issue time |
+| `text` | string | no | Paragraph-preserved prose text |
+
+---
+
 ## Compatibility rules
 
 - Consumers **must** ignore unknown fields.
 - Producers (weatherfeeder) prefer **additive changes** within a schema version.
-- Renames/removals/semantic breaks require a **schema version bump** (`weather.*.v2`).
+- Renames/removals/semantic breaks normally require a **schema version bump** (`weather.*.v2`); pre-1.0 projects may choose in-place changes.
 
 ---
 
@@ -259,7 +315,7 @@ A run may contain zero, one, or many alerts.
     "stationId": "KSTL",
     "timestamp": "2026-01-17T14:00:00Z",
     "conditionCode": 1,
-    "conditionText": "Mainly Sunny",
+    "textDescription": "Mainly Sunny",
     "temperatureC": 3.25,
     "windSpeedKmh": 18.5
   }
@@ -285,7 +341,7 @@ A run may contain zero, one, or many alerts.
         "startTime": "2026-01-17T14:00:00Z",
         "endTime": "2026-01-17T15:00:00Z",
         "conditionCode": 2,
-        "conditionText": "Partly Cloudy",
+        "textDescription": "Partly Cloudy",
         "temperatureC": 3.5,
         "probabilityOfPrecipitationPercent": 10
       }
@@ -317,3 +373,32 @@ A run may contain zero, one, or many alerts.
   }
 }
 ```
+
+### Weather story event (`weather.weather_story.v1`)
+
+```json
+{
+  "id": "nws:weatherstories:2026-05-30T09:00:34Z",
+  "schema": "weather.weather_story.v1",
+  "source": "nws_weatherstories",
+  "effectiveAt": "2026-05-30T09:00:34Z",
+  "payload": {
+    "officeId": "LSX",
+    "asOf": "2026-05-30T09:00:34Z",
+    "stories": [
+      {
+        "officeId": "LSX",
+        "startTime": "2026-05-30T08:46:00Z",
+        "endTime": "2026-05-31T11:00:00Z",
+        "updatedAt": "2026-05-30T09:00:34Z",
+        "title": "Several Chances for Rain Through Monday",
+        "description": "Scattered showers and thunderstorms remain possible.",
+        "altText": "This slide shows the forecast for today through Tuesday.",
+        "priority": false,
+        "order": 1,
+        "downloadUrl": "https://api.weather.gov/offices/LSX/weatherstories/download/3228e499-2aae-45a8-9ff9-1c060311026f"
+      }
+    ]
+  }
+}
+```

README.md

@@ -14,6 +14,8 @@ Canonical domain schemas emitted after normalization:
 
 - `weather.observation.v1` → `WeatherObservation`
 - `weather.forecast.v1` → `WeatherForecastRun`
+- `weather.forecast_discussion.v1` → `WeatherForecastDiscussion`
+- `weather.weather_story.v1` → `WeatherStoryRun`
 - `weather.alert.v1` → `WeatherAlertRun`
 
 For the complete wire contract (event envelope + payload schemas, fields, units, and compatibility rules), see:
@@ -22,7 +24,7 @@ For the complete wire contract (event envelope + payload schemas, fields, units,
 
 ## Upstream providers (current MVP)
 
-- NWS: observations, hourly forecasts, alerts
+- NWS: observations, hourly forecasts, narrative forecasts, forecast discussions, weather stories, alerts
 - Open-Meteo: observations, hourly forecasts
 - OpenWeather: observations
 

cmd/weatherfeeder/config.yml

@@ -1,7 +1,8 @@
 ---
 sources:
   - name: NWSObservationKSTL
-    kind: observation
+    mode: poll
+    kinds: ["observation"]
     driver: nws_observation
     every: 10m
     params:
@@ -9,15 +10,17 @@ sources:
       user_agent: "HomeOps (eric@maximumdirect.net)"
 
 #  - name: OpenMeteoObservation
-#    kind: observation
+#    mode: poll
+#    kinds: ["observation"]
 #    driver: openmeteo_observation
 #    every: 10m
 #    params:
-#      url: "https://api.open-meteo.com/v1/forecast?latitude=38.6239&longitude=-90.3571&current=temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m,wind_direction_10m,precipitation,surface_pressure,rain,showers,snowfall,cloud_cover,apparent_temperature,is_day,wind_gusts_10m,pressure_msl&forecast_days=1"
+#      url: "https://api.open-meteo.com/v1/forecast?latitude=38.6239&longitude=-90.3571&current=temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m,wind_direction_10m,precipitation,surface_pressure,rain,showers,snowfall,cloud_cover,apparent_temperature,is_day,wind_gusts_10m,pressure_msl"
 #      user_agent: "HomeOps (eric@maximumdirect.net)"
 
 #  - name: OpenWeatherObservation
-#    kind: observation
+#    mode: poll
+#    kinds: ["observation"]
 #    driver: openweather_observation
 #    every: 10m
 #    params:
@@ -25,7 +28,8 @@ sources:
 #      user_agent: "HomeOps (eric@maximumdirect.net)"
 
 #  - name: NWSObservationKSUS
-#    kind: observation
+#    mode: poll
+#    kinds: ["observation"]
 #    driver: nws_observation
 #    every: 10m
 #    params:
@@ -33,7 +37,8 @@ sources:
 #      user_agent: "HomeOps (eric@maximumdirect.net)"
 
 #  - name: NWSObservationKCPS
-#    kind: observation
+#    mode: poll
+#    kinds: ["observation"]
 #    driver: nws_observation
 #    every: 10m
 #    params:
@@ -41,15 +46,44 @@ sources:
 #      user_agent: "HomeOps (eric@maximumdirect.net)"
 
   - name: NWSHourlyForecastSTL
-    kind: forecast
+    mode: poll
-    driver: nws_forecast
+    kinds: ["forecast"]
+    driver: nws_forecast_hourly
     every: 45m
     params:
       url: "https://api.weather.gov/gridpoints/LSX/90,74/forecast/hourly"
       user_agent: "HomeOps (eric@maximumdirect.net)"
 
+  - name: NWSNarrativeForecastSTL
+    mode: poll
+    kinds: ["forecast"]
+    driver: nws_forecast_narrative
+    every: 45m
+    params:
+      url: "https://api.weather.gov/gridpoints/LSX/90,74/forecast?units=us"
+      user_agent: "HomeOps (eric@maximumdirect.net)"
+
+  - name: NWSForecastDiscussionSTL
+    mode: poll
+    kinds: ["forecast_discussion"]
+    driver: nws_forecast_discussion
+    every: 30m
+    params:
+      url: "https://forecast.weather.gov/product.php?site=LSX&issuedby=LSX&product=AFD&format=TXT&version=1&glossary=0"
+      user_agent: "HomeOps (eric@maximumdirect.net)"
+
+  - name: NWSWeatherStoriesSTL
+    mode: poll
+    kinds: ["weather_story"]
+    driver: nws_weatherstories
+    every: 30m
+    params:
+      url: "https://api.weather.gov/offices/LSX/weatherstories"
+      user_agent: "HomeOps (eric@maximumdirect.net)"
+
   - name: OpenMeteoHourlyForecastSTL
-    kind: forecast
+    mode: poll
+    kinds: ["forecast"]
     driver: openmeteo_forecast
     every: 60m
     params:
@@ -57,7 +91,8 @@ sources:
       user_agent: "HomeOps (eric@maximumdirect.net)"
 
   - name: NWSAlertsSTL
-    kind: alert
+    mode: poll
+    kinds: ["alert"]
     driver: nws_alerts
     every: 1m
     params:
@@ -73,7 +108,16 @@ sinks:
     driver: nats
     params:
       url: nats://nats:4222
-      exchange: weatherfeeder
+      subject: weatherfeeder
+
+#  - name: pg_weatherfeeder
+#    driver: postgres
+#    params:
+#      uri: postgres://weatherdb:5432/weatherdb?sslmode=disable
+#      username: weatherdb
+#      password: weatherdb
+#      prune: 3d
+#      # Prunes rows older than now-3d on each write transaction.
 
 #  - name: logfile
 #    driver: file
@@ -82,10 +126,13 @@ sinks:
 
 routes:
   - sink: stdout
-    kinds: ["observation", "forecast", "alert"]
+    kinds: ["observation", "forecast", "forecast_discussion", "weather_story", "alert"]
 
   - sink: nats_weatherfeeder
-    kinds: ["observation", "forecast", "alert"]
+    kinds: ["observation", "forecast", "forecast_discussion", "weather_story", "alert"]
+
+#  - sink: pg_weatherfeeder
+#    kinds: ["observation", "forecast", "forecast_discussion", "weather_story", "alert"]
 
 #  - sink: logfile
-#    kinds: ["observation", "alert", "forecast"]
+#    kinds: ["observation", "alert", "forecast", "forecast_discussion", "weather_story"]

cmd/weatherfeeder/main.go

@@ -3,27 +3,29 @@ package main
 import (
 	"context"
 	"errors"
-	"fmt"
 	"log"
 	"os"
 	"os/signal"
-	"strings"
 	"syscall"
-	"time"
 
 	"gitea.maximumdirect.net/ejr/feedkit/config"
 	fkdispatch "gitea.maximumdirect.net/ejr/feedkit/dispatch"
 	fkevent "gitea.maximumdirect.net/ejr/feedkit/event"
-	fknormalize "gitea.maximumdirect.net/ejr/feedkit/normalize"
 	fkpipeline "gitea.maximumdirect.net/ejr/feedkit/pipeline"
+	fkprocessors "gitea.maximumdirect.net/ejr/feedkit/processors"
+	fkdedupe "gitea.maximumdirect.net/ejr/feedkit/processors/dedupe"
+	fknormalize "gitea.maximumdirect.net/ejr/feedkit/processors/normalize"
 	fkscheduler "gitea.maximumdirect.net/ejr/feedkit/scheduler"
 	fksinks "gitea.maximumdirect.net/ejr/feedkit/sinks"
 	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
 
 	wfnormalizers "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers"
+	wfpgsink "gitea.maximumdirect.net/ejr/weatherfeeder/internal/sinks/postgres"
 	wfsources "gitea.maximumdirect.net/ejr/weatherfeeder/internal/sources"
 )
 
+const dedupeMaxEntries = 2048
+
 func main() {
 	log.SetFlags(log.LstdFlags | log.Lmicroseconds)
 
@@ -42,41 +44,26 @@ func main() {
 
 	// Compile stdout, Postgres, and NATS sinks for weatherfeeder. The former is useful for debugging and the latter are the main intended outputs.
 	sinkReg := fksinks.NewRegistry()
-	sinkReg.Register("stdout", func(cfg config.SinkConfig) (fksinks.Sink, error) {
+	fksinks.RegisterBuiltins(sinkReg)
-		return fksinks.NewStdoutSink(cfg.Name), nil
+	sinkReg.Register("postgres", fksinks.PostgresFactory(wfpgsink.PostgresSchema()))
-	})
+
-	sinkReg.Register("postgres", func(cfg config.SinkConfig) (fksinks.Sink, error) {
-		return fksinks.NewPostgresSinkFromConfig(cfg)
-	})
-	sinkReg.Register("nats", func(cfg config.SinkConfig) (fksinks.Sink, error) {
-		return fksinks.NewNATSSinkFromConfig(cfg)
-	})
 	// --- Build sources into scheduler jobs ---
 	var jobs []fkscheduler.Job
 	for i, sc := range cfg.Sources {
-		src, err := srcReg.Build(sc)
+		in, err := srcReg.BuildInput(sc) // may be polling or streaming
 		if err != nil {
 			log.Fatalf("build source failed (sources[%d] name=%q driver=%q): %v", i, sc.Name, sc.Driver, err)
 		}
 
-		// Optional safety: if config.kind is set, ensure it matches the source.Kind().
+		if err := fksources.ValidateExpectedKinds(sc, in); err != nil {
-		if strings.TrimSpace(sc.Kind) != "" {
+			log.Fatalf("source expected kinds validation failed (sources[%d] name=%q driver=%q): %v", i, sc.Name, sc.Driver, err)
-			expectedKind, err := fkevent.ParseKind(sc.Kind)
-			if err != nil {
-				log.Fatalf("invalid kind in config (sources[%d] name=%q kind=%q): %v", i, sc.Name, sc.Kind, err)
-			}
-			if src.Kind() != expectedKind {
-				log.Fatalf(
-					"source kind mismatch (sources[%d] name=%q driver=%q): config kind=%q but driver emits kind=%q",
-					i, sc.Name, sc.Driver, expectedKind, src.Kind(),
-				)
-			}
 		}
 
-		jobs = append(jobs, fkscheduler.Job{
+		job, err := fkscheduler.JobFromSourceConfig(in, sc)
-			Source: src,
+		if err != nil {
-			Every:  sc.Every.Duration,
+			log.Fatalf("build scheduler job failed (sources[%d] name=%q driver=%q): %v", i, sc.Name, sc.Driver, err)
-		})
+		}
+		jobs = append(jobs, job)
 	}
 
 	// --- Build sinks ---
@@ -90,27 +77,35 @@ func main() {
 	}
 
 	// --- Compile routes ---
-	routes, err := compileRoutes(cfg, builtSinks)
+	routes, err := fkdispatch.CompileRoutes(cfg)
 	if err != nil {
 		log.Fatalf("compile routes failed: %v", err)
 	}
 
 	events := make(chan fkevent.Event, 256)
 
-	// --- Normalization (optional) ---
+	// --- Processors ---
 	//
-	// We install feedkit's normalize.Processor even before any normalizers exist.
+	// We install feedkit's processors/normalize.Processor even before any normalizers exist.
-	// With an empty registry and RequireMatch=false, this is a no-op passthrough.
+	// With an empty normalizer list and RequireMatch=false, this is a no-op passthrough.
 	// It will begin transforming events as soon as:
 	//   1) sources emit raw schemas (raw.*), and
 	//   2) matching normalizers are registered.
-	normReg := &fknormalize.Registry{}
+	normalizers := wfnormalizers.RegisterBuiltins(nil)
-	wfnormalizers.RegisterBuiltins(normReg)
+
+	procReg := fkprocessors.NewRegistry()
+	procReg.Register("normalize", func() (fkprocessors.Processor, error) {
+		return fknormalize.NewProcessor(normalizers, false), nil
+	})
+	procReg.Register("dedupe", fkdedupe.Factory(dedupeMaxEntries))
+
+	chain, err := procReg.BuildChain([]string{"normalize", "dedupe"})
+	if err != nil {
+		log.Fatalf("build processor chain failed: %v", err)
+	}
 
 	pl := &fkpipeline.Pipeline{
-		Processors: []fkpipeline.Processor{
+		Processors: chain,
-			fknormalize.Processor{Registry: normReg},
-		},
 	}
 
 	s := &fkscheduler.Scheduler{
@@ -143,55 +138,6 @@ func main() {
 	log.Printf("shutdown complete")
 }
 
-func compileRoutes(cfg *config.Config, builtSinks map[string]fksinks.Sink) ([]fkdispatch.Route, error) {
-	if len(cfg.Routes) == 0 {
-		return defaultRoutes(builtSinks), nil
-	}
-
-	var routes []fkdispatch.Route
-	for i, r := range cfg.Routes {
-		if strings.TrimSpace(r.Sink) == "" {
-			return nil, fmt.Errorf("routes[%d].sink is empty", i)
-		}
-		if _, ok := builtSinks[r.Sink]; !ok {
-			return nil, fmt.Errorf("routes[%d].sink references unknown sink %q", i, r.Sink)
-		}
-
-		kinds := map[fkevent.Kind]bool{}
-		for j, k := range r.Kinds {
-			kind, err := fkevent.ParseKind(k)
-			if err != nil {
-				return nil, fmt.Errorf("routes[%d].kinds[%d]: %w", i, j, err)
-			}
-			kinds[kind] = true
-		}
-
-		routes = append(routes, fkdispatch.Route{
-			SinkName: r.Sink,
-			Kinds:    kinds,
-		})
-	}
-
-	return routes, nil
-}
-
-func defaultRoutes(builtSinks map[string]fksinks.Sink) []fkdispatch.Route {
-	// nil Kinds means "match all kinds" by convention
-	var allKinds map[fkevent.Kind]bool = nil
-
-	routes := make([]fkdispatch.Route, 0, len(builtSinks))
-	for name := range builtSinks {
-		routes = append(routes, fkdispatch.Route{
-			SinkName: name,
-			Kinds:    allKinds,
-		})
-	}
-	return routes
-}
-
 func isContextShutdown(err error) bool {
 	return errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded)
 }
-
-// keep time imported (mirrors your previous main.go defensive trick)
-var _ = time.Second

cmd/weatherfeeder/main_test.go

@@ -0,0 +1,194 @@
+package main
+
+import (
+	"context"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	fkevent "gitea.maximumdirect.net/ejr/feedkit/event"
+	fkpipeline "gitea.maximumdirect.net/ejr/feedkit/pipeline"
+	fkprocessors "gitea.maximumdirect.net/ejr/feedkit/processors"
+	fkdedupe "gitea.maximumdirect.net/ejr/feedkit/processors/dedupe"
+	fknormalize "gitea.maximumdirect.net/ejr/feedkit/processors/normalize"
+	fkscheduler "gitea.maximumdirect.net/ejr/feedkit/scheduler"
+	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
+
+	wfnormalizers "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers"
+	wfsources "gitea.maximumdirect.net/ejr/weatherfeeder/internal/sources"
+)
+
+type testInput struct {
+	name string
+}
+
+func (s testInput) Name() string { return s.name }
+
+type testKindsSource struct {
+	testInput
+	kinds []fkevent.Kind
+}
+
+func (s testKindsSource) Kinds() []fkevent.Kind { return s.kinds }
+
+func TestValidateSourceExpectedKindsSubsetAllowed(t *testing.T) {
+	sc := config.SourceConfig{Kinds: []string{"observation"}}
+	in := testKindsSource{
+		testInput: testInput{name: "test"},
+		kinds:     []fkevent.Kind{"observation", "forecast"},
+	}
+
+	if err := fksources.ValidateExpectedKinds(sc, in); err != nil {
+		t.Fatalf("ValidateExpectedKinds() unexpected error: %v", err)
+	}
+}
+
+func TestValidateSourceExpectedKindsMismatchFails(t *testing.T) {
+	sc := config.SourceConfig{Kinds: []string{"alert"}}
+	in := testKindsSource{
+		testInput: testInput{name: "test"},
+		kinds:     []fkevent.Kind{"observation", "forecast"},
+	}
+
+	err := fksources.ValidateExpectedKinds(sc, in)
+	if err == nil {
+		t.Fatalf("ValidateExpectedKinds() expected mismatch error, got nil")
+	}
+	if !strings.Contains(err.Error(), "configured expected kind") {
+		t.Fatalf("ValidateExpectedKinds() error %q does not include expected message", err)
+	}
+}
+
+func TestValidateSourceExpectedKindsNoMetadataSkipsCheck(t *testing.T) {
+	sc := config.SourceConfig{Kinds: []string{"alert"}}
+	in := testInput{name: "test"}
+
+	if err := fksources.ValidateExpectedKinds(sc, in); err != nil {
+		t.Fatalf("ValidateExpectedKinds() unexpected error: %v", err)
+	}
+}
+
+func TestExampleConfigLoads(t *testing.T) {
+	if _, err := config.Load("config.yml"); err != nil {
+		t.Fatalf("config.Load(config.yml) unexpected error: %v", err)
+	}
+}
+
+func TestExampleConfigSourcesBuildSchedulerJobs(t *testing.T) {
+	cfg, err := config.Load("config.yml")
+	if err != nil {
+		t.Fatalf("config.Load(config.yml) unexpected error: %v", err)
+	}
+
+	reg := fksources.NewRegistry()
+	wfsources.RegisterBuiltins(reg)
+
+	for i, sc := range cfg.Sources {
+		in, err := reg.BuildInput(sc)
+		if err != nil {
+			t.Fatalf("BuildInput(sources[%d]) error = %v", i, err)
+		}
+
+		job, err := fkscheduler.JobFromSourceConfig(in, sc)
+		if err != nil {
+			t.Fatalf("JobFromSourceConfig(sources[%d]) error = %v", i, err)
+		}
+		if job.Source == nil {
+			t.Fatalf("JobFromSourceConfig(sources[%d]) returned nil source", i)
+		}
+	}
+}
+
+func TestProcessorRegistryBuildsNormalizeThenDedupeChain(t *testing.T) {
+	chain, err := buildProcessorChainForTests()
+	if err != nil {
+		t.Fatalf("BuildChain() unexpected error: %v", err)
+	}
+	if len(chain) != 2 {
+		t.Fatalf("BuildChain() expected 2 processors, got %d", len(chain))
+	}
+
+	pl := &fkpipeline.Pipeline{Processors: chain}
+	if len(pl.Processors) != 2 {
+		t.Fatalf("pipeline expected 2 processors, got %d", len(pl.Processors))
+	}
+}
+
+func TestNormalizeNoMatchPassThrough(t *testing.T) {
+	chain, err := buildProcessorChainForTests()
+	if err != nil {
+		t.Fatalf("BuildChain() unexpected error: %v", err)
+	}
+
+	pl := &fkpipeline.Pipeline{Processors: chain}
+	in := fkevent.Event{
+		ID:        "evt-no-match",
+		Kind:      fkevent.Kind("observation"),
+		Source:    "test",
+		EmittedAt: time.Now().UTC(),
+		Schema:    "raw.weatherfeeder.unknown.v1",
+		Payload: map[string]any{
+			"ok": true,
+		},
+	}
+
+	out, err := pl.Process(context.Background(), in)
+	if err != nil {
+		t.Fatalf("Pipeline.Process() unexpected error: %v", err)
+	}
+	if out == nil {
+		t.Fatalf("Pipeline.Process() returned nil output")
+	}
+	if !reflect.DeepEqual(*out, in) {
+		t.Fatalf("Pipeline.Process() expected passthrough output, got %#v", *out)
+	}
+}
+
+func TestDedupeDropsSecondEventWithSameID(t *testing.T) {
+	chain, err := buildProcessorChainForTests()
+	if err != nil {
+		t.Fatalf("BuildChain() unexpected error: %v", err)
+	}
+
+	pl := &fkpipeline.Pipeline{Processors: chain}
+	in := fkevent.Event{
+		ID:        "evt-dedupe-1",
+		Kind:      fkevent.Kind("observation"),
+		Source:    "test",
+		EmittedAt: time.Now().UTC(),
+		Schema:    "raw.weatherfeeder.unknown.v1",
+		Payload: map[string]any{
+			"ok": true,
+		},
+	}
+
+	first, err := pl.Process(context.Background(), in)
+	if err != nil {
+		t.Fatalf("first Pipeline.Process() unexpected error: %v", err)
+	}
+	if first == nil {
+		t.Fatalf("first Pipeline.Process() unexpectedly dropped event")
+	}
+
+	second, err := pl.Process(context.Background(), in)
+	if err != nil {
+		t.Fatalf("second Pipeline.Process() unexpected error: %v", err)
+	}
+	if second != nil {
+		t.Fatalf("second Pipeline.Process() expected dedupe drop, got %#v", *second)
+	}
+}
+
+func buildProcessorChainForTests() ([]fkprocessors.Processor, error) {
+	normalizers := wfnormalizers.RegisterBuiltins(nil)
+
+	procReg := fkprocessors.NewRegistry()
+	procReg.Register("normalize", func() (fkprocessors.Processor, error) {
+		return fknormalize.NewProcessor(normalizers, false), nil
+	})
+	procReg.Register("dedupe", fkdedupe.Factory(dedupeMaxEntries))
+
+	return procReg.BuildChain([]string{"normalize", "dedupe"})
+}

docs/policy/architecture.md

@@ -0,0 +1,179 @@
+# Architecture Policy
+
+## Purpose
+
+This document defines `weatherfeeder`'s development architecture and invariants for maintainers and LLM coding agents. It describes how the implemented system is built and how future changes should preserve its boundaries.
+
+This is an inward-facing policy document. User-facing wire contracts belong in [`API.md`](../../API.md), and future work belongs under [`docs/roadmap/`](../roadmap/).
+
+## Project Shape
+
+`weatherfeeder` is a config-driven Go daemon that polls upstream weather providers, emits feed events, normalizes provider-specific raw payloads into canonical weather payloads, and routes those events to configured sinks.
+
+The implemented runtime flow is:
+
+1. `cmd/weatherfeeder` loads `config.yml` from the working directory.
+2. Source drivers are built through the source registry.
+3. Feedkit scheduler jobs poll sources and publish raw events onto an in-process event channel.
+4. A pipeline runs normalization, then in-memory dedupe.
+5. The dispatcher routes processed events to configured sinks by event kind.
+6. Sinks consume events independently through feedkit fanout workers.
+
+Canonical payload structs live in `model`. Schema identifiers and cross-provider wire conventions live in `standards`. Source adapters live under `internal/sources`. Normalizers live under `internal/normalizers`. Provider-specific parsing helpers shared by sources and normalizers live under `internal/providers`. Sink-specific persistence mapping lives under `internal/sinks`.
+
+## Core Design Principles
+
+- Hexagonal boundaries: provider APIs, config loading, scheduling, dispatch, and sinks are external mechanisms around the weather domain model and normalization logic.
+- Raw-to-canonical flow: sources should fetch and envelope raw provider payloads; normalizers should own provider-to-canonical mapping.
+- Schema-based routing: normalizers match on event schema, not source name or event kind.
+- Composable registries: source drivers, normalizers, processors, and sinks are assembled explicitly through registries.
+- Bounded concurrency: scheduling and sink fanout are concurrent, but the application should keep queues, goroutine ownership, logging, and cancellation behavior visible.
+- Standard-library-first: use the Go standard library unless a narrow dependency materially improves maintainability or interoperability.
+- Current-behavior docs: outside roadmap files, document only implemented behavior.
+
+## Architectural Boundaries
+
+Core/domain logic:
+
+- `model` defines canonical payload structs and JSON field names.
+- `standards` defines schema strings, versioning conventions, WMO constants, and shared wire policy.
+- Normalizer mapping code is domain logic and should stay independent of CLI setup, filesystem paths, sink details, and runtime orchestration.
+
+Adapters:
+
+- Source adapters under `internal/sources/<provider>` fetch upstream data and produce raw feed events.
+- Sink adapters under `internal/sinks/<sink>` map canonical events to external systems.
+- Provider helper packages under `internal/providers/<provider>` contain pure parsing or provider-specific helper logic shared by sources and normalizers.
+
+Runtime composition:
+
+- `cmd/weatherfeeder/main.go` owns process wiring: config load, registry setup, scheduler jobs, processor chain, dispatcher, signal cancellation, and logging.
+- It should remain thin. Do not move provider mapping or sink persistence rules into `cmd/weatherfeeder`.
+
+Tests and examples:
+
+- The sample `cmd/weatherfeeder/config.yml` is executable test input and is load-tested.
+- Tests should keep exercising package contracts directly rather than relying only on full-daemon execution.
+
+## Modules or Stages
+
+The implemented processing stages are source polling, normalization, dedupe, and sink dispatch.
+
+Source contract:
+
+- Build from `feedkit/config.SourceConfig`.
+- Validate required driver params inside the source constructor.
+- Advertise emitted event kinds through `Kinds()` when possible.
+- Emit raw schemas from `standards`.
+- Decode only minimal metadata needed for event identity and effective time; leave full provider decoding to normalizers.
+- Respect `context.Context` during network work.
+
+Normalizer contract:
+
+- One normalizer type per normalizer file.
+- Match by `Event.Schema`.
+- Decode raw payloads into provider structs.
+- Map to canonical `model` payloads.
+- Preserve the incoming event envelope except for intentional schema, payload, and effective-time changes.
+- Use shared helpers in `internal/normalizers/common` for cross-provider behavior.
+- Follow the detailed normalizer conventions in `internal/normalizers/doc.go`.
+
+Sink contract:
+
+- Consume canonical schemas, not provider raw schemas.
+- Keep sink mapping isolated from normalizers and sources.
+- Preserve event envelope fields in durable storage where the sink schema supports it.
+- Validate required canonical fields before writing.
+
+## State, Inputs, and Outputs
+
+Inputs are configured source polls. The daemon currently uses feedkit's YAML config model with sources, sinks, and routes.
+
+Outputs are feed events sent to configured sinks. Implemented sink support comes from feedkit built-ins plus weatherfeeder's Postgres schema mapping. The sample config includes stdout and NATS routes; Postgres is configured as an optional commented example.
+
+The daemon's own state is in-process:
+
+- the event channel buffers events during runtime;
+- the dedupe processor stores a bounded in-memory key set;
+- source instances may keep HTTP conditional request state through feedkit HTTP source helpers;
+- scheduler and dispatcher state is not persisted by `weatherfeeder`.
+
+Durable persistence is an external sink concern. The Postgres table contract is documented in `internal/sinks/postgres/doc.go`; the consumer-facing event contract is documented in [`API.md`](../../API.md).
+
+## Configuration and CLI Boundaries
+
+The implemented executable reads `config.yml` from the current working directory. It does not currently expose CLI flags or config path discovery.
+
+Configuration shape is owned by feedkit's config package:
+
+- `sources` define named source drivers, mode, poll cadence, expected kinds, and driver params.
+- `sinks` define named sink drivers and sink params.
+- `routes` connect event kinds to sinks.
+
+Weatherfeeder-specific config policy belongs in source and sink constructors, registry setup, and tests. Do not spread config parsing through domain model or normalizer packages.
+
+If dedicated `docs/config.md` or `docs/cli.md` files are added later, they should become the canonical user/operator references. This policy should stay architectural and avoid duplicating those references.
+
+## Errors, Logging, and Diagnostics
+
+`cmd/weatherfeeder` uses the standard library `log` package with timestamps and microseconds.
+
+Startup errors are fatal and include config index, source/sink name, driver name, or operation context where available. Runtime scheduler and dispatcher errors are reported through logs; context cancellation and deadline errors are treated as shutdown conditions.
+
+Normalizers and sink mappers should wrap errors with operation and payload context, for example decode, parse, map, scan, or required-field context. Avoid logging or returning whole upstream payloads by default.
+
+The daemon handles `os.Interrupt` and `SIGTERM` through `signal.NotifyContext`. Sources, sinks, scheduler jobs, dispatcher, and processors should respect `context.Context`.
+
+## Testing Expectations
+
+When changing behavior, inspect or add focused tests in the owning package.
+
+Expected coverage by change type:
+
+- Source drivers: constructor behavior, advertised kinds, poll event schema/kind, effective-time policy, unchanged responses, and malformed metadata handling.
+- Normalizers: schema matching, canonical schema output, key field mapping, effective time, malformed required fields, and wire-shape regressions.
+- Provider helpers: parsing edge cases and fixtures.
+- Runtime wiring: config loading, source registry build, scheduler job creation, processor ordering, pass-through behavior, and dedupe behavior.
+- Postgres sink: schema shape, mapper writes, required-field validation, nullable handling, and compact JSON behavior.
+- Documentation-sensitive examples: keep sample config loadable.
+
+Use local test servers and fixtures rather than real upstream services. Full-package tests should remain fast and deterministic.
+
+## Dependency Policy
+
+Prefer the Go standard library for parsing, HTTP handling, time handling, logging, and tests where reasonable.
+
+Existing broad runtime composition is delegated to `feedkit`, which provides config, sources, scheduler, processors, dispatch, and sinks. Keep weatherfeeder-specific code from depending directly on low-level external clients when feedkit or a small adapter can contain that dependency.
+
+Third-party dependencies should be narrow, justified, and preferably de facto standard for their purpose. YAML parsing through feedkit is an acceptable example. Do not add dependencies for small conveniences, and do not let dependency-specific types leak across package boundaries unless that dependency is the package's explicit contract.
+
+## Documentation Expectations
+
+Documentation must follow [`docs/policy/documentation.md`](documentation.md).
+
+Rules for architecture-related docs:
+
+- Current-behavior docs must describe implemented behavior only.
+- Roadmap or speculative work belongs only under `docs/roadmap/`.
+- Prefer links to canonical docs over repeated reference material.
+- Update docs in the same change when modifying schemas, config behavior, runtime behavior, adapters, or persistence contracts.
+
+## Architectural Invariants
+
+- Keep `cmd/weatherfeeder` as composition code, not domain logic.
+- Keep source fetching separate from normalization.
+- Keep normalizers matched by schema constants from `standards`.
+- Keep canonical payload structs in `model` and treat JSON tags as wire contract.
+- Keep provider-specific helpers under `internal/providers/<provider>` when shared by sources and normalizers.
+- Keep cross-provider normalizer helpers pure and deterministic.
+- Keep sink persistence mapping isolated under `internal/sinks/<sink>`.
+- Preserve explicit registry-based extension points for sources and normalizers.
+- Preserve context-aware shutdown and bounded in-process queues.
+- Avoid broad dependencies without clear architectural value.
+
+## Non-Goals
+
+- `weatherfeeder` is not an HTTP API. API serving belongs to separate consumers such as `weatherapi`.
+- `weatherfeeder` does not own long-term durable state except through configured external sinks.
+- `weatherfeeder` does not provide a general plugin runtime; new built-in providers and sinks are registered in code.
+- Architecture policy is not a CLI, config, or wire-contract reference.

docs/policy/documentation.md

@@ -0,0 +1,356 @@
+# Go Project Documentation Policy
+
+## Purpose
+
+Project documentation must help four audiences:
+
+1. users who need to run the application;
+2. administrators/operators who need to configure and operate it;
+3. developers who need to understand and change it safely;
+4. LLM coding agents that need clear scope, boundaries, and invariants.
+
+Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
+
+## Core Rules
+
+### 1. Keep docs concise
+
+Each document should cover a defined scope and only the essentials for that scope.
+
+Avoid:
+- long background explanations;
+- repeated reference material;
+- implementation detail in user-facing docs;
+- aspirational language outside roadmap docs;
+- verbose examples where one minimal example is clearer.
+
+### 2. Document only implemented behavior outside roadmap files
+
+Unimplemented, planned, aspirational, experimental, or future work may be described only under:
+
+- `docs/roadmap/`
+
+No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist.
+
+If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary.
+
+### 3. Use canonical homes
+
+Each type of information should have one canonical location.
+
+Canonical homes:
+
+- project purpose and quickstart: `README.md`
+- development principles: `docs/policy/architecture.md`
+- configuration reference: `docs/config.md`
+- CLI reference: `docs/cli.md`
+- operations and recovery: `docs/operations.md`
+- troubleshooting: `docs/troubleshooting.md`
+- implemented internals: `docs/internal/`
+- future work: `docs/roadmap/`
+- contributor workflow: `docs/policy/development.md`
+- copyable examples: `examples/`
+
+Other files should summarize briefly and link to the canonical source.
+
+### 4. Keep examples real
+
+Examples should be valid, maintained, and free of secrets.
+
+Where practical:
+- example configs should load successfully;
+- example commands should match real CLI syntax;
+- important examples should be covered by tests.
+
+## Documentation Profiles
+
+All projects require:
+
+- `README.md`
+- `docs/policy/architecture.md`
+
+Additional docs depend on the project.
+
+### Small library
+
+Recommended:
+- `docs/policy/development.md`, if contributor conventions are non-obvious
+
+### Simple CLI
+
+Required:
+- `docs/cli.md`
+
+Recommended:
+- `docs/policy/development.md`
+
+### Config-driven CLI
+
+Required:
+- `docs/cli.md`
+- `docs/config.md`
+
+Recommended:
+- `examples/`
+- `docs/policy/development.md`
+
+### Stateful or operator-facing application
+
+Required:
+- `docs/cli.md`, if CLI-based
+- `docs/config.md`, if config-driven
+- `docs/operations.md`
+
+Recommended:
+- `docs/troubleshooting.md`
+- `examples/`
+- `docs/policy/development.md`
+
+### Modular, staged, service-oriented, or orchestration application
+
+Required:
+- `docs/cli.md`, if CLI-based
+- `docs/config.md`, if config-driven
+- `docs/operations.md`
+- `docs/internal/`
+- `docs/policy/development.md`
+
+Recommended:
+- `docs/troubleshooting.md`
+- validated examples under `examples/`
+
+## Required Documents
+
+### README.md
+
+**Audience:** users, administrators, operators
+
+The README is the outward-facing project orientation page.
+
+It should include, in order:
+
+1. concise description;
+2. elevator pitch;
+3. shortest useful command or usage example;
+4. links to targeted docs.
+
+The README should be short. It is not a manual.
+
+The “shortest useful command” means the simplest command that performs the project’s core use case. (It does not mean `app --help`.)
+
+### docs/policy/architecture.md
+
+**Audience:** developers, LLM coding agents
+
+`docs/policy/architecture.md` is required for every project.
+
+It is an inward-facing development policy document. It should describe how the project is intended to be built and changed.
+
+It should include:
+
+- project shape;
+- core design principles;
+- package and boundary philosophy;
+- state/persistence philosophy, if applicable;
+- external integration philosophy, if applicable;
+- error-handling and logging principles;
+- testing expectations;
+- documentation expectations;
+- architectural invariants;
+- explicit non-goals, if useful.
+
+For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
+
+### docs/policy/development.md
+
+**Audience:** developers, LLM coding agents
+
+Required for projects maintained by humans and LLM coding agents.
+
+It should include:
+
+- repository layout;
+- build/test commands;
+- coding conventions;
+- dependency policy;
+- how to add config fields;
+- how to add CLI flags;
+- how to add stages/modules/adapters, if applicable;
+- how to update examples;
+- documentation update expectations.
+
+### docs/config.md
+
+**Audience:** administrators, operators, advanced users
+
+Required for applications with configuration files.
+
+It should include, in order:
+
+1. config file locations and discovery precedence;
+2. minimal working config;
+3. production-oriented config;
+4. full configuration reference;
+5. secrets handling, if applicable;
+6. links to maintained examples.
+
+The full configuration reference should be canonical.
+
+### docs/cli.md
+
+**Audience:** users, administrators, operators
+
+Required for CLI applications.
+
+It should include, in order:
+
+1. shortest useful command;
+2. command overview;
+3. complete flag reference;
+4. common workflows;
+5. diagnostic or recovery commands, if applicable.
+
+Explain when commands are useful, not just their syntax.
+
+### docs/operations.md
+
+**Audience:** administrators, operators
+
+Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures.
+
+It should cover:
+
+- normal workflow;
+- filesystem layout;
+- remote storage layout, if applicable;
+- logs and manifests;
+- resume/retry behavior;
+- cleanup behavior;
+- archive/backup behavior;
+- safe recovery procedures;
+- operational caveats.
+
+### docs/troubleshooting.md
+
+**Audience:** administrators, operators
+
+Recommended once recurring failure modes exist.
+
+Each entry should include:
+
+- symptom;
+- likely cause;
+- diagnostic command or inspection step;
+- safe fix;
+- relevant links.
+
+### docs/internal/
+
+**Audience:** developers, LLM coding agents
+
+Required for modular, staged, service-oriented, or orchestration projects.
+
+This directory describes implemented internal components. It is not the roadmap.
+
+Use one file per major component where useful.
+
+Each component doc should include:
+
+1. purpose;
+2. inputs and outputs;
+3. boundaries;
+4. config fields used;
+5. external adapters used;
+6. state or manifest behavior, if applicable;
+7. skip/resume behavior, if applicable;
+8. failure behavior;
+9. tests to inspect before changing;
+10. architectural invariants.
+
+### docs/roadmap/
+
+**Audience:** maintainers, developers, LLM coding agents
+
+This is the only place for planned, future, aspirational, experimental, or unimplemented work.
+
+Roadmap docs should clearly distinguish:
+
+- proposed work;
+- accepted plans;
+- deferred ideas;
+- rejected ideas;
+- implementation prompts or task breakdowns, if useful.
+
+Roadmap docs should not be confused with current behavior.
+
+### docs/integrations/
+
+**Audience:** developers, LLM coding agents
+
+Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
+
+This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
+
+Use one file per integration where useful.
+
+## Examples Directory
+
+Projects with non-trivial configuration or workflows should include `examples/`.
+
+Useful examples include:
+
+- minimal working config;
+- production-oriented config;
+- full annotated config;
+- local development config;
+- remote/object-storage config;
+- minimal session/input file.
+
+Examples should be valid, maintained, tested when practical, and linked from relevant docs.
+
+## Security and Privacy
+
+Docs and examples must not include:
+
+- real API keys;
+- tokens;
+- passwords;
+- private keys;
+- private environment dumps;
+- sensitive user data;
+- raw private transcripts;
+- private infrastructure details unless intentionally public.
+
+Document secret-handling mechanisms, not actual secret values.
+
+## Maintenance Rules
+
+When docs change, verify the affected behavior.
+
+Where practical:
+
+- load example config files in tests;
+- test CLI examples or command parser behavior;
+- validate documented flags against real flags;
+- remove stale references;
+- update links after renames;
+- keep roadmap content out of non-roadmap docs.
+
+If documentation and code disagree, fix the documentation and/or open a roadmap item; do not leave aspirational behavior in current-behavior docs.
+
+Documentation is complete only when it matches the current code.
+
+## Documentation Change Checklist
+
+Before merging documentation changes, verify:
+
+- README is concise and orientation-focused.
+- `docs/policy/architecture.md` describes development principles.
+- Future work appears only under `docs/roadmap/`.
+- User-facing docs avoid unnecessary internals.
+- Developer-facing docs preserve boundaries and invariants.
+- Config examples match the schema.
+- CLI examples match real commands and flags.
+- Defaults appear in the canonical config reference.
+- No secrets or private data are included.
+- Links are accurate.

docs/roadmap/documentation.md

@@ -0,0 +1,491 @@
+# Documentation Roadmap
+
+## Purpose
+
+This roadmap defines the work required to bring `weatherfeeder` documentation into compliance with [`docs/policy/documentation.md`](../policy/documentation.md) and the current implementation described by [`docs/policy/architecture.md`](../policy/architecture.md).
+
+This is a planning document only. Implementation stages must update current-behavior documentation so it reflects implemented code, and keep proposed or unimplemented work under `docs/roadmap/`.
+
+## Repository Documentation Inventory
+
+- `README.md`: keep and rewrite. It is the correct project orientation file, but it is stale: it says stdout is the only implemented sink, uses “current MVP” framing, and lacks a shortest useful run command and links to targeted docs.
+- `API.md`: move and rewrite. It currently acts as the event wire contract, but external integration contracts belong under `docs/integrations/`. It is also stale: it omits the emitted `kind` and `emitted_at` envelope fields, documents `effectiveAt` instead of the actual `effective_at` JSON field, lists only some raw schemas, and has duplicate alert `response` rows.
+- `docs/policy/documentation.md`: keep and lightly update only if needed. It is the controlling documentation policy and should not be duplicated elsewhere.
+- `docs/policy/architecture.md`: keep and lightly update after the documentation tree is migrated. Its architecture content is current, but its link to `API.md` should be updated when the wire contract moves to `docs/integrations/events.md`.
+- `docs/roadmap/spc.md`: keep. It is correctly located under roadmap because it describes unimplemented SPC outlook support.
+- `docs/roadmap/documentation.md`: create. This file is the current deliverable.
+- `cmd/weatherfeeder/config.yml`: keep and treat as an executable sample, but do not use it as the only operator-facing config reference. It includes live endpoints and a commented OpenWeather URL with an apparent real API key; future cleanup should remove or replace that secret-like value.
+- `internal/normalizers/doc.go`: keep and lightly update. It contains implemented developer guidance but incorrectly references `internal/standards/schema.go`; the actual package is `standards` at repository root.
+- `internal/normalizers/common/doc.go`: keep and lightly update if needed. It is concise and current.
+- `internal/providers/nws/doc.go`: keep and lightly update if needed. It documents implemented provider-helper boundaries.
+- `internal/providers/openweather/doc.go`: keep and lightly update. It references future forecasts/alerts in a comment; outside roadmap docs this should be rewritten to current behavior only.
+- `standards/doc.go`: keep and lightly update. It incorrectly says `internal/standards/doc.go`; actual path is `standards/doc.go`.
+- `model/doc.go`: keep and lightly update. It says JSON tags are wire contract for “stdout today; others later,” which is stale because NATS and Postgres are implemented.
+- `internal/sinks/postgres/doc.go`: keep and lightly update. It is the authoritative implemented Postgres table contract, but should be linked from `docs/integrations/postgres.md` instead of being the only discoverable operator/developer reference.
+- `examples/`: create new. No examples directory exists. Current example material is embedded in `cmd/weatherfeeder/config.yml` only.
+- `docs/config.md`: create new. Required because `weatherfeeder` is config-driven.
+- `docs/cli.md`: create new. Required because `weatherfeeder` is a command-line executable, even though it currently has no flags.
+- `docs/operations.md`: create new. Required because `weatherfeeder` is an operator-facing daemon with polling, concurrency, external sinks, retention/pruning, and shutdown behavior.
+- `docs/troubleshooting.md`: create new. Recommended and useful because recurring operator failures are visible in constructors and config validation.
+- `docs/policy/development.md`: create new. Required for a modular project maintained by humans and coding agents.
+- `docs/internal/`: create new. Required because the project is modular and staged.
+- `docs/integrations/`: create new. Required because the project depends on external weather APIs, NATS, Postgres, and an emitted event contract.
+
+## Policy Compliance Assessment
+
+Required missing documents:
+
+- `docs/cli.md`
+- `docs/config.md`
+- `docs/operations.md`
+- `docs/internal/`
+- `docs/policy/development.md`
+- `docs/integrations/` entries for important external contracts
+
+Recommended missing documents:
+
+- `docs/troubleshooting.md`
+- `examples/` with maintained config examples
+
+Existing stale or misplaced content:
+
+- `README.md` is not concise enough as a current quickstart and contains stale sink status.
+- `API.md` is in the wrong canonical home for an external integration contract and does not match `feedkit/event.Event` JSON tags.
+- Some package comments include stale path references or future-looking language outside roadmap files.
+- The sample config contains live endpoint examples and an OpenWeather URL with an apparent credential-like `appid` value in a commented block; examples should be secret-free.
+
+Unimplemented, historical, or roadmap-only content outside roadmap:
+
+- README “current MVP” phrasing is development-history framing and should be removed.
+- Comments such as “others later,” “forecasts/alerts later,” and “future expensive steps” should be rewritten or removed unless they describe an implemented boundary.
+- Do not move SPC outlook content out of `docs/roadmap/spc.md` until it is implemented.
+
+Examples needing work:
+
+- There is no `examples/` directory.
+- `cmd/weatherfeeder/config.yml` is load-tested by `cmd/weatherfeeder/main_test.go`, but it is not an ideal copyable public example because it includes local/operator-specific values and a commented API key-like OpenWeather URL.
+- Future examples should be checked with `feedkit/config.Load` or a weatherfeeder-specific test.
+
+Links needing verification:
+
+- Links from `README.md` to `API.md` should be changed to the new canonical event contract path if `API.md` is moved.
+- `docs/policy/architecture.md` links to `../../API.md`; update this after moving the contract.
+- Internal package comments referring to `internal/standards` need correction to `standards`.
+
+## Target Documentation Set
+
+### `README.md`
+
+- Audience: users, administrators, operators.
+- Purpose: orient readers and get them to the shortest useful run path.
+- Canonical scope: project purpose, elevator pitch, shortest useful command, and links to deeper docs.
+- Recommended outline: description; what it does; shortest useful command; emitted products and providers summary; links to config, CLI, operations, event contract, development policy.
+- Source of truth: `cmd/weatherfeeder/main.go`, `cmd/weatherfeeder/config.yml`, `internal/sources/builtins.go`, `internal/normalizers/builtins.go`, `standards/schema.go`, `README.md` stale claims.
+- Acceptance criteria: concise, no stale stdout-only claim, no full config reference, no development-history framing, links target canonical docs.
+
+### `docs/cli.md`
+
+- Audience: users, administrators, operators.
+- Purpose: document the executable interface.
+- Canonical scope: how to run `weatherfeeder` and what CLI flags exist.
+- Recommended outline: shortest useful command; command overview; complete flag reference stating there are currently no flags; working-directory requirement for `config.yml`; common local/container workflows; shutdown signal behavior.
+- Source of truth: `cmd/weatherfeeder/main.go`, `Dockerfile`, `cmd/weatherfeeder/main_test.go`.
+- Acceptance criteria: accurately states that `config.yml` is loaded from current working directory and no config path flag exists; does not invent flags.
+
+### `docs/config.md`
+
+- Audience: administrators, operators, advanced users.
+- Purpose: canonical configuration reference.
+- Canonical scope: YAML shape, field rules, source/sink/route definitions, driver params, and defaults.
+- Recommended outline: config file location; minimal config; production-oriented config; top-level reference; source drivers; source params; sink drivers; sink params; routes; duration formats; secrets handling; links to examples.
+- Source of truth: `cmd/weatherfeeder/main.go`, `cmd/weatherfeeder/config.yml`, `../feedkit/config/config.go`, `../feedkit/config/load.go`, `../feedkit/sources/http.go`, `../feedkit/sinks/*.go`, `internal/sources/builtins.go`, source constructors.
+- Acceptance criteria: documents strict YAML known-field behavior, required `sources` and `sinks`, optional `routes`, `mode`, `every`, `kinds`, HTTP params including `url`, `user_agent`, `conditional`, `http_timeout`, and `http_response_body_limit_bytes`; documents OpenWeather `units=metric` requirement; avoids embedding secrets.
+
+### `docs/operations.md`
+
+- Audience: administrators and operators.
+- Purpose: explain how to run, observe, shut down, and recover the daemon.
+- Canonical scope: runtime behavior, logs, scheduling, sink behavior, Postgres initialization/pruning, and operational caveats.
+- Recommended outline: normal workflow; runtime lifecycle; logs; scheduler and polling behavior; conditional HTTP fetches; routing and sink fanout; Postgres table creation and retention; shutdown; recovery; caveats.
+- Source of truth: `cmd/weatherfeeder/main.go`, `../feedkit/scheduler`, `../feedkit/dispatch`, `../feedkit/sources/http.go`, `../feedkit/sinks/postgres.go`, `internal/sinks/postgres/schema.go`, `Dockerfile`.
+- Acceptance criteria: describes implemented behavior only; no unsupported admin commands; clearly states durable state is external sink state.
+
+### `docs/troubleshooting.md`
+
+- Audience: administrators and operators.
+- Purpose: provide safe diagnosis for common implemented failure modes.
+- Canonical scope: symptoms, likely causes, checks, fixes, and links.
+- Recommended outline: missing `config.yml`; YAML parse or unknown-field errors; unknown source/sink driver; source kind mismatch; missing `params.url` or `params.user_agent`; OpenWeather missing `units=metric`; NATS connection failure; Postgres connection/table/credential failure; no events due to 304 unchanged responses; route sends no events.
+- Source of truth: constructors and validation in feedkit/weatherfeeder, `cmd/weatherfeeder/main.go`, source tests, sink tests.
+- Acceptance criteria: every entry has symptom, likely cause, diagnostic step, safe fix, and link to config/operations where useful.
+
+### `docs/policy/development.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: contributor workflow and safe-change guidance.
+- Canonical scope: repository layout, build/test commands, coding conventions, dependency policy, adding drivers/normalizers/schemas/config fields/docs.
+- Recommended outline: layout; Go/test commands; style; dependency policy; adding a source; adding a normalizer; adding a canonical model/schema; adding Postgres mapping; updating sample config/examples/docs; review checklist.
+- Source of truth: `docs/policy/architecture.md`, `go.mod`, `cmd/weatherfeeder/main_test.go`, package docs, builtins registries, tests.
+- Acceptance criteria: no user/operator reference duplication; links to config/CLI docs; gives enough steps for coding agents to preserve architecture.
+
+### `docs/internal/runtime.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: describe implemented runtime composition.
+- Canonical scope: config load, registries, scheduler, processor chain, dispatcher, sink fanout, shutdown.
+- Recommended outline: purpose; inputs/outputs; boundaries; config fields used; adapters used; state; failure behavior; tests; invariants.
+- Source of truth: `cmd/weatherfeeder/main.go`, `cmd/weatherfeeder/main_test.go`, `../feedkit/scheduler`, `../feedkit/dispatch`, `../feedkit/processors`.
+- Acceptance criteria: accurately describes normalize then dedupe, `dedupeMaxEntries = 2048`, event channel buffer 256, and context shutdown behavior.
+
+### `docs/internal/sources.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: document implemented source drivers and source contracts.
+- Canonical scope: source boundaries, registered drivers, kinds, raw schemas, params, effective-time policies at a summary level.
+- Recommended outline: source contract; common HTTP behavior; driver table; provider notes; failure behavior; tests; invariants.
+- Source of truth: `internal/sources/builtins.go`, `internal/sources/*`, `../feedkit/sources/http.go`, source tests, `standards/schema.go`.
+- Acceptance criteria: includes all current drivers and no legacy `nws_forecast`; documents raw payload preservation and conditional GET behavior without duplicating full config reference.
+
+### `docs/internal/normalizers.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: document raw-to-canonical mapping boundaries and registration.
+- Canonical scope: normalizer contract, schema matching, provider packages, output schemas, tests.
+- Recommended outline: contract; registration/order; mapping table from raw schemas to canonical schemas; common helpers; failure behavior; tests; invariants.
+- Source of truth: `internal/normalizers/doc.go`, `internal/normalizers/builtins.go`, provider normalizer packages, `standards/schema.go`, normalizer tests.
+- Acceptance criteria: fixes stale `internal/standards` references; avoids duplicating every payload field from event contract.
+
+### `docs/internal/postgres-sink.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: explain weatherfeeder-owned Postgres mapping internals.
+- Canonical scope: schema registration, mapper behavior, required-field validation, table contract link.
+- Recommended outline: purpose; input schemas; writes; parent/child tables; nullable rules; pruning columns; tests; invariants.
+- Source of truth: `internal/sinks/postgres/doc.go`, `schema.go`, `map.go`, sink tests, feedkit Postgres sink.
+- Acceptance criteria: links to `docs/integrations/postgres.md` for operator-facing table contract; does not duplicate full table definitions unless that integration doc remains intentionally concise.
+
+### `docs/integrations/events.md`
+
+- Audience: downstream consumers and developers.
+- Purpose: canonical emitted event wire contract.
+- Canonical scope: feedkit event envelope JSON and canonical weather payload schemas.
+- Recommended outline: envelope; timestamp rules; kinds and schemas; raw schema note; shared conventions; canonical payloads; compatibility rules; compact examples.
+- Source of truth: `../feedkit/event/event.go`, `standards/schema.go`, `model/*.go`, `internal/normalizers/common/round.go`, normalizer tests.
+- Acceptance criteria: documents actual JSON field names (`id`, `kind`, `source`, `emitted_at`, `effective_at`, `schema`, `payload`); includes all current raw and canonical schemas; states forecast period `conditionCode` is optional; examples validate against current structs.
+
+### `docs/integrations/postgres.md`
+
+- Audience: downstream SQL consumers, administrators, developers.
+- Purpose: canonical Postgres table contract for weatherfeeder writes.
+- Canonical scope: tables, columns, keys, indexes, pruning, reconstruction notes, migration caveats.
+- Recommended outline: scope; sink config link; initialization behavior; table overview; full table contract; pruning; migrations; reconstruction of canonical payloads.
+- Source of truth: `internal/sinks/postgres/doc.go`, `schema.go`, `map.go`, `../feedkit/sinks/postgres.go`, schema/map tests.
+- Acceptance criteria: matches generated schema exactly; notes `CREATE TABLE IF NOT EXISTS` does not alter existing schemas; documents `forecast_periods.condition_code` nullable.
+
+### `docs/integrations/nws.md`
+
+- Audience: developers and operators maintaining NWS integrations.
+- Purpose: concise notes for implemented NWS endpoint usage.
+- Canonical scope: only endpoints and fields weatherfeeder currently uses.
+- Recommended outline: supported drivers; endpoint shapes; required user agent; accept headers; effective-time policies; parser caveats; tests.
+- Source of truth: `internal/sources/nws`, `internal/normalizers/nws`, `internal/providers/nws`, NWS tests and fixtures.
+- Acceptance criteria: no undocumented SPC outlook content; weather stories and forecast discussions included as implemented.
+
+### `docs/integrations/openmeteo.md`
+
+- Audience: developers and operators maintaining Open-Meteo integrations.
+- Purpose: concise notes for implemented Open-Meteo observation and hourly forecast usage.
+- Canonical scope: current endpoint usage, time parsing, fields mapped, effective time.
+- Source of truth: `internal/sources/openmeteo`, `internal/normalizers/openmeteo`, `internal/providers/openmeteo`, tests.
+- Acceptance criteria: no daily forecast or unsupported products documented as current.
+
+### `docs/integrations/openweather.md`
+
+- Audience: developers and operators maintaining OpenWeather integration.
+- Purpose: concise notes for implemented OpenWeather observation usage.
+- Canonical scope: current observation driver, `units=metric` requirement, timestamp behavior, mapped fields.
+- Source of truth: `internal/sources/openweather`, `internal/normalizers/openweather`, `internal/providers/openweather`, tests.
+- Acceptance criteria: no forecast/alert OpenWeather support documented as current.
+
+### `examples/config.minimal.yml`
+
+- Audience: users and operators.
+- Purpose: copyable minimal config.
+- Canonical scope: one source, one stdout sink, one route.
+- Source of truth: `cmd/weatherfeeder/config.yml`, config tests, source constructors.
+- Acceptance criteria: loads with `config.Load`; no secrets; uses placeholder-safe or public endpoints as appropriate.
+
+### `examples/config.nats.yml`
+
+- Audience: operators.
+- Purpose: copyable NATS publishing config.
+- Canonical scope: selected sources, NATS sink, route examples.
+- Source of truth: sample config, feedkit NATS sink.
+- Acceptance criteria: loads with `config.Load`; no secrets; clearly uses replaceable NATS URL/subject.
+
+### `examples/config.postgres.yml`
+
+- Audience: operators.
+- Purpose: copyable Postgres persistence config.
+- Canonical scope: selected sources, Postgres sink params, pruning example, routes.
+- Source of truth: sample config, feedkit Postgres sink, weatherfeeder Postgres schema.
+- Acceptance criteria: loads with `config.Load`; uses placeholders for username/password/URI; links from config and operations docs.
+
+## File-by-File Rewrite Guidance
+
+### `README.md`
+
+Cover what the daemon does, the shortest useful command, and where to go next. Use implemented provider and product summaries from source/normalizer registries. Avoid full config tables, full wire schemas, history, “MVP” language, and stale sink limitations. Link to `docs/cli.md`, `docs/config.md`, `docs/operations.md`, `docs/integrations/events.md`, and `docs/policy/development.md`.
+
+Do not carry forward the claim that stdout is the only implemented sink.
+
+### `API.md`
+
+Move its canonical content to `docs/integrations/events.md` and either delete `API.md` or replace it with a short pointer only if backward-compatible repository links are required. The rewritten contract must inspect `../feedkit/event/event.go` before documenting envelope fields. Do not preserve camelCase envelope examples unless the code changes first.
+
+### `docs/config.md`
+
+Use feedkit config structs for generic fields and weatherfeeder source/sink constructors for driver-specific params. Link to examples instead of embedding all large configs. Avoid documenting feedkit stream-only params as actively used by weatherfeeder unless clearly marked as generic feedkit config accepted by the current config model; all current weatherfeeder sources are poll sources.
+
+### `docs/cli.md`
+
+State the current no-flags behavior plainly. Include that `weatherfeeder` expects `config.yml` in the current working directory. Do not document environment variables, subcommands, or alternate config paths unless implemented.
+
+### `docs/operations.md`
+
+Focus on running the daemon and operating sinks. Include signal shutdown, log behavior, conditional HTTP fetches, Postgres table creation, retention pruning, and no internal durable scheduler state. Avoid unsupported recovery commands.
+
+### `docs/troubleshooting.md`
+
+Base entries on actual validation and constructor errors. Link to `docs/config.md` for fixes. Avoid speculative upstream outages beyond generic HTTP/source errors unless tests or code reveal specific behavior.
+
+### `docs/policy/development.md`
+
+Use `docs/policy/architecture.md` as the authority. Give concrete safe-change steps for adding source drivers, normalizers, schemas, Postgres tables, config examples, and docs. Avoid repeating the architecture policy wholesale.
+
+### `docs/internal/*.md`
+
+Create concise component docs. They should guide changes, not become manuals. Each should include tests to inspect before changing. Link to package docs when those are more precise.
+
+### `docs/integrations/*.md`
+
+Document only external contracts actually used by the implementation. Keep provider docs narrow and maintenance-oriented. Do not describe unimplemented SPC support outside `docs/roadmap/spc.md`.
+
+### Package comments
+
+Fix stale path and future-language comments during the documentation migration stage that touches developer docs. Specific likely fixes:
+
+- `model/doc.go`: remove “stdout today; others later.”
+- `standards/doc.go`: correct `internal/standards/doc.go` path.
+- `internal/normalizers/doc.go`: correct `internal/standards/schema.go` path.
+- `internal/providers/openweather/doc.go`: remove “forecasts/alerts later.”
+
+## Examples Plan
+
+No `examples/` directory currently exists. Create one because the project has non-trivial configuration and operator workflows.
+
+Recommended examples:
+
+- `examples/config.minimal.yml`: one public HTTP source, stdout sink, route. Validity check: `config.Load` in a new or existing config/example test. Link from README, config, CLI.
+- `examples/config.nats.yml`: NATS sink publishing example. Validity check: `config.Load`; do not require a live NATS server. Link from config and operations.
+- `examples/config.postgres.yml`: Postgres sink with placeholder credentials and optional `prune`. Validity check: `config.Load`; do not require a live Postgres server. Link from config, operations, Postgres integration docs.
+- `examples/config.full.yml`: optional, only if the team wants one annotated config covering all implemented drivers. Validity check: `config.Load`; must use placeholders for secrets and avoid real OpenWeather API keys. Link from config docs only.
+
+Do not add SPC examples until SPC support is implemented.
+
+## Internal Documentation Plan
+
+### Runtime Pipeline
+
+- Path: `docs/internal/runtime.md`
+- Purpose: explain daemon composition.
+- Inputs and outputs: YAML config in; feed events through scheduler/pipeline/dispatcher to sinks out.
+- Boundaries: composition belongs in `cmd/weatherfeeder`; domain mapping belongs in normalizers/model.
+- Config fields used: sources, sinks, routes, source `every`, mode/kinds, sink params.
+- Adapters used: feedkit scheduler, processors, dispatch, sinks.
+- Failure behavior: fatal startup errors; runtime errors logged and cancel context; interrupt/SIGTERM shutdown.
+- Tests to inspect: `cmd/weatherfeeder/main_test.go`, feedkit scheduler/dispatch tests.
+- Invariants: normalize before dedupe; bounded event channel; context-aware shutdown.
+
+### Sources
+
+- Path: `docs/internal/sources.md`
+- Purpose: document source driver architecture.
+- Inputs and outputs: `config.SourceConfig` and upstream HTTP responses in; raw feed events out.
+- Boundaries: sources fetch and envelope raw payloads; normalizers decode full payloads.
+- Config fields used: name, driver, mode, every, kinds, params URL/user agent/HTTP options.
+- Adapters used: feedkit source registry and HTTP helper.
+- Failure behavior: constructor validation, HTTP errors, unchanged 304 returns no events, some malformed metadata still emits raw events.
+- Tests to inspect: `internal/sources/builtins_test.go`, provider source tests.
+- Invariants: drivers registered in one place; raw schemas from `standards`; no canonical mapping in sources.
+
+### Normalizers
+
+- Path: `docs/internal/normalizers.md`
+- Purpose: document raw-to-canonical mapping architecture.
+- Inputs and outputs: raw events matched by schema in; canonical model payload events out.
+- Boundaries: no HTTP, no sink persistence, no CLI/config behavior.
+- Config fields used: none directly.
+- Adapters used: feedkit normalize processor.
+- Failure behavior: decode/parse/missing required fields return contextual errors; no-match passthrough configured in main.
+- Tests to inspect: `internal/normalizers/builtins_test.go`, provider normalizer tests, `internal/normalizers/common` tests.
+- Invariants: schema matching only, stable registration order, canonical schema constants.
+
+### Postgres Sink Mapping
+
+- Path: `docs/internal/postgres-sink.md`
+- Purpose: document weatherfeeder-specific Postgres mapping internals.
+- Inputs and outputs: canonical events in; feedkit `PostgresWrite` rows out.
+- Boundaries: mapper validates and maps; feedkit owns DB connection, DDL, transactions, pruning.
+- Config fields used: sink `uri`, `username`, `password`, optional `prune` via feedkit.
+- Adapters used: feedkit Postgres sink.
+- Failure behavior: unsupported schemas map to no writes or errors per mapper behavior; required missing fields fail before write.
+- Tests to inspect: `internal/sinks/postgres/map_test.go`, `schema_test.go`, feedkit Postgres tests.
+- Invariants: consume canonical schemas only; preserve envelope columns; keep parent/child order indexes.
+
+## Integration Documentation Plan
+
+### Event Wire Contract
+
+- Path: `docs/integrations/events.md`
+- External system or contract: JSON events emitted to stdout/NATS and represented in Postgres parent envelope columns.
+- Current usage: sinks marshal feedkit events or map canonical events to tables.
+- Version notes: schema identifiers use `raw.*.v1` and `weather.*.v1`; JSON tags are compatibility contract.
+- Document: actual envelope fields, schema list, payload fields, units, optionality, examples.
+- Do not document: weatherapi HTTP endpoints, unimplemented outlooks, or future schemas.
+
+### Postgres
+
+- Path: `docs/integrations/postgres.md`
+- External system or contract: PostgreSQL schema created/written by feedkit Postgres sink using weatherfeeder schema definition.
+- Current usage: optional configured sink; create-if-missing tables and indexes; transactional writes; optional pruning.
+- Version notes: no migration framework is implemented; existing DBs may need manual schema changes when table definitions change.
+- Document: params, table contract, pruning, reconstruction, migration caveats.
+- Do not document: weatherapi query behavior except as a downstream consumer link if needed.
+
+### NWS
+
+- Path: `docs/integrations/nws.md`
+- External system or contract: NWS API and NWS forecast discussion/weather story endpoints used by current drivers.
+- Current usage: observations, alerts, hourly forecast, narrative forecast, forecast discussion, weather stories.
+- Version notes: no explicit upstream API version in code; weatherfeeder pins its own raw schema names.
+- Document: endpoint shapes used, required User-Agent, accept headers, effective time, raw schemas.
+- Do not document: SPC outlooks or unsupported NWS products.
+
+### Open-Meteo
+
+- Path: `docs/integrations/openmeteo.md`
+- External system or contract: Open-Meteo forecast API for current observations and hourly forecasts.
+- Current usage: JSON HTTP source, time parsing from timezone/UTC offset, hourly fields mapped to canonical forecast.
+- Version notes: no explicit upstream API version in code.
+- Document: required URL/user agent params, expected current/hourly response pieces, effective time behavior.
+- Do not document: daily forecast unless implemented.
+
+### OpenWeather
+
+- Path: `docs/integrations/openweather.md`
+- External system or contract: OpenWeather current weather endpoint.
+- Current usage: observation source/normalizer only.
+- Version notes: source requires `units=metric` in URL.
+- Document: metric units requirement, timestamp behavior, mapped fields, secret handling for API key.
+- Do not document: OpenWeather forecasts or alerts.
+
+### NATS
+
+- Path: include in `docs/operations.md` and `docs/config.md`; create `docs/integrations/nats.md` only if NATS-specific maintenance grows.
+- External system or contract: NATS publish subject configured by feedkit sink.
+- Current usage: optional sink publishes each event as JSON.
+- Document: `url`, `subject`, JSON event payload, connection failure behavior.
+- Do not document: subscriptions or server administration beyond this sink contract.
+
+## Recommended Implementation Sequence
+
+### Stage 1: Current-State README, CLI, and Config Docs
+
+- Goal: establish accurate user/operator entry points.
+- Files to create/update/delete/move: rewrite `README.md`; create `docs/cli.md`; create `docs/config.md`.
+- Repository areas to inspect: `cmd/weatherfeeder/main.go`, `cmd/weatherfeeder/config.yml`, `../feedkit/config`, `../feedkit/sources/http.go`, `../feedkit/sinks`, `internal/sources/builtins.go`, source constructors.
+- Acceptance criteria: README concise and current; CLI doc states no flags and cwd `config.yml`; config doc includes complete implemented config reference and no secrets.
+- Suggested validation commands: `go test ./cmd/weatherfeeder`; `rg -n "only implemented sink|current MVP|--config|API.md" README.md docs/cli.md docs/config.md`.
+- Size: small enough for one implementation prompt.
+
+### Stage 2: Event and Postgres Integration Contracts
+
+- Goal: move and correct external contracts.
+- Files to create/update/delete/move: create `docs/integrations/events.md`; create `docs/integrations/postgres.md`; delete or replace `API.md` with a pointer; update links in `README.md` and `docs/policy/architecture.md`.
+- Repository areas to inspect: `../feedkit/event/event.go`, `standards/schema.go`, `model/*.go`, `internal/sinks/postgres/doc.go`, `schema.go`, `map.go`, normalizer tests, sink tests.
+- Acceptance criteria: event envelope field names match code; all current schemas listed; Postgres contract matches schema definition; no duplicate or stale API rows.
+- Suggested validation commands: `go test ./internal/sinks/postgres ./internal/normalizers/...`; `rg -n "effectiveAt|emittedAt|API.md|response \| string.*response" README.md docs API.md`.
+- Size: one implementation prompt if kept focused; split if examples are expanded heavily.
+
+### Stage 3: Operations and Troubleshooting Docs
+
+- Goal: document running and recovering the daemon.
+- Files to create/update/delete/move: create `docs/operations.md`; create `docs/troubleshooting.md`.
+- Repository areas to inspect: `cmd/weatherfeeder/main.go`, `Dockerfile`, feedkit scheduler/dispatch/source/sink implementations, config validation, source/sink constructors.
+- Acceptance criteria: operational docs describe logs, shutdown, scheduling, conditional HTTP, fanout, Postgres create/prune behavior, and common failures without inventing commands.
+- Suggested validation commands: `go test ./cmd/weatherfeeder`; `rg -n "TODO|future|planned|unimplemented" docs/operations.md docs/troubleshooting.md`.
+- Size: small enough for one implementation prompt.
+
+### Stage 4: Examples Directory and Example Validation
+
+- Goal: add maintained copyable configs.
+- Files to create/update/delete/move: create `examples/config.minimal.yml`, `examples/config.nats.yml`, `examples/config.postgres.yml`; optionally create `examples/config.full.yml`; update tests to load examples; update links in README/config/operations.
+- Repository areas to inspect: `cmd/weatherfeeder/config.yml`, `cmd/weatherfeeder/main_test.go`, feedkit config validation, source/sink params.
+- Acceptance criteria: examples contain no secrets, load successfully, and are linked from canonical docs.
+- Suggested validation commands: `go test ./cmd/weatherfeeder`; `rg -n "appid=|password: [^<]|token|secret" examples cmd/weatherfeeder/config.yml docs`.
+- Size: one implementation prompt.
+
+### Stage 5: Developer and Internal Docs
+
+- Goal: document safe change workflow and internal component boundaries.
+- Files to create/update/delete/move: create `docs/policy/development.md`; create `docs/internal/runtime.md`; create `docs/internal/sources.md`; create `docs/internal/normalizers.md`; create `docs/internal/postgres-sink.md`; lightly update package comments with stale paths/future language.
+- Repository areas to inspect: architecture policy, package docs, registries, source/normalizer/sink tests, `go.mod`.
+- Acceptance criteria: docs are inward-facing, concise, and action-oriented; package comments no longer contain stale path or future-support language outside roadmap.
+- Suggested validation commands: `go test ./...`; `rg -n "internal/standards|others later|forecasts/alerts later|future expensive steps" . -g '*.go' -g '*.md'`.
+- Size: likely one implementation prompt, but split package-comment cleanup if code comment edits are considered too broad.
+
+### Stage 6: Provider Integration Notes
+
+- Goal: document external provider contracts actually used by implemented source/normalizer pairs.
+- Files to create/update/delete/move: create `docs/integrations/nws.md`, `docs/integrations/openmeteo.md`, `docs/integrations/openweather.md`; optionally create `docs/integrations/nats.md` only if NATS content should stand alone.
+- Repository areas to inspect: provider source packages, provider normalizer packages, `internal/providers`, provider tests/fixtures.
+- Acceptance criteria: each integration doc is narrow, current, and excludes unimplemented products; NWS doc does not include SPC outlooks except linking to roadmap if needed.
+- Suggested validation commands: `go test ./internal/sources/... ./internal/normalizers/... ./internal/providers/...`; `rg -n "SPC|outlook|daily forecast|OpenWeather forecast|OpenWeather alert" docs/integrations`.
+- Size: one implementation prompt.
+
+### Stage 7: Final Documentation Consistency Pass
+
+- Goal: remove stale references and verify policy compliance.
+- Files to create/update/delete/move: any docs touched in prior stages; remove obsolete root `API.md` if not kept as pointer.
+- Repository areas to inspect: whole documentation tree, package comments, tests.
+- Acceptance criteria: every non-roadmap doc describes implemented behavior only; every doc has clear audience/scope; roadmap content remains only in `docs/roadmap`; links resolve by inspection.
+- Suggested validation commands: `go test ./...`; `find docs -type f -name '*.md' -print | sort`; `rg -n "MVP|only implemented sink|planned|future|later|deprecated|experimental|TODO|API.md|effectiveAt|emittedAt|internal/standards|appid=" README.md docs internal model standards cmd examples`.
+- Size: small enough for one implementation prompt.
+
+## Validation Plan
+
+Automated checks available now:
+
+- `go test ./...` verifies code behavior and existing load-tested sample config.
+- `go test ./cmd/weatherfeeder` verifies `cmd/weatherfeeder/config.yml` loads and sources build scheduler jobs.
+- Focused package tests verify source drivers, normalizers, and Postgres schema/mapping.
+
+Recommended new checks during implementation:
+
+- Add tests that load all `examples/*.yml` with `feedkit/config.Load`.
+- Add or extend tests to ensure documented source drivers in config examples build through `internal/sources.RegisterBuiltins`.
+- Use `rg` checks for stale or prohibited terms: `only implemented sink`, `current MVP`, `future`, `later`, `planned`, `deprecated`, `experimental`, `API.md`, `effectiveAt`, `emittedAt`, `internal/standards`, and secret-like strings such as `appid=`.
+- Manually verify Markdown links because no dedicated Markdown/link checker is currently present.
+- Manually compare `docs/integrations/events.md` against `../feedkit/event/event.go`, `standards/schema.go`, and `model/*.go` before accepting.
+- Manually compare `docs/integrations/postgres.md` against `internal/sinks/postgres/schema.go` before accepting.
+
+No repository-local Markdown formatter, Markdown linter, Makefile, justfile, Taskfile, or `package.json` docs tooling was found during this planning pass.
+
+## Open Questions
+
+No question blocks implementation of this documentation migration. Recommended decisions:
+
+- Move the canonical event contract from `API.md` to `docs/integrations/events.md` to comply with the documentation policy.
+- Replace root `API.md` with a short pointer only if backward-compatible links are considered important; otherwise delete it during the migration.
+- Keep `cmd/weatherfeeder/config.yml` as the executable in-repo sample used by tests, but create public copyable examples under `examples/` and remove secret-like values from examples.

docs/roadmap/spc.md

@@ -0,0 +1,323 @@
+# SPC Convective Outlook Support Roadmap
+
+## Summary
+
+Add `weatherfeeder` support for Storm Prediction Center convective outlooks as a new canonical outlook domain. The feature should poll SPC GeoJSON outlook products, optionally enrich them with RSS discussion metadata, compute whether the configured forecast point is inside each active outlook polygon, normalize the result into a provider-independent schema, and persist it through existing sinks.
+
+This is a new domain, not an extension of `weather.alert.v1`. SPC outlooks describe probabilistic/categorical risk areas over a validity window; alerts describe active actionable hazard messages.
+
+## Public Contract
+
+Add schema constants:
+
+- Raw schema: `raw.spc.convective_outlook.v1`
+- Canonical schema: `weather.outlook.v1`
+
+Add source driver:
+
+- `spc_convective_outlook`
+
+Add event kind:
+
+- `outlook`
+
+Add canonical model types:
+
+- `model.WeatherOutlookRun`
+- `model.WeatherOutlook`
+
+Recommended canonical run fields:
+
+- `locationId`, `locationName`
+- `latitude`, `longitude`
+- `asOf`
+- `issuedAt`
+- `outlooks`
+
+Recommended canonical outlook fields:
+
+- `id`
+- `provider`
+- `product`
+- `day`
+- `outlookType`
+- `label`
+- `labelText`
+- `severityRank`
+- `validFrom`
+- `validTo`
+- `issuedAt`
+- `expiresAt`
+- `forecaster`
+- `headline`
+- `summary`
+- `discussion`
+- `sourceUrl`
+- `imageUrl`
+- `containsLocation`
+- `geometry`
+
+Contract defaults:
+
+- `product` should be `convective`.
+- `outlookType` should be one of `categorical`, `tornado`, `hail`, `wind`.
+- `day` should be `1`, `2`, or `3` for this first implementation.
+- `containsLocation` is computed against configured forecast coordinates.
+- `geometry` should preserve compact GeoJSON geometry for auditability and future API use.
+
+## Source Scope
+
+The source should fetch a bundle of SPC products in one poll cycle and emit one raw event containing the fetched RSS metadata, GeoJSON products, configured point, and per-product fetch metadata.
+
+Poll these GeoJSON URLs:
+
+- `https://www.spc.noaa.gov/products/outlook/day1otlk_cat.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day1otlk_torn.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day1otlk_hail.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day1otlk_wind.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day2otlk_cat.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day2otlk_torn.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day2otlk_hail.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day2otlk_wind.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day3otlk_cat.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day3otlk_torn.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day3otlk_hail.nolyr.geojson`
+- `https://www.spc.noaa.gov/products/outlook/day3otlk_wind.nolyr.geojson`
+
+Note: the initial candidate list duplicated Day 3 wind and omitted Day 2 wind. Use the corrected 12-product matrix above.
+
+Also poll:
+
+- `https://www.spc.noaa.gov/products/spcacrss.xml`
+
+RSS usage:
+
+- Use RSS as discussion/discovery metadata, not as the geometry source.
+- Preserve item title, link, description text, pubDate, and guid where useful.
+- Extract the narrative outlook text from the RSS item description when practical.
+- Do not attempt to parse polygons from RSS HTML.
+
+Polling cadence:
+
+- Use a default cadence of `30m`, not daily/twice-daily. SPC current outlook files can update several times per day, and a 30-minute poll with HTTP caching is low cost and less likely to miss updates.
+- Rely on ETag/Last-Modified handling from the HTTP source layer where available.
+- Keep the cadence configurable via `every`.
+
+Recommended config shape:
+
+```yaml
+- name: SPCConvectiveOutlookSTL
+  mode: poll
+  kinds: ["outlook"]
+  driver: spc_convective_outlook
+  every: 30m
+  params:
+    latitude: 38.6239
+    longitude: -90.3571
+    location_id: "stl"
+    location_name: "St. Louis, MO"
+    user_agent: "HomeOps (eric@maximumdirect.net)"
+```
+
+The source should own default SPC URLs, with optional params to override the RSS URL and product URLs for tests or future provider changes.
+
+## Implementation Stages
+
+### Stage 1: Raw Source and Schema
+
+- Add schema constants and model placeholders.
+- Add `internal/sources/spc` package.
+- Implement `spc_convective_outlook` as a poll source.
+- Fetch all configured GeoJSON products and RSS during a poll cycle.
+- Emit one raw event with kind `outlook` and schema `raw.spc.convective_outlook.v1`.
+- Use the latest valid `ISSUE_ISO`, RSS `lastBuildDate`, or fetch time for `effectiveAt`, in that order.
+- Preserve partial fetch errors as source errors for the first implementation; do not emit incomplete outlook bundles unless a later explicit degraded-mode policy is added.
+
+Tests:
+
+- source driver builds as a `PollSource`
+- source advertises kind `outlook`
+- source emits one raw bundled event
+- source chooses expected effective time
+- source uses configured location metadata
+- source fails clearly on missing latitude/longitude
+
+### Stage 2: GeoJSON and Spatial Matching
+
+- Add an internal geometry helper package, for example `internal/geo`.
+- Support GeoJSON `Polygon` and `MultiPolygon`.
+- Implement point-in-polygon with ring support:
+  - first ring is the exterior
+  - subsequent rings are holes
+  - boundary counts as inside
+  - GeoJSON coordinate order is `[longitude, latitude]`
+- Use planar ray casting for this operational point-in-polygon check.
+
+Tests:
+
+- point inside polygon
+- point outside polygon
+- point on polygon boundary
+- point inside a hole is outside
+- point inside one multipolygon member is inside
+- longitude/latitude order regression test
+
+### Stage 3: Normalizer and Canonical Mapping
+
+- Add `SPCConvectiveOutlookNormalizer`.
+- Match only `raw.spc.convective_outlook.v1`.
+- Decode the raw source bundle.
+- Map each GeoJSON feature to one `WeatherOutlook`.
+- Preserve SPC feature order within each product, then order products by day and type.
+- Map properties:
+  - `VALID_ISO` -> `validFrom`
+  - `EXPIRE_ISO` -> `validTo` and `expiresAt`
+  - `ISSUE_ISO` -> `issuedAt`
+  - `FORECASTER` -> `forecaster`
+  - `LABEL` -> `label`
+  - `LABEL2` -> `labelText`
+  - `DN` -> `severityRank`
+- Derive:
+  - `day` from product key or URL
+  - `outlookType` from product key or URL
+  - `id` from day, type, label, issuedAt, validFrom, and feature index
+  - `containsLocation` from configured point and GeoJSON geometry
+- Enrich narrative fields from RSS where a matching day/product item can be determined.
+- Set run `asOf` to the latest valid `issuedAt` across features, falling back to RSS `lastBuildDate`, then input event time.
+- Set run `issuedAt` to the latest valid `issuedAt` across features.
+- Set output event `effectiveAt` to run `asOf`.
+
+Tests:
+
+- normalizer routes only raw SPC schema
+- categorical and probabilistic products map expected fields
+- `containsLocation` is true for a known point inside a fixture polygon
+- `containsLocation` is false outside
+- missing optional RSS still permits GeoJSON normalization
+- malformed required GeoJSON timestamps fail with useful context
+- canonical JSON shape does not expose raw-provider-only bundle internals
+
+### Stage 4: Postgres Sink
+
+Add tables:
+
+- `outlook_runs`
+- `outlooks`
+
+Suggested `outlook_runs` columns:
+
+- event envelope columns
+- `location_id`
+- `location_name`
+- `latitude`
+- `longitude`
+- `as_of`
+- `issued_at`
+- `outlook_count`
+
+Suggested `outlooks` columns:
+
+- `run_event_id`
+- `outlook_index`
+- `as_of`
+- `product`
+- `day`
+- `outlook_type`
+- `label`
+- `label_text`
+- `severity_rank`
+- `valid_from`
+- `valid_to`
+- `issued_at`
+- `expires_at`
+- `forecaster`
+- `headline`
+- `summary`
+- `discussion`
+- `source_url`
+- `image_url`
+- `contains_location`
+- `geometry_json`
+
+Suggested indexes:
+
+- `outlook_runs(location_id, as_of)`
+- `outlooks(contains_location, valid_from, valid_to)`
+- `outlooks(day, outlook_type, label)`
+- `outlooks(valid_from, valid_to)`
+
+Mapping rules:
+
+- Store `geometry` as compact GeoJSON text in `geometry_json`.
+- Require run `asOf`.
+- Require outlook `validFrom`, `validTo`, `issuedAt`, `day`, `outlookType`, and `label`.
+- Preserve all outlook polygons, not only polygons containing the configured point.
+
+Tests:
+
+- schema includes outlook tables and indexes
+- mapper writes one run row plus one row per outlook
+- mapper stores compact geometry JSON
+- mapper rejects missing required run/outlook fields
+
+### Stage 5: Config and Documentation
+
+- Update sample config with `SPCConvectiveOutlookSTL`.
+- Add `outlook` to route examples.
+- Update README provider capabilities.
+- Update `API.md` with `weather.outlook.v1`.
+- Update Postgres sink docs with outlook table contract.
+
+Docs should clearly state:
+
+- RSS is used for narrative/discussion metadata.
+- GeoJSON is used for polygons and point matching.
+- `containsLocation` is computed by weatherfeeder at ingestion time.
+- Geometry is stored for downstream audit/display.
+
+### Stage 6: Weatherapi Follow-Up
+
+Do not include weatherapi changes in the first weatherfeeder implementation unless explicitly requested.
+
+Likely future weatherapi endpoints:
+
+- `GET /outlooks/convective`
+- `GET /outlooks/convective/active`
+- `GET /outlooks/convective/location`
+
+Recommended API behavior:
+
+- latest run by default
+- active outlooks filtered by current time and `containsLocation=true`
+- optional filter query params for `day`, `outlookType`, and `containsLocation`
+
+## Open Questions for Implementation
+
+- Whether to include Day 4-8 probabilistic outlooks in a later version. Exclude them from v1.
+- Whether to make partial source bundles acceptable if one product URL fails. Default v1 behavior should fail the poll and retry.
+- Whether to parse detailed discussion text from RSS only, HTML pages, or both. Default v1 should use RSS only.
+- Whether to keep `geometry` in canonical JSON permanently. Default v1 should include it because it preserves source context and enables downstream display.
+
+## Verification Commands
+
+Run focused tests:
+
+```sh
+go test ./internal/sources ./internal/normalizers/... ./internal/sinks/postgres ./model
+```
+
+Run full weatherfeeder tests:
+
+```sh
+go test ./...
+```
+
+## Acceptance Criteria
+
+- A configured SPC source emits raw outlook bundles.
+- Normalization produces `weather.outlook.v1` events.
+- Each outlook indicates whether the configured forecast point is inside its polygon.
+- All current Day 1-3 categorical/tornado/hail/wind products are represented.
+- RSS discussion metadata is preserved where available.
+- Postgres sink persists outlook runs and outlook rows.
+- Sample config and public docs describe the new kind, driver, schema, and storage contract.

go.mod

@@ -2,10 +2,11 @@ module gitea.maximumdirect.net/ejr/weatherfeeder
 
 go 1.25
 
-require gitea.maximumdirect.net/ejr/feedkit v0.4.1
+require gitea.maximumdirect.net/ejr/feedkit v0.9.1
 
 require (
 	github.com/klauspost/compress v1.17.2 // indirect
+	github.com/lib/pq v1.10.9 // indirect
 	github.com/nats-io/nats.go v1.34.0 // indirect
 	github.com/nats-io/nkeys v0.4.7 // indirect
 	github.com/nats-io/nuid v1.0.1 // indirect

go.sum

@@ -1,7 +1,9 @@
-gitea.maximumdirect.net/ejr/feedkit v0.4.1 h1:mMFtPCBKp2LXV3euPH21WzjHku/HHx31KQqYW+w1aqU=
+gitea.maximumdirect.net/ejr/feedkit v0.9.1 h1:YghBQT1podqc+FJuPGuIZImV4A9dMr56Hikd5xuniig=
-gitea.maximumdirect.net/ejr/feedkit v0.4.1/go.mod h1:wYtA10GouvSe7L/8e1UEC+tqcp32HJofExIo1k+Wjls=
+gitea.maximumdirect.net/ejr/feedkit v0.9.1/go.mod h1:U6xC9xZLN3cL4yi7YBVyzGoHYRLJXusFCAKlj2kdYYQ=
 github.com/klauspost/compress v1.17.2 h1:RlWWUY/Dr4fL8qk9YG7DTZ7PDgME2V4csBXA8L/ixi4=
 github.com/klauspost/compress v1.17.2/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE=
+github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
+github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
 github.com/nats-io/nats.go v1.34.0 h1:fnxnPCNiwIG5w08rlMcEKTUw4AV/nKyGCOJE8TdhSPk=
 github.com/nats-io/nats.go v1.34.0/go.mod h1:Ubdu4Nh9exXdSz0RVWRFBbRfrbSxOYd26oF0wkWclB8=
 github.com/nats-io/nkeys v0.4.7 h1:RwNJbbIdYCoClSDNY7QVKZlyb/wfT6ugvFCiKy6vDvI=

internal/normalizers/builtins.go

@@ -2,13 +2,19 @@
 package normalizers
 
 import (
-	fknormalize "gitea.maximumdirect.net/ejr/feedkit/normalize"
+	fknormalize "gitea.maximumdirect.net/ejr/feedkit/processors/normalize"
 
 	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/nws"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/openmeteo"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/openweather"
 )
 
+var builtinRegistrations = []func([]fknormalize.Normalizer) []fknormalize.Normalizer{
+	nws.Register,
+	openmeteo.Register,
+	openweather.Register,
+}
+
 // RegisterBuiltins registers all normalizers shipped with this binary.
 //
 // This mirrors internal/sources.RegisterBuiltins, but note the selection model:
@@ -16,22 +22,20 @@ import (
 //   - sources are built by name (cfg.Driver -> factory)
 //   - normalizers are selected by Match() (event.Schema -> first match wins)
 //
-// Registration order matters because feedkit normalize.Registry is “first match wins”.
+// Registration order matters because feedkit normalize.Processor is "first match wins".
 // In weatherfeeder we avoid ambiguity by matching strictly on schema constants, but
 // we still keep ordering stable as a best practice.
-//
+func RegisterBuiltins(in []fknormalize.Normalizer) []fknormalize.Normalizer {
-// If reg is nil, this function is a no-op.
+	out := in
-func RegisterBuiltins(reg *fknormalize.Registry) {
-	if reg == nil {
-		return
-	}
 
 	// Keep this intentionally boring: delegate registration to provider subpackages
 	// so main.go stays clean and each provider owns its own mapping logic.
 	//
 	// Order here should be stable across releases to reduce surprises when adding
 	// new normalizers.
-	nws.Register(reg)
+	for _, register := range builtinRegistrations {
-	openmeteo.Register(reg)
+		out = register(out)
-	openweather.Register(reg)
+	}
+
+	return out
 }

internal/normalizers/builtins_test.go

@@ -0,0 +1,44 @@
+package normalizers
+
+import (
+	"reflect"
+	"testing"
+
+	fknormalize "gitea.maximumdirect.net/ejr/feedkit/processors/normalize"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/nws"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/openmeteo"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/openweather"
+)
+
+func TestRegisterBuiltinsOrder(t *testing.T) {
+	got := RegisterBuiltins(nil)
+	if len(got) == 0 {
+		t.Fatalf("RegisterBuiltins() returned no normalizers")
+	}
+
+	want := []fknormalize.Normalizer{
+		nws.ObservationNormalizer{},
+		nws.ForecastNormalizer{},
+		nws.ForecastDiscussionNormalizer{},
+		nws.WeatherStoriesNormalizer{},
+		nws.AlertsNormalizer{},
+		openmeteo.ObservationNormalizer{},
+		openmeteo.ForecastNormalizer{},
+		openweather.ObservationNormalizer{},
+	}
+
+	if len(got) != len(want) {
+		t.Fatalf("RegisterBuiltins() expected %d normalizers, got %d", len(want), len(got))
+	}
+
+	for i := range want {
+		if reflect.TypeOf(got[i]) != reflect.TypeOf(want[i]) {
+			t.Fatalf(
+				"RegisterBuiltins() order mismatch at index %d: got %T, want %T",
+				i,
+				got[i],
+				want[i],
+			)
+		}
+	}
+}

internal/normalizers/common/finalize.go

@@ -5,6 +5,7 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fknormalize "gitea.maximumdirect.net/ejr/feedkit/processors/normalize"
 )
 
 // Finalize builds the output event envelope by copying the input and applying the
@@ -16,20 +17,7 @@ import (
 //     If effectiveAt is zero, any existing in.EffectiveAt is preserved.
 //   - Payload floats are rounded to a stable wire-friendly precision (see round.go).
 func Finalize(in event.Event, outSchema string, outPayload any, effectiveAt time.Time) (*event.Event, error) {
-	out := in
+	// Enforce stable numeric presentation for weather payloads before delegating to feedkit's
-	out.Schema = outSchema
+	// generic envelope finalizer.
-
+	return fknormalize.FinalizeEvent(in, outSchema, RoundFloats(outPayload, DefaultFloatPrecision), effectiveAt)
-	// Enforce stable numeric presentation for sinks: round floats in the canonical payload.
-	out.Payload = RoundFloats(outPayload, DefaultFloatPrecision)
-
-	if !effectiveAt.IsZero() {
-		t := effectiveAt.UTC()
-		out.EffectiveAt = &t
-	}
-
-	if err := out.Validate(); err != nil {
-		return nil, err
-	}
-
-	return &out, nil
 }

internal/normalizers/common/finalize_test.go

@@ -0,0 +1,36 @@
+package common
+
+import (
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+)
+
+func TestFinalizeRoundsWeatherPayloadFloats(t *testing.T) {
+	type payload struct {
+		Value float64
+	}
+
+	in := event.Event{
+		ID:        "evt-1",
+		Kind:      event.Kind("observation"),
+		Source:    "source-a",
+		EmittedAt: time.Date(2026, 3, 28, 12, 0, 0, 0, time.UTC),
+		Schema:    "raw.example.v1",
+		Payload:   map[string]any{"old": true},
+	}
+
+	out, err := Finalize(in, "weather.example.v1", payload{Value: 1.234567}, time.Time{})
+	if err != nil {
+		t.Fatalf("Finalize() unexpected error: %v", err)
+	}
+
+	got, ok := out.Payload.(payload)
+	if !ok {
+		t.Fatalf("Finalize() payload type = %T, want payload", out.Payload)
+	}
+	if got.Value != 1.2346 {
+		t.Fatalf("Finalize() rounded value = %v, want 1.2346", got.Value)
+	}
+}

internal/normalizers/common/json.go

@@ -2,11 +2,11 @@
 package common
 
 import (
-	"encoding/json"
 	"fmt"
 	"time"
 
 	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fknormalize "gitea.maximumdirect.net/ejr/feedkit/processors/normalize"
 )
 
 // DecodeJSONPayload extracts the event payload as bytes and unmarshals it into T.
@@ -18,19 +18,7 @@ import (
 // Errors include a small amount of stage context ("extract payload", "decode raw payload").
 // Callers typically wrap these with a provider/kind label.
 func DecodeJSONPayload[T any](in event.Event) (T, error) {
-	var zero T
+	return fknormalize.DecodeJSONPayload[T](in)
-
-	b, err := PayloadBytes(in)
-	if err != nil {
-		return zero, fmt.Errorf("extract payload: %w", err)
-	}
-
-	var parsed T
-	if err := json.Unmarshal(b, &parsed); err != nil {
-		return zero, fmt.Errorf("decode raw payload: %w", err)
-	}
-
-	return parsed, nil
 }
 
 // NormalizeJSON is a convenience wrapper for the common JSON-normalizer pattern:

internal/normalizers/common/payload.go

@@ -1,53 +0,0 @@
-package common
-
-import (
-	"encoding/json"
-	"fmt"
-
-	"gitea.maximumdirect.net/ejr/feedkit/event"
-)
-
-// PayloadBytes extracts a JSON payload into bytes suitable for json.Unmarshal.
-//
-// Supported payload shapes (weatherfeeder convention):
-//   - json.RawMessage  (recommended for raw events)
-//   - []byte
-//   - string           (assumed to contain JSON)
-//   - map[string]any   (re-marshaled to JSON)
-//
-// If you add other raw representations later, extend this function.
-func PayloadBytes(e event.Event) ([]byte, error) {
-	if e.Payload == nil {
-		return nil, fmt.Errorf("payload is nil")
-	}
-
-	switch v := e.Payload.(type) {
-	case json.RawMessage:
-		if len(v) == 0 {
-			return nil, fmt.Errorf("payload is empty json.RawMessage")
-		}
-		return []byte(v), nil
-
-	case []byte:
-		if len(v) == 0 {
-			return nil, fmt.Errorf("payload is empty []byte")
-		}
-		return v, nil
-
-	case string:
-		if v == "" {
-			return nil, fmt.Errorf("payload is empty string")
-		}
-		return []byte(v), nil
-
-	case map[string]any:
-		b, err := json.Marshal(v)
-		if err != nil {
-			return nil, fmt.Errorf("marshal map payload: %w", err)
-		}
-		return b, nil
-
-	default:
-		return nil, fmt.Errorf("unsupported payload type %T", e.Payload)
-	}
-}

internal/normalizers/doc.go

@@ -8,7 +8,7 @@
 // transforming provider-specific raw payloads into canonical internal models.
 //
 // This package is domain code (weatherfeeder). feedkit’s normalize package is
-// infrastructure (registry + processor).
+// infrastructure (normalizer contracts + processor).
 //
 // Directory layout (required)
 // ---------------------------
@@ -29,7 +29,7 @@
 //
 //  1. One normalizer per file.
 //     Each file contains exactly one Normalizer implementation (one type that
-//     satisfies feedkit/normalize.Normalizer).
+//     satisfies feedkit/processors/normalize.Normalizer).
 //     Helper files are encouraged (types.go, common.go, mapping.go, etc.) as long
 //     as they do not define additional Normalizer types.
 //
@@ -136,21 +136,22 @@
 //
 // Registration pattern
 // --------------------
-// feedkit normalization uses a match-driven registry (“first match wins”).
+// feedkit normalization uses an ordered normalizer list ("first match wins").
 //
 // Provider subpackages should expose:
 //
-//	func Register(reg *normalize.Registry)
+//	func Register(in []normalize.Normalizer) []normalize.Normalizer
 //
 // And internal/normalizers/builtins.go should provide one entrypoint:
 //
-//	func RegisterBuiltins(reg *normalize.Registry)
+//	func RegisterBuiltins(in []normalize.Normalizer) []normalize.Normalizer
 //
-// which calls each provider’s Register() in a stable order.
+// which appends each provider's normalizers in a stable order and is then passed
+// to normalize.NewProcessor(...).
 //
-// Registry ordering
+// Normalizer ordering
 // -----------------------------
-// feedkit normalization uses a match-driven registry (“first match wins”).
+// feedkit normalization is "first match wins" by list order.
 // Therefore order matters:
 //
 //   - Register more specific normalizers before more general ones.

internal/normalizers/nws/alerts.go

@@ -11,8 +11,8 @@ import (
 	"gitea.maximumdirect.net/ejr/feedkit/event"
 	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
 	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
 )
 
 // AlertsNormalizer converts:

internal/normalizers/nws/forecast.go

@@ -10,100 +10,208 @@ import (
 	"gitea.maximumdirect.net/ejr/feedkit/event"
 	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
 	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
 )
 
 // ForecastNormalizer converts:
 //
 //	standards.SchemaRawNWSHourlyForecastV1    -> standards.SchemaWeatherForecastV1
+//	standards.SchemaRawNWSNarrativeForecastV1 -> standards.SchemaWeatherForecastV1
 //
-// It interprets NWS GeoJSON gridpoint *hourly* forecast responses and maps them into
+// It keeps one NWS forecast normalization entrypoint and dispatches to product-specific
-// the canonical model.WeatherForecastRun representation.
+// builders by raw schema.
 //
 // Caveats / policy:
-//  1. NWS forecast periods do not include METAR presentWeather phenomena, so ConditionCode
+//  1. Hourly NWS forecast periods do not include METAR presentWeather phenomena, so
-//     is inferred from period.shortForecast (with a conservative icon-based fallback).
+//     ConditionCode is inferred from period.shortForecast (with a conservative icon fallback).
-//  2. Temperature is converted to °C when NWS supplies °F.
+//  2. Narrative NWS periods intentionally leave ConditionCode unset.
-//  3. WindSpeed is parsed from strings like "9 mph" / "10 to 15 mph" and converted to km/h.
+//  3. Temperature is converted to °C when NWS supplies °F.
+//  4. WindSpeed is parsed from strings like "9 mph" / "10 to 15 mph" and converted to km/h.
 type ForecastNormalizer struct{}
 
 func (ForecastNormalizer) Match(e event.Event) bool {
-	s := strings.TrimSpace(e.Schema)
+	switch strings.TrimSpace(e.Schema) {
-	return s == standards.SchemaRawNWSHourlyForecastV1
+	case standards.SchemaRawNWSHourlyForecastV1:
+		return true
+	case standards.SchemaRawNWSNarrativeForecastV1:
+		return true
+	default:
+		return false
+	}
 }
 
 func (ForecastNormalizer) Normalize(ctx context.Context, in event.Event) (*event.Event, error) {
 	_ = ctx // normalization is pure/CPU; keep ctx for future expensive steps
 
+	return normalizeForecastEventBySchema(in)
+}
+
+func normalizeForecastEventBySchema(in event.Event) (*event.Event, error) {
+	switch strings.TrimSpace(in.Schema) {
+	case standards.SchemaRawNWSHourlyForecastV1:
+		return normalizeHourlyForecastEvent(in)
+	case standards.SchemaRawNWSNarrativeForecastV1:
+		return normalizeNarrativeForecastEvent(in)
+	default:
+		return nil, fmt.Errorf("unsupported nws forecast schema %q", strings.TrimSpace(in.Schema))
+	}
+}
+
+func normalizeHourlyForecastEvent(in event.Event) (*event.Event, error) {
 	return normcommon.NormalizeJSON(
 		in,
 		"nws hourly forecast",
 		standards.SchemaWeatherForecastV1,
-		buildForecast,
+		buildHourlyForecast,
 	)
 }
 
-// buildForecast contains the domain mapping logic (provider -> canonical model).
+func normalizeNarrativeForecastEvent(in event.Event) (*event.Event, error) {
-func buildForecast(parsed nwsForecastResponse) (model.WeatherForecastRun, time.Time, error) {
+	return normcommon.NormalizeJSON(
-	// IssuedAt is required by the canonical model.
+		in,
-	issuedStr := strings.TrimSpace(parsed.Properties.GeneratedAt)
+		"nws narrative forecast",
+		standards.SchemaWeatherForecastV1,
+		buildNarrativeForecast,
+	)
+}
+
+type forecastPeriodMapper[T any] func(idx int, period T) (model.WeatherForecastPeriod, error)
+
+// buildHourlyForecast contains hourly forecast mapping logic (provider -> canonical model).
+func buildHourlyForecast(parsed nwsHourlyForecastResponse) (model.WeatherForecastRun, time.Time, error) {
+	return buildForecastRun(
+		parsed.Properties.GeneratedAt,
+		parsed.Properties.UpdateTime,
+		parsed.Geometry.Coordinates,
+		parsed.Properties.Elevation.Value,
+		model.ForecastProductHourly,
+		parsed.Properties.Periods,
+		mapHourlyForecastPeriod,
+	)
+}
+
+// buildNarrativeForecast contains narrative forecast mapping logic (provider -> canonical model).
+func buildNarrativeForecast(parsed nwsNarrativeForecastResponse) (model.WeatherForecastRun, time.Time, error) {
+	return buildForecastRun(
+		parsed.Properties.GeneratedAt,
+		parsed.Properties.UpdateTime,
+		parsed.Geometry.Coordinates,
+		parsed.Properties.Elevation.Value,
+		model.ForecastProductNarrative,
+		parsed.Properties.Periods,
+		mapNarrativeForecastPeriod,
+	)
+}
+
+func buildForecastRun[T any](
+	generatedAt string,
+	updateTime string,
+	coordinates [][][]float64,
+	elevation *float64,
+	product model.ForecastProduct,
+	srcPeriods []T,
+	mapPeriod forecastPeriodMapper[T],
+) (model.WeatherForecastRun, time.Time, error) {
+	issuedAt, updatedAt, err := parseForecastRunTimes(generatedAt, updateTime)
+	if err != nil {
+		return model.WeatherForecastRun{}, time.Time{}, err
+	}
+
+	// Best-effort location centroid from the GeoJSON polygon (optional).
+	lat, lon := centroidLatLon(coordinates)
+
+	run := newForecastRunBase(
+		issuedAt,
+		updatedAt,
+		product,
+		lat,
+		lon,
+		elevation,
+	)
+
+	periods := make([]model.WeatherForecastPeriod, 0, len(srcPeriods))
+	for i, p := range srcPeriods {
+		period, err := mapPeriod(i, p)
+		if err != nil {
+			return model.WeatherForecastRun{}, time.Time{}, err
+		}
+		periods = append(periods, period)
+	}
+
+	run.Periods = periods
+
+	// EffectiveAt policy for forecasts: treat IssuedAt as the effective time (dedupe-friendly).
+	return run, issuedAt, nil
+}
+
+func parseForecastRunTimes(generatedAt, updateTime string) (time.Time, *time.Time, error) {
+	issuedStr := strings.TrimSpace(generatedAt)
 	if issuedStr == "" {
-		return model.WeatherForecastRun{}, time.Time{}, fmt.Errorf("missing properties.generatedAt")
+		return time.Time{}, nil, fmt.Errorf("missing properties.generatedAt")
 	}
 	issuedAt, err := nwscommon.ParseTime(issuedStr)
 	if err != nil {
-		return model.WeatherForecastRun{}, time.Time{}, fmt.Errorf("invalid properties.generatedAt %q: %w", issuedStr, err)
+		return time.Time{}, nil, fmt.Errorf("invalid properties.generatedAt %q: %w", issuedStr, err)
 	}
 	issuedAt = issuedAt.UTC()
 
-	// UpdatedAt is optional.
 	var updatedAt *time.Time
-	if s := strings.TrimSpace(parsed.Properties.UpdateTime); s != "" {
+	if s := strings.TrimSpace(updateTime); s != "" {
 		if t, err := nwscommon.ParseTime(s); err == nil {
 			tt := t.UTC()
 			updatedAt = &tt
 		}
 	}
 
-	// Best-effort location centroid from the GeoJSON polygon (optional).
+	return issuedAt, updatedAt, nil
-	lat, lon := centroidLatLon(parsed.Geometry.Coordinates)
+}
 
-	// Schema is explicitly hourly, so product is not a heuristic.
+func newForecastRunBase(
-	run := model.WeatherForecastRun{
+	issuedAt time.Time,
+	updatedAt *time.Time,
+	product model.ForecastProduct,
+	lat, lon, elevation *float64,
+) model.WeatherForecastRun {
+	return model.WeatherForecastRun{
 		LocationID:   "",
 		LocationName: "",
-
 		IssuedAt:     issuedAt,
 		UpdatedAt:    updatedAt,
-		Product:   model.ForecastProductHourly,
+		Product:      product,
-
 		Latitude:     lat,
 		Longitude:    lon,
-		ElevationMeters: parsed.Properties.Elevation.Value,
 
+		ElevationMeters: elevation,
 		Periods:         nil,
 	}
+}
 
-	periods := make([]model.WeatherForecastPeriod, 0, len(parsed.Properties.Periods))
+func parseForecastPeriodWindow(startStr, endStr string, idx int) (time.Time, time.Time, error) {
-	for i, p := range parsed.Properties.Periods {
+	startStr = strings.TrimSpace(startStr)
-		startStr := strings.TrimSpace(p.StartTime)
+	endStr = strings.TrimSpace(endStr)
-		endStr := strings.TrimSpace(p.EndTime)
 
 	if startStr == "" || endStr == "" {
-			return model.WeatherForecastRun{}, time.Time{}, fmt.Errorf("periods[%d]: missing startTime/endTime", i)
+		return time.Time{}, time.Time{}, fmt.Errorf("periods[%d]: missing startTime/endTime", idx)
 	}
 
 	start, err := nwscommon.ParseTime(startStr)
 	if err != nil {
-			return model.WeatherForecastRun{}, time.Time{}, fmt.Errorf("periods[%d].startTime invalid %q: %w", i, startStr, err)
+		return time.Time{}, time.Time{}, fmt.Errorf("periods[%d].startTime invalid %q: %w", idx, startStr, err)
 	}
 	end, err := nwscommon.ParseTime(endStr)
 	if err != nil {
-			return model.WeatherForecastRun{}, time.Time{}, fmt.Errorf("periods[%d].endTime invalid %q: %w", i, endStr, err)
+		return time.Time{}, time.Time{}, fmt.Errorf("periods[%d].endTime invalid %q: %w", idx, endStr, err)
+	}
+
+	return start.UTC(), end.UTC(), nil
+}
+
+func mapHourlyForecastPeriod(idx int, p nwsHourlyForecastPeriod) (model.WeatherForecastPeriod, error) {
+	start, end, err := parseForecastPeriodWindow(p.StartTime, p.EndTime, idx)
+	if err != nil {
+		return model.WeatherForecastPeriod{}, err
 	}
-		start = start.UTC()
-		end = end.UTC()
 
 	// NWS hourly supplies isDaytime; make it a pointer to match the canonical model.
 	var isDay *bool
@@ -117,26 +225,19 @@ func buildForecast(parsed nwsForecastResponse) (model.WeatherForecastRun, time.T
 	// Infer WMO from shortForecast (and fall back to icon token).
 	providerDesc := strings.TrimSpace(p.ShortForecast)
 	wmo := wmoFromNWSForecast(providerDesc, p.Icon, tempC)
+	wmoPtr := wmoCodePtr(wmo)
 
-		canonicalText := standards.WMOText(wmo, isDay)
+	return model.WeatherForecastPeriod{
-
-		period := model.WeatherForecastPeriod{
 		StartTime: start,
 		EndTime:   end,
 
 		Name:  strings.TrimSpace(p.Name),
 		IsDay: isDay,
 
-			ConditionCode: wmo,
+		ConditionCode: wmoPtr,
-			ConditionText: canonicalText,
 
-			ProviderRawDescription: providerDesc,
+		// For forecasts, keep provider short forecast text as the human-facing description.
-
+		TextDescription: providerDesc,
-			// For forecasts, keep provider text as the human-facing description.
-			TextDescription: strings.TrimSpace(p.ShortForecast),
-			DetailedText:    strings.TrimSpace(p.DetailedForecast),
-
-			IconURL: strings.TrimSpace(p.Icon),
 
 		TemperatureC: tempC,
 
@@ -147,13 +248,52 @@ func buildForecast(parsed nwsForecastResponse) (model.WeatherForecastRun, time.T
 		WindSpeedKmh:         parseNWSWindSpeedKmh(p.WindSpeed),
 
 		ProbabilityOfPrecipitationPercent: p.ProbabilityOfPrecipitation.Value,
-		}
+	}, nil
-
+}
-		periods = append(periods, period)
+
-	}
+func mapNarrativeForecastPeriod(idx int, p nwsNarrativeForecastPeriod) (model.WeatherForecastPeriod, error) {
-
+	start, end, err := parseForecastPeriodWindow(p.StartTime, p.EndTime, idx)
-	run.Periods = periods
+	if err != nil {
-
+		return model.WeatherForecastPeriod{}, err
-	// EffectiveAt policy for forecasts: treat IssuedAt as the effective time (dedupe-friendly).
+	}
-	return run, issuedAt, nil
+
+	// NWS narrative supplies isDaytime; make it a pointer to match the canonical model.
+	var isDay *bool
+	if p.IsDaytime != nil {
+		b := *p.IsDaytime
+		isDay = &b
+	}
+
+	tempC := tempCFromNWS(p.Temperature, p.TemperatureUnit)
+
+	shortForecast := strings.TrimSpace(p.ShortForecast)
+
+	textDescription := strings.TrimSpace(p.DetailedForecast)
+	if textDescription == "" {
+		textDescription = shortForecast
+	}
+
+	return model.WeatherForecastPeriod{
+		StartTime: start,
+		EndTime:   end,
+
+		Name:  strings.TrimSpace(p.Name),
+		IsDay: isDay,
+
+		ConditionCode: nil,
+
+		TextDescription: textDescription,
+
+		TemperatureC: tempC,
+
+		WindDirectionDegrees: parseNWSWindDirectionDegrees(p.WindDirection),
+		WindSpeedKmh:         parseNWSWindSpeedKmh(p.WindSpeed),
+
+		ProbabilityOfPrecipitationPercent: p.ProbabilityOfPrecipitation.Value,
+	}, nil
+}
+
+func wmoCodePtr(code model.WMOCode) *model.WMOCode {
+	out := code
+	return &out
 }

internal/normalizers/nws/forecast_discussion.go

@@ -0,0 +1,72 @@
+package nws
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
+	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+type ForecastDiscussionNormalizer struct{}
+
+func (ForecastDiscussionNormalizer) Match(e event.Event) bool {
+	return strings.TrimSpace(e.Schema) == standards.SchemaRawNWSForecastDiscussionV1
+}
+
+func (ForecastDiscussionNormalizer) Normalize(ctx context.Context, in event.Event) (*event.Event, error) {
+	_ = ctx
+
+	rawHTML, err := decodeStringPayload(in.Payload)
+	if err != nil {
+		return nil, fmt.Errorf("nws forecast discussion normalize: %w", err)
+	}
+
+	parsed, err := nwscommon.ParseForecastDiscussionHTML(rawHTML)
+	if err != nil {
+		return nil, fmt.Errorf("nws forecast discussion normalize: build: %w", err)
+	}
+
+	payload := model.WeatherForecastDiscussion{
+		OfficeID:    strings.TrimSpace(parsed.OfficeID),
+		OfficeName:  strings.TrimSpace(parsed.OfficeName),
+		Product:     model.ForecastDiscussionProduct(strings.TrimSpace(parsed.Product)),
+		IssuedAt:    parsed.IssuedAt.UTC(),
+		UpdatedAt:   parsed.UpdatedAt,
+		KeyMessages: append([]string(nil), parsed.KeyMessages...),
+		ShortTerm:   mapForecastDiscussionSection(parsed.ShortTerm),
+		LongTerm:    mapForecastDiscussionSection(parsed.LongTerm),
+	}
+
+	out, err := normcommon.Finalize(in, standards.SchemaWeatherForecastDiscussionV1, payload, payload.IssuedAt)
+	if err != nil {
+		return nil, fmt.Errorf("nws forecast discussion normalize: %w", err)
+	}
+	return out, nil
+}
+
+func mapForecastDiscussionSection(in *nwscommon.ForecastDiscussionSection) *model.WeatherForecastDiscussionSection {
+	if in == nil {
+		return nil
+	}
+	return &model.WeatherForecastDiscussionSection{
+		Qualifier: strings.TrimSpace(in.Qualifier),
+		IssuedAt:  in.IssuedAt,
+		Text:      strings.TrimSpace(in.Text),
+	}
+}
+
+func decodeStringPayload(payload any) (string, error) {
+	switch v := payload.(type) {
+	case string:
+		return v, nil
+	case []byte:
+		return string(v), nil
+	default:
+		return "", fmt.Errorf("extract payload: expected string payload, got %T", payload)
+	}
+}

internal/normalizers/nws/forecast_discussion_test.go

@@ -0,0 +1,130 @@
+package nws
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+func TestForecastDiscussionNormalizerProducesCanonicalSchema(t *testing.T) {
+	rawHTML := loadForecastDiscussionSampleHTML(t)
+
+	out, err := (ForecastDiscussionNormalizer{}).Normalize(nil, event.Event{
+		ID:        "evt-discussion-1",
+		Kind:      event.Kind("forecast_discussion"),
+		Source:    "nws-discussion-test",
+		EmittedAt: time.Date(2026, 3, 28, 19, 25, 0, 0, time.UTC),
+		Schema:    standards.SchemaRawNWSForecastDiscussionV1,
+		Payload:   rawHTML,
+	})
+	if err != nil {
+		t.Fatalf("Normalize() error = %v", err)
+	}
+	if out == nil {
+		t.Fatalf("Normalize() returned nil output")
+	}
+	if out.Schema != standards.SchemaWeatherForecastDiscussionV1 {
+		t.Fatalf("Schema = %q, want %q", out.Schema, standards.SchemaWeatherForecastDiscussionV1)
+	}
+	if out.Kind != event.Kind("forecast_discussion") {
+		t.Fatalf("Kind = %q, want forecast_discussion", out.Kind)
+	}
+
+	payload, ok := out.Payload.(model.WeatherForecastDiscussion)
+	if !ok {
+		t.Fatalf("Payload type = %T, want model.WeatherForecastDiscussion", out.Payload)
+	}
+	if payload.OfficeID != "LSX" {
+		t.Fatalf("OfficeID = %q, want LSX", payload.OfficeID)
+	}
+	if payload.Product != model.ForecastDiscussionProductAFD {
+		t.Fatalf("Product = %q, want %q", payload.Product, model.ForecastDiscussionProductAFD)
+	}
+	if len(payload.KeyMessages) != 3 {
+		t.Fatalf("KeyMessages len = %d, want 3", len(payload.KeyMessages))
+	}
+	if payload.ShortTerm == nil || payload.LongTerm == nil {
+		t.Fatalf("ShortTerm=%v LongTerm=%v, want both populated", payload.ShortTerm, payload.LongTerm)
+	}
+	if payload.ShortTerm.Qualifier != "(Through Late Sunday Night)" {
+		t.Fatalf("ShortTerm.Qualifier = %q", payload.ShortTerm.Qualifier)
+	}
+	if !strings.Contains(payload.ShortTerm.Text, "After a chilly morning") {
+		t.Fatalf("ShortTerm.Text = %q, want normalized prose", payload.ShortTerm.Text)
+	}
+	if strings.Contains(payload.ShortTerm.Text, "BRC") {
+		t.Fatalf("ShortTerm.Text contains signature: %q", payload.ShortTerm.Text)
+	}
+	if strings.Contains(payload.LongTerm.Text, "AVIATION") || strings.Contains(payload.LongTerm.Text, "WATCHES/WARNINGS/ADVISORIES") {
+		t.Fatalf("LongTerm.Text includes downstream sections: %q", payload.LongTerm.Text)
+	}
+	wantEffectiveAt := time.Date(2026, 3, 28, 19, 24, 0, 0, time.UTC)
+	if out.EffectiveAt == nil || !out.EffectiveAt.Equal(wantEffectiveAt) {
+		t.Fatalf("EffectiveAt = %v, want %s", out.EffectiveAt, wantEffectiveAt.Format(time.RFC3339))
+	}
+}
+
+func TestForecastDiscussionNormalizerRejectsMissingIssueTime(t *testing.T) {
+	_, err := (ForecastDiscussionNormalizer{}).Normalize(nil, event.Event{
+		ID:        "evt-discussion-bad",
+		Kind:      event.Kind("forecast_discussion"),
+		Source:    "nws-discussion-test",
+		EmittedAt: time.Date(2026, 3, 28, 19, 25, 0, 0, time.UTC),
+		Schema:    standards.SchemaRawNWSForecastDiscussionV1,
+		Payload:   "<html><body><pre class=\"glossaryProduct\">National Weather Service Saint Louis MO</pre></body></html>",
+	})
+	if err == nil {
+		t.Fatalf("Normalize() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "issue time") {
+		t.Fatalf("error = %q, want issue time context", err)
+	}
+}
+
+func TestForecastDiscussionNormalizerWireShapeHasNoUnexpectedKeys(t *testing.T) {
+	rawHTML := loadForecastDiscussionSampleHTML(t)
+
+	out, err := (ForecastDiscussionNormalizer{}).Normalize(nil, event.Event{
+		ID:        "evt-discussion-2",
+		Kind:      event.Kind("forecast_discussion"),
+		Source:    "nws-discussion-test",
+		EmittedAt: time.Date(2026, 3, 28, 19, 25, 0, 0, time.UTC),
+		Schema:    standards.SchemaRawNWSForecastDiscussionV1,
+		Payload:   rawHTML,
+	})
+	if err != nil {
+		t.Fatalf("Normalize() error = %v", err)
+	}
+
+	b, err := json.Marshal(out.Payload)
+	if err != nil {
+		t.Fatalf("json.Marshal(payload) error = %v", err)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(b, &got); err != nil {
+		t.Fatalf("json.Unmarshal(payload) error = %v", err)
+	}
+	for _, key := range []string{"sections", "aviation"} {
+		if _, ok := got[key]; ok {
+			t.Fatalf("unexpected key %q in canonical payload", key)
+		}
+	}
+}
+
+func loadForecastDiscussionSampleHTML(t *testing.T) string {
+	t.Helper()
+
+	path := filepath.Join("..", "..", "providers", "nws", "testdata", "forecast_discussion_sample.html")
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("os.ReadFile(%q) error = %v", path, err)
+	}
+	return string(b)
+}

internal/normalizers/nws/forecast_test.go

@@ -0,0 +1,330 @@
+package nws
+
+import (
+	"encoding/json"
+	"math"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+func TestBuildHourlyForecastUsesShortForecastAsTextDescription(t *testing.T) {
+	parsed := nwsHourlyForecastResponse{}
+	parsed.Properties.GeneratedAt = "2026-03-16T18:00:00Z"
+	parsed.Properties.Periods = []nwsHourlyForecastPeriod{
+		{
+			StartTime:        "2026-03-16T19:00:00Z",
+			EndTime:          "2026-03-16T20:00:00Z",
+			ShortForecast:    "  Mostly Cloudy  ",
+			DetailedForecast: "Clouds increasing overnight.",
+			Icon:             "https://example.invalid/icon",
+		},
+	}
+
+	run, effectiveAt, err := buildHourlyForecast(parsed)
+	if err != nil {
+		t.Fatalf("buildHourlyForecast() error = %v", err)
+	}
+	if len(run.Periods) != 1 {
+		t.Fatalf("periods len = %d, want 1", len(run.Periods))
+	}
+	if got, want := run.Periods[0].TextDescription, "Mostly Cloudy"; got != want {
+		t.Fatalf("TextDescription = %q, want %q", got, want)
+	}
+	if run.Periods[0].ConditionCode == nil {
+		t.Fatalf("ConditionCode is nil, want inferred hourly WMO code")
+	}
+
+	wantIssued := time.Date(2026, 3, 16, 18, 0, 0, 0, time.UTC)
+	if !run.IssuedAt.Equal(wantIssued) {
+		t.Fatalf("IssuedAt = %s, want %s", run.IssuedAt.Format(time.RFC3339), wantIssued.Format(time.RFC3339))
+	}
+	if !effectiveAt.Equal(wantIssued) {
+		t.Fatalf("effectiveAt = %s, want %s", effectiveAt.Format(time.RFC3339), wantIssued.Format(time.RFC3339))
+	}
+
+	assertNoLegacyForecastDescriptionKeys(t, run.Periods[0])
+}
+
+func TestBuildHourlyForecastPreservesUpdatedAtCentroidAndElevation(t *testing.T) {
+	parsed := nwsHourlyForecastResponse{}
+	parsed.Properties.GeneratedAt = "2026-03-16T18:00:00Z"
+	parsed.Properties.UpdateTime = "2026-03-16T18:30:00Z"
+	elevation := 123.4
+	parsed.Properties.Elevation.Value = &elevation
+	parsed.Geometry.Coordinates = [][][]float64{
+		{
+			{-90.0, 38.0},
+			{-89.0, 38.0},
+			{-89.0, 39.0},
+			{-90.0, 39.0},
+		},
+	}
+	parsed.Properties.Periods = []nwsHourlyForecastPeriod{
+		{
+			StartTime:     "2026-03-16T19:00:00Z",
+			EndTime:       "2026-03-16T20:00:00Z",
+			ShortForecast: "Cloudy",
+		},
+	}
+
+	run, effectiveAt, err := buildHourlyForecast(parsed)
+	if err != nil {
+		t.Fatalf("buildHourlyForecast() error = %v", err)
+	}
+
+	wantIssued := time.Date(2026, 3, 16, 18, 0, 0, 0, time.UTC)
+	wantUpdated := time.Date(2026, 3, 16, 18, 30, 0, 0, time.UTC)
+	if !run.IssuedAt.Equal(wantIssued) {
+		t.Fatalf("IssuedAt = %s, want %s", run.IssuedAt.Format(time.RFC3339), wantIssued.Format(time.RFC3339))
+	}
+	if run.UpdatedAt == nil || !run.UpdatedAt.Equal(wantUpdated) {
+		t.Fatalf("UpdatedAt = %v, want %s", run.UpdatedAt, wantUpdated.Format(time.RFC3339))
+	}
+	if run.Latitude == nil || math.Abs(*run.Latitude-38.5) > 0.0001 {
+		t.Fatalf("Latitude = %v, want 38.5", run.Latitude)
+	}
+	if run.Longitude == nil || math.Abs(*run.Longitude+89.5) > 0.0001 {
+		t.Fatalf("Longitude = %v, want -89.5", run.Longitude)
+	}
+	if run.ElevationMeters == nil || math.Abs(*run.ElevationMeters-elevation) > 0.0001 {
+		t.Fatalf("ElevationMeters = %v, want %.1f", run.ElevationMeters, elevation)
+	}
+	if !effectiveAt.Equal(wantIssued) {
+		t.Fatalf("effectiveAt = %s, want %s", effectiveAt.Format(time.RFC3339), wantIssued.Format(time.RFC3339))
+	}
+}
+
+func TestNormalizeForecastEventBySchemaRejectsUnsupportedSchema(t *testing.T) {
+	_, err := normalizeForecastEventBySchema(event.Event{
+		Schema: "raw.nws.daily.forecast.v1",
+	})
+	if err == nil {
+		t.Fatalf("normalizeForecastEventBySchema() expected unsupported schema error")
+	}
+	if !strings.Contains(err.Error(), "unsupported nws forecast schema") {
+		t.Fatalf("error = %q, want unsupported schema context", err)
+	}
+}
+
+func TestNormalizeForecastEventBySchemaRoutesHourly(t *testing.T) {
+	_, err := normalizeForecastEventBySchema(event.Event{
+		Schema:  standards.SchemaRawNWSHourlyForecastV1,
+		Payload: map[string]any{"properties": map[string]any{}},
+	})
+	if err == nil {
+		t.Fatalf("normalizeForecastEventBySchema() expected build error for missing generatedAt")
+	}
+	if !strings.Contains(err.Error(), "missing properties.generatedAt") {
+		t.Fatalf("error = %q, want missing properties.generatedAt", err)
+	}
+}
+
+func TestNormalizeForecastEventBySchemaRoutesNarrative(t *testing.T) {
+	_, err := normalizeForecastEventBySchema(event.Event{
+		Schema:  standards.SchemaRawNWSNarrativeForecastV1,
+		Payload: map[string]any{"properties": map[string]any{}},
+	})
+	if err == nil {
+		t.Fatalf("normalizeForecastEventBySchema() expected build error for missing generatedAt")
+	}
+	if !strings.Contains(err.Error(), "missing properties.generatedAt") {
+		t.Fatalf("error = %q, want missing properties.generatedAt", err)
+	}
+}
+
+func TestNormalizeForecastEventBySchemaProducesCanonicalWeatherForecastSchema(t *testing.T) {
+	tests := []struct {
+		name    string
+		schema  string
+		payload map[string]any
+	}{
+		{
+			name:   "hourly",
+			schema: standards.SchemaRawNWSHourlyForecastV1,
+			payload: map[string]any{
+				"properties": map[string]any{
+					"generatedAt": "2026-03-16T18:00:00Z",
+					"periods": []map[string]any{
+						{
+							"startTime":     "2026-03-16T19:00:00Z",
+							"endTime":       "2026-03-16T20:00:00Z",
+							"shortForecast": "Cloudy",
+						},
+					},
+				},
+			},
+		},
+		{
+			name:   "narrative",
+			schema: standards.SchemaRawNWSNarrativeForecastV1,
+			payload: map[string]any{
+				"properties": map[string]any{
+					"generatedAt": "2026-03-16T18:00:00Z",
+					"periods": []map[string]any{
+						{
+							"startTime":        "2026-03-16T19:00:00Z",
+							"endTime":          "2026-03-16T20:00:00Z",
+							"shortForecast":    "Cloudy",
+							"detailedForecast": "Cloudy",
+						},
+					},
+				},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			out, err := normalizeForecastEventBySchema(event.Event{
+				ID:        "evt-1",
+				Kind:      event.Kind("forecast"),
+				Source:    "nws-test",
+				EmittedAt: time.Date(2026, 3, 16, 18, 0, 0, 0, time.UTC),
+				Schema:    tt.schema,
+				Payload:   tt.payload,
+			})
+			if err != nil {
+				t.Fatalf("normalizeForecastEventBySchema() error = %v", err)
+			}
+			if out == nil {
+				t.Fatalf("normalizeForecastEventBySchema() returned nil output")
+			}
+			if out.Schema != standards.SchemaWeatherForecastV1 {
+				t.Fatalf("Schema = %q, want %q", out.Schema, standards.SchemaWeatherForecastV1)
+			}
+		})
+	}
+}
+
+func TestBuildNarrativeForecastMapsExpectedFields(t *testing.T) {
+	parsed := nwsNarrativeForecastResponse{}
+	parsed.Properties.GeneratedAt = "2026-03-27T15:17:01Z"
+	isDay := true
+	tempF := 53.0
+	pop := 20.0
+
+	parsed.Properties.Periods = []nwsNarrativeForecastPeriod{
+		{
+			Name:             "Today",
+			StartTime:        "2026-03-27T10:00:00-05:00",
+			EndTime:          "2026-03-27T18:00:00-05:00",
+			IsDaytime:        &isDay,
+			Temperature:      &tempF,
+			TemperatureUnit:  "F",
+			WindSpeed:        "10 to 14 mph",
+			WindDirection:    "SW",
+			ShortForecast:    "Partly Sunny",
+			DetailedForecast: "  Partly sunny, with a high near 53.  ",
+			ProbabilityOfPrecipitation: struct {
+				UnitCode string   `json:"unitCode"`
+				Value    *float64 `json:"value"`
+			}{
+				UnitCode: "wmoUnit:percent",
+				Value:    &pop,
+			},
+			Icon: "https://api.weather.gov/icons/land/day/bkn?size=medium",
+		},
+	}
+
+	run, effectiveAt, err := buildNarrativeForecast(parsed)
+	if err != nil {
+		t.Fatalf("buildNarrativeForecast() error = %v", err)
+	}
+	if got, want := run.Product, model.ForecastProductNarrative; got != want {
+		t.Fatalf("Product = %q, want %q", got, want)
+	}
+	if len(run.Periods) != 1 {
+		t.Fatalf("periods len = %d, want 1", len(run.Periods))
+	}
+
+	p := run.Periods[0]
+	if got, want := p.TextDescription, "Partly sunny, with a high near 53."; got != want {
+		t.Fatalf("TextDescription = %q, want %q", got, want)
+	}
+	if p.TemperatureC == nil {
+		t.Fatalf("TemperatureC is nil, want converted value")
+	}
+	if math.Abs(*p.TemperatureC-11.6666666667) > 0.0001 {
+		t.Fatalf("TemperatureC = %.6f, want ~11.6667", *p.TemperatureC)
+	}
+	if p.IsDay == nil || !*p.IsDay {
+		t.Fatalf("IsDay = %v, want true", p.IsDay)
+	}
+	if p.WindDirectionDegrees == nil || *p.WindDirectionDegrees != 225 {
+		t.Fatalf("WindDirectionDegrees = %v, want 225", p.WindDirectionDegrees)
+	}
+	if p.WindSpeedKmh == nil || math.Abs(*p.WindSpeedKmh-19.3128) > 0.001 {
+		t.Fatalf("WindSpeedKmh = %.6f, want ~19.3128", derefOrZero(p.WindSpeedKmh))
+	}
+	if p.ProbabilityOfPrecipitationPercent == nil || *p.ProbabilityOfPrecipitationPercent != 20 {
+		t.Fatalf("ProbabilityOfPrecipitationPercent = %v, want 20", p.ProbabilityOfPrecipitationPercent)
+	}
+	if p.ConditionCode != nil {
+		t.Fatalf("ConditionCode = %v, want nil for narrative period", p.ConditionCode)
+	}
+
+	wantIssued := time.Date(2026, 3, 27, 15, 17, 1, 0, time.UTC)
+	if !run.IssuedAt.Equal(wantIssued) {
+		t.Fatalf("IssuedAt = %s, want %s", run.IssuedAt.Format(time.RFC3339), wantIssued.Format(time.RFC3339))
+	}
+	if !effectiveAt.Equal(wantIssued) {
+		t.Fatalf("effectiveAt = %s, want %s", effectiveAt.Format(time.RFC3339), wantIssued.Format(time.RFC3339))
+	}
+
+	assertNoLegacyForecastDescriptionKeys(t, p)
+}
+
+func TestBuildNarrativeForecastFallsBackToShortForecastDescription(t *testing.T) {
+	parsed := nwsNarrativeForecastResponse{}
+	parsed.Properties.GeneratedAt = "2026-03-27T15:17:01Z"
+	parsed.Properties.Periods = []nwsNarrativeForecastPeriod{
+		{
+			StartTime:        "2026-03-27T18:00:00-05:00",
+			EndTime:          "2026-03-28T06:00:00-05:00",
+			ShortForecast:    "  Mostly Clear  ",
+			DetailedForecast: "   ",
+		},
+	}
+
+	run, _, err := buildNarrativeForecast(parsed)
+	if err != nil {
+		t.Fatalf("buildNarrativeForecast() error = %v", err)
+	}
+	if len(run.Periods) != 1 {
+		t.Fatalf("periods len = %d, want 1", len(run.Periods))
+	}
+	if got, want := run.Periods[0].TextDescription, "Mostly Clear"; got != want {
+		t.Fatalf("TextDescription = %q, want %q", got, want)
+	}
+}
+
+func assertNoLegacyForecastDescriptionKeys(t *testing.T, period any) {
+	t.Helper()
+
+	b, err := json.Marshal(period)
+	if err != nil {
+		t.Fatalf("json.Marshal(period) error = %v", err)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(b, &got); err != nil {
+		t.Fatalf("json.Unmarshal(period) error = %v", err)
+	}
+
+	for _, key := range []string{"conditionText", "providerRawDescription", "detailedText", "iconUrl"} {
+		if _, ok := got[key]; ok {
+			t.Fatalf("unexpected legacy key %q in marshaled period: %#v", key, got)
+		}
+	}
+}
+
+func derefOrZero(v *float64) float64 {
+	if v == nil {
+		return 0
+	}
+	return *v
+}

internal/normalizers/nws/observation.go

@@ -10,8 +10,8 @@ import (
 	"gitea.maximumdirect.net/ejr/feedkit/event"
 	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
 	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
 )
 
 // ObservationNormalizer converts:
@@ -54,14 +54,6 @@ func buildObservation(parsed nwsObservationResponse) (model.WeatherObservation,
 		ts = t.UTC()
 	}
 
-	cloudLayers := make([]model.CloudLayer, 0, len(parsed.Properties.CloudLayers))
-	for _, cl := range parsed.Properties.CloudLayers {
-		cloudLayers = append(cloudLayers, model.CloudLayer{
-			BaseMeters: cl.Base.Value,
-			Amount:     cl.Amount,
-		})
-	}
-
 	// Preserve raw presentWeather objects (for troubleshooting / drift analysis).
 	present := make([]model.PresentWeather, 0, len(parsed.Properties.PresentWeather))
 	for _, pw := range parsed.Properties.PresentWeather {
@@ -70,6 +62,7 @@ func buildObservation(parsed nwsObservationResponse) (model.WeatherObservation,
 
 	// Decode presentWeather into typed METAR phenomena for mapping.
 	phenomena := decodeMetarPhenomena(parsed.Properties.PresentWeather)
+	cloudLayers := parsed.Properties.CloudLayers
 
 	providerDesc := strings.TrimSpace(parsed.Properties.TextDescription)
 
@@ -81,9 +74,6 @@ func buildObservation(parsed nwsObservationResponse) (model.WeatherObservation,
 		isDay = isDayFromLatLonTime(*lat, *lon, ts)
 	}
 
-	// Canonical condition text comes from our WMO table.
-	canonicalText := standards.WMOText(wmo, isDay)
-
 	// Apparent temperature: prefer wind chill when both are supplied.
 	var apparentC *float64
 	if parsed.Properties.WindChill.Value != nil {
@@ -98,15 +88,9 @@ func buildObservation(parsed nwsObservationResponse) (model.WeatherObservation,
 		Timestamp:   ts,
 
 		ConditionCode: wmo,
-		ConditionText: canonicalText,
 		IsDay:         isDay,
 
-		ProviderRawDescription: providerDesc,
+		TextDescription: providerDesc,
-
-		// Transitional / human-facing:
-		// keep output consistent by populating TextDescription from canonical text.
-		TextDescription: canonicalText,
-		IconURL:         parsed.Properties.Icon,
 
 		TemperatureC: parsed.Properties.Temperature.Value,
 		DewpointC:    parsed.Properties.Dewpoint.Value,
@@ -115,19 +99,21 @@ func buildObservation(parsed nwsObservationResponse) (model.WeatherObservation,
 		WindSpeedKmh:         parsed.Properties.WindSpeed.Value,
 		WindGustKmh:          parsed.Properties.WindGust.Value,
 
-		BarometricPressurePa: parsed.Properties.BarometricPressure.Value,
+		BarometricPressurePa: pressurePrecedenceNWS(parsed.Properties.SeaLevelPressure.Value, parsed.Properties.BarometricPressure.Value),
-		SeaLevelPressurePa:   parsed.Properties.SeaLevelPressure.Value,
 		VisibilityMeters:     parsed.Properties.Visibility.Value,
 
 		RelativeHumidityPercent: parsed.Properties.RelativeHumidity.Value,
 		ApparentTemperatureC:    apparentC,
 
-		ElevationMeters: parsed.Properties.Elevation.Value,
-		RawMessage:      parsed.Properties.RawMessage,
-
 		PresentWeather: present,
-		CloudLayers:    cloudLayers,
 	}
 
 	return obs, ts, nil
 }
+
+func pressurePrecedenceNWS(seaLevelPa, barometricPa *float64) *float64 {
+	if seaLevelPa != nil {
+		return seaLevelPa
+	}
+	return barometricPa
+}

internal/normalizers/nws/observation_test.go

@@ -0,0 +1,51 @@
+package nws
+
+import "testing"
+
+func TestBuildObservationTextDescriptionAndPressurePrecedence(t *testing.T) {
+	barometric := 100200.0
+	seaLevel := 101400.0
+
+	parsed := nwsObservationResponse{}
+	parsed.Properties.Timestamp = "2026-03-16T19:00:00Z"
+	parsed.Properties.TextDescription = "  Overcast  "
+	parsed.Properties.BarometricPressure.Value = &barometric
+	parsed.Properties.SeaLevelPressure.Value = &seaLevel
+
+	obs, _, err := buildObservation(parsed)
+	if err != nil {
+		t.Fatalf("buildObservation() error = %v", err)
+	}
+
+	if got, want := obs.TextDescription, "Overcast"; got != want {
+		t.Fatalf("TextDescription = %q, want %q", got, want)
+	}
+
+	if obs.BarometricPressurePa == nil {
+		t.Fatalf("BarometricPressurePa = nil, want non-nil")
+	}
+	if got, want := *obs.BarometricPressurePa, seaLevel; got != want {
+		t.Fatalf("BarometricPressurePa = %v, want %v", got, want)
+	}
+}
+
+func TestBuildObservationPressureFallbackToBarometric(t *testing.T) {
+	barometric := 99900.0
+
+	parsed := nwsObservationResponse{}
+	parsed.Properties.Timestamp = "2026-03-16T19:00:00Z"
+	parsed.Properties.TextDescription = "Cloudy"
+	parsed.Properties.BarometricPressure.Value = &barometric
+
+	obs, _, err := buildObservation(parsed)
+	if err != nil {
+		t.Fatalf("buildObservation() error = %v", err)
+	}
+
+	if obs.BarometricPressurePa == nil {
+		t.Fatalf("BarometricPressurePa = nil, want non-nil")
+	}
+	if got, want := *obs.BarometricPressurePa, barometric; got != want {
+		t.Fatalf("BarometricPressurePa = %v, want %v", got, want)
+	}
+}

internal/normalizers/nws/register.go

@@ -2,21 +2,18 @@
 package nws
 
 import (
-	fknormalize "gitea.maximumdirect.net/ejr/feedkit/normalize"
+	fknormalize "gitea.maximumdirect.net/ejr/feedkit/processors/normalize"
 )
 
-// Register registers NWS normalizers into the provided registry.
+var builtins = []fknormalize.Normalizer{
-func Register(reg *fknormalize.Registry) {
+	ObservationNormalizer{},
-	if reg == nil {
+	ForecastNormalizer{},
-		return
+	ForecastDiscussionNormalizer{},
-	}
+	WeatherStoriesNormalizer{},
-
+	AlertsNormalizer{},
-	// Observations
+}
-	reg.Register(ObservationNormalizer{})
+
-
+// Register appends NWS normalizers in stable order.
-	// Forecasts
+func Register(in []fknormalize.Normalizer) []fknormalize.Normalizer {
-	reg.Register(ForecastNormalizer{})
+	return append(in, builtins...)
-
-	// Alerts
-	reg.Register(AlertsNormalizer{})
 }

internal/normalizers/nws/types.go

@@ -86,22 +86,21 @@ type nwsObservationResponse struct {
 		// We decode these as generic maps, then optionally interpret them in metar.go.
 		PresentWeather []map[string]any `json:"presentWeather"`
 
-		CloudLayers []struct {
+		CloudLayers []nwsCloudLayer `json:"cloudLayers"`
+	} `json:"properties"`
+}
+
+type nwsCloudLayer struct {
 	Base struct {
 		UnitCode string   `json:"unitCode"`
 		Value    *float64 `json:"value"`
 	} `json:"base"`
 	Amount string `json:"amount"`
-		} `json:"cloudLayers"`
-	} `json:"properties"`
 }
 
-// nwsForecastResponse is a minimal-but-sufficient representation of the NWS
+// nwsHourlyForecastResponse is a minimal-but-sufficient representation of the NWS
-// gridpoint forecast GeoJSON payload needed for mapping into model.WeatherForecastRun.
+// gridpoint hourly forecast GeoJSON payload needed for mapping into model.WeatherForecastRun.
-//
+type nwsHourlyForecastResponse struct {
-// This is currently designed to support the hourly forecast endpoint; revisions may be needed
-// to accommodate other forecast endpoints in the future.
-type nwsForecastResponse struct {
 	Geometry struct {
 		Type        string        `json:"type"`
 		Coordinates [][][]float64 `json:"coordinates"` // GeoJSON polygon: [ring][point][lon,lat]
@@ -120,11 +119,11 @@ type nwsForecastResponse struct {
 			Value    *float64 `json:"value"`
 		} `json:"elevation"`
 
-		Periods []nwsForecastPeriod `json:"periods"`
+		Periods []nwsHourlyForecastPeriod `json:"periods"`
 	} `json:"properties"`
 }
 
-type nwsForecastPeriod struct {
+type nwsHourlyForecastPeriod struct {
 	Number    int    `json:"number"`
 	Name      string `json:"name"`
 	StartTime string `json:"startTime"`
@@ -159,6 +158,56 @@ type nwsForecastPeriod struct {
 	DetailedForecast string `json:"detailedForecast"`
 }
 
+// nwsNarrativeForecastResponse is a minimal-but-sufficient representation of the NWS
+// gridpoint narrative forecast GeoJSON payload needed for mapping into model.WeatherForecastRun.
+type nwsNarrativeForecastResponse struct {
+	Geometry struct {
+		Type        string        `json:"type"`
+		Coordinates [][][]float64 `json:"coordinates"` // GeoJSON polygon: [ring][point][lon,lat]
+	} `json:"geometry"`
+
+	Properties struct {
+		Units             string `json:"units"`             // "us" or "si" (often "us" for narrative)
+		ForecastGenerator string `json:"forecastGenerator"` // e.g. "BaselineForecastGenerator"
+
+		GeneratedAt string `json:"generatedAt"` // RFC3339-ish
+		UpdateTime  string `json:"updateTime"`  // RFC3339-ish
+		ValidTimes  string `json:"validTimes"`
+
+		Elevation struct {
+			UnitCode string   `json:"unitCode"`
+			Value    *float64 `json:"value"`
+		} `json:"elevation"`
+
+		Periods []nwsNarrativeForecastPeriod `json:"periods"`
+	} `json:"properties"`
+}
+
+type nwsNarrativeForecastPeriod struct {
+	Number    int    `json:"number"`
+	Name      string `json:"name"`
+	StartTime string `json:"startTime"`
+	EndTime   string `json:"endTime"`
+
+	IsDaytime *bool `json:"isDaytime"`
+
+	Temperature      *float64 `json:"temperature"`
+	TemperatureUnit  string   `json:"temperatureUnit"` // "F" or "C"
+	TemperatureTrend any      `json:"temperatureTrend"`
+
+	ProbabilityOfPrecipitation struct {
+		UnitCode string   `json:"unitCode"`
+		Value    *float64 `json:"value"`
+	} `json:"probabilityOfPrecipitation"`
+
+	WindSpeed     string `json:"windSpeed"`     // e.g. "9 mph", "10 to 15 mph"
+	WindDirection string `json:"windDirection"` // e.g. "W", "NW"
+
+	Icon             string `json:"icon"`
+	ShortForecast    string `json:"shortForecast"`
+	DetailedForecast string `json:"detailedForecast"`
+}
+
 // nwsAlertsResponse is a minimal-but-sufficient representation of the NWS /alerts
 // FeatureCollection payload needed for mapping into model.WeatherAlertRun.
 type nwsAlertsResponse struct {
@@ -213,6 +262,25 @@ type nwsAlertProperties struct {
 	References json.RawMessage `json:"references"`
 }
 
+// nwsWeatherStoriesResponse is a minimal representation of the NWS /weatherstories
+// payload needed for mapping into model.WeatherStoryRun.
+type nwsWeatherStoriesResponse struct {
+	Stories []nwsWeatherStory `json:"stories"`
+}
+
+type nwsWeatherStory struct {
+	OfficeID    string `json:"officeId"`
+	StartTime   string `json:"startTime"`
+	EndTime     string `json:"endTime"`
+	UpdateTime  string `json:"updateTime"`
+	Title       string `json:"title"`
+	Description string `json:"description"`
+	AltText     string `json:"altText"`
+	Priority    bool   `json:"priority"`
+	Order       int    `json:"order"`
+	Download    string `json:"download"`
+}
+
 type nwsAlertReference struct {
 	ID         string `json:"id"`
 	Identifier string `json:"identifier"`

internal/normalizers/nws/weatherstories.go

@@ -0,0 +1,107 @@
+package nws
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
+	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+// WeatherStoriesNormalizer converts:
+//
+//	standards.SchemaRawNWSWeatherStoriesV1 -> standards.SchemaWeatherStoryV1
+//
+// It maps the NWS /weatherstories JSON response into a canonical story snapshot.
+type WeatherStoriesNormalizer struct{}
+
+func (WeatherStoriesNormalizer) Match(e event.Event) bool {
+	return strings.TrimSpace(e.Schema) == standards.SchemaRawNWSWeatherStoriesV1
+}
+
+func (WeatherStoriesNormalizer) Normalize(ctx context.Context, in event.Event) (*event.Event, error) {
+	_ = ctx
+
+	fallbackAsOf := in.EmittedAt.UTC()
+	if in.EffectiveAt != nil && !in.EffectiveAt.IsZero() {
+		fallbackAsOf = in.EffectiveAt.UTC()
+	}
+
+	return normcommon.NormalizeJSON(
+		in,
+		"nws weatherstories",
+		standards.SchemaWeatherStoryV1,
+		func(parsed nwsWeatherStoriesResponse) (model.WeatherStoryRun, time.Time, error) {
+			return buildWeatherStories(parsed, fallbackAsOf)
+		},
+	)
+}
+
+func buildWeatherStories(parsed nwsWeatherStoriesResponse, fallbackAsOf time.Time) (model.WeatherStoryRun, time.Time, error) {
+	stories := make([]model.WeatherStory, 0, len(parsed.Stories))
+
+	var officeID string
+	var asOf time.Time
+	for i, raw := range parsed.Stories {
+		startTime, err := parseRequiredNWSTime(raw.StartTime, fmt.Sprintf("stories[%d].startTime", i))
+		if err != nil {
+			return model.WeatherStoryRun{}, time.Time{}, err
+		}
+		endTime, err := parseRequiredNWSTime(raw.EndTime, fmt.Sprintf("stories[%d].endTime", i))
+		if err != nil {
+			return model.WeatherStoryRun{}, time.Time{}, err
+		}
+		updatedAt, err := parseRequiredNWSTime(raw.UpdateTime, fmt.Sprintf("stories[%d].updateTime", i))
+		if err != nil {
+			return model.WeatherStoryRun{}, time.Time{}, err
+		}
+
+		storyOfficeID := strings.TrimSpace(raw.OfficeID)
+		if officeID == "" && storyOfficeID != "" {
+			officeID = storyOfficeID
+		}
+		if asOf.IsZero() || updatedAt.After(asOf) {
+			asOf = updatedAt
+		}
+
+		stories = append(stories, model.WeatherStory{
+			OfficeID:    storyOfficeID,
+			StartTime:   startTime,
+			EndTime:     endTime,
+			UpdatedAt:   updatedAt,
+			Title:       strings.TrimSpace(raw.Title),
+			Description: strings.TrimSpace(raw.Description),
+			AltText:     strings.TrimSpace(raw.AltText),
+			Priority:    raw.Priority,
+			Order:       raw.Order,
+			DownloadURL: strings.TrimSpace(raw.Download),
+		})
+	}
+
+	if asOf.IsZero() {
+		asOf = fallbackAsOf.UTC()
+	}
+
+	run := model.WeatherStoryRun{
+		OfficeID: officeID,
+		AsOf:     asOf,
+		Stories:  stories,
+	}
+	return run, asOf, nil
+}
+
+func parseRequiredNWSTime(raw, field string) (time.Time, error) {
+	if strings.TrimSpace(raw) == "" {
+		return time.Time{}, fmt.Errorf("%s is required", field)
+	}
+	t, err := nwscommon.ParseTime(raw)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("%s: %w", field, err)
+	}
+	return t.UTC(), nil
+}

internal/normalizers/nws/weatherstories_test.go

@@ -0,0 +1,146 @@
+package nws
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+func TestWeatherStoriesNormalizerProducesCanonicalSchemaAndMapsSample(t *testing.T) {
+	out, err := (WeatherStoriesNormalizer{}).Normalize(nil, weatherStoriesRawEvent(weatherStoriesSamplePayload()))
+	if err != nil {
+		t.Fatalf("Normalize() error = %v", err)
+	}
+	if out == nil {
+		t.Fatalf("Normalize() returned nil output")
+	}
+	if out.Schema != standards.SchemaWeatherStoryV1 {
+		t.Fatalf("Schema = %q, want %q", out.Schema, standards.SchemaWeatherStoryV1)
+	}
+	if out.Kind != event.Kind("weather_story") {
+		t.Fatalf("Kind = %q, want weather_story", out.Kind)
+	}
+
+	payload, ok := out.Payload.(model.WeatherStoryRun)
+	if !ok {
+		t.Fatalf("Payload type = %T, want model.WeatherStoryRun", out.Payload)
+	}
+	if payload.OfficeID != "LSX" {
+		t.Fatalf("OfficeID = %q, want LSX", payload.OfficeID)
+	}
+	wantAsOf := time.Date(2026, 5, 30, 9, 0, 34, 0, time.UTC)
+	if !payload.AsOf.Equal(wantAsOf) {
+		t.Fatalf("AsOf = %s, want %s", payload.AsOf, wantAsOf)
+	}
+	if out.EffectiveAt == nil || !out.EffectiveAt.Equal(wantAsOf) {
+		t.Fatalf("EffectiveAt = %v, want %s", out.EffectiveAt, wantAsOf)
+	}
+	if len(payload.Stories) != 1 {
+		t.Fatalf("Stories len = %d, want 1", len(payload.Stories))
+	}
+	story := payload.Stories[0]
+	if story.Title != "Several Chances for Rain Through Monday" {
+		t.Fatalf("Title = %q", story.Title)
+	}
+	if story.Description != "A stagnant weather pattern." {
+		t.Fatalf("Description = %q", story.Description)
+	}
+	if story.AltText != "This slide shows the forecast." {
+		t.Fatalf("AltText = %q", story.AltText)
+	}
+	if story.Priority {
+		t.Fatalf("Priority = true, want false")
+	}
+	if story.Order != 1 {
+		t.Fatalf("Order = %d, want 1", story.Order)
+	}
+	if story.DownloadURL != "https://api.weather.gov/offices/LSX/weatherstories/download/3228e499-2aae-45a8-9ff9-1c060311026f" {
+		t.Fatalf("DownloadURL = %q", story.DownloadURL)
+	}
+}
+
+func TestWeatherStoriesNormalizerEmptyStoriesUsesFallbackAsOf(t *testing.T) {
+	effectiveAt := time.Date(2026, 5, 30, 12, 0, 0, 0, time.UTC)
+	in := weatherStoriesRawEvent(`{"stories":[]}`)
+	in.EffectiveAt = &effectiveAt
+
+	out, err := (WeatherStoriesNormalizer{}).Normalize(nil, in)
+	if err != nil {
+		t.Fatalf("Normalize() error = %v", err)
+	}
+	payload, ok := out.Payload.(model.WeatherStoryRun)
+	if !ok {
+		t.Fatalf("Payload type = %T, want model.WeatherStoryRun", out.Payload)
+	}
+	if !payload.AsOf.Equal(effectiveAt) {
+		t.Fatalf("AsOf = %s, want fallback %s", payload.AsOf, effectiveAt)
+	}
+	if payload.Stories == nil {
+		t.Fatalf("Stories = nil, want empty slice")
+	}
+	if len(payload.Stories) != 0 {
+		t.Fatalf("Stories len = %d, want 0", len(payload.Stories))
+	}
+}
+
+func TestWeatherStoriesNormalizerRejectsInvalidRequiredStoryTime(t *testing.T) {
+	_, err := (WeatherStoriesNormalizer{}).Normalize(nil, weatherStoriesRawEvent(`{
+		"stories": [{
+			"officeId": "LSX",
+			"startTime": "bad",
+			"endTime": "2026-05-31T11:00:00+00:00",
+			"updateTime": "2026-05-30T09:00:34+00:00"
+		}]
+	}`))
+	if err == nil {
+		t.Fatalf("Normalize() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "stories[0].startTime") {
+		t.Fatalf("error = %q, want field context", err)
+	}
+}
+
+func TestWeatherStoriesNormalizerMatch(t *testing.T) {
+	n := WeatherStoriesNormalizer{}
+	if !n.Match(event.Event{Schema: standards.SchemaRawNWSWeatherStoriesV1}) {
+		t.Fatalf("Match(raw weatherstories) = false, want true")
+	}
+	if n.Match(event.Event{Schema: standards.SchemaRawNWSAlertsV1}) {
+		t.Fatalf("Match(raw alerts) = true, want false")
+	}
+}
+
+func weatherStoriesRawEvent(payload string) event.Event {
+	return event.Event{
+		ID:        "evt-weatherstories-1",
+		Kind:      event.Kind("weather_story"),
+		Source:    "nws-weatherstories-test",
+		EmittedAt: time.Date(2026, 5, 30, 9, 5, 0, 0, time.UTC),
+		Schema:    standards.SchemaRawNWSWeatherStoriesV1,
+		Payload:   json.RawMessage(payload),
+	}
+}
+
+func weatherStoriesSamplePayload() string {
+	return `{
+		"stories": [
+			{
+				"officeId": " LSX ",
+				"startTime": "2026-05-30T08:46:00+00:00",
+				"endTime": "2026-05-31T11:00:00+00:00",
+				"updateTime": "2026-05-30T09:00:34+00:00",
+				"title": " Several Chances for Rain Through Monday ",
+				"description": " A stagnant weather pattern. ",
+				"altText": " This slide shows the forecast. ",
+				"priority": false,
+				"order": 1,
+				"download": " https://api.weather.gov/offices/LSX/weatherstories/download/3228e499-2aae-45a8-9ff9-1c060311026f "
+			}
+		]
+	}`
+}

internal/normalizers/nws/wmo_map.go

@@ -14,7 +14,7 @@ import (
 //  1. METAR phenomena (presentWeather) — most reliable for precip/hazards
 //  2. textDescription keywords — weaker, but reusable across providers
 //  3. cloud layers fallback — only for sky-only conditions
-func mapNWSToWMO(providerDesc string, cloudLayers []model.CloudLayer, phenomena []metarPhenomenon) model.WMOCode {
+func mapNWSToWMO(providerDesc string, cloudLayers []nwsCloudLayer, phenomena []metarPhenomenon) model.WMOCode {
 	// 1) Prefer METAR phenomena if present.
 	if code := wmoFromPhenomena(phenomena); code != model.WMOUnknown {
 		return code
@@ -167,7 +167,7 @@ func wmoFromPhenomena(phenomena []metarPhenomenon) model.WMOCode {
 	return model.WMOUnknown
 }
 
-func wmoFromCloudLayers(cloudLayers []model.CloudLayer) model.WMOCode {
+func wmoFromCloudLayers(cloudLayers []nwsCloudLayer) model.WMOCode {
 	// NWS cloud layer amount values commonly include:
 	// OVC, BKN, SCT, FEW, SKC, CLR, VV (vertical visibility / obscured sky)
 	//

internal/normalizers/openmeteo/forecast.go

@@ -9,8 +9,8 @@ import (
 	"gitea.maximumdirect.net/ejr/feedkit/event"
 	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
 	omcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/openmeteo"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
 )
 
 // ForecastNormalizer converts:
@@ -98,6 +98,7 @@ func buildForecast(parsed omForecastResponse, fallbackIssued time.Time) (model.W
 		}
 
 		wmo := wmoAt(parsed.Hourly.WeatherCode, i)
+		wmoPtr := wmoCodePtr(wmo)
 		canonicalText := standards.WMOText(wmo, isDay)
 
 		period := model.WeatherForecastPeriod{
@@ -107,15 +108,8 @@ func buildForecast(parsed omForecastResponse, fallbackIssued time.Time) (model.W
 			Name:  "",
 			IsDay: isDay,
 
-			ConditionCode: wmo,
+			ConditionCode:   wmoPtr,
-			ConditionText: canonicalText,
-
-			ProviderRawDescription: "",
-
 			TextDescription: canonicalText,
-			DetailedText:    "",
-
-			IconURL: "",
 		}
 
 		if v := floatAt(parsed.Hourly.Temperature2m, i); v != nil {
@@ -244,3 +238,8 @@ func wmoAt(vals []*int, idx int) model.WMOCode {
 	}
 	return model.WMOUnknown
 }
+
+func wmoCodePtr(code model.WMOCode) *model.WMOCode {
+	out := code
+	return &out
+}

internal/normalizers/openmeteo/forecast_test.go

@@ -0,0 +1,74 @@
+package openmeteo
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+func TestBuildForecastUsesCanonicalTextDescription(t *testing.T) {
+	weatherCode := 2
+	isDay := 1
+
+	parsed := omForecastResponse{
+		Timezone:         "UTC",
+		UTCOffsetSeconds: 0,
+		Hourly: omForecastHourly{
+			Time:        []string{"2026-03-16T19:00"},
+			WeatherCode: []*int{&weatherCode},
+			IsDay:       []*int{&isDay},
+		},
+	}
+
+	run, effectiveAt, err := buildForecast(parsed, time.Time{})
+	if err != nil {
+		t.Fatalf("buildForecast() error = %v", err)
+	}
+	if len(run.Periods) != 1 {
+		t.Fatalf("periods len = %d, want 1", len(run.Periods))
+	}
+
+	expectedText := standards.WMOText(model.WMOCode(weatherCode), boolPtr(true))
+	if got := run.Periods[0].TextDescription; got != expectedText {
+		t.Fatalf("TextDescription = %q, want %q", got, expectedText)
+	}
+	if run.Periods[0].ConditionCode == nil {
+		t.Fatalf("ConditionCode is nil, want mapped WMO code")
+	}
+
+	wantIssued := time.Date(2026, 3, 16, 19, 0, 0, 0, time.UTC)
+	if !run.IssuedAt.Equal(wantIssued) {
+		t.Fatalf("IssuedAt = %s, want %s", run.IssuedAt.Format(time.RFC3339), wantIssued.Format(time.RFC3339))
+	}
+	if !effectiveAt.Equal(wantIssued) {
+		t.Fatalf("effectiveAt = %s, want %s", effectiveAt.Format(time.RFC3339), wantIssued.Format(time.RFC3339))
+	}
+
+	assertNoLegacyForecastDescriptionKeys(t, run.Periods[0])
+}
+
+func boolPtr(v bool) *bool {
+	return &v
+}
+
+func assertNoLegacyForecastDescriptionKeys(t *testing.T, period any) {
+	t.Helper()
+
+	b, err := json.Marshal(period)
+	if err != nil {
+		t.Fatalf("json.Marshal(period) error = %v", err)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(b, &got); err != nil {
+		t.Fatalf("json.Unmarshal(period) error = %v", err)
+	}
+
+	for _, key := range []string{"conditionText", "providerRawDescription", "detailedText", "iconUrl"} {
+		if _, ok := got[key]; ok {
+			t.Fatalf("unexpected legacy key %q in marshaled period: %#v", key, got)
+		}
+	}
+}

internal/normalizers/openmeteo/observation.go

@@ -10,8 +10,8 @@ import (
 	"gitea.maximumdirect.net/ejr/feedkit/event"
 	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
 	omcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/openmeteo"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
 )
 
 // ObservationNormalizer converts:
@@ -87,19 +87,8 @@ func buildObservation(parsed omResponse) (model.WeatherObservation, time.Time, e
 		Timestamp:   ts,
 
 		ConditionCode:   wmo,
-		ConditionText: canonicalText,
 		IsDay:           isDay,
-
-		// Open-Meteo does not provide a separate human text description for "current"
-		// when using weather_code; we leave provider evidence empty.
-		ProviderRawDescription: "",
-
-		// Transitional / human-facing:
-		// keep output consistent by populating TextDescription from canonical text.
 		TextDescription: canonicalText,
-
-		// IconURL: Open-Meteo does not provide an icon URL in this endpoint.
-		IconURL: "",
 	}
 
 	// Measurements (all optional; only set when present).
@@ -132,20 +121,13 @@ func buildObservation(parsed omResponse) (model.WeatherObservation, time.Time, e
 		obs.WindGustKmh = &v
 	}
 
-	if parsed.Current.SurfacePressure != nil {
+	if parsed.Current.PressureMSL != nil {
+		v := normcommon.PressurePaFromHPa(*parsed.Current.PressureMSL)
+		obs.BarometricPressurePa = &v
+	} else if parsed.Current.SurfacePressure != nil {
 		v := normcommon.PressurePaFromHPa(*parsed.Current.SurfacePressure)
 		obs.BarometricPressurePa = &v
 	}
 
-	if parsed.Current.PressureMSL != nil {
-		v := normcommon.PressurePaFromHPa(*parsed.Current.PressureMSL)
-		obs.SeaLevelPressurePa = &v
-	}
-
-	if parsed.Elevation != nil {
-		v := *parsed.Elevation
-		obs.ElevationMeters = &v
-	}
-
 	return obs, ts, nil
 }

internal/normalizers/openmeteo/observation_test.go

@@ -0,0 +1,61 @@
+package openmeteo
+
+import "testing"
+
+func TestBuildObservationTextDescriptionAndPressurePrecedence(t *testing.T) {
+	weatherCode := 2
+	pressureMSL := 1016.0
+	surfacePressure := 1009.0
+
+	parsed := omResponse{
+		Timezone:         "UTC",
+		UTCOffsetSeconds: 0,
+		Current: omCurrent{
+			Time:            "2026-03-16T19:00",
+			WeatherCode:     &weatherCode,
+			PressureMSL:     &pressureMSL,
+			SurfacePressure: &surfacePressure,
+		},
+	}
+
+	obs, _, err := buildObservation(parsed)
+	if err != nil {
+		t.Fatalf("buildObservation() error = %v", err)
+	}
+
+	if got, want := obs.TextDescription, "Partly Cloudy"; got != want {
+		t.Fatalf("TextDescription = %q, want %q", got, want)
+	}
+
+	if obs.BarometricPressurePa == nil {
+		t.Fatalf("BarometricPressurePa = nil, want non-nil")
+	}
+	if got, want := *obs.BarometricPressurePa, 101600.0; got != want {
+		t.Fatalf("BarometricPressurePa = %v, want %v", got, want)
+	}
+}
+
+func TestBuildObservationPressureFallbackToSurface(t *testing.T) {
+	surfacePressure := 1008.0
+
+	parsed := omResponse{
+		Timezone:         "UTC",
+		UTCOffsetSeconds: 0,
+		Current: omCurrent{
+			Time:            "2026-03-16T19:00",
+			SurfacePressure: &surfacePressure,
+		},
+	}
+
+	obs, _, err := buildObservation(parsed)
+	if err != nil {
+		t.Fatalf("buildObservation() error = %v", err)
+	}
+
+	if obs.BarometricPressurePa == nil {
+		t.Fatalf("BarometricPressurePa = nil, want non-nil")
+	}
+	if got, want := *obs.BarometricPressurePa, 100800.0; got != want {
+		t.Fatalf("BarometricPressurePa = %v, want %v", got, want)
+	}
+}

internal/normalizers/openmeteo/register.go

@@ -2,17 +2,15 @@
 package openmeteo
 
 import (
-	fknormalize "gitea.maximumdirect.net/ejr/feedkit/normalize"
+	fknormalize "gitea.maximumdirect.net/ejr/feedkit/processors/normalize"
 )
 
-// Register registers Open-Meteo normalizers into the provided registry.
+var builtins = []fknormalize.Normalizer{
-func Register(reg *fknormalize.Registry) {
+	ObservationNormalizer{},
-	if reg == nil {
+	ForecastNormalizer{},
-		return
+}
-	}
+
-
+// Register appends Open-Meteo normalizers in stable order.
-	// Observations
+func Register(in []fknormalize.Normalizer) []fknormalize.Normalizer {
-	reg.Register(ObservationNormalizer{})
+	return append(in, builtins...)
-	// Forecasts
-	reg.Register(ForecastNormalizer{})
 }

internal/normalizers/openweather/common.go

@@ -53,15 +53,6 @@ func inferIsDay(icon string, dt, sunrise, sunset int64) *bool {
 	return nil
 }
 
-// openWeatherIconURL builds the standard OpenWeather icon URL for the given icon code.
-func openWeatherIconURL(icon string) string {
-	icon = strings.TrimSpace(icon)
-	if icon == "" {
-		return ""
-	}
-	return fmt.Sprintf("https://openweathermap.org/img/wn/%s@2x.png", icon)
-}
-
 // openWeatherStationID returns a stable station identifier for the given response.
 // Prefer the OpenWeather city ID when present; otherwise, fall back to coordinates.
 func openWeatherStationID(parsed owmResponse) string {

internal/normalizers/openweather/observation.go

@@ -8,8 +8,8 @@ import (
 
 	"gitea.maximumdirect.net/ejr/feedkit/event"
 	normcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/normalizers/common"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
 )
 
 // ObservationNormalizer converts:
@@ -75,10 +75,10 @@ func buildObservation(parsed owmResponse) (model.WeatherObservation, time.Time,
 	}
 
 	surfacePa := normcommon.PressurePaFromHPa(parsed.Main.Pressure)
-	var seaLevelPa *float64
+	barometricPa := &surfacePa
 	if parsed.Main.SeaLevel != nil {
 		v := normcommon.PressurePaFromHPa(*parsed.Main.SeaLevel)
-		seaLevelPa = &v
+		barometricPa = &v
 	}
 
 	wsKmh := normcommon.SpeedKmhFromMps(parsed.Wind.Speed)
@@ -96,9 +96,6 @@ func buildObservation(parsed owmResponse) (model.WeatherObservation, time.Time,
 
 	// Condition mapping: OpenWeather condition IDs -> canonical WMO code vocabulary.
 	wmo := mapOpenWeatherToWMO(owmID)
-	canonicalText := standards.WMOText(wmo, isDay)
-
-	iconURL := openWeatherIconURL(icon)
 
 	stationID := openWeatherStationID(parsed)
 	stationName := strings.TrimSpace(parsed.Name)
@@ -112,14 +109,8 @@ func buildObservation(parsed owmResponse) (model.WeatherObservation, time.Time,
 		Timestamp:   ts,
 
 		ConditionCode:   wmo,
-		ConditionText: canonicalText,
 		IsDay:           isDay,
-
+		TextDescription: rawDesc,
-		ProviderRawDescription: rawDesc,
-
-		// Human-facing legacy fields: populate with canonical text for consistency.
-		TextDescription: canonicalText,
-		IconURL:         iconURL,
 
 		TemperatureC:         &tempC,
 		ApparentTemperatureC: apparentC,
@@ -128,8 +119,7 @@ func buildObservation(parsed owmResponse) (model.WeatherObservation, time.Time,
 		WindSpeedKmh:         &wsKmh,
 		WindGustKmh:          wgKmh,
 
-		BarometricPressurePa: &surfacePa,
+		BarometricPressurePa: barometricPa,
-		SeaLevelPressurePa:   seaLevelPa,
 		VisibilityMeters:     visM,
 
 		RelativeHumidityPercent: &rh,

internal/normalizers/openweather/observation_test.go

@@ -0,0 +1,58 @@
+package openweather
+
+import "testing"
+
+func TestBuildObservationTextDescriptionAndPressurePrecedence(t *testing.T) {
+	seaLevel := 1018.0
+
+	parsed := owmResponse{}
+	parsed.Dt = 1710000000
+	parsed.Main.Temp = 20.0
+	parsed.Main.Humidity = 45.0
+	parsed.Main.Pressure = 1000.0
+	parsed.Main.SeaLevel = &seaLevel
+	parsed.Wind.Speed = 3.0
+	parsed.Weather = []owmWeather{
+		{ID: 801, Main: "Clouds", Description: "few clouds", Icon: "02d"},
+	}
+
+	obs, _, err := buildObservation(parsed)
+	if err != nil {
+		t.Fatalf("buildObservation() error = %v", err)
+	}
+
+	if obs.TextDescription != "few clouds" {
+		t.Fatalf("TextDescription = %q, want %q", obs.TextDescription, "few clouds")
+	}
+
+	if obs.BarometricPressurePa == nil {
+		t.Fatalf("BarometricPressurePa = nil, want non-nil")
+	}
+	if got, want := *obs.BarometricPressurePa, 101800.0; got != want {
+		t.Fatalf("BarometricPressurePa = %v, want %v", got, want)
+	}
+}
+
+func TestBuildObservationPressureFallbackToSurface(t *testing.T) {
+	parsed := owmResponse{}
+	parsed.Dt = 1710000000
+	parsed.Main.Temp = 20.0
+	parsed.Main.Humidity = 45.0
+	parsed.Main.Pressure = 1001.0
+	parsed.Wind.Speed = 3.0
+	parsed.Weather = []owmWeather{
+		{ID: 800, Description: "clear sky", Icon: "01d"},
+	}
+
+	obs, _, err := buildObservation(parsed)
+	if err != nil {
+		t.Fatalf("buildObservation() error = %v", err)
+	}
+
+	if obs.BarometricPressurePa == nil {
+		t.Fatalf("BarometricPressurePa = nil, want non-nil")
+	}
+	if got, want := *obs.BarometricPressurePa, 100100.0; got != want {
+		t.Fatalf("BarometricPressurePa = %v, want %v", got, want)
+	}
+}

internal/normalizers/openweather/register.go

@@ -2,15 +2,14 @@
 package openweather
 
 import (
-	fknormalize "gitea.maximumdirect.net/ejr/feedkit/normalize"
+	fknormalize "gitea.maximumdirect.net/ejr/feedkit/processors/normalize"
 )
 
-// Register registers OpenWeather normalizers into the provided registry.
+var builtins = []fknormalize.Normalizer{
-func Register(reg *fknormalize.Registry) {
+	ObservationNormalizer{},
-	if reg == nil {
+}
-		return
+
-	}
+// Register appends OpenWeather normalizers in stable order.
-
+func Register(in []fknormalize.Normalizer) []fknormalize.Normalizer {
-	// Observations
+	return append(in, builtins...)
-	reg.Register(ObservationNormalizer{})
 }

internal/providers/nws/forecast_discussion.go

@@ -0,0 +1,552 @@
+package nws
+
+import (
+	"fmt"
+	"html"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+)
+
+type ForecastDiscussion struct {
+	OfficeID   string
+	OfficeName string
+	Product    string
+	IssuedAt   time.Time
+	UpdatedAt  *time.Time
+
+	KeyMessages []string
+	ShortTerm   *ForecastDiscussionSection
+	LongTerm    *ForecastDiscussionSection
+}
+
+type ForecastDiscussionSection struct {
+	Qualifier string
+	IssuedAt  *time.Time
+	Text      string
+}
+
+var (
+	forecastDiscussionHeaderRE = regexp.MustCompile(`^\.(KEY MESSAGES|SHORT TERM|LONG TERM|AVIATION)\.\.\.(.*)$`)
+	forecastDiscussionAFDRE    = regexp.MustCompile(`^AFD([A-Z]{3})$`)
+	forecastDiscussionWMORE    = regexp.MustCompile(`\bK([A-Z]{3})\b`)
+	forecastDiscussionSigRE    = regexp.MustCompile(`^[A-Z]{2,6}$`)
+)
+
+func ParseForecastDiscussionHTML(raw string) (ForecastDiscussion, error) {
+	text, err := ExtractForecastDiscussionText(raw)
+	if err != nil {
+		return ForecastDiscussion{}, err
+	}
+
+	parsed, err := ParseForecastDiscussionText(text)
+	if err != nil {
+		return ForecastDiscussion{}, err
+	}
+
+	parsed.UpdatedAt = parseForecastDiscussionUpdatedAt(raw)
+	return parsed, nil
+}
+
+func ExtractForecastDiscussionText(raw string) (string, error) {
+	lower := strings.ToLower(raw)
+	searchFrom := 0
+	for {
+		openStart := strings.Index(lower[searchFrom:], "<pre")
+		if openStart < 0 {
+			return "", fmt.Errorf("missing <pre class=\"glossaryProduct\"> block")
+		}
+		openStart += searchFrom
+
+		openEnd := strings.Index(lower[openStart:], ">")
+		if openEnd < 0 {
+			return "", fmt.Errorf("unterminated <pre> tag")
+		}
+		openEnd += openStart
+
+		tag := lower[openStart : openEnd+1]
+		if isGlossaryProductTag(tag) {
+			closeStart := strings.Index(lower[openEnd+1:], "</pre>")
+			if closeStart < 0 {
+				return "", fmt.Errorf("missing closing </pre> for glossaryProduct block")
+			}
+			closeStart += openEnd + 1
+
+			text := html.UnescapeString(raw[openEnd+1 : closeStart])
+			text = strings.ReplaceAll(text, "\r\n", "\n")
+			text = strings.ReplaceAll(text, "\r", "\n")
+			return text, nil
+		}
+
+		searchFrom = openEnd + 1
+	}
+}
+
+func ParseForecastDiscussionText(text string) (ForecastDiscussion, error) {
+	lines := splitLines(text)
+
+	officeID := parseForecastDiscussionOfficeID(lines)
+	officeName, issuedAt, err := parseForecastDiscussionHeader(lines)
+	if err != nil {
+		return ForecastDiscussion{}, err
+	}
+
+	out := ForecastDiscussion{
+		OfficeID:   officeID,
+		OfficeName: officeName,
+		Product:    "afd",
+		IssuedAt:   issuedAt.UTC(),
+	}
+
+	if block, ok := extractForecastDiscussionSection(lines, "KEY MESSAGES"); ok {
+		out.KeyMessages = parseForecastDiscussionKeyMessages(block)
+	}
+	if block, ok := extractForecastDiscussionSection(lines, "SHORT TERM"); ok {
+		section, err := parseForecastDiscussionTextSection(block)
+		if err != nil {
+			return ForecastDiscussion{}, fmt.Errorf("parse SHORT TERM: %w", err)
+		}
+		out.ShortTerm = &section
+	}
+	if block, ok := extractForecastDiscussionSection(lines, "LONG TERM"); ok {
+		section, err := parseForecastDiscussionTextSection(block)
+		if err != nil {
+			return ForecastDiscussion{}, fmt.Errorf("parse LONG TERM: %w", err)
+		}
+		out.LongTerm = &section
+	}
+
+	return out, nil
+}
+
+func isGlossaryProductTag(tag string) bool {
+	tag = strings.ToLower(tag)
+	return strings.Contains(tag, `class="glossaryproduct"`) ||
+		strings.Contains(tag, `class='glossaryproduct'`) ||
+		strings.Contains(tag, `class="glossaryproduct `) ||
+		strings.Contains(tag, `class='glossaryproduct `)
+}
+
+func parseForecastDiscussionUpdatedAt(raw string) *time.Time {
+	lower := strings.ToLower(raw)
+	searchFrom := 0
+	for {
+		metaStart := strings.Index(lower[searchFrom:], "<meta")
+		if metaStart < 0 {
+			return nil
+		}
+		metaStart += searchFrom
+
+		metaEnd := strings.Index(lower[metaStart:], ">")
+		if metaEnd < 0 {
+			return nil
+		}
+		metaEnd += metaStart
+
+		tag := raw[metaStart : metaEnd+1]
+		if !strings.EqualFold(strings.TrimSpace(extractHTMLAttr(tag, "name")), "DC.date.created") {
+			searchFrom = metaEnd + 1
+			continue
+		}
+
+		content := strings.TrimSpace(extractHTMLAttr(tag, "content"))
+		if content == "" {
+			return nil
+		}
+		t, err := ParseTime(content)
+		if err != nil {
+			return nil
+		}
+		tt := t.UTC()
+		return &tt
+	}
+}
+
+func extractHTMLAttr(tag, attr string) string {
+	lower := strings.ToLower(tag)
+	attrLower := strings.ToLower(attr)
+	for i := 0; i < len(lower); i++ {
+		idx := strings.Index(lower[i:], attrLower)
+		if idx < 0 {
+			return ""
+		}
+		idx += i
+		if idx > 0 {
+			prev := lower[idx-1]
+			if isAttrNameChar(prev) {
+				i = idx + len(attrLower)
+				continue
+			}
+		}
+		j := idx + len(attrLower)
+		for j < len(lower) && isHTMLSpace(lower[j]) {
+			j++
+		}
+		if j >= len(lower) || lower[j] != '=' {
+			i = idx + len(attrLower)
+			continue
+		}
+		j++
+		for j < len(lower) && isHTMLSpace(lower[j]) {
+			j++
+		}
+		if j >= len(tag) {
+			return ""
+		}
+		quote := tag[j]
+		if quote != '"' && quote != '\'' {
+			return ""
+		}
+		j++
+		k := j
+		for k < len(tag) && tag[k] != quote {
+			k++
+		}
+		if k >= len(tag) {
+			return ""
+		}
+		return html.UnescapeString(tag[j:k])
+	}
+	return ""
+}
+
+func isHTMLSpace(b byte) bool {
+	switch b {
+	case ' ', '\n', '\r', '\t', '\f':
+		return true
+	default:
+		return false
+	}
+}
+
+func isAttrNameChar(b byte) bool {
+	switch {
+	case b >= 'a' && b <= 'z':
+		return true
+	case b >= 'A' && b <= 'Z':
+		return true
+	case b >= '0' && b <= '9':
+		return true
+	case b == '-' || b == '_' || b == ':':
+		return true
+	default:
+		return false
+	}
+}
+
+func splitLines(text string) []string {
+	text = strings.ReplaceAll(text, "\r\n", "\n")
+	text = strings.ReplaceAll(text, "\r", "\n")
+	return strings.Split(text, "\n")
+}
+
+func parseForecastDiscussionOfficeID(lines []string) string {
+	for _, raw := range lines {
+		line := strings.TrimSpace(raw)
+		if m := forecastDiscussionAFDRE.FindStringSubmatch(line); len(m) == 2 {
+			return m[1]
+		}
+	}
+	for _, raw := range lines {
+		line := strings.TrimSpace(raw)
+		if m := forecastDiscussionWMORE.FindStringSubmatch(line); len(m) == 2 {
+			return m[1]
+		}
+	}
+	return ""
+}
+
+func parseForecastDiscussionHeader(lines []string) (string, time.Time, error) {
+	for i, raw := range lines {
+		line := strings.TrimSpace(raw)
+		if !strings.HasPrefix(line, "National Weather Service ") {
+			continue
+		}
+
+		officeName := line
+		for j := i + 1; j < len(lines); j++ {
+			tsLine := strings.TrimSpace(lines[j])
+			if tsLine == "" {
+				continue
+			}
+			issuedAt, err := parseForecastDiscussionIssueTime(tsLine)
+			if err != nil {
+				return "", time.Time{}, fmt.Errorf("parse bulletin issuedAt %q: %w", tsLine, err)
+			}
+			return officeName, issuedAt.UTC(), nil
+		}
+
+		return "", time.Time{}, fmt.Errorf("missing bulletin issue time after office line")
+	}
+
+	return "", time.Time{}, fmt.Errorf("missing office header")
+}
+
+func parseForecastDiscussionIssueTime(line string) (time.Time, error) {
+	line = strings.TrimSpace(line)
+	line = strings.TrimPrefix(line, "Issued at ")
+	line = strings.TrimSpace(line)
+
+	parts := strings.Fields(line)
+	if len(parts) != 7 {
+		return time.Time{}, fmt.Errorf("unexpected issue time format")
+	}
+
+	loc, err := forecastDiscussionLocation(parts[2])
+	if err != nil {
+		return time.Time{}, err
+	}
+
+	datePart, err := time.Parse("Mon Jan 2 2006", strings.Join(parts[3:], " "))
+	if err != nil {
+		return time.Time{}, err
+	}
+
+	hour, minute, err := parseForecastDiscussionClock(parts[0], parts[1])
+	if err != nil {
+		return time.Time{}, err
+	}
+
+	return time.Date(
+		datePart.Year(),
+		datePart.Month(),
+		datePart.Day(),
+		hour,
+		minute,
+		0,
+		0,
+		loc,
+	), nil
+}
+
+func parseForecastDiscussionClock(rawClock, rawAMPM string) (int, int, error) {
+	clock := strings.TrimSpace(rawClock)
+	ampm := strings.ToUpper(strings.TrimSpace(rawAMPM))
+	if ampm != "AM" && ampm != "PM" {
+		return 0, 0, fmt.Errorf("unexpected meridiem %q", rawAMPM)
+	}
+
+	n, err := strconv.Atoi(clock)
+	if err != nil {
+		return 0, 0, fmt.Errorf("invalid clock %q", rawClock)
+	}
+
+	hour := n
+	minute := 0
+	if len(clock) >= 3 {
+		hour = n / 100
+		minute = n % 100
+	}
+
+	if hour < 1 || hour > 12 {
+		return 0, 0, fmt.Errorf("invalid hour %q", rawClock)
+	}
+	if minute < 0 || minute > 59 {
+		return 0, 0, fmt.Errorf("invalid minute %q", rawClock)
+	}
+
+	if ampm == "AM" {
+		if hour == 12 {
+			hour = 0
+		}
+		return hour, minute, nil
+	}
+
+	if hour != 12 {
+		hour += 12
+	}
+	return hour, minute, nil
+}
+
+func forecastDiscussionLocation(abbrev string) (*time.Location, error) {
+	offsets := map[string]int{
+		"AST":  -4 * 3600,
+		"ADT":  -3 * 3600,
+		"EST":  -5 * 3600,
+		"EDT":  -4 * 3600,
+		"CST":  -6 * 3600,
+		"CDT":  -5 * 3600,
+		"MST":  -7 * 3600,
+		"MDT":  -6 * 3600,
+		"PST":  -8 * 3600,
+		"PDT":  -7 * 3600,
+		"AKST": -9 * 3600,
+		"AKDT": -8 * 3600,
+		"HST":  -10 * 3600,
+		"UTC":  0,
+		"GMT":  0,
+	}
+
+	abbr := strings.ToUpper(strings.TrimSpace(abbrev))
+	offset, ok := offsets[abbr]
+	if !ok {
+		return nil, fmt.Errorf("unsupported time zone %q", abbrev)
+	}
+	return time.FixedZone(abbr, offset), nil
+}
+
+func extractForecastDiscussionSection(lines []string, section string) ([]string, bool) {
+	target := "." + section + "..."
+	for i, raw := range lines {
+		line := strings.TrimSpace(raw)
+		if !strings.HasPrefix(line, target) {
+			continue
+		}
+
+		out := []string{line}
+		for j := i + 1; j < len(lines); j++ {
+			next := strings.TrimSpace(lines[j])
+			if next == "&&" || next == "$$" || strings.Contains(next, "WATCHES/WARNINGS/ADVISORIES") {
+				break
+			}
+			if j > i+1 && isForecastDiscussionSectionHeader(next) {
+				break
+			}
+			out = append(out, lines[j])
+		}
+		return out, true
+	}
+	return nil, false
+}
+
+func isForecastDiscussionSectionHeader(line string) bool {
+	return forecastDiscussionHeaderRE.MatchString(strings.TrimSpace(line))
+}
+
+func parseForecastDiscussionKeyMessages(block []string) []string {
+	if len(block) <= 1 {
+		return nil
+	}
+
+	body := trimBlankLines(block[1:])
+	var messages []string
+	var current strings.Builder
+
+	flush := func() {
+		msg := strings.TrimSpace(current.String())
+		if msg != "" {
+			messages = append(messages, msg)
+		}
+		current.Reset()
+	}
+
+	for _, raw := range body {
+		line := strings.TrimSpace(raw)
+		if line == "" {
+			continue
+		}
+		if strings.HasPrefix(line, "-") {
+			flush()
+			line = strings.TrimSpace(strings.TrimPrefix(line, "-"))
+			current.WriteString(line)
+			continue
+		}
+		if current.Len() > 0 {
+			current.WriteByte(' ')
+		}
+		current.WriteString(line)
+	}
+	flush()
+
+	return messages
+}
+
+func parseForecastDiscussionTextSection(block []string) (ForecastDiscussionSection, error) {
+	if len(block) == 0 {
+		return ForecastDiscussionSection{}, fmt.Errorf("empty section")
+	}
+
+	section := ForecastDiscussionSection{
+		Qualifier: parseForecastDiscussionQualifier(strings.TrimSpace(block[0])),
+	}
+
+	body := trimBlankLines(block[1:])
+	if len(body) == 0 {
+		return section, nil
+	}
+
+	first := strings.TrimSpace(body[0])
+	if strings.HasPrefix(first, "Issued at ") {
+		issuedAt, err := parseForecastDiscussionIssueTime(first)
+		if err != nil {
+			return ForecastDiscussionSection{}, fmt.Errorf("parse section issuedAt %q: %w", first, err)
+		}
+		tt := issuedAt.UTC()
+		section.IssuedAt = &tt
+		body = trimBlankLines(body[1:])
+	}
+
+	body = trimForecastDiscussionSignatureLines(body)
+	section.Text = joinForecastDiscussionParagraphs(body)
+	return section, nil
+}
+
+func parseForecastDiscussionQualifier(header string) string {
+	m := forecastDiscussionHeaderRE.FindStringSubmatch(header)
+	if len(m) != 3 {
+		return ""
+	}
+	return strings.TrimSpace(m[2])
+}
+
+func trimBlankLines(lines []string) []string {
+	start := 0
+	for start < len(lines) && strings.TrimSpace(lines[start]) == "" {
+		start++
+	}
+
+	end := len(lines)
+	for end > start && strings.TrimSpace(lines[end-1]) == "" {
+		end--
+	}
+
+	return lines[start:end]
+}
+
+func trimForecastDiscussionSignatureLines(lines []string) []string {
+	lines = trimBlankLines(lines)
+	for len(lines) > 0 {
+		last := strings.TrimSpace(lines[len(lines)-1])
+		if last == "" {
+			lines = lines[:len(lines)-1]
+			continue
+		}
+		if forecastDiscussionSigRE.MatchString(last) {
+			lines = trimBlankLines(lines[:len(lines)-1])
+			continue
+		}
+		break
+	}
+	return lines
+}
+
+func joinForecastDiscussionParagraphs(lines []string) string {
+	lines = trimBlankLines(lines)
+	if len(lines) == 0 {
+		return ""
+	}
+
+	var paragraphs []string
+	current := make([]string, 0, len(lines))
+
+	flush := func() {
+		if len(current) == 0 {
+			return
+		}
+		paragraphs = append(paragraphs, strings.Join(current, " "))
+		current = current[:0]
+	}
+
+	for _, raw := range lines {
+		line := strings.TrimSpace(raw)
+		if line == "" {
+			flush()
+			continue
+		}
+		current = append(current, line)
+	}
+	flush()
+
+	return strings.Join(paragraphs, "\n\n")
+}

internal/providers/nws/forecast_discussion_test.go

@@ -0,0 +1,118 @@
+package nws
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestParseForecastDiscussionHTMLParsesExpectedFields(t *testing.T) {
+	raw := loadForecastDiscussionSampleHTML(t)
+
+	got, err := ParseForecastDiscussionHTML(raw)
+	if err != nil {
+		t.Fatalf("ParseForecastDiscussionHTML() error = %v", err)
+	}
+
+	if got.OfficeID != "LSX" {
+		t.Fatalf("OfficeID = %q, want LSX", got.OfficeID)
+	}
+	if got.OfficeName != "National Weather Service Saint Louis MO" {
+		t.Fatalf("OfficeName = %q", got.OfficeName)
+	}
+	if got.Product != "afd" {
+		t.Fatalf("Product = %q, want afd", got.Product)
+	}
+
+	wantIssuedAt := time.Date(2026, 3, 28, 19, 24, 0, 0, time.UTC)
+	if !got.IssuedAt.Equal(wantIssuedAt) {
+		t.Fatalf("IssuedAt = %s, want %s", got.IssuedAt.Format(time.RFC3339), wantIssuedAt.Format(time.RFC3339))
+	}
+
+	wantUpdatedAt := time.Date(2026, 3, 28, 20, 29, 47, 0, time.UTC)
+	if got.UpdatedAt == nil || !got.UpdatedAt.Equal(wantUpdatedAt) {
+		t.Fatalf("UpdatedAt = %v, want %s", got.UpdatedAt, wantUpdatedAt.Format(time.RFC3339))
+	}
+
+	wantMessages := []string{
+		"Elevated fire danger conditions are expected across a broad area tomorrow afternoon due to breezy southwest winds and low humidity.",
+		"Very warm temperatures are expected once again Monday and Tuesday, with highs well into the 80s.",
+		"A cold front late Tuesday or early Wednesday brings our next chance of thunderstorms, followed by a cooldown and possibly more chances for rain later in the week.",
+	}
+	if len(got.KeyMessages) != len(wantMessages) {
+		t.Fatalf("KeyMessages len = %d, want %d", len(got.KeyMessages), len(wantMessages))
+	}
+	for i := range wantMessages {
+		if got.KeyMessages[i] != wantMessages[i] {
+			t.Fatalf("KeyMessages[%d] = %q, want %q", i, got.KeyMessages[i], wantMessages[i])
+		}
+	}
+
+	if got.ShortTerm == nil {
+		t.Fatalf("ShortTerm is nil")
+	}
+	if got.ShortTerm.Qualifier != "(Through Late Sunday Night)" {
+		t.Fatalf("ShortTerm.Qualifier = %q", got.ShortTerm.Qualifier)
+	}
+	if got.ShortTerm.IssuedAt == nil || !got.ShortTerm.IssuedAt.Equal(time.Date(2026, 3, 28, 19, 19, 0, 0, time.UTC)) {
+		t.Fatalf("ShortTerm.IssuedAt = %v", got.ShortTerm.IssuedAt)
+	}
+	if !strings.Contains(got.ShortTerm.Text, "After a chilly morning") {
+		t.Fatalf("ShortTerm.Text missing expected prose: %q", got.ShortTerm.Text)
+	}
+	if strings.Contains(got.ShortTerm.Text, "BRC") {
+		t.Fatalf("ShortTerm.Text should not include signature: %q", got.ShortTerm.Text)
+	}
+	if strings.Contains(got.ShortTerm.Text, "\n\n\n") {
+		t.Fatalf("ShortTerm.Text contains unexpected paragraph breaks: %q", got.ShortTerm.Text)
+	}
+
+	if got.LongTerm == nil {
+		t.Fatalf("LongTerm is nil")
+	}
+	if got.LongTerm.Qualifier != "(Monday through Next Saturday)" {
+		t.Fatalf("LongTerm.Qualifier = %q", got.LongTerm.Qualifier)
+	}
+	if got.LongTerm.IssuedAt == nil || !got.LongTerm.IssuedAt.Equal(time.Date(2026, 3, 28, 19, 19, 0, 0, time.UTC)) {
+		t.Fatalf("LongTerm.IssuedAt = %v", got.LongTerm.IssuedAt)
+	}
+	if !strings.Contains(got.LongTerm.Text, "The peak of the warmth arrives Monday and Tuesday") {
+		t.Fatalf("LongTerm.Text missing expected prose: %q", got.LongTerm.Text)
+	}
+	if strings.Contains(got.LongTerm.Text, "AVIATION") || strings.Contains(got.LongTerm.Text, "WATCHES/WARNINGS/ADVISORIES") {
+		t.Fatalf("LongTerm.Text includes content from other sections: %q", got.LongTerm.Text)
+	}
+}
+
+func TestParseForecastDiscussionHTMLMissingPreBlock(t *testing.T) {
+	_, err := ParseForecastDiscussionHTML("<html><body><div>no pre block</div></body></html>")
+	if err == nil {
+		t.Fatalf("ParseForecastDiscussionHTML() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "glossaryProduct") {
+		t.Fatalf("error = %q, want glossaryProduct context", err)
+	}
+}
+
+func TestParseForecastDiscussionTextMissingIssueTime(t *testing.T) {
+	_, err := ParseForecastDiscussionText("National Weather Service Saint Louis MO\n\n.KEY MESSAGES...\n- Test")
+	if err == nil {
+		t.Fatalf("ParseForecastDiscussionText() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "issue time") {
+		t.Fatalf("error = %q, want issue time context", err)
+	}
+}
+
+func loadForecastDiscussionSampleHTML(t *testing.T) string {
+	t.Helper()
+
+	path := filepath.Join("testdata", "forecast_discussion_sample.html")
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("os.ReadFile(%q) error = %v", path, err)
+	}
+	return string(b)
+}

internal/providers/nws/testdata/forecast_discussion_sample.html

@@ -0,0 +1,84 @@
+<!DOCTYPE html>
+<html class="no-js">
+  <head>
+    <meta name="DC.date.created" scheme="ISO8601" content="2026-03-28T20:29:47+00:00" />
+    <title>National Weather Service</title>
+  </head>
+  <body>
+    <pre class="glossaryProduct">
+988
+FXUS63 KLSX 281924
+AFDLSX
+
+Area Forecast Discussion
+National Weather Service Saint Louis MO
+224 PM CDT Sat Mar 28 2026
+
+.KEY MESSAGES...
+
+- Elevated fire danger conditions are expected across a broad area
+  tomorrow afternoon due to breezy southwest winds and low
+  humidity.
+
+- Very warm temperatures are expected once again Monday and
+  Tuesday, with highs well into the 80s.
+
+- A cold front late Tuesday or early Wednesday brings our next
+  chance of thunderstorms, followed by a cooldown and possibly
+  more chances for rain later in the week.
+
+&&
+
+.SHORT TERM...  (Through Late Sunday Night)
+Issued at 219 PM CDT Sat Mar 28 2026
+
+After a chilly morning that saw widespread freezing temperatures,
+another warmup is in store over the next several days as southerly
+winds become re-established. We will also see the return of
+shower/thunderstorm chances Tuesday onward as we enter a more
+unsettled pattern.
+
+In the near-term, the focus continues to be on some lingering fire
+weather potential thanks to the presence of an exceptionally dry
+airmass.
+
+BRC
+
+&&
+
+.LONG TERM...  (Monday through Next Saturday)
+Issued at 219 PM CDT Sat Mar 28 2026
+
+The peak of the warmth arrives Monday and Tuesday, as a broad, but
+low-amplitude ridge nudges eastward and steady warm/moist advection
+continues on both days.
+
+Wednesday onward, the day-to-day details become much less clear, but
+latest trends suggest that an active/wet pattern will likely
+continue as another more substantial trough follows with additional
+chances for showers/thunderstorms late in the week.
+
+BRC
+
+&&
+
+.AVIATION...  (For the 18z TAFs through 18z Sunday Afternoon)
+Issued at 1133 AM CDT Sat Mar 28 2026
+
+VFR conditions are expected throughout the 18Z TAF period.
+
+BRC
+
+&&
+
+.LSX WATCHES/WARNINGS/ADVISORIES...
+MO...None.
+IL...None.
+&&
+
+$$
+
+WFO LSX
+    </pre>
+  </body>
+</html>

internal/sinks/postgres/doc.go

@@ -0,0 +1,229 @@
+// Package postgres documents weatherfeeder's PostgreSQL sink contract for
+// downstream SQL consumers.
+//
+// This package wires weatherfeeder canonical events into normalized relational
+// tables. Downstream consumers can reconstruct the same canonical JSON objects
+// that were written by joining parent/child tables as described below.
+//
+// Canonical input schemas:
+//   - weather.observation.v1 -> model.WeatherObservation
+//   - weather.forecast.v1    -> model.WeatherForecastRun
+//   - weather.forecast_discussion.v1 -> model.WeatherForecastDiscussion
+//   - weather.weather_story.v1 -> model.WeatherStoryRun
+//   - weather.alert.v1       -> model.WeatherAlertRun
+//
+// Parent/child relationships:
+//   - observations.event_id -> observation_present_weather.event_id
+//   - forecasts.event_id    -> forecast_periods.run_event_id
+//   - forecast_discussions.event_id -> forecast_discussion_key_messages.run_event_id
+//   - weather_story_runs.event_id -> weather_stories.run_event_id
+//   - alert_runs.event_id   -> alerts.run_event_id
+//   - alerts.(run_event_id, alert_index) -> alert_references.(run_event_id, alert_index)
+//
+// Dedupe and retention behavior:
+//   - Parent primary keys (event_id): observations, forecasts, alert_runs.
+//   - Child primary keys use positional indexes to preserve payload order.
+//   - Prune columns:
+//   - observations.observed_at
+//   - observation_present_weather.observed_at
+//   - forecasts.issued_at
+//   - forecast_periods.issued_at
+//   - forecast_discussions.issued_at
+//   - forecast_discussion_key_messages.issued_at
+//   - weather_story_runs.as_of
+//   - weather_stories.as_of
+//   - alert_runs.as_of
+//   - alerts.as_of
+//   - alert_references.as_of
+//
+// Envelope field mapping (shared parent columns)
+//
+// These columns exist on parent tables such as observations, forecasts,
+// forecast_discussions, weather_story_runs, and alert_runs:
+//   - event_id TEXT -> event.id
+//   - event_kind TEXT -> event.kind
+//   - event_source TEXT -> event.source
+//   - event_schema TEXT -> event.schema
+//   - event_emitted_at TIMESTAMPTZ -> event.emitted_at
+//   - event_effective_at TIMESTAMPTZ NULL -> event.effective_at
+//
+// Table contract
+//
+//  1. observations (PK: event_id)
+//
+//     - event_id TEXT -> event.id
+//     - event_kind TEXT -> event.kind
+//     - event_source TEXT -> event.source
+//     - event_schema TEXT -> event.schema
+//     - event_emitted_at TIMESTAMPTZ -> event.emitted_at
+//     - event_effective_at TIMESTAMPTZ NULL -> event.effective_at
+//     - station_id TEXT NULL -> payload.stationId
+//     - station_name TEXT NULL -> payload.stationName
+//     - observed_at TIMESTAMPTZ -> payload.timestamp
+//     - condition_code INTEGER -> payload.conditionCode
+//     - is_day BOOLEAN NULL -> payload.isDay
+//     - text_description TEXT NULL -> payload.textDescription
+//     - temperature_c DOUBLE PRECISION NULL -> payload.temperatureC
+//     - dewpoint_c DOUBLE PRECISION NULL -> payload.dewpointC
+//     - wind_direction_degrees DOUBLE PRECISION NULL -> payload.windDirectionDegrees
+//     - wind_speed_kmh DOUBLE PRECISION NULL -> payload.windSpeedKmh
+//     - wind_gust_kmh DOUBLE PRECISION NULL -> payload.windGustKmh
+//     - barometric_pressure_pa DOUBLE PRECISION NULL -> payload.barometricPressurePa
+//     - visibility_meters DOUBLE PRECISION NULL -> payload.visibilityMeters
+//     - relative_humidity_percent DOUBLE PRECISION NULL -> payload.relativeHumidityPercent
+//     - apparent_temperature_c DOUBLE PRECISION NULL -> payload.apparentTemperatureC
+//
+//  2. observation_present_weather (PK: event_id, weather_index)
+//
+//     - event_id TEXT -> observations.event_id / payload.presentWeather[i]
+//     - weather_index INTEGER -> i (array position in payload.presentWeather)
+//     - observed_at TIMESTAMPTZ -> payload.timestamp
+//     - raw_text TEXT NULL -> JSON-encoded payload.presentWeather[i].raw
+//
+// Note: raw_text stores compact JSON text. Consumers that need the original
+// object should parse raw_text as JSON.
+//
+//  3. forecasts (PK: event_id)
+//
+//     - event_id TEXT -> event.id
+//     - event_kind TEXT -> event.kind
+//     - event_source TEXT -> event.source
+//     - event_schema TEXT -> event.schema
+//     - event_emitted_at TIMESTAMPTZ -> event.emitted_at
+//     - event_effective_at TIMESTAMPTZ NULL -> event.effective_at
+//     - location_id TEXT NULL -> payload.locationId
+//     - location_name TEXT NULL -> payload.locationName
+//     - issued_at TIMESTAMPTZ -> payload.issuedAt
+//     - updated_at TIMESTAMPTZ NULL -> payload.updatedAt
+//     - product TEXT -> payload.product
+//     - latitude DOUBLE PRECISION NULL -> payload.latitude
+//     - longitude DOUBLE PRECISION NULL -> payload.longitude
+//     - elevation_meters DOUBLE PRECISION NULL -> payload.elevationMeters
+//     - period_count INTEGER -> len(payload.periods)
+//
+//  4. forecast_periods (PK: run_event_id, period_index)
+//
+//     - run_event_id TEXT -> forecasts.event_id / payload.periods[i]
+//     - period_index INTEGER -> i (array position in payload.periods)
+//     - issued_at TIMESTAMPTZ -> payload.issuedAt (copied from parent)
+//     - start_time TIMESTAMPTZ -> payload.periods[i].startTime
+//     - end_time TIMESTAMPTZ -> payload.periods[i].endTime
+//     - name TEXT NULL -> payload.periods[i].name
+//     - is_day BOOLEAN NULL -> payload.periods[i].isDay
+//     - condition_code INTEGER NULL -> payload.periods[i].conditionCode
+//     - text_description TEXT NULL -> payload.periods[i].textDescription
+//     - temperature_c DOUBLE PRECISION NULL -> payload.periods[i].temperatureC
+//     - temperature_c_min DOUBLE PRECISION NULL -> payload.periods[i].temperatureCMin
+//     - temperature_c_max DOUBLE PRECISION NULL -> payload.periods[i].temperatureCMax
+//     - dewpoint_c DOUBLE PRECISION NULL -> payload.periods[i].dewpointC
+//     - relative_humidity_percent DOUBLE PRECISION NULL -> payload.periods[i].relativeHumidityPercent
+//     - wind_direction_degrees DOUBLE PRECISION NULL -> payload.periods[i].windDirectionDegrees
+//     - wind_speed_kmh DOUBLE PRECISION NULL -> payload.periods[i].windSpeedKmh
+//     - wind_gust_kmh DOUBLE PRECISION NULL -> payload.periods[i].windGustKmh
+//     - barometric_pressure_pa DOUBLE PRECISION NULL -> payload.periods[i].barometricPressurePa
+//     - visibility_meters DOUBLE PRECISION NULL -> payload.periods[i].visibilityMeters
+//     - apparent_temperature_c DOUBLE PRECISION NULL -> payload.periods[i].apparentTemperatureC
+//     - cloud_cover_percent DOUBLE PRECISION NULL -> payload.periods[i].cloudCoverPercent
+//     - probability_of_precipitation_percent DOUBLE PRECISION NULL -> payload.periods[i].probabilityOfPrecipitationPercent
+//     - precipitation_amount_mm DOUBLE PRECISION NULL -> payload.periods[i].precipitationAmountMm
+//     - snowfall_depth_mm DOUBLE PRECISION NULL -> payload.periods[i].snowfallDepthMm
+//     - uv_index DOUBLE PRECISION NULL -> payload.periods[i].uvIndex
+//
+//  5. weather_story_runs (PK: event_id)
+//
+//     - event_id TEXT -> event.id
+//     - event_kind TEXT -> event.kind
+//     - event_source TEXT -> event.source
+//     - event_schema TEXT -> event.schema
+//     - event_emitted_at TIMESTAMPTZ -> event.emitted_at
+//     - event_effective_at TIMESTAMPTZ NULL -> event.effective_at
+//     - office_id TEXT NULL -> payload.officeId
+//     - as_of TIMESTAMPTZ -> payload.asOf
+//     - story_count INTEGER -> len(payload.stories)
+//
+//  6. weather_stories (PK: run_event_id, story_index)
+//
+//     - run_event_id TEXT -> weather_story_runs.event_id / payload.stories[i]
+//     - story_index INTEGER -> i (array position in payload.stories)
+//     - as_of TIMESTAMPTZ -> payload.asOf (copied from parent)
+//     - office_id TEXT NULL -> payload.stories[i].officeId
+//     - start_time TIMESTAMPTZ -> payload.stories[i].startTime
+//     - end_time TIMESTAMPTZ -> payload.stories[i].endTime
+//     - updated_at TIMESTAMPTZ -> payload.stories[i].updatedAt
+//     - title TEXT NULL -> payload.stories[i].title
+//     - description TEXT NULL -> payload.stories[i].description
+//     - alt_text TEXT NULL -> payload.stories[i].altText
+//     - priority BOOLEAN -> payload.stories[i].priority
+//     - story_order INTEGER -> payload.stories[i].order
+//     - download_url TEXT NULL -> payload.stories[i].downloadUrl
+//
+//  7. alert_runs (PK: event_id)
+//
+//     - event_id TEXT -> event.id
+//     - event_kind TEXT -> event.kind
+//     - event_source TEXT -> event.source
+//     - event_schema TEXT -> event.schema
+//     - event_emitted_at TIMESTAMPTZ -> event.emitted_at
+//     - event_effective_at TIMESTAMPTZ NULL -> event.effective_at
+//     - location_id TEXT NULL -> payload.locationId
+//     - location_name TEXT NULL -> payload.locationName
+//     - as_of TIMESTAMPTZ -> payload.asOf
+//     - latitude DOUBLE PRECISION NULL -> payload.latitude
+//     - longitude DOUBLE PRECISION NULL -> payload.longitude
+//     - alert_count INTEGER -> len(payload.alerts)
+//
+//  8. alerts (PK: run_event_id, alert_index)
+//
+//     - run_event_id TEXT -> alert_runs.event_id / payload.alerts[i]
+//     - alert_index INTEGER -> i (array position in payload.alerts)
+//     - as_of TIMESTAMPTZ -> payload.asOf (copied from parent)
+//     - alert_id TEXT -> payload.alerts[i].id
+//     - event TEXT NULL -> payload.alerts[i].event
+//     - headline TEXT NULL -> payload.alerts[i].headline
+//     - severity TEXT NULL -> payload.alerts[i].severity
+//     - urgency TEXT NULL -> payload.alerts[i].urgency
+//     - certainty TEXT NULL -> payload.alerts[i].certainty
+//     - status TEXT NULL -> payload.alerts[i].status
+//     - message_type TEXT NULL -> payload.alerts[i].messageType
+//     - category TEXT NULL -> payload.alerts[i].category
+//     - response TEXT NULL -> payload.alerts[i].response
+//     - description TEXT NULL -> payload.alerts[i].description
+//     - instruction TEXT NULL -> payload.alerts[i].instruction
+//     - sent TIMESTAMPTZ NULL -> payload.alerts[i].sent
+//     - effective TIMESTAMPTZ NULL -> payload.alerts[i].effective
+//     - onset TIMESTAMPTZ NULL -> payload.alerts[i].onset
+//     - expires TIMESTAMPTZ NULL -> payload.alerts[i].expires
+//     - area_description TEXT NULL -> payload.alerts[i].areaDescription
+//     - sender_name TEXT NULL -> payload.alerts[i].senderName
+//     - reference_count INTEGER -> len(payload.alerts[i].references)
+//
+//  9. alert_references (PK: run_event_id, alert_index, reference_index)
+//
+//     - run_event_id TEXT -> alert_runs.event_id / payload.alerts[i].references[j]
+//     - alert_index INTEGER -> i (array position in payload.alerts)
+//     - reference_index INTEGER -> j (array position in payload.alerts[i].references)
+//     - as_of TIMESTAMPTZ -> payload.asOf (copied from parent)
+//     - id TEXT NULL -> payload.alerts[i].references[j].id
+//     - identifier TEXT NULL -> payload.alerts[i].references[j].identifier
+//     - sender TEXT NULL -> payload.alerts[i].references[j].sender
+//     - sent TIMESTAMPTZ NULL -> payload.alerts[i].references[j].sent
+//
+// Reconstructing canonical JSON payloads
+//
+//   - WeatherObservation:
+//     read one row from observations, then join child rows by event_id ordered by
+//     weather_index to rebuild presentWeather arrays.
+//
+//   - WeatherForecastRun:
+//     read one row from forecasts, then join forecast_periods by run_event_id
+//     ordered by period_index to rebuild periods.
+//
+//   - WeatherStoryRun:
+//     read one row from weather_story_runs, then join weather_stories by
+//     run_event_id ordered by story_index to rebuild stories.
+//
+//   - WeatherAlertRun:
+//     read one row from alert_runs, join alerts by run_event_id ordered by
+//     alert_index, then join alert_references by (run_event_id, alert_index)
+//     ordered by reference_index to rebuild references per alert.
+package postgres

internal/sinks/postgres/map.go

@@ -0,0 +1,447 @@
+package postgres
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	fkevent "gitea.maximumdirect.net/ejr/feedkit/event"
+	fksinks "gitea.maximumdirect.net/ejr/feedkit/sinks"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+func mapPostgresEvent(_ context.Context, e fkevent.Event) ([]fksinks.PostgresWrite, error) {
+	schema := strings.TrimSpace(e.Schema)
+	switch schema {
+	case standards.SchemaWeatherObservationV1:
+		return mapObservationEvent(e)
+	case standards.SchemaWeatherForecastV1:
+		return mapForecastEvent(e)
+	case standards.SchemaWeatherForecastDiscussionV1:
+		return mapForecastDiscussionEvent(e)
+	case standards.SchemaWeatherStoryV1:
+		return mapWeatherStoryEvent(e)
+	case standards.SchemaWeatherAlertV1:
+		return mapAlertEvent(e)
+	default:
+		return nil, nil
+	}
+}
+
+func mapObservationEvent(e fkevent.Event) ([]fksinks.PostgresWrite, error) {
+	obs, err := decodePayload[model.WeatherObservation](e.Payload)
+	if err != nil {
+		return nil, fmt.Errorf("decode observation payload: %w", err)
+	}
+	if obs.Timestamp.IsZero() {
+		return nil, fmt.Errorf("decode observation payload: timestamp is required")
+	}
+
+	observedAt := obs.Timestamp.UTC()
+	writes := make([]fksinks.PostgresWrite, 0, 1+len(obs.PresentWeather))
+
+	writes = append(writes, fksinks.PostgresWrite{
+		Table: tableObservations,
+		Values: map[string]any{
+			"event_id":                  e.ID,
+			"event_kind":                string(e.Kind),
+			"event_source":              e.Source,
+			"event_schema":              e.Schema,
+			"event_emitted_at":          e.EmittedAt.UTC(),
+			"event_effective_at":        nullableTime(e.EffectiveAt),
+			"station_id":                nullableString(obs.StationID),
+			"station_name":              nullableString(obs.StationName),
+			"observed_at":               observedAt,
+			"condition_code":            int(obs.ConditionCode),
+			"is_day":                    nullableBool(obs.IsDay),
+			"text_description":          nullableString(obs.TextDescription),
+			"temperature_c":             nullableFloat64(obs.TemperatureC),
+			"dewpoint_c":                nullableFloat64(obs.DewpointC),
+			"wind_direction_degrees":    nullableFloat64(obs.WindDirectionDegrees),
+			"wind_speed_kmh":            nullableFloat64(obs.WindSpeedKmh),
+			"wind_gust_kmh":             nullableFloat64(obs.WindGustKmh),
+			"barometric_pressure_pa":    nullableFloat64(obs.BarometricPressurePa),
+			"visibility_meters":         nullableFloat64(obs.VisibilityMeters),
+			"relative_humidity_percent": nullableFloat64(obs.RelativeHumidityPercent),
+			"apparent_temperature_c":    nullableFloat64(obs.ApparentTemperatureC),
+		},
+	})
+
+	for i, pw := range obs.PresentWeather {
+		rawText, err := compactJSONText(pw.Raw)
+		if err != nil {
+			return nil, fmt.Errorf("observation presentWeather[%d].raw: %w", i, err)
+		}
+		writes = append(writes, fksinks.PostgresWrite{
+			Table: tableObservationPresentWeather,
+			Values: map[string]any{
+				"event_id":      e.ID,
+				"weather_index": i,
+				"observed_at":   observedAt,
+				"raw_text":      rawText,
+			},
+		})
+	}
+
+	return writes, nil
+}
+
+func mapForecastEvent(e fkevent.Event) ([]fksinks.PostgresWrite, error) {
+	run, err := decodePayload[model.WeatherForecastRun](e.Payload)
+	if err != nil {
+		return nil, fmt.Errorf("decode forecast payload: %w", err)
+	}
+	if run.IssuedAt.IsZero() {
+		return nil, fmt.Errorf("decode forecast payload: issuedAt is required")
+	}
+	if strings.TrimSpace(string(run.Product)) == "" {
+		return nil, fmt.Errorf("decode forecast payload: product is required")
+	}
+
+	issuedAt := run.IssuedAt.UTC()
+	writes := make([]fksinks.PostgresWrite, 0, 1+len(run.Periods))
+
+	writes = append(writes, fksinks.PostgresWrite{
+		Table: tableForecasts,
+		Values: map[string]any{
+			"event_id":           e.ID,
+			"event_kind":         string(e.Kind),
+			"event_source":       e.Source,
+			"event_schema":       e.Schema,
+			"event_emitted_at":   e.EmittedAt.UTC(),
+			"event_effective_at": nullableTime(e.EffectiveAt),
+			"location_id":        nullableString(run.LocationID),
+			"location_name":      nullableString(run.LocationName),
+			"issued_at":          issuedAt,
+			"updated_at":         nullableTime(run.UpdatedAt),
+			"product":            string(run.Product),
+			"latitude":           nullableFloat64(run.Latitude),
+			"longitude":          nullableFloat64(run.Longitude),
+			"elevation_meters":   nullableFloat64(run.ElevationMeters),
+			"period_count":       len(run.Periods),
+		},
+	})
+
+	for i, p := range run.Periods {
+		if p.StartTime.IsZero() || p.EndTime.IsZero() {
+			return nil, fmt.Errorf("decode forecast payload: periods[%d] startTime/endTime are required", i)
+		}
+		writes = append(writes, fksinks.PostgresWrite{
+			Table: tableForecastPeriods,
+			Values: map[string]any{
+				"run_event_id":                         e.ID,
+				"period_index":                         i,
+				"issued_at":                            issuedAt,
+				"start_time":                           p.StartTime.UTC(),
+				"end_time":                             p.EndTime.UTC(),
+				"name":                                 nullableString(p.Name),
+				"is_day":                               nullableBool(p.IsDay),
+				"condition_code":                       nullableWMOCode(p.ConditionCode),
+				"text_description":                     nullableString(p.TextDescription),
+				"temperature_c":                        nullableFloat64(p.TemperatureC),
+				"temperature_c_min":                    nullableFloat64(p.TemperatureCMin),
+				"temperature_c_max":                    nullableFloat64(p.TemperatureCMax),
+				"dewpoint_c":                           nullableFloat64(p.DewpointC),
+				"relative_humidity_percent":            nullableFloat64(p.RelativeHumidityPercent),
+				"wind_direction_degrees":               nullableFloat64(p.WindDirectionDegrees),
+				"wind_speed_kmh":                       nullableFloat64(p.WindSpeedKmh),
+				"wind_gust_kmh":                        nullableFloat64(p.WindGustKmh),
+				"barometric_pressure_pa":               nullableFloat64(p.BarometricPressurePa),
+				"visibility_meters":                    nullableFloat64(p.VisibilityMeters),
+				"apparent_temperature_c":               nullableFloat64(p.ApparentTemperatureC),
+				"cloud_cover_percent":                  nullableFloat64(p.CloudCoverPercent),
+				"probability_of_precipitation_percent": nullableFloat64(p.ProbabilityOfPrecipitationPercent),
+				"precipitation_amount_mm":              nullableFloat64(p.PrecipitationAmountMm),
+				"snowfall_depth_mm":                    nullableFloat64(p.SnowfallDepthMM),
+				"uv_index":                             nullableFloat64(p.UVIndex),
+			},
+		})
+	}
+
+	return writes, nil
+}
+
+func mapForecastDiscussionEvent(e fkevent.Event) ([]fksinks.PostgresWrite, error) {
+	run, err := decodePayload[model.WeatherForecastDiscussion](e.Payload)
+	if err != nil {
+		return nil, fmt.Errorf("decode forecast discussion payload: %w", err)
+	}
+	if run.IssuedAt.IsZero() {
+		return nil, fmt.Errorf("decode forecast discussion payload: issuedAt is required")
+	}
+	if strings.TrimSpace(string(run.Product)) == "" {
+		return nil, fmt.Errorf("decode forecast discussion payload: product is required")
+	}
+
+	issuedAt := run.IssuedAt.UTC()
+	shortTermQualifier, shortTermIssuedAt, shortTermText := nullableDiscussionSection(run.ShortTerm)
+	longTermQualifier, longTermIssuedAt, longTermText := nullableDiscussionSection(run.LongTerm)
+
+	writes := make([]fksinks.PostgresWrite, 0, 1+len(run.KeyMessages))
+	writes = append(writes, fksinks.PostgresWrite{
+		Table: tableForecastDiscussions,
+		Values: map[string]any{
+			"event_id":             e.ID,
+			"event_kind":           string(e.Kind),
+			"event_source":         e.Source,
+			"event_schema":         e.Schema,
+			"event_emitted_at":     e.EmittedAt.UTC(),
+			"event_effective_at":   nullableTime(e.EffectiveAt),
+			"office_id":            nullableString(run.OfficeID),
+			"office_name":          nullableString(run.OfficeName),
+			"issued_at":            issuedAt,
+			"updated_at":           nullableTime(run.UpdatedAt),
+			"product":              string(run.Product),
+			"short_term_qualifier": shortTermQualifier,
+			"short_term_issued_at": shortTermIssuedAt,
+			"short_term_text":      shortTermText,
+			"long_term_qualifier":  longTermQualifier,
+			"long_term_issued_at":  longTermIssuedAt,
+			"long_term_text":       longTermText,
+			"key_message_count":    len(run.KeyMessages),
+		},
+	})
+
+	for i, msg := range run.KeyMessages {
+		writes = append(writes, fksinks.PostgresWrite{
+			Table: tableForecastDiscussionKeyMessages,
+			Values: map[string]any{
+				"run_event_id":  e.ID,
+				"message_index": i,
+				"issued_at":     issuedAt,
+				"message_text":  nullableString(msg),
+			},
+		})
+	}
+
+	return writes, nil
+}
+
+func mapWeatherStoryEvent(e fkevent.Event) ([]fksinks.PostgresWrite, error) {
+	run, err := decodePayload[model.WeatherStoryRun](e.Payload)
+	if err != nil {
+		return nil, fmt.Errorf("decode weather story payload: %w", err)
+	}
+	if run.AsOf.IsZero() {
+		return nil, fmt.Errorf("decode weather story payload: asOf is required")
+	}
+
+	asOf := run.AsOf.UTC()
+	writes := make([]fksinks.PostgresWrite, 0, 1+len(run.Stories))
+	writes = append(writes, fksinks.PostgresWrite{
+		Table: tableWeatherStoryRuns,
+		Values: map[string]any{
+			"event_id":           e.ID,
+			"event_kind":         string(e.Kind),
+			"event_source":       e.Source,
+			"event_schema":       e.Schema,
+			"event_emitted_at":   e.EmittedAt.UTC(),
+			"event_effective_at": nullableTime(e.EffectiveAt),
+			"office_id":          nullableString(run.OfficeID),
+			"as_of":              asOf,
+			"story_count":        len(run.Stories),
+		},
+	})
+
+	for i, story := range run.Stories {
+		if story.StartTime.IsZero() || story.EndTime.IsZero() || story.UpdatedAt.IsZero() {
+			return nil, fmt.Errorf("decode weather story payload: stories[%d] startTime/endTime/updatedAt are required", i)
+		}
+		writes = append(writes, fksinks.PostgresWrite{
+			Table: tableWeatherStories,
+			Values: map[string]any{
+				"run_event_id": e.ID,
+				"story_index":  i,
+				"as_of":        asOf,
+				"office_id":    nullableString(story.OfficeID),
+				"start_time":   story.StartTime.UTC(),
+				"end_time":     story.EndTime.UTC(),
+				"updated_at":   story.UpdatedAt.UTC(),
+				"title":        nullableString(story.Title),
+				"description":  nullableString(story.Description),
+				"alt_text":     nullableString(story.AltText),
+				"priority":     story.Priority,
+				"story_order":  story.Order,
+				"download_url": nullableString(story.DownloadURL),
+			},
+		})
+	}
+
+	return writes, nil
+}
+
+func mapAlertEvent(e fkevent.Event) ([]fksinks.PostgresWrite, error) {
+	run, err := decodePayload[model.WeatherAlertRun](e.Payload)
+	if err != nil {
+		return nil, fmt.Errorf("decode alert payload: %w", err)
+	}
+	if run.AsOf.IsZero() {
+		return nil, fmt.Errorf("decode alert payload: asOf is required")
+	}
+
+	asOf := run.AsOf.UTC()
+	writes := make([]fksinks.PostgresWrite, 0, 1+len(run.Alerts)+countAlertReferences(run.Alerts))
+
+	writes = append(writes, fksinks.PostgresWrite{
+		Table: tableAlertRuns,
+		Values: map[string]any{
+			"event_id":           e.ID,
+			"event_kind":         string(e.Kind),
+			"event_source":       e.Source,
+			"event_schema":       e.Schema,
+			"event_emitted_at":   e.EmittedAt.UTC(),
+			"event_effective_at": nullableTime(e.EffectiveAt),
+			"location_id":        nullableString(run.LocationID),
+			"location_name":      nullableString(run.LocationName),
+			"as_of":              asOf,
+			"latitude":           nullableFloat64(run.Latitude),
+			"longitude":          nullableFloat64(run.Longitude),
+			"alert_count":        len(run.Alerts),
+		},
+	})
+
+	for i, a := range run.Alerts {
+		if strings.TrimSpace(a.ID) == "" {
+			return nil, fmt.Errorf("decode alert payload: alerts[%d].id is required", i)
+		}
+
+		writes = append(writes, fksinks.PostgresWrite{
+			Table: tableAlerts,
+			Values: map[string]any{
+				"run_event_id":     e.ID,
+				"alert_index":      i,
+				"as_of":            asOf,
+				"alert_id":         a.ID,
+				"event":            nullableString(a.Event),
+				"headline":         nullableString(a.Headline),
+				"severity":         nullableString(a.Severity),
+				"urgency":          nullableString(a.Urgency),
+				"certainty":        nullableString(a.Certainty),
+				"status":           nullableString(a.Status),
+				"message_type":     nullableString(a.MessageType),
+				"category":         nullableString(a.Category),
+				"response":         nullableString(a.Response),
+				"description":      nullableString(a.Description),
+				"instruction":      nullableString(a.Instruction),
+				"sent":             nullableTime(a.Sent),
+				"effective":        nullableTime(a.Effective),
+				"onset":            nullableTime(a.Onset),
+				"expires":          nullableTime(a.Expires),
+				"area_description": nullableString(a.AreaDescription),
+				"sender_name":      nullableString(a.SenderName),
+				"reference_count":  len(a.References),
+			},
+		})
+
+		for j, ref := range a.References {
+			writes = append(writes, fksinks.PostgresWrite{
+				Table: tableAlertReferences,
+				Values: map[string]any{
+					"run_event_id":    e.ID,
+					"alert_index":     i,
+					"reference_index": j,
+					"as_of":           asOf,
+					"id":              nullableString(ref.ID),
+					"identifier":      nullableString(ref.Identifier),
+					"sender":          nullableString(ref.Sender),
+					"sent":            nullableTime(ref.Sent),
+				},
+			})
+		}
+	}
+
+	return writes, nil
+}
+
+func decodePayload[T any](payload any) (T, error) {
+	var out T
+	if payload == nil {
+		return out, fmt.Errorf("payload is nil")
+	}
+
+	if typed, ok := payload.(T); ok {
+		return typed, nil
+	}
+	if ptr, ok := payload.(*T); ok {
+		if ptr == nil {
+			return out, fmt.Errorf("payload pointer is nil")
+		}
+		return *ptr, nil
+	}
+
+	b, err := json.Marshal(payload)
+	if err != nil {
+		return out, fmt.Errorf("marshal payload: %w", err)
+	}
+	if err := json.Unmarshal(b, &out); err != nil {
+		return out, fmt.Errorf("unmarshal payload: %w", err)
+	}
+	return out, nil
+}
+
+func nullableDiscussionSection(section *model.WeatherForecastDiscussionSection) (any, any, any) {
+	if section == nil {
+		return nil, nil, nil
+	}
+	return nullableString(section.Qualifier), nullableTime(section.IssuedAt), nullableString(section.Text)
+}
+
+func countAlertReferences(alerts []model.WeatherAlert) int {
+	total := 0
+	for _, a := range alerts {
+		total += len(a.References)
+	}
+	return total
+}
+
+func nullableString(s string) any {
+	if strings.TrimSpace(s) == "" {
+		return nil
+	}
+	return s
+}
+
+func nullableFloat64(v *float64) any {
+	if v == nil {
+		return nil
+	}
+	return *v
+}
+
+func nullableBool(v *bool) any {
+	if v == nil {
+		return nil
+	}
+	return *v
+}
+
+func nullableTime(v *time.Time) any {
+	if v == nil || v.IsZero() {
+		return nil
+	}
+	return v.UTC()
+}
+
+func nullableWMOCode(v *model.WMOCode) any {
+	if v == nil {
+		return nil
+	}
+	return int(*v)
+}
+
+func compactJSONText(v any) (any, error) {
+	if v == nil {
+		return nil, nil
+	}
+	b, err := json.Marshal(v)
+	if err != nil {
+		return nil, err
+	}
+	if string(b) == "null" {
+		return nil, nil
+	}
+	return string(b), nil
+}

internal/sinks/postgres/map_test.go

@@ -0,0 +1,379 @@
+package postgres
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	fkevent "gitea.maximumdirect.net/ejr/feedkit/event"
+	fksinks "gitea.maximumdirect.net/ejr/feedkit/sinks"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/model"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+func TestMapPostgresEventObservationStructPayload(t *testing.T) {
+	isDay := true
+	temp := 21.5
+	obs := model.WeatherObservation{
+		StationID:       "KSTL",
+		StationName:     "St. Louis",
+		Timestamp:       time.Date(2026, 3, 16, 19, 0, 0, 0, time.UTC),
+		ConditionCode:   model.WMOCode(1),
+		IsDay:           &isDay,
+		TextDescription: "few clouds",
+		TemperatureC:    &temp,
+		PresentWeather:  []model.PresentWeather{{Raw: map[string]any{"a": 1, "b": "x"}}},
+	}
+
+	writes, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherObservationV1, "observation", obs))
+	if err != nil {
+		t.Fatalf("mapPostgresEvent() error = %v", err)
+	}
+	if len(writes) != 2 {
+		t.Fatalf("mapPostgresEvent() writes len = %d, want 2", len(writes))
+	}
+	if writes[0].Table != tableObservations {
+		t.Fatalf("writes[0].Table = %q, want %q", writes[0].Table, tableObservations)
+	}
+	if got := writes[0].Values["station_id"]; got != "KSTL" {
+		t.Fatalf("observations station_id = %#v, want KSTL", got)
+	}
+	if writes[1].Table != tableObservationPresentWeather {
+		t.Fatalf("writes[1].Table = %q, want %q", writes[1].Table, tableObservationPresentWeather)
+	}
+	if got := writes[1].Values["raw_text"]; got != `{"a":1,"b":"x"}` {
+		t.Fatalf("present_weather raw_text = %#v, want compact JSON", got)
+	}
+
+	assertAllWritesIncludeAllColumns(t, writes)
+}
+
+func TestMapPostgresEventForecastStructPayload(t *testing.T) {
+	isDay := true
+	temp := 10.5
+	run := model.WeatherForecastRun{
+		LocationID:   "LOC-1",
+		LocationName: "St. Louis",
+		IssuedAt:     time.Date(2026, 3, 16, 18, 0, 0, 0, time.UTC),
+		Product:      model.ForecastProductHourly,
+		Periods: []model.WeatherForecastPeriod{
+			{
+				StartTime:     time.Date(2026, 3, 16, 19, 0, 0, 0, time.UTC),
+				EndTime:       time.Date(2026, 3, 16, 20, 0, 0, 0, time.UTC),
+				IsDay:         &isDay,
+				ConditionCode: wmoCodePtr(model.WMOCode(2)),
+				TemperatureC:  &temp,
+			},
+			{
+				StartTime:     time.Date(2026, 3, 16, 20, 0, 0, 0, time.UTC),
+				EndTime:       time.Date(2026, 3, 16, 21, 0, 0, 0, time.UTC),
+				ConditionCode: nil,
+			},
+		},
+	}
+
+	writes, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherForecastV1, "forecast", run))
+	if err != nil {
+		t.Fatalf("mapPostgresEvent() error = %v", err)
+	}
+	if len(writes) != 3 {
+		t.Fatalf("mapPostgresEvent() writes len = %d, want 3", len(writes))
+	}
+
+	if writes[0].Table != tableForecasts {
+		t.Fatalf("writes[0].Table = %q, want %q", writes[0].Table, tableForecasts)
+	}
+	if got := writes[0].Values["period_count"]; got != 2 {
+		t.Fatalf("forecasts period_count = %#v, want 2", got)
+	}
+	if writes[1].Table != tableForecastPeriods || writes[2].Table != tableForecastPeriods {
+		t.Fatalf("forecast period writes not in expected order")
+	}
+	if got := writes[1].Values["period_index"]; got != 0 {
+		t.Fatalf("first period index = %#v, want 0", got)
+	}
+	if got := writes[2].Values["condition_code"]; got != nil {
+		t.Fatalf("second period condition_code = %#v, want nil", got)
+	}
+
+	assertAllWritesIncludeAllColumns(t, writes)
+}
+
+func TestMapPostgresEventAlertStructPayload(t *testing.T) {
+	sent := time.Date(2026, 3, 16, 17, 0, 0, 0, time.UTC)
+	run := model.WeatherAlertRun{
+		AsOf: time.Date(2026, 3, 16, 18, 0, 0, 0, time.UTC),
+		Alerts: []model.WeatherAlert{
+			{
+				ID:       "urn:alert:1",
+				Headline: "Winter Weather Advisory",
+				Severity: "Moderate",
+				References: []model.AlertReference{
+					{ID: "urn:ref:1", Sent: &sent},
+					{Identifier: "ref-two"},
+				},
+			},
+			{
+				ID:       "urn:alert:2",
+				Headline: "Second alert",
+			},
+		},
+	}
+
+	writes, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherAlertV1, "alert", run))
+	if err != nil {
+		t.Fatalf("mapPostgresEvent() error = %v", err)
+	}
+	if len(writes) != 5 {
+		t.Fatalf("mapPostgresEvent() writes len = %d, want 5", len(writes))
+	}
+
+	counts := map[string]int{}
+	for _, w := range writes {
+		counts[w.Table]++
+	}
+	if counts[tableAlertRuns] != 1 || counts[tableAlerts] != 2 || counts[tableAlertReferences] != 2 {
+		t.Fatalf("unexpected table write counts: %#v", counts)
+	}
+
+	firstAlert, ok := firstWriteForTable(writes, tableAlerts)
+	if !ok {
+		t.Fatalf("missing alerts write")
+	}
+	if got := firstAlert.Values["reference_count"]; got != 2 {
+		t.Fatalf("alerts reference_count = %#v, want 2", got)
+	}
+
+	assertAllWritesIncludeAllColumns(t, writes)
+}
+
+func TestMapPostgresEventForecastDiscussionStructPayload(t *testing.T) {
+	updatedAt := time.Date(2026, 3, 28, 20, 29, 47, 0, time.UTC)
+	shortIssuedAt := time.Date(2026, 3, 28, 19, 19, 0, 0, time.UTC)
+	run := model.WeatherForecastDiscussion{
+		OfficeID:    "LSX",
+		OfficeName:  "National Weather Service Saint Louis MO",
+		Product:     model.ForecastDiscussionProductAFD,
+		IssuedAt:    time.Date(2026, 3, 28, 19, 24, 0, 0, time.UTC),
+		UpdatedAt:   &updatedAt,
+		KeyMessages: []string{"msg one", "msg two"},
+		ShortTerm:   &model.WeatherForecastDiscussionSection{Qualifier: "(Tonight)", IssuedAt: &shortIssuedAt, Text: "Short term text"},
+		LongTerm:    &model.WeatherForecastDiscussionSection{Text: "Long term text"},
+	}
+
+	writes, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherForecastDiscussionV1, "forecast_discussion", run))
+	if err != nil {
+		t.Fatalf("mapPostgresEvent() error = %v", err)
+	}
+	if len(writes) != 3 {
+		t.Fatalf("mapPostgresEvent() writes len = %d, want 3", len(writes))
+	}
+
+	if writes[0].Table != tableForecastDiscussions {
+		t.Fatalf("writes[0].Table = %q, want %q", writes[0].Table, tableForecastDiscussions)
+	}
+	if got := writes[0].Values["key_message_count"]; got != 2 {
+		t.Fatalf("forecast_discussions key_message_count = %#v, want 2", got)
+	}
+	if got := writes[0].Values["short_term_qualifier"]; got != "(Tonight)" {
+		t.Fatalf("forecast_discussions short_term_qualifier = %#v, want (Tonight)", got)
+	}
+	if got := writes[0].Values["long_term_issued_at"]; got != nil {
+		t.Fatalf("forecast_discussions long_term_issued_at = %#v, want nil", got)
+	}
+	if writes[1].Table != tableForecastDiscussionKeyMessages || writes[2].Table != tableForecastDiscussionKeyMessages {
+		t.Fatalf("forecast discussion key message writes not in expected order")
+	}
+	if got := writes[2].Values["message_index"]; got != 1 {
+		t.Fatalf("second key message index = %#v, want 1", got)
+	}
+
+	assertAllWritesIncludeAllColumns(t, writes)
+}
+
+func TestMapPostgresEventWeatherStoryStructPayload(t *testing.T) {
+	run := model.WeatherStoryRun{
+		OfficeID: "LSX",
+		AsOf:     time.Date(2026, 5, 30, 9, 0, 34, 0, time.UTC),
+		Stories: []model.WeatherStory{
+			{
+				OfficeID:    "LSX",
+				StartTime:   time.Date(2026, 5, 30, 8, 46, 0, 0, time.UTC),
+				EndTime:     time.Date(2026, 5, 31, 11, 0, 0, 0, time.UTC),
+				UpdatedAt:   time.Date(2026, 5, 30, 9, 0, 34, 0, time.UTC),
+				Title:       "Several Chances for Rain Through Monday",
+				Description: "Scattered showers and thunderstorms.",
+				AltText:     "This slide shows the forecast.",
+				Priority:    true,
+				Order:       1,
+				DownloadURL: "https://api.weather.gov/offices/LSX/weatherstories/download/story-1",
+			},
+		},
+	}
+
+	writes, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherStoryV1, "weather_story", run))
+	if err != nil {
+		t.Fatalf("mapPostgresEvent() error = %v", err)
+	}
+	if len(writes) != 2 {
+		t.Fatalf("mapPostgresEvent() writes len = %d, want 2", len(writes))
+	}
+	if writes[0].Table != tableWeatherStoryRuns {
+		t.Fatalf("writes[0].Table = %q, want %q", writes[0].Table, tableWeatherStoryRuns)
+	}
+	if got := writes[0].Values["story_count"]; got != 1 {
+		t.Fatalf("weather_story_runs story_count = %#v, want 1", got)
+	}
+	if writes[1].Table != tableWeatherStories {
+		t.Fatalf("writes[1].Table = %q, want %q", writes[1].Table, tableWeatherStories)
+	}
+	if got := writes[1].Values["download_url"]; got != "https://api.weather.gov/offices/LSX/weatherstories/download/story-1" {
+		t.Fatalf("weather_stories download_url = %#v", got)
+	}
+	if got := writes[1].Values["story_order"]; got != 1 {
+		t.Fatalf("weather_stories story_order = %#v, want 1", got)
+	}
+
+	assertAllWritesIncludeAllColumns(t, writes)
+}
+
+func TestMapPostgresEventWeatherStoryRejectsMissingAsOf(t *testing.T) {
+	_, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherStoryV1, "weather_story", model.WeatherStoryRun{}))
+	if err == nil {
+		t.Fatalf("mapPostgresEvent() error = nil, want missing asOf error")
+	}
+	if !strings.Contains(err.Error(), "asOf is required") {
+		t.Fatalf("error = %q, want asOf context", err)
+	}
+}
+
+func TestMapPostgresEventWeatherStoryRejectsMissingStoryTimes(t *testing.T) {
+	run := model.WeatherStoryRun{
+		AsOf:    time.Date(2026, 5, 30, 9, 0, 34, 0, time.UTC),
+		Stories: []model.WeatherStory{{Title: "missing times"}},
+	}
+	_, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherStoryV1, "weather_story", run))
+	if err == nil {
+		t.Fatalf("mapPostgresEvent() error = nil, want missing story times error")
+	}
+	if !strings.Contains(err.Error(), "stories[0] startTime/endTime/updatedAt are required") {
+		t.Fatalf("error = %q, want story time context", err)
+	}
+}
+
+func TestMapPostgresEventMapPayload(t *testing.T) {
+	run := model.WeatherForecastRun{
+		IssuedAt: time.Date(2026, 3, 16, 18, 0, 0, 0, time.UTC),
+		Product:  model.ForecastProductHourly,
+		Periods: []model.WeatherForecastPeriod{
+			{
+				StartTime:     time.Date(2026, 3, 16, 19, 0, 0, 0, time.UTC),
+				EndTime:       time.Date(2026, 3, 16, 20, 0, 0, 0, time.UTC),
+				ConditionCode: wmoCodePtr(model.WMOCode(2)),
+			},
+		},
+	}
+	b, err := json.Marshal(run)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(b, &payload); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+
+	writes, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherForecastV1, "forecast", payload))
+	if err != nil {
+		t.Fatalf("mapPostgresEvent() error = %v", err)
+	}
+	if len(writes) != 2 {
+		t.Fatalf("mapPostgresEvent() writes len = %d, want 2", len(writes))
+	}
+	if writes[0].Table != tableForecasts {
+		t.Fatalf("writes[0].Table = %q, want %q", writes[0].Table, tableForecasts)
+	}
+
+	assertAllWritesIncludeAllColumns(t, writes)
+}
+
+func TestMapPostgresEventUnknownSchemaNoOp(t *testing.T) {
+	writes, err := mapPostgresEvent(context.Background(), testEvent("weather.unknown.v1", "observation", map[string]any{"x": 1}))
+	if err != nil {
+		t.Fatalf("mapPostgresEvent() error = %v", err)
+	}
+	if len(writes) != 0 {
+		t.Fatalf("mapPostgresEvent() writes len = %d, want 0", len(writes))
+	}
+}
+
+func TestMapPostgresEventMalformedPayload(t *testing.T) {
+	_, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherForecastV1, "forecast", "bad"))
+	if err == nil {
+		t.Fatalf("mapPostgresEvent() expected error for malformed payload")
+	}
+	if !strings.Contains(err.Error(), "decode forecast payload") {
+		t.Fatalf("error = %q, want decode forecast payload context", err)
+	}
+}
+
+func TestMapPostgresEventForecastDiscussionMalformedPayload(t *testing.T) {
+	_, err := mapPostgresEvent(context.Background(), testEvent(standards.SchemaWeatherForecastDiscussionV1, "forecast_discussion", "bad"))
+	if err == nil {
+		t.Fatalf("mapPostgresEvent() expected error for malformed payload")
+	}
+	if !strings.Contains(err.Error(), "decode forecast discussion payload") {
+		t.Fatalf("error = %q, want decode forecast discussion payload context", err)
+	}
+}
+
+func testEvent(schema string, kind fkevent.Kind, payload any) fkevent.Event {
+	effectiveAt := time.Date(2026, 3, 16, 18, 30, 0, 0, time.UTC)
+	return fkevent.Event{
+		ID:          "evt-1",
+		Kind:        kind,
+		Source:      "test-source",
+		Schema:      schema,
+		EmittedAt:   time.Date(2026, 3, 16, 18, 31, 0, 0, time.UTC),
+		EffectiveAt: &effectiveAt,
+		Payload:     payload,
+	}
+}
+
+func firstWriteForTable(writes []fksinks.PostgresWrite, table string) (fksinks.PostgresWrite, bool) {
+	for _, w := range writes {
+		if w.Table == table {
+			return w, true
+		}
+	}
+	return fksinks.PostgresWrite{}, false
+}
+
+func assertAllWritesIncludeAllColumns(t *testing.T, writes []fksinks.PostgresWrite) {
+	t.Helper()
+	colCounts := tableColumnCounts()
+	for i, w := range writes {
+		expectedCount, ok := colCounts[w.Table]
+		if !ok {
+			t.Fatalf("writes[%d] references unknown table %q", i, w.Table)
+		}
+		if len(w.Values) != expectedCount {
+			t.Fatalf("writes[%d] table=%q has %d values, want %d", i, w.Table, len(w.Values), expectedCount)
+		}
+	}
+}
+
+func tableColumnCounts() map[string]int {
+	s := PostgresSchema()
+	m := make(map[string]int, len(s.Tables))
+	for _, tbl := range s.Tables {
+		m[tbl.Name] = len(tbl.Columns)
+	}
+	return m
+}
+
+func wmoCodePtr(v model.WMOCode) *model.WMOCode {
+	out := v
+	return &out
+}

internal/sinks/postgres/schema.go

@@ -0,0 +1,303 @@
+package postgres
+
+import (
+	fksinks "gitea.maximumdirect.net/ejr/feedkit/sinks"
+)
+
+const (
+	tableObservations                  = "observations"
+	tableObservationPresentWeather     = "observation_present_weather"
+	tableForecasts                     = "forecasts"
+	tableForecastPeriods               = "forecast_periods"
+	tableForecastDiscussions           = "forecast_discussions"
+	tableForecastDiscussionKeyMessages = "forecast_discussion_key_messages"
+	tableWeatherStoryRuns              = "weather_story_runs"
+	tableWeatherStories                = "weather_stories"
+	tableAlertRuns                     = "alert_runs"
+	tableAlerts                        = "alerts"
+	tableAlertReferences               = "alert_references"
+)
+
+// PostgresSchema returns weatherfeeder's Postgres schema definition.
+func PostgresSchema() fksinks.PostgresSchema {
+	return fksinks.PostgresSchema{
+		Tables: []fksinks.PostgresTable{
+			{
+				Name: tableObservations,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "event_id", Type: "TEXT", Nullable: false},
+					{Name: "event_kind", Type: "TEXT", Nullable: false},
+					{Name: "event_source", Type: "TEXT", Nullable: false},
+					{Name: "event_schema", Type: "TEXT", Nullable: false},
+					{Name: "event_emitted_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "event_effective_at", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "station_id", Type: "TEXT", Nullable: true},
+					{Name: "station_name", Type: "TEXT", Nullable: true},
+					{Name: "observed_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "condition_code", Type: "INTEGER", Nullable: false},
+					{Name: "is_day", Type: "BOOLEAN", Nullable: true},
+					{Name: "text_description", Type: "TEXT", Nullable: true},
+					{Name: "temperature_c", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "dewpoint_c", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "wind_direction_degrees", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "wind_speed_kmh", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "wind_gust_kmh", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "barometric_pressure_pa", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "visibility_meters", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "relative_humidity_percent", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "apparent_temperature_c", Type: "DOUBLE PRECISION", Nullable: true},
+				},
+				PrimaryKey:  []string{"event_id"},
+				PruneColumn: "observed_at",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_obs_station_observed_at", Columns: []string{"station_id", "observed_at"}},
+					{Name: "idx_wf_obs_observed_at", Columns: []string{"observed_at"}},
+					{Name: "idx_wf_obs_condition_code", Columns: []string{"condition_code"}},
+				},
+			},
+			{
+				Name: tableObservationPresentWeather,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "event_id", Type: "TEXT REFERENCES observations(event_id) ON DELETE CASCADE", Nullable: false},
+					{Name: "weather_index", Type: "INTEGER", Nullable: false},
+					{Name: "observed_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "raw_text", Type: "TEXT", Nullable: true},
+				},
+				PrimaryKey:  []string{"event_id", "weather_index"},
+				PruneColumn: "observed_at",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_obs_present_observed_at", Columns: []string{"observed_at"}},
+				},
+			},
+			{
+				Name: tableForecasts,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "event_id", Type: "TEXT", Nullable: false},
+					{Name: "event_kind", Type: "TEXT", Nullable: false},
+					{Name: "event_source", Type: "TEXT", Nullable: false},
+					{Name: "event_schema", Type: "TEXT", Nullable: false},
+					{Name: "event_emitted_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "event_effective_at", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "location_id", Type: "TEXT", Nullable: true},
+					{Name: "location_name", Type: "TEXT", Nullable: true},
+					{Name: "issued_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "updated_at", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "product", Type: "TEXT", Nullable: false},
+					{Name: "latitude", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "longitude", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "elevation_meters", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "period_count", Type: "INTEGER", Nullable: false},
+				},
+				PrimaryKey:  []string{"event_id"},
+				PruneColumn: "issued_at",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_fc_location_product_issued_at", Columns: []string{"location_id", "product", "issued_at"}},
+					{Name: "idx_wf_fc_issued_at", Columns: []string{"issued_at"}},
+					{Name: "idx_wf_fc_product_issued_at", Columns: []string{"product", "issued_at"}},
+				},
+			},
+			{
+				Name: tableForecastPeriods,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "run_event_id", Type: "TEXT REFERENCES forecasts(event_id) ON DELETE CASCADE", Nullable: false},
+					{Name: "period_index", Type: "INTEGER", Nullable: false},
+					{Name: "issued_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "start_time", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "end_time", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "name", Type: "TEXT", Nullable: true},
+					{Name: "is_day", Type: "BOOLEAN", Nullable: true},
+					{Name: "condition_code", Type: "INTEGER", Nullable: true},
+					{Name: "text_description", Type: "TEXT", Nullable: true},
+					{Name: "temperature_c", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "temperature_c_min", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "temperature_c_max", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "dewpoint_c", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "relative_humidity_percent", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "wind_direction_degrees", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "wind_speed_kmh", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "wind_gust_kmh", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "barometric_pressure_pa", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "visibility_meters", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "apparent_temperature_c", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "cloud_cover_percent", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "probability_of_precipitation_percent", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "precipitation_amount_mm", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "snowfall_depth_mm", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "uv_index", Type: "DOUBLE PRECISION", Nullable: true},
+				},
+				PrimaryKey:  []string{"run_event_id", "period_index"},
+				PruneColumn: "issued_at",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_fc_period_start_time", Columns: []string{"start_time"}},
+					{Name: "idx_wf_fc_period_end_time", Columns: []string{"end_time"}},
+					{Name: "idx_wf_fc_period_run_start", Columns: []string{"run_event_id", "start_time"}},
+				},
+			},
+			{
+				Name: tableForecastDiscussions,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "event_id", Type: "TEXT", Nullable: false},
+					{Name: "event_kind", Type: "TEXT", Nullable: false},
+					{Name: "event_source", Type: "TEXT", Nullable: false},
+					{Name: "event_schema", Type: "TEXT", Nullable: false},
+					{Name: "event_emitted_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "event_effective_at", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "office_id", Type: "TEXT", Nullable: true},
+					{Name: "office_name", Type: "TEXT", Nullable: true},
+					{Name: "issued_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "updated_at", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "product", Type: "TEXT", Nullable: false},
+					{Name: "short_term_qualifier", Type: "TEXT", Nullable: true},
+					{Name: "short_term_issued_at", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "short_term_text", Type: "TEXT", Nullable: true},
+					{Name: "long_term_qualifier", Type: "TEXT", Nullable: true},
+					{Name: "long_term_issued_at", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "long_term_text", Type: "TEXT", Nullable: true},
+					{Name: "key_message_count", Type: "INTEGER", Nullable: false},
+				},
+				PrimaryKey:  []string{"event_id"},
+				PruneColumn: "issued_at",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_discussion_office_product_issued_at", Columns: []string{"office_id", "product", "issued_at"}},
+					{Name: "idx_wf_discussion_issued_at", Columns: []string{"issued_at"}},
+				},
+			},
+			{
+				Name: tableForecastDiscussionKeyMessages,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "run_event_id", Type: "TEXT REFERENCES forecast_discussions(event_id) ON DELETE CASCADE", Nullable: false},
+					{Name: "message_index", Type: "INTEGER", Nullable: false},
+					{Name: "issued_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "message_text", Type: "TEXT", Nullable: true},
+				},
+				PrimaryKey:  []string{"run_event_id", "message_index"},
+				PruneColumn: "issued_at",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_discussion_message_issued_at", Columns: []string{"issued_at"}},
+				},
+			},
+			{
+				Name: tableWeatherStoryRuns,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "event_id", Type: "TEXT", Nullable: false},
+					{Name: "event_kind", Type: "TEXT", Nullable: false},
+					{Name: "event_source", Type: "TEXT", Nullable: false},
+					{Name: "event_schema", Type: "TEXT", Nullable: false},
+					{Name: "event_emitted_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "event_effective_at", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "office_id", Type: "TEXT", Nullable: true},
+					{Name: "as_of", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "story_count", Type: "INTEGER", Nullable: false},
+				},
+				PrimaryKey:  []string{"event_id"},
+				PruneColumn: "as_of",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_story_run_office_as_of", Columns: []string{"office_id", "as_of"}},
+					{Name: "idx_wf_story_run_as_of", Columns: []string{"as_of"}},
+				},
+			},
+			{
+				Name: tableWeatherStories,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "run_event_id", Type: "TEXT REFERENCES weather_story_runs(event_id) ON DELETE CASCADE", Nullable: false},
+					{Name: "story_index", Type: "INTEGER", Nullable: false},
+					{Name: "as_of", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "office_id", Type: "TEXT", Nullable: true},
+					{Name: "start_time", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "end_time", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "updated_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "title", Type: "TEXT", Nullable: true},
+					{Name: "description", Type: "TEXT", Nullable: true},
+					{Name: "alt_text", Type: "TEXT", Nullable: true},
+					{Name: "priority", Type: "BOOLEAN", Nullable: false},
+					{Name: "story_order", Type: "INTEGER", Nullable: false},
+					{Name: "download_url", Type: "TEXT", Nullable: true},
+				},
+				PrimaryKey:  []string{"run_event_id", "story_index"},
+				PruneColumn: "as_of",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_stories_start_time", Columns: []string{"start_time"}},
+					{Name: "idx_wf_stories_end_time", Columns: []string{"end_time"}},
+					{Name: "idx_wf_stories_updated_at", Columns: []string{"updated_at"}},
+				},
+			},
+			{
+				Name: tableAlertRuns,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "event_id", Type: "TEXT", Nullable: false},
+					{Name: "event_kind", Type: "TEXT", Nullable: false},
+					{Name: "event_source", Type: "TEXT", Nullable: false},
+					{Name: "event_schema", Type: "TEXT", Nullable: false},
+					{Name: "event_emitted_at", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "event_effective_at", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "location_id", Type: "TEXT", Nullable: true},
+					{Name: "location_name", Type: "TEXT", Nullable: true},
+					{Name: "as_of", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "latitude", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "longitude", Type: "DOUBLE PRECISION", Nullable: true},
+					{Name: "alert_count", Type: "INTEGER", Nullable: false},
+				},
+				PrimaryKey:  []string{"event_id"},
+				PruneColumn: "as_of",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_alert_run_location_as_of", Columns: []string{"location_id", "as_of"}},
+					{Name: "idx_wf_alert_run_as_of", Columns: []string{"as_of"}},
+				},
+			},
+			{
+				Name: tableAlerts,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "run_event_id", Type: "TEXT REFERENCES alert_runs(event_id) ON DELETE CASCADE", Nullable: false},
+					{Name: "alert_index", Type: "INTEGER", Nullable: false},
+					{Name: "as_of", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "alert_id", Type: "TEXT", Nullable: false},
+					{Name: "event", Type: "TEXT", Nullable: true},
+					{Name: "headline", Type: "TEXT", Nullable: true},
+					{Name: "severity", Type: "TEXT", Nullable: true},
+					{Name: "urgency", Type: "TEXT", Nullable: true},
+					{Name: "certainty", Type: "TEXT", Nullable: true},
+					{Name: "status", Type: "TEXT", Nullable: true},
+					{Name: "message_type", Type: "TEXT", Nullable: true},
+					{Name: "category", Type: "TEXT", Nullable: true},
+					{Name: "response", Type: "TEXT", Nullable: true},
+					{Name: "description", Type: "TEXT", Nullable: true},
+					{Name: "instruction", Type: "TEXT", Nullable: true},
+					{Name: "sent", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "effective", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "onset", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "expires", Type: "TIMESTAMPTZ", Nullable: true},
+					{Name: "area_description", Type: "TEXT", Nullable: true},
+					{Name: "sender_name", Type: "TEXT", Nullable: true},
+					{Name: "reference_count", Type: "INTEGER", Nullable: false},
+				},
+				PrimaryKey:  []string{"run_event_id", "alert_index"},
+				PruneColumn: "as_of",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_alerts_alert_id", Columns: []string{"alert_id"}},
+					{Name: "idx_wf_alerts_severity_expires", Columns: []string{"severity", "expires"}},
+					{Name: "idx_wf_alerts_as_of", Columns: []string{"as_of"}},
+				},
+			},
+			{
+				Name: tableAlertReferences,
+				Columns: []fksinks.PostgresColumn{
+					{Name: "run_event_id", Type: "TEXT REFERENCES alert_runs(event_id) ON DELETE CASCADE", Nullable: false},
+					{Name: "alert_index", Type: "INTEGER", Nullable: false},
+					{Name: "reference_index", Type: "INTEGER", Nullable: false},
+					{Name: "as_of", Type: "TIMESTAMPTZ", Nullable: false},
+					{Name: "id", Type: "TEXT", Nullable: true},
+					{Name: "identifier", Type: "TEXT", Nullable: true},
+					{Name: "sender", Type: "TEXT", Nullable: true},
+					{Name: "sent", Type: "TIMESTAMPTZ", Nullable: true},
+				},
+				PrimaryKey:  []string{"run_event_id", "alert_index", "reference_index"},
+				PruneColumn: "as_of",
+				Indexes: []fksinks.PostgresIndex{
+					{Name: "idx_wf_alert_refs_as_of", Columns: []string{"as_of"}},
+					{Name: "idx_wf_alert_refs_sent", Columns: []string{"sent"}},
+				},
+			},
+		},
+		MapEvent: mapPostgresEvent,
+	}
+}

internal/sinks/postgres/schema_test.go

@@ -0,0 +1,79 @@
+package postgres
+
+import "testing"
+
+func TestWeatherPostgresSchemaShape(t *testing.T) {
+	s := PostgresSchema()
+	if s.MapEvent == nil {
+		t.Fatalf("PostgresSchema().MapEvent is nil")
+	}
+
+	wantTables := map[string]bool{
+		tableObservations:                  true,
+		tableObservationPresentWeather:     true,
+		tableForecasts:                     true,
+		tableForecastPeriods:               true,
+		tableForecastDiscussions:           true,
+		tableForecastDiscussionKeyMessages: true,
+		tableWeatherStoryRuns:              true,
+		tableWeatherStories:                true,
+		tableAlertRuns:                     true,
+		tableAlerts:                        true,
+		tableAlertReferences:               true,
+	}
+
+	if len(s.Tables) != len(wantTables) {
+		t.Fatalf("PostgresSchema().Tables len = %d, want %d", len(s.Tables), len(wantTables))
+	}
+
+	seenIndexes := map[string]bool{}
+	for _, tbl := range s.Tables {
+		if !wantTables[tbl.Name] {
+			t.Fatalf("unexpected table %q in schema", tbl.Name)
+		}
+		if tbl.PruneColumn == "" {
+			t.Fatalf("table %q missing prune column", tbl.Name)
+		}
+		for _, idx := range tbl.Indexes {
+			if seenIndexes[idx.Name] {
+				t.Fatalf("duplicate index name %q", idx.Name)
+			}
+			seenIndexes[idx.Name] = true
+		}
+	}
+}
+
+func TestWeatherPostgresSchemaIncludesWeatherStoryColumns(t *testing.T) {
+	runColumns := columnsForTable(t, tableWeatherStoryRuns)
+	if !runColumns["as_of"] {
+		t.Fatalf("%s missing as_of column", tableWeatherStoryRuns)
+	}
+	if !runColumns["story_count"] {
+		t.Fatalf("%s missing story_count column", tableWeatherStoryRuns)
+	}
+
+	storyColumns := columnsForTable(t, tableWeatherStories)
+	for _, col := range []string{"start_time", "end_time", "updated_at", "title", "description", "alt_text", "priority", "story_order", "download_url"} {
+		if !storyColumns[col] {
+			t.Fatalf("%s missing %s column", tableWeatherStories, col)
+		}
+	}
+}
+
+func columnsForTable(t *testing.T, table string) map[string]bool {
+	t.Helper()
+
+	schema := PostgresSchema()
+	for _, tbl := range schema.Tables {
+		if tbl.Name != table {
+			continue
+		}
+		cols := make(map[string]bool, len(tbl.Columns))
+		for _, col := range tbl.Columns {
+			cols[col.Name] = true
+		}
+		return cols
+	}
+	t.Fatalf("missing table %q", table)
+	return nil
+}

internal/sources/builtins.go

@@ -9,30 +9,34 @@ import (
 	fksource "gitea.maximumdirect.net/ejr/feedkit/sources"
 )
 
+type pollDriverRegistration struct {
+	driver  string
+	factory func(config.SourceConfig) (fksource.PollSource, error)
+}
+
+var pollDriverRegistrations = []pollDriverRegistration{
+	{driver: "nws_observation", factory: func(cfg config.SourceConfig) (fksource.PollSource, error) { return nws.NewObservationSource(cfg) }},
+	{driver: "nws_alerts", factory: func(cfg config.SourceConfig) (fksource.PollSource, error) { return nws.NewAlertsSource(cfg) }},
+	{driver: "nws_forecast_hourly", factory: func(cfg config.SourceConfig) (fksource.PollSource, error) { return nws.NewHourlyForecastSource(cfg) }},
+	{driver: "nws_forecast_narrative", factory: func(cfg config.SourceConfig) (fksource.PollSource, error) { return nws.NewNarrativeForecastSource(cfg) }},
+	{driver: "nws_forecast_discussion", factory: func(cfg config.SourceConfig) (fksource.PollSource, error) {
+		return nws.NewForecastDiscussionSource(cfg)
+	}},
+	{driver: "nws_weatherstories", factory: func(cfg config.SourceConfig) (fksource.PollSource, error) { return nws.NewWeatherStoriesSource(cfg) }},
+	{driver: "openmeteo_observation", factory: func(cfg config.SourceConfig) (fksource.PollSource, error) { return openmeteo.NewObservationSource(cfg) }},
+	{driver: "openmeteo_forecast", factory: func(cfg config.SourceConfig) (fksource.PollSource, error) { return openmeteo.NewForecastSource(cfg) }},
+	{driver: "openweather_observation", factory: func(cfg config.SourceConfig) (fksource.PollSource, error) {
+		return openweather.NewObservationSource(cfg)
+	}},
+}
+
 // RegisterBuiltins registers the source drivers that ship with this binary.
 // Keeping this in one place makes main.go very readable.
 func RegisterBuiltins(r *fksource.Registry) {
-	// NWS drivers
+	for _, reg := range pollDriverRegistrations {
-	r.Register("nws_observation", func(cfg config.SourceConfig) (fksource.Source, error) {
+		reg := reg
-		return nws.NewObservationSource(cfg)
+		r.RegisterPoll(reg.driver, func(cfg config.SourceConfig) (fksource.PollSource, error) {
-	})
+			return reg.factory(cfg)
-	r.Register("nws_alerts", func(cfg config.SourceConfig) (fksource.Source, error) {
-		return nws.NewAlertsSource(cfg)
-	})
-	r.Register("nws_forecast", func(cfg config.SourceConfig) (fksource.Source, error) {
-		return nws.NewForecastSource(cfg)
-	})
-
-	// Open-Meteo drivers
-	r.Register("openmeteo_observation", func(cfg config.SourceConfig) (fksource.Source, error) {
-		return openmeteo.NewObservationSource(cfg)
-	})
-	r.Register("openmeteo_forecast", func(cfg config.SourceConfig) (fksource.Source, error) {
-		return openmeteo.NewForecastSource(cfg)
-	})
-
-	// OpenWeatherMap drivers
-	r.Register("openweather_observation", func(cfg config.SourceConfig) (fksource.Source, error) {
-		return openweather.NewObservationSource(cfg)
 		})
+	}
 }

internal/sources/builtins_test.go

@@ -0,0 +1,117 @@
+package sources
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	fksource "gitea.maximumdirect.net/ejr/feedkit/sources"
+)
+
+func TestRegisterBuiltinsRegistersNWSHourlyForecastDriver(t *testing.T) {
+	reg := fksource.NewRegistry()
+	RegisterBuiltins(reg)
+
+	in, err := reg.BuildInput(sourceConfigForDriver("nws_forecast_hourly"))
+	if err != nil {
+		t.Fatalf("BuildInput(nws_forecast_hourly) error = %v", err)
+	}
+	if _, ok := in.(fksource.PollSource); !ok {
+		t.Fatalf("BuildInput(nws_forecast_hourly) type = %T, want PollSource", in)
+	}
+}
+
+func TestRegisterBuiltinsRegistersNWSNarrativeForecastDriver(t *testing.T) {
+	reg := fksource.NewRegistry()
+	RegisterBuiltins(reg)
+
+	in, err := reg.BuildInput(sourceConfigForDriver("nws_forecast_narrative"))
+	if err != nil {
+		t.Fatalf("BuildInput(nws_forecast_narrative) error = %v", err)
+	}
+	if _, ok := in.(fksource.PollSource); !ok {
+		t.Fatalf("BuildInput(nws_forecast_narrative) type = %T, want PollSource", in)
+	}
+}
+
+func TestRegisterBuiltinsRegistersNWSForecastDiscussionDriver(t *testing.T) {
+	reg := fksource.NewRegistry()
+	RegisterBuiltins(reg)
+
+	in, err := reg.BuildInput(sourceConfigForDriver("nws_forecast_discussion"))
+	if err != nil {
+		t.Fatalf("BuildInput(nws_forecast_discussion) error = %v", err)
+	}
+	if _, ok := in.(fksource.PollSource); !ok {
+		t.Fatalf("BuildInput(nws_forecast_discussion) type = %T, want PollSource", in)
+	}
+}
+
+func TestRegisterBuiltinsRegistersNWSWeatherStoriesDriver(t *testing.T) {
+	reg := fksource.NewRegistry()
+	RegisterBuiltins(reg)
+
+	in, err := reg.BuildInput(sourceConfigForDriver("nws_weatherstories"))
+	if err != nil {
+		t.Fatalf("BuildInput(nws_weatherstories) error = %v", err)
+	}
+	if _, ok := in.(fksource.PollSource); !ok {
+		t.Fatalf("BuildInput(nws_weatherstories) type = %T, want PollSource", in)
+	}
+}
+
+func TestRegisterBuiltinsDoesNotRegisterLegacyNWSForecastDriver(t *testing.T) {
+	reg := fksource.NewRegistry()
+	RegisterBuiltins(reg)
+
+	_, err := reg.BuildInput(sourceConfigForDriver("nws_forecast"))
+	if err == nil {
+		t.Fatalf("BuildInput(nws_forecast) expected unknown driver error")
+	}
+	if !strings.Contains(err.Error(), `unknown source driver: "nws_forecast"`) {
+		t.Fatalf("error = %q, want unknown source driver for nws_forecast", err)
+	}
+}
+
+func TestRegisterBuiltinsRegistersAllCurrentDrivers(t *testing.T) {
+	reg := fksource.NewRegistry()
+	RegisterBuiltins(reg)
+
+	drivers := []string{
+		"nws_observation",
+		"nws_alerts",
+		"nws_forecast_hourly",
+		"nws_forecast_narrative",
+		"nws_forecast_discussion",
+		"nws_weatherstories",
+		"openmeteo_observation",
+		"openmeteo_forecast",
+		"openweather_observation",
+	}
+
+	for _, driver := range drivers {
+		in, err := reg.BuildInput(sourceConfigForDriver(driver))
+		if err != nil {
+			t.Fatalf("BuildInput(%s) error = %v", driver, err)
+		}
+		if _, ok := in.(fksource.PollSource); !ok {
+			t.Fatalf("BuildInput(%s) type = %T, want PollSource", driver, in)
+		}
+	}
+}
+
+func sourceConfigForDriver(driver string) config.SourceConfig {
+	url := "https://example.invalid"
+	if driver == "openweather_observation" {
+		url = "https://example.invalid?units=metric"
+	}
+	return config.SourceConfig{
+		Name:   "test-source",
+		Driver: driver,
+		Mode:   config.SourceModePoll,
+		Params: map[string]any{
+			"url":        url,
+			"user_agent": "test-agent",
+		},
+	}
+}

internal/sources/common/config.go

@@ -1,104 +0,0 @@
-// FILE: ./internal/sources/common/config.go
-package common
-
-import (
-	"fmt"
-	"strings"
-
-	"gitea.maximumdirect.net/ejr/feedkit/config"
-)
-
-// This file centralizes small, boring config-validation patterns shared across
-// weatherfeeder source drivers.
-//
-// Goal: keep driver constructors (New*Source) easy to read and consistent, while
-// keeping driver-specific options in cfg.Params (feedkit remains domain-agnostic).
-
-// HTTPSourceConfig is the standard "HTTP-polling source" config shape used across drivers.
-type HTTPSourceConfig struct {
-	Name      string
-	URL       string
-	UserAgent string
-}
-
-// RequireHTTPSourceConfig enforces weatherfeeder's standard HTTP source config:
-//
-//   - cfg.Name must be present
-//   - cfg.Params must be present
-//   - params.url must be present (accepts "url" or "URL")
-//   - params.user_agent must be present (accepts "user_agent" or "userAgent")
-//
-// We intentionally require a User-Agent for *all* sources, even when upstreams
-// do not strictly require one. This keeps config uniform across providers.
-func RequireHTTPSourceConfig(driver string, cfg config.SourceConfig) (HTTPSourceConfig, error) {
-	if strings.TrimSpace(cfg.Name) == "" {
-		return HTTPSourceConfig{}, fmt.Errorf("%s: name is required", driver)
-	}
-	if cfg.Params == nil {
-		return HTTPSourceConfig{}, fmt.Errorf("%s %q: params are required (need params.url and params.user_agent)", driver, cfg.Name)
-	}
-
-	url, ok := cfg.ParamString("url", "URL")
-	if !ok {
-		return HTTPSourceConfig{}, fmt.Errorf("%s %q: params.url is required", driver, cfg.Name)
-	}
-
-	ua, ok := cfg.ParamString("user_agent", "userAgent")
-	if !ok {
-		return HTTPSourceConfig{}, fmt.Errorf("%s %q: params.user_agent is required", driver, cfg.Name)
-	}
-
-	return HTTPSourceConfig{
-		Name:      cfg.Name,
-		URL:       url,
-		UserAgent: ua,
-	}, nil
-}
-
-// --- The helpers below remain useful for future drivers; they are not required
-// --- by the observation sources after adopting RequireHTTPSourceConfig.
-
-// RequireName ensures cfg.Name is present and non-whitespace.
-func RequireName(driver string, cfg config.SourceConfig) error {
-	if strings.TrimSpace(cfg.Name) == "" {
-		return fmt.Errorf("%s: name is required", driver)
-	}
-	return nil
-}
-
-// RequireParams ensures cfg.Params is non-nil. The "want" string should be a short
-// description of required keys, e.g. "need params.url and params.user_agent".
-func RequireParams(driver string, cfg config.SourceConfig, want string) error {
-	if cfg.Params == nil {
-		return fmt.Errorf("%s %q: params are required (%s)", driver, cfg.Name, want)
-	}
-	return nil
-}
-
-// RequireURL returns the configured URL for a source.
-// Canonical key is "url"; we also accept "URL" as a convenience.
-func RequireURL(driver string, cfg config.SourceConfig) (string, error) {
-	if cfg.Params == nil {
-		return "", fmt.Errorf("%s %q: params are required (need params.url)", driver, cfg.Name)
-	}
-
-	u, ok := cfg.ParamString("url", "URL")
-	if !ok {
-		return "", fmt.Errorf("%s %q: params.url is required", driver, cfg.Name)
-	}
-	return u, nil
-}
-
-// RequireUserAgent returns the configured User-Agent for a source.
-// Canonical key is "user_agent"; we also accept "userAgent" as a convenience.
-func RequireUserAgent(driver string, cfg config.SourceConfig) (string, error) {
-	if cfg.Params == nil {
-		return "", fmt.Errorf("%s %q: params are required (need params.user_agent)", driver, cfg.Name)
-	}
-
-	ua, ok := cfg.ParamString("user_agent", "userAgent")
-	if !ok {
-		return "", fmt.Errorf("%s %q: params.user_agent is required", driver, cfg.Name)
-	}
-	return ua, nil
-}

internal/sources/common/event.go

@@ -1,54 +0,0 @@
-// FILE: ./internal/sources/common/event.go
-package common
-
-import (
-	"time"
-
-	"gitea.maximumdirect.net/ejr/feedkit/event"
-)
-
-// SingleRawEvent constructs, validates, and returns a slice containing exactly one event.
-//
-// This removes repetitive "event envelope ceremony" from individual sources.
-// Sources remain responsible for:
-//   - fetching bytes (raw payload)
-//   - choosing Schema (raw schema identifier)
-//   - computing Event.ID and (optional) EffectiveAt
-//
-// emittedAt is explicit so callers can compute IDs using the same timestamp (or
-// so tests can provide a stable value).
-func SingleRawEvent(
-	kind event.Kind,
-	sourceName string,
-	schema string,
-	id string,
-	emittedAt time.Time,
-	effectiveAt *time.Time,
-	payload any,
-) ([]event.Event, error) {
-	if emittedAt.IsZero() {
-		emittedAt = time.Now().UTC()
-	} else {
-		emittedAt = emittedAt.UTC()
-	}
-
-	e := event.Event{
-		ID:          id,
-		Kind:        kind,
-		Source:      sourceName,
-		EmittedAt:   emittedAt,
-		EffectiveAt: effectiveAt,
-
-		// RAW schema (normalizer matches on this).
-		Schema: schema,
-
-		// Raw payload (usually json.RawMessage). Normalizer will decode and map to canonical model.
-		Payload: payload,
-	}
-
-	if err := e.Validate(); err != nil {
-		return nil, err
-	}
-
-	return []event.Event{e}, nil
-}

internal/sources/common/http.go

@@ -1,76 +0,0 @@
-// FILE: ./internal/sources/common/http_source.go
-package common
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"net/http"
-
-	"gitea.maximumdirect.net/ejr/feedkit/config"
-	"gitea.maximumdirect.net/ejr/feedkit/transport"
-)
-
-// HTTPSource is a tiny, reusable "HTTP polling spine" for weatherfeeder sources.
-//
-// It centralizes the boring parts:
-//   - standard config shape (url + user_agent) via RequireHTTPSourceConfig
-//   - a default http.Client with timeout
-//   - FetchBody / headers / max-body safety limit
-//   - consistent error wrapping (driver + source name)
-//
-// Individual drivers remain responsible for:
-//   - decoding minimal metadata (for Event.ID / EffectiveAt)
-//   - constructing the event envelope (kind/schema/payload)
-type HTTPSource struct {
-	Driver    string
-	Name      string
-	URL       string
-	UserAgent string
-	Accept    string
-	Client    *http.Client
-}
-
-// NewHTTPSource builds an HTTPSource using weatherfeeder's standard HTTP source
-// config (params.url + params.user_agent) and a default HTTP client.
-func NewHTTPSource(driver string, cfg config.SourceConfig, accept string) (*HTTPSource, error) {
-	c, err := RequireHTTPSourceConfig(driver, cfg)
-	if err != nil {
-		return nil, err
-	}
-
-	return &HTTPSource{
-		Driver:    driver,
-		Name:      c.Name,
-		URL:       c.URL,
-		UserAgent: c.UserAgent,
-		Accept:    accept,
-		Client:    transport.NewHTTPClient(transport.DefaultHTTPTimeout),
-	}, nil
-}
-
-// FetchBytes fetches the URL and returns the raw response body bytes.
-func (s *HTTPSource) FetchBytes(ctx context.Context) ([]byte, error) {
-	client := s.Client
-	if client == nil {
-		// Defensive: allow tests or callers to nil out Client; keep behavior sane.
-		client = transport.NewHTTPClient(transport.DefaultHTTPTimeout)
-	}
-
-	b, err := transport.FetchBody(ctx, client, s.URL, s.UserAgent, s.Accept)
-	if err != nil {
-		return nil, fmt.Errorf("%s %q: %w", s.Driver, s.Name, err)
-	}
-	return b, nil
-}
-
-// FetchJSON fetches the URL and returns the raw body as json.RawMessage.
-// json.Unmarshal accepts json.RawMessage directly, so callers can decode minimal
-// metadata without keeping both []byte and RawMessage in their own structs.
-func (s *HTTPSource) FetchJSON(ctx context.Context) (json.RawMessage, error) {
-	b, err := s.FetchBytes(ctx)
-	if err != nil {
-		return nil, err
-	}
-	return json.RawMessage(b), nil
-}

internal/sources/common/id.go

@@ -1,39 +0,0 @@
-// FILE: ./internal/sources/common/id.go
-package common
-
-import (
-	"fmt"
-	"strings"
-	"time"
-)
-
-// ChooseEventID applies weatherfeeder's opinionated Event.ID policy:
-//
-//   - If upstream provides an ID, use it (trimmed).
-//   - Otherwise, ID is "<Source>:<EffectiveAt>" when available.
-//   - If EffectiveAt is unavailable, fall back to "<Source>:<EmittedAt>".
-//
-// Timestamps are encoded as RFC3339Nano in UTC.
-func ChooseEventID(upstreamID, sourceName string, effectiveAt *time.Time, emittedAt time.Time) string {
-	if id := strings.TrimSpace(upstreamID); id != "" {
-		return id
-	}
-
-	src := strings.TrimSpace(sourceName)
-	if src == "" {
-		src = "UNKNOWN_SOURCE"
-	}
-
-	// Prefer EffectiveAt for dedupe friendliness.
-	if effectiveAt != nil && !effectiveAt.IsZero() {
-		return fmt.Sprintf("%s:%s", src, effectiveAt.UTC().Format(time.RFC3339Nano))
-	}
-
-	// Fall back to EmittedAt (still stable within a poll invocation).
-	t := emittedAt.UTC()
-	if t.IsZero() {
-		t = time.Now().UTC()
-	}
-
-	return fmt.Sprintf("%s:%s", src, t.Format(time.RFC3339Nano))
-}

internal/sources/nws/alerts.go

@@ -9,9 +9,9 @@ import (
 
 	"gitea.maximumdirect.net/ejr/feedkit/config"
 	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
 	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/sources/common"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 )
 
 // AlertsSource polls an NWS alerts endpoint and emits a RAW alerts Event.
@@ -22,14 +22,14 @@ import (
 // Output schema:
 //   - standards.SchemaRawNWSAlertsV1
 type AlertsSource struct {
-	http *common.HTTPSource
+	http *fksources.HTTPSource
 }
 
 func NewAlertsSource(cfg config.SourceConfig) (*AlertsSource, error) {
 	const driver = "nws_alerts"
 
 	// NWS alerts responses are GeoJSON-ish; allow fallback to plain JSON as well.
-	hs, err := common.NewHTTPSource(driver, cfg, "application/geo+json, application/json")
+	hs, err := fksources.NewHTTPSource(driver, cfg, "application/geo+json, application/json")
 	if err != nil {
 		return nil, err
 	}
@@ -39,14 +39,17 @@ func NewAlertsSource(cfg config.SourceConfig) (*AlertsSource, error) {
 
 func (s *AlertsSource) Name() string { return s.http.Name }
 
-// Kind is used for routing/policy.
+// Kinds is used for routing/policy.
-func (s *AlertsSource) Kind() event.Kind { return event.Kind("alert") }
+func (s *AlertsSource) Kinds() []event.Kind { return []event.Kind{event.Kind("alert")} }
 
 func (s *AlertsSource) Poll(ctx context.Context) ([]event.Event, error) {
-	raw, meta, err := s.fetchRaw(ctx)
+	raw, meta, changed, err := s.fetchRaw(ctx)
 	if err != nil {
 		return nil, err
 	}
+	if !changed {
+		return nil, nil
+	}
 
 	// EffectiveAt policy for alerts:
 	// Prefer the collection-level "updated" timestamp (best dedupe signal).
@@ -65,10 +68,10 @@ func (s *AlertsSource) Poll(ctx context.Context) ([]event.Event, error) {
 
 	// NWS alerts collections do not provide a stable per-snapshot ID.
 	// Use Source:EffectiveAt (or Source:EmittedAt fallback) for dedupe friendliness.
-	eventID := common.ChooseEventID("", s.http.Name, effectiveAt, emittedAt)
+	eventID := fksources.DefaultEventID("", s.http.Name, effectiveAt, emittedAt)
 
-	return common.SingleRawEvent(
+	return fksources.SingleEvent(
-		s.Kind(),
+		event.Kind("alert"),
 		s.http.Name,
 		standards.SchemaRawNWSAlertsV1,
 		eventID,
@@ -97,16 +100,19 @@ type alertsMeta struct {
 	ParsedLatestFeatureTime time.Time `json:"-"`
 }
 
-func (s *AlertsSource) fetchRaw(ctx context.Context) (json.RawMessage, alertsMeta, error) {
+func (s *AlertsSource) fetchRaw(ctx context.Context) (json.RawMessage, alertsMeta, bool, error) {
-	raw, err := s.http.FetchJSON(ctx)
+	raw, changed, err := s.http.FetchJSONIfChanged(ctx)
 	if err != nil {
-		return nil, alertsMeta{}, err
+		return nil, alertsMeta{}, false, err
+	}
+	if !changed {
+		return nil, alertsMeta{}, false, nil
 	}
 
 	var meta alertsMeta
 	if err := json.Unmarshal(raw, &meta); err != nil {
 		// If metadata decode fails, still return raw; Poll will fall back to Source:EmittedAt.
-		return raw, alertsMeta{}, nil
+		return raw, alertsMeta{}, true, nil
 	}
 
 	// Top-level updated (preferred).
@@ -143,5 +149,5 @@ func (s *AlertsSource) fetchRaw(ctx context.Context) (json.RawMessage, alertsMet
 	}
 	meta.ParsedLatestFeatureTime = latest
 
-	return raw, meta, nil
+	return raw, meta, true, nil
 }

internal/sources/nws/forecast.go

@@ -1,129 +0,0 @@
-// FILE: internal/sources/nws/forecast.go
-package nws
-
-import (
-	"context"
-	"encoding/json"
-	"strings"
-	"time"
-
-	"gitea.maximumdirect.net/ejr/feedkit/config"
-	"gitea.maximumdirect.net/ejr/feedkit/event"
-	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/sources/common"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
-)
-
-// ForecastSource polls an NWS forecast endpoint (narrative or hourly) and emits a RAW forecast Event.
-//
-// It intentionally emits the *entire* upstream payload as json.RawMessage and only decodes
-// minimal metadata for Event.EffectiveAt and Event.ID.
-//
-// Output schema (current implementation):
-//   - standards.SchemaRawNWSHourlyForecastV1
-type ForecastSource struct {
-	http *common.HTTPSource
-}
-
-func NewForecastSource(cfg config.SourceConfig) (*ForecastSource, error) {
-	const driver = "nws_forecast"
-
-	// NWS forecast endpoints are GeoJSON (and sometimes also advertise json-ld/json).
-	hs, err := common.NewHTTPSource(driver, cfg, "application/geo+json, application/json")
-	if err != nil {
-		return nil, err
-	}
-
-	return &ForecastSource{http: hs}, nil
-}
-
-func (s *ForecastSource) Name() string { return s.http.Name }
-
-// Kind is used for routing/policy.
-func (s *ForecastSource) Kind() event.Kind { return event.Kind("forecast") }
-
-func (s *ForecastSource) Poll(ctx context.Context) ([]event.Event, error) {
-	raw, meta, err := s.fetchRaw(ctx)
-	if err != nil {
-		return nil, err
-	}
-
-	// EffectiveAt is optional; for forecasts it’s most naturally the run “issued” time.
-	// NWS gridpoint forecasts expose generatedAt (preferred) and updateTime/updated.
-	var effectiveAt *time.Time
-	switch {
-	case !meta.ParsedGeneratedAt.IsZero():
-		t := meta.ParsedGeneratedAt.UTC()
-		effectiveAt = &t
-	case !meta.ParsedUpdateTime.IsZero():
-		t := meta.ParsedUpdateTime.UTC()
-		effectiveAt = &t
-	}
-
-	emittedAt := time.Now().UTC()
-
-	// NWS gridpoint forecast GeoJSON commonly has a stable "id" equal to the endpoint URL.
-	// That is *not* unique per issued run, so we intentionally do not use it for Event.ID.
-	// Instead we rely on Source:EffectiveAt (or Source:EmittedAt fallback).
-	eventID := common.ChooseEventID("", s.http.Name, effectiveAt, emittedAt)
-
-	return common.SingleRawEvent(
-		s.Kind(),
-		s.http.Name,
-		standards.SchemaRawNWSHourlyForecastV1,
-		eventID,
-		emittedAt,
-		effectiveAt,
-		raw,
-	)
-}
-
-// ---- RAW fetch + minimal metadata decode ----
-
-type forecastMeta struct {
-	// Present for GeoJSON Feature responses, but often stable (endpoint URL).
-	ID string `json:"id"`
-
-	Properties struct {
-		GeneratedAt string `json:"generatedAt"` // preferred “issued/run generated” time
-		UpdateTime  string `json:"updateTime"`  // last update time of underlying data
-		Updated     string `json:"updated"`     // deprecated alias for updateTime
-	} `json:"properties"`
-
-	ParsedGeneratedAt time.Time `json:"-"`
-	ParsedUpdateTime  time.Time `json:"-"`
-}
-
-func (s *ForecastSource) fetchRaw(ctx context.Context) (json.RawMessage, forecastMeta, error) {
-	raw, err := s.http.FetchJSON(ctx)
-	if err != nil {
-		return nil, forecastMeta{}, err
-	}
-
-	var meta forecastMeta
-	if err := json.Unmarshal(raw, &meta); err != nil {
-		// If metadata decode fails, still return raw; Poll will fall back to Source:EmittedAt.
-		return raw, forecastMeta{}, nil
-	}
-
-	// generatedAt (preferred)
-	genStr := strings.TrimSpace(meta.Properties.GeneratedAt)
-	if genStr != "" {
-		if t, err := nwscommon.ParseTime(genStr); err == nil {
-			meta.ParsedGeneratedAt = t.UTC()
-		}
-	}
-
-	// updateTime, with fallback to deprecated "updated"
-	updStr := strings.TrimSpace(meta.Properties.UpdateTime)
-	if updStr == "" {
-		updStr = strings.TrimSpace(meta.Properties.Updated)
-	}
-	if updStr != "" {
-		if t, err := nwscommon.ParseTime(updStr); err == nil {
-			meta.ParsedUpdateTime = t.UTC()
-		}
-	}
-
-	return raw, meta, nil
-}

internal/sources/nws/forecast_common.go

@@ -0,0 +1,114 @@
+package nws
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
+	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
+)
+
+const nwsForecastAccept = "application/geo+json, application/json"
+
+type forecastSource struct {
+	http      *fksources.HTTPSource
+	rawSchema string
+}
+
+type forecastMeta struct {
+	Properties struct {
+		GeneratedAt string `json:"generatedAt"`
+		UpdateTime  string `json:"updateTime"`
+		Updated     string `json:"updated"`
+	} `json:"properties"`
+
+	ParsedGeneratedAt time.Time `json:"-"`
+	ParsedUpdateTime  time.Time `json:"-"`
+}
+
+func newForecastSource(cfg config.SourceConfig, driver, rawSchema string) (*forecastSource, error) {
+	hs, err := fksources.NewHTTPSource(driver, cfg, nwsForecastAccept)
+	if err != nil {
+		return nil, err
+	}
+
+	return &forecastSource{
+		http:      hs,
+		rawSchema: rawSchema,
+	}, nil
+}
+
+func (s *forecastSource) Name() string { return s.http.Name }
+
+func (s *forecastSource) Kinds() []event.Kind { return []event.Kind{event.Kind("forecast")} }
+
+func (s *forecastSource) Poll(ctx context.Context) ([]event.Event, error) {
+	raw, meta, changed, err := s.fetchRaw(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if !changed {
+		return nil, nil
+	}
+
+	var effectiveAt *time.Time
+	switch {
+	case !meta.ParsedGeneratedAt.IsZero():
+		t := meta.ParsedGeneratedAt.UTC()
+		effectiveAt = &t
+	case !meta.ParsedUpdateTime.IsZero():
+		t := meta.ParsedUpdateTime.UTC()
+		effectiveAt = &t
+	}
+
+	emittedAt := time.Now().UTC()
+	eventID := fksources.DefaultEventID("", s.http.Name, effectiveAt, emittedAt)
+
+	return fksources.SingleEvent(
+		event.Kind("forecast"),
+		s.http.Name,
+		s.rawSchema,
+		eventID,
+		emittedAt,
+		effectiveAt,
+		raw,
+	)
+}
+
+func (s *forecastSource) fetchRaw(ctx context.Context) (json.RawMessage, forecastMeta, bool, error) {
+	raw, changed, err := s.http.FetchJSONIfChanged(ctx)
+	if err != nil {
+		return nil, forecastMeta{}, false, err
+	}
+	if !changed {
+		return nil, forecastMeta{}, false, nil
+	}
+
+	var meta forecastMeta
+	if err := json.Unmarshal(raw, &meta); err != nil {
+		return raw, forecastMeta{}, true, nil
+	}
+
+	genStr := strings.TrimSpace(meta.Properties.GeneratedAt)
+	if genStr != "" {
+		if t, err := nwscommon.ParseTime(genStr); err == nil {
+			meta.ParsedGeneratedAt = t.UTC()
+		}
+	}
+
+	updStr := strings.TrimSpace(meta.Properties.UpdateTime)
+	if updStr == "" {
+		updStr = strings.TrimSpace(meta.Properties.Updated)
+	}
+	if updStr != "" {
+		if t, err := nwscommon.ParseTime(updStr); err == nil {
+			meta.ParsedUpdateTime = t.UTC()
+		}
+	}
+
+	return raw, meta, true, nil
+}

internal/sources/nws/forecast_discussion.go

@@ -0,0 +1,68 @@
+package nws
+
+import (
+	"context"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
+	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+// ForecastDiscussionSource polls an NWS forecast discussion HTML page and emits a RAW discussion Event.
+//
+// Output schema:
+//   - standards.SchemaRawNWSForecastDiscussionV1
+type ForecastDiscussionSource struct {
+	http *fksources.HTTPSource
+}
+
+func NewForecastDiscussionSource(cfg config.SourceConfig) (*ForecastDiscussionSource, error) {
+	const driver = "nws_forecast_discussion"
+
+	hs, err := fksources.NewHTTPSource(driver, cfg, "text/html, application/xhtml+xml")
+	if err != nil {
+		return nil, err
+	}
+
+	return &ForecastDiscussionSource{http: hs}, nil
+}
+
+func (s *ForecastDiscussionSource) Name() string { return s.http.Name }
+
+func (s *ForecastDiscussionSource) Kinds() []event.Kind {
+	return []event.Kind{event.Kind("forecast_discussion")}
+}
+
+func (s *ForecastDiscussionSource) Poll(ctx context.Context) ([]event.Event, error) {
+	body, changed, err := s.http.FetchBytesIfChanged(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if !changed {
+		return nil, nil
+	}
+
+	rawHTML := string(body)
+	parsed, err := nwscommon.ParseForecastDiscussionHTML(rawHTML)
+	if err != nil {
+		return nil, err
+	}
+
+	issuedAt := parsed.IssuedAt.UTC()
+	effectiveAt := &issuedAt
+	emittedAt := time.Now().UTC()
+	eventID := fksources.DefaultEventID("", s.http.Name, effectiveAt, emittedAt)
+
+	return fksources.SingleEvent(
+		event.Kind("forecast_discussion"),
+		s.http.Name,
+		standards.SchemaRawNWSForecastDiscussionV1,
+		eventID,
+		emittedAt,
+		effectiveAt,
+		rawHTML,
+	)
+}

internal/sources/nws/forecast_discussion_test.go

@@ -0,0 +1,138 @@
+package nws
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+func TestForecastDiscussionSourcePollEmitsExpectedEvent(t *testing.T) {
+	rawHTML := loadForecastDiscussionSampleHTML(t)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = w.Write([]byte(rawHTML))
+	}))
+	defer srv.Close()
+
+	src, err := NewForecastDiscussionSource(forecastDiscussionSourceConfig(srv.URL))
+	if err != nil {
+		t.Fatalf("NewForecastDiscussionSource() error = %v", err)
+	}
+	if got := src.Kinds(); len(got) != 1 || got[0] != event.Kind("forecast_discussion") {
+		t.Fatalf("Kinds() = %#v, want [forecast_discussion]", got)
+	}
+
+	events, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if len(events) != 1 {
+		t.Fatalf("Poll() len = %d, want 1", len(events))
+	}
+
+	got := events[0]
+	if got.Kind != event.Kind("forecast_discussion") {
+		t.Fatalf("Kind = %q, want forecast_discussion", got.Kind)
+	}
+	if got.Schema != standards.SchemaRawNWSForecastDiscussionV1 {
+		t.Fatalf("Schema = %q, want %q", got.Schema, standards.SchemaRawNWSForecastDiscussionV1)
+	}
+	wantEffectiveAt := time.Date(2026, 3, 28, 19, 24, 0, 0, time.UTC)
+	if got.EffectiveAt == nil || !got.EffectiveAt.Equal(wantEffectiveAt) {
+		t.Fatalf("EffectiveAt = %v, want %s", got.EffectiveAt, wantEffectiveAt.Format(time.RFC3339))
+	}
+	payload, ok := got.Payload.(string)
+	if !ok {
+		t.Fatalf("Payload type = %T, want string", got.Payload)
+	}
+	if payload != rawHTML {
+		t.Fatalf("Payload did not preserve exact HTML")
+	}
+}
+
+func TestForecastDiscussionSourcePollReturnsNoEventsWhenUnchanged(t *testing.T) {
+	rawHTML := loadForecastDiscussionSampleHTML(t)
+	const etag = `"discussion-v1"`
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("If-None-Match") == etag {
+			w.WriteHeader(http.StatusNotModified)
+			return
+		}
+		w.Header().Set("ETag", etag)
+		_, _ = w.Write([]byte(rawHTML))
+	}))
+	defer srv.Close()
+
+	src, err := NewForecastDiscussionSource(forecastDiscussionSourceConfig(srv.URL))
+	if err != nil {
+		t.Fatalf("NewForecastDiscussionSource() error = %v", err)
+	}
+
+	first, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("first Poll() error = %v", err)
+	}
+	if len(first) != 1 {
+		t.Fatalf("first Poll() len = %d, want 1", len(first))
+	}
+
+	second, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("second Poll() error = %v", err)
+	}
+	if len(second) != 0 {
+		t.Fatalf("second Poll() len = %d, want 0", len(second))
+	}
+}
+
+func TestForecastDiscussionSourcePollRejectsInvalidHTML(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte("<html><body><div>missing discussion block</div></body></html>"))
+	}))
+	defer srv.Close()
+
+	src, err := NewForecastDiscussionSource(forecastDiscussionSourceConfig(srv.URL))
+	if err != nil {
+		t.Fatalf("NewForecastDiscussionSource() error = %v", err)
+	}
+
+	_, err = src.Poll(context.Background())
+	if err == nil {
+		t.Fatalf("Poll() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "glossaryProduct") {
+		t.Fatalf("error = %q, want glossaryProduct context", err)
+	}
+}
+
+func forecastDiscussionSourceConfig(url string) config.SourceConfig {
+	return config.SourceConfig{
+		Name:   "test-forecast-discussion-source",
+		Driver: "nws_forecast_discussion",
+		Mode:   config.SourceModePoll,
+		Params: map[string]any{
+			"url":        url,
+			"user_agent": "test-agent",
+		},
+	}
+}
+
+func loadForecastDiscussionSampleHTML(t *testing.T) string {
+	t.Helper()
+
+	path := filepath.Join("..", "..", "providers", "nws", "testdata", "forecast_discussion_sample.html")
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("os.ReadFile(%q) error = %v", path, err)
+	}
+	return string(b)
+}

internal/sources/nws/forecast_hourly.go

@@ -0,0 +1,28 @@
+// FILE: internal/sources/nws/forecast_hourly.go
+package nws
+
+import (
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+// HourlyForecastSource polls an NWS hourly forecast endpoint and emits a RAW forecast Event.
+//
+// It intentionally emits the *entire* upstream payload as json.RawMessage and only decodes
+// minimal metadata for Event.EffectiveAt and Event.ID.
+//
+// Output schema (current implementation):
+//   - standards.SchemaRawNWSHourlyForecastV1
+type HourlyForecastSource struct {
+	*forecastSource
+}
+
+func NewHourlyForecastSource(cfg config.SourceConfig) (*HourlyForecastSource, error) {
+	const driver = "nws_forecast_hourly"
+	src, err := newForecastSource(cfg, driver, standards.SchemaRawNWSHourlyForecastV1)
+	if err != nil {
+		return nil, err
+	}
+
+	return &HourlyForecastSource{forecastSource: src}, nil
+}

internal/sources/nws/forecast_narrative.go

@@ -0,0 +1,28 @@
+// FILE: internal/sources/nws/forecast_narrative.go
+package nws
+
+import (
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+// NarrativeForecastSource polls an NWS narrative forecast endpoint and emits a RAW forecast Event.
+//
+// It intentionally emits the *entire* upstream payload as json.RawMessage and only decodes
+// minimal metadata for Event.EffectiveAt and Event.ID.
+//
+// Output schema:
+//   - standards.SchemaRawNWSNarrativeForecastV1
+type NarrativeForecastSource struct {
+	*forecastSource
+}
+
+func NewNarrativeForecastSource(cfg config.SourceConfig) (*NarrativeForecastSource, error) {
+	const driver = "nws_forecast_narrative"
+	src, err := newForecastSource(cfg, driver, standards.SchemaRawNWSNarrativeForecastV1)
+	if err != nil {
+		return nil, err
+	}
+
+	return &NarrativeForecastSource{forecastSource: src}, nil
+}

internal/sources/nws/forecast_test.go

@@ -0,0 +1,189 @@
+package nws
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+type forecastPoller interface {
+	Poll(ctx context.Context) ([]event.Event, error)
+}
+
+func TestForecastSourcesEmitExpectedSchemaAndPreferGeneratedAt(t *testing.T) {
+	tests := []struct {
+		name       string
+		driver     string
+		wantSchema string
+		newSource  func(config.SourceConfig) (forecastPoller, error)
+	}{
+		{
+			name:       "hourly",
+			driver:     "nws_forecast_hourly",
+			wantSchema: standards.SchemaRawNWSHourlyForecastV1,
+			newSource: func(cfg config.SourceConfig) (forecastPoller, error) {
+				return NewHourlyForecastSource(cfg)
+			},
+		},
+		{
+			name:       "narrative",
+			driver:     "nws_forecast_narrative",
+			wantSchema: standards.SchemaRawNWSNarrativeForecastV1,
+			newSource: func(cfg config.SourceConfig) (forecastPoller, error) {
+				return NewNarrativeForecastSource(cfg)
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				_, _ = w.Write([]byte(`{"properties":{"generatedAt":"2026-03-28T12:00:00Z","updateTime":"2026-03-28T11:00:00Z"}}`))
+			}))
+			defer srv.Close()
+
+			src, err := tt.newSource(forecastSourceConfig(tt.driver, srv.URL))
+			if err != nil {
+				t.Fatalf("newSource() error = %v", err)
+			}
+			if ks, ok := src.(interface{ Kinds() []event.Kind }); !ok {
+				t.Fatalf("source does not implement Kinds()")
+			} else if gotKinds := ks.Kinds(); len(gotKinds) != 1 || gotKinds[0] != event.Kind("forecast") {
+				t.Fatalf("Kinds() = %#v, want [forecast]", gotKinds)
+			}
+
+			got, err := src.Poll(context.Background())
+			if err != nil {
+				t.Fatalf("Poll() error = %v", err)
+			}
+			if len(got) != 1 {
+				t.Fatalf("Poll() len = %d, want 1", len(got))
+			}
+			if got[0].Schema != tt.wantSchema {
+				t.Fatalf("Poll() schema = %q, want %q", got[0].Schema, tt.wantSchema)
+			}
+			if got[0].Kind != event.Kind("forecast") {
+				t.Fatalf("Poll() kind = %q, want forecast", got[0].Kind)
+			}
+
+			wantEffectiveAt := time.Date(2026, 3, 28, 12, 0, 0, 0, time.UTC)
+			if got[0].EffectiveAt == nil || !got[0].EffectiveAt.Equal(wantEffectiveAt) {
+				t.Fatalf("Poll() effectiveAt = %v, want %s", got[0].EffectiveAt, wantEffectiveAt)
+			}
+		})
+	}
+}
+
+func TestForecastSourcePollEffectiveAtFallbackOrder(t *testing.T) {
+	tests := []struct {
+		name            string
+		body            string
+		wantEffectiveAt *time.Time
+	}{
+		{
+			name: "updateTime fallback",
+			body: `{"properties":{"updateTime":"2026-03-28T11:00:00Z"}}`,
+			wantEffectiveAt: func() *time.Time {
+				t := time.Date(2026, 3, 28, 11, 0, 0, 0, time.UTC)
+				return &t
+			}(),
+		},
+		{
+			name: "updated fallback",
+			body: `{"properties":{"updated":"2026-03-28T10:00:00Z"}}`,
+			wantEffectiveAt: func() *time.Time {
+				t := time.Date(2026, 3, 28, 10, 0, 0, 0, time.UTC)
+				return &t
+			}(),
+		},
+		{
+			name:            "omitted when metadata lacks timestamps",
+			body:            `{"properties":{}}`,
+			wantEffectiveAt: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				_, _ = w.Write([]byte(tt.body))
+			}))
+			defer srv.Close()
+
+			src, err := NewHourlyForecastSource(forecastSourceConfig("nws_forecast_hourly", srv.URL))
+			if err != nil {
+				t.Fatalf("NewHourlyForecastSource() error = %v", err)
+			}
+
+			got, err := src.Poll(context.Background())
+			if err != nil {
+				t.Fatalf("Poll() error = %v", err)
+			}
+			if len(got) != 1 {
+				t.Fatalf("Poll() len = %d, want 1", len(got))
+			}
+			if tt.wantEffectiveAt == nil {
+				if got[0].EffectiveAt != nil {
+					t.Fatalf("Poll() effectiveAt = %v, want nil", got[0].EffectiveAt)
+				}
+				return
+			}
+			if got[0].EffectiveAt == nil || !got[0].EffectiveAt.Equal(*tt.wantEffectiveAt) {
+				t.Fatalf("Poll() effectiveAt = %v, want %s", got[0].EffectiveAt, *tt.wantEffectiveAt)
+			}
+		})
+	}
+}
+
+func TestForecastSourcePollMetadataDecodeFailureStillEmitsRawEvent(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`not-json`))
+	}))
+	defer srv.Close()
+
+	src, err := NewNarrativeForecastSource(forecastSourceConfig("nws_forecast_narrative", srv.URL))
+	if err != nil {
+		t.Fatalf("NewNarrativeForecastSource() error = %v", err)
+	}
+
+	got, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("Poll() len = %d, want 1", len(got))
+	}
+	if got[0].EffectiveAt != nil {
+		t.Fatalf("Poll() effectiveAt = %v, want nil", got[0].EffectiveAt)
+	}
+	if got[0].Schema != standards.SchemaRawNWSNarrativeForecastV1 {
+		t.Fatalf("Poll() schema = %q, want %q", got[0].Schema, standards.SchemaRawNWSNarrativeForecastV1)
+	}
+
+	raw, ok := got[0].Payload.(json.RawMessage)
+	if !ok {
+		t.Fatalf("Poll() payload type = %T, want json.RawMessage", got[0].Payload)
+	}
+	if string(raw) != "not-json" {
+		t.Fatalf("Poll() payload = %q, want %q", string(raw), "not-json")
+	}
+}
+
+func forecastSourceConfig(driver, url string) config.SourceConfig {
+	return config.SourceConfig{
+		Name:   "test-forecast-source",
+		Driver: driver,
+		Mode:   config.SourceModePoll,
+		Params: map[string]any{
+			"url":        url,
+			"user_agent": "test-agent",
+		},
+	}
+}

internal/sources/nws/observation.go

@@ -9,20 +9,20 @@ import (
 
 	"gitea.maximumdirect.net/ejr/feedkit/config"
 	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
 	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/sources/common"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 )
 
 // ObservationSource polls an NWS station observation endpoint and emits a RAW observation Event.
 type ObservationSource struct {
-	http *common.HTTPSource
+	http *fksources.HTTPSource
 }
 
 func NewObservationSource(cfg config.SourceConfig) (*ObservationSource, error) {
 	const driver = "nws_observation"
 
-	hs, err := common.NewHTTPSource(driver, cfg, "application/geo+json, application/json")
+	hs, err := fksources.NewHTTPSource(driver, cfg, "application/geo+json, application/json")
 	if err != nil {
 		return nil, err
 	}
@@ -32,13 +32,16 @@ func NewObservationSource(cfg config.SourceConfig) (*ObservationSource, error) {
 
 func (s *ObservationSource) Name() string { return s.http.Name }
 
-func (s *ObservationSource) Kind() event.Kind { return event.Kind("observation") }
+func (s *ObservationSource) Kinds() []event.Kind { return []event.Kind{event.Kind("observation")} }
 
 func (s *ObservationSource) Poll(ctx context.Context) ([]event.Event, error) {
-	raw, meta, err := s.fetchRaw(ctx)
+	raw, meta, changed, err := s.fetchRaw(ctx)
 	if err != nil {
 		return nil, err
 	}
+	if !changed {
+		return nil, nil
+	}
 
 	// EffectiveAt is optional; for observations it’s naturally the observation timestamp.
 	var effectiveAt *time.Time
@@ -48,10 +51,10 @@ func (s *ObservationSource) Poll(ctx context.Context) ([]event.Event, error) {
 	}
 
 	emittedAt := time.Now().UTC()
-	eventID := common.ChooseEventID(meta.ID, s.http.Name, effectiveAt, emittedAt)
+	eventID := fksources.DefaultEventID(meta.ID, s.http.Name, effectiveAt, emittedAt)
 
-	return common.SingleRawEvent(
+	return fksources.SingleEvent(
-		s.Kind(),
+		event.Kind("observation"),
 		s.http.Name,
 		standards.SchemaRawNWSObservationV1,
 		eventID,
@@ -72,16 +75,19 @@ type observationMeta struct {
 	ParsedTimestamp time.Time `json:"-"`
 }
 
-func (s *ObservationSource) fetchRaw(ctx context.Context) (json.RawMessage, observationMeta, error) {
+func (s *ObservationSource) fetchRaw(ctx context.Context) (json.RawMessage, observationMeta, bool, error) {
-	raw, err := s.http.FetchJSON(ctx)
+	raw, changed, err := s.http.FetchJSONIfChanged(ctx)
 	if err != nil {
-		return nil, observationMeta{}, err
+		return nil, observationMeta{}, false, err
+	}
+	if !changed {
+		return nil, observationMeta{}, false, nil
 	}
 
 	var meta observationMeta
 	if err := json.Unmarshal(raw, &meta); err != nil {
 		// If metadata decode fails, still return raw; envelope will fall back to Source:EffectiveAt.
-		return raw, observationMeta{}, nil
+		return raw, observationMeta{}, true, nil
 	}
 
 	tsStr := strings.TrimSpace(meta.Properties.Timestamp)
@@ -91,5 +97,5 @@ func (s *ObservationSource) fetchRaw(ctx context.Context) (json.RawMessage, obse
 		}
 	}
 
-	return raw, meta, nil
+	return raw, meta, true, nil
 }

internal/sources/nws/observation_test.go

@@ -0,0 +1,66 @@
+package nws
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+)
+
+func TestObservationSourcePollReturnsNoEventsOn304(t *testing.T) {
+	var call int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		call++
+		switch call {
+		case 1:
+			w.Header().Set("ETag", `"obs-v1"`)
+			_, _ = w.Write([]byte(`{"id":"obs-1","properties":{"timestamp":"2026-03-28T12:00:00Z"}}`))
+		case 2:
+			if got := r.Header.Get("If-None-Match"); got != `"obs-v1"` {
+				t.Fatalf("second request If-None-Match = %q", got)
+			}
+			w.WriteHeader(http.StatusNotModified)
+		default:
+			t.Fatalf("unexpected call count %d", call)
+		}
+	}))
+	defer srv.Close()
+
+	src, err := NewObservationSource(config.SourceConfig{
+		Name:   "NWSObservationTest",
+		Driver: "nws_observation",
+		Mode:   config.SourceModePoll,
+		Params: map[string]any{
+			"url":        srv.URL,
+			"user_agent": "test-agent",
+		},
+	})
+	if err != nil {
+		t.Fatalf("NewObservationSource() error = %v", err)
+	}
+	if got := src.Kinds(); len(got) != 1 || got[0] != event.Kind("observation") {
+		t.Fatalf("Kinds() = %#v, want [observation]", got)
+	}
+
+	first, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("first Poll() error = %v", err)
+	}
+	if len(first) != 1 {
+		t.Fatalf("first Poll() len = %d, want 1", len(first))
+	}
+	if first[0].Kind != event.Kind("observation") {
+		t.Fatalf("first Poll() kind = %q", first[0].Kind)
+	}
+
+	second, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("second Poll() error = %v", err)
+	}
+	if len(second) != 0 {
+		t.Fatalf("second Poll() len = %d, want 0", len(second))
+	}
+}

internal/sources/nws/weatherstories.go

@@ -0,0 +1,118 @@
+package nws
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
+	nwscommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/nws"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+// WeatherStoriesSource polls an NWS weatherstories endpoint and emits a RAW weather story Event.
+//
+// Output schema:
+//   - standards.SchemaRawNWSWeatherStoriesV1
+type WeatherStoriesSource struct {
+	http *fksources.HTTPSource
+}
+
+func NewWeatherStoriesSource(cfg config.SourceConfig) (*WeatherStoriesSource, error) {
+	const driver = "nws_weatherstories"
+
+	hs, err := fksources.NewHTTPSource(driver, cfg, "application/geo+json, application/json")
+	if err != nil {
+		return nil, err
+	}
+
+	return &WeatherStoriesSource{http: hs}, nil
+}
+
+func (s *WeatherStoriesSource) Name() string { return s.http.Name }
+
+func (s *WeatherStoriesSource) Kinds() []event.Kind {
+	return []event.Kind{event.Kind("weather_story")}
+}
+
+func (s *WeatherStoriesSource) Poll(ctx context.Context) ([]event.Event, error) {
+	raw, meta, changed, err := s.fetchRaw(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if !changed {
+		return nil, nil
+	}
+
+	var effectiveAt *time.Time
+	switch {
+	case !meta.ParsedLatestUpdateTime.IsZero():
+		t := meta.ParsedLatestUpdateTime.UTC()
+		effectiveAt = &t
+	case !meta.ParsedLatestStartTime.IsZero():
+		t := meta.ParsedLatestStartTime.UTC()
+		effectiveAt = &t
+	}
+
+	emittedAt := time.Now().UTC()
+	eventID := fksources.DefaultEventID("", s.http.Name, effectiveAt, emittedAt)
+
+	return fksources.SingleEvent(
+		event.Kind("weather_story"),
+		s.http.Name,
+		standards.SchemaRawNWSWeatherStoriesV1,
+		eventID,
+		emittedAt,
+		effectiveAt,
+		raw,
+	)
+}
+
+type weatherStoriesMeta struct {
+	Stories []struct {
+		StartTime  string `json:"startTime"`
+		UpdateTime string `json:"updateTime"`
+	} `json:"stories"`
+
+	ParsedLatestUpdateTime time.Time `json:"-"`
+	ParsedLatestStartTime  time.Time `json:"-"`
+}
+
+func (s *WeatherStoriesSource) fetchRaw(ctx context.Context) (json.RawMessage, weatherStoriesMeta, bool, error) {
+	raw, changed, err := s.http.FetchJSONIfChanged(ctx)
+	if err != nil {
+		return nil, weatherStoriesMeta{}, false, err
+	}
+	if !changed {
+		return nil, weatherStoriesMeta{}, false, nil
+	}
+
+	var meta weatherStoriesMeta
+	if err := json.Unmarshal(raw, &meta); err != nil {
+		return raw, weatherStoriesMeta{}, true, nil
+	}
+
+	for _, story := range meta.Stories {
+		if ts := strings.TrimSpace(story.UpdateTime); ts != "" {
+			if t, err := nwscommon.ParseTime(ts); err == nil {
+				t = t.UTC()
+				if meta.ParsedLatestUpdateTime.IsZero() || t.After(meta.ParsedLatestUpdateTime) {
+					meta.ParsedLatestUpdateTime = t
+				}
+			}
+		}
+		if ts := strings.TrimSpace(story.StartTime); ts != "" {
+			if t, err := nwscommon.ParseTime(ts); err == nil {
+				t = t.UTC()
+				if meta.ParsedLatestStartTime.IsZero() || t.After(meta.ParsedLatestStartTime) {
+					meta.ParsedLatestStartTime = t
+				}
+			}
+		}
+	}
+
+	return raw, meta, true, nil
+}

internal/sources/nws/weatherstories_test.go

@@ -0,0 +1,158 @@
+package nws
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
+)
+
+func TestWeatherStoriesSourcePollEmitsExpectedEventAndPrefersLatestUpdateTime(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{
+			"stories": [
+				{"startTime":"2026-05-30T08:46:00+00:00","updateTime":"2026-05-30T09:00:34+00:00"},
+				{"startTime":"2026-05-30T10:00:00+00:00","updateTime":"2026-05-30T11:00:34+00:00"}
+			]
+		}`))
+	}))
+	defer srv.Close()
+
+	src, err := NewWeatherStoriesSource(weatherStoriesSourceConfig(srv.URL))
+	if err != nil {
+		t.Fatalf("NewWeatherStoriesSource() error = %v", err)
+	}
+	if got := src.Kinds(); len(got) != 1 || got[0] != event.Kind("weather_story") {
+		t.Fatalf("Kinds() = %#v, want [weather_story]", got)
+	}
+
+	events, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if len(events) != 1 {
+		t.Fatalf("Poll() len = %d, want 1", len(events))
+	}
+
+	got := events[0]
+	if got.Kind != event.Kind("weather_story") {
+		t.Fatalf("Kind = %q, want weather_story", got.Kind)
+	}
+	if got.Schema != standards.SchemaRawNWSWeatherStoriesV1 {
+		t.Fatalf("Schema = %q, want %q", got.Schema, standards.SchemaRawNWSWeatherStoriesV1)
+	}
+	wantEffectiveAt := time.Date(2026, 5, 30, 11, 0, 34, 0, time.UTC)
+	if got.EffectiveAt == nil || !got.EffectiveAt.Equal(wantEffectiveAt) {
+		t.Fatalf("EffectiveAt = %v, want %s", got.EffectiveAt, wantEffectiveAt.Format(time.RFC3339))
+	}
+	if _, ok := got.Payload.(json.RawMessage); !ok {
+		t.Fatalf("Payload type = %T, want json.RawMessage", got.Payload)
+	}
+}
+
+func TestWeatherStoriesSourcePollEffectiveAtFallsBackToLatestStartTime(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{
+			"stories": [
+				{"startTime":"2026-05-30T08:46:00+00:00","updateTime":"bad"},
+				{"startTime":"2026-05-31T11:00:00+00:00","updateTime":""}
+			]
+		}`))
+	}))
+	defer srv.Close()
+
+	src, err := NewWeatherStoriesSource(weatherStoriesSourceConfig(srv.URL))
+	if err != nil {
+		t.Fatalf("NewWeatherStoriesSource() error = %v", err)
+	}
+
+	events, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if len(events) != 1 {
+		t.Fatalf("Poll() len = %d, want 1", len(events))
+	}
+	wantEffectiveAt := time.Date(2026, 5, 31, 11, 0, 0, 0, time.UTC)
+	if events[0].EffectiveAt == nil || !events[0].EffectiveAt.Equal(wantEffectiveAt) {
+		t.Fatalf("EffectiveAt = %v, want %s", events[0].EffectiveAt, wantEffectiveAt.Format(time.RFC3339))
+	}
+}
+
+func TestWeatherStoriesSourcePollReturnsNoEventsWhenUnchanged(t *testing.T) {
+	const etag = `"stories-v1"`
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("If-None-Match") == etag {
+			w.WriteHeader(http.StatusNotModified)
+			return
+		}
+		w.Header().Set("ETag", etag)
+		_, _ = w.Write([]byte(`{"stories":[]}`))
+	}))
+	defer srv.Close()
+
+	src, err := NewWeatherStoriesSource(weatherStoriesSourceConfig(srv.URL))
+	if err != nil {
+		t.Fatalf("NewWeatherStoriesSource() error = %v", err)
+	}
+
+	first, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("first Poll() error = %v", err)
+	}
+	if len(first) != 1 {
+		t.Fatalf("first Poll() len = %d, want 1", len(first))
+	}
+
+	second, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("second Poll() error = %v", err)
+	}
+	if len(second) != 0 {
+		t.Fatalf("second Poll() len = %d, want 0", len(second))
+	}
+}
+
+func TestWeatherStoriesSourcePollMetadataDecodeFailureStillEmitsRawEvent(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`not-json`))
+	}))
+	defer srv.Close()
+
+	src, err := NewWeatherStoriesSource(weatherStoriesSourceConfig(srv.URL))
+	if err != nil {
+		t.Fatalf("NewWeatherStoriesSource() error = %v", err)
+	}
+
+	events, err := src.Poll(context.Background())
+	if err != nil {
+		t.Fatalf("Poll() error = %v", err)
+	}
+	if len(events) != 1 {
+		t.Fatalf("Poll() len = %d, want 1", len(events))
+	}
+	if events[0].EffectiveAt != nil {
+		t.Fatalf("EffectiveAt = %v, want nil", events[0].EffectiveAt)
+	}
+	if events[0].Schema != standards.SchemaRawNWSWeatherStoriesV1 {
+		t.Fatalf("Schema = %q, want %q", events[0].Schema, standards.SchemaRawNWSWeatherStoriesV1)
+	}
+}
+
+func weatherStoriesSourceConfig(url string) config.SourceConfig {
+	return config.SourceConfig{
+		Name:   "test-weatherstories-source",
+		Driver: "nws_weatherstories",
+		Mode:   config.SourceModePoll,
+		Params: map[string]any{
+			"url":        url,
+			"user_agent": "test-agent",
+		},
+	}
+}

internal/sources/openmeteo/forecast.go

@@ -8,20 +8,20 @@ import (
 
 	"gitea.maximumdirect.net/ejr/feedkit/config"
 	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/openmeteo"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/sources/common"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 )
 
 // ForecastSource polls an Open-Meteo hourly forecast endpoint and emits one RAW Forecast Event.
 type ForecastSource struct {
-	http *common.HTTPSource
+	http *fksources.HTTPSource
 }
 
 func NewForecastSource(cfg config.SourceConfig) (*ForecastSource, error) {
 	const driver = "openmeteo_forecast"
 
-	hs, err := common.NewHTTPSource(driver, cfg, "application/json")
+	hs, err := fksources.NewHTTPSource(driver, cfg, "application/json")
 	if err != nil {
 		return nil, err
 	}
@@ -31,13 +31,16 @@ func NewForecastSource(cfg config.SourceConfig) (*ForecastSource, error) {
 
 func (s *ForecastSource) Name() string { return s.http.Name }
 
-func (s *ForecastSource) Kind() event.Kind { return event.Kind("forecast") }
+func (s *ForecastSource) Kinds() []event.Kind { return []event.Kind{event.Kind("forecast")} }
 
 func (s *ForecastSource) Poll(ctx context.Context) ([]event.Event, error) {
-	raw, meta, err := s.fetchRaw(ctx)
+	raw, meta, changed, err := s.fetchRaw(ctx)
 	if err != nil {
 		return nil, err
 	}
+	if !changed {
+		return nil, nil
+	}
 
 	// Open-Meteo does not expose a true "issued at" timestamp for forecast runs.
 	// We use current.time when present; otherwise we fall back to the first hourly time
@@ -49,10 +52,10 @@ func (s *ForecastSource) Poll(ctx context.Context) ([]event.Event, error) {
 	}
 
 	emittedAt := time.Now().UTC()
-	eventID := common.ChooseEventID("", s.http.Name, effectiveAt, emittedAt)
+	eventID := fksources.DefaultEventID("", s.http.Name, effectiveAt, emittedAt)
 
-	return common.SingleRawEvent(
+	return fksources.SingleEvent(
-		s.Kind(),
+		event.Kind("forecast"),
 		s.http.Name,
 		standards.SchemaRawOpenMeteoHourlyForecastV1,
 		eventID,
@@ -79,16 +82,19 @@ type forecastMeta struct {
 	ParsedTimestamp time.Time `json:"-"`
 }
 
-func (s *ForecastSource) fetchRaw(ctx context.Context) (json.RawMessage, forecastMeta, error) {
+func (s *ForecastSource) fetchRaw(ctx context.Context) (json.RawMessage, forecastMeta, bool, error) {
-	raw, err := s.http.FetchJSON(ctx)
+	raw, changed, err := s.http.FetchJSONIfChanged(ctx)
 	if err != nil {
-		return nil, forecastMeta{}, err
+		return nil, forecastMeta{}, false, err
+	}
+	if !changed {
+		return nil, forecastMeta{}, false, nil
 	}
 
 	var meta forecastMeta
 	if err := json.Unmarshal(raw, &meta); err != nil {
 		// If metadata decode fails, still return raw; Poll will fall back to Source:EmittedAt.
-		return raw, forecastMeta{}, nil
+		return raw, forecastMeta{}, true, nil
 	}
 
 	ts := strings.TrimSpace(meta.Current.Time)
@@ -106,5 +112,5 @@ func (s *ForecastSource) fetchRaw(ctx context.Context) (json.RawMessage, forecas
 		}
 	}
 
-	return raw, meta, nil
+	return raw, meta, true, nil
 }

internal/sources/openmeteo/observation.go

@@ -8,20 +8,20 @@ import (
 
 	"gitea.maximumdirect.net/ejr/feedkit/config"
 	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
 	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/openmeteo"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/sources/common"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 )
 
 // ObservationSource polls an Open-Meteo endpoint and emits one RAW Observation Event.
 type ObservationSource struct {
-	http *common.HTTPSource
+	http *fksources.HTTPSource
 }
 
 func NewObservationSource(cfg config.SourceConfig) (*ObservationSource, error) {
 	const driver = "openmeteo_observation"
 
-	hs, err := common.NewHTTPSource(driver, cfg, "application/json")
+	hs, err := fksources.NewHTTPSource(driver, cfg, "application/json")
 	if err != nil {
 		return nil, err
 	}
@@ -31,13 +31,16 @@ func NewObservationSource(cfg config.SourceConfig) (*ObservationSource, error) {
 
 func (s *ObservationSource) Name() string { return s.http.Name }
 
-func (s *ObservationSource) Kind() event.Kind { return event.Kind("observation") }
+func (s *ObservationSource) Kinds() []event.Kind { return []event.Kind{event.Kind("observation")} }
 
 func (s *ObservationSource) Poll(ctx context.Context) ([]event.Event, error) {
-	raw, meta, err := s.fetchRaw(ctx)
+	raw, meta, changed, err := s.fetchRaw(ctx)
 	if err != nil {
 		return nil, err
 	}
+	if !changed {
+		return nil, nil
+	}
 
 	var effectiveAt *time.Time
 	if !meta.ParsedTimestamp.IsZero() {
@@ -46,10 +49,10 @@ func (s *ObservationSource) Poll(ctx context.Context) ([]event.Event, error) {
 	}
 
 	emittedAt := time.Now().UTC()
-	eventID := common.ChooseEventID("", s.http.Name, effectiveAt, emittedAt)
+	eventID := fksources.DefaultEventID("", s.http.Name, effectiveAt, emittedAt)
 
-	return common.SingleRawEvent(
+	return fksources.SingleEvent(
-		s.Kind(),
+		event.Kind("observation"),
 		s.http.Name,
 		standards.SchemaRawOpenMeteoCurrentV1,
 		eventID,
@@ -72,21 +75,24 @@ type openMeteoMeta struct {
 	ParsedTimestamp time.Time `json:"-"`
 }
 
-func (s *ObservationSource) fetchRaw(ctx context.Context) (json.RawMessage, openMeteoMeta, error) {
+func (s *ObservationSource) fetchRaw(ctx context.Context) (json.RawMessage, openMeteoMeta, bool, error) {
-	raw, err := s.http.FetchJSON(ctx)
+	raw, changed, err := s.http.FetchJSONIfChanged(ctx)
 	if err != nil {
-		return nil, openMeteoMeta{}, err
+		return nil, openMeteoMeta{}, false, err
+	}
+	if !changed {
+		return nil, openMeteoMeta{}, false, nil
 	}
 
 	var meta openMeteoMeta
 	if err := json.Unmarshal(raw, &meta); err != nil {
 		// If metadata decode fails, still return raw; envelope will omit EffectiveAt.
-		return raw, openMeteoMeta{}, nil
+		return raw, openMeteoMeta{}, true, nil
 	}
 
 	if t, err := openmeteo.ParseTime(meta.Current.Time, meta.Timezone, meta.UTCOffsetSeconds); err == nil {
 		meta.ParsedTimestamp = t.UTC()
 	}
 
-	return raw, meta, nil
+	return raw, meta, true, nil
 }

internal/sources/openmeteo/source_test.go

@@ -0,0 +1,44 @@
+package openmeteo
+
+import (
+	"testing"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+)
+
+func TestObservationSourceAdvertisesKinds(t *testing.T) {
+	src, err := NewObservationSource(config.SourceConfig{
+		Name:   "openmeteo-observation-test",
+		Driver: "openmeteo_observation",
+		Mode:   config.SourceModePoll,
+		Params: map[string]any{
+			"url":        "https://example.invalid",
+			"user_agent": "test-agent",
+		},
+	})
+	if err != nil {
+		t.Fatalf("NewObservationSource() error = %v", err)
+	}
+	if got := src.Kinds(); len(got) != 1 || got[0] != event.Kind("observation") {
+		t.Fatalf("Kinds() = %#v, want [observation]", got)
+	}
+}
+
+func TestForecastSourceAdvertisesKinds(t *testing.T) {
+	src, err := NewForecastSource(config.SourceConfig{
+		Name:   "openmeteo-forecast-test",
+		Driver: "openmeteo_forecast",
+		Mode:   config.SourceModePoll,
+		Params: map[string]any{
+			"url":        "https://example.invalid",
+			"user_agent": "test-agent",
+		},
+	})
+	if err != nil {
+		t.Fatalf("NewForecastSource() error = %v", err)
+	}
+	if got := src.Kinds(); len(got) != 1 || got[0] != event.Kind("forecast") {
+		t.Fatalf("Kinds() = %#v, want [forecast]", got)
+	}
+}

internal/sources/openweather/observation.go

@@ -9,19 +9,19 @@ import (
 
 	"gitea.maximumdirect.net/ejr/feedkit/config"
 	"gitea.maximumdirect.net/ejr/feedkit/event"
+	fksources "gitea.maximumdirect.net/ejr/feedkit/sources"
 	owcommon "gitea.maximumdirect.net/ejr/weatherfeeder/internal/providers/openweather"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/sources/common"
+	"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
-	"gitea.maximumdirect.net/ejr/weatherfeeder/internal/standards"
 )
 
 type ObservationSource struct {
-	http *common.HTTPSource
+	http *fksources.HTTPSource
 }
 
 func NewObservationSource(cfg config.SourceConfig) (*ObservationSource, error) {
 	const driver = "openweather_observation"
 
-	hs, err := common.NewHTTPSource(driver, cfg, "application/json")
+	hs, err := fksources.NewHTTPSource(driver, cfg, "application/json")
 	if err != nil {
 		return nil, err
 	}
@@ -35,17 +35,20 @@ func NewObservationSource(cfg config.SourceConfig) (*ObservationSource, error) {
 
 func (s *ObservationSource) Name() string { return s.http.Name }
 
-func (s *ObservationSource) Kind() event.Kind { return event.Kind("observation") }
+func (s *ObservationSource) Kinds() []event.Kind { return []event.Kind{event.Kind("observation")} }
 
 func (s *ObservationSource) Poll(ctx context.Context) ([]event.Event, error) {
 	if err := owcommon.RequireMetricUnits(s.http.URL); err != nil {
 		return nil, fmt.Errorf("%s %q: %w", s.http.Driver, s.http.Name, err)
 	}
 
-	raw, meta, err := s.fetchRaw(ctx)
+	raw, meta, changed, err := s.fetchRaw(ctx)
 	if err != nil {
 		return nil, err
 	}
+	if !changed {
+		return nil, nil
+	}
 
 	var effectiveAt *time.Time
 	if !meta.ParsedTimestamp.IsZero() {
@@ -54,10 +57,10 @@ func (s *ObservationSource) Poll(ctx context.Context) ([]event.Event, error) {
 	}
 
 	emittedAt := time.Now().UTC()
-	eventID := common.ChooseEventID("", s.http.Name, effectiveAt, emittedAt)
+	eventID := fksources.DefaultEventID("", s.http.Name, effectiveAt, emittedAt)
 
-	return common.SingleRawEvent(
+	return fksources.SingleEvent(
-		s.Kind(),
+		event.Kind("observation"),
 		s.http.Name,
 		standards.SchemaRawOpenWeatherCurrentV1,
 		eventID,
@@ -75,20 +78,23 @@ type openWeatherMeta struct {
 	ParsedTimestamp time.Time `json:"-"`
 }
 
-func (s *ObservationSource) fetchRaw(ctx context.Context) (json.RawMessage, openWeatherMeta, error) {
+func (s *ObservationSource) fetchRaw(ctx context.Context) (json.RawMessage, openWeatherMeta, bool, error) {
-	raw, err := s.http.FetchJSON(ctx)
+	raw, changed, err := s.http.FetchJSONIfChanged(ctx)
 	if err != nil {
-		return nil, openWeatherMeta{}, err
+		return nil, openWeatherMeta{}, false, err
+	}
+	if !changed {
+		return nil, openWeatherMeta{}, false, nil
 	}
 
 	var meta openWeatherMeta
 	if err := json.Unmarshal(raw, &meta); err != nil {
-		return raw, openWeatherMeta{}, nil
+		return raw, openWeatherMeta{}, true, nil
 	}
 
 	if meta.Dt > 0 {
 		meta.ParsedTimestamp = time.Unix(meta.Dt, 0).UTC()
 	}
 
-	return raw, meta, nil
+	return raw, meta, true, nil
 }

internal/sources/openweather/source_test.go

@@ -0,0 +1,26 @@
+package openweather
+
+import (
+	"testing"
+
+	"gitea.maximumdirect.net/ejr/feedkit/config"
+	"gitea.maximumdirect.net/ejr/feedkit/event"
+)
+
+func TestObservationSourceAdvertisesKinds(t *testing.T) {
+	src, err := NewObservationSource(config.SourceConfig{
+		Name:   "openweather-observation-test",
+		Driver: "openweather_observation",
+		Mode:   config.SourceModePoll,
+		Params: map[string]any{
+			"url":        "https://example.invalid?units=metric",
+			"user_agent": "test-agent",
+		},
+	})
+	if err != nil {
+		t.Fatalf("NewObservationSource() error = %v", err)
+	}
+	if got := src.Kinds(); len(got) != 1 || got[0] != event.Kind("observation") {
+		t.Fatalf("Kinds() = %#v, want [observation]", got)
+	}
+}

internal/standards/wmo_categories.go

@@ -1,127 +0,0 @@
-package standards
-
-import "gitea.maximumdirect.net/ejr/weatherfeeder/model"
-
-// This file provides small, shared helper functions for reasoning about WMO codes.
-// These are intentionally "coarse" categories that are useful for business logic,
-// dashboards, and alerting decisions.
-//
-// Example uses:
-// - jogging suitability: precipitation? thunderstorm? freezing precip?
-// - quick glance: "is it cloudy?" "is there any precip?"
-// - downstream normalizers / aggregators
-
-func IsThunderstorm(code model.WMOCode) bool {
-	switch code {
-	case 95, 96, 99:
-		return true
-	default:
-		return false
-	}
-}
-
-func IsHail(code model.WMOCode) bool {
-	switch code {
-	case 96, 99:
-		return true
-	default:
-		return false
-	}
-}
-
-func IsFog(code model.WMOCode) bool {
-	switch code {
-	case 45, 48:
-		return true
-	default:
-		return false
-	}
-}
-
-// IsPrecipitation returns true if the code represents any precipitation
-// (drizzle, rain, snow, showers, etc.).
-func IsPrecipitation(code model.WMOCode) bool {
-	switch code {
-	// Drizzle
-	case 51, 53, 55, 56, 57:
-		return true
-
-	// Rain
-	case 61, 63, 65, 66, 67:
-		return true
-
-	// Snow
-	case 71, 73, 75, 77:
-		return true
-
-	// Showers
-	case 80, 81, 82, 85, 86:
-		return true
-
-	// Thunderstorm (often includes rain/hail)
-	case 95, 96, 99:
-		return true
-
-	default:
-		return false
-	}
-}
-
-func IsRainFamily(code model.WMOCode) bool {
-	switch code {
-	// Drizzle + freezing drizzle
-	case 51, 53, 55, 56, 57:
-		return true
-
-	// Rain + freezing rain
-	case 61, 63, 65, 66, 67:
-		return true
-
-	// Rain showers
-	case 80, 81, 82:
-		return true
-
-	// Thunderstorm often implies rain
-	case 95, 96, 99:
-		return true
-
-	default:
-		return false
-	}
-}
-
-func IsSnowFamily(code model.WMOCode) bool {
-	switch code {
-	// Snow and related
-	case 71, 73, 75, 77:
-		return true
-
-	// Snow showers
-	case 85, 86:
-		return true
-
-	default:
-		return false
-	}
-}
-
-// IsFreezingPrecip returns true if the code represents freezing drizzle/rain.
-func IsFreezingPrecip(code model.WMOCode) bool {
-	switch code {
-	case 56, 57, 66, 67:
-		return true
-	default:
-		return false
-	}
-}
-
-// IsSkyOnly returns true for codes that represent "sky condition only"
-// (clear/mostly/partly/cloudy) rather than fog/precip/etc.
-func IsSkyOnly(code model.WMOCode) bool {
-	switch code {
-	case 0, 1, 2, 3:
-		return true
-	default:
-		return false
-	}
-}

model/alert.go

@@ -1,4 +1,4 @@
-// FILE: internal/model/alert.go
+// FILE: model/alert.go
 package model
 
 import "time"

model/doc.go

@@ -1,4 +1,4 @@
-// FILE: internal/model/doc.go
+// FILE: model/doc.go
 // Package model defines weatherfeeder's canonical domain payload types.
 //
 // These structs are emitted as the Payload of canonical events (schemas "weather.*.vN").

model/forecast.go

@@ -1,4 +1,4 @@
-// FILE: internal/model/forecast.go
+// FILE: model/forecast.go
 package model
 
 import "time"
@@ -71,22 +71,12 @@ type WeatherForecastPeriod struct {
 	// Providers vary in whether they explicitly include this.
 	IsDay *bool `json:"isDay,omitempty"`
 
-	// Canonical internal representation (provider-independent).
+	// Canonical internal representation (provider-independent), when applicable.
-	// Like WeatherObservation, this is required; use an “unknown” WMOCode if unmappable.
+	// Some products (notably narrative) may not provide or imply a canonical WMO code.
-	ConditionCode WMOCode `json:"conditionCode"`
+	ConditionCode *WMOCode `json:"conditionCode,omitempty"`
 
-	// Provider-independent short text describing the conditions (normalized, if possible).
+	// Human-facing narrative summary for this period.
-	ConditionText string `json:"conditionText,omitempty"`
+	TextDescription string `json:"textDescription,omitempty"`
-
-	// Provider-specific “evidence” for troubleshooting mapping and drift.
-	ProviderRawDescription string `json:"providerRawDescription,omitempty"`
-
-	// Human-facing narrative. Not all providers supply rich text (Open-Meteo often won’t).
-	TextDescription string `json:"textDescription,omitempty"` // short phrase / summary
-	DetailedText    string `json:"detailedText,omitempty"`    // longer narrative, if available
-
-	// Provider-specific (legacy / transitional)
-	IconURL string `json:"iconUrl,omitempty"`
 
 	// Core predicted measurements (nullable; units align with WeatherObservation)
 	TemperatureC *float64 `json:"temperatureC,omitempty"`

model/forecast_discussion.go

@@ -0,0 +1,40 @@
+package model
+
+import "time"
+
+// ForecastDiscussionProduct distinguishes the discussion bulletin family.
+//
+// Today weatherfeeder only normalizes Area Forecast Discussion (AFD) products,
+// but this remains a distinct type so additional discussion-like products can be
+// added without changing the payload field type.
+type ForecastDiscussionProduct string
+
+const (
+	ForecastDiscussionProductAFD ForecastDiscussionProduct = "afd"
+)
+
+// WeatherForecastDiscussion is a canonical issued discussion bulletin for an NWS office.
+//
+// Unlike WeatherForecastRun, this is authored narrative text rather than a sequence
+// of forecast periods.
+type WeatherForecastDiscussion struct {
+	OfficeID   string `json:"officeId,omitempty"`
+	OfficeName string `json:"officeName,omitempty"`
+
+	Product ForecastDiscussionProduct `json:"product"`
+
+	IssuedAt  time.Time  `json:"issuedAt"`
+	UpdatedAt *time.Time `json:"updatedAt,omitempty"`
+
+	KeyMessages []string `json:"keyMessages,omitempty"`
+
+	ShortTerm *WeatherForecastDiscussionSection `json:"shortTerm,omitempty"`
+	LongTerm  *WeatherForecastDiscussionSection `json:"longTerm,omitempty"`
+}
+
+// WeatherForecastDiscussionSection is a fixed prose section within a discussion bulletin.
+type WeatherForecastDiscussionSection struct {
+	Qualifier string     `json:"qualifier,omitempty"`
+	IssuedAt  *time.Time `json:"issuedAt,omitempty"`
+	Text      string     `json:"text,omitempty"`
+}

model/observation.go

@@ -1,4 +1,4 @@
-// FILE: internal/model/observation.go
+// FILE: model/observation.go
 package model
 
 import "time"
@@ -11,18 +11,9 @@ type WeatherObservation struct {
 
 	// Canonical internal representation (provider-independent).
 	ConditionCode   WMOCode `json:"conditionCode"`
-	ConditionText string  `json:"conditionText,omitempty"`
 	IsDay           *bool   `json:"isDay,omitempty"`
-
-	// Provider-specific “evidence” for troubleshooting mapping and drift.
-	ProviderRawDescription string `json:"providerRawDescription,omitempty"`
-
-	// Human-facing (legacy / transitional)
 	TextDescription string  `json:"textDescription,omitempty"`
 
-	// Provider-specific (legacy / transitional)
-	IconURL string `json:"iconUrl,omitempty"`
-
 	// Core measurements (nullable)
 	TemperatureC *float64 `json:"temperatureC,omitempty"`
 	DewpointC    *float64 `json:"dewpointC,omitempty"`
@@ -32,22 +23,12 @@ type WeatherObservation struct {
 	WindGustKmh          *float64 `json:"windGustKmh,omitempty"`
 
 	BarometricPressurePa *float64 `json:"barometricPressurePa,omitempty"`
-	SeaLevelPressurePa   *float64 `json:"seaLevelPressurePa,omitempty"`
 	VisibilityMeters     *float64 `json:"visibilityMeters,omitempty"`
 
 	RelativeHumidityPercent *float64 `json:"relativeHumidityPercent,omitempty"`
 	ApparentTemperatureC    *float64 `json:"apparentTemperatureC,omitempty"`
 
-	ElevationMeters *float64 `json:"elevationMeters,omitempty"`
-	RawMessage      string   `json:"rawMessage,omitempty"`
-
 	PresentWeather []PresentWeather `json:"presentWeather,omitempty"`
-	CloudLayers    []CloudLayer     `json:"cloudLayers,omitempty"`
-}
-
-type CloudLayer struct {
-	BaseMeters *float64 `json:"baseMeters,omitempty"`
-	Amount     string   `json:"amount,omitempty"`
 }
 
 type PresentWeather struct {

model/weather_story.go

@@ -0,0 +1,28 @@
+package model
+
+import "time"
+
+// WeatherStoryRun is a snapshot of NWS weather stories for an office as-of a point in time.
+type WeatherStoryRun struct {
+	OfficeID string    `json:"officeId,omitempty"`
+	AsOf     time.Time `json:"asOf"`
+
+	Stories []WeatherStory `json:"stories"`
+}
+
+// WeatherStory is a provider-independent representation of a single story card.
+type WeatherStory struct {
+	OfficeID string `json:"officeId,omitempty"`
+
+	StartTime time.Time `json:"startTime"`
+	EndTime   time.Time `json:"endTime"`
+	UpdatedAt time.Time `json:"updatedAt"`
+
+	Title       string `json:"title,omitempty"`
+	Description string `json:"description,omitempty"`
+	AltText     string `json:"altText,omitempty"`
+
+	Priority    bool   `json:"priority"`
+	Order       int    `json:"order"`
+	DownloadURL string `json:"downloadUrl,omitempty"`
+}

standards/doc.go

@@ -15,7 +15,7 @@
 // -----------------------
 // For readability and stability, canonical payloads (weather.* schemas) should not emit
 // noisy floating-point representations. weatherfeeder enforces this by rounding float
-// values in canonical payloads to 2 digits after the decimal point at normalization
+// values in canonical payloads to 4 digits after the decimal point at normalization
 // finalization time.
 //
 // Provider-specific decoding helpers and quirks live in internal/providers/<provider>.

standards/schema.go

@@ -16,6 +16,9 @@ const (
 	SchemaRawOpenWeatherCurrentV1 = "raw.openweather.current.v1"
 
 	SchemaRawNWSHourlyForecastV1         = "raw.nws.hourly.forecast.v1"
+	SchemaRawNWSNarrativeForecastV1      = "raw.nws.narrative.forecast.v1"
+	SchemaRawNWSForecastDiscussionV1     = "raw.nws.forecast_discussion.v1"
+	SchemaRawNWSWeatherStoriesV1         = "raw.nws.weatherstories.v1"
 	SchemaRawOpenMeteoHourlyForecastV1   = "raw.openmeteo.hourly.forecast.v1"
 	SchemaRawOpenWeatherHourlyForecastV1 = "raw.openweather.hourly.forecast.v1"
 
@@ -24,5 +27,7 @@ const (
 	// Canonical domain schemas (emitted after normalization).
 	SchemaWeatherObservationV1        = "weather.observation.v1"
 	SchemaWeatherForecastV1           = "weather.forecast.v1"
+	SchemaWeatherForecastDiscussionV1 = "weather.forecast_discussion.v1"
+	SchemaWeatherStoryV1              = "weather.weather_story.v1"
 	SchemaWeatherAlertV1              = "weather.alert.v1"
 )

standards/wmo.go

@@ -1,5 +1,14 @@
 package standards
 
+// This file provides small, shared helper functions for reasoning about WMO codes.
+// These are intentionally "coarse" categories that are useful for business logic,
+// dashboards, and alerting decisions.
+//
+// Example uses:
+// - jogging suitability: precipitation? thunderstorm? freezing precip?
+// - quick glance: "is it cloudy?" "is there any precip?"
+// - downstream normalizers / aggregators
+
 import (
 	"fmt"
 
@@ -12,7 +21,7 @@ type WMODescription struct {
 }
 
 // WMODescriptions is the canonical internal mapping of WMO code -> day/night text.
-// These are used to populate model.WeatherObservation.ConditionText.
+// These are used to populate canonical text fields derived from WMO codes.
 var WMODescriptions = map[model.WMOCode]WMODescription{
 	0:  {Day: "Sunny", Night: "Clear"},
 	1:  {Day: "Mainly Sunny", Night: "Mainly Clear"},
@@ -47,7 +56,8 @@ var WMODescriptions = map[model.WMOCode]WMODescription{
 // WMOText returns the canonical text description for a WMO code.
 // If isDay is nil, it prefers the Day description (if present).
 //
-// This is intended to be used by drivers after they set ConditionCode.
+// This is intended to be used by drivers after they set ConditionCode when they
+// need a human-readable description.
 func WMOText(code model.WMOCode, isDay *bool) string {
 	if code == model.WMOUnknown {
 		return "Unknown"
@@ -100,3 +110,118 @@ func IsKnownWMO(code model.WMOCode) bool {
 	_, ok := WMODescriptions[code]
 	return ok
 }
+
+func IsThunderstorm(code model.WMOCode) bool {
+	switch code {
+	case 95, 96, 99:
+		return true
+	default:
+		return false
+	}
+}
+
+func IsHail(code model.WMOCode) bool {
+	switch code {
+	case 96, 99:
+		return true
+	default:
+		return false
+	}
+}
+
+func IsFog(code model.WMOCode) bool {
+	switch code {
+	case 45, 48:
+		return true
+	default:
+		return false
+	}
+}
+
+// IsPrecipitation returns true if the code represents any precipitation
+// (drizzle, rain, snow, showers, etc.).
+func IsPrecipitation(code model.WMOCode) bool {
+	switch code {
+	// Drizzle
+	case 51, 53, 55, 56, 57:
+		return true
+
+	// Rain
+	case 61, 63, 65, 66, 67:
+		return true
+
+	// Snow
+	case 71, 73, 75, 77:
+		return true
+
+	// Showers
+	case 80, 81, 82, 85, 86:
+		return true
+
+	// Thunderstorm (often includes rain/hail)
+	case 95, 96, 99:
+		return true
+
+	default:
+		return false
+	}
+}
+
+func IsRainFamily(code model.WMOCode) bool {
+	switch code {
+	// Drizzle + freezing drizzle
+	case 51, 53, 55, 56, 57:
+		return true
+
+	// Rain + freezing rain
+	case 61, 63, 65, 66, 67:
+		return true
+
+	// Rain showers
+	case 80, 81, 82:
+		return true
+
+	// Thunderstorm often implies rain
+	case 95, 96, 99:
+		return true
+
+	default:
+		return false
+	}
+}
+
+func IsSnowFamily(code model.WMOCode) bool {
+	switch code {
+	// Snow and related
+	case 71, 73, 75, 77:
+		return true
+
+	// Snow showers
+	case 85, 86:
+		return true
+
+	default:
+		return false
+	}
+}
+
+// IsFreezingPrecip returns true if the code represents freezing drizzle/rain.
+func IsFreezingPrecip(code model.WMOCode) bool {
+	switch code {
+	case 56, 57, 66, 67:
+		return true
+	default:
+		return false
+	}
+}
+
+// IsSkyOnly returns true for codes that represent "sky condition only"
+// (clear/mostly/partly/cloudy) rather than fog/precip/etc.
+func IsSkyOnly(code model.WMOCode) bool {
+	switch code {
+	case 0, 1, 2, 3:
+		return true
+	default:
+		return false
+	}
+}