Clean up documentation consistency

docs/policy/architecture.md

@@ -8,7 +8,7 @@ This document defines the development principles for `distributor`. It is inward
 
 Producer applications generate manifested bundles. `distributor` discovers those bundles, validates them, optionally derives publication artifacts such as HTML, and publishes selected source and generated artifacts to one or more configured destinations.
 
-`distributor` does not generate domain reports, interpret domain-specific report content, run producer pipelines, edit reports, or act as a CMS. Weather reports, D&D recaps, calendar summaries, email digests, and future report types should all enter `distributor` through the same bundle contract.
+`distributor` does not generate domain reports, interpret domain-specific report content, run producer pipelines, edit reports, or act as a CMS. Weather reports, D&D recaps, calendar summaries, email digests, and additional report types should all enter `distributor` through the same bundle contract.
 
 ## Project Shape
 
@@ -16,7 +16,7 @@ Default to a small, explicit, dependency-light Go application. Keep the design m
 
 Business logic should live outside CLI, transport, and external-adapter packages. The core application should reason in terms of pipelines, bundles, destination state, transforms, and publish plans—not S3 SDK calls, SFTP sessions, shell commands, or filesystem details.
 
-The core workflow is:
+The current core workflow is:
 
 1. load configured pipelines;
 2. open the source backend;
@@ -28,13 +28,13 @@ The core workflow is:
 8. optionally transform Markdown to HTML for that destination;
 9. publish selected source and generated artifacts;
 10. write `.distributor.json` as the destination sentinel/state file;
-11. run the notification stage, which is a no-op in the MVP.
+11. run the notification hook, which is a no-op in the MVP.
 
 ## Pipeline Model
 
 A pipeline has exactly one source and one or more destinations.
 
-The source is discovered and validated once. Each destination has independent backend configuration, publication policy, transform policy, replacement behavior, state, and future notification behavior.
+The source is discovered and validated once. Each destination has independent backend configuration, publication policy, transform policy, replacement behavior, state, and notification behavior.
 
 The pipeline model is fan-out by design:
 
@@ -45,7 +45,7 @@ source bundle
   -> destination C: source files + HTML
 ```
 
-Destination-specific behavior must not leak back into the source bundle contract. A producer should not need to know whether a bundle will be published to local storage, SSH/SFTP, S3, a static site, email, RSS, or a future notification channel.
+Destination-specific behavior must not leak back into the source bundle contract. A producer should not need to know whether a bundle will be published to local storage, another storage backend, a static site, email, RSS, or another notification channel.
 
 ## Source Bundle Contract
 
@@ -166,13 +166,13 @@ For example, one destination may publish source files only as a long-term archiv
 
 ## Backend Abstraction
 
-Sources and destinations use the same storage abstraction. Local filesystem, SSH/SFTP, and S3-compatible object storage are peer backends. Any backend may appear as a source or a destination unless a specific limitation is documented.
+Sources and destinations use the same storage abstraction. Current runtime execution uses the local filesystem backend. Additional storage backends should be peer implementations behind the same interface, and any backend-specific execution limitation must be documented.
 
-Application logic must interact with storage through internal backend interfaces. Backend-specific behavior belongs in adapter packages. Pipeline, bundle, state, publish, and transform packages must not import S3, SSH/SFTP, or filesystem adapter implementation details.
+Application logic must interact with storage through internal backend interfaces. Backend-specific behavior belongs in adapter packages. Pipeline, bundle, state, publish, and transform packages must not import service-specific or filesystem adapter implementation details.
 
 Adapters should be thin. Backend adapters should implement storage operations and translate backend-specific errors, but should not make bundle comparison, transform, routing, or replacement decisions.
 
-SSH support should prefer a native SFTP implementation over shelling out to `ssh`, `scp`, or `rsync`, unless a later design document records a reason to differ.
+Remote file-transfer support should prefer native protocol implementations over shelling out, unless a later design document records a reason to differ.
 
 ## Dependency Policy
 
@@ -184,7 +184,7 @@ Avoid dependencies for small conveniences. Do not let external dependency types
 
 ## Package Layout
 
-Use this layout unless the project has a documented reason to differ:
+Use this current layout unless the project has a documented reason to differ:
 
 - `cmd/distributor`: application entrypoint only.
 - `internal/app`: application orchestration and top-level use cases.
@@ -194,14 +194,14 @@ Use this layout unless the project has a documented reason to differ:
 - `internal/state`: `.distributor.json` parsing, validation, comparison, and output metadata.
 - `internal/storage`: backend interfaces, shared path/resource types, backend registry, and storage errors.
 - `internal/adapters/local`: local filesystem backend.
-- `internal/adapters/ssh`: SSH/SFTP backend.
-- `internal/adapters/s3`: S3-compatible object storage backend.
 - `internal/transform`: transform interfaces, registry, planning, and shared transform models.
 - `internal/transform/markdown`: Markdown-to-HTML implementation.
 - `internal/publish`: destination planning, reconciliation, safety checks, and publish execution.
 - `internal/notify`: notification interface and MVP no-op notifier.
 - `internal/logging`: logging setup and shared logging helpers.
 
+New storage adapters should live under `internal/adapters/<name>` and stay thin.
+
 Package-private implementation constants may live near the package that owns them, preferably in `constants.go` when useful.
 
 ## Configuration
@@ -244,9 +244,9 @@ Each major stage should have an explicit input/output contract:
 - publish execution;
 - notification.
 
-If users can select backends, transforms, notifiers, or future renderers, selection should go through a registry or equivalent mechanism rather than scattered conditionals.
+If users can select backends, transforms, notifiers, or renderers, selection should go through a registry or equivalent mechanism rather than scattered conditionals.
 
-The orchestrator should be able to plan, dry-run, and execute configured pipelines. Dry-run behavior should be first-class because the application may delete, overwrite, or publish files to remote storage.
+The orchestrator should be able to plan, dry-run, and execute configured pipelines. Dry-run behavior should be first-class because the application may delete, overwrite, or publish files.
 
 ## Embedded Assets
 
@@ -264,7 +264,7 @@ Skip and no-op decisions should be logged at an appropriate level so operators c
 
 ## Context, Timeouts, and Cancellation
 
-Long-running operations should accept `context.Context`. Storage operations, SSH/SFTP sessions, S3 requests, transforms, and multi-stage workflows should respect cancellation and timeouts.
+Long-running operations should accept `context.Context`. Storage operations, service requests, transforms, and multi-step workflows should respect cancellation and timeouts.
 
 ## State, Files, and Safety
 
@@ -282,7 +282,7 @@ Where practical, publish operations should use staging paths or temporary object
 
 Core logic should be testable without real external services. Use fakes, fixtures, or local test doubles for adapters where practical.
 
-Config examples should be load-tested. Important CLI workflows should have parser or command tests. Stage/module contracts should have focused tests that do not require running the full application unless end-to-end coverage is intentional.
+Config examples should be load-tested. Important CLI workflows should have parser or command tests. Component contracts should have focused tests that do not require running the full application unless end-to-end coverage is intentional.
 
 Important tests include:
 
@@ -297,13 +297,13 @@ Important tests include:
 - transform output planning and metadata recording;
 - dry-run output;
 - local backend behavior with temporary directories;
-- fake backend behavior for S3 and SSH/SFTP-facing core logic.
+- fake backend behavior for storage-facing core logic.
 
 ## Documentation
 
 Documentation should follow the project documentation policy. Keep user docs focused on implemented behavior. Put future, planned, or aspirational work only under `docs/roadmap/`.
 
-When changing architecture, config, CLI behavior, adapters, manifest/state contracts, transform behavior, publish behavior, or stage/module contracts, update the relevant docs and examples in the same change.
+When changing architecture, config, CLI behavior, adapters, manifest/state contracts, transform behavior, publish behavior, or component contracts, update the relevant docs and examples in the same change.
 
 The source manifest and destination `.distributor.json` schemas should have canonical documentation once implemented. Example configs should be valid and load-tested where practical.
 
@@ -321,4 +321,4 @@ The source manifest and destination `.distributor.json` schemas should have cano
 - a backup system;
 - a notification platform.
 
-It may later support notification adapters, RSS/feed generation, richer HTML templates, or additional transforms, but those features must preserve the core bundle-distribution boundary.
+Additional notification, feed, template, or transform behavior must preserve the core bundle-distribution boundary.