diff --git a/README.md b/README.md index b94b007..723f6e5 100644 --- a/README.md +++ b/README.md @@ -16,5 +16,6 @@ weatherreporter generate daily --date 2026-05-29 --out ./daily.md - [CLI reference](docs/cli.md) - [Configuration reference](docs/config.md) - [Operations guide](docs/operations.md) +- [Troubleshooting](docs/troubleshooting.md) - [Architecture policy](docs/policy/architecture.md) - [Development policy](docs/policy/development.md) diff --git a/docs/roadmap/documentation.md b/docs/roadmap/documentation.md index b58660d..173b482 100644 --- a/docs/roadmap/documentation.md +++ b/docs/roadmap/documentation.md @@ -77,44 +77,36 @@ unimplemented work belongs only under `docs/roadmap/`. ## 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`, +Required documents for a modular, CLI/config-driven, stateful application are +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: +Recommended documentation is also present: -- `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. +- `docs/troubleshooting.md` covers recurring operator-facing failure modes. +- `examples/config.yml` and `examples/minimal-config.yml` are validated by + config tests. +- `docs/internal/app-orchestration.md` documents the workflow coordinator. -Documents that are stale or in the wrong canonical home: +Documents that were stale or in the wrong canonical home have been corrected: -- `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/policy/development.md` is the contributor workflow policy. - `docs/roadmap/future.md` is the current home for deferred project 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. +- `README.md` links to current user/operator/developer docs. +- `docs/integrations/weatherapi.md` is limited to the implemented adapter + contract. 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/`. +- Non-roadmap docs should remain limited to implemented behavior. Some + policy-level wording about future work is legitimate; feature-specific + deferred behavior belongs under `docs/roadmap/`. Examples: -- `examples/config.yml` exists and matches the implemented configuration shape, - but the documentation should state how it is validated. +- `examples/config.yml` and `examples/minimal-config.yml` exist and load + through the config test suite. - 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,