swarm-zap/TOOLS.md

# TOOLS.md - Local Notes

Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.

## What Goes Here

Things like:

- Camera names and locations
- SSH hosts and aliases
- Preferred voices for TTS
- Speaker/room names
- Device nicknames
- Anything environment-specific

## Examples

```markdown
### Cameras

- living-room → Main area, 180° wide angle
- front-door → Entrance, motion-triggered

### SSH

- home-server → 192.168.1.100, user: admin

### TTS

- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod
```

## Why Separate?

Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.

---

## LAN Services (Will)

- Host LAN IPs observed:
  - `192.168.153.113` (wlan0)
  - `192.168.153.117` (eth0)
- Tailscale IP:
  - `100.123.88.127`

### Session routing notes

- Current TUI conversations arrive with inbound metadata like:
  - `channel: webchat`
  - `provider: webchat`
  - `surface: webchat`
- Telegram DMs route into a separate main session when `session.dmScope = "per-channel-peer"`.
- Verified 2026-03-10:
  - TUI/webchat session remained separate from Telegram DM session
  - Telegram outbound + inbound both worked
  - Telegram inbound landed in its own main session file rather than the active TUI session

### Search routing

- Default page-reading tool: native `web_fetch`
- Default search path: `skills/local-meta-search/scripts/search.sh`
- Routing policy:
  - use **SearXNG first** for normal web lookups
  - fall back to **Brave MCP** if SearXNG fails or returns weak/empty results
  - use **Brave MCP directly** when Will explicitly asks for Brave / a second opinion
- Backend labels should be called out in research answers when relevant

#### Search cheat sheet

- General/local-first search:
  - `skills/local-meta-search/scripts/search.sh "query"`
- Direct SearXNG:
  - `skills/searxng-local-search/scripts/search.sh "query"`
- Direct Brave MCP:
  - `skills/brave-mcp-search/scripts/search.sh "query"`
- Native fetch:
  - use tool `web_fetch(url=...)`

### Docker services

- **searxng**
  - Image: `searxng/searxng:latest`
  - Container: `searxng`
  - Port: `18803 -> 8080`
  - URL(s):
    - `http://192.168.153.113:18803`
    - `http://192.168.153.117:18803`
  - API: JSON enabled (`search.formats` includes `html,json`)
  - Runtime env: `SEARXNG_URL=http://192.168.153.113:18803` (workspace `.env`)
  - Role: preferred local-first search backend
  - Smoke test:
    - `skills/searxng-local-search/scripts/smoke.sh openclaw`

- **whisper-server**
  - Image: `ghcr.io/ggml-org/whisper.cpp:main`
  - Container: `whisper-server`
  - Port: `18801 -> 8080`
  - Health: healthy
  - URL(s):
    - `http://192.168.153.113:18801`
    - `http://192.168.153.117:18801`

- **brave-search (MCP)**
  - Image: `mcp/brave-search:latest`
  - Container: `brave-search`
  - Port: `18802 -> 8000`
  - URL(s):
    - `http://192.168.153.113:18802`
    - `http://192.168.153.117:18802`
  - MCP endpoint: `http://192.168.153.113:18802/mcp`
  - Note: Will confirmed Brave search port is `18802` on 2026-03-10.
  - Verified 2026-03-10: reachable via `mcporter` as tool `brave_web_search`.
  - Native Brave Search API (`web_search`) configured on 2026-03-10.
  - Plan/rate note: Brave free plan hit `rate_limit: 1`; serialize requests instead of parallel bursts.

### Embeddings (local)

- Runtime: Ollama
- Active model: `nomic-embed-text:latest`
- Model id: `0a109f422b47`
- Size: `595 MB`
- Processor: `100% GPU`
- Context: `2048`
- Loaded until: `Forever`
- Ollama embeddings endpoint: `http://192.168.153.113:18807`
- OpenClaw memory search: configured to use provider `ollama` with model `nomic-embed-text`
- OpenClaw memory index verified working on 2026-03-10 (`45 files`, `160 chunks`, vector dims `768`)

### Object storage (assistant bucket)

- Provider: MinIO
- Endpoint: `http://192.168.153.253:9000`
- Bucket: `zap`
- Credentials file: `~/.openclaw/credentials/minio-zap.env` (mode `600`)
- Backup script: `scripts/backup-to-minio.sh`
- Backup scope: full archive of `~/.openclaw` (tar.gz) + `sha256` + `manifest.txt`
- Backup schedule: system cron every 6 hours at minute 17
  - `17 */6 * * * /home/openclaw/.openclaw/workspace/scripts/backup-to-minio.sh >> /home/openclaw/.openclaw/workspace/memory/minio-backup.log 2>&1`
- Bucket versioning: enabled
- Lifecycle rule (prefix `workspace-backups/`):
  - expire noncurrent versions after 90 days
  - keep 3 newer noncurrent versions
  - expire delete markers enabled

### Kubernetes (homelab)

- Cluster access: available
- Shared namespace: `swarm`
- Kubeconfig: `~/.openclaw/credentials/kubeconfig-swarm.yaml` (mode `600`)
- Usage note: deploy assistant workloads into `swarm`; namespace is shared with other agents
- Cluster profile: small Raspberry Pi cluster — prefer lightweight images, low CPU/memory requests, and minimal replicas by default

### Local custom skills (security-reviewed)

- `skills/swarm-kubectl-safe`
  - Purpose: safe kubectl operations scoped to `swarm`
  - Script: `skills/swarm-kubectl-safe/scripts/kubectl-swarm.sh`
- `skills/whisper-local-safe`
  - Purpose: local whisper-server transcription on LAN only
  - Script: `skills/whisper-local-safe/scripts/transcribe-local.sh`

Why local equivalents were built:
- Candidate ClawHub skills `kubectl` and `faster-whisper-transcribe` were flagged as suspicious by ClawHub/VirusTotal checks.
- We intentionally avoided force-installing flagged skills for safety.
- Decision: use minimal local skills for now; revisit those ClawHub skills later if we perform a manual security review and explicitly approve.

Add whatever helps you do your job. This is your cheat sheet.