Documents custom state directory feature and use cases

Updates README.md with practical examples showing how to use custom
state directories with absolute paths, tilde expansion, and relative
paths. Adds API_REFERENCE.md documentation detailing the state_directory
parameter, path handling behavior, and common use cases (testing,
containers, multi-tenant apps, development environments).

Clarifies that this feature is optional and defaults maintain backward
compatibility with platform-specific directories.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: crdant

API_REFERENCE.md

@@ -56,15 +56,17 @@ ReplicatedClient(
     publishable_key: str,
     app_slug: str,
     base_url: str = "https://replicated.app",
-    timeout: float = 30.0
+    timeout: float = 30.0,
+    state_directory: Optional[str] = None
 )
 ```
 
 **Parameters:**
 - `publishable_key`: Your publishable API key from the Vendor Portal
 - `app_slug`: Your application slug
-- `base_url`: Base URL for the API (optional)
-- `timeout`: Request timeout in seconds (optional)
+- `base_url`: Base URL for the API (optional, defaults to "https://replicated.app")
+- `timeout`: Request timeout in seconds (optional, defaults to 30.0)
+- `state_directory`: Custom directory for state storage (optional). If not provided, uses platform-specific defaults. Supports `~` expansion and relative paths.
 
 #### Methods
 
@@ -76,7 +78,7 @@ The asynchronous version of ReplicatedClient with identical API but requiring `a
 
 #### Constructor
 
-Same parameters as `ReplicatedClient`.
+Same parameters as `ReplicatedClient`, including the optional `state_directory`.
 
 #### Context Manager
 
@@ -160,11 +162,32 @@ The SDK automatically manages local state for:
 
 ### State Directory
 
-State is stored in platform-specific directories:
+State is stored in platform-specific directories by default:
 - **macOS:** `~/Library/Application Support/Replicated/<app_slug>`
 - **Linux:** `${XDG_STATE_HOME:-~/.local/state}/replicated/<app_slug>`
 - **Windows:** `%APPDATA%\Replicated\<app_slug>`
 
+You can override the state directory by providing the `state_directory` parameter:
+
+```python
+client = ReplicatedClient(
+    publishable_key="...",
+    app_slug="my-app",
+    state_directory="/custom/path/to/state"
+)
+```
+
+**Path Handling:**
+- The SDK automatically expands `~` to your home directory
+- Relative paths are resolved to absolute paths
+- The directory will be created automatically if it doesn't exist
+
+**Use Cases for Custom Directories:**
+- **Testing:** Use temporary directories for isolated test runs
+- **Containers:** Mount persistent volumes at custom paths
+- **Multi-tenant:** Isolate state per tenant in separate directories
+- **Development:** Use project-local directories for development state
+
 ## Machine Fingerprinting
 
 The SDK generates unique machine fingerprints using:

README.md

@@ -34,6 +34,34 @@ instance.set_status(InstanceStatus.RUNNING)
 instance.set_version("1.2.0")
 ```
 
+### Custom State Directory
+
+By default, the SDK stores state in platform-specific directories. You can override this for testing, containerization, or custom deployments:
+
+```python
+from replicated import ReplicatedClient
+
+# Use a custom directory (supports ~ and relative paths)
+client = ReplicatedClient(
+    publishable_key="replicated_pk_...",
+    app_slug="my-app",
+    state_directory="/var/lib/my-app/replicated-state"
+)
+
+# Or use a relative path (will be resolved to absolute)
+client = ReplicatedClient(
+    publishable_key="replicated_pk_...",
+    app_slug="my-app",
+    state_directory="./local-state"
+)
+```
+
+**When to use custom state directories:**
+- Testing with temporary directories
+- Docker containers with mounted volumes
+- Multi-tenant applications requiring isolated state
+- Development with project-local state
+
 ### Async Example
 
 ```python