Expose managed output pruning

docs/troubleshooting.md

@@ -87,6 +87,24 @@ Safe fix: pass the configured `--config`, `--pipeline`, and `--destination` valu
 
 Reference: [CLI](cli.md#reconcile-state).
 
+## Prune Selector Or Mode Is Missing Or Wrong
+
+Symptom: `prune requires --config`, `requires --pipeline`, `requires --destination`, `requires exactly one of --dry-run or --apply`, `pipeline "<id>" not found`, `destination <id> not found`, or `state owner is ... not ...`.
+
+Likely cause: the command did not identify one configured destination root, did not choose exactly one execution mode, or the selected root contains state for a different single-owner pipeline/destination.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor prune --help
+rg -n 'retention:|prune:|pipelines:|destinations:|id:' <config-path>
+cat <destination-path>/.distributor.json
+```
+
+Safe fix: pass the configured `--config`, `--pipeline`, and `--destination` values that identify the destination root containing the state file. Use `--dry-run` for read-only review or `--apply` for deletion, but not both. For unrelated single-owner state, use the correct config selector or a separate destination root; `prune` will not take over mismatched state.
+
+Reference: [CLI](cli.md#prune).
+
 ## Output Format Is Invalid
 
 Symptom: `format must be text or json`.
@@ -220,6 +238,28 @@ Safe fix: if the missing files should no longer be managed, rerun the same comma
 
 Reference: [Operations](operations.md#destination-state-repair).
 
+## Prune Reports No Planned Deletes
+
+Symptom: `prune --dry-run` reports `planned=0` or JSON `planned_outputs: []`.
+
+Likely cause: pruning is disabled for the selected destination, every managed output is preserved by `keep_latest`, no managed output is older than `older_than`, or the selected shared-root owner has no eligible outputs.
+
+Diagnostic:
+
+```sh
+rg -n 'retention:|prune:|older_than:|keep_latest:' <config-path>
+go run ./cmd/distributor prune \
+  --config <config-path> \
+  --pipeline <pipeline-id> \
+  --destination <destination-id> \
+  --dry-run \
+  --format json
+```
+
+Safe fix: verify the selected destination's retention policy and the managed output `updated_at` timestamps in `.distributor.json`. Adjust config if the policy is too conservative, then rerun `--dry-run` before using `--apply`.
+
+Reference: [Operations](operations.md#managed-output-pruning).
+
 ## Destination Is Newer Than Source
 
 Symptom: `skip_destination_newer` or `destination is newer and replacement requires --force`.