brito-cli 0.0.0-stage → 0.3.2

package/.brito/agents/reviewer.md

@@ -0,0 +1,7 @@
+---
+name: reviewer
+description: Revisa mudanças procurando bugs e impacto em chamadores. Somente leitura.
+tools: read_file, grep, graph_context, graph_callers, graph_impact
+model: claude-opus-5-5
+---
+Você é um revisor de código rigoroso. Para cada símbolo alterado, rode graph_callers e verifique se os chamadores continuam corretos.

package/LICENSE

@@ -0,0 +1,75 @@
+Required Notice: Copyright (c) 2026 Wilson Brito (https://github.com/wilsonbrito/brito)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+# Brito
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [Português](README.pt-BR.md)
+
+> A coding-agent CLI that knows your codebase as a **graph** and learns your project's procedures as **skills you review**.
+
+Brito is a terminal agent for software development. Instead of grepping and reading files blindly, it keeps a **knowledge graph of your code** (symbols, who calls whom, who imports whom) and answers questions like *"what breaks if I change this?"* straight from the graph, in a fraction of a second. It also keeps **memory notes** and **skills**: reusable procedures learned from your own work, which only become active after **you** approve them.
+
+![Brito answering a question with the code graph](docs/images/answer-with-graph.png)
+
+*A real session on a small SvelteKit project: one question, two graph calls (0.1 s and 0.0 s), and an answer that already includes the `.svelte` components depending on the file. The status bar shows the real cost of the turn.*
+
+## Highlights
+
+- **Graph-first exploration.** `graph_search`, `graph_context`, `graph_callers`, `graph_callees` and `graph_impact` answer "where is it, who uses it, what breaks" without reading whole files. The graph is embedded ([Kùzu](https://kuzudb.com)), local and incremental.
+- **Wide coverage.** TypeScript/JavaScript, Python and the script blocks of `.svelte`, `.vue` and `.astro` components. Import aliases (`tsconfig` paths, `package.json` imports, SvelteKit's `$lib`) become real edges. Files ignored by `.gitignore` stay out.
+- **Skills that learn, with a human in the loop.** After a complex task Brito reflects on what happened and *proposes* skills. Nothing becomes active until you run `/skills approve`.
+- **Safety rails for what gets learned.** A lint rejects secrets, credentials embedded in URLs, `curl | sh` and prompt-injection phrasing, and **warns about destructive commands** (see below).
+- **Permission modes.** manual, auto-edits, plan and "everything allowed" (`Shift+Tab` cycles them). Even in the last one, skills are queued for review instead of being activated.
+- **Two backends, one interface.** Use an Anthropic API key, or your Claude Code subscription through the `claude` CLI. Brito never reads or sends your subscription token.
+- **Subagents.** `explore`, `plan` and `general` run in isolated contexts (read-only ones in parallel); add your own in `.brito/agents/*.md`.
+- **MCP server.** `brito mcp-serve` exposes the graph, memory and skills to other MCP clients such as Claude Code. The query tools are marked `alwaysLoad`, so they are not hidden behind tool search.
+
+## How it works
+
+```mermaid
+flowchart LR
+    code["Your project<br/>.ts · .js · .py · .java · .kt · .go · .rb · .php · .cs · .rs · .svelte · .vue · .astro"] -->|"tree-sitter<br/>incremental"| cg[("Code graph<br/>symbols · calls · imports")]
+    cg <-->|"graph_search · graph_callers<br/>graph_impact · graph_context"| agent{{"Brito agent"}}
+    mem[("Memory<br/>decisions · conventions")] <-->|"recall / remember"| agent
+    agent -->|"after a complex task"| learn["Reflection"]
+    learn -->|"proposes"| pending["Pending skills"]
+    pending -->|"/skills approve<br/>you decide"| skills[("Skills<br/>.brito/skills")]
+    skills -->|"skill_load"| agent
+```
+
+- **Code graph**: functions, classes, methods and components as nodes; `CALLS` and `IMPORTS` as edges. It re-parses only files whose hash changed and updates itself after edits.
+- **Memory**: durable notes (decisions, conventions, bugs found) linked to files and symbols, retrieved with `recall`.
+- **Skills**: step-by-step procedures for *your* project (commands, order, traps, how to verify). The agent loads one with `skill_load` before a task it covers.
+- **Journal**: Brito remembers across sessions which tasks repeated, which is the best hint that a procedure is general and worth saving.
+
+## Skills you review, not magic
+
+![Reviewing a pending skill, with a destructive-command warning](docs/images/skills-review.png)
+
+1. A proposal appears in `/skills pending`, flagged when it contains destructive commands.
+2. `/skills approve <name>` shows the **whole body** and the lint warnings, then asks for confirmation. That confirmation is required even in "everything allowed" mode.
+3. Approved skills are versioned (`history/`), ranked by use, and flagged when the files they cite no longer exist. `/skills consolidate` merges duplicates and prunes unused ones.
+4. A skill can be project-scoped or **global** (valid in every project); `/skills promote` moves one to global.
+
+The lint **rejects** secrets/tokens, absolute user paths, credentials in URLs (`user:password@host`), `curl | sh`, and instructions to override rules or skip approval. It **warns** (without blocking) about commands that destroy data: removing database or data files, `DROP`/`TRUNCATE`, `DELETE` without `WHERE`, migration resets, `git reset --hard`, force-push, Docker volume removal. A skill is a standing instruction, so a step that was only safe in the state of one moment must not silently become the default.
+
+## Install
+
+Requires Node >= 20. Developed on macOS; Linux should work, Windows is untested.
+
+```bash
+# from npm (the command is `brito`)
+npm i -g brito-cli
+
+# or one line
+curl -fsSL https://raw.githubusercontent.com/wilsonbrito/brito/main/install.sh | bash
+
+# or straight from GitHub
+npm i -g github:wilsonbrito/brito
+
+# or cloning
+git clone https://github.com/wilsonbrito/brito && cd brito
+npm install && npm run build && npm link
+```
+
+Pick a backend:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...      # Anthropic API
+# or: install Claude Code, run `claude` and /login — Brito will use your subscription
+```
+
+## Quick start
+
+```bash
+cd your-project
+brito                       # opens the REPL
+brito "who calls parseConfig?"   # single prompt, no REPL
+brito index                 # (re)index the graph; it is also kept up to date automatically
+brito query "MATCH (c:Symbol {kind:'component'})-[:CALLS]->(f:Symbol) RETURN c.file, f.name LIMIT 5"
+```
+
+A real `brito index` on the sample project above:
+
+```
+OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
+```
+
+![Brito start screen](docs/images/startup.png)
+
+### Inside the REPL
+
+| Command | What it does |
+|---|---|
+| `/help` | list commands |
+| `/model`, `/effort`, `/reasoning` | choose model, reasoning effort and thinking (session, global or once) |
+| `/modo` or `Shift+Tab` | switch permission mode: manual → auto-edits → plan |
+| `/skills` | list skills · `pending` · `approve <name>` · `reject <name>` · `consolidate` · `rm <name>` · `promote <name>` |
+| `/learn` | extract skills from the last turn now |
+| `/agents`, `/tools`, `/index`, `/context` | inspect subagents, tools, the index and the context window |
+| `!command` | run a shell command directly, without calling the model |
+| `/clear`, `/exit` | clear the conversation, quit |
+
+## What the graph indexes
+
+- **Languages:** TypeScript/JavaScript (`.ts .tsx .mts .cts .js .jsx .mjs .cjs`), Python (`.py`), backend languages — Java (`.java`), Kotlin (`.kt`), Go (`.go`), Ruby (`.rb`), PHP (`.php`), C# (`.cs`), Rust (`.rs`) — and the `.svelte`, `.vue` and `.astro` components. In components Brito reads the script block(s) (and Astro's frontmatter) and records calls made from the template to functions the script declares or imports; each component becomes a `component` symbol.
+- **Scope:** inside a git repository, only what git considers part of the project (tracked + untracked-but-not-ignored), so anything in `.gitignore` stays out. Outside git, or with `BRITO_INDEX_IGNORED=1`, it indexes by glob (still skipping `node_modules`, `dist`, `build`, `target`, `vendor`, `obj`, `.gradle`, `.venv`, `.brito`).
+- **Imports:** relative and aliased. Resolves `paths`/`baseUrl` from `tsconfig.json`/`jsconfig.json` (following relative `extends`, like `.svelte-kit/tsconfig.json`), `package.json` `imports` (`#internal/*`) and SvelteKit's `$lib`. Configuration applies per file (nearest config), so monorepos work; editing a tsconfig re-indexes the affected files.
+- **Backend languages:** the graph holds classes/interfaces/structs/traits/enums/modules, functions and methods (`Class.method`), calls and imports. Imports name a package, not a path, so Brito matches them against the end of your files' paths (`com.acme.Repo` ↔ `src/main/java/com/acme/Repo.java`; PHP PSR-4 namespaces; Rust `use crate::…`; Ruby `require`/`require_relative`; Go packages through the `go.mod` module path). External packages (`java.util`, `serde`, `github.com/gin-gonic/gin`) never match and create no edges. There is no type inference: a call like `userRepository.save()` is linked by matching the receiver name to a type in the project (`UserRepository`), `this`/`self`/receivers resolve to the enclosing class, and a bare call inside a class tries the class's own methods first.
+- **Not yet:** `extends` by package (`@tsconfig/node20`), sibling-workspace `exports`, and function references without a call in a template (`onclick={fn}`). Calls are resolved statically with name-based fallbacks, so dynamic dispatch and reflection are not captured.
+
+## Databases and other sensitive resources
+
+Brito has **no database drivers and connects to nothing on its own**. When it needs to touch a database, it uses your project's own tooling through the shell, under the permission mode you chose. Because every project is different (a local file, a remote server, a container), declare the sensitive parts in `BRITO.md` (or `CLAUDE.md` / `AGENTS.md`), which is read into the system prompt:
+
+```markdown
+## Protected resources
+- Database: local SQLite file `local.db` (never commit, never recreate).
+  Test destructive changes on a copy: `cp local.db /tmp/test.db` and set `DATABASE_URL`.
+  Schema changes: additive only, back up first (`cp local.db backups/pre-change.db`).
+- Staging Postgres: connection string is in `$STAGING_DATABASE_URL` (read-only role). Never touch production.
+```
+
+- Credentials never belong in skills or notes: the lint rejects them. Cite the **name** of the environment variable instead.
+- Prefer read-only roles and non-production environments when you give an agent database access.
+- A proposed skill that contains a destructive command is highlighted at review time, so you decide whether it needs a guard (backup, copy, confirmation).
+
+## Configuration
+
+`BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (where global skills and history live), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` or `full`; default: full screen on windows of 95+ columns and 28+ rows), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (how long a turn must be to trigger reflection when nothing else does).
+
+Project data lives in `.brito/` (graph, project skills, agents) and global data in `~/.brito`. The graph, memory and skills stay on your machine; as with any coding agent, the code the model reads is sent to the model provider you configured.
+
+## Limitations
+
+- Early software (v0.3.1), one maintainer.
+- **The interface and the agent's default language are Brazilian Portuguese.** Translating them is a welcome contribution.
+- Skill learning is a heuristic: it proposes, you decide. Expect some proposals to be rejected.
+
+## Development
+
+```bash
+git clone https://github.com/wilsonbrito/brito && cd brito
+npm install
+npm run dev          # runs via tsx
+npm run typecheck
+npm test             # 190+ tests, including a real MCP server and a real REPL
+```
+
+| Path | What |
+|---|---|
+| `src/graph/` | indexer (tree-sitter), `.svelte/.vue/.astro` support, import aliases, Kùzu store |
+| `src/skills/` | store, lint, reflection, journal, consolidation |
+| `src/agent/` | agent loop, prompts, subagents, `claude` CLI backend |
+| `src/tools/` | graph, memory, skills, filesystem and shell tools |
+| `src/mcp/` | MCP server |
+| `src/repl.ts`, `src/ui/` | terminal interface |
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE): free to use, study and modify for any noncommercial purpose (personal use, research, education, hobby, nonprofits). Commercial use is not permitted. This is source-available, not OSI open source. Need a commercial license? Open an issue.

package/README.pt-BR.md

@@ -0,0 +1,167 @@
+# Brito
+
+[English](README.md) · **Português**
+
+> Uma CLI de agente de código que conhece o seu projeto como um **grafo** e aprende os procedimentos dele como **skills que você revisa**.
+
+O Brito é um agente de terminal para desenvolvimento de software. Em vez de dar `grep` e ler arquivos às cegas, ele mantém um **grafo de conhecimento do código** (símbolos, quem chama quem, quem importa quem) e responde perguntas como *"o que quebra se eu mudar isto?"* direto do grafo, em uma fração de segundo. Ele também guarda **notas de memória** e **skills**: procedimentos reutilizáveis aprendidos no seu próprio trabalho, que só passam a valer depois que **você** aprova.
+
+![Brito respondendo uma pergunta com o grafo de código](docs/images/answer-with-graph.png)
+
+*Uma sessão real num pequeno projeto SvelteKit: uma pergunta, duas consultas ao grafo (0,1 s e 0,0 s) e uma resposta que já inclui os componentes `.svelte` que dependem do arquivo. A barra de status mostra o custo real do turno.*
+
+## Destaques
+
+- **Exploração guiada pelo grafo.** `graph_search`, `graph_context`, `graph_callers`, `graph_callees` e `graph_impact` respondem "onde está, quem usa, o que quebra" sem ler arquivos inteiros. O grafo é embutido ([Kùzu](https://kuzudb.com)), local e incremental.
+- **Cobertura ampla.** TypeScript/JavaScript, Python e os blocos de script de componentes `.svelte`, `.vue` e `.astro`. Aliases de import (`paths` do tsconfig, `imports` do package.json, `$lib` do SvelteKit) viram arestas de verdade. O que o `.gitignore` ignora fica de fora.
+- **Skills que aprendem, com um humano no circuito.** Depois de uma tarefa complexa o Brito reflete sobre o que aconteceu e *propõe* skills. Nada fica ativo até você rodar `/skills approve`.
+- **Proteções sobre o que é aprendido.** Um lint rejeita segredos, credenciais embutidas em URL, `curl | sh` e frases de injeção de prompt, e **avisa sobre comandos destrutivos** (veja abaixo).
+- **Modos de permissão.** manual, auto-edições, plano e "tudo liberado" (`Shift+Tab` alterna). Mesmo no último, as skills vão para a fila de revisão em vez de ficarem ativas.
+- **Dois backends, uma interface.** Use uma chave da API da Anthropic ou a sua assinatura do Claude Code pela CLI `claude`. O Brito nunca lê nem envia o token da sua assinatura.
+- **Subagentes.** `explore`, `plan` e `general` rodam em contextos isolados (os somente-leitura, em paralelo); crie os seus em `.brito/agents/*.md`.
+- **Servidor MCP.** `brito mcp-serve` expõe grafo, memória e skills a outros clientes MCP, como o Claude Code. As tools de consulta são marcadas `alwaysLoad`, para não ficarem escondidas atrás da busca de tools.
+
+## Como funciona
+
+```mermaid
+flowchart LR
+    code["Seu projeto<br/>.ts · .js · .py · .java · .kt · .go · .rb · .php · .cs · .rs · .svelte · .vue · .astro"] -->|"tree-sitter<br/>incremental"| cg[("Grafo de código<br/>símbolos · chamadas · imports")]
+    cg <-->|"graph_search · graph_callers<br/>graph_impact · graph_context"| agent{{"Agente Brito"}}
+    mem[("Memória<br/>decisões · convenções")] <-->|"recall / remember"| agent
+    agent -->|"após uma tarefa complexa"| learn["Reflexão"]
+    learn -->|"propõe"| pending["Skills pendentes"]
+    pending -->|"/skills approve<br/>você decide"| skills[("Skills<br/>.brito/skills")]
+    skills -->|"skill_load"| agent
+```
+
+- **Grafo de código**: funções, classes, métodos e componentes como nós; `CALLS` e `IMPORTS` como arestas. Só reparseia os arquivos cujo hash mudou e se atualiza sozinho após edições.
+- **Memória**: notas duráveis (decisões, convenções, bugs descobertos) ligadas a arquivos e símbolos, recuperadas com `recall`.
+- **Skills**: procedimentos passo a passo para o *seu* projeto (comandos, ordem, armadilhas, como verificar). O agente carrega uma com `skill_load` antes de uma tarefa que ela cobre.
+- **Journal**: o Brito lembra entre sessões quais tarefas se repetiram, o melhor indício de que um procedimento é geral e vale guardar.
+
+## Skills que você revisa, sem mágica
+
+![Revisando uma skill pendente, com aviso de comando destrutivo](docs/images/skills-review.png)
+
+1. Uma proposta aparece em `/skills pending`, sinalizada quando contém comandos destrutivos.
+2. `/skills approve <nome>` mostra o **corpo inteiro** e os avisos do lint, e pede confirmação. Essa confirmação é exigida mesmo no modo "tudo liberado".
+3. Skills aprovadas são versionadas (`history/`), ranqueadas por uso e sinalizadas quando os arquivos que citam deixam de existir. `/skills consolidate` junta duplicadas e poda as sem uso.
+4. Uma skill pode ser do projeto ou **global** (vale em todos os projetos); `/skills promote` move uma para global.
+
+O lint **rejeita** segredos/tokens, caminhos absolutos do usuário, credenciais em URL (`usuario:senha@host`), `curl | sh` e instruções para sobrepor regras ou pular aprovação. Ele **avisa** (sem bloquear) sobre comandos que destroem dados: apagar arquivos de banco ou de dados, `DROP`/`TRUNCATE`, `DELETE` sem `WHERE`, reset de migrações, `git reset --hard`, force push, remoção de volumes do Docker. Uma skill é uma instrução permanente, então um passo que só era seguro no estado de um momento não pode virar o padrão em silêncio.
+
+## Instalação
+
+Requer Node >= 20. Desenvolvido no macOS; no Linux deve funcionar, no Windows não foi testado.
+
+```bash
+# pelo npm (o comando é `brito`)
+npm i -g brito-cli
+
+# ou uma linha
+curl -fsSL https://raw.githubusercontent.com/wilsonbrito/brito/main/install.sh | bash
+
+# ou direto do GitHub
+npm i -g github:wilsonbrito/brito
+
+# ou clonando
+git clone https://github.com/wilsonbrito/brito && cd brito
+npm install && npm run build && npm link
+```
+
+Escolha um backend:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...      # API da Anthropic
+# ou: instale o Claude Code, rode `claude` e /login — o Brito usa a sua assinatura
+```
+
+## Começando
+
+```bash
+cd seu-projeto
+brito                       # abre o REPL
+brito "quem chama parseConfig?"   # prompt único, sem REPL
+brito index                 # (re)indexa o grafo; ele também se mantém atualizado sozinho
+brito query "MATCH (c:Symbol {kind:'component'})-[:CALLS]->(f:Symbol) RETURN c.file, f.name LIMIT 5"
+```
+
+Um `brito index` real no projeto de exemplo acima:
+
+```
+OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
+```
+
+![Tela inicial do Brito](docs/images/startup.png)
+
+### Dentro do REPL
+
+| Comando | O que faz |
+|---|---|
+| `/help` | lista os comandos |
+| `/model`, `/effort`, `/reasoning` | escolhem modelo, esforço de raciocínio e thinking (sessão, global ou uma vez) |
+| `/modo` ou `Shift+Tab` | troca o modo de permissão: manual → auto-edições → plano |
+| `/skills` | lista skills · `pending` · `approve <nome>` · `reject <nome>` · `consolidate` · `rm <nome>` · `promote <nome>` |
+| `/learn` | extrai skills do último turno agora |
+| `/agents`, `/tools`, `/index`, `/context` | inspecionam subagentes, tools, o índice e a janela de contexto |
+| `!comando` | roda um comando no shell direto, sem chamar o modelo |
+| `/clear`, `/exit` | limpa a conversa, sai |
+
+## O que o grafo indexa
+
+- **Linguagens:** TypeScript/JavaScript (`.ts .tsx .mts .cts .js .jsx .mjs .cjs`), Python (`.py`), linguagens de backend — Java (`.java`), Kotlin (`.kt`), Go (`.go`), Ruby (`.rb`), PHP (`.php`), C# (`.cs`), Rust (`.rs`) — e os componentes `.svelte`, `.vue` e `.astro`. Nos componentes o Brito lê o(s) bloco(s) de script (e o frontmatter do Astro) e registra as chamadas feitas no template a funções que o script declara ou importa; cada componente vira um símbolo `component`.
+- **Escopo:** em um repositório git, só o que o git considera parte do projeto (rastreados + novos não ignorados), então o que está no `.gitignore` não entra. Fora do git, ou com `BRITO_INDEX_IGNORED=1`, indexa por glob (ainda sem `node_modules`, `dist`, `build`, `target`, `vendor`, `obj`, `.gradle`, `.venv`, `.brito`).
+- **Imports:** relativos e por alias. Resolve `paths`/`baseUrl` do `tsconfig.json`/`jsconfig.json` (seguindo `extends` relativo, como o `.svelte-kit/tsconfig.json`), `imports` do `package.json` (`#interno/*`) e o `$lib` do SvelteKit. A configuração vale por arquivo (a mais próxima), então monorepos funcionam; editar um tsconfig reindexa os arquivos afetados.
+- **Linguagens de backend:** o grafo guarda classes/interfaces/structs/traits/enums/módulos, funções e métodos (`Classe.metodo`), chamadas e imports. Nelas o import nomeia um pacote, não um caminho; o Brito casa o especificador com o final do caminho dos seus arquivos (`com.acme.Repo` ↔ `src/main/java/com/acme/Repo.java`; namespaces PSR-4 do PHP; `use crate::…` do Rust; `require`/`require_relative` do Ruby; pacotes Go pelo módulo do `go.mod`). Pacote externo (`java.util`, `serde`, `github.com/gin-gonic/gin`) nunca casa e não gera aresta. Não há inferência de tipos: `userRepository.save()` é ligado casando o nome do receptor com um tipo do projeto (`UserRepository`), `this`/`self`/receiver resolvem para a classe que contém a chamada, e uma chamada solta dentro de classe tenta primeiro os métodos da própria classe.
+- **Ainda não:** `extends` por pacote (`@tsconfig/node20`), `exports` de workspaces vizinhos e referências de função sem chamada em um template (`onclick={fn}`). As chamadas são resolvidas estaticamente, com fallback por nome, então despacho dinâmico e reflexão não são capturados.
+
+## Bancos de dados e outros recursos sensíveis
+
+O Brito **não tem drivers de banco e não se conecta a nada sozinho**. Quando precisa mexer em um banco, usa as ferramentas do próprio projeto pelo shell, sob o modo de permissão que você escolheu. Como cada projeto é diferente (um arquivo local, um servidor remoto, um container), declare as partes sensíveis no `BRITO.md` (ou `CLAUDE.md` / `AGENTS.md`), que é lido para o system prompt:
+
+```markdown
+## Recursos protegidos
+- Banco: arquivo SQLite local `local.db` (nunca commitar, nunca recriar).
+  Teste mudanças destrutivas numa cópia: `cp local.db /tmp/teste.db` e aponte `DATABASE_URL`.
+  Mudanças de schema: só aditivas, com backup antes (`cp local.db backups/pre-mudanca.db`).
+- Postgres de staging: a connection string está em `$STAGING_DATABASE_URL` (papel somente leitura). Nunca toque em produção.
+```
+
+- Credenciais nunca pertencem a skills ou notas: o lint as rejeita. Cite o **nome** da variável de ambiente.
+- Prefira papéis somente leitura e ambientes que não sejam de produção ao dar acesso a banco para um agente.
+- Uma skill proposta que contém comando destrutivo é destacada na revisão, para você decidir se precisa de uma guarda (backup, cópia, confirmação).
+
+## Configuração
+
+`BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (onde ficam skills globais e histórico), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` ou `full`; padrão: tela cheia em janelas de 95+ colunas e 28+ linhas), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (tamanho mínimo do turno para disparar a reflexão quando nada mais dispara).
+
+Os dados do projeto ficam em `.brito/` (grafo, skills do projeto, agentes) e os globais em `~/.brito`. O grafo, a memória e as skills ficam na sua máquina; como em qualquer agente de código, o código que o modelo lê é enviado ao provedor de modelo que você configurou.
+
+## Limitações
+
+- Software em fase inicial (v0.3.1), um mantenedor.
+- **A interface e o idioma padrão do agente são português do Brasil.** Traduzi-los é uma contribuição bem-vinda.
+- O aprendizado de skills é heurístico: ele propõe, você decide. Espere rejeitar algumas propostas.
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/wilsonbrito/brito && cd brito
+npm install
+npm run dev          # roda via tsx
+npm run typecheck
+npm test             # 190+ testes, incluindo um servidor MCP real e um REPL real
+```
+
+| Caminho | O quê |
+|---|---|
+| `src/graph/` | indexador (tree-sitter), suporte a `.svelte/.vue/.astro`, aliases de import, store Kùzu |
+| `src/skills/` | store, lint, reflexão, journal, consolidação |
+| `src/agent/` | loop do agente, prompts, subagentes, backend da CLI `claude` |
+| `src/tools/` | tools de grafo, memória, skills, arquivos e shell |
+| `src/mcp/` | servidor MCP |
+| `src/repl.ts`, `src/ui/` | interface de terminal |
+
+## Licença
+
+[PolyForm Noncommercial 1.0.0](LICENSE): uso, estudo e modificação livres para qualquer fim não comercial (uso pessoal, pesquisa, educação, hobby, ONGs). Uso comercial não é permitido. É código disponível (source-available), não open source pela definição da OSI. Precisa de licença comercial? Abra uma issue.

package/dist/agent/agents.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../util/frontmatter.js";
+import { ui } from "../ui/ui.js";
+const READ_TOOLS = ["read_file", "glob", "grep", "graph_search", "graph_callers", "graph_callees", "graph_impact", "graph_context", "graph_query", "recall"];
+const BUILTIN = [
+    {
+        name: "explore",
+        description: "Somente leitura e rápido. Localiza código, mapeia fluxos e responde 'onde/como/quem chama' usando o grafo. Não edita nada.",
+        tools: READ_TOOLS,
+        model: process.env.BRITO_EXPLORE_MODEL ?? "claude-haiku-4-5-20251001",
+        prompt: "Você é um agente de exploração de código. Descubra o que foi pedido com o mínimo de leitura: comece pelo grafo (graph_search/graph_context/graph_callers/graph_callees), leia só os trechos apontados. Entregue achados com caminhos `arquivo:linha`, sem despejar código longo.",
+        source: "builtin",
+    },
+    {
+        name: "plan",
+        description: "Somente leitura. Analisa impacto e devolve um plano de implementação passo a passo (arquivos, símbolos, riscos). Não edita nada.",
+        tools: READ_TOOLS,
+        prompt: "Você é um arquiteto de software. Investigue via grafo (graph_context, graph_callers, graph_impact) e devolva um plano: passos ordenados, arquivos e símbolos a alterar, o que pode quebrar (impacto) e como verificar. Não implemente.",
+        source: "builtin",
+    },
+    {
+        name: "general",
+        description: "Executa uma tarefa completa e isolada, incluindo editar arquivos e rodar comandos (pede aprovação ao usuário). Use para sub-tarefas grandes que sujariam o seu contexto.",
+        tools: "all",
+        prompt: "Você é um agente de engenharia de software. Execute a tarefa até o fim, verifique o resultado (typecheck/testes quando existirem) e reporte o que mudou.",
+        source: "builtin",
+    },
+];
+const agents = new Map();
+for (const a of BUILTIN)
+    agents.set(a.name, a);
+export const getAgent = (name) => agents.get(name);
+export const listAgents = () => [...agents.values()];
+/** Agentes de projeto: `.brito/agents/*.md` com frontmatter (name, description, tools, model). */
+export function loadProjectAgents(root) {
+    const dir = path.join(root, ".brito", "agents");
+    if (!fs.existsSync(dir))
+        return [];
+    const loaded = [];
+    for (const f of fs.readdirSync(dir).filter((x) => x.endsWith(".md"))) {
+        const fm = parseFrontmatter(fs.readFileSync(path.join(dir, f), "utf8"));
+        if (!fm) {
+            ui.warn(`agente ignorado (.brito/agents/${f}): frontmatter ausente ou inválido`);
+            continue;
+        }
+        const { meta, body } = fm;
+        const name = meta.name ?? f.replace(/\.md$/, "");
+        if (!meta.description || !body.trim()) {
+            ui.warn(`agente ignorado (.brito/agents/${f}): precisa de description e corpo`);
+            continue;
+        }
+        const def = {
+            name,
+            description: meta.description,
+            tools: meta.tools ? meta.tools.split(",").map((t) => t.trim()).filter(Boolean) : "all",
+            model: meta.model || undefined,
+            prompt: body.trim(),
+            source: "project",
+        };
+        agents.set(name, def);
+        loaded.push(def);
+    }
+    return loaded;
+}