# 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 en background: delegar a workers/subagentes separados y devolver rapido el control del chat.
- Para esta skill de previews en Telegram/direct chat, no usar `sessions_spawn`; usar workers en background y monitorearlos por process handle.
- Devolver rapido el control del chat con los handles de cada worker para poder pedir status, cancelar o cambiar una sola rama.
- Si el humano pide un subagente real de Codex o Gemini en Telegram/direct chat, usar ACP: `sessions_spawn` con `runtime: "acp"`, `mode: "run"` y `thread: false`.
- No pedir ACP thread-bound en Telegram/direct chat: ese canal no tiene hooks de thread binding.
- `deepseek-code` no corre como harness ACPX real en esta maquina; para DeepSeek, usar un worker en background separado y tratarlo como rama aislada con process handle.

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

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