docs: improve Claw Compactor integration + security notes

README.md

@@ -44,6 +44,8 @@ One wallet, 41+ models, zero API keys.
 | [Screenshots](#-screenshots)              | See it in action                |
 | [Payment](#-payment)                      | x402 non-custodial USDC         |
 | [Configuration](#%EF%B8%8F-configuration) | Environment variables           |
+| [Compactor Integration](#-compactor-integration) | ClawRouter × Claw Compactor |
+| [Security Notes](#-security-notes)        | Secrets and wallet safety       |
 | [Troubleshooting](#-troubleshooting)      | `doctor` AI-powered diagnostics |
 | [vs OpenRouter](#-vs-openrouter)          | Why ClawRouter wins             |
 | [Support](#-support)                      | Telegram, X, founders           |
@@ -236,6 +238,33 @@ For basic usage, no configuration needed. For advanced options:
 
 ---
 
+## 🦞 Compactor Integration
+
+If you want maximum savings, pair ClawRouter with Claw Compactor.
+
+- Claw Compactor reduces token volume (input size)
+- ClawRouter reduces token unit cost ($/token)
+
+Recommended order:
+
+`Compactor -> ClawRouter -> Provider`
+
+**Guide:** [docs/claw-compactor-integration.md](docs/claw-compactor-integration.md)
+
+---
+
+## 🔐 Security Notes
+
+For operators and contributors, read the secrets policy before production use:
+
+- no plaintext seed persistence
+- token redaction in logs
+- secure credential storage guidance
+
+**Policy:** [docs/security-secrets.md](docs/security-secrets.md)
+
+---
+
 ## 🥊 vs OpenRouter
 
 |                 | OpenRouter / LiteLLM        | ClawRouter                       |

docs/claw-compactor-integration.md

@@ -0,0 +1,86 @@
+# ClawRouter × Claw Compactor Integration Guide
+
+This guide explains how to combine:
+
+- **ClawRouter** (model routing + payment)
+- **Claw Compactor** (context compression)
+
+Together, they reduce cost from two directions:
+
+1. **Fewer tokens sent** (Compactor)
+2. **Lower $/token paid** (Router)
+
+---
+
+## Why combine them?
+
+ClawRouter alone optimizes model choice.
+Claw Compactor alone optimizes context size.
+
+Using both usually gives better savings than either one alone.
+
+---
+
+## Recommended order in request pipeline
+
+```text
+OpenClaw request
+  -> Claw Compactor (compress context)
+  -> ClawRouter (route to lowest-cost capable model)
+  -> Provider
+```
+
+Compaction should happen **before routing**, so router sees the real token footprint.
+
+---
+
+## Practical setup
+
+1. Install and enable ClawRouter plugin
+2. Install Claw Compactor in your workspace
+3. Enable Compactor auto mode (or hook mode)
+4. Keep ClawRouter on `auto` profile
+
+---
+
+## Validation checklist
+
+Use the same workload and compare:
+
+- Baseline: no compaction + fixed expensive model
+- Router only
+- Compactor only
+- Router + Compactor
+
+Track:
+
+- input/output tokens
+- effective $/request
+- p95 latency
+- task quality / regression rate
+
+---
+
+## Safety notes
+
+- Keep compression deterministic and reversible where possible
+- Do not compress secrets into logs or headers
+- Audit tool-output compression for semantic loss before production rollout
+
+---
+
+## What ClawRouter already includes
+
+ClawRouter contains built-in context compression layers inspired by Claw Compactor (dictionary, observation compression, dynamic codebook).
+
+Use external Claw Compactor when you need:
+
+- workspace-level file compression workflows
+- custom memory/markdown compression policies
+- explicit per-run savings reporting in chat
+
+---
+
+## Attribution
+
+Parts of ClawRouter compression architecture are inspired by Claw Compactor design patterns.

docs/security-secrets.md

@@ -0,0 +1,58 @@
+# Security: Secrets, Wallet Material, and Local State
+
+This document defines secure defaults for ClawRouter operators and contributors.
+
+## 1) Never persist seed material in plaintext
+
+High-risk secrets must not be written to disk unencrypted:
+
+- wallet mnemonic / seed phrase
+- private keys
+- exported wallet seeds
+- long-lived API tokens
+
+If persistence is required, use OS-backed secure storage (Keychain / Secret Service / KMS).
+
+---
+
+## 2) Token handling
+
+- Read tokens from env at runtime
+- Avoid printing tokens in logs
+- Redact sensitive values in diagnostics and errors
+- Prefer short-lived credentials when possible
+
+---
+
+## 3) File permissions are defense-in-depth, not primary protection
+
+`chmod 600` is useful but **not sufficient** for critical key material.
+
+Treat local files as potentially recoverable through:
+
+- backups
+- endpoint compromise
+- misconfigured sync
+
+---
+
+## 4) Contributor checklist for security-sensitive PRs
+
+Before merge:
+
+- [ ] Secret-bearing files are avoided or encrypted
+- [ ] Logs do not leak secrets
+- [ ] New env vars are documented with risk level
+- [ ] Fallback paths do not silently downgrade security
+- [ ] Migration/cleanup steps exist for legacy insecure state
+
+---
+
+## 5) Incident response
+
+If potential secret leakage is discovered:
+
+1. Rotate impacted credentials immediately
+2. Revoke/replace wallet material if applicable
+3. Add temporary guardrails to block re-introduction
+4. Publish a patch + security note