Removed the completed code audit and implementation plan

.woodpecker/release.yml

@@ -0,0 +1,50 @@
+when:
+  - event: tag
+
+steps:
+  - name: build-release-assets
+    image: golang:1.26
+    commands:
+      - |
+        set -eu
+
+        version="$CI_COMMIT_TAG"
+        dist="dist"
+        pkg="gitea.maximumdirect.net/eric/distributor/cmd/distributor"
+
+        rm -rf "$dist"
+        mkdir -p "$dist"
+
+        build_binary() {
+          goos="$1"
+          goarch="$2"
+          suffix="$3"
+          output="$dist/distributor-$version-$goos-$goarch$suffix"
+
+          CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \
+            go build -trimpath -ldflags "-s -w -X gitea.maximumdirect.net/eric/distributor/internal/buildinfo.Version=$version" \
+            -o "$output" "$pkg"
+        }
+
+        build_binary linux amd64 ""
+        build_binary linux arm64 ""
+        build_binary darwin amd64 ""
+        build_binary darwin arm64 ""
+        build_binary windows amd64 ".exe"
+        build_binary windows arm64 ".exe"
+
+  - name: publish-release
+    image: woodpeckerci/plugin-release
+    depends_on:
+      - build-release-assets
+    settings:
+      api_key:
+        from_secret: GITEA_RELEASE_TOKEN
+      files:
+        - dist/distributor-*
+      checksum: sha256
+      checksum-file: SHA256SUMS
+      checksum-flatten: true
+      file-exists: skip
+      overwrite: false
+      prerelease: false

README.md

@@ -1,6 +1,10 @@
 # distributor
 
-`distributor` validates and publishes manifested report bundles.
+`distributor` validates manifested report bundles and publishes selected source or generated artifacts to configured destinations.
+
+It is a local-first CLI with SSH/SFTP and S3-compatible storage support: source bundles can be read from local or remote storage, destinations can be local directories or remote paths, and Markdown files can be rendered to HTML sidecars or `index.html`.
+
+Go producers can use `gitea.maximumdirect.net/eric/distributor/pkg/bundle` to build, write, parse, and validate complete local source bundles with the same manifest contract used by `distributor`.
 
 Run the local example pipeline:
 
@@ -8,4 +12,4 @@ Run the local example pipeline:
 go run ./cmd/distributor run --config examples/local-publish.yml
 ```
 
-See [docs/cli.md](docs/cli.md), [docs/config.md](docs/config.md), and [docs/operations.md](docs/operations.md) for the implemented CLI, configuration, and operating notes. Current design and implementation planning lives under `docs/roadmap/`.
+See [docs/cli.md](docs/cli.md), [docs/config.md](docs/config.md), [docs/operations.md](docs/operations.md), and [docs/troubleshooting.md](docs/troubleshooting.md) for the implemented CLI, configuration, operating notes, and common failure modes. Future and deferred work lives under `docs/roadmap/`.

docs/cli.md

@@ -6,44 +6,63 @@
 go run ./cmd/distributor run --config examples/local-publish.yml
 ```
 
-This validates and publishes the example source bundle to `workspace/published/source-bundle`.
+This discovers the example source bundle and publishes source files to `workspace/published/source-bundle`.
 
 ## Command overview
 
 ```sh
-distributor --help
-distributor version
-distributor run
-distributor validate
-distributor inspect
+distributor [--help]
+distributor version [--format text|json]
+distributor run [--config <path>] [--dry-run] [--force] [--format text|json]
+distributor validate [--format text|json] <path>
+distributor validate --config <path> --pipeline <id> [--bundle <path>] [--format text|json]
+distributor inspect [--format text|json] <path>
+distributor inspect --config <path> --pipeline <id> [--bundle <path>] [--format text|json]
+distributor manifest create <bundle-path> --id <bundle-id> [options]
 ```
 
-`version` prints the application name and version. The default development version is `dev`; release builds may replace it at build time.
+- `version`: prints the application name and version. Development builds print `distributor dev`.
+- `run`: loads a YAML config, discovers source bundles, plans each configured destination, writes selected outputs unless `--dry-run` is set, and prints a final status summary.
+- `validate`: validates a local source bundle directory, a local source bundle tree, or one configured pipeline source.
+- `inspect`: validates source bundles and prints normalized bundle metadata for a local path or one configured pipeline source.
+- `manifest create`: creates `manifest.json` for a local source bundle directory.
 
-`run --config <path>` executes configured local-to-local pipelines that publish source files, generated HTML files, or both.
-
-`run --config <path> --dry-run` discovers source bundles, inspects destination state, and prints planned actions plus a final status summary without writing files.
-
-`validate <path>` validates a local source bundle directory or a local tree containing source bundles.
-
-`inspect <path>` validates discovered local source bundles and prints a concise normalized summary.
-
-Remote backends are not implemented yet.
+`validate` and `inspect` have two mutually exclusive modes: a local path shortcut, or configured source mode with `--config <path> --pipeline <id>`. Configured source mode opens only the selected pipeline source and supports configured `local`, `ssh`, and `s3` sources. It does not open destinations. `run` executes configured sources and destinations.
 
 ## Flag reference
 
-The root command supports:
+Root command:
 
-- `--help`, `-h`: print root help.
+- `--help`, `-h`, or `help`: print root help.
 
-Each subcommand supports:
+All subcommands:
 
 - `--help`, `-h`: print command-specific help.
 
-`run` supports:
+Output-producing subcommands:
 
-- `--config <path>`: config file to load.
-- `--dry-run`: validate config, print planned actions and final status, and do not publish.
+- `--format text|json`: output format. `text` is the default. Help and usage output are always text.
+
+`run` flags:
+
+- `--config <path>`: config file to load. If omitted, `run` uses `/usr/local/etc/distributor/config.yml`.
+- `--dry-run`: load config, discover bundles, inspect destination state, print planned actions and final status, and do not write output files, destination state, or SSH `known_hosts` entries.
+- `--force`: allow explicit destructive replacement for supported conflict cases in this run only.
+
+`validate` and `inspect` configured source flags:
+
+- `--config <path>`: config file to load for source validation or inspection. Required in configured source mode.
+- `--pipeline <id>`: pipeline source to validate or inspect. Required in configured source mode.
+- `--bundle <path>`: source-root-relative bundle directory to validate or inspect instead of discovering every bundle under the source root.
+
+`manifest create` flags:
+
+- `--id <bundle-id>`: source bundle id. Required.
+- `--file <path>`: bundle-relative file to include. Repeatable. If omitted, files are scanned recursively.
+- `--created <time>`: RFC3339 source created timestamp. If omitted, the current UTC time is used.
+- `--overwrite`: replace an existing `manifest.json`.
+
+`run` does not accept positional arguments. `validate` and `inspect` accept at most one path in local mode. Local paths cannot be combined with `--config`, `--pipeline`, or `--bundle`.
 
 ## Common workflows
 
@@ -59,13 +78,44 @@ Inspect a source bundle:
 go run ./cmd/distributor inspect examples/source-bundle
 ```
 
+Validate a configured source without opening destinations:
+
+```sh
+go run ./cmd/distributor validate --config examples/local-publish.yml --pipeline example-source-bundle
+```
+
+Inspect one configured source bundle:
+
+```sh
+go run ./cmd/distributor inspect \
+  --config <config-path> \
+  --pipeline <pipeline-id> \
+  --bundle daily/2026-06-01
+```
+
+Create a manifest for a local producer bundle:
+
+```sh
+go run ./cmd/distributor manifest create <bundle-path> --id <bundle-id>
+```
+
+Create a manifest with explicit file order:
+
+```sh
+go run ./cmd/distributor manifest create <bundle-path> \
+  --id <bundle-id> \
+  --created 2026-06-01T11:00:00Z \
+  --file report.md \
+  --file summary.txt
+```
+
 Preview local publication without writing:
 
 ```sh
 go run ./cmd/distributor run --config examples/local-publish.yml --dry-run
 ```
 
-Publish the local example:
+Publish the local source example:
 
 ```sh
 go run ./cmd/distributor run --config examples/local-publish.yml
@@ -76,3 +126,70 @@ Publish the local HTML example:
 ```sh
 go run ./cmd/distributor run --config examples/local-html.yml
 ```
+
+Preview local fan-out publication:
+
+```sh
+go run ./cmd/distributor run --config examples/fan-out.yml --dry-run
+```
+
+Preview local archive-plus-latest publication:
+
+```sh
+go run ./cmd/distributor run --config examples/archive-and-latest.yml --dry-run
+```
+
+Preview a forced replacement before publishing:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run --force
+```
+
+## Output
+
+Text output is the default and is intended for humans.
+
+`run` text output prints the number of configured pipelines, one line per pipeline, one line per planned destination action, and a final status line. Destination action lines include the source bundle path, destination id, destination backend, action, outputs, and reason. Fixed path destinations also print `path_mapping=fixed target=.` to show that the selected bundle targets the destination backend root. Actions include:
+
+- `publish_new`: destination has no managed state and is empty.
+- `replace_older`: destination state is older than the source manifest.
+- `force_replace`: `--force` requested a supported destructive replacement.
+- `skip_same`: destination state already matches the source manifest.
+- `skip_destination_newer`: destination state is newer than the source manifest.
+- `error`: planning or execution failed for that destination.
+
+The command exits non-zero if any destination fails. Independent later destinations are still attempted.
+
+Dry-run output for fixed path destinations prints a warning with the candidate count and selected source bundle. If a fixed path dry run plans a destructive replacement, it prints an additional warning that the destination root would be replaced.
+
+The final status line includes counters for `publish_new`, `replace_older`, `force_replace`, skipped destinations, failures, whether the run was a dry run, and fixed path destinations.
+
+JSON output writes exactly one JSON document to stdout:
+
+```json
+{
+  "schema_version": 1,
+  "command": "inspect",
+  "ok": true,
+  "warnings": [],
+  "result": {}
+}
+```
+
+Warnings are objects in the top-level `warnings` array and are not printed again as text. Fatal setup errors, such as a missing config file or invalid arguments, write no JSON document and return a non-zero exit code with a text error on stderr.
+
+`run --format json` returns partial results when destination failures occur after planning or execution begins. In that case stdout contains `ok: false`, a `result` with pipeline summaries, destination actions, final counters, and a top-level `errors` array; the process still exits non-zero.
+
+Command-specific JSON results:
+
+- `version`: application name and version.
+- `validate`: bundle count and discovered bundle identifiers. Configured source results also include pipeline id and source backend.
+- `inspect`: bundle path, id, created timestamp, digest, file count, total size, and manifest file records. Configured source results also include pipeline id and source backend.
+- `manifest create`: manifest path, bundle root, id, created timestamp, digest, file count, and file records.
+- `run`: dry-run status, pipeline summaries, destination action records, destination bundle paths, path mapping markers, optional primary URLs, output records with optional URLs, final counters, warnings, and partial failure records.
+
+## Diagnostics
+
+Use `manifest create` when a local producer has written bundle files but not `manifest.json`. Use `validate` before publication when a producer has written a new bundle; use configured source mode when the bundle is already on an SSH or S3 source. Use `inspect` to confirm normalized ids, timestamps, digests, file paths, and file sizes.
+
+For symptom-oriented recovery steps, see [troubleshooting](troubleshooting.md). For destination state and retry behavior, see [operations](operations.md). For config fields and defaults, see [configuration](config.md).

docs/config.md

@@ -1,18 +1,18 @@
-# Distributor Configuration
+# Configuration Reference
 
-## Config file location
+## Config File Location
 
-`distributor run --config <path>` loads the YAML config at the path provided by `--config`.
+`distributor run --config <path>` loads the YAML config at the provided path.
 
-If `--config` is omitted during run, the built-in default path is:
+If `--config` is omitted, `run` uses:
 
 ```text
 /usr/local/etc/distributor/config.yml
 ```
 
-The current implementation supports local-to-local publication of source files, generated HTML files, or both. Remote backends are not implemented yet.
+Config parsing rejects unknown YAML fields. The executable backends are `local`, `ssh`, and `s3`.
 
-## Minimal config
+## Minimal Local Config
 
 ```yaml
 pipelines:
@@ -26,9 +26,9 @@ pipelines:
         path: /srv/reports/archive
 ```
 
-This uses the default publish policy of source files only and the default transfer policy.
+This publishes source files only. It uses the default validation and transfer policies.
 
-## Production-oriented config
+## Production-Oriented Local Config
 
 ```yaml
 pipelines:
@@ -52,45 +52,257 @@ pipelines:
           on_conflict: fail
 ```
 
+## HTML Publication
+
+To publish generated sidecar HTML from Markdown files:
+
+```yaml
+publish:
+  source: false
+  html: true
+transform:
+  markdown_to_html:
+    enabled: true
+    mode: sidecar
+```
+
+Sidecar generation writes `report.html` for `report.md`. It does not mutate the source bundle.
+
+To publish a single Markdown file as `index.html`:
+
+```yaml
+publish:
+  source: false
+  html: true
+transform:
+  markdown_to_html:
+    enabled: true
+    mode: index
+    input: report.md
+```
+
+When `mode: index` omits `input`, the source manifest must list exactly one Markdown file.
+
+## Destination Path Mapping
+
+Each destination chooses how source bundle paths map into that destination:
+
+```yaml
+path_mapping:
+  mode: preserve_relative
+```
+
+`preserve_relative` is the default. It publishes each discovered source bundle at the same path relative to the destination backend root. A source bundle at `daily/2026-06-01` publishes below `daily/2026-06-01` for that destination.
+
+`fixed` publishes one selected source bundle directly at the destination backend root:
+
+```yaml
+destinations:
+  - id: latest-html
+    backend: local
+    path: /srv/www/reports/latest
+    path_mapping:
+      mode: fixed
+    publish:
+      source: false
+      html: true
+    transform:
+      markdown_to_html:
+        enabled: true
+        mode: index
+        input: report.md
+```
+
+Fixed destinations select the newest discovered source bundle by manifest `created` timestamp. If multiple candidates have the same timestamp, the source-root-relative bundle path in ascending order wins. Older candidates are not planned or written for that destination.
+
+Fixed mapping is useful for stable latest-style paths. It is more destructive than archive-style publication because successive source bundles target the same destination root. Preview fixed destinations with `run --dry-run`, especially before using `--force`.
+
+## Destination Links
+
+Destinations can record public URLs for published outputs:
+
+```yaml
+links:
+  base_url: https://reports.example.com/archive
+  primary: auto
+```
+
+`links.base_url` is an absolute `http` or `https` URL corresponding to the destination backend root. It may include a path prefix, but it must not include a query string or fragment. Distributor does not infer public URLs from backend config.
+
+`links.primary` selects the top-level primary URL stored in destination state:
+
+- `auto`: prefer `index.html`, then generated HTML, then source outputs.
+- `html`: use the first generated HTML output.
+- `source`: use the first copied source output.
+
+If a destination has no `links` block, no URL metadata is generated. If a primary policy has no matching output, per-output URLs are still recorded and the top-level primary URL is omitted.
+
+Output URLs are built from `links.base_url`, the destination bundle path, and the output path using URL path semantics. `index.html` outputs produce directory-style URLs that omit the filename.
+
 ## Reference
 
 Top level:
 
+- `secrets.directory`: optional credential secrets directory.
 - `pipelines`: required non-empty list.
 
 Pipeline:
 
-- `id`: required unique identifier.
+- `id`: required unique slug-like identifier.
 - `source`: required backend config.
+- `validation.on_digest_mismatch`: optional; defaults to `fail`; only `fail` is supported.
 - `destinations`: required non-empty destination list.
-- `validation.on_digest_mismatch`: optional, defaults to `fail`; only `fail` is supported.
 
-Backends:
+Source backend:
 
-- `local`: requires `path`.
-- `ssh`: requires `uri` and `path`.
-- `s3`: requires `endpoint` and `bucket`; supports optional `prefix`, `region`, `force_path_style`, and `credentials`.
+- `backend`: required.
+- `path`: required for `local` and `ssh`.
+- `host`: required for `ssh`.
+- `user`: optional for `ssh`; defaults to the current OS user when available.
+- `port`: optional for `ssh`; defaults to `22`.
+- `ssh_key_file`: optional for `ssh`.
+- `known_hosts`: optional for `ssh`; defaults to the service user's OpenSSH `known_hosts` path when available.
+- `host_key_policy`: optional for `ssh`; defaults to `accept-new`.
+- `endpoint`: required for `s3`.
+- `bucket`: required for `s3`.
+- `prefix`: optional for `s3`; leading and trailing slashes are trimmed.
+- `region`: optional for `s3`; defaults to `us-east-1`.
+- `force_path_style`: optional for `s3`; defaults to `true`. Set `false` only for services that require virtual-host addressing.
+- `credentials.access_key_id_env`: optional S3 credential environment variable name.
+- `credentials.secret_access_key_env`: optional S3 credential environment variable name.
 
-Destination policy:
+Destination:
+
+- `id`: required unique slug-like identifier within the pipeline.
+- Backend fields: same accepted shape as source backends, with destination fields at the destination level.
+- `publish`: optional; defaults to source-only publication.
+- `transform`: required only for generated HTML publication.
+- `path_mapping.mode`: optional; defaults to `preserve_relative`. Accepted values are `preserve_relative` and `fixed`.
+- `links.base_url`: optional links block; when present, `base_url` is required and must be an absolute HTTP or HTTPS URL without query string or fragment.
+- `links.primary`: optional; defaults to `auto`. Accepted values are `auto`, `html`, and `source`.
+- `transfer`: optional; defaults described below.
+
+Accepted backend names:
+
+- `local`: executable; requires `path`.
+- `ssh`: executable; requires `host` and `path`.
+- `s3`: executable; requires `endpoint` and `bucket`.
+
+## SSH Backend
+
+SSH uses native SFTP. It can be used for sources, destinations, or both:
+
+```yaml
+backend: ssh
+host: example.com
+user: distributor
+port: 2222
+path: /remote/root
+ssh_key_file: /home/distributor/.ssh/id_ed25519
+known_hosts: /home/distributor/.ssh/known_hosts
+host_key_policy: accept-new
+```
+
+Authentication uses SSH agent identities first when `SSH_AUTH_SOCK` is set, then `ssh_key_file` if configured. Password authentication in YAML is not supported.
+
+Host key policies:
+
+- `strict`, `true`, and `"true"` require a matching known host key.
+- `accept-new` accepts and persists a new host key, but fails if an existing key changed. During `run --dry-run`, new host keys are accepted only for the current connection and are not persisted.
+- `off`, `false`, and `"false"` disable host key checking and are insecure.
+
+`accept-new` and `strict` use `known_hosts` when configured. If omitted, distributor uses the current service user's default OpenSSH `known_hosts` path where practical. `accept-new` fails when it needs to persist a new host key and no writable `known_hosts` path is available. It does not create a missing parent `.ssh` directory.
+
+## S3 Backend
+
+S3 uses the AWS SDK for Go v2 and supports S3-compatible endpoints:
+
+```yaml
+backend: s3
+endpoint: https://s3.example.com
+bucket: reports
+prefix: archive
+region: us-east-1
+force_path_style: true
+credentials:
+  access_key_id_env: DISTRIBUTOR_S3_ACCESS_KEY_ID
+  secret_access_key_env: DISTRIBUTOR_S3_SECRET_ACCESS_KEY
+```
+
+`endpoint` and `bucket` are required. `prefix` is an optional backend root; it is treated as an object-key prefix, not a real directory. Prefixes must be clean slash-separated paths after trimming leading and trailing slashes. `http://` endpoints are allowed for explicitly configured local development or local S3-compatible test services.
+
+If either credential environment variable name is configured, both must be configured and both referenced variables must resolve to non-empty values through the real process environment or `secrets.directory`. Explicit credentials take precedence over the AWS SDK default credential chain. If credential environment variable names are omitted, the SDK default credential chain is used and `secrets.directory` values are not injected into the process environment.
+
+Publish policy:
 
 - `publish.source`: publish source artifacts.
 - `publish.html`: publish generated HTML artifacts from Markdown source files.
-- `transfer.on_destination_same`: `skip` or `fail`, defaults to `skip`.
-- `transfer.on_destination_older`: `replace` or `fail`, defaults to `replace`.
-- `transfer.on_destination_newer`: `skip` or `fail`, defaults to `skip`.
-- `transfer.on_conflict`: only `fail`, defaults to `fail`.
 
-When `publish.html` is true, `transform.markdown_to_html.enabled: true` and `transform.markdown_to_html.mode: sidecar` are required.
+At least one output type must be enabled. When `publish.html` is true, `transform.markdown_to_html.enabled` must be `true`.
 
-Markdown-to-HTML sidecar generation writes `report.html` for `report.md` and does not mutate the source bundle.
+Markdown-to-HTML transform:
+
+- `transform.markdown_to_html.enabled`: enables Markdown-to-HTML generation for destinations with `publish.html: true`.
+- `transform.markdown_to_html.mode`: optional; defaults to `sidecar`. Accepted values are `sidecar` and `index`.
+- `transform.markdown_to_html.input`: optional source manifest path for `index` mode. It must identify a listed Markdown file.
+
+`sidecar` mode renders each manifest-listed `.md` file to a same-directory `.html` output. `index` mode renders one selected Markdown file to `index.html` at the destination bundle path. Enabled Markdown-to-HTML config is rejected when `publish.html` is false, and `input` is valid only with `mode: index`.
+
+Transfer policy:
+
+- `transfer.on_destination_same`: `skip` or `fail`; defaults to `skip`.
+- `transfer.on_destination_older`: `replace` or `fail`; defaults to `replace`.
+- `transfer.on_destination_newer`: `skip`, `replace`, or `fail`; defaults to `skip`.
+- `transfer.on_conflict`: `fail` or `replace`; defaults to `fail`.
+
+`replace` for `on_destination_newer` and `on_conflict` is honored only when `run --force` is used for that invocation. Force is CLI-only; there is no persistent config field that enables forced replacement by default.
+
+## Defaults
+
+Defaults are applied after YAML decoding and before validation:
+
+- `validation.on_digest_mismatch: fail`
+- SSH `port: 22`
+- SSH `host_key_policy: accept-new`
+- S3 `region: us-east-1`
+- S3 `force_path_style: true`
+- `transform.markdown_to_html.mode: sidecar` when a Markdown-to-HTML transform block is present and mode is omitted
+- `publish.source: true`
+- `publish.html: false`
+- `path_mapping.mode: preserve_relative`
+- `links.primary: auto` when a `links` block is present and `primary` is omitted
+- `transfer.on_destination_same: skip`
+- `transfer.on_destination_older: replace`
+- `transfer.on_destination_newer: skip`
+- `transfer.on_conflict: fail`
 
 ## Secrets
 
-Do not put literal secrets in config files. S3 credentials may refer to environment variable names with:
+Do not put literal secrets in config files. `secrets.directory` lets deployments provide credential values as files:
+
+```yaml
+secrets:
+  directory: /run/secrets/distributor
+```
+
+Each regular file in the directory becomes an internal credential environment value named by the filename. Valid filenames must match `[A-Za-z_][A-Za-z0-9_]*`. Directories are ignored, and symlinks to regular files are followed. Exactly one trailing LF or CRLF is trimmed from each file; other whitespace is preserved.
+
+The resolver checks the real process environment first, then the secrets directory. If both define the same variable with different values, `run` prints a warning with the variable name and uses the real environment value. Secret values are not printed. The process environment is not modified, so SDK default credential chains see only real environment variables.
+
+S3 credentials may name environment variables:
 
 - `credentials.access_key_id_env`
 - `credentials.secret_access_key_env`
 
 ## Examples
 
-Maintained examples live under [examples/](../examples/).
+Maintained examples live under [examples](../examples/):
+
+- `local-to-local.yml`: minimal local config.
+- `local-publish.yml`: runnable local source publication.
+- `local-html.yml`: runnable local HTML publication.
+- `local-index.yml`: runnable local `index.html` publication.
+- `fan-out.yml`: runnable local fan-out publication to source and HTML destinations.
+- `archive-and-latest.yml`: runnable local fan-out publication to an archive destination and a fixed latest destination.
+- `ssh-destination.yml`: environment-gated local-to-SSH publication example.
+- `s3-destination.yml`: environment-gated local-to-S3 publication example.

docs/integrations/markdown.md

@@ -0,0 +1,60 @@
+# Markdown Integration
+
+## Purpose
+
+Markdown-to-HTML is the only implemented external file-format integration. This note documents the renderer behavior that is externally visible in generated destination artifacts.
+
+## Dependency
+
+Rendering uses `github.com/yuin/goldmark`. The exact dependency version is pinned in `go.mod`; review that file before changing renderer behavior or diagnosing version-specific output changes.
+
+## Renderer behavior
+
+`internal/transform/markdown.New` constructs the renderer with `goldmark.New()` and no project-specific extensions or renderer options.
+
+The transform supports two output modes:
+
+- `sidecar`: reads each source bundle file ending in `.md` and generates an HTML sidecar in the same logical directory. The output path replaces the `.md` suffix with `.html`, so `report.md` produces `report.html`. Non-Markdown source files produce no Markdown outputs.
+- `index`: renders one selected Markdown source to `index.html` at the destination bundle path.
+
+In `index` mode, `transform.markdown_to_html.input` can name the source manifest path to render. If `input` is omitted, the manifest must list exactly one Markdown file. The selected input must be a safe relative source path, must be listed in the source manifest, and must end in `.md`.
+
+Raw HTML embedded in Markdown is not passed through by the current renderer behavior. Tests allow Goldmark's disabled-or-escaped raw HTML output forms and reject literal script tags in generated HTML.
+
+## Wrapper
+
+Rendered Markdown body HTML is wrapped in a fixed document shell:
+
+- `<!doctype html>`
+- `<html lang="en">`
+- UTF-8 `<meta charset>`
+- empty `<title>`
+- `<body>` containing the rendered Markdown body
+
+The wrapper is deterministic and does not read configuration, templates, CSS, or source manifest metadata.
+
+## Output metadata
+
+Generated outputs record:
+
+- destination path;
+- source path;
+- transform id `markdown_to_html`;
+- SHA-256 digest of the wrapped HTML bytes;
+- byte size of the wrapped HTML bytes.
+
+## Boundaries
+
+Markdown rendering does not mutate source bundles, publish files, write `.distributor.json`, select outputs, or choose transfer actions. Publish planning decides whether generated HTML is selected for a destination.
+
+Publish planning chooses the configured mode and input for each destination. Markdown rendering does not inspect destinations, publish files, write `.distributor.json`, or choose transfer actions.
+
+## Tests
+
+Before changing Markdown renderer behavior, inspect and run:
+
+```bash
+go test ./internal/transform/markdown
+```
+
+The tests cover sidecar naming, index input selection, ignored non-Markdown files, raw HTML handling, deterministic output, digest metadata, and size metadata.

docs/internal/app.md

@@ -0,0 +1,80 @@
+# Application Orchestration
+
+## Purpose
+
+`internal/app` owns top-level use cases for `run`, `validate`, and `inspect`. It wires configuration, storage backends, transforms, publish planning, execution, summaries, and notification handoff.
+
+## Inputs and outputs
+
+`Run` accepts a context, optional config path, dry-run flag, force flag, stdout writer, output format, and optional notifier. It loads YAML config, discovers source bundles for each configured pipeline, plans each destination independently, optionally executes publish plans, writes text or JSON output when stdout is supplied, and returns an aggregated error if any destination fails.
+
+`Validate` and `Inspect` accept either a local path or one configured pipeline source. `Validate` discovers and validates bundles. `Inspect` writes bundle metadata and manifest file entries to stdout when provided.
+
+## Run flow
+
+The runner:
+
+1. loads config from the supplied path or `config.DefaultConfigPath`;
+2. opens the configured source backend;
+3. discovers validated bundles from the source root;
+4. selects source bundles for each destination according to destination path mapping;
+5. opens each destination backend independently;
+6. builds publish plans for the selected bundle and destination combinations;
+7. prints plan lines or JSON action records and records summary counters;
+8. executes publish or replacement plans unless dry-run is enabled;
+9. invokes the notifier after successful publish or replacement actions.
+
+Destination failures are collected while later destinations continue to run. Source open and source discovery failures stop the run because there are no valid bundles to fan out.
+
+## Run implementation
+
+`run.go` contains the public `Run` entrypoint and the main configuration orchestration path. Package-local run helpers are grouped by responsibility:
+
+- `run_selection.go`: destination bundle selection, path mapping decisions, and fixed-path warnings;
+- `run_warnings.go`: secret and SSH warning data;
+- `run_output.go`: text plan lines, JSON action records, and output projections;
+- `run_summary.go`: summary counters and JSON summary records;
+- `run_failures.go`: destination failure aggregation and partial-result detection;
+- `run_notify.go`: notification event projection and action filtering.
+
+These helpers remain in `internal/app` because command output, warning collection, destination failure aggregation, notifier handoff, and backend construction are app-owned orchestration concerns.
+
+## Backend and transform wiring
+
+The app-level backend factory registers local, SSH, and S3 backends for execution. Source and destination backend config is converted through a shared app-local open spec before adapter construction. S3 explicit credential references are resolved through the config environment resolver.
+
+The app-level transform registry registers Markdown-to-HTML using `internal/transform/markdown`. Lower-level publish code receives a resolver and does not import concrete transform implementations.
+
+## Dry-run behavior
+
+Dry-run still loads config, opens backends, discovers bundles, inspects destinations, resolves transforms, and builds publish plans. It does not write destination outputs, write `.distributor.json`, delete managed outputs, perform forced prefix deletion, or notify.
+
+## Failure behavior
+
+`Run` returns immediately for config loading errors, context cancellation before work starts, source open errors, and source discovery errors. Per-destination backend, planning, execution, and notification errors are aggregated into one run error after remaining destinations have been attempted.
+
+Run diagnostics include pipeline id, destination id, destination backend, and bundle path for destination-scoped failures. Source open and discovery failures include the source backend.
+
+Stdout write errors are returned immediately because the caller's requested output stream can no longer be trusted.
+
+## Boundaries
+
+`internal/app` coordinates packages but does not own manifest validation rules, destination state comparison, storage path rules, output planning, transform rendering, or backend-specific filesystem behavior.
+
+Configured-source `Validate` and `Inspect` share source backend construction with `Run` and do not open destinations.
+
+## Tests
+
+Before changing app orchestration, inspect tests under:
+
+- `internal/app`
+- `internal/cli`
+- `internal/publish`
+
+## Invariants
+
+- One source fans out to each destination independently.
+- Destination failures do not prevent later destinations from being planned.
+- Dry-run must not mutate destination storage or invoke notifications.
+- Concrete backend and transform registration stays at the app layer.
+- The default notifier is `notify.Noop`.

docs/internal/bundle.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-`internal/bundle` parses, discovers, and validates source bundles through the storage interface.
+`internal/bundle` discovers and validates source bundles through the storage interface. The source manifest model, manifest parsing, manifest validation, path rules, digest calculation, and producer-side local writer come from `pkg/bundle` so producer-facing APIs and distributor validation share one manifest contract.
 
 ## Inputs and outputs
 
@@ -20,11 +20,13 @@ The source manifest requires:
 
 Each file requires `path`, `sha256`, and `size`. Digests must use lowercase `sha256:<64 hex>` format. `created` must parse as RFC3339.
 
+`pkg/bundle.ValidateDigest` is the canonical digest format validator for producer-facing and internal code. `internal/bundle.ValidateDigest` delegates to that public validator so source manifests and destination state use the same digest grammar.
+
 ## Validation
 
-`ValidateManifest` owns normalized source manifest semantics: schema version, id, digest format, timestamp presence, file list presence, source path safety, duplicate file paths, reserved paths, file digest format, non-negative file sizes, and the top-level bundle digest.
+`pkg/bundle.ValidateManifest` owns normalized source manifest semantics: schema version, id, digest format, timestamp presence, file list presence, source path safety, duplicate file paths, reserved paths, file digest format, non-negative file sizes, and the top-level bundle digest.
 
-Storage-backed bundle validation additionally checks file existence, regular-file type, file size, and per-file SHA-256.
+Storage-backed bundle validation in `internal/bundle` additionally checks file existence, regular-file type, file size, and per-file SHA-256 for configured storage backends.
 
 The bundle digest is SHA-256 of a deterministic JSON array of file records in manifest order with fields `path`, `sha256`, and `size`.
 
@@ -32,10 +34,22 @@ The bundle digest is SHA-256 of a deterministic JSON array of file records in ma
 
 Discovery walks a storage backend beneath a source root, finds `manifest.json` files, sorts bundle paths lexically, and rejects nested manifests.
 
+## Failure behavior
+
+Manifest parsing and validation fail before destination planning. Storage-backed validation fails when listed files are missing, are not regular files, have unexpected sizes, have unexpected SHA-256 digests, or when a source bundle includes unsafe or reserved paths.
+
 ## Boundaries
 
-Bundle code uses `internal/storage` and does not import local, SSH, or S3 adapters. CLI local path support is wired in `internal/app`.
+Internal bundle discovery uses `internal/storage` and does not import concrete adapters. Producer-side local filesystem manifest building, complete bundle writing, and validation belong to `pkg/bundle`. CLI local path support is wired in `internal/app`.
 
 ## Tests
 
-Before changing bundle behavior, inspect tests under `internal/bundle`.
+Before changing bundle behavior, inspect tests under `pkg/bundle` and `internal/bundle`.
+
+## Invariants
+
+- `manifest.json` is the only source bundle contract.
+- Source file paths must stay relative to the bundle root.
+- The top-level bundle digest is derived from manifest file records in order.
+- Discovery order is lexical and deterministic.
+- Nested manifests are rejected.

docs/internal/config.md

@@ -0,0 +1,86 @@
+# Configuration Internals
+
+## Purpose
+
+`internal/config` defines YAML-backed configuration structs, defaulting, and validation for distributor pipelines.
+
+## Inputs and outputs
+
+Input is a YAML file containing optional `secrets` and required `pipelines`. Output is a `Config` value with defaults applied and validation completed. Load failures include the config path and whether the failure occurred during file loading, YAML parsing, or validation.
+
+## Loading flow
+
+`LoadFile` opens the requested path, decodes YAML with known-field checking enabled, applies defaults, and validates the result. The app uses `DefaultConfigPath` when the CLI does not supply a config path.
+
+Known-field checking rejects misspelled or unknown YAML keys before defaults and validation run.
+
+`LoadFile` does not read secret files. `Run` loads the configured secrets directory after config validation and before backend construction.
+
+## Defaults
+
+Defaults are applied in `ApplyDefaults`:
+
+- pipeline validation defaults `on_digest_mismatch` to `fail`;
+- SSH backend `port` defaults to `22`;
+- SSH backend `host_key_policy` defaults to `accept-new`;
+- destination publish policy defaults to source output only;
+- Markdown-to-HTML mode defaults to `sidecar` when a transform block is present and mode is omitted;
+- destination path mapping defaults to `preserve_relative`;
+- destination link primary policy defaults to `auto` when a `links` block is present;
+- `transfer.on_destination_same` defaults to `skip`;
+- `transfer.on_destination_older` defaults to `replace`;
+- `transfer.on_destination_newer` defaults to `skip`;
+- `transfer.on_conflict` defaults to `fail`.
+
+## Validation responsibilities
+
+Validation requires at least one pipeline, slug-like unique pipeline ids, one source per pipeline, at least one destination, slug-like unique destination ids within each pipeline, backend-specific required fields, valid validation policy, valid publish and transform combinations, valid destination path mapping mode, valid destination link config, and valid transfer actions.
+
+Transfer validation accepts `replace` for `on_destination_newer` and `on_conflict`, but publish planning honors those destructive actions only when the current run explicitly requests force.
+
+`ValidatePublishTransformPolicy` is shared with publish planning so destination policy combinations are checked consistently. Publishing HTML requires an enabled Markdown-to-HTML transform in `sidecar` or `index` mode. Enabled Markdown-to-HTML config is rejected when `publish.html` is false. `input` is accepted only for enabled `index` mode. A publish policy must select source output, HTML output, or both.
+
+Destination path mapping accepts `preserve_relative` and `fixed`. The app layer applies the mapping when it selects destination bundle paths; config owns only YAML shape, defaulting, and validation.
+
+Destination links are optional. When a `links` block is present, `base_url` is required, must use `http` or `https`, and must not include a query string or fragment. `primary` accepts `auto`, `html`, and `source`.
+
+## Executable support boundary
+
+Config validation accepts `local`, `ssh`, and `s3` backend shapes. Runtime execution opens all three through `internal/app`.
+
+SSH config uses structured fields: `host`, optional `user`, optional `port`, `path`, optional `ssh_key_file`, optional `known_hosts`, and optional `host_key_policy`. `host_key_policy` accepts YAML booleans and strings and normalizes `true`/`strict`, `accept-new`, and `false`/`off`.
+
+S3 config requires `endpoint` and `bucket`, normalizes optional `prefix`, defaults `region` to `us-east-1`, and defaults omitted `force_path_style` to `true` while preserving explicit `false`.
+
+## Secrets and credential resolution
+
+`secrets.directory` points to a directory of credential files. `LoadSecretEnvironment` reads regular files and symlinks to regular files, rejects invalid filenames, trims exactly one trailing LF or CRLF, and returns an `Environment` resolver plus conflict metadata.
+
+The resolver checks the real process environment first and loaded secret values second. Differing process/secret conflicts are reported by variable name only. The resolver does not mutate `os.Environ`; default SDK credential chains continue to see only real process environment values.
+
+Credential-consuming backend wiring should resolve explicit credential environment variable references through `Environment.ResolveCredentials` or the same resolver pattern instead of calling `os.Getenv` directly.
+
+The user-facing configuration reference is `docs/config.md`; this file documents package behavior for maintainers.
+
+## Failure behavior
+
+Load errors wrap the underlying file, YAML, or validation error with context. Validation collects all detected field errors into one error value instead of stopping at the first invalid field.
+
+Unsupported backend names fail validation. Accepted backend names without runtime execution support fail later during app backend opening.
+
+## Tests
+
+Before changing config behavior, inspect:
+
+- `internal/config/load_test.go`
+- `internal/config/validate_test.go`
+- example-loading coverage in `internal/config`
+- user-facing examples under `examples/`
+
+## Invariants
+
+- Defaults are applied before validation.
+- Unknown YAML fields are rejected.
+- `docs/config.md` remains the canonical user-facing config reference.
+- Runtime backend execution support is not inferred from config validation support.
+- New user-visible config behavior must be covered by tests and docs in the same change.

docs/internal/link.md

@@ -0,0 +1,27 @@
+# Link URL Policy
+
+## Purpose
+
+`internal/link` defines shared validation for configured and persisted HTTP link URLs.
+
+## Inputs and outputs
+
+Input is a URL string. Output is either nil for an accepted URL or a concise validation error that callers wrap with field context.
+
+## Validation behavior
+
+Accepted URLs must parse successfully, use `http` or `https`, include a host, and omit query strings and fragments.
+
+## Boundaries
+
+This package validates URL shape only. It does not construct destination output URLs, choose primary URLs, infer public URLs from backend configuration, or read configuration files.
+
+## Tests
+
+Before changing link URL policy, inspect tests under `internal/link` and callers in `internal/config`, `internal/state`, and `internal/publish`.
+
+## Invariants
+
+- Configured `links.base_url`, persisted `links.primary_url`, persisted output `url`, and publish link planning use the same URL policy.
+- Callers own field-specific error context.
+- URL path construction remains in `internal/publish`.

docs/internal/notify.md

@@ -4,10 +4,32 @@
 
 `internal/notify` defines the internal notification interface used by the application runner.
 
+## Inputs and outputs
+
+Input is a notification event containing pipeline id, destination id, bundle id, bundle path, action, and output metadata. The interface returns an error so app orchestration can treat notification failures as destination failures.
+
 ## Current behavior
 
 The implemented notifier is a no-op. It is invoked only after a successful publish or replacement. Dry-run, skipped destinations, and failed destinations do not invoke it.
 
+## Failure behavior
+
+`notify.Noop` always succeeds unless the context is already canceled. If a configured notifier returns an error, `internal/app` records that destination as failed and continues with remaining destinations.
+
 ## Boundaries
 
-No external notification adapters are implemented. Notification configuration is not part of the current user-facing config schema.
+External notification adapters and user-facing notification configuration are outside current behavior.
+
+## Tests
+
+Before changing notification behavior, inspect:
+
+- `internal/notify`
+- `internal/app/run_test.go`
+
+## Invariants
+
+- Notifications are emitted only after successful publish or replacement execution.
+- Dry-run never notifies.
+- Skipped and failed destinations never notify.
+- The default app notifier is `notify.Noop`.

docs/internal/publish.md

@@ -6,24 +6,47 @@
 
 ## Inputs and outputs
 
-Inputs are a source bundle, source backend, destination backend, pipeline id, destination id, publish policy, transform policy, transformer resolver, transfer policy, destination bundle path, and existing destination state.
+Inputs are a source bundle, source backend, destination backend, pipeline id, destination id, publish policy, transform policy, optional link policy, transformer resolver, transfer policy, path mapping mode, destination bundle path, existing destination state, and whether explicit force was requested for the current run.
 
-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.
+Output is a plan with an action, reason, optional primary URL, 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.
+Supported actions are `publish_new`, `replace_older`, `force_replace`, `skip_same`, `skip_destination_newer`, `fail_conflict`, and `fail_unmanaged`.
+
+## Failure behavior
+
+Planning fails when request fields are incomplete, publish and transform policies are invalid, selected outputs collide, HTML output is requested without Markdown inputs, destination state is invalid, destination content is unmanaged without force, or transfer policy maps the comparison outcome to failure.
+
+Execution fails if a write, delete, state serialization, or context check fails. Outputs written during a failed publish attempt are cleaned up through managed deletion where possible.
 
 ## Boundaries
 
-The current implementation publishes source files and Markdown-to-HTML sidecar outputs. Remote backend execution is not implemented.
+The package publishes source files and Markdown-to-HTML outputs. Markdown sidecar mode writes same-directory `.html` outputs, and Markdown index mode writes `index.html`. Backend behavior is supplied through `internal/storage`; app runtime supplies local, SSH, and S3 backends.
 
-The package uses `internal/state` for destination comparison, `internal/storage` for IO, and the shared `internal/config` publish/transform policy helper for request validation. It resolves transforms through a narrow resolver supplied by the caller; concrete transform registration is owned by the app layer. It does not parse CLI flags or load config files.
+The package uses `internal/state` for destination comparison, `internal/storage` for IO, and the shared `internal/config` publish/transform policy helper for request validation. It resolves transforms through a narrow resolver supplied by the caller; concrete transform registration is owned by the app layer. It does not parse CLI flags, load config files, or choose which source bundles a destination receives.
+
+The package owns projection from planned publish outputs to destination state output records and managed destination output paths. App JSON results and notification events keep their own schemas, but may use the publish output projection to avoid field-mapping drift.
+
+The app layer computes the destination bundle path before planning. `preserve_relative` destinations pass the source-root-relative bundle path. `fixed` destinations pass an empty destination bundle path, which means the destination backend root, and pass only the newest selected source bundle for that destination.
+
+When link config is present, publish planning builds per-output URLs from `links.base_url`, the destination bundle path, and each output path. `index.html` outputs use directory-style URLs. The primary URL is selected from planned outputs according to the destination primary policy.
 
 ## 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.
+Normal replacement deletes only outputs recorded in existing destination state plus `.distributor.json`. Forced replacement deletes the bounded destination bundle path before writing outputs and state. Failed writes trigger cleanup of outputs written during the failed attempt where practical.
 
 ## Tests
 
-Before changing publish behavior, inspect tests under `internal/publish` and local run tests under `internal/app`.
+Before changing publish behavior, inspect tests under `internal/publish` and run tests under `internal/app`.
+
+## Invariants
+
+- Publish planning is deterministic for the same source, destination state, policies, and transform outputs.
+- Destination bundle paths are caller-supplied and are interpreted relative to the destination backend root.
+- URL generation uses URL path semantics and does not infer public URLs from backend configuration.
+- Normal replacement deletes only managed paths recorded in existing state plus `.distributor.json`.
+- Forced replacement is explicit per run and deletes only within the destination bundle path.
+- Publish execution writes destination state after selected outputs are written.
+- Transform implementations are resolved through an interface supplied by the caller.
+- Unmanaged destination content is overwritten only by explicit forced replacement.

docs/internal/state.md

@@ -19,18 +19,24 @@ Input is JSON destination state plus the current source manifest, pipeline id, d
 - `source.manifest`
 - `outputs`
 
-`distributor_version` is optional diagnostic metadata. `published_at` parses as RFC3339 and distributor-written state serializes it as RFC3339 UTC.
+`distributor_version` is optional diagnostic metadata. `links` is optional URL metadata. `published_at` parses as RFC3339 and distributor-written state serializes it as RFC3339 UTC.
 
 The embedded `source.manifest` is validated with the same source manifest rules used by `internal/bundle`.
 
 ## Outputs
 
-Each output records `path`, `kind`, `source_path`, `sha256`, and `size`. Supported output kinds are `source` and `generated`. Generated outputs require `transform`.
+Each output records `path`, `kind`, `source_path`, `sha256`, and `size`. Supported output kinds are `source` and `generated`. Generated outputs require `transform`. Outputs may record `url` when the destination has link generation configured.
+
+The optional top-level `links.primary_url` records the selected primary URL for the published destination bundle. It is omitted when link generation is not configured or when the destination primary policy has no matching output.
 
 ## Comparison
 
 Comparison outcomes cover absent destination state, unmanaged destination content, invalid state, pipeline or destination mismatch, same source manifest, older destination source, newer destination source, same-created digest conflict, and different source id conflict.
 
+## Failure behavior
+
+Invalid JSON, invalid state schema, invalid embedded source manifests, unsafe output paths, invalid stored URLs, unsupported output kinds, missing generated-output transform names, and mismatched pipeline or destination ids produce comparison outcomes that publish planning can turn into fail actions. Supported identity and source-manifest conflicts can become forced replacement only when publish planning receives explicit force and compatible transfer policy.
+
 ## Boundaries
 
 This package does not publish files, delete files, inspect storage backends, or choose transfer policy actions. Publish planning consumes these comparison outcomes later.
@@ -38,3 +44,12 @@ This package does not publish files, delete files, inspect storage backends, or
 ## Tests
 
 Before changing destination state behavior, inspect tests under `internal/state`.
+
+## Invariants
+
+- `.distributor.json` is the destination sentinel and state record.
+- Embedded source manifests use the same validation rules as source bundles.
+- Generated outputs always record a transform id.
+- Stored URLs are optional and must be absolute HTTP or HTTPS URLs when present.
+- Comparison returns outcomes and reasons; it does not mutate storage.
+- `distributor_version` is diagnostic metadata, not a comparison key.

docs/internal/storage.md

@@ -6,7 +6,7 @@
 
 ## Inputs and outputs
 
-The storage interface supports byte reads, stream reads, byte writes, stream writes, exact metadata lookup, traversal, destination emptiness checks, and guarded managed deletion.
+The storage interface supports byte reads, stream reads, byte writes, stream writes, exact metadata lookup, traversal, destination emptiness checks, guarded managed deletion, and bounded prefix deletion for explicit forced replacement.
 
 Entries report a logical path, type, and size when available. Entry types are `file`, `directory`, `symlink`, and `other`.
 
@@ -14,7 +14,7 @@ Entries report a logical path, type, and size when available. Entry types are `f
 
 Core packages should depend on `internal/storage`, not adapter packages. Adapter-specific path handling stays behind backend implementations.
 
-The local adapter lives in `internal/adapters/local`. Runtime backend construction is wired through the app-level backend factory and storage registry. The fake backend lives in `internal/storage/fake` for tests and is not registered for runtime use.
+The local adapter lives in `internal/adapters/local`. The SSH/SFTP adapter lives in `internal/adapters/ssh`. The S3-compatible adapter lives in `internal/adapters/s3`. Runtime backend construction is wired through the app-level backend factory and storage registry. The fake backend lives in `internal/storage/fake` for tests and is not registered for runtime use.
 
 ## Paths
 
@@ -24,9 +24,36 @@ Logical file paths must be non-empty, relative, clean, slash-separated, and must
 
 Storage errors use typed categories such as not found, already exists, invalid path, conflict, permission, temporary, unsupported, and unknown. Callers should use helper predicates rather than matching error strings.
 
+Backends may wrap implementation-specific errors, but callers should receive storage errors where practical. Traversal can stop cleanly with `ErrStopWalk`.
+
+## Traversal helpers
+
+Backends own their traversal mechanics. The local adapter owns filesystem walking, the SSH adapter owns SFTP directory walking, and the S3 adapter owns object listing and pagination.
+
+`internal/storage` owns the shared callback emission rules used by backends:
+
+- context cancellation is checked before callback emission;
+- `WalkOptions.Limit` bounds the number of emitted entries;
+- `ErrStopWalk` stops traversal without becoming a caller-visible error;
+- callback errors are wrapped as storage walk errors.
+
+`storage.HasAny(ctx, backend, prefix)` provides the shared destination-content check. It calls `Walk` with non-recursive, limit-one traversal and stops after the first emitted entry.
+
 ## Deletion
 
-Backends expose guarded managed deletion only. `DeleteManagedBundle` may delete listed managed outputs plus `.distributor.json`; it does not provide broad recursive deletion.
+`DeleteManagedBundle` may delete listed managed outputs plus `.distributor.json`.
+
+`DeletePrefix` removes content at and below a logical prefix for explicit forced replacement. It must not delete above the requested prefix or above the configured backend root.
+
+## Local, SSH, S3, and fake backends
+
+The local adapter maps logical paths to a configured filesystem root and keeps adapter-specific path handling behind the storage interface.
+
+The SSH adapter maps logical paths to a configured remote SFTP root. It uses native SSH and SFTP libraries, supports SSH agent and key-file authentication, applies host-key policies, rejects unsafe logical paths, reports symlink entries from `Lstat`, and limits deletion to managed targets or explicit bounded prefixes.
+
+The S3 adapter maps logical paths to object keys below a configured bucket and optional prefix. It uses the AWS SDK for Go v2, treats prefixes as object trees, requires exact objects for `Stat`, paginates traversal, applies conservative overwrite checks with `HeadObject`, infers basic content types, and limits deletion to managed target objects or explicit bounded object-key prefixes.
+
+The fake backend is an in-memory implementation for package tests. It is not registered for runtime use.
 
 ## Tests
 
@@ -35,3 +62,14 @@ Before changing storage behavior, inspect tests under:
 - `internal/storage`
 - `internal/storage/fake`
 - `internal/adapters/local`
+- `internal/adapters/ssh`
+- `internal/adapters/s3`
+
+## Invariants
+
+- Core packages depend on `internal/storage`, not concrete adapters.
+- Logical paths are slash-separated and confined to the backend root.
+- `storage.List` uses backend traversal and returns deterministic entries.
+- Managed deletion is limited to recorded outputs plus `.distributor.json`.
+- Prefix deletion is limited to the requested logical prefix.
+- Runtime backend registration is owned by `internal/app`.

docs/internal/transform.md

@@ -2,18 +2,28 @@
 
 ## Purpose
 
-`internal/transform` defines generated publication artifacts. `internal/transform/markdown` implements Markdown-to-HTML sidecar generation.
+`internal/transform` defines generated publication artifacts. `internal/transform/markdown` implements Markdown-to-HTML generation.
 
 ## Inputs and outputs
 
-Inputs are a validated source bundle and source backend. Outputs include destination path, source path, transform id, generated bytes, SHA-256, and size.
+Inputs are a validated source bundle, source backend, and transform options supplied by publish planning. Outputs include destination path, source path, transform id, generated bytes, SHA-256, and size.
+
+## Registry
+
+`internal/transform` defines the transform interface and registry. The app layer registers the Markdown implementation; publish planning receives only a resolver.
 
 ## Markdown behavior
 
-Markdown files ending in `.md` generate `.html` files in the same logical directory. Non-Markdown files do not generate outputs. Raw HTML embedded in Markdown is not passed through by the renderer.
+Markdown sidecar mode renders files ending in `.md` to `.html` files in the same logical directory. Markdown index mode renders one selected manifest-listed Markdown file to `index.html`. Non-Markdown files do not generate sidecar outputs. Raw HTML embedded in Markdown is not passed through by the renderer.
 
 Generated HTML is deterministic for the same source content and transform configuration.
 
+See `docs/integrations/markdown.md` for the Goldmark integration contract.
+
+## Failure behavior
+
+Transform resolution fails when a requested transform id is not registered. Markdown rendering fails when the source file cannot be read or rendered. Index input selection fails when the configured input is unsafe, not listed, not Markdown, or when no configured input can be inferred from exactly one manifest-listed Markdown file. Publish planning fails when HTML output is requested and the selected transform produces no outputs for a bundle.
+
 ## Boundaries
 
 Transforms do not publish files, mutate source bundles, or write destination state. Publish planning selects and writes transform outputs.
@@ -22,4 +32,16 @@ The app layer owns default transform registration. The transform package does no
 
 ## Tests
 
-Before changing transform behavior, inspect tests under `internal/transform`.
+Before changing transform behavior, inspect tests under:
+
+- `internal/transform`
+- `internal/transform/markdown`
+
+## Invariants
+
+- Source bundle files are never mutated by transforms.
+- Generated outputs record destination path, source path, transform id, SHA-256, and size.
+- Markdown sidecar naming changes only the `.md` extension to `.html`.
+- Markdown index mode always writes `index.html`.
+- Non-Markdown source files do not generate Markdown outputs.
+- Transform registration stays outside publish planning.

docs/operations.md

@@ -1,6 +1,12 @@
 # Distributor Operations
 
-## Normal workflow
+## Normal Workflow
+
+Validate a source bundle:
+
+```sh
+go run ./cmd/distributor validate examples/source-bundle
+```
 
 Preview a local publication:
 
@@ -20,30 +26,308 @@ Run the local HTML publication:
 go run ./cmd/distributor run --config examples/local-html.yml
 ```
 
-## Filesystem layout
+Run the local `index.html` publication:
 
-Source bundles are discovered beneath the configured local source root. Destination bundle paths preserve the source bundle path relative to that source root.
+```sh
+go run ./cmd/distributor run --config examples/local-index.yml
+```
 
-The maintained example writes under `workspace/`, which is ignored by Git.
+Preview local fan-out publication:
 
-## Destination state
+```sh
+go run ./cmd/distributor run --config examples/fan-out.yml --dry-run
+```
 
-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`.
+Preview local archive-plus-latest publication:
+
+```sh
+go run ./cmd/distributor run --config examples/archive-and-latest.yml --dry-run
+```
+
+Preview a run for automation:
+
+```sh
+go run ./cmd/distributor run --config examples/fan-out.yml --dry-run --format json
+```
+
+Preview an environment-gated SSH destination config after editing it for an SSH/SFTP endpoint you control:
+
+```sh
+go run ./cmd/distributor run --config examples/ssh-destination.yml --dry-run
+```
+
+Preview an environment-gated S3 destination config after editing it for an S3-compatible endpoint and bucket you control:
+
+```sh
+go run ./cmd/distributor run --config examples/s3-destination.yml --dry-run
+```
+
+Validate one configured source without opening destinations:
+
+```sh
+go run ./cmd/distributor validate --config examples/local-publish.yml --pipeline example-source-bundle
+```
+
+## Filesystem Layout
+
+Source bundles are discovered beneath the configured source root. Each bundle is a directory containing `manifest.json`.
+
+Destination bundle paths are configured per destination with `path_mapping.mode`.
+
+The default mode, `preserve_relative`, preserves the source bundle path relative to the source root. A source bundle at the source root publishes to the destination root. A source bundle under `daily/` publishes under `daily/` at that destination.
+
+The `fixed` mode publishes one selected source bundle at the destination backend root. A fixed destination with local `path: /srv/www/reports/latest` writes outputs and `.distributor.json` directly under `/srv/www/reports/latest`. Fixed destinations select the newest discovered source bundle by manifest `created` timestamp, with the source-root-relative bundle path as the deterministic tie-breaker.
+
+The maintained local examples write under `workspace/`, which is ignored by Git.
+
+SSH backends use the configured remote `path` as the backend root. Source bundle discovery and destination bundle paths are relative to that root, using the same logical path rules as local storage.
+
+S3 backends use the configured bucket plus optional `prefix` as the backend root. Source bundle discovery and destination bundle paths are relative to that object-key prefix. Prefixes are object-key prefixes, not real directories.
+
+## Destination State
+
+Each published destination bundle contains `.distributor.json`. This file is the managed sentinel and destination state record. It stores:
+
+- pipeline and destination identity;
+- publication timestamp;
+- source manifest used for publication;
+- copied source output metadata;
+- generated output metadata;
+- optional public URL metadata when destination links are configured.
 
 `manifest.json` from the source bundle is not copied as destination state.
 
-## Retry behavior
+Do not edit `.distributor.json` by hand during normal operation. If it is missing or invalid while destination files remain, `distributor` treats the destination as unmanaged or conflicted.
 
-If a destination already has matching `.distributor.json`, publication skips it as already published.
+## Go Producer Bundles
 
-If destination state is older than the source manifest, publication replaces only managed outputs recorded in `.distributor.json` plus the state file.
+Go producer applications can import `gitea.maximumdirect.net/eric/distributor/pkg/bundle` to create complete local source bundles with the same path, digest, timestamp, and validation rules used by `distributor`. The package also exposes digest helpers, including `ValidateDigest`, for producer code that needs to validate lowercase `sha256:<64 hex>` strings before writing manifests.
 
-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.
+Minimal producer-side bundle creation:
 
-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.
+```go
+manifest, err := bundle.WriteBundle(bundle.WriteBundleOptions{
+    Root:  outputDir,
+    ID:    "reports.example.2026-05-30",
+    Files: []bundle.BundleFile{
+        {SourcePath: reportPath, Path: "report.md"},
+        {SourcePath: summaryPath, Path: "summary.txt"},
+    },
+})
+if err != nil {
+    return err
+}
+```
 
-After a successful publish or replacement, the internal notifier hook runs as a no-op. Skipped destinations do not invoke it.
+`WriteBundle` copies local producer files into a sibling temporary directory, writes `manifest.json`, validates the result, and promotes the completed bundle into place. It fails if `Root` already exists unless `Overwrite` is true. With overwrite enabled, it builds and validates the replacement before moving the existing root aside.
+
+Use `BuildManifest` and `WriteManifest` when a producer already wrote all bundle files into the final root. `BuildManifest` can preserve an explicit file order, or `Scan: true` can recursively include regular files under `Root` in deterministic slash-path order. Scan mode includes dotfiles, excludes files named `manifest.json` or `.distributor.json`, and rejects symlinks.
+
+Shell producers can create the same manifest through the CLI after writing bundle files:
+
+```sh
+go run ./cmd/distributor manifest create <bundle-path> --id reports.example.2026-05-30
+go run ./cmd/distributor validate <bundle-path>
+```
+
+Use repeated `--file` flags to preserve a specific file order. If no `--file` flags are provided, the command scans the bundle directory recursively using the same filtering rules as `pkg/bundle.BuildManifest`.
+
+## Static HTML Publication
+
+Markdown-to-HTML publication can write sidecar files or a fixed `index.html`.
+
+Use sidecar mode when each Markdown source should keep a matching HTML filename:
+
+```yaml
+publish:
+  source: false
+  html: true
+transform:
+  markdown_to_html:
+    enabled: true
+    mode: sidecar
+```
+
+Use index mode for static-site destinations that should serve a bundle through `index.html`:
+
+```yaml
+publish:
+  source: false
+  html: true
+transform:
+  markdown_to_html:
+    enabled: true
+    mode: index
+    input: report.md
+```
+
+If `input` is omitted in index mode, the source manifest must list exactly one Markdown file. Generated HTML is recorded in `.distributor.json` with `kind: generated`, `source_path`, `transform: markdown_to_html`, digest, and size metadata.
+
+## Archive And Latest Fan-Out
+
+A pipeline can publish the same source to an archive destination and a stable latest destination:
+
+```yaml
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: /var/spool/distributor/reports
+    destinations:
+      - id: archive
+        backend: local
+        path: /srv/reports/archive
+        path_mapping:
+          mode: preserve_relative
+        publish:
+          source: true
+          html: false
+      - id: latest-html
+        backend: local
+        path: /srv/www/reports/latest
+        path_mapping:
+          mode: fixed
+        links:
+          base_url: https://reports.example.com/latest
+          primary: auto
+        publish:
+          source: false
+          html: true
+        transform:
+          markdown_to_html:
+            enabled: true
+            mode: index
+            input: report.md
+```
+
+The archive destination plans every discovered source bundle at its source-relative path. The fixed latest destination plans only the newest discovered bundle and writes `index.html` plus `.distributor.json` at its backend root.
+
+## Static Site URLs
+
+Use destination `links` when a destination backend root corresponds to a public HTTP or HTTPS URL:
+
+```yaml
+links:
+  base_url: https://reports.example.com/archive
+  primary: auto
+```
+
+Distributor records URLs in `.distributor.json`; it does not publish notifications or infer URLs from local, SSH, or S3 backend fields.
+
+For archive-style destinations, URLs include the destination bundle path. A source bundle under `daily/brentwood/2026-06-01` with `base_url: https://reports.example.com/archive` can produce:
+
+```text
+https://reports.example.com/archive/daily/brentwood/2026-06-01/report.html
+```
+
+For fixed destinations, URLs are rooted at `links.base_url`. A fixed HTML index destination with `base_url: https://reports.example.com/latest` records:
+
+```text
+https://reports.example.com/latest/
+```
+
+`index.html` outputs use directory-style URLs. Other outputs include their filename. The primary URL is selected from the published outputs using the destination `links.primary` policy.
+
+## Source Validation and Inspection
+
+`validate` and `inspect` can operate on a local path or on one configured pipeline source. Configured source mode requires both `--config` and `--pipeline`; it loads the normal config, resolves `secrets.directory`, opens only the selected source backend, and does not open any destinations.
+
+Configured source validation is useful when producers write directly to SSH or S3 storage:
+
+```sh
+go run ./cmd/distributor validate --config <config-path> --pipeline <pipeline-id>
+go run ./cmd/distributor inspect --config <config-path> --pipeline <pipeline-id>
+```
+
+Use `--bundle <path>` to validate or inspect one source-root-relative bundle directory:
+
+```sh
+go run ./cmd/distributor validate \
+  --config <config-path> \
+  --pipeline <pipeline-id> \
+  --bundle daily/2026-06-01
+```
+
+For configured SSH sources, host key and authentication behavior matches `run`. For configured S3 sources, endpoint, bucket, prefix, region, path-style, explicit credential environment variables, and `secrets.directory` handling match `run`.
+
+## Dry Runs
+
+`--dry-run` loads and validates config, discovers source bundles, inspects destination state, plans outputs, and prints summary lines. It does not write output files, destination state, or SSH `known_hosts` entries.
+
+Dry-run output is useful before publishing to confirm actions such as `publish_new`, `replace_older`, `force_replace`, `skip_same`, and `skip_destination_newer`.
+
+Destination action lines include the destination backend, so mixed local, SSH, and S3 fan-out runs can be audited before publication. Fixed path destinations add `path_mapping=fixed target=.` to planned action lines. Dry-run also prints a warning with the fixed destination candidate count and selected source bundle; destructive fixed replacements print an additional warning that the destination root would be replaced.
+
+Use `--format json` when another process needs stable run data. JSON output includes warnings, pipeline summaries, destination actions, destination bundle paths, path mapping modes, optional link URLs, output records, final counters, and partial failure records. The summary includes `fixed_path`. If one destination fails after planning or execution begins, JSON output still contains the successful and failed destination records with `ok: false`, and the command exits non-zero.
+
+## Retry and Replacement Behavior
+
+If a destination has matching `.distributor.json`, publication skips it as already published.
+
+If destination state is older than the source manifest and transfer policy allows replacement, publication deletes only managed outputs recorded in `.distributor.json` plus the state file, then writes the new outputs and state.
+
+If destination state is newer than the source manifest, the default behavior is to skip. If destination state has the same source id and created timestamp but a different digest, publication fails as a conflict.
+
+If a destination path has files but no valid `.distributor.json`, publication fails as unmanaged content unless the current run explicitly uses `--force`.
+
+## Force Workflow
+
+Use `--force` only after a dry run shows the intended `force_replace` action:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run --force
+go run ./cmd/distributor run --config <config-path> --force
+```
+
+Forced replacement can overwrite unmanaged non-empty destination paths. Destination state conflicts require `transfer.on_conflict: replace` plus `--force`. Newer destination state requires `transfer.on_destination_newer: replace` plus `--force`.
+
+Forced replacement deletes the current destination bundle path before writing outputs and state. It does not delete above that bundle path. For fixed destinations, the destination bundle path is the backend root, so forced replacement may clear that configured root but not its parent path, sibling directories, or anything outside the configured S3 bucket and prefix. Force is per run only and has no config default.
+
+## Failure Handling
+
+If one destination fails in a fan-out run, independent later destinations are still planned and executed. The command exits non-zero after printing the final status if any destination failed.
+
+Errors include the pipeline id, destination id, destination backend, and bundle path where applicable.
+
+In JSON mode, destination failures after planning or execution begins are reported in the top-level `errors` array and in the run result while preserving a non-zero exit code. Fatal setup errors such as an unreadable config or invalid secrets directory write no JSON document.
+
+If a write fails during publication, `distributor` attempts to remove outputs written during that failed attempt so a retry does not see those partial outputs as unmanaged destination content.
+
+After a successful publish or replacement, the internal notifier hook runs. The current default notifier is a no-op. Skipped destinations do not invoke it.
+
+## SSH Operation Notes
+
+SSH execution uses SFTP over `golang.org/x/crypto/ssh` and `github.com/pkg/sftp`. It does not shell out to `ssh`, `scp`, or `rsync`.
+
+Configure `ssh_key_file`, an SSH agent, or both. Agent identities are attempted first, followed by the configured key file. YAML password authentication is not supported.
+
+The default host key policy is `accept-new`. New host keys are written to `known_hosts` when the file path is writable. During `--dry-run`, unknown host keys may be accepted for the current connection but are not written to `known_hosts`; a later non-dry-run may persist the same key. Changed host keys are fatal for both `strict` and `accept-new`. The `off` policy disables host key checking and `run` prints a warning when stdout is enabled.
+
+Recovery boundaries are the same as local storage: replacement deletes only managed output paths recorded in `.distributor.json` plus the state file, and failed writes are cleaned up where practical. Distributor never performs broad recursive remote deletion.
+
+## S3 Operation Notes
+
+S3 execution uses the AWS SDK for Go v2. Configure `endpoint`, `bucket`, optional `prefix`, optional `region`, and optional explicit credential environment variable names.
+
+When explicit credential env names are configured, both variables must resolve to non-empty values through the real process environment or `secrets.directory`. When they are omitted, the AWS SDK default credential chain is used as-is.
+
+Normal replacement and failed-write cleanup delete only managed output objects recorded in `.distributor.json` plus the state object. Forced replacement deletes objects under the bounded destination bundle prefix. For fixed destinations, that prefix is the configured bucket plus optional `prefix`. Distributor does not manage bucket versioning or delete markers.
+
+## Secrets Directory
+
+Configure `secrets.directory` when credential values should come from mounted files, such as deployment secrets:
+
+```yaml
+secrets:
+  directory: /run/secrets/distributor
+```
+
+The directory is loaded during `run` and configured-source `validate` or `inspect` before any backend is opened. If the directory is missing, unreadable, or contains an invalid secret filename, the command fails before storage work starts.
+
+Real process environment values take precedence over files with the same name. If the values differ and stdout is enabled, `run` and configured-source diagnostics print a warning naming the ignored secret file variable without printing either value. The process environment is not changed.
 
 ## Caveats
 
-Only local-to-local publication is implemented. SSH, S3, external notification adapters, and force overwrite behavior are not implemented.
+External notification adapters are unavailable. Force overwrite behavior is available only through the explicit `run --force` workflow.
+
+For symptom-oriented fixes, see [troubleshooting](troubleshooting.md). For config details, see [configuration](config.md). For command syntax, see [CLI](cli.md).

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,25 +16,27 @@ 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;
 3. discover source bundles beneath the source root;
 4. validate each source bundle and its `manifest.json`;
-5. for each configured destination, inspect destination state;
-6. compare source state to destination state;
-7. build a publish plan;
-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.
+5. select the source bundle or bundles for each destination according to that destination's path mapping policy;
+6. open each destination backend independently;
+7. inspect destination state at the resolved destination bundle path;
+8. compare source state to destination state;
+9. build a publish plan that selects source files, generated files, destination paths, and optional public URLs;
+10. optionally transform Markdown to HTML for that destination;
+11. publish selected source and generated artifacts;
+12. write `.distributor.json` as the destination sentinel/state file;
+13. run the notification hook, whose default implementation is currently a no-op.
 
 ## 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, path mapping, publication policy, transform policy, public link policy, replacement behavior, state, and notification behavior.
 
 The pipeline model is fan-out by design:
 
@@ -45,7 +47,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
 
@@ -53,7 +55,7 @@ A source bundle is a directory containing `manifest.json`.
 
 `manifest.json` is the sole producer-to-`distributor` contract. `distributor` must not rely on producer-specific work directory layouts, filenames, metadata, or conventions outside the configured source root and the source manifest.
 
-The MVP source manifest schema is intentionally minimal:
+The source manifest schema is intentionally minimal:
 
 ```json
 {
@@ -73,7 +75,7 @@ The MVP source manifest schema is intentionally minimal:
 
 Required fields:
 
-- `schema_version`: source manifest schema version. MVP value: `1`.
+- `schema_version`: source manifest schema version. Current value: `1`.
 - `id`: stable bundle identifier.
 - `digest`: SHA-256 digest for the listed files.
 - `created`: RFC3339 timestamp. UTC is preferred; explicit offsets are allowed.
@@ -101,6 +103,7 @@ Each destination bundle path is managed by `.distributor.json`. This file is bot
 - the normalized source manifest used for publication;
 - metadata for copied source outputs;
 - metadata for generated outputs, such as HTML files;
+- optional URL metadata for published outputs;
 - any additional metadata required by `distributor`.
 
 A representative destination state file is:
@@ -127,14 +130,18 @@ A representative destination state file is:
       ]
     }
   },
+  "links": {
+    "primary_url": "https://reports.example.com/weather-daily/"
+  },
   "outputs": [
     {
-      "path": "report.html",
+      "path": "index.html",
       "kind": "generated",
       "source_path": "report.md",
       "transform": "markdown_to_html",
       "sha256": "sha256:...",
-      "size": 23456
+      "size": 23456,
+      "url": "https://reports.example.com/weather-daily/"
     }
   ]
 }
@@ -157,6 +164,8 @@ Transforms are configured per destination. A destination may receive source file
 
 The MVP supports only Markdown-to-HTML transformation. HTML generation must not mutate the source bundle. Generated outputs must be deterministic from the source bundle and destination transform configuration, and must be recorded in `.distributor.json`.
 
+Destination path mapping and public link generation are destination behavior. Source manifests do not declare where a bundle is published or which public URLs are recorded.
+
 The application should distinguish:
 
 - transform policy: how derived files are generated;
@@ -166,13 +175,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, SSH/SFTP, and S3-compatible backends. 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,14 +193,16 @@ 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.
+- `pkg/bundle`: public producer-facing source manifest model, digest logic, parsing, manifest building, complete local bundle writing, and local validation helpers.
 - `internal/app`: application orchestration and top-level use cases.
 - `internal/cli`: CLI command definitions, flags, argument parsing, and command wiring.
 - `internal/config`: configuration structs, defaults, loading, precedence, and validation.
-- `internal/bundle`: source manifest parsing, source bundle discovery, source digest validation, and source bundle model.
+- `internal/bundle`: storage-backed source bundle discovery and validation over the public manifest contract.
 - `internal/state`: `.distributor.json` parsing, validation, comparison, and output metadata.
+- `internal/link`: shared HTTP URL validation for configured and persisted link 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.
@@ -202,6 +213,8 @@ Use this layout unless the project has a documented reason to differ:
 - `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
@@ -226,17 +239,20 @@ Pipeline configuration should express:
 - pipeline id;
 - one source backend;
 - one or more destinations;
+- per-destination path mapping;
 - per-destination publish policy;
 - per-destination transform policy;
+- per-destination public link policy;
 - validation behavior;
 - destination conflict/replacement behavior.
 
-## Modules, Stages, and Registries
+## Modules and Registries
 
-Each major stage should have an explicit input/output contract:
+Each major workflow step should have an explicit input/output contract:
 
 - source discovery;
 - source validation;
+- destination bundle selection;
 - destination state inspection;
 - destination comparison;
 - transform planning/execution;
@@ -244,9 +260,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 +280,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
 
@@ -272,9 +288,11 @@ If the application writes durable state, writes should be atomic where practical
 
 Code that deletes, moves, or overwrites files must use narrow, explicit paths. Avoid broad parent-directory operations. Cleanup that can cause data loss must be opt-in.
 
-`distributor` must never perform broad deletion against a configured source root or destination root. Destructive replacement may occur only inside a resolved destination bundle path when a valid `.distributor.json` confirms that the path is distributor-managed.
+`distributor` must never perform broad deletion against a configured source root. Destination deletion must be bounded to the resolved destination bundle path for the current source bundle and backend root.
 
-Replacement must be narrow, logged, test-covered, and configurable. Prefer deleting files recorded in `.distributor.json` and known generated outputs rather than blindly deleting parent directories. Backend implementations must guard against path traversal, prefix confusion, and accidental root deletion.
+Normal destructive replacement may occur only when a valid `.distributor.json` confirms that the destination bundle path is distributor-managed. Explicit forced replacement is a per-run CLI workflow for supported conflict and unmanaged-content cases; it must be dry-runnable, clearly reported, and constrained to the destination bundle path.
+
+Replacement must be narrow, reported, test-covered, and configurable. Prefer normal replacement that deletes files recorded in `.distributor.json` and known generated outputs. Forced replacement may delete a bounded destination bundle prefix only when the operator explicitly requests it. Backend implementations must guard against path traversal, prefix confusion, and accidental deletion above the configured backend root.
 
 Where practical, publish operations should use staging paths or temporary objects and promote them into place only after validation and transform steps succeed.
 
@@ -282,7 +300,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:
 
@@ -293,17 +311,19 @@ Important tests include:
 - relative path safety and path traversal rejection;
 - destination `.distributor.json` parsing and comparison;
 - same/older/newer/conflict publish decisions;
+- destination bundle path mapping;
 - destructive replacement safety checks;
 - transform output planning and metadata recording;
+- public URL planning and state metadata;
 - 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 +341,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.

docs/policy/development.md

@@ -1 +1,211 @@
-# Not yet implemented
+# Development Policy
+
+This document defines the day-to-day development workflow for `distributor`.
+Use it with `docs/policy/architecture.md` and `docs/policy/documentation.md`.
+
+## Repository Layout
+
+- `cmd/distributor`: executable entrypoint only.
+- `pkg/bundle`: public producer-facing source manifest and local bundle writer helpers.
+- `internal/app`: top-level use cases for `run`, `validate`, and `inspect`.
+- `internal/cli`: standard-library command parsing, flags, help text, and command wiring.
+- `internal/config`: YAML configuration structs, loading, defaults, and validation.
+- `internal/bundle`: storage-backed source bundle discovery and validation using the public manifest contract.
+- `internal/state`: destination `.distributor.json` parsing, validation, and comparison.
+- `internal/storage`: backend interface, registry, logical path rules, typed errors, and shared storage helpers.
+- `internal/adapters/local`: local filesystem backend.
+- `internal/adapters/ssh`: SSH/SFTP backend.
+- `internal/adapters/s3`: S3-compatible object storage backend.
+- `internal/storage/fake`: in-memory backend for tests.
+- `internal/publish`: destination inspection, output planning, reconciliation, execution, managed cleanup, and explicit forced replacement.
+- `internal/transform`: transform interface and registry.
+- `internal/transform/markdown`: Markdown-to-HTML transform.
+- `internal/notify`: notification interface and current no-op notifier.
+- `internal/testutil`: shared test fixtures. Production code must not import this package.
+- `docs`: current user, operator, policy, internal, and roadmap documentation.
+- `examples`: copyable example configs and source bundles.
+
+Do not create new top-level package families such as public `pkg/...` packages
+beyond `pkg/bundle`, generic workflow containers, or service-specific adapter
+directories unless the architecture policy or a current roadmap explicitly
+calls for them.
+
+## Common Commands
+
+Run the full test suite:
+
+```bash
+go test ./...
+```
+
+Run targeted packages while developing:
+
+```bash
+go test ./internal/config
+go test ./internal/cli ./internal/app
+go test ./internal/publish ./internal/state
+go test ./internal/transform/markdown
+```
+
+Run the CLI against an example config:
+
+```bash
+go run ./cmd/distributor run --config examples/local-publish.yml --dry-run
+```
+
+Validate or inspect a local source bundle:
+
+```bash
+go run ./cmd/distributor validate examples/source-bundle
+go run ./cmd/distributor inspect examples/source-bundle
+```
+
+If Go cache permissions fail in a restricted environment, use workspace-safe
+temporary caches:
+
+```bash
+GOCACHE=/private/tmp/distributor-gocache GOMODCACHE=/private/tmp/distributor-gomodcache go test ./...
+```
+
+## Coding Conventions
+
+- Keep the application small, explicit, and dependency-light.
+- Prefer package-local helpers over broad abstractions until behavior is shared by multiple packages.
+- Keep CLI parsing in `internal/cli`; business decisions belong in `internal/app`, `internal/bundle`, `internal/publish`, `internal/state`, and related core packages.
+- Keep adapter packages thin. Backend-specific filesystem or service behavior belongs in adapters; bundle, state, transform, and publish policy belongs outside adapters.
+- Preserve public CLI behavior, config semantics, manifest schema, destination state schema, and implemented backend behavior unless the current task explicitly changes them.
+- Use `storage.DisplayPath`, `storage.StateFileName`, `storage.StatePath`, and `storage.ManagedBundleTargets` instead of duplicating those conventions.
+- Use `pkg/bundle` for normalized source manifest semantics. Internal packages should reach those rules through `internal/bundle` when they also need storage-backed bundle discovery or validation.
+- Use `config.ValidatePublishTransformPolicy` for publish and transform policy combinations.
+- Do not import concrete transform implementations from `internal/publish`; app-level wiring owns transform registration.
+- Do not import `internal/testutil` from production code.
+
+## Dependency Policy
+
+The project currently depends on:
+
+- `gopkg.in/yaml.v3` for YAML configuration loading.
+- `github.com/yuin/goldmark` for Markdown rendering.
+- `golang.org/x/crypto/ssh`, `golang.org/x/crypto/ssh/agent`, and `golang.org/x/crypto/ssh/knownhosts` for native SSH support.
+- `github.com/pkg/sftp` for native SFTP support.
+- `github.com/aws/aws-sdk-go-v2/...` packages for S3-compatible storage support.
+
+Add external dependencies only when they materially improve correctness,
+security, interoperability, or implementation complexity. Avoid dependencies
+for small conveniences. Do not let dependency-specific types leak across
+internal package boundaries unless that dependency is the explicit package
+contract.
+
+## Configuration Changes
+
+When adding or changing configuration:
+
+1. Update `internal/config/config.go` structs and YAML tags.
+2. Add defaults in `internal/config/defaults.go` only for built-in defaults.
+3. Add validation in `internal/config/validate.go` with clear field context.
+4. Update config load and validation tests.
+5. Update `docs/config.md` in the same change if current user-visible config behavior changes.
+6. Update examples only with configs that are valid and executable for implemented behavior.
+
+Config validation may accept fields for roadmap backends before execution
+support exists, but user-facing docs and examples must clearly state execution
+support. Runtime executable backends are local, SSH, and S3.
+
+Credential-consuming code must use the config-owned environment resolver for
+explicit credential environment variable references. Do not call `os.Getenv`
+directly for backend credentials, because `secrets.directory` values are
+intentionally available through the resolver without mutating the process
+environment.
+
+## CLI Changes
+
+The CLI is hand-written with the Go standard library. Do not introduce a CLI
+framework without a documented reason.
+
+When adding or changing commands or flags:
+
+1. Keep parsing and help text in `internal/cli`.
+2. Keep command work in `internal/app` or a lower-level package.
+3. Add or update CLI tests in `internal/cli`.
+4. Update `docs/cli.md` if syntax, flags, output expectations, or workflows change.
+
+`validate` and `inspect` support a local path shortcut and configured
+source-only diagnostics. `run` loads configured pipelines and executes local,
+SSH, and S3 backends.
+
+## Storage Backends
+
+Storage behavior is defined by `internal/storage.Backend` and shared path rules
+in `internal/storage`.
+
+When adding a backend:
+
+1. Implement the storage interface in an adapter package.
+2. Translate backend-specific errors into storage errors where practical.
+3. Keep bundle comparison, transform, routing, and replacement policy out of the adapter.
+4. Register runtime construction through app-level backend factory wiring.
+5. Add focused adapter tests and app-level wiring tests.
+6. Update user docs, operations docs, examples, and internal docs only for behavior that is actually implemented.
+
+Do not document future backend execution as available until the corresponding
+adapter package and app wiring exist.
+
+## Transforms
+
+Transforms use `internal/transform` interfaces and registry wiring.
+
+When adding or changing a transform:
+
+1. Keep the transform implementation in its own package under `internal/transform`.
+2. Register default runtime transforms from `internal/app`.
+3. Keep `internal/publish` dependent only on the transform interface or resolver.
+4. Record deterministic output metadata: path, source path, transform name, digest, and size.
+5. Add transform tests and app or publish tests for wiring and policy behavior.
+6. Update `docs/internal/transform.md` and any relevant integration docs for implemented behavior.
+
+## Tests
+
+Test close to the behavior being changed:
+
+- Use package tests for parsing, validation, comparison, planning, and adapter behavior.
+- Use `internal/app` and `internal/cli` tests for user-facing workflows.
+- Use `internal/testutil` for shared valid fixtures only; keep edge cases near the package under test.
+- Run `go test ./...` after cross-package changes or documentation/example changes tied to tests.
+
+Live integration tests must be opt-in and skipped during normal `go test ./...`
+unless their required environment variables are set. Test-only environment
+variables must use this prefix shape:
+
+```text
+DISTRIBUTOR_TEST_<BACKEND>_*
+```
+
+Examples include `DISTRIBUTOR_TEST_SSH_HOST` and
+`DISTRIBUTOR_TEST_S3_ENDPOINT`. Do not use production credential variable names
+for test-only controls.
+
+## Examples
+
+Examples under `examples/` must be valid, maintained, and free of secrets.
+They should be copyable for implemented behavior. Remote examples must use
+placeholders or environment variables for endpoint and credential material.
+
+When changing examples:
+
+1. Keep paths relative to the repository where practical.
+2. Keep local examples runnable without external services; gate remote examples
+   behind user-provided endpoints and credentials.
+3. Run `go test ./internal/config` because config tests load examples.
+4. Update README, CLI, or config docs if links or recommended workflows change.
+
+## Documentation
+
+Follow `docs/policy/documentation.md`.
+
+- Document implemented behavior outside `docs/roadmap/`.
+- Keep future, planned, or aspirational behavior under `docs/roadmap/`.
+- Keep `docs/config.md` canonical for user-facing config reference.
+- Keep `docs/cli.md` canonical for command syntax and workflows.
+- Keep `docs/operations.md` canonical for operational and recovery behavior.
+- Keep `docs/internal/` focused on implemented package contracts.
+- Update docs in the same change as behavior when public behavior, config, CLI, examples, or internal contracts change.

docs/policy/documentation.md

@@ -106,7 +106,7 @@ Recommended:
 - `examples/`
 - `docs/policy/development.md`
 
-### Modular, staged, service-oriented, or orchestration application
+### Modular, service-oriented, or orchestration application
 
 Required:
 - `docs/cli.md`, if CLI-based
@@ -175,7 +175,7 @@ It should include:
 - dependency policy;
 - how to add config fields;
 - how to add CLI flags;
-- how to add stages/modules/adapters, if applicable;
+- how to add modules or adapters, if applicable;
 - how to update examples;
 - documentation update expectations.
 
@@ -216,7 +216,7 @@ Explain when commands are useful, not just their syntax.
 
 **Audience:** administrators, operators
 
-Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures.
+Required for applications that maintain state, support resume behavior, run multi-step workflows, write durable artifacts, use remote storage, or require recovery procedures.
 
 It should cover:
 
@@ -248,7 +248,7 @@ Each entry should include:
 
 **Audience:** developers, LLM coding agents
 
-Required for modular, staged, service-oriented, or orchestration projects.
+Required for modular, service-oriented, or orchestration projects.
 
 This directory describes implemented internal components. It is not the roadmap.
 

docs/roadmap/audit.md

@@ -1,255 +0,0 @@
-# Code Quality and Deduplication Audit
-
-## 1. Executive summary
-
-The Stage 1-8 implementation is generally clean, modular, and close to the roadmap boundaries. The codebase is ready for a limited cleanup pass before remote backend work. I did not find evidence of a major architectural problem or a need for broad redesign.
-
-Top three refactoring targets:
-
-1. Runtime backend and transform resolution bypasses the registries already present in `internal/storage` and `internal/transform`.
-2. Source manifest validation semantics are split between `internal/bundle` and `internal/state`, and publish/transform policy is checked in both `internal/config` and `internal/publish`.
-3. Managed deletion target construction is duplicated in the local and fake storage backends and will otherwise be repeated in SSH/SFTP and S3 adapters.
-
-The recommended cleanup is a series of small, behavior-preserving commits. The public CLI, config schema, manifest schema, and destination state schema should remain stable.
-
-## 2. Repository map reviewed
-
-Reviewed implementation areas:
-
-- `cmd/distributor`: process entrypoint.
-- `internal/cli`: root command dispatch, `run`, `validate`, `inspect`, `version`, and CLI tests.
-- `internal/app`: run orchestration, validation, inspection, notification integration, and integration-style tests.
-- `internal/config`: config structs, defaults, YAML loading, validation, examples tests.
-- `internal/bundle`: manifest parsing, digest logic, discovery, validation, fixtures, and tests.
-- `internal/state`: `.distributor.json` parsing, validation, comparison, marshaling, and tests.
-- `internal/storage`: storage interface, path helpers, typed errors, registry, fake backend, and tests.
-- `internal/adapters/local`: local storage backend and tests.
-- `internal/publish`: plan, output selection, destination inspection, safety, execution, and tests.
-- `internal/transform` and `internal/transform/markdown`: transform interface, registry, Markdown-to-HTML implementation, and tests.
-- `internal/notify`: notifier interface and no-op implementation.
-- `internal/logging`: placeholder logging setup.
-- `examples`, `docs/config.md`, `docs/cli.md`, `docs/operations.md`, and `docs/internal/*`.
-
-Requested areas that do not currently exist as separate packages: `internal/stage`, `internal/modules`, `internal/validators`, `internal/artifacts`, `internal/manifest`, `internal/schema`, `internal/report`, and `pkg`.
-
-Major execution paths reviewed:
-
-- `distributor validate <path>`: CLI to app to local backend to bundle discovery and validation.
-- `distributor inspect <path>`: CLI to app to local backend to bundle discovery and inspection output.
-- `distributor run --config <path> [--dry-run]`: CLI to app to config loading, local source discovery, publish planning, local execution, destination state writing, and no-op notification.
-
-## 3. High-confidence deduplication opportunities
-
-### Runtime adapter and transform resolution bypass existing registries
-
-- Affected files/packages: `internal/app/run.go`, `internal/app/validate.go`, `internal/app/inspect.go`, `internal/publish/plan.go`, `internal/storage/registry.go`, `internal/transform/registry.go`.
-- Duplicated or near-duplicated behavior: app code directly checks `config.BackendLocal` and calls `local.New` in multiple paths. Publish code directly imports `internal/transform/markdown` and constructs the Markdown transformer through `markdownTransformer`, while `internal/transform.Registry` is unused.
-- Why it matters: Stage 9 and Stage 10 will add SSH/SFTP and S3 backends. If app orchestration continues to branch on backend names directly, every command path and run mode becomes a possible drift point. Direct Markdown construction also makes future transform registration less useful.
-- Recommended refactor: introduce an app-level backend factory that converts `config.Backend` and `config.Destination` into `storage.OpenConfig` and opens through a registry. Register only local for now. Move Markdown transformer selection behind a transform registry or a small transform resolver owned by app/publish boundaries.
-- Suggested tests: keep existing local run/validate/inspect tests; add an app factory unit test for local source and destination config resolution; add a publish/app test proving HTML generation uses the registered Markdown transform.
-- Risk level: medium. The behavior should remain unchanged, but this touches orchestration wiring used by all commands.
-
-### Source manifest validation rules are duplicated between bundle and state
-
-- Affected files/packages: `internal/bundle/manifest.go`, `internal/bundle/validate.go`, `internal/state/distributor.go`, `internal/state/validate.go`, `internal/state/compare.go`.
-- Duplicated or near-duplicated behavior: source manifest schema version, id, digest format, timestamp presence, file path safety, duplicate file path checks, file size rules, and bundle digest validation are enforced in both bundle parsing/validation and destination state validation.
-- Why it matters: `.distributor.json` embeds the normalized source manifest model. If the source manifest contract changes, fixes will likely need to be made in multiple packages, and state validation can drift from source validation.
-- Recommended refactor: expose a single `bundle` helper for validating an in-memory normalized manifest, including duplicate paths and canonical bundle digest. Let `ParseManifest` use parsing-specific checks and then call that helper. Let `state.Validate` call the same helper for embedded source manifests.
-- Suggested tests: preserve current `bundle` and `state` validation tests; add one cross-package regression fixture proving a manifest accepted by `bundle` is accepted when embedded in state, and a digest/path violation is rejected through the shared helper.
-- Risk level: medium. The refactor is behavior-preserving but affects core contract validation.
-
-### Managed deletion target construction is repeated in storage backends
-
-- Affected files/packages: `internal/adapters/local/backend.go`, `internal/storage/fake/backend.go`, `internal/storage/path.go`, `internal/publish/execute.go`.
-- Duplicated or near-duplicated behavior: both local and fake backends build the managed deletion target list by joining every output path under `bundlePath`, appending `storage.StatePath(bundlePath)`, and then applying backend-specific deletion.
-- Why it matters: SSH/SFTP and S3 adapters will need the same target derivation. Duplicating it in each adapter increases the chance of inconsistent state-file handling, invalid path behavior, or root deletion safeguards.
-- Recommended refactor: add a storage helper such as `ManagedBundleTargets(bundlePath string, managedOutputPaths []string) ([]string, error)` that validates and returns exact logical targets. Keep actual deletion backend-specific.
-- Suggested tests: add storage helper tests for root bundle path, nested bundle path, invalid output path, and inclusion of `.distributor.json`; keep local and fake managed deletion tests focused on backend deletion behavior.
-- Risk level: low. Target construction is small and already deterministic.
-
-### Publish/HTML policy validation is split between config and publish
-
-- Affected files/packages: `internal/config/validate.go`, `internal/publish/plan.go`, `internal/publish/output.go`, `internal/config/load_test.go`, `internal/publish/output_test.go`.
-- Duplicated or near-duplicated behavior: `internal/config` validates that `publish.html` requires `transform.markdown_to_html.enabled: true` and sidecar mode. `internal/publish` independently validates the same effective policy in `validateRequest`.
-- Why it matters: config-loaded runs are protected, but tests and programmatic callers can see different error text or future behavior if config and publish validation evolve separately.
-- Recommended refactor: centralize the effective publish/transform policy check in `internal/config` or a small policy helper that both config validation and publish request validation call.
-- Suggested tests: keep the existing config rejection test and publish rejection test, but assert both route through the same allowed combinations table.
-- Risk level: low.
-
-### Repeated bundle, config, and state test fixtures obscure behavior changes
-
-- Affected files/packages: `internal/app/run_test.go`, `internal/cli/root_test.go`, `internal/publish/output_test.go`, `internal/publish/execute_test.go`, `internal/transform/markdown/markdown_test.go`, `internal/state/distributor_test.go`, `internal/bundle/testdata`.
-- Duplicated or near-duplicated behavior: several packages recreate the same valid bundle shape, timestamps, file contents, digest calculation, local YAML snippets, and destination state data. Some tests use filesystem fixtures, some use fake storage, and some inline JSON/YAML.
-- Why it matters: changing the bundle contract, adding output metadata, or changing default config will require edits across many test files. The duplication also makes it harder to tell which tests are exercising unique behavior.
-- Recommended refactor: add an internal test helper package or package-local shared fixtures for valid manifests, source bundles, state files, and minimal configs. Keep package-specific edge cases local.
-- Suggested tests: no behavior tests are needed for helpers themselves beyond using them; add helper-backed tests incrementally while preserving current assertions.
-- Risk level: low.
-
-## 4. Medium-confidence opportunities
-
-### CLI command scaffolding is lightly duplicated
-
-- Affected files/packages: `internal/cli/run.go`, `internal/cli/validate.go`, `internal/cli/inspect.go`, `internal/cli/root.go`.
-- Duplicated or near-duplicated behavior: every command checks help, validates positional arguments, prints command-specific usage, calls app functions, and maps errors to exit codes. `validate` and `inspect` have nearly identical optional-path parsing.
-- Why it matters: adding `--pipeline`, output modes, or future command preflight behavior could create command drift.
-- Recommended refactor: add small CLI helpers for help detection, optional single path parsing, no-positional-argument rejection, and command usage printing. Do not introduce a large command framework unless the CLI grows substantially.
-- Suggested tests: keep existing CLI root tests; add table tests for validate/inspect path arity and run positional-argument rejection.
-- Risk level: low.
-
-### Output metadata projection appears in multiple layers
-
-- Affected files/packages: `internal/publish/output.go`, `internal/app/run.go`, `internal/notify/notify.go`, `internal/state/validate.go`.
-- Duplicated or near-duplicated behavior: publish outputs are converted to state output files in `stateOutputs`, and separately converted to notification outputs in `notifyEvent`.
-- Why it matters: when output metadata grows, fields can be added to state and omitted from notification, or vice versa, without a compiler-visible central projection.
-- Recommended refactor: keep destination state conversion in publish, but consider a small helper for notification output projection if output metadata changes in the next feature stage.
-- Suggested tests: extend notifier tests when output fields change.
-- Risk level: low.
-
-### Empty-path display helpers are repeated
-
-- Affected files/packages: `internal/bundle/validate.go`, `internal/app/inspect.go`, `internal/publish/plan.go`, `internal/publish/safety.go`.
-- Duplicated or near-duplicated behavior: `displayRoot`, `displayBundlePath`, and `displayPath` all render an empty logical path as `"."`.
-- Why it matters: this is user-facing output and error text. Minor drift can make tests brittle and logs inconsistent.
-- Recommended refactor: add a small formatting helper in the package that owns logical paths, or keep command/report formatting in app if avoiding cross-package formatting dependencies.
-- Suggested tests: update affected output/error tests to use behavior assertions rather than exact helper names.
-- Risk level: low.
-
-### Backend config structs repeat fields by shape
-
-- Affected files/packages: `internal/config/config.go`, `internal/config/validate.go`.
-- Duplicated or near-duplicated behavior: source `Backend` and destination `Destination` share backend fields such as `backend`, `path`, `uri`, `endpoint`, `bucket`, `prefix`, `region`, `force_path_style`, and credentials.
-- Why it matters: new backend fields need to be added in two places and passed through validation manually.
-- Recommended refactor: consider embedding a shared backend config struct in `Destination` only when adding remote backend implementations. Do not refactor now if it would complicate YAML decoding or docs.
-- Suggested tests: config load tests should cover any newly added shared fields for source and destination.
-- Risk level: low.
-
-## 5. Boundary and responsibility concerns
-
-- `internal/app` currently imports `internal/adapters/local` directly and branches on backend names. This is acceptable for the local MVP, but the documented architecture says app should construct backends through registries and avoid adapter-specific logic. The app layer is the right place for backend factory wiring; backend implementation details should remain in adapter packages.
-- `internal/publish` imports `internal/transform/markdown` directly. Publish should plan and execute outputs, but transform implementation selection belongs in transform/app wiring. A registry-backed resolver would better match the current package layout.
-- `internal/state` owns destination state, but it partially revalidates source manifest semantics. State should validate state-specific fields and delegate embedded source manifest contract checks to `internal/bundle`.
-- `internal/storage` owns logical path and state path helpers, but the state filename constant is private while callers and tests still hard-code `.distributor.json`. Expose the constant or provide a clearer canonical helper to reduce cross-package string reuse.
-
-## 6. Path, key, and naming construction review
-
-Local path safety is centralized well in `internal/storage/path.go` and the local adapter. Bundle-relative path composition generally uses `storage.Join`, and destination state paths use `storage.StatePath`.
-
-Cleanup targets:
-
-- `.distributor.json` is canonical in `storage.StatePath`, but the literal is also hard-coded in `bundle.ValidateSourcePath`, adapter tests, app tests, CLI tests, and docs. Exporting a canonical state filename would reduce drift.
-- Managed deletion target construction is repeated in local and fake storage backends. A storage helper should derive exact managed targets once.
-- Empty logical path display as `"."` is repeated across app, bundle, and publish.
-- Markdown sidecar naming is currently local to `internal/transform/markdown` through `strings.TrimSuffix(file.Path, ".md") + ".html"`. That is acceptable while Markdown sidecar is the only transform, but future path remapping or additional transforms should introduce a transform output naming helper rather than spreading suffix logic.
-
-## 7. Resolution and catalog review
-
-Backend resolution is not centralized enough for the next roadmap stage. The storage registry exists and is tested, but runtime code does not use it. App orchestration currently resolves only local backends manually.
-
-Transform resolution is also not centralized enough. The transform registry exists, but publish planning directly constructs the Markdown transformer.
-
-There are no separate artifact, schema, prompt, profile, module, validator, stage, source catalog, or report catalog packages in the current repository. That absence is appropriate for this application; no new catalog layer should be introduced unless a later feature creates multiple named implementations with shared resolution semantics.
-
-## 8. Config and command-loading review
-
-Config loading is mostly centralized: `app.Run` applies the default config path, calls `config.LoadFile`, and `config.LoadFile` handles YAML strict decoding, defaults, and validation. I did not find multiple independent config-loading paths for `run`.
-
-Intentional differences:
-
-- `validate` and `inspect` take direct local paths and do not load config. That matches current CLI behavior.
-- `run` supports `--config` and `--dry-run`; `validate` and `inspect` do not.
-
-Likely cleanup:
-
-- Keep default config path resolution close to config/app rather than in CLI.
-- Add shared CLI parsing helpers only for repeated command preflight, not for business policy.
-- Centralize publish/transform policy validation so config-loaded and programmatic publish requests cannot drift.
-
-## 9. State, manifest, or progress handling review
-
-Manifest handling is deterministic and well-covered: parsing is strict, digest validation is canonical, discovery sorts bundle paths, and source validation rejects unsafe paths and symlinks through storage metadata.
-
-Destination state handling is generally strong: `.distributor.json` is the success marker, comparison is centralized in `internal/state`, and publish execution writes state only after outputs are written.
-
-Cleanup targets:
-
-- Destination state validation should delegate embedded manifest validation to `internal/bundle`.
-- State output metadata construction should remain centralized in publish; if notification output metadata grows, add a projection helper to avoid field drift.
-- Run summary and status output currently live in `internal/app/run.go`. That is acceptable for MVP. Only extract a report/formatting package if additional output formats or commands start sharing the same summaries.
-
-I did not find run checkpoint, resume, retry, force, or progress-file logic in the implemented MVP.
-
-## 10. Refactors to avoid
-
-- Do not introduce a generic workflow engine for the pipeline. The current sequential orchestration is readable and matches MVP requirements.
-- Do not add a broad plugin architecture. Registries for storage and transforms are enough for the next stage.
-- Do not redesign the CLI around a larger framework solely to remove small parsing duplication.
-- Do not merge local and fake backends into one implementation. Their shared contract should be tested, but their storage behavior is intentionally different.
-- Do not generalize every test fixture immediately. Preserve package-local edge-case setup where it makes the behavior clearer.
-- Do not create catalog packages for artifacts, schemas, prompts, profiles, modules, stages, or reports unless the product adds multiple named implementations in those domains.
-- Do not rewrite manifest or state schemas as part of cleanup. Any schema change should be its own explicit compatibility task.
-
-## 11. Recommended implementation sequence
-
-1. Centralize storage names and managed target construction.
-   - Export or otherwise canonicalize the destination state filename.
-   - Add a storage helper for managed bundle deletion targets.
-   - Update local and fake backends to use it.
-
-2. Centralize source manifest model validation.
-   - Add a `bundle` helper for validating normalized manifests.
-   - Reuse it from manifest parsing and destination state validation.
-
-3. Centralize publish/transform policy validation.
-   - Move the allowed publish/transform combinations into one helper.
-   - Reuse it from config validation and publish request validation.
-
-4. Introduce runtime backend factory wiring.
-   - Register local storage through the existing storage registry.
-   - Update app run/validate/inspect paths to use the factory where appropriate.
-   - Keep unsupported remote backends returning the same user-facing behavior.
-
-5. Introduce transform resolver wiring.
-   - Register Markdown-to-HTML through the existing transform registry.
-   - Remove direct Markdown construction from publish.
-
-6. Add focused CLI preflight helpers.
-   - Share optional-path parsing and no-extra-argument handling.
-   - Keep command bodies explicit.
-
-7. Consolidate high-value test fixtures.
-   - Add helpers for valid source bundles, minimal configs, destination state, and fake backend source data.
-   - Migrate tests opportunistically while preserving package-specific assertions.
-
-8. Revisit output/report formatting only if additional output formats are added.
-
-9. Do a small dead-code sweep after the above.
-   - Remove `ErrNotImplemented`, `Pipeline`, or placeholder logging only if they are still unused and not needed by planned next work.
-
-## 12. Test strategy
-
-Tests to add before or during cleanup:
-
-- `internal/storage`: tests for managed target helper behavior, including root bundle path, nested bundle path, invalid output path, and `.distributor.json` inclusion.
-- `internal/bundle` and `internal/state`: shared manifest validation regression tests for embedded destination manifests.
-- `internal/config` and `internal/publish`: table-driven tests for allowed and rejected publish/transform policy combinations.
-- `internal/app`: backend factory tests that preserve current unsupported-backend errors and local backend behavior.
-- `internal/transform`: registry-backed Markdown resolution test if publish/app wiring moves to the registry.
-- `internal/cli`: table tests for command help, optional path handling, and rejected extra args.
-
-Tests that can accompany refactors:
-
-- Local and fake backend managed deletion tests after target helper extraction.
-- Existing app run tests after backend factory introduction.
-- Existing Markdown and publish output tests after transform resolver introduction.
-- CLI root tests after preflight helper extraction.
-
-The full suite should be run after any cleanup implementation. For this audit report itself, no full test run is required.
-
-## 13. Appendix: findings not worth acting on
-
-- The local and fake backend tests intentionally cover many of the same storage contract behaviors. Keep this parity. Only extract small test helpers if setup starts obscuring assertions.
-- `config.Backend` and `config.Destination` duplicate backend-shaped fields, but this is not urgent. A premature struct embedding refactor could make YAML behavior and docs less obvious.
-- `runSummary` and text output formatting are local to app orchestration. They are not worth extracting until more commands or output formats need the same formatting.
-- `internal/logging.Configure` is currently a placeholder. Do not build a logging abstraction until real logging requirements appear.
-- `internal/app/pipeline.go` currently contains only a minimal `Pipeline` type. Treat it as harmless unless it remains unused after the next implementation pass.
-- The small `displayRoot`/`displayPath` helpers are duplicated, but this is a low-risk cleanup after higher-value policy and storage centralization.

docs/roadmap/cleanup.md

@@ -1,537 +0,0 @@
-# Cleanup Implementation Roadmap
-
-This roadmap converts the findings in `docs/roadmap/audit.md` into staged cleanup work. It is written for LLM coding agents that will implement one stage at a time.
-
-The cleanup goal is to reduce drift before remote backend work without changing public CLI behavior, config semantics, manifest/state schemas, or local MVP behavior.
-
-## Global Cleanup Rules
-
-Every implementation stage must:
-
-1. read `AGENTS.md`, `docs/policy/architecture.md`, `docs/policy/documentation.md`, and this roadmap before editing;
-2. implement only the current stage;
-3. preserve current public CLI behavior and config behavior unless the stage explicitly says otherwise;
-4. keep cleanup behavior-preserving and avoid broad rewrites;
-5. add or update focused tests for the changed behavior;
-6. run relevant package tests, and run `go test ./...` when the stage touches cross-package behavior;
-7. update implemented internal docs only when an internal contract actually changes;
-8. leave user-facing docs unchanged unless public behavior changes;
-9. avoid implementing future remote backend features as part of cleanup.
-
-If Go cache or module cache permissions fail, use workspace-safe temporary caches:
-
-```bash
-GOCACHE=/private/tmp/distributor-gocache GOMODCACHE=/private/tmp/distributor-gomodcache go test ./...
-```
-
-## Stage 1: Centralize Storage State Names and Managed Delete Targets
-
-### Goal
-
-Make state-file naming and managed deletion target construction canonical before SSH/SFTP and S3 adapters are added.
-
-### Implementation
-
-In `internal/storage`:
-
-- Export the destination state filename as:
-
-```go
-const StateFileName = ".distributor.json"
-```
-
-- Update `StatePath` to use `StateFileName`.
-- Add:
-
-```go
-func ManagedBundleTargets(bundlePath string, managedOutputPaths []string) ([]string, error)
-```
-
-Required behavior:
-
-- `bundlePath` is validated as a prefix, so `""` is valid.
-- each managed output path is validated as a file path below `bundlePath`;
-- returned targets contain each managed output target followed by the `.distributor.json` target;
-- root bundle path returns output paths unchanged plus `.distributor.json`;
-- nested bundle path returns `bundlePath/output` plus `bundlePath/.distributor.json`;
-- invalid output paths fail before any backend deletion occurs;
-- duplicate output paths do not need to be de-duplicated in this stage.
-
-Update local and fake backends to call `storage.ManagedBundleTargets` inside `DeleteManagedBundle`. Keep actual deletion, missing-file handling, directory pruning, and backend-specific error translation in the backend implementations.
-
-Replace code/test references to literal `.distributor.json` with `storage.StateFileName` where the code already imports or reasonably can import `internal/storage`. Do not contort docs or unrelated tests only to remove literals from prose.
-
-### Tests
-
-Add or update tests for:
-
-- `StatePath("") == ".distributor.json"`;
-- `StatePath("bundle") == "bundle/.distributor.json"`;
-- managed targets for root and nested bundle paths;
-- invalid managed output path rejection;
-- local and fake managed deletion still delete only listed outputs plus state;
-- local and fake managed deletion still preserve unlisted files.
-
-Run:
-
-```bash
-go test ./internal/storage ./internal/storage/fake ./internal/adapters/local ./internal/bundle ./internal/publish
-```
-
-### Completion Criteria
-
-- Managed target derivation lives in one storage helper.
-- Local and fake backend behavior is unchanged.
-- No broad recursive delete behavior is introduced.
-
-## Stage 2: Centralize Normalized Source Manifest Validation
-
-### Goal
-
-Make `internal/bundle` the single owner of source manifest semantics, including embedded source manifests in destination state.
-
-### Implementation
-
-In `internal/bundle`, add a model-level validation helper:
-
-```go
-func ValidateManifest(manifest Manifest) error
-```
-
-Required behavior:
-
-- validate `SchemaVersion == 1`;
-- validate non-empty `ID`;
-- validate top-level `Digest` format;
-- validate non-zero `Created`;
-- require at least one file;
-- validate every file path with `ValidateSourcePath`;
-- validate every file digest format;
-- reject negative file sizes;
-- reject duplicate logical file paths;
-- recompute `BundleDigest(manifest.Files)` and require it to match `manifest.Digest`.
-
-Keep `ParseManifest` responsible for raw JSON parsing, missing-field detection, RFC3339 timestamp parsing, and trailing-data detection. After building the normalized `Manifest`, call `ValidateManifest` for model-level validation. Preserve current error substrings where practical, especially for existing tests that assert user-facing diagnostics.
-
-In `internal/state`, replace `validateEmbeddedManifest` logic with delegation to `bundle.ValidateManifest`, wrapping the error as `state source.manifest: ...` where current callers expect state context.
-
-Do not change the manifest JSON schema, destination state schema, digest algorithm, timestamp normalization policy, or source path policy.
-
-### Tests
-
-Add or update tests for:
-
-- `bundle.ValidateManifest` accepts the existing valid fixture manifest;
-- `bundle.ValidateManifest` rejects bad schema version, empty id, bad digest, zero created time, empty files, unsafe paths, duplicate paths, negative size, and bundle digest mismatch;
-- `state.Validate` rejects the same embedded manifest violations through the shared helper;
-- existing manifest parser and destination state parser tests continue to pass.
-
-Run:
-
-```bash
-go test ./internal/bundle ./internal/state ./internal/publish ./internal/app
-```
-
-### Completion Criteria
-
-- Source manifest contract semantics are implemented once in `internal/bundle`.
-- Destination state validation delegates embedded source manifest semantics to `internal/bundle`.
-- Existing local MVP behavior is unchanged.
-
-## Stage 3: Centralize Publish and Transform Policy Validation
-
-### Goal
-
-Prevent drift between config validation and publish request validation for allowed source/html/transform combinations.
-
-### Implementation
-
-Keep ownership in `internal/config`, because the policy is expressed in config types and used by config validation.
-
-Add a helper such as:
-
-```go
-func ValidatePublishTransformPolicy(publish PublishPolicy, transform Transform) error
-```
-
-Required behavior:
-
-- fail when both `publish.Source` and `publish.HTML` are false;
-- when `publish.HTML` is true, require `transform.MarkdownToHTML != nil`;
-- when `publish.HTML` is true, require `transform.MarkdownToHTML.Enabled == true`;
-- when `publish.HTML` is true, require `transform.MarkdownToHTML.Mode == TransformModeSidecar`;
-- when Markdown-to-HTML is configured and enabled, reject any mode other than `TransformModeSidecar`;
-- when Markdown-to-HTML is configured but disabled, allow empty mode or `TransformModeSidecar` and reject other modes;
-- return concise errors that can be wrapped with config field context.
-
-Update `internal/config.Validate` to use this helper while preserving contextual error messages such as `pipelines[0].destinations[0].transform...`.
-
-Update `internal/publish.validateRequest` to use the same helper for programmatic requests. The publish-layer error may be less field-path-specific, but it must remain actionable.
-
-Do not change defaulting behavior in `ApplyDefaults`.
-
-### Tests
-
-Add table tests covering:
-
-- source-only publish allowed;
-- html-only publish with enabled sidecar transform allowed;
-- source-plus-html with enabled sidecar transform allowed;
-- no outputs rejected;
-- html without transform rejected;
-- html with disabled transform rejected;
-- html with wrong mode rejected;
-- enabled Markdown transform with wrong mode rejected.
-
-Apply the table at both config validation and publish request validation levels.
-
-Run:
-
-```bash
-go test ./internal/config ./internal/publish ./internal/app
-```
-
-### Completion Criteria
-
-- Effective publish/transform policy is checked through one helper.
-- Config-loaded and programmatic publish paths cannot drift on this policy.
-
-## Stage 4: Introduce App Backend Factory Wiring
-
-### Goal
-
-Move runtime backend construction toward the storage registry before remote backends are implemented.
-
-### Implementation
-
-Create an app-level backend factory, preferably in `internal/app/backends.go`.
-
-Required shape:
-
-- The factory owns a `*storage.Registry`.
-- The default factory registers only the local backend for now.
-- Local backend registration maps storage open config key `path` to `local.New(path)`.
-- Source and destination config conversion stays in `internal/app`; adapter packages must not import config types.
-- Unsupported SSH/SFTP and S3 execution must continue to fail clearly as not implemented for execution.
-
-Suggested API:
-
-```go
-type backendFactory struct {
-    registry *storage.Registry
-}
-
-func newBackendFactory() *backendFactory
-func (f *backendFactory) openSource(ctx context.Context, source config.Backend) (storage.Backend, error)
-func (f *backendFactory) openDestination(ctx context.Context, destination config.Destination) (storage.Backend, error)
-func (f *backendFactory) openLocalPath(ctx context.Context, path string) (storage.Backend, error)
-```
-
-Use the factory from:
-
-- `app.Run` for pipeline sources and destinations;
-- `app.Validate` for direct local path validation;
-- `app.Inspect` for direct local path inspection.
-
-Keep `validate` and `inspect` direct-path commands local-only in this stage. Do not add config-driven validation or remote validation.
-
-Keep public error behavior stable enough that current tests continue to assert meaningful substrings. It is acceptable to update exact error text if the new text is clearer and tests assert stable behavior rather than brittle phrasing.
-
-### Tests
-
-Add tests for:
-
-- factory opens a local source backend;
-- factory opens a local destination backend;
-- factory opens a direct local path;
-- factory rejects unsupported source backend with a clear execution-not-implemented error;
-- factory rejects unsupported destination backend with a clear execution-not-implemented error.
-
-Run:
-
-```bash
-go test ./internal/app ./internal/cli
-```
-
-Then run:
-
-```bash
-go test ./...
-```
-
-### Completion Criteria
-
-- `internal/app` no longer directly constructs local backends in multiple command paths.
-- Backend construction goes through one app-level factory and storage registry.
-- No SSH/SFTP or S3 backend implementation is added.
-
-## Stage 5: Introduce Transform Resolver Wiring
-
-### Goal
-
-Remove direct Markdown transform construction from `internal/publish` and make transform selection explicit and testable.
-
-### Implementation
-
-Do not make `internal/transform` import `internal/transform/markdown`; that would create the wrong dependency direction. The app layer should own default transform registration.
-
-In `internal/publish`, define a narrow resolver interface:
-
-```go
-type TransformerResolver interface {
-    Get(name string) (transform.Transformer, bool)
-}
-```
-
-Add a resolver field to `publish.Request`, for example:
-
-```go
-Transformers TransformerResolver
-```
-
-Update output planning so HTML generation:
-
-- looks up `transform.MarkdownToHTML` through the resolver;
-- fails clearly if the resolver is nil or the Markdown transformer is not registered;
-- uses the resolved transformer to generate outputs.
-
-Create app-level transform registry wiring, preferably in `internal/app/transforms.go`:
-
-- create a `transform.Registry`;
-- register `transform.MarkdownToHTML` with `markdown.New()`;
-- pass the registry into every publish request created by `app.Run`.
-
-Update publish tests to use either:
-
-- a tiny fake resolver and fake transformer for publish package tests; or
-- a local registry assembled in the test.
-
-Use app tests to prove the real Markdown transformer remains wired for end-to-end local HTML publication.
-
-### Tests
-
-Add or update tests for:
-
-- publish planning fails when HTML is requested and no transformer resolver is supplied;
-- publish planning fails when Markdown transformer is missing from the resolver;
-- publish planning uses a registered transformer;
-- app local HTML publication still produces `report.html`;
-- existing Markdown transformer tests remain focused on Markdown rendering.
-
-Run:
-
-```bash
-go test ./internal/publish ./internal/transform ./internal/transform/markdown ./internal/app
-```
-
-Then run:
-
-```bash
-go test ./...
-```
-
-### Completion Criteria
-
-- `internal/publish` no longer imports `internal/transform/markdown`.
-- App wiring registers the MVP Markdown transform explicitly.
-- Transform behavior and public CLI behavior are unchanged.
-
-## Stage 6: Add Focused CLI Preflight Helpers
-
-### Goal
-
-Reduce small CLI parsing drift without hiding command behavior behind a large framework.
-
-### Implementation
-
-Keep the hand-written standard-library CLI. Do not introduce a new CLI dependency.
-
-Add small helpers in `internal/cli`, such as:
-
-```go
-func parseOptionalPathArg(stderr io.Writer, command string, args []string) (string, bool)
-func rejectPositionalArgs(stderr io.Writer, command string, args []string) bool
-```
-
-Use them to simplify:
-
-- `validateCommand`;
-- `inspectCommand`;
-- run positional argument rejection after flag parsing.
-
-Keep each command's help text local to that command. Keep `hasHelp`, `fail`, and root dispatch behavior simple and explicit.
-
-Do not add aliases, output modes, config loading for validate/inspect, or new flags.
-
-### Tests
-
-Add table tests for:
-
-- `validate` with zero args returns app-level required-path error;
-- `validate` with one arg succeeds for a valid bundle;
-- `validate` with two args returns usage;
-- `inspect` with zero args returns app-level required-path error;
-- `inspect` with one arg succeeds for a valid bundle;
-- `inspect` with two args returns usage;
-- `run` rejects extra positional args after flags.
-
-Run:
-
-```bash
-go test ./internal/cli ./internal/app
-```
-
-### Completion Criteria
-
-- CLI command bodies are still readable.
-- Common preflight parsing behavior is centralized where it is actually shared.
-- Public CLI behavior remains unchanged.
-
-## Stage 7: Add Test Fixture Helper Foundation
-
-### Goal
-
-Create shared test helpers for high-value fixtures without forcing every test to use them immediately.
-
-### Implementation
-
-Create `internal/testutil` for test support used by multiple internal packages.
-
-This package may contain regular Go files even though it is intended only for tests. Production code must not import `internal/testutil`.
-
-Initial helper coverage:
-
-- valid source bundle data:
-  - default id `weather.daily.brentwood.2026-05-30`;
-  - default created time `2026-05-30T11:10:00Z`;
-  - default files `report.md` with `# Report\nSunny.\n` and `summary.txt` with `Summary\n`;
-- filesystem source bundle writer;
-- fake-backend source bundle writer;
-- minimal local config writer;
-- fan-out local config writer;
-- destination state writer;
-- destination state reader.
-
-Helpers should return normal project types such as `bundle.Manifest`, `bundle.Bundle`, and `state.DistributorState`.
-
-Do not move edge-case test logic into `testutil`. Tests for invalid manifests, collisions, symlinks, failures, and backend-specific behavior should remain close to the package being tested.
-
-### Tests
-
-Do not add tests for `testutil` itself unless helpers contain nontrivial logic not covered by consuming tests.
-
-Migrate only one or two low-risk test files in this stage to prove the helpers work. Good candidates:
-
-- `internal/publish/execute_test.go`;
-- `internal/transform/markdown/markdown_test.go`.
-
-Run:
-
-```bash
-go test ./internal/testutil ./internal/publish ./internal/transform/markdown
-```
-
-Then run:
-
-```bash
-go test ./...
-```
-
-### Completion Criteria
-
-- A shared fixture foundation exists.
-- At least two packages use it successfully.
-- The migration is incremental and does not obscure package-specific assertions.
-
-## Stage 8: Migrate High-Value Duplicate Test Fixtures
-
-### Goal
-
-Reduce the largest remaining test fixture duplication after the helper foundation is proven.
-
-### Implementation
-
-Migrate duplicated valid bundle/config/state setup in:
-
-- `internal/app/run_test.go`;
-- `internal/cli/root_test.go`;
-- `internal/publish/output_test.go`;
-- `internal/state/distributor_test.go`, where helper use improves clarity.
-
-Keep tests local when custom setup makes the behavior clearer than a shared helper. Do not chase 100 percent fixture reuse.
-
-Preserve all existing behavioral assertions.
-
-### Tests
-
-Run:
-
-```bash
-go test ./internal/app ./internal/cli ./internal/publish ./internal/state
-```
-
-Then run:
-
-```bash
-go test ./...
-```
-
-### Completion Criteria
-
-- The largest repeated valid bundle/config/state setup is centralized.
-- Edge-case tests remain readable.
-- No production code imports `internal/testutil`.
-
-## Stage 9: Final Dead-Code and Low-Value Cleanup Sweep
-
-### Goal
-
-Remove or defer remaining low-value cleanup items after the higher-impact centralization work is complete.
-
-### Implementation
-
-Review and decide on these items:
-
-- remove `app.ErrNotImplemented` if it is still unused;
-- remove or expand `internal/app/pipeline.go` if the placeholder `Pipeline` type is still unused;
-- keep `internal/logging.Configure` if it is still a planned extension point, otherwise remove it only if no code or docs reference it;
-- decide whether empty-path display helpers should remain local or move to a single helper;
-- leave `config.Backend` and `config.Destination` field duplication alone unless remote backend implementation work is starting immediately.
-
-Do not add:
-
-- generic workflow engine;
-- plugin architecture;
-- broad CLI framework;
-- schema rewrites;
-- remote backend behavior;
-- output/report formatting package unless it is now clearly shared by multiple commands.
-
-### Tests
-
-Run the full suite:
-
-```bash
-go test ./...
-```
-
-If removals affect docs or internal docs, update only implemented-behavior docs.
-
-### Completion Criteria
-
-- Obvious dead code is removed or explicitly left in place for a documented reason.
-- Remaining duplication is either low-value or intentionally deferred.
-- The codebase is ready to resume roadmap work on remote backends.
-
-## Deferred Cleanup
-
-Do not implement these as part of the cleanup roadmap unless a later roadmap explicitly promotes them:
-
-- embedding a shared backend config struct into `config.Destination`;
-- generic output/report formatting package;
-- broader test fixture migration beyond the high-value repeated fixtures;
-- remote backend implementations;
-- force overwrite behavior;
-- generic pipeline/workflow engine;
-- broad plugin system.
-

docs/roadmap/config.md

@@ -1,580 +0,0 @@
-# Distributor Configuration Roadmap
-
-This roadmap defines the planned `config.yml` schema for the `distributor` MVP. The goal is to support one-to-many publication pipelines where each pipeline has one source and one or more destinations. Each destination independently controls backend configuration, publication outputs, transform behavior, and replacement policy.
-
-## Configuration Goals
-
-The MVP configuration should be:
-
-- explicit enough to avoid hidden publication behavior;
-- compact enough for routine self-hosted use;
-- backend-agnostic at the pipeline layer;
-- capable of local, SSH/SFTP, and S3-compatible source and destination backends;
-- ready for future notification adapters without exposing a fake notification feature in the MVP.
-
-## Top-Level Shape
-
-```yaml
-pipelines:
-  - id: weather-daily
-    source:
-      backend: local
-      path: /var/spool/distributor/weather
-
-    validation:
-      on_digest_mismatch: fail
-
-    destinations:
-      - id: markdown-archive
-        backend: s3
-        endpoint: https://s3.example.com
-        bucket: reports
-        prefix: weather/archive
-        region: us-east-1
-        force_path_style: true
-        credentials:
-          access_key_id_env: DISTRIBUTOR_S3_ACCESS_KEY_ID
-          secret_access_key_env: DISTRIBUTOR_S3_SECRET_ACCESS_KEY
-
-        publish:
-          source: true
-          html: false
-
-        transfer:
-          on_destination_same: skip
-          on_destination_older: replace
-          on_destination_newer: skip
-          on_conflict: fail
-
-      - id: static-site
-        backend: ssh
-        uri: ssh://deploy@example.com:22
-        path: /srv/www/weather
-
-        publish:
-          source: false
-          html: true
-
-        transform:
-          markdown_to_html:
-            enabled: true
-            mode: sidecar
-
-        transfer:
-          on_destination_same: skip
-          on_destination_older: replace
-          on_destination_newer: skip
-          on_conflict: fail
-```
-
-## Pipeline Fields
-
-Each pipeline must include:
-
-- `id`: Required stable pipeline identifier.
-- `source`: Required source backend configuration.
-- `destinations`: Required non-empty list of destination configurations.
-
-Optional pipeline-level fields:
-
-- `validation`: Source validation behavior.
-- Future: `notifications` or `notify`, when notification adapters are implemented.
-
-A pipeline has exactly one source and one or more destinations.
-
-## Pipeline ID Rules
-
-`pipelines[].id` should:
-
-- be required;
-- be unique across the config file;
-- be stable over time;
-- use a simple slug-like format, such as `weather-daily` or `dnd-session-recaps`.
-
-Recommended validation:
-
-```text
-^[a-zA-Z0-9][a-zA-Z0-9._-]*$
-```
-
-## Source Configuration
-
-`source` defines the source root where bundles are discovered.
-
-The source backend may be:
-
-- `local`;
-- `ssh`;
-- `s3`.
-
-The source is scanned for `manifest.json` files beneath the configured root.
-
-### Local source
-
-```yaml
-source:
-  backend: local
-  path: /var/spool/distributor/weather
-```
-
-Required fields:
-
-- `backend: local`
-- `path`
-
-### SSH source
-
-```yaml
-source:
-  backend: ssh
-  uri: ssh://reports@example.com:22
-  path: /var/spool/distributor/weather
-```
-
-Required fields:
-
-- `backend: ssh`
-- `uri`
-- `path`
-
-Recommended authentication behavior:
-
-- use SSH agent by default;
-- use local known_hosts validation by default;
-- support optional key file configuration later if needed;
-- do not require passwords in YAML.
-
-Optional future fields:
-
-```yaml
-known_hosts: /home/user/.ssh/known_hosts
-key_file: /home/user/.ssh/id_ed25519
-```
-
-### S3 source
-
-```yaml
-source:
-  backend: s3
-  endpoint: https://s3.example.com
-  bucket: reports
-  prefix: incoming/weather
-  region: us-east-1
-  force_path_style: true
-  credentials:
-    access_key_id_env: DISTRIBUTOR_S3_ACCESS_KEY_ID
-    secret_access_key_env: DISTRIBUTOR_S3_SECRET_ACCESS_KEY
-```
-
-Required fields:
-
-- `backend: s3`
-- `endpoint`
-- `bucket`
-
-Optional fields:
-
-- `prefix`
-- `region`
-- `force_path_style`
-- `credentials`
-
-Credential configuration should prefer environment variables or standard SDK behavior over literal secrets in config.
-
-## Destination Configuration
-
-Each destination defines one publication target for a pipeline.
-
-Required destination fields:
-
-- `id`
-- `backend`
-- backend-specific location fields;
-- `publish`
-
-Optional destination fields:
-
-- `transform`
-- `transfer`
-
-Each destination is independently planned and published. A destination may receive source files, generated HTML, or both.
-
-## Destination ID Rules
-
-`destinations[].id` should:
-
-- be required;
-- be unique within the containing pipeline;
-- be stable over time;
-- use a slug-like format.
-
-Recommended examples:
-
-- `markdown-archive`
-- `static-site`
-- `full-mirror`
-
-## Local Destination
-
-```yaml
-destinations:
-  - id: local-static
-    backend: local
-    path: /srv/www/reports
-    publish:
-      source: false
-      html: true
-```
-
-Required fields:
-
-- `backend: local`
-- `path`
-- `publish`
-
-## SSH Destination
-
-```yaml
-destinations:
-  - id: static-site
-    backend: ssh
-    uri: ssh://deploy@example.com:22
-    path: /srv/www/weather
-    publish:
-      source: false
-      html: true
-```
-
-Required fields:
-
-- `backend: ssh`
-- `uri`
-- `path`
-- `publish`
-
-The MVP should use a native SFTP implementation rather than shelling out to `ssh`, `scp`, or `rsync`.
-
-## S3 Destination
-
-```yaml
-destinations:
-  - id: markdown-archive
-    backend: s3
-    endpoint: https://s3.example.com
-    bucket: reports
-    prefix: weather/archive
-    region: us-east-1
-    force_path_style: true
-    credentials:
-      access_key_id_env: DISTRIBUTOR_S3_ACCESS_KEY_ID
-      secret_access_key_env: DISTRIBUTOR_S3_SECRET_ACCESS_KEY
-    publish:
-      source: true
-      html: false
-```
-
-Required fields:
-
-- `backend: s3`
-- `endpoint`
-- `bucket`
-- `publish`
-
-Optional fields:
-
-- `prefix`
-- `region`
-- `force_path_style`
-- `credentials`
-
-## Backend Configuration Normalization
-
-The config loader should normalize backend configuration into internal source and destination backend specs. Pipeline logic should not branch on backend-specific fields.
-
-Validation should catch:
-
-- missing backend names;
-- unsupported backend names;
-- missing backend-specific required fields;
-- duplicate pipeline IDs;
-- duplicate destination IDs within a pipeline;
-- empty destination lists;
-- invalid policy values.
-
-## Publication Policy
-
-`publish` controls which categories of files are written to a destination.
-
-```yaml
-publish:
-  source: true
-  html: false
-```
-
-Fields:
-
-- `source`: Publish source artifacts listed in `manifest.json`.
-- `html`: Publish HTML files generated from Markdown source artifacts.
-
-At least one of `source` or `html` must be true.
-
-Recommended defaults:
-
-```yaml
-publish:
-  source: true
-  html: false
-```
-
-No implicit HTML transformation should occur. When `publish.html` is true, `transform.markdown_to_html.enabled: true` and `mode: sidecar` are required for the MVP.
-
-## Transform Configuration
-
-For MVP, the only supported transform is Markdown to HTML.
-
-```yaml
-transform:
-  markdown_to_html:
-    enabled: true
-    mode: sidecar
-```
-
-Fields:
-
-- `enabled`: Whether Markdown-to-HTML transform is enabled.
-- `mode`: Output mode. MVP value: `sidecar`.
-
-MVP `sidecar` behavior:
-
-- each listed Markdown source file generates an HTML file with the same base path and `.html` extension;
-- `report.md` generates `report.html`;
-- generated files are destination publication artifacts;
-- source bundles are not mutated.
-
-MVP defaulting:
-
-- If `publish.html` is false, transform may be omitted.
-- If `publish.html` is true and `transform.markdown_to_html` is omitted or disabled, config validation must fail.
-
-## Validation Policy
-
-Pipeline-level validation is intentionally narrow in the MVP.
-
-```yaml
-validation:
-  on_digest_mismatch: fail
-```
-
-Supported value:
-
-- `fail`
-
-Default:
-
-```yaml
-on_digest_mismatch: fail
-```
-
-Validation should happen before any destination writes. Warning-only digest mismatch handling is deferred and must be rejected if configured.
-
-## Transfer Policy
-
-Destination-level transfer policy controls behavior after inspecting `.distributor.json` at the destination bundle path.
-
-```yaml
-transfer:
-  on_destination_same: skip
-  on_destination_older: replace
-  on_destination_newer: skip
-  on_conflict: fail
-```
-
-Supported fields:
-
-- `on_destination_same`
-- `on_destination_older`
-- `on_destination_newer`
-- `on_conflict`
-
-MVP supported values are intentionally limited by field:
-
-- `on_destination_same`: `skip` or `fail`
-- `on_destination_older`: `replace` or `fail`
-- `on_destination_newer`: `skip` or `fail`
-- `on_conflict`: `fail`
-
-Recommended MVP defaults:
-
-```yaml
-transfer:
-  on_destination_same: skip
-  on_destination_older: replace
-  on_destination_newer: skip
-  on_conflict: fail
-```
-
-Safety rule:
-
-- `replace` must never perform broad deletion against a destination root.
-- `replace` may only operate within a resolved destination bundle path and should delete only files recorded in existing `.distributor.json.outputs` plus `.distributor.json` where practical.
-- Unmanaged non-empty destination paths fail in the MVP. Force or unmanaged overwrite configuration is deferred.
-- Broader replacement values, including replacing newer destinations or conflicts, are deferred to a later explicit force-overwrite stage.
-
-## Path Mapping
-
-MVP path mapping is fixed:
-
-```text
-destination bundle path = destination root + source relative bundle path
-```
-
-Example:
-
-```text
-source root: /var/spool/reports
-source bundle: /var/spool/reports/weather/daily/brentwood/2026-05-30
-relative bundle path: weather/daily/brentwood/2026-05-30
-
-destination root: /srv/www/reports
-destination bundle path: /srv/www/reports/weather/daily/brentwood/2026-05-30
-```
-
-Future config may support explicit path mapping, but MVP should not.
-
-## Dry Run Configuration and CLI Behavior
-
-Dry-run should be a CLI flag rather than a persistent config setting.
-
-```bash
-distributor run --config config.yml --dry-run
-```
-
-Dry-run should report:
-
-- pipeline ID;
-- source backend;
-- destination ID;
-- destination backend;
-- discovered bundle ID;
-- relative bundle path;
-- planned action;
-- reason;
-- transform outputs that would be generated;
-- files that would be written or deleted.
-
-## Example: Weather Pipeline
-
-```yaml
-pipelines:
-  - id: weather-daily
-    source:
-      backend: local
-      path: /var/spool/distributor/weather
-
-    validation:
-      on_digest_mismatch: fail
-
-    destinations:
-      - id: markdown-archive
-        backend: s3
-        endpoint: https://s3.example.com
-        bucket: reports
-        prefix: weather/archive
-        region: us-east-1
-        force_path_style: true
-        credentials:
-          access_key_id_env: DISTRIBUTOR_S3_ACCESS_KEY_ID
-          secret_access_key_env: DISTRIBUTOR_S3_SECRET_ACCESS_KEY
-        publish:
-          source: true
-          html: false
-
-      - id: static-site
-        backend: ssh
-        uri: ssh://deploy@web.example.com:22
-        path: /srv/www/weather
-        publish:
-          source: false
-          html: true
-        transform:
-          markdown_to_html:
-            enabled: true
-            mode: sidecar
-```
-
-## Example: D&D Recap Pipeline
-
-```yaml
-pipelines:
-  - id: dnd-session-recaps
-    source:
-      backend: local
-      path: /var/spool/distributor/dnd/session-recaps
-
-    destinations:
-      - id: private-markdown-archive
-        backend: s3
-        endpoint: https://s3.example.com
-        bucket: reports
-        prefix: dnd/session-recaps
-        region: us-east-1
-        force_path_style: true
-        credentials:
-          access_key_id_env: DISTRIBUTOR_S3_ACCESS_KEY_ID
-          secret_access_key_env: DISTRIBUTOR_S3_SECRET_ACCESS_KEY
-        publish:
-          source: true
-          html: false
-
-      - id: private-html-site
-        backend: local
-        path: /srv/www/private/dnd/session-recaps
-        publish:
-          source: false
-          html: true
-        transform:
-          markdown_to_html:
-            enabled: true
-            mode: sidecar
-```
-
-## Future Notification Configuration
-
-Notification should not be exposed as a functional MVP feature unless an adapter exists.
-
-The internal pipeline may include a no-op notification stage. Future config may look like:
-
-```yaml
-notifications:
-  - id: weather-email
-    backend: email
-    after_destinations:
-      - static-site
-    subject: "Weather report published"
-```
-
-Future notification policy should require:
-
-- notification after successful relevant publication;
-- idempotency by source manifest id and digest;
-- no duplicate notification unless explicitly forced.
-
-## Implementation Stages
-
-1. Define config structs for pipelines, sources, destinations, validation, publish, transform, and transfer policies.
-2. Implement config loading and strict validation.
-3. Implement backend-specific config validation for local, SSH, and S3.
-4. Implement defaulting for validation and transfer policies.
-5. Require explicit transform configuration when `publish.html` is true.
-6. Add example config fixtures for local-to-local, local-to-SSH, local-to-S3, and fan-out scenarios.
-7. Connect config to backend registry and publish planner.
-8. Add `--pipeline` filtering for targeted runs.
-9. Add `--dry-run` output that reflects the resolved config and planned actions.
-
-## Deferred Configuration
-
-The following configuration ideas are intentionally outside the MVP:
-
-- warning-only digest mismatch handling;
-- unmanaged destination overwrite flags until the explicit force-overwrite roadmap stage;
-- force replacement of destinations with different source ids until the explicit force-overwrite roadmap stage.

docs/roadmap/contracts.md

@@ -1,398 +0,0 @@
-# Distributor Contracts Roadmap
-
-This roadmap defines the contracts that `distributor` should implement before or alongside the MVP. The goal is to make bundle validation, destination state, digest verification, and safe replacement deterministic and testable before backend-specific publication behavior is layered on top.
-
-## Purpose
-
-`distributor` publishes manifested report bundles produced by other applications. Producer applications own domain-specific report generation. `distributor` owns validation, optional transformation, destination publication, and destination state.
-
-The MVP contract has two durable files:
-
-- `manifest.json`: source-owned bundle manifest produced by the upstream application.
-- `.distributor.json`: destination-owned publication state written by `distributor`.
-
-`manifest.json` is not copied to the destination as destination state. Instead, `.distributor.json` records the normalized source manifest, generated output metadata, and distributor-owned publication metadata.
-
-All manifest and state timestamps should be serialized as RFC3339. Internal comparison should use parsed timestamp values, and distributor-written timestamps should be normalized to RFC3339 UTC.
-
-## Terminology
-
-- **Source root**: Configured root path for a pipeline source.
-- **Bundle root**: Directory beneath the source root that contains `manifest.json`.
-- **Relative bundle path**: Bundle root path relative to the source root.
-- **Destination root**: Configured root path or prefix for a destination.
-- **Destination bundle path**: Destination root plus the relative bundle path, unless a future mapping option overrides that behavior.
-- **Source artifact**: File listed in the source `manifest.json`.
-- **Generated artifact**: File created by `distributor`, such as an HTML file derived from Markdown.
-- **Destination state**: `.distributor.json` at the destination bundle path.
-
-## Source Bundle Contract
-
-A source bundle is a directory containing a `manifest.json` file. For MVP, the manifest schema is intentionally minimal.
-
-### Required `manifest.json` fields
-
-```json
-{
-  "schema_version": 1,
-  "id": "weather.daily.brentwood.2026-05-30",
-  "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
-  "created": "2026-05-30T11:10:00Z",
-  "files": [
-    {
-      "path": "report.md",
-      "sha256": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
-      "size": 12345
-    }
-  ]
-}
-```
-
-Required top-level fields:
-
-- `schema_version`: Source manifest schema version. MVP value: `1`.
-- `id`: Stable bundle identifier. Required, non-empty string.
-- `digest`: Bundle digest. Required, lowercase `sha256:<64 hex>` string.
-- `created`: Bundle creation timestamp. Required RFC3339 timestamp. UTC is preferred; explicit offsets are allowed.
-- `files`: Non-empty array of file objects.
-
-Required file fields:
-
-- `path`: Relative path from bundle root to source artifact.
-- `sha256`: Per-file digest as lowercase `sha256:<64 hex>`.
-- `size`: File size in bytes.
-
-No other source manifest fields are required for the MVP. Additional fields may be ignored unless later documented. Destination state records the normalized source manifest model, not raw unknown manifest fields.
-
-## Source Path Safety Rules
-
-For every `files[].path`:
-
-- Path must be relative.
-- Path must not be empty.
-- Path must not contain `..` segments.
-- Path must not resolve outside the bundle root.
-- Path must use slash-separated logical paths in the manifest.
-- Absolute paths are invalid.
-- Symlinks should be rejected for MVP unless a later policy deliberately supports them.
-- `manifest.json` itself should not be listed as a source artifact.
-- `.distributor.json` should not be listed as a source artifact.
-- Duplicate logical file paths are invalid after path normalization.
-
-The implementation should validate paths before reading file contents.
-
-## Digest Contract
-
-The MVP validates both per-file digests and the bundle digest.
-
-### Per-file digest
-
-For each file listed in `files`, compute:
-
-```text
-sha256(file bytes)
-```
-
-The computed digest must match `files[].sha256`.
-
-The actual file size must match `files[].size`.
-
-### Bundle digest
-
-The bundle digest is computed from the listed file records in the listed order. The canonical algorithm is:
-
-1. For each file listed in `files`, in order:
-   - validate the file path;
-   - compute the file SHA256;
-   - determine the file size.
-2. Construct a canonical JSON array containing only:
-   - `path`;
-   - `sha256`;
-   - `size`.
-3. Preserve the source manifest's file order.
-4. Encode the array deterministically with:
-   - object fields in exactly this order: `path`, `sha256`, `size`;
-   - no extra spaces;
-   - no trailing newline;
-   - lowercase `sha256:<64 hex>` digest strings.
-5. Compute `sha256(canonical JSON bytes)`.
-6. Compare the result to top-level `digest`.
-
-Conceptual canonical payload:
-
-```json
-[
-  {"path":"report.md","sha256":"sha256:...","size":12345},
-  {"path":"summary.txt","sha256":"sha256:...","size":234}
-]
-```
-
-This avoids ambiguous concatenation of file bytes while keeping the manifest small.
-
-Implementation fixtures should include at least one reference manifest and canonical payload with known per-file and bundle digests.
-
-## Digest Mismatch Behavior
-
-Digest validation is always fatal in the MVP. A digest mismatch must fail the affected bundle, pipeline, and run before any destination writes occur.
-
-Warning-only digest behavior is intentionally deferred until a later roadmap accepts transitional ingestion semantics.
-
-## Bundle Discovery Contract
-
-A source path may contain one bundle or a tree of bundles. Discovery should scan beneath the configured source root for `manifest.json` files.
-
-For each discovered manifest:
-
-- Bundle root is the directory containing `manifest.json`.
-- Relative bundle path is computed relative to source root.
-- Destination bundle path is destination root plus relative bundle path, unless a future mapping option overrides it.
-
-If nested manifests are found, the MVP should fail with a clear error unless a later policy defines nested-bundle semantics.
-
-## Destination State Contract
-
-Destinations are managed by `.distributor.json`, not by copying `manifest.json`.
-
-A destination bundle path is considered distributor-managed only when it contains a valid `.distributor.json` written by `distributor`. Force or unmanaged-overwrite behavior is not part of the MVP.
-
-### Required `.distributor.json` shape
-
-```json
-{
-  "schema_version": 1,
-  "distributor_version": "0.1.0",
-  "pipeline_id": "weather-daily",
-  "destination_id": "static-site",
-  "published_at": "2026-05-30T11:12:00Z",
-  "source": {
-    "manifest": {
-      "schema_version": 1,
-      "id": "weather.daily.brentwood.2026-05-30",
-      "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
-      "created": "2026-05-30T11:10:00Z",
-      "files": [
-        {
-          "path": "report.md",
-          "sha256": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
-          "size": 12345
-        }
-      ]
-    }
-  },
-  "outputs": [
-    {
-      "path": "report.html",
-      "kind": "generated",
-      "source_path": "report.md",
-      "transform": "markdown_to_html",
-      "sha256": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
-      "size": 23456
-    }
-  ]
-}
-```
-
-Required fields:
-
-- `schema_version`: Destination state schema version. MVP value: `1`.
-- `distributor_version`: Optional diagnostic distributor version. It must not affect source comparison.
-- `pipeline_id`: Pipeline that produced the destination publication.
-- `destination_id`: Destination within the pipeline.
-- `published_at`: RFC3339 timestamp.
-- `source.manifest`: Normalized source manifest model used for this publication.
-- `outputs`: Array of files written by `distributor` for this destination.
-
-Required output fields:
-
-- `path`: Destination-relative output path within the destination bundle path.
-- `kind`: `source` or `generated`.
-- `source_path`: Source artifact path that produced this output. For copied source files, this should equal `path` unless renamed by a future feature.
-- `transform`: Transform identifier for generated files. Empty or omitted may be allowed for copied source files.
-- `sha256`: Output file digest as lowercase `sha256:<64 hex>`.
-- `size`: Output file size in bytes.
-
-## Destination Comparison Rules
-
-Destination comparison uses `.distributor.json`, not destination `manifest.json`.
-
-For a source bundle and destination bundle path:
-
-### No `.distributor.json`
-
-If no `.distributor.json` exists and the destination path is empty:
-
-- Publish normally.
-
-If no `.distributor.json` exists and the destination path is non-empty:
-
-- Fail as unmanaged content.
-
-Local destination paths are empty when the destination bundle directory does not exist or exists with no entries. S3-compatible destination prefixes are empty when no objects exist below the destination bundle prefix, ignoring objects outside that exact prefix.
-
-### Pipeline or destination mismatch
-
-If `.distributor.json` exists but its `pipeline_id` or `destination_id` differs from the current pipeline or destination config:
-
-- Fail as a conflict.
-
-### Same source manifest
-
-If `.distributor.json` exists and `source.manifest` exactly matches the current normalized source manifest:
-
-- Skip as already published.
-
-### Same source id, destination older
-
-If `.distributor.json` exists, `source.manifest.id` matches the source manifest `id`, and destination `source.manifest.created` is older than the source `created`:
-
-- Replace destination contents, subject to replacement safety rules.
-
-### Same source id, destination newer
-
-If `.distributor.json` exists, `source.manifest.id` matches the source manifest `id`, and destination `source.manifest.created` is newer than the source `created`:
-
-- Skip and log that destination is newer than source.
-
-### Same source id and created, different digest
-
-If `.distributor.json` exists, `source.manifest.id` and `created` match but `digest` differs:
-
-- Fail as a conflict.
-
-### Different source id
-
-If `.distributor.json` exists and `source.manifest.id` differs from the source manifest `id`:
-
-- Fail as a conflict.
-
-## Replacement Safety Rules
-
-Replacement is destructive and must be narrow.
-
-`distributor` must never perform broad deletion against a configured destination root.
-
-Replacement may occur only at a resolved destination bundle path when:
-
-- a valid `.distributor.json` exists at that destination bundle path; and
-- the state identifies the path as distributor-managed; and
-- the replacement decision follows the destination comparison rules.
-
-For MVP, replacement should delete only known managed outputs where practical:
-
-- files listed in existing `.distributor.json.outputs`;
-- existing `.distributor.json`;
-- empty directories created by those files, where applicable for filesystem-like backends.
-
-For S3, replacement should delete only objects under the destination bundle prefix that are listed in `.distributor.json.outputs` plus `.distributor.json`, unless a later managed-prefix deletion policy is explicitly implemented.
-
-Before any write, planned destination output paths must be checked for collisions. For example, if `report.md` is copied as a source artifact and Markdown transformation would also generate `report.html`, but `report.html` is already a source artifact or another generated output, planning must fail before writing.
-
-## Transform Output Contract
-
-Source files are canonical. Generated files are derived publication artifacts.
-
-For MVP, the only supported transform is Markdown to HTML.
-
-Recommended MVP behavior:
-
-- Transform is configured per destination.
-- Markdown source files are files listed in `manifest.json` with `.md` extension.
-- Generated HTML files are sidecars by default.
-- `report.md` generates `report.html`.
-- Source bundles are never mutated.
-- Generated outputs are recorded in `.distributor.json.outputs`.
-- Raw HTML embedded in Markdown is escaped or disabled by default for the MVP to keep generated output deterministic and conservative.
-
-Future versions may add templates, `index.html`, CSS assets, email-safe HTML, and per-file transform selection.
-
-## Destination Output Contract
-
-Each destination chooses which categories of files it receives.
-
-MVP categories:
-
-- `source`: copied source artifacts listed in `manifest.json`.
-- `html`: generated HTML derived from Markdown source artifacts.
-
-Examples:
-
-- Markdown archive: `source: true`, `html: false`.
-- Static HTML site: `source: false`, `html: true`.
-- Full mirror: `source: true`, `html: true`.
-
-Every file written to the destination must be represented in `.distributor.json.outputs`.
-
-## Atomicity and Partial Failure
-
-The MVP should prefer staging and promotion where backend semantics permit it.
-
-Minimum behavior:
-
-- Validate source before writing destination files.
-- Do not write `.distributor.json` until all configured destination outputs are successfully written.
-- If publication fails before `.distributor.json` is written, the destination must not be treated as successfully published on a later run.
-- Local publication must use staging or equivalent cleanup behavior so a failed write does not leave a confusing unmanaged destination bundle path.
-- Later cleanup may remove orphaned files, but MVP correctness should rely on `.distributor.json` as the success marker.
-
-## Example Source Bundle
-
-```text
-weather/daily/brentwood/2026-05-30/
-  manifest.json
-  report.md
-  summary.txt
-```
-
-Example manifest:
-
-```json
-{
-  "schema_version": 1,
-  "id": "weather.daily.brentwood.2026-05-30",
-  "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
-  "created": "2026-05-30T11:10:00Z",
-  "files": [
-    {
-      "path": "report.md",
-      "sha256": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
-      "size": 12345
-    },
-    {
-      "path": "summary.txt",
-      "sha256": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
-      "size": 234
-    }
-  ]
-}
-```
-
-## Example Destination Bundle: HTML Only
-
-```text
-weather/daily/brentwood/2026-05-30/
-  report.html
-  .distributor.json
-```
-
-## Example Destination Bundle: Source Archive
-
-```text
-weather/daily/brentwood/2026-05-30/
-  report.md
-  summary.txt
-  .distributor.json
-```
-
-## Implementation Stages
-
-1. Define Go structs for source manifest and destination state.
-2. Implement source path validation.
-3. Implement per-file SHA256 and size validation.
-4. Implement canonical bundle digest validation.
-5. Implement source bundle discovery beneath a source root.
-6. Implement `.distributor.json` parsing and validation.
-7. Implement destination comparison rules.
-8. Implement replacement safety checks.
-9. Add fixture bundles for valid, invalid, duplicate path, older, newer, same, and conflict scenarios.
-10. Add reference canonical digest fixtures.
-11. Use the contract layer from the publish pipeline and backend adapters.

docs/roadmap/implementation.md

@@ -1,863 +1,102 @@
-# Distributor Implementation Roadmap
-
-This roadmap defines a staged implementation plan for the `distributor` MVP. Each stage is intended to map cleanly to one Codex implementation prompt.
-
-The roadmap assumes the project includes these planning documents before implementation begins:
-
-- `docs/policy/architecture.md`
-- `docs/policy/documentation.md`
-- `docs/roadmap/packages.md`
-- `docs/roadmap/contracts.md`
-- `docs/roadmap/config.md`
-- `docs/roadmap/storage.md`
-
-The MVP goal is a domain-agnostic bundle distributor that discovers source bundles, validates `manifest.json`, optionally transforms Markdown to HTML, publishes selected outputs to one or more destinations, and records destination state in `.distributor.json`.
-
-## Global Implementation Rules
-
-All stages should preserve these invariants:
-
-- Producer applications own source bundle creation.
-- `distributor` owns validation, transformation, publication, destination state, and future notification hooks.
-- Source bundle state is defined by `manifest.json`.
-- Destination publication state is defined by `.distributor.json`.
-- `manifest.json` is not copied to the destination as destination state.
-- Pipelines have exactly one source and one or more destinations.
-- Transform and publish policy are destination-specific.
-- Destructive replacement is allowed only inside a managed destination bundle path. Unsafe force or unmanaged overwrite behavior is deferred.
-- Dry-run behavior should be implemented before broad remote write behavior.
-- Config, bundle, state, publish planning, storage adapters, transforms, and CLI wiring should remain separate packages.
-
-Unless a stage explicitly says otherwise, each implementation prompt should:
-
-1. read the project policy and roadmap documents;
-2. implement only the current stage;
-3. add or update tests for the current stage;
-4. run the relevant test suite;
-5. update documentation only when the implemented behavior now exists;
-6. avoid implementing future roadmap stages early.
-
-## Stage 1: Project Skeleton, CLI Shell, and Baseline Tooling
-
-### Goal
-
-Create the initial Go application structure and a minimal executable `distributor` command with no business behavior beyond version/help output and placeholder commands.
-
-### Scope
-
-Implement the accepted package skeleton from `docs/roadmap/packages.md` at the level needed for compilation.
-
-Create:
-
-```text
-cmd/distributor/main.go
-internal/cli/
-internal/app/
-internal/config/
-internal/logging/
-```
-
-Initial CLI commands:
-
-- `distributor --help`
-- `distributor version`
-- `distributor run`
-- `distributor validate`
-- `distributor inspect`
-
-At this stage, `run`, `validate`, and `inspect` may return clear “not implemented” errors, but the command structure should be present.
-
-### Notes
-
-Prefer a small CLI dependency only if the project already standardizes on one. Otherwise, the standard library is acceptable for the first pass.
-
-Add a version variable that can later be set at build time.
-
-### Tests
-
-Add tests for:
-
-- command construction if testable;
-- version string behavior if exposed through a package;
-- basic package compilation.
-
-### Completion Criteria
-
-- `go test ./...` passes.
-- `go run ./cmd/distributor --help` works.
-- `go run ./cmd/distributor version` works.
-- Placeholder operational commands fail clearly and intentionally.
-
-## Stage 2: Config Schema, Loading, Defaults, and Validation
-
-### Goal
-
-Implement the MVP `config.yml` schema described in `docs/roadmap/config.md`.
-
-### Scope
-
-Create config structs for:
-
-- top-level config;
-- pipelines;
-- source backend config;
-- destination backend config;
-- validation policy;
-- publish policy;
-- transform policy;
-- transfer/replacement policy;
-- backend-specific local, SSH, and S3 fields.
-
-Support loading YAML from a file path.
-
-Implement validation for:
-
-- required top-level `pipelines`;
-- unique pipeline ids;
-- required pipeline `id`, `source`, and non-empty `destinations`;
-- unique destination ids within a pipeline;
-- supported backend names: `local`, `ssh`, `s3`;
-- required backend fields;
-- supported validation action: `fail`;
-- supported transfer actions;
-- valid `publish` policy;
-- valid Markdown-to-HTML transform config.
-
-Default behavior should match `docs/roadmap/config.md`.
-
-### CLI Integration
-
-Add `--config` to `run`.
-
-For this stage, `distributor run --config config.yml --dry-run` may only load and validate config, then print a concise summary of configured pipelines and destinations.
-
-### Tests
-
-Add unit tests for:
-
-- valid minimal local-to-local config;
-- valid fan-out config;
-- valid local, SSH, and S3 backend configs;
-- duplicate pipeline ids;
-- duplicate destination ids;
-- missing required fields;
-- unsupported backend;
-- invalid transfer action;
-- invalid validation action, including `warn`.
-
-### Completion Criteria
-
-- Config load/default/validate behavior is implemented and tested.
-- `distributor run --config <file> --dry-run` validates config and prints a summary.
-- No bundle discovery or publication occurs yet.
-
-## Stage 3: Storage Abstraction, Local Backend, and Fake Backend
-
-### Goal
-
-Introduce the storage backend abstraction before bundle validation so source discovery, validation, and publication are backend-agnostic from the start.
-
-### Scope
-
-Create:
-
-```text
-internal/storage/backend.go
-internal/storage/registry.go
-internal/storage/path.go
-internal/storage/errors.go
-internal/adapters/local/backend.go
-internal/storage/fake/
-```
-
-Implement the storage contract in `docs/roadmap/storage.md`, including backend-rooted logical paths, hybrid byte/stream IO, metadata, traversal, typed errors, managed deletion, and efficient destination emptiness helper behavior.
-
-The fake backend should exist for unit tests of config, bundle, state, and publish logic without real local, SSH, or S3 IO.
-
-### Safety Requirements
-
-The local backend must:
-
-- clean and join paths safely;
-- reject path traversal;
-- reject unsafe destructive deletion requests;
-- avoid following symlinks for source bundle files unless explicitly supported;
-- avoid deleting configured roots;
-- classify destination bundle emptiness deterministically.
-
-### Tests
-
-Add tests for:
-
-- path validation;
-- backend byte and stream read/write behavior;
-- `Stat`, `Walk`, and materialized deterministic traversal helper behavior;
-- traversal rejection;
-- symlink entry reporting and source-read rejection;
-- staged write behavior where testable;
-- typed storage errors and helper predicates;
-- managed deletion guard behavior;
-- early-stop destination emptiness helper behavior;
-- fake backend parity for core package tests.
-
-### Completion Criteria
-
-- Local backend implements the storage interface.
-- Fake backend can support bundle and publish tests without external services.
-- `go test ./...` passes.
-- No SSH or S3 implementation exists yet.
-
-## Stage 4: Source Bundle Manifest, Digest, Validation, and Discovery
-
-### Goal
-
-Implement the source bundle contract from `docs/roadmap/contracts.md` through the storage abstraction.
-
-### Scope
-
-Create:
-
-```text
-internal/bundle/manifest.go
-internal/bundle/digest.go
-internal/bundle/validate.go
-internal/bundle/discover.go
-```
-
-Implement:
-
-- parsing `manifest.json`;
-- strict required field validation, including `schema_version: 1`;
-- RFC3339 `created` parsing;
-- lowercase `sha256:<64 hex>` digest validation;
-- source file path safety checks;
-- duplicate logical file path rejection;
-- per-file SHA256 validation;
-- per-file size validation;
-- bundle digest validation using the canonical ordered file-record algorithm;
-- deterministic storage-backed bundle discovery under a source root;
-- nested manifest detection and failure.
-
-Discovery and validation should use `internal/storage` rather than direct `os` APIs. The local CLI path should be adapted to the local backend.
-
-### CLI Integration
-
-Implement:
-
-```text
-distributor validate <path>
-distributor inspect <path>
-```
-
-For local paths:
-
-- `validate` should validate either a single bundle directory or a tree containing bundles.
-- `inspect` should print a concise normalized summary of discovered bundle ids, relative paths, created timestamps, digest values, and files.
-
-### Tests
-
-Add fixture bundles under a testdata directory.
-
-Test:
-
-- valid bundle;
-- invalid JSON;
-- missing required fields;
-- invalid schema version;
-- invalid timestamp;
-- invalid digest format;
-- unsafe file paths;
-- duplicate normalized file paths;
-- missing files;
-- size mismatch;
-- per-file digest mismatch;
-- bundle digest mismatch;
-- canonical bundle digest reference fixture;
-- multiple discovered bundles in deterministic order;
-- nested manifests fail.
-
-### Completion Criteria
-
-- Storage-backed bundle validation is deterministic and well-tested.
-- `distributor validate <path>` works for local bundle fixtures.
-- `distributor inspect <path>` works for local bundle fixtures.
-- No destination publication occurs yet.
-
-## Stage 5: Destination State Contract and Comparison Logic
-
-### Goal
-
-Implement `.distributor.json` parsing, validation, and source-to-destination comparison.
-
-### Scope
-
-Create:
-
-```text
-internal/state/distributor.go
-internal/state/compare.go
-internal/state/validate.go
-```
-
-Implement the destination state schema from `docs/roadmap/contracts.md`, including:
-
-- `schema_version`;
-- optional `distributor_version`;
-- `pipeline_id`;
-- `destination_id`;
-- `published_at`;
-- embedded normalized source manifest;
-- outputs array;
-- output file metadata.
-
-Implement comparison outcomes:
-
-- destination absent;
-- destination unmanaged/non-empty;
-- destination state pipeline or destination id mismatch;
-- same source manifest;
-- same source id, destination older;
-- same source id, destination newer;
-- same source id and same created but different digest;
-- different source id;
-- invalid destination state.
-
-### Tests
-
-Add unit tests for every comparison outcome.
-
-Test validation for:
-
-- valid state;
-- missing fields;
-- invalid schema version;
-- invalid embedded source manifest;
-- invalid output metadata;
-- malformed published timestamp.
-
-Timestamps should parse RFC3339 input and distributor-written timestamps should normalize to RFC3339 UTC.
-
-### Completion Criteria
-
-- Destination state can be parsed and validated independently.
-- Source manifest to destination state comparison is deterministic and fully tested.
-- No publication execution occurs yet.
-
-## Stage 6: Publish Planning, Dry-Run, and Local-to-Local Publication Without Transform
-
-### Goal
-
-Implement the core publish planner and execute local-to-local publication for source files only.
-
-### Scope
-
-Create:
-
-```text
-internal/publish/plan.go
-internal/publish/reconcile.go
-internal/publish/safety.go
-internal/publish/output.go
-internal/publish/execute.go
-```
-
-Implement planning for one source bundle to one destination based on:
-
-- source manifest;
-- destination config;
-- publish policy;
-- transfer policy;
-- existing `.distributor.json`;
-- destination path state.
-
-Actions should include:
-
-- publish new;
-- replace older destination;
-- skip same;
-- skip destination newer;
-- fail conflict;
-- fail unmanaged destination.
-
-Implement local-to-local execution for `publish.source: true` and `publish.html: false`.
-
-Execution should:
-
-- copy listed source files selected by publish policy;
-- write `.distributor.json` with copied source output metadata;
-- avoid copying source `manifest.json` as destination state;
-- preserve relative bundle paths from source root beneath destination root;
-- detect destination output collisions before writing;
-- use staging or equivalent cleanup behavior for local writes;
-- support fan-out to multiple local destinations;
-- support dry-run without writes.
-
-### CLI Integration
-
-`distributor run --config <file>` should now execute local-to-local pipelines when configured.
-
-`--dry-run` should print the planned action for each discovered bundle and destination.
-
-### Tests
-
-Add integration-style tests using temp directories for:
-
-- new local publication;
-- no-op when destination state matches;
-- replacement when destination state is older;
-- skip when destination state is newer;
-- fail on conflict;
-- fail on unmanaged non-empty destination;
-- fail on output path collision;
-- fan-out from one source to two local destinations;
-- failed local write does not leave a destination that appears unmanaged on retry;
-- dry-run performs no writes;
-- `.distributor.json` is written correctly.
-
-### Completion Criteria
-
-- Local-to-local source-file publication works end to end.
-- Dry-run produces meaningful planned actions.
-- Destination state is authoritative.
-- No Markdown-to-HTML transform exists yet.
-
-## Stage 7: Markdown-to-HTML Transform and Destination-Specific Publish Policy
-
-### Goal
-
-Add MVP Markdown-to-HTML transformation and destination-specific source/html output selection.
-
-### Scope
-
-Create:
-
-```text
-internal/transform/transform.go
-internal/transform/registry.go
-internal/transform/plan.go
-internal/transform/markdown/markdown.go
-internal/transform/markdown/template.go
-```
-
-Implement only:
-
-```yaml
-transform:
-  markdown_to_html:
-    enabled: true
-    mode: sidecar
-```
-
-MVP sidecar behavior:
-
-- for each listed source artifact ending in `.md`, generate a same-directory `.html` sidecar;
-- preserve the original Markdown file unchanged;
-- do not generate HTML for non-Markdown files;
-- escape or disable raw HTML embedded in Markdown;
-- fail before writing when generated output paths collide with copied source outputs or other generated outputs;
-- record generated output metadata in `.distributor.json`;
-- if `publish.source: false`, do not publish source files;
-- if `publish.html: true`, publish generated HTML files;
-- if `publish.html: true` but transform is disabled or no Markdown files exist, fail with a clear error unless config later defines another behavior.
-
-Use a well-maintained Markdown renderer. Keep HTML templating minimal and deterministic.
-
-### Tests
-
-Add tests for:
-
-- Markdown sidecar generation;
-- source-only destination;
-- HTML-only destination;
-- source-plus-HTML destination;
-- no mutation of source bundle;
-- generated output metadata in `.distributor.json`;
-- failure when HTML publication is requested without transform support;
-- failure when generated HTML collides with a source artifact path;
-- raw HTML in Markdown is escaped or disabled consistently;
-- deterministic output for a fixture Markdown file.
-
-### Completion Criteria
-
-- Local-to-local publication supports source-only, HTML-only, and source-plus-HTML destinations.
-- Generated outputs are recorded in destination state.
-- Dry-run reports transform outputs that would be generated.
-
-## Stage 8: No-Op Notification Stage, Pipeline Polish, and Local MVP Checkpoint
-
-### Goal
-
-Add the internal no-op notification stage and polish orchestration around per-destination outcomes.
-
-### Scope
-
-Create:
-
-```text
-internal/notify/notify.go
-internal/notify/noop.go
-```
-
-Integrate a no-op notifier after actual successful publication or replacement. Skipped destinations should not invoke the notifier in the MVP.
-
-Clarify orchestration behavior when one destination fails. For MVP, fan-out should be deterministic and sequential. Continue planning and reporting later destinations where safe, but return non-zero if any destination fails.
-
-Improve run summary output:
-
-- pipeline id;
-- source backend;
-- discovered bundle count;
-- destination ids;
-- action per bundle/destination;
-- final status.
-
-### Tests
-
-Add tests for:
-
-- notifier is invoked at the expected orchestration point where testable;
-- pipeline failure when a destination fails;
-- run summary contains meaningful status information;
-- dry-run does not invoke write-side effects.
-
-### Completion Criteria
-
-- The pipeline shape includes notification as an internal no-op stage.
-- Run output is useful for unattended operation logs.
-- Local MVP behavior remains passing and is ready for one real local producer pipeline.
-
-Stages 1 through 8 define the local MVP checkpoint. Later stages extend the local MVP with remote backends, cross-backend hardening, user-facing documentation sync, and release readiness.
-
-## Stage 9: Native SSH/SFTP Backend Roadmap Extension
-
-### Goal
-
-Implement SSH/SFTP storage backend support for sources and destinations.
-
-### Scope
-
-Create:
-
-```text
-internal/adapters/ssh/backend.go
-internal/adapters/ssh/config.go
-```
-
-Implement the storage backend interface over native SSH/SFTP.
-
-Required config:
-
-```yaml
-backend: ssh
-uri: ssh://user@example.com:22
-path: /remote/root
-```
-
-Authentication expectations:
-
-- prefer SSH agent by default;
-- use known_hosts validation by default where practical;
-- do not require passwords in YAML;
-- optional key-file support may be implemented if straightforward, but should not distract from agent-based auth.
-
-Support SSH/SFTP backend as both source and destination:
-
-- local -> ssh;
-- ssh -> local;
-- ssh -> ssh where feasible through staging or streaming.
-
-### Safety Requirements
-
-The SSH backend must enforce the same logical path safety rules as the local backend.
-
-Deletion must remain limited to managed destination bundle paths guarded by valid `.distributor.json`.
-
-### Tests
-
-Unit-test path handling and config validation.
-
-If practical, add integration tests that can be skipped unless an SSH test endpoint is configured through environment variables. Do not require a live SSH server for normal `go test ./...`.
-
-### Completion Criteria
-
-- SSH/SFTP backend compiles and satisfies the storage interface.
-- Backend config validation is tested.
-- Normal tests do not depend on a live SSH server.
-- At least local-to-SSH and SSH-to-local flows are documented or manually testable.
-
-## Stage 10: S3-Compatible Backend Roadmap Extension
-
-### Goal
-
-Implement S3-compatible backend support for sources and destinations.
-
-### Scope
-
-Create:
-
-```text
-internal/adapters/s3/backend.go
-internal/adapters/s3/config.go
-```
-
-Required config should align with `docs/roadmap/config.md`:
-
-```yaml
-backend: s3
-endpoint: https://s3.example.com
-bucket: reports
-prefix: some/prefix
-region: us-east-1
-force_path_style: true
-credentials:
-  access_key_id_env: DISTRIBUTOR_S3_ACCESS_KEY_ID
-  secret_access_key_env: DISTRIBUTOR_S3_SECRET_ACCESS_KEY
-```
-
-Implement storage operations over S3 object keys through the common storage contract:
-
-- `ReadFile` and `OpenReader`;
-- `WriteFile` and `WriteFrom`;
-- `Stat`;
-- `Walk` using object-list pagination where available;
-- `HasAny` with early stop for destination emptiness checks;
-- `DeleteManagedBundle`;
-- read/write `.distributor.json` through normal storage operations.
-
-Set reasonable content types where available:
-
-- `.md`: `text/markdown; charset=utf-8`;
-- `.html`: `text/html; charset=utf-8`;
-- `.json`: `application/json`;
-- `.txt`: `text/plain; charset=utf-8`.
-
-Support S3 backend as both source and destination.
-
-### Safety Requirements
-
-Treat S3 prefixes as object trees. Do not assume real directories exist.
-
-Deletion must be limited to destination bundle prefixes that are confirmed managed by `.distributor.json`.
-
-### Tests
-
-Add unit tests for:
-
-- config validation;
-- key/prefix normalization;
-- content type selection;
-- path traversal rejection;
-- publish planning with S3 destination state fixtures.
-
-If practical, add integration tests gated by environment variables or a local S3-compatible test service. Normal `go test ./...` must not require live S3 credentials.
-
-### Completion Criteria
-
-- S3 backend compiles and satisfies the storage interface.
-- S3 source and destination flows are supported through the common pipeline path.
-- Normal tests do not require live S3.
-
-## Stage 11: Cross-Backend End-to-End Coverage and Hardening Roadmap Extension
-
-### Goal
-
-Harden the MVP across backend combinations, destination policies, and failure cases.
-
-### Scope
-
-Add end-to-end coverage for representative scenarios:
-
-- local source -> local archive destination;
-- local source -> local HTML destination;
-- local source -> two destinations with different publish policies;
-- local source -> SSH destination, where integration credentials exist;
-- local source -> S3 destination, where integration credentials exist;
-- S3 source -> local destination, where integration credentials exist;
-- SSH source -> local destination, where integration credentials exist.
-
-Improve logging and error messages for:
-
-- invalid config;
-- invalid source manifest;
-- digest mismatch;
-- destination conflict;
-- unmanaged destination path;
-- backend read/write/list failures;
-- transform failures.
-
-Ensure all destructive paths have tests or explicit safeguards.
-
-### Tests
-
-Add or expand tests for:
-
-- dry-run across multiple destinations;
-- partial failure behavior;
-- repeated run idempotency;
-- older/newer destination state behavior;
-- destination state output metadata accuracy;
-- generated HTML output metadata accuracy.
-
-### Completion Criteria
-
-- MVP behavior is reliable across implemented backend types.
-- Error messages identify pipeline id, destination id, bundle id, and reason where practical.
-- Idempotent repeated runs behave as expected.
-
-## Stage 12: User-Facing Documentation Sync
-
-### Goal
-
-Update documentation to reflect implemented MVP behavior.
-
-### Scope
-
-Following `docs/policy/documentation.md`, create or update user-facing documentation only for implemented features.
-
-Likely docs:
-
-```text
-README.md
-docs/config.md
-docs/cli.md
-docs/policy/architecture.md
-docs/internal/bundles.md
-docs/internal/backends.md
-```
-
-Document:
-
-- what `distributor` does;
-- bundle contract summary;
-- `.distributor.json` role;
-- example source bundle;
-- example local-to-local config;
-- example local-to-S3 config;
-- example local-to-SSH config;
-- `run`, `validate`, and `inspect` commands;
-- dry-run behavior;
-- replacement and safety rules;
-- Markdown-to-HTML transform behavior;
-- environment-variable credential handling.
-
-Move roadmap material to historical/planning status only if your documentation policy allows it. Do not describe unimplemented notification adapters as available features.
-
-### Tests
-
-Run the full test suite.
-
-If docs include command examples, verify that basic examples correspond to actual CLI behavior.
-
-### Completion Criteria
-
-- User-facing docs describe the implemented MVP accurately.
-- Roadmap docs no longer masquerade as implemented behavior.
-- `go test ./...` passes.
-
-## Stage 13: MVP Release Readiness Pass
-
-### Goal
-
-Perform a final pre-release quality pass.
-
-### Scope
-
-Review:
-
-- package boundaries against `docs/policy/architecture.md`;
-- package layout against `docs/roadmap/packages.md`;
-- implemented contracts against `docs/roadmap/contracts.md`;
-- implemented config behavior against `docs/roadmap/config.md`;
-- docs against `docs/policy/documentation.md`;
-- destructive operation safety;
-- logs and errors for unattended operation;
-- command UX;
-- test coverage for core invariants.
-
-Add any missing small tests or docs discovered during review.
-
-Do not add new product features in this stage.
-
-### Completion Criteria
-
-- MVP is ready to deploy against one real producer pipeline.
-- A dry-run can be performed safely against a real source and destination.
-- Repeated runs are idempotent.
-- Destructive replacement cannot occur outside managed destination bundle paths.
-- Final docs accurately reflect the application.
-
-## Stage 14: Explicit Force Overwrite Roadmap Extension
-
-### Goal
-
-Introduce explicit operator-requested force behavior for controlled overwrite cases that are intentionally outside the local MVP.
-
-### Scope
-
-Add a CLI-only force option such as:
-
-```bash
-distributor run --config config.yml --force
-```
-
-Define and implement force planning for:
-
-- unmanaged non-empty destination paths;
-- destination state with a different source id;
-- destination state with matching source id and created timestamp but different digest;
-- destination state with mismatched `pipeline_id` or `destination_id`;
-- destination newer than source when the transfer policy explicitly allows replacement.
-
-Force behavior must be explicit per run. It should not be a persistent default in config for this stage.
-
-Update transfer policy validation to allow broader values only when force behavior is implemented and documented:
-
-- `on_destination_newer: replace`
-- `on_conflict: replace`
-
-### Safety Requirements
-
-- Dry-run must show every file or object that would be written or deleted before a forced run.
-- Force must still never delete above the resolved destination bundle path or configured destination prefix.
-- Filesystem replacement should remain staged where practical.
-- S3 replacement must remain constrained to the destination bundle prefix.
-- Logs must clearly mark force decisions and include pipeline id, destination id, bundle id, and reason.
-
-### Tests
-
-Add tests for:
-
-- force rejected when the flag is absent;
-- unmanaged non-empty destination overwritten only with force;
-- different source id overwritten only with force and allowed policy;
-- same id and created but different digest overwritten only with force and allowed policy;
-- destination newer replaced only with force and allowed policy;
-- pipeline or destination id mismatch overwritten only with force and allowed policy;
-- dry-run reports destructive force actions without writing;
-- destructive paths remain bounded to the destination bundle path.
-
-### Completion Criteria
-
-- Force overwrite behavior is explicit, logged, dry-runnable, and test-covered.
-- Default non-force behavior remains unchanged and conservative.
-
-## Deferred Post-MVP Work
-
-The following items are intentionally outside the MVP unless explicitly pulled into a later roadmap:
-
-- email notifications;
-- ntfy/Gotify/Pushover notifications;
-- RSS/Atom feed generation;
-- static site index pages beyond sidecar HTML output;
-- templated HTML themes beyond a minimal deterministic template;
-- destination path remapping rules;
-- full plugin architecture;
-- web UI;
-- report editing;
-- producer pipeline execution;
-- database-backed state;
-- complex retry queues;
-- concurrent publication workers;
-- symlink support;
-- warning-only digest mismatch handling;
-- password-based SSH authentication in YAML.
+# Roadmap
+
+This directory contains only future, deferred, or aspirational work for
+`distributor`. Implemented behavior is documented in the current user,
+operator, internal, policy, integration, and example documentation:
+
+- `README.md`
+- `docs/cli.md`
+- `docs/config.md`
+- `docs/operations.md`
+- `docs/troubleshooting.md`
+- `docs/internal/`
+- `docs/integrations/markdown.md`
+- `docs/policy/`
+- `examples/`
+
+`distributor` currently supports local, SSH/SFTP, and S3-compatible source and
+destination backends; producer bundle creation through `pkg/bundle` and
+`distributor manifest create`; configured source validation and inspection;
+Markdown sidecar and `index.html` publication; archive and fixed destination
+path mapping; destination link metadata; shared text/JSON CLI output; and
+managed destination replacement behavior.
+
+## Future Work
+
+These items are not implemented. They should not be documented as current
+behavior outside `docs/roadmap/` unless a future implementation adds them.
+
+### CLI And Status Output
+
+- Add a root-global output flag only if the command parser is later refactored
+  around shared root options.
+- Add output formats beyond `text` and `json` only if a concrete consumer
+  requires them.
+- Add a versioned JSON schema reference after the first JSON-capable release.
+- Add destination-state inspection behind an explicit flag such as
+  `--with-destinations` if operators need fan-out status diagnostics from
+  `inspect`.
+- Add additional status or inspection presentation for destination primary
+  links beyond the current `run --format json` result model.
+
+### Producer Workflows
+
+- Add a no-write manifest creation mode, such as writing manifest JSON to
+  stdout, if producer pipelines need to capture manifests directly.
+- Add broader producer workflow helpers, such as richer ignore rules or
+  template scaffolding, if real producer use cases require them.
+- Add remote or storage-backed producer writers only if producer applications
+  need to assemble bundles outside the local filesystem.
+
+### Publication And Transform Behavior
+
+- Add a separate collection or site-index transform if distributor needs
+  multi-page aggregation.
+- Add richer transform metadata only if future state consumers need more than
+  the transform name and output path.
+- Add custom HTML index output names only if fixed `index.html` is too limiting
+  for real deployments.
+- Add richer fixed-destination source selection policies if deployments need
+  something other than newest-by-`created`.
+- Add stricter handling for equal latest timestamps if timestamp ties become
+  common in producer workflows.
+- Add higher-level status or approval workflows for fixed-root replacements if
+  dry-run output is not enough operational protection.
+- Add richer link policies only if `auto`, `html`, and `source` prove
+  insufficient.
+
+### State And Compatibility
+
+- Define a post-release destination state schema bump policy before introducing
+  materially incompatible state changes.
+- Add warning-only digest mismatch handling only if an operator workflow needs
+  publication to continue after validation failures.
+- Add compatibility parsing for legacy SSH URI config only if migration support
+  is required.
+
+### Backends, Security, And Deployment
+
+- Add authentication mechanisms beyond the implemented SSH agent/key and S3
+  credential paths only when a concrete backend workflow requires them.
+- Add broad recursive destination deletion outside managed bundle paths only if
+  a future design can preserve the current safety boundary.
+- Add concurrent fan-out publishing only if runtime profiling shows it is
+  needed.
+- Add streaming, resumable, or multipart S3 uploads only if object sizes make
+  the current write path insufficient.
+- Add cloud-provider-specific IAM integration docs only when the repository
+  includes tested provider-specific behavior.
+- Add repository-managed packaging, release, and deployment automation when the
+  release process is ready to be standardized.
+
+## Roadmap Maintenance
+
+When adding future roadmap work:
+
+- describe user-visible behavior and safety boundaries;
+- define which current docs must change after implementation;
+- keep examples secret-free and runnable or clearly environment-gated;
+- keep workflow labels out of production code, tests, config fields, and
+  user-facing documentation;
+- run focused tests for the changed behavior and `go test ./...` for
+  cross-package changes.

docs/roadmap/packages.md

@@ -1,526 +0,0 @@
-# Package Layout Roadmap
-
-This roadmap defines the proposed package layout, boundaries, and implementation responsibilities for the `distributor` MVP.
-
-`distributor` is expected to be a domain-agnostic bundle publisher. Producer applications emit source bundles containing `manifest.json`; `distributor` validates those bundles and publishes selected source and generated artifacts to one or more configured destinations.
-
-This document is roadmap material. It describes the intended package design before implementation and should move into `docs/internal/` only after corresponding behavior exists.
-
-## Accepted Package Layout
-
-```text
-cmd/distributor/
-  main.go
-
-internal/app/
-  app.go
-  run.go
-  pipeline.go
-
-internal/cli/
-  root.go
-  run.go
-  validate.go
-  inspect.go
-
-internal/config/
-  config.go
-  defaults.go
-  load.go
-  validate.go
-
-internal/bundle/
-  manifest.go
-  digest.go
-  validate.go
-  discover.go
-
-internal/state/
-  distributor.go
-  compare.go
-  validate.go
-
-internal/storage/
-  backend.go
-  registry.go
-  path.go
-  errors.go
-
-internal/storage/fake/
-  backend.go
-
-internal/adapters/local/
-  backend.go
-
-internal/adapters/ssh/
-  backend.go
-  config.go
-
-internal/adapters/s3/
-  backend.go
-  config.go
-
-internal/transform/
-  transform.go
-  registry.go
-  plan.go
-
-internal/transform/markdown/
-  markdown.go
-  template.go
-
-internal/publish/
-  plan.go
-  execute.go
-  output.go
-  reconcile.go
-  safety.go
-
-internal/notify/
-  notify.go
-  noop.go
-
-internal/logging/
-  logging.go
-```
-
-## Package Responsibilities
-
-### `cmd/distributor`
-
-Application entrypoint only.
-
-Responsibilities:
-
-- call CLI execution;
-- translate process exit status;
-- avoid business logic.
-
-Non-responsibilities:
-
-- config loading;
-- backend construction;
-- bundle validation;
-- publish decisions.
-
-### `internal/cli`
-
-CLI command definitions, flags, argument parsing, and command wiring.
-
-Expected MVP commands:
-
-- `distributor run` — run configured pipelines.
-- `distributor run --dry-run` — plan without modifying destinations.
-- `distributor run --pipeline <id>` — run one configured pipeline.
-- `distributor validate <path>` — validate a source bundle or source tree where feasible.
-- `distributor inspect <path>` — inspect a bundle or destination state where feasible.
-
-Boundaries:
-
-- CLI should call `internal/app` use cases.
-- CLI should not parse manifests directly except through application APIs.
-- CLI should not import backend adapter implementation details unless only for registration side effects.
-
-### `internal/app`
-
-Application orchestration and top-level use cases.
-
-Responsibilities:
-
-- load and validate configuration;
-- construct configured pipelines;
-- build source and destination backends through registries;
-- orchestrate discovery, validation, planning, publishing, and notification;
-- coordinate dry-run output;
-- run destination fan-out deterministically and sequentially;
-- aggregate destination outcomes into run-level failure behavior.
-
-Core orchestration shape:
-
-```text
-for each selected pipeline:
-  open source backend
-  discover source bundles
-  for each source bundle:
-    validate source manifest and digest
-    for each destination:
-      inspect .distributor.json
-      build publish plan
-      transform as required by that destination
-      execute publish plan unless dry-run
-      run noop notifier after actual publication or replacement
-```
-
-Boundaries:
-
-- `internal/app` composes packages but should not contain backend-specific logic.
-- Publish decisions should live in `internal/publish`, not inline in orchestration.
-- Destination state comparison should live in `internal/state` or `internal/publish`, not CLI code.
-
-### `internal/config`
-
-Configuration structs, defaults, loading, precedence, and validation.
-
-Responsibilities:
-
-- load `/usr/local/etc/distributor/config.yml` by default;
-- support `--config` override;
-- apply defaults;
-- validate required fields;
-- validate pipeline ids and destination ids;
-- validate backend-specific config shapes;
-- validate transform and publish policy combinations.
-
-MVP config model:
-
-```yaml
-pipelines:
-  - id: weather-daily
-    source:
-      backend: local
-      path: /var/spool/distributor/weather
-    validation:
-      on_digest_mismatch: fail
-    destinations:
-      - id: markdown-archive
-        backend: s3
-        endpoint: https://s3.example.com
-        bucket: reports
-        prefix: weather/archive
-        region: us-east-1
-        force_path_style: true
-        publish:
-          source: true
-          html: false
-        transfer:
-          on_destination_same: skip
-          on_destination_older: replace
-          on_destination_newer: skip
-          on_conflict: fail
-      - id: static-site
-        backend: ssh
-        uri: ssh://deploy@example.com:22
-        path: /srv/www/weather
-        publish:
-          source: false
-          html: true
-        transform:
-          markdown_to_html:
-            enabled: true
-            mode: sidecar
-```
-
-Configuration principles:
-
-- one source per pipeline;
-- one or more destinations per pipeline;
-- transforms are destination-specific;
-- publish policy is destination-specific;
-- secrets should use environment variables, secret files, SSH agent, or standard credential mechanisms rather than raw YAML values.
-
-### `internal/bundle`
-
-Source bundle contract and validation.
-
-Responsibilities:
-
-- parse source `manifest.json`;
-- represent source manifests and files;
-- discover bundle roots beneath a configured source root;
-- validate required manifest fields;
-- validate RFC3339 `created` values;
-- validate relative paths;
-- validate file existence, size, per-file SHA-256, and bundle digest;
-- expose normalized source bundle models to other packages.
-
-Core types:
-
-```go
-type Manifest struct {
-    SchemaVersion int
-    ID      string
-    Digest  string
-    Created time.Time
-    Files   []ManifestFile
-}
-
-type ManifestFile struct {
-    Path   string
-    SHA256 string
-    Size   int64
-}
-
-type Bundle struct {
-    RootRelativePath string
-    Manifest         Manifest
-}
-```
-
-Boundaries:
-
-- `internal/bundle` does not know about `.distributor.json`.
-- `internal/bundle` does not know about destinations, transforms, or notification.
-- `internal/bundle` may use the storage abstraction to read source files, but it should not import backend adapter packages.
-
-### `internal/state`
-
-Destination state contract for `.distributor.json`.
-
-Responsibilities:
-
-- parse `.distributor.json`;
-- validate destination state;
-- represent copied source outputs and generated outputs;
-- embed the source manifest used for publication;
-- compare destination state against a current source manifest;
-- classify destination state as same, older, newer, conflict, absent, invalid, or unmanaged.
-
-Core types:
-
-```go
-type DistributorState struct {
-    SchemaVersion int
-    DistributorVersion string
-    PipelineID    string
-    DestinationID string
-    PublishedAt   time.Time
-    Source        SourceState
-    Outputs       []OutputFile
-}
-
-type SourceState struct {
-    Manifest bundle.Manifest
-}
-
-type OutputFile struct {
-    Path       string
-    Kind       string // source | generated
-    SourcePath string
-    Transform  string
-    SHA256     string
-    Size       int64
-}
-```
-
-Comparison rules:
-
-- same source manifest: skip;
-- same source id, older destination source `created`: replace;
-- same source id, newer destination source `created`: skip;
-- same source id, same `created`, different digest: conflict;
-- different source id: conflict;
-- pipeline id or destination id mismatch: conflict;
-- absent state: publish only if safe;
-- unmanaged non-empty path: fail.
-
-Boundaries:
-
-- `internal/state` owns destination state semantics, not publish execution.
-- `internal/state` should not know about S3, SSH/SFTP, local filesystem details, or Markdown rendering.
-
-### `internal/storage`
-
-Backend abstraction and shared storage types.
-
-Responsibilities:
-
-- define storage backend interfaces;
-- define object/file metadata types;
-- define path/prefix helpers;
-- define common storage errors;
-- provide backend registry mechanisms;
-- provide a fake backend for core package tests.
-
-The detailed storage contract is defined in `docs/roadmap/storage.md`. Core application code should use that storage interface for backend-rooted logical paths, byte and stream IO, metadata, traversal, typed errors, emptiness checks, and managed deletion.
-
-Destructive APIs should remain narrow. Prefer managed deletion of files recorded in `.distributor.json` instead of broad recursive deletion.
-
-Boundaries:
-
-- `internal/storage` should not contain backend implementation details.
-- Adapter dependencies must not leak through storage interfaces.
-- The fake backend exists for tests and should not become an application runtime backend.
-
-### `internal/adapters/local`
-
-Local filesystem backend.
-
-Responsibilities:
-
-- implement `storage.Backend` for local paths;
-- clean and constrain paths;
-- perform safe reads/writes/listing/deletion;
-- use atomic writes where practical;
-- reject unsafe path traversal;
-- handle symlink policy explicitly.
-
-Testing expectations:
-
-- use temporary directories;
-- verify path traversal rejection;
-- verify write and delete safety.
-
-### `internal/adapters/ssh`
-
-SSH/SFTP backend.
-
-Responsibilities:
-
-- implement `storage.Backend` over SSH/SFTP;
-- support `uri` and `path` config;
-- prefer native SFTP implementation;
-- use SSH agent, key files, known hosts, or documented auth mechanisms;
-- avoid raw passwords in config unless explicitly designed and documented later;
-- translate SSH/SFTP errors into storage-level errors.
-
-Testing expectations:
-
-- core app tests should use fake backends;
-- adapter tests may use local test servers or targeted integration tests if practical;
-- do not require a real production SSH host for normal unit tests.
-
-### `internal/adapters/s3`
-
-S3-compatible object storage backend.
-
-Responsibilities:
-
-- implement `storage.Backend` over S3-compatible object storage;
-- support endpoint, bucket, prefix, region, and force-path-style configuration;
-- support standard credential mechanisms or explicit environment-variable references;
-- treat S3 as an object tree, not a filesystem;
-- set reasonable content types where practical;
-- guard against prefix/root deletion mistakes.
-
-Testing expectations:
-
-- core app tests should use fake backends;
-- adapter behavior may be tested through mocks, local S3-compatible services, or narrow integration tests;
-- config examples should avoid real secrets.
-
-### `internal/transform`
-
-Transform interfaces, registry, and transform planning.
-
-Responsibilities:
-
-- define transform interfaces;
-- register available transforms;
-- represent transform requests and outputs;
-- keep transform execution independent of destination backend details.
-
-Boundaries:
-
-- transforms operate on source bundle content and destination transform config;
-- transforms do not publish outputs;
-- transforms do not mutate source bundles;
-- transforms should return generated output metadata for `.distributor.json`.
-
-### `internal/transform/markdown`
-
-Markdown-to-HTML implementation.
-
-Responsibilities:
-
-- render listed Markdown files to HTML;
-- support MVP sidecar behavior, such as `report.md` -> `report.html`;
-- record generated output path, source path, transform name, SHA-256, and size;
-- optionally use embedded templates if needed.
-
-MVP scope:
-
-- Markdown to HTML only;
-- no PDF generation;
-- no email-specific HTML;
-- no complex theming unless required for basic output correctness.
-
-### `internal/publish`
-
-Destination planning, reconciliation, safety checks, and publish execution.
-
-Responsibilities:
-
-- inspect destination state;
-- plan destination action;
-- enforce destination conflict rules;
-- enforce destructive-operation safety rules;
-- detect output path collisions before writing;
-- combine source files and transform outputs according to destination publish policy;
-- write destination outputs;
-- write `.distributor.json`;
-- use staging or equivalent cleanup behavior where practical;
-- support dry-run planning;
-- report skipped, replaced, failed, and published actions.
-
-Action model:
-
-```text
-publish
-replace
-skip_same
-skip_destination_newer
-fail_conflict
-fail_unmanaged
-```
-
-Boundaries:
-
-- publish logic should not parse CLI flags;
-- publish logic should not know adapter implementation details;
-- publish logic should use `internal/state` for destination state semantics;
-- publish logic should use `internal/storage` interfaces for IO.
-
-### `internal/notify`
-
-Notification stage abstraction.
-
-MVP responsibilities:
-
-- define notifier interface;
-- implement no-op notifier;
-- preserve future extension point for email, ntfy, Gotify, RSS update hooks, or other notification channels.
-
-Future notification rules:
-
-- notify only after successful publication to the relevant destination or destinations;
-- notification must be idempotent with respect to source id, digest, pipeline id, and destination id where applicable;
-- notification should not run for skipped or failed publications unless explicitly configured.
-
-### `internal/logging`
-
-Logging setup and helpers.
-
-Responsibilities:
-
-- centralize structured logging setup;
-- ensure logs omit secrets;
-- provide consistent fields for pipeline id, bundle id, destination id, backend, path, action, and reason.
-
-## Deferred Ideas
-
-The following are intentionally out of MVP unless separately accepted in a later roadmap:
-
-- email, ntfy, Gotify, or other real notification adapters;
-- RSS/Atom feed generation;
-- PDF generation;
-- web UI;
-- full-text search;
-- dynamic plugin loading;
-- arbitrary transform chains;
-- workflow DAGs;
-- producer execution;
-- complex templating/theming;
-- bidirectional sync;
-- backup semantics.
-
-## Key Invariants
-
-- Producer apps own source bundle creation.
-- `distributor` owns destination publication state.
-- Source `manifest.json` is not copied as destination state.
-- Destination `.distributor.json` is the managed sentinel.
-- One pipeline has one source and one or more destinations.
-- Transform and publish policy are destination-specific.
-- Source files are canonical; HTML is derived.
-- Destructive replacement is allowed only inside managed destination bundle paths.
-- Core logic must be testable without real S3, SSH, or remote services.

docs/roadmap/storage.md

@@ -1,265 +0,0 @@
-# Storage Interface Roadmap
-
-This roadmap defines the planned `internal/storage` contract for the `distributor` MVP. The goal is to give bundle validation, destination state inspection, publish planning, and backend adapters one consistent IO boundary without leaking local filesystem, SSH/SFTP, or S3-specific behavior into core packages.
-
-## Purpose and Invariants
-
-The storage layer is responsible for safe, backend-rooted access to files, objects, prefixes, and destination bundle paths.
-
-Core invariants:
-
-- Backends are opened at configured roots.
-- Core packages operate on backend-rooted logical paths, not absolute filesystem paths or raw object keys.
-- Backend adapters translate native storage behavior into common storage entries and typed errors.
-- Destructive operations remain narrow and managed.
-- Staging or atomic write behavior belongs behind the storage interface where practical.
-- The fake backend exists for tests only and must not be registered as a runtime backend.
-
-## Logical Path Model
-
-Storage paths are slash-separated logical paths relative to an already configured backend root.
-
-File paths:
-
-- must be non-empty;
-- must be relative;
-- must be clean;
-- must not contain `.` or `..` segments;
-- must not start with `/`;
-- must not contain backslashes;
-- must not resolve outside the backend root.
-
-Prefix paths use the same slash-separated model. A prefix may be empty to represent the backend root for traversal and destination emptiness checks.
-
-Prefix matching must preserve logical path boundaries. A prefix of `foo` matches `foo` and entries below `foo/`; it must not match a sibling path such as `foobar`. Backends that map logical paths to object keys must apply the same normalized boundary rule after combining configured backend prefixes with caller-provided logical prefixes.
-
-Backends own conversion from logical paths to native paths or object keys. Core packages should not construct local filesystem paths, SFTP paths, or S3 object keys directly.
-
-## Core Interface Shape
-
-The MVP should use a hybrid byte and stream interface:
-
-```go
-type Backend interface {
-    ReadFile(ctx context.Context, path string) ([]byte, error)
-    OpenReader(ctx context.Context, path string) (io.ReadCloser, error)
-    WriteFile(ctx context.Context, path string, data []byte, opts WriteOptions) (Entry, error)
-    WriteFrom(ctx context.Context, path string, r io.Reader, opts WriteOptions) (Entry, error)
-    Stat(ctx context.Context, path string) (Entry, error)
-    Walk(ctx context.Context, prefix string, opts WalkOptions, fn WalkFunc) error
-    HasAny(ctx context.Context, prefix string) (bool, error)
-    DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts DeleteOptions) error
-}
-```
-
-Byte helpers are expected to cover manifests, destination state, small source artifacts, and generated outputs. Stream methods are included from the start for backend flexibility and larger future artifacts.
-
-Write operations should create required parent directories or prefixes as needed.
-
-Concrete option and callback types should use this shape:
-
-```go
-type WalkOptions struct {
-    Recursive bool
-    Limit     int
-}
-
-type WalkFunc func(Entry) error
-
-var ErrStopWalk = errors.New("stop walk")
-
-type WriteOptions struct {
-    ContentType  string
-    Overwrite    bool
-    PreferAtomic bool
-    Size         int64
-    SizeKnown    bool
-}
-
-type DeleteOptions struct {
-    IgnoreMissing  bool
-    PruneEmptyDirs bool
-}
-```
-
-`WalkOptions.Limit == 0` means no explicit limit. `SizeKnown` applies primarily to `WriteFrom`; byte writes can infer size from the provided data.
-
-## Entries and Metadata
-
-Storage metadata should be represented by an `Entry` model with at least:
-
-- backend-relative logical path;
-- entry type;
-- size, where available.
-
-Entry types:
-
-- `file`: filesystem file or object-storage object;
-- `directory`: filesystem directory or logical prefix;
-- `symlink`: local filesystem symlink;
-- `other`: unknown or unsupported native entry type.
-
-`Stat` returns metadata for one exact logical path. It may report a real filesystem directory, symlink, file, or exact object. It must not synthesize S3-like directory metadata solely because objects exist below a prefix; callers that need prefix existence or destination emptiness must use `HasAny` or `Walk`.
-
-`Walk` traverses entries below a prefix and calls a callback for each entry. `WalkOptions` should include:
-
-- whether traversal is recursive;
-- an optional entry limit for callers that only need to know whether content exists.
-
-If a callback returns `ErrStopWalk`, traversal stops successfully and `Walk` returns nil. Any other callback error stops traversal and is returned with storage context where practical. If `WalkOptions.Limit` is greater than zero, reaching the limit stops traversal successfully.
-
-Backends may stream or paginate traversal internally. S3-compatible adapters should not need to load a whole prefix into memory to satisfy traversal.
-
-Raw traversal is not required to be lexically sorted. A helper that materializes walk results for bundle discovery, tests, or CLI output should sort entries lexically by logical path before returning them.
-
-`HasAny` reports whether at least one entry exists below a prefix. It should stop as soon as content is found.
-
-Source validation must reject symlink entries reported by local `Stat` or `Walk`.
-
-## Read Behavior
-
-`ReadFile` reads the whole object into memory and is appropriate for MVP manifest, state, and ordinary artifact handling.
-
-`OpenReader` returns a stream for callers that need to copy or hash content without requiring a second storage-specific API. Callers must close the returned reader.
-
-Both read methods must:
-
-- validate logical paths before backend access;
-- reject directories, prefixes, symlinks, and unsupported entries;
-- return typed not-found and invalid-path errors where applicable.
-
-## Write Behavior
-
-`WriteOptions` should include:
-
-- content type, when the destination backend can use it;
-- overwrite permission;
-- atomic or staged write preference;
-- optional known size for stream writes.
-
-Backends own staging and atomic behavior where practical:
-
-- Local backend writes to a temporary file in the destination directory and renames or promotes into place.
-- SSH/SFTP backend should use a temporary remote file and rename where available.
-- S3-compatible backend treats a successful object PUT as publish-on-success and applies content type metadata.
-
-Remote adapters may buffer or spool `WriteFrom` input when needed to satisfy backend requirements such as content length, multipart upload, or retry behavior. Callers that know the stream size should set `SizeKnown` and `Size`.
-
-If overwrite is false and the target exists, writes should fail with an already-exists error.
-
-`WriteFile` and `WriteFrom` should return the written `Entry`, including final path and size where available.
-
-`DeleteOptions` should include:
-
-- whether missing managed output paths are ignored;
-- whether empty parent directories may be pruned for filesystem-like backends.
-
-## Managed Deletion
-
-The storage interface should expose a guarded managed deletion operation rather than raw recursive delete.
-
-`DeleteManagedBundle(ctx, bundlePath, managedOutputPaths, opts)` may delete only:
-
-- files or objects listed in valid `.distributor.json.outputs`;
-- `.distributor.json` at the destination bundle path;
-- empty directories created by those files, for filesystem-like backends.
-
-`managedOutputPaths` are relative to the destination bundle path. The backend validates each path and resolves it under `bundlePath`.
-
-If `bundlePath == ""`, deletion may remove explicit managed files at the destination root, but must never delete the root itself.
-
-Prefix or recursive deletion is out of MVP scope. A future force-overwrite stage may add broader behavior, but it must remain explicit and separately documented.
-
-## Destination Emptiness
-
-Destination emptiness should use `HasAny(prefix)` and typed not-found behavior. Callers that only need emptiness must not materialize a full recursive traversal.
-
-Rules:
-
-- A local destination bundle path is empty when the directory does not exist or exists with no entries.
-- An S3-compatible prefix is empty when no objects exist below that exact destination bundle prefix.
-- Entries outside the exact destination bundle path or prefix do not affect emptiness.
-
-## Error Model
-
-Storage should expose typed error categories with wrapping context. Callers should use helper predicates rather than string matching.
-
-Required categories:
-
-- not found;
-- already exists;
-- not empty;
-- invalid path;
-- conflict;
-- permission;
-- temporary;
-- unsupported;
-- unknown.
-
-Adapters should translate backend-native errors into these categories while preserving useful operation, backend, path, and cause context.
-
-## Adapter Expectations
-
-### Local
-
-The local backend should:
-
-- constrain all operations beneath the configured root;
-- reject traversal and absolute logical paths;
-- report symlinks through metadata;
-- reject symlink reads for source artifacts;
-- use staged writes where practical;
-- perform managed deletion only for explicit managed files and `.distributor.json`;
-- clean up empty directories created by managed outputs where safe.
-
-### Fake
-
-The fake backend should:
-
-- be in-memory and deterministic;
-- implement the same logical path validation rules;
-- support `Stat`, `Walk`, `HasAny`, byte reads and writes, stream reads and writes, managed deletion, and destination emptiness helper behavior;
-- support configured symlink entries for validation tests;
-- be used only by tests.
-
-### SSH/SFTP
-
-The SSH/SFTP backend should:
-
-- use native SFTP operations;
-- enforce the same logical path rules as local storage;
-- use temporary file plus rename for staged writes where available;
-- translate remote errors into storage error categories;
-- avoid exposing SSH or SFTP dependency types through `internal/storage`.
-
-### S3-Compatible
-
-The S3-compatible backend should:
-
-- treat prefixes as object trees, not real directories;
-- normalize configured prefix plus logical path into object keys;
-- use object PUT as publish-on-success;
-- set content type from `WriteOptions`;
-- implement traversal and emptiness by exact prefix;
-- use backend pagination for traversal where available;
-- allow `HasAny` to stop after the first matching object;
-- constrain managed deletion to listed output objects and `.distributor.json`.
-
-## Tests and Fixtures
-
-Storage implementation stages should test:
-
-- path validation rejects absolute paths, traversal, empty file paths, backslashes, and dot segments;
-- `Walk` visits backend-rooted logical paths under a prefix and supports recursive traversal;
-- a materializing helper sorts walk results lexically for deterministic tests and CLI output;
-- `HasAny` returns quickly for non-empty prefixes without requiring full traversal;
-- `ReadFile` and `OpenReader` return equivalent bytes;
-- `WriteFile` and `WriteFrom` honor overwrite and content-type options;
-- local staged writes do not leave final files on failure where testable;
-- managed deletion deletes only state-listed files and `.distributor.json`;
-- managed deletion never deletes destination root or unlisted files;
-- destination emptiness helper handles missing, empty, and non-empty local paths;
-- S3-compatible traversal can use pagination without loading a whole prefix into memory;
-- symlink entries are reported and rejected by source validation;
-- typed errors are usable through helper predicates;
-- fake backend behavior matches local backend semantics relevant to core tests.

docs/troubleshooting.md

@@ -0,0 +1,394 @@
+# Distributor Troubleshooting
+
+## `load config ... no such file or directory`
+
+Likely cause: `run` could not find the config path. If `--config` is omitted, the default path is `/usr/local/etc/distributor/config.yml`.
+
+Diagnostic:
+
+```sh
+ls -l <config-path>
+```
+
+Safe fix: pass an existing config path with `--config`, or install a config at the default path. See [configuration](config.md).
+
+## `parse config ... field not found`
+
+Likely cause: the YAML contains an unknown field. Config loading rejects unknown keys.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run
+```
+
+Safe fix: compare the file to the reference in [configuration](config.md) and remove or rename unsupported fields.
+
+## `validate config ... backend ... is unsupported`
+
+Likely cause: a source or destination uses a backend name other than `local`, `ssh`, or `s3`.
+
+Diagnostic:
+
+```sh
+rg -n "backend:" <config-path>
+```
+
+Safe fix: use `backend: local`, `backend: ssh`, or `backend: s3` for executable workflows.
+
+## `--format: format must be text or json`
+
+Likely cause: a command was run with an unsupported output format.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --help
+```
+
+Safe fix: use `--format text` or `--format json`. Help and usage output are always text.
+
+## `--format json` wrote no JSON output
+
+Likely cause: the command failed before it could construct a result, such as a missing config file, invalid arguments, unreadable secrets directory, or source setup failure.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --format json
+```
+
+Safe fix: read the stderr error and fix the setup problem. JSON mode writes a document only after the command has enough information to construct a result.
+
+## `configured source mode requires --pipeline`
+
+Likely cause: `validate` or `inspect` was run with `--config` but without an explicit pipeline id.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor validate --help
+go run ./cmd/distributor inspect --help
+```
+
+Safe fix: add `--pipeline <pipeline-id>`. Configured source diagnostics require an explicit pipeline even when the config contains one pipeline.
+
+## `does not accept a local path with --config, --pipeline, or --bundle`
+
+Likely cause: local-path mode and configured source mode were mixed in one `validate` or `inspect` command.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor inspect --help
+```
+
+Safe fix: use either `distributor inspect <local-path>` or `distributor inspect --config <path> --pipeline <id>`, not both.
+
+## `--format json` exited non-zero with `ok: false`
+
+Likely cause: `run` began planning or executing destinations, and at least one destination failed while other destination results were still available.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --format json
+```
+
+Safe fix: inspect the top-level `errors` array, `result.actions`, and `result.summary`. Fix the failed destination, then preview with `--dry-run --format json` before retrying.
+
+## `prefix must be a clean relative slash-separated path`
+
+Likely cause: S3 `prefix` contains traversal, dot segments, empty segments, or backslashes after leading and trailing slashes are trimmed.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run
+```
+
+Safe fix: use a clean relative prefix such as `reports/archive`, or omit `prefix`.
+
+## `NoSuchBucket`, `InvalidBucketName`, or `not_found`
+
+Likely cause: the S3 bucket, endpoint, or prefix is wrong, or the configured credentials cannot see the requested object.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run
+```
+
+Safe fix: verify `endpoint`, `bucket`, `region`, `force_path_style`, and `prefix`. For S3-compatible services, keep `force_path_style: true` unless the service requires virtual-host addressing.
+
+## `AccessDenied`, `InvalidAccessKeyId`, or `SignatureDoesNotMatch`
+
+Likely cause: S3 credentials are missing, wrong, empty, or lack permission for the bucket or prefix.
+
+Diagnostic:
+
+```sh
+env | cut -d= -f1 | rg '^(<access-key-variable>|<secret-key-variable>)$'
+ls -l <secrets-directory>
+```
+
+Safe fix: provide both configured credential environment variables through the real environment or `secrets.directory`, or omit explicit credential fields to use the AWS SDK default credential chain.
+
+## S3 endpoint connection failures
+
+Likely cause: the endpoint URL is unreachable, uses the wrong scheme, or does not match the configured path-style mode.
+
+Diagnostic:
+
+```sh
+curl -I <endpoint>
+```
+
+Safe fix: correct `endpoint`, network routing, TLS settings outside distributor, or `force_path_style`. Distributor does not provide insecure TLS bypass configuration.
+
+## `load secrets directory ... no such file or directory`
+
+Likely cause: `secrets.directory` points to a missing directory.
+
+Diagnostic:
+
+```sh
+ls -ld <secrets-directory>
+```
+
+Safe fix: create or mount the directory before running, or remove `secrets.directory` if no credential files are needed.
+
+## `load secrets directory ... permission denied`
+
+Likely cause: the service user cannot read the configured secrets directory.
+
+Diagnostic:
+
+```sh
+ls -ld <secrets-directory>
+namei -l <secrets-directory>
+```
+
+Safe fix: adjust the directory path or deployment permissions so the service user can read the directory. Distributor does not enforce owner, group, or mode policy beyond OS read access.
+
+## `secret filename ... is invalid`
+
+Likely cause: a regular file in `secrets.directory` does not match `[A-Za-z_][A-Za-z0-9_]*`.
+
+Diagnostic:
+
+```sh
+find <secrets-directory> -maxdepth 1 -type f -printf '%f\n'
+```
+
+Safe fix: rename the file to a valid credential environment variable name, or remove it from the secrets directory.
+
+## `credential environment variable ... is not set`
+
+Likely cause: a backend credential field references an environment variable that is absent from both the real process environment and the configured secrets directory.
+
+Diagnostic:
+
+```sh
+env | cut -d= -f1 | rg '^<variable-name>$'
+ls -l <secrets-directory>/<variable-name>
+```
+
+Safe fix: set the real environment variable or create a readable secrets-directory file with the same name.
+
+## `secret ... ignored because the real environment already has that variable`
+
+Likely cause: the real process environment and secrets directory both define the variable with different values.
+
+Diagnostic:
+
+```sh
+env | cut -d= -f1 | rg '^<variable-name>$'
+ls -l <secrets-directory>/<variable-name>
+```
+
+Safe fix: remove one source of the credential or make the deployment intentionally prefer the real environment value. Distributor does not print either value.
+
+## `host is required for ssh backend`
+
+Likely cause: SSH config is missing the structured `host` field, or an old URL-style SSH config is still in use.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run
+```
+
+Safe fix: configure SSH with `host`, optional `user` and `port`, and `path`. SSH URLs are not part of the active config schema.
+
+## `no SSH auth methods configured`
+
+Likely cause: neither an SSH agent nor `ssh_key_file` is available.
+
+Diagnostic:
+
+```sh
+test -n "$SSH_AUTH_SOCK" && ssh-add -l
+ls -l <ssh-key-file>
+```
+
+Safe fix: start an SSH agent with an appropriate key loaded, or configure `ssh_key_file` with a readable private key.
+
+## `host key ... is unknown` or `known_hosts is required`
+
+Likely cause: strict host key checking has no known host key, or `accept-new` cannot persist a new key.
+
+Diagnostic:
+
+```sh
+ls -l <known-hosts-path>
+ssh-keygen -F <host> -f <known-hosts-path>
+```
+
+Safe fix: configure a writable `known_hosts` path for `accept-new`, pre-populate `known_hosts` for `strict`, or explicitly use `host_key_policy: off` only for insecure test environments.
+
+## `host key ... has changed`
+
+Likely cause: the remote server presented a different host key than the one recorded in `known_hosts`.
+
+Diagnostic:
+
+```sh
+ssh-keygen -F <host> -f <known-hosts-path>
+```
+
+Safe fix: verify the server identity out of band before updating `known_hosts`. Do not switch to `host_key_policy: off` to bypass an unexpected changed key.
+
+## `pipeline "<id>" not found`
+
+Likely cause: configured source validation or inspection requested a pipeline id that is not present in the config file.
+
+Diagnostic:
+
+```sh
+rg -n "id:" <config-path>
+```
+
+Safe fix: pass an existing pipeline id with `--pipeline`, or update the config.
+
+## `stat ssh ... not_found`, `stat s3 ... not_found`, or `no bundles found`
+
+Likely cause: the configured source root is wrong, unreadable, or does not contain source bundles.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor validate --config <config-path> --pipeline <pipeline-id>
+```
+
+Safe fix: correct the configured source root, S3 prefix, permissions, or source bundle location. Use `--bundle <path>` only with a source-root-relative bundle directory that contains `manifest.json`.
+
+## `validate command requires a path` or `inspect command requires a path`
+
+Likely cause: `validate` or `inspect` was run without a local path and without configured source mode.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor validate --help
+go run ./cmd/distributor inspect --help
+```
+
+Safe fix: pass a local source bundle directory or local tree, or pass both `--config <path>` and `--pipeline <id>`.
+
+## `no bundles found under "."`
+
+Likely cause: the selected source root does not contain a `manifest.json` source bundle.
+
+Diagnostic:
+
+```sh
+find <source-root> -name manifest.json -print
+```
+
+Safe fix: point the command or config at the directory containing the source bundle, or write a valid `manifest.json` and listed files. See [CLI](cli.md).
+
+## `sha256 mismatch`, `size mismatch`, or `digest mismatch`
+
+Likely cause: a listed source file changed after `manifest.json` was created, or the manifest digest does not match its file list.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor validate <source-root>
+```
+
+Safe fix: regenerate the producer bundle and manifest together. Do not edit destination state to work around source digest failures.
+
+## `destination has content but no distributor state`
+
+Likely cause: the destination path is not empty and has no `.distributor.json` state file, so `distributor` will not claim it as managed.
+
+Diagnostic:
+
+```sh
+find <destination-path> -maxdepth 2 -print
+```
+
+Safe fix: choose an empty destination path or move existing files aside after confirming they are not needed. If the destination should be claimed by distributor, preview with `run --dry-run --force` and publish with `run --force` only after confirming the reported `force_replace` action is bounded to the intended bundle path.
+
+## `fail_conflict`
+
+Likely cause: existing `.distributor.json` belongs to a different pipeline, a different destination, a different source id, or a same-created source with a different digest.
+
+Diagnostic:
+
+```sh
+cat <destination-path>/.distributor.json
+go run ./cmd/distributor inspect <source-root>
+```
+
+Safe fix: verify you are publishing the intended source to the intended destination. Use a separate destination path for unrelated content. If the existing state should be replaced, configure `transfer.on_conflict: replace`, preview with `run --dry-run --force`, then publish with `run --force`.
+
+## `destination is newer and replacement requires --force`
+
+Likely cause: config explicitly allows newer-destination replacement, but the current run did not include `--force`.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run --force
+```
+
+Safe fix: prefer the default `transfer.on_destination_newer: skip` unless replacing newer destination state is intentional. To replace it, keep `transfer.on_destination_newer: replace`, confirm the dry-run output shows `force_replace`, then run with `--force`.
+
+## `force_replace`
+
+Likely cause: the current run used `--force` and publish planning selected a supported destructive replacement.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run --force
+```
+
+Safe fix: inspect the printed pipeline id, destination id, backend, and bundle path. Proceed only if deleting all content within that destination bundle path is intended.
+
+## `destination output path collision`
+
+Likely cause: configured publication would write two outputs to the same destination path, such as publishing a source `report.html` while also generating `report.html` from `report.md`.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run
+```
+
+Safe fix: adjust the source bundle contents or publish policy so source and generated outputs do not collide.
+
+## A run failed after writing some files
+
+Likely cause: a write failed partway through publication. Local, SSH, and S3 execution attempt to clean up outputs written during the failed attempt.
+
+Diagnostic:
+
+```sh
+find <destination-path> -maxdepth 2 -print
+```
+
+Safe fix: use the pipeline id, destination id, backend, and bundle path printed in the run error to inspect the destination before retrying. If only unrelated unmanaged files remain, move them aside or choose a clean destination. Re-run with `--dry-run` before publishing again. See [operations](operations.md).

examples/archive-and-latest.yml

@@ -0,0 +1,29 @@
+pipelines:
+  - id: example-archive-and-latest
+    source:
+      backend: local
+      path: examples/source-bundle
+    destinations:
+      - id: local-source-archive
+        backend: local
+        path: workspace/published/archive-and-latest/archive
+        path_mapping:
+          mode: preserve_relative
+        publish:
+          source: true
+          html: false
+      - id: local-html-latest
+        backend: local
+        path: workspace/published/archive-and-latest/latest
+        path_mapping:
+          mode: fixed
+        links:
+          base_url: https://reports.example.com/latest
+          primary: auto
+        publish:
+          source: false
+          html: true
+        transform:
+          markdown_to_html:
+            enabled: true
+            mode: index

examples/fan-out.yml

@@ -1,28 +1,18 @@
 pipelines:
-  - id: reports
+  - id: example-fan-out
     source:
       backend: local
-      path: /var/spool/distributor/reports
-    validation:
-      on_digest_mismatch: fail
+      path: examples/source-bundle
     destinations:
-      - id: markdown-archive
-        backend: s3
-        endpoint: https://s3.example.com
-        bucket: reports
-        prefix: archive
-        region: us-east-1
-        force_path_style: true
-        credentials:
-          access_key_id_env: DISTRIBUTOR_S3_ACCESS_KEY_ID
-          secret_access_key_env: DISTRIBUTOR_S3_SECRET_ACCESS_KEY
+      - id: local-source-archive
+        backend: local
+        path: workspace/published/fan-out/source
         publish:
           source: true
           html: false
-      - id: static-site
-        backend: ssh
-        uri: ssh://deploy@example.com:22
-        path: /srv/www/reports
+      - id: local-html-site
+        backend: local
+        path: workspace/published/fan-out/html
         publish:
           source: false
           html: true

examples/local-index.yml

@@ -0,0 +1,16 @@
+pipelines:
+  - id: example-index-bundle
+    source:
+      backend: local
+      path: examples/source-bundle
+    destinations:
+      - id: local-index
+        backend: local
+        path: workspace/published/index-bundle
+        publish:
+          source: false
+          html: true
+        transform:
+          markdown_to_html:
+            enabled: true
+            mode: index

examples/s3-destination.yml

@@ -0,0 +1,22 @@
+# Environment-gated example.
+# Replace endpoint, bucket, prefix, and credential environment variable names
+# with values for an S3-compatible service you control before running this config.
+pipelines:
+  - id: example-s3-destination
+    source:
+      backend: local
+      path: examples/source-bundle
+    destinations:
+      - id: s3-archive
+        backend: s3
+        endpoint: https://s3.example.com
+        bucket: reports
+        prefix: distributor/archive
+        region: us-east-1
+        force_path_style: true
+        credentials:
+          access_key_id_env: DISTRIBUTOR_S3_ACCESS_KEY_ID
+          secret_access_key_env: DISTRIBUTOR_S3_SECRET_ACCESS_KEY
+        publish:
+          source: true
+          html: false

examples/ssh-destination.yml

@@ -0,0 +1,21 @@
+# Environment-gated example.
+# Replace host, user, path, ssh_key_file, and known_hosts with values for an
+# SSH/SFTP endpoint you control before running this config.
+pipelines:
+  - id: example-ssh-destination
+    source:
+      backend: local
+      path: examples/source-bundle
+    destinations:
+      - id: ssh-archive
+        backend: ssh
+        host: ssh.example.com
+        user: distributor
+        port: 22
+        path: /srv/distributor/archive
+        ssh_key_file: /home/distributor/.ssh/id_ed25519
+        known_hosts: /home/distributor/.ssh/known_hosts
+        host_key_policy: strict
+        publish:
+          source: true
+          html: false

go.mod

@@ -3,6 +3,31 @@ module gitea.maximumdirect.net/eric/distributor
 go 1.26
 
 require (
+	github.com/aws/aws-sdk-go-v2 v1.41.9
+	github.com/aws/aws-sdk-go-v2/config v1.32.20
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.19
+	github.com/aws/aws-sdk-go-v2/service/s3 v1.102.2
+	github.com/aws/smithy-go v1.26.0
+	github.com/pkg/sftp v1.13.10
 	github.com/yuin/goldmark v1.8.2
+	golang.org/x/crypto v0.52.0
 	gopkg.in/yaml.v3 v3.0.1
 )
+
+require (
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.11 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.25 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.25 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.25 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.26 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.10 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.18 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.25 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.25 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.1.1 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.30.19 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.2 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.42.3 // indirect
+	github.com/kr/fs v0.1.0 // indirect
+	golang.org/x/sys v0.45.0 // indirect
+)

go.sum

@@ -1,5 +1,57 @@
+github.com/aws/aws-sdk-go-v2 v1.41.9 h1:/rYeyO2+HrMztAmxAq9++XJtFMqSIpSsNA0yDGALYq4=
+github.com/aws/aws-sdk-go-v2 v1.41.9/go.mod h1:+HsoOEX80qAVUitj1A2DhCNTjmb3edVyuDypb6LNEeo=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.11 h1:h5+3VT69KUBK24grGuuA5saDJTj2IIjLb9au668Fo5I=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.11/go.mod h1:dnakxebH6UwFvcvujL0LVggYQ8nEvBGjU4G/V79Nv94=
+github.com/aws/aws-sdk-go-v2/config v1.32.20 h1:8VMDnWc/kEzxsI/1ngGM9mG81a8IGmIHD8KLcYGwagc=
+github.com/aws/aws-sdk-go-v2/config v1.32.20/go.mod h1:PuwEpciweIXGULWeOeSTXtSbH4CW9mWdWrhdCKQI1sM=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.19 h1:yuFzSV1U0aRNYCQGVaTY2zW2M/L93pYHnXnrJUphYhU=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.19/go.mod h1:7y63L1kGzeoDlJaQ3Z578KrnmfBut96JjvJUzGwR+YE=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.25 h1:0w6dCiO8iez+YKwRhRBlL1CH/E3GTfdkuzrwj1by8vo=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.25/go.mod h1:9FDWUothyr5RCRAHc45XOiVCzUR8n/IhCYX+uVqw6vk=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.25 h1:Uii3frf9ztec/ABM2/FSH9/z7PLzxfpG8h4RpkUFflQ=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.25/go.mod h1:G6kntsA2GorAxDPbap6xgB2F+amSLUF8GJTi7PUoX44=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.25 h1:r1+/l6m+WaUJF9HISEsNOLHSNj5EXYQxK8VX6Cz9NlA=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.25/go.mod h1:cKf+D+NMDK1LndD7BowHbBZPgR9V0/5HubH0PFWvA+c=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.26 h1:A1PmWU2zfkIm9EyFlJncFXL4W4phML+h8KjltUsCvNQ=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.26/go.mod h1:dY4MRzXEizrD4hqtpKvWVGPX7QleSGGVY+EBolo1RmM=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.10 h1:d5/908OJ4bXg8lyjeMPvXetEKqoDoLi5Owy1zNue3yg=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.10/go.mod h1:a57l7Hwh+FWI+we50g5NPJHYUKeJKfXbc4w8SyXu8Ig=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.18 h1:W/EyPFl9A5rXrtoilfwHYEvzHER+K4SpBPtMXi24Mos=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.18/go.mod h1:UG50K+pvd/uy6xExbobg0rjqFBFZe6I3l75EPDZw4tg=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.25 h1:dD3dhHNglpd98gs72my22Ndqi1hqQGllFFg1F+twfxg=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.25/go.mod h1:0yAbjPfd64gG7mj85RW+fMEYdfBgCRZw8g/oWcL1pjc=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.25 h1:2pQEbwf+/6EDbiit/GcBE2K4IUpMZymaA0kOz3xK978=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.25/go.mod h1:KvT6NCcQ0EZ+ZkVRrlBMt04Po3ok23YELEp7WimhLhM=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.102.2 h1:ie4ElCmUKS26pzrZcIk/lmt4yWjAqLLcawstyQCh298=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.102.2/go.mod h1:zjsomFeX5duj+4PlMB+o4JoWTIx+G0XMyzjYrUbQkN0=
+github.com/aws/aws-sdk-go-v2/service/signin v1.1.1 h1:1VwbP3qMNfxUDEXWki4rCE5iA+44VA1lokTz9HasGzw=
+github.com/aws/aws-sdk-go-v2/service/signin v1.1.1/go.mod h1:vUtyoSj0OPji3kjIVSc/GlKuWEiL33f/WFxl6dmpy/A=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.19 h1:N6pIsdFOW1Kd9S4KyFKXdGRBojPPxkP32+uHFWLv4Hc=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.19/go.mod h1:3gt5WJArFooNmyLONS+h/R4J+o86II8du38IgCwj9dE=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.2 h1:hc+lBYiiTr8Zk4MTzIsQ92MeDWCIDvWGmzKUWOaBcOg=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.2/go.mod h1:hU6fqB3OJA6/ePheD47LQnxvjYk6br6PtQxs+Q9ojvk=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.3 h1:ErklX/7uhSbkAAeyQD/Y1OoQ9hO3SJXQNEgksORW3Js=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.3/go.mod h1:ULe4HCzfKPiR6R3HEurE3b1upEkuk8AkMrOKtaOxKO8=
+github.com/aws/smithy-go v1.26.0 h1:9ouqbi+NyKP7fV3Te7UElCwdAb6Y8uk7LGwPE5tVe/s=
+github.com/aws/smithy-go v1.26.0/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/kr/fs v0.1.0 h1:Jskdu9ieNAYnjxsi0LbQp1ulIKZV1LAFgK1tWhpZgl8=
+github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
+github.com/pkg/sftp v1.13.10 h1:+5FbKNTe5Z9aspU88DPIKJ9z2KZoaGCu6Sr6kKR/5mU=
+github.com/pkg/sftp v1.13.10/go.mod h1:bJ1a7uDhrX/4OII+agvy28lzRvQrmIQuaHrcI1HbeGA=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/yuin/goldmark v1.8.2 h1:kEGpgqJXdgbkhcOgBxkC0X0PmoPG1ZyoZ117rDVp4zE=
 github.com/yuin/goldmark v1.8.2/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
+golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
+golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
+golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
+golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

internal/adapters/local/backend.go

@@ -161,31 +161,10 @@ func (b *Backend) Walk(ctx context.Context, prefix string, opts storage.WalkOpti
 		}
 		return b.translateError(storage.OpWalk, prefix, err)
 	}
-	visited := 0
-	emit := func(entry storage.Entry) error {
-		if err := ctx.Err(); err != nil {
-			return err
-		}
-		if opts.Limit > 0 && visited >= opts.Limit {
-			return storage.ErrStopWalk
-		}
-		visited++
-		if err := fn(entry); err != nil {
-			if errors.Is(err, storage.ErrStopWalk) {
-				return storage.ErrStopWalk
-			}
-			return storage.NewError(storage.OpWalk, backendName, entry.Path, storage.ErrUnknown, err)
-		}
-		return nil
-	}
+	emitter := storage.NewWalkEmitter(ctx, backendName, opts, fn)
 
 	if !info.IsDir() {
-		if err := emit(entryFromInfo(prefix, info)); errors.Is(err, storage.ErrStopWalk) {
-			return nil
-		} else if err != nil {
-			return err
-		}
-		return nil
+		return storage.FinishWalk(emitter.Emit(entryFromInfo(prefix, info)))
 	}
 
 	walkErr := filepath.WalkDir(nativePrefix, func(nativePath string, dirEntry fs.DirEntry, err error) error {
@@ -210,24 +189,13 @@ func (b *Backend) Walk(ctx context.Context, prefix string, opts storage.WalkOpti
 		if err != nil {
 			return b.translateError(storage.OpWalk, logicalPath, err)
 		}
-		return emit(entryFromInfo(logicalPath, info))
+		return emitter.Emit(entryFromInfo(logicalPath, info))
 	})
-	if errors.Is(walkErr, storage.ErrStopWalk) {
-		return nil
-	}
-	return walkErr
+	return storage.FinishWalk(walkErr)
 }
 
 func (b *Backend) HasAny(ctx context.Context, prefix string) (bool, error) {
-	found := false
-	err := b.Walk(ctx, prefix, storage.WalkOptions{Recursive: false, Limit: 1}, func(storage.Entry) error {
-		found = true
-		return storage.ErrStopWalk
-	})
-	if err != nil {
-		return false, err
-	}
-	return found, nil
+	return storage.HasAny(ctx, b, prefix)
 }
 
 func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
@@ -267,6 +235,51 @@ func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, ma
 	return nil
 }
 
+func (b *Backend) DeletePrefix(ctx context.Context, prefix string, opts storage.DeleteOptions) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	nativePrefix, err := b.nativePath(prefix, true)
+	if err != nil {
+		return err
+	}
+	if err := b.rejectSymlinkAncestors(nativePrefix, false); err != nil {
+		return err
+	}
+	if prefix == "" {
+		entries, err := os.ReadDir(nativePrefix)
+		if err != nil {
+			if opts.IgnoreMissing && errors.Is(err, fs.ErrNotExist) {
+				return nil
+			}
+			return b.translateError(storage.OpDeletePrefix, prefix, err)
+		}
+		for _, entry := range entries {
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+			child := filepath.Join(nativePrefix, entry.Name())
+			if err := os.RemoveAll(child); err != nil {
+				return b.translateError(storage.OpDeletePrefix, entry.Name(), err)
+			}
+		}
+		return nil
+	}
+	if _, err := os.Lstat(nativePrefix); err != nil {
+		if opts.IgnoreMissing && errors.Is(err, fs.ErrNotExist) {
+			return nil
+		}
+		return b.translateError(storage.OpDeletePrefix, prefix, err)
+	}
+	if err := os.RemoveAll(nativePrefix); err != nil {
+		return b.translateError(storage.OpDeletePrefix, prefix, err)
+	}
+	if opts.PruneEmptyDirs {
+		b.pruneEmptyParents(filepath.Dir(nativePrefix))
+	}
+	return nil
+}
+
 func (b *Backend) nativePath(logicalPath string, allowEmpty bool) (string, error) {
 	if logicalPath == "" {
 		if !allowEmpty {

internal/adapters/local/backend_test.go

@@ -169,6 +169,30 @@ func TestBackendManagedDeletion(t *testing.T) {
 	}
 }
 
+func TestBackendDeletePrefixStaysWithinPrefix(t *testing.T) {
+	backend := newBackend(t)
+	mustWrite(t, backend, "bundle/report.md", "report")
+	mustWrite(t, backend, "bundle/nested/old.txt", "old")
+	mustWrite(t, backend, "bundle-sibling/keep.txt", "keep")
+	mustWrite(t, backend, "outside.txt", "outside")
+
+	if err := backend.DeletePrefix(context.Background(), "bundle", storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true}); err != nil {
+		t.Fatalf("DeletePrefix() error = %v", err)
+	}
+	if _, err := backend.Stat(context.Background(), "bundle/report.md"); !storage.IsNotFound(err) {
+		t.Fatalf("deleted file stat error = %v, want not found", err)
+	}
+	if _, err := backend.Stat(context.Background(), "bundle/nested/old.txt"); !storage.IsNotFound(err) {
+		t.Fatalf("deleted nested file stat error = %v, want not found", err)
+	}
+	if _, err := backend.Stat(context.Background(), "bundle-sibling/keep.txt"); err != nil {
+		t.Fatalf("sibling stat error = %v", err)
+	}
+	if _, err := backend.Stat(context.Background(), "outside.txt"); err != nil {
+		t.Fatalf("outside stat error = %v", err)
+	}
+}
+
 func TestBackendHasAny(t *testing.T) {
 	backend := newBackend(t)
 	found, err := backend.HasAny(context.Background(), "missing")

internal/adapters/s3/backend.go

@@ -0,0 +1,455 @@
+package s3
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"path"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"github.com/aws/aws-sdk-go-v2/aws"
+	awscfg "github.com/aws/aws-sdk-go-v2/config"
+	"github.com/aws/aws-sdk-go-v2/credentials"
+	awss3 "github.com/aws/aws-sdk-go-v2/service/s3"
+	"github.com/aws/aws-sdk-go-v2/service/s3/types"
+	"github.com/aws/smithy-go"
+)
+
+type Client interface {
+	HeadObject(ctx context.Context, input *awss3.HeadObjectInput, optFns ...func(*awss3.Options)) (*awss3.HeadObjectOutput, error)
+	GetObject(ctx context.Context, input *awss3.GetObjectInput, optFns ...func(*awss3.Options)) (*awss3.GetObjectOutput, error)
+	PutObject(ctx context.Context, input *awss3.PutObjectInput, optFns ...func(*awss3.Options)) (*awss3.PutObjectOutput, error)
+	ListObjectsV2(ctx context.Context, input *awss3.ListObjectsV2Input, optFns ...func(*awss3.Options)) (*awss3.ListObjectsV2Output, error)
+	DeleteObject(ctx context.Context, input *awss3.DeleteObjectInput, optFns ...func(*awss3.Options)) (*awss3.DeleteObjectOutput, error)
+}
+
+type Backend struct {
+	client Client
+	bucket string
+	prefix string
+}
+
+func New(ctx context.Context, options Options) (*Backend, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	options, err := options.normalized()
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.Prefix, storage.ErrInvalidPath, err)
+	}
+	loadOptions := []func(*awscfg.LoadOptions) error{
+		awscfg.WithRegion(options.Region),
+	}
+	if options.AccessKeyID != "" {
+		loadOptions = append(loadOptions, awscfg.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(options.AccessKeyID, options.SecretAccessKey, "")))
+	}
+	cfg, err := awscfg.LoadDefaultConfig(ctx, loadOptions...)
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.Endpoint, storage.ErrUnknown, err)
+	}
+	client := awss3.NewFromConfig(cfg, func(o *awss3.Options) {
+		o.BaseEndpoint = aws.String(options.Endpoint)
+		o.UsePathStyle = options.ForcePathStyle
+	})
+	return NewWithClient(client, options)
+}
+
+func NewWithClient(client Client, options Options) (*Backend, error) {
+	options, err := options.normalized()
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.Prefix, storage.ErrInvalidPath, err)
+	}
+	if client == nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.Bucket, storage.ErrInvalidPath, fmt.Errorf("client is required"))
+	}
+	return &Backend{
+		client: client,
+		bucket: options.Bucket,
+		prefix: options.Prefix,
+	}, nil
+}
+
+func (b *Backend) ReadFile(ctx context.Context, logicalPath string) ([]byte, error) {
+	reader, err := b.OpenReader(ctx, logicalPath)
+	if err != nil {
+		return nil, err
+	}
+	defer reader.Close()
+	data, err := io.ReadAll(reader)
+	if err != nil {
+		return nil, storage.NewError(storage.OpReadFile, BackendName, logicalPath, storage.ErrUnknown, err)
+	}
+	return data, nil
+}
+
+func (b *Backend) OpenReader(ctx context.Context, logicalPath string) (io.ReadCloser, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	key, err := b.objectKey(logicalPath, false)
+	if err != nil {
+		return nil, err
+	}
+	output, err := b.client.GetObject(ctx, &awss3.GetObjectInput{
+		Bucket: aws.String(b.bucket),
+		Key:    aws.String(key),
+	})
+	if err != nil {
+		return nil, b.translateError(storage.OpOpenReader, logicalPath, err)
+	}
+	return output.Body, nil
+}
+
+func (b *Backend) WriteFile(ctx context.Context, logicalPath string, data []byte, opts storage.WriteOptions) (storage.Entry, error) {
+	opts.Size = int64(len(data))
+	opts.SizeKnown = true
+	return b.WriteFrom(ctx, logicalPath, bytes.NewReader(data), opts)
+}
+
+func (b *Backend) WriteFrom(ctx context.Context, logicalPath string, r io.Reader, opts storage.WriteOptions) (storage.Entry, error) {
+	if err := ctx.Err(); err != nil {
+		return storage.Entry{}, err
+	}
+	key, err := b.objectKey(logicalPath, false)
+	if err != nil {
+		return storage.Entry{}, err
+	}
+	if !opts.Overwrite {
+		_, err := b.client.HeadObject(ctx, &awss3.HeadObjectInput{
+			Bucket: aws.String(b.bucket),
+			Key:    aws.String(key),
+		})
+		if err == nil {
+			return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrAlreadyExist, nil)
+		}
+		if !isNotFound(err) {
+			return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+		}
+	}
+	data, err := io.ReadAll(r)
+	if err != nil {
+		return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrUnknown, err)
+	}
+	if opts.SizeKnown && int64(len(data)) != opts.Size {
+		return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrConflict, fmt.Errorf("stream size %d does not match expected size %d", len(data), opts.Size))
+	}
+	contentType := opts.ContentType
+	if contentType == "" {
+		contentType = ContentType(logicalPath)
+	}
+	_, err = b.client.PutObject(ctx, &awss3.PutObjectInput{
+		Bucket:        aws.String(b.bucket),
+		Key:           aws.String(key),
+		Body:          bytes.NewReader(data),
+		ContentLength: aws.Int64(int64(len(data))),
+		ContentType:   aws.String(contentType),
+	})
+	if err != nil {
+		return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+	}
+	return storage.Entry{Path: logicalPath, Type: storage.EntryTypeFile, Size: int64(len(data))}, nil
+}
+
+func (b *Backend) Stat(ctx context.Context, logicalPath string) (storage.Entry, error) {
+	if err := ctx.Err(); err != nil {
+		return storage.Entry{}, err
+	}
+	key, err := b.objectKey(logicalPath, false)
+	if err != nil {
+		return storage.Entry{}, err
+	}
+	output, err := b.client.HeadObject(ctx, &awss3.HeadObjectInput{
+		Bucket: aws.String(b.bucket),
+		Key:    aws.String(key),
+	})
+	if err != nil {
+		return storage.Entry{}, b.translateError(storage.OpStat, logicalPath, err)
+	}
+	size := int64(0)
+	if output.ContentLength != nil {
+		size = *output.ContentLength
+	}
+	return storage.Entry{Path: logicalPath, Type: storage.EntryTypeFile, Size: size}, nil
+}
+
+func (b *Backend) Walk(ctx context.Context, logicalPrefix string, opts storage.WalkOptions, fn storage.WalkFunc) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if err := storage.ValidatePrefix(logicalPrefix); err != nil {
+		return err
+	}
+	emitter := storage.NewWalkEmitter(ctx, BackendName, opts, fn)
+	if logicalPrefix != "" {
+		entry, err := b.Stat(ctx, logicalPrefix)
+		if err == nil {
+			if err := emitter.Emit(entry); err != nil {
+				return storage.FinishWalk(err)
+			}
+			if emitter.LimitReached() {
+				return nil
+			}
+		} else if !storage.IsNotFound(err) {
+			return err
+		}
+	}
+	return storage.FinishWalk(b.walkObjects(ctx, logicalPrefix, opts, emitter.Emit))
+}
+
+func (b *Backend) HasAny(ctx context.Context, logicalPrefix string) (bool, error) {
+	return storage.HasAny(ctx, b, logicalPrefix)
+}
+
+func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	targets, err := storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	if err != nil {
+		return err
+	}
+	for _, target := range targets {
+		if err := b.deleteObject(ctx, storage.OpDeleteManagedBundle, target, opts); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (b *Backend) DeletePrefix(ctx context.Context, logicalPrefix string, opts storage.DeleteOptions) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if err := storage.ValidatePrefix(logicalPrefix); err != nil {
+		return err
+	}
+	found := false
+	if logicalPrefix != "" {
+		key, err := b.objectKey(logicalPrefix, false)
+		if err != nil {
+			return err
+		}
+		_, err = b.client.HeadObject(ctx, &awss3.HeadObjectInput{
+			Bucket: aws.String(b.bucket),
+			Key:    aws.String(key),
+		})
+		if err == nil {
+			found = true
+			if err := b.deleteObject(ctx, storage.OpDeletePrefix, logicalPrefix, storage.DeleteOptions{IgnoreMissing: false}); err != nil {
+				return err
+			}
+		} else if !isNotFound(err) {
+			return b.translateError(storage.OpDeletePrefix, logicalPrefix, err)
+		}
+	}
+	var entries []storage.Entry
+	if err := b.walkObjects(ctx, logicalPrefix, storage.WalkOptions{Recursive: true}, func(entry storage.Entry) error {
+		if entry.Type == storage.EntryTypeFile {
+			entries = append(entries, entry)
+		}
+		return nil
+	}); err != nil {
+		return err
+	}
+	for _, entry := range entries {
+		found = true
+		if err := b.deleteObject(ctx, storage.OpDeletePrefix, entry.Path, storage.DeleteOptions{IgnoreMissing: true}); err != nil {
+			return err
+		}
+	}
+	if !found && !opts.IgnoreMissing {
+		return storage.NewError(storage.OpDeletePrefix, BackendName, logicalPrefix, storage.ErrNotFound, nil)
+	}
+	return nil
+}
+
+func (b *Backend) deleteObject(ctx context.Context, op, logicalPath string, opts storage.DeleteOptions) error {
+	key, err := b.objectKey(logicalPath, false)
+	if err != nil {
+		return err
+	}
+	if key == b.prefix {
+		return storage.NewError(op, BackendName, logicalPath, storage.ErrInvalidPath, nil)
+	}
+	if !opts.IgnoreMissing {
+		_, err := b.client.HeadObject(ctx, &awss3.HeadObjectInput{
+			Bucket: aws.String(b.bucket),
+			Key:    aws.String(key),
+		})
+		if err != nil {
+			return b.translateError(op, logicalPath, err)
+		}
+	}
+	_, err = b.client.DeleteObject(ctx, &awss3.DeleteObjectInput{
+		Bucket: aws.String(b.bucket),
+		Key:    aws.String(key),
+	})
+	if err != nil {
+		if opts.IgnoreMissing && isNotFound(err) {
+			return nil
+		}
+		return b.translateError(op, logicalPath, err)
+	}
+	return nil
+}
+
+func (b *Backend) walkObjects(ctx context.Context, logicalPrefix string, opts storage.WalkOptions, emit func(storage.Entry) error) error {
+	listPrefix, err := b.listPrefix(logicalPrefix)
+	if err != nil {
+		return err
+	}
+	delimiter := ""
+	if !opts.Recursive {
+		delimiter = "/"
+	}
+	var token *string
+	for {
+		output, err := b.client.ListObjectsV2(ctx, &awss3.ListObjectsV2Input{
+			Bucket:            aws.String(b.bucket),
+			Prefix:            aws.String(listPrefix),
+			Delimiter:         aws.String(delimiter),
+			ContinuationToken: token,
+		})
+		if err != nil {
+			return b.translateError(storage.OpWalk, logicalPrefix, err)
+		}
+		entries := entriesFromList(logicalPrefix, b.prefix, output)
+		sort.Slice(entries, func(i, j int) bool { return entries[i].Path < entries[j].Path })
+		for _, entry := range entries {
+			if entry.Path == "" {
+				continue
+			}
+			if err := emit(entry); err != nil {
+				return err
+			}
+		}
+		if output.IsTruncated == nil || !*output.IsTruncated {
+			return nil
+		}
+		token = output.NextContinuationToken
+	}
+}
+
+func entriesFromList(logicalPrefix, rootPrefix string, output *awss3.ListObjectsV2Output) []storage.Entry {
+	seen := make(map[string]storage.Entry)
+	for _, object := range output.Contents {
+		if object.Key == nil {
+			continue
+		}
+		logicalPath := logicalPathFromKey(rootPrefix, *object.Key)
+		if logicalPath == "" || logicalPath == logicalPrefix {
+			continue
+		}
+		size := int64(0)
+		if object.Size != nil {
+			size = *object.Size
+		}
+		seen[logicalPath] = storage.Entry{Path: logicalPath, Type: storage.EntryTypeFile, Size: size}
+	}
+	for _, commonPrefix := range output.CommonPrefixes {
+		if commonPrefix.Prefix == nil {
+			continue
+		}
+		logicalPath := strings.TrimSuffix(logicalPathFromKey(rootPrefix, *commonPrefix.Prefix), "/")
+		if logicalPath == "" || logicalPath == logicalPrefix {
+			continue
+		}
+		seen[logicalPath] = storage.Entry{Path: logicalPath, Type: storage.EntryTypeDirectory}
+	}
+	entries := make([]storage.Entry, 0, len(seen))
+	for _, entry := range seen {
+		entries = append(entries, entry)
+	}
+	return entries
+}
+
+func (b *Backend) objectKey(logicalPath string, allowEmpty bool) (string, error) {
+	if logicalPath == "" {
+		if !allowEmpty {
+			return "", storage.NewError(storage.OpValidatePath, BackendName, logicalPath, storage.ErrInvalidPath, nil)
+		}
+		return b.prefix, nil
+	}
+	if err := storage.ValidatePath(logicalPath); err != nil {
+		return "", err
+	}
+	if b.prefix == "" {
+		return logicalPath, nil
+	}
+	return b.prefix + "/" + logicalPath, nil
+}
+
+func (b *Backend) listPrefix(logicalPrefix string) (string, error) {
+	key, err := b.objectKey(logicalPrefix, true)
+	if err != nil {
+		return "", err
+	}
+	if key != "" {
+		key = strings.TrimSuffix(key, "/") + "/"
+	}
+	return key, nil
+}
+
+func logicalPathFromKey(rootPrefix, key string) string {
+	if rootPrefix == "" {
+		return key
+	}
+	if key == rootPrefix {
+		return ""
+	}
+	return strings.TrimPrefix(key, rootPrefix+"/")
+}
+
+func ContentType(logicalPath string) string {
+	switch strings.ToLower(path.Ext(logicalPath)) {
+	case ".md":
+		return "text/markdown; charset=utf-8"
+	case ".html":
+		return "text/html; charset=utf-8"
+	case ".json":
+		return "application/json"
+	case ".txt":
+		return "text/plain; charset=utf-8"
+	default:
+		return "application/octet-stream"
+	}
+}
+
+func isNotFound(err error) bool {
+	var notFound *types.NotFound
+	if errors.As(err, &notFound) {
+		return true
+	}
+	var apiErr smithy.APIError
+	if errors.As(err, &apiErr) {
+		switch apiErr.ErrorCode() {
+		case "NotFound", "NoSuchKey", "404":
+			return true
+		}
+	}
+	return false
+}
+
+func (b *Backend) translateError(op, logicalPath string, err error) error {
+	kind := storage.ErrUnknown
+	if isNotFound(err) {
+		kind = storage.ErrNotFound
+	} else {
+		var apiErr smithy.APIError
+		if errors.As(err, &apiErr) {
+			switch apiErr.ErrorCode() {
+			case "AccessDenied", "InvalidAccessKeyId", "SignatureDoesNotMatch":
+				kind = storage.ErrPermission
+			case "SlowDown", "RequestTimeout", "ServiceUnavailable", "InternalError":
+				kind = storage.ErrTemporary
+			case "InvalidBucketName", "NoSuchBucket":
+				kind = storage.ErrInvalidPath
+			}
+		}
+	}
+	return storage.NewError(op, BackendName, logicalPath, kind, err)
+}

internal/adapters/s3/backend_test.go

@@ -0,0 +1,442 @@
+package s3
+
+import (
+	"context"
+	"io"
+	"sort"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"github.com/aws/aws-sdk-go-v2/aws"
+	awss3 "github.com/aws/aws-sdk-go-v2/service/s3"
+	"github.com/aws/aws-sdk-go-v2/service/s3/types"
+)
+
+func TestKeyAndPrefixNormalization(t *testing.T) {
+	backend := newTestBackend(t, "root/prefix", nil)
+	key, err := backend.objectKey("bundle/report.md", false)
+	if err != nil {
+		t.Fatalf("objectKey() error = %v", err)
+	}
+	if got, want := key, "root/prefix/bundle/report.md"; got != want {
+		t.Fatalf("objectKey() = %q, want %q", got, want)
+	}
+	listPrefix, err := backend.listPrefix("bundle")
+	if err != nil {
+		t.Fatalf("listPrefix() error = %v", err)
+	}
+	if got, want := listPrefix, "root/prefix/bundle/"; got != want {
+		t.Fatalf("listPrefix() = %q, want %q", got, want)
+	}
+}
+
+func TestPathTraversalRejected(t *testing.T) {
+	backend := newTestBackend(t, "", nil)
+	for _, logicalPath := range []string{"/absolute", "../escape", "a/../b", `a\b`} {
+		t.Run(logicalPath, func(t *testing.T) {
+			if _, err := backend.objectKey(logicalPath, false); err == nil || !storage.IsInvalidPath(err) {
+				t.Fatalf("objectKey() error = %v, want invalid path", err)
+			}
+		})
+	}
+}
+
+func TestContentType(t *testing.T) {
+	tests := map[string]string{
+		"report.md":   "text/markdown; charset=utf-8",
+		"report.html": "text/html; charset=utf-8",
+		"state.json":  "application/json",
+		"summary.txt": "text/plain; charset=utf-8",
+		"data.bin":    "application/octet-stream",
+	}
+	for path, want := range tests {
+		if got := ContentType(path); got != want {
+			t.Fatalf("ContentType(%q) = %q, want %q", path, got, want)
+		}
+	}
+}
+
+func TestStatRequiresExactObject(t *testing.T) {
+	client := newFakeClient(map[string]string{"root/dir/file.txt": "data"})
+	backend := newTestBackend(t, "root", client)
+	_, err := backend.Stat(context.Background(), "dir")
+	if err == nil || !storage.IsNotFound(err) {
+		t.Fatalf("Stat() error = %v, want not found", err)
+	}
+}
+
+func TestWalkIncludesExactObjectAndDescendants(t *testing.T) {
+	client := newFakeClient(map[string]string{
+		"root/bundle":           "marker",
+		"root/bundle/report.md": "report",
+	})
+	backend := newTestBackend(t, "root", client)
+	entries, err := storage.List(context.Background(), backend, "bundle", storage.WalkOptions{Recursive: true})
+	if err != nil {
+		t.Fatalf("List() error = %v", err)
+	}
+	paths := entryPaths(entries)
+	if got, want := paths, []string{"bundle", "bundle/report.md"}; !equalStrings(got, want) {
+		t.Fatalf("paths = %v, want %v", got, want)
+	}
+}
+
+func TestWalkExactObjectHonorsLimitBeforeListingDescendants(t *testing.T) {
+	client := newFakeClient(map[string]string{
+		"root/bundle":           "marker",
+		"root/bundle/report.md": "report",
+	})
+	backend := newTestBackend(t, "root", client)
+	var entries []storage.Entry
+	err := backend.Walk(context.Background(), "bundle", storage.WalkOptions{Recursive: true, Limit: 1}, func(entry storage.Entry) error {
+		entries = append(entries, entry)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("Walk() error = %v", err)
+	}
+	paths := entryPaths(entries)
+	if got, want := paths, []string{"bundle"}; !equalStrings(got, want) {
+		t.Fatalf("paths = %v, want %v", got, want)
+	}
+	if len(client.tokens) != 0 {
+		t.Fatalf("list calls = %d, want none", len(client.tokens))
+	}
+}
+
+func TestHasAnyWithExactObjectStopsBeforeListingDescendants(t *testing.T) {
+	client := newFakeClient(map[string]string{
+		"root/bundle":           "marker",
+		"root/bundle/report.md": "report",
+	})
+	backend := newTestBackend(t, "root", client)
+	found, err := backend.HasAny(context.Background(), "bundle")
+	if err != nil {
+		t.Fatalf("HasAny() error = %v", err)
+	}
+	if !found {
+		t.Fatal("HasAny() = false, want true")
+	}
+	if len(client.tokens) != 0 {
+		t.Fatalf("list calls = %d, want none", len(client.tokens))
+	}
+}
+
+func TestWriteFromChecksOverwriteBeforePut(t *testing.T) {
+	client := newFakeClient(map[string]string{"root/report.md": "old"})
+	backend := newTestBackend(t, "root", client)
+	_, err := backend.WriteFile(context.Background(), "report.md", []byte("new"), storage.WriteOptions{})
+	if err == nil || !storage.IsAlreadyExists(err) {
+		t.Fatalf("WriteFile() error = %v, want already exists", err)
+	}
+	if len(client.putKeys) != 0 {
+		t.Fatalf("put keys = %v, want none", client.putKeys)
+	}
+}
+
+func TestWriteFromPutsNewObjectWithContentType(t *testing.T) {
+	client := newFakeClient(nil)
+	backend := newTestBackend(t, "root", client)
+	entry, err := backend.WriteFile(context.Background(), "report.html", []byte("<p>ok</p>"), storage.WriteOptions{})
+	if err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	if entry.Path != "report.html" || entry.Size != 9 || entry.Type != storage.EntryTypeFile {
+		t.Fatalf("entry = %#v", entry)
+	}
+	if got, want := client.objects["root/report.html"], "<p>ok</p>"; got != want {
+		t.Fatalf("object = %q, want %q", got, want)
+	}
+	if got, want := client.contentTypes["root/report.html"], "text/html; charset=utf-8"; got != want {
+		t.Fatalf("content type = %q, want %q", got, want)
+	}
+}
+
+func TestWalkUsesPagination(t *testing.T) {
+	client := newFakeClient(nil)
+	client.listPages = []awss3.ListObjectsV2Output{
+		{
+			Contents:              []types.Object{{Key: aws.String("root/a.txt"), Size: aws.Int64(1)}},
+			IsTruncated:           aws.Bool(true),
+			NextContinuationToken: aws.String("next"),
+		},
+		{
+			Contents:    []types.Object{{Key: aws.String("root/b.txt"), Size: aws.Int64(2)}},
+			IsTruncated: aws.Bool(false),
+		},
+	}
+	backend := newTestBackend(t, "root", client)
+	entries, err := storage.List(context.Background(), backend, "", storage.WalkOptions{Recursive: true})
+	if err != nil {
+		t.Fatalf("List() error = %v", err)
+	}
+	paths := entryPaths(entries)
+	if got, want := paths, []string{"a.txt", "b.txt"}; !equalStrings(got, want) {
+		t.Fatalf("paths = %v, want %v", got, want)
+	}
+	if got, want := client.tokens, []string{"", "next"}; !equalStrings(got, want) {
+		t.Fatalf("tokens = %v, want %v", got, want)
+	}
+}
+
+func TestHasAnyStopsAfterFirstPage(t *testing.T) {
+	client := newFakeClient(nil)
+	client.listPages = []awss3.ListObjectsV2Output{
+		{
+			Contents:              []types.Object{{Key: aws.String("root/a.txt"), Size: aws.Int64(1)}},
+			IsTruncated:           aws.Bool(true),
+			NextContinuationToken: aws.String("next"),
+		},
+		{
+			Contents:    []types.Object{{Key: aws.String("root/b.txt"), Size: aws.Int64(2)}},
+			IsTruncated: aws.Bool(false),
+		},
+	}
+	backend := newTestBackend(t, "root", client)
+	found, err := backend.HasAny(context.Background(), "")
+	if err != nil {
+		t.Fatalf("HasAny() error = %v", err)
+	}
+	if !found {
+		t.Fatal("HasAny() = false, want true")
+	}
+	if got, want := len(client.tokens), 1; got != want {
+		t.Fatalf("list calls = %d, want %d", got, want)
+	}
+}
+
+func TestWalkNonRecursiveUsesPrefixBoundary(t *testing.T) {
+	client := newFakeClient(map[string]string{
+		"base/dir/file.txt": "nested",
+		"base/file.txt":     "file",
+		"baseball/file.txt": "wrong",
+	})
+	backend := newTestBackend(t, "base", client)
+	entries, err := storage.List(context.Background(), backend, "", storage.WalkOptions{})
+	if err != nil {
+		t.Fatalf("List() error = %v", err)
+	}
+	paths := entryPaths(entries)
+	if got, want := paths, []string{"dir", "file.txt"}; !equalStrings(got, want) {
+		t.Fatalf("paths = %v, want %v", got, want)
+	}
+}
+
+func TestDeleteManagedBundleDeletesOnlyManagedTargets(t *testing.T) {
+	client := newFakeClient(map[string]string{
+		"root/report.md":         "report",
+		"root/.distributor.json": "state",
+		"root/keep.txt":          "keep",
+	})
+	backend := newTestBackend(t, "root", client)
+	err := backend.DeleteManagedBundle(context.Background(), "", []string{"report.md"}, storage.DeleteOptions{IgnoreMissing: true})
+	if err != nil {
+		t.Fatalf("DeleteManagedBundle() error = %v", err)
+	}
+	if _, ok := client.objects["root/report.md"]; ok {
+		t.Fatal("managed output still exists")
+	}
+	if _, ok := client.objects["root/.distributor.json"]; ok {
+		t.Fatal("state file still exists")
+	}
+	if _, ok := client.objects["root/keep.txt"]; !ok {
+		t.Fatal("unmanaged object was deleted")
+	}
+	if got, want := sortedStrings(client.deleteKeys), []string{"root/.distributor.json", "root/report.md"}; !equalStrings(got, want) {
+		t.Fatalf("deleted keys = %v, want %v", got, want)
+	}
+}
+
+func TestDeletePrefixStaysWithinPrefix(t *testing.T) {
+	client := newFakeClient(map[string]string{
+		"root/bundle/report.md":           "report",
+		"root/bundle/nested/old.txt":      "old",
+		"root/bundle-sibling/keep.txt":    "keep",
+		"root/outside.txt":                "outside",
+		"other-root/bundle/report.md":     "other",
+		"root/.distributor-prefix-marker": "marker",
+	})
+	backend := newTestBackend(t, "root", client)
+	if err := backend.DeletePrefix(context.Background(), "bundle", storage.DeleteOptions{IgnoreMissing: true}); err != nil {
+		t.Fatalf("DeletePrefix() error = %v", err)
+	}
+	for _, deleted := range []string{"root/bundle/report.md", "root/bundle/nested/old.txt"} {
+		if _, ok := client.objects[deleted]; ok {
+			t.Fatalf("%s still exists", deleted)
+		}
+	}
+	for _, kept := range []string{"root/bundle-sibling/keep.txt", "root/outside.txt", "other-root/bundle/report.md", "root/.distributor-prefix-marker"} {
+		if _, ok := client.objects[kept]; !ok {
+			t.Fatalf("%s was deleted", kept)
+		}
+	}
+	if got, want := sortedStrings(client.deleteKeys), []string{"root/bundle/nested/old.txt", "root/bundle/report.md"}; !equalStrings(got, want) {
+		t.Fatalf("deleted keys = %v, want %v", got, want)
+	}
+}
+
+func newTestBackend(t *testing.T, prefix string, client *fakeClient) *Backend {
+	t.Helper()
+	if client == nil {
+		client = newFakeClient(nil)
+	}
+	backend, err := NewWithClient(client, Options{
+		Endpoint:       "https://s3.example.com",
+		Bucket:         "reports",
+		Prefix:         prefix,
+		Region:         DefaultRegion,
+		ForcePathStyle: true,
+	})
+	if err != nil {
+		t.Fatalf("NewWithClient() error = %v", err)
+	}
+	return backend
+}
+
+type fakeClient struct {
+	objects      map[string]string
+	contentTypes map[string]string
+	listPages    []awss3.ListObjectsV2Output
+	tokens       []string
+	putKeys      []string
+	deleteKeys   []string
+}
+
+func newFakeClient(objects map[string]string) *fakeClient {
+	copied := make(map[string]string)
+	for key, value := range objects {
+		copied[key] = value
+	}
+	return &fakeClient{
+		objects:      copied,
+		contentTypes: make(map[string]string),
+	}
+}
+
+func (c *fakeClient) HeadObject(ctx context.Context, input *awss3.HeadObjectInput, optFns ...func(*awss3.Options)) (*awss3.HeadObjectOutput, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	value, ok := c.objects[aws.ToString(input.Key)]
+	if !ok {
+		return nil, &types.NotFound{}
+	}
+	return &awss3.HeadObjectOutput{ContentLength: aws.Int64(int64(len(value)))}, nil
+}
+
+func (c *fakeClient) GetObject(ctx context.Context, input *awss3.GetObjectInput, optFns ...func(*awss3.Options)) (*awss3.GetObjectOutput, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	value, ok := c.objects[aws.ToString(input.Key)]
+	if !ok {
+		return nil, &types.NotFound{}
+	}
+	return &awss3.GetObjectOutput{
+		Body:          io.NopCloser(stringsReader(value)),
+		ContentLength: aws.Int64(int64(len(value))),
+	}, nil
+}
+
+func (c *fakeClient) PutObject(ctx context.Context, input *awss3.PutObjectInput, optFns ...func(*awss3.Options)) (*awss3.PutObjectOutput, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	data, err := io.ReadAll(input.Body)
+	if err != nil {
+		return nil, err
+	}
+	key := aws.ToString(input.Key)
+	c.objects[key] = string(data)
+	c.contentTypes[key] = aws.ToString(input.ContentType)
+	c.putKeys = append(c.putKeys, key)
+	return &awss3.PutObjectOutput{}, nil
+}
+
+func (c *fakeClient) ListObjectsV2(ctx context.Context, input *awss3.ListObjectsV2Input, optFns ...func(*awss3.Options)) (*awss3.ListObjectsV2Output, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	c.tokens = append(c.tokens, aws.ToString(input.ContinuationToken))
+	if len(c.listPages) > 0 {
+		index := len(c.tokens) - 1
+		if index >= len(c.listPages) {
+			return &awss3.ListObjectsV2Output{IsTruncated: aws.Bool(false)}, nil
+		}
+		page := c.listPages[index]
+		return &page, nil
+	}
+	return c.dynamicList(input), nil
+}
+
+func (c *fakeClient) DeleteObject(ctx context.Context, input *awss3.DeleteObjectInput, optFns ...func(*awss3.Options)) (*awss3.DeleteObjectOutput, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	key := aws.ToString(input.Key)
+	delete(c.objects, key)
+	c.deleteKeys = append(c.deleteKeys, key)
+	return &awss3.DeleteObjectOutput{}, nil
+}
+
+func (c *fakeClient) dynamicList(input *awss3.ListObjectsV2Input) *awss3.ListObjectsV2Output {
+	prefix := aws.ToString(input.Prefix)
+	delimiter := aws.ToString(input.Delimiter)
+	var contents []types.Object
+	commonPrefixes := make(map[string]struct{})
+	for key, value := range c.objects {
+		if !strings.HasPrefix(key, prefix) {
+			continue
+		}
+		remainder := strings.TrimPrefix(key, prefix)
+		if delimiter != "" {
+			if index := strings.Index(remainder, delimiter); index >= 0 {
+				commonPrefixes[prefix+remainder[:index+1]] = struct{}{}
+				continue
+			}
+		}
+		contents = append(contents, types.Object{Key: aws.String(key), Size: aws.Int64(int64(len(value)))})
+	}
+	sort.Slice(contents, func(i, j int) bool { return aws.ToString(contents[i].Key) < aws.ToString(contents[j].Key) })
+	prefixes := make([]types.CommonPrefix, 0, len(commonPrefixes))
+	for prefix := range commonPrefixes {
+		prefixes = append(prefixes, types.CommonPrefix{Prefix: aws.String(prefix)})
+	}
+	sort.Slice(prefixes, func(i, j int) bool { return aws.ToString(prefixes[i].Prefix) < aws.ToString(prefixes[j].Prefix) })
+	return &awss3.ListObjectsV2Output{
+		Contents:       contents,
+		CommonPrefixes: prefixes,
+		IsTruncated:    aws.Bool(false),
+	}
+}
+
+func stringsReader(value string) io.Reader {
+	return strings.NewReader(value)
+}
+
+func entryPaths(entries []storage.Entry) []string {
+	paths := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		paths = append(paths, entry.Path)
+	}
+	return paths
+}
+
+func sortedStrings(values []string) []string {
+	copied := append([]string(nil), values...)
+	sort.Strings(copied)
+	return copied
+}
+
+func equalStrings(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for index := range a {
+		if a[index] != b[index] {
+			return false
+		}
+	}
+	return true
+}

internal/adapters/s3/integration_test.go

@@ -0,0 +1,39 @@
+package s3
+
+import (
+	"context"
+	"os"
+	"strconv"
+	"testing"
+)
+
+func TestIntegrationS3BackendHasAny(t *testing.T) {
+	endpoint := os.Getenv("DISTRIBUTOR_TEST_S3_ENDPOINT")
+	bucket := os.Getenv("DISTRIBUTOR_TEST_S3_BUCKET")
+	if endpoint == "" || bucket == "" {
+		t.Skip("DISTRIBUTOR_TEST_S3_ENDPOINT and DISTRIBUTOR_TEST_S3_BUCKET are not set")
+	}
+	forcePathStyle := true
+	if raw := os.Getenv("DISTRIBUTOR_TEST_S3_FORCE_PATH_STYLE"); raw != "" {
+		parsed, err := strconv.ParseBool(raw)
+		if err != nil {
+			t.Fatalf("parse DISTRIBUTOR_TEST_S3_FORCE_PATH_STYLE: %v", err)
+		}
+		forcePathStyle = parsed
+	}
+	backend, err := New(context.Background(), Options{
+		Endpoint:        endpoint,
+		Bucket:          bucket,
+		Prefix:          os.Getenv("DISTRIBUTOR_TEST_S3_PREFIX"),
+		Region:          os.Getenv("DISTRIBUTOR_TEST_S3_REGION"),
+		ForcePathStyle:  forcePathStyle,
+		AccessKeyID:     os.Getenv("DISTRIBUTOR_TEST_S3_ACCESS_KEY_ID"),
+		SecretAccessKey: os.Getenv("DISTRIBUTOR_TEST_S3_SECRET_ACCESS_KEY"),
+	})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	if _, err := backend.HasAny(context.Background(), ""); err != nil {
+		t.Fatalf("HasAny(root) error = %v", err)
+	}
+}

internal/adapters/s3/options.go

@@ -0,0 +1,42 @@
+package s3
+
+import (
+	"fmt"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+)
+
+const BackendName = "s3"
+
+const DefaultRegion = "us-east-1"
+
+type Options struct {
+	Endpoint        string
+	Bucket          string
+	Prefix          string
+	Region          string
+	ForcePathStyle  bool
+	AccessKeyID     string
+	SecretAccessKey string
+}
+
+func (o Options) normalized() (Options, error) {
+	if o.Endpoint == "" {
+		return Options{}, fmt.Errorf("endpoint is required")
+	}
+	if o.Bucket == "" {
+		return Options{}, fmt.Errorf("bucket is required")
+	}
+	if o.Region == "" {
+		o.Region = DefaultRegion
+	}
+	o.Prefix = strings.Trim(o.Prefix, "/")
+	if err := storage.ValidatePrefix(o.Prefix); err != nil {
+		return Options{}, fmt.Errorf("prefix: %w", err)
+	}
+	if (o.AccessKeyID == "") != (o.SecretAccessKey == "") {
+		return Options{}, fmt.Errorf("access key id and secret access key must be configured together")
+	}
+	return o, nil
+}

internal/adapters/ssh/auth.go

@@ -0,0 +1,61 @@
+package ssh
+
+import (
+	"fmt"
+	"io"
+	"net"
+	"os"
+
+	cryptossh "golang.org/x/crypto/ssh"
+	"golang.org/x/crypto/ssh/agent"
+)
+
+type agentDialer func(network, address string) (net.Conn, error)
+
+func authMethods(keyFile string) ([]cryptossh.AuthMethod, func(), error) {
+	return authMethodsWithAgent(os.Getenv("SSH_AUTH_SOCK"), net.Dial, keyFile)
+}
+
+func authMethodsWithAgent(agentSocket string, dial agentDialer, keyFile string) ([]cryptossh.AuthMethod, func(), error) {
+	var methods []cryptossh.AuthMethod
+	var closers []io.Closer
+	if agentSocket != "" {
+		methods = append(methods, cryptossh.PublicKeysCallback(func() ([]cryptossh.Signer, error) {
+			conn, err := dial("unix", agentSocket)
+			if err != nil {
+				return nil, err
+			}
+			closers = append(closers, conn)
+			return agent.NewClient(conn).Signers()
+		}))
+	}
+	if keyFile != "" {
+		signer, err := signerFromKeyFile(keyFile)
+		if err != nil {
+			return nil, nil, err
+		}
+		methods = append(methods, cryptossh.PublicKeys(signer))
+	}
+	if len(methods) == 0 {
+		return nil, nil, fmt.Errorf("no SSH auth methods configured; set SSH_AUTH_SOCK or ssh_key_file")
+	}
+	return methods, func() { closeAll(closers) }, nil
+}
+
+func signerFromKeyFile(path string) (cryptossh.Signer, error) {
+	key, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read ssh_key_file %q: %w", path, err)
+	}
+	signer, err := cryptossh.ParsePrivateKey(key)
+	if err != nil {
+		return nil, fmt.Errorf("parse ssh_key_file %q: %w", path, err)
+	}
+	return signer, nil
+}
+
+func closeAll(closers []io.Closer) {
+	for _, closer := range closers {
+		_ = closer.Close()
+	}
+}

internal/adapters/ssh/auth_test.go

@@ -0,0 +1,59 @@
+package ssh
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/x509"
+	"encoding/pem"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestAuthMethodsPreferAgentBeforeKeyFile(t *testing.T) {
+	keyFile := writePrivateKey(t)
+	methods, cleanup, err := authMethodsWithAgent("/tmp/ssh-agent.sock", nil, keyFile)
+	if err != nil {
+		t.Fatalf("authMethodsWithAgent() error = %v", err)
+	}
+	defer cleanup()
+	if got, want := len(methods), 2; got != want {
+		t.Fatalf("auth method count = %d, want %d", got, want)
+	}
+}
+
+func TestAuthMethodsLoadsKeyFile(t *testing.T) {
+	keyFile := writePrivateKey(t)
+	methods, cleanup, err := authMethodsWithAgent("", nil, keyFile)
+	if err != nil {
+		t.Fatalf("authMethodsWithAgent() error = %v", err)
+	}
+	defer cleanup()
+	if got, want := len(methods), 1; got != want {
+		t.Fatalf("auth method count = %d, want %d", got, want)
+	}
+}
+
+func TestAuthMethodsRejectsMissingAuth(t *testing.T) {
+	_, _, err := authMethodsWithAgent("", nil, "")
+	if err == nil {
+		t.Fatal("authMethodsWithAgent() error = nil, want error")
+	}
+}
+
+func writePrivateKey(t *testing.T) string {
+	t.Helper()
+	privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generate key: %v", err)
+	}
+	data := pem.EncodeToMemory(&pem.Block{
+		Type:  "RSA PRIVATE KEY",
+		Bytes: x509.MarshalPKCS1PrivateKey(privateKey),
+	})
+	path := filepath.Join(t.TempDir(), "id_rsa")
+	if err := os.WriteFile(path, data, 0o600); err != nil {
+		t.Fatalf("write private key: %v", err)
+	}
+	return path
+}

internal/adapters/ssh/backend.go

@@ -0,0 +1,487 @@
+package ssh
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path"
+	"sort"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"github.com/pkg/sftp"
+	cryptossh "golang.org/x/crypto/ssh"
+)
+
+type Backend struct {
+	client    *sftp.Client
+	sshClient *cryptossh.Client
+	root      string
+}
+
+func New(ctx context.Context, options Options) (*Backend, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	options, err := options.normalized()
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.Root, storage.ErrInvalidPath, err)
+	}
+	hostKeyCallback, err := hostKeyCallback(options)
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.KnownHosts, storage.ErrInvalidPath, err)
+	}
+	auth, cleanupAuth, err := authMethods(options.KeyFile)
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.KeyFile, storage.ErrPermission, err)
+	}
+	defer cleanupAuth()
+
+	sshClient, err := cryptossh.Dial("tcp", options.address(), &cryptossh.ClientConfig{
+		User:            options.User,
+		Auth:            auth,
+		HostKeyCallback: hostKeyCallback,
+		Timeout:         30 * time.Second,
+	})
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.address(), storage.ErrUnknown, err)
+	}
+	client, err := sftp.NewClient(sshClient)
+	if err != nil {
+		_ = sshClient.Close()
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.address(), storage.ErrUnknown, err)
+	}
+	return &Backend{client: client, sshClient: sshClient, root: options.Root}, nil
+}
+
+func (b *Backend) Close() error {
+	var err error
+	if b.client != nil {
+		err = b.client.Close()
+	}
+	if b.sshClient != nil {
+		if closeErr := b.sshClient.Close(); err == nil {
+			err = closeErr
+		}
+	}
+	return err
+}
+
+func (b *Backend) ReadFile(ctx context.Context, logicalPath string) ([]byte, error) {
+	reader, err := b.OpenReader(ctx, logicalPath)
+	if err != nil {
+		return nil, err
+	}
+	defer reader.Close()
+	data, err := io.ReadAll(reader)
+	if err != nil {
+		return nil, storage.NewError(storage.OpReadFile, BackendName, logicalPath, storage.ErrUnknown, err)
+	}
+	return data, nil
+}
+
+func (b *Backend) OpenReader(ctx context.Context, logicalPath string) (io.ReadCloser, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	nativePath, err := b.nativePath(logicalPath, false)
+	if err != nil {
+		return nil, err
+	}
+	if err := b.rejectSymlinkAncestors(ctx, logicalPath, true); err != nil {
+		return nil, err
+	}
+	info, err := b.client.Lstat(nativePath)
+	if err != nil {
+		return nil, b.translateError(storage.OpOpenReader, logicalPath, err)
+	}
+	if !info.Mode().IsRegular() {
+		return nil, storage.NewError(storage.OpOpenReader, BackendName, logicalPath, storage.ErrUnsupported, nil)
+	}
+	file, err := b.client.Open(nativePath)
+	if err != nil {
+		return nil, b.translateError(storage.OpOpenReader, logicalPath, err)
+	}
+	return file, nil
+}
+
+func (b *Backend) WriteFile(ctx context.Context, logicalPath string, data []byte, opts storage.WriteOptions) (storage.Entry, error) {
+	opts.Size = int64(len(data))
+	opts.SizeKnown = true
+	return b.WriteFrom(ctx, logicalPath, bytes.NewReader(data), opts)
+}
+
+func (b *Backend) WriteFrom(ctx context.Context, logicalPath string, r io.Reader, opts storage.WriteOptions) (storage.Entry, error) {
+	if err := ctx.Err(); err != nil {
+		return storage.Entry{}, err
+	}
+	nativePath, err := b.nativePath(logicalPath, false)
+	if err != nil {
+		return storage.Entry{}, err
+	}
+	if err := b.rejectSymlinkAncestors(ctx, parentOf(logicalPath), true); err != nil {
+		return storage.Entry{}, err
+	}
+	if info, err := b.client.Lstat(nativePath); err == nil {
+		if !opts.Overwrite {
+			return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrAlreadyExist, nil)
+		}
+		if !info.Mode().IsRegular() {
+			return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrConflict, nil)
+		}
+	} else if !isNotExist(err) {
+		return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+	}
+
+	parentNative := path.Dir(nativePath)
+	if err := b.client.MkdirAll(parentNative); err != nil {
+		return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+	}
+
+	writePath := nativePath
+	if opts.PreferAtomic {
+		writePath = path.Join(parentNative, fmt.Sprintf(".distributor-write-%d", time.Now().UnixNano()))
+	}
+	file, err := b.client.Create(writePath)
+	if err != nil {
+		return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+	}
+	cleanup := opts.PreferAtomic
+	defer func() {
+		if cleanup {
+			_ = b.client.Remove(writePath)
+		}
+	}()
+
+	written, copyErr := io.Copy(file, r)
+	closeErr := file.Close()
+	if copyErr != nil {
+		return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrUnknown, copyErr)
+	}
+	if closeErr != nil {
+		return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrUnknown, closeErr)
+	}
+	if opts.SizeKnown && written != opts.Size {
+		return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrConflict, fmt.Errorf("stream size %d does not match expected size %d", written, opts.Size))
+	}
+	if opts.PreferAtomic {
+		if err := b.client.Rename(writePath, nativePath); err != nil {
+			return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+		}
+		cleanup = false
+	}
+	return b.Stat(ctx, logicalPath)
+}
+
+func (b *Backend) Stat(ctx context.Context, logicalPath string) (storage.Entry, error) {
+	if err := ctx.Err(); err != nil {
+		return storage.Entry{}, err
+	}
+	nativePath, err := b.nativePath(logicalPath, true)
+	if err != nil {
+		return storage.Entry{}, err
+	}
+	info, err := b.client.Lstat(nativePath)
+	if err != nil {
+		return storage.Entry{}, b.translateError(storage.OpStat, logicalPath, err)
+	}
+	return entryFromInfo(logicalPath, info), nil
+}
+
+func (b *Backend) Walk(ctx context.Context, prefix string, opts storage.WalkOptions, fn storage.WalkFunc) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	nativePrefix, err := b.nativePath(prefix, true)
+	if err != nil {
+		return err
+	}
+	info, err := b.client.Lstat(nativePrefix)
+	if err != nil {
+		if isNotExist(err) {
+			return nil
+		}
+		return b.translateError(storage.OpWalk, prefix, err)
+	}
+
+	emitter := storage.NewWalkEmitter(ctx, BackendName, opts, fn)
+
+	if !info.IsDir() {
+		return storage.FinishWalk(emitter.Emit(entryFromInfo(prefix, info)))
+	}
+
+	return storage.FinishWalk(b.walkDirectory(ctx, prefix, nativePrefix, opts, emitter.Emit))
+}
+
+func (b *Backend) HasAny(ctx context.Context, prefix string) (bool, error) {
+	return storage.HasAny(ctx, b, prefix)
+}
+
+func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	targets, err := storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	if err != nil {
+		return err
+	}
+	for _, target := range targets {
+		nativePath, err := b.nativePath(target, false)
+		if err != nil {
+			return err
+		}
+		if nativePath == b.root {
+			return storage.NewError(storage.OpDeleteManagedBundle, BackendName, target, storage.ErrInvalidPath, nil)
+		}
+		info, err := b.client.Lstat(nativePath)
+		if err != nil {
+			if opts.IgnoreMissing && isNotExist(err) {
+				continue
+			}
+			return b.translateError(storage.OpDeleteManagedBundle, target, err)
+		}
+		if info.IsDir() {
+			return storage.NewError(storage.OpDeleteManagedBundle, BackendName, target, storage.ErrUnsupported, nil)
+		}
+		if err := b.client.Remove(nativePath); err != nil {
+			return b.translateError(storage.OpDeleteManagedBundle, target, err)
+		}
+		if opts.PruneEmptyDirs {
+			b.pruneEmptyParents(parentOf(target))
+		}
+	}
+	return nil
+}
+
+func (b *Backend) DeletePrefix(ctx context.Context, prefix string, opts storage.DeleteOptions) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if err := storage.ValidatePrefix(prefix); err != nil {
+		return err
+	}
+	var entries []storage.Entry
+	if prefix != "" {
+		entry, err := b.Stat(ctx, prefix)
+		if err != nil {
+			if opts.IgnoreMissing && storage.IsNotFound(err) {
+				return nil
+			}
+			return err
+		}
+		if entry.Type != storage.EntryTypeDirectory {
+			return b.deleteEntry(ctx, entry, opts)
+		}
+		entries = append(entries, entry)
+	}
+	if err := b.Walk(ctx, prefix, storage.WalkOptions{Recursive: true}, func(entry storage.Entry) error {
+		entries = append(entries, entry)
+		return nil
+	}); err != nil {
+		return err
+	}
+	if prefix != "" && len(entries) == 1 {
+		if err := b.deleteEntry(ctx, entries[0], opts); err != nil {
+			return err
+		}
+		if opts.PruneEmptyDirs {
+			b.pruneEmptyParents(parentOf(prefix))
+		}
+		return nil
+	}
+	sort.Slice(entries, func(i, j int) bool {
+		return strings.Count(entries[i].Path, "/") > strings.Count(entries[j].Path, "/")
+	})
+	for _, entry := range entries {
+		if entry.Path == "" {
+			continue
+		}
+		if err := b.deleteEntry(ctx, entry, storage.DeleteOptions{IgnoreMissing: true}); err != nil {
+			return err
+		}
+	}
+	if opts.PruneEmptyDirs {
+		b.pruneEmptyParents(parentOf(prefix))
+	}
+	return nil
+}
+
+func (b *Backend) deleteEntry(ctx context.Context, entry storage.Entry, opts storage.DeleteOptions) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	nativePath, err := b.nativePath(entry.Path, false)
+	if err != nil {
+		return err
+	}
+	var removeErr error
+	if entry.Type == storage.EntryTypeDirectory {
+		removeErr = b.client.RemoveDirectory(nativePath)
+	} else {
+		removeErr = b.client.Remove(nativePath)
+	}
+	if removeErr != nil {
+		if opts.IgnoreMissing && isNotExist(removeErr) {
+			return nil
+		}
+		return b.translateError(storage.OpDeletePrefix, entry.Path, removeErr)
+	}
+	return nil
+}
+
+func (b *Backend) walkDirectory(ctx context.Context, logicalPrefix, nativePrefix string, opts storage.WalkOptions, emit func(storage.Entry) error) error {
+	entries, err := b.client.ReadDir(nativePrefix)
+	if err != nil {
+		return b.translateError(storage.OpWalk, logicalPrefix, err)
+	}
+	sort.Slice(entries, func(i, j int) bool { return entries[i].Name() < entries[j].Name() })
+	for _, info := range entries {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		logicalPath := info.Name()
+		if logicalPrefix != "" {
+			logicalPath = logicalPrefix + "/" + info.Name()
+		}
+		if err := emit(entryFromInfo(logicalPath, info)); err != nil {
+			return err
+		}
+		if opts.Recursive && info.IsDir() {
+			if err := b.walkDirectory(ctx, logicalPath, path.Join(nativePrefix, info.Name()), opts, emit); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func (b *Backend) nativePath(logicalPath string, allowEmpty bool) (string, error) {
+	if logicalPath == "" {
+		if !allowEmpty {
+			return "", storage.NewError(storage.OpValidatePath, BackendName, logicalPath, storage.ErrInvalidPath, nil)
+		}
+		return b.root, nil
+	}
+	if err := storage.ValidatePath(logicalPath); err != nil {
+		return "", err
+	}
+	nativePath := path.Clean(path.Join(b.root, logicalPath))
+	if !withinRoot(b.root, nativePath) {
+		return "", storage.NewError(storage.OpValidatePath, BackendName, logicalPath, storage.ErrInvalidPath, nil)
+	}
+	return nativePath, nil
+}
+
+func (b *Backend) rejectSymlinkAncestors(ctx context.Context, logicalPath string, includeFinal bool) error {
+	if logicalPath == "" {
+		return nil
+	}
+	if err := storage.ValidatePath(logicalPath); err != nil {
+		return err
+	}
+	segments := strings.Split(logicalPath, "/")
+	limit := len(segments)
+	if !includeFinal {
+		limit--
+	}
+	current := ""
+	for index := 0; index < limit; index++ {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		if current == "" {
+			current = segments[index]
+		} else {
+			current += "/" + segments[index]
+		}
+		nativePath, err := b.nativePath(current, false)
+		if err != nil {
+			return err
+		}
+		info, err := b.client.Lstat(nativePath)
+		if err != nil {
+			if isNotExist(err) {
+				return nil
+			}
+			return b.translateError(storage.OpStat, current, err)
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			return storage.NewError(storage.OpStat, BackendName, current, storage.ErrUnsupported, nil)
+		}
+	}
+	return nil
+}
+
+func (b *Backend) pruneEmptyParents(logicalPath string) {
+	for logicalPath != "" {
+		nativePath, err := b.nativePath(logicalPath, false)
+		if err != nil || nativePath == b.root {
+			return
+		}
+		if err := b.client.RemoveDirectory(nativePath); err != nil {
+			return
+		}
+		logicalPath = parentOf(logicalPath)
+	}
+}
+
+func withinRoot(root, candidate string) bool {
+	if candidate == root {
+		return true
+	}
+	if root == "/" {
+		return strings.HasPrefix(candidate, "/")
+	}
+	return strings.HasPrefix(candidate, strings.TrimSuffix(root, "/")+"/")
+}
+
+func parentOf(logicalPath string) string {
+	index := strings.LastIndex(logicalPath, "/")
+	if index == -1 {
+		return ""
+	}
+	return logicalPath[:index]
+}
+
+func isNotExist(err error) bool {
+	return errors.Is(err, fs.ErrNotExist) || errors.Is(err, os.ErrNotExist) || errors.Is(err, sftp.ErrSSHFxNoSuchFile)
+}
+
+func (b *Backend) translateError(op, logicalPath string, err error) error {
+	kind := storage.ErrUnknown
+	switch {
+	case isNotExist(err):
+		kind = storage.ErrNotFound
+	case errors.Is(err, fs.ErrExist), errors.Is(err, os.ErrExist):
+		kind = storage.ErrAlreadyExist
+	case errors.Is(err, fs.ErrPermission), errors.Is(err, os.ErrPermission), errors.Is(err, sftp.ErrSSHFxPermissionDenied):
+		kind = storage.ErrPermission
+	case errors.Is(err, sftp.ErrSSHFxOpUnsupported):
+		kind = storage.ErrUnsupported
+	case errors.Is(err, sftp.ErrSSHFxNoConnection), errors.Is(err, sftp.ErrSSHFxConnectionLost):
+		kind = storage.ErrTemporary
+	}
+	return storage.NewError(op, BackendName, logicalPath, kind, err)
+}
+
+func entryFromInfo(logicalPath string, info fs.FileInfo) storage.Entry {
+	entryType := storage.EntryTypeOther
+	switch {
+	case info.Mode()&os.ModeSymlink != 0:
+		entryType = storage.EntryTypeSymlink
+	case info.Mode().IsRegular():
+		entryType = storage.EntryTypeFile
+	case info.IsDir():
+		entryType = storage.EntryTypeDirectory
+	}
+	return storage.Entry{
+		Path: logicalPath,
+		Type: entryType,
+		Size: info.Size(),
+	}
+}

internal/adapters/ssh/hostkeys.go

@@ -0,0 +1,84 @@
+package ssh
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"os"
+
+	cryptossh "golang.org/x/crypto/ssh"
+	"golang.org/x/crypto/ssh/knownhosts"
+)
+
+func hostKeyCallback(options Options) (cryptossh.HostKeyCallback, error) {
+	switch options.HostKeyPolicy {
+	case HostKeyPolicyOff:
+		return cryptossh.InsecureIgnoreHostKey(), nil
+	case HostKeyPolicyStrict:
+		if options.KnownHosts == "" {
+			return nil, fmt.Errorf("known_hosts is required for strict host key checking")
+		}
+		callback, err := knownhosts.New(options.KnownHosts)
+		if err != nil {
+			return nil, fmt.Errorf("load known_hosts %q: %w", options.KnownHosts, err)
+		}
+		return callback, nil
+	case HostKeyPolicyAcceptNew:
+		return acceptNewHostKeyCallback(options)
+	default:
+		return nil, fmt.Errorf("host_key_policy must be strict, accept-new, or off")
+	}
+}
+
+func acceptNewHostKeyCallback(options Options) (cryptossh.HostKeyCallback, error) {
+	var checker cryptossh.HostKeyCallback
+	if options.KnownHosts != "" {
+		loaded, err := knownhosts.New(options.KnownHosts)
+		if err == nil {
+			checker = loaded
+		} else if !errors.Is(err, os.ErrNotExist) {
+			return nil, fmt.Errorf("load known_hosts %q: %w", options.KnownHosts, err)
+		}
+	}
+	return func(hostname string, remote net.Addr, key cryptossh.PublicKey) error {
+		if checker != nil {
+			err := checker(hostname, remote, key)
+			if err == nil {
+				return nil
+			}
+			var keyErr *knownhosts.KeyError
+			if !errors.As(err, &keyErr) {
+				return err
+			}
+			if len(keyErr.Want) > 0 {
+				return fmt.Errorf("host key for %s has changed: %w", hostname, err)
+			}
+		}
+		if options.ReadOnlyKnownHosts {
+			return nil
+		}
+		if options.KnownHosts == "" {
+			return fmt.Errorf("host key for %s is unknown and no writable known_hosts path is available", hostname)
+		}
+		if err := appendKnownHost(options.KnownHosts, hostname, key); err != nil {
+			return err
+		}
+		loaded, err := knownhosts.New(options.KnownHosts)
+		if err == nil {
+			checker = loaded
+		}
+		return nil
+	}, nil
+}
+
+func appendKnownHost(path, host string, key cryptossh.PublicKey) error {
+	file, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
+	if err != nil {
+		return fmt.Errorf("persist accepted host key to known_hosts %q: %w", path, err)
+	}
+	defer file.Close()
+	if _, err := fmt.Fprintln(file, knownhosts.Line([]string{knownhosts.Normalize(host)}, key)); err != nil {
+		return fmt.Errorf("persist accepted host key to known_hosts %q: %w", path, err)
+	}
+	return nil
+}

internal/adapters/ssh/hostkeys_test.go

@@ -0,0 +1,138 @@
+package ssh
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	cryptossh "golang.org/x/crypto/ssh"
+	"golang.org/x/crypto/ssh/knownhosts"
+)
+
+func TestAcceptNewHostKeyCallbackPersistsUnknownHost(t *testing.T) {
+	key := testPublicKey(t)
+	knownHosts := filepath.Join(t.TempDir(), "known_hosts")
+	callback, err := acceptNewHostKeyCallback(Options{KnownHosts: knownHosts})
+	if err != nil {
+		t.Fatalf("acceptNewHostKeyCallback() error = %v", err)
+	}
+
+	if err := callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, key); err != nil {
+		t.Fatalf("callback() error = %v", err)
+	}
+	data, err := os.ReadFile(knownHosts)
+	if err != nil {
+		t.Fatalf("read known_hosts: %v", err)
+	}
+	if !strings.Contains(string(data), "example.com") {
+		t.Fatalf("known_hosts = %q, want example.com entry", data)
+	}
+	if err := callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, key); err != nil {
+		t.Fatalf("second callback() error = %v", err)
+	}
+}
+
+func TestAcceptNewHostKeyCallbackReadOnlyDoesNotPersistUnknownHost(t *testing.T) {
+	key := testPublicKey(t)
+	knownHosts := filepath.Join(t.TempDir(), "known_hosts")
+	callback, err := acceptNewHostKeyCallback(Options{
+		KnownHosts:         knownHosts,
+		ReadOnlyKnownHosts: true,
+	})
+	if err != nil {
+		t.Fatalf("acceptNewHostKeyCallback() error = %v", err)
+	}
+
+	if err := callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, key); err != nil {
+		t.Fatalf("callback() error = %v", err)
+	}
+	if _, err := os.Stat(knownHosts); !os.IsNotExist(err) {
+		t.Fatalf("known_hosts stat error = %v, want not exist", err)
+	}
+}
+
+func TestAcceptNewHostKeyCallbackRejectsChangedHostKey(t *testing.T) {
+	first := testPublicKey(t)
+	second := testPublicKey(t)
+	knownHosts := filepath.Join(t.TempDir(), "known_hosts")
+	if err := os.WriteFile(knownHosts, []byte(knownhosts.Line([]string{knownhosts.Normalize("example.com:22")}, first)+"\n"), 0o600); err != nil {
+		t.Fatalf("write known_hosts: %v", err)
+	}
+	callback, err := acceptNewHostKeyCallback(Options{KnownHosts: knownHosts})
+	if err != nil {
+		t.Fatalf("acceptNewHostKeyCallback() error = %v", err)
+	}
+
+	err = callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, second)
+	if err == nil || !strings.Contains(err.Error(), "has changed") {
+		t.Fatalf("callback() error = %v, want changed host key", err)
+	}
+}
+
+func TestAcceptNewHostKeyCallbackReadOnlyRejectsChangedHostKey(t *testing.T) {
+	first := testPublicKey(t)
+	second := testPublicKey(t)
+	knownHosts := filepath.Join(t.TempDir(), "known_hosts")
+	if err := os.WriteFile(knownHosts, []byte(knownhosts.Line([]string{knownhosts.Normalize("example.com:22")}, first)+"\n"), 0o600); err != nil {
+		t.Fatalf("write known_hosts: %v", err)
+	}
+	callback, err := acceptNewHostKeyCallback(Options{
+		KnownHosts:         knownHosts,
+		ReadOnlyKnownHosts: true,
+	})
+	if err != nil {
+		t.Fatalf("acceptNewHostKeyCallback() error = %v", err)
+	}
+
+	err = callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, second)
+	if err == nil || !strings.Contains(err.Error(), "has changed") {
+		t.Fatalf("callback() error = %v, want changed host key", err)
+	}
+}
+
+func TestAcceptNewHostKeyCallbackRequiresWritableKnownHostsForUnknownHost(t *testing.T) {
+	callback, err := acceptNewHostKeyCallback(Options{})
+	if err != nil {
+		t.Fatalf("acceptNewHostKeyCallback() error = %v", err)
+	}
+
+	err = callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, testPublicKey(t))
+	if err == nil || !strings.Contains(err.Error(), "no writable known_hosts path") {
+		t.Fatalf("callback() error = %v, want no writable known_hosts path", err)
+	}
+}
+
+func TestAcceptNewHostKeyCallbackReadOnlyAllowsMissingKnownHosts(t *testing.T) {
+	callback, err := acceptNewHostKeyCallback(Options{ReadOnlyKnownHosts: true})
+	if err != nil {
+		t.Fatalf("acceptNewHostKeyCallback() error = %v", err)
+	}
+
+	if err := callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, testPublicKey(t)); err != nil {
+		t.Fatalf("callback() error = %v", err)
+	}
+}
+
+func TestStrictHostKeyCallbackRequiresKnownHosts(t *testing.T) {
+	_, err := hostKeyCallback(Options{HostKeyPolicy: HostKeyPolicyStrict})
+	if err == nil || !strings.Contains(err.Error(), "known_hosts is required") {
+		t.Fatalf("hostKeyCallback() error = %v, want known_hosts required", err)
+	}
+}
+
+func testPublicKey(t *testing.T) cryptossh.PublicKey {
+	t.Helper()
+	privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generate key: %v", err)
+	}
+	publicKey, err := cryptossh.NewPublicKey(&privateKey.PublicKey)
+	if err != nil {
+		t.Fatalf("new public key: %v", err)
+	}
+	return publicKey
+}

internal/adapters/ssh/integration_test.go

@@ -0,0 +1,39 @@
+package ssh
+
+import (
+	"context"
+	"os"
+	"strconv"
+	"testing"
+)
+
+func TestIntegrationSSHBackendStatRoot(t *testing.T) {
+	host := os.Getenv("DISTRIBUTOR_TEST_SSH_HOST")
+	if host == "" {
+		t.Skip("DISTRIBUTOR_TEST_SSH_HOST is not set")
+	}
+	port := 22
+	if raw := os.Getenv("DISTRIBUTOR_TEST_SSH_PORT"); raw != "" {
+		parsed, err := strconv.Atoi(raw)
+		if err != nil {
+			t.Fatalf("parse DISTRIBUTOR_TEST_SSH_PORT: %v", err)
+		}
+		port = parsed
+	}
+	backend, err := New(context.Background(), Options{
+		Host:          host,
+		User:          os.Getenv("DISTRIBUTOR_TEST_SSH_USER"),
+		Port:          port,
+		Root:          os.Getenv("DISTRIBUTOR_TEST_SSH_PATH"),
+		KeyFile:       os.Getenv("DISTRIBUTOR_TEST_SSH_KEY_FILE"),
+		KnownHosts:    os.Getenv("DISTRIBUTOR_TEST_SSH_KNOWN_HOSTS"),
+		HostKeyPolicy: HostKeyPolicyStrict,
+	})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	defer backend.Close()
+	if _, err := backend.Stat(context.Background(), ""); err != nil {
+		t.Fatalf("Stat(root) error = %v", err)
+	}
+}

internal/adapters/ssh/options.go

@@ -0,0 +1,78 @@
+package ssh
+
+import (
+	"fmt"
+	"os"
+	"os/user"
+	"path"
+	"path/filepath"
+	"strconv"
+)
+
+const (
+	BackendName = "ssh"
+
+	HostKeyPolicyStrict    HostKeyPolicy = "strict"
+	HostKeyPolicyAcceptNew HostKeyPolicy = "accept-new"
+	HostKeyPolicyOff       HostKeyPolicy = "off"
+)
+
+type HostKeyPolicy string
+
+type Options struct {
+	Host               string
+	User               string
+	Port               int
+	Root               string
+	KeyFile            string
+	KnownHosts         string
+	HostKeyPolicy      HostKeyPolicy
+	ReadOnlyKnownHosts bool
+}
+
+func (o Options) normalized() (Options, error) {
+	if o.Host == "" {
+		return Options{}, fmt.Errorf("host is required")
+	}
+	if o.User == "" {
+		current, err := user.Current()
+		if err != nil || current.Username == "" {
+			return Options{}, fmt.Errorf("user is required when current OS user cannot be determined")
+		}
+		o.User = current.Username
+	}
+	if o.Port == 0 {
+		o.Port = 22
+	}
+	if o.Port < 1 || o.Port > 65535 {
+		return Options{}, fmt.Errorf("port must be between 1 and 65535")
+	}
+	if o.Root == "" {
+		return Options{}, fmt.Errorf("path is required")
+	}
+	o.Root = path.Clean(o.Root)
+	if o.HostKeyPolicy == "" {
+		o.HostKeyPolicy = HostKeyPolicyAcceptNew
+	}
+	switch o.HostKeyPolicy {
+	case HostKeyPolicyStrict, HostKeyPolicyAcceptNew, HostKeyPolicyOff:
+	default:
+		return Options{}, fmt.Errorf("host_key_policy must be strict, accept-new, or off")
+	}
+	if o.KnownHosts == "" && o.HostKeyPolicy != HostKeyPolicyOff {
+		o.KnownHosts = defaultKnownHostsPath()
+	}
+	return o, nil
+}
+
+func (o Options) address() string {
+	return o.Host + ":" + strconv.Itoa(o.Port)
+}
+
+func defaultKnownHostsPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".ssh", "known_hosts")
+}

internal/adapters/ssh/options_test.go

@@ -0,0 +1,118 @@
+package ssh
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"github.com/pkg/sftp"
+)
+
+func TestOptionsNormalizeDefaultsUserPortAndHostKeyPolicy(t *testing.T) {
+	options, err := (Options{
+		Host: "example.com",
+		Root: "/reports",
+	}).normalized()
+	if err != nil {
+		t.Fatalf("normalized() error = %v", err)
+	}
+	if options.User == "" {
+		t.Fatal("normalized user is empty")
+	}
+	if options.Port != 22 {
+		t.Fatalf("port = %d, want 22", options.Port)
+	}
+	if options.HostKeyPolicy != HostKeyPolicyAcceptNew {
+		t.Fatalf("host key policy = %q, want accept-new", options.HostKeyPolicy)
+	}
+}
+
+func TestOptionsNormalizeRejectsInvalidFields(t *testing.T) {
+	tests := map[string]Options{
+		"host": {Root: "/reports"},
+		"port": {
+			Host: "example.com",
+			Port: 70000,
+			Root: "/reports",
+		},
+		"path": {
+			Host: "example.com",
+		},
+		"host key policy": {
+			Host:          "example.com",
+			Root:          "/reports",
+			HostKeyPolicy: "prompt",
+		},
+	}
+	for name, options := range tests {
+		t.Run(name, func(t *testing.T) {
+			if _, err := options.normalized(); err == nil {
+				t.Fatal("normalized() error = nil, want error")
+			}
+		})
+	}
+}
+
+func TestNativePathEnforcesLogicalPathRules(t *testing.T) {
+	backend := &Backend{root: "/srv/reports"}
+	tests := map[string]string{
+		"bundle/report.md": "/srv/reports/bundle/report.md",
+		"":                 "/srv/reports",
+	}
+	for logicalPath, want := range tests {
+		t.Run(logicalPath, func(t *testing.T) {
+			got, err := backend.nativePath(logicalPath, true)
+			if err != nil {
+				t.Fatalf("nativePath() error = %v", err)
+			}
+			if got != want {
+				t.Fatalf("nativePath() = %q, want %q", got, want)
+			}
+		})
+	}
+
+	for _, logicalPath := range []string{"/absolute", "../escape", "a/../b", `a\b`} {
+		t.Run("reject "+logicalPath, func(t *testing.T) {
+			_, err := backend.nativePath(logicalPath, true)
+			if err == nil || !storage.IsInvalidPath(err) {
+				t.Fatalf("nativePath() error = %v, want invalid path", err)
+			}
+		})
+	}
+}
+
+func TestNewRejectsMissingAuthBeforeDial(t *testing.T) {
+	t.Setenv("SSH_AUTH_SOCK", "")
+	_, err := New(context.Background(), Options{
+		Host:          "example.com",
+		User:          "reports",
+		Root:          "/reports",
+		HostKeyPolicy: HostKeyPolicyOff,
+	})
+	if err == nil || !strings.Contains(err.Error(), "no SSH auth methods configured") {
+		t.Fatalf("New() error = %v, want missing auth", err)
+	}
+}
+
+func TestTranslateErrorMapsSFTPStatusCodes(t *testing.T) {
+	backend := &Backend{}
+	tests := []struct {
+		name string
+		err  error
+		want storage.ErrorKind
+	}{
+		{name: "not found", err: sftp.ErrSSHFxNoSuchFile, want: storage.ErrNotFound},
+		{name: "permission", err: sftp.ErrSSHFxPermissionDenied, want: storage.ErrPermission},
+		{name: "unsupported", err: sftp.ErrSSHFxOpUnsupported, want: storage.ErrUnsupported},
+		{name: "temporary", err: sftp.ErrSSHFxConnectionLost, want: storage.ErrTemporary},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := backend.translateError(storage.OpStat, "report.md", tt.err)
+			if !storage.IsKind(err, tt.want) {
+				t.Fatalf("translateError() = %v, want kind %s", err, tt.want)
+			}
+		})
+	}
+}

internal/app/backends.go

@@ -3,19 +3,61 @@ package app
 import (
 	"context"
 	"fmt"
+	"strconv"
 
 	"gitea.maximumdirect.net/eric/distributor/internal/adapters/local"
+	s3adapter "gitea.maximumdirect.net/eric/distributor/internal/adapters/s3"
+	sshadapter "gitea.maximumdirect.net/eric/distributor/internal/adapters/ssh"
 	"gitea.maximumdirect.net/eric/distributor/internal/config"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 )
 
 const storagePathKey = "path"
 
+const (
+	sshHostKey          = "host"
+	sshUserKey          = "user"
+	sshPortKey          = "port"
+	sshKeyFileKey       = "ssh_key_file"
+	sshKnownHostsKey    = "known_hosts"
+	sshHostKeyPolicyKey = "host_key_policy"
+	sshReadOnlyHostsKey = "read_only_known_hosts"
+	s3EndpointKey       = "endpoint"
+	s3BucketKey         = "bucket"
+	s3PrefixKey         = "prefix"
+	s3RegionKey         = "region"
+	s3ForcePathStyleKey = "force_path_style"
+	s3AccessKeyIDKey    = "access_key_id"
+	s3SecretAccessKey   = "secret_access_key"
+)
+
 type backendFactory struct {
 	registry           *storage.Registry
+	environment        config.Environment
+	readOnlyKnownHosts bool
+}
+
+type backendOpenSpec struct {
+	role        string
+	backend     string
+	path        string
+	host        string
+	user        string
+	port        int
+	ssh         config.SSH
+	endpoint    string
+	bucket      string
+	prefix      string
+	region      string
+	forcePath   *bool
+	credentials config.Credentials
 }
 
 func newBackendFactory() *backendFactory {
+	return newBackendFactoryWithEnvironment(config.ProcessEnvironment())
+}
+
+func newBackendFactoryWithEnvironment(environment config.Environment) *backendFactory {
 	registry := storage.NewRegistry()
 	_ = registry.Register(config.BackendLocal, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
 		if err := ctx.Err(); err != nil {
@@ -23,23 +65,149 @@ func newBackendFactory() *backendFactory {
 		}
 		return local.New(cfg[storagePathKey])
 	})
-	return &backendFactory{registry: registry}
+	_ = registry.Register(config.BackendSSH, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+		port, err := strconv.Atoi(cfg[sshPortKey])
+		if err != nil {
+			return nil, fmt.Errorf("ssh port: %w", err)
+		}
+		readOnlyKnownHosts := false
+		if raw := cfg[sshReadOnlyHostsKey]; raw != "" {
+			readOnlyKnownHosts, err = strconv.ParseBool(raw)
+			if err != nil {
+				return nil, fmt.Errorf("ssh read_only_known_hosts: %w", err)
+			}
+		}
+		return sshadapter.New(ctx, sshadapter.Options{
+			Host:               cfg[sshHostKey],
+			User:               cfg[sshUserKey],
+			Port:               port,
+			Root:               cfg[storagePathKey],
+			KeyFile:            cfg[sshKeyFileKey],
+			KnownHosts:         cfg[sshKnownHostsKey],
+			HostKeyPolicy:      sshadapter.HostKeyPolicy(cfg[sshHostKeyPolicyKey]),
+			ReadOnlyKnownHosts: readOnlyKnownHosts,
+		})
+	})
+	_ = registry.Register(config.BackendS3, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+		forcePathStyle, err := strconv.ParseBool(cfg[s3ForcePathStyleKey])
+		if err != nil {
+			return nil, fmt.Errorf("s3 force_path_style: %w", err)
+		}
+		return s3adapter.New(ctx, s3adapter.Options{
+			Endpoint:        cfg[s3EndpointKey],
+			Bucket:          cfg[s3BucketKey],
+			Prefix:          cfg[s3PrefixKey],
+			Region:          cfg[s3RegionKey],
+			ForcePathStyle:  forcePathStyle,
+			AccessKeyID:     cfg[s3AccessKeyIDKey],
+			SecretAccessKey: cfg[s3SecretAccessKey],
+		})
+	})
+	return &backendFactory{registry: registry, environment: environment}
 }
 
 func (f *backendFactory) openSource(ctx context.Context, source config.Backend) (storage.Backend, error) {
-	if source.Backend != config.BackendLocal {
-		return nil, fmt.Errorf("source backend %s is not implemented for execution", source.Backend)
-	}
-	return f.registry.Open(ctx, source.Backend, storage.OpenConfig{storagePathKey: source.Path})
+	return f.openBackend(ctx, backendOpenSpecFromSource(source))
 }
 
 func (f *backendFactory) openDestination(ctx context.Context, destination config.Destination) (storage.Backend, error) {
-	if destination.Backend != config.BackendLocal {
-		return nil, fmt.Errorf("backend %s is not implemented for execution", destination.Backend)
-	}
-	return f.registry.Open(ctx, destination.Backend, storage.OpenConfig{storagePathKey: destination.Path})
+	return f.openBackend(ctx, backendOpenSpecFromDestination(destination))
 }
 
 func (f *backendFactory) openLocalPath(ctx context.Context, path string) (storage.Backend, error) {
 	return f.registry.Open(ctx, config.BackendLocal, storage.OpenConfig{storagePathKey: path})
 }
+
+func (f *backendFactory) resolveCredentials(creds config.Credentials) (config.ResolvedCredentials, error) {
+	return f.environment.ResolveCredentials(creds)
+}
+
+func (f *backendFactory) openBackend(ctx context.Context, spec backendOpenSpec) (storage.Backend, error) {
+	if !backendExecutable(spec.backend) {
+		if spec.role == "source" {
+			return nil, fmt.Errorf("source backend %s is not implemented for execution", spec.backend)
+		}
+		return nil, fmt.Errorf("backend %s is not implemented for execution", spec.backend)
+	}
+	openConfig, err := f.openConfig(spec)
+	if err != nil {
+		return nil, err
+	}
+	return f.registry.Open(ctx, spec.backend, openConfig)
+}
+
+func backendExecutable(name string) bool {
+	return name == config.BackendLocal || name == config.BackendSSH || name == config.BackendS3
+}
+
+func (f *backendFactory) openConfig(spec backendOpenSpec) (storage.OpenConfig, error) {
+	cfg := storage.OpenConfig{storagePathKey: spec.path}
+	switch spec.backend {
+	case config.BackendSSH:
+		cfg[sshHostKey] = spec.host
+		cfg[sshUserKey] = spec.user
+		cfg[sshPortKey] = strconv.Itoa(spec.port)
+		cfg[sshKeyFileKey] = spec.ssh.KeyFile
+		cfg[sshKnownHostsKey] = spec.ssh.KnownHosts
+		cfg[sshHostKeyPolicyKey] = string(spec.ssh.HostKeyPolicy)
+		cfg[sshReadOnlyHostsKey] = strconv.FormatBool(f.readOnlyKnownHosts)
+	case config.BackendS3:
+		if err := f.addS3Config(cfg, spec); err != nil {
+			return nil, err
+		}
+	}
+	return cfg, nil
+}
+
+func (f *backendFactory) addS3Config(cfg storage.OpenConfig, spec backendOpenSpec) error {
+	cfg[s3EndpointKey] = spec.endpoint
+	cfg[s3BucketKey] = spec.bucket
+	cfg[s3PrefixKey] = spec.prefix
+	cfg[s3RegionKey] = spec.region
+	cfg[s3ForcePathStyleKey] = strconv.FormatBool(config.ForcePathStyle(spec.forcePath))
+	if spec.credentials.AccessKeyIDEnv != "" || spec.credentials.SecretAccessKeyEnv != "" {
+		resolved, err := f.resolveCredentials(spec.credentials)
+		if err != nil {
+			return err
+		}
+		cfg[s3AccessKeyIDKey] = resolved.AccessKeyID
+		cfg[s3SecretAccessKey] = resolved.SecretAccessKey
+	}
+	return nil
+}
+
+func backendOpenSpecFromSource(source config.Backend) backendOpenSpec {
+	return backendOpenSpec{
+		role:        "source",
+		backend:     source.Backend,
+		path:        source.Path,
+		host:        source.Host,
+		user:        source.User,
+		port:        source.Port,
+		ssh:         source.SSH,
+		endpoint:    source.Endpoint,
+		bucket:      source.Bucket,
+		prefix:      source.Prefix,
+		region:      source.Region,
+		forcePath:   source.ForcePath,
+		credentials: source.Creds,
+	}
+}
+
+func backendOpenSpecFromDestination(destination config.Destination) backendOpenSpec {
+	return backendOpenSpec{
+		role:        "destination",
+		backend:     destination.Backend,
+		path:        destination.Path,
+		host:        destination.Host,
+		user:        destination.User,
+		port:        destination.Port,
+		ssh:         destination.SSH,
+		endpoint:    destination.Endpoint,
+		bucket:      destination.Bucket,
+		prefix:      destination.Prefix,
+		region:      destination.Region,
+		forcePath:   destination.ForcePath,
+		credentials: destination.Creds,
+	}
+}

internal/app/backends_test.go

@@ -1,11 +1,16 @@
 package app
 
 import (
+	"bytes"
 	"context"
+	"fmt"
 	"strings"
 	"testing"
 
 	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
+	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
 )
 
 func TestBackendFactoryOpensLocalSource(t *testing.T) {
@@ -47,14 +52,125 @@ func TestBackendFactoryOpensDirectLocalPath(t *testing.T) {
 	}
 }
 
+func TestBackendFactoryOpensSSHSourceWithRegisteredOpener(t *testing.T) {
+	factory := &backendFactory{registry: storage.NewRegistry()}
+	var got storage.OpenConfig
+	if err := factory.registry.Register(config.BackendSSH, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+		got = cfg
+		return fake.New(), nil
+	}); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+
+	backend, err := factory.openSource(context.Background(), config.Backend{
+		Backend: config.BackendSSH,
+		Host:    "source.example.com",
+		User:    "reports",
+		Port:    22,
+		Path:    "/reports",
+		SSH:     config.SSH{HostKeyPolicy: config.HostKeyPolicyAcceptNew},
+	})
+	if err != nil {
+		t.Fatalf("openSource() error = %v", err)
+	}
+	if backend == nil {
+		t.Fatal("openSource() backend = nil")
+	}
+	if got[sshHostKey] != "source.example.com" || got[storagePathKey] != "/reports" {
+		t.Fatalf("open config = %#v, want SSH source fields", got)
+	}
+}
+
+func TestBackendFactoryOpensSSHDestinationWithRegisteredOpener(t *testing.T) {
+	factory := &backendFactory{registry: storage.NewRegistry()}
+	var got storage.OpenConfig
+	if err := factory.registry.Register(config.BackendSSH, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+		got = cfg
+		return fake.New(), nil
+	}); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+
+	backend, err := factory.openDestination(context.Background(), config.Destination{
+		Backend: config.BackendSSH,
+		Host:    "destination.example.com",
+		User:    "deploy",
+		Port:    2222,
+		Path:    "/archive",
+		SSH:     config.SSH{HostKeyPolicy: config.HostKeyPolicyStrict},
+	})
+	if err != nil {
+		t.Fatalf("openDestination() error = %v", err)
+	}
+	if backend == nil {
+		t.Fatal("openDestination() backend = nil")
+	}
+	if got[sshHostKey] != "destination.example.com" || got[sshPortKey] != "2222" || got[sshHostKeyPolicyKey] != "strict" {
+		t.Fatalf("open config = %#v, want SSH destination fields", got)
+	}
+}
+
+func TestBackendFactorySetsReadOnlyKnownHostsForDryRunSSH(t *testing.T) {
+	factory := &backendFactory{
+		registry:           storage.NewRegistry(),
+		readOnlyKnownHosts: true,
+	}
+	var got storage.OpenConfig
+	if err := factory.registry.Register(config.BackendSSH, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+		got = cfg
+		return fake.New(), nil
+	}); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+
+	_, err := factory.openDestination(context.Background(), config.Destination{
+		Backend: config.BackendSSH,
+		Host:    "destination.example.com",
+		User:    "deploy",
+		Port:    22,
+		Path:    "/archive",
+		SSH:     config.SSH{HostKeyPolicy: config.HostKeyPolicyAcceptNew},
+	})
+	if err != nil {
+		t.Fatalf("openDestination() error = %v", err)
+	}
+	if got[sshReadOnlyHostsKey] != "true" {
+		t.Fatalf("open config %s = %q, want true", sshReadOnlyHostsKey, got[sshReadOnlyHostsKey])
+	}
+}
+
+func TestBackendFactoryUsesPersistentKnownHostsByDefault(t *testing.T) {
+	factory := &backendFactory{registry: storage.NewRegistry()}
+	var got storage.OpenConfig
+	if err := factory.registry.Register(config.BackendSSH, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+		got = cfg
+		return fake.New(), nil
+	}); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+
+	_, err := factory.openDestination(context.Background(), config.Destination{
+		Backend: config.BackendSSH,
+		Host:    "destination.example.com",
+		User:    "deploy",
+		Port:    22,
+		Path:    "/archive",
+		SSH:     config.SSH{HostKeyPolicy: config.HostKeyPolicyAcceptNew},
+	})
+	if err != nil {
+		t.Fatalf("openDestination() error = %v", err)
+	}
+	if got[sshReadOnlyHostsKey] != "false" {
+		t.Fatalf("open config %s = %q, want false", sshReadOnlyHostsKey, got[sshReadOnlyHostsKey])
+	}
+}
+
 func TestBackendFactoryRejectsUnsupportedSource(t *testing.T) {
 	factory := newBackendFactory()
 	_, err := factory.openSource(context.Background(), config.Backend{
-		Backend: config.BackendSSH,
-		URI:     "ssh://reports@example.com:22",
-		Path:    "/reports",
+		Backend: "ftp",
 	})
-	if err == nil || !strings.Contains(err.Error(), "source backend ssh is not implemented for execution") {
+	if err == nil || !strings.Contains(err.Error(), "source backend ftp is not implemented for execution") {
 		t.Fatalf("openSource() error = %v, want not implemented", err)
 	}
 }
@@ -62,11 +178,461 @@ func TestBackendFactoryRejectsUnsupportedSource(t *testing.T) {
 func TestBackendFactoryRejectsUnsupportedDestination(t *testing.T) {
 	factory := newBackendFactory()
 	_, err := factory.openDestination(context.Background(), config.Destination{
-		Backend:  config.BackendS3,
-		Endpoint: "https://s3.example.com",
-		Bucket:   "reports",
+		Backend: "ftp",
 	})
-	if err == nil || !strings.Contains(err.Error(), "backend s3 is not implemented for execution") {
+	if err == nil || !strings.Contains(err.Error(), "backend ftp is not implemented for execution") {
 		t.Fatalf("openDestination() error = %v, want not implemented", err)
 	}
 }
+
+func TestBackendFactoryOpensS3DestinationWithRegisteredOpener(t *testing.T) {
+	factory := &backendFactory{
+		registry:    storage.NewRegistry(),
+		environment: config.NewEnvironment(nil, func(string) (string, bool) { return "", false }),
+	}
+	var got storage.OpenConfig
+	if err := factory.registry.Register(config.BackendS3, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+		got = cfg
+		return fake.New(), nil
+	}); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+	forcePathStyle := false
+	backend, err := factory.openDestination(context.Background(), config.Destination{
+		Backend:   config.BackendS3,
+		Endpoint:  "https://s3.example.com",
+		Bucket:    "reports",
+		Prefix:    "archive",
+		Region:    config.DefaultS3Region,
+		ForcePath: &forcePathStyle,
+	})
+	if err != nil {
+		t.Fatalf("openDestination() error = %v", err)
+	}
+	if backend == nil {
+		t.Fatal("openDestination() backend = nil")
+	}
+	assertOpenConfig(t, got, map[string]string{
+		s3EndpointKey:       "https://s3.example.com",
+		s3BucketKey:         "reports",
+		s3PrefixKey:         "archive",
+		s3RegionKey:         config.DefaultS3Region,
+		s3ForcePathStyleKey: "false",
+	})
+}
+
+func TestBackendFactoryResolvesS3CredentialsThroughSecretsAwareEnvironment(t *testing.T) {
+	factory := &backendFactory{
+		registry: storage.NewRegistry(),
+		environment: config.NewEnvironment(map[string]string{
+			"ACCESS_KEY_ID":     "secret-access",
+			"SECRET_ACCESS_KEY": "secret-secret",
+		}, func(string) (string, bool) { return "", false }),
+	}
+	var got storage.OpenConfig
+	if err := factory.registry.Register(config.BackendS3, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+		got = cfg
+		return fake.New(), nil
+	}); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+	forcePathStyle := true
+	_, err := factory.openSource(context.Background(), config.Backend{
+		Backend:   config.BackendS3,
+		Endpoint:  "https://s3.example.com",
+		Bucket:    "reports",
+		Region:    config.DefaultS3Region,
+		ForcePath: &forcePathStyle,
+		Creds: config.Credentials{
+			AccessKeyIDEnv:     "ACCESS_KEY_ID",
+			SecretAccessKeyEnv: "SECRET_ACCESS_KEY",
+		},
+	})
+	if err != nil {
+		t.Fatalf("openSource() error = %v", err)
+	}
+	assertOpenConfig(t, got, map[string]string{
+		s3AccessKeyIDKey:  "secret-access",
+		s3SecretAccessKey: "secret-secret",
+	})
+}
+
+func TestBackendFactoryResolvesCredentialsThroughEnvironment(t *testing.T) {
+	factory := newBackendFactoryWithEnvironment(config.NewEnvironment(map[string]string{
+		"ACCESS_KEY_ID":     "secret-access",
+		"SECRET_ACCESS_KEY": "secret-secret",
+	}, func(string) (string, bool) {
+		return "", false
+	}))
+
+	creds, err := factory.resolveCredentials(config.Credentials{
+		AccessKeyIDEnv:     "ACCESS_KEY_ID",
+		SecretAccessKeyEnv: "SECRET_ACCESS_KEY",
+	})
+	if err != nil {
+		t.Fatalf("resolveCredentials() error = %v", err)
+	}
+	if creds.AccessKeyID != "secret-access" || creds.SecretAccessKey != "secret-secret" {
+		t.Fatalf("resolved credentials = %#v", creds)
+	}
+}
+
+func TestBackendFactoryBuildsSSHSourceOpenConfig(t *testing.T) {
+	factory := &backendFactory{environment: config.NewEnvironment(nil, nil)}
+	cfg, err := factory.openConfig(backendOpenSpecFromSource(config.Backend{
+		Backend: config.BackendSSH,
+		Host:    "source.example.com",
+		User:    "reports",
+		Port:    2222,
+		Path:    "/reports",
+		SSH: config.SSH{
+			KeyFile:       "/home/reports/.ssh/id_ed25519",
+			KnownHosts:    "/home/reports/.ssh/known_hosts",
+			HostKeyPolicy: config.HostKeyPolicyStrict,
+		},
+	}))
+	if err != nil {
+		t.Fatalf("openConfig() error = %v", err)
+	}
+
+	assertOpenConfig(t, cfg, map[string]string{
+		storagePathKey:      "/reports",
+		sshHostKey:          "source.example.com",
+		sshUserKey:          "reports",
+		sshPortKey:          "2222",
+		sshKeyFileKey:       "/home/reports/.ssh/id_ed25519",
+		sshKnownHostsKey:    "/home/reports/.ssh/known_hosts",
+		sshHostKeyPolicyKey: "strict",
+	})
+}
+
+func TestBackendFactoryBuildsSSHDestinationOpenConfig(t *testing.T) {
+	factory := &backendFactory{environment: config.NewEnvironment(nil, nil)}
+	cfg, err := factory.openConfig(backendOpenSpecFromDestination(config.Destination{
+		Backend: config.BackendSSH,
+		Host:    "destination.example.com",
+		User:    "deploy",
+		Port:    22,
+		Path:    "/srv/archive",
+		SSH: config.SSH{
+			HostKeyPolicy: config.HostKeyPolicyAcceptNew,
+		},
+	}))
+	if err != nil {
+		t.Fatalf("openConfig() error = %v", err)
+	}
+
+	assertOpenConfig(t, cfg, map[string]string{
+		storagePathKey:      "/srv/archive",
+		sshHostKey:          "destination.example.com",
+		sshUserKey:          "deploy",
+		sshPortKey:          "22",
+		sshHostKeyPolicyKey: "accept-new",
+	})
+}
+
+func TestBackendFactoryBuildsEquivalentSourceAndDestinationOpenConfig(t *testing.T) {
+	forcePathStyle := false
+	tests := []struct {
+		name        string
+		source      config.Backend
+		destination config.Destination
+	}{
+		{
+			name:        "local",
+			source:      config.Backend{Backend: config.BackendLocal, Path: "/reports"},
+			destination: config.Destination{Backend: config.BackendLocal, Path: "/reports"},
+		},
+		{
+			name: "ssh",
+			source: config.Backend{
+				Backend: config.BackendSSH,
+				Host:    "reports.example.com",
+				User:    "reports",
+				Port:    2222,
+				Path:    "/reports",
+				SSH: config.SSH{
+					KeyFile:       "/home/reports/.ssh/id_ed25519",
+					KnownHosts:    "/home/reports/.ssh/known_hosts",
+					HostKeyPolicy: config.HostKeyPolicyStrict,
+				},
+			},
+			destination: config.Destination{
+				Backend: config.BackendSSH,
+				Host:    "reports.example.com",
+				User:    "reports",
+				Port:    2222,
+				Path:    "/reports",
+				SSH: config.SSH{
+					KeyFile:       "/home/reports/.ssh/id_ed25519",
+					KnownHosts:    "/home/reports/.ssh/known_hosts",
+					HostKeyPolicy: config.HostKeyPolicyStrict,
+				},
+			},
+		},
+		{
+			name: "s3",
+			source: config.Backend{
+				Backend:   config.BackendS3,
+				Endpoint:  "https://s3.example.com",
+				Bucket:    "reports",
+				Prefix:    "archive",
+				Region:    "us-west-2",
+				ForcePath: &forcePathStyle,
+			},
+			destination: config.Destination{
+				Backend:   config.BackendS3,
+				Endpoint:  "https://s3.example.com",
+				Bucket:    "reports",
+				Prefix:    "archive",
+				Region:    "us-west-2",
+				ForcePath: &forcePathStyle,
+			},
+		},
+		{
+			name: "s3 explicit credentials",
+			source: config.Backend{
+				Backend:  config.BackendS3,
+				Endpoint: "https://s3.example.com",
+				Bucket:   "reports",
+				Region:   config.DefaultS3Region,
+				Creds: config.Credentials{
+					AccessKeyIDEnv:     "ACCESS_KEY_ID",
+					SecretAccessKeyEnv: "SECRET_ACCESS_KEY",
+				},
+			},
+			destination: config.Destination{
+				Backend:  config.BackendS3,
+				Endpoint: "https://s3.example.com",
+				Bucket:   "reports",
+				Region:   config.DefaultS3Region,
+				Creds: config.Credentials{
+					AccessKeyIDEnv:     "ACCESS_KEY_ID",
+					SecretAccessKeyEnv: "SECRET_ACCESS_KEY",
+				},
+			},
+		},
+	}
+
+	factory := &backendFactory{
+		environment: config.NewEnvironment(map[string]string{
+			"ACCESS_KEY_ID":     "secret-access",
+			"SECRET_ACCESS_KEY": "secret-secret",
+		}, func(string) (string, bool) { return "", false }),
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			sourceConfig, err := factory.openConfig(backendOpenSpecFromSource(tt.source))
+			if err != nil {
+				t.Fatalf("source openConfig() error = %v", err)
+			}
+			destinationConfig, err := factory.openConfig(backendOpenSpecFromDestination(tt.destination))
+			if err != nil {
+				t.Fatalf("destination openConfig() error = %v", err)
+			}
+			if !openConfigEqual(sourceConfig, destinationConfig) {
+				t.Fatalf("source open config = %#v, destination open config = %#v, want equivalent", sourceConfig, destinationConfig)
+			}
+		})
+	}
+}
+
+func TestBackendFactoryBuildsEquivalentDryRunSSHOpenConfig(t *testing.T) {
+	factory := &backendFactory{readOnlyKnownHosts: true}
+	sourceConfig, err := factory.openConfig(backendOpenSpecFromSource(config.Backend{
+		Backend: config.BackendSSH,
+		Host:    "reports.example.com",
+		Port:    22,
+		Path:    "/reports",
+		SSH:     config.SSH{HostKeyPolicy: config.HostKeyPolicyAcceptNew},
+	}))
+	if err != nil {
+		t.Fatalf("source openConfig() error = %v", err)
+	}
+	destinationConfig, err := factory.openConfig(backendOpenSpecFromDestination(config.Destination{
+		Backend: config.BackendSSH,
+		Host:    "reports.example.com",
+		Port:    22,
+		Path:    "/reports",
+		SSH:     config.SSH{HostKeyPolicy: config.HostKeyPolicyAcceptNew},
+	}))
+	if err != nil {
+		t.Fatalf("destination openConfig() error = %v", err)
+	}
+	if !openConfigEqual(sourceConfig, destinationConfig) {
+		t.Fatalf("source open config = %#v, destination open config = %#v, want equivalent", sourceConfig, destinationConfig)
+	}
+	if sourceConfig[sshReadOnlyHostsKey] != "true" {
+		t.Fatalf("open config %s = %q, want true", sshReadOnlyHostsKey, sourceConfig[sshReadOnlyHostsKey])
+	}
+}
+
+func TestConfiguredSourceValidationAndRunUseEquivalentSourceOpenConfig(t *testing.T) {
+	tests := []struct {
+		name       string
+		source     config.Backend
+		sourceKey  string
+		dest       config.Destination
+		destKey    string
+		wantFields map[string]string
+	}{
+		{
+			name: "s3",
+			source: config.Backend{
+				Backend:  config.BackendS3,
+				Endpoint: "https://s3.example.com",
+				Bucket:   "source-bucket",
+				Prefix:   "source-prefix",
+				Region:   config.DefaultS3Region,
+			},
+			sourceKey: "s3:source-bucket",
+			dest: config.Destination{
+				ID:       "archive",
+				Backend:  config.BackendS3,
+				Endpoint: "https://s3.example.com",
+				Bucket:   "destination-bucket",
+				Region:   config.DefaultS3Region,
+			},
+			destKey: "s3:destination-bucket",
+			wantFields: map[string]string{
+				s3EndpointKey:       "https://s3.example.com",
+				s3BucketKey:         "source-bucket",
+				s3PrefixKey:         "source-prefix",
+				s3RegionKey:         config.DefaultS3Region,
+				s3ForcePathStyleKey: "true",
+			},
+		},
+		{
+			name: "ssh",
+			source: config.Backend{
+				Backend: config.BackendSSH,
+				Host:    "ssh.example.com",
+				User:    "reports",
+				Port:    2222,
+				Path:    "/source",
+				SSH: config.SSH{
+					KeyFile:       "/home/reports/.ssh/id_ed25519",
+					KnownHosts:    "/home/reports/.ssh/known_hosts",
+					HostKeyPolicy: config.HostKeyPolicyStrict,
+				},
+			},
+			sourceKey: "ssh:/source",
+			dest: config.Destination{
+				ID:      "archive",
+				Backend: config.BackendSSH,
+				Host:    "ssh.example.com",
+				Port:    2222,
+				Path:    "/destination",
+				SSH:     config.SSH{HostKeyPolicy: config.HostKeyPolicyStrict},
+			},
+			destKey: "ssh:/destination",
+			wantFields: map[string]string{
+				storagePathKey:      "/source",
+				sshHostKey:          "ssh.example.com",
+				sshUserKey:          "reports",
+				sshPortKey:          "2222",
+				sshKeyFileKey:       "/home/reports/.ssh/id_ed25519",
+				sshKnownHostsKey:    "/home/reports/.ssh/known_hosts",
+				sshHostKeyPolicyKey: "strict",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			sourceBackend := fake.New()
+			testutil.WriteFakeSourceBundle(t, sourceBackend, "", testutil.BundleOptions{ID: "reports.source"})
+			destinationBackend := fake.New()
+			var validateSourceConfig storage.OpenConfig
+			var runSourceConfig storage.OpenConfig
+			validateProvider := recordingBackendFactoryProvider(t, map[string]storage.Backend{
+				tt.sourceKey: sourceBackend,
+				tt.destKey:   destinationBackend,
+			}, func(cfg storage.OpenConfig) {
+				validateSourceConfig = cfg
+			})
+			runProvider := recordingBackendFactoryProvider(t, map[string]storage.Backend{
+				tt.sourceKey: sourceBackend,
+				tt.destKey:   destinationBackend,
+			}, func(cfg storage.OpenConfig) {
+				runSourceConfig = cfg
+			})
+			cfg := config.Config{Pipelines: []config.Pipeline{{
+				ID:           "reports",
+				Source:       tt.source,
+				Destinations: []config.Destination{tt.dest},
+			}}}
+			config.ApplyDefaults(&cfg)
+
+			var validateOutput bytes.Buffer
+			if err := validateConfigWithBackendFactory(context.Background(), cfg, ValidateOptions{
+				PipelineID: "reports",
+				Stdout:     &validateOutput,
+			}, validateProvider); err != nil {
+				t.Fatalf("validateConfigWithBackendFactory() error = %v", err)
+			}
+			if err := runConfigWithBackendFactory(context.Background(), cfg, RunOptions{}, runProvider); err != nil {
+				t.Fatalf("runConfigWithBackendFactory() error = %v", err)
+			}
+			if !openConfigEqual(validateSourceConfig, runSourceConfig) {
+				t.Fatalf("validate source config = %#v, run source config = %#v, want equivalent", validateSourceConfig, runSourceConfig)
+			}
+			assertOpenConfig(t, runSourceConfig, tt.wantFields)
+		})
+	}
+}
+
+func assertOpenConfig(t *testing.T, got map[string]string, want map[string]string) {
+	t.Helper()
+	for key, wantValue := range want {
+		if gotValue := got[key]; gotValue != wantValue {
+			t.Fatalf("open config %s = %q, want %q", key, gotValue, wantValue)
+		}
+	}
+}
+
+func openConfigEqual(left, right storage.OpenConfig) bool {
+	if len(left) != len(right) {
+		return false
+	}
+	for key, leftValue := range left {
+		if right[key] != leftValue {
+			return false
+		}
+	}
+	return true
+}
+
+func recordingBackendFactoryProvider(t *testing.T, remoteBackends map[string]storage.Backend, recordSource func(storage.OpenConfig)) backendFactoryProvider {
+	t.Helper()
+	return func(environment config.Environment) *backendFactory {
+		registry := storage.NewRegistry()
+		if err := registry.Register(config.BackendS3, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+			if cfg[s3BucketKey] == "source-bucket" {
+				recordSource(cfg)
+			}
+			key := "s3:" + cfg[s3BucketKey]
+			backend := remoteBackends[key]
+			if backend == nil {
+				return nil, fmt.Errorf("missing fake backend for %s", key)
+			}
+			return backend, nil
+		}); err != nil {
+			t.Fatalf("register s3 backend: %v", err)
+		}
+		if err := registry.Register(config.BackendSSH, func(ctx context.Context, cfg storage.OpenConfig) (storage.Backend, error) {
+			if cfg[storagePathKey] == "/source" {
+				recordSource(cfg)
+			}
+			key := "ssh:" + cfg[storagePathKey]
+			backend := remoteBackends[key]
+			if backend == nil {
+				return nil, fmt.Errorf("missing fake backend for %s", key)
+			}
+			return backend, nil
+		}); err != nil {
+			t.Fatalf("register ssh backend: %v", err)
+		}
+		return &backendFactory{registry: registry, environment: environment}
+	}
+}

internal/app/inspect.go

@@ -5,38 +5,130 @@ import (
 	"fmt"
 	"io"
 
-	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 )
 
 type InspectOptions struct {
 	Path         string
+	ConfigPath   string
+	PipelineID   string
+	BundlePath   string
 	Stdout       io.Writer
+	OutputFormat OutputFormat
 }
 
 func Inspect(ctx context.Context, options InspectOptions) error {
-	if options.Path == "" {
-		return fmt.Errorf("inspect command requires a path")
-	}
-	backend, err := newBackendFactory().openLocalPath(ctx, options.Path)
-	if err != nil {
-		return err
-	}
-	bundles, err := bundle.Discover(ctx, backend, "")
-	if err != nil {
-		return err
-	}
-	return writeInspection(options.Stdout, bundles)
+	return inspectWithBackendFactory(ctx, options, newBackendFactoryWithEnvironment)
 }
 
-func writeInspection(w io.Writer, bundles []bundle.Bundle) error {
+func inspectWithBackendFactory(ctx context.Context, options InspectOptions, provider backendFactoryProvider) error {
+	if err := ValidateOutputFormat(options.OutputFormat); err != nil {
+		return err
+	}
+	selection, err := selectSourceBundles(ctx, sourceCommandOptions{
+		CommandName: "inspect",
+		Path:        options.Path,
+		ConfigPath:  options.ConfigPath,
+		PipelineID:  options.PipelineID,
+		BundlePath:  options.BundlePath,
+	}, provider)
+	if err != nil {
+		return err
+	}
+	return writeInspectResult(options, selection)
+}
+
+func inspectConfigWithBackendFactory(ctx context.Context, cfg config.Config, options InspectOptions, provider backendFactoryProvider) error {
+	if err := ValidateOutputFormat(options.OutputFormat); err != nil {
+		return err
+	}
+	selection, err := selectSourceBundlesFromConfig(ctx, cfg, sourceCommandOptions{
+		CommandName: "inspect",
+		PipelineID:  options.PipelineID,
+		BundlePath:  options.BundlePath,
+	}, provider)
+	if err != nil {
+		return err
+	}
+	return writeInspectResult(options, selection)
+}
+
+func writeInspectResult(options InspectOptions, selection sourceSelection) error {
+	if IsJSONOutput(options.OutputFormat) {
+		return WriteJSONEnvelope(options.Stdout, "inspect", true, selection.Warnings, inspectResultFromSelection(selection), nil)
+	}
+	if err := writeWarnings(options.Stdout, selection.Warnings); err != nil {
+		return err
+	}
+	return writeInspection(options.Stdout, selection)
+}
+
+type inspectResult struct {
+	PipelineID    string                `json:"pipeline_id,omitempty"`
+	SourceBackend string                `json:"source_backend,omitempty"`
+	BundleCount   int                   `json:"bundle_count"`
+	Bundles       []inspectBundleResult `json:"bundles"`
+}
+
+type inspectBundleResult struct {
+	Path      string              `json:"path"`
+	ID        string              `json:"id"`
+	Created   string              `json:"created"`
+	Digest    string              `json:"digest"`
+	FileCount int                 `json:"file_count"`
+	TotalSize int64               `json:"total_size"`
+	Files     []inspectFileResult `json:"files"`
+}
+
+type inspectFileResult struct {
+	Path   string `json:"path"`
+	SHA256 string `json:"sha256"`
+	Size   int64  `json:"size"`
+}
+
+func inspectResultFromSelection(selection sourceSelection) inspectResult {
+	result := inspectResult{
+		PipelineID:    selection.PipelineID,
+		SourceBackend: selection.SourceBackend,
+		BundleCount:   len(selection.Bundles),
+		Bundles:       make([]inspectBundleResult, 0, len(selection.Bundles)),
+	}
+	for _, sourceBundle := range selection.Bundles {
+		bundleResult := inspectBundleResult{
+			Path:      storage.DisplayPath(sourceBundle.RootRelativePath),
+			ID:        sourceBundle.Manifest.ID,
+			Created:   sourceBundle.Manifest.Created.Format("2006-01-02T15:04:05Z07:00"),
+			Digest:    sourceBundle.Manifest.Digest,
+			FileCount: len(sourceBundle.Manifest.Files),
+			Files:     make([]inspectFileResult, 0, len(sourceBundle.Manifest.Files)),
+		}
+		for _, file := range sourceBundle.Manifest.Files {
+			bundleResult.TotalSize += file.Size
+			bundleResult.Files = append(bundleResult.Files, inspectFileResult{
+				Path:   file.Path,
+				SHA256: file.SHA256,
+				Size:   file.Size,
+			})
+		}
+		result.Bundles = append(result.Bundles, bundleResult)
+	}
+	return result
+}
+
+func writeInspection(w io.Writer, selection sourceSelection) error {
 	if w == nil {
 		return nil
 	}
-	if _, err := fmt.Fprintf(w, "Bundles: %d\n", len(bundles)); err != nil {
+	if selection.ConfigMode {
+		if _, err := fmt.Fprintf(w, "Pipeline: %s\nSource: %s\n", selection.PipelineID, selection.SourceBackend); err != nil {
 			return err
 		}
-	for _, sourceBundle := range bundles {
+	}
+	if _, err := fmt.Fprintf(w, "Bundles: %d\n", len(selection.Bundles)); err != nil {
+		return err
+	}
+	for _, sourceBundle := range selection.Bundles {
 		if _, err := fmt.Fprintf(
 			w,
 			"- path=%s id=%s created=%s digest=%s files=%d\n",

internal/app/inspect_test.go

@@ -6,6 +6,8 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
 )
 
 func TestInspectPrintsBundleSummary(t *testing.T) {
@@ -32,6 +34,57 @@ func TestInspectPrintsBundleSummary(t *testing.T) {
 	}
 }
 
+func TestInspectConfiguredLocalSource(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "daily", testutil.BundleOptions{ID: "reports.daily"})
+	var stdout bytes.Buffer
+
+	err := Inspect(context.Background(), InspectOptions{
+		ConfigPath: testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot),
+		PipelineID: "reports",
+		Stdout:     &stdout,
+	})
+
+	if err != nil {
+		t.Fatalf("Inspect() configured source error = %v", err)
+	}
+	output := stdout.String()
+	for _, want := range []string{
+		"Pipeline: reports",
+		"Source: local",
+		"Bundles: 1",
+		"path=daily",
+		"id=reports.daily",
+	} {
+		if !strings.Contains(output, want) {
+			t.Fatalf("Inspect() output = %q, want substring %q", output, want)
+		}
+	}
+}
+
+func TestInspectConfiguredSourceJSON(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{ID: "reports.json"})
+	var stdout bytes.Buffer
+
+	err := Inspect(context.Background(), InspectOptions{
+		ConfigPath:   testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot),
+		PipelineID:   "reports",
+		Stdout:       &stdout,
+		OutputFormat: OutputFormatJSON,
+	})
+
+	if err != nil {
+		t.Fatalf("Inspect() configured JSON error = %v", err)
+	}
+	result := decodeAppResult(t, stdout.String())
+	if result["pipeline_id"] != "reports" || result["source_backend"] != "local" || result["bundle_count"] != float64(1) {
+		t.Fatalf("result = %#v, want configured inspect metadata", result)
+	}
+}
+
 func TestInspectRequiresPath(t *testing.T) {
 	err := Inspect(context.Background(), InspectOptions{})
 	if err == nil || !strings.Contains(err.Error(), "requires a path") {

internal/app/manifest.go

@@ -0,0 +1,128 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"path/filepath"
+	"strings"
+	"time"
+
+	producerbundle "gitea.maximumdirect.net/eric/distributor/pkg/bundle"
+)
+
+type ManifestCreateOptions struct {
+	Root         string
+	ID           string
+	Created      string
+	Files        []string
+	Overwrite    bool
+	Stdout       io.Writer
+	OutputFormat OutputFormat
+}
+
+func ManifestCreate(ctx context.Context, options ManifestCreateOptions) error {
+	if err := ValidateOutputFormat(options.OutputFormat); err != nil {
+		return err
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if options.Root == "" {
+		return fmt.Errorf("manifest create command requires a bundle path")
+	}
+	if options.ID == "" {
+		return fmt.Errorf("manifest create command requires --id")
+	}
+
+	created, err := parseOptionalCreated(options.Created)
+	if err != nil {
+		return err
+	}
+	files := normalizeManifestFiles(options.Files)
+	buildOptions := producerbundle.BuildOptions{
+		Root:    options.Root,
+		ID:      options.ID,
+		Created: created,
+		Files:   files,
+		Scan:    len(files) == 0,
+	}
+	manifest, err := producerbundle.BuildManifest(buildOptions)
+	if err != nil {
+		return err
+	}
+	if err := producerbundle.WriteManifest(options.Root, manifest, producerbundle.WriteManifestOptions{Overwrite: options.Overwrite}); err != nil {
+		return err
+	}
+	loaded, err := producerbundle.LoadManifest(options.Root)
+	if err != nil {
+		return err
+	}
+	if err := producerbundle.ValidateBundle(options.Root, loaded); err != nil {
+		return err
+	}
+
+	result := manifestCreateResultFromManifest(options.Root, loaded)
+	if IsJSONOutput(options.OutputFormat) {
+		return WriteJSONEnvelope(options.Stdout, "manifest create", true, nil, result, nil)
+	}
+	if options.Stdout != nil {
+		_, err = fmt.Fprintf(options.Stdout, "created %s\nbundle: %s\nfiles: %d\ndigest: %s\n", producerbundle.ManifestName, result.ID, result.FileCount, result.Digest)
+	}
+	return err
+}
+
+func parseOptionalCreated(value string) (time.Time, error) {
+	if value == "" {
+		return time.Time{}, nil
+	}
+	created, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("created must be RFC3339: %w", err)
+	}
+	return created, nil
+}
+
+func normalizeManifestFiles(files []string) []string {
+	normalized := make([]string, 0, len(files))
+	for _, file := range files {
+		normalized = append(normalized, filepath.ToSlash(filepath.Clean(strings.ReplaceAll(file, "\\", string(filepath.Separator)))))
+	}
+	return normalized
+}
+
+type manifestCreateResult struct {
+	ManifestPath string                     `json:"manifest_path"`
+	Root         string                     `json:"root"`
+	ID           string                     `json:"id"`
+	Created      string                     `json:"created"`
+	Digest       string                     `json:"digest"`
+	FileCount    int                        `json:"file_count"`
+	Files        []manifestCreateFileResult `json:"files"`
+}
+
+type manifestCreateFileResult struct {
+	Path   string `json:"path"`
+	SHA256 string `json:"sha256"`
+	Size   int64  `json:"size"`
+}
+
+func manifestCreateResultFromManifest(root string, manifest producerbundle.Manifest) manifestCreateResult {
+	result := manifestCreateResult{
+		ManifestPath: filepath.ToSlash(filepath.Join(root, producerbundle.ManifestName)),
+		Root:         filepath.ToSlash(root),
+		ID:           manifest.ID,
+		Created:      manifest.Created.Format(time.RFC3339),
+		Digest:       manifest.Digest,
+		FileCount:    len(manifest.Files),
+		Files:        make([]manifestCreateFileResult, 0, len(manifest.Files)),
+	}
+	for _, file := range manifest.Files {
+		result.Files = append(result.Files, manifestCreateFileResult{
+			Path:   file.Path,
+			SHA256: file.SHA256,
+			Size:   file.Size,
+		})
+	}
+	return result
+}

internal/app/output.go

@@ -0,0 +1,76 @@
+package app
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+)
+
+const outputSchemaVersion = 1
+
+type OutputFormat string
+
+const (
+	OutputFormatText OutputFormat = "text"
+	OutputFormatJSON OutputFormat = "json"
+)
+
+type OutputWarning struct {
+	Message string `json:"message"`
+}
+
+type OutputError struct {
+	PipelineID    string `json:"pipeline_id,omitempty"`
+	DestinationID string `json:"destination_id,omitempty"`
+	Backend       string `json:"backend,omitempty"`
+	BundlePath    string `json:"bundle_path,omitempty"`
+	Message       string `json:"message"`
+}
+
+type outputEnvelope struct {
+	SchemaVersion int             `json:"schema_version"`
+	Command       string          `json:"command"`
+	OK            bool            `json:"ok"`
+	Warnings      []OutputWarning `json:"warnings"`
+	Result        any             `json:"result"`
+	Errors        []OutputError   `json:"errors,omitempty"`
+}
+
+func NormalizeOutputFormat(format OutputFormat) OutputFormat {
+	if format == "" {
+		return OutputFormatText
+	}
+	return format
+}
+
+func ValidateOutputFormat(format OutputFormat) error {
+	switch NormalizeOutputFormat(format) {
+	case OutputFormatText, OutputFormatJSON:
+		return nil
+	default:
+		return fmt.Errorf("format must be text or json")
+	}
+}
+
+func IsJSONOutput(format OutputFormat) bool {
+	return NormalizeOutputFormat(format) == OutputFormatJSON
+}
+
+func WriteJSONEnvelope(w io.Writer, command string, ok bool, warnings []OutputWarning, result any, errors []OutputError) error {
+	if w == nil {
+		return nil
+	}
+	if warnings == nil {
+		warnings = []OutputWarning{}
+	}
+	envelope := outputEnvelope{
+		SchemaVersion: outputSchemaVersion,
+		Command:       command,
+		OK:            ok,
+		Warnings:      warnings,
+		Result:        result,
+		Errors:        errors,
+	}
+	encoder := json.NewEncoder(w)
+	return encoder.Encode(envelope)
+}

internal/app/run.go

@@ -2,10 +2,8 @@ package app
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"io"
-	"strings"
 
 	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
 	"gitea.maximumdirect.net/eric/distributor/internal/config"
@@ -17,11 +15,16 @@ import (
 type RunOptions struct {
 	ConfigPath   string
 	DryRun       bool
+	Force        bool
 	Stdout       io.Writer
+	OutputFormat OutputFormat
 	Notifier     notify.Notifier
 }
 
 func Run(ctx context.Context, options RunOptions) error {
+	if err := ValidateOutputFormat(options.OutputFormat); err != nil {
+		return err
+	}
 	if err := ctx.Err(); err != nil {
 		return err
 	}
@@ -38,88 +41,201 @@ func Run(ctx context.Context, options RunOptions) error {
 }
 
 func runConfig(ctx context.Context, cfg config.Config, options RunOptions) error {
+	return runConfigWithBackendFactory(ctx, cfg, options, newBackendFactoryWithEnvironment)
+}
+
+type backendFactoryProvider func(config.Environment) *backendFactory
+
+func runConfigWithBackendFactory(ctx context.Context, cfg config.Config, options RunOptions, provider backendFactoryProvider) error {
 	notifier := options.Notifier
 	if notifier == nil {
 		notifier = notify.Noop{}
 	}
+	jsonOutput := IsJSONOutput(options.OutputFormat)
 	summary := runSummary{dryRun: options.DryRun}
+	result := runResult{
+		DryRun:    options.DryRun,
+		Pipelines: []runPipelineResult{},
+		Actions:   []runActionResult{},
+	}
+	var warnings []OutputWarning
 	var failures runFailures
-	backends := newBackendFactory()
+	secretLoad, err := config.LoadSecretEnvironment(cfg.Secrets.Directory, nil)
+	if err != nil {
+		return err
+	}
+	secretWarnings := secretConflictWarnings(secretLoad.Conflicts)
+	if jsonOutput {
+		warnings = append(warnings, secretWarnings...)
+	} else if options.Stdout != nil {
+		if err := writeWarnings(options.Stdout, secretWarnings); err != nil {
+			return err
+		}
+	}
+	backends := provider(secretLoad.Environment)
+	backends.readOnlyKnownHosts = options.DryRun
 	transforms := newTransformRegistry()
-	if options.Stdout != nil {
+	if options.Stdout != nil && !jsonOutput {
 		if _, err := fmt.Fprintf(options.Stdout, "Configured pipelines: %d\n", len(cfg.Pipelines)); err != nil {
 			return err
 		}
 	}
 	for _, pipeline := range cfg.Pipelines {
-		sourceBackend, err := backends.openSource(ctx, pipeline.Source)
-		if err != nil {
-			return fmt.Errorf("pipeline %s: %w", pipeline.ID, err)
-		}
-		bundles, err := bundle.Discover(ctx, sourceBackend, "")
-		if err != nil {
-			return fmt.Errorf("pipeline %s discover source bundles: %w", pipeline.ID, err)
-		}
-		if options.Stdout != nil {
-			if _, err := fmt.Fprintf(options.Stdout, "- pipeline=%s source=%s bundles=%d destinations=%s\n", pipeline.ID, pipeline.Source.Backend, len(bundles), destinationSummary(pipeline.Destinations)); err != nil {
+		pipelineWarnings := sshWarnings(pipeline)
+		if jsonOutput {
+			warnings = append(warnings, pipelineWarnings...)
+		} else if options.Stdout != nil {
+			if err := writeWarnings(options.Stdout, pipelineWarnings); err != nil {
+				return err
+			}
+		}
+		sourceBackend, err := backends.openSource(ctx, pipeline.Source)
+		if err != nil {
+			return fmt.Errorf("pipeline %s source backend %s: %w", pipeline.ID, pipeline.Source.Backend, err)
+		}
+		bundles, err := bundle.Discover(ctx, sourceBackend, "")
+		if err != nil {
+			closeBackend(sourceBackend)
+			return fmt.Errorf("pipeline %s source backend %s discover source bundles: %w", pipeline.ID, pipeline.Source.Backend, err)
+		}
+		result.Pipelines = append(result.Pipelines, runPipelineResult{
+			ID:            pipeline.ID,
+			SourceBackend: pipeline.Source.Backend,
+			BundleCount:   len(bundles),
+			Destinations:  destinationIDs(pipeline.Destinations),
+		})
+		if options.Stdout != nil && !jsonOutput {
+			if _, err := fmt.Fprintf(options.Stdout, "- pipeline=%s source=%s bundles=%d destinations=%s\n", pipeline.ID, pipeline.Source.Backend, len(bundles), destinationSummary(pipeline.Destinations)); err != nil {
+				closeBackend(sourceBackend)
 				return err
 			}
 		}
-		for _, sourceBundle := range bundles {
 		for _, destination := range pipeline.Destinations {
+			selections := selectDestinationBundles(destination, bundles)
+			if isFixedPathDestination(destination) {
+				summary.recordFixedPath()
+				if options.DryRun {
+					warning := fixedPathSelectionWarning(pipeline.ID, destination.ID, selections, len(bundles))
+					if jsonOutput {
+						warnings = append(warnings, warning)
+					} else if options.Stdout != nil {
+						if err := writeWarnings(options.Stdout, []OutputWarning{warning}); err != nil {
+							closeBackend(sourceBackend)
+							return err
+						}
+					}
+				}
+			}
+			if len(selections) == 0 {
+				continue
+			}
 			destinationBackend, err := backends.openDestination(ctx, destination)
 			if err != nil {
-					failures.add(pipeline.ID, destination.ID, storage.DisplayPath(sourceBundle.RootRelativePath), err)
+				for _, selection := range selections {
+					failures.add(pipeline.ID, destination.ID, destination.Backend, storage.DisplayPath(selection.SourceBundle.RootRelativePath), err)
 					summary.recordFailure()
-					if options.Stdout != nil {
-						writeErrorLine(options.Stdout, sourceBundle.RootRelativePath, destination.ID, err)
+					if jsonOutput {
+						result.Actions = append(result.Actions, errorAction(pipeline.ID, destination.ID, destination.Backend, selection.SourceBundle.RootRelativePath, err))
+					} else if options.Stdout != nil {
+						writeErrorLine(options.Stdout, selection.SourceBundle.RootRelativePath, destination.ID, destination.Backend, err)
+					}
 				}
 				continue
 			}
+			closeDestination := true
+			deferCloseDestination := func() {
+				if closeDestination {
+					closeBackend(destinationBackend)
+					closeDestination = false
+				}
+			}
+			for _, selection := range selections {
+				sourceBundle := selection.SourceBundle
 				req := publish.Request{
 					PipelineID:            pipeline.ID,
 					DestinationID:         destination.ID,
 					SourceBundle:          sourceBundle,
 					SourceBackend:         sourceBackend,
 					DestinationBackend:    destinationBackend,
-					DestinationBundlePath: sourceBundle.RootRelativePath,
+					DestinationBundlePath: selection.DestinationBundlePath,
+					PathMapping:           destination.PathMap.Mode,
 					Publish:               *destination.Publish,
 					Transform:             destination.Transform,
+					Links:                 destination.Links,
 					Transformers:          transforms,
 					Transfer:              destination.Transfer,
 					DistributorVersion:    Version,
+					Force:                 options.Force,
 				}
 				plan, err := publish.Build(ctx, req)
-				if err != nil && plan.DestinationID == "" {
-					plan = publish.Plan{DestinationID: destination.ID, BundlePath: sourceBundle.RootRelativePath}
+				if err != nil {
+					if plan.PipelineID == "" {
+						plan.PipelineID = pipeline.ID
 					}
-				if options.Stdout != nil {
-					writePlanLine(options.Stdout, plan, err)
+					if plan.DestinationID == "" {
+						plan.DestinationID = destination.ID
+					}
+					if plan.BundleID == "" {
+						plan.BundleID = sourceBundle.Manifest.ID
+					}
+					if plan.BundlePath == "" {
+						plan.BundlePath = sourceBundle.RootRelativePath
+					}
+					if plan.DestinationBundlePath == "" {
+						plan.DestinationBundlePath = selection.DestinationBundlePath
+					}
+				}
+				if isFixedPathDestination(destination) {
+					plan.PathMapping = config.PathMappingFixed
+					if options.DryRun && isDestructiveFixedPathAction(plan.Action) {
+						warning := fixedPathReplacementWarning(plan)
+						if jsonOutput {
+							warnings = append(warnings, warning)
+						} else if options.Stdout != nil {
+							if err := writeWarnings(options.Stdout, []OutputWarning{warning}); err != nil {
+								deferCloseDestination()
+								closeBackend(sourceBackend)
+								return err
+							}
+						}
+					}
+				}
+				if jsonOutput {
+					result.Actions = append(result.Actions, runActionFromPlan(destination.Backend, plan, err))
+				} else if options.Stdout != nil {
+					writePlanLine(options.Stdout, destination.Backend, plan, err)
 				}
 				if err != nil {
-					failures.add(pipeline.ID, destination.ID, storage.DisplayPath(sourceBundle.RootRelativePath), err)
+					failures.add(pipeline.ID, destination.ID, destination.Backend, storage.DisplayPath(sourceBundle.RootRelativePath), err)
 					summary.recordFailure()
 					continue
 				}
 				summary.recordPlan(plan.Action)
 				if !options.DryRun {
 					if err := publish.Execute(ctx, req, plan); err != nil {
-						failures.add(pipeline.ID, destination.ID, storage.DisplayPath(sourceBundle.RootRelativePath), err)
+						failures.add(pipeline.ID, destination.ID, destination.Backend, storage.DisplayPath(sourceBundle.RootRelativePath), err)
 						summary.recordFailure()
 						continue
 					}
 					if shouldNotify(plan.Action) {
 						if err := notifier.Notify(ctx, notifyEvent(plan)); err != nil {
-							failures.add(pipeline.ID, destination.ID, storage.DisplayPath(sourceBundle.RootRelativePath), err)
+							failures.add(pipeline.ID, destination.ID, destination.Backend, storage.DisplayPath(sourceBundle.RootRelativePath), err)
 							summary.recordFailure()
 							continue
 						}
 					}
 				}
 			}
+			deferCloseDestination()
 		}
+		closeBackend(sourceBackend)
 	}
-	if options.Stdout != nil {
+	result.Summary = summary.Result()
+	if jsonOutput {
+		if err := WriteJSONEnvelope(options.Stdout, "run", len(failures.items) == 0, warnings, result, failures.outputErrors()); err != nil {
+			return err
+		}
+	} else if options.Stdout != nil {
 		if _, err := fmt.Fprintln(options.Stdout, summary.Line()); err != nil {
 			return err
 		}
@@ -130,144 +246,14 @@ func runConfig(ctx context.Context, cfg config.Config, options RunOptions) error
 	return nil
 }
 
-func writePlanLine(w io.Writer, plan publish.Plan, planErr error) {
-	if w == nil {
+type closeableBackend interface {
+	Close() error
+}
+
+func closeBackend(backend storage.Backend) {
+	closeable, ok := backend.(closeableBackend)
+	if !ok {
 		return
 	}
-	if planErr != nil {
-		destinationID := plan.DestinationID
-		if destinationID == "" {
-			destinationID = "unknown"
-		}
-		fmt.Fprintf(w, "  - bundle=%s destination=%s action=error reason=%q\n", storage.DisplayPath(plan.BundlePath), destinationID, planErr.Error())
-		return
-	}
-	fmt.Fprintf(w, "  - bundle=%s destination=%s action=%s outputs=%s reason=%q\n", storage.DisplayPath(plan.BundlePath), plan.DestinationID, plan.Action, outputSummary(plan.Outputs), plan.Reason)
-}
-
-func writeErrorLine(w io.Writer, bundlePath, destinationID string, err error) {
-	if w == nil {
-		return
-	}
-	fmt.Fprintf(w, "  - bundle=%s destination=%s action=error reason=%q\n", storage.DisplayPath(bundlePath), destinationID, err.Error())
-}
-
-func outputSummary(outputs []publish.Output) string {
-	if len(outputs) == 0 {
-		return "none"
-	}
-	paths := make([]string, 0, len(outputs))
-	for _, output := range outputs {
-		paths = append(paths, output.DestinationPath)
-	}
-	return strings.Join(paths, ",")
-}
-
-func destinationSummary(destinations []config.Destination) string {
-	if len(destinations) == 0 {
-		return "none"
-	}
-	ids := make([]string, 0, len(destinations))
-	for _, destination := range destinations {
-		ids = append(ids, destination.ID)
-	}
-	return strings.Join(ids, ",")
-}
-
-func shouldNotify(action publish.Action) bool {
-	return action == publish.ActionPublishNew || action == publish.ActionReplaceOlder
-}
-
-func notifyEvent(plan publish.Plan) notify.Event {
-	outputs := make([]notify.Output, 0, len(plan.Outputs))
-	for _, output := range plan.Outputs {
-		outputs = append(outputs, notify.Output{
-			Path:       output.DestinationPath,
-			Kind:       output.Kind,
-			SourcePath: output.SourcePath,
-			Transform:  output.Transform,
-			SHA256:     output.SHA256,
-			Size:       output.Size,
-		})
-	}
-	return notify.Event{
-		PipelineID:    plan.PipelineID,
-		DestinationID: plan.DestinationID,
-		BundleID:      plan.BundleID,
-		BundlePath:    plan.BundlePath,
-		Action:        string(plan.Action),
-		Outputs:       outputs,
-	}
-}
-
-type runSummary struct {
-	dryRun       bool
-	planned      int
-	publishNew   int
-	replaceOlder int
-	skipped      int
-	failures     int
-}
-
-func (s *runSummary) recordPlan(action publish.Action) {
-	s.planned++
-	switch action {
-	case publish.ActionPublishNew:
-		s.publishNew++
-	case publish.ActionReplaceOlder:
-		s.replaceOlder++
-	case publish.ActionSkipSame, publish.ActionSkipDestinationNewer:
-		s.skipped++
-	}
-}
-
-func (s *runSummary) recordFailure() {
-	s.failures++
-}
-
-func (s runSummary) Line() string {
-	status := "ok"
-	if s.failures > 0 {
-		status = "failed"
-	}
-	return fmt.Sprintf("Final status: %s planned=%d publish_new=%d replace_older=%d skipped=%d failed=%d dry_run=%t", status, s.planned, s.publishNew, s.replaceOlder, s.skipped, s.failures, s.dryRun)
-}
-
-type runFailure struct {
-	pipelineID    string
-	destinationID string
-	bundlePath    string
-	err           error
-}
-
-type runFailures struct {
-	items []runFailure
-}
-
-func (f *runFailures) add(pipelineID, destinationID, bundlePath string, err error) {
-	f.items = append(f.items, runFailure{
-		pipelineID:    pipelineID,
-		destinationID: destinationID,
-		bundlePath:    bundlePath,
-		err:           err,
-	})
-}
-
-func (f runFailures) Error() string {
-	if len(f.items) == 0 {
-		return ""
-	}
-	parts := make([]string, 0, len(f.items))
-	for _, item := range f.items {
-		parts = append(parts, fmt.Sprintf("pipeline %s destination %s bundle %s: %v", item.pipelineID, item.destinationID, item.bundlePath, item.err))
-	}
-	return "run failed: " + strings.Join(parts, "; ")
-}
-
-func (f runFailures) Unwrap() error {
-	errs := make([]error, 0, len(f.items))
-	for _, item := range f.items {
-		errs = append(errs, item.err)
-	}
-	return errors.Join(errs...)
+	_ = closeable.Close()
 }

internal/app/run_failures.go

@@ -0,0 +1,70 @@
+package app
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+)
+
+type runFailure struct {
+	pipelineID    string
+	destinationID string
+	backend       string
+	bundlePath    string
+	err           error
+}
+
+type runFailures struct {
+	items []runFailure
+}
+
+func (f *runFailures) add(pipelineID, destinationID, backend, bundlePath string, err error) {
+	f.items = append(f.items, runFailure{
+		pipelineID:    pipelineID,
+		destinationID: destinationID,
+		backend:       backend,
+		bundlePath:    bundlePath,
+		err:           err,
+	})
+}
+
+func (f runFailures) Error() string {
+	if len(f.items) == 0 {
+		return ""
+	}
+	parts := make([]string, 0, len(f.items))
+	for _, item := range f.items {
+		parts = append(parts, fmt.Sprintf("pipeline %s destination %s backend %s bundle %s: %v", item.pipelineID, item.destinationID, item.backend, item.bundlePath, item.err))
+	}
+	return "run failed: " + strings.Join(parts, "; ")
+}
+
+func (f runFailures) outputErrors() []OutputError {
+	if len(f.items) == 0 {
+		return nil
+	}
+	errors := make([]OutputError, 0, len(f.items))
+	for _, item := range f.items {
+		errors = append(errors, OutputError{
+			PipelineID:    item.pipelineID,
+			DestinationID: item.destinationID,
+			Backend:       item.backend,
+			BundlePath:    item.bundlePath,
+			Message:       item.err.Error(),
+		})
+	}
+	return errors
+}
+
+func IsPartialResultError(err error) bool {
+	var failures runFailures
+	return errors.As(err, &failures)
+}
+
+func (f runFailures) Unwrap() error {
+	errs := make([]error, 0, len(f.items))
+	for _, item := range f.items {
+		errs = append(errs, item.err)
+	}
+	return errors.Join(errs...)
+}

internal/app/run_notify.go

@@ -0,0 +1,33 @@
+package app
+
+import (
+	"gitea.maximumdirect.net/eric/distributor/internal/notify"
+	"gitea.maximumdirect.net/eric/distributor/internal/publish"
+)
+
+func shouldNotify(action publish.Action) bool {
+	return action == publish.ActionPublishNew || action == publish.ActionReplaceOlder || action == publish.ActionForceReplace
+}
+
+func notifyEvent(plan publish.Plan) notify.Event {
+	outputs := make([]notify.Output, 0, len(plan.Outputs))
+	for _, output := range plan.Outputs {
+		stateOutput := output.StateOutputFile()
+		outputs = append(outputs, notify.Output{
+			Path:       stateOutput.Path,
+			Kind:       stateOutput.Kind,
+			SourcePath: stateOutput.SourcePath,
+			Transform:  stateOutput.Transform,
+			SHA256:     stateOutput.SHA256,
+			Size:       stateOutput.Size,
+		})
+	}
+	return notify.Event{
+		PipelineID:    plan.PipelineID,
+		DestinationID: plan.DestinationID,
+		BundleID:      plan.BundleID,
+		BundlePath:    plan.BundlePath,
+		Action:        string(plan.Action),
+		Outputs:       outputs,
+	}
+}

internal/app/run_output.go

@@ -0,0 +1,154 @@
+package app
+
+import (
+	"fmt"
+	"io"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/publish"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+)
+
+func writePlanLine(w io.Writer, backend string, plan publish.Plan, planErr error) {
+	if w == nil {
+		return
+	}
+	if planErr != nil {
+		destinationID := plan.DestinationID
+		if destinationID == "" {
+			destinationID = "unknown"
+		}
+		fmt.Fprintf(w, "  - bundle=%s destination=%s backend=%s%s action=error reason=%q\n", storage.DisplayPath(plan.BundlePath), destinationID, backend, pathMappingSummary(plan), planErr.Error())
+		return
+	}
+	fmt.Fprintf(w, "  - bundle=%s destination=%s backend=%s%s action=%s outputs=%s reason=%q\n", storage.DisplayPath(plan.BundlePath), plan.DestinationID, backend, pathMappingSummary(plan), plan.Action, outputSummary(plan.Outputs), plan.Reason)
+}
+
+func pathMappingSummary(plan publish.Plan) string {
+	if plan.PathMapping != config.PathMappingFixed {
+		return ""
+	}
+	return fmt.Sprintf(" path_mapping=fixed target=%s", storage.DisplayPath(plan.DestinationBundlePath))
+}
+
+func writeErrorLine(w io.Writer, bundlePath, destinationID, backend string, err error) {
+	if w == nil {
+		return
+	}
+	fmt.Fprintf(w, "  - bundle=%s destination=%s backend=%s action=error reason=%q\n", storage.DisplayPath(bundlePath), destinationID, backend, err.Error())
+}
+
+func outputSummary(outputs []publish.Output) string {
+	if len(outputs) == 0 {
+		return "none"
+	}
+	paths := make([]string, 0, len(outputs))
+	for _, output := range outputs {
+		paths = append(paths, output.DestinationPath)
+	}
+	return strings.Join(paths, ",")
+}
+
+type runResult struct {
+	DryRun    bool                `json:"dry_run"`
+	Pipelines []runPipelineResult `json:"pipelines"`
+	Actions   []runActionResult   `json:"actions"`
+	Summary   runSummaryResult    `json:"summary"`
+}
+
+type runPipelineResult struct {
+	ID            string   `json:"id"`
+	SourceBackend string   `json:"source_backend"`
+	BundleCount   int      `json:"bundle_count"`
+	Destinations  []string `json:"destinations"`
+}
+
+type runActionResult struct {
+	PipelineID      string            `json:"pipeline_id,omitempty"`
+	DestinationID   string            `json:"destination_id"`
+	Backend         string            `json:"backend"`
+	BundleID        string            `json:"bundle_id,omitempty"`
+	BundlePath      string            `json:"bundle_path"`
+	DestinationPath string            `json:"destination_path"`
+	PathMapping     string            `json:"path_mapping,omitempty"`
+	Action          string            `json:"action"`
+	PrimaryURL      string            `json:"primary_url,omitempty"`
+	Reason          string            `json:"reason,omitempty"`
+	Outputs         []runOutputResult `json:"outputs"`
+}
+
+type runOutputResult struct {
+	Path       string `json:"path"`
+	Kind       string `json:"kind"`
+	SourcePath string `json:"source_path,omitempty"`
+	Transform  string `json:"transform,omitempty"`
+	URL        string `json:"url,omitempty"`
+	SHA256     string `json:"sha256"`
+	Size       int64  `json:"size"`
+}
+
+func runActionFromPlan(backend string, plan publish.Plan, planErr error) runActionResult {
+	if planErr != nil {
+		destinationID := plan.DestinationID
+		if destinationID == "" {
+			destinationID = "unknown"
+		}
+		return runActionResult{
+			PipelineID:      plan.PipelineID,
+			DestinationID:   destinationID,
+			Backend:         backend,
+			BundleID:        plan.BundleID,
+			BundlePath:      storage.DisplayPath(plan.BundlePath),
+			DestinationPath: storage.DisplayPath(plan.DestinationBundlePath),
+			PathMapping:     plan.PathMapping,
+			Action:          "error",
+			PrimaryURL:      plan.PrimaryURL,
+			Reason:          planErr.Error(),
+			Outputs:         []runOutputResult{},
+		}
+	}
+	return runActionResult{
+		PipelineID:      plan.PipelineID,
+		DestinationID:   plan.DestinationID,
+		Backend:         backend,
+		BundleID:        plan.BundleID,
+		BundlePath:      storage.DisplayPath(plan.BundlePath),
+		DestinationPath: storage.DisplayPath(plan.DestinationBundlePath),
+		PathMapping:     plan.PathMapping,
+		Action:          string(plan.Action),
+		PrimaryURL:      plan.PrimaryURL,
+		Reason:          plan.Reason,
+		Outputs:         runOutputsFromPlan(plan.Outputs),
+	}
+}
+
+func errorAction(pipelineID, destinationID, backend, bundlePath string, err error) runActionResult {
+	return runActionResult{
+		PipelineID:      pipelineID,
+		DestinationID:   destinationID,
+		Backend:         backend,
+		BundlePath:      storage.DisplayPath(bundlePath),
+		DestinationPath: storage.DisplayPath(bundlePath),
+		Action:          "error",
+		Reason:          err.Error(),
+		Outputs:         []runOutputResult{},
+	}
+}
+
+func runOutputsFromPlan(outputs []publish.Output) []runOutputResult {
+	results := make([]runOutputResult, 0, len(outputs))
+	for _, output := range outputs {
+		stateOutput := output.StateOutputFile()
+		results = append(results, runOutputResult{
+			Path:       stateOutput.Path,
+			Kind:       stateOutput.Kind,
+			SourcePath: stateOutput.SourcePath,
+			Transform:  stateOutput.Transform,
+			URL:        stateOutput.URL,
+			SHA256:     stateOutput.SHA256,
+			Size:       stateOutput.Size,
+		})
+	}
+	return results
+}

internal/app/run_selection.go

@@ -0,0 +1,91 @@
+package app
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/publish"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+)
+
+type destinationBundleSelection struct {
+	SourceBundle          bundle.Bundle
+	DestinationBundlePath string
+}
+
+func selectDestinationBundles(destination config.Destination, bundles []bundle.Bundle) []destinationBundleSelection {
+	if !isFixedPathDestination(destination) {
+		selections := make([]destinationBundleSelection, 0, len(bundles))
+		for _, sourceBundle := range bundles {
+			selections = append(selections, destinationBundleSelection{
+				SourceBundle:          sourceBundle,
+				DestinationBundlePath: sourceBundle.RootRelativePath,
+			})
+		}
+		return selections
+	}
+	if len(bundles) == 0 {
+		return nil
+	}
+	sourceBundle := newestBundle(bundles)
+	return []destinationBundleSelection{{
+		SourceBundle:          sourceBundle,
+		DestinationBundlePath: "",
+	}}
+}
+
+func newestBundle(bundles []bundle.Bundle) bundle.Bundle {
+	if len(bundles) == 0 {
+		return bundle.Bundle{}
+	}
+	sorted := append([]bundle.Bundle(nil), bundles...)
+	sort.Slice(sorted, func(i, j int) bool {
+		if sorted[i].Manifest.Created.Equal(sorted[j].Manifest.Created) {
+			return sorted[i].RootRelativePath < sorted[j].RootRelativePath
+		}
+		return sorted[i].Manifest.Created.After(sorted[j].Manifest.Created)
+	})
+	return sorted[0]
+}
+
+func isFixedPathDestination(destination config.Destination) bool {
+	return destination.PathMap.Mode == config.PathMappingFixed
+}
+
+func fixedPathSelectionWarning(pipelineID, destinationID string, selections []destinationBundleSelection, candidateCount int) OutputWarning {
+	selected := "none"
+	if len(selections) > 0 {
+		selected = storage.DisplayPath(selections[0].SourceBundle.RootRelativePath)
+	}
+	return OutputWarning{Message: fmt.Sprintf("pipeline=%s destination=%s path_mapping=fixed candidates=%d selected_bundle=%s destination_bundle=.", pipelineID, destinationID, candidateCount, selected)}
+}
+
+func isDestructiveFixedPathAction(action publish.Action) bool {
+	return action == publish.ActionReplaceOlder || action == publish.ActionForceReplace
+}
+
+func fixedPathReplacementWarning(plan publish.Plan) OutputWarning {
+	return OutputWarning{Message: fmt.Sprintf("pipeline=%s destination=%s path_mapping=fixed action=%s replaces destination root for selected_bundle=%s", plan.PipelineID, plan.DestinationID, plan.Action, storage.DisplayPath(plan.BundlePath))}
+}
+
+func destinationIDs(destinations []config.Destination) []string {
+	ids := make([]string, 0, len(destinations))
+	for _, destination := range destinations {
+		ids = append(ids, destination.ID)
+	}
+	return ids
+}
+
+func destinationSummary(destinations []config.Destination) string {
+	if len(destinations) == 0 {
+		return "none"
+	}
+	ids := make([]string, 0, len(destinations))
+	for _, destination := range destinations {
+		ids = append(ids, destination.ID)
+	}
+	return strings.Join(ids, ",")
+}

internal/app/run_summary.go

@@ -0,0 +1,78 @@
+package app
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/publish"
+)
+
+type runSummary struct {
+	dryRun       bool
+	planned      int
+	publishNew   int
+	replaceOlder int
+	forceReplace int
+	skipped      int
+	failures     int
+	fixedPath    int
+}
+
+func (s *runSummary) recordPlan(action publish.Action) {
+	s.planned++
+	switch action {
+	case publish.ActionPublishNew:
+		s.publishNew++
+	case publish.ActionReplaceOlder:
+		s.replaceOlder++
+	case publish.ActionForceReplace:
+		s.forceReplace++
+	case publish.ActionSkipSame, publish.ActionSkipDestinationNewer:
+		s.skipped++
+	}
+}
+
+func (s *runSummary) recordFailure() {
+	s.failures++
+}
+
+func (s *runSummary) recordFixedPath() {
+	s.fixedPath++
+}
+
+func (s runSummary) Line() string {
+	status := "ok"
+	if s.failures > 0 {
+		status = "failed"
+	}
+	return fmt.Sprintf("Final status: %s planned=%d publish_new=%d replace_older=%d force_replace=%d skipped=%d failed=%d dry_run=%t fixed_path=%d", status, s.planned, s.publishNew, s.replaceOlder, s.forceReplace, s.skipped, s.failures, s.dryRun, s.fixedPath)
+}
+
+type runSummaryResult struct {
+	Status       string `json:"status"`
+	Planned      int    `json:"planned"`
+	PublishNew   int    `json:"publish_new"`
+	ReplaceOlder int    `json:"replace_older"`
+	ForceReplace int    `json:"force_replace"`
+	Skipped      int    `json:"skipped"`
+	Failed       int    `json:"failed"`
+	DryRun       bool   `json:"dry_run"`
+	FixedPath    int    `json:"fixed_path"`
+}
+
+func (s runSummary) Result() runSummaryResult {
+	status := "ok"
+	if s.failures > 0 {
+		status = "failed"
+	}
+	return runSummaryResult{
+		Status:       status,
+		Planned:      s.planned,
+		PublishNew:   s.publishNew,
+		ReplaceOlder: s.replaceOlder,
+		ForceReplace: s.forceReplace,
+		Skipped:      s.skipped,
+		Failed:       s.failures,
+		DryRun:       s.dryRun,
+		FixedPath:    s.fixedPath,
+	}
+}

internal/app/run_warnings.go

@@ -0,0 +1,47 @@
+package app
+
+import (
+	"fmt"
+	"io"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+)
+
+func secretConflictWarnings(conflicts []config.SecretConflict) []OutputWarning {
+	warnings := make([]OutputWarning, 0, len(conflicts))
+	for _, conflict := range conflicts {
+		warnings = append(warnings, OutputWarning{
+			Message: fmt.Sprintf("secret %s ignored because the real environment already has that variable", conflict.Name),
+		})
+	}
+	return warnings
+}
+
+func sshWarnings(pipeline config.Pipeline) []OutputWarning {
+	var warnings []OutputWarning
+	if pipeline.Source.Backend == config.BackendSSH && pipeline.Source.SSH.HostKeyPolicy == config.HostKeyPolicyOff {
+		warnings = append(warnings, OutputWarning{
+			Message: fmt.Sprintf("pipeline=%s source host_key_policy=off disables SSH host key checking", pipeline.ID),
+		})
+	}
+	for _, destination := range pipeline.Destinations {
+		if destination.Backend == config.BackendSSH && destination.SSH.HostKeyPolicy == config.HostKeyPolicyOff {
+			warnings = append(warnings, OutputWarning{
+				Message: fmt.Sprintf("pipeline=%s destination=%s host_key_policy=off disables SSH host key checking", pipeline.ID, destination.ID),
+			})
+		}
+	}
+	return warnings
+}
+
+func writeWarnings(w io.Writer, warnings []OutputWarning) error {
+	if w == nil {
+		return nil
+	}
+	for _, warning := range warnings {
+		if _, err := fmt.Fprintf(w, "Warning: %s\n", warning.Message); err != nil {
+			return err
+		}
+	}
+	return nil
+}

internal/app/source_select.go

@@ -0,0 +1,120 @@
+package app
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+)
+
+type sourceCommandOptions struct {
+	CommandName string
+	Path        string
+	ConfigPath  string
+	PipelineID  string
+	BundlePath  string
+}
+
+type sourceSelection struct {
+	Bundles       []bundle.Bundle
+	PipelineID    string
+	SourceBackend string
+	ConfigMode    bool
+	Warnings      []OutputWarning
+}
+
+func selectSourceBundles(ctx context.Context, options sourceCommandOptions, provider backendFactoryProvider) (sourceSelection, error) {
+	if err := ctx.Err(); err != nil {
+		return sourceSelection{}, err
+	}
+	if options.ConfigPath != "" {
+		cfg, err := config.LoadFile(options.ConfigPath)
+		if err != nil {
+			return sourceSelection{}, err
+		}
+		return selectSourceBundlesFromConfig(ctx, cfg, options, provider)
+	}
+	if options.PipelineID != "" {
+		return sourceSelection{}, fmt.Errorf("configured source mode requires --config")
+	}
+	if options.BundlePath != "" {
+		return sourceSelection{}, fmt.Errorf("configured source mode requires --config")
+	}
+	if options.Path == "" {
+		return sourceSelection{}, fmt.Errorf("%s command requires a path", options.CommandName)
+	}
+	backend, err := newBackendFactory().openLocalPath(ctx, options.Path)
+	if err != nil {
+		return sourceSelection{}, err
+	}
+	defer closeBackend(backend)
+	bundles, err := bundle.Discover(ctx, backend, "")
+	if err != nil {
+		return sourceSelection{}, err
+	}
+	return sourceSelection{Bundles: bundles}, nil
+}
+
+func selectSourceBundlesFromConfig(ctx context.Context, cfg config.Config, options sourceCommandOptions, provider backendFactoryProvider) (sourceSelection, error) {
+	if options.Path != "" {
+		return sourceSelection{}, fmt.Errorf("configured source mode does not accept a local path")
+	}
+	if options.PipelineID == "" {
+		return sourceSelection{}, fmt.Errorf("configured source mode requires --pipeline")
+	}
+	secretLoad, err := config.LoadSecretEnvironment(cfg.Secrets.Directory, nil)
+	if err != nil {
+		return sourceSelection{}, err
+	}
+	pipeline, ok := findPipeline(cfg, options.PipelineID)
+	if !ok {
+		return sourceSelection{}, fmt.Errorf("pipeline %q not found", options.PipelineID)
+	}
+	backends := provider(secretLoad.Environment)
+	sourceBackend, err := backends.openSource(ctx, pipeline.Source)
+	if err != nil {
+		return sourceSelection{}, fmt.Errorf("pipeline %s source backend %s: %w", pipeline.ID, pipeline.Source.Backend, err)
+	}
+	defer closeBackend(sourceBackend)
+
+	var bundles []bundle.Bundle
+	if options.BundlePath != "" {
+		sourceBundle, err := bundle.Validate(ctx, sourceBackend, options.BundlePath)
+		if err != nil {
+			return sourceSelection{}, fmt.Errorf("pipeline %s source backend %s bundle %s: %w", pipeline.ID, pipeline.Source.Backend, storage.DisplayPath(options.BundlePath), err)
+		}
+		bundles = []bundle.Bundle{sourceBundle}
+	} else {
+		bundles, err = bundle.Discover(ctx, sourceBackend, "")
+		if err != nil {
+			return sourceSelection{}, fmt.Errorf("pipeline %s source backend %s discover source bundles: %w", pipeline.ID, pipeline.Source.Backend, err)
+		}
+	}
+	return sourceSelection{
+		Bundles:       bundles,
+		PipelineID:    pipeline.ID,
+		SourceBackend: pipeline.Source.Backend,
+		ConfigMode:    true,
+		Warnings:      append(secretConflictWarnings(secretLoad.Conflicts), sourceSSHWarnings(pipeline)...),
+	}, nil
+}
+
+func findPipeline(cfg config.Config, id string) (config.Pipeline, bool) {
+	for _, pipeline := range cfg.Pipelines {
+		if pipeline.ID == id {
+			return pipeline, true
+		}
+	}
+	return config.Pipeline{}, false
+}
+
+func sourceSSHWarnings(pipeline config.Pipeline) []OutputWarning {
+	if pipeline.Source.Backend != config.BackendSSH || pipeline.Source.SSH.HostKeyPolicy != config.HostKeyPolicyOff {
+		return nil
+	}
+	return []OutputWarning{{
+		Message: fmt.Sprintf("pipeline=%s source host_key_policy=off disables SSH host key checking", pipeline.ID),
+	}}
+}

internal/app/validate.go

@@ -5,28 +5,97 @@ import (
 	"fmt"
 	"io"
 
-	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 )
 
 type ValidateOptions struct {
 	Path         string
+	ConfigPath   string
+	PipelineID   string
+	BundlePath   string
 	Stdout       io.Writer
+	OutputFormat OutputFormat
 }
 
 func Validate(ctx context.Context, options ValidateOptions) error {
-	if options.Path == "" {
-		return fmt.Errorf("validate command requires a path")
+	return validateWithBackendFactory(ctx, options, newBackendFactoryWithEnvironment)
 }
-	backend, err := newBackendFactory().openLocalPath(ctx, options.Path)
+
+func validateWithBackendFactory(ctx context.Context, options ValidateOptions, provider backendFactoryProvider) error {
+	if err := ValidateOutputFormat(options.OutputFormat); err != nil {
+		return err
+	}
+	selection, err := selectSourceBundles(ctx, sourceCommandOptions{
+		CommandName: "validate",
+		Path:        options.Path,
+		ConfigPath:  options.ConfigPath,
+		PipelineID:  options.PipelineID,
+		BundlePath:  options.BundlePath,
+	}, provider)
 	if err != nil {
 		return err
 	}
-	bundles, err := bundle.Discover(ctx, backend, "")
+	return writeValidateResult(options, selection)
+}
+
+func validateConfigWithBackendFactory(ctx context.Context, cfg config.Config, options ValidateOptions, provider backendFactoryProvider) error {
+	if err := ValidateOutputFormat(options.OutputFormat); err != nil {
+		return err
+	}
+	selection, err := selectSourceBundlesFromConfig(ctx, cfg, sourceCommandOptions{
+		CommandName: "validate",
+		PipelineID:  options.PipelineID,
+		BundlePath:  options.BundlePath,
+	}, provider)
 	if err != nil {
 		return err
 	}
+	return writeValidateResult(options, selection)
+}
+
+func writeValidateResult(options ValidateOptions, selection sourceSelection) error {
+	if IsJSONOutput(options.OutputFormat) {
+		return WriteJSONEnvelope(options.Stdout, "validate", true, selection.Warnings, validateResultFromSelection(selection), nil)
+	}
+	var err error
 	if options.Stdout != nil {
-		_, err = fmt.Fprintf(options.Stdout, "Validated %d bundle(s)\n", len(bundles))
+		if err := writeWarnings(options.Stdout, selection.Warnings); err != nil {
+			return err
+		}
+		if selection.ConfigMode {
+			_, err = fmt.Fprintf(options.Stdout, "Validated %d bundle(s) for pipeline %s source %s\n", len(selection.Bundles), selection.PipelineID, selection.SourceBackend)
+		} else {
+			_, err = fmt.Fprintf(options.Stdout, "Validated %d bundle(s)\n", len(selection.Bundles))
+		}
 	}
 	return err
 }
+
+type validateResult struct {
+	PipelineID    string                 `json:"pipeline_id,omitempty"`
+	SourceBackend string                 `json:"source_backend,omitempty"`
+	BundleCount   int                    `json:"bundle_count"`
+	Bundles       []validateBundleResult `json:"bundles"`
+}
+
+type validateBundleResult struct {
+	Path string `json:"path"`
+	ID   string `json:"id"`
+}
+
+func validateResultFromSelection(selection sourceSelection) validateResult {
+	result := validateResult{
+		PipelineID:    selection.PipelineID,
+		SourceBackend: selection.SourceBackend,
+		BundleCount:   len(selection.Bundles),
+		Bundles:       make([]validateBundleResult, 0, len(selection.Bundles)),
+	}
+	for _, sourceBundle := range selection.Bundles {
+		result.Bundles = append(result.Bundles, validateBundleResult{
+			Path: storage.DisplayPath(sourceBundle.RootRelativePath),
+			ID:   sourceBundle.Manifest.ID,
+		})
+	}
+	return result
+}

internal/app/validate_test.go

@@ -3,9 +3,15 @@ package app
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
+	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
 )
 
 func TestValidateLocalBundle(t *testing.T) {
@@ -31,9 +37,182 @@ func TestValidateExampleSourceBundle(t *testing.T) {
 	}
 }
 
+func TestValidateConfiguredLocalSource(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	var stdout bytes.Buffer
+
+	err := Validate(context.Background(), ValidateOptions{
+		ConfigPath: testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot),
+		PipelineID: "reports",
+		Stdout:     &stdout,
+	})
+
+	if err != nil {
+		t.Fatalf("Validate() configured source error = %v", err)
+	}
+	if got, want := stdout.String(), "Validated 1 bundle(s) for pipeline reports source local\n"; got != want {
+		t.Fatalf("stdout = %q, want %q", got, want)
+	}
+}
+
+func TestValidateConfiguredSourceBundlePath(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "daily/one", testutil.BundleOptions{ID: "reports.one"})
+	testutil.WriteSourceBundle(t, sourceRoot, "daily/two", testutil.BundleOptions{ID: "reports.two"})
+	var stdout bytes.Buffer
+
+	err := Validate(context.Background(), ValidateOptions{
+		ConfigPath:   testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot),
+		PipelineID:   "reports",
+		BundlePath:   "daily/two",
+		Stdout:       &stdout,
+		OutputFormat: OutputFormatJSON,
+	})
+
+	if err != nil {
+		t.Fatalf("Validate() configured bundle error = %v", err)
+	}
+	result := decodeAppResult(t, stdout.String())
+	if result["pipeline_id"] != "reports" || result["source_backend"] != "local" || result["bundle_count"] != float64(1) {
+		t.Fatalf("result = %#v, want configured source summary", result)
+	}
+	bundles, ok := result["bundles"].([]any)
+	if !ok || len(bundles) != 1 {
+		t.Fatalf("bundles = %#v, want one bundle", result["bundles"])
+	}
+	sourceBundle, ok := bundles[0].(map[string]any)
+	if !ok || sourceBundle["path"] != "daily/two" || sourceBundle["id"] != "reports.two" {
+		t.Fatalf("bundle = %#v, want narrowed bundle", sourceBundle)
+	}
+}
+
+func TestValidateConfiguredRemoteSourcesThroughStorageAbstraction(t *testing.T) {
+	s3Source := fake.New()
+	testutil.WriteFakeSourceBundle(t, s3Source, "", testutil.BundleOptions{ID: "reports.s3"})
+	sshSource := fake.New()
+	testutil.WriteFakeSourceBundle(t, sshSource, "daily", testutil.BundleOptions{ID: "reports.ssh"})
+	cfg := config.Config{Pipelines: []config.Pipeline{
+		{
+			ID: "s3-reports",
+			Source: config.Backend{
+				Backend:  config.BackendS3,
+				Endpoint: "http://s3.test",
+				Bucket:   "source-bucket",
+			},
+			Destinations: []config.Destination{{
+				ID:      "archive",
+				Backend: config.BackendLocal,
+				Path:    t.TempDir(),
+			}},
+		},
+		{
+			ID: "ssh-reports",
+			Source: config.Backend{
+				Backend: config.BackendSSH,
+				Host:    "ssh.test",
+				Path:    "/source",
+			},
+			Destinations: []config.Destination{{
+				ID:      "archive",
+				Backend: config.BackendLocal,
+				Path:    t.TempDir(),
+			}},
+		},
+	}}
+	config.ApplyDefaults(&cfg)
+	provider := fakeBackendFactoryProvider(t, map[string]storage.Backend{
+		"s3:source-bucket": s3Source,
+		"ssh:/source":      sshSource,
+	})
+
+	var s3Stdout bytes.Buffer
+	if err := validateConfigWithBackendFactory(context.Background(), cfg, ValidateOptions{
+		PipelineID:   "s3-reports",
+		Stdout:       &s3Stdout,
+		OutputFormat: OutputFormatJSON,
+	}, provider); err != nil {
+		t.Fatalf("validate s3 source error = %v", err)
+	}
+	s3Result := decodeAppResult(t, s3Stdout.String())
+	if s3Result["source_backend"] != "s3" || s3Result["bundle_count"] != float64(1) {
+		t.Fatalf("s3 result = %#v, want one s3 bundle", s3Result)
+	}
+
+	var sshStdout bytes.Buffer
+	if err := validateConfigWithBackendFactory(context.Background(), cfg, ValidateOptions{
+		PipelineID: "ssh-reports",
+		BundlePath: "daily",
+		Stdout:     &sshStdout,
+	}, provider); err != nil {
+		t.Fatalf("validate ssh source error = %v", err)
+	}
+	if !strings.Contains(sshStdout.String(), "pipeline ssh-reports source ssh") {
+		t.Fatalf("ssh stdout = %q, want ssh source summary", sshStdout.String())
+	}
+}
+
+func TestValidateConfiguredSourceLoadsSecretsBeforeOpeningBackend(t *testing.T) {
+	sourceRoot := filepath.Join(t.TempDir(), "missing-source")
+	destinationRoot := t.TempDir()
+	configPath := writeConfigFile(t, `
+secrets:
+  directory: `+filepath.Join(t.TempDir(), "missing-secrets")+`
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: `+sourceRoot+`
+    destinations:
+      - id: archive
+        backend: local
+        path: `+destinationRoot+`
+`)
+
+	err := Validate(context.Background(), ValidateOptions{ConfigPath: configPath, PipelineID: "reports"})
+	if err == nil {
+		t.Fatal("Validate() error = nil, want secrets directory error")
+	}
+	if !strings.Contains(err.Error(), "load secrets directory") {
+		t.Fatalf("Validate() error = %v, want secrets directory error", err)
+	}
+	if strings.Contains(err.Error(), "missing-source") {
+		t.Fatalf("Validate() error = %v, opened source before loading secrets", err)
+	}
+}
+
+func TestValidateConfiguredSourceRequiresPipeline(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+
+	err := Validate(context.Background(), ValidateOptions{
+		ConfigPath: testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot),
+	})
+
+	if err == nil || !strings.Contains(err.Error(), "requires --pipeline") {
+		t.Fatalf("Validate() error = %v, want required pipeline", err)
+	}
+}
+
 func TestValidateRequiresPath(t *testing.T) {
 	err := Validate(context.Background(), ValidateOptions{})
 	if err == nil || !strings.Contains(err.Error(), "requires a path") {
 		t.Fatalf("Validate() error = %v, want required path", err)
 	}
 }
+
+func decodeAppResult(t *testing.T, output string) map[string]any {
+	t.Helper()
+	var envelope map[string]any
+	if err := json.Unmarshal([]byte(output), &envelope); err != nil {
+		t.Fatalf("decode output: %v; output = %q", err, output)
+	}
+	result, ok := envelope["result"].(map[string]any)
+	if !ok {
+		t.Fatalf("result = %#v, want object", envelope["result"])
+	}
+	return result
+}

internal/bundle/digest.go

@@ -1,49 +1,19 @@
 package bundle
 
-import (
-	"crypto/sha256"
-	"encoding/hex"
-	"fmt"
-	"regexp"
-	"strconv"
-	"strings"
-)
-
-var digestPattern = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`)
+import publicbundle "gitea.maximumdirect.net/eric/distributor/pkg/bundle"
 
 func ValidateDigest(value string) error {
-	if !digestPattern.MatchString(value) {
-		return fmt.Errorf("must be lowercase sha256:<64 hex>")
-	}
-	return nil
+	return publicbundle.ValidateDigest(value)
 }
 
 func FileDigest(data []byte) string {
-	sum := sha256.Sum256(data)
-	return "sha256:" + hex.EncodeToString(sum[:])
+	return publicbundle.FileDigest(data)
 }
 
 func BundleDigest(files []ManifestFile) string {
-	canonical := CanonicalFilePayload(files)
-	sum := sha256.Sum256([]byte(canonical))
-	return "sha256:" + hex.EncodeToString(sum[:])
+	return publicbundle.BundleDigest(files)
 }
 
 func CanonicalFilePayload(files []ManifestFile) string {
-	var builder strings.Builder
-	builder.WriteByte('[')
-	for index, file := range files {
-		if index > 0 {
-			builder.WriteByte(',')
-		}
-		builder.WriteString(`{"path":`)
-		builder.WriteString(strconv.Quote(file.Path))
-		builder.WriteString(`,"sha256":`)
-		builder.WriteString(strconv.Quote(file.SHA256))
-		builder.WriteString(`,"size":`)
-		builder.WriteString(strconv.FormatInt(file.Size, 10))
-		builder.WriteByte('}')
-	}
-	builder.WriteByte(']')
-	return builder.String()
+	return publicbundle.CanonicalFilePayload(files)
 }

internal/bundle/manifest.go

@@ -1,110 +1,32 @@
 package bundle
 
-import (
-	"bytes"
-	"encoding/json"
-	"fmt"
-	"io"
-	"time"
-)
+import publicbundle "gitea.maximumdirect.net/eric/distributor/pkg/bundle"
 
-const ManifestName = "manifest.json"
+const ManifestName = publicbundle.ManifestName
 
-type Manifest struct {
-	SchemaVersion int            `json:"schema_version"`
-	ID            string         `json:"id"`
-	Digest        string         `json:"digest"`
-	Created       time.Time      `json:"created"`
-	Files         []ManifestFile `json:"files"`
-}
+const SchemaVersion = publicbundle.SchemaVersion
 
-type ManifestFile struct {
-	Path   string `json:"path"`
-	SHA256 string `json:"sha256"`
-	Size   int64  `json:"size"`
-}
+type Manifest = publicbundle.Manifest
+
+type ManifestFile = publicbundle.ManifestFile
 
 type Bundle struct {
 	RootRelativePath string
 	Manifest         Manifest
 }
 
-type rawManifest struct {
-	SchemaVersion *int              `json:"schema_version"`
-	ID            *string           `json:"id"`
-	Digest        *string           `json:"digest"`
-	Created       *string           `json:"created"`
-	Files         []rawManifestFile `json:"files"`
-}
-
-type rawManifestFile struct {
-	Path   *string `json:"path"`
-	SHA256 *string `json:"sha256"`
-	Size   *int64  `json:"size"`
-}
-
 func ParseManifest(data []byte) (Manifest, error) {
-	decoder := json.NewDecoder(bytes.NewReader(data))
-	var raw rawManifest
-	if err := decoder.Decode(&raw); err != nil {
-		return Manifest{}, fmt.Errorf("parse manifest: %w", err)
-	}
-	var extra any
-	if err := decoder.Decode(&extra); err != io.EOF {
-		return Manifest{}, fmt.Errorf("parse manifest: trailing data")
+	return publicbundle.ParseManifest(data)
 }
 
-	var manifest Manifest
-	if raw.SchemaVersion == nil {
-		return Manifest{}, fmt.Errorf("manifest schema_version is required")
-	}
-	manifest.SchemaVersion = *raw.SchemaVersion
-	if raw.ID == nil || *raw.ID == "" {
-		return Manifest{}, fmt.Errorf("manifest id is required")
-	}
-	manifest.ID = *raw.ID
-	if raw.Digest == nil || *raw.Digest == "" {
-		return Manifest{}, fmt.Errorf("manifest digest is required")
-	}
-	manifest.Digest = *raw.Digest
-	if raw.Created == nil || *raw.Created == "" {
-		return Manifest{}, fmt.Errorf("manifest created is required")
-	}
-	created, err := time.Parse(time.RFC3339, *raw.Created)
-	if err != nil {
-		return Manifest{}, fmt.Errorf("manifest created must be RFC3339: %w", err)
-	}
-	manifest.Created = created
-	if len(raw.Files) == 0 {
-		return Manifest{}, fmt.Errorf("manifest files is required")
+func MarshalManifest(manifest Manifest) ([]byte, error) {
+	return publicbundle.MarshalManifest(manifest)
 }
 
-	for index, rawFile := range raw.Files {
-		file, err := parseManifestFile(index, rawFile)
-		if err != nil {
-			return Manifest{}, err
-		}
-		manifest.Files = append(manifest.Files, file)
-	}
-	if err := ValidateManifest(manifest); err != nil {
-		return Manifest{}, fmt.Errorf("manifest %w", err)
-	}
-	return manifest, nil
+func ValidateManifest(manifest Manifest) error {
+	return publicbundle.ValidateManifest(manifest)
 }
 
-func parseManifestFile(index int, raw rawManifestFile) (ManifestFile, error) {
-	if raw.Path == nil || *raw.Path == "" {
-		return ManifestFile{}, fmt.Errorf("manifest files[%d].path is required", index)
-	}
-	if raw.SHA256 == nil || *raw.SHA256 == "" {
-		return ManifestFile{}, fmt.Errorf("manifest files[%d].sha256 is required", index)
-	}
-	if raw.Size == nil {
-		return ManifestFile{}, fmt.Errorf("manifest files[%d].size is required", index)
-	}
-	return ManifestFile{
-		Path:   *raw.Path,
-		SHA256: *raw.SHA256,
-		Size:   *raw.Size,
-	}, nil
+func ValidateSourcePath(path string) error {
+	return publicbundle.ValidateSourcePath(path)
 }

internal/bundle/validate.go

@@ -7,55 +7,6 @@ import (
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 )
 
-func ValidateSourcePath(path string) error {
-	if err := storage.ValidatePath(path); err != nil {
-		return err
-	}
-	switch path {
-	case ManifestName, storage.StateFileName:
-		return fmt.Errorf("%q is reserved", path)
-	}
-	return nil
-}
-
-func ValidateManifest(manifest Manifest) error {
-	if manifest.SchemaVersion != 1 {
-		return fmt.Errorf("schema_version must be 1")
-	}
-	if manifest.ID == "" {
-		return fmt.Errorf("id is required")
-	}
-	if err := ValidateDigest(manifest.Digest); err != nil {
-		return fmt.Errorf("digest: %w", err)
-	}
-	if manifest.Created.IsZero() {
-		return fmt.Errorf("created is required")
-	}
-	if len(manifest.Files) == 0 {
-		return fmt.Errorf("files is required")
-	}
-	seen := make(map[string]struct{}, len(manifest.Files))
-	for index, file := range manifest.Files {
-		if err := ValidateSourcePath(file.Path); err != nil {
-			return fmt.Errorf("files[%d].path: %w", index, err)
-		}
-		if err := ValidateDigest(file.SHA256); err != nil {
-			return fmt.Errorf("files[%d].sha256: %w", index, err)
-		}
-		if file.Size < 0 {
-			return fmt.Errorf("files[%d].size must be non-negative", index)
-		}
-		if _, exists := seen[file.Path]; exists {
-			return fmt.Errorf("files[%d].path duplicates %q", index, file.Path)
-		}
-		seen[file.Path] = struct{}{}
-	}
-	if actual := BundleDigest(manifest.Files); actual != manifest.Digest {
-		return fmt.Errorf("digest mismatch: got %s want %s", actual, manifest.Digest)
-	}
-	return nil
-}
-
 func Validate(ctx context.Context, backend storage.Backend, bundleRoot string) (Bundle, error) {
 	return validateAt(ctx, backend, bundleRoot, bundleRoot)
 }

internal/cli/format.go

@@ -0,0 +1,22 @@
+package cli
+
+import (
+	"flag"
+	"fmt"
+	"io"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/app"
+)
+
+func addFormatFlag(flags *flag.FlagSet) *string {
+	return flags.String("format", string(app.OutputFormatText), "output format: text or json")
+}
+
+func parseOutputFormat(stderr io.Writer, command, raw string) (app.OutputFormat, bool) {
+	format := app.OutputFormat(raw)
+	if err := app.ValidateOutputFormat(format); err != nil {
+		fmt.Fprintf(stderr, "%s: %s --format: %s\n", app.Name, command, err)
+		return "", false
+	}
+	return app.NormalizeOutputFormat(format), true
+}

internal/cli/inspect.go

@@ -13,11 +13,18 @@ func inspectCommand(ctx context.Context, args []string, stdout, stderr io.Writer
 		printInspectHelp(stdout)
 		return exitOK
 	}
-	path, ok := parseOptionalPathArg(stderr, "inspect", args)
+	parsed, ok := parseSourceDiagnosticArgs(stderr, "inspect", args)
 	if !ok {
 		return exitUsage
 	}
-	if err := app.Inspect(ctx, app.InspectOptions{Path: path, Stdout: stdout}); err != nil {
+	if err := app.Inspect(ctx, app.InspectOptions{
+		Path:         parsed.Path,
+		ConfigPath:   parsed.ConfigPath,
+		PipelineID:   parsed.PipelineID,
+		BundlePath:   parsed.BundlePath,
+		Stdout:       stdout,
+		OutputFormat: parsed.OutputFormat,
+	}); err != nil {
 		return fail(stderr, err)
 	}
 	return exitOK
@@ -25,8 +32,16 @@ func inspectCommand(ctx context.Context, args []string, stdout, stderr io.Writer
 
 func printInspectHelp(w io.Writer) {
 	fmt.Fprint(w, `Usage:
-  distributor inspect <path>
+  distributor inspect [--format text|json] <path>
+  distributor inspect --config <path> --pipeline <id> [--bundle <path>] [--format text|json]
 
-Print a normalized summary of local source bundles.
+Options:
+  --config <path>     Path to config file for configured source inspection
+  --pipeline <id>     Pipeline id to inspect in config mode
+  --bundle <path>     Source-root-relative bundle path to inspect
+  --format text|json  Output format
+
+Print a normalized summary of local source bundles or a configured pipeline
+source.
 `)
 }

internal/cli/manifest.go

@@ -0,0 +1,139 @@
+package cli
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/app"
+)
+
+func manifestCommand(ctx context.Context, args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 || args[0] == "-h" || args[0] == "--help" || args[0] == "help" {
+		printManifestHelp(stdout)
+		return exitOK
+	}
+	switch args[0] {
+	case "create":
+		return manifestCreateCommand(ctx, args[1:], stdout, stderr)
+	default:
+		fmt.Fprintf(stderr, "%s: manifest unknown command %q\n\n", app.Name, args[0])
+		printManifestHelp(stderr)
+		return exitUsage
+	}
+}
+
+func manifestCreateCommand(ctx context.Context, args []string, stdout, stderr io.Writer) int {
+	if hasHelp(args) {
+		printManifestCreateHelp(stdout)
+		return exitOK
+	}
+	flags := flag.NewFlagSet("manifest create", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	id := flags.String("id", "", "source bundle id")
+	created := flags.String("created", "", "source created timestamp")
+	overwrite := flags.Bool("overwrite", false, "replace an existing manifest.json")
+	formatFlag := addFormatFlag(flags)
+	var files repeatedFlag
+	flags.Var(&files, "file", "bundle-relative file to include")
+	flagArgs, positionalArgs, ok := splitManifestCreateArgs(stderr, args)
+	if !ok {
+		return exitUsage
+	}
+	if err := flags.Parse(flagArgs); err != nil {
+		return exitUsage
+	}
+	if len(positionalArgs) != 1 {
+		fmt.Fprintf(stderr, "%s: manifest create requires exactly one bundle path\n", app.Name)
+		return exitUsage
+	}
+	format, ok := parseOutputFormat(stderr, "manifest create", *formatFlag)
+	if !ok {
+		return exitUsage
+	}
+	err := app.ManifestCreate(ctx, app.ManifestCreateOptions{
+		Root:         positionalArgs[0],
+		ID:           *id,
+		Created:      *created,
+		Files:        []string(files),
+		Overwrite:    *overwrite,
+		Stdout:       stdout,
+		OutputFormat: format,
+	})
+	if err != nil {
+		return fail(stderr, err)
+	}
+	return exitOK
+}
+
+func splitManifestCreateArgs(stderr io.Writer, args []string) ([]string, []string, bool) {
+	var flagArgs []string
+	var positionalArgs []string
+	for index := 0; index < len(args); index++ {
+		arg := args[index]
+		switch arg {
+		case "--overwrite":
+			flagArgs = append(flagArgs, arg)
+		case "--id", "--created", "--file", "--format":
+			if index+1 >= len(args) {
+				fmt.Fprintf(stderr, "%s: manifest create %s requires a value\n", app.Name, arg)
+				return nil, nil, false
+			}
+			flagArgs = append(flagArgs, arg, args[index+1])
+			index++
+		default:
+			if strings.HasPrefix(arg, "--id=") ||
+				strings.HasPrefix(arg, "--created=") ||
+				strings.HasPrefix(arg, "--file=") ||
+				strings.HasPrefix(arg, "--format=") {
+				flagArgs = append(flagArgs, arg)
+				continue
+			}
+			if strings.HasPrefix(arg, "-") {
+				flagArgs = append(flagArgs, arg)
+				continue
+			}
+			positionalArgs = append(positionalArgs, arg)
+		}
+	}
+	return flagArgs, positionalArgs, true
+}
+
+type repeatedFlag []string
+
+func (f *repeatedFlag) String() string {
+	return fmt.Sprint([]string(*f))
+}
+
+func (f *repeatedFlag) Set(value string) error {
+	*f = append(*f, value)
+	return nil
+}
+
+func printManifestHelp(w io.Writer) {
+	fmt.Fprint(w, `Usage:
+  distributor manifest <command> [options]
+
+Commands:
+  create    Create a source bundle manifest
+
+Use "distributor manifest <command> --help" for command-specific help.
+`)
+}
+
+func printManifestCreateHelp(w io.Writer) {
+	fmt.Fprint(w, `Usage:
+  distributor manifest create <bundle-path> --id <bundle-id> [options]
+
+Options:
+  --id <bundle-id>     Source bundle id
+  --file <path>        Bundle-relative file to include; repeatable
+  --created <time>     RFC3339 source created timestamp
+  --overwrite          Replace an existing manifest.json
+  --format text|json   Output format
+
+Create manifest.json for a local source bundle directory.
+`)
+}

internal/cli/root.go

@@ -33,6 +33,8 @@ func Execute(ctx context.Context, args []string, stdout, stderr io.Writer) int {
 		return validateCommand(ctx, args[1:], stdout, stderr)
 	case "inspect":
 		return inspectCommand(ctx, args[1:], stdout, stderr)
+	case "manifest":
+		return manifestCommand(ctx, args[1:], stdout, stderr)
 	default:
 		fmt.Fprintf(stderr, "%s: unknown command %q\n\n", app.Name, args[0])
 		printRootHelp(stderr)
@@ -51,6 +53,7 @@ Commands:
   run        Run configured distribution pipelines
   validate   Validate a source bundle or bundle tree
   inspect    Inspect bundles or distributor state
+  manifest   Create source bundle manifests
 
 Use "%s <command> --help" for command-specific help.
 `, app.Name, app.Name, app.Name)

internal/cli/root_test.go

@@ -3,6 +3,9 @@ package cli
 import (
 	"bytes"
 	"context"
+	"encoding/json"
+	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
@@ -10,8 +13,32 @@ import (
 
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
+	producerbundle "gitea.maximumdirect.net/eric/distributor/pkg/bundle"
 )
 
+func decodeEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]any {
+	t.Helper()
+	decoder := json.NewDecoder(strings.NewReader(stdout.String()))
+	var envelope map[string]any
+	if err := decoder.Decode(&envelope); err != nil {
+		t.Fatalf("decode JSON envelope: %v; stdout = %q", err, stdout.String())
+	}
+	var extra any
+	if err := decoder.Decode(&extra); err != io.EOF {
+		t.Fatalf("stdout contains more than one JSON document: %q", stdout.String())
+	}
+	return envelope
+}
+
+func envelopeResult(t *testing.T, envelope map[string]any) map[string]any {
+	t.Helper()
+	result, ok := envelope["result"].(map[string]any)
+	if !ok {
+		t.Fatalf("result = %#v, want object", envelope["result"])
+	}
+	return result
+}
+
 func TestExecuteRootHelp(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 
@@ -44,6 +71,43 @@ func TestExecuteVersion(t *testing.T) {
 	}
 }
 
+func TestExecuteVersionJSON(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"version", "--format", "json"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	if envelope["command"] != "version" || envelope["ok"] != true {
+		t.Fatalf("envelope = %#v, want version ok", envelope)
+	}
+	result := envelopeResult(t, envelope)
+	if result["application"] != "distributor" || result["version"] != "dev" {
+		t.Fatalf("result = %#v, want application/version", result)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecuteRejectsInvalidFormat(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"version", "--format", "xml"}, &stdout, &stderr)
+
+	if code != exitUsage {
+		t.Fatalf("exit code = %d, want %d", code, exitUsage)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout = %q, want empty", stdout.String())
+	}
+	if !strings.Contains(stderr.String(), "format must be text or json") {
+		t.Fatalf("stderr = %q, want invalid format error", stderr.String())
+	}
+}
+
 func TestExecuteValidate(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 
@@ -57,6 +121,63 @@ func TestExecuteValidate(t *testing.T) {
 	}
 }
 
+func TestExecuteValidateJSON(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"validate", "--format", "json", filepath.Join("..", "bundle", "testdata", "valid_bundle")}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	if envelope["command"] != "validate" || envelope["ok"] != true {
+		t.Fatalf("envelope = %#v, want validate ok", envelope)
+	}
+	result := envelopeResult(t, envelope)
+	if result["bundle_count"] != float64(1) {
+		t.Fatalf("result = %#v, want one bundle", result)
+	}
+}
+
+func TestExecuteValidateConfiguredSource(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	configPath := testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot)
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"validate", "--config", configPath, "--pipeline", "reports"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	if got, want := stdout.String(), "Validated 1 bundle(s) for pipeline reports source local\n"; got != want {
+		t.Fatalf("stdout = %q, want %q", got, want)
+	}
+}
+
+func TestExecuteValidateConfiguredSourceJSON(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "daily", testutil.BundleOptions{ID: "reports.daily"})
+	configPath := testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot)
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"validate", "--config", configPath, "--pipeline", "reports", "--bundle", "daily", "--format", "json"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	if envelope["command"] != "validate" || envelope["ok"] != true {
+		t.Fatalf("envelope = %#v, want validate ok", envelope)
+	}
+	result := envelopeResult(t, envelope)
+	if result["pipeline_id"] != "reports" || result["source_backend"] != "local" || result["bundle_count"] != float64(1) {
+		t.Fatalf("result = %#v, want configured source metadata", result)
+	}
+}
+
 func TestExecuteValidateArgs(t *testing.T) {
 	validPath := filepath.Join("..", "bundle", "testdata", "valid_bundle")
 	tests := []struct {
@@ -84,6 +205,36 @@ func TestExecuteValidateArgs(t *testing.T) {
 			wantCode:   exitUsage,
 			wantStderr: "accepts at most one path",
 		},
+		{
+			name:       "path plus config",
+			args:       []string{"validate", "--config", "config.yml", "--pipeline", "reports", validPath},
+			wantCode:   exitUsage,
+			wantStderr: "does not accept a local path",
+		},
+		{
+			name:       "pipeline without config",
+			args:       []string{"validate", "--pipeline", "reports"},
+			wantCode:   exitUsage,
+			wantStderr: "requires --config",
+		},
+		{
+			name:       "bundle without config",
+			args:       []string{"validate", "--bundle", "daily"},
+			wantCode:   exitUsage,
+			wantStderr: "requires --config",
+		},
+		{
+			name:       "config without pipeline",
+			args:       []string{"validate", "--config", "config.yml"},
+			wantCode:   exitUsage,
+			wantStderr: "requires --pipeline",
+		},
+		{
+			name:       "invalid format",
+			args:       []string{"validate", "--format", "xml", validPath},
+			wantCode:   exitUsage,
+			wantStderr: "format must be text or json",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -115,6 +266,56 @@ func TestExecuteInspect(t *testing.T) {
 	}
 }
 
+func TestExecuteInspectJSON(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"inspect", "--format", "json", filepath.Join("..", "bundle", "testdata", "valid_bundle")}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	if envelope["command"] != "inspect" || envelope["ok"] != true {
+		t.Fatalf("envelope = %#v, want inspect ok", envelope)
+	}
+	result := envelopeResult(t, envelope)
+	bundles, ok := result["bundles"].([]any)
+	if !ok || len(bundles) != 1 {
+		t.Fatalf("bundles = %#v, want one bundle", result["bundles"])
+	}
+	bundle, ok := bundles[0].(map[string]any)
+	if !ok {
+		t.Fatalf("bundle = %#v, want object", bundles[0])
+	}
+	if bundle["id"] != "weather.daily.brentwood.2026-05-30" || bundle["file_count"] != float64(2) || bundle["total_size"] != float64(24) {
+		t.Fatalf("bundle = %#v, want normalized metadata", bundle)
+	}
+}
+
+func TestExecuteInspectConfiguredSource(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "daily", testutil.BundleOptions{ID: "reports.daily"})
+	configPath := testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot)
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"inspect", "--config", configPath, "--pipeline", "reports"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	for _, want := range []string{
+		"Pipeline: reports",
+		"Source: local",
+		"path=daily",
+		"id=reports.daily",
+	} {
+		if !strings.Contains(stdout.String(), want) {
+			t.Fatalf("stdout = %q, want substring %q", stdout.String(), want)
+		}
+	}
+}
+
 func TestExecuteInspectArgs(t *testing.T) {
 	validPath := filepath.Join("..", "bundle", "testdata", "valid_bundle")
 	tests := []struct {
@@ -142,6 +343,36 @@ func TestExecuteInspectArgs(t *testing.T) {
 			wantCode:   exitUsage,
 			wantStderr: "accepts at most one path",
 		},
+		{
+			name:       "path plus config",
+			args:       []string{"inspect", "--config", "config.yml", "--pipeline", "reports", validPath},
+			wantCode:   exitUsage,
+			wantStderr: "does not accept a local path",
+		},
+		{
+			name:       "pipeline without config",
+			args:       []string{"inspect", "--pipeline", "reports"},
+			wantCode:   exitUsage,
+			wantStderr: "requires --config",
+		},
+		{
+			name:       "bundle without config",
+			args:       []string{"inspect", "--bundle", "daily"},
+			wantCode:   exitUsage,
+			wantStderr: "requires --config",
+		},
+		{
+			name:       "config without pipeline",
+			args:       []string{"inspect", "--config", "config.yml"},
+			wantCode:   exitUsage,
+			wantStderr: "requires --pipeline",
+		},
+		{
+			name:       "invalid format",
+			args:       []string{"inspect", "--format", "xml", validPath},
+			wantCode:   exitUsage,
+			wantStderr: "format must be text or json",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -160,6 +391,206 @@ func TestExecuteInspectArgs(t *testing.T) {
 	}
 }
 
+func TestExecuteManifestCreateExplicitFiles(t *testing.T) {
+	root := t.TempDir()
+	writeCLIFile(t, root, "b.txt", "bravo")
+	writeCLIFile(t, root, "nested/a.txt", "alpha")
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{
+		"manifest", "create", root,
+		"--id", "reports.explicit",
+		"--created", "2026-06-01T11:00:00Z",
+		"--file", "b.txt",
+		"--file", "nested/a.txt",
+	}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	for _, want := range []string{
+		"created manifest.json",
+		"bundle: reports.explicit",
+		"files: 2",
+		"digest: sha256:",
+	} {
+		if !strings.Contains(stdout.String(), want) {
+			t.Fatalf("stdout = %q, want substring %q", stdout.String(), want)
+		}
+	}
+	manifest, err := producerbundle.LoadManifest(root)
+	if err != nil {
+		t.Fatalf("LoadManifest() error = %v", err)
+	}
+	if got, want := manifestPaths(manifest), []string{"b.txt", "nested/a.txt"}; !equalStrings(got, want) {
+		t.Fatalf("manifest paths = %v, want %v", got, want)
+	}
+	if err := producerbundle.ValidateBundle(root, manifest); err != nil {
+		t.Fatalf("ValidateBundle() error = %v", err)
+	}
+	var validateStdout, validateStderr bytes.Buffer
+	validateCode := Execute(context.Background(), []string{"validate", root}, &validateStdout, &validateStderr)
+	if validateCode != exitOK {
+		t.Fatalf("validate exit code = %d, want %d; stderr = %q", validateCode, exitOK, validateStderr.String())
+	}
+}
+
+func TestExecuteManifestCreateScansBundle(t *testing.T) {
+	root := t.TempDir()
+	writeCLIFile(t, root, "z.txt", "zulu")
+	writeCLIFile(t, root, ".env", "dotfile")
+	writeCLIFile(t, root, "nested/report.md", "# Report\n")
+	writeCLIFile(t, root, storage.StateFileName, "destination state")
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"manifest", "create", root, "--id", "reports.scan"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	manifest, err := producerbundle.LoadManifest(root)
+	if err != nil {
+		t.Fatalf("LoadManifest() error = %v", err)
+	}
+	if got, want := manifestPaths(manifest), []string{".env", "nested/report.md", "z.txt"}; !equalStrings(got, want) {
+		t.Fatalf("manifest paths = %v, want %v", got, want)
+	}
+}
+
+func TestExecuteManifestCreateJSON(t *testing.T) {
+	root := t.TempDir()
+	writeCLIFile(t, root, "report.md", "# Report\n")
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"manifest", "create", root, "--id", "reports.json", "--file", "report.md", "--format", "json"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	if envelope["command"] != "manifest create" || envelope["ok"] != true {
+		t.Fatalf("envelope = %#v, want manifest create ok", envelope)
+	}
+	result := envelopeResult(t, envelope)
+	if result["id"] != "reports.json" || result["file_count"] != float64(1) {
+		t.Fatalf("result = %#v, want manifest summary", result)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecuteManifestCreateOverwrite(t *testing.T) {
+	root := t.TempDir()
+	writeCLIFile(t, root, "report.md", "old\n")
+	var stdout, stderr bytes.Buffer
+	code := Execute(context.Background(), []string{"manifest", "create", root, "--id", "reports.old", "--file", "report.md"}, &stdout, &stderr)
+	if code != exitOK {
+		t.Fatalf("initial exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	writeCLIFile(t, root, "report.md", "new\n")
+
+	stdout.Reset()
+	stderr.Reset()
+	code = Execute(context.Background(), []string{"manifest", "create", root, "--id", "reports.new", "--file", "report.md"}, &stdout, &stderr)
+	if code != exitError {
+		t.Fatalf("overwrite exit code = %d, want %d", code, exitError)
+	}
+	if !strings.Contains(stderr.String(), "write manifest") {
+		t.Fatalf("stderr = %q, want write manifest error", stderr.String())
+	}
+	manifest, err := producerbundle.LoadManifest(root)
+	if err != nil {
+		t.Fatalf("LoadManifest() error = %v", err)
+	}
+	if manifest.ID != "reports.old" {
+		t.Fatalf("manifest id = %q, want reports.old", manifest.ID)
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	code = Execute(context.Background(), []string{"manifest", "create", root, "--id", "reports.new", "--file", "report.md", "--overwrite"}, &stdout, &stderr)
+	if code != exitOK {
+		t.Fatalf("overwrite exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	manifest, err = producerbundle.LoadManifest(root)
+	if err != nil {
+		t.Fatalf("LoadManifest() error = %v", err)
+	}
+	if manifest.ID != "reports.new" {
+		t.Fatalf("manifest id = %q, want reports.new", manifest.ID)
+	}
+}
+
+func TestExecuteManifestCreateRejectsSymlink(t *testing.T) {
+	root := t.TempDir()
+	writeCLIFile(t, root, "target.md", "# Report\n")
+	if err := os.Symlink("target.md", filepath.Join(root, "link.md")); err != nil {
+		t.Skipf("symlink unavailable: %v", err)
+	}
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"manifest", "create", root, "--id", "reports.link", "--file", "link.md"}, &stdout, &stderr)
+
+	if code != exitError {
+		t.Fatalf("exit code = %d, want %d", code, exitError)
+	}
+	if !strings.Contains(stderr.String(), "regular file") {
+		t.Fatalf("stderr = %q, want regular file error", stderr.String())
+	}
+}
+
+func TestExecuteManifestCreateArgs(t *testing.T) {
+	root := t.TempDir()
+	writeCLIFile(t, root, "report.md", "# Report\n")
+	tests := []struct {
+		name       string
+		args       []string
+		wantCode   int
+		wantStderr string
+	}{
+		{
+			name:       "missing path",
+			args:       []string{"manifest", "create", "--id", "reports.missing"},
+			wantCode:   exitUsage,
+			wantStderr: "requires exactly one bundle path",
+		},
+		{
+			name:       "missing id",
+			args:       []string{"manifest", "create", root},
+			wantCode:   exitError,
+			wantStderr: "requires --id",
+		},
+		{
+			name:       "bad created",
+			args:       []string{"manifest", "create", root, "--id", "reports.bad", "--created", "June 1"},
+			wantCode:   exitError,
+			wantStderr: "created must be RFC3339",
+		},
+		{
+			name:       "bad format",
+			args:       []string{"manifest", "create", root, "--id", "reports.bad", "--format", "xml"},
+			wantCode:   exitUsage,
+			wantStderr: "format must be text or json",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			code := Execute(context.Background(), tt.args, &stdout, &stderr)
+			if code != tt.wantCode {
+				t.Fatalf("exit code = %d, want %d; stderr = %q", code, tt.wantCode, stderr.String())
+			}
+			if stdout.Len() != 0 {
+				t.Fatalf("stdout = %q, want empty", stdout.String())
+			}
+			if !strings.Contains(stderr.String(), tt.wantStderr) {
+				t.Fatalf("stderr = %q, want substring %q", stderr.String(), tt.wantStderr)
+			}
+		})
+	}
+}
+
 func TestExecuteRunDryRun(t *testing.T) {
 	sourceRoot := t.TempDir()
 	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
@@ -180,6 +611,295 @@ func TestExecuteRunDryRun(t *testing.T) {
 	}
 }
 
+func TestExecuteRunJSONDryRun(t *testing.T) {
+	sourceRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	configPath := testutil.WriteMinimalLocalConfig(t, sourceRoot, t.TempDir())
+
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"run", "--config", configPath, "--dry-run", "--format", "json"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	if envelope["command"] != "run" || envelope["ok"] != true {
+		t.Fatalf("envelope = %#v, want run ok", envelope)
+	}
+	result := envelopeResult(t, envelope)
+	if result["dry_run"] != true {
+		t.Fatalf("result = %#v, want dry_run true", result)
+	}
+	actions, ok := result["actions"].([]any)
+	if !ok || len(actions) != 1 {
+		t.Fatalf("actions = %#v, want one action", result["actions"])
+	}
+	action, ok := actions[0].(map[string]any)
+	if !ok || action["action"] != "publish_new" {
+		t.Fatalf("action = %#v, want publish_new", actions[0])
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecuteRunJSONDryRunReportsFixedPathMapping(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	configPath := filepath.Join(t.TempDir(), "config.yml")
+	if err := os.WriteFile(configPath, []byte(`
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: `+sourceRoot+`
+    destinations:
+      - id: latest
+        backend: local
+        path: `+destinationRoot+`
+        path_mapping:
+          mode: fixed
+`), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"run", "--config", configPath, "--dry-run", "--format", "json"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	warnings, ok := envelope["warnings"].([]any)
+	if !ok || len(warnings) != 1 {
+		t.Fatalf("warnings = %#v, want one fixed-path warning", envelope["warnings"])
+	}
+	warning, ok := warnings[0].(map[string]any)
+	if !ok || !strings.Contains(fmt.Sprint(warning["message"]), "path_mapping=fixed candidates=1 selected_bundle=.") {
+		t.Fatalf("warning = %#v, want fixed-path selection warning", warnings[0])
+	}
+	result := envelopeResult(t, envelope)
+	actions, ok := result["actions"].([]any)
+	if !ok || len(actions) != 1 {
+		t.Fatalf("actions = %#v, want one action", result["actions"])
+	}
+	action, ok := actions[0].(map[string]any)
+	if !ok || action["path_mapping"] != "fixed" || action["destination_path"] != "." || action["action"] != "publish_new" {
+		t.Fatalf("action = %#v, want fixed publish_new at root", actions[0])
+	}
+	summary, ok := result["summary"].(map[string]any)
+	if !ok || summary["fixed_path"] != float64(1) {
+		t.Fatalf("summary = %#v, want fixed_path 1", result["summary"])
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecuteRunJSONDryRunReportsLinks(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	configPath := filepath.Join(t.TempDir(), "config.yml")
+	if err := os.WriteFile(configPath, []byte(`
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: `+sourceRoot+`
+    destinations:
+      - id: web
+        backend: local
+        path: `+destinationRoot+`
+        links:
+          base_url: https://reports.example.com/archive
+          primary: source
+`), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"run", "--config", configPath, "--dry-run", "--format", "json"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	result := envelopeResult(t, envelope)
+	actions, ok := result["actions"].([]any)
+	if !ok || len(actions) != 1 {
+		t.Fatalf("actions = %#v, want one action", result["actions"])
+	}
+	action, ok := actions[0].(map[string]any)
+	if !ok || action["primary_url"] != "https://reports.example.com/archive/report.md" {
+		t.Fatalf("action = %#v, want primary URL", actions[0])
+	}
+	outputs, ok := action["outputs"].([]any)
+	if !ok || len(outputs) != 2 {
+		t.Fatalf("outputs = %#v, want two outputs", action["outputs"])
+	}
+	output, ok := outputs[0].(map[string]any)
+	if !ok || output["url"] != "https://reports.example.com/archive/report.md" {
+		t.Fatalf("output = %#v, want output URL", outputs[0])
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecuteRunJSONWarningsAreStructured(t *testing.T) {
+	name := "DISTRIBUTOR_TEST_CLI_JSON_SECRET"
+	t.Setenv(name, "process-value")
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	secretsRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	if err := os.WriteFile(filepath.Join(secretsRoot, name), []byte("secret-value\n"), 0o600); err != nil {
+		t.Fatalf("write secret: %v", err)
+	}
+	configPath := filepath.Join(t.TempDir(), "config.yml")
+	if err := os.WriteFile(configPath, []byte(`
+secrets:
+  directory: `+secretsRoot+`
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: `+sourceRoot+`
+    destinations:
+      - id: archive
+        backend: local
+        path: `+destinationRoot+`
+`), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	code := Execute(context.Background(), []string{"run", "--config", configPath, "--dry-run", "--format", "json"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	warnings, ok := envelope["warnings"].([]any)
+	if !ok || len(warnings) != 1 {
+		t.Fatalf("warnings = %#v, want one warning", envelope["warnings"])
+	}
+	warning, ok := warnings[0].(map[string]any)
+	if !ok || !strings.Contains(fmt.Sprint(warning["message"]), name) {
+		t.Fatalf("warning = %#v, want secret name", warnings[0])
+	}
+	if strings.Contains(stdout.String(), "Warning:") || strings.Contains(stdout.String(), "process-value") || strings.Contains(stdout.String(), "secret-value") {
+		t.Fatalf("stdout exposed text warning or secret values: %q", stdout.String())
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecuteRunJSONFatalSetupErrorWritesNoJSON(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{"run", "--config", filepath.Join(t.TempDir(), "missing.yml"), "--format", "json"}, &stdout, &stderr)
+
+	if code != exitError {
+		t.Fatalf("exit code = %d, want %d", code, exitError)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout = %q, want empty", stdout.String())
+	}
+	if !strings.Contains(stderr.String(), "no such file or directory") {
+		t.Fatalf("stderr = %q, want setup error", stderr.String())
+	}
+}
+
+func TestExecuteRunJSONPartialFailure(t *testing.T) {
+	sourceRoot := t.TempDir()
+	firstDestination := t.TempDir()
+	secondDestination := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	if err := os.WriteFile(filepath.Join(firstDestination, "unmanaged.txt"), []byte("data"), 0o600); err != nil {
+		t.Fatalf("write unmanaged file: %v", err)
+	}
+	configPath := filepath.Join(t.TempDir(), "config.yml")
+	if err := os.WriteFile(configPath, []byte(`
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: `+sourceRoot+`
+    destinations:
+      - id: archive-one
+        backend: local
+        path: `+firstDestination+`
+      - id: archive-two
+        backend: local
+        path: `+secondDestination+`
+`), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	code := Execute(context.Background(), []string{"run", "--config", configPath, "--format", "json"}, &stdout, &stderr)
+
+	if code != exitError {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitError, stderr.String())
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty for partial JSON result", stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	if envelope["command"] != "run" || envelope["ok"] != false {
+		t.Fatalf("envelope = %#v, want failed run envelope", envelope)
+	}
+	errors, ok := envelope["errors"].([]any)
+	if !ok || len(errors) != 1 {
+		t.Fatalf("errors = %#v, want one error", envelope["errors"])
+	}
+	result := envelopeResult(t, envelope)
+	summary, ok := result["summary"].(map[string]any)
+	if !ok || summary["status"] != "failed" || summary["failed"] != float64(1) {
+		t.Fatalf("summary = %#v, want failed summary", result["summary"])
+	}
+	actions, ok := result["actions"].([]any)
+	if !ok || len(actions) != 2 {
+		t.Fatalf("actions = %#v, want two actions", result["actions"])
+	}
+	if _, err := os.Stat(filepath.Join(secondDestination, storage.StateFileName)); err != nil {
+		t.Fatalf("second destination state stat error = %v", err)
+	}
+}
+
+func TestExecuteRunForceDryRunReportsWithoutWriting(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	if err := os.WriteFile(filepath.Join(destinationRoot, "unmanaged.txt"), []byte("old"), 0o600); err != nil {
+		t.Fatalf("write unmanaged file: %v", err)
+	}
+	configPath := testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot)
+
+	var stdout, stderr bytes.Buffer
+	code := Execute(context.Background(), []string{"run", "--config", configPath, "--force", "--dry-run"}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "action=force_replace") {
+		t.Fatalf("stdout = %q, want force_replace", stdout.String())
+	}
+	if _, err := os.Stat(filepath.Join(destinationRoot, "unmanaged.txt")); err != nil {
+		t.Fatalf("unmanaged file stat error = %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(destinationRoot, storage.StateFileName)); !os.IsNotExist(err) {
+		t.Fatalf("state stat error = %v, want not exist", err)
+	}
+}
+
 func TestExecuteRunRejectsExtraPositionalArgs(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 
@@ -223,3 +943,34 @@ func TestUnknownCommandIsUsageError(t *testing.T) {
 		t.Fatalf("stderr = %q, want unknown command error", stderr.String())
 	}
 }
+
+func manifestPaths(manifest producerbundle.Manifest) []string {
+	paths := make([]string, 0, len(manifest.Files))
+	for _, file := range manifest.Files {
+		paths = append(paths, file.Path)
+	}
+	return paths
+}
+
+func equalStrings(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for index := range a {
+		if a[index] != b[index] {
+			return false
+		}
+	}
+	return true
+}
+
+func writeCLIFile(t *testing.T, root, relative, body string) {
+	t.Helper()
+	path := filepath.Join(root, filepath.FromSlash(relative))
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("mkdir %s: %v", filepath.Dir(path), err)
+	}
+	if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
+		t.Fatalf("write %s: %v", path, err)
+	}
+}

internal/cli/run.go

@@ -19,18 +19,29 @@ func runCommand(ctx context.Context, args []string, stdout, stderr io.Writer) in
 	flags.SetOutput(stderr)
 	configPath := flags.String("config", "", "path to config file")
 	dryRun := flags.Bool("dry-run", false, "load and validate config without publishing")
+	force := flags.Bool("force", false, "allow explicit destructive replacement for supported conflicts")
+	formatFlag := addFormatFlag(flags)
 	if err := flags.Parse(args); err != nil {
 		return exitUsage
 	}
 	if rejectPositionalArgs(stderr, "run", flags.Args()) {
 		return exitUsage
 	}
+	format, ok := parseOutputFormat(stderr, "run", *formatFlag)
+	if !ok {
+		return exitUsage
+	}
 
 	if err := app.Run(ctx, app.RunOptions{
 		ConfigPath:   *configPath,
 		DryRun:       *dryRun,
+		Force:        *force,
 		Stdout:       stdout,
+		OutputFormat: format,
 	}); err != nil {
+		if app.IsJSONOutput(format) && app.IsPartialResultError(err) {
+			return exitError
+		}
 		return fail(stderr, err)
 	}
 	return exitOK
@@ -38,13 +49,16 @@ func runCommand(ctx context.Context, args []string, stdout, stderr io.Writer) in
 
 func printRunHelp(w io.Writer) {
 	fmt.Fprint(w, `Usage:
-  distributor run --config <path> --dry-run
+  distributor run --config <path> [--dry-run] [--force] [--format text|json]
 
 Options:
   --config <path>  Path to config file
   --dry-run        Load and validate config without publishing
+  --force          Allow explicit destructive replacement for supported conflicts
+  --format text|json
+                   Output format
 
-Run discovers local source bundles, plans each configured destination, publishes
+Run discovers configured source bundles, plans each destination, publishes
 selected outputs unless --dry-run is set, and prints a final status summary.
 `)
 }

internal/cli/source_mode.go

@@ -0,0 +1,67 @@
+package cli
+
+import (
+	"flag"
+	"fmt"
+	"io"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/app"
+)
+
+type sourceDiagnosticArgs struct {
+	Path         string
+	ConfigPath   string
+	PipelineID   string
+	BundlePath   string
+	OutputFormat app.OutputFormat
+}
+
+func parseSourceDiagnosticArgs(stderr io.Writer, command string, args []string) (sourceDiagnosticArgs, bool) {
+	flags := flag.NewFlagSet(command, flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	configPath := flags.String("config", "", "path to config file")
+	pipelineID := flags.String("pipeline", "", "pipeline id")
+	bundlePath := flags.String("bundle", "", "source-root-relative bundle path")
+	formatFlag := addFormatFlag(flags)
+	if err := flags.Parse(args); err != nil {
+		return sourceDiagnosticArgs{}, false
+	}
+	format, ok := parseOutputFormat(stderr, command, *formatFlag)
+	if !ok {
+		return sourceDiagnosticArgs{}, false
+	}
+	path, ok := parseOptionalPathArg(stderr, command, flags.Args())
+	if !ok {
+		return sourceDiagnosticArgs{}, false
+	}
+	if !validateInspectModeOK(stderr, command, path, *configPath, *pipelineID, *bundlePath) {
+		return sourceDiagnosticArgs{}, false
+	}
+	return sourceDiagnosticArgs{
+		Path:         path,
+		ConfigPath:   *configPath,
+		PipelineID:   *pipelineID,
+		BundlePath:   *bundlePath,
+		OutputFormat: format,
+	}, true
+}
+
+func validateInspectModeOK(stderr io.Writer, command, path, configPath, pipelineID, bundlePath string) bool {
+	configMode := configPath != "" || pipelineID != "" || bundlePath != ""
+	if !configMode {
+		return true
+	}
+	if path != "" {
+		fmt.Fprintf(stderr, "distributor: %s does not accept a local path with --config, --pipeline, or --bundle\n", command)
+		return false
+	}
+	if configPath == "" {
+		fmt.Fprintf(stderr, "distributor: %s requires --config when --pipeline or --bundle is set\n", command)
+		return false
+	}
+	if pipelineID == "" {
+		fmt.Fprintf(stderr, "distributor: %s requires --pipeline in config mode\n", command)
+		return false
+	}
+	return true
+}

internal/cli/validate.go

@@ -13,11 +13,18 @@ func validateCommand(ctx context.Context, args []string, stdout, stderr io.Write
 		printValidateHelp(stdout)
 		return exitOK
 	}
-	path, ok := parseOptionalPathArg(stderr, "validate", args)
+	parsed, ok := parseSourceDiagnosticArgs(stderr, "validate", args)
 	if !ok {
 		return exitUsage
 	}
-	if err := app.Validate(ctx, app.ValidateOptions{Path: path, Stdout: stdout}); err != nil {
+	if err := app.Validate(ctx, app.ValidateOptions{
+		Path:         parsed.Path,
+		ConfigPath:   parsed.ConfigPath,
+		PipelineID:   parsed.PipelineID,
+		BundlePath:   parsed.BundlePath,
+		Stdout:       stdout,
+		OutputFormat: parsed.OutputFormat,
+	}); err != nil {
 		return fail(stderr, err)
 	}
 	return exitOK
@@ -25,8 +32,16 @@ func validateCommand(ctx context.Context, args []string, stdout, stderr io.Write
 
 func printValidateHelp(w io.Writer) {
 	fmt.Fprint(w, `Usage:
-  distributor validate <path>
+  distributor validate [--format text|json] <path>
+  distributor validate --config <path> --pipeline <id> [--bundle <path>] [--format text|json]
 
-Validate a local source bundle directory or a tree containing source bundles.
+Options:
+  --config <path>     Path to config file for configured source validation
+  --pipeline <id>     Pipeline id to validate in config mode
+  --bundle <path>     Source-root-relative bundle path to validate
+  --format text|json  Output format
+
+Validate a local source bundle directory, a local source bundle tree, or a
+configured pipeline source.
 `)
 }

internal/cli/version.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"context"
+	"flag"
 	"fmt"
 	"io"
 
@@ -13,16 +14,44 @@ func versionCommand(_ context.Context, args []string, stdout, stderr io.Writer)
 		printVersionHelp(stdout)
 		return exitOK
 	}
-	if rejectExtraArgs(stderr, "version", args) {
+	flags := flag.NewFlagSet("version", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	formatFlag := addFormatFlag(flags)
+	if err := flags.Parse(args); err != nil {
 		return exitUsage
 	}
+	if rejectExtraArgs(stderr, "version", flags.Args()) {
+		return exitUsage
+	}
+	format, ok := parseOutputFormat(stderr, "version", *formatFlag)
+	if !ok {
+		return exitUsage
+	}
+	if app.IsJSONOutput(format) {
+		err := app.WriteJSONEnvelope(stdout, "version", true, nil, versionResult{
+			Application: app.Name,
+			Version:     app.Version,
+		}, nil)
+		if err != nil {
+			return fail(stderr, err)
+		}
+		return exitOK
+	}
 	fmt.Fprintln(stdout, app.VersionString())
 	return exitOK
 }
 
+type versionResult struct {
+	Application string `json:"application"`
+	Version     string `json:"version"`
+}
+
 func printVersionHelp(w io.Writer) {
 	fmt.Fprint(w, `Usage:
-  distributor version
+  distributor version [--format text|json]
+
+Options:
+  --format text|json  Output format
 
 Print version information.
 `)

internal/config/config.go

@@ -1,9 +1,14 @@
 package config
 
 type Config struct {
+	Secrets   Secrets    `yaml:"secrets"`
 	Pipelines []Pipeline `yaml:"pipelines"`
 }
 
+type Secrets struct {
+	Directory string `yaml:"directory"`
+}
+
 type Pipeline struct {
 	ID           string           `yaml:"id"`
 	Source       Backend          `yaml:"source"`
@@ -14,29 +19,43 @@ type Pipeline struct {
 type Destination struct {
 	ID        string         `yaml:"id"`
 	Backend   string         `yaml:"backend"`
+	Host      string         `yaml:"host"`
+	User      string         `yaml:"user"`
+	Port      int            `yaml:"port"`
 	Path      string         `yaml:"path"`
-	URI       string         `yaml:"uri"`
 	Endpoint  string         `yaml:"endpoint"`
 	Bucket    string         `yaml:"bucket"`
 	Prefix    string         `yaml:"prefix"`
 	Region    string         `yaml:"region"`
-	ForcePath bool           `yaml:"force_path_style"`
+	ForcePath *bool          `yaml:"force_path_style"`
 	Creds     Credentials    `yaml:"credentials"`
+	SSH       SSH            `yaml:",inline"`
 	Publish   *PublishPolicy `yaml:"publish"`
 	Transform Transform      `yaml:"transform"`
+	PathMap   PathMapping    `yaml:"path_mapping"`
+	Links     *Links         `yaml:"links"`
 	Transfer  TransferPolicy `yaml:"transfer"`
 }
 
 type Backend struct {
 	Backend   string      `yaml:"backend"`
+	Host      string      `yaml:"host"`
+	User      string      `yaml:"user"`
+	Port      int         `yaml:"port"`
 	Path      string      `yaml:"path"`
-	URI       string      `yaml:"uri"`
 	Endpoint  string      `yaml:"endpoint"`
 	Bucket    string      `yaml:"bucket"`
 	Prefix    string      `yaml:"prefix"`
 	Region    string      `yaml:"region"`
-	ForcePath bool        `yaml:"force_path_style"`
+	ForcePath *bool       `yaml:"force_path_style"`
 	Creds     Credentials `yaml:"credentials"`
+	SSH       SSH         `yaml:",inline"`
+}
+
+type SSH struct {
+	KeyFile       string        `yaml:"ssh_key_file"`
+	KnownHosts    string        `yaml:"known_hosts"`
+	HostKeyPolicy HostKeyPolicy `yaml:"host_key_policy"`
 }
 
 type Credentials struct {
@@ -60,6 +79,16 @@ type Transform struct {
 type MarkdownToHTML struct {
 	Enabled bool   `yaml:"enabled"`
 	Mode    string `yaml:"mode"`
+	Input   string `yaml:"input"`
+}
+
+type PathMapping struct {
+	Mode string `yaml:"mode"`
+}
+
+type Links struct {
+	BaseURL string `yaml:"base_url"`
+	Primary string `yaml:"primary"`
 }
 
 type TransferPolicy struct {

internal/config/defaults.go

@@ -1,5 +1,7 @@
 package config
 
+import "gitea.maximumdirect.net/eric/distributor/internal/transform"
+
 const DefaultConfigPath = "/usr/local/etc/distributor/config.yml"
 
 const (
@@ -19,20 +21,45 @@ const (
 )
 
 const (
-	TransformModeSidecar = "sidecar"
+	TransformModeSidecar = transform.MarkdownModeSidecar
+	TransformModeIndex   = transform.MarkdownModeIndex
 )
 
+const (
+	PathMappingPreserveRelative = "preserve_relative"
+	PathMappingFixed            = "fixed"
+)
+
+const (
+	LinkPrimaryAuto   = "auto"
+	LinkPrimaryHTML   = "html"
+	LinkPrimarySource = "source"
+)
+
+const DefaultS3Region = "us-east-1"
+
 func ApplyDefaults(cfg *Config) {
 	for pipelineIndex := range cfg.Pipelines {
 		pipeline := &cfg.Pipelines[pipelineIndex]
+		applyBackendDefaults(&pipeline.Source)
 		if pipeline.Validation.OnDigestMismatch == "" {
 			pipeline.Validation.OnDigestMismatch = ValidationActionFail
 		}
 		for destinationIndex := range pipeline.Destinations {
 			destination := &pipeline.Destinations[destinationIndex]
+			applyDestinationDefaults(destination)
 			if destination.Publish == nil {
 				destination.Publish = &PublishPolicy{Source: true}
 			}
+			if destination.Transform.MarkdownToHTML != nil && destination.Transform.MarkdownToHTML.Mode == "" {
+				destination.Transform.MarkdownToHTML.Mode = TransformModeSidecar
+			}
+			if destination.PathMap.Mode == "" {
+				destination.PathMap.Mode = PathMappingPreserveRelative
+			}
+			if destination.Links != nil && destination.Links.Primary == "" {
+				destination.Links.Primary = LinkPrimaryAuto
+			}
 			if destination.Transfer.OnDestinationSame == "" {
 				destination.Transfer.OnDestinationSame = TransferActionSkip
 			}
@@ -48,3 +75,42 @@ func ApplyDefaults(cfg *Config) {
 		}
 	}
 }
+
+func applyBackendDefaults(backend *Backend) {
+	if backend.Backend == BackendSSH {
+		if backend.Port == 0 {
+			backend.Port = 22
+		}
+		if backend.SSH.HostKeyPolicy == "" {
+			backend.SSH.HostKeyPolicy = HostKeyPolicyAcceptNew
+		}
+	}
+	if backend.Backend == BackendS3 {
+		applyS3Defaults(&backend.Region, &backend.Prefix, &backend.ForcePath)
+	}
+}
+
+func applyDestinationDefaults(destination *Destination) {
+	if destination.Backend == BackendSSH {
+		if destination.Port == 0 {
+			destination.Port = 22
+		}
+		if destination.SSH.HostKeyPolicy == "" {
+			destination.SSH.HostKeyPolicy = HostKeyPolicyAcceptNew
+		}
+	}
+	if destination.Backend == BackendS3 {
+		applyS3Defaults(&destination.Region, &destination.Prefix, &destination.ForcePath)
+	}
+}
+
+func applyS3Defaults(region, prefix *string, forcePath **bool) {
+	if *region == "" {
+		*region = DefaultS3Region
+	}
+	*prefix = NormalizeS3Prefix(*prefix)
+	if *forcePath == nil {
+		defaultForcePath := true
+		*forcePath = &defaultForcePath
+	}
+}

internal/config/load_test.go

@@ -33,6 +33,29 @@ pipelines:
 	if got, want := destination.Transfer.OnDestinationOlder, TransferActionReplace; got != want {
 		t.Fatalf("transfer default = %q, want %q", got, want)
 	}
+	if cfg.Secrets.Directory != "" {
+		t.Fatalf("secrets.directory = %q, want empty", cfg.Secrets.Directory)
+	}
+}
+
+func TestLoadFileValidSecretsDirectoryConfig(t *testing.T) {
+	cfg := loadConfig(t, `
+secrets:
+  directory: /run/secrets/distributor
+pipelines:
+  - id: local-copy
+    source:
+      backend: local
+      path: /var/spool/reports
+    destinations:
+      - id: archive
+        backend: local
+        path: /srv/archive
+`)
+
+	if got, want := cfg.Secrets.Directory, "/run/secrets/distributor"; got != want {
+		t.Fatalf("secrets.directory = %q, want %q", got, want)
+	}
 }
 
 func TestLoadFileValidFanOutConfig(t *testing.T) {
@@ -53,7 +76,9 @@ pipelines:
           html: false
       - id: static-site
         backend: ssh
-        uri: ssh://deploy@example.com:22
+        host: example.com
+        user: deploy
+        port: 22
         path: /srv/www/reports
         publish:
           source: false
@@ -69,6 +94,120 @@ pipelines:
 	}
 }
 
+func TestLoadFileValidMarkdownIndexConfig(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: static-site
+    source:
+      backend: local
+      path: /var/spool/reports
+    destinations:
+      - id: web
+        backend: local
+        path: /srv/www/reports
+        publish:
+          source: false
+          html: true
+        transform:
+          markdown_to_html:
+            enabled: true
+            mode: index
+            input: report.md
+`)
+
+	markdown := cfg.Pipelines[0].Destinations[0].Transform.MarkdownToHTML
+	if markdown == nil || markdown.Mode != TransformModeIndex || markdown.Input != "report.md" {
+		t.Fatalf("markdown config = %#v, want index input", markdown)
+	}
+}
+
+func TestLoadFileDefaultsMarkdownModeToSidecar(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: static-site
+    source:
+      backend: local
+      path: /var/spool/reports
+    destinations:
+      - id: web
+        backend: local
+        path: /srv/www/reports
+        publish:
+          source: false
+          html: true
+        transform:
+          markdown_to_html:
+            enabled: true
+`)
+
+	markdown := cfg.Pipelines[0].Destinations[0].Transform.MarkdownToHTML
+	if markdown == nil || markdown.Mode != TransformModeSidecar {
+		t.Fatalf("markdown mode = %#v, want sidecar default", markdown)
+	}
+}
+
+func TestLoadFileDefaultsPathMappingToPreserveRelative(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: /source
+    destinations:
+      - id: archive
+        backend: local
+        path: /destination
+`)
+
+	if got, want := cfg.Pipelines[0].Destinations[0].PathMap.Mode, PathMappingPreserveRelative; got != want {
+		t.Fatalf("path mapping mode = %q, want %q", got, want)
+	}
+}
+
+func TestLoadFileAcceptsFixedPathMapping(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: /source
+    destinations:
+      - id: latest
+        backend: local
+        path: /destination/latest
+        path_mapping:
+          mode: fixed
+`)
+
+	if got, want := cfg.Pipelines[0].Destinations[0].PathMap.Mode, PathMappingFixed; got != want {
+		t.Fatalf("path mapping mode = %q, want %q", got, want)
+	}
+}
+
+func TestLoadFileDefaultsLinksPrimaryToAuto(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: /source
+    destinations:
+      - id: web
+        backend: local
+        path: /destination
+        links:
+          base_url: https://reports.example.com/archive
+`)
+
+	links := cfg.Pipelines[0].Destinations[0].Links
+	if links == nil {
+		t.Fatal("links = nil, want config")
+	}
+	if links.BaseURL != "https://reports.example.com/archive" || links.Primary != LinkPrimaryAuto {
+		t.Fatalf("links = %#v, want base URL with auto primary", links)
+	}
+}
+
 func TestLoadFileValidBackendConfigs(t *testing.T) {
 	tests := map[string]string{
 		"local": `
@@ -87,13 +226,19 @@ pipelines:
   - id: ssh-backend
     source:
       backend: ssh
-      uri: ssh://reports@example.com:22
+      host: source.example.com
+      user: reports
       path: /source
     destinations:
       - id: ssh-destination
         backend: ssh
-        uri: ssh://deploy@example.com:22
+        host: destination.example.com
+        user: deploy
+        port: 2222
         path: /destination
+        ssh_key_file: /home/deploy/.ssh/id_ed25519
+        known_hosts: /home/deploy/.ssh/known_hosts
+        host_key_policy: strict
 `,
 		"s3": `
 pipelines:
@@ -124,6 +269,61 @@ pipelines:
 	}
 }
 
+func TestLoadFileDefaultsS3Config(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: s3-defaults
+    source:
+      backend: s3
+      endpoint: http://127.0.0.1:9000
+      bucket: source
+      prefix: /incoming/reports/
+    destinations:
+      - id: archive
+        backend: s3
+        endpoint: http://127.0.0.1:9000
+        bucket: destination
+`)
+
+	source := cfg.Pipelines[0].Source
+	if got, want := source.Region, DefaultS3Region; got != want {
+		t.Fatalf("source region = %q, want %q", got, want)
+	}
+	if got, want := source.Prefix, "incoming/reports"; got != want {
+		t.Fatalf("source prefix = %q, want %q", got, want)
+	}
+	if !ForcePathStyle(source.ForcePath) {
+		t.Fatal("source force_path_style = false, want true")
+	}
+	destination := cfg.Pipelines[0].Destinations[0]
+	if got, want := destination.Region, DefaultS3Region; got != want {
+		t.Fatalf("destination region = %q, want %q", got, want)
+	}
+	if !ForcePathStyle(destination.ForcePath) {
+		t.Fatal("destination force_path_style = false, want true")
+	}
+}
+
+func TestLoadFilePreservesExplicitS3ForcePathStyleFalse(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: s3-force-path
+    source:
+      backend: s3
+      endpoint: https://s3.example.com
+      bucket: source
+      force_path_style: false
+    destinations:
+      - id: archive
+        backend: local
+        path: /archive
+`)
+
+	if ForcePathStyle(cfg.Pipelines[0].Source.ForcePath) {
+		t.Fatal("force_path_style = true, want explicit false")
+	}
+}
+
 func TestLoadFileRejectsDuplicatePipelineIDs(t *testing.T) {
 	assertLoadError(t, `
 pipelines:
@@ -171,7 +371,7 @@ func TestLoadFileRejectsMissingRequiredFields(t *testing.T) {
 		"destinations":    `pipelines: [{id: reports, source: {backend: local, path: /source}}]`,
 		"destination id":  `pipelines: [{id: reports, source: {backend: local, path: /source}, destinations: [{backend: local, path: /archive}]}]`,
 		"local path":      `pipelines: [{id: reports, source: {backend: local}, destinations: [{id: archive, backend: local, path: /archive}]}]`,
-		"ssh uri":         `pipelines: [{id: reports, source: {backend: ssh, path: /source}, destinations: [{id: archive, backend: local, path: /archive}]}]`,
+		"ssh host":        `pipelines: [{id: reports, source: {backend: ssh, path: /source}, destinations: [{id: archive, backend: local, path: /archive}]}]`,
 		"s3 bucket":       `pipelines: [{id: reports, source: {backend: s3, endpoint: "https://s3.example.com"}, destinations: [{id: archive, backend: local, path: /archive}]}]`,
 		"publish outputs": `pipelines: [{id: reports, source: {backend: local, path: /source}, destinations: [{id: archive, backend: local, path: /archive, publish: {source: false, html: false}}]}]`,
 	}
@@ -183,6 +383,101 @@ func TestLoadFileRejectsMissingRequiredFields(t *testing.T) {
 	}
 }
 
+func TestLoadFileRejectsInvalidS3Config(t *testing.T) {
+	tests := map[string]string{
+		"prefix traversal": `pipelines: [{id: reports, source: {backend: s3, endpoint: "https://s3.example.com", bucket: source, prefix: "../reports"}, destinations: [{id: archive, backend: local, path: /archive}]}]`,
+		"prefix backslash": `pipelines: [{id: reports, source: {backend: s3, endpoint: "https://s3.example.com", bucket: source, prefix: 'a\b'}, destinations: [{id: archive, backend: local, path: /archive}]}]`,
+		"partial creds":    `pipelines: [{id: reports, source: {backend: s3, endpoint: "https://s3.example.com", bucket: source, credentials: {access_key_id_env: ACCESS_KEY_ID}}, destinations: [{id: archive, backend: local, path: /archive}]}]`,
+	}
+	for name, body := range tests {
+		t.Run(name, func(t *testing.T) {
+			assertLoadError(t, body, "")
+		})
+	}
+}
+
+func TestLoadFileDefaultsSSHConfig(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: ssh-defaults
+    source:
+      backend: ssh
+      host: source.example.com
+      path: /source
+    destinations:
+      - id: archive
+        backend: ssh
+        host: destination.example.com
+        path: /archive
+        host_key_policy: false
+`)
+
+	source := cfg.Pipelines[0].Source
+	if source.Port != 22 {
+		t.Fatalf("source port = %d, want 22", source.Port)
+	}
+	if source.SSH.HostKeyPolicy != HostKeyPolicyAcceptNew {
+		t.Fatalf("source host key policy = %q, want accept-new", source.SSH.HostKeyPolicy)
+	}
+	destination := cfg.Pipelines[0].Destinations[0]
+	if destination.Port != 22 {
+		t.Fatalf("destination port = %d, want 22", destination.Port)
+	}
+	if destination.SSH.HostKeyPolicy != HostKeyPolicyOff {
+		t.Fatalf("destination host key policy = %q, want off", destination.SSH.HostKeyPolicy)
+	}
+}
+
+func TestLoadFileNormalizesSSHHostKeyPolicies(t *testing.T) {
+	tests := map[string]HostKeyPolicy{
+		`true`:         HostKeyPolicyStrict,
+		`"true"`:       HostKeyPolicyStrict,
+		`strict`:       HostKeyPolicyStrict,
+		`accept-new`:   HostKeyPolicyAcceptNew,
+		`false`:        HostKeyPolicyOff,
+		`"false"`:      HostKeyPolicyOff,
+		`off`:          HostKeyPolicyOff,
+		`"STRICT"`:     HostKeyPolicyStrict,
+		`"ACCEPT-NEW"`: HostKeyPolicyAcceptNew,
+		`"OFF"`:        HostKeyPolicyOff,
+	}
+	for value, want := range tests {
+		t.Run(value, func(t *testing.T) {
+			cfg := loadConfig(t, `
+pipelines:
+  - id: ssh-policy
+    source:
+      backend: ssh
+      host: source.example.com
+      path: /source
+      host_key_policy: `+value+`
+    destinations:
+      - id: archive
+        backend: local
+        path: /archive
+`)
+			if got := cfg.Pipelines[0].Source.SSH.HostKeyPolicy; got != want {
+				t.Fatalf("host key policy = %q, want %q", got, want)
+			}
+		})
+	}
+}
+
+func TestLoadFileRejectsLegacySSHURIFieldAsUnknown(t *testing.T) {
+	assertLoadError(t, `
+pipelines:
+  - id: reports
+    source:
+      backend: ssh
+      uri: ssh://reports@example.com:22
+      path: /source
+    destinations:
+      - id: archive
+        backend: local
+        path: /archive
+`, "field uri not found")
+}
+
 func TestLoadFileRejectsUnsupportedBackend(t *testing.T) {
 	assertLoadError(t, `
 pipelines:
@@ -261,12 +556,33 @@ pipelines:
 `, "field surprise not found")
 }
 
+func TestLoadFileRejectsUnknownSecretsFields(t *testing.T) {
+	assertLoadError(t, `
+secrets:
+  directory: /run/secrets/distributor
+  surprise: true
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: /source
+    destinations:
+      - id: archive
+        backend: local
+        path: /archive
+`, "field surprise not found")
+}
+
 func TestExampleConfigsLoad(t *testing.T) {
 	for _, path := range []string{
 		"../../examples/local-to-local.yml",
 		"../../examples/local-publish.yml",
 		"../../examples/local-html.yml",
+		"../../examples/local-index.yml",
 		"../../examples/fan-out.yml",
+		"../../examples/archive-and-latest.yml",
+		"../../examples/ssh-destination.yml",
+		"../../examples/s3-destination.yml",
 	} {
 		t.Run(path, func(t *testing.T) {
 			if _, err := LoadFile(path); err != nil {

internal/config/s3.go

@@ -0,0 +1,19 @@
+package config
+
+import (
+	"strings"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+)
+
+func NormalizeS3Prefix(prefix string) string {
+	return strings.Trim(prefix, "/")
+}
+
+func ValidateS3Prefix(prefix string) error {
+	return storage.ValidatePrefix(prefix)
+}
+
+func ForcePathStyle(value *bool) bool {
+	return value == nil || *value
+}

internal/config/secrets.go

@@ -0,0 +1,154 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+var secretNamePattern = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+
+type EnvLookup func(string) (string, bool)
+
+type Environment struct {
+	values map[string]string
+	lookup EnvLookup
+}
+
+type SecretConflict struct {
+	Name string
+}
+
+type SecretLoadResult struct {
+	Environment Environment
+	Conflicts   []SecretConflict
+}
+
+type ResolvedCredentials struct {
+	AccessKeyID     string
+	SecretAccessKey string
+}
+
+func ProcessEnvironment() Environment {
+	return NewEnvironment(nil, os.LookupEnv)
+}
+
+func NewEnvironment(values map[string]string, lookup EnvLookup) Environment {
+	copied := make(map[string]string, len(values))
+	for key, value := range values {
+		copied[key] = value
+	}
+	if lookup == nil {
+		lookup = os.LookupEnv
+	}
+	return Environment{values: copied, lookup: lookup}
+}
+
+func (e Environment) Lookup(name string) (string, bool) {
+	if e.lookup != nil {
+		if value, ok := e.lookup(name); ok {
+			return value, true
+		}
+	}
+	value, ok := e.values[name]
+	return value, ok
+}
+
+func (e Environment) ResolveCredentials(creds Credentials) (ResolvedCredentials, error) {
+	var resolved ResolvedCredentials
+	var err error
+	if creds.AccessKeyIDEnv != "" {
+		resolved.AccessKeyID, err = e.required(creds.AccessKeyIDEnv)
+		if err != nil {
+			return ResolvedCredentials{}, err
+		}
+	}
+	if creds.SecretAccessKeyEnv != "" {
+		resolved.SecretAccessKey, err = e.required(creds.SecretAccessKeyEnv)
+		if err != nil {
+			return ResolvedCredentials{}, err
+		}
+	}
+	return resolved, nil
+}
+
+func (e Environment) required(name string) (string, error) {
+	value, ok := e.Lookup(name)
+	if !ok {
+		return "", fmt.Errorf("credential environment variable %s is not set", name)
+	}
+	if value == "" {
+		return "", fmt.Errorf("credential environment variable %s is empty", name)
+	}
+	return value, nil
+}
+
+func LoadSecretEnvironment(directory string, lookup EnvLookup) (SecretLoadResult, error) {
+	if directory == "" {
+		return SecretLoadResult{Environment: NewEnvironment(nil, lookup)}, nil
+	}
+	values, err := loadSecretValues(directory)
+	if err != nil {
+		return SecretLoadResult{}, err
+	}
+	var conflicts []SecretConflict
+	for name, value := range values {
+		if processValue, ok := lookupValue(lookup, name); ok && processValue != value {
+			conflicts = append(conflicts, SecretConflict{Name: name})
+		}
+	}
+	sort.Slice(conflicts, func(i, j int) bool {
+		return conflicts[i].Name < conflicts[j].Name
+	})
+	return SecretLoadResult{
+		Environment: NewEnvironment(values, lookup),
+		Conflicts:   conflicts,
+	}, nil
+}
+
+func loadSecretValues(directory string) (map[string]string, error) {
+	entries, err := os.ReadDir(directory)
+	if err != nil {
+		return nil, fmt.Errorf("load secrets directory %q: %w", directory, err)
+	}
+	values := make(map[string]string)
+	for _, entry := range entries {
+		path := filepath.Join(directory, entry.Name())
+		info, err := os.Stat(path)
+		if err != nil {
+			return nil, fmt.Errorf("inspect secret file %q: %w", entry.Name(), err)
+		}
+		if info.IsDir() || !info.Mode().IsRegular() {
+			continue
+		}
+		if !secretNamePattern.MatchString(entry.Name()) {
+			return nil, fmt.Errorf("secret filename %q is invalid", entry.Name())
+		}
+		data, err := os.ReadFile(path)
+		if err != nil {
+			return nil, fmt.Errorf("read secret file %q: %w", entry.Name(), err)
+		}
+		values[entry.Name()] = trimOneTrailingLineEnding(string(data))
+	}
+	return values, nil
+}
+
+func trimOneTrailingLineEnding(value string) string {
+	if strings.HasSuffix(value, "\r\n") {
+		return strings.TrimSuffix(value, "\r\n")
+	}
+	if strings.HasSuffix(value, "\n") {
+		return strings.TrimSuffix(value, "\n")
+	}
+	return value
+}
+
+func lookupValue(lookup EnvLookup, name string) (string, bool) {
+	if lookup == nil {
+		lookup = os.LookupEnv
+	}
+	return lookup(name)
+}

internal/config/secrets_test.go

@@ -0,0 +1,248 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestLoadSecretEnvironmentLoadsValidFiles(t *testing.T) {
+	directory := t.TempDir()
+	writeSecret(t, directory, "API_KEY", "value\n")
+	writeSecret(t, directory, "CRLF", "value\r\n")
+	writeSecret(t, directory, "MULTILINE", "value\n\n")
+	writeSecret(t, directory, "SPACES", "  value  \n")
+	writeSecret(t, directory, "CARRIAGE", "value\r")
+
+	result, err := LoadSecretEnvironment(directory, emptyLookup)
+	if err != nil {
+		t.Fatalf("LoadSecretEnvironment() error = %v", err)
+	}
+	assertEnvValue(t, result.Environment, "API_KEY", "value")
+	assertEnvValue(t, result.Environment, "CRLF", "value")
+	assertEnvValue(t, result.Environment, "MULTILINE", "value\n")
+	assertEnvValue(t, result.Environment, "SPACES", "  value  ")
+	assertEnvValue(t, result.Environment, "CARRIAGE", "value\r")
+}
+
+func TestLoadSecretEnvironmentRejectsInvalidFilenames(t *testing.T) {
+	directory := t.TempDir()
+	secretValue := "do-not-print"
+	writeSecret(t, directory, "1INVALID", secretValue)
+
+	_, err := LoadSecretEnvironment(directory, emptyLookup)
+	if err == nil {
+		t.Fatal("LoadSecretEnvironment() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "secret filename") {
+		t.Fatalf("LoadSecretEnvironment() error = %q, want filename error", err)
+	}
+	if strings.Contains(err.Error(), secretValue) {
+		t.Fatalf("LoadSecretEnvironment() error exposed secret value: %q", err)
+	}
+}
+
+func TestLoadSecretEnvironmentIgnoresDirectoriesAndFollowsSymlinks(t *testing.T) {
+	directory := t.TempDir()
+	if err := os.Mkdir(filepath.Join(directory, "IGNORED_DIR"), 0o700); err != nil {
+		t.Fatalf("mkdir ignored dir: %v", err)
+	}
+	targetFile := filepath.Join(t.TempDir(), "target")
+	if err := os.WriteFile(targetFile, []byte("linked\n"), 0o600); err != nil {
+		t.Fatalf("write target file: %v", err)
+	}
+	if err := os.Symlink(targetFile, filepath.Join(directory, "LINKED_SECRET")); err != nil {
+		t.Fatalf("symlink file: %v", err)
+	}
+	targetDir := t.TempDir()
+	if err := os.Symlink(targetDir, filepath.Join(directory, "LINKED_DIR")); err != nil {
+		t.Fatalf("symlink dir: %v", err)
+	}
+
+	result, err := LoadSecretEnvironment(directory, emptyLookup)
+	if err != nil {
+		t.Fatalf("LoadSecretEnvironment() error = %v", err)
+	}
+	assertEnvValue(t, result.Environment, "LINKED_SECRET", "linked")
+	if _, ok := result.Environment.Lookup("IGNORED_DIR"); ok {
+		t.Fatal("directory appeared in environment")
+	}
+	if _, ok := result.Environment.Lookup("LINKED_DIR"); ok {
+		t.Fatal("directory symlink appeared in environment")
+	}
+}
+
+func TestLoadSecretEnvironmentMissingDirectoryFails(t *testing.T) {
+	missing := filepath.Join(t.TempDir(), "missing")
+	_, err := LoadSecretEnvironment(missing, emptyLookup)
+	if err == nil {
+		t.Fatal("LoadSecretEnvironment() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "load secrets directory") || !strings.Contains(err.Error(), missing) {
+		t.Fatalf("LoadSecretEnvironment() error = %q, want directory context", err)
+	}
+}
+
+func TestEnvironmentPrefersProcessValuesAndReportsDifferingConflicts(t *testing.T) {
+	directory := t.TempDir()
+	secretValue := "secret-value"
+	processValue := "process-value"
+	writeSecret(t, directory, "TOKEN", secretValue)
+
+	result, err := LoadSecretEnvironment(directory, mapLookup(map[string]string{"TOKEN": processValue}))
+	if err != nil {
+		t.Fatalf("LoadSecretEnvironment() error = %v", err)
+	}
+	assertEnvValue(t, result.Environment, "TOKEN", processValue)
+	if got, want := len(result.Conflicts), 1; got != want {
+		t.Fatalf("conflict count = %d, want %d", got, want)
+	}
+	if result.Conflicts[0].Name != "TOKEN" {
+		t.Fatalf("conflict name = %q, want TOKEN", result.Conflicts[0].Name)
+	}
+	if strings.Contains(result.Conflicts[0].Name, secretValue) || strings.Contains(result.Conflicts[0].Name, processValue) {
+		t.Fatalf("conflict exposed secret values: %#v", result.Conflicts[0])
+	}
+}
+
+func TestEnvironmentDoesNotWarnWhenProcessValueMatchesSecret(t *testing.T) {
+	directory := t.TempDir()
+	writeSecret(t, directory, "TOKEN", "same-value")
+
+	result, err := LoadSecretEnvironment(directory, mapLookup(map[string]string{"TOKEN": "same-value"}))
+	if err != nil {
+		t.Fatalf("LoadSecretEnvironment() error = %v", err)
+	}
+	if len(result.Conflicts) != 0 {
+		t.Fatalf("conflicts = %#v, want none", result.Conflicts)
+	}
+}
+
+func TestEnvironmentDoesNotMutateProcessEnvironment(t *testing.T) {
+	name := "DISTRIBUTOR_TEST_SECRET_ONLY"
+	t.Setenv(name, "")
+	if err := os.Unsetenv(name); err != nil {
+		t.Fatalf("unset env: %v", err)
+	}
+	directory := t.TempDir()
+	writeSecret(t, directory, name, "secret")
+
+	if _, err := LoadSecretEnvironment(directory, nil); err != nil {
+		t.Fatalf("LoadSecretEnvironment() error = %v", err)
+	}
+	if _, ok := os.LookupEnv(name); ok {
+		t.Fatalf("%s was added to process environment", name)
+	}
+}
+
+func TestResolveCredentialsUsesSecretsAwareEnvironment(t *testing.T) {
+	directory := t.TempDir()
+	writeSecret(t, directory, "ACCESS_KEY_ID", "secret-access")
+	writeSecret(t, directory, "SECRET_ACCESS_KEY", "secret-secret")
+	result, err := LoadSecretEnvironment(directory, emptyLookup)
+	if err != nil {
+		t.Fatalf("LoadSecretEnvironment() error = %v", err)
+	}
+
+	creds, err := result.Environment.ResolveCredentials(Credentials{
+		AccessKeyIDEnv:     "ACCESS_KEY_ID",
+		SecretAccessKeyEnv: "SECRET_ACCESS_KEY",
+	})
+	if err != nil {
+		t.Fatalf("ResolveCredentials() error = %v", err)
+	}
+	if creds.AccessKeyID != "secret-access" || creds.SecretAccessKey != "secret-secret" {
+		t.Fatalf("resolved credentials = %#v", creds)
+	}
+}
+
+func TestResolveCredentialsPrefersProcessEnvironment(t *testing.T) {
+	directory := t.TempDir()
+	writeSecret(t, directory, "ACCESS_KEY_ID", "secret-access")
+	result, err := LoadSecretEnvironment(directory, mapLookup(map[string]string{"ACCESS_KEY_ID": "process-access"}))
+	if err != nil {
+		t.Fatalf("LoadSecretEnvironment() error = %v", err)
+	}
+
+	creds, err := result.Environment.ResolveCredentials(Credentials{AccessKeyIDEnv: "ACCESS_KEY_ID"})
+	if err != nil {
+		t.Fatalf("ResolveCredentials() error = %v", err)
+	}
+	if creds.AccessKeyID != "process-access" {
+		t.Fatalf("access key = %q, want process-access", creds.AccessKeyID)
+	}
+}
+
+func TestResolveCredentialsDoesNotFeedProcessEnvironment(t *testing.T) {
+	name := "DISTRIBUTOR_TEST_SDK_CHAIN_VALUE"
+	t.Setenv(name, "")
+	if err := os.Unsetenv(name); err != nil {
+		t.Fatalf("unset env: %v", err)
+	}
+	directory := t.TempDir()
+	writeSecret(t, directory, name, "secret")
+
+	result, err := LoadSecretEnvironment(directory, nil)
+	if err != nil {
+		t.Fatalf("LoadSecretEnvironment() error = %v", err)
+	}
+	assertEnvValue(t, result.Environment, name, "secret")
+	if _, ok := os.LookupEnv(name); ok {
+		t.Fatalf("%s is visible to process environment", name)
+	}
+}
+
+func TestResolveCredentialsMissingReferenceFailsWithoutSecretValue(t *testing.T) {
+	env := NewEnvironment(map[string]string{"PRESENT": "do-not-print"}, emptyLookup)
+	_, err := env.ResolveCredentials(Credentials{AccessKeyIDEnv: "MISSING"})
+	if err == nil {
+		t.Fatal("ResolveCredentials() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "MISSING") {
+		t.Fatalf("ResolveCredentials() error = %q, want missing variable name", err)
+	}
+	if strings.Contains(err.Error(), "do-not-print") {
+		t.Fatalf("ResolveCredentials() error exposed secret value: %q", err)
+	}
+}
+
+func TestResolveCredentialsRejectsEmptyReferencedValue(t *testing.T) {
+	env := NewEnvironment(map[string]string{"EMPTY": ""}, emptyLookup)
+	_, err := env.ResolveCredentials(Credentials{AccessKeyIDEnv: "EMPTY"})
+	if err == nil {
+		t.Fatal("ResolveCredentials() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "EMPTY") || !strings.Contains(err.Error(), "empty") {
+		t.Fatalf("ResolveCredentials() error = %q, want empty variable context", err)
+	}
+}
+
+func writeSecret(t *testing.T, directory, name, value string) {
+	t.Helper()
+	if err := os.WriteFile(filepath.Join(directory, name), []byte(value), 0o600); err != nil {
+		t.Fatalf("write secret %s: %v", name, err)
+	}
+}
+
+func assertEnvValue(t *testing.T, env Environment, name, want string) {
+	t.Helper()
+	got, ok := env.Lookup(name)
+	if !ok {
+		t.Fatalf("Lookup(%q) ok = false", name)
+	}
+	if got != want {
+		t.Fatalf("Lookup(%q) = %q, want %q", name, got, want)
+	}
+}
+
+func emptyLookup(string) (string, bool) {
+	return "", false
+}
+
+func mapLookup(values map[string]string) EnvLookup {
+	return func(name string) (string, bool) {
+		value, ok := values[name]
+		return value, ok
+	}
+}

internal/config/ssh.go

@@ -0,0 +1,64 @@
+package config
+
+import (
+	"fmt"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+type HostKeyPolicy string
+
+const (
+	HostKeyPolicyStrict    HostKeyPolicy = "strict"
+	HostKeyPolicyAcceptNew HostKeyPolicy = "accept-new"
+	HostKeyPolicyOff       HostKeyPolicy = "off"
+)
+
+func (p *HostKeyPolicy) UnmarshalYAML(value *yaml.Node) error {
+	switch value.Kind {
+	case yaml.ScalarNode:
+	default:
+		return fmt.Errorf("host_key_policy must be a boolean or string")
+	}
+
+	switch value.Tag {
+	case "!!bool":
+		var enabled bool
+		if err := value.Decode(&enabled); err != nil {
+			return err
+		}
+		if enabled {
+			*p = HostKeyPolicyStrict
+		} else {
+			*p = HostKeyPolicyOff
+		}
+		return nil
+	case "!!str":
+		var raw string
+		if err := value.Decode(&raw); err != nil {
+			return err
+		}
+		normalized, ok := NormalizeHostKeyPolicy(raw)
+		if !ok {
+			return fmt.Errorf("host_key_policy must be strict, true, accept-new, off, or false")
+		}
+		*p = normalized
+		return nil
+	default:
+		return fmt.Errorf("host_key_policy must be a boolean or string")
+	}
+}
+
+func NormalizeHostKeyPolicy(value string) (HostKeyPolicy, bool) {
+	switch strings.ToLower(value) {
+	case "", string(HostKeyPolicyAcceptNew):
+		return HostKeyPolicyAcceptNew, true
+	case string(HostKeyPolicyStrict), "true":
+		return HostKeyPolicyStrict, true
+	case string(HostKeyPolicyOff), "false":
+		return HostKeyPolicyOff, true
+	default:
+		return "", false
+	}
+}

internal/config/validate.go

@@ -4,6 +4,8 @@ import (
 	"fmt"
 	"regexp"
 	"strings"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/link"
 )
 
 var idPattern = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`)
@@ -37,7 +39,7 @@ func Validate(cfg Config) error {
 			pipelineIDs[pipeline.ID] = struct{}{}
 		}
 
-		errs = validateBackend(errs, pipelineContext+".source", pipeline.Source.Backend, pipeline.Source.Path, pipeline.Source.URI, pipeline.Source.Endpoint, pipeline.Source.Bucket)
+		errs = validateSourceBackend(errs, pipelineContext+".source", pipeline.Source)
 		errs = validateValidationPolicy(errs, pipelineContext+".validation", pipeline.Validation)
 		if len(pipeline.Destinations) == 0 {
 			errs = append(errs, pipelineContext+".destinations is required")
@@ -56,8 +58,10 @@ func Validate(cfg Config) error {
 				destinationIDs[destination.ID] = struct{}{}
 			}
 
-			errs = validateBackend(errs, destinationContext, destination.Backend, destination.Path, destination.URI, destination.Endpoint, destination.Bucket)
+			errs = validateDestinationBackend(errs, destinationContext, destination)
 			errs = validatePublishTransformPolicy(errs, destinationContext, destination.Publish, destination.Transform)
+			errs = validatePathMapping(errs, destinationContext+".path_mapping", destination.PathMap)
+			errs = validateLinks(errs, destinationContext+".links", destination.Links)
 			errs = validateTransferPolicy(errs, destinationContext+".transfer", destination.Transfer)
 		}
 	}
@@ -68,7 +72,15 @@ func Validate(cfg Config) error {
 	return nil
 }
 
-func validateBackend(errs ValidationErrors, context, backend, path, uri, endpoint, bucket string) ValidationErrors {
+func validateSourceBackend(errs ValidationErrors, context string, backend Backend) ValidationErrors {
+	return validateBackend(errs, context, backend.Backend, backend.Host, backend.Port, backend.Path, backend.Endpoint, backend.Bucket, backend.Prefix, backend.SSH.HostKeyPolicy, backend.Creds)
+}
+
+func validateDestinationBackend(errs ValidationErrors, context string, destination Destination) ValidationErrors {
+	return validateBackend(errs, context, destination.Backend, destination.Host, destination.Port, destination.Path, destination.Endpoint, destination.Bucket, destination.Prefix, destination.SSH.HostKeyPolicy, destination.Creds)
+}
+
+func validateBackend(errs ValidationErrors, context, backend, host string, port int, path, endpoint, bucket, prefix string, hostKeyPolicy HostKeyPolicy, creds Credentials) ValidationErrors {
 	switch backend {
 	case "":
 		errs = append(errs, context+".backend is required")
@@ -77,12 +89,23 @@ func validateBackend(errs ValidationErrors, context, backend, path, uri, endpoin
 			errs = append(errs, context+".path is required for local backend")
 		}
 	case BackendSSH:
-		if uri == "" {
-			errs = append(errs, context+".uri is required for ssh backend")
+		if host == "" {
+			errs = append(errs, context+".host is required for ssh backend")
 		}
 		if path == "" {
 			errs = append(errs, context+".path is required for ssh backend")
 		}
+		if port < 0 || port > 65535 {
+			errs = append(errs, context+".port must be between 1 and 65535")
+		}
+		if port == 0 {
+			errs = append(errs, context+".port is required for ssh backend after defaults are applied")
+		}
+		if hostKeyPolicy != "" {
+			if _, ok := NormalizeHostKeyPolicy(string(hostKeyPolicy)); !ok {
+				errs = append(errs, context+".host_key_policy must be strict, true, accept-new, off, or false")
+			}
+		}
 	case BackendS3:
 		if endpoint == "" {
 			errs = append(errs, context+".endpoint is required for s3 backend")
@@ -90,6 +113,12 @@ func validateBackend(errs ValidationErrors, context, backend, path, uri, endpoin
 		if bucket == "" {
 			errs = append(errs, context+".bucket is required for s3 backend")
 		}
+		if err := ValidateS3Prefix(prefix); err != nil {
+			errs = append(errs, context+".prefix must be a clean relative slash-separated path")
+		}
+		if (creds.AccessKeyIDEnv == "") != (creds.SecretAccessKeyEnv == "") {
+			errs = append(errs, context+".credentials.access_key_id_env and credentials.secret_access_key_env must be configured together")
+		}
 	default:
 		errs = append(errs, context+".backend "+backend+" is unsupported")
 	}
@@ -124,21 +153,52 @@ func ValidatePublishTransformPolicy(publish PublishPolicy, transform Transform)
 	if transform.MarkdownToHTML == nil {
 		return nil
 	}
+	mode := transform.MarkdownToHTML.Mode
+	if mode == "" {
+		mode = TransformModeSidecar
+	}
+	if mode != TransformModeSidecar && mode != TransformModeIndex {
+		return fmt.Errorf("transform.markdown_to_html.mode must be %s or %s", TransformModeSidecar, TransformModeIndex)
+	}
+	if transform.MarkdownToHTML.Input != "" && !transform.MarkdownToHTML.Enabled {
+		return fmt.Errorf("transform.markdown_to_html.input requires transform.markdown_to_html.enabled to be true")
+	}
+	if transform.MarkdownToHTML.Input != "" && mode != TransformModeIndex {
+		return fmt.Errorf("transform.markdown_to_html.input is only valid when mode is %s", TransformModeIndex)
+	}
+	if transform.MarkdownToHTML.Enabled && !publish.HTML {
+		return fmt.Errorf("transform.markdown_to_html.enabled requires publish.html to be true")
+	}
 	if publish.HTML && !transform.MarkdownToHTML.Enabled {
 		return fmt.Errorf("transform.markdown_to_html.enabled must be true when publish.html is true")
 	}
-	if publish.HTML && transform.MarkdownToHTML.Mode != TransformModeSidecar {
-		return fmt.Errorf("transform.markdown_to_html.mode must be %s", TransformModeSidecar)
-	}
-	if transform.MarkdownToHTML.Enabled && transform.MarkdownToHTML.Mode != TransformModeSidecar {
-		return fmt.Errorf("transform.markdown_to_html.mode must be %s", TransformModeSidecar)
-	}
-	if !transform.MarkdownToHTML.Enabled && transform.MarkdownToHTML.Mode != "" && transform.MarkdownToHTML.Mode != TransformModeSidecar {
-		return fmt.Errorf("transform.markdown_to_html.mode must be %s", TransformModeSidecar)
-	}
 	return nil
 }
 
+func validatePathMapping(errs ValidationErrors, context string, mapping PathMapping) ValidationErrors {
+	if mapping.Mode != PathMappingPreserveRelative && mapping.Mode != PathMappingFixed {
+		errs = append(errs, context+".mode must be "+PathMappingPreserveRelative+" or "+PathMappingFixed)
+	}
+	return errs
+}
+
+func validateLinks(errs ValidationErrors, context string, links *Links) ValidationErrors {
+	if links == nil {
+		return errs
+	}
+	if links.BaseURL == "" {
+		errs = append(errs, context+".base_url is required")
+	} else if err := link.ValidateHTTPURL(links.BaseURL); err != nil {
+		errs = append(errs, context+".base_url "+err.Error())
+	}
+	switch links.Primary {
+	case LinkPrimaryAuto, LinkPrimaryHTML, LinkPrimarySource:
+	default:
+		errs = append(errs, context+".primary must be "+LinkPrimaryAuto+", "+LinkPrimaryHTML+", or "+LinkPrimarySource)
+	}
+	return errs
+}
+
 func validateTransferPolicy(errs ValidationErrors, context string, policy TransferPolicy) ValidationErrors {
 	if policy.OnDestinationSame != TransferActionSkip && policy.OnDestinationSame != TransferActionFail {
 		errs = append(errs, context+".on_destination_same must be skip or fail")
@@ -146,11 +206,11 @@ func validateTransferPolicy(errs ValidationErrors, context string, policy Transf
 	if policy.OnDestinationOlder != TransferActionReplace && policy.OnDestinationOlder != TransferActionFail {
 		errs = append(errs, context+".on_destination_older must be replace or fail")
 	}
-	if policy.OnDestinationNewer != TransferActionSkip && policy.OnDestinationNewer != TransferActionFail {
-		errs = append(errs, context+".on_destination_newer must be skip or fail")
+	if policy.OnDestinationNewer != TransferActionSkip && policy.OnDestinationNewer != TransferActionFail && policy.OnDestinationNewer != TransferActionReplace {
+		errs = append(errs, context+".on_destination_newer must be skip, replace, or fail")
 	}
-	if policy.OnConflict != TransferActionFail {
-		errs = append(errs, context+".on_conflict must be fail")
+	if policy.OnConflict != TransferActionFail && policy.OnConflict != TransferActionReplace {
+		errs = append(errs, context+".on_conflict must be fail or replace")
 	}
 	return errs
 }

internal/config/validate_test.go

@@ -1,6 +1,9 @@
 package config
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestValidatePublishTransformPolicy(t *testing.T) {
 	tests := publishTransformPolicyCases()
@@ -47,6 +50,126 @@ func TestValidateChecksPublishTransformPolicy(t *testing.T) {
 	}
 }
 
+func TestValidateAcceptsForceReplacementTransferActions(t *testing.T) {
+	cfg := Config{Pipelines: []Pipeline{{
+		ID: "reports",
+		Source: Backend{
+			Backend: BackendLocal,
+			Path:    "/source",
+		},
+		Destinations: []Destination{{
+			ID:      "archive",
+			Backend: BackendLocal,
+			Path:    "/destination",
+			Transfer: TransferPolicy{
+				OnDestinationNewer: TransferActionReplace,
+				OnConflict:         TransferActionReplace,
+			},
+		}},
+	}}}
+	ApplyDefaults(&cfg)
+	if err := Validate(cfg); err != nil {
+		t.Fatalf("Validate() error = %v", err)
+	}
+}
+
+func TestValidatePathMapping(t *testing.T) {
+	tests := []struct {
+		name    string
+		mode    string
+		wantErr bool
+	}{
+		{name: "preserve relative", mode: PathMappingPreserveRelative},
+		{name: "fixed", mode: PathMappingFixed},
+		{name: "invalid", mode: "archive", wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := Config{Pipelines: []Pipeline{{
+				ID:     "reports",
+				Source: Backend{Backend: BackendLocal, Path: "/source"},
+				Destinations: []Destination{{
+					ID:      "archive",
+					Backend: BackendLocal,
+					Path:    "/destination",
+					PathMap: PathMapping{Mode: tt.mode},
+				}},
+			}}}
+			ApplyDefaults(&cfg)
+			err := Validate(cfg)
+			if tt.wantErr && err == nil {
+				t.Fatal("Validate() error = nil, want error")
+			}
+			if !tt.wantErr && err != nil {
+				t.Fatalf("Validate() error = %v", err)
+			}
+		})
+	}
+}
+
+func TestValidateLinks(t *testing.T) {
+	tests := []struct {
+		name    string
+		links   *Links
+		wantErr bool
+	}{
+		{name: "absent links"},
+		{name: "http", links: &Links{BaseURL: "http://reports.example.com/archive", Primary: LinkPrimaryAuto}},
+		{name: "https", links: &Links{BaseURL: "https://reports.example.com/archive/", Primary: LinkPrimaryHTML}},
+		{name: "source primary", links: &Links{BaseURL: "https://reports.example.com", Primary: LinkPrimarySource}},
+		{name: "missing base", links: &Links{Primary: LinkPrimaryAuto}, wantErr: true},
+		{name: "ftp scheme", links: &Links{BaseURL: "ftp://reports.example.com", Primary: LinkPrimaryAuto}, wantErr: true},
+		{name: "missing host", links: &Links{BaseURL: "https:///archive", Primary: LinkPrimaryAuto}, wantErr: true},
+		{name: "query", links: &Links{BaseURL: "https://reports.example.com/archive?preview=1", Primary: LinkPrimaryAuto}, wantErr: true},
+		{name: "fragment", links: &Links{BaseURL: "https://reports.example.com/archive#top", Primary: LinkPrimaryAuto}, wantErr: true},
+		{name: "invalid primary", links: &Links{BaseURL: "https://reports.example.com", Primary: "document"}, wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := Config{Pipelines: []Pipeline{{
+				ID:     "reports",
+				Source: Backend{Backend: BackendLocal, Path: "/source"},
+				Destinations: []Destination{{
+					ID:      "web",
+					Backend: BackendLocal,
+					Path:    "/destination",
+					Links:   tt.links,
+				}},
+			}}}
+			ApplyDefaults(&cfg)
+			err := Validate(cfg)
+			if tt.wantErr && err == nil {
+				t.Fatal("Validate() error = nil, want error")
+			}
+			if !tt.wantErr && err != nil {
+				t.Fatalf("Validate() error = %v", err)
+			}
+		})
+	}
+}
+
+func TestValidateLinksReportsFieldContext(t *testing.T) {
+	cfg := Config{Pipelines: []Pipeline{{
+		ID:     "reports",
+		Source: Backend{Backend: BackendLocal, Path: "/source"},
+		Destinations: []Destination{{
+			ID:      "web",
+			Backend: BackendLocal,
+			Path:    "/destination",
+			Links:   &Links{BaseURL: "https://reports.example.com/archive?preview=1", Primary: LinkPrimaryAuto},
+		}},
+	}}}
+	ApplyDefaults(&cfg)
+	err := Validate(cfg)
+	if err == nil {
+		t.Fatal("Validate() error = nil, want error")
+	}
+	want := "pipelines[0].destinations[0].links.base_url must not include a query string"
+	if !strings.Contains(err.Error(), want) {
+		t.Fatalf("Validate() error = %q, want %q", err, want)
+	}
+}
+
 type publishTransformPolicyCase struct {
 	name      string
 	publish   PublishPolicy
@@ -68,6 +191,30 @@ func publishTransformPolicyCases() []publishTransformPolicyCase {
 				Mode:    TransformModeSidecar,
 			}},
 		},
+		{
+			name:    "html only default mode allowed",
+			publish: PublishPolicy{HTML: true},
+			transform: Transform{MarkdownToHTML: &MarkdownToHTML{
+				Enabled: true,
+			}},
+		},
+		{
+			name:    "html only index allowed",
+			publish: PublishPolicy{HTML: true},
+			transform: Transform{MarkdownToHTML: &MarkdownToHTML{
+				Enabled: true,
+				Mode:    TransformModeIndex,
+			}},
+		},
+		{
+			name:    "html only index input allowed",
+			publish: PublishPolicy{HTML: true},
+			transform: Transform{MarkdownToHTML: &MarkdownToHTML{
+				Enabled: true,
+				Mode:    TransformModeIndex,
+				Input:   "report.md",
+			}},
+		},
 		{
 			name:    "source and html sidecar allowed",
 			publish: PublishPolicy{Source: true, HTML: true},
@@ -104,6 +251,15 @@ func publishTransformPolicyCases() []publishTransformPolicyCase {
 			}},
 			wantErr: true,
 		},
+		{
+			name:    "source only enabled transform rejected",
+			publish: PublishPolicy{Source: true},
+			transform: Transform{MarkdownToHTML: &MarkdownToHTML{
+				Enabled: true,
+				Mode:    TransformModeSidecar,
+			}},
+			wantErr: true,
+		},
 		{
 			name:    "enabled markdown wrong mode rejected",
 			publish: PublishPolicy{Source: true},
@@ -113,6 +269,16 @@ func publishTransformPolicyCases() []publishTransformPolicyCase {
 			}},
 			wantErr: true,
 		},
+		{
+			name:    "sidecar input rejected",
+			publish: PublishPolicy{HTML: true},
+			transform: Transform{MarkdownToHTML: &MarkdownToHTML{
+				Enabled: true,
+				Mode:    TransformModeSidecar,
+				Input:   "report.md",
+			}},
+			wantErr: true,
+		},
 		{
 			name:    "disabled markdown empty mode allowed",
 			publish: PublishPolicy{Source: true},
@@ -128,6 +294,24 @@ func publishTransformPolicyCases() []publishTransformPolicyCase {
 				Mode:    TransformModeSidecar,
 			}},
 		},
+		{
+			name:    "disabled markdown index mode allowed",
+			publish: PublishPolicy{Source: true},
+			transform: Transform{MarkdownToHTML: &MarkdownToHTML{
+				Enabled: false,
+				Mode:    TransformModeIndex,
+			}},
+		},
+		{
+			name:    "disabled markdown input rejected",
+			publish: PublishPolicy{Source: true},
+			transform: Transform{MarkdownToHTML: &MarkdownToHTML{
+				Enabled: false,
+				Mode:    TransformModeIndex,
+				Input:   "report.md",
+			}},
+			wantErr: true,
+		},
 		{
 			name:    "disabled markdown wrong mode rejected",
 			publish: PublishPolicy{Source: true},

internal/link/url.go

@@ -0,0 +1,26 @@
+package link
+
+import (
+	"fmt"
+	"net/url"
+)
+
+func ValidateHTTPURL(value string) error {
+	parsed, err := url.Parse(value)
+	if err != nil {
+		return fmt.Errorf("must be a valid URL")
+	}
+	if parsed.Scheme != "http" && parsed.Scheme != "https" {
+		return fmt.Errorf("must use http or https")
+	}
+	if parsed.Host == "" {
+		return fmt.Errorf("must include a host")
+	}
+	if parsed.RawQuery != "" {
+		return fmt.Errorf("must not include a query string")
+	}
+	if parsed.Fragment != "" {
+		return fmt.Errorf("must not include a fragment")
+	}
+	return nil
+}

internal/link/url_test.go

@@ -0,0 +1,39 @@
+package link
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateHTTPURL(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   string
+		wantErr string
+	}{
+		{name: "http", value: "http://reports.example.com/archive"},
+		{name: "https", value: "https://reports.example.com/archive"},
+		{name: "missing host", value: "https:///archive", wantErr: "must include a host"},
+		{name: "unsupported scheme", value: "ftp://reports.example.com/archive", wantErr: "must use http or https"},
+		{name: "query string", value: "https://reports.example.com/archive?preview=1", wantErr: "must not include a query string"},
+		{name: "fragment", value: "https://reports.example.com/archive#top", wantErr: "must not include a fragment"},
+		{name: "parse failure", value: "http://[::1", wantErr: "must be a valid URL"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ValidateHTTPURL(tt.value)
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Fatalf("ValidateHTTPURL() error = %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatal("ValidateHTTPURL() error = nil, want error")
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("ValidateHTTPURL() error = %q, want %q", err, tt.wantErr)
+			}
+		})
+	}
+}

internal/publish/execute.go

@@ -14,7 +14,7 @@ func Execute(ctx context.Context, req Request, plan Plan) error {
 	switch plan.Action {
 	case ActionSkipSame, ActionSkipDestinationNewer:
 		return nil
-	case ActionPublishNew, ActionReplaceOlder:
+	case ActionPublishNew, ActionReplaceOlder, ActionForceReplace:
 	default:
 		return fmt.Errorf("cannot execute action %s: %s", plan.Action, plan.Reason)
 	}
@@ -23,7 +23,15 @@ func Execute(ctx context.Context, req Request, plan Plan) error {
 		if plan.ExistingState == nil {
 			return fmt.Errorf("replace requires existing destination state")
 		}
-		if err := req.DestinationBackend.DeleteManagedBundle(ctx, req.DestinationBundlePath, existingManagedOutputPaths(*plan.ExistingState), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true}); err != nil {
+		if err := req.DestinationBackend.DeleteManagedBundle(ctx, req.DestinationBundlePath, stateOutputManagedPaths(plan.ExistingState.Outputs), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true}); err != nil {
+			return err
+		}
+		if err := ensureDestinationEmpty(ctx, req.DestinationBackend, req.DestinationBundlePath); err != nil {
+			return err
+		}
+	}
+	if plan.Action == ActionForceReplace {
+		if err := req.DestinationBackend.DeletePrefix(ctx, req.DestinationBundlePath, storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true}); err != nil {
 			return err
 		}
 		if err := ensureDestinationEmpty(ctx, req.DestinationBackend, req.DestinationBundlePath); err != nil {
@@ -33,7 +41,7 @@ func Execute(ctx context.Context, req Request, plan Plan) error {
 
 	writtenOutputs := make([]Output, 0, len(plan.Outputs))
 	cleanup := func() {
-		_ = req.DestinationBackend.DeleteManagedBundle(ctx, req.DestinationBundlePath, managedOutputPaths(writtenOutputs), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true})
+		_ = req.DestinationBackend.DeleteManagedBundle(ctx, req.DestinationBundlePath, ManagedOutputPaths(writtenOutputs), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true})
 	}
 	for _, output := range plan.Outputs {
 		destinationPath, err := storage.Join(req.DestinationBundlePath, output.DestinationPath)
@@ -68,7 +76,10 @@ func Execute(ctx context.Context, req Request, plan Plan) error {
 		DestinationID:      req.DestinationID,
 		PublishedAt:        time.Now().UTC(),
 		Source:             state.SourceState{Manifest: req.SourceBundle.Manifest},
-		Outputs:            stateOutputs(plan.Outputs),
+		Outputs:            StateOutputFiles(plan.Outputs),
+	}
+	if plan.PrimaryURL != "" {
+		destinationState.Links = &state.LinkState{PrimaryURL: plan.PrimaryURL}
 	}
 	if err := state.Validate(destinationState); err != nil {
 		cleanup()
@@ -91,11 +102,3 @@ func Execute(ctx context.Context, req Request, plan Plan) error {
 	}
 	return nil
 }
-
-func existingManagedOutputPaths(destinationState state.DistributorState) []string {
-	paths := make([]string, 0, len(destinationState.Outputs))
-	for _, output := range destinationState.Outputs {
-		paths = append(paths, output.Path)
-	}
-	return paths
-}

internal/publish/force_test.go

@@ -0,0 +1,193 @@
+package publish
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
+	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
+)
+
+func TestBuildPlansForcedReplacementOnlyWhenExplicit(t *testing.T) {
+	tests := []struct {
+		name        string
+		prepare     func(t *testing.T, backend *fake.Backend, source bundle.Manifest)
+		transfer    config.TransferPolicy
+		wantReason  string
+		forceAction bool
+	}{
+		{
+			name: "unmanaged content",
+			prepare: func(t *testing.T, backend *fake.Backend, source bundle.Manifest) {
+				t.Helper()
+				testutil.WriteFakeFile(t, backend, "bundle/old.txt", "old")
+			},
+			transfer:    defaultTransfer(),
+			wantReason:  "fail_unmanaged",
+			forceAction: true,
+		},
+		{
+			name: "different source id",
+			prepare: func(t *testing.T, backend *fake.Backend, source bundle.Manifest) {
+				t.Helper()
+				conflict := source
+				conflict.ID = "other.source"
+				testutil.WriteFakeDestinationState(t, backend, "bundle", conflict, testutil.DestinationStateOptions{})
+			},
+			transfer:    conflictReplaceTransfer(),
+			wantReason:  "requires --force",
+			forceAction: true,
+		},
+		{
+			name: "same created digest conflict",
+			prepare: func(t *testing.T, backend *fake.Backend, source bundle.Manifest) {
+				t.Helper()
+				conflict := testutil.ValidManifest(testutil.BundleOptions{Files: []testutil.SourceFile{{Path: "report.md", Data: "# Different\n"}}})
+				testutil.WriteFakeDestinationState(t, backend, "bundle", conflict, testutil.DestinationStateOptions{})
+			},
+			transfer:    conflictReplaceTransfer(),
+			wantReason:  "requires --force",
+			forceAction: true,
+		},
+		{
+			name: "pipeline mismatch",
+			prepare: func(t *testing.T, backend *fake.Backend, source bundle.Manifest) {
+				t.Helper()
+				testutil.WriteFakeDestinationState(t, backend, "bundle", source, testutil.DestinationStateOptions{PipelineID: "other-pipeline"})
+			},
+			transfer:    conflictReplaceTransfer(),
+			wantReason:  "requires --force",
+			forceAction: true,
+		},
+		{
+			name: "destination mismatch",
+			prepare: func(t *testing.T, backend *fake.Backend, source bundle.Manifest) {
+				t.Helper()
+				testutil.WriteFakeDestinationState(t, backend, "bundle", source, testutil.DestinationStateOptions{DestinationID: "other-destination"})
+			},
+			transfer:    conflictReplaceTransfer(),
+			wantReason:  "requires --force",
+			forceAction: true,
+		},
+		{
+			name: "newer destination",
+			prepare: func(t *testing.T, backend *fake.Backend, source bundle.Manifest) {
+				t.Helper()
+				newer := source
+				newer.Created = newer.Created.AddDate(0, 0, 1)
+				testutil.WriteFakeDestinationState(t, backend, "bundle", newer, testutil.DestinationStateOptions{})
+			},
+			transfer:    newerReplaceTransfer(),
+			wantReason:  "requires --force",
+			forceAction: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			sourceBackend := fake.New()
+			sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{})
+			destinationBackend := fake.New()
+			tt.prepare(t, destinationBackend, sourceBundle.Manifest)
+
+			req := forceRequest(sourceBackend, destinationBackend, sourceBundle, tt.transfer)
+			_, err := Build(context.Background(), req)
+			if err == nil || !strings.Contains(err.Error(), tt.wantReason) {
+				t.Fatalf("Build() error = %v, want %q", err, tt.wantReason)
+			}
+
+			req.Force = true
+			plan, err := Build(context.Background(), req)
+			if tt.forceAction {
+				if err != nil {
+					t.Fatalf("Build() with force error = %v", err)
+				}
+				if plan.Action != ActionForceReplace || !plan.Force {
+					t.Fatalf("forced plan action = %s force=%t", plan.Action, plan.Force)
+				}
+			}
+		})
+	}
+}
+
+func TestBuildRequiresConflictPolicyForStateConflicts(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{})
+	destinationBackend := fake.New()
+	conflict := sourceBundle.Manifest
+	conflict.ID = "other.source"
+	testutil.WriteFakeDestinationState(t, destinationBackend, "bundle", conflict, testutil.DestinationStateOptions{})
+
+	req := forceRequest(sourceBackend, destinationBackend, sourceBundle, defaultTransfer())
+	req.Force = true
+	_, err := Build(context.Background(), req)
+	if err == nil || !strings.Contains(err.Error(), "destination source id differs") {
+		t.Fatalf("Build() error = %v, want conservative conflict", err)
+	}
+}
+
+func TestExecuteForcedReplacementDeletesOnlyBundlePath(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{})
+	destinationBackend := fake.New()
+	testutil.WriteFakeFile(t, destinationBackend, "bundle/old.txt", "old")
+	testutil.WriteFakeFile(t, destinationBackend, "bundle/nested/old.txt", "old")
+	testutil.WriteFakeFile(t, destinationBackend, "bundle-sibling/keep.txt", "keep")
+	testutil.WriteFakeFile(t, destinationBackend, "outside.txt", "outside")
+
+	req := forceRequest(sourceBackend, destinationBackend, sourceBundle, defaultTransfer())
+	req.Force = true
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if plan.Action != ActionForceReplace {
+		t.Fatalf("plan action = %s, want force_replace", plan.Action)
+	}
+	if err := Execute(context.Background(), req, plan); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	testutil.AssertFakeFile(t, destinationBackend, "bundle/report.md", "# Report\nSunny.\n")
+	testutil.AssertFakeMissing(t, destinationBackend, "bundle/old.txt")
+	testutil.AssertFakeMissing(t, destinationBackend, "bundle/nested/old.txt")
+	testutil.AssertFakeFile(t, destinationBackend, "bundle-sibling/keep.txt", "keep")
+	testutil.AssertFakeFile(t, destinationBackend, "outside.txt", "outside")
+}
+
+func forceRequest(sourceBackend, destinationBackend *fake.Backend, sourceBundle bundle.Bundle, transfer config.TransferPolicy) Request {
+	return Request{
+		PipelineID:            "reports",
+		DestinationID:         "archive",
+		SourceBundle:          sourceBundle,
+		SourceBackend:         sourceBackend,
+		DestinationBackend:    destinationBackend,
+		DestinationBundlePath: sourceBundle.RootRelativePath,
+		Publish:               config.PublishPolicy{Source: true},
+		Transfer:              transfer,
+		DistributorVersion:    "test",
+	}
+}
+
+func defaultTransfer() config.TransferPolicy {
+	return config.TransferPolicy{
+		OnDestinationSame:  config.TransferActionSkip,
+		OnDestinationOlder: config.TransferActionReplace,
+		OnDestinationNewer: config.TransferActionSkip,
+		OnConflict:         config.TransferActionFail,
+	}
+}
+
+func conflictReplaceTransfer() config.TransferPolicy {
+	transfer := defaultTransfer()
+	transfer.OnConflict = config.TransferActionReplace
+	return transfer
+}
+
+func newerReplaceTransfer() config.TransferPolicy {
+	transfer := defaultTransfer()
+	transfer.OnDestinationNewer = config.TransferActionReplace
+	return transfer
+}

internal/publish/links.go

@@ -0,0 +1,120 @@
+package publish
+
+import (
+	"fmt"
+	"net/url"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/link"
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
+)
+
+func PlanLinks(req Request, outputs []Output) ([]Output, string, error) {
+	if req.Links == nil {
+		return outputs, "", nil
+	}
+	if err := link.ValidateHTTPURL(req.Links.BaseURL); err != nil {
+		return nil, "", fmt.Errorf("link base URL: %w", err)
+	}
+	linked := make([]Output, 0, len(outputs))
+	for _, output := range outputs {
+		outputURL, err := OutputURL(req.Links.BaseURL, req.DestinationBundlePath, output.DestinationPath)
+		if err != nil {
+			return nil, "", err
+		}
+		output.URL = outputURL
+		linked = append(linked, output)
+	}
+	return linked, primaryURL(linked, req.Links.Primary), nil
+}
+
+func OutputURL(baseURL, destinationBundlePath, outputPath string) (string, error) {
+	parsed, err := url.Parse(baseURL)
+	if err != nil {
+		return "", fmt.Errorf("link base URL: %w", err)
+	}
+	segments := pathSegments(parsed.Path)
+	segments = append(segments, pathSegments(destinationBundlePath)...)
+	outputSegments := pathSegments(outputPath)
+	trailingSlash := false
+	if len(outputSegments) > 0 && outputSegments[len(outputSegments)-1] == "index.html" {
+		outputSegments = outputSegments[:len(outputSegments)-1]
+		trailingSlash = true
+	}
+	segments = append(segments, outputSegments...)
+	parsed.Path = urlPath(segments, trailingSlash)
+	parsed.RawPath = ""
+	return parsed.String(), nil
+}
+
+func pathSegments(value string) []string {
+	trimmed := strings.Trim(value, "/")
+	if trimmed == "" {
+		return nil
+	}
+	return strings.Split(trimmed, "/")
+}
+
+func urlPath(segments []string, trailingSlash bool) string {
+	if len(segments) == 0 {
+		return "/"
+	}
+	path := "/" + strings.Join(segments, "/")
+	if trailingSlash && !strings.HasSuffix(path, "/") {
+		path += "/"
+	}
+	return path
+}
+
+func primaryURL(outputs []Output, policy string) string {
+	switch policy {
+	case config.LinkPrimaryHTML:
+		return firstGeneratedHTMLURL(outputs)
+	case config.LinkPrimarySource:
+		return firstSourceURL(outputs)
+	default:
+		if url := firstIndexURL(outputs); url != "" {
+			return url
+		}
+		if url := firstGeneratedHTMLURL(outputs); url != "" {
+			return url
+		}
+		return firstSourceURL(outputs)
+	}
+}
+
+func firstIndexURL(outputs []Output) string {
+	for _, output := range outputs {
+		if isIndexOutput(output.DestinationPath) {
+			return output.URL
+		}
+	}
+	return ""
+}
+
+func firstGeneratedHTMLURL(outputs []Output) string {
+	for _, output := range outputs {
+		if output.Kind == state.OutputKindGenerated && isHTMLOutput(output.DestinationPath) {
+			return output.URL
+		}
+	}
+	return ""
+}
+
+func firstSourceURL(outputs []Output) string {
+	for _, output := range outputs {
+		if output.Kind == state.OutputKindSource {
+			return output.URL
+		}
+	}
+	return ""
+}
+
+func isIndexOutput(path string) bool {
+	return path == "index.html" || strings.HasSuffix(path, "/index.html")
+}
+
+func isHTMLOutput(path string) bool {
+	return strings.HasSuffix(path, ".html")
+}

internal/publish/links_test.go

@@ -0,0 +1,169 @@
+package publish
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
+)
+
+func TestOutputURLUsesURLPathSemantics(t *testing.T) {
+	tests := []struct {
+		name                  string
+		baseURL               string
+		destinationBundlePath string
+		outputPath            string
+		want                  string
+	}{
+		{
+			name:                  "nested non index",
+			baseURL:               "https://reports.example.com/archive",
+			destinationBundlePath: "daily/brentwood",
+			outputPath:            "report.html",
+			want:                  "https://reports.example.com/archive/daily/brentwood/report.html",
+		},
+		{
+			name:                  "nested index",
+			baseURL:               "https://reports.example.com/archive",
+			destinationBundlePath: "daily/brentwood",
+			outputPath:            "index.html",
+			want:                  "https://reports.example.com/archive/daily/brentwood/",
+		},
+		{
+			name:                  "fixed index",
+			baseURL:               "https://reports.example.com/latest",
+			destinationBundlePath: "",
+			outputPath:            "index.html",
+			want:                  "https://reports.example.com/latest/",
+		},
+		{
+			name:                  "escaped segments",
+			baseURL:               "https://reports.example.com/archive root",
+			destinationBundlePath: "daily reports",
+			outputPath:            "morning report.html",
+			want:                  "https://reports.example.com/archive%20root/daily%20reports/morning%20report.html",
+		},
+		{
+			name:                  "nested output index",
+			baseURL:               "https://reports.example.com",
+			destinationBundlePath: "daily",
+			outputPath:            "site/index.html",
+			want:                  "https://reports.example.com/daily/site/",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := OutputURL(tt.baseURL, tt.destinationBundlePath, tt.outputPath)
+			if err != nil {
+				t.Fatalf("OutputURL() error = %v", err)
+			}
+			if got != tt.want {
+				t.Fatalf("OutputURL() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestPlanLinksSelectsPrimaryURL(t *testing.T) {
+	outputs := []Output{
+		{
+			DestinationPath: "report.md",
+			Kind:            state.OutputKindSource,
+		},
+		{
+			DestinationPath: "report.html",
+			Kind:            state.OutputKindGenerated,
+		},
+		{
+			DestinationPath: "index.html",
+			Kind:            state.OutputKindGenerated,
+		},
+	}
+	tests := []struct {
+		name    string
+		primary string
+		want    string
+	}{
+		{name: "auto prefers index", primary: config.LinkPrimaryAuto, want: "https://reports.example.com/daily/"},
+		{name: "html uses first generated html", primary: config.LinkPrimaryHTML, want: "https://reports.example.com/daily/report.html"},
+		{name: "source uses first source", primary: config.LinkPrimarySource, want: "https://reports.example.com/daily/report.md"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			linked, primaryURL, err := PlanLinks(Request{
+				DestinationBundlePath: "daily",
+				Links: &config.Links{
+					BaseURL: "https://reports.example.com",
+					Primary: tt.primary,
+				},
+			}, outputs)
+			if err != nil {
+				t.Fatalf("PlanLinks() error = %v", err)
+			}
+			if primaryURL != tt.want {
+				t.Fatalf("primary URL = %q, want %q", primaryURL, tt.want)
+			}
+			for index, output := range linked {
+				if output.URL == "" {
+					t.Fatalf("linked output %d has empty URL", index)
+				}
+			}
+		})
+	}
+}
+
+func TestPlanLinksReturnsNoPrimaryWhenPolicyHasNoMatch(t *testing.T) {
+	linked, primaryURL, err := PlanLinks(Request{
+		DestinationBundlePath: "daily",
+		Links: &config.Links{
+			BaseURL: "https://reports.example.com",
+			Primary: config.LinkPrimaryHTML,
+		},
+	}, []Output{{
+		DestinationPath: "report.md",
+		Kind:            state.OutputKindSource,
+	}})
+	if err != nil {
+		t.Fatalf("PlanLinks() error = %v", err)
+	}
+	if primaryURL != "" {
+		t.Fatalf("primary URL = %q, want empty", primaryURL)
+	}
+	if linked[0].URL != "https://reports.example.com/daily/report.md" {
+		t.Fatalf("linked URL = %q", linked[0].URL)
+	}
+}
+
+func TestPlanLinksLeavesOutputsUnchangedWithoutConfig(t *testing.T) {
+	outputs := []Output{{DestinationPath: "report.md", Kind: state.OutputKindSource}}
+	linked, primaryURL, err := PlanLinks(Request{}, outputs)
+	if err != nil {
+		t.Fatalf("PlanLinks() error = %v", err)
+	}
+	if primaryURL != "" {
+		t.Fatalf("primary URL = %q, want empty", primaryURL)
+	}
+	if linked[0].URL != "" {
+		t.Fatalf("output URL = %q, want empty", linked[0].URL)
+	}
+}
+
+func TestPlanLinksValidatesBaseURLBeforePlanning(t *testing.T) {
+	_, _, err := PlanLinks(Request{
+		DestinationBundlePath: "daily",
+		Links: &config.Links{
+			BaseURL: "https://reports.example.com/archive?preview=1",
+			Primary: config.LinkPrimaryAuto,
+		},
+	}, []Output{{
+		DestinationPath: "report.md",
+		Kind:            state.OutputKindSource,
+	}})
+	if err == nil {
+		t.Fatal("PlanLinks() error = nil, want error")
+	}
+	if !strings.Contains(err.Error(), "link base URL: must not include a query string") {
+		t.Fatalf("PlanLinks() error = %q, want link base URL context", err)
+	}
+}

internal/publish/output.go

@@ -26,6 +26,10 @@ func PlanOutputs(ctx context.Context, req Request) ([]Output, error) {
 		generatedOutputs, err := transformer.Generate(ctx, transform.Request{
 			SourceBundle:  req.SourceBundle,
 			SourceBackend: req.SourceBackend,
+			Markdown: transform.MarkdownOptions{
+				Mode:  req.Transform.MarkdownToHTML.Mode,
+				Input: req.Transform.MarkdownToHTML.Input,
+			},
 		})
 		if err != nil {
 			return nil, err
@@ -93,25 +97,42 @@ func rejectOutputCollisions(outputs []Output) error {
 	return nil
 }
 
-func stateOutputs(outputs []Output) []state.OutputFile {
+func (o Output) StateOutputFile() state.OutputFile {
+	return state.OutputFile{
+		Path:       o.DestinationPath,
+		Kind:       o.Kind,
+		SourcePath: o.SourcePath,
+		Transform:  o.Transform,
+		URL:        o.URL,
+		SHA256:     o.SHA256,
+		Size:       o.Size,
+	}
+}
+
+func (o Output) ManagedPath() string {
+	return o.DestinationPath
+}
+
+func StateOutputFiles(outputs []Output) []state.OutputFile {
 	files := make([]state.OutputFile, 0, len(outputs))
 	for _, output := range outputs {
-		files = append(files, state.OutputFile{
-			Path:       output.DestinationPath,
-			Kind:       output.Kind,
-			SourcePath: output.SourcePath,
-			Transform:  output.Transform,
-			SHA256:     output.SHA256,
-			Size:       output.Size,
-		})
+		files = append(files, output.StateOutputFile())
 	}
 	return files
 }
 
-func managedOutputPaths(outputs []Output) []string {
+func ManagedOutputPaths(outputs []Output) []string {
 	paths := make([]string, 0, len(outputs))
 	for _, output := range outputs {
-		paths = append(paths, output.DestinationPath)
+		paths = append(paths, output.ManagedPath())
+	}
+	return paths
+}
+
+func stateOutputManagedPaths(outputs []state.OutputFile) []string {
+	paths := make([]string, 0, len(outputs))
+	for _, output := range outputs {
+		paths = append(paths, output.Path)
 	}
 	return paths
 }

internal/publish/output_test.go

@@ -6,11 +6,58 @@ import (
 
 	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
 	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
 	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
 	"gitea.maximumdirect.net/eric/distributor/internal/transform"
 )
 
+func TestOutputStateProjection(t *testing.T) {
+	sourceOutput := Output{
+		SourcePath:      "report.md",
+		DestinationPath: "report.md",
+		Kind:            state.OutputKindSource,
+		URL:             "https://reports.example.com/report.md",
+		SHA256:          "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+		Size:            123,
+	}
+	sourceState := sourceOutput.StateOutputFile()
+	if sourceState.Path != "report.md" || sourceState.Kind != state.OutputKindSource || sourceState.SourcePath != "report.md" || sourceState.URL != sourceOutput.URL || sourceState.SHA256 != sourceOutput.SHA256 || sourceState.Size != sourceOutput.Size {
+		t.Fatalf("source state output = %#v", sourceState)
+	}
+
+	generatedOutput := Output{
+		SourcePath:      "report.md",
+		DestinationPath: "report.html",
+		Kind:            state.OutputKindGenerated,
+		Transform:       transform.MarkdownToHTML,
+		URL:             "https://reports.example.com/report.html",
+		SHA256:          "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+		Size:            456,
+	}
+	generatedState := generatedOutput.StateOutputFile()
+	if generatedState.Path != "report.html" || generatedState.Kind != state.OutputKindGenerated || generatedState.SourcePath != "report.md" || generatedState.Transform != transform.MarkdownToHTML || generatedState.URL != generatedOutput.URL || generatedState.SHA256 != generatedOutput.SHA256 || generatedState.Size != generatedOutput.Size {
+		t.Fatalf("generated state output = %#v", generatedState)
+	}
+}
+
+func TestOutputSliceProjections(t *testing.T) {
+	outputs := []Output{
+		{SourcePath: "report.md", DestinationPath: "report.md", Kind: state.OutputKindSource, SHA256: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Size: 1},
+		{SourcePath: "report.md", DestinationPath: "report.html", Kind: state.OutputKindGenerated, Transform: transform.MarkdownToHTML, URL: "https://reports.example.com/report.html", SHA256: "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", Size: 2},
+	}
+
+	stateOutputs := StateOutputFiles(outputs)
+	if len(stateOutputs) != 2 || stateOutputs[1].Path != "report.html" || stateOutputs[1].Transform != transform.MarkdownToHTML || stateOutputs[1].URL != outputs[1].URL {
+		t.Fatalf("state outputs = %#v", stateOutputs)
+	}
+
+	paths := ManagedOutputPaths(outputs)
+	if len(paths) != 2 || paths[0] != "report.md" || paths[1] != "report.html" {
+		t.Fatalf("managed paths = %#v", paths)
+	}
+}
+
 func TestPlanOutputsRejectsCollision(t *testing.T) {
 	sourceBackend := fake.New()
 	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "", testutil.BundleOptions{
@@ -103,6 +150,35 @@ func TestPlanOutputsUsesRegisteredTransformer(t *testing.T) {
 	}
 }
 
+func TestPlanOutputsPassesMarkdownOptions(t *testing.T) {
+	data := []byte("<p>Generated</p>\n")
+	transformer := &recordingTransformer{outputs: []transform.Output{{
+		Path:       "index.html",
+		SourcePath: "report.md",
+		Transform:  transform.MarkdownToHTML,
+		Data:       data,
+		SHA256:     bundle.FileDigest(data),
+		Size:       int64(len(data)),
+	}}}
+
+	_, err := PlanOutputs(context.Background(), Request{
+		Publish: config.PublishPolicy{HTML: true},
+		Transform: config.Transform{MarkdownToHTML: &config.MarkdownToHTML{
+			Enabled: true,
+			Mode:    config.TransformModeIndex,
+			Input:   "report.md",
+		}},
+		Transformers: testResolver{transform.MarkdownToHTML: transformer},
+	})
+
+	if err != nil {
+		t.Fatalf("PlanOutputs() error = %v", err)
+	}
+	if transformer.request.Markdown.Mode != config.TransformModeIndex || transformer.request.Markdown.Input != "report.md" {
+		t.Fatalf("markdown options = %#v, want index/report.md", transformer.request.Markdown)
+	}
+}
+
 func TestBuildRejectsHTMLWithoutTransform(t *testing.T) {
 	sourceBackend := fake.New()
 	destinationBackend := fake.New()
@@ -148,6 +224,14 @@ func TestValidateRequestChecksPublishTransformPolicy(t *testing.T) {
 				Mode:    config.TransformModeSidecar,
 			}},
 		},
+		{
+			name:    "html only index allowed",
+			publish: config.PublishPolicy{HTML: true},
+			transform: config.Transform{MarkdownToHTML: &config.MarkdownToHTML{
+				Enabled: true,
+				Mode:    config.TransformModeIndex,
+			}},
+		},
 		{
 			name:    "source and html sidecar allowed",
 			publish: config.PublishPolicy{Source: true, HTML: true},
@@ -184,6 +268,15 @@ func TestValidateRequestChecksPublishTransformPolicy(t *testing.T) {
 			}},
 			wantErr: true,
 		},
+		{
+			name:    "source only enabled transform rejected",
+			publish: config.PublishPolicy{Source: true},
+			transform: config.Transform{MarkdownToHTML: &config.MarkdownToHTML{
+				Enabled: true,
+				Mode:    config.TransformModeSidecar,
+			}},
+			wantErr: true,
+		},
 		{
 			name:    "enabled markdown wrong mode rejected",
 			publish: config.PublishPolicy{Source: true},
@@ -253,3 +346,14 @@ type testTransformer struct {
 func (t testTransformer) Generate(context.Context, transform.Request) ([]transform.Output, error) {
 	return t.outputs, t.err
 }
+
+type recordingTransformer struct {
+	outputs []transform.Output
+	request transform.Request
+	err     error
+}
+
+func (t *recordingTransformer) Generate(_ context.Context, req transform.Request) ([]transform.Output, error) {
+	t.request = req
+	return t.outputs, t.err
+}

internal/publish/plan.go

@@ -20,6 +20,7 @@ const (
 	ActionSkipDestinationNewer Action = "skip_destination_newer"
 	ActionFailConflict         Action = "fail_conflict"
 	ActionFailUnmanaged        Action = "fail_unmanaged"
+	ActionForceReplace         Action = "force_replace"
 )
 
 type Request struct {
@@ -29,11 +30,14 @@ type Request struct {
 	SourceBackend         storage.Backend
 	DestinationBackend    storage.Backend
 	DestinationBundlePath string
+	PathMapping           string
 	Publish               config.PublishPolicy
 	Transform             config.Transform
+	Links                 *config.Links
 	Transformers          TransformerResolver
 	Transfer              config.TransferPolicy
 	DistributorVersion    string
+	Force                 bool
 }
 
 type TransformerResolver interface {
@@ -46,8 +50,11 @@ type Plan struct {
 	BundleID              string
 	BundlePath            string
 	DestinationBundlePath string
+	PathMapping           string
 	Action                Action
 	Reason                string
+	Force                 bool
+	PrimaryURL            string
 	Outputs               []Output
 	ExistingState         *state.DistributorState
 }
@@ -57,6 +64,7 @@ type Output struct {
 	DestinationPath string
 	Kind            string
 	Transform       string
+	URL             string
 	Data            []byte
 	SHA256          string
 	Size            int64
@@ -70,20 +78,27 @@ func Build(ctx context.Context, req Request) (Plan, error) {
 	if err != nil {
 		return Plan{}, err
 	}
+	outputs, primaryURL, err := PlanLinks(req, outputs)
+	if err != nil {
+		return Plan{}, err
+	}
 	status, err := inspectDestination(ctx, req.DestinationBackend, req.DestinationBundlePath)
 	if err != nil {
 		return Plan{}, err
 	}
-	comparison := state.Compare(req.SourceBundle.Manifest, req.PipelineID, req.DestinationID, status)
-	action, reason := actionForComparison(comparison, req.Transfer)
+	comparison := compareDestination(req, status)
+	action, reason := actionForComparison(comparison, req.Transfer, req.Force)
 	plan := Plan{
 		PipelineID:            req.PipelineID,
 		DestinationID:         req.DestinationID,
 		BundleID:              req.SourceBundle.Manifest.ID,
 		BundlePath:            req.SourceBundle.RootRelativePath,
 		DestinationBundlePath: req.DestinationBundlePath,
+		PathMapping:           req.PathMapping,
 		Action:                action,
 		Reason:                reason,
+		Force:                 action == ActionForceReplace,
+		PrimaryURL:            primaryURL,
 		Outputs:               outputs,
 		ExistingState:         status.State,
 	}
@@ -112,13 +127,39 @@ func validateRequest(req Request) error {
 	return nil
 }
 
-func actionForComparison(comparison state.Comparison, transfer config.TransferPolicy) (Action, string) {
+func compareDestination(req Request, status state.DestinationStatus) state.Comparison {
+	comparison := state.Compare(req.SourceBundle.Manifest, req.PipelineID, req.DestinationID, status)
+	if req.PathMapping != config.PathMappingFixed || comparison.Outcome != state.OutcomeDifferentSourceConflict || status.State == nil {
+		return comparison
+	}
+	destinationManifest := status.State.Source.Manifest
+	if destinationManifest.Created.Before(req.SourceBundle.Manifest.Created) {
+		return state.Comparison{Outcome: state.OutcomeDestinationOlder, Reason: "fixed destination source is older than selected source"}
+	}
+	if destinationManifest.Created.After(req.SourceBundle.Manifest.Created) {
+		return state.Comparison{Outcome: state.OutcomeDestinationNewer, Reason: "fixed destination source is newer than selected source"}
+	}
+	return comparison
+}
+
+func actionForComparison(comparison state.Comparison, transfer config.TransferPolicy, force bool) (Action, string) {
 	switch comparison.Outcome {
 	case state.OutcomeDestinationAbsent:
 		return ActionPublishNew, comparison.Reason
 	case state.OutcomeDestinationUnmanaged:
+		if force {
+			return ActionForceReplace, "forced replacement of unmanaged destination content"
+		}
 		return ActionFailUnmanaged, comparison.Reason
-	case state.OutcomeInvalidState, state.OutcomeIdentityMismatch, state.OutcomeSameCreatedConflict, state.OutcomeDifferentSourceConflict:
+	case state.OutcomeInvalidState:
+		return ActionFailConflict, comparison.Reason
+	case state.OutcomeIdentityMismatch, state.OutcomeSameCreatedConflict, state.OutcomeDifferentSourceConflict:
+		if transfer.OnConflict == config.TransferActionReplace {
+			if force {
+				return ActionForceReplace, "forced replacement of conflicting destination state: " + comparison.Reason
+			}
+			return ActionFailConflict, "destination conflict replacement requires --force"
+		}
 		return ActionFailConflict, comparison.Reason
 	case state.OutcomeSameSource:
 		if transfer.OnDestinationSame == config.TransferActionFail {
@@ -131,6 +172,12 @@ func actionForComparison(comparison state.Comparison, transfer config.TransferPo
 		}
 		return ActionReplaceOlder, comparison.Reason
 	case state.OutcomeDestinationNewer:
+		if transfer.OnDestinationNewer == config.TransferActionReplace {
+			if force {
+				return ActionForceReplace, "forced replacement of newer destination state"
+			}
+			return ActionFailConflict, "destination is newer and replacement requires --force"
+		}
 		if transfer.OnDestinationNewer == config.TransferActionFail {
 			return ActionFailConflict, "destination is newer and transfer policy requires failure"
 		}

internal/state/distributor.go

@@ -19,6 +19,7 @@ type DistributorState struct {
 	DestinationID      string
 	PublishedAt        time.Time
 	Source             SourceState
+	Links              *LinkState
 	Outputs            []OutputFile
 }
 
@@ -26,11 +27,16 @@ type SourceState struct {
 	Manifest bundle.Manifest
 }
 
+type LinkState struct {
+	PrimaryURL string
+}
+
 type OutputFile struct {
 	Path       string
 	Kind       string
 	SourcePath string
 	Transform  string
+	URL        string
 	SHA256     string
 	Size       int64
 }
@@ -42,6 +48,7 @@ type rawDistributorState struct {
 	DestinationID      *string         `json:"destination_id"`
 	PublishedAt        *string         `json:"published_at"`
 	Source             *rawSourceState `json:"source"`
+	Links              *rawLinkState   `json:"links"`
 	Outputs            []rawOutputFile `json:"outputs"`
 }
 
@@ -49,11 +56,16 @@ type rawSourceState struct {
 	Manifest json.RawMessage `json:"manifest"`
 }
 
+type rawLinkState struct {
+	PrimaryURL string `json:"primary_url"`
+}
+
 type rawOutputFile struct {
 	Path       *string `json:"path"`
 	Kind       *string `json:"kind"`
 	SourcePath *string `json:"source_path"`
 	Transform  string  `json:"transform"`
+	URL        string  `json:"url"`
 	SHA256     *string `json:"sha256"`
 	Size       *int64  `json:"size"`
 }
@@ -112,6 +124,9 @@ func parseRaw(raw rawDistributorState) (DistributorState, error) {
 		return DistributorState{}, fmt.Errorf("state source.manifest: %w", err)
 	}
 	state.Source.Manifest = manifest
+	if raw.Links != nil {
+		state.Links = &LinkState{PrimaryURL: raw.Links.PrimaryURL}
+	}
 	if raw.Outputs == nil {
 		return DistributorState{}, fmt.Errorf("state outputs is required")
 	}
@@ -161,6 +176,7 @@ func parseOutput(index int, raw rawOutputFile) (OutputFile, error) {
 		Kind:       *raw.Kind,
 		SourcePath: *raw.SourcePath,
 		Transform:  raw.Transform,
+		URL:        raw.URL,
 		SHA256:     *raw.SHA256,
 		Size:       *raw.Size,
 	}, nil
@@ -181,6 +197,7 @@ func (s DistributorState) MarshalJSON() ([]byte, error) {
 		DestinationID      string       `json:"destination_id"`
 		PublishedAt        string       `json:"published_at"`
 		Source             sourceJSON   `json:"source"`
+		Links              *LinkState   `json:"links,omitempty"`
 		Outputs            []OutputFile `json:"outputs"`
 	}
 	return json.Marshal(stateJSON{
@@ -190,16 +207,25 @@ func (s DistributorState) MarshalJSON() ([]byte, error) {
 		DestinationID:      s.DestinationID,
 		PublishedAt:        s.PublishedAtString(),
 		Source:             sourceJSON{Manifest: s.Source.Manifest},
+		Links:              s.Links,
 		Outputs:            s.Outputs,
 	})
 }
 
+func (l LinkState) MarshalJSON() ([]byte, error) {
+	type linkJSON struct {
+		PrimaryURL string `json:"primary_url,omitempty"`
+	}
+	return json.Marshal(linkJSON{PrimaryURL: l.PrimaryURL})
+}
+
 func (o OutputFile) MarshalJSON() ([]byte, error) {
 	type outputJSON struct {
 		Path       string `json:"path"`
 		Kind       string `json:"kind"`
 		SourcePath string `json:"source_path"`
 		Transform  string `json:"transform,omitempty"`
+		URL        string `json:"url,omitempty"`
 		SHA256     string `json:"sha256"`
 		Size       int64  `json:"size"`
 	}
@@ -208,6 +234,7 @@ func (o OutputFile) MarshalJSON() ([]byte, error) {
 		Kind:       o.Kind,
 		SourcePath: o.SourcePath,
 		Transform:  o.Transform,
+		URL:        o.URL,
 		SHA256:     o.SHA256,
 		Size:       o.Size,
 	})

internal/state/distributor_test.go

@@ -29,6 +29,22 @@ func TestParseValidState(t *testing.T) {
 	}
 }
 
+func TestParseValidStateWithLinks(t *testing.T) {
+	body := strings.Replace(validStateJSON(t), `"outputs": [`, `"links": {"primary_url": "https://reports.example.com/archive/report.md"},`+"\n  "+`"outputs": [`, 1)
+	body = strings.Replace(body, `"source_path": "report.md",`, `"source_path": "report.md",`+"\n      "+`"url": "https://reports.example.com/archive/report.md",`, 1)
+
+	state, err := Parse([]byte(body))
+	if err != nil {
+		t.Fatalf("Parse() error = %v", err)
+	}
+	if state.Links == nil || state.Links.PrimaryURL != "https://reports.example.com/archive/report.md" {
+		t.Fatalf("links = %#v, want primary URL", state.Links)
+	}
+	if state.Outputs[0].URL != "https://reports.example.com/archive/report.md" {
+		t.Fatalf("output URL = %q", state.Outputs[0].URL)
+	}
+}
+
 func TestParseNormalizesPublishedAtOffset(t *testing.T) {
 	body := strings.Replace(validStateJSON(t), `"published_at": "2026-05-30T11:12:00Z"`, `"published_at": "2026-05-30T13:12:00+02:00"`, 1)
 	state, err := Parse([]byte(body))
@@ -145,6 +161,12 @@ func TestParseRejectsInvalidOutputMetadata(t *testing.T) {
 		"negative size": func(s *DistributorState) {
 			s.Outputs[0].Size = -1
 		},
+		"invalid output url": func(s *DistributorState) {
+			s.Outputs[0].URL = "file:///tmp/report.md"
+		},
+		"invalid primary url": func(s *DistributorState) {
+			s.Links = &LinkState{PrimaryURL: "file:///tmp/report.md"}
+		},
 	}
 	for name, mutate := range tests {
 		t.Run(name, func(t *testing.T) {
@@ -157,6 +179,23 @@ func TestParseRejectsInvalidOutputMetadata(t *testing.T) {
 	}
 }
 
+func TestValidateReportsURLFieldContext(t *testing.T) {
+	source := validManifest(t)
+	state := *withState(t, source, func(s *DistributorState) {
+		s.Links = &LinkState{PrimaryURL: "https://reports.example.com/archive#top"}
+	})
+	err := Validate(state)
+	assertStateErrorContains(t, err, "state links.primary_url")
+	assertStateErrorContains(t, err, "must not include a fragment")
+
+	state = *withState(t, source, func(s *DistributorState) {
+		s.Outputs[0].URL = "https://reports.example.com/archive?preview=1"
+	})
+	err = Validate(state)
+	assertStateErrorContains(t, err, "state outputs[0].url")
+	assertStateErrorContains(t, err, "must not include a query string")
+}
+
 func TestParseRejectsMalformedPublishedTimestamp(t *testing.T) {
 	body := strings.Replace(validStateJSON(t), `"published_at": "2026-05-30T11:12:00Z"`, `"published_at": "May 30"`, 1)
 	_, err := Parse([]byte(body))
@@ -188,6 +227,36 @@ func TestMarshalNormalizesPublishedAtUTC(t *testing.T) {
 	}
 }
 
+func TestMarshalIncludesLinksWhenPresent(t *testing.T) {
+	source := validManifest(t)
+	state := DistributorState{
+		SchemaVersion: SchemaVersion,
+		PipelineID:    "reports",
+		DestinationID: "archive",
+		PublishedAt:   time.Date(2026, 5, 30, 11, 12, 0, 0, time.UTC),
+		Source:        SourceState{Manifest: source},
+		Links:         &LinkState{PrimaryURL: "https://reports.example.com/archive/report.md"},
+		Outputs: []OutputFile{{
+			Path:       "report.md",
+			Kind:       OutputKindSource,
+			SourcePath: "report.md",
+			URL:        "https://reports.example.com/archive/report.md",
+			SHA256:     source.Files[0].SHA256,
+			Size:       source.Files[0].Size,
+		}},
+	}
+	data, err := json.Marshal(state)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	if !strings.Contains(string(data), `"links":{"primary_url":"https://reports.example.com/archive/report.md"}`) {
+		t.Fatalf("json = %s, want links primary URL", data)
+	}
+	if !strings.Contains(string(data), `"url":"https://reports.example.com/archive/report.md"`) {
+		t.Fatalf("json = %s, want output URL", data)
+	}
+}
+
 func validStateJSON(t *testing.T) string {
 	t.Helper()
 	return validStateWithManifestJSON(t, manifestJSON(t))

internal/state/validate.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 
 	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/link"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 )
 
@@ -28,6 +29,11 @@ func Validate(s DistributorState) error {
 	if err := validateEmbeddedManifest(s.Source.Manifest); err != nil {
 		return fmt.Errorf("state source.manifest: %w", err)
 	}
+	if s.Links != nil && s.Links.PrimaryURL != "" {
+		if err := link.ValidateHTTPURL(s.Links.PrimaryURL); err != nil {
+			return fmt.Errorf("state links.primary_url: %w", err)
+		}
+	}
 	if s.Outputs == nil {
 		return fmt.Errorf("state outputs is required")
 	}
@@ -63,6 +69,11 @@ func validateOutput(index int, output OutputFile) error {
 	if output.Kind == OutputKindGenerated && output.Transform == "" {
 		return fmt.Errorf("state outputs[%d].transform is required for generated output", index)
 	}
+	if output.URL != "" {
+		if err := link.ValidateHTTPURL(output.URL); err != nil {
+			return fmt.Errorf("state outputs[%d].url: %w", index, err)
+		}
+	}
 	if err := bundle.ValidateDigest(output.SHA256); err != nil {
 		return fmt.Errorf("state outputs[%d].sha256: %w", index, err)
 	}

internal/storage/backend.go

@@ -30,6 +30,7 @@ type Backend interface {
 	Walk(ctx context.Context, prefix string, opts WalkOptions, fn WalkFunc) error
 	HasAny(ctx context.Context, prefix string) (bool, error)
 	DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts DeleteOptions) error
+	DeletePrefix(ctx context.Context, prefix string, opts DeleteOptions) error
 }
 
 type WalkOptions struct {

internal/storage/errors.go

@@ -29,6 +29,7 @@ const (
 	OpWalk                = "walk"
 	OpHasAny              = "has any"
 	OpDeleteManagedBundle = "delete managed bundle"
+	OpDeletePrefix        = "delete prefix"
 	OpRegisterBackend     = "register backend"
 	OpOpenBackend         = "open backend"
 )

internal/storage/fake/backend.go

@@ -3,7 +3,6 @@ package fake
 import (
 	"bytes"
 	"context"
-	"errors"
 	"io"
 	"sort"
 	"strings"
@@ -133,14 +132,14 @@ func (b *Backend) Walk(ctx context.Context, prefix string, opts storage.WalkOpti
 	if err := storage.ValidatePrefix(prefix); err != nil {
 		return err
 	}
+	emitter := storage.NewWalkEmitter(ctx, backendName, opts, fn)
 	if entry, err := b.Stat(ctx, prefix); err == nil && entry.Type != storage.EntryTypeDirectory {
-		return emit(ctx, entry, opts, fn)
+		return storage.FinishWalk(emitter.Emit(entry))
 	} else if err != nil && !storage.IsNotFound(err) {
 		return err
 	}
 
 	entries := b.entries()
-	visited := 0
 	for _, entry := range entries {
 		if entry.Path == "" || !entryBelow(prefix, entry.Path) {
 			continue
@@ -148,33 +147,15 @@ func (b *Backend) Walk(ctx context.Context, prefix string, opts storage.WalkOpti
 		if !opts.Recursive && !isImmediateChild(prefix, entry.Path) {
 			continue
 		}
-		if opts.Limit > 0 && visited >= opts.Limit {
-			return nil
-		}
-		visited++
-		if err := ctx.Err(); err != nil {
-			return err
-		}
-		if err := fn(entry); err != nil {
-			if errors.Is(err, storage.ErrStopWalk) {
-				return nil
-			}
-			return storage.NewError(storage.OpWalk, backendName, entry.Path, storage.ErrUnknown, err)
+		if err := emitter.Emit(entry); err != nil {
+			return storage.FinishWalk(err)
 		}
 	}
 	return nil
 }
 
 func (b *Backend) HasAny(ctx context.Context, prefix string) (bool, error) {
-	found := false
-	err := b.Walk(ctx, prefix, storage.WalkOptions{Recursive: false, Limit: 1}, func(storage.Entry) error {
-		found = true
-		return storage.ErrStopWalk
-	})
-	if err != nil {
-		return false, err
-	}
-	return found, nil
+	return storage.HasAny(ctx, b, prefix)
 }
 
 func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
@@ -205,6 +186,41 @@ func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, ma
 	return nil
 }
 
+func (b *Backend) DeletePrefix(ctx context.Context, prefix string, opts storage.DeleteOptions) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if err := storage.ValidatePrefix(prefix); err != nil {
+		return err
+	}
+	if prefix != "" && !b.exists(prefix) && !b.hasChild(prefix) {
+		if opts.IgnoreMissing {
+			return nil
+		}
+		return storage.NewError(storage.OpDeletePrefix, backendName, prefix, storage.ErrNotFound, nil)
+	}
+	for path := range b.files {
+		if path == prefix || entryBelow(prefix, path) {
+			delete(b.files, path)
+		}
+	}
+	for path := range b.symlinks {
+		if path == prefix || entryBelow(prefix, path) {
+			delete(b.symlinks, path)
+		}
+	}
+	for path := range b.dirs {
+		if path != "" && (path == prefix || entryBelow(prefix, path)) {
+			delete(b.dirs, path)
+		}
+	}
+	if opts.PruneEmptyDirs {
+		b.pruneEmptyParents(parentOf(prefix))
+	}
+	b.dirs[""] = struct{}{}
+	return nil
+}
+
 func (b *Backend) ensureParents(path string) {
 	parent := parentOf(path)
 	for parent != "" {
@@ -267,19 +283,6 @@ func (b *Backend) entries() []storage.Entry {
 	return entries
 }
 
-func emit(ctx context.Context, entry storage.Entry, opts storage.WalkOptions, fn storage.WalkFunc) error {
-	if opts.Limit > 0 && opts.Limit < 1 {
-		return nil
-	}
-	if err := ctx.Err(); err != nil {
-		return err
-	}
-	if err := fn(entry); err != nil && !errors.Is(err, storage.ErrStopWalk) {
-		return err
-	}
-	return nil
-}
-
 func entryBelow(prefix, path string) bool {
 	if prefix == "" {
 		return path != ""