# Documentation Roadmap

## Purpose

This roadmap defines a documentation-only refresh plan for `distributor` after the local MVP and cleanup roadmap implementation.

The goal is to make current-behavior documentation concise, accurate, and compliant with `docs/policy/documentation.md` while keeping planned, aspirational, or unimplemented behavior under `docs/roadmap/`.

This file is written for an LLM coding agent that will implement the documentation refresh in stages. It does not itself rewrite current user, policy, internal, or example documentation.

## Repository Documentation Inventory

The current documentation and examples reviewed are:

| Path | Current status | Notes |
| --- | --- | --- |
| `README.md` | Keep and lightly update | Short, accurate orientation page with a runnable local example command. |
| `docs/cli.md` | Keep and update against CLI tests | Covers `version`, `run`, `validate`, and `inspect`; should be checked against command help and parser tests. |
| `docs/config.md` | Keep and tighten | Current config reference documents local execution and also accepted SSH/S3 config fields. It must clearly distinguish config validation from executable backend support. |
| `docs/operations.md` | Keep and expand slightly | Covers local workflow, destination state, retry behavior, cleanup, fan-out failure handling, and caveats. |
| `docs/troubleshooting.md` | Added | Covers recurring local MVP failure modes. |
| `docs/policy/architecture.md` | Keep and clarify where needed | Development policy is broad and includes future adapter direction. Wording should not imply SSH/S3 adapters currently exist. |
| `docs/policy/development.md` | Updated | Contains contributor and agent workflow guidance. |
| `docs/policy/documentation.md` | Keep | Canonical documentation policy. No change required unless the policy itself changes. |
| `docs/internal/bundle.md` | Keep and verify | Describes implemented bundle parsing, discovery, validation, and digest semantics. |
| `docs/internal/notify.md` | Keep and verify | Accurately states current no-op notification behavior. |
| `docs/internal/publish.md` | Keep and verify | Describes planning, execution, replacement, safety, and current local scope. |
| `docs/internal/state.md` | Keep and verify | Describes implemented `.distributor.json` state and comparison behavior. |
| `docs/internal/storage.md` | Keep and verify | Describes storage interface, typed errors, path rules, traversal, and managed deletion. |
| `docs/internal/transform.md` | Keep and verify | Describes Markdown-to-HTML sidecar behavior and transform boundaries. |
| `docs/internal/app.md` | Added | Covers orchestration, backend factory, transform registry, dry-run, summaries, and notifier handoff. |
| `docs/internal/config.md` | Added | Covers config loading, defaults, validation, accepted-but-not-executable backends, and example tests. |
| `docs/internal/local-backend.md` | Missing, optional | Local adapter behavior may remain in `docs/internal/storage.md`; create this only if local filesystem safety detail outgrows that doc. |
| `docs/integrations/markdown.md` | Added | Documents current Goldmark-backed Markdown rendering behavior. |
| `docs/roadmap/audit.md` | Historical roadmap/report | Keep under roadmap unless replaced by a new audit. |
| `docs/roadmap/cleanup.md` | Historical or completed roadmap | Keep under roadmap; optionally add completion status in the documentation refresh. |
| `docs/roadmap/config.md` | Roadmap | Keep as planning material; avoid linking to it as current config reference. |
| `docs/roadmap/contracts.md` | Roadmap | Keep as planning material; current implemented contracts should be summarized in `docs/internal/` and user docs as needed. |
| `docs/roadmap/implementation.md` | Roadmap | Keep as implementation history plus future stages; status should be clear. |
| `docs/roadmap/packages.md` | Roadmap | Keep as planning material; current package docs belong under `docs/internal/`. |
| `docs/roadmap/storage.md` | Roadmap | Keep as planning material; current storage contract belongs in `docs/internal/storage.md`. |
| `examples/local-to-local.yml` | Keep | Minimal local config; load-tested. |
| `examples/local-publish.yml` | Keep | Runnable local publication example used by README and CLI docs. |
| `examples/local-html.yml` | Keep | Runnable local HTML example. |
| `examples/fan-out.yml` | Updated | Local-only runnable fan-out example. |
| `examples/source-bundle/` | Keep | Copyable valid source bundle fixture for local CLI examples. |

Implementation source areas inspected for documentation truth:

- CLI entrypoints: `cmd/distributor`, `internal/cli`.
- Application orchestration: `internal/app`.
- Config loading/defaults/validation: `internal/config`.
- Bundle manifest, discovery, and validation: `internal/bundle`.
- Destination state: `internal/state`.
- Storage abstraction and local/fake backends: `internal/storage`, `internal/storage/fake`, `internal/adapters/local`.
- Publish planning and execution: `internal/publish`.
- Transform registry and Markdown renderer: `internal/transform`, `internal/transform/markdown`.
- Notification hook: `internal/notify`.
- Tests and fixtures: package tests, `internal/testutil`, `examples/`, and `internal/bundle/testdata`.

Absent areas from earlier planning that should not be documented as implemented:

- `internal/adapters/ssh`
- `internal/adapters/s3`
- `internal/stage`
- `internal/modules`
- `internal/validators`
- `internal/artifacts`
- `internal/manifest`
- `internal/schema`
- `internal/report`
- `pkg`

## Policy Compliance Assessment

Required current-behavior docs now exist for the config-driven, stateful, modular CLI.

Completed fixes from this refresh:

- `docs/policy/development.md` contains real workflow guidance.
- Non-roadmap docs are scoped to implemented behavior. SSH/S3 execution, force overwrite, and external notification adapters remain described as unavailable unless the corresponding code exists.
- `examples/fan-out.yml` is local-only and runnable.

Completed recommended fixes from this refresh:

- `docs/troubleshooting.md` covers recurring local MVP failure modes.
- `docs/internal/app.md` and `docs/internal/config.md` provide current-behavior internal references.
- `docs/integrations/markdown.md` documents current Goldmark-backed rendering behavior.
- Historical roadmap status notes were added where useful.

No broad rewrite is needed for `README.md`, `docs/cli.md`, `docs/config.md`, or `docs/operations.md`. They are close to the implemented local MVP and should be tightened against code and tests.

## Target Documentation Set

### `README.md`

- Audience: users, administrators, operators.
- Purpose: short project orientation and fastest useful local command.
- Canonical scope: project purpose, elevator pitch, one local quickstart command, links to current docs.
- Recommended outline: title, one-sentence description, local example command, links.
- Source-of-truth repo areas to inspect: `internal/cli`, `internal/app/run.go`, `examples/local-publish.yml`, `docs/cli.md`.
- Acceptance criteria: command is executable in the current local MVP; README does not describe SSH, S3, force overwrite, notification adapters, or future roadmap behavior as available.

### `docs/cli.md`

- Audience: users, administrators, operators.
- Purpose: canonical CLI reference.
- Canonical scope: commands, flags, useful workflows, command output expectations, local-only limits.
- Recommended outline: shortest useful command, command overview, flag reference, common workflows, diagnostics and recovery commands.
- Source-of-truth repo areas to inspect: `internal/cli/*.go`, `internal/cli/*_test.go`, `internal/app/validate.go`, `internal/app/inspect.go`, `internal/app/run.go`.
- Acceptance criteria: every documented command and flag exists; `validate` and `inspect` are documented as local path commands; `run --dry-run` output is described without over-specifying every line; unsupported remote execution is stated clearly.

### `docs/config.md`

- Audience: administrators, operators, advanced users.
- Purpose: canonical configuration reference.
- Canonical scope: config file path behavior, minimal local config, production-oriented local config, full schema, defaults, validation rules, secrets handling, links to examples.
- Recommended outline: config file location, minimal local config, production-oriented local config, reference, defaults, secrets, examples.
- Source-of-truth repo areas to inspect: `internal/config/config.go`, `internal/config/defaults.go`, `internal/config/load.go`, `internal/config/validate.go`, `internal/config/load_test.go`, `examples/*.yml`.
- Acceptance criteria: fields and defaults match code; `KnownFields(true)` behavior is noted where useful; SSH/S3 fields are described as accepted by config validation but not implemented for execution; `on_digest_mismatch: warn` and unmanaged overwrite are not documented as active options.

### `docs/operations.md`

- Audience: administrators, operators.
- Purpose: operating and recovery notes for the implemented local MVP.
- Canonical scope: local workflow, filesystem layout, destination state, dry-run, retry behavior, replacement safety, failed write cleanup, caveats.
- Recommended outline: normal workflow, filesystem layout, destination state, dry-run and planning, retry and replacement behavior, failure handling, cleanup behavior, caveats.
- Source-of-truth repo areas to inspect: `internal/app/run.go`, `internal/publish/plan.go`, `internal/publish/execute.go`, `internal/publish/reconcile.go`, `internal/publish/safety.go`, `internal/state`, `internal/adapters/local`.
- Acceptance criteria: describes only local-to-local operation; explains `.distributor.json` as the managed sentinel; distinguishes skip, replace, conflict, and unmanaged destination behavior; does not promise resume, remote storage, force overwrite, or external notifications.

### `docs/troubleshooting.md`

- Audience: administrators, operators.
- Purpose: symptom-oriented fixes for common local MVP failures.
- Canonical scope: implemented failure modes only.
- Recommended outline: one entry per symptom with symptom, likely cause, diagnostic step, safe fix, and relevant link.
- Source-of-truth repo areas to inspect: `internal/config/validate.go`, `internal/bundle/validate.go`, `internal/state/compare.go`, `internal/publish/plan.go`, `internal/publish/output.go`, CLI tests.
- Acceptance criteria: entries are actionable and do not suggest unsafe deletion; remote backend failures are described only as unsupported execution; all fixes link to `docs/cli.md`, `docs/config.md`, or `docs/operations.md` where useful.

### `docs/policy/architecture.md`

- Audience: developers, LLM coding agents.
- Purpose: development principles and architectural invariants.
- Canonical scope: project shape, package boundaries, state/persistence philosophy, external integration philosophy, errors/logging, tests, docs, non-goals.
- Recommended outline: keep the existing outline.
- Source-of-truth repo areas to inspect: full package tree, implemented internal docs, roadmap files for explicitly future work.
- Acceptance criteria: still gives long-term architecture direction, but any unimplemented adapter packages or future capabilities are worded as planned/target architecture rather than implemented behavior.

### `docs/policy/development.md`

- Audience: developers, LLM coding agents.
- Purpose: contributor and agent workflow.
- Canonical scope: repo layout, build/test commands, coding conventions, dependency policy, how to add config fields, CLI flags, backends, transforms, examples, and docs.
- Recommended outline: repository layout, common commands, coding conventions, dependency policy, adding config fields, adding CLI flags, adding storage backends, adding transforms, updating examples, documentation expectations.
- Source-of-truth repo areas to inspect: `go.mod`, `cmd/distributor`, `internal/*`, `examples`, tests, `docs/policy/architecture.md`, `docs/policy/documentation.md`.
- Acceptance criteria: no placeholder content remains; commands are real; workflow guidance protects current boundaries; examples and docs update rules match policy.

### `docs/internal/app.md`

- Audience: developers, LLM coding agents.
- Purpose: implemented orchestration reference.
- Canonical scope: `Run`, `Validate`, `Inspect`, backend factory, transform registry, dry-run, per-destination fan-out, failure aggregation, notifier invocation.
- Recommended outline: purpose, inputs and outputs, run flow, backend and transform registration, dry-run behavior, failure behavior, notification behavior, tests to inspect, invariants.
- Source-of-truth repo areas to inspect: `internal/app/*.go`, `internal/app/*_test.go`, `internal/cli/root_test.go`.
- Acceptance criteria: documents current local-only backend execution and the no-op default notifier; does not introduce a generic stage framework that does not exist.

### `docs/internal/config.md`

- Audience: developers, LLM coding agents.
- Purpose: internal config loading/default/validation reference.
- Canonical scope: YAML decoding, known-field rejection, defaults, validation error model, backend config shape, publish/transform validation helper, example load tests.
- Recommended outline: purpose, inputs and outputs, loading flow, defaults, validation responsibilities, executable support boundary, tests to inspect, invariants.
- Source-of-truth repo areas to inspect: `internal/config/*.go`, `internal/config/*_test.go`, `docs/config.md`, `examples/*.yml`.
- Acceptance criteria: documents that SSH/S3 config validation exists while execution does not; keeps user-facing config reference canonical in `docs/config.md`.

### `docs/internal/bundle.md`

- Audience: developers, LLM coding agents.
- Purpose: implemented bundle contract and validation reference.
- Canonical scope: `manifest.json`, discovery, validation, digest semantics, storage interactions, tests.
- Recommended outline: keep current outline and verify against code.
- Source-of-truth repo areas to inspect: `internal/bundle`, `internal/storage`, `internal/bundle/testdata`, `examples/source-bundle`.
- Acceptance criteria: canonical digest, duplicate paths, reserved paths, symlink rejection, RFC3339 parsing, and discovery behavior match implementation.

### `docs/internal/state.md`

- Audience: developers, LLM coding agents.
- Purpose: destination state and comparison reference.
- Canonical scope: `.distributor.json` schema, validation, output metadata, comparison outcomes.
- Recommended outline: keep current outline and verify against code.
- Source-of-truth repo areas to inspect: `internal/state`, `internal/publish/reconcile.go`, `internal/publish/execute.go`.
- Acceptance criteria: state schema and comparison outcomes match implemented structs and tests; `distributor_version` is described as optional diagnostic metadata.

### `docs/internal/storage.md`

- Audience: developers, LLM coding agents.
- Purpose: storage interface and backend safety reference.
- Canonical scope: logical paths, IO methods, traversal, `HasAny`, typed errors, managed deletion, local and fake backend behavior.
- Recommended outline: keep current outline and add any missing implemented details that matter for callers.
- Source-of-truth repo areas to inspect: `internal/storage`, `internal/storage/fake`, `internal/adapters/local`.
- Acceptance criteria: matches actual `Backend` interface, `WriteOptions`, `DeleteOptions`, `ErrStopWalk`, and `storage.List` helper; does not describe raw recursive delete as available.

### `docs/internal/publish.md`

- Audience: developers, LLM coding agents.
- Purpose: publish planning and execution reference.
- Canonical scope: request inputs, output planning, destination inspection, transfer policy, actions, replacement safety, cleanup on failed writes.
- Recommended outline: keep current outline and verify against code.
- Source-of-truth repo areas to inspect: `internal/publish`, `internal/app/run.go`, `internal/config/defaults.go`.
- Acceptance criteria: action names match constants; transfer policy values match code; collision detection and managed deletion behavior are covered.

### `docs/internal/transform.md`

- Audience: developers, LLM coding agents.
- Purpose: transform registry and Markdown transform reference.
- Canonical scope: transform interface, registry, Markdown sidecar output, deterministic output metadata, raw HTML behavior.
- Recommended outline: keep current outline; link to integration notes if `docs/integrations/markdown.md` is created.
- Source-of-truth repo areas to inspect: `internal/transform`, `internal/transform/markdown`, markdown tests.
- Acceptance criteria: `.md` to `.html` sidecar naming, skipped non-Markdown files, digest metadata, and source immutability match implementation.

### `docs/internal/notify.md`

- Audience: developers, LLM coding agents.
- Purpose: notification hook reference.
- Canonical scope: interface, no-op notifier, invocation points, non-invocation points.
- Recommended outline: keep current outline and add tests to inspect if useful.
- Source-of-truth repo areas to inspect: `internal/notify`, `internal/app/run.go`, `internal/app/run_test.go`.
- Acceptance criteria: says no external notification adapters or user-facing notification config exist.

### `docs/integrations/markdown.md`

- Audience: developers, LLM coding agents.
- Purpose: concise external integration note for Markdown rendering.
- Canonical scope: Goldmark dependency, renderer defaults used by `markdown.New`, raw HTML behavior as observed in tests, deterministic wrapper template, supported output mode.
- Recommended outline: purpose, dependency, behavior used, behavior intentionally not customized, tests to inspect, update rules.
- Source-of-truth repo areas to inspect: `go.mod`, `internal/transform/markdown`, markdown tests.
- Acceptance criteria: documents only the Markdown renderer behavior actually used; does not claim full CommonMark compatibility beyond Goldmark defaults.

### `docs/roadmap/*.md`

- Audience: maintainers, developers, LLM coding agents.
- Purpose: future work, historical plans, accepted deferred work, and implementation prompts.
- Canonical scope: unimplemented SSH/S3 adapters, force overwrite, notification adapters, future config fields, release readiness, historical cleanup/audit plans.
- Recommended outline: add status notes only where useful; avoid rewriting history unless it causes confusion.
- Source-of-truth repo areas to inspect: current implementation and each roadmap file.
- Acceptance criteria: future work remains under `docs/roadmap/`; completed historical plans are labeled clearly enough that agents do not re-run them blindly.

## File-by-File Rewrite Guidance

`README.md`:

- Cover: purpose, one local quickstart, links.
- Avoid: full config schema, internal package details, remote backend promises.
- Link to: `docs/cli.md`, `docs/config.md`, `docs/operations.md`, `docs/roadmap/`.
- Inspect: `examples/local-publish.yml`, `internal/cli`.
- Stale claims to remove: any implication that remote publication is implemented.

`docs/cli.md`:

- Cover: real command syntax and current local workflows.
- Avoid: roadmap flags such as force overwrite or remote validation.
- Link to: `docs/config.md`, `docs/operations.md`, `docs/troubleshooting.md` if created.
- Inspect: `internal/cli/*_test.go`.
- Stale claims to remove: any command or flag not present in `internal/cli`.

`docs/config.md`:

- Cover: current config schema and defaults.
- Avoid: presenting SSH/S3 as executable backend support.
- Link to: examples and operations.
- Inspect: `internal/config/defaults.go`, `internal/config/validate.go`, `internal/config/load_test.go`.
- Stale claims to remove: `on_digest_mismatch: warn`, unmanaged overwrite, or force replacement as active options.

`docs/operations.md`:

- Cover: local destination state, managed cleanup, retry behavior, fan-out failure aggregation.
- Avoid: remote storage recovery, force cleanup, external notifier delivery.
- Link to: `docs/troubleshooting.md` for symptom-specific fixes.
- Inspect: `internal/app/run.go`, `internal/publish/execute.go`, `internal/state`.
- Stale claims to remove: any resume or recovery mechanism beyond re-running after safe cleanup.

`docs/policy/development.md`:

- Cover: concrete contributor workflow.
- Avoid: placeholder text and invented tools.
- Link to: architecture and documentation policies.
- Inspect: package tree and `go.mod`.
- Stale claims to remove: `# Not yet implemented`.

`docs/internal/*.md`:

- Cover: implemented component contracts, boundaries, failure behavior, tests to inspect.
- Avoid: roadmap package names or future stages as if they exist.
- Link to: current user docs only when relevant.
- Inspect: package code and tests.
- Stale claims to remove: broad future backend behavior outside local/fake abstractions.

`examples/`:

- Cover: valid, maintained, copyable examples.
- Avoid: examples that look runnable but fail because the backend execution is unsupported.
- Link from: README, CLI docs, config docs.
- Inspect: `internal/config/load_test.go` and optional CLI smoke commands.
- Stale claims to remove: executable remote fan-out examples until remote backends exist.

## Examples Plan

Keep these examples:

- `examples/source-bundle/`: valid source bundle used by local CLI examples.
- `examples/local-to-local.yml`: minimal local config. Use in config docs as the minimal schema example.
- `examples/local-publish.yml`: primary runnable quickstart config.
- `examples/local-html.yml`: runnable Markdown-to-HTML example.

Revise `examples/fan-out.yml` in the documentation refresh:

- Preferred option: replace it with a local-only fan-out example using two local destinations, such as one source archive destination and one HTML destination under `workspace/`.
- Alternative option: move the SSH/S3 fan-out material under a roadmap file and remove it from `examples/`.
- Do not keep a non-roadmap example that appears copyable for execution but uses unsupported SSH/S3 execution.

Future example tests should continue loading every YAML file under `examples/`. If `examples/fan-out.yml` becomes local-only, add or update a CLI/app test that exercises local fan-out behavior or rely on existing fan-out tests if they cover equivalent behavior.

## Internal Documentation Plan

Update existing internal docs only after checking package code and tests.

Create these internal docs:

- `docs/internal/app.md`: orchestration, backend factory, transform registry, dry-run behavior, fan-out, failure aggregation, notifier invocation.
- `docs/internal/config.md`: YAML loading, defaults, validation, accepted config fields, unsupported execution boundary, example load tests.

Keep and verify these internal docs:

- `docs/internal/bundle.md`
- `docs/internal/state.md`
- `docs/internal/storage.md`
- `docs/internal/publish.md`
- `docs/internal/transform.md`
- `docs/internal/notify.md`

Defer these internal docs unless the corresponding implementation grows:

- `docs/internal/local-backend.md`: create only if local adapter details become too long for `docs/internal/storage.md`.
- `docs/internal/logging.md`: defer until logging has behavior beyond placeholders.
- `docs/internal/testutil.md`: defer unless test fixture helpers become a stable contributor-facing contract.

Do not create docs for packages or directories that do not exist.

## Integration Documentation Plan

No external service integration docs should be created for SSH, S3, or notification services until those integrations are implemented.

Recommended current integration doc:

- `docs/integrations/markdown.md`

This should document Goldmark usage because Markdown rendering is an implemented external file-format integration with externally visible output. Keep it concise and limited to:

- dependency and version source: `go.mod`;
- renderer construction: `goldmark.New()`;
- sidecar output path behavior owned by `internal/transform/markdown`;
- raw HTML behavior covered by tests;
- wrapper template behavior;
- tests to inspect before changing renderer behavior.

Do not create separate YAML integration docs unless configuration parsing behavior outgrows `docs/config.md` and `docs/internal/config.md`.

## Recommended Implementation Sequence

### Stage 1: Establish Documentation Status and Contributor Policy

- Goal: remove the required policy placeholder and classify active versus historical documentation.
- Files to create/update/delete/move: update `docs/policy/development.md`; optionally add short status notes to `docs/roadmap/audit.md` and `docs/roadmap/cleanup.md`.
- Repo areas to inspect: `go.mod`, `cmd/distributor`, `internal/*`, `examples`, `docs/policy/architecture.md`, `docs/policy/documentation.md`.
- Acceptance criteria: `docs/policy/development.md` contains real workflow guidance; no active policy doc says "Not yet implemented"; roadmap status notes do not change current behavior docs.
- Suggested validation commands: `rg -n "Not yet implemented" docs/policy README.md docs/*.md docs/internal`; `git diff -- docs/policy/development.md docs/roadmap/audit.md docs/roadmap/cleanup.md`.
- One prompt: yes.

### Stage 2: Tighten Current User and Operator Docs

- Goal: make README, CLI, config, and operations docs exactly match the local MVP.
- Files to create/update/delete/move: update `README.md`, `docs/cli.md`, `docs/config.md`, `docs/operations.md`; create `docs/troubleshooting.md`.
- Repo areas to inspect: `internal/cli`, `internal/app`, `internal/config`, `internal/publish`, `internal/state`, `examples`.
- Acceptance criteria: user docs describe local execution, local validation/inspection, current config schema, current defaults, current state/retry behavior, and clear unsupported remote execution boundaries.
- Suggested validation commands: `rg -n "force|allow_unmanaged|on_digest_mismatch: warn|warn" README.md docs/cli.md docs/config.md docs/operations.md docs/troubleshooting.md`; `rg -n "ssh|s3|remote|notification" README.md docs/cli.md docs/config.md docs/operations.md docs/troubleshooting.md`.
- One prompt: yes.

### Stage 3: Make Examples Fully Runnable or Clearly Roadmap-Only

- Goal: ensure `examples/` contains implemented, copyable examples only.
- Files to create/update/delete/move: update or replace `examples/fan-out.yml`; update links in `README.md`, `docs/cli.md`, and `docs/config.md` if needed; move remote fan-out material to a roadmap section if preserving it is useful.
- Repo areas to inspect: `internal/config/load_test.go`, `internal/app/run_test.go`, `examples`.
- Acceptance criteria: every example under `examples/` is valid current config and does not rely on unsupported remote execution; primary examples remain load-tested.
- Suggested validation commands: `go test ./internal/config`; optional `go run ./cmd/distributor run --config examples/local-publish.yml --dry-run`; optional `go run ./cmd/distributor run --config examples/local-html.yml --dry-run`.
- One prompt: yes.

### Stage 4: Complete Internal Component Docs

- Goal: give future agents a current-behavior internal map before remote backends are added.
- Files to create/update/delete/move: create `docs/internal/app.md` and `docs/internal/config.md`; update existing `docs/internal/*.md` as needed.
- Repo areas to inspect: `internal/app`, `internal/config`, `internal/bundle`, `internal/state`, `internal/storage`, `internal/storage/fake`, `internal/adapters/local`, `internal/publish`, `internal/transform`, `internal/notify`, package tests.
- Acceptance criteria: every major implemented component has a concise doc with purpose, inputs/outputs, boundaries, failure behavior, tests to inspect, and invariants; no internal doc describes absent SSH/S3 adapters as implemented.
- Suggested validation commands: `rg -n "internal/adapters/ssh|internal/adapters/s3|not implemented|future" docs/internal`; `git diff -- docs/internal`.
- One prompt: yes.

### Stage 5: Add Markdown Integration Notes

- Goal: document the one implemented external file-format integration where behavior matters.
- Files to create/update/delete/move: create `docs/integrations/markdown.md`; optionally link from `docs/internal/transform.md`.
- Repo areas to inspect: `go.mod`, `internal/transform/markdown`, markdown tests.
- Acceptance criteria: the doc is concise, version-aware through `go.mod`, and limited to current Goldmark usage and observed renderer behavior.
- Suggested validation commands: `go test ./internal/transform/markdown`; `rg -n "Goldmark|markdown" docs/integrations docs/internal/transform.md`.
- One prompt: yes.

### Stage 6: Final Documentation Consistency Sweep

- Goal: catch stale links, stale roadmap references, and unimplemented claims outside roadmap.
- Files to create/update/delete/move: any docs touched in earlier stages.
- Repo areas to inspect: all docs and examples.
- Acceptance criteria: documentation is current, concise, link-consistent, and policy-compliant.
- Suggested validation commands: `go test ./...`; `rg -n "go-application-template|maximumdirect.net|docs/architecture.md|docs/documentation.md" README.md docs examples`; `rg -n "allow_unmanaged_overwrite|on_digest_mismatch: warn" README.md docs examples`; `rg -n "not implemented|future|planned|roadmap|ssh|s3|remote" README.md docs/*.md docs/internal docs/policy examples`.
- One prompt: yes, after the prior stages are complete.

## Validation Plan

Run Go tests when examples, CLI docs, config docs, or behavior-linked docs change:

- `go test ./internal/config`: validates example config loading and config semantics.
- `go test ./internal/cli ./internal/app`: validates documented command behavior and local run workflows.
- `go test ./internal/transform/markdown`: validates documented Markdown rendering behavior.
- `go test ./...`: final broad verification after documentation and example changes.

Run grep checks:

- `rg -n "Not yet implemented" docs/policy README.md docs/*.md docs/internal`
- `rg -n "go-application-template|docs/architecture.md|docs/documentation.md" README.md docs examples`
- `rg -n "allow_unmanaged_overwrite|on_digest_mismatch: warn" README.md docs examples`
- `rg -n "force overwrite|--force|remote backends are implemented|notification adapters" README.md docs/*.md docs/internal docs/policy examples`
- `rg -n "ssh|s3|remote" README.md docs/*.md docs/internal docs/policy examples`

The final SSH/S3/remote grep is not expected to return zero results. Manually review every result and confirm it is either:

- under `docs/roadmap/`;
- a clearly stated unsupported-execution boundary;
- a config-validation reference that does not imply executable support; or
- an architecture policy statement phrased as future/target direction rather than implemented behavior.

Manual review checklist:

- README remains short.
- `docs/config.md` is the only current-behavior config reference.
- `docs/cli.md` is the only current-behavior CLI reference.
- `docs/operations.md` covers state and recovery without unsafe deletion advice.
- `docs/troubleshooting.md` is symptom-oriented and links to canonical docs.
- Internal docs point to tests before changing behavior.
- Examples are copyable and free of secrets.
- Future work remains under `docs/roadmap/`.

## Open Questions

No blocking questions remain before implementing this documentation refresh.

The only non-blocking choice is how to handle `examples/fan-out.yml`:

- Preferred: convert it to a local-only fan-out example so `examples/` remains fully runnable.
- Acceptable: move the current SSH/S3 fan-out example into roadmap material until remote execution exists.

Use the preferred option unless a maintainer explicitly wants `examples/` to include config-validated but non-executable examples.