# 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.

---

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

## Local Setup (Ignacio)

### Bitwarden

- `bw-sync` → carga `BW_SESSION` desde `~/.bw/session`.
- `bw-unlock` → desbloquea vault y refresca sesión (usa master password configurada localmente).
- Para leer secretos puntuales: `bw get password "<nombre>"`.

### AI Wrappers

- `g "prompt"` → Gemini CLI (útil para planning, segunda opinión y análisis).
- `c "prompt"` → Codex en modo seguro (sandbox read-only, sin red).
- `cn "prompt"` → Codex con acceso total/red (útil para git clone, etc.).

### CLI Backends for OpenClaw

- `codex-cli` → backend principal para tareas de código y cambios importantes.
- `gemini-cli` → backend auxiliar para planning, contraste de ideas, análisis largo y tareas con mucho contexto.
- `deepseek-code` → backend barato auxiliar para propuestas rápidas y exploración.
- `kimi` → backend Moonshot Kimi K2.5 (200k contexto, créditos ~$10). CLI directo: `kimi-openclaw "prompt"`.
- Cuando se pidan estos nombres, tratarlos como **backends de OpenClaw** (no como comandos shell literales tipo `codex-cli --help`).
- Si `codex-cli` necesita ejecutarse fuera de un repo real, usar un scratch repo temporal (`mktemp` + `git init`) y correrlo vía `bash` con PTY.
- Cuando se pida `gemini-cli`, no usar el skill interno `gemini`; usar el backend configurado de OpenClaw que corre Gemini en modo one-shot con `-p`.
- Si el humano pide probar uno de estos backends, no responder `OK` sin una ejecución real y una salida real del tool/proceso.
- Si el humano pide usar varios backends en paralelo, ejecutar una llamada separada por backend. No meter todo en un solo comando shell gigante.
- Para sitios de prueba, crear una carpeta separada por backend, levantar un servidor separado por puerto, y desplegar cada uno con `pipo-deploy` por separado.
- Si ya existe una skill local conocida para el flujo pedido, no hacer preflight con `cd && ls` o `ls skills`; leer la `SKILL.md` conocida directamente.
- Para la orquestacion de previews en paralelo, usar directamente `skills/parallel-preview-orchestrator/SKILL.md`.
- En Telegram/direct chat, preferir orquestacion via subagente runtime: `sessions_spawn` con `runtime: "subagent"` y el `agentId` del worker.
- Workers disponibles para `sessions_spawn runtime="subagent"`: `codex`, `gemini`, `claude`, `deepseek-code`, `kimi`, `clawrouter`. Confirmar con `agents_list` antes de spawnar.
- Despues de spawnar un subagente, usar `subagents list` para ver estado, `subagents steer` para enviarle seguimiento, y `subagents kill` para cancelarlo.
- Para observar el historial de un worker: `sessions_history` con la `childSessionKey` devuelta por `sessions_spawn`.
- ACP (`runtime: "acp"`) sigue disponible para harnesses externos (codex-acp, gemini-acp); usarlo solo cuando se necesite el harness ACPX con modelo nativo, no para orquestacion general.
- No pedir ACP thread-bound en Telegram/direct chat: ese canal no tiene hooks de thread binding.
- `deepseek-code` disponible como subagente runtime (`agentId: "deepseek-code"`); usar `sessions_spawn runtime="subagent"` — ya no hace falta worker en background separado.
- Para la skill de previews en paralelo, se puede combinar: spawnar un subagente por branch y monitorear con `subagents list`.
- **CLI backend session transcripts**: Los backends CLI (kimi, gemini, claude, deepseek-code) ahora escriben su output al JSONL de sesión al completar (parche runtime de emergencia en dist bundles).
- Runbook detallado: `~/.openclaw/workspace/cli-subagent-transcript-fix-runbook.md`.
- Script de reaplicación post-update: `~/.openclaw/workspace/scripts/reapply_subagent_transcript_fix.py`.
- Motivo: updates de OpenClaw pueden reemplazar `dist/*.js` y borrar hotfixes locales.

### gog (Google Workspace — READ ONLY)

- Auth: `ignaciolagosruiz@gmail.com`, services: `gmail, calendar, drive` (read-only).
- Keyring passphrase: stored as `GOG_KEYRING_PASSWORD=openclaw` in `~/.bash_aliases` (auto-loaded).
- Account shortcut: `GOG_ACCOUNT=ignaciolagosruiz@gmail.com` also in `~/.bash_aliases`.
- Google Cloud project: "pipo-gmail-readonly", Desktop app OAuth client.
- APIs enabled: Gmail, Calendar, Drive, People.
- **NEVER use `--services contacts`** — it adds `directory.readonly` scope which Google blocks for personal accounts (`invalid_request`). Use `people` instead if contacts are needed.
- Re-auth if tokens expire: `gog auth add ignaciolagosruiz@gmail.com --services gmail,calendar,drive,people --readonly --manual`
- Examples: `gog gmail search 'newer_than:7d' --max 10`, `gog calendar events primary --from 2026-03-05 --to 2026-03-12`
- **Read-only. Never attempt write/send/delete operations.**

### summarize

- The steipete `summarize` binary is macOS-only and won't run on this ARM64 Linux VPS.
- Wrapper at `/home/ubuntu/.local/bin/summarize` delegates to `gemini -p` instead.
- Works for URLs, YouTube, articles. Flags `--length short|medium|long` supported.

### Notion

- API key (internal integration token) stored at `~/.config/notion/api_key` (chmod 600).
- To use a page/database: open it in Notion → "..." → "Connect to" → your integration name. Otherwise Pipo won't see it.
- Key starts with `ntn_`. Skill uses Notion API `2025-09-03`.
- Good for: saving session notes, agent memory, decisions, project tracking.

### Entorno y contexto

- Inyección de claves automática al abrir shell desde `~/.openclaw/openclaw.json`.
- Centro de operaciones: `~/.openclaw/workspace/ops/docker-cli-stack`.
- Source of truth operativo adicional: `~/.openclaw/workspace/MEMORIES.md`.
- Si una herramienta dice `API Key missing`: `source ~/.bashrc && bw-sync`.

### Scraping geo-sensible (Argentina)

- Para scraping o login de sitios argentinos sensibles a geolocalización, WAF o reputación de IP (por ejemplo Coto, Carrefour, DÍA y similares), asumir que puede hacer falta salida con IP argentina.
- Cuando haga falta egress argentino, usar Tailscale con el `Pixel 6a` como exit node preferido.
- No asumir que la IP actual de la VPS sirve para estos flujos; verificar si el sitio bloquea o desafía la navegación antes de insistir.
- Si aun con Tailscale + `Pixel 6a` el sitio bloquea, reportarlo explícitamente y pasar a un plan alternativo (por ejemplo navegador/dispositivo real, captura desde el teléfono, o flujo no-headless).

### Chrome Extension (Browser Control)

- The OpenClaw Chrome extension lets Pipo control **your real Chrome browser** (with existing logged-in sessions) instead of the headless `openclaw` profile.
- How it works: extension runs in Chrome on your local machine → relays via `http://127.0.0.1:18792` → Gateway connects through Tailscale.
- To install: run `openclaw browser extension install` on the VPS to get the extension path, then load it unpacked in Chrome (chrome://extensions → Developer mode → Load unpacked).
- Before first use: open extension Options, set port to `18792` and Gateway token to match `OPENCLAW_GATEWAY_TOKEN` in the systemd service.
- Once installed: use `profile="chrome"` in browser tool calls. Attach/detach tabs via the toolbar button — Pipo only controls tabs you explicitly attach.
- **When to use `chrome` vs `openclaw`:**
  - `chrome` → sites that need your real logged-in session (e.g. Gmail, banking, Argentine supermarkets with geo/session checks)
  - `openclaw` → headless automation tasks where login state doesn't matter
- Security: keep Gateway on tailnet only; don't expose relay port 18792 publicly.

### Deploy / Preview

- La raiz `https://miopenclaw-vnic.tail9799d2.ts.net/` queda reservada para OpenClaw.
- Puertos disponibles para apps: `3001-3010` (3000 reservado por Tailscale).
- Exponer servicio al tailnet sin romper OpenClaw: `pipo-deploy <puerto> [nombre]`.
- Ruta preview por defecto: `pipo-deploy 3001 demo` -> `https://miopenclaw-vnic.tail9799d2.ts.net/preview/demo/`.
- Ruta anidada por agente/sitio: `pipo-deploy 3001 codex/json-inspector` -> `https://miopenclaw-vnic.tail9799d2.ts.net/codex/json-inspector/`.
- Para retirar una ruta, usar el mismo identificador: `pipo-undeploy demo` o `pipo-undeploy codex/json-inspector`.
- Si una app tiene sub-secciones, deben vivir debajo de la ruta base publicada.
- Remover preview: `pipo-undeploy <nombre>`.