Harden PromptKit upgrade integration

.gitignore

@@ -1,6 +1,5 @@
-# Compiled application binary and testing workspace
+# Compiled application binary
 /weatherreporter
-/workspace
 
 # ---> Go
 # If you prefer the allow list template instead of the deny list, see community template:

.woodpecker/release.yml

@@ -2,8 +2,50 @@ when:
   - event: tag
 
 steps:
+  - name: validate-release
+    image: golang:1.26.5
+    commands:
+      - |
+        set -eu
+
+        version="$CI_COMMIT_TAG"
+        release_note="docs/releases/$version.md"
+
+        if ! printf '%s\n' "$version" |
+          grep -Eq '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'
+        then
+          printf '%s\n' "invalid release tag: $version" >&2
+          exit 1
+        fi
+        test -s "$release_note"
+        test -z "$(git ls-files go.work go.work.sum)"
+        test ! -e vendor
+        if grep -Eq '^[[:space:]]*replace([[:space:]]|\()' go.mod
+        then
+          printf '%s\n' 'go.mod contains a replacement' >&2
+          exit 1
+        fi
+
+        GOWORK=off go test -count=1 ./...
+        GOWORK=off go test -race -count=1 ./...
+        GOWORK=off go vet ./...
+        GOWORK=off go build ./...
+        GOWORK=off go mod tidy -diff
+
+        unformatted=$(
+          git ls-files '*.go' |
+            while IFS= read -r go_file
+            do
+              gofmt -l "$go_file"
+            done
+        )
+        test -z "$unformatted"
+        git diff --check
+
   - name: build-release-assets
-    image: golang:1.25
+    image: golang:1.26.5
+    depends_on:
+      - validate-release
     commands:
       - |
         set -eu
@@ -33,8 +75,11 @@ steps:
         build_binary windows amd64 ".exe"
         build_binary windows arm64 ".exe"
 
+        host_binary="$dist/weatherreporter-$version-$(go env GOOS)-$(go env GOARCH)"
+        test "$("$host_binary" --version)" = "weatherreporter $version"
+
   - name: publish-release
-    image: woodpeckerci/plugin-release
+    image: woodpeckerci/plugin-release:0.3.1
     depends_on:
       - build-release-assets
     settings:
@@ -42,6 +87,8 @@ steps:
         from_secret: GITEA_RELEASE_TOKEN
       files:
         - dist/weatherreporter-*
+      title: Weatherreporter ${CI_COMMIT_TAG}
+      note: docs/releases/${CI_COMMIT_TAG}.md
       checksum: sha256
       checksum-file: SHA256SUMS
       checksum-flatten: true

README.md

@@ -1,25 +1,31 @@
 # weatherreporter
 
-Weatherreporter is a Go CLI that turns normalized weather data into managed,
+Weatherreporter is a Go CLI that turns normalized weather data into
 human-facing Markdown reports.
 
-It provides repeatable reports with inspectable local artifacts, so operators
+It produces a Markdown report at an operator-owned destination and can upload
-can review what was collected and generated for every run.
+the completed output through Distributor. It can also compare explicitly
+selected Promptkit profiles against one shared prepared report and publish a
+local comparison bundle.
 
 ## Quickstart
 
 ```sh
-weatherreporter generate today --out ./today.md
+weatherreporter generate today
 ```
 
 Configure a Weather API endpoint first; see the
-[configuration reference](docs/config.md).
+[configuration reference](docs/config.md). The report is written to
+`today.md` in the current directory when `output.directory` is not configured.
+Set that configuration value for an ordinary publication directory, or use
+`--out` for one command. See the [CLI reference](docs/cli.md) and [operations
+guide](docs/operations.md) for command and operating details.
 
 ## Documentation
 
 - [CLI reference](docs/cli.md)
 - [Configuration reference](docs/config.md)
 - [Operations guide](docs/operations.md)
-- [Troubleshooting](docs/troubleshooting.md)
+- [Comparison bundle contract](docs/integrations/comparison-bundle.md)
 - [Development guide](docs/development.md)
 - [Architecture policy](docs/policy/architecture.md)

cmd/weatherreporter/main.go

@@ -3,14 +3,29 @@ package main
 import (
 	"context"
 	"fmt"
+	"io"
 	"os"
+	"os/signal"
+	"syscall"
 
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/cli"
 )
 
 func main() {
-	if err := cli.Run(context.Background(), os.Args[1:], os.Stdout, os.Stderr); err != nil {
+	if err := runCommand(os.Args[1:], os.Stdout, os.Stderr, cli.Run); err != nil {
 		fmt.Fprintf(os.Stderr, "weatherreporter: %v\n", err)
 		os.Exit(1)
 	}
 }
+
+func runCommand(args []string, stdout, stderr io.Writer, runner func(context.Context, []string, io.Writer, io.Writer) error) error {
+	return runCommandWithSignalContext(args, stdout, stderr, runner, signal.NotifyContext)
+}
+
+type signalContextFunc func(context.Context, ...os.Signal) (context.Context, context.CancelFunc)
+
+func runCommandWithSignalContext(args []string, stdout, stderr io.Writer, runner func(context.Context, []string, io.Writer, io.Writer) error, signalContext signalContextFunc) error {
+	ctx, stop := signalContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	return runner(ctx, args, stdout, stderr)
+}

cmd/weatherreporter/main_test.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"syscall"
+	"testing"
+)
+
+func TestRunCommandBuildsCancelableSignalContext(t *testing.T) {
+	var signals []os.Signal
+	stopped := false
+	signalContext := func(parent context.Context, requested ...os.Signal) (context.Context, context.CancelFunc) {
+		signals = append([]os.Signal(nil), requested...)
+		ctx, cancel := context.WithCancel(parent)
+		cancel()
+		return ctx, func() {
+			stopped = true
+		}
+	}
+
+	err := runCommandWithSignalContext(nil, io.Discard, io.Discard, func(ctx context.Context, _ []string, _, _ io.Writer) error {
+		return ctx.Err()
+	}, signalContext)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("runCommandWithSignalContext() error = %v, want context cancellation", err)
+	}
+	if len(signals) != 2 || signals[0] != os.Interrupt || signals[1] != syscall.SIGTERM {
+		t.Fatalf("requested signals = %#v, want Interrupt and SIGTERM", signals)
+	}
+	if !stopped {
+		t.Fatal("signal context stop function was not called")
+	}
+}

cmd/weatherreporter/main_unix_test.go

@@ -0,0 +1,58 @@
+//go:build unix
+
+package main
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"syscall"
+	"testing"
+	"time"
+)
+
+func TestRunCommandCancelsActionContextOnSignal(t *testing.T) {
+	for _, tt := range []struct {
+		name   string
+		signal os.Signal
+	}{
+		{name: "Interrupt", signal: os.Interrupt},
+		{name: "Terminate", signal: syscall.SIGTERM},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			started := make(chan struct{})
+			done := make(chan error, 1)
+			go func() {
+				done <- runCommand(nil, io.Discard, io.Discard, func(ctx context.Context, _ []string, _, _ io.Writer) error {
+					close(started)
+					<-ctx.Done()
+					return ctx.Err()
+				})
+			}()
+
+			select {
+			case <-started:
+			case <-time.After(time.Second):
+				t.Fatal("runner did not receive an action context")
+			}
+
+			process, err := os.FindProcess(os.Getpid())
+			if err != nil {
+				t.Fatalf("FindProcess() error = %v", err)
+			}
+			if err := process.Signal(tt.signal); err != nil {
+				t.Fatalf("Signal(%v) error = %v", tt.signal, err)
+			}
+
+			select {
+			case err := <-done:
+				if !errors.Is(err, context.Canceled) {
+					t.Fatalf("runCommand() error = %v, want context cancellation", err)
+				}
+			case <-time.After(time.Second):
+				t.Fatal("interrupt did not cancel the action context")
+			}
+		})
+	}
+}

docs/adr/0001-stateless-execution.md

@@ -0,0 +1,100 @@
+# 0001: Make Weatherreporter Execution Stateless
+
+Status: Accepted
+
+Date: 2026-08-01
+
+## Context
+
+Weather reports are ephemeral products. Forecasts and current conditions change
+continuously, so the useful response to an old, failed, or superseded report is
+normally a new generation rather than replaying or inspecting a prior run.
+
+The existing run-addressed workspace retains module snapshots, prompt inputs,
+execution receipts, generated text, rendered reports, metadata, and
+notification receipts. That provenance store accumulates operational history
+whose recovery and compatibility obligations are disproportionate to the value
+of an ephemeral weather report. It also exists solely to support local Recent
+Changes comparison for a rarely used report section.
+
+The temporary roadmap that defined the feature scope and implementation plan
+has been retired under the repository's documentation lifecycle. The
+[architecture policy](../policy/architecture.md) defines the resulting system
+invariants; this decision records their durable rationale.
+
+## Decision
+
+Weatherreporter will operate as a stateless transformation pipeline:
+
+```text
+Weather API input
+  -> deterministic facts and modules
+  -> Promptkit data package and generated text
+  -> repository-owned Markdown rendering
+  -> operator-owned report output
+  -> optional Distributor upload
+```
+
+Ordinary invocations will retain intermediate values only for the active
+process and will publish one operator-owned Markdown output atomically. A
+failed or canceled generation must not truncate or partially replace an
+existing selected output. Single-report Distributor notification follows
+successful publication; batch notification follows successful publication of
+every planned report.
+
+Weatherreporter will remove local Recent Changes comparison instead of
+retaining application state to support it. It will remove run-addressed
+workspace artifacts, historical inspection, and backward-compatible workspace
+decoding. RunIDs may remain active correlation and Distributor idempotency
+values, but will not identify retained application history.
+
+Explicit `--llm-debug-dir` capture remains the sole diagnostic-file exception.
+The operator selects and manages that secure location; ordinary execution does
+not create an implicit debug location or a general logging store, and debug
+capture must continue to exclude credentials.
+
+Any future forecast comparison must use a structured product supplied by the
+Weather API rather than local Weatherreporter history. The proposed
+[Upstream Forecast Change Product](../roadmap/future.md#upstream-forecast-change-product)
+defines the required upstream direction. A future integration must not add a
+local snapshot fallback.
+
+## Alternatives Considered
+
+### Retain The Bounded Current-State Design
+
+Retaining a managed workspace with current metadata, receipts, and snapshots
+would preserve inspection and local comparison, but keeps an application-owned
+history subsystem, artifact compatibility burden, and recovery surface that do
+not match the report lifecycle.
+
+### Time-Based Retention
+
+Expiring workspace material after a fixed period reduces accumulation but still
+requires retention policy, cleanup behavior, failure handling, and historical
+format support. It does not remove the mismatch between retained provenance and
+ephemeral report products.
+
+### Bounded Run History
+
+Keeping only a fixed number of prior runs limits storage volume but still makes
+Weatherreporter responsible for run selection, comparison, inspection, and
+state migration. It also creates arbitrary history gaps without establishing an
+authoritative forecast baseline.
+
+## Consequences
+
+The CLI, configuration, prompt-input, workspace, and inspection contracts will
+change together. Legacy workspace material will not be migrated, decoded, or
+automatically deleted; operators remain responsible for any desired cleanup.
+
+Current action results will carry active identity, selected profile, safe
+effective model information, output location, notification result, and safe
+errors instead of historical artifact paths. Tests will protect atomic output,
+batch and notification ordering, explicit secure debug capture, and the
+absence of ordinary application-managed state.
+
+This decision deliberately leaves the Weather API responsible for any future
+forecast-history comparison. It avoids a cache, archive, retention engine,
+manifest, resume mechanism, or replacement inspection surface in
+Weatherreporter.

docs/cli.md

@@ -1,123 +1,193 @@
 # Weatherreporter CLI
 
-`weatherreporter` generates weather reports, runs report batches, and inspects
+`weatherreporter` generates Markdown weather reports, runs report batches, and
-artifacts already stored in its workspace.
+compares explicitly selected Promptkit profiles against one prepared report. It
+has no command for inspecting prior runs or application-owned state.
 
 ## Shortest Useful Command
 
 ```sh
-weatherreporter generate today --out ./today.md
+weatherreporter generate today
 ```
 
-The command uses the configured Weather API and writes an extra Markdown copy
+The command uses the configured Weather API and atomically writes `today.md`.
-at `./today.md`. See the [configuration reference](config.md) to supply the
+With no configured output directory, it writes in the current directory. See
-required Weather API endpoint.
+the [configuration reference](config.md) to supply the required Weather API
+endpoint and choose an ordinary output directory.
 
 ## Commands And Usage
 
 ```text
 weatherreporter --help
-weatherreporter generate daily --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter --version
-weatherreporter generate today [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD] [--quiet]
+weatherreporter generate daily --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--llm-debug-dir PATH] [--quiet]
-weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter generate today [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD] [--llm-debug-dir PATH] [--quiet]
-weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--llm-debug-dir PATH] [--quiet]
-weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--llm-debug-dir PATH] [--quiet]
-weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--llm-debug-dir PATH] [--quiet]
-weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet] --start TIME --end TIME
+weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--llm-debug-dir PATH] [--quiet]
-weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
+weatherreporter compare REPORT --profile PROFILE --profile PROFILE [--config PATH] [--units VALUE] [--tz NAME] [--date YYYY-MM-DD] [--out-dir PATH] [--replace] [--llm-debug-dir PATH] [--quiet]
-weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
-weatherreporter inspect reports [--config PATH] [--limit N]
-weatherreporter inspect metadata [--config PATH] RUN_ID
-weatherreporter inspect modules [--config PATH] RUN_ID
-weatherreporter inspect data-package [--config PATH] RUN_ID
-weatherreporter inspect prior [--config PATH] RUN_ID
-weatherreporter inspect sources [--config PATH] RUN_ID
 ```
 
+`weatherreporter --version` prints the version embedded in the executable.
+Tagged release binaries report their semantic version tag; ordinary local
+builds report `development`.
+
 | Command | Contract |
 | --- | --- |
-| `generate daily` | Requires `--date YYYY-MM-DD`; the date is interpreted in the effective report timezone. |
+| `generate daily` | Requires `--date YYYY-MM-DD`; the date is interpreted in the effective report timezone. Its default filename is `daily-YYYY-MM-DD.md`. |
-| `generate today` | Accepts an optional `--date YYYY-MM-DD`; without it, the current local date in the effective report timezone is used. |
+| `generate today` | Accepts an optional `--date YYYY-MM-DD`; without it, the current local date in the effective report timezone is used. Its default filename is `today.md`. |
-| `generate tomorrow`, `three-day`, `weekend` | Use their report-defined valid period and accept the common generate flags. |
+| `generate tomorrow` | Uses the next local civil day and writes `tomorrow.md` by default. |
-| `generate hourly` | Covers the next six hours in the effective report timezone. It does not accept `--date`, `--start`, `--end`, `--hours`, or `--duration`. |
+| `generate hourly` | Covers the next six hours in the effective report timezone and writes `hourly.md` by default. It does not accept `--date`, `--hours`, or `--duration`. |
-| `generate storm` | Requires both `--start TIME` and `--end TIME`. Each time may be `YYYY-MM-DDTHH:MM` in the effective timezone or an RFC3339 timestamp with an explicit offset. |
+| `run morning` and `run evening` | Run their defined report batches beneath the configured output directory, or the current directory when none is configured. `--out-dir` selects another directory. `--out` is not accepted. |
-| `run morning` and `run evening` | Run their defined report batches. `--out-dir` writes extra Markdown copies; `--out` is not accepted. |
+| `compare REPORT` | Accepts `daily`, `today`, `tomorrow`, or `hourly`. It requires at least two distinct, nonblank `--profile` values in their supplied order. Daily requires `--date`; Today accepts it optionally; Tomorrow and Hourly do not accept it. |
 
-`generate` accepts all seven report command names shown above. `run` accepts
+`generate` accepts the four report command names shown above. `run` accepts
-only `morning` and `evening`. Batch membership, workspace artifacts, and
+only `morning` and `evening`. `compare` always requires explicit profile
-notification sequencing are described in the [operations guide](operations.md).
+selection: `promptkit.profile` is not used as a comparison default. Batch
+membership and notification ordering are described in the
+[operations guide](operations.md).
 
 ## Output, Errors, And Quiet Mode
 
-Action commands (`generate` and `run`) write a JSON summary to stdout unless
+For `generate`, the report's default filename is placed beneath
-`--quiet` is set. `run` also writes compact per-report and batch status lines
+`output.directory` when configured, otherwise the current directory. `--out
-to stderr. A pre-run error, such as an invalid flag, missing required argument,
+PATH` selects one complete output file instead. A relative path is resolved
-or configuration-load failure, produces no partial JSON summary. When an action
+from the current directory; an absolute path is used as given. For a batch,
-fails after it has produced a result, its summary has `"status": "failed"` and
+the configured directory has the same role and `--out-dir PATH` selects its
-an `error` field.
+output directory instead. For `compare`, `--out-dir PATH` selects one exact
+bundle directory; otherwise the report-derived comparison directory is placed
+beneath the configured directory or current directory. `--replace` is required
+to replace an existing nonempty recognized comparison bundle. See the
+[configuration reference](config.md) for the field's validation and path rules
+and the [comparison bundle contract](integrations/comparison-bundle.md) for the
+bundle format.
+
+Outputs are written atomically. A generation, rendering, write, or cancellation
+failure before publication leaves an existing destination unchanged. A
+notification failure occurs after publication, so the newly written output
+remains available.
+
+`SIGINT` and `SIGTERM` cancel an active action. Weatherreporter lets that
+cancellation reach the action before exiting; when the action has a result, it
+emits the usual failed summary and exits nonzero. A canceled batch retains any
+reports that were already published, marks interrupted and unstarted reports
+as `canceled`, skips batch notification, and identifies cancellation separately
+from report failures.
+
+Action commands (`generate`, `run`, and `compare`) write a JSON summary to
+stdout unless `--quiet` is set. `run` also writes compact per-report and batch
+status lines to stderr. A pre-run error, such as an invalid flag, missing
+required argument, or configuration-load failure, produces no partial JSON
+summary. When an action fails after it has produced a result, its summary has
+`"status": "failed"` and an `error` field.
 
 `--quiet` is supported by action commands only. It suppresses action summaries
 and routine batch status output; it does not suppress command errors.
 
-Inspection commands always write their requested JSON value to stdout and do
-not accept `--quiet`.
-
 ### Generate Summary
 
-A generate summary always identifies the command, report, run, generation
+A generate summary identifies the command, report, run, generation time, valid
-time, valid period, and status:
+period, prompt version, timezone, and status. Successful output has an absolute
+`outputPath`:
 
 ```json
 {
   "command": "generate",
   "reportId": "today",
-  "reportName": "Today Report",
   "promptId": "weather.today_generated_text",
+  "promptVersion": "2.1.0",
   "runId": "20260529T120000.000000000Z_today",
   "status": "succeeded",
-  "generatedAt": "2026-05-29T12:00:00Z",
+  "timezone": "America/Chicago",
-  "validPeriod": {
+  "outputPath": "/srv/weather/today.md"
-    "start": "2026-05-29T00:00:00-05:00",
-    "end": "2026-05-30T00:00:00-05:00"
-  }
 }
 ```
 
-When available, the summary also includes `reportPath`, `metadataPath`,
+When available, the summary also includes the effective `profileId`,
-`dataPackagePath`, and `preflightPath`. Generated-text reports additionally
+`backendId`, `modelName`, `sourceWarnings`, `validationStatus`, requested
-include `generatedTextRawPath`, `generatedTextResultPath`,
+`repairAttempts`, `llmDebugPath`, and compact Distributor `notification`
-`generatedTextPath`, and `renderContextPath`. `outputPath` is included only
+result. `repairAttempts` is `0` when the initial output passed validation,
-when `--out` wrote an extra copy. Distributor notification, when attempted,
+positive when PromptKit made corrective generation calls, and omitted when
-adds `notificationPath` and may add a compact `notification` object.
+validation did not complete. The summary does not
+include historical or transient artifact paths such as metadata, prompt input,
+raw generated text, render context, or notification receipts.
 
 ### Run Summary And Stderr
 
 A run summary contains `command`, `batch`, `status`, `startedAt`, `finishedAt`,
-`total`, `succeeded`, `failed`, and a `reports` array. It may also contain a
+`total`, `succeeded`, `failed`, and a `reports` array. Each report item includes
-top-level `notification` object and `error`. Batch status is `failed` if any
+its identity, status, effective profile and model details when available,
-report or the batch notification fails.
+source warnings, validation status, repair-attempt count when validation
+completed, and absolute `outputPath` after publication.
+The top-level summary may also contain a batch `notification` object and
+`error`. Batch status is `failed` if any report or the batch notification fails.
+The `total`, `succeeded`, and `failed` counters describe report items only, so
+a failed batch notification can leave `failed` at `0` while the top-level
+notification and action status are `failed`.
+
+When cancellation stops a batch, the summary also includes a nonzero
+`canceled` count. Canceled reports have `"status": "canceled"`; they are not
+included in `failed`, and the action still has failed status and exits nonzero.
 
 Without `--quiet`, batch status lines use this form:
 
 ```text
-report=today status=succeeded output="reports/today.md"
+report=today status=succeeded output="/srv/weather/reports/today.md"
-batch=morning total=2 succeeded=2 failed=0
+batch=morning total=2 succeeded=2 failed=0 canceled=0
 ```
 
+### Compare Summary
+
+A comparison summary contains these fields in this order: `command`,
+`comparisonId`, `reportId`, `reportName`, `promptId`, `promptVersion`,
+`promptHash`, `status`, `startedAt`, `finishedAt`, `timezone`, `validPeriod`,
+`outputDirectory`, `manifestPath`, `dataPackagePath`, `total`, `succeeded`,
+`failed`, `results`, and optional `error`. Published artifact paths and each
+successful `results[].reportPath` are absolute. `results` preserves the
+supplied profile order and each item contains `position`, `profileId`, optional
+`backendId`, `modelName`, `status`, optional `validationStatus`, optional
+`repairAttempts`, optional `reportPath`, optional `llmDebugPath`, and optional
+safe `error`. The repair-attempt semantics match the generate summary.
+
+The comparison status is `succeeded` only when every selected profile succeeds
+and the bundle is published. Individual profile failures still publish a
+complete partial bundle and return a failed command result. Cancellation or a
+failure before publication omits the artifact paths and returns a safe
+top-level error; the resolved `outputDirectory` and finalized timestamp remain
+when available. The safe error includes only a category and message: aggregate
+and unclassified application failures use `application`; cancellation uses
+`canceled`; deadlines use `deadline_exceeded`; prompt execution uses its
+published Promptkit category; destination failures use `destination_<kind>`;
+and committed cleanup failures use `publication_cleanup` with a message that
+states whether a complete prior bundle, partial remnants, or no prior bundle
+remains, or that recovery state could not be inspected. It does not expose
+provider diagnostics, filesystem causes, or recovery paths. A provider HTTP
+failure may include its numeric status in the safe message. See the
+[comparison bundle contract](integrations/comparison-bundle.md) for durable
+artifact fields and failure invariants.
+
+If the bundle is published but cleanup of its replaced prior bundle fails, the
+summary still includes the published artifact paths and has status `failed`.
+Its JSON error is `publication_cleanup`; the returned command error identifies
+a recovery path only when cleanup left a sibling behind. Only a reported
+complete prior bundle is a rollback artifact.
+
 ## Flag Reference
 
 | Flag | Accepted by | Meaning |
 | --- | --- | --- |
-| `-h`, `--help` | top level | Show help. |
+| `-h`, `--help` | top level, `compare` | Show help without loading configuration or contacting a provider. |
 | `--config PATH` | all commands | Load `PATH` instead of `/usr/local/etc/weatherreporter/config.yml`. |
-| `--units VALUE` | `generate`, `run` | Override `weather_api.units` for this command. |
+| `--units VALUE` | `generate`, `run`, `compare` | Override `weather_api.units` for this command. |
-| `--tz NAME` | `generate`, `run` | Override `weather_api.timezone` for this command. |
+| `--tz NAME` | `generate`, `run`, `compare` | Override `weather_api.timezone` for this command. |
-| `--out PATH` | every `generate` command | Write an extra Markdown report copy. |
+| `--out PATH` | every `generate` command | Write the report to this complete file destination instead of the configured or current-directory default. |
-| `--out-dir PATH` | `run morning`, `run evening` | Write extra Markdown report copies in `PATH`. |
+| `--llm-debug-dir PATH` | every `generate`, `run`, and `compare` command | On Unix hosts, write requested sensitive prompt diagnostics under this absolute path. Other hosts fail closed when the flag is requested. |
-| `--quiet` | `generate`, `run` | Suppress action summaries and routine batch status output. |
+| `--profile PROFILE` | `compare` | Select one explicit profile. Repeat at least twice with distinct, nonblank IDs. |
-| `--date YYYY-MM-DD` | `generate daily`, `generate today` | Required for Daily; optional for Today. |
+| `--out-dir PATH` | `run morning`, `run evening`, `compare` | Write batch reports beneath this directory, or select the exact comparison directory. |
-| `--start TIME`, `--end TIME` | `generate storm` | Required storm-event bounds. |
+| `--replace` | `compare` | Authorize replacement of a recognized nonempty comparison bundle. |
-| `--limit N` | `inspect reports` | Maximum runs to list. Defaults to `20`; `0` means no limit. |
+| `--quiet` | `generate`, `run`, `compare` | Suppress all action summaries and routine batch status output. |
+| `--date YYYY-MM-DD` | `generate daily`, `generate today`, `compare daily`, `compare today` | Required for Daily; optional for Today. |
 
 Distributor notification is configured through `notify.distributor`; there are
 no Distributor-specific CLI flags. See the [configuration reference](config.md).
@@ -125,33 +195,10 @@ no Distributor-specific CLI flags. See the [configuration reference](config.md).
 ## Invocation Examples
 
 ```sh
-weatherreporter generate daily --date 2026-05-29 --out ./daily.md
+weatherreporter generate daily --date 2026-05-29
-weatherreporter generate today --date 2026-05-29 --out ./today.md
+weatherreporter generate today --out ./reports/today.md
-weatherreporter generate hourly --out ./hourly.md
+weatherreporter generate hourly --out /srv/weather/hourly.md
-weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
+weatherreporter generate today --llm-debug-dir /var/tmp/weatherreporter-debug
-weatherreporter run morning --out-dir ./reports
+weatherreporter run morning --out-dir ./reports --llm-debug-dir /var/tmp/weatherreporter-debug
+weatherreporter compare daily --date 2026-05-29 --profile weather-light --profile weather-balanced --out-dir ./comparison-daily-2026-05-29
 ```
-
-## Inspection Commands
-
-```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
-```
-
-| Command | JSON returned |
-| --- | --- |
-| `inspect reports` | Recent generated runs, including artifact paths and source-warning counts. |
-| `inspect metadata RUN_ID` | Persisted metadata for the run. |
-| `inspect modules RUN_ID` | The run's persisted ordered module snapshot. |
-| `inspect data-package RUN_ID` | The run's persisted prompt data package. |
-| `inspect prior RUN_ID` | Prior comparable snapshot metadata, or `null` when none exists. |
-| `inspect sources RUN_ID` | Source provenance and source warnings without full weather payloads. |
-
-Inspection is read-only: it does not collect weather data or invoke
-`scriptorium`. See the [operations guide](operations.md) for artifact lifecycle
-and recovery.

docs/config.md

@@ -13,8 +13,8 @@ explicit `--config PATH` must exist. Values are applied in this order:
 2. the configuration file, when present; and
 3. the `--units` and `--tz` command-line overrides.
 
-Environment variables do not override configuration fields. Output flags write
+Environment variables do not override configuration fields. Output flags select
-extra report copies for a command and do not change configuration.
+operator-owned destinations for one command and do not change configuration.
 
 ## Maintained Examples
 
@@ -22,8 +22,12 @@ extra report copies for a command and do not change configuration.
   collection and generation configuration.
 - [config.yml](../examples/config.yml) is a representative production-oriented
   configuration using synthetic endpoints and no credentials.
+- [weather-light-local-profile.yml](../examples/weather-light-local-profile.yml)
+  is a complete endpoint-only override for the embedded `weather-light`
+  profile.
 
-Both files are loaded by the configuration test suite.
+The configuration examples are loaded by the configuration test suite. The
+profile example is inspected through the Promptkit adapter test suite.
 
 ## Minimal Configuration
 
@@ -41,7 +45,7 @@ All omitted fields use their built-in defaults.
 
 | Field | Default | Rules |
 | --- | --- | --- |
-| `base_url` | empty | Absolute Weather API URL. Required for collection and generation. |
+| `base_url` | empty | Absolute HTTP(S) Weather API URL. Required for collection and generation. |
 | `timeout` | `10s` | Must be greater than zero. |
 | `precision` | `0` | Must be zero or greater. Sent as the Weather API precision query value. |
 | `units` | `us` | Required Weather API units query value; `--units` overrides it for one command. |
@@ -49,7 +53,11 @@ All omitted fields use their built-in defaults.
 | `format` | `json` | Required and must be `json`. |
 
 Timezone values may be IANA names, configured aliases such as `Chicago` and
-`Stl`, US timezone abbreviations, or UTC offsets such as `-5` and `+09:30`.
+`Stl`, US timezone abbreviations, or signed UTC offsets such as `-5`, `+0930`,
+and `+09:30`. Numeric offsets require a sign, one or two hour digits, and an
+optional two-digit minute component with or without a colon. Hours must be
+from `00` through `23`, minutes from `00` through `59`, so the largest accepted
+offset magnitude is `23:59`.
 
 ### `location`
 
@@ -68,8 +76,10 @@ The prompt-facing location timezone is derived from the effective
 ### `secrets`
 
 `secrets.directory` defaults to empty, which disables secret loading. When it
-is set, every regular file directly in that directory is loaded after the file
+is set, every regular file directly in that directory is staged after the file
-and command-line overrides. A file basename must match
+and command-line overrides, then applied only after the complete configuration
+has validated successfully. A rejected load leaves the existing environment
+unchanged. A file basename must match
 `[A-Za-z_][A-Za-z0-9_]*`; it becomes an environment variable name, and the
 file contents replace any existing value. One trailing LF or CRLF is removed.
 
@@ -77,6 +87,32 @@ Missing directories, unreadable files, subdirectories, symlinks, non-regular
 files, and invalid names fail configuration loading. Put only secret values in
 this directory, never in the YAML file.
 
+### `output`
+
+`output.directory` selects the ordinary operator-owned publication directory
+for individual reports, batches, and the default parent of comparison bundles.
+
+| Field | Default | Rules |
+| --- | --- | --- |
+| `directory` | empty | An omitted or empty value uses the invocation working directory. A nonempty value must contain at least one non-whitespace character. |
+
+The configured value is preserved while configuration loads: it is not cleaned,
+made absolute, inspected, created, or expanded through environment variables or
+a home-directory shortcut. At execution, an absolute directory is used as
+given; a relative directory resolves from the invocation working directory, not
+from the configuration file's location. A missing directory is created when a
+report is successfully published. An existing non-directory or an uninspectable
+path fails output preflight before prompt inspection, weather collection, or
+publication.
+
+For one `generate` command, `--out` is a complete file destination and takes
+precedence over `output.directory`. For `run`, `--out-dir` takes precedence.
+For `compare`, `--out-dir` selects its exact bundle directory; without it, the
+comparison's report-derived directory is placed beneath `output.directory`.
+Those explicit flags do not inspect or rebase beneath the configured directory.
+See the [CLI reference](cli.md) for command selection and the [operations
+guide](operations.md) for publication and failure handling.
+
 ### `notify.distributor`
 
 Distributor notification is disabled by default. Its fields are:
@@ -84,7 +120,7 @@ Distributor notification is disabled by default. Its fields are:
 | Field | Default | Rules when notification is enabled |
 | --- | --- | --- |
 | `enabled` | `false` | Activates Distributor notification validation. |
-| `endpoint` | `https://distributor.example.com` | Must be an absolute URL. |
+| `endpoint` | `https://distributor.example.com` | Must be an absolute HTTP(S) base URL with a host and no userinfo, query, or fragment. A path prefix is allowed. |
 | `token_env` | `DISTRIBUTOR_UPLOAD_TOKEN` | Must name a valid environment variable. |
 | `timeout` | `30s` | Must be greater than zero. |
 | `failure_policy` | `error` | Must be `error`. |
@@ -99,13 +135,20 @@ Distributor notification is disabled by default. Its fields are:
 The upload token is read from the environment variable named by `token_env`.
 Use `secrets.directory` when a file-backed secret is appropriate.
 
+When notification is enabled, Weatherreporter validates the Distributor endpoint
+before prompt inspection, weather collection, or output publication. Use an
+HTTP(S) base URL such as `https://distributor.example.com/archive`; do not put
+credentials, a query string, or a fragment in the endpoint.
+
+When notification is enabled, each rendered single-report pipeline ID, bundle
+ID, and idempotency key must contain at least one non-whitespace character.
+
 Single-report bundle templates accept `location_id`, `report_id`, `run_id`,
 `artifact_group`, `batch_output_name`, `valid_start_date`, `valid_end_date`,
 `valid_start_time`, `valid_end_time`, `valid_start_stamp`, `valid_end_stamp`,
-and `storm_id`. Pipeline and idempotency-key templates may also use
+Pipeline and idempotency-key templates may also use `bundle_id`. Dates use
-`bundle_id`. Dates use `YYYY-MM-DD`; times use `HHMM`; and stamps use
+`YYYY-MM-DD`; times use `HHMM`; and stamps use `YYYY-MM-DDTHHMM` in the
-`YYYY-MM-DDTHHMM` in the effective report timezone. `storm_id` is
+effective report timezone.
-`{valid_start_stamp}-{valid_end_stamp}` for Storm Report and empty otherwise.
 
 Batch bundle and pipeline templates accept `location_id`, `batch`,
 `batch_run_id`, and `batch_started_date`; batch idempotency-key templates may
@@ -124,45 +167,67 @@ The default paths are:
 | `daily` | `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md` |
 | `today` | `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md`, `today/index.md` |
 | `tomorrow` | `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md`, `tomorrow/index.md` |
-| `three_day` | `three-day/{valid_start_date}/{run_id}.md`, `three-day/{valid_start_date}/index.md` |
-| `weekend` | `weekend/{valid_start_date}/{run_id}.md`, `weekend/{valid_start_date}/index.md` |
-| `storm` | `storm/{storm_id}/{run_id}.md`, `storm/{storm_id}/index.md` |
 
 See the [operations guide](operations.md) for notification timing, uploaded
-artifact selection, and failure handling.
+output selection, and failure handling.
 
 ### `missing_source`
 
 `missing_source.default` defaults to `warn` and accepts `error`, `warn`, or
 `none`. `missing_source.sources` optionally overrides that policy by source.
-Hourly forecast data is required for generated reports. Supported optional
+Hourly forecast data is required for generated reports and cannot have a
-source keys are `observations`, `current`, `narrative`, `alerts`, `discussion`,
+source-specific policy. Supported optional source keys are `observations`,
-`weather_story`, and `spc_convective_outlooks`.
+`current`, `narrative`, `alerts`, `discussion`, `weather_story`, and
+`spc_convective_outlooks`; any other key is rejected.
 
-### `scriptorium`
+### `promptkit`
+
+Promptkit configuration selects the executor and prompt/profile checks for
+every `generate`, `run`, and `compare` command. A top-level `scriptorium:` configuration
+key is rejected with a migration error; it is not translated or ignored.
+
+Prompt debug capture has no YAML setting. Use `--llm-debug-dir PATH` on an
+individual `generate`, `run`, or `compare` command when explicitly needed.
+See [optional prompt debug capture](operations.md#optional-prompt-debug-capture)
+for platform availability, security, and retention requirements.
 
 | Field | Default | Rules |
 | --- | --- | --- |
-| `binary` | `scriptorium` | Required executable name or path. |
+| `profile` | empty | Optional global profile selection for every report in one command. When empty, each exact prompt version selects its declared default. |
-| `config_path` | empty | Optional Scriptorium configuration path. |
+| `profile_file` | empty | Optional external Promptkit profile file. It cannot be combined with `profile_dir`. A same-ID profile completely replaces Weatherreporter's embedded definition. |
-| `profile` | empty | Optional Scriptorium profile. |
+| `profile_dir` | empty | Optional external Promptkit profile directory. It cannot be combined with `profile_file`. A same-ID profile completely replaces Weatherreporter's embedded definition. |
 | `timeout` | `2m` | Must be greater than zero. |
-| `extra_args` | empty | Optional extra arguments passed to Scriptorium commands. |
+| `local.endpoint` | empty | Optional absolute URL for the conventional local backend. A blank endpoint leaves it unregistered. |
+| `local.concurrency_limit` | `1` | Maximum local backend concurrency. `0` is unlimited; negative values are invalid. |
 
-### `workspace`
+`profile` selects an ID; `profile_file` and `profile_dir` supply definitions.
+They are separate decisions. An explicit `profile` applies to every selected
+report. Otherwise Hourly selects `weather-light`, while Daily, Today, and
+Tomorrow select `weather-balanced` through their exact `2.1.0` prompt
+definitions.
 
-| Field | Default |
+Promptkit resolves a selected profile definition from a test or embedding
-| --- | --- |
+consumer's explicit in-memory profile, then the configured `profile_file` or
-| `root` | `workspace` |
+`profile_dir`, then Weatherreporter's embedded catalog, and finally Promptkit's
-| `snapshots_dir` | `snapshots` |
+built-in catalog. Weatherreporter's embedded `weather-*` definitions are small
-| `reports_dir` | `reports` |
+aliases of Promptkit's maintained base profiles, so Promptkit also resolves
-| `data_packages_dir` | `data-packages` |
+their inherited target and settings. A configured definition with the same ID
-| `preflight_dir` | `preflight` |
+as either a selected profile or an inherited base takes precedence. A matching
-| `notifications_dir` | `notifications` |
+malformed external profile fails rather than using the embedded definition. The
+[Promptkit integration guide](integrations/promptkit.md) owns the catalog and
+precedence details.
 
-`workspace.root` is required. Each workspace subdirectory must be a relative
+An endpoint-only profile may intentionally have no backend identity. Profiles
-path that stays within the root. See the [operations guide](operations.md) for
+that require a direct API key are rejected before collection, while Promptkit
-the managed workspace layout and lifecycle.
+resolves optional environment credential sources during execution.
+
+To replace the default Hourly definition with a local OpenAI-compatible
+endpoint, set `profile_file` to a copy of
+[weather-light-local-profile.yml](../examples/weather-light-local-profile.yml).
+The example has no credential and should be edited for the local endpoint and
+model before use. An alternative profile may use `backend: local`; in that
+case `promptkit.local.endpoint` supplies the conventional local backend
+endpoint.
 
 ### `dayparts`
 
@@ -172,26 +237,21 @@ derivation. Every item needs `name`, `start`, and `end`; start and end use
 (`06:00`–`10:00`), `midday` (`10:00`–`15:00`), `afternoon`
 (`15:00`–`17:00`), and `evening` (`17:00`–`24:00`).
 
-### `recent_change`
+Names remain display text, but each name must have a distinct canonical
-
+identity. Canonicalization trims whitespace, lowercases letters, and collapses
-| Field | Default |
+punctuation and whitespace to underscores; for example, `Morning`,
-| --- | --- |
+`morning!`, and `morning` conflict. Planning recognizes the canonical
-| `temperature_degrees` | `5` |
+identities `morning`, `afternoon`, `evening`, and `overnight` regardless of
-| `precip_probability_points` | `20` |
+their display capitalization or punctuation.
-| `wind_gust_miles_per_hour` | `10` |
-| `precip_timing_shift_minutes` | `120` |
-
-These thresholds control when Recent Changes are included in prompt input for a
-prior comparable module snapshot.
 
 ### `reports`
 
 `reports` optionally overrides a report's ordered deterministic modules and
 Distributor path templates. Omit a report entry to retain its defaults.
 
-Supported report keys are `daily`, `today`, `tomorrow`, `hourly`, `three_day`,
+Supported report keys are `daily`, `today`, `tomorrow`, and `hourly`. Keys are
-`weekend`, and `storm`. Configuration also accepts `three_day_outlook`,
+trimmed, case-folded to lowercase, and normalize hyphens to underscores before
-`weekend_outlook`, and `storm_report`; hyphens and underscores are equivalent.
+lookup.
 
 Each report entry can contain:
 

docs/development.md

@@ -5,9 +5,9 @@ Weatherreporter. It provides a concise repository orientation and routes each
 kind of change to its canonical documentation.
 
 Weatherreporter is a Go CLI that collects normalized weather data, derives
-deterministic report facts and module snapshots, invokes Scriptorium for
+deterministic report facts and module snapshots, executes Promptkit for
-generated text, renders managed Markdown reports, and can upload completed
+single-report generated text, renders Markdown reports, and can upload completed
-reports through Distributor. Start with the [README](../README.md) for product
+operator-owned outputs through Distributor. Start with the [README](../README.md) for product
 context and the [architecture policy](policy/architecture.md) for system
 boundaries and invariants.
 
@@ -21,17 +21,18 @@ boundaries and invariants.
 | Adding, changing, reviewing, or deleting tests | [Testing policy](policy/testing.md) and focused package tests | The policy defines risk-based sufficiency, durable test boundaries, doubles, and test-maintenance criteria. |
 | CLI commands, flags, output, quiet mode, or command wiring | [CLI reference](cli.md) and [CLI internals](internal/cli.md) | The reference owns the user contract; the internal guide owns command composition and output flow. |
 | Configuration fields, defaults, loading, overrides, validation, or secrets | [Configuration reference](config.md), [architecture policy](policy/architecture.md), and tests under `internal/config` | These separate the user-visible contract, architectural rules, and executable behavior. |
-| Top-level generation, batch, collection, inspection, or notification workflow | [App orchestration internals](internal/app-orchestration.md) | It owns workflow ordering, persistence points, failure propagation, and orchestration invariants. |
+| Top-level generation, batch, comparison, collection, output publication, or notification workflow | [App orchestration internals](internal/app-orchestration.md), [comparison execution internals](internal/comparison-execution.md), and [comparison publication internals](internal/comparison-publication.md) | They own workflow ordering, concurrent profile execution, output publication, failure propagation, and orchestration invariants. |
 | Weather API transport, source envelopes, source warnings, or collection | [Weather API integration](integrations/weatherapi.md), [weather-data internals](internal/weather-data.md), and [collection internals](internal/collect.md) | These separate the external contract, normalized source facts, and app-facing collection behavior. |
 | Forecast periods, weather derivation, collected facts, or derived facts | [Forecast derivation internals](internal/forecast-derivation.md) and [fact contracts](internal/facts.md) | They own deterministic derivation and the fact boundaries used by reports. |
 | Report definitions, valid periods, report IDs, output naming, or batch composition | [Report registry internals](internal/report-registry.md) and [app orchestration internals](internal/app-orchestration.md) | Report definitions own selection and period rules; orchestration owns execution. |
 | Module IDs, module composition, briefing values, or prompt-facing exports | [Module contract internals](internal/module.md), [module builder internals](internal/briefing.md), and [prompt-input internals](internal/prompt-input.md) | These own module contracts, value construction, and the curated prompt-package boundary. |
-| Recent Changes comparison | [Changes internals](internal/changes.md) and [operations guide](operations.md) | The internal guide owns structured comparison; operations owns user-visible artifact behavior. |
+| Prompt execution, profiles, prepared report inputs, or result handling | `internal/promptexec`, the Promptkit adapter, [prepared report internals](internal/prepared-report.md), and [prompt-input internals](internal/prompt-input.md) | These separate the executor contract, immutable preparation, and input construction. |
-| Scriptorium commands, subprocess execution, prompt inputs, or result handling | [Scriptorium integration](integrations/scriptorium.md), [Scriptorium adapter internals](internal/scriptorium-adapter.md), and [prompt-input internals](internal/prompt-input.md) | These separate the external CLI contract, subprocess boundary, and input construction. |
+| Durable comparison bundles or their compatibility | [Comparison bundle contract](integrations/comparison-bundle.md) and [comparison publication internals](internal/comparison-publication.md) | The integration document owns the external schema; internals own how it is published. |
 | Generated-text schemas, validation, render contexts, templates, or Markdown rendering | [Generated-text internals](internal/generatedtext.md), [report-template internals](internal/reporttemplate.md), and [report template guide](templates.md) | These own structured text, renderer implementation, and the maintainer-facing template surface. |
-| Workspace paths, metadata, atomic persistence, lookup, inspection, or recovery | [State internals](internal/state.md), [operations guide](operations.md), and [troubleshooting guide](troubleshooting.md) | These separate implementation, operator workflows, and symptom-based recovery. |
+| Output destinations, atomic publication, prompt diagnosis, or legacy cleanup | [Operations guide](operations.md), [App orchestration internals](internal/app-orchestration.md), and [comparison publication internals](internal/comparison-publication.md) | Operations owns operator workflows; internals own implementation boundaries. |
-| Distributor bundles, uploads, notification artifacts, or failures | [Distributor adapter internals](internal/distributor-adapter.md), [Distributor integration contracts](integrations/distributor/), and [operations guide](operations.md) | These separate adapter behavior, external contracts, and operational lifecycle. |
+| Distributor bundles, uploads, notification results, or failures | [Distributor adapter internals](internal/distributor-adapter.md), [Distributor integration contracts](integrations/distributor/), and [operations guide](operations.md) | These separate adapter behavior, external contracts, and operational lifecycle. |
 | Maintained example configuration | [Configuration reference](config.md) and files under `examples/` | The reference owns field meaning; examples own complete copyable files. |
+| Release preparation, tagging, publication, or verification | [Release procedure](release.md) | It owns version selection, release-note preparation, candidate validation, tag publication, CI behavior, and post-publication checks. |
 | Proposed, deferred, or unimplemented work | Documents under `docs/roadmap/` | Future behavior and implementation status belong only in roadmaps until implemented. |
 
 For an existing subsystem, inspect its focused internal document, package-local
@@ -44,13 +45,14 @@ present before introducing a new package or abstraction.
 | --- | --- |
 | `cmd/weatherreporter` | Binary entry point. |
 | `internal/cli` | Command parsing, flags, help, output, and command wiring. |
-| `internal/app` | Generation, batches, collection coordination, notification, and inspection orchestration. |
+| `internal/app` | Stateless generation, batches, comparisons, collection coordination, output publication, and notification. |
+| `internal/comparison` | Comparison identities, logical bundles, guarded destinations, and atomic bundle publication. |
 | `internal/config` | Configuration defaults, loading, precedence, secrets, and validation. |
-| `internal/adapters` | Weather API, Scriptorium, and Distributor boundaries. |
+| `internal/adapters` | Weather API, Promptkit, and Distributor boundaries. |
 | `internal/weatherdata`, `internal/forecast`, `internal/facts` | Normalized source facts and deterministic derivation. |
-| `internal/report`, `internal/module`, `internal/briefing`, `internal/changes` | Report registry, module contracts and values, and structured comparison. |
+| `internal/report`, `internal/module`, `internal/briefing` | Report registry plus module and briefing contracts. |
 | `internal/promptinput`, `internal/generatedtext`, `internal/reporttemplate` | Prompt packages, generated-text validation, render contexts, and Markdown templates. |
-| `internal/state`, `internal/fileutil`, `internal/timeutil` | Durable artifacts, atomic file operations, clocks, dates, timezones, and periods. |
+| `internal/fileutil`, `internal/timeutil` | Atomic output operations, clocks, dates, timezones, and periods. |
 | `docs` | User, operator, integration, internal, policy, and roadmap documentation. |
 | `examples` | Maintained copyable configuration. |
 
@@ -68,7 +70,7 @@ implemented subsystem behavior.
 5. Run repository-wide validation before considering the work complete.
 
 Preserve actionable error context, keep secrets out of logs and fixtures, and
-avoid validation that requires live Weather API, Scriptorium, or Distributor
+avoid validation that requires live Weather API, Promptkit providers, or Distributor
 services. The architecture and testing policies own the detailed rules.
 
 ## Baseline Validation

docs/integrations/comparison-bundle.md

@@ -0,0 +1,109 @@
+# Comparison Bundle Contract
+
+A comparison bundle is the durable, flat artifact produced when one report is
+executed with multiple explicit Promptkit profiles. This document is the
+canonical contract for consumers of those bundles. Command invocation and JSON
+action summaries belong to the [CLI reference](../cli.md); destination handling
+and retention belong to the [operations guide](../operations.md).
+
+## Version And Layout
+
+The current and only supported manifest schema version is
+`weatherreporter.comparison.v2`. A bundle directory contains exactly these
+regular, non-symlinked files:
+
+```text
+comparison.json
+data-package.yml
+NN-profile-slug.md
+```
+
+`comparison.json` is the manifest and `data-package.yml` is the exact YAML
+input supplied to every selected profile. There is one Markdown file for each
+successful result and none for failed results. `NN` is the one-based selected
+profile position, zero padded to at least two digits (and widened only when
+needed for 100 or more profiles). The profile slug preserves ASCII letters,
+digits, `-`, and `_`; each run of other characters becomes one `-`; edge `-`
+and `_` characters are removed; the value is capped at 64 bytes; and an empty
+slug becomes `profile`. Logical profile IDs remain authoritative in the
+manifest.
+
+All manifest paths are basenames relative to the bundle root. They never use
+path separators, `.` or `..`. The CLI reports absolute paths only after a
+bundle has been published.
+
+## Manifest Schema
+
+The manifest is UTF-8 JSON, encoded as two-space-indented JSON with one
+trailing newline. Its fields appear in this order:
+
+```text
+schemaVersion, comparisonId, startedAt, finishedAt, reportId, validPeriod,
+timezone, promptId, promptVersion, promptHash, dataPackage, total, succeeded,
+failed, results
+```
+
+`validPeriod` contains `start` and `end`; it is a nonempty half-open period.
+`dataPackage` contains `path` (always `data-package.yml`) and `sha256` (the
+lowercase, 64-character SHA-256 digest of that file's exact bytes). `results`
+is in the explicit profile-selection order. Its result-object fields appear in
+this order:
+
+```text
+position, profileId, backendId, modelName, status, validationStatus,
+repairAttempts, reportPath, error
+```
+
+`startedAt` and `finishedAt` are nonzero UTC timestamps, and the latter is not
+earlier than the former. `validPeriod` retains its resolved time offset.
+`reportId`, `timezone`, prompt identity, model name, and comparison ID are
+nonblank. `promptHash` and `dataPackage.sha256` are lowercase SHA-256 digests.
+
+## Result Invariants
+
+`total` is at least two and equals the number of results. Positions are
+contiguous from one, profile IDs are distinct and nonblank, and
+`succeeded + failed == total`.
+
+A successful result has `status: "succeeded"`, `validationStatus: "passed"`,
+and a non-negative `repairAttempts` count,
+a `reportPath` exactly equal to the canonical `NN-profile-slug.md` filename for
+its position, total, and logical profile ID, and no `error`. A failed result has
+`status: "failed"`, no `reportPath`, and an `error` object with nonblank
+`category` and `message`. Its validation status is absent, `failed`, or
+`skipped`; it may also be `passed` when a WeatherReporter step after PromptKit
+validation failed. Error messages are valid UTF-8 and no longer than 1,024 bytes.
+`backendId` and `validationStatus` are omitted when unavailable. A failed
+result with any completed validation status must retain its non-negative
+`repairAttempts`; early operational failures omit both fields.
+
+Every successful Markdown file is declared by exactly one successful result.
+The directory contains no extra entries. Consumers can therefore verify the
+data-package digest and the full manifest-to-file mapping without scanning a
+larger workspace.
+
+## Compatibility And Sensitivity
+
+Weatherreporter recognizes a replaceable bundle only when it exactly satisfies
+the current version, schema, file set, file types, relative-path rules, and
+data-package digest. JSON field names are case-sensitive canonical names and a
+field may appear only once in each manifest object. It rejects unknown,
+case-variant, or duplicate fields; multiple JSON values; extra entries;
+symlinks; and future or otherwise unsupported versions. Treat a bundle that
+fails recognition as an ordinary directory, not as a compatible bundle.
+
+Only v2 is recognized as a replaceable bundle; v1 is unsupported and must be
+moved or removed before a replacement at the same destination. When replacing
+a recognized bundle, cancellation observed before the new
+bundle is installed preserves the prior bundle rather than committing the
+replacement.
+
+Cleanup of a prior bundle occurs only after its replacement is committed and
+does not affect the new bundle's compatibility. A cleanup error may identify a
+complete recovery bundle, partial remnants, no remaining sibling, or an
+uninspectable state; this operational state is not recorded in the manifest.
+
+The manifest contains safe operational provenance, but `data-package.yml` and
+the generated Markdown can contain sensitive weather or location context. Do
+not assume these artifacts are safe for public distribution. Handle retention,
+access, and deletion according to the [operations guide](../operations.md).

docs/integrations/distributor/api.md

@@ -8,8 +8,10 @@ and [operations guide](../../operations.md).
 
 ## Upload Admission
 
-Weatherreporter uses an absolute HTTP(S) endpoint as a base URL. The client
+Weatherreporter uses an absolute HTTP(S) endpoint with a host as a base URL.
-posts a gzip-compressed source bundle to:
+It allows a path prefix but rejects userinfo, query strings, and fragments
+before local report work begins. The client posts a gzip-compressed source
+bundle to:
 
 ```text
 POST /v1/pipelines/<pipeline_id>/upload
@@ -23,11 +25,16 @@ A successful response is `202 Accepted` with JSON containing `run_id` and
 `status`. Acceptance means Distributor staged and validated the source bundle;
 it does not mean downstream destinations have published it.
 
-The adapter requires a pipeline ID, bundle ID, idempotency key, and at least one
+The adapter requires nonblank pipeline ID, bundle ID, and idempotency key, plus
-source-file mapping before calling Distributor. It reads the bearer token from
+at least one source-file mapping, before calling Distributor. It reads the bearer token from
 the configured environment variable and redacts that value from errors. Request
 construction and timeout handling belong to the [Distributor adapter](../../internal/distributor-adapter.md).
 
+Weatherreporter reads at most 1 MiB from each Distributor response. An
+oversized response fails notification with a stable local diagnostic. Normal
+Weatherreporter results retain upload and status identity but do not repeat
+Distributor response bodies, status reports, or remote error text.
+
 ## Idempotency
 
 Distributor scopes idempotency to the token, pipeline ID, and key. Keys must be
@@ -58,8 +65,8 @@ application to record.
 
 Run and idempotency records are in-memory. Completed records expire according
 to Distributor's `server.http.retention`, and a Distributor restart removes
-retained status and idempotency state. Status polling decisions and persistence
+retained status and idempotency state. Status polling decisions are internal
-of notification artifacts are internal orchestration behavior; see the
+orchestration behavior; see the
 [Distributor adapter](../../internal/distributor-adapter.md) and
 [application orchestration](../../internal/app-orchestration.md).
 

docs/integrations/distributor/pkg-bundle.md

@@ -8,15 +8,15 @@ the upload call returns.
 
 ## File Mappings
 
-Every mapping pairs a managed Markdown report source with one bundle-relative
+Every mapping pairs an operator-owned Markdown output with one bundle-relative
-path. A single-report notification maps its one managed report to each rendered
+path. A single-report notification maps its published output to each rendered
 path configured for that report. A batch notification combines mappings for
-every included managed report and rejects duplicate bundle paths.
+every included published output and rejects duplicate bundle paths.
 
-The report source is never an `--out` copy or an arbitrary workspace scan. The
+The report source is the output selected for that command; the application does
-application selects it and renders notification paths; see the [operations guide](../../operations.md)
+not scan local directories. It renders notification paths after publication;
-for the managed-upload rule and the [Distributor adapter](../../internal/distributor-adapter.md)
+see the [operations guide](../../operations.md) and the
-for the adapter boundary.
+[Distributor adapter](../../internal/distributor-adapter.md) for the boundary.
 
 Bundle paths must be clean, relative, slash-separated paths. They cannot be
 empty or absolute, contain backslashes, empty segments, `.` or `..`, or use

docs/integrations/distributor/pkg-upload.md

@@ -6,17 +6,21 @@ attempt and calls `UploadFiles`, followed by `Status` for the accepted run.
 
 ## Client And Upload
 
-The adapter constructs the client with the configured endpoint, bearer token,
+The adapter constructs the client with the prevalidated HTTP(S) endpoint,
-and an HTTP client whose timeout is the configured Distributor timeout. It
+bearer token, and an HTTP client whose timeout is the configured Distributor
-passes no custom retry options, so the pinned client's defaults apply: three
+timeout. The endpoint may include a path prefix but never userinfo, a query, or
-attempts, 100 ms base delay, and one-second maximum delay.
+a fragment. It passes no custom retry options, so the pinned client's defaults
+apply: three attempts, 100 ms base delay, and one-second maximum delay.
+The adapter bounds every response to 1 MiB before handing it to the pinned
+client. A response above that boundary is rejected as a local overflow rather
+than decoding or retaining a prefix.
 
 For each notification, Weatherreporter calls `UploadFiles` with:
 
 - the rendered pipeline ID;
 - the rendered bundle ID as the source manifest ID;
 - the report or batch generation time as `Created`;
-- the managed-report-to-bundle-path mappings described in the
+- the published-output-to-bundle-path mappings described in the
   [bundle mapping contract](pkg-bundle.md); and
 - a rendered idempotency key.
 
@@ -38,8 +42,9 @@ adapter translates it to its own conflict error without exposing the token.
 The adapter then calls `Status` for the accepted run. A terminal `failed`
 status is a notification failure. A status lookup failure or a timeout before a
 terminal status remains attached to the otherwise accepted upload as diagnostic
-status information. Polling cadence, final failure handling, redaction, and
+status information. Normal diagnostics use local status classifications; they
-notification artifact persistence are internal behavior documented in the
+do not expose remote response text or the status report. Polling cadence, final
+failure handling, and redaction are internal behavior documented in the
 [Distributor adapter](../../internal/distributor-adapter.md) and
 [application orchestration](../../internal/app-orchestration.md).
 

docs/integrations/promptkit.md

@@ -0,0 +1,82 @@
+# Promptkit Integration
+
+Weatherreporter uses Promptkit for all generated-text reports. The four logical prompts are `weather.daily_generated_text`, `weather.today_generated_text`, `weather.tomorrow_generated_text`, and `weather.hourly_generated_text`, each at version `2.1.0`. Their prompt assets, generated-text JSON Schemas, and Weatherreporter profile catalog are embedded by `internal/promptassets`.
+
+## Logical Profile Catalog
+
+Prompt definitions select a stable Weatherreporter profile ID. Each embedded
+definition contains only its ID and one Promptkit base-profile reference; the
+effective execution settings resolve from Promptkit's maintained catalog:
+
+| Profile ID | Model | Reasoning effort | Timeout | Service tier | Default reports |
+| --- | --- | --- | --- | --- | --- |
+| `weather-light` | `deepseek/deepseek-v4-flash` | Provider default | 180 seconds | `flex` | Hourly |
+| `weather-balanced` | `~google/gemini-flash-latest` | `high` | 240 seconds | `flex` | Daily, Today, Tomorrow |
+| `weather-deep` | `~anthropic/claude-sonnet-latest` | `high` | 240 seconds | `flex` | None |
+
+The `~` prefix is part of each OpenRouter rolling-alias model ID. The embedded
+profiles intentionally omit endpoints, credentials, and execution settings;
+Promptkit owns inherited resolution and its provider-native defaults.
+Promptkit's built-in `rakestrawhome-gemma-4-31b` is also available for ordinary
+and comparison selection and reports the `rakestrawhome` backend without
+Weatherreporter-specific configuration.
+
+## Selection And Active Execution
+
+Before weather collection, Weatherreporter validates the report's exact generated-text report/schema/template catalog binding, prompt version and hash, output contract, and selected profile. Active profiles must resolve a nonblank model; an endpoint-only profile may intentionally have no backend identity. A nonblank `promptkit.profile` selects one profile ID for every report in the command; otherwise the prompt's declared default selects it. Promptkit resolves the selected definition in this order:
+
+1. explicit in-memory profiles used by an embedding consumer or test;
+2. the configured `profile_file` or `profile_dir`;
+3. Weatherreporter's embedded fallback profiles; and
+4. Promptkit's built-in catalog.
+
+A source falls through only when the selected ID is absent. Promptkit resolves a
+derived profile's base with the same source precedence, so a configured base
+can shadow a built-in base. A missing, cyclic, malformed, or incomplete
+selected inheritance chain is an error and does not fall back.
+
+Profiles that require a direct API key are unsupported. Optional environment
+credential sources are Promptkit runtime concerns and are not checked by
+Weatherreporter during profile inspection. Active results retain the selected
+logical profile ID and resolved backend and model. Ordinary errors, summaries,
+logs, and outputs exclude endpoints, credentials, rendered messages, schemas,
+request bodies, response bodies, and complete parameter maps.
+
+Promptkit receives the YAML data package as an inline input and returns structured JSON that Weatherreporter validates before rendering its own Markdown template. Before accepting that JSON, Weatherreporter requires exactly one preparation callback and reconciles its prompt/profile/backend/model and rendered/input hashes with the inspected identity and completed result. The callback output contract and completed validation must use the report's expected JSON Schema mode and path. The package contains only reviewed prompt-facing warning summaries, never source transport or provenance details. Safe active provenance remains in memory. Content-rich diagnostics are opt-in through `--llm-debug-dir`; see [operations](../operations.md) for retention and permissions. Ordinary generation errors disclose only the safe Weatherreporter category and optional HTTP status; provider code, type, and message are written only to the explicit secure failure-debug artifact.
+
+Each embedded prompt permits one Promptkit-owned corrective generation after an
+eligible failed or explicitly empty result. This is not an application retry:
+Weatherreporter performs no provider retry, profile fallback, or request-level
+output-contract override. Promptkit reports cumulative usage and the actual
+number of corrective calls; repair exhaustion remains a completed validation
+failure.
+
+When capture is enabled, its preparation artifact projects a provider endpoint
+to its scheme and host and retains only reviewed execution settings. Provider
+extras and URL user information, paths, queries, and fragments are omitted.
+Capture storage remains confined to the operator-selected debug root; an unsafe
+filesystem path causes the requested execution to fail. Host availability and
+operator handling are documented in the
+[operations guide](../operations.md#optional-prompt-debug-capture).
+
+## Comparison Execution
+
+For `compare`, Weatherreporter validates the report's generated-text catalog
+binding, one exact prompt, and every explicitly selected profile before weather
+collection. It prepares one deterministic YAML
+data package, retains immutable copies of the report inputs, and executes every
+profile against the same exact data-package bytes. Each profile remains an
+independent Promptkit execution: one provider, provenance, or validation failure does not
+stop its peers, while caller cancellation applies to every in-flight execution.
+
+Weatherreporter starts selected profile executions concurrently and does not
+add an application-level concurrency limit. Promptkit owns backend capacity and
+any profile or backend concurrency policy. A shared Weatherreporter executor
+must safely accept those concurrent `Execute` calls. The durable comparison output and
+its compatibility rules are defined by the
+[comparison bundle contract](comparison-bundle.md); the user-facing command
+contract is in the [CLI reference](../cli.md).
+
+The generated-text schemas require `summary`, `forecast_discussion`, and `precipitation_timing`, and reject additional properties. Promptkit results are accepted only when their raw JSON is at most 64 KiB; the adapter drops larger results before copying them into Weatherreporter's execution values or debug artifacts. The validator also limits total generated prose to 20,000 characters, with 4,000-character summary and timing fields, a 12,000-character Hourly discussion, and at most 12 day-style paragraphs of 4,000 characters each. Prompts return an empty string for `precipitation_timing` when the deterministic package contains no precipitation windows.
+
+Prompt/profile configuration and the maintained local override example are owned by the [configuration reference](../config.md). Adapter construction and mapping are documented in the [Promptkit adapter internals](../internal/promptkit-adapter.md).

docs/integrations/scriptorium.md

@@ -1,91 +0,0 @@
-# Scriptorium Integration
-
-`weatherreporter` invokes the Scriptorium executable as a subprocess to
-preflight prompt input and produce report artifacts. This is the limited CLI
-contract Weatherreporter uses, not general Scriptorium documentation.
-
-## Invocation
-
-The configured `scriptorium.binary` is the executable name or path. When it is
-empty, the adapter invokes `scriptorium`. Arguments are passed directly to the
-process, without a shell.
-
-For every command, arguments occur in this order:
-
-1. The subcommand.
-2. `--config <path>` when `scriptorium.config_path` is set.
-3. `--profile <profile>` when `scriptorium.profile` is set.
-4. The command-specific arguments below.
-5. Each configured `scriptorium.extra_args` item.
-
-The adapter uses these exact command shapes:
-
-```text
-scriptorium render [--config <path>] [--profile <profile>] \
-  --prompt <prompt_id> --input data_package=<data_package_path> --format json \
-  [<extra_arg> ...]
-
-scriptorium run [--config <path>] [--profile <profile>] \
-  --prompt <prompt_id> --input data_package=<data_package_path> --out <output_path> \
-  [<extra_arg> ...]
-```
-
-`render` is the preflight command. `run` writes either a Markdown report or a
-raw generated-text artifact to the supplied `--out` path. The structured
-generated-text use of `run` has the same argv as Markdown generation; it does
-not add `--format`, `--schema`, `--schema-path`, or `--json-schema` flags.
-Prompt configuration selected by `<prompt_id>` controls that output.
-
-## Inputs and Outputs
-
-Weatherreporter always supplies exactly one prompt input:
-`--input data_package=<data_package_path>`. The path identifies the YAML data
-package produced by the [prompt-input builder](../internal/prompt-input.md).
-Its schema and the separate JSON module snapshots are internal artifacts, not
-part of this CLI contract.
-
-The application supplies an already-managed output path to every `run` call.
-For direct reports it is the Markdown artifact path. For generated-text
-reports it is the raw JSON artifact path; subsequent validation and Markdown
-rendering are owned by [generated-text processing](../internal/generatedtext.md).
-
-`render` has no output-path argument. Its JSON-formatted stdout remains
-captured output: the adapter records it and does not parse it into a separate
-CLI result type. Likewise, the adapter records `run` output metadata without
-decoding the artifact written at `--out`.
-
-## Execution and Results
-
-`scriptorium.timeout`, when greater than zero, creates a timeout for each
-subprocess invocation. Parent-context cancellation and that timeout stop the
-command through the process context.
-
-Stdout and stderr are captured independently, each up to 1 MiB. Every returned
-result records the complete argv as `command`, the captured `stdout` and
-`stderr`, `exitCode`, and `stdoutTruncated` and `stderrTruncated` when a stream
-was capped. Results from both forms of `run` also record `outputPath`, the
-requested `--out` value.
-
-The [Scriptorium adapter](../internal/scriptorium-adapter.md) owns process
-execution and result capture. [Application orchestration](../internal/app-orchestration.md)
-owns when preflight output, report artifacts, and generated-text artifacts are
-persisted.
-
-## Failure Behavior
-
-Before starting Scriptorium, the adapter requires a prompt ID and data-package
-path for every command, plus an output path for `run`. Missing fields fail
-without executing a subprocess.
-
-A nonzero process exit returns the captured result and an error that includes
-the exit code and stderr. An output file written before such an exit does not
-make the request successful. Failures to start the command, context
-cancellation, and timeout return an error rather than a successful result.
-
-## Operational Notes
-
-- Extra arguments are argv items; they are not shell-interpreted.
-- Prompt input, generated artifacts, stdout, and stderr can contain
-  operationally sensitive weather data.
-- Provide API keys through the Scriptorium environment or its configuration,
-  not through Weatherreporter CLI arguments.

docs/integrations/weatherapi.md

@@ -9,24 +9,29 @@ are documented in [Weather data internals](../internal/weather-data.md) and
 
 ## Base URL And Requests
 
-`weather_api.base_url` must be an absolute URL. Weatherreporter joins each
+`weather_api.base_url` must be an absolute HTTP(S) URL. Weatherreporter joins
-endpoint path to the configured base URL path, so a service hosted under a path
+each endpoint path to the configured base URL path, so a service hosted under a
-prefix must keep that prefix available. Requests use `GET` and carry the
+path prefix must keep that prefix available. Requests use `GET` and carry the
 configured timeout on every HTTP attempt.
 
 Every request sends `format` and, except where noted below, `units`. The
 configured format must be `json`.
 
-Before retrieving sources, Weatherreporter warms up
+Before retrieving sources, Weatherreporter requests `/conditions/current` with
-`/conditions/current` with the same `format`, `units`, and `precision` query
+the same `format`, `units`, and `precision` query parameters used for current
-parameters used for current conditions. The warmup only requires a readable
+conditions. After a readable 2xx response, it retains that response for the
-2xx response; its body is not decoded. Failure after its internal retry budget
+normal current-conditions source step rather than making a second identical
-stops the fetch before source requests begin.
+request. Failure after the readiness request's internal retry budget stops the
+fetch before source requests begin.
 
 ## Endpoints And Query Parameters
 
-The adapter makes one source request for each endpoint after a successful
+The adapter makes one source request for each endpoint, subject to retry on
-warmup, subject to retry on transient failures.
+transient failures. A successful readiness request supplies the current
+conditions source response. The remaining independent source requests run
+concurrently, then their results are processed in the source order shown below.
+This keeps source provenance, missing-source policy, and surfaced errors
+deterministic regardless of response order.
 
 | Source | Endpoint | Query parameters | Availability |
 | --- | --- | --- | --- |
@@ -57,14 +62,15 @@ An absent `data` member is treated as a missing source. For ordinary sources,
 `data: null` is also missing. The active-alert exception is listed above: its
 explicit `null` payload represents an empty alert result.
 
-Hourly forecast data must be present and contain at least one `period`; a
+Hourly forecast data must be present and contain at least one `period`. Every
-missing, malformed, or empty hourly product fails collection. The remaining
+hourly period needs nonzero `startTime` and `endTime` values, with `endTime`
-sources follow the configured missing-source policy. Under `error`, collection
+after `startTime`; a missing, malformed, empty, or invalidly bounded hourly
-fails; under `warn`, the source is omitted and an inspectable warning is
+product fails collection. The remaining sources follow the configured
-recorded; under `none`, the source is omitted without a warning. A per-source
+missing-source policy. Under `error`, collection fails; under `warn`, the
-policy overrides the default. See [Configuration](../config.md) for policy
+source is omitted and an inspectable warning is recorded; under `none`, the
-settings and [Weather data internals](../internal/weather-data.md) for recorded
+source is omitted without a warning. A per-source policy overrides the default.
-source metadata.
+See [Configuration](../config.md) for policy settings and [Weather data
+internals](../internal/weather-data.md) for recorded source metadata.
 
 Malformed top-level JSON envelopes and HTTP failures are direct request errors.
 Malformed `data` for an optional source follows its missing-source policy.
@@ -138,9 +144,10 @@ It does not retry other HTTP statuses, malformed envelopes, missing data, or
 payload decoding failures. A canceled context also stops an in-progress retry
 delay.
 
-The adapter reads at most 10 MiB from one response body. A non-2xx response,
+The adapter accepts response bodies up to 10 MiB and rejects larger bodies
-request construction failure, read failure, or decode failure includes endpoint
+before decoding. A non-2xx response reports its relative endpoint and status,
-context in its error.
+without including upstream response text. Request construction, response-limit,
+read, and decode failures include endpoint context in their errors.
 
 Retry counts and delays are adapter behavior rather than Weather API request
 parameters. Do not depend on a particular attempt count when implementing the

docs/internal/app-orchestration.md

@@ -1,110 +1,72 @@
 # Application Orchestration Internals
 
-`internal/app` composes top-level generation, batch, collection-save, and
+`internal/app` owns stateless report generation, batch execution, comparison
-inspection workflows after CLI parsing and configuration loading. It owns
+orchestration, atomic output publication, and notification coordination after
-workflow ordering, request composition, partial-result handling, and the
+`internal/cli` has parsed arguments and loaded configuration. The user contract
-application-facing interfaces used for tests.
+is owned by the [CLI reference](../cli.md) and [operations guide](../operations.md).
 
-## Inputs And Outputs
+## Single-Report Flow
 
-The package accepts generate, resolved-report, batch, explicit-collection, and
+`GenerateDetailed` resolves the requested report and output destination before initializing an optional explicit debug writer. An explicit output file wins; otherwise the configured output directory is used, falling back to the captured working directory. Output preflight validates the final filename, permits only an absent or regular final destination, and validates the bounded same-directory temporary form without creating a missing parent. It then validates the report's generated-text catalog binding, exact Promptkit prompt, and selected profile before collecting weather data. Profile inspection requires a model, permits an empty backend identity for endpoint-only profiles, and leaves inherited resolution and optional credential sources to Promptkit. The resolved profile, backend, model, and actual repair count (once a completed execution exists) are carried in the active result; the configured repair budget remains part of the exact prompt contract.
-inspection requests. Generation and batch requests may supply collector,
-renderer, store, and notifier implementations for tests; production defaults
-use the focused packages.
 
-A report result contains the module snapshot, prompt package, available
+The workflow builds facts, a module snapshot, briefing metadata, and the YAML prompt package in memory. It executes Promptkit only against the inspected prompt and profile, reconciles the preparation callback and completed result with that identity and the prepared report schema, validates the returned generated text, builds a render context, and renders Markdown. `fileutil` writes the completed Markdown through a same-directory temporary file, rechecks the final destination and context after close and immediately before the atomic rename. Only after that write succeeds does single-report notification run.
-Scriptorium results, generated-text artifacts when used, report and metadata
-paths, prior snapshot, Recent Changes, and notification information. A batch
-result contains aggregate counts, per-report outcomes, and an optional batch
-notification. Inspection returns persisted values only.
 
-Exact public command syntax, configuration fields, workspace layout, external
+Failures return an active partial result with safe identity, profile, warning, validation, debug, and output information when available. After rendering and immediately before publication, the workflow checks for cancellation or deadline expiry. Any failure before publication leaves an existing destination unchanged. A notification failure retains the newly published output.
-protocols, and report definitions belong in [the CLI reference](../cli.md),
-[the configuration reference](../config.md), [operations](../operations.md),
-and their focused integration and internal documents.
 
-## Single-Report Workflow
+## Batches
 
-`GenerateDetailed` first collects weather data, then resolves the requested
+`RunBatchDetailed` selects an explicit output directory first, otherwise the configured directory and then the captured working directory. It does this before creating at most one explicit debug writer or validating generated-text catalog, prompt, and profile candidates for the selected batch. It collects once, calculates the data-dependent plan, then validates and retains the final output path for every planned report before invoking the same generation core sequentially.
-report using the configured registry and current time, and finally calls
-`GenerateReport` with that explicit collection. It returns no result when
-collection or resolution fails.
 
-`GenerateReport` requires a non-nil normalized bundle and then performs this
+Each item has an independent result. A failed item does not stop later items; successful items retain their published output paths. Per-report notification is suppressed during a batch. Batch notification runs only after every planned report has published successfully. It is skipped when any item failed. Batch result counters count report items only; a batch notification failure is represented by the top-level notification result and still produces a failed batch outcome.
-ordered work:
 
-1. Select a state store, determine artifact destinations, and locate a prior
+Cancellation and deadline expiry stop the sequential loop before another report
-   compatible snapshot.
+starts. Completed report results and published paths remain successful; the
-2. Build report facts and deterministic module snapshots, then save the module
+interrupted and unstarted planned reports have `canceled` status and are counted
-   snapshot and calculate Recent Changes.
+separately from failed reports. The batch notification result records that
-3. Build and save the prompt data package, run Scriptorium render preflight,
+delivery was skipped, and the returned error retains the original context cause
-   save any preflight result, and save initial metadata.
+for callers and CLI projection.
-4. Produce managed Markdown according to the report generation mode.
-5. Optionally make an output copy, save final metadata, optionally notify
-   Distributor from the managed report path, and save metadata again when a
-   notification path is produced.
 
-Direct-Markdown reports prepare the managed report and invoke the Scriptorium
+## Comparisons
-run boundary. Generated-text-template reports look up their catalog definition,
-run structured Scriptorium output to the raw artifact, preserve any structured
-run result, validate and save generated text, build and save a render context,
-then render the embedded Markdown template. Schema, template, and subprocess
-details remain in their [generated-text](generatedtext.md),
-[report-template](reporttemplate.md), and [Scriptorium adapter](scriptorium-adapter.md)
-owners.
 
-If preflight returns a result with an error, the result and initial metadata are
+`CompareDetailed` validates ordered explicit profile IDs, resolves the report,
-saved before the error returns. If report generation fails after a managed path
+and preflights the exact bundle destination before initializing optional prompt
-is prepared, metadata still records that path; output copies and notification
+debugging, prompt inspection, or collection. It then validates the report's
-are skipped. Generated-text failures preserve the latest artifact reached
+generated-text catalog binding, inspects the one prompt and every selected
-before failure when it was saved.
+profile, collects once, and delegates shared report
+construction to the prepared-report flow. It does not accept a notifier.
 
-## Batch And Inspection Workflows
+Once the destination is resolved, the partial result retains its absolute
+output directory even when later preflight, debug initialization, inspection,
+collection, or preparation fails. Every initialized result is finalized with a
+finished timestamp. If prompt inspection succeeds before a later profile
+inspection fails, the partial result retains the resolved prompt ID, version,
+and hash. Artifact paths are added only after publication commits.
 
-`RunBatchDetailed` collects once, asks the report registry to plan the batch
+The comparison execution core starts each inspected profile independently,
-from that collection, and invokes `GenerateReport` independently for every
+keeps results in selection order, and waits for all started work. Every profile
-planned report using the same collection and state store. Per-report
+reconciles its callback and completion provenance before its JSON can be
-notification is suppressed. A failed report is recorded and does not prevent
+rendered. Independent profile failures are recorded and do not stop peers; a
-later planned reports from running.
+completed profile failure remains recorded if cancellation happens later.
+Context cancellation marks only unfinished or cancellation-terminated work and
+prevents publication. Details of
+prepared values, execution and debugging, and publication are documented in [prepared report
+internals](prepared-report.md), [comparison execution
+internals](comparison-execution.md), and [comparison publication
+internals](comparison-publication.md).
 
-After report generation, the batch notifier is considered once. It is omitted
+When publication has committed its new bundle, application results contain the
-when Distributor or batch notification is disabled, skipped when any report
+absolute manifest, data-package, and successful report paths even if removal of
-failed, and otherwise receives one multi-file request. A batch notification
+the previous sibling backup then fails. That cleanup failure is still returned
-failure increments the aggregate failure count but does not rewrite successful
+as an operational error rather than treating the new bundle as unpublished;
-report items. Notification identities, path mappings, polling, and redaction
+the returned error identifies the observed recovery state and includes a path
-are owned by the [Distributor adapter](distributor-adapter.md).
+only when cleanup left a sibling behind.
 
-Inspection methods create a state store and load existing report records,
+## Boundaries And Verification
-metadata, module snapshots, prompt packages, prior snapshots, or source
-provenance. They neither collect data nor invoke Scriptorium or Distributor.
 
-## Boundaries And Failure Propagation
+The package does not parse flags, load YAML, implement transport, construct provider SDKs, or define report-period policy. Prompt, profile, weather, and Distributor implementations remain behind project-owned contracts.
 
-The app layer does not parse flags, load configuration files, implement Weather
+Focused checks:
-API transport, construct Scriptorium argv, or define report registry policy. It
-coordinates the relevant collaborators and preserves their error context.
 
-- Collection failure stops a single report or batch before resolution or
+```sh
-  planning completes.
+go test ./internal/app ./internal/collect
-- State, fact, module, prompt-input, or preflight failures stop that report
+```
-  before report generation.
-- A terminal Distributor failure is returned with the saved notification
-  information when available.
-- Batch failures are represented per report and through aggregate batch status.
-- Persisted artifact paths are carried in results so callers can inspect work
-  completed before a later failure.
-
-## Tests And Invariants
-
-Focused tests are in `internal/app/app_test.go` and
-`internal/app/batch_plan_test.go`, with collection coverage in
-`internal/collect/collect_test.go`.
-
-- Production workflows collect through `internal/collect`.
-- A report uses one explicit normalized collection throughout its generation.
-- Render preflight precedes report generation.
-- Recent Changes compare structured module snapshots.
-- Generated-text reports render from a validated typed context, never directly
-  from a raw prompt package.
-- Only managed Markdown reports are notification sources; output copies are
-  never uploaded.

docs/internal/briefing.md

@@ -4,13 +4,16 @@
 collected facts, and derived facts. It owns the module registry, including
 module support, fact requirements, option types, missing-data policy, builders,
 and prompt-export hooks. It does not collect data, derive periods, write a
-snapshot, construct YAML, invoke Scriptorium, or render a report.
+snapshot, construct YAML, invoke Promptkit, or render a report.
 
 ## Registry and construction
 
 Every `ModuleDefinition` declares an ID, stanza name, default option value,
 required collected and derived facts, supported report IDs, missing-data
-behavior, duplicate policy, builder, and optional prompt exporter.
+behavior, duplicate policy, builder, and optional prompt exporter. The
+briefing-owned fact-requirement vocabulary supplies each prerequisite's stable
+identity, category, and availability predicate; registry construction rejects
+unknown requirements and requirements listed under the wrong category.
 
 `BuildModule` first verifies the requested module, report compatibility, and
 option shape. It then applies the declared missing-data behavior:
@@ -32,29 +35,60 @@ discussion, and weather story. Derived builders shape daily and daypart
 summaries, precipitation timing, outdoor windows, and the report-specific
 Daily, Today, and Tomorrow planning values.
 
+The daily summary preserves generic feels-like values as
+`apparent_temperature_max_f`; it does not label them as a heat index. Daypart
+temperature phrases retain below-zero meaning, including through temperature
+trends that cross zero. Outdoor windows add a 25-point risk penalty and an
+explicit reason for each snow, ice, or fog indicator. Equal scores retain input
+order for both best and worst windows.
+
 The module registry preserves rich values for templates and snapshots while
 curating prompt exports where needed. In particular, source warnings are a
 metadata summary, checked-empty alerts and SPC outlooks remain distinct from
 missing sources, and prompt-safe SPC values omit geometry and other
 template-only or source details. The complete module composition is in
 [module internals](module.md); fact derivation is in [fact contracts](facts.md).
+Alert digests are built from selected alert items and source provenance, not a
+provider response envelope.
 
-`area_forecast_discussion` accepts an optional typed section filter. Planning
+Derived daypart-summary maps use the forecast package's canonical daypart
-modules are report-specific: `daily_planning` supports Daily,
+identity and reject any collision instead of replacing an earlier value.
+Planning applies the same identity when recognizing morning, afternoon,
+evening, and overnight windows; display labels remain separate and preserve
+configured text with rune-safe first-letter capitalization.
+
+The embedded SPC background-definition asset records its authoritative sources,
+source update dates, and maintainer review schedule. Its categorical
+`official_description` values transcribe the [SPC convective-outlook risk
+table](https://www.spc.noaa.gov/about/outlooks/); its Conditional Intensity
+Group entries follow the [SPC conditional-intensity
+reference](https://www.spc.noaa.gov/exper/conditional-intensity-information).
+`plain_language` values are Weatherreporter summaries. Weatherreporter
+maintainers review the asset annually and whenever either source changes.
+
+`area_forecast_discussion` accepts an optional typed section filter. Accepted
+typed option pointers are normalized to the declared value type before builder
+execution. Planning modules are report-specific: `daily_planning` supports Daily,
 `today_planning` supports Today, and `tomorrow_planning` supports Tomorrow.
 
 ## Missing data and boundaries
 
 Optional current conditions, narrative products, discussions, and weather
-stories may be omitted. Required derived modules fail when their declared facts
+stories may be omitted. A weather story is usable only when it has non-blank
+displayable content (title, description, alternate text, or download URL) or a
+valid start/end period; otherwise collection applies its optional-source policy
+and the module is omitted. Required derived modules fail when their declared facts
 are unavailable. Empty alert and outlook runs can still produce checked-empty
 modules. SPC discussion is omitted unless a retained categorical outlook meets
 the package's severity criterion and matching discussion text exists.
 
-Effective units, timezone, and location context arrive in `ModuleContext` from
+`ModuleContext` carries the effective units, timezone, location context, and
-configuration and resolved report metadata. Field defaults are owned by
+prepared identity. Report preparation creates that one `PreparedIdentity` for
-[configuration](../config.md), and prompt-package layout is owned by
+the shared report identity, timing, configuration context, and source warnings
-[prompt input](prompt-input.md).
+before module construction. The metadata module projects its matching fields
+from that value and retains its prompt-safe shape. Field defaults are owned by
+[configuration](../config.md), and prompt-package layout is owned by [prompt
+input](prompt-input.md).
 
 ## Verification and invariants
 
@@ -66,4 +100,4 @@ go test ./internal/briefing
 ```
 
 Builders emit structured facts, never report prose. The app collects their
-outputs into a module snapshot, and state persists that snapshot.
+outputs into an in-memory module snapshot for prompt input and rendering.

docs/internal/changes.md

@@ -1,61 +0,0 @@
-# Changes Internals
-
-`internal/changes` deterministically compares a compatible prior module
-snapshot with the current snapshot. It returns compact structured changes for
-prompt input; it never reads state, finds a prior report, renders Markdown, or
-compares generated text. Snapshot construction belongs to
-[module internals](module.md), and prior-snapshot discovery belongs to
-[state internals](state.md).
-
-## Comparison inputs and output
-
-Each comparator receives a prior snapshot, a current snapshot, and
-`Thresholds`. A `Change` has a stable type and message plus previous and
-current values where useful. Changes are sorted by type and then message, so
-the same inputs always yield the same order.
-
-Threshold values are supplied by application orchestration from the
-[Recent Changes configuration](../config.md#recent_change); this package does
-not load configuration or choose defaults. Numeric changes are emitted when
-the absolute difference meets the configured threshold. Precipitation also
-requires a change between its low, possible, likely, and high categories.
-
-## Strategies
-
-| Comparator | Required snapshot data | Compared values |
-| --- | --- | --- |
-| `CompareDaily` | `derived_daily_summary`, `derived_daypart_summaries` | Low and high temperature, daily precipitation probability and timing, peak gust, alerts, and aggregate indicators |
-| `CompareThreeDay` | `derived_daypart_summaries` | Per-day temperatures, precipitation probability and timing, peak gust, indicators, and added or removed outlook days |
-| `CompareWeekend` | `derived_daypart_summaries` | The three-day values with weekend-prefixed change types |
-
-For daily comparison, `alert_digest` and `precip_timing` are optional: alerts
-are compared when present, and timing is compared only when both snapshots
-contain it. The multi-day comparators build their day map from daypart
-summaries. A missing or added day becomes a dedicated change rather than a
-comparison against invented data.
-
-The application selects a comparator only after state lookup establishes a
-compatible prior snapshot. Daily, Today, and Tomorrow use the daily comparator;
-Three-day and Weekend use their named comparators. Other report types, such as
-Storm, produce no Recent Changes list.
-
-## Missing data and failures
-
-Required stanzas that are absent or cannot be decoded return an error with the
-snapshot and stanza context. Optional stanzas may be absent. A snapshot with no
-eligible predecessor is not a comparison failure: the caller supplies an empty
-change list without invoking this package.
-
-The package has no filesystem, transport, CLI, renderer, or persistence
-behavior. It does not decide report compatibility or retain snapshots.
-
-## Verification and invariants
-
-Focused tests cover the daily, three-day, and weekend strategies, threshold
-boundaries, indicator and alert changes, and missing required stanzas:
-
-```sh
-go test ./internal/changes
-```
-
-Recent Changes always compare structured snapshot values, never report prose.

docs/internal/cli.md

@@ -1,65 +1,21 @@
 # CLI Internals
 
-`internal/cli` turns process arguments into application requests and translates
+`internal/cli` parses terminal arguments, loads configuration, constructs app requests, and translates app results to bounded JSON summaries. The public contract belongs in the [CLI reference](../cli.md).
-application results into terminal output. The user-facing command, flag, and
-output contract belongs in the [CLI reference](../cli.md).
 
-## Responsibilities
+The root `--version` flag reports the build version supplied by `internal/buildinfo`. Tagged release builds replace its development default at link time.
 
-`Runner.Run` dispatches the top-level action or inspection request. For actions,
+The executable derives its action context from `SIGINT` and `SIGTERM` and
-the package parses command-specific and common flags, loads configuration with
+passes it to `Runner.Run`. Signal cancellation therefore uses the same action,
-CLI overrides, obtains the current time, and constructs either an
+summary, and error paths as other context cancellation.
-`app.GenerateRequest` or an `app.BatchRequest`. It delegates generation and
-batch execution to `internal/app`.
 
-For inspection, it loads configuration, builds the appropriate app inspection
+For each `generate`, `run`, or `compare` action, `Runner` constructs one project-owned Promptkit executor after request preflight and configuration loading. It captures an absolute working directory, resolves only a relative explicit output override against it, and passes the working directory, loaded configuration, resolved override, and any `--llm-debug-dir` request to the app. The raw configured fallback remains in the configuration for app-owned destination selection. `run` uses the same explicit-resolution rule for `--out-dir`.
-request, and writes the returned value. Inspection is read-only; the inspected
-artifact types and user invocation remain owned by the [CLI reference](../cli.md)
-and [operations guide](../operations.md).
 
-## Result Translation
+The CLI dispatches generation, batch, and comparison actions. It has no persisted-run or inspection dispatch. Generation and batch summaries include report identity, status, output path, effective profile/backend/model, source warnings, validation, requested debug path, and notification result when available. Comparison summaries retain their ordered profile results and published bundle paths when available. All summaries intentionally exclude prompt input, raw generated text, render context, endpoints, credentials, and full Distributor payloads. A failed action with a partial result still emits its safe summary before its error is returned unless `--quiet` is set.
 
-Action results become CLI-safe JSON summaries in `result.go`. Generate summaries
+CLI code owns report-date flag acceptance and date resolution, but not report
-carry report identity, status, relevant artifact paths, and notification
+composition, weather collection, output publication, provider execution, or
-summary data. Batch summaries carry aggregate counts, per-report outcomes, and
+notification policy. Focused checks:
-the optional batch notification result. The translation deliberately excludes
-full module snapshots, prompt packages, raw generated text, Scriptorium output,
-and complete Distributor payloads.
 
-When an action returns both a result and an error, the CLI writes the failed
+```sh
-summary before returning that error. Parse, configuration-load, and other
+go test ./internal/cli
-failures that produce no application result return without a summary.
+```
-
-`writeActionResult` writes action status information to stderr first, then JSON
-to stdout. Batch execution supplies the status writer; single-report generation
-does not emit routine stderr output. Quiet action requests suppress both normal
-streams but still return errors. Inspection writes its JSON value to stdout and
-does not accept quiet mode because stdout is the inspection result.
-
-## Boundaries
-
-The package owns argument parsing, request adaptation, help text, and terminal
-presentation. It does not implement report selection, collection, state
-persistence, external transport, subprocess execution, or notification policy.
-Those concerns remain in [application orchestration](app-orchestration.md) and
-their focused owners.
-
-## Failure Behavior
-
-- Invalid command names, flags, dates, and configuration fail before an app
-  request is executed.
-- Application errors retain their application context; output helpers do not
-  hide or replace them.
-- JSON-encoding errors are returned directly.
-- A failed batch summary causes the CLI to return an aggregate batch error even
-  when the detailed batch call has already returned its result.
-
-## Tests And Invariants
-
-Focused tests are in `internal/cli/root_test.go`, `internal/cli/output_test.go`,
-and `internal/cli/result_test.go`.
-
-- CLI summaries are stable, bounded views of app results.
-- Routine batch status lines precede the batch JSON summary.
-- A quiet action produces no successful or failure summary output.
-- Inspection never invokes action-output helpers.

docs/internal/collect.md

@@ -1,43 +1,36 @@
 # Collection Internals
 
-`internal/collect` is the application-facing boundary for collecting the
+`internal/collect` is the small application-facing boundary that obtains one
 normalized Weather API bundle. The external HTTP contract belongs in the
-[Weather API integration guide](../integrations/weatherapi.md); normalized data
+[Weather API integration guide](../integrations/weatherapi.md); normalized
-semantics belong in [weather-data internals](weather-data.md).
+source values belong in [weather-data internals](weather-data.md).
 
 ## Contract
 
-`Run` accepts a `context.Context` and a `Request` containing effective
+`Run` receives a context and effective configuration in `Request`. It creates
-`config.Config`. It constructs the Weather API adapter from that configuration,
+the Weather API adapter, calls `FetchBundle`, and returns the adapter's
-calls `FetchBundle`, and returns `Result{Bundle: *weatherdata.Bundle}`.
+normalized bundle in `Result`. Adapter construction errors are wrapped as
+weather-collection setup errors and fetch errors as bundle-collection errors.
 
-The package wraps adapter construction failures as weather-collection setup
+The package neither chooses reports nor derives facts, builds modules, invokes
-errors and fetch failures as bundle-collection errors. It does not retry,
+Promptkit, writes files, or sends notifications. Request scheduling, endpoint
-persist, select reports, derive facts, build modules, invoke Scriptorium, or
+retrieval, response limits, and source-level warnings belong to the Weather
-notify Distributor.
+API adapter and its integration contract.
 
-## Application Composition
+## Application Use
 
-`internal/app` owns the narrow `Collector` interface used by workflow tests;
+`internal/app` owns the `Collector` interface used by report workflows and
-the production implementation delegates to `collect.Run`. Generation, batch
+tests. Its default implementation delegates to `collect.Run`; callers may
-execution, and explicit bundle fetching all use this boundary. Application
+substitute a collector at that boundary. Application orchestration owns
-orchestration rejects a nil collector result or a nil bundle before report work
+collection timing, reuse across a workflow, and the handling of nil collection
-can continue.
+results. See [app orchestration internals](app-orchestration.md) for that
+flow.
 
-Single-report generation and a batch each collect once. A batch passes the same
+## Verification
-normalized collection to planning and to every report it generates. Collection
-failure prevents later workflow work for that request.
 
-## Boundaries And Invariants
+Focused package tests cover a successful fetch and wrapping failures from
+adapter construction and bundle retrieval:
 
-Collection owns adapter creation and retrieval of one normalized bundle. It
+```sh
-must not make report, period, batch, prompt, module, filesystem, or notification
+go test ./internal/collect
-decisions.
+```
-
-- App-facing Weather API collection always passes through this package.
-- The returned value is normalized source data, not facts or prompt input.
-- Context cancellation is passed to the Weather API adapter.
-- Errors retain whether setup or fetching failed.
-
-Focused tests are in `internal/collect/collect_test.go`; orchestration use is
-also covered by `internal/app/app_test.go`.

docs/internal/comparison-execution.md

@@ -0,0 +1,32 @@
+# Comparison Execution Internals
+
+The comparison execution core receives an already prepared report and an
+already inspected, ordered profile list. It initializes an outcome for every
+selected profile, launches each started profile in its own goroutine, and
+waits for every started goroutine before returning. Results retain the supplied
+selection order even though execution completes in an arbitrary order.
+
+Every profile uses the exact inspected prompt identity and a private copy of
+the same prepared data package. Provider, generated-text validation, rendering,
+or debug-write failure becomes that profile's safe failed outcome and does not
+cancel its peers. The shared executor must support those concurrent `Execute`
+calls. The application deliberately imposes no additional semaphore: Promptkit
+owns backend capacity. A profile failure completed before a later cancellation
+remains its original safe outcome; cancellation or a deadline marks only
+unfinished or cancellation-terminated outcomes as skipped or failed, joins work,
+and prevents bundle publication.
+
+When debugging is enabled, each execution receives a deterministic reference
+derived from the comparison identity, ordered profile position, and safe
+profile slug. This keeps concurrent captures separate. The debug writer itself
+owns secure-root validation and file permissions. It safely creates shared
+missing ancestors during concurrent writes, then rejects symlink and non-
+directory components. Operational retention and sensitivity are documented in
+the [operations guide](../operations.md). This secure writer is enabled only on
+Unix hosts; comparison fails before execution when another host requests debug
+capture.
+
+The output result and its safe errors are converted into the durable contract
+only by comparison publication. See [comparison publication
+internals](comparison-publication.md) and the external [comparison bundle
+contract](../integrations/comparison-bundle.md).

docs/internal/comparison-publication.md

@@ -0,0 +1,47 @@
+# Comparison Publication Internals
+
+`internal/comparison` separates the logical bundle from filesystem mechanics.
+The application builds a validated manifest, exact shared data-package bytes,
+and only the Markdown files for successful profiles. The durable layout,
+schema, and compatibility rules are owned by the [comparison bundle
+contract](../integrations/comparison-bundle.md).
+
+Recognition first token-validates the manifest's object fields, rejecting
+unknown, case-variant, and duplicate names before decoding its typed schema.
+Manifest validation derives each successful report filename from its ordered
+position, total profile count, and logical profile ID; logical-bundle and
+filesystem validation then require that exact path and file set.
+
+Destination planning is read-only. It requires an exact absolute target that
+is neither the filesystem root nor the working directory, rejects unsafe
+symlinks and non-directories, accepts a missing or empty directory, and permits
+replacement only for a recognized current bundle. Publication rechecks the
+destination namespace and type immediately before it writes a private sibling
+staging directory. For replacement, it moves the prior bundle to a private
+sibling backup, fully reauthorizes that moved entry, checks for cancellation,
+and restores it if cancellation or installing the new bundle prevents
+replacement. If guarded restoration fails, the error retains the prior bundle's
+recovery path.
+
+Planning also validates the final component and the bounded fixed names used
+for private staging and backup siblings. A destination that cannot form those
+names is rejected before publication creates a missing parent directory; a
+maximum-length valid destination remains usable because transaction siblings do
+not incorporate its basename.
+
+The new bundle is committed only after the staged directory has been installed
+at the target. From that point its artifact paths are authoritative: a failure
+to remove the retained sibling backup does not roll back the new bundle.
+After a cleanup failure, publication inspects the sibling without masking the
+original filesystem cause. Its inspectable cleanup result distinguishes a
+complete recognized recovery bundle, partial remnants, an absent sibling, or
+an uninspectable state. A recovery path is reported only when something
+remains; only a complete recognized bundle is suitable for rollback recovery.
+
+The application preflights before prompt inspection and collection. Publication
+performs its transaction-boundary checks and final moved-destination
+authorization before installation. A cancellation or any failure before the
+commit leaves the prior destination untouched. Completed bundles include
+partial profile results; comparison publication never coordinates Distributor
+notification. Operator-facing lifecycle and cleanup are in the
+[operations guide](../operations.md).

docs/internal/distributor-adapter.md

@@ -13,7 +13,9 @@ the token, an optional timeout, and an injectable upstream-client factory.
 `New` validates its configuration before creating the adapter. For each upload,
 the adapter reads the token from the configured environment variable and builds
 the upstream client with that endpoint, token, and an HTTP client whose timeout
-matches the local positive timeout.
+matches the local positive timeout. Its transport reads at most 1 MiB from any
+Distributor response before the pinned client decodes it; an oversized response
+is a distinct local failure and does not trigger an extra upload attempt.
 
 The upstream client is an implementation dependency, not a source of
 application configuration: retry ownership, pipeline selection, path
@@ -43,20 +45,26 @@ persist notification artifacts.
 An accepted upload is followed by one status request. When a timeout is
 configured, a nonterminal result is polled until `succeeded` or `failed`, or
 until the context ends. The translated `UploadResult` contains the run ID,
-status, and `RunStatus`, including pipeline ID, lifecycle timestamps, report,
+status, and `RunStatus`, including pipeline ID and lifecycle timestamps.
-and remote error details.
+Remote response bodies, status reports, and remote error text are not retained
+in normal results. HTTP failures retain a local typed status-code and
+retryability classification; conflicts retain the local idempotency-conflict
+type.
 
 Status lookup or polling errors are preserved in `UploadResult.StatusError` so
-the caller can record an accepted-but-unconfirmed delivery. A terminal failed
+the caller can report an accepted-but-unconfirmed delivery, using a bounded
-run returns that result and an error. Upload failures return no result. Upstream
+repository-owned diagnostic rather than remote text. A terminal failed run
+returns that result and an error. Upload failures return no result. Upstream
 idempotency conflicts become the local `IdempotencyConflictError`, which adds
 endpoint, pipeline, bundle, idempotency, and file-path context while redacting
 the token.
 
 ## Verification
 
-Focused tests cover configuration validation, request mapping, timeouts and
+Focused tests cover configuration validation, request mapping, response size
-polling, status translation, conflict handling, and token redaction:
+boundaries, safe diagnostics, timeouts and polling, status translation, conflict
+handling, and token redaction. A local HTTP server exercises the production
+upload and status boundary:
 
 ```sh
 go test ./internal/adapters/distributor

docs/internal/facts.md

@@ -16,6 +16,9 @@ story, and convective outlook data. Source provenance and warnings are copied
 into their own slices so downstream consumers can inspect data completeness
 without treating it as an ordinary weather fact.
 
+Alert facts retain individual alert payloads for period selection together with
+their copied source provenance; they do not retain a provider response envelope.
+
 A nil bundle produces an empty collected value. Collection itself, missing
 source policy, and source hashes are outside this package.
 
@@ -26,6 +29,8 @@ uses half-open period overlap to select hourly, narrative, daily, and alert
 data; it also derives precipitation timing. Convective outlooks are retained
 only when their valid interval overlaps the report period, with discussions
 kept for represented outlook days. Both collections are sorted deterministically.
+It rejects collected hourly data with a precipitation probability outside the
+finite 0 through 100 percentage domain before constructing derived facts.
 
 Report identity controls the summary shape:
 
@@ -33,12 +38,12 @@ Report identity controls the summary shape:
 | --- | --- |
 | Hourly | Rolling-period selections and precipitation timing; no daily or daypart summary |
 | Daily, Today, Tomorrow | One local civil-day summary and its dayparts |
-| Three-day, Weekend | One clipped daily summary for each overlapping local day |
-| Storm | One summary for the explicit report window |
 
-`DaypartSummaries` is collected from the resulting daily or storm summaries.
+`DaypartSummaries` is collected from the resulting daily summaries.
 The detailed grouping, daypart-window, and alert rules are owned by
 [forecast derivation](forecast-derivation.md).
+Daily alert overlaps remain scoped to the civil day, while overnight daypart
+summaries retain alerts that overlap their complete next-day window.
 
 ## Missing data and failures
 
@@ -55,13 +60,12 @@ not access the CLI, filesystem, subprocesses, or network.
 ## Verification and invariants
 
 Focused tests cover collected-fact separation, report-period selection,
-hourly and storm behavior, daily and partial-day summaries, and convective
+hourly behavior, daily summaries, and convective outlook selection:
-outlook selection:
 
 ```sh
 go test ./internal/facts
 ```
 
 Facts are derived once for a resolved report from already collected data.
-They remain reusable structured values: prompt wording, state persistence,
+They remain reusable structured values for prompt input and template
-prior-report comparison, and template presentation are owned elsewhere.
+presentation, which are owned elsewhere.

docs/internal/forecast-derivation.md

@@ -2,62 +2,46 @@
 
 `internal/forecast` deterministically selects and summarizes normalized
 forecast data. It has no transport, filesystem, CLI, subprocess, or report
-registry dependency. Its summaries are consumed by
+registry dependency. The report-scoped caller is [fact
-[fact contracts](facts.md) and later module builders.
+contracts](facts.md), which owns the choice of data required by each report.
 
-## Period and daypart semantics
+## Daily Derivation
 
-Selections use `timeutil.Period` half-open overlap: a value is selected only
+`BuildDailySummary` builds one summary for one local civil day. The facts
-when both intervals share time. `BuildDailySummary` creates one local civil
+layer calls it for Daily, Today, and Tomorrow reports; it does not provide a
-day; `BuildPeriodDailySummaries` intersects every local civil day with the
+multi-day or arbitrary-period summary constructor. `timeutil.Period` supplies
-requested period, preserving partial first and last days.
+the shared half-open overlap rule used while selecting source values.
 
-`ResolveDayparts` converts each configured name, start clock, and end clock
+`ResolveDayparts` turns configured local clock ranges into windows. A range
-into a local window. An end clock at or before its start clock wraps into the
+whose end is not after its start continues into the next civil day. The
-next civil day. The daypart and timezone defaults are defined in the
+available daypart and timezone settings are defined in the
-[configuration reference](../config.md), not here.
+[configuration reference](../config.md).
 
-## Deterministic summaries
+The summary keeps selected hourly and narrative values, the discussion,
+source warnings and provenance, alert overlaps, and one summary for each
+resolved daypart. Daypart summaries derive their measurements, conditions,
+weather indicators, and precipitation timing from normalized forecast
+periods. `BuildPrecipTiming` is also available to the facts layer for a
+report's selected hourly periods.
 
-`BuildDailySummary` requires an hourly run with at least one period. It adds
+## Boundaries And Failures
-the selected narrative periods, discussion, alert overlaps, source provenance,
-source warnings, and one `DaypartSummary` per resolved window. A daypart keeps
-its selected hourly periods and derives temperature and apparent-temperature
-ranges, timed precipitation and wind maxima, dominant and notable conditions,
-and weather indicators.
 
-Indicators are deterministic checks over normalized values and condition text:
+Daily-summary construction requires a bundle with hourly forecast data,
-heat, cold, and wind use package-owned numeric cutoffs; snow, ice, fog, and
+valid precipitation probabilities, and valid daypart definitions. Optional
-wind text are detected from the forecast description. `BuildPrecipTiming`
+normalized products remain absent when unavailable. Invalid alerts are ignored
-sorts periods, records the maximum and first precipitation, groups contiguous
+while valid overlaps are selected for the relevant day or daypart window.
-periods at or above its package-owned probability threshold, and records
-thunder mentions.
 
-Alert overlap parsing supports the normalized alert payload's available timing
+Thresholds, text classification, unit normalization, and alert selection are
-fields. Unparseable alerts and invalid intervals are ignored; valid overlaps
+package implementation rules. Report identity, period selection, and the
-are clipped to the requested period and ordered by alert start time.
+resulting derived-fact shape are owned by [fact contracts](facts.md); external
+source semantics are owned by [weather-data internals](weather-data.md).
 
-## Missing data and failures
+## Verification
 
-Empty selections yield empty summary fields rather than generated prose.
+Focused `internal/forecast` tests exercise daily and overnight dayparts,
-Direct daily or period-summary calls fail when their required bundle, valid
+summary derivation, invalid precipitation data, precipitation timing, and
-period, hourly data, or daypart definitions are invalid. A nil location uses
+alert overlap handling. `internal/facts` tests cover the report-scoped caller:
-UTC when these APIs are called directly. Optional narrative, discussion, and
-alerts remain absent when their normalized products are absent.
-
-Forecast thresholds used for brief indicators and precipitation timing are
-implementation rules. User-configurable Recent Changes thresholds are applied
-by [changes internals](changes.md), whose defaults are documented in
-[configuration](../config.md).
-
-## Verification and invariants
-
-Focused tests cover local civil days, clipped periods, daypart resolution,
-summary metrics, precipitation windows, threshold helpers, and alert overlap:
 
 ```sh
-go test ./internal/forecast ./internal/timeutil
+go test ./internal/forecast ./internal/facts
 ```
-
-The package preserves normalized inputs as inspectable structured values and
-never decides report identity, delivery, or presentation wording.

docs/internal/generatedtext.md

@@ -8,33 +8,56 @@ maintainer-facing context fields belong to [report templates](../templates.md).
 
 ## Catalog and validation
 
-Only the Daily, Today, Tomorrow, and Hourly report definitions use the
+The Daily, Today, Tomorrow, and Hourly report definitions each use structured
-generated-text-template mode. `LookupDefinition` rejects a direct-Markdown
+generated text. `LookupDefinition` requires the exact report, schema, and
-definition, unknown schema or template IDs, and unsupported schema/template
+template triple and rejects unknown IDs, unsupported pairs, and a pair that
-pairs before the run begins. A handler validates raw JSON, returns a typed
+belongs to another report before the run begins. A handler validates and
-value and canonical normalized JSON, loads its schema, builds a render context,
+normalizes raw JSON into a typed value, loads its canonical schema through
-and renders through `internal/reporttemplate`.
+`internal/promptassets`, builds a render context, and renders through
+`internal/reporttemplate`.
 
 Daily, Today, and Tomorrow use a day-style value with required trimmed summary
 and one or more nonblank discussion paragraphs. Hourly requires trimmed summary
-and a single trimmed discussion string. Each form permits optional trimmed
+and a single trimmed discussion string. Every form also requires the
-precipitation-timing and confidence prose. Typed decoding rejects unknown JSON
+`precipitation_timing` field; an empty string means there is no supported timing
-fields; no general-purpose JSON Schema engine is used at runtime.
+prose to render. Typed decoding requires the exact lowercase JSON field names,
+rejects missing, duplicate, case-variant, and unknown fields, and checks field
+shapes; no general-purpose JSON Schema engine is used at runtime.
+
+The validator accepts at most 64 KiB of raw JSON before it allocates typed
+values. Its JSON Schemas and typed checks limit `summary` and
+`precipitation_timing` to 4,000 characters each. Hourly
+`forecast_discussion` is limited to 12,000 characters. Day-style discussion
+accepts at most 12 paragraphs of at most 4,000 characters each. Across all
+prose fields, one report may contain at most 20,000 characters. These bounds
+apply before trimming, filtering, normalization, and template rendering.
+
+Malformed JSON and field values return short, content-safe errors. They name
+only canonical fields where useful and never echo provider values or unknown
+field names. The Promptkit adapter also drops an oversized provider result
+before copying it into execution or debug state; direct executor implementations
+receive the same enforcement in this package.
 
 ## Render contexts
 
-The catalog's report-specific builders receive briefing metadata, a rich module
+The catalog's report-specific builders receive the prepared report identity, a
-snapshot, collected facts, derived facts, and the matching validated generated
+rich module snapshot, derived facts needed to order dayparts, and the matching
-text. They decode the module stanzas needed by the template and build typed
+validated generated text. They require the identity's report ID to match the
-Daily, Today, Tomorrow, or Hourly contexts. Context construction validates
+selected builder. When the optional metadata stanza is present, every shared
-metadata and periods, preserves rich module values, and uses ordered slices for
+identity field must agree with that prepared authority before context
-template iteration rather than maps.
+construction continues. Builders then decode the module stanzas needed by the
+template and build typed Daily, Today, Tomorrow, or Hourly contexts. Contexts
+expose only display-ready report values, generated prose, and module values;
+they do not expose complete collected or derived fact bundles. Ordered slices
+remain the template iteration surface rather than maps.
 
-Optional source stanzas become nil or fallback context fields. Missing required
+Optional source stanzas become nil or fallback context fields. Today also
-stanzas, type-decoding failures, invalid metadata, or a generated-text type
+computes whether its ordered dayparts contain a displayable condition so the
-that does not match the chosen handler fail before template execution. Prompt
+template can render either rows or its explicit no-details fallback. Missing
-packages, raw Scriptorium output, state persistence, and template asset lookup
+required stanzas, type-decoding failures, conflicting identity values, invalid
-remain outside this package.
+metadata, or a generated-text type that does not match the chosen handler fail
+before template execution. Prompt packages, raw Promptkit output handling, and
+template asset lookup remain outside this package.
 
 ## Verification and invariants
 
@@ -47,5 +70,7 @@ go test ./internal/generatedtext
 ```
 
 Generated text supplies prose slots only; deterministic weather facts remain in
-module and fact values. Every generated-text definition must resolve to exactly
+module and fact values. The renderer applies its plain-text policy to every
-one supported catalog pair.
+generated prose insertion, preserving ordinary text and paragraph breaks while
+preventing provider text from creating Markdown or HTML structure. Every report
+definition must resolve to exactly one supported catalog pair.

docs/internal/module.md

@@ -1,7 +1,7 @@
 # Module Contract Internals
 
-`internal/module` defines the stable envelope between report composition,
+`internal/module` defines the envelope between report composition,
-module builders, snapshots, comparisons, templates, and prompt packages. It
+module builders, in-memory snapshots, templates, and prompt packages. It
 does not define a report, execute a builder, or choose prompt-export policy;
 those responsibilities belong to [report registry](report-registry.md) and
 [briefing](briefing.md).
@@ -11,10 +11,10 @@ those responsibilities belong to [report registry](report-registry.md) and
 Each `Output` has a module ID, stanza name, rich `Value`, and runtime-only
 `PromptValue`. `DataPackageValue` returns the prompt value when present and
 otherwise the rich value. This permits custom prompt exports without shrinking
-the template and inspection value.
+the template value.
 
-`NewSnapshot` builds the ordered `weatherreporter.modules.v1` snapshot and
+`NewSnapshot` builds and validates the ordered in-memory snapshot. Its JSON
-validates it. Snapshot JSON persists IDs, stanza names, and rich values only;
+representation carries a package-owned schema marker, IDs, stanza names, and rich values only;
 `PromptValue` is deliberately excluded. `StanzaValue` decodes a named rich
 stanza into a caller-supplied type, reporting a missing stanza separately from
 a decoding error.
@@ -39,17 +39,16 @@ The registry declares these ordered default compositions:
 | Today | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows, hourly forecast, today planning |
 | Tomorrow | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows, tomorrow planning, hourly forecast |
 | Hourly | metadata, current conditions, hourly forecast, precipitation timing, alert digest, SPC outlooks, AFD (key messages and short term), SPC discussion, weather story |
-| Three-day and Weekend | metadata, current conditions, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows |
-| Storm | metadata, current conditions, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story |
 
 The only non-empty default option is the AFD section selection. It accepts a
 `sections` list; omitted or empty selects all available sections. Report
 definitions may narrow it as shown above. Option shape and report compatibility
-are validated by the briefing registry.
+are validated by the briefing registry. Accepted typed option pointers are
+canonicalized to the declared value type before a module builder receives them.
 
 ## Rich and prompt-facing values
 
-Rich values remain available to snapshots, comparisons, and render contexts.
+Rich values remain available to module snapshots and render contexts.
 Briefing attaches custom prompt exports only for current conditions, hourly
 forecast, and derived daypart summaries; all other current builders use
 pass-through values. The prompt package owns how exported stanzas are grouped

docs/internal/prepared-report.md

@@ -0,0 +1,38 @@
+# Prepared Report Internals
+
+`internal/app` validates the report's generated-text catalog binding during
+prompt inspection, before collection, and carries the resulting handler into
+`preparedReport` construction after collection. This is the immutable boundary
+shared by ordinary report generation and profile comparison; it is not a
+durable artifact.
+
+Preparation first establishes one `PreparedIdentity` for the report run, report
+and prompt IDs, variant, generation time, units, timezone, valid period,
+location, and source warnings. It passes that identity to the configured module
+snapshot, curated prompt-input package, serialized YAML, generated-text render
+context, and generated-text definition. Each boundary projects only the fields
+it needs from that prepared authority.
+
+Preparation deep-copies mutable facts, snapshots, identity, and data-package
+bytes before returning them. Consumers receive independent copies so one
+execution cannot change another's input or rendering context.
+
+Before accepting generated JSON, the execution boundary reconciles the prepared
+report definition, inspected prompt hash and selected profile identity, the one
+preparation callback, and the completed Promptkit result. The callback and
+completion must agree on prompt, profile, backend, model, and rendered/input
+hashes; the callback output must also carry the prepared report's configured
+repair budget, while the completed validation records the actual corrective
+calls used within that budget. A mismatch produces no rendered Markdown and leaves
+results with only the inspected safe identity.
+
+Single-report generation executes one prepared profile and publishes its
+Markdown. Comparison prepares once, gives every selected profile the same YAML
+bytes, and only then assembles the resulting logical bundle. The prompt-input
+shape is owned by [prompt-input internals](prompt-input.md); profile execution
+semantics are owned by [Promptkit integration](../integrations/promptkit.md).
+
+Catalog incompatibility stops prompt inspection before weather collection or
+model work. Preparation failure has no publication side effects. Tests for this
+boundary cover catalog-preflight ordering, mutation isolation, byte equality,
+and reuse by both execution paths.

docs/internal/prompt-input.md

@@ -1,61 +1,36 @@
 # Prompt Input Internals
 
-`internal/promptinput` converts report metadata, an ordered module snapshot,
+`internal/promptinput` turns prepared report metadata and an ordered module
-Recent Changes, and source warnings into the YAML `data_package` consumed by
+snapshot into the YAML data package passed to Promptkit. The externally visible
-Scriptorium. It owns this package's schema, grouping, serialization, loading,
+prompt and inline-input contract is owned by the [Promptkit integration
-and validation—not weather collection, module construction, path choice, or
+guide](../integrations/promptkit.md); preparation of the inputs is owned by
-subprocess execution.
+[prepared report internals](prepared-report.md).
 
-## Package construction
+## Package Construction
 
-`Build` produces `weatherreporter.data_package.v3`. It copies the run ID;
+`Build` projects report identity, the report-local current date, source-warning
-report ID, variant, prompt ID, generation time, timezone, local current date,
+summaries, and each snapshot output's prompt-facing value into a package. It
-and valid period; ordered briefing stanzas; Recent Changes; and source
+does not expose source transport or provenance details. The module snapshot
-warnings. A nil Recent Changes slice becomes an empty `items` list.
+defines stanza order and selects curated prompt values; the corresponding
+module contracts are documented in [module internals](module.md) and [briefing
+internals](briefing.md).
 
-Briefing starts as a flat snapshot order and stanza-value map. `Build` uses
+`MarshalYAML` validates the package before serializing it. Serialization emits
-each output's `DataPackageValue`, so runtime prompt exports take precedence and
+the metadata stanza first, then groups the remaining recognized stanzas in the
-rich values are used only as a fallback. Prompt exports are selected by the
+package's fixed category order while preserving snapshot order within a
-[briefing registry](briefing.md), while the rich-versus-prompt contract is in
+category. `Validate` enforces the supported schema version, required report
-[module internals](module.md).
+identity and period values, and a nonempty, complete ordered briefing.
 
-## YAML ordering and grouping
+This package does not collect weather, choose an output destination, execute a
+provider, or persist data packages. The application passes its in-memory YAML
+to the Promptkit adapter as part of prepared report execution.
 
-Serialization keeps `metadata` directly under `briefing`. Every other known
+## Verification
-stanza is placed in exactly one category, emitted in category order and in its
-original snapshot order within that category:
 
-| Category | Current stanzas |
+Focused tests cover package construction, report-local dates, validation,
-| --- | --- |
+curated snapshot exports, deterministic YAML grouping, and safe source-warning
-| `applicable_risk_products` | alert digest, SPC convective outlooks |
+projection:
-| `derived_summaries` | deterministic summaries, precipitation timing, outdoor windows, and planning values |
-| `narrative_products` | narrative forecast, discussions, and weather story |
-| `raw_data` | current conditions and hourly forecast |
-
-This YAML presentation does not alter the flat snapshot model. `LoadYAML`
-accepts the same category layout and reconstructs flat `Order` and `Values`,
-rejecting misplaced, duplicate, unknown, or uncategorized stanzas.
-
-## Validation and persistence
-
-`Validate` requires the current schema version, run and report identifiers,
-prompt ID, generation timestamp, timezone, current local date, valid period,
-and at least one ordered briefing stanza. It rejects duplicate stanza names,
-missing values, and a missing category for every non-metadata stanza.
-
-`MarshalYAML` and `LoadYAML` validate their result. `Save` writes the serialized
-YAML atomically; managed workspace paths are owned by [state internals](state.md).
-Generated-text artifacts and template render contexts are later workflow
-artifacts, not members of this package.
-
-## Verification and invariants
-
-Focused tests cover construction, curated exports, category ordering, YAML
-round trips, invalid layout, validation, and atomic saves:
 
 ```sh
 go test ./internal/promptinput
 ```
-
-The package is narrower than a template render context and never infers changes
-from report prose.

docs/internal/promptkit-adapter.md

@@ -0,0 +1,17 @@
+# Promptkit Adapter Internals
+
+`internal/adapters/promptkit` maps Weatherreporter's project-owned executor contract to Promptkit. The CLI maps `promptkit` configuration to a `PromptExecutorConfig` and constructs one executor per action. Promptkit dependency types do not escape the adapter.
+
+The adapter supplies Weatherreporter's embedded prompt, schema, and fallback profile filesystems to each engine. Promptkit resolves configured operator profile sources, embedded profile aliases and their bases, and its built-in catalog; the adapter does not parse profile YAML, resolve inheritance, merge sources, inspect optional environment credentials, or probe endpoints.
+
+The adapter exposes exact prompt and profile validation plus prepared execution. It maps safe prompt identity, logical profile, effective backend/model, preparation, execution, validation, and optional debug values into `promptexec`. An empty backend identity remains valid for an endpoint-only profile; a nonblank model is required. PromptKit's configured repair-call budget and the completed result's actual corrective-call count are retained, along with its cumulative provider usage and final candidate. Structured provider generation failures become project-owned redacted generation errors that retain only bounded details through explicit accessors. `Execute` passes the YAML package as an inline Promptkit input; it does not construct a filesystem URI or write a package file.
+
+The application uses the preparation callback to record active safe provenance in memory and optionally writes content-rich diagnostics only through an explicit debug writer. The adapter returns raw output for application validation and rendering. It does not retain application state, render Markdown, choose report definitions, or send Distributor notifications.
+
+Focused tests:
+
+```sh
+go test ./internal/adapters/promptkit ./internal/cli ./internal/app
+```
+
+The public logical prompt/profile/schema contract is owned by the [Promptkit integration guide](../integrations/promptkit.md).

docs/internal/report-registry.md

@@ -1,76 +1,38 @@
 # Report Registry Internals
 
-`internal/report` owns the registry of report identities and the data declared
+`internal/report` owns the in-process registry of report identities and the
-for each one: resolution, generation mode, prompt identity, comparison policy,
+resolution of a report's valid period. Command names and configuration aliases
-artifact group, output-copy name, default module composition, and Distributor
+belong to the [CLI reference](../cli.md) and [configuration
-path declarations. The public command syntax is owned by the
+reference](../config.md), respectively.
-[CLI reference](../cli.md); configuration aliases and overrides are owned by
-the [configuration reference](../config.md).
 
-## Definitions and resolution
+## Registry And Resolution
 
-Each `Definition` declares a stable ID and display name, prompt ID, generation
+`DefaultRegistry` supplies the maintained definitions. `Lookup` returns a
-mode, optional template and generated-text schema IDs, valid-period resolver,
+definition by its internal ID, while `Resolve` combines it with a request time,
-comparison strategy, artifact group, batch-copy filename, Distributor path
+location, and optional date to produce `Resolved`. The result carries the
-templates, generation eligibility, compatible prior IDs, default modules, and
+definition, generation time, timezone, and resolved valid period; its metadata
-batch eligibility flags. `Resolved` combines that definition with the valid
+and output-name helpers keep derived identity values consistent for callers.
-period and run metadata for one invocation.
 
-| Report ID | Mode | Period policy | Comparison | Registry batch flag | Output copy |
+Definitions carry the internal collaborators needed downstream: prompt and
-| --- | --- | --- | --- | --- | --- |
+template identity, module configuration, output naming, Distributor path
-| `daily` | Generated text + template | Explicit local civil day | Same valid date | Dynamic Daily inclusion is app-owned | `daily.md` |
+templates, and fixed batch eligibility. The external prompt contract is owned
-| `today` | Generated text + template | Selected or current local civil day | Same valid date | Morning | `today.md` |
+by the [Promptkit integration guide](../integrations/promptkit.md), template
-| `tomorrow` | Generated text + template | Next local civil day | Same valid date | Evening | `tomorrow.md` |
+surface by the [report template guide](../templates.md), and published
-| `hourly` | Generated text + template | Rolling six-hour interval | Rolling window | — | `hourly.md` |
+Distributor paths by the [Distributor bundle guide](../integrations/distributor/pkg-bundle.md).
-| `three_day` | Scriptorium Markdown | Generation time through the third following local midnight | Same valid date | Morning | `three-day.md` |
-| `weekend` | Scriptorium Markdown | Upcoming weekend window | Weekend window | Morning | `weekend.md` |
-| `storm` | Scriptorium Markdown | Caller-supplied event window | Explicit window | — | `storm.md` |
 
-The four generated-text reports pair their report ID with matching template and
+`WithModuleOverrides` returns an independently cloned registry with replacement
-schema IDs. The three direct-Markdown reports leave both IDs empty. Exact
+module configuration for recognized report IDs. The application owns batch
-template fields and schema assets belong to [report templates](../templates.md)
+planning and data-dependent inclusion; see [app orchestration
-and [generated-text internals](generatedtext.md).
+internals](app-orchestration.md).
 
-All valid periods are half-open. Storm accepts local `YYYY-MM-DDTHH:MM` values
+The registry never collects weather data, parses CLI flags, writes output,
-in the effective report timezone or offset-bearing RFC3339 values; its end
+executes Promptkit, or delivers a report.
-must follow its start. Resolving Weekend directly on Sunday is rejected.
 
-## Registry collaborators
+## Verification
 
-`DefaultRegistry` is the only source of the seven report definitions.
+Focused tests protect retained report definitions, period resolution, Daily
-`Lookup`, `Resolve`, and report-name helpers prevent callers from duplicating
+run-ID disambiguation, and rejection of retired command or configuration names:
-report identity rules. Registry overrides clone a definition and replace its
-module list only after the report ID is recognized.
-
-The definition's `DistributorPathTemplates` are internal declarations consumed
-by app orchestration. Their rendered external bundle paths and compatibility
-contract are documented in the [Distributor bundle guide](../integrations/distributor/pkg-bundle.md), not repeated here.
-
-`morning` and `evening` are registry-owned batch names. Registry flags declare
-fixed report eligibility; app orchestration determines data-dependent Daily
-membership and produces the actual batch plan.
-
-## Module composition and failures
-
-Each definition supplies an ordered `[]module.ConfigItem`; the complete
-report-to-module mapping is maintained in [module internals](module.md).
-`ArtifactGroup`, `BatchOutputName`, `Generated`, and comparison compatibility
-are likewise consumed by state and orchestration rather than recomputed there.
-
-Unknown report IDs or batch names, an invalid weekend resolution, and invalid
-storm windows return errors. The registry never collects weather data, builds
-modules, parses CLI flags, writes state, executes Scriptorium, or delivers a
-report.
-
-## Verification and invariants
-
-Focused tests cover definition completeness, command and alias lookup, period
-resolution, run IDs, path declarations, composition defaults, and override
-validation:
 
 ```sh
 go test ./internal/report
 ```
-
-All report selection goes through the registry, and the registry is the source
-of truth for report identity—not rendered report text or app-local constants.

docs/internal/reporttemplate.md

@@ -1,22 +1,21 @@
 # Report Template Internals
 
 `internal/reporttemplate` embeds and renders the repository's native Markdown
-templates and exposes their companion generated-text schemas. The current asset
+templates. The current template IDs are `daily`, `today`, `tomorrow`, and
-IDs are `daily`, `today`, `tomorrow`, and `hourly`. The template files, partials,
+`hourly`. The template files, partials, and complete render-context field
-and complete render-context field reference are maintained in
+reference are maintained in
 [report templates](../templates.md).
 
 ## Assets and lookup
 
-The package embeds top-level templates, shared partials, and JSON schemas from
+The package embeds top-level templates and shared partials. `Template` returns
-its asset directories. `Template` and `Schema` return the requested embedded
+the requested embedded template and fails with the requested ID when it is
-asset and fail with the requested ID when it is unknown or unreadable.
+unknown or unreadable.
 
-Generated-text catalog handlers obtain schema bytes and template source through
+Generated-text schemas and Promptkit definitions are owned by
-these APIs. Prompt source files are repository assets for prompt registration;
+`internal/promptassets`; report-template owns Markdown source only. Report
-they are not reporttemplate lookup assets. Report definitions select IDs, while
+definitions select IDs, while [generated-text internals](generatedtext.md)
-[generated-text internals](generatedtext.md) verifies the supported
+verifies the supported schema/template pairing.
-schema/template pairing.
 
 ## Rendering
 
@@ -29,23 +28,29 @@ failures actionable with template or partial context.
 Top-level templates decide which shared partials they invoke. The current
 partials cover daypart forecast variants, alert digest, and precipitation
 timing. Template code receives curated typed contexts rather than raw data
-packages, and it must not reimplement weather selection or generated-text
+packages or complete fact bundles, and it must not reimplement weather
-validation.
+selection or generated-text validation. Context construction rejects
+report-identity disagreements before template execution. Every generated-prose
+insertion uses the `plainText` helper. It retains ordinary prose and paragraph
+breaks but renders Markdown/HTML syntax, code indentation, and control
+characters as safe text, so the repository templates remain the sole owners of
+report structure.
 
 ## Boundaries and verification
 
 This package does not collect weather data, build modules, validate generated
 text, construct contexts, resolve report definitions, write state, execute
-Scriptorium, or upload reports. It produces Markdown bytes for application
+Promptkit, or upload reports. It produces Markdown bytes for application
 orchestration to persist.
 
-Focused tests cover asset lookup, schema availability, rendering, partial
+Focused tests cover template lookup, rendering, partial behavior, daypart
-behavior, missing keys, and malformed context:
+fallbacks, missing keys, and malformed context:
 
 ```sh
 go test ./internal/reporttemplate
 ```
 
-Embedded assets stay as separate files, shared fragments stay under the partial
+Embedded templates stay as separate files and shared fragments stay under the
-directory, and generated-text schemas describe prose slots rather than
+partial directory. Generated-text schemas are embedded separately by
-deterministic weather facts.
+`internal/promptassets` and describe prose slots rather than deterministic
+weather facts.

docs/internal/scriptorium-adapter.md

@@ -1,51 +0,0 @@
-# Scriptorium Adapter Internals
-
-`internal/adapters/scriptorium` translates Weatherreporter render requests to
-Scriptorium process arguments and translates process results back to local
-types. The external CLI and output contract belongs to the
-[Scriptorium integration guide](../integrations/scriptorium.md); prompts,
-template inputs, and report ownership remain outside this adapter.
-
-## Request-to-command translation
-
-`Runner` accepts a binary, config path, profile, timeout, extra arguments, and
-an injectable command executor. Its defaults are the `scriptorium` binary and
-the real `ExecRunner`. Optional configuration flags are placed before the
-operation-specific arguments, and extra arguments are appended last.
-
-| Local operation | Required values | Translated arguments |
-| --- | --- | --- |
-| `Render` | prompt ID, data-package path | `render [--config …] [--profile …] --prompt <id> --input data_package=<path> --format json [extra …]` |
-| `Run` | prompt ID, data-package path, output path | `run [--config …] [--profile …] --prompt <id> --input data_package=<path> --out <path> [extra …]` |
-| `StructuredRun` | prompt ID, data-package path, output path | Same translation as `Run` |
-
-Blank required values fail before a command starts. The adapter does not add
-schema flags or interpret a prompt's payload; it only gives Scriptorium the
-named `data_package` input.
-
-## Command execution and result translation
-
-`ExecRunner` uses `exec.CommandContext`, never a shell. A positive configured
-timeout creates a child context. Standard output and standard error are
-captured independently, each with a 1 MiB limit, and the executed command is
-retained for diagnostics.
-
-`RenderResult`, `RunResult`, and `StructuredRunResult` expose the command,
-captured output, truncation markers, and exit code. Run results also retain the
-requested output path. Exit status zero is successful. A nonzero process exit
-returns its result and an error, while a start failure, cancellation, or
-deadline failure returns no result and the execution error.
-
-The adapter does not parse rendered JSON, validate a generated report, write
-state, or upload a report. Those responsibilities sit with
-[application orchestration](app-orchestration.md), [state internals](state.md), and the
-relevant delivery adapter.
-
-## Verification
-
-Focused tests cover argument order, validation, bounded capture, timeout and
-cancellation handling, and exit-status translation:
-
-```sh
-go test ./internal/adapters/scriptorium
-```

docs/internal/state.md

@@ -1,91 +0,0 @@
-# State Internals
-
-The `internal/state` package owns filesystem-backed run state: safe path
-derivation, metadata persistence, prior-report lookup, and read-only report
-inspection. It does not decide which reports to generate or deliver. For the
-operator-facing layout and retention procedures, see the
-[operations guide](../operations.md).
-
-## Store construction and artifact paths
-
-`NewFilesystemStore` requires a workspace root and rejects absolute or
-escaping values for every configured state directory. `Paths` then validates a
-run ID and artifact group before deriving all paths from the report's valid
-start date (`YYYY-MM-DD`). This keeps a run's artifacts together while making
-the paths safe to use below the configured workspace.
-
-| Artifact | Derived location |
-| --- | --- |
-| Module snapshot | `snapshots/<group>/<date>/modules.<run-id>.json` |
-| Metadata | `snapshots/<group>/<date>/metadata.<run-id>.json` |
-| Data package | `data-packages/<group>/<date>/data_package.<run-id>.yaml` |
-| Render preflight | `preflight/<group>/<date>/render.<run-id>.json` |
-| Notification record | `notifications/<group>/<date>/distributor.<run-id>.json` |
-| Managed report | `reports/<group>/<date>/report.<run-id>.md` |
-| Generated text | `snapshots/<group>/<date>/generated_text.<run-id>.json` |
-| Generated-text source and result | `snapshots/<group>/<date>/generated_text_raw.<run-id>.json` and `generated_text_result.<run-id>.json` |
-| Generated-text render context | `snapshots/<group>/<date>/render_context.<run-id>.json` |
-
-The configured notification root separates notification artifacts from report
-artifacts; single-report notification paths use the report's valid date. Report
-producers create parent directories as needed and write the report body; state
-is responsible for the surrounding paths and saved run artifacts.
-
-Batch Distributor notifications are derived separately as
-`notifications/batches/<batch>/<local-date>/distributor.<batch-run-id>.json`.
-Their date is calculated from the batch start in its configured location, and
-the batch identity and run ID receive the same path-segment validation as
-single-report artifact identifiers.
-
-## Metadata and durable writes
-
-`Metadata` is the durable inventory for a run. It records its schema version,
-run identity, generated and valid timestamps, artifact group and mode, source
-content and provenance, and the module snapshot, data-package, preflight,
-report, generated-artifact, and notification locations when present.
-
-`BuildMetadataFromBriefingMetadata` establishes the common fields; the
-application adds locations as artifacts are produced. `SaveMetadata` requires
-the run ID and the module snapshot, data-package, preflight, and metadata
-paths. The package also saves module snapshots, data packages, preflight
-records, generated-text artifacts, render contexts, and notifications. JSON
-writes use `fileutil.WriteJSONAtomic`, so readers do not observe a partially
-written state file.
-
-The data package itself follows the shared
-[prompt-input contract](prompt-input.md). Report text, templates, and external
-delivery payloads remain owned by their respective packages and integration
-references.
-
-## Prior reports and inspection
-
-`FindPriorSnapshot` searches metadata rather than guessing from filenames. It
-only considers an earlier compatible report in the same artifact group and
-supports the comparison strategies defined by the report request:
-
-- `same_valid_date` finds an earlier generated report for the same valid day.
-- `weekend_window` finds a prior comparable weekend window.
-
-The newest eligible metadata record wins; the current run is excluded.
-Unreadable or malformed candidate metadata is ignored so a damaged historical
-record does not block a new run.
-
-`ListReports` walks saved metadata, returns results ordered newest-first by
-generation time, and treats a missing snapshots directory as an empty history.
-`LoadMetadataByRunID` builds on that inspection path. These APIs are read-only;
-repairing or pruning stored state is an operational concern.
-
-## Boundaries and verification
-
-The package rejects unsafe path components and incomplete metadata before
-writing. Callers must provide a valid report request, artifact group, and
-store configuration. Its focused tests cover path derivation, atomic
-persistence, metadata validation, comparison eligibility, and report listing:
-
-```sh
-go test ./internal/state
-```
-
-See [application orchestration](app-orchestration.md) for the order in which
-these artifacts are created and [report templates](../templates.md) for the
-user-facing report contract.

docs/internal/weather-data.md

@@ -1,7 +1,7 @@
 # Weather Data Internals
 
 `internal/weatherdata` owns the normalized, wire-independent weather bundle
-that passes from collection through rendering and persistence. The Weather API
+that passes from collection through rendering. The Weather API
 adapter translates provider responses into these types; its request, response,
 and availability contract is documented in the
 [Weather API integration guide](../integrations/weatherapi.md).
@@ -31,6 +31,10 @@ provider endpoint or retry policy from the normalized types. See
 [collection](collect.md) for assembly and
 [report templates](../templates.md) for the values exposed to authors.
 
+An alert run retains its check time and individual alert payloads for overlap
+selection. Its source entry retains provider provenance; the full provider
+envelope is not carried into the normalized bundle.
+
 ## Source provenance
 
 Every checked source is represented by a `Source` entry. The record identifies
@@ -45,6 +49,10 @@ marked missing only when the adapter's missing-source policy treats the
 response or parsing failure as unavailable. The policy itself belongs to the
 [configuration reference](../config.md).
 
+Accepted hourly forecast periods always have nonzero start and end times, with
+the end after the start. Collection rejects a required hourly product that does
+not meet those bounds before it enters downstream derivation.
+
 ## Warning semantics
 
 `SourceWarning` has a source name, stable code, severity, explanatory message,
@@ -54,8 +62,7 @@ local provenance and whole-run consumers see it. A policy that treats a missing
 source as an error returns no partial bundle.
 
 Warnings describe data completeness, not rendering or delivery failures.
-Those failures are recorded by the application and state layers; see
+Those failures are reported by [application orchestration](app-orchestration.md).
-[application orchestration](app-orchestration.md) and [state internals](state.md).
 
 ## Boundaries and verification
 

docs/operations.md

@@ -1,156 +1,235 @@
 # Weatherreporter Operations
 
-This guide covers normal operation, managed workspace state, inspection,
+This guide covers normal output handling, Distributor notification, secure
-recovery, and operational caveats. See the [CLI reference](cli.md) for complete
+prompt diagnostics, and cleanup of legacy application state. See the [CLI
-command syntax and the [configuration reference](config.md) for fields,
+reference](cli.md) for command syntax and the [configuration reference](config.md)
-defaults, and notification templates. For symptom-based diagnosis, see
+for fields, defaults, and notification templates.
-[Troubleshooting](troubleshooting.md).
 
 ## Normal Operation
 
 After configuring a Weather API endpoint, generate one report:
 
 ```sh
-weatherreporter generate today --out ./today.md
+weatherreporter generate today
 ```
 
-A generation collects weather data, resolves the report period, builds and
+With no configured output directory, the command writes `today.md` in the
-persists the module snapshot and prompt data package, runs Scriptorium
+current directory. Set `output.directory` to use one ordinary publication
-preflight, then produces the managed Markdown report. Daily, Today, Tomorrow,
+directory for reports, or choose a one-command operator-owned file with
-and Hourly reports additionally persist generated-text artifacts, validate the
+`--out`; a relative path is resolved from the current directory and an absolute
-structured generated text, and render Markdown from the validated text and
+path is used directly. The explicit flag takes precedence over the configured
-deterministic values.
+directory. Weatherreporter renders in memory and atomically replaces the
+selected destination only after generation and rendering succeed. It does not
+create a default workspace, metadata, receipts, or intermediate output files.
 
-The managed report and its final metadata are saved before single-report
+A missing configured directory is created only as part of successful report
-Distributor notification is attempted. `--out` writes an extra operator copy;
+publication. If its existing path is not a directory or cannot be inspected,
-it never changes the managed report or upload source. A successful generate
+the command stops before prompt inspection or weather collection, leaving any
-command prints its summary to stdout unless `--quiet` is used.
+existing report unchanged. See the [configuration reference](config.md) for the
+field definition and validation rules.
 
-Run a scheduled batch with the same configured collection:
+Before a destination is published, provider, validation, rendering, write, and
+cancellation failures leave an existing report unchanged. A notification
+failure happens after publication, so retain and use the completed Markdown
+file while resolving the delivery error. The JSON result identifies the
+absolute output path and active profile, backend, model, warnings, validation,
+debug, and notification information; see the [CLI reference](cli.md) for its
+exact fields.
+
+Weatherreporter validates the final output filename before prompt inspection or
+weather collection. A valid long filename is published through a short,
+same-directory temporary sibling, so temporary naming does not shorten the
+operator-selected destination. A rejected filename does not create a missing
+parent directory. The final destination itself must be absent or a regular
+file: symlinks, directories, named pipes, sockets, and other special objects
+are rejected before prompt inspection or weather collection. The destination is
+checked again immediately before the atomic replacement; cancellation or a
+deadline at that point leaves the prior report unchanged and skips notification.
+
+`SIGINT` and `SIGTERM` request orderly cancellation of an active action. The
+command lets cancellation and related cleanup finish before it exits; use the
+usual failed result or error to determine whether an output was published.
+
+## Batch Outputs And Distributor Notification
+
+Run a scheduled batch with an explicit output directory when appropriate:
 
 ```sh
 weatherreporter run morning --out-dir ./reports
 ```
 
-Each batch collects once before it plans reports. Morning runs Today, Tomorrow,
+Without `--out-dir`, batch reports are written beneath `output.directory` when
-and every eligible dated Daily Report; evening runs Tomorrow and the same
+configured, otherwise the current directory. The explicit directory applies
-eligible Daily Reports. Eligible Daily dates begin after tomorrow and require
+only to that command and takes precedence over the configured fallback.
-complete hourly coverage for their entire local civil day. A batch continues
+Morning runs Today, Tomorrow, and every eligible dated Daily Report; evening
-after an individual report fails and returns an aggregate failure when any
+runs Tomorrow and the same eligible Daily Reports. Eligible Daily dates begin
-report or batch notification fails.
+after tomorrow and require complete hourly coverage for their local civil day.
+A batch collects once, determines the complete report set, and validates every
+final output destination before executing its first report prompt. A destination
+collision, such as a directory named `tomorrow.md`, stops the batch before any
+report output is created or replaced. After successful validation, each selected
+report processes independently and successful outputs remain available if
+another report fails. If cancellation or a deadline is observed during the
+sequence, Weatherreporter stops before starting another report. It retains
+already published files, marks interrupted and unstarted reports as canceled in
+the result, and skips batch notification.
 
-`--out-dir` writes extra copies such as `today.md`, `tomorrow.md`, and
+When `notify.distributor.enabled` and batch notification are enabled,
-`daily-YYYY-MM-DD.md`. These copies are never upload sources. Batch report
+Weatherreporter sends one Distributor upload only after every selected output
-copies and notification behavior are summarized in the CLI result; use the
+exists. If an item fails, the batch notification is skipped and successful
-[CLI reference](cli.md) for its exact JSON and stderr contract.
+files remain at their selected destinations. A batch notification failure also
+leaves all successfully published report files in place. Distributor source
+files are those operator-owned Markdown outputs; rendered bundle paths and
+delivery status appear in the result, not in a local notification receipt.
+Remote Distributor response text is not included in command output. Instead,
+notification failures use stable local diagnostics while retaining the upload
+and status identities needed to investigate delivery with Distributor.
+Report counters count report items only. A batch notification failure therefore
+returns a failed batch status even when all report counters show success; the
+top-level notification result contains the delivery diagnostic.
 
-## Managed Workspace
+For a single report, Distributor notification follows the atomic output write.
+Enabled notification configuration, including the HTTP(S) endpoint and
+templates, is validated before report processing. A malformed endpoint does not
+collect weather data, generate a report, publish output, or invoke Distributor.
+See the [configuration reference](config.md) for endpoint, pipeline, bundle,
+idempotency-key, and per-report path templates.
 
-The default workspace root is `workspace`. Artifact paths use the report
+## Comparison Bundles
-definition's artifact group, the valid-period start date in the effective
-timezone, and the RunID:
 
-```text
+Use `compare` when an operator needs to evaluate explicit Promptkit profiles
-workspace/
+against the same report input. The command writes one flat, operator-owned
-  reports/<artifact_group>/<YYYY-MM-DD>/report.<run_id>.md
+bundle directory and never sends a Distributor notification. Command syntax,
+profile validation, JSON output, and exit behavior belong to the
+[CLI reference](cli.md); the durable file contract belongs to the
+[comparison bundle contract](integrations/comparison-bundle.md).
 
-  snapshots/<artifact_group>/<YYYY-MM-DD>/modules.<run_id>.json
+The output destination follows the normal `output.directory` fallback. An
-  snapshots/<artifact_group>/<YYYY-MM-DD>/metadata.<run_id>.json
+explicit `--out-dir` takes precedence and names the exact bundle directory,
-  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text_raw.<run_id>.json
+not a parent to be combined with another name. The standard names are derived
-  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text_result.<run_id>.json
+from the report output name, such as `comparison-today` and
-  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text.<run_id>.json
+`comparison-daily-2026-05-29`; see the [configuration reference](config.md)
-  snapshots/<artifact_group>/<YYYY-MM-DD>/render_context.<run_id>.json
+for output-directory resolution.
 
-  data-packages/<artifact_group>/<YYYY-MM-DD>/data_package.<run_id>.yaml
+A comparison bundle contains the shared data package, a manifest, and one
-  preflight/<artifact_group>/<YYYY-MM-DD>/render.<run_id>.json
+Markdown file for every successful profile. Treat all of these files as
+potentially sensitive: the data package and generated reports can contain
+location or forecast context. Weatherreporter creates no application-owned
+history, retention store, or cleanup job. Retain, archive, or remove only the
+specific bundle directories your operating policy permits.
 
-  notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json
+The destination is preflighted before prompt inspection and collection, then
-  notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json
+rechecked immediately before an atomic publish. A missing or empty directory
-```
+is usable. A nonempty directory can be replaced only when `--replace` is given
+and it is recognized as a current Weatherreporter comparison bundle; ordinary
+directories, symlinks, and unsafe destinations are rejected. Existing v1
+bundles are not recognized for replacement: move or remove them first.
+Cancellation and
+all failures before publication preserve an existing bundle, including a
+cancellation observed while a replacement is being prepared. If guarded
+restoration cannot complete, the error names the retained sibling bundle for
+manual recovery. Profile failures are different: the command publishes a
+complete partial bundle, with failed profiles represented in the manifest and
+no Markdown file for those profiles.
+Comparison preflight also checks that private publication siblings can be
+formed. An infeasible destination name is rejected before a missing parent
+directory is created.
 
-The generated-text and render-context artifacts are written only by Daily,
+## Local Prompt Profile Override
-Today, Tomorrow, and Hourly reports. A report's metadata links the module
-snapshot, data package, preflight artifact, managed report, and any available
-generated-text or single-report notification artifact. Batch notification
-artifacts are separate batch-level records under `notifications/batches`.
 
-RunIDs begin with the UTC generation timestamp and report ID. A Daily RunID
+Hourly normally selects the embedded `weather-light` profile. To use a local
-also contains its local valid date so multiple Daily reports in one batch have
+OpenAI-compatible model without changing prompts or application code, copy
-different managed paths. Batch notification RunIDs contain the UTC batch start
+[weather-light-local-profile.yml](../examples/weather-light-local-profile.yml),
-timestamp and batch name.
+set its `endpoint` and `model` for the local server, and configure the copy as
+`promptkit.profile_file`. The profile file's `weather-light` definition
+completely replaces the embedded definition; it does not affect a report that
+selects another profile ID.
 
-## Distributor Notification
+Prompt and profile validation occurs before weather collection. A malformed
+profile file, missing required credential, or unsupported selected backend
+stops the command before collection. A reachable profile can still fail later
+if its local model endpoint is unavailable; Weatherreporter does not switch to
+a remote profile.
 
-When `notify.distributor.enabled` is enabled, a successful `generate`
+## Optional Prompt Debug Capture
-uploads only the managed Markdown report after final metadata has been saved.
-The extra copy from `--out` is never uploaded. A notification attempt writes
-a redacted debug artifact at
-`notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json`; its
-path is then recorded in report metadata.
 
-Batches suppress per-report notification. When both Distributor and its batch
+Use `--llm-debug-dir` only when content-rich prompt diagnostics are required:
-notification are enabled, Weatherreporter submits one multi-report upload after
-every planned report succeeds. If any report fails, it records a top-level
-`skipped` notification with reason `one or more reports failed` and does not
-call Distributor. If batch notification is disabled, a batch does not fall back
-to individual uploads.
-
-A batch notification attempt writes
-`notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json`.
-A notification failure makes the batch fail but does not change successful
-individual report items into failed items. The debug artifacts contain rendered
-identifiers, managed source and bundle paths, upload and status results, and
-redacted errors; they do not contain tokens.
-
-## Inspecting Stored Runs
-
-Inspection is read-only: it neither collects weather data nor invokes
-Scriptorium or Distributor. Start by finding a RunID:
 
 ```sh
-weatherreporter inspect reports --limit 10
+weatherreporter generate today --llm-debug-dir /var/tmp/weatherreporter-debug
-weatherreporter inspect metadata RUN_ID
 ```
 
-| Command | Reads |
+The directory must be absolute. Requested captures are written with restrictive
-| --- | --- |
+permissions beneath the supplied directory, organized by report and run. They
-| `inspect reports` | Metadata files under the workspace snapshots tree. |
+can contain rendered prompts and generated output, so limit access to trusted
-| `inspect metadata RUN_ID` | Metadata located by RunID. |
+operators and remove the captures when they are no longer needed. Comparison
-| `inspect modules RUN_ID` | The module snapshot path recorded in metadata. |
+captures additionally identify each selected profile so concurrent executions
-| `inspect data-package RUN_ID` | The data-package path recorded in metadata. |
+remain distinct. Normal output, summaries, and routine logs omit that sensitive
-| `inspect prior RUN_ID` | The run metadata, then compatible earlier metadata for its comparison policy. |
+content. Debug capture is never created for an ordinary command without
-| `inspect sources RUN_ID` | Source provenance and warnings in the run metadata. |
+`--llm-debug-dir`.
 
-A missing snapshots directory produces no listed reports. An unknown or empty
+Secure prompt debug capture is currently available only on Unix hosts, where
-RunID is an error; use `inspect reports` to obtain a valid value.
+Weatherreporter can keep every traversal and write anchored to opened directory
+descriptors without following symbolic links. On other platforms, requesting
+`--llm-debug-dir` fails before prompt inspection, weather collection, or
+provider execution; ordinary commands without the flag remain available.
 
-## Recovery
+Preparation captures retain only the provider endpoint origin and reviewed
+execution settings. URL user information, paths, queries, fragments, and
+unrecognized provider parameters are omitted.
 
-Keep the workspace when a run fails: artifacts reached before the failure
+Each run directory may contain `preparation.json` (v3), `execution.json` (v3),
-remain available where they can be safely persisted.
+and, for a provider generation failure, `failure.json` (v1). The failure
+artifact retains the safe category, HTTP status, and provider code, type, and
+message for trusted debugging only. Ordinary command output never includes
+those provider details.
 
-- A preflight failure can leave the preflight artifact and metadata.
+Capture writes are confined to the requested root and fail if an unsafe
-- A report-generation failure can leave the managed report, module snapshot,
+filesystem component prevents secure artifact creation.
-  data package, and metadata.
-- A generated-text failure can leave raw text, the structured run result, or a
-  validated generated-text and render-context artifact, depending on where it
-  stopped.
-- A single-report notification failure preserves the report and final metadata,
-  including its notification artifact when it was written.
-- A batch notification failure preserves each report's artifacts and adds the
-  top-level batch notification artifact.
 
-Use the RunID from the action summary with the inspection commands above. For
+If capture creation or writing fails, the affected run fails rather than
-a batch failure, inspect the summary first, then inspect the affected report
+silently continuing without the requested diagnostics.
-RunIDs or the batch notification path. Do not remove the whole workspace as a
-first response; retain it until the failure is understood.
 
-## Operational Caveats
+## Diagnosing Failures
 
-- Workspace files, generated reports, and Scriptorium stderr can contain
+Start with the command error and JSON summary. For a report generation failure,
-  sensitive operational context. Set appropriate filesystem permissions and do
+the selected destination was not replaced; for a notification failure, inspect
-  not publish them unintentionally.
+the completed destination and the notification result. For a batch failure,
-- Weatherreporter uses one configured Weather API endpoint and local workspace
+use the per-report statuses and retain successful output files. For a comparison
-  state.
+failure, inspect the published manifest when its path is present: individual
-- It does not provide automatic resume, cleanup, archival, remote state, daemon
+profile failures retain their safe result and successful Markdown files, while
-  operation, or automatic storm monitoring.
+cancellation and pre-publication errors leave the prior destination unchanged.
+
+If a replacement commits but cleanup of its prior sibling backup fails, the new
+bundle remains valid and its artifact paths appear in the failed command
+summary. The summary records a safe `publication_cleanup` error that indicates
+whether a complete prior bundle remains, only partial remnants remain, or no
+prior bundle remains; it also identifies when the sibling cannot be inspected.
+The returned command error includes a recovery path only when a sibling remains.
+Preserve a complete recognized recovery bundle until it has been inspected and
+cleaned up manually; partial remnants are not a rollback artifact. Do not
+remove the new bundle to retry cleanup.
+
+Enable explicit debug capture only when content-rich Promptkit diagnostics are
+necessary.
+
+Weatherreporter does not retain runs for later inspection, resume failed work,
+or provide automatic cleanup, archival, remote state, daemon operation, or
+automatic storm monitoring.
+
+## Manual Cleanup Of Legacy Workspaces
+
+Older installations may have a directory named `workspace` containing reports,
+snapshots, prompt inputs, or notification records from previous versions.
+Current commands neither read nor update it. After confirming that no separate
+retention requirement applies, remove that specific legacy directory manually;
+do not use a broad cleanup command that could remove current operator outputs.
+
+For example, from the directory that contains the old directory:
+
+```sh
+rm -rf ./workspace
+```
+
+This removal cannot be recovered by Weatherreporter. Keep or archive any
+historical files that are still needed before deleting them.

docs/policy/architecture.md

@@ -2,217 +2,104 @@
 
 ## Purpose
 
-This policy defines Weatherreporter's system shape, normative ownership,
+This policy defines Weatherreporter's system shape, ownership, dependency direction,
-dependency direction, architectural invariants, safety properties, and
+and safety invariants. The [development guide](../development.md) owns the
-non-goals. Developers and coding agents should use it to preserve the
+package inventory; focused documents in `docs/internal/` own implementation detail.
-application's boundaries as the implementation evolves.
-
-The [development guide](../development.md) owns the current package inventory
-and contributor workflow. Focused documents under `docs/internal/` own
-implemented subsystem mechanics. This policy owns the rules those packages and
-mechanics must preserve.
 
 ## System Shape
 
-Weatherreporter is a deterministic weather briefing and report-preparation CLI.
+Weatherreporter is a deterministic weather-report CLI. It collects normalized
-It consumes normalized weather data, derives report facts and module snapshots,
+weather data, derives facts and modules, builds a curated YAML data package,
-builds curated prompt packages, compares structured snapshots with prior runs,
+executes exact-version Promptkit prompts, validates structured generated prose,
-and invokes Scriptorium either to produce managed Markdown directly or to
+and renders repository-owned Markdown in memory. Completed Markdown is
-produce bounded generated-text prose for repository-owned templates. It
+atomically published to an operator-owned output destination and may then be
-persists inspectable artifacts and can upload completed reports through
+uploaded through Distributor.
-Distributor.
 
-The application is intentionally a small, explicit, dependency-light Go
+An explicit profile comparison prepares one report input once, executes the
-program. Add abstraction only when it protects a real boundary, makes an
+same exact prompt and data package across selected profiles concurrently, and
-important invariant testable, or supports an implemented extension point.
+atomically publishes one operator-owned comparison bundle. It remains local:
+it does not create application state or send a Distributor notification.
 
-The primary flow is:
+The supported report products are Daily, Today, Tomorrow, and Hourly. A batch
+collects once, validates its complete candidate prompt/profile set before
+collection, then determines and validates every planned output destination
+before executing reports sequentially with one executor. It continues after
+independent report failures and sends a batch notification only after every
+planned report succeeds.
 
-1. CLI parsing and configuration resolution;
+## Ownership And Boundaries
-2. report or batch resolution;
-3. normalized weather collection;
-4. deterministic fact derivation and module construction;
-5. structured prior-snapshot comparison;
-6. curated prompt input and report-mode-specific Scriptorium processing;
-7. generated-text validation when applicable, managed Markdown production,
-   and metadata persistence; and
-8. optional notification using managed report artifacts.
 
-Inspection is a separate read-only flow over persisted state. It must not
+- `internal/cli` owns command parsing, help, summaries, and one executor
-collect weather data, invoke Scriptorium, or upload reports.
+  construction per action.
+- `internal/config` owns defaults, loading, validation, and secret loading.
+- `internal/app` owns in-memory workflow order, partial results, atomic output
+  publication, and notification coordination through project-owned contracts.
+- `internal/comparison` owns comparison identity, durable logical bundle
+  validation, safe destination recognition, and atomic bundle publication.
+- Deterministic domain packages own weather derivation, report periods, modules,
+  generated-text validation, and template contexts.
+- `internal/adapters/weatherapi`, `internal/adapters/promptkit`, and
+  `internal/adapters/distributor` own their external dependency mechanics.
 
-## Ownership And Dependency Direction
+Dependency-specific Promptkit types remain inside its adapter. The application
+does not parse flags, construct provider clients, or render provider output
+directly.
 
-### Entry Point And CLI
+## Prompt Execution Invariants
 
-The binary entry point should do no business work beyond constructing and
+- Prompts receive curated module packages, never unbounded raw weather payloads.
-running the CLI. CLI code owns commands, arguments, flags, help, output
+- Every execution validates the exact prompt version and output contract before
-formatting, and conversion into application requests.
+  collection. The selected profile is configured explicitly or declared by the
+  prompt; profiles requiring unsupported direct API keys fail before collection.
+  A profile may have an empty backend identity when it supplies an endpoint;
+  PromptKit resolves inherited profiles and optional credential sources when it
+  executes them.
+- Prompt and profile validation completes before weather collection. Raw output
+  is validated before template rendering.
+- PromptKit may make at most the prompt contract's one corrective generation;
+  exhaustion is a validation rejection, not an application-level retry.
+- Comparison validates every explicit profile before collection, prepares one
+  immutable report input, and delegates backend capacity to Promptkit rather
+  than adding an application-wide execution limit.
+- Generated text fills defined prose slots only. Deterministic facts remain
+  authoritative and repository-owned templates produce all Markdown output.
+- Sensitive rendered prompts, schemas, input bodies, provider endpoints, and
+  credentials never enter normal summaries or logs. They are written only to
+  an explicit secure debug root when requested.
+- Provider-controlled diagnostics never enter ordinary outputs; they are
+  retained only in explicit secure failure-debug artifacts.
 
-CLI packages must not own meteorological decisions, report composition,
+## Output, Notification, And Testing Invariants
-artifact layout, Recent Changes comparison, external transport, or subprocess
-construction.
 
-### Configuration
+- Normal execution is stateless: it keeps weather data, prompt input, generated
-
+  text, and render context in memory and creates no application-owned durable
-Configuration loading, built-in defaults, overrides, secret loading, and
+  state.
-validation belong to `internal/config`. Operational values shared across
+- Markdown writes are atomic at an operator-selected destination. A
-packages must be explicit configuration or constants owned by the responsible
+  pre-publication failure, including cancellation observed immediately before
-package, not hidden in CLI or adapter code.
+  publication, does not replace an existing destination; a notification failure
-
+  does not remove a newly published output.
-The exact configuration contract belongs in the
+- A single-report final destination is either absent or a regular file.
-[configuration reference](../config.md). Other architecture documents should
+  Symlinks and special filesystem objects are rejected during preflight and
-state ownership and safety rules rather than repeat fields, defaults, or
+  rechecked immediately before the atomic replacement.
-precedence.
+- Configuration or explicit CLI input selects that operator-owned destination;
-
+  it does not create an application-owned state boundary.
-### Application Orchestration
+- Comparison bundles are flat, versioned operator outputs. Their guarded
-
+  replacement accepts only a recognized current bundle; cancellation and every
-`internal/app` owns top-level use cases and workflow order. It composes report
+  pre-publication failure preserve a prior bundle, while individual profile
-resolution, collection, domain transformations, state, rendering, and optional
+  failures can publish a complete partial bundle.
-notification through narrow project-owned contracts.
+- Distributor uploads use only the published Markdown output, never a scan of
-
+  local files. Single notification follows publication; batch notification
-The application layer may coordinate components and convert between their
+  follows publication of every selected report. Batch counters describe report
-contracts. It must not absorb CLI parsing, HTTP transport, subprocess argument
+  outcomes only; a failed batch notification is represented separately at the
-construction, filesystem layout, weather derivation algorithms, template
+  batch level.
-execution, or adapter-specific dependency types.
+- Comparison never invokes Distributor notification.
-
+- Profile comparison supports operator review only: it does not score, rank,
-### Domain And Report Logic
+  select, resample, or replay profile executions.
-
+- Default tests are deterministic, offline, and use Promptkit/provider fakes
-Meteorological selection, forecast-period resolution, daypart grouping,
+  rather than live provider calls. See the [testing policy](testing.md).
-threshold detection, fact derivation, report composition, module construction,
-generated-text validation, and Recent Changes comparison belong in deterministic
-Go domain packages.
-
-Domain packages must not depend on CLI parsing, process execution, remote
-transport, or concrete external-library types. Given the same normalized
-inputs, configuration, valid period, prior snapshot, and clock, domain behavior
-should be reproducible.
-
-Report selection must go through the report registry or an equivalent
-centralized mechanism. A report definition owns its identity, prompt and
-rendering mode, valid-period resolver, module composition, comparison strategy,
-artifact grouping, and output naming. Do not scatter report-ID conditionals
-through CLI, orchestration, or adapters.
-
-### External Adapters
-
-External integrations use adapter boundaries under `internal/adapters`.
-Adapters own transport and protocol mechanics; application and domain packages
-own decisions.
-
-- The Weather API adapter owns HTTP request construction, timeouts, retries,
-  response-envelope handling, decoding, and endpoint compatibility.
-- The Scriptorium adapter owns argument construction, context-aware subprocess
-  execution, stdout and stderr capture, exit interpretation, and result
-  decoding. It must avoid shell interpolation.
-- The Distributor adapter owns dependency-specific bundle and upload types,
-  client construction, request execution, status handling, and redaction.
-
-External dependency types must not leak beyond the adapter that integrates
-them. Adapters should expose narrow project-owned inputs and outputs so an
-integration can be tested or replaced without changing domain logic.
-
-### State And Embedded Assets
-
-`internal/state` owns managed workspace paths, durable metadata, atomic
-artifact persistence, prior lookup, and inspection reads. Other packages should
-request state operations rather than reconstruct managed paths independently.
-
-Schemas, prompts, Markdown templates, and partials should live as separate
-repository assets and be embedded by the package that owns their execution or
-lookup. Keep weather derivation and path construction out of templates.
-
-## Architectural Invariants
-
-### Weather Truth And Generated Text
-
-- Normalized source data and deterministic Go derivation are authoritative for
-  weather facts.
-- LLM prompts receive curated module-based packages rather than raw,
-  unbounded source payloads.
-- For generated-text-template reports, generated text is limited to defined
-  prose slots, validated before use, and rendered through typed or otherwise
-  explicit contexts.
-- Direct-Markdown reports receive the same curated prompt-package boundary but
-  produce managed Markdown directly through Scriptorium rather than the
-  generated-text schema and repository-template workflow.
-- Repository-owned templates arrange validated prose and deterministic facts;
-  they do not perform meteorological derivation.
-
-### Reports And Comparison
-
-- Report behavior is resolved through centralized definitions.
-- Recent Changes is computed from structured module snapshots, never by
-  comparing rendered Markdown.
-- Batch workflows collect normalized weather data once and reuse that
-  collection for planning and report generation.
-- Report metadata links identity, generation time, valid period, source
-  provenance, and the managed artifacts produced for the run.
-
-### Managed State And Notification
-
-- Durable structured writes are atomic where practical.
-- Managed paths remain beneath the configured workspace root.
-- Operations that delete, move, overwrite, or copy files use narrow, explicit
-  paths; destructive cleanup is opt-in.
-- Intermediate artifacts reached before a later failure remain inspectable
-  where practical.
-- Distributor uploads use managed Markdown reports, never optional output
-  copies or broad workspace scans.
-- Notification occurs only after the managed report and required metadata have
-  been successfully produced.
-
-### Security, Errors, And Cancellation
-
-- Secrets must not appear in logs, errors, persisted artifacts, examples, or
-  user-facing output.
-- Errors preserve actionable operation, report, RunID, path, endpoint, or
-  subprocess context without exposing secrets or unnecessarily large payloads.
-- External calls, subprocesses, storage operations, and multi-step workflows
-  accept or propagate `context.Context` where cancellation or timeout is
-  meaningful.
-- Adapter failures preserve useful status, stderr, or response context at the
-  boundary and are translated into project-owned errors before crossing into
-  unrelated packages.
-
-## Dependency Policy
-
-Prefer the Go standard library. Add an external dependency only when it
-materially improves correctness, security, interoperability, or
-maintainability. A dependency used for a small convenience does not justify its
-lifetime upgrade and compatibility cost.
-
-Keep dependency-specific types inside the package that intentionally adopts
-the dependency. The application should remain understandable and testable
-without requiring framework-wide abstractions or live external services.
-
-## Verification And Documentation
-
-Core behavior must be testable without live Weather API, Scriptorium, or
-Distributor services. The [testing policy](testing.md) owns test philosophy,
-sufficiency, boundaries, and test-double guidance.
-
-Documentation must follow the
-[documentation policy](documentation.md). Update the canonical user,
-operator, integration, internal, and example documentation in the same change
-as the behavior it describes. Future or proposed behavior belongs under
-`docs/roadmap/`; significant durable decisions may be recorded as ADRs.
 
 ## Non-Goals
 
-Weatherreporter is not:
+Weatherreporter is not a weather-data ingestion service, general LLM
-
+orchestration framework, plugin platform, HTTP service, multi-user job system,
-- a source weather-data ingestion or normalization service;
+or a replacement for Promptkit or Distributor.
-- a general-purpose LLM orchestration framework;
-- an application in which an LLM selects authoritative weather facts or report
-  policy;
-- a plugin framework with dynamically discovered report or module behavior;
-- an HTTP service or multi-user distributed job system;
-- a replacement for Scriptorium or Distributor protocol ownership; or
-- a system that hides operational state exclusively inside opaque logs or
-  remote services.
-
-New requirements may justify revisiting a non-goal. A change that alters system
-shape, dependency direction, a safety property, or another architectural
-invariant should be recorded deliberately in this policy or an ADR rather than
-introduced implicitly.

docs/policy/documentation.md

@@ -82,12 +82,13 @@ mechanisms, not secret values.
 | Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, package boundaries, invariants, safety properties, and non-goals. | Concrete implementation mechanics, contributor procedures, decision history, and future work. |
 | Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and document lifecycle. | Application architecture and runtime behavior. |
 | Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, stable test boundaries, doubles, coverage guidance, regression policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
+| Release procedure | `docs/release.md` | Version policy, release preparation, validation, tagging, automated publication, verification, failure handling, and release ordering. | General contributor workflow, product contracts, release-specific change summaries, and implementation history. |
+| Release notes | `docs/releases/` | One versioned, changelog-style summary for each release, including compatibility and operator action. The file at the tagged commit supplies the corresponding Gitea release body. | Current CLI, configuration, operations, integration, architecture, and internal contracts; release procedure; implementation plans. |
 | CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, stdout and stderr behavior, summaries, and exit behavior. | Configuration field definitions, complete operating procedures, runtime filesystem layout, and command implementation. |
-| Configuration contract | `docs/config.md` | Discovery and precedence, fields, defaults, secrets, validation rules, and user-selectable values. | Complete example files, CLI syntax, runtime state lifecycle, and loading implementation. |
+| Configuration contract | `docs/config.md` | Discovery and precedence, fields, defaults, secrets, validation rules, and user-selectable values. | Complete example files, CLI syntax, output lifecycle, and loading implementation. |
-| Operations | `docs/operations.md` | Normal workflows, physical workspace layout, artifacts and metadata, inspection, notification behavior, recovery, cleanup, permissions, and operational caveats. | Complete CLI syntax, configuration field definitions, logical external contracts, and implementation mechanics. |
+| Operations | `docs/operations.md` | Normal output handling, atomic replacement, notification behavior, diagnosis, explicit debug capture, manual legacy-workspace cleanup, permissions, and operational caveats. | Complete CLI syntax, configuration field definitions, logical external contracts, and implementation mechanics. |
-| Troubleshooting | `docs/troubleshooting.md` | Recurring symptoms, likely causes, diagnostic steps, safe fixes, and links to normal-operation references. | Complete command and configuration references, routine operating procedures, and implementation detail. |
 | Report template surface | `docs/templates.md` | Implemented template files and partials, render-context fields, editing rules, and maintainer-facing template examples. | Weather derivation, module implementation, generated-text validation internals, and operator procedures. |
-| External and durable integration contracts | `docs/integrations/` | Weather API, Scriptorium, Distributor, external formats and protocols, durable logical paths and schemas, compatibility behavior, and upstream or downstream responsibilities. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, and configuration defaults. |
+| External and durable integration contracts | `docs/integrations/` | Weather API, Promptkit, Distributor, external formats and protocols, durable logical paths and schemas, compatibility behavior, and upstream or downstream responsibilities. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, and configuration defaults. |
 | Internal subsystem behavior | `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, user-facing contracts, external schemas, operator procedures, and future package plans. |
 | Architectural decision history | `docs/adr/`, when repository-local decisions require records | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, and task sequencing. |
 | Temporary feature roadmaps | `docs/roadmap/`, while planned work needs coordination | Proposed, accepted, deferred, or rejected work; sequencing; gates; implementation status; and task breakdowns. | Implemented behavior reference and durable decision rationale. |
@@ -108,13 +109,12 @@ structure and invariants. Focused internal documents own implementation
 behavior. These documents may link to one another but must not maintain
 parallel package or behavior references.
 
-### Commands, Configuration, Operations, And Troubleshooting
+### Commands, Configuration, And Operations
 
 CLI documentation answers how to invoke Weatherreporter and what its command
 interface does. Configuration documentation answers what settings mean.
-Operations answers what happens to runtime state and how to operate or recover
+Operations answers how to handle operator-owned outputs and runtime failures,
-the application. Troubleshooting starts from a symptom and leads to diagnosis
+including diagnosis, explicit debug capture, and safe legacy cleanup.
-and a safe fix.
 
 When a workflow crosses these topics, place the complete procedure with the
 document that owns the task and link to the other contracts. Do not duplicate
@@ -131,6 +131,25 @@ Internal documents may name a command, field, template value, path, or protocol
 to identify a dependency, but must link to its canonical documentation for the
 complete definition.
 
+### Release Procedure And Release Notes
+
+The release procedure owns how a maintainer prepares, publishes, verifies, and
+recovers from a Weatherreporter release. Release notes under `docs/releases/`
+own the concise historical summary for one version and are the checked-in
+source for its generated Gitea release body.
+
+Release notes are not current-state reference documents. They may summarize
+what changed and link to durable documentation, but they must not become a
+second command, configuration, operations, integration, architecture, or
+internal reference. Correct the applicable canonical owner in the same change
+when a release changes an implemented contract.
+
+The release note at a published tag and the Gitea release generated from it are
+historical records. Later corrections on `main` do not rewrite that published
+record. Material release errors require the failure handling defined by the
+release procedure rather than moving a published tag or overwriting its
+release.
+
 ### Executable Authority
 
 CLI parsing and help generation are the executable authority for accepted
@@ -195,6 +214,10 @@ durable owners, update incoming links, and archive or remove the roadmap
 according to repository practice. Do not preserve completed roadmaps as a
 second current-state reference.
 
+Release notes are durable historical summaries rather than temporary roadmaps.
+Keep them concise, retain them after publication, and keep current contracts in
+their canonical owners.
+
 Before completing documentation work:
 
 - verify affected behavior and examples;

docs/policy/testing.md

@@ -54,8 +54,8 @@ Use a classical or Detroit-style approach:
 - Test exact collaborator interactions only when the interaction itself is a
   requirement.
 
-Weatherreporter's important seams include clocks, subprocesses, HTTP services,
+Weatherreporter's important seams include clocks, Promptkit executors, HTTP
-Distributor uploads, filesystem roots, environment-backed secrets, and any
+services, Distributor uploads, filesystem roots, environment-backed secrets, and any
 future source of randomness or nondeterminism.
 
 ## Execution Requirements
@@ -73,7 +73,7 @@ package command while iterating and `go test -race ./...` when the risk crosses
 package boundaries.
 
 Tests in the default suite must be deterministic, offline, and independent of
-real credentials. They must not invoke live Weather API, Scriptorium, or
+real credentials. They must not invoke live Weather API, Promptkit providers, or
 Distributor services or depend on other mutable external infrastructure.
 Tests that require live infrastructure must be explicitly opt-in and clearly
 separated from the default suite.
@@ -96,8 +96,8 @@ Use each test type where it protects a distinct risk:
 - Integration tests use real deterministic collaborators when correctness
   depends on their interaction, while replacing live or nondeterministic
   external boundaries.
-- App and CLI tests protect representative assembled generation, batch,
+- App and CLI tests protect representative assembled generation, batch, atomic
-  inspection, persistence, and notification workflows.
+  output, and notification workflows.
 - Fixtures must be minimal, synthetic, versioned with the behavior they
   exercise, and free of credentials or private data.
 - Golden files are appropriate only when the complete output is intentionally
@@ -198,10 +198,10 @@ Each behavior should have a clear test owner:
 - CLI parser tests own arguments, flags, and command construction.
 - Config tests own loading, precedence, defaults, secrets, and validation.
 - Domain tests own weather transformations and invariants.
-- Adapter tests own HTTP, subprocess, and upload boundaries.
+- Adapter tests own HTTP, Promptkit/provider, and upload boundaries.
-- Orchestrator tests own workflow ordering, persistence, partial success, and
+- Orchestrator tests own workflow ordering, output publication, partial success,
-  failure propagation.
+  and failure propagation.
-- State tests own path derivation, atomic artifacts, lookup, and round trips.
+- Filesystem tests own atomic writes and destination-preservation behavior.
 - Template and generated-text tests own schemas, render contexts, and rendered
   output contracts.
 
@@ -219,8 +219,8 @@ observation:
 3. Use stubs when a dependency only needs controlled responses.
 4. Use mocks when the interaction itself is contractual.
 
-Mocks are appropriate for requirements such as uploading exactly once, saving
+Mocks are appropriate for requirements such as uploading exactly once,
-metadata before notification, propagating cancellation to Scriptorium, or
+notifying only after output publication, propagating cancellation to Promptkit, or
 avoiding an external call after an earlier workflow failure. Do not use mocks
 merely to isolate every object or reproduce the implementation's call graph.
 
@@ -232,7 +232,7 @@ Use:
 - `t.TempDir()` for real filesystem behavior;
 - `httptest.Server` for realistic Weather API interactions;
 - test-controlled clocks for periods and RunIDs;
-- fake command runners for Scriptorium behavior;
+- fake Promptkit executors or provider clients for Promptkit behavior;
 - fake upload clients for Distributor behavior;
 - fuzz tests when parsers, normalization, or path handling have a broad and
   consequential input space;

docs/release.md

@@ -0,0 +1,269 @@
+# Release Procedure
+
+## Release Model
+
+Weatherreporter publishes executable binaries through tagged commits on
+`main`. Releases use stable semantic-version tags in the form
+`vMAJOR.MINOR.PATCH`. The current pipeline does not publish prereleases.
+
+Every release has one nonempty, version-matched note at
+`docs/releases/<tag>.md`. After the tag is pushed, the Woodpecker release
+pipeline validates the tagged source, builds six binaries, creates SHA-256
+checksums, and creates the corresponding Gitea release. The pipeline uses the
+checked-in release note as the Gitea release body and does not overwrite an
+existing release.
+
+Before `v1.0.0`, a minor release may deliberately change user-facing
+interfaces when its release note explains the compatibility impact and
+required operator action. Patch releases must not intentionally break the
+documented CLI, configuration, durable artifact, or integration contracts in
+their minor line.
+
+Published tags and their generated releases are immutable. Never move, reuse,
+or delete a published tag, and never manually overwrite the release produced
+from it.
+
+## Select The Version And Write The Release Note
+
+Choose an unpublished version and export it as `RELEASE_VERSION`. Run the
+commands in this procedure from the Weatherreporter repository root in one
+POSIX shell:
+
+```sh
+export RELEASE_VERSION=vMAJOR.MINOR.PATCH
+```
+
+Create `docs/releases/$RELEASE_VERSION.md` with this structure:
+
+```markdown
+# Weatherreporter vMAJOR.MINOR.PATCH
+
+This release ...
+
+## Summary
+
+Summarize the release's purpose and most important outcomes.
+
+## Compatibility
+
+State compatibility with the preceding release and identify any changed CLI,
+configuration, durable artifact, integration, or operating contract.
+
+## Upgrade
+
+State the operator actions required to upgrade, or state that no special
+action is required.
+
+## Changes
+
+Describe the material user-visible, operational, and maintainer-visible
+changes. Link to canonical documentation for exact current contracts.
+```
+
+The note is a concise changelog and adoption aid, not a replacement for current
+documentation. Update every affected canonical document in the same candidate
+commit. Do not include credentials, private infrastructure details, or claims
+that are not true of the candidate.
+
+Require the version, path, heading, and minimum sections before continuing:
+
+```sh
+set -eu
+
+: "${RELEASE_VERSION:?export an unpublished vMAJOR.MINOR.PATCH version}"
+if ! printf '%s\n' "$RELEASE_VERSION" |
+    grep -Eq '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'
+then
+    printf '%s\n' "invalid release version: $RELEASE_VERSION" >&2
+    exit 1
+fi
+
+RELEASE_NOTE="docs/releases/$RELEASE_VERSION.md"
+export RELEASE_NOTE
+
+test -s "$RELEASE_NOTE"
+grep -Fx "# Weatherreporter $RELEASE_VERSION" "$RELEASE_NOTE"
+grep -Fx '## Summary' "$RELEASE_NOTE"
+grep -Fx '## Compatibility' "$RELEASE_NOTE"
+grep -Fx '## Upgrade' "$RELEASE_NOTE"
+grep -Fx '## Changes' "$RELEASE_NOTE"
+```
+
+## Validate The Candidate
+
+Run the same substantive checks enforced by the tag pipeline before committing
+the release note:
+
+```sh
+test -z "$(git ls-files go.work go.work.sum)"
+test ! -e vendor
+if grep -Eq '^[[:space:]]*replace([[:space:]]|\()' go.mod
+then
+    printf '%s\n' 'go.mod contains a replacement' >&2
+    exit 1
+fi
+
+GOWORK=off go test -count=1 ./...
+GOWORK=off go test -race -count=1 ./...
+GOWORK=off go vet ./...
+GOWORK=off go build ./...
+GOWORK=off go mod tidy -diff
+
+unformatted=$(
+    git ls-files '*.go' |
+        while IFS= read -r go_file
+        do
+            gofmt -l "$go_file"
+        done
+)
+test -z "$unformatted"
+git diff --check
+git diff --cached --check
+```
+
+Follow every added or changed Markdown link and confirm that its local target
+exists. Review the candidate for generated binaries, test output, credentials,
+temporary files, replacements, vendored dependencies, and other files that do
+not belong in source control.
+
+## Publish The Candidate Commit
+
+Commit the release note and any final current-state documentation updates, then
+push `main` through the ordinary repository workflow:
+
+```sh
+git add "$RELEASE_NOTE"
+git commit -m "Document Weatherreporter $RELEASE_VERSION"
+git push origin main
+```
+
+Do not tag an uncommitted or unpushed candidate. Record and export the exact
+candidate commit after the push:
+
+```sh
+RELEASE_COMMIT=$(git rev-parse --verify 'HEAD^{commit}')
+export RELEASE_COMMIT
+```
+
+## Guard And Tag The Candidate
+
+Run this guard immediately before creating the tag. It requires a clean
+checkout on synchronized `main`, valid module hygiene, the version-matched
+release note, and an unpublished local and remote tag:
+
+```sh
+check_release_candidate() {
+    test "$(git branch --show-current)" = main
+    test -z "$(git status --porcelain)"
+
+    gowork_value=$(go env GOWORK)
+    case "$gowork_value" in
+        ''|off) ;;
+        *)
+            printf '%s\n' "active Go workspace: $gowork_value" >&2
+            return 1
+            ;;
+    esac
+
+    test -z "$(git ls-files go.work go.work.sum)"
+    test ! -e vendor
+    if grep -Eq '^[[:space:]]*replace([[:space:]]|\()' go.mod
+    then
+        printf '%s\n' 'go.mod contains a replacement' >&2
+        return 1
+    fi
+
+    test -s "$RELEASE_NOTE"
+    grep -Fx "# Weatherreporter $RELEASE_VERSION" "$RELEASE_NOTE"
+
+    git fetch origin main --tags
+    test "$RELEASE_COMMIT" = \
+        "$(git rev-parse --verify 'refs/remotes/origin/main^{commit}')"
+
+    if git show-ref --verify --quiet "refs/tags/$RELEASE_VERSION"
+    then
+        printf '%s\n' "local tag already exists: $RELEASE_VERSION" >&2
+        return 1
+    fi
+    if test -n "$(
+        git ls-remote --tags origin \
+            "refs/tags/$RELEASE_VERSION" \
+            "refs/tags/$RELEASE_VERSION^{}"
+    )"
+    then
+        printf '%s\n' "remote tag already exists: $RELEASE_VERSION" >&2
+        return 1
+    fi
+}
+
+check_release_candidate
+```
+
+Create a lightweight tag, matching Weatherreporter's existing release tags,
+and bind it explicitly to the guarded commit:
+
+```sh
+git tag "$RELEASE_VERSION" "$RELEASE_COMMIT"
+test "$(git cat-file -t "refs/tags/$RELEASE_VERSION")" = commit
+test "$(git rev-parse --verify "refs/tags/$RELEASE_VERSION^{commit}")" = \
+    "$RELEASE_COMMIT"
+git show --no-patch --decorate "refs/tags/$RELEASE_VERSION"
+```
+
+If inspection finds an error, delete the unpublished local tag, correct the
+candidate, and repeat the procedure. Once the tag is pushed, it is immutable.
+
+## Publish And Verify The Release
+
+Push only the selected tag ref. Do not use `git push --tags`:
+
+```sh
+git push origin \
+    "refs/tags/$RELEASE_VERSION:refs/tags/$RELEASE_VERSION"
+```
+
+The tag event starts the release pipeline. Its validation step rejects a
+non-stable semantic tag, a missing release note, module or repository hygiene
+violations, and any failing test, race test, vet, build, module-tidiness,
+formatting, or whitespace check. Its build step also verifies that the host
+binary reports `weatherreporter $RELEASE_VERSION`.
+
+Wait for the pipeline to succeed, then confirm that the Gitea release:
+
+- targets `RELEASE_COMMIT` through `RELEASE_VERSION`;
+- is titled `Weatherreporter $RELEASE_VERSION`;
+- uses `RELEASE_NOTE` from the tagged commit as its body;
+- contains `SHA256SUMS`; and
+- contains Linux, macOS, and Windows binaries for both `amd64` and `arm64`,
+  named `weatherreporter-$RELEASE_VERSION-<os>-<arch>` with `.exe` on Windows.
+
+Compare the remote tag with the guarded commit:
+
+```sh
+remote_commit=$(
+    git ls-remote --tags origin "refs/tags/$RELEASE_VERSION" |
+        awk 'NR == 1 { print $1 }'
+)
+test "$remote_commit" = "$RELEASE_COMMIT"
+```
+
+Download `SHA256SUMS` and every release binary into a new temporary directory,
+run `sha256sum --check SHA256SUMS`, and execute the binary for the maintainer's
+host platform with `--version`. It must print exactly:
+
+```text
+weatherreporter vMAJOR.MINOR.PATCH
+```
+
+## Failed Publication And Corrections
+
+If the tag pipeline fails after publication, preserve the tag and diagnose the
+failure from the pipeline logs. Fix the cause on `main`, select a new patch
+version, prepare a new release note, and repeat the complete procedure. Do not
+move or recreate the failed published tag.
+
+Do not manually edit an automatically generated Gitea release or republish its
+assets. A wording-only correction may be committed to the historical document
+on `main`, with an explicit correction note, but it does not alter the file at
+the tag or the generated release. Publish a new patch release when the error is
+material to installation, compatibility, security, or operation.

docs/releases/v0.10.0.md

@@ -0,0 +1,140 @@
+# Weatherreporter v0.10.0
+
+Weatherreporter `v0.10.0` makes report execution stateless, adds stable
+weather-specific Promptkit profiles, and turns every successful generation
+into one atomic operator-owned Markdown output.
+
+## Summary
+
+- Ordinary generation no longer creates or depends on a managed workspace,
+  historical run artifacts, metadata, receipts, or prior snapshots.
+- `generate` and `run` now publish directly to operator-selected paths, with
+  useful current-directory defaults when output flags are omitted.
+- Local Recent Changes comparison and the historical `inspect` command family
+  have been removed.
+- Promptkit `v0.5.0` and three embedded logical profiles provide a stable model
+  ladder with complete file- or directory-based overrides.
+- Prompt input and generated-text contracts have been tightened, and output,
+  cancellation, batch preflight, notification, and partial-failure behavior
+  have focused offline coverage.
+
+## Compatibility
+
+This pre-`v1` minor release intentionally breaks CLI, configuration,
+prompt-input, action-summary, and workspace contracts from `v0.9.0`.
+
+- The `workspace:` and `recent_change:` configuration sections are no longer
+  supported. Strict configuration loading rejects them.
+- The `inspect reports`, `inspect metadata`, `inspect modules`,
+  `inspect data-package`, `inspect prior`, and `inspect sources` commands have
+  been removed. Weatherreporter no longer reads V1 or V2 run metadata or other
+  historical workspace artifacts.
+- Every successful `generate` writes exactly one Markdown file. Without
+  `--out`, Daily writes `daily-YYYY-MM-DD.md` and Today, Tomorrow, and Hourly
+  write `today.md`, `tomorrow.md`, and `hourly.md` in the invocation's current
+  directory. `--out` selects that file rather than creating an extra copy of a
+  separately managed report.
+- `run` writes selected outputs beneath the current directory unless
+  `--out-dir` selects another directory. Successful items remain available
+  when another batch item fails.
+- Action summaries no longer expose managed report, metadata, snapshot, data
+  package, prompt preparation, prompt execution, generated-text, render-context,
+  or notification-receipt paths. They retain the final `outputPath`, optional
+  `llmDebugPath`, safe effective profile/backend/model details, validation,
+  warnings, notification status, and safe errors.
+- Batch report items no longer contain per-report notification fields. Batch
+  notification is represented once at the top level. The `total`, `succeeded`,
+  and `failed` counters describe reports only, so notification failure can
+  produce a failed action while `failed` remains `0`.
+- The prompt data package advances from `weatherreporter.data_package.v3` to
+  `weatherreporter.data_package.v4` and removes `recent_changes`. All four
+  embedded prompts advance from `1.1.0` to `2.0.0`.
+- Generated-text schemas now require string-valued `precipitation_timing`; the
+  model returns an empty string when there is no timing text. The unused
+  `confidence` field has been removed and is rejected as an unknown field.
+
+Existing operator-owned Markdown files remain valid. Existing workspace trees
+are ignored rather than migrated or deleted. Distributor continues to receive
+the completed Markdown report, but its source is now the selected operator
+output rather than a managed report copy.
+
+## Upgrade
+
+Before replacing `v0.9.0`:
+
+1. Remove `workspace:` and `recent_change:` from configuration files.
+2. Give scheduled commands a predictable working directory or explicit
+   `--out` or `--out-dir` destination. Confirm that these selected files may be
+   atomically replaced on later successful runs.
+3. Remove historical `inspect` invocations and update action-summary consumers
+   to use `outputPath` and the remaining active-workflow fields.
+4. Decide whether old workspace contents have any external retention value.
+   Weatherreporter no longer reads them; after review, they may be removed
+   manually using the narrowly scoped procedure in the operations guide.
+5. Review Promptkit profile selection and credentials. Hourly defaults to
+   `weather-light`; Daily, Today, and Tomorrow default to `weather-balanced`.
+   A configured `promptkit.profile` still overrides every report in one action.
+
+The embedded logical profiles are:
+
+| Profile | OpenRouter model | Default use |
+| --- | --- | --- |
+| `weather-light` | `deepseek/deepseek-v4-flash` | Hourly |
+| `weather-balanced` | `~google/gemini-flash-latest` | Daily, Today, Tomorrow |
+| `weather-deep` | `~anthropic/claude-sonnet-latest` | Explicit selection |
+
+Override a complete same-ID definition through `promptkit.profile_file` or
+`promptkit.profile_dir` to use different models or a local OpenAI-compatible
+endpoint. Definitions are replaced rather than field-merged, and a malformed
+matching override fails instead of silently falling back.
+
+See the [CLI reference](../cli.md), [configuration
+reference](../config.md), [operations guide](../operations.md), and [Promptkit
+integration](../integrations/promptkit.md) for the exact current contracts.
+
+## Changes
+
+### Stateless Execution And Operator-Owned Outputs
+
+- Removed local forecast-change comparison, prior-snapshot selection, durable
+  module and prompt artifacts, managed reports, metadata compatibility, run
+  discovery, notification receipts, and the complete `internal/state`
+  subsystem.
+- Added an Accepted architecture decision recording the stateless
+  transformation pipeline and operator-owned output boundary.
+- Kept weather, facts, modules, prompt input, generated text, and render context
+  in memory during ordinary execution.
+- Made output publication atomic and ensured cancellation or deadline expiry
+  observed before publication leaves an existing destination unchanged.
+- Added complete batch-destination preflight before the first report prompt,
+  so a structural collision cannot leave an unreported partial batch.
+- Preserved successful outputs after report or Distributor failure. Batch
+  notification runs only after every selected report succeeds.
+
+### Promptkit Profiles And Prompt Contracts
+
+- Upgraded Promptkit from `v0.4.0` to `v0.5.0`.
+- Added embedded `weather-light`, `weather-balanced`, and `weather-deep`
+  profiles and mapped each exact prompt to its logical default.
+- Added embedded-profile fallback after configured `profile_file` or
+  `profile_dir` lookup, allowing operators to replace a logical profile without
+  changing report definitions.
+- Added a maintained local-endpoint example for replacing `weather-light`.
+- Advanced the four prompt definitions to `2.0.0` and the curated data package
+  to v4 after removing Recent Changes.
+- Required `precipitation_timing`, normalized whitespace-only timing to an
+  empty string, and removed the unused confidence value.
+
+### CLI, Reliability, Documentation, And Testing
+
+- Simplified action summaries to active workflow identity, output, model,
+  validation, warning, debug, notification, and safe error information.
+- Made batch counters report-only while retaining failed action status and
+  non-zero exit behavior for batch notification failure.
+- Kept prompt and profile inspection ahead of weather collection and validated
+  every batch candidate before collecting once.
+- Replaced state-oriented workflow fixtures with focused generation, batch,
+  output, cancellation, profile-resolution, Distributor, and CLI coverage.
+- Reconciled user, operator, integration, internal, policy, and ADR
+  documentation around the implemented stateless architecture and removed
+  completed temporary roadmaps.

docs/releases/v0.10.1.md

@@ -0,0 +1,33 @@
+# Weatherreporter v0.10.1
+
+This release repairs release validation after the `v0.10.0` pipeline failed in
+its privileged build container. Application behavior is unchanged from
+`v0.10.0`.
+
+## Summary
+
+The unreadable-secret configuration test now verifies that its process is
+actually subject to file permission bits before asserting that a mode-`000`
+file cannot be read. This keeps the test meaningful for ordinary users while
+allowing the release suite to run correctly in privileged containers.
+
+## Compatibility
+
+This patch release makes no changes to Weatherreporter's CLI, configuration,
+report output, integrations, prompts, profiles, or operating behavior. It is
+fully compatible with `v0.10.0`.
+
+## Upgrade
+
+No special operator action is required. Use `v0.10.1` in place of `v0.10.0`;
+the `v0.10.0` tag remains immutable, but its failed pipeline did not publish
+release binaries.
+
+## Changes
+
+- Made the unreadable-secret test capability-aware when the test process can
+  bypass filesystem permission bits.
+- Preserved the production contract that genuinely unreadable secret files
+  fail configuration loading.
+- Restored portable release validation in Woodpecker's privileged Go
+  container.

docs/releases/v0.11.0.md

@@ -0,0 +1,37 @@
+# Weatherreporter v0.11.0
+
+This release adds a configurable default publication directory for generated
+weather reports.
+
+## Summary
+
+Operators can now set `output.directory` once for both individual reports and
+scheduled batches. Explicit `--out` and `--out-dir` destinations continue to
+take precedence, while installations that omit the setting retain the existing
+current-directory behavior.
+
+## Compatibility
+
+This release is additive and compatible with `v0.10.1`. Existing configuration
+files, commands, report filenames, Promptkit behavior, and Distributor
+notification behavior remain valid and unchanged.
+
+## Upgrade
+
+No special action is required. To use the new default destination, configure
+`output.directory` as described in the [configuration
+reference](../config.md). Existing deployments may continue using the current
+working directory or explicit CLI output flags.
+
+## Changes
+
+- Added strict configuration loading and validation for the optional
+  `output.directory` field.
+- Applied the configured directory consistently to `generate` and `run`, with
+  explicit CLI destinations retaining highest precedence.
+- Preserved relative-path handling, absolute result paths, atomic publication,
+  cancellation safety, and Distributor notification ordering.
+- Strengthened output preflight so existing non-directory paths, uninspectable
+  paths, and dangling symlink components fail before expensive report work.
+- Updated the [CLI reference](../cli.md) and [operations
+  guide](../operations.md) for the new destination-selection behavior.

docs/releases/v0.12.0.md

@@ -0,0 +1,66 @@
+# Weatherreporter v0.12.0
+
+This release completes a repository-wide correctness, security, efficiency,
+test-durability, and documentation audit.
+
+## Summary
+
+Weatherreporter now applies stricter validation and bounded diagnostics across
+its configuration, weather collection, Promptkit, rendering, publication,
+comparison, and Distributor boundaries. Report preparation and execution carry
+one reconciled identity, independent weather sources are collected
+concurrently, and cancellation preserves completed report and comparison
+outcomes.
+
+The release also removes obsolete compatibility surfaces and consolidates
+duplicated implementation and test policy without changing ordinary report
+commands or output identities.
+
+## Compatibility
+
+This release is compatible with `v0.11.0` for ordinary `generate`, `run`, and
+`compare` commands, configuration files, report filenames, comparison bundles,
+and Distributor integration.
+
+Sensitive prompt-debug capture through `--llm-debug-dir` is now supported only
+on Unix hosts. Non-Unix hosts reject an explicit capture request before prompt
+inspection, weather collection, or provider execution because the required
+handle-relative, no-follow filesystem guarantees are unavailable there.
+
+Several unused internal compatibility exports were removed. They were not part
+of the documented CLI, configuration, artifact, or integration contracts.
+
+## Upgrade
+
+No special action is required for ordinary installations. Operators who use
+`--llm-debug-dir` on Windows must run that diagnostic workflow on a Unix host.
+Review any automation that depended on undocumented internal Go APIs removed by
+this release.
+
+## Changes
+
+- Hardened configuration loading, source validation, secrets rollback,
+  endpoint validation, HTTP diagnostics, generated-text limits, prompt-debug
+  redaction, output publication, comparison replacement, and Distributor
+  failure reporting.
+- Reconciled inspected, prepared, callback, and completed Promptkit identity
+  and provenance before accepting generated content.
+- Preserved metric values, civil-day and daypart identity, overnight alerts,
+  precipitation semantics, and Markdown structure across deterministic report
+  preparation and rendering.
+- Collected independent Weather API sources concurrently and reused readiness
+  data while retaining deterministic normalized results.
+- Preserved completed report and comparison failures independently from shared
+  cancellation, stopped unfinished work, and skipped batch notification after
+  cancellation or partial report failure.
+- Made secure prompt-debug traversal descriptor-relative on Unix and fail
+  closed elsewhere. See the [operations
+  guide](../operations.md#optional-prompt-debug-capture).
+- Strengthened default test portability and determinism, including
+  capability-aware symbolic-link fixtures and platform-appropriate process
+  signal coverage.
+- Removed obsolete compatibility helpers, duplicated test ownership, dormant
+  persistence code, and completed audit and implementation roadmaps.
+- Updated the [architecture policy](../policy/architecture.md), [testing
+  policy](../policy/testing.md), and focused internal guides to describe the
+  implemented final state.

docs/releases/v0.9.0.md

@@ -0,0 +1,134 @@
+# Weatherreporter v0.9.0
+
+Weatherreporter `v0.9.0` replaces its external Scriptorium execution path with
+an in-process Promptkit integration and makes prompt preparation, execution,
+validation, and failure artifacts first-class parts of each report run.
+
+## Summary
+
+- Promptkit `v0.4.0` now executes all generated text for Daily, Today,
+  Tomorrow, and Hourly reports.
+- The four exact-version prompts and their JSON Schemas are embedded in the
+  Weatherreporter binary.
+- Prompt preparation and execution have separate durable, redacted provenance
+  records, while sensitive prompt debugging is explicit and stored outside the
+  managed workspace.
+- Weather API collection now performs a warmup request and retries transient
+  transport, read, and selected HTTP failures.
+- Release binaries now report their embedded version and are published with
+  checksums through a guarded Woodpecker pipeline.
+
+## Compatibility
+
+This pre-`v1` minor release contains intentional configuration, CLI, and
+artifact changes that require review when upgrading from `v0.8.0`.
+
+- The `scriptorium:` configuration section is no longer supported. A file that
+  contains it fails with a migration error instead of silently ignoring it.
+  Use `promptkit:` configuration instead.
+- The previously exposed but unfinished three-day, weekend, and storm report
+  surfaces have been removed. Supported report IDs and `generate` commands are
+  `daily`, `today`, `tomorrow`, and `hourly`. The retired `storm_id`
+  Distributor template variable is also no longer accepted.
+- Generate and batch result items now expose `preparationPath` and
+  `executionPath` instead of the Scriptorium-oriented `preflightPath` and
+  `generatedTextResultPath`. An opt-in prompt capture may also add
+  `llmDebugPath`.
+- New runs write `weatherreporter.metadata.v2`, which records Promptkit
+  preparation and execution paths. Inspection and prior-run lookup continue to
+  read existing `weatherreporter.metadata.v1` records.
+- The built-in `weather_api.precision` default changed from `1` to `0`.
+  Configurations that explicitly set a value retain that value.
+- Report prose may differ because the embedded prompt corpus, structured
+  output path, alert presentation, and SPC background context have changed.
+
+The documented Go version remains 1.26. Distributor integration remains at
+`v0.5.0`. Existing managed workspaces do not require conversion.
+
+## Upgrade
+
+Replace the old Scriptorium block in the Weatherreporter configuration. The
+smallest equivalent Promptkit block is:
+
+```yaml
+promptkit:
+  timeout: 2m
+```
+
+The embedded prompts default to the Promptkit `gemini-flash-latest` profile.
+Ensure that the selected profile's credential environment variable is present,
+or configure `promptkit.profile`, an external `profile_file` or `profile_dir`,
+or the optional `promptkit.local` backend. Direct per-request API keys are not
+supported by Weatherreporter.
+
+Before upgrading automation or downstream processing:
+
+1. remove any `three-day`, `weekend`, or `storm` command, report override, and
+   `storm_id` template usage;
+2. update consumers of action-summary JSON to use the new preparation and
+   execution path fields;
+3. decide whether to retain the new precision default or explicitly configure
+   the previous value; and
+4. preserve the existing workspace if historical V1 runs must remain
+   inspectable.
+
+Scriptorium, its executable configuration, and its external prompt corpus are
+no longer needed by Weatherreporter. See the
+[configuration reference](../config.md), [CLI reference](../cli.md), and
+[Promptkit integration](../integrations/promptkit.md) for the current
+contracts.
+
+## Changes
+
+### Prompt Execution And Artifacts
+
+- Added a project-owned Promptkit adapter with exact prompt and profile
+  inspection, prepare-once execution, error classification, and bounded
+  execution timeouts.
+- Embedded version `1.0.0` of the Daily, Today, Tomorrow, and Hourly prompts and
+  their private generated-text schemas.
+- Added durable preparation and execution receipts with prompt, profile,
+  backend, model, hashes, timings, validation status, classified failures, and
+  paths to every artifact reached during the run. Credentials, endpoints,
+  rendered messages, request parameters, and generated content are excluded
+  from these managed records.
+- Added `--llm-debug-dir` for explicitly requested content-rich diagnostics.
+  Debug output must use an absolute path outside the managed workspace and is
+  written with restrictive filesystem permissions.
+- Preflight now validates each exact prompt and selected profile before weather
+  collection. Batch execution validates every candidate first, collects once,
+  and retains independent report progress and failure artifacts.
+
+See the [operations guide](../operations.md) for artifact layout, inspection,
+debug handling, and recovery.
+
+### Weather Collection And Report Content
+
+- Added a `/conditions/current` warmup before source collection and automatic
+  retry for transient transport and response-read failures and HTTP `408`,
+  `429`, `500`, `502`, `503`, and `504` responses.
+- Changed the default upstream precision query value to `0`.
+- Added embedded background definitions for recognized SPC categorical,
+  tornado, wind, and hail outlook products.
+- Made the Alert Digest more concise: alert descriptions are omitted, and an
+  SPC-only digest is rendered only for Enhanced, Moderate, or High categorical
+  risk.
+- Removed duplicated alert detail from the prompt-facing metadata module; the
+  alert digest remains its single prompt-facing owner.
+
+See the [Weather API integration](../integrations/weatherapi.md) for the request,
+retry, and response contract.
+
+### CLI, Documentation, Testing, And Releases
+
+- Added `weatherreporter --version`; tagged binaries report `v0.9.0`, while
+  ordinary local builds report `development`.
+- Reworked CLI summaries and inspection coverage around the Promptkit artifact
+  lifecycle and retained partial-result behavior.
+- Reorganized contributor, policy, user, operator, integration, template, and
+  internal documentation around explicit canonical owners.
+- Added focused single-report, batch, CLI, Promptkit adapter, durable-state,
+  and artifact-path coverage while simplifying orchestration internals.
+- Added guarded tag validation and reproducible release builds for Linux,
+  macOS, and Windows on `amd64` and `arm64`, with SHA-256 checksums and
+  changelog-backed Gitea releases.

docs/roadmap/future.md

@@ -3,20 +3,55 @@
 This roadmap contains future work only. Each section identifies its planning
 status; current behavior is documented outside `docs/roadmap/`.
 
+## Upstream Forecast Change Product
+
+Status: Proposed upstream feature request; unimplemented.
+
+Weatherreporter's local Recent Changes feature was removed by the accepted
+[stateless execution decision](../adr/0001-stateless-execution.md). Forecast
+version history and comparison are better owned by the Weather API, where the
+underlying forecast issuances can be retained and compared consistently for
+all consumers.
+
+A future Weather API feature should expose a structured change product with:
+
+- explicit current and baseline forecast issuance timestamps or identifiers;
+- documented baseline selection, such as a requested comparison timestamp,
+  preceding issuance, or fixed rolling period;
+- location, timezone, and half-open valid-period identity;
+- typed changed values with previous and current values and units;
+- stable change categories for temperature, precipitation probability and
+  timing, wind gusts, alerts, and aggregate hazards;
+- an API-owned significance classification or enough structured information
+  for a stateless consumer to apply a documented presentation threshold; and
+- deterministic ordering, missing-baseline behavior, and source metadata.
+
+The API should compare forecast versions, not track a Weatherreporter client's
+"previous run." It should not require consumer identity, mutable cursors, or
+Weatherreporter-managed history. A missing baseline should be a normal empty
+result rather than an error.
+
+Once a stable upstream contract exists, a separate Weatherreporter roadmap may
+reintroduce change commentary by collecting that product and mapping it into a
+curated prompt-facing module. There must be no local snapshot fallback. The
+ordinary Weatherreporter process must remain stateless, and the upstream
+feature should have deterministic fixtures before adoption.
+
 ## Automatic Storm Monitoring
 
 Status: Proposed and unimplemented.
 
-Manual Storm Report generation is implemented; see the [CLI reference](../cli.md).
+Storm reporting, whether manual or automatic, is unimplemented.
-Automatic storm-event evaluation remains unimplemented.
 
 Possible direction:
 
 1. Detect candidate storm events from alerts, forecast discussion, weather
    story context, hourly thresholds, and material forecast changes.
-2. Evaluate candidates through Scriptorium or another narrow evaluator adapter.
+2. Evaluate candidates through Promptkit or another narrow evaluator adapter.
-3. Persist storm lifecycle state.
+3. Keep any required storm lifecycle state in the upstream service or another
-4. Generate or update Storm Reports only when a meaningful event is present.
+   explicitly designed external owner rather than silently reintroducing a
+   Weatherreporter workspace.
+4. Generate or update a storm report only when a meaningful event is present.
 5. Suppress ordinary low-impact thunder or rain chances.
 
 Possible lifecycle states:
@@ -29,8 +64,8 @@ Possible lifecycle states:
 - `resolved`
 
 Before implementation, the design must preserve scheduled report behavior,
-manual Storm Report generation, inspectable evaluator failures, and fixture
+inspectable evaluator failures, and fixture coverage for deterministic
-coverage for deterministic candidate detection.
+candidate detection.
 
 ## Future Report Types
 
@@ -55,11 +90,10 @@ Status: Proposed and unimplemented.
 Possible future modules:
 
 - `hourly_table` for compact valid-period hourly facts
-- `forecast_delta` if a separate stanza is useful beyond current Recent
+- `forecast_delta` after an upstream forecast-change product exists
-  Changes
 - `weekend_planning` if weekend-specific planning guidance needs a dedicated
   deterministic stanza
-- `storm_window_summary` if manual or automatic Storm Reports need a dedicated
+- `storm_window_summary` if manual or automatic storm reports need a dedicated
   prompt-facing storm-window module
 - separate AFD section aliases, such as `afd_key_messages`,
   `afd_short_term_text`, and `afd_long_term_text`, if separate stanzas prove
@@ -80,7 +114,7 @@ contracts](../internal/facts.md), [module internals](../internal/module.md), and
 - keep broad reusable calculations in `DerivedFacts`
 - keep prompt-facing field shape inside module builders
 - use typed options for configurable module behavior
-- keep module snapshots structured and deterministic for Recent Changes
+- keep module output structured and deterministic
 
 ## Distributor Notification Enhancements
 
@@ -93,10 +127,8 @@ behavior is documented in the [Distributor adapter guide](../internal/distributo
 unimplemented:
 
 - `failure_policy: warn`
-- uploading metadata, module snapshots, data packages, or preflight artifacts
 - durable upload retry queues
 - distributor-specific CLI flags
-- distributor workspace scanning
 - destination routing, Markdown-to-HTML transformation, public URLs, or nginx
   layout inside weatherreporter
 
@@ -104,6 +136,17 @@ Any distributor enhancement should preserve the adapter boundary:
 weatherreporter selects explicit generated files and submits source bundles,
 while distributor owns destination routing and publication behavior.
 
+## Comparison Profile Diagnostics
+
+Status: Proposed and unimplemented.
+
+Comparison preflight failures could identify the profile being inspected and
+preserve a safe, actionable Promptkit cause, such as a duplicate profile ID,
+instead of reporting only a generic `profile_load` failure. Any improvement
+must continue to omit credentials, endpoints, and other sensitive profile
+values. Regression coverage should include a comparison that mixes built-in
+and configured-directory profiles and a directory containing duplicate IDs.
+
 ## Alternate Runtime Integrations
 
 Status: Proposed and unimplemented.
@@ -139,6 +182,7 @@ maintenance costs make the added abstraction worthwhile:
 - global test helper package
 - logging subsystem
 
-Any future implementation should preserve the existing public CLI, artifact
+Any future implementation should preserve the public CLI, report-output
-paths, report identities, module boundaries, and adapter boundaries unless a
+contract, report identities, module boundaries, and adapter boundaries in
-separate roadmap explicitly changes them.
+effect when that work begins unless a separate roadmap explicitly changes
+them.

docs/roadmap/implementation.md

@@ -0,0 +1,595 @@
+# PromptKit v0.8.0 Upgrade Implementation Plan
+
+Status: Complete.
+
+Completion note: Stages 1–9 upgraded PromptKit, adopted inherited profiles and
+current credential handling, added repair and provider-failure contracts,
+enabled one corrective generation for v2.1.0 prompts, exposed repair
+provenance in ordinary and comparison results, migrated comparison bundles to
+v2, and added secure failure-debug capture.
+
+## Purpose And Authority
+
+This plan translates the accepted
+[PromptKit v0.8.0 upgrade roadmap](promptkit-v0.8.0.md) into an ordered,
+decision-complete implementation procedure. The feature roadmap owns purpose,
+scope, policy, and the desired end state. This document owns implementation
+order, concrete work allocation, stage boundaries, and verification until the
+upgrade is complete.
+
+The implementing agent must complete the stages in numerical order. Each stage
+is sized for one focused prompt handled by `gpt-5.6-terra` with high reasoning.
+Do not combine stages merely because adjacent work touches the same package.
+
+## Locked Decisions
+
+The following decisions are final for this implementation:
+
+- upgrade directly from PromptKit `v0.5.0` to `v0.8.0`;
+- declare one corrective call in each embedded prompt through
+  `repair_attempts: 1` rather than adding WeatherReporter repair logic;
+- keep the repair budget in the exact embedded prompt definition and add no
+  global, per-report, CLI, profile, or operator configuration override;
+- advance all four exact prompt versions from `2.0.0` to `2.1.0`;
+- make `weather-light`, `weather-balanced`, and `weather-deep` minimal aliases
+  of the corresponding PromptKit built-ins through `base_profile`;
+- retain the existing report-to-profile assignments and effective model
+  ladder;
+- allow successfully inspected endpoint-only profiles to have an empty backend
+  ID while continuing to require a nonblank model;
+- treat `APIKeyEnv` as an optional lookup source and reject only profiles that
+  report `APIKeyRequired`, because WeatherReporter supplies no direct request
+  credential;
+- support PromptKit's built-in `rakestrawhome-gemma-4-31b` profile without
+  WeatherReporter-specific backend configuration;
+- expose provider HTTP status through a project-owned safe generation error,
+  while writing provider code, type, and message only to explicit secure debug
+  capture;
+- emit only `weatherreporter.comparison.v2`, with repair provenance, and do not
+  preserve v1 guarded-replacement support; and
+- retain PromptKit dependency types inside the adapter and preserve all
+  stateless execution, atomic publication, comparison independence, and
+  disclosure invariants.
+
+## Implementation Rules
+
+For every stage:
+
+- read `docs/development.md`, all files under `docs/policy/`, this plan, the
+  feature roadmap, and the task-specific documents named by the stage;
+- inspect the current code and tests before editing; use the repository's code
+  knowledge graph first for code discovery and fall back to text search for
+  literals, assets, and documentation;
+- implement only the stage's scope and preserve unrelated user changes;
+- keep PromptKit/provider types, client construction, YAML parsing, repair
+  mechanics, and provider transport inside the existing adapter boundary;
+- use deterministic, offline, credential-free tests and injected clients or
+  synthetic fixtures rather than live OpenRouter, Rakestrawhome, or local
+  endpoint calls;
+- add tests at the narrowest stable owner identified by the testing policy and
+  avoid copying PromptKit's internal test matrices;
+- update the canonical documentation owners listed for that stage in the same
+  change as the implemented contract;
+- run `gofmt` on changed Go files, the stage's focused tests,
+  `GOWORK=off go test -count=1 ./...`, and `git diff --check`; and
+- leave the repository passing before proceeding to the next stage.
+
+Stages affecting concurrent comparison, cancellation, or secure debug
+filesystem work must also run the named focused packages with `-race`. Do not
+weaken an existing assertion solely to accommodate the new dependency. When a
+test encodes an intentionally changed contract, replace it with a behavioral
+assertion for the accepted policy.
+
+## Implementation Stages
+
+### Stage 1: Upgrade The Dependency And Establish A v0.8.0 Baseline
+
+Status: Complete.
+
+Purpose: move to the tagged dependency and isolate compatibility changes before
+adopting new WeatherReporter behavior.
+
+Work:
+
+1. Update `go.mod` to require
+   `gitea.maximumdirect.net/eric/promptkit v0.8.0` and refresh `go.sum` with
+   `GOWORK=off go mod tidy`. Do not add `go.work`, `vendor`, or a `replace`
+   directive and do not change WeatherReporter's Go version.
+2. Resolve any compile failures using PromptKit's public root package only.
+   Keep all `Profile` and `OpenAICompatibleProfileConfig` literals keyed. Do not
+   register the now-reserved `rakestrawhome` backend.
+3. Reconcile adapter tests that directly exercise PromptKit's changed optional
+   credential behavior. A profile whose only credential metadata is
+   `api_key_env` must reach an injected client when the environment value is
+   absent; it must no longer expect PromptKit to return
+   `ErrAPIKeyEnvMissing`. Do not change WeatherReporter's application preflight
+   in this stage.
+4. Verify that every current embedded prompt, content file, schema, and fallback
+   profile inspects under v0.8.0. Verify selected invalid local endpoints and
+   malformed selected profile definitions still map to project-owned
+   configuration or profile-load categories.
+5. Review the v0.6.0 compatibility corrections against supported
+   WeatherReporter inputs: metadata-authoritative identities, exact contained
+   `content_file` paths, regular embedded files, structurally valid endpoints,
+   bounded JSON-compatible values, cancellation identity, and strict response
+   framing. Add consumer tests only for a WeatherReporter boundary not already
+   protected by PromptKit.
+
+Do not enable profile inheritance or output repair yet. The expected result is
+the current WeatherReporter feature set running against PromptKit v0.8.0.
+
+Focused verification:
+
+```sh
+GOWORK=off go test -count=1 ./internal/adapters/promptkit ./internal/promptassets
+GOWORK=off go test -race -count=1 ./internal/adapters/promptkit
+```
+
+### Stage 2: Adopt Profile Inheritance And Current Credential Routing
+
+Status: Complete.
+
+Purpose: adopt v0.7.0 profile composition, endpoint-only routing, optional
+credential semantics, and the Rakestrawhome built-in without changing the model
+ladder.
+
+Work:
+
+1. Replace the three embedded profile bodies with these exact leaf/base
+   relationships and no duplicated execution settings:
+
+   | Leaf | Base |
+   | --- | --- |
+   | `weather-light` | `deepseek-4-flash` |
+   | `weather-balanced` | `gemini-flash-latest` |
+   | `weather-deep` | `claude-sonnet-latest` |
+
+2. Update prompt-asset fixtures and tests to understand `base_profile`. Assert
+   that all three leaf IDs remain selected identities and resolve to the same
+   backend, model, timeout, service tier, and reasoning settings exposed by the
+   current standalone definitions. Test relationships and effective behavior,
+   not copied private constants beyond the intentional model-ladder contract.
+3. Preserve source precedence. Cover a standalone same-ID operator override, a
+   derived operator override, a configured source that shadows a base ID, and
+   selected missing-base, cyclic, malformed-base, and incomplete-target
+   failures. Do not implement inheritance or merging in WeatherReporter; all
+   resolution must remain PromptKit-owned.
+4. Change application profile preflight to accept a successful inspection with
+   a nonblank model and an empty backend ID. Trust PromptKit inspection to have
+   resolved either a backend or endpoint; do not add the endpoint to
+   `promptexec.ProfileInspection` or ordinary provenance.
+5. Remove application-level environment lookup and rejection for a nonblank
+   `APIKeyEnv`. Remove the now-unused `LookupEnv` fields and plumbing from
+   prompt, batch, and comparison inspection requests. Continue rejecting
+   `CredentialRequired`/`APIKeyRequired` before weather collection with the
+   existing missing-credential category.
+6. Add an end-to-end offline regression proving the maintained endpoint-only
+   `weather-light` example passes application inspection, retains an empty
+   backend ID, and does not expose its endpoint.
+7. Prove `rakestrawhome-gemma-4-31b` can pass ordinary and comparison profile
+   inspection through the existing adapter and reports the PromptKit
+   `rakestrawhome` backend ID. Do not make a provider call or add
+   Rakestrawhome-specific configuration.
+
+Canonical documentation in this stage:
+
+- update `docs/policy/architecture.md` so only direct-key-required profiles
+  fail credential preflight and backend identity is optional for endpoint-only
+  profiles;
+- update `docs/config.md` to distinguish same-ID source replacement from
+  `base_profile` chain inheritance and to describe optional environment
+  credentials;
+- update `docs/integrations/promptkit.md` for profile composition, parent
+  lookup precedence, endpoint-only identity, optional credentials, and
+  Rakestrawhome availability; and
+- update `docs/internal/promptkit-adapter.md` and focused app internals for the
+  implemented inspection behavior.
+
+Focused verification:
+
+```sh
+GOWORK=off go test -count=1 ./internal/promptassets ./internal/adapters/promptkit ./internal/app
+GOWORK=off go test -race -count=1 ./internal/adapters/promptkit ./internal/app
+```
+
+### Stage 3: Extend The Project-Owned Prompt Execution Contract
+
+Status: Complete.
+
+Purpose: establish dependency-neutral repair and structured-generation-error
+values before the adapter or application relies on them.
+
+Work:
+
+1. Add `RepairAttempts int` to `promptexec.OutputContract`. It is the configured
+   additional-call budget from the exact prompt contract.
+2. Add `RepairAttempts int` to `promptexec.Validation`. It is the number of
+   corrective calls actually started for the completed result. Update
+   `NewValidation` and every caller so construction is explicit; reject or
+   normalize no values here because PromptKit owns output-contract validity.
+3. Update all copy helpers, equality/provenance helpers, fixtures, and tests so
+   repair values are retained without sharing mutable state.
+4. Add a project-owned immutable `promptexec.GenerationError` with unexported
+   status and provider-detail fields plus safe accessors:
+
+   - `StatusCode() int`
+   - `ProviderCode() string`
+   - `ProviderType() string`
+   - `ProviderMessage() string`
+   - `Category() ErrorCategory`, always returning `Generation`
+   - `Error()`, exposing only the WeatherReporter generation category/message
+     and optional HTTP status
+   - `GoString()`, returning the same safe representation
+   - `Unwrap()`, preserving a project-owned `*promptexec.Error`
+
+5. Provide one constructor used by adapters. Defensively normalize valid UTF-8
+   and bound code/type to 256 Unicode code points and message to 4,096 Unicode
+   code points, even though PromptKit already bounds its accessors. Do not
+   expose fields through struct formatting, JSON tags, or exported mutable
+   fields. Preserve the dependency cause only behind the project-owned error so
+   `errors.Is`/`errors.As` identities remain available without entering error
+   text.
+6. Add focused tests proving nil/zero safety, category and unwrap behavior,
+   status-only ordinary formatting, `%#v` redaction, provider-detail bounds,
+   and repair-value copying.
+
+Do not import PromptKit from `internal/promptexec` and do not change CLI or
+artifact schemas in this stage.
+
+Focused verification:
+
+```sh
+GOWORK=off go test -count=1 ./internal/promptexec
+```
+
+### Stage 4: Map PromptKit v0.8.0 Repair And Generation Errors In The Adapter
+
+Status: Complete.
+
+Purpose: make the adapter faithfully translate v0.8.0 preparation, execution,
+validation, usage, and failure values into the Stage 3 contract.
+
+Work:
+
+1. Map `promptkit.OutputContract.RepairAttempts` in prompt inspection and
+   prepared-execution details. Map
+   `promptkit.ValidationResult.RepairAttempts` in completed execution.
+2. Preserve PromptKit's cumulative usage exactly as reported across the initial
+   call and every completed correction. Continue returning only the final raw
+   candidate and final validation result, subject to WeatherReporter's 64 KiB
+   generated-output bound.
+3. In adapter error classification, retain cancellation, deadline, and capacity
+   precedence. Before the generic `ErrLLMGenerate` branch, use `errors.As` for
+   `*promptkit.GenerationError` and construct the project-owned
+   `promptexec.GenerationError` with status, code, type, message, and hidden
+   cause. Initial and corrective generation failures use the same mapping.
+4. Extend the injected adapter client used by tests so it can return an ordered
+   sequence of responses or errors and record each request safely.
+5. Use a synthetic PromptKit prompt with JSON Schema validation and
+   `repair_attempts: 1` to cover:
+
+   - first-pass valid output with zero corrections;
+   - explicitly empty or invalid output followed by valid corrected output;
+   - one-attempt exhaustion returning a final failed validation result rather
+     than an operational error;
+   - a non-2xx-style `GenerationError` during correction;
+   - cumulative token usage and actual repair count; and
+   - the same prepared prompt/profile identity across the corrective flow.
+
+6. Keep these tests at the adapter boundary. Do not assert PromptKit's private
+   corrective-message wording or reconstruct its internal repair algorithm.
+
+Canonical documentation in this stage: update
+`docs/internal/promptkit-adapter.md` for the repair/result/error mappings. Do
+not yet claim that embedded WeatherReporter prompts enable repair.
+
+Focused verification:
+
+```sh
+GOWORK=off go test -count=1 ./internal/adapters/promptkit ./internal/promptexec
+GOWORK=off go test -race -count=1 ./internal/adapters/promptkit
+```
+
+### Stage 5: Carry Repair Provenance Through Application Workflows
+
+Status: Complete.
+
+Purpose: make application orchestration understand configured and actual repair
+counts before changing the embedded prompt policy.
+
+Work:
+
+1. Add an expected generated-text repair budget to `report.Definition` and set
+   it explicitly to zero for all four current `2.0.0` definitions in this
+   stage. Include it in report-definition validation and retained contract
+   tests.
+2. Extend exact prompt preflight so format, validation mode, schema path, and
+   repair budget must all match the resolved report definition. Extend
+   preparation and completion provenance checks to require the same repair
+   budget across inspection and the opaque prepared snapshot.
+3. Add `RepairAttempts *int` to application outcomes where execution may fail
+   before validation exists. Set it to a fresh pointer immediately after a
+   non-nil completed execution is returned, before WeatherReporter's secondary
+   generated-text validation. A pointer is required so completed first-pass
+   zero is distinguishable from unavailable provenance.
+4. Carry independent copies through `ReportResult`, `BatchReportResult`, batch
+   conversion, comparison execution's internal outcome, and relevant test
+   fakes. Do not expose the new value in CLI or comparison JSON yet.
+5. Preserve the actual count on PromptKit validation rejection and on later
+   WeatherReporter generated-text or render failures. Leave it unavailable on
+   preparation, capacity, cancellation, deadline, and generation errors that
+   return no completed PromptKit result.
+6. Add focused tests for provenance mismatch, completed zero, completed
+   positive, validation rejection, later local validation failure, early
+   operational failure, batch copying, and independent concurrent profile
+   outcomes.
+
+Canonical documentation in this stage: update the focused prepared-report and
+app-orchestration internals to describe configured versus actual repair
+provenance. Current public documents should continue to report the embedded
+budget as zero until Stage 6.
+
+Focused verification:
+
+```sh
+GOWORK=off go test -count=1 ./internal/report ./internal/app ./internal/cli
+GOWORK=off go test -race -count=1 ./internal/app
+```
+
+### Stage 6: Activate One Repair And Expose Ordinary Result Provenance
+
+Status: Complete.
+
+Purpose: switch the operational prompts to the accepted one-correction policy
+and make ordinary generate/run/batch output report what occurred.
+
+Work:
+
+1. Add `repair_attempts: 1` to the output contract of all four embedded prompt
+   definitions and change each exact prompt version from `2.0.0` to `2.1.0`.
+   Do not change prompt text or generated-text schemas solely for this upgrade.
+2. Change all four report registry definitions to exact prompt version `2.1.0`
+   and expected repair budget one. Update exact-version fixtures and assertions
+   throughout adapter, app, CLI, report, and prompt-asset tests. Remove tests
+   that classify `repair_attempts` as a retired setting and replace them with
+   an exact one-attempt contract assertion.
+3. Add `repairAttempts` to successful and failed generate and batch JSON result
+   shapes through the Stage 5 pointers. Emit integer zero for a completed
+   first-pass result, a positive integer for a completed repaired result, and
+   omit the field when no completed validation made it available.
+4. Keep the existing `validationStatus` and failure categories authoritative.
+   A repaired valid result proceeds normally. Repair exhaustion remains
+   `validation_rejected`, publishes no report for that profile, and retains the
+   actual attempt count.
+5. Add representative offline assembled tests proving first-pass success,
+   repaired success, exhaustion, explicit empty initial content, and batch
+   result propagation. Reuse the real PromptKit adapter with an injected
+   sequence client for at least one end-to-end repaired execution; use the
+   existing app fake at other boundaries where lower-level repair is already
+   covered.
+6. Confirm no application loop, provider retry, profile fallback, or
+   request-level `OutputContract` override was introduced.
+
+Canonical documentation in this stage:
+
+- update `docs/policy/architecture.md` with PromptKit-owned bounded repair and
+  failed-exhaustion invariants;
+- update `docs/integrations/promptkit.md` with exact prompt version `2.1.0`, one
+  configured repair, actual-count semantics, cumulative usage, explicit-empty
+  handling, and the distinction from operational retries;
+- update `docs/cli.md` for generate and batch `repairAttempts` fields;
+- update `docs/internal/report-registry.md`, prepared-report internals, and app
+  orchestration internals for exact version and repair flow; and
+- keep configuration documentation unchanged because no repair setting is
+  added.
+
+Focused verification:
+
+```sh
+GOWORK=off go test -count=1 ./internal/promptassets ./internal/report ./internal/adapters/promptkit ./internal/app ./internal/cli
+GOWORK=off go test -race -count=1 ./internal/adapters/promptkit ./internal/app
+```
+
+### Stage 7: Migrate Comparison Bundles To v2
+
+Status: Complete.
+
+Purpose: preserve repair activity in the profile-evaluation artifact and make
+the strict durable schema change explicit.
+
+Work:
+
+1. Change `comparison.SchemaVersion` to
+   `weatherreporter.comparison.v2`. Emit and recognize v2 only; do not retain a
+   v1 parser or guarded-replacement compatibility path.
+2. Add `RepairAttempts *int` to each application comparison profile result,
+   CLI comparison profile summary, and durable `comparison.Result`. Propagate a
+   fresh copy from Stage 5's execution outcome.
+3. Place `repairAttempts` immediately after `validationStatus` in the canonical
+   result-object JSON field order. Encode zero for completed first-pass
+   validation, a positive integer for completed correction, and omit it only
+   when no completed validation exists.
+4. Tighten manifest invariants: every non-nil repair count is non-negative; a
+   successful result must have `validationStatus: "passed"` and a non-nil
+   repair count; a failed result with a completed validation status must also
+   have a non-nil count; and an early operational failure may omit both.
+5. Update the strict token-level JSON recognizer to accept only the canonical
+   `repairAttempts` field at its correct object level, reject duplicate,
+   unknown, negative, fractional, string, overflow, and malformed values, and
+   continue rejecting v1 as an unsupported current bundle.
+6. Update manifest construction, cloning, validation, exact serialization
+   tests, guarded replacement tests, malicious bundle tests, partial-success
+   tests, and CLI comparison summaries. Preserve flat layout, result ordering,
+   hashes, atomic publication, cancellation safety, and no Distributor calls.
+7. Cover concurrent peers where one succeeds first-pass, one repairs, one
+   exhausts, and one fails operationally. The counts must remain attached to
+   the selected profile positions without races or cross-contamination.
+
+Canonical documentation in this stage:
+
+- replace the v1 contract in `docs/integrations/comparison-bundle.md` with v2,
+  including exact field order, presence rules, and the lack of v1 replacement
+  compatibility;
+- update `docs/cli.md` for comparison `repairAttempts`;
+- update `docs/operations.md` to tell operators to move or remove an existing
+  v1 bundle before replacing at the same destination; and
+- update comparison execution/publication internals and architecture policy as
+  needed for the current-only version invariant.
+
+Focused verification:
+
+```sh
+GOWORK=off go test -count=1 ./internal/comparison ./internal/app ./internal/cli
+GOWORK=off go test -race -count=1 ./internal/comparison ./internal/app
+```
+
+### Stage 8: Add Secure Provider-Failure Debug Capture
+
+Status: Complete.
+
+Purpose: expose useful PromptKit v0.7.0 provider diagnostics only through the
+existing explicit secure debug boundary while keeping ordinary errors safe.
+
+Work:
+
+1. Extend prompt preparation debug output with configured
+   `repairAttempts` and advance its schema identifier from
+   `weatherreporter.prompt_preparation_debug.v2` to
+   `weatherreporter.prompt_preparation_debug.v3`.
+2. Extend execution validation debug output with actual `repairAttempts` and
+   advance its schema identifier from
+   `weatherreporter.prompt_execution_debug.v2` to
+   `weatherreporter.prompt_execution_debug.v3`. Retain cumulative token usage.
+3. Add a dedicated `failure.json` artifact with schema identifier
+   `weatherreporter.prompt_failure_debug.v1`. Its canonical fields are:
+
+   - top level: `schemaVersion`, `reportId`, `validDate`, `runId`, `failure`;
+   - failure object: `category`, `statusCode`, `providerCode`, `providerType`,
+     `providerMessage`;
+   - omit absent provider fields and zero status; and
+   - never include the raw provider body, headers, endpoint, credentials,
+     request, schema, rendered prompt, or generated candidate.
+
+4. Add `PromptDebugWriter.WriteFailure` using the existing handle-relative
+   secure run directory, `0700` directory and `0600` file modes, canonical JSON
+   encoding, and no-follow/atomic replacement behavior. Disabled writers must
+   perform no filesystem work.
+5. When execution returns an error, use `errors.As` only against the
+   project-owned `*promptexec.GenerationError`. If explicit debug capture is
+   enabled, write `failure.json` using that profile's existing debug reference.
+   This applies equally to initial and corrective provider failures and keeps
+   comparison profile directories isolated.
+6. If failure-debug writing also fails, retain the generation failure as the
+   primary categorized error and join the safe debug-write failure rather than
+   replacing or hiding the provider failure. Never place provider code, type,
+   or message in the joined error text.
+7. Ordinary generate, batch, and comparison errors should gain only the safe
+   HTTP status already rendered by `promptexec.GenerationError.Error`; do not
+   add provider detail fields to CLI summaries, comparison manifests, logs, or
+   Distributor requests.
+8. Add adversarial tests for formatter redaction, malicious provider strings,
+   JSON escaping, bounds, absent fields, file modes, symlink/path attacks,
+   write failure, cancellation identity, initial versus corrective failures,
+   and concurrent comparison captures.
+
+Canonical documentation in this stage:
+
+- update `docs/operations.md` with the three debug artifact versions,
+  `failure.json`, sensitivity, permissions, and retention;
+- update `docs/integrations/promptkit.md` with ordinary status-only disclosure
+  and debug-only provider detail;
+- update prompt-debug, PromptKit-adapter, and app-orchestration internals; and
+- ensure `docs/policy/architecture.md` explicitly prohibits provider-controlled
+  diagnostics from ordinary outputs.
+
+Focused verification:
+
+```sh
+GOWORK=off go test -count=1 ./internal/promptexec ./internal/promptdebug ./internal/adapters/promptkit ./internal/app ./internal/cli
+GOWORK=off go test -race -count=1 ./internal/promptdebug ./internal/adapters/promptkit ./internal/app
+```
+
+### Stage 9: Reconcile Documentation And Perform The Final Upgrade Audit
+
+Status: Complete.
+
+Purpose: verify the complete end state as one coherent WeatherReporter feature
+and leave no stale v0.5.0, prompt v2.0.0, comparison v1, credential, profile,
+repair, or debug claims.
+
+Work:
+
+1. Re-read the feature roadmap, `docs/development.md`, every policy document,
+   and every canonical document changed by Stages 1-8. Reconcile them against
+   executable behavior and remove duplicated or stale definitions. Keep
+   unimplemented future ideas in `docs/roadmap/future.md`, not current-state
+   documents.
+2. Search code, embedded assets, examples, tests, and documentation for stale
+   contractual literals and review every occurrence of:
+
+   - PromptKit `v0.5.0`, `v0.6.0`, and `v0.7.0` as an active dependency claim;
+   - prompt version `2.0.0`;
+   - `weatherreporter.comparison.v1`;
+   - prompt debug schema v2 identifiers;
+   - claims that profile fields never inherit;
+   - claims that every `APIKeyEnv` must be populated;
+   - claims that backend ID is always required;
+   - claims that repair is disabled or `repair_attempts` is retired; and
+   - provider detail in ordinary output.
+
+   Historical release documents may retain accurate historical literals.
+3. Verify canonical ownership:
+
+   - architecture owns invariants and boundaries;
+   - config owns operator profile and credential behavior, but no repair field;
+   - PromptKit integration owns logical prompt/profile/output contracts;
+   - CLI owns result fields;
+   - operations owns explicit debug handling and old comparison-bundle cleanup;
+   - comparison integration owns the complete v2 manifest; and
+   - internal documents own implementation flow without duplicating the public
+     references.
+
+4. Verify maintained examples remain valid, secret-free, and tested. The local
+   `weather-light` example remains a standalone endpoint-only profile rather
+   than inheriting an OpenRouter backend it cannot clear.
+5. Review the complete diff for architecture leakage. Production packages
+   outside `internal/adapters/promptkit` must not import PromptKit; no
+   application repair loop, provider client, raw provider diagnostic, profile
+   YAML parser, or durable application state may have appeared.
+6. Review tests under the testing policy. Keep consumer contract and regression
+   coverage, remove accidental duplication of upstream implementation tests,
+   and ensure every default test is offline and repeatable.
+7. Run the complete validation set:
+
+```sh
+gofmt -w <all changed Go files>
+GOWORK=off go test -count=1 ./...
+GOWORK=off go test -race -count=1 ./...
+GOWORK=off go vet ./...
+GOWORK=off go build ./...
+GOWORK=off go mod tidy -diff
+go run ./cmd/weatherreporter --help
+go run ./cmd/weatherreporter compare --help
+test -z "$(git ls-files go.work go.work.sum)"
+test ! -e vendor
+git diff --check
+```
+
+8. Confirm `go.mod` has no `replace`, the resolved PromptKit module is exactly
+   v0.8.0, and no live credential or provider call occurred during validation.
+9. After every check passes, update this plan's status to Completed and add a
+   concise completion note listing the implemented stages. Do not delete either
+   roadmap until the maintainer has reviewed the implementation. Do not create
+   a release document or tag; release preparation remains a separate maintainer
+   action once a version is selected.
+
+## Completion Standard
+
+The implementation is complete only when all nine stages pass their focused
+and repository-wide checks, all locked decisions are observable in code and
+canonical documentation, and the feature roadmap's completion criteria are
+satisfied. Passing compilation alone is insufficient. The final state must
+demonstrate repaired success, repair exhaustion, comparison provenance,
+endpoint-only routing, optional credentials, inherited profiles, Rakestrawhome
+inspection, safe ordinary provider failures, secure debug-only detail, and
+unchanged publication and concurrency invariants.

docs/roadmap/promptkit-v0.8.0.md

@@ -0,0 +1,488 @@
+# PromptKit v0.8.0 Upgrade Roadmap
+
+Status: Implemented.
+
+## Purpose
+
+WeatherReporter should upgrade its PromptKit dependency from `v0.5.0` to
+`v0.8.0` and deliberately adopt the useful consumer-facing capabilities added
+in `v0.6.0`, `v0.7.0`, and `v0.8.0`. The upgrade should improve output-contract
+reliability, profile composition, local and alternate endpoint support, and
+provider-failure diagnosis without moving PromptKit responsibilities into
+WeatherReporter or weakening the application's stateless and security
+boundaries.
+
+This roadmap defines the intended scope, policy, and end state. The
+[implementation plan](implementation.md) owns the procedure for reaching that
+state.
+
+## User Intent
+
+The upgrade is intended to:
+
+- use PromptKit's bounded output repair to recover from occasional malformed
+  structured weather prose;
+- keep WeatherReporter's domain profile IDs stable while inheriting maintained
+  PromptKit model definitions;
+- make PromptKit's additional built-in backend and profile available for
+  explicit generation and profile comparisons;
+- support unauthenticated or optionally authenticated OpenAI-compatible
+  endpoints without inventing a WeatherReporter transport layer;
+- make provider HTTP failures more actionable under an explicit
+  WeatherReporter disclosure policy; and
+- receive PromptKit's intervening correctness, safety, cancellation, resource,
+  and efficiency improvements as part of one tested dependency upgrade.
+
+The model ladder and report assignments do not change as part of this work:
+Hourly continues to select `weather-light`; Daily, Today, and Tomorrow continue
+to select `weather-balanced`; and `weather-deep` remains available for explicit
+selection. This upgrade does not promote the new Rakestrawhome profile into
+that default ladder.
+
+## Current State
+
+WeatherReporter currently depends on
+`gitea.maximumdirect.net/eric/promptkit` at `v0.5.0`. The PromptKit adapter
+supplies embedded prompts, JSON Schemas, and
+application-fallback profiles, plus an optional configured profile source and
+the conventional local backend.
+
+The four generated-text prompts are exact version `2.0.0` JSON Schema prompts.
+They omit `repair_attempts`, so execution is single-pass. The project-owned
+`promptexec.OutputContract` and validation result also omit repair budgets and
+actual repair counts.
+
+The three embedded WeatherReporter profiles duplicate the effective fields of
+these PromptKit built-ins:
+
+| WeatherReporter profile | PromptKit built-in with the same target |
+| --- | --- |
+| `weather-light` | `deepseek-4-flash` |
+| `weather-balanced` | `gemini-flash-latest` |
+| `weather-deep` | `claude-sonnet-latest` |
+
+WeatherReporter preflights any nonblank `api_key_env` as a required credential,
+even though PromptKit v0.7.0 distinguishes an optional environment source from
+an explicit `APIKeyRequired` target. Provider generation failures are reduced
+to WeatherReporter's safe `generation` category; the PromptKit dependency error
+is retained as a hidden cause, but its structured HTTP status and provider
+diagnostics are not mapped into project-owned values.
+
+The maintained `weather-light` local override is an endpoint-only profile, and
+the configuration contract says endpoint-only profiles are supported. PromptKit
+inspection correctly reports no backend ID for that form, but WeatherReporter
+application preflight currently requires both a nonblank backend and model.
+That mismatch prevents the documented example from reaching generation and
+should be corrected as part of adopting the current PromptKit target contract.
+
+## Upstream Release Assessment
+
+### PromptKit v0.6.0
+
+`v0.6.0` adds no public declarations, but it is a material compatibility and
+safety release. It centralizes execution-setting, output-contract, endpoint,
+and JSON-compatible-value validation; makes YAML metadata authoritative for
+prompt and profile identity; hardens `content_file` containment and regular-file
+requirements; validates OpenAI-compatible endpoints structurally; bounds JSON
+trees and successful provider bodies; requires exactly one JSON value in
+provider responses; preserves cancellation and transport error identities; and
+reuses schema and rendered-artifact work within an operation.
+
+WeatherReporter should receive these improvements directly from the dependency
+and audit its own supported assets and configuration paths against the stricter
+contracts. It should not duplicate PromptKit's internal validators or tests.
+The existing embedded prompt paths, inline data-package input, generated-output
+limit, and adapter boundary remain conceptually correct.
+
+### PromptKit v0.7.0
+
+`v0.7.0` adds four potentially useful consumer features:
+
+- linear, cycle-safe profile inheritance through `base_profile` and
+  `Profile.BaseProfileID`;
+- the built-in `rakestrawhome` backend and
+  `rakestrawhome-gemma-4-31b` profile;
+- optional API-key environment sources, with `APIKeyRequired` reserved for an
+  explicit local credential requirement; and
+- bounded structured `GenerationError` details for non-2xx responses from the
+  built-in OpenAI-compatible client.
+
+WeatherReporter has no manual `rakestrawhome` registration and uses keyed
+PromptKit profile literals, so the two source-compatibility hazards called out
+by the release do not require migration shims. The profile, credential, and
+error features do require deliberate application-policy choices described
+below.
+
+### PromptKit v0.8.0
+
+`v0.8.0` activates the existing output-contract repair budget. A positive
+`repair_attempts` value authorizes up to that many corrective model calls after
+eligible `basic`, `json`, or `json_schema` validation failures. The supported
+budget is zero through three. Repairs preserve the original rendered
+conversation, effective target, session, structured-output contract, and
+backend capacity policy. The final result reports cumulative token usage and
+the number of corrective calls actually made.
+
+Repair exhaustion is a completed generation with failed validation, not an
+operational error. WeatherReporter's existing policy should continue to reject
+that result and publish no report for that profile. Explicit empty provider
+content now reaches output validation; for WeatherReporter's JSON Schema
+prompts it is therefore eligible for repair rather than being misclassified as
+a malformed provider envelope.
+
+## Desired End State
+
+WeatherReporter builds and tests against PromptKit `v0.8.0` with no workspace,
+vendor, or module replacement dependency. Its public behavior remains
+stateless, its PromptKit dependency types remain confined to the adapter, and
+its ordinary summaries and logs remain safe.
+
+The completed integration:
+
+- benefits from the v0.6.0 safety and efficiency corrections;
+- composes WeatherReporter domain profiles from PromptKit's maintained built-in
+  profiles while preserving WeatherReporter-owned leaf IDs and operator
+  override precedence;
+- accepts a successfully inspected endpoint-only profile with a nonblank model
+  even though it has no logical backend ID;
+- permits explicit use of PromptKit's Rakestrawhome profile without custom
+  backend wiring;
+- applies an accepted bounded-repair policy to every operational structured
+  prompt;
+- validates repair configuration during preflight and records actual repair
+  activity in project-owned result values;
+- retains PromptKit's cumulative usage accounting in explicit debug output;
+- distinguishes safe provider HTTP status from potentially sensitive provider
+  diagnostics; and
+- documents the changed profile, credential, repair, comparison, debug, and
+  failure contracts in their canonical owners.
+
+## Dependency And Compatibility Policy
+
+The module requirement should move directly from `v0.5.0` to `v0.8.0`, followed
+by a clean module tidy. WeatherReporter already requires Go 1.26 while PromptKit
+`v0.8.0` requires Go 1.25.5, so no Go version change is needed for this upgrade.
+
+Consumer validation must cover the paths called out by PromptKit v0.6.0:
+
+- every embedded prompt, content file, schema, and fallback profile inspects
+  through PromptKit `v0.8.0`;
+- configured single-file and directory profile sources retain their lazy,
+  metadata-authoritative identity and precedence behavior;
+- malformed selected profiles and invalid local endpoints retain actionable
+  WeatherReporter categories;
+- the inline YAML data package and prepared-execution path remain within the
+  new JSON and response bounds; and
+- cancellation, deadline, and backend-capacity identities still cross the
+  adapter correctly.
+
+PromptKit owns its 16 MiB successful transport-response bound and JSON framing.
+WeatherReporter retains its stricter 64 KiB generated-text acceptance bound.
+The consumer suite should protect that relationship without reproducing
+PromptKit's lower-level transport matrix.
+
+## Domain Profile Composition
+
+The embedded profiles should become application-owned aliases:
+
+```yaml
+id: weather-light
+base_profile: deepseek-4-flash
+```
+
+```yaml
+id: weather-balanced
+base_profile: gemini-flash-latest
+```
+
+```yaml
+id: weather-deep
+base_profile: claude-sonnet-latest
+```
+
+The effective backend, model, timeout, service tier, and reasoning settings
+must initially remain identical to the current WeatherReporter definitions.
+The selected leaf remains the durable logical profile identity even though its
+effective target is inherited.
+
+Profile source precedence remains:
+
+1. explicit in-memory profiles used by tests or embedding consumers;
+2. the configured `profile_file` or `profile_dir` source;
+3. WeatherReporter's embedded fallback catalog; and
+4. PromptKit's built-in catalog.
+
+Sources still do not merge definitions of the same ID. Once a selected
+definition names `base_profile`, however, each parent ID is resolved through
+that same precedence order and the resulting linear chain is merged from root
+to leaf according to PromptKit's inheritance contract. Documentation must make
+that distinction explicit. A malformed leaf, missing or malformed base, cycle,
+overlong chain, or incomplete resolved target fails profile inspection before
+weather collection.
+
+An operator may continue to replace `weather-light`, `weather-balanced`, or
+`weather-deep` with a standalone definition. An operator may also define a
+derived replacement. The maintained local endpoint example should remain
+standalone because PromptKit profile inheritance has no clearing syntax: using
+an OpenRouter base would retain its backend identity and capacity policy even
+when the child replaces the endpoint.
+
+WeatherReporter should treat the adapter's successful profile inspection as
+authoritative that PromptKit resolved a usable route. A nonblank model remains
+required, but backend ID is optional for an endpoint-only profile and should be
+omitted from safe provenance where unavailable. WeatherReporter still must not
+surface the endpoint outside explicit debug capture. This aligns application
+preflight with PromptKit and with the existing CLI, comparison, and debug value
+shapes, all of which already permit an absent backend identity.
+
+## Rakestrawhome Availability
+
+The reserved `rakestrawhome` backend and built-in
+`rakestrawhome-gemma-4-31b` profile should be supported automatically through
+ordinary PromptKit selection. Operators may choose that profile with the
+existing global profile setting or as one entry in `compare`, and PromptKit's
+backend capacity policy remains authoritative.
+
+WeatherReporter should not register, wrap, or duplicate the backend or profile,
+and should not add a Rakestrawhome-specific configuration field. Its canonical
+PromptKit integration documentation should link to PromptKit for the current
+built-in catalog and credential contract rather than copying volatile endpoint
+or capacity values. Offline inspection coverage should prove that the built-in
+profile crosses the WeatherReporter adapter with the expected logical backend
+identity.
+
+## Bounded Structured-Output Repair
+
+The accepted repair budget belongs to the exact PromptKit output contract, not
+to a WeatherReporter retry loop. PromptKit alone should construct corrective
+messages, perform additional calls, enforce the budget, aggregate usage, and
+coordinate backend capacity. WeatherReporter must not retry provider failures,
+switch profiles, or layer another repair mechanism around `RunPrepared`.
+
+All four embedded prompt definitions should declare `repair_attempts: 1`.
+Because this changes prompt
+execution behavior, latency, cost, hash, and provenance, each definition and
+its report-registry binding should advance from exact version `2.0.0` to
+`2.1.0`. Prompt text and generated-text schemas do not need to change solely
+for this feature.
+
+The embedded prompt definition is the per-report pipeline policy owner. This
+upgrade should not add a global or per-report operator configuration field for
+repair attempts and should not construct a request-level replacement output
+contract. A future pipeline may select another budget only through a deliberate
+prompt-definition and exact-version change.
+
+The project-owned PromptKit boundary should retain:
+
+- the configured repair budget in prompt inspection and preparation output
+  contracts;
+- the number of corrective calls actually made in completed validation;
+- cumulative PromptKit token usage across initial and corrective calls; and
+- the final candidate and final validation result only, consistent with the
+  PromptKit contract.
+
+Prompt inspection and preparation provenance must require the repair budget to
+match the exact expected prompt definition just as they currently require the
+format, validation mode, and schema path to match. A zero-attempt successful
+result is normal when the first candidate passes. A repair-exhausted result
+continues through WeatherReporter's ordinary `validation_rejected` failure
+path, and an operational or generation failure during correction remains that
+profile's ordinary operational failure.
+
+For concurrent comparison, every profile should use the same prompt repair
+budget. A corrective call remains part of that profile's one prepared
+execution and uses PromptKit's existing backend capacity pool. One profile's
+repair or failure must not cancel independent peers.
+
+## Repair Observability And Comparison Contract
+
+The actual repair count is safe operational provenance and should be visible
+where WeatherReporter already reports completed validation. Generation, batch,
+and comparison action summaries should expose it without exposing candidates,
+schemas, or diagnostics. Explicit execution debug output should add it to the
+validation object alongside PromptKit's already mapped cumulative usage.
+
+Profile comparison needs this value in `comparison.json`: a successful result
+that required correction is materially different from a first-pass success
+when evaluating model reliability, latency, and cost. The manifest should
+therefore advance to `weatherreporter.comparison.v2` and add a non-negative
+`repairAttempts` field to each result. The field is zero when no corrective
+call began, including ordinary first-pass success. A failure carries the count
+when PromptKit returned a completed validation result; it is omitted only when
+execution failed before a completed validation result made the value known.
+
+The v2 manifest should remain flat, strict, deterministic, and atomically
+published. WeatherReporter does not need to preserve v1 replacement
+compatibility: comparison bundles are operator-owned development outputs, and
+the current integration contract intentionally recognizes only its current
+schema. The release notes and comparison documentation must call out the
+version change so an operator can remove or relocate an older bundle before
+using guarded replacement at the same destination.
+
+## Credential Semantics
+
+PromptKit v0.7.0 treats `APIKeyEnv` as an optional lookup source. If the
+environment variable is absent or blank and no direct credential is supplied,
+the built-in client omits `Authorization` and lets the endpoint respond.
+`APIKeyRequired` is the distinct signal that a usable credential must be
+provided locally.
+
+WeatherReporter cannot supply PromptKit's request-scoped direct API-key value,
+so a profile reporting `APIKeyRequired` remains unsupported and must fail
+before weather collection. WeatherReporter should not require a nonblank value
+for an optional `APIKeyEnv` during application preflight. The built-in client
+should omit `Authorization` when that source is unavailable and let the
+endpoint return any authentication failure through the ordinary structured
+generation-error path.
+
+## Structured Generation Failures
+
+PromptKit v0.7.0's `GenerationError` can report a provider HTTP status plus
+bounded provider code, type, and message. WeatherReporter should consume that
+type only inside the PromptKit adapter and map any adopted fields into a
+project-owned immutable error. PromptKit dependency types must not become app
+or CLI contracts.
+
+HTTP status is safe enough for ordinary diagnostics. Provider code, type, and
+message remain untrusted and may contain request or schema fragments. They
+must never enter ordinary errors, action summaries, comparison manifests,
+logs, generated reports, or Distributor payloads. The full structured
+diagnostic belongs only in an explicitly requested secure `--llm-debug-dir`
+`failure.json` artifact. That artifact may contain PromptKit's normalized
+bounded fields but never the raw provider body, headers, endpoint, credentials,
+or reconstructed request.
+
+Initial-call and corrective-call non-2xx responses should follow the same
+mapping. Cancellation and deadline categories continue to take precedence over
+provider classification where PromptKit preserves those identities.
+
+## Testing Policy
+
+The default suite must remain deterministic, offline, and credential-free.
+Use injected PromptKit clients and synthetic embedded or temporary assets for
+consumer behavior; do not call OpenRouter, Rakestrawhome, or a local endpoint.
+
+Risk-based coverage should include:
+
+- all embedded prompts and inherited domain profiles inspecting successfully
+  under PromptKit `v0.8.0`;
+- unchanged effective targets and report-to-profile assignments after the
+  alias refactor;
+- external standalone and derived profile precedence, plus selected missing,
+  cyclic, and malformed-base failures at the WeatherReporter boundary;
+- end-to-end preflight and prepared execution through the maintained
+  endpoint-only `weather-light` override without exposing its endpoint;
+- offline inspection of `rakestrawhome-gemma-4-31b`;
+- a first-pass valid result with zero repairs;
+- an invalid structured result repaired successfully within one corrective
+  call;
+- one-attempt exhaustion returning failed validation and no published report;
+- a corrective generation failure retaining its safe category and provider
+  status policy;
+- cumulative usage and actual repair-count mapping;
+- comparison peers remaining independent when one profile repairs, exhausts,
+  or fails;
+- v2 comparison manifest validation and guarded replacement; and
+- absent or blank optional `APIKeyEnv` values reaching the provider without an
+  `Authorization` header, while `APIKeyRequired` profiles fail preflight.
+
+Do not reproduce PromptKit's internal matrices for path traversal, JSON tree
+bounds, response framing, inheritance depth, repair prompt construction, or
+provider-detail normalization. WeatherReporter tests should protect only its
+adapter mappings, application policy, provenance, publication, and public
+contracts. Run ordinary and race-enabled repository tests because the repaired
+execution path participates in concurrent comparisons.
+
+## Documentation And Release Impact
+
+Implementation must update each canonical owner whose contract changes:
+
+- `docs/policy/architecture.md` for prompt-execution, credential, diagnostic,
+  and comparison invariants;
+- `docs/config.md` and the maintained local profile example for profile-source,
+  inheritance, and credential semantics;
+- `docs/integrations/promptkit.md` for exact prompt versions, repair policy,
+  profile composition, Rakestrawhome availability, and safe errors;
+- `docs/integrations/comparison-bundle.md` for the v2 manifest and repair count;
+- `docs/cli.md` for repair-count fields in action summaries;
+- `docs/operations.md` for changed failure behavior and any explicit provider
+  diagnostic capture;
+- focused internal PromptKit adapter, app orchestration, prompt-debug, and
+  comparison documentation; and
+- release notes for the dependency jump, prompt version change, possible
+  additional model call, credential behavior, profile inheritance, diagnostic
+  behavior, and comparison schema change.
+
+Current-state documentation must not describe this behavior until the
+implementation lands. PromptKit remains the canonical owner of its complete
+built-in catalogs, YAML merge rules, transport limits, corrective-message
+construction, and public Go API.
+
+## Scope
+
+The completed feature includes:
+
+- the direct module upgrade and tidy dependency graph;
+- a v0.6.0 compatibility audit of WeatherReporter's supported PromptKit paths;
+- inherited WeatherReporter domain profile definitions with unchanged
+  effective targets;
+- correction of application preflight so PromptKit endpoint-only profiles work
+  as documented while retaining a required model identity;
+- ordinary access to the Rakestrawhome built-in profile;
+- PromptKit's optional-credential policy, while direct-key-required profiles
+  remain unsupported;
+- `repair_attempts` on all operational prompts and exact prompt-version bumps;
+- project-owned repair budget, actual-attempt, usage, and provenance mappings;
+- repair observability in action summaries, explicit debug output, and a v2
+  comparison manifest;
+- safe provider HTTP status in ordinary errors and bounded provider detail only
+  in explicit secure debug capture;
+- focused offline and race-enabled regression coverage; and
+- canonical current-state and release documentation updated with the code.
+
+## Non-Goals
+
+This upgrade does not include:
+
+- application-implemented repair prompts or provider transport;
+- retries for HTTP, network, timeout, capacity, or other operational failures;
+- automatic profile escalation, fallback, ranking, or resampling;
+- changing the weather profile ladder, default report assignments, or concrete
+  model targets beyond inheriting their maintained PromptKit definitions;
+- making Rakestrawhome a default or adding provider-specific configuration;
+- live-provider tests or a permanent benchmark framework;
+- exposing raw provider responses or sensitive diagnostics routinely;
+- a general prompt-source or pipeline plugin system; or
+- compatibility shims for PromptKit versions older than `v0.8.0`.
+
+## Completion Criteria
+
+The roadmap is complete when:
+
+- `go.mod` and `go.sum` resolve PromptKit `v0.8.0` without a replacement,
+  workspace, or vendor tree;
+- all PromptKit v0.6.0 compatibility points relevant to WeatherReporter have
+  been checked and valid supported inputs retain project-owned error identity;
+- the three WeatherReporter profiles inherit the intended PromptKit built-ins,
+  retain their logical IDs, and inspect to the intended effective targets;
+- external standalone and inherited overrides obey documented precedence and
+  failure behavior;
+- the maintained endpoint-only local override passes application preflight,
+  retains an empty backend ID, and keeps its endpoint out of ordinary values;
+- `rakestrawhome-gemma-4-31b` is selectable through ordinary generation and
+  comparison paths without WeatherReporter backend registration;
+- every operational prompt has one bounded repair attempt at exact
+  version `2.1.0`;
+- inspection, preparation, execution, debug, and comparison values accurately
+  preserve configured and actual repair counts;
+- first-pass success, repaired success, repair exhaustion, repair generation
+  failure, and explicit empty content follow the documented outcomes;
+- the v2 comparison bundle distinguishes first-pass and repaired results;
+- credential preflight accepts absent optional environment credentials while
+  rejecting direct-key-required profiles, and provider-error disclosure does
+  not leak sensitive values;
+- the default test suite is offline and deterministic, ordinary and race
+  validation pass, and no redundant upstream implementation suite is copied;
+  and
+- every implemented contract is documented by its canonical current-state
+  owner and disclosed in the eventual release notes.

docs/roadmap/promptkit.md

@@ -1,327 +0,0 @@
-# Promptkit Migration Roadmap
-
-Status: Accepted migration policy; the migration itself is unimplemented.
-
-## Purpose
-
-This roadmap defines the scope and desired end state for replacing the
-external Scriptorium CLI integration with the Promptkit Go library. The
-migration is not yet implemented. Current Scriptorium behavior remains
-documented in the [Scriptorium integration guide](../integrations/scriptorium.md)
-until the replacement is complete.
-
-A separate staged implementation plan will describe how to move from the
-current code to this target state. That plan should reference this roadmap
-rather than redefine its architectural decisions or scope.
-
-## Desired End State
-
-Status: Accepted target state; unimplemented.
-
-Weatherreporter uses a pinned released version of
-`gitea.maximumdirect.net/eric/promptkit` as its in-process prompt preparation
-and LLM execution engine. The `scriptorium` executable, subprocess adapter,
-configuration, runtime dependency, and integration documentation have been
-removed.
-
-The migration does not change weatherreporter's fundamental product behavior.
-Weather selection, forecast derivation, report periods, module construction,
-Recent Changes, generated-text interpretation, Markdown templates, durable
-state, inspection, output copies, and distributor notification remain owned by
-weatherreporter.
-
-All report prompts and private response schemas are versioned application
-assets. Operators may configure Promptkit execution profiles without replacing
-the report-owned prompt and schema corpus. One Promptkit engine is constructed
-per CLI invocation and shared by every report in that invocation, including
-all reports in a morning or evening batch.
-
-Promptkit is isolated behind a weatherreporter-owned prompt execution contract.
-Promptkit request, result, validation, error, profile, backend, and provider
-types do not leak into application orchestration, report definitions, domain
-packages, CLI summaries, state contracts, or distributor behavior.
-
-## Goals
-
-Status: Accepted migration scope; unimplemented.
-
-- Remove the runtime dependency on the `scriptorium` executable.
-- Replace shell-free subprocess orchestration with typed in-process Promptkit
-  preparation and execution.
-- Preserve the seven report definitions and their existing prompt IDs.
-- Preserve both direct-Markdown and generated-text-template report workflows.
-- Preserve deterministic module snapshots and structured Recent Changes.
-- Preserve context cancellation, actionable errors, secret redaction, and
-  inspectable failures.
-- Improve durable prompt provenance with prompt, input, profile, model,
-  validation, usage, and timing metadata.
-- Keep content-rich prompt and response diagnostics separate from routine
-  metadata and CLI output.
-- Keep tests offline and deterministic through injected Promptkit model
-  clients and fixtures.
-
-## Non-Goals
-
-Status: Accepted migration scope; unimplemented.
-
-The migration will not:
-
-- move meteorological selection, derivation, thresholds, or comparison logic
-  into prompts or Promptkit;
-- send raw unbounded Weather API responses to the model;
-- replace weatherreporter's generated-text domain validation or Markdown
-  template rendering;
-- add a general workflow engine, provider plugin system, or arbitrary backend
-  registry to weatherreporter;
-- add automatic provider, validation, or capacity retries;
-- add concurrent report generation to the existing sequential batch workflow;
-- expose Promptkit types as a weatherreporter component contract;
-- keep a production-selectable Scriptorium/Promptkit dual-run mode; or
-- use an unpublished Promptkit commit, committed Go workspace, or committed
-  local module replacement.
-
-## Locked Decisions
-
-Status: Accepted decisions for the unimplemented migration.
-
-### Dependency And Versioning
-
-- The initial integration will pin Promptkit `v0.3.0`.
-- Coordinated local development may temporarily use the sibling Promptkit
-  checkout, but committed module metadata must reference the tagged release.
-- A future Promptkit upgrade requires an explicit review of the public engine,
-  prompt/profile/schema formats, error identities, validation behavior, and
-  outbound provider contract used by weatherreporter.
-
-### Application Boundary
-
-- Promptkit remains an adapter boundary even though it runs in process.
-- A weatherreporter-owned contract will represent preparation, execution,
-  output formats, validation, usage, provenance, and neutral error categories.
-- The Promptkit adapter will map public Promptkit values into that contract at
-  the boundary.
-- App orchestration and test fakes will depend on the weatherreporter contract,
-  not on Promptkit.
-- Existing Scriptorium-specific generation mode names will be replaced with
-  provider-neutral names.
-
-### Prompt And Schema Ownership
-
-- Weatherreporter will embed all report prompt definitions, prompt content,
-  and private response schemas.
-- Prompt assets will remain separate files rather than inline Go strings.
-- The current Scriptorium prompt corpus will be retrieved before the
-  implementation stage that establishes the embedded Promptkit assets.
-- The retrieved corpus will be reviewed and converted to the pinned Promptkit
-  format without changing report intent or prompt IDs.
-- The four existing generated-text prompt fragments and schemas under
-  `internal/reporttemplate` will be reconciled with that corpus rather than
-  duplicated.
-- Direct-Markdown prompt assets for the three-day, weekend, and storm reports
-  will become weatherreporter-owned assets.
-- Weatherreporter needs one centralized embedded prompt/schema source; it does
-  not need Notarius's multi-module asset-flattening registry.
-
-### Profiles, Backends, And Credentials
-
-- Execution profiles remain operator-configurable rather than embedded report
-  policy.
-- Configuration will support at most one external profile source: a profile
-  directory or a single profile file.
-- Prompt definitions may provide their normal default profile, while
-  weatherreporter may support an explicit configured profile selection.
-- Credential values remain in environment variables or file-backed
-  environment secrets. Configuration contains only credential source names.
-- Provider credentials must not appear in logs, errors, CLI output, durable
-  metadata, preparation artifacts, execution artifacts, or debug summaries.
-- Weatherreporter will not expose Promptkit's general backend registry as
-  arbitrary application configuration.
-
-### Engine Lifetime
-
-- One Promptkit engine will be constructed per CLI invocation at the
-  application composition boundary.
-- Single-report generation will use that engine for preparation and execution.
-- Morning and evening batches will share the same engine across every planned
-  report.
-- Per-report orchestration will not construct its own default Promptkit engine.
-- Promptkit backend capacity state and HTTP transport will therefore be shared
-  consistently for the invocation.
-
-### Prompt Input
-
-- Promptkit will continue to receive the curated `data_package` produced by
-  `internal/promptinput`.
-- Weatherreporter will serialize the data package once, atomically persist
-  those exact bytes, and supply the same bytes as a Promptkit inline artifact.
-- The managed data-package path may be supplied as non-secret artifact
-  provenance.
-- Weatherreporter will not delegate unrestricted path loading to Promptkit's
-  default file artifact reader.
-- The same immutable Promptkit request will be used for preparation and
-  execution so the preflight and run inputs cannot diverge.
-
-### Preparation And Execution
-
-- Promptkit `Prepare` replaces the current Scriptorium render preflight.
-- Promptkit `Run` performs both Markdown and structured generated-text
-  execution.
-- Promptkit basic validation will be used where appropriate for direct
-  Markdown output.
-- Promptkit JSON Schema validation provides the provider-facing and first
-  structured-output check for generated-text reports.
-- Weatherreporter's `internal/generatedtext` validation remains the final
-  report-specific domain boundary.
-- Weatherreporter's `internal/reporttemplate` remains responsible for
-  generated-text Markdown rendering.
-- Weatherreporter will atomically persist Promptkit output rather than asking
-  the dependency to write managed report files.
-- The migration will not rely on Promptkit output repair. Promptkit v0.3.0's
-  public engine validates in a single pass even when a prompt declares repair
-  attempts.
-
-## Durable Artifacts And Observability
-
-Status: Accepted design constraints; unimplemented.
-
-Routine durable artifacts should retain useful non-secret provenance without
-persisting full rendered prompts by default.
-
-The preparation record should contain:
-
-- prompt ID and version;
-- prompt definition hash;
-- rendered prompt hash;
-- input hashes;
-- selected profile and backend identity;
-- effective model identity;
-- output contract summary; and
-- preparation timing.
-
-The execution record and run metadata should contain, when available:
-
-- Promptkit run ID;
-- prompt ID, version, and hashes;
-- input hashes;
-- selected profile, backend, and model identity;
-- generated-content hash;
-- token usage;
-- start, end, and duration;
-- validation status and bounded diagnostics; and
-- the path of any separately persisted raw generated output.
-
-Provider endpoints, full effective model parameter maps, rendered messages,
-schema bodies, data-package contents, and generated content do not belong in
-routine metadata or CLI summaries.
-
-Rendered messages and other content-rich preparation or response diagnostics
-will be available only through an explicitly enabled debug mechanism. Debug
-artifacts must be documented as potentially sensitive, must not contain
-credentials, and must have a clear operator-owned retention policy.
-
-## Failure Contract
-
-Status: Accepted design constraints; unimplemented.
-
-Promptkit returns a completed `RunResult` for output-validation failure but no
-partial result for operational preparation or execution errors. Weatherreporter
-will preserve that distinction.
-
-- A preparation failure produces a redacted weatherreporter-owned failure
-  receipt with report, RunID, prompt, stage, timing, and classified error
-  context. It does not fabricate a Promptkit preparation result.
-- An operational execution failure retains the successful preparation record
-  and adds a redacted execution failure receipt. No partial Promptkit result or
-  model output is invented.
-- A Promptkit validation failure retains the returned result, raw generated
-  output, validation details, and safe provenance before the report fails.
-- A later weatherreporter generated-text decode, domain-validation, or template
-  failure retains every raw and validated artifact reached before that stage.
-- Context cancellation takes precedence when the caller context is canceled.
-- Promptkit capacity rejection maps to a weatherreporter-owned error category.
-  It is an operational report failure, not invalid model output.
-- Single-report commands return the classified failure with available
-  inspectable paths.
-- Batch runs continue independent later reports under the existing batch
-  failure policy.
-- The migration adds no automatic retries. Any future retry policy belongs to
-  app orchestration, not the Promptkit adapter.
-
-## Compatibility Requirements
-
-Status: Accepted design constraints; unimplemented.
-
-- Report IDs, prompt IDs, report selection, valid periods, artifact grouping,
-  output names, and distributor bundle behavior remain stable.
-- Module snapshot and Recent Changes behavior remains deterministic.
-- Promptkit receives only the existing curated prompt-input boundary.
-- Generated reports continue to use the managed Markdown path as the
-  distributor upload source.
-- RunID lookup and inspection remain available for successful and failed runs.
-- Existing managed state paths remain stable where their meaning is unchanged.
-  Scriptorium-specific artifact names or schemas may change when retaining
-  them would misrepresent the new contract.
-- Any artifact or metadata schema change is explicit, documented, and covered
-  by state and inspection tests.
-- Prompt or generated content is not added to routine logs or CLI summaries.
-- Tests do not require live Promptkit providers or credentials.
-
-## Verification And Completion Criteria
-
-Status: Proposed completion criteria for the unimplemented migration.
-
-The migration is complete when:
-
-- all seven reports prepare and execute through Promptkit using embedded
-  report-owned assets;
-- direct-Markdown and generated-text-template paths have deterministic offline
-  adapter and app-level coverage;
-- preparation, provider failure, capacity rejection, cancellation, timeout,
-  Promptkit validation failure, generated-text validation failure, template
-  failure, and successful generation preserve their specified artifacts;
-- morning and evening batches construct one shared engine and preserve current
-  collection, planning, ordering, continuation, output, and notification
-  behavior;
-- configuration examples load and contain no Scriptorium fields;
-- CLI summaries and inspection commands expose the new artifact contract
-  without Promptkit dependency types;
-- Scriptorium code, configuration, tests, and runtime documentation have been
-  removed;
-- non-roadmap documentation describes only the implemented Promptkit
-  integration;
-- `go test ./...`, CLI help validation, and `git diff --check` pass; and
-- no committed `go.work`, local `replace`, live-provider test, or secret-bearing
-  fixture remains.
-
-Fixture-based comparison with the current Scriptorium behavior is sufficient
-for migration verification. A production-selectable dual-run period is not
-required because model calls are nondeterministic, costly, and difficult to
-compare meaningfully.
-
-## External Prerequisite
-
-Status: Required and unimplemented.
-
-Before implementing the embedded asset stage, the current Scriptorium prompt
-corpus must be made available in this repository. It should include the seven
-prompt definitions, referenced content files, private response schemas,
-relevant default-profile declarations, and any shared prompt fragments needed
-to reproduce current report behavior.
-
-## Open Questions
-
-Status: Open; these require decisions before implementation.
-
-- What exact `promptkit.*` configuration fields should replace the current
-  Scriptorium fields, including the name and precedence of an optional explicit
-  profile override?
-- Should weatherreporter expose Promptkit's conventional `local` backend
-  registration as a narrow configuration feature, or rely initially on
-  built-in and endpoint-only profiles?
-- Should report definitions store an explicit Promptkit prompt version, or
-  should each embedded prompt ID be required to have exactly one version?
-- What CLI or configuration control enables sensitive prompt/response debug
-  artifacts, and where should those artifacts live?
-- What final names and schema versions should replace the
-  Scriptorium-specific preflight and run-result artifacts while balancing
-  semantic clarity with existing state-path compatibility?

docs/roadmap/scriptorium/prompts/common/data_package.user.md

@@ -1,107 +0,0 @@
-Your task is to generate a local weather forecast analysis from the following YAML data package, which is prepared by the weatherreporter application.
-
-Your analysis will be incorporated into a structured, user-facing report. The report may be for today, tomorrow, or a future date. You will be provided with precise output instructions following the YAML data package.
-
-# SOURCE ROLES AND WEIGHTING
-
-Use `report` and `briefing.metadata` for framing: location, timezone, units, valid period, and generation time. Do not treat metadata as forecast evidence except where it identifies source relevance, such as alert counts or location matching.
-
-For weather interpretation, think in four source layers, in this order:
-
-## 1. Active hazard and risk products
-
-Give appropriate weight to official hazard or risk products that the package identifies as relevant to the forecast location and valid period. This includes current or future package sections for alerts, watches, warnings, advisories, SPC outlook polygon hits, WPC excessive rainfall outlook polygon hits, mesoscale discussions, precipitation discussions, or similar location-matched products.
-
-These products have already been filtered or matched to the forecast location. Treat them as locally relevant, but distinguish product strength:
-
-- Active warnings are urgent and should dominate the lead and relevant sections.
-- Watches and advisories should be mentioned prominently when they affect the report period.
-- Outlook/risk polygon hits may or may not be important local risk signals; they can vary significantly with respect to both impact and certainty. Higher risk levels deserve greater and more detailed attention than lower risk levels. Outlook/risk polygons should elevate the caveat, uncertainty, and forecast outlook discussion without necessarily implying that severe weather is likely or even probable at the exact point.
-- Mesoscale discussions and precipitation discussions are strong short-term situational-awareness signals when they cover the location and valid period.
-
-For the current schema, use `briefing.applicable_risk_products.alert_digest` and `briefing.metadata.alerts` to determine whether relevant local alerts exist. If `relevant_count` is zero, do not imply that the report location is under an active alert merely because `active_count` is nonzero.
-
-## 2. Derived summaries
-
-Use derived summaries as the baseline interpretation of the local forecast when no active hazard product requires stronger framing.
-
-For the current schema:
-
-- Use `briefing.derived_daily_summary`, if present, for the overall daily theme, high/low temperature, dominant conditions, daily precipitation probability, most likely precipitation hour, and thunder flag.
-- Use `briefing.derived_daypart_summaries`, if present, for daypart timing, dominant conditions, temperature ranges, maximum precipitation chances, and notable conditions.
-- Use `briefing.precip_timing`, if present, as the deterministic summary of maximum precipitation probability and whether thunder is mentioned in the structured local forecast.
-- Use `briefing.outdoor_windows`, if present, only if it adds meaningful signal to the daypart discussion. Do not turn the report into outdoor-planning advice.
-
-## 3. Narrative products
-
-Use `briefing.narrative_products` for meteorological context, prose framing, uncertainty, and conditional outcomes. This includes the AFD, Weather Story, NWS narrative forecast text, SPC narrative text, WPC discussions, CPC discussions, and similar products. These products have the potential to add the highest degree of value to the weather report, but should be read with important context and caveats as discusssed below.
-
-For the current schema:
-
-- Use `briefing.narrative_products.narrative_forecast.periods` to confirm and reconcile official day/night wording, high/low temperatures, winds, and broad precipitation wording.
-- Use `briefing.narrative_products.weather_story` to understand what the NWS considered the public-facing weather headline at the start of the day. Caveats: the covered forecast area for this product is relatively large, and it is only updated once per day, so be wary of discussion that relates to forecast events that have already occurred, or to geographical areas outside the forecast location.
-- Use `briefing.narrative_products.area_forecast_discussion.key_messages` to understand what the NWS forecast office considered the most relevant, public-facing key messages. This product is updated somewhat more frequently than `briefing.narrative_products.weather_story`, but otherwise the same caveats apply: the covered forecast area for this product is relatively large, and one or more messges may relate to forecast events that have already occurred, or to geographical areas outside the forecast location.
-- Use `briefing.narrative_products.area_forecast_discussion.short_term` for setup, local/regional nuance, confidence, uncertainty, and forecast dependencies affecting the next 12-48 hours.
-- Use `briefing.narrative_products.area_forecast_discussion.long_term` only if it affects the valid day, the overnight period immediately following it, or to support a brief note about what to watch for over the following day/days.
-- If `briefing.narrative_products.spc_convective_discussion.discussions` is present, use it to provide context to the severe weather forecast. Because the covered forecast area for this product is relatively large, be wary of discussion that relates to geographical areas far from the forecast location, except as a discussion of the broader synoptic pattern. Additionally, because outlooks are not typically canceled after they are issued, be wary of an outlook that relates to potential severe weather that has not (and will not) materialize based upon more recently updated forecast data.
-
-Do not let broad regional narrative language override point-specific local forecast data unless an applicable hazard/risk product, local forecast data, or the narrative itself clearly supports that local implication.
-
-## 4. Raw underlying data
-
-Use `briefing.raw_data` as the source of truth for exact timing, temperatures, precipitation probabilities, wind, humidity/dew point, and condition changes when more detail is needed.
-
-For the current schema, `briefing.raw_data.hourly_forecast.periods` is the most granular local forecast source.
-
-Use `briefing.raw_data.current_conditions` only as generation-time context.
-
-If raw data and derived summaries appear to disagree, prefer the raw data for exact values and timing, but treat the disagreement as a reason to be cautious rather than as permission to invent an explanation.
-
-# CONFLICT RESOLUTION
-
-When sources differ, ask:
-
-1. Which source is most local to the forecast point?
-2. Which source is valid for the report period or near-term window?
-3. Which source is most authoritative for the type of claim being made?
-4. Is the source describing the most likely outcome, or a conditional/low-probability hazard?
-
-Do not turn regional severe-weather discussion into a deterministic local severe-weather forecast unless point-specific data supports that conclusion. Conversely, do not bury a location-specific warning, watch, advisory, outlook polygon hit, or valid mesoscale discussion merely because the baseline derived summary is otherwise quiet.
-
-# HAZARD AND SEVERE-WEATHER RULES
-
-Mention a hazard only to the extent supported by location-specific products, local structured forecast data, or clearly applicable narrative text.
-
-Preserve product strength and uncertainty. An SPC Slight Risk, WPC Excessive Rainfall Outlook, or similar polygon hit is a locally relevant risk signal, not a warning and not a guarantee of local impact.
-
-Preserve geography. If the package says the main severe risk is north of the metro, north of I-70, along a front, or over a specific part of the CWA, carry that limitation into the report.
-
-Preserve timing. Do not say storms “arrive,” “clear,” “develop,” or “move in” at a specific time unless the hourly data, narrative forecast, Weather Story, AFD, or hazard product supports that timing.
-
-# PRECIPITATION RULES
-
-Do not overstate low precipitation probabilities.
-
-Use precipitation wording consistently:
-
-- 0–14%: usually omit unless relevant to a trend, caveat, hazard product, regional risk, or timing uncertainty.
-- 15–24%: “slight chance,” “isolated,” “spotty,” or “brief passing shower/storm possible.”
-- 25–39%: “chance,” “scattered,” or “some showers/storms possible.”
-- 40–59%: “good chance” or “showers/storms likely enough to plan around.”
-- 60%+: “likely,” “wet,” or “unsettled,” if consistent with the narrative forecast.
-
-If the package does not provide rainfall amounts, say nothing about totals unless a narrative product provides a supported qualitative signal. Do not invent QPF.
-
-If local precipitation chances are low and no meaningful local impacts are expected, do not imply that, e.g., thunderstorms are likely solely because regional precipitation or severe weather appears in a narrative product. Mention the regional caveat if relevant, but preserve geographic limits.
-
-# STYLE RULES
-
-- Plainspoken, precise, and weather-literate.
-- Compact, but not shallow.
-- No generic public-safety filler.
-- No umbrella/rain-jacket/snow-boots advice unless unusually warranted by a specific hazard.
-- No commute or outdoor-plan boilerplate.
-- No unsupported precision.
-- No apologies for missing data.
-- Avoid phrases like “developing,” “moving in,” “clearing,” “threatening,” or “impacting” unless the timing and trend are clearly supported by the package.
-- Prefer “most likely,” “possible,” “favored,” “conditional,” “limited coverage,” and “worth watching” when those phrases accurately reflect the data.

docs/roadmap/scriptorium/prompts/daily/daily_generated_text.user.md

@@ -1,63 +0,0 @@
-TASK: You are writing structured prose slots for a daily weather report.
-
-The calling application will render the final Markdown report. Your job is not to write the full report. Return only a JSON object matching the configured schema.
-
-Use only the supplied `data_package`. Do not invent weather details, times, hazards, probabilities, or impacts that are not supported by the data.
-
-The report focuses on the valid period in `report.valid_period`, which corresponds to an upcoming civil day for the configured location.
-
-Return these fields:
-
-- `summary`: required. 1-2 sentences summarizing the main weather story for the valid period.
-- `forecast_discussion`: required. 3 paragraphs explaining the broader setup, trend, and/or forecast reasoning most relevant to the valid period.
-- `precipitation_timing`: optional. Include only when the deterministic `precip_timing` module contains precipitation windows. 
-
-Return JSON only.
-
-# summary
-
-The summary should typically consist of two sentences.
-
-If an active warning is relevant during the report period, lead with the hazard. Otherwise, the first sentence should state the most likely local weather outcome for the valid period, including the overall character of the weather and expected temperature/temperature range. 
-
-The second sentence should state the most important active hazard, caveat, uncertainty, or alternate outcome, if one exists. If there is no meaningful caveat, the second sentence may be omitted.
-
-In the lead, distinguish the main weather outcome from the caveat. If showers and thunderstorms have different timing, state that difference rather than combining them as a single risk throughout the valid period. If the main caveat is a regional severe-weather or precipitation risk displaced from the report location, state that limitation clearly.
-
-Example style:
-
-- “Today is expected to be warm and dry, with mostly clear skies. There is a slight chance of isolated showers and thunderstorms developing from late afternoon into early evening.”
-
-# forecast_discussion
-
-Use narrative products to explain the “why” behind the local forecast when useful. Useful context may include:
-
-- synoptic pattern
-- fronts or boundaries
-- shortwaves, troughs, or ridges
-- instability, moisture, shear, forcing, or capping
-- regional placement of precipitation or severe-weather chances
-- hazard types and timing windows
-- confidence or uncertainty
-- conditional outcomes
-- relevant notes about the following day or days
-
-In most cases, the `forecast_discussion` should include three paragraphs:
-
-1. 2–4 sentences summarizing the relevant local/regional setup.
-2. 2-4 sentences describing the main forecast uncertainty or conditional factor, if present.
-3. 2-4 sentences about the next day or broader pattern if supported.
-
-# precipitation_timing
-
-Optional. Return only if precipitation is forecast. If present, provide 1 to 4 sentences to add practical context, including:
-
-  - Whether the precipitation is associated with a moving frontal boundary, convective initiation, or wide stratiform rain (if this can be determined from the data package);
-  - The expected type, intensity, and duration of the precipitation; and
-  - Any caveats or uncertainty with respect to the onset, duration, or occurrance of the precipitation.
-
-# Narrative Source Selection
-
-As previously noted, use `briefing.derived_daily_summary`, `briefing.derived_daypart_summaries`, `briefing.narrative_products.narrative_forecast.periods`, and `briefing.raw_data.hourly_forecast.periods` as your primary reference sources for forecast.
-
-As previously noted, narrative sources can provide significant added value, but you must think carefully about whether information from the available narrative sources is relevant to the valid period. If the valid period relates to a civil day that is several days in the future, then products such as `briefing.narrative_products.weather_story`, `briefing.narrative_products.area_forecast_discussion.key_messages`, and `briefing.narrative_products.area_forecast_discussion.short_term` may have limited relevance. On the other hand, `briefing.narrative_products.area_forecast_discussion.long_term` may have relatively more relevance.

docs/roadmap/scriptorium/prompts/daily_report/daily_report.system.md

@@ -1,13 +0,0 @@
-You are WeatherReporter, a concise personal weather briefing writer.
-
-You generate local daily weather briefings from structured data packages prepared by the weatherreporter application.
-
-The reader is weather-literate and interested in meteorology. Do not write a generic public weather report. Do not include routine lifestyle advice such as bringing an umbrella, wearing a jacket, driving carefully, or checking the radar unless the forecast contains a specific hazard or meaningful uncertainty that makes such a note unusually important.
-
-Your job is to identify the most likely weather outcome, state meaningful caveats or uncertainty, summarize the daypart forecast, and explain the meteorological setup when useful.
-
-Use only the provided data package as your source of truth. Do not invent forecast details, alerts, hazards, timing, locations, rainfall amounts, severe weather risks, synoptic features, confidence levels, or recent changes that are not supported by the package.
-
-Write in plain, precise, meteorologically informed language. Avoid hype, filler, generic safety advice, and TV-weather style. Do not mention that you are an AI model. Do not expose internal implementation details,  field names, source hashes, endpoint names, or missing internal data sources unless the missing data materially limits the report.
-
-The report should be compact, but it may include meteorological context when the forecast discussion supports it.

docs/roadmap/scriptorium/prompts/daily_report/daily_report.user.md

@@ -1,234 +0,0 @@
-Generate a Daily Weather Report from the following weatherreporter YAML data package.
-
-The report may be for today, tomorrow, or a future date. Determine the correct framing from report, briefing.metadata, the report valid period, and the derived daily date when present.
-
-Use Markdown.
-
-# CORE EDITORIAL GOAL
-
-This is a personal weather-nerd briefing, not a generic public forecast. The report should answer:
-
-1. What is the most likely local weather outcome for the day?
-2. What active hazard, caveat, uncertainty, or alternate outcome matters relative to that most likely outcome?
-3. If precipitation is likely, impactful, or meteorologically meaningful, when is it favored, how significant is it, and is severe weather possible?
-4. What should each daypart generally look and feel like?
-5. What broader meteorological setup or forecast dependency is worth watching?
-
-# SOURCE ROLES AND WEIGHTING
-
-Use report and briefing.metadata for framing: location, timezone, units, valid period, generation time, and today/tomorrow/future wording. Do not treat metadata as forecast evidence except where it identifies source relevance, such as alert counts or location matching.
-
-For weather interpretation, think in four source layers, in this order:
-
-## 1. Active hazard and risk products
-
-Give substantial weight to official hazard or risk products that the package identifies as relevant to the forecast location and valid period. This includes current or future package sections for alerts, watches, warnings, advisories, SPC outlook polygon hits, WPC excessive rainfall outlook polygon hits, mesoscale discussions, precipitation discussions, or similar location-matched products.
-
-These products have already been filtered or matched to the forecast location. Treat them as locally relevant, but distinguish product strength:
-
-- Active warnings are urgent and should dominate the lead and relevant sections.
-- Watches and advisories should be mentioned prominently when they affect the report period.
-- Outlook/risk polygon hits are important local risk signals, but they can vary significantly with respect to both impact and certainty. Higher risk levels deserve greater and more detailed attention than lower risk levels. Outlook/risk polygons should elevate the caveat, uncertainty, and ## What to Watch discussion without necessarily implying that severe weather is certain at the exact point.
-- Mesoscale discussions and precipitation discussions are strong short-term situational-awareness signals when they cover the location and valid period.
-
-For the current schema, use `briefing.applicable_risk_products.alert_digest` and `briefing.metadata.alerts` to determine whether relevant local alerts exist. If `relevant_count` is zero, do not imply that the report location is under an active alert merely because `active_count` is nonzero.
-
-## 2. Derived summaries
-
-Use derived summaries as the baseline interpretation of the local forecast when no active hazard product requires stronger framing.
-
-For the current schema:
-
-- Use briefing.derived_daily_summary for the overall daily theme, high/low temperature, dominant conditions, daily precipitation probability, most likely precipitation hour, and thunder flag.
-- Use briefing.derived_daypart_summaries for daypart timing, dominant conditions, temperature ranges, maximum precipitation chances, and notable conditions.
-- Use briefing.precip_timing as the deterministic summary of maximum precipitation probability and whether thunder is mentioned in the structured local forecast.
-- Use briefing.outdoor_windows only if it adds meaningful signal to the daypart discussion. Do not turn the report into outdoor-planning advice.
-
-## 3. Narrative products
-
-Use `briefing.narrative_products` for meteorological context, prose framing, uncertainty, and conditional outcomes. This includes the AFD, Weather Story, NWS narrative forecast text, SPC narrative text, WPC discussions, CPC discussions, and similar products.
-
-For the current schema:
-
-- Use `briefing.narrative_products.narrative_forecast.periods` to confirm and reconcile official day/night wording, high/low temperatures, winds, and broad precipitation wording.
-- Use `briefing.narrative_products.weather_story` to understand what the NWS considers the most relevant, public-facing headlines for the short-term forecast. Because the covered forecast area for this product is relatively large, be wary of discussion that relates to geographical areas outside the forecast location, and preserve spatial limits such as “north of I-70.”
-- Use `briefing.narrative_products.area_forecast_discussion.key_messages` and `briefing.narrative_products.area_forecast_discussion.short_term` for setup, local/regional nuance, confidence, uncertainty, and forecast dependencies affecting the report period.
-- Use `briefing.narrative_products.area_forecast_discussion.long_term` only if it affects the valid day, the overnight period immediately following it, or a brief note about the following day/days.
-- If `briefing.narrative_products.spc_convective_discussion.discussions` is present, use it to understand  and to provide context to the severe weather forecast. Because the covered forecast area for this product is relatively large, be wary of discussion that relates to geographical areas far from the forecast location, except as a discussion of the broader synoptic pattern.
-
-Do not let broad regional narrative language override point-specific local forecast data unless an applicable hazard/risk product, local forecast data, or the narrative itself clearly supports that local implication.
-
-## 4. Raw underlying data
-
-Use `briefing.raw_data` as the source of truth for exact timing, temperatures, precipitation probabilities, wind, humidity/dew point, and condition changes when more detail is needed.
-
-For the current schema, `briefing.raw_data.hourly_forecast.periods` is the most granular local forecast source. Use it to verify daypart summaries, refine timing, identify trends, and resolve ambiguity.
-
-Use `briefing.raw_data.current_conditions` only as generation-time context. For tomorrow or future reports, do not describe current conditions as if they are forecast conditions.
-
-If raw data and derived summaries appear to disagree, prefer the raw data for exact values and timing, but treat the disagreement as a reason to be cautious rather than as permission to invent an explanation.
-
-# CONFLICT RESOLUTION
-
-When sources differ, ask:
-
-1. Which source is most local to the forecast point?
-2. Which source is valid for the report period or near-term window?
-3. Which source is most authoritative for the type of claim being made?
-4. Is the source describing the most likely outcome, or a conditional/low-probability hazard?
-
-Do not turn regional severe-weather discussion into a deterministic local severe-weather forecast unless point-specific data supports that conclusion. Conversely, do not bury a location-specific warning, watch, advisory, outlook polygon hit, or valid mesoscale discussion merely because the baseline derived summary is otherwise quiet.
-
-# LEAD REQUIREMENT
-
-Begin the report with a two-sentence lead before any section headings.
-
-If an active warning is relevant during the report period, lead with the hazard. Otherwise, the first sentence should state the most likely local weather outcome for the day, including the overall character of the weather and expected high temperature.
-
-The second sentence should state the most important active hazard, caveat, uncertainty, or alternate outcome, if one exists. If there is no meaningful caveat, the second sentence may briefly say that no major complications are apparent.
-
-In the lead, distinguish the main weather outcome from the caveat. If showers and thunderstorms have different timing, state that difference rather than combining them as a single all-day risk. If the main caveat is a regional severe-weather or precipitation risk displaced from the report location, state that limitation clearly.
-
-Example style:
-
-- “Tomorrow is expected to be warm, mostly cloudy, and mostly dry, with a high near 72. There is a slight chance of isolated showers and thunderstorms from late afternoon into early evening.”
-
-Do not open with generic planning advice.
-
-# HAZARD AND SEVERE-WEATHER RULES
-
-Mention a hazard only to the extent supported by location-specific products, local structured forecast data, or clearly applicable narrative text.
-
-Preserve product strength and uncertainty. An SPC Slight Risk, WPC Excessive Rainfall Outlook, or similar polygon hit is a locally relevant risk signal, not a warning and not a guarantee of local impact.
-
-Preserve geography. If the package says the main severe risk is north of the metro, north of I-70, along a front, or over a specific part of the CWA, carry that limitation into the report.
-
-Preserve timing. Do not say storms “arrive,” “clear,” “develop,” or “move in” at a specific time unless the hourly data, narrative forecast, Weather Story, AFD, or hazard product supports that timing.
-
-# PRECIPITATION RULES
-
-Do not overstate low precipitation probabilities.
-
-Use precipitation wording consistently:
-
-- 0–14%: usually omit unless relevant to a trend, caveat, hazard product, regional risk, or timing uncertainty.
-- 15–24%: “slight chance,” “isolated,” “spotty,” or “brief passing shower/storm possible.”
-- 25–39%: “chance,” “scattered,” or “some showers/storms possible.”
-- 40–59%: “good chance” or “showers/storms likely enough to plan around.”
-- 60%+: “likely,” “wet,” or “unsettled,” if consistent with the narrative forecast.
-
-Include ## Precipitation Details only when precipitation is likely, potentially impactful, or meteorologically interesting. In that section, address as many of the following as the data supports:
-
-- likely or favored start/end timing
-- most likely precipitation window
-- expected intensity
-- expected rainfall amount
-- thunderstorm potential
-- severe-weather potential
-- uncertainty in timing, coverage, or placement
-
-If the package does not provide rainfall amounts, say nothing about totals unless a narrative product provides a supported qualitative signal. Do not invent QPF.
-
-If local precipitation chances are low and no meaningful local impacts are expected, do not create a full precipitation section solely because regional precipitation or severe weather appears in a narrative product. Mention the regional caveat in the lead or ## What to Watch instead, preserving geographic limits.
-
-# DAYPART RULES
-
-Use dayparts from briefing.derived_daypart_summaries. If a daypart is present but incomplete, use raw hourly data and narrative forecast periods to fill in only what is supported. Only include dayparts present in the package.
-
-In ## Daypart Forecast, each bullet should usually follow this pattern:
-
-- **Daypart:** [Sky/general condition] with [temperature trend or approximate temperature]. [Precipitation/storm/hazard sentence only if relevant.] [Wind sentence only if meaningful.]
-
-Always include the expected sky or general condition when supported, such as mostly cloudy, partly cloudy, sunny, overcast, rainy, snowy, foggy, or stormy.
-
-Prefer natural temperature phrasing:
-
-- “temperatures around 82”
-- “temperatures rising from the upper 60s into the low 70s”
-- “temperatures near 80”
-- “cooling from the low 80s into the low 70s”
-- “holding in the upper 60s”
-- “peaking near 83 late in the day”
-
-For quiet or mostly dry dayparts, keep the bullet to one sentence. For dayparts with meaningful precipitation, thunder, snow, ice, fog, high wind, heat, or other weather impacts, add a second sentence with timing and caveat details.
-
-Keep sky/general condition separate from precipitation probability. Do not write only “slight chance of showers” when the broader condition is “mostly cloudy with a slight chance of showers.”
-
-When precipitation or hazards are likely during only part of a daypart, describe that timing first, then describe the sky/temperature trend. Do not lead with a benign sky condition if showers, storms, snow, ice, fog, or other impacts are likely during that same daypart.
-
-Avoid “throughout the day” unless the same weather risk is meaningfully present across most dayparts.
-
-# METEOROLOGICAL CONTEXT RULES
-
-Use narrative products to explain the “why” behind the local forecast when useful.
-
-Useful context may include:
-
-- synoptic pattern
-- fronts or boundaries
-- shortwaves, troughs, or ridges
-- instability, moisture, shear, forcing, or capping
-- regional placement of precipitation or severe-weather chances
-- hazard types and timing windows
-- confidence or uncertainty
-- conditional outcomes
-- relevant notes about the following day or days
-
-Do not simply quote or summarize narrative products at length. Translate them into concise, plainspoken, weather-literate context.
-
-# OUTPUT FORMAT
-
-Use this structure:
-
-# [Today’s/Tomorrow’s/DOW's] Weather — [Location Name]
-
-[Valid date]
-
-[Two-sentence lead.]
-
-## Daypart Forecast
-
-- Morning: ...
-- Midday: ...
-- Afternoon: ...
-- Evening: ...
-- Overnight: ...
-
-Only include dayparts present in the package. Use natural language timing where helpful.
-
-## Precipitation Details
-
-Include this section only if:
-
-- local precipitation probability reaches at least 30% during the valid period;
-- thunder is mentioned in the structured local forecast and the timing/coverage is meteorologically interesting;
-- a relevant hazard/risk product discusses flooding, severe weather, winter weather, high wind, or another meaningful precipitation-related hazard;
-- narrative products discuss intensity, rainfall rates, flooding, severe potential, or meaningful uncertainty that plausibly affects the report location or is important regional context;
-- recent changes materially affect precipitation timing, coverage, or intensity.
-
-## Recent Changes
-
-Include this section only if recent_changes.items contains meaningful changes. Summarize changes in plain English. Do not fabricate changes.
-
-## What to Watch
-
-Include meteorological context, uncertainty, conditional forecast factors, and any relevant non-warning hazard/risk signals.
-
-In most cases:
-
-- Provide 2–3 sentences summarizing the relevant local/regional setup.
-- Provide 1–2 sentences describing the main forecast uncertainty or conditional factor, if present.
-- Optionally include 1–2 sentences about the next day or broader pattern if supported.
-
-# STYLE RULES
-
-- Plainspoken, precise, and weather-literate.
-- Compact, but not shallow.
-- No generic public-safety filler.
-- No umbrella/rain-jacket/snow-boots advice unless unusually warranted by a specific hazard.
-- No commute or outdoor-plan boilerplate.
-- No unsupported precision.
-- No raw YAML, raw JSON, internal field names, source hashes, endpoint names, URLs, implementation details, or debugging notes.
-- No apologies for missing data.
-- Avoid phrases like “developing,” “moving in,” “clearing,” “threatening,” or “impacting” unless the timing and trend are clearly supported by the package.
-- Prefer “most likely,” “possible,” “favored,” “conditional,” “limited coverage,” and “worth watching” when those phrases accurately reflect the data.

docs/roadmap/scriptorium/prompts/daily_report/daily_report.yml

@@ -1,24 +0,0 @@
-id: weather.daily_report
-version: "1.0.0"
-#default_profile: local-heavy
-default_profile: gemini-3-flash-lite
-description: Daily weather report prompt.
-inputs:
-  - name: data_package
-    required: true
-    content_type: application/json
-    description: Structured weather data package
-messages:
-  - role: system
-    content_file: ./daily_report.system.md
-  - role: user
-    content_file: ./daily_report.user.md
-  - role: user
-    content: |
-      <<<CURRENT_SESSION_TRANSCRIPT
-      {{input "data_package"}}
-      CURRENT_SESSION_TRANSCRIPT>>>
-output:
-  format: markdown
-  validation_mode: basic
-  repair_attempts: 0

docs/roadmap/scriptorium/prompts/hourly/hourly_generated_text.user.md

@@ -1,55 +0,0 @@
-TASK: You are writing structured prose slots for a short-term hourly weather report.
-
-The calling application will render the final Markdown report. Your job is not to write the full report. Return only a JSON object matching the configured schema.
-
-Use only the supplied `data_package`. Do not invent weather details, times, hazards, probabilities, or impacts that are not supported by the data.
-
-The report focuses on the valid period in `report.valid_period`, typically the next several hours for the configured location.
-
-Return these fields:
-
-- `summary`: required. 1-2 sentences summarizing the main weather story for the valid period.
-- `forecast_discussion`: required. 2-3 sentences explaining the broader setup, trend, or forecast reasoning most relevant to the valid period.
-- `precipitation_timing`: optional. Include only when the deterministic `precip_timing` module contains precipitation windows. 
-
-Return JSON only.
-
-# summary
-
-The summary should typically consist of two sentences.
-
-If an active warning is relevant during the report period, lead with the hazard. Otherwise, the first sentence should state the most likely local weather outcome for the valid period, including the overall character of the weather and expected temperature/temperature range. 
-
-If the forecast indicates a significant shift in conditions over time (e.g., from sunny to overcast), then identify the hour when the shift is most likely to occur. If the conditions are generally similar or stable across the forecast period, then pick a single descriptor (e.g., mostly clear) that best captures the character of the weather.
-
-The second sentence should state the most important active hazard, caveat, uncertainty, or alternate outcome, if one exists. If there is no meaningful caveat, the second sentence may be omitted, or may briefly say that no major complications are apparent.
-
-In the lead, distinguish the main weather outcome from the caveat. If showers and thunderstorms have different timing, state that difference rather than combining them as a single risk throughout the valid period. If the main caveat is a regional severe-weather or precipitation risk displaced from the report location, state that limitation clearly.
-
-Example style:
-
-- “The rest of the afternoon is expected to be warm and dry, with mostly clear skies. There is a slight chance of isolated showers and thunderstorms developing from late afternoon into early evening.”
-
-# forecast_discussion
-
-Use narrative products to explain the “why” behind the local forecast when useful.
-
-Useful context may include:
-
-- synoptic pattern
-- fronts or boundaries
-- shortwaves, troughs, or ridges
-- instability, moisture, shear, forcing, or capping
-- regional placement of precipitation or severe-weather chances
-- hazard types and timing windows
-- confidence or uncertainty
-- conditional outcomes
-- relevant notes about the following day or days
-
-# precipitation_timing
-
-Optional. Return only if precipitation is forecast. If present, provide 1 to 4 sentences to add practical context, including:
-
-  - Whether the precipitation is associated with a moving frontal boundary, convective initiation, or wide stratiform rain (if this can be determined from the data package);
-  - The expected type, intensity, and duration of the precipitation; and
-  - Any caveats or uncertainty with respect to the onset, duration, or occurrance of the precipitation.

docs/roadmap/scriptorium/prompts/today/today_generated_text.user.md

@@ -1,57 +0,0 @@
-TASK: You are writing structured prose slots for a daily weather report.
-
-The calling application will render the final Markdown report. Your job is not to write the full report. Return only a JSON object matching the configured schema.
-
-Use only the supplied `data_package`. Do not invent weather details, times, hazards, probabilities, or impacts that are not supported by the data.
-
-The report focuses on the valid period in `report.valid_period`, which corresponds to the current civil day (today) for the configured location.
-
-Return these fields:
-
-- `summary`: required. 1-2 sentences summarizing the main weather story for the valid period.
-- `forecast_discussion`: required. 3 paragraphs explaining the broader setup, trend, and/or forecast reasoning most relevant to the valid period.
-- `precipitation_timing`: optional. Include only when the deterministic `precip_timing` module contains precipitation windows. 
-
-Return JSON only.
-
-# summary
-
-The summary should typically consist of two sentences.
-
-If an active warning is relevant during the report period, lead with the hazard. Otherwise, the first sentence should state the most likely local weather outcome for the valid period, including the overall character of the weather and expected temperature/temperature range. 
-
-The second sentence should state the most important active hazard, caveat, uncertainty, or alternate outcome, if one exists. If there is no meaningful caveat, the second sentence may be omitted.
-
-In the lead, distinguish the main weather outcome from the caveat. If showers and thunderstorms have different timing, state that difference rather than combining them as a single risk throughout the valid period. If the main caveat is a regional severe-weather or precipitation risk displaced from the report location, state that limitation clearly.
-
-Example style:
-
-- “Today is expected to be warm and dry, with mostly clear skies. There is a slight chance of isolated showers and thunderstorms developing from late afternoon into early evening.”
-
-# forecast_discussion
-
-Use narrative products to explain the “why” behind the local forecast when useful. Useful context may include:
-
-- synoptic pattern
-- fronts or boundaries
-- shortwaves, troughs, or ridges
-- instability, moisture, shear, forcing, or capping
-- regional placement of precipitation or severe-weather chances
-- hazard types and timing windows
-- confidence or uncertainty
-- conditional outcomes
-- relevant notes about the following day or days
-
-In most cases, the `forecast_discussion` should include three paragraphs:
-
-1. 2–4 sentences summarizing the relevant local/regional setup.
-2. 2-4 sentences describing the main forecast uncertainty or conditional factor, if present.
-3. 2-4 sentences about the next day or broader pattern if supported.
-
-# precipitation_timing
-
-Optional. Return only if precipitation is forecast. If present, provide 1 to 4 sentences to add practical context, including:
-
-  - Whether the precipitation is associated with a moving frontal boundary, convective initiation, or wide stratiform rain (if this can be determined from the data package);
-  - The expected type, intensity, and duration of the precipitation; and
-  - Any caveats or uncertainty with respect to the onset, duration, or occurrance of the precipitation.

docs/roadmap/scriptorium/prompts/tomorrow/tomorrow_generated_text.user.md

@@ -1,58 +0,0 @@
-TASK: You are writing structured prose slots for a daily weather report.
-
-The calling application will render the final Markdown report. Your job is not to write the full report. Return only a JSON object matching the configured schema.
-
-Use only the supplied `data_package`. Do not invent weather details, times, hazards, probabilities, or impacts that are not supported by the data.
-
-The report focuses on the valid period in `report.valid_period`, which corresponds to the next civil day (tomorrow) for the configured location.
-
-Return these fields:
-
-- `summary`: required. 1-2 sentences summarizing the main weather story for the valid period.
-- `forecast_discussion`: required. 3 paragraphs explaining the broader setup, trend, and/or forecast reasoning most relevant to the valid period.
-- `precipitation_timing`: optional. Include only when the deterministic `precip_timing` module contains precipitation windows. 
-- `confidence`: optional. Include only if uncertainty, timing spread, or conflicting signals materially affect how the reader should interpret the forecast.
-
-Return JSON only.
-
-# summary
-
-The summary should typically consist of two sentences.
-
-If an active warning is relevant during the report period, lead with the hazard. Otherwise, the first sentence should state the most likely local weather outcome for the valid period, including the overall character of the weather and expected temperature/temperature range. 
-
-The second sentence should state the most important active hazard, caveat, uncertainty, or alternate outcome, if one exists. If there is no meaningful caveat, the second sentence may be omitted.
-
-In the lead, distinguish the main weather outcome from the caveat. If showers and thunderstorms have different timing, state that difference rather than combining them as a single risk throughout the valid period. If the main caveat is a regional severe-weather or precipitation risk displaced from the report location, state that limitation clearly.
-
-Example style:
-
-- “Sunday is expected to be warm and dry, with mostly clear skies. There is a slight chance of isolated showers and thunderstorms developing from late afternoon into early evening.”
-
-# forecast_discussion
-
-Use narrative products to explain the “why” behind the local forecast when useful. Useful context may include:
-
-- synoptic pattern
-- fronts or boundaries
-- shortwaves, troughs, or ridges
-- instability, moisture, shear, forcing, or capping
-- regional placement of precipitation or severe-weather chances
-- hazard types and timing windows
-- confidence or uncertainty
-- conditional outcomes
-- relevant notes about the following day or days
-
-In most cases, the `forecast_discussion` should include three paragraphs:
-
-1. 2–4 sentences summarizing the relevant local/regional setup.
-2. 2-4 sentences describing the main forecast uncertainty or conditional factor, if present.
-3. 2-4 sentences about the next day or broader pattern if supported.
-
-# precipitation_timing
-
-Use 1-2 sentences to add practical context, including:
-
-  - Whether the precipitation is associated with a moving frontal boundary, convective initiation, or wide stratiform rain (if this can be determined from the data package);
-  - The expected type, intensity, and duration of the precipitation; and
-  - Any caveats or uncertainty with respect to the onset, duration, or occurrance of the precipitation.

docs/roadmap/scriptorium/schemas/daily/daily.generated_text.schema.json

@@ -1,26 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "weatherreporter.today.generated_text.schema.json",
-  "title": "Today GeneratedText",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "summary",
-    "forecast_discussion"
-  ],
-  "properties": {
-    "summary": {
-      "type": "string"
-    },
-    "forecast_discussion": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "minItems": 1
-    },
-    "precipitation_timing": {
-      "type": "string"
-    }
-  }
-}

docs/roadmap/scriptorium/schemas/hourly/hourly.generated_text.schema.json

@@ -1,22 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "weatherreporter.hourly.generated_text.schema.json",
-  "title": "Hourly GeneratedText",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "summary",
-    "forecast_discussion"
-  ],
-  "properties": {
-    "summary": {
-      "type": "string"
-    },
-    "forecast_discussion": {
-      "type": "string"
-    },
-    "precipitation_timing": {
-      "type": "string"
-    }
-  }
-}

docs/roadmap/scriptorium/schemas/today/today.generated_text.schema.json

@@ -1,26 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "weatherreporter.today.generated_text.schema.json",
-  "title": "Today GeneratedText",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "summary",
-    "forecast_discussion"
-  ],
-  "properties": {
-    "summary": {
-      "type": "string"
-    },
-    "forecast_discussion": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "minItems": 1
-    },
-    "precipitation_timing": {
-      "type": "string"
-    }
-  }
-}

docs/roadmap/scriptorium/schemas/tomorrow/tomorrow.generated_text.schema.json

@@ -1,26 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "weatherreporter.tomorrow.generated_text.schema.json",
-  "title": "Tomorrow GeneratedText",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "summary",
-    "forecast_discussion"
-  ],
-  "properties": {
-    "summary": {
-      "type": "string"
-    },
-    "forecast_discussion": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "minItems": 1
-    },
-    "precipitation_timing": {
-      "type": "string"
-    }
-  }
-}

docs/templates.md

@@ -14,14 +14,15 @@ source:
 
 | Report | Template | Schema | Prompt ID and source |
 | --- | --- | --- | --- |
-| Daily | `templates/daily.md.tmpl` (`daily`) | `daily` | `weather.daily_generated_text`; `prompts/daily.generated_text.md` |
+| Daily | `templates/daily.md.tmpl` (`daily`) | `daily` | `weather.daily_generated_text`; `internal/promptassets/assets/prompts/daily/` |
-| Today | `templates/today.md.tmpl` (`today`) | `today` | `weather.today_generated_text`; `prompts/today.generated_text.md` |
+| Today | `templates/today.md.tmpl` (`today`) | `today` | `weather.today_generated_text`; `internal/promptassets/assets/prompts/today/` |
-| Tomorrow | `templates/tomorrow.md.tmpl` (`tomorrow`) | `tomorrow` | `weather.tomorrow_generated_text`; `prompts/tomorrow.generated_text.md` |
+| Tomorrow | `templates/tomorrow.md.tmpl` (`tomorrow`) | `tomorrow` | `weather.tomorrow_generated_text`; `internal/promptassets/assets/prompts/tomorrow/` |
-| Hourly | `templates/hourly.md.tmpl` (`hourly`) | `hourly` | `weather.hourly_generated_text`; `prompts/hourly.generated_text.md` |
+| Hourly | `templates/hourly.md.tmpl` (`hourly`) | `hourly` | `weather.hourly_generated_text`; `internal/promptassets/assets/prompts/hourly/` |
 
-The matching schema files are under `internal/reporttemplate/schemas/`. The
+The matching schemas and Promptkit definitions are embedded by
-generated-text catalog pairs each schema ID with its template ID; keep the
+`internal/promptassets`. The generated-text catalog requires each report's
-matching report prompt source aligned with that pair.
+exact schema/template pair; keep the matching prompt definition aligned with
+that report-specific triple.
 
 Shared partials are under `internal/reporttemplate/templates/partials/`:
 
@@ -46,11 +47,18 @@ from rendering.
   calculations, source selection, or prompt-input shaping to a template.
 - Keep generated prose in `.GeneratedText`; do not restate deterministic facts
   in generated prose merely to compensate for a template change.
+- Render every `.GeneratedText` value through `plainText`. It preserves prose
+  and paragraph breaks while escaping Markdown and HTML syntax, removing code
+  indentation, and replacing control characters. Never interpolate generated
+  prose directly: repository templates alone own headings, lists, links, and
+  other Markdown structure.
 - When changing the generated-prose contract, update the matching prompt,
   schema, validator, render context, and template together. The validation and
   catalog rules are owned by [Generated Text internals](internal/generatedtext.md).
 - Use `.Modules.Dayparts` for ordered daypart output. Do not range over
-  `.Modules.DerivedDaypartSummaries`, which is a map.
+  `.Modules.DerivedDaypartSummaries`, which is a map. The Today partial uses
+  `.Modules.HasDaypartDetails` to ensure its heading has either rows or the
+  explicit no-details fallback.
 
 Minimal optional-value pattern:
 
@@ -66,7 +74,7 @@ Minimal list pattern:
 
 ```gotemplate
 {{ range .GeneratedText.ForecastDiscussion }}
-{{ . }}
+{{ plainText . }}
 {{ end }}
 ```
 
@@ -79,6 +87,7 @@ Templates have these helpers in addition to Go template built-ins:
 | `hasRelevantAlerts` | an alert-digest value or pointer | its `Relevant` slice is nonempty |
 | `hasEnhancedOrHigherSPCRisk` | an SPC outlook value or pointer | its `RiskDigest` contains an Enhanced, Moderate, or High Risk entry |
 | `isEnhancedOrHigherSPCRisk` | one SPC risk-digest entry | its `LabelText`, or fallback `RiskLabel`, is Enhanced, Moderate, or High Risk |
+| `plainText` | a generated prose string | a readable plain-text rendering that preserves paragraph breaks without allowing dynamic Markdown or HTML structure |
 
 For example, the alert partial uses the first two functions to decide whether
 to render the section:
@@ -91,20 +100,14 @@ to render the section:
 
 ## Render Context
 
-Every rendered template receives one typed context with these five top-level
+Every rendered template receives one typed context with these three top-level
 fields:
 
 | Field | Purpose |
 | --- | --- |
 | `.Report` | Display labels and canonical report timing metadata. |
-| `.GeneratedText` | Validated prose supplied by Scriptorium. |
+| `.GeneratedText` | Validated prose supplied by Promptkit. |
 | `.Modules` | Deterministic, typed values prepared for Markdown rendering. |
-| `.Collected` | Normalized upstream facts for advanced use. |
-| `.Derived` | Shared calculated facts for advanced use. |
-
-`.Collected` and `.Derived` are available for an exceptional display need, but
-they are lower-level contracts. Keep reusable weather derivation in Go and use
-the module surface for normal template work.
 
 ### Report Metadata
 
@@ -121,19 +124,20 @@ of formatting timestamps in a template.
 
 ### Validated GeneratedText Prose
 
-GeneratedText is prose returned by Scriptorium and validated before rendering.
+GeneratedText is prose returned by Promptkit and validated before rendering.
 It is not a source for deterministic weather facts.
 
 | Field | Hourly type | Daily, Today, and Tomorrow type | Notes |
 | --- | --- | --- | --- |
-| `.GeneratedText.Summary` | `string` | `string` | Required. |
+| `.GeneratedText.Summary` | `string` | `string` | Required; at most 4,000 characters. |
-| `.GeneratedText.ForecastDiscussion` | `string` | `[]string` | Required; range over the day-style paragraph slice. |
+| `.GeneratedText.ForecastDiscussion` | `string` | `[]string` | Required; Hourly permits 12,000 characters. Day-style values permit up to 12 paragraphs of 4,000 characters each. |
-| `.GeneratedText.PrecipitationTiming` | `string` | `string` | Optional prose used by the precipitation partial when deterministic windows exist. |
+| `.GeneratedText.PrecipitationTiming` | `string` | `string` | Required field, at most 4,000 characters; an empty string represents no supported prose. The precipitation partial uses nonempty prose only when deterministic windows exist. |
-| `.GeneratedText.Confidence` | `string` | `string` | Optional validated prose; the current templates do not render it. |
 
 The JSON schema rejects unknown properties and defines the required fields, but
 the schema body and validation behavior are documented in [Generated Text
-internals](internal/generatedtext.md).
+internals](internal/generatedtext.md). All validated generated prose together
+is limited to 20,000 characters, so template edits can rely on a bounded prose
+surface.
 
 ### Deterministic Module Values
 
@@ -142,8 +146,9 @@ Module pointers can be nil when their source or policy permits omission.
 
 | Module field | Available in |
 | --- | --- |
-| `.Modules.Metadata`, `.Modules.CurrentConditions`, `.Modules.HourlyForecast`, `.Modules.PrecipTiming`, `.Modules.AlertDigest`, `.Modules.SPCConvectiveOutlooks`, `.Modules.AreaForecastDiscussion`, `.Modules.SPCConvectiveDiscussion`, `.Modules.WeatherStory` | All four contexts |
+| `.Modules.CurrentConditions`, `.Modules.HourlyForecast`, `.Modules.PrecipTiming`, `.Modules.AlertDigest`, `.Modules.SPCConvectiveOutlooks`, `.Modules.AreaForecastDiscussion`, `.Modules.SPCConvectiveDiscussion`, `.Modules.WeatherStory` | All four contexts |
 | `.Modules.DerivedDailySummary`, `.Modules.DerivedDaypartSummaries`, `.Modules.Dayparts` | Daily, Today, Tomorrow |
+| `.Modules.HasDaypartDetails` | Today |
 | `.Modules.OutdoorWindows`, `.Modules.DailyPlanning` | Daily |
 | `.Modules.TodayPlanning` | Today |
 | `.Modules.TomorrowPlanning` | Tomorrow |

docs/troubleshooting.md

@@ -1,271 +0,0 @@
-# Troubleshooting
-
-Use the error from the command together with the run artifacts when a run ID is
-available. Start with [`inspect metadata`](cli.md#inspection-commands) to identify the
-report and artifact paths, then use the narrower inspection command named
-below. Do not remove a workspace to diagnose a failure: it contains the
-evidence needed to correct it safely.
-
-## A command or configuration is rejected before work starts
-
-Symptom: The command exits before it creates a run, with an unknown-flag,
-missing-argument, invalid date or time bound, invalid timezone, or
-`weather_api.base_url` message.
-
-Likely cause: The command does not accept that option for the requested report,
-or required command and configuration values are absent or malformed.
-
-Diagnostic: Compare the command with [`generate` and `run`](cli.md#commands-and-usage)
-and review the configured value named in the error. `generate daily` requires
-`--date`; `generate storm` requires both `--start` and `--end`.
-
-Safe fix: Correct only the reported option or configuration value. Use an
-absolute Weather API URL and a valid IANA timezone; do not change unrelated
-workspace data.
-
-See also: [Configuration](config.md) and [Weather API integration](integrations/weatherapi.md).
-
-## Weather data cannot be collected
-
-Symptom: A generation command fails while fetching weather data, or reports
-`hourly forecast data is missing` or `contains no periods`.
-
-Likely cause: The Weather API is unavailable, its configured endpoint or
-credentials are unsuitable, or the response lacks the hourly forecast required
-by the selected report.
-
-Diagnostic: Check the service status and the configured base URL, then retry
-the same report. If a run ID was produced, run `weatherreporter inspect sources
-RUN_ID` to see the recorded source result.
-
-Safe fix: Restore access to the configured Weather API or choose a reporting
-period supported by the returned forecast. Do not invent missing hourly values
-in local artifacts.
-
-See also: [Configuration](config.md) and [Weather API integration](integrations/weatherapi.md).
-
-## Optional source warnings appear
-
-Symptom: The report succeeds but its output says that a source supplied a
-warning or degraded result.
-
-Likely cause: An optional source did not return usable data; mandatory weather
-collection still completed.
-
-Diagnostic: Run `weatherreporter inspect sources RUN_ID` and identify the
-source and warning recorded for that run.
-
-Safe fix: Correct the affected source configuration or service issue, then
-generate a new report if the missing optional information is needed. Keep the
-existing run for comparison.
-
-See also: [Inspecting a run](cli.md#inspection-commands) and [Operations](operations.md).
-
-## Scriptorium cannot be prepared
-
-Symptom: The report fails with a fragment such as `run scriptorium render`, or
-the Scriptorium executable cannot be started.
-
-Likely cause: The configured executable, profile, prompt, or its local runtime
-environment is unavailable to Weatherreporter.
-
-Diagnostic: Confirm that the configured executable can be run by the same user
-and inspect `weatherreporter inspect metadata RUN_ID` when a run ID is shown.
-
-Safe fix: Repair the executable path or the Scriptorium configuration and retry
-the report. Do not edit generated artifacts to bypass preparation.
-
-See also: [Configuration](config.md) and [Operations](operations.md).
-
-## Scriptorium preflight fails
-
-Symptom: A Scriptorium-backed report stops before text generation, often with
-a `scriptorium render exited with code` fragment.
-
-Likely cause: Scriptorium rejected the render request, prompt, profile, or data
-package before it could run the report.
-
-Diagnostic: Inspect the run metadata and the saved preflight artifact path it
-references. Compare the reported Scriptorium diagnostic with its configuration.
-
-Safe fix: Correct the reported Scriptorium input or configuration, then create
-a new run. Preserve the failed preflight artifact for support or comparison.
-
-See also: [Inspecting a run](cli.md#inspection-commands) and [Operations](operations.md).
-
-## Scriptorium report execution fails
-
-Symptom: Preparation succeeded, but generation stops with a
-`scriptorium run exited with code` fragment.
-
-Likely cause: The Scriptorium run failed after preflight, for example because
-its prompt execution or runtime dependency failed.
-
-Diagnostic: Inspect the run metadata and preflight artifact, then review the
-exit diagnostic from the command. This distinguishes a run failure from a
-preflight failure.
-
-Safe fix: Correct the Scriptorium issue identified by that diagnostic and run
-the report again; leave the failed run artifacts in place.
-
-See also: [Operations](operations.md).
-
-## Generated text fails validation
-
-Symptom: A generated-text report fails after Scriptorium returns text, with a
-message about generated text or required report content.
-
-Likely cause: Returned text does not meet the report's validation rules.
-
-Diagnostic: Use `weatherreporter inspect metadata RUN_ID` to find the saved raw
-generated-text artifact, and inspect it alongside the reported validation
-message.
-
-Safe fix: Correct the upstream prompt or generation configuration that caused
-the invalid output, then create a new run. Do not hand-edit saved raw text and
-present it as a validated report.
-
-See also: [Operations](operations.md).
-
-## Report template rendering fails
-
-Symptom: Scriptorium output is available, but the report fails while building
-the final Markdown document.
-
-Likely cause: The selected report template or the render context is
-incompatible with the generated or collected data.
-
-Diagnostic: Inspect the metadata, generated-text result, and render-context
-artifacts for the run. Note the template or missing-field fragment in the
-error rather than relying on a complete error string.
-
-Safe fix: Correct the template or its supported inputs in source control, test
-the change, and create a new report. Do not alter the saved context merely to
-make one historical run render.
-
-See also: [Operations](operations.md).
-
-## A report fails after artifacts are saved
-
-Symptom: A generation command reports an error after showing a run ID, such as
-an error writing the managed report, copying `--out`, saving metadata, or
-notifying Distributor.
-
-Likely cause: A local filesystem permission or path problem, an unavailable
-destination for `--out`, or a later report-delivery failure occurred after
-earlier steps succeeded.
-
-Diagnostic: Run `weatherreporter inspect metadata RUN_ID` and check the exact
-path and operation named in the error. For an `--out` failure, verify only the
-specified destination directory and filename.
-
-Safe fix: Repair access to that exact path or disable the optional delivery
-step only when appropriate, then generate a new report. Keep the existing
-managed artifacts untouched.
-
-See also: [Operations](operations.md) and [Distributor integration](integrations/distributor/pkg-upload.md).
-
-## A batch has partial report failures
-
-Symptom: `run morning` or `run evening` returns nonzero and reports both
-succeeded and failed report items.
-
-Likely cause: A report-level collection, generation, rendering, or local
-output failure affected one or more planned reports; the remaining reports
-continue independently.
-
-Diagnostic: Read the per-report status lines, then inspect the run ID for each
-failed item with `weatherreporter inspect metadata RUN_ID`.
-
-Safe fix: Correct the specific failure and rerun the batch or affected report.
-Do not delete successful reports simply because another item failed.
-
-See also: [Batch commands](cli.md#commands-and-usage) and [Operations](operations.md).
-
-## A batch upload is skipped
-
-Symptom: The batch result says Distributor notification was skipped because
-one or more reports failed.
-
-Likely cause: Batch notification intentionally runs only after every planned
-report succeeds.
-
-Diagnostic: Review the failed report items and their metadata; a skipped batch
-notification is expected while any item is failed.
-
-Safe fix: Resolve the report failures and rerun the batch. Do not upload a
-partial bundle by manually reusing batch artifacts.
-
-See also: [Batch commands](cli.md#commands-and-usage) and [Operations](operations.md).
-
-## Distributor notification fails
-
-Symptom: A completed report or otherwise successful batch reports a Distributor
-error, including a rejected upload, source or idempotency conflict, or service
-unavailability.
-
-Likely cause: Distributor rejected the request identity or bundle, required
-credentials are unavailable, or the remote service cannot be reached.
-
-Diagnostic: Inspect the report metadata or batch result for the notification
-artifact and the error fragment. Verify the configured Distributor endpoint and
-request identity without exposing credentials.
-
-Safe fix: Resolve the reported remote conflict, configuration, or availability
-issue and create a new report or rerun the batch. Do not modify recorded bundle
-or idempotency artifacts to force an upload.
-
-See also: [Configuration](config.md), [Distributor integration](integrations/distributor/pkg-upload.md), and [Operations](operations.md).
-
-## Secrets cannot be loaded
-
-Symptom: Startup reports `read secrets directory`, `secret file`, or a token
-environment-variable error before the affected service can be used.
-
-Likely cause: The configured secrets directory cannot be read, contains a
-non-regular file, or does not supply the environment variable required by an
-enabled integration.
-
-Diagnostic: Check the configured secrets directory path, ownership, and that
-each intended secret is a regular file. Confirm the variable name from
-configuration only; never print or paste its value.
-
-Safe fix: Correct permissions, file type, or the missing secret file, then
-retry. Keep secret values out of commands, logs, tickets, and artifacts.
-
-See also: [Configuration](config.md) and [Operations](operations.md).
-
-## A run ID or saved state cannot be found
-
-Symptom: An inspection command reports that metadata for a run ID was not
-found, or a report cannot use a prior snapshot.
-
-Likely cause: The run ID is wrong, the configured workspace is different from
-the one that created the run, or no compatible prior snapshot exists.
-
-Diagnostic: Use `weatherreporter inspect reports` to list available reports in
-the current workspace, then copy the run ID from that output. Confirm the
-workspace configuration before retrying a prior-snapshot operation.
-
-Safe fix: Use an existing run ID and its original workspace, or generate a new
-compatible report when no prior snapshot is available. Do not fabricate state
-files or run IDs.
-
-See also: [Inspecting a run](cli.md#inspection-commands) and [Operations](operations.md).
-
-## Workspace paths cannot be read or written
-
-Symptom: Startup or report persistence reports a workspace-path, permission,
-or "must be relative to workspace root" error.
-
-Likely cause: A configured artifact directory escapes the workspace, or the
-current user lacks access to the specific workspace location.
-
-Diagnostic: Check the named configuration path against the configured workspace
-root and inspect ownership and permissions of that exact directory.
-
-Safe fix: Set the path to a location within the workspace or repair access to
-the named directory, then rerun. Do not remove the workspace or broadly relax
-permissions.
-
-See also: [Configuration](config.md) and [Operations](operations.md).

examples/config.yml

@@ -14,6 +14,9 @@ location:
 secrets:
   directory: ""
 
+output:
+  directory: /var/lib/weatherreporter/reports
+
 notify:
   distributor:
     enabled: false
@@ -35,17 +38,10 @@ missing_source:
   sources:
     alerts: none
 
-scriptorium:
+promptkit:
-  binary: scriptorium
   timeout: 2m
-
+  local:
-workspace:
+    concurrency_limit: 1
-  root: workspace
-  snapshots_dir: snapshots
-  reports_dir: reports
-  data_packages_dir: data-packages
-  preflight_dir: preflight
-  notifications_dir: notifications
 
 dayparts:
   - name: overnight
@@ -64,12 +60,6 @@ dayparts:
     start: "17:00"
     end: "24:00"
 
-recent_change:
-  temperature_degrees: 5
-  precip_probability_points: 20
-  wind_gust_miles_per_hour: 10
-  precip_timing_shift_minutes: 120
-
 reports:
   daily:
     distributor:

examples/weather-light-local-profile.yml

@@ -0,0 +1,4 @@
+id: weather-light
+endpoint: http://127.0.0.1:11434/v1
+model: weather-local
+timeout_seconds: 180

go.mod

@@ -4,4 +4,11 @@ go 1.26
 
 require gopkg.in/yaml.v3 v3.0.1
 
-require gitea.maximumdirect.net/eric/distributor v0.5.0
+require (
+	gitea.maximumdirect.net/eric/distributor v0.5.0
+	gitea.maximumdirect.net/eric/promptkit v0.8.0
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
+	golang.org/x/sys v0.45.0
+)
+
+require golang.org/x/text v0.14.0 // indirect

go.sum

@@ -1,5 +1,7 @@
 gitea.maximumdirect.net/eric/distributor v0.5.0 h1:+al7Bw+kMv6V35a3Sm5rUtCTQhwOn5b9x3RsclPMKJk=
 gitea.maximumdirect.net/eric/distributor v0.5.0/go.mod h1:G03FCFZPHpsUKC6SeMgTdbfNRpPQBdyTtDUj04e1Tu8=
+gitea.maximumdirect.net/eric/promptkit v0.8.0 h1:NGd9hDLu0UMxKbvittMrqM5Ua94eFb+kOE7UIir8l08=
+gitea.maximumdirect.net/eric/promptkit v0.8.0/go.mod h1:R95NM6fbMDGDC0/UomgnSBP6ui2ns+8SZb8bESNvrDQ=
 github.com/aws/aws-sdk-go-v2 v1.41.9 h1:/rYeyO2+HrMztAmxAq9++XJtFMqSIpSsNA0yDGALYq4=
 github.com/aws/aws-sdk-go-v2 v1.41.9/go.mod h1:+HsoOEX80qAVUitj1A2DhCNTjmb3edVyuDypb6LNEeo=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.11 h1:h5+3VT69KUBK24grGuuA5saDJTj2IIjLb9au668Fo5I=
@@ -36,16 +38,22 @@ github.com/aws/aws-sdk-go-v2/service/sts v1.42.3 h1:ErklX/7uhSbkAAeyQD/Y1OoQ9hO3
 github.com/aws/aws-sdk-go-v2/service/sts v1.42.3/go.mod h1:ULe4HCzfKPiR6R3HEurE3b1upEkuk8AkMrOKtaOxKO8=
 github.com/aws/smithy-go v1.26.0 h1:9ouqbi+NyKP7fV3Te7UElCwdAb6Y8uk7LGwPE5tVe/s=
 github.com/aws/smithy-go v1.26.0/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
+github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/kr/fs v0.1.0 h1:Jskdu9ieNAYnjxsi0LbQp1ulIKZV1LAFgK1tWhpZgl8=
 github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
 github.com/pkg/sftp v1.13.10 h1:+5FbKNTe5Z9aspU88DPIKJ9z2KZoaGCu6Sr6kKR/5mU=
 github.com/pkg/sftp v1.13.10/go.mod h1:bJ1a7uDhrX/4OII+agvy28lzRvQrmIQuaHrcI1HbeGA=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/yuin/goldmark v1.8.2 h1:kEGpgqJXdgbkhcOgBxkC0X0PmoPG1ZyoZ117rDVp4zE=
 github.com/yuin/goldmark v1.8.2/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
 golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
 golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
 golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
+golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

internal/adapters/distributor/client.go

@@ -2,10 +2,12 @@
 package distributor
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"net/http"
 	"os"
 	"strings"
@@ -22,6 +24,7 @@ type Client struct {
 	TokenEnv        string
 	Timeout         time.Duration
 	newUploadClient uploadClientFactory
+	pollWait        func(context.Context, time.Duration) error
 }
 
 type UploadRequest struct {
@@ -107,6 +110,10 @@ type runStatus struct {
 
 const statusPollInterval = 250 * time.Millisecond
 
+const maxDistributorResponseBytes int64 = 1 << 20
+
+var errDistributorResponseTooLarge = fmt.Errorf("distributor response exceeds the %d-byte limit", maxDistributorResponseBytes)
+
 func New(cfg config.DistributorNotifyConfig) *Client {
 	return newClient(cfg, newDistributorUploadClient)
 }
@@ -120,6 +127,7 @@ func newClient(cfg config.DistributorNotifyConfig, factory uploadClientFactory)
 		TokenEnv:        cfg.TokenEnv,
 		Timeout:         cfg.Timeout,
 		newUploadClient: factory,
+		pollWait:        waitForPoll,
 	}
 }
 
@@ -201,7 +209,12 @@ func (c *Client) Upload(ctx context.Context, req UploadRequest) (UploadResult, e
 		Status:       result.Status,
 		UploadStatus: result.Status,
 	}
-	status, statusErr := waitForRunStatus(runCtx, uploadClient, result.RunID, c.Timeout > 0)
+	pollWait := c.pollWait
+	if pollWait == nil {
+		pollWait = waitForPoll
+	}
+	status, statusErr := waitForRunStatus(runCtx, uploadClient, result.RunID, c.Timeout > 0, pollWait)
+	status = sanitizeRunStatus(status)
 	if status.RunID != "" || status.Status != "" {
 		uploadResult.RunStatus = &RunStatus{
 			RunID:      status.RunID,
@@ -218,7 +231,7 @@ func (c *Client) Upload(ctx context.Context, req UploadRequest) (UploadResult, e
 		}
 	}
 	if statusErr != nil {
-		uploadResult.StatusError = redactTokenString(statusErr.Error(), token)
+		uploadResult.StatusError = safeDistributorDiagnostic(statusErr, token).Error()
 		return uploadResult, nil
 	}
 	if status.Status == "failed" {
@@ -227,19 +240,15 @@ func (c *Client) Upload(ctx context.Context, req UploadRequest) (UploadResult, e
 	return uploadResult, nil
 }
 
-func waitForRunStatus(ctx context.Context, client uploadClient, runID string, poll bool) (runStatus, error) {
+func waitForRunStatus(ctx context.Context, client uploadClient, runID string, poll bool, wait func(context.Context, time.Duration) error) (runStatus, error) {
 	status, err := client.Status(ctx, runID)
 	if err != nil || terminalRunStatus(status.Status) || !poll {
 		return status, err
 	}
 
 	for {
-		timer := time.NewTimer(statusPollInterval)
+		if err := wait(ctx, statusPollInterval); err != nil {
-		select {
+			return status, fmt.Errorf("distributor run %q did not reach terminal status before timeout: %w", runID, err)
-		case <-ctx.Done():
-			timer.Stop()
-			return status, fmt.Errorf("distributor run %q did not reach terminal status before timeout: %w", runID, ctx.Err())
-		case <-timer.C:
 		}
 
 		next, err := client.Status(ctx, runID)
@@ -253,6 +262,17 @@ func waitForRunStatus(ctx context.Context, client uploadClient, runID string, po
 	}
 }
 
+func waitForPoll(ctx context.Context, interval time.Duration) error {
+	timer := time.NewTimer(interval)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
 func terminalRunStatus(status string) bool {
 	return status == "succeeded" || status == "failed"
 }
@@ -261,10 +281,52 @@ type distributorUploadClient struct {
 	client *distributorupload.Client
 }
 
+type boundedResponseTransport struct {
+	base  http.RoundTripper
+	limit int64
+}
+
+func (t boundedResponseTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	base := t.base
+	if base == nil {
+		base = http.DefaultTransport
+	}
+	response, err := base.RoundTrip(req)
+	if err != nil {
+		return nil, err
+	}
+	defer response.Body.Close()
+
+	data, err := io.ReadAll(io.LimitReader(response.Body, t.limit+1))
+	if err != nil {
+		return nil, err
+	}
+	if int64(len(data)) > t.limit {
+		return nil, errDistributorResponseTooLarge
+	}
+	response.Body = io.NopCloser(bytes.NewReader(data))
+	response.ContentLength = int64(len(data))
+	return response, nil
+}
+
+type RemoteResponseError struct {
+	StatusCode int
+	Retryable  bool
+}
+
+func (e *RemoteResponseError) Error() string {
+	if e == nil || e.StatusCode == 0 {
+		return "distributor request failed"
+	}
+	return fmt.Sprintf("distributor request failed with HTTP status %d", e.StatusCode)
+}
+
 func newDistributorUploadClient(endpoint, token string, timeout time.Duration) (uploadClient, error) {
-	httpClient := (*http.Client)(nil)
+	httpClient := &http.Client{
+		Transport: boundedResponseTransport{base: http.DefaultTransport, limit: maxDistributorResponseBytes},
+	}
 	if timeout > 0 {
-		httpClient = &http.Client{Timeout: timeout}
+		httpClient.Timeout = timeout
 	}
 	client, err := distributorupload.NewClient(distributorupload.ClientOptions{
 		Endpoint:   endpoint,
@@ -306,7 +368,7 @@ func (c distributorUploadClient) Status(ctx context.Context, runID string) (runS
 	if err != nil {
 		return runStatus{}, err
 	}
-	return runStatus{
+	return sanitizeRunStatus(runStatus{
 		RunID:      status.RunID,
 		PipelineID: status.PipelineID,
 		Status:     status.Status,
@@ -315,7 +377,7 @@ func (c distributorUploadClient) Status(ctx context.Context, runID string) (runS
 		FinishedAt: status.FinishedAt,
 		Report:     append(json.RawMessage(nil), status.Report...),
 		Error:      status.Error,
-	}, nil
+	}), nil
 }
 
 type uploadErrorContext struct {
@@ -331,7 +393,7 @@ type uploadErrorContext struct {
 func wrapUploadError(err error, ctx uploadErrorContext) error {
 	var conflict *distributorupload.IdempotencyConflictError
 	isConflict := errors.As(err, &conflict)
-	err = redactToken(err, ctx.Token)
+	err = safeDistributorDiagnostic(err, ctx.Token)
 	if isConflict {
 		return &IdempotencyConflictError{
 			Err: fmt.Errorf("upload distributor bundle %q to pipeline %q at endpoint %q with idempotency key %q from sources %q as bundle paths %q: idempotency conflict: %w", ctx.BundleID, ctx.PipelineID, ctx.Endpoint, ctx.IdempotencyKey, ctx.SourcePaths, ctx.BundlePaths, err),
@@ -340,6 +402,31 @@ func wrapUploadError(err error, ctx uploadErrorContext) error {
 	return fmt.Errorf("upload distributor bundle %q to pipeline %q at endpoint %q with idempotency key %q from sources %q as bundle paths %q: %w", ctx.BundleID, ctx.PipelineID, ctx.Endpoint, ctx.IdempotencyKey, ctx.SourcePaths, ctx.BundlePaths, err)
 }
 
+func safeDistributorDiagnostic(err error, token string) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, errDistributorResponseTooLarge) {
+		return errDistributorResponseTooLarge
+	}
+	if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+		return redactToken(err, token)
+	}
+	var httpErr *distributorupload.HTTPError
+	if errors.As(err, &httpErr) {
+		return &RemoteResponseError{StatusCode: httpErr.StatusCode, Retryable: httpErr.Retryable}
+	}
+	return errors.New("distributor request failed")
+}
+
+func sanitizeRunStatus(status runStatus) runStatus {
+	status.Report = nil
+	if status.Error != "" {
+		status.Error = "distributor reported a failed run"
+	}
+	return status
+}
+
 func uploadSourcePaths(files []UploadFile) []string {
 	paths := make([]string, 0, len(files))
 	for _, file := range files {

internal/adapters/distributor/client_http_test.go

@@ -0,0 +1,310 @@
+package distributor
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+)
+
+const oversizedRemoteDiagnostic = "REMOTE-DIAGNOSTIC"
+
+func TestUploadUsesProductionHTTPBoundary(t *testing.T) {
+	const token = "test-upload-token"
+	var uploadCalls, statusCalls int
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.Method == http.MethodPost && r.URL.Path == "/prefix/v1/pipelines/weather/upload":
+			uploadCalls++
+			if got := r.Header.Get("Authorization"); got != "Bearer "+token {
+				t.Fatalf("authorization = %q", got)
+			}
+			if got := r.Header.Get("Idempotency-Key"); got != "bundle-key" {
+				t.Fatalf("idempotency key = %q", got)
+			}
+			if got := r.Header.Get("Content-Type"); got != "application/gzip" {
+				t.Fatalf("content type = %q", got)
+			}
+			verifyUploadedArchive(t, r.Body, "daily/report.md", "report body")
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusAccepted)
+			_, _ = io.WriteString(w, `{"run_id":"run-123","status":"accepted"}`)
+		case r.Method == http.MethodGet && r.URL.Path == "/prefix/runs/run-123":
+			statusCalls++
+			if got := r.Header.Get("Authorization"); got != "Bearer "+token {
+				t.Fatalf("authorization = %q", got)
+			}
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, `{"run_id":"run-123","pipeline_id":"weather","status":"succeeded","report":{"detail":"REMOTE-DETAIL"}}`)
+		default:
+			t.Fatalf("unexpected request %s %s", r.Method, r.URL.Path)
+		}
+	}))
+	defer server.Close()
+
+	client := productionClient(t, server.URL+"/prefix", token)
+	result, err := client.Upload(context.Background(), productionUploadRequest(t))
+	if err != nil || uploadCalls != 1 || statusCalls != 1 || result.RunID != "run-123" || result.Status != "succeeded" || result.UploadStatus != "accepted" || result.RunStatus == nil || result.RunStatus.PipelineID != "weather" || len(result.RunStatus.Report) != 0 {
+		t.Fatalf("result/error/calls = %#v/%v/%d/%d", result, err, uploadCalls, statusCalls)
+	}
+}
+
+func TestUploadClassifiesRemoteHTTPDiagnostics(t *testing.T) {
+	const token = "test-upload-token"
+	const remote = oversizedRemoteDiagnostic
+	for _, tt := range []struct {
+		name   string
+		handle func(http.ResponseWriter, *http.Request)
+		check  func(t *testing.T, result UploadResult, err error)
+	}{
+		{
+			name: "upload failure",
+			handle: func(w http.ResponseWriter, r *http.Request) {
+				if r.Method != http.MethodPost {
+					t.Fatalf("method = %s", r.Method)
+				}
+				w.WriteHeader(http.StatusBadRequest)
+				_, _ = io.WriteString(w, `{"error":"REMOTE-DIAGNOSTIC","retryable":true}`)
+			},
+			check: func(t *testing.T, _ UploadResult, err error) {
+				t.Helper()
+				var remoteErr *RemoteResponseError
+				if err == nil || !errors.As(err, &remoteErr) || remoteErr.StatusCode != http.StatusBadRequest || !remoteErr.Retryable {
+					t.Fatalf("error = %T %v", err, err)
+				}
+			},
+		},
+		{
+			name: "status failure",
+			handle: func(w http.ResponseWriter, r *http.Request) {
+				if r.Method == http.MethodPost {
+					w.WriteHeader(http.StatusAccepted)
+					_, _ = io.WriteString(w, `{"run_id":"run-123","status":"accepted"}`)
+					return
+				}
+				w.WriteHeader(http.StatusInternalServerError)
+				_, _ = io.WriteString(w, remote)
+			},
+			check: func(t *testing.T, result UploadResult, err error) {
+				t.Helper()
+				if err != nil || result.Status != "accepted" || result.StatusError != "distributor request failed with HTTP status 500" {
+					t.Fatalf("result/error = %#v/%v", result, err)
+				}
+			},
+		},
+		{
+			name: "failed run",
+			handle: func(w http.ResponseWriter, r *http.Request) {
+				if r.Method == http.MethodPost {
+					w.WriteHeader(http.StatusAccepted)
+					_, _ = io.WriteString(w, `{"run_id":"run-123","status":"accepted"}`)
+					return
+				}
+				_, _ = io.WriteString(w, `{"run_id":"run-123","status":"failed","error":"REMOTE-DIAGNOSTIC","report":{"detail":"REMOTE-DIAGNOSTIC"}}`)
+			},
+			check: func(t *testing.T, result UploadResult, err error) {
+				t.Helper()
+				if err == nil || result.Status != "failed" || result.RunStatus == nil || result.RunStatus.Error != "distributor reported a failed run" || len(result.RunStatus.Report) != 0 {
+					t.Fatalf("result/error = %#v/%v", result, err)
+				}
+			},
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(tt.handle))
+			defer server.Close()
+			result, err := productionClient(t, server.URL, token).Upload(context.Background(), productionUploadRequest(t))
+			tt.check(t, result, err)
+			for _, value := range []string{fmt.Sprint(result), fmt.Sprint(err)} {
+				if strings.Contains(value, remote) || strings.Contains(value, token) {
+					t.Fatalf("normal diagnostic leaked remote value: %q", value)
+				}
+			}
+		})
+	}
+}
+
+func TestUploadBoundsHTTPResponses(t *testing.T) {
+	for _, tt := range []struct {
+		name       string
+		response   func(size int) string
+		statusCode int
+		statusBody func(size int) string
+		check      func(t *testing.T, result UploadResult, err error, overflow bool)
+	}{
+		{
+			name: "accepted response",
+			response: func(size int) string {
+				return paddedJSON(t, `{"run_id":"run-123","status":"accepted","detail":"REMOTE-DIAGNOSTIC"}`, size)
+			},
+			statusBody: func(_ int) string {
+				return `{"run_id":"run-123","status":"succeeded"}`
+			},
+			check: func(t *testing.T, result UploadResult, err error, overflow bool) {
+				t.Helper()
+				if overflow {
+					if !errors.Is(err, errDistributorResponseTooLarge) || result.RunID != "" {
+						t.Fatalf("overflow result/error = %#v/%v", result, err)
+					}
+					return
+				}
+				if err != nil || result.Status != "succeeded" {
+					t.Fatalf("bounded result/error = %#v/%v", result, err)
+				}
+			},
+		},
+		{
+			name: "status report",
+			response: func(_ int) string {
+				return `{"run_id":"run-123","status":"accepted"}`
+			},
+			statusBody: func(size int) string { return statusReportBody(t, size) },
+			check: func(t *testing.T, result UploadResult, err error, overflow bool) {
+				t.Helper()
+				if overflow {
+					if err != nil || result.Status != "accepted" || result.StatusError != errDistributorResponseTooLarge.Error() {
+						t.Fatalf("overflow result/error = %#v/%v", result, err)
+					}
+					return
+				}
+				if err != nil || result.Status != "succeeded" || result.RunStatus == nil || len(result.RunStatus.Report) != 0 {
+					t.Fatalf("bounded result/error = %#v/%v", result, err)
+				}
+			},
+		},
+		{
+			name:       "error response",
+			response:   func(size int) string { return repeatedToLength(oversizedRemoteDiagnostic, size) },
+			statusCode: http.StatusBadRequest,
+			check: func(t *testing.T, result UploadResult, err error, overflow bool) {
+				t.Helper()
+				if overflow {
+					if !errors.Is(err, errDistributorResponseTooLarge) || result.RunID != "" {
+						t.Fatalf("overflow result/error = %#v/%v", result, err)
+					}
+					return
+				}
+				var remoteErr *RemoteResponseError
+				if !errors.As(err, &remoteErr) || remoteErr.StatusCode != http.StatusBadRequest {
+					t.Fatalf("bounded result/error = %#v/%v", result, err)
+				}
+			},
+		},
+	} {
+		for _, overflow := range []bool{false, true} {
+			t.Run(tt.name+"/"+map[bool]string{false: "limit", true: "over-limit"}[overflow], func(t *testing.T) {
+				size := int(maxDistributorResponseBytes)
+				if overflow {
+					size++
+				}
+				var uploadCalls int
+				server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					if r.Method == http.MethodPost {
+						uploadCalls++
+						statusCode := tt.statusCode
+						if statusCode == 0 {
+							statusCode = http.StatusAccepted
+						}
+						w.WriteHeader(statusCode)
+						_, _ = io.WriteString(w, tt.response(size))
+						return
+					}
+					_, _ = io.WriteString(w, tt.statusBody(size))
+				}))
+				defer server.Close()
+
+				result, err := productionClient(t, server.URL, "test-upload-token").Upload(context.Background(), productionUploadRequest(t))
+				tt.check(t, result, err, overflow)
+				if strings.Contains(fmt.Sprint(result), oversizedRemoteDiagnostic) || strings.Contains(fmt.Sprint(err), oversizedRemoteDiagnostic) {
+					t.Fatalf("result/error leaked oversized response detail: %#v/%v", result, err)
+				}
+				if uploadCalls != 1 {
+					t.Fatalf("upload calls = %d, want one", uploadCalls)
+				}
+			})
+		}
+	}
+}
+
+func productionClient(t *testing.T, endpoint, token string) *Client {
+	t.Helper()
+	cfg := config.Defaults().Notify.Distributor
+	cfg.Endpoint = endpoint
+	cfg.Timeout = 0
+	t.Setenv(cfg.TokenEnv, token)
+	return New(cfg)
+}
+
+func productionUploadRequest(t *testing.T) UploadRequest {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "report.md")
+	if err := os.WriteFile(path, []byte("report body"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return UploadRequest{
+		PipelineID: "weather", BundleID: "bundle", IdempotencyKey: "bundle-key",
+		Files:     []UploadFile{{SourcePath: path, BundlePath: "daily/report.md"}},
+		CreatedAt: time.Date(2026, 6, 7, 12, 0, 0, 0, time.UTC),
+	}
+}
+
+func verifyUploadedArchive(t *testing.T, body io.Reader, wantPath, wantContents string) {
+	t.Helper()
+	reader, err := gzip.NewReader(body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer reader.Close()
+	archive := tar.NewReader(reader)
+	for {
+		header, err := archive.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			t.Fatal(err)
+		}
+		if header.Name != wantPath {
+			continue
+		}
+		contents, err := io.ReadAll(archive)
+		if err != nil || string(contents) != wantContents {
+			t.Fatalf("archive file contents/error = %q/%v", contents, err)
+		}
+		return
+	}
+	t.Fatalf("archive did not contain %q", wantPath)
+}
+
+func paddedJSON(t *testing.T, value string, size int) string {
+	t.Helper()
+	if len(value) > size {
+		t.Fatalf("JSON length = %d, exceeds requested size %d", len(value), size)
+	}
+	return value + strings.Repeat(" ", size-len(value))
+}
+
+func statusReportBody(t *testing.T, size int) string {
+	t.Helper()
+	const prefix = `{"run_id":"run-123","pipeline_id":"weather","status":"succeeded","report":"`
+	const suffix = `"}`
+	if len(prefix)+len(suffix) > size {
+		t.Fatalf("status response exceeds requested size %d", size)
+	}
+	return prefix + repeatedToLength(oversizedRemoteDiagnostic, size-len(prefix)-len(suffix)) + suffix
+}
+
+func repeatedToLength(value string, size int) string {
+	return strings.Repeat(value, size/len(value)+1)[:size]
+}

internal/adapters/distributor/client_test.go

@@ -45,8 +45,8 @@ func TestUploadUsesConfiguredClientAndFiles(t *testing.T) {
 	if result.RunID != "run-123" || result.Status != "succeeded" || result.UploadStatus != "accepted" {
 		t.Fatalf("result = %#v, want accepted run", result)
 	}
-	if result.RunStatus == nil || result.RunStatus.PipelineID != "reports" || !strings.Contains(string(result.RunStatus.Report), "replace_older") {
+	if result.RunStatus == nil || result.RunStatus.PipelineID != "reports" || len(result.RunStatus.Report) != 0 {
-		t.Fatalf("RunStatus = %#v, want parsed run report", result.RunStatus)
+		t.Fatalf("RunStatus = %#v, want safe status details", result.RunStatus)
 	}
 	if factory.endpoint != cfg.Endpoint {
 		t.Fatalf("factory endpoint = %q, want %q", factory.endpoint, cfg.Endpoint)
@@ -242,13 +242,14 @@ func TestUploadPollsUntilTerminalStatus(t *testing.T) {
 		},
 	}
 	client := newClient(cfg, factory.newClient)
+	client.pollWait = func(context.Context, time.Duration) error { return nil }
 
 	result, err := client.Upload(context.Background(), validUploadRequest())
 	if err != nil {
 		t.Fatalf("Upload() error = %v", err)
 	}
-	if result.Status != "succeeded" || result.RunStatus == nil || !strings.Contains(string(result.RunStatus.Report), "replace_older") {
+	if result.Status != "succeeded" || result.RunStatus == nil || len(result.RunStatus.Report) != 0 {
-		t.Fatalf("result = %#v, want terminal succeeded status with run report", result)
+		t.Fatalf("result = %#v, want terminal succeeded status without remote report", result)
 	}
 	if factory.client.statusCalls != 2 {
 		t.Fatalf("status calls = %d, want 2", factory.client.statusCalls)
@@ -298,8 +299,8 @@ func TestUploadFailsWhenDistributorRunFailed(t *testing.T) {
 	if err == nil {
 		t.Fatal("Upload() error = nil, want failed distributor run error")
 	}
-	if result.RunStatus == nil || result.RunStatus.Status != "failed" || !strings.Contains(string(result.RunStatus.Report), "failed") {
+	if result.RunStatus == nil || result.RunStatus.Status != "failed" || len(result.RunStatus.Report) != 0 || result.RunStatus.Error != "distributor reported a failed run" {
-		t.Fatalf("result = %#v, want failed run status report", result)
+		t.Fatalf("result = %#v, want safe failed run status", result)
 	}
 	if strings.Contains(err.Error(), "secret-token") || strings.Contains(result.RunStatus.Error, "secret-token") {
 		t.Fatalf("error/result leaked token: err=%q result=%#v", err.Error(), result)

internal/adapters/promptkit/adapter.go

@@ -0,0 +1,343 @@
+// Package promptkitadapter implements promptexec with Promptkit.
+package promptkitadapter
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	promptkit "gitea.maximumdirect.net/eric/promptkit"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/generatedtext"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptassets"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+)
+
+// Config selects the Promptkit sources and optional local backend for one engine.
+type Config struct {
+	ProfileDirectory      string
+	ProfileFile           string
+	LocalEndpoint         string
+	LocalConcurrencyLimit int
+	Timeout               time.Duration
+}
+
+// Adapter owns one Promptkit engine and its opaque prepared execution handles.
+// It supports concurrent Execute calls on the shared executor.
+type Adapter struct {
+	engine *promptkit.Engine
+}
+
+var _ promptexec.Executor = (*Adapter)(nil)
+
+// New constructs a Promptkit-backed executor from Weatherreporter-owned settings.
+func New(config Config) (*Adapter, error) {
+	return newAdapter(config)
+}
+
+func newAdapter(config Config, additionalOptions ...promptkit.Option) (*Adapter, error) {
+	if config.ProfileDirectory != "" && config.ProfileFile != "" {
+		return nil, promptexec.NewError(promptexec.InvalidConfiguration, "profile directory and profile file cannot both be configured", nil)
+	}
+	if config.LocalEndpoint == "" && config.LocalConcurrencyLimit != 0 {
+		return nil, promptexec.NewError(promptexec.InvalidConfiguration, "local concurrency requires a local endpoint", nil)
+	}
+
+	options := []promptkit.Option{
+		promptkit.WithPromptFS(promptassets.PromptFS(), "."),
+		promptkit.WithSchemaFS(promptassets.SchemaFS(), "."),
+		promptkit.WithFallbackProfileFS(promptassets.ProfileFS(), "."),
+	}
+	if config.ProfileFile != "" {
+		options = append(options, promptkit.WithProfileFile(config.ProfileFile))
+	}
+	if config.LocalEndpoint != "" {
+		options = append(options, promptkit.WithBackend(promptkit.LocalBackend(config.LocalEndpoint, config.LocalConcurrencyLimit)))
+	}
+	options = append(options, additionalOptions...)
+	engine, err := promptkit.NewEngine(promptkit.Config{
+		ProfileDir: config.ProfileDirectory,
+		Timeout:    config.Timeout,
+	}, options...)
+	if err != nil {
+		return nil, classifyConfigurationError(err)
+	}
+	return &Adapter{engine: engine}, nil
+}
+
+func newAdapterForTest(config Config, client promptkit.LLMClient) (*Adapter, error) {
+	return newAdapter(config, promptkit.WithLLMClient(client))
+}
+
+// InspectPrompt maps an exact Promptkit prompt inspection into project-owned values.
+func (adapter *Adapter) InspectPrompt(ctx context.Context, promptID string, promptVersion string) (promptexec.PromptInspection, error) {
+	if adapter == nil || adapter.engine == nil {
+		return promptexec.PromptInspection{}, promptexec.NewError(promptexec.InvalidConfiguration, "prompt executor is not configured", nil)
+	}
+	inspection, err := adapter.engine.InspectPrompt(ctx, promptID, promptVersion)
+	if err != nil {
+		return promptexec.PromptInspection{}, classifyError(err)
+	}
+	inputs := make([]promptexec.InputDefinition, len(inspection.Inputs))
+	for index, input := range inspection.Inputs {
+		inputs[index] = promptexec.InputDefinition{
+			Name:        input.Name,
+			Required:    input.Required,
+			ContentType: input.ContentType,
+			Description: input.Description,
+		}
+	}
+	return promptexec.PromptInspection{
+		PromptID:         inspection.PromptID,
+		PromptVersion:    inspection.PromptVersion,
+		PromptHash:       inspection.PromptHash,
+		DefaultProfileID: inspection.DefaultProfileID,
+		Inputs:           inputs,
+		Output:           outputContract(inspection.OutputContract),
+	}, nil
+}
+
+// InspectProfile maps one explicit Promptkit profile inspection into safe values.
+func (adapter *Adapter) InspectProfile(ctx context.Context, profileID string) (promptexec.ProfileInspection, error) {
+	if adapter == nil || adapter.engine == nil {
+		return promptexec.ProfileInspection{}, promptexec.NewError(promptexec.InvalidConfiguration, "prompt executor is not configured", nil)
+	}
+	inspection, err := adapter.engine.InspectProfile(ctx, profileID)
+	if err != nil {
+		return promptexec.ProfileInspection{}, classifyError(err)
+	}
+	return promptexec.ProfileInspection{
+		ProfileID:          inspection.ProfileID,
+		BackendID:          inspection.EffectiveModelParams.BackendID,
+		ModelName:          inspection.EffectiveModelParams.Model,
+		CredentialRequired: inspection.APIKeyRequired,
+		APIKeyEnv:          inspection.EffectiveModelParams.APIKeyEnv,
+	}, nil
+}
+
+// Execute prepares one exact inline data package, invokes prepared after a
+// successful preparation, and then runs the same opaque prepared handle.
+func (adapter *Adapter) Execute(ctx context.Context, request promptexec.ExecuteRequest, preparedCallback promptexec.PreparationCallback) (*promptexec.Execution, error) {
+	if adapter == nil || adapter.engine == nil {
+		return nil, promptexec.NewError(promptexec.InvalidConfiguration, "prompt executor is not configured", nil)
+	}
+	prepared, err := adapter.engine.PrepareExecution(ctx, promptkit.RunRequest{
+		PromptID:      request.PromptID,
+		PromptVersion: request.PromptVersion,
+		ProfileID:     request.ProfileID,
+		Inputs:        map[string]promptkit.ArtifactRef{"data_package": promptkit.Inline(string(append([]byte(nil), request.DataPackage...)))},
+	})
+	if err != nil {
+		return nil, classifyError(err)
+	}
+	defer prepared.Discard()
+
+	details := prepared.Details()
+	preparation, debug := preparationValues(details, request.CaptureDebug)
+	if preparedCallback != nil {
+		if err := preparedCallback(preparation, debug); err != nil {
+			return nil, err
+		}
+	}
+
+	result, err := adapter.engine.RunPrepared(ctx, prepared)
+	if err != nil {
+		return nil, classifyError(err)
+	}
+	return executionValue(result, request.CaptureDebug), nil
+}
+
+func outputContract(value promptkit.OutputContract) promptexec.OutputContract {
+	return promptexec.OutputContract{
+		Format:         string(value.Format),
+		ValidationMode: string(value.ValidationMode),
+		SchemaPath:     value.SchemaPath,
+		RepairAttempts: value.RepairAttempts,
+	}
+}
+
+func preparationValues(value promptkit.PreparedRun, captureDebug bool) (promptexec.Preparation, *promptexec.PreparationDebug) {
+	preparation := promptexec.Preparation{
+		PromptID:           value.PromptID,
+		PromptVersion:      value.PromptVersion,
+		PromptHash:         value.PromptHash,
+		RenderedPromptHash: value.RenderedPromptHash,
+		InputHashes:        copyInputHashes(value.InputHashes),
+		ProfileID:          value.SelectedProfileID,
+		BackendID:          value.SelectedBackendID,
+		ModelName:          value.EffectiveModelParams.Model,
+		Output:             outputContract(value.OutputContract),
+		StartedAt:          value.StartTime,
+		EndedAt:            value.EndTime,
+		Duration:           time.Duration(value.DurationMS) * time.Millisecond,
+	}
+	if !captureDebug {
+		return preparation, nil
+	}
+	debug := &promptexec.PreparationDebug{
+		RenderedMessages: renderedMessages(value.Messages),
+		Endpoint:         value.EffectiveModelParams.Endpoint,
+		ParametersJSON:   marshalDebugParameters(value.EffectiveModelParams),
+	}
+	if value.StructuredOutput != nil && value.StructuredOutput.JSONSchema != nil {
+		debug.StructuredSchema, _ = json.Marshal(value.StructuredOutput.JSONSchema.Schema)
+	}
+	return preparation, debug
+}
+
+func executionValue(value *promptkit.RunResult, captureDebug bool) *promptexec.Execution {
+	if value == nil {
+		return nil
+	}
+	validation := promptexec.NewValidation(
+		promptexec.ValidationStatus(value.Validation.Status),
+		string(value.Validation.Mode),
+		value.Validation.SchemaPath,
+		value.Validation.RepairAttempts,
+		value.Validation.Errors,
+	)
+	rawOutput := []byte(nil)
+	if len(value.RawOutput) <= generatedtext.MaxGeneratedTextBytes {
+		rawOutput = []byte(value.RawOutput)
+	} else {
+		validation = promptexec.NewValidation(
+			promptexec.ValidationFailed,
+			string(value.Validation.Mode),
+			value.Validation.SchemaPath,
+			value.Validation.RepairAttempts,
+			[]string{"generated output exceeds the configured size limit"},
+		)
+	}
+	execution := &promptexec.Execution{
+		RunID:              value.RunID,
+		PromptID:           value.PromptID,
+		PromptVersion:      value.PromptVersion,
+		PromptHash:         value.PromptHash,
+		RenderedPromptHash: value.RenderedPromptHash,
+		InputHashes:        copyInputHashes(value.InputHashes),
+		ProfileID:          value.SelectedProfileID,
+		BackendID:          value.SelectedBackendID,
+		ModelName:          value.ModelName,
+		GeneratedHash:      value.Artifact.Hash,
+		Usage: promptexec.TokenUsage{
+			PromptTokens:     value.Usage.PromptTokens,
+			CompletionTokens: value.Usage.CompletionTokens,
+			TotalTokens:      value.Usage.TotalTokens,
+			CachedTokens:     value.Usage.CachedTokens,
+			CacheWriteTokens: value.Usage.CacheWriteTokens,
+		},
+		StartedAt:  value.StartTime,
+		EndedAt:    value.EndTime,
+		Duration:   value.Duration,
+		Validation: validation,
+		RawOutput:  rawOutput,
+	}
+	if captureDebug {
+		execution.Debug = &promptexec.ExecutionDebug{
+			RawOutput:             append([]byte(nil), rawOutput...),
+			ValidationDiagnostics: append([]string(nil), validation.Diagnostics...),
+		}
+	}
+	return execution
+}
+
+func renderedMessages(values []promptkit.RenderedMessage) []promptexec.RenderedMessage {
+	messages := make([]promptexec.RenderedMessage, len(values))
+	for index, value := range values {
+		messages[index] = promptexec.RenderedMessage{Role: value.Role, Content: value.Content}
+	}
+	return messages
+}
+
+func copyInputHashes(values map[string]string) map[string]string {
+	if values == nil {
+		return nil
+	}
+	copy := make(map[string]string, len(values))
+	for key, value := range values {
+		copy[key] = value
+	}
+	return copy
+}
+
+func marshalDebugParameters(value promptkit.ExecutionTarget) []byte {
+	parameters := struct {
+		Temperature     float64 `json:"temperature"`
+		MaxTokens       int     `json:"max_tokens"`
+		TopP            float64 `json:"top_p"`
+		TimeoutSeconds  int     `json:"timeout_seconds"`
+		ServiceTier     string  `json:"service_tier"`
+		ReasoningEffort string  `json:"reasoning_effort"`
+	}{
+		Temperature:     value.Temperature,
+		MaxTokens:       value.MaxTokens,
+		TopP:            value.TopP,
+		TimeoutSeconds:  value.TimeoutSeconds,
+		ServiceTier:     value.ServiceTier,
+		ReasoningEffort: value.ReasoningEffort,
+	}
+	data, _ := json.Marshal(parameters)
+	return data
+}
+
+func classifyConfigurationError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return promptexec.NewError(promptexec.InvalidConfiguration, "prompt executor configuration is invalid", err)
+}
+
+func classifyError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, context.Canceled) {
+		return promptexec.NewError(promptexec.Canceled, "prompt operation was canceled", err)
+	}
+	if errors.Is(err, context.DeadlineExceeded) {
+		return promptexec.NewError(promptexec.DeadlineExceeded, "prompt operation exceeded its deadline", err)
+	}
+	var capacityError *promptkit.CapacityError
+	if errors.As(err, &capacityError) {
+		return promptexec.NewCapacityError(capacityError.BackendID, "prompt backend capacity is unavailable", err)
+	}
+	var generationError *promptkit.GenerationError
+	if errors.As(err, &generationError) {
+		return promptexec.NewGenerationError(
+			generationError.StatusCode(),
+			generationError.ProviderCode(),
+			generationError.ProviderType(),
+			generationError.ProviderMessage(),
+			err,
+		)
+	}
+	switch {
+	case errors.Is(err, promptkit.ErrInvalidConfig):
+		return promptexec.NewError(promptexec.InvalidConfiguration, "prompt executor configuration is invalid", err)
+	case errors.Is(err, promptkit.ErrPromptNotFound):
+		return promptexec.NewError(promptexec.PromptNotFound, "prompt definition was not found", err)
+	case errors.Is(err, promptkit.ErrPromptLoad):
+		return promptexec.NewError(promptexec.PromptLoad, "prompt definition could not be loaded", err)
+	case errors.Is(err, promptkit.ErrProfileNotFound):
+		return promptexec.NewError(promptexec.ProfileNotFound, "execution profile was not found", err)
+	case errors.Is(err, promptkit.ErrProfileLoad):
+		return promptexec.NewError(promptexec.ProfileLoad, "execution profile could not be loaded", err)
+	case errors.Is(err, promptkit.ErrAPIKeyEnvMissing):
+		return promptexec.NewError(promptexec.MissingCredential, "execution credential is unavailable", err)
+	case errors.Is(err, promptkit.ErrArtifactLoad):
+		return promptexec.NewError(promptexec.ArtifactLoad, "prompt input could not be loaded", err)
+	case errors.Is(err, promptkit.ErrPromptRender):
+		return promptexec.NewError(promptexec.PromptRender, "prompt could not be rendered", err)
+	case errors.Is(err, promptkit.ErrCapacityExceeded):
+		return promptexec.NewCapacityError("", "prompt backend capacity is unavailable", err)
+	case errors.Is(err, promptkit.ErrLLMGenerate):
+		return promptexec.NewError(promptexec.Generation, "prompt generation failed", err)
+	case errors.Is(err, promptkit.ErrValidation):
+		return promptexec.NewError(promptexec.OperationalValidation, "prompt output validation could not be completed", err)
+	case errors.Is(err, promptkit.ErrInvalidRequest), errors.Is(err, promptkit.ErrProfileRequired):
+		return promptexec.NewError(promptexec.InvalidRequest, "prompt execution request is invalid", err)
+	default:
+		return promptexec.NewError(promptexec.Generation, "prompt operation failed", fmt.Errorf("%w", err))
+	}
+}

internal/adapters/promptkit/adapter_test.go

@@ -0,0 +1,958 @@
+package promptkitadapter
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	promptkit "gitea.maximumdirect.net/eric/promptkit"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/generatedtext"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+)
+
+type fakeClient struct {
+	mu       sync.Mutex
+	response *promptkit.GenerateResponse
+	err      error
+	outcomes []generationOutcome
+	next     int
+	calls    int
+	requests []promptkit.GenerateRequest
+	block    bool
+	started  chan struct{}
+}
+
+type generationOutcome struct {
+	response *promptkit.GenerateResponse
+	err      error
+}
+
+type recordingReader struct {
+	ref promptkit.ArtifactRef
+}
+
+func (reader *recordingReader) Read(_ context.Context, ref promptkit.ArtifactRef) (*promptkit.Artifact, error) {
+	reader.ref = ref
+	return &promptkit.Artifact{
+		Name:        "data_package",
+		ContentType: "application/yaml",
+		Body:        []byte(ref.Body),
+		URI:         ref.URI,
+		Hash:        "input-hash",
+	}, nil
+}
+
+func (client *fakeClient) Generate(ctx context.Context, request promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) {
+	client.mu.Lock()
+	client.calls++
+	client.requests = append(client.requests, request)
+	block := client.block
+	started := client.started
+	response := client.response
+	err := client.err
+	if client.next < len(client.outcomes) {
+		outcome := client.outcomes[client.next]
+		client.next++
+		response, err = outcome.response, outcome.err
+	}
+	client.mu.Unlock()
+	if started != nil {
+		started <- struct{}{}
+	}
+	if block {
+		<-ctx.Done()
+		return nil, ctx.Err()
+	}
+	return response, err
+}
+
+func TestExecuteSupportsConcurrentCalls(t *testing.T) {
+	client := &fakeClient{response: validResponse(), block: true, started: make(chan struct{}, 2)}
+	adapter := newTestAdapter(t, client)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	executionErrors := make(chan error, 2)
+	for range 2 {
+		go func() {
+			_, err := adapter.Execute(ctx, testExecuteRequest(), nil)
+			executionErrors <- err
+		}()
+	}
+	for range 2 {
+		select {
+		case <-client.started:
+		case <-time.After(5 * time.Second):
+			t.Fatal("timed out waiting for concurrent Promptkit calls")
+		}
+	}
+	cancel()
+	for range 2 {
+		if err := <-executionErrors; promptexec.CategoryOf(err) != promptexec.Canceled {
+			t.Fatalf("Execute() error/category = %v/%q", err, promptexec.CategoryOf(err))
+		}
+	}
+	if client.callCount() != 2 {
+		t.Fatalf("provider calls = %d, want 2", client.callCount())
+	}
+}
+
+func (client *fakeClient) callCount() int {
+	client.mu.Lock()
+	defer client.mu.Unlock()
+	return client.calls
+}
+
+func (client *fakeClient) request() promptkit.GenerateRequest {
+	client.mu.Lock()
+	defer client.mu.Unlock()
+	return client.requests[0]
+}
+
+func (client *fakeClient) allRequests() []promptkit.GenerateRequest {
+	client.mu.Lock()
+	defer client.mu.Unlock()
+	return append([]promptkit.GenerateRequest(nil), client.requests...)
+}
+
+func TestInspectPromptAndProfile(t *testing.T) {
+	adapter := newTestAdapter(t, &fakeClient{})
+	inspection, err := adapter.InspectPrompt(context.Background(), "weather.daily_generated_text", "2.1.0")
+	if err != nil {
+		t.Fatalf("InspectPrompt() error = %v", err)
+	}
+	if inspection.PromptID != "weather.daily_generated_text" || inspection.PromptVersion != "2.1.0" || inspection.DefaultProfileID != "weather-balanced" || inspection.Output.RepairAttempts != 1 {
+		t.Fatalf("inspection = %#v", inspection)
+	}
+	if len(inspection.Inputs) != 1 || inspection.Inputs[0].Name != "data_package" || !inspection.Inputs[0].Required || inspection.Inputs[0].ContentType != "application/yaml" {
+		t.Fatalf("inputs = %#v", inspection.Inputs)
+	}
+	if inspection.Output.Format != "json" || inspection.Output.ValidationMode != "json_schema" || inspection.Output.SchemaPath != "daily.generated_text.schema.json" {
+		t.Fatalf("output = %#v", inspection.Output)
+	}
+
+	profile, err := adapter.InspectProfile(context.Background(), "test-profile")
+	if err != nil {
+		t.Fatalf("InspectProfile() error = %v", err)
+	}
+	if profile.ProfileID != "test-profile" || profile.BackendID != "" || profile.ModelName != "test-model" || profile.CredentialRequired {
+		t.Fatalf("profile = %#v", profile)
+	}
+	if strings.Contains(fmt.Sprintf("%#v", profile), "https://profile.example") {
+		t.Fatalf("profile leaks endpoint: %#v", profile)
+	}
+
+	builtin, err := adapter.InspectProfile(context.Background(), "gemini-flash-latest")
+	if err != nil {
+		t.Fatalf("InspectProfile(builtin) error = %v", err)
+	}
+	if builtin.ProfileID != "gemini-flash-latest" || builtin.ModelName == "" {
+		t.Fatalf("builtin profile = %#v", builtin)
+	}
+}
+
+func TestEmbeddedProfilesAreAvailableToProductionAndTestAdapters(t *testing.T) {
+	adapter, err := New(Config{})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	for _, want := range []struct {
+		id      string
+		backend string
+		model   string
+	}{
+		{"weather-light", "openrouter", "deepseek/deepseek-v4-flash"},
+		{"weather-balanced", "openrouter", "~google/gemini-flash-latest"},
+		{"weather-deep", "openrouter", "~anthropic/claude-sonnet-latest"},
+	} {
+		t.Run(want.id, func(t *testing.T) {
+			assertProfile(t, adapter, want.id, want.backend, want.model)
+		})
+	}
+
+	testAdapter, err := newAdapterForTest(Config{}, &fakeClient{})
+	if err != nil {
+		t.Fatalf("newAdapterForTest() error = %v", err)
+	}
+	assertProfile(t, testAdapter, "weather-light", "openrouter", "deepseek/deepseek-v4-flash")
+}
+
+func TestConfiguredProfilesOverrideEmbeddedFallbacks(t *testing.T) {
+	file := writeProfileFile(t, `id: weather-light
+endpoint: https://local-file.example/v1
+model: file-light
+`)
+	fileAdapter, err := New(Config{ProfileFile: file})
+	if err != nil {
+		t.Fatalf("New(profile file) error = %v", err)
+	}
+	assertProfile(t, fileAdapter, "weather-light", "", "file-light")
+
+	directory := testProfileDirectory(t, map[string]string{"profile.yml": `id: weather-light
+backend: local
+model: directory-light
+`})
+	directoryAdapter, err := New(Config{ProfileDirectory: directory, LocalEndpoint: "https://local-directory.example/v1"})
+	if err != nil {
+		t.Fatalf("New(profile directory) error = %v", err)
+	}
+	assertProfile(t, directoryAdapter, "weather-light", promptkit.BackendLocal, "directory-light")
+
+	derived := writeProfileFile(t, `id: weather-light
+base_profile: gemini-flash-latest
+`)
+	derivedAdapter, err := New(Config{ProfileFile: derived})
+	if err != nil {
+		t.Fatalf("New(derived profile) error = %v", err)
+	}
+	assertProfile(t, derivedAdapter, "weather-light", "openrouter", "~google/gemini-flash-latest")
+}
+
+func TestConfiguredBaseProfileOverridesEmbeddedProfileTarget(t *testing.T) {
+	directory := testProfileDirectory(t, map[string]string{
+		"deepseek.yml": `id: deepseek-4-flash
+backend: local
+model: shadowed-deepseek
+`,
+	})
+	adapter, err := New(Config{ProfileDirectory: directory, LocalEndpoint: "https://local-directory.example/v1"})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	assertProfile(t, adapter, "weather-light", promptkit.BackendLocal, "shadowed-deepseek")
+}
+
+func TestMaintainedWeatherLightLocalProfileExampleInspectsOffline(t *testing.T) {
+	adapter, err := New(Config{ProfileFile: filepath.Join("..", "..", "..", "examples", "weather-light-local-profile.yml")})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	assertProfile(t, adapter, "weather-light", "", "weather-local")
+}
+
+func TestMaintainedWeatherLightLocalProfileExampleExecutesThroughProductionClient(t *testing.T) {
+	t.Setenv("WEATHERREPORTER_TEST_MISSING_KEY", "")
+	for _, test := range []struct {
+		name             string
+		credentialSource string
+	}{
+		{name: "without credential source"},
+		{name: "with blank optional credential source", credentialSource: "\napi_key_env: WEATHERREPORTER_TEST_MISSING_KEY\n"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			var authorization string
+			server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+				authorization = request.Header.Get("Authorization")
+				writer.Header().Set("Content-Type", "application/json")
+				_, _ = fmt.Fprintf(writer, `{"choices":[{"message":{"content":%q}}],"usage":{"prompt_tokens":12,"completion_tokens":8,"total_tokens":20}}`, validResponse().Content)
+			}))
+			defer server.Close()
+
+			example, err := os.ReadFile(filepath.Join("..", "..", "..", "examples", "weather-light-local-profile.yml"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			profile := strings.Replace(string(example), "http://127.0.0.1:11434/v1", server.URL+"/v1", 1) + test.credentialSource
+			adapter, err := New(Config{ProfileFile: writeProfileFile(t, profile)})
+			if err != nil {
+				t.Fatalf("New() error = %v", err)
+			}
+			request := testExecuteRequest()
+			request.ProfileID = "weather-light"
+			var preparation promptexec.Preparation
+			result, err := adapter.Execute(context.Background(), request, func(value promptexec.Preparation, _ *promptexec.PreparationDebug) error {
+				preparation = value
+				return nil
+			})
+			if err != nil {
+				t.Fatalf("Execute() error = %v", err)
+			}
+			if authorization != "" {
+				t.Fatalf("Authorization header = %q, want absent", authorization)
+			}
+			if preparation.ProfileID != "weather-light" || preparation.BackendID != "" || preparation.ModelName != "weather-local" || preparation.Output.RepairAttempts != 1 {
+				t.Fatalf("preparation = %#v", preparation)
+			}
+			if result == nil || result.ProfileID != "weather-light" || result.BackendID != "" || result.ModelName != "weather-local" || result.Validation.Status != promptexec.ValidationPassed || result.Validation.RepairAttempts != 0 {
+				t.Fatalf("execution = %#v", result)
+			}
+		})
+	}
+}
+
+func TestProfileResolutionFallsThroughOnlyWhenTheConfiguredIDIsAbsent(t *testing.T) {
+	absentAdapter, err := New(Config{ProfileDirectory: testProfileDirectory(t, map[string]string{"profile.yml": `id: other-profile
+backend: openrouter
+model: other-model
+`})})
+	if err != nil {
+		t.Fatalf("New(absent profile) error = %v", err)
+	}
+	assertProfile(t, absentAdapter, "weather-light", "openrouter", "deepseek/deepseek-v4-flash")
+
+	malformedAdapter, err := New(Config{ProfileDirectory: testProfileDirectory(t, map[string]string{"profile.yml": `id: weather-light
+backend: openrouter
+`})})
+	if err != nil {
+		t.Fatalf("New(malformed profile) error = %v", err)
+	}
+	if _, err := malformedAdapter.InspectProfile(context.Background(), "weather-light"); err == nil {
+		t.Fatal("InspectProfile() error = nil, want malformed configured profile error")
+	}
+}
+
+func TestProfileResolutionReturnsConfiguredInheritanceFailures(t *testing.T) {
+	tests := []struct {
+		name     string
+		profile  string
+		profiles map[string]string
+	}{
+		{
+			name:    "missing base",
+			profile: "missing-base",
+			profiles: map[string]string{"missing.yml": `id: missing-base
+base_profile: unavailable
+`},
+		},
+		{
+			name:    "cyclic bases",
+			profile: "first",
+			profiles: map[string]string{
+				"first.yml": `id: first
+base_profile: second
+`,
+				"second.yml": `id: second
+base_profile: first
+`,
+			},
+		},
+		{
+			name:    "malformed base",
+			profile: "child",
+			profiles: map[string]string{
+				"child.yml": `id: child
+base_profile: malformed
+`,
+				"malformed.yml": `id: malformed
+base_profile: [not-a-profile]
+`,
+			},
+		},
+		{
+			name:    "incomplete target",
+			profile: "incomplete",
+			profiles: map[string]string{"incomplete.yml": `id: incomplete
+backend: openrouter
+`},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			adapter, err := New(Config{ProfileDirectory: testProfileDirectory(t, test.profiles)})
+			if err != nil {
+				t.Fatalf("New() error = %v", err)
+			}
+			if _, err := adapter.InspectProfile(context.Background(), test.profile); err == nil {
+				t.Fatal("InspectProfile() error = nil, want configured inheritance error")
+			}
+		})
+	}
+}
+
+func TestRakestrawhomeBuiltInProfileInspectsOffline(t *testing.T) {
+	adapter, err := New(Config{})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	profile, err := adapter.InspectProfile(context.Background(), "rakestrawhome-gemma-4-31b")
+	if err != nil {
+		t.Fatalf("InspectProfile() error = %v", err)
+	}
+	if profile.ProfileID != "rakestrawhome-gemma-4-31b" || profile.BackendID != "rakestrawhome" || profile.ModelName == "" {
+		t.Fatalf("profile = %#v", profile)
+	}
+}
+
+func TestProfileResolutionPreservesBuiltInAndExplicitPrecedence(t *testing.T) {
+	adapter, err := New(Config{})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	builtin, err := adapter.InspectProfile(context.Background(), "gemini-flash-latest")
+	if err != nil {
+		t.Fatalf("InspectProfile(builtin) error = %v", err)
+	}
+	if builtin.ProfileID != "gemini-flash-latest" || builtin.BackendID != "openrouter" || builtin.ModelName == "" {
+		t.Fatalf("builtin profile = %#v", builtin)
+	}
+
+	explicit, err := newAdapter(Config{}, promptkit.WithProfiles(promptkit.Profile{
+		ID:       "weather-light",
+		Endpoint: "https://explicit.example/v1",
+		Model:    "explicit-light",
+	}))
+	if err != nil {
+		t.Fatalf("newAdapter(explicit profile) error = %v", err)
+	}
+	assertProfile(t, explicit, "weather-light", "", "explicit-light")
+}
+
+func TestExecuteUsesPreparedInlineDataPackage(t *testing.T) {
+	client := &fakeClient{response: validResponse()}
+	adapter := newTestAdapter(t, client)
+	request := testExecuteRequest()
+	callbackCalls := 0
+	result, err := adapter.Execute(context.Background(), request, func(preparation promptexec.Preparation, debug *promptexec.PreparationDebug) error {
+		callbackCalls++
+		if preparation.PromptID != request.PromptID || preparation.PromptVersion != request.PromptVersion || preparation.ModelName != "test-model" {
+			t.Fatalf("preparation = %#v", preparation)
+		}
+		if debug != nil {
+			t.Fatalf("debug = %#v, want nil", debug)
+		}
+		if client.callCount() != 0 {
+			t.Fatal("provider called before preparation callback")
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if callbackCalls != 1 || client.callCount() != 1 {
+		t.Fatalf("callback/provider calls = %d/%d, want 1/1", callbackCalls, client.callCount())
+	}
+	if result == nil || result.Validation.Status != promptexec.ValidationPassed || string(result.RawOutput) != client.response.Content {
+		t.Fatalf("result = %#v", result)
+	}
+	if result.Debug != nil {
+		t.Fatalf("debug = %#v, want nil", result.Debug)
+	}
+	providerRequest := client.request()
+	if providerRequest.Target.Model != "test-model" || providerRequest.Target.Endpoint != "https://profile.example/v1" {
+		t.Fatalf("provider target = %#v", providerRequest.Target)
+	}
+	if len(providerRequest.Prompt.Messages) == 0 || !strings.Contains(providerRequest.Prompt.Messages[2].Content, string(request.DataPackage)) {
+		t.Fatalf("rendered messages do not contain exact data package: %#v", providerRequest.Prompt.Messages)
+	}
+}
+
+func TestExecuteEmbeddedHourlyProfileThroughPreparedPath(t *testing.T) {
+	t.Setenv("OPENROUTER_API_KEY", "test-openrouter-key")
+	client := &fakeClient{response: hourlyValidResponse()}
+	adapter, err := newAdapter(Config{}, promptkit.WithLLMClient(client))
+	if err != nil {
+		t.Fatalf("newAdapter() error = %v", err)
+	}
+	request := promptexec.ExecuteRequest{
+		PromptID:      "weather.hourly_generated_text",
+		PromptVersion: "2.1.0",
+		ProfileID:     "weather-light",
+		DataPackage:   []byte("report:\n  id: hourly\nbriefing: {}\n"),
+	}
+	var preparation promptexec.Preparation
+	prepared := false
+	result, err := adapter.Execute(context.Background(), request, func(value promptexec.Preparation, _ *promptexec.PreparationDebug) error {
+		if client.callCount() != 0 {
+			t.Fatal("provider was called before preparation completed")
+		}
+		preparation = value
+		prepared = true
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if !prepared || preparation.ProfileID != "weather-light" || preparation.BackendID != "openrouter" || preparation.ModelName != "deepseek/deepseek-v4-flash" {
+		t.Fatalf("preparation = %#v", preparation)
+	}
+	if result == nil || result.ProfileID != "weather-light" || result.BackendID != "openrouter" || result.ModelName != "deepseek/deepseek-v4-flash" || result.Validation.Status != promptexec.ValidationPassed {
+		t.Fatalf("execution = %#v", result)
+	}
+	if client.callCount() != 1 || client.request().Target.Model != "deepseek/deepseek-v4-flash" {
+		t.Fatalf("provider calls/request = %d/%#v", client.callCount(), client.request())
+	}
+}
+
+func TestExecuteUsesExactInlineDataPackageProvenance(t *testing.T) {
+	client := &fakeClient{response: validResponse()}
+	reader := &recordingReader{}
+	adapter := newTestAdapterWithOptions(t, client, promptkit.WithArtifactReader(reader))
+	request := testExecuteRequest()
+	if _, err := adapter.Execute(context.Background(), request, nil); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if reader.ref.Type != promptkit.ArtifactRefInline || reader.ref.URI != "" || reader.ref.Body != string(request.DataPackage) {
+		t.Fatalf("artifact ref = %#v, want exact inline data package provenance", reader.ref)
+	}
+}
+
+func TestExecuteCapturesSensitiveDebugOnlyWhenRequested(t *testing.T) {
+	client := &fakeClient{response: validResponse()}
+	adapter := newTestAdapter(t, client)
+	request := testExecuteRequest()
+	request.CaptureDebug = true
+	var preparationDebug *promptexec.PreparationDebug
+	result, err := adapter.Execute(context.Background(), request, func(preparation promptexec.Preparation, debug *promptexec.PreparationDebug) error {
+		preparationDebug = debug
+		if strings.Contains(fmt.Sprintf("%#v", preparation), "https://profile.example") || strings.Contains(fmt.Sprintf("%#v", preparation), string(request.DataPackage)) {
+			t.Fatalf("safe preparation leaks sensitive content: %#v", preparation)
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if preparationDebug == nil || preparationDebug.Endpoint != "https://profile.example/v1" || len(preparationDebug.RenderedMessages) == 0 || len(preparationDebug.StructuredSchema) == 0 || len(preparationDebug.ParametersJSON) == 0 {
+		t.Fatalf("preparation debug = %#v", preparationDebug)
+	}
+	if result.Debug == nil || string(result.Debug.RawOutput) != client.response.Content {
+		t.Fatalf("execution debug = %#v", result.Debug)
+	}
+}
+
+func TestMarshalDebugParametersOmitsProviderExtras(t *testing.T) {
+	const marker = "private-debug-marker"
+	parameters := string(marshalDebugParameters(promptkit.ExecutionTarget{
+		Temperature:     0.2,
+		MaxTokens:       400,
+		TopP:            0.9,
+		TimeoutSeconds:  30,
+		ServiceTier:     "flex",
+		ReasoningEffort: "high",
+		ExtraParams: map[string]any{
+			"access-key": marker,
+			"signature":  marker,
+		},
+	}))
+	if strings.Contains(parameters, marker) || strings.Contains(parameters, "extra_params") {
+		t.Fatalf("debug parameters leaked provider extras: %s", parameters)
+	}
+	for _, want := range []string{`"temperature":0.2`, `"max_tokens":400`, `"top_p":0.9`, `"timeout_seconds":30`, `"service_tier":"flex"`, `"reasoning_effort":"high"`} {
+		if !strings.Contains(parameters, want) {
+			t.Fatalf("debug parameters missing safe value %q: %s", want, parameters)
+		}
+	}
+}
+
+func TestExecuteCallbackFailurePreventsGeneration(t *testing.T) {
+	client := &fakeClient{response: validResponse()}
+	adapter := newTestAdapter(t, client)
+	callbackError := errors.New("save preparation")
+	result, err := adapter.Execute(context.Background(), testExecuteRequest(), func(promptexec.Preparation, *promptexec.PreparationDebug) error {
+		return callbackError
+	})
+	if result != nil || !errors.Is(err, callbackError) || client.callCount() != 0 {
+		t.Fatalf("result/error/provider calls = %#v/%v/%d", result, err, client.callCount())
+	}
+}
+
+func TestExecuteReturnsCompletedValidationRejection(t *testing.T) {
+	client := &fakeClient{response: &promptkit.GenerateResponse{Content: `{"summary":42}`, Usage: promptkit.TokenUsage{TotalTokens: 5}}}
+	adapter := newTestAdapter(t, client)
+	result, err := adapter.Execute(context.Background(), testExecuteRequest(), nil)
+	if err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if result == nil || result.Validation.Status != promptexec.ValidationFailed || len(result.Validation.Diagnostics) == 0 || string(result.RawOutput) != client.response.Content {
+		t.Fatalf("result = %#v", result)
+	}
+}
+
+func TestExecuteMapsCorrectiveGenerationResults(t *testing.T) {
+	valid := `{"summary":"valid"}`
+	invalid := `{"summary":42}`
+	tests := []struct {
+		name        string
+		outcomes    []generationOutcome
+		wantStatus  promptexec.ValidationStatus
+		wantRepairs int
+		wantCalls   int
+		wantRaw     string
+		wantUsage   promptexec.TokenUsage
+	}{
+		{
+			name:        "first pass valid",
+			outcomes:    []generationOutcome{{response: generationResponse(valid, 2, 3, 5)}},
+			wantStatus:  promptexec.ValidationPassed,
+			wantRepairs: 0,
+			wantCalls:   1,
+			wantRaw:     valid,
+			wantUsage:   promptexec.TokenUsage{PromptTokens: 2, CompletionTokens: 3, TotalTokens: 5},
+		},
+		{
+			name:        "empty output repaired",
+			outcomes:    []generationOutcome{{response: generationResponse("", 2, 3, 5)}, {response: generationResponse(valid, 7, 11, 18)}},
+			wantStatus:  promptexec.ValidationPassed,
+			wantRepairs: 1,
+			wantCalls:   2,
+			wantRaw:     valid,
+			wantUsage:   promptexec.TokenUsage{PromptTokens: 9, CompletionTokens: 14, TotalTokens: 23},
+		},
+		{
+			name:        "invalid output repaired",
+			outcomes:    []generationOutcome{{response: generationResponse(invalid, 2, 3, 5)}, {response: generationResponse(valid, 7, 11, 18)}},
+			wantStatus:  promptexec.ValidationPassed,
+			wantRepairs: 1,
+			wantCalls:   2,
+			wantRaw:     valid,
+			wantUsage:   promptexec.TokenUsage{PromptTokens: 9, CompletionTokens: 14, TotalTokens: 23},
+		},
+		{
+			name:        "repair budget exhausted",
+			outcomes:    []generationOutcome{{response: generationResponse(invalid, 2, 3, 5)}, {response: generationResponse(invalid, 7, 11, 18)}},
+			wantStatus:  promptexec.ValidationFailed,
+			wantRepairs: 1,
+			wantCalls:   2,
+			wantRaw:     invalid,
+			wantUsage:   promptexec.TokenUsage{PromptTokens: 9, CompletionTokens: 14, TotalTokens: 23},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			client := &fakeClient{outcomes: test.outcomes}
+			adapter := newRepairAdapter(t, client, "https://repair.example/v1")
+			var preparation promptexec.Preparation
+			result, err := adapter.Execute(context.Background(), repairExecuteRequest(), func(value promptexec.Preparation, _ *promptexec.PreparationDebug) error {
+				preparation = value
+				return nil
+			})
+			if err != nil {
+				t.Fatalf("Execute() error = %v", err)
+			}
+			if preparation.Output.RepairAttempts != 1 || result == nil || result.Validation.Status != test.wantStatus || result.Validation.RepairAttempts != test.wantRepairs || string(result.RawOutput) != test.wantRaw || result.Usage != test.wantUsage {
+				t.Fatalf("preparation/result = %#v/%#v", preparation, result)
+			}
+			requests := client.allRequests()
+			if len(requests) != test.wantCalls {
+				t.Fatalf("provider requests = %d, want %d", len(requests), test.wantCalls)
+			}
+			if test.wantCalls == 2 && !reflect.DeepEqual(requests[0].Target, requests[1].Target) {
+				t.Fatalf("corrective target = %#v, want same prepared identity as %#v", requests[1].Target, requests[0].Target)
+			}
+			if result.ProfileID != preparation.ProfileID || result.BackendID != preparation.BackendID || result.ModelName != preparation.ModelName || result.PromptID != preparation.PromptID || result.PromptVersion != preparation.PromptVersion || result.PromptHash != preparation.PromptHash {
+				t.Fatalf("prepared/result identity = %#v/%#v", preparation, result)
+			}
+		})
+	}
+}
+
+func TestExecuteMapsCorrectiveGenerationError(t *testing.T) {
+	const providerBody = `{"error":{"code":"repair-code","type":"repair-type","message":"repair-message"}}`
+	calls := 0
+	server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, _ *http.Request) {
+		calls++
+		if calls == 1 {
+			writer.Header().Set("Content-Type", "application/json")
+			_, _ = fmt.Fprintf(writer, `{"choices":[{"message":{"content":%q}}],"usage":{"prompt_tokens":2,"completion_tokens":3,"total_tokens":5}}`, `{"summary":42}`)
+			return
+		}
+		writer.Header().Set("Content-Type", "application/json")
+		writer.WriteHeader(http.StatusUnprocessableEntity)
+		_, _ = writer.Write([]byte(providerBody))
+	}))
+	defer server.Close()
+
+	adapter := newRepairAdapter(t, nil, server.URL)
+	result, err := adapter.Execute(context.Background(), repairExecuteRequest(), nil)
+	if result != nil || err == nil || calls != 2 {
+		t.Fatalf("result/error/calls = %#v/%v/%d", result, err, calls)
+	}
+	var generationError *promptexec.GenerationError
+	if !errors.As(err, &generationError) || generationError.StatusCode() != http.StatusUnprocessableEntity || generationError.ProviderCode() != "repair-code" || generationError.ProviderType() != "repair-type" || generationError.ProviderMessage() != "repair-message" {
+		t.Fatalf("generation error = %#v", err)
+	}
+	if strings.Contains(err.Error(), "repair-message") || !errors.Is(err, promptkit.ErrLLMGenerate) {
+		t.Fatalf("generation error = %v", err)
+	}
+}
+
+func TestExecuteDropsOversizedGeneratedOutput(t *testing.T) {
+	client := &fakeClient{response: &promptkit.GenerateResponse{Content: strings.Repeat("x", generatedtext.MaxGeneratedTextBytes+1)}}
+	adapter := newTestAdapter(t, client)
+	request := testExecuteRequest()
+	request.CaptureDebug = true
+	result, err := adapter.Execute(context.Background(), request, nil)
+	if err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	if result == nil || result.Validation.Status != promptexec.ValidationFailed || len(result.RawOutput) != 0 || result.Debug == nil || len(result.Debug.RawOutput) != 0 {
+		t.Fatalf("execution = %#v", result)
+	}
+	if len(result.Validation.Diagnostics) != 1 || result.Validation.Diagnostics[0] != "generated output exceeds the configured size limit" {
+		t.Fatalf("diagnostics = %#v", result.Validation.Diagnostics)
+	}
+}
+
+func TestExecuteClassifiesOperationalFailures(t *testing.T) {
+	tests := []struct {
+		name     string
+		client   *fakeClient
+		context  func() (context.Context, context.CancelFunc)
+		category promptexec.ErrorCategory
+	}{
+		{
+			name:   "generation",
+			client: &fakeClient{err: errors.New("provider response body")},
+			context: func() (context.Context, context.CancelFunc) {
+				return context.WithCancel(context.Background())
+			},
+			category: promptexec.Generation,
+		},
+		{
+			name:   "canceled",
+			client: &fakeClient{block: true},
+			context: func() (context.Context, context.CancelFunc) {
+				ctx, cancel := context.WithCancel(context.Background())
+				cancel()
+				return ctx, func() {}
+			},
+			category: promptexec.Canceled,
+		},
+		{
+			name:   "deadline",
+			client: &fakeClient{block: true},
+			context: func() (context.Context, context.CancelFunc) {
+				return context.WithTimeout(context.Background(), time.Nanosecond)
+			},
+			category: promptexec.DeadlineExceeded,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			adapter := newTestAdapter(t, test.client)
+			ctx, cancel := test.context()
+			defer cancel()
+			result, err := adapter.Execute(ctx, testExecuteRequest(), nil)
+			if result != nil || err == nil || promptexec.CategoryOf(err) != test.category {
+				t.Fatalf("result/error/category = %#v/%v/%q, want %q", result, err, promptexec.CategoryOf(err), test.category)
+			}
+			if strings.Contains(err.Error(), "provider response body") {
+				t.Fatalf("error leaks provider detail: %v", err)
+			}
+		})
+	}
+}
+
+func TestClassifyPromptkitErrors(t *testing.T) {
+	tests := []struct {
+		err      error
+		category promptexec.ErrorCategory
+	}{
+		{promptkit.ErrInvalidConfig, promptexec.InvalidConfiguration},
+		{promptkit.ErrInvalidRequest, promptexec.InvalidRequest},
+		{promptkit.ErrPromptNotFound, promptexec.PromptNotFound},
+		{promptkit.ErrPromptLoad, promptexec.PromptLoad},
+		{promptkit.ErrProfileNotFound, promptexec.ProfileNotFound},
+		{promptkit.ErrProfileLoad, promptexec.ProfileLoad},
+		{promptkit.ErrAPIKeyEnvMissing, promptexec.MissingCredential},
+		{promptkit.ErrArtifactLoad, promptexec.ArtifactLoad},
+		{promptkit.ErrPromptRender, promptexec.PromptRender},
+		{promptkit.ErrLLMGenerate, promptexec.Generation},
+		{promptkit.ErrValidation, promptexec.OperationalValidation},
+		{&promptkit.CapacityError{BackendID: "local"}, promptexec.Capacity},
+	}
+	for _, test := range tests {
+		t.Run(string(test.category), func(t *testing.T) {
+			got := classifyError(test.err)
+			if promptexec.CategoryOf(got) != test.category {
+				t.Fatalf("category = %q, want %q", promptexec.CategoryOf(got), test.category)
+			}
+		})
+	}
+}
+
+func TestNewValidatesConfiguration(t *testing.T) {
+	if _, err := New(Config{ProfileDirectory: "profiles", ProfileFile: "profile.yml"}); promptexec.CategoryOf(err) != promptexec.InvalidConfiguration {
+		t.Fatalf("profile source error = %v", err)
+	}
+	if _, err := New(Config{LocalConcurrencyLimit: 1}); promptexec.CategoryOf(err) != promptexec.InvalidConfiguration {
+		t.Fatalf("local concurrency error = %v", err)
+	}
+	if _, err := New(Config{LocalEndpoint: "not a URL"}); promptexec.CategoryOf(err) != promptexec.InvalidConfiguration {
+		t.Fatalf("local endpoint error = %v", err)
+	}
+}
+
+func TestLocalBackendAndOptionalCredentialSourceBehavior(t *testing.T) {
+	t.Setenv("WEATHERREPORTER_TEST_MISSING_KEY", "")
+	profiles := testProfileDirectory(t, map[string]string{"profile.yml": `id: local-profile
+backend: local
+model: local-model
+`})
+	adapter, err := newAdapterForTest(Config{
+		ProfileDirectory:      profiles,
+		LocalEndpoint:         "https://local.example/v1",
+		LocalConcurrencyLimit: 1,
+	}, &fakeClient{})
+	if err != nil {
+		t.Fatalf("newAdapterForTest(local) error = %v", err)
+	}
+	profile, err := adapter.InspectProfile(context.Background(), "local-profile")
+	if err != nil || profile.BackendID != promptkit.BackendLocal || profile.ModelName != "local-model" {
+		t.Fatalf("local profile/error = %#v/%v", profile, err)
+	}
+	if got := classifyError(&promptkit.CapacityError{BackendID: promptkit.BackendLocal}); promptexec.CategoryOf(got) != promptexec.Capacity {
+		t.Fatalf("capacity classification = %v", got)
+	}
+
+	credentialProfiles := testProfileDirectory(t, map[string]string{"profile.yml": `id: credential-profile
+endpoint: https://profile.example/v1
+model: test-model
+api_key_env: WEATHERREPORTER_TEST_MISSING_KEY
+`})
+	client := &fakeClient{response: validResponse()}
+	credentialAdapter, err := newAdapterForTest(Config{ProfileDirectory: credentialProfiles}, client)
+	if err != nil {
+		t.Fatalf("newAdapterForTest(credential) error = %v", err)
+	}
+	credentialProfile, err := credentialAdapter.InspectProfile(context.Background(), "credential-profile")
+	if err != nil || credentialProfile.CredentialRequired || credentialProfile.APIKeyEnv != "WEATHERREPORTER_TEST_MISSING_KEY" {
+		t.Fatalf("credential profile/error = %#v/%v", credentialProfile, err)
+	}
+	request := testExecuteRequest()
+	request.ProfileID = "credential-profile"
+	result, err := credentialAdapter.Execute(context.Background(), request, nil)
+	if err != nil || result == nil || client.callCount() != 1 {
+		t.Fatalf("credential result/error/calls = %#v/%v/%d", result, err, client.callCount())
+	}
+}
+
+func newTestAdapter(t *testing.T, client promptkit.LLMClient) *Adapter {
+	return newTestAdapterWithOptions(t, client)
+}
+
+func assertProfile(t *testing.T, adapter *Adapter, id string, backend string, model string) {
+	t.Helper()
+	profile, err := adapter.InspectProfile(context.Background(), id)
+	if err != nil {
+		t.Fatalf("InspectProfile(%q) error = %v", id, err)
+	}
+	if profile.ProfileID != id || profile.BackendID != backend || profile.ModelName != model {
+		t.Fatalf("profile = %#v, want %q with backend/model %q/%q", profile, id, backend, model)
+	}
+}
+
+func newTestAdapterWithOptions(t *testing.T, client promptkit.LLMClient, options ...promptkit.Option) *Adapter {
+	t.Helper()
+	profiles := testProfileDirectory(t, map[string]string{"profile.yml": `id: test-profile
+endpoint: https://profile.example/v1
+model: test-model
+temperature: 0.2
+max_tokens: 300
+top_p: 1
+timeout_seconds: 30
+`})
+	options = append(options, promptkit.WithLLMClient(client))
+	adapter, err := newAdapter(Config{ProfileDirectory: profiles, Timeout: time.Second}, options...)
+	if err != nil {
+		t.Fatalf("newAdapter() error = %v", err)
+	}
+	return adapter
+}
+
+func testProfileDirectory(t *testing.T, profiles map[string]string) string {
+	t.Helper()
+	directory := t.TempDir()
+	for name, profile := range profiles {
+		if err := os.WriteFile(filepath.Join(directory, name), []byte(profile), 0o600); err != nil {
+			t.Fatalf("write profile: %v", err)
+		}
+	}
+	return directory
+}
+
+func writeProfileFile(t *testing.T, profile string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "profile.yml")
+	if err := os.WriteFile(path, []byte(profile), 0o600); err != nil {
+		t.Fatalf("write profile: %v", err)
+	}
+	return path
+}
+
+func testExecuteRequest() promptexec.ExecuteRequest {
+	return promptexec.ExecuteRequest{
+		PromptID:      "weather.daily_generated_text",
+		PromptVersion: "2.1.0",
+		ProfileID:     "test-profile",
+		DataPackage:   []byte("report:\n  id: daily\nbriefing: {}\n"),
+	}
+}
+
+func validResponse() *promptkit.GenerateResponse {
+	return &promptkit.GenerateResponse{
+		Content: `{"summary":"A quiet day is expected.","forecast_discussion":["High pressure keeps conditions settled."],"precipitation_timing":""}`,
+		Usage:   promptkit.TokenUsage{PromptTokens: 12, CompletionTokens: 8, TotalTokens: 20},
+	}
+}
+
+func generationResponse(content string, promptTokens int, completionTokens int, totalTokens int) *promptkit.GenerateResponse {
+	return &promptkit.GenerateResponse{
+		Content: content,
+		Usage: promptkit.TokenUsage{
+			PromptTokens:     promptTokens,
+			CompletionTokens: completionTokens,
+			TotalTokens:      totalTokens,
+		},
+	}
+}
+
+func newRepairAdapter(t *testing.T, client promptkit.LLMClient, endpoint string) *Adapter {
+	t.Helper()
+	profiles := testProfileDirectory(t, map[string]string{"profile.yml": "id: repair-profile\nendpoint: " + endpoint + "\nmodel: repair-model\n"})
+	options := []promptkit.Option{
+		promptkit.WithPromptFS(fstest.MapFS{
+			"repair.yml": &fstest.MapFile{Data: []byte(`id: weather.repair
+version: "1.0.0"
+default_profile: repair-profile
+inputs:
+  - name: data_package
+    required: true
+    content_type: application/yaml
+messages:
+  - role: user
+    content: "{{input \"data_package\"}}"
+output:
+  format: json
+  validation_mode: json_schema
+  schema_path: repair.schema.json
+  repair_attempts: 1
+`)}}, "."),
+		promptkit.WithSchemaFS(fstest.MapFS{
+			"repair.schema.json": &fstest.MapFile{Data: []byte(`{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"],"additionalProperties":false}`)},
+		}, "."),
+	}
+	if client != nil {
+		options = append(options, promptkit.WithLLMClient(client))
+	}
+	adapter, err := newAdapter(Config{ProfileDirectory: profiles}, options...)
+	if err != nil {
+		t.Fatalf("newAdapter() error = %v", err)
+	}
+	return adapter
+}
+
+func repairExecuteRequest() promptexec.ExecuteRequest {
+	return promptexec.ExecuteRequest{
+		PromptID:      "weather.repair",
+		PromptVersion: "1.0.0",
+		ProfileID:     "repair-profile",
+		DataPackage:   []byte("report: repair\n"),
+	}
+}
+
+func hourlyValidResponse() *promptkit.GenerateResponse {
+	return &promptkit.GenerateResponse{
+		Content: `{"summary":"A quiet hour is expected.","forecast_discussion":"Conditions remain settled.","precipitation_timing":""}`,
+		Usage:   promptkit.TokenUsage{PromptTokens: 12, CompletionTokens: 8, TotalTokens: 20},
+	}
+}

internal/adapters/scriptorium/runner.go

@@ -1,338 +0,0 @@
-// Package scriptorium adapts the external scriptorium CLI.
-package scriptorium
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"os/exec"
-	"time"
-)
-
-const maxCapturedOutputBytes = 1024 * 1024
-
-type CommandRunner interface {
-	Run(ctx context.Context, name string, args []string, timeout time.Duration) (CommandResult, error)
-}
-
-type CommandResult struct {
-	Stdout          []byte
-	Stderr          []byte
-	StdoutTruncated bool
-	StderrTruncated bool
-	ExitCode        int
-}
-
-type ExecRunner struct{}
-
-func (ExecRunner) Run(ctx context.Context, name string, args []string, timeout time.Duration) (CommandResult, error) {
-	runCtx := ctx
-	cancel := func() {}
-	if timeout > 0 {
-		runCtx, cancel = context.WithTimeout(ctx, timeout)
-	}
-	defer cancel()
-
-	cmd := exec.CommandContext(runCtx, name, args...)
-	stdout := &limitedBuffer{limit: maxCapturedOutputBytes}
-	stderr := &limitedBuffer{limit: maxCapturedOutputBytes}
-	cmd.Stdout = stdout
-	cmd.Stderr = stderr
-	err := cmd.Run()
-	result := CommandResult{
-		Stdout:          stdout.Bytes(),
-		Stderr:          stderr.Bytes(),
-		StdoutTruncated: stdout.Truncated(),
-		StderrTruncated: stderr.Truncated(),
-		ExitCode:        0,
-	}
-	if err == nil {
-		return result, nil
-	}
-	if runCtx.Err() != nil {
-		return result, runCtx.Err()
-	}
-	if exitErr, ok := err.(*exec.ExitError); ok {
-		result.ExitCode = exitErr.ExitCode()
-		return result, nil
-	}
-	return result, err
-}
-
-type Runner struct {
-	Binary     string
-	ConfigPath string
-	Profile    string
-	Timeout    time.Duration
-	ExtraArgs  []string
-	Commands   CommandRunner
-}
-
-type RenderRequest struct {
-	PromptID        string
-	DataPackagePath string
-}
-
-type RunRequest struct {
-	PromptID        string
-	DataPackagePath string
-	OutputPath      string
-}
-
-type StructuredRunRequest struct {
-	PromptID        string
-	DataPackagePath string
-	OutputPath      string
-}
-
-type RenderResult struct {
-	Command         []string `json:"command"`
-	Stdout          string   `json:"stdout"`
-	Stderr          string   `json:"stderr"`
-	StdoutTruncated bool     `json:"stdoutTruncated,omitempty"`
-	StderrTruncated bool     `json:"stderrTruncated,omitempty"`
-	ExitCode        int      `json:"exitCode"`
-}
-
-type RunResult struct {
-	Command         []string `json:"command"`
-	Stdout          string   `json:"stdout"`
-	Stderr          string   `json:"stderr"`
-	StdoutTruncated bool     `json:"stdoutTruncated,omitempty"`
-	StderrTruncated bool     `json:"stderrTruncated,omitempty"`
-	ExitCode        int      `json:"exitCode"`
-	OutputPath      string   `json:"outputPath"`
-}
-
-type StructuredRunResult struct {
-	Command         []string `json:"command"`
-	Stdout          string   `json:"stdout"`
-	Stderr          string   `json:"stderr"`
-	StdoutTruncated bool     `json:"stdoutTruncated,omitempty"`
-	StderrTruncated bool     `json:"stderrTruncated,omitempty"`
-	ExitCode        int      `json:"exitCode"`
-	OutputPath      string   `json:"outputPath"`
-}
-
-func (r Runner) Render(ctx context.Context, req RenderRequest) (*RenderResult, error) {
-	if req.PromptID == "" {
-		return nil, fmt.Errorf("prompt id is required")
-	}
-	if req.DataPackagePath == "" {
-		return nil, fmt.Errorf("data package path is required")
-	}
-	execution, err := r.execute(ctx, r.renderArgs(req))
-	if err != nil {
-		return nil, fmt.Errorf("run scriptorium render: %w", err)
-	}
-	result := &RenderResult{
-		Command:         execution.argv(),
-		Stdout:          string(execution.result.Stdout),
-		Stderr:          string(execution.result.Stderr),
-		StdoutTruncated: execution.result.StdoutTruncated,
-		StderrTruncated: execution.result.StderrTruncated,
-		ExitCode:        execution.result.ExitCode,
-	}
-	if execution.result.ExitCode != 0 {
-		return result, fmt.Errorf("scriptorium render exited with code %d: %s", execution.result.ExitCode, result.Stderr)
-	}
-	return result, nil
-}
-
-func (r Runner) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
-	result, err := r.executeRun(ctx, outputRunRequest{
-		PromptID:        req.PromptID,
-		DataPackagePath: req.DataPackagePath,
-		OutputPath:      req.OutputPath,
-	}, "run scriptorium", "scriptorium run")
-	if err != nil {
-		if result == nil {
-			return nil, err
-		}
-		return result.runResult(), err
-	}
-	return result.runResult(), nil
-}
-
-func (r Runner) StructuredRun(ctx context.Context, req StructuredRunRequest) (*StructuredRunResult, error) {
-	result, err := r.executeRun(ctx, outputRunRequest{
-		PromptID:        req.PromptID,
-		DataPackagePath: req.DataPackagePath,
-		OutputPath:      req.OutputPath,
-	}, "run scriptorium structured output", "scriptorium structured run")
-	if err != nil {
-		if result == nil {
-			return nil, err
-		}
-		return result.structuredRunResult(), err
-	}
-	return result.structuredRunResult(), nil
-}
-
-func (result outputRunResult) runResult() *RunResult {
-	return &RunResult{
-		Command:         result.Command,
-		Stdout:          result.Stdout,
-		Stderr:          result.Stderr,
-		StdoutTruncated: result.StdoutTruncated,
-		StderrTruncated: result.StderrTruncated,
-		ExitCode:        result.ExitCode,
-		OutputPath:      result.OutputPath,
-	}
-}
-
-func (result outputRunResult) structuredRunResult() *StructuredRunResult {
-	return &StructuredRunResult{
-		Command:         result.Command,
-		Stdout:          result.Stdout,
-		Stderr:          result.Stderr,
-		StdoutTruncated: result.StdoutTruncated,
-		StderrTruncated: result.StderrTruncated,
-		ExitCode:        result.ExitCode,
-		OutputPath:      result.OutputPath,
-	}
-}
-
-type execution struct {
-	binary string
-	args   []string
-	result CommandResult
-}
-
-type outputRunRequest struct {
-	PromptID        string
-	DataPackagePath string
-	OutputPath      string
-}
-
-type outputRunResult struct {
-	Command         []string
-	Stdout          string
-	Stderr          string
-	StdoutTruncated bool
-	StderrTruncated bool
-	ExitCode        int
-	OutputPath      string
-}
-
-func (r Runner) executeRun(ctx context.Context, req outputRunRequest, executeContext string, exitContext string) (*outputRunResult, error) {
-	if req.PromptID == "" {
-		return nil, fmt.Errorf("prompt id is required")
-	}
-	if req.DataPackagePath == "" {
-		return nil, fmt.Errorf("data package path is required")
-	}
-	if req.OutputPath == "" {
-		return nil, fmt.Errorf("output path is required")
-	}
-	execution, err := r.execute(ctx, r.runArgs(RunRequest{
-		PromptID:        req.PromptID,
-		DataPackagePath: req.DataPackagePath,
-		OutputPath:      req.OutputPath,
-	}))
-	if err != nil {
-		return nil, fmt.Errorf("%s: %w", executeContext, err)
-	}
-	result := &outputRunResult{
-		Command:         execution.argv(),
-		Stdout:          string(execution.result.Stdout),
-		Stderr:          string(execution.result.Stderr),
-		StdoutTruncated: execution.result.StdoutTruncated,
-		StderrTruncated: execution.result.StderrTruncated,
-		ExitCode:        execution.result.ExitCode,
-		OutputPath:      req.OutputPath,
-	}
-	if execution.result.ExitCode != 0 {
-		return result, fmt.Errorf("%s exited with code %d: %s", exitContext, execution.result.ExitCode, result.Stderr)
-	}
-	return result, nil
-}
-
-func (r Runner) execute(ctx context.Context, args []string) (execution, error) {
-	binary := r.Binary
-	if binary == "" {
-		binary = "scriptorium"
-	}
-	commands := r.Commands
-	if commands == nil {
-		commands = ExecRunner{}
-	}
-	result, err := commands.Run(ctx, binary, args, r.Timeout)
-	if err != nil {
-		return execution{}, err
-	}
-	return execution{binary: binary, args: args, result: result}, nil
-}
-
-func (e execution) argv() []string {
-	return append([]string{e.binary}, e.args...)
-}
-
-func (r Runner) renderArgs(req RenderRequest) []string {
-	args := []string{"render"}
-	if r.ConfigPath != "" {
-		args = append(args, "--config", r.ConfigPath)
-	}
-	if r.Profile != "" {
-		args = append(args, "--profile", r.Profile)
-	}
-	args = append(args,
-		"--prompt", req.PromptID,
-		"--input", "data_package="+req.DataPackagePath,
-		"--format", "json",
-	)
-	args = append(args, r.ExtraArgs...)
-	return args
-}
-
-func (r Runner) runArgs(req RunRequest) []string {
-	args := []string{"run"}
-	if r.ConfigPath != "" {
-		args = append(args, "--config", r.ConfigPath)
-	}
-	if r.Profile != "" {
-		args = append(args, "--profile", r.Profile)
-	}
-	args = append(args,
-		"--prompt", req.PromptID,
-		"--input", "data_package="+req.DataPackagePath,
-		"--out", req.OutputPath,
-	)
-	args = append(args, r.ExtraArgs...)
-	return args
-}
-
-type limitedBuffer struct {
-	data      []byte
-	limit     int
-	truncated bool
-}
-
-func (b *limitedBuffer) Write(p []byte) (int, error) {
-	if b.limit <= 0 {
-		b.truncated = true
-		return len(p), nil
-	}
-	remaining := b.limit - len(b.data)
-	if remaining <= 0 {
-		b.truncated = true
-		return len(p), nil
-	}
-	if len(p) > remaining {
-		b.data = append(b.data, p[:remaining]...)
-		b.truncated = true
-		return len(p), nil
-	}
-	b.data = append(b.data, p...)
-	return len(p), nil
-}
-
-func (b *limitedBuffer) Bytes() []byte {
-	return append([]byte{}, b.data...)
-}
-
-func (b *limitedBuffer) Truncated() bool {
-	return b.truncated
-}
-
-var _ io.Writer = (*limitedBuffer)(nil)

internal/adapters/scriptorium/runner_test.go

@@ -1,544 +0,0 @@
-package scriptorium
-
-import (
-	"context"
-	"fmt"
-	"reflect"
-	"strings"
-	"testing"
-	"time"
-)
-
-func TestRenderConstructsCommand(t *testing.T) {
-	commands := &fakeCommands{result: CommandResult{Stdout: []byte(`{"ok":true}`)}}
-	runner := Runner{
-		Binary:     "/usr/local/bin/scriptorium",
-		ConfigPath: "/etc/scriptorium.yml",
-		Profile:    "weather",
-		Timeout:    time.Minute,
-		Commands:   commands,
-	}
-
-	result, err := runner.Render(context.Background(), RenderRequest{
-		PromptID:        "weather.markdown_report",
-		DataPackagePath: "/tmp/data_package.yaml",
-	})
-	if err != nil {
-		t.Fatalf("Render() error = %v", err)
-	}
-
-	wantArgs := []string{
-		"render",
-		"--config", "/etc/scriptorium.yml",
-		"--profile", "weather",
-		"--prompt", "weather.markdown_report",
-		"--input", "data_package=/tmp/data_package.yaml",
-		"--format", "json",
-	}
-	if commands.name != "/usr/local/bin/scriptorium" {
-		t.Fatalf("command name = %q, want custom binary", commands.name)
-	}
-	if !reflect.DeepEqual(commands.args, wantArgs) {
-		t.Fatalf("args = %#v, want %#v", commands.args, wantArgs)
-	}
-	if !reflect.DeepEqual(result.Command, append([]string{"/usr/local/bin/scriptorium"}, wantArgs...)) {
-		t.Fatalf("result command = %#v, want full argv", result.Command)
-	}
-}
-
-func TestRenderReturnsResultForNonzeroExit(t *testing.T) {
-	runner := Runner{
-		Commands: &fakeCommands{
-			result: CommandResult{
-				Stderr:   []byte("missing input"),
-				ExitCode: 1,
-			},
-		},
-	}
-
-	result, err := runner.Render(context.Background(), RenderRequest{
-		PromptID:        "weather.markdown_report",
-		DataPackagePath: "/tmp/data_package.yaml",
-	})
-	if err == nil {
-		t.Fatal("Render() error = nil, want nonzero exit error")
-	}
-	if result == nil {
-		t.Fatal("Render() result = nil, want captured result")
-	}
-	if result.ExitCode != 1 {
-		t.Fatalf("ExitCode = %d, want 1", result.ExitCode)
-	}
-	if !strings.Contains(err.Error(), "missing input") {
-		t.Fatalf("error = %q, want stderr context", err.Error())
-	}
-}
-
-func TestRunConstructsCommand(t *testing.T) {
-	commands := &fakeCommands{result: CommandResult{Stderr: []byte("wrote report")}}
-	runner := Runner{
-		Binary:     "/usr/local/bin/scriptorium",
-		ConfigPath: "/etc/scriptorium.yml",
-		Profile:    "weather",
-		Timeout:    45 * time.Second,
-		Commands:   commands,
-	}
-
-	result, err := runner.Run(context.Background(), RunRequest{
-		PromptID:        "weather.markdown_report",
-		DataPackagePath: "/tmp/data_package.yaml",
-		OutputPath:      "/tmp/daily.md",
-	})
-	if err != nil {
-		t.Fatalf("Run() error = %v", err)
-	}
-
-	wantArgs := []string{
-		"run",
-		"--config", "/etc/scriptorium.yml",
-		"--profile", "weather",
-		"--prompt", "weather.markdown_report",
-		"--input", "data_package=/tmp/data_package.yaml",
-		"--out", "/tmp/daily.md",
-	}
-	if commands.name != "/usr/local/bin/scriptorium" {
-		t.Fatalf("command name = %q, want custom binary", commands.name)
-	}
-	if !reflect.DeepEqual(commands.args, wantArgs) {
-		t.Fatalf("args = %#v, want %#v", commands.args, wantArgs)
-	}
-	if commands.timeout != 45*time.Second {
-		t.Fatalf("timeout = %s, want 45s", commands.timeout)
-	}
-	if !reflect.DeepEqual(result.Command, append([]string{"/usr/local/bin/scriptorium"}, wantArgs...)) {
-		t.Fatalf("result command = %#v, want full argv", result.Command)
-	}
-	if result.OutputPath != "/tmp/daily.md" {
-		t.Fatalf("OutputPath = %q, want /tmp/daily.md", result.OutputPath)
-	}
-}
-
-func TestRunReturnsResultForValidationExit(t *testing.T) {
-	runner := Runner{
-		Commands: &fakeCommands{
-			result: CommandResult{
-				Stdout:   []byte("# Daily Report\n"),
-				Stderr:   []byte("validation failed"),
-				ExitCode: 2,
-			},
-		},
-	}
-
-	result, err := runner.Run(context.Background(), RunRequest{
-		PromptID:        "weather.markdown_report",
-		DataPackagePath: "/tmp/data_package.yaml",
-		OutputPath:      "/tmp/daily.md",
-	})
-	if err == nil {
-		t.Fatal("Run() error = nil, want nonzero exit error")
-	}
-	if result == nil {
-		t.Fatal("Run() result = nil, want captured result")
-	}
-	if result.ExitCode != 2 {
-		t.Fatalf("ExitCode = %d, want 2", result.ExitCode)
-	}
-	if !strings.Contains(err.Error(), "validation failed") {
-		t.Fatalf("error = %q, want stderr context", err.Error())
-	}
-}
-
-func TestStructuredRunConstructsCommandWithoutSchemaFlags(t *testing.T) {
-	commands := &fakeCommands{result: CommandResult{
-		Stdout:          []byte(`{"summary":"ok"}`),
-		Stderr:          []byte("wrote generated text"),
-		StdoutTruncated: true,
-	}}
-	runner := Runner{
-		Binary:     "/usr/local/bin/scriptorium",
-		ConfigPath: "/etc/scriptorium.yml",
-		Profile:    "weather",
-		Timeout:    30 * time.Second,
-		Commands:   commands,
-	}
-
-	result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
-		PromptID:        "weather.hourly_generated_text",
-		DataPackagePath: "/tmp/data_package.hourly.yaml",
-		OutputPath:      "/tmp/generated_text_raw.hourly.json",
-	})
-	if err != nil {
-		t.Fatalf("StructuredRun() error = %v", err)
-	}
-
-	wantArgs := []string{
-		"run",
-		"--config", "/etc/scriptorium.yml",
-		"--profile", "weather",
-		"--prompt", "weather.hourly_generated_text",
-		"--input", "data_package=/tmp/data_package.hourly.yaml",
-		"--out", "/tmp/generated_text_raw.hourly.json",
-	}
-	if commands.name != "/usr/local/bin/scriptorium" {
-		t.Fatalf("command name = %q, want custom binary", commands.name)
-	}
-	if !reflect.DeepEqual(commands.args, wantArgs) {
-		t.Fatalf("args = %#v, want %#v", commands.args, wantArgs)
-	}
-	for _, disallowed := range []string{"--format", "--schema", "--schema-path", "--json-schema"} {
-		if containsArg(commands.args, disallowed) {
-			t.Fatalf("args = %#v, should not include %q", commands.args, disallowed)
-		}
-	}
-	if commands.timeout != 30*time.Second {
-		t.Fatalf("timeout = %s, want 30s", commands.timeout)
-	}
-	if !reflect.DeepEqual(result.Command, append([]string{"/usr/local/bin/scriptorium"}, wantArgs...)) {
-		t.Fatalf("result command = %#v, want full argv", result.Command)
-	}
-	if result.Stdout != `{"summary":"ok"}` || result.Stderr != "wrote generated text" || !result.StdoutTruncated {
-		t.Fatalf("result = %#v, want captured output and truncation flags", result)
-	}
-	if result.OutputPath != "/tmp/generated_text_raw.hourly.json" {
-		t.Fatalf("OutputPath = %q, want generated text raw path", result.OutputPath)
-	}
-}
-
-func TestStructuredRunReturnsResultForNonzeroExit(t *testing.T) {
-	runner := Runner{
-		Commands: &fakeCommands{
-			result: CommandResult{
-				Stdout:   []byte(`{"summary":"partial"}`),
-				Stderr:   []byte("structured output failed"),
-				ExitCode: 3,
-			},
-		},
-	}
-
-	result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
-		PromptID:        "weather.hourly_generated_text",
-		DataPackagePath: "/tmp/data_package.hourly.yaml",
-		OutputPath:      "/tmp/generated_text_raw.hourly.json",
-	})
-	if err == nil {
-		t.Fatal("StructuredRun() error = nil, want nonzero exit error")
-	}
-	if result == nil {
-		t.Fatal("StructuredRun() result = nil, want captured result")
-	}
-	if result.ExitCode != 3 {
-		t.Fatalf("ExitCode = %d, want 3", result.ExitCode)
-	}
-	if result.Stdout != `{"summary":"partial"}` || result.OutputPath != "/tmp/generated_text_raw.hourly.json" {
-		t.Fatalf("result = %#v, want captured result fields", result)
-	}
-	if !strings.Contains(err.Error(), "structured output failed") {
-		t.Fatalf("error = %q, want stderr context", err.Error())
-	}
-}
-
-func TestOutputRunsPreserveCapturedResultFields(t *testing.T) {
-	type commonResult struct {
-		Command         []string
-		Stdout          string
-		Stderr          string
-		StdoutTruncated bool
-		StderrTruncated bool
-		ExitCode        int
-		OutputPath      string
-	}
-	tests := []struct {
-		name string
-		run  func(Runner) (*commonResult, error)
-	}{
-		{
-			name: "Run",
-			run: func(runner Runner) (*commonResult, error) {
-				result, err := runner.Run(context.Background(), RunRequest{
-					PromptID:        "weather.markdown_report",
-					DataPackagePath: "/tmp/data_package.yaml",
-					OutputPath:      "/tmp/report.md",
-				})
-				if result == nil {
-					return nil, err
-				}
-				return &commonResult{
-					Command:         result.Command,
-					Stdout:          result.Stdout,
-					Stderr:          result.Stderr,
-					StdoutTruncated: result.StdoutTruncated,
-					StderrTruncated: result.StderrTruncated,
-					ExitCode:        result.ExitCode,
-					OutputPath:      result.OutputPath,
-				}, err
-			},
-		},
-		{
-			name: "StructuredRun",
-			run: func(runner Runner) (*commonResult, error) {
-				result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
-					PromptID:        "weather.markdown_report",
-					DataPackagePath: "/tmp/data_package.yaml",
-					OutputPath:      "/tmp/report.md",
-				})
-				if result == nil {
-					return nil, err
-				}
-				return &commonResult{
-					Command:         result.Command,
-					Stdout:          result.Stdout,
-					Stderr:          result.Stderr,
-					StdoutTruncated: result.StdoutTruncated,
-					StderrTruncated: result.StderrTruncated,
-					ExitCode:        result.ExitCode,
-					OutputPath:      result.OutputPath,
-				}, err
-			},
-		},
-	}
-
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			commands := &fakeCommands{result: CommandResult{
-				Stdout:          []byte("captured stdout"),
-				Stderr:          []byte("captured stderr"),
-				StdoutTruncated: true,
-				StderrTruncated: true,
-			}}
-			runner := Runner{
-				Binary:     "/usr/local/bin/scriptorium",
-				ConfigPath: "/etc/scriptorium.yml",
-				Profile:    "weather",
-				Timeout:    15 * time.Second,
-				Commands:   commands,
-			}
-
-			result, err := test.run(runner)
-			if err != nil {
-				t.Fatalf("%s error = %v", test.name, err)
-			}
-			wantArgs := []string{
-				"run",
-				"--config", "/etc/scriptorium.yml",
-				"--profile", "weather",
-				"--prompt", "weather.markdown_report",
-				"--input", "data_package=/tmp/data_package.yaml",
-				"--out", "/tmp/report.md",
-			}
-			if !reflect.DeepEqual(commands.args, wantArgs) {
-				t.Fatalf("args = %#v, want %#v", commands.args, wantArgs)
-			}
-			if commands.timeout != 15*time.Second {
-				t.Fatalf("timeout = %s, want 15s", commands.timeout)
-			}
-			if !reflect.DeepEqual(result.Command, append([]string{"/usr/local/bin/scriptorium"}, wantArgs...)) {
-				t.Fatalf("Command = %#v, want full argv", result.Command)
-			}
-			if result.Stdout != "captured stdout" || result.Stderr != "captured stderr" {
-				t.Fatalf("captured output = %q/%q, want stdout/stderr", result.Stdout, result.Stderr)
-			}
-			if !result.StdoutTruncated || !result.StderrTruncated {
-				t.Fatalf("truncation flags = %t/%t, want both true", result.StdoutTruncated, result.StderrTruncated)
-			}
-			if result.ExitCode != 0 || result.OutputPath != "/tmp/report.md" {
-				t.Fatalf("result = %#v, want exit 0 and output path", result)
-			}
-		})
-	}
-}
-
-func TestOutputRunsReturnCapturedResultForNonzeroExit(t *testing.T) {
-	type commonResult struct {
-		Stdout          string
-		Stderr          string
-		StderrTruncated bool
-		ExitCode        int
-		OutputPath      string
-	}
-	tests := []struct {
-		name    string
-		run     func(Runner) (*commonResult, error)
-		wantErr string
-	}{
-		{
-			name: "Run",
-			run: func(runner Runner) (*commonResult, error) {
-				result, err := runner.Run(context.Background(), RunRequest{
-					PromptID:        "weather.markdown_report",
-					DataPackagePath: "/tmp/data_package.yaml",
-					OutputPath:      "/tmp/report.md",
-				})
-				if result == nil {
-					return nil, err
-				}
-				return &commonResult{
-					Stdout:          result.Stdout,
-					Stderr:          result.Stderr,
-					StderrTruncated: result.StderrTruncated,
-					ExitCode:        result.ExitCode,
-					OutputPath:      result.OutputPath,
-				}, err
-			},
-			wantErr: "scriptorium run exited with code 7: captured stderr",
-		},
-		{
-			name: "StructuredRun",
-			run: func(runner Runner) (*commonResult, error) {
-				result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
-					PromptID:        "weather.markdown_report",
-					DataPackagePath: "/tmp/data_package.yaml",
-					OutputPath:      "/tmp/report.md",
-				})
-				if result == nil {
-					return nil, err
-				}
-				return &commonResult{
-					Stdout:          result.Stdout,
-					Stderr:          result.Stderr,
-					StderrTruncated: result.StderrTruncated,
-					ExitCode:        result.ExitCode,
-					OutputPath:      result.OutputPath,
-				}, err
-			},
-			wantErr: "scriptorium structured run exited with code 7: captured stderr",
-		},
-	}
-
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			runner := Runner{
-				Commands: &fakeCommands{result: CommandResult{
-					Stdout:          []byte("captured stdout"),
-					Stderr:          []byte("captured stderr"),
-					StderrTruncated: true,
-					ExitCode:        7,
-				}},
-			}
-
-			result, err := test.run(runner)
-			if err == nil {
-				t.Fatalf("%s error = nil, want nonzero exit error", test.name)
-			}
-			if result == nil {
-				t.Fatalf("%s result = nil, want captured result", test.name)
-			}
-			if err.Error() != test.wantErr {
-				t.Fatalf("%s error = %q, want %q", test.name, err.Error(), test.wantErr)
-			}
-			if result.Stdout != "captured stdout" || result.Stderr != "captured stderr" || !result.StderrTruncated {
-				t.Fatalf("captured result = %#v, want stdout/stderr/truncation", result)
-			}
-			if result.ExitCode != 7 || result.OutputPath != "/tmp/report.md" {
-				t.Fatalf("result = %#v, want exit 7 and output path", result)
-			}
-		})
-	}
-}
-
-func TestOutputRunsValidateRequiredFieldsBeforeExecution(t *testing.T) {
-	tests := []struct {
-		name string
-		run  func(Runner, string, string, string) error
-	}{
-		{
-			name: "Run",
-			run: func(runner Runner, promptID string, dataPackagePath string, outputPath string) error {
-				result, err := runner.Run(context.Background(), RunRequest{
-					PromptID:        promptID,
-					DataPackagePath: dataPackagePath,
-					OutputPath:      outputPath,
-				})
-				if result != nil {
-					return fmt.Errorf("result = %#v, want nil", result)
-				}
-				return err
-			},
-		},
-		{
-			name: "StructuredRun",
-			run: func(runner Runner, promptID string, dataPackagePath string, outputPath string) error {
-				result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
-					PromptID:        promptID,
-					DataPackagePath: dataPackagePath,
-					OutputPath:      outputPath,
-				})
-				if result != nil {
-					return fmt.Errorf("result = %#v, want nil", result)
-				}
-				return err
-			},
-		},
-	}
-	cases := []struct {
-		name            string
-		promptID        string
-		dataPackagePath string
-		outputPath      string
-		want            string
-	}{
-		{
-			name:            "prompt id",
-			dataPackagePath: "/tmp/data_package.yaml",
-			outputPath:      "/tmp/report.md",
-			want:            "prompt id is required",
-		},
-		{
-			name:       "data package path",
-			promptID:   "weather.markdown_report",
-			outputPath: "/tmp/report.md",
-			want:       "data package path is required",
-		},
-		{
-			name:            "output path",
-			promptID:        "weather.markdown_report",
-			dataPackagePath: "/tmp/data_package.yaml",
-			want:            "output path is required",
-		},
-	}
-
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			for _, tc := range cases {
-				t.Run(tc.name, func(t *testing.T) {
-					commands := &fakeCommands{}
-					err := test.run(Runner{Commands: commands}, tc.promptID, tc.dataPackagePath, tc.outputPath)
-					if err == nil {
-						t.Fatalf("%s error = nil, want validation error", test.name)
-					}
-					if !strings.Contains(err.Error(), tc.want) {
-						t.Fatalf("%s error = %v, want %q", test.name, err, tc.want)
-					}
-					if commands.calls != 0 {
-						t.Fatalf("commands calls = %d, want no subprocess execution", commands.calls)
-					}
-				})
-			}
-		})
-	}
-}
-
-type fakeCommands struct {
-	name    string
-	args    []string
-	timeout time.Duration
-	result  CommandResult
-	err     error
-	calls   int
-}
-
-func (f *fakeCommands) Run(_ context.Context, name string, args []string, timeout time.Duration) (CommandResult, error) {
-	f.calls++
-	f.name = name
-	f.args = append([]string{}, args...)
-	f.timeout = timeout
-	return f.result, f.err
-}
-
-func containsArg(args []string, want string) bool {
-	for _, arg := range args {
-		if arg == want {
-			return true
-		}
-	}
-	return false
-}

internal/adapters/weatherapi/client.go

@@ -7,6 +7,7 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -14,24 +15,28 @@ import (
 	"path"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/fileutil"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
 )
 
 const (
 	convectiveOutlooksEndpoint  = "/outlooks/convective"
-	sourceSPCConvectiveOutlooks = "spc_convective_outlooks"
+	currentConditionsEndpoint   = "/conditions/current"
+	sourceSPCConvectiveOutlooks = config.MissingSourceSPCConvectiveOutlooks
 
-	defaultWarmupEndpoint  = "/conditions/current"
+	defaultWarmupEndpoint  = currentConditionsEndpoint
 	defaultWarmupAttempts  = 3
 	defaultWarmupDelay     = time.Second
 	defaultFetchAttempts   = 2
 	defaultFetchRetryDelay = time.Second
+	maxResponseBodyBytes   = 10 << 20
 )
 
+var errResponseBodyTooLarge = errors.New("response exceeds 10 MiB limit")
+
 type Client struct {
 	baseURL       *url.URL
 	httpClient    *http.Client
@@ -75,6 +80,9 @@ func New(cfg config.Config, opts ...Option) (*Client, error) {
 	if err != nil || baseURL.Scheme == "" || baseURL.Host == "" {
 		return nil, fmt.Errorf("weather_api.base_url must be an absolute URL")
 	}
+	if !strings.EqualFold(baseURL.Scheme, "http") && !strings.EqualFold(baseURL.Scheme, "https") {
+		return nil, fmt.Errorf("weather_api.base_url must use http or https")
+	}
 
 	timeout := cfg.WeatherAPI.Timeout
 	if timeout <= 0 {
@@ -106,49 +114,32 @@ func New(cfg config.Config, opts ...Option) (*Client, error) {
 }
 
 func (c *Client) FetchBundle(ctx context.Context) (*weatherdata.Bundle, error) {
-	if err := c.warmup(ctx); err != nil {
+	warmup, err := c.warmup(ctx)
+	if err != nil {
 		return nil, err
 	}
 
 	fetchedAt := c.now()
 	builder := bundleBuilder{
-		client:    c,
+		client: c,
-		bundle:    &weatherdata.Bundle{FetchedAt: fetchedAt},
+		bundle: &weatherdata.Bundle{FetchedAt: fetchedAt},
-		fetchedAt: fetchedAt,
 	}
 
-	if err := builder.fetchObservation(ctx); err != nil {
+	for _, acquired := range builder.acquireSources(ctx, warmup) {
-		return nil, err
+		if err := ctx.Err(); err != nil {
-	}
+			return nil, fmt.Errorf("fetch weather API sources: %w", err)
-	if err := builder.fetchCurrent(ctx); err != nil {
+		}
-		return nil, err
+		if err := builder.mergeSource(acquired); err != nil {
-	}
+			return nil, err
-	if err := builder.fetchHourly(ctx); err != nil {
+		}
-		return nil, err
-	}
-	if err := builder.fetchNarrative(ctx); err != nil {
-		return nil, err
-	}
-	if err := builder.fetchAlerts(ctx); err != nil {
-		return nil, err
-	}
-	if err := builder.fetchDiscussion(ctx); err != nil {
-		return nil, err
-	}
-	if err := builder.fetchWeatherStory(ctx); err != nil {
-		return nil, err
-	}
-	if err := builder.fetchSPCConvectiveOutlooks(ctx); err != nil {
-		return nil, err
 	}
 
 	return builder.bundle, nil
 }
 
 type bundleBuilder struct {
-	client    *Client
+	client *Client
-	bundle    *weatherdata.Bundle
+	bundle *weatherdata.Bundle
-	fetchedAt time.Time
 }
 
 type sourceRequest struct {
@@ -165,14 +156,81 @@ type fetchedSource struct {
 	source weatherdata.Source
 }
 
-func (b *bundleBuilder) fetchObservation(ctx context.Context) error {
+type warmupResponse struct {
+	endpoint   string
+	requestURL *url.URL
+	body       []byte
+	fetchedAt  time.Time
+}
+
+type sourceAcquisition struct {
+	request    sourceRequest
+	fetched    fetchedSource
+	err        error
+	warmup     warmupResponse
+	usesWarmup bool
+}
+
+func (b *bundleBuilder) acquireSources(ctx context.Context, warmup warmupResponse) []sourceAcquisition {
+	sources := []sourceAcquisition{
+		{request: sourceRequest{name: config.MissingSourceObservations, endpoint: "/observations", query: queryOptions{precision: true}, missingMessage: "observation data is missing"}},
+		{request: currentConditionsRequest()},
+		{request: sourceRequest{name: "hourly", endpoint: "/forecast/hourly", query: queryOptions{precision: true, timezone: true}, missingMessage: "hourly forecast data is missing", required: true, decodeLabel: "hourly forecast"}},
+		{request: sourceRequest{name: config.MissingSourceNarrative, endpoint: "/forecast/narrative", query: queryOptions{precision: true, timezone: true}, missingMessage: "narrative forecast data is missing"}},
+		{request: sourceRequest{name: config.MissingSourceAlerts, endpoint: "/alerts/active", query: queryOptions{allowNull: true}, missingMessage: "active alerts data is missing"}},
+		{request: sourceRequest{name: config.MissingSourceDiscussion, endpoint: "/discussion", query: queryOptions{timezone: true}, missingMessage: "forecast discussion data is missing"}},
+		{request: sourceRequest{name: config.MissingSourceWeatherStory, endpoint: "/weatherstories/latest", query: queryOptions{omitUnits: true}, missingMessage: "NWS weather story data is missing"}},
+		{request: sourceRequest{name: sourceSPCConvectiveOutlooks, endpoint: convectiveOutlooksEndpoint, query: queryOptions{timezone: true, omitUnits: true}, missingMessage: "SPC convective outlook data is missing"}},
+	}
+	if warmup.endpoint == currentConditionsEndpoint {
+		sources[1].warmup = warmup
+		sources[1].usesWarmup = true
+	}
+
+	var group sync.WaitGroup
+	for i := range sources {
+		if sources[i].usesWarmup {
+			continue
+		}
+		group.Add(1)
+		go func(index int) {
+			defer group.Done()
+			request := sources[index].request
+			raw, source, err := b.client.fetch(ctx, request.name, request.endpoint, request.query)
+			sources[index].fetched = fetchedSource{raw: raw, source: source}
+			sources[index].err = err
+		}(i)
+	}
+	group.Wait()
+	return sources
+}
+
+func (b *bundleBuilder) mergeSource(acquired sourceAcquisition) error {
+	switch acquired.request.name {
+	case config.MissingSourceObservations:
+		return b.fetchObservation(acquired)
+	case config.MissingSourceCurrent:
+		return b.fetchCurrent(acquired)
+	case "hourly":
+		return b.fetchHourly(acquired)
+	case config.MissingSourceNarrative:
+		return b.fetchNarrative(acquired)
+	case config.MissingSourceAlerts:
+		return b.fetchAlerts(acquired)
+	case config.MissingSourceDiscussion:
+		return b.fetchDiscussion(acquired)
+	case config.MissingSourceWeatherStory:
+		return b.fetchWeatherStory(acquired)
+	case sourceSPCConvectiveOutlooks:
+		return b.fetchSPCConvectiveOutlooks(acquired)
+	default:
+		return fmt.Errorf("merge unknown weather source %q", acquired.request.name)
+	}
+}
+
+func (b *bundleBuilder) fetchObservation(acquired sourceAcquisition) error {
 	var observation weatherdata.Observation
-	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+	fetched, ok, err := b.fetchDecodedSource(acquired, &observation)
-		name:           "observations",
-		endpoint:       "/observations",
-		query:          queryOptions{precision: true},
-		missingMessage: "observation data is missing",
-	}, &observation)
 	if err != nil || !ok {
 		return err
 	}
@@ -183,14 +241,18 @@ func (b *bundleBuilder) fetchObservation(ctx context.Context) error {
 	return nil
 }
 
-func (b *bundleBuilder) fetchCurrent(ctx context.Context) error {
+func currentConditionsRequest() sourceRequest {
-	var current weatherdata.Current
+	return sourceRequest{
-	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+		name:           config.MissingSourceCurrent,
-		name:           "current",
+		endpoint:       currentConditionsEndpoint,
-		endpoint:       "/conditions/current",
 		query:          queryOptions{precision: true},
 		missingMessage: "current conditions data is missing",
-	}, &current)
+	}
+}
+
+func (b *bundleBuilder) fetchCurrent(acquired sourceAcquisition) error {
+	var current weatherdata.Current
+	fetched, ok, err := b.fetchDecodedSource(acquired, &current)
 	if err != nil || !ok {
 		return err
 	}
@@ -200,16 +262,9 @@ func (b *bundleBuilder) fetchCurrent(ctx context.Context) error {
 	return nil
 }
 
-func (b *bundleBuilder) fetchHourly(ctx context.Context) error {
+func (b *bundleBuilder) fetchHourly(acquired sourceAcquisition) error {
 	var hourly weatherdata.ForecastRun
-	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+	fetched, ok, err := b.fetchDecodedSource(acquired, &hourly)
-		name:           "hourly",
-		endpoint:       "/forecast/hourly",
-		query:          queryOptions{precision: true, timezone: true},
-		missingMessage: "hourly forecast data is missing",
-		required:       true,
-		decodeLabel:    "hourly forecast",
-	}, &hourly)
 	if err != nil || !ok {
 		return err
 	}
@@ -217,6 +272,14 @@ func (b *bundleBuilder) fetchHourly(ctx context.Context) error {
 	if len(hourly.Periods) == 0 {
 		return fmt.Errorf("hourly forecast from %s contains no periods", source.Endpoint)
 	}
+	for i, period := range hourly.Periods {
+		if !period.HasUsableTimeBounds() {
+			return fmt.Errorf("hourly forecast from %s has unusable time bounds for period %d", source.Endpoint, i+1)
+		}
+		if !period.HasValidPrecipitationProbability() {
+			return fmt.Errorf("hourly forecast from %s has invalid precipitation probability for period %d", source.Endpoint, i+1)
+		}
+	}
 	source.IssuedAt = &hourly.IssuedAt
 	source.UpdatedAt = hourly.UpdatedAt
 	b.bundle.Hourly = &hourly
@@ -224,14 +287,9 @@ func (b *bundleBuilder) fetchHourly(ctx context.Context) error {
 	return nil
 }
 
-func (b *bundleBuilder) fetchNarrative(ctx context.Context) error {
+func (b *bundleBuilder) fetchNarrative(acquired sourceAcquisition) error {
 	var narrative weatherdata.ForecastRun
-	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+	fetched, ok, err := b.fetchDecodedSource(acquired, &narrative)
-		name:           "narrative",
-		endpoint:       "/forecast/narrative",
-		query:          queryOptions{precision: true, timezone: true},
-		missingMessage: "narrative forecast data is missing",
-	}, &narrative)
 	if err != nil || !ok {
 		return err
 	}
@@ -243,24 +301,21 @@ func (b *bundleBuilder) fetchNarrative(ctx context.Context) error {
 	return nil
 }
 
-func (b *bundleBuilder) fetchAlerts(ctx context.Context) error {
+func (b *bundleBuilder) fetchAlerts(acquired sourceAcquisition) error {
-	raw, source, err := b.client.fetch(ctx, "alerts", "/alerts/active", queryOptions{allowNull: true})
+	fetched, ok, err := b.fetchSource(acquired)
-	if err != nil {
+	if err != nil || !ok {
 		return err
 	}
-	if raw == nil {
+	raw, source := fetched.raw, fetched.source
-		return b.handleMissing(&source, "active alerts data is missing", false)
-	}
 	if isJSONNull(raw) {
-		b.bundle.Alerts = &weatherdata.AlertRun{Raw: append(json.RawMessage(nil), raw...)}
+		b.bundle.Alerts = &weatherdata.AlertRun{}
 		b.addSource(source)
 		return nil
 	}
 	var alerts weatherdata.AlertRun
 	if err := decodeSource(raw, &alerts); err != nil {
-		return b.handleMalformed(&source, err, sourceRequest{name: "alerts"})
+		return b.handleMalformed(&source, err, acquired.request)
 	}
-	alerts.Raw = append(json.RawMessage(nil), raw...)
 	if alerts.AsOf != nil {
 		source.IssuedAt = alerts.AsOf
 	}
@@ -269,14 +324,9 @@ func (b *bundleBuilder) fetchAlerts(ctx context.Context) error {
 	return nil
 }
 
-func (b *bundleBuilder) fetchDiscussion(ctx context.Context) error {
+func (b *bundleBuilder) fetchDiscussion(acquired sourceAcquisition) error {
 	var discussion weatherdata.Discussion
-	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+	fetched, ok, err := b.fetchDecodedSource(acquired, &discussion)
-		name:           "discussion",
-		endpoint:       "/discussion",
-		query:          queryOptions{timezone: true},
-		missingMessage: "forecast discussion data is missing",
-	}, &discussion)
 	if err != nil || !ok {
 		return err
 	}
@@ -288,18 +338,16 @@ func (b *bundleBuilder) fetchDiscussion(ctx context.Context) error {
 	return nil
 }
 
-func (b *bundleBuilder) fetchWeatherStory(ctx context.Context) error {
+func (b *bundleBuilder) fetchWeatherStory(acquired sourceAcquisition) error {
 	var story weatherdata.WeatherStory
-	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+	fetched, ok, err := b.fetchDecodedSource(acquired, &story)
-		name:           "weather_story",
-		endpoint:       "/weatherstories/latest",
-		query:          queryOptions{omitUnits: true},
-		missingMessage: "NWS weather story data is missing",
-	}, &story)
 	if err != nil || !ok {
 		return err
 	}
 	source := fetched.source
+	if !story.HasUsableContent() {
+		return b.handleMalformed(&source, fmt.Errorf("weather story has no usable content"), acquired.request)
+	}
 	if !story.StartTime.IsZero() {
 		source.IssuedAt = &story.StartTime
 	}
@@ -309,14 +357,9 @@ func (b *bundleBuilder) fetchWeatherStory(ctx context.Context) error {
 	return nil
 }
 
-func (b *bundleBuilder) fetchSPCConvectiveOutlooks(ctx context.Context) error {
+func (b *bundleBuilder) fetchSPCConvectiveOutlooks(acquired sourceAcquisition) error {
 	var run weatherdata.ConvectiveOutlookRun
-	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+	fetched, ok, err := b.fetchDecodedSource(acquired, &run)
-		name:           sourceSPCConvectiveOutlooks,
-		endpoint:       convectiveOutlooksEndpoint,
-		query:          queryOptions{timezone: true, omitUnits: true},
-		missingMessage: "SPC convective outlook data is missing",
-	}, &run)
 	if err != nil || !ok {
 		return err
 	}
@@ -332,26 +375,35 @@ func (b *bundleBuilder) fetchSPCConvectiveOutlooks(ctx context.Context) error {
 	return nil
 }
 
-func (b *bundleBuilder) fetchDecodedSource(ctx context.Context, request sourceRequest, target any) (fetchedSource, bool, error) {
+func (b *bundleBuilder) fetchDecodedSource(acquired sourceAcquisition, target any) (fetchedSource, bool, error) {
-	fetched, ok, err := b.fetchSource(ctx, request)
+	fetched, ok, err := b.fetchSource(acquired)
 	if err != nil || !ok {
 		return fetchedSource{}, false, err
 	}
+	return b.decodeFetchedSource(fetched, acquired.request, target)
+}
+
+func (b *bundleBuilder) decodeFetchedSource(fetched fetchedSource, request sourceRequest, target any) (fetchedSource, bool, error) {
 	if err := decodeSource(fetched.raw, target); err != nil {
 		return fetchedSource{}, false, b.handleMalformed(&fetched.source, err, request)
 	}
 	return fetched, true, nil
 }
 
-func (b *bundleBuilder) fetchSource(ctx context.Context, request sourceRequest) (fetchedSource, bool, error) {
+func (b *bundleBuilder) fetchSource(acquired sourceAcquisition) (fetchedSource, bool, error) {
-	raw, source, err := b.client.fetch(ctx, request.name, request.endpoint, request.query)
+	if acquired.usesWarmup {
-	if err != nil {
+		raw, source, err := b.client.decodeSourceResponse(acquired.request.name, acquired.request.endpoint, acquired.request.query, acquired.warmup.requestURL, acquired.warmup.body, acquired.warmup.fetchedAt)
-		return fetchedSource{}, false, err
+		if err != nil {
+			return fetchedSource{}, false, err
+		}
+		acquired.fetched = fetchedSource{raw: raw, source: source}
+	} else if acquired.err != nil {
+		return fetchedSource{}, false, acquired.err
 	}
-	if raw == nil {
+	if acquired.fetched.raw == nil {
-		return fetchedSource{}, false, b.handleMissing(&source, request.missingMessage, request.required)
+		return fetchedSource{}, false, b.handleMissing(&acquired.fetched.source, acquired.request.missingMessage, acquired.request.required)
 	}
-	return fetchedSource{raw: raw, source: source}, true, nil
+	return acquired.fetched, true, nil
 }
 
 func (b *bundleBuilder) handleMissing(source *weatherdata.Source, message string, required bool) error {
@@ -422,7 +474,10 @@ func (c *Client) fetch(ctx context.Context, sourceName string, endpoint string,
 	if err != nil {
 		return nil, weatherdata.Source{}, err
 	}
+	return c.decodeSourceResponse(sourceName, endpoint, opts, reqURL, body, c.now())
+}
 
+func (c *Client) decodeSourceResponse(sourceName string, endpoint string, opts queryOptions, reqURL *url.URL, body []byte, fetchedAt time.Time) (json.RawMessage, weatherdata.Source, error) {
 	var env envelope
 	if err := json.Unmarshal(body, &env); err != nil {
 		return nil, weatherdata.Source{}, fmt.Errorf("decode %s envelope: %w", endpoint, err)
@@ -432,7 +487,7 @@ func (c *Client) fetch(ctx context.Context, sourceName string, endpoint string,
 		Name:      sourceName,
 		Endpoint:  endpoint,
 		Query:     queryMap(reqURL.Query()),
-		FetchedAt: c.now(),
+		FetchedAt: fetchedAt,
 	}
 	if len(env.Data) == 0 || (isJSONNull(env.Data) && !opts.allowNull) {
 		source.Missing = true
@@ -446,53 +501,40 @@ func (c *Client) fetch(ctx context.Context, sourceName string, endpoint string,
 	return env.Data, source, nil
 }
 
-func (c *Client) warmup(ctx context.Context) error {
+func (c *Client) warmup(ctx context.Context) (warmupResponse, error) {
 	endpoint := c.warmupEndpoint
 	if strings.TrimSpace(endpoint) == "" {
 		endpoint = defaultWarmupEndpoint
 	}
 	attempts := positiveAttemptCount(c.warmupAttempts)
 	var lastErr error
+	var lastRetryable bool
 	for attempt := 1; attempt <= attempts; attempt++ {
 		if err := ctx.Err(); err != nil {
-			return fmt.Errorf("warm up weather API via %s: %w", endpoint, err)
+			return warmupResponse{}, fmt.Errorf("warm up weather API via %s: %w", endpoint, err)
 		}
-		if err := c.warmupOnce(ctx, endpoint); err != nil {
+		reqURL, body, err := c.warmupOnce(ctx, endpoint)
+		if err != nil {
 			lastErr = err
+			lastRetryable = isRetryableRequestError(err)
 		} else {
-			return nil
+			return warmupResponse{endpoint: endpoint, requestURL: reqURL, body: body, fetchedAt: c.now()}, nil
 		}
-		if attempt == attempts {
+		if !lastRetryable || attempt == attempts {
 			break
 		}
 		if err := waitForRetry(ctx, c.warmupDelay); err != nil {
-			return fmt.Errorf("warm up weather API via %s after %d attempt(s): %w", endpoint, attempt, err)
+			return warmupResponse{}, fmt.Errorf("warm up weather API via %s after %d attempt(s): %w", endpoint, attempt, err)
 		}
 	}
-	return fmt.Errorf("warm up weather API via %s failed after %d attempts: %w", endpoint, attempts, lastErr)
+	if !lastRetryable {
+		return warmupResponse{}, lastErr
+	}
+	return warmupResponse{}, fmt.Errorf("warm up weather API via %s failed after %d attempts: %w", endpoint, attempts, lastErr)
 }
 
-func (c *Client) warmupOnce(ctx context.Context, endpoint string) error {
+func (c *Client) warmupOnce(ctx context.Context, endpoint string) (*url.URL, []byte, error) {
-	reqURL := c.endpointURL(endpoint, queryOptions{precision: true})
+	return c.fetchHTTPOnce(ctx, endpoint, queryOptions{precision: true})
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL.String(), nil)
-	if err != nil {
-		return fmt.Errorf("create request for %s: %w", endpoint, err)
-	}
-
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return fmt.Errorf("fetch %s: %w", endpoint, err)
-	}
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(io.LimitReader(resp.Body, 10<<20))
-	if err != nil {
-		return fmt.Errorf("read %s response: %w", endpoint, err)
-	}
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return fmt.Errorf("fetch %s: unexpected HTTP status %d: %s", endpoint, resp.StatusCode, strings.TrimSpace(string(body)))
-	}
-	return nil
 }
 
 func (c *Client) fetchHTTP(ctx context.Context, endpoint string, opts queryOptions) (*url.URL, []byte, error) {
@@ -539,16 +581,12 @@ func (c *Client) fetchHTTPOnce(ctx context.Context, endpoint string, opts queryO
 	}
 	defer resp.Body.Close()
 
-	body, err := io.ReadAll(io.LimitReader(resp.Body, 10<<20))
+	body, err := readResponseBody(resp.Body)
 	if err != nil {
-		err = fmt.Errorf("read %s response: %w", endpoint, err)
+		return reqURL, nil, responseReadError(ctx, endpoint, err)
-		if ctx.Err() != nil {
-			return reqURL, nil, err
-		}
-		return reqURL, nil, retryableRequestError{err: err}
 	}
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		err := fmt.Errorf("fetch %s: unexpected HTTP status %d: %s", endpoint, resp.StatusCode, strings.TrimSpace(string(body)))
+		err := fmt.Errorf("fetch %s: unexpected HTTP status %d", endpoint, resp.StatusCode)
 		if isRetryableHTTPStatus(resp.StatusCode) {
 			return reqURL, nil, retryableRequestError{err: err}
 		}
@@ -557,6 +595,25 @@ func (c *Client) fetchHTTPOnce(ctx context.Context, endpoint string, opts queryO
 	return reqURL, body, nil
 }
 
+func readResponseBody(body io.Reader) ([]byte, error) {
+	data, err := io.ReadAll(io.LimitReader(body, maxResponseBodyBytes+1))
+	if err != nil {
+		return nil, err
+	}
+	if int64(len(data)) > maxResponseBodyBytes {
+		return nil, errResponseBodyTooLarge
+	}
+	return data, nil
+}
+
+func responseReadError(ctx context.Context, endpoint string, err error) error {
+	err = fmt.Errorf("read %s response: %w", endpoint, err)
+	if errors.Is(err, errResponseBodyTooLarge) || ctx.Err() != nil {
+		return err
+	}
+	return retryableRequestError{err: err}
+}
+
 type retryableRequestError struct {
 	err error
 }
@@ -659,10 +716,3 @@ func sourceHash(raw json.RawMessage) (string, error) {
 	sum := sha256.Sum256(compact.Bytes())
 	return hex.EncodeToString(sum[:]), nil
 }
-
-func SaveBundle(path string, bundle *weatherdata.Bundle) error {
-	if err := fileutil.WriteJSONAtomic(path, bundle); err != nil {
-		return fmt.Errorf("save bundle: %w", err)
-	}
-	return nil
-}

internal/adapters/weatherapi/client_test.go

@@ -3,11 +3,13 @@ package weatherapi
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 
@@ -15,6 +17,12 @@ import (
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
 )
 
+type roundTripperFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripperFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
 func TestFetchBundleFromFixtures(t *testing.T) {
 	var requested []string
 	server := fixtureServer(t, nil, &requested)
@@ -80,8 +88,8 @@ func TestFetchBundleFromFixtures(t *testing.T) {
 		"/weatherstories/latest",
 		convectiveOutlooksEndpoint,
 	}
-	if len(requested) != len(wantPaths)+1 {
+	if len(requested) != len(wantPaths) {
-		t.Fatalf("requested paths = %v, want warmup plus %d source endpoints", requested, len(wantPaths))
+		t.Fatalf("requested paths = %v, want %d source endpoints", requested, len(wantPaths))
 	}
 	if !strings.HasPrefix(requested[0], defaultWarmupEndpoint+"?") && requested[0] != defaultWarmupEndpoint {
 		t.Fatalf("first requested path = %q, want warmup endpoint %s", requested[0], defaultWarmupEndpoint)
@@ -91,6 +99,9 @@ func TestFetchBundleFromFixtures(t *testing.T) {
 			t.Fatalf("requested paths = %v, want %s", requested, want)
 		}
 	}
+	if got := countPath(requested, currentConditionsEndpoint); got != 1 {
+		t.Fatalf("conditions/current requests = %d, want 1; requested paths = %v", got, requested)
+	}
 	if !containsPath(requested, "/forecast/hourly") || containsPath(requested, "/forecast/hourly/today") {
 		t.Fatalf("requested paths = %v, want full hourly endpoint only", requested)
 	}
@@ -105,6 +116,191 @@ func TestFetchBundleFromFixtures(t *testing.T) {
 	}
 }
 
+func TestFetchBundleMergesConcurrentSourcesInSourceOrder(t *testing.T) {
+	paths := []string{
+		"/observations",
+		"/forecast/hourly",
+		"/forecast/narrative",
+		"/alerts/active",
+		"/discussion",
+		"/weatherstories/latest",
+		convectiveOutlooksEndpoint,
+	}
+	started := make(chan string, len(paths))
+	release := make(map[string]chan struct{}, len(paths))
+	for _, path := range paths {
+		release[path] = make(chan struct{})
+	}
+	var releaseOnce sync.Once
+	releaseAll := func() {
+		releaseOnce.Do(func() {
+			for i := len(paths) - 1; i >= 0; i-- {
+				close(release[paths[i]])
+			}
+		})
+	}
+	t.Cleanup(releaseAll)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == currentConditionsEndpoint {
+			if !serveWeatherFixture(w, r) {
+				http.NotFound(w, r)
+			}
+			return
+		}
+		ready, ok := release[r.URL.Path]
+		if !ok {
+			http.NotFound(w, r)
+			return
+		}
+		started <- r.URL.Path
+		<-ready
+		if !serveWeatherFixture(w, r) {
+			http.NotFound(w, r)
+		}
+	}))
+	defer server.Close()
+	client := newTestClient(t, server.URL+"/", nil)
+
+	type fetchResult struct {
+		bundle *weatherdata.Bundle
+		err    error
+	}
+	result := make(chan fetchResult, 1)
+	go func() {
+		bundle, err := client.FetchBundle(context.Background())
+		result <- fetchResult{bundle: bundle, err: err}
+	}()
+
+	seen := make(map[string]bool, len(paths))
+	for range paths {
+		select {
+		case path := <-started:
+			seen[path] = true
+		case <-time.After(time.Second):
+			t.Fatalf("independent requests started = %v, want %v", seen, paths)
+		}
+	}
+	releaseAll()
+
+	select {
+	case got := <-result:
+		if got.err != nil {
+			t.Fatalf("FetchBundle() error = %v", got.err)
+		}
+		wantSources := []string{
+			config.MissingSourceObservations,
+			config.MissingSourceCurrent,
+			"hourly",
+			config.MissingSourceNarrative,
+			config.MissingSourceAlerts,
+			config.MissingSourceDiscussion,
+			config.MissingSourceWeatherStory,
+			sourceSPCConvectiveOutlooks,
+		}
+		gotSources := make([]string, 0, len(got.bundle.Sources))
+		for _, source := range got.bundle.Sources {
+			gotSources = append(gotSources, source.Name)
+		}
+		if strings.Join(gotSources, ",") != strings.Join(wantSources, ",") {
+			t.Fatalf("source order = %v, want %v", gotSources, wantSources)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("FetchBundle() did not finish after all source responses were released")
+	}
+}
+
+func TestFetchBundleReportsConcurrentFailuresInSourceOrder(t *testing.T) {
+	var requested []string
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/forecast/hourly":    {status: http.StatusBadRequest, body: `invalid hourly request`},
+		"/forecast/narrative": {status: http.StatusBadRequest, body: `invalid narrative request`},
+	}, &requested)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want source error")
+	}
+	if !strings.Contains(err.Error(), "/forecast/hourly") {
+		t.Fatalf("error = %q, want the earlier hourly source failure", err.Error())
+	}
+	if !containsPath(requested, "/forecast/narrative") {
+		t.Fatalf("requested paths = %v, want independent narrative request", requested)
+	}
+}
+
+func TestFetchBundleCancelsConcurrentSourceRequests(t *testing.T) {
+	paths := []string{
+		"/observations",
+		"/forecast/hourly",
+		"/forecast/narrative",
+		"/alerts/active",
+		"/discussion",
+		"/weatherstories/latest",
+		convectiveOutlooksEndpoint,
+	}
+	started := make(chan string, len(paths))
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == currentConditionsEndpoint {
+			if !serveWeatherFixture(w, r) {
+				http.NotFound(w, r)
+			}
+			return
+		}
+		for _, path := range paths {
+			if r.URL.Path == path {
+				started <- path
+				<-r.Context().Done()
+				return
+			}
+		}
+		http.NotFound(w, r)
+	}))
+	defer server.Close()
+	client := newTestClient(t, server.URL+"/", nil)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	result := make(chan error, 1)
+	go func() {
+		_, err := client.FetchBundle(ctx)
+		result <- err
+	}()
+	for range paths {
+		select {
+		case <-started:
+		case <-time.After(time.Second):
+			cancel()
+			t.Fatal("not all independent requests started before cancellation")
+		}
+	}
+	cancel()
+	select {
+	case err := <-result:
+		if err == nil || !strings.Contains(err.Error(), context.Canceled.Error()) {
+			t.Fatalf("FetchBundle() error = %v, want context cancellation", err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("FetchBundle() did not return after cancellation")
+	}
+}
+
+func TestFetchBundleRejectsInvalidHourlyPrecipitationProbability(t *testing.T) {
+	for _, probability := range []string{"-1", "101"} {
+		t.Run(probability, func(t *testing.T) {
+			server := fixtureServer(t, map[string]handlerOverride{
+				"/forecast/hourly": {status: http.StatusOK, body: `{"data":{"periods":[{"startTime":"2026-05-29T13:00:00Z","endTime":"2026-05-29T14:00:00Z","probabilityOfPrecipitationPercent":` + probability + `}]}}`},
+			}, nil)
+			client := newTestClient(t, server.URL+"/", nil)
+
+			_, err := client.FetchBundle(context.Background())
+			if err == nil || !strings.Contains(err.Error(), "invalid precipitation probability") {
+				t.Fatalf("FetchBundle() error = %v, want invalid precipitation probability", err)
+			}
+		})
+	}
+}
+
 func TestFetchBundleBuildsExpectedQueries(t *testing.T) {
 	var requested []string
 	server := fixtureServer(t, nil, &requested)
@@ -194,8 +390,9 @@ func TestFetchBundleRecordsSourceHash(t *testing.T) {
 }
 
 func TestHTTPErrorIsActionable(t *testing.T) {
+	const marker = "upstream-secret-marker"
 	server := fixtureServer(t, map[string]handlerOverride{
-		"/forecast/hourly": {status: http.StatusBadGateway, body: `upstream failed`},
+		"/forecast/hourly": {status: http.StatusBadGateway, body: marker + strings.Repeat("x", 4096)},
 	}, nil)
 	client := newTestClient(t, server.URL+"/", nil)
 
@@ -206,6 +403,9 @@ func TestHTTPErrorIsActionable(t *testing.T) {
 	if !strings.Contains(err.Error(), "/forecast/hourly") || !strings.Contains(err.Error(), "502") {
 		t.Fatalf("error = %q, want endpoint and status", err.Error())
 	}
+	if strings.Contains(err.Error(), marker) {
+		t.Fatalf("error = %q, must not contain upstream response text", err.Error())
+	}
 }
 
 func TestWarmupRetriesBeforeFetchBundle(t *testing.T) {
@@ -231,8 +431,8 @@ func TestWarmupRetriesBeforeFetchBundle(t *testing.T) {
 	if bundle.Current == nil {
 		t.Fatal("Current = nil, want successful fetch after warmup retry")
 	}
-	if warmupCalls != 3 {
+	if warmupCalls != 2 {
-		t.Fatalf("conditions/current calls = %d, want failed warmup, successful warmup, and current source fetch", warmupCalls)
+		t.Fatalf("conditions/current calls = %d, want failed and successful warmup attempts", warmupCalls)
 	}
 	if len(requested) < 2 || !containsPath(requested[:2], defaultWarmupEndpoint) {
 		t.Fatalf("initial requests = %v, want warmup endpoint retries", requested)
@@ -265,6 +465,111 @@ func TestWarmupFailureStopsBeforeSourceFetches(t *testing.T) {
 	}
 }
 
+func TestWarmupDoesNotRetryPermanentStatus(t *testing.T) {
+	var requested []string
+	server := fixtureServer(t, map[string]handlerOverride{
+		defaultWarmupEndpoint: {status: http.StatusNotFound, body: `not found`},
+	}, &requested)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "404") {
+		t.Fatalf("FetchBundle() error = %v, want non-retryable warmup status", err)
+	}
+	if got := countPath(requested, defaultWarmupEndpoint); got != 1 {
+		t.Fatalf("warmup requests = %d, want 1; all requests = %v", got, requested)
+	}
+	if containsPath(requested, "/observations") {
+		t.Fatalf("requested paths = %v, want warmup failure before source fetches", requested)
+	}
+}
+
+func TestWarmupErrorDiagnosticsRedactResponseBody(t *testing.T) {
+	const marker = "upstream-secret-marker"
+	server := fixtureServer(t, map[string]handlerOverride{
+		defaultWarmupEndpoint: {status: http.StatusNotFound, body: marker + strings.Repeat("x", 4096)},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want warmup error")
+	}
+	if !strings.Contains(err.Error(), defaultWarmupEndpoint) || !strings.Contains(err.Error(), "404") {
+		t.Fatalf("error = %q, want warmup endpoint and status", err.Error())
+	}
+	if strings.Contains(err.Error(), marker) {
+		t.Fatalf("error = %q, must not contain upstream response text", err.Error())
+	}
+}
+
+func TestFetchAcceptsResponseAtBodyLimit(t *testing.T) {
+	body := paddedJSON(t, `{"data":null}`, int(maxResponseBodyBytes))
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/forecast/narrative": {handler: func(w http.ResponseWriter, r *http.Request) {
+			_, _ = w.Write([]byte(body))
+		}},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	if _, err := client.FetchBundle(context.Background()); err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+}
+
+func TestFetchRejectsOversizedResponseWithoutRetry(t *testing.T) {
+	var requested []string
+	var narrativeCalls int
+	oversizedBody := paddedJSON(t, `{"data":null}`, int(maxResponseBodyBytes)) + "x"
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/forecast/narrative": {handler: func(w http.ResponseWriter, r *http.Request) {
+			narrativeCalls++
+			_, _ = w.Write([]byte(oversizedBody))
+		}},
+	}, &requested)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want oversized response error")
+	}
+	if !strings.Contains(err.Error(), "/forecast/narrative") || !strings.Contains(err.Error(), errResponseBodyTooLarge.Error()) {
+		t.Fatalf("error = %q, want endpoint and response limit", err.Error())
+	}
+	if narrativeCalls != 1 {
+		t.Fatalf("narrative calls = %d, want no retry", narrativeCalls)
+	}
+	if !containsPath(requested, "/alerts/active") {
+		t.Fatalf("requested paths = %v, want independent source requests despite narrative failure", requested)
+	}
+}
+
+func TestWarmupRejectsOversizedResponseWithoutRetry(t *testing.T) {
+	var requested []string
+	oversizedBody := paddedJSON(t, `{"data":{}}`, int(maxResponseBodyBytes)) + "x"
+	server := fixtureServer(t, map[string]handlerOverride{
+		defaultWarmupEndpoint: {handler: func(w http.ResponseWriter, r *http.Request) {
+			_, _ = w.Write([]byte(oversizedBody))
+		}},
+	}, &requested)
+	client := newTestClient(t, server.URL+"/", nil)
+	client.warmupAttempts = 2
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want oversized warmup response error")
+	}
+	if !strings.Contains(err.Error(), defaultWarmupEndpoint) || !strings.Contains(err.Error(), errResponseBodyTooLarge.Error()) {
+		t.Fatalf("error = %q, want warmup endpoint and response limit", err.Error())
+	}
+	if got := countPath(requested, defaultWarmupEndpoint); got != 1 {
+		t.Fatalf("warmup requests = %d, want no retry; all requests = %v", got, requested)
+	}
+	if containsPath(requested, "/observations") {
+		t.Fatalf("requested paths = %v, want warmup failure before source fetches", requested)
+	}
+}
+
 func TestFetchRetriesRetryableStatus(t *testing.T) {
 	var hourlyCalls int
 	server := fixtureServer(t, map[string]handlerOverride{
@@ -312,6 +617,40 @@ func TestFetchDoesNotRetryNonRetryableStatus(t *testing.T) {
 	}
 }
 
+func TestNewValidatesWeatherAPIBaseURLSchemeWithoutRequests(t *testing.T) {
+	requests := 0
+	httpClient := &http.Client{Transport: roundTripperFunc(func(*http.Request) (*http.Response, error) {
+		requests++
+		return nil, errors.New("unexpected request")
+	})}
+	tests := []struct {
+		name    string
+		baseURL string
+		wantErr string
+	}{
+		{name: "local HTTP", baseURL: "http://127.0.0.1:8080/weather/"},
+		{name: "local HTTPS", baseURL: "https://127.0.0.1:8443/weather/"},
+		{name: "unsupported scheme", baseURL: "ftp://weather.example.test/", wantErr: "weather_api.base_url must use http or https"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := testConfig(tt.baseURL)
+			_, err := New(cfg, WithHTTPClient(httpClient))
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Fatalf("New() error = %v", err)
+				}
+			} else if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("New() error = %v, want %q", err, tt.wantErr)
+			}
+		})
+	}
+	if requests != 0 {
+		t.Fatalf("HTTP requests = %d, want none", requests)
+	}
+}
+
 func TestFetchDoesNotRetryMalformedEnvelope(t *testing.T) {
 	var hourlyCalls int
 	server := fixtureServer(t, map[string]handlerOverride{
@@ -351,6 +690,66 @@ func TestRequiredHourlyForecast(t *testing.T) {
 	}
 }
 
+func TestRequiredHourlyForecastValidatesPeriodBounds(t *testing.T) {
+	tests := []struct {
+		name    string
+		body    string
+		wantErr bool
+	}{
+		{
+			name: "valid period",
+			body: `{"data":{"periods":[{"startTime":"2026-05-29T13:00:00Z","endTime":"2026-05-29T14:00:00Z"}]}}`,
+		},
+		{
+			name:    "missing start",
+			body:    `{"data":{"periods":[{"endTime":"2026-05-29T14:00:00Z"}]}}`,
+			wantErr: true,
+		},
+		{
+			name:    "missing end",
+			body:    `{"data":{"periods":[{"startTime":"2026-05-29T13:00:00Z"}]}}`,
+			wantErr: true,
+		},
+		{
+			name:    "empty range",
+			body:    `{"data":{"periods":[{"startTime":"2026-05-29T13:00:00Z","endTime":"2026-05-29T13:00:00Z"}]}}`,
+			wantErr: true,
+		},
+		{
+			name:    "reversed range",
+			body:    `{"data":{"periods":[{"startTime":"2026-05-29T14:00:00Z","endTime":"2026-05-29T13:00:00Z"}]}}`,
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var requested []string
+			server := fixtureServer(t, map[string]handlerOverride{
+				"/forecast/hourly": {status: http.StatusOK, body: tt.body},
+			}, &requested)
+			client := newTestClient(t, server.URL+"/", nil)
+
+			bundle, err := client.FetchBundle(context.Background())
+			if tt.wantErr {
+				if err == nil || !strings.Contains(err.Error(), "hourly forecast") || !strings.Contains(err.Error(), "time bounds") {
+					t.Fatalf("FetchBundle() error = %v, want hourly time-bounds failure", err)
+				}
+				if got := countPath(requested, "/forecast/hourly"); got != 1 {
+					t.Fatalf("hourly requests = %d, want no retry; all requests = %v", got, requested)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("FetchBundle() error = %v", err)
+			}
+			if bundle.Hourly == nil || len(bundle.Hourly.Periods) != 1 {
+				t.Fatalf("Hourly = %#v, want accepted hourly period", bundle.Hourly)
+			}
+		})
+	}
+}
+
 func TestNullAlertsMeansNoActiveAlerts(t *testing.T) {
 	server := fixtureServer(t, map[string]handlerOverride{
 		"/alerts/active": {status: http.StatusOK, body: `{"data": null}`},
@@ -542,6 +941,44 @@ func TestMalformedWeatherStoryUsesPolicy(t *testing.T) {
 	}
 }
 
+func TestEmptyWeatherStoryUsesPolicy(t *testing.T) {
+	for _, tt := range []struct {
+		name    string
+		policy  config.MissingSourcePolicy
+		wantErr bool
+	}{
+		{name: "warn", policy: config.MissingSourceWarn},
+		{name: "error", policy: config.MissingSourceError, wantErr: true},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			server := fixtureServer(t, map[string]handlerOverride{
+				"/weatherstories/latest": {status: http.StatusOK, body: `{"data": {}}`},
+			}, nil)
+			client := newTestClient(t, server.URL+"/", map[string]config.MissingSourcePolicy{
+				"weather_story": tt.policy,
+			})
+
+			bundle, err := client.FetchBundle(context.Background())
+			if tt.wantErr {
+				if err == nil || !strings.Contains(err.Error(), "weather story has no usable content") {
+					t.Fatalf("FetchBundle() error = %v, want unusable weather story error", err)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("FetchBundle() error = %v", err)
+			}
+			if bundle.WeatherStory != nil {
+				t.Fatalf("WeatherStory = %#v, want nil for empty source", bundle.WeatherStory)
+			}
+			source := sourceByName(t, bundle.Sources, "weather_story")
+			if !source.Missing || len(source.Warnings) != 1 || source.Warnings[0].Code != "malformed_source" {
+				t.Fatalf("weather_story source = %#v, want malformed source warning", source)
+			}
+		})
+	}
+}
+
 func TestContextCancellation(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		<-r.Context().Done()
@@ -618,48 +1055,40 @@ func TestHTTPTimeout(t *testing.T) {
 	}
 }
 
-func TestSaveBundle(t *testing.T) {
-	server := fixtureServer(t, nil, nil)
-	client := newTestClient(t, server.URL+"/", nil)
-	bundle, err := client.FetchBundle(context.Background())
-	if err != nil {
-		t.Fatalf("FetchBundle() error = %v", err)
-	}
-
-	path := filepath.Join(t.TempDir(), "nested", "bundle.json")
-	if err := SaveBundle(path, bundle); err != nil {
-		t.Fatalf("SaveBundle() error = %v", err)
-	}
-	data, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatalf("read saved bundle: %v", err)
-	}
-	if !strings.Contains(string(data), `"hourly"`) {
-		t.Fatalf("saved bundle missing hourly source:\n%s", string(data))
-	}
-}
-
 type handlerOverride struct {
 	status  int
 	body    string
 	handler http.HandlerFunc
 }
 
+var weatherFixtureFiles = map[string]string{
+	"/observations":            "observations.json",
+	"/conditions/current":      "current.json",
+	"/forecast/hourly":         "hourly.json",
+	"/forecast/narrative":      "narrative.json",
+	"/alerts/active":           "alerts.json",
+	"/discussion":              "discussion.json",
+	"/weatherstories/latest":   "weather_story.json",
+	convectiveOutlooksEndpoint: "convective_outlooks.json",
+}
+
+func serveWeatherFixture(w http.ResponseWriter, r *http.Request) bool {
+	name, ok := weatherFixtureFiles[r.URL.Path]
+	if !ok {
+		return false
+	}
+	http.ServeFile(w, r, filepath.Join("testdata", name))
+	return true
+}
+
 func fixtureServer(t *testing.T, overrides map[string]handlerOverride, requested *[]string) *httptest.Server {
 	t.Helper()
-	fixtures := map[string]string{
+	var requestedMu sync.Mutex
-		"/observations":            "observations.json",
-		"/conditions/current":      "current.json",
-		"/forecast/hourly":         "hourly.json",
-		"/forecast/narrative":      "narrative.json",
-		"/alerts/active":           "alerts.json",
-		"/discussion":              "discussion.json",
-		"/weatherstories/latest":   "weather_story.json",
-		convectiveOutlooksEndpoint: "convective_outlooks.json",
-	}
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if requested != nil {
+			requestedMu.Lock()
 			*requested = append(*requested, r.URL.String())
+			requestedMu.Unlock()
 		}
 		if override, ok := overrides[r.URL.Path]; ok {
 			if override.handler != nil {
@@ -670,12 +1099,9 @@ func fixtureServer(t *testing.T, overrides map[string]handlerOverride, requested
 			_, _ = w.Write([]byte(override.body))
 			return
 		}
-		name, ok := fixtures[r.URL.Path]
+		if !serveWeatherFixture(w, r) {
-		if !ok {
 			http.NotFound(w, r)
-			return
 		}
-		http.ServeFile(w, r, filepath.Join("testdata", name))
 	}))
 	t.Cleanup(server.Close)
 	return server
@@ -706,6 +1132,14 @@ func fixedNow() time.Time {
 	return time.Date(2026, 5, 29, 15, 0, 0, 0, time.UTC)
 }
 
+func paddedJSON(t *testing.T, value string, size int) string {
+	t.Helper()
+	if len(value) > size {
+		t.Fatalf("JSON value length = %d, exceeds requested size %d", len(value), size)
+	}
+	return value + strings.Repeat(" ", size-len(value))
+}
+
 func containsPath(requested []string, path string) bool {
 	for _, rawURL := range requested {
 		if strings.HasPrefix(rawURL, path+"?") || rawURL == path {

internal/app/batch_generation_test.go

@@ -0,0 +1,361 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+)
+
+func TestRunBatchDetailedKeepsSuccessfulOutputAndSkipsNotificationAfterPartialFailure(t *testing.T) {
+	bundle := generationBundle(t)
+	bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+	notifier := &generationNotifier{}
+	executor := &generationExecutor{failedPrompt: generationDefinitionForPrompt("weather.tomorrow_generated_text").PromptID}
+	result, err := RunBatchDetailed(context.Background(), BatchRequest{
+		Config: generationDistributorConfig(), Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: t.TempDir(),
+		Collector: &generationCollector{bundle: &bundle}, Executor: executor, Notifier: notifier,
+	})
+	if err != nil || result == nil || result.Total != 2 || result.Succeeded != 1 || result.Failed != 1 || result.Canceled != 0 || result.Notification == nil || result.Notification.Status != "skipped" || notifier.batchCalls != 0 {
+		t.Fatalf("RunBatchDetailed() result/error/notifier = %#v/%v/%#v", result, err, notifier)
+	}
+	if result.Reports[0].Status != "succeeded" || result.Reports[0].OutputPath == "" || result.Reports[1].Status != "failed" || result.Reports[1].OutputPath != "" {
+		t.Fatalf("report results = %#v", result.Reports)
+	}
+	if data, readErr := os.ReadFile(result.Reports[0].OutputPath); readErr != nil || len(data) == 0 {
+		t.Fatalf("successful output = %q, error = %v", data, readErr)
+	}
+}
+
+func TestRunBatchDetailedStopsAfterReportCancellation(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	bundle := generationBundle(t)
+	bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+	notifier := &generationNotifier{}
+	executor := &generationExecutor{cancelBeforeReturn: cancel}
+
+	result, err := RunBatchDetailed(ctx, BatchRequest{
+		Config: generationDistributorConfig(), Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: t.TempDir(),
+		Collector: &generationCollector{bundle: &bundle}, Executor: executor, Notifier: notifier,
+	})
+	if !errors.Is(err, context.Canceled) || result == nil || result.Total != 2 || result.Succeeded != 0 || result.Failed != 0 || result.Canceled != 2 || executor.executeCalls != 1 || notifier.batchCalls != 0 || result.Notification == nil || result.Notification.Status != "skipped" || result.Notification.Reason != "batch canceled" {
+		t.Fatalf("RunBatchDetailed() result/error/executor/notifier = %#v/%v/%#v/%#v", result, err, executor, notifier)
+	}
+	for _, item := range result.Reports {
+		if item.Status != "canceled" || item.OutputPath != "" {
+			t.Fatalf("canceled report = %#v", item)
+		}
+	}
+}
+
+func TestRunBatchDetailedPreservesIndependentFailureDuringCancellation(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	bundle := generationBundle(t)
+	bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+	notifier := &generationNotifier{}
+	executor := &generationExecutor{
+		executeErr: errors.New("independent report failure"),
+		beforeExecute: func(promptexec.ExecuteRequest) {
+			cancel()
+		},
+	}
+
+	result, err := RunBatchDetailed(ctx, BatchRequest{
+		Config: generationDistributorConfig(), Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: t.TempDir(),
+		Collector: &generationCollector{bundle: &bundle}, Executor: executor, Notifier: notifier,
+	})
+	if !errors.Is(err, context.Canceled) || result == nil || result.Total != 2 || result.Succeeded != 0 || result.Failed != 1 || result.Canceled != 1 || notifier.batchCalls != 0 || result.Notification == nil || result.Notification.Status != "skipped" || result.Notification.Reason != "batch canceled" {
+		t.Fatalf("RunBatchDetailed() result/error/notifier = %#v/%v/%#v", result, err, notifier)
+	}
+	if result.Reports[0].Status != "failed" || result.Reports[0].Error == "" || result.Reports[1].Status != "canceled" {
+		t.Fatalf("report results = %#v", result.Reports)
+	}
+}
+
+func TestNotifyBatchSkipsCancellationObservedAfterReportsComplete(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	notifier := &generationNotifier{}
+
+	result := notifyBatch(batchNotificationInput{
+		ctx: ctx, cfg: generationDistributorConfig(), batch: BatchMorning,
+		runID: "run-id", startedAt: generationTime("2026-05-29T08:30:00-05:00"),
+		result:   &BatchResult{Total: 1, Succeeded: 1, Reports: []BatchReportResult{{Status: "succeeded"}}},
+		notifier: notifier,
+	})
+
+	if result == nil || result.Status != "skipped" || result.Reason != "batch canceled" || notifier.batchCalls != 0 {
+		t.Fatalf("notifyBatch() result/notifier = %#v/%#v", result, notifier)
+	}
+}
+
+func TestRunBatchDetailedRetainsPublishedReportBeforeCancellation(t *testing.T) {
+	for _, cause := range []error{context.Canceled, context.DeadlineExceeded} {
+		t.Run(cause.Error(), func(t *testing.T) {
+			bundle := generationBundle(t)
+			bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+			notifier := &generationNotifier{}
+			ctx := &publicationGateContext{Context: context.Background(), err: cause, afterChecks: 4}
+
+			result, err := RunBatchDetailed(ctx, BatchRequest{
+				Config: generationDistributorConfig(), Batch: BatchMorning,
+				Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: t.TempDir(),
+				Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{}, Notifier: notifier,
+			})
+			if !errors.Is(err, cause) || result == nil || result.Total != 2 || result.Succeeded != 1 || result.Failed != 0 || result.Canceled != 1 || len(result.Reports) != 2 || result.Reports[0].Status != "succeeded" || result.Reports[0].OutputPath == "" || result.Reports[1].Status != "canceled" || result.Reports[1].OutputPath != "" || notifier.batchCalls != 0 || result.Notification == nil || result.Notification.Status != "skipped" || result.Notification.Reason != "batch canceled" {
+				t.Fatalf("RunBatchDetailed() result/error/notifier = %#v/%v/%#v", result, err, notifier)
+			}
+			if _, statErr := os.Stat(result.Reports[0].OutputPath); statErr != nil {
+				t.Fatalf("published report %q: %v", result.Reports[0].OutputPath, statErr)
+			}
+		})
+	}
+}
+
+func TestRunBatchPreservesCancellationCause(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	bundle := generationBundle(t)
+	bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+	err := RunBatch(ctx, BatchRequest{
+		Config: generationDistributorConfig(), Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: t.TempDir(),
+		Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{cancelBeforeReturn: cancel}, Notifier: &generationNotifier{},
+	})
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("RunBatch() error = %v", err)
+	}
+}
+
+func TestRunBatchDetailedNotifiesOnlyAfterAllOutputsExist(t *testing.T) {
+	bundle := generationBundle(t)
+	bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+	outputDir := t.TempDir()
+	notifier := &generationNotifier{}
+	result, err := RunBatchDetailed(context.Background(), BatchRequest{
+		Config: generationDistributorConfig(), Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: outputDir,
+		Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{}, Notifier: notifier,
+	})
+	if err != nil || result == nil || result.Total != 2 || result.Succeeded != 2 || result.Failed != 0 || notifier.batchCalls != 1 || result.Notification == nil || result.Notification.Status != "succeeded" {
+		t.Fatalf("RunBatchDetailed() result/error/notifier = %#v/%v/%#v", result, err, notifier)
+	}
+	if len(notifier.batchRequest.Files) < 2 || len(notifier.batchRequest.IncludedReports) != 2 {
+		t.Fatalf("batch notification = %#v", notifier.batchRequest)
+	}
+	if result.Reports[0].OutputPath == result.Reports[1].OutputPath {
+		t.Fatalf("batch reports share output path %q", result.Reports[0].OutputPath)
+	}
+	for _, file := range notifier.batchRequest.Files {
+		if filepath.Dir(file.SourcePath) != outputDir || file.BundlePath == "" {
+			t.Fatalf("notification file = %#v", file)
+		}
+		if _, statErr := os.Stat(file.SourcePath); statErr != nil {
+			t.Fatalf("notification source %q: %v", file.SourcePath, statErr)
+		}
+	}
+}
+
+func TestRunBatchDetailedRejectsUnsupportedDistributorEndpointBeforeWork(t *testing.T) {
+	outputDir := t.TempDir()
+	cfg := generationDistributorConfig()
+	cfg.Notify.Distributor.Endpoint = "ftp://distributor.example.test"
+	bundle := generationBundle(t)
+	collector := &generationCollector{bundle: &bundle}
+	executor := &generationExecutor{}
+	notifier := &generationNotifier{}
+
+	result, err := RunBatchDetailed(context.Background(), BatchRequest{
+		Config: cfg, Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: outputDir,
+		Collector: collector, Executor: executor, Notifier: notifier,
+	})
+	if err == nil || result != nil || collector.called || executor.promptInspections != 0 || executor.called || notifier.calls != 0 || notifier.batchCalls != 0 {
+		t.Fatalf("RunBatchDetailed() result/error/collector/executor/notifier = %#v/%v/%t/%#v/%#v", result, err, collector.called, executor, notifier)
+	}
+	entries, readErr := os.ReadDir(outputDir)
+	if readErr != nil || len(entries) != 0 {
+		t.Fatalf("output directory entries/error = %v/%v", entries, readErr)
+	}
+}
+
+func TestRunBatchDetailedUsesDefaultAndConfiguredOutputDirectories(t *testing.T) {
+	tests := []struct {
+		name      string
+		directory func(t *testing.T, workingDir string) string
+		wantDir   func(t *testing.T, workingDir string, configuredDir string) string
+	}{
+		{
+			name: "working directory default",
+			directory: func(_ *testing.T, _ string) string {
+				return ""
+			},
+			wantDir: func(_ *testing.T, workingDir string, _ string) string {
+				return workingDir
+			},
+		},
+		{
+			name: "absolute directory",
+			directory: func(t *testing.T, _ string) string {
+				return filepath.Join(t.TempDir(), "reports")
+			},
+			wantDir: func(_ *testing.T, _ string, configuredDir string) string {
+				return configuredDir
+			},
+		},
+		{
+			name: "relative directory",
+			directory: func(_ *testing.T, _ string) string {
+				return "configured/../reports"
+			},
+			wantDir: func(_ *testing.T, workingDir string, _ string) string {
+				return filepath.Join(workingDir, "reports")
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			workingDir := t.TempDir()
+			configuredDir := tt.directory(t, workingDir)
+			cfg := generationDistributorConfig()
+			cfg.Output.Directory = configuredDir
+			bundle := generationBundle(t)
+			bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+			notifier := &generationNotifier{}
+
+			result, err := RunBatchDetailed(context.Background(), BatchRequest{
+				Config: cfg, Batch: BatchMorning,
+				Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: workingDir,
+				Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{}, Notifier: notifier,
+			})
+			wantDir := tt.wantDir(t, workingDir, configuredDir)
+			if err != nil || result == nil || result.Succeeded != len(result.Reports) || notifier.batchCalls != 1 {
+				t.Fatalf("RunBatchDetailed() result/error/notifier = %#v/%v/%#v", result, err, notifier)
+			}
+			for _, item := range result.Reports {
+				if filepath.Dir(item.OutputPath) != wantDir {
+					t.Fatalf("report output %q, want directory %q", item.OutputPath, wantDir)
+				}
+			}
+			for _, file := range notifier.batchRequest.Files {
+				if filepath.Dir(file.SourcePath) != wantDir {
+					t.Fatalf("notification source %q, want directory %q", file.SourcePath, wantDir)
+				}
+			}
+		})
+	}
+}
+
+func TestRunBatchDetailedExplicitOutputDirectoryIgnoresConfiguredDirectory(t *testing.T) {
+	configuredPath := filepath.Join(t.TempDir(), "not-a-directory")
+	if err := os.WriteFile(configuredPath, []byte("not a directory"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	explicitDir := t.TempDir()
+	cfg := generationDistributorConfig()
+	cfg.Output.Directory = configuredPath
+	bundle := generationBundle(t)
+	bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+
+	result, err := RunBatchDetailed(context.Background(), BatchRequest{
+		Config: cfg, Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: explicitDir,
+		Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{}, Notifier: &generationNotifier{},
+	})
+	if err != nil || result == nil || result.Succeeded != len(result.Reports) {
+		t.Fatalf("RunBatchDetailed() result/error = %#v/%v", result, err)
+	}
+	for _, item := range result.Reports {
+		if filepath.Dir(item.OutputPath) != explicitDir {
+			t.Fatalf("report output %q, want directory %q", item.OutputPath, explicitDir)
+		}
+	}
+}
+
+func TestRunBatchDetailedPreflightsAllOutputPaths(t *testing.T) {
+	bundle := generationBundle(t)
+	bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+	outputDir := t.TempDir()
+	if err := os.Mkdir(filepath.Join(outputDir, "tomorrow.md"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	todayPath := filepath.Join(outputDir, "today.md")
+	const previousReport = "previous report"
+	if err := os.WriteFile(todayPath, []byte(previousReport), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	executor := &generationExecutor{}
+	promptInspectedBeforeCollection := false
+	collector := &generationCollector{
+		bundle: &bundle,
+		beforeRun: func() {
+			promptInspectedBeforeCollection = executor.promptInspections > 0
+		},
+	}
+	result, err := RunBatchDetailed(context.Background(), BatchRequest{
+		Config: generationDistributorConfig(), Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: outputDir,
+		Collector: collector, Executor: executor, Notifier: &generationNotifier{},
+	})
+	if err == nil || result != nil || !collector.called || !promptInspectedBeforeCollection || executor.called {
+		t.Fatalf("RunBatchDetailed() result/error/collection/inspection/execution = %#v/%v/%t/%t/%t", result, err, collector.called, promptInspectedBeforeCollection, executor.called)
+	}
+	if data, readErr := os.ReadFile(todayPath); readErr != nil || string(data) != previousReport {
+		t.Fatalf("earlier output = %q, error = %v", data, readErr)
+	}
+	if info, statErr := os.Stat(filepath.Join(outputDir, "tomorrow.md")); statErr != nil || !info.IsDir() {
+		t.Fatalf("blocked output info/error = %#v/%v", info, statErr)
+	}
+}
+
+func TestRunBatchDetailedRetainsReportCountsWhenNotificationFails(t *testing.T) {
+	bundle := generationBundle(t)
+	bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+	outputDir := t.TempDir()
+	notifier := &generationNotifier{batchErr: errors.New("distributor unavailable")}
+	result, err := RunBatchDetailed(context.Background(), BatchRequest{
+		Config: generationDistributorConfig(), Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: outputDir,
+		Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{}, Notifier: notifier,
+	})
+	if err != nil || result == nil || result.Total != len(result.Reports) || result.Succeeded != len(result.Reports) || result.Failed != 0 || result.Notification == nil || result.Notification.Status != "failed" {
+		t.Fatalf("RunBatchDetailed() result/error = %#v/%v", result, err)
+	}
+	for _, item := range result.Reports {
+		if item.Status != "succeeded" || item.OutputPath == "" {
+			t.Fatalf("report result = %#v", item)
+		}
+		if _, statErr := os.Stat(item.OutputPath); statErr != nil {
+			t.Fatalf("published output %q: %v", item.OutputPath, statErr)
+		}
+	}
+}
+
+func TestRunBatchReturnsNotificationFailureWithoutReportFailureWording(t *testing.T) {
+	bundle := generationBundle(t)
+	bundle.Hourly.Periods = bundle.Hourly.Periods[:1]
+	err := RunBatch(context.Background(), BatchRequest{
+		Config: generationDistributorConfig(), Batch: BatchMorning,
+		Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputDir: t.TempDir(),
+		Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{}, Notifier: &generationNotifier{batchErr: errors.New("distributor unavailable")},
+	})
+	var batchErr BatchError
+	if !errors.As(err, &batchErr) || batchErr.Result == nil || batchErr.Result.Failed != 0 || batchErr.Result.Notification == nil || batchErr.Result.Notification.Status != "failed" || !strings.Contains(err.Error(), "notification failed") || strings.Contains(err.Error(), "reports failed") {
+		t.Fatalf("RunBatch() error/result = %v/%#v", err, batchErr.Result)
+	}
+}
+
+func generationDistributorConfig() config.Config {
+	cfg := generationConfig()
+	cfg.Notify.Distributor.Enabled = true
+	cfg.Notify.Distributor.PipelineIDTemplate = "weather"
+	return cfg
+}

internal/app/batch_notification.go

@@ -3,12 +3,12 @@ package app
 import (
 	"context"
 	"fmt"
+	"path/filepath"
 	"time"
 
 	distributoradapter "gitea.maximumdirect.net/eric/weatherreporter/internal/adapters/distributor"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/state"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
 )
 
@@ -42,62 +42,67 @@ type batchNotifier interface {
 	NotifyBatch(context.Context, batchNotificationRequest) (*NotificationResult, error)
 }
 
+type batchNotificationInput struct {
+	ctx          context.Context
+	cancellation error
+	cfg          config.Config
+	batch        BatchKind
+	runID        string
+	startedAt    time.Time
+	result       *BatchResult
+	planned      []plannedBatchReport
+	notifier     Notifier
+}
+
 func batchRunID(startedAt time.Time, batch BatchKind) string {
 	return startedAt.UTC().Format(runIDTimestampLayout) + "_" + string(batch)
 }
 
-func notifyBatch(ctx context.Context, cfg config.Config, batch BatchKind, runID string, startedAt time.Time, result *BatchResult, planned []plannedBatchReport, store state.Store, notifier Notifier) (*BatchNotificationResult, error) {
+func notifyBatch(input batchNotificationInput) *BatchNotificationResult {
-	if !cfg.Notify.Distributor.Enabled {
+	if !input.cfg.Notify.Distributor.Enabled {
-		return nil, nil
+		return nil
 	}
-	if !cfg.Notify.Distributor.Batch.Enabled {
+	if !input.cfg.Notify.Distributor.Batch.Enabled {
-		return nil, nil
+		return nil
 	}
-	if result == nil {
+	if input.result == nil {
-		return nil, fmt.Errorf("batch result is required")
+		return failedBatchNotificationResult(batchNotificationRequest{}, fmt.Errorf("batch result is required"))
 	}
-	if result.Failed > 0 {
+	if input.cancellation != nil || batchContextCancellationCause(input.ctx) != nil || input.result.Canceled > 0 {
+		return &BatchNotificationResult{
+			Status: "skipped",
+			Reason: "batch canceled",
+		}
+	}
+	if input.result.Failed > 0 {
 		return &BatchNotificationResult{
 			Status: "skipped",
 			Reason: "one or more reports failed",
-		}, nil
-	}
-
-	req, err := buildBatchNotificationRequest(cfg, batch, runID, startedAt, result.Reports, planned)
-	if err != nil {
-		path, saveErr := saveBatchNotificationArtifact(ctx, store, cfg, batch, runID, startedAt, batchNotificationRequest{}, nil, err)
-		if saveErr != nil {
-			return nil, saveErr
 		}
-		return failedBatchNotificationResult(batchNotificationRequest{}, path, err), err
 	}
 
-	batchNotifier, err := resolveBatchNotifier(cfg, notifier)
+	req, err := buildBatchNotificationRequest(input.cfg, input.batch, input.runID, input.startedAt, input.result.Reports, input.planned)
 	if err != nil {
-		path, saveErr := saveBatchNotificationArtifact(ctx, store, cfg, batch, runID, startedAt, req, nil, err)
+		return failedBatchNotificationResult(batchNotificationRequest{}, err)
-		if saveErr != nil {
-			return nil, saveErr
-		}
-		return failedBatchNotificationResult(req, path, err), err
 	}
 
-	notification, notifyErr := batchNotifier.NotifyBatch(ctx, req)
+	batchNotifier, err := resolveBatchNotifier(input.cfg, input.notifier)
+	if err != nil {
+		return failedBatchNotificationResult(req, err)
+	}
+
+	notification, notifyErr := batchNotifier.NotifyBatch(input.ctx, req)
 	wrappedErr := notifyErr
 	if notifyErr != nil {
-		wrappedErr = fmt.Errorf("notify batch %q run %q bundle %q: %w", batch, runID, req.BundleID, notifyErr)
+		wrappedErr = fmt.Errorf("notify batch %q run %q bundle %q: %w", input.batch, input.runID, req.BundleID, notifyErr)
 	}
-	path, saveErr := saveBatchNotificationArtifact(ctx, store, cfg, batch, runID, startedAt, req, notification, wrappedErr)
+	batchResult := batchNotificationResult(req, notification)
-	if saveErr != nil {
-		return nil, saveErr
-	}
-
-	batchResult := batchNotificationResult(req, notification, path)
 	if wrappedErr != nil {
 		batchResult.Status = "failed"
-		batchResult.Error = wrappedErr.Error()
+		batchResult.Error = safeDistributorNotificationFailure(wrappedErr)
-		return batchResult, wrappedErr
+		return batchResult
 	}
-	return batchResult, nil
+	return batchResult
 }
 
 func resolveBatchNotifier(cfg config.Config, notifier Notifier) (batchNotifier, error) {
@@ -153,15 +158,15 @@ func buildBatchNotificationRequest(cfg config.Config, batch BatchKind, runID str
 		if item.ReportID != plannedReport.Resolved.Definition.ID {
 			return batchNotificationRequest{}, fmt.Errorf("batch notification report %q run %q does not match planned report %q", item.ReportID, item.RunID, plannedReport.Resolved.Definition.ID)
 		}
-		if item.ReportPath == "" {
+		if item.OutputPath == "" {
-			return batchNotificationRequest{}, fmt.Errorf("batch notification report %q run %q is missing managed report path", item.ReportID, item.RunID)
+			return batchNotificationRequest{}, fmt.Errorf("batch notification report %q run %q is missing output path", item.ReportID, item.RunID)
 		}
 
-		values, err := distributorTemplateValuesForReport(cfg, plannedReport.Resolved, item.RunID, plannedReport.OutputCopyName)
+		values, err := distributorTemplateValuesForReport(cfg, plannedReport.Resolved, item.RunID, filepath.Base(item.OutputPath))
 		if err != nil {
-			return batchNotificationRequest{}, fmt.Errorf("batch notification report %q run %q source path %q: %w", item.ReportID, item.RunID, item.ReportPath, err)
+			return batchNotificationRequest{}, fmt.Errorf("batch notification report %q run %q source path %q: %w", item.ReportID, item.RunID, item.OutputPath, err)
 		}
-		bundlePaths, err := renderDistributorReportBundlePaths(cfg, plannedReport.Resolved, item.RunID, item.ReportPath, values)
+		bundlePaths, err := renderDistributorReportBundlePaths(cfg, plannedReport.Resolved, item.RunID, item.OutputPath, values)
 		if err != nil {
 			return batchNotificationRequest{}, err
 		}
@@ -169,18 +174,18 @@ func buildBatchNotificationRequest(cfg config.Config, batch BatchKind, runID str
 		included := BatchNotificationReport{
 			ReportID:    item.ReportID,
 			RunID:       item.RunID,
-			SourcePath:  item.ReportPath,
+			SourcePath:  item.OutputPath,
 			BundlePaths: append([]string(nil), bundlePaths...),
 		}
 		for _, bundlePath := range bundlePaths {
 			file := batchNotificationFile{
 				ReportID:   item.ReportID,
 				RunID:      item.RunID,
-				SourcePath: item.ReportPath,
+				SourcePath: item.OutputPath,
 				BundlePath: bundlePath,
 			}
 			if previous, ok := seenBundlePaths[bundlePath]; ok {
-				return batchNotificationRequest{}, fmt.Errorf("batch notification duplicate bundle path %q for report %q run %q source path %q; already used by report %q run %q source path %q", bundlePath, item.ReportID, item.RunID, item.ReportPath, previous.ReportID, previous.RunID, previous.SourcePath)
+				return batchNotificationRequest{}, fmt.Errorf("batch notification duplicate bundle path %q for report %q run %q source path %q; already used by report %q run %q source path %q", bundlePath, item.ReportID, item.RunID, item.OutputPath, previous.ReportID, previous.RunID, previous.SourcePath)
 			}
 			seenBundlePaths[bundlePath] = file
 			req.Files = append(req.Files, file)
@@ -225,13 +230,12 @@ func batchDistributorUploadRequest(req batchNotificationRequest) distributoradap
 	}
 }
 
-func batchNotificationResult(req batchNotificationRequest, result *NotificationResult, path string) *BatchNotificationResult {
+func batchNotificationResult(req batchNotificationRequest, result *NotificationResult) *BatchNotificationResult {
 	notification := &BatchNotificationResult{
 		Status:          "unknown",
 		PipelineID:      req.PipelineID,
 		BundleID:        req.BundleID,
 		IdempotencyKey:  req.IdempotencyKey,
-		Path:            path,
 		IncludedReports: append([]BatchNotificationReport(nil), req.IncludedReports...),
 	}
 	if result != nil {
@@ -247,7 +251,7 @@ func batchNotificationResult(req batchNotificationRequest, result *NotificationR
 			notification.IdempotencyKey = result.IdempotencyKey
 		}
 		if result.Error != "" {
-			notification.Error = result.Error
+			notification.Error = safeDistributorRunError(result.Error)
 		}
 	}
 	if notification.Status == "" {
@@ -256,85 +260,20 @@ func batchNotificationResult(req batchNotificationRequest, result *NotificationR
 	return notification
 }
 
-func failedBatchNotificationResult(req batchNotificationRequest, path string, err error) *BatchNotificationResult {
+func failedBatchNotificationResult(req batchNotificationRequest, err error) *BatchNotificationResult {
-	notification := batchNotificationResult(req, nil, path)
+	notification := batchNotificationResult(req, nil)
 	notification.Status = "failed"
 	if err != nil {
-		notification.Error = err.Error()
+		notification.Error = safeDistributorNotificationFailure(err)
 	}
 	return notification
 }
 
-func saveBatchNotificationArtifact(ctx context.Context, store state.Store, cfg config.Config, batch BatchKind, runID string, startedAt time.Time, req batchNotificationRequest, result *NotificationResult, notifyErr error) (string, error) {
+func safeDistributorNotificationFailure(err error) string {
-	if store == nil {
+	if err == nil {
-		return "", fmt.Errorf("state store is required")
+		return ""
 	}
-	location, err := timeutil.LoadLocation(cfg.WeatherAPI.Timezone)
+	return "distributor notification failed"
-	if err != nil {
-		return "", fmt.Errorf("load batch notification timezone: %w", err)
-	}
-	artifact := state.BatchDistributorNotificationArtifact{
-		SchemaVersion:  state.BatchDistributorNotificationSchemaVersion,
-		Batch:          string(batch),
-		BatchRunID:     runID,
-		AttemptedAt:    time.Now(),
-		Endpoint:       cfg.Notify.Distributor.Endpoint,
-		PipelineID:     req.PipelineID,
-		BundleID:       req.BundleID,
-		IdempotencyKey: req.IdempotencyKey,
-		BundleCreated:  req.CreatedAt,
-		Reports:        batchNotificationReportArtifacts(req.IncludedReports),
-		Status:         "attempted",
-	}
-	if result != nil {
-		artifact.Status = result.Status
-		artifact.Upload = &state.DistributorUploadResult{
-			RunID:  result.RunID,
-			Status: result.UploadStatus,
-		}
-		if result.PipelineID != "" || !result.AcceptedAt.IsZero() || result.StartedAt != nil || result.FinishedAt != nil || len(result.Report) > 0 || result.Error != "" {
-			artifact.RunStatus = &state.DistributorRunStatus{
-				RunID:      result.RunID,
-				PipelineID: result.PipelineID,
-				Status:     result.Status,
-				AcceptedAt: result.AcceptedAt,
-				StartedAt:  result.StartedAt,
-				FinishedAt: result.FinishedAt,
-				Report:     append([]byte(nil), result.Report...),
-				Error:      result.Error,
-			}
-		}
-		artifact.StatusError = result.StatusError
-	}
-	if notifyErr != nil {
-		artifact.Status = "failed"
-		artifact.Error = notifyErr.Error()
-	}
-	if artifact.Status == "" {
-		artifact.Status = "unknown"
-	}
-	return store.SaveBatchDistributorNotification(ctx, state.BatchDistributorNotificationRef{
-		Batch:      string(batch),
-		BatchRunID: runID,
-		StartedAt:  startedAt,
-		Location:   location,
-	}, artifact)
-}
-
-func batchNotificationReportArtifacts(reports []BatchNotificationReport) []state.BatchDistributorNotificationReportArtifact {
-	if len(reports) == 0 {
-		return nil
-	}
-	artifacts := make([]state.BatchDistributorNotificationReportArtifact, 0, len(reports))
-	for _, item := range reports {
-		artifacts = append(artifacts, state.BatchDistributorNotificationReportArtifact{
-			ReportID:    item.ReportID,
-			RunID:       item.RunID,
-			SourcePath:  item.SourcePath,
-			BundlePaths: append([]string(nil), item.BundlePaths...),
-		})
-	}
-	return artifacts
 }
 
 func renderBatchNotificationIdentity(cfg config.Config, batch BatchKind, runID string, startedAt time.Time) (batchNotificationIdentity, error) {

internal/app/batch_plan.go

@@ -11,8 +11,8 @@ import (
 )
 
 type plannedBatchReport struct {
-	Resolved       report.Resolved
+	Resolved   report.Resolved
-	OutputCopyName string
+	OutputPath string
 }
 
 func planBatchRun(req BatchRequest, now time.Time, collection collect.Result) ([]plannedBatchReport, error) {
@@ -36,16 +36,16 @@ func planBatchRun(req BatchRequest, now time.Time, collection collect.Result) ([
 	var planned []plannedBatchReport
 	switch batch {
 	case report.Morning:
-		planned, err = appendPlannedReport(planned, registry, report.Today, resolveReq, "")
+		planned, err = appendPlannedReport(planned, registry, report.Today, resolveReq)
 		if err != nil {
 			return nil, err
 		}
-		planned, err = appendPlannedReport(planned, registry, report.Tomorrow, resolveReq, "")
+		planned, err = appendPlannedReport(planned, registry, report.Tomorrow, resolveReq)
 		if err != nil {
 			return nil, err
 		}
 	case report.Evening:
-		planned, err = appendPlannedReport(planned, registry, report.Tomorrow, resolveReq, "")
+		planned, err = appendPlannedReport(planned, registry, report.Tomorrow, resolveReq)
 		if err != nil {
 			return nil, err
 		}
@@ -60,8 +60,7 @@ func planBatchRun(req BatchRequest, now time.Time, collection collect.Result) ([
 	for _, date := range eligibleDailyDates(hourly, now, location) {
 		dailyReq := resolveReq
 		dailyReq.Date = date
-		outputCopyName := "daily-" + date.In(location).Format(timeutil.DateLayout) + ".md"
+		planned, err = appendPlannedReport(planned, registry, report.Daily, dailyReq)
-		planned, err = appendPlannedReport(planned, registry, report.Daily, dailyReq, outputCopyName)
 		if err != nil {
 			return nil, err
 		}
@@ -69,15 +68,12 @@ func planBatchRun(req BatchRequest, now time.Time, collection collect.Result) ([
 	return planned, nil
 }
 
-func appendPlannedReport(planned []plannedBatchReport, registry report.Registry, id report.ID, req report.ResolveRequest, outputCopyName string) ([]plannedBatchReport, error) {
+func appendPlannedReport(planned []plannedBatchReport, registry report.Registry, id report.ID, req report.ResolveRequest) ([]plannedBatchReport, error) {
 	resolved, err := registry.Resolve(id, req)
 	if err != nil {
 		return nil, err
 	}
-	return append(planned, plannedBatchReport{
+	return append(planned, plannedBatchReport{Resolved: resolved}), nil
-		Resolved:       resolved,
-		OutputCopyName: outputCopyName,
-	}), nil
 }
 
 func eligibleDailyDates(hourly *weatherdata.ForecastRun, now time.Time, location *time.Location) []time.Time {

internal/app/batch_plan_test.go

@@ -55,20 +55,7 @@ func TestPlanBatchRunDynamicDailyDatesStartAfterTomorrow(t *testing.T) {
 	assertPlanningPeriod(t, daily[1].Resolved.ValidPeriod, "2026-06-01T00:00:00-05:00", "2026-06-02T00:00:00-05:00")
 }
 
-func TestPlanBatchRunMorningExcludesLegacyStaticReports(t *testing.T) {
+func TestPlanBatchRunUsesResolvedOutputNames(t *testing.T) {
-	planned, err := planBatchRun(BatchRequest{Config: planningConfig(), Batch: BatchMorning}, mustParse("2026-05-29T08:00:00-05:00"), collect.Result{Bundle: &weatherdata.Bundle{}})
-	if err != nil {
-		t.Fatalf("planBatchRun() error = %v", err)
-	}
-
-	for _, item := range planned {
-		if item.Resolved.Definition.ID == report.ThreeDay || item.Resolved.Definition.ID == report.Weekend {
-			t.Fatalf("morning plan includes %s, want no 3-Day or Weekend", item.Resolved.Definition.ID)
-		}
-	}
-}
-
-func TestPlanBatchRunDynamicDailyOutputCopyNames(t *testing.T) {
 	location := mustLoadTestLocation(t, "America/Chicago")
 	hourly := hourlyRun(fullDayPeriods(t, "2026-05-31", location)...)
 
@@ -81,11 +68,19 @@ func TestPlanBatchRunDynamicDailyOutputCopyNames(t *testing.T) {
 	if len(daily) != 1 {
 		t.Fatalf("daily reports = %#v, want one Daily report", daily)
 	}
-	if daily[0].OutputCopyName != "daily-2026-05-31.md" {
+	outputName, err := daily[0].Resolved.OutputName()
-		t.Fatalf("OutputCopyName = %q, want date-qualified Daily name", daily[0].OutputCopyName)
+	if err != nil {
+		t.Fatalf("OutputName() error = %v", err)
 	}
-	if planned[0].OutputCopyName != "" {
+	if outputName != "daily-2026-05-31.md" {
-		t.Fatalf("Tomorrow OutputCopyName = %q, want definition batch output name to apply later", planned[0].OutputCopyName)
+		t.Fatalf("Daily output name = %q, want date-qualified name", outputName)
+	}
+	outputName, err = planned[0].Resolved.OutputName()
+	if err != nil {
+		t.Fatalf("OutputName() error = %v", err)
+	}
+	if outputName != "tomorrow.md" {
+		t.Fatalf("Tomorrow output name = %q, want tomorrow.md", outputName)
 	}
 }
 

internal/app/comparison.go

@@ -0,0 +1,243 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/comparison"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptdebug"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+// ComparisonRequest describes one explicit, multi-profile report comparison.
+// It deliberately does not accept a notifier: comparison publication is local.
+type ComparisonRequest struct {
+	Config      config.Config
+	Report      ReportKind
+	ProfileIDs  []string
+	WorkingDir  string
+	OutputDir   string
+	Replace     bool
+	LLMDebugDir string
+	Date        time.Time
+	Clock       timeutil.Clock
+	Collector   Collector
+	Executor    promptexec.Executor
+}
+
+// ComparisonResult records the resolved comparison and profile outcomes.
+type ComparisonResult struct {
+	ComparisonID    string
+	ReportID        report.ID
+	ReportName      string
+	PromptID        string
+	PromptVersion   string
+	PromptHash      string
+	StartedAt       time.Time
+	FinishedAt      time.Time
+	Timezone        string
+	ValidPeriod     timeutil.Period
+	OutputDirectory string
+	ManifestPath    string
+	DataPackagePath string
+	Total           int
+	Succeeded       int
+	Failed          int
+	Results         []ComparisonProfileResult
+}
+
+// ComparisonProfileResult records one explicitly selected profile.
+type ComparisonProfileResult struct {
+	Position         int
+	ProfileID        string
+	BackendID        string
+	ModelName        string
+	Status           string
+	ValidationStatus promptexec.ValidationStatus
+	RepairAttempts   *int
+	ReportPath       string
+	LLMDebugPath     string
+	Error            *comparison.SafeError
+}
+
+type comparisonPublisher func(context.Context, comparison.DestinationPlan, comparison.LogicalBundle) (comparison.PublicationResult, error)
+
+// CompareDetailed assembles, executes, and atomically publishes a comparison
+// bundle. Profile failures publish a complete partial bundle. Failures before
+// commit leave the destination untouched; a post-commit cleanup failure leaves
+// the new bundle installed and returns its artifact paths with an error.
+func CompareDetailed(ctx context.Context, req ComparisonRequest) (*ComparisonResult, error) {
+	return compareDetailed(ctx, req, comparison.Publish)
+}
+
+func compareDetailed(ctx context.Context, req ComparisonRequest, publish comparisonPublisher) (*ComparisonResult, error) {
+	if err := comparison.ValidateProfileIDs(req.ProfileIDs); err != nil {
+		return nil, err
+	}
+
+	clock := req.Clock
+	if clock == nil {
+		clock = timeutil.SystemClock{}
+	}
+	now := clock.Now()
+	resolved, err := ResolveGenerate(GenerateRequest{Config: req.Config, Report: req.Report, Date: req.Date}, now)
+	if err != nil {
+		return nil, err
+	}
+	metadata := resolved.Metadata()
+	comparisonID, err := comparison.BuildComparisonID(metadata.RunID)
+	if err != nil {
+		return nil, fmt.Errorf("build comparison identity: %w", err)
+	}
+	result := initialComparisonResult(req, resolved, comparisonID, now.UTC())
+	defer func() {
+		if result.FinishedAt.IsZero() {
+			finalizeComparisonResult(result, clock)
+		}
+	}()
+
+	outputName, err := resolved.OutputName()
+	if err != nil {
+		return result, fmt.Errorf("resolve comparison output name: %w", err)
+	}
+	outputDirectory, err := resolveComparisonOutputDirectory(req.WorkingDir, req.OutputDir, req.Config.Output.Directory, outputName)
+	if err != nil {
+		return result, err
+	}
+	result.OutputDirectory = outputDirectory
+	publicationPlan, err := comparison.PlanDestination(req.WorkingDir, outputDirectory, req.Replace)
+	if err != nil {
+		return result, fmt.Errorf("preflight comparison destination: %w", err)
+	}
+
+	debugWriter, err := promptdebug.NewPromptDebugWriter(req.LLMDebugDir)
+	if err != nil {
+		return result, promptexec.NewError(promptexec.InvalidConfiguration, "initialize prompt debug", err)
+	}
+	defer func() { _ = debugWriter.Close() }()
+	inspection, err := InspectComparisonExecution(ctx, ComparisonInspectionRequest{
+		Resolved: resolved, ProfileIDs: req.ProfileIDs, Executor: req.Executor,
+	})
+	result.PromptID, result.PromptVersion, result.PromptHash = inspection.PromptID, inspection.PromptVersion, inspection.PromptHash
+	if err != nil {
+		return result, err
+	}
+
+	collection, err := collectWeather(ctx, req.Config, req.Collector)
+	if err != nil {
+		return result, err
+	}
+	prepared, err := prepareReport(prepareReportRequest{Config: req.Config, Resolved: resolved, Collection: *collection, handler: inspection.handler})
+	if err != nil {
+		return result, fmt.Errorf("prepare comparison report: %w", err)
+	}
+
+	executed := executeComparisonProfiles(ctx, comparisonExecutionRequest{
+		Prepared: prepared, Inspection: inspection, ComparisonID: comparisonID, DebugWriter: debugWriter, Executor: req.Executor,
+	})
+	finalizeComparisonResult(result, clock)
+	copyComparisonOutcomes(result, executed.Outcomes, false)
+	if executed.Canceled {
+		return result, fmt.Errorf("comparison execution: %w", ctx.Err())
+	}
+
+	bundle := comparisonBundle(result, prepared.dataPackageCopy(), executed.Outcomes)
+	if err := bundle.Validate(); err != nil {
+		return result, fmt.Errorf("build comparison bundle: %w", err)
+	}
+	publication, err := publish(ctx, publicationPlan, bundle)
+	if publication.Committed {
+		result.OutputDirectory = publicationPlan.Target
+		result.ManifestPath = filepath.Join(publicationPlan.Target, comparison.ManifestFilename)
+		result.DataPackagePath = filepath.Join(publicationPlan.Target, comparison.DataPackageFilename)
+		copyComparisonOutcomes(result, executed.Outcomes, true)
+	}
+	if err != nil {
+		return result, fmt.Errorf("publish comparison bundle: %w", err)
+	}
+
+	if result.Failed > 0 {
+		return result, fmt.Errorf("comparison completed with %d failed profiles", result.Failed)
+	}
+	return result, nil
+}
+
+func finalizeComparisonResult(result *ComparisonResult, clock timeutil.Clock) {
+	finishedAt := clock.Now().UTC()
+	if finishedAt.IsZero() {
+		finishedAt = time.Unix(0, 1).UTC()
+	}
+	if finishedAt.Before(result.StartedAt) {
+		finishedAt = result.StartedAt
+	}
+	result.FinishedAt = finishedAt
+}
+
+func initialComparisonResult(req ComparisonRequest, resolved report.Resolved, comparisonID string, startedAt time.Time) *ComparisonResult {
+	metadata := resolved.Metadata()
+	return &ComparisonResult{
+		ComparisonID: comparisonID,
+		ReportID:     resolved.Definition.ID,
+		ReportName:   resolved.Definition.Name,
+		StartedAt:    startedAt,
+		Timezone:     req.Config.WeatherAPI.Timezone,
+		ValidPeriod:  metadata.ValidPeriod,
+	}
+}
+
+func copyComparisonOutcomes(result *ComparisonResult, outcomes []comparisonProfileOutcome, published bool) {
+	result.Results = make([]ComparisonProfileResult, len(outcomes))
+	result.Total, result.Succeeded, result.Failed = len(outcomes), 0, 0
+	for index, outcome := range outcomes {
+		profile := ComparisonProfileResult{
+			Position: outcome.Position, ProfileID: outcome.ProfileID, BackendID: outcome.BackendID, ModelName: outcome.ModelName,
+			Status: outcome.Status, ValidationStatus: outcome.ValidationStatus, LLMDebugPath: outcome.LLMDebugPath, Error: outcome.Error,
+		}
+		if outcome.RepairAttempts != nil {
+			profile.RepairAttempts = repairAttemptsPointer(*outcome.RepairAttempts)
+		}
+		if published && outcome.Status == comparison.StatusSucceeded {
+			profile.ReportPath = filepath.Join(result.OutputDirectory, outcome.ReportPath)
+		}
+		result.Results[index] = profile
+		if outcome.Status == comparison.StatusSucceeded {
+			result.Succeeded++
+		} else {
+			result.Failed++
+		}
+	}
+}
+
+func comparisonBundle(result *ComparisonResult, dataPackage []byte, outcomes []comparisonProfileOutcome) comparison.LogicalBundle {
+	manifest := comparison.Manifest{
+		SchemaVersion: comparison.SchemaVersion, ComparisonID: result.ComparisonID,
+		StartedAt: result.StartedAt.UTC(), FinishedAt: result.FinishedAt.UTC(),
+		ReportID: string(result.ReportID), Timezone: result.Timezone,
+		ValidPeriod: comparison.ValidPeriod{Start: result.ValidPeriod.Start, End: result.ValidPeriod.End},
+		PromptID:    result.PromptID, PromptVersion: result.PromptVersion, PromptHash: result.PromptHash,
+		DataPackage: comparison.DataPackageReference{Path: comparison.DataPackageFilename, SHA256: comparison.SHA256(dataPackage)},
+		Total:       result.Total, Succeeded: result.Succeeded, Failed: result.Failed,
+		Results: make([]comparison.Result, len(outcomes)),
+	}
+	bundle := comparison.LogicalBundle{Manifest: manifest, DataPackage: dataPackage}
+	for index, outcome := range outcomes {
+		manifestResult := comparison.Result{
+			Position: outcome.Position, ProfileID: outcome.ProfileID, BackendID: outcome.BackendID, ModelName: outcome.ModelName,
+			Status: outcome.Status, ValidationStatus: string(outcome.ValidationStatus), Error: outcome.Error,
+		}
+		if outcome.RepairAttempts != nil {
+			manifestResult.RepairAttempts = repairAttemptsPointer(*outcome.RepairAttempts)
+		}
+		if outcome.Status == comparison.StatusSucceeded {
+			manifestResult.ReportPath = outcome.ReportPath
+			bundle.Reports = append(bundle.Reports, comparison.BundleReport{Position: outcome.Position, Path: outcome.ReportPath, Markdown: outcome.Markdown})
+		}
+		bundle.Manifest.Results[index] = manifestResult
+	}
+	return bundle
+}

internal/app/comparison_execution.go

@@ -0,0 +1,186 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/comparison"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptdebug"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+)
+
+type comparisonExecutionRequest struct {
+	Prepared     preparedReport
+	Inspection   ComparisonInspectionResult
+	ComparisonID string
+	DebugWriter  *promptdebug.PromptDebugWriter
+	Executor     promptexec.Executor
+}
+
+type comparisonExecutionResult struct {
+	Outcomes []comparisonProfileOutcome
+	Canceled bool
+}
+
+type comparisonProfileOutcome struct {
+	Position         int
+	ProfileID        string
+	BackendID        string
+	ModelName        string
+	Status           string
+	ValidationStatus promptexec.ValidationStatus
+	RepairAttempts   *int
+	ReportPath       string
+	Markdown         []byte
+	LLMDebugPath     string
+	Error            *comparison.SafeError
+	canceled         bool
+}
+
+type comparisonProfileExecutionState uint8
+
+const (
+	comparisonProfilePending comparisonProfileExecutionState = iota
+	comparisonProfileRunning
+	comparisonProfileComplete
+)
+
+func executeComparisonProfiles(ctx context.Context, req comparisonExecutionRequest) comparisonExecutionResult {
+	profiles := req.Inspection.Profiles
+	result := comparisonExecutionResult{Outcomes: make([]comparisonProfileOutcome, len(profiles))}
+	states := make([]comparisonProfileExecutionState, len(profiles))
+	for index, profile := range profiles {
+		result.Outcomes[index] = comparisonProfileOutcome{
+			Position:  index + 1,
+			ProfileID: profile.ProfileID,
+			BackendID: profile.BackendID,
+			ModelName: profile.ModelName,
+			Status:    comparison.StatusFailed,
+		}
+	}
+
+	var waitGroup sync.WaitGroup
+	for index, profile := range profiles {
+		if err := ctx.Err(); err != nil {
+			result.Canceled = true
+			break
+		}
+		index, profile := index, profile
+		states[index] = comparisonProfileRunning
+		waitGroup.Add(1)
+		go func() {
+			defer waitGroup.Done()
+			result.Outcomes[index] = executeComparisonProfile(ctx, req, index, profile)
+			states[index] = comparisonProfileComplete
+		}()
+	}
+	waitGroup.Wait()
+	if err := ctx.Err(); err != nil {
+		result.Canceled = true
+		for index := range result.Outcomes {
+			if states[index] != comparisonProfileComplete || result.Outcomes[index].canceled {
+				markCanceledComparisonOutcome(&result.Outcomes[index], err)
+			}
+		}
+	}
+	return result
+}
+
+func executeComparisonProfile(ctx context.Context, req comparisonExecutionRequest, index int, profile ComparisonProfileInspection) comparisonProfileOutcome {
+	position := index + 1
+	outcome := comparisonProfileOutcome{
+		Position: position, ProfileID: profile.ProfileID, BackendID: profile.BackendID, ModelName: profile.ModelName,
+		Status: comparison.StatusFailed,
+	}
+	debugRef := promptdebug.PromptDebugRef{
+		ReportID:  req.Prepared.resolved.Definition.ID,
+		ValidDate: req.Prepared.resolved.ValidPeriod.Start.Format("2006-01-02"),
+		RunID:     comparisonDebugRunID(req.ComparisonID, position, len(req.Inspection.Profiles), profile.ProfileID),
+	}
+	execution, markdown, err := executePreparedProfile(ctx, profileExecutionRequest{
+		Prepared: req.Prepared,
+		Prompt: PromptInspectionResult{
+			PromptID: req.Inspection.PromptID, PromptVersion: req.Inspection.PromptVersion, PromptHash: req.Inspection.PromptHash,
+		},
+		Profile:  promptexec.ProfileInspection{ProfileID: profile.ProfileID, BackendID: profile.BackendID, ModelName: profile.ModelName},
+		Executor: req.Executor, DebugWriter: req.DebugWriter, DebugRef: &debugRef,
+	})
+	outcome.ProfileID, outcome.BackendID, outcome.ModelName = execution.ProfileID, execution.BackendID, execution.ModelName
+	outcome.ValidationStatus = execution.ValidationStatus
+	if execution.RepairAttempts != nil {
+		outcome.RepairAttempts = repairAttemptsPointer(*execution.RepairAttempts)
+	}
+	outcome.LLMDebugPath = execution.LLMDebugPath
+	if err != nil {
+		outcome.canceled = cancellationError(err)
+		safe := comparisonSafeExecutionError(err)
+		outcome.Error = &safe
+		return outcome
+	}
+	reportPath, err := comparison.ReportFilename(position, len(req.Inspection.Profiles), profile.ProfileID)
+	if err != nil {
+		safe := comparison.NewSafeError("application", "derive comparison report filename failed")
+		outcome.Error = &safe
+		return outcome
+	}
+	outcome.Status = comparison.StatusSucceeded
+	outcome.ReportPath = reportPath
+	outcome.Markdown = append([]byte(nil), markdown...)
+	return outcome
+}
+
+func comparisonDebugRunID(comparisonID string, position, profileCount int, profileID string) string {
+	return fmt.Sprintf("%s_%0*d-%s", comparisonID, comparison.OrdinalWidth(profileCount), position, comparison.ProfileSlug(profileID))
+}
+
+func markCanceledComparisonOutcome(outcome *comparisonProfileOutcome, err error) {
+	outcome.Status = comparison.StatusFailed
+	outcome.ValidationStatus = promptexec.ValidationSkipped
+	outcome.ReportPath = ""
+	outcome.Markdown = nil
+	safe := comparisonSafeExecutionError(err)
+	outcome.Error = &safe
+}
+
+func cancellationError(err error) bool {
+	category := promptexec.CategoryOf(err)
+	return errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) ||
+		category == promptexec.Canceled || category == promptexec.DeadlineExceeded
+}
+
+func comparisonSafeExecutionError(err error) comparison.SafeError {
+	category := promptexec.CategoryOf(err)
+	if category == "" {
+		switch {
+		case errors.Is(err, context.Canceled):
+			category = promptexec.Canceled
+		case errors.Is(err, context.DeadlineExceeded):
+			category = promptexec.DeadlineExceeded
+		}
+	}
+	if category == "" {
+		return comparison.NewSafeError("application", comparisonExecutionMessage(err))
+	}
+	return comparison.NewSafeError(string(category), comparisonExecutionMessage(err))
+}
+
+func comparisonExecutionMessage(err error) string {
+	if errors.Is(err, context.Canceled) {
+		return "profile execution canceled"
+	}
+	if errors.Is(err, context.DeadlineExceeded) {
+		return "profile execution deadline exceeded"
+	}
+	operation := "profile execution"
+	var execution *profileExecutionError
+	if errors.As(err, &execution) {
+		operation = execution.operation
+	}
+	var generation *promptexec.GenerationError
+	if errors.As(err, &generation) && generation.StatusCode() > 0 {
+		return comparison.TruncateErrorMessage(fmt.Sprintf("%s failed (HTTP %d)", operation, generation.StatusCode()))
+	}
+	return comparison.TruncateErrorMessage(operation + " failed")
+}

internal/app/comparison_execution_test.go

@@ -0,0 +1,401 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/comparison"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptdebug"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+)
+
+func TestExecuteComparisonProfilesRunsOrderedProfilesConcurrently(t *testing.T) {
+	prepared, prompt := preparedDailyProfile(t)
+	profiles := comparisonProfiles(10)
+	executor := newBarrierExecutor(profiles)
+	results := startComparisonExecution(t, context.Background(), comparisonExecutionRequest{
+		Prepared: prepared, Inspection: comparisonInspection(prompt, profiles), ComparisonID: "comparison_daily", Executor: executor,
+	}, executor)
+	waitForProfileStarts(t, executor, profiles, results)
+	if executor.maximumInFlight() < 2 {
+		t.Fatalf("maximum in-flight executions = %d, want overlap", executor.maximumInFlight())
+	}
+	for index := len(profiles) - 1; index >= 0; index-- {
+		executor.release(profiles[index].ProfileID)
+	}
+	result := <-results
+	if result.Canceled || len(result.Outcomes) != len(profiles) {
+		t.Fatalf("result = %#v", result)
+	}
+	for index, profile := range profiles {
+		outcome := result.Outcomes[index]
+		wantPath, err := comparison.ReportFilename(index+1, len(profiles), profile.ProfileID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if outcome.Position != index+1 || outcome.ProfileID != profile.ProfileID || outcome.Status != comparison.StatusSucceeded || outcome.ValidationStatus != promptexec.ValidationPassed || outcome.ReportPath != wantPath || len(outcome.Markdown) == 0 || outcome.Error != nil {
+			t.Fatalf("outcome[%d] = %#v", index, outcome)
+		}
+		request, ok := executor.request(profile.ProfileID)
+		if !ok || request.PromptVersion != prompt.PromptVersion || !bytesEqual(request.DataPackage, prepared.dataPackage) {
+			t.Fatalf("request for %q = %#v, want prompt version %q and shared data package", profile.ProfileID, request, prompt.PromptVersion)
+		}
+	}
+}
+
+func TestExecuteComparisonProfilesContinuesAfterProfileFailure(t *testing.T) {
+	prepared, prompt := preparedDailyProfile(t)
+	profiles := comparisonProfiles(3)
+	executor := newBarrierExecutor(profiles)
+	executor.setError(profiles[1].ProfileID, errors.New("provider response body must not escape"))
+	results := startComparisonExecution(t, context.Background(), comparisonExecutionRequest{
+		Prepared: prepared, Inspection: comparisonInspection(prompt, profiles), ComparisonID: "comparison_daily", Executor: executor,
+	}, executor)
+	waitForProfileStarts(t, executor, profiles, results)
+	for _, profile := range profiles {
+		executor.release(profile.ProfileID)
+	}
+	result := <-results
+	if result.Canceled || result.Outcomes[0].Status != comparison.StatusSucceeded || result.Outcomes[1].Status != comparison.StatusFailed || result.Outcomes[2].Status != comparison.StatusSucceeded {
+		t.Fatalf("outcomes = %#v", result.Outcomes)
+	}
+	failure := result.Outcomes[1]
+	if failure.Error == nil || failure.Error.Category != string(promptexec.Generation) || failure.Error.Message != "execute prompt failed" || failure.ReportPath != "" || len(failure.Markdown) != 0 {
+		t.Fatalf("failure outcome = %#v", failure)
+	}
+}
+
+func TestExecuteComparisonProfilesPreservesIndependentRepairOutcomes(t *testing.T) {
+	prepared, prompt := preparedDailyProfile(t)
+	profiles := comparisonProfiles(4)
+	executor := newBarrierExecutor(profiles)
+	executor.setValidation(profiles[0].ProfileID, promptexec.ValidationPassed, 0)
+	executor.setValidation(profiles[1].ProfileID, promptexec.ValidationPassed, 1)
+	executor.setValidation(profiles[2].ProfileID, promptexec.ValidationFailed, 1)
+	executor.setError(profiles[3].ProfileID, errors.New("provider failure"))
+	results := startComparisonExecution(t, context.Background(), comparisonExecutionRequest{
+		Prepared: prepared, Inspection: comparisonInspection(prompt, profiles), ComparisonID: "comparison_daily", Executor: executor,
+	}, executor)
+	waitForProfileStarts(t, executor, profiles, results)
+	executor.releaseAll()
+	result := <-results
+	wantStatuses := []string{comparison.StatusSucceeded, comparison.StatusSucceeded, comparison.StatusFailed, comparison.StatusFailed}
+	wantValidations := []promptexec.ValidationStatus{promptexec.ValidationPassed, promptexec.ValidationPassed, promptexec.ValidationFailed, ""}
+	wantRepairs := []*int{intPointer(0), intPointer(1), intPointer(1), nil}
+	for index, outcome := range result.Outcomes {
+		if outcome.Status != wantStatuses[index] || outcome.ValidationStatus != wantValidations[index] || !reflect.DeepEqual(outcome.RepairAttempts, wantRepairs[index]) {
+			t.Fatalf("outcome[%d] = %#v, want status/validation/repairs %q/%q/%#v", index, outcome, wantStatuses[index], wantValidations[index], wantRepairs[index])
+		}
+	}
+}
+
+func TestExecuteComparisonProfilesCapturesConcurrentProviderFailures(t *testing.T) {
+	prepared, prompt := preparedDailyProfile(t)
+	profiles := comparisonProfiles(2)
+	debugWriter, err := promptdebug.NewPromptDebugWriter(t.TempDir())
+	if errors.Is(err, promptdebug.ErrSecureCaptureUnsupported) {
+		t.Skipf("secure prompt debug capture is unavailable: %v", err)
+	}
+	if err != nil {
+		t.Fatalf("NewPromptDebugWriter() error = %v", err)
+	}
+	markers := []string{"first-provider-private-marker", "second-provider-private-marker"}
+	statuses := []int{http.StatusTooManyRequests, http.StatusServiceUnavailable}
+	executor := newBarrierExecutor(profiles)
+	for index, profile := range profiles {
+		executor.setError(profile.ProfileID, promptexec.NewGenerationError(statuses[index], "provider_code", "provider_type", markers[index], nil))
+	}
+	results := startComparisonExecution(t, context.Background(), comparisonExecutionRequest{
+		Prepared: prepared, Inspection: comparisonInspection(prompt, profiles), ComparisonID: "comparison_daily", DebugWriter: debugWriter, Executor: executor,
+	}, executor)
+	waitForProfileStarts(t, executor, profiles, results)
+	executor.releaseAll()
+	result := <-results
+	for index, outcome := range result.Outcomes {
+		if outcome.Status != comparison.StatusFailed || outcome.Error == nil || outcome.Error.Category != string(promptexec.Generation) || outcome.Error.Message != fmt.Sprintf("execute prompt failed (HTTP %d)", statuses[index]) || strings.Contains(outcome.Error.Message, markers[index]) || outcome.LLMDebugPath == "" {
+			t.Fatalf("outcome[%d] = %#v", index, outcome)
+		}
+		failure, readErr := os.ReadFile(filepath.Join(outcome.LLMDebugPath, "failure.json"))
+		if readErr != nil {
+			t.Fatal(readErr)
+		}
+		if !strings.Contains(string(failure), markers[index]) || strings.Contains(string(failure), markers[1-index]) {
+			t.Fatalf("failure[%d] = %s", index, failure)
+		}
+	}
+}
+
+func TestExecuteComparisonProfilesPropagatesCancellationAndJoins(t *testing.T) {
+	prepared, prompt := preparedDailyProfile(t)
+	profiles := comparisonProfiles(4)
+	executor := newBarrierExecutor(profiles)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	results := startComparisonExecution(t, ctx, comparisonExecutionRequest{
+		Prepared: prepared, Inspection: comparisonInspection(prompt, profiles), ComparisonID: "comparison_daily", Executor: executor,
+	}, executor)
+	waitForProfileStarts(t, executor, profiles, results)
+	cancel()
+	result := <-results
+	if !result.Canceled || executor.inFlightCount() != 0 {
+		t.Fatalf("result/in-flight = %#v/%d", result, executor.inFlightCount())
+	}
+	for _, outcome := range result.Outcomes {
+		if outcome.Status != comparison.StatusFailed || outcome.Error == nil || outcome.Error.Category != string(promptexec.Canceled) || outcome.ValidationStatus != promptexec.ValidationSkipped || outcome.ReportPath != "" || len(outcome.Markdown) != 0 {
+			t.Fatalf("canceled outcome = %#v", outcome)
+		}
+	}
+}
+
+func TestExecuteComparisonProfilesUsesDistinctDeterministicDebugReferences(t *testing.T) {
+	prepared, prompt := preparedDailyProfile(t)
+	profiles := []ComparisonProfileInspection{
+		{ProfileID: "light.one", BackendID: "local", ModelName: "light"},
+		{ProfileID: "deep/two", BackendID: "cloud", ModelName: "deep"},
+	}
+	debugWriter, err := promptdebug.NewPromptDebugWriter(t.TempDir())
+	if errors.Is(err, promptdebug.ErrSecureCaptureUnsupported) {
+		t.Skipf("secure prompt debug capture is unavailable: %v", err)
+	}
+	if err != nil {
+		t.Fatalf("NewPromptDebugWriter() error = %v", err)
+	}
+	executor := newBarrierExecutor(profiles)
+	results := startComparisonExecution(t, context.Background(), comparisonExecutionRequest{
+		Prepared: prepared, Inspection: comparisonInspection(prompt, profiles), ComparisonID: "comparison_daily", DebugWriter: debugWriter, Executor: executor,
+	}, executor)
+	waitForProfileStarts(t, executor, profiles, results)
+	for _, profile := range profiles {
+		executor.release(profile.ProfileID)
+	}
+	result := <-results
+	paths := map[string]struct{}{}
+	for index, outcome := range result.Outcomes {
+		wantName := fmt.Sprintf("comparison_daily_%0*d-%s", comparison.OrdinalWidth(len(profiles)), index+1, comparison.ProfileSlug(outcome.ProfileID))
+		if filepath.Base(outcome.LLMDebugPath) != wantName {
+			t.Fatalf("debug path = %q, want base %q", outcome.LLMDebugPath, wantName)
+		}
+		if _, err := os.Stat(filepath.Join(outcome.LLMDebugPath, "preparation.json")); err != nil {
+			t.Fatalf("preparation artifact %q: %v", outcome.LLMDebugPath, err)
+		}
+		paths[outcome.LLMDebugPath] = struct{}{}
+	}
+	if len(paths) != len(profiles) {
+		t.Fatalf("debug paths = %#v", paths)
+	}
+}
+
+type barrierExecutor struct {
+	mu               sync.Mutex
+	started          chan string
+	callbackFailures chan error
+	releases         map[string]chan struct{}
+	requests         map[string]promptexec.ExecuteRequest
+	errors           map[string]error
+	validations      map[string]promptexec.ValidationStatus
+	repairAttempts   map[string]int
+	profiles         map[string]ComparisonProfileInspection
+	inFlight         int
+	maximum          int
+}
+
+func newBarrierExecutor(profiles []ComparisonProfileInspection) *barrierExecutor {
+	releases := make(map[string]chan struct{}, len(profiles))
+	identities := make(map[string]ComparisonProfileInspection, len(profiles))
+	for _, profile := range profiles {
+		releases[profile.ProfileID] = make(chan struct{})
+		identities[profile.ProfileID] = profile
+	}
+	return &barrierExecutor{
+		started: make(chan string, len(profiles)), callbackFailures: make(chan error, len(profiles)), releases: releases,
+		requests: make(map[string]promptexec.ExecuteRequest, len(profiles)), errors: map[string]error{}, validations: map[string]promptexec.ValidationStatus{}, repairAttempts: map[string]int{}, profiles: identities,
+	}
+}
+
+func (e *barrierExecutor) InspectPrompt(context.Context, string, string) (promptexec.PromptInspection, error) {
+	return promptexec.PromptInspection{}, errors.New("unexpected prompt inspection")
+}
+
+func (e *barrierExecutor) InspectProfile(context.Context, string) (promptexec.ProfileInspection, error) {
+	return promptexec.ProfileInspection{}, errors.New("unexpected profile inspection")
+}
+
+func (e *barrierExecutor) Execute(ctx context.Context, req promptexec.ExecuteRequest, callback promptexec.PreparationCallback) (*promptexec.Execution, error) {
+	stamp := time.Date(2026, 5, 29, 15, 0, 0, 0, time.UTC)
+	e.mu.Lock()
+	profile := e.profiles[req.ProfileID]
+	e.mu.Unlock()
+	definition := generationDefinitionForPrompt(req.PromptID)
+	if err := callback(promptexec.Preparation{PromptID: req.PromptID, PromptVersion: req.PromptVersion, PromptHash: generationPromptHash, ProfileID: req.ProfileID, BackendID: profile.BackendID, ModelName: profile.ModelName, Output: promptexec.OutputContract{Format: "json", ValidationMode: "json_schema", SchemaPath: definition.GeneratedTextSchemaID + ".generated_text.schema.json", RepairAttempts: definition.GeneratedTextRepairAttempts}, StartedAt: stamp, EndedAt: stamp}, nil); err != nil {
+		e.callbackFailures <- err
+		return nil, err
+	}
+	e.mu.Lock()
+	e.requests[req.ProfileID] = promptexec.ExecuteRequest{PromptID: req.PromptID, PromptVersion: req.PromptVersion, ProfileID: req.ProfileID, DataPackage: append([]byte(nil), req.DataPackage...), CaptureDebug: req.CaptureDebug}
+	e.inFlight++
+	if e.inFlight > e.maximum {
+		e.maximum = e.inFlight
+	}
+	release := e.releases[req.ProfileID]
+	e.mu.Unlock()
+	e.started <- req.ProfileID
+	select {
+	case <-release:
+	case <-ctx.Done():
+		e.mu.Lock()
+		e.inFlight--
+		e.mu.Unlock()
+		return nil, ctx.Err()
+	}
+	e.mu.Lock()
+	e.inFlight--
+	err := e.errors[req.ProfileID]
+	validationStatus := e.validations[req.ProfileID]
+	repairAttempts := e.repairAttempts[req.ProfileID]
+	e.mu.Unlock()
+	if err != nil {
+		return nil, err
+	}
+	if validationStatus == "" {
+		validationStatus = promptexec.ValidationPassed
+	}
+	return &promptexec.Execution{
+		PromptID: req.PromptID, PromptVersion: req.PromptVersion, PromptHash: generationPromptHash,
+		ProfileID: req.ProfileID, BackendID: profile.BackendID, ModelName: profile.ModelName,
+		StartedAt: stamp, EndedAt: stamp, RawOutput: comparisonRawOutput(),
+		Validation: promptexec.NewValidation(validationStatus, "json_schema", generationDefinitionForPrompt(req.PromptID).GeneratedTextSchemaID+".generated_text.schema.json", repairAttempts, nil),
+	}, nil
+}
+
+func (e *barrierExecutor) request(profileID string) (promptexec.ExecuteRequest, bool) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	request, ok := e.requests[profileID]
+	return request, ok
+}
+
+func (e *barrierExecutor) setError(profileID string, err error) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.errors[profileID] = err
+}
+
+func (e *barrierExecutor) setValidation(profileID string, status promptexec.ValidationStatus, repairAttempts int) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.validations[profileID] = status
+	e.repairAttempts[profileID] = repairAttempts
+}
+
+func (e *barrierExecutor) release(profileID string) {
+	close(e.releases[profileID])
+}
+
+func (e *barrierExecutor) releaseAll() {
+	for _, release := range e.releases {
+		select {
+		case <-release:
+		default:
+			close(release)
+		}
+	}
+}
+
+func (e *barrierExecutor) maximumInFlight() int {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	return e.maximum
+}
+
+func (e *barrierExecutor) inFlightCount() int {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	return e.inFlight
+}
+
+const comparisonExecutionTestTimeout = 5 * time.Second
+
+func startComparisonExecution(t *testing.T, ctx context.Context, request comparisonExecutionRequest, executor *barrierExecutor) <-chan comparisonExecutionResult {
+	t.Helper()
+	results := make(chan comparisonExecutionResult, 1)
+	finished := make(chan struct{})
+	t.Cleanup(func() {
+		executor.releaseAll()
+		timeout := time.NewTimer(comparisonExecutionTestTimeout)
+		defer timeout.Stop()
+		select {
+		case <-finished:
+		case <-timeout.C:
+			t.Error("comparison execution workers did not finish after release")
+		}
+	})
+	go func() {
+		defer close(finished)
+		results <- executeComparisonProfiles(ctx, request)
+	}()
+	return results
+}
+
+func waitForProfileStarts(t *testing.T, executor *barrierExecutor, profiles []ComparisonProfileInspection, results <-chan comparisonExecutionResult) {
+	t.Helper()
+	timeout := time.NewTimer(comparisonExecutionTestTimeout)
+	defer timeout.Stop()
+	seen := map[string]struct{}{}
+	for range profiles {
+		var profileID string
+		select {
+		case profileID = <-executor.started:
+		case err := <-executor.callbackFailures:
+			executor.releaseAll()
+			select {
+			case result := <-results:
+				t.Fatalf("comparison profile preparation failed before executor entry: %v; result: %#v", err, result)
+			case <-timeout.C:
+				t.Fatalf("comparison profile preparation failed before executor entry: %v; comparison did not finish", err)
+			}
+		case result := <-results:
+			t.Fatalf("comparison completed before all profiles started: %#v", result)
+		case <-timeout.C:
+			t.Fatal("timed out waiting for comparison profile starts")
+		}
+		if _, duplicate := seen[profileID]; duplicate {
+			t.Fatalf("duplicate execution start for %q", profileID)
+		}
+		seen[profileID] = struct{}{}
+	}
+}
+
+func comparisonProfiles(count int) []ComparisonProfileInspection {
+	profiles := make([]ComparisonProfileInspection, 0, count)
+	for index := 1; index <= count; index++ {
+		profiles = append(profiles, ComparisonProfileInspection{ProfileID: fmt.Sprintf("profile.%02d", index), BackendID: "backend", ModelName: "model"})
+	}
+	return profiles
+}
+
+func comparisonInspection(prompt PromptInspectionResult, profiles []ComparisonProfileInspection) ComparisonInspectionResult {
+	return ComparisonInspectionResult{PromptID: prompt.PromptID, PromptVersion: prompt.PromptVersion, PromptHash: prompt.PromptHash, Profiles: profiles}
+}
+
+func comparisonRawOutput() []byte {
+	return []byte(`{"summary":"Showers are possible during the selected day.","forecast_discussion":["A front will keep rain chances in the forecast."],"precipitation_timing":"Rain is most likely during the afternoon."}`)
+}
+
+func bytesEqual(left, right []byte) bool {
+	return reflect.DeepEqual(left, right)
+}
+
+func intPointer(value int) *int {
+	return &value
+}
+
+var _ promptexec.Executor = (*barrierExecutor)(nil)

internal/app/comparison_test.go

@@ -0,0 +1,433 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/comparison"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+func TestCompareDetailedPublishesOneCoherentBundle(t *testing.T) {
+	cfg := comparisonConfig()
+	bundle := generationBundle(t)
+	workingDir := t.TempDir()
+	executor := &generationExecutor{}
+	inspectedBeforeCollection := false
+	result, err := CompareDetailed(context.Background(), ComparisonRequest{
+		Config: cfg, Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+		WorkingDir: workingDir, Date: generationTime("2026-05-29T12:00:00-05:00"),
+		Clock: timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")},
+		Collector: &generationCollector{bundle: &bundle, beforeRun: func() {
+			inspectedBeforeCollection = executor.promptInspections == 1 && executor.profileInspections == 2
+		}}, Executor: executor,
+	})
+	if err != nil {
+		t.Fatalf("CompareDetailed() error = %v", err)
+	}
+	if result == nil || result.Total != 2 || result.Succeeded != 2 || result.Failed != 0 || executor.promptInspections != 1 || executor.profileInspections != 2 || executor.executeCalls != 2 || !inspectedBeforeCollection || result.ManifestPath == "" || result.DataPackagePath == "" {
+		t.Fatalf("result/executor = %#v/%#v", result, executor)
+	}
+	if result.OutputDirectory != filepath.Dir(result.ManifestPath) || !filepath.IsAbs(result.ManifestPath) || !filepath.IsAbs(result.DataPackagePath) {
+		t.Fatalf("published paths = %#v", result)
+	}
+	for index, profile := range result.Results {
+		if profile.Position != index+1 || profile.Status != comparison.StatusSucceeded || !filepath.IsAbs(profile.ReportPath) || profile.Error != nil {
+			t.Fatalf("profile result = %#v", profile)
+		}
+	}
+	data, readErr := os.ReadFile(result.ManifestPath)
+	if readErr != nil {
+		t.Fatal(readErr)
+	}
+	var manifest comparison.Manifest
+	if err := json.Unmarshal(data, &manifest); err != nil {
+		t.Fatal(err)
+	}
+	if manifest.ComparisonID != result.ComparisonID || manifest.Total != result.Total || manifest.Succeeded != result.Succeeded || manifest.DataPackage.SHA256 == "" || len(manifest.Results) != 2 {
+		t.Fatalf("manifest = %#v", manifest)
+	}
+	if manifest.Results[0].ReportPath != filepath.Base(result.Results[0].ReportPath) || manifest.Results[1].ReportPath != filepath.Base(result.Results[1].ReportPath) {
+		t.Fatalf("manifest report paths = %#v", manifest.Results)
+	}
+}
+
+func TestCompareDetailedPublishesPartialBundleAndReturnsAggregateError(t *testing.T) {
+	cfg := comparisonConfig()
+	bundle := generationBundle(t)
+	executor := &generationExecutor{executeErrors: map[string]error{"weather-deep": errors.New("provider detail must not escape")}}
+	result, err := CompareDetailed(context.Background(), ComparisonRequest{
+		Config: cfg, Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep", "weather-fallback"},
+		WorkingDir: t.TempDir(), Date: generationTime("2026-05-29T12:00:00-05:00"),
+		Clock:     timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")},
+		Collector: &generationCollector{bundle: &bundle}, Executor: executor,
+	})
+	if err == nil || err.Error() != "comparison completed with 1 failed profiles" || result == nil || result.Total != 3 || result.Succeeded != 2 || result.Failed != 1 {
+		t.Fatalf("CompareDetailed() result/error = %#v/%v", result, err)
+	}
+	failure := result.Results[1]
+	if failure.Status != comparison.StatusFailed || failure.ReportPath != "" || failure.Error == nil || strings.Contains(failure.Error.Message, "provider detail") {
+		t.Fatalf("failure = %#v", failure)
+	}
+	if _, statErr := os.Stat(result.ManifestPath); statErr != nil {
+		t.Fatalf("partial manifest: %v", statErr)
+	}
+	if _, statErr := os.Stat(filepath.Join(result.OutputDirectory, filepath.Base(result.Results[0].ReportPath))); statErr != nil {
+		t.Fatalf("successful partial report: %v", statErr)
+	}
+}
+
+func TestCompareDetailedPublishesPostValidationProfileFailure(t *testing.T) {
+	bundle := generationBundle(t)
+	executor := &generationExecutor{complete: func(execution *promptexec.Execution) {
+		if execution.ProfileID == "weather-deep" {
+			execution.RawOutput = []byte(`{"summary":42}`)
+		}
+	}}
+	result, err := CompareDetailed(context.Background(), ComparisonRequest{
+		Config: comparisonConfig(), Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+		WorkingDir: t.TempDir(), Date: generationTime("2026-05-29T12:00:00-05:00"),
+		Clock:     timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")},
+		Collector: &generationCollector{bundle: &bundle}, Executor: executor,
+	})
+	if err == nil || result == nil || result.Succeeded != 1 || result.Failed != 1 || result.ManifestPath == "" {
+		t.Fatalf("CompareDetailed() result/error = %#v/%v", result, err)
+	}
+	failure := result.Results[1]
+	if failure.Status != comparison.StatusFailed || failure.ValidationStatus != promptexec.ValidationPassed || failure.RepairAttempts == nil || *failure.RepairAttempts != 0 {
+		t.Fatalf("post-validation failure = %#v", failure)
+	}
+	data, readErr := os.ReadFile(result.ManifestPath)
+	if readErr != nil {
+		t.Fatal(readErr)
+	}
+	var manifest comparison.Manifest
+	if decodeErr := json.Unmarshal(data, &manifest); decodeErr != nil {
+		t.Fatal(decodeErr)
+	}
+	manifestFailure := manifest.Results[1]
+	if manifestFailure.ValidationStatus != "passed" || manifestFailure.RepairAttempts == nil || *manifestFailure.RepairAttempts != 0 {
+		t.Fatalf("published post-validation failure = %#v", manifestFailure)
+	}
+}
+
+func TestCompareDetailedRetainsCommittedPathsWhenBackupCleanupFails(t *testing.T) {
+	for _, test := range []struct {
+		name  string
+		state comparison.BackupRecoveryState
+		path  bool
+	}{
+		{name: "complete recovery bundle", state: comparison.BackupRecoveryComplete, path: true},
+		{name: "partial remnants", state: comparison.BackupRecoveryPartial, path: true},
+		{name: "absent backup", state: comparison.BackupRecoveryAbsent},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			bundle := generationBundle(t)
+			recoveryPath := ""
+			if test.path {
+				recoveryPath = filepath.Join(t.TempDir(), ".comparison-daily.backup-recovery")
+			}
+			cleanupCause := errors.New("backup cleanup failed")
+			publish := func(context.Context, comparison.DestinationPlan, comparison.LogicalBundle) (comparison.PublicationResult, error) {
+				return comparison.PublicationResult{Committed: true, RecoveryState: test.state, RecoveryPath: recoveryPath}, &comparison.PublicationCleanupError{RecoveryState: test.state, RecoveryPath: recoveryPath, Err: cleanupCause}
+			}
+
+			result, err := compareDetailed(context.Background(), ComparisonRequest{
+				Config: comparisonConfig(), Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+				WorkingDir: t.TempDir(), Date: generationTime("2026-05-29T12:00:00-05:00"),
+				Clock:     timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")},
+				Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{},
+			}, publish)
+			var cleanupErr *comparison.PublicationCleanupError
+			if result == nil || !errors.As(err, &cleanupErr) || !errors.Is(err, cleanupCause) || cleanupErr.RecoveryState != test.state || cleanupErr.RecoveryPath != recoveryPath || !filepath.IsAbs(result.ManifestPath) || !filepath.IsAbs(result.DataPackagePath) {
+				t.Fatalf("CompareDetailed() result/error = %#v/%v", result, err)
+			}
+			for _, profile := range result.Results {
+				if profile.Status == comparison.StatusSucceeded && !filepath.IsAbs(profile.ReportPath) {
+					t.Fatalf("published profile result = %#v", profile)
+				}
+			}
+		})
+	}
+}
+
+func TestCompareDetailedPreflightsBeforePromptOrCollection(t *testing.T) {
+	invalidDestination := filepath.Join(t.TempDir(), "not-a-directory")
+	if err := os.WriteFile(invalidDestination, []byte("x"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	bundle := generationBundle(t)
+	collector := &generationCollector{bundle: &bundle}
+	executor := &generationExecutor{}
+	result, err := CompareDetailed(context.Background(), ComparisonRequest{
+		Config: comparisonConfig(), Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+		WorkingDir: t.TempDir(), OutputDir: invalidDestination, Date: generationTime("2026-05-29T12:00:00-05:00"),
+		Clock: timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")}, Collector: collector, Executor: executor,
+	})
+	if err == nil || result == nil || collector.called || executor.promptInspections != 0 || executor.executeCalls != 0 || result.ManifestPath != "" {
+		t.Fatalf("result/error/collector/executor = %#v/%v/%#v/%#v", result, err, collector, executor)
+	}
+}
+
+func TestCompareDetailedFinalizesUnpublishedFailures(t *testing.T) {
+	for _, test := range []struct {
+		name           string
+		prepare        func(t *testing.T, outputDirectory string)
+		debugDir       string
+		executor       *generationExecutor
+		collector      *generationCollector
+		wantPrompt     bool
+		wantCollection bool
+	}{
+		{
+			name: "destination preflight",
+			prepare: func(t *testing.T, outputDirectory string) {
+				t.Helper()
+				if err := os.WriteFile(outputDirectory, []byte("not a directory"), 0o600); err != nil {
+					t.Fatal(err)
+				}
+			},
+			executor: &generationExecutor{},
+		},
+		{
+			name:      "debug initialization",
+			debugDir:  "relative-debug-directory",
+			executor:  &generationExecutor{},
+			collector: &generationCollector{},
+		},
+		{
+			name:       "prompt preflight",
+			executor:   &generationExecutor{inspectErr: promptexec.NewError(promptexec.PromptLoad, "unsafe prompt detail", errors.New("unsafe cause"))},
+			collector:  &generationCollector{},
+			wantPrompt: false,
+		},
+		{
+			name: "profile preflight",
+			executor: &generationExecutor{profileInspectErrors: map[string]error{
+				"weather-deep": promptexec.NewError(promptexec.MissingCredential, "profile credential is unavailable", errors.New("unsafe cause")),
+			}},
+			collector:  &generationCollector{},
+			wantPrompt: true,
+		},
+		{
+			name:           "collection",
+			executor:       &generationExecutor{},
+			collector:      &generationCollector{err: errors.New("collection failed")},
+			wantPrompt:     true,
+			wantCollection: true,
+		},
+		{
+			name:           "preparation",
+			executor:       &generationExecutor{},
+			collector:      &generationCollector{bundle: &weatherdata.Bundle{}},
+			wantPrompt:     true,
+			wantCollection: true,
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			workingDirectory := t.TempDir()
+			outputDirectory := filepath.Join(workingDirectory, "comparison-output")
+			if test.prepare != nil {
+				test.prepare(t, outputDirectory)
+			}
+			collector := test.collector
+			if collector == nil {
+				bundle := generationBundle(t)
+				collector = &generationCollector{bundle: &bundle}
+			}
+			result, err := CompareDetailed(context.Background(), ComparisonRequest{
+				Config: comparisonConfig(), Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+				WorkingDir: workingDirectory, OutputDir: outputDirectory, LLMDebugDir: test.debugDir,
+				Date: generationTime("2026-05-29T12:00:00-05:00"), Clock: timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")},
+				Collector: collector, Executor: test.executor,
+			})
+			if err == nil {
+				t.Fatal("CompareDetailed() error = nil")
+			}
+			assertUnpublishedComparisonResult(t, result, outputDirectory)
+			if (result.PromptID != "") != test.wantPrompt || (result.PromptHash != "") != test.wantPrompt {
+				t.Fatalf("prompt identity = %q/%q, want resolved=%t", result.PromptID, result.PromptHash, test.wantPrompt)
+			}
+			if collector.called != test.wantCollection || test.executor.executeCalls != 0 {
+				t.Fatalf("collection/execution = %t/%d, want collection=%t and no execution", collector.called, test.executor.executeCalls, test.wantCollection)
+			}
+		})
+	}
+}
+
+func TestCompareDetailedLeavesDestinationWhenCollectionOrPreparationFails(t *testing.T) {
+	collectionErr := errors.New("weather collection failed")
+	for _, test := range []struct {
+		name      string
+		collector *generationCollector
+	}{
+		{name: "collection", collector: &generationCollector{err: collectionErr}},
+		{name: "preparation", collector: &generationCollector{bundle: &weatherdata.Bundle{}}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			workingDir := t.TempDir()
+			executor := &generationExecutor{}
+			result, err := CompareDetailed(context.Background(), ComparisonRequest{
+				Config: comparisonConfig(), Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+				WorkingDir: workingDir, Date: generationTime("2026-05-29T12:00:00-05:00"),
+				Clock: timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")}, Collector: test.collector, Executor: executor,
+			})
+			if err == nil || result == nil || executor.executeCalls != 0 || result.ManifestPath != "" || result.DataPackagePath != "" {
+				t.Fatalf("CompareDetailed() result/error/executor = %#v/%v/%#v", result, err, executor)
+			}
+			if _, statErr := os.Stat(filepath.Join(workingDir, "comparison-daily-2026-05-29")); !os.IsNotExist(statErr) {
+				t.Fatalf("comparison destination stat error = %v", statErr)
+			}
+		})
+	}
+}
+
+func TestCompareDetailedPublishesManifestWhenEveryProfileFails(t *testing.T) {
+	bundle := generationBundle(t)
+	executor := &generationExecutor{executeErrors: map[string]error{
+		"weather-light": errors.New("first provider failure"), "weather-deep": errors.New("second provider failure"),
+	}}
+	result, err := CompareDetailed(context.Background(), ComparisonRequest{
+		Config: comparisonConfig(), Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+		WorkingDir: t.TempDir(), Date: generationTime("2026-05-29T12:00:00-05:00"),
+		Clock:     timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")},
+		Collector: &generationCollector{bundle: &bundle}, Executor: executor,
+	})
+	if err == nil || err.Error() != "comparison completed with 2 failed profiles" || result == nil || result.Succeeded != 0 || result.Failed != 2 || result.ManifestPath == "" {
+		t.Fatalf("CompareDetailed() result/error = %#v/%v", result, err)
+	}
+	for _, profile := range result.Results {
+		if profile.ReportPath != "" || profile.Error == nil {
+			t.Fatalf("failed profile = %#v", profile)
+		}
+	}
+}
+
+func TestCompareDetailedCancellationPreservesPublishedBundle(t *testing.T) {
+	workingDir := t.TempDir()
+	bundle := generationBundle(t)
+	request := ComparisonRequest{
+		Config: comparisonConfig(), Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+		WorkingDir: workingDir, Date: generationTime("2026-05-29T12:00:00-05:00"),
+		Clock: timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")}, Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{},
+	}
+	previous, err := CompareDetailed(context.Background(), request)
+	if err != nil {
+		t.Fatalf("initial CompareDetailed() error = %v", err)
+	}
+	before, err := os.ReadFile(previous.ManifestPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	request.Replace = true
+	request.Executor = &generationExecutor{cancelBeforeReturn: cancel}
+	result, err := CompareDetailed(ctx, request)
+	if !errors.Is(err, context.Canceled) || result == nil || result.ManifestPath != "" || result.DataPackagePath != "" {
+		t.Fatalf("canceled CompareDetailed() result/error = %#v/%v", result, err)
+	}
+	after, readErr := os.ReadFile(previous.ManifestPath)
+	if readErr != nil || string(after) != string(before) {
+		t.Fatalf("published manifest changed = %q, error = %v", after, readErr)
+	}
+}
+
+func TestCompareDetailedPreservesCompletedProfileFailureWhenCanceled(t *testing.T) {
+	bundle := generationBundle(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	failureStarted := make(chan struct{})
+	var signalFailure sync.Once
+	executor := &generationExecutor{
+		validations:         map[string]promptexec.ValidationStatus{"weather-light": promptexec.ValidationFailed},
+		waitForCancellation: map[string]bool{"weather-deep": true},
+		beforeExecute: func(request promptexec.ExecuteRequest) {
+			if request.ProfileID == "weather-light" {
+				signalFailure.Do(func() { close(failureStarted) })
+			}
+		},
+	}
+	results := make(chan struct {
+		result *ComparisonResult
+		err    error
+	}, 1)
+	go func() {
+		result, err := CompareDetailed(ctx, ComparisonRequest{
+			Config: comparisonConfig(), Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+			WorkingDir: t.TempDir(), Date: generationTime("2026-05-29T12:00:00-05:00"),
+			Clock:     timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")},
+			Collector: &generationCollector{bundle: &bundle}, Executor: executor,
+		})
+		results <- struct {
+			result *ComparisonResult
+			err    error
+		}{result: result, err: err}
+	}()
+
+	select {
+	case <-failureStarted:
+		cancel()
+	case <-time.After(5 * time.Second):
+		t.Fatal("timed out waiting for the completed profile failure")
+	}
+	completed := <-results
+	if !errors.Is(completed.err, context.Canceled) || completed.result == nil || completed.result.ManifestPath != "" || completed.result.DataPackagePath != "" || completed.result.Succeeded != 0 || completed.result.Failed != 2 {
+		t.Fatalf("CompareDetailed() result/error = %#v/%v", completed.result, completed.err)
+	}
+	failed, canceled := completed.result.Results[0], completed.result.Results[1]
+	if failed.Error == nil || failed.Error.Category != string(promptexec.ValidationRejected) || failed.ValidationStatus != promptexec.ValidationFailed || failed.ReportPath != "" {
+		t.Fatalf("completed failure = %#v", failed)
+	}
+	if canceled.Error == nil || canceled.Error.Category != string(promptexec.Canceled) || canceled.ValidationStatus != promptexec.ValidationSkipped || canceled.ReportPath != "" {
+		t.Fatalf("canceled profile = %#v", canceled)
+	}
+}
+
+func TestCompareDetailedLeavesExistingBundleWhenPublicationPreflightChanges(t *testing.T) {
+	workingDir := t.TempDir()
+	target := filepath.Join(workingDir, "comparison-output")
+	bundle := generationBundle(t)
+	executor := &generationExecutor{beforeExecute: func(promptexec.ExecuteRequest) {
+		_ = os.WriteFile(target, []byte("changed"), 0o600)
+	}}
+	result, err := CompareDetailed(context.Background(), ComparisonRequest{
+		Config: comparisonConfig(), Report: ReportDaily, ProfileIDs: []string{"weather-light", "weather-deep"},
+		WorkingDir: workingDir, OutputDir: target, Date: generationTime("2026-05-29T12:00:00-05:00"),
+		Clock: timeutil.FixedClock{Time: generationTime("2026-05-29T08:30:00-05:00")}, Collector: &generationCollector{bundle: &bundle}, Executor: executor,
+	})
+	if err == nil || result == nil || result.ManifestPath != "" || result.DataPackagePath != "" || result.Results[0].ReportPath != "" {
+		t.Fatalf("CompareDetailed() result/error = %#v/%v", result, err)
+	}
+	data, readErr := os.ReadFile(target)
+	if readErr != nil || string(data) != "changed" {
+		t.Fatalf("destination = %q, error = %v", data, readErr)
+	}
+}
+
+func comparisonConfig() config.Config {
+	cfg := config.Defaults()
+	cfg.WeatherAPI.Timezone, cfg.Location.ID = "America/Chicago", "home"
+	return cfg
+}
+
+func assertUnpublishedComparisonResult(t *testing.T, result *ComparisonResult, outputDirectory string) {
+	t.Helper()
+	if result == nil || result.OutputDirectory != outputDirectory || !filepath.IsAbs(result.OutputDirectory) || result.FinishedAt.IsZero() || result.FinishedAt.Location() != time.UTC || result.FinishedAt.Before(result.StartedAt) || result.ManifestPath != "" || result.DataPackagePath != "" {
+		t.Fatalf("unpublished comparison result = %#v", result)
+	}
+	for _, profile := range result.Results {
+		if profile.ReportPath != "" {
+			t.Fatalf("unpublished profile result = %#v", profile)
+		}
+	}
+}

internal/app/distributor_notification_test.go

@@ -0,0 +1,45 @@
+package app
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	distributoradapter "gitea.maximumdirect.net/eric/weatherreporter/internal/adapters/distributor"
+)
+
+func TestNotificationResultFromUploadExcludesRemoteResponseDetails(t *testing.T) {
+	const remote = "REMOTE-DIAGNOSTIC"
+	notification := notificationResultFromUpload("weather", "bundle", "key", distributoradapter.UploadResult{
+		RunID: "run-123", Status: "failed", UploadStatus: "accepted", StatusError: remote,
+		RunStatus: &distributoradapter.RunStatus{PipelineID: "weather", Status: "failed", Report: []byte(`{"detail":"REMOTE-DIAGNOSTIC"}`), Error: remote},
+	})
+	if notification == nil || notification.StatusError != "distributor status could not be confirmed" || notification.Error != "distributor reported a failed run" || len(notification.Report) != 0 {
+		t.Fatalf("notification = %#v", notification)
+	}
+	if strings.Contains(notification.StatusError, remote) || strings.Contains(notification.Error, remote) {
+		t.Fatalf("notification includes remote detail: %#v", notification)
+	}
+}
+
+func TestBatchNotificationResultExcludesRemoteResponseDetails(t *testing.T) {
+	const remote = "REMOTE-DIAGNOSTIC"
+	notification := batchNotificationResult(batchNotificationRequest{PipelineID: "weather", BundleID: "bundle", IdempotencyKey: "key"}, &NotificationResult{Status: "failed", Error: remote})
+	if notification == nil || notification.Error != "distributor reported a failed run" {
+		t.Fatalf("notification = %#v", notification)
+	}
+	if strings.Contains(notification.Error, remote) {
+		t.Fatalf("notification includes remote detail: %#v", notification)
+	}
+}
+
+func TestFailedBatchNotificationResultExcludesRemoteResponseDetails(t *testing.T) {
+	const remote = "REMOTE-DIAGNOSTIC"
+	notification := failedBatchNotificationResult(batchNotificationRequest{PipelineID: "weather", BundleID: "bundle", IdempotencyKey: "key"}, errors.New(remote))
+	if notification == nil || notification.Error != "distributor notification failed" {
+		t.Fatalf("notification = %#v", notification)
+	}
+	if strings.Contains(notification.Error, remote) {
+		t.Fatalf("notification includes remote detail: %#v", notification)
+	}
+}

internal/app/generation_test.go

@@ -0,0 +1,673 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/collect"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptdebug"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/testutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+type generationCollector struct {
+	bundle    *weatherdata.Bundle
+	err       error
+	called    bool
+	calls     int
+	beforeRun func()
+}
+
+type publicationGateContext struct {
+	context.Context
+	err         error
+	checks      int
+	afterChecks int
+}
+
+func (c *publicationGateContext) Err() error {
+	c.checks++
+	afterChecks := c.afterChecks
+	if afterChecks == 0 {
+		afterChecks = 2
+	}
+	if c.checks >= afterChecks {
+		return c.err
+	}
+	return nil
+}
+
+func (c *generationCollector) Run(context.Context, collect.Request) (*collect.Result, error) {
+	if c.beforeRun != nil {
+		c.beforeRun()
+	}
+	c.called = true
+	c.calls++
+	return &collect.Result{Bundle: c.bundle}, c.err
+}
+
+type generationExecutor struct {
+	called               bool
+	executeCalls         int
+	promptInspections    int
+	profileInspections   int
+	inspectErr           error
+	profileInspectErrors map[string]error
+	executeErr           error
+	executeErrors        map[string]error
+	beforeExecute        func(promptexec.ExecuteRequest)
+	cancelBeforeReturn   context.CancelFunc
+	validation           promptexec.ValidationStatus
+	repairAttempts       int
+	validations          map[string]promptexec.ValidationStatus
+	rawOutput            []byte
+	waitForCancellation  map[string]bool
+	failedPrompt         string
+	skipPreparation      bool
+	preparationCalls     int
+	prepare              func(*promptexec.Preparation)
+	complete             func(*promptexec.Execution)
+}
+
+var generationExecutorMu sync.Mutex
+
+func (e *generationExecutor) InspectPrompt(_ context.Context, id, version string) (promptexec.PromptInspection, error) {
+	generationExecutorMu.Lock()
+	defer generationExecutorMu.Unlock()
+	e.promptInspections++
+	if e.inspectErr != nil {
+		return promptexec.PromptInspection{}, e.inspectErr
+	}
+	definition := generationDefinitionForPrompt(id)
+	return promptexec.PromptInspection{PromptID: id, PromptVersion: version, PromptHash: generationPromptHash, DefaultProfileID: "fixture", Inputs: []promptexec.InputDefinition{{Name: "data_package", Required: true, ContentType: "application/yaml"}}, Output: promptexec.OutputContract{Format: "json", ValidationMode: "json_schema", SchemaPath: definition.GeneratedTextSchemaID + ".generated_text.schema.json", RepairAttempts: definition.GeneratedTextRepairAttempts}}, nil
+}
+func (e *generationExecutor) InspectProfile(_ context.Context, id string) (promptexec.ProfileInspection, error) {
+	generationExecutorMu.Lock()
+	defer generationExecutorMu.Unlock()
+	e.profileInspections++
+	if err := e.profileInspectErrors[id]; err != nil {
+		return promptexec.ProfileInspection{}, err
+	}
+	return promptexec.ProfileInspection{ProfileID: id, BackendID: "fixture", ModelName: "fixture-model"}, nil
+}
+func (e *generationExecutor) Execute(ctx context.Context, req promptexec.ExecuteRequest, callback promptexec.PreparationCallback) (*promptexec.Execution, error) {
+	stamp := time.Date(2026, 5, 29, 15, 0, 0, 0, time.UTC)
+	generationExecutorMu.Lock()
+	skipPreparation := e.skipPreparation
+	prepare := e.prepare
+	preparationCalls := e.preparationCalls
+	generationExecutorMu.Unlock()
+	if !skipPreparation {
+		calls := preparationCalls
+		if calls == 0 {
+			calls = 1
+		}
+		for range calls {
+			definition := generationDefinitionForPrompt(req.PromptID)
+			preparation := promptexec.Preparation{PromptID: req.PromptID, PromptVersion: req.PromptVersion, PromptHash: generationPromptHash, RenderedPromptHash: "rendered-hash", ProfileID: req.ProfileID, BackendID: "fixture", ModelName: "fixture-model", Output: promptexec.OutputContract{Format: "json", ValidationMode: "json_schema", SchemaPath: definition.GeneratedTextSchemaID + ".generated_text.schema.json", RepairAttempts: definition.GeneratedTextRepairAttempts}, StartedAt: stamp, EndedAt: stamp}
+			if prepare != nil {
+				prepare(&preparation)
+			}
+			if err := callback(preparation, nil); err != nil {
+				return nil, err
+			}
+		}
+	}
+	generationExecutorMu.Lock()
+	e.called = true
+	e.executeCalls++
+	beforeExecute := e.beforeExecute
+	profileErr := e.executeErrors[req.ProfileID]
+	executeErr := e.executeErr
+	status := e.validation
+	repairAttempts := e.repairAttempts
+	if profileStatus, ok := e.validations[req.ProfileID]; ok {
+		status = profileStatus
+	}
+	rawOutput := append([]byte(nil), e.rawOutput...)
+	waitForCancellation := e.waitForCancellation[req.ProfileID]
+	failedPrompt := e.failedPrompt
+	cancelBeforeReturn := e.cancelBeforeReturn
+	complete := e.complete
+	generationExecutorMu.Unlock()
+	if beforeExecute != nil {
+		beforeExecute(req)
+	}
+	if waitForCancellation {
+		<-ctx.Done()
+		return nil, ctx.Err()
+	}
+	if profileErr != nil {
+		return nil, profileErr
+	}
+	if executeErr != nil {
+		return nil, executeErr
+	}
+	if status == "" {
+		status = promptexec.ValidationPassed
+	}
+	if failedPrompt == req.PromptID {
+		status = promptexec.ValidationFailed
+	}
+	if rawOutput == nil {
+		rawOutput = []byte(`{"summary":"Showers are possible during the selected day.","forecast_discussion":["A front will keep rain chances in the forecast."],"precipitation_timing":"Rain is most likely during the afternoon."}`)
+	}
+	if cancelBeforeReturn != nil {
+		cancelBeforeReturn()
+	}
+	execution := &promptexec.Execution{RunID: "provider-run", PromptID: req.PromptID, PromptVersion: req.PromptVersion, PromptHash: generationPromptHash, RenderedPromptHash: "rendered-hash", ProfileID: req.ProfileID, BackendID: "fixture", ModelName: "fixture-model", StartedAt: stamp, EndedAt: stamp, RawOutput: rawOutput, Validation: promptexec.NewValidation(status, "json_schema", generationDefinitionForPrompt(req.PromptID).GeneratedTextSchemaID+".generated_text.schema.json", repairAttempts, nil)}
+	if complete != nil {
+		complete(execution)
+	}
+	return execution, nil
+}
+
+const generationPromptHash = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+
+func generationDefinitionForPrompt(promptID string) report.Definition {
+	for _, definition := range report.DefaultRegistry().All() {
+		if definition.PromptID == promptID {
+			return definition
+		}
+	}
+	panic("unknown fixture prompt " + promptID)
+}
+
+func TestGenerateDetailedPublishesOnlySelectedOutput(t *testing.T) {
+	cfg := config.Defaults()
+	cfg.WeatherAPI.Timezone, cfg.Location.ID = "America/Chicago", "home"
+	bundle := generationBundle(t)
+	executor := &generationExecutor{}
+	collector := &generationCollector{bundle: &bundle}
+	workingDir := t.TempDir()
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{Config: cfg, Report: ReportDaily, Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: workingDir, Collector: collector, Executor: executor})
+	if err != nil {
+		t.Fatalf("GenerateDetailed() error = %v", err)
+	}
+	if !executor.called || executor.executeCalls != 1 || collector.calls != 1 || result.OutputPath != filepath.Join(workingDir, "daily-2026-05-29.md") || result.ValidationStatus != promptexec.ValidationPassed || result.ProfileID == "" || result.BackendID == "" || result.ModelName == "" {
+		t.Fatalf("result = %#v", result)
+	}
+	if result.LLMDebugPath != "" {
+		t.Fatalf("unexpected debug output = %q", result.LLMDebugPath)
+	}
+	if _, err := os.Stat(filepath.Join(workingDir, "workspace")); !os.IsNotExist(err) {
+		t.Fatalf("unexpected default state directory: %v", err)
+	}
+	data, err := os.ReadFile(result.OutputPath)
+	if err != nil || len(data) == 0 {
+		t.Fatalf("output = %q, error = %v", data, err)
+	}
+}
+
+func TestGenerateDetailedUsesConfiguredOutputDirectory(t *testing.T) {
+	tests := []struct {
+		name      string
+		directory func(t *testing.T, workingDir string) string
+		wantDir   func(t *testing.T, workingDir string, configuredDir string) string
+	}{
+		{
+			name: "absolute directory",
+			directory: func(t *testing.T, _ string) string {
+				return filepath.Join(t.TempDir(), "reports")
+			},
+			wantDir: func(_ *testing.T, _ string, configuredDir string) string {
+				return configuredDir
+			},
+		},
+		{
+			name: "relative directory",
+			directory: func(_ *testing.T, _ string) string {
+				return "configured/../reports"
+			},
+			wantDir: func(_ *testing.T, workingDir string, _ string) string {
+				return filepath.Join(workingDir, "reports")
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			workingDir := t.TempDir()
+			configuredDir := tt.directory(t, workingDir)
+			cfg := generationDistributorConfig()
+			cfg.Output.Directory = configuredDir
+			bundle := generationBundle(t)
+			notifier := &generationNotifier{}
+
+			result, err := GenerateDetailed(context.Background(), GenerateRequest{
+				Config: cfg, Report: ReportDaily,
+				Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+				WorkingDir: workingDir, Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{}, Notifier: notifier,
+			})
+			wantPath := filepath.Join(tt.wantDir(t, workingDir, configuredDir), "daily-2026-05-29.md")
+			if err != nil || result == nil || result.OutputPath != wantPath || notifier.request.ReportPath != wantPath {
+				t.Fatalf("GenerateDetailed() result/error/notification = %#v/%v/%#v", result, err, notifier.request)
+			}
+			if info, statErr := os.Stat(filepath.Dir(wantPath)); statErr != nil || !info.IsDir() {
+				t.Fatalf("configured output directory info/error = %#v/%v", info, statErr)
+			}
+			if _, statErr := os.Stat(wantPath); statErr != nil {
+				t.Fatalf("output %q: %v", wantPath, statErr)
+			}
+		})
+	}
+}
+
+func TestGenerateDetailedExplicitOutputPathIgnoresConfiguredDirectory(t *testing.T) {
+	configuredPath := filepath.Join(t.TempDir(), "not-a-directory")
+	if err := os.WriteFile(configuredPath, []byte("not a directory"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	explicitPath := filepath.Join(t.TempDir(), "explicit.md")
+	cfg := generationConfig()
+	cfg.Output.Directory = configuredPath
+	bundle := generationBundle(t)
+
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{
+		Config: cfg, Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), OutputPath: explicitPath, Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{},
+	})
+	if err != nil || result == nil || result.OutputPath != explicitPath {
+		t.Fatalf("GenerateDetailed() result/error = %#v/%v", result, err)
+	}
+	if _, statErr := os.Stat(explicitPath); statErr != nil {
+		t.Fatalf("explicit output %q: %v", explicitPath, statErr)
+	}
+}
+
+func TestGenerateDetailedRejectsConfiguredNonDirectoryBeforeWork(t *testing.T) {
+	configuredPath := filepath.Join(t.TempDir(), "not-a-directory")
+	if err := os.WriteFile(configuredPath, []byte("not a directory"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg := generationDistributorConfig()
+	cfg.Output.Directory = configuredPath
+	bundle := generationBundle(t)
+	collector := &generationCollector{bundle: &bundle}
+	executor := &generationExecutor{}
+	notifier := &generationNotifier{}
+
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{
+		Config: cfg, Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), Collector: collector, Executor: executor, Notifier: notifier,
+	})
+	if err == nil || result == nil || collector.called || executor.promptInspections != 0 || executor.called || notifier.calls != 0 {
+		t.Fatalf("GenerateDetailed() result/error/collector/executor/notifier = %#v/%v/%t/%#v/%#v", result, err, collector.called, executor, notifier)
+	}
+	if data, readErr := os.ReadFile(configuredPath); readErr != nil || string(data) != "not a directory" {
+		t.Fatalf("configured path = %q, error = %v", data, readErr)
+	}
+}
+
+func TestGenerateDetailedRejectsOverlongOutputBeforeWork(t *testing.T) {
+	missingDirectory := filepath.Join(t.TempDir(), "missing")
+	outputPath := filepath.Join(missingDirectory, strings.Repeat("a", 253)+".md")
+	bundle := generationBundle(t)
+	collector := &generationCollector{bundle: &bundle}
+	executor := &generationExecutor{}
+
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{
+		Config: generationConfig(), Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: collector, Executor: executor,
+	})
+	if err == nil || result == nil || collector.called || executor.promptInspections != 0 || executor.called {
+		t.Fatalf("GenerateDetailed() result/error/collector/executor = %#v/%v/%t/%#v", result, err, collector.called, executor)
+	}
+	if _, statErr := os.Stat(missingDirectory); !os.IsNotExist(statErr) {
+		t.Fatalf("missing output directory exists after preflight failure: %v", statErr)
+	}
+}
+
+func TestGenerateDetailedRejectsUnsupportedDistributorEndpointBeforeWork(t *testing.T) {
+	outputPath := filepath.Join(t.TempDir(), "daily.md")
+	cfg := generationDistributorConfig()
+	cfg.Notify.Distributor.Endpoint = "ftp://distributor.example.test"
+	bundle := generationBundle(t)
+	collector := &generationCollector{bundle: &bundle}
+	executor := &generationExecutor{}
+	notifier := &generationNotifier{}
+
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{
+		Config: cfg, Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: collector, Executor: executor, Notifier: notifier,
+	})
+	if err == nil || result == nil || collector.called || executor.promptInspections != 0 || executor.called || notifier.calls != 0 {
+		t.Fatalf("GenerateDetailed() result/error/collector/executor/notifier = %#v/%v/%t/%#v/%#v", result, err, collector.called, executor, notifier)
+	}
+	if _, statErr := os.Stat(outputPath); !os.IsNotExist(statErr) {
+		t.Fatalf("output exists after endpoint preflight failure: %v", statErr)
+	}
+}
+
+func TestGenerateDetailedReturnsResolvedResultWhenCollectionFails(t *testing.T) {
+	cfg := config.Defaults()
+	cfg.WeatherAPI.Timezone, cfg.Location.ID = "America/Chicago", "home"
+	collectionErr := errors.New("weather source unavailable")
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{
+		Config: cfg, Report: ReportDaily, Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), Collector: &generationCollector{err: collectionErr}, Executor: &generationExecutor{},
+	})
+	if !errors.Is(err, collectionErr) {
+		t.Fatalf("GenerateDetailed() error = %v, want %v", err, collectionErr)
+	}
+	if result == nil || result.ReportID != report.Daily || result.RunID == "" || result.ProfileID != "fixture" || result.BackendID != "fixture" || result.ModelName != "fixture-model" || result.OutputPath != "" {
+		t.Fatalf("result = %#v", result)
+	}
+}
+
+func TestGenerateDetailedInspectsPromptBeforeCollectingWeather(t *testing.T) {
+	cfg := generationConfig()
+	inspectionErr := errors.New("profile is invalid")
+	collector := &generationCollector{bundle: generationBundlePointer(t)}
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{Config: cfg, Report: ReportDaily, Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), Collector: collector, Executor: &generationExecutor{inspectErr: inspectionErr}})
+	if !errors.Is(err, inspectionErr) || collector.called || result == nil {
+		t.Fatalf("GenerateDetailed() result/error/collector-called = %#v/%v/%t", result, err, collector.called)
+	}
+}
+
+func TestGenerateDetailedPreservesDestinationBeforePublish(t *testing.T) {
+	for _, scenario := range []struct {
+		name     string
+		executor generationExecutor
+	}{
+		{name: "generation", executor: generationExecutor{executeErr: errors.New("provider unavailable")}},
+		{name: "render", executor: generationExecutor{rawOutput: []byte(`{"summary":""}`)}},
+	} {
+		t.Run(scenario.name, func(t *testing.T) {
+			outputPath := filepath.Join(t.TempDir(), "daily.md")
+			if err := os.WriteFile(outputPath, []byte("previous report"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			bundle := generationBundle(t)
+			result, err := GenerateDetailed(context.Background(), GenerateRequest{Config: generationConfig(), Report: ReportDaily, Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: &generationCollector{bundle: &bundle}, Executor: &scenario.executor})
+			data, readErr := os.ReadFile(outputPath)
+			if err == nil || result == nil || readErr != nil || string(data) != "previous report" {
+				t.Fatalf("GenerateDetailed() result/error/output = %#v/%v/%q (%v)", result, err, data, readErr)
+			}
+		})
+	}
+}
+
+func TestGenerateDetailedPreservesDestinationWhenContextCancelsBeforePublication(t *testing.T) {
+	outputPath := filepath.Join(t.TempDir(), "daily.md")
+	const previousReport = "previous report"
+	if err := os.WriteFile(outputPath, []byte(previousReport), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	bundle := generationBundle(t)
+	result, err := GenerateDetailed(ctx, GenerateRequest{
+		Config: generationConfig(), Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{cancelBeforeReturn: cancel},
+	})
+	data, readErr := os.ReadFile(outputPath)
+	if !errors.Is(err, context.Canceled) || promptexec.CategoryOf(err) != promptexec.Canceled || result == nil || result.OutputPath != "" || readErr != nil || string(data) != previousReport {
+		t.Fatalf("GenerateDetailed() result/error/output = %#v/%v/%q (%v)", result, err, data, readErr)
+	}
+}
+
+func TestGenerateDetailedPreservesDestinationWhenContextDeadlineExpiresBeforePublication(t *testing.T) {
+	outputPath := filepath.Join(t.TempDir(), "daily.md")
+	const previousReport = "previous report"
+	if err := os.WriteFile(outputPath, []byte(previousReport), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithDeadline(context.Background(), time.Unix(0, 0))
+	defer cancel()
+	bundle := generationBundle(t)
+	result, err := GenerateDetailed(ctx, GenerateRequest{
+		Config: generationConfig(), Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{},
+	})
+	data, readErr := os.ReadFile(outputPath)
+	if !errors.Is(err, context.DeadlineExceeded) || promptexec.CategoryOf(err) != promptexec.DeadlineExceeded || result == nil || result.OutputPath != "" || readErr != nil || string(data) != previousReport {
+		t.Fatalf("GenerateDetailed() result/error/output = %#v/%v/%q (%v)", result, err, data, readErr)
+	}
+}
+
+func TestGenerateDetailedPreservesDestinationWhenContextChangesDuringPublication(t *testing.T) {
+	for _, tt := range []struct {
+		name     string
+		err      error
+		category promptexec.ErrorCategory
+	}{
+		{name: "canceled", err: context.Canceled, category: promptexec.Canceled},
+		{name: "deadline", err: context.DeadlineExceeded, category: promptexec.DeadlineExceeded},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			outputPath := filepath.Join(t.TempDir(), "daily.md")
+			const previousReport = "previous report"
+			if err := os.WriteFile(outputPath, []byte(previousReport), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			ctx := &publicationGateContext{Context: context.Background(), err: tt.err}
+			cfg := generationConfig()
+			cfg.Notify.Distributor.Enabled = true
+			cfg.Notify.Distributor.PipelineIDTemplate = "weather"
+			bundle := generationBundle(t)
+			notifier := &generationNotifier{}
+			result, err := GenerateDetailed(ctx, GenerateRequest{
+				Config: cfg, Report: ReportDaily,
+				Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+				WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{}, Notifier: notifier,
+			})
+			data, readErr := os.ReadFile(outputPath)
+			matches, globErr := filepath.Glob(filepath.Join(filepath.Dir(outputPath), ".weatherreporter-*.tmp"))
+			if !errors.Is(err, tt.err) || promptexec.CategoryOf(err) != tt.category || result == nil || result.OutputPath != "" || notifier.calls != 0 || readErr != nil || string(data) != previousReport || globErr != nil || len(matches) != 0 {
+				t.Fatalf("GenerateDetailed() result/error/output/notification/temp = %#v/%v/%q/%#v/%v/%v", result, err, data, notifier, matches, globErr)
+			}
+		})
+	}
+}
+
+func TestGenerateDetailedRetainsPublishedOutputWhenNotificationFails(t *testing.T) {
+	cfg := generationConfig()
+	cfg.Notify.Distributor.Enabled = true
+	cfg.Notify.Distributor.PipelineIDTemplate = "weather"
+	bundle := generationBundle(t)
+	outputPath := filepath.Join(t.TempDir(), "daily.md")
+	notifier := &generationNotifier{err: errors.New("distributor unavailable")}
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{Config: cfg, Report: ReportDaily, Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{}, Notifier: notifier})
+	if err == nil || result == nil || result.OutputPath != outputPath || notifier.request.ReportPath != outputPath || len(notifier.request.BundlePaths) == 0 {
+		t.Fatalf("GenerateDetailed() result/error/request = %#v/%v/%#v", result, err, notifier.request)
+	}
+	if data, readErr := os.ReadFile(outputPath); readErr != nil || len(data) == 0 {
+		t.Fatalf("published output = %q, error = %v", data, readErr)
+	}
+}
+
+func TestGenerateDetailedDoesNotReplaceDirectoryOutput(t *testing.T) {
+	bundle := generationBundle(t)
+	outputPath := filepath.Join(t.TempDir(), "daily.md")
+	if err := os.Mkdir(outputPath, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	collector := &generationCollector{bundle: &bundle}
+	executor := &generationExecutor{}
+	notifier := &generationNotifier{}
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{Config: generationConfig(), Report: ReportDaily, Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: collector, Executor: executor, Notifier: notifier})
+	info, statErr := os.Stat(outputPath)
+	if err == nil || result == nil || statErr != nil || !info.IsDir() || collector.called || executor.promptInspections != 0 || executor.called || notifier.calls != 0 {
+		t.Fatalf("GenerateDetailed() result/error/output-info/collector/executor/notifier = %#v/%v/%#v (%v)/%t/%#v/%#v", result, err, info, statErr, collector.called, executor, notifier)
+	}
+}
+
+func TestGenerateDetailedDoesNotReplaceSymbolicLinkOutput(t *testing.T) {
+	dir := t.TempDir()
+	backing := filepath.Join(dir, "backing.md")
+	if err := os.WriteFile(backing, []byte("previous report"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	outputPath := filepath.Join(dir, "daily.md")
+	testutil.RequireSymlink(t, backing, outputPath)
+	bundle := generationBundle(t)
+	collector := &generationCollector{bundle: &bundle}
+	executor := &generationExecutor{}
+	notifier := &generationNotifier{}
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{Config: generationConfig(), Report: ReportDaily, Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"), WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: collector, Executor: executor, Notifier: notifier})
+	info, statErr := os.Lstat(outputPath)
+	data, readErr := os.ReadFile(backing)
+	if err == nil || result == nil || statErr != nil || info.Mode()&os.ModeSymlink == 0 || readErr != nil || string(data) != "previous report" || collector.called || executor.promptInspections != 0 || executor.called || notifier.calls != 0 {
+		t.Fatalf("GenerateDetailed() result/error/output/backing/collector/executor/notifier = %#v/%v/%#v (%v)/%q (%v)/%t/%#v/%#v", result, err, info, statErr, data, readErr, collector.called, executor, notifier)
+	}
+}
+
+func TestGenerateDetailedWritesRequestedPromptDebugArtifacts(t *testing.T) {
+	bundle := generationBundle(t)
+	debugRoot := t.TempDir()
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{
+		Config: generationConfig(), Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), LLMDebugDir: debugRoot, Collector: &generationCollector{bundle: &bundle}, Executor: &generationExecutor{},
+	})
+	if errors.Is(err, promptdebug.ErrSecureCaptureUnsupported) {
+		t.Skipf("secure prompt debug capture is unavailable: %v", err)
+	}
+	if err != nil || result == nil || result.LLMDebugPath == "" {
+		t.Fatalf("GenerateDetailed() result/error = %#v/%v", result, err)
+	}
+	for _, name := range []string{"preparation.json", "execution.json"} {
+		if _, statErr := os.Stat(filepath.Join(result.LLMDebugPath, name)); statErr != nil {
+			t.Fatalf("debug artifact %q: %v", name, statErr)
+		}
+	}
+}
+
+func TestGenerateDetailedCapturesProviderFailureOnlyInDebugArtifacts(t *testing.T) {
+	bundle := generationBundle(t)
+	debugRoot := t.TempDir()
+	const marker = "provider-private-generation-marker"
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{
+		Config: generationConfig(), Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), LLMDebugDir: debugRoot, Collector: &generationCollector{bundle: &bundle},
+		Executor: &generationExecutor{executeErr: promptexec.NewGenerationError(http.StatusTooManyRequests, "rate_limit", "provider_error", marker, nil)},
+	})
+	if errors.Is(err, promptdebug.ErrSecureCaptureUnsupported) {
+		t.Skipf("secure prompt debug capture is unavailable: %v", err)
+	}
+	if err == nil || result == nil || result.LLMDebugPath == "" || promptexec.CategoryOf(err) != promptexec.Generation || !strings.Contains(err.Error(), "HTTP 429") || strings.Contains(err.Error(), marker) || result.OutputPath != "" {
+		t.Fatalf("GenerateDetailed() result/error = %#v/%v", result, err)
+	}
+	for _, name := range []string{"preparation.json", "failure.json"} {
+		if _, statErr := os.Stat(filepath.Join(result.LLMDebugPath, name)); statErr != nil {
+			t.Fatalf("debug artifact %q: %v", name, statErr)
+		}
+	}
+	data, readErr := os.ReadFile(filepath.Join(result.LLMDebugPath, "failure.json"))
+	if readErr != nil || !strings.Contains(string(data), marker) {
+		t.Fatalf("failure artifact = %q, error = %v", data, readErr)
+	}
+}
+
+func TestGenerateDetailedPreservesProviderFailureWhenFailureDebugWriteFails(t *testing.T) {
+	bundle := generationBundle(t)
+	debugRoot := t.TempDir()
+	const marker = "provider-private-write-failure-marker"
+	var setupErr error
+	executor := &generationExecutor{
+		executeErr: promptexec.NewGenerationError(http.StatusServiceUnavailable, "unavailable", "provider_error", marker, nil),
+		beforeExecute: func(promptexec.ExecuteRequest) {
+			setupErr = filepath.Walk(debugRoot, func(path string, info os.FileInfo, err error) error {
+				if err != nil {
+					return err
+				}
+				if info.Name() == "preparation.json" {
+					return os.Mkdir(filepath.Join(filepath.Dir(path), "failure.json"), 0o700)
+				}
+				return nil
+			})
+		},
+	}
+	result, err := GenerateDetailed(context.Background(), GenerateRequest{
+		Config: generationConfig(), Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+		WorkingDir: t.TempDir(), LLMDebugDir: debugRoot, Collector: &generationCollector{bundle: &bundle}, Executor: executor,
+	})
+	if errors.Is(err, promptdebug.ErrSecureCaptureUnsupported) {
+		t.Skipf("secure prompt debug capture is unavailable: %v", err)
+	}
+	var generationError *promptexec.GenerationError
+	if setupErr != nil || err == nil || result == nil || result.OutputPath != "" || promptexec.CategoryOf(err) != promptexec.Generation || !errors.As(err, &generationError) || generationError.StatusCode() != http.StatusServiceUnavailable || !strings.Contains(err.Error(), "HTTP 503") || strings.Contains(err.Error(), marker) {
+		t.Fatalf("GenerateDetailed() setup/result/error = %v/%#v/%v", setupErr, result, err)
+	}
+}
+
+func generationConfig() config.Config {
+	cfg := config.Defaults()
+	cfg.WeatherAPI.Timezone, cfg.Location.ID = "America/Chicago", "home"
+	return cfg
+}
+
+func generationBundlePointer(t *testing.T) *weatherdata.Bundle {
+	bundle := generationBundle(t)
+	return &bundle
+}
+
+type generationNotifier struct {
+	err          error
+	batchErr     error
+	calls        int
+	request      NotificationRequest
+	batchRequest batchNotificationRequest
+	batchCalls   int
+}
+
+func (n *generationNotifier) Notify(_ context.Context, request NotificationRequest) (*NotificationResult, error) {
+	n.calls++
+	n.request = request
+	if n.err != nil {
+		return nil, n.err
+	}
+	return &NotificationResult{Status: "succeeded"}, nil
+}
+
+func (n *generationNotifier) NotifyBatch(_ context.Context, request batchNotificationRequest) (*NotificationResult, error) {
+	n.batchCalls++
+	n.batchRequest = request
+	for _, file := range request.Files {
+		if _, err := os.Stat(file.SourcePath); err != nil {
+			return nil, err
+		}
+	}
+	return &NotificationResult{Status: "succeeded", PipelineID: request.PipelineID, BundleID: request.BundleID}, n.batchErr
+}
+
+func generationBundle(t *testing.T) weatherdata.Bundle {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join("..", "forecast", "testdata", "daily_bundle.json"))
+	if err != nil {
+		t.Fatalf("read bundle fixture: %v", err)
+	}
+	var bundle weatherdata.Bundle
+	if err := json.Unmarshal(data, &bundle); err != nil {
+		t.Fatalf("decode bundle fixture: %v", err)
+	}
+	return bundle
+}
+func generationTime(value string) time.Time {
+	parsed, _ := time.Parse(time.RFC3339, value)
+	return parsed
+}
+
+var _ promptexec.Executor = (*generationExecutor)(nil)
+var _ Collector = (*generationCollector)(nil)
+var _ Notifier = (*generationNotifier)(nil)
+var _ = report.Daily

internal/app/inspect.go

@@ -1,126 +0,0 @@
-package app
-
-import (
-	"context"
-	"fmt"
-
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptinput"
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/state"
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
-	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
-)
-
-type InspectReportsRequest struct {
-	Config config.Config
-	Limit  int
-}
-
-type InspectRunRequest struct {
-	Config config.Config
-	RunID  string
-}
-
-type SourceInspection struct {
-	RunID          string                      `json:"runId"`
-	ReportID       report.ID                   `json:"reportId"`
-	SourceLocation string                      `json:"sourceLocation,omitempty"`
-	Sources        []briefing.SourceMetadata   `json:"sources,omitempty"`
-	Warnings       []weatherdata.SourceWarning `json:"warnings,omitempty"`
-}
-
-func InspectReports(ctx context.Context, req InspectReportsRequest) ([]state.ReportRecord, error) {
-	store, err := defaultStore(req.Config)
-	if err != nil {
-		return nil, err
-	}
-	return store.ListReports(ctx, req.Limit)
-}
-
-func InspectMetadata(ctx context.Context, req InspectRunRequest) (state.Metadata, error) {
-	inspection, err := inspectRun(ctx, req)
-	return inspection.metadata, err
-}
-
-func InspectModules(ctx context.Context, req InspectRunRequest) (module.Snapshot, error) {
-	inspection, err := inspectRun(ctx, req)
-	if err != nil {
-		return module.Snapshot{}, err
-	}
-	return inspection.store.LoadModuleSnapshot(ctx, inspection.metadata.ModuleSnapshotPath)
-}
-
-func InspectDataPackage(ctx context.Context, req InspectRunRequest) (promptinput.Package, error) {
-	inspection, err := inspectRun(ctx, req)
-	if err != nil {
-		return promptinput.Package{}, err
-	}
-	return inspection.store.LoadDataPackage(ctx, inspection.metadata.DataPackagePath)
-}
-
-func InspectPriorSnapshot(ctx context.Context, req InspectRunRequest) (*state.PriorSnapshot, error) {
-	inspection, err := inspectRun(ctx, req)
-	if err != nil {
-		return nil, err
-	}
-	resolved, err := resolvedFromMetadata(inspection.metadata)
-	if err != nil {
-		return nil, err
-	}
-	return inspection.store.FindPriorSnapshot(ctx, resolved)
-}
-
-func InspectSources(ctx context.Context, req InspectRunRequest) (SourceInspection, error) {
-	inspection, err := inspectRun(ctx, req)
-	if err != nil {
-		return SourceInspection{}, err
-	}
-	metadata := inspection.metadata
-	return SourceInspection{
-		RunID:          metadata.RunID,
-		ReportID:       metadata.ReportID,
-		SourceLocation: metadata.SourceLocation,
-		Sources:        metadata.Sources,
-		Warnings:       metadata.SourceWarnings,
-	}, nil
-}
-
-type runInspection struct {
-	store    *state.FilesystemStore
-	metadata state.Metadata
-}
-
-func inspectRun(ctx context.Context, req InspectRunRequest) (runInspection, error) {
-	store, err := defaultStore(req.Config)
-	if err != nil {
-		return runInspection{}, err
-	}
-	metadata, _, err := store.LoadMetadataByRunID(ctx, req.RunID)
-	if err != nil {
-		return runInspection{}, err
-	}
-	return runInspection{store: store, metadata: metadata}, nil
-}
-
-func resolvedFromMetadata(metadata state.Metadata) (report.Resolved, error) {
-	definition, err := report.DefaultRegistry().Lookup(metadata.ReportID)
-	if err != nil {
-		return report.Resolved{}, err
-	}
-	location, err := timeutil.LoadLocation(metadata.Timezone)
-	if err != nil {
-		return report.Resolved{}, err
-	}
-	if !metadata.ValidPeriod.IsValid() {
-		return report.Resolved{}, fmt.Errorf("metadata valid period for run id %q is invalid", metadata.RunID)
-	}
-	return report.Resolved{
-		Definition:  definition,
-		GeneratedAt: metadata.GeneratedAt,
-		Timezone:    location.String(),
-		ValidPeriod: metadata.ValidPeriod,
-	}, nil
-}

internal/app/output.go

@@ -0,0 +1,192 @@
+package app
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/comparison"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/fileutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+func plannedBatchOutputPath(outputDir string, planned plannedBatchReport) (string, error) {
+	outputName, err := planned.Resolved.OutputName()
+	if err != nil {
+		return "", err
+	}
+	return validateOutputPath(filepath.Join(outputDir, outputName))
+}
+
+func prepareBatchOutputs(outputDir string, plannedReports []plannedBatchReport) error {
+	for index := range plannedReports {
+		outputPath, err := plannedBatchOutputPath(outputDir, plannedReports[index])
+		if err != nil {
+			return err
+		}
+		plannedReports[index].OutputPath = outputPath
+	}
+	return nil
+}
+
+func resolveReportOutputPath(workingDir, override, configuredDir string, resolved report.Resolved) (string, error) {
+	outputName, err := resolved.OutputName()
+	if err != nil {
+		return "", err
+	}
+	if override != "" {
+		return resolveOutputPath(workingDir, override, outputName)
+	}
+	outputDir, err := resolveOutputDir(workingDir, configuredDir)
+	if err != nil {
+		return "", err
+	}
+	return validateOutputPath(filepath.Join(outputDir, outputName))
+}
+
+func resolveOutputDirWithConfigured(workingDir, override, configuredDir string) (string, error) {
+	directory := configuredDir
+	if override != "" {
+		directory = override
+	}
+	return resolveOutputDir(workingDir, directory)
+}
+
+func resolveComparisonOutputDirectory(workingDir, override, configuredDir, reportOutputName string) (string, error) {
+	workingDir, err := validateWorkingDir(workingDir)
+	if err != nil {
+		return "", err
+	}
+	if override != "" {
+		return resolveComparisonDirectoryPath(workingDir, override)
+	}
+	outputDir, err := resolveOutputDir(workingDir, configuredDir)
+	if err != nil {
+		return "", err
+	}
+	name, err := comparison.DefaultDirectoryName(reportOutputName)
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(outputDir, name), nil
+}
+
+func resolveComparisonDirectoryPath(workingDir, directory string) (string, error) {
+	if strings.TrimSpace(directory) == "" {
+		return "", fmt.Errorf("comparison output directory is required")
+	}
+	if !filepath.IsAbs(directory) {
+		directory = filepath.Join(workingDir, directory)
+	}
+	return filepath.Clean(directory), nil
+}
+
+func resolveOutputDir(workingDir, override string) (string, error) {
+	workingDir, err := validateWorkingDir(workingDir)
+	if err != nil {
+		return "", err
+	}
+	if override == "" {
+		return workingDir, nil
+	}
+	if strings.TrimSpace(override) == "" {
+		return "", fmt.Errorf("output directory is required")
+	}
+	directory := override
+	if !filepath.IsAbs(directory) {
+		directory = filepath.Join(workingDir, directory)
+	}
+	directory = filepath.Clean(directory)
+	if err := preflightOutputDirectory(directory); err != nil {
+		return "", err
+	}
+	return directory, nil
+}
+
+func preflightOutputDirectory(directory string) error {
+	info, err := os.Stat(directory)
+	if err == nil {
+		if !info.IsDir() {
+			return fmt.Errorf("output directory %q is not a directory", directory)
+		}
+		return nil
+	}
+	if !os.IsNotExist(err) {
+		return fmt.Errorf("inspect output directory %q: %w", directory, err)
+	}
+
+	// A missing directory is valid, but os.Stat also reports ErrNotExist for a
+	// dangling symlink. Walk to the first existing component so invalid links
+	// fail preflight instead of being discovered only during publication.
+	for component := directory; ; component = filepath.Dir(component) {
+		componentInfo, componentErr := os.Lstat(component)
+		if componentErr == nil {
+			if componentInfo.Mode()&os.ModeSymlink != 0 {
+				targetInfo, targetErr := os.Stat(component)
+				if targetErr != nil {
+					return fmt.Errorf("inspect output directory %q at %q: %w", directory, component, targetErr)
+				}
+				if !targetInfo.IsDir() {
+					return fmt.Errorf("output directory %q has non-directory path component %q", directory, component)
+				}
+				return nil
+			}
+			if !componentInfo.IsDir() {
+				return fmt.Errorf("output directory %q has non-directory path component %q", directory, component)
+			}
+			return nil
+		}
+		if !os.IsNotExist(componentErr) {
+			return fmt.Errorf("inspect output directory %q at %q: %w", directory, component, componentErr)
+		}
+		if filepath.Dir(component) == component {
+			return fmt.Errorf("inspect output directory %q: no existing directory ancestor", directory)
+		}
+	}
+}
+
+func resolveOutputPath(workingDir, override, defaultName string) (string, error) {
+	workingDir, err := validateWorkingDir(workingDir)
+	if err != nil {
+		return "", err
+	}
+	path := override
+	if path == "" {
+		path = defaultName
+	}
+	if strings.TrimSpace(path) == "" {
+		return "", fmt.Errorf("final output path is required")
+	}
+	if !filepath.IsAbs(path) {
+		path = filepath.Join(workingDir, path)
+	}
+	return validateOutputPath(path)
+}
+
+func validateWorkingDir(workingDir string) (string, error) {
+	if strings.TrimSpace(workingDir) == "" {
+		return "", fmt.Errorf("working directory is required")
+	}
+	if !filepath.IsAbs(workingDir) {
+		return "", fmt.Errorf("working directory %q must be absolute", workingDir)
+	}
+	return filepath.Clean(workingDir), nil
+}
+
+func validateOutputPath(path string) (string, error) {
+	if strings.TrimSpace(path) == "" {
+		return "", fmt.Errorf("final output path is required")
+	}
+	path = filepath.Clean(path)
+	if !filepath.IsAbs(path) {
+		return "", fmt.Errorf("final output path %q must be absolute", path)
+	}
+	if filepath.Dir(path) == path {
+		return "", fmt.Errorf("final output path %q must not be a filesystem root", path)
+	}
+	if err := fileutil.ValidateAtomicPath(path); err != nil {
+		return "", fmt.Errorf("validate final output path %q: %w", path, err)
+	}
+	return path, nil
+}

internal/app/output_linux_test.go

@@ -0,0 +1,59 @@
+//go:build linux
+
+package app
+
+import (
+	"context"
+	"net"
+	"os"
+	"path/filepath"
+	"syscall"
+	"testing"
+)
+
+func TestGenerateDetailedRejectsSpecialOutputBeforeWork(t *testing.T) {
+	for _, tt := range []struct {
+		name  string
+		setup func(t *testing.T, path string)
+	}{
+		{
+			name: "named pipe",
+			setup: func(t *testing.T, path string) {
+				t.Helper()
+				if err := syscall.Mkfifo(path, 0o600); err != nil {
+					t.Fatal(err)
+				}
+			},
+		},
+		{
+			name: "socket",
+			setup: func(t *testing.T, path string) {
+				t.Helper()
+				listener, err := net.ListenUnix("unix", &net.UnixAddr{Name: path, Net: "unix"})
+				if err != nil {
+					t.Fatal(err)
+				}
+				t.Cleanup(func() { _ = listener.Close() })
+			},
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			outputPath := filepath.Join(t.TempDir(), "daily.md")
+			tt.setup(t, outputPath)
+			bundle := generationBundle(t)
+			collector := &generationCollector{bundle: &bundle}
+			executor := &generationExecutor{}
+			notifier := &generationNotifier{}
+
+			result, err := GenerateDetailed(context.Background(), GenerateRequest{
+				Config: generationConfig(), Report: ReportDaily,
+				Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+				WorkingDir: t.TempDir(), OutputPath: outputPath, Collector: collector, Executor: executor, Notifier: notifier,
+			})
+			info, statErr := os.Lstat(outputPath)
+			if err == nil || result == nil || statErr != nil || info.Mode().IsRegular() || collector.called || executor.promptInspections != 0 || executor.called || notifier.calls != 0 {
+				t.Fatalf("GenerateDetailed() result/error/output/collector/executor/notifier = %#v/%v/%#v (%v)/%t/%#v/%#v", result, err, info, statErr, collector.called, executor, notifier)
+			}
+		})
+	}
+}

internal/app/output_test.go

@@ -0,0 +1,73 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/testutil"
+)
+
+func TestResolveComparisonOutputDirectory(t *testing.T) {
+	workingDir := t.TempDir()
+	configured := filepath.Join(workingDir, "configured")
+	blocked := filepath.Join(workingDir, "not-a-directory")
+	if err := os.WriteFile(blocked, []byte("blocked"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	tests := []struct {
+		name             string
+		override         string
+		configuredDir    string
+		reportOutputName string
+		want             string
+		wantErr          bool
+	}{
+		{name: "working directory default", reportOutputName: "today.md", want: filepath.Join(workingDir, "comparison-today")},
+		{name: "configured relative directory", configuredDir: "configured", reportOutputName: "tomorrow.md", want: filepath.Join(configured, "comparison-tomorrow")},
+		{name: "configured absolute directory", configuredDir: configured, reportOutputName: "hourly.md", want: filepath.Join(configured, "comparison-hourly")},
+		{name: "relative explicit directory", override: "exact", configuredDir: blocked, reportOutputName: "daily-2026-08-24.md", want: filepath.Join(workingDir, "exact")},
+		{name: "absolute explicit directory", override: filepath.Join(workingDir, "absolute"), reportOutputName: "today.md", want: filepath.Join(workingDir, "absolute")},
+		{name: "invalid report suffix", reportOutputName: "today.txt", wantErr: true},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			got, err := resolveComparisonOutputDirectory(workingDir, test.override, test.configuredDir, test.reportOutputName)
+			if (err != nil) != test.wantErr {
+				t.Fatalf("resolveComparisonOutputDirectory() error = %v, want error %t", err, test.wantErr)
+			}
+			if !test.wantErr && got != test.want {
+				t.Fatalf("resolveComparisonOutputDirectory() = %q, want %q", got, test.want)
+			}
+		})
+	}
+}
+
+func TestResolveOutputDirRejectsDanglingSymlinkComponents(t *testing.T) {
+	workingDir := t.TempDir()
+	dangling := filepath.Join(workingDir, "dangling")
+	testutil.RequireSymlink(t, filepath.Join(workingDir, "missing"), dangling)
+
+	for _, directory := range []string{dangling, filepath.Join(dangling, "reports")} {
+		t.Run(filepath.Base(directory), func(t *testing.T) {
+			if _, err := resolveOutputDir(workingDir, directory); err == nil {
+				t.Fatalf("resolveOutputDir(%q) error = nil, want dangling symlink error", directory)
+			}
+		})
+	}
+}
+
+func TestResolveOutputDirAllowsMissingDirectoryBelowValidSymlink(t *testing.T) {
+	workingDir := t.TempDir()
+	target := t.TempDir()
+	link := filepath.Join(workingDir, "linked")
+	testutil.RequireSymlink(t, target, link)
+
+	directory := filepath.Join(link, "reports")
+	got, err := resolveOutputDir(workingDir, directory)
+	if err != nil || got != directory {
+		t.Fatalf("resolveOutputDir() = %q, %v, want %q, nil", got, err, directory)
+	}
+}

internal/app/prepared_report.go

@@ -0,0 +1,148 @@
+package app
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/collect"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/facts"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/generatedtext"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptinput"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+// preparedReport contains the immutable deterministic inputs shared by prompt
+// executions for one resolved report.
+type preparedReport struct {
+	resolved       report.Resolved
+	derived        facts.DerivedFacts
+	moduleSnapshot module.Snapshot
+	identity       briefing.PreparedIdentity
+	sourceWarnings []weatherdata.SourceWarning
+	dataPackage    []byte
+	handler        generatedtext.Handler
+}
+
+type prepareReportRequest struct {
+	Config     config.Config
+	Resolved   report.Resolved
+	Collection collect.Result
+	handler    generatedtext.Handler
+}
+
+type preparationError struct {
+	operation string
+	err       error
+}
+
+func (e *preparationError) Error() string {
+	return e.operation + ": " + e.err.Error()
+}
+
+func (e *preparationError) Unwrap() error {
+	return e.err
+}
+
+func prepareReport(req prepareReportRequest) (preparedReport, error) {
+	if req.Collection.Bundle == nil {
+		return preparedReport{}, &preparationError{operation: "prepare report", err: fmt.Errorf("collected weather bundle is required")}
+	}
+
+	reportFacts, err := BuildReportFacts(ModuleSnapshotRequest{Config: req.Config, Resolved: req.Resolved}, req.Collection.Bundle)
+	if err != nil {
+		return preparedReport{}, &preparationError{operation: "build report facts", err: err}
+	}
+	buildContext := briefingBuildContext(req.Config, req.Resolved, reportFacts.Collected)
+	identity := briefing.BuildPreparedIdentity(buildContext)
+	moduleSnapshot, err := BuildModuleSnapshotFromFacts(ModuleSnapshotRequest{Config: req.Config, Resolved: req.Resolved, Identity: identity}, reportFacts)
+	if err != nil {
+		return preparedReport{}, &preparationError{operation: "build module snapshot", err: err}
+	}
+	dataPackage, err := promptinput.Build(promptinput.BuildRequest{Metadata: promptMetadata(identity), Modules: moduleSnapshot})
+	if err != nil {
+		return preparedReport{}, &preparationError{operation: "build data package", err: err}
+	}
+	serializedDataPackage, err := promptinput.MarshalYAML(dataPackage)
+	if err != nil {
+		return preparedReport{}, &preparationError{operation: "marshal data package", err: err}
+	}
+	clonedDerived, err := clonePreparedValue(reportFacts.Derived)
+	if err != nil {
+		return preparedReport{}, &preparationError{operation: "copy prepared derived facts", err: err}
+	}
+	clonedSnapshot, err := clonePreparedValue(moduleSnapshot)
+	if err != nil {
+		return preparedReport{}, &preparationError{operation: "copy prepared module snapshot", err: err}
+	}
+	clonedIdentity, err := clonePreparedValue(identity)
+	if err != nil {
+		return preparedReport{}, &preparationError{operation: "copy prepared identity", err: err}
+	}
+	prepared := preparedReport{
+		resolved:       cloneResolved(req.Resolved),
+		derived:        clonedDerived,
+		moduleSnapshot: clonedSnapshot,
+		identity:       clonedIdentity,
+		sourceWarnings: append([]weatherdata.SourceWarning(nil), clonedIdentity.SourceWarnings...),
+		dataPackage:    append([]byte(nil), serializedDataPackage...),
+		handler:        req.handler,
+	}
+	return prepared, nil
+}
+
+func cloneResolved(value report.Resolved) report.Resolved {
+	cloned := value
+	cloned.Definition.DistributorPathTemplates = append([]string(nil), value.Definition.DistributorPathTemplates...)
+	cloned.Definition.Modules = make([]module.ConfigItem, len(value.Definition.Modules))
+	for i, item := range value.Definition.Modules {
+		cloned.Definition.Modules[i] = item
+		switch options := item.Options.(type) {
+		case module.AreaForecastDiscussionOptions:
+			options.Sections = append([]string(nil), options.Sections...)
+			cloned.Definition.Modules[i].Options = options
+		}
+	}
+	return cloned
+}
+
+func (p preparedReport) dataPackageCopy() []byte {
+	return append([]byte(nil), p.dataPackage...)
+}
+
+func (p preparedReport) sourceWarningsCopy() []weatherdata.SourceWarning {
+	return append([]weatherdata.SourceWarning(nil), p.sourceWarnings...)
+}
+
+func (p preparedReport) renderInputs() (briefing.PreparedIdentity, module.Snapshot, facts.DerivedFacts, error) {
+	identity, err := clonePreparedValue(p.identity)
+	if err != nil {
+		return briefing.PreparedIdentity{}, module.Snapshot{}, facts.DerivedFacts{}, err
+	}
+	snapshot, err := clonePreparedValue(p.moduleSnapshot)
+	if err != nil {
+		return briefing.PreparedIdentity{}, module.Snapshot{}, facts.DerivedFacts{}, err
+	}
+	derived, err := clonePreparedValue(p.derived)
+	if err != nil {
+		return briefing.PreparedIdentity{}, module.Snapshot{}, facts.DerivedFacts{}, err
+	}
+	return identity, snapshot, derived, nil
+}
+
+func clonePreparedValue[T any](value T) (T, error) {
+	encoded, err := json.Marshal(value)
+	if err != nil {
+		var zero T
+		return zero, fmt.Errorf("marshal immutable prepared value: %w", err)
+	}
+	var cloned T
+	if err := json.Unmarshal(encoded, &cloned); err != nil {
+		var zero T
+		return zero, fmt.Errorf("unmarshal immutable prepared value: %w", err)
+	}
+	return cloned, nil
+}

internal/app/prepared_report_test.go

@@ -0,0 +1,121 @@
+package app
+
+import (
+	"bytes"
+	"reflect"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/collect"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/generatedtext"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+func TestPrepareReportBuildsImmutableDeterministicInputs(t *testing.T) {
+	cfg := generationConfig()
+	bundle := generationBundle(t)
+	resolved, err := ResolveGenerate(GenerateRequest{
+		Config: cfg, Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+	}, generationTime("2026-05-29T08:30:00-05:00"))
+	if err != nil {
+		t.Fatalf("ResolveGenerate() error = %v", err)
+	}
+
+	request := prepareReportRequest{Config: cfg, Resolved: resolved, Collection: collect.Result{Bundle: &bundle}, handler: preparedHandler(t, resolved)}
+	prepared, err := prepareReport(request)
+	if err != nil {
+		t.Fatalf("prepareReport() error = %v", err)
+	}
+	repeated, err := prepareReport(request)
+	if err != nil {
+		t.Fatalf("second prepareReport() error = %v", err)
+	}
+	if len(prepared.dataPackage) == 0 || !bytes.Equal(prepared.dataPackage, repeated.dataPackage) || !reflect.DeepEqual(prepared.identity, repeated.identity) {
+		t.Fatalf("prepared package and identity are not deterministic: %q/%#v", prepared.dataPackage, prepared.identity)
+	}
+
+	originalDataPackage := append([]byte(nil), prepared.dataPackage...)
+	originalIdentity := prepared.identity
+	originalDerived := prepared.derived
+	originalWarnings := append([]weatherdata.SourceWarning(nil), prepared.sourceWarnings...)
+	identity, snapshot, derived, err := prepared.renderInputs()
+	if err != nil {
+		t.Fatalf("renderInputs() error = %v", err)
+	}
+	identity.SourceWarnings = append(identity.SourceWarnings, weatherdata.SourceWarning{Source: "test", Message: "consumer mutation"})
+	snapshot.Outputs = nil
+	derived.PrecipTiming.ThunderMentioned = false
+	bundle.Hourly.Periods[0].TextDescription = "mutated after preparation"
+	bundle.Warnings = append(bundle.Warnings, weatherdata.SourceWarning{Source: "test", Message: "mutated warning"})
+	if len(bundle.Sources) > 0 {
+		if bundle.Sources[0].Query == nil {
+			bundle.Sources[0].Query = map[string]string{}
+		}
+		bundle.Sources[0].Query["mutated"] = "true"
+	}
+
+	if !bytes.Equal(prepared.dataPackage, originalDataPackage) || !reflect.DeepEqual(prepared.identity, originalIdentity) || !reflect.DeepEqual(prepared.derived, originalDerived) || !reflect.DeepEqual(prepared.sourceWarnings, originalWarnings) {
+		t.Fatalf("prepared values changed after caller mutation: %#v", prepared)
+	}
+	if len(prepared.moduleSnapshot.Outputs) == 0 {
+		t.Fatal("prepared report values retain consumer mutation")
+	}
+}
+
+func TestPrepareReportProjectsPreparedIdentity(t *testing.T) {
+	cfg := generationConfig()
+	bundle := generationBundle(t)
+	resolved, err := ResolveGenerate(GenerateRequest{
+		Config: cfg, Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+	}, generationTime("2026-05-29T08:30:00-05:00"))
+	if err != nil {
+		t.Fatalf("ResolveGenerate() error = %v", err)
+	}
+	prepared, err := prepareReport(prepareReportRequest{Config: cfg, Resolved: resolved, Collection: collect.Result{Bundle: &bundle}, handler: preparedHandler(t, resolved)})
+	if err != nil {
+		t.Fatalf("prepareReport() error = %v", err)
+	}
+
+	identity := prepared.identity
+	renderIdentity, _, _, err := prepared.renderInputs()
+	if err != nil {
+		t.Fatalf("renderInputs() error = %v", err)
+	}
+	if !reflect.DeepEqual(renderIdentity, identity) {
+		t.Fatalf("render identity = %#v, want %#v", renderIdentity, identity)
+	}
+	prompt := promptMetadata(identity)
+	if prompt.RunID != identity.RunID || prompt.ReportID != identity.ReportID || prompt.Variant != identity.Variant || prompt.PromptID != identity.PromptID || !prompt.GeneratedAt.Equal(identity.GeneratedAt) || prompt.Timezone != identity.Timezone || prompt.ValidPeriod != identity.ValidPeriod || !reflect.DeepEqual(prompt.SourceWarnings, identity.SourceWarnings) {
+		t.Fatalf("prompt metadata does not match prepared identity: %#v/%#v", prompt, identity)
+	}
+
+	moduleMetadata, found, err := module.StanzaValue[briefing.MetadataModule](prepared.moduleSnapshot, "metadata")
+	if err != nil || !found {
+		t.Fatalf("metadata stanza = %#v/%t/%v", moduleMetadata, found, err)
+	}
+	if moduleMetadata.RunID != identity.RunID || moduleMetadata.ReportID != identity.ReportID || moduleMetadata.Variant != identity.Variant || moduleMetadata.PromptID != identity.PromptID || !moduleMetadata.GeneratedAt.Equal(identity.GeneratedAt) || moduleMetadata.Units != identity.Units || moduleMetadata.Timezone != identity.Timezone || moduleMetadata.ValidPeriod != identity.ValidPeriod || !reflect.DeepEqual(moduleMetadata.Location, identity.Location) {
+		t.Fatalf("module metadata does not match prepared identity: %#v/%#v", moduleMetadata, identity)
+	}
+	if len(moduleMetadata.SourceWarnings) != len(identity.SourceWarnings) {
+		t.Fatalf("module source warnings = %#v, want %#v", moduleMetadata.SourceWarnings, identity.SourceWarnings)
+	}
+	for index, warning := range identity.SourceWarnings {
+		summary := moduleMetadata.SourceWarnings[index]
+		if summary.Source != warning.Source || summary.Code != warning.Code || summary.Severity != warning.Severity || summary.Message != warning.Message || summary.CompletenessImpact != warning.CompletenessImpact {
+			t.Fatalf("module source warning %d = %#v, want %#v", index, summary, warning)
+		}
+	}
+}
+
+func preparedHandler(t *testing.T, resolved report.Resolved) generatedtext.Handler {
+	t.Helper()
+	handler, err := generatedtext.LookupDefinition(resolved.Definition)
+	if err != nil {
+		t.Fatalf("LookupDefinition() error = %v", err)
+	}
+	return handler
+}

internal/app/profile_execution.go

@@ -0,0 +1,222 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"reflect"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/generatedtext"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptdebug"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+)
+
+type profileExecutionRequest struct {
+	Prepared    preparedReport
+	Prompt      PromptInspectionResult
+	Profile     promptexec.ProfileInspection
+	Executor    promptexec.Executor
+	DebugWriter *promptdebug.PromptDebugWriter
+	DebugRef    *promptdebug.PromptDebugRef
+}
+
+type profileExecutionOutcome struct {
+	ProfileID        string
+	BackendID        string
+	ModelName        string
+	ValidationStatus promptexec.ValidationStatus
+	RepairAttempts   *int
+	LLMDebugPath     string
+}
+
+type profileExecutionError struct {
+	operation       string
+	err             error
+	callbackFailure bool
+}
+
+func (e *profileExecutionError) Error() string {
+	return e.operation + ": " + e.err.Error()
+}
+
+func (e *profileExecutionError) Unwrap() error {
+	return e.err
+}
+
+func executePreparedProfile(ctx context.Context, req profileExecutionRequest) (profileExecutionOutcome, []byte, error) {
+	outcome := profileExecutionOutcome{
+		ProfileID: req.Profile.ProfileID,
+		BackendID: req.Profile.BackendID,
+		ModelName: req.Profile.ModelName,
+	}
+	if req.Executor == nil {
+		return outcome, nil, &profileExecutionError{operation: "execute prompt", err: promptexec.NewError(promptexec.InvalidConfiguration, "prompt executor is required", nil)}
+	}
+	if err := validatePreparedExecutionRequest(req); err != nil {
+		return outcome, nil, &profileExecutionError{operation: "validate prompt provenance", err: err}
+	}
+
+	callbackFailed := false
+	preparationCount := 0
+	var preparation promptexec.Preparation
+	preparationCallback := func(value promptexec.Preparation, debug *promptexec.PreparationDebug) error {
+		preparationCount++
+		if preparationCount != 1 {
+			return promptProvenanceError()
+		}
+		if err := validatePreparationProvenance(req, value); err != nil {
+			return err
+		}
+		preparation = clonePreparation(value)
+		if req.DebugWriter == nil || !req.DebugWriter.Enabled() {
+			return nil
+		}
+		if req.DebugRef == nil {
+			callbackFailed = true
+			return promptDebugWriteError(fmt.Errorf("prompt debug reference is required"))
+		}
+		path, err := req.DebugWriter.WritePreparation(*req.DebugRef, value, debug)
+		if err != nil {
+			callbackFailed = true
+			return promptDebugWriteError(err)
+		}
+		outcome.LLMDebugPath = path
+		return nil
+	}
+
+	captureDebug := req.DebugWriter != nil && req.DebugWriter.Enabled()
+	execution, err := req.Executor.Execute(ctx, promptexec.ExecuteRequest{
+		PromptID:      req.Prompt.PromptID,
+		PromptVersion: req.Prompt.PromptVersion,
+		ProfileID:     req.Profile.ProfileID,
+		DataPackage:   req.Prepared.dataPackageCopy(),
+		CaptureDebug:  captureDebug,
+	}, preparationCallback)
+	if err != nil {
+		if callbackFailed {
+			return outcome, nil, &profileExecutionError{operation: "execute prompt", err: err, callbackFailure: true}
+		}
+		if req.DebugWriter != nil && req.DebugWriter.Enabled() && req.DebugRef != nil {
+			var generationError *promptexec.GenerationError
+			if errors.As(err, &generationError) {
+				path, debugErr := req.DebugWriter.WriteFailure(*req.DebugRef, generationError)
+				if path != "" {
+					outcome.LLMDebugPath = path
+				}
+				if debugErr != nil {
+					err = errors.Join(err, promptDebugWriteError(debugErr))
+				}
+			}
+		}
+		return outcome, nil, &profileExecutionError{operation: "execute prompt", err: classifiedPromptError("prompt execution failed", err)}
+	}
+	if execution == nil {
+		return outcome, nil, &profileExecutionError{operation: "execute prompt", err: promptexec.NewError(promptexec.Generation, "prompt executor returned no execution", nil)}
+	}
+	outcome.RepairAttempts = repairAttemptsPointer(execution.Validation.RepairAttempts)
+	if preparationCount != 1 {
+		return outcome, nil, &profileExecutionError{operation: "validate prompt provenance", err: promptProvenanceError()}
+	}
+	if err := validateExecutionProvenance(req, preparation, *execution); err != nil {
+		return outcome, nil, &profileExecutionError{operation: "validate prompt provenance", err: err}
+	}
+	outcome.ValidationStatus = execution.Validation.Status
+	if err := generatedtext.ValidateRawOutput(execution.RawOutput); err != nil {
+		return outcome, nil, &profileExecutionError{operation: "validate generated text", err: err}
+	}
+	if req.DebugWriter != nil && req.DebugWriter.Enabled() {
+		if req.DebugRef == nil {
+			return outcome, nil, &profileExecutionError{operation: "write prompt debug", err: promptDebugWriteError(fmt.Errorf("prompt debug reference is required"))}
+		}
+		path, err := req.DebugWriter.WriteExecution(*req.DebugRef, *execution)
+		if err != nil {
+			return outcome, nil, &profileExecutionError{operation: "write prompt debug", err: promptDebugWriteError(err)}
+		}
+		if path != "" {
+			outcome.LLMDebugPath = path
+		}
+	}
+
+	if execution.Validation.Status != promptexec.ValidationPassed && execution.Validation.Status != promptexec.ValidationFailed {
+		return outcome, nil, &profileExecutionError{operation: "validate prompt execution", err: promptexec.NewError(promptexec.OperationalValidation, "prompt execution did not complete validation", nil)}
+	}
+	if execution.Validation.Status == promptexec.ValidationFailed {
+		return outcome, nil, &profileExecutionError{operation: "validate prompt execution", err: promptexec.NewError(promptexec.ValidationRejected, "prompt output did not satisfy its schema", nil)}
+	}
+
+	generatedText, err := req.Prepared.handler.Validate(execution.RawOutput)
+	if err != nil {
+		return outcome, nil, &profileExecutionError{operation: "validate generated text", err: err}
+	}
+	identity, snapshot, derived, err := req.Prepared.renderInputs()
+	if err != nil {
+		return outcome, nil, &profileExecutionError{operation: "copy prepared render inputs", err: err}
+	}
+	renderContext, err := req.Prepared.handler.BuildRenderContext(identity, snapshot, derived, generatedText)
+	if err != nil {
+		return outcome, nil, &profileExecutionError{operation: "build render context", err: err}
+	}
+	rendered, err := req.Prepared.handler.Render(renderContext)
+	if err != nil {
+		return outcome, nil, &profileExecutionError{operation: "render template", err: err}
+	}
+	return outcome, rendered, nil
+}
+
+func validatePreparedExecutionRequest(req profileExecutionRequest) error {
+	definition := req.Prepared.resolved.Definition
+	if definition.PromptID != req.Prompt.PromptID || definition.PromptVersion != req.Prompt.PromptVersion ||
+		definition.GeneratedTextSchemaID != req.Prepared.handler.SchemaID() {
+		return promptProvenanceError()
+	}
+	if req.Prompt.ProfileID != "" && (req.Prompt.ProfileID != req.Profile.ProfileID || req.Prompt.BackendID != req.Profile.BackendID || req.Prompt.ModelName != req.Profile.ModelName) {
+		return promptProvenanceError()
+	}
+	if req.Prompt.PromptHash == "" || req.Profile.ProfileID == "" || req.Profile.ModelName == "" {
+		return promptProvenanceError()
+	}
+	return nil
+}
+
+func validatePreparationProvenance(req profileExecutionRequest, preparation promptexec.Preparation) error {
+	definition := req.Prepared.resolved.Definition
+	if preparation.PromptID != req.Prompt.PromptID || preparation.PromptVersion != req.Prompt.PromptVersion || preparation.PromptHash != req.Prompt.PromptHash ||
+		preparation.ProfileID != req.Profile.ProfileID || preparation.BackendID != req.Profile.BackendID || preparation.ModelName != req.Profile.ModelName ||
+		!validPromptOutput(definition, preparation.Output) {
+		return promptProvenanceError()
+	}
+	return nil
+}
+
+func validateExecutionProvenance(req profileExecutionRequest, preparation promptexec.Preparation, execution promptexec.Execution) error {
+	definition := req.Prepared.resolved.Definition
+	if execution.PromptID != preparation.PromptID || execution.PromptVersion != preparation.PromptVersion || execution.PromptHash != preparation.PromptHash ||
+		execution.RenderedPromptHash != preparation.RenderedPromptHash || !reflect.DeepEqual(execution.InputHashes, preparation.InputHashes) ||
+		execution.ProfileID != preparation.ProfileID || execution.BackendID != preparation.BackendID || execution.ModelName != preparation.ModelName ||
+		execution.Validation.Mode != "json_schema" || execution.Validation.SchemaPath != definition.GeneratedTextSchemaID+".generated_text.schema.json" ||
+		execution.Validation.RepairAttempts < 0 || execution.Validation.RepairAttempts > preparation.Output.RepairAttempts ||
+		preparation.Output.RepairAttempts != definition.GeneratedTextRepairAttempts {
+		return promptProvenanceError()
+	}
+	return nil
+}
+
+func repairAttemptsPointer(value int) *int {
+	copy := value
+	return &copy
+}
+
+func promptProvenanceError() error {
+	return promptexec.NewError(promptexec.InvalidConfiguration, "prompt execution provenance is inconsistent", nil)
+}
+
+func clonePreparation(value promptexec.Preparation) promptexec.Preparation {
+	if value.InputHashes != nil {
+		inputHashes := make(map[string]string, len(value.InputHashes))
+		for name, hash := range value.InputHashes {
+			inputHashes[name] = hash
+		}
+		value.InputHashes = inputHashes
+	}
+	return value
+}

internal/app/profile_execution_test.go

@@ -0,0 +1,190 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/collect"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/generatedtext"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptdebug"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+)
+
+func TestExecutePreparedProfileRendersWithoutPublishing(t *testing.T) {
+	prepared, inspection := preparedDailyProfile(t)
+	executor := &generationExecutor{}
+	outputPath := filepath.Join(t.TempDir(), "report.md")
+	outcome, rendered, err := executePreparedProfile(context.Background(), profileExecutionRequest{
+		Prepared: prepared, Prompt: inspection,
+		Profile:  promptexec.ProfileInspection{ProfileID: inspection.ProfileID, BackendID: inspection.BackendID, ModelName: inspection.ModelName},
+		Executor: executor,
+	})
+	if err != nil {
+		t.Fatalf("executePreparedProfile() error = %v", err)
+	}
+	if len(rendered) == 0 || outcome.ValidationStatus != promptexec.ValidationPassed || outcome.RepairAttempts == nil || *outcome.RepairAttempts != 0 || outcome.ProfileID != inspection.ProfileID || executor.executeCalls != 1 {
+		t.Fatalf("outcome/rendered/execution calls = %#v/%q/%d", outcome, rendered, executor.executeCalls)
+	}
+	if _, statErr := os.Stat(outputPath); !os.IsNotExist(statErr) {
+		t.Fatalf("execution unexpectedly published %q: %v", outputPath, statErr)
+	}
+}
+
+func TestExecutePreparedProfileRetainsCompletedRepairAttemptsOnLaterFailure(t *testing.T) {
+	prepared, inspection := preparedDailyProfile(t)
+	prepared.resolved.Definition.GeneratedTextRepairAttempts = 1
+	executor := &generationExecutor{repairAttempts: 1, rawOutput: []byte(`{"summary":42}`), prepare: func(value *promptexec.Preparation) { value.Output.RepairAttempts = 1 }}
+	outcome, _, err := executePreparedProfile(context.Background(), profileExecutionRequest{
+		Prepared: prepared, Prompt: inspection,
+		Profile:  promptexec.ProfileInspection{ProfileID: inspection.ProfileID, BackendID: inspection.BackendID, ModelName: inspection.ModelName},
+		Executor: executor,
+	})
+	if err == nil || outcome.RepairAttempts == nil || *outcome.RepairAttempts != 1 {
+		t.Fatalf("outcome/error = %#v/%v", outcome, err)
+	}
+}
+
+func TestExecutePreparedProfileKeepsDebugCallbackFailureLocal(t *testing.T) {
+	prepared, inspection := preparedDailyProfile(t)
+	debugWriter, err := promptdebug.NewPromptDebugWriter(t.TempDir())
+	if errors.Is(err, promptdebug.ErrSecureCaptureUnsupported) {
+		t.Skipf("secure prompt debug capture is unavailable: %v", err)
+	}
+	if err != nil {
+		t.Fatalf("NewPromptDebugWriter() error = %v", err)
+	}
+	executor := &generationExecutor{}
+	outcome, rendered, err := executePreparedProfile(context.Background(), profileExecutionRequest{
+		Prepared: prepared, Prompt: inspection,
+		Profile:  promptexec.ProfileInspection{ProfileID: inspection.ProfileID, BackendID: inspection.BackendID, ModelName: inspection.ModelName},
+		Executor: executor, DebugWriter: debugWriter,
+		DebugRef: &promptdebug.PromptDebugRef{ReportID: inspectionResolved(t).Definition.ID, ValidDate: "2026-05-29", RunID: "invalid/path"},
+	})
+	var executionErr *profileExecutionError
+	if err == nil || !errors.As(err, &executionErr) || !executionErr.callbackFailure || promptexec.CategoryOf(err) != promptexec.InvalidConfiguration || len(rendered) != 0 || executor.executeCalls != 0 || outcome.LLMDebugPath != "" {
+		t.Fatalf("outcome/rendered/error/execution calls = %#v/%q/%v/%d", outcome, rendered, err, executor.executeCalls)
+	}
+}
+
+func TestExecutePreparedProfileBoundsOversizedExecutorOutput(t *testing.T) {
+	prepared, inspection := preparedDailyProfile(t)
+	marker := "provider-controlled-marker"
+	executor := &generationExecutor{rawOutput: []byte(strings.Repeat("x", generatedtext.MaxGeneratedTextBytes+1) + marker)}
+	_, _, err := executePreparedProfile(context.Background(), profileExecutionRequest{
+		Prepared: prepared, Prompt: inspection,
+		Profile:  promptexec.ProfileInspection{ProfileID: inspection.ProfileID, BackendID: inspection.BackendID, ModelName: inspection.ModelName},
+		Executor: executor,
+	})
+	if err == nil || !strings.Contains(err.Error(), "65536-byte limit") {
+		t.Fatalf("executePreparedProfile() error = %v, want bounded raw size error", err)
+	}
+	if len(err.Error()) > 160 || strings.Contains(err.Error(), marker) {
+		t.Fatalf("ordinary error leaked provider content: %q", err)
+	}
+}
+
+func TestExecutePreparedProfileRejectsInconsistentProvenance(t *testing.T) {
+	tests := []struct {
+		name    string
+		mutate  func(*preparedReport, *PromptInspectionResult, *promptexec.ProfileInspection, *generationExecutor)
+		invoked bool
+	}{
+		{
+			name: "prepared definition", mutate: func(prepared *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, _ *generationExecutor) {
+				prepared.resolved.Definition.PromptVersion = "different-version"
+			},
+		},
+		{
+			name: "missing callback", mutate: func(_ *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, executor *generationExecutor) {
+				executor.skipPreparation = true
+			}, invoked: true,
+		},
+		{
+			name: "duplicate callback", mutate: func(_ *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, executor *generationExecutor) {
+				executor.preparationCalls = 2
+			},
+		},
+		{
+			name: "callback prompt hash", mutate: func(_ *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, executor *generationExecutor) {
+				executor.prepare = func(value *promptexec.Preparation) { value.PromptHash = "different-hash" }
+			},
+		},
+		{
+			name: "callback output schema", mutate: func(_ *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, executor *generationExecutor) {
+				executor.prepare = func(value *promptexec.Preparation) { value.Output.SchemaPath = "other.generated_text.schema.json" }
+			},
+		},
+		{
+			name: "completed profile", mutate: func(_ *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, executor *generationExecutor) {
+				executor.complete = func(value *promptexec.Execution) { value.ProfileID = "different-profile" }
+			}, invoked: true,
+		},
+		{
+			name: "completed rendered prompt hash", mutate: func(_ *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, executor *generationExecutor) {
+				executor.complete = func(value *promptexec.Execution) { value.RenderedPromptHash = "different-rendered-hash" }
+			}, invoked: true,
+		},
+		{
+			name: "completed input hashes", mutate: func(_ *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, executor *generationExecutor) {
+				executor.prepare = func(value *promptexec.Preparation) {
+					value.InputHashes = map[string]string{"data_package": "prepared-hash"}
+				}
+				executor.complete = func(value *promptexec.Execution) {
+					value.InputHashes = map[string]string{"data_package": "completed-hash"}
+				}
+			}, invoked: true,
+		},
+		{
+			name: "completed validation mode", mutate: func(_ *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, executor *generationExecutor) {
+				executor.complete = func(value *promptexec.Execution) { value.Validation.Mode = "other" }
+			}, invoked: true,
+		},
+		{
+			name: "completed validation schema", mutate: func(_ *preparedReport, _ *PromptInspectionResult, _ *promptexec.ProfileInspection, executor *generationExecutor) {
+				executor.complete = func(value *promptexec.Execution) { value.Validation.SchemaPath = "other.generated_text.schema.json" }
+			}, invoked: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			prepared, inspection := preparedDailyProfile(t)
+			profile := promptexec.ProfileInspection{ProfileID: inspection.ProfileID, BackendID: inspection.BackendID, ModelName: inspection.ModelName}
+			executor := &generationExecutor{}
+			tt.mutate(&prepared, &inspection, &profile, executor)
+
+			outcome, rendered, err := executePreparedProfile(context.Background(), profileExecutionRequest{Prepared: prepared, Prompt: inspection, Profile: profile, Executor: executor})
+			if err == nil || promptexec.CategoryOf(err) != promptexec.InvalidConfiguration || len(rendered) != 0 {
+				t.Fatalf("outcome/rendered/error = %#v/%q/%v", outcome, rendered, err)
+			}
+			if outcome.ProfileID != profile.ProfileID || outcome.BackendID != profile.BackendID || outcome.ModelName != profile.ModelName || outcome.ValidationStatus != "" {
+				t.Fatalf("outcome retained unverified provenance: %#v", outcome)
+			}
+			if (executor.executeCalls == 1) != tt.invoked {
+				t.Fatalf("executor calls = %d, want invoked=%t", executor.executeCalls, tt.invoked)
+			}
+		})
+	}
+}
+
+func preparedDailyProfile(t *testing.T) (preparedReport, PromptInspectionResult) {
+	t.Helper()
+	cfg := generationConfig()
+	resolved, err := ResolveGenerate(GenerateRequest{
+		Config: cfg, Report: ReportDaily,
+		Date: generationTime("2026-05-29T12:00:00-05:00"), Now: generationTime("2026-05-29T08:30:00-05:00"),
+	}, generationTime("2026-05-29T08:30:00-05:00"))
+	if err != nil {
+		t.Fatalf("ResolveGenerate() error = %v", err)
+	}
+	bundle := generationBundle(t)
+	prepared, err := prepareReport(prepareReportRequest{Config: cfg, Resolved: resolved, Collection: collect.Result{Bundle: &bundle}, handler: preparedHandler(t, resolved)})
+	if err != nil {
+		t.Fatalf("prepareReport() error = %v", err)
+	}
+	return prepared, PromptInspectionResult{PromptID: resolved.Definition.PromptID, PromptVersion: resolved.Definition.PromptVersion, PromptHash: generationPromptHash, ProfileID: "fixture", BackendID: "fixture", ModelName: "fixture-model"}
+}

internal/app/prompt_generate.go

@@ -0,0 +1,148 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/collect"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/fileutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptdebug"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+type promptReportRequest struct {
+	GenerateRequest
+	Resolved    report.Resolved
+	Collection  collect.Result
+	Inspection  PromptInspectionResult
+	DebugWriter *promptdebug.PromptDebugWriter
+	Result      *ReportResult
+	noNotify    bool
+}
+
+func generatePromptReport(ctx context.Context, req promptReportRequest) (*ReportResult, error) {
+	if req.Collection.Bundle == nil {
+		return nil, fmt.Errorf("collected weather bundle is required")
+	}
+	result := req.Result
+	if result == nil {
+		result = initialReportResult(req.GenerateRequest, req.Resolved, req.Inspection)
+	}
+	prepared, err := prepareReport(prepareReportRequest{Config: req.Config, Resolved: req.Resolved, Collection: req.Collection, handler: req.Inspection.handler})
+	if err != nil {
+		return result, generatedPreparationError(req.Resolved, result.RunID, err)
+	}
+	result.SourceWarnings = prepared.sourceWarningsCopy()
+	debugRef := promptdebug.PromptDebugRef{ReportID: result.ReportID, ValidDate: prepared.resolved.ValidPeriod.Start.Format("2006-01-02"), RunID: result.RunID}
+	outcome, rendered, err := executePreparedProfile(ctx, profileExecutionRequest{
+		Prepared: prepared,
+		Prompt:   req.Inspection,
+		Profile: promptexec.ProfileInspection{
+			ProfileID: req.Inspection.ProfileID,
+			BackendID: req.Inspection.BackendID,
+			ModelName: req.Inspection.ModelName,
+		},
+		Executor: req.Executor, DebugWriter: req.DebugWriter, DebugRef: &debugRef,
+	})
+	result.ProfileID, result.BackendID, result.ModelName = outcome.ProfileID, outcome.BackendID, outcome.ModelName
+	result.ValidationStatus = outcome.ValidationStatus
+	if outcome.RepairAttempts != nil {
+		result.RepairAttempts = repairAttemptsPointer(*outcome.RepairAttempts)
+	}
+	result.LLMDebugPath = outcome.LLMDebugPath
+	if err != nil {
+		return result, generatedProfileExecutionError(req.Resolved, result.RunID, err)
+	}
+	return publishPromptReport(ctx, promptPublicationRequest{
+		GenerateRequest:      req.GenerateRequest,
+		Resolved:             req.Resolved,
+		OutputPath:           req.OutputPath,
+		Result:               result,
+		Markdown:             rendered,
+		suppressNotification: req.noNotify,
+	})
+}
+
+func initialReportResult(req GenerateRequest, resolved report.Resolved, inspection PromptInspectionResult) *ReportResult {
+	metadata := resolved.Metadata()
+	return &ReportResult{
+		ReportID: resolved.Definition.ID, ReportName: resolved.Definition.Name,
+		PromptID: resolved.Definition.PromptID, PromptVersion: resolved.Definition.PromptVersion,
+		RunID: metadata.RunID, GeneratedAt: metadata.GeneratedAt, Timezone: req.Config.WeatherAPI.Timezone,
+		ValidPeriod: metadata.ValidPeriod,
+		ProfileID:   inspection.ProfileID, BackendID: inspection.BackendID, ModelName: inspection.ModelName,
+	}
+}
+
+type promptPublicationRequest struct {
+	GenerateRequest
+	Resolved             report.Resolved
+	OutputPath           string
+	Result               *ReportResult
+	Markdown             []byte
+	suppressNotification bool
+}
+
+func publishPromptReport(ctx context.Context, req promptPublicationRequest) (*ReportResult, error) {
+	if err := publicationContextError(ctx); err != nil {
+		return req.Result, generatedReportError(req.Resolved, req.Result.RunID, "publish report", err)
+	}
+	if err := fileutil.WriteFileAtomicContext(ctx, req.OutputPath, req.Markdown); err != nil {
+		if contextErr := publicationContextError(ctx); contextErr != nil {
+			return req.Result, generatedReportError(req.Resolved, req.Result.RunID, "publish report", contextErr)
+		}
+		return req.Result, err
+	}
+	req.Result.OutputPath = req.OutputPath
+	if req.suppressNotification {
+		return req.Result, nil
+	}
+	notification, err := notifyReport(ctx, req.Config, req.Resolved, req.Result.OutputPath, req.Result.RunID, req.Result.GeneratedAt, req.Notifier)
+	req.Result.Notification = notification
+	if err != nil {
+		return req.Result, err
+	}
+	return req.Result, nil
+}
+
+func generatedPreparationError(resolved report.Resolved, runID string, err error) error {
+	var preparation *preparationError
+	if errors.As(err, &preparation) {
+		return generatedReportError(resolved, runID, preparation.operation, preparation.err)
+	}
+	return generatedReportError(resolved, runID, "prepare report", err)
+}
+
+func generatedProfileExecutionError(resolved report.Resolved, runID string, err error) error {
+	var execution *profileExecutionError
+	if errors.As(err, &execution) {
+		if execution.callbackFailure {
+			return execution.err
+		}
+		return generatedReportError(resolved, runID, execution.operation, execution.err)
+	}
+	return generatedReportError(resolved, runID, "execute prompt", err)
+}
+
+func classifiedPromptError(operation string, err error) error {
+	if promptexec.CategoryOf(err) != "" {
+		return err
+	}
+	return promptexec.NewError(promptexec.Generation, operation, err)
+}
+
+func publicationContextError(ctx context.Context) error {
+	if err := ctx.Err(); err != nil {
+		if errors.Is(err, context.DeadlineExceeded) {
+			return promptexec.NewError(promptexec.DeadlineExceeded, "context expired before output publication", err)
+		}
+		return promptexec.NewError(promptexec.Canceled, "context canceled before output publication", err)
+	}
+	return nil
+}
+
+func promptDebugWriteError(err error) error {
+	return promptexec.NewError(promptexec.InvalidConfiguration, "write requested prompt debug artifact", err)
+}

internal/app/prompt_inspection.go

@@ -0,0 +1,226 @@
+package app
+
+import (
+	"context"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/comparison"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/generatedtext"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptexec"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+// PromptInspectionRequest contains the non-executing inputs required to
+// validate one report's configured prompt and profile.
+type PromptInspectionRequest struct {
+	Resolved  report.Resolved
+	Executor  promptexec.Executor
+	Promptkit config.PromptkitConfig
+}
+
+// PromptInspectionResult contains only safe identity and provenance from a
+// prompt/profile inspection.
+type PromptInspectionResult struct {
+	PromptID      string
+	PromptVersion string
+	PromptHash    string
+	ProfileID     string
+	BackendID     string
+	ModelName     string
+	handler       generatedtext.Handler
+}
+
+// PromptExecutionsInspectionRequest validates all prompt/profile combinations
+// needed by a batch before collection begins.
+type PromptExecutionsInspectionRequest struct {
+	Resolved  []report.Resolved
+	Executor  promptexec.Executor
+	Promptkit config.PromptkitConfig
+}
+
+// ComparisonInspectionRequest contains the explicit profile selection for one
+// resolved prompt comparison. It intentionally has no configured profile field.
+type ComparisonInspectionRequest struct {
+	Resolved   report.Resolved
+	ProfileIDs []string
+	Executor   promptexec.Executor
+}
+
+// ComparisonInspectionResult contains the safe, shared prompt identity and
+// ordered effective profile identities for a comparison.
+type ComparisonInspectionResult struct {
+	PromptID      string
+	PromptVersion string
+	PromptHash    string
+	Profiles      []ComparisonProfileInspection
+	handler       generatedtext.Handler
+}
+
+// ComparisonProfileInspection contains one requested profile's safe effective
+// execution identity.
+type ComparisonProfileInspection struct {
+	ProfileID string
+	BackendID string
+	ModelName string
+}
+
+// InspectPromptExecution validates the exact prompt and profile needed for a
+// report before collection, execution, or durable writes begin.
+func InspectPromptExecution(ctx context.Context, req PromptInspectionRequest) (PromptInspectionResult, error) {
+	results, err := InspectPromptExecutions(ctx, PromptExecutionsInspectionRequest{
+		Resolved:  []report.Resolved{req.Resolved},
+		Executor:  req.Executor,
+		Promptkit: req.Promptkit,
+	})
+	if err != nil {
+		return PromptInspectionResult{}, err
+	}
+	return results[req.Resolved.Definition.ID], nil
+}
+
+// InspectPromptExecutions validates exact prompt contracts and their unique
+// effective profiles. It performs no collection, execution, or durable write.
+func InspectPromptExecutions(ctx context.Context, req PromptExecutionsInspectionRequest) (map[report.ID]PromptInspectionResult, error) {
+	if req.Executor == nil {
+		return nil, promptexec.NewError(promptexec.InvalidConfiguration, "prompt executor is required", nil)
+	}
+	results := make(map[report.ID]PromptInspectionResult, len(req.Resolved))
+	profiles := map[string]promptexec.ProfileInspection{}
+	for _, resolved := range req.Resolved {
+		definition := resolved.Definition
+		handler, err := generatedtext.LookupDefinition(definition)
+		if err != nil {
+			return nil, promptexec.NewError(promptexec.InvalidConfiguration, "report generated-text catalog is incompatible", err)
+		}
+		inspection, err := inspectPromptContract(ctx, req.Executor, definition)
+		if err != nil {
+			return nil, err
+		}
+		profileID := req.Promptkit.Profile
+		if profileID == "" {
+			profileID = inspection.DefaultProfileID
+		}
+		if strings.TrimSpace(profileID) == "" {
+			return nil, promptexec.NewError(promptexec.InvalidConfiguration, "prompt has no execution profile", nil)
+		}
+		profile, ok := profiles[profileID]
+		if !ok {
+			profile, err = inspectPromptProfile(ctx, req.Executor, profileID)
+			if err != nil {
+				return nil, err
+			}
+			profiles[profileID] = profile
+		}
+		results[definition.ID] = PromptInspectionResult{
+			PromptID: inspection.PromptID, PromptVersion: inspection.PromptVersion, PromptHash: inspection.PromptHash,
+			ProfileID: profile.ProfileID, BackendID: profile.BackendID, ModelName: profile.ModelName,
+			handler: handler,
+		}
+	}
+	return results, nil
+}
+
+// InspectComparisonExecution validates one exact prompt and every explicitly
+// requested profile before collection or model execution. Profiles are
+// inspected sequentially in request order. If a profile fails, the returned
+// partial result retains the prompt identity and successfully inspected prefix.
+func InspectComparisonExecution(ctx context.Context, req ComparisonInspectionRequest) (ComparisonInspectionResult, error) {
+	if err := comparison.ValidateProfileIDs(req.ProfileIDs); err != nil {
+		return ComparisonInspectionResult{}, promptexec.NewError(promptexec.InvalidRequest, "comparison profile selection is invalid", err)
+	}
+	if req.Executor == nil {
+		return ComparisonInspectionResult{}, promptexec.NewError(promptexec.InvalidConfiguration, "prompt executor is required", nil)
+	}
+
+	handler, err := generatedtext.LookupDefinition(req.Resolved.Definition)
+	if err != nil {
+		return ComparisonInspectionResult{}, comparisonInspectionError("comparison generated-text catalog inspection failed", promptexec.NewError(promptexec.InvalidConfiguration, "report generated-text catalog is incompatible", err))
+	}
+	inspection, err := inspectPromptContract(ctx, req.Executor, req.Resolved.Definition)
+	if err != nil {
+		return ComparisonInspectionResult{}, comparisonInspectionError("comparison prompt inspection failed", err)
+	}
+	result := ComparisonInspectionResult{
+		PromptID:      inspection.PromptID,
+		PromptVersion: inspection.PromptVersion,
+		PromptHash:    inspection.PromptHash,
+		Profiles:      make([]ComparisonProfileInspection, 0, len(req.ProfileIDs)),
+		handler:       handler,
+	}
+	for _, profileID := range req.ProfileIDs {
+		profile, err := inspectPromptProfile(ctx, req.Executor, profileID)
+		if err != nil {
+			return result, comparisonInspectionError("comparison profile inspection failed", err)
+		}
+		result.Profiles = append(result.Profiles, ComparisonProfileInspection{
+			ProfileID: profile.ProfileID,
+			BackendID: profile.BackendID,
+			ModelName: profile.ModelName,
+		})
+	}
+	return result, nil
+}
+
+func inspectPromptContract(ctx context.Context, executor promptexec.Executor, definition report.Definition) (promptexec.PromptInspection, error) {
+	if strings.TrimSpace(definition.PromptID) == "" || strings.TrimSpace(definition.PromptVersion) == "" {
+		return promptexec.PromptInspection{}, promptexec.NewError(promptexec.InvalidConfiguration, "report prompt identity is incomplete", nil)
+	}
+	inspection, err := executor.InspectPrompt(ctx, definition.PromptID, definition.PromptVersion)
+	if err != nil {
+		return promptexec.PromptInspection{}, promptInspectionError("prompt inspection failed", err)
+	}
+	if inspection.PromptID != definition.PromptID || inspection.PromptVersion != definition.PromptVersion {
+		return promptexec.PromptInspection{}, promptexec.NewError(promptexec.InvalidConfiguration, "prompt inspection did not return the requested prompt version", nil)
+	}
+	if strings.TrimSpace(inspection.PromptHash) == "" {
+		return promptexec.PromptInspection{}, promptexec.NewError(promptexec.InvalidConfiguration, "prompt inspection did not return a prompt hash", nil)
+	}
+	if !validPromptInput(inspection.Inputs) {
+		return promptexec.PromptInspection{}, promptexec.NewError(promptexec.InvalidConfiguration, "prompt must declare exactly one required application/yaml data_package input", nil)
+	}
+	if !validPromptOutput(definition, inspection.Output) {
+		return promptexec.PromptInspection{}, promptexec.NewError(promptexec.InvalidConfiguration, "prompt must declare the report JSON Schema output contract", nil)
+	}
+	return inspection, nil
+}
+
+func inspectPromptProfile(ctx context.Context, executor promptexec.Executor, profileID string) (promptexec.ProfileInspection, error) {
+	profile, err := executor.InspectProfile(ctx, profileID)
+	if err != nil {
+		return promptexec.ProfileInspection{}, promptInspectionError("profile inspection failed", err)
+	}
+	if profile.ProfileID != profileID {
+		return promptexec.ProfileInspection{}, promptexec.NewError(promptexec.InvalidConfiguration, "profile inspection did not return the selected profile", nil)
+	}
+	if profile.CredentialRequired {
+		return promptexec.ProfileInspection{}, promptexec.NewError(promptexec.MissingCredential, "selected profile requires an unsupported direct API key", nil)
+	}
+	if strings.TrimSpace(profile.ModelName) == "" {
+		return promptexec.ProfileInspection{}, promptexec.NewError(promptexec.InvalidConfiguration, "profile inspection did not return a complete execution identity", nil)
+	}
+	return profile, nil
+}
+
+func validPromptInput(inputs []promptexec.InputDefinition) bool {
+	return len(inputs) == 1 && inputs[0].Name == "data_package" && inputs[0].Required && inputs[0].ContentType == "application/yaml"
+}
+
+func validPromptOutput(definition report.Definition, output promptexec.OutputContract) bool {
+	return output.Format == "json" && output.ValidationMode == "json_schema" && output.SchemaPath == definition.GeneratedTextSchemaID+".generated_text.schema.json" && output.RepairAttempts == definition.GeneratedTextRepairAttempts
+}
+
+func promptInspectionError(operation string, err error) error {
+	if promptexec.CategoryOf(err) != "" {
+		return err
+	}
+	return promptexec.NewError(promptexec.InvalidConfiguration, operation, err)
+}
+
+func comparisonInspectionError(operation string, err error) error {
+	category := promptexec.CategoryOf(err)
+	if category == "" {
+		category = promptexec.InvalidConfiguration
+	}
+	return promptexec.NewError(category, operation, err)
+}