initial pinning docs

.cspell/words.txt

@@ -1,2 +1,3 @@
 backends
+prefetch
 renterd

File-Pinning.md

@@ -1 +1,134 @@
-Files can be pinned to cache to prevent eviction.
+# 📌 File Pinning
+
+Pinning keeps specific **files** cached locally and protected from eviction. It’s **per-file** metadata (stored in the mount’s meta DB) and is supported on **S3, Sia, and Encrypt** providers.  
+> **Not supported on Remote Mount.**
+
+---
+
+## ✅ Provider Compatibility
+
+| Provider      | Pin Support |
+|---------------|-------------|
+| **S3**        | Yes         |
+| **Sia**       | Yes         |
+| **Encrypt**   | Yes         |
+| **Remote Mount** | **No**  |
+
+> On **Remote Mount**, pin/unpin/status/list endpoints are **not implemented**; CLI pinning commands will return an error (HTTP error / unsupported).
+
+---
+
+## What “pinned” means
+
+- Pinned files are marked with `pinned=true` in the mount’s metadata database.
+- Cache eviction **skips** pinned files.
+- Pinning **does not auto-download** content in v2.0.x; the file is retained **after it’s cached** by normal access.
+  - `v2.1.x` and above, by default, will auto-download files not residing in cache.
+
+> To prefetch in v2.0.x, read the file once (e.g., `cat`, open/scan, copy).
+
+---
+
+## CLI
+
+These commands hit the local management HTTP API of the active **S3/Sia/Encrypt** mount.
+
+- **Pin a file**
+
+  ```shell
+  repertory -pf "/path/to/file.ext"
+  ```
+
+- **Unpin a file**
+
+  ```shell
+  repertory -uf "/path/to/file.ext"
+  ```
+
+- **Check pinned status**
+
+  ```shell
+  repertory -ps "/path/to/file.ext"
+  # → { "pinned": true|false }
+  ```
+
+- **List all pinned files**
+
+  ```shell
+  repertory -gpf
+  # → { "items": [ "/path/one", "/path/two", ... ] }
+  ```
+
+**Arguments:** `-pf`, `-uf`, `-ps` take an **API path** (virtual path inside the mount), e.g., `"/docs/report.pdf"`.  
+**Auth (optional):** `--user`, `--password`.  
+**Ports (defaults):** Sia **20000**, S3 **20100**, Encrypt **20001**.  
+
+> **Remote Mount:** pin CLI calls are **unsupported** and will error.
+
+---
+
+## REST API (S3/Sia/Encrypt)
+
+Base: `http://localhost:<api_port>/api/v1/` (Basic Auth if configured)
+
+### List pinned
+
+**GET** `get_pinned_files` → `200 OK`
+
+```json
+{ "items": [ "/path/one", "/path/two" ] }
+```
+
+### Pinned status
+
+**GET** `pinned_status?api_path=/path/to/file.ext` → `200 OK`
+
+```json
+{ "pinned": true }
+```
+Errors: `500` on provider/meta error.
+
+### Pin file
+
+**POST** `pin_file` (form: `api_path=/path/to/file.ext`)  
+Responses: `200 OK` on success, `404 Not Found` if not a file or doesn’t exist, `500` on error.
+
+### Unpin file
+
+**POST** `unpin_file` (form: `api_path=/path/to/file.ext`)  
+Responses: `200 OK` on success, `404 Not Found` if not a file or doesn’t exist, `500` on error.
+
+> Success bodies are empty JSON; rely on the HTTP status code.
+
+---
+
+## Examples (S3/Sia/Encrypt)
+
+```shell
+# Pin a file
+repertory -pf "/media/photos/2024/trip.jpg"
+
+# Verify status
+repertory -ps "/media/photos/2024/trip.jpg"
+# { "pinned": true }
+
+# List all pins
+repertory -gpf
+# { "items": [ "/media/photos/2024/trip.jpg", ... ] }
+```
+
+Windows (PowerShell):
+
+```powershell
+repertory -pf "/Docs/Quarterly Report.pdf"
+repertory -uf "/Docs/Quarterly Report.pdf"
+```
+
+---
+
+## Troubleshooting
+
+- **Remote Mount:** Pinning is **unsupported**; CLI returns an HTTP error/unsupported operation.
+- **404 Not Found:** Wrong path, item isn’t a file, or missing. Use `-gi` (item info) or `-gdi` (directory list) to verify paths.
+- **401/403:** API auth enabled — pass `--user` and `--password` or set in config.
+- **Pinned but not in local cache yet:** Pin prevents eviction; read once to cache locally for `v2.0.x`. For `v2.1.x+`, ensure configuration option `AutoDownloadOnPin` is set to `true`.