brito-cli 0.13.3 → 0.14.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/graph/indexer.js

@@ -7,6 +7,7 @@ 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 { 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 +15,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 +190,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";
@@ -341,9 +343,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 +363,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 +372,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/mcp/server.js

@@ -24,7 +24,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");

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brito-cli",
-  "version": "0.13.3",
+  "version": "0.14.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": {