Docs: Network volume path guidance, S3 upload, and test workaround

.changeset/docs-network-volume-guidance.md

@@ -0,0 +1,5 @@
+---
+"worker-comfyui": patch
+---
+
+docs: clarify network-volume path semantics (paths relative to volume root), document S3-compatible upload flow, and note the `.runpod/tests_.json` rename for tests that fail without the volume.

docs/network-volumes.md

@@ -24,6 +24,10 @@ If you use the S3-compatible API, the same paths map as:
 - Pod: `/workspace/my-folder/file.txt`
 - S3 API: `s3://<NETWORK_VOLUME_ID>/my-folder/file.txt`
 
+> **Important: Path on the network storage**
+>
+> When you upload or configure paths **on the network storage itself** (e.g. via S3), use paths **relative to the volume root**. For example, put models at `/models/[model]/file_name.ext`, **not** `/runpod-volume/models/...`. The worker mounts the volume at `/runpod-volume`, so if you use `/runpod-volume` in the path on the storage, the container will see `runpod-volume/runpod-volume/models/...` and models will not be found.
+
 ## Expected Directory Structure
 
 Models must be placed in the following structure on your network volume:
@@ -47,6 +51,22 @@ Models must be placed in the following structure on your network volume:
 >
 > Only create the subdirectories you actually need; empty or missing folders are fine.
 
+## Uploading models via the S3-compatible API
+
+You can upload models to your network volume using RunPod’s [S3-compatible API](https://docs.runpod.io/storage/s3-api). You need an **S3 API key** (separate from your RunPod API key): create one under **Settings → S3 API Keys** in the RunPod console. The access key and secret are shown there; the docs explain [setup and authentication](https://docs.runpod.io/storage/s3-api#setup-and-authentication) in detail.
+
+```bash
+AWS_ACCESS_KEY_ID=your_access_key \
+AWS_SECRET_ACCESS_KEY=your_secret_key \
+aws s3 cp \
+  --region [REGION] \
+  --endpoint-url ENDPOINT_URL \
+  /path/to/local/file.ext \
+  s3://BUCKET_NAME/models/[model]/file_name.ext
+```
+
+The file will then appear at `/runpod-volume/models/[model]/file_name.ext` inside the worker.
+
 ## Supported File Extensions
 
 ComfyUI only recognizes files with specific extensions when scanning model directories.
@@ -76,6 +96,10 @@ Files with other extensions (for example `.txt`, `.zip`) are **ignored** by Comf
 
 If any of the above is true, ComfyUI will silently fail to discover models from the network volume.
 
+### Tests and `runpod-volume` access
+
+RunPod’s test environment does **not** have access to the network volume mount: the `/runpod-volume` folder is not visible when tests run. When the endpoint starts for real, the volume is mounted and the folder appears. The repository ships with the tests file renamed to `.runpod/tests_.json` so they don't run by default; if you've re-enabled them and they fail with `Value not in list`, remove or rename the file again so the endpoint is deployed without running those tests.
+
 ## Debugging with `NETWORK_VOLUME_DEBUG`
 
 The worker exposes an opt‑in debug mode controlled via the `NETWORK_VOLUME_DEBUG` environment variable.