# TOOLS.md - Local Notes

Environment-specific configs: device names, IPs, accounts, API endpoints.

---

## Gateway Constraints

⚠️ **Cannot restart gateway** - running in Docker container. Always ask Ben to perform gateway restarts when required.

---

## Sub-Agents

Use `sessions_send` to delegate large-context or research tasks. Model: **gemini-3-flash** (1M context).
Avoids blowing up primary agent context. Available to all agents.

## Large Log Safety

- Never `read` huge `*.jsonl` session logs directly.
- Use `scripts/safe-jsonl-peek.sh <file> [max-bytes]` for bounded head/tail inspection.
- For metadata extraction, prefer scripts that enforce file/byte caps (like `scripts/resolve-channel-names.sh`).

---

## Skills

**Shared** (`~/.openclaw/skills/` — all agents):

| Skill | Purpose |
|-------|---------|
| capmetro-monitor | Monitor CapMetro service changes for Route 5 & 550 |
| outline | Search and read Outline wiki documents |
| reminder | Create reminders with proper CST→UTC timezone handling |
| sonoscli | Control Sonos speakers (play, pause, volume, grouping) |

**Main-only** (`workspace/skills/`):

| Skill | Purpose |
|-------|---------|
| exa | Neural/semantic web search via Exa API |
| github-notifications | Check notifications + auto-dismiss nightlies/previews |

---

## Sonos Speakers

| Name | IP | Notes |
|------|-----|-------|
| Ben Office L | 192.168.2.125 | Stereo pair left |
| Ben Office R | 192.168.2.190 | Stereo pair right |
| Patio - Grill | 192.168.2.57 | Wired |
| Patio | 192.168.2.74 | USW Ultra Port 7 |

---

## GitHub CLI

**Account:** b3nw (189466) — `GH_TOKEN` with notifications scope

---

## Search Tools

| Tool | Use Case | Access |
|------|----------|--------|
| `web_search` | General web, news | Built-in (Brave API) |
| Exa | Technical/semantic search | `skills/exa/scripts/search.sh` |

---

## n8n Integration Design Principles

1. **Credential isolation:** n8n manages credentials and scoped external access so broad-scope secrets are not stored in the OpenClaw container.
2. **Logic ownership:** OpenClaw manages projects, reminders, and action/deadline intelligence derived from n8n-provided data.
3. **Directionality:** OpenClaw always initiates flow by polling n8n to kick off workflows (for targeted actions or checking new items to review).

Reference: `docs/integrations/n8n-pattern.md`

---

## Outline Wiki

**URL:** `OUTLINE_URL` env var  
**Token:** `OUTLINE_API_TOKEN` (read-only)  
**Scripts:** `skills/outline/scripts/{search,get-document,list-collections,list-recent}.sh`

**Collections:** Daily Journals, Kids Stuff, Home Stuff, Home Lab, Scratch Pad

---

## CapMetro Transit (GTFS)

⚠️ **Use GTFS for all schedule lookups — no web scraping**

**Download:**
```bash
curl -sL "https://data.austintexas.gov/download/r4v4-vz24/application%2Fx-zip-compressed" -o /tmp/capmetro.zip
unzip -o /tmp/capmetro.zip -d /tmp/capmetro_gtfs
```

**Key files:** `routes.txt`, `stops.txt`, `trips.txt`, `stop_times.txt`

**User's Commute Stops:**
| Route | Stop ID | Name | Direction |
|-------|---------|------|-----------|
| 5 | 964 | Woodrow/Choquette | Eastbound |
| 550 | 5538 | Crestview Station | Southbound |

**Real-time:** `data.austintexas.gov/widgets/cuc7-ywmd` (vehicle positions)

---

## Gitea (Self-Hosted Git)

**URL:** https://gitea.ext.ben.io
**User:** claw
**Email:** claw@ben.io
**Auth:** Git credential store (HTTPS PAT) — pre-configured, no setup needed

**Usage:** Standard git commands work automatically with stored credentials:
```bash
git clone https://gitea.ext.ben.io/claw/<repo>.git
git push origin main
```

**API:** Gitea API v1 is available. Use the stored PAT for API calls:
```bash
# Extract token from credential store
GITEA_TOKEN=$(awk -F'[/:@]' '/gitea.ext.ben.io/{print $6}' ~/.git-credentials)

# List repos
curl -s -H "Authorization: token $GITEA_TOKEN" https://gitea.ext.ben.io/api/v1/user/repos | jq -r '.[].full_name'

# Create repo
curl -s -X POST -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "repo-name", "private": true}' \
  https://gitea.ext.ben.io/api/v1/user/repos
```

**SSH alternative:** `ssh://git.local.ben.io` (not configured; use HTTPS)

---