Add local source publication

docs/internal/publish.md

@@ -0,0 +1,29 @@
+# Publish
+
+## Purpose
+
+`internal/publish` plans and executes publication for one validated source bundle and one destination.
+
+## Inputs and outputs
+
+Inputs are a source bundle, source backend, destination backend, pipeline id, destination id, publish policy, transfer policy, destination bundle path, and existing destination state.
+
+Output is a plan with an action, reason, and selected source outputs. Execution writes selected source files and `.distributor.json` for publish or replacement actions.
+
+## Actions
+
+Supported actions are publish new, replace older destination, skip same source, skip newer destination, fail conflict, and fail unmanaged destination.
+
+## Boundaries
+
+The current implementation publishes source files only. HTML generation and remote backend execution are not implemented.
+
+The package uses `internal/state` for destination comparison and `internal/storage` for IO. It does not parse CLI flags or load config files.
+
+## Safety
+
+Replacement deletes only outputs recorded in existing destination state plus `.distributor.json`. Failed local writes trigger cleanup of outputs written during the failed attempt.
+
+## Tests
+
+Before changing publish behavior, inspect tests under `internal/publish` and local run tests under `internal/app`.