Add SSH SFTP backend support

docs/troubleshooting.md

@@ -34,11 +34,11 @@ Diagnostic:
 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 unavailable.
+Safe fix: use `backend: local` or `backend: ssh` for executable workflows. S3 config shape is accepted only for validation; runtime execution is unavailable.
 
-## `backend ssh is not implemented for execution` or `backend s3 is not implemented for execution`
+## `backend s3 is not implemented for execution`
 
-Likely cause: the config validates but `run` tried to execute a remote backend.
+Likely cause: the config validates but `run` tried to execute S3, which is not implemented.
 
 Diagnostic:
 
@@ -46,7 +46,69 @@ Diagnostic:
 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 unless those adapters are added. See [configuration](config.md).
+Safe fix: use `local` or `ssh` for executable workflows. See [configuration](config.md).
+
+## `host is required for ssh backend`
+
+Likely cause: SSH config is missing the structured `host` field, or an old URI-based 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`. The `uri` field is not used for SSH execution.
+
+## `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.
+
+## `stat ssh ... not_found` or `no bundles found`
+
+Likely cause: the configured SSH `path` is wrong, unreadable, or does not contain source bundles.
+
+Diagnostic:
+
+```sh
+sftp <user>@<host>
+```
+
+Safe fix: correct the remote root `path`, permissions, or source bundle location.
 
 ## `validate command requires a path` or `inspect command requires a path`