@justmpm/comunicate 0.1.4 → 0.2.0

package/AGENTS.md

@@ -1,45 +1,36 @@
-# @justmpm/comunicate - Guia Completo
+# @justmpm/comunicate - Guia Completo para Agentes
 
-Sistema de Comunicação Entre Agentes usando arquivos JSON locais (File-Based Architecture) otimizado para Windows.
+Sistema de Comunicação Entre Agentes usando arquivos JSON locais (File-Based Architecture).
 
 ---
 
 ## 📋 Índice
 
-1. [Visão Geral](#visão-geral)
+1. [Conceitos Fundamentais](#conceitos-fundamentais)
 2. [Arquitetura](#arquitetura)
-3. [Instalação](#instalação)
-4. [Configuração](#configuração)
-5. [Tools MCP](#tools-mcp)
+3. [Tokens](#tokens)
+4. [Domínios](#domínios)
+5. [Claims](#claims)
 6. [Fluxos de Trabalho](#fluxos-de-trabalho)
-7. [CLI](#cli)
-8. [Exemplos](#exemplos)
-9. [Segurança](#segurança)
-10. [Troubleshooting](#troubleshooting)
+7. [Todas as Tools](#todas-as-tools)
+8. [Exemplos Completos](#exemplos-completos)
+9. [Troubleshooting](#troubleshooting)
 
 ---
 
-## Visão Geral
+## Conceitos Fundamentais
 
-O **@justmpm/comunicate** é um servidor MCP (Model Context Protocol) que permite comunicação entre múltiplos agentes através de arquivos JSON locais.
+### O que é este sistema?
 
-### Por que File-Based?
+O **@justmpm/comunicate** permite que múltiplos agentes (IAs, scripts, processos) trabalhem juntos no mesmo projeto sem conflitos, através de:
 
-- ✅ **Zero dependências** - Sem banco de dados ou servidor externo
-- ✅ **Portátil** - Viaja com o projeto (controle de versão)
-- ✅ **Debug fácil** - Arquivos JSON human-readable
-- ✅ **No-lock** - Cada agente escreve apenas no seu próprio arquivo
-- ✅ **Otimizado Windows** - File system nativo
+- **Mensagens**: Comunicação assíncrona entre agentes
+- **Domínios**: Separação de responsabilidades por pasta
+- **Claims**: Reserva de arquivos compartilhados
 
-### Conceitos Fundamentais
+### Metáfora
 
-| Conceito | Descrição |
-|----------|-----------|
-| **Agente** | Entidade que pode enviar/receber mensagens |
-| **Inbox** | Caixa de entrada exclusiva de cada agente |
-| **Domínio** | Diretórios que um agente pode editar naturalmente |
-| **Claim** | Reserva temporária de arquivo fora do domínio |
-| **Heartbeat** | Sinal de vida do agente |
+> Imagine uma sala de equipe onde cada pessoa tem seu próprio quadro de avisos (inbox). Você só escreve no seu quadro, mas pode ler os dos outros. Para escrever no quadro de outra pessoa, você precisa pedir permissão (claim).
 
 ---
 
@@ -48,160 +39,229 @@ O **@justmpm/comunicate** é um servidor MCP (Model Context Protocol) que permit
 ```
 .comunicate/
 ├── registry/
-│   ├── agents.json       # Registro de agentes (com heartbeat)
-│   ├── tasks.json        # Tarefas
-│   └── claims.json       # Arquivos reservados (com sequence)
+│   ├── agents.json       # Registro de agentes e tokens
+│   ├── tasks.json        # Tarefas do sistema
+│   └── claims.json       # Arquivos reservados
 ├── messages/
-│   ├── inbox-*.json      # Caixas de entrada
-│   └── archive/          # Mensagens arquivadas (gzip)
+│   ├── inbox-*.json      # Caixa de entrada de cada agente
+│   └── archive/          # Mensagens antigas (gzip)
 └── context/
     ├── api-contracts.json
     ├── decisions.json
     └── progress.json
 ```
 
-### Metáfora
+---
+
+## Tokens
+
+### Admin Token
+
+- Configurado na variável de ambiente `COMUNICATE_ADMIN_TOKEN` no arquivo de configuração do MCP
+- Usado para validar operações administrativas: `create_agent`, `list_agents`, `get_inactive_agents`, `get_all_claims`
+- **Função de Segurança**: Garante que apenas o administrador do sistema possa gerenciar agentes e ver informações sensíveis
+- Quando uma tool de admin é chamada, o adminToken passado é comparado com o configurado no sistema
+- Se não corresponder, a operação é negada
+
+**IMPORTANTE:**
+- Apenas o administrador deve usar tools de admin
+- Agentes normais não devem ter acesso ao adminToken
+- O adminToken protege contra criação não autorizada de agentes
+
+### Agent Token
+
+- Gerado pelo `create_agent` quando um admin cria um novo agente
+- **CADA AGENTE TEM SEU PRÓPRIO TOKEN ÚNICO**
+- Usado em TODAS as operações do agente (enviar mensagens, fazer claims, etc.)
+- **GUARDE O TOKEN!** Não será mostrado novamente
+
+### Diferença entre os Tokens
 
-> É como uma sala de equipe onde cada pessoa tem seu próprio quadro de avisos. Você só escreve no seu quadro, mas pode ler os dos outros. Se precisar escrever no quadro de outra pessoa, você precisa pedir permissão (claim).
+| Aspecto | Admin Token | Agent Token |
+|---------|-------------|-------------|
+| **Quem tem** | Apenas administrador | Cada agente tem o seu |
+| **Para que serve** | Gerenciar o sistema | Operações do agente |
+| **Onde é configurado** | Variável de ambiente | Gerado pelo create_agent |
+| **Tools que usa** | create_agent, list_agents, etc. | send_agent_message, claim_file, etc. |
 
 ---
 
-## Instalação
+## Domínios
 
-Escolha uma das três opções:
+### O que são?
 
-### Opção 1: npx (Recomendado - Sem Instalar)
+Domínios são pastas onde um agente pode editar arquivos **naturalmente**, sem precisar reservar (fazer claim).
 
-Execute diretamente sem instalar:
+### Exemplo Prático
 
-```bash
-npx -y @justmpm/comunicate
 ```
+Agente Frontend criado com:
+  domains: ["src/components", "src/pages"]
 
-Para configurar no Claude Desktop:
-
-```json
-{
-  "mcpServers": {
-    "@justmpm/comunicate": {
-      "command": "npx",
-      "args": ["-y", "@justmpm/comunicate"],
-      "env": {
-        "COMUNICATE_ADMIN_TOKEN": "seu-token-aqui"
-      }
-    }
-  }
-}
+Resultado:
+  ✅ Pode editar: src/components/Button.tsx
+  ✅ Pode editar: src/components/Header/index.tsx
+  ✅ Pode editar: src/pages/Home.tsx
+  ❌ NÃO pode editar: src/api/users.ts
+  ❌ NÃO pode editar: src/types/api.ts
 ```
 
-### Opção 2: Instalação Global
+### Por que usar domínios?
 
-Instale uma vez e use em qualquer projeto:
+1. **Segurança**: Agentes só tocam em arquivos de sua responsabilidade
+2. **Eficiência**: Sem necessidade de claims para arquivos próprios
+3. **Organização**: Separação clara de responsabilidades
 
-```bash
-npm install -g @justmpm/comunicate
-```
+---
 
-Configure no Claude Desktop:
+## Claims
 
-```json
-{
-  "mcpServers": {
-    "@justmpm/comunicate": {
-      "command": "comunicate",
-      "env": {
-        "COMUNICATE_ADMIN_TOKEN": "seu-token-aqui"
-      }
-    }
-  }
-}
-```
+### O que é um Claim?
+
+Um **claim** é uma reserva temporária de um arquivo fora do domínio do agente.
 
-> Após instalar globalmente, o comando `comunicate` estará disponível no PATH.
+### Quando usar?
 
-### Opção 3: Desenvolvimento (Clone Local)
+- Arquivos compartilhados (ex: `src/types/api.ts`)
+- Configurações globais
+- Arquivos de definição compartilhados
 
-Para desenvolver ou modificar o código:
+### Ciclo de Vida de um Claim
 
-```bash
-git clone https://github.com/justmpm/comunicate.git
-cd comunicate
-npm install
-npm run build
+```
+1. Agente tenta editar arquivo fora do domínio
+2. can_edit_file retorna erro
+3. Agente faz claim_file
+4. Arquivo é reservado por X minutos
+5. Agente edita o arquivo
+6. Agente libera com release_file (ou deixa expirar)
 ```
 
-Configure apontando para o arquivo local:
+### Regras Importantes
 
-```json
-{
-  "mcpServers": {
-    "@justmpm/comunicate": {
-      "command": "node",
-      "args": ["C:/caminho/completo/para/comunicate/dist/mcp-server.js"],
-      "env": {
-        "COMUNICATE_ADMIN_TOKEN": "seu-token-aqui"
-      }
-    }
-  }
-}
-```
+| Regra | Descrição |
+|-------|-----------|
+| Exclusividade | Apenas um claim por arquivo |
+| Expiração | Claims expiram automaticamente |
+| Renovação | Só pode renovar quando faltarem < 5 min |
+| Liberação | Opcional mas recomendada |
 
 ---
 
-## Configuração
+## Fluxos de Trabalho
 
-### 1. Gerar Token de Admin
+### Fluxo 1: Setup Inicial (Admin)
 
-Se não tiver um token, gere um:
+```
+1. Gerar token admin (32 caracteres hex)
+2. Configurar no mcp.json do Claude Desktop
+3. Criar agentes com create_agent
+4. Distribuir tokens para cada agente
+```
 
-```powershell
-# PowerShell (32 caracteres hex)
--join ((48..57) + (97..102) | Get-Random -Count 32 | ForEach-Object { [char]$_ })
+### Fluxo 2: Comunicação entre Agentes
 
-# Ou via CLI (se instalado globalmente)
-comunicate generate-token
 ```
+Agente A (Backend)                    Agente B (Frontend)
+     │                                         │
+     │  1. Envia mensagem                      │
+     ├────────────────────────────────────────>│
+     │     send_agent_message                  │
+     │     (tokenA → "frontend")               │
+     │                                         │
+     │                               2. Lê inbox
+     │<────────────────────────────────────────┤
+     │                                         │
+     │                               get_agent_messages
+     │                               (tokenB)
+```
+
+### Fluxo 3: Edição de Arquivos
 
-### 2. Configurar no Claude Desktop
+```
+Agente precisa editar src/types/api.ts:
 
-Edite `%APPDATA%\Claude\settings.json` com uma das opções acima.
+PASSO 1: Verificar permissão
+  can_edit_file(token, "src/types/api.ts")
+  → Retorna: ❌ "File not in agent domains"
 
-> ⚠️ **IMPORTANTE**: Use barras normais (`/`) ou duplas barras invertidas (`\\`) nos caminhos Windows.
+PASSO 2: Reservar arquivo
+  claim_file(token, "src/types/api.ts", 30, "Adicionando tipos")
+  → Retorna: ✅ "Reservado até 2026-02-08T23:30:00Z"
 
-### 3. Reinicie o Claude Desktop
+PASSO 3: Editar arquivo
+  [Edita o arquivo normalmente]
 
-Após configurar, feche e reabra o Claude Desktop.
+PASSO 4: Liberar (opcional mas recomendado)
+  release_file(token, "src/types/api.ts")
+  → Retorna: ✅ "Arquivo liberado"
+```
+
+### Fluxo 4: Renovação de Claim
+
+```
+Situação: Edição está demorando mais que o previsto
+
+1. Verificar tempo restante
+   get_agent_claims(token)
+   → "src/types/api.ts expira em 3 minutos"
+
+2. Renovar (só funciona se < 5 min)
+   renew_claim(token, "src/types/api.ts", 15)
+   → "Claim renovado até 2026-02-08T23:45:00Z"
+```
 
 ---
 
-## Tools MCP
+## Todas as Tools
 
 ### Comunicação
 
-#### `send_agent_message`
+#### send_agent_message
 Envia mensagem para outro agente.
 
+**QUANDO USAR:**
+- Notificar progresso de tarefa
+- Solicitar ajuda
+- Enviar atualizações
+
+**PARÂMETROS:**
+- `token`: Seu token de agente
+- `recipientId`: ID do agente destino
+- `message`: Conteúdo (max 4000 chars)
+- `type`: text | assistance_request | task_update | notification
+- `priority`: low | normal | high | urgent
+
+**EXEMPLO:**
 ```json
 {
-  "token": "token-do-agente",
+  "token": "a1b2c3d4e5f6789012345678abcdef00",
   "recipientId": "frontend",
-  "message": "API pronta!",
+  "message": "API /users pronta!",
   "type": "task_update",
   "priority": "high"
 }
 ```
 
-**Tipos:** `text`, `assistance_request`, `task_update`, `notification`  
-**Prioridades:** `low`, `normal`, `high`, `urgent`
-
 ---
 
-#### `get_agent_messages`
+#### get_agent_messages
 Lê mensagens da inbox.
 
+**QUANDO USAR:**
+- Verificar novas mensagens
+- Processar pendências
+
+**PARÂMETROS:**
+- `token`: Seu token
+- `includeRead`: Incluir mensagens lidas (default: false)
+- `markAsRead`: Marcar como lidas ao ler (default: true)
+- `limit`: Máximo de mensagens (1-50, default: 10)
+
+**EXEMPLO:**
 ```json
 {
-  "token": "token-do-agente",
+  "token": "a1b2c3d4e5f6789012345678abcdef00",
   "includeRead": false,
   "markAsRead": true,
   "limit": 10
@@ -210,283 +270,220 @@ Lê mensagens da inbox.
 
 ---
 
-#### `get_unread_count`
-Retorna número de mensagens não lidas.
+#### get_unread_count
+Conta mensagens não lidas.
 
-```json
-{
-  "token": "token-do-agente"
-}
-```
+**QUANDO USAR:**
+- Verificação rápida sem carregar conteúdo
+- Polling ou notificações
 
 ---
 
-### Claims (Reserva de Arquivos)
-
-#### `claim_file`
-Reserva arquivo fora do domínio para edição.
+#### delete_message
+Deleta mensagem específica.
 
-```json
-{
-  "token": "token-do-agente",
-  "filePath": "src/types/api.ts",
-  "durationMinutes": 30,
-  "reason": "Adicionando tipos da API"
-}
-```
+**QUANDO USAR:**
+- Remover mensagens irrelevantes
+- Limpar spam
 
-> O claim expira automaticamente após o tempo definido.
+**PARÂMETROS:**
+- `token`: Seu token
+- `messageId`: ID da mensagem (formato: msg_xxxxxxxxxxxxxxxx)
 
 ---
 
-#### `renew_claim`
-Renova um claim prestes a expirar (só funciona se faltarem < 5 min).
+#### clear_read_messages
+Remove todas as mensagens lidas.
 
-```json
-{
-  "token": "token-do-agente",
-  "filePath": "src/types/api.ts",
-  "additionalMinutes": 15
-}
-```
+**QUANDO USAR:**
+- Manutenção periódica da inbox
+- Limpar mensagens antigas
 
 ---
 
-#### `release_file`
-Libera um arquivo reservado antes do tempo.
-
-```json
-{
-  "token": "token-do-agente",
-  "filePath": "src/types/api.ts"
-}
-```
+### Claims (Reserva de Arquivos)
 
----
+#### can_edit_file
+**SEMPRE CHAME ESTA TOOL ANTES DE EDITAR QUALQUER ARQUIVO!**
 
-#### `can_edit_file`
-Verifica se pode editar um arquivo (domínio ou claim ativo).
+Verifica se você pode editar um arquivo.
 
-```json
-{
-  "token": "token-do-agente",
-  "filePath": "src/components/Button.tsx"
-}
-```
+**RESULTADOS:**
+- ✅ "Você pode editar" → Arquivo no domínio ou tem claim ativo
+- ❌ "File not in agent domains" → Use claim_file
+- ❌ "File claimed by X" → Aguarde ou peça para liberar
 
 ---
 
-### Administração (requer token de admin)
-
-#### `create_agent`
-Cria novo agente.
+#### claim_file
+Reserva arquivo fora do domínio.
 
-```json
-{
-  "adminToken": "token-admin",
-  "agentId": "backend",
-  "capabilities": ["api", "database", "auth"],
-  "domains": ["src/api", "src/models"]
-}
-```
+**QUANDO USAR:**
+- can_edit_file retornou erro de domínio
+- Precisa editar arquivo compartilhado
 
-**Regras para agentId:**
-- Apenas letras minúsculas, números e hífens
-- Exemplos válidos: `backend`, `frontend-v2`, `test-runner`
+**PARÂMETROS:**
+- `token`: Seu token
+- `filePath`: Caminho do arquivo
+- `durationMinutes`: Tempo de reserva (1-60, default: 15)
+- `reason`: Motivo da reserva (opcional)
 
 ---
 
-#### `list_agents`
-Lista todos os agentes registrados.
+#### renew_claim
+Renova claim prestes a expirar.
 
-```json
-{
-  "adminToken": "token-admin"
-}
-```
+**QUANDO USAR:**
+- Quando faltarem < 5 minutos para expirar
+- Edição está demorando mais que o previsto
+
+**RESTRICAO:**
+Só funciona se faltarem menos de 5 minutos!
 
 ---
 
-#### `get_inactive_agents`
-Lista agentes sem heartbeat (possivelmente "mortos").
+#### release_file
+Libera arquivo reservado antes do tempo.
 
-```json
-{
-  "adminToken": "token-admin",
-  "timeoutMinutes": 5
-}
-```
+**QUANDO USAR:**
+- Terminou de editar antes da expiração
+- Boas práticas: libere assim que terminar
 
 ---
 
-## Fluxos de Trabalho
+#### get_agent_claims
+Lista seus claims ativos.
 
-### Fluxo 1: Criar Agente e Enviar Mensagem
+**QUANDO USAR:**
+- Verificar quais arquivos você reservou
+- Ver quando claims expiram
 
-```
-1. Admin executa: create_agent
-   → Recebe token único do agente
-   
-2. Agente salva seu token
-
-3. Agente A executa: send_agent_message
-   → Mensagem vai para inbox-B.json
-   
-4. Agente B executa: get_agent_messages
-   → Lê e processa mensagens
-```
-
-### Fluxo 2: Coordenação com Claims
-
-```
-Backend (domínio: src/models):
-  ✅ Pode editar: src/models/user.ts
-  ❌ Não pode: src/components/Button.tsx
+---
 
-Frontend (domínio: src/components):
-  ✅ Pode editar: src/components/Button.tsx
-  ❌ Não pode: src/models/user.ts
-
-Quando Frontend precisa editar src/types/api.ts:
-  1. Executa: can_edit_file → false
-  2. Executa: claim_file → success
-  3. Executa: can_edit_file → true
-  4. [edita o arquivo]
-  5. Executa: release_file (ou espera expirar)
-```
+### Administração (requer token de admin)
 
-### Fluxo 3: Monitoramento de Saúde
+#### create_agent
+Cria novo agente.
 
-```
-Cada agente deve:
-  - Chamar qualquer tool periodicamente (atualiza lastSeen)
-  - Ou chamar updateAgentHeartbeat() via código
+**IMPORTANTE:**
+Guarde o token retornado! Não será mostrado novamente.
 
-Admin pode executar:
-  get_inactive_agents → lista agentes "zumbis"
-```
+**PARÂMETROS:**
+- `adminToken`: Token de admin
+- `agentId`: ID único (ex: backend, frontend)
+- `capabilities`: ["api", "auth"]
+- `domains`: ["src/api", "src/models"]
 
 ---
 
-## CLI
+#### list_agents
+Lista todos os agentes.
 
-Se instalou globalmente, use a CLI para administração:
+**QUANDO USAR:**
+- Ver configurações
+- Descobrir agentIds para mensagens
 
-```bash
-# Listar agentes
-comunicate list-agents
+---
 
-# Criar agente
-comunicate create-agent backend
+#### get_inactive_agents
+Lista agentes sem heartbeat.
 
-# Listar claims
-comunicate list-claims
+**QUANDO USAR:**
+- Monitorar saúde do sistema
+- Detectar agentes travados
 
-# Verificar saúde
-comunicate check-health 5
+---
 
-# Gerar token aleatório
-comunicate generate-token
+#### get_all_claims
+Lista todos os claims do sistema.
 
-# Ajuda
-comunicate help
-```
+**QUANDO USAR:**
+- Monitorar uso do sistema
+- Identificar gargalos
 
 ---
 
-## Exemplos
+## Exemplos Completos
 
 ### Exemplo 1: Backend notifica Frontend
 
 ```typescript
 // Backend envia atualização
-const result = sendMessage(
-  BACKEND_TOKEN,
-  'frontend',
-  'API /users pronta! Contrato: { id, name, email }',
-  { type: 'task_update', priority: 'normal' }
-);
+const result = send_agent_message({
+  token: BACKEND_TOKEN,
+  recipientId: "frontend",
+  message: "API /users pronta! Contrato: { id, name, email }",
+  type: "task_update",
+  priority: "normal"
+});
 ```
 
-### Exemplo 2: Frontend reserva arquivo
+### Exemplo 2: Frontend reserva arquivo compartilhado
 
 ```typescript
-// Verifica se pode editar
-const check = canEditFile('frontend', 'src/types/api.ts');
+// 1. Verifica se pode editar
+const check = can_edit_file({
+  token: FRONTEND_TOKEN,
+  filePath: "src/types/api.ts"
+});
+
 if (!check.allowed) {
-  // Reserva arquivo
-  const claim = claimFile(
-    'frontend',
-    'src/types/api.ts',
-    30,
-    'Adicionando tipos'
-  );
+  // 2. Reserva arquivo
+  const claim = claim_file({
+    token: FRONTEND_TOKEN,
+    filePath: "src/types/api.ts",
+    durationMinutes: 30,
+    reason: "Adicionando tipos da API"
+  });
   
   if (claim.success) {
-    // Agora pode editar
-    editFile('src/types/api.ts', ...);
+    // 3. Edita o arquivo
+    editFile("src/types/api.ts", ...);
     
-    // Libera quando terminar
-    releaseFile('frontend', 'src/types/api.ts');
+    // 4. Libera quando terminar
+    release_file({
+      token: FRONTEND_TOKEN,
+      filePath: "src/types/api.ts"
+    });
   }
 }
 ```
 
-### Exemplo 3: Notificações em tempo real
+### Exemplo 3: Agente verifica e processa mensagens
 
 ```typescript
-import { startNotificationListener } from './comunicate/core/notifications';
-
-const listener = startNotificationListener('frontend', {
-  onMessage: (msg) => {
-    console.log(`Nova mensagem de ${msg.senderId}: ${msg.content}`);
+// Verifica se há mensagens novas
+const unread = get_unread_count({ token: AGENT_TOKEN });
+
+if (unread.count > 0) {
+  // Lê e processa mensagens
+  const messages = get_agent_messages({
+    token: AGENT_TOKEN,
+    markAsRead: true,
+    limit: 10
+  });
+  
+  for (const msg of messages) {
+    processMessage(msg);
   }
-});
-
-// ... quando quiser parar:
-listener.stop();
+}
 ```
 
 ---
 
-## Segurança
-
-### Timing-Safe Comparison
-
-Todos os tokens são comparados usando `crypto.timingSafeEqual()` para prevenir timing attacks.
-
-### Token de Admin
-
-- Armazene em variável de ambiente `COMUNICATE_ADMIN_TOKEN`
-- Nunca commite tokens em repositório
-- Use tokens longos e aleatórios (32+ caracteres hex)
-
-### Claims
-
-- Claims expiram automaticamente
-- Só um agente pode ter claim de um arquivo por vez
-- Sequence number previne race conditions
-
-### Domínios
-
-- Defina domínios restritos ao criar agente
-- Agente só edita arquivos dentro de seus domínios sem claim
-
----
-
 ## Troubleshooting
 
 ### "Token inválido"
 
 - Verifique se o token está completo (32 caracteres hex)
-- Confirme que o agente está ativo (`list_agents`)
+- Confirme que o agente está ativo (list_agents)
 - Verifique se há espaços extras
 
 ### "File claimed by X"
 
 - Outro agente já reservou o arquivo
-- Espere expirar ou peça para liberar
-- Use `get_all_claims` (admin) para verificar
+- Espere expirar ou peça para liberar via mensagem
+- Use get_all_claims (admin) para verificar
 
 ### Mensagens não aparecem
 
@@ -494,77 +491,88 @@ Todos os tokens são comparados usando `crypto.timingSafeEqual()` para prevenir
 - Confirme o `recipientId` no envio
 - Verifique o arquivo inbox-*.json manualmente
 
-### File watcher não funciona
+### "File not in agent domains"
 
-- O sistema tem fallback automático para polling
-- No Windows, polling é mais confiável que file watcher
-- Considere usar `startPolling()` explicitamente
+- Arquivo está fora dos domínios definidos no create_agent
+- Use claim_file para reservar o arquivo
 
 ### Permissão negada ao escrever JSON
 
 - Verifique permissões da pasta `.comunicate/`
-- Execute como administrador se necessário
 - Verifique se outro processo está usando os arquivos
 
-### "command not found: comunicate"
+---
+
+## Segurança e Permissões
+
+### Modelo de Segurança
+
+O sistema tem dois níveis de acesso:
 
-Se instalou globalmente mas o comando não é encontrado:
+#### 1. Administrador
+- Tem acesso ao **adminToken** configurado no sistema
+- Pode criar, listar e monitorar agentes
+- Pode ver todos os claims do sistema
+- Não participa diretamente da comunicação entre agentes
 
-```powershell
-# Verifique se o npm global está no PATH
-npm bin -g
+#### 2. Agentes
+- Têm apenas seu **próprio token** (recebido no create_agent)
+- Podem se comunicar entre si via mensagens
+- Podem reservar arquivos fora de seus domínios
+- **NÃO** podem usar tools de admin (create_agent, list_agents, etc.)
 
-# No Windows, pode precisar adicionar ao PATH:
-# %APPDATA%\npm
+### Validação de Acesso
+
+Toda tool de admin valida o adminToken:
+```
+Usuário chama: list_agents(adminToken="abc123...")
+                    ↓
+Sistema compara: adminToken == COMUNICATE_ADMIN_TOKEN?
+                    ↓
+Se SIM → executa a operação
+Se NÃO → retorna "Token de admin inválido"
 ```
 
+Isso garante que apenas quem tem o token de admin configurado no sistema possa gerenciar agentes.
+
+### Por que isso é importante?
+
+Imagine um projeto com múltiplos agentes trabalhando:
+- Se qualquer agente pudesse criar outros, o sistema ficaria caótico
+- O adminToken garante controle centralizado sobre quem pode participar
+- Cada agente opera apenas dentro de suas permissões
+
 ---
 
 ## Dicas
 
-1. **Organize domínios por responsabilidade**
-   - `backend`: `src/api`, `src/models`
-   - `frontend`: `src/components`, `src/hooks`
-   - `shared`: `src/types`, `src/utils` (use claims)
+1. **SEMPRE use can_edit_file antes de editar**
+   - Previne erros de permissão
+   - Identifica necessidade de claim
 
 2. **Renove claims antes de expirar**
-   - Se uma tarefa demorar mais que o previsto
-   - Renove quando faltarem < 5 minutos
+   - Se faltarem < 5 minutos
+   - Evita interrupção no meio da edição
 
 3. **Use prioridades adequadamente**
-   - `urgent`: Bugs críticos, system down
-   - `high`: Features importantes, deadlines
+   - `urgent`: Bugs críticos
+   - `high`: Features importantes
    - `normal`: Comunicação rotineira
-   - `low`: Informações, updates
+   - `low`: Informações
 
 4. **Limpe mensagens lidas periodicamente**
-   - Use `clear_read_messages` para manter inbox limpa
-   - Mensagens antigas são arquivadas automaticamente
-
----
-
-## Referência Rápida
-
-### Criar Agente
-```json
-{"adminToken": "...", "agentId": "backend", "capabilities": ["api"], "domains": ["src/api"]}
-```
+   - Use clear_read_messages
+   - Mantém inbox performática
 
-### Enviar Mensagem
-```json
-{"token": "...", "recipientId": "frontend", "message": "...", "type": "task_update", "priority": "normal"}
-```
+5. **Libere claims ao terminar**
+   - Boas práticas de convivência
+   - Permite outros agentes trabalharem
 
-### Reservar Arquivo
-```json
-{"token": "...", "filePath": "src/types/api.ts", "durationMinutes": 30, "reason": "..."}
-```
-
-### Ler Mensagens
-```json
-{"token": "...", "includeRead": false, "markAsRead": true, "limit": 10}
-```
+6. **Proteja o adminToken**
+   - Apenas o administrador deve usá-lo
+   - Não compartilhe com agentes normais
+   - Configurado uma única vez no mcp.json
 
 ---
 
-**Versão 0.1.0** | Arquitetura File-Based | Otimizado para Windows
+**Versão 0.1.4** | Arquitetura File-Based | Otimizado para Windows