Tighten local MVP user documentation

docs/troubleshooting.md

@@ -0,0 +1,135 @@
+# 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` for executable workflows. SSH and S3 config shapes are accepted only for validation; runtime execution is not implemented.
+
+## `backend ssh is not implemented for execution` or `backend s3 is not implemented for execution`
+
+Likely cause: the config validates but `run` tried to execute a remote backend.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor run --config <config-path> --dry-run
+```
+
+Safe fix: use local destinations for current executable workflows, or keep remote backend configs under roadmap material until those adapters exist. See [configuration](config.md).
+
+## `validate command requires a path` or `inspect command requires a path`
+
+Likely cause: `validate` or `inspect` was run without a path.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor validate --help
+go run ./cmd/distributor inspect --help
+```
+
+Safe fix: pass a local source bundle directory or a local tree containing source bundles.
+
+## `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. There is no force overwrite option.
+
+## `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.
+
+## `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 execution attempts to clean up outputs written during the failed attempt.
+
+Diagnostic:
+
+```sh
+find <destination-path> -maxdepth 2 -print
+```
+
+Safe fix: 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).