weatherreporter/docs/roadmap/implementation.md

# Documentation Refresh Implementation Plan

## Status

Accepted for implementation.

This is a temporary, staged coordination plan for refreshing Weatherreporter's
current documentation. Implement each stage in order. Do not treat this file as
a current-behavior reference.

## Objective

Bring every maintained document and example into agreement with:

- the implemented Go application;
- the canonical ownership rules in `docs/policy/documentation.md`;
- the architectural boundaries in `docs/policy/architecture.md`;
- the testing rules in `docs/policy/testing.md`; and
- the contributor routing in `docs/development.md`.

The completed documentation set must be concise, task-oriented, free of stale
or duplicate contracts, and verifiably consistent with the executable sources
of truth.

## Scope And Constraints

This is a documentation-only refresh.

- Do not add or change product behavior.
- Do not modify Go code, schemas, prompts, or templates to make documentation
  claims true.
- `examples/*.yml` may be corrected when they disagree with implemented
  configuration, because examples are maintained documentation artifacts.
- If code and documentation disagree, document implemented and tested behavior.
- If code appears to violate an architecture or safety policy, do not conceal
  the conflict with prose and do not fix it during this refresh. Record the
  conflict in this plan's implementation notes and report it to the maintainer.
- Do not implement any work from `docs/roadmap/future.md` or
  `docs/roadmap/promptkit.md`.
- Preserve the exact contents of `AGENTS.md`.
- Treat `docs/policy/*.md` and `docs/development.md` as the governing baseline.
  Change them only to repair a link made stale by this refresh; do not reopen
  their substantive decisions.
- Do not create `docs/internal/overview.md`; `docs/development.md` owns the
  current concise package inventory.
- Do not introduce a release guide, public API guide, consumer guide, or ADR
  unless a separate maintainer decision expands this plan.
- Preserve unrelated working-tree changes and do not commit unless explicitly
  instructed.

## Executable Authorities

Use codebase-memory graph tools before text search for code discovery. Index the
repository first if needed, use `search_graph` to locate symbols,
`trace_path` for dependencies and impact, and `get_code_snippet` for exact
source. Use graph-augmented `search_code` or `rg` for literal flags, paths,
errors, schemas, asset names, and configuration values.

The primary authorities for this refresh are:

| Contract | Executable authority |
| --- | --- |
| CLI commands, flags, help, and dispatch | `internal/cli/root.go`, `internal/report/names.go`, and `internal/cli/root_test.go` |
| CLI JSON summaries and stdout/stderr behavior | `internal/cli/output.go`, `internal/cli/result.go`, and their tests |
| Configuration fields, defaults, loading, precedence, secrets, templates, and validation | `internal/config/*.go` and `internal/config/config_test.go` |
| Report IDs, modes, periods, modules, output names, comparison, and Distributor paths | `internal/report/*.go` and `internal/report/period_test.go` |
| Application generation, batch, inspection, persistence, and notification order | `internal/app/*.go`, `internal/app/*_test.go`, and `internal/cli/root_test.go` |
| Weather collection and external Weather API behavior | `internal/collect`, `internal/weatherdata`, `internal/adapters/weatherapi`, fixtures, and focused tests |
| Facts, forecast derivation, modules, and Recent Changes | `internal/facts`, `internal/forecast`, `internal/module`, `internal/briefing`, `internal/changes`, and focused tests |
| Prompt packages and Scriptorium invocation | `internal/promptinput`, `internal/adapters/scriptorium`, and focused tests |
| Generated text, render contexts, templates, and schemas | `internal/generatedtext`, `internal/reporttemplate`, embedded assets, and focused tests |
| Workspace paths, metadata, atomic writes, prior lookup, and inspection | `internal/state`, `internal/fileutil`, and focused tests |
| Distributor bundle, upload, polling, redaction, and notification behavior | `internal/adapters/distributor`, `internal/app/batch_notification.go`, `go.mod`, and focused tests |

Sibling repositories may be used only as secondary integration references.
Weatherreporter's pinned dependency, adapter code, and tests determine the
subset this repository actually uses. Do not copy broad upstream manuals into
this repository.

## Rules For Every Stage

For each stage:

1. Read the task-specific entries in `docs/development.md`.
2. Inspect the listed executable authorities and focused tests.
3. Update only the files assigned to the stage, plus this plan's stage status
   if progress tracking is requested.
4. Keep exact facts in their canonical owner. Replace duplicate detail with a
   short stable summary and a relative link.
5. Describe implemented behavior only outside `docs/roadmap/`.
6. Keep examples synthetic, valid, and secret-free.
7. Use language tags on every fenced block.
8. Run the stage validation before proceeding.
9. Do not reinterpret surprising behavior as intent; tests and executable
   contracts take precedence over old prose.

## Stage 1: Inventory And Mechanical Hygiene

### Files

- `README.md`
- all Markdown files under `docs/`
- `examples/*.yml`

### Work

1. Classify every document under the ownership table in
   `docs/policy/documentation.md`. Do not create a separate permanent inventory
   document.
2. Identify duplicated exact contracts, stale paths, broken links, untagged
   code fences, and current-state claims in the wrong document.
3. Repair mechanical link and path defects that do not require content
   redesign.
4. In `docs/integrations/distributor/pkg-bundle.md`, remove the broken local
   link to `../integrations/source-bundle.md`. Identify the upstream canonical
   file as `docs/integrations/source-bundle.md` in the Distributor repository
   using prose or code formatting, not a nonexistent repository-relative link.
5. In `docs/integrations/distributor/pkg-upload.md`, do the same for the broken
   `../integrations/http-upload.md` link.
6. Confirm that no document references the retired development-policy path.
7. Defer substantive rewrites to the assigned later stage; this stage should
   establish a clean mechanical baseline.

### Acceptance

- Every repository-relative link target exists.
- All fenced blocks have language tags.
- No stale development-policy reference remains.
- No future feature is presented as current behavior outside `docs/roadmap/`.
- `git diff --check` passes.

## Stage 2: CLI, Configuration, And Examples

### Files

- `docs/cli.md`
- `docs/config.md`
- `examples/minimal-config.yml`
- `examples/config.yml`

### CLI Work

1. Regenerate the command inventory from `go run ./cmd/weatherreporter --help`
   and verify it against `internal/cli/root.go` and report command-name tests.
2. Keep this document's order:
   - shortest useful command;
   - command overview and complete usage;
   - stdout, stderr, JSON summary, quiet-mode, and exit behavior;
   - complete flag reference;
   - concise invocation examples; and
   - inspection commands.
3. Keep exact command syntax and output semantics here. Move or replace
   operational workflow explanations with links to `operations.md`.
4. Verify all seven generate commands, both batch commands, and every inspect
   command.
5. Verify command-specific restrictions: required Daily date, optional Today
   date, Storm bounds, Hourly restrictions, generate output copies, batch
   output directories, and inspection quiet-mode rejection.

### Configuration Work

1. Compare every documented field and default with `Config`, `Defaults`,
   loading, secret loading, report overrides, notification templates, and
   validation code.
2. Keep discovery, precedence, fields, defaults, accepted values, validation
   rules, secret-supply behavior, and links to examples here.
3. Keep operational notification sequencing, filesystem lifecycle, and
   recovery in `operations.md`; summarize and link rather than duplicate them.
4. Verify report-module override keys against the report registry and module
   registry.
5. Verify every template placeholder accepted by Distributor notification
   configuration.

### Example Work

1. Ensure both examples contain only implemented fields and synthetic
   endpoints.
2. Keep `minimal-config.yml` genuinely minimal.
3. Keep `config.yml` production-oriented and representative without becoming a
   second field reference.
4. Do not add credentials, private endpoints, or generated reports.

### Validation

```sh
go run ./cmd/weatherreporter --help
go test ./internal/cli ./internal/config ./internal/report ./internal/module
git diff --check
```

The config tests must load the maintained examples successfully.

## Stage 3: README And Operations

### Files

- `README.md`
- `docs/operations.md`

### README Work

Keep the README short and in this order:

1. concise product description;
2. one-sentence value proposition;
3. the shortest successful generation command; and
4. links to CLI, configuration, operations, troubleshooting, development, and
   architecture documentation.

Do not add a complete command list, configuration fields, workspace layout, or
future Promptkit behavior.

### Operations Work

1. Verify generation and batch workflow order against `internal/app`.
2. Verify the physical workspace tree, artifact names, RunID placement,
   metadata links, notification artifact placement, and prior lookup against
   `internal/state`.
3. Verify output-copy behavior and the rule that managed reports are the only
   upload sources.
4. Verify single-report and batch notification sequencing, skip conditions,
   failure accounting, and inspectable artifacts.
5. Verify inspection is read-only and identify exactly which artifacts each
   command reads.
6. Keep normal operation, state lifecycle, inspection, recovery, and
   operational caveats here.
7. Replace complete flag or config-field definitions with links to their
   canonical references.
8. Keep only the minimal commands needed to illustrate an operational
   procedure.

### Validation

```sh
go test ./internal/app ./internal/state ./internal/cli
go run ./cmd/weatherreporter --help
git diff --check
```

## Stage 4: Troubleshooting

### File

- `docs/troubleshooting.md`

### Work

1. Verify every documented symptom and diagnostic fragment against current
   errors and failure tests.
2. Use one consistent entry shape:
   - symptom;
   - likely cause;
   - diagnostic step or command;
   - safe fix; and
   - links to canonical references.
3. Keep symptom-oriented diagnosis here. Remove repeated normal workflows,
   full endpoint inventories, config-field definitions, and artifact schemas.
4. Preserve the distinction between pre-run failures, collection failures,
   Scriptorium preparation/run failures, generated-text validation failures,
   template failures, report failures, batch partial failures, skipped batch
   uploads, Distributor failures, secret loading, and state lookup failures.
5. Use exact error text only when it is a stable operator-facing contract;
   otherwise use the smallest stable identifying fragment.
6. Ensure fixes are safe, narrow, and do not recommend broad workspace
   deletion or expose secret values.

### Validation

```sh
go test ./internal/cli ./internal/config ./internal/app ./internal/state
go test ./internal/adapters/weatherapi ./internal/adapters/scriptorium ./internal/adapters/distributor
git diff --check
```

## Stage 5: Report Template Guide

### File

- `docs/templates.md`

### Work

1. Verify top-level templates, shared partials, schema IDs, prompt sources, and
   registered template functions against `internal/reporttemplate`.
2. Verify every documented render-context field against
   `internal/generatedtext`; remove fields that are absent and add implemented
   fields needed by maintainers.
3. Keep the maintainer-facing editing rules, context contracts, and minimal
   template examples here.
4. Clearly distinguish deterministic module values, collected/derived facts,
   and validated GeneratedText prose.
5. Keep weather derivation and generated-text validation mechanics in their
   internal owners; summarize and link from this guide.
6. Avoid duplicating the full JSON schema bodies or package implementation
   flow.

### Validation

```sh
go test ./internal/reporttemplate ./internal/generatedtext ./internal/app
git diff --check
```

## Stage 6: Weather API Integration

### File

- `docs/integrations/weatherapi.md`

### Work

1. Verify URL joining, query parameters, timeout and retry behavior, response
   envelope, endpoint set, decoding, source identity, warnings, and
   required/optional source behavior against the adapter, collection layer,
   fixtures, and tests.
2. Keep the external Weather API contract and compatibility assumptions here.
3. Move internal normalization and orchestration mechanics to links pointing at
   the relevant internal documents.
4. Document only endpoints and fields Weatherreporter currently consumes.

### Validation

```sh
go test ./internal/adapters/weatherapi ./internal/collect ./internal/weatherdata
git diff --check
```

## Stage 7: Scriptorium Integration

### File

- `docs/integrations/scriptorium.md`

### Work

1. Verify the exact `render` and `run` invocations, argument ordering,
   timeouts, output paths, result decoding, stderr handling, cancellation, and
   failure behavior against the adapter and tests.
2. Keep the external CLI contract here and link to internal prompt-input,
   adapter, generated-text, and orchestration mechanics.
3. Describe Scriptorium as the implemented runtime. Do not mention the proposed
   Promptkit replacement outside `docs/roadmap/promptkit.md`.
4. Do not copy Scriptorium's general manual; document only the commands and
   result fields Weatherreporter uses.

### Validation

```sh
go test ./internal/adapters/scriptorium ./internal/promptinput ./internal/app
git diff --check
```

## Stage 8: Distributor Integration

### Files

- `docs/integrations/distributor/api.md`
- `docs/integrations/distributor/pkg-bundle.md`
- `docs/integrations/distributor/pkg-upload.md`

### Work

1. Rewrite these as concise references to the exact Distributor surface used
   by Weatherreporter:
   - `api.md` owns accepted upload, authentication, idempotency, run status,
     terminal failure, and retention assumptions used by the adapter;
   - `pkg-bundle.md` owns the bundle file mapping and path constraints used by
     Weatherreporter;
   - `pkg-upload.md` owns the client construction, upload, retry, conflict, and
     status operations used by the adapter.
2. Remove generic producer tutorials, broad upstream feature descriptions,
   unrelated examples, and claims Weatherreporter does not rely on.
3. Verify the pinned module version in `go.mod` and the adapter's actual calls.
4. Use the sibling Distributor repository only to confirm the pinned API. Do
   not make Weatherreporter documentation depend on sibling-relative links.
5. Keep internal request construction, redaction, polling decisions, and app
   notification order in internal documents.
6. Ensure all local links resolve and upstream canonical paths are identified
   without pretending those files exist in this repository.

### Validation

```sh
go test ./internal/adapters/distributor ./internal/app ./internal/config
git diff --check
```

## Stage 9: CLI, Collection, And App Internals

### Files

- `docs/internal/cli.md`
- `docs/internal/collect.md`
- `docs/internal/app-orchestration.md`

### Work

Verify purpose, inputs and outputs, ownership boundaries, workflow composition,
failure propagation, focused tests, and invariants. Keep public CLI syntax in
`docs/cli.md`, Weather API wire behavior in its integration document, and
physical state layout in `docs/operations.md` or `docs/internal/state.md`.

The app document may retain explicit workflow ordering because orchestration is
its owned internal contract. It must not duplicate complete config, CLI, or
external protocol references.

### Validation

```sh
go test ./internal/cli ./internal/collect ./internal/app
git diff --check
```

## Stage 10: State, Source, And Adapter Internals

### Files

- `docs/internal/state.md`
- `docs/internal/weather-data.md`
- `docs/internal/scriptorium-adapter.md`
- `docs/internal/distributor-adapter.md`

### Work

1. Verify each document against its package and focused tests.
2. Keep state path derivation, metadata ownership, prior lookup, atomic writes,
   and inspection mechanics in the state document.
3. Keep normalized bundle, source metadata, and warning semantics in the
   weather-data document.
4. Keep argv/result translation in the Scriptorium adapter document and
   dependency/client translation in the Distributor adapter document.
5. Link external contracts and user-facing references rather than repeating
   them.

### Validation

```sh
go test ./internal/state ./internal/weatherdata
go test ./internal/adapters/scriptorium ./internal/adapters/distributor
git diff --check
```

## Stage 11: Deterministic Domain Internals

### Files

- `docs/internal/facts.md`
- `docs/internal/forecast-derivation.md`
- `docs/internal/changes.md`

### Work

Verify fact ownership, derivation inputs, period and daypart behavior,
thresholds, comparison strategies, missing-data behavior, failures, tests, and
invariants. Keep these documents deterministic and independent of CLI,
filesystem, subprocess, and transport mechanics. Link configuration defaults
instead of restating them.

### Validation

```sh
go test ./internal/facts ./internal/forecast ./internal/changes ./internal/timeutil
git diff --check
```

## Stage 12: Reports, Modules, Briefing, And Prompt Input

### Files

- `docs/internal/report-registry.md`
- `docs/internal/module.md`
- `docs/internal/briefing.md`
- `docs/internal/prompt-input.md`

### Work

1. Verify all report definitions, registry fields, valid periods, batch
   membership, comparison policy, output naming, module defaults, and
   Distributor path declarations.
2. Verify registered module IDs, options, rich values, prompt exports,
   composition by report, and missing-source behavior.
3. Verify prompt package schema, ordering, metadata, serialization, validation,
   and the boundary between rich module values and prompt-facing exports.
4. Keep exact CLI command syntax, config defaults, integration protocol, and
   rendered template contracts in their canonical owners.
5. Prefer tables for report-to-module or report-to-mode mappings where they
   materially reduce repeated prose.

### Validation

```sh
go test ./internal/report ./internal/module ./internal/briefing ./internal/promptinput
git diff --check
```

## Stage 13: Generated Text And Template Internals

### Files

- `docs/internal/generatedtext.md`
- `docs/internal/reporttemplate.md`

### Work

Verify catalog registration, schema selection, decoding and validation,
generated-text types, render-context construction, embedded asset lookup,
template parsing, partials, failure behavior, and invariants. Keep the complete
maintainer-facing context-field reference in `docs/templates.md`; internal
documents should explain implementation and link to that contract.

### Validation

```sh
go test ./internal/generatedtext ./internal/reporttemplate ./internal/app
git diff --check
```

## Stage 14: Roadmap Review

### Files

- `docs/roadmap/future.md`
- `docs/roadmap/promptkit.md`

### Work

1. Ensure every roadmap item is explicitly unimplemented, proposed, accepted,
   deferred, or rejected.
2. Remove or rewrite work that has already been implemented.
3. Keep current-state summaries minimal and link to canonical current
   documentation instead of reproducing it.
4. In `future.md`, correct the Distributor enhancement introduction so it
   acknowledges implemented single-report and batch notification without
   maintaining their detailed current contract.
5. Preserve the Promptkit roadmap as future migration policy. Do not implement
   it, resolve its product-design open questions, or describe it as current.
6. Ensure future architecture does not leak into README, user/operator docs,
   integrations, or current internal docs.

### Validation

```sh
rg -n "Promptkit|promptkit" README.md docs \
  --glob "*.md" --glob "!docs/roadmap/**"
git diff --check
```

The Promptkit search must return no current-state documentation matches.

## Stage 15: Cross-Document Consistency And Final Validation

### Semantic Review

Verify these cross-document facts have one exact owner and consistent summaries
elsewhere:

- seven generate report commands;
- four generated-text-template reports and three direct-Markdown reports;
- morning and evening batch membership and future Daily eligibility;
- configuration precedence and defaults;
- module and report IDs;
- managed workspace and notification paths;
- Recent Changes structured comparison;
- Scriptorium preflight and run behavior;
- single-report and batch Distributor behavior;
- output copies versus managed upload sources; and
- inspection's read-only behavior.

Remove duplicate exact tables or narratives from non-owning documents. Preserve
short task-relevant summaries and relative links.

### Link Validation

Check every Markdown link in `README.md` and `docs/`. Repository-relative
targets and changed heading anchors must resolve. No maintained document may
depend on sibling checkout paths.

At minimum, run a repository-relative target check equivalent to:

```sh
find README.md docs -type f -name "*.md" -print0 |
  while IFS= read -r -d "" file; do
    dir=$(dirname "$file")
    rg -o '\]\([^)]+\)' "$file" |
      sed -E 's/^\]\(([^)#]+)(#[^)]+)?\)$/\1/' |
      while IFS= read -r target; do
        case "$target" in
          http:*|https:*|mailto:*) continue
        esac
        test -z "$target" || test -e "$dir/$target" ||
          printf '%s -> %s\n' "$file" "$target"
      done
  done
```

Manually verify anchors on every changed link because the target check does not
validate fragments.

### Final Commands

```sh
go test ./...
go run ./cmd/weatherreporter --help
git diff --check
```

Review `git diff --name-only` and confirm the refresh changed only Markdown and
maintained YAML examples. Confirm no secrets, private endpoints, generated
artifacts, code changes, `go.work`, or local module replacements were added.

## Completion Criteria

The refresh is complete when:

- every document has one clear canonical owner;
- current user and operator documentation matches implemented behavior;
- CLI and configuration references are complete and verified;
- examples load and contain no secrets;
- operation, recovery, template, and integration contracts are accurate;
- internal documents preserve package boundaries without duplicating public
  references;
- roadmaps contain only future or coordination material;
- all repository-relative links and changed anchors resolve;
- all validation commands pass; and
- no unresolved architecture-policy conflict was hidden or implemented as part
  of the documentation work.

After all stages are accepted, remove this temporary implementation plan in a
final documentation-only change. Do not move its task sequencing or completion
history into current-state documentation.