Add S3-compatible storage backend

docs/troubleshooting.md

@@ -34,11 +34,11 @@ Diagnostic:
 rg -n "backend:" <config-path>
 ```
 
-Safe fix: use `backend: local` or `backend: ssh` for executable workflows. S3 config shape is accepted only for validation; runtime execution is unavailable.
+Safe fix: use `backend: local`, `backend: ssh`, or `backend: s3` for executable workflows.
 
-## `backend s3 is not implemented for execution`
+## `prefix must be a clean relative slash-separated path`
 
-Likely cause: the config validates but `run` tried to execute S3, which is not implemented.
+Likely cause: S3 `prefix` contains traversal, dot segments, empty segments, or backslashes after leading and trailing slashes are trimmed.
 
 Diagnostic:
 
@@ -46,7 +46,44 @@ Diagnostic:
 go run ./cmd/distributor run --config <config-path> --dry-run
 ```
 
-Safe fix: use `local` or `ssh` for executable workflows. See [configuration](config.md).
+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`
 
@@ -92,7 +129,7 @@ Likely cause: a backend credential field references an environment variable that
 Diagnostic:
 
 ```sh
-printenv <variable-name>
+env | cut -d= -f1 | rg '^<variable-name>$'
 ls -l <secrets-directory>/<variable-name>
 ```
 
@@ -105,7 +142,7 @@ Likely cause: the real process environment and secrets directory both define the
 Diagnostic:
 
 ```sh
-printenv <variable-name>
+env | cut -d= -f1 | rg '^<variable-name>$'
 ls -l <secrets-directory>/<variable-name>
 ```