distributor/docs/roadmap/documentation.md

# Documentation Roadmap

## Purpose

This roadmap tracks the remaining work required to verify that project documentation complies with `docs/policy/documentation.md` and accurately reflects the current implementation.

The documentation migration has rewritten the current user, operator, integration, and internal component docs. This file now records only remaining validation work. Current behavior belongs outside `docs/roadmap/`; deferred or unimplemented work belongs under `docs/roadmap/`.

## Current Documentation Set

Current documentation outside roadmap:

- `README.md`: concise project orientation and quickstart.
- `docs/cli.md`: canonical CLI command, flag, workflow, and output reference.
- `docs/config.md`: canonical YAML configuration reference.
- `docs/operations.md`: operating, safety, state, upload, and recovery guidance.
- `docs/troubleshooting.md`: symptom-oriented diagnostic and safe-fix guide.
- `docs/policy/architecture.md`: architecture and invariant policy.
- `docs/policy/development.md`: contributor and coding workflow policy.
- `docs/policy/documentation.md`: controlling documentation policy.
- `docs/integrations/*.md`: implemented external/file-format/protocol contracts.
- `docs/internal/*.md`: implemented internal component contracts.
- `examples/*.yml` and `examples/source-bundle/*`: maintained example configs and source bundle fixture.

Current roadmap files:

- `docs/roadmap/documentation.md`: this remaining documentation validation plan.
- `docs/roadmap/http.md`: deferred HTTP upload extensions only.

Removed completed roadmap artifacts:

- `docs/roadmap/audit.md`
- `docs/roadmap/cleanup.md`
- `docs/roadmap/implementation.md`

## Remaining Documentation Validation

Goal: verify the rewritten docs against tests, examples, code, links, and the documentation policy checklist.

Files to create, update, delete, or move: fixes only if validation finds gaps.

Repository areas to inspect:

- `README.md`
- `docs/cli.md`
- `docs/config.md`
- `docs/operations.md`
- `docs/troubleshooting.md`
- `docs/internal/`
- `docs/integrations/`
- `docs/policy/`
- `examples/`
- CLI parser code under `internal/cli`
- config loading/defaulting/validation under `internal/config`
- app/report/upload behavior under `internal/app`
- source bundle, state, publish, storage, adapter, and transform packages

Acceptance criteria:

- Tests pass for the full repository.
- Maintained example configs load.
- CLI examples and flags match parser behavior.
- Config fields and defaults match `internal/config`.
- Operations and troubleshooting docs describe implemented behavior only.
- Internal docs preserve package boundaries and policy-required sections.
- Integration docs describe only implemented contracts.
- Roadmap files contain only remaining or deferred work.
- Links resolve.
- No secrets or private data are present.

Suggested validation commands:

```sh
go test ./...
go test ./internal/config ./internal/cli ./internal/app
go test ./pkg/bundle ./internal/bundle ./internal/state ./internal/publish ./internal/storage ./internal/storage/fake
go test ./internal/adapters/local ./internal/adapters/ssh ./internal/adapters/s3 ./internal/ingest ./internal/transform/markdown
rg -n -i "future|planned|deferred|experimental|deprecated|not implemented|old behavior" README.md docs --glob '!docs/roadmap/**' --glob '!docs/policy/**'
rg -n "\\b(Stages?|Phases?)\\b" README.md docs --glob '!docs/roadmap/**' --glob '!docs/policy/**'
rg -n -- "--config|--dry-run|--force|--format|--pipeline|--bundle|--id|--file|--created|--overwrite" docs/cli.md internal/cli
rg -n "examples/" README.md docs examples internal/config/load_test.go
```

Manual review items:

- Confirm README remains concise and orientation-focused.
- Confirm `docs/config.md` is the only full config field/default reference.
- Confirm `docs/cli.md` is the only full command/flag reference.
- Confirm `docs/operations.md` focuses on operating and recovery.
- Confirm `docs/troubleshooting.md` remains symptom-first.
- Confirm `docs/internal/` describes implemented component contracts and boundaries.
- Confirm integration docs do not claim support for unimplemented external features.
- Confirm examples contain no secrets and distinguish local runnable examples from environment-gated remote examples.

## Open Questions

No open questions block the remaining validation work.