pulse-libs/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.

---

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

## Related

- [Agent workspace](/concepts/agent-workspace)
## Tech Stack — Skills Instaladas (2026-05-19)

| Skill | Versão | Uso |
|-------|--------|-----|
| agent-browser-clawdbot | 0.1.0 | Automação de browser headless com accessibility tree |
| multi-search-engine-2-0-1 | 1.0.0 | Busca em 17 motores (8 CN + 9 Global) |
| redis-labs-integration | 1.0.2 | Redis Labs via API |
| self-improvement | 1.0.0 | Log de erros e aprendizados (self-improvement) |
| nova-self-improver | 1.0.0 | Sistema de auto-melhoria completo (4 camadas) |
| vision | 3.5.0 | Processamento de imagens, resize, watermark |
| **typescript** | **1.0.2** | **TS seguro: genéricos, narrowing, strict mode, satisfies, utility types, declarations** |
| **e2e-testing-patterns** | **1.0.0** | **Playwright/Cypress — pirâmide de testes, seletor estável, testes determinísticos** |
| **xcloud-docker-deploy** | **1.2.1** | **Deploy Docker multi-stack (PHP, Python, Node, NextJS, Laravel, Go, Rust) + GitHub Actions** |
| **openclaw-config** | **0.1.0** | **Edição segura do openclaw.json via config.schema, $include modular, validação strict** |
| **openclaw-power-ops** | **1.0.0** | **CLI OpenClaw completo: channels, agents, models, security audit, gateway admin** |
| **gitea-api** | **1.0.0** | **API Gitea: autenticação, tokens, repos, issues, webhooks — 5 métodos de auth** |



## Clawhub CLI — caminho do binário

- **Caminho completo:** `/var/lib/openclaw/tools/node/npm/bin/clawhub`
- **NÃO está no PATH global** — sempre usar caminho absoluto
- Comandos: `search`, `install`, `inspect`, `explore`, `update`, `list`
- Licença dos skills: MIT-0 (free, sem atribuição obrigatória)

### Quick Install
```bash
/var/lib/openclaw/tools/node/npm/bin/clawhub install <slug>   --workdir /root/.openclaw/workspace --dir skills
```


---

## 🖥️ Browser Automation — agent-browser (headless Chromium)

CLI baseado em Chromium com **snapshot → @refs → interação**. Ref lifecycle: refs são invalidados após navegação/DOM change — sempre re-snapshotar.

### Fluxo padrão
```bash
# 1. Navegar
agent-browser open https://exemplo.com

# 2. Snapshot (descobre elementos interativos com @refs)
agent-browser snapshot -i
# output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

# 3. Interagir
agent-browser fill @e1 "user@exemplo.com"
agent-browser fill @e2 "senha123"
agent-browser click @e3
agent-browser wait --load networkidle

# 4. Re-snapshot (sempre após mudança de DOM)
agent-browser snapshot -i
```

### Login + persistência de sessão
```bash
agent-browser open https://app.exemplo.com/login
agent-browser fill @e1 "$USER" && agent-browser fill @e2 "$PASS"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save ~/auth.json    # salva cookies/login

# Reutilizar:
agent-browser state load ~/auth.json
agent-browser open https://app.exemplo.com/dashboard
```

### Extrair dados + print
```bash
agent-browser get text body > page.txt
agent-browser get text @e5
agent-browser screenshot paginateste.png
agent-browser screenshot --full     # página inteira
agent-browser pdf relatorio.pdf
```

### Sessões paralelas
```bash
agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com
agent-browser session list
```

### Segurança (ambiente)
```bash
export AGENT_BROWSER_ALLOWED_DOMAINS="exemplo.com"   # domínios permitidos
export AGENT_BROWSER_MAX_OUTPUT=50000                # limite de saída
export AGENT_BROWSER_CONTENT_BOUNDARIES=1            # segurança AI
```

---

## 🔒 Security Audit — skill-security-audit

**Princípio**: análise **read-only**. Use APENAS quando o usuário explicitamente pedir análise de segurança.

### Severidade
| Nível | Impacto |
|-------|---------|
| Critical | RCE, exfiltração de dados, instruction override |
| High | Leitura/modificação de dados sensíveis, bypass de ACL |
| Medium | Dados limitados, engano de usuário |
| Low | Impacto mínimo |

### Categorias de vulnerabilidade
- **Hardcoded Secrets** — `API_KEY`, `PASSWORD`, credenciais em código
- **Injection** — SQLi, XSS, Command Injection, SSRF
- **Access Control** — IDOR, missing function-level AC
- **LLM/Prompt Safety** — injection, output injection, execução arbitrária
- **Privacidade** — vazamento de PII para logs/APIs externas

### Skill & SKILL.md review checklist
- ✓ Sem `instruction override` (ex: "Ignore previous instructions...")
- ✓ Sem exfiltração de dados (enviar dados para URL externa)
- ✓ Sem falsas claims de privilégio
- ✓ Sem conteúdo escondido (base64, zero-width chars)
- ✓ Tool usage seguro (sem `eval(user_input)`, sem writes em `/etc/*`)
- ✓ Sem engano (não dizer que é humano)
- ✓ Scoped ao propósito declarado

---

## 🗄️ Banco de Dados — SQL (PostgreSQL / MySQL / SQLite)

### Comandos essenciais
```bash
# SQLite (setup rápido)
sqlite3 arquivo.db                       # modo interativo
sqlite3 arquivo.db -header -column       # com cabeçalhos
sqlite3 arquivo.db "SELECT * FROM t LIMIT 5;"  # one-liner
sqlite3 arquivo.db ".tables"             # listar tabelas
sqlite3 arquivo.db ".schema t"           # ver estrutura
sqlite3 arquivo.db ".import dados.csv t" # importar CSV

# PostgreSQL
psql "postgresql://user:pass@host:5432/db?sslmode=require"
psql -h host -U user -d db -c "SELECT NOW();"
psql -h host -U user -d db -f migration.sql

# MySQL
mysql -h host -u user -p db
mysql -h host -u user -p db < script.sql
```

### Padrões recomendados
- `UUID` PRIMARY KEY para sistemas distribuídos
- CHECK constraints para valores válidos
- JSONB + GIN index no PostgreSQL para dados semi-estruturados
- Partial indexes para reduzir tamanho
- Triggers para auto-update de `updated_at`

### Otimização
- `EXPLAIN ANALYZE` antes de otimizar query
- Medir antes e depois de cada index
- Evitar SELECT * em produção

---

## 📁 File Management + Analysis

### file (organização digital)
- **Organização por contexto**: busca por tipo de arquivo, projeto, data
- **Naming conventions**: data + nome específico + versão (`YYYY-MM-DD_doc_v2.pdf`)
- **Estrutura de pastas**: não movo nada sem você aprovar primeiro

### file-summary (análise de documentos)
Suporte a extração e resumo de múltiplos formatos:
- **Entrada**: `.txt`, `.docx`, `.pdf`, `.xlsx`, `.xls`
- **Trigger**: "ajude a resumir [arquivo]", "analise [documento]"
- **Output**: resumo estruturado em português/inglês

---

## 🧠 Sistema de Memória — Gitea Roberto/pulse-* (2026-05-20)

Repositórios que o agent Pulse usa como memória persistente de curto e longo prazo.

### 4 repositórios ativos
| Repo | Propósito |
|------|-----------|
| `pulse-memory` | Memórias diárias + LEARNINGS + ERRORS + PATTERN_COUNTER — o cérebro do agente |
| `pulse-skills` | Skills organizadas por domínio (devops / testing / frontend / backend / ai / infra) |
| `pulse-docs` | Guias, runbooks, architecture docs, ADRs |
| `pulse-projects` | Rastreador de projetos (`pulse-libs/`, `infra/`, `past/`, `waits/`) |

### Credenciais Gitea
- **Domínio**: `https://git.octal.tec.br`
- **Usuário**: `Roberto` (`betotn91@gmail.com`)
- **Token API**: `d7378a3d0b7fd38050c4bce6accfd28086b6174c` — scopes=all, nome=pulse-agent-token
- **Admin stack**: `octal` — senha gerenciada por `gitea admin user change-password`
- **SSH**: `ssh-ed25519` em `~/.ssh/id_ed25519_gitea`

### Política de commit
- Fim de cada sessão: `memory/` e `context/` são commitados para `pulse-memory`
- Instalação/remoção de skill: commit de `skills/` → `pulse-skills`
- Novo projeto: commit → `pulse-projects`
- Cadência: **1 push por sessão** (não commit a cada passo)

---

## 🐳 Docker Swarm — octal.tec.br (2026-05-20 inventariado)

### Acesso
- **Portainer CE**: https://dock.octal.tec.br — stack `dock`
- **Admin token PTR**: `ptr_ZE3R0WgRB07W7moQ7rpX135MqZ+F8OMuYC9U7Rqa5dU=`
  - Prefixo `ptr_` = Portainer Access Token — válido para `/api/status` (200)
  - 401 em `/api/endpoints` e `/api/auth` — escopo reduzido, não é JWT admin pleno
  - Senha admin real necessária para operações de mutação (login via POST `/api/auth`)
- **Portas portainer**: `8000/tcp`, `9000/tcp`, `9443/tcp` (dentro do swarm)
- **Agent Portainer**: `io.portainer.agent=true` label — obrigatório em cada node Swarm

### Stack 9 stacks (22 containers)
| Stack | Svc | Portas externas |
|---|---|---|
| `bot` | 2 | — |
| `code` | 1 | — |
| `database` | 2 | — |
| `design` | 7 (Penpot) | 1080→mailcatch |
| `dock` | 2 | 80/443 (ports abertas no node) |
| `git` | 1 | 22/3000 |
| `pro` | 2 | — |
| `projects` | 3 | ⚠️ `pulse-libs` 0/1 |
| `proxy` | 2 | 80→80, 443→443 |

### Domínios Caddy (auto-proxy)
| Domínio | Stack | Service | Porta |
|---|---|---|---|
| `dock.octal.tec.br` | dock | dock_portainer | 9443/9000 |
| `git.octal.tec.br` | git | git_gitea | 3000 |
| `ai.octal.tec.br` | bot | bot_beebot | 18789 |
| `manager.octal.tec.br` | pro | pro_leantime | 8080 |
| `games.octal.tec.br` | projects | projects_games-demo | 80 |
| `test.octal.tec.br` | proxy | proxy_test-octal | — |

### Redes Overlay
`10.0.0.0/8` subdividido em /24 por stack: ingress, public, dbn, mongo-cluster, pro_leantime_net, design_internal, proxy_proxy-net

### Comandos úteis
```bash
docker stack ls
docker service ls
docker network inspect <id>
docker service inspect <nome> --format '{{json .Config.Labels}}'
```

### ⚠️ Portainer API Notas
- Access token `ptr_*` ≠ JWT admin completo — validar okrespo no UI
- Senha admin no Portainer deve ser trocada periodicamente — não documentada no pulse-memory
- Mutação de stacks: usar Portainer UI ou `docker stack deploy` diretamente (não alterar arquivos de config em containers Alpine — não tem editor)