JaimeJunr · cursor · May 31, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > Próximas fases v0.3.0+: ver [docs/v0.2-roadmap.md](docs/v0.2-roadmap.md) — file watcher, FTS5, dispatch dinâmico, mais frameworks (Spring/Django/Express), session continuity.
 
+### Semana 2026-05-24 — 2026-05-31
+
+Sincronização pós-v0.2.0: correções factuais de documentação, higiene de repositório e estabilidade de CI em macOS.
+
+#### Added
+
+_(nenhuma feature nova de produto nesta janela — entregas principais já documentadas em [0.2.0])_
+
+#### Changed
+
+- Documentação do pipeline `graph`: ranking descrito como heurística (match de termos da query + log₂ de sites + boost por `kind`), não BM25+PageRank; budget de tokens linear nos resultados, não binary search.
+- Contagem de tools do MCP server corrigida para **10** em `README.md` e guias (antes constava 4 em trechos desatualizados).
+- `docs/guides/agent-integration.md`: caminhos do `claude_desktop_config.json` por SO; reinício separado (Claude Code = nova sessão; Claude Desktop = reler config).
+
+#### Removed
+
+- Diretório `.claude/` removido do tracking git (`git rm --cached`); permanece no `.gitignore` — cópias locais intactas.
+
+#### Fixed
+
+- CI macOS: testes de integração `desktop_*` em `tests/agent_install.rs` restritos a Linux (`#[cfg(target_os = "linux")]`) — `dirs::config_dir()` no macOS resolve para `~/Library/Application Support`, não `XDG_CONFIG_HOME`.
+
 ## [0.2.0] - 2026-05-25
 
 Foco: **paridade total nas 5 linguagens prioritárias (Java, Groovy, Ruby, Rust, JS/TS) + framework-aware routing** para Grails, Rails e NestJS. Primeiro passo formal do roadmap para fechar gap competitivo vs CodeGraph.

diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 [![Docs](https://img.shields.io/badge/docs-jaimejunr.github.io%2Fcontext--engine-blue)](https://jaimejunr.github.io/context-engine/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://rustup.rs/)
-[![Tests](https://img.shields.io/badge/tests-282%20passing-green.svg)](#desenvolvimento)
+[![Tests](https://img.shields.io/badge/tests-312%20passing-green.svg)](#desenvolvimento)
 [![Release](https://img.shields.io/github/v/release/JaimeJunr/context-engine)](https://github.com/JaimeJunr/context-engine/releases)
 
 > **Maintainers e AI agents:** leia [`CLAUDE.md`](CLAUDE.md) antes de fazer qualquer mudança.
@@ -74,8 +74,8 @@ O único CLI que cobre **4 eixos competitivos** em um binário Rust único, 100%
 | Busca semântica em docs (RAG local) | ✅ | ❌ | ❌ | parcial (FTS5) | ✅ |
 | Token budget com binary search | ✅ | ❌ | ❌ | ❌ | ❌ |
 | **Grafo de chamadas** (callers/callees/trace/impact) | ✅ | ❌ | ✅ | ❌ | ❌ |
-| **Ranking de relevância em resultados de grafo** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Budget de tokens em outputs de grafo** | ✅ | ❌ | ❌ | ❌ | ❌ |
+| **Ranking de relevância em resultados de grafo** | ✅ (termos + sites + kind) | ❌ | ❌ | ❌ | ❌ |
+| **Budget de tokens em outputs de grafo** | ✅ (corte linear top-ranked) | ❌ | ❌ | ❌ | ❌ |
 | Session continuity (PreCompact) | 🚧 | ❌ | ❌ | ✅ | ❌ |
 | 100% local (sem API externa) | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Single binary Rust nativo | ✅ | ✅ | ❌ (TS) | ❌ (TS) | ❌ (TS) |
@@ -88,8 +88,8 @@ O único CLI que cobre **4 eixos competitivos** em um binário Rust único, 100%
 - **Único** com hook + MCP server + compressão + RAG + repo map + grafo de chamadas no mesmo binário.
 - **Único** com Token Budget via binary search (maximiza arquivos respeitando limite de tokens).
 - **Único** com BM25 + Personalized PageRank híbrido para ranqueamento de repo map.
-- **Único** com **ranking de relevância à query** em resultados de grafo (callers ranqueados por BM25 + número de sites). CodeGraph devolve lista crua sem ranking.
-- **Único** com **budget de tokens em outputs de grafo** — trace/impact respeitam limite. CodeGraph pode estourar contexto.
+- **Único** com **ranking de relevância à query** em resultados de grafo (match de termos + log₂ de sites + boost por kind). CodeGraph devolve lista crua sem ranking.
+- **Único** com **budget de tokens em outputs de grafo** — trace/impact cortam por limite linear nos top-ranked. CodeGraph pode estourar contexto.
 
 **Onde estamos atrás (assumido, com plano):**
 - Cobertura de comandos do `exec` (17 famílias vs 100+ do RTK) — ver [análise](docs/competitors/rtk.md) e roadmap.
@@ -124,7 +124,7 @@ O único CLI que cobre **4 eixos competitivos** em um binário Rust único, 100%
 - **`ctx exec`** — proxy universal: aplica filtros de compressão por família (git, cargo, npm, docker, kubectl, aws, gh, gradle, maven, pytest, etc), persiste métricas.
 - **`ctx graph`** — grafo de símbolos resolvido (callers/callees/trace/impact/node) em 8 linguagens. **Resultados ranqueados** por relevância à query e respeitam token budget.
 - **`ctx install --agent claude-code`** — configura hook PreToolUse (auto-rewrite de `git status` → `ctx exec git status`) **e** MCP server (`ctx_exec`, `ctx_search`, `ctx_map`, `ctx_list`) num único comando idempotente.
-- **`ctx mcp serve`** — MCP server stdio expondo 4 tools com schema JSON gerado via `rmcp` + `schemars`.
+- **`ctx mcp serve`** — MCP server stdio expondo **10 tools** com schema JSON gerado via `rmcp` + `schemars`.
 - **Arquitetura modular** com 3 camadas (`pipelines/`, `integrations/`, `shared/`) preparada para crescer sem virar mono-arquivo.
 
 ## Estrutura do Código
@@ -138,7 +138,7 @@ src/
 │
 ├── integrations/            INTERFACES EXTERNAS
 │   ├── agents/              Hooks + MCP entries (Claude Code, futuros Cursor/Codex)
-│   └── mcp/                 MCP server stdio com 4 tools
+│   └── mcp/                 MCP server stdio com 10 tools
 │
 └── shared/                  UTILITÁRIOS CROSS-CUTTING
     ├── cache.rs             SQLite ~/.cache/context_engine/
@@ -252,7 +252,7 @@ ignore_extra = ["**/fixtures/**"]
 ## Desenvolvimento
 
 ```bash
-cargo test --locked --all-features                       # 282 testes
+cargo test --locked --all-features                       # 312 testes
 cargo clippy --all-targets --all-features -- -D warnings # lint estrito
 cargo fmt -- --check                                     # formatação
 cargo run -- map --help                                  # ajuda dos subcomandos

diff --git a/docs/competitors/codegraph.md b/docs/competitors/codegraph.md
@@ -52,16 +52,16 @@ Roda como **MCP server (stdio)**. Installer interativo configura cada agente aut
 |---|---|---|
 | Grafo de chamadas resolvido | callers/callees/trace/impact com dispatch dinâmico | ✅ callers/callees/trace/impact/node (sem dispatch dinâmico ainda) |
 | Resolução de referências | call→def, import→source, herança, interface→impl | ✅ call→def por nome simples; imports cross-file; sem herança ainda |
-| **Ranking de relevância em resultados** | ❌ lista crua | ✅ BM25(query) + número de sites |
-| **Budget de tokens em outputs de grafo** | ❌ pode estourar contexto | ✅ binary search igual ao `map` |
+| **Ranking de relevância em resultados** | ❌ lista crua | ✅ match de termos + log₂(sites) + boost kind |
+| **Budget de tokens em outputs de grafo** | ❌ pode estourar contexto | ✅ corte linear nos top-ranked |
 | **Dedup de sites de chamada similares** | ❌ | ✅ caller com N sites → 1 entrada + array de sites |
 | MCP server nativo | stdio, 9 tools | stdio, **10 tools** (4 + 6 de grafo) |
-| Framework-aware routing | URL pattern → handler em 14+ frameworks | 🚧 ausente |
+| Framework-aware routing | URL pattern → handler em 14+ frameworks | ✅ parcial (Rails, Grails, NestJS) |
 | Live file watcher | FSEvents/inotify, debounce 2s | 🚧 re-indexação manual via `ctx graph index` |
 | Dispatch dinâmico / herança | sim | 🚧 ausente |
-| Linguagens | 19+ | **7** (TS, Py, Ruby, Go, Rust, Java, Groovy) |
+| Linguagens | 19+ | **8** no grafo (TS, JS, Py, Ruby, Go, Rust, Java, Groovy) |
 | Busca textual | SQLite FTS5 | BM25 in-memory + grafo SQLite |
-| Installer multi-agente | auto-configura 5 agentes | 1 (Claude Code) |
+| Installer multi-agente | auto-configura 5 agentes | 2 (Claude Code, Claude Desktop) |
 
 ## O que `ctx` faz que ele não faz
 

diff --git a/docs/graph/README.md b/docs/graph/README.md
@@ -11,21 +11,21 @@ Diferente do `grep` tradicional, o `ctx graph` entende a semântica do código,
 O pipeline do `ctx graph` é dividido em cinco etapas fundamentais:
 
 ```
-[Código Fonte] ──> Extractor (Tree-Sitter) ──> Framework Router ──> SQLite Store ──> Query & Ranking (PageRank/BM25)
+[Código Fonte] ──> Extractor (Tree-Sitter) ──> Framework Router ──> SQLite Store ──> Query & Ranking ──> Token Budget
 ```
 
 1. **Scanner & Extractor**: O scanner descobre os arquivos no projeto (respeitando as regras de `.gitignore`). Cada arquivo é analisado usando **Tree-Sitter** para extrair declarações de símbolos (classes, métodos, funções, etc.), chamadas (`call sites`), e `imports` de módulos.
 2. **Framework Routing**: Detecta definições de rotas HTTP para frameworks conhecidos e injeta símbolos sintéticos do tipo `route::METODO /path` vinculados às suas respectivas funções handler.
-3. **Persistência**: As informações extraídas são limpas de forma idempotente e salvas em um banco de dados SQLite unificado localizado em `~/.cache/context_engine/graph.db`.
-4. **Ranking & BM25**: Para as buscas, as queries textuais são resolvidas usando um algoritmo de relevância híbrido baseado em **BM25** (no nome dos símbolos) combinado com métricas de conectividade do grafo (PageRank e contagem de call sites).
-5. **Token Budget**: Os resultados passam por um algoritmo de busca binária para limitar e ajustar perfeitamente o tamanho do output em número de tokens de acordo com o contexto disponível do LLM.
+3. **Persistência**: As informações extraídas são limpas de forma idempotente por arquivo (`clear_file` + insert) e salvas em SQLite em `~/.cache/context_engine/graph.db`. Não há file watcher — re-indexe com `ctx graph index` após mudanças.
+4. **Ranking**: Resultados de `callers`/`callees`/`trace` são ordenados por score heurístico (`src/pipelines/graph/query.rs::score_node`): boost se termos da `--query` aparecem no nome/qualified, `log₂` do número de call sites (centralidade), e peso leve por `kind` (function/method > struct > variable). **Não** usa BM25 nem PageRank do pipeline `map`.
+5. **Token Budget**: Com `--max-tokens`, os nós já ranqueados são incluídos em ordem até estourar o limite (estimativa 1 token ≈ 4 chars) — corte linear, não binary search.
 
 ---
 
 ## 🛠️ Subcomandos Disponíveis
 
 ### 1. `ctx graph index`
-Indexa (ou re-indexa de forma incremental) os diretórios especificados.
+Indexa os diretórios especificados (re-indexação idempotente por arquivo; varre todos os arquivos elegíveis a cada execução).
 
 ```bash
 ctx graph index --dirs src
@@ -65,7 +65,8 @@ ctx graph impact migrate_db
 Detalha as propriedades e o local exato onde um símbolo está definido no grafo.
 
 ```bash
-ctx graph node "route::GET /users/:id"
+# Busca por nome do símbolo (ex.: rota sintética ou handler)
+ctx graph node "GET /users/:id"
 ```
 
 ---
@@ -90,7 +91,7 @@ Uma das funcionalidades mais poderosas do `ctx graph` é o suporte nativo a rota
 
 ## 💎 Diferenciais Exclusivos vs CodeGraph e RTK
 
-1.  **Resultados Ranqueados:** O CodeGraph retorna listas cruas de callers/callees. O `ctx graph` ranqueia os resultados usando a query textual com BM25 + PageRank para garantir que os símbolos mais relevantes para a tarefa do agente apareçam primeiro.
+1.  **Resultados Ranqueados:** O CodeGraph retorna listas cruas de callers/callees. O `ctx graph` ordena por relevância heurística à `--query` (termos no nome + popularidade por sites + kind).
 2.  **Deduplicação Inteligente de Call Sites:** Se um método é chamado 10 vezes pelo mesmo chamador, o `ctx graph` agrupa os call sites em uma única entrada reduzida, economizando tokens preciosos.
-3.  **Token Budget Integration:** As buscas respeitam a flag `--max-tokens` do seu agente através de busca binária robusta no output final do grafo.
-4.  **100% Local e Rápido:** Construído em Rust e usando o poder do SQLite e Tree-Sitter, indexa projetos gigantescos em segundos com threads paralelas via `rayon`.
+3.  **Token Budget Integration:** `--max-tokens` corta o output nos símbolos top-ranked já ordenados (corte linear).
+4.  **100% Local e Rápido:** Construído em Rust com SQLite e Tree-Sitter; indexação paralela via `rayon`.
diff --git a/docs/guides/agent-integration.md b/docs/guides/agent-integration.md
@@ -3,7 +3,7 @@
 `ctx install --agent <name>` configura **dois mecanismos** no agente de codificação, juntos no mesmo `settings.json`:
 
 1. **Hook `PreToolUse`** que redireciona comandos Bash cobertos para `ctx exec` automaticamente (compressão de output).
-2. **MCP server `ctx`** expondo `ctx_exec`, `ctx_search`, `ctx_map`, `ctx_list` como tools nominais (chamadas explícitas pelo agente).
+2. **MCP server `ctx`** expondo **10 tools** (`ctx_exec`, `ctx_search`, `ctx_map`, `ctx_list`, mais seis de grafo) como chamadas explícitas pelo agente.
 
 Os dois coexistem: o hook captura Bash calls existentes, o MCP server permite que o agente invoque tools por nome quando faz sentido (ex: `ctx_search` para busca semântica em docs indexadas).
 
@@ -14,7 +14,7 @@ Resultado prático: o agente roda `git status` normalmente; o hook reescreve par
 | Agente | Status | Escopo padrão |
 |--------|--------|---------------|
 | Claude Code | ✅ disponível | `~/.claude/settings.json` |
-| Claude Desktop | ✅ disponível | `~/*.../claude_desktop_config.json` |
+| Claude Desktop | ✅ disponível | Ver [caminhos por SO](#claude-desktop) abaixo |
 | Cursor | 🚧 próxima entrega | — |
 | Codex CLI | 🚧 próxima entrega | — |
 | opencode | 🚧 próxima entrega | — |
@@ -47,7 +47,24 @@ ctx install --agent claude-desktop
 ctx uninstall --agent claude-desktop
 ```
 
-Reinicie sessões abertas do agente para o hook entrar em vigor.
+O installer escreve apenas o bloco `mcpServers` (Claude Desktop **não** suporta hooks `PreToolUse`).
+
+**Caminhos do config** (`claude_desktop_config.json`), resolvidos por `dirs::config_dir()`:
+
+| SO | Caminho |
+|---|---|
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+**Após instalar:** feche e reabra o app Claude Desktop (ou reinicie o processo) para recarregar o MCP. Não é necessário “nova sessão de chat” como no Claude Code — basta o app reler o JSON.
+
+### Reinício por agente
+
+| Agente | O que fazer após `ctx install` |
+|---|---|
+| Claude Code | Inicie uma **nova sessão** de chat para o hook `PreToolUse` e o MCP entrarem em vigor |
+| Claude Desktop | **Reabra o app** para recarregar `claude_desktop_config.json` (só MCP, sem hook) |
 
 ## O que é escrito no `settings.json`