funifier-mcp 0.2.27 → 0.3.0

package/dist/mcp/tools/search-docs.js

@@ -88,13 +88,13 @@ function registerSearchDocsTool(server, docsPath) {
             };
         }
         const lines = results.map((r, i) => {
-            const resourcePath = r.file.replace(/^knowledge\//, "").replace(/\.md$/, "");
-            return `${i + 1}. funifier://docs/${resourcePath}  [score: ${r.score.toFixed(2)}]`;
+            const docPath = r.file.replace(/^knowledge\//, "").replace(/\.md$/, "");
+            return `${i + 1}. ${docPath}  [score: ${r.score.toFixed(2)}]`;
         });
         return {
             content: [{
                     type: "text",
-                    text: `Documentation search results for "${query}":\n\n${lines.join("\n")}\n\nFetch a resource with its funifier://docs/... URI to read the full content.`,
+                    text: `Documentation search results for "${query}":\n\n${lines.join("\n")}\n\nRead the full content with funifier_read_doc path=<path> (e.g. funifier_read_doc path=${results[0].file.replace(/^knowledge\//, "").replace(/\.md$/, "")}).`,
                 }],
         };
     });

package/dist/mcp/tools/search-docs.js.map

@@ -1 +1 @@
-{"version":3,"file":"search-docs.js","sourceRoot":"","sources":["../../../src/mcp/tools/search-docs.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMA,wDAqEC;AA3ED,uCAAyB;AACzB,2CAA6B;AAC7B,6BAAwB;AAExB,gDAAkE;AAElE,SAAgB,sBAAsB,CAAC,MAAiB,EAAE,QAAgB;IACxE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAClE,IAAI,WAAW,GAAuB,IAAI,CAAC;IAE3C,SAAS,SAAS;QAChB,IAAI,WAAW;YAAE,OAAO,WAAW,CAAC;QACpC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3C,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAgB,CAAC;QAC7E,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,MAAM,CAAC,YAAY,CACjB,sBAAsB,EACtB;QACE,KAAK,EAAE,+BAA+B;QACtC,WAAW,EACT,6FAA6F;YAC7F,yGAAyG;YACzG,oEAAoE;QACtE,WAAW,EAAE;YACX,KAAK,EAAE,OAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,CAAC,4GAA4G,CAAC;YACzH,GAAG,EAAE,OAAC;iBACH,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,kDAAkD,CAAC;YAC/D,SAAS,EAAE,OAAC;iBACT,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,4DAA4D,CAAC;SAC1E;QACD,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,KAAK;SACrB;KACF,EACD,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE;QAC5B,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kFAAkF,EAAE,CAAC;gBACrH,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,IAAA,oBAAU,EAAC,KAAK,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,SAAS,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;QAExF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oCAAoC,KAAK,uBAAuB,EAAE,CAAC;aACpG,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACjC,MAAM,YAAY,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC7E,OAAO,GAAG,CAAC,GAAG,CAAC,qBAAqB,YAAY,aAAa,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QACrF,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,qCAAqC,KAAK,SAAS,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,iFAAiF;iBAC3J,CAAC;SACH,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"search-docs.js","sourceRoot":"","sources":["../../../src/mcp/tools/search-docs.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/search-docs.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search-docs.test.d.ts.map

package/dist/mcp/tools/search-docs.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-docs.test.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/search-docs.test.ts"],"names":[],"mappings":""}

package/dist/mcp/tools/search-docs.test.js

@@ -0,0 +1,100 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const search_docs_1 = require("./search-docs");
+const lexical_1 = require("../../core/lexical");
+// Package-style layout: docsPath is the knowledge/ dir; the index sits one level up,
+// exactly where the tool resolves it (path.join(docsPath, "..", ".search-index.json")).
+let root;
+let docsPath;
+function invokeWith(dp) {
+    const handlers = {};
+    const server = {
+        registerTool: (name, _config, handler) => {
+            handlers[name] = handler;
+        },
+    };
+    (0, search_docs_1.registerSearchDocsTool)(server, dp);
+    return (args) => handlers["funifier_search_docs"](args);
+}
+(0, vitest_1.beforeAll)(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "funifier-searchdocs-"));
+    docsPath = path.join(root, "knowledge");
+    fs.mkdirSync(docsPath, { recursive: true });
+    // Index keys carry the knowledge/ prefix, like the real build output, so the
+    // tool's strip of `^knowledge/` and `.md` is exercised.
+    const files = new Map([
+        [
+            "knowledge/modules/trigger.md",
+            "# Trigger\n\n## Groovy event\n\nTrigger fires on before_win events with a groovy script.",
+        ],
+        ["knowledge/modules/quiz.md", "# Quiz\n\nQuestions and answers for players."],
+    ]);
+    fs.writeFileSync(path.join(root, ".search-index.json"), JSON.stringify((0, lexical_1.buildIndex)(files)));
+});
+(0, vitest_1.afterAll)(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+});
+(0, vitest_1.describe)("funifier_search_docs", () => {
+    (0, vitest_1.it)("loads the index next to docsPath and ranks matching docs", () => {
+        const result = invokeWith(docsPath)({ query: "trigger groovy event before_win" });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(result.content[0].text).toContain("modules/trigger");
+    });
+    (0, vitest_1.it)("returns paths stripped of knowledge/ and .md, pointing at funifier_read_doc (not a resource URI)", () => {
+        const text = invokeWith(docsPath)({ query: "trigger groovy event before_win" }).content[0].text;
+        (0, vitest_1.expect)(text).toContain("funifier_read_doc path=");
+        (0, vitest_1.expect)(text).not.toContain("funifier://docs/");
+        (0, vitest_1.expect)(text).not.toContain("knowledge/");
+        (0, vitest_1.expect)(text).not.toContain(".md");
+    });
+    (0, vitest_1.it)("returns isError when the search index is missing", () => {
+        const emptyRoot = fs.mkdtempSync(path.join(os.tmpdir(), "funifier-noindex-"));
+        const result = invokeWith(path.join(emptyRoot, "knowledge"))({ query: "trigger" });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toContain("index not found");
+        fs.rmSync(emptyRoot, { recursive: true, force: true });
+    });
+    (0, vitest_1.it)("reports no matches for an unrelated query", () => {
+        const result = invokeWith(docsPath)({ query: "zzzznonexistentterm" });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(result.content[0].text).toContain("No documentation found");
+    });
+});
+//# sourceMappingURL=search-docs.test.js.map

package/dist/mcp/tools/search-docs.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-docs.test.js","sourceRoot":"","sources":["../../../src/mcp/tools/search-docs.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "funifier-mcp",
-  "version": "0.2.27",
+  "version": "0.3.0",
   "description": "Funifier AI toolkit — MCP server, API client, and Claude Code skills for the Funifier gamification platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/acquire-funifier-knowledge/SKILL.md

@@ -27,7 +27,7 @@ Produza esta estrutura em `docs/funifier/`. **Nenhum arquivo pode ficar vazio**
 
 | Arquivo | Conteúdo |
 |---------|----------|
-| `OVERVIEW.md` | Identificação da instância, contagens agregadas por categoria, data do snapshot, escopo do mapeamento |
+| `OVERVIEW.md` | Identificação da instância, contagens agregadas por categoria, data do snapshot, escopo do mapeamento e o **mapa de arquitetura em Mermaid** (o que dispara/premia/alimenta/chama o quê) |
 | `GAME_MECHANICS.md` | Pontos, níveis, achievements/badges, challenges, missions, quizzes, virtual goods — com IDs, regras de atribuição e condições |
 | `TRIGGERS.md` | Todos os triggers: nome, ID, entidade/evento de origem, condições, ações, status |
 | `SCHEDULERS.md` | Cron jobs: nome, expressão cron, ação, próxima/última execução conhecida, status |
@@ -82,7 +82,7 @@ Avance pelas fases em ordem. As fases 1 e 6 são sempre completas (mesmo em Modo
 1. **Validar conexão e identificar a instância.** Confirme que o MCP responde (uma chamada `funifier_database action=collections` ou um `funifier_list type=trigger limit=1` serve). Registre serverUrl/nome da conexão e a data do snapshot para o `OVERVIEW.md`.
 2. **Inventário bruto.** Para cada um dos 18 tipos, rode `funifier_list` e registre os IDs e nomes. Rode `funifier_database action=collections` para descobrir coleções que revelam elementos fora do enum (webhooks, notifications, competitions, custom `__c`, player, team). Consulte `references/funifier-inventory-checklist.md` para a lista de perguntas por categoria.
 3. **Detalhamento.** Para cada objeto que precisa de detalhe, rode `funifier_get mode=read` e extraia as regras, condições e ações. Amostre coleções relevantes com `funifier_database action=query` (limit pequeno) para entender o modelo de player/team.
-4. **Análise cruzada.** Relacione objetos: qual `trigger` alimenta qual `point`/`challenge`; qual `scheduler` chama qual `public-endpoint`; quais `action`s satisfazem as regras de cada `challenge`; quais `leaderboard`s usam quais `point`s. Anote as relações para `CONCERNS.md` e `TECHNIQUES_AND_PATTERNS.md`.
+4. **Análise cruzada e diagrama de arquitetura.** Relacione objetos: qual `trigger` alimenta qual `point`/`challenge`; qual `scheduler` chama qual `public-endpoint`; quais `action`s satisfazem as regras de cada `challenge`; quais `leaderboard`s usam quais `point`s. Anote as relações para `CONCERNS.md` e `TECHNIQUES_AND_PATTERNS.md`. Com essas relações já mapeadas (e **somente** com elas), monte o **mapa de arquitetura em Mermaid** e escreva-o na seção própria do `OVERVIEW.md` — siga as convenções em "Diagrama de arquitetura (Mermaid)" abaixo.
 5. **Inferência de técnicas de jogos.** Classifique as técnicas observadas usando `references/game-techniques-taxonomy.md`. Cada técnica DEVE ser ligada aos IDs concretos que a implementam. Sem objeto que a sustente, não afirme a técnica.
 6. **Validação.** Verifique: (a) cada claim aponta para um ID/objeto; (b) nenhuma seção obrigatória está vazia; (c) todo nome de ferramenta usado existe; (d) nenhum tipo inventado. Veja a checklist no fim deste arquivo.
 7. **Apresentar.** Mostre um sumário (contagens + onde está cada doc) e uma lista numerada de itens `[ASK USER]` e divergências encontradas, para o usuário resolver.
@@ -95,6 +95,26 @@ Avance pelas fases em ordem. As fases 1 e 6 são sempre completas (mesmo em Modo
 - **Nunca infira comportamento sem um objeto que o sustente.** "Provavelmente dispara X" é proibido; cite a config do trigger e o evento exato.
 - **Toda seção termina com um bloco `## Evidence`** listando os IDs consultados e as chamadas MCP que produziram o conteúdo (ex.: `funifier_list type=trigger`, `funifier_get type=challenge id=...`).
 
+## Diagrama de arquitetura (Mermaid)
+
+O `OVERVIEW.md` carrega um **mapa de arquitetura** em Mermaid: a visão macro de "o que dispara, premia, alimenta e chama o quê". Ele é a *visualização* das relações já levantadas na Fase 4 — nunca uma fonte nova de verdade.
+
+**Regras duras:**
+
+1. **Toda aresta corresponde a um campo configurado num objeto real.** A origem é o `entity`/`event` de um `trigger`, a recompensa de um `challenge`, a métrica de um `leaderboard`, o preço de um `virtual-good-item`, etc. Sem campo que a sustente, a aresta não existe.
+2. **Toda aresta é rastreável no doc da categoria.** Cada relação desenhada DEVE também aparecer como fato no doc correspondente (`TRIGGERS.md`, `GAME_MECHANICS.md`, `LEADERBOARDS.md`, ...). O diagrama não afirma nada que os docs não afirmem.
+3. **Relação incerta = aresta tracejada `-.->` rotulada `[ASK USER]`.** Nunca desenhe uma aresta sólida "provável" (mesmo princípio do anti-padrão "provavelmente dispara X").
+4. **Legibilidade > completude.** Se uma categoria tem **mais de 8 objetos**, não desenhe um nó por objeto: colapse a categoria num único nó anotado com a contagem (ex.: `challenges["challenges (×24)"]`) e desenhe só os fluxos principais. O mapa do `OVERVIEW.md` é macro; diagramas detalhados por área só quando o usuário pedir.
+
+**Convenções de sintaxe (para o Mermaid não quebrar):**
+
+- Use `flowchart LR`. Agrupe os nós em `subgraph`s por camada: `Ações & Eventos`, `Automação` (`trigger`/`scheduler`), `Mecânicas` (`challenge`/`quiz`/`level`/trilhas), `Recompensas` (`point`/`virtual-good`), `Visualização` (`leaderboard`/`aggregate`/`custom-page`/`widget`), `Integrações` (`public-endpoint`/`webhook`/`websocket`/`auth-module`).
+- **IDs de nó**: apenas `[A-Za-z0-9_]`. Derive do nome substituindo qualquer outro caractere por `_`. Rótulo sempre entre aspas duplas, com nome + tipo: `tr_login["login_trigger · trigger"]`.
+- **Verbos das arestas** (use só estes, sempre rotulados): `dispara` (trigger/scheduler → ação/endpoint), `premia` (challenge/quiz → point/virtual-good), `alimenta` (point → leaderboard; action → challenge), `exige` (level → point; item → preço), `lê` (aggregate → coleção; page/widget → aggregate/leaderboard), `chama` (frontend/page → public-endpoint; trigger → webhook externo).
+- Uma instrução por linha; nunca use parênteses em rótulos sem aspas.
+
+O esqueleto pronto para preencher está em `assets/templates/OVERVIEW.md` — substitua os `{{...}}` pelos objetos reais e remova as arestas que não tiverem relação comprovada.
+
 ## Modo Foco (Focus Area Mode)
 
 Se o usuário pedir foco ("só triggers", "mecânicas e técnicas apenas"):
@@ -102,6 +122,7 @@ Se o usuário pedir foco ("só triggers", "mecânicas e técnicas apenas"):
 - A **Fase 1** (validar/identificar) roda sempre, completa.
 - Os documentos do foco são preenchidos **completos**.
 - Os demais documentos obrigatórios **existem**, com suas seções presentes mas marcadas `[TODO]` (e uma nota indicando que ficaram fora do escopo desta execução).
+- O **mapa de arquitetura** no `OVERVIEW.md` é sempre gerado; seu escopo reflete o foco — categorias fora do foco aparecem colapsadas num único nó com a contagem.
 - A **Fase 6** (validação) roda em **todos** os documentos.
 
 ## Anti-padrões
@@ -114,6 +135,7 @@ Se o usuário pedir foco ("só triggers", "mecânicas e técnicas apenas"):
 | Confundir achievement com challenge ou mission | Respeitar a tipagem do Funifier; cada categoria no seu doc |
 | Inventar um tipo (ex.: tratar "webhook" como `funifier_list type=webhook`) | Usar só os 18 tipos reais; inferir o resto de coleções e ações |
 | Modificar a instância para "testar" um comportamento | Apenas ler; nunca `save`/`delete`/`execute`/`insert`/`update` |
+| Desenhar uma aresta "provável" no diagrama Mermaid | Só desenhar arestas com um campo de objeto que as sustente; incertezas viram `-.->` `[ASK USER]` |
 
 ## Quando ler cada arquivo de referência
 
@@ -128,5 +150,6 @@ Se o usuário pedir foco ("só triggers", "mecânicas e técnicas apenas"):
 - [ ] Todo objeto com status conhecido tem o status registrado.
 - [ ] Nenhum tipo inventado — só os 18 tipos reais + coleções via `funifier_database`.
 - [ ] Cada documento termina com um bloco `## Evidence`.
+- [ ] O `OVERVIEW.md` contém o mapa de arquitetura em Mermaid; cada aresta tem um campo de objeto que a sustenta e o mesmo fato aparece no doc da categoria. Incertezas são `-.->` `[ASK USER]`, não arestas sólidas.
 - [ ] Itens dependentes de intenção estão marcados `[ASK USER]`, não adivinhados.
 - [ ] Nenhuma ferramenta de escrita foi usada (`save`/`delete`/`execute`/`insert`/`update`/`bulk`/`folder progress`).

package/skills/acquire-funifier-knowledge/assets/templates/OVERVIEW.md

@@ -38,6 +38,44 @@ Contagem por tipo listável (preencha 0 quando não houver — não omita):
 |----------|---------|-------------|
 | {{webhook/notification/competition/...}} | {{collection}} | {{n}} |
 
+### Mapa de Arquitetura
+
+Visão macro de "o que dispara/premia/alimenta/chama o quê". **Regras:** toda aresta vem de um campo real (trigger `entity`/`event`, recompensa de challenge, métrica de leaderboard, preço de virtual-good...) e o mesmo fato aparece no doc da categoria; relação incerta = `-.->` `[ASK USER]`; categoria com >8 objetos = um único nó com a contagem (`challenges["challenges (×24)"]`). Verbos permitidos: `dispara`, `premia`, `alimenta`, `exige`, `lê`, `chama`. Substitua os `{{...}}` por IDs de nó saneados (`[A-Za-z0-9_]`) e remova as arestas sem relação comprovada.
+
+```mermaid
+flowchart LR
+  subgraph Acoes["Ações & Eventos"]
+    {{act_id}}["{{nome}} · action"]
+  end
+  subgraph Automacao["Automação"]
+    {{trigger_id}}["{{nome}} · trigger"]
+    {{scheduler_id}}["{{nome}} · scheduler"]
+  end
+  subgraph Mecanicas["Mecânicas"]
+    {{challenge_id}}["{{nome}} · challenge"]
+    {{level_id}}["{{nome}} · level"]
+  end
+  subgraph Recompensas["Recompensas"]
+    {{point_id}}["{{nome}} · point"]
+    {{vg_id}}["{{nome}} · virtual-good"]
+  end
+  subgraph Visualizacao["Visualização"]
+    {{leaderboard_id}}["{{nome}} · leaderboard"]
+    {{aggregate_id}}["{{nome}} · aggregate"]
+  end
+  subgraph Integracoes["Integrações"]
+    {{endpoint_id}}["{{nome}} · public-endpoint"]
+  end
+
+  {{act_id}} -->|alimenta| {{challenge_id}}
+  {{trigger_id}} -->|premia| {{point_id}}
+  {{challenge_id}} -->|premia| {{vg_id}}
+  {{point_id}} -->|alimenta| {{leaderboard_id}}
+  {{level_id}} -->|exige| {{point_id}}
+  {{aggregate_id}} -->|lê| {{point_id}}
+  {{scheduler_id}} -.->|chama [ASK USER]| {{endpoint_id}}
+```
+
 ## Extended (Opcional)
 - Versão/plano da instância, se conhecido.
 - Principais áreas funcionais identificadas (resumo de 2-3 linhas).
@@ -45,3 +83,4 @@ Contagem por tipo listável (preencha 0 quando não houver — não omita):
 ## Evidence
 - `funifier_list type=<cada um dos 18 tipos>`
 - `funifier_database action=collections`
+- Mapa de arquitetura: cada aresta é evidenciada pelo objeto/campo que a sustenta, documentado no doc da categoria correspondente ({{ex.: TRIGGERS.md #id, GAME_MECHANICS.md #id}}).

package/skills/funifier/SKILL.md

@@ -21,11 +21,13 @@ Only proceed directly with MCP tools when no row matches.
 3. Read the file listed in the Reference column
 4. Follow the workflow in that file
 
-For general questions with no matching task, run lexical search:
+For general questions with no matching task, search the docs with the MCP tool:
 
-```bash
-npx funifier-mcp search "<user question>"
 ```
+funifier_search_docs "<user question>"
+```
+
+Then read a result with `funifier_read_doc path=<path>`.
 
 ## Routing Table
 

package/skills/funifier/references/configure-security.md

@@ -6,19 +6,19 @@ Configure Funifier security settings — roles, scopes, app tokens, and auth par
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "security role scope token auth app permission basic bearer access-control" --skill funifier-configure-security
+```
+funifier_search_docs "security role scope token auth app permission basic bearer access-control"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/modules/security.md`
+- `funifier_read_doc path=modules/security`
 
 ## Steps
 
@@ -54,7 +54,7 @@ Authorization: Bearer <studio_token>
 ### 2. Ler a documentação do módulo
 
 ```
-datasource-funifier-docs/knowledge/modules/security.md
+funifier_read_doc path=modules/security
 ```
 
 ### 3. Definir roles e apps

package/skills/funifier/references/create-action.md

@@ -6,20 +6,20 @@ Create a Funifier action — define trackable player behaviors with attributes
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "action track player behavior attributes log event" --skill funifier-create-action
+```
+funifier_search_docs "action track player behavior attributes log event"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/modules/action.md`
-- `datasource-funifier-docs/knowledge/modules/action-log.md`
+- `funifier_read_doc path=modules/action`
+- `funifier_read_doc path=modules/action-log`
 
 ## Steps
 

package/skills/funifier/references/create-aggregate.md

@@ -45,21 +45,21 @@ Note que `aggregate` é uma **string** contendo JSON serializado (com `\n` e `\"
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "aggregate mongodb pipeline report dashboard query prepared" --skill funifier-create-aggregate
+```
+funifier_search_docs "aggregate mongodb pipeline report dashboard query prepared"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/guides/aggregates.md`
-- `datasource-funifier-docs/knowledge/guides/database-access.md`
-- `datasource-funifier-docs/knowledge/modules/database.md`
+- `funifier_read_doc path=guides/aggregates`
+- `funifier_read_doc path=guides/database-access`
+- `funifier_read_doc path=modules/database`
 
 ## Steps
 

package/skills/funifier/references/create-challenge.md

@@ -6,21 +6,21 @@ Create a Funifier challenge — missions with action rules and point rewards
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "challenge mission reward rules action points gamification" --skill funifier-create-challenge
+```
+funifier_search_docs "challenge mission reward rules action points gamification"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/modules/challenge.md`
-- `datasource-funifier-docs/knowledge/modules/action.md`
-- `datasource-funifier-docs/knowledge/modules/point.md`
+- `funifier_read_doc path=modules/challenge`
+- `funifier_read_doc path=modules/action`
+- `funifier_read_doc path=modules/point`
 
 ## Steps
 

package/skills/funifier/references/create-competition.md

@@ -6,19 +6,19 @@ Create a Funifier competition — timed ranking contests with player enrollment,
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "competition contest ranking tournament enrollment rewards position gt26" --skill funifier-create-competition
+```
+funifier_search_docs "competition contest ranking tournament enrollment rewards position gt26"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/modules/competition.md`
+- `funifier_read_doc path=modules/competition`
 
 ## Steps
 

package/skills/funifier/references/create-crossword.md

@@ -542,7 +542,7 @@ funifier_list type=crossword search=<titulo>
 ### 2. Ler a documentação do módulo
 
 ```
-datasource-funifier-docs/knowledge/modules/crossword.md
+funifier_read_doc path=modules/crossword
 ```
 
 ### 3. Criar o crossword

package/skills/funifier/references/create-custom-object.md

@@ -6,20 +6,20 @@ Create and manage Funifier custom objects — domain-specific collections with t
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "custom object collection database crud __c domain entity business" --skill funifier-create-custom-object
+```
+funifier_search_docs "custom object collection database crud __c domain entity business"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/modules/custom-object.md`
-- `datasource-funifier-docs/knowledge/modules/database.md`
+- `funifier_read_doc path=modules/custom-object`
+- `funifier_read_doc path=modules/database`
 
 ## Steps
 

package/skills/funifier/references/create-custom-page.md

@@ -45,21 +45,21 @@ Note que `aggregate` é uma **string** contendo JSON serializado (com `\n` e `\"
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "custom page studio dashboard angularjs bootstrap admin crud kpi" --skill funifier-create-custom-page
+```
+funifier_search_docs "custom page studio dashboard angularjs bootstrap admin crud kpi"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/modules/studio-page.md`
-- `datasource-funifier-docs/knowledge/guides/aggregates.md`
-- `datasource-funifier-docs/knowledge/modules/auth.md`
+- `funifier_read_doc path=modules/studio-page`
+- `funifier_read_doc path=guides/aggregates`
+- `funifier_read_doc path=modules/auth`
 
 ## Steps
 

package/skills/funifier/references/create-folder.md

@@ -6,19 +6,19 @@ Create a Funifier learning trail (folder) — hierarchical courses with content
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "folder trail course learning progress content hierarchy unlock training lms" --skill funifier-create-folder
+```
+funifier_search_docs "folder trail course learning progress content hierarchy unlock training lms"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/modules/folder.md`
+- `funifier_read_doc path=modules/folder`
 
 ## Steps
 

package/skills/funifier/references/create-lastmile.md

@@ -616,7 +616,7 @@ funifier_list type=lastmile search=<descricao>
 ### 3. Ler a documentação do módulo
 
 ```
-datasource-funifier-docs/knowledge/modules/lastmile.md
+funifier_read_doc path=modules/lastmile
 ```
 
 ### 4. Criar o lastmile

package/skills/funifier/references/create-leaderboard.md

@@ -6,21 +6,21 @@ Create a Funifier leaderboard — rankings by points, actions, or attributes
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "leaderboard ranking score top players classification board" --skill funifier-create-leaderboard
+```
+funifier_search_docs "leaderboard ranking score top players classification board"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/modules/leaderboard.md`
-- `datasource-funifier-docs/knowledge/modules/point.md`
-- `datasource-funifier-docs/knowledge/modules/action.md`
+- `funifier_read_doc path=modules/leaderboard`
+- `funifier_read_doc path=modules/point`
+- `funifier_read_doc path=modules/action`
 
 ## Steps
 

package/skills/funifier/references/create-level.md

@@ -6,20 +6,20 @@ Create Funifier levels — progression system based on accumulated points
 
 ## Before starting — find relevant docs
 
-Run lexical search to load only what you need:
+Use the `funifier_search_docs` MCP tool to load only what you need:
 
-```bash
-npx funifier-mcp search "level progression rank tier xp points unlock" --skill funifier-create-level
+```
+funifier_search_docs "level progression rank tier xp points unlock"
 ```
 
-Read only files returned with score > 0.5 (this threshold is printed in the search output).
+Then read the most relevant results with `funifier_read_doc path=<path>`.
 
 ## Primary docs for this skill
 
-If search returns insufficient results, read directly:
+If search returns insufficient results, read these directly:
 
-- `datasource-funifier-docs/knowledge/modules/level.md`
-- `datasource-funifier-docs/knowledge/modules/point.md`
+- `funifier_read_doc path=modules/level`
+- `funifier_read_doc path=modules/point`
 
 ## Steps