brito-cli 0.13.3 → 0.15.0

package/README.md

@@ -44,7 +44,7 @@ Upgrading from 0.9: `npm i -g brito-cli@latest`, and update the desktop app to t
 
 ```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")]
+    code["Your project<br/>.ts · .js · .py · .java · .kt · .go · .rb · .php · .cs · .rs · .svelte · .vue · .astro · .md"] -->|"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"]
@@ -191,7 +191,7 @@ OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
 
 ## 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.
+- **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. **Markdown (`.md`)** is indexed as a note graph (no tree-sitter): headings → `heading` symbols, frontmatter and `#tags` → `tag` symbols (`status:open`), `#123` mentions → `ref` symbols, and `[text](./b.md)` / `[[wikilinks]]` → file→file edges, so `graph_impact` on a note lists its backlinks. Frontmatter values that name another note (`pessoas: [ana]`) and numeric ids (`pendencias: [14]`) link too. For note vaults use `graph_notes_find` (filter by folder, field, date/number, links, `#N`), `graph_notes_backlinks` and `graph_notes_path` (follows relations between notes in one call; `{}` lists the vault's relations), no Cypher needed. On a real 318-note vault they cut ~28% of tokens (and ~48% of cost) at equal accuracy; see the CHANGELOG. 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.

package/README.pt-BR.md

@@ -44,7 +44,7 @@ Atualizando da 0.9: `npm i -g brito-cli@latest` e atualize o app de desktop para
 
 ```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")]
+    code["Seu projeto<br/>.ts · .js · .py · .java · .kt · .go · .rb · .php · .cs · .rs · .svelte · .vue · .astro · .md"] -->|"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"]
@@ -187,7 +187,7 @@ OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
 
 ## 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`.
+- **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`. **Markdown (`.md`)** entra como grafo de notas (sem tree-sitter): headings viram símbolos `heading`, frontmatter e `#tags` viram `tag` (`status:aberta`), menções `#123` viram `ref`, e `[texto](./b.md)` / `[[wikilinks]]` viram arestas arquivo→arquivo; `graph_impact` numa nota lista os backlinks. Valores de frontmatter que nomeiam outra nota (`pessoas: [ana]`) e ids numéricos (`pendencias: [14]`) também ligam. Para vaults de notas use `graph_notes_find` (filtro por pasta, campo, data/número, links, `#N`), `graph_notes_backlinks` e `graph_notes_path` (segue relações entre notas em uma chamada; `{}` lista as relações do vault), sem Cypher. Num vault real de 318 notas cortaram ~28% dos tokens (e ~48% do custo) com o mesmo acerto; veja o CHANGELOG. 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.

package/dist/cli.js

@@ -29,6 +29,7 @@ import { addRule, loadRules, projectSettingsPath } from "./rules.js";
 import { serveMcp } from "./mcp/server.js";
 import "./tools/skills.js";
 import "./tools/digest.js";
+import "./tools/vault.js";
 import { adviseSkill, approvePending, lintSkill, listBuiltins, listPending, listSkills, rejectPending, skillsIndex, staleRefs } from "./skills/store.js";
 import { applyProposal, autoConsolidate, describeProposal, proposeConsolidation, pruneCandidates } from "./skills/consolidate.js";
 import { defaultComplete, recordOutcomes, reflect, shouldReflect } from "./skills/learn.js";
@@ -57,7 +58,7 @@ program
     const g = await GraphStore.open(root);
     const t = Date.now();
     const s = await indexProject(root, g, { full: o.full, onProgress: (m) => console.log(m) });
-    console.log(`OK: ${s.files} arquivos, ${s.symbols} símbolos, ${s.calls} chamadas, ${s.imports} imports | +${s.added} ~${s.changed} -${s.removed} =${s.unchanged} (${Date.now() - t}ms)`);
+    console.log(`OK: ${s.files} arquivos, ${s.symbols} símbolos, ${s.calls} chamadas, ${s.imports} imports | +${s.added} ~${s.changed} -${s.removed} =${s.unchanged}${s.docs ? ` | ${s.docs} docs, ${s.secoes} seções, ${s.ligas} ligações, ${s.citas} citações, ${s.linksQuebrados} links sem destino` : ""} (${Date.now() - t}ms)`);
     await g.close();
 });
 program

package/dist/desktop/serve.js

@@ -17,6 +17,7 @@ import "../tools/implement.js";
 import "../tools/spec.js";
 import "../tools/skills.js";
 import "../tools/digest.js";
+import "../tools/vault.js";
 import "../tools/todo.js";
 import { Agent } from "../agent/loop.js";
 import { loadSession, repairHistory, saveSession, titleOf } from "../agent/sessions.js";

package/dist/graph/indexer.js

@@ -7,6 +7,8 @@ import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
 import { SFC_EXT, componentName, splitSfc, templateCalleeNames } from "./sfc.js";
 import { Aliases, aliasCandidates } from "./aliases.js";
+import { IDREF_PREFIX, IdIndex, MD_EXT, WIKI_PREFIX, WikiIndex, extractMarkdown } from "./markdown.js";
+import { indexSections } from "./sections.js";
 import { EXTRA_EXT, ProjectIndex, extractLang, isExtraLang } from "./langs.js";
 const require = createRequire(import.meta.url);
 const WASM_DIR = path.dirname(require.resolve("tree-sitter-wasms/package.json")) + "/out";
@@ -14,6 +16,7 @@ const EXT = {
     ".ts": "typescript", ".mts": "typescript", ".cts": "typescript",
     ".tsx": "tsx", ".js": "javascript", ".jsx": "javascript", ".mjs": "javascript", ".cjs": "javascript",
     ".py": "python",
+    ".md": "markdown", ".markdown": "markdown",
     ...EXTRA_EXT,
 };
 /** Tudo que o grafo indexa: código em EXT e os scripts de componentes (.svelte/.vue/.astro). Usado também nas instruções do MCP. */
@@ -188,7 +191,7 @@ function resolveImport(from, spec, known, aliases) {
     }
     return null;
 }
-const INDEXER_VERSION = "v4";
+const INDEXER_VERSION = "v7";
 const TYPE_KINDS = new Set(["class", "interface", "struct", "trait", "enum", "module", "type"]);
 const JS_LIKE_RE = /\.(m|c)?[jt]sx?$|\.py$|\.svelte$|\.vue$|\.astro$/;
 const SEP = "\t";
@@ -245,7 +248,9 @@ const count = async (store, q) => Number((await store.run(q))[0].n);
 export async function indexProject(root, store, opts = {}) {
     const release = await acquireIndexLock(root, opts.onProgress);
     try {
-        return await indexProjectLocked(root, store, opts);
+        const code = await indexProjectLocked(root, store, opts);
+        const md = await indexSections(root, store, opts);
+        return { ...code, docs: md.docs, secoes: md.secoes, ligas: md.ligas, citas: md.citas, linksQuebrados: md.unresolved, mdChanged: md.added + md.changed + md.removed };
     }
     finally {
         release();
@@ -341,9 +346,15 @@ async function indexProjectLocked(root, store, opts = {}) {
         // Componente (.svelte/.vue/.astro): o parser vê só os blocos de script; o template vira chamadas de um símbolo próprio.
         const sfc = SFC_EXT.has(ext) ? splitSfc(src, ext) : null;
         const lang = sfc ? (sfc.tsx ? "tsx" : "typescript") : EXT[ext];
-        const tree = (await getParser(lang)).parse(sfc ? sfc.script : src);
-        const info = isExtraLang(lang) ? extractLang(tree.rootNode, lang, rel) : extract(tree.rootNode, lang, rel);
-        tree.delete();
+        let info;
+        if (MD_EXT.has(ext.toLowerCase())) { // markdown: sem parser, só estrutura e links
+            info = { ...extractMarkdown(src, rel), calls: [], bindings: [] };
+        }
+        else {
+            const tree = (await getParser(lang)).parse(sfc ? sfc.script : src);
+            info = isExtraLang(lang) ? extractLang(tree.rootNode, lang, rel) : extract(tree.rootNode, lang, rel);
+            tree.delete();
+        }
         if (sfc) {
             const name = componentName(rel);
             const comp = { id: `${rel}::${name}:1`, name, kind: "component", file: rel, startLine: 1, endLine: src.split("\n").length };
@@ -355,9 +366,8 @@ async function indexProjectLocked(root, store, opts = {}) {
         const calls = [...new Set(info.calls.filter((c) => c.callerId).map((c) => [c.callerId, c.callee, c.obj].join(SEP)))];
         const bindings = [...new Set(info.bindings.map((b) => b.join(SEP)))];
         await store.run("CREATE (:File {path:$p, lang:$l, hash:$h, calls:$c, imports:$i, bindings:$b})", { p: rel, l: sfc ? ext.slice(1) : lang, h: hash, c: calls, i: [...new Set(info.imports)], b: bindings });
-        for (const s of info.syms) {
-            await store.run("CREATE (:Symbol {id:$id, name:$n, kind:$k, file:$f, startLine:$s, endLine:$e})", { id: s.id, n: s.name, k: s.kind, f: s.file, s: s.startLine, e: s.endLine });
-            await store.run("MATCH (f:File {path:$f}), (s:Symbol {id:$id}) CREATE (f)-[:DEFINES]->(s)", { f: rel, id: s.id });
+        for (const s of info.syms) { // símbolo e DEFINES numa query só: metade das idas ao banco
+            await store.run("MATCH (f:File {path:$f}) CREATE (f)-[:DEFINES]->(:Symbol {id:$id, name:$n, kind:$k, file:$f, startLine:$s, endLine:$e})", { id: s.id, n: s.name, k: s.kind, f: s.file, s: s.startLine, e: s.endLine });
         }
         stored.set(rel, { hash, calls, imports: [...new Set(info.imports)], bindings });
         await store.yieldIfWaited(); // dá a vez a outra sessão que só quer consultar
@@ -365,8 +375,14 @@ async function indexProjectLocked(root, store, opts = {}) {
     // 3. Recalcula arestas desejadas em memória (sem parsear) e aplica diff.
     const known = new Set(stored.keys());
     const projectIndex = new ProjectIndex(root, known);
+    const wikiIndex = new WikiIndex(known);
+    const idIndex = new IdIndex((await store.run("MATCH (s:Symbol) WHERE s.kind = 'tag' AND s.name STARTS WITH 'id:' RETURN s.file AS file, s.name AS name")).map((r) => ({ file: String(r.file), name: String(r.name) })));
     /** Arquivos que um import pode designar: vários em linguagens de pacote (Go, Java/Kotlin com wildcard), no máximo um em TS/Python. */
     const resolveAll = (from, spec) => {
+        if (spec.startsWith(WIKI_PREFIX))
+            return wikiIndex.resolve(spec);
+        if (spec.startsWith(IDREF_PREFIX))
+            return idIndex.resolve(spec);
         const r = projectIndex.resolve(from, spec);
         if (r)
             return r;

package/dist/graph/markdown.js

@@ -0,0 +1,168 @@
+/**
+ * Markdown no grafo (sem tree-sitter): vault de notas vira rede de relações.
+ *  - heading            → Symbol `heading` (nível no nome não; faixa de linhas até o próximo heading do mesmo nível ou acima)
+ *  - frontmatter        → Symbol `tag` com nome `chave:valor` (status:aberta, pessoa:Xande…); listas viram vários; `null` é ignorado.
+ *                         Valor que é o nome de outra nota (pessoas: [adonis-santos]) também vira link para ela
+ *  - #tag no texto      → Symbol `tag` com nome `#tag`
+ *  - menção #123        → Symbol `ref` com nome `#123` (mesmo número em notas diferentes = mesmo assunto)
+ *  - [texto](./b.md)    → import relativo (aresta File→File)
+ *  - [[Nota]] / [[Nota|alias]] / [[Nota#Seção]] → import `wiki:nota`, resolvido pelo nome do arquivo
+ */
+export const MD_EXT = new Set([".md", ".markdown"]);
+export const WIKI_PREFIX = "wiki:";
+export const IDREF_PREFIX = "idref:";
+const clip = (s, n = 80) => (s.length > n ? s.slice(0, n) : s);
+const unquote = (s) => s.trim().replace(/^(['"])(.*)\1$/, "$2").trim();
+/** Subconjunto de YAML que notas usam: `k: v`, `k: [a, b]` e lista `- item` abaixo de `k:`. Devolve pares chave/valor. */
+function frontmatter(lines) {
+    if (lines[0]?.trim() !== "---")
+        return { pairs: [], end: 0 };
+    let close = -1;
+    for (let i = 1; i < lines.length; i++)
+        if (/^(---|\.\.\.)\s*$/.test(lines[i])) {
+            close = i;
+            break;
+        }
+    if (close < 0)
+        return { pairs: [], end: 0 };
+    const pairs = [];
+    let key = "";
+    for (const raw of lines.slice(1, close)) {
+        const item = raw.match(/^\s+-\s+(.*)$/);
+        if (item && key) {
+            const v = unquote(item[1]);
+            if (v)
+                pairs.push([key, v]);
+            continue;
+        }
+        const kv = raw.match(/^([A-Za-zÀ-ÿ0-9_-]+)\s*:\s*(.*)$/);
+        if (!kv)
+            continue;
+        key = kv[1].toLowerCase();
+        const val = kv[2].trim();
+        if (!val)
+            continue;
+        if (val.startsWith("[") && val.endsWith("]"))
+            for (const v of val.slice(1, -1).split(",")) {
+                const u = unquote(v);
+                if (u)
+                    pairs.push([key, u]);
+            }
+        else
+            pairs.push([key, unquote(val)]);
+    }
+    return { pairs, end: close + 1 };
+}
+export function extractMarkdown(src, file) {
+    const lines = src.split(/\r?\n/);
+    const syms = [];
+    const imports = [];
+    const seen = new Set();
+    const add = (name, kind, line, endLine = line) => {
+        const id = `${file}::${name}:${line}`;
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        syms.push({ id, name, kind, file, startLine: line, endLine });
+    };
+    const fm = frontmatter(lines);
+    for (const [k, v] of fm.pairs) {
+        if (/^(null|~|none)$/i.test(v))
+            continue; // campo vazio (concluida_em: null) é ruído
+        add(clip(`${k}:${v}`), "tag", 1, fm.end);
+        // valor que é o nome de outra nota (pessoas: [adonis-santos]) vira link; sem nota com esse nome, não liga nada
+        if (/^[\w][\w.-]{2,}$/.test(v) && !/^\d/.test(v))
+            imports.push(WIKI_PREFIX + v.toLowerCase());
+        // número em campo plural (pendencias: [14]) aponta para a nota com `id: 14` na pasta de mesmo nome (pendencias/)
+        else if (/^\d+$/.test(v) && k !== "id")
+            imports.push(`${IDREF_PREFIX}${k}:${v}`);
+    }
+    const heads = [];
+    let fence = null;
+    const refs = new Set();
+    for (let i = fm.end; i < lines.length; i++) {
+        const line = lines[i];
+        const f = line.match(/^\s*(```+|~~~+)/);
+        if (f) {
+            fence = fence === null ? f[1][0] : fence === f[1][0] ? null : fence;
+            continue;
+        }
+        if (fence !== null)
+            continue;
+        const h = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+        if (h)
+            heads.push({ level: h[1].length, name: clip(h[2].replace(/[*_`]/g, "")), line: i + 1 });
+        // texto sem código inline: não interpreta `[[x]]` nem `#1` dentro de crase
+        const text = line.replace(/`[^`]*`/g, "");
+        for (const m of text.matchAll(/\[\[([^\]\n]+)\]\]/g)) {
+            const target = m[1].split("|")[0].split("#")[0].trim();
+            if (target)
+                imports.push(WIKI_PREFIX + target.toLowerCase());
+        }
+        for (const m of text.matchAll(/(?<!!)\[[^\]\n]*\]\(\s*<?([^)\s>]+)>?[^)]*\)/g)) {
+            let t = m[1];
+            if (/^([a-z][a-z0-9+.-]*:|#|\/\/)/i.test(t))
+                continue; // http:, mailto:, âncora
+            t = t.split("#")[0].split("?")[0];
+            if (!t)
+                continue;
+            try {
+                t = decodeURIComponent(t);
+            }
+            catch { /* mantém como veio */ }
+            imports.push(t.startsWith(".") || t.startsWith("/") ? t : "./" + t);
+        }
+        const body = h ? "" : text.replace(/\[\[[^\]]*\]\]|\]\([^)]*\)/g, " "); // não conta URL/âncora como tag
+        for (const m of body.matchAll(/(?:^|[\s(])#(\d+)\b/g))
+            refs.add("#" + m[1]);
+        for (const m of body.matchAll(/(?:^|[\s(])#([A-Za-zÀ-ÿ][\w/-]*)/g))
+            add("#" + m[1].toLowerCase(), "tag", i + 1);
+    }
+    for (const r of refs) {
+        const line = lines.findIndex((l, i) => i >= fm.end && l.includes(r)) + 1;
+        add(r, "ref", line || 1);
+    }
+    heads.forEach((h, i) => {
+        const next = heads.slice(i + 1).find((x) => x.level <= h.level);
+        add(h.name, "heading", h.line, next ? next.line - 1 : lines.length);
+    });
+    return { syms, imports };
+}
+/** Resolve `wiki:nome` para notas indexadas pelo nome do arquivo (sem extensão, sem caixa) ou pelo caminho relativo. */
+export class WikiIndex {
+    byBase = new Map();
+    constructor(files) {
+        for (const f of files) {
+            const dot = f.lastIndexOf(".");
+            if (!MD_EXT.has(dot < 0 ? "" : f.slice(dot).toLowerCase()))
+                continue;
+            const noExt = f.slice(0, dot).toLowerCase();
+            for (const key of new Set([noExt.split("/").pop(), noExt]))
+                (this.byBase.get(key) ?? this.byBase.set(key, []).get(key)).push(f);
+        }
+    }
+    /** Vários candidatos = nome ambíguo: liga a todos (o usuário vê o conflito no grafo). */
+    resolve(spec) {
+        const t = spec.slice(WIKI_PREFIX.length).replace(/\.(md|markdown)$/i, "");
+        return this.byBase.get(t) ?? [];
+    }
+}
+/** Resolve `idref:<campo>:<n>` para a nota da pasta `<campo>/` cujo frontmatter tem `id: n` (pendencias: [14] → pendencias/014-….md). */
+export class IdIndex {
+    byKey = new Map();
+    /** tags: pares (arquivo, nome do tag) com nome `id:N` */
+    constructor(tags) {
+        for (const t of tags) {
+            const m = /^id:(\d+)$/.exec(t.name);
+            if (!m)
+                continue;
+            const folder = t.file.includes("/") ? t.file.split("/")[0].toLowerCase() : "";
+            const key = `${folder}:${Number(m[1])}`;
+            (this.byKey.get(key) ?? this.byKey.set(key, []).get(key)).push(t.file);
+        }
+    }
+    resolve(spec) {
+        const m = /^idref:([^:]+):(\d+)$/.exec(spec);
+        return m ? this.byKey.get(`${m[1].toLowerCase()}:${Number(m[2])}`) ?? [] : [];
+    }
+}

package/dist/graph/sections.js

@@ -0,0 +1,244 @@
+/**
+ * Markdown como cidadão do grafo: cada .md vira um Doc, cada cabeçalho uma Secao (com texto e linhas), os [[wikilinks]]
+ * viram LIGA entre Docs e as passagens bíblicas viram CITA → Passagem. Parser puro (sem banco) + indexação incremental.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+export const SECTIONS_VERSION = "m1";
+const MD_RE = /\.(md|markdown)$/i;
+/** Formatos que só viram metadado (Doc sem seções): a fonte de verdade é o .md derivado deles. */
+const META_RE = /\.(pdf|epub|docx)$/i;
+const IGNORE_RE = /(^|\/)(node_modules|dist|build|\.git|\.brito|\.venv|target|vendor)(\/|$)|(^|\/)\./;
+const MAX_MD_BYTES = 5_000_000;
+/** Siglas da NAA (e variantes sem acento); só estas valem como livro, para não confundir "Cap 3" com passagem. */
+const LIVROS = new Set(("Gn Êx Ex Lv Nm Dt Js Jz Rt 1Sm 2Sm 1Rs 2Rs 1Cr 2Cr Ed Ne Et Jó Sl Pv Ec Ct Is Jr Lm Ez Dn Os Jl Am Ob Jn Mq Na Hc Sf Ag Zc Ml " +
+    "Mt Mc Lc Jo At Rm 1Co 2Co Gl Ef Fp Cl 1Ts 2Ts 1Tm 2Tm Tt Fm Hb Tg 1Pe 2Pe 1Jo 2Jo 3Jo Jd Ap").split(" "));
+/** "Rm 9.13; Rm 3.25-26; Ob 15" → ["Rm 9.13","Rm 3.25","Rm 3.26","Ob 15"]. Intervalo vira um item por versículo (máx. 60). */
+export function parsePassagens(txt) {
+    const out = [];
+    for (const m of txt.normalize("NFC").matchAll(/(?<![\p{L}\d])(\d?[A-Za-zÀ-ÿ]+)\s+(\d+)(?:\.(\d+)(?:-(\d+))?)?(?![\d])/gu)) {
+        const [, livro, cap, v1, v2] = m;
+        if (!LIVROS.has(livro))
+            continue;
+        if (v1 === undefined) {
+            out.push(`${livro} ${cap}`);
+            continue;
+        }
+        for (let v = +v1; v <= +(v2 || v1) && v - +v1 < 60; v++)
+            out.push(`${livro} ${cap}.${v}`);
+    }
+    return [...new Set(out)];
+}
+/** Frontmatter simples (chave: valor, inclusive listas inline). Retorna também quantas linhas ele ocupa. */
+export function splitFrontmatter(txt) {
+    const m = txt.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+    if (!m)
+        return { fm: {}, corpo: txt, linhas: 0 };
+    const fm = {};
+    for (const l of m[1].split(/\r?\n/)) {
+        const k = l.match(/^([\p{L}\d_-]+):\s*(.*)$/u);
+        if (k)
+            fm[k[1]] = k[2].replace(/^["']|["']$/g, "");
+    }
+    return { fm, corpo: txt.slice(m[0].length), linhas: m[0].split("\n").length - 1 };
+}
+const wikilinks = (t) => [...t.matchAll(/\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g)].map((m) => m[1].trim()).filter(Boolean);
+/** Tira blocos e trechos de código (os cabeçalhos e [[links]] dentro deles são exemplo, não estrutura). */
+const semCodigo = (t) => t.replace(/^(```|~~~)[\s\S]*?^\1[^\n]*$/gm, "").replace(/`[^`\n]*`/g, "");
+export function parseMarkdown(rel, src) {
+    const { fm, corpo, linhas: offset } = splitFrontmatter(src);
+    const h1 = corpo.match(/^#\s+(.+)$/m);
+    const tipo = (fm.tipo || rel.split("/")[0] || "").toLowerCase();
+    const secoes = [];
+    let atual = { nivel: 0, titulo: "(abertura)", buf: [], start: offset + 1 };
+    let ordem = 0, fence = null;
+    const lines = corpo.split("\n");
+    const fecha = (fim) => {
+        const texto = atual.buf.join("\n").trim();
+        if (texto || atual.nivel)
+            secoes.push({ id: `${rel}#${ordem}`, nivel: atual.nivel, titulo: atual.titulo, ordem: ordem++, texto, startLine: atual.start, endLine: Math.max(atual.start, fim) });
+    };
+    lines.forEach((raw, i) => {
+        const l = raw.replace(/\r$/, "");
+        const f = l.match(/^(```|~~~)/);
+        if (f)
+            fence = fence === null ? f[1] : fence === f[1] ? null : fence;
+        const h = fence === null && !f ? l.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/) : null;
+        if (h) {
+            fecha(offset + i);
+            atual = { nivel: h[1].length, titulo: h[2].trim(), buf: [], start: offset + i + 1 };
+        }
+        else
+            atual.buf.push(l);
+    });
+    fecha(offset + lines.length);
+    const links = [];
+    const modelo = rel.startsWith("Modelos/");
+    if (!modelo) {
+        for (const [k, v] of Object.entries(fm))
+            for (const a of wikilinks(v))
+                links.push({ tipo: k, alvo: a });
+        for (const a of wikilinks(semCodigo(corpo)))
+            links.push({ tipo: "menciona", alvo: a });
+    }
+    let passagens = [];
+    if (!modelo) {
+        if (fm.passagens)
+            passagens = parsePassagens(fm.passagens);
+        if (tipo === "tema") {
+            const bb = secoes.find((s) => /^Base bíblica/i.test(s.titulo));
+            if (bb)
+                passagens = passagens.concat(parsePassagens(bb.texto));
+        }
+    }
+    return {
+        path: rel, tipo, titulo: fm.titulo || h1?.[1].trim() || path.basename(rel).replace(MD_RE, ""),
+        ano: fm.ano || "", status: fm.status || "", tamanho: Buffer.byteLength(src), secoes, links, passagens: [...new Set(passagens)],
+    };
+}
+/** Nome → caminho, comparando em NFC e sem diferenciar caixa (links do macOS vêm decompostos). Nome repetido: vale o 1º por ordem de caminho. */
+export function linkResolver(paths) {
+    const nfc = (s) => s.normalize("NFC").toLowerCase();
+    const map = new Map();
+    const add = (k, p) => { const a = map.get(k) ?? map.set(k, []).get(k); if (!a.includes(p))
+        a.push(p); };
+    for (const p of [...paths].sort()) {
+        const noExt = p.replace(MD_RE, "");
+        add(nfc(p), p);
+        add(nfc(noExt), p);
+        add(nfc(path.posix.basename(p)), p);
+        add(nfc(path.posix.basename(noExt)), p);
+    }
+    return (alvo, de) => {
+        const c = map.get(nfc(alvo));
+        if (!c)
+            return null;
+        const top = de.split("/")[0];
+        return c.find((x) => x.split("/")[0] === top) ?? c[0]; // ambíguo: prefere a mesma pasta raiz
+    };
+}
+function listFiles(root) {
+    if (process.env.BRITO_INDEX_IGNORED !== "1") {
+        const r = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+        if (!r.error && r.status === 0)
+            return r.stdout.split("\0").filter(Boolean).filter((f) => !IGNORE_RE.test(f) && fs.existsSync(path.join(root, f)));
+    }
+    const out = [];
+    const walk = (dir) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (e.name.startsWith(".") || IGNORE_RE.test(e.name))
+                continue;
+            const p = path.join(dir, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else
+                out.push(path.relative(root, p).split(path.sep).join("/"));
+        }
+    };
+    walk(root);
+    return out;
+}
+/** Indexação incremental dos .md (e metadados de pdf/epub/docx): só reparseia o que mudou; as LIGA são recalculadas em memória e aplicadas por diff. */
+export async function indexSections(root, store, opts = {}) {
+    const files = listFiles(root).filter((f) => MD_RE.test(f) || META_RE.test(f));
+    if (!files.length) {
+        const had = Number((await store.run("MATCH (d:Doc) RETURN count(d) AS n"))[0].n);
+        if (had)
+            await store.run("MATCH (d:Doc) DETACH DELETE d");
+        return { docs: 0, secoes: 0, ligas: 0, citas: 0, added: 0, changed: 0, removed: had, unresolved: 0 };
+    }
+    if (opts.full) {
+        await store.run("MATCH (s:Secao) DETACH DELETE s");
+        await store.run("MATCH (d:Doc) DETACH DELETE d");
+        await store.run("MATCH (p:Passagem) DELETE p");
+    }
+    const stored = new Map();
+    for (const r of await store.run("MATCH (d:Doc) RETURN d.path AS p, d.hash AS h"))
+        stored.set(r.p, r.h ?? "");
+    const current = new Map();
+    for (const rel of files) {
+        const abs = path.join(root, rel);
+        try {
+            const st = fs.statSync(abs);
+            if (MD_RE.test(rel)) {
+                if (st.size > MAX_MD_BYTES)
+                    continue;
+                const src = fs.readFileSync(abs, "utf8");
+                current.set(rel, { src, size: st.size, hash: crypto.createHash("sha1").update(src).digest("hex") + ":" + SECTIONS_VERSION });
+            }
+            else
+                current.set(rel, { size: st.size, hash: `meta:${st.size}:${SECTIONS_VERSION}` });
+        }
+        catch { /* ilegível: ignora */ }
+    }
+    const added = [], changed = [], removed = [];
+    for (const [p, { hash }] of current) {
+        const old = stored.get(p);
+        if (old === undefined)
+            added.push(p);
+        else if (old !== hash)
+            changed.push(p);
+    }
+    for (const p of stored.keys())
+        if (!current.has(p))
+            removed.push(p);
+    if (added.length + changed.length + removed.length)
+        opts.onProgress?.(`markdown: +${added.length} ~${changed.length} -${removed.length}`);
+    for (const p of [...removed, ...changed]) {
+        await store.run("MATCH (s:Secao {doc:$p}) DETACH DELETE s", { p });
+        await store.run("MATCH (d:Doc {path:$p}) DETACH DELETE d", { p });
+    }
+    const parsed = new Map();
+    for (const rel of [...added, ...changed]) {
+        const c = current.get(rel);
+        const doc = c.src !== undefined ? parseMarkdown(rel, c.src)
+            : { path: rel, tipo: path.extname(rel).slice(1).toLowerCase(), titulo: path.basename(rel), ano: "", status: "", tamanho: c.size, secoes: [], links: [], passagens: [] };
+        parsed.set(rel, doc);
+        await store.run("CREATE (:Doc {path:$path, tipo:$tipo, titulo:$titulo, ano:$ano, status:$status, tamanho:$tamanho, hash:$hash, links:$links})", { path: rel, tipo: doc.tipo, titulo: doc.titulo, ano: doc.ano, status: doc.status, tamanho: doc.tamanho, hash: c.hash, links: doc.links.map((l) => `${l.tipo}\t${l.alvo}`) });
+        for (const s of doc.secoes) {
+            await store.run("MATCH (d:Doc {path:$doc}) CREATE (d)-[:TEM_SECAO]->(:Secao {id:$id, doc:$doc, nivel:$nivel, titulo:$titulo, ordem:$ordem, texto:$texto, startLine:$sl, endLine:$el})", { doc: rel, id: s.id, nivel: s.nivel, titulo: s.titulo, ordem: s.ordem, texto: s.texto, sl: s.startLine, el: s.endLine });
+        }
+        for (const ref of doc.passagens) {
+            await store.run("MERGE (p:Passagem {ref:$ref})", { ref });
+            await store.run("MATCH (d:Doc {path:$d}), (p:Passagem {ref:$ref}) CREATE (d)-[:CITA]->(p)", { d: rel, ref });
+        }
+        await store.yieldIfWaited();
+    }
+    // LIGA: recalculada em memória a partir dos links crus guardados em cada Doc; aplica só a diferença.
+    const resolve = linkResolver(current.keys());
+    const want = new Set();
+    let unresolved = 0;
+    const raw = new Map();
+    for (const r of await store.run("MATCH (d:Doc) RETURN d.path AS p, d.links AS l"))
+        raw.set(r.p, r.l ?? []);
+    for (const [de, ls] of raw) {
+        for (const l of ls) {
+            const [tipo, alvo] = l.split("\t");
+            const para = resolve(alvo, de);
+            if (!para) {
+                unresolved++;
+                continue;
+            }
+            if (para !== de)
+                want.add([de, para, tipo].join("\t"));
+        }
+    }
+    const have = new Set((await store.run("MATCH (a:Doc)-[r:LIGA]->(b:Doc) RETURN a.path AS a, b.path AS b, r.tipo AS t")).map((r) => [r.a, r.b, r.t].join("\t")));
+    for (const k of have)
+        if (!want.has(k)) {
+            const [a, b, t] = k.split("\t");
+            await store.run("MATCH (x:Doc {path:$a})-[r:LIGA {tipo:$t}]->(y:Doc {path:$b}) DELETE r", { a, b, t });
+        }
+    for (const k of want)
+        if (!have.has(k)) {
+            const [a, b, t] = k.split("\t");
+            await store.run("MATCH (x:Doc {path:$a}), (y:Doc {path:$b}) CREATE (x)-[:LIGA {tipo:$t}]->(y)", { a, b, t });
+        }
+    const n = async (q) => Number((await store.run(q))[0].n);
+    return {
+        docs: current.size, secoes: await n("MATCH (s:Secao) RETURN count(s) AS n"), ligas: want.size, citas: await n("MATCH ()-[r:CITA]->() RETURN count(r) AS n"),
+        added: added.length, changed: changed.length, removed: removed.length, unresolved,
+    };
+}

package/dist/graph/store.js

@@ -149,12 +149,24 @@ export class GraphStore {
             "CREATE REL TABLE IF NOT EXISTS DEFINES(FROM File TO Symbol)",
             "CREATE REL TABLE IF NOT EXISTS CALLS(FROM Symbol TO Symbol)",
             "CREATE REL TABLE IF NOT EXISTS IMPORTS(FROM File TO File)",
+            // Markdown: Doc por arquivo, Secao por cabeçalho, LIGA = [[wikilink]], CITA = passagem bíblica.
+            "CREATE NODE TABLE IF NOT EXISTS Doc(path STRING, tipo STRING, titulo STRING, ano STRING, status STRING, tamanho INT64, PRIMARY KEY(path))",
+            "CREATE NODE TABLE IF NOT EXISTS Secao(id STRING, doc STRING, nivel INT64, titulo STRING, ordem INT64, texto STRING, PRIMARY KEY(id))",
+            "CREATE NODE TABLE IF NOT EXISTS Passagem(ref STRING, PRIMARY KEY(ref))",
+            "CREATE REL TABLE IF NOT EXISTS TEM_SECAO(FROM Doc TO Secao)",
+            "CREATE REL TABLE IF NOT EXISTS CITA(FROM Doc TO Passagem)",
+            "CREATE REL TABLE IF NOT EXISTS LIGA(FROM Doc TO Doc, tipo STRING)",
         ];
         for (const q of ddl)
             await drain(await this.conn.query(q), false);
         // Bancos criados antes do indexador incremental não têm estas colunas.
         for (const col of ["calls", "imports", "bindings"])
             await drain(await this.conn.query(`ALTER TABLE File ADD IF NOT EXISTS ${col} STRING[] DEFAULT []`), false);
+        for (const q of [
+            "ALTER TABLE Doc ADD IF NOT EXISTS hash STRING DEFAULT ''", "ALTER TABLE Doc ADD IF NOT EXISTS links STRING[] DEFAULT []",
+            "ALTER TABLE Secao ADD IF NOT EXISTS startLine INT64 DEFAULT 0", "ALTER TABLE Secao ADD IF NOT EXISTS endLine INT64 DEFAULT 0",
+        ])
+            await drain(await this.conn.query(q), false);
     }
     /** Serializa as queries: leituras paralelas de subagentes dividem uma única Connection. */
     run(cypher, params = {}, forceWrite = false) {

package/dist/graph/vault.js

@@ -0,0 +1,108 @@
+/**
+ * Busca no cofre de Markdown: seções do grafo (Secao) + trechos de livros/aulas do índice SQLite FTS5 (.brito/textos.db,
+ * mantido por Modelos/buscar.py). Cada resultado traz arquivo, linhas ou página e um trecho curto; o 1º também traz os
+ * vizinhos do grafo (LIGA), para o agente seguir o link sem abrir o arquivo.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const fold = (s) => s.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+const terms = (q) => [...new Set(fold(q).match(/[\p{L}\p{N}]+/gu) ?? [])].filter((t) => t.length > 1 || /\d/.test(t));
+function snippet(texto, ts, width = 220) {
+    const flat = texto.replace(/\s+/g, " ");
+    const f = fold(flat); // fold remove só marcas combinantes: comprimento igual ao de `flat` em texto já em NFC
+    let at = -1;
+    for (const t of ts) {
+        const i = f.indexOf(t);
+        if (i >= 0 && (at < 0 || i < at))
+            at = i;
+    }
+    const a = Math.max(0, (at < 0 ? 0 : at) - 60);
+    return (a ? "… " : "") + flat.slice(a, a + width).trim() + (a + width < flat.length ? " …" : "");
+}
+/** Seções do grafo que contêm TODAS as palavras (sem acento nem caixa). Título pesa mais; frase exata ganha bônus. */
+export async function searchSecoes(graph, query, opts = {}) {
+    const ts = terms(query);
+    if (!ts.length)
+        return [];
+    const rows = await graph.run("MATCH (s:Secao) RETURN s.doc AS doc, s.titulo AS titulo, s.texto AS texto, s.startLine AS a, s.endLine AS b");
+    const em = opts.em ? fold(opts.em) : "";
+    const phrase = ts.join(" ");
+    const hits = [];
+    for (const r of rows) {
+        if (em && !fold(r.doc).includes(em))
+            continue;
+        const f = fold(`${r.titulo}\n${r.texto}`), ft = fold(r.titulo);
+        if (!ts.every((t) => f.includes(t)))
+            continue;
+        let score = 0;
+        for (const t of ts) {
+            score += Math.min(5, f.split(t).length - 1);
+            if (ft.includes(t))
+                score += 5;
+        }
+        if (f.replace(/\s+/g, " ").includes(phrase))
+            score += 6;
+        score /= 1 + Math.log10(1 + f.length / 2000); // não premia seção gigante só por ser longa
+        hits.push({ kind: "md", doc: r.doc, where: `${r.doc}:${r.a}-${r.b}`, title: r.titulo, snippet: snippet(r.texto || r.titulo, ts), score });
+    }
+    return hits.sort((x, y) => y.score - x.score).slice(0, opts.limit ?? 6);
+}
+/** Trechos de livros/aulas (Textos/*.txt) pelo FTS5 do SQLite; vazio se o índice não existe ou o node não tem node:sqlite. */
+export async function searchTextos(root, query, opts = {}) {
+    const file = path.join(root, ".brito", "textos.db");
+    if (!fs.existsSync(file))
+        return [];
+    const ts = terms(query);
+    if (!ts.length)
+        return [];
+    let sqlite;
+    try {
+        sqlite = await import("node:sqlite");
+    }
+    catch {
+        return [];
+    }
+    const db = new sqlite.DatabaseSync(file, { readOnly: true });
+    try {
+        const sql = "SELECT path, loc, snippet(trechos, 2, '«', '»', ' … ', 24) AS t FROM trechos WHERE trechos MATCH ?" + (opts.em ? " AND path LIKE ?" : "") + " ORDER BY rank LIMIT ?";
+        for (const match of [`"${ts.join(" ")}"`, ts.map((t) => `"${t}"`).join(" ")]) { // 1º frase exata, depois todas as palavras
+            const rows = db.prepare(sql).all(...[match, ...(opts.em ? [`%${opts.em}%`] : []), opts.limit ?? 6]);
+            if (rows.length)
+                return rows.map((r, i) => ({ kind: "texto", where: `${r.path.replaceAll("\\", "/")} (${r.loc})`, title: path.basename(r.path).replace(/\.txt$/, ""), snippet: r.t, score: rows.length - i }));
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+    finally {
+        db.close();
+    }
+}
+/** Docs ligados ao documento (entrada e saída), com o tipo da ligação. */
+export async function neighbors(graph, doc, limit = 8) {
+    const out = await graph.run("MATCH (a:Doc {path:$p})-[r:LIGA]->(b:Doc) RETURN b.path AS p, r.tipo AS t LIMIT $n", { p: doc, n: limit });
+    const inn = await graph.run("MATCH (b:Doc)-[r:LIGA]->(a:Doc {path:$p}) RETURN b.path AS p, r.tipo AS t LIMIT $n", { p: doc, n: limit });
+    return [...out.map((r) => `→ ${r.p} (${r.t})`), ...inn.map((r) => `← ${r.p} (${r.t})`)].slice(0, limit);
+}
+export async function vaultSearch(root, graph, query, opts = {}) {
+    const md = await searchSecoes(graph, query, opts);
+    const tx = opts.textos === false ? [] : await searchTextos(root, query, opts);
+    if (!md.length && !tx.length)
+        return "nada encontrado (tente menos palavras ou outra forma da palavra)";
+    const lines = [];
+    if (md.length) {
+        lines.push("## Notas do cofre (.md)");
+        for (const h of md)
+            lines.push(`- ${h.where} | ${h.title} | ${h.snippet}`);
+        const near = await neighbors(graph, md[0].doc);
+        if (near.length)
+            lines.push(`Ligações de ${md[0].doc}:`, ...near.map((n) => `  ${n}`));
+    }
+    if (tx.length) {
+        lines.push("## Livros e aulas (Textos/)");
+        for (const h of tx)
+            lines.push(`- ${h.where} | ${h.snippet}`);
+    }
+    return lines.join("\n");
+}

package/dist/mcp/server.js

@@ -12,6 +12,7 @@ import { implementIo } from "../tools/implement.js";
 import "../tools/spec.js";
 import { ORCH_ONLY, orch } from "../orchestrator.js";
 import "../tools/digest.js";
+import "../tools/vault.js";
 import { allTools, execTool } from "../tools/registry.js";
 import { GraphStore } from "../graph/store.js";
 import { INDEXED_EXTENSIONS, indexProject } from "../graph/indexer.js";
@@ -24,7 +25,7 @@ export const MCP_NAME = "brito";
 export const MCP_INSTRUCTIONS = [
     "Brito: grafo de código, memória e skills do projeto.",
     "- Para localizar código, use graph_search/graph_context antes de ler arquivos; antes de alterar, meça o impacto com graph_callers/graph_impact. O grafo se atualiza sozinho após edições (graph_index só força).",
-    `- O grafo cobre ${INDEXED_EXTENSIONS.join(", ")} (em .svelte/.vue/.astro, o script e as chamadas do template). Imports relativos e por alias (paths/baseUrl do tsconfig, imports do package.json, $lib do SvelteKit) viram arestas. Em Java, Kotlin, Go, Ruby, PHP, C# e Rust os imports são resolvidos pelo pacote/namespace/módulo e o receptor de uma chamada é casado com o tipo pelo nome (sem inferência de tipos). Outras linguagens e arquivos ignorados pelo .gitignore não entram: use busca de texto para eles.`,
+    `- O grafo cobre ${INDEXED_EXTENSIONS.join(", ")} (em .svelte/.vue/.astro, o script e as chamadas do template). Imports relativos e por alias (paths/baseUrl do tsconfig, imports do package.json, $lib do SvelteKit) viram arestas. Em Java, Kotlin, Go, Ruby, PHP, C# e Rust os imports são resolvidos pelo pacote/namespace/módulo e o receptor de uma chamada é casado com o tipo pelo nome (sem inferência de tipos). Em .md o grafo guarda headings, tags (frontmatter e #tag), refs (#123) e links/[[wikilinks]] entre notas: graph_impact numa nota dá os backlinks; graph_search kind=tag/ref/heading acha por assunto. Para vaults de notas prefira graph_notes_find (filtros por campo, data, link e #N), graph_notes_backlinks e graph_notes_path (segue relações entre notas em uma chamada), sem escrever Cypher. Outras linguagens e arquivos ignorados pelo .gitignore não entram: use busca de texto para eles.`,
     "- recall/remember: notas duráveis (decisões, convenções, bugs descobertos). Consulte recall ao começar uma tarefa.",
     "- skill_load: carregue a skill antes de uma tarefa que ela cobre. No modo \"tudo liberado\", skill_save grava em teste; só o arriscado (comando destrutivo, mudança em skill aprovada) vira proposta pendente para /skills approve.",
 ].join("\n");
@@ -34,7 +35,7 @@ export const MCP_INSTRUCTIONS = [
  * tools de consulta, que são baratas e de uso frequente. As de escrita e a de aprovação (interna) continuam adiadas.
  */
 export const ALWAYS_LOAD_META = "anthropic/alwaysLoad";
-export const alwaysLoaded = (tool) => /^(graph_|recall$|remember$|skill_load$|digest$|implement$)/.test(tool);
+export const alwaysLoaded = (tool) => /^(graph_|recall$|remember$|skill_load$|digest$|implement$|vault_)/.test(tool);
 /** Prefixo com que o claude CLI enxerga as tools deste servidor. */
 export const MCP_PREFIX = `mcp__${MCP_NAME}__`;
 /** Tool usada como --permission-prompt-tool: encaminha o pedido ao REPL do Brito. */

package/dist/tools/graph-notes-path.js

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { defineTool } from "./registry.js";
+/**
+ * Travessia de relações entre notas .md em uma chamada (ex.: calls de outubro → pendências abertas → donos).
+ * O grafo tipado é montado em memória a partir do índice (tags do frontmatter, refs #N e links), sem mudar o banco:
+ *  - relação = nome do campo do frontmatter: `pessoas: [ana]` em A cria A -[pessoas]-> pessoas/ana.md (valor = nome de arquivo);
+ *    `pendencias: [14]` cria A -[pendencias]-> nota da pasta pendencias/ com `id: 14`.
+ *  - `cita`: nota que menciona #N → nota com `id: N`. `link`: link Markdown ou [[wikilink]].
+ */
+const OPS = ["=", "!=", "<", "<=", ">", ">="];
+const cmp = (a, b) => {
+    const na = Number(a), nb = Number(b);
+    if (a.trim() !== "" && b.trim() !== "" && Number.isFinite(na) && Number.isFinite(nb))
+        return na - nb;
+    return a < b ? -1 : a > b ? 1 : 0;
+};
+const test = (v, op, ref) => { const c = cmp(v, ref); return op === "=" ? c === 0 : op === "!=" ? c !== 0 : op === "<" ? c < 0 : op === "<=" ? c <= 0 : op === ">" ? c > 0 : c >= 0; };
+export async function buildNotesGraph(graph) {
+    const files = (await graph.run("MATCH (f:File) WHERE f.lang = 'markdown' RETURN f.path AS path")).map((r) => String(r.path));
+    const props = new Map();
+    const idOf = new Map(); // `${pasta}\t${n}` e `*\t${n}` → arquivos
+    const byBase = new Map();
+    const push = (m, k, v) => (m.get(k) ?? m.set(k, []).get(k)).push(v);
+    for (const f of files) {
+        props.set(f, new Map());
+        push(byBase, f.replace(/\.(md|markdown)$/i, "").split("/").pop().toLowerCase(), f);
+    }
+    for (const r of await graph.run("MATCH (f:File)-[:DEFINES]->(s:Symbol) WHERE f.lang = 'markdown' AND s.kind = 'tag' RETURN f.path AS path, s.name AS name")) {
+        const name = String(r.name);
+        const i = name.indexOf(":");
+        if (i < 0)
+            continue;
+        const m = props.get(String(r.path));
+        if (!m)
+            continue;
+        push(m, name.slice(0, i).toLowerCase(), name.slice(i + 1));
+    }
+    for (const [f, m] of props)
+        for (const id of m.get("id") ?? [])
+            if (/^\d+$/.test(id)) {
+                push(idOf, `${f.split("/")[0].toLowerCase()}\t${Number(id)}`, f);
+                push(idOf, `*\t${Number(id)}`, f);
+            }
+    const g = { files, props, out: new Map(), inn: new Map() };
+    const add = (rel, a, b) => {
+        if (a === b)
+            return;
+        (g.out.get(`${rel}\t${a}`) ?? g.out.set(`${rel}\t${a}`, new Set()).get(`${rel}\t${a}`)).add(b);
+        (g.inn.get(`${rel}\t${b}`) ?? g.inn.set(`${rel}\t${b}`, new Set()).get(`${rel}\t${b}`)).add(a);
+    };
+    for (const [f, m] of props)
+        for (const [k, vs] of m) {
+            if (k === "id")
+                continue;
+            for (const v of vs) {
+                if (/^\d+$/.test(v))
+                    for (const t of idOf.get(`${k}\t${Number(v)}`) ?? [])
+                        add(k, f, t);
+                else if (!/^\d/.test(v))
+                    for (const t of byBase.get(v.toLowerCase()) ?? [])
+                        add(k, f, t); // data (2026-10-26) não é nome de nota
+            }
+        }
+    for (const r of await graph.run("MATCH (s:Symbol) WHERE s.kind = 'ref' RETURN s.file AS file, s.name AS name")) {
+        const n = String(r.name).slice(1);
+        for (const t of idOf.get(`*\t${Number(n)}`) ?? [])
+            add("cita", String(r.file), t);
+    }
+    for (const r of await graph.run("MATCH (a:File)-[:IMPORTS]->(b:File) WHERE a.lang = 'markdown' AND b.lang = 'markdown' RETURN a.path AS a, b.path AS b"))
+        add("link", String(r.a), String(r.b));
+    return g;
+}
+const matches = (g, f, wh) => (wh ?? []).every((w) => {
+    if (w.missing)
+        return !(w.missing.dir === "in" ? g.inn : g.out).get(`${w.missing.rel}\t${f}`)?.size;
+    const vs = g.props.get(f)?.get((w.key ?? "").toLowerCase()) ?? [];
+    const op = w.op ?? "=";
+    return op === "!=" ? vs.length > 0 && vs.every((v) => test(v, op, w.value ?? "")) : vs.some((v) => test(v, op, w.value ?? ""));
+});
+/** Chamada sem argumentos: mostra o que existe no vault (relações com pastas de origem/destino e campos por pasta). */
+export function describeNotesGraph(g) {
+    const top = (f) => (f.includes("/") ? f.split("/")[0] + "/" : "(raiz)");
+    const rels = new Map();
+    for (const [k, dsts] of g.out) {
+        const [rel, src] = k.split("\t");
+        const r = rels.get(rel) ?? rels.set(rel, { n: 0, pairs: new Map() }).get(rel);
+        for (const d of dsts) {
+            r.n++;
+            const pair = `${top(src)}→${top(d)}`;
+            r.pairs.set(pair, (r.pairs.get(pair) ?? 0) + 1);
+        }
+    }
+    const lines = ["Relações (dir out = da nota que tem o campo para a nota citada):"];
+    for (const [rel, r] of [...rels].sort((a, b) => b[1].n - a[1].n))
+        lines.push(`  ${rel}  (${r.n}): ${[...r.pairs].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([p, n]) => `${p} ${n}`).join(", ")}`);
+    const fields = new Map();
+    for (const [f, m] of g.props)
+        for (const k of m.keys()) {
+            const t = top(f);
+            const c = fields.get(t) ?? fields.set(t, new Map()).get(t);
+            c.set(k, (c.get(k) ?? 0) + 1);
+        }
+    lines.push("Campos do frontmatter por pasta:");
+    for (const [t, c] of [...fields].sort((a, b) => (a[0] < b[0] ? -1 : 1)))
+        lines.push(`  ${t}: ${[...c].sort((a, b) => b[1] - a[1]).slice(0, 14).map(([k]) => k).join(", ")}`);
+    return lines.join("\n");
+}
+/** Falha alto em chave desconhecida: ignorar um filtro em silêncio devolve resposta errada com cara de certa. `has: ['k:v']` vira where k = v. */
+function checked(o, allowed, ctx) {
+    if (!o)
+        return o;
+    for (const k of Object.keys(o))
+        if (!allowed.includes(k))
+            throw new Error(`chave desconhecida "${k}" em ${ctx}. Use: ${allowed.join(", ")}`);
+    if (!o.has?.length)
+        return o;
+    const extra = o.has.map((h) => { const i = h.indexOf(":"); return { key: h.slice(0, i), op: "=", value: h.slice(i + 1) }; });
+    return { ...o, where: [...(o.where ?? []), ...extra] };
+}
+export function traverse(g, rawSpec) {
+    for (const k of Object.keys(rawSpec))
+        if (!["from", "steps", "return", "limit"].includes(k))
+            throw new Error(`chave desconhecida "${k}" na spec. Use: from, steps, return, limit`);
+    const spec = { ...rawSpec, from: checked(rawSpec.from, ["folder", "where", "has"], "from"), steps: rawSpec.steps?.map((st, i) => checked(st, ["rel", "dir", "folder", "where", "has"], `steps[${i}]`)) };
+    if (!spec.from && !spec.steps && !spec.return)
+        return describeNotesGraph(g);
+    let cur = new Set(g.files.filter((f) => (!spec.from?.folder || f.startsWith(spec.from.folder)) && matches(g, f, spec.from?.where)));
+    for (const st of spec.steps ?? []) {
+        const next = new Set();
+        for (const f of cur)
+            for (const t of (st.dir === "in" ? g.inn : g.out).get(`${st.rel}\t${f}`) ?? [])
+                next.add(t);
+        cur = new Set([...next].filter((f) => (!st.folder || f.startsWith(st.folder)) && matches(g, f, st.where)));
+    }
+    const limit = spec.limit ?? 100;
+    const list = [...cur].sort();
+    const ret = spec.return ?? "id";
+    if (ret === "count")
+        return String(list.length);
+    if (ret !== "id") {
+        const cnt = new Map();
+        for (const f of list)
+            for (const v of new Set(g.props.get(f)?.get(ret.toLowerCase()) ?? []))
+                cnt.set(v, (cnt.get(v) ?? 0) + 1);
+        const rows = [...cnt].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
+        return `${list.length} notas; valores de "${ret}":\n` + (rows.length ? rows.slice(0, limit).map(([v, n]) => `${v}  (${n})`).join("\n") : "(vazio)");
+    }
+    return `${list.length} notas${list.length > limit ? ` (mostrando ${limit})` : ""}:\n` + (list.length ? list.slice(0, limit).join("\n") : "(vazio)");
+}
+const whereSchema = z.object({ key: z.string().optional(), op: z.enum(OPS).optional(), value: z.string().optional(), missing: z.object({ rel: z.string(), dir: z.enum(["in", "out"]).optional() }).optional() });
+defineTool({
+    name: "graph_notes_path",
+    concurrent: true,
+    readsGraph: true,
+    description: "Segue relações entre notas .md em uma chamada (ex.: calls de outubro → pendências abertas que elas tratam → dono). " +
+        "Relação = nome de um campo do frontmatter: `pessoas: [ana]` liga a nota a pessoas/ana.md; `pendencias: [14]` liga à nota da pasta pendencias/ com `id: 14`; `dono`, `desbloqueia` etc. igual. " +
+        "Também existem `cita` (menção #N no texto, mais ampla que o campo do frontmatter) e `link` (link Markdown/wikilink); para vínculo formal prefira o campo do frontmatter. dir 'out' segue da nota que tem o campo para a nota citada; 'in' segue ao contrário. " +
+        "O resultado é o conjunto do ÚLTIMO passo, não o de partida: para listar quem cita/trata X, parta de X e siga dir 'in'. " +
+        "Spec: from {folder, where}, steps [{rel, dir, folder?, where?}], return ('id' lista notas, 'count', ou nome de um campo para listar seus valores). " +
+        "where: {key, op (= != < <= > >=), value} ou has: ['campo:valor'] (igualdade) sobre campos do frontmatter (datas ISO e números comparam certo) ou {missing:{rel,dir}} (nota sem aquela relação). " +
+        "Chamada com {} lista as relações e os campos do vault (use antes de montar a spec). Não cobre texto do corpo além de #N e links: para achar palavra ou menção em prosa, use grep.",
+    schema: z.object({
+        from: z.object({ folder: z.string().optional(), where: z.array(whereSchema).optional(), has: z.array(z.string()).optional() }).strict().optional(),
+        steps: z.array(z.object({ rel: z.string(), dir: z.enum(["in", "out"]).optional(), folder: z.string().optional(), where: z.array(whereSchema).optional(), has: z.array(z.string()).optional() }).strict()).optional(),
+        return: z.string().optional(),
+        limit: z.number().int().min(1).max(500).optional(),
+    }).strict(),
+    async run(spec, { graph }) {
+        return traverse(await buildNotesGraph(graph), spec);
+    },
+});

package/dist/tools/graph-notes.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { defineTool } from "./registry.js";
+/**
+ * Ferramentas para vaults de notas .md: escondem o Cypher e respondem as perguntas de relação, filtro e data
+ * que o agente faria com grep+script. Os dados vêm do indexador de markdown (tags do frontmatter, refs #N, links).
+ */
+const OPS = ["=", "!=", "<", "<=", ">", ">="];
+/** Compara como número quando os dois lados são numéricos; senão como texto (datas ISO ordenam certo). */
+function cmp(a, b) {
+    const na = Number(a), nb = Number(b);
+    if (a.trim() !== "" && b.trim() !== "" && Number.isFinite(na) && Number.isFinite(nb))
+        return na - nb;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+const test = (v, op, ref) => {
+    const c = cmp(v, ref);
+    return op === "=" ? c === 0 : op === "!=" ? c !== 0 : op === "<" ? c < 0 : op === "<=" ? c <= 0 : op === ">" ? c > 0 : c >= 0;
+};
+/** Nome do Symbol tag → [chave, valor]. `#urgente` vira ["tag","urgente"]. */
+function splitTag(name) {
+    if (name.startsWith("#"))
+        return ["tag", name.slice(1)];
+    const i = name.indexOf(":");
+    return i < 0 ? [name, ""] : [name.slice(0, i).toLowerCase(), name.slice(i + 1)];
+}
+const FIND_KEYS = ["folder", "has", "where", "links_to", "not_linked_from", "mentions", "pick", "limit"];
+export async function findNotes(graph, p) {
+    for (const k of Object.keys(p))
+        if (!FIND_KEYS.includes(k))
+            throw new Error(`chave desconhecida "${k}". Use: ${FIND_KEYS.join(", ")}`); // filtro ignorado em silêncio = resposta errada
+    const folder = p.folder ?? "";
+    const files = (await graph.run(`MATCH (f:File) WHERE f.lang = 'markdown' ${folder ? "AND f.path STARTS WITH $p" : ""} RETURN f.path AS path`, folder ? { p: folder } : {})).map((r) => String(r.path));
+    let set = new Set(files);
+    const needTags = (p.has?.length ?? 0) > 0 || (p.where?.length ?? 0) > 0 || !!p.pick;
+    const tags = new Map();
+    if (needTags) {
+        for (const r of await graph.run("MATCH (f:File)-[:DEFINES]->(s:Symbol) WHERE f.lang = 'markdown' AND s.kind = 'tag' RETURN f.path AS path, s.name AS name")) {
+            if (!set.has(String(r.path)))
+                continue;
+            const [k, v] = splitTag(String(r.name));
+            const m = tags.get(r.path) ?? tags.set(r.path, new Map()).get(r.path);
+            (m.get(k) ?? m.set(k, []).get(k)).push(v);
+        }
+    }
+    const valuesOf = (path, key) => tags.get(path)?.get(key.toLowerCase()) ?? [];
+    for (const h of p.has ?? []) {
+        const [k, ...rest] = h.split(":");
+        const v = rest.join(":");
+        set = new Set([...set].filter((f) => valuesOf(f, k).includes(v)));
+    }
+    for (const w of p.where ?? []) {
+        set = new Set([...set].filter((f) => {
+            const vs = valuesOf(f, w.key);
+            return w.op === "!=" ? vs.length > 0 && vs.every((v) => test(v, w.op, w.value)) : vs.some((v) => test(v, w.op, w.value));
+        }));
+    }
+    if (p.links_to) {
+        const src = new Set((await graph.run("MATCH (a:File)-[:IMPORTS]->(b:File {path:$t}) RETURN a.path AS path", { t: p.links_to })).map((r) => String(r.path)));
+        set = new Set([...set].filter((f) => src.has(f)));
+    }
+    if (p.not_linked_from) {
+        const hit = new Set((await graph.run("MATCH (a:File)-[:IMPORTS]->(b:File) WHERE a.path STARTS WITH $p RETURN DISTINCT b.path AS path", { p: p.not_linked_from })).map((r) => String(r.path)));
+        set = new Set([...set].filter((f) => !hit.has(f)));
+    }
+    if (p.mentions) {
+        const n = p.mentions.startsWith("#") ? p.mentions : "#" + p.mentions;
+        const m = new Set((await graph.run("MATCH (s:Symbol) WHERE s.kind = 'ref' AND s.name = $n RETURN s.file AS file", { n })).map((r) => String(r.file)));
+        set = new Set([...set].filter((f) => m.has(f)));
+    }
+    const limit = p.limit ?? 100;
+    const list = [...set].sort();
+    if (p.pick) {
+        const cnt = new Map();
+        for (const f of list)
+            for (const v of new Set(valuesOf(f, p.pick)))
+                cnt.set(v, (cnt.get(v) ?? 0) + 1);
+        const rows = [...cnt].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
+        return `${list.length} notas; ${rows.length} valores distintos de "${p.pick}":\n` + (rows.length ? rows.slice(0, limit).map(([v, n]) => `${v}  (${n})`).join("\n") : "(vazio)");
+    }
+    return `${list.length} notas${list.length > limit ? ` (mostrando ${limit})` : ""}:\n` + (list.length ? list.slice(0, limit).join("\n") : "(vazio)");
+}
+export async function backlinks(graph, file) {
+    const linked = (await graph.run("MATCH (a:File)-[:IMPORTS]->(b:File {path:$f}) RETURN a.path AS path", { f: file })).map((r) => String(r.path));
+    const idTag = (await graph.run("MATCH (f:File {path:$f})-[:DEFINES]->(s:Symbol) WHERE s.kind = 'tag' AND s.name STARTS WITH 'id:' RETURN s.name AS name", { f: file }))[0];
+    let mentioned = [];
+    const id = idTag ? String(idTag.name).slice(3) : "";
+    if (/^\d+$/.test(id)) {
+        mentioned = (await graph.run("MATCH (s:Symbol) WHERE s.kind = 'ref' AND s.name = $n RETURN DISTINCT s.file AS file", { n: "#" + id })).map((r) => String(r.file)).filter((f) => f !== file);
+    }
+    const all = new Set([...linked, ...mentioned]);
+    if (!all.size)
+        return "(nenhuma nota aponta para este arquivo)";
+    const rows = [...all].sort().map((f) => `${f}  [${linked.includes(f) ? "link" : ""}${linked.includes(f) && mentioned.includes(f) ? "+" : ""}${mentioned.includes(f) ? "menção #" + id : ""}]`);
+    return `${all.size} notas apontam para ${file}:\n` + rows.join("\n");
+}
+defineTool({
+    name: "graph_notes_find",
+    concurrent: true,
+    readsGraph: true,
+    description: "Acha notas .md por pasta, campo do frontmatter, data, links e menções #N, sem escrever Cypher. Todos os filtros se combinam (E). " +
+        "folder: prefixo de caminho (ex. 'pendencias/'). has: ['status:aberta','produto:Predize'] (igualdade). " +
+        "where: [{key:'prazo',op:'<',value:'2026-11-12'}] (op = != < <= > >=; datas ISO e números comparam certo). " +
+        "links_to: notas que linkam para esse caminho. not_linked_from: exclui notas linkadas por qualquer arquivo dessa pasta (ex. pendências sem call: folder 'pendencias/', has status:aberta, not_linked_from 'calls/'). " +
+        "mentions: '#85' (menção no texto). pick: devolve os valores distintos de um campo no conjunto (ex. pick 'pessoas') em vez da lista de notas. " +
+        "Use para perguntas de relação, filtro e data sobre notas; para achar uma palavra no corpo, use grep.",
+    schema: z.object({
+        folder: z.string().optional(),
+        has: z.array(z.string()).optional(),
+        where: z.array(z.object({ key: z.string(), op: z.enum(OPS), value: z.string() })).optional(),
+        links_to: z.string().optional(),
+        not_linked_from: z.string().optional(),
+        mentions: z.string().optional(),
+        pick: z.string().optional(),
+        limit: z.number().int().min(1).max(500).optional(),
+    }).strict(),
+    async run(args, { graph }) {
+        return findNotes(graph, args);
+    },
+});
+defineTool({
+    name: "graph_notes_backlinks",
+    concurrent: true,
+    readsGraph: true,
+    description: "Quem aponta para uma nota .md: notas que a linkam e, se ela tem `id: N` no frontmatter, notas que a mencionam como #N no texto. Use antes de grep para achar o que se liga a uma pessoa, pendência ou decisão.",
+    schema: z.object({ file: z.string() }),
+    async run({ file }, { graph }) {
+        return backlinks(graph, file);
+    },
+});

package/dist/tools/graph.js

@@ -3,6 +3,8 @@ import crypto from "node:crypto";
 import { defineTool } from "./registry.js";
 import { indexProject } from "../graph/indexer.js";
 import { listSkills } from "../skills/store.js";
+import "./graph-notes.js";
+import "./graph-notes-path.js";
 const fmt = (rows, cols) => (rows.length ? rows.map((r) => cols.map((c) => r[c]).join("  ")).join("\n") : "(vazio)");
 defineTool({
     name: "graph_index",

package/dist/tools/vault.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { defineTool } from "./registry.js";
+import { vaultSearch } from "../graph/vault.js";
+defineTool({
+    name: "vault_search",
+    concurrent: true,
+    readsGraph: true,
+    description: "Busca por palavras num cofre de notas Markdown (sem acento nem caixa, todas as palavras): devolve seções de .md com arquivo e linhas (`arq.md:12-30`), os vizinhos do 1º resultado no grafo ([[links]]) e, se houver índice, trechos de livros/aulas com página. USE ANTES de abrir arquivos ou PDFs; depois leia só a faixa de linhas indicada.",
+    schema: z.object({
+        query: z.string().describe("palavras ou frase"),
+        em: z.string().optional().describe("limita a caminhos que contêm este texto (ex.: 'Temas/', 'Frame')"),
+        limit: z.number().int().min(1).max(20).optional(),
+    }),
+    async run({ query, em, limit }, { root, graph }) {
+        return vaultSearch(root, graph, query, { em, limit });
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brito-cli",
-  "version": "0.13.3",
+  "version": "0.15.0",
   "description": "Coding-agent CLI with a code knowledge graph, memory and reviewable skills / CLI de agente de código com grafo de conhecimento, memória e skills revisáveis",
   "type": "module",
   "bin": {