diff --git a/README.md b/README.md
index e9e7467..09529fd 100644
--- a/README.md
+++ b/README.md
@@ -318,36 +318,79 @@ Install the **"Export Claude Chat to Markdown"** browser extension for Chrome/Ed
 
 ```bash
 pip install graphifyy
-graphify install
+graphify install --platform claude
 ```
 
-`graphify install` creates the skill at `~/.claude/skills/graphify/SKILL.md`.
+`graphify install --platform claude` creates the skill at `~/.claude/skills/graphify/SKILL.md`. Other platforms are also supported (`cursor`, `codex`, `opencode`, etc.).
+
+**1.5. Set up API key (required for semantic extraction):**
+
+Graphify needs an LLM API key from Anthropic or Moonshot (Kimi) for semantic extraction. Export one before running:
+
+```bash
+export ANTHROPIC_API_KEY="your-key-here"
+# or
+export MOONSHOT_API_KEY="your-key-here"
+```
+
+If you want to skip LLM costs entirely, use AST-only mode:
+
+```bash
+graphify extract . --out ./graphify-out --no-cluster
+```
+
+This generates a structural graph without semantic edges.
 
 **2. Generate the graph:**
 
-From your project root:
+Graphify has two execution paths and the original `--obsidian*` flags only work on one of them. Pick the form that matches how you're invoking it:
 
-```bash
-# Full pipeline + Obsidian notes in the centralized vault
-graphify . --obsidian --obsidian-dir ~/vault/graphify/project-name
+**A. Inside Claude Code (skill — recommended for this guide):**
+
+```
+/graphify . --obsidian --obsidian-dir ~/vault/graphify/project-name
 ```
 
-Generated output:
+This runs the `/graphify` slash command, which the skill at `~/.claude/skills/graphify/SKILL.md` parses. The skill calls `graphify.export.to_obsidian()` in Python directly, so `--obsidian` and `--obsidian-dir` are recognized here — they're not part of the headless shell parser.
+
+**B. From the terminal / CI (headless CLI):**
+
+```bash
+graphify extract . --out ./graphify-out
+```
+
+The headless CLI uses subcommands (`extract`, `update`, `watch`, `tree`) and does **not** expose `--obsidian` / `--obsidian-dir` / `--wiki` / `--mode deep`. If you want Obsidian integration from the terminal, symlink the output directory into your vault after extraction:
+
+```bash
+ln -s $(pwd)/graphify-out ~/vault/graphify/project-name/graphify-out
+```
+
+Generated output (varies by path and flags):
 
 ```
 your-project/
 └── graphify-out/
-    ├── graph.json          # queryable graph (Claude Code uses this)
-    ├── graph.html          # interactive visualization (open in browser)
-    ├── GRAPH_REPORT.md     # god nodes, connections, metrics
-    ├── wiki/               # Wikipedia-style articles (agent navigation)
+    ├── graph.json          # queryable graph (always)
+    ├── graph.html          # interactive viz (skill auto-generates; headless: see step 3)
+    ├── GRAPH_REPORT.md     # god nodes, connections, metrics (always)
+    ├── wiki/               # Wikipedia-style articles (skill form with --wiki only)
     └── cache/              # SHA256 cache
 
-~/vault/graphify/project-name/
-    └── (Obsidian notes)    # each function/module as a node in graph view
+~/vault/graphify/project-name/    # only when skill form was given --obsidian
+    └── (Obsidian notes)          # one note per function/module
 ```
 
-**3. Update .gitignore:**
+**3. Generate interactive visualization (headless only):**
+
+The skill auto-generates `graph.html` during extraction. For the headless path, run the visualization as a separate step:
+
+```bash
+graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html
+```
+
+Open the HTML file in a browser to explore the graph interactively.
+
+**4. Update .gitignore:**
 
 ```gitignore
 # Graphify
@@ -356,7 +399,7 @@ graphify-out/cache/
 
 Keep `graph.json` and `GRAPH_REPORT.md` versioned — they're useful for the team.
 
-**4. Add to the project's CLAUDE.md:**
+**5. Add to the project's CLAUDE.md:**
 
 Append to the CLAUDE.md at the repository root:
 
@@ -372,7 +415,8 @@ Append to the CLAUDE.md at the repository root:
 
 ### When to rebuild the graph
 - After structural changes (new modules, major refactors)
-- Command: `graphify . --update` (only processes modified files)
+- Headless: `graphify update .` (only processes modified files)
+- Skill: `/graphify . --update` (same behavior, runs through the skill — also accepts `--obsidian` to refresh the vault)
 - The graph is persistent — NO need to rebuild every session
 
 ### Do NOT
@@ -380,7 +424,7 @@ Append to the CLAUDE.md at the repository root:
 - Don't re-read the entire codebase if the graph already has the information
 ```
 
-**5. Add to the vault's CLAUDE.md:**
+**6. Add to the vault's CLAUDE.md:**
 
 ```markdown
 ## Graphify (Codebase Maps)
@@ -395,7 +439,7 @@ Append to the CLAUDE.md at the repository root:
 - Filter by `-path:graphify` to hide code nodes
 ```
 
-**6. Git Hook (optional):**
+**7. Git Hook (optional):**
 
 Automatically rebuilds the graph on every commit:
 
@@ -403,36 +447,57 @@ Automatically rebuilds the graph on every commit:
 graphify hook install
 ```
 
-**7. Watch Mode (optional):**
+**8. Watch Mode (optional):**
 
-Auto-rebuild on file save (run in a separate terminal):
+Auto-rebuild on file save. Pick the form that matches how you invoke graphify.
+
+Headless (separate terminal):
 
 ```bash
-graphify . --watch
+graphify watch .
+```
+
+Skill (inside Claude Code):
+
+```
+/graphify . --watch
 ```
 
 ### Useful Commands
 
+The table below lists the **headless CLI** subcommands you'd run in a terminal. Inside Claude Code, the same operations are available via the `/graphify` slash form documented in `~/.claude/skills/graphify/SKILL.md` — that form additionally supports `--obsidian`, `--obsidian-dir`, `--wiki`, and `--mode deep` (which the headless parser doesn't expose).
+
 | Command | Description |
 |---------|-------------|
-| `graphify .` | Full pipeline on current directory |
-| `graphify ./src` | Scan specific folder |
-| `graphify . --update` | Only process modified files |
-| `graphify . --mode deep` | Semantic extraction (uses LLM, costs tokens) |
-| `graphify . --watch` | Auto-rebuild on save |
+| `graphify extract .` | Full extraction on current directory |
+| `graphify extract ./src` | Scan specific folder |
+| `graphify update .` | Only process modified files |
+| `graphify watch .` | Auto-rebuild on save |
 | `graphify query "question"` | Query the graph directly |
-| `open graphify-out/graph.html` | Open interactive visualization |
+| `graphify explain "NodeName"` | Plain-language explanation of a node |
+| `graphify path "A" "B"` | Shortest path between two nodes |
+| `graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html` | Generate interactive visualization |
+| `open graphify-out/graph.html` | Open interactive visualization (skill-generated) or `GRAPH_TREE.html` (headless) |
 
 ### Adding New Projects
 
-With a centralized vault, each project is just a subfolder:
+With a centralized vault, each project is just a subfolder. Same two paths as the initial setup.
+
+Skill (inside Claude Code):
+
+```
+/graphify ~/another-project --obsidian --obsidian-dir ~/vault/graphify/another-project
+```
+
+Headless (terminal):
 
 ```bash
 cd ~/another-project
-graphify . --obsidian --obsidian-dir ~/vault/graphify/another-project
+graphify extract . --out ./graphify-out
+ln -s $(pwd)/graphify-out ~/vault/graphify/another-project/graphify-out
 ```
 
-Notes automatically appear in Obsidian's graph view alongside everything else.
+Drop the `ln -s` line if you don't need Obsidian to pick up the graph. Notes appear in Obsidian's graph view alongside everything else.
 
 ---
 
@@ -539,7 +604,7 @@ Check that the project's CLAUDE.md has the "Context Navigation" section and that
 Grant Full Disk Access to your terminal in System Preferences → Privacy & Security.
 
 **Graphify doesn't generate wiki:**
-The wiki requires semantic edges. In AST-only mode, use `graphify query "question"` or run `--mode deep` (costs API tokens).
+The `wiki/` folder is only produced by the **skill form with `--wiki`** (`/graphify . --wiki` inside Claude Code). The headless `graphify extract` subcommand doesn't expose `--wiki`. From the terminal, use `graphify query "question"` against `graph.json` instead, or run the skill form if you need the Wikipedia-style articles.
 
 **Files with parentheses in name:**
 Graphify generates notes like `myFunction().md`. Obsidian may struggle indexing files with `()` in the name. If needed, batch rename:
@@ -548,9 +613,15 @@ cd ~/vault/graphify/project
 for f in *"("*; do mv "$f" "$(echo "$f" | sed 's/[()]//g')"; done
 ```
 **Unknown Command error in graphify:**
-If an `unknown command '.'` error occurs in the `Generate the graph` step, in newer versions the `update` parameter should be placed immediately after `graphify`, resulting in:
+If `graphify .` errors with `unknown command '.'`, you're running the **headless CLI** — which requires a subcommand (`extract`, `update`, `watch`, etc.) before the path. Either use the headless form:
 ```bash
-graphify update . --obsidian --obsidian-dir ~/vault/graphify/project-name
+graphify extract . --out ./graphify-out
+# or, to refresh an existing graph:
+graphify update .
+```
+Or, inside Claude Code, use the **skill form** with the leading slash — which routes through the `/graphify` skill rather than the shell parser and supports the full flag set (`--obsidian`, `--obsidian-dir`, `--wiki`, `--mode deep`, etc.):
+```
+/graphify . --obsidian --obsidian-dir ~/vault/graphify/project-name
 ```
 
 ---
diff --git a/README.pt-BR.md b/README.pt-BR.md
index 8a34a44..793f00a 100644
--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -318,36 +318,79 @@ Instale a extensão **"Export Claude Chat to Markdown"** no Chrome/Edge. Faça b
 
 ```bash
 pip install graphifyy
-graphify install
+graphify install --platform claude
 ```
 
-O `graphify install` cria o skill em `~/.claude/skills/graphify/SKILL.md`.
+O `graphify install --platform claude` cria o skill em `~/.claude/skills/graphify/SKILL.md`. Outras plataformas também são suportadas (`cursor`, `codex`, `opencode`, etc.).
+
+**1.5. Configurar API key (necessário para extração semântica):**
+
+O Graphify precisa de uma API key de LLM da Anthropic ou da Moonshot (Kimi) para extração semântica. Exporte uma antes de rodar:
+
+```bash
+export ANTHROPIC_API_KEY="sua-chave-aqui"
+# ou
+export MOONSHOT_API_KEY="sua-chave-aqui"
+```
+
+Se quiser pular custos de LLM completamente, use o modo AST-only:
+
+```bash
+graphify extract . --out ./graphify-out --no-cluster
+```
+
+Isso gera um grafo estrutural sem edges semânticas.
 
 **2. Gerar o grafo:**
 
-Na raiz do seu projeto:
+O Graphify tem dois caminhos de execução e as flags `--obsidian*` originais só funcionam em um deles. Escolha o formato que corresponde a como você está invocando:
 
-```bash
-# Pipeline completa + notas Obsidian no vault centralizado
-graphify . --obsidian --obsidian-dir ~/vault/graphify/nome-do-projeto
+**A. Dentro do Claude Code (skill — recomendado para este guia):**
+
+```
+/graphify . --obsidian --obsidian-dir ~/vault/graphify/nome-do-projeto
 ```
 
-Output gerado:
+Isso roda o slash command `/graphify`, que o skill em `~/.claude/skills/graphify/SKILL.md` interpreta. O skill chama `graphify.export.to_obsidian()` em Python diretamente, então `--obsidian` e `--obsidian-dir` são reconhecidas aqui — elas não fazem parte do parser do shell headless.
+
+**B. Do terminal / CI (CLI headless):**
+
+```bash
+graphify extract . --out ./graphify-out
+```
+
+O CLI headless usa subcomandos (`extract`, `update`, `watch`, `tree`) e **não** expõe `--obsidian` / `--obsidian-dir` / `--wiki` / `--mode deep`. Se quiser integração com Obsidian a partir do terminal, faça um symlink do diretório de output para o vault depois da extração:
+
+```bash
+ln -s $(pwd)/graphify-out ~/vault/graphify/nome-do-projeto/graphify-out
+```
+
+Output gerado (varia conforme o caminho e as flags):
 
 ```
 seu-projeto/
 └── graphify-out/
-    ├── graph.json          # grafo consultável (o Claude Code usa este)
-    ├── graph.html          # visualização interativa (abra no browser)
-    ├── GRAPH_REPORT.md     # god nodes, conexões, métricas
-    ├── wiki/               # artigos estilo Wikipedia (navegação do agente)
+    ├── graph.json          # grafo consultável (sempre)
+    ├── graph.html          # viz interativa (skill auto-gera; headless: ver passo 3)
+    ├── GRAPH_REPORT.md     # god nodes, conexões, métricas (sempre)
+    ├── wiki/               # artigos estilo Wikipedia (só skill com --wiki)
     └── cache/              # cache SHA256
 
-~/vault/graphify/nome-do-projeto/
-    └── (notas Obsidian)    # cada função/módulo como um nó no graph view
+~/vault/graphify/nome-do-projeto/    # só quando o skill recebeu --obsidian
+    └── (notas Obsidian)              # uma nota por função/módulo
 ```
 
-**3. Atualizar .gitignore:**
+**3. Gerar visualização interativa (só no caminho headless):**
+
+O skill auto-gera `graph.html` durante a extração. Para o caminho headless, rode a visualização como passo separado:
+
+```bash
+graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html
+```
+
+Abra o arquivo HTML no navegador para explorar o grafo interativamente.
+
+**4. Atualizar .gitignore:**
 
 ```gitignore
 # Graphify
@@ -356,7 +399,7 @@ graphify-out/cache/
 
 Mantenha `graph.json` e `GRAPH_REPORT.md` versionados.
 
-**4. Adicionar ao CLAUDE.md do projeto:**
+**5. Adicionar ao CLAUDE.md do projeto:**
 
 Adicione ao final do CLAUDE.md na raiz do repositório:
 
@@ -372,7 +415,8 @@ Adicione ao final do CLAUDE.md na raiz do repositório:
 
 ### Quando reconstruir o grafo
 - Após mudanças estruturais (novos módulos, refactors)
-- Comando: `graphify . --update` (só processa arquivos modificados)
+- Headless: `graphify update .` (só processa arquivos modificados)
+- Skill: `/graphify . --update` (mesmo comportamento, rodando via skill — também aceita `--obsidian` para atualizar o vault)
 - O grafo é persistente — NÃO precisa reconstruir a cada sessão
 
 ### O que NÃO fazer
@@ -380,7 +424,7 @@ Adicione ao final do CLAUDE.md na raiz do repositório:
 - Não releia o codebase inteiro se o grafo já tem a informação
 ```
 
-**5. Adicionar ao CLAUDE.md do vault:**
+**6. Adicionar ao CLAUDE.md do vault:**
 
 ```markdown
 ## Graphify (Mapas de Codebase)
@@ -395,7 +439,7 @@ Adicione ao final do CLAUDE.md na raiz do repositório:
 - Filtrar por `-path:graphify` para esconder nós de código
 ```
 
-**6. Git Hook (opcional):**
+**7. Git Hook (opcional):**
 
 Reconstrói o grafo automaticamente a cada commit:
 
@@ -403,36 +447,57 @@ Reconstrói o grafo automaticamente a cada commit:
 graphify hook install
 ```
 
-**7. Watch Mode (opcional):**
+**8. Watch Mode (opcional):**
 
-Rebuild automático ao salvar arquivos (rode em terminal separado):
+Rebuild automático ao salvar arquivos. Escolha o formato conforme como você invoca o graphify.
+
+Headless (terminal separado):
 
 ```bash
-graphify . --watch
+graphify watch .
+```
+
+Skill (dentro do Claude Code):
+
+```
+/graphify . --watch
 ```
 
 ### Comandos Úteis
 
+A tabela abaixo lista os subcomandos do **CLI headless** que você rodaria no terminal. Dentro do Claude Code, as mesmas operações estão disponíveis via o slash command `/graphify` documentado em `~/.claude/skills/graphify/SKILL.md` — esse formato aceita adicionalmente `--obsidian`, `--obsidian-dir`, `--wiki` e `--mode deep` (que o parser headless não expõe).
+
 | Comando | Descrição |
 |---------|-----------|
-| `graphify .` | Pipeline completa no diretório atual |
-| `graphify ./src` | Escanear pasta específica |
-| `graphify . --update` | Só processa arquivos modificados |
-| `graphify . --mode deep` | Extração semântica (usa LLM, consome tokens) |
-| `graphify . --watch` | Auto-rebuild ao salvar |
+| `graphify extract .` | Extração completa no diretório atual |
+| `graphify extract ./src` | Escanear pasta específica |
+| `graphify update .` | Só processa arquivos modificados |
+| `graphify watch .` | Auto-rebuild ao salvar |
 | `graphify query "pergunta"` | Consultar o grafo diretamente |
-| `open graphify-out/graph.html` | Abrir visualização interativa |
+| `graphify explain "NomeDoNo"` | Explicação em linguagem natural de um nó |
+| `graphify path "A" "B"` | Caminho mais curto entre dois nós |
+| `graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html` | Gerar visualização interativa |
+| `open graphify-out/graph.html` | Abrir visualização interativa (skill gera) ou `GRAPH_TREE.html` (headless) |
 
 ### Adicionando Novos Projetos
 
-Com vault centralizado, cada projeto é uma subpasta:
+Com vault centralizado, cada projeto é uma subpasta. Mesmos dois caminhos do setup inicial.
+
+Skill (dentro do Claude Code):
+
+```
+/graphify ~/outro-projeto --obsidian --obsidian-dir ~/vault/graphify/outro-projeto
+```
+
+Headless (terminal):
 
 ```bash
 cd ~/outro-projeto
-graphify . --obsidian --obsidian-dir ~/vault/graphify/outro-projeto
+graphify extract . --out ./graphify-out
+ln -s $(pwd)/graphify-out ~/vault/graphify/outro-projeto/graphify-out
 ```
 
-As notas aparecem automaticamente no graph view do Obsidian.
+Pule a linha do `ln -s` se você não precisa que o Obsidian enxergue o grafo. As notas aparecem no graph view do Obsidian junto com tudo o mais.
 
 ---
 
@@ -539,7 +604,7 @@ Verifique se o CLAUDE.md do projeto tem a seção "Context Navigation" e se `gra
 Dê permissão de Full Disk Access ao terminal em Preferências do Sistema → Privacidade e Segurança.
 
 **Graphify não gera wiki:**
-A wiki requer edges semânticas. No modo AST-only, use `graphify query "pergunta"` ou rode `--mode deep` (consome tokens da API).
+A pasta `wiki/` só é produzida pelo **formato skill com `--wiki`** (`/graphify . --wiki` dentro do Claude Code). O subcomando headless `graphify extract` não expõe `--wiki`. Do terminal, use `graphify query "pergunta"` contra o `graph.json`, ou rode o formato skill se precisar dos artigos estilo Wikipedia.
 
 **Arquivos com parênteses no nome:**
 O Graphify gera notas como `minhaFuncao().md`. O Obsidian pode ter dificuldades de indexação com `()` nos nomes. Se necessário, renomeie em batch: