diff --git a/docs/cli.md b/docs/cli.md index 177cc74..cb139a9 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -39,9 +39,10 @@ weatherreporter inspect sources [--config PATH] RUN_ID artifact, managed Markdown report, and metadata under the configured workspace. `--out` writes an extra Markdown copy for the operator; distributor notification uses the managed report path, not the extra copy. `generate -near-term` uses the current generation time and does not accept date or event -window flags. `generate storm` requires explicit event-window bounds with -`--start` and `--end`. +near-term` uses the current generation time, covers the next six hours in the +effective report timezone, and does not accept date or event window flags. +`generate storm` requires explicit event-window bounds with `--start` and +`--end`. `run morning` generates Daily Today and the 3-Day Outlook, plus Weekend Outlook except on Sunday. `run evening` generates the Tomorrow Planning Brief. Batch @@ -53,6 +54,9 @@ notification is enabled, batch summaries and status lines include notification status, accepted distributor run ID, or notification error fields for each attempted report. +Near-Term Report generation is explicit only; it is not included in `run +morning` or `run evening`. + `inspect` commands read existing workspace artifacts and emit JSON to stdout. They do not fetch weather data or invoke `scriptorium`. diff --git a/docs/config.md b/docs/config.md index 0cc0122..406063a 100644 --- a/docs/config.md +++ b/docs/config.md @@ -183,7 +183,8 @@ report definitions. Omit a report entry to use its default module order. Supported report keys are `daily`, `tomorrow`, `near_term`, `near-term`, `three_day`, `weekend`, and `storm`. Canonical report IDs such as -`daily_today` and `daily_tomorrow` are also accepted. +`daily_today` and `daily_tomorrow` are also accepted. `near_term` and +`near-term` are aliases for the same Near-Term Report override. Each report entry supports: diff --git a/docs/internal/briefing.md b/docs/internal/briefing.md index bd886ad..e19d425 100644 --- a/docs/internal/briefing.md +++ b/docs/internal/briefing.md @@ -38,6 +38,14 @@ Outputs: Every registered composition entry has a builder. Unknown or unimplemented module IDs fail validation instead of being skipped. +Near-Term Report supports source and valid-period modules that operate over its +rolling six-hour period: `metadata`, `current_conditions`, `hourly_forecast`, +`precip_timing`, `alert_digest`, `spc_convective_outlooks`, +`area_forecast_discussion`, `spc_convective_discussion`, and `weather_story`. +It does not support daily/daypart-only modules such as +`derived_daily_summary`, `derived_daypart_summaries`, `outdoor_windows`, or +`tomorrow_planning`. + Prompt-facing module values use local, human-readable date and time labels where the LLM is expected to reason about report content. Canonical timestamps remain in report metadata, source provenance, and integration artifacts. @@ -59,7 +67,8 @@ builders run. Configured `location` values are prompt context only; Weather API `sourceLocationId` and `sourceLocation` remain source provenance. `area_forecast_discussion` uses optional `sections` configuration to include a -subset of discussion fields. +subset of discussion fields. Near-Term Report defaults this module to +`key_messages` and `short_term`. `spc_convective_outlooks` uses collected SPC run metadata and derived report-period outlooks. It emits `checked: true` for a successfully fetched diff --git a/docs/internal/facts.md b/docs/internal/facts.md index 91d3fe6..33bbfe9 100644 --- a/docs/internal/facts.md +++ b/docs/internal/facts.md @@ -27,6 +27,12 @@ Outputs: report-period SPC convective outlooks and discussions, daily summaries, daypart summaries, and Storm Report window summary +Near-Term Report uses the generic valid-period hourly and narrative selection +for its rolling six-hour window. Its derived facts include precipitation timing +from the selected hourly periods, alert overlaps for the six-hour period, and +SPC outlooks/discussions overlapping that period. It does not build daily +summaries, daypart summaries, or a storm-window summary. + ## Boundaries - This package owns fact assembly and reusable deterministic derivation for a @@ -62,6 +68,8 @@ and inspection. - Invalid timezone names return an error. - Missing required hourly forecast data returns the underlying forecast derivation error for reports that require daily summaries. +- Near-Term Report can derive its default module facts without daily or + daypart summaries. - Missing optional narrative, alert, discussion, daily, or weather story data produces empty or nil derived fields. - Missing optional SPC convective outlook data produces a nil collected field. diff --git a/docs/internal/module.md b/docs/internal/module.md index ef6a5f4..7f061b9 100644 --- a/docs/internal/module.md +++ b/docs/internal/module.md @@ -47,6 +47,24 @@ The registry recognizes these IDs: Every registered module has a builder. Report composition entries that refer to unknown or unimplemented module IDs fail validation instead of being skipped. +## Near-Term Composition + +The default Near-Term Report module order is: + +1. `metadata` +2. `current_conditions` +3. `hourly_forecast` +4. `precip_timing` +5. `alert_digest` +6. `spc_convective_outlooks` +7. `area_forecast_discussion` +8. `spc_convective_discussion` +9. `weather_story` + +Near-Term Report does not include daily or daypart summary modules by default. +Its `area_forecast_discussion` item is configured to include only +`key_messages` and `short_term`. + ## Options Most modules use an empty options struct, including diff --git a/docs/internal/prompt-input.md b/docs/internal/prompt-input.md index d996aaa..9173b63 100644 --- a/docs/internal/prompt-input.md +++ b/docs/internal/prompt-input.md @@ -68,6 +68,12 @@ Prompt-facing module intervals use local `period_begins` and `period_ends` labels; canonical report metadata and source timestamps remain structured timestamps where applicable. +Near-Term Report uses the same package schema and categories. Its default +package includes `precip_timing` under `derived_summaries`, alert and SPC +outlooks under `applicable_risk_products`, AFD/SPC discussion/weather story +under `narrative_products`, and current/hourly data under `raw_data`. It does +not include daily or daypart summary stanzas. + Current categories are: - `applicable_risk_products`: location-applicable alerts, warnings, outlooks, @@ -106,6 +112,7 @@ None. ## Skip And Resume Behavior None. Recent Changes is always present as an `items` list and may be empty. +Near-Term Report currently writes an empty `items` list. ## Failure Behavior diff --git a/docs/internal/report-registry.md b/docs/internal/report-registry.md index aef7c1f..6405a3b 100644 --- a/docs/internal/report-registry.md +++ b/docs/internal/report-registry.md @@ -31,6 +31,7 @@ Each report definition declares: | --- | --- | --- | --- | --- | --- | | Daily Today | `daily_today` | `weather.daily_report` | `daily` | `daily.md` | Daily Today, Daily Tomorrow | | Daily Tomorrow | `daily_tomorrow` | `weather.daily_report` | `daily` | `tomorrow.md` | Daily Today, Daily Tomorrow | +| Near-Term Report | `near_term` | `weather.near_term_report` | `near-term` | `near-term.md` | Near-Term Report | | 3-Day Outlook | `three_day` | `weather.three_day_outlook` | `three-day` | `three-day.md` | 3-Day Outlook | | Weekend Outlook | `weekend` | `weather.weekend_outlook` | `weekend` | `weekend.md` | Weekend Outlook | | Storm Report | `storm` | `weather.storm_report` | `storm` | `storm.md` | Storm Report | @@ -42,6 +43,9 @@ All report definitions are eligible for generation. - Daily Today covers the selected local civil day, or the current local civil day when no date override is supplied. - Daily Tomorrow covers the next local civil day from generation time. +- Near-Term Report covers the half-open six-hour period from generation time in + the effective report timezone. The duration is an internal report constant, + not a configuration field. - 3-Day Outlook covers the interval from generation time through local midnight three days later. - Weekend Outlook covers the upcoming weekend window and is not scheduled for @@ -64,7 +68,15 @@ IDs, then uses the registry for report policy. ## Config Fields Used The app supplies `weather_api.timezone` as a loaded `time.Location`. Batch -output path copying uses batch output names from report definitions. +output path copying uses batch output names from report definitions. Report +module overrides can use the `near_term` or `near-term` keys for Near-Term +Report. + +## Batch Membership + +Morning batches include Daily Today, 3-Day Outlook, and Weekend Outlook except +on Sunday. Evening batches include Daily Tomorrow. Near-Term Report is not part +of a scheduled batch. ## State And App Usage diff --git a/docs/operations.md b/docs/operations.md index 96665e2..5b2f172 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -11,6 +11,7 @@ Generation commands: ```text weatherreporter generate daily --date 2026-05-29 weatherreporter generate tomorrow +weatherreporter generate near-term weatherreporter generate three-day weatherreporter generate weekend weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 @@ -25,6 +26,10 @@ Markdown report after `scriptorium run` succeeds and final metadata is saved. `--out PATH` writes an extra Markdown copy for the current generated report; it is not used as the distributor upload source. +`generate near-term` is an explicit generation command. It covers the six-hour +rolling period from generation time in the effective report timezone and is not +part of scheduled morning or evening batches. + Batch commands: ```text @@ -62,6 +67,10 @@ workspace/ YYYY-MM-DD/ .modules.json .metadata.json + near-term/ + YYYY-MM-DD/ + .modules.json + .metadata.json storm/ YYYY-MM-DD/ .modules.json @@ -76,6 +85,9 @@ workspace/ weekend/ YYYY-MM-DD/ .data_package.yaml + near-term/ + YYYY-MM-DD/ + .data_package.yaml storm/ YYYY-MM-DD/ .data_package.yaml @@ -89,6 +101,9 @@ workspace/ weekend/ YYYY-MM-DD/ .render.json + near-term/ + YYYY-MM-DD/ + .render.json storm/ YYYY-MM-DD/ .render.json @@ -102,6 +117,9 @@ workspace/ weekend/ YYYY-MM-DD/ .distributor.json + near-term/ + YYYY-MM-DD/ + .distributor.json storm/ YYYY-MM-DD/ .distributor.json @@ -112,6 +130,8 @@ workspace/ .md weekend/ .md + near-term/ + .md storm/ .md ``` @@ -218,8 +238,8 @@ Markdown or YAML text. Daily Today and Daily Tomorrow can compare with each other when they cover the same valid local date. 3-Day Outlook compares with prior compatible 3-Day snapshots for the same valid local date. Weekend Outlook compares with prior -compatible Weekend snapshots for the same weekend window. Storm Report leaves -Recent Changes empty. +compatible Weekend snapshots for the same weekend window. Near-Term Report and +Storm Report leave Recent Changes empty. When no prior comparable snapshot exists, or no configured threshold is crossed, `recentChanges.items` is empty.