Refresh CLI collection and app internals

docs/internal/collect.md

@@ -1,58 +1,43 @@
 # Collection Internals
 
-This document describes the app-facing upstream collection boundary in
-`internal/collect`.
-
-## Purpose
-
-`internal/collect` is the canonical package used by app workflows to collect
-upstream Weather API data. It constructs the Weather API adapter, fetches a
-normalized bundle, and returns that bundle without applying report selection or
-batch policy.
+`internal/collect` is the application-facing boundary for collecting the
+normalized Weather API bundle. The external HTTP contract belongs in the
+[Weather API integration guide](../integrations/weatherapi.md); normalized data
+semantics belong in [weather-data internals](weather-data.md).
 
 ## Contract
 
-Inputs:
+`Run` accepts a `context.Context` and a `Request` containing effective
+`config.Config`. It constructs the Weather API adapter from that configuration,
+calls `FetchBundle`, and returns `Result{Bundle: *weatherdata.Bundle}`.
 
-- `collect.Request`, containing the effective `config.Config`
-- `context.Context` for cancellation
+The package wraps adapter construction failures as weather-collection setup
+errors and fetch failures as bundle-collection errors. It does not retry,
+persist, select reports, derive facts, build modules, invoke Scriptorium, or
+notify Distributor.
 
-Output:
+## Application Composition
 
-- `collect.Result`, containing `*weatherdata.Bundle`
+`internal/app` owns the narrow `Collector` interface used by workflow tests;
+the production implementation delegates to `collect.Run`. Generation, batch
+execution, and explicit bundle fetching all use this boundary. Application
+orchestration rejects a nil collector result or a nil bundle before report work
+can continue.
 
-`Run` returns an actionable error when Weather API adapter construction or
-bundle fetch fails. The package does not derive `facts.CollectedFacts`, build
-modules, resolve report periods, select reports, write state, invoke
-Scriptorium, or notify distributor.
+Single-report generation and a batch each collect once. A batch passes the same
+normalized collection to planning and to every report it generates. Collection
+failure prevents later workflow work for that request.
 
-## App Usage
+## Boundaries And Invariants
 
-`internal/app` owns a narrow `Collector` interface for orchestration tests. The
-default implementation calls `collect.Run`.
+Collection owns adapter creation and retrieval of one normalized bundle. It
+must not make report, period, batch, prompt, module, filesystem, or notification
+decisions.
 
-Single-report generation collects once, resolves the requested report, and
-passes the explicit collection into report generation. Batch generation
-collects once before planning and passes the same collection into each planned
-report. If collection returns no bundle, app orchestration returns an error
-before report generation.
+- 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.
 
-## Boundaries
-
-Weather API HTTP details stay in `internal/adapters/weatherapi`. The collection
-package returns normalized `weatherdata` only. It must not know about report
-IDs, prompt IDs, batch names, Daily eligibility, module composition, Recent
-Changes, state paths, or Scriptorium arguments.
-
-## Tests
-
-Inspect:
-
-- `internal/collect/collect_test.go`
-- `internal/app/app_test.go`
-
-## Invariants
-
-- App-facing Weather API collection goes through `internal/collect`.
-- Collection returns normalized source data, not report facts or prompt input.
-- Report and batch policy belongs outside `internal/collect`.
+Focused tests are in `internal/collect/collect_test.go`; orchestration use is
+also covered by `internal/app/app_test.go`.