Add filesystem state metadata baseline

docs/cli.md

@@ -1,9 +1,10 @@
 # Weatherreporter CLI
 
-`weatherreporter generate daily` currently writes a Daily prompt input data
-package and runs `scriptorium render` as a preflight check. Other report
-generation and scheduled runs still resolve configuration, report definitions,
-and valid periods, then return a not-implemented error.
+`weatherreporter generate daily` currently writes managed Daily preparation
+artifacts under the configured workspace and runs `scriptorium render` as a
+preflight check. Other report generation and scheduled runs still resolve
+configuration, report definitions, and valid periods, then return a
+not-implemented error.
 
 ## Shortest Useful Command
 
@@ -12,8 +13,9 @@ weatherreporter generate daily --date 2026-05-29 --out ./daily.data_package.json
 ```
 
 The command parses flags, loads configuration, fetches weather data, builds a
-Daily briefing, writes the `data_package` JSON artifact to `--out`, and invokes
-`scriptorium render --input data_package=<path> --format json`.
+Daily briefing, writes workspace artifacts, and invokes
+`scriptorium render --input data_package=<managed_path> --format json`. When
+`--out` is supplied, it also writes a copy of the data package to that path.
 
 ## Command Overview
 
@@ -27,11 +29,11 @@ weatherreporter run morning
 weatherreporter run evening
 ```
 
-`generate daily` writes a data package JSON artifact, writes the Daily briefing
-snapshot under the configured workspace, and writes the render preflight output
-under the configured workspace. Other `generate` commands resolve one report
-request and stop before report generation. `run` commands resolve a scheduled
-batch request and stop before execution.
+`generate daily` writes a briefing snapshot, prompt input data package, render
+preflight output, and metadata file under the configured workspace. Other
+`generate` commands resolve one report request and stop before report
+generation. `run` commands resolve a scheduled batch request and stop before
+execution.
 
 ## Flags
 
@@ -39,7 +41,7 @@ batch request and stop before execution.
 - `--config PATH`: load configuration from `PATH` instead of `/usr/local/etc/weatherreporter/config.yml`.
 - `--units VALUE`: override configured Weather API units.
 - `--tz NAME`: override configured Weather API timezone.
-- `--out PATH`: data package output path for `generate daily`; reserved for later generated report output on other `generate` commands.
+- `--out PATH`: optional extra data package copy for `generate daily`; reserved for later generated report output on other `generate` commands.
 - `--date YYYY-MM-DD`: optional date for `generate daily`; defaults to the current local date in the configured timezone.
 - `--start TIME`: required start time for `generate storm`.
 - `--end TIME`: required end time for `generate storm`.

docs/internal/state.md

@@ -0,0 +1,69 @@
+# State Internals
+
+This document describes the implemented filesystem state boundary.
+
+## Purpose
+
+`internal/state` owns durable artifact paths, atomic JSON writes, metadata, and
+prior Daily snapshot lookup.
+
+## Inputs and Outputs
+
+Inputs:
+
+- workspace configuration
+- resolved report definition and valid period
+- briefing package
+- prompt input data package
+- `scriptorium render` result
+
+Outputs:
+
+- briefing snapshot JSON
+- prompt input data package JSON
+- render preflight JSON
+- metadata JSON
+- prior Daily snapshot metadata when available
+
+## Boundaries
+
+- This package owns managed workspace layout and narrow path validation.
+- It does not fetch weather data, derive forecasts, build prompt inputs, invoke
+  `scriptorium`, or compare briefing contents.
+
+## Config Fields Used
+
+- `workspace.root`
+- `workspace.snapshots_dir`
+- `workspace.reports_dir`
+- `workspace.data_packages_dir`
+- `workspace.preflight_dir`
+
+Workspace subdirectories must be relative paths that stay under
+`workspace.root`.
+
+## State Behavior
+
+Managed artifact names use RunID, which is generated from report generation time
+and report ID. Daily metadata is stored beside Daily briefing snapshots by valid
+local date. Prior Daily snapshot lookup reads metadata for the same valid local
+date and returns the latest earlier run.
+
+## Failure Behavior
+
+Writes are atomic where practical: JSON is written to a temporary file in the
+target directory and then renamed into place. Invalid workspace paths and
+missing required metadata fields produce actionable errors.
+
+## Tests
+
+Inspect:
+
+- `internal/state/filesystem_test.go`
+- `internal/app/app_test.go`
+
+## Invariants
+
+- Managed paths stay under the configured workspace root.
+- Metadata links the artifacts produced for a run.
+- Prior lookup is based on structured metadata, not rendered report text.

docs/operations.md

@@ -0,0 +1,73 @@
+# Weatherreporter Operations
+
+## Normal Workflow
+
+The implemented preparation workflow is:
+
+```text
+weatherreporter generate daily --date 2026-05-29
+```
+
+The command fetches weather data, builds the Daily briefing, builds the prompt
+input data package, runs `scriptorium render`, and writes inspectable artifacts
+under the configured workspace.
+
+## Filesystem Layout
+
+The default workspace root is `workspace`.
+
+```text
+workspace/
+  snapshots/
+    daily/
+      YYYY-MM-DD/
+        <run_id>.briefing.json
+        <run_id>.metadata.json
+  data-packages/
+    daily/
+      YYYY-MM-DD/
+        <run_id>.data_package.json
+  preflight/
+    daily/
+      YYYY-MM-DD/
+        <run_id>.render.json
+  reports/
+    daily/
+      <run_id>.md
+```
+
+The report path is reserved in metadata for the eventual rendered report. The
+current workflow does not write the Markdown report.
+
+## Run Identifiers
+
+Run IDs are based on generation time plus report ID, such as:
+
+```text
+20260529T100000.123456789Z_daily_today
+```
+
+Managed artifact filenames use the RunID so repeated runs for the same valid
+date do not overwrite each other.
+
+## Metadata
+
+Each Daily preparation writes metadata that links:
+
+- RunID
+- report ID and prompt ID
+- generation time and valid period
+- source location, source hashes, and source warnings
+- briefing snapshot path
+- prompt input data package path
+- preflight output path
+- reserved rendered report path
+
+## Recovery
+
+If render preflight exits nonzero after producing a result, the captured stdout,
+stderr, exit code, and command are still written to the preflight artifact, and
+metadata is still written for inspection.
+
+The application does not currently implement resume, cleanup, archive, or
+remote storage behavior.