distributor/docs/roadmap/documentation.md

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.