Added initial policy documentation and a docs implementation roadmap

docs/policy/architecture.md

@@ -0,0 +1,196 @@
+# Architecture Policy
+
+## Purpose
+
+This document defines `weatherapi`'s development architecture and invariants for maintainers and LLM coding agents. It describes how the implemented system is built and how future changes should preserve its boundaries.
+
+This is an inward-facing policy document. Consumer-facing HTTP contract details belong in [`docs/api.md`](../api.md), and proposed or unimplemented work belongs under [`docs/roadmap/`](../roadmap/).
+
+## Project Shape
+
+`weatherapi` is a small Go HTTP API that serves weather data previously persisted by `weatherfeeder`. It does not poll upstream weather providers. It reads weatherfeeder-owned Postgres tables, maps rows back into weatherfeeder canonical model types or API-specific read models, and presents those resources through HTTP endpoints.
+
+The implemented runtime flow is:
+
+1. `cmd/weatherapi` resolves the config path from `-config`, then `WEATHERAPI_CONFIG`, then `config.yml`.
+2. Feedapi loads YAML configuration for the HTTP server, database handles, and template directory.
+3. The command opens configured databases and selects the first database as the primary weather data store.
+4. The Postgres repository is constructed against the primary database.
+5. The application service is constructed over the repository read port.
+6. HTTP endpoint definitions are registered with feedapi.
+7. Feedapi handles routing, middleware, format negotiation, template rendering, and graceful shutdown.
+8. Each request binds query parameters, calls an application use case, presents the result, and returns a `data` response envelope.
+
+Core application code lives in `internal/app`. Inbound HTTP adapters live under `internal/adapters/inbound/httpapi`. Outbound Postgres reads live under `internal/adapters/outbound/postgres`. Text response templates live in `templates/`.
+
+## Core Design Principles
+
+- Hexagonal boundaries: HTTP, configuration, database handles, SQL, rendering, and templates are adapters around application read use cases.
+- Read-only API posture: `weatherapi` reads persisted weather data; ingestion and table ownership belong to `weatherfeeder`.
+- Explicit ports: `internal/app.Repository` is the outbound read port, and `internal/adapters/inbound/httpapi.Service` is the inbound service contract used by handlers.
+- Thin composition root: `cmd/weatherapi` wires config, databases, repository, service, endpoints, and feedapi runtime; it should not contain endpoint, SQL, or presentation logic.
+- Adapter-local policy: query validation belongs at the HTTP boundary; SQL row shape and null handling belong in the Postgres adapter; unit and timezone presentation belongs in presenter helpers.
+- Current-behavior docs: outside roadmap files, document only implemented routes, config, storage assumptions, and runtime behavior.
+- Standard-library-first: use the Go standard library where reasonable, with narrow dependencies for framework/runtime integration and database access.
+
+## Architectural Boundaries
+
+Core/application logic:
+
+- `internal/app` defines read use cases, repository ports, and API-specific read models such as current conditions.
+- Application code may depend on canonical `weatherfeeder/model` types because those are the persisted weather domain contract.
+- Application code should not import HTTP, feedapi endpoint/render packages, SQL packages, or template packages.
+
+Inbound HTTP adapter:
+
+- `internal/adapters/inbound/httpapi` owns route definitions, query binding, request validation, day-slice filtering for forecast routes, and endpoint-specific handler wiring.
+- `internal/adapters/inbound/httpapi/presenter` owns response payload shaping, metric/US conversions, rounding, timestamp timezone conversion, and copy semantics.
+- Endpoint handlers should call the `Service` interface and return `response.Envelope{Data: ...}`. They should not execute SQL directly.
+
+Outbound Postgres adapter:
+
+- `internal/adapters/outbound/postgres` owns SQL text, row structs, row scanning, null conversion, UTC normalization, and reconstruction of nested canonical payloads from weatherfeeder tables.
+- Repository methods return `nil, nil` for missing latest rows so HTTP responses can render `data: null`.
+- The adapter assumes the weatherfeeder Postgres schema exists. It does not create or migrate weatherfeeder tables.
+
+Runtime composition:
+
+- `cmd/weatherapi/main.go` owns process wiring: config path selection, config loading, DB registry, primary DB selection, repository/service construction, endpoint registration, signal cancellation, and logging.
+- Feedapi owns the generic HTTP runtime: routing, renderers, middleware, database registry lifecycle, and graceful server shutdown.
+
+## Modules or Stages
+
+The implemented request path has five main stages: route matching, query binding, service call, presentation, and rendering.
+
+Query binding contract:
+
+- Normalize common `format`, `units`, and `precision` query values where supported.
+- Reject unknown query parameters on implemented endpoints.
+- Keep endpoint-specific query rules in endpoint binders.
+- Parse timezone only for route families that support `tz` / `TZ`.
+- Return typed feedapi errors so invalid input becomes a structured `400 Bad Request` response.
+
+Service contract:
+
+- Keep service methods narrow and resource-specific.
+- Delegate simple latest-resource reads directly to the repository.
+- Keep use-case defaults in `internal/app`; current conditions use `ObservationWindowMinutesDefault`.
+- Do not let transport or SQL details leak into service method signatures.
+
+Presenter contract:
+
+- Treat repository-returned models as immutable input.
+- Copy payloads before unit conversion, rounding, or timezone conversion.
+- Preserve nil pointers and optional fields so JSON/XML `omitempty` behavior remains meaningful.
+- Keep metric and US field naming explicit and tested.
+- Keep text templates conditional so absent optional values do not render misleading zero values.
+
+Repository contract:
+
+- Query the latest parent row for each resource, then load child rows in stored order where needed.
+- Map SQL nulls to nil pointers or zero-value omitted fields consistently.
+- Normalize database timestamps to UTC before returning models.
+- Wrap query, scan, iteration, and decode errors with operation context.
+
+## State, Inputs, and Outputs
+
+Inputs are HTTP requests and Postgres rows written by `weatherfeeder`.
+
+Outputs are HTTP responses in JSON, XML, or text format. All public endpoint handlers return a top-level `data` envelope; missing latest data is represented as `data: null`.
+
+`weatherapi` owns no durable weather state. Its runtime state is limited to process memory, loaded configuration, HTTP server state, template registry, renderer registry, and database connection pools. Durable weather data and schema creation are external concerns owned by `weatherfeeder` and Postgres.
+
+The API currently serves latest-resource views: latest observation, current conditions, latest active alerts run, latest hourly forecast, latest narrative forecast, latest forecast discussion, latest weather story run, and latest individual weather story. Forecast `today` and `tomorrow` routes derive filtered copies from the latest run.
+
+## Configuration and CLI Boundaries
+
+The executable supports one CLI flag:
+
+- `-config`: path to the YAML config file.
+
+If `-config` is not provided, the default comes from `WEATHERAPI_CONFIG`; if that environment variable is empty, the default is `config.yml`.
+
+Configuration shape is provided by feedapi and includes:
+
+- `server`: listen address, default format, and HTTP timeouts;
+- `databases`: named database handles;
+- `templates`: template base directory.
+
+`cmd/weatherapi` requires at least one configured database and uses the first database as the primary weather repository. Template loading is handled by feedapi; text output is available when the configured template directory is present and loaded.
+
+Do not duplicate full CLI or config reference material here. If `docs/cli.md` or `docs/config.md` are added or updated, they should be the canonical user/operator references.
+
+## Errors, Logging, and Diagnostics
+
+`cmd/weatherapi` uses the standard library `log` package with timestamps and microseconds.
+
+Startup failures are fatal and include operation context such as config loading, database opening, primary database selection, app construction, or server startup. Database close errors during shutdown are logged.
+
+Feedapi handles transport-level diagnostics:
+
+- bind errors become structured invalid-parameter responses;
+- unsupported formats become structured unsupported-format responses;
+- handler errors are normalized before response rendering;
+- recovery, request ID, and timing middleware are installed by default.
+
+Repository methods should distinguish no data from errors. `sql.ErrNoRows` maps to `nil, nil`; query, scan, iteration, and JSON decode failures should return contextual errors.
+
+The daemon handles `os.Interrupt` and `SIGTERM` through `signal.NotifyContext`. Feedapi starts `http.Server.ListenAndServe` and performs graceful shutdown when the context is canceled.
+
+## Testing Expectations
+
+When changing behavior, inspect or add focused tests in the owning package.
+
+Expected coverage by change type:
+
+- App service: repository delegation, use-case defaults, filtering or aggregation rules, and error propagation.
+- HTTP adapter: route registration, query validation, supported/rejected parameters, format negotiation, error envelopes, null `data`, day-slice behavior, and timezone behavior.
+- Presenter: metric/US conversion, rounding, timezone conversion, optional field omission, nil handling, copy semantics, and text-template-sensitive fields.
+- Postgres adapter: SQL row mapping, nullable handling, UTC normalization, child ordering, missing rows, and nested payload reconstruction.
+- Runtime/config: config path behavior, database selection, template loading, and endpoint registration when those surfaces change.
+
+Use fakes, `httptest`, local renderers/templates, and row-mapping fixtures rather than live services. Full-package tests should remain fast and deterministic.
+
+## Dependency Policy
+
+Prefer the Go standard library for HTTP helpers, time handling, logging, tests, conversions, and small utilities.
+
+Accepted project-level dependencies are narrow and purposeful:
+
+- `feedapi` provides config loading, HTTP runtime, endpoint definitions, renderers, templates, middleware, and database registry behavior.
+- `weatherfeeder` provides canonical weather model and standards types that match the persisted data contract.
+- `github.com/lib/pq` provides the Postgres driver.
+
+Do not add dependencies for small conveniences. Do not let dependency-specific types cross application boundaries unless that dependency is the explicit adapter contract.
+
+## Documentation Expectations
+
+Documentation must follow [`docs/policy/documentation.md`](documentation.md).
+
+Rules for architecture-related docs:
+
+- Current-behavior docs must describe implemented behavior only.
+- Planned work, including outlook endpoints, belongs only under `docs/roadmap/` until implemented.
+- Prefer links to canonical docs over repeated reference material.
+- Update docs in the same change when modifying public routes, query behavior, config behavior, runtime behavior, presenter payloads, or database read assumptions.
+
+## Architectural Invariants
+
+- Keep `cmd/weatherapi` as composition code, not endpoint, SQL, or presentation logic.
+- Keep application read ports in `internal/app` independent of HTTP and SQL packages.
+- Keep HTTP route definitions and query binding in the inbound adapter.
+- Keep unit conversion, rounding, timezone presentation, and payload copy behavior in presenters.
+- Keep SQL text, row structs, and null handling in the Postgres adapter.
+- Preserve `data` envelope responses and `data: null` semantics for missing latest rows.
+- Preserve UTC normalization at the repository boundary and timezone conversion at the presentation boundary.
+- Preserve strict query-parameter rejection unless an endpoint explicitly allows a parameter.
+- Preserve text templates as adapter presentation assets, not business logic.
+- Do not make `weatherapi` responsible for ingesting upstream weather data or creating weatherfeeder tables.
+
+## Non-Goals
+
+- `weatherapi` is not a weather ingester and does not call NWS, Open-Meteo, OpenWeather, or SPC provider APIs.
+- `weatherapi` does not own weatherfeeder's database schema creation or migrations.
+- `weatherapi` does not provide historical browsing except where an implemented endpoint explicitly derives a filtered view from the latest run.
+- `weatherapi` is not a general-purpose API framework; generic HTTP runtime behavior belongs to `feedapi`.
+- Architecture policy is not a public endpoint, CLI, or config reference.

docs/policy/documentation.md

@@ -0,0 +1,444 @@
+# Go Project Documentation Policy
+
+## Purpose
+
+Project documentation must help five audiences:
+
+1. users who need to run the application;
+2. administrators/operators who need to configure and operate it;
+3. developers who need to understand and change it safely;
+4. LLM coding agents that need clear scope, boundaries, and invariants;
+5. developers and LLM coding agents integrating this project from another codebase.
+
+Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
+
+## Core Rules
+
+### 1. Keep docs concise
+
+Each document should cover a defined scope and only the essentials for that scope.
+
+Avoid:
+- long background explanations;
+- repeated reference material;
+- implementation detail in user-facing docs;
+- aspirational language outside roadmap docs;
+- verbose examples where one minimal example is clearer.
+
+### 2. Document only implemented behavior outside roadmap files
+
+Unimplemented, planned, aspirational, experimental, or future work may be described only under:
+
+- `docs/roadmap/`
+
+No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist.
+
+If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary.
+
+### 3. Use canonical homes
+
+Each type of information should have one canonical location.
+
+Canonical homes:
+
+- project purpose and quickstart: `README.md`
+- development principles: `docs/policy/architecture.md`
+- public HTTP API reference: `docs/api.md`
+- configuration reference: `docs/config.md`
+- CLI reference: `docs/cli.md`
+- operations and recovery: `docs/operations.md`
+- troubleshooting: `docs/troubleshooting.md`
+- public API/package consumer guidance: `docs/consumers/`
+- implemented internals: `docs/internal/`
+- external protocol, service, and file-format contracts: `docs/integrations/`
+- future work: `docs/roadmap/`
+- contributor workflow: `docs/policy/development.md`
+- copyable examples: `examples/`
+
+Other files should summarize briefly and link to the canonical source.
+
+### 4. Keep examples real
+
+Examples should be valid, maintained, and free of secrets.
+
+Where practical:
+- example configs should load successfully;
+- example commands should match real CLI syntax;
+- important examples should be covered by tests.
+
+## Documentation Profiles
+
+All projects require:
+
+- `README.md`
+- `docs/policy/architecture.md`
+
+Additional docs depend on the project.
+
+### Small library
+
+Recommended:
+- `docs/policy/development.md`, if contributor conventions are non-obvious
+
+### Simple CLI
+
+Required:
+- `docs/cli.md`
+
+Recommended:
+- `docs/policy/development.md`
+
+### Config-driven CLI
+
+Required:
+- `docs/cli.md`
+- `docs/config.md`
+
+Recommended:
+- `examples/`
+- `docs/policy/development.md`
+
+### Stateful or operator-facing application
+
+Required:
+- `docs/cli.md`, if CLI-based
+- `docs/config.md`, if config-driven
+- `docs/operations.md`
+
+Recommended:
+- `docs/troubleshooting.md`
+- `examples/`
+- `docs/policy/development.md`
+
+### Modular, service-oriented, or orchestration application
+
+Required:
+- `docs/cli.md`, if CLI-based
+- `docs/config.md`, if config-driven
+- `docs/operations.md`
+- `docs/internal/`
+- `docs/policy/development.md`
+
+Recommended:
+- `docs/troubleshooting.md`
+- validated examples under `examples/`
+
+### Public HTTP API service
+
+Required:
+- `docs/api.md`
+- `docs/cli.md`, if CLI-based
+- `docs/config.md`, if config-driven
+- `docs/operations.md`
+- `docs/internal/`
+- `docs/policy/development.md`
+
+Recommended:
+- `docs/troubleshooting.md`
+- `docs/consumers/`, for task-oriented client integration guides
+- `docs/integrations/`, for upstream/downstream service contracts
+- validated examples under `examples/`
+
+### Project with public packages or consumer APIs
+
+Required:
+- `docs/consumers/api.md`
+- one `docs/consumers/pkg-<name>.md` file per public package, if public packages exist
+
+Recommended:
+- copyable consumer examples under `examples/`, if practical
+
+## Required Documents
+
+### README.md
+
+**Audience:** users, administrators, operators
+
+The README is the outward-facing project orientation page.
+
+It should include, in order:
+
+1. concise description;
+2. elevator pitch;
+3. shortest useful command or usage example;
+4. links to targeted docs.
+
+The README should be short. It is not a manual.
+
+The “shortest useful command” means the simplest command that performs the project’s core use case. (It does not mean `app --help`.)
+
+### docs/policy/architecture.md
+
+**Audience:** developers, LLM coding agents
+
+`docs/policy/architecture.md` is required for every project.
+
+It is an inward-facing development policy document. It should describe how the project is intended to be built and changed.
+
+It should include:
+
+- project shape;
+- core design principles;
+- package and boundary philosophy;
+- state/persistence philosophy, if applicable;
+- external integration philosophy, if applicable;
+- error-handling and logging principles;
+- testing expectations;
+- documentation expectations;
+- architectural invariants;
+- explicit non-goals, if useful.
+
+For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
+
+### docs/api.md
+
+**Audience:** external HTTP API consumers, developers, LLM coding agents integrating by HTTP
+
+Required for projects whose primary public interface is HTTP.
+
+`docs/api.md` is the canonical public HTTP API contract. It should be normative for external consumers and should not be duplicated by README, operations docs, consumer guides, or integration docs.
+
+It should include:
+
+1. base URL conventions;
+2. authentication and authorization behavior, if implemented;
+3. response envelope;
+4. supported media types and content negotiation behavior;
+5. shared query parameters;
+6. endpoint reference grouped by route family;
+7. request parameters and validation rules;
+8. response fields, units, nullability, and optionality;
+9. error response shape and status codes;
+10. pagination, caching, rate-limit, idempotency, and retry behavior, if implemented;
+11. compact request and response examples.
+
+It must document only implemented endpoints and behavior. Planned endpoints, proposed fields, future filters, and experimental response shapes belong only under `docs/roadmap/`.
+
+For HTTP API projects, `docs/consumers/` may provide task-oriented client integration guides, but those guides should link to `docs/api.md` for the authoritative endpoint contract.
+
+### docs/policy/development.md
+
+**Audience:** developers, LLM coding agents
+
+Required for projects maintained by humans and LLM coding agents.
+
+It should include:
+
+- repository layout;
+- build/test commands;
+- coding conventions;
+- dependency policy;
+- how to add config fields;
+- how to add CLI flags;
+- how to add modules or adapters, if applicable;
+- how to update examples;
+- documentation update expectations.
+
+### docs/config.md
+
+**Audience:** administrators, operators, advanced users
+
+Required for applications with configuration files.
+
+It should include, in order:
+
+1. config file locations and discovery precedence;
+2. minimal working config;
+3. production-oriented config;
+4. full configuration reference;
+5. secrets handling, if applicable;
+6. links to maintained examples.
+
+The full configuration reference should be canonical.
+
+### docs/cli.md
+
+**Audience:** users, administrators, operators
+
+Required for CLI applications.
+
+It should include, in order:
+
+1. shortest useful command;
+2. command overview;
+3. complete flag reference;
+4. common workflows;
+5. diagnostic or recovery commands, if applicable.
+
+Explain when commands are useful, not just their syntax.
+
+### docs/operations.md
+
+**Audience:** administrators, operators
+
+Required for applications that maintain state, support resume behavior, run multi-step workflows, write durable artifacts, use remote storage, or require recovery procedures.
+
+It should cover:
+
+- normal workflow;
+- filesystem layout;
+- remote storage layout, if applicable;
+- logs and manifests;
+- resume/retry behavior;
+- cleanup behavior;
+- archive/backup behavior;
+- safe recovery procedures;
+- operational caveats.
+
+### docs/troubleshooting.md
+
+**Audience:** administrators, operators
+
+Recommended once recurring failure modes exist.
+
+Each entry should include:
+
+- symptom;
+- likely cause;
+- diagnostic command or inspection step;
+- safe fix;
+- relevant links.
+
+### docs/consumers/
+
+**Audience:** developers and LLM coding agents integrating this project from another codebase
+
+Required for projects with public packages, SDKs, client APIs, plugin APIs, or other application-facing integration surfaces.
+
+This directory describes how an external codebase should consume the project's public API. It should be task-oriented and copyable where useful. It is not the place for internal implementation details or operator procedures.
+
+For projects whose public API is HTTP, `docs/consumers/` is not required, and it should not duplicate the endpoint reference in `docs/api.md`. If present, it may provide practical integration workflows, client-specific examples, or migration notes that link back to `docs/api.md`.
+
+`docs/consumers/api.md` should provide the consumer-facing overview and primary implementation workflow. It should include:
+
+1. intended consumer audience and use cases;
+2. required inputs supplied by operators or deployment configuration;
+3. recommended public package or API workflow;
+4. minimal copyable example;
+5. consumer responsibilities and boundaries;
+6. retry, idempotency, or status behavior, if applicable;
+7. links to package-specific docs and canonical integration contracts.
+
+Package-specific docs should be named `pkg-<name>.md` and should include:
+
+1. import path;
+2. intended use cases;
+3. primary types and functions needed by consumers;
+4. minimal examples;
+5. validation, error, retry, and boundary behavior;
+6. links to canonical file-format or wire-protocol contracts.
+
+### docs/internal/
+
+**Audience:** developers, LLM coding agents
+
+Required for modular, service-oriented, or orchestration projects.
+
+This directory describes implemented internal components. It is not the roadmap.
+
+Use one file per major component where useful.
+
+Each component doc should include:
+
+1. purpose;
+2. inputs and outputs;
+3. boundaries;
+4. config fields used;
+5. external adapters used;
+6. state or manifest behavior, if applicable;
+7. skip/resume behavior, if applicable;
+8. failure behavior;
+9. tests to inspect before changing;
+10. architectural invariants.
+
+### docs/roadmap/
+
+**Audience:** maintainers, developers, LLM coding agents
+
+This is the only place for planned, future, aspirational, experimental, or unimplemented work.
+
+Roadmap docs should clearly distinguish:
+
+- proposed work;
+- accepted plans;
+- deferred ideas;
+- rejected ideas;
+- implementation prompts or task breakdowns, if useful.
+
+Roadmap docs should not be confused with current behavior.
+
+### docs/integrations/
+
+**Audience:** developers, LLM coding agents
+
+Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
+
+This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses or exposes.
+
+For public HTTP API services, `docs/integrations/` should document upstream, downstream, storage, protocol, or runtime contracts that the service depends on or bridges. It should not become a second copy of the public HTTP endpoint reference; that belongs in `docs/api.md`.
+
+Use one file per integration where useful.
+
+## Examples Directory
+
+Projects with non-trivial configuration or workflows should include `examples/`.
+
+Useful examples include:
+
+- minimal working config;
+- production-oriented config;
+- full annotated config;
+- local development config;
+- remote/object-storage config;
+- minimal session/input file.
+
+Examples should be valid, maintained, tested when practical, and linked from relevant docs.
+
+## Security and Privacy
+
+Docs and examples must not include:
+
+- real API keys;
+- tokens;
+- passwords;
+- private keys;
+- private environment dumps;
+- sensitive user data;
+- raw private transcripts;
+- private infrastructure details unless intentionally public.
+
+Document secret-handling mechanisms, not actual secret values.
+
+## Maintenance Rules
+
+When docs change, verify the affected behavior.
+
+Where practical:
+
+- load example config files in tests;
+- test CLI examples or command parser behavior;
+- validate documented flags against real flags;
+- remove stale references;
+- update links after renames;
+- keep roadmap content out of non-roadmap docs.
+
+If documentation and code disagree, fix the documentation and/or open a roadmap item; do not leave aspirational behavior in current-behavior docs.
+
+Documentation is complete only when it matches the current code.
+
+## Documentation Change Checklist
+
+Before merging documentation changes, verify:
+
+- README is concise and orientation-focused.
+- `docs/policy/architecture.md` describes development principles.
+- `docs/api.md` is the canonical HTTP contract for HTTP API services.
+- Future work appears only under `docs/roadmap/`.
+- User-facing docs avoid unnecessary internals.
+- Consumer-facing docs explain public APIs without duplicating HTTP endpoint or integration contracts.
+- Developer-facing docs preserve boundaries and invariants.
+- Config examples match the schema.
+- CLI examples match real commands and flags.
+- Defaults appear in the canonical config reference.
+- No secrets or private data are included.
+- Links are accurate.

docs/roadmap/documentation.md

@@ -0,0 +1,489 @@
+# Documentation Roadmap
+
+## Purpose
+
+This roadmap defines the work required to bring `weatherapi` documentation into compliance with `docs/policy/documentation.md` and the current implementation. It is a planning document only; implementation agents should update the target documentation files in later stages and must continue to document only implemented behavior outside `docs/roadmap/`.
+
+## Repository Documentation Inventory
+
+- `README.md`: keep and rewrite. It currently identifies the project and lists routes, but it does not provide the policy-required shortest useful command, operational prerequisites, or links to canonical docs.
+- `docs/api.md`: keep and rewrite. It is the canonical public HTTP API home, but it needs correction and tightening against route binders, presenters, feedapi rendering, and tests.
+- `docs/policy/documentation.md`: keep and lightly update only if future policy gaps are found. It is the controlling policy and already covers HTTP API services.
+- `docs/policy/architecture.md`: keep and lightly update only when architecture or public integration boundaries change. It accurately describes the current read-only hexagonal structure.
+- `docs/roadmap/outlook.md`: keep. It is roadmap-only material for unimplemented outlook support and must not be promoted into current-behavior docs until implemented.
+- `docs/roadmap/documentation.md`: create. This file is the staged plan for the documentation refresh.
+- `config.yml`: keep as the checked-in local sample runtime config, but do not treat it as the full canonical configuration reference. Link from future config docs and avoid copying local credentials into production examples.
+- `templates/*.txt.tmpl`: keep. These are implemented text rendering assets and should be referenced from API/internal docs where relevant.
+- `examples/`: create new. No maintained examples directory exists, but policy recommends validated examples for this config-driven HTTP service.
+- `docs/config.md`: create new. Required because `weatherapi` is config-driven.
+- `docs/cli.md`: create new. Required because `weatherapi` has an executable CLI surface.
+- `docs/operations.md`: create new. Required because `weatherapi` is an operator-facing HTTP service.
+- `docs/troubleshooting.md`: create new. Recommended for operator-facing services and useful for query/config/database failure modes present in the code.
+- `docs/policy/development.md`: create new. Required for developers and LLM coding agents.
+- `docs/internal/`: create new. Required for the modular HTTP/app/repository/presenter architecture.
+- `docs/integrations/`: create new. Recommended because `weatherapi` depends on feedapi runtime behavior, PostgreSQL, and weatherfeeder-owned table contracts.
+- `docs/consumers/`: do not create in the first migration. `docs/api.md` should be the authoritative HTTP contract; add task-oriented consumer guides later only if concrete integration workflows are needed.
+
+## Policy Compliance Assessment
+
+Required documents currently missing:
+
+- `docs/cli.md` for the `cmd/weatherapi` executable and `-config` flag.
+- `docs/config.md` for feedapi YAML configuration used by `weatherapi`.
+- `docs/operations.md` for deployment, startup, shutdown, database, and template operations.
+- `docs/internal/` for implemented internal component boundaries.
+- `docs/policy/development.md` for contributor and LLM-agent workflow.
+
+Recommended documents currently missing:
+
+- `docs/troubleshooting.md` for common startup, database, query, rendering, and no-data cases.
+- `docs/integrations/` entries for feedapi runtime/config/render behavior and the weatherfeeder/Postgres storage contract.
+- `examples/` with maintained config and request examples.
+
+Existing docs that need correction or relocation:
+
+- `README.md` duplicates endpoint inventory better owned by `docs/api.md` and lacks quickstart guidance.
+- `docs/api.md` should remain in place, but it should be rewritten as a normative HTTP contract with exact implemented behavior.
+- `docs/roadmap/outlook.md` is correctly located; do not link it from user quickstarts as current functionality.
+
+Likely stale or inaccurate current-behavior claims to fix during the API rewrite:
+
+- `docs/api.md` describes discussion section fields as `title` and `narrative`; implemented model/presenter fields are `qualifier`, `issuedAt`, and `text`.
+- `docs/api.md` examples should not imply a discussion product value of `discussion`; current code/tests use the weatherfeeder AFD product value.
+- `docs/api.md` says current conditions are synthesized from latest observation/forecast data; implemented SQL aggregates recent `observations` rows only.
+- `docs/api.md` says `tz` and `TZ` must match exactly; implemented validation allows case-insensitive equality via `strings.EqualFold`.
+- `docs/api.md` says error fields may vary; feedapi exposes a stable error envelope with `error.code` and `error.message` for implemented API errors.
+- Existing docs should clarify that `precision` is accepted only on observations, current conditions, and forecast routes; it is rejected on alerts, discussion, and weather stories.
+- Existing docs should clarify that `tz` / `TZ` is accepted only on forecast, discussion, and weather story routes; it is rejected elsewhere.
+- Existing docs should clarify that JSON is the default format, but format negotiation is `format` query parameter first, then `Accept` header, then configured default.
+
+Examples and links:
+
+- There is no `examples/` directory, so examples are missing rather than stale.
+- Existing docs have few links. Future links should be checked after creating the target docs.
+- Avoid example secrets. The checked-in `config.yml` contains local `weatherdb` credentials and should not be copied as production guidance without placeholders and secrets notes.
+
+## Target Documentation Set
+
+### `README.md`
+
+- Audience: users, administrators, operators.
+- Purpose: concise project orientation and shortest useful startup path.
+- Canonical scope: what `weatherapi` is, core prerequisite that weatherfeeder-populated Postgres tables must exist, shortest useful command, and links to detailed docs.
+- Recommended outline: description, short pitch, prerequisites, shortest useful command, endpoint family summary, documentation links.
+- Source of truth: `cmd/weatherapi/main.go`, `config.yml`, `docs/api.md`, `docs/config.md`, `docs/cli.md`, `docs/operations.md`.
+- Acceptance criteria: short enough to scan, no full endpoint reference, no unimplemented outlook endpoints, links to canonical docs.
+
+### `docs/api.md`
+
+- Audience: external HTTP API consumers and integrating developers/LLM agents.
+- Purpose: normative public HTTP API contract.
+- Canonical scope: routes, query parameters, content negotiation, response envelope, payload fields, nullability, units, precision, timezone behavior, errors, and compact examples.
+- Recommended outline: base URL, authentication behavior, response envelope, media types and negotiation, shared query rules, errors, endpoint families, field definitions, examples.
+- Source of truth: `internal/adapters/inbound/httpapi/*_endpoint.go`, `query_bind.go`, `query_normalize.go`, `query_timezone.go`, `internal/adapters/inbound/httpapi/presenter`, `templates/`, `internal/adapters/inbound/httpapi/endpoints_test.go`, feedapi `render`, `response`, and `errors` packages.
+- Acceptance criteria: documents only implemented routes; discussion/current-conditions/query/error semantics match code and tests; marks optional forecast `conditionCode`; states no auth, pagination, cache headers, or rate limiting are implemented by `weatherapi` if those remain true.
+
+### `docs/cli.md`
+
+- Audience: users, administrators, operators.
+- Purpose: canonical CLI reference for the executable.
+- Canonical scope: `weatherapi` command invocation, `-config`, `WEATHERAPI_CONFIG`, default `config.yml`, signal/shutdown behavior at a high level.
+- Recommended outline: synopsis, flags, environment variables, config precedence, exit/startup failures, examples.
+- Source of truth: `cmd/weatherapi/main.go`, `Dockerfile`, feedapi app startup behavior.
+- Acceptance criteria: does not duplicate config field reference; includes the real flag and env var only; examples are copyable.
+
+### `docs/config.md`
+
+- Audience: administrators, operators, advanced users.
+- Purpose: canonical YAML configuration reference.
+- Canonical scope: config file discovery, minimal config, production-oriented config, full field reference, defaults, validation, template directory, database ordering, secrets handling.
+- Recommended outline: discovery precedence, minimal config, production config, server fields, database fields, template fields, validation/defaults, examples.
+- Source of truth: `cmd/weatherapi/main.go`, `config.yml`, feedapi `config` package, feedapi `db` package, feedapi `app.defaultRenderers`.
+- Acceptance criteria: states first configured database is primary for weather reads; states feedapi defaults for listen/read/write/idle/default format; does not claim strict unknown-field rejection unless implemented; links to examples.
+
+### `docs/operations.md`
+
+- Audience: administrators and operators.
+- Purpose: run, deploy, and recover the service.
+- Canonical scope: runtime prerequisites, Postgres/schema dependency, templates, Docker image behavior, startup/shutdown, logs, no migrations, no ingestion.
+- Recommended outline: runtime model, prerequisites, local run, container run, database dependency, templates and text output, graceful shutdown, health/verification, backup/recovery boundaries.
+- Source of truth: `cmd/weatherapi/main.go`, `Dockerfile`, `.woodpecker/build-image.yml`, feedapi `app`, feedapi middleware, repository packages.
+- Acceptance criteria: clear that weather data and schema are produced by weatherfeeder; does not document provider polling; includes practical checks without inventing health endpoints.
+
+### `docs/troubleshooting.md`
+
+- Audience: users, operators, support engineers.
+- Purpose: diagnose common failures and surprising responses.
+- Canonical scope: startup config failures, DB connection failures, missing tables, missing templates/text format, unsupported format, invalid query params, timezone errors, `data: null`, precision validation.
+- Recommended outline: startup failures, database failures, API request errors, rendering/text issues, no-data responses, timezone and precision issues.
+- Source of truth: `cmd/weatherapi/main.go`, feedapi `errors`, feedapi `render`, query binders, endpoint tests, repository read methods.
+- Acceptance criteria: action-oriented; avoids repeating full API/config references; links to `docs/api.md`, `docs/config.md`, and `docs/operations.md`.
+
+### `docs/policy/development.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: contributor workflow and safe-change checklist.
+- Canonical scope: repository layout, build/test commands, how to add endpoints, config fields, repository reads, presenters, templates, docs, and examples.
+- Recommended outline: layout, local setup, test commands, endpoint change workflow, adapter boundaries, dependency policy, docs checklist.
+- Source of truth: `docs/policy/architecture.md`, `go.mod`, internal packages, existing endpoint/repository/presenter tests.
+- Acceptance criteria: reinforces architecture invariants; gives concrete package/test paths; no current-behavior user reference duplication.
+
+### `docs/internal/runtime.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: explain implemented runtime composition.
+- Canonical scope: config load, DB registry, primary DB selection, service/repo construction, endpoint registration, feedapi server startup, graceful shutdown.
+- Recommended outline: composition root, feedapi responsibilities, database registry, renderers/templates, shutdown/errors, tests to inspect.
+- Source of truth: `cmd/weatherapi/main.go`, feedapi `app`, feedapi `db`, feedapi `templates`.
+- Acceptance criteria: development-facing only; no deployment manual duplication; captures boundaries around `cmd`.
+
+### `docs/internal/http-adapter.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: explain route definitions, query binding, and handler conventions.
+- Canonical scope: endpoint definition pattern, strict query rejection, supported route families, forecast day-slice filtering, timezone parsing.
+- Recommended outline: route registry, binder types, endpoint families, validation rules, day-slice filtering, tests to inspect.
+- Source of truth: `internal/adapters/inbound/httpapi`, `endpoints_test.go`.
+- Acceptance criteria: enough guidance to add a route safely; does not duplicate full public endpoint field reference.
+
+### `docs/internal/presenters.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: explain payload shaping and presentation responsibilities.
+- Canonical scope: metric/US conversion, rounding, timezone conversion, nil/optional handling, copy semantics, text-template interaction.
+- Recommended outline: presenter responsibilities, unit conversion, precision, timezone, optional fields, text templates, tests to inspect.
+- Source of truth: `internal/adapters/inbound/httpapi/presenter`, `templates/`, `presenter/payload_test.go`.
+- Acceptance criteria: prevents conversion logic from moving into handlers or repository; documents current pointer/omitempty behavior.
+
+### `docs/internal/postgres-repository.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: explain outbound read adapter behavior.
+- Canonical scope: query organization, latest-row selection, child loading, row mapping, null handling, UTC normalization, no-data semantics.
+- Recommended outline: repository contract, route-to-query mapping, row mappers, null/timestamp policy, no migrations, tests to inspect.
+- Source of truth: `internal/adapters/outbound/postgres`, `repository_test.go`, `docs/integrations/weatherfeeder-postgres.md`.
+- Acceptance criteria: distinguishes storage contract from public HTTP contract; no schema creation instructions beyond integration notes.
+
+### `docs/integrations/weatherfeeder-postgres.md`
+
+- Audience: operators, developers, LLM coding agents integrating with stored data.
+- Purpose: document `weatherapi`'s dependency on weatherfeeder-owned Postgres tables.
+- Canonical scope: required table families, read assumptions, latest ordering, nullable field expectations, weatherfeeder version compatibility, no migration ownership.
+- Recommended outline: integration boundary, supported weatherfeeder version, table families read, ordering assumptions, nullability assumptions, operational requirements.
+- Source of truth: `go.mod`, `internal/adapters/outbound/postgres/*_queries.go`, `*_rows.go`, `*_mapper.go`, weatherfeeder model dependency.
+- Acceptance criteria: does not duplicate weatherfeeder's full schema docs; documents only tables/columns read by `weatherapi`.
+
+### `docs/integrations/feedapi.md`
+
+- Audience: developers and LLM coding agents.
+- Purpose: document framework/runtime behavior that shapes `weatherapi` externally.
+- Canonical scope: config loading/defaults, renderer registration, content negotiation, success/error envelopes, middleware, graceful shutdown.
+- Recommended outline: dependency version, config ownership, render negotiation, error mapping, middleware, upgrade checklist.
+- Source of truth: `go.mod`, feedapi `config`, `app`, `render`, `response`, `errors`, `transport/httpx` packages.
+- Acceptance criteria: focuses on the contract `weatherapi` relies on; does not become feedapi's full manual.
+
+### `examples/config.minimal.yml`
+
+- Audience: operators and developers.
+- Purpose: minimal local config that can load successfully when a database is available.
+- Canonical scope: server listen/default format, one Postgres database, templates base dir.
+- Recommended outline: YAML only with comments kept brief.
+- Source of truth: `config.yml`, feedapi config defaults and validation.
+- Acceptance criteria: uses placeholders or safe local values; can be loaded by config tests; contains no real secrets.
+
+### `examples/config.production.yml`
+
+- Audience: operators.
+- Purpose: production-oriented config pattern with explicit timeouts and pool settings.
+- Canonical scope: explicit server timeouts, database pool fields, templates dir, secret placeholders.
+- Recommended outline: YAML only with brief comments for values that must be changed.
+- Source of truth: feedapi config/db packages, `Dockerfile`, `docs/operations.md`.
+- Acceptance criteria: load-valid, no real secrets, linked from `docs/config.md` and `docs/operations.md`.
+
+### `examples/requests.http`
+
+- Audience: API consumers and developers.
+- Purpose: copyable requests for implemented endpoints.
+- Canonical scope: one or two requests per endpoint family using supported query params.
+- Recommended outline: base URL variable and representative GET requests.
+- Source of truth: `docs/api.md`, endpoint tests.
+- Acceptance criteria: includes only implemented endpoints; no outlook routes; linked from README/API docs.
+
+## File-by-File Rewrite Guidance
+
+### `README.md`
+
+Cover what `weatherapi` does: a read-only HTTP API over weatherfeeder-populated Postgres data. Include the shortest useful command, for example `go run ./cmd/weatherapi -config config.yml`, with a note that the configured Postgres database and templates directory must be available. Link to API, CLI, config, operations, and troubleshooting docs.
+
+Avoid full route/field reference, config field tables, Docker internals, or future outlook functionality. Keep any endpoint summary grouped by family and link to `docs/api.md`.
+
+Inspect `cmd/weatherapi/main.go`, `config.yml`, `Dockerfile`, and final target docs before rewriting.
+
+### `docs/api.md`
+
+Rewrite as the normative external HTTP contract. Cover response envelope, `data: null`, media negotiation, accepted `format` values, `units`, `precision`, `tz` / `TZ`, strict unknown-parameter rejection, errors, endpoint families, field definitions, optionality, nullability, and compact examples.
+
+Explicitly avoid config/deployment instructions, SQL table details, implementation history, and roadmap endpoints. Do not describe unimplemented authentication, pagination, cache controls, rate limits, or retries except to state their implemented absence where useful for consumers.
+
+Inspect route definitions, query binders, presenters, templates, endpoint tests, feedapi render negotiation, feedapi success/error envelopes, and feedapi status mapping. Do not carry forward the stale discussion section field names or current-conditions source description.
+
+### `docs/cli.md`
+
+Document `weatherapi` invocation, `-config`, `WEATHERAPI_CONFIG`, default `config.yml`, and signal behavior. Include examples for local binary and `go run` usage.
+
+Avoid full YAML reference and endpoint reference. Link to `docs/config.md` and `docs/api.md`.
+
+Inspect `cmd/weatherapi/main.go` and `Dockerfile`.
+
+### `docs/config.md`
+
+Document feedapi YAML as used by `weatherapi`: file discovery, required database list, first database as primary, server defaults, database fields, templates directory, and secrets guidance. Include minimal and production examples or link to files under `examples/`.
+
+Avoid claiming unknown YAML fields are rejected; feedapi currently uses `yaml.Unmarshal` into structs and validation only checks required/defaulted fields. Avoid documenting unused provider/source/sink fields from weatherfeeder.
+
+Inspect feedapi `config`, feedapi `db`, feedapi `app.defaultRenderers`, `config.yml`, and example files.
+
+### `docs/operations.md`
+
+Document how to run the service locally and in a container, required weatherfeeder schema/data, template availability for text output, logs, graceful shutdown, and verification requests. Make clear that `weatherapi` does not ingest data or manage weatherfeeder migrations.
+
+Avoid full API field reference and full config reference. Link to `docs/api.md`, `docs/config.md`, and integration docs.
+
+Inspect `cmd/weatherapi/main.go`, `Dockerfile`, `.woodpecker/build-image.yml`, feedapi app startup/shutdown, and repository no-data behavior.
+
+### `docs/troubleshooting.md`
+
+Organize by symptoms: startup failure, config decode/validation, database open/query errors, missing weatherfeeder tables, `format=text` problems, `406 unsupported_format`, `400 invalid_parameter`, invalid timezone, precision out of range, and `data: null` responses.
+
+Avoid duplicating every parameter and field. Link to API/config/operations docs for reference details.
+
+Inspect feedapi `errors`, feedapi `render`, query binders, endpoint tests, repository methods, and templates.
+
+### `docs/policy/development.md`
+
+Document repository layout, local build/test commands, dependency policy, endpoint-addition checklist, config-change checklist, presenter/template checklist, and documentation update checklist. Reinforce architecture invariants from `docs/policy/architecture.md`.
+
+Avoid public API reference duplication and aspirational modules. Planned work belongs in `docs/roadmap/`.
+
+Inspect architecture policy, `go.mod`, internal packages, tests, and examples after they are created.
+
+### `docs/internal/runtime.md`
+
+Document the runtime composition path from config to feedapi app startup. Include primary database selection and renderer/template registration.
+
+Avoid operator runbooks and full config field reference. Link to `docs/config.md` and `docs/operations.md`.
+
+Inspect `cmd/weatherapi/main.go` and feedapi `app` package.
+
+### `docs/internal/http-adapter.md`
+
+Document endpoint definition conventions, binders, strict query rejection, timezone parsing, forecast day-slice behavior, and route registration tests.
+
+Avoid full public payload field reference. Link to `docs/api.md` for consumer contract.
+
+Inspect `internal/adapters/inbound/httpapi` and `endpoints_test.go`.
+
+### `docs/internal/presenters.md`
+
+Document unit conversion, precision, timezone conversion, optional field preservation, copy-before-presenting behavior, and template dependencies.
+
+Avoid SQL or route registration details. Link to HTTP adapter and API docs.
+
+Inspect `internal/adapters/inbound/httpapi/presenter`, `templates/`, and presenter tests.
+
+### `docs/internal/postgres-repository.md`
+
+Document latest-resource query patterns, child-loading order, mapper responsibilities, SQL null handling, UTC normalization, `nil, nil` no-data behavior, and contextual errors.
+
+Avoid full schema DDL; link to `docs/integrations/weatherfeeder-postgres.md` for storage contract assumptions.
+
+Inspect `internal/adapters/outbound/postgres` and repository tests.
+
+### `docs/integrations/weatherfeeder-postgres.md`
+
+Document the storage contract consumed from weatherfeeder v0.10.0: table families read by each repository method, ordering used to select latest rows, child ordering, nullable fields, timestamp expectations, and the fact that `weatherapi` does not create or migrate these tables.
+
+Avoid duplicating the complete weatherfeeder schema or documenting future tables. Link to weatherfeeder docs if available.
+
+Inspect `go.mod`, all Postgres query/row/mapper files, and weatherfeeder model types.
+
+### `docs/integrations/feedapi.md`
+
+Document how feedapi affects `weatherapi`: config load/default/validate behavior, renderer registration, content negotiation precedence, success and error envelopes, status-code mapping, middleware, DB registry, and graceful shutdown.
+
+Avoid documenting all feedapi internals or APIs not used by `weatherapi`.
+
+Inspect feedapi `config`, `app`, `render`, `response`, `errors`, `transport/httpx`, and `middleware` packages.
+
+## Examples Plan
+
+Create an `examples/` directory because this is a config-driven HTTP API service and policy recommends maintained examples.
+
+Recommended examples:
+
+- `examples/config.minimal.yml`: minimal load-valid local configuration with one Postgres database and `templates` base directory. Validate with a config load test if practical. Link from README and `docs/config.md`.
+- `examples/config.production.yml`: production-oriented config with explicit HTTP timeouts and database pool settings, using placeholders for credentials. Validate with a config load test if practical. Link from `docs/config.md` and `docs/operations.md`.
+- `examples/requests.http`: copyable HTTP requests for implemented route families: observations, current conditions, alerts, hourly forecast, narrative forecast, discussion, and weather stories. Validate manually or with a lightweight grep/check that every path appears in route definitions if practical. Link from README and `docs/api.md`.
+
+Do not add outlook examples until outlook endpoints are implemented. Do not include real database passwords, deployment hostnames, or private URLs.
+
+## Internal Documentation Plan
+
+### Runtime Composition
+
+- Path: `docs/internal/runtime.md`.
+- Purpose: explain how `cmd/weatherapi` composes feedapi, database registry, repository, service, endpoints, renderers, and shutdown.
+- Inputs and outputs: YAML config, OS signals, database handles, HTTP server.
+- Boundaries: runtime wiring only; no endpoint logic or SQL logic.
+- Config fields used: `server`, `databases`, `templates`.
+- Adapters used: feedapi app/db/templates, Postgres repository, HTTP endpoint registry.
+- Failure behavior: config load/validation, missing database, DB open, app construction, server startup, DB close logging.
+- Tests to inspect before changing: add or inspect runtime/config tests if created; existing package tests for endpoint registration and app service delegation.
+- Architectural invariants: keep `cmd` thin; first DB is primary; feedapi owns generic runtime.
+
+### HTTP Adapter
+
+- Path: `docs/internal/http-adapter.md`.
+- Purpose: explain route definitions, handlers, query binders, timezone parsing, and forecast day-slice filtering.
+- Inputs and outputs: HTTP requests, typed request structs, service calls, response envelopes.
+- Boundaries: no SQL and no business aggregation beyond endpoint-specific request shaping/day slicing.
+- Config fields used: none directly; feedapi provides default format/renderers.
+- Adapters used: feedapi endpoint/render/response and presenter package.
+- Failure behavior: feedapi invalid parameter errors for rejected/invalid query parameters.
+- Tests to inspect before changing: `internal/adapters/inbound/httpapi/endpoints_test.go`.
+- Architectural invariants: strict query rejection; transport-specific policy remains at HTTP boundary.
+
+### Presenters and Templates
+
+- Path: `docs/internal/presenters.md`.
+- Purpose: explain response payload transformation, unit conversion, rounding, timezone conversion, and text templates.
+- Inputs and outputs: canonical weatherfeeder models or app read models; JSON/XML/text-ready payloads.
+- Boundaries: no SQL, no service calls, no route registration.
+- Config fields used: templates are loaded from `templates.base_dir` by feedapi.
+- Adapters used: feedapi templates indirectly through endpoint template names.
+- Failure behavior: nil inputs return nil payloads; absent optional fields remain absent; text output depends on loaded templates.
+- Tests to inspect before changing: `internal/adapters/inbound/httpapi/presenter/payload_test.go` and endpoint text tests.
+- Architectural invariants: copy before mutation; preserve optional fields; keep unit/timezone policy out of repository.
+
+### Postgres Repository
+
+- Path: `docs/internal/postgres-repository.md`.
+- Purpose: explain SQL read organization and mapping behavior.
+- Inputs and outputs: Postgres rows; canonical weatherfeeder models and app read models.
+- Boundaries: no HTTP query binding, no unit conversion, no template rendering, no migrations.
+- Config fields used: database connection config is supplied by feedapi/db through `cmd/weatherapi`.
+- Adapters used: `database/sql`, `lib/pq`, weatherfeeder model types.
+- Failure behavior: missing latest rows return `nil, nil`; query/scan/iteration/decode failures return contextual errors.
+- Tests to inspect before changing: `internal/adapters/outbound/postgres/repository_test.go`.
+- Architectural invariants: UTC-normalize timestamps; map nullable SQL to pointers; preserve child ordering.
+
+## Integration Documentation Plan
+
+### Weatherfeeder Postgres Storage Contract
+
+- Path: `docs/integrations/weatherfeeder-postgres.md`.
+- External system or contract: weatherfeeder-owned Postgres schema and weatherfeeder canonical model dependency.
+- Current usage: `weatherapi` reads observations, current-condition observation aggregates, alert runs/alerts/references, forecast runs/periods, forecast discussions/key messages, and weather story runs/stories.
+- Version or compatibility notes: `go.mod` currently depends on `gitea.maximumdirect.net/ejr/weatherfeeder v0.10.0`; table compatibility must match repository SQL.
+- What should be documented: read-only boundary, table families, latest ordering, nullable/optional field assumptions, timestamp normalization, no migrations.
+- What should not be documented: full weatherfeeder setup, source polling, sink write implementation, unimplemented outlook tables.
+
+### Feedapi Runtime Contract
+
+- Path: `docs/integrations/feedapi.md`.
+- External system or contract: feedapi framework/runtime package dependency.
+- Current usage: config load/default/validate, DB registry, endpoint registry, renderers, templates, middleware, HTTP transport, success/error envelopes.
+- Version or compatibility notes: `go.mod` currently depends on `gitea.maximumdirect.net/ejr/feedapi v0.1.0`.
+- What should be documented: behavior that affects `weatherapi` users or maintainers, including format negotiation and error shape.
+- What should not be documented: unused feedapi packages, generic feedapi extension APIs not used by `weatherapi`.
+
+### PostgreSQL Driver and Service
+
+- Path: optional; prefer folding into `docs/integrations/weatherfeeder-postgres.md` unless operations docs become too large.
+- External system or contract: PostgreSQL accessed through `database/sql` and `github.com/lib/pq`.
+- Current usage: configured by feedapi database entries and used by the Postgres repository.
+- Version or compatibility notes: `github.com/lib/pq v1.10.9`; exact PostgreSQL server version is not specified in the repository.
+- What should be documented: connection URI, username/password handling, pool fields, read-only expectations, no schema ownership.
+- What should not be documented: general PostgreSQL administration unrelated to `weatherapi`.
+
+## Recommended Implementation Sequence
+
+### Stage 1: Orientation, CLI, and Config
+
+- Goal: establish user/operator entry points and remove README as the accidental endpoint reference.
+- Files to create/update/delete/move: update `README.md`; create `docs/cli.md`; create `docs/config.md`; create `examples/config.minimal.yml`; create `examples/config.production.yml`.
+- Repository areas to inspect: `cmd/weatherapi/main.go`, `config.yml`, feedapi `config` and `db` packages, `Dockerfile`.
+- Acceptance criteria: README has shortest useful command and links; CLI doc documents only implemented flag/env/default behavior; config doc includes defaults, validation, primary DB ordering, templates, and secrets guidance; example configs load successfully if tests are added.
+- Suggested validation commands: `go test ./...`; add or run config load tests for `examples/*.yml` if practical.
+- Prompt size: small enough for one implementation prompt.
+
+### Stage 2: Public HTTP API Reference
+
+- Goal: rewrite `docs/api.md` as the canonical external contract.
+- Files to create/update/delete/move: update `docs/api.md`; create `examples/requests.http` if not already created in Stage 1.
+- Repository areas to inspect: `internal/adapters/inbound/httpapi`, `internal/adapters/inbound/httpapi/presenter`, `templates/`, feedapi `render`, `response`, `errors`, endpoint tests.
+- Acceptance criteria: all implemented endpoints and only implemented endpoints are documented; query acceptance/rejection matches tests; discussion/current-conditions stale claims are fixed; error envelope/status codes are exact; examples are compact and valid.
+- Suggested validation commands: `go test ./internal/adapters/inbound/httpapi ./internal/adapters/inbound/httpapi/presenter`; `rg "outlook|convective|product.*discussion|title.*narrative|latest observation/forecast|exact fields may vary" README.md docs/api.md` and manually review results.
+- Prompt size: small enough for one implementation prompt, but keep examples concise.
+
+### Stage 3: Operations and Troubleshooting
+
+- Goal: document running and recovering the service without duplicating API/config references.
+- Files to create/update/delete/move: create `docs/operations.md`; create `docs/troubleshooting.md`.
+- Repository areas to inspect: `cmd/weatherapi/main.go`, `Dockerfile`, `.woodpecker/build-image.yml`, feedapi `app`, feedapi `render`, feedapi `errors`, query binders, repository no-data behavior.
+- Acceptance criteria: operators can distinguish config, DB, template, request-validation, unsupported-format, and no-data issues; docs state that ingestion/schema ownership belongs to weatherfeeder; no invented health endpoint.
+- Suggested validation commands: `go test ./...`; manually verify documented startup command and Docker paths against `Dockerfile`.
+- Prompt size: small enough for one implementation prompt.
+
+### Stage 4: Internal Architecture Docs
+
+- Goal: provide enough implementation guidance for developers and LLM coding agents to make safe changes.
+- Files to create/update/delete/move: create `docs/internal/runtime.md`; create `docs/internal/http-adapter.md`; create `docs/internal/presenters.md`; create `docs/internal/postgres-repository.md`.
+- Repository areas to inspect: `docs/policy/architecture.md`, `cmd/weatherapi/main.go`, internal app/httpapi/presenter/postgres packages, tests.
+- Acceptance criteria: docs explain boundaries, inputs/outputs, failure behavior, tests to inspect, and invariants; no public API field reference duplication.
+- Suggested validation commands: `go test ./internal/app ./internal/adapters/inbound/httpapi ./internal/adapters/inbound/httpapi/presenter ./internal/adapters/outbound/postgres`.
+- Prompt size: may be large; split into runtime/http adapter and presenter/postgres docs if needed.
+
+### Stage 5: Integration and Development Policy Docs
+
+- Goal: document external contracts and contributor workflow.
+- Files to create/update/delete/move: create `docs/integrations/weatherfeeder-postgres.md`; create `docs/integrations/feedapi.md`; create `docs/policy/development.md`.
+- Repository areas to inspect: `go.mod`, feedapi packages, weatherfeeder model/schema docs if available, Postgres SQL/row/mapper files, architecture policy.
+- Acceptance criteria: integration docs document only contracts used by `weatherapi`; development policy gives concrete package/test paths and update checklists; no roadmap material outside `docs/roadmap/`.
+- Suggested validation commands: `go test ./...`; `rg "outlook|planned|future|experimental|TODO|deprecated" docs README.md examples` and manually confirm roadmap-only exceptions.
+- Prompt size: small enough for one implementation prompt if kept concise.
+
+### Stage 6: Consistency and Link Pass
+
+- Goal: make the documentation tree coherent after all target docs exist.
+- Files to create/update/delete/move: update cross-links in `README.md`, `docs/*.md`, `docs/internal/*.md`, `docs/integrations/*.md`, and `examples/requests.http` comments if needed.
+- Repository areas to inspect: complete docs tree, route definitions, examples, tests.
+- Acceptance criteria: no broken relative links found by manual or automated checks; no current-behavior docs mention unimplemented outlook endpoints; examples remain valid; each canonical topic has one home.
+- Suggested validation commands: `go test ./...`; `find docs examples -type f -maxdepth 4 | sort`; `rg "docs/|README|examples/" README.md docs examples`; run a markdown/link checker only if one is added to the repository.
+- Prompt size: small enough for one implementation prompt.
+
+## Validation Plan
+
+Automated checks to run during or after documentation implementation:
+
+- `go test ./...` from `weatherapi` after any doc/example changes that add tests or could affect embedded paths.
+- `go test ./internal/app ./internal/adapters/inbound/httpapi ./internal/adapters/inbound/httpapi/presenter ./internal/adapters/outbound/postgres` when API, internal, or integration docs are cross-checked against behavior.
+- Add config example loading tests if examples are created; validate `examples/config.minimal.yml` and `examples/config.production.yml` with feedapi `config.Load` or equivalent test helper.
+- Use `rg` to check stale or forbidden current-doc content: `outlook`, `convective`, `planned`, `future`, `experimental`, `deprecated`, `product.*discussion`, `title.*narrative`, `latest observation/forecast`, and `exact fields may vary`.
+- Use `rg` to verify documented routes against route registration: `/observations`, `/conditions/current`, `/alerts/active`, `/discussion`, `/weatherstories`, `/forecast/hourly`, and `/forecast/narrative`.
+- Manually verify examples contain no real secrets and no unimplemented endpoints.
+
+Documentation tooling status:
+
+- No repository-local markdown linter, link checker, `Makefile`, `justfile`, `Taskfile`, or `package.json` was found during this planning pass.
+- If documentation tooling is added later, update this roadmap or the development policy to make that command part of the validation checklist.
+
+## Open Questions
+
+No open questions block implementation of this documentation roadmap.
+
+Recommendations made by this roadmap:
+
+- Do not create `docs/consumers/` in the first migration because `docs/api.md` is the canonical HTTP consumer contract and no separate task-oriented client workflow exists yet.
+- Keep `docs/roadmap/outlook.md` as roadmap-only material until outlook endpoints are implemented.
+- Prefer concise internal docs over package-by-package manuals; the goal is safe change guidance, not source-code duplication.