distributor/docs/operations.md

# Distributor Operations

## Normal workflow

Preview a local publication:

```sh
go run ./cmd/distributor run --config examples/local-publish.yml --dry-run
```

Run the local publication:

```sh
go run ./cmd/distributor run --config examples/local-publish.yml
```

Run the local HTML publication:

```sh
go run ./cmd/distributor run --config examples/local-html.yml
```

## Filesystem layout

Source bundles are discovered beneath the configured local source root. Destination bundle paths preserve the source bundle path relative to that source root.

The maintained example writes under `workspace/`, which is ignored by Git.

## Destination state

Each published destination bundle contains `.distributor.json`. This state file records the source manifest, copied source outputs, and generated outputs. It is the authoritative marker that a destination path is managed by `distributor`.

`manifest.json` from the source bundle is not copied as destination state.

## Retry behavior

If a destination already has matching `.distributor.json`, publication skips it as already published.

If destination state is older than the source manifest, publication replaces only managed outputs recorded in `.distributor.json` plus the state file.

If a write fails during local publication, `distributor` removes outputs written during that failed attempt where possible so a retry does not see an unmanaged destination.

If one destination fails, later destinations in the same fan-out are still planned and run where they are independent. The command exits non-zero after printing the final status when any destination fails.

After a successful publish or replacement, the internal notifier hook runs as a no-op. Skipped destinations do not invoke it.

## Caveats

Only local-to-local publication is implemented. SSH, S3, external notification adapters, and force overwrite behavior are not implemented.