feat(proxy): add scoped proxy configuration and docs runbooks

- add scope-aware proxy schema and runtime wiring for providers/channels/tools

- add agent callable proxy_config tool for fast proxy setup

- standardize docs system with index, template, and playbooks

docs/proxy-agent-playbook.md

@@ -0,0 +1,229 @@
+# Proxy Agent Playbook
+
+This playbook provides copy-paste tool calls for configuring proxy behavior via `proxy_config`.
+
+Use this document when you want the agent to switch proxy scope quickly and safely.
+
+## 0. Summary
+
+- **Purpose:** provide copy-ready agent tool calls for proxy scope management and rollback.
+- **Audience:** operators and maintainers running ZeroClaw in proxied networks.
+- **Scope:** `proxy_config` actions, mode selection, verification flow, and troubleshooting.
+- **Non-goals:** generic network debugging outside ZeroClaw runtime behavior.
+
+---
+
+## 1. Fast Path by Intent
+
+Use this section for quick operational routing.
+
+### 1.1 Proxy only ZeroClaw internal traffic
+
+1. Use scope `zeroclaw`.
+2. Set `http_proxy`/`https_proxy` or `all_proxy`.
+3. Validate with `{"action":"get"}`.
+
+Go to:
+
+- [Section 4](#4-mode-a--proxy-only-for-zeroclaw-internals)
+
+### 1.2 Proxy only selected services
+
+1. Use scope `services`.
+2. Set concrete keys or wildcard selectors in `services`.
+3. Validate coverage using `{"action":"list_services"}`.
+
+Go to:
+
+- [Section 5](#5-mode-b--proxy-only-for-specific-services)
+
+### 1.3 Export process-wide proxy environment variables
+
+1. Use scope `environment`.
+2. Apply with `{"action":"apply_env"}`.
+3. Verify env snapshot via `{"action":"get"}`.
+
+Go to:
+
+- [Section 6](#6-mode-c--proxy-for-full-process-environment)
+
+### 1.4 Emergency rollback
+
+1. Disable proxy.
+2. If needed, clear env exports.
+3. Re-check runtime and environment snapshots.
+
+Go to:
+
+- [Section 7](#7-disable--rollback-patterns)
+
+---
+
+## 2. Scope Decision Matrix
+
+| Scope | Affects | Exports env vars | Typical use |
+|---|---|---|---|
+| `zeroclaw` | ZeroClaw internal HTTP clients | No | Normal runtime proxying without process-level side effects |
+| `services` | Only selected service keys/selectors | No | Fine-grained routing for specific providers/tools/channels |
+| `environment` | Runtime + process environment proxy variables | Yes | Integrations that require `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` |
+
+---
+
+## 3. Standard Safe Workflow
+
+Use this sequence for every proxy change:
+
+1. Inspect current state.
+2. Discover valid service keys/selectors.
+3. Apply target scope configuration.
+4. Verify runtime and environment snapshots.
+5. Roll back if behavior is not expected.
+
+Tool calls:
+
+```json
+{"action":"get"}
+{"action":"list_services"}
+```
+
+---
+
+## 4. Mode A — Proxy Only for ZeroClaw Internals
+
+Use when ZeroClaw provider/channel/tool HTTP traffic should use proxy, without exporting process-level proxy env vars.
+
+Tool calls:
+
+```json
+{"action":"set","enabled":true,"scope":"zeroclaw","http_proxy":"http://127.0.0.1:7890","https_proxy":"http://127.0.0.1:7890","no_proxy":["localhost","127.0.0.1"]}
+{"action":"get"}
+```
+
+Expected behavior:
+
+- Runtime proxy is active for ZeroClaw HTTP clients.
+- `HTTP_PROXY` / `HTTPS_PROXY` process env exports are not required.
+
+---
+
+## 5. Mode B — Proxy Only for Specific Services
+
+Use when only part of the system should use proxy (for example specific providers/tools/channels).
+
+### 5.1 Target specific services
+
+```json
+{"action":"set","enabled":true,"scope":"services","services":["provider.openai","tool.http_request","channel.telegram"],"all_proxy":"socks5h://127.0.0.1:1080","no_proxy":["localhost","127.0.0.1",".internal"]}
+{"action":"get"}
+```
+
+### 5.2 Target by selectors
+
+```json
+{"action":"set","enabled":true,"scope":"services","services":["provider.*","tool.*"],"http_proxy":"http://127.0.0.1:7890"}
+{"action":"get"}
+```
+
+Expected behavior:
+
+- Only matched services use proxy.
+- Unmatched services bypass proxy.
+
+---
+
+## 6. Mode C — Proxy for Full Process Environment
+
+Use when you intentionally need exported process env vars (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`) for runtime integrations.
+
+### 6.1 Configure and apply environment scope
+
+```json
+{"action":"set","enabled":true,"scope":"environment","http_proxy":"http://127.0.0.1:7890","https_proxy":"http://127.0.0.1:7890","no_proxy":"localhost,127.0.0.1,.internal"}
+{"action":"apply_env"}
+{"action":"get"}
+```
+
+Expected behavior:
+
+- Runtime proxy is active.
+- Environment variables are exported for the process.
+
+---
+
+## 7. Disable / Rollback Patterns
+
+### 7.1 Disable proxy (default safe behavior)
+
+```json
+{"action":"disable"}
+{"action":"get"}
+```
+
+### 7.2 Disable proxy and force-clear env vars
+
+```json
+{"action":"disable","clear_env":true}
+{"action":"get"}
+```
+
+### 7.3 Keep proxy enabled but clear environment exports only
+
+```json
+{"action":"clear_env"}
+{"action":"get"}
+```
+
+---
+
+## 8. Common Operation Recipes
+
+### 8.1 Switch from environment-wide proxy to service-only proxy
+
+```json
+{"action":"set","enabled":true,"scope":"services","services":["provider.openai","tool.http_request"],"all_proxy":"socks5://127.0.0.1:1080"}
+{"action":"get"}
+```
+
+### 8.2 Add one more proxied service
+
+```json
+{"action":"set","scope":"services","services":["provider.openai","tool.http_request","channel.slack"]}
+{"action":"get"}
+```
+
+### 8.3 Reset `services` list with selectors
+
+```json
+{"action":"set","scope":"services","services":["provider.*","channel.telegram"]}
+{"action":"get"}
+```
+
+---
+
+## 9. Troubleshooting
+
+- Error: `proxy.scope='services' requires a non-empty proxy.services list`
+  - Fix: set at least one concrete service key or selector.
+
+- Error: invalid proxy URL scheme
+  - Allowed schemes: `http`, `https`, `socks5`, `socks5h`.
+
+- Proxy does not apply as expected
+  - Run `{"action":"list_services"}` and verify service names/selectors.
+  - Run `{"action":"get"}` and check `runtime_proxy` and `environment` snapshot values.
+
+---
+
+## 10. Related Docs
+
+- [README.md](./README.md) — Documentation index and taxonomy.
+- [network-deployment.md](./network-deployment.md) — end-to-end network deployment and tunnel topology guidance.
+- [resource-limits.md](./resource-limits.md) — runtime safety limits for network/tool execution contexts.
+
+---
+
+## 11. Maintenance Notes
+
+- **Owner:** runtime and tooling maintainers.
+- **Update trigger:** new `proxy_config` actions, proxy scope semantics, or supported service selector changes.
+- **Last reviewed:** 2026-02-18.