Document shared-root publishing

docs/troubleshooting.md

@@ -230,6 +230,40 @@ Safe fix: adjust source files or publish/transform policy so copied and generate
 
 Reference: [Configuration](config.md#publish-and-transform-policy).
 
+## Shared-Root Ownership Conflict
+
+Symptom: `fail_conflict` with a reason like `destination output path ... is owned by <pipeline>/<destination>`.
+
+Likely cause: a `state.mode: shared_root` destination planned an output path already recorded in `.distributor.json` for another pipeline/destination owner.
+
+Diagnostic:
+
+```sh
+cat <destination-path>/.distributor.json
+go run ./cmd/distributor run --config <config-path> --dry-run
+```
+
+Safe fix: change one owner so it writes a different output path, use a separate destination root, or intentionally replace the whole destination root only after previewing with `--dry-run --force`.
+
+Reference: [Operations](operations.md#destination-state-and-retry-behavior).
+
+## Shared-Root Unmanaged Path Collision
+
+Symptom: `fail_unmanaged` with a reason like `destination output path ... exists but is not managed by destination state`.
+
+Likely cause: a `state.mode: shared_root` destination planned a new output path that already exists in storage but is not recorded as managed in `.distributor.json`.
+
+Diagnostic:
+
+```sh
+find <destination-path> -maxdepth 2 -print
+cat <destination-path>/.distributor.json
+```
+
+Safe fix: move the unmanaged file aside, change the planned output path, or use forced replacement only when deleting the configured destination root is intended.
+
+Reference: [Operations](operations.md#forced-replacement-workflow).
+
 ## Run Failed After Writing Some Files
 
 Symptom: a destination write failed and the command exited non-zero after partial work.