# Documentation Roadmap

## Purpose

This roadmap defines the work required to bring `weatherreporter` documentation
into compliance with `docs/policy/documentation.md` and the current
implementation.

The migration must keep current-behavior documentation limited to implemented
behavior. Planned, future, aspirational, experimental, deprecated, or
unimplemented work belongs only under `docs/roadmap/`.

## Repository Documentation Inventory

- `README.md` - keep and lightly update. It already provides project purpose,
  quickstart commands, and documentation links, but it should remain short and
  should not link to stale implementation-roadmap material as though it were
  current documentation.
- `docs/cli.md` - keep and lightly update. It is the canonical CLI reference
  and should be checked against `internal/cli/root.go` and
  `internal/cli/root_test.go`.
- `docs/config.md` - keep and lightly update. It is the canonical
  configuration reference and should be checked against `internal/config/*`,
  `examples/config.yml`, and config tests.
- `docs/operations.md` - keep and lightly update. It documents implemented
  generation, batch, inspection, artifact, metadata, and recovery behavior.
  Some recurring failure-mode content should move or link to the new
  troubleshooting guide.
- `docs/troubleshooting.md` - create new. The project has enough implemented
  CLI, config, state, Weather API, and Scriptorium failure modes to warrant a
  focused troubleshooting guide.
- `docs/internal/briefing.md` - keep and standardize. It documents an
  implemented component, but it should be aligned with the full internal-doc
  field list required by the documentation policy.
- `docs/internal/changes.md` - keep and standardize. It documents implemented
  recent-change comparison and should remain scoped to structured snapshots,
  implemented report compatibility, and current thresholds.
- `docs/internal/forecast-derivation.md` - keep and standardize. It documents
  implemented forecast derivation and should explicitly identify config fields,
  adapter inputs, state behavior, and invariants.
- `docs/internal/prompt-input.md` - keep and standardize. It documents the
  implemented prompt input package and should stay focused on
  `internal/promptinput`.
- `docs/internal/report-registry.md` - keep and standardize. It documents the
  implemented registry and valid-period behavior.
- `docs/internal/scriptorium-adapter.md` - keep and standardize. It documents
  the implemented subprocess adapter and should link to
  `docs/integrations/scriptorium.md` for external contract details.
- `docs/internal/state.md` - keep and standardize. It documents implemented
  filesystem state and should remain canonical for internal state behavior.
- `docs/internal/weather-data.md` - keep and standardize. It documents the
  implemented Weather API adapter and forecast bundle boundary.
- `docs/internal/app-orchestration.md` - create new. `internal/app` is the
  implemented workflow coordinator and needs its own internal component doc.
- `docs/integrations/scriptorium.md` - keep and lightly update. It documents an
  actual external CLI integration and should stay limited to the commands,
  arguments, inputs, outputs, and exit behavior used by `weatherreporter`.
- `docs/integrations/weatherapi.md` - keep and rewrite. It currently describes
  more Weather API surface than `weatherreporter` uses; narrow it to the
  implemented fan-out endpoints, envelope conventions, query parameters, and
  source warning/provenance expectations.
- `docs/policy/architecture.md` - keep and lightly update only if accuracy
  issues are found. It is the canonical architecture policy.
- `docs/policy/development.md` - keep and rewrite. It currently reads like a
  proposed package layout and includes future/MVP language. It should become
  the canonical contributor workflow document.
- `docs/policy/documentation.md` - keep. It is the controlling documentation
  policy for this migration.
- `docs/roadmap/initial.md` - split and delete or replace. Much of it now
  describes completed implementation work; extract only still-future content
  into a future-only roadmap and remove this stale initial roadmap from the
  current documentation map.
- `examples/config.yml` - keep and lightly update. It is a maintained
  production-oriented example config and should be validated against the
  implemented config loader.
- `examples/minimal-config.yml` - create new only if the implementation pass
  adds a validation path for it. It should contain the smallest useful config
  for implemented generation behavior.

## Policy Compliance Assessment

Required documents for a modular, staged, CLI/config-driven, stateful
application are mostly present: `README.md`, `docs/cli.md`, `docs/config.md`,
`docs/operations.md`, `docs/internal/`, and `docs/policy/development.md`.
The main required gap is that `docs/policy/development.md` is not in the
canonical contributor-workflow shape required by `docs/policy/documentation.md`.

Recommended documentation gaps:

- `docs/troubleshooting.md` is missing.
- Validated examples are limited to `examples/config.yml`; there is no minimal
  example config.
- `docs/internal/app-orchestration.md` is missing for the implemented
  application workflow layer.

Documents that are stale or in the wrong canonical home:

- `docs/policy/development.md` contains proposed layout, MVP wording, and future
  design notes that should live in roadmap docs or be removed once implemented.
- `docs/roadmap/initial.md` should not be treated as a current implementation
  guide. It mixes completed MVP planning with deferred work.
- `README.md` links to the implementation roadmap. The README should link to
  current user/operator/developer docs and, if useful, a future-work roadmap
  that is clearly labeled as such.
- `docs/integrations/weatherapi.md` includes endpoint details beyond the
  implemented adapter fan-out and should be narrowed.

Content that appears planned, historical, or aspirational outside
`docs/roadmap/`:

- `docs/policy/development.md` uses proposed/future/MVP language and describes
  some behavior as intended rather than current contributor practice.
- Non-roadmap docs should be searched for future-oriented terms during the
  migration. Some instances in policy docs are legitimate policy wording, but
  feature-specific plans should move under `docs/roadmap/`.

Examples:

- `examples/config.yml` exists and matches the implemented configuration shape,
  but the documentation should state how it is validated.
- No generated report examples should be added unless they can be maintained
  without live Weather API and Scriptorium dependencies.
- No workflow examples should be added for unimplemented daemon, cleanup,
  archive, remote storage, or automatic storm monitoring behavior.

Links likely needing verification:

- README links to `docs/roadmap/initial.md`.
- Internal docs should link to canonical integration docs instead of repeating
  Scriptorium or Weather API details.
- Operations and troubleshooting should link to CLI and config reference rather
  than duplicating complete flag or field tables.

## Target Documentation Set

### `README.md`

- Audience: users, administrators, operators.
- Purpose: concise orientation and shortest useful generation command.
- Canonical scope: project purpose, elevator pitch, one minimal usage example,
  and links to targeted docs.
- Recommended outline: description, elevator pitch, shortest useful command,
  documentation links.
- Source-of-truth areas: `cmd/weatherreporter/main.go`,
  `internal/cli/root.go`, `internal/app/app.go`, `docs/cli.md`.
- Acceptance criteria: short enough to remain an orientation page; no
  unimplemented behavior; no stale roadmap link presented as current docs;
  commands match `weatherreporter --help`.

### `docs/cli.md`

- Audience: users, administrators, operators.
- Purpose: canonical CLI reference.
- Canonical scope: implemented commands, flags, workflows, diagnostics, and
  recovery-oriented inspect commands.
- Recommended outline: shortest useful command, command overview, flag
  reference, common workflows, inspection commands, exit behavior.
- Source-of-truth areas: `internal/cli/root.go`,
  `internal/cli/root_test.go`, `internal/app/app.go`,
  `internal/app/app_test.go`.
- Acceptance criteria: every documented command exists; every documented flag is
  parsed; `generate daily --date` is optional and documented as `YYYY-MM-DD`;
  batch nonzero behavior is documented; no unimplemented commands appear.

### `docs/config.md`

- Audience: administrators, operators, advanced users.
- Purpose: canonical configuration reference.
- Canonical scope: config discovery, precedence, minimal config, production
  config, full field reference, and examples.
- Recommended outline: file location and precedence, minimal config, production
  config, field reference, secrets handling, links to examples.
- Source-of-truth areas: `internal/config/config.go`,
  `internal/config/defaults.go`, `internal/config/load.go`,
  `internal/config/validate.go`, `internal/config/config_test.go`,
  `examples/config.yml`.
- Acceptance criteria: defaults match code; CLI overrides are accurate;
  `weather_api.base_url` is described as required for generation/fetching;
  no unused or future config fields appear.

### `docs/operations.md`

- Audience: administrators, operators.
- Purpose: operational workflows, state layout, inspection, recovery, and caveats.
- Canonical scope: implemented generation and batch operation, workspace layout,
  metadata, artifact inspection, retry/recovery behavior, and explicit
  non-behavior where operationally important.
- Recommended outline: normal workflow, filesystem layout, RunID and metadata,
  inspection, recent changes, recovery, current operational caveats.
- Source-of-truth areas: `internal/app/app.go`, `internal/app/inspect.go`,
  `internal/state/*`, `internal/report/*`, `internal/cli/root.go`.
- Acceptance criteria: workspace paths match `internal/state`; batch behavior
  matches `RunBatchDetailed`; recovery guidance reflects actual persisted
  artifacts; troubleshooting details are linked rather than duplicated.

### `docs/troubleshooting.md`

- Audience: administrators, operators.
- Purpose: symptom-driven diagnosis and safe fixes.
- Canonical scope: recurring failure modes for config loading, CLI parsing,
  Weather API fetching, missing data policy, Scriptorium render/run, workspace
  state, and inspect commands.
- Recommended outline: symptom, likely cause, diagnostic command or inspection
  step, safe fix, relevant links.
- Source-of-truth areas: `internal/cli/root.go`, `internal/config/*`,
  `internal/adapters/weatherapi/*`, `internal/adapters/scriptorium/*`,
  `internal/state/*`, tests for those packages.
- Acceptance criteria: entries are actionable; no speculative failures; links
  point to CLI/config/operations/integration docs; no secrets or private
  infrastructure examples.

### `docs/policy/architecture.md`

- Audience: developers and LLM coding agents.
- Purpose: canonical architecture policy and invariants.
- Canonical scope: project shape, boundaries, dependency policy, configuration,
  adapters, state, testing, and documentation expectations.
- Recommended outline: keep current structure unless implementation inspection
  reveals an inaccurate invariant.
- Source-of-truth areas: current package layout and tests.
- Acceptance criteria: policy remains principle-level; it does not become a
  package manual; current implementation does not obviously violate described
  invariants.

### `docs/policy/development.md`

- Audience: developers and LLM coding agents.
- Purpose: canonical contributor workflow.
- Canonical scope: repository layout, build/test commands, coding conventions,
  dependency policy, adding config fields, adding CLI flags, adding components
  and adapters, updating examples, and documentation expectations.
- Recommended outline: repository layout, local validation commands, coding
  conventions, dependencies, config changes, CLI changes, component/adapters,
  tests, docs/examples checklist.
- Source-of-truth areas: `go.mod`, package layout, `internal/config`,
  `internal/cli`, adapters, tests, `docs/policy/documentation.md`.
- Acceptance criteria: no MVP/proposed/future feature narrative; no duplicate
  full architecture manual; future work appears only as links to roadmap docs.

### `docs/internal/app-orchestration.md`

- Audience: developers and LLM coding agents.
- Purpose: describe implemented workflow orchestration in `internal/app`.
- Canonical scope: generation flow, batch flow, inspection flow, dependencies,
  state writes, preflight/run ordering, and failure behavior.
- Recommended outline: purpose, inputs and outputs, boundaries, config fields
  used, adapters used, state behavior, skip/resume behavior, failure behavior,
  tests, invariants.
- Source-of-truth areas: `internal/app/app.go`, `internal/app/inspect.go`,
  `internal/app/app_test.go`, `internal/state/*`.
- Acceptance criteria: documents `scriptorium render` before `scriptorium run`;
  documents metadata persistence before/after generation failures; does not
  expose adapter internals beyond orchestration needs.

### `docs/internal/briefing.md`

- Audience: developers and LLM coding agents.
- Purpose: implemented briefing package and report-specific briefing builders.
- Canonical scope: briefing inputs, outputs, boundaries, source warnings,
  metadata, report variants, tests, and invariants.
- Source-of-truth areas: `internal/briefing/*`, `internal/forecast/*`,
  briefing tests.
- Acceptance criteria: includes all internal-doc policy fields; no raw API
  endpoint documentation duplicated from integrations.

### `docs/internal/changes.md`

- Audience: developers and LLM coding agents.
- Purpose: structured recent-change comparison.
- Canonical scope: comparable snapshot inputs, thresholds, supported report
  strategies, output items, and empty-result behavior.
- Source-of-truth areas: `internal/changes/*`, `internal/report/*`,
  `internal/state/*`, changes tests.
- Acceptance criteria: states that comparisons use structured snapshots, not
  rendered Markdown; storm current behavior is accurate.

### `docs/internal/forecast-derivation.md`

- Audience: developers and LLM coding agents.
- Purpose: forecast derivation from normalized bundle data.
- Canonical scope: hourly requirement, dayparts, daily/period summaries,
  alerts, narrative/discussion usage, warnings, and failure behavior.
- Source-of-truth areas: `internal/forecast/*`, forecast tests and testdata.
- Acceptance criteria: config fields and adapter inputs are explicit; hourly
  failure behavior matches tests.

### `docs/internal/prompt-input.md`

- Audience: developers and LLM coding agents.
- Purpose: prompt input data package construction.
- Canonical scope: package schema, report metadata, briefing, recent changes,
  source warnings, validation, and boundaries.
- Source-of-truth areas: `internal/promptinput/*`, `internal/app/app.go`,
  prompt input tests.
- Acceptance criteria: uses `data_package` terminology; no `promptvars` or
  `--vars-file` terminology.

### `docs/internal/report-registry.md`

- Audience: developers and LLM coding agents.
- Purpose: report registry, prompt IDs, valid periods, batches, and comparison
  strategy declarations.
- Canonical scope: implemented report IDs, prompt IDs, default output naming,
  period resolution, batch composition, and compatibility behavior.
- Source-of-truth areas: `internal/report/*`, report tests,
  `internal/app/app.go`.
- Acceptance criteria: documents `weather.daily_report` for both Daily Today
  and Daily Tomorrow; no stale `weather.tomorrow_report`.

### `docs/internal/scriptorium-adapter.md`

- Audience: developers and LLM coding agents.
- Purpose: internal subprocess adapter boundary.
- Canonical scope: request structs, argv construction, context/timeouts,
  stdout/stderr capture, result handling, and errors.
- Source-of-truth areas: `internal/adapters/scriptorium/*`,
  scriptorium adapter tests.
- Acceptance criteria: no shell interpolation; domain packages do not receive
  Scriptorium-specific flags; links to integration contract for CLI details.

### `docs/internal/state.md`

- Audience: developers and LLM coding agents.
- Purpose: filesystem store, metadata, artifact paths, and lookup behavior.
- Canonical scope: workspace layout, RunID-managed files, metadata records,
  prior snapshot lookup, inspection, atomic write expectations, failure cases.
- Source-of-truth areas: `internal/state/*`, state tests,
  `internal/app/app.go`.
- Acceptance criteria: paths match code; no resume/archive/cleanup behavior is
  documented as implemented.

### `docs/internal/weather-data.md`

- Audience: developers and LLM coding agents.
- Purpose: Weather API adapter to internal forecast bundle.
- Canonical scope: implemented endpoint fan-out, required vs optional sources,
  missing-source policy, source hashes, provenance, and warnings.
- Source-of-truth areas: `internal/adapters/weatherapi/*`,
  `internal/forecast/bundle.go`, weather adapter tests and testdata.
- Acceptance criteria: documents hourly as required; optional/stub sources
  match code; links to Weather API integration doc for external contract.

### `docs/integrations/scriptorium.md`

- Audience: developers and LLM coding agents.
- Purpose: external Scriptorium CLI contract used by `weatherreporter`.
- Canonical scope: `scriptorium render`, `scriptorium run`,
  `--input data_package=<path>`, optional config/profile/extra args,
  stdout/stderr, output path, and exit behavior.
- Source-of-truth areas: `internal/adapters/scriptorium/runner.go`,
  `internal/adapters/scriptorium/runner_test.go`, `internal/config/*`.
- Acceptance criteria: only implemented invocation shapes are documented; no
  unused Scriptorium features appear as project behavior.

### `docs/integrations/weatherapi.md`

- Audience: developers and LLM coding agents.
- Purpose: external Weather API contract used by `weatherreporter`.
- Canonical scope: base URL handling, response envelope, query parameters,
  implemented endpoints, source identity, timestamps, missing data, and
  compatibility assumptions.
- Source-of-truth areas: `internal/adapters/weatherapi/client.go`,
  `internal/adapters/weatherapi/client_test.go`, adapter testdata.
- Acceptance criteria: documents `/observations`, `/conditions/current`,
  `/forecast/hourly`, `/forecast/narrative`, `/alerts/active`, and
  `/discussion`; does not present unused day-slice endpoints as current usage.

### `docs/roadmap/documentation.md`

- Audience: maintainers, developers, LLM coding agents.
- Purpose: this migration plan.
- Canonical scope: planned documentation migration only.
- Source-of-truth areas: documentation policy and current repository.
- Acceptance criteria: action-oriented; distinguishes required and recommended
  work; does not rewrite current docs inline; includes validation commands.

### `docs/roadmap/future.md`

- Audience: maintainers, developers, LLM coding agents.
- Purpose: future-only project work extracted from stale roadmap material.
- Canonical scope: deferred features such as automatic storm monitoring, if
  still desired.
- Source-of-truth areas: `docs/roadmap/initial.md` and current code boundaries.
- Acceptance criteria: no completed MVP tasks; no claims of current behavior;
  each item is clearly labeled proposed, accepted, deferred, or rejected.

### `examples/config.yml`

- Audience: administrators, operators, developers.
- Purpose: production-oriented example configuration.
- Canonical scope: implemented config fields only, no secrets.
- Source-of-truth areas: `internal/config/*`, `internal/config/config_test.go`.
- Acceptance criteria: loads successfully; linked from `docs/config.md`; no
  private endpoint or credential values.

### `examples/minimal-config.yml`

- Audience: administrators, operators, developers.
- Purpose: smallest useful config for implemented generation behavior.
- Canonical scope: only required or commonly changed fields.
- Source-of-truth areas: `internal/config/*`, config tests.
- Acceptance criteria: add only with validation coverage; linked from
  `docs/config.md`; no unimplemented fields.

## File-by-File Rewrite Guidance

- `README.md`: keep it short. Cover what the application does, one shortest
  useful command, and links to canonical docs. Avoid manual-level flag tables,
  state layout details, implementation stages, or stale roadmap links.
- `docs/cli.md`: inspect `internal/cli/root.go` and CLI tests before editing.
  Cover real commands and flags only. Link to config for config fields and to
  operations for artifact/state behavior.
- `docs/config.md`: inspect `internal/config` and `examples/config.yml`.
  Document precedence and defaults in one place. Avoid repeating operations or
  CLI workflow material.
- `docs/operations.md`: inspect `internal/app`, `internal/state`, and
  `internal/report`. Cover normal operation, artifacts, metadata, inspect
  commands, batch behavior, and recovery. Avoid detailed troubleshooting
  entries that belong in `docs/troubleshooting.md`.
- `docs/troubleshooting.md`: create symptom-driven entries only for implemented
  failure modes. Likely entries include missing `weather_api.base_url`, invalid
  timezone, invalid storm bounds, Weather API missing hourly data, optional
  source warnings, `scriptorium` not found, render/run nonzero exit, missing
  workspace artifacts, and unknown RunID.
- `docs/policy/development.md`: rewrite as contributor workflow. Do not carry
  forward "proposed layout", "MVP should", "future backend", or automatic storm
  monitoring guidance except as roadmap links.
- `docs/policy/architecture.md`: edit only if a current invariant is wrong.
  Keep it principle-level and avoid duplicating internal component docs.
- `docs/internal/*`: standardize each implemented component doc to the policy
  field list. Avoid documenting unimplemented resume, cleanup, archive, remote
  storage, daemon, or automatic storm-monitoring behavior.
- `docs/integrations/weatherapi.md`: narrow the endpoint section to actual
  adapter calls. Document source hash behavior as SHA-256 over canonical,
  minified raw `data` JSON. Do not carry forward unused endpoint examples as
  current project behavior.
- `docs/integrations/scriptorium.md`: keep `--input data_package=<path>` as the
  documented input contract. Do not reintroduce `--vars-file` or `promptvars`.
- `docs/roadmap/initial.md`: do not update it as current docs. Extract
  still-future work into `docs/roadmap/future.md`, then delete or replace the
  stale file.
- `examples/config.yml`: keep as production-oriented config. Validate it with
  config-loading tests or an equivalent non-secret check.
- `examples/minimal-config.yml`: add only if the implementation agent also adds
  a validation check and can point `docs/config.md` at it.

## Examples Plan

`examples/` currently exists and contains `examples/config.yml`.

Recommended examples:

- `examples/config.yml`
  - Purpose: production-oriented config covering implemented fields.
  - Expected validity check: load through `internal/config` in tests or an
    equivalent config validation command.
  - Documentation links: `docs/config.md`; optional link from README only if the
    README remains concise.
- `examples/minimal-config.yml`
  - Purpose: smallest useful config for generation against a configured Weather
    API and Scriptorium installation.
  - Expected validity check: add test coverage that loads the file and confirms
    defaults fill omitted fields.
  - Documentation links: `docs/config.md`.

Do not add generated report examples in this migration. They depend on live
Weather API and Scriptorium behavior and would become stale unless fixture-based
generation is implemented.

Do not add examples for automatic storm monitoring, daemon operation, cleanup,
archive, remote storage, or resume behavior because those are not implemented.

## Internal Documentation Plan

- App orchestration
  - Path: `docs/internal/app-orchestration.md`
  - Purpose: explain implemented generation, batch, inspection, preflight, run,
    and persistence ordering.
  - Inputs and outputs: app requests, config, report definitions, forecast
    bundle, briefing, data package, metadata, preflight result, rendered report,
    batch summary.
  - Boundaries: coordinates packages but does not own forecast derivation,
    config parsing, adapter internals, or report definitions.
  - Config fields used: Weather API, Scriptorium, workspace, report output,
    dayparts, recent-change thresholds.
  - Adapters used: Weather API and Scriptorium.
  - Failure behavior: render failures persist preflight and metadata when
    available; run failures leave inspectable artifacts; batches continue
    independent reports and return aggregate failure through CLI.
  - Tests to inspect: `internal/app/app_test.go`, CLI batch tests, state tests.
  - Architectural invariants: render preflight precedes run; domain logic stays
    outside adapters; metadata links artifacts.

- Weather data
  - Path: `docs/internal/weather-data.md`
  - Purpose: document Weather API fan-out into `forecast.Bundle`.
  - Inputs and outputs: config, HTTP responses, source records, warnings,
    bundle.
  - Boundaries: adapter handles transport and normalization boundary, not
    forecast selection policy.
  - Config fields used: base URL, timeout, precision, units, timezone, format,
    missing-source policy.
  - Adapters used: Weather API HTTP client.
  - Failure behavior: hourly is required; optional and stub sources follow
    missing-source policy.
  - Tests to inspect: `internal/adapters/weatherapi/client_test.go` and
    adapter testdata.
  - Architectural invariants: source provenance and warning records are
    first-class.

- Forecast derivation
  - Path: `docs/internal/forecast-derivation.md`
  - Purpose: document deriving daily and period summaries from bundle data.
  - Inputs and outputs: bundle, dayparts, valid period, summary structures,
    warnings.
  - Boundaries: no HTTP, state, or Scriptorium calls.
  - Config fields used: dayparts and relevant threshold settings.
  - Adapters used: none directly.
  - Failure behavior: missing required hourly data fails report preparation.
  - Tests to inspect: `internal/forecast/derive_test.go`.
  - Architectural invariants: Go owns period selection and meteorological
    summarization.

- Report registry
  - Path: `docs/internal/report-registry.md`
  - Purpose: document report IDs, prompt IDs, valid periods, output naming,
    batches, and comparison strategies.
  - Inputs and outputs: report kind, clock, timezone, manual bounds, resolved
    report definition.
  - Boundaries: does not build briefings or execute workflows.
  - Config fields used: timezone and report output settings.
  - Adapters used: none.
  - Failure behavior: invalid report kinds, invalid dates, and invalid manual
    storm bounds fail before generation.
  - Tests to inspect: `internal/report/period_test.go`.
  - Architectural invariants: report-specific behavior is registry-driven.

- Briefing
  - Path: `docs/internal/briefing.md`
  - Purpose: document report-specific briefing package builders.
  - Inputs and outputs: resolved report, forecast summaries, source metadata,
    source warnings, briefing package.
  - Boundaries: no prompt rendering and no external calls.
  - Config fields used: dayparts and report period inputs.
  - Adapters used: none directly.
  - Failure behavior: invalid or insufficient forecast summaries fail before
    prompt input construction.
  - Tests to inspect: briefing package tests.
  - Architectural invariants: briefings are curated inputs for prompts.

- Prompt input
  - Path: `docs/internal/prompt-input.md`
  - Purpose: document data package construction for Scriptorium.
  - Inputs and outputs: metadata, briefing, recent changes, warnings,
    `data_package` JSON.
  - Boundaries: no subprocess execution.
  - Config fields used: none directly except values already recorded in
    metadata/briefing.
  - Adapters used: none directly.
  - Failure behavior: validation errors fail before render/run.
  - Tests to inspect: `internal/promptinput/package_test.go`.
  - Architectural invariants: Scriptorium receives structured prompt input, not
    raw unbounded source payloads.

- Recent changes
  - Path: `docs/internal/changes.md`
  - Purpose: document structured comparison of current and prior briefings.
  - Inputs and outputs: current briefing, prior comparable briefing, thresholds,
    change items.
  - Boundaries: no Markdown comparison and no external calls.
  - Config fields used: `recent_change` thresholds.
  - Adapters used: none.
  - Failure behavior: no prior comparable snapshot produces an empty change set.
  - Tests to inspect: `internal/changes/*_test.go`.
  - Architectural invariants: comparisons are structured and report-compatible.

- Filesystem state
  - Path: `docs/internal/state.md`
  - Purpose: document workspace paths, metadata, artifact persistence, lookup,
    and inspection support.
  - Inputs and outputs: workspace config, RunID, artifact JSON/Markdown,
    metadata records, lookup results.
  - Boundaries: no forecast logic and no subprocess execution.
  - Config fields used: workspace directories and report output directory.
  - Adapters used: filesystem.
  - Failure behavior: path, write, read, and lookup errors are surfaced with
    context.
  - Tests to inspect: `internal/state/filesystem_test.go`.
  - Architectural invariants: persisted artifacts support inspection and retry
    diagnosis.

- Scriptorium adapter
  - Path: `docs/internal/scriptorium-adapter.md`
  - Purpose: document subprocess isolation and result handling.
  - Inputs and outputs: render/run requests, argv, stdout, stderr, exit code,
    report path.
  - Boundaries: owns subprocess invocation only; does not know report semantics.
  - Config fields used: binary, config path, profile, timeout, extra args.
  - Adapters used: external `scriptorium` CLI.
  - Failure behavior: context timeouts and nonzero exits return captured output.
  - Tests to inspect: `internal/adapters/scriptorium/runner_test.go`.
  - Architectural invariants: no shell interpolation; Scriptorium details do not
    leak into domain packages.

## Integration Documentation Plan

- Weather API
  - Path: `docs/integrations/weatherapi.md`
  - External system or contract: internal weatherfeeder-backed Weather API.
  - Current usage: the adapter fetches observations, current conditions, hourly
    forecast, narrative forecast, active alerts, and discussion; daily forecast
    and weather story are internal stub source slots.
  - Version or compatibility notes: no explicit external version is visible in
    the repository; document compatibility in terms of endpoints, query
    parameters, and response envelope shape used by tests.
  - What should be documented: base URL joining, timeout behavior, query
    parameters (`format`, `units`, `tz`, `precision` where used), `data`
    envelope handling, `data:null`, source hashes, warnings, and required vs
    optional sources.
  - What should not be documented: unused endpoint families, unimplemented
    location selection, upstream implementation internals, or private
    deployment details.

- Scriptorium
  - Path: `docs/integrations/scriptorium.md`
  - External system or contract: `scriptorium` CLI.
  - Current usage: `scriptorium render --prompt <prompt_id> --input
    data_package=<path> --format json` and `scriptorium run --prompt
    <prompt_id> --input data_package=<path> --out <artifact_path>`, with
    configured binary/config/profile/extra args where applicable.
  - Version or compatibility notes: no explicit Scriptorium version is visible
    in the repository; document the argv contract and behavior expected by
    adapter tests.
  - What should be documented: input contract, output path behavior,
    stdout/stderr capture, nonzero exit handling, timeout behavior, and security
    notes about no shell interpolation.
  - What should not be documented: unused Scriptorium modes, prompt authoring
    guidance beyond the input contract, or Scriptorium internals.

## Recommended Implementation Sequence

### Stage 1: Baseline And User Docs

- Goal: align README, CLI, and config docs with implemented behavior.
- Files to create/update/delete/move: update `README.md`, `docs/cli.md`,
  `docs/config.md`.
- Repository areas to inspect: `cmd/weatherreporter/main.go`,
  `internal/cli/root.go`, `internal/cli/root_test.go`, `internal/config/*`,
  `internal/config/config_test.go`, `examples/config.yml`.
- Acceptance criteria: no unimplemented commands or config fields; quickstart
  commands match `weatherreporter --help`; config defaults and precedence match
  code; README remains concise.
- Suggested validation commands: `go run ./cmd/weatherreporter --help`,
  `go test ./internal/cli ./internal/config`, stale-term greps for removed CLI
  or prompt terminology.
- Prompt size: small enough for one implementation prompt.

### Stage 2: Operations And Troubleshooting

- Goal: keep operations focused on normal workflows and recovery; create a
  symptom-driven troubleshooting guide.
- Files to create/update/delete/move: update `docs/operations.md`; create
  `docs/troubleshooting.md`.
- Repository areas to inspect: `internal/app/app.go`, `internal/app/inspect.go`,
  `internal/state/*`, `internal/report/*`, `internal/adapters/weatherapi/*`,
  `internal/adapters/scriptorium/*`.
- Acceptance criteria: recovery and troubleshooting are clearly separated;
  failure entries are actionable; state layout matches code; no resume,
  cleanup, archive, remote storage, or daemon behavior is documented as
  implemented.
- Suggested validation commands: `go test ./internal/app ./internal/state`,
  `go run ./cmd/weatherreporter --help`, link review.
- Prompt size: small enough for one implementation prompt.

### Stage 3: Internal Component Docs

- Goal: bring internal docs into the policy-required shape and add missing app
  orchestration documentation.
- Files to create/update/delete/move: create
  `docs/internal/app-orchestration.md`; update all existing `docs/internal/*.md`.
- Repository areas to inspect: `internal/app`, `internal/forecast`,
  `internal/briefing`, `internal/promptinput`, `internal/changes`,
  `internal/report`, `internal/state`, adapters, and related tests.
- Acceptance criteria: each component doc includes purpose, inputs/outputs,
  boundaries, config fields, adapters, state behavior, skip/resume behavior,
  failure behavior, tests, and invariants; no unimplemented components are
  documented.
- Suggested validation commands: `go test ./internal/...`, grep for stale terms
  in `docs/internal`.
- Prompt size: likely too large for one prompt unless handled mechanically;
  split into app/state/adapters and domain/report/briefing docs if needed.

### Stage 4: Integration Contracts

- Goal: make integration docs concise and limited to actual external contracts
  used by `weatherreporter`.
- Files to create/update/delete/move: rewrite
  `docs/integrations/weatherapi.md`; lightly update
  `docs/integrations/scriptorium.md`.
- Repository areas to inspect: `internal/adapters/weatherapi/*`,
  weather adapter testdata, `internal/adapters/scriptorium/*`,
  `internal/config/*`.
- Acceptance criteria: no unused Weather API endpoint surface is presented as
  current behavior; Scriptorium docs use `--input data_package=<path>`; no
  `--vars-file` or `promptvars` terminology.
- Suggested validation commands: `go test ./internal/adapters/weatherapi
  ./internal/adapters/scriptorium`, stale-term greps.
- Prompt size: small enough for one implementation prompt.

### Stage 5: Policy Docs

- Goal: align policy docs with their canonical roles.
- Files to create/update/delete/move: rewrite
  `docs/policy/development.md`; lightly update
  `docs/policy/architecture.md` only if implementation inspection finds
  inaccuracies; leave `docs/policy/documentation.md` unchanged unless the
  project intentionally changes policy.
- Repository areas to inspect: `go.mod`, package layout, `internal/cli`,
  `internal/config`, adapters, tests, current documentation policy.
- Acceptance criteria: development policy is contributor workflow, not proposed
  architecture; future/planned/MVP language is removed or moved to roadmap;
  architecture policy remains principle-level.
- Suggested validation commands: grep `docs/policy` for feature-specific
  future/planned/MVP wording, `go test ./...`.
- Prompt size: small enough for one implementation prompt.

### Stage 6: Examples And Roadmap Cleanup

- Goal: validate examples and ensure roadmap docs contain only future/planned
  material.
- Files to create/update/delete/move: update `examples/config.yml`; optionally
  create `examples/minimal-config.yml` with validation coverage; extract
  future-only content from `docs/roadmap/initial.md` into
  `docs/roadmap/future.md`; delete or replace `docs/roadmap/initial.md`.
- Repository areas to inspect: `internal/config/*`, config tests,
  `docs/roadmap/initial.md`, current implemented feature set.
- Acceptance criteria: examples load successfully; roadmap files are clearly
  future-only; no completed MVP stage plan is linked as current docs.
- Suggested validation commands: config example loading test, `go test ./...`,
  link review.
- Prompt size: small enough for one implementation prompt if no new example
  test helper is needed; otherwise split examples and roadmap cleanup.

### Stage 7: Final Validation

- Goal: verify the documentation set is coherent and policy-compliant.
- Files to create/update/delete/move: all migrated docs and examples.
- Repository areas to inspect: full repository.
- Acceptance criteria: non-roadmap docs describe only implemented behavior;
  canonical homes are respected; links are valid; examples are maintained;
  stale terminology is absent.
- Suggested validation commands: `go test ./...`,
  `go run ./cmd/weatherreporter --help`, `git diff --check`, stale-term greps,
  manual link review.
- Prompt size: small enough for one implementation prompt.

## Validation Plan

Automated or semi-automated checks:

- Run `go test ./...` after documentation migration, especially if examples or
  config-loading tests change.
- Run `go run ./cmd/weatherreporter --help` and compare documented CLI syntax
  against the output.
- Run `git diff --check` for whitespace and patch hygiene.
- Search for stale terminology outside roadmap docs:
  - `--vars-file`
  - `promptvars`
  - `weather.tomorrow_report`
  - `--location home`
  - `MVP`
  - `future`
  - `planned`
  - `proposed`
- Review matches manually. Some policy-level wording such as documentation
  policy references to future work is legitimate; feature-specific future
  behavior outside `docs/roadmap/` is not.
- Verify README, CLI, config, operations, troubleshooting, internal, and
  integration links manually. No automated link checker is currently present.
- If `examples/minimal-config.yml` is added, add or update a config-loading test
  so the example remains maintained.
- Verify `docs/integrations/weatherapi.md` against
  `internal/adapters/weatherapi/client.go` so unused endpoints are not
  documented as current usage.
- Verify `docs/integrations/scriptorium.md` against
  `internal/adapters/scriptorium/runner.go` so argv examples match current
  subprocess construction.

Manual review items:

- Confirm each non-roadmap document has a clear audience and canonical scope.
- Confirm current-behavior docs avoid changelog or development-history framing.
- Confirm roadmap docs clearly distinguish accepted plans, proposed work,
  deferred ideas, and rejected ideas where applicable.
- Confirm internal docs describe implemented components only.
- Confirm operations and troubleshooting do not imply resume, cleanup, archive,
  remote storage, daemon, or automatic storm monitoring support.

## Open Questions

No questions block a correct documentation roadmap or migration.

Recommendation: during the migration, delete or replace
`docs/roadmap/initial.md` after extracting any still-valid future work into a
future-only roadmap. Do not treat `docs/roadmap/initial.md` as current project
documentation.