docs: add FreeRide documentation and update README

README.md

@@ -97,6 +97,8 @@
 
 🧠 **Smart routing**: Rule-based model routing — simple queries go to lightweight models, saving API costs.
 
+🧬 **FreeRide**: Intelligent model rotation using OpenRouter's free pool — never pay for basic LLM traffic again. [Learn more](docs/freeride.md).
+
 🛡️ **Hardened Multi-User Isolation**: Built-in [Tenant Isolation](docs/configuration.md#🔒-multi-tenant-agent-isolation) for shared infrastructure (Azure/ACA) — automatically partitions workspaces, memory, and tools (including MCP) per-user session.
 
 🛡️ **Security Shield**: Active protection layers including Canary tokens (leak detection), PII Redaction, Indirect Prompt Injection (IPIA) Analysis, and Tool Policy-as-Code. [Learn more](docs/security_configuration.md#security-shield-active-protection).
@@ -607,6 +609,7 @@ For detailed guides beyond this README:
 | [Scheduled Tasks and Cron Jobs](docs/cron.md) | Cron schedule types, deliver modes, command gates, job storage |
 | [Providers & Models](docs/providers.md) | 30+ LLM providers, model routing, model_list configuration |
 | [Spawn & Async Tasks](docs/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |
+| [FreeRide](docs/freeride.md) | Dynamic free model rotation and K3s secret management |
 | [Hooks](docs/hooks/README.md) | Event-driven hook system: observers, interceptors, approval hooks |
 | [Steering](docs/steering.md) | Inject messages into a running agent loop between tool calls |
 | [SubTurn](docs/subturn.md) | Subagent coordination, concurrency control, lifecycle |

docs/freeride.md

@@ -0,0 +1,102 @@
+# FreeRide 🦞
+
+FreeRide is a dynamic model rotation and failover system for PicoClaw that leverages OpenRouter's free model pool. It ensures your agent stays alive even if individual free models become rate-limited or go offline.
+
+## Key Features
+
+- **Automatic Discovery**: Scans OpenRouter for the best currently available free models.
+- **Dynamic Failover**: Automatically rotates through a pool of models when errors (like 429 Rate Limiting) occur.
+- **Intelligent Ranking**: Models are scored and ranked based on context length, capabilities (tools/vision), and provider trust.
+- **K3s Ready**: Designed to work seamlessly in Kubernetes environments with secure API key management.
+
+## Configuration
+
+FreeRide is implemented as a native PicoClaw tool.
+
+### 1. Enable the Tool
+Ensure the `freeride` tool is enabled and whitelisted in your `config.json`:
+
+```json
+{
+  "tools": {
+    "whitelist": ["freeride", ...],
+    "whitelist_enabled": true,
+    "security_policy": {
+      "enabled": true,
+      "config": {
+        "allowed_tools": {
+          "freeride": true
+        }
+      }
+    }
+  }
+}
+```
+
+### 2. Set the API Key
+FreeRide requires an OpenRouter API key. Even for free models, many providers require a key for identification and higher rate limits.
+
+In **Local Mode**, set the environment variable:
+```bash
+export OPENROUTER_API_KEY="sk-or-v1-..."
+```
+
+In **K3s Mode**, add the secret to your cluster (see below).
+
+## Usage
+
+You can interact with FreeRide directly through the agent:
+
+### `freeride auto`
+**The most important command.** This command:
+1. Fetches the current list of ~28+ free models.
+2. Ranks them by quality.
+3. Automatically populates your `config.json`'s `model_list`.
+4. Adds the top 5 models to your agent's `model_fallbacks` list.
+5. Reloads the agent configuration instantly.
+
+### `freeride status`
+Shows your current primary model and the active fallback rotation pool.
+
+### `freeride list [limit]`
+Displays the current top-ranked free models available on OpenRouter without modifying your configuration.
+
+## K3s Deployment & Secrets
+
+When running PicoClaw on K3s, follow these steps to manage your secrets safely.
+
+### Adding the Secret
+If you are creating the secrets for the first time:
+```bash
+kubectl create secret generic picoclaw-secrets \
+  --namespace agi \
+  --from-literal=openrouter-api-key="YOUR_KEY_HERE"
+```
+
+### Updating Existing Secrets (Safe Patching)
+If `picoclaw-secrets` already exists and you want to add the OpenRouter key without losing your Telegram or NVIDIA keys, use **`kubectl patch`**:
+
+```bash
+kubectl patch secret picoclaw-secrets \
+  --namespace agi \
+  --type='json' \
+  -p='[{"op": "add", "path": "/data/openrouter-api-key", "value":"'$(echo -n "YOUR_KEY_HERE" | base64 -w0)'"}]'
+```
+
+### Deployment Configuration
+Ensure your `deployment.yaml` maps the secret to the environment variable:
+
+```yaml
+env:
+  - name: OPENROUTER_API_KEY
+    valueFrom:
+      secretKeyRef:
+        name: picoclaw-secrets
+        key: openrouter-api-key
+```
+
+## Troubleshooting
+
+- **404 Errors**: Ensure the model is still available on OpenRouter using `freeride list`. If it's gone, run `freeride auto` to refresh your fallback pool.
+- **429 Rate Limiting**: This is common with free models. PicoClaw will automatically try the next model in your `model_fallbacks` list.
+- **Security Blocks**: Ensure `freeride` is added to your `security_policy` allowed tools map.