distributor/docs/internal/publish.md

# 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 or generated outputs. Execution writes selected source files, generated 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 and Markdown-to-HTML sidecar outputs. Remote backend execution is 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`.