weatherreporter/docs/roadmap/documentation.md

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.