Refresh cleanup-related documentation

docs/internal/state.md

@@ -4,7 +4,7 @@ This document describes filesystem state in `internal/state`.
 
 ## Purpose
 
-`internal/state` owns managed artifact paths, atomic JSON writes, persisted
+`internal/state` owns managed workspace paths, atomic JSON writes, persisted
 metadata, prior snapshot lookup, and read-only artifact inspection helpers.
 
 ## Inputs And Outputs
@@ -32,11 +32,13 @@ Outputs:
 
 ## Boundaries
 
-- This package owns managed workspace layout, path validation, filesystem
-  writes, and metadata reads.
-- It does not fetch weather data, derive forecasts, build prompt input content,
-  compare briefing contents, invoke Scriptorium, import adapter result types, or
-  parse CLI flags.
+`internal/state` owns local filesystem layout, path validation, durable writes,
+metadata reads, prior lookup, and report listing. It does not fetch weather
+data, derive forecasts, build prompt input content, compare briefing contents,
+invoke Scriptorium, import adapter result types, or parse CLI flags.
+
+Preflight persistence uses the state-owned `PreflightArtifact` shape. The app
+converts adapter render results into that shape before saving.
 
 ## Config Fields Used
 
@@ -49,31 +51,48 @@ Outputs:
 Workspace subdirectories must be relative paths that stay under
 `workspace.root`.
 
-## External Adapters Used
+## Managed Layout
 
-- local filesystem
+Paths are derived from the resolved report definition's artifact group, the
+valid-period start date for JSON artifacts, and the RunID.
 
-## State Or Manifest Behavior
+```text
+<workspace.root>/
+  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.briefing.json
+  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.metadata.json
+  data-packages/<artifact_group>/<YYYY-MM-DD>/<run_id>.data_package.json
+  preflight/<artifact_group>/<YYYY-MM-DD>/<run_id>.render.json
+  reports/<artifact_group>/<run_id>.md
+```
 
-Managed paths are grouped by the report definition's artifact group and
-valid-period start date for JSON artifacts. Reports are written under the same
-artifact group. Metadata is stored beside briefing snapshots and links
-briefing, data package, preflight, and report paths. Report listing walks
-metadata files under the snapshots directory.
+Metadata is stored beside briefing snapshots and links the briefing, data
+package, preflight, and report paths. Report listing walks metadata files under
+the snapshots directory.
 
-Prior snapshot lookup reads metadata through the shared lookup path and selects
-the latest earlier snapshot whose report ID is compatible according to the
-current report definition. Daily Today and Daily Tomorrow are compatible with
-each other for the same valid local date. 3-Day Outlook compares with prior
-3-Day snapshots for the same valid local date. Weekend Outlook compares with
-prior Weekend snapshots for the same weekend window. Storm Report currently has
-no prior lookup because its comparison strategy is not searched by the
-filesystem store.
+## Prior Lookup
 
-## Skip And Resume Behavior
+Prior snapshot lookup reads stored metadata through the shared lookup path and
+selects the latest earlier snapshot whose report ID is compatible with the
+current report definition.
 
-There is no resume workflow. Missing metadata directories return no inspection
-records or no prior snapshot rather than creating state.
+- Daily Today and Daily Tomorrow are compatible with each other for the same
+  valid local date.
+- 3-Day Outlook compares with prior 3-Day snapshots for the same valid local
+  date.
+- Weekend Outlook compares with prior Weekend snapshots for the same weekend
+  window.
+- Storm Report currently has no prior lookup because explicit event-window
+  comparison is not searched by the filesystem store.
+
+## Writes And Inspection
+
+Durable JSON writes use shared atomic file helpers. Managed Markdown reports are
+prepared by creating their parent directory; Scriptorium writes the report body
+to the prepared path. Extra Markdown copies are handled by app orchestration.
+
+Inspection helpers read existing metadata, briefing, and data package files.
+Missing metadata directories return no inspection records or no prior snapshot
+rather than creating state.
 
 ## Failure Behavior
 
@@ -93,5 +112,6 @@ Inspect:
 ## Invariants
 
 - Managed paths stay under the configured workspace root.
+- Artifact grouping comes from report definitions.
 - Metadata links artifacts produced for a run.
 - Prior lookup is based on structured metadata, not rendered report text.