funifier-mcp 0.3.21 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,52 @@
 All notable changes to `funifier-mcp` are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [0.4.0]
+
+Setup now runs the MCP via `npx` instead of installing it into your project — eliminates the
+dependency conflicts that `npm install funifier-mcp --save` caused in Node.js apps.
+
+### Changed
+- **`funifier-mcp init` no longer installs the package into the consumer project.** The old flow
+  ran `npm install funifier-mcp@latest --save` (and `npm init -y`), mutating the project's
+  `package.json`, lockfile, and `node_modules` — so the MCP's own deps (`axios`, `zod`,
+  `@modelcontextprotocol/sdk`, `@inquirer/prompts`) collided with the host app's pinned versions.
+  Setup is now zero-install.
+- **Generated MCP configs run the server via `npx`.** All platforms (Claude Code, Cursor,
+  Antigravity, Codex, OpenCode, Kimi) now emit `command: "npx"`, `args: ["-y", "funifier-mcp@latest"]`
+  instead of `command: "node"` + an absolute `node_modules/.../bundle.js` path. npx caches the
+  package in its own store (`~/.npm/_npx`) and never touches the project. Matches the
+  industry-standard stdio MCP distribution pattern (official MCP docs, `@modelcontextprotocol/server-*`).
+- **Dropped the hardcoded `FUNIFIER_DOCS_PATH` from generated configs.** The server auto-resolves
+  its bundled docs from the running package, so the env var is no longer written.
+
+### Migration
+- Re-running `funifier-mcp init` over an existing setup rewrites the configs to the npx form and,
+  when it detects a project-local `funifier-mcp` (in `package.json` or `node_modules`), offers to
+  run `npm uninstall funifier-mcp` to clean up the stale dependency.
+- **Requirement:** Node.js with `npx` on `PATH` (ships with npm). Windows clients that can't find
+  `npx` can use `npx.cmd`; air-gapped setups can point `command`/`args` at a local install (see README).
+
+## [0.3.22]
+
+New MCP tool `funifier_db_explain` and a full-replace warning on `funifier_database` updates.
+
+### Features
+- **New tool `funifier_db_explain`.** Returns the REAL MongoDB query plan (`winningPlan` /
+  `executionStats` — IXSCAN vs COLLSCAN, docs examined vs returned) for an `aggregate` or `find`
+  against a Funifier collection. Since the REST API cannot explain queries, it runs `explain` inside
+  the engine via a TEMPORARY scheduler (create → execute → delete) — nothing is left behind.
+  Inputs validated before touching the API (collection `^[A-Za-z0-9_]+$` injection guard, JSON
+  pipeline/filter); pipeline/filter travel as JSON strings in `extra` so no `$`-key is persisted;
+  cleanup runs in a `finally` block even on error.
+- **`funifier_database` update: full-replace warning.** The tool now warns that a `PUT` update
+  replaces the whole document (no field merge).
+
+### Documentation
+- **Add `guides/explain-diagnostics.md`.** How to obtain the real MongoDB query plan on Funifier via
+  the scheduler escape-hatch, including the daily-execution limit and why the plan is real (not an
+  estimate). Registered in `knowledge/index.md` and cross-linked from `modules/database.md`.
+
 ## [0.3.21]
 
 Documentation of the `com.funifier.engine.util` package as a new knowledge guide and Claude Code skill.

package/README.md

@@ -42,7 +42,7 @@ Once the MCP server is connected, agents discover and read docs through MCP tool
 
 ## MCP Server Setup
 
-The MCP server exposes Funifier as tools in any MCP-compatible AI client. `npx funifier-mcp@latest init` configures it automatically. For manual setup, install the package first (`npm install funifier-mcp`) then configure your client:
+The MCP server exposes Funifier as tools in any MCP-compatible AI client. `npx funifier-mcp@latest init` configures it automatically. The server runs via **`npx`** — it is never installed into your project, so there are no dependency conflicts with your app's `package.json`/lockfile. The only requirement is **Node.js with `npx` on your `PATH`** (npx ships with npm). For manual setup, add the block below to your client config:
 
 ### Claude Code / Cursor / Antigravity (`.mcp.json`)
 
@@ -50,8 +50,8 @@ The MCP server exposes Funifier as tools in any MCP-compatible AI client. `npx f
 {
   "mcpServers": {
     "funifier": {
-      "command": "node",
-      "args": ["/absolute/path/to/node_modules/funifier-mcp/dist/mcp/bundle.js"],
+      "command": "npx",
+      "args": ["-y", "funifier-mcp@latest"],
       "env": {
         "FUNIFIER_API_KEY": "your-api-key",
         "FUNIFIER_SECRET_KEY": "your-secret-key",
@@ -66,8 +66,8 @@ The MCP server exposes Funifier as tools in any MCP-compatible AI client. `npx f
 
 ```toml
 [mcp_servers.funifier]
-command = "node"
-args = ["/absolute/path/to/node_modules/funifier-mcp/dist/mcp/bundle.js"]
+command = "npx"
+args = ["-y", "funifier-mcp@latest"]
 enabled = true
 
 [mcp_servers.funifier.env]
@@ -83,7 +83,7 @@ FUNIFIER_SERVER_URL = "https://your-instance.funifier.com"
   "mcp": {
     "funifier": {
       "type": "local",
-      "command": ["node", "/absolute/path/to/node_modules/funifier-mcp/dist/mcp/bundle.js"],
+      "command": ["npx", "-y", "funifier-mcp@latest"],
       "environment": {
         "FUNIFIER_API_KEY": "your-api-key",
         "FUNIFIER_SECRET_KEY": "your-secret-key",
@@ -94,6 +94,10 @@ FUNIFIER_SERVER_URL = "https://your-instance.funifier.com"
 }
 ```
 
+> **Windows:** if your client can't find `npx`, set `"command": "npx.cmd"` (or wrap it as `"command": "cmd", "args": ["/c", "npx", "-y", "funifier-mcp@latest"]`).
+>
+> **Air-gapped / offline:** npx needs network access on first run to fetch the package. Where that isn't possible, install `funifier-mcp` anywhere you like and point the client at its bin directly — e.g. `"command": "node", "args": ["/path/to/funifier-mcp/dist/mcp/index.js"]`.
+
 ### Runtime connection
 
 If no config is provided at startup, use the `funifier_connect` tool to connect:
@@ -149,12 +153,12 @@ Restore refuses cross-server application when the snapshot's `serverUrl` differs
 
 ## Skills and Instructions
 
-`npx funifier-mcp@latest init` copies the right files for each platform automatically. For manual setup, install first (`npm install funifier-mcp`) then copy:
+`npx funifier-mcp@latest init` copies the right files for each platform automatically (recommended). For manual copying, use `npm install --no-save` so nothing is added to your project's `package.json`/lockfile:
 
 ### Claude Code
 
 ```bash
-npm install funifier-mcp
+npm install --no-save funifier-mcp
 cp -r node_modules/funifier-mcp/skills/* .claude/skills/
 ```
 
@@ -167,7 +171,7 @@ Start with `/funifier` in Claude Code — the router skill routes to the right w
 ### Codex CLI / OpenCode
 
 ```bash
-npm install funifier-mcp
+npm install --no-save funifier-mcp
 cp node_modules/funifier-mcp/AGENTS.md .
 ```
 
@@ -176,7 +180,7 @@ The `AGENTS.md` is the entry point for Codex, OpenCode, and any agent that reads
 ### GitHub Copilot / Continue
 
 ```bash
-npm install funifier-mcp
+npm install --no-save funifier-mcp
 mkdir -p .github
 cp node_modules/funifier-mcp/.github/copilot-instructions.md .github/
 ```
@@ -186,7 +190,7 @@ Copilot and Continue automatically apply `.github/copilot-instructions.md`.
 ### Cursor IDE
 
 ```bash
-npm install funifier-mcp
+npm install --no-save funifier-mcp
 mkdir -p .cursor/rules
 cp node_modules/funifier-mcp/.cursor/rules/funifier.mdc .cursor/rules/
 ```

package/datasource-funifier-docs/.coverage.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-22T15:32:00.000Z",
+  "generatedAt": "2026-07-01T20:31:00.000Z",
   "docsRoot": "datasource-funifier-docs/",
   "docs": {
     "knowledge/guides/aggregates.md": {
@@ -22,6 +22,14 @@
         "funifier-implement-frontend"
       ]
     },
+    "knowledge/guides/explain-diagnostics.md": {
+      "status": "grouped",
+      "skillIds": [
+        "funifier-query-aggregate",
+        "funifier-create-aggregate",
+        "funifier-debug"
+      ]
+    },
     "knowledge/guides/java-entities.md": {
       "status": "covered",
       "skillIds": [
@@ -346,9 +354,9 @@
     }
   },
   "summary": {
-    "total": 53,
+    "total": 54,
     "covered": 33,
-    "grouped": 14,
+    "grouped": 15,
     "deferred": 6,
     "uncovered": 0
   }

package/datasource-funifier-docs/.validation.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-12T17:50:00Z",
+  "generatedAt": "2026-07-01T15:08:00Z",
   "skills": {
     "funifier-audit-permissions": {
       "configHash": "f0569bdb0e11e1a2c6a11f6a4ff9cfd940668c7431bee06342b29faab32510fc",
@@ -69,7 +69,7 @@
       ]
     },
     "funifier-create-aggregate": {
-      "configHash": "c27031c7453134f3386ca29d55ab4d6ad25e20b0aec443d9cf84858f0984415f",
+      "configHash": "8ddc1acdf7a961571399d0885722c0e702c00bca4990157ba500f81889b7ce16",
       "status": "verified",
       "claims": [
         {
@@ -85,7 +85,7 @@
       ]
     },
     "funifier-create-audit": {
-      "configHash": "0ca754be3545a16a6efb50ca2c4b360f1438efa1cd1bc2b5109aa76768376e07",
+      "configHash": "c98ef7a985ad1d7a1c3c325b17aec630d3d99aa67372b640c271d7a1d2faf580",
       "status": "verified",
       "claims": [
         {
@@ -189,7 +189,7 @@
       ]
     },
     "funifier-create-custom-object": {
-      "configHash": "8aa7a96fdc72793c3d095db04831396d58a1aca931a7542cc8d5b8eed2e0c31d",
+      "configHash": "6fb0edb78fecd25705a6e8b7d4c683c65c9673994bf24cf77d062e533d35eb0a",
       "status": "verified",
       "claims": [
         {
@@ -452,7 +452,7 @@
       ]
     },
     "funifier-create-trigger": {
-      "configHash": "21a46732f80324f9662064e8d96528f26c7cfa277f152905fd537be8ef12dab1",
+      "configHash": "511b1e5e8d9211eb5149e40eb2bd700014b04ead15401fb9d2812511d5fe3842",
       "status": "verified",
       "claims": [
         {
@@ -484,6 +484,16 @@
             "symbol": "Class:src/main/java/com/funifier/engine/integration/trigger/TriggerManager.java:TriggerManager",
             "file": "src/main/java/com/funifier/engine/integration/trigger/TriggerManager.java"
           }
+        },
+        {
+          "claim": "TriggerManager.executeStrict rethrows the first collected exception as a FunifierException (HTTP 500), and DatabaseRest.insert/update/delete call it for before_create/before_update/before_delete — so a throw in those before_ events on a database collection aborts the operation. This is version-dependent (not on every instance). Plain execute() swallows exceptions.",
+          "gitnexusQuery": "executeStrict",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Method:src/main/java/com/funifier/engine/integration/trigger/TriggerManager.java:TriggerManager.executeStrict#6",
+            "file": "src/main/java/com/funifier/engine/integration/trigger/TriggerManager.java"
+          }
         }
       ]
     },
@@ -552,12 +562,12 @@
       ]
     },
     "funifier-date-handling": {
-      "configHash": "5a7fd773c2e29a7dacb108bc54262693df7f547cdde225dc95825f1c8dc04651",
+      "configHash": "dfb22a3c66b117006b5fff0e11e8f9293051463a39235fb33cf174ea321f6e20",
       "status": "verified",
       "claims": []
     },
     "funifier-debug": {
-      "configHash": "e64ae75ed8e9d02014c75480f83888904f408ce87de73e9ab71c142d272fa856",
+      "configHash": "c881d7adc2585c1aebbb053677ec219ec4d869441aaf42d4e8dff72eccde6f2f",
       "status": "verified",
       "claims": [
         {
@@ -573,7 +583,7 @@
       ]
     },
     "funifier-help": {
-      "configHash": "25fbe8f89b7cb24e2410477d1c033f6761cd94c777995ae69a21eaf276a4d8ad",
+      "configHash": "e2abfdc80de3bfd4200d93d727675ccf51f76afa60293fd0f38158ffc5b9e9ef",
       "status": "verified",
       "claims": [
         {
@@ -589,7 +599,7 @@
       ]
     },
     "funifier-implement-frontend": {
-      "configHash": "74c5916808501dd0f10572caf22b92dc083da076493422881060d413cc722681",
+      "configHash": "086904fe521764c1e7846ce01babd1b4c77e14f33f31447890d5e4564c856905",
       "status": "verified",
       "claims": [
         {
@@ -620,7 +630,7 @@
       "claims": []
     },
     "funifier-manage-indexes": {
-      "configHash": "bebb7f00e3b8a6eff8276b7264a33dfc6c912a58adc96f3fc8406e8cb1675df3",
+      "configHash": "7ff9fa3b1b6a5725b341f58711c4e8bf8521e39c5a16a4254478448202e56d55",
       "status": "verified",
       "claims": []
     },
@@ -667,10 +677,76 @@
       ]
     },
     "funifier-query-aggregate": {
-      "configHash": "830f98451a47c0e2684aa6d77a218a5f9b3dc4d10ea3281d9a7fcde8c79f7dec",
+      "configHash": "272b0e297357bfdd9a9a79c945eef5ded46aa3029242d1907eb56658d86d3ea6",
       "status": "verified",
       "claims": []
     },
+    "funifier-server-utils": {
+      "configHash": "34d9bfa05517ff3b5d23000d0bb421006c1eb71c176be600df7d6c3cc48bc1d7",
+      "status": "verified",
+      "claims": [
+        {
+          "claim": "CpfUtil.isValid(Object cpf) accepts String (formatted or plain) or Number (Long) and returns false for null; isValidCNPJ is commented out and unavailable",
+          "gitnexusQuery": "CpfUtil",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/engine/util/CpfUtil.java:CpfUtil",
+            "file": "src/main/java/com/funifier/engine/util/CpfUtil.java"
+          }
+        },
+        {
+          "claim": "AesCrypt.encryptFields(Object object, List<String> fields, String secret) accepts dot-notation JSONPath field names and returns the same object type with those fields AES-encrypted as Base64",
+          "gitnexusQuery": "AesCrypt",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/engine/util/AesCrypt.java:AesCrypt",
+            "file": "src/main/java/com/funifier/engine/util/AesCrypt.java"
+          }
+        },
+        {
+          "claim": "OtpAuthUtil.createQRCode is the only active public method; generateSecretKey, getTOTPCode, validateTOTPCode, and getGoogleAuthenticatorBarCode are commented out in the current source",
+          "gitnexusQuery": "OtpAuthUtil",
+          "critical": true,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/engine/util/OtpAuthUtil.java:OtpAuthUtil",
+            "file": "src/main/java/com/funifier/engine/util/OtpAuthUtil.java"
+          }
+        },
+        {
+          "claim": "JsonUtil.fromJsonToMap(String json) returns Map<String, Object> parsed via DBObject.toMap(); JsonUtil.toJson produces indented JSON with nulls included",
+          "gitnexusQuery": "JsonUtil",
+          "critical": false,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/engine/util/JsonUtil.java:JsonUtil",
+            "file": "src/main/java/com/funifier/engine/util/JsonUtil.java"
+          }
+        },
+        {
+          "claim": "DiffUtil.buildChangelogFromSequence(List<?> data, String sortBy, Config config) produces a List where each entry is the new version's fields plus a 'changes' key with diffAsMap output",
+          "gitnexusQuery": "DiffUtil",
+          "critical": false,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/engine/util/DiffUtil.java:DiffUtil",
+            "file": "src/main/java/com/funifier/engine/util/DiffUtil.java"
+          }
+        },
+        {
+          "claim": "ExcelUtil.generateExcelFromObjects(List<Map<String, Object>> listRows, String sheetName) returns byte[] XLSX; column headers come from the key set of the first Map",
+          "gitnexusQuery": "ExcelUtil",
+          "critical": false,
+          "status": "verified",
+          "evidence": {
+            "symbol": "Class:src/main/java/com/funifier/engine/util/ExcelUtil.java:ExcelUtil",
+            "file": "src/main/java/com/funifier/engine/util/ExcelUtil.java"
+          }
+        }
+      ]
+    },
     "funifier-upload-file": {
       "configHash": "9c3dcaf7351189c3395ae3ea5ac122d5b470b3e1db0b0fd94384880c0094f19c",
       "status": "verified",

package/datasource-funifier-docs/knowledge/guides/database-access.md

@@ -44,6 +44,8 @@ Este documento descreve as duas formas de acessar o MongoDB da Funifier — via
 
 > ⚠️ **Use `strict=true` em todo GET/escrita de campos tipados.** Consequência de omitir: `Date` é lido como número e regravado com tipo errado, quebrando queries por data (`patterns.md` §9).
 
+> ⚠️ **`DELETE` de muitos registros tem duas armadilhas.** `> 20.000` docs = **no-op silencioso** (200, nada apaga); milhares `≤ 20.000` = **timeout** (síncrono: 3 varreduras + materializa todos os ids). → Apague em **lotes de 1.000 sobre campo indexado** (`modules/database.md` §2.4/§10.5).
+
 ### 1.6 Documentos relacionados
 
 > 📄 `datasource-funifier-docs/knowledge/guides/aggregates.md` — pipelines de aggregate e expressões de data
@@ -103,6 +105,7 @@ POST /v3/database/:collection/aggregate
 - **`_filter`/`_sort`/`_limit`** → ignorados (§1.5). Correção: `q` + aggregate `$sort`.
 - **`PUT` parcial** → replace apaga campos (§1.5). Correção: objeto completo.
 - **`POST` esperando busca** → cria documento (§1.5). Correção: `GET ?q=`.
+- **`DELETE` com filtro amplo** → duas armadilhas: `> 20.000` docs = **no-op silencioso** (200, nada apaga); milhares `≤ 20.000` = **timeout** (operação síncrona, 3 varreduras + materializa todos os ids num único request). Correção: apague em **lotes de 1.000 sobre campo indexado** (`modules/database.md` §2.4/§10.5).
 
 ---
 

package/datasource-funifier-docs/knowledge/guides/explain-diagnostics.md

@@ -0,0 +1,170 @@
+# Diagnóstico de Queries — `explain()` do MongoDB via Scheduler
+
+## 1. Visão Geral
+
+### 1.1 O que é este documento
+
+Descreve como obter o **plano de consulta real** do MongoDB (`explain`) na Funifier — `winningPlan`,
+`IXSCAN` vs `COLLSCAN`, `totalDocsExamined` — mesmo sem endpoint nativo de explain. A técnica roda o
+comando `explain` **dentro do engine**, num script server-side (scheduler), e devolve o plano de forma
+síncrona. É a única forma de ver o plano real de uma query específica sem alterar o `funifier-service`.
+
+### 1.2 Quando consultar
+
+- Ao **diagnosticar uma query lenta** (aggregate ou find) e precisar saber se ela usa índice.
+- Ao investigar **timeout de `DELETE`** ou varreduras caras — confirmar `COLLSCAN` vs `IXSCAN`.
+- Ao **validar um índice recém-criado** — provar que a query passou a usá-lo.
+- Antes de otimizar: medir `totalDocsExamined` vs `nReturned` (quanto maior a razão, pior).
+
+### 1.3 Quando NÃO consultar
+
+- **NÃO** consulte para montar pipelines (`$match`/`$group`/`$sort`) nem expressões de data — use
+  `guides/aggregates.md`.
+- **NÃO** consulte para criar/listar índices — use `guides/database-access.md` §5 e o endpoint
+  `/v3/database/:collection/index`.
+- **NÃO** use isto quando só precisa de **estatística de índices/coleção** (uso por índice, tamanho):
+  aí basta `$indexStats`/`$collStats` como primeiro estágio de um aggregate normal (§5), sem scheduler.
+
+### 1.4 Índice de decisão
+
+| Problema / Situação | O que fazer | Seção |
+|---|---|---|
+| Ver o plano real de um aggregate | `explain` do `aggregate` via scheduler | §2, §3 |
+| Ver o plano real de um find/delete | `explain` do `find` com o mesmo `filter` | §3 |
+| Saber se bate no índice | Ler `winningPlan.stage` (`IXSCAN`/`COLLSCAN`) | §4 |
+| Medir custo real (docs examinados) | `verbosity: "executionStats"` | §3, §4 |
+| Só uso/tamanho de índices | `$indexStats` / `$collStats` (sem scheduler) | §5 |
+
+### 1.5 Restrições globais críticas
+
+> ⚠️ **`explain: true` é uma flag de comando (`runCommand`), não um estágio de pipeline.** Consequência:
+> **não** dá para obtê-lo pelo endpoint `/v3/database/{collection}/aggregate` (que só *executa* a query).
+> → Rode `explain` num script server-side com `manager.getJongoConnection().runCommand(...)`.
+
+> ⚠️ **Cada execução consome uma execução diária de scheduler** (há limite por gamificação). Consequência:
+> diagnósticos em massa podem esgotar a cota. → Use pontualmente; não coloque em loop.
+
+> ⚠️ **Nunca persista o pipeline/filtro como sub-documento com chaves `$`.** O MongoDB rejeita chaves
+> iniciadas por `$` em documentos gravados. → Guarde o pipeline como **string JSON** em `scheduler.extra`
+> e concatene o comando no script (§3), ou embuta o JSON direto no script.
+
+> ⚠️ **O sandbox de scripts (`TriggerExpressionChecker`) bloqueia `.execute`, `.getDB`, `.getMongo`,
+> `.dropDatabase`.** Consequência: `jongo.getDatabase().command(...)` casa com `.getDB`? Não — mas evite
+> caminhos bloqueados. → Use `jongo.runCommand(...)` (permitido) — é o caminho canónico e testado.
+
+### 1.6 Documentos relacionados
+
+- `guides/database-access.md` — mecânica de acesso (Jongo, `manager.getJongoConnection()`, índices).
+- `guides/aggregates.md` — montagem de pipelines e expressões de data.
+- `guides/java-libraries.md` — `JsonUtil`, Jongo.
+- `modules/scheduler.md` — recurso Scheduler e execução via `/v3/scheduler/execute/{id}`.
+
+---
+
+## 2. Como funciona (mecânica)
+
+1. **Criar** um scheduler temporário (`POST /v3/scheduler`) com `active:false` (não agenda job Quartz)
+   e um `cron` Quartz válido (o compilador valida a expressão).
+2. **Executar** de forma síncrona: `GET /v3/scheduler/execute/{id}` → roda o script na hora e devolve
+   `{ scheduler, outputs, exceptions, millis }`. O que o script `println`-a cai em **`outputs`**.
+3. **Apagar** o scheduler (`DELETE /v3/scheduler/{id}`) — sempre, mesmo em erro.
+
+O script tem acesso ao driver Mongo nativo via `manager.getJongoConnection()`, então executa o
+comando `explain` de verdade — o mesmo que `db.runCommand({ explain: ... })` no shell.
+
+> O id enviado no campo `_id` é honrado pelo servidor (`SchedulerConfig.id` é `@JsonProperty("_id")`),
+> então o mesmo id serve para `execute` e `delete`.
+
+---
+
+## 3. O script (Groovy)
+
+Sandbox-legal (só `runCommand`, acesso a propriedade e concatenação de string). Os dados chegam como
+**strings JSON** em `scheduler.extra` para nunca persistir chaves `$`:
+
+```groovy
+void execute(scheduler){
+    def x = scheduler.extra
+    def jongo = manager.getJongoConnection()
+    def cmd
+    if (x.operation == 'find') {
+        cmd = '{ explain: { find: "' + x.collection + '", filter: ' + x.filterJson + ' }, verbosity: "' + x.verbosity + '" }'
+    } else {
+        cmd = '{ explain: { aggregate: "' + x.collection + '", pipeline: ' + x.pipelineJson + ', cursor: {} }, verbosity: "' + x.verbosity + '" }'
+    }
+    def plan = jongo.runCommand(cmd).as(java.util.Map.class)
+    println JsonUtil.toJson(plan)
+}
+```
+
+`extra` de exemplo (aggregate):
+
+```json
+{
+  "operation": "aggregate",
+  "collection": "action_log",
+  "verbosity": "executionStats",
+  "pipelineJson": "[{\"$match\":{\"time\":{\"$gt\":0}}}]"
+}
+```
+
+Formas do comando `explain` (MongoDB 5.0):
+
+- **aggregate:** `{ explain: { aggregate: "<col>", pipeline: [...], cursor: {} }, verbosity: "<v>" }`
+- **find:** `{ explain: { find: "<col>", filter: {...} }, verbosity: "<v>" }`
+
+`verbosity`: `queryPlanner` (só escolhe o plano, não executa) · `executionStats` (executa e mede docs
+examinados — melhor para diagnóstico) · `allPlansExecution` (inclui planos rejeitados).
+
+> Valide `collection` com `^[A-Za-z0-9_]+$` antes de concatenar — evita quebrar o JSON do comando.
+
+---
+
+## 4. Interpretando o resultado
+
+Resposta real (find sem filtro em `player`, `executionStats`, MongoDB 5.0.29):
+
+```json
+{
+  "queryPlanner": { "winningPlan": { "stage": "COLLSCAN", "direction": "forward" }, "rejectedPlans": [] },
+  "executionStats": {
+    "nReturned": 55,
+    "executionTimeMillis": 1,
+    "totalKeysExamined": 0,
+    "totalDocsExamined": 55,
+    "executionStages": { "stage": "COLLSCAN", "docsExamined": 55 }
+  },
+  "ok": 1
+}
+```
+
+Sinais a observar:
+
+| Campo | O que significa |
+|---|---|
+| `winningPlan.stage = COLLSCAN` | ⚠️ Varredura completa — **nenhum índice** foi usado. Candidato a criar índice. |
+| `winningPlan.stage = IXSCAN` (com `indexName`) | ✅ Usou índice. |
+| `totalDocsExamined` >> `nReturned` | ⚠️ Examinou muito mais do que devolveu — filtro sem índice ou índice ruim. |
+| `totalKeysExamined = 0` | Não tocou em nenhum índice (confirma `COLLSCAN`). |
+| `rejectedPlans` não vazio | Havia índices alternativos; útil ver por que perderam. |
+
+Para o problema clássico de **timeout de `DELETE` sobre campo indexado**: explique um `find` com o
+**mesmo `filter` do delete**. Se der `COLLSCAN`, o delete varre a coleção inteira → crie o índice e
+apague em lotes (`guides/database-access.md`, `modules/database.md`).
+
+---
+
+## 5. Alternativa sem scheduler (só estatística de índices)
+
+Se você **não** precisa do plano de uma query específica, mas só de diagnóstico de índices/coleção,
+use estágios de agregação que passam pelo endpoint normal (`POST /v3/database/{collection}/aggregate`),
+como **primeiro** estágio — sem scheduler:
+
+| Objetivo | Primeiro estágio |
+|---|---|
+| Uso/acesso por índice (índice morto?) | `[{ "$indexStats": {} }]` |
+| Tamanho da coleção, contagem, tamanho dos índices | `[{ "$collStats": { "storageStats": {} } }]` |
+| Planos em cache | `[{ "$planCacheStats": {} }]` |
+
+Limitação: isto mostra **quais índices existem e o uso deles**, mas **não** o `winningPlan` de uma
+query concreta — para isso, use o `explain` via scheduler (§2–§4).

package/datasource-funifier-docs/knowledge/index.md

@@ -103,6 +103,7 @@ A Funifier funciona como um **backend de aplicações**. Independentemente do ti
 | Triggers | `guides/triggers-guide.md` | Guia completo de triggers | Referência de eventos, entidades, managers e exemplos de código Java |
 | Trigger Examples | `guides/trigger-examples.md` | Exemplos de produção de triggers | Código Groovy pronto para padrões reais: atualizar coleção relacionada, criar achievement, inicializar jogador, normalizar/rejeitar `__c`, processar lote, registrar ação via `track` |
 | Database Access | `guides/database-access.md` | Acesso ao banco de dados | Referência de acesso via API REST e via código Java (Jongo) |
+| Explain / Diagnóstico | `guides/explain-diagnostics.md` | Plano de consulta real (`explain`) do MongoDB | Diagnosticar query lenta / timeout de `DELETE`: obter `winningPlan`, `IXSCAN` vs `COLLSCAN`, `totalDocsExamined` via scheduler (`runCommand explain`), já que o endpoint REST só executa a query. Inclui alternativa `$indexStats`/`$collStats` sem scheduler |
 | Java Managers | `guides/java-managers.md` | Referência de managers Java | Métodos disponíveis em cada manager (PlayerManager, ActionManager, etc.) para uso em triggers, schedulers e public endpoints |
 | Java Entities | `guides/java-entities.md` | Referência de entidades Java | Campos e tipos dos objetos (Player, Achievement, ActionLog, etc.) e mapeamento para coleções MongoDB |
 | Java Libraries | `guides/java-libraries.md` | Bibliotecas e utilitários Java | JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo — métodos e exemplos de uso |
@@ -124,4 +125,6 @@ Para **relatórios e queries avançadas**, consulte `guides/aggregates.md` — d
 
 Para **lógica customizada com código**, consulte `guides/triggers-guide.md` (conceitos e referência de eventos) e `guides/trigger-examples.md` (exemplos Groovy prontos), além de `guides/database-access.md`.
 
+Para **diagnosticar queries lentas ou timeout de `DELETE`** (ver se bate no índice), consulte `guides/explain-diagnostics.md` — obtém o plano real (`explain`) do MongoDB via scheduler, já que o endpoint REST só executa a query.
+
 Para **referência completa de recursos Java** (managers, entidades, bibliotecas), consulte `guides/java-managers.md`, `guides/java-entities.md` e `guides/java-libraries.md`.

package/datasource-funifier-docs/knowledge/modules/custom-object.md

@@ -137,6 +137,8 @@ flowchart TD
 
 > **Armadilha crítica (confirmada no código):** se `q` casa com **mais de 20.000** documentos, o delete **não executa** e retorna **200 OK** sem erro. O comentário no código diz "menor que 1000" (`DatabaseRest.java:466`), mas a constante real é `20_000` (`:469`) — o comentário está **desatualizado**.
 
+> **Segunda armadilha — TIMEOUT (independente do no-op):** mesmo **abaixo** de 20.000, o delete é **síncrono num único request HTTP** e faz **3 varreduras** na coleção (`count` → `distinct(_id)` materializando **todos** os ids em memória → `remove`). Casar **milhares** de docs (ex.: ~10.000) sobre campo **não indexado** estoura o **timeout do request**. → Apague em **lotes de 1.000 por chamada, sobre campo indexado** (o número 1.000 é a intenção original do comentário do código); particione o `q` (o DELETE não aceita `$limit`) e repita até zerar. Se houver delete-trigger/audit na coleção, o lote seguro cai abaixo de 1.000. Ver §5.6 e §10.
+
 #### Fluxograma — delete
 
 ```mermaid
@@ -507,8 +509,8 @@ Operam sobre o **banco de sistema** (`SystemFactory.getInstance()`), não o do t
 ### 5.5 Convenção `__c`
 Não é validada no CRUD. Única exigência: `out` do `aggregate` deve terminar em `__c`. O framework usa internamente `csv_config__c`, `csv_log__c`, `csv_format__c`, `find_cache_<id>__c`, `email_code_verifier_log__c`.
 
-### 5.6 Limite de delete (20.000)
-Filtro que casa > 20.000 docs → no-op silencioso com 200. (Comentário do código diz "1000", mas o valor real é 20.000.)
+### 5.6 Limite de delete (20.000) e timeout
+**Duas armadilhas independentes** (ver §2.4): filtro que casa **> 20.000** docs → **no-op silencioso** com 200 (comentário do código diz "1000", mas o valor real é 20.000); filtro que casa **milhares ≤ 20.000** → **timeout** (operação síncrona: 3 varreduras + materializa todos os ids num único request). Mitigação: apague em **lotes de 1.000 sobre campo indexado** (§10).
 
 ### 5.7 Assimetria de encriptação — risco silencioso
 Encriptação na escrita só ocorre se `checkReadEncryptedValues()` for verdadeiro. Esse método retorna `true` por **dois caminhos** (`AuthBean.java:221-226`): scope `read_encrypted_field_values` **ou** permissão de sistema `api/encrypted_field_values/read`. Se **nenhum** estiver presente, o dado é salvo em **plaintext** na coleção configurada, **sem aviso**. Resultado: a mesma coleção pode acumular documentos encriptados e em plaintext, dependendo de qual token escreveu. Além disso, falhas internas de `AesCrypt.encryptFields` (ex.: JSONPath inválido) são **engolidas** (`printStackTrace`) → o campo permanece plaintext silenciosamente.
@@ -562,6 +564,7 @@ Toda operação resolve `FrontController.getInstance(authBean.getApiKey()).getMa
 - **PATCH parcial:** PUT é sempre replace via `save()`.
 - **`PUT /{collection}/operations`:** **código morto** comentado em `DatabaseRest.java:393-447` (operações `$inc`/`$set`/`upsert`/`multi`). Implementado, porém **nunca exposto**.
 - **Delete > 20.000 docs:** no-op silencioso (200).
+- **Delete de milhares de docs (≤ 20.000):** timeout HTTP — síncrono, 3 varreduras + materializa todos os ids num único request. Apague em lotes de 1.000 sobre campo indexado (§5.6, §10).
 - **Auditoria no bulk:** inexistente.
 - **Encriptação no bulk e no aggregate:** inexistente (campos não são encriptados/decriptados nesses caminhos).
 - **`aggregate_test` não oculta `password`** da coleção `player` (diferente de `/aggregate`).
@@ -625,6 +628,7 @@ GET /v3/database/cars__c/index                      # índices da coleção
 |---|---|---|
 | Resposta vazia com 200/201 | Token sem scope `database` ou nome de coleção curto demais | Conferir `scope` e o limiar de chars do endpoint (§5.1) |
 | DELETE retorna 200 mas nada some | Filtro casa > 20.000 docs | `GET /count?q=...` antes; paginar o filtro |
+| DELETE dá timeout / 504 / conexão cai | Filtro casa milhares de docs (≤ 20.000): síncrono, 3 varreduras + materializa ids | Apague em lotes de 1.000 sobre campo indexado (§5.6, §10); se houver delete-trigger/audit, lotes menores |
 | PUT criou doc novo em vez de atualizar | `_id` ausente no body | Incluir `_id` |
 | Campo volta como string ilegível | Token de leitura sem capacidade de cripto → ciphertext retornado | Usar token com `read_encrypted_field_values` |
 | Coleção com mix encriptado/plaintext | Algum writer escreveu sem capacidade de cripto | Garantir capacidade em **todos** os writers (§5.7) |
@@ -687,15 +691,16 @@ PUT /v3/database/products__c
 ```
 **Resultado:** cria documento NOVO (`_id` gerado). O original não é atualizado. **Sempre** envie `_id` no PUT — e lembre que campos omitidos serão removidos (replace, não patch).
 
-### 10.5 Anti-pattern — DELETE em volume sem checar count
+### 10.5 Anti-pattern — DELETE em volume sem fatiar
 ```
 DELETE /v3/database/logs__c?q=year:2022
 ```
-Se houver > 20.000 docs de 2022, retorna **200 sem deletar nada**. Cheque antes:
+**Duas armadilhas** (ver §2.4): se houver **> 20.000** docs de 2022, retorna **200 sem deletar nada** (no-op); se houver **milhares ≤ 20.000**, **dá timeout** (síncrono: 3 varreduras + materializa todos os ids num único request). Cheque antes e **fatie em lotes de ≤ 1.000 sobre campo indexado**:
 ```
-GET /v3/database/count?collection=logs__c&q=year:2022
+GET /v3/database/count?collection=logs__c&q=year:2022,month:1   # confirme ≤ 1.000
+DELETE /v3/database/logs__c?q=year:2022,month:1                 # repita por mês/dia até zerar
 ```
-Se > 20.000, fatie o filtro (ex.: `year:2022,month:{$lte:6}`) ou use `/drop` (com cautela — sem scope).
+O DELETE REST **não aceita `$limit`** — "lote" = montar `q` que case ≤ 1.000 por chamada (janelas de data, prefixos de `_id`) e repetir. O número 1.000 vem do comentário original do código. Filtre sempre por **campo indexado** (senão as 3 varreduras continuam O(coleção)). Se a coleção inteira pode ir embora → `/drop` (cautela: sem scope). Para volume massivo sem o timeout do REST, mova a deleção para **trigger/scheduler/public endpoint** (`remove` em laço server-side).
 
 ### 10.6 Anti-pattern — confiar em encriptação sem a capacidade
 Escrever em coleção com `crypt_object_field` configurado usando token **sem** `read_encrypted_field_values` (nem permissão de sistema) salva os campos em **plaintext silenciosamente**. Garanta a capacidade em todos os writers.
@@ -708,7 +713,7 @@ Escrever em coleção com `crypt_object_field` configurado usando token **sem**
 - [ ] Nome da coleção respeita o limiar de chars do endpoint usado (§5.1): `> 3` para POST/PUT/bulk/aggregate_test, `> 2` para aggregate, `> 0` para GET-list/delete/count/index.
 - [ ] `_id` incluído no PUT para atualizar (e ciência de que PUT é replace completo).
 - [ ] Sufixo `__c` no destino `out` do aggregate.
-- [ ] `GET /count` executado antes de DELETE para garantir filtro com ≤ 20.000 docs.
+- [ ] `GET /count` executado antes de DELETE: filtro casa **≤ 20.000** (acima = no-op) **e cada chamada ≤ 1.000 sobre campo indexado** (acima = risco de timeout — fatie em lotes; §10.5).
 - [ ] Triggers cadastradas com `entity: '<colecao>'` se há comportamento automático esperado — e ciência de que **exceção no script não aborta** a operação.
 - [ ] `Audit` **ativo** em `{entity, event, type}` se auditoria for necessária (e token com user/player; bulk não audita).
 - [ ] Índices criados (`POST /{collection}/index`) para campos de filtro frequente.