# Octopus — Manual

> Atualizado em 04/10/2026 (versão 1.4). Substitui o manual de julho (`/docs/octopus.md`). O contrato completo da API é gerado do código e fica em `GET /api/v1/contrato`.

## 1. O que é

O Octopus é o agente pessoal do dono. Ele roda 24 horas numa VPS, recebe pedidos pelo painel web, por voz, pelo Telegram, pelo carro e por tarefas agendadas, e os executa com ferramentas reais: navegador e chats de IA (o **Computador**), contêineres isolados, banco, sites de clientes (o **Construtor**), Google, n8n e OSINT.

Ele cumpre quatro funções:
1. **Operar a VPS e os sites** dos clientes, sem derrubar o que já roda.
2. **Ajudar no dia a dia**: pesquisa com fontes, e-mail, agenda, documentos, imagens e voz.
3. **Investigar**: OSINT dentro do escopo autorizado de cada investigação.
4. **Aprender sozinho**: o Cérebro transforma o que o dia ensinou em conhecimento (seção 3).

O princípio que atravessa tudo é **prosa é sugestão, código é garantia**: o que importa é imposto por mecanismo (réguas, testes, decisão humana explícita), não pedido ao modelo.

## 2. Usar no dia a dia

- **Chat.** Escreva no campo de baixo. Trabalho de várias etapas vira **plano**, que espera a sua aprovação logo abaixo da resposta. A conversa aberta se atualiza sozinha, sem F5.
- **Projetos** agrupam conversas, a pasta de trabalho, regras próprias e a biblioteca do projeto. O modo **investigação** isola o contexto.
- **Construtor**: no projeto, o botão 🌐 abre o construtor do site do cliente, com prévia, publicar, tirar do ar e voltar.
- **Avisos**: o sino 🔔 no topo abre o painel de avisos. Aviso novo aparece por alguns segundos como uma pílula. O mesmo aviso não se repete.
- **Computador**: o ícone acende em âmbar quando uma tarefa depende de você (um login, um desafio anti-robô). Clique para ver a tela ao vivo.
- **Voz e carro**: o modo de voz e a central do carro (`/central.html`) usam o mesmo Octopus.

## 3. Cérebro: como o Octopus aprende

Abra pelo 🧠. As abas:

| Aba | O que é |
|---|---|
| **Fila** | Cole um texto ou um link (página, documentação, YouTube) ou envie um PDF. O Octopus classifica (natureza, tema, resumo) e integra sozinho. **Sistema 2:** biblioteca/RAG, doutrina (princípios), memória sobre você e **skills do Octopus**. **Sistema 1:** frases de exemplo por tema, que ensinam o classificador local. |
| **Decisões** | Só o que depende de você (itens do backlog e lições). As falhas técnicas ficam recolhidas abaixo. |
| **Curadoria** | O jeito conversado: trazer um material, ler a devolutiva, conversar sobre ele e persistir. |
| **Doutrina** | Os princípios que guiam o Octopus, globais e por projeto (com teto, para não diluir o prompt). |
| **Ondas** | O ciclo da madrugada (seção 3.1), com os passos de cada noite e o botão **Rodar a onda agora**. |
| **Monitor** | Módulo de intenção sem LLM e atividade ao vivo. |

### 3.1 A Onda do conhecimento (3h, só em PRD)

1. As conversas do dia entram na fila.
2. As falhas que se repetem entram na fila e viram armadilha de procedimento.
3. **Pelo Computador, nos chats de IA** (ChatGPT, Gemini e Claude, revezando, com as suas assinaturas), as skills do Octopus mexidas na semana são revisadas, e a revisão volta para a fila.
4. A fila é processada.
5. O Sistema 1 é retreinado.

Durante o dia, cada pesquisa interpretada e cada página de documentação lida também entram na fila.

### 3.2 Skills do Octopus

O Octopus escreve e atualiza as próprias skills em `data/skills-do-octopus`. As **suas** skills (`.agents/skills`) ele nunca toca. Uma skill com `fixada: true` no cabeçalho não muda mais sozinha. A mesma tarefa é uma skill só, e aprender de novo acrescenta passos.

## 4. Skills e tentáculos

- **Da casa** (`.agents/skills`): as suas e as instaladas (inclui os pacotes do Reversa e do Google Workspace `gws`).
- **Do Octopus**: as que ele escreveu (seção 3.2), marcadas "do Octopus" na lista.
- **Disponibilidade**: skill que exige um programa ou uma variável que não existe na máquina aparece apagada, com o motivo, e não entra no agente. Ela volta sozinha quando o requisito aparecer.
- **Uso**: cada uso é medido. A dica da lista mostra quantas vezes a skill foi usada e quando, ou se nunca foi.

## 5. Modelos e custo

Cada classe de tarefa (Cérebro, Classificação, Resumos, Conversa leve, Raciocínio pesado e outras) tem uma **cadeia** de modelos. A assinatura vem primeiro (custo marginal zero), depois os pagos (OpenRouter, Groq) e o modelo local (Qwen3.5 4B). Em Configurações → Modelos:
- **Quando a assinatura bater no limite**: por classe, seguir pelos pagos ou esperar o reset.
- **Sem crédito no pago**: seguir pela assinatura, pular os pagos ou parar.
- O **disjuntor de gastos** (Configurações → Geral) mostra o gasto do mês e o teto.

## 6. Ambientes e versões

| | HML | PRD |
|---|---|---|
| Endereço | https://hml.octopus.rstecbr.com.br | https://octopus.rstecbr.com.br |
| Função | Onde todo trabalho entra primeiro | O que você usa |

Todo commit em `develop` passa pelo portão no GitHub, sobe em HML, é observado por 5 minutos e **sobe sozinho para PRD**, com aceite que entra com o seu login. Se o aceite reprovar, PRD volta sozinho à versão anterior. A tela **Versões** (`/versoes.html`) mostra cada versão, permite promover à mão e permite **voltar** de versão (decisão humana). Para pausar a subida automática: `touch /root/.octopus-esteira-pausada`.

## 7. API

### 7.1 Autenticação

Todo `/api/` exige `Authorization: Bearer <credencial>`:
- **Sessão do painel**: o token de `POST /api/login` (30 dias). Vale para tudo.
- **Chave de API**: `oct_…`, criada em **Configurações → Integrações → Chaves de API**. Tem escopos, pode expirar e pode ser revogada a qualquer momento. O segredo aparece uma vez só.

| Escopo | Permite |
|---|---|
| `leitura` | Todo GET |
| `chat` | Conversar (`POST /api/chat`) |
| `conhecimento` | Fila do conhecimento e onda |
| `decisoes` | Aprovar ou reprovar planos, responder tarefas paradas |
| `projetos` | Projetos, regras e tarefas agendadas |
| `ambientes` | Promover e voltar versão (decisão humana; `admin` não cobre) |
| `admin` | Todo o resto que altera o Octopus, menos chaves e ambientes |

Chave nunca gerencia chaves: isso é só pela sessão do painel. Chamada fora do escopo recebe `403`, com o escopo que faltou.

### 7.2 Contrato

`GET /api/v1/contrato` devolve o OpenAPI 3.1 **gerado do código**: todas as rotas, cada uma com a descrição e o escopo exigido (`x-escopo`). A régua `api/contrato-cobre-as-rotas` reprova o deploy se uma rota nova nascer sem descrição.

### 7.3 Exemplos

```bash
OCTOPUS=https://octopus.rstecbr.com.br
CHAVE=oct_xxxxxxxx_yyyy...

# conversar (assíncrono): manda e acompanha o turno
curl -s -X POST $OCTOPUS/api/chat -H "Authorization: Bearer $CHAVE" -H 'Content-Type: application/json' \
  -d '{"message":"resuma as decisões pendentes","conversationId":"minha-integracao"}'
curl -s $OCTOPUS/api/chat/turno/<id-do-turno> -H "Authorization: Bearer $CHAVE"

# ensinar
curl -s -X POST $OCTOPUS/api/v1/conhecimento/fila -H "Authorization: Bearer $CHAVE" -H 'Content-Type: application/json' \
  -d '{"entrada":"https://docs.n8n.io/workflows/"}'
```

## 8. MCP: dirigir o Octopus de outro agente

O Octopus é **servidor MCP** em `https://octopus.rstecbr.com.br/api/v1/mcp` (Streamable HTTP). Crie uma chave com os escopos que quer liberar (no mínimo `leitura`; para conversar, `chat`; para aprovar, `decisoes`).

**Claude Code:**
```bash
claude mcp add --transport http octopus https://octopus.rstecbr.com.br/api/v1/mcp \
  --header "Authorization: Bearer oct_xxxxxxxx_yyyy..."
```

**Claude Desktop** (pelo `mcp-remote`, em `claude_desktop_config.json`):
```json
{ "mcpServers": { "octopus": { "command": "npx", "args": ["mcp-remote", "https://octopus.rstecbr.com.br/api/v1/mcp",
  "--header", "Authorization: Bearer oct_xxxxxxxx_yyyy..."] } } }
```

**claude.ai (conectores personalizados)** exige login OAuth, que este servidor ainda não oferece. Por enquanto, use o Claude Code ou o Desktop.

**Ferramentas:** `octopus_conversar`, `octopus_mensagens`, `octopus_conversas`, `octopus_projetos`, `octopus_ensinar`, `octopus_fila_do_conhecimento`, `octopus_decisoes`, `octopus_plano_pendente`, `octopus_aprovar_plano`, `octopus_reprovar_plano`, `octopus_responder_requisicao`, `octopus_ambientes` e `octopus_chamar_api` (qualquer rota do contrato). Cada ferramenta vale só dentro do escopo da chave. Promover e voltar versão não têm ferramenta própria.

## 9. Segurança

- **Arquivos**: o Octopus só escreve nos webroots marcados em Configurações → Integrações → Domínios permitidos (PathGuard).
- **Código gerado** roda em contêiner efêmero, no menor escopo que resolve: `isolated` (sem disco, sem rede), `network`, `project` (a pasta do projeto) ou `project-network`. Não existe escopo "VPS inteira".
- **Skills de terceiros** passam por uma auditoria de sinais perigosos antes de entrar.
- **Segredos** ficam no cofre cifrado; a chave de API guarda só o hash.

## 10. Para quem desenvolve

- Situação, backlog e ciclos: `npx tsx scripts/evolucao.ts` (módulo E, no banco). Grave sempre a partir de `/root/Octopus`.
- Trabalho só em `/root/Octopus-hml` (branch `develop`). Commit e push na hora, com teste, subindo o piso.
- Especificações e histórico de arquitetura: `_reversa_sdd/` (extração do Reversa) e os adendos em `_reversa_sdd/addenda/`.
- Regras do projeto: `CLAUDE.md`.