eric/distributor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Clean up documentation consistency

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-31 04:10:14 +00:00
parent 14444c152b
commit 783d094007
7 changed files with 43 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/roadmap/documentation.md
View File

@@ -18,9 +18,9 @@ The current documentation and examples reviewed are:
| `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` | Missing, recommended | Recurring failure modes now exist and should be documented. |
| `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` | Required rewrite | Currently contains only `# Not yet implemented`; this is the largest policy compliance gap. |
| `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. |
@@ -28,10 +28,10 @@ The current documentation and examples reviewed are:
| `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` | Missing, recommended | Needed for orchestration, backend factory, transform registry, dry-run, summaries, and notifier handoff. |
| `docs/internal/config.md` | Missing, recommended | Needed for config loading, defaults, validation, accepted-but-not-executable backends, and example tests. |
| `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/` | Missing, optional/recommended | Markdown rendering uses Goldmark. A concise Markdown integration note is useful because raw HTML behavior and deterministic rendering are externally visible. |
| `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. |
@@ -42,7 +42,7 @@ The current documentation and examples reviewed are:
| `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` | Needs decision in refresh | Currently load-tested but uses SSH/S3 destinations that are not executable. Replace with a local-only fan-out example or move remote fan-out material under roadmap. |
| `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:
@@ -73,20 +73,20 @@ Absent areas from earlier planning that should not be documented as implemented:
## Policy Compliance Assessment
Required current-behavior docs mostly exist for a config-driven, stateful, modular CLI, but three gaps should be closed before remote backend work resumes.
Required current-behavior docs now exist for the config-driven, stateful, modular CLI.
Required fixes:
Completed fixes from this refresh:
- Rewrite `docs/policy/development.md`; it is required by the documentation policy and is currently a placeholder.
- Keep all non-roadmap docs scoped to implemented behavior. In particular, SSH/S3 execution, force overwrite, and external notification adapters must remain described as unavailable unless the corresponding code exists.
- Resolve `examples/fan-out.yml`. It is valid config syntax, but it is not an executable example because SSH/S3 backends are not implemented for execution.
- `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.
Recommended fixes:
Completed recommended fixes from this refresh:
- Add `docs/troubleshooting.md` for recurring local MVP failure modes: invalid config, invalid source manifest, digest mismatch, unmanaged destination content, destination conflicts, unsupported remote execution, output path collisions, and failed writes.
- Add `docs/internal/app.md` and `docs/internal/config.md` so future agents have one current-behavior internal reference for orchestration and config semantics.
- Add a concise `docs/integrations/markdown.md` only if the project wants integration notes for Goldmark/CommonMark rendering behavior. This is recommended because Markdown rendering is externally visible and raw HTML handling is an important contract.
- Add status notes to roadmap files that are now historical or completed so future agents do not treat old MVP planning as current behavior or active instructions.
- `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.