diff --git a/README.md b/README.md index a8e039e..954d332 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Markdown reports to a configured `distributor` HTTP upload endpoint. ## Quickstart ```sh -weatherreporter generate daily --date 2026-05-29 --out ./daily.md +weatherreporter generate today --out ./today.md ``` ## Documentation diff --git a/docs/cli.md b/docs/cli.md index 532f205..f4a5ca6 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,14 +6,15 @@ batches, and inspects stored artifacts. ## Shortest Useful Command ```sh -weatherreporter generate daily --date 2026-05-29 --out ./daily.md +weatherreporter generate today --out ./today.md ``` This loads configuration, fetches weather data, writes managed workspace -artifacts, runs `scriptorium render` as a preflight check, runs -`scriptorium run`, and writes an extra Markdown copy to `./daily.md`. If -distributor notification is enabled in configuration, the command also uploads -the managed Markdown report after final metadata is saved. +artifacts, runs `scriptorium render` as a preflight check, runs structured +`scriptorium run`, validates generated text, renders the embedded Today +template, and writes an extra Markdown copy to `./today.md`. If distributor +notification is enabled in configuration, the command also uploads the managed +Markdown report after final metadata is saved. ## Commands @@ -47,6 +48,10 @@ the effective report timezone and does not accept date or event window flags. `generate storm` requires explicit event-window bounds with `--start` and `--end`. +`generate daily` remains the existing Daily Today report. It is separate from +`generate today`; the commands use different report IDs, artifact groups, +prompts, and config override keys. + `run morning` generates Today Report and the 3-Day Outlook, plus Weekend Outlook except on Sunday. `run evening` generates the Tomorrow Report. Batch runs continue independent reports after a failure, print a JSON summary to @@ -85,8 +90,9 @@ are no distributor-specific CLI flags. ## Common Workflows ```sh -weatherreporter generate tomorrow --out ./tomorrow.md weatherreporter generate today --out ./today.md +weatherreporter generate daily --date 2026-05-29 --out ./daily.md +weatherreporter generate tomorrow --out ./tomorrow.md weatherreporter generate hourly weatherreporter generate three-day --out ./three-day.md weatherreporter generate weekend --out ./weekend.md @@ -99,11 +105,12 @@ weatherreporter run evening --out-dir ./reports ```sh weatherreporter inspect reports --limit 10 +weatherreporter inspect metadata 20260529T100000.000000000Z_today +weatherreporter inspect modules 20260529T100000.000000000Z_today +weatherreporter inspect data-package 20260529T100000.000000000Z_today +weatherreporter inspect prior 20260529T100000.000000000Z_today +weatherreporter inspect sources 20260529T100000.000000000Z_today weatherreporter inspect metadata 20260529T100000.000000000Z_daily_today -weatherreporter inspect modules 20260529T100000.000000000Z_daily_today -weatherreporter inspect data-package 20260529T100000.000000000Z_daily_today -weatherreporter inspect prior 20260529T100000.000000000Z_daily_today -weatherreporter inspect sources 20260529T100000.000000000Z_daily_today ``` `inspect reports` lists recent generated runs with artifact paths and source diff --git a/docs/config.md b/docs/config.md index d4d1597..5a27ae7 100644 --- a/docs/config.md +++ b/docs/config.md @@ -181,11 +181,14 @@ snapshot exists and a threshold is crossed. `reports` optionally overrides the ordered deterministic modules declared by report definitions. Omit a report entry to use its default module order. -Supported report keys are `daily`, `tomorrow`, `hourly`, `three_day`, -`weekend`, and `storm`. Canonical report IDs and accepted aliases are also -valid, including `daily_today`, `three_day_outlook`, `weekend_outlook`, and -`storm_report`. Hyphens and underscores are treated equivalently in report -keys. +Supported report keys are `daily`, `today`, `tomorrow`, `hourly`, +`three_day`, `weekend`, and `storm`. Canonical report IDs and accepted aliases +are also valid, including `daily_today`, `three_day_outlook`, +`weekend_outlook`, and `storm_report`. Hyphens and underscores are treated +equivalently in report keys. + +`reports.today` applies only to the Today Report. `reports.daily` and +`reports.daily_today` apply only to the existing Daily Today report. Each report entry supports: @@ -209,6 +212,22 @@ reports: - short_term - spc_convective_discussion - hourly_forecast + today: + deterministic_modules: + - metadata + - current_conditions + - narrative_forecast + - derived_daily_summary + - derived_daypart_summaries + - precip_timing + - alert_digest + - spc_convective_outlooks + - area_forecast_discussion + - spc_convective_discussion + - weather_story + - outdoor_windows + - hourly_forecast + - today_planning hourly: deterministic_modules: - metadata diff --git a/docs/internal/briefing.md b/docs/internal/briefing.md index a6f5c99..ac61019 100644 --- a/docs/internal/briefing.md +++ b/docs/internal/briefing.md @@ -42,6 +42,10 @@ Tomorrow Report supports the Daily-style civil-day modules plus `tomorrow_planning` and `hourly_forecast`; those outputs feed the Tomorrow GeneratedText prompt package and embedded Markdown template. +Today Report supports the Daily-style civil-day modules plus `today_planning` +and `hourly_forecast`; those outputs feed the Today GeneratedText prompt +package and embedded Markdown template. + `today_planning` is a Today-specific deterministic planning stanza with morning readiness, commute/school/workday concerns, outdoor planning, and late-day change-watch fields. It is compatible with `report.Today` only. diff --git a/docs/internal/generatedtext.md b/docs/internal/generatedtext.md index 2030427..936bbc7 100644 --- a/docs/internal/generatedtext.md +++ b/docs/internal/generatedtext.md @@ -9,9 +9,8 @@ This document describes structured generated-text handling in generated-text-template reports and builds curated render contexts for templates. It also owns the generated-text catalog that connects report definitions to validators, render-context builders, schema assets, and template -assets. The implemented contracts are Today, Tomorrow Report, and Hourly -Report. Today support is internal until a report definition references the -`today` schema and template IDs. +assets. The implemented contracts are Today Report, Tomorrow Report, and Hourly +Report. ## Inputs And Outputs @@ -50,7 +49,9 @@ The hourly generated text JSON accepts: JSON when blank. The Today generated text JSON accepts the same public fields and validation -rules as Tomorrow: +rules as Tomorrow. It is selected by the active Today report definition through +schema ID `today`, template ID `today`, and prompt ID +`weather.today_generated_text`: ```json { diff --git a/docs/internal/module.md b/docs/internal/module.md index 753b425..dff9a0a 100644 --- a/docs/internal/module.md +++ b/docs/internal/module.md @@ -48,6 +48,28 @@ 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. +## Today Composition + +The default Today Report module order is: + +1. `metadata` +2. `current_conditions` +3. `narrative_forecast` +4. `derived_daily_summary` +5. `derived_daypart_summaries` +6. `precip_timing` +7. `alert_digest` +8. `spc_convective_outlooks` +9. `area_forecast_discussion` +10. `spc_convective_discussion` +11. `weather_story` +12. `outdoor_windows` +13. `hourly_forecast` +14. `today_planning` + +The embedded Today template uses selected deterministic fields from these +module outputs after GeneratedText validation. + ## Tomorrow Composition The default Tomorrow Report module order is: @@ -70,6 +92,24 @@ The default Tomorrow Report module order is: The embedded Tomorrow template uses selected deterministic fields from these module outputs after GeneratedText validation. +## Today Planning + +`today_planning` emits current-day planning facts for Today Report. Its output +stanza is also named `today_planning`. The module is supported only by Today +Report and depends on daily and daypart summaries for the current local civil +day. + +The output uses the same shape as Tomorrow planning: + +- `morning_readiness` +- `commute` +- `outdoor_planning` +- `things_to_watch` +- `confidence` + +The type is `briefing.TodayPlanningModule`; it is independent from +`briefing.TomorrowPlanningModule`. + ## Hourly Composition The default Hourly Report module order is: diff --git a/docs/internal/prompt-input.md b/docs/internal/prompt-input.md index 2631576..4421ee5 100644 --- a/docs/internal/prompt-input.md +++ b/docs/internal/prompt-input.md @@ -68,9 +68,9 @@ Prompt-facing module intervals use local `period_begins` and `period_ends` labels; canonical report metadata and source timestamps remain structured timestamps where applicable. -Tomorrow Report and Hourly Report module snapshots use the same package schema -and categories when converted into prompt input. The default hourly module list -places +Today Report, Tomorrow Report, and Hourly Report module snapshots use the same +package schema and categories when converted into prompt input. The default +hourly module list places `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 @@ -78,9 +78,10 @@ include civil-day summary stanzas. Generated-text and render context artifacts are produced later in app orchestration and are not part of the YAML data package. -The default Tomorrow module list includes civil-day summary stanzas, -`tomorrow_planning`, and `hourly_forecast` in the data package before -structured GeneratedText is requested from Scriptorium. +The default Today and Tomorrow module lists include civil-day summary stanzas, +planning stanzas, and `hourly_forecast` in the data package before structured +GeneratedText is requested from Scriptorium. Today uses `today_planning`; +Tomorrow uses `tomorrow_planning`. Current categories are: diff --git a/docs/internal/report-registry.md b/docs/internal/report-registry.md index acdd19a..02baeae 100644 --- a/docs/internal/report-registry.md +++ b/docs/internal/report-registry.md @@ -33,6 +33,10 @@ The generate command names are `daily`, `today`, `tomorrow`, `hourly`, legacy descriptive aliases such as `daily_today`, `three_day_outlook`, `weekend_outlook`, and `storm_report`. +`daily` resolves to the existing Daily Today report ID `daily_today`. +`today` resolves to the independent Today report ID `today`. `reports.today` +is not an alias for `reports.daily` or `reports.daily_today`. + Markdown report definitions use the `scriptorium_markdown` generation mode. Their template and structured-text schema identifiers are empty. Today Report, Tomorrow Report, and Hourly Report declare `generated_text_template`; the app @@ -88,7 +92,7 @@ report override keys. The app supplies `weather_api.timezone` as a loaded `time.Location`. Batch output path copying uses batch output names from report definitions. Report module overrides can use short keys such as `today`, `tomorrow`, and `hourly`, -canonical report IDs such as `daily_today`, or accepted aliases such as +canonical report IDs such as `daily_today`, or descriptive names such as `three_day_outlook`. ## Batch Membership diff --git a/docs/internal/reporttemplate.md b/docs/internal/reporttemplate.md index 00766ee..afd5406 100644 --- a/docs/internal/reporttemplate.md +++ b/docs/internal/reporttemplate.md @@ -6,9 +6,8 @@ in `internal/reporttemplate`. ## Purpose `internal/reporttemplate` owns repository-native report templates and companion -GeneratedText JSON schemas. The implemented template contracts are Today, -Tomorrow Report, and Hourly Report. Today assets are available internally until -a report definition selects them. +GeneratedText JSON schemas. The implemented template contracts are Today +Report, Tomorrow Report, and Hourly Report. The package embeds assets from: @@ -36,6 +35,10 @@ The implemented template IDs are `today`, `tomorrow`, and `hourly`. The implemented schema IDs are also `today`, `tomorrow`, and `hourly`, backed by matching `*.generated_text.schema.json` files. +The Today generated-text prompt source is +`internal/reporttemplate/prompts/today.generated_text.md`, selected by prompt +ID `weather.today_generated_text`. + ## Boundaries This package owns embedded asset lookup, Go template parsing, and Markdown diff --git a/docs/operations.md b/docs/operations.md index d1c106d..eb159e3 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -10,6 +10,7 @@ Generation commands: ```text weatherreporter generate daily --date 2026-05-29 +weatherreporter generate today weatherreporter generate tomorrow weatherreporter generate hourly weatherreporter generate three-day @@ -23,12 +24,16 @@ a JSON module snapshot, build a YAML prompt input data package, run workspace. Markdown-path reports then run `scriptorium run` directly to the managed Markdown report path. -`generate tomorrow` and `generate hourly` use the generated-text-template -workflow. They run structured `scriptorium run` to raw GeneratedText JSON, -validate the structured text, save a render context, and render the managed -Markdown report from embedded templates. `generate hourly` covers the six-hour -rolling period from generation time in the effective report timezone and is not -part of scheduled morning or evening batches. +`generate today`, `generate tomorrow`, and `generate hourly` use the +generated-text-template workflow. They run structured `scriptorium run` to raw +GeneratedText JSON, validate the structured text, save a render context, and +render the managed Markdown report from embedded templates. `generate today` +covers the selected or current local civil day. `generate hourly` covers the +six-hour rolling period from generation time in the effective report timezone +and is not part of scheduled morning or evening batches. + +`generate daily` remains the existing Daily Today report and is independent of +`generate today`. When distributor notification is enabled, weatherreporter uploads the managed Markdown report after report rendering succeeds and final metadata is saved. @@ -42,14 +47,14 @@ weatherreporter run morning weatherreporter run evening ``` -`run morning` generates Daily Today and the 3-Day Outlook, plus Weekend Outlook +`run morning` generates Today Report and the 3-Day Outlook, plus Weekend Outlook except on Sunday. `run evening` generates the Tomorrow Report. Batch commands print a JSON summary to stdout, write compact per-report status lines to stderr, continue independent reports after one report fails, and return nonzero when any report failed. When notification is configured, the summary and status lines include notification status, accepted distributor run ID, or notification error fields for each attempted report. `--out-dir PATH` writes -extra Markdown copies using report default filenames such as `daily.md`, +extra Markdown copies using report default filenames such as `today.md`, `three-day.md`, `weekend.md`, and `tomorrow.md`; these copies are not used as distributor upload sources. @@ -64,6 +69,14 @@ workspace/ YYYY-MM-DD/ .modules.json .metadata.json + today/ + YYYY-MM-DD/ + .modules.json + .metadata.json + .generated_text.raw.json + .generated_text.run.json + .generated_text.json + .render_context.json three-day/ YYYY-MM-DD/ .modules.json @@ -96,6 +109,9 @@ workspace/ daily/ YYYY-MM-DD/ .data_package.yaml + today/ + YYYY-MM-DD/ + .data_package.yaml three-day/ YYYY-MM-DD/ .data_package.yaml @@ -115,6 +131,9 @@ workspace/ daily/ YYYY-MM-DD/ .render.json + today/ + YYYY-MM-DD/ + .render.json three-day/ YYYY-MM-DD/ .render.json @@ -134,6 +153,9 @@ workspace/ daily/ YYYY-MM-DD/ .distributor.json + today/ + YYYY-MM-DD/ + .distributor.json three-day/ YYYY-MM-DD/ .distributor.json @@ -152,6 +174,8 @@ workspace/ reports/ daily/ .md + today/ + .md three-day/ .md weekend/ @@ -173,6 +197,7 @@ RunIDs are based on generation time plus report ID: ```text 20260529T100000.123456789Z_daily_today +20260529T100000.123456789Z_today ``` Each generated report writes metadata that links: @@ -214,6 +239,8 @@ The default idempotency key appends RunID to the rendered bundle ID so each report generation has a distinct retry identity. The default bundle path uses the valid-period start date, artifact group, and RunID. Distributor owns destination merge, retention, and derived snapshot behavior such as `latest`. +For Today, the default report ID and artifact group values are both `today`, +and the batch output filename value is `today.md`. Notification happens after final metadata save for generated reports. Weather API, module snapshot, data-package, render preflight, Scriptorium run, @@ -267,11 +294,12 @@ Recent Changes are computed from structured module snapshots, not rendered Markdown or YAML text. Daily Today compares with prior Daily Today snapshots for the same valid local -date. Tomorrow Report compares with prior Tomorrow Report snapshots for 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. Hourly Report and -Storm Report leave Recent Changes empty. +date. Today Report compares with prior Today Report snapshots for the same +valid local date. Tomorrow Report compares with prior Tomorrow Report snapshots +for 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. Hourly Report +and Storm Report leave Recent Changes empty. When no prior comparable snapshot exists, or no configured threshold is crossed, `recentChanges.items` is empty. @@ -284,10 +312,10 @@ A failed generation run may still leave useful artifacts: preflight JSON and metadata are written for inspection. - If `scriptorium run` exits nonzero after writing a report, the managed report and metadata remain available. -- Hourly generated-text failures preserve available intermediate artifacts, - such as the structured run result, raw generated-text JSON, validated - generated text, and render context. Metadata links those paths when it can be - safely written. +- Generated-text failures for Today, Tomorrow, and Hourly reports preserve + available intermediate artifacts, such as the structured run result, raw + generated-text JSON, validated generated text, and render context. Metadata + links those paths when it can be safely written. - If distributor notification fails, report artifacts and final metadata remain available, but the report or batch command returns nonzero. - For batch commands, inspect the stdout JSON summary first, then inspect the diff --git a/docs/templates.md b/docs/templates.md index cf80341..c8f813d 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -130,6 +130,9 @@ Today generated text uses `.GeneratedText.Summary`, `.GeneratedText.Confidence`. Forecast discussion is a slice of paragraphs and should be rendered with `range`. +Today uses template ID `today`, generated-text schema ID `today`, and prompt +source `internal/reporttemplate/prompts/today.generated_text.md`. + Today modules include the Hourly module fields plus: | Variable | Type | Description | diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 47e2776..489c057 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -187,7 +187,7 @@ Relevant docs: [Operations guide](operations.md), ## Generated Text Validation Fails -Symptom: Tomorrow or Hourly generation fails with generated-text decode, +Symptom: Today, Tomorrow, or Hourly generation fails with generated-text decode, unknown-field, required-field, or multiple-JSON-values context. Likely cause: Scriptorium wrote structured JSON that does not match the @@ -210,7 +210,7 @@ Relevant docs: [Operations guide](operations.md), ## Template Rendering Fails -Symptom: Tomorrow or Hourly generation fails with report template parsing or +Symptom: Today, Tomorrow, or Hourly generation fails with report template parsing or execution context after generated text validation succeeds. Likely cause: an embedded template references a missing context field or diff --git a/examples/config.yml b/examples/config.yml index 226a7c9..14cbdee 100644 --- a/examples/config.yml +++ b/examples/config.yml @@ -89,6 +89,28 @@ reports: - weather_story - outdoor_windows - hourly_forecast + today: + deterministic_modules: + - metadata + - current_conditions + - narrative_forecast + - derived_daily_summary + - derived_daypart_summaries + - precip_timing + - alert_digest + - spc_convective_outlooks + - id: area_forecast_discussion + options: + sections: + - product + - key_messages + - short_term + - long_term + - spc_convective_discussion + - weather_story + - outdoor_windows + - hourly_forecast + - today_planning hourly: deterministic_modules: - metadata